CLAUDE_CODE_SUBAGENT_MODEL silently discards explicit per-call subagent model since v2.1.223; documented warning never fires; subagent metadata records requested (not effective) model

Adding a related failure mode when the env-pin value is the literal string inherit rather than a real model ID.

Environment

• AI_AGENT=claude-code/2.1.121/agent (the actual executing process, from env)
• claude --version reports 2.1.239
• ~/.claude/settings.json env.CLAUDE_CODE_SUBAGENT_MODEL=inherit
• Session model: opus[1m]
• macOS 25.6.0

Repro

1. Set env.CLAUDE_CODE_SUBAGENT_MODEL=inherit in ~/.claude/settings.json.
2. Dispatch Agent({subagent_type: "Explore", model: "sonnet", prompt: ...}) or Agent({subagent_type: "general-purpose", model: "opus", prompt: ...}).
3. The Agent tool returns the tool_result:

> There's an issue with the selected model (inherit). It may not exist or you may not have access to it. Run /model to pick a different model.

total_tokens: 0, tool_uses: 0, duration_ms: 762 — the subagent never runs.

Reproduced 6 out of 6 attempts across both Explore and general-purpose built-in subagent types with explicit model: "sonnet" and model: "opus" overrides in the same session.

What this adds to #85592

1. The bug from #85592 (per-call model silently discarded in favour of the env pin) also fires when the pin value is "inherit" — but here the failure is a hard user-visible error, not a silent downgrade, because the CLI's model resolver never rewrites the literal string "inherit" into the parent model ID before the API call.
2. This makes CLAUDE_CODE_SUBAGENT_MODEL=inherit unusable as a workaround for #85592: users who tried setting it to inherit specifically to stop the env pin overriding per-call model (see e.g. custom PreToolUse gates that flipped from sonnet to inherit for exactly this reason) get every subagent call hard-failing instead.
3. Combined with the metadata bug you flagged, this is a debugging trap: .meta.json shows the requested model, the tool_result shows the resolver error naming inherit, and neither surfaces the fact that the env pin is the actual culprit.

Suggested fix scope

Either:

• resolve "inherit" to the parent model ID inside the resolver (matches the schema's documented "inherits from the parent" behaviour), and honour explicit per-call model over the env pin; or
• reject "inherit" at settings-load time with a clear error message, so users don't hit the resolver failure at first Agent call.

Happy to test a fix against 2.1.239 if useful.

Adding empirical data plus links to the specific docs this contradicts.

Data: CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5-20251001 exported globally via shell profile (not managed-settings). Two agents in .claude/agents/ declare model: sonnet in frontmatter: coder-scout and coder-build. Checked 4 real invocations (no model param passed at call time, per each subagent's meta.json), grepping message.model across every assistant turn:

• coder-scout x3: 58, 281, 44 turns, 100% claude-haiku-4-5-20251001
• coder-build x1: 178 turns, 100% claude-haiku-4-5-20251001

561/561 turns served by the env-pinned model despite explicit model: sonnet frontmatter.

This matches the documented precedence at code.claude.com/docs/en/sub-agents ("Configure subagents → Choose a model"): env var > per-invocation param > frontmatter > main conversation model. So against that page, this is working as designed.

But it contradicts two other places:

1. The Agent tool's own model parameter description (in-product tool schema, no public URL): "Takes precedence over the agent definition's model frontmatter." No mention that a machine-wide env var can override the param itself.
2. CHANGELOG.md, ## 2.1.223: "Added a warning when workflow agents, forked skills, slash commands, or resumed background agents' requested subagent model is restricted and the parent model runs instead." Here the env-pinned model runs, not the parent model, and no warning fires anywhere (tool result, transcript, or meta.json, which still records the requested model, not the effective one).

Whichever precedence is intended, the tool schema text and changelog description should match actual behavior, and the promised warning should fire so agent authors know their model: field is inert.

Thanks for the very detailed report — I ran this against the latest release (2.1.233) and can confirm parts of it, with one important correction on the regression framing.

Confirmed on 2.1.233:

• With CLAUDE_CODE_SUBAGENT_MODEL set, an Agent call with an explicit model parameter is served the env-pinned model (verified via the subagent's self-reported model ID and "model" on its transcript's assistant messages).
• No warning appears anywhere (tool result, parent transcript, subagent transcript).
• The subagent's .meta.json records the requested model, not the effective one.

Not a precedence regression: I ran the identical test on 2.1.220 and the env pin overrides the explicit model parameter there too. This precedence is documented: the settings docs describe CLAUDE_CODE_SUBAGENT_MODEL as overriding the per-invocation model parameter and subagent frontmatter (with inherit restoring normal resolution).

Why it changed for you at 2.1.223: that release fixed machine-local managed-settings.json env blocks being disabled when server-delivered settings are present (see the 2.1.223 changelog). Your May-era env pin most likely only started taking effect then — which matches your ≤2.1.220 observations of per-call models being honored.

Why the documented warning doesn't fire: the 2.1.223 warning entry covers org-restricted subagent models falling back to the parent model — a different mechanism than the env pin, which currently substitutes silently.

Keeping this open for the two things that are genuinely wrong regardless of intended precedence: the silent substitution of an explicitly requested model should surface a notice, and subagent metadata should record the effective model (or both).

🤖 Generated with Claude Code