8 · Subagents

The tools/AgentTool/ directory; its main file is 228 KB. This is the most complex of all the tools — because its job is to recursively launch another complete agent.

8.1 The Primary Motivation Is Context Isolation, Not Parallelism

8.2 Three Forms

8.3 Forking: Pushing Prompt Caching to the Limit

The typical use of forking is “spawn 5 subagents at once to explore the same problem from different angles.” Their five contexts are almost identical — the only difference is the final line: “you take direction A / B / C / D / E.”

Prompt caching is prefix-matched. So:

Four things done to make that happen

① The system prompt is passed as “already-rendered bytes”

/**
 * The getSystemPrompt here is unused: the fork path passes
 * `override.systemPrompt` with the parent's already-rendered system prompt
 * bytes, threaded via `toolUseContext.renderedSystemPrompt`. Reconstructing
 * by re-calling getSystemPrompt() can diverge (GrowthBook cold→warm)
 * and bust the prompt cache; threading the rendered bytes is byte-exact.
 */

claude-code/src/tools/AgentTool/forkSubagent.ts

Put plainly: the getSystemPrompt here goes unused: the fork path passes the parent's already-rendered system prompt bytes, threaded through the renderedSystemPrompt field. Regenerating by calling the generator again can diverge (because the feature-flag config may have gone from cold cache to warm cache), which busts the prompt cache; passing the rendered bytes is byte-exact.

To unpack the trap: the system prompt's content isn't entirely fixed; it can include A/B experiment variants. And the experiment config is itself cached — at the moment the parent generates its prompt, some experiment config may still be in a “cold cache” state (using the default value); a few seconds later, when the child regenerates it, the config has become “warm cache” (using the real value). The two generations produce different bytes, and the cache is wasted entirely.

The corresponding field is defined in Tool.ts:

/**
 * Parent's rendered system prompt bytes, frozen at turn start.
 * Used by fork subagents to share the parent's prompt cache — re-calling
 * getSystemPrompt() at fork-spawn time can diverge (GrowthBook cold→warm)
 * and bust the cache. See forkSubagent.ts.
 */
renderedSystemPrompt?: SystemPrompt

“frozen at turn start” — that's the key.

② The tool list is inherited as-is

/**
 * Synthetic agent definition for the fork path.
 *
 * Not registered in builtInAgents — used only when `!subagent_type` and the
 * experiment is active. `tools: ['*']` with `useExactTools` means the fork
 * child receives the parent's exact tool pool (for cache-identical API
 * prefixes). `permissionMode: 'bubble'` surfaces permission prompts to the
 * parent terminal. `model: 'inherit'` keeps the parent's model for context
 * length parity.
 */
export const FORK_AGENT = {
  tools: ['*'],
  permissionMode: 'bubble',
  model: 'inherit',
  ...
}

Each of the three fields has its reason:

• tools: ['*'] together with useExactTools — the child gets the parent's exact tool pool. It won't use that many tools, but tool definitions are part of the request prefix; change them and the cache is gone.
• permissionMode: 'bubble' — permission confirmations bubble up to the terminal where the parent lives. The subagent has no UI of its own.
• model: 'inherit' — inherits the parent's model, guaranteeing the same context window size. If the child used a model with a smaller window, the inherited history might simply not fit.

③ Message construction: only the last text block differs

/**
 * Build the forked conversation messages for the child agent.
 *
 * For prompt cache sharing, all fork children must produce byte-identical
 * API request prefixes. This function:
 * 1. Keeps the full parent assistant message (all tool_use blocks, thinking, text)
 * 2. Builds a single user message with tool_results for every tool_use block
 *    using an identical placeholder, then appends a per-child directive text block
 *
 * Result: [...history, assistant(all_tool_uses), user(placeholder_results..., directive)]
 * Only the final text block differs per child, maximizing cache hits.
 */
export function buildForkedMessages(...)

What's clever about the “placeholder tool results”: the parent's message contains 5 tool calls (one per fork). By the API's rules, every tool call must have a paired result. But the 5 forks haven't finished yet, so real results don't exist. So each one gets filled with exactly the same placeholder content — satisfying the pairing requirement while guaranteeing all 5 children see an identical stretch.

The source even has a dedicated constant for it:

/** Must be identical across all fork children for prompt cache sharing. */

④ The recursive-fork guard: moved down from the interface layer to the call layer

/**
 * Guard against recursive forking. Fork children keep the Agent tool in their
 * tool pool for cache-identical tool definitions, so we reject fork attempts
 * at call time by detecting the fork boilerplate tag in conversation history.
 */
export function isInForkChild(messages: MessageType[]): boolean { ... }

The conventional approach is “remove the Agent tool from the subagent's tool pool.” But that changes the tool definitions and breaks the cache. So instead: keep the tool, but at the moment it's actually called, check the conversation history for a fork marker:

if (isInForkChild(toolUseContext.messages)) {
  throw new Error('Fork is not available inside a forked worker. '
                + 'Complete your task directly using your tools.')
}

An extra notice for worktree isolation

/**
 * Notice injected into fork children running in an isolated worktree.
 * Tells the child to translate paths from the inherited context, re-read
 * potentially stale files, and that its changes are isolated.
 */
export function buildWorktreeNotice(...)

If a forked child runs in an isolated git worktree, the file paths in the history it inherited point at the parent's directory. So it has to be told explicitly: translate paths, files may no longer be the version you saw, and your changes are isolated.

8.4 Tool Restrictions on Subagents

export const ALL_AGENT_DISALLOWED_TOOLS = new Set([
  TASK_OUTPUT_TOOL_NAME,        // can't view other tasks' output
  EXIT_PLAN_MODE_V2_TOOL_NAME,  // can't exit plan mode (session-wide global state)
  ENTER_PLAN_MODE_TOOL_NAME,    // can't enter plan mode
  // internal users may nest subagents; external users may not
  ...(process.env.USER_TYPE === 'ant' ? [] : [AGENT_TOOL_NAME]),
  ASK_USER_QUESTION_TOOL_NAME,  // ★ can't ask the user questions
  TASK_STOP_TOOL_NAME,          // can't stop other tasks
  // prevent recursive workflow execution inside a subagent
  ...(feature('WORKFLOW_SCRIPTS') ? [WORKFLOW_TOOL_NAME] : []),
])

export const CUSTOM_AGENT_DISALLOWED_TOOLS = new Set([...ALL_AGENT_DISALLOWED_TOOLS])

claude-code/src/constants/tools.ts

The allowlist for background async agents is stricter

/*
 * Async Agent Tool Availability Status (Source of Truth)
 */
export const ASYNC_AGENT_ALLOWED_TOOLS = new Set([
  FILE_READ_TOOL_NAME,      // read files
  WEB_SEARCH_TOOL_NAME,     // web search
  TODO_WRITE_TOOL_NAME,     // todo list
  GREP_TOOL_NAME,           // content search
  WEB_FETCH_TOOL_NAME,      // fetch web pages
  GLOB_TOOL_NAME,           // filename search
  ...
])

Note the shift here from a “denylist” to an “allowlist” — and nearly everything on it is a read-only tool.

8.5 Constructing a Subagent's Context

Creating a subagent constructs a new ToolUseContext. Several fields are handled with care:

/**
 * Always-shared setAppState for session-scoped infrastructure (background
 * tasks, session hooks). Unlike setAppState, which is no-op for async agents
 * (see createSubagentContext), this always reaches the root store so agents
 * at any nesting depth can register/clean up infrastructure that outlives
 * a single turn. Only set by createSubagentContext; main-thread contexts
 * fall back to setAppState.
 */
setAppStateForTasks?: (f: (prev: AppState) => AppState) => void

Put plainly: an “always-shared” state setter for session-scoped infrastructure (background tasks, session hooks). Unlike the regular setAppState (a no-op for async agents), this one always reaches the root store — so an agent at any nesting depth can register or clean up infrastructure that outlives a single turn. Only set when a subagent context is created; main-thread contexts fall back to the regular setAppState.

Two more related fields:

agentId?: AgentId      // set only for subagents; hooks use it to tell whether a call came from a subagent
agentType?: string     // the subagent's type name

/** When true, preserve toolUseResult on messages even for subagents.
 *  Used by in-process teammates whose transcripts are viewable by the user. */
preserveToolUseResults?: boolean

That last field tells you: by default, a subagent's tool results are discarded (saves memory; the user can't see them anyway). But for the “in-process teammate” kind of subagent, whose transcript is visible to the user, they're kept.

8.6 Built-in Agent Types

tools/AgentTool/builtInAgents.ts defines several built-in types; the most commonly used:

Users can also define their own — write a Markdown file under .claude/agents/*.md, with front matter declaring the name, description, available tools, and model. loadAgentsDir.ts handles loading them.

8.7 The Forms Background Tasks Take

The tasks/ directory holds several task forms; they differ in “where it runs” and “how it communicates”:

Task completion is reported back to the main loop via the message queue — the “process-level global queue” from section 3.9, where each agent takes only the notifications addressed to it.

8.8 Cascading Interruption

The abort controllers form a tree: