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.
Within Claude Engineering, 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.
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.
Choose the hook event that matches the control boundary
PreToolUse is appropriate when you need to block or alter a tool call before it executes. PostToolUse is better for validation after a successful action. Stop runs after Claude finishes a response, while SessionStart is useful for environment preparation or context setup.
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.
Map the lifecycle first, then place the hook where it can make the intended decision with the evidence it needs.
Matchers keep high-frequency hooks narrow
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.
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.
Regular-expression matchers are useful for MCP tool families, but exact matching is safer when the tool name is known.
PreToolUse can enforce hard command boundaries
The current docs show PreToolUse hooks inspecting a Bash command and returning a deny decision before execution.
This is stronger than a CLAUDE.md sentence such as “never run rm -rf” because the client enforces the decision independently of what Claude chooses to do.
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.
Exit codes and JSON outputs have explicit semantics
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.
Claude Code distinguishes normal success, blocking exit behavior, and other failures.
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.
PostToolUse is a natural place for tests and formatters
A post-edit hook can run targeted unit tests, formatting, linting, or static analysis after Write/Edit operations.
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.
Use quick local checks per edit and reserve broader suites for Stop, pre-commit, CI, or explicit task boundaries.
Async hooks are useful for nonblocking telemetry and background validation
Current Claude Code supports asynchronous hooks for use cases that do not need to block the next model step.
This fits notifications, logging, metrics, slower background checks, or external system updates.
Do not make a security-critical deny decision async; by definition the agent can continue before that hook finishes.
HTTP hooks connect sessions to central policy services
HTTP hook handlers let Claude Code send event context to a service rather than spawning a local script.
This can centralize organization policy, audit, or approval logic, but it introduces network latency and availability dependencies.
Use current HTTP hook URL allowlists and environment-variable restrictions so project code cannot redirect sensitive event payloads to arbitrary endpoints.
Prompt and agent hooks can perform higher-level review
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.
This is useful for semantic checks such as “did the final response address all requested requirements?” or “is this change ready to stop?”
Keep deterministic security/permission rules in code where possible; use model-based hooks for judgments that genuinely require language/code understanding.
Hook scope should match ownership
User hooks in ~/.claude/settings.json are personal. Project hooks in .claude/settings.json 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.
Put a control at the narrowest level that still matches the authority that owns it.
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.
Hooks should be tested against failure and bypass attempts
Test matching and nonmatching commands, unusual quoting, paths with spaces, command chaining, tool failures, timeout, malformed input, and unavailable dependencies.
A hook that blocks rm -rf only when written exactly one way may provide false confidence if shell equivalents bypass it.
Claude Code Security Reviews is related because hooks can enforce pre-execution controls while security review finds code-level vulnerabilities.
Hooks are successful when deterministic policy surrounds probabilistic reasoning
Claude Code is strongest when the model explores and reasons freely inside boundaries the client enforces. Hooks provide those boundaries and integration points without stuffing every operational rule into the prompt.
The mature hook system is narrow, observable, fast, versioned, centrally governed where needed, and clear enough that developers know why a tool call was blocked or a validation step ran.
Performance budgets should exist for hooks. A PreToolUse hook that launches a heavy interpreter or network request on every Read call can add seconds to routine work. Measure invocation frequency and latency, cache stable policy data, and use the optional if/matcher filters to avoid spawning the handler when it cannot affect the decision.
Hooks that modify files should be used sparingly because they create side effects Claude may not expect. Auto-formatters are usually safe and obvious; scripts that rewrite configuration, regenerate code, or update dependency files after every edit can make diffs difficult to understand. If a hook changes files, ensure those changes are visible to the next model turn and to the human reviewer.
Project hooks should be reviewed like build scripts. A malicious or careless repository can commit a hook that executes commands when a developer opens Claude Code. Workspace trust and organization-managed hook restrictions therefore matter, especially when cloning unfamiliar repositories. Do not assume a configuration file is harmless because it is “only Claude settings.”
Managed settings can centralize nonnegotiable controls. Enterprises can enforce approved hooks and restrict user/project hook behavior so local repositories cannot disable organization security policy. Use this for data-exfiltration boundaries, protected production commands, or audit events that must apply consistently across teams.
Hook outputs should be actionable. When a tool call is denied, explain the policy reason and the safe alternative—such as “production deploy requires the release workflow; use make staging-deploy here.” Vague denial messages encourage users to bypass the control; good messages turn enforcement into discoverable workflow documentation.
Subagent hooks deserve explicit testing because tool events inside subagents fire configured hooks too. A hook that assumes every Bash call comes from the main conversation can mis-handle background research or isolated worktree agents. Current hook inputs include agent identifiers/types, allowing policy to distinguish where the action originated.
Configuration-change hooks can protect the guardrails themselves. A ConfigChange event can audit or block changes to settings during a session. This is useful when a repository or agent could otherwise relax permission rules, disable hooks, or alter tool configuration before performing a restricted action.
Combine hooks with Claude Code Custom Commands when a team wants both an ergonomic supported path and enforcement around it. Commands give developers a repeatable entry point; hooks verify that the surrounding safety checks run regardless of whether the developer remembers the preferred command.
Hook version compatibility should be part of upgrades. Claude Code adds events and fields over time, and older client versions may not support newer hook semantics. If a repository depends on a specific event such as WorktreeCreate or ConfigChange, document the minimum Claude Code version and test upgrades on a representative project before organization-wide rollout.
Security-sensitive hooks should fail in the safer direction where appropriate. If a policy service is unreachable, decide explicitly whether the tool call is denied, deferred, or allowed with an audit warning. The right answer depends on the control: an optional metrics hook can fail open; a production-deploy authorization hook may need to fail closed.
Keep hook code small and composable. A thin handler that validates input and calls a tested policy/library is easier to reason about than a 500-line shell script containing parsing, network calls, business logic, and side effects. Hooks are easier to trust when their decision path is obvious.
Review hook behavior like any other enforcement code: version it, test failure modes, and keep the output understandable to developers. A policy hook that silently blocks normal work or can be bypassed by routine environment differences will quickly lose trust and invite workarounds.
