[DOCS] Nested-subagent docs still describe a fixed depth and omit the default-disabled behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

The Spawn nested subagents section, especially the description of the depth limit and when a subagent receives the Agent tool.

Current Documentation

The page currently says:

As of Claude Code v2.1.172, a subagent can spawn its own subagents.

It then states:

A subagent at depth five doesn't receive the Agent tool and can't spawn further. The limit is fixed and not configurable.

What's Wrong or Missing?

Claude Code v2.1.217 changes nested-subagent behavior: subagents no longer spawn nested subagents by default, and CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH can be set to allow deeper nesting.

The current page presents nested spawning as generally available and explicitly says the depth limit is fixed and not configurable. Both statements are now incomplete or incorrect for the default configuration and leave users without the name or semantics of the control that enables deeper nesting.

Suggested Improvement

Update the nested-subagent section to:

• State that nested subagent spawning is disabled by default as of Claude Code v2.1.217.
• Document the default maximum spawn depth and how depth is counted.
• Document CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, including accepted values, scope, and the exact depth at which the Agent tool becomes unavailable.
• Explain how the variable interacts with Agent in tools/disallowedTools, background subagents, forks, and resumed subagents.
• Replace “The limit is fixed and not configurable” with the current configurable-depth behavior, while retaining any separate fork limitation that still applies.

Add the variable to the environment-variable reference with a minimum-version marker for Claude Code v2.1.217.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 835-849 | Nested-spawn availability, depth semantics, and the current “fixed” limit statement |
| https://code.claude.com/docs/en/env-vars | 258-263 | Subagent-related variable reference; no CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH row |

Total scope: 2 pages should describe the changed nested-spawn default and its configuration variable.

The relevant release is Claude Code v2.1.217. The release entry is listed in the Claude Code changelog under version 2.1.217.