[DOCS] Subagent docs still restrict `model` to aliases instead of full model IDs

Resolved 💬 2 comments Opened Mar 12, 2026 by coygeek Closed Mar 16, 2026

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, or inherit. Defaults to inherit |

The "Choose a model" subsection also says:

* Model alias: Use one of the available aliases: sonnet, opus, or haiku

The CLI reference says the --agents JSON field is alias-only:

| model | No | Model alias to use: sonnet, opus, haiku, or inherit. If omitted, defaults to inherit |

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:

  1. Standard aliases such as sonnet and opus.
  2. Full model IDs such as claude-opus-4-5.
  3. A short example for both file-based subagents and --agents JSON.

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 frontmatter model: field and --agents JSON config — agents now accept the same model values as --model

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗