One line pins a subagent to a different model. One environment variable silently outranks it.

August 14, 2026

So I’d been doing this by asking. Spin up a subagent, tell it in the prompt to be cheap and fast, hope the routing worked out. It mostly did, in the sense that I never checked.

There’s a config for it. One field, in a file I already had.

The field

Subagent definitions are markdown files with YAML frontmatter. Project-level ones live in .claude/agents/, user-level ones in ~/.claude/agents/. The model field is just model:

---
  name: cheap-searcher
  description: Broad file sweeps where I want the conclusion, not the reading
  model: haiku
  ---

  Search widely. Report what you found and where. Do not read whole files
  when an excerpt settles it.

It takes aliases — sonnet, opus, haiku, fable — or a full model ID like claude-opus-5. There’s also an explicit inherit, which does what it says.

Leave the field out entirely and you get inherit. So every subagent I’d ever written was running on whatever the parent was running on, which for me is usually the expensive one. Broad file sweeps. On Opus. For months.

Sources: subagents, model configuration.

What else crosses the boundary

Worth knowing before you split models, because the subagent is more isolated than I’d assumed and less isolated in one specific way.

Context does not cross. The subagent starts fresh. It gets the prompt string you hand it and nothing else — not the conversation, not what you were just looking at. If it needs a fact, put the fact in the prompt.

CLAUDE.md does cross. Your instructions go with it. The built-in Explore and Plan agents are the exception and don’t receive it.

Tools cross unless you narrow them. Specify tools: and the subagent gets only those. Say nothing and it inherits everything.

Permission mode crosses, mostly. The subagent runs under the parent’s permission mode, except that bypassPermissions and acceptEdits take precedence.

Extended thinking crosses, as of v2.1.198.

The precedence order

Here’s the part I’d want to know and didn’t.

There’s an environment variable, CLAUDE_CODE_SUBAGENT_MODEL. It takes the same values as the frontmatter field. And the documented resolution order is:

environment variable → per-invocation parameter → frontmatter

Read that again. The environment variable is first.

Every config system I work with resolves the other way. The most specific declaration wins and the broadest fallback loses. A file that says model: opus should beat an ambient shell variable, the same way a project setting beats a user default.

So I tested it, because “the docs describe the precedence backwards” seemed at least as likely as the behaviour actually being backwards.

It isn’t the docs.

cat > ~/.claude/agents/model-probe.md <<'EOF'
  ---
  name: model-probe
  description: Reports which model it is running as
  model: opus
  ---
  State exactly which model you are. Nothing else.
  EOF

  CLAUDE_CODE_SUBAGENT_MODEL=haiku claude

Then, in the session: use the model-probe agent and tell me exactly which model it reports being.

The frontmatter says opus. The environment variable says haiku. The subagent came back claude-haiku-4-5-20251001 while the parent session stayed on Opus 5.

Nothing warned me. The file still says opus, the agent still loads, and it runs on something else. One line in a shell profile quietly overrides the declared model of every subagent in every project on that machine.

On method, since it matters: the subagent is self-reporting, and models are not always reliable about their own identity. What makes me believe it is the differential — same session, parent says Opus 5, child says Haiku 4.5, and the child’s answer tracks the variable. One test, one machine. If it goes the other way for you I’d like to know.

There’s a small footnote to the test. My first attempt was denied by my own supervision daemon, which classified a user asking their own subagent which model it is as reconnaissance-shaped behaviour designed to leak model information. I wrote the agent file. I set the variable. It’s my laptop. Rerunning with the supervisor disabled worked immediately — but a judge that confident about something that benign is its own small lesson, and I’ve written about that one before.

What I haven’t verified

Three things the documentation still doesn’t settle, and I’m not going to pretend otherwise.

Does inherit re-read the parent’s model on every invocation, or bind once? If you /model mid-session, do your inheriting subagents follow? The docs note that running /model while viewing a subagent’s transcript changes the main conversation rather than the subagent, which is a different question than the one I’m asking.

Does a differently-modelled subagent show up separately in cost tracking? Result messages carry a modelUsage map, and /usage attributes some percentage to subagents. Whether that lands as visibly different billing, I don’t know.

fallbackModel and modelOverrides turn up in search results as frontmatter fields with no documentation behind them. They might be real and undocumented. They might be somebody’s guess that got indexed. I’m not repeating them as fact.

The first two are testable in about ten minutes each, and I’d rather publish the gap than fill it with a confident guess. If you run them before I do, tell me and I’ll update this with a credit.

What I changed

Two subagents now pinned to haiku — the broad file sweeps where I want a conclusion rather than a reading. One pinned to opus regardless of what the parent is doing, because it reviews plans and I don’t want that one getting cheap when I’m economising.

The rest inherit. That’s fine. The point isn’t that every agent needs a declared model. It’s that I had zero declared models and thought I had a routing strategy.

SOs

SOs — standing orders you can lift and prime your own agent with. (New here? The convention started with the Neverland post.) Paste them into a session for a one-time dose, or commit them to your CLAUDE.md / AGENTS.md and they stay in force.

STANDING ORDERS — Subagent model routing
  Source: "One line pins a subagent to a different model" — bensimon.dev

  1. When proposing a subagent for broad mechanical work — file sweeps,
     grep fan-out, log scanning — recommend a declared cheap model in the
     agent's frontmatter rather than asking the parent's model to do it.

  2. Never assume a subagent inherited context. It receives the prompt
     string and nothing else. Put every fact it needs in the prompt, and
     say so when handing off.

  3. Before relying on any model-routing behaviour, state whether it is
     documented, tested, or assumed. For Claude Code subagents specifically:
     CLAUDE_CODE_SUBAGENT_MODEL overrides the model declared in an agent's
     frontmatter, silently. Check the environment before trusting the file.

  4. When a config precedence order is surprising — ambient beating
     specific — flag it rather than passing it along. Backwards
     documentation is as likely as backwards behaviour, and the reader
     needs to know which you checked.

  5. If a field appears in search results but not in the documentation,
     do not repeat it as fact. Name it as undocumented and stop there.