Inside Claude Code subagents: context, control, and common mistakes

Context: how isolation works

A common misconception is that subagents are mini-experts — smaller, specialized Claudes that know more about a topic than the main thread. In reality, Claude already has all the knowledge in every context window. Subagents don’t add capability. They add isolation.

When you launch a subagent, it runs in a separate context window. It receives a task, explores independently — reading files, searching code, running commands — and returns only a summary. All intermediate work stays in the subagent’s context and is discarded when it finishes.

Why does this matter? Context windows are finite. Every file read, every tool call, every intermediate result fills your main thread’s context. As it fills, the conversation degrades — the agent loses track of earlier decisions, makes contradictory choices, and produces worse output. Subagents are a pressure valve: they offload exploratory work so the main thread stays clean.

This reframes how you should think about subagent design. Don’t design them around expertise. Design them around what work you don’t need to see.

It also helps to understand what subagents are not. Skills add knowledge to your current conversation — they load instructions into the existing context. Subagents do the opposite: they spin up a separate context and return only results. Skills enhance; subagents isolate. Knowing this distinction prevents you from reaching for a subagent when a skill would be the right tool.

Control: the description field

Every subagent has a description field in its config. Most people treat it as metadata — a label for what the subagent does. It’s actually the highest-leverage control surface you have.

The description plays two roles. First, it controls when the main agent launches the subagent. The name and description of every available subagent are included in the main agent’s system prompt — this is how it decides which subagent to use and when.

Second — and this is the non-obvious part — the description shapes what instructions the main agent writes when it delegates a task. When the main agent launches a subagent, it composes an input prompt. It uses the description as guidance for writing that prompt. So the description doesn’t just control triggering — it programs the parent agent’s delegation behavior.

Use this agent
for code review.

You must tell the
agent precisely which
files you want it to
review. Return sources
that can be cited.

The generic version leaves the main agent to figure out scope on its own — it will write a vague delegation prompt like “use git diff to find the current changes.” The steering version causes the main agent to write a specific prompt that lists actual files and requests citable output. The description text steered the parent’s behavior.

Common mistakes: three anti-patterns

“Expert” personas

Naming a subagent “Senior Staff Engineer” or “Python Expert” adds zero capability. Claude already has that knowledge in every context window. There is nothing a so-called expert subagent can do that your main thread can’t do directly. Personas don’t unlock new abilities — they just add noise to the system prompt.

Test runners

This one is counterintuitive. When tests fail, you need the full output to diagnose the issue. A subagent that returns “3 tests failed” forces you to build additional tooling just to recover information that direct output would have shown for free. The summarization that makes delegation useful elsewhere is exactly what destroys a test run.

Sequential pipelines

A three-agent pipeline — reproduce bug → debug → fix — sounds clean on paper. It fails in practice because information degrades at every handoff. Bug fixing almost always depends on discoveries from the previous step: the specific error message, the stack trace, the unexpected state. Each summarization boundary loses critical context. If steps depend on each other, keep them in the main thread.

What actually works

Structured output creates stopping points

The single most impactful improvement for any subagent is a defined output format in its system prompt. Without one, subagents don’t know when they’re done. They lack internal stopping criteria, so they keep researching, reading more files, and exploring more paths — running far longer than necessary.

A structured format solves this by creating a checklist. Once every section is filled in, the subagent knows it can stop. It also ensures the summary that returns to the main thread is actually usable.

Return your review as:

## Summary
## Critical Issues
## Major Issues
## Minor Issues
## Recommendations
## Approval Status
## Obstacles Encountered

Obstacle reporting prevents knowledge loss

When a subagent discovers a workaround during its work — a dependency quirk, a command that needs a special flag, an environment issue — those details need to appear in its summary. If they don’t, the main thread has to rediscover the same solutions on its own. That’s wasted time and wasted tokens.

The fix is simple: add an explicit “Obstacles Encountered” section to the output format. This surfaces setup issues, workarounds, commands needing special flags, and dependency problems reliably.

Limit tool access to what the subagent actually needs

Not every subagent needs every tool. Restricting tool access does two things: it prevents unintended side effects, and it makes each subagent’s role clearer when you have several of them.

Here’s a practical breakdown by subagent type:

• Research / read-only subagent — Only needs Glob, Grep, and Read. Cannot accidentally modify files.
• Code reviewer — Needs Bash access to run git diff and see what changed, but doesn’t need Edit or Write.
• Styling / code modification agent — Give Edit and Write access here, because the subagent’s job is to change code.

Tool restriction is the security counterpart to structured output: output formats define when the subagent stops, tool restrictions define what it can touch while running.

Choose the right model for the task

Subagents can run on different models than the main thread. The options are:

• Haiku — Fast and lightweight. Best for quick searches, simple file lookups, and high-volume exploratory work where speed matters more than depth.
• Sonnet — A middle ground. Good for code review and general-purpose delegation where you want solid analysis without Opus-level cost.
• Opus — Best for complex analysis that requires deep reasoning. Use when the subagent’s output is critical to a decision.
• Inherit — Uses whatever model the main conversation is running. The default, and often the right call when you don’t have a specific reason to diverge.

Matching the model to the task’s importance keeps fast work fast and reserves deeper reasoning for when it actually pays off.

The decision rule

When deciding whether to use a subagent, there’s one question that matters: does the intermediate work matter to your main thread?

If the answer is no — you just need the result and don’t care about the journey — delegate it. A research subagent can read dozens of files, trace function calls, and explore code paths. All that exploration stays in the subagent’s context. Your main thread gets a clean answer.

If the answer is yes — you need to see and react to what happens along the way — keep it in the main thread.

Delegate

• Research — “Where is JWT validated in this codebase?”
• Code review — A fresh context window catches things the main thread misses because it wrote the code
• Custom system prompts — Styling agents that pre-load design system files, copywriting agents with tone guidelines

Keep in main thread

• Debugging — You need the full error context to diagnose
• Test runs — Failure output must be visible, not summarized away
• Sequential workflows — Each step depends on what the previous step discovered

One special case worth noting: code review. Claude reviews code more effectively when presented in a separate context from where it was written. If you built a feature over many turns in your main thread and then ask that same thread to review it, the feedback is weak — it was involved in creating the code and cannot see it with fresh eyes. A reviewer subagent sees the changes in a clean context, free from the history of how they were written.

Takeaways