Claude Code Model Aliases Silently Hardcode Instead of Tracking Latest

What you expect

Anthropic’s model-config documentation states that aliases (opus, sonnet, haiku) always resolve to the current latest model in a family. When Anthropic promotes a new model, the alias re-targets silently. Teams using model: opus in agent frontmatter expect either a live pointer (always the latest Opus) or a stable pinned version — the docs describe the first behavior, so teams assume they know what they’re getting.

The deprecation cadence documentation specifies ≥60 days notice before model retirement, and teams assume this covers alias transitions.

What actually happens

model: opus in a .claude/agents/ frontmatter file hardcodes to claude-opus-4-1-20250805 — a specific dated model ID — regardless of which model the opus alias currently targets at the Anthropic API level. The alias is not a live pointer at the Claude Code runtime layer; it is a static identifier that was resolved at some point during Claude Code’s development and baked in.

Three confirmed production failures from GitHub issues (Feb 2026):

1. Hard 400 on Bedrock and Vertex — model: opus in frontmatter causes Claude Code to send claude-opus-4-1-20250805 to the Bedrock endpoint. If the org policy allowlist only includes Opus 4.6, the request fails: "Organization Policy constraint constraints/vertexai.allowedModels violated... attempting to use a disallowed Gen AI model claude-opus-4-1." The error names the hardcoded dated model ID, not the alias — this is the first indication to most operators that hardcoding is occurring. (Issues #25530, #27754)

2. ANTHROPIC_MODEL env var silently ignored — Setting ANTHROPIC_MODEL=global.anthropic.claude-opus-4-6-v1 does not override model: opus in frontmatter; the session uses the hardcoded resolved model ID with no error emitted (issue #27754).

The correct env var is ANTHROPIC_DEFAULT_OPUS_MODEL, not ANTHROPIC_MODEL — using the wrong one is a silent no-op with no validation or feedback.

3. /model picker doesn’t reflect env var overrides — The interactive /model command displays a model selection UI but does not reflect environment variable overrides active at the session level. An operator using /model to verify which model is running may see a model name that differs from the model actually invoked. There is no reliable in-session mechanism to confirm the active model when overrides are in effect. (Claude Code changelog)

4. Subagent cost amplification via model: inherit — When a session runs on Opus, all subagents using model: inherit bill at Opus pricing; an audit of 62 agent definitions across 6 plugins found zero that required Opus (issue #26179, open and stale as of 2026-03-07).

There is no global max_subagent_model cap — all were suitable for Sonnet or Haiku, but plugin authors default to inherit because it requires no assumption about the caller’s model.

5. Inverse failure — stale pinned model IDs — Pinning a versioned model ID (e.g., claude-sonnet-4-6-20250514) avoids alias drift but creates a retirement dependency. When Anthropic retires the pinned version, agent invocations fail hard with no fallback and no proactive notification. The confirmed minimum retirement window is 62 days (Haiku 3.5: deprecated Dec 2025, retired Feb 2026), but alias promotion to a new model happens on Anthropic’s release schedule, not bounded by the deprecation window.

The Bedrock/Vertex alias breakage warning appears only in Anthropic’s third-party deployment documentation section — not on the primary model-config page. Teams not deploying to those targets skip that section entirely and have no in-path indication that alias behavior differs by deployment target.

What this means for you

Any agent definition using a bare alias (model: opus, model: sonnet, model: haiku) in .claude/agents/ frontmatter is operating on a hardcoded dated model ID that may diverge from both the current alias target and your org’s allowlist. The failure mode is silent until a deployment boundary or retirement event forces it to the surface.

Teams using Bedrock or Vertex are at highest immediate risk: org policy allowlists configured for current model IDs will reject requests using Claude Code’s stale hardcoded resolution. The mismatch is invisible until the first request fails, and the error message (which names the hardcoded model ID) is the first signal that hardcoding is occurring.

Teams running Opus sessions without auditing subagent model fields pay Opus pricing for all subagents via model: inherit — a cost multiplier that compounds across every plugin update unless patched manually. There is no automated mechanism to detect or cap this.

What to do

For Bedrock/Vertex hard 400 errors:

1. Remove model: opus (or any bare alias) from agent frontmatter entirely.
2. Either omit the model: field (inherits from session, resolved correctly at session level) or set a versioned model ID matching your org allowlist.
3. Restart the Claude Code session — agent definitions are cached at startup; hot-reload of modified frontmatter does not occur.

For env var override:

1. Use ANTHROPIC_DEFAULT_OPUS_MODEL (not ANTHROPIC_MODEL) to override the Opus alias target.
2. Verify the override by running a test task and checking debug output — do not infer from the /model picker, which does not reflect env var overrides.

For subagent cost amplification:

1. Audit all .claude/agents/ files (including installed plugins) for model: inherit.
2. Set model: sonnet or model: haiku explicitly on each agent that does not require Opus capability.
3. Repeat this audit after every plugin update — there is no global max_subagent_model setting.

For preventing stale pinned model ID failures:

1. Monitor platform.claude.com/docs/en/about-claude/model-deprecations manually — there is no subscription mechanism.
2. Review all agent frontmatter model fields at each major Claude release cycle.
3. Treat pinned dated model IDs as short-to-medium term stability only (within the ~62-day deprecation window).

Falsification criterion: This finding would be disproved by Claude Code shipping a fix that makes model: opus in agent frontmatter resolve dynamically to the current Anthropic API alias target (not a hardcoded dated model ID), and ANTHROPIC_MODEL correctly overriding frontmatter aliases — confirmed in issues #25530 and #22587.

Evidence

Note: model identifiers in the Version column identify specific model IDs observed in failure reports — no scores are compared across models; these are tool versions and issue references only.

Tool	Version	Evidence	Result
Claude Code (Anthropic)	v2.x, researched 2026-03-08	docs-reviewed	Alias docs describe live pointer behavior; Bedrock/Vertex warning segregated to deployment section only
Claude Code on AWS Bedrock	Issues #25530, #27754 — Feb 2026	source-reviewed	model: opus hardcodes to claude-opus-4-1-20250805; hard 400 when org allowlist excludes it
Claude Code on AWS Bedrock	Issue #27754 — Feb 2026	source-reviewed	ANTHROPIC_MODEL env var silently ignored when frontmatter alias is set; correct var is ANTHROPIC_DEFAULT_OPUS_MODEL
Claude Code subagent inherit	Issue #26179 — open, stale 2026-03-07	source-reviewed	62 agent definitions across 6 plugins; all used model: inherit; zero required Opus
Anthropic model deprecations	Reviewed 2026-05-24	docs-reviewed	Haiku 3.5: deprecated Dec 2025, retired Feb 2026 — 62-day minimum window confirmed

Confidence: empirical — 4 environments reviewed. No independent third-party confirmation; all evidence sourced from Anthropic’s own GitHub issues and documentation.

Strongest case against: The behavior documented here (alias hardcoding, ANTHROPIC_MODEL being silently ignored) may have been fixed in a Claude Code release after 2026-03-08, the research date. The issue tracker shows volunteer patch offers (issue #25530, Feb 23 2026), and issue #27754 was closed as a duplicate of #22587 — the root issue status is unclear. Teams should test current behavior before treating this as confirmed for their Claude Code version.

Open questions: Complete behavior mapping of model: opus in frontmatter across all non-Bedrock deployment targets is unknown. How alias resolution behaves on other third-party runtimes or in air-gapped environments has not been studied. Whether the v1.5.x+ release series resolved the hardcoding is unverified — no per-issue fix confirmation appears in release notes.

Seen different? Contribute your evidence — share a repro or counter-example and we’ll review it against this finding. Reader evidence is what keeps these findings accurate.