Hooks
sequenceDiagram participant You participant Host as Claude Code participant Agent as Subagent Host->>Host: session-start (new session) You->>Host: Send prompt Host->>Host: prompt hook Host->>Host: pre-tool hook (before Edit, Bash, Agent...) Host->>Agent: Agent call allowed Host->>Host: capture-agent-launch Agent-->>Host: Subagent stops Host->>Host: capture-agent-stop Host->>Host: capture-host-usage (turn ends)
The hooks
Section titled “The hooks”| Hook | Event | Matcher | Job |
|---|---|---|---|
session-start |
SessionStart | startup|clear|compact |
Injects using-superlite; shows the intro once per installed version. |
pre-tool |
PreToolUse | Edit|Write|NotebookEdit|Bash|PowerShell|Monitor|Agent |
Runs the kill, edit and test guards in order. |
prompt |
UserPromptSubmit | none | Records your replies, adds the compact nudge and the cost line. |
capture-agent-launch |
PostToolUse | Agent |
Appends a launch record to .superlite/metrics.jsonl. |
capture-agent-stop |
SubagentStop | none | Appends a stop record; time is the gap between the two records. |
capture-host-usage |
Stop | none | Appends a host_usage record when the host reports usage. |
The guards inside pre-tool
Section titled “The guards inside pre-tool”The first guard that denies wins. A test rewrite ends the run of the guards.
| Guard | Rule |
|---|---|
| Kill guard | Blocks taskkill /IM, pkill, killall and Stop-Process -Name, and lets kills by PID pass. |
| Edit guard | Stops the coordinator writing project code or the state files .superlite/orchestrator.json, .superlite/feature.json and .superlite/human-replies.jsonl. |
| Test guard | Rewrites raw test commands into a background superlite-cli run_tests and denies a test run in an until/while loop or with output sent to /dev/null. |
During a run the edit guard lets the coordinator write only docs/plans/**, SPEC*.md, docs/**/*.md and .superlite/**. Run hooks are active only while a run marker exists in .superlite/. Cursor uses hooks/hooks-cursor.json with its own event names.
Example: a hook stops the coordinator from fixing code itself
Section titled “Example: a hook stops the coordinator from fixing code itself”Say you approved a plan for CSV export and the build is running. A test in tests/test_export.py fails. Hooks are live now, because the run has written its marker files in .superlite/.
-
The coordinator, the main Claude Code session, tries to patch
src/reports/export.pyitself. You see the edit refused:
Real output: the refusal the hook printed in a real run, when the coordinator tried to write a fix note itself.
The
pre-toolhook runs before everyEdit,WriteandBashcall. Its edit guard denies the call with exit code 2, so the file never changes. It exists because a coordinator that edits code skips the tiers, the checkpoints and the reviews. A script enforces this, since an instruction in a prompt can drift. -
The coordinator reads the message and launches
fixer-sonnetwith a finding id and a note path. You see an agent start, not another block.The guard checks the coordinator only. The fixer is a subagent, so its edits pass. See Reviews and fixes for how fix tiers are chosen.
-
The coordinator runs
pytest tests/test_export.pyto check the fix. You see a note that the raw test run was rewritten:Claude Code · ~/social $ pytest tests/test_export.pyraw test run rewritten to a superlite-cli run_tests --fast; its summary is in .superlite/test-summary.jsonThis is the test guard. A test run in the foreground can hang the whole session, so the hook swaps it for a background run that the coordinator then waits on. If the run goes silent, the wait returns early with a
SUSPECT HANGreport instead of a frozen terminal. -
The fixer finishes and stops. Nothing prompts you here.
capture-agent-launchandcapture-agent-stopappended a record each to.superlite/metrics.jsonl, and the gap is the agent’s time. The final report reads these records for cost and speed.Directory.superlite/
- incidents.jsonl one line for the blocked edit, one for the rewritten test run
- metrics.jsonl launch and stop records per agent
- test-summary.json result of the background run
What you end up with: the fix landed through a fixer agent, the tests ran without hanging the session, and the two interventions sit in .superlite/incidents.jsonl if you want to check them. You approved nothing and typed nothing. If a hook gets malformed input it exits 0 and lets the call through, so a broken hook never stalls you.