Fable router

Fable 5 Model Router

Exploit each Claude model's strengths so Fable 5 (the parent, most expensive tier) spends tokens only where its judgment is irreplaceable. The parent stays orchestrator and integrator; subagents perform only capability-matched stages that justify their overhead.

Activation

Activate only on explicit invocation. Before the first user selection, use only the request and existing conversation context — no file reads, commands, or agents, except the auto-mode and opus-pin flag checks below.

The plugin's UserPromptSubmit hook counts as explicit invocation. While auto mode is on it injects a routing directive on every parent turn; acting on that directive is intended, not implicit activation. The directive carries its own bail-out — trivial or conversational turns are answered directly, unrouted — so honor that bail-out rather than routing every turn mechanically.

Auto Mode

Default: disabled. State is the existence of the flag file ~/.claude/fable-router-auto — check it with one test -f at activation.

• Arguments auto on / auto off toggle the flag (touch / rm -f), confirm the new state, and stop — no routing.
• Disabled (no flag): run Gate 1 and Gate 2 as written below.
• Hook (plugin install only): hooks/auto-route.sh fires on UserPromptSubmit, reads the same flag, and injects the routing directive so auto mode applies without typing /fable-router each turn. No flag means no injection. Manual installs get auto mode but not the hook.
• Enabled (flag exists): skip both AskUserQuestion gates. Pick the profile yourself — BALANCED unless the arguments name one — then build the recommended route and execute it immediately. State the chosen route in one line before spawning (profile, stages as model+effort+subagent_type). Everything else is unchanged: safety invariants, normal permission prompts, escalation rules, and the full completion report. Auto mode never authorizes external or destructive actions that Gate 2 would have flagged — those still stop for approval.

Opus Version Pin

Default: unpinned — stages routed to Opus use the Agent tool's opus alias, which resolves to whatever the harness maps it to (currently the newest Opus). State is the content of ~/.claude/fable-router-opus-pin — one full model ID on one line — checked with a single cat at activation alongside the auto-mode flag.

Sub-command (opus ... arguments toggle state, confirm, and stop — no routing, same shape as auto on/auto off):

• opus 4.8 / opus 4.7 / opus 4.6 — write claude-opus-4-8 / claude-opus-4-7 / claude-opus-4-6 to the pin file. Also accept the equivalent full claude-opus-* model ID and store any other such ID verbatim (see fallback below).
• opus 5, opus default, or opus off — remove the pin file; the opus alias applies again.
• opus or opus status — report the current pin (or "unpinned") and, for a pinned version, whether its pinned workers are available.

While pinned, every stage the route assigns to Opus uses the pinned version:

• Pin has shipped pinned workers (4.8 → fable-router:worker-opus48-medium|high|xhigh, likewise worker-opus47-* and worker-opus46-*): spawn that subagent_type and omit the Agent tool model parameter — the pin lives in the worker's frontmatter and a model parameter would override it back to the alias.
• Any other pinned ID: the Agent tool's model parameter accepts only tier aliases (haiku/sonnet/opus/fable), never full model IDs — a pin without shipped pinned workers therefore cannot be honored via the model parameter. Stop and ask (AskUserQuestion) whether to fall back to the alias or re-pin to a version with shipped workers — never substitute silently.

Scope: the pin changes only which Opus executes Opus stages. Capability floors, effort floors, and which stages route to Opus are unchanged; Sonnet/Haiku/Fable stages are untouched; escalation above Opus still goes to Fable, not another Opus version. Pinned workers ship medium, high, and xhigh efforts but not low — the low floor (deterministic, validator-backed work) is never Opus territory; if a route ever wants Opus at low, use medium. Gate 2 route listings and the completion report must show the pinned model ID, not the bare word "opus", so the user sees exactly what will run.

Gate 1: Choose An Objective

Present these profiles with a task-specific one-line tradeoff, using AskUserQuestion:

1. PERFORMANCE — maximize correctness, depth, independent validation; may use more tokens/time.
2. BALANCED — preserve required quality while minimizing duplicate context and unnecessary agents. Recommend by default.
3. TOKEN_SAVER — minimize non-required Fable output: delegate every delegable stage to the cheapest capable model, keep parent turns short, preserve Fable-owned design/judgment and safety floors.

Alongside the choices, state the minimum read-only discovery needed to route accurately. Profile selection authorizes only that discovery. If the task is fully specified and discovery is unnecessary, say so.

Read-Only Discovery

After Gate 1, inspect only the approved evidence to identify: independent vs coupled stages; ambiguity, consequence of error, repetition, verification burden; available deterministic validators (tests, linters, typecheckers); likely context duplication vs orchestration overhead.

Use Explore/cavecrew-investigator subagents (model: haiku or sonnet) for this discovery so raw file dumps never enter the parent context. No writes, no implementation agents.

Build The Adaptive Route

1. Express the task as a small dependency graph: analysis, research, design, implementation, deterministic transformation, verification, final judgment — as applicable.
2. For any user-facing product/UI work, decide whether a design stage exists. If so, assign design direction and subjective design acceptance to Fable (the parent, in-context — never a subagent's guess).
3. Assign the lowest-cost model that satisfies each remaining stage's capability and risk floor, and the lowest reasoning effort that its ambiguity and consequence allow (see Effort Floors).
4. The parent Fable is already an active capability — do not duplicate its planning or integration in a subagent unless independent review has explicit value.
5. Prefer one agent. Add agents only for: independent evidence, disjoint parallel work, deterministic volume, or consequential independent review.
6. Keep context packets narrow: each subagent gets only its role contract, objective, required evidence (file paths, not dumps), allowed write surface, non-goals, validation command, and output shape. If the packet spawns the agent with a name (promoting it to an addressable teammate), it must also require the worker to report its result with SendMessage(to: "main") before finishing, since a teammate's final text is not relayed to the parent.
7. Escalate on ambiguity, failed validation, conflicting evidence, or higher consequence — cheapest step first: raise effort within the same model (low → medium → high → xhigh) before raising the model (Haiku → Sonnet → Opus → Fable). One escalation retry per stage before pulling the stage back into the parent.
8. Compare the route with Fable-direct. If delegation lacks a credible advantage for the selected profile, recommend Fable-direct and say why.

Mechanics: spawn via the Agent tool with an explicit model parameter (haiku, sonnet, opus; omit = inherit Fable — never omit for a routed stage, with one exception: Opus-pinned workers carry their model in frontmatter and are spawned with no model parameter, per Opus Version Pin). The Agent tool has no per-call effort parameter; effort comes from the agent definition, so route effort by choosing subagent_type: fable-router:worker-low, fable-router:worker-medium, fable-router:worker-high, or fable-router:worker-xhigh (this plugin ships them; model × effort compose freely via the model parameter). Workers carry WebSearch/WebFetch, so web-research stages route through them too. Other types still work when their scope fits — Explore for codebase search, caveman:cavecrew-* for compressed output — but they inherit session effort. Parallel independent stages go in one message. Use isolation: "worktree" only when agents mutate files in parallel.

Skill-Invocation Turns

A turn that invokes a skill (slash command) is a routing target like any other — the skill body is an input to route design (a procedure spec), not grounds for the parent to perform every step inline.

• If the skill fully specifies the procedure and carries a deterministic validator (test-runner exit code, BUILD SUCCESSFUL marker, diff shape), route its execution stage to worker-medium on sonnet (worker-low where the low floor holds). The context packet carries the skill body or its path plus the environment contract it needs (required env vars, working directory).
• The parent keeps result integration and pulls a stage back inline on failure: diagnosis that judges against session context (branch diff, recent change history) is legitimately parent-inline.
• Mechanical re-runs expected to pass (no code changes since the last green run) are exactly the delegable case — never Fable-direct.
• Routing policy has one owner: this skill. Do not write routing rules into domain skill documents; when a domain skill needs different routing, change this file.

Capability Floors

• Fable (parent): design/UX/art direction and subjective acceptance, ambiguous planning, architecture, high-consequence changes, adversarial review, final judgment, integration.
• Opus: complex implementation, cross-file refactors, tricky debugging, independent second-opinion review when consequence is high.
• Sonnet: standard implementation of an approved plan, exploration/research synthesis, test writing, evidence gathering, moderate-difficulty fixes.
• Haiku: deterministic extraction, normalization, mechanical renames/conversions, repetitive transformation with objective checks, bulk file scanning.

Never assign Haiku: source-of-truth selection, design decisions, architecture, ambiguity resolution, destructive decisions, or final sufficiency review. Profiles may reduce context or duplicate review — never the Fable design/judgment floor.

Effort Floors

Effort is an axis orthogonal to model choice; pick both per stage.

• low — deterministic or repetitive work where an objective validator (tests, linter, typechecker, countable diff) catches mistakes: bulk scanning, extraction, mechanical conversions.
• medium — standard implementation of an approved plan, research synthesis, test writing: low ambiguity, clear acceptance criteria. Default when unsure between low and medium.
• high — tricky debugging, cross-file refactors, retries after failed validation, consequential independent review.
• xhigh — the hardest delegated stages: adversarial review of high-consequence changes, debugging that survived a high attempt, subtle correctness analysis. The most expensive tier per stage — reach it through escalation, or assign it directly only under PERFORMANCE for a stage whose consequence clearly warrants it.

Rules: a stage with no deterministic validator never gets low. TOKEN_SAVER prefers the lowest effort whose floor holds — do not spend sonnet + medium where haiku + low with a validator suffices; PERFORMANCE may raise review stages to high or xhigh but still never lowers a floor.

Estimate Effects Honestly

Report Fable-direct-relative estimates for output quality, elapsed time, token cost, and regression risk using directional values (lower/similar/higher) plus evidence and uncertainty. Use numbers only from measured history or deterministic workload counts. If usage is not observable, say not observable — never invent savings.

Gate 2: Approve Execution

Present one recommended route (compact alternative only if it has a genuinely different tradeoff):

• selected profile;
• stages: role, model, effort, subagent_type, order, expected deliverable, validation per stage;
• Fable-direct comparison and estimate confidence;
• external/destructive actions that remain separately approval-gated.

Wait for explicit approval (AskUserQuestion). Profile selection is not execution approval. After approval, spawn only the approved roles; tactical changes within approved scope/models/risk need no reapproval, but model, scope, permission, or risk changes do.

Safety Invariants

• Routing approval does not bypass normal permission prompts.
• Delegation depth stays at one; subagents must not spawn descendants.
• Never silently substitute a model; pause and reapprove.
• Do not expose secrets in plans, handoffs, or subagent prompts.

Completion

The parent integrates all results and reports: actual route taken, validation results, deviations from the approved route, and residual risk. Subagent completion alone is not task completion.