CLAUDE_CODE_SUBAGENT_MODEL routing of subagents to a small local model
Parent: Mac local LLMs: Agent clients, context and compaction · Published reference · snapshot 2026-10-05
↓ Facts as markdownall context files
Before v2.1.251 `CLAUDE_CODE_SUBAGENT_MODEL` came first in the order and overrode the per-invocation parameter and the frontmatter, including `model: inherit`.
These notes link each claim to its source. A source may be a research report hosted on this site rather than the primary document. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Facts
- Before v2.1.251 `CLAUDE_CODE_SUBAGENT_MODEL` came first in the order and overrode the per-invocation parameter and the frontmatter, including `model: inherit`. [source]
- Setting the variable to `inherit` is the same as leaving it unset; before v2.1.196 that value forced subagents onto the main conversation's model. [source]
- Setting `CLAUDE_CODE_SUBAGENT_MODEL` by itself does not change the model that the built-in Explore and Plan subagents run on. [source]
- Under a Claude subscription, a Console account or an LLM gateway reached through `ANTHROPIC_BASE_URL`, the built-in Explore subagent runs on the model the `opus` alias resolves to. [source]
- A user or project subagent named `Explore` overrides the built-in and keeps its own `model` field, so `model: haiku` in it moves exploration to a cheaper model. [source]
- With `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`, Claude Code ignores the `model` field in subagent definitions and Claude cannot pass a model when it starts a subagent. [source]
- If only `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is set, subagents run on the main conversation's model, except that built-in Explore runs on the model listed for it under built-in subagents. [source]
- A fork and a skill that runs in a subagent with `model: inherit` stay on the main conversation's model even while force is on. [source]
- An alias in `CLAUDE_CODE_SUBAGENT_MODEL` always resolves to the version the alias points to, even when it names the main model's family. [source]
- A family alias such as `opus` in the per-invocation parameter or the frontmatter resolves to the main conversation's exact model, including a `[1m]` suffix, when the main model belongs to that family. [source]
- Claude Code checks the per-invocation, frontmatter and variable values against the organisation's `availableModels`; a blocked family alias runs on the newest allowed version of the family, other blocked values run on the inherited model, and an interactive session shows a warning naming both models. [source]
- `/tasks` shows the model each running subagent uses, from v2.1.242, so it is the check that a small local model took effect. [source]
- When a configured fallback model chain covers a subagent's failure, Claude Code moves that subagent to the first model in the chain that accepts the request, from v2.1.247, and leaves the session model unchanged. [source]
- The variable accepts an alias such as `haiku` or a full model name; Claude Code does not check a model set by `--model`, `ANTHROPIC_MODEL` or the `model` setting up front, and a mistyped value fails at request time. [source]
Corrections and disagreements
- This CONTRADICTS the unqualified wording in local-router-policy-keyed-on-x-claude-code-reque.md that the variable sets the default for subagents with a short override note: the full order is per-invocation `model`, then definition `model` frontmatter (`inherit` selects the main model), then `CLAUDE_CODE_SUBAGENT_MODEL`, then the main conversation's model. [source]
Children
- No children recorded.