A coding agent that can delegate and search indefinitely is not more autonomous. It is an unbounded production workload waiting for an ambiguous task, a flaky tool, or a bad retry loop.
Claude Code 2.1.212 adds two simple controls that deserve more attention than a standard release-note skim: a per-session cap on subagent spawns and a per-session cap on web searches. Both default to 200 and can be configured with environment variables. The same release also moves MCP calls that run longer than two minutes into the background by default, so one slow integration no longer freezes the interactive session. Anthropic's release notes are explicit about those defaults and controls.
That is a practical reliability pattern for every agent harness: make expensive fan-out and external I/O finite, observable, and recoverable.
The failure mode is not just cost
A long task can cause an agent to keep opening research branches, retrying a weak query, or delegating variants of the same work. The obvious impact is token and tool spend. Less obvious impacts are:
- the parent session has more partial results to reconcile
- duplicate subagents create conflicting edits or conclusions
- a slow MCP service turns an interactive workflow into a blocked workflow
- a "still working" indicator hides that the system has stopped making useful progress
This is especially relevant with agent teams. Anthropic documents that agent teams use significantly more tokens than a single session, and recommends them only where independent parallel work adds real value. They are experimental and have coordination limitations. Read the agent-team guidance before treating parallelism as a default.
Translate the new controls into an operating policy
Claude Code exposes the two limits as environment variables:
# Example starting budgets, not universal defaults
export CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=12
export CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=30
# Keep a slow integration from blocking the foreground forever.
# Omit or adjust only after measuring normal MCP latency.
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000
The release notes say /clear resets the subagent budget. Treat that as a new work segment, not a loophole to bypass a runaway-session guardrail.
The right values depend on workload. A bounded PR review may need 3 to 8 specialists and no web search. A research task may need more search calls but only one or two synthesis workers. Start low enough that hitting the cap is a useful signal, then increase it only when traces show the extra work improves the outcome.
| Workload | Start with | Stop or escalate when |
|---|---|---|
| Local bug fix | 0-2 subagents, 0-5 searches | the worker needs information outside the repo |
| PR review | 3-5 focused reviewers, 0-10 searches | findings overlap or reviewers touch the same files |
| Incident investigation | 2-4 parallel hypotheses, 10-25 searches | evidence stops changing the leading hypothesis |
| Broad architecture research | 1 synthesizer, 2-4 researchers, 20-40 searches | sources become repetitive or stale |
These are operational starting points, not product limits. Measure completion quality, elapsed time, tool calls, and cost per accepted change.
Keep foreground work responsive
Claude Code now backgrounds MCP tool calls after two minutes by default, and lets you tune or disable that behavior with CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS. This is a good UX safeguard, but it is not an SLO. A slow MCP call still consumes capacity and can return stale data.
Use a separate timeout policy for the integration itself:
- Decide which MCP operations may run asynchronously, such as indexing or a large issue search.
- Keep write actions and approval-dependent operations in the foreground with an explicit user-visible state.
- Record the request, start time, result, failure reason, and retry count.
- Let the lead continue with independent work, then require it to re-check assumptions when the background result arrives.
MCP servers can expose issue trackers, databases, and APIs directly to the agent, so their latency and trust boundaries are part of your application architecture, not merely a plugin detail. Claude Code's MCP documentation also warns that servers which fetch external content can create prompt-injection risk.
A minimal budget contract
Put the policy beside the task, rather than asking the model to "be efficient":
agent_budget:
max_subagents: 4
max_web_searches: 20
mcp_foreground_timeout_seconds: 120
require_unique_role_per_subagent: true
stop_conditions:
- evidence_is_repetitive
- two_consecutive_tool_failures
- budget_exhausted
on_stop: summarize_open_questions_and_escalate
The important field is not the exact number. It is the stop behavior. A bounded system should return a useful partial result with open questions, not quietly start another round of expensive exploration.
What to do now
- Upgrade a non-critical Claude Code environment to 2.1.212 and inspect the release behavior first.
- Set conservative session budgets for one workflow with measurable outcomes, such as PR review or incident triage.
- Add telemetry for subagent count, search count, MCP latency, retries, and accepted-result rate.
- Review any run that hits a cap: did the cap prevent waste, or did it block a clearly valuable step?
- Keep permission controls separate from budget controls. A request can be safe yet uneconomical, and cheap yet unsafe.
If you are already running coordinated workers, pair this with an explicit task contract and an evaluation loop. These earlier guides cover when shared-context agent teams beat more subagents, turning bad runs into regression tests, and why approval prompts need defense in depth.
Limits and when this does not apply
Do not use hard caps as a substitute for task design. A large migration or deep investigation may legitimately need more work, but it should be split into resumable phases with a fresh budget and a human checkpoint. Also, backgrounding a slow MCP call improves interactivity; it does not make the remote system reliable or its output trustworthy.
Sources
- Claude Code v2.1.212 release notes
- Claude Code agent teams documentation
- Claude Code MCP documentation
What budget has actually caught the most waste in your agent workflow: delegations, searches, retries, or slow tool calls?
Top comments (0)