Two hooks that record every model switch and stop the ones you never agreed to

Recording belongs to PostModelSwitch; only the decision belongs to PreModelSwitch

This is the design choice worth making before you write any code. My first attempt put both the logging and the policy check into PreModelSwitch, since standing right before the switch means you can see both sides of it.

That turns out to be the wrong place. When a PreModelSwitch hook is canceled at its timeout, the model switch is blocked. Most hook events fail open on a timeout; this one fails closed.

So a logging step that simply took too long stops the switch from happening at all. You wanted a log line, and instead your model routing silently stopped working — with a cause that is genuinely hard to see from the outside. In an unattended run, nobody is watching the screen when it happens.

Hence the split.

The blocking side stays fast; the recording side gets the freedom. On the related question of how much a hook should print at all, I wrote up the quiet-on-success pattern in Never pipe a validation script's output straight back through a hook.

Building the guard

We want to block switches to unapproved models during unattended runs only. Interactive switches have a human in front of them, so they stay out of scope.

Start with an allowlist. Put one model ID per line in .claude/model-allowlist.txt.

claude-haiku-4-5-20251001
claude-sonnet-5

The hook reads JSON on stdin and exits with code 2 when the switch should not proceed. For most hook events, exit code 2 is the only exit code that blocks through the exit code alone.

#!/usr/bin/env bash
# .claude/hooks/model-switch-guard.sh
# PreModelSwitch: decision only. Nothing heavy goes in here.
set -uo pipefail
 
INPUT=$(cat)
ALLOW_FILE="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/model-allowlist.txt"
 
# Let everything through unless this is an unattended run.
# An interactive switch was somebody's deliberate choice.
[[ "$INPUT" == *'"source":"sdk"'* || "$INPUT" == *'"source": "sdk"'* ]] || exit 0
 
# Pull out to_model with parameter expansion — no subprocess.
TO="${INPUT#*\"to_model\":}"
TO="${TO#*\"}"
TO="${TO%%\"*}"
 
# No allowlist means no blocking. A missing config file
# should never be the thing that halts your work.
[ -f "$ALLOW_FILE" ] || exit 0
grep -qxF "$TO" "$ALLOW_FILE" && exit 0
 
echo "Unattended run attempted a switch to an unapproved model: ${TO}" >&2
echo "Allowlist: ${ALLOW_FILE}" >&2
exit 2

Feeding it three sample payloads:

$ echo '{"to_model":"claude-opus-5","source":"sdk"}' | ./model-switch-guard.sh
Unattended run attempted a switch to an unapproved model: claude-opus-5
Allowlist: /tmp/hooktest/.claude/model-allowlist.txt
exit=2
 
$ echo '{"to_model":"claude-sonnet-5","source":"sdk"}' | ./model-switch-guard.sh
exit=0
 
$ echo '{"to_model":"claude-opus-5","source":"picker"}' | ./model-switch-guard.sh
exit=0

The third case matters most. A guard that also blocks the picker turns into an obstacle the moment you want to try something by hand.

Why the JSON parsing avoids Python

My first version piped the payload through python3 to read to_model and source. That version is plainly easier to read. Running each variant twenty times on my machine gave these numbers:

Almost all of the difference is interpreter startup. Even 29 ms sits nowhere near a timeout, and on those numbers alone the readable version wins. I went with the fast one because of what PreModelSwitch does when it runs out of time: slow means blocked. Leaving headroom now keeps room for a heavier check later.

These are numbers from my environment, not a benchmark you should adopt. Measure your own. What transfers is the shape of the cost — interpreter startup as a fixed overhead on every invocation — not the milliseconds.

Building the recorder

The PostModelSwitch side appends one JSONL line per switch. Nothing here can affect the switch, so readability wins.

#!/usr/bin/env bash
# .claude/hooks/model-switch-log.sh
# PostModelSwitch: recording only.
set -uo pipefail
 
LOG_DIR="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/logs"
mkdir -p "$LOG_DIR"
export LOG="${LOG_DIR}/model-switch-$(date -u +%Y-%m).jsonl"
 
python3 -c '
import json, sys, os, datetime
 
d = json.load(sys.stdin)
row = {
  "at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds"),
  "session": d.get("session_id"),
  "from": d.get("from_model"),
  "to": d.get("to_model"),
  "requested": d.get("requested_model"),
  "source": d.get("source"),
  "context_tokens": d.get("context_tokens"),
  "cache_warm": d.get("prompt_cache_warm"),
  "cache_ttl": d.get("cache_ttl"),
  "cache_write_usd": d.get("estimated_cache_write_usd"),
  "pricing": d.get("pricing"),
}
with open(os.environ["LOG"], "a", encoding="utf-8") as f:
    f.write(json.dumps(row, ensure_ascii=False) + "\n")
' 2>>"${LOG_DIR}/model-switch-error.log"
 
# The switch is already done by now. Do not turn a logging
# failure into something that looks like a switching failure.
exit 0

That explicit exit 0 is deliberate. For SessionStart, SubagentStart, and PostModelSwitch, exit code 2 causes Claude Code to render the stderr in the transcript as a hook error. A failed append does not deserve that treatment.

A written line looks like this:

{"at": "2026-09-02T03:08:32+00:00", "session": "s1", "from": "claude-haiku-4-5-20251001", "to": "claude-sonnet-5", "requested": "claude-sonnet-5", "source": "sdk", "context_tokens": 48210, "cache_warm": true, "cache_ttl": "5m", "cache_write_usd": 0.9042, "pricing": "catalog"}

Monthly files match how I read the numbers. If you are watching the weekly ceiling, cut them weekly instead.

Registering both hooks

Add the two events to your project's .claude/settings.json.

{
  "hooks": {
    "PreModelSwitch": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/model-switch-guard.sh",
            "timeout": 5
          }
        ]
      }
    ],
    "PostModelSwitch": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/model-switch-log.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

Omitting matcher fires the hook on every switch. If you later want to narrow it, note that for PreModelSwitch the matcher is evaluated against the canonical name Claude Code derives from to_model. Recording everything first and narrowing afterwards is the safer order — you cannot pick a filter for behavior you have not observed yet.

The 5-second and 15-second timeouts are the earlier split written into configuration: short for the decision, generous for the record.

Once registered, /hooks shows you what got loaded. When a hook does not fire and the logs are not telling you why, Debugging Claude Code hooks in production walks through the isolation steps, and Claude Code Hooks: design decisions for the core eight, now that there are 33 events covers how the events relate to each other.

Reading the log: counts, sources, and round trips

Once the JSONL has some volume, aggregate it. Counts alone are not what you are after — you want the breakdown by source, and the pairs that go back and forth.

#!/usr/bin/env python3
"""Aggregate recorded switches by source, and surface round trips."""
import json, sys, collections
 
rows = []
for path in sys.argv[1:]:
    with open(path, encoding="utf-8") as f:
        rows += [json.loads(l) for l in f if l.strip()]
 
by_source = collections.Counter()
cost_by_source = collections.defaultdict(float)
pairs = collections.Counter()
 
for r in rows:
    s = r.get("source") or "unknown"
    by_source[s] += 1
    cost_by_source[s] += r.get("cache_write_usd") or 0.0
    pairs[(r.get("from"), r.get("to"))] += 1
 
total = sum(cost_by_source.values())
print(f"{len(rows)} switches / estimated cache writes ${total:.4f}")
for s, n in by_source.most_common():
    print(f"  source={s:<8} {n:>3}x  ${cost_by_source[s]:.4f}")
 
# A pair that appears in both directions is worth a second look.
seen = set()
for (a, b), n in pairs.items():
    if (b, a) in pairs and (b, a) not in seen:
        seen.add((a, b))
        print(f"  round trip: {a} <-> {b}  {n}+{pairs[(b,a)]}x")

Run against the three sample rows:

3 switches / estimated cache writes $1.2981
  source=sdk        2x  $1.1473
  source=command    1x  $0.1508
  round trip: claude-haiku-4-5-20251001 <-> claude-sonnet-5  2+1x

Round trips get their own line on purpose. When a single session bounces between a light and a heavy model, either the work is sliced too finely or two switching conditions are fighting each other. Neither shape shows up in a raw count.

The cache write that rides along with every switch

There is a reason estimated_cache_write_usd is in the payload at all.

Changing models changes the prompt cache prefix. Whatever was warm before the switch is no longer usable, and the next turn starts with a cache write. The higher prompt_cache_warm was at the moment of the switch, the more you just threw away.

This is where the September 1 pricing change gets easy to misread. With Claude Fable 5.1, the cut applies to cache reads only — down 75% from the equivalent of $1.00 to $0.25 per MTok. Input at $10 and output at $50 per MTok are unchanged, and cache writes were not reduced either.

Anthropic published an index from four weeks of August 2026 usage: roughly 25% lower for a typical workload, up to roughly 45% lower for context- and tool-heavy agentic work. Both figures assume cache reads make up a large share of the bill. A workload that switches often, discarding the cache each time, sits at the low end of that share.

Which is why "25% cheaper" needed checking against my own numbers before I believed it. In my case, having sliced the unattended runs into small stages translated directly into switch count. The switch count, it turns out, is a cost question — and I had no way to see that until the log existed.

Where to start

Roll it out in four stages:

1. Drop in .claude/hooks/model-switch-log.sh and register it on PostModelSwitch only. Nothing gets blocked yet
2. Let it run for a week, then read the breakdown and round trips with switch-report.py
3. From the models that actually appear, write the ones you sanction for unattended work into .claude/model-allowlist.txt
4. Register model-switch-guard.sh on PreModelSwitch, with a short timeout

Do steps 1 and 2 first and leave the guard for later. What is worth blocking is not something you can decide before you have seen what actually happens.

I prefer this order for my own automation: drawing the line after observing holds up better than drawing it in advance. My own allowlist is waiting on two weeks of data before I settle it.