model-switch-sentinel

Model Switch Sentinel

You are setting up a sentinel that watches the session model per turn and reacts when it silently falls back to a cheaper model. The recovery has to be SAFE: it must not interrupt live work, it must not trust a brief blindly, and it must not let degraded output silently become the foundation for later work.

The package gives you two portable, runnable pieces and one documented seam:

• reference/model-sentinel.example.py - the per-turn hook. It detects the fallback, does a busy check first, tracks the span of fallback turns, and emits events. It never switches the model itself and never blocks a tool.
• scripts/brief-scrub.py - the mechanical scrubber that neutralizes turn-boundary and markup injection signatures in the context brief before it is injected into the restored session.
• The SEAM: switch-back, context clear, and restore are harness-specific. The hook emits events; your automation performs the actual plumbing. You wire it at the config on_event_command field. The package deliberately ships no environment-specific plumbing.

Ring-and-ask is the safe default throughout. Busy heuristics are imperfect, so the sentinel prefers to alert a human and wait over taking an automatic action on a wrong guess.

Step 1: Inspect the setup

• Settings location. Check, in order, for a hooks-capable settings file: ~/.claude/settings.json (user scope), .claude/settings.json (project scope), .claude/settings.local.json (local scope). Confirm which scope the user wants and read the chosen file.
• Intended model marker. Ask which model the session is SUPPOSED to run on. You need a substring that appears in that model's harness id (case insensitive). Any observed model lacking that marker is treated as a fallback.
• Busy probe. Ask how the user can tell, mechanically, that work is in flight. This becomes busy_probe_command: a shell command that exits 0 when busy and non-zero when idle (for example, a check for an active lock file, a task file with open items, or a queue depth). Warn the user that any such heuristic is imperfect, which is exactly why the default is to ring and wait. If they have no reliable probe, leave it empty: the sentinel then stays in alert-and-wait and never claims idle on its own.
• Automation seam. Ask what should perform the actual switch-back, clear, and restore in their harness. This becomes on_event_command: a shell command the hook runs once per event, with the event JSON on stdin. If they are not ready to automate, leave it empty and consume the handoff JSONL manually.