version: "1.0.0" name: token-miser description: > Minimize Claude token and cost waste across ALL surfaces — Claude Code subagents, API calls in code, and artifacts. Routes subagent model selection via the Agent tool's model parameter. Recommends /model switches when the current model is overkill or underpowered. Applies to any code importing anthropic or calling /v1/messages. Trigger on: "API call", "artifact", "pipeline", "multi-agent", "LangGraph", "which model", "save tokens", "reduce cost", "claude API", "token usage", "context window", any code importing anthropic or calling /v1/messages, subagent launches, or any discussion about optimizing Claude usage or costs.

Token-Miser

Route every Claude interaction to the cheapest model that can handle it reliably.

Exemptions — Planning Phase Only

Token-miser routing is suspended ONLY during the planning phase (before ExitPlanMode):

• plan mode (/plan) — implementation design uses Opus for all subagents

Once ExitPlanMode is called and execution begins, token-miser routing RESUMES. During execution, route subagents normally: haiku for search/lookup, sonnet for code, opus for complex reasoning.

This applies to three surfaces:

1. Claude Code subagents — set model param on every Agent tool call
2. API calls in code — model selection when writing code that calls Anthropic
3. Artifacts — model selection for API calls inside artifacts

Never mention routing decisions to the user unless asked — just apply them.

Scope

Model Tiers (Verified 2026-03-17)

See references/model-pricing.md for detailed token pricing.

Claude Code Subagent Routing

This is the primary cost lever. Every Agent tool call accepts an optional model parameter. Always set it explicitly based on the task.

Subagent Routing Table

When NOT to downgrade subagents

• Subagent will write code that gets committed — sonnet minimum
• Subagent needs to make judgment calls about ambiguous requirements — sonnet+
• Subagent result feeds directly into user-facing output — match main model tier
• Task previously failed at a lower tier — escalate, don't retry same tier

Main Model Recommendations

Rule: Only recommend switches when the cost/quality delta is significant. Sonnet is always an acceptable default.

Freshness Protocol

1. Read references/model-pricing.md header date.
2. If <90 days old — use as-is.
3. If >90 days old — web-search Anthropic Claude API pricing before using prices.
4. If prices changed — update the reference file.

Skip when: applying routing table (no dollar amounts needed), subagent model selection (relative tiers don't change with pricing), token efficiency rules.

Routing Decision Framework

Step 1 — Classify the task

Step 2 — Apply modifiers

Bump up one tier if:

• Output is user-facing AND quality-sensitive
• Task requires multi-hop reasoning or >3 tool calls in a chain
• Input context >100K tokens
• Previous attempt at lower tier produced poor results

Bump down one tier if ALL of:

• Output is intermediate (not user-facing)
• Task is deterministic and templated
• Correctness is cheaply verifiable

Step 3 — Fallback / escalation

• Malformed output — retry once at same tier, then escalate
• Logically inconsistent — escalate one tier
• Confident and well-formed — done

Token Efficiency Rules

1. Trim system prompts — under 500 tokens unless required.
2. Batch — one call with 10 items beats 10 sequential calls.
3. Cap `max_tokens` — set to minimum plausible output length.
4. Cache-friendly prompts — stable content at the top.
5. Avoid redundant context — summarize prior turns, don't echo.
6. Structured output — JSON/tables over prose when consumer is a machine.
7. Minimize calls per interaction — batch user inputs before calling API.

Multi-Call Pipeline Design

[Router / Planner]   → Tier 1 or 2 (classify intent, decompose task)
[Subtask Workers]    → Tier 1 (extraction, formatting, simple transforms)
[Synthesizer]        → Tier 2 (combine, reason across results)
[Quality Gate]       → Tier 1 (schema check) → escalate to Tier 2 if fail
[Final Response]     → Tier matching user-facing quality bar

General rule: cheap models do the volume work; expensive models do the judgment.

Quick Reference Card

SUBAGENT ROUTING (Claude Code):
  Explore/search/grep:  haiku     Research/synthesis:   sonnet
  Code gen (simple):    sonnet    Code gen (complex):   opus
  Test/build/git:       haiku     Planning/arch:        opus
  Docs/formatting:      haiku     Debugging:            sonnet
 
API / ARTIFACT ROUTING:
  Task complexity:   LOW  → Haiku    MED  → Sonnet    HIGH → Opus
  Context size:      <20K → Haiku    20K-100K → Sonnet  >100K → Sonnet/Opus
  User-facing:       No   → Haiku    Yes → +1 tier if quality-sensitive
  Cost ratio:        1x         ~3x              ~5x
 
NOTE: Opus 4.6 at $5/$25 is only 5x Haiku (not 15x like legacy Opus 4.1).
When in doubt between Sonnet and Opus, quality wins.