Skip to content
← Back to release · 2.1.257
New features / v2.1.257

Force a consistent subagent model

CHANGELOG · original

Added CLAUDE_CODE_SUBAGENT_MODEL_FORCE to apply CLAUDE_CODE_SUBAGENT_MODEL (or the main model) to every subagent, ignoring per-spawn and agent-definition model overrides
Open official changelog ↗

Documentation

Documentation excerpt

Run every subagent on one model

To apply one model to every subagent, teammate, and workflow agent, set CLAUDE_CODE_SUBAGENT_MODEL to that model and CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1. Requires Claude Code v2.1.257 or later.

For example, to run every subagent on Haiku, set both variables in the env block of a settings file:

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

To check that the setting took effect, run /tasks while a subagent is running. The subagent's row shows the model it runs on.

While CLAUDE_CODE_SUBAGENT_MODEL_FORCE is on, Claude Code ignores the model field in subagent definitions, and Claude can't pass a model when it starts a subagent. The following subagents still run on their parent conversation's model:

If you set only CLAUDE_CODE_SUBAGENT_MODEL_FORCE, subagents run on the main conversation's model, except that the built-in Explore subagent runs on the model listed for it under Built-in subagents.

Documentation snapshot · 2026-11-20

Change details