CLAUDE_CODE_SUBAGENT_MODEL_FORCE Explained

One environment variable, every subagent

Claude Code has always let a subagent's own definition or a spawn prompt choose its model, which is exactly what you want when a code-review subagent should run on a strong model and a file-listing subagent shouldn't. That flexibility becomes a liability the moment you're trying to hold a session, or a whole team, to a fixed budget: individual subagent definitions and ad hoc spawn prompts can still reach for an expensive model regardless of what you intended.

CLAUDE_CODE_SUBAGENT_MODEL_FORCE, added in Claude Code v2.1.257 (1 September 2026), closes that gap. Set it to 1 and Claude Code runs every subagent, every agent team teammate, and every workflow agent on one model, ignoring per-spawn requests and agent-definition overrides entirely.

What it overrides, and what "one model" means

Set the variable alongside CLAUDE_CODE_SUBAGENT_MODEL, which names the model to force:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku
export CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1

With both set, every subagent, teammate, and workflow agent Claude Code spawns runs on Haiku, whatever their own definition or Claude's spawn request asks for, including the built-in Explore and Plan subagents. If you set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 without setting CLAUDE_CODE_SUBAGENT_MODEL, Claude Code forces the main conversation's model instead, which still gives you one consistent model everywhere, just not necessarily the cheapest one.

Where this sits in the precedence order

Before v2.1.257, Claude Code resolved a subagent's model in this order:

1. The per-invocation model parameter Claude passes when it spawns the subagent
2. The subagent definition's own model frontmatter field, where inherit selects the main conversation's model
3. CLAUDE_CODE_SUBAGENT_MODEL, when set to a model alias or full model ID
4. The main conversation's model

That order meant CLAUDE_CODE_SUBAGENT_MODEL was a fallback, useful for subagents that didn't specify anything, but powerless against a subagent definition that pinned model: opus or a spawn prompt that asked for a specific model by name. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 collapses that whole order: CLAUDE_CODE_SUBAGENT_MODEL (or the main conversation's model, unset) wins outright, and steps 1 and 2 above stop being consulted for the model choice.

Worth knowing if you're comparing against older documentation or your own memory of the setting: before v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL itself used to override both the per-invocation model and the definition's model field, including model: inherit. That behaviour moved to v2.1.257's dedicated _FORCE flag; on current versions, setting CLAUDE_CODE_SUBAGENT_MODEL alone no longer overrides anything, it's strictly a fallback until you add _FORCE.

Quick reference

Why teams reach for this

The obvious use is cost control, but the more common trigger in practice is consistency during a review or audit pass. If you're asking Claude Code to fan out a dozen subagents across a large repository, code review, dependency audit, or a documentation sweep, you often want every one of them reasoning at the same capability level so results are comparable to each other. A subagent definition written months ago with model: sonnet baked in shouldn't quietly produce a weaker pass than one written last week with no model field at all, just because of when the file was authored. Forcing one model for the run removes that inconsistency without editing every definition in the repository.

The inverse case matters too: a security-critical review where you want every subagent, including ones whose definitions default to a cheaper model for routine work, to run on your strongest available model for this one pass:

CLAUDE_CODE_SUBAGENT_MODEL=opus \
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 \
claude -p "run the pre-release security review across every changed file"

Neither direction, cheaper-for-cost or stronger-for-thoroughness, was reliably possible before v2.1.257 if even one subagent definition in play specified its own model. The per-invocation parameter and the definition's frontmatter both outranked CLAUDE_CODE_SUBAGENT_MODEL, so the old variable only ever caught subagents that hadn't opinionated about their own model in the first place.

Agent teams read the same variable

Agent teams teammates resolve their model through a near-identical chain: your spawn prompt naming a model for that teammate, then a subagent definition's model field for a teammate spawned from one, then CLAUDE_CODE_SUBAGENT_MODEL when it's set to anything other than inherit, then the team lead's current model. CLAUDE_CODE_SUBAGENT_MODEL_FORCE applies to teammates exactly the same way it applies to subagents: set it, and every teammate runs on the forced model regardless of what the spawn prompt or definition requested.

Workflow agents, the agents a Workflow script spawns, are covered too. If you're running a workflow that fans out to a dozen agents and each one has its own model setting in the script, CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 overrides all of them the same way.

What still escapes the force

Two things keep running on the main conversation's model no matter what you set:

• A forked subagent. Whether started with /subtask or spawned by Claude as subagent_type: 'fork', a fork inherits the entire parent conversation, including its model, by design. Forcing a different model onto a fork would break the prompt-cache reuse that makes forking worth using in the first place, so it's excluded.
• A skill that runs in a subagent with model: inherit. Same logic: inherit is an explicit request to match the parent, and the force flag doesn't override that specific case.

Everything else, including the built-in Explore and Plan subagents that previously had no documented way to be pinned to a specific model, is fair game. Before this flag, Explore inherited the main conversation's model capped at Opus on the Claude API, and Plan inherited it with no cap; setting CLAUDE_CODE_SUBAGENT_MODEL by itself never changed either of them. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 is what finally lets you move both onto, say, Haiku for cost-sensitive exploration work.

How this setting's behaviour has shifted over time

CLAUDE_CODE_SUBAGENT_MODEL and its new _FORCE companion have changed shape more than once, which matters if you're reading older advice or a script someone wrote a few months ago:

• Before v2.1.196: setting CLAUDE_CODE_SUBAGENT_MODEL to inherit forced subagents onto the main conversation's model and ignored every other source.
• v2.1.196 onward: setting the variable to inherit became equivalent to leaving it unset entirely, deferring to whatever the rest of the precedence order picked.
• Before v2.1.251: CLAUDE_CODE_SUBAGENT_MODEL, when set to an actual model rather than inherit, came first in the precedence order and overrode both the per-invocation model parameter and the subagent definition's model field, including model: inherit.
• v2.1.251 onward: that override behaviour was removed. CLAUDE_CODE_SUBAGENT_MODEL dropped to a fallback, consulted only when neither a per-invocation model nor a definition's model field applies.
• v2.1.257 (1 September 2026): CLAUDE_CODE_SUBAGENT_MODEL_FORCE arrived specifically to restore that override behaviour on demand, as an explicit opt-in rather than the variable's default effect.

If a runbook or CI script from before August 2026 relies on CLAUDE_CODE_SUBAGENT_MODEL alone to pin every subagent's model, it stopped doing that in v2.1.251 and needs CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 added alongside it to behave the same way on current versions.

A worked example: capping a CI harness's spend

Say you run Claude Code headlessly in CI, and a handful of subagent definitions checked into the repo specify model: opus for thoroughness. That's fine for interactive use, but in CI you want a hard ceiling on what any single run can cost, regardless of what any individual definition asks for:

CLAUDE_CODE_SUBAGENT_MODEL=sonnet \
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 \
claude -p "run the full review checklist" --output-format json

Every subagent that checklist spawns, including any that name model: opus in their own frontmatter, runs on Sonnet instead. You don't have to edit the checked-in subagent definitions or coordinate a change across the team; the environment variable applies at the session level and wins over everything those files ask for.

Model allowlist substitution still applies

CLAUDE_CODE_SUBAGENT_MODEL_FORCE doesn't bypass your organization's availableModels allowlist. If the forced model is blocked, Claude Code substitutes: a blocked family alias like opus runs on the newest version of that family the allowlist permits, and any other blocked value, or a family with no permitted version, falls back to the subagent's inherited model instead. Claude Code shows a warning in interactive sessions naming the requested model and the one actually used, so a forced model that gets substituted doesn't fail silently.

Confirming it's working

Run /tasks during or after a session. Claude Code lists each subagent's row with the model it actually ran on, and adds the effort level when the subagent's definition or the skill it forked from sets one. This is the fastest way to confirm the force flag is taking effect, especially the first time you set it, before you trust it in an automated pipeline.

Troubleshooting

A subagent still ran on a different model. Check whether it's a fork or a skill running with model: inherit; both are explicitly excluded from the force. For anything else, confirm the variable is actually reaching the session, an environment variable set in your shell doesn't automatically propagate into a CI job or a different terminal, and check /tasks to see what model was actually used versus requested.

The forced model isn't what you expected. If your organization's availableModels allowlist blocks the model you named in CLAUDE_CODE_SUBAGENT_MODEL, Claude Code substitutes the newest permitted version of that family, or falls back to the subagent's inherited model if no version is permitted. Check the interactive warning, or /tasks, for the substitution.

Setting CLAUDE_CODE_SUBAGENT_MODEL alone doesn't seem to override anything. That's expected on v2.1.257 and later. Before v2.1.251, the variable overrode per-invocation and frontmatter models by itself; that behaviour is now gated behind CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. Without the force flag, CLAUDE_CODE_SUBAGENT_MODEL is only a fallback for subagents that don't specify a model another way.

You need this on every session without setting the variable each time. Add it to your shell profile, or set it as an env value in settings.json so it applies to every session that reads that settings file, rather than exporting it manually before each run.

Where this fits

CLAUDE_CODE_SUBAGENT_MODEL_FORCE is a cost and consistency control, not a security boundary; pair it with the classifier-level guardrails covered in auto mode's permissions tab if you're also trying to constrain what a forced-cheap subagent is allowed to do, not just which model it runs on. For the full mechanics of how subagents start, background by default, and fork, see how Claude Code's subagent forking works. For coordinating a whole team of teammates rather than a single subagent, see what Claude Code's agent teams feature does. Browse the current install paths and full feature set at getclaudeskills.com/platforms/claude-code.