Benutzerdefinierte Subagenten erstellen

Erstellen und verwenden Sie spezialisierte KI-Subagenten in Claude Code für aufgabenspezifische Workflows und verbesserte Kontextverwaltung.

Subagenten sind spezialisierte KI-Assistenten, die bestimmte Arten von Aufgaben bearbeiten. Verwenden Sie einen, wenn eine Nebenaufgabe Ihre Hauptkonversation mit Suchergebnissen, Protokollen oder Dateiinhalten überfluten würde, auf die Sie nicht mehr verweisen werden: Der Subagent führt diese Arbeit in seinem eigenen Kontext durch und gibt nur die Zusammenfassung zurück. Definieren Sie einen benutzerdefinierten Subagenten, wenn Sie wiederholt denselben Typ von Worker mit denselben Anweisungen spawnen.

Jeder Subagent läuft in seinem eigenen Kontextfenster mit einem benutzerdefinierten Systemprompt, spezifischem Werkzeugzugriff und unabhängigen Berechtigungen. Wenn Claude auf eine Aufgabe trifft, die der Beschreibung eines Subagenten entspricht, delegiert es an diesen Subagenten, der unabhängig arbeitet und Ergebnisse zurückgibt. Um die Kontexteinsparungen in der Praxis zu sehen, zeigt die Kontextfenster-Visualisierung eine Sitzung, in der ein Subagent Recherchen in seinem eigenen separaten Fenster durchführt.

Subagenten helfen Ihnen:

Kontext bewahren, indem Sie Exploration und Implementierung aus Ihrer Hauptkonversation heraushalten
Einschränkungen durchsetzen, indem Sie begrenzen, welche Werkzeuge ein Subagent verwenden kann
Konfigurationen wiederverwenden über Projekte hinweg mit Subagenten auf Benutzerebene
Verhalten spezialisieren mit fokussierten Systemprompts für spezifische Domänen
Kosten kontrollieren, indem Sie Aufgaben an schnellere, günstigere Modelle wie Haiku weiterleiten

Claude verwendet die Beschreibung jedes Subagenten, um zu entscheiden, wann Aufgaben delegiert werden. Wenn Sie einen Subagenten erstellen, schreiben Sie eine klare Beschreibung, damit Claude weiß, wann er ihn verwenden soll.

Diese Beschreibungen beanspruchen Kontext, daher halten Sie sie kurz. Wenn die kombinierten Beschreibungen Ihrer Subagenten, mit Ausnahme der integrierten, 15.000 Token überschreiten, zeigt Claude Code eine Warnung beim Start mit der Gesamtanzahl der Token. Kürzen Sie die description-Felder Ihrer Subagenten und verschieben Sie Details in den Systemprompt jedes Subagenten, der nur geladen wird, wenn dieser Subagent ausgeführt wird.

Integrierte Subagenten

Claude Code enthält integrierte Subagenten, die Claude automatisch bei Bedarf verwendet. Jeder erbt die Berechtigungen der übergeordneten Konversation; die meisten werden mit einem eingeschränkten Werkzeugsatz ausgeführt.

Explore und Plan überspringen Ihre CLAUDE.md-Dateien und den Git-Status der übergeordneten Sitzung, um die Recherche schnell und kostengünstig zu halten. Alle anderen integrierten und benutzerdefinierten Subagenten laden beide, es sei denn, ihre Definition setzt das Feld omitClaudeMd, um die Benutzer-, Projekt- und lokalen CLAUDE.md-Dateien zu überspringen. Für die vollständige Aufschlüsselung dessen, was einen Subagenten erreicht, siehe was beim Start geladen wird.

Ein schneller, schreibgeschützter Agent, der für die Suche und Analyse von Codebases optimiert ist.

Modell: Erbt von der Hauptkonversation, begrenzt auf Opus in der Claude API, sodass Explore niemals auf einem teureren Modell ausgeführt wird als dem, das Sie bereits für die Sitzung gewählt haben, es sei denn, Sie setzen CLAUDE_CODE_SUBAGENT_MODEL und erzwingen es auf jeden Subagenten
Werkzeuge: Schreibgeschützte Werkzeuge; Write und Edit sind nicht zulässig
Zweck: Dateiermittlung, Codesuche, Codebase-Exploration

Ab v2.1.198 erbt Explore das Modell der Hauptkonversation, anstatt immer auf Haiku ausgeführt zu werden. In der Claude API ist das geerbte Modell auf Opus begrenzt: Eine Hauptkonversation auf einer höheren Stufe führt Explore auf Opus aus, und eine Hauptkonversation auf Sonnet oder Haiku führt Explore auf demselben Modell aus. Bei jedem anderen Anbieter, wie z. B. Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry oder Claude Platform on AWS, erbt Explore das Modell der Hauptkonversation direkt.

Ein Benutzer- oder Projekt-Subagent mit dem Namen Explore überschreibt den integrierten und behält sein eigenes model-Feld, daher definieren Sie einen mit model: haiku, um die Exploration auf einem kostengünstigeren Modell zu halten.

Claude delegiert an Explore, wenn es eine Codebase durchsuchen oder verstehen muss, ohne Änderungen vorzunehmen. Dies hält Explorationsergebnisse aus Ihrem Hauptkonversationskontext heraus.

Beim Aufrufen von Explore gibt Claude ein Gründlichkeitsniveau an: quick für gezielte Lookups, medium für ausgewogene Exploration oder very thorough für umfassende Analyse.

Ein Forschungsagent, der während des Plan-Modus verwendet wird, um Kontext zu sammeln, bevor ein Plan präsentiert wird.

Modell: Erbt von der Hauptkonversation, es sei denn, Sie setzen CLAUDE_CODE_SUBAGENT_MODEL und erzwingen es auf jeden Subagenten
Werkzeuge: Schreibgeschützte Werkzeuge; Write und Edit sind nicht zulässig
Zweck: Codebase-Recherche für Planung

Wenn Sie sich im Plan-Modus befinden und Claude Ihre Codebase verstehen muss, delegiert es die Recherche an den Plan-Subagenten, damit die Explorationsergebnisse in einem separaten Kontextfenster bleiben, während die Hauptkonversation schreibgeschützt bleibt.

Ein fähiger Agent für komplexe, mehrstufige Aufgaben, die sowohl Exploration als auch Aktion erfordern.

Modell: das CLAUDE_CODE_SUBAGENT_MODEL-Modell, wenn Sie eines setzen und nichts anderes ein Modell auf andere Weise zuweist, ansonsten das Modell der Hauptkonversation; Wählen Sie ein Modell gibt die vollständige Reihenfolge an, und Führen Sie jeden Subagenten auf einem Modell aus zeigt, wie die Variable diese Quellen überschreibt
Werkzeuge: Alle Werkzeuge verfügbar für Subagenten
Zweck: Komplexe Recherche, mehrstufige Operationen, Code-Änderungen

Claude delegiert an general-purpose, wenn die Aufgabe sowohl Exploration als auch Änderung, komplexes Denken zur Interpretation von Ergebnissen oder mehrere abhängige Schritte erfordert.

Claude Code enthält zusätzliche Hilfagenten für spezifische Aufgaben. Diese werden normalerweise automatisch aufgerufen, daher müssen Sie sie nicht direkt verwenden.

Agent	Modell	Wann Claude ihn verwendet
claude	Keines eigenes; folgt der Modellreihenfolge, wenn Claude ihn als Subagenten erzeugt	Wenn eine Aufgabe nicht zu einem spezialisierteren Agent passt. Ein Catch-All mit jedem Werkzeug verfügbar für Subagenten. Auch der Standard-Agent für eine verteilte Hintergrundsitzung; welcher Berechtigungsmodus sie startet, hängt davon ab, wie die Sitzung gestartet wurde
statusline-setup	Sonnet	Wenn Sie `/statusline` ausführen, um Ihre Statuszeile zu konfigurieren
claude-code-guide	Haiku	Wenn Sie Fragen zu Claude Code-Funktionen stellen

Integrierte Subagenten sind in interaktiven Sitzungen standardmäßig registriert. Um sie einzuschränken:

Um einen bestimmten integrierten Typ zu blockieren, fügen Sie ihn zu permissions.deny hinzu, wie in Spezifische Subagenten deaktivieren gezeigt.
Um zu verhindern, dass Claude an einen Subagenten delegiert, verweigern Sie das Agent-Werkzeug selbst mit permissions.deny.
Um nur die integrierten Explore- und Plan-Subagenten zu entfernen, setzen Sie CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude liest und erkundet Dateien direkt, anstatt an sie zu delegieren. Erfordert Claude Code v2.1.198 oder später.
Im nicht-interaktiven Modus und dem Agent SDK setzen Sie CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1, um alle integrierten Typen zu entfernen und nur Ihre eigenen bereitzustellen.

Ein Agent-Werkzeugaufruf, der subagent_type auslässt, schlägt mit subagent_type is required fehl, wenn die Sitzung keinen general-purpose-Subagenten hat, auf den zurückgegriffen werden kann.

Über diese integrierten Subagenten hinaus können Sie Ihre eigenen mit benutzerdefinierten Prompts, Werkzeugbeschränkungen, Berechtigungsmodi, Hooks und Skills erstellen. Die folgenden Abschnitte zeigen, wie Sie anfangen und Subagenten anpassen.

Schnellstart: Erstellen Sie Ihren ersten Subagenten

Subagenten sind Markdown-Dateien mit YAML-Frontmatter. Um einen zu erstellen, bitten Sie Claude, ihn für Sie zu schreiben, oder schreiben Sie die Datei selbst.

Ab v2.1.198 öffnet der /agents-Befehl nicht mehr den interaktiven Erstellungs-Assistenten; das Ausführen gibt eine Erinnerung aus, Claude zu fragen oder .claude/agents/ direkt zu bearbeiten. Subagenten-Dateien, Frontmatter-Felder und die Speicherorte .claude/agents/ und ~/.claude/agents/ bleiben unverändert; nur der Terminal-Assistent wird entfernt.

Diese Anleitung erstellt einen Subagenten auf Benutzerebene, der Code überprüft und Verbesserungen vorschlägt.

Bitten Sie Claude, den Subagenten zu erstellen

Beschreiben Sie in Claude Code den Subagenten, den Sie möchten, und wo Sie ihn speichern möchten:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude schreibt die Datei mit einem name, einer description, einer tools-Liste, einem model und einem Systemprompt.

Überprüfen Sie die Datei

Öffnen Sie ~/.claude/agents/code-improver.md und bestätigen Sie, dass das Frontmatter dem entspricht, was Sie angefordert haben. Das Ergebnis sieht so aus:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Da sich die Datei in ~/.claude/agents/ befindet, ist der Subagent in jedem Projekt auf Ihrem Computer verfügbar. Um ihn stattdessen auf ein Projekt zu beschränken, verschieben Sie ihn in das .claude/agents/-Verzeichnis dieses Projekts. Wählen Sie den Subagenten-Umfang vergleicht die beiden.

Probieren Sie es aus

Bitten Sie Claude, an den neuen Subagenten zu delegieren:

Use the code-improver agent to suggest improvements in this project

Claude delegiert an Ihren neuen Subagenten, der die Codebase durchsucht und Verbesserungsvorschläge zurückgibt. Im Transkript wird die Delegierung als eine Werkzeugaufrufs-Zeile angezeigt, die den Namen des Subagenten gefolgt von einer kurzen Aufgabenbeschreibung zeigt, wie z. B. code-improver(Suggest code improvements).

Wenn Claude den neuen Subagenten nicht finden kann, starten Sie Claude Code neu und versuchen Sie es erneut. Dies geschieht nur, wenn ~/.claude/agents/ vor dem Sitzungsstart nicht vorhanden war, da eine laufende Sitzung ein neu erstelltes agents-Verzeichnis nicht erkennt.

Sie haben jetzt einen Subagenten, den Sie in jedem Projekt auf Ihrem Computer verwenden können, um Codebases zu analysieren und Verbesserungen vorzuschlagen.

Sie können Subagenten-Dateien auch manuell schreiben, sie über CLI-Flags definieren oder sie über Plugins verteilen. Die folgenden Abschnitte behandeln alle Konfigurationsoptionen.

Konfigurieren Sie Subagenten

Der Dateispeicherort eines Subagenten bestimmt, wer darauf zugreifen kann, und sein Frontmatter bestimmt, was er tun kann. Dieser Abschnitt behandelt, wo Subagenten-Dateien gespeichert werden und welche Felder sie unterstützen.

Wählen Sie den Subagenten-Umfang

Speichern Sie Subagenten-Dateien an verschiedenen Orten je nach Umfang. Wenn mehrere Subagenten denselben Namen haben, verwendet Claude Code den aus dem höherrangigen Ort.

Ort	Umfang	Priorität	Wie zu erstellen
Verwaltete Einstellungen	Organisationsweit	1 (höchste)	Bereitgestellt über verwaltete Einstellungen
`--agents` CLI-Flag	Aktuelle Sitzung	2	JSON beim Starten von Claude Code übergeben
`.claude/agents/`	Aktuelles Projekt	3	Claude fragen oder die Datei manuell erstellen
`~/.claude/agents/`	Alle Ihre Projekte	4	Claude fragen oder die Datei manuell erstellen
Plugin-Verzeichnis `agents/`	Wo Plugin aktiviert ist	5 (niedrigste)	Installiert mit Plugins

Projekt-Subagenten (.claude/agents/) sind ideal für Subagenten, die spezifisch für eine Codebase sind. Checken Sie sie in die Versionskontrolle ein, damit Ihr Team sie gemeinsam verwenden und verbessern kann.

Projekt-Subagenten werden durch Aufwärts-Traversierung vom aktuellen Arbeitsverzeichnis entdeckt, sodass jedes .claude/agents/-Verzeichnis zwischen dort und dem Repository-Root gescannt wird. Ab v2.1.178 verwendet Claude Code, wenn mehr als eines dieser verschachtelten Verzeichnisse denselben name definiert, die Definition, die dem Arbeitsverzeichnis am nächsten liegt.

Wenn Sie ein Verzeichnis mit --add-dir oder /add-dir hinzufügen, lädt Claude Code auch seinen .claude/agents/-Ordner zusammen mit Ihren Projekt-Subagenten. Siehe Zusätzliche Verzeichnisse für welche anderen Konfigurationstypen aus --add-dir geladen werden. Um Subagenten über Projekte hinweg zu teilen, ohne --add-dir zu verwenden, nutzen Sie ~/.claude/agents/ oder ein Plugin.

Benutzer-Subagenten (~/.claude/agents/) sind persönliche Subagenten, die in allen Ihren Projekten verfügbar sind.

Claude Code scannt .claude/agents/ und ~/.claude/agents/ rekursiv, sodass Sie Definitionen in Unterordnern wie agents/review/ oder agents/research/ organisieren können. Der Unterverzeichnis-Pfad beeinflusst nicht, wie ein Subagent identifiziert oder aufgerufen wird, da die Identität nur vom name-Frontmatter-Feld stammt.

Halten Sie name-Werte über den gesamten Baum eindeutig: Wenn zwei Dateien unter demselben .claude/agents/-Verzeichnis, einschließlich seiner Unterordner, denselben Namen deklarieren, lädt Claude Code nur eine von ihnen, ausgewählt nach Dateisystem-Lesereihenfolge statt nach dokumentierter Priorität. Über verschachtelte Projekt-Verzeichnisse hinweg gewinnt die Definition, die dem Arbeitsverzeichnis am nächsten liegt, wie oben beschrieben. Die /doctor-Setup-Überprüfung meldet Dateien im selben Verzeichnis, die einen Namen teilen, und schlägt vor, alle außer einer umzubenennen oder zu entfernen. Vor v2.1.205 öffnete /doctor einen Diagnose-Bildschirm, der Duplikate auflistete und zeigte, welche Definition aktiv war.

Plugin-agents/-Verzeichnisse werden ebenfalls rekursiv gescannt. Im Gegensatz zu Projekt- und Benutzer-Umfängen wird ein Unterordner in einem Plugin-agents/-Verzeichnis Teil des scoped identifier: Eine Datei unter agents/review/security.md im Plugin my-plugin registriert sich als my-plugin:review:security.

CLI-definierte Subagenten werden als JSON beim Starten von Claude Code übergeben. Sie existieren nur für diese Sitzung und werden nicht auf der Festplatte gespeichert, was sie für schnelle Tests oder Automatisierungsskripte nützlich macht. Sie können mehrere Subagenten in einem einzigen --agents-Aufruf definieren:

claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}'

claude --agents @'
{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}
'@

Das --agents-Flag akzeptiert JSON mit einem prompt-Feld plus diese Frontmatter-Felder: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, omitClaudeMd und isolation. Verwenden Sie prompt für den Systemprompt, äquivalent zum Markdown-Body in dateibasierten Subagenten.

Jeder Top-Level-Schlüssel im JSON ist der Name des Agenten. Starten Sie einen Namen nicht mit -.

Für das, was Claude Code mit einem Wert tut, den es nicht laden kann, und die Flags und Umgebungsvariable, die diese Überprüfung überspringen, siehe Invalid --agents configuration.

Verwaltete Subagenten werden von Organisationsadministratoren bereitgestellt. Platzieren Sie Markdown-Dateien in .claude/agents/ im Verzeichnis der verwalteten Einstellungen, wobei Sie das gleiche Frontmatter-Format wie bei Projekt- und Benutzer-Subagenten verwenden. Verwaltete Definitionen haben Vorrang vor Projekt- und Benutzer-Subagenten mit demselben Namen.

Plugin-Subagenten stammen von Plugins, die Sie installiert haben. Sie werden automatisch zusammen mit Ihren benutzerdefinierten Subagenten geladen und erscheinen in der @-Erwähnung-Typeahead unter ihrem scoped name. Siehe die Plugin-Komponenten-Referenz für Details zum Erstellen von Plugin-Subagenten.

Subagenten-Definitionen aus einem dieser Umfänge sind auch für Agent-Teams verfügbar: Beim Spawnen eines Teammates können Sie auf einen Subagenten-Typ verweisen, und Claude Code wendet Teile dieser Definition auf den Teammate an. Siehe Agent-Teams für welche Teile in jedem Anzeigemodus gelten.

Schreiben Sie Subagenten-Dateien

Subagenten-Dateien verwenden YAML-Frontmatter für die Konfiguration, gefolgt vom Systemprompt in Markdown:

Note

Claude Code überwacht ~/.claude/agents/ und .claude/agents/. Wenn Sie eine Subagenten-Datei auf der Festplatte hinzufügen oder bearbeiten oder Claude bitten, eine für Sie zu schreiben, erkennt Claude Code die Änderung innerhalb weniger Sekunden und die nächste Delegation verwendet die aktualisierte Definition, ohne dass ein Neustart erforderlich ist.

Drei Fälle erfordern immer noch einen Neustart:

Der Watcher deckt nur Verzeichnisse ab, die beim Sitzungsstart existierten, daher müssen Sie nach dem Erstellen der ersten Agent-Datei eines Umfangs in einem neuen agents-Verzeichnis neu starten, um sie zu laden.
Claude Code überwacht .claude/agents/ nicht in Verzeichnissen, die mit --add-dir oder /add-dir hinzugefügt wurden, daher müssen Sie nach dem Hinzufügen oder Bearbeiten eines Subagenten dort neu starten, um die Änderung zu laden.
Sitzungen, die mit --disable-slash-commands gestartet wurden, überwachen diese Verzeichnisse überhaupt nicht.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Das Frontmatter definiert die Metadaten und Konfiguration des Subagenten. Der Body wird zum Systemprompt, der das Verhalten des Subagenten leitet. Subagenten erhalten nur diesen Systemprompt plus grundlegende Umgebungsdetails wie Arbeitsverzeichnis, nicht den Claude Code-Systemprompt.

Im nicht-interaktiven Modus hängt das Flag --append-subagent-system-prompt den von Ihnen bereitgestellten Text an das Ende des Systemprompts jedes Subagenten an, einschließlich verschachtelter Subagenten, außer einem forked Subagenten, der den Prompt der Konversation selbst wiederverwendet. Erfordert Claude Code v2.1.205 oder später. Wenn Ihr Text zu lang ist, um ihn in der Befehlszeile zu übergeben, speichern Sie ihn in einer Datei und übergeben Sie den Pfad mit --append-subagent-system-prompt-file stattdessen. Das Datei-Flag erfordert Claude Code v2.1.261 oder später.

Ein Subagent startet im aktuellen Arbeitsverzeichnis der Hauptkonversation. Innerhalb eines Subagenten bleiben cd-Befehle nicht zwischen Bash- oder PowerShell-Werkzeugaufrufen bestehen und beeinflussen nicht das Arbeitsverzeichnis der Hauptkonversation. Um dem Subagenten stattdessen eine isolierte Kopie des Repositorys zu geben, setzen Sie isolation: worktree.

Ein Subagent mit isolation: worktree führt seine Bash- und PowerShell-Befehle in seinem Worktree aus. Ein Befehl, dessen Arbeitsverzeichnis sich stattdessen zu Ihrem Haupt-Checkout auflöst, beispielsweise weil das Worktree-Verzeichnis entfernt wurde, während der Subagent lief, schlägt mit einem Fehler fehl. Vor v2.1.203 konnte ein solcher Befehl im Haupt-Checkout ausgeführt werden.

Diese Arbeitsverzeichnis-Überprüfung deckt das gesamte Repository ab, das das Verzeichnis enthält, von dem aus Sie Claude Code gestartet haben. Wenn Ihre Sitzung in einem verknüpften Worktree läuft, deckt die Überprüfung auch den Haupt-Checkout ab, von dem dieser Worktree verknüpft ist. Vor v2.1.210 deckte die Überprüfung nur das Start-Verzeichnis selbst ab. Ein Befehl, dessen Arbeitsverzeichnis sich anderswo im selben Repository auflöste, wie das Repository-Root, wenn Sie Claude Code von einem Monorepo-Unterverzeichnis aus gestartet haben, wurde dort ausgeführt, anstatt zu fehlschlagen.

Für Bash-Befehle überprüft Claude Code auch den Befehl selbst auf zwei Arten:

Es blockiert einen Befehl, der Git in den Haupt-Checkout umleitet.
Es weigert sich, einen Befehl auszuführen, wenn es nicht vom Befehlstext überprüfen kann, dass jedes Git, das der Befehl ausführt, im Worktree bleibt, beispielsweise wenn der Befehlsname zur Laufzeit berechnet wird.

Die Umleitungsvektoren und die Formregeln sind unter Wie Claude Code Isolation erzwingt aufgelistet. PowerShell-Befehle erhalten nur die Arbeitsverzeichnis-Überprüfung.

Monitor-Befehle durchlaufen die gleichen Arbeitsverzeichnis- und Befehlsinhalts-Überprüfungen wie Bash-Befehle.

Wenn die Hauptkonversation selbst isoliert in einem Worktree läuft, wendet Claude Code die gleichen Überprüfungen auf die Sitzung und jeden Subagenten an, den es spawnt, einschließlich Subagenten ohne isolation: worktree; siehe Wie Claude Code Isolation erzwingt.

Unterstützte Frontmatter-Felder

Die folgenden Felder können im YAML-Frontmatter verwendet werden. Nur name und description sind erforderlich.

Feld	Erforderlich	Beschreibung
`name`	Ja	Eindeutige Kennung mit Kleinbuchstaben und Bindestrichen. Hooks erhalten diesen Wert als `agent_type`. Der Dateiname muss nicht übereinstimmen. Namen können kein `:` enthalten, das für Plugin-Umfang-Identifier wie `my-plugin:reviewer` reserviert ist. Claude Code lädt eine Datei, deren Name eins enthält, nicht und protokolliert einen Fehler im Debug-Protokoll. Vor v2.1.218 wurden solche Namen akzeptiert
`description`	Ja	Wann Claude an diesen Subagenten delegieren sollte
`tools`	Nein	Werkzeuge, die der Subagent verwenden kann. Erbt jedes Werkzeug, das für Subagenten verfügbar ist, wenn weggelassen. Wenn kein Eintrag in der Liste sich zu einem Werkzeug auflöst, schlägt der Subagent normalerweise fehl zu starten mit einem Fehler, der die Einträge benennt. Um Skills in den Kontext zu laden, verwenden Sie das `skills`-Feld statt `Skill` hier aufzulisten
`disallowedTools`	Nein	Werkzeuge zum Verweigern, entfernt aus geerbter oder angegebener Liste. Ein Eintrag mit einem Spezifizierer, wie `Bash(git push *)`, entfernt immer noch das ganze Werkzeug
`model`	Nein	Modell zu verwenden: `sonnet`, `opus`, `haiku`, `fable`, eine vollständige Modell-ID wie `claude-opus-5` oder `inherit`. Wenn Sie es weglassen, wählt Claude Code das Modell in der Subagenten-Modell-Reihenfolge
`permissionMode`	Nein	Berechtigungsmodus: `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` oder `manual` als Alias für `default`. Der `manual`-Alias erfordert Claude Code v2.1.200 oder später. Ignoriert für Plugin-Subagenten
`maxTurns`	Nein	Maximale Anzahl von Agenten-Turns, bevor der Subagent stoppt. Wenn der Subagent die Grenze erreicht, gibt Claude Code seine Ausgabe als teilweise markiert zurück, und Claude kann ihn fortsetzen, um fortzufahren. Die teilweise Markierung erfordert Claude Code v2.1.246 oder später
`skills`	Nein	Skills zum Vorausladen in den Kontext des Subagenten beim Start. Der vollständige Skill-Inhalt wird eingespritzt, nicht nur die Beschreibung. Subagenten können weiterhin unlisted Projekt-, Benutzer- und Plugin-Skills durch das Skill-Werkzeug aufrufen
`mcpServers`	Nein	MCP-Server verfügbar für diesen Subagenten. Jeder Eintrag ist entweder ein Servername, der auf einen bereits konfigurierten Server verweist (z. B. `"slack"`) oder eine Inline-Definition mit dem Servernamen als Schlüssel und einer vollständigen MCP-Server-Konfiguration als Wert. Ignoriert für Plugin-Subagenten
`hooks`	Nein	Lifecycle-Hooks mit Umfang auf diesen Subagenten. Ignoriert für Plugin-Subagenten
`memory`	Nein	Persistenter Speicherumfang: `user`, `project` oder `local`. Ermöglicht sitzungsübergreifendes Lernen
`background`	Nein	Auf `true` setzen, um diesen Subagenten im Hintergrund zu halten, auch wenn Claude ihn im Vordergrund ausführen möchte. Wo Fork-Modus aktiviert ist, führt Claude Code die Subagenten, die Claude spawnt, bereits im Hintergrund aus
`omitClaudeMd`	Nein	Auf `true` setzen, um diesen Subagenten ohne die Benutzer-, Projekt- und lokalen CLAUDE.md-Dateien zu starten; verwaltete Richtliniendateien werden immer noch geladen, außer für verwaltete Subagenten. Verwenden Sie es für Subagenten, die alles, was sie benötigen, aus dem Delegationsprompt erhalten. Ignoriert, wenn der Agent als Hauptsitzungs-Agent über `--agent` oder die `agent`-Einstellung läuft. Erfordert Claude Code v2.1.271 oder später
`effort`	Nein	Aufwandsstufe, wenn dieser Subagent aktiv ist. Überschreibt die Aufwandsstufe der Sitzung. Standard: erbt von Sitzung. Optionen: `low`, `medium`, `high`, `xhigh`, `max`; verfügbare Stufen hängen vom Modell ab
`isolation`	Nein	Auf `worktree` setzen, um den Subagenten in einem temporären Git-Worktree auszuführen, was ihm eine isolierte Kopie des Repositorys gibt, die standardmäßig von Ihrem Standard-Branch verzweigt ist, anstatt vom `HEAD` der übergeordneten Sitzung. Der Worktree wird automatisch bereinigt, wenn der Subagent keine Änderungen vornimmt
`color`	Nein	Anzeigefarbe für den Subagenten in der Aufgabenliste und dem Transkript. Akzeptiert `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink` oder `cyan`
`initialPrompt`	Nein	Auto-eingereicht als der erste Benutzer-Turn, wenn dieser Agent als Hauptsitzungs-Agent läuft (über `--agent` oder die `agent`-Einstellung). Befehle und Skills werden verarbeitet. Vorangestellt zu jedem vom Benutzer bereitgestellten Prompt
`experimental`	Nein	Zuordnung experimenteller Optionen. Setzen Sie seinen `cacheTtl`-Schlüssel auf `5m` oder `1h`, um die Prompt-Cache-Lebensdauer für die Anfragen dieses Subagenten zu wählen, an der Stelle des Frontmatters in der Cache-Lebensdauer-Priorität. Claude Code ignoriert jeden anderen Wert, ignoriert `1h`, während Ihr Claude-Abonnement Nutzungsguthaben verwendet, und liest das Feld nur aus Subagenten-Dateien. Erfordert Claude Code v2.1.248 oder später

Schreiben Sie cacheTtl in die experimental-Zuordnung, nicht auf die oberste Ebene des Frontmatters.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

Subagenten-Dateien, die Claude Code überspringt

Claude Code überspringt eine Datei in einem Projekt-, Benutzer- oder verwalteten agents-Verzeichnis oder in einem unter einem Verzeichnis, das Sie mit --add-dir hinzufügen, ohne es in der Sitzung zu melden, wenn das Frontmatter eines dieser Probleme hat:

Kein name: Claude Code behandelt die Datei als Dokumentation, die neben Ihren Agenten aufbewahrt wird.
Ein öffnendes ---, das nicht die erste Zeile der Datei ist: Claude Code liest die Datei als ohne Frontmatter und behandelt sie als Dokumentation.
Ein name, der mit - beginnt oder : enthält: Claude Code überspringt die Datei und schreibt einen Fehler in das Debug-Protokoll. Siehe die name-Zeile in der Tabelle oben.
Ein name, aber keine description: Claude Code überspringt die Datei und schreibt den Grund in das Debug-Protokoll.
YAML, das nicht analysiert wird: Claude Code liest keine Felder aus der Datei, überspringt sie und schreibt den Parse-Fehler in das Debug-Protokoll.

Um das Debug-Protokoll zu sehen, führen Sie Claude Code mit --debug aus.

Ein Plugin-Subagent, dessen Frontmatter kein name hat oder nicht analysiert wird, wird immer noch unter seinem Dateinamen geladen.

Überprüfen Sie ein `agents`-Verzeichnis vor einer Sitzung

Um Dateien in einem agents-Verzeichnis zu finden, deren Frontmatter nicht analysiert wird, führen Sie claude plugin validate gegen das Verzeichnis aus, beispielsweise .claude/agents oder ~/.claude/agents. Claude Code überprüft nur das Verzeichnis, das Sie benennen, und kennzeichnet keine Datei, deren Frontmatter analysiert wird, aber kein name hat. Erfordert Claude Code v2.1.233 oder später.

Wählen Sie ein Modell

Das model-Feld steuert, welches Modell der Subagent verwendet:

Modell-Alias: Verwenden Sie einen der verfügbaren Aliase: sonnet, opus, haiku oder fable
Vollständige Modell-ID: Verwenden Sie eine vollständige Modell-ID wie claude-opus-5 oder claude-sonnet-5. Akzeptiert dieselben Werte wie das --model-Flag
inherit: Verwenden Sie dasselbe Modell wie die Hauptkonversation

Wenn Claude einen Subagenten aufruft, kann es auch einen model-Parameter für diese spezifische Invokation übergeben. Claude Code löst das Modell des Subagenten in dieser Reihenfolge auf:

Der Per-Invokation-model-Parameter
Das model-Frontmatter des Subagenten, wobei inherit das Modell der Hauptkonversation auswählt
Die CLAUDE_CODE_SUBAGENT_MODEL-Umgebungsvariable, wenn Sie sie auf einen Modell-Alias oder eine Modell-ID setzen
Das Modell der Hauptkonversation

Das Setzen von CLAUDE_CODE_SUBAGENT_MODEL allein ändert nicht das Modell, auf dem die integrierten Explore- und Plan-Subagenten laufen. Um es zu ändern, siehe Führen Sie jeden Subagenten auf einem Modell aus.

Vor v2.1.251 kam CLAUDE_CODE_SUBAGENT_MODEL zuerst in dieser Reihenfolge und überschrieb sowohl den Per-Invokation-Parameter als auch das Frontmatter, einschließlich model: inherit.

Das Setzen der Variablen auf inherit ist dasselbe wie das Nichtsetzen. Vor v2.1.196 erzwang dieser Wert Subagenten auf das Modell der Hauptkonversation und ignorierte die anderen Quellen.

Claude Code überprüft die Per-Invokation-Parameter, Frontmatter und Umgebungsvariablenwerte gegen die availableModels-Allowlist Ihrer Organisation. Für einen blockierten Wert ersetzt es ein anderes Modell:

Wenn der blockierte Wert ein Familien-Alias wie opus ist, führt Claude Code den Subagenten auf der neuesten Version dieser Familie aus, die die Allowlist zulässt, und folgt den gleichen Substitutionsregeln und Provider-Umfang wie /model. Vor v2.1.222 führte Claude Code den Subagenten auf dem geerbten Modell für einen blockierten Familien-Alias aus.
Für jeden anderen blockierten Wert, auf Providern, wo diese Substitution nicht funktioniert, oder wenn die Allowlist keine Version der Familie zulässt, führt Claude Code den Subagenten stattdessen auf dem geerbten Modell aus. Wenn Sie CLAUDE_CODE_SUBAGENT_MODEL setzen, versucht Claude Code zuerst dieses Modell unter den gleichen Regeln.

In interaktiven Sitzungen zeigt Claude Code eine Warnung an, die das angeforderte Modell und das Modell benennt, auf dem der Subagent läuft, für beide Substitutionen.

Um zu überprüfen, auf welchem Modell ein Subagent läuft, führen Sie /tasks aus. Claude Code benennt das Modell in der Zeile des Subagenten und fügt die Aufwandsstufe hinzu, wenn die Definition des Subagenten oder der Skill, von dem er geforkt wurde, effort setzt. Erfordert Claude Code v2.1.242 oder später.

Ein Per-Invokation-model-Parameter gilt auch, wenn der Subagent fortgesetzt oder eine Folgenachricht gesendet wird, sodass der Subagent auf diesem Modell bleibt. Vor v2.1.211 ließ das Fortsetzen den Per-Invokation-Wert fallen und der Subagent kehrte zu seinem model-Feld oder, ohne einen, zum Modell der Hauptkonversation zurück.

Ab v2.1.198 erben Subagenten auch die Extended Thinking-Konfiguration der Hauptkonversation: Wenn Thinking in Ihrer Sitzung aktiviert ist, ist es für den Subagenten aktiviert, und wenn es deaktiviert ist, bleibt es deaktiviert. Es gibt keine Pro-Subagenten-Thinking-Einstellung. Vor v2.1.198 liefen Subagenten mit deaktiviertem Extended Thinking, unabhängig von der Einstellung der Hauptkonversation.

Führen Sie jeden Subagenten auf einem Modell aus

CLAUDE_CODE_SUBAGENT_MODEL ist ein Standard, daher hat die Definition eines Subagenten oder ein Modell, das Claude übergibt, immer noch Vorrang vor ihm. Um ein Modell auf jeden Subagenten, Teammate und Workflow-Agent anzuwenden, setzen Sie auch CLAUDE_CODE_SUBAGENT_MODEL_FORCE auf 1. Erfordert Claude Code v2.1.257 oder später.

Wenn Sie beide Variablen setzen, laufen Subagenten auf dem Modell in CLAUDE_CODE_SUBAGENT_MODEL.
Wenn Sie nur CLAUDE_CODE_SUBAGENT_MODEL_FORCE setzen, laufen Subagenten auf dem Modell der Hauptkonversation.

Um beispielsweise jeden Subagenten auf Haiku auszuführen, setzen Sie beide Variablen im env-Block einer Einstellungsdatei:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Um zu überprüfen, dass die Einstellung wirksam wurde, führen Sie /tasks aus, während ein Subagent läuft. Die Zeile des Subagenten zeigt das Modell, auf dem er läuft.

Während CLAUDE_CODE_SUBAGENT_MODEL_FORCE aktiviert ist, ignoriert Claude Code das model-Feld jeder Subagenten-Definition, einschließlich der integrierten Explore- und Plan-Subagenten, und Claude kann kein Modell übergeben, wenn es einen Subagenten startet. Zwei Arten von Subagenten laufen immer noch auf dem Modell der Hauptkonversation:

Ein Fork
Ein Skill, der in einem Subagenten läuft mit model: inherit

Wenn Sie nur CLAUDE_CODE_SUBAGENT_MODEL_FORCE setzen, behält der integrierte Explore-Subagent seine Modell-Obergrenze.

Kontrollieren Sie Subagenten-Fähigkeiten

Sie können kontrollieren, was Subagenten durch Werkzeugzugriff, Berechtigungsmodi und bedingte Regeln tun können.

Verfügbare Werkzeuge

Subagenten erben die integrierten Werkzeuge und MCP-Werkzeuge, die in der Hauptkonversation verfügbar sind, eingeengt durch zwei Filter: Der erste entfernt eine kurze Liste von Werkzeugen aus jedem Subagenten, und der zweite reduziert den integrierten Werkzeugsatz für Subagenten, die im Hintergrund laufen, was der Standard ist. Auf macOS, Linux und WSL kann ein Subagent auch die Glob- und Grep-Werkzeuge erhalten, wenn die Hauptkonversation sie nicht hat, wie unter Glob-Werkzeugverhalten beschrieben. Forks überspringen beide Filter und erhalten den genauen Werkzeugpool der Hauptkonversation. Der erste Filter entfernt diese Werkzeuge, auch wenn sie im tools-Feld aufgelistet sind:

Agent, wenn der Subagent die Tiefengrenze erreicht hat; in einem Fork bleibt das Werkzeug aufgelistet, gibt aber stattdessen einen Fehler zurück
AskUserQuestion
EndConversation, das nur die Hauptkonversation beenden kann; siehe EndConversation-Werkzeugverhalten
EnterPlanMode
ExitPlanMode, es sei denn, der permissionMode des Subagenten ist plan
ScheduleWakeup
TaskOutput
WaitForMcpServers
Workflow

Der zweite Filter gilt für Subagenten, die im Hintergrund laufen. Abgesehen von Agent und ExitPlanMode, die den Bedingungen des ersten Filters folgen, wo immer der Subagent läuft, behält ein Hintergrund-Subagent jedes MCP-Werkzeug, aber nur diese integrierten Werkzeuge: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage und Artifact, plus SubagentHandback für einen Subagenten, der durch ihn berichtet. Claude Code entfernt jedes andere integrierte Werkzeug aus einem Hintergrund-Subagenten, ob geerbt oder im tools-Feld aufgelistet, sodass die gleiche Definition zu verschiedenen Werkzeugen im Vordergrund und im Hintergrund führen kann. Die Entfernung meldet keinen Fehler, es sei denn, sie hinterlässt die tools-Liste aufgelöst zu nichts.

ListAgents folgt diesen Filtern wie jedes integrierte Werkzeug: Ein Vordergrund-Subagent erbt es in Sitzungen, wo sitzungsübergreifendes Messaging aktiviert ist, und ein Hintergrund-Subagent behält es nicht.

Teammates in Agent-Teams behalten zusätzlich die Task-Werkzeuge und Cron-Werkzeuge: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete und CronList.

In einer Sitzung ohne die Task-Werkzeuge stellt Claude Code die Task-Werkzeuge auch nicht für Subagenten bereit, auch wenn der Subagent ein anderes Modell ausführt. Ein In-Process-Teammate folgt Ihrer Sitzung auf die gleiche Weise, während ein Teammate in seinem eigenen Split-Pane als separater Claude Code-Prozess läuft, sodass sein eigenes Modell entscheidet.

Um Werkzeuge einzuschränken, verwenden Sie das tools-Feld als Allowlist oder das disallowedTools-Feld als Denylist. Dieses Beispiel verwendet tools, um ausschließlich Read, Grep, Glob und Bash zuzulassen. Der Subagent kann keine Dateien bearbeiten, keine Dateien schreiben oder MCP-Werkzeuge verwenden:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Dieses Beispiel verwendet disallowedTools, um alle verfügbaren Werkzeuge außer Write und Edit zu erben. Der Subagent behält Bash, MCP-Werkzeuge und den Rest seines Pools:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Wenn beide gesetzt sind, wird disallowedTools zuerst angewendet, dann wird tools gegen den verbleibenden Pool aufgelöst. Ein Werkzeug, das in beiden aufgelistet ist, wird entfernt.

Wenn nichts in der tools-Liste sich zu einem Werkzeug auflöst, beispielsweise weil jeder Eintrag falsch geschrieben ist oder ein Werkzeug benennt, das nicht für Subagenten verfügbar ist, weigert sich Claude Code normalerweise, den Subagenten zu starten, und das Agent-Werkzeug gibt einen Fehler zurück, der die ungelösten Einträge benennt; siehe Agent würde mit null Werkzeugen gespawnt für die Nachricht und wie man jeden Eintrag behebt. Vor v2.1.208 startete dieser Subagent mit keinen Werkzeugen und konnte ein leeres oder verwirrendes Ergebnis zurückgeben.

Beide Felder akzeptieren MCP-Server-Level-Muster zusätzlich zu exakten Werkzeugnamen: mcp__<server> oder mcp__<server>__* gewährt oder entfernt jedes Werkzeug vom benannten Server. In disallowedTools entfernt mcp__* auch jedes MCP-Werkzeug von jedem Server. Dieses Beispiel entfernt jedes Werkzeug vom github MCP-Server, während Werkzeuge von anderen Servern und die integrierten Werkzeuge in seinem Pool beibehalten werden:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

Ein disallowedTools-Eintrag mit einem Spezifizierer, wie Bash(git push *), entfernt immer noch das ganze Werkzeug aus dem Subagenten, nicht nur die übereinstimmenden Befehle. Um Bash zu behalten und bestimmte Befehle zu blockieren, fügen Sie eine Bash-Ablehnungsregel wie Bash(git push *) zu permissions.deny in Ihren Einstellungen hinzu. Die Regel gilt für die Hauptkonversation und für Subagenten.

Beschränken Sie, welche Subagenten gespawnt werden können

Wenn ein Agent als Hauptthread mit claude --agent läuft, kann er Subagenten mit dem Agent-Werkzeug spawnen. Um zu beschränken, welche Subagenten-Typen er spawnen kann, verwenden Sie die Agent(agent_type)-Syntax im tools-Feld.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Dies ist eine Allowlist: Nur die worker- und researcher-Subagenten können gespawnt werden. Wenn der Agent versucht, einen anderen Typ zu spawnen, schlägt die Anfrage fehl und der Agent sieht nur die zulässigen Typen in seinem Prompt. Um bestimmte Agenten zu blockieren und alle anderen zuzulassen, verwenden Sie stattdessen permissions.deny.

Um das Spawnen eines beliebigen Subagenten ohne Einschränkungen zu ermöglichen, verwenden Sie Agent ohne Klammern:

tools: Agent, Read, Bash

Wenn Agent vollständig aus der tools-Liste weggelassen wird, kann der Agent keine Subagenten spawnen.

Die Agent(agent_type)-Allowlist-Syntax gilt nur für einen Agent, der als Hauptthread mit claude --agent läuft. In einer Subagenten-Definition ermöglicht das Auflisten von Agent in tools diesem Subagenten, Subagenten zu spawnen, während die Tiefengrenze es zulässt, aber jede Typenliste in den Klammern wird ignoriert.

Umfang von MCP-Servern auf einen Subagenten

Verwenden Sie das mcpServers-Feld, um einem Subagenten Zugriff auf MCP-Server zu geben, die in der Hauptkonversation nicht verfügbar sind. Inline-Server, die hier definiert sind, werden verbunden, wenn der Subagent startet, unter Beachtung der Vertrauensregel für den Ordner der Agent-Datei, und getrennt, wenn er endet. String-Verweise teilen die Verbindung der übergeordneten Sitzung.

Jeder Eintrag in der Liste ist entweder eine Inline-Server-Definition oder ein String, der auf einen bereits konfigurierten MCP-Server in Ihrer Sitzung verweist:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Inline-Definitionen verwenden das gleiche Schema wie .mcp.json-Server-Einträge, mit dem Servernamen als Schlüssel, und unterstützen die Typen stdio, http, sse und ws.

Um einen MCP-Server vollständig aus der Hauptkonversation herauszuhalten und zu vermeiden, dass seine Werkzeugbeschreibungen dort Kontext verbrauchen, definieren Sie ihn inline hier statt in .mcp.json. Der Subagent erhält die Werkzeuge; die übergeordnete Konversation nicht.

Claude Code lädt einen Inline-Server aus einer Agent-Datei in Ihrem Projekt-.claude/agents/-Verzeichnis oder in einem --add-dir-Verzeichnis-.claude/agents/ nur, nachdem Sie dem Ordner vertrauen, aus dem die Agent-Datei stammt. Vor v2.1.238 lud Claude Code diese Server ohne Vertrauensprüfung.

Vertrauen, das nicht zählt: Vertrauen eines übergeordneten Ordners und das automatische Vertrauen, das eine -p- oder SDK-Sitzung für Hooks in Einstellungsdateien erhält
Bis dahin: Claude Code überspringt jeden Inline-Server in dieser Agent-Datei und schreibt den genauen projects["<path>"].hasTrustDialogAccepted-Schlüssel für ~/.claude.json in das Debug-Protokoll
--add-dir-Verzeichnisse: Ein Verzeichnis außerhalb des Repositorys Ihres vertrauenswürdigen Arbeitsbereichs benötigt seinen eigenen Vertrauenseintrag, da seine .claude/agents/-Dateien das Vertrauen Ihres Arbeitsbereichs nicht erben

Claude Code lädt zwei Arten von Servern ohne Vertrauensprüfung für den Ordner, aus dem die Agent-Datei stammt:

Ein Name, der auf einen bereits konfigurierten Server verweist
Ein Inline-Server in einer Agent-Datei aus ~/.claude/agents/, in einer, die Sie mit --agents oder der SDK-Option agents übergeben, oder in einer, die verwaltete Einstellungen liefern

Ab v2.1.153 gelten die MCP-Einschränkungen, die für die Hauptsitzung gelten, auch für Server, die im Subagenten-Frontmatter deklariert sind:

Wenn einer dieser Punkte einen Server blockiert, überspringt Claude Code ihn und zeigt eine Warnung mit den Namen der blockierten Server an.

Verwaltete Einstellungseinschränkungen gelten für jeden Subagenten, unabhängig davon, wie er definiert ist. --strict-mcp-config filtert keine Server, die Sie inline über --agents oder die SDK-Option agents übergeben, da diese explizite Eingaben des Aufrufers sind.

Berechtigungsmodi

Setzen Sie permissionMode, um den Berechtigungsmodus zu wählen, in dem ein Subagent läuft. Verwenden Sie die Konfigurationswerte der Modi, daher ist der Manuelle Modus default. Wenn Sie ihn nicht setzen, erbt der Subagent den Modus der Hauptkonversation, der als Auto-Modus auf Pro-, Max- und Team-Plänen beginnt, es sei denn, Ihre Einstellungen oder Ihre Organisation ändern ihn.

Die Hauptkonversation's Berechtigungsmodus entscheidet, ob Claude Code den Wert verwendet, den Sie setzen:

Wenn die Hauptkonversation in bypassPermissions, acceptEdits oder Auto-Modus ist, läuft der Subagent in diesem gleichen Modus und Claude Code ignoriert den permissionMode, den Sie setzen. Unter Auto-Modus bewertet der Klassifizierer die Werkzeugaufrufe des Subagenten mit den Block- und Zulassungsregeln der Hauptkonversation. Wenn der Subagent endet, überprüft der Klassifizierer auch seine Arbeit und seinen endgültigen Bericht, bevor der Bericht geliefert wird, wie Wie Auto-Modus Subagenten handhabt beschreibt.
Wenn die Hauptkonversation in default, dontAsk oder plan Modus ist, läuft der Subagent in dem Berechtigungsmodus, den Sie setzen, außer bypassPermissions. Ein Subagent, der bypassPermissions deklariert, behält stattdessen den Modus der Hauptkonversation. Die bypassPermissions-Ausnahme erfordert Claude Code v2.1.267 oder später.

permissionMode akzeptiert diese Werte und manual als Alias für default:

Modus	Verhalten
`default`	Manueller Modus: fordert Berechtigung an
`acceptEdits`	Auto-Akzeptanz von Dateibearbeitungen und häufigen Dateisystem-Befehlen für Pfade im Arbeitsverzeichnis oder `additionalDirectories`
`auto`	Auto-Modus: ein Hintergrund-Klassifizierer überprüft Befehle und Schreibvorgänge in geschützten Verzeichnissen
`dontAsk`	Auto-Ablehnung von Berechtigungsaufforderungen. Explizit zulässige Werkzeuge funktionieren weiterhin; `AskUserQuestion`, MCP-Werkzeuge, die mit `requiresUserInteraction` gekennzeichnet sind, und Connector-Werkzeuge die Ihre Organisation auf `ask` gesetzt hat in Sitzungen, wo diese Einstellung Claude Code erreicht, werden verweigert, auch wenn Sie sie zugelassen haben
`bypassPermissions`	Alle Berechtigungsprüfungen überspringen. Ein Subagent läuft in diesem Modus nur, wenn die Hauptkonversation es tut
`plan`	Plan-Modus (schreibgeschützte Exploration)

Laden Sie Skills in Subagenten vor

Verwenden Sie das skills-Feld, um Skill-Inhalte beim Start in den Kontext eines Subagenten einzuspeisen. Dies gibt dem Subagenten Domänenwissen, ohne dass er Skills während der Ausführung entdecken und laden muss.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Der vollständige Inhalt jedes aufgelisteten Skills wird in den Kontext des Subagenten eingespritzt. Dieses Feld steuert, welche Skills vorausgeladen werden, nicht welche Skills der Subagent zugreifen kann: ohne es kann der Subagent weiterhin Projekt-, Benutzer- und Plugin-Skills durch das Skill-Werkzeug während der Ausführung entdecken und aufrufen. Um einen Subagenten daran zu hindern, Skills überhaupt aufzurufen, lassen Sie Skill aus der tools-Liste weg oder fügen Sie es zu disallowedTools hinzu.

Sie können keine Skills vorausladen, die disable-model-invocation: true setzen, da das Vorausladen aus dem gleichen Satz von Skills stammt, die Claude aufrufen kann. Dies schließt den gebündelten /verify-Skill ein: Nur Sie können ihn ausführen, daher kann er auch nicht vorausgeladen werden.

Wenn ein aufgelisteter Skill fehlt oder deaktiviert ist, beispielsweise durch die Richtlinie Ihrer Organisation, überspringt Claude Code ihn und protokolliert eine Warnung im Debug-Protokoll.

Aktivieren Sie persistenten Speicher

Das memory-Feld gibt dem Subagenten ein persistentes Verzeichnis, das über Konversationen hinweg bestehen bleibt. Der Subagent verwendet dieses Verzeichnis, um im Laufe der Zeit Wissen aufzubauen, wie z. B. Codebase-Muster, Debugging-Erkenntnisse und architektonische Entscheidungen.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Wählen Sie einen Umfang basierend darauf, wie breit der Speicher angewendet werden sollte:

Umfang	Ort	Verwenden Sie, wenn
`user`	`~/.claude/agent-memory/<name-of-agent>/`	der Subagent Erkenntnisse über alle Projekte hinweg merken sollte
`project`	`.claude/agent-memory/<name-of-agent>/`	das Wissen des Subagenten projektspezifisch ist und über Versionskontrolle teilbar ist
`local`	`.claude/agent-memory-local/<name-of-agent>/`	das Wissen des Subagenten projektspezifisch ist, aber nicht in die Versionskontrolle eingecheckt werden sollte

Subagenten-Speicher ist Teil des Auto-Speichers: Wenn Sie Auto-Speicher mit der autoMemoryEnabled-Einstellung oder CLAUDE_CODE_DISABLE_AUTO_MEMORY ausschalten, hat das memory-Feld keine Auswirkung und der Subagent startet ohne die Speicheranweisungen oder den Speicher-Werkzeugzugriff, der unten beschrieben ist.

Wenn der Speicher aktiviert ist:

Der Systemprompt des Subagenten enthält Anweisungen zum Lesen und Schreiben in das Speicherverzeichnis.
Der Systemprompt des Subagenten enthält auch die ersten 200 Zeilen oder 25 KB von MEMORY.md im Speicherverzeichnis, je nachdem, was zuerst kommt, mit Anweisungen zur Verwaltung von MEMORY.md, wenn es diese Grenze überschreitet.
Read-, Write- und Edit-Werkzeuge werden automatisch aktiviert, damit der Subagent seine Speicherdateien verwalten kann.

Tipps zum persistenten Speicher

project ist der empfohlene Standard-Umfang. Es macht Subagenten-Wissen über Versionskontrolle teilbar.
Bitten Sie den Subagenten, seinen Speicher vor dem Start zu konsultieren: "Review this PR, and check your memory for patterns you've seen before."
Bitten Sie den Subagenten, seinen Speicher nach Abschluss einer Aufgabe zu aktualisieren: "Now that you're done, save what you learned to your memory." Im Laufe der Zeit baut dies eine Wissensdatenbank auf, die den Subagenten effektiver macht.

Fügen Sie Speicheranweisungen direkt in die Markdown-Datei des Subagenten ein, damit er proaktiv seine eigene Wissensdatenbank verwaltet:

Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

Bedingte Regeln mit Hooks

Für dynamischere Kontrolle über die Werkzeugnutzung verwenden Sie PreToolUse-Hooks, um Operationen vor ihrer Ausführung zu validieren. Dies ist nützlich, wenn Sie einige Operationen eines Werkzeugs zulassen möchten, während Sie andere blockieren.

Dieses Beispiel erstellt einen Subagenten, der nur schreibgeschützte Datenbankabfragen zulässt. Der PreToolUse-Hook führt das in command angegebene Skript vor jeder Bash-Befehlsausführung aus:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code übergibt Hook-Eingabe als JSON über stdin an Hook-Befehle. Das Validierungsskript liest dieses JSON, extrahiert den Bash-Befehl und beendet mit Code 2, um Schreibvorgänge zu blockieren:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

Auf macOS und Linux machen Sie das Skript ausführbar, oder der Hook schlägt fehl, anstatt etwas zu blockieren:

chmod +x ./scripts/validate-readonly-query.sh

Um die Regel zu testen, bitten Sie den Subagenten, eine UPDATE-Anweisung auszuführen: Das Skript beendet sich mit Code 2, Claude Code blockiert den Befehl, und der Subagent sieht die Nachricht Blocked: Only SELECT queries are allowed.

Siehe Hook-Eingabe für das vollständige Eingabeschema und Exit-Codes für die Auswirkungen von Exit-Codes auf das Verhalten. Unter Windows schreiben Sie Hook-Skripte in PowerShell und fügen Sie shell: powershell zum Hook-Eintrag hinzu, wie in Ausführen von Hooks in PowerShell gezeigt.

Deaktivieren Sie spezifische Subagenten

Sie können verhindern, dass Claude bestimmte Subagenten verwendet, indem Sie sie zum deny-Array in Ihren Einstellungen hinzufügen. Verwenden Sie das Format Agent(subagent-name), wobei subagent-name dem name-Feld des Subagenten entspricht.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Dies funktioniert für integrierte und benutzerdefinierte Subagenten. Sie können auch das --disallowedTools-CLI-Flag verwenden:

claude --disallowedTools "Agent(Explore)"

Siehe Berechtigungsdokumentation für weitere Details zu Berechtigungsregeln.

Definieren Sie Hooks für Subagenten

Subagenten können Hooks definieren, die während des Lebenszyklus des Subagenten ausgeführt werden. Es gibt zwei Möglichkeiten, Hooks zu konfigurieren:

Im Frontmatter des Subagenten: Definieren Sie Hooks, die nur ausgeführt werden, während dieser Subagent aktiv ist
In settings.json: Definieren Sie Hooks auf Sitzungsebene, die auch in Subagenten ausgelöst werden. Tool-Ereignisse wie PreToolUse und PostToolUse werden für die Werkzeugaufrufe des Subagenten auf die gleiche Weise ausgelöst wie in der Hauptkonversation, und SubagentStart und SubagentStop werden ausgelöst, wenn ein Subagent startet oder endet

Hooks aus Einstellungsdateien, verwalteten Richtlinieneinstellungen und Plugins gelten alle in Subagenten, daher wird ein PreToolUse-Hook in settings.json auch vor jedem Werkzeug ausgeführt, das ein Subagent verwendet.

Hooks im Subagenten-Frontmatter

Definieren Sie Hooks direkt in der Markdown-Datei des Subagenten. Diese Hooks werden nur ausgeführt, während dieser spezifische Subagent aktiv ist, und werden bereinigt, wenn er endet.

Um Frontmatter-Hooks eines Subagenten auf Projektebene auszuführen, akzeptieren Sie den Arbeitsbereichs-Vertrauensdialog für den Ordner, der die Agent-Datei enthält. Hooks von Benutzer-Subagenten in ~/.claude/agents/ und von Definitionen, die Sie mit --agents übergeben, werden ohne diesen Schritt ausgeführt. Wenn Sie einen Ordner mit --add-dir von außerhalb des Repositorys Ihres vertrauenswürdigen Arbeitsbereichs hinzugefügt haben, vertrauen Sie diesem Ordner separat: Seine .claude/agents/-Hooks erben das Vertrauen Ihres Arbeitsbereichs nicht.

Bis Sie dem Ordner vertrauen, wird der Subagent immer noch ausgeführt, aber Claude Code überspringt seine Frontmatter-Hooks und protokolliert einen Fehler im Debug-Protokoll, der erklärt, wie man dem Ordner vertraut. Dies ist eine strengere Regel als die für Hooks in Einstellungsdateien: Das Vertrauen eines übergeordneten Ordners ist nicht ausreichend, und eine -p-Sitzung zählt nicht als vertrauenswürdig. Was vor dem Vertrauen eines Ordners ausgeführt wird vergleicht die beiden. Vor v2.1.218 konnten Frontmatter-Hooks aus Ordnern ausgeführt werden, denen Sie nicht vertraut haben, auch in nicht-interaktiven Sitzungen.

Alle Hook-Ereignisse werden unterstützt. Die häufigsten Ereignisse für Subagenten sind:

Ereignis	Matcher-Eingabe	Wann es ausgelöst wird
`PreToolUse`	Werkzeugname	Bevor der Subagent ein Werkzeug verwendet
`PostToolUse`	Werkzeugname	Nachdem der Subagent ein Werkzeug verwendet hat
`Stop`	(keine)	Wenn der Subagent endet (wird zur Laufzeit in `SubagentStop` konvertiert)

Dieses Beispiel validiert Bash-Befehle mit dem PreToolUse-Hook und führt einen Linter nach Dateibearbeitungen mit PostToolUse aus:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Wenn der Agent als Subagent aufgerufen wird, werden Stop-Hooks im Frontmatter automatisch in SubagentStop-Ereignisse konvertiert.

Hooks auf Projektebene für Subagenten-Ereignisse

Konfigurieren Sie Hooks in settings.json, die auf Subagenten-Lebenszyklus-Ereignisse in der Hauptsitzung reagieren.

Ereignis	Matcher-Eingabe	Wann es ausgelöst wird
`SubagentStart`	Agent-Typname	Wenn ein Subagent mit der Ausführung beginnt
`SubagentStop`	Agent-Typname	Wenn ein Subagent abgeschlossen ist

Beide Ereignisse unterstützen Matcher, um bestimmte Agent-Typen nach Name zu adressieren. Der Matcher-Wert ist der name des Frontmatters des Agenten für Projekt- und Benutzer-Subagenten oder der Plugin-Umfang-Identifier wie my-plugin:db-agent für Plugin-Subagenten. Ein Umfang-Name enthält einen Doppelpunkt, daher wird er als unverankerte reguläre Ausdrücke ausgewertet; verankern Sie ihn mit ^ und $, wie in ^my-plugin:db-agent$, um nur diesen Agent zu treffen.

Dieses Beispiel führt ein Setup-Skript nur aus, wenn der db-agent-Subagent startet, und ein Cleanup-Skript, wenn ein beliebiger Subagent stoppt:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Ein Matcher mit Bindestrichen wie db-agent passt genau auf Claude Code v2.1.195 oder später. In früheren Versionen wird er als unverankerte reguläre Ausdrücke ausgewertet und wird auch für jeden Agent-Typ ausgelöst, der ihn enthält, wie prod-db-agent; verankern Sie ihn als ^db-agent$ in diesen Versionen.

Siehe Hooks für das vollständige Hook-Konfigurationsformat.

Mit Subagenten arbeiten

Automatische Delegierung verstehen

Claude delegiert Aufgaben automatisch basierend auf der Aufgabenbeschreibung in Ihrer Anfrage, dem Feld description in Subagenten-Konfigurationen und dem aktuellen Kontext. Um proaktive Delegierung zu fördern, fügen Sie Phrasen wie „use proactively" in das Beschreibungsfeld Ihres Subagenten ein.

Halten Sie Beschreibungen kurz: Claude Code zeigt eine Startwarnmeldung an, wenn die kombinierten Beschreibungen Ihrer Subagenten das Limit von 15.000 Token überschreiten, und lädt dennoch jeden Subagenten.

Subagenten explizit aufrufen

Wenn automatische Delegierung nicht ausreicht, können Sie einen Subagenten selbst anfordern. Drei Muster eskalieren von einem einmaligen Vorschlag zu einem sitzungsweiten Standard:

Natürliche Sprache: Nennen Sie den Subagenten in Ihrer Eingabeaufforderung; Claude entscheidet, ob delegiert werden soll
@-Erwähnung: Garantiert, dass der Subagent für eine Aufgabe ausgeführt wird
Sitzungsweit: Die gesamte Sitzung verwendet die Systemeingabeaufforderung, Werkzeugbeschränkungen und das Modell dieses Subagenten über das Flag --agent oder die Einstellung agent

Für natürliche Sprache gibt es keine spezielle Syntax. Nennen Sie den Subagenten und Claude delegiert normalerweise:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

Erwähnen Sie den Subagenten mit @. Geben Sie @ ein und wählen Sie den Subagenten aus der Typvorhersage aus, genauso wie Sie Dateien mit @ erwähnen. Dies stellt sicher, dass dieser spezifische Subagent ausgeführt wird, anstatt die Wahl Claude zu überlassen:

@"code-reviewer (agent)" look at the auth changes

Ihre vollständige Nachricht geht immer noch an Claude, der die Aufgabeneingabeaufforderung des Subagenten basierend auf Ihrer Anfrage schreibt. Die @-Erwähnung steuert, welcher Subagent Claude aufruft, nicht welche Eingabeaufforderung er erhält.

Subagenten, die von einem aktivierten Plugin bereitgestellt werden, erscheinen in der Typvorhersage unter ihrem Bereichsnamen, z. B. my-plugin:code-reviewer oder my-plugin:review:security, wenn das Plugin Agenten in Unterordnern organisiert. Benannte Hintergrund-Subagenten, die derzeit in der Sitzung ausgeführt werden, erscheinen auch in der Typvorhersage und zeigen ihren Status neben dem Namen an.

Sie können die Erwähnung auch manuell eingeben, ohne die Auswahl zu verwenden: @agent-<name> für lokale Subagenten oder @agent- gefolgt vom Bereichsnamen für Plugin-Subagenten, z. B. @agent-my-plugin:code-reviewer. Während Sie dieses Formular eingeben, zeigt die Typvorhersage Dateienübereinstimmungen anstelle von Agenten. Die Agent-Erwähnung wird trotzdem aufgelöst, wenn Sie absenden.

Führen Sie die gesamte Sitzung als Subagent aus. Übergeben Sie --agent <name>, um eine Sitzung zu starten, in der der Hauptthread selbst die Systemeingabeaufforderung, Werkzeugbeschränkungen und das Modell dieses Subagenten übernimmt:

claude --agent code-reviewer

Die Systemeingabeaufforderung des Subagenten ersetzt die Standard-Claude-Code-Systemeingabeaufforderung vollständig, genauso wie --system-prompt es tut. CLAUDE.md-Dateien und Projektgedächtnis werden immer noch durch den normalen Nachrichtenfluss geladen, auch wenn die Agent-Definition omitClaudeMd setzt.

Der Agent-Name erscheint als @<name> in der Startkopfzeile, damit Sie bestätigen können, dass er aktiv ist.

Dies funktioniert mit integrierten und benutzerdefinierten Subagenten, und die Wahl bleibt bestehen, wenn Sie die Sitzung fortsetzen: Claude Code stellt die Werkzeugbeschränkungen und das Modell des Agenten zusammen mit der Konversation wieder her. Wenn der Agent nicht mehr vorhanden ist, wenn Sie fortsetzen, wird die Sitzung mit den Standardwerkzeugen fortgesetzt und zeigt eine Warnung mit dem Namen des Agenten. Für die Systemeingabeaufforderung in beiden Fällen siehe Systemeingabeaufforderungs-Flags in fortgesetzten Konversationen.

Für einen von einem Plugin bereitgestellten Subagenten können Sie nur den Agent-Namen übergeben und Claude Code findet ihn:

claude --agent security-reviewer

Wenn mehrere Plugins Agenten mit demselben Namen bereitstellen, übergeben Sie den Bereichsnamen zur Disambiguierung:

claude --agent my-plugin:security-reviewer

Wenn das Plugin den Agenten in einem Unterordner seines agents/-Verzeichnisses platziert, fügen Sie den Unterordner in den Bereichsnamen ein, z. B. claude --agent my-plugin:review:security.

Um es zum Standard für jede Sitzung in einem Projekt zu machen, setzen Sie agent in .claude/settings.json:

{
  "agent": "code-reviewer"
}

Das CLI-Flag überschreibt die Einstellung, wenn beide vorhanden sind.

Subagenten im Vordergrund oder Hintergrund ausführen

Subagenten können im Vordergrund oder im Hintergrund ausgeführt werden:

Vordergrund-Subagenten blockieren die Hauptkonversation bis zur Fertigstellung. Genehmigungseingabeaufforderungen werden an Sie weitergeleitet, wenn sie auftauchen.
Hintergrund-Subagenten werden gleichzeitig ausgeführt, während Sie weiterarbeiten. Wenn ein Hintergrund-Subagent einen Werkzeugaufruf erreicht, der eine Genehmigung benötigt, zeigt Claude Code die Eingabeaufforderung in Ihrer Hauptsitzung an und nennt den Subagenten, der fragt. Genehmigen Sie, um den Subagenten fortsetzen zu lassen, oder drücken Sie Esc, um diesen einen Werkzeugaufruf zu verweigern, ohne den Subagenten zu stoppen. Vor v2.1.186 verweigerten Hintergrund-Subagenten automatisch jeden Werkzeugaufruf, der eine Eingabeaufforderung verursacht hätte.

Für jeden Subagenten, den Claude mit dem Agent-Werkzeug spawnt, wählt Claude Code Vordergrund oder Hintergrund aus dem ersten dieser Fälle, der zutrifft:

Wenn ein In-Process-Agent-Team-Teamkollege den Subagenten spawnte, führt Claude Code ihn im Vordergrund aus. Claude Code weigert sich mit einem Fehler, einen Teamkollegen-Subagenten zu spawnen, dessen Definition background: true setzt. Wenn Fork-Modus aus ist und Sie Hintergrund-Aufgaben nicht ausgeschaltet haben, weigert sich Claude Code auch mit einem Fehler, wenn ein Teamkollege run_in_background: true setzt.
Wenn Sie CLAUDE_CODE_DISABLE_BACKGROUND_TASKS auf 1 setzen, führt Claude Code den Subagenten im Vordergrund aus, in jeder Art von Sitzung und unabhängig davon, ob Fork-Modus an ist.
Wenn Fork-Modus an ist, wie es standardmäßig in einer interaktiven Sitzung der Fall ist, führt Claude Code den Subagenten im Hintergrund aus, sowohl Fork- als auch Non-Fork-Subagenten, und Claude kann nicht den Vordergrund anfordern.
Wenn Fork-Modus aus ist, führt Claude den Subagenten standardmäßig im Hintergrund aus und im Vordergrund, wenn er das Ergebnis benötigt, bevor er fortfährt. Fork-Modus ist aus im nicht-interaktiven Modus mit -p und im Agent SDK, es sei denn, Sie schalten ihn ein. Um einen bestimmten Subagenten im Hintergrund zu halten, auch wenn Claude das Ergebnis möchte, setzen Sie sein Frontmatter-Feld background auf true.

Für eine Skill mit context: fork folgt Claude Code stattdessen den Regeln in Führen Sie Skills in einem Subagenten aus, unabhängig davon, ob Fork-Modus an ist.

Hintergrund-Subagenten werden mit einem kleineren integrierten Werkzeugsatz als Vordergrund-Subagenten ausgeführt, außer für Konversations-Forks und fortgesetzte Vordergrund-Subagenten.

Hintergrund-Subagenten zeigen jede Genehmigungseingabeaufforderung in Ihrer Hauptsitzung an. Wenn Sie eine dieser Eingabeaufforderungen mit einer Wahl beantworten, die über diesen einen Werkzeugaufruf hinausgeht, z. B. eine Genehmigung, die für den Rest der Sitzung gilt, wendet Claude Code Ihre Antwort auf die gesamte Sitzung an, einschließlich Ihrer Hauptkonversation.

Ein Hintergrund-Subagent kann einen Hintergrund-Bash- oder PowerShell-Befehl über das Ende seines Zuges hinaus laufen lassen. Wenn dieser Befehl endet, sendet Claude Code dem Subagenten eine Benachrichtigung.

Die Ergebnisse eines Hintergrund-Subagenten erreichen Claude als Abschlussbenachrichtigung in einem späteren Zug. Claude wartet auf diese Benachrichtigung, bevor er die Ergebnisse des Subagenten meldet, und wenn Sie zuerst nach Fortschritt fragen, meldet er, dass der Subagent noch läuft. Vor v2.1.211 meldete Claude manchmal Ergebnisse für einen Hintergrund-Subagenten, der nicht fertig war.

Sie können dies auch selbst steuern:

Wenn Fork-Modus aus ist, bitten Sie Claude, eine Aufgabe im Hintergrund oder im Vordergrund auszuführen
Drücken Sie Strg+B, um eine laufende Aufgabe in den Hintergrund zu verschieben

Claude Code löscht die Zeile eines Hintergrund-Subagenten aus dem Subagenten-Panel unter der Eingabeaufforderungseingabe auf eine von zwei Arten, je nachdem, wie der Subagent endete:

Wenn ein Subagent erfolgreich beendet wird, entfernt Claude Code seine Zeile sofort und zeigt außer im Bildschirmlesemodus /tasks to see subagents in der Fußzeile für 30 Sekunden an. Führen Sie während dieser 30 Sekunden /tasks aus und drücken Sie Enter auf dem Subagenten, um sein Transkript zu öffnen. Vor v2.1.232 behielt Claude Code die Zeile 30 Sekunden nach Beendigung des Subagenten, genauso wie eine fehlgeschlagene, und zeigte keinen Fußzeilentipp.
Wenn ein Subagent fehlschlägt oder Sie ihn stoppen, behält Claude Code seine Zeile 30 Sekunden lang. Um die Zeile schneller zu löschen, wählen Sie sie aus und drücken Sie x.

Ein Hintergrund-Subagent, der abgeschlossen ist, bleibt in /tasks aufgelistet, als erledigt markiert und unter laufender Arbeit sortiert, für die gleichen 30 Sekunden wie der Fußzeilentipp. Seine Detailansicht bleibt offen, wenn der Subagent beendet wird. Subagenten, die fehlschlagen oder die Sie stoppen, verlassen die Liste. Vor v2.1.208 verließ ein abgeschlossener Subagent die Liste in dem Moment, in dem er beendet wurde, und seine Detailansicht schloss sich.

Subagenten-Namen

Claude kann einem Subagenten einen Namen geben, indem er einen name-Parameter beim Agent-Werkzeugaufruf übergibt, und kann dies auch von selbst tun, ohne Sie zuerst zu fragen. Der Name macht den Subagenten adressierbar: Claude kann ihn nach Abschluss nach Name ansprechen oder fortsetzen.

In einer interaktiven Sitzung mit aktivierten Agent-Teams wird ein Subagent, den Claude aus der Hauptkonversation mit einem name spawnt, stattdessen als Teamkollege gestartet, es sei denn, der Aufruf ist ein Fork oder übergibt isolation beim Aufruf selbst. Ein isolation-Wert in der Frontmatter des Subagenten verhindert es nicht, und der Teamkollege wird dann im Arbeitsverzeichnis der Hauptsitzung ausgeführt. Siehe Wie Claude Agent-Teams startet.

API-Fehler in Subagenten

Wenn etwas die Antwort eines Subagenten mitten im Stream unterbricht, und die teilweise Antwort Text enthält, aber keine Werkzeugaufrufe, fordert Claude Code den Subagenten auf, fortzufahren, anstatt den Lauf zu beenden. Dies geschieht auch in interaktiven Sitzungen. Der Lauf endet beim Fehler nur, wenn diese Fortsetzungen aufgebraucht sind.

Ab v2.1.199 meldet ein Subagent, dessen Lauf bei einem API-Fehler endet, z. B. bei einem Nutzungslimit oder wiederholtem Serverfehler, diesen Fehler an Claude zurück, anstatt den Fehlertext so zurückzugeben, als wären es die Erkenntnisse des Subagenten. Was Claude erhält, hängt davon ab, wo der Subagent lief:

Vordergrund: Wenn ein Ratenlimit, eine Überlastung oder ein Serverfehler einen Subagenten unterbricht, der bereits Textausgabe produziert hat, gibt das Agent-Werkzeug diese teilweise Ausgabe mit einer Notiz zurück, dass der Subagent unterbrochen wurde und seine Aufgabe nicht abgeschlossen hat. Ein Subagent, der nichts produziert hat oder dessen einzige Ausgabe Werkzeugaufrufe waren, schlägt mit Agent terminated early due to an API error fehl, gefolgt von der Fehlerdetail. In v2.1.199 gab ein Ratenlimit, eine Überlastung oder ein Serverfehler, der die Form „nur Werkzeugaufrufe" unterbrach, ein leeres teilweises Ergebnis zurück, das nur die Unterbrechungsnotiz enthielt.
Hintergrund: Der Subagent wird als fehlgeschlagen markiert, und die Nachricht, die Claude erhält, wenn er endet, nennt den API-Fehler und enthält die letzte Ausgabe des Subagenten, sodass teilweise Arbeit nicht verloren geht.

Wenn Sie eine Fallback-Modellkette konfigurieren und ein Subagent auf einen Fehler trifft, den die Kette abdeckt, z. B. dass sein Modell nicht verfügbar ist, wechselt Claude Code den Subagenten zum ersten Modell in der Kette, das die Anfrage akzeptiert. Der Subagent arbeitet weiter, anstatt beim Fehler zu enden.

Sobald der zugrunde liegende API-Fehler behoben ist, bitten Sie Claude, die Aufgabe zu wiederholen oder den Subagenten fortzusetzen.

Subagenten-Ausgabe-Scanning

Claude Code scannt den endgültigen Bericht jedes Subagenten, bevor Claude ihn liest. Ein Subagent kann Dateien, Webseiten oder Befehlsausgaben gelesen haben, die Sie nie überprüft haben, und Text aus diesen Quellen kann Anweisungen enthalten, die auf die Hauptkonversation abzielen. Der Scan entfernt oder umformuliert niemals etwas; er nimmt zwei Arten von Änderungen vor, die Sie möglicherweise in einem Bericht bemerken:

Backslash-Einfügung: Der Scan fügt einen Backslash in Text ein, der Claude Codes eigene Ausgabe imitiert, z. B. ein <system-reminder>-Tag oder eine Zeile, die mit Human: oder Assistant: beginnt, damit die Imitation als gewöhnlicher Text gelesen wird, anstatt als Teil der Konversation verwechselt zu werden.
Marker-Zeile: Der Scan stellt eine Zeile voran, die mit [harness: subagent output matched instruction-shaped pattern(s): beginnt, wenn der Bericht ein Tag wie <system-reminder> imitiert oder Genehmigungseinstellungen wie bypassPermissions oder --dangerously-skip-permissions erwähnt. Genehmigungseinstellungs-Erwähnungen erhalten die Marker-Zeile, aber der Text selbst bleibt wie geschrieben.

Der Scan beurteilt nicht, ob Inhalte bösartig sind, und er ändert nicht, was eine Anweisung in einem Bericht tun kann: Ein Werkzeugaufruf, zu dem der Bericht Claude führt, durchläuft immer noch die Genehmigungsprüfungen und Sandboxing der Sitzung. Es ist kein Ersatz für Einschränkung, was ein Subagent erreichen kann.

Häufige Muster

Isolieren Sie hochvolumige Operationen

Eine der effektivsten Verwendungen für Subagenten ist die Isolierung von Operationen, die große Mengen an Ausgabe produzieren. Das Ausführen von Tests, das Abrufen von Dokumentation oder das Verarbeiten von Protokolldateien kann erheblichen Kontext verbrauchen. Durch die Delegierung dieser an einen Subagenten bleibt die ausführliche Ausgabe im Kontext des Subagenten, während nur die relevante Zusammenfassung zu Ihrer Hauptkonversation zurückkehrt.

Use a subagent to run the test suite and report only the failing tests with their error messages

Führen Sie parallele Recherchen durch

Für unabhängige Untersuchungen spawnen Sie mehrere Subagenten, um gleichzeitig zu arbeiten:

Research the authentication, database, and API modules in parallel using separate subagents

Jeder Subagent erkundet seinen Bereich unabhängig, dann synthetisiert Claude die Erkenntnisse. Dies funktioniert am besten, wenn die Forschungspfade nicht voneinander abhängen.

Für Arbeit, die parallel weiterläuft oder nicht in ein Kontextfenster passt, führen Sie sie in separaten Sitzungen aus und lassen Sie Claude Erkenntnisse zwischen ihnen weitergeben.

Verketten Sie Subagenten

Für mehrstufige Workflows bitten Sie Claude, Subagenten nacheinander zu verwenden. Jeder Subagent schließt seine Aufgabe ab und gibt Ergebnisse an Claude zurück, der dann relevanten Kontext an den nächsten Subagenten übergibt.

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Wählen Sie zwischen Subagenten und Hauptkonversation

Verwenden Sie die Hauptkonversation, wenn:

Die Aufgabe häufiges Hin und Her oder iterative Verfeinerung benötigt
Mehrere Phasen teilen erheblichen Kontext, z. B. Planung, Implementierung und Tests
Sie eine schnelle, gezielte Änderung vornehmen
Latenz wichtig ist. Ein Subagent, der kein Fork ist, startet von vorne und benötigt möglicherweise Zeit, um Kontext zu sammeln

Verwenden Sie Subagenten, wenn:

Die Aufgabe ausführliche Ausgabe produziert, die Sie nicht in Ihrem Hauptkontext benötigen
Sie spezifische Werkzeugbeschränkungen oder Genehmigungen erzwingen möchten
Die Arbeit in sich geschlossen ist und eine Zusammenfassung zurückgeben kann

Erwägen Sie stattdessen Skills, wenn Sie wiederverwendbare Eingabeaufforderungen oder Workflows möchten, die im Hauptkonversationskontext ausgeführt werden, anstatt in isoliertem Subagenten-Kontext.

Für eine Frage zu etwas, das bereits in Ihrer Konversation vorhanden ist, verwenden Sie /btw anstelle eines Subagenten. Es sieht Ihren vollständigen Kontext, hat aber keinen Werkzeugzugriff, und die Antwort wird nicht zur Historie hinzugefügt.

Lassen Sie Subagenten ihre eigenen Subagenten spawnen

Standardmäßig kann ein Subagent seine eigenen Subagenten spawnen, bis zu drei Ebenen unter der Hauptkonversation. Bei der Tiefengrenze entzieht Claude Code das Agent-Werkzeug jedem Subagenten außer einem Fork, sodass ein Subagent bei der Grenze seine delegierte Arbeit selbst erledigt und eine Zusammenfassung zurückgibt. Ein Fork bei der Grenze behält Agent in seiner geerbten Werkzeugliste, aber das Werkzeug gibt stattdessen einen Fehler zurück.

Verschachtelte Subagenten eignen sich für eine delegierte Aufgabe, die sich selbst in parallele Unteraufgaben aufteilt, z. B. ein Reviewer-Subagent, der einen Verifizierer pro Befund versendet. In einer interaktiven Sitzung kehrt nur die Zusammenfassung des Top-Level-Subagenten zu Ihnen zurück und die Zwischenausgabe bleibt aus Ihrer Hauptkonversation: Ein Subagent, der Hintergrund-Subagenten startet, wartet auf deren Ergebnisse, bevor er beendet wird. Im nicht-interaktiven Modus und dem Agent SDK wartet der startende Subagent nicht, sodass ein verschachtelter Hintergrund-Subagent, der beendet wird, nachdem sein Starter beendet wurde, stattdessen an Ihre Hauptkonversation meldet.

Um die Grenze zu ändern, setzen Sie CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH auf die Anzahl der Subagenten-Ebenen, die Sie unter Ihrer Hauptkonversation möchten. Beispielsweise begrenzt dieser Eintrag in settings.json die Verschachtelung auf zwei Ebenen:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Mit diesem Wert können Ihre Subagenten an eine zweite Ebene ihrer eigenen delegieren, und diese zweite Ebene kann nicht weiter delegieren. Setzen Sie 1, um Verschachtelung auszuschalten.

Ein verschachtelter Subagent wird genauso konfiguriert wie ein Top-Level-Subagent und wird aus denselben Bereichen aufgelöst. Um zu verhindern, dass ein Subagent spawnt, während Verschachtelung an ist, z. B. ein Reviewer, der schreibgeschützt bleiben sollte, lassen Sie Agent aus seiner tools-Liste weg oder fügen Sie es zu disallowedTools hinzu.

Claude Code zeigt verschachtelte Subagenten als Baum im Subagenten-Panel unter der Eingabeaufforderungseingabe an und markiert jede Zeile, die noch Nachkommen hat, mit einer (+N)-Anzahl von ihnen. Öffnen Sie eine Zeile, um die Geschwister und direkten Kinder dieses Subagenten mit einem Pfad zurück zu main zu sehen.

Gleichzeitiges Subagenten-Limit

Zwei Grenzen steuern die Subagenten-Nutzung, jede mit ihrer eigenen Variablen: Diese stoppt Claude daran, mehr Subagenten zu spawnen, während zu viele laufen, und die Tiefengrenze begrenzt, wie tief Subagenten verschachtelt sind. Es gibt keine Grenze für die Gesamtzahl der Subagenten, die Claude über eine Sitzung spawnen kann.

Standardmäßig schlägt das Spawnen eines anderen mit dem Agent-Werkzeug fehl, wenn 20 Subagenten in einer Sitzung laufen, mit Concurrent subagent limit reached, und der Fehler teilt Claude mit, nicht zu wiederholen. Das Spawnen ist erfolgreich, wenn die laufende Anzahl unter die Grenze fällt. Um die Grenze zu ändern, setzen Sie CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS auf eine beliebige positive ganze Zahl. Sitzungen mit aktivem ultracode sind ausgenommen: Die Grenze wird dort nicht erzwungen. Erfordert Claude Code v2.1.217 oder später.

Die Grenze blockiert nur Subagenten, die Claude mit dem Agent-Werkzeug spawnt, aber andere Läufe belegen die gleichen Slots:

Ein In-Session-Fork, den Sie mit /subtask starten, belegt einen Slot während der Ausführung und wird niemals durch die Grenze blockiert.
Fortsetzen eines Subagenten, der bereits beendet ist, belegt einen neuen Slot, ohne die Grenze zu überprüfen, sodass Fortsetzungen die laufende Anzahl über die Grenze hinaus drücken können.

Agenten, die andere Funktionen ausführen, z. B. Workflow-Agenten und Agent-Team-Teamkollegen, folgen stattdessen ihren eigenen Grenzen.

Verwalten Sie den Subagenten-Kontext

Was beim Start geladen wird

Jeder Subagent startet mit einem frischen, isolierten Kontextfenster. Er sieht Ihre Konversationshistorie nicht, die Skills, die Sie bereits aufgerufen haben, oder die Dateien, die Claude bereits gelesen hat. Claude verfasst eine Delegierungsnachricht, die die Aufgabe zusammenfasst, und der Subagent arbeitet von dort aus. Die Ausnahme ist ein Fork, der die übergeordnete Konversation erbt, anstatt von vorne zu beginnen.

Der anfängliche Kontext eines Non-Fork-Subagenten enthält:

Systemeingabeaufforderung: die eigene Eingabeaufforderung des Agenten plus Umgebungsdetails, die Claude Code anfügt, nicht die Claude-Code-Systemeingabeaufforderung. Benutzerdefinierte Subagenten definieren ihre im Markdown-Body oder im Feld prompt. Integrierte Agenten haben vordefinierte Eingabeaufforderungen.
Aufgabennachricht: die Delegierungseingabeaufforderung, die Claude schreibt, wenn es die Arbeit übergibt.
CLAUDE.md-Dateien: jede Ebene der CLAUDE.md-Hierarchie, die die Hauptkonversation lädt, einschließlich ~/.claude/CLAUDE.md, Projektregeln, CLAUDE.local.md, verwaltete Richtliniendateien und alle AGENTS.md-Dateien, die als Projektanweisungen geladen werden. Die integrierten Explore- und Plan-Agenten überspringen dies. Ein Subagent, dessen Definition omitClaudeMd setzt, lädt nur die verwalteten Richtliniendateien oder gar keine, wenn die Definition aus verwalteten Einstellungen stammt.
Git-Status: Ein Snapshot, der zu Beginn der übergeordneten Sitzung aufgenommen wurde. Fehlt, wenn das Arbeitsverzeichnis kein Git-Repository ist oder wenn includeGitInstructions false ist. Explore und Plan überspringen es unabhängig davon.
Vorgeladene Skills: Vollständiger Inhalt jeder Skill, die im Feld skills des Agenten benannt ist. Integrierte Agenten laden Skills nicht vor.
Geschwister-Roster: Eine Systemerinnerung, die main und jeden anderen benannten Agenten in der Sitzung auflistet, jeweils ein gültiger to-Wert für SendMessage. Erfordert Claude Code v2.1.206 oder später. Das Roster erscheint nur, wenn die Tools des Subagenten SendMessage enthalten und mindestens ein anderer Agent einen Namen hat, ob Claude ihn beim Spawnen benannt hat oder er als Agent-Team-Teamkollege läuft. Es ist ein Snapshot, der aufgenommen wird, wenn der Subagent startet, sodass später benannte Agenten nicht erscheinen.

Um einen Ihrer eigenen Subagenten ohne die Benutzer-, Projekt- und lokalen CLAUDE.md-Dateien zu starten, setzen Sie omitClaudeMd: true in seiner Frontmatter oder --agents JSON.

Die Hauptkonversation hat immer noch Ihre vollständige CLAUDE.md, wenn sie die Ergebnisse dieser Subagenten liest, sodass die meisten Regeln den Subagenten selbst nicht erreichen müssen. Wenn eine Regel dies muss, z. B. „ignorieren Sie das vendor/-Verzeichnis", wiederholen Sie sie in der Eingabeaufforderung, die Sie Claude geben, wenn Sie delegieren.

Sie können nicht ändern, welche Subagenten Git-Status erhalten. Nur Explore und Plan überspringen es.

Einige Hauptkonversationszustände erreichen niemals einen Non-Fork-Subagenten:

Ausgabestil: Ein Subagent führt seine eigene Systemeingabeaufforderung aus, sodass Ihr Ausgabestil seine Antworten nicht formt, außer in einem Fork.
Auto-Gedächtnis: Das Auto-Gedächtnis der Hauptkonversation wird nicht geladen. Um einem Subagenten persistentes Gedächtnis seiner eigenen zu geben, verwenden Sie das Feld memory.
Kontextfenstergröße: Das Kontextfenster eines Subagenten wird durch sein eigenes Modell dimensioniert, nicht das des übergeordneten. Die Delegierung an ein Modell mit einem kleineren Fenster gibt diesem Subagenten das kleinere Fenster.

Fortsetzen Sie Subagenten

Jeder Subagenten-Aufruf erstellt eine neue Instanz, anstatt eine frühere fortzusetzen. Um die Arbeit eines bestehenden Subagenten fortzusetzen, anstatt von vorne zu beginnen, bitten Sie Claude, ihn fortzusetzen.

Fortgesetzte Subagenten behalten ihre vollständige Konversationshistorie, einschließlich aller vorherigen Werkzeugaufrufe, Ergebnisse und Überlegungen. Wenn der Subagent Hintergrund-Subagenten seiner eigenen spawnte, enthält diese Historie die Ergebnisse, die sie während der Ausführung lieferten. Der Subagent setzt genau dort an, wo er stoppte, anstatt von vorne zu beginnen.

Wenn ein Subagent abgeschlossen ist, erhält Claude seine Agent-ID.
Die integrierten Explore- und Plan-Agenten sind einmalig und geben keine Agent-ID zurück, sodass Claude sie nicht fortsetzen kann. Verwenden Sie general-purpose oder einen benutzerdefinierten Subagenten, wenn Sie die Arbeit fortsetzen müssen.
Wenn ein Subagent bei seinem maxTurns-Limit stoppt, markiert Claude Code die zurückgegebene Ausgabe als teilweise. Für Subagenten, die eine Agent-ID zurückgeben, vermerkt Claude Code auch im Ergebnis, dass Claude den Subagenten ansprechen kann, um von dort fortzufahren, wo er stoppte.

Claude verwendet das SendMessage-Werkzeug mit der Agent-ID oder dem Namen des Agenten als to-Feld, um ihn fortzusetzen. SendMessage erfordert nicht, dass Agent-Teams aktiviert sind; nur strukturierte Team-Protokoll-Nachrichten wie shutdown_request und plan_approval_response tun dies. Über Subagenten und Teamkollegen hinaus können Claude in Sitzungen, in denen Cross-Session-Messaging aktiviert ist, mit demselben Werkzeug Ihre anderen Claude-Code-Sitzungen ansprechen, auf dieser Maschine oder darüber hinaus.

Um einen Subagenten fortzusetzen, bitten Sie Claude, die vorherige Arbeit fortzusetzen:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

Wenn Claude einen abgeschlossenen Subagenten mit dem SendMessage-Werkzeug eine Nachricht sendet, wird der Subagent im Hintergrund ohne einen neuen Agent-Aufruf fortgesetzt. Das Gleiche gilt für einen Subagenten, den Claude mit dem TaskStop-Werkzeug gestoppt hat, sobald sein gestoppter Lauf beendet ist. Der fortgesetzte Lauf behält den Werkzeugsatz von dort, wo der Subagent zuerst lief, und kann weiterhin den Prompt-Cache lesen, den der ursprüngliche Lauf aufgewärmt hat.

Ein Subagent, der das SendMessage-Werkzeug hat, kann diese Nachricht auch senden. In einer interaktiven Sitzung meldet der fortgesetzte Agent dann dem Subagenten, der ihn fortgesetzt hat, zurück, nicht zu Ihrer Hauptkonversation. Dieser Subagent wartet auf das Ergebnis, bevor er seine eigene Arbeit beendet. Wenn ein Subagent einen Agenten anspricht, dem er meldet, z. B. seinen eigenen Launcher, setzt Claude Code diesen Agenten fort, ohne seine Ergebnisse umzuleiten.

Ein Subagent, den Sie selbst gestoppt haben, mit x in /tasks oder einer SDK-stop_task-Anfrage, wird nicht automatisch fortgesetzt. Wenn Claude ihm eine Nachricht sendet, wird die Nachricht verweigert und Claude wird mitgeteilt, dass der Agent abgebrochen wurde.

Während die Zeile dieses Subagenten immer noch im Subagenten-Panel ist, geben Sie in sein Transkript ein, um ihn selbst fortzusetzen. Danach kann eine Nachricht von Claude ihn wieder automatisch fortsetzen. Erfordert Claude Code v2.1.191 oder später.

Das Fortsetzen startet einen neuen Lauf des Agenten unter derselben ID, sodass ein Subagent, der bereits fehlgeschlagen oder abgeschlossen war, in der Aufgabenliste und in den Task-Events des Agent SDK wieder als laufend angezeigt wird. Vor v2.1.205 zeigte er seinen früheren fehlgeschlagenen oder abgeschlossenen Status, während der fortgesetzte Lauf funktionierte.

Ab v2.1.199 überprüft SendMessage, dass ein Name immer noch auf denselben Agenten verweist, den er früher in der Konversation erreicht hat. Wenn ein neuerer Agent den Namen übernommen hat, z. B. ein neu gespawnter Hintergrund-Agent, der ihn wiederverwendet hat, weigert sich Claude Code, die Nachricht zu senden, anstatt sie an den falschen Agenten zu liefern, und der Fehler meldet, welcher Agent der Name jetzt erreicht, damit Claude neu ausrichten kann. Um den früheren Agenten zu erreichen, während er noch läuft, spricht Claude ihn nach der Agent-ID an, die er erhielt, als er diesen Agenten spawnte. Die Überprüfung ist auf die aktuelle Konversation beschränkt und wird bei /clear zurückgesetzt.

Ab v2.1.198 behandelt ein Subagent Nachrichten vom Agenten, der ihn gestartet hat, als normale Aufgabenrichtung, einschließlich Kurskorrektionen während der Aufgabe, und handelt nach ihnen innerhalb seiner eigenen Genehmigungseinstellungen. Zwei Grenzen gelten trotzdem unabhängig davon, wer die Nachricht gesendet hat: Keine Nachricht von einem Agenten zählt als Ihre Genehmigung für eine ausstehende Genehmigungseingabeaufforderung, und keine Agent-Nachricht kann die Genehmigungseinstellungen, CLAUDE.md oder Konfiguration eines Subagenten ändern. Nur das Genehmigungssystem oder Ihre eigenen Nachrichten können Genehmigung gewähren.

Sie können Claude auch nach der Agent-ID fragen, wenn Sie sie explizit referenzieren möchten, oder IDs in den Transkriptdateien unter ~/.claude/projects/{project}/{sessionId}/subagents/ finden. Jedes Transkript wird als agent-{agentId}.jsonl gespeichert.

Subagenten-Transkripte bleiben unabhängig von der Hauptkonversation bestehen:

Hauptkonversations-Komprimierung: Wenn die Hauptkonversation komprimiert wird, sind Subagenten-Transkripte nicht betroffen. Sie werden in separaten Dateien gespeichert.
Sitzungspersistenz: Subagenten-Transkripte bleiben innerhalb ihrer Sitzung bestehen. Sie können einen Subagenten fortsetzen, nachdem Sie Claude Code neu gestartet haben, indem Sie dieselbe Sitzung fortsetzen.
Automatische Bereinigung: Claude Code löscht Subagenten-Transkripte nach der Aufbewahrungsfrist cleanupPeriodDays, standardmäßig 30 Tage, nach den Aufbewahrungsfeger-Regeln.

Auto-Komprimierung

Subagenten unterstützen automatische Komprimierung mit der gleichen Logik wie die Hauptkonversation. Die Komprimierung wird unter den gleichen Bedingungen ausgelöst, und CLAUDE_AUTOCOMPACT_PCT_OVERRIDE gilt auch für Subagenten. Siehe Umgebungsvariablen für den Zeitpunkt, an dem die Überschreibung wirksam wird.

Komprimierungsereignisse werden in Subagenten-Transkriptdateien protokolliert:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

Der Wert preTokens zeigt, wie viele Token vor der Komprimierung verwendet wurden.

Gegabelte Konversation

Ein Fork ist ein Subagent, der die gesamte bisherige Konversation erbt, anstatt von vorne zu beginnen. Dies lässt die Eingabe-Isolierung fallen, die Subagenten ansonsten bieten: Ein Fork sieht denselben Systemprompt, dieselben Werkzeuge, dasselbe Modell und die Nachrichtenhistorie wie die Hauptsitzung, sodass Sie ihm eine Nebenaufgabe übergeben können, ohne die Situation erneut zu erklären. Die eigenen Werkzeugaufrufe des Forks bleiben weiterhin aus Ihrer Konversation heraus und nur sein endgültiges Ergebnis kommt zurück, sodass Ihr Hauptkontextfenster sauber bleibt. Verwenden Sie einen Fork, wenn ein anderer Subagent zu viel Hintergrund benötigen würde, um nützlich zu sein, oder wenn Sie mehrere Ansätze parallel vom gleichen Ausgangspunkt aus versuchen möchten.

Claude startet einen Fork, indem er den fork-Subagenten-Typ durch das Agent-Werkzeug anfordert. Sie steuern, ob dies möglich ist, mit dem Fork-Modus, der in interaktiven Sitzungen standardmäßig aktiviert ist.

Sie können einen Fork selbst mit /subtask gefolgt von einer Aufgabe starten, unabhängig davon, ob der Fork-Modus aktiviert ist oder nicht. In v2.1.161 bis v2.1.211 ist der Befehl /fork. Claude Code benennt den Fork aus den ersten Worten der Aufgabe. Das folgende Beispiel gabelt die Konversation, um Testfälle zu entwerfen, während Sie mit der Implementierung in der Hauptsitzung fortfahren:

/subtask draft unit tests for the parser changes so far

Der Fork erscheint in einem Panel unter Ihrer Eingabeaufforderung und läuft im Hintergrund, während Sie weiterarbeiten. Wenn er fertig ist, kommt sein Ergebnis als Nachricht in Ihrer Hauptkonversation an. Der nächste Abschnitt behandelt die Panel-Steuerelemente zum Beobachten und Lenken von Forks während ihrer Ausführung.

Beobachten und lenken Sie laufende Forks

Laufende Forks erscheinen in einem Panel unter der Eingabeaufforderung, mit einer Zeile für die Hauptsitzung und einer für jeden Fork.

Wenn ein Fork erfolgreich abgeschlossen ist, entfernt Claude Code seine Zeile. Claude Code behält die Zeile eines Forks, der fehlgeschlagen ist oder den Sie gestoppt haben, für 30 Sekunden bei, das gleiche wie für jeden anderen Hintergrund-Subagenten. Vor v2.1.232 behielt Claude Code die Zeile eines abgeschlossenen Forks ebenfalls für 30 Sekunden bei.

Verwenden Sie diese Tasten, um mit dem Panel zu interagieren:

Taste	Aktion
`↑` / `↓`	Zwischen Zeilen wechseln
`Enter`	Öffnen Sie das Transkript des ausgewählten Forks und senden Sie ihm Folgefragen
`x`	Stoppen Sie den ausgewählten Fork, wenn er läuft, oder schließen Sie seine Zeile, wenn er nicht mehr läuft. In der Hauptsitzungs-Zeile oder in der Zeile des Forks, dessen Transkript Sie mit `Enter` geöffnet haben, gibt `x` stattdessen in die Eingabeaufforderung ein
`Esc`	Fokus zurück zur Eingabeaufforderung

Mit einem geöffneten Transkript eines Forks oder Subagenten gehen Folgefragen und Skills an diesen Agenten, aber integrierte Befehle werden weiterhin in Ihrer Hauptkonversation ausgeführt. Ab v2.1.199 zeigt die Eingabe von /model oder /fast in dieser Ansicht einen Hinweis an, dass dies das Modell oder den Schnellmodus der Hauptkonversation ändert, nicht des angezeigten Agenten, anstatt es stillschweigend auszuführen.

Wie sich Forks von anderen Subagenten unterscheiden

Ein Fork erbt alles, was die Hauptsitzung zum Zeitpunkt des Spawnens hat. Jeder andere Subagent startet von seiner Definition aus.

	Fork	Nicht-Fork-Subagent
Kontext	Vollständige Konversationshistorie	Frischer Kontext mit dem Prompt, den Sie übergeben
Systemprompt und Werkzeuge	Gleich wie Hauptsitzung	Aus der Definitionsdatei des Subagenten, gefiltert für Hintergrund-Läufe
Modell	Gleich wie Hauptsitzung	Aus dem `model`-Feld des Subagenten
Berechtigungen	Aufforderungen erscheinen in Ihrem Terminal	Aufforderungen erscheinen in Ihrer Hauptsitzung bei Ausführung im Hintergrund
Prompt-Cache	Mit Hauptsitzung geteilt	Separater Cache

Da der Systemprompt und die Werkzeugdefinitionen eines Forks identisch mit dem übergeordneten Element sind, wird seine erste Anfrage den Prompt-Cache des übergeordneten Elements wiederverwenden. Dies macht das Forking billiger als das Spawnen eines frischen Subagenten für Aufgaben, die denselben Kontext benötigen.

Wenn Claude einen Fork durch das Agent-Werkzeug spawnt, kann es isolation: "worktree" übergeben, sodass die Dateibearbeitungen des Forks in einen separaten Git-Worktree geschrieben werden, anstatt in Ihren Checkout. Ein Fork kann keine weiteren Forks spawnen.

Fork-Modus aktivieren oder deaktivieren

Claude Code aktiviert den Fork-Modus standardmäßig in interaktiven Sitzungen und lässt ihn standardmäßig im nicht-interaktiven Modus mit -p und im Agent SDK deaktiviert. Der interaktive Standard erfordert Claude Code v2.1.232 oder später. In früheren Versionen setzen Sie CLAUDE_CODE_FORK_SUBAGENT auf 1, um den Fork-Modus zu aktivieren.

Sie können erkennen, dass der Fork-Modus aktiviert ist, an der Art und Weise, wie Claude Code das Agent-Werkzeug handhabt:

Claude kann einen Fork spawnen, indem er den fork-Subagenten-Typ anfordert. Wenn Claude keinen Typ anfordert, erhält es den allgemeinen-Subagenten, falls die Sitzung diesen Typ noch hat. Subagenten, die aus einer Definition gespawnt werden, wie Explore, funktionieren wie gewohnt.
Claude Code führt die Subagenten, die Claude spawnt, im Hintergrund aus, Forks und Nicht-Fork-Subagenten gleichermaßen, abgesehen von den Fällen, die im Vordergrund bleiben. Claude Code entfernt auch den run_in_background-Parameter des Agent-Werkzeugs, sodass Claude nicht den Vordergrund anfordern kann.

Setzen Sie die Umgebungsvariable CLAUDE_CODE_FORK_SUBAGENT, um die Standardwerte zu überschreiben:

1 aktiviert den Fork-Modus auch im nicht-interaktiven Modus und im Agent SDK
0 deaktiviert den Fork-Modus in jeder Art von Sitzung

Um den Fork-Modus aktiviert zu halten, aber Claude daran zu hindern, Forks zu spawnen, verweigern Sie den fork-Subagenten-Typ mit einer Agent(fork)-Regel. Claude Code führt die Subagenten, die Claude spawnt, weiterhin im Hintergrund aus, abgesehen von den gleichen Fällen, die im Vordergrund bleiben.

Beispiel-Subagenten

Diese Beispiele demonstrieren effektive Muster für die Erstellung von Subagenten. Verwenden Sie sie als Ausgangspunkte oder generieren Sie eine angepasste Version mit Claude.

Code-Reviewer

Ein schreibgeschützter Subagent, der Code überprüft, ohne ihn zu ändern. Dieses Beispiel zeigt, wie man einen fokussierten Subagenten mit begrenztem Werkzeugzugriff entwirft, der Edit und Write ausschließt, und einen detaillierten Prompt, der genau angibt, worauf zu achten ist und wie die Ausgabe formatiert wird.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Debugger

Ein Subagent, der sowohl Probleme analysieren als auch beheben kann. Im Gegensatz zum Code-Reviewer enthält dieser Edit, da das Beheben von Bugs die Änderung von Code erfordert. Der Prompt bietet einen klaren Workflow von der Diagnose zur Verifizierung.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Data Scientist

Ein domänenspezifischer Subagent für Datenanalyse-Arbeiten. Dieses Beispiel zeigt, wie man Subagenten für spezialisierte Workflows außerhalb typischer Coding-Aufgaben erstellt. Es setzt explizit model: sonnet für fähigere Analysen.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Datenbankabfrage-Validator

Ein Subagent, der Bash-Zugriff zulässt, aber Befehle validiert, um nur schreibgeschützte SQL-Abfragen zu ermöglichen. Dieses Beispiel zeigt, wie man PreToolUse-Hooks für bedingte Validierung verwendet, wenn Sie feinere Kontrolle benötigen, als das tools-Feld bietet.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code übergibt Hook-Eingabe als JSON über stdin an Hook-Befehle. Das Validierungsskript liest dieses JSON, extrahiert den auszuführenden Befehl und prüft ihn gegen eine Liste von SQL-Schreibvorgängen. Wenn ein Schreibvorgang erkannt wird, beendet das Skript mit Code 2, um die Ausführung zu blockieren, und gibt eine Fehlermeldung an Claude über stderr zurück.

Erstellen Sie das Validierungsskript überall in Ihrem Projekt. Der Pfad muss dem command-Feld in Ihrer Hook-Konfiguration entsprechen:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

Machen Sie das Skript unter macOS und Linux ausführbar:

chmod +x ./scripts/validate-readonly-query.sh

Unter Windows schreiben Sie das Validierungsskript in PowerShell und fügen shell: powershell zum Hook-Eintrag hinzu. Siehe Hooks in PowerShell ausführen.

Der Hook empfängt JSON über stdin mit dem Bash-Befehl in tool_input.command. Exit-Code 2 blockiert die Operation und leitet die Fehlermeldung an Claude weiter. Siehe Hooks für Details zu Exit-Codes und Hook-Eingabe für das vollständige Eingabeschema.

Das System-Prompt teilt dem Subagenten mit, Schreibanfragen abzulehnen, daher ist der Hook ein Sicherheitsmechanismus: Wenn der Subagent trotzdem einen Schreibvorgang versucht, blockiert Claude Code den Befehl und der Subagent sieht die Meldung Blocked: Write operations not allowed. Use SELECT queries only..

Nächste Schritte

Jetzt, da Sie Subagenten verstehen, erkunden Sie diese verwandten Funktionen:

Verteilen Sie Subagenten mit Plugins, um Subagenten über Teams oder Projekte hinweg zu teilen
Führen Sie Claude Code programmgesteuert aus mit dem Agent SDK für CI/CD und Automatisierung
Verwenden Sie MCP-Server, um Subagenten Zugriff auf externe Werkzeuge und Daten zu geben

sub-agents.md +107 −100

32 32

33Claude Code enthält integrierte Subagenten, die Claude automatisch bei Bedarf verwendet. Jeder erbt die Berechtigungen der übergeordneten Konversation; die meisten werden mit einem eingeschränkten Werkzeugsatz ausgeführt.33Claude Code enthält integrierte Subagenten, die Claude automatisch bei Bedarf verwendet. Jeder erbt die Berechtigungen der übergeordneten Konversation; die meisten werden mit einem eingeschränkten Werkzeugsatz ausgeführt.

34 34

35Explore und Plan überspringen Ihre CLAUDE.md-Dateien und den Git-Status der übergeordneten Sitzung, um die Recherche schnell und kostengünstig zu halten. Alle anderen integrierten und [benutzerdefinierten Subagenten](#configure-subagents) laden beide. Für die vollständige Aufschlüsselung dessen, was einen Subagenten erreicht, siehe [was beim Start geladen wird](#what-loads-at-startup).35Explore und Plan überspringen Ihre CLAUDE.md-Dateien und den Git-Status der übergeordneten Sitzung, um die Recherche schnell und kostengünstig zu halten. Alle anderen integrierten und [benutzerdefinierten Subagenten](#configure-subagents) laden beide, es sei denn, ihre Definition setzt das Feld [`omitClaudeMd`](#supported-frontmatter-fields), um die Benutzer-, Projekt- und lokalen CLAUDE.md-Dateien zu überspringen. Für die vollständige Aufschlüsselung dessen, was einen Subagenten erreicht, siehe [was beim Start geladen wird](#what-loads-at-startup).

36 36

37<Tabs>37<Tabs>

38 <Tab title="Explore">38 <Tab title="Explore">

230 </Tab>230 </Tab>

231</Tabs>231</Tabs>

232 232

233Das `--agents`-Flag akzeptiert JSON mit einem `prompt`-Feld plus diese [Frontmatter](#supported-frontmatter-fields)-Felder: `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background` und `isolation`. Verwenden Sie `prompt` für den Systemprompt, äquivalent zum Markdown-Body in dateibasierten Subagenten. Jeder Top-Level-Schlüssel im JSON ist der Name des Agenten. Starten Sie einen Namen nicht mit `-`.233Das `--agents`-Flag akzeptiert JSON mit einem `prompt`-Feld plus diese [Frontmatter](#supported-frontmatter-fields)-Felder: `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `omitClaudeMd` und `isolation`. Verwenden Sie `prompt` für den Systemprompt, äquivalent zum Markdown-Body in dateibasierten Subagenten.

234

235Jeder Top-Level-Schlüssel im JSON ist der Name des Agenten. Starten Sie einen Namen nicht mit `-`.

234 236

235Für das, was Claude Code mit einem Wert tut, den es nicht laden kann, und die Flags und Umgebungsvariable, die diese Überprüfung überspringen, siehe [`Invalid --agents configuration`](/docs/de/errors#invalid-agents-configuration).237Für das, was Claude Code mit einem Wert tut, den es nicht laden kann, und die Flags und Umgebungsvariable, die diese Überprüfung überspringen, siehe [`Invalid --agents configuration`](/docs/de/errors#invalid-agents-configuration).

236 238

300Die folgenden Felder können im YAML-Frontmatter verwendet werden. Nur `name` und `description` sind erforderlich.302Die folgenden Felder können im YAML-Frontmatter verwendet werden. Nur `name` und `description` sind erforderlich.

301 303

303| :---------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |305| :---------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

304| `name` | Ja | Eindeutige Kennung mit Kleinbuchstaben und Bindestrichen. [Hooks](/docs/de/hooks#subagentstart) erhalten diesen Wert als `agent_type`. Der Dateiname muss nicht übereinstimmen. Namen können kein `:` enthalten, das für [Plugin-Umfang-Identifier](/docs/de/plugins) wie `my-plugin:reviewer` reserviert ist. Claude Code lädt eine Datei, deren Name eins enthält, nicht und protokolliert einen Fehler im Debug-Protokoll. Vor v2.1.218 wurden solche Namen akzeptiert |306| `name` | Ja | Eindeutige Kennung mit Kleinbuchstaben und Bindestrichen. [Hooks](/docs/de/hooks#subagentstart) erhalten diesen Wert als `agent_type`. Der Dateiname muss nicht übereinstimmen. Namen können kein `:` enthalten, das für [Plugin-Umfang-Identifier](/docs/de/plugins) wie `my-plugin:reviewer` reserviert ist. Claude Code lädt eine Datei, deren Name eins enthält, nicht und protokolliert einen Fehler im Debug-Protokoll. Vor v2.1.218 wurden solche Namen akzeptiert |

305| `description` | Ja | Wann Claude an diesen Subagenten delegieren sollte |307| `description` | Ja | Wann Claude an diesen Subagenten delegieren sollte |

306| `tools` | Nein | [Werkzeuge](#available-tools), die der Subagent verwenden kann. Erbt jedes Werkzeug, das für Subagenten verfügbar ist, wenn weggelassen. Wenn kein Eintrag in der Liste sich zu einem Werkzeug auflöst, schlägt der Subagent normalerweise [fehl zu starten](/docs/de/errors#agent-would-be-spawned-with-zero-tools) mit einem Fehler, der die Einträge benennt. Um Skills in den Kontext zu laden, verwenden Sie das `skills`-Feld statt `Skill` hier aufzulisten |308| `tools` | Nein | [Werkzeuge](#available-tools), die der Subagent verwenden kann. Erbt jedes Werkzeug, das für Subagenten verfügbar ist, wenn weggelassen. Wenn kein Eintrag in der Liste sich zu einem Werkzeug auflöst, schlägt der Subagent normalerweise [fehl zu starten](/docs/de/errors#agent-would-be-spawned-with-zero-tools) mit einem Fehler, der die Einträge benennt. Um Skills in den Kontext zu laden, verwenden Sie das `skills`-Feld statt `Skill` hier aufzulisten |

315| `background` | Nein | Auf `true` setzen, um diesen Subagenten im Hintergrund zu halten, auch wenn Claude ihn im Vordergrund ausführen möchte. Wo [Fork-Modus](#turn-fork-mode-on-or-off) aktiviert ist, führt Claude Code die Subagenten, die Claude spawnt, bereits [im Hintergrund](#run-subagents-in-foreground-or-background) aus |317| `background` | Nein | Auf `true` setzen, um diesen Subagenten im Hintergrund zu halten, auch wenn Claude ihn im Vordergrund ausführen möchte. Wo [Fork-Modus](#turn-fork-mode-on-or-off) aktiviert ist, führt Claude Code die Subagenten, die Claude spawnt, bereits [im Hintergrund](#run-subagents-in-foreground-or-background) aus |

318| `omitClaudeMd` | Nein | Auf `true` setzen, um diesen Subagenten ohne die Benutzer-, Projekt- und lokalen CLAUDE.md-Dateien zu starten; [verwaltete Richtliniendateien](/docs/de/memory#how-claude-md-files-load) werden immer noch geladen, außer für [verwaltete Subagenten](#choose-the-subagent-scope). Verwenden Sie es für Subagenten, die alles, was sie benötigen, aus dem [Delegationsprompt](#what-loads-at-startup) erhalten. Ignoriert, wenn der Agent als Hauptsitzungs-Agent über `--agent` oder die `agent`-Einstellung läuft. Erfordert Claude Code v2.1.271 oder später |

316| `effort` | Nein | Aufwandsstufe, wenn dieser Subagent aktiv ist. Überschreibt die Aufwandsstufe der Sitzung. Standard: erbt von Sitzung. Optionen: `low`, `medium`, `high`, `xhigh`, `max`; verfügbare Stufen hängen vom Modell ab |319| `effort` | Nein | Aufwandsstufe, wenn dieser Subagent aktiv ist. Überschreibt die Aufwandsstufe der Sitzung. Standard: erbt von Sitzung. Optionen: `low`, `medium`, `high`, `xhigh`, `max`; verfügbare Stufen hängen vom Modell ab |

317| `isolation` | Nein | Auf `worktree` setzen, um den Subagenten in einem temporären [Git-Worktree](/docs/de/worktrees) auszuführen, was ihm eine isolierte Kopie des Repositorys gibt, die standardmäßig von Ihrem [Standard-Branch](/docs/de/worktrees#choose-the-base-branch) verzweigt ist, anstatt vom `HEAD` der übergeordneten Sitzung. Der Worktree wird automatisch bereinigt, wenn der Subagent keine Änderungen vornimmt |320| `isolation` | Nein | Auf `worktree` setzen, um den Subagenten in einem temporären [Git-Worktree](/docs/de/worktrees) auszuführen, was ihm eine isolierte Kopie des Repositorys gibt, die standardmäßig von Ihrem [Standard-Branch](/docs/de/worktrees#choose-the-base-branch) verzweigt ist, anstatt vom `HEAD` der übergeordneten Sitzung. Der Worktree wird automatisch bereinigt, wenn der Subagent keine Änderungen vornimmt |

318| `color` | Nein | Anzeigefarbe für den Subagenten in der Aufgabenliste und dem Transkript. Akzeptiert `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink` oder `cyan` |321| `color` | Nein | Anzeigefarbe für den Subagenten in der Aufgabenliste und dem Transkript. Akzeptiert `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink` oder `cyan` |

439* `WaitForMcpServers`442* `WaitForMcpServers`

440* `Workflow`443* `Workflow`

441 444

442Der zweite Filter gilt für Subagenten, die im Hintergrund laufen. Abgesehen von `Agent` und `ExitPlanMode`, die den Bedingungen des ersten Filters folgen, wo immer der Subagent läuft, behält ein Hintergrund-Subagent jedes MCP-Werkzeug, aber nur diese integrierten Werkzeuge: `Read`, `Grep`, `Glob`, `Bash`, `PowerShell`, `Edit`, `Write`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `ToolSearch`, `EnterWorktree`, `ExitWorktree`, `Monitor`, `TaskStop`, `SendMessage` und `Artifact`. Claude Code entfernt jedes andere integrierte Werkzeug aus einem Hintergrund-Subagenten, ob geerbt oder im `tools`-Feld aufgelistet, sodass die gleiche Definition zu verschiedenen Werkzeugen im Vordergrund und im Hintergrund führen kann. Die Entfernung meldet keinen Fehler, es sei denn, sie hinterlässt die `tools`-Liste [aufgelöst zu nichts](/docs/de/errors#agent-would-be-spawned-with-zero-tools).445Der zweite Filter gilt für Subagenten, die im Hintergrund laufen. Abgesehen von `Agent` und `ExitPlanMode`, die den Bedingungen des ersten Filters folgen, wo immer der Subagent läuft, behält ein Hintergrund-Subagent jedes MCP-Werkzeug, aber nur diese integrierten Werkzeuge: `Read`, `Grep`, `Glob`, `Bash`, `PowerShell`, `Edit`, `Write`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `ToolSearch`, `EnterWorktree`, `ExitWorktree`, `Monitor`, `TaskStop`, `SendMessage` und `Artifact`, plus [`SubagentHandback`](/docs/de/tools-reference) für einen Subagenten, der durch ihn berichtet. Claude Code entfernt jedes andere integrierte Werkzeug aus einem Hintergrund-Subagenten, ob geerbt oder im `tools`-Feld aufgelistet, sodass die gleiche Definition zu verschiedenen Werkzeugen im Vordergrund und im Hintergrund führen kann. Die Entfernung meldet keinen Fehler, es sei denn, sie hinterlässt die `tools`-Liste [aufgelöst zu nichts](/docs/de/errors#agent-would-be-spawned-with-zero-tools).

443 446

444[`ListAgents`](/docs/de/cross-session-messaging) folgt diesen Filtern wie jedes integrierte Werkzeug: Ein Vordergrund-Subagent erbt es in Sitzungen, wo sitzungsübergreifendes Messaging aktiviert ist, und ein Hintergrund-Subagent behält es nicht.447[`ListAgents`](/docs/de/cross-session-messaging) folgt diesen Filtern wie jedes integrierte Werkzeug: Ein Vordergrund-Subagent erbt es in Sitzungen, wo sitzungsübergreifendes Messaging aktiviert ist, und ein Hintergrund-Subagent behält es nicht.

445 448

578 581

579Die Hauptkonversation's Berechtigungsmodus entscheidet, ob Claude Code den Wert verwendet, den Sie setzen:582Die Hauptkonversation's Berechtigungsmodus entscheidet, ob Claude Code den Wert verwendet, den Sie setzen:

580 583

581* Wenn die Hauptkonversation in `bypassPermissions`, `acceptEdits` oder [Auto-Modus](/docs/de/permission-modes#eliminate-prompts-with-auto-mode) ist, läuft der Subagent in diesem gleichen Modus und Claude Code ignoriert den `permissionMode`, den Sie setzen. Unter Auto-Modus bewertet der Klassifizierer die Werkzeugaufrufe des Subagenten mit den Block- und Zulassungsregeln der Hauptkonversation.584* Wenn die Hauptkonversation in `bypassPermissions`, `acceptEdits` oder [Auto-Modus](/docs/de/permission-modes#eliminate-prompts-with-auto-mode) ist, läuft der Subagent in diesem gleichen Modus und Claude Code ignoriert den `permissionMode`, den Sie setzen. Unter Auto-Modus bewertet der Klassifizierer die Werkzeugaufrufe des Subagenten mit den Block- und Zulassungsregeln der Hauptkonversation. Wenn der Subagent endet, überprüft der Klassifizierer auch seine Arbeit und seinen endgültigen Bericht, bevor der Bericht geliefert wird, wie [Wie Auto-Modus Subagenten handhabt](/docs/de/permission-modes#eliminate-prompts-with-auto-mode) beschreibt.

582* Wenn die Hauptkonversation in `default`, `dontAsk` oder `plan` Modus ist, läuft der Subagent in dem Berechtigungsmodus, den Sie setzen, außer `bypassPermissions`. Ein Subagent, der `bypassPermissions` deklariert, behält stattdessen den Modus der Hauptkonversation. Die `bypassPermissions`-Ausnahme erfordert Claude Code v2.1.267 oder später.585* Wenn die Hauptkonversation in `default`, `dontAsk` oder `plan` Modus ist, läuft der Subagent in dem Berechtigungsmodus, den Sie setzen, außer `bypassPermissions`. Ein Subagent, der `bypassPermissions` deklariert, behält stattdessen den Modus der Hauptkonversation. Die `bypassPermissions`-Ausnahme erfordert Claude Code v2.1.267 oder später.

583 586

584`permissionMode` akzeptiert diese Werte und `manual` als Alias für `default`:587`permissionMode` akzeptiert diese Werte und `manual` als Alias für `default`:

838Siehe [Hooks](/docs/de/hooks) für das vollständige Hook-Konfigurationsformat.841Siehe [Hooks](/docs/de/hooks) für das vollständige Hook-Konfigurationsformat.

839 842

840<h2 id="work-with-subagents">843<h2 id="work-with-subagents">

841 Arbeiten Sie mit Subagenten844 Mit Subagenten arbeiten

842</h2>845</h2>

843 846

844<h3 id="understand-automatic-delegation">847<h3 id="understand-automatic-delegation">

845 Verstehen Sie automatische Delegation848 Automatische Delegierung verstehen

846</h3>849</h3>

847 850

848Claude delegiert automatisch Aufgaben basierend auf der Aufgabenbeschreibung in Ihrer Anfrage, dem `description`-Feld in Subagenten-Konfigurationen und dem aktuellen Kontext. Um proaktive Delegation zu fördern, fügen Sie Phrasen wie "use proactively" in das `description`-Feld Ihres Subagenten ein.851Claude delegiert Aufgaben automatisch basierend auf der Aufgabenbeschreibung in Ihrer Anfrage, dem Feld `description` in Subagenten-Konfigurationen und dem aktuellen Kontext. Um proaktive Delegierung zu fördern, fügen Sie Phrasen wie „use proactively" in das Beschreibungsfeld Ihres Subagenten ein.

849 852

850Halten Sie Beschreibungen kurz: Claude Code zeigt eine Startwarnmeldung an, wenn die kombinierten Beschreibungen Ihrer Subagenten das [Limit von 15.000 Token](/docs/de/errors#agent-descriptions-are-over-the-15000-token-limit) überschreiten, und lädt dennoch jeden Subagenten.853Halten Sie Beschreibungen kurz: Claude Code zeigt eine Startwarnmeldung an, wenn die kombinierten Beschreibungen Ihrer Subagenten das [Limit von 15.000 Token](/docs/de/errors#agent-descriptions-are-over-the-15000-token-limit) überschreiten, und lädt dennoch jeden Subagenten.

851 854

852<h3 id="invoke-subagents-explicitly">855<h3 id="invoke-subagents-explicitly">

853 Rufen Sie Subagenten explizit auf856 Subagenten explizit aufrufen

854</h3>857</h3>

855 858

856Wenn automatische Delegation nicht ausreicht, können Sie einen Subagenten selbst anfordern. Drei Muster eskalieren von einem einmaligen Vorschlag zu einem sitzungsweiten Standard:859Wenn automatische Delegierung nicht ausreicht, können Sie einen Subagenten selbst anfordern. Drei Muster eskalieren von einem einmaligen Vorschlag zu einem sitzungsweiten Standard:

857 860

858* **Natürliche Sprache**: Nennen Sie den Subagenten in Ihrem Prompt; Claude entscheidet, ob delegiert werden soll861* **Natürliche Sprache**: Nennen Sie den Subagenten in Ihrer Eingabeaufforderung; Claude entscheidet, ob delegiert werden soll

859* **@-Erwähnung**: Garantiert, dass der Subagent für eine Aufgabe ausgeführt wird862* **@-Erwähnung**: Garantiert, dass der Subagent für eine Aufgabe ausgeführt wird

860* **Sitzungsweit**: Die gesamte Sitzung verwendet den Systemprompt, die Werkzeugbeschränkungen und das Modell dieses Subagenten über das `--agent`-Flag oder die `agent`-Einstellung863* **Sitzungsweit**: Die gesamte Sitzung verwendet die Systemeingabeaufforderung, Werkzeugbeschränkungen und das Modell dieses Subagenten über das Flag `--agent` oder die Einstellung `agent`

861 864

862Für natürliche Sprache gibt es keine spezielle Syntax. Nennen Sie den Subagenten und Claude delegiert normalerweise:865Für natürliche Sprache gibt es keine spezielle Syntax. Nennen Sie den Subagenten und Claude delegiert normalerweise:

863 866

866Have the code-reviewer subagent look at my recent changes869Have the code-reviewer subagent look at my recent changes

867```870```

868 871

869**@-Erwähnen Sie den Subagenten.** Geben Sie `@` ein und wählen Sie den Subagenten aus der Typeahead-Liste, genauso wie Sie Dateien @-erwähnen. Dies stellt sicher, dass dieser spezifische Subagent ausgeführt wird, anstatt die Wahl Claude zu überlassen:872**Erwähnen Sie den Subagenten mit @.** Geben Sie `@` ein und wählen Sie den Subagenten aus der Typvorhersage aus, genauso wie Sie Dateien mit @ erwähnen. Dies stellt sicher, dass dieser spezifische Subagent ausgeführt wird, anstatt die Wahl Claude zu überlassen:

870 873

871```text wrap theme={null}874```text wrap theme={null}

872@"code-reviewer (agent)" look at the auth changes875@"code-reviewer (agent)" look at the auth changes

873```876```

874 877

875Ihre vollständige Nachricht geht immer noch an Claude, das den Task-Prompt des Subagenten basierend auf Ihrer Anfrage schreibt. Die @-Erwähnung steuert, welcher Subagent Claude aufruft, nicht welchen Prompt er erhält.878Ihre vollständige Nachricht geht immer noch an Claude, der die Aufgabeneingabeaufforderung des Subagenten basierend auf Ihrer Anfrage schreibt. Die @-Erwähnung steuert, welcher Subagent Claude aufruft, nicht welche Eingabeaufforderung er erhält.

876 879

877Subagenten, die von einem aktivierten [Plugin](/docs/de/plugins) bereitgestellt werden, erscheinen in der Typeahead-Liste unter ihrem scoped Namen, z. B. `my-plugin:code-reviewer` oder `my-plugin:review:security`, wenn das Plugin [Agenten in Unterordnern organisiert](#choose-the-subagent-scope). Benannte Hintergrund-Subagenten, die derzeit in der Sitzung ausgeführt werden, erscheinen auch in der Typeahead-Liste und zeigen ihren Status neben dem Namen an.880Subagenten, die von einem aktivierten [Plugin](/docs/de/plugins) bereitgestellt werden, erscheinen in der Typvorhersage unter ihrem Bereichsnamen, z. B. `my-plugin:code-reviewer` oder `my-plugin:review:security`, wenn das Plugin [Agenten in Unterordnern organisiert](#choose-the-subagent-scope). Benannte Hintergrund-Subagenten, die derzeit in der Sitzung ausgeführt werden, erscheinen auch in der Typvorhersage und zeigen ihren Status neben dem Namen an.

878 881

879Sie können die Erwähnung auch manuell eingeben, ohne den Picker zu verwenden: `@agent-<name>` für lokale Subagenten, oder `@agent-` gefolgt vom scoped Namen für Plugin-Subagenten, z. B. `@agent-my-plugin:code-reviewer`. Während Sie diese Form eingeben, zeigt die Typeahead-Liste Dateien statt Agenten an. Die Agent-Erwähnung wird trotzdem aufgelöst, wenn Sie absenden.882Sie können die Erwähnung auch manuell eingeben, ohne die Auswahl zu verwenden: `@agent-<name>` für lokale Subagenten oder `@agent-` gefolgt vom Bereichsnamen für Plugin-Subagenten, z. B. `@agent-my-plugin:code-reviewer`. Während Sie dieses Formular eingeben, zeigt die Typvorhersage Dateienübereinstimmungen anstelle von Agenten. Die Agent-Erwähnung wird trotzdem aufgelöst, wenn Sie absenden.

880 883

881**Führen Sie die gesamte Sitzung als Subagent aus.** Übergeben Sie [`--agent <name>`](/docs/de/cli-reference), um eine Sitzung zu starten, in der der Hauptthread selbst den Systemprompt, die Werkzeugbeschränkungen und das Modell dieses Subagenten annimmt:884**Führen Sie die gesamte Sitzung als Subagent aus.** Übergeben Sie [`--agent <name>`](/docs/de/cli-reference), um eine Sitzung zu starten, in der der Hauptthread selbst die Systemeingabeaufforderung, Werkzeugbeschränkungen und das Modell dieses Subagenten übernimmt:

882 885

883```bash theme={null}886```bash theme={null}

884claude --agent code-reviewer887claude --agent code-reviewer

885```888```

886 889

887Der Systemprompt des Subagenten ersetzt den Standard-Claude Code-Systemprompt vollständig, genauso wie [`--system-prompt`](/docs/de/cli-reference) es tut. `CLAUDE.md`-Dateien und Projekt-Memory werden weiterhin durch den normalen Nachrichtenfluss geladen. Der Agent-Name erscheint als `@<name>` in der Startup-Kopfzeile, damit Sie bestätigen können, dass er aktiv ist.890Die Systemeingabeaufforderung des Subagenten ersetzt die Standard-Claude-Code-Systemeingabeaufforderung vollständig, genauso wie [`--system-prompt`](/docs/de/cli-reference) es tut. `CLAUDE.md`-Dateien und Projektgedächtnis werden immer noch durch den normalen Nachrichtenfluss geladen, auch wenn die Agent-Definition [`omitClaudeMd`](#supported-frontmatter-fields) setzt.

891

892Der Agent-Name erscheint als `@<name>` in der Startkopfzeile, damit Sie bestätigen können, dass er aktiv ist.

888 893

889Dies funktioniert mit integrierten und benutzerdefinierten Subagenten, und die Wahl bleibt bestehen, wenn Sie die Sitzung fortsetzen: Claude Code stellt den Systemprompt, die Werkzeugbeschränkungen und das Modell des Agenten zusammen mit der Konversation wieder her. Wenn der Agent nicht mehr vorhanden ist, wenn Sie fortsetzen, wird die Sitzung mit den Standard-Tools fortgesetzt und zeigt eine [Warnung mit dem Namen des Agenten](/docs/de/errors#session-agent-no-longer-available). Für den Systemprompt in beiden Fällen siehe [Systemprompt-Flags in fortgesetzten Konversationen](/docs/de/cli-reference#system-prompt-flags-in-resumed-conversations).894Dies funktioniert mit integrierten und benutzerdefinierten Subagenten, und die Wahl bleibt bestehen, wenn Sie die Sitzung fortsetzen: Claude Code stellt die Werkzeugbeschränkungen und das Modell des Agenten zusammen mit der Konversation wieder her. Wenn der Agent nicht mehr vorhanden ist, wenn Sie fortsetzen, wird die Sitzung mit den Standardwerkzeugen fortgesetzt und zeigt eine [Warnung mit dem Namen des Agenten](/docs/de/errors#session-agent-no-longer-available). Für die Systemeingabeaufforderung in beiden Fällen siehe [Systemeingabeaufforderungs-Flags in fortgesetzten Konversationen](/docs/de/cli-reference#system-prompt-flags-in-resumed-conversations).

890 895

891Für einen von einem Plugin bereitgestellten Subagenten können Sie einfach den Agent-Namen übergeben und Claude Code findet ihn:896Für einen von einem Plugin bereitgestellten Subagenten können Sie nur den Agent-Namen übergeben und Claude Code findet ihn:

892 897

893```bash theme={null}898```bash theme={null}

894claude --agent security-reviewer899claude --agent security-reviewer

895```900```

896 901

897Wenn mehrere Plugins Agenten mit demselben Namen bereitstellen, übergeben Sie den scoped Namen zur Disambiguierung:902Wenn mehrere Plugins Agenten mit demselben Namen bereitstellen, übergeben Sie den Bereichsnamen zur Disambiguierung:

898 903

899```bash theme={null}904```bash theme={null}

900claude --agent my-plugin:security-reviewer905claude --agent my-plugin:security-reviewer

901```906```

902 907

903Wenn das Plugin den Agenten in einem Unterordner seines `agents/`-Verzeichnisses platziert, fügen Sie den Unterordner in den scoped Namen ein, z. B. `claude --agent my-plugin:review:security`.908Wenn das Plugin den Agenten in einem Unterordner seines `agents/`-Verzeichnisses platziert, fügen Sie den Unterordner in den Bereichsnamen ein, z. B. `claude --agent my-plugin:review:security`.

904 909

905Um es zum Standard für jede Sitzung in einem Projekt zu machen, setzen Sie `agent` in `.claude/settings.json`:910Um es zum Standard für jede Sitzung in einem Projekt zu machen, setzen Sie `agent` in `.claude/settings.json`:

906 911

913Das CLI-Flag überschreibt die Einstellung, wenn beide vorhanden sind.918Das CLI-Flag überschreibt die Einstellung, wenn beide vorhanden sind.

914 919

915<h3 id="run-subagents-in-foreground-or-background">920<h3 id="run-subagents-in-foreground-or-background">

916 Führen Sie Subagenten im Vordergrund oder Hintergrund aus921 Subagenten im Vordergrund oder Hintergrund ausführen

917</h3>922</h3>

918 923

919Subagenten können im Vordergrund oder im Hintergrund ausgeführt werden:924Subagenten können im Vordergrund oder im Hintergrund ausgeführt werden:

920 925

921* **Vordergrund-Subagenten** blockieren die Hauptkonversation bis zur Fertigstellung. Berechtigungsaufforderungen werden an Sie weitergeleitet, wenn sie auftreten.926* **Vordergrund-Subagenten** blockieren die Hauptkonversation bis zur Fertigstellung. Genehmigungseingabeaufforderungen werden an Sie weitergeleitet, wenn sie auftauchen.

922* **Hintergrund-Subagenten** laufen gleichzeitig, während Sie weiterarbeiten. Wenn ein Hintergrund-Subagent einen Werkzeugaufruf erreicht, der Berechtigung benötigt, wird die Aufforderung in Ihrer Hauptsitzung angezeigt und nennt den Subagenten, der fragt. Genehmigen Sie, um den Subagenten fortzusetzen, oder drücken Sie Esc, um diesen einen Werkzeugaufruf zu verweigern, ohne den Subagenten zu stoppen. Vor v2.1.186 lehnten Hintergrund-Subagenten automatisch jeden Werkzeugaufruf ab, der eine Aufforderung ausgelöst hätte.927* **Hintergrund-Subagenten** werden gleichzeitig ausgeführt, während Sie weiterarbeiten. Wenn ein Hintergrund-Subagent einen Werkzeugaufruf erreicht, der eine Genehmigung benötigt, zeigt Claude Code die Eingabeaufforderung in Ihrer Hauptsitzung an und nennt den Subagenten, der fragt. Genehmigen Sie, um den Subagenten fortsetzen zu lassen, oder drücken Sie Esc, um diesen einen Werkzeugaufruf zu verweigern, ohne den Subagenten zu stoppen. Vor v2.1.186 verweigerten Hintergrund-Subagenten automatisch jeden Werkzeugaufruf, der eine Eingabeaufforderung verursacht hätte.

923 928

924Für jeden Subagenten, den Claude mit dem Agent-Werkzeug spawnt, wählt Claude Code Vordergrund oder Hintergrund aus dem ersten dieser Fälle, der zutrifft:929Für jeden Subagenten, den Claude mit dem Agent-Werkzeug spawnt, wählt Claude Code Vordergrund oder Hintergrund aus dem ersten dieser Fälle, der zutrifft:

925 930

926* Wenn ein In-Process-[Agent-Team](/docs/de/agent-teams#limitations)-Teamkollege den Subagenten spawnt, führt Claude Code ihn im Vordergrund aus. Claude Code weigert sich mit einem Fehler, einen Subagenten eines Teamkollegen zu spawnen, dessen Definition [`background: true`](#supported-frontmatter-fields) setzt. Wenn [Fork-Modus](#turn-fork-mode-on-or-off) aus ist und Sie [Hintergrund-Aufgaben nicht ausgeschaltet haben](/docs/de/env-vars), weigert sich Claude Code auch mit einem Fehler, wenn ein Teamkollege `run_in_background: true` setzt.931* Wenn ein In-Process-[Agent-Team](/docs/de/agent-teams#limitations)-Teamkollege den Subagenten spawnte, führt Claude Code ihn im Vordergrund aus. Claude Code weigert sich mit einem Fehler, einen Teamkollegen-Subagenten zu spawnen, dessen Definition [`background: true`](#supported-frontmatter-fields) setzt. Wenn [Fork-Modus](#turn-fork-mode-on-or-off) aus ist und Sie [Hintergrund-Aufgaben nicht ausgeschaltet haben](/docs/de/env-vars), weigert sich Claude Code auch mit einem Fehler, wenn ein Teamkollege `run_in_background: true` setzt.

927* Wenn Sie [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/de/env-vars) auf `1` setzen, führt Claude Code den Subagenten im Vordergrund aus, in jeder Art von Sitzung und unabhängig davon, ob Fork-Modus an ist.932* Wenn Sie [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/de/env-vars) auf `1` setzen, führt Claude Code den Subagenten im Vordergrund aus, in jeder Art von Sitzung und unabhängig davon, ob Fork-Modus an ist.

928* Wenn [Fork-Modus](#turn-fork-mode-on-or-off) an ist, wie es standardmäßig in einer interaktiven Sitzung der Fall ist, führt Claude Code den Subagenten im Hintergrund aus, sowohl Fork- als auch Nicht-Fork-Subagenten, und Claude kann nicht den Vordergrund anfordern.933* Wenn [Fork-Modus](#turn-fork-mode-on-or-off) an ist, wie es standardmäßig in einer interaktiven Sitzung der Fall ist, führt Claude Code den Subagenten im Hintergrund aus, sowohl Fork- als auch Non-Fork-Subagenten, und Claude kann nicht den Vordergrund anfordern.

929* Wenn Fork-Modus aus ist, führt Claude den Subagenten standardmäßig im Hintergrund aus und im Vordergrund, wenn er das Ergebnis benötigt, bevor er fortfährt. Fork-Modus ist aus im [nicht-interaktiven Modus](/docs/de/headless) mit `-p` und im Agent SDK, es sei denn, Sie schalten ihn ein. Um einen bestimmten Subagenten im Hintergrund zu halten, auch wenn Claude das Ergebnis benötigt, setzen Sie sein Frontmatter-Feld [`background`](#supported-frontmatter-fields) auf `true`.934* Wenn Fork-Modus aus ist, führt Claude den Subagenten standardmäßig im Hintergrund aus und im Vordergrund, wenn er das Ergebnis benötigt, bevor er fortfährt. Fork-Modus ist aus im [nicht-interaktiven Modus](/docs/de/headless) mit `-p` und im Agent SDK, es sei denn, Sie schalten ihn ein. Um einen bestimmten Subagenten im Hintergrund zu halten, auch wenn Claude das Ergebnis möchte, setzen Sie sein Frontmatter-Feld [`background`](#supported-frontmatter-fields) auf `true`.

930 935

931Für eine Skill mit `context: fork` folgt Claude Code stattdessen den Regeln in [Führen Sie Skills in einem Subagenten aus](/docs/de/skills#run-skills-in-a-subagent), unabhängig davon, ob Fork-Modus an ist.936Für eine Skill mit `context: fork` folgt Claude Code stattdessen den Regeln in [Führen Sie Skills in einem Subagenten aus](/docs/de/skills#run-skills-in-a-subagent), unabhängig davon, ob Fork-Modus an ist.

932 937

933Hintergrund-Subagenten laufen mit einem [kleineren integrierten Werkzeugsatz](#available-tools) als Vordergrund-Subagenten, außer für Konversations-Forks und [fortgesetzte](#resume-subagents) Vordergrund-Subagenten.938Hintergrund-Subagenten werden mit einem [kleineren integrierten Werkzeugsatz](#available-tools) als Vordergrund-Subagenten ausgeführt, außer für Konversations-Forks und [fortgesetzte](#resume-subagents) Vordergrund-Subagenten.

934 939

935Hintergrund-Subagenten zeigen jede Berechtigungsaufforderung in Ihrer Hauptsitzung an. Wenn Sie eine dieser Aufforderungen mit einer Wahl beantworten, die über diesen einen Werkzeugaufruf hinausgeht, z. B. eine Genehmigung, die für den Rest der Sitzung gilt, wendet Claude Code Ihre Antwort auf die gesamte Sitzung an, einschließlich Ihrer Hauptkonversation.940Hintergrund-Subagenten zeigen jede Genehmigungseingabeaufforderung in Ihrer Hauptsitzung an. Wenn Sie eine dieser Eingabeaufforderungen mit einer Wahl beantworten, die über diesen einen Werkzeugaufruf hinausgeht, z. B. eine Genehmigung, die für den Rest der Sitzung gilt, wendet Claude Code Ihre Antwort auf die gesamte Sitzung an, einschließlich Ihrer Hauptkonversation.

936 941

937Ein Hintergrund-Subagent kann einen Hintergrund-[Bash- oder PowerShell-Befehl](/docs/de/tools-reference#background-commands) [über das Ende seiner Runde hinaus laufen lassen](/docs/de/interactive-mode#how-backgrounding-works). Wenn dieser Befehl endet, sendet Claude Code dem Subagenten eine Benachrichtigung.942Ein Hintergrund-Subagent kann einen Hintergrund-[Bash- oder PowerShell-Befehl](/docs/de/tools-reference#background-commands) [über das Ende seines Zuges hinaus laufen lassen](/docs/de/interactive-mode#how-backgrounding-works). Wenn dieser Befehl endet, sendet Claude Code dem Subagenten eine Benachrichtigung.

938 943

939Die Ergebnisse eines Hintergrund-Subagenten erreichen Claude als Abschlussbenachrichtigung in einer späteren Runde. Claude wartet auf diese Benachrichtigung, bevor er die Ergebnisse des Subagenten meldet, und wenn Sie zuerst nach Fortschritt fragen, meldet er, dass der Subagent noch läuft. Vor v2.1.211 meldete Claude manchmal Ergebnisse für einen Hintergrund-Subagenten, der noch nicht fertig war.944Die Ergebnisse eines Hintergrund-Subagenten erreichen Claude als Abschlussbenachrichtigung in einem späteren Zug. Claude wartet auf diese Benachrichtigung, bevor er die Ergebnisse des Subagenten meldet, und wenn Sie zuerst nach Fortschritt fragen, meldet er, dass der Subagent noch läuft. Vor v2.1.211 meldete Claude manchmal Ergebnisse für einen Hintergrund-Subagenten, der nicht fertig war.

940 945

941Sie können auch selbst steuern:946Sie können dies auch selbst steuern:

942 947

943* Wenn Fork-Modus aus ist, bitten Sie Claude, eine Aufgabe im Hintergrund oder im Vordergrund auszuführen948* Wenn Fork-Modus aus ist, bitten Sie Claude, eine Aufgabe im Hintergrund oder im Vordergrund auszuführen

944* Drücken Sie **Ctrl+B**, um eine laufende Aufgabe in den Hintergrund zu verschieben949* Drücken Sie **Strg+B**, um eine laufende Aufgabe in den Hintergrund zu verschieben

945 950

946Claude Code löscht eine Zeile eines Hintergrund-Subagenten aus dem Subagenten-Panel unter der Eingabeaufforderung auf eine von zwei Arten, je nachdem, wie der Subagent endete:951Claude Code löscht die Zeile eines Hintergrund-Subagenten aus dem Subagenten-Panel unter der Eingabeaufforderungseingabe auf eine von zwei Arten, je nachdem, wie der Subagent endete:

947 952

948* Wenn ein Subagent erfolgreich fertig wird, entfernt Claude Code seine Zeile sofort und zeigt außer im [Bildschirmlesemodus](/docs/de/accessibility) `/tasks to see subagents` in der Fußzeile für 30 Sekunden an. Während dieser 30 Sekunden führen Sie [`/tasks`](/docs/de/commands) aus und drücken `Enter` auf dem Subagenten, um sein Transkript zu öffnen. Vor v2.1.232 behielt Claude Code die Zeile 30 Sekunden nach Fertigstellung des Subagenten, genauso wie einen fehlgeschlagenen, und zeigte keinen Fußzeilentipp.953* Wenn ein Subagent erfolgreich beendet wird, entfernt Claude Code seine Zeile sofort und zeigt außer im [Bildschirmlesemodus](/docs/de/accessibility) `/tasks to see subagents` in der Fußzeile für 30 Sekunden an. Führen Sie während dieser 30 Sekunden [`/tasks`](/docs/de/commands) aus und drücken Sie `Enter` auf dem Subagenten, um sein Transkript zu öffnen. Vor v2.1.232 behielt Claude Code die Zeile 30 Sekunden nach Beendigung des Subagenten, genauso wie eine fehlgeschlagene, und zeigte keinen Fußzeilentipp.

949* Wenn ein Subagent fehlschlägt oder Sie ihn stoppen, behält Claude Code seine Zeile für 30 Sekunden. Um die Zeile früher zu löschen, wählen Sie sie aus und drücken `x`.954* Wenn ein Subagent fehlschlägt oder Sie ihn stoppen, behält Claude Code seine Zeile 30 Sekunden lang. Um die Zeile schneller zu löschen, wählen Sie sie aus und drücken Sie `x`.

950 955

951Ein Hintergrund-Subagent, der abgeschlossen ist, bleibt in [`/tasks`](/docs/de/commands) aufgelistet, als erledigt markiert und unter laufenden Arbeiten sortiert, für dasselbe Fenster wie der Fußzeilentipp oben. Seine Detailansicht bleibt offen, wenn der Subagent fertig ist. Subagenten, die fehlschlagen oder die Sie stoppen, verlassen die Liste. Vor v2.1.208 verließ ein abgeschlossener Subagent die Liste in dem Moment, in dem er fertig war, und seine Detailansicht schloss sich.956Ein Hintergrund-Subagent, der abgeschlossen ist, bleibt in [`/tasks`](/docs/de/commands) aufgelistet, als erledigt markiert und unter laufender Arbeit sortiert, für die gleichen 30 Sekunden wie der Fußzeilentipp. Seine Detailansicht bleibt offen, wenn der Subagent beendet wird. Subagenten, die fehlschlagen oder die Sie stoppen, verlassen die Liste. Vor v2.1.208 verließ ein abgeschlossener Subagent die Liste in dem Moment, in dem er beendet wurde, und seine Detailansicht schloss sich.

952 957

953<h3 id="subagent-names">958<h3 id="subagent-names">

954 Subagenten-Namen959 Subagenten-Namen

955</h3>960</h3>

956 961

957Claude kann einem Subagenten einen Namen geben, indem er einen `name`-Parameter beim Agent-Werkzeugaufruf übergibt, und kann dies von sich aus tun, ohne Sie zuerst zu fragen. Der Name macht den Subagenten adressierbar: Claude kann ihn [nach Fertigstellung nach Name ansprechen oder fortsetzen](#resume-subagents).962Claude kann einem Subagenten einen Namen geben, indem er einen `name`-Parameter beim Agent-Werkzeugaufruf übergibt, und kann dies auch von selbst tun, ohne Sie zuerst zu fragen. Der Name macht den Subagenten adressierbar: Claude kann ihn [nach Abschluss nach Name ansprechen oder fortsetzen](#resume-subagents).

958 963

959In einer interaktiven Sitzung mit aktivierten [Agent-Teams](/docs/de/agent-teams) wird ein Subagent, den Claude aus der Hauptkonversation mit einem `name` spawnt, stattdessen als Teamkollege gestartet, es sei denn, der Aufruf ist ein [Fork](#fork-the-current-conversation) oder übergibt `isolation` beim Aufruf selbst. Ein `isolation`-Wert im Frontmatter des Subagenten verhindert es nicht, und der Teamkollege läuft dann im Arbeitsverzeichnis der Hauptsitzung. Siehe [Wie Claude Agent-Teams startet](/docs/de/agent-teams#how-claude-starts-agent-teams).964In einer interaktiven Sitzung mit aktivierten [Agent-Teams](/docs/de/agent-teams) wird ein Subagent, den Claude aus der Hauptkonversation mit einem `name` spawnt, stattdessen als Teamkollege gestartet, es sei denn, der Aufruf ist ein [Fork](#fork-the-current-conversation) oder übergibt `isolation` beim Aufruf selbst. Ein `isolation`-Wert in der Frontmatter des Subagenten verhindert es nicht, und der Teamkollege wird dann im Arbeitsverzeichnis der Hauptsitzung ausgeführt. Siehe [Wie Claude Agent-Teams startet](/docs/de/agent-teams#how-claude-starts-agent-teams).

960 965

961<h3 id="api-errors-in-subagents">966<h3 id="api-errors-in-subagents">

962 API-Fehler in Subagenten967 API-Fehler in Subagenten

963</h3>968</h3>

964 969

965Wenn etwas [einen Subagenten-Response mid-stream unterbricht](/docs/de/errors#the-response-above-may-be-incomplete), und die Teilantwort Text enthält, aber keine Werkzeugaufrufe, fordert Claude Code den Subagenten auf, fortzufahren, anstatt die Ausführung zu beenden. Dies geschieht auch in interaktiven Sitzungen. Die Ausführung endet beim Fehler nur, wenn diese Fortsetzungen aufgebraucht sind.970Wenn etwas [die Antwort eines Subagenten mitten im Stream unterbricht](/docs/de/errors#the-response-above-may-be-incomplete), und die teilweise Antwort Text enthält, aber keine Werkzeugaufrufe, fordert Claude Code den Subagenten auf, fortzufahren, anstatt den Lauf zu beenden. Dies geschieht auch in interaktiven Sitzungen. Der Lauf endet beim Fehler nur, wenn diese Fortsetzungen aufgebraucht sind.

966 971

967Ab v2.1.199 meldet ein Subagent, dessen Ausführung mit einem API-Fehler endet, z. B. ein Nutzungslimit oder ein wiederholter Serverfehler, diesen Fehler an Claude zurück, anstatt den Fehlertext so zurückzugeben, als wären es die Erkenntnisse des Subagenten. Was Claude erhält, hängt davon ab, wo der Subagent ausgeführt wurde:972Ab v2.1.199 meldet ein Subagent, dessen Lauf bei einem API-Fehler endet, z. B. bei einem Nutzungslimit oder wiederholtem Serverfehler, diesen Fehler an Claude zurück, anstatt den Fehlertext so zurückzugeben, als wären es die Erkenntnisse des Subagenten. Was Claude erhält, hängt davon ab, wo der Subagent lief:

968 973

969* **Vordergrund**: Wenn ein Ratenlimit, eine Überlastung oder ein Serverfehler einen Subagenten unterbricht, der bereits Textausgabe erzeugt hat, gibt das Agent-Werkzeug diese Teilausgabe mit einem Hinweis zurück, dass der Subagent unterbrochen wurde und seine Aufgabe nicht abgeschlossen hat. Ein Subagent, der nichts erzeugt hat, oder dessen einzige Ausgabe Werkzeugaufrufe waren, schlägt mit [`Agent terminated early due to an API error`](/docs/de/errors#agent-terminated-early-due-to-an-api-error) fehl, gefolgt von der Fehlerdetail. In v2.1.199 gab ein Ratenlimit, eine Überlastung oder ein Serverfehler, der die Form nur mit Werkzeugaufrufen unterbrach, ein leeres Teilergebnis zurück, das nur den Unterbrechungshinweis enthielt.974* **Vordergrund**: Wenn ein Ratenlimit, eine Überlastung oder ein Serverfehler einen Subagenten unterbricht, der bereits Textausgabe produziert hat, gibt das Agent-Werkzeug diese teilweise Ausgabe mit einer Notiz zurück, dass der Subagent unterbrochen wurde und seine Aufgabe nicht abgeschlossen hat. Ein Subagent, der nichts produziert hat oder dessen einzige Ausgabe Werkzeugaufrufe waren, schlägt mit [`Agent terminated early due to an API error`](/docs/de/errors#agent-terminated-early-due-to-an-api-error) fehl, gefolgt von der Fehlerdetail. In v2.1.199 gab ein Ratenlimit, eine Überlastung oder ein Serverfehler, der die Form „nur Werkzeugaufrufe" unterbrach, ein leeres teilweises Ergebnis zurück, das nur die Unterbrechungsnotiz enthielt.

970* **Hintergrund**: Der Subagent wird als fehlgeschlagen markiert, und die Nachricht, die Claude erhält, wenn er endet, nennt den API-Fehler und enthält die letzte Ausgabe des Subagenten, sodass Teilarbeit nicht verloren geht.975* **Hintergrund**: Der Subagent wird als fehlgeschlagen markiert, und die Nachricht, die Claude erhält, wenn er endet, nennt den API-Fehler und enthält die letzte Ausgabe des Subagenten, sodass teilweise Arbeit nicht verloren geht.

971 976

972Wenn Sie eine [Fallback-Modellkette](/docs/de/model-config#fallback-model-chains) konfigurieren und ein Subagent auf einen Fehler trifft, den die Kette abdeckt, z. B. dass sein Modell nicht verfügbar ist, wechselt Claude Code den Subagenten zum ersten Modell in der Kette, das die Anfrage akzeptiert. Der Subagent arbeitet weiter, anstatt beim Fehler zu enden.977Wenn Sie eine [Fallback-Modellkette](/docs/de/model-config#fallback-model-chains) konfigurieren und ein Subagent auf einen Fehler trifft, den die Kette abdeckt, z. B. dass sein Modell nicht verfügbar ist, wechselt Claude Code den Subagenten zum ersten Modell in der Kette, das die Anfrage akzeptiert. Der Subagent arbeitet weiter, anstatt beim Fehler zu enden.

973 978

974Sobald der zugrunde liegende API-Fehler behoben ist, bitten Sie Claude, die Aufgabe zu wiederholen oder [setzen Sie den Subagenten fort](#resume-subagents).979Sobald der zugrunde liegende API-Fehler behoben ist, bitten Sie Claude, die Aufgabe zu wiederholen oder [den Subagenten fortzusetzen](#resume-subagents).

975 980

976<h3 id="subagent-output-scanning">981<h3 id="subagent-output-scanning">

977 Subagenten-Ausgabe-Scanning982 Subagenten-Ausgabe-Scanning

978</h3>983</h3>

979 984

980Claude Code scannt den abschließenden Bericht jedes Subagenten, bevor Claude ihn liest. Ein Subagent kann Dateien, Webseiten oder Befehlsausgaben gelesen haben, die Sie nie überprüft haben, und Text aus diesen Quellen kann Anweisungen enthalten, die auf die Hauptkonversation abzielen. Der Scan entfernt oder umformuliert niemals etwas; er nimmt zwei Arten von Änderungen vor, die Sie in einem Bericht bemerken können:985Claude Code scannt den endgültigen Bericht jedes Subagenten, bevor Claude ihn liest. Ein Subagent kann Dateien, Webseiten oder Befehlsausgaben gelesen haben, die Sie nie überprüft haben, und Text aus diesen Quellen kann Anweisungen enthalten, die auf die Hauptkonversation abzielen. Der Scan entfernt oder umformuliert niemals etwas; er nimmt zwei Arten von Änderungen vor, die Sie möglicherweise in einem Bericht bemerken:

981 986

982* **Backslash-Einfügung**: Der Scan fügt einen Backslash in Text ein, der Claude Code's eigene Ausgabe imitiert, z. B. ein `<system-reminder>`-Tag oder eine Zeile, die mit `Human:` oder `Assistant:` beginnt, damit die Imitation als gewöhnlicher Text gelesen wird, anstatt als Teil der Konversation verwechselt zu werden.987* **Backslash-Einfügung**: Der Scan fügt einen Backslash in Text ein, der Claude Codes eigene Ausgabe imitiert, z. B. ein `<system-reminder>`-Tag oder eine Zeile, die mit `Human:` oder `Assistant:` beginnt, damit die Imitation als gewöhnlicher Text gelesen wird, anstatt als Teil der Konversation verwechselt zu werden.

983* **Marker-Zeile**: Der Scan stellt eine Zeile voran, die mit `[harness: subagent output matched instruction-shaped pattern(s):` beginnt, wenn der Bericht ein Tag wie `<system-reminder>` imitiert oder Berechtigungseinstellungen wie `bypassPermissions` oder `--dangerously-skip-permissions` erwähnt. Berechtigungseinstellungs-Erwähnungen erhalten die Marker-Zeile, aber der Text selbst bleibt wie geschrieben.988* **Marker-Zeile**: Der Scan stellt eine Zeile voran, die mit `[harness: subagent output matched instruction-shaped pattern(s):` beginnt, wenn der Bericht ein Tag wie `<system-reminder>` imitiert oder Genehmigungseinstellungen wie `bypassPermissions` oder `--dangerously-skip-permissions` erwähnt. Genehmigungseinstellungs-Erwähnungen erhalten die Marker-Zeile, aber der Text selbst bleibt wie geschrieben.

984 989

985Der Scan beurteilt nicht, ob Inhalte bösartig sind, und er ändert nicht, was eine Anweisung in einem Bericht tun kann: Ein Werkzeugaufruf, zu dem der Bericht Claude führt, durchläuft immer noch die [Berechtigungsprüfungen](/docs/de/permissions) und [Sandboxing](/docs/de/sandboxing) der Sitzung. Es ist kein Ersatz für [Einschränkung, was ein Subagent erreichen kann](#control-subagent-capabilities).990Der Scan beurteilt nicht, ob Inhalte bösartig sind, und er ändert nicht, was eine Anweisung in einem Bericht tun kann: Ein Werkzeugaufruf, zu dem der Bericht Claude führt, durchläuft immer noch die [Genehmigungsprüfungen](/docs/de/permissions) und [Sandboxing](/docs/de/sandboxing) der Sitzung. Es ist kein Ersatz für [Einschränkung, was ein Subagent erreichen kann](#control-subagent-capabilities).

986 991

987<Note>992<Note>

988 Subagenten-Ausgabe-Scanning erfordert Claude Code v2.1.210 oder später.993 Das Subagenten-Ausgabe-Scanning erfordert Claude Code v2.1.210 oder später.

989</Note>994</Note>

990 995

991<h3 id="common-patterns">996<h3 id="common-patterns">

996 Isolieren Sie hochvolumige Operationen1001 Isolieren Sie hochvolumige Operationen

997</h4>1002</h4>

998 1003

999Eine der effektivsten Verwendungen für Subagenten ist die Isolierung von Operationen, die große Mengen an Ausgaben erzeugen. Das Ausführen von Tests, das Abrufen von Dokumentation oder die Verarbeitung von Protokolldateien kann erheblichen Kontext verbrauchen. Durch die Delegierung an einen Subagenten bleibt die ausführliche Ausgabe im Kontext des Subagenten, während nur die relevante Zusammenfassung zu Ihrer Hauptkonversation zurückkehrt.1004Eine der effektivsten Verwendungen für Subagenten ist die Isolierung von Operationen, die große Mengen an Ausgabe produzieren. Das Ausführen von Tests, das Abrufen von Dokumentation oder das Verarbeiten von Protokolldateien kann erheblichen Kontext verbrauchen. Durch die Delegierung dieser an einen Subagenten bleibt die ausführliche Ausgabe im Kontext des Subagenten, während nur die relevante Zusammenfassung zu Ihrer Hauptkonversation zurückkehrt.

1000 1005

1001```text wrap theme={null}1006```text wrap theme={null}

1002Use a subagent to run the test suite and report only the failing tests with their error messages1007Use a subagent to run the test suite and report only the failing tests with their error messages

1003```1008```

1004 1009

1005<h4 id="run-parallel-research">1010<h4 id="run-parallel-research">

1006 Führen Sie parallele Recherche durch1011 Führen Sie parallele Recherchen durch

1007</h4>1012</h4>

1008 1013

1009Für unabhängige Untersuchungen spawnen Sie mehrere Subagenten, um gleichzeitig zu arbeiten:1014Für unabhängige Untersuchungen spawnen Sie mehrere Subagenten, um gleichzeitig zu arbeiten:

1012Research the authentication, database, and API modules in parallel using separate subagents1017Research the authentication, database, and API modules in parallel using separate subagents

1013```1018```

1014 1019

1015Jeder Subagent erkundet seinen Bereich unabhängig, dann synthetisiert Claude die Erkenntnisse. Dies funktioniert am besten, wenn die Recherchepfade nicht voneinander abhängen.1020Jeder Subagent erkundet seinen Bereich unabhängig, dann synthetisiert Claude die Erkenntnisse. Dies funktioniert am besten, wenn die Forschungspfade nicht voneinander abhängen.

1016 1021

1017<Warning>1022<Warning>

1018 Wenn Subagenten abgeschlossen sind, kehren ihre Ergebnisse zu Ihrer Hauptkonversation zurück. Das Ausführen vieler Subagenten, die jeweils detaillierte Ergebnisse zurückgeben, kann erheblichen Kontext verbrauchen.1023 Wenn Subagenten abgeschlossen sind, kehren ihre Ergebnisse zu Ihrer Hauptkonversation zurück. Das Ausführen vieler Subagenten, die jeweils detaillierte Ergebnisse zurückgeben, kann erheblichen Kontext verbrauchen.

1019</Warning>1024</Warning>

1020 1025

1021Für Aufgaben, die anhaltende Parallelität benötigen oder Ihr Kontextfenster nicht passen, führen Sie sie in [separaten Sitzungen](/docs/de/agents) aus und lassen Sie Claude [Erkenntnisse zwischen ihnen weitergeben](/docs/de/cross-session-messaging).1026Für Arbeit, die parallel weiterläuft oder nicht in ein Kontextfenster passt, führen Sie sie in [separaten Sitzungen](/docs/de/agents) aus und lassen Sie Claude [Erkenntnisse zwischen ihnen weitergeben](/docs/de/cross-session-messaging).

1022 1027

1023<h4 id="chain-subagents">1028<h4 id="chain-subagents">

1024 Verketten Sie Subagenten1029 Verketten Sie Subagenten

1025</h4>1030</h4>

1026 1031

1027Für mehrstufige Workflows bitten Sie Claude, Subagenten nacheinander zu verwenden. Jeder Subagent vervollständigt seine Aufgabe und gibt Ergebnisse an Claude zurück, das dann relevanten Kontext an den nächsten Subagenten übergibt.1032Für mehrstufige Workflows bitten Sie Claude, Subagenten nacheinander zu verwenden. Jeder Subagent schließt seine Aufgabe ab und gibt Ergebnisse an Claude zurück, der dann relevanten Kontext an den nächsten Subagenten übergibt.

1028 1033

1029```text wrap theme={null}1034```text wrap theme={null}

1030Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them1035Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

1037Verwenden Sie die **Hauptkonversation**, wenn:1042Verwenden Sie die **Hauptkonversation**, wenn:

1038 1043

1039* Die Aufgabe häufiges Hin und Her oder iterative Verfeinerung benötigt1044* Die Aufgabe häufiges Hin und Her oder iterative Verfeinerung benötigt

1040* Mehrere Phasen teilen erheblichen Kontext, z. B. Planung, Implementierung und Testen1045* Mehrere Phasen teilen erheblichen Kontext, z. B. Planung, Implementierung und Tests

1041* Sie eine schnelle, gezielte Änderung vornehmen1046* Sie eine schnelle, gezielte Änderung vornehmen

1042* Latenz ist wichtig. Ein Subagent, der kein [Fork](#fork-the-current-conversation) ist, startet von vorne und benötigt möglicherweise Zeit, um Kontext zu sammeln1047* Latenz wichtig ist. Ein Subagent, der kein [Fork](#fork-the-current-conversation) ist, startet von vorne und benötigt möglicherweise Zeit, um Kontext zu sammeln

1043 1048

1044Verwenden Sie **Subagenten**, wenn:1049Verwenden Sie **Subagenten**, wenn:

1045 1050

1046* Die Aufgabe ausführliche Ausgaben erzeugt, die Sie nicht in Ihrem Hauptkontext benötigen1051* Die Aufgabe ausführliche Ausgabe produziert, die Sie nicht in Ihrem Hauptkontext benötigen

1047* Sie spezifische Werkzeugbeschränkungen oder Berechtigungen durchsetzen möchten1052* Sie spezifische Werkzeugbeschränkungen oder Genehmigungen erzwingen möchten

1048* Die Arbeit in sich geschlossen ist und eine Zusammenfassung zurückgeben kann1053* Die Arbeit in sich geschlossen ist und eine Zusammenfassung zurückgeben kann

1049 1054

1050Erwägen Sie stattdessen [Skills](/docs/de/skills), wenn Sie wiederverwendbare Prompts oder Workflows möchten, die im Kontext der Hauptkonversation ausgeführt werden, anstatt in isoliertem Subagenten-Kontext.1055Erwägen Sie stattdessen [Skills](/docs/de/skills), wenn Sie wiederverwendbare Eingabeaufforderungen oder Workflows möchten, die im Hauptkonversationskontext ausgeführt werden, anstatt in isoliertem Subagenten-Kontext.

1051 1056

1052Für eine Frage zu etwas, das bereits in Ihrer Konversation ist, verwenden Sie stattdessen [`/btw`](/docs/de/interactive-mode#side-questions-with-%2Fbtw). Es sieht Ihren vollständigen Kontext, hat aber keinen Werkzeugzugriff, und die Antwort wird nicht zur Historie hinzugefügt.1057Für eine Frage zu etwas, das bereits in Ihrer Konversation vorhanden ist, verwenden Sie [`/btw`](/docs/de/interactive-mode#side-questions-with-%2Fbtw) anstelle eines Subagenten. Es sieht Ihren vollständigen Kontext, hat aber keinen Werkzeugzugriff, und die Antwort wird nicht zur Historie hinzugefügt.

1053 1058

1054<h3 id="let-subagents-spawn-their-own-subagents">1059<h3 id="let-subagents-spawn-their-own-subagents">

1055 Lassen Sie Subagenten ihre eigenen Subagenten spawnen1060 Lassen Sie Subagenten ihre eigenen Subagenten spawnen

1057 1062

1058Standardmäßig kann ein Subagent seine eigenen Subagenten spawnen, bis zu drei Ebenen unter der Hauptkonversation. Bei der Tiefengrenze entzieht Claude Code das `Agent`-Werkzeug jedem Subagenten außer einem [Fork](#fork-the-current-conversation), sodass ein Subagent bei der Grenze seine delegierte Arbeit selbst erledigt und eine Zusammenfassung zurückgibt. Ein Fork bei der Grenze behält `Agent` in seiner geerbten Werkzeugliste, aber das Werkzeug gibt stattdessen einen Fehler zurück.1063Standardmäßig kann ein Subagent seine eigenen Subagenten spawnen, bis zu drei Ebenen unter der Hauptkonversation. Bei der Tiefengrenze entzieht Claude Code das `Agent`-Werkzeug jedem Subagenten außer einem [Fork](#fork-the-current-conversation), sodass ein Subagent bei der Grenze seine delegierte Arbeit selbst erledigt und eine Zusammenfassung zurückgibt. Ein Fork bei der Grenze behält `Agent` in seiner geerbten Werkzeugliste, aber das Werkzeug gibt stattdessen einen Fehler zurück.

1059 1064

1060Verschachtelte Subagenten eignen sich für eine delegierte Aufgabe, die sich selbst in parallele Unteraufgaben aufteilt, z. B. ein Reviewer-Subagent, der einen Verifier pro Befund versendet, sodass die Zwischenausgabe niemals Ihre Hauptkonversation erreicht. Nur die Zusammenfassung des Top-Level-Subagenten kehrt zu Ihnen zurück.1065Verschachtelte Subagenten eignen sich für eine delegierte Aufgabe, die sich selbst in parallele Unteraufgaben aufteilt, z. B. ein Reviewer-Subagent, der einen Verifizierer pro Befund versendet. In einer interaktiven Sitzung kehrt nur die Zusammenfassung des Top-Level-Subagenten zu Ihnen zurück und die Zwischenausgabe bleibt aus Ihrer Hauptkonversation: Ein Subagent, der Hintergrund-Subagenten startet, wartet auf deren Ergebnisse, bevor er beendet wird. Im [nicht-interaktiven Modus](/docs/de/headless) und dem Agent SDK wartet der startende Subagent nicht, sodass ein verschachtelter Hintergrund-Subagent, der beendet wird, nachdem sein Starter beendet wurde, stattdessen an Ihre Hauptkonversation meldet.

1061 1066

1062Um die Grenze zu ändern, setzen Sie [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/de/env-vars) auf die Anzahl der Subagenten-Ebenen, die Sie unter Ihrer Hauptkonversation möchten. Zum Beispiel begrenzt dieser Eintrag in [`settings.json`](/docs/de/settings) die Verschachtelung auf zwei Ebenen:1067Um die Grenze zu ändern, setzen Sie [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/de/env-vars) auf die Anzahl der Subagenten-Ebenen, die Sie unter Ihrer Hauptkonversation möchten. Beispielsweise begrenzt dieser Eintrag in [`settings.json`](/docs/de/settings) die Verschachtelung auf zwei Ebenen:

1063 1068

1064```json theme={null}1069```json theme={null}

1065{1070{

1071 1076

1072Mit diesem Wert können Ihre Subagenten an eine zweite Ebene ihrer eigenen delegieren, und diese zweite Ebene kann nicht weiter delegieren. Setzen Sie `1`, um Verschachtelung auszuschalten.1077Mit diesem Wert können Ihre Subagenten an eine zweite Ebene ihrer eigenen delegieren, und diese zweite Ebene kann nicht weiter delegieren. Setzen Sie `1`, um Verschachtelung auszuschalten.

1073 1078

1074Ein verschachtelter Subagent wird genauso konfiguriert wie ein Top-Level-Subagent und wird aus denselben [Scopes](#choose-the-subagent-scope) aufgelöst. Um zu verhindern, dass ein Subagent spawnt, während Verschachtelung an ist, z. B. ein Reviewer, der schreibgeschützt bleiben sollte, lassen Sie `Agent` aus seiner [`tools`](#available-tools)-Liste weg oder fügen Sie es zu `disallowedTools` hinzu.1079Ein verschachtelter Subagent wird genauso konfiguriert wie ein Top-Level-Subagent und wird aus denselben [Bereichen](#choose-the-subagent-scope) aufgelöst. Um zu verhindern, dass ein Subagent spawnt, während Verschachtelung an ist, z. B. ein Reviewer, der schreibgeschützt bleiben sollte, lassen Sie `Agent` aus seiner [`tools`](#available-tools)-Liste weg oder fügen Sie es zu `disallowedTools` hinzu.

1075 1080

1076Claude Code zeigt verschachtelte Subagenten als Baum im Subagenten-Panel unter der Eingabeaufforderung an und markiert jede Zeile, die noch Nachkommen hat, mit einer `(+N)`-Anzahl von ihnen. Öffnen Sie eine Zeile, um die Geschwister und direkten Kinder dieses Subagenten mit einem Pfad zurück zu `main` zu sehen.1081Claude Code zeigt verschachtelte Subagenten als Baum im Subagenten-Panel unter der Eingabeaufforderungseingabe an und markiert jede Zeile, die noch Nachkommen hat, mit einer `(+N)`-Anzahl von ihnen. Öffnen Sie eine Zeile, um die Geschwister und direkten Kinder dieses Subagenten mit einem Pfad zurück zu `main` zu sehen.

1077 1082

1078<Note>1083<Note>

1079 Frühere Versionen verwendeten unterschiedliche Standardwerte:1084 Frühere Versionen verwendeten unterschiedliche Standards:

1080 1085

1081 * **v2.1.172 bis v2.1.216**: Subagenten konnten standardmäßig verschachtelt werden, bis zu fünf Ebenen tief, und die Grenze konnte nicht geändert werden.1086 * **v2.1.172 bis v2.1.216**: Subagenten konnten standardmäßig verschachtelt werden, bis zu fünf Ebenen tief, und die Grenze konnte nicht geändert werden.

1082 * **v2.1.217 bis v2.1.218**: Die Grenze betrug standardmäßig eins, sodass ein Subagent nicht seine eigenen spawnen konnte, es sei denn, Sie erhöhten sie; v2.1.219 erhöhte den Standard auf drei.1087 * **v2.1.217 bis v2.1.218**: Die Grenze betrug standardmäßig eins, sodass ein Subagent nicht seine eigenen spawnen konnte, es sei denn, Sie erhöhten sie; v2.1.219 erhöhte den Standard auf drei.

1083</Note>1088</Note>

1084 1089

1085<h3 id="concurrent-subagent-limit">1090<h3 id="concurrent-subagent-limit">

1086 Gleichzeitige Subagenten-Grenze1091 Gleichzeitiges Subagenten-Limit

1087</h3>1092</h3>

1088 1093

1089Zwei Grenzen steuern die Subagenten-Nutzung, jede mit ihrer eigenen Variablen: Diese stoppt Claude daran, mehr Subagenten zu spawnen, während zu viele laufen, und die [Tiefengrenze](#let-subagents-spawn-their-own-subagents) begrenzt, wie tief Subagenten verschachtelt sind. Es gibt keine Grenze für die Gesamtzahl der Subagenten, die Claude über eine Sitzung spawnen kann.1094Zwei Grenzen steuern die Subagenten-Nutzung, jede mit ihrer eigenen Variablen: Diese stoppt Claude daran, mehr Subagenten zu spawnen, während zu viele laufen, und die [Tiefengrenze](#let-subagents-spawn-their-own-subagents) begrenzt, wie tief Subagenten verschachtelt sind. Es gibt keine Grenze für die Gesamtzahl der Subagenten, die Claude über eine Sitzung spawnen kann.

1090 1095

1091Standardmäßig schlägt das Spawnen eines anderen mit dem Agent-Werkzeug fehl mit `Concurrent subagent limit reached`, wenn 20 Subagenten in einer Sitzung laufen, und der Fehler teilt Claude mit, nicht zu wiederholen. Das Spawnen gelingt wieder, wenn die laufende Anzahl unter die Grenze fällt. Um die Grenze zu ändern, setzen Sie [`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`](/docs/de/env-vars) auf eine beliebige positive ganze Zahl. Sitzungen mit aktiviertem [ultracode](/docs/de/model-config#adjust-effort-level) sind ausgenommen: Die Grenze wird dort nicht durchgesetzt. Erfordert Claude Code v2.1.217 oder später.1096Standardmäßig schlägt das Spawnen eines anderen mit dem Agent-Werkzeug fehl, wenn 20 Subagenten in einer Sitzung laufen, mit `Concurrent subagent limit reached`, und der Fehler teilt Claude mit, nicht zu wiederholen. Das Spawnen ist erfolgreich, wenn die laufende Anzahl unter die Grenze fällt. Um die Grenze zu ändern, setzen Sie [`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`](/docs/de/env-vars) auf eine beliebige positive ganze Zahl. Sitzungen mit aktivem [ultracode](/docs/de/model-config#adjust-effort-level) sind ausgenommen: Die Grenze wird dort nicht erzwungen. Erfordert Claude Code v2.1.217 oder später.

1092 1097

1093Die Grenze blockiert nur Subagenten, die Claude mit dem Agent-Werkzeug spawnt, aber andere Ausführungen belegen dieselben Slots:1098Die Grenze blockiert nur Subagenten, die Claude mit dem Agent-Werkzeug spawnt, aber andere Läufe belegen die gleichen Slots:

1094 1099

1095* Ein In-Session-Fork, den Sie mit [`/subtask`](#fork-the-current-conversation) starten, belegt einen Slot, während er läuft, und wird niemals durch die Grenze blockiert.1100* Ein In-Session-Fork, den Sie mit [`/subtask`](#fork-the-current-conversation) starten, belegt einen Slot während der Ausführung und wird niemals durch die Grenze blockiert.

1096* [Fortsetzen eines Subagenten](#resume-subagents), der bereits fertig ist, belegt einen frischen Slot, ohne die Grenze zu prüfen, sodass Fortsetzungen die laufende Anzahl über die Grenze hinaus drücken können.1101* [Fortsetzen eines Subagenten](#resume-subagents), der bereits beendet ist, belegt einen neuen Slot, ohne die Grenze zu überprüfen, sodass Fortsetzungen die laufende Anzahl über die Grenze hinaus drücken können.

1097 1102

1098Agenten, die andere Funktionen ausführen, z. B. [Workflow](/docs/de/workflows)-Agenten und [Agent-Team](/docs/de/agent-teams)-Teamkollegen, folgen stattdessen ihren eigenen Grenzen.1103Agenten, die andere Funktionen ausführen, z. B. [Workflow](/docs/de/workflows)-Agenten und [Agent-Team](/docs/de/agent-teams)-Teamkollegen, folgen stattdessen ihren eigenen Grenzen.

1099 1104

1102</h3>1107</h3>

1103 1108

1104<h4 id="what-loads-at-startup">1109<h4 id="what-loads-at-startup">

1105 Was wird beim Start geladen1110 Was beim Start geladen wird

1106</h4>1111</h4>

1107 1112

1108Jeder Subagent startet mit einem frischen, isolierten Kontextfenster. Er sieht nicht Ihre Konversationshistorie, die Skills, die Sie bereits aufgerufen haben, oder die Dateien, die Claude bereits gelesen hat. Claude verfasst eine Delegierungsnachricht, die die Aufgabe zusammenfasst, und der Subagent arbeitet von dort aus. Die Ausnahme ist ein [Fork](#fork-the-current-conversation), der die übergeordnete Konversation erbt, anstatt von vorne zu beginnen.1113Jeder Subagent startet mit einem frischen, isolierten Kontextfenster. Er sieht Ihre Konversationshistorie nicht, die Skills, die Sie bereits aufgerufen haben, oder die Dateien, die Claude bereits gelesen hat. Claude verfasst eine Delegierungsnachricht, die die Aufgabe zusammenfasst, und der Subagent arbeitet von dort aus. Die Ausnahme ist ein [Fork](#fork-the-current-conversation), der die übergeordnete Konversation erbt, anstatt von vorne zu beginnen.

1114

1115Der anfängliche Kontext eines Non-Fork-Subagenten enthält:

1109 1116

1110Der anfängliche Kontext eines Nicht-Fork-Subagenten enthält:1117* **Systemeingabeaufforderung**: die eigene Eingabeaufforderung des Agenten plus Umgebungsdetails, die Claude Code anfügt, nicht die Claude-Code-Systemeingabeaufforderung. Benutzerdefinierte Subagenten definieren ihre im [Markdown-Body](#write-subagent-files) oder im Feld `prompt`. Integrierte Agenten haben vordefinierte Eingabeaufforderungen.

1118* **Aufgabennachricht**: die Delegierungseingabeaufforderung, die Claude schreibt, wenn es die Arbeit übergibt.

1119* **CLAUDE.md-Dateien**: jede Ebene der [CLAUDE.md-Hierarchie](/docs/de/memory#how-claude-md-files-load), die die Hauptkonversation lädt, einschließlich `~/.claude/CLAUDE.md`, Projektregeln, `CLAUDE.local.md`, verwaltete Richtliniendateien und alle [`AGENTS.md`-Dateien](/docs/de/memory#agents-md), die als Projektanweisungen geladen werden. Die integrierten Explore- und Plan-Agenten überspringen dies. Ein Subagent, dessen Definition [`omitClaudeMd`](#supported-frontmatter-fields) setzt, lädt nur die verwalteten Richtliniendateien oder gar keine, wenn die Definition aus [verwalteten Einstellungen](#choose-the-subagent-scope) stammt.

1120* **Git-Status**: Ein Snapshot, der zu Beginn der übergeordneten Sitzung aufgenommen wurde. Fehlt, wenn das Arbeitsverzeichnis kein Git-Repository ist oder wenn [`includeGitInstructions`](/docs/de/settings-reference#includegitinstructions) `false` ist. Explore und Plan überspringen es unabhängig davon.

1121* **Vorgeladene Skills**: Vollständiger Inhalt jeder Skill, die im Feld [`skills`](#preload-skills-into-subagents) des Agenten benannt ist. Integrierte Agenten laden Skills nicht vor.

1122* **Geschwister-Roster**: Eine Systemerinnerung, die `main` und jeden anderen benannten Agenten in der Sitzung auflistet, jeweils ein gültiger `to`-Wert für [`SendMessage`](#resume-subagents). Erfordert Claude Code v2.1.206 oder später. Das Roster erscheint nur, wenn die Tools des Subagenten `SendMessage` enthalten und mindestens ein anderer Agent einen Namen hat, ob Claude ihn beim Spawnen benannt hat oder er als [Agent-Team](/docs/de/agent-teams)-Teamkollege läuft. Es ist ein Snapshot, der aufgenommen wird, wenn der Subagent startet, sodass später benannte Agenten nicht erscheinen.

1111 1123

1112* **Systemprompt**: Der eigene Prompt des Agenten plus Umgebungsdetails, die Claude Code anhängt, nicht der Claude Code-Systemprompt. Benutzerdefinierte Subagenten definieren ihren in der [Markdown-Datei](#write-subagent-files) oder im `prompt`-Feld. Integrierte Agenten haben vordefinierte Prompts.1124Um einen Ihrer eigenen Subagenten ohne die Benutzer-, Projekt- und lokalen CLAUDE.md-Dateien zu starten, setzen Sie [`omitClaudeMd: true`](#supported-frontmatter-fields) in seiner Frontmatter oder `--agents` JSON.

1113* **Task-Nachricht**: Der Delegierungsprompt, den Claude schreibt, wenn er die Arbeit übergibt.

1114* **CLAUDE.md-Dateien**: Jede Ebene der [CLAUDE.md-Hierarchie](/docs/de/memory#how-claude-md-files-load), die die Hauptkonversation lädt, einschließlich `~/.claude/CLAUDE.md`, Projektregeln, `CLAUDE.local.md` und verwaltete Richtliniendateien. Die integrierten Explore- und Plan-Agenten überspringen dies.

1115* **Git-Status**: Ein Snapshot, der zu Beginn der übergeordneten Sitzung erstellt wurde. Fehlt, wenn das Arbeitsverzeichnis kein Git-Repository ist oder wenn [`includeGitInstructions`](/docs/de/settings-reference#includegitinstructions) `false` ist. Explore und Plan überspringen es unabhängig davon.

1116* **Vorgeladene Skills**: Vollständiger Inhalt aller Skills, die im [`skills`-Feld](#preload-skills-into-subagents) des Agenten benannt sind. Integrierte Agenten laden Skills nicht vor.

1117* **Geschwister-Verzeichnis**: Eine Systemerinnerung, die `main` und jeden anderen benannten Agenten in der Sitzung auflistet, jeweils ein gültiger `to`-Wert für [`SendMessage`](#resume-subagents). Erfordert Claude Code v2.1.206 oder später. Das Verzeichnis erscheint nur, wenn die Tools des Subagenten `SendMessage` enthalten und mindestens ein anderer Agent einen Namen hat, ob Claude ihn beim Spawnen benannt hat oder er als [Agent-Team](/docs/de/agent-teams)-Teamkollege läuft. Es ist ein Snapshot, der erstellt wird, wenn der Subagent startet, daher erscheinen später benannte Agenten nicht.

1118 1125

1119Explore und Plan sind die einzigen Subagenten, die CLAUDE.md und Git-Status auslassen. Es gibt kein Frontmatter-Feld oder eine Pro-Agent-Einstellung, um zu ändern, welche Agenten sie überspringen.1126Die Hauptkonversation hat immer noch Ihre vollständige CLAUDE.md, wenn sie die Ergebnisse dieser Subagenten liest, sodass die meisten Regeln den Subagenten selbst nicht erreichen müssen. Wenn eine Regel dies muss, z. B. „ignorieren Sie das `vendor/`-Verzeichnis", wiederholen Sie sie in der Eingabeaufforderung, die Sie Claude geben, wenn Sie delegieren.

1120 1127

1121Die Hauptkonversation liest Explore- und Plan-Ergebnisse mit vollständigem CLAUDE.md-Kontext, daher müssen die meisten Regeln den Subagenten selbst nicht erreichen. Wenn eine Regel dies muss, z. B. "ignore the `vendor/` directory", wiederholen Sie sie in dem Prompt, den Sie Claude geben, wenn Sie delegieren.1128Sie können nicht ändern, welche Subagenten Git-Status erhalten. Nur Explore und Plan überspringen es.

1122 1129

1123Einige Hauptkonversations-Status erreichen niemals einen Nicht-Fork-Subagenten:1130Einige Hauptkonversationszustände erreichen niemals einen Non-Fork-Subagenten:

1124 1131

1125* **Ausgabestil**: Ein Subagent führt seinen eigenen Systemprompt aus, daher formt Ihr [Ausgabestil](/docs/de/output-styles) seine Antworten nicht, außer in einem [Fork](#fork-the-current-conversation).1132* **Ausgabestil**: Ein Subagent führt seine eigene Systemeingabeaufforderung aus, sodass Ihr [Ausgabestil](/docs/de/output-styles) seine Antworten nicht formt, außer in einem [Fork](#fork-the-current-conversation).

1126* **Auto-Memory**: Das [Auto-Memory](/docs/de/memory#auto-memory) der Hauptkonversation wird nicht geladen. Um einem Subagenten sein eigenes persistentes Memory zu geben, verwenden Sie das [`memory`-Feld](#enable-persistent-memory).1133* **Auto-Gedächtnis**: Das [Auto-Gedächtnis](/docs/de/memory#auto-memory) der Hauptkonversation wird nicht geladen. Um einem Subagenten persistentes Gedächtnis seiner eigenen zu geben, verwenden Sie das Feld [`memory`](#enable-persistent-memory).

1127* **Kontextfenstergröße**: Das Kontextfenster eines Subagenten wird durch sein eigenes Modell dimensioniert, nicht das des übergeordneten. Die Delegierung an ein Modell mit einem kleineren Fenster gibt diesem Subagenten das kleinere Fenster.1134* **Kontextfenstergröße**: Das Kontextfenster eines Subagenten wird durch sein eigenes Modell dimensioniert, nicht das des übergeordneten. Die Delegierung an ein Modell mit einem kleineren Fenster gibt diesem Subagenten das kleinere Fenster.

1128 1135

1129<h4 id="resume-subagents">1136<h4 id="resume-subagents">

1130 Setzen Sie Subagenten fort1137 Fortsetzen Sie Subagenten

1131</h4>1138</h4>

1132 1139

1133Jede Subagenten-Invokation erstellt eine neue Instanz, anstatt eine frühere fortzusetzen. Um die Arbeit eines vorhandenen Subagenten fortzusetzen, anstatt von vorne zu beginnen, bitten Sie Claude, ihn fortzusetzen.1140Jeder Subagenten-Aufruf erstellt eine neue Instanz, anstatt eine frühere fortzusetzen. Um die Arbeit eines bestehenden Subagenten fortzusetzen, anstatt von vorne zu beginnen, bitten Sie Claude, ihn fortzusetzen.

1134 1141

1135Fortgesetzte Subagenten behalten ihre vollständige Konversationshistorie, einschließlich aller vorherigen Werkzeugaufrufe, Ergebnisse und Überlegungen. Wenn der Subagent [Hintergrund-Subagenten seiner eigenen](#let-subagents-spawn-their-own-subagents) spawnt, enthält diese Historie die Ergebnisse, die sie während seiner Ausführung lieferten. Der Subagent setzt genau dort an, wo er gestoppt hat, anstatt von vorne zu beginnen.1142Fortgesetzte Subagenten behalten ihre vollständige Konversationshistorie, einschließlich aller vorherigen Werkzeugaufrufe, Ergebnisse und Überlegungen. Wenn der Subagent [Hintergrund-Subagenten seiner eigenen](#let-subagents-spawn-their-own-subagents) spawnte, enthält diese Historie die Ergebnisse, die sie während der Ausführung lieferten. Der Subagent setzt genau dort an, wo er stoppte, anstatt von vorne zu beginnen.

1136 1143

1137* Wenn ein Subagent abgeschlossen ist, erhält Claude seine Agent-ID.1144* Wenn ein Subagent abgeschlossen ist, erhält Claude seine Agent-ID.

1138* Die integrierten Explore- und Plan-Agenten sind einmalig und geben keine Agent-ID zurück, sodass Claude sie nicht fortsetzen kann. Verwenden Sie `general-purpose` oder einen benutzerdefinierten Subagenten, wenn Sie die Arbeit fortsetzen müssen.1145* Die integrierten Explore- und Plan-Agenten sind einmalig und geben keine Agent-ID zurück, sodass Claude sie nicht fortsetzen kann. Verwenden Sie `general-purpose` oder einen benutzerdefinierten Subagenten, wenn Sie die Arbeit fortsetzen müssen.

1139* Wenn ein Subagent bei seiner [`maxTurns`](#supported-frontmatter-fields)-Grenze stoppt, markiert Claude Code die zurückgegebene Ausgabe als Teilausgabe. Für Subagenten, die eine Agent-ID zurückgeben, vermerkt Claude Code auch im Ergebnis, dass Claude den Subagenten ansprechen kann, um von dort weiterzumachen, wo er gestoppt hat.1146* Wenn ein Subagent bei seinem [`maxTurns`](#supported-frontmatter-fields)-Limit stoppt, markiert Claude Code die zurückgegebene Ausgabe als teilweise. Für Subagenten, die eine Agent-ID zurückgeben, vermerkt Claude Code auch im Ergebnis, dass Claude den Subagenten ansprechen kann, um von dort fortzufahren, wo er stoppte.

1140 1147

1141Claude verwendet das `SendMessage`-Werkzeug mit der Agent-ID oder dem Namen des Agenten als `to`-Feld, um ihn fortzusetzen. `SendMessage` erfordert nicht, dass [Agent-Teams](/docs/de/agent-teams) aktiviert sind; nur strukturierte Team-Protokoll-Nachrichten wie `shutdown_request` und `plan_approval_response` erfordern dies. Über Subagenten und Teamkollegen hinaus können Claude in Sitzungen, in denen Cross-Session-Messaging aktiviert ist, mit demselben Werkzeug [Ihre anderen Claude Code-Sitzungen](/docs/de/cross-session-messaging) auf dieser Maschine oder [darüber hinaus](/docs/de/cross-session-messaging#message-sessions-on-other-machines) ansprechen.1148Claude verwendet das `SendMessage`-Werkzeug mit der Agent-ID oder dem Namen des Agenten als `to`-Feld, um ihn fortzusetzen. `SendMessage` erfordert nicht, dass [Agent-Teams](/docs/de/agent-teams) aktiviert sind; nur strukturierte Team-Protokoll-Nachrichten wie `shutdown_request` und `plan_approval_response` tun dies. Über Subagenten und Teamkollegen hinaus können Claude in Sitzungen, in denen Cross-Session-Messaging aktiviert ist, mit demselben Werkzeug [Ihre anderen Claude-Code-Sitzungen](/docs/de/cross-session-messaging) ansprechen, auf dieser Maschine oder [darüber hinaus](/docs/de/cross-session-messaging#message-sessions-on-other-machines).

1142 1149

1143Um einen Subagenten fortzusetzen, bitten Sie Claude, die vorherige Arbeit fortzusetzen:1150Um einen Subagenten fortzusetzen, bitten Sie Claude, die vorherige Arbeit fortzusetzen:

1144 1151

1150[Claude resumes the subagent with full context from previous conversation]1157[Claude resumes the subagent with full context from previous conversation]

1151```1158```

1152 1159

1153Wenn Claude einen abgeschlossenen Subagenten mit dem `SendMessage`-Werkzeug eine Nachricht sendet, wird der Subagent automatisch im Hintergrund fortgesetzt, ohne dass eine neue `Agent`-Invokation erforderlich ist. Das Gleiche gilt für einen Subagenten, den Claude mit dem `TaskStop`-Werkzeug gestoppt hat, sobald sein gestoppter Lauf beendet ist. Der fortgesetzte Lauf behält den [Werkzeugsatz von dort, wo der Subagent zuerst lief](#run-subagents-in-foreground-or-background), und kann weiterhin den [Prompt-Cache lesen, den der ursprüngliche Lauf aufgewärmt hat](/docs/de/prompt-caching#subagents-and-the-cache).1160Wenn Claude einen abgeschlossenen Subagenten mit dem `SendMessage`-Werkzeug eine Nachricht sendet, wird der Subagent im Hintergrund ohne einen neuen `Agent`-Aufruf fortgesetzt. Das Gleiche gilt für einen Subagenten, den Claude mit dem `TaskStop`-Werkzeug gestoppt hat, sobald sein gestoppter Lauf beendet ist. Der fortgesetzte Lauf behält den [Werkzeugsatz von dort, wo der Subagent zuerst lief](#run-subagents-in-foreground-or-background), und kann weiterhin den [Prompt-Cache lesen, den der ursprüngliche Lauf aufgewärmt hat](/docs/de/prompt-caching#subagents-and-the-cache).

1154 1161

1155Ein Subagent, der das `SendMessage`-Werkzeug hat, kann diese Nachricht auch senden. In einer interaktiven Sitzung meldet der fortgesetzte Agent dann dem Subagenten, der ihn fortgesetzt hat, zurück, nicht zu Ihrer Hauptkonversation. Dieser Subagent wartet auf das Ergebnis, bevor er seine eigene Arbeit beendet. Wenn ein Subagent einen Agenten anspricht, dem er meldet, z. B. seinen eigenen Launcher, setzt Claude Code diesen Agenten fort, ohne seine Ergebnisse umzuleiten.1162Ein Subagent, der das `SendMessage`-Werkzeug hat, kann diese Nachricht auch senden. In einer interaktiven Sitzung meldet der fortgesetzte Agent dann dem Subagenten, der ihn fortgesetzt hat, zurück, nicht zu Ihrer Hauptkonversation. Dieser Subagent wartet auf das Ergebnis, bevor er seine eigene Arbeit beendet. Wenn ein Subagent einen Agenten anspricht, dem er meldet, z. B. seinen eigenen Launcher, setzt Claude Code diesen Agenten fort, ohne seine Ergebnisse umzuleiten.

1156 1163

1157Ein Subagent, den Sie selbst gestoppt haben, mit `x` in `/tasks` oder einer SDK-`stop_task`-Anfrage, wird nicht automatisch fortgesetzt. Wenn Claude ihm eine Nachricht sendet, wird die Nachricht abgelehnt und Claude wird mitgeteilt, dass der Agent abgebrochen wurde.1164Ein Subagent, den Sie selbst gestoppt haben, mit `x` in `/tasks` oder einer SDK-`stop_task`-Anfrage, wird nicht automatisch fortgesetzt. Wenn Claude ihm eine Nachricht sendet, wird die Nachricht verweigert und Claude wird mitgeteilt, dass der Agent abgebrochen wurde.

1158 1165

1159Während [diese Zeile des Subagenten noch im Subagenten-Panel ist](#run-subagents-in-foreground-or-background), geben Sie in sein Transkript ein, um ihn selbst fortzusetzen. Danach kann eine Nachricht von Claude ihn wieder automatisch fortsetzen. Erfordert Claude Code v2.1.191 oder später.1166Während [die Zeile dieses Subagenten immer noch im Subagenten-Panel ist](#run-subagents-in-foreground-or-background), geben Sie in sein Transkript ein, um ihn selbst fortzusetzen. Danach kann eine Nachricht von Claude ihn wieder automatisch fortsetzen. Erfordert Claude Code v2.1.191 oder später.

1160 1167

1161Das Fortsetzen startet einen neuen Lauf des Agenten unter derselben ID, sodass ein Subagent, der bereits fehlgeschlagen oder abgeschlossen war, in der Aufgabenliste und in den Task-Events des Agent SDK wieder als laufend angezeigt wird. Vor v2.1.205 zeigte er seinen früheren fehlgeschlagenen oder abgeschlossenen Status, während der fortgesetzte Lauf funktionierte.1168Das Fortsetzen startet einen neuen Lauf des Agenten unter derselben ID, sodass ein Subagent, der bereits fehlgeschlagen oder abgeschlossen war, in der Aufgabenliste und in den Task-Events des Agent SDK wieder als laufend angezeigt wird. Vor v2.1.205 zeigte er seinen früheren fehlgeschlagenen oder abgeschlossenen Status, während der fortgesetzte Lauf funktionierte.

1162 1169

1163Ab v2.1.199 überprüft `SendMessage`, dass ein Name immer noch auf denselben Agenten verweist, den er früher in der Konversation erreicht hat. Wenn ein neuerer Agent den Namen übernommen hat, z. B. ein neu gestarteter Hintergrund-Agent, der ihn wiederverwendet hat, weigert sich Claude Code, die Nachricht zu senden, anstatt sie an den falschen Agenten zu liefern, und der Fehler meldet, welchen Agenten der Name jetzt erreicht, damit Claude neu ausrichten kann. Um den früheren Agenten zu erreichen, während er noch läuft, adressiert Claude ihn nach der Agent-ID, die er beim Spawnen dieses Agenten erhalten hat. Die Überprüfung ist auf die aktuelle Konversation beschränkt und wird bei `/clear` zurückgesetzt.1170Ab v2.1.199 überprüft `SendMessage`, dass ein Name immer noch auf denselben Agenten verweist, den er früher in der Konversation erreicht hat. Wenn ein neuerer Agent den Namen übernommen hat, z. B. ein neu gespawnter Hintergrund-Agent, der ihn wiederverwendet hat, weigert sich Claude Code, die Nachricht zu senden, anstatt sie an den falschen Agenten zu liefern, und der Fehler meldet, welcher Agent der Name jetzt erreicht, damit Claude neu ausrichten kann. Um den früheren Agenten zu erreichen, während er noch läuft, spricht Claude ihn nach der Agent-ID an, die er erhielt, als er diesen Agenten spawnte. Die Überprüfung ist auf die aktuelle Konversation beschränkt und wird bei `/clear` zurückgesetzt.

1164 1171

1165Ab v2.1.198 behandelt ein Subagent Nachrichten vom Agenten, der ihn gestartet hat, als normale Aufgabenrichtung, einschließlich Kurskorrektionen während der Aufgabe, und handelt danach innerhalb seiner eigenen Berechtigungseinstellungen. Zwei Limits gelten immer noch unabhängig davon, wer die Nachricht gesendet hat: Keine Nachricht von einem Agenten zählt als Ihre Genehmigung für eine ausstehende Berechtigungsaufforderung, und keine Agent-Nachricht kann die Berechtigungseinstellungen, `CLAUDE.md` oder Konfiguration eines Subagenten ändern. Nur das Berechtigungssystem oder Ihre eigenen Nachrichten können Genehmigung gewähren.1172Ab v2.1.198 behandelt ein Subagent Nachrichten vom Agenten, der ihn gestartet hat, als normale Aufgabenrichtung, einschließlich Kurskorrektionen während der Aufgabe, und handelt nach ihnen innerhalb seiner eigenen Genehmigungseinstellungen. Zwei Grenzen gelten trotzdem unabhängig davon, wer die Nachricht gesendet hat: Keine Nachricht von einem Agenten zählt als Ihre Genehmigung für eine ausstehende Genehmigungseingabeaufforderung, und keine Agent-Nachricht kann die Genehmigungseinstellungen, `CLAUDE.md` oder Konfiguration eines Subagenten ändern. Nur das Genehmigungssystem oder Ihre eigenen Nachrichten können Genehmigung gewähren.

1166 1173

1167Sie können auch Claude nach der Agent-ID fragen, wenn Sie sie explizit referenzieren möchten, oder IDs in den Transkriptdateien unter `~/.claude/projects/{project}/{sessionId}/subagents/` finden. Jedes Transkript wird als `agent-{agentId}.jsonl` gespeichert.1174Sie können Claude auch nach der Agent-ID fragen, wenn Sie sie explizit referenzieren möchten, oder IDs in den Transkriptdateien unter `~/.claude/projects/{project}/{sessionId}/subagents/` finden. Jedes Transkript wird als `agent-{agentId}.jsonl` gespeichert.

1168 1175

1169Subagenten-Transkripte bleiben unabhängig von der Hauptkonversation bestehen:1176Subagenten-Transkripte bleiben unabhängig von der Hauptkonversation bestehen:

1170 1177

1171* **Hauptkonversations-Komprimierung**: Wenn die Hauptkonversation komprimiert wird, sind Subagenten-Transkripte nicht betroffen. Sie werden in separaten Dateien gespeichert.1178* **Hauptkonversations-Komprimierung**: Wenn die Hauptkonversation komprimiert wird, sind Subagenten-Transkripte nicht betroffen. Sie werden in separaten Dateien gespeichert.

1172* **Sitzungs-Persistenz**: Subagenten-Transkripte bleiben innerhalb ihrer Sitzung bestehen. Sie können [einen Subagenten fortsetzen](#resume-subagents), nachdem Sie Claude Code neu gestartet haben, indem Sie dieselbe Sitzung fortsetzen.1179* **Sitzungspersistenz**: Subagenten-Transkripte bleiben innerhalb ihrer Sitzung bestehen. Sie können [einen Subagenten fortsetzen](#resume-subagents), nachdem Sie Claude Code neu gestartet haben, indem Sie dieselbe Sitzung fortsetzen.

1173* **Automatische Bereinigung**: Claude Code löscht Subagenten-Transkripte nach der `cleanupPeriodDays`-Aufbewahrungsfrist, standardmäßig 30 Tage, nach den [Aufbewahrungssweep-Regeln](/docs/de/claude-directory#cleaned-up-automatically).1180* **Automatische Bereinigung**: Claude Code löscht Subagenten-Transkripte nach der Aufbewahrungsfrist `cleanupPeriodDays`, standardmäßig 30 Tage, nach den [Aufbewahrungsfeger-Regeln](/docs/de/claude-directory#cleaned-up-automatically).

1174 1181

1175<h4 id="auto-compaction">1182<h4 id="auto-compaction">

1176 Auto-Komprimierung1183 Auto-Komprimierung

1177</h4>1184</h4>

1178 1185

1179Subagenten unterstützen automatische Komprimierung mit derselben Logik wie die Hauptkonversation. Die Komprimierung wird unter denselben Bedingungen ausgelöst, und `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` gilt auch für Subagenten. Siehe [Umgebungsvariablen](/docs/de/env-vars) für den Zeitpunkt, zu dem die Überschreibung wirksam wird.1186Subagenten unterstützen automatische Komprimierung mit der gleichen Logik wie die Hauptkonversation. Die Komprimierung wird unter den gleichen Bedingungen ausgelöst, und `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` gilt auch für Subagenten. Siehe [Umgebungsvariablen](/docs/de/env-vars) für den Zeitpunkt, an dem die Überschreibung wirksam wird.

1180 1187

1181Komprimierungsereignisse werden in Subagenten-Transkriptdateien protokolliert:1188Komprimierungsereignisse werden in Subagenten-Transkriptdateien protokolliert:

1182 1189

1191}1198}

1192```1199```

1193 1200

1194Der `preTokens`-Wert zeigt, wie viele Token vor der Komprimierung verwendet wurden.1201Der Wert `preTokens` zeigt, wie viele Token vor der Komprimierung verwendet wurden.

1195 1202

1196<h2 id="fork-the-current-conversation">1203<h2 id="fork-the-current-conversation">

1197 Gegabelte Konversation1204 Gegabelte Konversation

sub-agents.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

Benutzerdefinierte Subagenten erstellen

Integrierte Subagenten

Schnellstart: Erstellen Sie Ihren ersten Subagenten

Bitten Sie Claude, den Subagenten zu erstellen

Überprüfen Sie die Datei

Probieren Sie es aus

Konfigurieren Sie Subagenten

Wählen Sie den Subagenten-Umfang

Schreiben Sie Subagenten-Dateien

Unterstützte Frontmatter-Felder

Subagenten-Dateien, die Claude Code überspringt

Überprüfen Sie ein `agents`-Verzeichnis vor einer Sitzung

Wählen Sie ein Modell

Führen Sie jeden Subagenten auf einem Modell aus

Kontrollieren Sie Subagenten-Fähigkeiten

Verfügbare Werkzeuge

Beschränken Sie, welche Subagenten gespawnt werden können

Umfang von MCP-Servern auf einen Subagenten

Berechtigungsmodi

Laden Sie Skills in Subagenten vor

Aktivieren Sie persistenten Speicher

Tipps zum persistenten Speicher

Bedingte Regeln mit Hooks

Deaktivieren Sie spezifische Subagenten

Definieren Sie Hooks für Subagenten

Hooks im Subagenten-Frontmatter

Hooks auf Projektebene für Subagenten-Ereignisse

Mit Subagenten arbeiten

Automatische Delegierung verstehen

Subagenten explizit aufrufen

Subagenten im Vordergrund oder Hintergrund ausführen

Subagenten-Namen

API-Fehler in Subagenten

Subagenten-Ausgabe-Scanning

Häufige Muster

Isolieren Sie hochvolumige Operationen

Führen Sie parallele Recherchen durch

Verketten Sie Subagenten

Wählen Sie zwischen Subagenten und Hauptkonversation

Lassen Sie Subagenten ihre eigenen Subagenten spawnen

Gleichzeitiges Subagenten-Limit

Verwalten Sie den Subagenten-Kontext

Was beim Start geladen wird

Fortsetzen Sie Subagenten

Auto-Komprimierung

Gegabelte Konversation

Beobachten und lenken Sie laufende Forks

Wie sich Forks von anderen Subagenten unterscheiden

Fork-Modus aktivieren oder deaktivieren

Beispiel-Subagenten

Code-Reviewer

Debugger

Data Scientist

Datenbankabfrage-Validator

Nächste Schritte