Skip to main content

Which model actually runs your subagent.

Setting model: opus on a subagent isn’t the whole story. Four things compete to decide, and which one wins changed in Claude Code 2.1.251. The same unedited configuration resolved to Haiku before that release and Opus after it, and nothing in the file says which one you got.

Start with a scenario, then change anything. This page has no server and sends nothing anywhere.

Start here

Until 2.1.251, the environment variable won and the agent quietly ran on Haiku. From 2.1.251 on, the definition wins. It is the same file with the opposite answer, and there is no warning either way.

The answer

Tier 3 of 4

On 2.1.278, this subagent runs on

opus

The definition’s model: field wins.

  • Warning: Flips at 2.1.251. It resolved to haiku before that release and opus from it on. That is a silent move up to a more expensive tier, with no edit to any file.

Your configuration

CLAUDE_CODE_SUBAGENT_MODEL_FORCE
Provider group

Type a version or drag the slider. The range is 2.1.190 to 2.1.289.

Resumed subagent?

Resuming, or sending a follow-up, behaved differently before 2.1.211.

How it resolved

  1. Not applicable: No per-invocation model.
  2. Decided: The definition’s model: opus wins.
  3. Ignored: The env var haiku is only a default since 2.1.251, so it is outranked.
  4. Not applicable: The main model isn’t needed.

The same config across every version

Every other control stays put while the version changes. Darker means more expensive.

Select a segment or a flip to move the version control there.

Where the answer flips

  • haiku: Tier 1, cheapest
  • sonnet: Tier 2
  • opus: Tier 3
  • fable: Tier 4, most expensive
  • unrecognized model ID: No tier, price unknown
Change the version range

The rules are verified through 2.1.289. A longer range assumes nothing changes after that.

Check your own setup

Drop your agent folders and settings files, or paste a few commands’ output, and see which of your agents change across 2.1.251. This page has no server and sends nothing anywhere.

Loading the setup checker…

Releases that change the answer

The Source column says where each rule was verified. A rule marked “docs only” is in the documentation but not the changelog.

Each release where Claude Code changed how a subagent’s model is chosen, and whether the changelog, the documentation, or both confirm it.
VersionChangeSource
2.1.196Setting the env var to inherit became equivalent to leaving it unset. Before this release, inherit forced subagents onto the main model and ignored every other source.docs only
2.1.198Built-in Explore began inheriting the main model, capped at Opus, instead of always running on Haiku. Subagents also began inheriting the session’s extended-thinking setting.changelog + docs
2.1.211Resuming a subagent, or sending it a follow-up, keeps its per-invocation model. Before this release, it reverted to the definition’s model field or the main model. (The changelog says “the parent’s model.”)changelog + docs
2.1.222A blocked family alias resolves to the newest permitted version of that family. Before this release, it fell back to the inherited model.changelog + docs
2.1.223A warning appears when a requested subagent model is restricted and the parent model runs instead.changelog
2.1.232Subagent forking became on by default: a fork inherits the full conversation and prompt cache.changelog
2.1.243The /tasks command names the model, and the effort level, on each subagent row. This was the first way to observe the resolved model directly. The docs say 2.1.242, but the changelog has no 2.1.242 entry.changelog
2.1.251The reversal. The env var went from overriding everything to setting a default. The definition’s model: and an explicit per-spawn model now win over it.changelog + docs
2.1.257CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 arrived. It applies the env model, or the main model, to every subagent and ignores per-spawn and definition models. The exemptions for forks and model: inherit skills come from the docs.changelog + docs
2.1.284Explore stopped switching to Opus when the session runs an unrecognized model ID. It now inherits that model.changelog

Notes and what this doesn’t model

The order from 2.1.251 on

For a custom agent, the per-invocation model wins, then the definition’s model:, then CLAUDE_CODE_SUBAGENT_MODEL, then the main conversation’s model. An inherit in the definition means the main model. An env var of inherit is the same as leaving it unset.

What FORCE does

CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 arrived in 2.1.257. It applies the env model, or the main model when there isn’t one, to every subagent, and ignores per-invocation and definition models. Two things are exempt: forks, and skills running with model: inherit. FORCE alone leaves Explore on its built-in model, and the env var without FORCE doesn’t move Explore or Plan at all.

Why the built-ins aren’t ordinary

Explore, Plan, and general-purpose don’t follow the same ladder. Explore inherits the main model but is capped at Opus on a subscription, a Console account, or an LLM gateway. Plan runs on the main model. A user or project agent with the same name replaces the built-in, and from then on it’s an ordinary custom agent that keeps its own model:.

Not modelled

  • Your organization’s model allowlist. A blocked alias steps down to the newest allowed version from 2.1.222, and a warning appears from 2.1.223. This page ignores both.
  • Same-family aliases. A family alias in the per-invocation parameter or in the frontmatter that names the main conversation’s own family resolves to the main model’s exact version, including any [1m] suffix, rather than the alias’s default. An alias in the env var always resolves to the alias’s version. This page works at family granularity.
  • Extended-thinking inheritance, which began in 2.1.198.
  • Live changelog fetching. The rules are a snapshot.

Where the sources disagree

The docs say /tasks shows each subagent’s model from 2.1.242, but the changelog has no 2.1.242 entry. Its 2.1.243 entry says it. This page uses 2.1.243. For 2.1.211, the changelog says a resumed subagent reverted to “the parent’s model,” and the docs say it reverted to the definition’s model field or the main model. This page follows the docs, which are more specific.

Rules last verified 2026-10-04, against the Claude Code changelog and the subagents documentation. To see the model a subagent really ran on, run /tasks in Claude Code (2.1.243 or later).