CLAUDE_CODE_SUBAGENT_MODEL=inherit ignores per-call Task model param (contradicts docs)

[AlvaroRojas]

Summary

On Claude Code 2.1.177, setting CLAUDE_CODE_SUBAGENT_MODEL=inherit causes dispatched subagents to ignore the per-call model parameter and always run the main session model. The model-config docs state inherit means "use normal model resolution," and the sub-agents docs rank the per-invocation model param above the session model — so per-call routing should work with inherit. It does not. Unsetting the variable entirely makes it work as documented.

Environment

• Claude Code 2.1.177, Windows 11
• settings.json: top-level "model": "opus", env "CLAUDE_CODE_SUBAGENT_MODEL": "inherit"

Repro

1. settings.json -> "model": "opus", env "CLAUDE_CODE_SUBAGENT_MODEL": "inherit". Restart Claude Code.
2. Dispatch a subagent (Task tool) with model: "haiku" (or "sonnet").
3. Inspect the subagent transcript ~/.claude/projects/<proj>/<session>/subagents/agent-<id>.jsonl and grep "model".

Actual

model:"haiku" and model:"sonnet" both ran claude-opus-4-8 (the session model). The per-call param is dropped — it is not even recorded in the subagent transcript.

Expected

Per the documented precedence (per-invocation model param > session model; inherit = normal resolution), the subagent should run claude-haiku-4-5.

What actually works

Removing CLAUDE_CODE_SUBAGENT_MODEL entirely (unset) + restart -> model:"haiku" correctly runs claude-haiku-4-5-20251001. So inherit does not behave like "unset," contrary to the docs.

Fix (either resolves it)

1. Code: make inherit defer to the per-call model param as documented; or
2. Docs: clarify that inherit forces the session model and the variable must be unset for the per-call model to be honored.

Impact

Silent cost blow-up — orchestrator-intended haiku/sonnet subagents all silently ran Opus.

[kcarriedo]

Good repro. The documented behavior says inherit means "use normal model resolution" (per-invocation param ranks above session model), but what you're seeing is it acting as "pin to session model, ignore per-call param." That's a meaningful difference - especially for anyone who set CLAUDE_CODE_SUBAGENT_MODEL=inherit specifically because they wanted orchestrator-level control over which model each task subagent runs.

The cost impact you flagged at the end deserves emphasis: this isn't just a doc inconsistency. Someone deliberately routing intensive subagents to haiku and light orchestration to opus to manage spend is getting the opposite - all subagents silently running opus regardless of the per-call instruction. At scale (a workflow with 10+ subagent dispatches per session) that's a real cost blow-up that's hard to catch without digging into the jsonl transcripts as you did.

The unset vs. set to inherit discrepancy you've isolated is the key evidence. If inherit genuinely meant "normal resolution," unsetting the variable would have produced no behavioral difference. The fact that unsetting it fixes the routing strongly suggests inherit is currently being interpreted as a special-case override ("use session model") rather than "no override."

Worth tagging this as a billing/cost impact bug in addition to the doc inconsistency framing - that may get it routed faster.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.