NachschlagenQuellenregister

Dokumentationerreichbar

Anthropic, Create custom subagents

code.claude.com (externe Seite)

Die Her­stel­ler­do­ku­men­ta­tion 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 17.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 17.11.2026
  • Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.bestätigt 17.11.2026
  • Running many subagents that each return detailed results can consume significant context, and each subagent spends tokens of its own while it runs.bestätigt 17.11.2026
  • At the depth limit, Claude Code withholds the Agent tool from every subagent except a forkbestätigt 17.11.2026
  • This works best when the research paths don't depend on each other.bestätigt 17.11.2026
  • There's no limit on the total number of subagents Claude can spawn over a session.bestätigt 17.11.2026
  • By default, when 20 subagents are running in a session, spawning another with the Agent tool failsbestätigt 17.11.2026
  • By default, a subagent can spawn subagents of its own, up to three layers below the main conversation.bestätigt 17.11.2026
  • Latency matters. A subagent that isn't a fork starts fresh and may need time to gather contextbestätigt 17.11.2026
  • A fork inherits everything the main session has at the moment it spawns. Any other subagent starts fresh from its definition.steht dort nicht mehr
  • In version 2.1.63, the Task tool was renamed to Agent.bestätigt 17.11.2026
  • Claude composes a delegation message that summarizes the task, and the subagent works from there.bestätigt 17.11.2026
  • Claude uses each subagent's description to decide when to delegate tasks.bestätigt 17.11.2026
  • It also sends its own requests, which count toward the same usage limits as your main conversation.bestätigt 17.11.2026
  • Each subagent starts with a fresh, isolated context window.bestätigt 17.11.2026
  • It doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read.bestätigt 17.11.2026
  • Subagents receive only this system prompt plus basic environment details like the working directory, not the Claude Code system prompt.bestätigt 17.11.2026
  • The 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 17.11.2026
  • Claude Code scans each subagent's final report before Claude reads it.bestätigt 17.11.2026
  • The header states that instructions or approval claims inside the report are the subagent's words and carry no authority from you.bestätigt 17.11.2026
  • A fast, read-only agent optimized for searching and analyzing codebases.bestätigt 17.11.2026
  • Explore and Plan start without your CLAUDE.md files and the git status snapshot to keep research fast and inexpensive.bestätigt 17.11.2026
  • For 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 17.11.2026
  • Subagents are Markdown files with YAML frontmatter.bestätigt 17.11.2026
  • Define a custom subagent when you keep spawning the same kind of worker with the same instructions.bestätigt 17.11.2026
  • Running /agents prints a reminder to ask Claude or edit .claude/agents/ and ~/.claude/agents/ directly.bestätigt 17.11.2026
  • The @-mention controls which subagent Claude invokes, not what prompt it receives.steht dort nicht mehr
  • Subagents work within a single session.bestätigt 17.11.2026
  • A fork is a subagent that inherits the entire conversation so far instead of starting fresh.bestätigt 17.11.2026
  • Because of that reuse, a fork costs less than a fresh subagent for tasks that need the same context.bestätigt 17.11.2026
  • When multiple subagents share the same name, Claude Code uses the one from the higher-priority location.bestätigt 17.11.2026
  • Claude Code watches ~/.claude/agents/ and .claude/agents/.bestätigt 17.11.2026
  • Claude Code ignores a field it doesn't recognize without reporting an error.bestätigt 17.11.2026
  • Claude 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 17.11.2026
  • A subagent's context window is sized by its own model, not the parent's.bestätigt 17.11.2026
  • Overrides the session effort level, but not the CLAUDE_CODE_EFFORT_LEVEL environment variable.bestätigt 17.11.2026
  • The per-invocation parameter requires Claude Code v2.1.292 or later.bestätigt 17.11.2026
  • Before v2.1.198, subagents ran with extended thinking disabled regardless of the main conversation's setting.steht dort nicht mehr
  • Claude Code applies your answer to the whole session, including your main conversation.bestätigt 17.11.2026
  • This field controls which skills are preloaded, not which skills the subagent can accessbestätigt 17.11.2026
  • The subagent uses this directory to build up knowledge over time, such as codebase patterns, debugging insights, and architectural decisions.bestätigt 17.11.2026
  • the main thread itself takes on that subagent's tool restrictions and modelbestätigt 17.11.2026
  • A fork can't spawn further forks.bestätigt 17.11.2026
  • Fork mode is on by default from Claude Code v2.1.302, and in an interactive terminal session from v2.1.232.bestätigt 17.11.2026
  • While 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 17.11.2026
  • Each subagent invocation creates a new instance rather than continuing an earlier one.bestätigt 17.11.2026
  • Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning.bestätigt 17.11.2026
  • no message from any agent counts as your approval for a pending permission promptbestätigt 17.11.2026
  • Subagent transcripts persist independently of the main conversationbestätigt 17.11.2026
  • The scan doesn't judge whether content is maliciousbestätigt 17.11.2026
  • Sessions with ultracode active are exempt: the limit isn't enforced there.bestätigt 17.11.2026
  • When 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 17.11.2026
  • A background subagent's results reach Claude as a completion notification in a later turn.bestätigt 17.11.2026
  • When the main conversation runs Fable, Explore's model depends on how you connectsteht dort nicht mehr
  • claude -p and the Agent SDK: Claude can wait, on its own judgment or when you ask.bestätigt 17.11.2026
  • every level of the CLAUDE.md hierarchy the main conversation loadsbestätigt 17.11.2026
  • loads only the managed policy files, or none at all when the definition comes from managed settingsbestätigt 17.11.2026
  • Use it for subagents that take everything they need from the delegation promptbestätigt 17.11.2026
  • Ignored when the agent runs as the main session agent via --agent or the agent setting.bestätigt 17.11.2026
  • A research agent used during plan mode to gather context before presenting a plan.bestätigt 17.11.2026
  • read-only tools; Write and Edit are deniedbestätigt 17.11.2026
  • it delegates research to the Plan subagent so that exploration output stays in a separate context window while the main conversation remains read-onlybestätigt 17.11.2026
  • With nothing configured, a subagent that Claude spawns from your main conversation starts in the background.bestätigt 17.11.2026
  • Interactive 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 17.11.2026
  • Turn fork mode off by setting CLAUDE_CODE_FORK_SUBAGENT to 0bestätigt 17.11.2026
  • claude -p and the Agent SDK: the spawning subagent waits while fork mode is on.bestätigt 17.11.2026
  • If you turn fork mode off, nested subagents start in the background instead.bestätigt 17.11.2026
  • Requires Claude Code v2.1.257 or later.bestätigt 17.11.2026
  • These subagents still run on the main conversation’s modelsteht dort nicht mehr
  • Sibling roster: a system reminder listing main and every other named agent in the sessionbestätigt 17.11.2026
  • /subtask isn’t available and /fork starts the forked subagent insteadbestätigt 17.11.2026
  • Three cases still need a restart:bestätigt 17.11.2026
  • The debug log names up to five top-level fields in the subagent’s file that Claude Code doesn’t recognizebestätigt 17.11.2026
  • Forks skip both filters and receive the main conversation’s exact tool pool.steht dort nicht mehr
  • The tools and disallowedTools fields also take entries for a whole MCP server:bestätigt 17.11.2026
  • The parameter overrides the effort field and stays in effect when the subagent is resumed.bestätigt 17.11.2026
  • When the main conversation is in plan mode, the subagent stays in plan mode whichever permissionMode you setbestätigt 17.11.2026
  • A subagent runs in this mode only when the main conversation doesbestätigt 17.11.2026
  • Before v2.1.238, Claude Code loaded these servers without checking trust.bestätigt 17.11.2026
  • Lower the auto-compact window for this subagent to a token count from 100000 to 1000000.bestätigt 17.11.2026
  • When the main conversation is in bypassPermissions, acceptEdits, or auto mode, the subagent runs in that same mode and Claude Code ignores the permissionMode you set.bestätigt 17.11.2026
  • 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 17.11.2026
  • Git status: a snapshot Claude Code reads from your repository when the subagent starts.bestätigt 17.11.2026
  • unless you set CLAUDE_CODE_SUBAGENT_MODEL and force it onto every subagentbestätigt 17.11.2026
  • Setting CLAUDE_CODE_SUBAGENT_MODEL by itself doesn’t change the model the built-in Explore and Plan subagents run on.bestätigt 17.11.2026

09 Bestehenden Code verstehen13 Subagenten und Schleifen14 Anweisungen und Gedächtnis20 Subagents21 Parallel arbeiten22 Teams und Workflows23 Plan vor Code31 Der Harness

Alle Quellen

↑↓ auswählenEnter öffnenDie Suche läuft im Browser. Nichts wird übertragen.