Hooks

Pre-tool and post-tool hooks for customizing tool execution

Hooks let you run custom logic before or after Claude Code invokes a tool. You can use them to log every tool call, block dangerous operations, auto-approve safe patterns, post results to a webhook, or run an LLM sub-agent to verify intent.

What hooks are

A hook is a shell command, HTTP request, LLM prompt, or agentic verifier attached to a hook event (such as PreToolUse) and optionally filtered by a matcher (such as "Bash"). When the event fires, Claude Code runs all matching hooks in the order they appear in your settings.

Hooks are configured under the hooks key in any settings.json file — user, project, or local. See Settings for file locations.

Hook events

The following hook events are available:

Tool lifecycle

Event	When it fires
PreToolUse	Before a tool call is sent to Claude
PostToolUse	After a tool call completes successfully
PostToolUseFailure	After a tool call fails

Session lifecycle

Event	When it fires
SessionStart	When a new session begins
SessionEnd	When a session ends
Setup	Early in session setup
Stop	When Claude stops generating
StopFailure	When a stop fails
UserPromptSubmit	When the user submits a prompt

Subagents and compaction

Event	When it fires
SubagentStart	When a subagent session starts
SubagentStop	When a subagent session stops
PreCompact	Before context compaction
PostCompact	After context compaction

Permissions and notifications

Event	When it fires
PermissionRequest	When Claude requests permission for a tool
PermissionDenied	When a permission request is denied
Notification	When a notification is emitted

File and workspace changes

Event	When it fires
FileChanged	When a file changes on disk
CwdChanged	When the working directory changes
InstructionsLoaded	When CLAUDE.md instructions are loaded
ConfigChange	When settings change
WorktreeCreate	When a git worktree is created
WorktreeRemove	When a git worktree is removed

Hook types

Each hook entry specifies a type field that determines how it runs.

command

Runs a shell command. The most common hook type.

{
  "type": "command",
  "command": "my-audit-script.sh",
  "shell": "bash",
  "timeout": 10,
  "statusMessage": "Running audit...",
  "async": false
}

Field	Type	Description
command	string	Shell command to execute
shell	"bash" | "powershell"	Shell interpreter (default: bash)
timeout	number	Timeout in seconds for this command
statusMessage	string	Custom spinner message while the hook runs
async	boolean	Run in background without blocking (default: false)
asyncRewake	boolean	Background hook that wakes the model on exit code 2
once	boolean	Run once and remove after execution
if	string	Permission-rule syntax to conditionally run (e.g. "Bash(git *)")

http

Posts the hook input JSON to an HTTP endpoint.

{
  "type": "http",
  "url": "https://hooks.example.com/claude",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"],
  "timeout": 5
}

Field	Type	Description
url	string	URL to POST the hook input JSON to
headers	Record<string, string>	Additional request headers; values may reference env vars via $VAR
allowedEnvVars	string[]	Env var names that may be interpolated in headers
timeout	number	Timeout in seconds
if	string	Conditional filter

HTTP hook URLs are subject to the allowedHttpHookUrls allowlist in managed settings. If the list is set and your URL does not match, the hook is blocked.

prompt

Evaluates an LLM prompt to approve or deny the action.

{
  "type": "prompt",
  "prompt": "Does this bash command look safe? $ARGUMENTS",
  "model": "claude-haiku-4-5",
  "timeout": 30
}

Field	Type	Description
prompt	string	Prompt to evaluate; use $ARGUMENTS for hook input JSON
model	string	Model to use (default: small fast model)
timeout	number	Timeout in seconds
if	string	Conditional filter

agent

Runs a full agentic verifier with tools.

{
  "type": "agent",
  "prompt": "Verify that unit tests ran and passed. $ARGUMENTS",
  "model": "claude-haiku-4-5",
  "timeout": 60
}

Field	Type	Description
prompt	string	Verification prompt; use $ARGUMENTS for hook input JSON
model	string	Model (default: Haiku)
timeout	number	Timeout in seconds (default: 60)
if	string	Conditional filter

Configuration in settings.json

Hooks are nested under the hooks key. Each top-level key is a hook event; its value is an array of matcher objects:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "/usr/local/bin/audit-bash.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "prettier --write $TOOL_OUTPUT_FILE", "async": true }
        ]
      }
    ]
  }
}

Each matcher object has:

Field	Type	Description
matcher	string	Tool name or pattern to match (e.g. "Bash", "Write"). Omit to match all tools
hooks	object[]	One or more hook definitions to run when the matcher matches

Hook execution flow

1. Tool call initiated

   Claude decides to call a tool (e.g. Bash(git status)).

2. PreToolUse hooks run

   All matching PreToolUse hooks execute in order. Hook receives the tool name and input as JSON via environment variables.

3. Tool executes

   If no hook blocked the call, the tool runs.

4. PostToolUse hooks run

   All matching PostToolUse hooks execute. Hook receives the tool output in addition to name and input.

Hook environment

For command hooks, the following environment variables are available:

Variable	Value
CLAUDE_TOOL_NAME	Name of the tool being called (e.g. Bash)
CLAUDE_TOOL_INPUT	Full JSON input to the tool
CLAUDE_HOOK_EVENT	Event name (e.g. PreToolUse)

Blocking a tool call

A PreToolUse hook can block a tool call by exiting with a non-zero exit code. Claude receives an error and does not execute the tool.

#!/usr/bin/env bash
# Block any rm -rf command
if echo "$CLAUDE_TOOL_INPUT" | grep -q "rm -rf"; then
  echo "Blocked: rm -rf is not allowed" >&2
  exit 1
fi

Example hooks

Log all tool calls

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "logger -t claude-code \"[PreToolUse] $CLAUDE_TOOL_NAME: $CLAUDE_TOOL_INPUT\""
          }
        ]
      }
    ]
  }
}

Block dangerous bash patterns

#!/usr/bin/env bash
# ~/.claude/hooks/block-dangerous.sh
DANGEROUS_PATTERNS="rm -rf|sudo rm|chmod -R 777|> /etc|dd if="

if echo "$CLAUDE_TOOL_INPUT" | grep -qE "$DANGEROUS_PATTERNS"; then
  echo "Blocked: dangerous command pattern detected" >&2
  exit 1
fi

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

Post to webhook on session end

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.example.com/claude-session-end",
            "headers": {
              "Authorization": "Bearer $WEBHOOK_TOKEN"
            },
            "allowedEnvVars": ["WEBHOOK_TOKEN"]
          }
        ]
      }
    ]
  }
}

LLM-based safety check

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are a security reviewer. The following is a bash command about to be run by Claude Code. Respond with {\"ok\": true} if it is safe, or {\"ok\": false, \"reason\": \"...\"} if it should be blocked.\n\n$ARGUMENTS",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

Hook sources

Hooks can come from multiple sources, resolved in priority order:

Source	Location
User settings	~/.claude/settings.json
Project settings	.claude/settings.json
Local settings	.claude/settings.local.json
Plugin hooks	~/.claude/plugins/*/hooks/hooks.json
Session hooks	In-memory, temporary
Built-in hooks	Registered internally by Claude Code

When allowManagedHooksOnly: true is set in managed settings, only hooks from the managed policy file run. User, project, and local hooks are ignored.

Disabling hooks

To disable all hooks and status line execution for a session or globally:

{
  "disableAllHooks": true
}

You can also use bare mode (--bare CLI flag or CLAUDE_CODE_SIMPLE=1) to skip hooks entirely along with other non-essential features.