Claude Code subagents are a context tool, not a speed tool

        main conversation
   ┌───────────────────────────┐
   │  "why did the build       │
   │   start failing?"         │
   └─────────────┬─────────────┘
                 │  delegation prompt
                 ▼
   ╔═══════════════════════════╗
   ║   subagent context        ║
   ║                           ║
   ║   file reads              ║
   ║   greps                   ║
   ║   full test output        ║
   ║   abandoned hypotheses    ║
   ║   build logs              ║
   ╚═════════════╤═════════════╝
                 │  final summary only
                 ▼
   ┌───────────────────────────┐
   │  "postbuild script exits  │
   │   non-zero when git has   │
   │   no parent commit"       │
   └───────────────────────────┘
 everything in the middle
 box is discarded on purpose</pre></div>
Read that diagram as a pipeline and you will conclude the middle box is where the work happens, so more middle boxes means more work. Read it as a valve and you conclude something different: the middle box is where the tokens go to die, and its width is the reason to use one at all.
Reaching for them to go faster is the common misread
The advice that circulates is mostly about count. Spawn a team of specialists, give each one a role, run them at once.
Claude Code will let you do this. The concurrent ceiling is high enough that most people never see it: spawning another subagent fails once 20 are already running, configurable through CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. That ceiling is not a target.
The write-up Google currently surfaces on the first page for this term makes the point against itself. @PrajwalTomar_ describes a setup where three agents outship twenty, and the diagnosis is that everyone “unleashing 20 subagents” gets “a swarm that drifts, duplicates work, and burns an Opus bill for nothing.” His fix is structure: one orchestrator owning the plan, every agent scoped to one job rather than “improve the codebase,” cheap models doing the volume.
None of those fixes are about parallelism. They all narrow what each agent is allowed to consider. That is the same variable the valve is controlling.
The bearish case is more precise than it sounds
There is a real backlash, and it is worth taking at full strength rather than in caricature.
@callebtc listed what he has never used for coding: MCPs, subagents, agent coordinators, memory systems, loops or graphs. His framing is that agentic coding “is becoming like photography: people obsess over the latest gear, optimize every inch of their workflow, and still never produce a beautiful photo worth looking at.” He calls it productivity larping. @avrldotdev put a number on the same instinct, arguing that for more than 95% of developers this is “all just a waste of tokens & no extra benefits.”
The sharpest version comes from @KingBootoshi, because it concedes something specific:

i am bearish on subagents
i am bullish on specialized agents that maintain state with their own memory working with each other
ephemeral agents are a waste of tokens (besides maybe, researching or scoping)

The parenthetical is the whole argument. Researching and scoping are exactly the tasks where a large amount of reading collapses into a short answer. He is not really bearish on subagents. He is bearish on using them where the ratio runs the wrong way, and he named the two cases where it runs the right way.
That ratio is the test. Ask what the work will read and what it will return. Work that reads a hundred files and returns a paragraph belongs behind the valve. Work that reads a paragraph and returns a hundred files does not, and neither does work where you will want to argue with the intermediate steps, because those steps are precisely what the subagent is built to withhold.
The configuration surface is a containment interface
The frontmatter fields of a subagent definition divide cleanly by what they do to the agent, and the division is lopsided.



Field
What it does
Direction




tools
Allowlist of tools the subagent may call
Restricts


disallowedTools
Denylist removed from the inherited pool
Restricts


permissionMode
How much it may do without asking
Restricts


maxTurns
Agentic turns before it stops
Restricts


isolation: worktree
Runs in a temporary git worktree
Restricts


model
Which model runs it
Routes


effort
Reasoning effort for this agent
Routes


background
Keeps it out of the foreground
Routes


skills
Preloads named skills into context
Adds


mcpServers
MCP servers available to it
Adds


memory
Persistent scope for cross-session learning
Adds



Most of the surface is about what the thing may not do. You can hand a subagent a tools allowlist of Read, Grep, Glob and a permissionMode and be confident it cannot write to your repository, which is a different kind of guarantee than asking a general agent nicely.
This is why the security-flavored uses land so well. A reviewer that structurally cannot edit the code it is reviewing is a better reviewer, for the same reason a rival lab’s model makes a better reviewer than the model that wrote the change. Independence is a property you build with restrictions, not with instructions.
The nesting cap moved down, not up
Nested subagents shipped in June. Boris Cherny announced it as an experiment in context management:

Just landed nested subagent support in Claude Code
Starting to experiment more with agents kicking off agents as a way to better manage context. Capped at depth=5 to start, going out in today’s release.

Note the stated purpose even at launch. Agents kicking off agents was framed as a way to better manage context, not to run more work at once.
The current documentation caps nesting at 3 layers below the main conversation by default, tunable through CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, with 1 disabling nesting entirely. The default came down from the launch value.
Defaults that move down are worth reading as findings. Somebody watched what depth 5 produced.
Forks are the opposite trade
Forks are the exception, and the contrast clarifies the rest. A fork inherits the entire conversation history, system prompt, tools, and model from its parent. It is the only subagent that sees prior context, and it skips the tool filters the others get.
The family therefore has two ends. An ordinary subagent buys isolation and pays for it in briefing: it knows nothing, so the delegation prompt has to carry everything, and a vague prompt produces a confidently irrelevant answer. A fork buys zero briefing cost and pays for it by carrying everything the parent was already holding, which is the cost you were trying to avoid.
The documented rule is to fork when any other subagent would need too much background context to be worth explaining. That is a judgment about the size of the briefing, not about the difficulty of the task.
Background and foreground are two different products
This last distinction changes what you get back and when, which is why it catches people building orchestration.
Background subagents are the default in interactive sessions. They run concurrently with the main conversation, they lose most built-in tools and keep a reduced set, and their results arrive as a completion notification in a later turn. Foreground subagents block the main conversation until they finish, keep the full inherited tool set, and hand back results before Claude continues.
If you are building a flow that waits on a result, this matters more than it looks. The agent teams documentation warns about the failure directly: while agent teams are enabled, a subagent that Claude names launches as a teammate instead, and a teammate’s idle notification reports that it stopped without carrying its output. An orchestration flow that waits on subagent results can stall on that difference. The fix is CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to 0, which is a strange thing to need to know, and exactly the kind of seam that shows up once you treat these as components rather than as magic.
A subagent is a station
The pipelines everyone is calling software factories are built out of exactly this primitive. Vercel’s Foreman splits the loop into stations, each an agent in its own sandbox, with the reviewer running a different model from the writer. The value of that arrangement sits in what it refuses to pass along.
A subagent is the smallest version of the same idea. It is a station with a sandbox, a tool allowlist, a model of its own, and a narrow output. Chaining more of them does not make a factory, and running twenty at once makes something worse than one.
The question to ask before spawning one is not whether the task could run in parallel. It is what you want to never see. If the honest answer is nothing, stay in the main conversation and save the briefing.