---
name: model-routing-patterns
description: "Multi-model pipelines (Haiku/Sonnet/Opus): cost routing, escalation, fallback chains. Triggers: model routing, Haiku, Sonnet, Opus, escalation, fallback chain."
effort: medium
user-invocable: false
allowed-tools: Read
---

# Model Routing Patterns

Three Claude tiers. Using Opus for everything is 10-40x more expensive than it needs to be. Using Haiku for everything loses accuracy on hard tasks. The craft is routing.

## Model Characteristics (2026)

| Model | $/1M in·out | Cost (rel.) | Strengths | When |
|-------|-------------|-------------|-----------|------|
| Haiku 4.5 | $1 / $5 | 1x | Classification, extraction, simple tools, moderation | Bulk processing, triage, labels |
| Sonnet 5 | $3 / $15 | ~3x | General coding, reasoning, most agent tasks | Default workhorse |
| Opus 4.8 | $5 / $25 | ~5x | Complex reasoning, orchestration, architecture, large context | Hard, rare, high-stakes |
| Fable 5 | $10 / $50 | ~10x | Most demanding long-horizon agentic work | Only when explicitly chosen |

Prices are per 1M tokens; ratios are approximate and shift between releases. Re-check pricing before committing a production path.

> **Fable 5 is not the default "best model".** Its price sits above Opus-tier, and Opus 4.8 is state-of-the-art on planning/orchestration at half the input and output cost. Reach for Fable 5 only when the user explicitly asks for it or a benchmarked task genuinely needs it — for "use the strongest model", the target is `claude-opus-4-8`.

## Effort — the cheaper lever before swapping models

On Fable 5 / Opus 4.8 / Sonnet 5, `output_config.effort` (`low` | `medium` | `high` | `xhigh` | `max`) controls thinking depth and token spend **without changing the model** — so it does not invalidate the prompt cache the way a mid-session model swap does. Tune effort first; drop to a cheaper model only when effort alone can't hit the cost target.

| Effort | Use for |
|--------|---------|
| `low` | Latency-sensitive, non-intelligence-sensitive: chat, simple lookups, cheap subagents |
| `medium` | Cost-conscious step-down from the default |
| `high` | Default for most intelligence-sensitive work (a good quality/cost balance) |
| `xhigh` | Hardest coding and agentic tasks (Claude Code's default) |
| `max` | Correctness matters more than cost; test for diminishing returns |

In our agents, effort is set per skill/agent frontmatter (`effort:`), not swapped at runtime. Combine effort routing with model routing: e.g. `sonnet` at `high` often beats `opus` at `low` for cost-equal quality — benchmark before committing.

## Pattern 1 — Complexity Router (pre-classify)

Cheap model classifies the request, then routes to the right tier:

```python
def route(user_message: str) -> str:
    complexity = classify_with_haiku(user_message)  # returns: simple | medium | hard
    return {"simple": "haiku", "medium": "sonnet", "hard": "opus"}[complexity]
```

Good when ~60% of traffic is simple. Overhead: one Haiku call per request (~100 tokens).

## Pattern 2 — Confidence-Based Escalation

Try the cheap model first, escalate only when it hesitates:

```python
def solve(problem: str):
    haiku = call_haiku(problem)
    if haiku.confidence > 0.85:
        return haiku.answer
    sonnet = call_sonnet(problem + haiku.reasoning)
    if sonnet.confidence > 0.8:
        return sonnet.answer
    return call_opus(problem)
```

Haiku must be prompted to output confidence (e.g. via tool-use structured output — see `json-mode-patterns`). Pure self-reported confidence is noisy; combine with a heuristic (output length, tool calls, hedging words).

## Pattern 3 — Sub-agent Delegation (Opus orchestrates, Haiku workers)

Orchestrator reasons about the plan, workers execute atomic steps:

```
Opus (planner)
  ├── Haiku (extract_dates_from_doc_1)
  ├── Haiku (extract_dates_from_doc_2)
  ├── Haiku (extract_dates_from_doc_3)
  └── Opus (synthesize all extractions into timeline)
```

Real example: `/orchestrate` in ai-toolkit runs Opus as planner, subagents (model per agent's frontmatter) as workers. See `app/agents/*.md` — each agent sets `model:` explicitly.

## Pattern 4 — Fallback Chain (resilience, not cost)

When primary is rate-limited or errors, degrade gracefully:

```python
def call_with_fallback(messages):
    for model in ["claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"]:
        try:
            return client.messages.create(model=model, messages=messages, ...)
        except (RateLimitError, OverloadedError):
            continue
    raise AllModelsExhausted()
```

Useful in production, not for cost optimization — you lose quality on fallback.

## Pattern 5 — Task-Specific Routing

Skip generic complexity scoring when you know the task type:

| Task | Route |
|------|-------|
| Commit message from diff | Haiku |
| Summarize 5-10 lines | Haiku |
| Classify intent | Haiku |
| Fix a failing test | Sonnet |
| Write new feature | Sonnet |
| Code review, architecture decision | Opus |
| Multi-agent orchestration | Opus |
| Complex debugging across systems | Opus |

Encode this as a map in code, not a prompt.

## Anti-patterns

| Anti-pattern | Consequence | Fix |
|--------------|-------------|-----|
| Opus for everything | 10-40x bill | Start with Sonnet, measure, demote |
| Haiku for code review | Misses subtle bugs | Sonnet minimum for code quality |
| Router overhead > savings | Haiku classifier eats the margin | Skip router if >80% of traffic is one tier |
| Different prompts per tier | Maintenance nightmare | Same prompt, just swap model |
| No telemetry | Can't optimize | Log model + tokens + cost per request |

## Measuring

Track per-route:
- Cost per request
- Latency p50/p95
- Quality score (human-labeled or auto-evaluated)
- Escalation rate (how often you fell back to a bigger model)

Target: move the Pareto curve — cheaper at equal quality OR better at equal cost.

## Related

- `llm-ops-engineer` agent — production routing strategy
- `prompt-caching-patterns` — stack caching on top of routing
- `json-mode-patterns` — structured confidence from Haiku
- Anthropic cookbook: https://github.com/anthropics/claude-cookbooks — see "sub-agents" notebook