Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/model-config
Section/Topic
CLAUDE_CODE_SUBAGENT_MODEL in the Model configuration environment-variables table, with a cross-reference from the agent-teams model-selection section
Current Documentation
The docs currently say:
CLAUDE_CODE_SUBAGENT_MODEL | The model to use for all subagents. Overrides both the per-invocation model parameter and the subagent definition's model frontmatter
The agent-teams guide also says:
Teammates don't inherit the lead's /model selection by default. To change the model used when the prompt doesn't specify one, set Default teammate model in /config. Pick Default (leader's model) to have teammates follow the lead's current model.
And later:
The teammate honors that definition's tools allowlist and model, and the definition's body is appended to the teammate's system prompt as additional instructions rather than replacing it.
What's Wrong or Missing?
Claude Code v2.1.147 fixed CLAUDE_CODE_SUBAGENT_MODEL not applying to teammate processes spawned by agent teams, but the docs still describe that variable only in subagent terms.
Because agent teams are documented separately from subagents, the current docs do not tell readers that this environment variable also affects teammate processes created by agent teams, or how that behavior relates to teammate model selection via /config, spawn-prompt model instructions, or a referenced subagent definition's model.
Suggested Improvement
Add one explicit note to the CLAUDE_CODE_SUBAGENT_MODEL row in the model-config page stating that, as of v2.1.147, the variable is also propagated to teammate processes spawned by agent teams.
Add a matching note in the agent-teams "Specify teammates and models" section clarifying whether this environment variable overrides or interacts with:
teammateDefaultModel- explicit teammate model instructions in the spawn prompt
- a referenced subagent definition's
model
A short precedence note or table would make multi-agent model configuration much easier to reason about.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Total scope: 4 pages affected
Version context: changelog entry in v2.1.147 says: Fixed CLAUDE_CODE_SUBAGENT_MODEL not applying to teammate processes spawned by agent teams.
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/model-config
Section/Topic
CLAUDE_CODE_SUBAGENT_MODELin the Model configuration environment-variables table, with a cross-reference from the agent-teams model-selection sectionCurrent Documentation
The docs currently say:
The agent-teams guide also says:
And later:
What's Wrong or Missing?
Claude Code v2.1.147 fixed
CLAUDE_CODE_SUBAGENT_MODELnot applying to teammate processes spawned by agent teams, but the docs still describe that variable only in subagent terms.Because agent teams are documented separately from subagents, the current docs do not tell readers that this environment variable also affects teammate processes created by agent teams, or how that behavior relates to teammate model selection via
/config, spawn-prompt model instructions, or a referenced subagent definition'smodel.Suggested Improvement
Add one explicit note to the
CLAUDE_CODE_SUBAGENT_MODELrow in the model-config page stating that, as of v2.1.147, the variable is also propagated to teammate processes spawned by agent teams.Add a matching note in the agent-teams "Specify teammates and models" section clarifying whether this environment variable overrides or interacts with:
teammateDefaultModelmodelA short precedence note or table would make multi-agent model configuration much easier to reason about.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
CLAUDE_CODE_SUBAGENT_MODELis documented only as a subagent overridemodelCLAUDE_CODE_SUBAGENT_MODELwithout linking that behavior to agent teamsTotal scope: 4 pages affected
Version context: changelog entry in v2.1.147 says:
Fixed CLAUDE_CODE_SUBAGENT_MODEL not applying to teammate processes spawned by agent teams.