Fork Subagents in Claude Code

Das Problem: Parallele Subagenten in Claude Code zu betreiben war teuer. Jeder Kind-Agent hat den System-Prompt, das komplette Tool-Array und die gesamte Konversationshistorie von Grund auf neu aufgebaut. Fünf Agenten bedeuteten fünf volle Input-Token-Rechnungen. Kein Sharing. Vor v2.1.117 existierte der Fork-Pfad zwar im Codebase, wurde aber in öffentlichen Releases per Compile-Time-Flag entfernt. Nur interne Anthropic-Builds konnten ihn nutzen.

Schneller Gewinn: Eine einzige Umgebungsvariable ändert die Rechnung. Setzt du CLAUDE_CODE_FORK_SUBAGENT=1, ziehen die Kinder 2-N ihren gemeinsamen Prefix direkt aus dem Prompt-Cache. Ungefähr 10x Kostenreduktion pro zusätzlichem Kind:

export CLAUDE_CODE_FORK_SUBAGENT=1

Was Fork Subagents wirklich sind

Ein Fork-Kind bekommt keine frische Session. Es bekommt die exakten Bytes des bereits gerenderten System-Prompts seines Eltern-Agenten, über override.systemPrompt aus toolUseContext.renderedSystemPrompt. Gleiche Bytes, kein Neu-Rendering. Das ist wichtig, weil Feature-Flag-Zustände (zum Beispiel GrowthBook) zwischen Eltern und Kind konsistent bleiben, ohne zusätzliche Koordination.

Das Tool-Array folgt der gleichen Regel. Es wird mit useExactTools: true durchgereicht, was resolveAgentTools() komplett umgeht. Die Serialisierung bleibt byte-identisch, und genau das macht den Prompt-Cache funktionsfähig. Eine Besonderheit: Das Agent-Tool bleibt im Tool-Pool des Kindes, obwohl das Kind es nicht aufrufen darf. Es zu entfernen würde den Cache brechen. Die Einschränkung wird anders durchgesetzt (dazu gleich mehr).

Jeder Eltern-Tool-Use-Block in der Nachrichtenhistorie des Kindes bekommt eine FORK_PLACEHOLDER_RESULT-Konstante ('Fork started -- processing in background') als Ergebnis. Jedes Kind empfängt identische Platzhalter-Bytes. Die Cache-Grenze liegt genau vor der kindspezifischen Direktive, sodass die Kinder erst bei der aufgabenspezifischen Anweisung auseinanderlaufen.

Vor v2.1.117 war dieser gesamte Pfad in öffentlichen Builds zur Compile-Zeit entfernt. Externe Nutzer konnten ihn überhaupt nicht auslösen.

Die Kostenrechnung

Bei 48.500 Tokens gemeinsamen Prefix sind die Zahlen konkret:

Kind eins zahlt den vollen Preis. Es ist die erste Anfrage, der Cache ist noch leer. Kinder 2-N treffen den gemeinsamen Prefix und zahlen nur für das Delta.

Fünf Agenten parallel: Ohne Fork gibt man für gemeinsamen Kontext rund 243.500 Tokens aus. Mit Fork sind es ~48.700 für Kind eins plus ~20.200 für die Kinder zwei bis fünf. Den Rest erledigt der Cache.

Aktivierung

Die Umgebungsvariable ins Shell-Profil eintragen:

export CLAUDE_CODE_FORK_SUBAGENT=1

Für CI/CD-Pipelines: die Variable auf Pipeline-Ebene in den Umgebungsvariablen setzen. Jeder Agent-Run in dieser Pipeline nimmt sie automatisch auf.

Wichtig zu wissen: Fork springt nur an, wenn subagent_type beim Agent-Tool-Aufruf weggelassen wird. Gibt das Modell einen expliziten Typ an (zum Beispiel "Explore" oder "Plan"), löst der Fork-Pfad nicht aus. Die benannten Typen haben ihre eigene Logik.

Der rekursive Fork-Guard

Das hier taucht sonst nirgendwo auf.

Jedes Fork-Kind bekommt ein Standard-XML-Tag in seine Session injiziert. Das Tag besagt sinngemäß: Diese Anweisung gilt für den Eltern-Agenten. Du BIST der Fork. Spawne KEINE Sub-Agenten.

Ohne das würden Kinder versuchen, eigene Kinder zu forken, die dann weitere forken, und das Ganze würde so lange rekursieren, bis das Kontextfenster kollabiert. Das XML-Tag bricht die Kette.

Es gibt zwei Guards, nicht einen. Der erste ist ein querySource === 'agent:builtin:fork' Fast-Path-Check am Anfang des Agent-Options-Handlers. Der zweite ist ein Fallback-Scan der Nachrichtenhistorie, der nach dem Standard-XML-Tag selbst sucht. Der Fallback existiert, weil querySource durch autocompact bei langen Sessions überschrieben werden kann. Beide Checks müssen übereinstimmen, dass es sich um eine Fork-Kind-Session handelt, bevor der Guard greift.

Fork ist außerdem inkompatibel mit dem Coordinator-Modus. Ein geforkter Koordinator würde den "Du bist der Koordinator, delegiere Aufgaben"-System-Prompt des Eltern-Agenten erben und anfangen zu orchestrieren statt auszuführen. Die beiden Modi können keine Session teilen.

Was es ermöglicht

Parallele Agent-Dispatches sind der Hauptanwendungsfall. Fünf Agenten über fünf Module laufen gleichzeitig, und die Kinder 2-5 teilen den gecachten Prefix des Eltern-Agenten. Die Gesamtkosten für den gemeinsamen Kontext sinken auf ungefähr die Token-Kosten eines zusätzlichen Kindes.

CI/CD-Pipelines profitieren automatisch, sobald CLAUDE_CODE_FORK_SUBAGENT=1 in der Umgebung gesetzt ist. Multi-Agenten-Workflows, die bisher wegen der Kosten nicht skalierbar waren, werden praktikabel.

Das "Policy Islands"-Pattern wird ebenfalls nutzbar. Befehle mit context: fork und agent: <name> im Frontmatter spawnen isolierte Subagenten mit vorab deklarierten allowed_tools. Diese Subagenten laufen ohne Approval-Prompts mitten im Workflow und geben dem Eltern-Agenten nur eine Zusammenfassung zurück. Der Eltern-Agent sieht die Zwischen-Tool-Calls nie.

Bekannte Grenzen

• Inkompatibel mit --print-Modus. Fork nutzt permissionMode: 'bubble', das Prompts an ein Eltern-Terminal übergibt. In non-interaktiven SDK/Headless-Runs gibt es kein Terminal.
• Inkompatibel mit dem Coordinator-Modus. Ein geforkter Koordinator erbt Orchestrierungsanweisungen und versucht zu delegieren statt auszuführen.
• Kontextfenster skaliert mit der Session-Länge. Fork-Kinder tragen die vollständige Eltern-Konversationshistorie. Lange Sessions mit vielen Kindern kosten insgesamt mehr, auch mit Caching. Lange, heiße Sessions sind der kritische Fall.
• Opt-in, kein Standard. Die Umgebungsvariable muss explizit gesetzt werden. Ohne sie ändert sich nichts.

Was das im großen Maßstab freisetzt

Mit gesetztem CLAUDE_CODE_FORK_SUBAGENT=1 und Pro/Max-Nutzern, die jetzt standardmäßig bei high-Effort liegen (ebenfalls ab v2.1.117), ist die Kombination bedeutsam. Ein Orchestrator auf high-Effort dispatcht parallele Fork-Kinder. Jedes Kind erbt den vollständigen Eltern-Kontext zu Cache-Rabattpreisen. Jedes Kind läuft auf high-Effort. Vor diesem Release hatten Pro/Max-Nutzer beides nicht.

Die Umgebungsvariable setzen, fünf Agenten parallel laufen lassen, und vier davon kosten ungefähr ein Zehntel von früher. Das ist die ganze Geschichte.