Claude Code hooks are deterministic automation points that run when specific events occur in a Claude Code session. Current Claude Code documentation supports command hooks, HTTP hooks, MCP-tool hooks, prompt hooks, and agent-based hooks across lifecycle events such as SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, SubagentStart\/Stop, WorktreeCreate\/Remove, PreCompact\/PostCompact, ConfigChange, FileChanged, and SessionEnd.<\/p>\n
Within Claude Engineering<\/a>, hooks are the enforcement and integration layer around the model’s agentic loop. A hook can block a dangerous command before execution, run tests after a file edit, attach context, notify external systems, or enforce organization policy without relying on Claude to remember a prompt instruction.<\/p>\n The important distinction is that hooks are code. They should be versioned, tested, least-privilege, fast enough for their cadence, and designed so failure does not create confusing session behavior.<\/p>\n Selecting the wrong event often creates race conditions. A post-hook cannot prevent the destructive command that already ran, and a pre-hook cannot inspect the final file content produced after an edit.<\/p>\n Map the lifecycle first, then place the hook where it can make the intended decision with the evidence it needs.<\/p>\n Tool-related events can fire many times per turn. Current hook configuration lets matcher groups filter on tool names, agent types, session start modes, notification types, and other event-specific fields.<\/p>\n A PreToolUse hook intended only for Bash should not spawn on every Read or Grep call. Narrow matchers reduce latency and make the resulting behavior easier to understand.<\/p>\n Regular-expression matchers are useful for MCP tool families, but exact matching is safer when the tool name is known.<\/p>\n The current docs show PreToolUse hooks inspecting a Bash command and returning a deny decision before execution.<\/p>\n This is stronger than a CLAUDE.md sentence such as \u201cnever run rm -rf\u201d because the client enforces the decision independently of what Claude chooses to do.<\/p>\n Use this for destructive commands, protected deployment paths, production database tools, credential files, or organization-specific prohibitions that should never depend on model compliance alone.<\/p>\n Command hooks receive JSON input on stdin and can return no decision, block\/deny, add context, or emit structured hook-specific output depending on the event.<\/p>\n Claude Code distinguishes normal success, blocking exit behavior, and other failures.<\/p>\n Hook scripts should emit valid JSON only when expected and log diagnostics somewhere appropriate; malformed stdout can turn a simple policy check into confusing hook failures.<\/p>\n A post-edit hook can run targeted unit tests, formatting, linting, or static analysis after Write\/Edit operations.<\/p>\n Keep the validation proportional. Running the entire monorepo integration suite after every one-line edit will make Claude Code unusable and encourage developers to disable hooks.<\/p>\n Use quick local checks per edit and reserve broader suites for Stop, pre-commit, CI, or explicit task boundaries.<\/p>\n Current Claude Code supports asynchronous hooks for use cases that do not need to block the next model step.<\/p>\n This fits notifications, logging, metrics, slower background checks, or external system updates.<\/p>\n Do not make a security-critical deny decision async; by definition the agent can continue before that hook finishes.<\/p>\n HTTP hook handlers let Claude Code send event context to a service rather than spawning a local script.<\/p>\n This can centralize organization policy, audit, or approval logic, but it introduces network latency and availability dependencies.<\/p>\n Use current HTTP hook URL allowlists and environment-variable restrictions so project code cannot redirect sensitive event payloads to arbitrary endpoints.<\/p>\n Some events support prompt-based or agent-based hooks that ask a model or subagent to evaluate conditions rather than running a deterministic shell test.<\/p>\n This is useful for semantic checks such as \u201cdid the final response address all requested requirements?\u201d or \u201cis this change ready to stop?\u201d<\/p>\n Keep deterministic security\/permission rules in code where possible; use model-based hooks for judgments that genuinely require language\/code understanding.<\/p>\n User hooks in Put a control at the narrowest level that still matches the authority that owns it.<\/p>\n A company security rule belongs in managed settings; a project formatter belongs in the repository; a personal notification does not belong in team source control.<\/p>\n Test matching and nonmatching commands, unusual quoting, paths with spaces, command chaining, tool failures, timeout, malformed input, and unavailable dependencies.<\/p>\nChoose the hook event that matches the control boundary<\/h3>\n
PreToolUse<\/code> is appropriate when you need to block or alter a tool call before it executes. PostToolUse<\/code> is better for validation after a successful action. Stop<\/code> runs after Claude finishes a response, while SessionStart<\/code> is useful for environment preparation or context setup.<\/p>\nMatchers keep high-frequency hooks narrow<\/h3>\n
PreToolUse can enforce hard command boundaries<\/h3>\n
Exit codes and JSON outputs have explicit semantics<\/h3>\n
PostToolUse is a natural place for tests and formatters<\/h3>\n
Async hooks are useful for nonblocking telemetry and background validation<\/h3>\n
HTTP hooks connect sessions to central policy services<\/h3>\n
Prompt and agent hooks can perform higher-level review<\/h3>\n
Hook scope should match ownership<\/h3>\n
~\/.claude\/settings.json<\/code> are personal. Project hooks in .claude\/settings.json<\/code> can be shared in source control. Managed policy hooks can enforce organization requirements. Plugins, skills, and subagents can also contribute hooks in their own scope.<\/p>\nHooks should be tested against failure and bypass attempts<\/h3>\n