Create Hook Command

Analyze the project, suggest practical hooks, and create them with proper testing.

Your Task (/create-hook)

1. Analyze environment - Detect tooling and existing hooks
2. Suggest hooks - Based on your project configuration
3. Configure hook - Ask targeted questions and create the script
4. Test & validate - Ensure the hook works correctly

Your Workflow

1. Environment Analysis & Suggestions

Automatically detect the project tooling and suggest relevant hooks:

When TypeScript is detected (

tsconfig.json

• PostToolUse hook: "Type-check files after editing"
• PreToolUse hook: "Block edits with type errors"

When Prettier is detected (

.prettierrc

prettier.config.js

• PostToolUse hook: "Auto-format files after editing"
• PreToolUse hook: "Require formatted code"

When ESLint is detected (

.eslintrc.*

• PostToolUse hook: "Lint and auto-fix after editing"
• PreToolUse hook: "Block commits with linting errors"

When package.json has scripts:

• test

  script → "Run tests before commits"

• build

  script → "Validate build before commits"

When a git repository is detected:

• PreToolUse/Bash hook: "Prevent commits with secrets"
• PostToolUse hook: "Security scan on file changes"

Decision Tree:

Project has TypeScript? → Suggest type checking hooks
Project has formatter? → Suggest formatting hooks
Project has tests? → Suggest test validation hooks
Security sensitive? → Suggest security hooks
+ Scan for additional patterns and suggest custom hooks based on:
  - Custom scripts in package.json
  - Unique file patterns or extensions
  - Development workflow indicators
  - Project-specific tooling configurations

2. Hook Configuration

Start by asking: "What should this hook do?" and offer relevant suggestions from your analysis.

Then understand the context from the user's description and only ask about details you're unsure about:

1. Trigger timing: When should it run?

   • PreToolUse

     : Before file operations (can block)

   • PostToolUse

     : After file operations (feedback/fixes)

   • UserPromptSubmit

     : Before processing requests
   • Other event types as needed

2. Tool matcher: Which tools should trigger it? (

   Write

   ,

   Edit

   ,

   Bash

   ,

   *

   etc)

3. Scope:

   global

   ,

   project

   , or

   project-local

4. Response approach:

   • Exit codes only: Simple (exit 0 = success, exit 2 = block in PreToolUse)
   • JSON response: Advanced control (blocking, context, decisions)
   • Guide based on complexity: simple pass/fail → exit codes, rich feedback → JSON

5. Blocking behavior (if relevant): "Should this stop operations when issues are found?"

   • PreToolUse: Can block operations (security, validation)
   • PostToolUse: Usually provide feedback only

6. Claude integration (CRITICAL): "Should Claude Code automatically see and fix issues this hook detects?"

   • If YES: Use

     additionalContext

     for error communication
   • If NO: Use

     suppressOutput: true

     for silent operation

7. Context pollution: "Should successful operations be silent to avoid noise?"

   • Recommend YES for formatting, routine checks
   • Recommend NO for security alerts, critical errors

8. File filtering: "What file types should this hook process?"

3. Hook Creation

You should:

• Create hooks directory:

  ~/.claude/hooks/

  or

  .claude/hooks/

  based on scope
• Generate script: Create hook script with:
  • Proper shebang and executable permissions
  • Project-specific commands (use detected config paths)
  • Comments explaining the hook's purpose
• Update settings: Add hook configuration to appropriate settings.json
• Use absolute paths: Avoid relative paths to scripts and executables. Use

  $CLAUDE_PROJECT_DIR

  to reference project root
• Offer validation: Ask if the user wants you to test the hook

Key Implementation Standards:

• Read JSON from stdin (never use argv)
• Use top-level

  additionalContext

  /

  systemMessage

  for Claude communication
• Include

  suppressOutput: true

  for successful operations
• Provide specific error counts and actionable feedback
• Focus on changed files rather than entire codebase
• Support common development workflows

⚠️ CRITICAL: Input/Output Format

This is where most hook implementations fail. Pay extra attention to:

• Input: Reading JSON from stdin correctly (not argv)
• Output: Using correct top-level JSON structure for Claude communication
• Documentation: Consulting official docs for exact schemas when in doubt

4. Testing & Validation

CRITICAL: Test both happy and sad paths:

Happy Path Testing:

1. Test expected success scenario - Create conditions where hook should pass
   • Examples: TypeScript (valid code), Linting (formatted code), Security (safe commands)

Sad Path Testing: 2. Test expected failure scenario - Create conditions where hook should fail/warn

• Examples: TypeScript (type errors), Linting (unformatted code), Security (dangerous operations)

Verification Steps: 3. Verify expected behavior: Check if it blocks/warns/provides context as intended

Example Testing Process:

• For a hook preventing file deletion: Create a test file, attempt the protected action, and verify the hook prevents it

If Issues Occur, you should:

• Check hook registration in settings
• Verify script permissions (

  chmod +x

  )
• Test with simplified version first
• Debug with detailed hook execution analysis

Hook Templates

Type Checking (PostToolUse)

#!/usr/bin/env node
// Read stdin JSON, check .ts/.tsx files only
// Run: npx tsc --noEmit --pretty
// Output: JSON with additionalContext for errors

Auto-formatting (PostToolUse)

#!/usr/bin/env node
// Read stdin JSON, check supported file types
// Run: npx prettier --write [file]
// Output: JSON with suppressOutput: true

Security Scanning (PreToolUse)

#!/bin/bash
# Read stdin JSON, check for secrets/keys
# Block if dangerous patterns found
# Exit 2 to block, 0 to continue

Complete templates available at: https://docs.claude.com/en/docs/claude-code/hooks#examples

Quick Reference

📖 Official Docs: https://docs.claude.com/en/docs/claude-code/hooks.md

Common Patterns:

• stdin input:

  JSON.parse(process.stdin.read())

• File filtering: Check extensions before processing
• Success response:

  {continue: true, suppressOutput: true}

• Error response:

  {continue: true, additionalContext: "error details"}

• Block operation:

  exit(2)

  in PreToolUse hooks

Hook Types by Use Case:

• Code Quality: PostToolUse for feedback and fixes
• Security: PreToolUse to block dangerous operations
• CI/CD: PreToolUse to validate before commits
• Development: PostToolUse for automated improvements

Hook Execution Best Practices:

• Hooks run in parallel according to official documentation
• Design for independence since execution order isn't guaranteed
• Plan hook interactions carefully when multiple hooks affect the same files

Success Criteria

✅ Hook created successfully when:

• Script has executable permissions
• Registered in correct settings.json
• Responds correctly to test scenarios
• Integrates properly with Claude for automated fixes
• Follows project conventions and detected tooling

Result: The user gets a working hook that enhances their development workflow with intelligent automation and quality checks.

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

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 or agent-based hooks that use a Claude model to evaluate conditions.

For other ways to extend Claude Code, see skills for giving Claude additional instructions and executable commands, subagents for running tasks in isolated contexts, and plugins for packaging extensions to share across projects.

Set up your first hook

The fastest way to create a hook is through the

/hooks

<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>

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.

Each example includes a ready-to-use configuration block that you add to a settings file. The most common patterns:

• Get notified when Claude needs input
• Auto-format code after edits
• Block edits to protected files
• 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

~/.claude/settings.json

/hooks

Auto-format code after edits

Automatically run Prettier on every file Claude edits, so formatting stays consistent without manual intervention.

This hook uses the

PostToolUse

Edit|Write

jq

.claude/settings.json

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

Block edits to protected files

Prevent Claude from modifying sensitive files like

.env

package-lock.json

.git/

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.

```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
```

```bash  theme={null}
chmod +x .claude/hooks/protect-files.sh
```

```json  theme={null}
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}
```

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

compact

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

{
  "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

git log --oneline -5

CLAUDE_ENV_FILE

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:

SessionStart

UserPromptSubmit

PreToolUse

PermissionRequest

PostToolUse

PostToolUseFailure

Notification

SubagentStart

SubagentStop

Stop

PreCompact

SessionEnd

Each hook has a

type

"type": "command"

"type": "prompt"

"type": "agent"

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

cwd

PreToolUse

{
  "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

prompt

SessionStart

source

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

#!/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.

For example, a

PreToolUse

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

Claude Code reads

permissionDecision

permissionDecisionReason

PreToolUse

• "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

Other events use different decision patterns. For example,

PostToolUse

Stop

decision: "block"

PermissionRequest

hookSpecificOutput.decision.behavior

For

UserPromptSubmit

additionalContext

type: "prompt"

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

The

"Edit|Write"

Edit

Write

Bash

Read

Each event type matches on a specific field. Matchers support exact strings and regex patterns:

PreToolUse

PostToolUse

PostToolUseFailure

PermissionRequest

Bash

Edit|Write

mcp__.*

SessionStart

startup

resume

clear

compact

SessionEnd

clear

logout

prompt_input_exit

other

Notification

permission_prompt

idle_prompt

auth_success

elicitation_dialog

SubagentStart

Bash

Explore

Plan

PreCompact

manual

auto

UserPromptSubmit

Stop

SubagentStop

SubagentStart

A few more examples showing matchers on different event types:

```json  theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}
```

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"
          }
        ]
      }
    ]
  }
}
```

```json  theme={null}
{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}
```

For full matcher syntax, see the Hooks reference.

Configure hook location

Where you add a hook determines its scope:

~/.claude/settings.json

.claude/settings.json

.claude/settings.local.json

hooks/hooks.json

You can also use the

/hooks

/hooks

"disableAllHooks": true

Hooks added through the

/hooks

/hooks

Prompt-based hooks

For decisions that require judgment rather than deterministic rules, use

type: "prompt"

model

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

"ok": false

reason

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

For full configuration options, see Prompt-based hooks in the reference.

Agent-based hooks

When verification requires inspecting files or running commands, use

type: "agent"

Agent hooks use the same

"ok"

"reason"

This example verifies that tests pass before allowing Claude to stop:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

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 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 (

  -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:

  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

true

#!/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

~/.bashrc

echo

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

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:

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

The

$-

i

Debug techniques

Toggle verbose mode with

Ctrl+O

claude --debug

Learn more

• Hooks reference: full event schemas, JSON output format, async hooks, and MCP tool hooks
• Security considerations: review before deploying hooks in shared or production environments
• Bash command validator example: complete reference implementation

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Hooks reference

Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, prompt hooks, and MCP tool hooks.

Hooks are user-defined shell commands or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks and MCP tool hooks. If you're setting up hooks for the first time, start with the guide instead.

Hook lifecycle

Hooks fire at specific points during a Claude Code session. When an event fires and a matcher matches, Claude Code passes JSON context about the event to your hook handler. For command hooks, this arrives on stdin. Your handler can then inspect the input, take action, and optionally return a decision. Some events fire once per session, while others fire repeatedly inside the agentic loop:

The table below summarizes when each event fires. The Hook events section documents the full input schema and decision control options for each one.

SessionStart

UserPromptSubmit

PreToolUse

PermissionRequest

PostToolUse

PostToolUseFailure

Notification

SubagentStart

SubagentStop

Stop

PreCompact

SessionEnd

How a hook resolves

To see how these pieces fit together, consider this

PreToolUse

block-rm.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

The script reads the JSON input from stdin, extracts the command, and returns a

permissionDecision

"deny"

rm -rf

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # allow the command
fi

Now suppose Claude Code decides to run

Bash "rm -rf /tmp/build"

```json  theme={null}
{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }
```

```json  theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}
```

If the command had been safe (like `npm test`), the script would hit `exit 0` instead, which tells Claude Code to allow the tool call with no further action.

The Configuration section below documents the full schema, and each hook event section documents what input your command receives and what output it can return.

Configuration

Hooks are defined in JSON settings files. The configuration has three levels of nesting:

1. Choose a hook event to respond to, like

   PreToolUse

   or

   Stop

2. Add a matcher group to filter when it fires, like "only for the Bash tool"
3. Define one or more hook handlers to run when matched

See How a hook resolves above for a complete walkthrough with an annotated example.

Hook locations

Where you define a hook determines its scope:

~/.claude/settings.json

.claude/settings.json

.claude/settings.local.json

hooks/hooks.json

For details on settings file resolution, see settings. Enterprise administrators can use

allowManagedHooksOnly

Matcher patterns

The

matcher

"*"

""

matcher

PreToolUse

PostToolUse

PostToolUseFailure

PermissionRequest

Bash

Edit|Write

mcp__.*

SessionStart

startup

resume

clear

compact

SessionEnd

clear

logout

prompt_input_exit

bypass_permissions_disabled

other

Notification

permission_prompt

idle_prompt

auth_success

elicitation_dialog

SubagentStart

Bash

Explore

Plan

PreCompact

manual

auto

SubagentStop

SubagentStart

UserPromptSubmit

Stop

The matcher is a regex, so

Edit|Write

Notebook.*

tool_name

This example runs a linting script only when Claude writes or edits a file:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

UserPromptSubmit

Stop

matcher

Match MCP tools

MCP server tools appear as regular tools in tool events (

PreToolUse

PostToolUse

PostToolUseFailure

PermissionRequest

MCP tools follow the naming pattern

mcp__<server>__<tool>

• mcp__memory__create_entities

  : Memory server's create entities tool

• mcp__filesystem__read_file

  : Filesystem server's read file tool

• mcp__github__search_repositories

  : GitHub server's search tool

Use regex patterns to target specific MCP tools or groups of tools:

• mcp__memory__.*

  matches all tools from the

  memory

  server

• mcp__.*__write.*

  matches any tool containing "write" from any server

This example logs all memory server operations and validates write operations from any MCP server:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

Hook handler fields

Each object in the inner

hooks

• Command hooks (

  type: "command"

  ): run a shell command. Your script receives the event's JSON input on stdin and communicates results back through exit codes and stdout.
• Prompt hooks (

  type: "prompt"

  ): send a prompt to a Claude model for single-turn evaluation. The model returns a yes/no decision as JSON. See Prompt-based hooks.
• Agent hooks (

  type: "agent"

  ): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. See Agent-based hooks.

Common fields

These fields apply to all hook types:

type

"command"

"prompt"

"agent"

timeout

statusMessage

once

true

Command hook fields

In addition to the common fields, command hooks accept these fields:

command

async

true

Prompt and agent hook fields

In addition to the common fields, prompt and agent hooks accept these fields:

prompt

$ARGUMENTS

model

All matching hooks run in parallel, and identical handlers are deduplicated automatically. Handlers run in the current directory with Claude Code's environment. The

$CLAUDE_CODE_REMOTE

"true"

Reference scripts by path

Use environment variables to reference hook scripts relative to the project or plugin root, regardless of the working directory when the hook runs:

• $CLAUDE_PROJECT_DIR

  : the project root. Wrap in quotes to handle paths with spaces.

• ${CLAUDE_PLUGIN_ROOT}

  : the plugin's root directory, for scripts bundled with a plugin.

```json  theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}
```

This example runs a formatting script bundled with the plugin:

```json  theme={null}
{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

See the [plugin components reference](/en/plugins-reference#hooks) for details on creating plugin hooks.

Hooks in skills and agents

In addition to settings files and plugins, hooks can be defined directly in skills and subagents using frontmatter. These hooks are scoped to the component's lifecycle and only run when that component is active.

All hook events are supported. For subagents,

Stop

SubagentStop

Hooks use the same configuration format as settings-based hooks but are scoped to the component's lifetime and cleaned up when it finishes.

This skill defines a

PreToolUse

Bash

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Agents use the same format in their YAML frontmatter.

The

/hooks

menu

Type

/hooks

Each hook in the menu is labeled with a bracket prefix indicating its source:

• [User]

  : from

  ~/.claude/settings.json

• [Project]

  : from

  .claude/settings.json

• [Local]

  : from

  .claude/settings.local.json

• [Plugin]

  : from a plugin's

  hooks/hooks.json

  , read-only

Disable or remove hooks

To remove a hook, delete its entry from the settings JSON file, or use the

/hooks

To temporarily disable all hooks without removing them, set

"disableAllHooks": true

/hooks

Direct edits to hooks in settings files don't take effect immediately. Claude Code captures a snapshot of hooks at startup and uses it throughout the session. This prevents malicious or accidental hook modifications from taking effect mid-session without your review. If hooks are modified externally, Claude Code warns you and requires review in the

/hooks

Hook input and output

Hooks receive JSON data via stdin and communicate results through exit codes, stdout, and stderr. This section covers fields and behavior common to all events. Each event's section under Hook events includes its specific input schema and decision control options.

Common input fields

All hook events receive these fields via stdin as JSON, in addition to event-specific fields documented in each hook event section:

session_id

transcript_path

cwd

permission_mode

"default"

"plan"

"acceptEdits"

"dontAsk"

"bypassPermissions"

hook_event_name

For example, a

PreToolUse

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

The

tool_name

tool_input

Exit code output

The exit code from your hook command tells Claude Code whether the action should proceed, be blocked, or be ignored.

Exit 0 means success. Claude Code parses stdout for JSON output fields. JSON output is only processed on exit 0. For most events, stdout is only shown in verbose mode (

Ctrl+O

UserPromptSubmit

SessionStart

Exit 2 means a blocking error. Claude Code ignores stdout and any JSON in it. Instead, stderr text is fed back to Claude as an error message. The effect depends on the event:

PreToolUse

UserPromptSubmit

Any other exit code is a non-blocking error. stderr is shown in verbose mode (

Ctrl+O

For example, a hook command script that blocks dangerous Bash commands:

#!/bin/bash
# Reads JSON input from stdin, checks the command
command=$(jq -r '.tool_input.command' < /dev/stdin)

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # Success: tool call proceeds

Exit code 2 behavior per event

Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.

PreToolUse

PermissionRequest

UserPromptSubmit

Stop

SubagentStop

PostToolUse

PostToolUseFailure

Notification

SubagentStart

SessionStart

SessionEnd

PreCompact

JSON output

Exit codes let you allow or block, but JSON output gives you finer-grained control. Instead of exiting with code 2 to block, exit 0 and print a JSON object to stdout. Claude Code reads specific fields from that JSON to control behavior, including decision control for blocking, allowing, or escalating to the user.

Your hook's stdout must contain only the JSON object. If your shell profile prints text on startup, it can interfere with JSON parsing. See JSON validation failed in the troubleshooting guide.

The JSON object supports three kinds of fields:

• Universal fields like

  continue

  work across all events. These are listed in the table below.
• Top-level

  decision

  and

  reason

  are used by some events to block or provide feedback.

• hookSpecificOutput

  is a nested object for events that need richer control. It requires a

  hookEventName

  field set to the event name.

continue

true

false

stopReason

continue

false

suppressOutput

false

true

systemMessage

To stop Claude entirely regardless of event type:

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

Decision control

Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:

decision

decision: "block"

reason

hookSpecificOutput

permissionDecision

permissionDecisionReason

hookSpecificOutput

decision.behavior

Here are examples of each pattern in action:

```json  theme={null}
{
  "decision": "block",
  "reason": "Test suite must pass before proceeding"
}
```

```json  theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}
```

```json  theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}
```

For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see What you can automate in the guide and the Bash command validator reference implementation.

Hook events

Each event corresponds to a point in Claude Code's lifecycle where hooks can run. The sections below are ordered to match the lifecycle: from session setup through the agentic loop to session end. Each section describes when the event fires, what matchers it supports, the JSON input it receives, and how to control behavior through output.

SessionStart

Runs when Claude Code starts a new session or resumes an existing session. Useful for loading development context like existing issues or recent changes to your codebase, or setting up environment variables. For static context that does not require a script, use CLAUDE.md instead.

SessionStart runs on every session, so keep these hooks fast.

The matcher value corresponds to how the session was initiated:

startup

resume

--resume

--continue

/resume

clear

/clear

compact

SessionStart input

In addition to the common input fields, SessionStart hooks receive

source

model

agent_type

source

"startup"

"resume"

"clear"

/clear

"compact"

model

claude --agent <name>

agent_type

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup",
  "model": "claude-sonnet-4-5-20250929"
}

SessionStart decision control

Any text your hook script prints to stdout is added as context for Claude. In addition to the JSON output fields available to all hooks, you can return these event-specific fields:

additionalContext

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

Persist environment variables

SessionStart hooks have access to the

CLAUDE_ENV_FILE

To set individual environment variables, write

export

CLAUDE_ENV_FILE

>>

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

To capture all environment changes from setup commands, compare the exported variables before and after:

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Run your setup commands that modify the environment
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

Any variables written to this file will be available in all subsequent Bash commands that Claude Code executes during the session.

UserPromptSubmit

Runs when the user submits a prompt, before Claude processes it. This allows you to add additional context based on the prompt/conversation, validate prompts, or block certain types of prompts.

UserPromptSubmit input

In addition to the common input fields, UserPromptSubmit hooks receive the

prompt

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

UserPromptSubmit decision control

UserPromptSubmit

There are two ways to add context to the conversation on exit code 0:

• Plain text stdout: any non-JSON text written to stdout is added as context
• JSON with

  additionalContext

  : use the JSON format below for more control. The

  additionalContext

  field is added as context

Plain stdout is shown as hook output in the transcript. The

additionalContext

To block a prompt, return a JSON object with

decision

"block"

decision

"block"

reason

decision

"block"

additionalContext

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

PreToolUse

Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name:

Bash

Edit

Write

Read

Glob

Grep

Task

WebFetch

WebSearch

Use PreToolUse decision control to allow, deny, or ask for permission to use the tool.

PreToolUse input

In addition to the common input fields, PreToolUse hooks receive

tool_name

tool_input

tool_use_id

tool_input

Bash

Executes shell commands.

command

"npm test"

description

"Run test suite"

timeout

120000

run_in_background

false

Write

Creates or overwrites a file.

file_path

"/path/to/file.txt"

content

"file content"

Edit

Replaces a string in an existing file.

file_path

"/path/to/file.txt"

old_string

"original text"

new_string

"replacement text"

replace_all

false

Read

Reads file contents.

file_path

"/path/to/file.txt"

offset

10

limit

50

Glob

Finds files matching a glob pattern.

pattern

"**/*.ts"

path

"/path/to/dir"

Grep

Searches file contents with regular expressions.

pattern

"TODO.*fix"

path

"/path/to/dir"

glob

"*.ts"

output_mode

"content"

"content"

"files_with_matches"

"count"

"files_with_matches"

-i

true

multiline

false

WebFetch

Fetches and processes web content.

url

"https://example.com/api"

prompt

"Extract the API endpoints"

WebSearch

Searches the web.

query

"react hooks best practices"

allowed_domains

["docs.example.com"]

blocked_domains

["spam.example.com"]

Task

Spawns a subagent.

prompt

"Find all API endpoints"

description

"Find API endpoints"

subagent_type

"Explore"

model

"sonnet"

PreToolUse decision control

PreToolUse

decision

hookSpecificOutput

permissionDecision

"allow"

"deny"

"ask"

permissionDecisionReason

"allow"

"ask"

"deny"

updatedInput

"allow"

"ask"

additionalContext

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

PermissionRequest

Runs when the user is shown a permission dialog. Use PermissionRequest decision control to allow or deny on behalf of the user.

Matches on tool name, same values as PreToolUse.

PermissionRequest input

PermissionRequest hooks receive

tool_name

tool_input

tool_use_id

permission_suggestions

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    { "type": "toolAlwaysAllow", "tool": "Bash" }
  ]
}

PermissionRequest decision control

PermissionRequest

decision

behavior

"allow"

"deny"

updatedInput

"allow"

updatedPermissions

"allow"

message

"deny"

interrupt

"deny"

true

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

PostToolUse

Runs immediately after a tool completes successfully.

Matches on tool name, same values as PreToolUse.

PostToolUse input

PostToolUse

tool_input

tool_response

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  },
  "tool_use_id": "toolu_01ABC123..."
}

PostToolUse decision control

PostToolUse

decision

"block"

reason

reason

decision

"block"

additionalContext

updatedMCPToolOutput

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

PostToolUseFailure

Runs when a tool execution fails. This event fires for tool calls that throw errors or return failure results. Use this to log failures, send alerts, or provide corrective feedback to Claude.

Matches on tool name, same values as PreToolUse.

PostToolUseFailure input

PostToolUseFailure hooks receive the same

tool_name

tool_input

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Command exited with non-zero status code 1",
  "is_interrupt": false
}

error

is_interrupt

PostToolUseFailure decision control

PostToolUseFailure

additionalContext

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

Notification

Runs when Claude Code sends notifications. Matches on notification type:

permission_prompt

idle_prompt

auth_success

elicitation_dialog

Use separate matchers to run different handlers depending on the notification type. This configuration triggers a permission-specific alert script when Claude needs permission approval and a different notification when Claude has been idle:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Notification input

In addition to the common input fields, Notification hooks receive

message

title

notification_type

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission to use Bash",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Notification hooks cannot block or modify notifications. In addition to the JSON output fields available to all hooks, you can return

additionalContext

additionalContext

SubagentStart

Runs when a Claude Code subagent is spawned via the Task tool. Supports matchers to filter by agent type name (built-in agents like

Bash

Explore

Plan

.claude/agents/

SubagentStart input

In addition to the common input fields, SubagentStart hooks receive

agent_id

agent_type

"Bash"

"Explore"

"Plan"

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

SubagentStart hooks cannot block subagent creation, but they can inject context into the subagent. In addition to the JSON output fields available to all hooks, you can return:

additionalContext

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

SubagentStop

Runs when a Claude Code subagent has finished responding. Matches on agent type, same values as SubagentStart.

SubagentStop input

In addition to the common input fields, SubagentStop hooks receive

stop_hook_active

agent_id

agent_type

agent_transcript_path

agent_type

transcript_path

agent_transcript_path

subagents/

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl"
}

SubagentStop hooks use the same decision control format as Stop hooks.

Stop

Runs when the main Claude Code agent has finished responding. Does not run if the stoppage occurred due to a user interrupt.

Stop input

In addition to the common input fields, Stop hooks receive

stop_hook_active

true

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

Stop decision control

Stop

SubagentStop

decision

"block"

reason

decision

"block"

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

PreCompact

Runs before Claude Code is about to run a compact operation.

The matcher value indicates whether compaction was triggered manually or automatically:

manual

/compact

auto

PreCompact input

In addition to the common input fields, PreCompact hooks receive

trigger

custom_instructions

manual

custom_instructions

/compact

auto

custom_instructions

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

SessionEnd

Runs when a Claude Code session ends. Useful for cleanup tasks, logging session statistics, or saving session state. Supports matchers to filter by exit reason.

The

reason

clear

/clear

logout

prompt_input_exit

bypass_permissions_disabled

other

SessionEnd input

In addition to the common input fields, SessionEnd hooks receive a

reason

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

SessionEnd hooks have no decision control. They cannot block session termination but can perform cleanup tasks.

Prompt-based hooks

In addition to Bash command hooks (

type: "command"

type: "prompt"

PreToolUse

PostToolUse

PostToolUseFailure

PermissionRequest

UserPromptSubmit

Stop

SubagentStop

How prompt-based hooks work

Instead of executing a Bash command, prompt-based hooks:

1. Send the hook input and your prompt to a Claude model, Haiku by default
2. The LLM responds with structured JSON containing a decision
3. Claude Code processes the decision automatically

Prompt hook configuration

Set

type

"prompt"

prompt

command

$ARGUMENTS

This

Stop

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

type

"prompt"

prompt

$ARGUMENTS

$ARGUMENTS

model

timeout

Response schema

The LLM must respond with JSON containing:

{
  "ok": true | false,
  "reason": "Explanation for the decision"
}

ok

true

false

reason

ok

false

Example: Multi-criteria Stop hook

This

Stop

"ok"

false

SubagentStop

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Agent-based hooks

Agent-based hooks (

type: "agent"

How agent hooks work

When an agent hook fires:

1. Claude Code spawns a subagent with your prompt and the hook's JSON input
2. The subagent can use tools like Read, Grep, and Glob to investigate
3. After up to 50 turns, the subagent returns a structured

   { "ok": true/false }

   decision
4. Claude Code processes the decision the same way as a prompt hook

Agent hooks are useful when verification requires inspecting actual files or test output, not just evaluating the hook input data alone.

Agent hook configuration

Set

type

"agent"

prompt

type

"agent"

prompt

$ARGUMENTS

model

timeout

The response schema is the same as prompt hooks:

{ "ok": true }

{ "ok": false, "reason": "..." }

This

Stop

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Run hooks in the background

By default, hooks block Claude's execution until they complete. For long-running tasks like deployments, test suites, or external API calls, set

"async": true

decision

permissionDecision

continue

Configure an async hook

Add

"async": true

type: "command"

This hook runs a test script after every

Write

run-tests.sh

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true,
            "timeout": 120
          }
        ]
      }
    ]
  }
}

The

timeout

How async hooks execute

When an async hook fires, Claude Code starts the hook process and immediately continues without waiting for it to finish. The hook receives the same JSON input via stdin as a synchronous hook.

After the background process exits, if the hook produced a JSON response with a

systemMessage

additionalContext

Example: run tests after file changes

This hook starts a test suite in the background whenever Claude writes a file, then reports the results back to Claude when the tests finish. Save this script to

.claude/hooks/run-tests-async.sh

chmod +x

#!/bin/bash
# run-tests-async.sh

# Read hook input from stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Only run tests for source files
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Run tests and report results via systemMessage
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"
else
  echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"
fi

Then add this configuration to

.claude/settings.json

async: true

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

Limitations

Async hooks have several constraints compared to synchronous hooks:

• Only

  type: "command"

  hooks support

  async

  . Prompt-based hooks cannot run asynchronously.
• Async hooks cannot block tool calls or return decisions. By the time the hook completes, the triggering action has already proceeded.
• Hook output is delivered on the next conversation turn. If the session is idle, the response waits until the next user interaction.
• Each execution creates a separate background process. There is no deduplication across multiple firings of the same async hook.

Security considerations

Disclaimer

Hooks run with your system user's full permissions.

Security best practices

Keep these practices in mind when writing hooks:

• Validate and sanitize inputs: never trust input data blindly
• Always quote shell variables: use

  "$VAR"

  not

  $VAR

• Block path traversal: check for

  ..

  in file paths
• Use absolute paths: specify full paths for scripts, using

  "$CLAUDE_PROJECT_DIR"

  for the project root
• Skip sensitive files: avoid

  .env

  ,

  .git/

  , keys, etc.

Debug hooks

Run

claude --debug

Ctrl+O

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 600000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

For troubleshooting common issues like hooks not firing, infinite Stop hook loops, or configuration errors, see Limitations and troubleshooting in the guide.