Put a Cost Ceiling on Every Subagent in Your Workflow: CLAUDE_CODE_SUBAGENT_MODEL_FORCE

TL;DR: Set CLAUDE_CODE_SUBAGENT_MODEL=haiku and CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 to cap every subagent, teammate, and workflow agent in your session to one model — even if their definitions request Opus. New in v2.1.257.

When you fan out work across 10 subagents, each one inherits your main session's model by default. If that's Opus 5, a 10-agent workflow burns 10 times the context at Opus rates. Two environment variables give you a ceiling.

What each variable does:

• CLAUDE_CODE_SUBAGENT_MODEL sets the fallback model for subagents when nothing else specifies one — but it does NOT override agent definition frontmatter or the built-in Explore and Plan agents.
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 overrides everything: per-invocation model parameters, agent definition frontmatter, and the built-in Explore and Plan agents.

Add both to .claude/settings.json for project-wide enforcement:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-4-5-20251001",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Or set per-session in your shell:

export CLAUDE_CODE_SUBAGENT_MODEL=sonnet
export CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1
claude

Model resolution order without FORCE: per-invocation model param → agent definition frontmatter → CLAUDE_CODE_SUBAGENT_MODEL → main session model.

With FORCE=1: CLAUDE_CODE_SUBAGENT_MODEL wins for everything above — except forks and skills with model: inherit, which still run on the main conversation's model by design (you don't control the skills you didn't write).

Real limits. Forcing Explore and Plan to Haiku degrades their quality on complex research tasks — those built-in agents are tuned for thoroughness. If your workflow's search or planning quality drops, set CLAUDE_CODE_SUBAGENT_MODEL to Sonnet instead, or remove FORCE and pin specific agent definitions individually via their frontmatter. The env var covers the entire session; there's no per-workflow override within a single session.

Sources: Claude Code v2.1.257 changelog — code.claude.com · Sub-agent model configuration — code.claude.com · Claude Code Subagents: A 2026 Practical Guide — Tembo.io