Hooks Event Reference — Claude Cert Academy

Hooks Event Reference

Hooks are shell scripts (or any executable) that Claude Code invokes at specific points in its tool loop. They allow you to intercept, block, log, or transform tool calls without modifying Claude's prompt.

Event Types

• PreToolUse — fires before Claude executes a tool call. Can block execution (exit 2) or transform the tool input (stdout JSON). Payload includes the tool name and full input.
• PostToolUse — fires after a tool call completes. Cannot block (tool already ran). Use for logging, auditing, or side effects. Payload includes tool name, input, and output.
• Notification — fires when Claude Code emits a user-facing notification (e.g. permission request, error). Use to route alerts to Slack, PagerDuty, etc.
• Stop — fires when Claude Code is about to exit a session. Use for cleanup, summaries, or final audit writes.

Event Summary Table

# Event         | When it fires              | Can block? | Payload fields
# --------------|----------------------------|------------|----------------
# PreToolUse    | Before tool execution      | YES (exit 2)| tool_name, tool_input, session_id
# PostToolUse   | After tool execution       | No         | tool_name, tool_input, tool_output, session_id
# Notification  | On user-visible alert      | No         | message, level, session_id
# Stop          | On session exit            | No         | exit_reason, session_id

Exit Code Semantics

• 0 — allow (for PreToolUse: proceed with the tool call as-is or use transformed input from stdout).
• 2 — block (PreToolUse only): Claude Code cancels the tool call and reports the block to the model. The hook's stderr is shown as the block reason.
• Any other non-zero — hook error. Claude Code logs the error and continues (does not block). Use for unexpected failures.

Exit code 2 only blocks on PreToolUse. On PostToolUse, Stop, and Notification, exit code 2 is treated as a generic error — it does NOT undo the tool call or halt the session.

Payload Schema (stdin JSON)

PreToolUse

{
  "event": "PreToolUse",
  "session_id": "sess_abc123",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/src/auth.ts",
    "content": "..."
  }
}

PostToolUse

{
  "event": "PostToolUse",
  "session_id": "sess_abc123",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" },
  "tool_output": { "stdout": "...", "stderr": "", "exit_code": 0 }
}

Notification

{
  "event": "Notification",
  "session_id": "sess_abc123",
  "message": "Claude Code wants to run: rm -rf dist/",
  "level": "warn"
}

Stop

{
  "event": "Stop",
  "session_id": "sess_abc123",
  "exit_reason": "end_turn"
}

Matcher Fields

In settings.json, hooks are registered with matcher conditions that limit which events trigger them.

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": {
        "tool_name": "Bash"
      },
      "command": "/usr/local/bin/bash-hook.sh"
    },
    {
      "event": "PreToolUse",
      "matcher": {
        "tool_name": "Write",
        "tool_input.file_path": "migrations/**"
      },
      "command": "/usr/local/bin/migration-guard.sh"
    }
  ]
}

• tool_name — exact match on the tool being called (Read, Write, Bash, etc.).
• tool_input.file_path — glob match on the file_path field of the tool input. Supports ** wildcards.
• If multiple matchers are specified, all must match (AND logic).
• Omit matcher to match all events of that type.

Transform Pattern (PreToolUse)

A PreToolUse hook can modify the tool input by printing a replacement JSON object to stdout before exiting 0.

#!/usr/bin/env bash
# rewrite-paths.sh — redirect all writes to /tmp/sandbox
set -euo pipefail

input=$(cat)  # read full JSON payload from stdin
tool=$(echo "$input" | jq -r '.tool_name')

if [ "$tool" = "Write" ]; then
  # Rewrite file_path to /tmp/sandbox prefix
  echo "$input" | jq '.tool_input.file_path |= "/tmp/sandbox" + .'
  exit 0
fi

# No transform for other tools — output nothing, exit 0
exit 0

Security Notes

• Always use jq (or a proper JSON parser) to read payload fields. Never interpolate raw stdin into shell variables — attackers can craft tool inputs that break out of your quoting.
• Validate that tool_name is what you expect before acting on tool_input fields.
• Hook scripts run with the same permissions as the Claude Code process. Keep them minimal and audited.
• Log hook decisions (allow/block) to an append-only file for audit trails.
• Test hooks in --plan mode first to verify they match the events you expect without executing real tools.

Use `jq -r '.tool_name'` (not echo + grep) to extract fields from the payload. This handles special characters in file paths and command strings correctly.

Continue to Claude Cert Academy