← all features · evolve-loop explainers

Model routing

How each phase picks a CLI and model — and what happens when the pick fails.

How it works today

One resolver: llmroute.Resolve (llmroute.go:125-142) → Plan{Candidates, Triggers, Model}. CLI precedence: EVOLVE_<AGENT>_CLI > EVOLVE_CLI > profile.cli > claude-tmux; model: env > profile.model_tier_default > default.
Tier vocabulary is fast | balanced | deep (modelcatalog.CanonicalTiers) — profiles speak tiers, each CLI’s manifest model_tier_map translates to concrete models (manifest.go:89-98); legacy haiku/sonnet/opus aliases auto-migrate with a deprecation WARN. There is no "tier-1/2/3" anywhere in code.
Fallback chain fires on exits {80, 81, 85, 124, 127} (llmroute.go:58) — boot timeout, artifact timeout, unknown-prompt/quota, coreutils timeout, missing binary. 85 joined after cycle-267 (codex quota wall didn’t fail over).
Policy pins are absolute (llmroute.go:127-135): a pin bypasses env, profile, and auto-expansion; bare family names normalize to the tmux driver (cycle-378 fix).
Benches reorder, never veto: quota/boot-timeout benches demote candidates in the chain; all-benched → least-recently-benched first with a loud WARN.
The clamp (router/model_routing_clamp.go:43-110): every advisor-proposed {CLI, tier} is re-validated against allowed_clis + tier envelopes + the live catalog; below-floor tiers clamp UP; a universal floor {balanced, deep} covers the 72/91 profiles that declare no envelope (cycle-480).
Every decision is an artifact: routing-decision-N.json per decision, routing-plan.json per cycle — replayable via evolve routing.

Verified drift (queued: docs-drift-sweep) — dynamic-phase-routing.md claims the advisor defaults to haiku ("lightweight routing"); code defaults to opus/deep and the constructor comment explicitly rebuts the doc (phase_advisor.go:92-100). Same doc’s status table still says "Default: Off" vs the shipped advisory default (config.go:508); dynamic-model-routing.md’s entire body describes a never-shipped bash design behind its supersession banner.

How it got built

ADR-0022 (manifest realization), ADR-0024/0052 (advisory routing + clamps), cycle-436 (per-phase {cli,tier} plans + clamp), cycle-480 (universal envelope floor). The standing operator rule — tiers not model names, any CLI × any phase × any model must execute — is what the clamp + manifest layers implement.

Generated by /evo:explain · verified against code 2026-07-13 (file:line citations) · doc drift found during verification is queued in .evolve/inbox (docs-code-alignment-2026-07 campaign).