Claude Code Subagents Model Selection: Role-by-Role Table

By Aoba Works · Published October 22, 2026 · Sources checked October 22, 2026 · 16 min read

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

• Claude Code
• Subagents

To choose models for Claude Code subagents, set model: in each subagent's frontmatter. Use haiku for high-volume, low-ambiguity jobs like triage, log filtering and file search. Use sonnet for most coding and review agents, and keep opus for the few agents whose mistakes are expensive, like architecture planning or security review. Anthropic's own cost guide says it directly: "For simple subagent tasks, specify model: haiku" (Claude Code costs). The docs show the syntax. This guide adds a way to decide by role, the price math (as of October 2026), and the one precedence rule that can quietly cancel your choice.

Which option is right for you?

If you're new to subagents, put model: sonnet on every custom subagent. Then move single agents down to Haiku or up to Opus once you've seen how they actually perform.

Why Sonnet first: in Anthropic's words, "Sonnet handles most coding tasks well and costs less than Opus" (costs). Starting there gives you a baseline you can compare against before you adjust anything.

What is the model field in Claude Code subagents?

The model field is an optional frontmatter key in a Claude Code subagent file. It sets which Claude model runs that subagent, independent of your main session.

Subagents are Markdown files with YAML frontmatter. Put them in .claude/agents/ for one project or ~/.claude/agents/ for every project. Both folders are scanned recursively, so subfolders like agents/review/ work (sub-agents). According to the frontmatter reference, model accepts:

• An alias: sonnet, opus, haiku, or fable
• A full model ID such as claude-opus-5-5, the same values the --model flag accepts
• inherit, which uses the same model as the main conversation
• Nothing at all. If you leave it out, Claude Code works down its resolution order, which ends at the main conversation's model (sub-agents)

On the Anthropic API, as of October 2026, the aliases resolve to Opus 5.5, Sonnet 5.5 and Haiku 5.5. On Amazon Bedrock and Google Cloud, sonnet and haiku still point to Sonnet 4.5 and Haiku 4.5 (model config). If you're on a cloud provider, check that table before you assume you're getting the newest model.

Steps: add a model to a subagent

1. In your project root, create the folder: mkdir -p .claude/agents.
2. Create .claude/agents/code-reviewer.md with this frontmatter. It's the example from the official docs:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

1. Optionally add effort: low|medium|high|xhigh|max. It "Overrides the session effort level" for this subagent only (sub-agents).
2. Call it explicitly by typing @ and choosing it from the typeahead, for example @"code-reviewer (agent)" look at the auth changes.
3. While it runs, type /tasks. The subagent's row shows the model it's actually using (sub-agents).

Note: from Claude Code v2.1.198, /agents no longer opens the old wizard with Running and Library tabs. It shows a reminder to edit the folders directly or to ask Claude to create the subagent for you (sub-agents). If an older tutorial tells you to click through Library, edit the file instead.

If you're also limiting what each agent can touch, the tools: line goes in the same frontmatter. See Claude Code Subagent allowed-tools: Syntax, Examples, Fixes.

Haiku vs Sonnet vs Opus: which should I use for subagents?

Use Haiku for repetitive, well-defined work, Sonnet for most coding agents, and Opus for complex planning where errors are costly.

Anthropic's own short descriptions line up with these roles. Haiku 5.5 is "For high-volume, latency-sensitive tasks such as classification, extraction, and routing" (models overview). The Choosing a model matrix even lists "sub-agent tasks" as a Haiku use case (choosing a model). The cost guide says to "Reserve Opus for complex architectural decisions or multi-step reasoning" (costs).

Prices and specs are from the models overview (as of October 2026; check the official page).

Here's a rule of thumb for each role. Ask what one wrong answer from this agent would cost you, and how often the agent runs. Low cost of error and high frequency points to Haiku. High cost of error and low frequency points to Opus. Everything else is Sonnet.

One limitation of this framework: the price gap between Opus 5.5 and Sonnet 5.5 is only 2x, so a single Opus agent called a few times a day may cost less than you'd expect. The gap that really matters for recurring work is between Sonnet and Haiku, which is roughly 20x on base prices.

How do I choose a model for a code review subagent?

Default a code review subagent to Sonnet. Drop to Haiku for mechanical checks like style or lint, and switch to Opus for security-sensitive or architectural reviews.

Review means reading a diff alongside the files it touches and judging intent. That's contextual reasoning, so Sonnet is the safe default, and it's what the official code-reviewer example uses. A practical way to split it is two or three review agents instead of one:

(Example layout, not an official template.)

Pitfalls with review agents

• A vague description triggers the expensive agent too often. Claude "uses each subagent's description to decide when to delegate tasks" (sub-agents). If your Opus security reviewer's description says "use proactively for any code change," it'll run on every edit. Fix: leave out the word "proactively" for Opus agents and call them with an @-mention instead.
• Haiku reviewing a refactor. A style agent that's asked "is this refactor safe?" will still answer, and the answer may be shallow. Fix: put the agent's scope in its system prompt, e.g. "Only report lint and formatting issues; say 'out of scope' for logic questions."
• Too many tokens per review. Lint output and test logs are long. Filtering them with a hook before the agent sees them keeps any model cheaper. The official cost guide shows a PreToolUse hook that greps test output down to failures (costs), and Claude Code Hooks Examples: 7 Copy-Paste Scripts has more patterns like it.

How to reduce cost when running multiple subagents?

Put Haiku on your high-frequency, low-complexity subagents and Sonnet or Opus on the rarely called, reasoning-heavy ones. Cost scales with model price times call volume.

Every subagent "runs in its own context window with its own requests," and those requests count toward the same limits as your main conversation (sub-agents). On a Pro or Max plan, that means usage limits. On API billing, it means dollars.

Example cost math (illustrative numbers, not measurements)

Say a triage subagent reads 50,000 input tokens and writes 5,000 output tokens per run, and a cron job fires it 30 times a day. Using base list prices, with no caching:

Prices from the models overview and Haiku 5.5 page (as of October 2026; check the official page). Your real numbers will differ. Prompt caching lowers them, since cache reads cost 10% of base input, or 5% on Opus 5.5 and Sonnet 5.5. Thinking pushes them up, because "Thinking tokens are billed as output tokens" (costs).

Three Haiku pricing details that change the math

1. Haiku 5.5 has two price tiers. It costs $0.10/$0.50 per MTok "for prompts up to 100,000 tokens" and $0.50/$2.50 above that (Haiku 5.5). A Haiku agent that loads a huge log costs 5x more per token. Keep Haiku prompts under 100K by trimming input with hooks or narrower file globs.
2. The tokenizer changed. The same text counts as "approximately 30% more tokens than on Claude Haiku 4.5" (Haiku 5.5). Old per-run estimates from Haiku 4.5 will undercount.
3. You can't switch thinking off. Thinking can't be disabled on Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable (costs). For cheap agents, lower effort instead. Anthropic notes "Tuning effort is often a better lever than switching models" (choosing a model).

The built-in Explore agent

Claude Code ships a built-in Explore subagent for file discovery and code search. With a Claude subscription or Console login, it runs on the model the opus alias resolves to, not your session model (sub-agents). If you want cheaper searches, create your own subagent named Explore with model: haiku. The docs say a user or project subagent with that name overrides the built-in one.

See where the tokens go

Run /usage. On Pro, Max, Team and Enterprise plans it shows usage attributed to "skills, subagents, plugins, and individual MCP servers" as percentages (costs). Start with the subagent that has the biggest share. For a full walkthrough of the numbers, see Claude Code: How to See Token Usage (and Reduce It).

What does the inherit model setting do in subagents?

model: inherit makes a Claude Code subagent run on the main conversation's current model. Config stays simple, but you lose per-agent cost control.

Inherit follows you around. If you type /model opus mid-session, the switch "reaches subagents that inherit the main conversation's model" (model config). That's useful for an implementer agent that should always match your thinking power. It's a cost trap for a summarize-the-logs agent that was fine on Haiku.

There's also a subtle alias rule. If you set model: opus and your main session is already on an Opus model, the subagent uses your session's exact model, including a [1m] suffix and its extended context (sub-agents).

When to use inherit vs. an explicit model

Steps: convert inherit agents safely

1. List your agents: ls .claude/agents ~/.claude/agents.
2. Search for agents with no model or with inherit: grep -L "^model:" .claude/agents/.md and grep -l "model: inherit" .claude/agents/.md.
3. For each one, decide on Haiku, Sonnet or Opus using the table above, and edit the line.
4. Start a run and confirm the model in /tasks.

A common mistake is assuming that leaving model out means "Sonnet." It doesn't. With no frontmatter model and no CLAUDE_CODE_SUBAGENT_MODEL, the agent falls through to the main conversation's model (sub-agents). In practice, that's the same as inherit.

Can I use different models for different subagents in the same project?

Yes. Each Claude Code subagent file sets its own model, so one project can run Haiku, Sonnet and Opus agents side by side without them affecting each other.

Example project layout (illustrative)

.claude/agents/
├── research/
│   ├── Explore.md          # model: haiku  (overrides built-in Explore)
│   └── log-triage.md       # model: haiku, effort: low
├── build/
│   ├── implementer.md      # model: inherit
│   └── test-fixer.md       # model: sonnet
└── review/
    ├── code-reviewer.md    # model: sonnet
    └── security-reviewer.md # model: opus

Folder order matters when names clash. Managed settings beat the --agents flag, which beats .claude/agents/, which beats ~/.claude/agents/, which beats plugin agents (sub-agents). A project code-reviewer on Sonnet will override a personal code-reviewer on Opus.

The precedence rule that can override your choice

This is the part most guides skip. "When Claude invokes a subagent, it can also pass a model parameter for that specific invocation," and that parameter comes first in the resolution order, ahead of your frontmatter (sub-agents). The full order:

1. The per-invocation model parameter (Claude's choice at call time)
2. The subagent's model frontmatter
3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable
4. The main conversation's model

So model: haiku is a default, not a guarantee. One developer reported on DEV Community that 21 of 25 subagent calls in their logs explicitly asked for Opus despite their Sonnet setup (DEV Community). That's one user's report, not an official figure, but it shows why you should check /tasks.

Your options if it happens:

• Force one model for everything. Set CLAUDE_CODE_SUBAGENT_MODEL plus CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 in the env block of your settings (Claude Code v2.1.257+). The limitation: Claude Code then "ignores the model field in subagent definitions," so you lose per-agent mixing (sub-agents).
• Use a mod. If an installed mod sets a model in its agent.spawn hook, that replaces the per-invocation parameter (sub-agents). This suits people comfortable with plugins, and is probably too much for a first setup.
• Ask in CLAUDE.md. Add a line like "When starting subagents, do not pass a model parameter; use each agent's configured model." It's a soft instruction, so verify it with /tasks.

Also note that before v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL beat both frontmatter and per-call parameters (sub-agents). If you're on an older version, upgrade before trusting per-agent settings. Run claude --version to check.

For unattended runs, pair this with Claude Code Cron Job Setup: Run Automations Overnight so the models are fixed before anything runs at 3 a.m.

What are the risks of using Haiku for complex subagent tasks?

The main risk with Haiku on complex subagent work is shallow reasoning. It can miss edge cases in multi-file changes or misread ambiguous instructions, and the result looks confident.

Anthropic positions Haiku 5.5 for "classification, routing, extraction, and subagent tasks" (Haiku 5.5). It puts large-scale refactoring and complex systems engineering under Opus in its selection matrix (choosing a model). Using Haiku outside that range rarely fails loudly. The more likely result is a plausible summary with a missing piece.

Where it tends to go wrong (examples)

• Multi-file refactors. Changing a function signature requires finding every call site and reasoning about side effects. Keep Haiku read-only here. Let it list call sites and let a Sonnet agent make the edits.
• Ambiguous prompts. "Clean up the auth module" has many valid readings. A cheaper model may pick one without saying so. Write success criteria into the agent's prompt.
• Silent scope creep. A Haiku agent with Write and Edit tools can make changes you didn't expect. Give Haiku agents read-only tools (Read, Glob, Grep) unless the task is truly mechanical.
• Verbose context. Above 100K prompt tokens, Haiku's price rises 5x (Haiku 5.5), so a big context removes much of the cost advantage too.

How to test before trusting it

Anthropic suggests an "efficiency-first" path: begin with Haiku 5.5, test thoroughly, and "Upgrade only if necessary for specific capability gaps" (choosing a model). For a solo builder, that can be small:

1. Pick 5–10 past tasks for this agent where you already know the right answer.
2. Run them with model: haiku, then with model: sonnet.
3. Compare misses. If Haiku misses things that matter, upgrade that one agent and leave the others alone.

Add guardrails so a weaker agent can't do damage. AI Agent Guardrails Example: Copy-Paste Claude Code Rules has rules you can paste in.

How does subagent model choice affect latency and token limits?

Haiku is the fastest Claude model and Fable the slowest. All four current models share the same 1M-token context and 128K-token output limits, so the choice mostly affects speed and price, not capacity.

Sources: models overview, model config. The overview adds that "Actual latency depends on prompt length, output length, and thinking effort." Lower effort can make a slow model feel faster, and max can make Haiku slow.

Subagents also add latency of their own. Non-fork subagents "start fresh and may need time to gather context," so delegation is slower than doing the work in the main conversation (sub-agents). For an agent in a tight loop, such as one called once per file across 200 files, both effects add up. Haiku with effort: low is the natural pick there, provided the task is mechanical.

Rate limits are the other limit to watch. Parallel subagents send requests at the same time. On API billing, Anthropic's suggested per-user rate for 1–5 user teams is 200k–300k tokens per minute and 5–7 requests per minute (costs). Several Opus agents running in parallel will hit that sooner. If your overnight jobs stop with a limit error, see Claude Code Rate Limit Reached: Retry Setup for Cron Jobs.

Next steps

Do it yourself today:

1. Run grep -L "^model:" .claude/agents/.md ~/.claude/agents/.md and give every listed agent an explicit model, using the role table above.
2. Create .claude/agents/Explore.md with model: haiku and read-only tools if you're on a subscription and search-heavy work is eating your limits.
3. Run your usual workflow once, then open /usage and /tasks to confirm each agent ran on the model you set.

If you'd rather not manage this yourself: the main official lever is your plan. Claude Pro is $20/month and Max starts at $100/month, and both include Claude Code (as of October 2026; check claude.com/pricing). A higher plan suits people who'd rather buy more headroom than tune agent configs. It's a poor fit if you're mainly trying to cut costs, because usage still adds up. For Team or Enterprise seats, admins get spend reports and limits in the admin console (costs). That helps small teams, but it's more than a solo builder needs.

Related guides on this site:

• Claude Code Subagent allowed-tools: Syntax, Examples, Fixes
• Claude Code: How to See Token Usage (and Reduce It)
• Claude Code Permissions Best Practices: Headless Template
• Why Claude Code Stops Mid-Automation (and How to Fix It)

FAQ

What is the model field in Claude Code subagents?

It's an optional frontmatter key in a subagent's Markdown file that picks the model for that agent. It accepts haiku, sonnet, opus, fable, a full model ID such as claude-opus-5-5, or inherit (sub-agents). If you leave it out, the agent usually ends up on your main conversation's model.

Can I use different models for different subagents in the same project?

Yes. Each file in .claude/agents/ declares its own model, so Haiku, Sonnet and Opus agents can sit side by side. Keep in mind that Claude can pass a per-call model parameter that overrides frontmatter, so check /tasks to see what actually ran.

What does the inherit model setting do in subagents?

It makes the subagent use whatever model your main session is on, and a /model switch carries over to it (model config). Use it for agents that do the same work as you. Avoid it for cheap, repetitive agents and unattended jobs.

What are the risks of using Haiku for complex subagent tasks?

Haiku is built for high-volume work like classification, routing and extraction. On multi-file refactors or vague instructions it can return confident but incomplete results. Keep Haiku agents read-only and narrowly scoped, and test them on known past tasks before relying on them.

Does the main conversation's model matter if every subagent has its own model?

Yes, a little. The main conversation still pays for its own tokens and orchestration, and the built-in Plan subagent inherits it (sub-agents). Anthropic's cost guide links unexpectedly high spend to "Opus left as the default model" (costs).

Sources

• Create custom subagents – Claude Code Docs
• Model configuration – Claude Code Docs
• Manage costs effectively – Claude Code Docs
• Models overview – Claude Platform Docs
• Choosing the right model – Claude Platform Docs
• Claude Haiku 5.5 overview – Claude Platform Docs
• Pricing – Claude Platform Docs
• Claude plans and pricing
• Your Claude Code subagents probably pick their own model – DEV Community
• Sub-agent models and effort – HumanLayer Docs

Spotted something out of date or wrong? Tell us at shigoto.ai.note@gmail.com. Guides are re-checked against official sources on a rolling schedule.