Subagents

A subagent is a Claude Code agent spawned by another one. The lead agent assigns a piece of work; the subagent does it in its own context window and returns a result.

Why the separate context is the whole point

The reason to delegate is rarely speed. It is that a broad search — “find every place this pattern is used across the repo” — would otherwise fill the main session’s context with file dumps that stop being useful the moment the question is answered.

A subagent absorbs that cost and hands back the conclusion. The lead agent gets the answer without the noise.

What it does not do

• It does not start warm. Each subagent begins cold and has to re-derive context the parent already has. That is the cost side of the trade, and it is why spawning one for a task you could do inline is usually a loss.
• It is not an agent team. Subagents report to one lead session. An agent team orchestrates multiple full sessions. See the comparison.
• It is not free of coordination cost. More parallelism means more merging.

Custom subagents

You can define your own with a specific model, tool access, permission set and system prompt — a read-only exploration agent, a reviewer with no write access, a specialist that only touches tests. Constraining tools per subagent is a genuine safety control, not just organisation.

At scale

Anthropic documents dynamic workflows as the pattern for orchestrating subagents at scale, and has written about how the Claude Code team itself uses it. If you find yourself hand-rolling an orchestration layer, read that first.

In the SDK

The Agent SDK exposes the same subagent mechanism, so an orchestration you design interactively in Claude Code can be lifted into a programmatic agent.