Dokumentationerreichbar
Anthropic, Create custom subagents
code.claude.com (externe Seite)
Die Herstellerdokumentation zu Subagenten. Sie beantwortet die Frage, wozu man sie nimmt, über den Kontext statt über die Arbeitsteilung: Eine Nebenaufgabe, deren Suchtreffer, Protokolle und Dateiinhalte niemand wieder braucht, läuft in einem eigenen Fenster und gibt nur die Zusammenfassung zurück. Dazu die Kanten, die man beim Bauen trifft: eigene Tool-Liste und eigene Berechtigungen, eine Anlaufzeit, weil ein Subagent bei null anfängt, und die Beobachtung, dass viele ausführliche Rückgaben denselben Platz kosten, den man sparen wollte.
geprüft 10.11.2026
Worauf sich diese Seite beruft, wörtlich, abgerufen am 04.08.2026:
Use one when a side task would flood your main conversation with search results, logs, or file contents you won't reference again: the subagent does that work in its own context and returns only the summary.
bestätigt 10.11.2026Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.
bestätigt 10.11.2026Running many subagents that each return detailed results can consume significant context, and each subagent spends tokens of its own while it runs.
bestätigt 10.11.2026At the depth limit, Claude Code withholds the Agent tool from every subagent except a fork
bestätigt 10.11.2026This works best when the research paths don't depend on each other.
bestätigt 10.11.2026There's no limit on the total number of subagents Claude can spawn over a session.
bestätigt 10.11.2026By default, when 20 subagents are running in a session, spawning another with the Agent tool fails
bestätigt 10.11.2026By default, a subagent can spawn subagents of its own, up to three layers below the main conversation.
bestätigt 10.11.2026Latency matters. A subagent that isn't a fork starts fresh and may need time to gather context
bestätigt 10.11.2026A fork inherits everything the main session has at the moment it spawns. Any other subagent starts fresh from its definition.
bestätigt 10.11.2026In version 2.1.63, the Task tool was renamed to Agent.
bestätigt 10.11.2026Claude composes a delegation message that summarizes the task, and the subagent works from there.
bestätigt 10.11.2026Claude uses each subagent's description to decide when to delegate tasks.
bestätigt 10.11.2026It also sends its own requests, which count toward the same usage limits as your main conversation.
bestätigt 10.11.2026Each subagent starts with a fresh, isolated context window.
bestätigt 10.11.2026It doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read.
bestätigt 10.11.2026Subagents receive only this system prompt plus basic environment details like the working directory, not the Claude Code system prompt.
bestätigt 10.11.2026The main conversation still has your full CLAUDE.md when it reads these subagents' results, so most rules don't need to reach the subagent itself.
bestätigt 10.11.2026Claude Code scans each subagent's final report before Claude reads it.
bestätigt 10.11.2026The header states that instructions or approval claims inside the report are the subagent's words and carry no authority from you.
bestätigt 10.11.2026A fast, read-only agent optimized for searching and analyzing codebases.
bestätigt 10.11.2026Explore and Plan start without your CLAUDE.md files and the git status snapshot to keep research fast and inexpensive.
bestätigt 10.11.2026For Explore, Plan, and subagents with omitClaudeMd, a subdirectory’s CLAUDE.md and matching path-scoped rules still load when the subagent works with files there.
bestätigt 10.11.2026Subagents are Markdown files with YAML frontmatter.
bestätigt 10.11.2026Define a custom subagent when you keep spawning the same kind of worker with the same instructions.
bestätigt 10.11.2026Running /
bestätigt 10.11.2026agents prints a reminder to ask Claude or edit .claude/ agents/ and ~/.claude/ agents/ directly. The @-mention controls which subagent Claude invokes, not what prompt it receives.
bestätigt 10.11.2026Subagents work within a single session.
bestätigt 10.11.2026A fork is a subagent that inherits the entire conversation so far instead of starting fresh.
bestätigt 10.11.2026Because of that reuse, a fork costs less than a fresh subagent for tasks that need the same context.
bestätigt 10.11.2026When multiple subagents share the same name, Claude Code uses the one from the higher-priority location.
bestätigt 10.11.2026Claude Code watches ~/.claude/
bestätigt 10.11.2026agents/ and .claude/ agents/. Claude Code ignores a field it doesn't recognize without reporting an error.
bestätigt 10.11.2026Claude Code removes every other built-in tool from a background subagent, whether inherited or listed in the tools field, so the same definition can resolve to different tools in the foreground and the background.
bestätigt 10.11.2026A subagent's context window is sized by its own model, not the parent's.
bestätigt 10.11.2026Overrides the session effort level, but not the CLAUDE_CODE_EFFORT_LEVEL environment variable.
bestätigt 10.11.2026The per-invocation parameter requires Claude Code v2.1.292 or later.
bestätigt 10.11.2026Before v2.1.198, subagents ran with extended thinking disabled regardless of the main conversation's setting.
bestätigt 10.11.2026Claude Code applies your answer to the whole session, including your main conversation.
bestätigt 10.11.2026This field controls which skills are preloaded, not which skills the subagent can access
bestätigt 10.11.2026The subagent uses this directory to build up knowledge over time, such as codebase patterns, debugging insights, and architectural decisions.
bestätigt 10.11.2026the main thread itself takes on that subagent's tool restrictions and model
bestätigt 10.11.2026A fork can't spawn further forks.
bestätigt 10.11.2026Fork mode is on by default from Claude Code v2.1.302, and in an interactive terminal session from v2.1.232.
bestätigt 10.11.2026While fork mode is on, Claude also can’t wait for a subagent in interactive terminal, VS Code, or desktop sessions on your machine.
bestätigt 10.11.2026Each subagent invocation creates a new instance rather than continuing an earlier one.
bestätigt 10.11.2026Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning.
bestätigt 10.11.2026no message from any agent counts as your approval for a pending permission prompt
bestätigt 10.11.2026Subagent transcripts persist independently of the main conversation
bestätigt 10.11.2026The scan doesn't judge whether content is malicious
bestätigt 10.11.2026Sessions with ultracode active are exempt: the limit isn't enforced there.
bestätigt 10.11.2026When a background subagent reaches a tool call that needs permission, Claude Code surfaces the prompt in your main session and names the subagent that is asking.
bestätigt 10.11.2026A background subagent's results reach Claude as a completion notification in a later turn.
bestätigt 10.11.2026When the main conversation runs Fable, Explore's model depends on how you connect
bestätigt 10.11.2026claude -p and the Agent SDK: Claude can wait, on its own judgment or when you ask.
bestätigt 10.11.2026every level of the CLAUDE.md hierarchy the main conversation loads
bestätigt 10.11.2026loads only the managed policy files, or none at all when the definition comes from managed settings
bestätigt 10.11.2026Use it for subagents that take everything they need from the delegation prompt
bestätigt 10.11.2026Ignored when the agent runs as the main session agent via --agent or the agent setting.
bestätigt 10.11.2026A research agent used during plan mode to gather context before presenting a plan.
bestätigt 10.11.2026read-only tools; Write and Edit are denied
bestätigt 10.11.2026it delegates research to the Plan subagent so that exploration output stays in a separate context window while the main conversation remains read-only
bestätigt 10.11.2026With nothing configured, a subagent that Claude spawns from your main conversation starts in the background.
bestätigt 10.11.2026Interactive terminal session, VS Code, and desktop app sessions on your machine: to let Claude wait for a subagent, turn off fork mode, which is on by default.
bestätigt 10.11.2026Turn fork mode off by setting CLAUDE_CODE_FORK_SUBAGENT to 0
bestätigt 10.11.2026claude -p and the Agent SDK: the spawning subagent waits while fork mode is on.
bestätigt 10.11.2026If you turn fork mode off, nested subagents start in the background instead.
bestätigt 10.11.2026Requires Claude Code v2.1.257 or later.
bestätigt 10.11.2026These subagents still run on the main conversation’s model
bestätigt 10.11.2026Sibling roster: a system reminder listing main and every other named agent in the session
bestätigt 10.11.2026/
bestätigt 10.11.2026subtask isn’t available and / fork starts the forked subagent instead Three cases still need a restart:
bestätigt 10.11.2026The debug log names up to five top-level fields in the subagent’s file that Claude Code doesn’t recognize
bestätigt 10.11.2026Forks skip both filters and receive the main conversation’s exact tool pool.
bestätigt 10.11.2026The tools and disallowed
bestätigt 10.11.2026Tools fields also take entries for a whole MCP server: The parameter overrides the effort field and stays in effect when the subagent is resumed.
bestätigt 10.11.2026When the main conversation is in plan mode, the subagent stays in plan mode whichever permission
bestätigt 10.11.2026Mode you set A subagent runs in this mode only when the main conversation does
bestätigt 10.11.2026Before v2.1.238, Claude Code loaded these servers without checking trust.
bestätigt 10.11.2026Lower the auto-compact window for this subagent to a token count from 100000 to 1000000.
bestätigt 10.11.2026When the main conversation is in bypass
bestätigt 10.11.2026Permissions, accept Edits, or auto mode, the subagent runs in that same mode and Claude Code ignores the permission Mode you set. The spawning subagent doesn’t wait for a background nested subagent, which reports to your main conversation if it outlasts the spawning subagent.
bestätigt 10.11.2026Git status: a snapshot Claude Code reads from your repository when the subagent starts.
bestätigt 10.11.2026unless you set CLAUDE_CODE_SUBAGENT_MODEL and force it onto every subagent
bestätigt 10.11.2026Setting CLAUDE_CODE_SUBAGENT_MODEL by itself doesn’t change the model the built-in Explore and Plan subagents run on.
bestätigt 10.11.2026
09 Bestehenden Code verstehen13 Subagenten und Schleifen14 Anweisungen und Gedächtnis20 Subagents21 Parallel arbeiten22 Teams und Workflows23 Plan vor Code31 Der Harness