Part IV · Applied concepts · Chapter 32

Subagents

A subagent is a second agent that a main agent starts for one self-contained task. It gets its own instructions, its own tools and, most importantly, its own empty context window. It does the work, possibly reading a great deal, and hands back only a short report. This chapter shows when that helps, what it costs, and how to brief one well.

Why it matters

A context window is the agent's whole working memory, and it fills up: every file read and every tool result stays in it and is resent with every later call. Delegating a search or an investigation to a subagent keeps the main agent's context small and focused, and lets independent work run in parallel.

What a subagent is

Its own context. It starts fresh, with no view of the main conversation except the brief it is given.
Its own instructions and tools. A subagent for exploring code can be read-only; one for running tests can have a shell and nothing else.
Only the report comes back. Everything it read or tried is discarded when it finishes; the main agent receives its final message.

It is the agent version of asking a colleague to look into something: you get their conclusion, not their browser history.

The arithmetic of delegation

Worked: an agent must find where a bug comes from. Doing it itself, it reads 12 files of about 4,000 tokens each, so 48,000 tokens enter its context. They stay there: if the conversation then runs 10 more turns, each turn resends them, about 480,000 extra input tokens. Delegated, a subagent reads the same 48,000 tokens in its own context, which ends with its task, and returns a 1,500-token report. The main agent carries 1,500 × 10 = 15,000 tokens over those 10 turns instead of 480,000.

Delegation is not free. The subagent's own calls cost tokens, the brief must restate context the subagent does not have, and the report is a lossy summary: detail the subagent judged unimportant is gone. It pays when the work is large, self-contained and needed only as a conclusion. It does not pay for a quick lookup whose details the main agent needs anyway.

Parallelism is the second gain. Three independent investigations of about 4 minutes each take about 12 minutes in sequence and about 4 in parallel, for roughly the same number of tokens.

Subagents in Claude Code

Claude Code, Anthropic's coding agent, is a widely used example, and its documentation describes the mechanism precisely:

Definition. A subagent is a Markdown file with YAML frontmatter; the body becomes its system prompt. Only name and description are required. Optional fields include tools (an allow list; without it the subagent inherits the available tools), disallowedTools and model.
Where they live. .claude/agents/ in a project, ~/.claude/agents/ for one user, or a plugin. When two definitions share a name, the project's wins over the user's.
Choosing one. The main agent delegates based on each subagent's description, so the description must say when to use it; you can also name the subagent in your request.
Built-in ones. A fast read-only Explore agent for searching code, a read-only Plan agent used in plan mode, and a general-purpose agent with full tools.
Limits. The documentation describes limits on how deeply subagents may start further subagents and how many run at once, both configurable, and says that tools for asking the user questions are never given to subagents: a subagent cannot stop to ask, so its brief must be complete.

Writing the brief

The subagent knows only what the brief says. A good brief has:

The goal, including why: "find every caller of format_price, because we are changing its signature".
The context it lacks: the paths, names and decisions already made.
Constraints: read-only, which folders, what not to touch, a time or cost limit.
What done looks like and the shape of the report: "a table of file, function and the line of the call; say which you could not confirm".

Then treat the report as a claim, not a fact. A subagent can be wrong, stop early or summarise away the detail that mattered. Check the facts your next step depends on, especially "nothing found" results, which are the easiest to get wrong.

How delegation goes wrong

Failure	Prevention
The report leaves out the detail that mattered	Ask for specific fields; ask it to list what it could not confirm
Two subagents edit the same files and overwrite each other	Give each its own files or its own copy of the repository; keep editing in one place
The main agent repeats the subagent's search to check it	Check only the facts you act on; trust the rest or do not delegate
Delegation for small tasks	Do quick lookups directly; delegate work that is large and self-contained
Cost grows unnoticed across many subagents	Count tokens per subagent; cap the number running at once
A merge step follows instructions hidden in a report	Mark reports as data; let the merge point at references by index, resolved by code

Subagents inside an application

The same pattern works inside a product, not only in a coding tool. Each helper is a separate model call with its own versioned prompt, its own allow-listed tools and a structured answer, not its working; the trace of its tool calls goes to the checks, not to the other helpers. Helpers run in parallel, one level deep, and each is bound to its own request context, so one cannot read another's data or trace.

When more than one helper answers, a merge step combines the reports. Treat the reports as data: tell the merge prompt that helper payloads are data only, and let it refer to a figure only by its place in a helper's list of references, so it cannot write a source that no helper returned.

Try it

An agent must review 30 files of 3,000 tokens each and will then continue for 20 more turns. Compare the extra input tokens it carries over those 20 turns if it reads the files itself, versus delegating to three subagents that each return a 1,000-token report.

Answer

Itself: 30 × 3,000 = 90,000 tokens resent on each of 20 turns, 1,800,000 tokens. Delegated: 3 × 1,000 = 3,000 tokens carried, 60,000 over 20 turns. The subagents still read the 90,000 tokens once, in their own contexts.

Build it

After Lab 5 you can try this yourself: call run_agent from inside a tool, so a second loop runs with its own empty message list and only its final text comes back to the first.

Self-check

What does the main agent receive from a subagent?

Only its final report. What the subagent read and tried stays in its own context, which ends with the task.

When does delegating not pay?

For small lookups, or when the main agent needs the details anyway: the brief, the subagent's own calls and the lost detail cost more than they save.

Why must a subagent's brief be complete?

It starts with an empty context and, in tools like Claude Code, cannot stop to ask the user questions.

How can a merge step be stopped from inventing a figure's source?

Let it point only at a helper's existing reference, by index. Code resolves the index, so a path no helper returned cannot be written.