Guide

Per-subagent model control in Claude Code: let the cheap model grind, the expensive one judge

Andrew Mercer July 30, 2026 · 8 min read

Put a model: key in a subagent's YAML frontmatter and you decide, per subagent, which model does that leg of the work. The useful shape is a cheap model doing the wide, mechanical fan-out and one expensive model reading the summaries and making the decision. At list prices, an eight-worker exploration costing $3.00 entirely on Opus 5 costs $0.80 with Haiku 4.5 workers and an Opus 5 judge. And because a named subagent runs its own conversation with its own cache, doing it this way does not invalidate the parent session's prompt cache — which is exactly what /model mid-session does.

How the model field works

A subagent is a Markdown file with YAML frontmatter — in .claude/agents/ for a project, ~/.claude/agents/ for you personally. Only name and description are required; model is optional and defaults to inherit.

---
name: explore
description: Search the repo and report findings. Read-only.
model: haiku
tools: Read, Grep, Glob
---

You are a fast, literal explorer. Report file paths, line numbers,
and exact snippets. Do not propose changes. Do not speculate.

The model value takes an alias (sonnet, opus, haiku, fable), a full model ID such as claude-opus-5 — the same values --model accepts — or inherit. On a third-party provider, prefer a full model ID unless you have confirmed that the alias resolves there.

Four things can set a subagent's model, resolving highest-priority first:

the CLAUDE_CODE_SUBAGENT_MODEL environment variable;
the per-invocation model parameter Claude passes on the Agent tool call;
the subagent definition's model frontmatter;
the main conversation's model.

Treat (1) and (3) as your real controls. There is no documented user-facing syntax for setting (2) from a prompt, so "ask Claude to run this one on Haiku" is not a guarantee. One version note: since Claude Code v2.1.196, CLAUDE_CODE_SUBAGENT_MODEL=inherit is equivalent to leaving it unset and resolution continues down the chain. In earlier versions it forced every subagent onto the main model and ignored both the per-invocation parameter and your frontmatter.

Scope order for the definitions themselves, highest first: managed settings, the --agents CLI JSON, .claude/agents/, ~/.claude/agents/, then plugin agents/ directories. The /agents wizard was removed in v2.1.198, so you write the file yourself or ask Claude to. What a subagent is is covered in our subagents explainer; this post is only about the model dial.

Why the isolated context is the whole trick

Every non-fork subagent starts with a fresh context window. It does not see the parent conversation, the skills the parent already invoked, or the files the parent already read. It gets its own system prompt plus environment details, the delegation message Claude wrote for it, the CLAUDE.md hierarchy, a git-status snapshot, any preloaded skills, and — when it can message other agents — a roster of its siblings. The built-in Explore and Plan agents are the exception: they skip CLAUDE.md and git status. Only the final summary comes back to the parent — tool calls and intermediate output stay in the subagent's own transcript.

That isolation is what makes per-subagent models cache-safe. Anthropic's caching docs put it plainly: a subagent "starts its own conversation with its own system prompt and tool set, separate from the parent's. It builds its own cache… The parent's cache is unaffected." From the parent's side the call and result simply append, leaving its prefix intact.

Compare the obvious alternative. Switching the main conversation's model with /model throws away every cache hit, because each model has its own cache and the model is part of the cache key — the next request re-reads the entire history at full input price. Same for effort: each effort level has its own cache for the same model, and changing it mid-session recomputes the whole request, which is why Claude Code confirms first. The subagent effort frontmatter field is the same escape hatch applied to effort instead of model. For the mid-session tradeoff directly, see switching models mid-session.

The deliberate exception is a fork (/subtask). A fork inherits the parent's exact system prompt, tools, model and full message history, so its first request reads the parent's cache — cheaper than a fresh subagent, but it gives up input isolation and cannot take a different model. The rule of thumb: named subagent = separate cache and its own model; fork = shared cache and the same model.

The cost math

List prices per million tokens on the Claude API, standard tier, as of July 30, 2026: Haiku 4.5 $1 in / $5 out; Sonnet 5 $3 / $15 (introductory $2 / $10 through August 31, 2026); Opus 5 and Opus 4.8 $5 / $25; Fable 5 $10 / $50.

Opus 5 costs exactly 5x Haiku 4.5 per token on both sides — not the 15x figure still repeated in 2026 blog posts. That was true against the deprecated Opus 4.1 at $15/$75; against Opus 5 the real ratio is 5x, and Sonnet 5 is 3x Haiku at standard pricing or 2x at the introductory rate. Plan against 5x.

A worked example, not a benchmark: eight exploration subagents, each consuming 50K input and producing 5K output, so 400K in / 40K out across the fan-out. In the mixed row, one Opus 5 judge then reads the eight summaries at 20K in / 4K out. No caching assumed.

Fan-out configuration	Input cost	Output cost	Total
8 workers, all Opus 5	$2.00	$1.00	$3.00
8 workers, all Sonnet 5 (standard)	$1.20	$0.60	$1.80
8 workers, all Haiku 4.5	$0.40	$0.20	$0.60
8 Haiku 4.5 workers + 1 Opus 5 judge	$0.50	$0.30	$0.80
Backgrind	Doesn't change the meter — it's a window over the CLI you already run. Each agent session gets a tab, and it pings you when that agent needs a decision or finishes.

The mixed row is 3.75x cheaper than the all-Opus one, a 73% saving, and the expensive model still makes the actual judgement. Run your own numbers with the agent cost calculator or check current rates in the model pricing tracker.

One caveat on the whole line of reasoning. A consulting firm that sells agent work published its own logging-proxy numbers claiming Claude Code fan-outs consumed 2.6x to 5.9x as many input tokens as the same work done sequentially, and were never faster in its tests. Those are vendor-reported figures from a single blog post that nobody has reproduced, so weigh them accordingly — but respect the direction. A mixed fan-out is cheaper per token than an all-frontier one; a fan-out that didn't need to happen is still more expensive than not fanning out.

Five failure modes

The context window shrinks with the model. A subagent's context window is sized by its own model, not the parent's. Haiku 4.5 has a 200K window and 64K max output; Opus 5, Opus 4.8, Sonnet 5 and Fable 5 all have 1M and 128K. Point a Haiku worker at a large log file or a wide repo scan and it hits a window 5x smaller than the session it came from. Scope cheap workers narrowly.
Allowlist mismatches fail silently. Claude Code checks the env var, the per-invocation parameter and the frontmatter model against your organization's availableModels allowlist. A value resolving to an excluded model is skipped with no error and the subagent runs on the inherited model — the cheap worker quietly becomes an expensive one. If your savings never materialise, check this first.
Haiku 4.5 doesn't do effort. It uses the older thinking.type: "enabled" mode and is not among the models supporting the effort parameter (Fable 5, Mythos 5, Opus 5, Opus 4.8/4.7/4.6/4.5, Sonnet 5, Sonnet 4.6). Claude Code's docs only say "available levels depend on the model," so what an effort: low on a Haiku subagent does is undocumented — treat it as a no-op at best.
You can't turn thinking off per subagent. Subagents inherit the main conversation's extended-thinking configuration, and there is no per-subagent thinking setting. You can pick a cheap model for a worker but not independently make it think less.
There are hard fan-out ceilings. 200 subagents per session by default (CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), 20 running concurrently (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), and a nesting depth of three layers below the main conversation — at which point the Agent tool is withheld and the subagent does the work itself. Those are the only numbers Anthropic documents; the widely repeated "3–5 concurrent is the sweet spot" is folklore.

Forcing cheap exploration

A detail that catches people out: the built-in Explore agent no longer hard-codes Haiku. Since v2.1.198 it inherits the main conversation's model, capped at Opus on the Claude API. If you assumed exploration was cheap by default, it isn't any more.

To get it back, define your own subagent named Explore with model: haiku in .claude/agents/; a user or project subagent overrides the built-in of the same name. For a whole session on one agent, use claude --agent <name> or put {"agent": "<name>"} in .claude/settings.json.

Then verify against /usage or a day of API billing. The failure modes above are all quiet ones — nothing errors when your cheap tier silently isn't cheap. If you're doing this because you keep hitting plan ceilings rather than an API bill, the mechanics are in Claude Code usage limits.

Frequently asked questions

How do I give a Claude Code subagent a different model?

Add a model: key to the YAML frontmatter of the subagent's Markdown file in .claude/agents/ or ~/.claude/agents/. It accepts an alias (sonnet, opus, haiku, fable), a full model ID like claude-opus-5, or inherit. Only name and description are required fields; when model is omitted it defaults to inherit, so the subagent runs on whatever the main conversation is running.

Does running a subagent on a different model break my prompt cache?

No, and that is the main reason to do it this way. A named subagent starts its own conversation with its own system prompt and tool set, so it builds its own cache and leaves the parent's prefix intact — the parent only sees the tool call and the returned summary appended. Switching the main conversation with /model does break it: the model is part of the cache key, so the next request reads the whole history with no cache hits.

How much does a mixed fan-out actually save?

At list prices, an eight-worker fan-out at 50K input and 5K output each costs $3.00 entirely on Opus 5, $1.80 on Sonnet 5 at standard pricing, or $0.80 with Haiku 4.5 workers plus one Opus 5 judge reading the eight summaries. That is 3.75x cheaper than the all-Opus version — a 73% saving — with the expensive model still making the call. Opus 5 is 5x Haiku 4.5 per token, not the 15x figure that circulates from the deprecated Opus 4.1 era.

What is the most common way per-subagent models silently fail?

The organization model allowlist. Claude Code checks the environment variable, the per-invocation parameter, and the frontmatter model against availableModels, and a value that resolves to an excluded model is skipped silently — the subagent runs on the inherited model with no error. Your cheap Haiku worker quietly becomes an expensive Opus worker and the only evidence is the bill.

Where Backgrind fits

Backgrind is not a model and not an agent — it is a desktop overlay for macOS and Windows that PTY-wraps the CLI you already run (Claude Code, Cursor, Codex, OpenCode, or a managed endpoint). It stays on top of your other windows, including games running in borderless fullscreen (not exclusive fullscreen), and pings you only when the agent needs a decision or finishes. In BYO-CLI mode your agent's content never touches our servers; Live mode on Plus and Pro lets you answer those prompts from a phone.

The connection to this post is the part fan-outs are bad at: knowing when to look. A mixed fan-out spends most of its wall-clock time with nothing for you to do, then needs you for thirty seconds. If you want several different models on one hard question rather than one model spread across subagents, the Fusion council runs your own CLIs in parallel and returns a single verdict, pinging you only on a split or a low-confidence answer. Either way the principle holds: escalate deliberately, not by default.

Sources

Frontmatter fields, model resolution order, context sizing, scope order, built-in agents and the subagent limits: Anthropic — subagents. Cache behaviour for subagents, forks, model switches and effort changes: prompt caching. Environment variables and allowlist behaviour: model configuration and managing costs. List prices and cache multipliers: model pricing. Context windows and max output per model: models overview and context windows. Effort-parameter model support: effort. The fan-out token-overhead claim (vendor-reported by a firm selling agent work, not independently reproduced): Systima — the subagent tax. Additional confirmation of the frontmatter model field: Tembo — Claude Code subagents. All cost figures in the table are arithmetic on list prices, not measured runs.