Claude Code Now Allows 3‑Layer Sub‑Agents—Why Anthropic Still Warns Against Multi‑Agent Programming

1. Version history: from 5 layers to 1, now back to 3

Official changelog shows default nesting depth changed three times: versions v2.1.172‑216 defaulted to 5 layers (non‑configurable), v2.1.217‑218 reduced to 1 layer (effectively disabled), and from v2.1.219 the default is 3 layers.

When the default is 1, sub‑agents are leaf nodes and cannot spawn further agents unless the user manually changes the configuration. With the new default of 3, a sub‑agent can automatically delegate tasks without any extra settings.

2. What happens at the depth limit

Reaching the maximum depth does not raise an error; the Agent tool is removed from the sub‑agent, forcing it to finish the work itself and return a summary. The only exception is a fork operation, which retains the Agent tool but still fails on actual invocation.

This design avoids a hard failure; the sub‑agent simply proceeds without the tool.

3. Nesting solves context isolation, not speed

The core value of a sub‑agent is an independent context window. Anthropic describes the pattern: when a side task would flood the main conversation with search results, logs, or file contents, a sub‑agent handles the work in its own window and returns only the conclusion.

Official example: a review sub‑agent creates a verification sub‑agent for each identified issue. All intermediate outputs stay in the lower layer; the main conversation receives only the review summary.

Without nesting, the main thread would need to retain all details, halving the isolation benefit.

4. Cost: Anthropic’s token‑burn numbers

Anthropic’s engineering blog “How we built our multi‑agent research system” reports that a normal dialogue costs 1× token, a single agent about 4×, and a multi‑agent system about 15×.

In the BrowseComp benchmark, token usage alone explains 80 % of performance variance; adding tool‑call count and model choice raises the explained variance to 95 %.

Thus the performance gain of multi‑agent setups largely stems from higher token consumption, which Anthropic calls “burn through tokens fast”. This is justified only for high‑value tasks that can afford the premium.

5. Official stance: most programming work is unsuitable

Anthropic lists scenarios where multi‑agent approaches are not recommended: tasks requiring a shared context across agents, strongly inter‑dependent agent tasks, most programming work (because parallelizable portions are few), and real‑time coordinated delegation.

Recommended use cases are high‑value, highly parallel, information‑heavy tasks that exceed a single context window and need many complex tools.

6. Three independent limits beyond depth

There are three concurrent limits: default nesting depth = 3, maximum total sub‑agents per session = 200, and maximum concurrently running sub‑agents = 20, each configurable via environment variables.

When the concurrent limit is hit, the system returns “Concurrent subagent limit reached” and advises the model not to retry until the count drops.

Disabling nesting sets the depth to 1 in settings.json:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"
  }
}

Setting the value to 2 allows one additional layer, but that layer cannot spawn further agents.

The 200‑agent total limit counts sub‑agents, forks, background agents, and workflow‑spawned agents, but excludes independent forked sessions and workflow‑script‑spawned agents. Completed sub‑agents still occupy slots until the session ends; the /clear command can reset the count, though lingering agents may carry over.

To prevent a specific sub‑agent from ever delegating, remove the Agent tool from its tools list or add it to disallowedTools.

7. Practical guidance

Use nesting when a task naturally splits into “decompose + parallel verification”, such as a review that generates issues and then validates each one. The more intermediate artifacts stay in lower layers, the greater the benefit.

Avoid nesting when multiple agents need to share the same context, because each layer summarises information, contradicting the sharing requirement.

Cost‑saving tip: specify a cheaper model (e.g., Haiku) in the sub‑agent’s model field for mechanical work, as recommended by the documentation.

The UI shows a sub‑agent tree with a (+N) count for each node; after v2.1.193 you can expand a node to see siblings, children, and the path back to the main thread, which is more useful than post‑run logs.

Conclusion

The single‑line changelog masks two common misconceptions: treating nesting as a new capability (it is a rollback) and treating it as a speed‑up (the token‑burn cost dominates). The appropriate depth remains an empirical parameter, and the benefit is cleaner context rather than faster execution.