[DOCS] Subagent documentation omits the concurrent-running subagent cap

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

Concurrency limits for background and foreground subagents

Current Documentation

The current subagent limits section says:

By default, Claude can spawn at most 200 subagents per session. To raise the limit, set CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION to any positive whole number; there is no upper bound, but the limit can't be turned off.

The environment-variable reference documents CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION and separately lists CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, but it does not list CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.

What's Wrong or Missing?

Claude Code 2.1.217 adds a cap on concurrently running subagents, with a default of 20 and an override named CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. The current documentation describes only the cumulative per-session spawn limit of 200. It does not explain that a session can have more total subagent spawns over time while only a bounded number run at once, nor how the new cap interacts with background agents, workflows, or CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY.

Without this distinction, users cannot predict why a fan-out request pauses or denies new background work even when the session has not reached its 200-subagent lifetime limit.

Suggested Improvement

Add a “Concurrent subagent limit” subsection to the subagents page and add CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to the environment-variable reference. Document the default of 20, the accepted override format and whether the value can be disabled, what happens when the cap is reached, and how it differs from the per-session spawn limit and the general tool-use concurrency setting. Include a short example for organizations that need to reduce fan-out.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 851-861 | Documents the 200-per-session limit but not the 20-concurrent limit |
| https://code.claude.com/docs/en/env-vars | Environment variables reference | CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS is absent; nearby concurrency variables can be confused with it |
| https://code.claude.com/docs/en/agent-view | Background agents and session fan-out | Needs a cross-reference explaining how concurrent work is capped |

Version: Claude Code 2.1.217.

Total scope: 3 pages should distinguish the new concurrency cap from existing subagent limits.