Claude Code Hooks

0:56 Claude Code hooks are your own commands that Claude Code runs automatically at set points in a session, such as PreToolUse before a tool call, PostToolUse after one and Stop when Claude tries to finish; they live under the "hooks" key of a settings file, and a command that exits with code 2 blocks the action. Anthropic's guide describes their purpose as deterministic control: the action happens every time, rather than when the model remembers to do it (Automate actions with hooks, read Nov 6, 2026). That is the difference from a line in CLAUDE.md, which Claude usually follows but may decide does not apply.

Quick facts

Source for the table: Hooks reference, Anthropic, read Nov 6, 2026.

What hook events are there?

The reference listed 33 events on Nov 6, 2026, grouped by how often they fire. Once per session: SessionStart and SessionEnd. Once per turn: UserPromptSubmit, Stop and StopFailure (the turn ended on an API error). Once per tool call: PreToolUse, PermissionRequest, PostToolUse and PostToolUseFailure, plus PostToolBatch after a set of parallel calls.

The rest cover narrower moments: Notification (Claude Code wants your attention), SubagentStart and SubagentStop, TaskCreated and TaskCompleted, PreCompact and PostCompact around context compaction, PreModelSwitch and PostModelSwitch, ConfigChange, CwdChanged, FileChanged, DirectoryAdded, WorktreeCreate and WorktreeRemove, InstructionsLoaded (a CLAUDE.md or rules file loaded), UserPromptExpansion, MessageDisplay, PermissionDenied (auto mode refused a call), TeammateIdle for agent teams, Setup for one-time CI preparation, and Elicitation and ElicitationResult for MCP servers that ask the user a question.

How is a hook configured?

1:26 A hook sits three levels deep: the event name, a matcher group that narrows it (for tool events, a tool name pattern such as Edit|Write or Bash), and one or more handlers. This is Anthropic's first example, a desktop notification on macOS whenever Claude Code is waiting for input, placed in ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

1. Add the block to a settings file (each event is one key inside a single "hooks" object).
2. Type /hooks in a session to see it listed with its source file.
3. Trigger the event and check the result. You can also ask Claude to write the hook for you in plain words.

Source: Automate actions with hooks, read Nov 6, 2026. On Windows, a command hook can run in PowerShell with "shell": "powershell" (Hooks reference, read Nov 6, 2026).

What does a hook receive and return?

1:54 A command hook gets the event as JSON on standard input: the session id, the working directory, the permission mode, the event name and, for tool events, tool_name and tool_input. It answers through its exit code and output. Exit code 0 is success, and any JSON it prints is applied; exit code 2 is a blocking error on events that can block, with stderr as the reason Claude sees; other codes are reported but do not block (Hooks reference, read Nov 6, 2026).

A PreToolUse hook can return permissionDecision as "allow", "deny", "ask" or "defer", with a reason, and can rewrite the tool's input with updatedInput. Plain output from SessionStart and UserPromptSubmit is added to what Claude sees, which is how teams inject context at the start of a session. An optional if field limits a handler to one permission-rule pattern such as "Bash(git *)", and async: true runs it without waiting (Hooks reference, read Nov 6, 2026).

Examples

Format every edited file. A PostToolUse hook with the matcher Edit|Write runs Prettier on the path Claude just wrote, read from the JSON with jq:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Block edits to protected files. Anthropic's guide uses a PreToolUse hook on Edit|Write that calls a script, .claude/hooks/protect-files.sh, which checks the target path against patterns such as .env, package-lock.json and .git/ and exits with code 2 on a match, so Claude is told why and changes course (Automate actions with hooks, read Nov 6, 2026).

Refuse to finish until the build passes. A Stop hook sends Claude back to work while a check fails. Anthropic's best practices page gives this one for TypeScript, which pipes compiler errors to stderr so Claude reads them:

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" } ] }
    ]
  }
}

After eight blocked stops in a row with no tool call between them, Claude Code lets the turn end; CLAUDE_CODE_STOP_HOOK_BLOCK_CAP raises that cap (read Nov 6, 2026).

Prompt and agent hooks

Besides shell commands, a handler can POST the event to a URL (http), call a tool on an MCP server (mcp_tool), ask Claude for a single-turn judgment (prompt) or start a read-only subagent with Read, Grep and Glob (agent, marked experimental). Anthropic's best practices note that a prompt or agent hook asks another model to decide, so it is not deterministic: for real enforcement it recommends a command or http hook, with onFailure: "block" when the action should also stop if the hook itself crashes (Best practices for Claude Code, read Nov 6, 2026).

Security

Command hooks run with your full user permissions and can read, change or delete anything your account can; Anthropic's reference tells users to review and test every hook before adding it (Hooks reference, read Nov 6, 2026). Its listed practices: validate input, quote shell variables ("$VAR"), reject .. in paths, use absolute script paths with ${CLAUDE_PROJECT_DIR}, and skip sensitive files.

The bigger trap is trust. In an interactive session Claude Code holds back hooks from every settings file until you accept the folder's trust dialog. In a claude -p or SDK run there is no dialog, so hooks committed in a repository's .claude/settings.json run in a folder you never trusted. Before scripting Claude Code over someone else's repository, review its .claude/ folder, start with --bare, or pass --settings '{"disableAllHooks": true}' (Hooks reference, read Nov 6, 2026). Organizations can restrict hooks with allowManagedHooksOnly, disableAllHooks and allowedHttpHookUrls.

One gap is documented: a file mentioned with @ in a prompt is inserted without a tool call, so a PreToolUse hook never sees it; a Read deny rule in permissions covers that case (Hooks reference, read Nov 6, 2026).

Frequently asked questions

What is a PreToolUse hook in Claude Code? It is a hook that runs before Claude Code executes a tool call, receiving the tool name and input as JSON. It can allow, deny, ask, defer or rewrite the call, and exiting with code 2 blocks it with your message as the reason.

Where do Claude Code hooks go? In the "hooks" object of a settings file: ~/.claude/settings.json for all your projects, .claude/settings.json to share with a repository, or .claude/settings.local.json for yourself in one repository. Plugins, skills and subagents can carry hooks too.

Can a Claude Code hook stop Claude from finishing? Yes. A Stop hook that exits with code 2 sends Claude back to work with the hook's stderr as the reason, until the check passes or the block cap (eight in a row by default) is reached.

Do Claude Code hooks work on Windows? Yes. Command hooks run in the shell Claude Code uses, and a hook can be set to PowerShell with "shell": "powershell"; Anthropic's sample scripts are written for bash, so Windows users may need to adapt them.

Are hooks the same as skills? No. A skill is instructions Claude chooses to follow; a hook is a command Claude Code itself runs at an event whether or not Claude would have. Anthropic's advice is to use hooks only for rules with no exceptions.

Sources

• Automate actions with hooks, Anthropic, read Nov 6, 2026
• Hooks reference, Anthropic, read Nov 6, 2026
• Best practices for Claude Code, Anthropic, read Nov 6, 2026
• What's new, Anthropic, read Nov 6, 2026
• Hooks in Claude Code, Claude, May 6, 2026 (video)