Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/env-vars
Section/Topic
The “Variables” reference, for session-level subagent and delegation controls.
Current Documentation
The page currently presents itself as a reference for environment variables controlling Claude Code behavior and documents other background-task and subagent settings, but it has no entry for CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION.
What's Wrong or Missing?
Claude Code 2.1.212 adds a per-session cap of 200 subagent spawns, configurable with CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION. The release behavior also says that /clear resets the budget. None of the variable name, default, scope, reset behavior, or exhaustion behavior is documented in the environment-variable reference or the subagent guide.
Users building delegation-heavy workflows cannot tell whether a spawn failure is caused by their configuration, a session budget, or the ordinary subagent depth and concurrency limits.
Suggested Improvement
Add a row for CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION describing its default of 200, the fact that it counts spawns across a session, how to override it, and that /clear resets the budget. Add a short link from the subagent limits section to the new environment-variable row and document the message or behavior users see when the cap is reached.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Total scope: 2 pages should explain the shared session budget without conflating it with depth or concurrency limits.
The cap was added in Claude Code 2.1.212; the release notes are listed at https://code.claude.com/docs/en/changelog.
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/env-vars
Section/Topic
The “Variables” reference, for session-level subagent and delegation controls.
Current Documentation
The page currently presents itself as a reference for environment variables controlling Claude Code behavior and documents other background-task and subagent settings, but it has no entry for
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION.What's Wrong or Missing?
Claude Code 2.1.212 adds a per-session cap of 200 subagent spawns, configurable with
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION. The release behavior also says that/clearresets the budget. None of the variable name, default, scope, reset behavior, or exhaustion behavior is documented in the environment-variable reference or the subagent guide.Users building delegation-heavy workflows cannot tell whether a spawn failure is caused by their configuration, a session budget, or the ordinary subagent depth and concurrency limits.
Suggested Improvement
Add a row for
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONdescribing its default of200, the fact that it counts spawns across a session, how to override it, and that/clearresets the budget. Add a short link from the subagent limits section to the new environment-variable row and document the message or behavior users see when the cap is reached.Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Total scope: 2 pages should explain the shared session budget without conflating it with depth or concurrency limits.
The cap was added in Claude Code 2.1.212; the release notes are listed at https://code.claude.com/docs/en/changelog.