Hooks

Hooks are user-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. The key distinction is that while CLAUDE.md instructions are contextual and may be ignored, hooks are code that runs regardless of Claude's decisions. If an action must occur at a fixed point—before every commit, after each file edit—it should be implemented as a hook.

Verified event names include: SessionStart, SessionEnd, Setup, UserPromptSubmit, UserPromptExpansion, Stop, StopFailure, PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied, PreCompact, PostCompact, Notification, SubagentStart, SubagentStop, InstructionsLoaded, and FileChanged.

Configuration follows a three-level structure: select a hook event, add a matcher group to filter when it fires (e.g., 'Bash'), and define handlers. Handlers can be of type command, http, mcp_tool, prompt, or agent. Verified configuration locations include ~/.claude/settings.json (global), .claude/settings.json (project-specific), .claude/settings.local.json (project-specific and gitignored), a plugin's hooks/hooks.json, and skill or agent frontmatter (scoped to the component's active duration).

Exit code semantics are critical: an exit code of 0 signifies success, allowing Claude Code to parse JSON output for subsequent decisions. An exit code of 2 indicates a blocking error, preventing the tool call and displaying stderr to Claude. Other non-zero exit codes are treated as non-blocking errors.

Crucially, a PreToolUse hook can return a permissionDecision of deny to prevent a tool call from executing. This provides a powerful mechanism for enforcing constraints or validating conditions before actions are taken. For managing hooks, the Hooks Management skill can translate natural language into validated configurations, and the Debug Hooks skill offers a workflow for troubleshooting issues.