title: "Sub-Agents" last_updated: 2026-03-21 status: proven difficulty: intermediate prerequisites: [03-prompting-for-agents]

Sub-Agents

The Core Question: When and How Do I Delegate to Child Agents?

At some point, a single agent conversation hits a wall. The task is too big, the context window is too full, or two parts of the work could run simultaneously but cannot because the agent can only do one thing at a time. You find yourself wishing you had a second pair of hands.

Sub-agents are that second pair of hands. A sub-agent is a child agent spawned by a parent agent to handle a specific piece of work. It gets its own context window, does its job, and returns a result to the parent. The parent coordinates, the children execute. This is the same division of labor you see in any well-run engineering team — a tech lead does not write every line of code personally. They delegate, review, and synthesize.

Understanding when and how to use sub-agents is the difference between an agentic workflow that handles complex tasks gracefully and one that chokes on anything larger than a single file change.

The Delegation Principle

Think about how you delegate to a junior developer. You do not hand them a vague gesture toward the codebase and say "make it better." You give them a specific task, the context they need to complete it, and clear criteria for what done looks like. Then you step back and let them work.

Sub-agent delegation follows the same pattern. The parent agent writes a prompt — the handoff — that tells the child agent what to do, what context it needs, and what to return. The quality of that handoff determines the quality of the result. A vague handoff produces vague results. A precise handoff produces precise results.

This is worth internalizing because it means your skill at writing good prompts — the skill you developed in Module 03 — directly translates to your skill at orchestrating sub-agents. The prompt is the handoff. Everything the sub-agent needs to know must be in that prompt, because the sub-agent does not inherit the parent's full conversation history.

When to Use Sub-Agents

Sub-agents earn their keep in specific situations. Reaching for them reflexively wastes tokens. Reaching for them at the right moment transforms what is possible.

Independent tasks. When a task decomposes into parts that do not depend on each other, sub-agents can execute those parts simultaneously. Adding tests to three unrelated modules, updating documentation for five separate APIs, implementing three independent features — these are natural candidates.

Parallel work. A single agent is sequential. Sub-agents let you fan out. If you need to research three different approaches before deciding which to pursue, three sub-agents can explore all three in the time one agent would explore one.

Isolation needed. Some tasks benefit from a clean context window. If the parent agent's context is already full of information about the frontend, sending a sub-agent to work on the backend means the backend work gets a fresh, uncluttered context. The sub-agent is not confused by irrelevant details.

Exploratory research. When you need to understand something before acting on it — how a library works, what an unfamiliar module does, where a pattern is used across the codebase — a research sub-agent can investigate without cluttering the parent's context with raw findings. It returns a summary, not a firehose.

Large-scale refactoring. When a change touches many files that can be modified independently, sub-agents can each handle a subset while the parent coordinates the overall effort.

When NOT to Use Sub-Agents

Sub-agents are not free. They have startup cost, they consume additional tokens, and they introduce coordination complexity. Use them when the benefit exceeds the overhead.

Tightly coupled tasks. If step two depends on the exact output of step one, and step three depends on step two, running these as sub-agents adds coordination overhead without parallelism. Just do them sequentially in the parent.

Simple sequential work. If the task is straightforward and fits comfortably in a single context window, sub-agents add complexity for no gain. Do not use a team when one person is enough.

Context sharing is critical. Sub-agents get their own context window. They do not see the parent's full conversation history. If the task requires deep understanding of a long, nuanced discussion that has been building up in the parent session, a sub-agent will not have that understanding. You would have to summarize the entire discussion into the handoff prompt, and something will inevitably be lost.

The task is too small. Spawning a sub-agent has overhead — the system prompt loads, the agent orients itself, it reads necessary files. If the actual work is a five-line change, the overhead exceeds the work. Just do it in the parent.

The Fan-Out/Fan-In Pattern

The most common sub-agent pattern is fan-out/fan-in. It works like this:

  1. Decompose. The parent identifies the pieces of the task that can run independently.
  2. Fan out. The parent spawns one sub-agent for each piece, giving each a clear prompt.
  3. Execute. The sub-agents work simultaneously (or sequentially, depending on the tool).
  4. Fan in. The sub-agents return their results to the parent.
  5. Synthesize. The parent combines the results, resolves any inconsistencies, and produces the final output.

This pattern is powerful because it trades tokens for time. Three sub-agents running in parallel cost the same total tokens as one agent doing the work sequentially, but they finish faster. And each sub-agent gets a clean context window focused on its specific piece, which often produces better results than one agent trying to juggle everything.

The synthesis step is where the parent earns its keep. Raw sub-agent output often needs integration — making sure naming is consistent across the three new modules, resolving a conflict between two sub-agents' approaches, deciding which of three research summaries is most relevant.

Context Boundaries

This is the single most important thing to understand about sub-agents: they get their own context window. They do not inherit the parent's full state.

When a parent spawns a sub-agent, it writes a prompt. That prompt — plus the system prompt and any files the sub-agent reads — is the sub-agent's entire world. It does not know what the parent discussed five messages ago. It does not know about the decision the parent made three steps back. It does not know about the other sub-agents running in parallel.

This is a feature, not a bug. Clean context boundaries are what make sub-agents effective. A research sub-agent that inherits 50,000 tokens of irrelevant parent context is worse off than one that starts fresh with a clear, focused prompt. But it means you must be intentional about what you put in the handoff.

The practical implication: when prompting for sub-agent usage, include all relevant context in the prompt you expect the parent to pass along. Do not assume the sub-agent will "just know" things from the parent conversation. If it matters, say it explicitly.

Sub-Agent Types

Different types of work call for different types of sub-agents. While the underlying mechanism is the same — spawn an agent with a prompt — the intent and behavior patterns differ.

Research and exploration agents. Their job is to investigate and report back. They read files, trace through code, search for patterns, and return a summary. They do not modify anything. Use them when you need to understand something before deciding what to do.

Implementation agents. Their job is to make changes. They edit files, create new files, and verify their work. Use them for well-defined implementation tasks where the requirements are clear and the work is independent.

Review agents. Their job is to evaluate work. They read code, check for issues, compare against conventions, and report findings. Use them after implementation to catch problems before you commit.

Coordination Patterns

How sub-agents relate to each other determines the coordination pattern.

Independent. Each sub-agent works on a completely separate piece. They do not interact. The parent dispatches them, collects results, and synthesizes. This is the simplest pattern and the most common.

Sequential. The output of one sub-agent feeds into the next. A research agent investigates, its findings go into a planning agent, the plan goes into an implementation agent. The parent acts as the relay, passing context between stages.

Parallel. Multiple sub-agents run simultaneously on related but independent work. This maximizes throughput but requires that the tasks genuinely be independent — if two sub-agents try to edit the same file, you have a conflict.

The Overhead Question

Sub-agents are not free. Every sub-agent incurs costs:

  • Token cost. The sub-agent's system prompt, the handoff prompt, and everything it reads and generates all consume tokens. If the task is trivial, the overhead exceeds the work.
  • Startup time. The sub-agent needs to orient itself — read files, understand context, plan its approach. For very small tasks, this startup time is disproportionate.
  • Coordination cost. The parent spends tokens managing sub-agents — writing handoff prompts, reading results, synthesizing output. More sub-agents means more coordination.

The break-even point is roughly this: if the sub-task would take more than a few minutes in the parent and benefits from isolation, parallelism, or a fresh context window, a sub-agent is worthwhile. If the sub-task is quick, sequential, and benefits from the parent's existing context, just do it inline.

Error Handling

Sub-agents can fail. They can misunderstand the task, go off on a tangent, produce incorrect output, or hit errors they cannot recover from. The parent must be prepared for this.

In practice, error handling for sub-agents is not fundamentally different from error handling for any delegated work. You review the output. If it is wrong, you correct course — either by giving the sub-agent more specific instructions and trying again, or by handling the task differently.

The key insight is that sub-agent failures are contained. A sub-agent that goes off the rails does not corrupt the parent's context or pollute the work of other sub-agents. This is one of the advantages of isolation — failure stays local.

Worktrees: Isolated File Systems for Parallel Editing

One challenge with parallel sub-agents is file conflicts. If two sub-agents try to edit the same file simultaneously, the results are unpredictable. Worktrees solve this problem.

A worktree is an isolated copy of your file system — specifically, a git worktree that shares the same repository history but has its own working directory. Each sub-agent that runs in a worktree gets its own copy of the files. It can edit freely without conflicting with other agents or the parent. When it finishes, its changes can be merged back.

This pattern is essential for large-scale parallel refactoring. If you want three sub-agents to each update a different set of files, and some of those files might overlap (e.g., a shared import file), worktree isolation prevents conflicts. Each sub-agent works in its own sandbox, and the merge step handles integration.

Not every sub-agent task needs worktree isolation. If the sub-agents are working on truly independent files with no overlap, standard parallel execution is fine. Worktrees matter when there is any risk of file-level conflict.

Key Takeaways

  • Sub-agents are child agents that handle specific pieces of a larger task. The parent coordinates, the children execute.
  • The prompt is the handoff. Sub-agents do not inherit the parent's context. Everything they need must be in the prompt they receive.
  • Use sub-agents for independent, parallel, or isolation-needing work. Do not use them for tightly coupled sequential tasks or trivially small work.
  • The fan-out/fan-in pattern is the workhorse. Decompose, dispatch, execute, collect, synthesize.
  • Context boundaries are a feature. Clean separation keeps sub-agents focused, but it means you must be explicit about what they need to know.
  • Sub-agents have overhead. Token cost, startup time, and coordination cost are real. Use sub-agents when the benefit exceeds this cost.
  • Worktrees solve file conflicts. When parallel sub-agents might edit overlapping files, worktree isolation prevents collisions.
  • Sub-agent failures are contained. A failing sub-agent does not corrupt the parent or other sub-agents. Review output, correct course, and move on.