Subagent model routing is broken — all mechanisms resolve to parent model (Opus)

[zadr007]

Bug description

Subagent model routing does not work. All documented mechanisms for routing subagents to a different model (e.g. Sonnet) are silently ignored — subagents always run on the parent session's model (Opus).

Tested mechanisms (all failed)

#	Mechanism	Doc reference
1	Agent(model: "sonnet") per-invocation param	Subagent docs
2	Custom agent .claude/agents/*.md with model: sonnet frontmatter	Subagent docs
3	CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-4-6 env var	Model config docs
4	CLAUDE_CODE_SUBAGENT_MODEL=sonnet env var (alias)	Same
5	settings.json top-level "env": { "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet" }	Model config docs

Reproduction

1. Start Claude Code on a Max plan with Opus as the main model
2. Note the "Sonnet only" usage % on the dashboard
3. Spawn subagents with any of the above mechanisms
4. Check dashboard — Sonnet stays flat, Opus session usage increases

We ran 5 separate tests (15 subagents total, 3 per test). Sonnet stayed at 2% across all tests while Opus increased each time.

Expected behavior

The subagent docs document a resolution order:

1. CLAUDE_CODE_SUBAGENT_MODEL env var (highest priority)
2. Per-invocation model parameter
3. Subagent definition's model frontmatter
4. Main conversation's model (fallback)

At least one of these should actually route the subagent to the specified model.

Impact

Max plan users have a separate "Sonnet only" quota that is currently unusable from Claude Code. All subagent work (search, exploration, scaffolding) consumes the shared Opus weekly limit instead, leading to faster throttling.

Related issues

• [BUG] general-purpose agent sets model as 'sonnet' rather than 'inherit' #8932 — general-purpose agent sets model as 'sonnet' rather than 'inherit'
• [BUG] Sub-agents Don't Inherit Model Configuration in Task Tool #5456 — Sub-agents Don't Inherit Model Configuration in Task Tool
• Allow per-agent-type model overrides in settings #37823 — Allow per-agent-type model overrides in settings
• Subagents should default to Sonnet, not inherit Opus #26179 — Subagents should default to Sonnet, not inherit Opus
• [DOCS] Ambiguity regarding default model behavior for Subagents #19174 — Ambiguity regarding default model behavior for Subagents

Environment

• Claude Code desktop app (Windows 11)
• Opus 4.6 (1M context) as main model
• Max plan (5x)
• Tested 2026-04-05

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Claude Code does not respect agent model definition, uses wrong model. #18346
2. Agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) ignore modelOverrides when spawning subagents #41045
3. Task tool model parameter ignored when spawning teammates with team_name #24668

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[zadr007]

This is not a duplicate of the suggested issues:

• [BUG] Claude Code does not respect agent model definition, uses wrong model. #18346 reports the opposite direction (sets model: opus, gets Sonnet). Our issue is: set model: sonnet, get Opus. Same root cause likely, but distinct symptom and different reproduction.
• Agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) ignore modelOverrides when spawning subagents #41045 is about agent teams on AWS Bedrock ignoring modelOverrides in the tmux spawner. We're on the Anthropic API using subagents, not agent teams.
• Task tool model parameter ignored when spawning teammates with team_name #24668 is about the Task tool model param being ignored specifically when team_name is provided (agent teams). Already closed as duplicate.

What makes this issue unique: We systematically tested all 5 documented mechanisms for subagent model routing — per-invocation model param, custom agent frontmatter, CLAUDE_CODE_SUBAGENT_MODEL env var (both full ID and alias), and settings.json env injection — and verified each with Anthropic dashboard metrics (Sonnet-only quota). None of them work.

The closest issue (#18346) only covers one mechanism and lacks dashboard verification. Our issue provides a complete test matrix that demonstrates the entire model resolution chain documented at https://code.claude.com/docs/en/sub-agents#choose-a-model is non-functional.

👎 to prevent auto-closure.