# Subagent Model Router — Agent Install Protocol

**Protocol version: v2.0 · Pinned kit: model-routing-v2.0 · This file is fetched and executed by the recipient's own Claude.**

You are Claude Code, running on the recipient's machine. The human pasted a prompt asking you to install the Subagent Model Router by following this document. Follow it **exactly, in order**. Explain each step in plain language before you run it, and wait for the human's OK at the marked decision points.

**What you are installing (say this up front, honestly):** a small quality-and-cost governor for Claude Code's subagents. Today, when Claude spawns helper agents, they inherit the session's model by default — usually the frontier tier — even for trivial jobs like searching files. This kit makes every subagent launch *deliberately routed*: reasoning-heavy work stays on the frontier model, simple retrieval work goes to Sonnet (a strong, cheaper model), and haiku-class models are banned outright. A ≥9/10 certainty rule means quality is never traded for token savings — when in doubt, it escalates to the stronger model. New in v2.0: a hardened gate (word-boundary haiku match, optional allowlist cross-check), an optional LOCAL-ONLY route log so the human can see routing decisions with real data, an optional structural model allowlist, an independence rule for grading (a different model family judges consequential work), and an optional notify-only update check.

**Enforcement scope (be precise about this — never claim more):** the mechanical gate covers subagents launched through the Agent/Task tool on well-formed hook events — the main fan-out path. It fails OPEN by design on malformed input (it must never break the harness). In the author's own live probing (July 2026), Workflow-script spawns did NOT pass through the hook and were not stopped by the model allowlist either — so on those paths the doctrine text Claude reads each session is the enforcement, and it explicitly says so. The hook checks the model field; the task classification and certainty judgment are applied by Claude following the doctrine.

**The honest cost note (say this in Step 1 — know which billing applies):** this is a QUALITY-FIRST governor, not a cost-cutter. The net effect is a 2×2 — find their square and say it plainly:
- **Frontier sessions + API billing** → usually SAVES money (trivial work stops inheriting the expensive model).
- **Frontier sessions + flat subscription** → saves rate-limit/latency budget, NOT dollars (the bill is flat either way).
- **Cheaper-model sessions + API billing** → can COST MORE (haiku banned, doubt escalates up).
- **Cheaper-model sessions + flat subscription** → better quality, some latency, faster rate-limit consumption — no dollar change.
Ask which billing they're on and state the row that applies to them.

**What it changes on this machine (enumerate honestly — a required core plus optionals the human chooses):**

*Required core (3 changes, all local):*
1. Adds `~/.claude/hooks/subagent-model-gate.py` — a ~180-line Python script. One side effect to disclose: if settings.json ALREADY contains an `availableModels` list, the gate enforces it on Agent/Task spawns even when the allowlist optional below is declined (check in Step 1 and say so if it applies).
2. Adds one PreToolUse hook entry to `~/.claude/settings.json` (merged carefully after a timestamped backup; existing settings preserved).
3. Appends one marker-fenced "Subagent Model Routing" section to `~/.claude/CLAUDE.md`.

*Optional, chosen in Step 1 (each = one more file and/or one settings entry):*
4. **Route log (recommended):** adds `~/.claude/hooks/route-log.py` + one PostToolUse entry; writes `~/.claude/logs/route-log.jsonl` (created 0600). Fields logged, completely: timestamp, random spawn id, session id, requested model, resolved model, subagent type, an 8-char hash of the task description (not the text), token usage, duration, tool-use count. **The kit never transmits this file** — it exists so the human can check routing against reality.
5. **Model allowlist:** adds an `availableModels` key to settings.json — a structural floor the harness itself enforces on several launch surfaces. Honest caveat: its reach varies by surface and Claude Code version; the hook remains the deliberate-choice gate either way.
6. **Update check (notify-only):** adds `~/.claude/hooks/model-routing-update-check.sh` + one SessionStart entry + a config line. At most once every 24 hours it makes ONE https request to the kit host and prints one line only if a STRICTLY NEWER kit exists. **It never modifies anything by itself** — upgrades always run through this protocol with the human present. It parses its config; it never executes it.

**Telemetry truth:** the core kit makes zero network requests after install. The route log is a local file the kit never transmits. The optional update check pings the kit host for a version number (ordinary web access log entries are the only trace). The only other traces anywhere are the access log entries from downloading the kit files below, and the name/email the human chose to submit on the share page. Every settings change is preceded by a timestamped backup; backups are deliberately kept (disclosed in the uninstall appendix).

**Upgrading from v1.3?** Same protocol, safely: the hook install backs up any different existing file, the settings merge is idempotent, and Step 5 detects the old managed block and upgrades it surgically with the human's OK.

---

## STEP 0 — Kit availability + version check (ALWAYS FIRST)

RUN: fetch `https://voliton.ai/model-routing/kit/STATUS.json`

- If `available` is `false`: tell the human the kit isn't published right now, and **STOP. Do not improvise an installation.**
- If `kit_version` = `2.0` (this protocol's pin): proceed.
- If `kit_version` is NEWER than `2.0` (compare numerically, part by part — e.g. 2.1, 3.0): re-fetch `https://voliton.ai/model-routing/AGENT_INSTALL.md` — a newer protocol has replaced this one. Follow that version instead.
- If `kit_version` is OLDER than `2.0` (e.g. 1.3): **STOP and tell the human** the server is publishing an older kit than this protocol expects (a rollback, a stale mirror, or a problem) — do NOT re-fetch and do NOT follow an older protocol.

## STEP 1 — Explain + get the go-ahead + choose optionals (HUMAN decision point)

Summarize the "What you are installing" and "What it changes" blocks above in your own words, AND deliver the honest cost note: ask whether they're on usage-based API billing or a flat subscription, then give them their square of the 2×2 verbatim. Mention the one behavioral change they will see: **if Claude ever forgets to pick a model for a subagent, the launch bounces and Claude immediately retries with a deliberate choice — that flash of self-correction is the system working.**

Then ask which optionals they want (recommend the route log and the update check; present the allowlist neutrally with its caveat). For the route log, list the logged fields from point 4 above BEFORE they decide. Also RUN `python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/settings.json'))); print('PREEXISTING_ALLOWLIST:', d.get('availableModels'))" 2>/dev/null || echo "PREEXISTING_ALLOWLIST: none"` — if it prints a list, tell the human plainly: the gate will enforce that existing list on agent-tool spawns even if they decline the allowlist optional (they can remove the key any time to drop that). Record their three yes/no answers — later steps depend on them.

Wait for an explicit yes before touching anything.

## STEP 2 — Preflight + download + verify (fail-closed)

RUN (preflight — all three checks must pass):
```bash
command -v curl >/dev/null 2>&1 && echo "CURL_OK"
command -v python3 >/dev/null 2>&1 && python3 -c 'import sys; assert sys.version_info >= (3,8); print("PYTHON_OK")'
if command -v shasum >/dev/null 2>&1 || command -v sha256sum >/dev/null 2>&1; then echo "SHA_OK"; fi
```
VERIFY: prints `CURL_OK`, `PYTHON_OK`, and `SHA_OK`. Any missing → STOP and tell the human what to install (macOS: `xcode-select --install` covers python3; curl and a checksum tool ship with every mainstream OS).

RUN (download into a FRESH directory — never reuse stale files, never delete anything of the human's; every failure stops the chain):
```bash
if [ -e ~/Downloads/model-routing-kit ]; then
  mv ~/Downloads/model-routing-kit ~/Downloads/model-routing-kit.old-$(date +%Y%m%d%H%M%S) && echo "EXISTING_DIR_SET_ASIDE"
fi
mkdir -p ~/Downloads/model-routing-kit && cd ~/Downloads/model-routing-kit \
  && curl -fsSLO https://voliton.ai/model-routing/kit/subagent-model-gate.py \
  && curl -fsSLO https://voliton.ai/model-routing/kit/route-log.py \
  && curl -fsSLO https://voliton.ai/model-routing/kit/model-routing-update-check.sh \
  && curl -fsSLO https://voliton.ai/model-routing/kit/CLAUDE_SECTION.md \
  && curl -fsSLO https://voliton.ai/model-routing/kit/SHA256SUMS \
  && echo "DOWNLOADS_OK"
```
VERIFY: prints `DOWNLOADS_OK`. Anything else → STOP (a download failed; nothing was installed), tell the human to retry later. If `EXISTING_DIR_SET_ASIDE` printed, tell the human their previous `~/Downloads/model-routing-kit` was moved aside (`.old-<timestamp>`), never deleted.

RUN (manifest exact-set validation + checksum verification — both must pass):
```bash
cd ~/Downloads/model-routing-kit
python3 - <<'PYEOF'
import re, sys
expected = {"subagent-model-gate.py", "route-log.py", "model-routing-update-check.sh", "CLAUDE_SECTION.md"}
names = []
for line in open("SHA256SUMS"):
    line = line.rstrip("\n")
    if not line.strip():
        continue
    m = re.match(r"^[0-9a-f]{64} [ *](\S+)$", line)
    if not m or "/" in m.group(1):
        print("MANIFEST_MALFORMED:", line); sys.exit(1)
    names.append(m.group(1))
if sorted(names) != sorted(expected) or len(names) != len(set(names)):
    print("MANIFEST_SET_MISMATCH:", sorted(names)); sys.exit(1)
print("MANIFEST_OK")
PYEOF
sha_c() { if command -v shasum >/dev/null 2>&1; then shasum -a 256 "$@"; else sha256sum "$@"; fi; }
sha_c -c SHA256SUMS && echo "CHECKSUMS_OK"
```
VERIFY: prints `MANIFEST_OK`, then `: OK` for all four files, then `CHECKSUMS_OK`. Any FAILED line, mismatch, or missing `CHECKSUMS_OK` → STOP, re-run the download block once; if it still fails, tell the human the download is corrupted and to try again later. Download all files even if some optionals were declined — only chosen ones get installed.

## STEP 3 — Install the hook script (backup-aware) + pipe tests

RUN:
```bash
mkdir -p ~/.claude/hooks
if [ -f ~/.claude/hooks/subagent-model-gate.py ] && ! cmp -s ~/Downloads/model-routing-kit/subagent-model-gate.py ~/.claude/hooks/subagent-model-gate.py; then
  cp ~/.claude/hooks/subagent-model-gate.py ~/.claude/hooks/subagent-model-gate.py.bak-$(date +%Y%m%d%H%M%S)
  echo "EXISTING_DIFFERENT_FILE_BACKED_UP"
fi
cp ~/Downloads/model-routing-kit/subagent-model-gate.py ~/.claude/hooks/subagent-model-gate.py
chmod +x ~/.claude/hooks/subagent-model-gate.py
```
If `EXISTING_DIFFERENT_FILE_BACKED_UP` printed: tell the human a different version of the gate already existed (v1.3 if they're upgrading) and was backed up alongside (`.bak-<timestamp>`), then continue.

Pipe-test the gate's behaviors before wiring anything in. The tests run under an ISOLATED temporary HOME so the results are identical on every machine regardless of existing settings:
```bash
G=~/.claude/hooks/subagent-model-gate.py
T=$(mktemp -d); mkdir -p "$T/.claude"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x"}}' | HOME="$T" python3 "$G" 2>/dev/null; echo "no-model exit=$?"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","model":"haiku"}}' | HOME="$T" python3 "$G" 2>/dev/null; echo "haiku exit=$?"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","model":"claude-haiku-4-5-20251001"}}' | HOME="$T" python3 "$G" 2>/dev/null; echo "haiku-id exit=$?"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","subagent_type":"not-codex-but-claude","model":"haiku"}}' | HOME="$T" python3 "$G" 2>/dev/null; echo "fake-exempt exit=$?"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","model":"sonnet"}}' | HOME="$T" python3 "$G"; echo "sonnet exit=$?"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","model":"shaikupro"}}' | HOME="$T" python3 "$G"; echo "word-boundary exit=$?"
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | HOME="$T" python3 "$G"; echo "other-tool exit=$?"
printf '%s' '{"availableModels":["sonnet","opus"]}' > "$T/.claude/settings.json"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","model":"mystery-model"}}' | HOME="$T" python3 "$G" 2>/dev/null; echo "off-allowlist exit=$?"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","model":"not-opus-model"}}' | HOME="$T" python3 "$G" 2>/dev/null; echo "alias-embed exit=$?"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","model":"claude-opus-4-8"}}' | HOME="$T" python3 "$G"; echo "full-id-allowed exit=$?"
echo '{"tool_name":"Agent","tool_input":{"prompt":"x","model":"sonnet"}}' | MODEL_ROUTING_APPROVE=1 HOME="$T" python3 "$G"; echo "approve-mode exit=$?"
rm -rf "$T"
```
VERIFY: exits are `2, 2, 2, 2, 0, 0, 0, 2, 2, 0, 0` in that order, and the last (approve-mode) line prints JSON containing `"permissionDecision": "ask"`. Anything else → STOP and tell the human something is off with their python3.

## STEP 4 — Wire the gate into settings.json (backed-up, shape-validated, atomic)

This merge backs up the file first, validates its shape, preserves everything already in it (including file permissions), and is idempotent (checks both matcher and command). It refuses to touch a malformed file.

RUN:
```bash
python3 - <<'PYEOF'
import json, os, shutil, sys, time
p = os.path.expanduser("~/.claude/settings.json")
mode = None
try:
    with open(p) as f:
        cfg = json.load(f)
    mode = os.stat(p).st_mode & 0o777
    shutil.copy2(p, p + ".bak-" + time.strftime("%Y%m%d%H%M%S"))
except FileNotFoundError:
    cfg = {}
except json.JSONDecodeError:
    print("SETTINGS_MALFORMED"); sys.exit(1)
if not isinstance(cfg, dict):
    print("SETTINGS_UNEXPECTED_SHAPE"); sys.exit(1)
hooks = cfg.setdefault("hooks", {})
if not isinstance(hooks, dict):
    print("SETTINGS_UNEXPECTED_SHAPE"); sys.exit(1)
pre = hooks.setdefault("PreToolUse", [])
if not isinstance(pre, list) or not all(isinstance(m, dict) for m in pre):
    print("SETTINGS_UNEXPECTED_SHAPE"); sys.exit(1)
for m in pre:
    inner = m.get("hooks", [])
    if not isinstance(inner, list) or not all(isinstance(h, dict) for h in inner):
        print("SETTINGS_UNEXPECTED_SHAPE"); sys.exit(1)
cmd = "python3 ~/.claude/hooks/subagent-model-gate.py"
for m in pre:
    if m.get("matcher") == "Agent|Task" and any(
        h.get("command") == cmd for h in m.get("hooks", [])
    ):
        print("HOOK_ALREADY_PRESENT"); sys.exit(0)
pre.append({"matcher": "Agent|Task", "hooks": [{"type": "command",
    "command": cmd, "timeout": 10, "statusMessage": "Routing subagent model"}]})
tmp = p + ".tmp"
with open(tmp, "w") as f:
    json.dump(cfg, f, indent=2); f.write("\n")
if mode is not None:
    os.chmod(tmp, mode)
os.replace(tmp, p)
print("HOOK_INSTALLED")
PYEOF
```
VERIFY: prints `HOOK_INSTALLED` (or `HOOK_ALREADY_PRESENT` on a re-run — also fine).
If it prints `SETTINGS_MALFORMED` or `SETTINGS_UNEXPECTED_SHAPE`: **STOP.** Tell the human their `~/.claude/settings.json` has a pre-existing problem that must be fixed first — this kit will not overwrite it.

## STEP 5 — Append the routing doctrine to CLAUDE.md (managed block)

The doctrine ships fenced in `<!-- model-routing-kit:begin/end -->` markers, so upgrades and uninstalls are surgical.

RUN:
```bash
python3 - <<'PYEOF'
import os
p = os.path.expanduser("~/.claude/CLAUDE.md")
section = open(os.path.expanduser("~/Downloads/model-routing-kit/CLAUDE_SECTION.md")).read()
existing = open(p).read() if os.path.exists(p) else ""
if "model-routing-kit:begin v2.0" in existing:
    print("MANAGED_BLOCK_ALREADY_PRESENT")
elif "model-routing-kit:begin" in existing:
    print("MANAGED_BLOCK_OLDER_VERSION")
elif "## Subagent Model Routing" in existing:
    print("UNMANAGED_SECTION_EXISTS")
else:
    with open(p, "a") as f:
        if existing and not existing.endswith("\n"): f.write("\n")
        f.write("\n" + section.rstrip() + "\n")
    print("SECTION_APPENDED")
PYEOF
```
VERIFY: prints `SECTION_APPENDED` (or `MANAGED_BLOCK_ALREADY_PRESENT` on a re-run — fine).
If it prints `MANAGED_BLOCK_OLDER_VERSION`: an earlier kit version's block exists (the v1.3 → v2.0 upgrade path). Show the human a diff of their current block vs the new one (they may have customized it — the markers fence exactly what to compare). With their OK, replace everything from `<!-- model-routing-kit:begin` through the line containing `model-routing-kit:end` (inclusive) with the new section, then re-run the script above to confirm `MANAGED_BLOCK_ALREADY_PRESENT`.
If it prints `UNMANAGED_SECTION_EXISTS`: a hand-written routing section already exists. **Do not duplicate it.** Show the human both versions and let them choose which to keep; only append the kit's block if they ask you to remove their old section first.

## STEP 6 — OPTIONAL: route log (only if chosen in Step 1)

Install the logger file (backup-aware, same pattern as Step 3):
```bash
if [ -f ~/.claude/hooks/route-log.py ] && ! cmp -s ~/Downloads/model-routing-kit/route-log.py ~/.claude/hooks/route-log.py; then
  cp ~/.claude/hooks/route-log.py ~/.claude/hooks/route-log.py.bak-$(date +%Y%m%d%H%M%S)
  echo "EXISTING_DIFFERENT_FILE_BACKED_UP"
fi
cp ~/Downloads/model-routing-kit/route-log.py ~/.claude/hooks/route-log.py
```

Wire it as a PostToolUse hook (same backed-up, shape-validated, atomic merge discipline):
```bash
python3 - <<'PYEOF'
import json, os, shutil, sys, time
p = os.path.expanduser("~/.claude/settings.json")
try:
    with open(p) as f:
        cfg = json.load(f)
    mode = os.stat(p).st_mode & 0o777
    shutil.copy2(p, p + ".bak-" + time.strftime("%Y%m%d%H%M%S"))
except (FileNotFoundError, json.JSONDecodeError):
    print("SETTINGS_PROBLEM"); sys.exit(1)
if not isinstance(cfg, dict) or not isinstance(cfg.get("hooks", {}), dict):
    print("SETTINGS_PROBLEM"); sys.exit(1)
post = cfg.setdefault("hooks", {}).setdefault("PostToolUse", [])
if not isinstance(post, list) or not all(isinstance(m, dict) for m in post):
    print("SETTINGS_PROBLEM"); sys.exit(1)
for m in post:
    inner = m.get("hooks", [])
    if not isinstance(inner, list) or not all(isinstance(h, dict) for h in inner):
        print("SETTINGS_PROBLEM"); sys.exit(1)
cmd = "python3 ~/.claude/hooks/route-log.py"
for m in post:
    if m.get("matcher") == "Agent|Task" and any(
        h.get("command") == cmd for h in m.get("hooks", [])
    ):
        print("ROUTELOG_ALREADY_PRESENT"); sys.exit(0)
post.append({"matcher": "Agent|Task", "hooks": [{"type": "command", "command": cmd, "timeout": 10}]})
tmp = p + ".tmp"
with open(tmp, "w") as f:
    json.dump(cfg, f, indent=2); f.write("\n")
os.chmod(tmp, mode)
os.replace(tmp, p)
print("ROUTELOG_INSTALLED")
PYEOF
```
VERIFY: prints `ROUTELOG_INSTALLED` (or `ROUTELOG_ALREADY_PRESENT`). On `SETTINGS_PROBLEM` → STOP as in Step 4. Tell the human: the log lives at `~/.claude/logs/route-log.jsonl` (created 0600), it is plain JSON lines they can read anytime, and the kit never transmits it.

## STEP 7 — OPTIONAL: model allowlist (only if chosen in Step 1)

Say the honest caveat first: this adds a floor the harness itself can enforce on several spawn surfaces, but its exact reach varies by surface and Claude Code version — the hook remains the deliberate-choice gate regardless. The list below allows the standard strong tiers and automatically includes their current default model so nothing they already use breaks; haiku is never included. If an `availableModels` key already exists but is malformed, this step refuses to touch it.

RUN:
```bash
python3 - <<'PYEOF'
import json, os, shutil, sys, time
p = os.path.expanduser("~/.claude/settings.json")
try:
    with open(p) as f:
        cfg = json.load(f)
    mode = os.stat(p).st_mode & 0o777
    shutil.copy2(p, p + ".bak-" + time.strftime("%Y%m%d%H%M%S"))
except (FileNotFoundError, json.JSONDecodeError):
    print("SETTINGS_PROBLEM"); sys.exit(1)
if not isinstance(cfg, dict):
    print("SETTINGS_PROBLEM"); sys.exit(1)
existing = cfg.get("availableModels")
if existing is not None and (not isinstance(existing, list) or not all(isinstance(m, str) for m in existing)):
    print("ALLOWLIST_MALFORMED_REFUSING"); sys.exit(1)
import re
haiku = lambda s: re.search(r"\bhaiku\b", s.lower())  # word-boundary, matching the gate
allow = ["sonnet", "opus"]
default = cfg.get("model")
if isinstance(default, str) and default.strip():
    d = default.strip()
    if not haiku(d) and d not in allow:
        allow.append(d)
if isinstance(existing, list):
    for m in existing:
        if m and not haiku(m) and m not in allow:
            allow.append(m)
if any(haiku(m) for m in allow):
    print("SETTINGS_PROBLEM"); sys.exit(1)
cfg["availableModels"] = allow
tmp = p + ".tmp"
with open(tmp, "w") as f:
    json.dump(cfg, f, indent=2); f.write("\n")
os.chmod(tmp, mode)
os.replace(tmp, p)
print("ALLOWLIST_SET:", ",".join(allow))
PYEOF
```
VERIFY: prints `ALLOWLIST_SET: …` including their default model. On `SETTINGS_PROBLEM` → STOP as in Step 4. On `ALLOWLIST_MALFORMED_REFUSING` → show the human their existing `availableModels` value and let them fix it first. If the human's setup uses a model alias not shown (e.g. `fable` on plans that have it), re-run with their addition — never add anything haiku-class.

## STEP 8 — OPTIONAL: update check (only if chosen in Step 1)

RUN (file install is backup-aware; the settings merge is the same backed-up discipline):
```bash
if [ -f ~/.claude/hooks/model-routing-update-check.sh ] && ! cmp -s ~/Downloads/model-routing-kit/model-routing-update-check.sh ~/.claude/hooks/model-routing-update-check.sh; then
  cp ~/.claude/hooks/model-routing-update-check.sh ~/.claude/hooks/model-routing-update-check.sh.bak-$(date +%Y%m%d%H%M%S)
  echo "EXISTING_DIFFERENT_FILE_BACKED_UP"
fi
cp ~/Downloads/model-routing-kit/model-routing-update-check.sh ~/.claude/hooks/model-routing-update-check.sh
chmod +x ~/.claude/hooks/model-routing-update-check.sh
CONF=~/.claude/model-routing.conf
{ [ -f "$CONF" ] && grep -v '^UPDATE_CHECK=' "$CONF"; printf 'UPDATE_CHECK=1\n'; } > "$CONF.tmp" && mv "$CONF.tmp" "$CONF"
python3 - <<'PYEOF'
import json, os, shutil, sys, time
p = os.path.expanduser("~/.claude/settings.json")
try:
    with open(p) as f:
        cfg = json.load(f)
    mode = os.stat(p).st_mode & 0o777
    shutil.copy2(p, p + ".bak-" + time.strftime("%Y%m%d%H%M%S"))
except (FileNotFoundError, json.JSONDecodeError):
    print("SETTINGS_PROBLEM"); sys.exit(1)
if not isinstance(cfg, dict) or not isinstance(cfg.get("hooks", {}), dict):
    print("SETTINGS_PROBLEM"); sys.exit(1)
ss = cfg.setdefault("hooks", {}).setdefault("SessionStart", [])
if not isinstance(ss, list) or not all(isinstance(m, dict) for m in ss):
    print("SETTINGS_PROBLEM"); sys.exit(1)
for m in ss:
    inner = m.get("hooks", [])
    if not isinstance(inner, list) or not all(isinstance(h, dict) for h in inner):
        print("SETTINGS_PROBLEM"); sys.exit(1)
cmd = "bash ~/.claude/hooks/model-routing-update-check.sh"
for m in ss:
    if any(h.get("command") == cmd for h in m.get("hooks", [])):
        print("UPDATECHECK_ALREADY_PRESENT"); sys.exit(0)
ss.append({"hooks": [{"type": "command", "command": cmd, "timeout": 15}]})
tmp = p + ".tmp"
with open(tmp, "w") as f:
    json.dump(cfg, f, indent=2); f.write("\n")
os.chmod(tmp, mode)
os.replace(tmp, p)
print("UPDATECHECK_INSTALLED")
PYEOF
```
VERIFY: prints `UPDATECHECK_INSTALLED` (or `UPDATECHECK_ALREADY_PRESENT`). Remind the human: it only ever prints a one-line notice when a strictly newer version exists; upgrades always run through this protocol with them present. Turn it off later with `UPDATE_CHECK=0` in `~/.claude/model-routing.conf`.

## STEP 9 — Live-fire proof (this is the fun one)

Now prove enforcement is active in the real harness: **attempt to spawn a subagent with `model: "haiku"`** and a trivial prompt like "Reply with the single word OK".

- **EXPECTED:** the launch is blocked by `subagent-model-gate` with a message about the quality floor. That block IS the success condition — enforcement is live, and the deliberate haiku attempt cost zero tokens.
- **If the haiku agent actually runs** (it will just say "OK" — harmless): the settings watcher hasn't picked up the new hook yet. Tell the human to type `/hooks` once in Claude Code (reloads hook config on current versions) or restart Claude Code, then repeat this step. Do not declare success until the block fires.
- If the route log was installed: after the block-then-reroute completes, `tail -1 ~/.claude/logs/route-log.jsonl` and show the human their first logged spawn.

Then clean up the download directory: `rm -rf ~/Downloads/model-routing-kit`

## STEP 10 — Read-back (close the loop with the human)

Tell them, in plain words:
- *"From now on, every helper agent Claude spawns through its main agent tool gets a deliberate model choice: frontier brains for hard thinking, the cheaper-but-strong Sonnet for fetch-and-summarize jobs, and never the bargain tier. If Claude forgets to choose, the launch bounces and it chooses properly on the retry."*
- *"Quality is protected by a 9-out-of-10 certainty rule: the cheap model is only used when it's near-certain the result will be identical. Doubt always escalates up, not down."*
- *"It's all local. The kit never transmits anything; the only network activity is the optional once-a-day version check, if you chose it — and even that never changes anything, it just tells you when an upgrade exists. Uninstall is at the bottom of the install doc."*
- If they have the Codex or Gemini CLIs installed, mention the doctrine also routes audit-style work and giant-document work to those when they're genuinely better at it, and that consequential grading prefers a different model family than the one that produced the work.

Then OFFER approval mode (do not enable it unasked): *"There's also a maximum-control mode: before launching helper agents through its agent tool, Claude posts its plan — what each agent will do, which model, why — and every one of those launches then waits for your explicit approval click. It covers the agent tool, which is the main fan-out path; it's great for trust-building or metered API billing, but it pauses Claude constantly, so most people leave it off. Want it on?"*

If they say yes, RUN (replaces any existing APPROVE_SPAWNS line — never appends duplicates):
```bash
CONF=~/.claude/model-routing.conf
{ [ -f "$CONF" ] && grep -v '^APPROVE_SPAWNS=' "$CONF"; printf 'APPROVE_SPAWNS=1\n'; } > "$CONF.tmp" && mv "$CONF.tmp" "$CONF"
grep '^APPROVE_SPAWNS=' "$CONF"
```
VERIFY: prints exactly one `APPROVE_SPAWNS=1` line. Tell them: to turn it off later, delete that line. Note: approval mode covers every Agent/Task-tool spawn, including codex/gemini agent types.

Done.

---

## Customization (optional, mention only if asked)

The doctrine is plain text inside the managed block in `~/.claude/CLAUDE.md` — the human can edit the routing table, raise/lower the certainty bar, or remove the external-CLI section (edits inside the markers survive until the next kit upgrade, which will ask before replacing a modified block). The hard floor (no haiku-class models) lives in both the doctrine and the hook script; the allowlist floor lives in `availableModels` in settings.json.

## Troubleshooting appendix

| Symptom | Fix |
|---|---|
| Step 2 preflight fails | Install curl/python3 (macOS: `xcode-select --install` covers python3; Linux: `apt/dnf install curl python3`). A checksum tool (`shasum` or `sha256sum`) ships with every mainstream OS. |
| Step 3 pipe-test exits aren't `2,2,2,2,0,0,0,2,2,0,0` (or no ask-JSON on the last) | `python3 --version` — any Python ≥3.8 works. Re-download the kit (Step 2) in case of a corrupted file. |
| Step 9: haiku agent runs instead of being blocked | Hook config not reloaded. Type `/hooks` once in Claude Code or restart it, then re-test. If your Claude Code predates hooks support, update it — the kit requires hooks. |
| Subagent spawns feel "double-issued" | Working as designed: a model-less launch is blocked once, then re-issued with an explicit model. The bounce is the routing decision being forced. |
| Every spawn asks for permission and it's exhausting | Approval mode is on. Delete the `APPROVE_SPAWNS=1` line from `~/.claude/model-routing.conf` — the routing gate itself stays active. |
| A legitimate model is blocked as off-allowlist | Add it to `availableModels` in `~/.claude/settings.json` (never a haiku-class id), or remove the `availableModels` key to drop the allowlist floor entirely. |
| A custom agent type legitimately needs no model | Gemini/Codex runtimes are exempt by exact namespace. For others, extend the namespace allowlist in `subagent-model-gate.py` (the `namespace in (...)` check). |
| The update-check line keeps appearing | A newer kit is published. Re-run the install prompt to upgrade, or set `UPDATE_CHECK=0` in `~/.claude/model-routing.conf` to silence it. |

## Uninstall (settings first, then files — surgical, honestly scoped)

1. Remove the kit's settings entries with this script. It operates at the individual hook level: kit commands are removed, any of the human's own hooks sharing a matcher entry are preserved, and an entry is dropped only when nothing of theirs remains in it.
```bash
python3 - <<'PYEOF'
import json, os, shutil, sys, time
p = os.path.expanduser("~/.claude/settings.json")
try:
    with open(p) as f:
        cfg = json.load(f)
    mode = os.stat(p).st_mode & 0o777
    shutil.copy2(p, p + ".bak-" + time.strftime("%Y%m%d%H%M%S"))
except (FileNotFoundError, json.JSONDecodeError):
    print("SETTINGS_ABSENT_OR_MALFORMED — skipping settings cleanup; continue with file deletion in step 2 and remove any kit hook entries by hand")
    sys.exit(0)
if not isinstance(cfg, dict):
    print("SETTINGS_ABSENT_OR_MALFORMED — skipping settings cleanup; continue with file deletion in step 2 and remove any kit hook entries by hand")
    sys.exit(0)
kit_cmds = (
    "python3 ~/.claude/hooks/subagent-model-gate.py",
    "python3 ~/.claude/hooks/route-log.py",
    "bash ~/.claude/hooks/model-routing-update-check.sh",
)
hooks = cfg.get("hooks", {})
if isinstance(hooks, dict):
    for event in ("PreToolUse", "PostToolUse", "SessionStart"):
        entries = hooks.get(event, [])
        if not isinstance(entries, list):
            continue
        kept_entries = []
        for m in entries:
            if not isinstance(m, dict):
                kept_entries.append(m); continue
            inner = m.get("hooks", [])
            if not isinstance(inner, list):
                kept_entries.append(m); continue
            kept = [h for h in inner if not (isinstance(h, dict) and h.get("command") in kit_cmds)]
            if kept:
                m = dict(m); m["hooks"] = kept
                kept_entries.append(m)
            # an entry whose hooks were ALL kit commands is dropped entirely
        hooks[event] = kept_entries
        if not kept_entries:
            hooks.pop(event, None)
tmp = p + ".tmp"
with open(tmp, "w") as f:
    json.dump(cfg, f, indent=2); f.write("\n")
os.chmod(tmp, mode)
os.replace(tmp, p)
print("KIT_SETTINGS_ENTRIES_REMOVED")
PYEOF
```
2. **Route log first (it is the human's data, not kit code):** ask the human — *"The route log at `~/.claude/logs/route-log.jsonl` contains your routing history. Back it up, keep it, or delete it?"* — and do what they say. Then delete the kit's files: `~/.claude/hooks/subagent-model-gate.py`, `~/.claude/hooks/route-log.py`, `~/.claude/hooks/model-routing-update-check.sh`, `~/.claude/.model-routing-check-stamp`, and `~/Downloads/model-routing-kit` if it still exists. (Skip any that don't exist.) For `~/.claude/model-routing.conf`, remove only the kit's keys — the same preserve-other-lines pattern the install uses — and delete the file only if nothing remains:
```bash
CONF=~/.claude/model-routing.conf
if [ -f "$CONF" ]; then
  grep -v '^UPDATE_CHECK=' "$CONF" | grep -v '^APPROVE_SPAWNS=' > "$CONF.tmp"
  if [ -s "$CONF.tmp" ]; then mv "$CONF.tmp" "$CONF"; echo "CONF_KIT_KEYS_REMOVED"; else rm -f "$CONF.tmp" "$CONF"; echo "CONF_DELETED_WAS_KIT_ONLY"; fi
fi
```
3. Delete everything from `<!-- model-routing-kit:begin` through the line containing `model-routing-kit:end` (inclusive) in `~/.claude/CLAUDE.md`.
4. Restart Claude Code.

**What deliberately remains, disclosed:** the timestamped `.bak-*` backups the kit created (delete them yourself if unwanted — they may contain your pre-kit settings), and the `availableModels` key. On that key, be precise: if you had NO `availableModels` before the kit, remove the whole key; if the kit EXTENDED a pre-existing list in Step 7, remove only the kit-added entries (`sonnet`, `opus`, and your default model if the kit added it) and keep your originals. The kit doesn't guess what you'd want restored. After the steps above, no kit hooks, files, or doctrine sections remain active — but note the harness itself may keep enforcing an `availableModels` key on some surfaces until you remove it by hand.