Pre/Post/Stop Hook Architecture

Claude Code hooks are interceptors that run at specific points in Claude's execution cycle. They are the mechanism that transforms Claude from an interactive assistant into a self-correcting system. There are three types, and each fires at a different moment in the lifecycle.

PreToolUse hooks fire before Claude executes a tool — before it writes a file, runs a bash command, or performs a search. This is your opportunity to block dangerous operations, validate inputs, or modify commands before they execute. PostToolUse hooks fire after Claude completes a tool execution — after the file is written, after the command finishes. This is your opportunity to run formatters, validators, or post-processing scripts on the output. Stop hooks fire when Claude finishes a complete task and is waiting for your next input. This is your opportunity to run comprehensive quality checks on the entire body of work Claude just produced.

Hooks are configured in your Claude Code settings.json — not in CLAUDE.md. This is an important distinction. CLAUDE.md is instructions that Claude interprets. settings.json is configuration that the Claude Code runtime enforces. A hook runs regardless of what Claude "wants" to do. It is a hard constraint, not a soft suggestion.

The configuration structure specifies the hook type, the file pattern to match (which tools or events trigger this hook), and the script to run. The script can be any executable — a bash script, a Node.js file, a Python script. The only requirement is that it communicates with Claude through a specific protocol: stdout for messages that Claude should see and act on, stderr for debug logging that Claude ignores. This protocol is simple but strict, and violating it is the most common source of hook failures.

1. PreToolUse: The Gatekeeper Fires before Claude executes a tool. Use for: blocking destructive commands (rm -rf, DROP TABLE), validating file paths before writes, requiring confirmation for production deployments. The hook can return "approve" to allow the action or "block" with a reason to prevent it.
2. PostToolUse: The Formatter Fires after Claude completes a tool execution. Use for: auto-formatting code after file edits (Prettier, ESLint --fix), running quick validation checks, updating related files. The hook receives the tool output and can modify it before Claude sees the result.
3. Stop: The Quality Gate Fires when Claude finishes a task and is ready for the next prompt. Use for: running the full test suite, type checking the codebase, linting all changed files, auto-committing if all checks pass. The most powerful hook type because it operates on the complete body of work.