Subagents

Ein Subagent ist ein zweiter Claude, den die Sitzung für eine Teilaufgabe startet. Er arbeitet in einem eigenen Kontextfenster und meldet am Ende ein Ergebnis. Warum sich das lohnt und wann das Hauptgespräch die bessere Wahl bleibt, erklärt Vibe-Coding / Agentic Engineering, Kapitel 13. Dieses Kapitel zeigt die Mechanik in Claude Code: wie die Übergabe abläuft, was der Subagent zu sehen bekommt und was zurückkommt.

Wie Claude eine Aufgabe abgibt

Claude delegiert über ein eigenes Werkzeug, das Agent-Werkzeug. Version 2.1.63 gab ihm diesen Namen, vorher hieß es Task. Angaben mit dem alten Namen in Einstellungen und Definitionen gelten weiter (Doku zu Subagents (externe Seite, code.claude.com)). Den Auftrag formuliert Claude selbst: Es schreibt eine Nachricht, die die Aufgabe zusammenfasst, und mit ihr beginnt der Subagent.

Ob Claude delegiert, entscheidet es meistens allein. Es vergleicht die Aufgabe mit der Beschreibung jedes verfügbaren Subagents. Wer das nicht dem Zufall überlassen will, ruft einen Subagent gezielt auf, dazu weiter unten mehr.

Ein Subagent schickt eigene Anfragen an das Modell. Sie zählen gegen dasselbe Kontingent wie das Hauptgespräch. Das eigene Fenster bleibt dabei schlank, der Verbrauch wächst.

Was der Subagent sieht

Ein gewöhnlicher Subagent beginnt mit einem leeren, abgetrennten Fenster (Doku zu Subagents (externe Seite, code.claude.com)). Den bisherigen Verlauf sieht er nicht, ebenso wenig die Skills, die schon geladen wurden, und die Dateien, die Claude schon gelesen hat. In seinem Fenster liegen zu Beginn:

• seine eigene Systemanweisung mit ein paar Angaben zur Umgebung, etwa dem Arbeits­ver­zeichnis. Die Systemanweisung von Claude Code bekommt er nicht.
• der Auftrag, den Claude geschrieben hat
• die CLAUDE.md-Dateien aller Ebenen, die auch das Hauptgespräch lädt
• ein Abbild des Git-Stands beim Start
• die Skills, die seine Definition ausdrücklich vorlädt

Was im Hauptgespräch geklärt wurde, kennt er also nur, wenn es im Auftrag steht. Eine Regel, die er unbedingt beachten muss, gehört deshalb in die Bitte, mit der man Claude die Arbeit abgeben lässt. Die Doku nennt als Beispiel ein Verzeichnis, das ignoriert werden soll. Für die meisten Regeln ist das unnötig, weil das Hauptgespräch den Bericht mit der ganzen CLAUDE.md liest.

seitlich verschiebbar

eigene Darstellung nach der Her­stel­ler­do­ku­men­ta­tion, Stand 12.10.2026

Was zurückkommt

Zurück kommt der Schlussbericht des Subagents. Seine Zwischenschritte, die gelesenen Dateien und die Ausgaben seiner Befehle bleiben in seinem Fenster. Bevor Claude den Bericht liest, prüft Claude Code ihn auf Text, der wie eine Anweisung an das Hauptgespräch aussieht (Doku zu Subagents (externe Seite, code.claude.com)). Der Grund: Ein Subagent hat womöglich Webseiten oder Dateien gelesen, die niemand gesehen hat. Der Bericht bekommt deshalb einen Kopf, der ihn als Wort des Subagents ausweist. Was darin wie eine Anweisung oder eine Zustimmung klingt, gilt nicht als Wort des Menschen am Terminal.

Mit dem Bericht bekommt Claude eine Kennung des Subagents. Über sie kann es ihn später weiterarbeiten lassen, mit dem ganzen bisherigen Verlauf. Wie das geht, steht auf der dritten Ebene.

Die eingebauten Subagents

Claude Code bringt eigene Subagents mit. Der bekannteste heißt Explore, ein schneller Agent, der nur liest und Code durchsucht (Doku zu Subagents (externe Seite, code.claude.com)). Schreiben und Bearbeiten sind ihm verboten. Beim Aufruf gibt Claude an, wie gründlich er suchen soll: quick, medium oder very thorough. Explore kam mit Version 2.0.17 vom 15.10.2025 und lief damals auf Haiku. Seit Version 2.1.198 vom 01.07.2026 nimmt er das Modell des Hauptgesprächs (Versionsliste (externe Seite, code.claude.com)). Läuft das Hauptgespräch auf Fable, hängt sein Modell vom Zugang ab. Mit einem Claude-Abo oder einem Console-Konto läuft er auf Opus, über Cloud-Anbieter wie Bedrock, Google oder Foundry bleibt er auf Fable (Doku zu Subagents (externe Seite, code.claude.com)). Wie man eine Erkundung beim Einarbeiten in fremden Code abgibt, zeigt Kapitel 09.

Daneben gibt es Plan, der im Plan-Modus den Code erkundet, und general-purpose für Aufgaben, die lesen und ändern müssen. Explore und Plan starten ohne die CLAUDE.md und den Git-Stand, damit die Suche schnell und billig bleibt. Dazu kommen kleine Helfer, etwa einer, der Fragen zu Claude Code beantwortet. Sie startet Claude in der Regel von selbst.

Eigene Subagents anlegen

Seit Version 1.0.60 vom 24.07.2025 kann man eigene Subagents anlegen (Versionsliste (externe Seite, code.claude.com)). Ein eigener Subagent ist eine Markdown-Datei mit einem Kopf in YAML. Der Kopf nennt mindestens einen Namen und eine Beschreibung, darunter steht die Systemanweisung des Subagents:

---
name: code-reviewer
description: Prüft Code nach jeder Änderung.
tools: Read, Glob, Grep
model: sonnet
---

Du prüfst Code. Nenne zu jedem Befund Datei, Zeile und einen Vorschlag.

Liegt die Datei in .claude/agents/ im Projekt, gilt der Subagent dort und lässt sich mit dem Repository teilen. In ~/.claude/agents/ steht er in jedem Projekt bereit. Die Doku rät zu einem eigenen Subagent, sobald man immer wieder dieselbe Art Helfer mit denselben Anweisungen losschickt.

Anfangs führte der Befehl /agents durch einen Dialog zum Anlegen. Diesen Assistenten hat Version 2.1.198 entfernt. Heute bittet man Claude, die Datei zu schreiben, oder schreibt sie selbst. /agents erinnert nur noch an diese beiden Wege (Doku zu Subagents (externe Seite, code.claude.com)). Welche Felder der Kopf sonst noch kennt, zeigt die zweite Ebene.

Einen Subagent gezielt aufrufen

Drei Wege führen zu einem bestimmten Subagent, vom schwächsten zum stärksten:

1. Man nennt ihn im Prompt beim Namen. Claude entscheidet dann selbst, ob es delegiert.
2. Man erwähnt ihn mit @, seit Version 1.0.62 vom 28.07.2025 (Versionsliste (externe Seite, code.claude.com)). Dann läuft genau dieser Subagent. Den Auftrag schreibt weiter Claude aus der ganzen Nachricht (Doku zu Subagents (externe Seite, code.claude.com)).
3. Die ganze Sitzung läuft als dieser Subagent, gestartet mit claude --agent <name>. Das Hauptgespräch übernimmt dann seine Anweisung, seine Werkzeuge und sein Modell. Mehr dazu auf der zweiten Ebene.

Subagents laufen im Hintergrund

Seit Version 2.1.198 vom 01.07.2026 laufen Subagents in der Voreinstellung im Hintergrund. Claude arbeitet weiter und wird benachrichtigt, wenn einer fertig ist (Versionsliste (externe Seite, code.claude.com)). Mit -p und im Agent SDK kann Claude auf einen Subagent warten, nach eigenem Ermessen oder auf Bitte. Die genauen Regeln stehen auf der dritten Ebene. Ein Subagent im Hintergrund bekommt einen kleineren Satz an Werkzeugen als einer im Vordergrund, die Liste steht auf der zweiten Ebene. Wie man mehrere laufende Agenten überblickt und anhält, erklärt Kapitel 21. Subagents gehören dabei immer zu einer Sitzung. Mehrere Sitzungen, die Claude als Team startet und beaufsichtigt, sind ein eigenes Format, beschrieben in Kapitel 22.

Mehrere Subagents dürfen gleichzeitig laufen. Laufen schon zwanzig, scheitert in der Voreinstellung jeder weitere Start, bis einer fertig ist. Jeder dieser Subagents verbraucht dabei eigene Token, und jeder Bericht belegt Platz im Hauptgespräch (Doku zu Subagents (externe Seite, code.claude.com)).

Der Fork nimmt das Gespräch mit

Ein Fork ist ein Subagent, der das ganze bisherige Gespräch erbt (Doku zu Subagents (externe Seite, code.claude.com)). Er sieht dieselbe Systemanweisung, dieselben Werkzeuge, dasselbe Modell und den Verlauf. Man muss ihm also nichts neu erklären. Seine Zwischenschritte bleiben trotzdem draußen, ins Hauptgespräch kommt nur sein Ergebnis.

Version 2.1.117 vom 22.04.2026 machte den Fork über eine Umgebungsvariable verfügbar. Seit Version 2.1.232 vom 13.08.2026 ist der Fork-Modus im Terminal voreingestellt, Claude kann also selbst Forks starten. Seit Version 2.1.302 vom 16.10.2026 gilt das auch mit -p, im Agent SDK, in der Desktop-App und in VS Code (Versionsliste (externe Seite, code.claude.com)). Von Hand startet man einen Fork mit /subtask und einer Aufgabe dahinter, bis Version 2.1.211 hieß der Befehl /fork. Er erscheint dann in einer Leiste unter der Eingabe, und sein Ergebnis kommt als Nachricht ins Gespräch. Weil Systemanweisung und Werkzeuge gleich sind, nutzt seine erste Anfrage den Zwischenspeicher des Hauptgesprächs. Für Aufgaben, die denselben Zusammenhang brauchen, kostet er deshalb weniger als ein frischer Subagent. Wie der Zwischenspeicher rechnet, steht in Kapitel 05.

Die erste Ebene hat gezeigt, wie Claude eine Aufgabe abgibt. Hier geht es um die Datei, die einen Subagent beschreibt: wo sie liegt, was in ihrem Kopf stehen kann und wie aus den Feldern Werkzeuge, Modell und Rechte werden.

Wo Subagents liegen

Dieselbe Definition kann an fünf Stellen stehen. Haben zwei Subagents denselben Namen, gewinnt die Stelle mit dem höheren Rang (Doku zu Subagents (externe Seite, code.claude.com)).

Die Angabe per --agents gibt es seit Version 2.0.0 vom 29.09.2025 (Versionsliste (externe Seite, code.claude.com)). Sie landet nirgends auf der Platte und passt deshalb für Versuche und Skripte. Projektordner sucht Claude Code vom Arbeits­ver­zeichnis aufwärts bis zur Wurzel des Repositorys. Bei gleichem Namen gewinnt dort die Datei, die dem Arbeits­ver­zeichnis am nächsten liegt. Unterordner wie agents/review/ sind erlaubt, sie ändern den Namen nicht.

Änderungen an einer Datei greifen ohne Neustart. Claude Code beobachtet beide Ordner und nimmt bei der nächsten Übergabe die neue Fassung. Neu starten muss man, wenn der Ordner agents beim Start noch fehlte.

Die Beschreibungen aller eigenen Subagents belegen Platz im Kontext, denn an ihnen entscheidet Claude, wohin es delegiert. Überschreiten sie zusammen 15.000 Token, warnt Claude Code beim Start. Die Doku rät, die Beschreibungen kurz zu halten und Einzelheiten in die Systemanweisung zu schieben. Die lädt erst, wenn der Subagent läuft.

Was in einer Definition steht

Pflicht sind nur name und description. Die übrigen Felder sind freiwillig, die wichtigsten mit der Version, in der sie dazukamen (Versionsliste (externe Seite, code.claude.com)):

Wo keine Version steht, nennt die Versionsliste keinen Einführungstag. Ein Vertipper fällt nicht auf. Claude Code übergeht ein Feld, das es nicht kennt, ohne Fehlermeldung (Doku zu Subagents (externe Seite, code.claude.com)). Fehlt die Beschreibung oder lässt sich der Kopf nicht lesen, wird die ganze Datei übersprungen, und nur das Protokoll von claude --debug nennt den Grund. Seit Version 2.1.233 findet claude plugin validate .claude/agents vorab die Köpfe eines Ordners, die sich nicht lesen lassen.

Ein Subagent aus einem Plugin übergeht drei Felder: hooks, mcpServers und permissionMode. Der Grund ist die Sicherheit. Wer sie braucht, kopiert die Datei in einen eigenen Ordner agents.

Welche Werkzeuge ein Subagent bekommt

Ohne Angabe erbt ein Subagent die Werkzeuge des Hauptgesprächs, MCP-Werkzeuge eingeschlossen (Doku zu Subagents (externe Seite, code.claude.com)). Zwei Filter nehmen davon weg. Der erste trifft jeden Subagent, gleich was in tools steht. Er entzieht unter anderem die Rückfrage an den Menschen, den Wechsel in den Plan-Modus und das Werkzeug für Workflows. Der zweite trifft Subagents im Hintergrund, also den Normalfall. Sie behalten alle MCP-Werkzeuge, aber nur eine feste Liste eingebauter Werkzeuge, darunter Lesen, Suchen, Bash, Bearbeiten, Schreiben und Webabruf. Dieselbe Definition kann damit im Vordergrund mehr Werkzeuge haben als im Hintergrund.

tools ist eine Erlaubnisliste, disallowedTools eine Sperrliste. Stehen beide da, zieht Claude Code zuerst die Sperrliste ab. Ein Eintrag mit Muster wie Bash(git push *) entzieht in der Sperrliste das ganze Werkzeug Bash. Wer nur einzelne Befehle sperren will, schreibt eine Regel in permissions.deny der Einstellungen. Wie solche Regeln aussehen, steht in Kapitel 04.

Einzelne Subagents lassen sich dort auch ganz abschalten, mit Agent(Explore) oder Agent(name) in permissions.deny. Steht nur Agent dort, delegiert Claude gar nicht mehr.

Modell und Effort eines Subagents

Seit Version 1.0.64 vom 30.07.2025 kann ein Subagent ein eigenes Modell haben (Versionsliste (externe Seite, code.claude.com)). Welches er bekommt, löst Claude Code in dieser Reihenfolge auf (Doku zu Subagents (externe Seite, code.claude.com)):

1. ein Modell, das Claude beim Aufruf mitgibt
2. das Feld model der Definition, wobei inherit das Modell des Hauptgesprächs meint
3. die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL
4. das Modell des Hauptgesprächs

Vor Version 2.1.251 stand die Umgebungsvariable an erster Stelle. Wer heute jeden Subagent auf ein Modell zwingen will, setzt zusätzlich CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. Ein Kurzname wie opus im Feld model oder beim Aufruf landet auf dem genauen Modell des Hauptgesprächs, wenn dieses zur selben Familie gehört, samt seinem Kontextfenster. Welches Modell ein laufender Subagent hat, zeigt /tasks in seiner Zeile. Wie Modelle und Effort allgemein gewählt werden, steht in Kapitel 06.

Das Fenster eines Subagents richtet sich nach seinem eigenen Modell. Wer an ein Modell mit kleinerem Fenster abgibt, gibt dem Subagent also weniger Platz.

Den Effort setzt das Feld effort. Es gilt vor dem Effort der Sitzung, die Umgebungsvariable CLAUDE_CODE_EFFORT_LEVEL gilt vor beiden. Seit Version 2.1.292 vom 06.10.2026 kann Claude beim Aufruf außerdem einen Effort mitgeben, wenn man darum bittet, außer bei einem Fork. Nachgedacht wird im Subagent seit Version 2.1.198 genau dann, wenn auch das Hauptgespräch nachdenkt. Vorher liefen Subagents immer ohne erweitertes Nachdenken.

Rechte und Rückfragen

Ohne eigenes permissionMode übernimmt ein Subagent den Modus des Hauptgesprächs (Doku zu Subagents (externe Seite, code.claude.com)). Ein eigener Wert gilt nur, solange das Hauptgespräch im Normalmodus, in dontAsk oder im Plan-Modus steht. Läuft es in auto, acceptEdits oder bypassPermissions, nimmt der Subagent denselben Modus, gleich was seine Datei sagt. Welche Modi es gibt, erklärt Kapitel 03.

Braucht ein Subagent im Hintergrund eine Erlaubnis, erscheint die Rückfrage seit Version 2.1.186 vom 22.06.2026 im Hauptgespräch. Vorher lehnte Claude Code sie selbst ab (Versionsliste (externe Seite, code.claude.com)). Was man dort antworten kann und wie weit eine Antwort reicht, steht in Kapitel 21.

Skills, Gedächtnis und Hooks

Das Feld skills lädt die genannten Skills beim Start vollständig in das Fenster des Subagents, höchstens die ersten 32 (Doku zu Subagents (externe Seite, code.claude.com)). Es legt fest, was vorgeladen wird. Andere Skills kann der Subagent weiter über das Skill-Werkzeug holen. Umgekehrt kann ein Skill selbst in einem Subagent laufen. Wie das geht, zeigt Kapitel 17.

Mit memory bekommt ein Subagent einen eigenen Ordner, der Sitzungen überdauert. Darin sammelt er, was er über den Code lernt. user legt ihn unter ~/.claude/agent-memory/ an, project unter .claude/agent-memory/ im Projekt, local ebenfalls im Projekt, aber außerhalb der Versionskontrolle. Die Doku empfiehlt project. Die ersten 200 Zeilen oder 25 KB der Datei MEMORY.md darin stehen bei jedem Start in seiner Anweisung. Ist das automatische Gedächtnis von Claude Code abgeschaltet, wirkt das Feld nicht.

Hooks gibt es an zwei Stellen. Im Kopf der Datei gelten sie nur für diesen Subagent. In den Einstellungen melden SubagentStart (seit 2.0.43) und SubagentStop (seit 1.0.41), wann ein Subagent beginnt und endet (Versionsliste (externe Seite, code.claude.com)). Hooks eines Projekt-Subagents laufen erst, wenn man dem Ordner vertraut hat.

Die ganze Sitzung als Subagent

Seit Version 2.0.59 vom 04.12.2025 kann das Hauptgespräch selbst die Rolle eines Subagents übernehmen (Versionsliste (externe Seite, code.claude.com)). Mit claude --agent code-reviewer gilt das für eine Sitzung, mit "agent": "code-reviewer" in .claude/settings.json für jede Sitzung im Projekt. Das Hauptgespräch bekommt dann die Werkzeugliste und das Modell des Subagents (Doku zu Subagents (externe Seite, code.claude.com)). Seine Systemanweisung ersetzt die von Claude Code vollständig, die CLAUDE.md lädt trotzdem. Der Kopf der Sitzung zeigt @code-reviewer, und beim Fortsetzen bleibt die Rolle erhalten.

In dieser Form gibt es zwei zusätzliche Felder. initialPrompt wird seit Version 2.1.83 als erste Nachricht abgeschickt. Und tools: Agent(worker, researcher) legt fest, welche Subagents die Sitzung ihrerseits starten darf, seit Version 2.1.33 (Versionsliste (externe Seite, code.claude.com)). In einem gewöhnlichen Subagent übergeht Claude Code die Liste in den Klammern.

Die Subagents haben sich seit dem Start oft verändert, am dichtesten im Juli 2026. Diese Ebene ordnet die Schritte und zeigt die Stellen, die man erst braucht, wenn ein Subagent weiterarbeiten soll, sich verschachtelt oder mit einem Fehler endet.

Vom AgentTool zum Fork

Ein Werkzeug zum Delegieren gab es vom ersten Tag an. Die Doku vom Februar 2025 führt in ihrer Werkzeugliste ein AgentTool, das einen Subagent für mehrstufige Aufgaben startet. Sie liegt heute nur noch als Archivfassung (externe Seite, docs.anthropic.com) vor. Die Schritte danach nennt die Versionsliste (externe Seite, code.claude.com):

Seit Version 2.1.63 vom 28.02.2026 heißt das Werkzeug Agent statt Task. Das steht in der Doku zu Subagents (externe Seite, code.claude.com), in der Versionsliste fehlt der Schritt.

Drei Linien laufen durch die Tabelle. Die erste macht aus einem Helfer ohne Schreibrecht einen Agenten, der Dateien ändert und Befehle ausführt. Die zweite gibt dem Nutzer die Definition in die Hand: Ab Juli 2025 beschreibt eine eigene Datei den Subagent, bis Ende 2025 kommen Felder für Modell, Rechte und vorgeladene Skills dazu. Die dritte schiebt die Arbeit in den Hintergrund und gibt dem Subagent das Gespräch mit, zuerst 2.1.198, dann 2.1.232 mit dem Fork als Voreinstellung im Terminal und 2.1.302 überall.

Wie tief Subagents sich schachteln

Dass ein Subagent selbst Subagents startet, ist eine junge Regel, und ihre Grenze hat sich seither zweimal verschoben (Versionsliste (externe Seite, code.claude.com)):

Die dritte Fassung gilt am 12.10.2026 weiter (Doku zu Subagents (externe Seite, code.claude.com)). Die Umgebungsvariable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH stellt die Zahl der Ebenen ein, der Wert 1 schaltet das Schachteln ab. Was an der Grenze mit dem Werkzeug zum Delegieren geschieht, erklärt die zweite Ebene von Vibe-Coding / Agentic Engineering, Kapitel 13.

In einer interaktiven Sitzung wartet ein Subagent auf die Subagents, die er selbst gestartet hat. Zurück ins Hauptgespräch kommt dann nur sein eigener Bericht. Mit -p und im Agent SDK wartet er ebenfalls, solange der Fork-Modus an ist. Ist er aus, starten die geschachtelten Subagents im Hintergrund. Ein Subagent, der dann nach ihm fertig wird, meldet sich direkt im Hauptgespräch. Im Terminal zeigt die Leiste unter der Eingabe verschachtelte Subagents als Baum, und jede Zeile mit weiteren Kindern zeigt deren Zahl als (+N).

Fork und frischer Subagent im Vergleich

Ein Fork erbt alles, was das Hauptgespräch beim Start hat. Jeder andere Subagent beginnt frisch mit seiner Definition. Die Doku zu Subagents (externe Seite, code.claude.com) stellt beide gegenüber:

Ein Fork kann keinen weiteren Fork starten. Claude kann ihm beim Start einen eigenen Worktree geben, dann landen seine Änderungen außerhalb des eigenen Arbeitsstands. Wie Worktrees parallele Arbeit trennen, steht in Kapitel 21.

Ob Claude Forks starten darf, regelt der Fork-Modus. Seit Version 2.1.302 vom 16.10.2026 ist er überall eingeschaltet, auch mit -p, im Agent SDK, in der Desktop-App und in VS Code. Im Terminal gilt das seit 2.1.232. Ohne eigene Einstellung startet ein Subagent aus dem Hauptgespräch im Hintergrund. Ist der Fork-Modus an, kann Claude im Terminal, in VS Code und in der Desktop-App auf keinen Subagent warten. Mit -p und im Agent SDK wartet Claude trotzdem, wenn es das für nötig hält oder man darum bittet. Wer Claude auch dort warten lassen will, schaltet den Fork-Modus aus. Steht CLAUDE_CODE_DISABLE_BACKGROUND_TASKS auf 1, läuft jeder Subagent im Vordergrund, mit und ohne Fork-Modus. CLAUDE_CODE_FORK_SUBAGENT=0 schaltet ihn überall aus. Wer den Modus behalten und nur Forks verbieten will, schreibt Agent(fork) in permissions.deny. Wie Claude Code Skripte und Pipelines betreibt, erklärt Kapitel 29.

Einen Subagent fortsetzen

Jeder Aufruf startet einen neuen Subagent (Doku zu Subagents (externe Seite, code.claude.com)). Soll einer weitermachen, bittet man Claude darum. Claude schickt ihm dann mit dem Werkzeug SendMessage eine Nachricht, adressiert über seine Kennung oder seinen Namen. Der Subagent setzt mit seinem ganzen Verlauf fort, einschließlich aller Werkzeugaufrufe, Ergebnisse und Überlegungen. Explore und Plan liefern keine Kennung und lassen sich deshalb nicht fortsetzen. Für Arbeit, die weitergehen soll, nimmt man general-purpose oder einen eigenen Subagent.

Ein Subagent, der an seiner Obergrenze maxTurns anhält, meldet sein Ergebnis seit Version 2.1.246 als unvollständig, und Claude kann ihn fortsetzen. Wer einen Subagent selbst stoppt, mit x in /tasks, sperrt ihn für Claude: Eine Nachricht von Claude an ihn weist Claude Code ab. Solange seine Zeile noch in der Leiste steht, kann man selbst in seinen Verlauf schreiben und ihn so fortsetzen. Danach darf auch Claude ihn wieder anschreiben.

Nachrichten des Agenten, der ihn gestartet hat, behandelt ein Subagent seit Version 2.1.198 als Teil seines Auftrags. Eine Zustimmung ersetzen sie nie. Keine Nachricht eines Agenten gilt als Antwort auf eine offene Rückfrage. Seine Rechte, seine CLAUDE.md und seine Einstellungen kann ihm ebenfalls kein Agent ändern.

Die Verläufe der Subagents liegen getrennt vom Hauptgespräch unter ~/.claude/projects/<projekt>/<sitzung>/subagents/, je Subagent eine Datei agent-<kennung>.jsonl. Verdichtet das Hauptgespräch, bleiben sie, wie sie sind. Nach einem Neustart lässt sich ein Subagent fortsetzen, wenn man dieselbe Sitzung fortsetzt. Gelöscht werden die Dateien nach der Frist cleanupPeriodDays, in der Voreinstellung 30 Tage.

Was mit dem Bericht geschieht

Seit Version 2.1.210 durchsucht Claude Code jeden Schlussbericht, bevor Claude ihn liest (Doku zu Subagents (externe Seite, code.claude.com)). Gestrichen oder umformuliert wird dabei nichts. Ahmt ein Text die Ausgabe von Claude Code nach, etwa einen Systemhinweis oder eine Zeile, die mit Human: beginnt, setzt die Prüfung einen Rückstrich hinein. So liest Claude die Stelle als gewöhnlichen Text. Erwähnt der Bericht Einstellungen wie bypassPermissions, steht darüber eine Markierungszeile, die mit [harness: subagent output matched beginnt.

Ob ein Inhalt bösartig ist, beurteilt die Prüfung nicht. Ein Werkzeugaufruf, zu dem ein Bericht Claude bringt, läuft weiter durch die Rechte und die Sandbox der Sitzung. Die Doku nennt die Prüfung ausdrücklich keinen Ersatz dafür, einem Subagent nur die Werkzeuge zu geben, die er braucht.

Endet ein Subagent an einem Fehler der Schnittstelle, etwa einem erschöpften Kontingent, erfährt Claude davon. Bricht im Vordergrund eine Ratenbegrenzung, eine Überlast oder ein Serverfehler einen Subagent ab, der schon Text geschrieben hat, kommt diese Teilantwort mit einem Hinweis auf den Abbruch zurück. Ein Subagent im Hintergrund wird als gescheitert geführt, und die Meldung an Claude enthält seine letzte Ausgabe. Ist eine Kette von Ausweichmodellen eingestellt, wechselt der Subagent auf das erste Modell, das die Anfrage annimmt, und arbeitet weiter. Wie diese Kette funktioniert, steht in Kapitel 06.