bug: agent definition frontmatter `model:` field is ignored — subagents always inherit parent model
Summary
The Agent tool documentation says: "If omitted [the model parameter], uses the agent definition's model, or inherits from the parent." But in practice, the model: field in agent .md frontmatter is completely ignored. Subagents always inherit the parent model unless model is explicitly passed in the Agent tool call.
Steps to Reproduce
- Create an agent definition with explicit model:
---
model: sonnet
name: Python Engineer
description: Python development specialist
---
# Agent instructions...
- Deploy to
.claude/agents/python-engineer.md
- Spawn the agent WITHOUT passing model parameter:
{"subagent_type": "python-engineer", "prompt": "What model are you?"}
- Agent reports: Opus 4.6 (parent model, NOT sonnet)
- Spawn with explicit model parameter:
{"subagent_type": "python-engineer", "model": "sonnet", "prompt": "What model are you?"}
- Agent reports: Sonnet 4.6 ✅
Expected Behavior
When model parameter is omitted from the Agent tool call, Claude Code should read the model: field from the agent's .md frontmatter and use it. Per the Agent tool schema: "If omitted, uses the agent definition's model."
Actual Behavior
The frontmatter model: field is ignored entirely. The subagent inherits the parent's model (opus in this case). Only the explicit model parameter on the Agent tool call has any effect.
Impact
This makes cost-optimized model tiering impossible via agent definitions alone. Multi-agent frameworks (like claude-mpm) that define 50+ agents with model: sonnet or model: haiku in frontmatter get no benefit — all subagents run as opus regardless, costing 5-34x more than intended.
Workaround
The calling agent (PM) must explicitly pass model: "sonnet" on every Agent tool call. This works but requires the orchestrator to know the right model for each agent type, defeating the purpose of declaring it in the agent definition.
Environment
- Claude Code CLI (latest)
- macOS Darwin 25.3.0
- Agent definitions in
.claude/agents/with YAML frontmatter
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗