Skip to main content

​
Model Tier Routing

Classify task complexity before every task and every agent spawn, then pick the cheapest model tier that can do the job correctly. No silent defaults — an unclassified task defaults to over- or under-spending. This page is the authoritative pull target for the routing rule. The always-loaded rules files (mistakes/global-prevention-rules.md, ~/.claude/rules/model-routing.md) carry only a one-line pointer here, so the table has a single source of truth.

​
Tier selection

​
Escalation and downgrade

  • Escalate to Opus if any hold: irreversible side effects, deep multi-domain reasoning, failure is hard to detect, or the output becomes downstream ground truth for other work.
  • Downgrade to Haiku only if all hold: bounded, single-step, mechanical, no judgment needed.
  • Sonnet flag: if a task warrants Opus but the session is running Sonnet, say so explicitly and let the user decide — do not silently proceed at the lower tier.
User-specified tiers always override this table.

​
Missing model fallback

When a configured model is unavailable (rate-limited, retired, provider outage, wrong id), do not silently cross to a different provider’s model. Demote or promote to the closest model of the same provider first: Rules:
  • Prefer same-provider closest-tier over cross-provider same-tier. Provider tuning matters more than tier label.
  • Never silently fall back to a model the user explicitly removed from their config.
  • Log the fallback so the run is auditable (task_progress: model fallback X → Y, reason: missing).
  • If the fallback model is below the task’s minimum tier, halt for human direction instead of proceeding.
This rule is what keeps difficulty-tier routing honest: a “high” task should not silently become a “low” run because one model id drifted.

​
Agent spawning

Always set the model parameter explicitly on the Agent tool. Never let it default — defaults are blocked in code repositories.
Translate a chosen tier into a subagent_type:

​
Why a tier discipline pays off

The wshobson finding: Opus achieves ~65% fewer tokens on complex tasks, often offsetting its higher per-token rate — so escalating a genuinely hard task can be cheaper, not just better. The inverse holds for trivial work: routing boilerplate to Opus burns budget for no quality gain. The discipline is bidirectional.