Sub-Agents for Fan-Out Research and Context Isolation¶

Spawn sub-agents to parallelize independent work in isolated context windows — the main thread receives only distilled results, not raw exploration.

Learn it hands-on with Breaking the Stack, a guided lesson with quizzes.

Also known as

Sub-Agents Fan-Out, Parallel Dispatch, Scatter-Gather. For the broader pattern survey, see Agent Composition Patterns. For the synthesis variant, see Fan-Out Synthesis. For the delegation variant, see Orchestrator-Worker.

The problem¶

Sequential in-thread research exhausts context fast. An agent reviewing ten files or fetching five URLs collects all the raw material in its context window. By the time it synthesizes results, the window is crowded with exploration artifacts: partial reads, dead ends, and intermediate notes that compete with the work that matters.

Context isolation as the core benefit¶

Sub-agents solve two problems, and isolation is the more important one:

Parallelism — spawn N sub-agents at once instead of running N tasks one after another.
Context isolation — each sub-agent has its own context window, so its exploration never enters the main thread.

The main thread dispatches tasks and receives only synthesized results. Raw work such as file reads, URL fetches, and retries happens entirely within sub-agent contexts, which are discarded when the sub-agent finishes.

This is the principle behind context engineering (Anthropic's framing): sub-agents as a context management strategy, not just a parallelism strategy.

Fan-out pattern¶

graph TD
    M[Main Agent] --> S1[Sub-Agent: File A]
    M --> S2[Sub-Agent: File B]
    M --> S3[Sub-Agent: File C]
    S1 -->|Summary| M
    S2 -->|Summary| M
    S3 -->|Summary| M
    M --> R[Synthesized Result]

Each sub-agent receives a focused task and returns a distilled summary, not the full file contents.

Claude Code implementation¶

You define Claude Code sub-agents in .claude/agents/, where YAML frontmatter controls scope, tools, and permissions (docs). The parent agent invokes them by name. Claude Code manages the context boundary.

Key frontmatter fields for sub-agents:

tools: restrict to only what the task needs (a research sub-agent may not need Write)
model: route to a cheaper or faster model for simpler sub-tasks
isolation: worktree: run in an isolated git worktree for file-writing sub-agents

Sub-agents can themselves fan out: as of Claude Code v2.1.172, a sub-agent can spawn its own sub-agents up to five levels deep, giving nested fan-out a concrete depth bound.

Agent teams¶

Agent teams (docs) are a distinct pattern: multiple coordinated agents working in parallel on related tasks with shared state. Sub-agents are fire-and-forget with isolated context. Teams are persistent and carry coordination overhead.

Use sub-agents when tasks are independent, produce distillable results, and context isolation matters more than shared state. Use agent teams when agents need to share evolving state, tasks are interdependent, or coordination is worth the overhead.

What to return from sub-agents¶

Sub-agents should return the minimum needed for synthesis, not the raw material:

Not: full file contents, raw HTML, complete API responses
Yes: extracted findings, structured summaries, specific facts with source attribution

A sub-agent reading a 5000-token page should return a 200-token summary of the relevant facts. The 4800 tokens it consumed vanish when it finishes.

Example¶

The following shows a Claude Code sub-agent definition and its invocation pattern. The sub-agent is scoped to read-only file analysis — the parent agent fans out to three of these in parallel, each reading a different module, and receives only distilled summaries back.

# .claude/agents/file-summarizer.md
---
name: file-summarizer
description: Reads a single source file and returns a concise summary of its purpose,
  exports, and key dependencies. Used internally for fan-out research tasks.
tools:
  - Read
  - Glob
model: claude-haiku-3-5
---

Read the file at the path provided. Return:
- One sentence describing what the file does
- List of exported functions/classes (names only)
- External dependencies imported

Return only these three items. Do not include file contents.

The parent agent dispatches three sub-agents in parallel:

Analyze the authentication module. Use the file-summarizer sub-agent to read
each of these files simultaneously and return summaries:
- src/auth/login.ts
- src/auth/session.ts
- src/auth/middleware.ts

The main thread receives three 200-token summaries. The raw file contents — potentially thousands of tokens of implementation detail — never enter the main context window. The parent agent synthesizes the architecture from summaries alone.

Error isolation in parallel tool calls¶

As of a June 2, 2026 Claude Code release (changelog), a failed Bash command in a batch of parallel tool calls no longer cancels the other calls in that batch. Each tool returns its own result independently. Previously a single failed Bash call would abort its siblings running in parallel.

This matters for fan-out because sub-agents routinely issue parallel calls. Before the change, one failing command could abort every parallel call in flight; now successful calls complete and only the failed call reports an error. Fan-out sub-agents handle partial failures gracefully instead of losing all concurrent work.

When this backfires¶

Fan-out sub-agents add overhead that makes them worse than in-thread execution in several cases:

Small tasks, low token volume — spawning three sub-agents to read three 100-token files costs more latency and money than three sequential in-thread reads. Isolation pays off only when each sub-agent's exploration would otherwise crowd the main context.
Interdependent tasks — when sub-task B depends on sub-task A's output, fan-out collapses into a two-phase sequence that removes the parallelism benefit.
Cost-sensitive workloads — N parallel sub-agents mean N model invocations at once. For simple sub-tasks, a single agent with context compaction is cheaper.
Synthesis is the bottleneck — if assembling N summaries means reading most of the raw detail anyway, the main thread context fills up regardless.

Key Takeaways¶

Sub-agents have isolated context windows — exploration never pollutes the main thread
Fan-out: N tasks dispatched in parallel, distilled results returned to main
Main thread sees summaries, not raw work — context stays clean for synthesis
Claude Code sub-agent frontmatter controls tools, model, and worktree per sub-task
Sub-agents differ from agent teams: fire-and-forget vs persistent coordination
A failed Bash call in a parallel batch no longer cancels its siblings — each tool returns its own result independently