Claude Code
Claude Code hooks: what they are and how teams use them
A plain guide for engineering leads. Every fact about hooks is taken from Anthropic's own documentation as read on 6 November 2026. Claude Code changes often, so check the cited pages before you act.
Claude Code hooks are handlers, most often shell commands, that Claude Code runs automatically at set points in a session, such as before a tool call or after Claude finishes responding. Anthropic's documentation (read 6 November 2026) says they give deterministic control: certain actions always happen instead of relying on the model to choose to run them. This page covers the events, where to configure hooks, how a hook blocks an action, and how an organization can control which hooks run.
plain answer
What are Claude Code hooks?
Claude Code hooks are user-defined shell commands, and other handlers, that Claude Code runs at specific points in its lifecycle. Anthropic's hooks guide says they give deterministic control: certain actions always happen rather than relying on the model to choose to run them. It lists uses such as formatting code, sending notifications, validating commands and enforcing project rules.
A hook can be one of five types: command, http, mcp_tool, prompt or agent. Prompt and agent hooks use a Claude model to judge a condition. Anthropic's reference marks agent hooks as experimental and says they may change.
Source: Anthropic, Automate actions with hooks (https://code.claude.com/docs/en/hooks-guide) and Hooks reference (https://code.claude.com/docs/en/hooks), read 6 November 2026.
reference
What events can a Claude Code hook run on?
A hook is attached to an event. Anthropic's reference lists many events across a session. The ones most teams meet first are SessionStart, when a session begins or resumes; UserPromptSubmit, when a prompt is submitted and before Claude processes it; PreToolUse, before a tool call executes, which can block it; PostToolUse, after a tool call succeeds; Stop, when Claude finishes responding; and SessionEnd. Other events cover subagents, tasks, permission requests, context compaction, file changes and configuration changes.
Some events and options need a minimum Claude Code version, so check the reference for the version you run.
Source: Anthropic, Hooks reference and Automate actions with hooks (links above), read 6 November 2026.
how to
How do you set up a Claude Code hook?
You add a hooks block to a settings file. Each entry names an event, an optional matcher that narrows when it fires, and a handler. Without a matcher a hook fires on every occurrence of its event, so Anthropic's examples match on tool names such as Edit or Write.
Where you put the block sets its scope. ~/.claude/settings.json covers all your projects and stays on your machine. .claude/settings.json covers one project and can be committed to the repository. .claude/settings.local.json is project-only and not shared. Managed policy settings apply across an organization. Plugins, skills and subagents can also carry hooks. Running /hooks in Claude Code lists what is configured.
Source: Anthropic, Automate actions with hooks, section Configure hook location (https://code.claude.com/docs/en/hooks-guide), read 6 November 2026.
how to
How does a Claude Code hook block an action?
A hook blocks by exiting with code 2 and writing a reason to stderr. On events that can block, Claude Code then stops the action: a PreToolUse hook blocks the tool call and a UserPromptSubmit hook rejects the prompt. Exit 2 blocks even if the hook also prints JSON. On most events any other exit code is a non-blocking error and the action goes ahead, unless the hook sets onFailure to block (Claude Code v2.1.295 or later).
Exit 0 from a PreToolUse hook is not an approval: the call still goes through the normal permission flow. A PostToolUse hook cannot undo anything, because the tool has already run. Anthropic also says its if filter, which narrows a hook by tool arguments, is best-effort, and that you should use the permission system rather than a hook to enforce a hard allow or deny.
Source: Anthropic, Hooks reference and Automate actions with hooks (links above), read 6 November 2026.
security
Can an organization control which Claude Code hooks run?
Yes, through managed settings. Anthropic documents allowManagedHooksOnly: when an administrator sets it in managed settings, hooks from user, project, local and plugin settings are blocked, except hooks from plugins that managed settings force-enable. Anthropic also says disableAllHooks cannot switch off managed hooks from outside managed settings.
A hook runs your own commands, so treat each one like code. Anthropic's guide links a security considerations section and says to review it before deploying hooks in shared or production environments. Anthropic says command hooks run with your full user permissions and can modify, delete or access any file your account can reach, and to review and test every hook command before you add it (read 6 November 2026).
Source: Anthropic, Hooks reference and Automate actions with hooks (links above), read 6 November 2026.
kriv role
Where Kriv helps
Kriv AI trains engineering teams on Claude Code and helps them agree in writing which checks belong in hooks, which belong in permissions and managed settings, and who owns each one. Our Claude Code training page describes setting up skills, hooks and MCP integrations once for a whole team. Kriv AI has achieved the Select partner tier in the Claude Partner Network Services Track.
Kriv did not build Claude Code and does not replace Anthropic's documentation. Your engineers own the scripts and the settings.
limits
What this page could not confirm
Anthropic's pages carry no last-updated date. We did not run any hook ourselves. Event names, options and version requirements change, so check Anthropic's current pages and your own Claude Code version before you rely on anything here.
Straight answers
Frequently asked questions about Claude Code hooks: what they are and how teams use them
Are Claude Code hooks the same as permissions?
No. Hooks run your own handlers at events. Permissions are Claude Code's separate permission rules. Anthropic says to use the permission system rather than a hook to enforce a hard allow or deny (read 6 November 2026).
Where do I put Claude Code hooks so the whole team gets them?
In .claude/settings.json inside the project, which Anthropic says can be committed to the repository. For an organization, Anthropic lists managed policy settings (read 6 November 2026).
Does a Claude Code hook run on every tool call?
Without a matcher, a hook fires on every occurrence of its event. A matcher such as Edit|Write narrows it to those tools (Anthropic, read 6 November 2026).
Can a Claude Code hook undo an edit?
Not a PostToolUse hook. Anthropic says it cannot undo actions because the tool has already run. A PreToolUse hook can block the call before it runs (read 6 November 2026).
Can Kriv AI set up hooks for our team?
Kriv AI trains teams and helps decide what to enforce and who owns it. Your engineers write and own the scripts and settings.
Talk to the team that would do the work
Bring your requirements to a working session with the person who'll actually deliver.
Book a Discovery Call