TL;DR: Claude Code can run every subagent on a different model than your main session — a model: haiku line in an agent file, one env var, or a per-invocation parameter. Route file-scanning agents to Haiku 4.5 ($1/$5 per million tokens) and keep Sonnet 5 or Opus 5 for judgment calls, and the same fan-out costs half as much. Verified against Anthropic’s docs and pricing pages on Aug 26, 2026.

What you’ll be able to do after this guide:

• Set a model per subagent three ways — frontmatter, the Agent tool’s model parameter, or CLAUDE_CODE_SUBAGENT_MODEL — and know the exact precedence order when they conflict
• Split a 200-agent repo audit so discovery runs on Haiku 4.5 and verification on Sonnet 5, with the worked cost math: $33.90 instead of $63.60 all-Sonnet, or $40.20 instead of $159 all-Opus
• Avoid the trap that bites every local-model setup: background tasks 404-ing because ANTHROPIC_DEFAULT_HAIKU_MODEL still points at a Haiku your Ollama server doesn’t have

Honest take: If you run subagents at all on an API key, per-agent routing is the single highest-leverage cost lever Claude Code ships — bigger than prompt tweaks, bigger than /compact discipline. Set model: haiku on your read-only scanner agents today; the quality loss on grep-and-summarize work is close to zero and the price gap is 2x against Sonnet, 5x against Opus.

---

One session, four price tags

A Claude Code session hasn’t been one model talking to one API for a while now. The main conversation runs on whatever you picked with /model. Every subagent it spawns — the Explore scout, a custom code reviewer, the fan-out agents a dynamic workflow launches by the dozen — can resolve to its own model. Background housekeeping (conversation summarization for --resume, status checks) runs on a Haiku-class model on top of that; Anthropic’s cost docs put that overhead at “typically under $0.04 per session.”

The pricing spread across those slots is wide. Verified against Anthropic’s pricing page today, per million tokens:

Model	Input	Output	Cache read	The slot it belongs in
Haiku 4.5	$1	$5	$0.10	File scanning, grep triage, log parsing, doc fetching
Sonnet 5	$2	$10	$0.20	Code generation, refactoring, test writing — the daily default
Opus 5 / Opus 4.8	$5	$25	$0.50	Architecture review, security verification, cross-file reasoning
Fable 5	$10	$50	$1	Long autonomous sessions; overkill as a subagent

Two footnotes that matter for the math. Sonnet 5’s $2/$10 was announced as introductory pricing through August 31 — the docs now state the scheduled September 1 increase to $3/$15 “will not occur,” so $2/$10 is the permanent rate. And Claude 4.7-and-later models use a tokenizer that produces roughly 30% more tokens for the same text, so cross-generation comparisons by token count alone flatter the older models.

A 10x input-price gap between Haiku 4.5 and Fable 5, inside one session, controlled by a frontmatter line. That’s the whole opportunity.

The four-layer resolution order

When Claude Code invokes a subagent, the sub-agents documentation specifies the model resolution order:

1. The CLAUDE_CODE_SUBAGENT_MODEL environment variable — a blunt global override for every subagent
2. The per-invocation model parameter — what the orchestrator passes on a specific Agent tool call
3. The subagent definition’s model: frontmatter — the per-agent-type setting you’ll actually use most
4. The main conversation’s model — the fallback, since frontmatter defaults to inherit

The frontmatter field accepts the aliases sonnet, opus, haiku, or fable, a full model ID like claude-opus-5 or claude-sonnet-5, or inherit. Omit it and you get inherit — which is precisely why unrouted fan-outs get expensive: run your main session on Opus 5 and every file-listing subagent silently bills at $5/$25 too.

Note which layer wins. The env var beats everything, including the orchestrator’s per-call choice. That makes CLAUDE_CODE_SUBAGENT_MODEL the right tool for exactly two jobs — forcing all subagents onto a local model in an Ollama setup, or capping a runaway experiment — and the wrong tool for nuanced routing, because it flattens your carefully tiered agent definitions into one model.

Setting it up

The per-agent-type route is a markdown file in .claude/agents/. This is the pattern from Anthropic’s own docs, a read-only scanner pinned to a cheap model:

---
name: repo-scanner
description: Scans files and inventories TODOs, dead exports, and stale docs. Read-only.
tools: Read, Grep, Glob
model: haiku
---
You are a fast repository scanner. Locate and list findings with file:line
references. Do not analyze root causes — return the inventory only.

The cost docs are explicit about the intent: “For simple subagent tasks, specify model: haiku in your subagent configuration.” Pair it with a second agent for the expensive thinking:

---
name: security-verifier
description: Adversarially verifies whether a reported finding is a real, exploitable defect.
model: opus
---

The global override, when you want it, goes in an env var or the env block of .claude/settings.json:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku   # every subagent, regardless of frontmatter

Alias resolution is itself configurable: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, and ANTHROPIC_DEFAULT_FABLE_MODEL control which concrete model each family alias points to — useful for pinning versions fleet-wide. (ANTHROPIC_SMALL_FAST_MODEL, which older guides still cite, is deprecated in favor of ANTHROPIC_DEFAULT_HAIKU_MODEL.) Skills and slash commands take a model: frontmatter field of their own, and the opusplan alias splits a single session — Opus while planning, Sonnet while executing.

Check that routing actually took: /usage breaks the session down by model. After a routed fan-out you want to see the cheap model carrying the token bulk:

Usage by model:
    claude-haiku-4-5:  2.1k input, 48.2k output, 26.4M cache read ($4.11)
       claude-opus-5:  1.8k input, 22.7k output,  1.9M cache read ($1.53)

If everything shows up under one model ID, your frontmatter didn’t apply — see the version gotcha below.

The worked example: a 200-agent repo audit

Here’s the shape of the fan-out that makes routing pay: a repo-wide audit where 180 “find” subagents each read a slice of the codebase and 20 “verify” subagents adversarially check the findings — the pattern we walked through in the dynamic workflows guide.

Assumptions, stated so you can rescale them: each find agent processes 150K input tokens (file contents dominate) and emits 3K; each verify agent takes 80K input and emits 5K. Cache reads excluded to keep the arithmetic legible — they only make the routed numbers better, since cache reads bill at 10% of input.

Configuration	Find cost (180 agents)	Verify cost (20 agents)	Total
Everything on Opus 5	$148.50	$10.50	$159.00
Everything on Sonnet 5	$59.40	$4.20	$63.60
Routed: Haiku find, Sonnet verify	$29.70	$4.20	$33.90
Routed: Haiku find, Opus verify	$29.70	$10.50	$40.20

That’s arithmetic on verified list prices, not a benchmark: the Haiku/Sonnet split runs 47% below all-Sonnet, and the Haiku/Opus split — cheap discovery, frontier-grade verification — comes in 75% below all-Opus while keeping the strongest model exactly where wrong answers hurt. The find agents are doing retrieval and inventory, the kind of work where Haiku 4.5’s quality gap against Sonnet is hard to even observe; the verify agents are doing the reasoning your audit exists for.

The same logic scales down. A solo developer whose custom agents mostly read, grep, and summarize can put model: haiku on those definitions and leave the main session on Sonnet 5, and the subagent share of the bill drops by half without touching any workflow. For calibration: Anthropic’s enterprise numbers put average Claude Code spend around $13 per developer per active day, with 90% of users under $30 — fan-out days are what create the other 10%.

The problem we hit: local models and the background 404

This one cost us a real debugging session when we first wired Claude Code to Ollama. Symptom: the main conversation works fine against the local model, then background functionality — the summarization jobs behind claude --resume — starts throwing 404s, and any subagent left on default routing errors out the same way.

Cause: two settings, not one. Pointing Claude Code’s base URL at a local server redirects where requests go, but the model names still resolve independently. The env-vars documentation notes that ANTHROPIC_DEFAULT_HAIKU_MODEL is “also used for background functionality” — so background jobs keep requesting a Haiku-family model ID that your Ollama or LM Studio instance has never heard of, and the server correctly answers 404. Fix is two exports, mapping both the background slot and the subagent slot to models that exist locally:

export ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder
export CLAUDE_CODE_SUBAGENT_MODEL=qwen3-coder

After that, background jobs and subagents resolve to the local model and the 404s stop. The full local wiring — base URL, context-window sizing, which models hold up agentically — is in the Ollama setup guide, and the hybrid pattern (local orchestrator, cloud subagents for frontier judgment, or the reverse) is in our subagents-on-Ollama deep dive. If you’re sizing hardware for the local half, runaihome.com’s local-models-by-VRAM guide covers which GPU runs which model class.

Three more gotchas before you commit a routing config

Version floors. Model aliases resolve against what your CLI supports: Opus 5 requires Claude Code v2.1.219 or later, Sonnet 5 requires v2.1.197, Opus 4.8 requires v2.1.154. An outdated install quietly resolves opus to an older Opus — same price on the 4.8/5 boundary ($5/$25 for both, per the pricing table), but not the model you specified. Run claude update before trusting any routing config, and pin with full IDs (claude-opus-5) where the exact version matters.

Org allowlists outrank your frontmatter. If your organization sets availableModels, subagent routing is checked against it like every other surface — the docs list subagent frontmatter, the Agent tool’s model parameter, and CLAUDE_CODE_SUBAGENT_MODEL all under allowlist enforcement, and family aliases resolve to the newest version the list permits. Your model: opus line means “the newest Opus my admin allows,” which may not be Opus 5.

Thinking tokens ride the routing too. Extended thinking bills as output tokens, and output is where the per-model gap is widest ($5 vs $25 vs $50 per million). Routing a chatty reasoning task to Haiku saves more than the input math alone suggests; conversely, an Opus verify agent with a huge thinking budget can dominate your bill. For mechanical stages, a lower effort level or a MAX_THINKING_TOKENS cap stacks with model routing rather than replacing it.

The meta-point: routing is a config-file decision now, which means it belongs in your repo like any other config. A .claude/agents/ directory with deliberate model: lines is a team-wide cost policy that survives every session — worth five minutes on any team where Claude Code is the daily driver, and worth revisiting if you’ve already built the power-user setup but left every agent on inherit.

FAQ

Does CLAUDE_CODE_SUBAGENT_MODEL override an agent’s model: frontmatter? Yes. The documented resolution order is env var first, then the per-invocation model parameter, then frontmatter, then the main conversation’s model. Set the env var only when you mean “all subagents, no exceptions.”

What happens if I don’t set a model on a subagent? The frontmatter defaults to inherit: the subagent runs on the same model as your main conversation, at that model’s full price. On an Opus 5 session, every default-routed subagent bills at $5/$25.

Is Haiku 4.5 actually good enough for scanning work? For read-grep-summarize tasks with a tight prompt and restricted tools (Read, Grep, Glob), we haven’t found failures that Sonnet avoids. Keep generation, refactoring, and anything requiring judgment on Sonnet 5 or above — that’s the split the pricing table is built for.

Do subscription users (Pro/Max) care about any of this? Less directly — plan usage is metered against seat allowances rather than per-token dollars. But subagent tokens still draw down the same allowance, and /usage attributes consumption to subagents, so routing scanners to Haiku stretches a weekly limit the same way it stretches an API budget.

Can I route subagents to a local model and keep the main session on the cloud API? Yes — that’s the hybrid pattern: CLAUDE_CODE_SUBAGENT_MODEL pointed at a local model via your local server’s endpoint, main session untouched. Details and the context-window caveats are in the subagents-on-Ollama guide.

Sources

• Model configuration — Claude Code docs (aliases, ANTHROPIC_DEFAULT_*_MODEL, version requirements, allowlists)
• Subagents — Claude Code docs (model frontmatter, resolution order)
• Environment variables — Claude Code docs (CLAUDE_CODE_SUBAGENT_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL and background functionality, ANTHROPIC_SMALL_FAST_MODEL deprecation)
• Manage costs effectively — Claude Code docs (background token usage, /usage breakdown, model-per-task guidance, enterprise spend figures)
• Pricing — Anthropic API docs (per-model rates, Sonnet 5 permanent pricing note, cache multipliers, tokenizer note)

Last updated August 26, 2026. Pricing and features change frequently; verify current state on the official pages before committing a budget to them.