Aoba Works

Posted on Oct 21 Originally published at en.aobaworks.com

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

#claudecode #subagents #modelselection #haiku

Originally published at Unattended.

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.

Your situation	What to pick first	First page to open
Beginner, writing your first 1–3 subagents	`model: sonnet` on each one. It's Anthropic's stated default for "daily coding tasks" (model config)	Create custom subagents
Daily work on a Pro or Max plan	Sonnet for coding agents, Haiku for search and summarize agents, inherit only where you want `/model` switches to carry over	Manage costs
Tight budget on API billing	Haiku for every read-only or repetitive agent. Opus only for one planning or review agent	Pricing
Unattended cron or headless pipelines	An explicit model on every agent (no `inherit`), plus `CLAUDE_CODE_SUBAGENT_MODEL` as a fallback	Sub-agents: choose a model
Security-critical or architectural review	`model: opus` on that one agent, called rarely and on purpose with an @-mention	Choosing a model

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

In your project root, create the folder: mkdir -p .claude/agents.
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.

Optionally add effort: low|medium|high|xhigh|max. It "Overrides the session effort level" for this subagent only (sub-agents).
Call it explicitly by typing @ and choosing it from the typeahead, for example @"code-reviewer (agent)" look at the auth changes.
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).

	Haiku 5.5	Sonnet 5.5	Opus 5.5	Fable 5.1
Alias in frontmatter	`haiku`	`sonnet`	`opus`	`fable`
Input / output price per MTok	From $0.10 / $0.50	$2 / $10	$4 / $20	$10 / $50
Comparative latency	Fastest	Fast	Moderate	Slower
Default API effort	`medium`	`high`	`medium`	`high`
Context window / max output	1M / 128K	1M / 128K	1M / 128K	1M / 128K
Good subagent roles	File search, log triage, test-output summary, labeling, routing	Implementing, debugging, everyday code review, doc writing	Architecture plans, security review, large refactor plans	Hours-long research or agent runs where Opus already fell short
Not for	Ambiguous multi-file changes	Rare, high-stakes decisions	Anything you call dozens of times a day	Budget-capped pipelines

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 agent	Model	Tools	What it checks
`style-checker`	`haiku`	Read, Grep, Bash(npm run lint)	Naming, formatting, lint output, missing docstrings
`code-reviewer`	`sonnet`	Read, Glob, Grep	Logic errors, test coverage, readability
`security-reviewer`	`opus`	Read, Glob, Grep	Auth, input validation, secrets, permission boundaries

(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:

Model	Cost per run	30 runs/day	~30 days
Haiku 5.5 ($0.10 / $0.50)	$0.0075	$0.23	~$7
Sonnet 5.5 ($2 / $10)	$0.15	$4.50	~$135
Opus 5.5 ($4 / $20)	$0.30	$9.00	~$270

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

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.
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.
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

Use `inherit` when	Use an explicit model when
The agent does the same kind of work as your main session (implementing, debugging)	The agent's job is clearly cheaper or harder than your main work
You switch models often and want the agent to follow	The agent runs unattended (cron, CI, headless `-p`)
You only use one or two subagents	You run several agents in one session

Steps: convert inherit agents safely

List your agents: ls .claude/agents ~/.claude/agents.
Search for agents with no model or with inherit: grep -L "^model:" .claude/agents/*.md and grep -l "model: inherit" .claude/agents/*.md.
For each one, decide on Haiku, Sonnet or Opus using the table above, and edit the line.
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:

The per-invocation model parameter (Claude's choice at call time)
The subagent's model frontmatter
The CLAUDE_CODE_SUBAGENT_MODEL environment variable
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:

Pick 5–10 past tasks for this agent where you already know the right answer.
Run them with model: haiku, then with model: sonnet.
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.

Spec (as of October 2026)	Haiku 5.5	Sonnet 5.5	Opus 5.5	Fable 5.1
Comparative latency	Fastest	Fast	Moderate	Slower
Context window	1M	1M	1M	1M
Max output (sync API)	128K	128K	128K	128K
Effort levels in Claude Code	low → max	low → max	low → max	low → max

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:

Run grep -L "^model:" .claude/agents/*.md ~/.claude/agents/*.md and give every listed agent an explicit model, using the role table above.
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.
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:

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

This article was created with the help of AI. Sources are linked inline; check the official documentation for the latest details.