Zum Hauptinhalt springen

Auto-Commit Background Agents: Draft-PR-Übergabe

Experte

Am 1. Juli 2026 lieferte Claude Code v2.1.198 aus und schloss leise den letzten manuellen Schritt in der Agent-Schleife: Background-Agenten, die aus claude agents gestartet wurden, begannen automatisch zu committen, automatisch zu pushen und automatisch einen Draft-PR zu öffnen, wenn sie Code-Arbeit in einem Worktree beendeten. Du gingst von "hier ist eine Aufgabe" direkt zu "hier ist ein prüfbarer Entwurf" — keine Tastenanschläge dazwischen.

Die Reaktion war sofort und gespalten. Manche Nutzer liebten es; andere reichten am nächsten Tag anthropics/claude-code#73197 ein und baten um einen Aus-Schalter, damit ihre propose-only-Workflows (Agent schlägt vor, Mensch committet) weiter funktionieren. Fünf Wochen später, am 4. August 2026, ging v2.1.221 mit dem Standard zurück: Background-Sitzungen committen und pushen jetzt immer, um Arbeit zu erhalten, öffnen aber nur einen Draft-PR, wenn die Aufgabe es erfordert. Gleiches Primitive, weicherer Standard.

Wenn du Agenten unbeaufsichtigt laufen lässt — nächtliches Triage, ein /loop auf /code-review, eine Flotte von /fork-Sitzungen — ist dies der Workflow, in dem du bereits steckst. Hier ist, was er von Anfang bis Ende tut, was wann feuert und wie du ihn für die Vertrauensschwelle deines Teams formst.

What you'll learn
  • Der exakte End-to-End-Flow vom `claude agents`-Start bis zum Draft-PR — Commit, Push, Notification, alles
  • Was v2.1.198 ausgeliefert hat, was v2.1.221 justiert hat und warum der Standard weicher wurde
  • Wie `/fork`, `/resume`, `/background` und (neu in v2.1.221) `/subtask` um den Auto-PR-Flow passen
  • Die Notification-Hook-Payload — `agent_needs_input` vs `agent_completed` — und wie du dich selbst statt Claude piepst
  • Ein propose-only-Muster, das jedes Release überlebt, indem es Permissions statt Settings als Durchsetzungspunkt nutzt

Die vier Auslieferungs-Ereignisse, in Reihenfolge​

Der Auto-PR-Flow kam nicht vollständig geformt an — er landete über fünf Releases in sechs Wochen. Sie in Reihenfolge zu lesen, sagt dir, wofür jede Schicht des aktuellen Verhaltens eigentlich gedacht ist.

DatumVersionÄnderung
2026-07-01v2.1.198Subagenten laufen standardmäßig im Hintergrund. Background-Agenten, die aus claude agents gestartet werden, committen automatisch, pushen automatisch und öffnen automatisch einen Draft-PR beim Abschluss. Notification-Hook feuert agent_needs_input und agent_completed für Background-Sitzungen.
2026-07-15 (ca.)v2.1.212/fork kopiert deine Konversation in eine neue Background-Sitzung (eigene Zeile in claude agents), während du weiterarbeitest. /resume öffnet einen Picker vergangener Sitzungen, einschließlich gelöschter.
2026-07-20 (ca.)v2.1.216Fix: Fortgesetzte Background-Sitzungen stellen den Prompt und die Tool-Einschränkungen des Agenten wieder her, statt auf den Default-Agenten zurückzufallen.
2026-07-22 (ca.)v2.1.218/code-review läuft standardmäßig als Background-Subagent — Review füllt die Konversation nicht mehr.
2026-08-04v2.1.221Standard justiert: Background-Sitzungen committen und pushen immer, um Arbeit zu erhalten, öffnen aber nur einen Draft-PR, wenn die Aufgabe es erfordert. Der In-Session-Subagent, den /fork früher startete, ist jetzt /subtask.

Zwei Dinge, die an diesem Bogen bemerkenswert sind:

  1. Jeder Schritt ist mehr Autonomie, nicht weniger. v2.1.221 hat Auto-Commit oder Auto-Push nicht deaktiviert — es hat nur den Draft-PR pro-Aufgabe-optional gemacht statt immer-an. Die Runtime möchte deine Arbeit immer noch aus einem ephemeren Worktree und auf einen Branch bekommen, bevor sie ihn vergisst.
  2. /fork und der Auto-PR-Flow komponieren. Sobald ein Fork seine eigene Zeile in claude agents ist, ist er eine Background-Sitzung — was bedeutet, dass beim Beenden dieselbe Commit → Push → Vielleicht-PR-Sequenz feuert. Ein einziger /fork, mittags gestartet, kann bis nachmittags als Branch auf origin zurückkommen.

Was tatsächlich passiert, wenn ein Background-Agent fertig ist​

Die End-to-End-Sequenz für eine claude agents-Background-Sitzung auf v2.1.221, sobald ihr letzter Tool-Call zurückkehrt:

Guided walkthrough1 of 6
  1. Die Runtime hält den isolierten Worktree (Standardort unter `~/.claude/worktrees/`) am Leben, solange das Working Tree dirty ist. Wenn der Agent null Änderungen gemacht hat, wird der Worktree automatisch beschnitten — keine Geister-Branches.

Die Sequenz rollt nie zurück. Wenn der Push scheitert (Auth, geschützter Branch), behält die Runtime den lokalen Commit und meldet den Fehler über dieselbe Notification — sie wird deine Arbeit aber nicht löschen.

Der Notification-Hook — piepse dich selbst, nicht Claude​

Die beiden Events, die v2.1.198 zum Notification-Hook hinzufügte, sind die Naht, an der du Menschen in der Schleife hältst, ohne je an der Sitzung teilzunehmen.

Zwei Payload-Formen am selben Hook

# agent_needs_input — session paused waiting for approval or clarification
{ "event": "agent_needs_input", "session_id": "...", "agent": "code-review", "reason": "..." }

# agent_completed — session finished; branch pushed, PR maybe opened
{ "event": "agent_completed", "session_id": "...", "agent": "feature-x",
"branch": "claude/feature-x-2026-08-04", "pr_url": "https://github.com/..." /* or null */ }

Das pr_url-Feld ist das einzelne nützlichste Bit: Es ist null, wenn die Runtime gepusht-aber-nicht-PR (der v2.1.221-Standard für exploratorische Arbeit) hat, und gefüllt, wenn sie es getan hat. Auf diesem Feld zu routen ist, wie du "nur für prüfbare Arbeit anpiepsen" ohne eine zweite Config-Schicht baust.

Ein minimaler Hook, der einen Slack-Kanal nur für Abschlüsse pingt, die einen PR produziert haben:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "agent_completed",
        "hooks": [
          { "type": "command", "command": "jq -e '.pr_url' >/dev/null && jq -r '\"<\" + .pr_url + \"|Draft PR ready> — \" + .agent' | curl -X POST -H 'content-type: application/json' -d @- $SLACK_WEBHOOK_URL" }
        ]
      }
    ]
  }
}

Das jq -e '.pr_url'-Gate ist der ganze Trick: -e beendet ungleich Null, wenn das Feld fehlt oder null ist, und kurzschließt den Rest der Pipeline. Sitzungen, die nur commiteten-und-pushten, piepsen nicht. Sitzungen, die einen PR öffneten, tun es.

Warum #73197 wichtig war — und warum der Fix keine Settings-Taste war​

Issue anthropics/claude-code#73197, eingereicht am 2. Juli 2026 — einen Tag nach v2.1.198 — bat um ein backgroundAgents.autoCreatePr: false in settings.json oder zumindest getrennte Regler für Commit / Push / PR. Die Begründung war vernünftig: In einem "propose-only"-Workflow ist der Mensch der Einzige, der auf origin pushen oder PRs öffnen darf, und ein Standard-an-Publish-Schritt braucht einen Aus-Schalter.

Anthropics Antwort war anders in der Form. Statt einer neuen Einstellung justierte v2.1.221 den Standard selbst (PR nur wenn die Aufgabe es erfordert) und verwies auf das bestehende Permission-System: Eine Bash(git push:*)-Deny-Regel blockiert den Push, und eine Bash(gh pr create:*)-Deny-Regel blockiert den PR. Die Permission-Schicht ist sowohl für interaktive als auch Background-Sitzungen autoritativ — so setzt die Runtime das Verbot durch, unabhängig davon, was der Agent am Ende entscheidet zu tun.

Watch out
  • Es gibt immer noch keinen `backgroundAgents.autoCreatePr`-Schlüssel in `settings.json` — 'das Feature deaktivieren' wird mit Permissions geschrieben, nicht Settings.
  • Ein Permission-Deny auf `Bash(git push:*)` blockiert auch den finalen Auto-Push, nicht nur interaktive Pushes. Wenn deine einzige Sorge der PR ist, deny `Bash(gh pr create:*)` stattdessen und lass den Push durch, damit `/resume` den Branch sauber aufgreifen kann.
  • v2.1.221 ist der Standard *heute*. Wenn du ein älteres Claude Code pinnst (2.1.198 – 2.1.220), bekommst du das Immer-PR-Verhalten — und das Permission-Gate ist deine einzige echte Verteidigung.

Das propose-only-Muster, das jedes Release überlebt​

Baue die Policy in der Permission-Schicht, nicht der Settings-Schicht. Dann gilt sie für jede Sitzung (Foreground, Background, /fork, /subtask, /loop) und kümmert sich nicht darum, welche Version von v2.1.x du hast.

settings.json — propose-only Projekt-Policy

{
"permissions": {
  "deny": [
    "Bash(git push:*)",
    "Bash(gh pr create:*)",
    "Bash(gh pr edit:*)"
  ],
  "allow": [
    "Bash(git commit:*)",
    "Bash(git add:*)"
  ]
}
}

Unter dieser Policy:

  • Der Background-Agent committet immer noch in seinem Worktree — dein Review hat den Diff genau so, wie ihn der Agent produziert hat.
  • Der Push am Session-Ende scheitert. Die Runtime meldet den Fehler über agent_completed mit pr_url: null.
  • Nichts erreicht origin, bis du den Branch selbst aus dem Worktree-Pfad pushst, den dir die Notification übergeben hat.

Das ist das Muster, um das die Community in #73197 gebeten hat, ausgedrückt in Tools, die bereits existieren. Es passiert auch, die Form zu sein, auf die der v2.1.221-Standard konvergiert — die Runtime akzeptiert dich einfach als Quelle der Autorität darüber, welche Agenten veröffentlichen dürfen.

/fork, /subtask, /resume — wo sie hinpassen​

v2.1.212 und v2.1.221 haben umgemischt, was diese drei Kommandos rund um den Auto-PR-Flow tun. Lies sie zusammen:

KommandoWas es startetLäuft woAuto-PR-Flow gilt?
/backgroundNeue Background-SitzungEigene Zeile in claude agentsJa
/fork (v2.1.212+)Kopie der aktuellen Konversation in eine neue Background-SitzungEigene Zeile in claude agentsJa
/subtask (v2.1.221+, war /fork in-session)Ephemerer Subagent innerhalb der aktuellen SitzungIn-ConversationNein — das Parent besitzt das Ergebnis
/resumeWieder anhängen an jede frühere Sitzung in claude agentsWo auch immer sie warWas auch immer die Config dieser Sitzung war
/code-review (v2.1.218+)Review als Background-SubagentEigene ZeileJa — aber Reviews produzieren selten PRs, also pusht v2.1.221 üblicherweise ohne PR

Die Umbenennung in v2.1.221 (/fork → /subtask für den In-Session-Fall) ist die wichtige Aufräumarbeit: /fork bedeutet jetzt "übergib diese Konversation an einen neuen Background-Worker und geh mir aus dem Weg", was die Form ist, um die der Auto-PR-Flow entworfen wurde. /subtask ist, was du verwendest, wenn du einen gescopeten Helfer in deiner bestehenden Sitzung willst und nicht willst, dass die Beende-und-Veröffentliche-Sequenz feuert.

Kosten, Race-Conditions und die zwei Gotchas, die niemand dokumentiert​

Drei reale Details, die nicht in Release-Notes auftauchen:

  • Background-Agenten zählen gegen das Concurrency-Cap. Seit v2.1.198 sind Subagenten standardmäßig Background — was bedeutet, dass eine claude agents-Liste von 25 laufenden Sitzungen anfängt, neue Spawns mit Concurrent subagent limit reached abzulehnen. Siehe Subagent Fleet Limits für die vier Env-Vars.
  • Der Auto-Commit ist nicht amend-sicher. Wenn zwei /forks von derselben Konversation beide fertig werden und beide auf ihre eigenen Branches pushen, bekommst du zwei Branches, zwei Commits und (auf v2.1.198 – v2.1.220) zwei PRs. Fein, wenn du es als Race gemeint hast; nicht fein, wenn du dachtest, nur einer würde gewinnen. Setze einen Plan-Schritt in deinen Agent-Prompt, wenn du Serialisierung brauchst.
  • Ein Watcher, der auto-committet, kann doppelt committen. Wenn du auch einen Repo-Watcher laufen lässt (ein häufiges Skript, das Änderungen, die es auf der Platte sieht, auto-committet), kann es mit dem eigenen End-of-Session-Commit des Agenten racen — du landest bei einem leeren Commit oder einem Merge-Konflikt beim Push. Die sichere Topologie ist: Der Agent besitzt den Worktree, der Watcher besitzt den Haupt-Clone, und nie überschreiten sich die beiden.

Prüfe dich selbst

0/3
  1. Bei v2.1.221-Standards beendet ein Background-Agent eine Recherche-Aufgabe mit `/subtask`. Was passiert beim Abschluss?
  2. Du willst die Draft-PR-Erstellung blockieren, aber den Push behalten, damit `/resume` den Branch aufgreifen kann. Was konfigurierst du?
  3. Der `Notification`-Hook feuert `agent_completed` mit `pr_url: null`. Was bedeutet das auf v2.1.221?
Auto-PR-Flow — jede Karte umdrehen
Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.
1 / 6
Key takeaways
  • Der Auto-PR-Flow lebt in der Runtime-Schicht, nicht der Settings-Schicht — es gibt keinen `backgroundAgents.autoCreatePr`-Schlüssel, und es wird keinen geben. Verwende Permissions.
  • v2.1.221 (heutiger Standard) committet und pusht immer; es öffnet einen Draft-PR nur, wenn die Aufgabe eine prüfbare Änderung darstellt. Lies das `pr_url`-Feld der Notification, um zu sagen, was geschah.
  • `/fork` bedeutet jetzt 'übergib diese Konversation an einen Background-Worker'; `/subtask` ist, was du greifst, wenn du einen In-Conversation-Helfer willst ohne die Beende-und-Veröffentliche-Sequenz.
  • Das propose-only-Muster ist ein Permission-Deny auf `Bash(gh pr create:*)`. Es überlebt jede Version von v2.1.x und jedes Kommando, das eine Background-Sitzung produziert.
  • Background-Agenten zählen immer noch gegen `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`. Eine Flotte von 25 halbfertigen Sitzungen in `claude agents` beginnt, neue Spawns abzulehnen.

Weiter​

Quellen & weiterführende Lektüre​