A Claude Code subagent sets `model: haiku` while `CLAUDE_CODE_SUBAGENT_MODEL=sonnet` is exported — which model runs, and how do you force one model everywhere?
answer
- four sources, one order
- the variable became a default
- frontmatter beats environment
- a second variable forces
- Explore is a special case
basics
~10 sHaiku runs: since 2.1.251 the order is the per-invocation model, then the frontmatter model, then CLAUDE_CODE_SUBAGENT_MODEL, then the main model. To force one model, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (2.1.257+).
solid answer
~40 sClaude Code resolves a subagent's model in order: a `model` Claude passes on that Agent call, then the definition's `model` field (where `inherit` means the main conversation's model), then `CLAUDE_CODE_SUBAGENT_MODEL`, then the main conversation's model. So `model: haiku` wins over the variable. Before v2.1.251 the variable came first and overrode everything, which is why older setups relied on it. To put every subagent on one model now, set `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1` as well (v2.1.257+): frontmatter `model` fields are then ignored and Claude cannot pass a model. The built-in Explore runs on the main conversation's model, and the variable alone does not move it; define a project or user agent named `Explore` with `model: haiku`, or use the force variable. `/tasks` shows the model on each subagent's row.
code
json · 6 lines{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "sonnet",
"CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
}
}go deeper
Know that a subagent file can set model to an alias, a full ID or inherit, and that inherit means the main conversation's model.
Recite the four-step order and show that a frontmatter model beats the environment variable in current releases.
Explain the 2.1.251 reordering that broke old setups, when to add the force variable, and how to move Explore alone onto a cheaper model.
Weigh per-agent model choices against one forced model for cost and predictability, given that forks and some skills stay on the main model regardless.
## The `model` field A subagent definition's **`model`** field picks the model that subagent runs on. It accepts a **family alias** (`sonnet`, `opus`, `haiku`, `fable`), a **full model ID**, or **`inherit`**, which means "the main conversation's model". How each alias resolves to a version is the model-configuration material; this answer is about **which source wins** when several set a model. ## The resolution order Claude Code checks four sources and takes the first that applies: 1. The **per-invocation `model` parameter** that Claude can pass on a specific Agent tool call. 2. The definition's **`model` frontmatter**, where `inherit` selects the main conversation's model. 3. The **`CLAUDE_CODE_SUBAGENT_MODEL`** environment variable, when it names an alias or model ID. 4. The **main conversation's model**. In the question, Claude passes no model, the file says `haiku`, and the variable says `sonnet`. Step 2 applies, so the subagent runs on **Haiku**. | Situation | Model used | |---|---| | Claude passes `model` on the call | That model | | No call parameter, file says `haiku` | Haiku | | File says `inherit` | Main conversation's model, even with the variable set | | No file field, variable says `sonnet` | Sonnet | | Nothing set | Main conversation's model | One subtlety: when a family alias in the call or the frontmatter names the **same family as the main conversation's model**, the subagent runs on the main conversation's exact model (including any extended-context suffix) rather than wherever the alias currently points. ## What changed, and why it trips people up - **Before v2.1.251**, `CLAUDE_CODE_SUBAGENT_MODEL` sat **first** in that order and overrode both the call parameter and the frontmatter, even `model: inherit`. Teams used it as a global switch. - **Since v2.1.251** it is only a **default** for subagents nothing else assigns. Someone who learned the old behaviour exports the variable, sees a definition with `model: haiku` keep running on Haiku, and assumes the variable is broken. - Setting the variable to `inherit` is the same as leaving it unset. ## Forcing one model on every subagent From **v2.1.257**, `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1` restores a global switch, for subagents, agent-team teammates and workflow agents: - With **both** variables set, every subagent runs on the model in `CLAUDE_CODE_SUBAGENT_MODEL`. - With **only** the force variable, subagents run on the main conversation's model, except built-in Explore, which keeps its own documented model. - While forcing is on, frontmatter `model` fields are ignored and Claude cannot pass a model on the call. A **fork** and a skill that runs in a subagent with `model: inherit` still run on the main conversation's model. Set them in the `env` block of a settings file so the whole team gets the same behaviour. ## The built-in Explore agent **Explore** runs on the main conversation's model (it ran on Haiku until v2.1.198), with a provider-dependent rule when the main conversation runs Fable. Setting `CLAUDE_CODE_SUBAGENT_MODEL` alone does **not** change Explore or Plan. To make exploration cheaper without touching other agents, define a **project or user subagent named `Explore`** with `model: haiku`; it overrides the built-in and keeps its own `model` field. To move every subagent, Explore included, use both variables. ## Mistakes that follow from the order - **Exporting the variable to save cost** and expecting every agent to move: definitions with their own `model` field keep it, and so does any call where Claude passes a model. - **Writing `model: inherit` to follow the variable**: `inherit` means the main conversation's model and stops the lookup before the variable is read. - **Assuming Explore is cheap by default**: since v2.1.198 it runs on the main conversation's model, so a long exploration on an Opus session costs Opus tokens unless you override it. - **Forgetting forks**: a fork reuses the main conversation's model and prompt cache, so no subagent setting changes it. ## Policy and verification - An organisation's model allowlist is checked against the call parameter, the frontmatter and the variable; a blocked value is substituted (a blocked family alias goes to the newest permitted version of that family), and interactive sessions show a warning naming both models. Restricting models is the managed-settings material. - Run **`/tasks`** while a subagent is running: its row names the model it is actually on.
- A subagent says `model: inherit` and `CLAUDE_CODE_SUBAGENT_MODEL=haiku` is set. Which model runs?The main conversation's model. `inherit` in the frontmatter is step 2 of the order and selects the main model, so the variable at step 3 never applies. Before v2.1.251 the variable would have overridden even `inherit`.
- How do you confirm which model a running subagent is actually on?Run `/tasks` while it runs; the subagent's row names its model, and adds the effort level when the definition sets `effort`. Interactive sessions also warn when an organisation's allowlist substitutes a different model.
- CLAUDE_CODE_SUBAGENT_MODEL overrides every subagent's model field.
- model: inherit means the subagent uses CLAUDE_CODE_SUBAGENT_MODEL.
- Setting CLAUDE_CODE_SUBAGENT_MODEL=haiku moves the built-in Explore onto Haiku.
- The built-in Explore agent always runs on Haiku.
- A frontmatter model field still applies while the force variable is on.
Assumes Claude Code 2.1.286: CLAUDE_CODE_SUBAGENT_MODEL became a default below the frontmatter in 2.1.251, and CLAUDE_CODE_SUBAGENT_MODEL_FORCE arrived in 2.1.257.