[DOCS] Behaviour of subagent model selection and effect of CLAUDE_CODE_SUBAGENT_MODEL unclear

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Subagents, Model selection

Current Documentation

The documentation mentions:

---

Configuration fields

| Field | Required | Description |
| :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | Yes | Unique identifier using lowercase letters and hyphens |
| description | Yes | Natural language description of the subagent's purpose |
| tools | No | Comma-separated list of specific tools. If omitted, inherits all tools from the main thread |
| model | No | Model to use for this subagent. Can be a model alias (sonnet, opus, haiku) or 'inherit' to use the main conversation's model. If omitted, defaults to the [configured subagent model](/en/docs/claude-code/model-config) |

Model selection

The model field allows you to control which [AI model](/en/docs/claude-code/model-config) the subagent uses:

• Model alias: Use one of the available aliases: sonnet, opus, or haiku
• 'inherit': Use the same model as the main conversation (useful for consistency)
• Omitted: If not specified, uses the default model configured for subagents (sonnet)

<Note>
Using 'inherit' is particularly useful when you want your subagents to adapt to the model choice of the main conversation, ensuring consistent capabilities and response style throughout your session.
</Note>

---

Also, on https://docs.claude.com/en/docs/claude-code/model-config#environment-variables:

Environment variables

You can use the following environment variables, which must be full model
names, to control the model names that the aliases map to.

| Env var | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| ANTHROPIC_DEFAULT_OPUS_MODEL | The model to use for opus, or for opusplan when Plan Mode is active. |
| ANTHROPIC_DEFAULT_SONNET_MODEL | The model to use for sonnet, or for opusplan when Plan Mode is not active. |
| ANTHROPIC_DEFAULT_HAIKU_MODEL | The model to use for haiku, or [background functionality](/en/docs/claude-code/costs#background-token-usage) |
| CLAUDE_CODE_SUBAGENT_MODEL | The model to use for [subagents](/en/docs/claude-code/sub-agents)

What's Wrong or Missing?

Values of CLAUDE_CODE_SUBAGENT_MODEL

There are a few issues I noticed. First, from the documentation of CLAUDE_CODE_SUBAGENT_MODEL, I got the impression that I can specify essentially the same values as in a subagents model field (in essence, a full model name OR a model alias). However, only full model names (e.g. claude-sonnet-4-5) seem to work. I think it would be valuable to mention that in the docs (OR allow the CLAUDE_CODE_SUBAGENT_MODEL to specify model aliases)

Behaviour of CLAUDE_CODE_SUBAGENT_MODEL and subagent's model: field

Further, I think it's a bit unclear how CLAUDE_CODE_SUBAGENT_MODEL and the subagent's model: field interact.

Based on

* Omitted: If not specified, uses the default model configured for subagents (sonnet)

I was somehow expecting that "<code>the default model configured for subagents</code>" meant CLAUDE_CODE_SUBAGENT_MODEL or (if not set) fall back to 'sonnet'

However, CLAUDE_CODE_SUBAGENT_MODEL will ALWAYS overwrite all agent's model, so if CLAUDE_CODE_SUBAGENT_MODEL is set, any agent will be called with the model specified by CLAUDE_CODE_SUBAGENT_MODEL

I think this is not very clear from the docs as they are currently, as I expected the following behaviour:

| | CLAUDE_CODE_SUBAGENT_MODEL unset | CLAUDE_CODE_SUBAGENT_MODEL set |
|---|---|---|
| Agent with model: set | uses model field | uses model field |
| Agent without model: set | uses default (sonnet) | uses CLAUDE_CODE_SUBAGENT_MODEL |

Suggested Improvement

I think the documentation should specify:

a) what acceptable values for are CLAUDE_CODE_SUBAGENT_MODEL
b) How an agent's model field (or absence thereof) interacts with CLAUDE_CODE_SUBAGENT_MODEL

Impact

Medium - Makes feature difficult to understand

Additional Context

_No response_