What is a subagent?

What is a subagent and what does it isolate?

A subagent is not a new kind of model. It is a second run of the same loop the parent runs: a system prompt, a set of tool definitions, a fresh conversation. The parent invokes it by calling a tool (in the Claude Agent SDK the tool is named Agent), and passes a prompt string. Everything the subagent then reads, writes and reasons about stays inside that new conversation. Only its final message comes back to the parent as the tool result.

Three things travel from parent to subagent: the tool prompt, the subagent's own system prompt from its definition, and the tool set the definition allows. Three things do not: the parent's conversation history, the parent's prior tool results, and the parent's system prompt. That gap is the isolation the pattern is named for, and it is the reason any file path, error message or decision the subagent needs has to be in the tool prompt.

The Claude Agent SDK lets you register subagents by name, either as YAML markdown files under .claude/agents/ or programmatically in the agents option. Each definition carries a description, a prompt, an optional tools allowlist and an optional model override, so a read-only reviewer subagent can run Read and Grep only, while a test-runner subagent gets Bash.

How does the parent pick and invoke a subagent?

Three routes, all resolving to a tool call. The parent can call the Agent tool on its own, matching the user's request against each registered subagent's description. The user can name one in the prompt (write "use the code-reviewer agent" and the model routes to that definition). Or the runtime can start the whole session as a specific subagent through a CLI flag. In every case the invocation is a tool call, and the reply is a tool result the parent reads like any other tool output.

Subagents can spawn subagents. Claude Code caps the nesting at three layers by default and the concurrent count at twenty, and both are tunable through CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH and CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. A dollar cap on the whole query, maxBudgetUsd in TypeScript or max_budget_usd in Python, refuses further spawns and ends the run once the estimated spend is reached. Set at least one of these before you run anything unattended: without them a single prompt can grow into a tree whose cost you did not intend.

When does a subagent help, and when does it just cost more?

The trade is context spend against latency and dollars. Delegating a file-heavy search to a subagent keeps twenty file reads out of the parent's window, which is usually worth more than the extra requests it costs. Delegating a two-sentence answer is pure overhead: the tool prompt has to carry every fact the subagent needs, because it inherits nothing else, and the round trip adds a full request pair.

The other reason to reach for a subagent is a genuinely different job that wants a different prompt or a different tool set. A read-only reviewer with Read, Grep and Glob is safer than the parent's full toolbox, and easier to reason about. If the subagent has the same tools and the same instructions as the parent, you are paying for isolation you may not need.

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for security and clarity. Use for PR reviews.
tools: Read, Grep, Glob
model: sonnet
---
You are a code reviewer. Report specific line-level findings.

# what the parent sees in the message stream
tool_use   name=Agent  input={subagent_type: "code-reviewer",
                              prompt: "Review src/auth/*.ts for
                                       injection risk"}
tool_result content="Two findings: unescaped query on line 42,
                     missing origin check on line 88."