[DOCS] Subagent docs still restrict `model` to aliases instead of full model IDs
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/sub-agents
Section/Topic
Subagent model: frontmatter and --agents JSON model value rules.
Current Documentation
The subagent frontmatter table currently says:
|model| No | Model to use:sonnet,opus,haiku, orinherit. Defaults toinherit|
The "Choose a model" subsection also says:
* Model alias: Use one of the available aliases:sonnet,opus, orhaiku
The CLI reference says the --agents JSON field is alias-only:
|model| No | Model alias to use:sonnet,opus,haiku, orinherit. If omitted, defaults toinherit|
But the model configuration page already says:
To pin to a specific version, use the full model name (for example, claude-opus-4-6)
What's Wrong or Missing?
Release v2.1.74 says agent frontmatter model: and --agents JSON now accept the same model values as --model, including full model IDs such as claude-opus-4-5.
Current subagent docs explicitly restrict those fields to aliases and inherit, which is now outdated and contradicts the main model configuration page.
Suggested Improvement
Update subagent and CLI docs to say that agent model accepts the same values as --model, including:
- Standard aliases such as
sonnetandopus. - Full model IDs such as
claude-opus-4-5. - A short example for both file-based subagents and
--agentsJSON.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 215, 227-231 | File-based subagent docs say model only accepts aliases or inherit |
| https://code.claude.com/docs/en/cli-reference | 93-102 | --agents JSON schema says model is alias-only |
| https://code.claude.com/docs/en/model-config | 34-42 | Main model docs already describe full model names for --model |
Total scope: 3 pages affected
Source: Release v2.1.74
- Fixed full model IDs (e.g.,
claude-opus-4-5) being silently ignored in agent frontmattermodel:field and--agentsJSON config — agents now accept the same model values as--model
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗