← Back to daily report

hooks-guide.md

Changed on 2026-01-30 23:01:27 EST

Unified Diff

--- a/hooks-guide.md
+++ b/hooks-guide.md
@@ -2,148 +2,156 @@
 > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
 > Use this file to discover all available pages before exploring further.
 
-# Get started with Claude Code hooks
-
-> Learn how to customize and extend Claude Code's behavior by registering shell commands
-
-Claude Code hooks are user-defined shell commands that execute at various points
-in Claude Code's lifecycle. Hooks provide deterministic control over Claude
-Code's behavior, ensuring certain actions always happen rather than relying on
-the LLM to choose to run them.
+# Automate workflows with hooks
+
+> Run shell commands automatically when Claude Code edits files, finishes tasks, or needs input. Format code, send notifications, validate commands, and enforce project rules.
+
+Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control over Claude Code's behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them. Use hooks to enforce project rules, automate repetitive tasks, and integrate Claude Code with your existing tools.
+
+For decisions that require judgment rather than deterministic rules, you can also use [prompt-based hooks](#prompt-based-hooks) or [agent-based hooks](#agent-based-hooks) that use a Claude model to evaluate conditions.
+
+For other ways to extend Claude Code, see [skills](/en/skills) for giving Claude additional instructions and executable commands, [subagents](/en/sub-agents) for running tasks in isolated contexts, and [plugins](/en/plugins) for packaging extensions to share across projects.
 
 <Tip>
-  For reference documentation on hooks, see [Hooks reference](/en/hooks).
+  This guide covers common use cases and how to get started. For full event schemas, JSON input/output formats, and advanced features like async hooks and MCP tool hooks, see the [Hooks reference](/en/hooks).
 </Tip>
 
-Example use cases for hooks include:
-
-* **Notifications**: Customize how you get notified when Claude Code is awaiting
-  your input or permission to run something.
-* **Automatic formatting**: Run `prettier` on .ts files, `gofmt` on .go files,
-  etc. after every file edit.
-* **Logging**: Track and count all executed commands for compliance or
-  debugging.
-* **Feedback**: Provide automated feedback when Claude Code produces code that
-  does not follow your codebase conventions.
-* **Custom permissions**: Block modifications to production files or sensitive
-  directories.
-
-By encoding these rules as hooks rather than prompting instructions, you turn
-suggestions into app-level code that executes every time it is expected to run.
-
-<Warning>
-  You must consider the security implication of hooks as you add them, because hooks run automatically during the agent loop with your current environment's credentials.
-  For example, malicious hooks code can exfiltrate your data. Always review your hooks implementation before registering them.
-
-  For full security best practices, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.
-</Warning>
-
-## Hook Events Overview
-
-Claude Code provides several hook events that run at different points in the
-workflow:
-
-* **PreToolUse**: Runs before tool calls (can block them)
-* **PermissionRequest**: Runs when a permission dialog is shown (can allow or deny)
-* **PostToolUse**: Runs after tool calls complete
-* **UserPromptSubmit**: Runs when the user submits a prompt, before Claude processes it
-* **Notification**: Runs when Claude Code sends notifications
-* **Stop**: Runs when Claude Code finishes responding
-* **SubagentStop**: Runs when subagent tasks complete
-* **PreCompact**: Runs before Claude Code is about to run a compact operation
-* **Setup**: Runs when Claude Code is invoked with `--init`, `--init-only`, or `--maintenance` flags
-* **SessionStart**: Runs when Claude Code starts a new session or resumes an existing session
-* **SessionEnd**: Runs when Claude Code session ends
-
-Each event receives different data and can control Claude's behavior in
-different ways.
-
-## Quickstart
-
-In this quickstart, you'll add a hook that logs the shell commands that Claude
-Code runs.
-
-### Prerequisites
-
-Install `jq` for JSON processing in the command line.
-
-### Step 1: Open hooks configuration
-
-Run the `/hooks` command and select
-the `PreToolUse` hook event.
-
-`PreToolUse` hooks run before tool calls and can block them while providing
-Claude feedback on what to do differently.
-
-### Step 2: Add a matcher
-
-Select `+ Add new matcher…` to run your hook only on Bash tool calls.
-
-Type `Bash` for the matcher.
-
-<Note>You can use `*` to match all tools.</Note>
-
-### Step 3: Add the hook
-
-Select `+ Add new hook…` and enter this command:
-
-```bash  theme={null}
-jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt
-```
-
-### Step 4: Save your configuration
-
-For storage location, select `User settings` since you're logging to your home
-directory. This hook will then apply to all projects, not just your current
-project.
-
-Then press `Esc` until you return to the REPL. Your hook is now registered.
-
-### Step 5: Verify your hook
-
-Run `/hooks` again or check `~/.claude/settings.json` to see your configuration:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Step 6: Test your hook
-
-Ask Claude to run a simple command like `ls` and check your log file:
-
-```bash  theme={null}
-cat ~/.claude/bash-command-log.txt
-```
-
-You should see entries like:
-
-```
-ls - Lists files and directories
-```
-
-## More Examples
-
-<Note>
-  For a complete example implementation, see the [bash command validator example](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py) in our public codebase.
-</Note>
-
-### Code Formatting Hook
-
-Automatically format TypeScript files after editing:
+## Set up your first hook
+
+The fastest way to create a hook is through the `/hooks` interactive menu in Claude Code. This walkthrough creates a desktop notification hook, so you get alerted whenever Claude is waiting for your input instead of watching the terminal.
+
+<Steps>
+  <Step title="Open the hooks menu">
+    Type `/hooks` in the Claude Code CLI. You'll see a list of all available hook events, plus an option to disable all hooks. Each event corresponds to a point in Claude's lifecycle where you can run custom code. Select `Notification` to create a hook that fires when Claude needs your attention.
+  </Step>
+
+  <Step title="Configure the matcher">
+    The menu shows a list of matchers, which filter when the hook fires. Set the matcher to `*` to fire on all notification types. You can narrow it later by changing the matcher to a specific value like `permission_prompt` or `idle_prompt`.
+  </Step>
+
+  <Step title="Add your command">
+    Select `+ Add new hook…`. The menu prompts you for a shell command to run when the event fires. Hooks run any shell command you provide, so you can use your platform's built-in notification tool. Copy the command for your OS:
+
+    <Tabs>
+      <Tab title="macOS">
+        Uses [`osascript`](https://ss64.com/mac/osascript.html) to trigger a native macOS notification through AppleScript:
+
+        ```
+        osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'
+        ```
+      </Tab>
+
+      <Tab title="Linux">
+        Uses `notify-send`, which is pre-installed on most Linux desktops with a notification daemon:
+
+        ```
+        notify-send 'Claude Code' 'Claude Code needs your attention'
+        ```
+      </Tab>
+
+      <Tab title="Windows (PowerShell)">
+        Uses PowerShell to show a native message box through .NET's Windows Forms:
+
+        ```
+        powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"
+        ```
+      </Tab>
+    </Tabs>
+  </Step>
+
+  <Step title="Choose a storage location">
+    The menu asks where to save the hook configuration. Select `User settings` to store it in `~/.claude/settings.json`, which applies the hook to all your projects. You could also choose `Project settings` to scope it to the current project. See [Configure hook location](#configure-hook-location) for all available scopes.
+  </Step>
+
+  <Step title="Test the hook">
+    Press `Esc` to return to the CLI. Ask Claude to do something that requires permission, then switch away from the terminal. You should receive a desktop notification.
+  </Step>
+</Steps>
+
+## What you can automate
+
+Hooks let you run code at key points in Claude Code's lifecycle: format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start, and more. For the full list of hook events, see the [Hooks reference](/en/hooks#hook-lifecycle).
+
+Each example includes a ready-to-use configuration block that you add to a [settings file](#configure-hook-location). The most common patterns:
+
+* [Get notified when Claude needs input](#get-notified-when-claude-needs-input)
+* [Auto-format code after edits](#auto-format-code-after-edits)
+* [Block edits to protected files](#block-edits-to-protected-files)
+* [Re-inject context after compaction](#re-inject-context-after-compaction)
+
+### Get notified when Claude needs input
+
+Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.
+
+This hook uses the `Notification` event, which fires when Claude is waiting for input or permission. Each tab below uses the platform's native notification command. Add this to `~/.claude/settings.json`, or use the [interactive walkthrough](#set-up-your-first-hook) above to configure it with `/hooks`:
+
+<Tabs>
+  <Tab title="macOS">
+    ```json  theme={null}
+    {
+      "hooks": {
+        "Notification": [
+          {
+            "matcher": "",
+            "hooks": [
+              {
+                "type": "command",
+                "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
+              }
+            ]
+          }
+        ]
+      }
+    }
+    ```
+  </Tab>
+
+  <Tab title="Linux">
+    ```json  theme={null}
+    {
+      "hooks": {
+        "Notification": [
+          {
+            "matcher": "",
+            "hooks": [
+              {
+                "type": "command",
+                "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
+              }
+            ]
+          }
+        ]
+      }
+    }
+    ```
+  </Tab>
+
+  <Tab title="Windows (PowerShell)">
+    ```json  theme={null}
+    {
+      "hooks": {
+        "Notification": [
+          {
+            "matcher": "",
+            "hooks": [
+              {
+                "type": "command",
+                "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
+              }
+            ]
+          }
+        ]
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### Auto-format code after edits
+
+Automatically run [Prettier](https://prettier.io/) on every file Claude edits, so formatting stays consistent without manual intervention.
+
+This hook uses the `PostToolUse` event with an `Edit|Write` matcher, so it runs only after file-editing tools. The command extracts the edited file path with [`jq`](https://jqlang.github.io/jq/) and passes it to Prettier. Add this to `.claude/settings.json` in your project root:
 
 ```json  theme={null}
 {
@@ -154,7 +162,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
+            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
           }
         ]
       }
@@ -163,9 +171,194 @@
 }
 ```
 
-### Markdown Formatting Hook
-
-Automatically fix missing language tags and formatting issues in markdown files:
+<Note>
+  The Bash examples on this page use `jq` for JSON parsing. Install it with `brew install jq` (macOS), `apt-get install jq` (Debian/Ubuntu), or see [`jq` downloads](https://jqlang.github.io/jq/download/).
+</Note>
+
+### Block edits to protected files
+
+Prevent Claude from modifying sensitive files like `.env`, `package-lock.json`, or anything in `.git/`. Claude receives feedback explaining why the edit was blocked, so it can adjust its approach.
+
+This example uses a separate script file that the hook calls. The script checks the target file path against a list of protected patterns and exits with code 2 to block the edit.
+
+<Steps>
+  <Step title="Create the hook script">
+    Save this to `.claude/hooks/protect-files.sh`:
+
+    ```bash  theme={null}
+    #!/bin/bash
+    # protect-files.sh
+
+    INPUT=$(cat)
+    FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+    PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
+
+    for pattern in "${PROTECTED_PATTERNS[@]}"; do
+      if [[ "$FILE_PATH" == *"$pattern"* ]]; then
+        echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
+        exit 2
+      fi
+    done
+
+    exit 0
+    ```
+  </Step>
+
+  <Step title="Make the script executable (macOS/Linux)">
+    Hook scripts must be executable for Claude Code to run them:
+
+    ```bash  theme={null}
+    chmod +x .claude/hooks/protect-files.sh
+    ```
+  </Step>
+
+  <Step title="Register the hook">
+    Add a `PreToolUse` hook to `.claude/settings.json` that runs the script before any `Edit` or `Write` tool call:
+
+    ```json  theme={null}
+    {
+      "hooks": {
+        "PreToolUse": [
+          {
+            "matcher": "Edit|Write",
+            "hooks": [
+              {
+                "type": "command",
+                "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
+              }
+            ]
+          }
+        ]
+      }
+    }
+    ```
+  </Step>
+</Steps>
+
+### Re-inject context after compaction
+
+When Claude's context window fills up, compaction summarizes the conversation to free space. This can lose important details. Use a `SessionStart` hook with a `compact` matcher to re-inject critical context after every compaction.
+
+Any text your command writes to stdout is added to Claude's context. This example reminds Claude of project conventions and recent work. Add this to `.claude/settings.json` in your project root:
+
+```json  theme={null}
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+You can replace the `echo` with any command that produces dynamic output, like `git log --oneline -5` to show recent commits. For injecting context on every session start, consider using [CLAUDE.md](/en/memory) instead. For environment variables, see [`CLAUDE_ENV_FILE`](/en/hooks#persist-environment-variables) in the reference.
+
+## How hooks work
+
+Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:
+
+| Event                | When it fires                                        |
+| :------------------- | :--------------------------------------------------- |
+| `SessionStart`       | When a session begins or resumes                     |
+| `UserPromptSubmit`   | When you submit a prompt, before Claude processes it |
+| `PreToolUse`         | Before a tool call executes. Can block it            |
+| `PermissionRequest`  | When a permission dialog appears                     |
+| `PostToolUse`        | After a tool call succeeds                           |
+| `PostToolUseFailure` | After a tool call fails                              |
+| `Notification`       | When Claude Code sends a notification                |
+| `SubagentStart`      | When a subagent is spawned                           |
+| `SubagentStop`       | When a subagent finishes                             |
+| `Stop`               | When Claude finishes responding                      |
+| `PreCompact`         | Before context compaction                            |
+| `SessionEnd`         | When a session terminates                            |
+
+Each hook has a `type` that determines how it runs. Most hooks use `"type": "command"`, which runs a shell command. Two other options use a Claude model to make decisions: `"type": "prompt"` for single-turn evaluation and `"type": "agent"` for multi-turn verification with tool access. See [Prompt-based hooks](#prompt-based-hooks) and [Agent-based hooks](#agent-based-hooks) for details.
+
+### Read input and return output
+
+Hooks communicate with Claude Code through stdin, stdout, stderr, and exit codes. When an event fires, Claude Code passes event-specific data as JSON to your script's stdin. Your script reads that data, does its work, and tells Claude Code what to do next via the exit code.
+
+#### Hook input
+
+Every event includes common fields like `session_id` and `cwd`, but each event type adds different data. For example, when Claude runs a Bash command, a `PreToolUse` hook receives something like this on stdin:
+
+```json  theme={null}
+{
+  "session_id": "abc123",          // unique ID for this session
+  "cwd": "/Users/sarah/myproject", // working directory when the event fired
+  "hook_event_name": "PreToolUse", // which event triggered this hook
+  "tool_name": "Bash",             // the tool Claude is about to use
+  "tool_input": {                  // the arguments Claude passed to the tool
+    "command": "npm test"          // for Bash, this is the shell command
+  }
+}
+```
+
+Your script can parse that JSON and act on any of those fields. `UserPromptSubmit` hooks get the `prompt` text instead, `SessionStart` hooks get the `source` (startup, resume, compact), and so on. See [Common input fields](/en/hooks#common-input-fields) in the reference for shared fields, and each event's section for event-specific schemas.
+
+#### Hook output
+
+Your script tells Claude Code what to do next by writing to stdout or stderr and exiting with a specific code. For example, a `PreToolUse` hook that wants to block a command:
+
+```bash  theme={null}
+#!/bin/bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
+
+if echo "$COMMAND" | grep -q "drop table"; then
+  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
+  exit 2                                               # exit 2 = block the action
+fi
+
+exit 0  # exit 0 = let it proceed
+```
+
+The exit code determines what happens next:
+
+* **Exit 0**: the action proceeds. For `UserPromptSubmit` and `SessionStart` hooks, anything you write to stdout is added to Claude's context.
+* **Exit 2**: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust.
+* **Any other exit code**: the action proceeds. Stderr is logged but not shown to Claude. Toggle verbose mode with `Ctrl+O` to see these messages in the transcript.
+
+#### Structured JSON output
+
+Exit codes give you two options: allow or block. For more control, exit 0 and print a JSON object to stdout instead.
+
+<Note>
+  Use exit 2 to block with a stderr message, or exit 0 with JSON for structured control. Don't mix them: Claude Code ignores JSON when you exit 2.
+</Note>
+
+For example, a `PreToolUse` hook can deny a tool call and tell Claude why, or escalate it to the user for approval:
+
+```json  theme={null}
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Use rg instead of grep for better performance"
+  }
+}
+```
+
+Claude Code reads `permissionDecision` and cancels the tool call, then feeds `permissionDecisionReason` back to Claude as feedback. The three options are:
+
+* `"allow"`: proceed without showing a permission prompt
+* `"deny"`: cancel the tool call and send the reason to Claude
+* `"ask"`: show the permission prompt to the user as normal
+
+For `UserPromptSubmit` hooks, use `additionalContext` instead to inject text into Claude's context. See [Control behavior with JSON output](/en/hooks#json-output) in the reference for the full JSON schema. Prompt-based hooks (`type: "prompt"`) handle output differently: see [Prompt-based hooks](#prompt-based-hooks).
+
+### Filter hooks with matchers
+
+Without a matcher, a hook fires on every occurrence of its event. Matchers let you narrow that down. For example, if you want to run a formatter only after file edits (not after every tool call), add a matcher to your `PostToolUse` hook:
 
 ```json  theme={null}
 {
@@ -174,10 +367,7 @@
       {
         "matcher": "Edit|Write",
         "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
-          }
+          { "type": "command", "command": "prettier --write ..." }
         ]
       }
     ]
@@ -185,121 +375,132 @@
 }
 ```
 
-Create `.claude/hooks/markdown_formatter.py` with this content:
-
-````python  theme={null}
-#!/usr/bin/env python3
-"""
-Markdown formatter for Claude Code output.
-Fixes missing language tags and spacing issues while preserving code content.
-"""
-import json
-import sys
-import re
-import os
-
-def detect_language(code):
-    """Best-effort language detection from code content."""
-    s = code.strip()
-    
-    # JSON detection
-    if re.search(r'^\s*[{\[]', s):
-        try:
-            json.loads(s)
-            return 'json'
-        except:
-            pass
-    
-    # Python detection
-    if re.search(r'^\s*def\s+\w+\s*\(', s, re.M) or \
-       re.search(r'^\s*(import|from)\s+\w+', s, re.M):
-        return 'python'
-    
-    # JavaScript detection  
-    if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', s) or \
-       re.search(r'=>|console\.(log|error)', s):
-        return 'javascript'
-    
-    # Bash detection
-    if re.search(r'^#!.*\b(bash|sh)\b', s, re.M) or \
-       re.search(r'\b(if|then|fi|for|in|do|done)\b', s):
-        return 'bash'
-    
-    # SQL detection
-    if re.search(r'\b(SELECT|INSERT|UPDATE|DELETE|CREATE)\s+', s, re.I):
-        return 'sql'
-        
-    return 'text'
-
-def format_markdown(content):
-    """Format markdown content with language detection."""
-    # Fix unlabeled code fences
-    def add_lang_to_fence(match):
-        indent, info, body, closing = match.groups()
-        if not info.strip():
-            lang = detect_language(body)
-            return f"{indent}```{lang}\n{body}{closing}\n"
-        return match.group(0)
-    
-    fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
-    content = re.sub(fence_pattern, add_lang_to_fence, content)
-    
-    # Fix excessive blank lines (only outside code fences)
-    content = re.sub(r'\n{3,}', '\n\n', content)
-    
-    return content.rstrip() + '\n'
-
-# Main execution
-try:
-    input_data = json.load(sys.stdin)
-    file_path = input_data.get('tool_input', {}).get('file_path', '')
-    
-    if not file_path.endswith(('.md', '.mdx')):
-        sys.exit(0)  # Not a markdown file
-    
-    if os.path.exists(file_path):
-        with open(file_path, 'r', encoding='utf-8') as f:
-            content = f.read()
-        
-        formatted = format_markdown(content)
-        
-        if formatted != content:
-            with open(file_path, 'w', encoding='utf-8') as f:
-                f.write(formatted)
-            print(f"✓ Fixed markdown formatting in {file_path}")
-    
-except Exception as e:
-    print(f"Error formatting markdown: {e}", file=sys.stderr)
-    sys.exit(1)
-````
-
-Make the script executable:
-
-```bash  theme={null}
-chmod +x .claude/hooks/markdown_formatter.py
-```
-
-This hook automatically:
-
-* Detects programming languages in unlabeled code blocks
-* Adds appropriate language tags for syntax highlighting
-* Fixes excessive blank lines while preserving code content
-* Only processes markdown files (`.md`, `.mdx`)
-
-### Custom Notification Hook
-
-Get desktop notifications when Claude needs input:
+The `"Edit|Write"` matcher is a regex pattern that matches the tool name. The hook only fires when Claude uses the `Edit` or `Write` tool, not when it uses `Bash`, `Read`, or any other tool.
+
+Each event type matches on a specific field. Matchers support exact strings and regex patterns:
+
+| Event                                                                  | What the matcher filters  | Example matcher values                                                   |
+| :--------------------------------------------------------------------- | :------------------------ | :----------------------------------------------------------------------- |
+| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` | tool name                 | `Bash`, `Edit\|Write`, `mcp__.*`                                         |
+| `SessionStart`                                                         | how the session started   | `startup`, `resume`, `clear`, `compact`                                  |
+| `SessionEnd`                                                           | why the session ended     | `clear`, `logout`, `prompt_input_exit`, `other`                          |
+| `Notification`                                                         | notification type         | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` |
+| `SubagentStart`                                                        | agent type                | `Bash`, `Explore`, `Plan`, or custom agent names                         |
+| `PreCompact`                                                           | what triggered compaction | `manual`, `auto`                                                         |
+| `UserPromptSubmit`, `Stop`                                             | no matcher support        | always fires on every occurrence                                         |
+| `SubagentStop`                                                         | agent type                | same values as `SubagentStart`                                           |
+
+A few more examples showing matchers on different event types:
+
+<Tabs>
+  <Tab title="Log every Bash command">
+    Match only `Bash` tool calls and log each command to a file. The `PostToolUse` event fires after the command completes, so `tool_input.command` contains what ran. The hook receives the event data as JSON on stdin, and `jq -r '.tool_input.command'` extracts just the command string, which `>>` appends to the log file:
+
+    ```json  theme={null}
+    {
+      "hooks": {
+        "PostToolUse": [
+          {
+            "matcher": "Bash",
+            "hooks": [
+              {
+                "type": "command",
+                "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
+              }
+            ]
+          }
+        ]
+      }
+    }
+    ```
+  </Tab>
+
+  <Tab title="Match MCP tools">
+    MCP tools use a different naming convention than built-in tools: `mcp__<server>__<tool>`, where `<server>` is the MCP server name and `<tool>` is the tool it provides. For example, `mcp__github__search_repositories` or `mcp__filesystem__read_file`. Use a regex matcher to target all tools from a specific server, or match across servers with a pattern like `mcp__.*__write.*`. See [Match MCP tools](/en/hooks#match-mcp-tools) in the reference for the full list of examples.
+
+    The command below extracts the tool name from the hook's JSON input with `jq` and writes it to stderr, where it shows up in verbose mode (`Ctrl+O`):
+
+    ```json  theme={null}
+    {
+      "hooks": {
+        "PreToolUse": [
+          {
+            "matcher": "mcp__github__.*",
+            "hooks": [
+              {
+                "type": "command",
+                "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
+              }
+            ]
+          }
+        ]
+      }
+    }
+    ```
+  </Tab>
+
+  <Tab title="Clean up on session end">
+    The `SessionEnd` event supports matchers on the reason the session ended. This hook only fires on `clear` (when you run `/clear`), not on normal exits:
+
+    ```json  theme={null}
+    {
+      "hooks": {
+        "SessionEnd": [
+          {
+            "matcher": "clear",
+            "hooks": [
+              {
+                "type": "command",
+                "command": "rm -f /tmp/claude-scratch-*.txt"
+              }
+            ]
+          }
+        ]
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+For full matcher syntax, see the [Hooks reference](/en/hooks#configuration).
+
+### Configure hook location
+
+Where you add a hook determines its scope:
+
+| Location                                                   | Scope                              | Shareable                          |
+| :--------------------------------------------------------- | :--------------------------------- | :--------------------------------- |
+| `~/.claude/settings.json`                                  | All your projects                  | No, local to your machine          |
+| `.claude/settings.json`                                    | Single project                     | Yes, can be committed to the repo  |
+| `.claude/settings.local.json`                              | Single project                     | No, gitignored                     |
+| Managed policy settings                                    | Organization-wide                  | Yes, admin-controlled              |
+| [Plugin](/en/plugins) `hooks/hooks.json`                   | When plugin is enabled             | Yes, bundled with the plugin       |
+| [Skill](/en/skills) or [agent](/en/sub-agents) frontmatter | While the skill or agent is active | Yes, defined in the component file |
+
+You can also use the [`/hooks` menu](/en/hooks#the-hooks-menu) in Claude Code to add, delete, and view hooks interactively. To disable all hooks at once, use the toggle at the bottom of the `/hooks` menu or set `"disableAllHooks": true` in your settings file.
+
+Hooks added through the `/hooks` menu take effect immediately. If you edit settings files directly while Claude Code is running, the changes won't take effect until you review them in the `/hooks` menu or restart your session.
+
+## Prompt-based hooks
+
+For decisions that require judgment rather than deterministic rules, use `type: "prompt"` hooks. Instead of running a shell command, Claude Code sends your prompt and the hook's input data to a Claude model (Haiku by default) to make the decision. You can specify a different model with the `model` field if you need more capability.
+
+The model's only job is to return a yes/no decision as JSON:
+
+* `"ok": true`: the action proceeds
+* `"ok": false`: the action is blocked. The model's `"reason"` is fed back to Claude so it can adjust.
+
+This example uses a `Stop` hook to ask the model whether all requested tasks are complete. If the model returns `"ok": false`, Claude keeps working and uses the `reason` as its next instruction:
 
 ```json  theme={null}
 {
   "hooks": {
-    "Notification": [
+    "Stop": [
       {
-        "matcher": "",
         "hooks": [
           {
-            "type": "command",
-            "command": "notify-send 'Claude Code' 'Awaiting your input'"
+            "type": "prompt",
+            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
           }
         ]
       }
@@ -308,20 +509,26 @@
 }
 ```
 
-### File Protection Hook
-
-Block edits to sensitive files:
+For full configuration options, see [Prompt-based hooks](/en/hooks#prompt-based-hooks) in the reference.
+
+## Agent-based hooks
+
+When verification requires inspecting files or running commands, use `type: "agent"` hooks. Unlike prompt hooks which make a single LLM call, agent hooks spawn a subagent that can read files, search code, and use other tools to verify conditions before returning a decision.
+
+Agent hooks use the same `"ok"` / `"reason"` response format as prompt hooks, but with a longer default timeout of 60 seconds and up to 50 tool-use turns.
+
+This example verifies that tests pass before allowing Claude to stop:
 
 ```json  theme={null}
 {
   "hooks": {
-    "PreToolUse": [
+    "Stop": [
       {
-        "matcher": "Edit|Write",
         "hooks": [
           {
-            "type": "command",
-            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
+            "type": "agent",
+            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
+            "timeout": 120
           }
         ]
       }
@@ -330,9 +537,93 @@
 }
 ```
 
+Use prompt hooks when the hook input data alone is enough to make a decision. Use agent hooks when you need to verify something against the actual state of the codebase.
+
+For full configuration options, see [Agent-based hooks](/en/hooks#agent-based-hooks) in the reference.
+
+## Limitations and troubleshooting
+
+### Limitations
+
+* Hooks communicate through stdout, stderr, and exit codes only. They cannot trigger slash commands or tool calls directly.
+* Hook timeout is 10 minutes by default, configurable per hook with the `timeout` field (in seconds).
+* `PostToolUse` hooks cannot undo actions since the tool has already executed.
+* `PermissionRequest` hooks do not fire in [non-interactive mode](/en/headless) (`-p`). Use `PreToolUse` hooks for automated permission decisions.
+* `Stop` hooks fire whenever Claude finishes responding, not only at task completion. They do not fire on user interrupts.
+
+### Hook not firing
+
+The hook is configured but never executes.
+
+* Run `/hooks` and confirm the hook appears under the correct event
+* Check that the matcher pattern matches the tool name exactly (matchers are case-sensitive)
+* Verify you're triggering the right event type (e.g., `PreToolUse` fires before tool execution, `PostToolUse` fires after)
+* If using `PermissionRequest` hooks in non-interactive mode (`-p`), switch to `PreToolUse` instead
+
+### Hook error in output
+
+You see a message like "PreToolUse hook error: ..." in the transcript.
+
+* Your script exited with a non-zero code unexpectedly. Test it manually by piping sample JSON:
+  ```bash  theme={null}
+  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
+  echo $?  # Check the exit code
+  ```
+* If you see "command not found", use absolute paths or `$CLAUDE_PROJECT_DIR` to reference scripts
+* If you see "jq: command not found", install `jq` or use Python/Node.js for JSON parsing
+* If the script isn't running at all, make it executable: `chmod +x ./my-hook.sh`
+
+### `/hooks` shows no hooks configured
+
+You edited a settings file but the hooks don't appear in the menu.
+
+* Restart your session or open `/hooks` to reload. Hooks added through the `/hooks` menu take effect immediately, but manual file edits require a reload.
+* Verify your JSON is valid (trailing commas and comments are not allowed)
+* Confirm the settings file is in the correct location: `.claude/settings.json` for project hooks, `~/.claude/settings.json` for global hooks
+
+### Stop hook runs forever
+
+Claude keeps working in an infinite loop instead of stopping.
+
+Your Stop hook script needs to check whether it already triggered a continuation. Parse the `stop_hook_active` field from the JSON input and exit early if it's `true`:
+
+```bash  theme={null}
+#!/bin/bash
+INPUT=$(cat)
+if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
+  exit 0  # Allow Claude to stop
+fi
+# ... rest of your hook logic
+```
+
+### JSON validation failed
+
+Claude Code shows a JSON parsing error even though your hook script outputs valid JSON.
+
+When Claude Code runs a hook, it spawns a shell that sources your profile (`~/.zshrc` or `~/.bashrc`). If your profile contains unconditional `echo` statements, that output gets prepended to your hook's JSON:
+
+```
+Shell ready on arm64
+{"decision": "allow"}
+```
+
+Claude Code tries to parse this as JSON and fails. To fix this, wrap echo statements in your shell profile so they only run in interactive shells:
+
+```bash  theme={null}
+# In ~/.zshrc or ~/.bashrc
+if [[ $- == *i* ]]; then
+  echo "Shell ready"
+fi
+```
+
+The `$-` variable contains shell flags, and `i` means interactive. Hooks run in non-interactive shells, so the echo is skipped.
+
+### Debug techniques
+
+Toggle verbose mode with `Ctrl+O` to see hook output in the transcript, or run `claude --debug` for full execution details including which hooks matched and their exit codes.
+
 ## Learn more
 
-* For reference documentation on hooks, see [Hooks reference](/en/hooks).
-* For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.
-* For troubleshooting steps and debugging techniques, see [Debugging](/en/hooks#debugging) in the hooks reference
-  documentation.
+* [Hooks reference](/en/hooks): full event schemas, JSON output format, async hooks, and MCP tool hooks
+* [Security considerations](/en/hooks#security-considerations): review before deploying hooks in shared or production environments
+* [Bash command validator example](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py): complete reference implementation