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

Full transcript

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