Claude Code Hooks: Turn "Usually Follows" Into "Cannot Skip" — Transcript

Full transcript

1. 0:03A hook is a deterministic code at a fixed point in the loop, which means it can guarantee far more than formatting on a run you're not watching.
2. 0:10It turns a rule from Claude usually listens into Claude can't skip it.
3. 0:15Claude code fires around 30 hook events.
4. 0:17The handful you'll reach for is pre-tool use, which fires before a tool call, the enforcement primitive.
5. 0:23Post-tool use, which fires after a successful tool call.
6. 0:26This is usually where like auto-formatting or an auto-lint would go.
7. 0:30Stop, which fires when Claude wants to end his turn.
8. 0:33Refuse if conditions are met.
9. 0:34Sub-agent stop is the same signal, but for sub-agent finishing.
10. 0:38Pre-compact and post-compact, fire before and after, compaction.
11. 0:41To re-inject context after compaction, use session start with the compact matcher, not post-compact.
12. 0:46Instructions loaded, fires when a claw.md or rule file loads.
13. 0:50Audit what made it into context.
14. 0:52Session start, primes the environment.
15. 0:54Check source startup to run only on fresh starts.
16. 0:58For pre-tool use, return JSON and exit zero with a permission decision field, allow, deny, or ask.
17. 1:04There's a fourth value defer, but it only applies to non-interactive dash p runs where a calling process pauses the tool and resumes it later.
18. 1:11So you'll rarely reach for it.
19. 1:13You can also return updated input to modify the tool call without blocking, which can be useful for redacting secrets out of a bash command.
20. 1:20One catch is that updated input replaces the whole input object.
21. 1:23So echo back the fields that you aren't changing.
22. 1:27For hooks that don't return JSON, exit codes work too.
23. 1:30So here's the three numbers that matter.
24. 1:31Zero is a success, so if the standard out is JSON, Claude parses it.
25. 1:36Plain text is ignored on most events, but on session start, user prompt submit, and user prompt expansion, it gets added to context, which is exactly what makes the state preserver work.
26. 1:46Two is a blocking error.
27. 1:47So standard error gets fed back to Claude as a context.
28. 1:50This is the blocking exit code almost everywhere where the loan exception WorkTreeCreate aborts any non-zero code.
29. 1:57Watch out because exit one feels like an error, but it actually does not block.
30. 2:01So Claude runs the command anyway.
31. 2:02And then anything else is non-blocking and is locked.
32. 2:05Exit2 can block stop, which is how you say, no, you're not done.
33. 2:08PostTool use fires after the tool already ran, so it's too late to stop the call, though it can still feed text back to Claude.
34. 2:15A few events ignore blocking, like notification, session start, and file change, show your standard error, and carry on.
35. 2:23A pretool used guardrail that redax instead of blocking.
36. 2:26The matcher picks the tool to watch, say, bash, and an optional if clause narrows it to a specific command.
37. 2:32So returning deny stops a dangerous call.
38. 2:35The lesser known move is return updated input to rewrite the call, which is how you strip a secret out of a command and still let it run.
39. 2:44When Claude compacts a long conversation, it drops a lot of details, but a session start hook with the compact matcher runs right after a print short summary of the files you've been working on.
40. 2:55That summary goes back into context, so Claude picks up where it was instead of starting cold.
41. 3:01Hooks turns a rule Claude usually follows into one that it always follows.
42. 3:08Reach past auto formatting, guard tools with pre-tool use, gate the turn with stop, and preserve stay across compact.
43. 3:14The setup pays back the first time it catches something on a run you weren't watching.