Claude Code subagent model: which one does a subagent run on?

The order Claude Code resolves the subagent model

This is the order in the sub-agents docs on 2026-10-19.

The order changed in v2.1.251. Before that, the environment variable came first and overrode both the per-call parameter and the frontmatter. Older guides still describe that order.

In practice, the setting closest to the call wins. What Claude passes for one call beats the agent file, and the agent file beats a session-wide variable. The main model is the last resort.

Frontmatter: inherit, alias or full id

The model field accepts the aliases sonnet, opus, haiku and fable, a full model id such as claude-opus-5-5, or inherit. Anthropic's cost page suggests model: haiku for simple subagent tasks.

---
name: log-reader
description: Reads logs and reports errors
model: haiku
---

CLAUDE_CODE_SUBAGENT_MODEL and the FORCE flag

The environment variable sets one model for every subagent that nothing else assigns. Since v2.1.257, adding CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 applies it to every subagent and overrides definitions and per-call choices. While FORCE is on, Claude cannot pass a model.

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Built-in agents: Explore, Plan, general-purpose

• Explore is read-only. Its model is the main conversation's model, with exceptions when the main model is Fable. To run it cheaper, define a subagent named Explore with model: haiku. Setting CLAUDE_CODE_SUBAGENT_MODEL alone does not change it.
• Plan is read-only and inherits the main model unless the environment variable with FORCE overrides it.
• General-purpose uses CLAUDE_CODE_SUBAGENT_MODEL if set and nothing else assigns a model. Otherwise it uses the main model.

Effort is separate from model

A subagent definition can set effort to low, medium, high, xhigh or max, and the available levels depend on the model. From v2.1.292, Claude can also pass an effort per call. The CLAUDE_CODE_EFFORT_LEVEL environment variable overrides both.

Why a subagent may still run on the parent's model

• Nothing assigns a model, so rule 4 applies.
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE is on, or the variable is set without the model you expected.
• The built-in Explore agent follows its own listed rule, not the environment variable.

People also report fallbacks that these rules do not explain. Issue #43869 says all mechanisms resolve to the parent model, and issue #100082 reports frontmatter model ignored, with 1,149 of 1,371 subagents on the parent's Opus. Both were open on 2026-10-19. They are user reports, and I make no claim about their cause.

Static choice versus per-task choice

Frontmatter and the environment variable are static: one answer for an agent or a whole session. A rename and an architecture review that go through the same agent get the same model. A PreToolUse hook can set the per-call model instead, so it can differ per task. Downshift does this on Claude Code, and in one session it was observed to take effect on two spawns.

Two limits. Downshift treats a pinned model as an explicit choice and leaves it alone, so it only routes subagents whose model is not pinned. And with FORCE on, Anthropic says Claude cannot pass a model, so I expect a rewrite not to win there. I have not tested that.

Check what actually ran

/tasks shows each subagent's model and any effort level (v2.1.242 and later). Downshift's downshift try "<task>" previews its decision before a spawn, and downshift session --tree lists the subagents of a session with their cost on Claude Code.

If the model shown is not the one you expected, walk the order from the top and stop at the first rule that applies. That rule is in charge.

Related guides

• Claude Code model routing: choosing the model per task
• Rewriting a subagent's model with a PreToolUse hook
• Claude Code token optimization: the levers, ranked by evidence
• Qual modelo cada subagente usa no Claude CodePortuguês
• Install Downshift: Claude Code, Codex and Cursor hook setup

Sources

1. Anthropic docsmeasured
   code.claude.com/docs/en/sub-agents
   model resolution order, FORCE, built-in agents, effort; the last 11,177 characters of the page were not read (fetched 2026-10-19)
2. Anthropic docsmeasured
   code.claude.com/docs/en/costs
   model: haiku for simple subagent tasks (fetched 2026-10-19)
3. GitHub issuesmeasured
   github.com/anthropics/claude-code/issues/43869
   open on 2026-10-19; user report, cause not established
4. GitHub issuesmeasured
   github.com/anthropics/claude-code/issues/100082
   open on 2026-10-19; user report, cause not established
5. Downshift repomeasured
   docs/guides/subagents.md
   a subagent is routable only when its model is not pinned
6. Downshift repomeasured
   docs/evidence/claude-code-rewrite-honored-2026-10-06.md
   rewrite observed, one session, two spawns
7. Downshift CLI outputmeasured
   downshift try and downshift dci output, captured 2026-10-19 (reproduce with the commands shown)
   routing decisions