Claude Code Now Caps Subagent Spawns and Web Searches at 200 Per Session

Claude Code v2.1.212, shipped July 17, 2026, closed a governance gap that let sessions spawn unlimited subagents and fire unlimited web searches. The release added two hard, session-scoped ceilings — both default to 200 — and a third guardrail that automatically backgrounds MCP tool calls that run longer than two minutes. For anyone running Claude Code at scale through background agents, CI pipelines, or multi-agent workflows, these three knobs are now the minimum configuration before your next big run.

Three failure modes, three guardrails

A runaway agent session is not one problem. It is three distinct failure modes, and Claude Code now has a separate mechanism for each:

A fourth failure mode — a slow MCP tool call blocking the entire session — is handled by the auto-background threshold: MCP calls running longer than two minutes now move to the background automatically. Tune or disable with CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS (default 120000, set to 0 to disable).

None of these four is a spend limit. Spend is governed separately by which model each subagent runs. Conflating the spawn cap with a dollar budget is the most common mistake teams make with these new controls.

The subagent spawn cap in detail

Claude can spawn at most 200 subagents per session by default. When the session hits the ceiling, the Agent tool fails with Subagent spawn limit reached, and the error instructs Claude to complete the remaining work directly with its own tools rather than delegating.

What counts toward the 200 is broader than most operators expect:

• Nested subagents — any subagent spawned by another subagent with the Agent tool.
• Background subagents — agents running in the background count the same as foreground ones.
• Forks started with /subtask — the in-session fork command (renamed from /fork in v2.1.212) spends the same budget.
• Workflow-spawned subagents — subagents that a workflow’s agents spawn via the Agent tool count.
• Finished subagents — the budget is a session lifetime total, not a live concurrency gauge. A subagent that completed ten minutes ago still costs one toward the 200.

What does not count:

• A separate background session you create with /fork — it runs as its own independent session with its own budget.
• Agents a workflow script spawns with agent() — workflows enforce their own per-run limit.

The critical asymmetry: the cap counts subagents by number, not by cost. Two hundred subagents routed to Haiku can cost far less than five routed to Opus. The cap stops a runaway loop; it does not cap your bill.

When Claude hits the limit in a headless or SDK session, the behavior is deterministic: the Agent tool call fails, Claude reads the error, and it finishes the remaining work with its own tools. No silent retry. No growing bill. This is the behavior you want from a guardrail.

Resetting the budget between tasks

Running /clear resets the subagent spawn count and starts a fresh conversation with the full budget. If you run multiple distinct tasks in a single long session — say a morning refactor followed by an afternoon feature — /clear between them prevents the first task’s spawns from eating into the second task’s budget.

The one caveat: if work that can still spawn subagents survives the clear (a running workflow, for example), the count carries over instead of resetting. Clear the workflow first, then /clear.

The depth limit: five, fixed, non-negotiable

Separate from the spawn cap is the depth limit: how many subagent levels can sit below your main conversation. It is fixed at five and not configurable. A subagent at depth five simply does not receive the Agent tool, so it cannot spawn a sixth level.

This is a design decision, not a missing feature. If a task genuinely requires more than five levels of delegation, the signal is to flatten your agent graph, not to raise the ceiling. Deeply nested agent chains are harder to debug, harder to observe, and almost always a sign that the top-level task was underspecified.

The WebSearch cap: stopping the doom-scroll

CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION is a session-wide limit on WebSearch tool calls, default 200. It was added specifically to stop an agent that keeps searching without converging on an answer — the doom-scroll pattern where Claude searches, reads, searches again, reads again, and never commits to a conclusion.

For most work the default is generous. If you hit 200 searches in a single session, the honest read is usually that the task is underspecified, not that the cap is too low. Tighten the task scope before raising the ceiling.

To raise it for a legitimately research-heavy session:

export CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=400

MCP auto-background: the session stays responsive

Before v2.1.212, a slow MCP tool call — a database query, a document processor, a long-running orchestration call — would block the entire interactive session. The terminal looked busy, but nothing was happening.

Now, MCP tool calls running longer than two minutes automatically move to the background. The session stays usable while the slow call continues in the background. Configure the threshold:

# Tighten the threshold to one minute:
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=60000

# Or disable entirely for deterministic debugging:
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0

For operators running Claude Code through a gateway or in CI pipelines, the auto-background behavior changes the failure mode from “session hangs” to “session continues.” If you depend on deterministic blocking behavior for workflow orchestration, test this before upgrading.

What to configure before your next run

Three settings, each serving a distinct purpose:

# 1. Spend control: route fan-out subagents to a cheaper model
# In your subagent YAML frontmatter:
#   model: haiku

# 2. Loop backstop: leave caps at 200 unless a specific job needs headroom
export CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200
export CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200

# 3. Reset between tasks
# Run /clear in Claude Code between distinct jobs

The depth limit (five) takes care of itself. The MCP auto-background (two minutes) works well at the default for most teams.

The /fork and /subtask rename

One more change that trips teams up: /fork no longer spawns an in-session subagent. It now copies your conversation into a new background session — its own row in claude agents — while you keep working in the original session. The old in-session behavior moved to a new command, /subtask.

This matters for automation: if you have shell scripts, CI pipelines, or playbooks that trigger /fork expecting a contained in-session helper, those workflows now create a separate background session instead. Audit and migrate to /subtask for the in-session pattern.

Who should update

Any team running Claude Code with background agents, multi-agent workflows, or CI/CD pipelines should update to v2.1.212 or later. The plan-mode permission bypass fix alone (covered in our separate Beware article) is reason enough, but the session caps and /fork redesign are the changes that reshape day-to-day operations.

Update with:

npm i -g @anthropic-ai/claude-code

Or let the auto-updater pick it up on next launch.

The governance gap is closed. The three guardrails are in place. Configure the two tunable caps to match your workload, route fan-out subagents to a cheaper model for spend control, and /clear between distinct tasks. The default of 200 for each cap is generous enough not to interrupt normal work and tight enough to prevent exponential delegation loops from running up a bill you did not authorize.