Cap subagent nesting before it caps your quota

You fire off one prompt — "research how these three APIs handle pagination" — walk away, and come back to a finished answer and a quota bar that moved far more than the work justified. No error, no warning, no obvious culprit. The usual suspect is a subagent tree you never saw: your subagent delegated to subagents of its own, and those delegated again.

The mechanism is real and documented

A subagent's tool pool can include Agent. So delegation is recursive by default. Claude Code caps it by depth, not by total count:

• The default is three layers below your main conversation.
• At the limit, Claude Code withholds Agent from every subagent except a fork, and a fork at the limit keeps the tool but gets an error instead of a new subagent — so the deepest layer does its own work and returns one summary either way.
• There is no cap on the total number of subagents a session may spawn — only a concurrency cap and a depth cap. That is a change rather than a constant, and it moved in the permissive direction: CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION was "removed in v2.1.224 and now a no-op", and before that it "capped the total number of subagents Claude could spawn with the Agent tool in one session (default: 200)", with a session that hit the ceiling failing with Subagent spawn limit reached. Nothing counts your session total any more.

Three layers with a modest branching factor is not three agents. It is three agents, then nine, then twenty-seven — each with its own fresh context window, each re-reading the same files, and none of them aware that a sibling already answered the question.

The four levers

To turn nesting off entirely:

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

Both variables accept a positive whole number in plain digits. Anything else is ignored and the default applies — so you can tighten or loosen the limit, but you cannot remove it, and a typo fails silently back to the default rather than erroring.

The per-agent lever is the surgical one. If a reviewer subagent should stay read-only, omit Agent from its tools list or add it to disallowedTools. That leaves nesting on for everything else instead of flattening the whole session.

What is actually unverified here

The mechanism above is straight from the docs. The reason to act on it is not.

The community reports behind this tip — one prompt fanning out to 48 simultaneous agents, four of them separately researching the same API after the first had already finished; roughly 1.5M tokens on a single research request; about 4M in five minutes — are anecdotes from issue threads and forum posts. Nobody has published a controlled measurement. Treat the numbers as directionally suggestive, not as a benchmark.

One of them is in visible tension with current behavior: since v2.1.217 the default concurrent-subagent cap is 20, and spawning past it fails with Concurrent subagent limit reached. A session showing 48 at once is therefore either on an older build, running with the cap raised, using ultracode (which is exempt from the concurrency limit), or counting resumed subagents, which take a fresh slot without checking the cap. That does not make the report false. It does mean the number cannot be read as "what your v2.1.2xx install will do tonight."

The deeper gap: nobody has isolated depth as the cause of the burn. A single flat layer of twelve subagents, each reading the same twenty files, burns just as badly and is not touched by the depth setting at all. Duplicated work across siblings is the cost driver; nesting is one way to get there, not the only one.

The recommendation to set depth to 1 as your default is a preference, not a documented one. The docs describe the setting and its trade-off; they do not name a default that is common cause of runaway token spend, and they do not suggest 1.

What would settle it

Run the same delegating prompt twice on the same repo, once with depth 1 and once with the default, and read the Session block in /usage after each:

claude --version
grep -h MAX_SUBAGENT_SPAWN_DEPTH ~/.claude/settings.json .claude/settings.json 2>/dev/null \
  || echo "unset - default applies (3 on v2.1.219+)"

Then compare token counts. Be honest about the limits of that experiment: agent runs are not deterministic, so a single pair of runs tells you very little. Three or four pairs, with the same prompt and a clean session each time, would be worth reporting.

When not to do this

Nesting exists for a reason: a delegated task that itself splits into parallel subtasks — a reviewer that dispatches one verifier per finding — keeps all the intermediate chatter out of your main context. Only the top-level summary comes back. Set depth to 1 and that pattern collapses: either you lose the fan-out, or the verification work lands in your own context window, which is the thing you delegated to avoid.

If your real problem is siblings duplicating each other's reads, the concurrency cap and tighter task descriptions will do more than the depth cap will.