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

[kije]

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

Model selection

The model field allows you to control which AI model 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)

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.

---

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
CLAUDE_CODE_SUBAGENT_MODEL	The model to use for subagents

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 "the default model configured for subagents" 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

[github-actions]

Found 3 possible duplicate issues:

1. [DOCS] Unclear default model behavior for Claude Code on Amazon Bedrock when ANTHROPIC_MODEL is not set #8369
2. [Bug] CLAUDE_CODE_SUBAGENT_MODEL env variable causes plugin agent return 404 errors #9573
3. [BUG] general-purpose agent sets model as 'sonnet' rather than 'inherit' #8932

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[kije]

👎

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[github-actions]

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.