Claude Code hooks explained: config structure, matchers, and a copy-paste PreToolUse guard

Short summary

A detailed technical walkthrough of Claude Code hooks: deterministic shell commands that fire at fixed lifecycle points and can block, allow, or reshape tool calls. The post explains the three-level config structure (event, matcher, handler), the five handler types, and the critical distinction between exit-code-only and JSON-on-stdout communication modes. It includes a copy-paste PreToolUse guard that blocks recursive rm, and highlights breaking changes to the JSON output format where PreToolUse now requires hookSpecificOutput with permissionDecision instead of the deprecated top-level decision field.

• •Hooks are deterministic commands fired at lifecycle points (SessionStart, PreToolUse, PostToolUse, etc.) that can block or allow tool calls
• •Matcher groups filter by tool name; regex matchers use JS RegExp.test so 'Edit' also matches 'NotebookEdit' — use ^Edit$ for exact matches
• •PreToolUse JSON output changed: use hookSpecificOutput.permissionDecision (allow/deny/ask/defer) instead of deprecated top-level decision field

Generated with AI, which can make mistakes.