Sub-Agents & Agent Teams

Hand bounded work to a fresh, isolated agent so your main context stays clean — and know the one case where that worker needs to become a team.

Why this, for you: your main session bloats. A research detour, a five-file review, a test run — each dumps tool calls and dead ends into the one context window you need to stay sharp. Sub-agents are the pressure valve: delegate the messy part, get back only the answer. The trap is reaching for a team when a fire-and-forget sub-agent would have done the job at a fraction of the tokens.

Two delegation tools, one decision. A sub-agent is a worker you can't talk to mid-flight; a team is a set of agents that can. Pick the cheaper one that still fits the coordination the task actually needs.

1 Sub-agents: a fresh context window you never see inside

You define a sub-agent as a Markdown file with YAML frontmatter — drop it in .claude/agents/ for project scope or ~/.claude/agents/ for user scope. Each one runs in its own fresh context window. Only the final result returns to the parent; the parent never sees the sub-agent's intermediate reasoning or tool calls.

That boundary is structural, not advisory. The runtime stops a sub-agent from reading the parent context, and hands the parent only the final text response. Isolation is what keeps your main window clean — and it's exactly why several sub-agents can run at once with no coordination overhead.

The frontmatter is small: name and description are required; tools restricts which tools the agent can touch, and model routes it to opus, sonnet, or haiku. The Agent tool also takes a per-invocation model parameter that overrides the definition's default — so the same reviewer can run on haiku for a cheap pass or opus for a hard one.

# .claude/agents/reviewer.md — scoped, single-purpose worker name: reviewer tools: [Read, Grep, Glob] # least privilege — no write, no shell model: sonnet # Parent invokes it and gets back only the findings: Agent(agent: "reviewer", prompt: "Review src/parser.ts for correctness.")

Reach for sub-agents for quick, focused tasks that report back: code review, research, file search, test execution.

2 The cost ceiling — and when delegation backfires

Isolation isn't free. Spawning a worker costs tokens to describe and delegate the task on top of doing it. Anthropic's research-system retrospective reports that multi-agent systems use roughly 15× more tokens than a single-thread chat — so the delegated work has to be worth that overhead.

When a sub-agent is the wrong tool

Too small: if the work takes fewer tokens to finish than to describe, doing it inline is cheaper and faster. Hard to debug: the parent sees only the final result — a sub-agent that quietly misreads the task hides the steps that led there. The isolation that blocks pollution also blocks inspection.

And there's a hard limit on the shape itself: sub-agents cannot talk to each other. They're fire-and-forget. The moment a task needs agents to exchange partial results, challenge each other, or coordinate decisions, you've outgrown sub-agents.

3 Agent teams: when the workers must talk

Agent teams (experimental; needs Claude Code v2.1.32+, enabled via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in settings.json) coordinate multiple full sessions. One acts as team lead, assigning tasks and synthesizing; teammates work in their own context windows but share a task list and message each other directly through a mailbox — not everything routes through the lead.

	Sub-Agents	Agent Teams
Communication	One-way (result to parent)	Two-way (direct messaging)
Coordination	Parent orchestrates	Teammates self-coordinate
Context	Fresh, isolated	Independent, can share findings
State	Ephemeral	Persistent within session

Use a team only when agents genuinely need to share findings, challenge each other, and coordinate on their own — research with competing hypotheses, cross-layer features. For sequential work or same-file edits, one session or a sub-agent fan-out is cheaper and faster.

Teams scale cost — and create races

Each teammate is a full Claude Code instance with its own context, so a 5-person team burns roughly 5× the tokens of one session. Two teammates editing the same file race each other — teams need an up-front split of file ownership or parallelism destroys work instead of speeding it. Also: one team per session, no nested teams, fixed leadership, and in-process teammates don't survive /resume.

↪ Your win: delegate at the right altitude

Sub-agent for fire-and-forget — fresh isolated context, only the final result returns; your main window stays clean.
Scope it down — restrict tools and pick a model per agent; override the model per invocation when needed.
Mind the 15× tax — if the work is smaller than its own description, do it inline.
Sub-agents can't talk — the moment they must coordinate, you've outgrown them.
Team only when they must coordinate — shared task list and mailbox, at ~5× tokens and with file ownership split up front.

Retrieval practice — recall, don't peek

Question 1After a sub-agent finishes, the parent receives…

Question 2The decisive limit that forces you from sub-agents to a team is that sub-agents…

Question 3Roughly how much more token cost does a multi-agent system carry versus a single-thread chat?

Question 4Before spawning two teammates onto the same area of code, you must first…

Question 5 · spaced recall from an earlier lessonIn Plan Mode, the agent explores the codebase…

Ask me anything. Want a worked sub-agent definition for a real task of yours, or help deciding whether a job is fan-out or team-shaped? Next in Part 1: Watching the Work — using agent-view and the monitor tool to steer long runs instead of flying blind.