claude-code - 💡(How to fix) Fix [DOCS] `CLAUDE_CODE_SUBAGENT_MODEL` docs do not explain agent-teams teammate behavior

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.