Runtime supervisor
A long-running monitor process — distinct from a hook — that watches a Claude Code session for token-budget exhaustion, oscillation hashes, and plan drift, with the authority to inject a Stop event.
Hooks fire on tool events; the runtime supervisor runs continuously beside the session. It tracks token spend against a budget, watches for repeated oscillation hashes from the detector hook, and compares the live plan against the planning-pass output to detect drift. When any threshold is breached, the supervisor injects a Stop event into the session — escalating to a human rather than letting the agent silently burn through budget.
The interaction between session, hooks, and supervisor:
session hook supervisor
│ Edit ────►│ │
│ │ PostToolUse: diff hash │
│ ├────────────────────────►│ window update: h3 h7 h3
│ Edit ────►│ │
│ ├────────────────────────►│ h3 recurs — threshold hit
│ │ │ budget check: 74% spent
│◄───────────┼─────────────────────────┤ inject Stop + summary
│ stopped │ │ notify human (Slack / PR comment)Hooks are the supervisor’s sensors; the supervisor is where the state and the authority live. It holds the token totals, the oscillation-hash window, and the original plan — and it is the only component allowed to end a session. Hooks report; the supervisor decides.
When to use
- Any unattended agent session — overnight runs, scheduled migrations, CI-triggered work.
- Solutions large enough that a single bad plan step can consume an hour of token budget before a human notices.
Distinguish from
A hook fires inside a single tool event. A supervisor watches across events, holds long-lived state (token totals, hash windows), and can act when no tool event is firing — for instance, when the agent is mid-thinking.