[DOCS] Model configuration docs omit deprecated/auto-updated model warning behavior for `-p` and subagent `model` frontmatter

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/model-config

Section/Topic

Model-selection warning behavior when a requested model is deprecated or automatically updated to a newer model, including subagent model frontmatter and print-mode (-p) output handling

Current Documentation

The model configuration page currently says:

Switching to a blocked model with /model is rejected with an error, while a blocked --model flag or ANTHROPIC_MODEL value is replaced at startup with a warning naming both the requested and substituted models, and the session starts on the default model. A blocked subagent or advisor override falls back to the inherited or default model rather than failing the request.

The subagents page currently says:

The model field controls which AI model the subagent uses: 1. The CLAUDE_CODE_SUBAGENT_MODEL environment variable, if set 2. The per-invocation model parameter 3. The subagent definition's model frontmatter 4. The main conversation's model

The headless and CLI reference pages currently say:

Add the -p (or --print) flag to any claude command to run it non-interactively.

--print, -p | Print response without interactive mode

The errors page currently says:

Claude Code does not silently change model versions. It can switch to a fallback model in three specific cases:

What's Wrong or Missing?

Claude Code v2.1.183 adds this behavior:

Added a warning when the requested model is deprecated or automatically updated to a newer model, shown on stderr in print mode (-p) and now also covering models set in agent frontmatter

A. The new warning path is undocumented outside the changelog

The current model-selection docs only describe startup warnings for blocked --model / ANTHROPIC_MODEL selections. They do not explain the separate v2.1.183 case where the requested model is deprecated or automatically advanced to a newer model version.

B. Subagent model frontmatter coverage is undocumented

sub-agents.md explains how model frontmatter is resolved, but it does not say that the same warning now also applies when the chosen model came from agent frontmatter. model-config.md still frames subagent model changes only as a fallback to the inherited or default model.

C. Print mode stderr behavior is undocumented

The -p docs explain how to run Claude Code non-interactively, but they do not say this warning is emitted on stderr instead of stdout. That matters for scripts that parse stdout, especially JSON or stream-json output.

D. The troubleshooting guidance is now incomplete

errors.md currently says Claude Code changes models in only three specific cases. After v2.1.183, model-selection troubleshooting also needs to mention the deprecated/auto-updated-model warning path so users know why a session may be running on a newer model than requested.

Suggested Improvement

Add a short subsection to model-config.md that explains:

1. When Claude Code warns that a requested model is deprecated or automatically updated to a newer model
2. That the warning names both the requested and effective models
3. That the behavior applies to --model, ANTHROPIC_MODEL, and subagent model frontmatter
4. That in -p mode the warning is written to stderr so stdout remains machine-parseable

Suggested wording:

If the requested model is deprecated or has been automatically moved forward to a newer version, Claude Code starts on the replacement model and shows a warning naming both the requested and effective models. The same behavior applies when the requested model comes from subagent model frontmatter. In -p mode, the warning is written to stderr.

Then add short cross-references:

• In sub-agents.md, note under the model field that deprecated or auto-updated model selections surface the same warning behavior documented on the model-config page
• In headless.md or cli-reference.md, note that model-selection warnings are emitted on stderr in print mode
• In errors.md, include this as another model-selection case or link back to the new model-config subsection

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/model-config | 121-125 | Covers subagent models and startup warning behavior, but only for blocked --model / ANTHROPIC_MODEL selections |
| https://code.claude.com/docs/en/sub-agents | 290-301 | Documents model frontmatter resolution without the new warning behavior |
| https://code.claude.com/docs/en/headless | 21-27 | Documents -p usage without noting that this warning goes to stderr |
| https://code.claude.com/docs/en/cli-reference | 99 | --print row does not mention stderr model warnings |
| https://code.claude.com/docs/en/errors | 695-701 | Says model changes happen in only three specific cases |

Total scope: 5 pages affected

Version: Claude Code v2.1.183 added the deprecated/auto-updated model warning, including stderr output for -p and coverage for models set in agent frontmatter.

Changelog reference: https://code.claude.com/docs/en/changelog