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

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

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.

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.

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:

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.

--- 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. Enter fullscreen mode Exit fullscreen mode 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.

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.

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

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.

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

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.

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

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

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.

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.

.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 Enter fullscreen mode Exit fullscreen mode 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.

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:

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.

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.

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.

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:

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.

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.

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.

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.

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.

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.

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.

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

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