hooks-mastery

USE THIS SKILL for building Claude Code hooks — all 24 hook events, 4 hook types (command, http, prompt, agent), conditional `if` filtering, decision control patterns, validators, and self-correcting

SKILL.md

GitHub

Hooks Mastery

Build hooks that make Claude self-correcting. This skill teaches the craft of hook development — when to use which event, how to filter efficiently, decision patterns that differ by event, and production-ready recipes.

For full event schemas and JSON formats, grep the CLI docs: grep -A 200 "^PAGE: /hooks.md" cli-full-docs.txt

When to Use This Skill

  • Building any kind of hook (validation, notification, formatting, policy)
  • Setting up self-correcting workflows (PostToolUse → Claude fixes → passes)
  • Adding quality gates (Stop hooks that block until standards met)
  • Preventing dangerous operations (PreToolUse guards)
  • Integrating Claude Code with external services (HTTP hooks, webhooks)
  • Building LLM-based verification (prompt/agent hooks)
  • Reactive environment management (CwdChanged, FileChanged)

Hook System at a Glance

24 events. 4 hook types. Hooks fire at specific lifecycle points — your code runs, returns a decision, and Claude acts on it.

Events by Category

Session lifecycle:

Event Fires when Can block?
SessionStart Session begins/resumes/compacted No
SessionEnd Session terminates No
UserPromptSubmit User submits prompt, before processing Yes
InstructionsLoaded CLAUDE.md or rules file loaded No
ConfigChange Settings/skills file modified Yes

Tool execution (the agentic loop):

Event Fires when Can block?
PreToolUse Before tool executes Yes (allow/deny/ask/defer)
PermissionRequest Permission dialog about to show Yes (allow/deny)
PermissionDenied Auto-mode denied a tool call No (but can signal retry)
PostToolUse After tool succeeds No (tool already ran)
PostToolUseFailure After tool fails No

Completion & tasks:

Event Fires when Can block?
Stop Claude finishes responding Yes
StopFailure Turn ends due to API error No
TaskCreated TaskCreate tool used Yes
TaskCompleted Task marked completed Yes

Agents & teams:

Event Fires when Can block?
SubagentStart Subagent spawned No
SubagentStop Subagent finishes Yes
TeammateIdle Agent team member going idle Yes

Environment & files:

Event Fires when Can block?
CwdChanged Working directory changes No
FileChanged Watched file changes on disk No
Notification Claude sends a notification No

Compaction:

Event Fires when Can block?
PreCompact Before context compaction No
PostCompact After compaction completes No

Worktrees & MCP:

Event Fires when Can block?
WorktreeCreate Worktree being created Yes
WorktreeRemove Worktree being removed No
Elicitation MCP server requests user input Yes
ElicitationResult User responds to MCP elicitation Yes

The Four Hook Types

{"type": "command", "command": "path/to/script.py"}
{"type": "http",    "url": "http://localhost:8080/hook"}
{"type": "prompt",  "prompt": "Check if all tasks are complete..."}
{"type": "agent",   "prompt": "Verify tests pass. Run the suite."}

When to use each:

Type Use when Speed Can use tools?
command Deterministic rules, file validation, formatting Fast No
http External services, team audit logs, CI/CD webhooks Fast No
prompt Judgment calls a script can't make (single LLM call) Medium No
agent Verification that requires reading files, running tests Slow Yes

Default to command. Use prompt when the decision needs judgment. Use agent when verification needs codebase access. Use http for external integration.

Where Hooks Live

Location Scope Shareable
~/.claude/settings.json All projects No
.claude/settings.json This project Yes (commit it)
.claude/settings.local.json This project No (gitignored)
Managed policy settings Organization-wide Admin-controlled
Plugin hooks/hooks.json When plugin enabled Bundled with plugin
Skill/agent frontmatter While component active In the component file

Matchers & Conditional Filtering

Two levels of filtering: matcher (group-level) and if (handler-level).

Matcher — filter which events fire the group

The matcher is a regex against an event-specific field. Different events match on different things:

Events Matcher filters Examples
Tool events (PreToolUse, PostToolUse, etc.) Tool name Bash, Edit|Write, mcp__.*
SessionStart How session started startup, resume, compact
SessionEnd Why session ended clear, resume, logout
Notification Notification type permission_prompt, idle_prompt
SubagentStart/Stop Agent type Explore, Plan, custom names
ConfigChange Config source user_settings, project_settings, skills
FileChanged Filename (basename) .envrc, .env
StopFailure Error type rate_limit, server_error
InstructionsLoaded Load reason session_start, path_glob_match

Some events have no matcher support and always fire: UserPromptSubmit, Stop, TaskCreated, TaskCompleted, TeammateIdle, CwdChanged, WorktreeCreate, WorktreeRemove.

The if Field — filter which handlers spawn (v2.1.85+)

The if field uses permission rule syntax to match tool name AND arguments. This avoids spawning the hook process when it's not needed.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

The hook only spawns when the Bash command starts with git. Other Bash commands skip it entirely.

if only works on tool events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied. Adding if to any other event prevents the hook from running.

Pattern examples:

  • "Bash(git *)" — only git commands
  • "Bash(rm *)" — only rm commands
  • "Edit(*.ts)" — only TypeScript files
  • "Write(*.py)" — only Python files

Why this matters: Without if, a PreToolUse hook on Bash spawns a process for every single shell command. With if: "Bash(git *)", it only spawns for git commands. In a long session with hundreds of Bash calls, this is the difference between 3 hook invocations and 300.

Other Handler Fields

Field Default Purpose
timeout 600s (command), 30s (prompt), 60s (agent) Seconds before canceling
statusMessage none Custom spinner text while hook runs
async false Run in background without blocking (command only)
once false Run only once per session, then removed (skills only)

Decision Control

This is the part most people get wrong. Different events use different output patterns. There is no universal format.

Pattern 1: Top-level decision (PostToolUse, Stop, UserPromptSubmit, SubagentStop, ConfigChange)

{
  "decision": "block",
  "reason": "Test suite must pass before proceeding"
}

Or exit code 2 with reason on stderr. These events also support additionalContext.

Pattern 2: hookSpecificOutput with permissionDecision (PreToolUse)

This is the current format. The old top-level decision: "block" is deprecated for PreToolUse.

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

Four decisions: allow (skip permission prompt), deny (cancel tool call), ask (show prompt to user), defer (pause for later resume in headless mode).

PreToolUse can also rewrite tool input and inject context:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": { "command": "npm run lint -- --fix" },
    "additionalContext": "Running in production environment."
  }
}

When multiple PreToolUse hooks disagree: deny > defer > ask > allow.

Pattern 3: hookSpecificOutput with decision.behavior (PermissionRequest)

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [{ "type": "setMode", "mode": "acceptEdits", "destination": "session" }]
    }
  }
}

Pattern 4: hookSpecificOutput with retry (PermissionDenied)

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

Pattern 5: Exit code only (TaskCreated, TaskCompleted, TeammateIdle)

Exit 2 + stderr message to block. No JSON decision control needed. These events also accept {"continue": false, "stopReason": "..."} to stop the teammate entirely.

Pattern 6: Context injection (SessionStart, UserPromptSubmit)

Plain text on stdout is added to Claude's context. Or use JSON:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current sprint: auth refactor. Use Bun, not npm."
  }
}

Pattern 7: Prompt/agent hooks (any blocking event)

Prompt and agent hooks return {"ok": true} or {"ok": false, "reason": "what's wrong"}. The model decides — you write the evaluation criteria.

The Simple Path: Exit Codes

For most hooks, you don't need JSON at all:

  • Exit 0 — allow (stdout parsed as JSON if present)
  • Exit 2 — block (stderr fed to Claude as error message)
  • Other — non-blocking error (logged, execution continues)

Building Command Hooks

The Validator Pattern

All command-type validators follow this structure (PEP 723 uv script):

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = ["pandas"]  # add what you need
# ///

import json, sys
from pathlib import Path

def main():
    # 1. Read hook input from stdin
    hook_input = json.loads(sys.stdin.read())

    # 2. Extract what you need
    tool_input = hook_input.get("tool_input", {})
    file_path = tool_input.get("file_path")

    # 3. Validate
    errors = your_validation_logic(file_path)

    # 4. Return decision
    if errors:
        # For PostToolUse/Stop: use top-level decision
        print(json.dumps({
            "decision": "block",
            "reason": "Fix these:\n" + "\n".join(errors)
        }))
        # For PreToolUse: use hookSpecificOutput instead
        # print(json.dumps({
        #     "hookSpecificOutput": {
        #         "hookEventName": "PreToolUse",
        #         "permissionDecision": "deny",
        #         "permissionDecisionReason": "Fix these:\n" + "\n".join(errors)
        #     }
        # }))
    else:
        print(json.dumps({}))  # Pass

if __name__ == "__main__":
    main()

Environment Variables

Variable Available in Purpose
$CLAUDE_PROJECT_DIR All hooks Project root — use for script paths
$CLAUDE_ENV_FILE SessionStart, CwdChanged, FileChanged Write export K=V lines to persist env vars
$CLAUDE_PLUGIN_ROOT Plugin hooks Plugin installation directory
$CLAUDE_PLUGIN_DATA Plugin hooks Plugin persistent data directory
$CLAUDE_CODE_REMOTE All hooks "true" in remote web environments

The stop_hook_active Guard

Stop hooks fire when Claude finishes responding. If your Stop hook blocks, Claude works on the issue and finishes again — firing the Stop hook again. Without a guard, this loops forever:

def main():
    hook_input = json.loads(sys.stdin.read())

    # CRITICAL: Check if we're already in a stop-hook correction cycle
    if hook_input.get("stop_hook_active"):
        print(json.dumps({}))  # Allow Claude to stop
        return

    # ... your validation logic ...

Path Resolution Best Practices

The Problem: Fragile Parent Counting

# WRONG — breaks if validator moves to different depth
project_root = Path(__file__).parent.parent.parent

The Solution: Anchor-Based Root Finding

def find_project_root(start_path: Path, anchor_files: list[str]) -> Path:
    """Walk up until finding a directory with an anchor file."""
    current = start_path.resolve()
    for _ in range(10):
        for anchor in anchor_files:
            if (current / anchor).exists():
                return current
        if current.parent == current:
            break
        current = current.parent
    raise FileNotFoundError(
        f"Could not find project root from {start_path}. "
        f"Searched for: {anchor_files}"
    )

project_root = find_project_root(
    Path(__file__).parent,
    anchor_files=[".git", "package.json", "pyproject.toml"]
)

Pre-flight Sanity Checks

After finding project root, verify it has expected structure:

def verify_project_root(project_root: Path, expected_paths: list[str]) -> list[str]:
    """Returns list of missing paths (empty = all verified)."""
    return [p for p in expected_paths if not (project_root / p).exists()]

missing = verify_project_root(project_root, ["src", ".claude"])
if missing:
    # This is a VALIDATOR BUG, not a validation failure
    print(json.dumps({
        "decision": "block",
        "reason": (
            f"Validator configuration error!\n"
            f"Project root: {project_root}\n"
            f"Missing expected paths: {missing}\n"
            f"The validator needs fixing, not the code."
        )
    }))
    return

Why this matters: Distinguishes validator bugs from validation failures. Prevents false positives that waste time in self-correction loops.

Common Anchor Files

Project type Anchor files
Python pyproject.toml, setup.py, .git
JavaScript/TypeScript package.json, tsconfig.json, .git
Rust Cargo.toml, .git
Go go.mod, .git
Any git repo .git

Recipes

Auto-format after edits

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

Block edits to protected files (with if)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(.env*)|Write(.env*)",
            "command": "echo 'Blocked: .env files are protected' >&2 && exit 2"
          }
        ]
      }
    ]
  }
}

Desktop notification when Claude is idle

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

Direnv-style environment reload

{
  "hooks": {
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Re-inject context after compaction

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun not npm. Run bun test before committing.'"
          }
        ]
      }
    ]
  }
}

Auto-approve ExitPlanMode

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PermissionRequest\",\"decision\":{\"behavior\":\"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

Prompt-type quality gate (LLM-based verification)

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

Agent-type test verification

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

HTTP audit logging

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": { "Authorization": "Bearer $MY_TOKEN" },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Audit config changes

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

Working Examples

PostToolUse: CSV Validator

See ${CLAUDE_SKILL_DIR}/examples/posttooluse-csv-validator.py

Validates CSV files are parseable and non-empty after Edit|Write. Claude self-corrects if invalid.

Stop: Linter Validator

See ${CLAUDE_SKILL_DIR}/examples/stop-ruff-validator.py

Runs ruff linter when Claude finishes. Blocks completion until all linting passes. Includes stop_hook_active guard to prevent infinite loops.

PreToolUse: Deletion Guard

See ${CLAUDE_SKILL_DIR}/examples/pretooluse-deletion-guard.py

Prevents deletion of critical files (.git, .claude, package.json, etc.). Uses hookSpecificOutput with permissionDecision: "deny".

PreToolUse: Git Policy (with if filtering)

See ${CLAUDE_SKILL_DIR}/examples/pretooluse-git-policy.py

Blocks force-pushes and main branch pushes. Demonstrates if: "Bash(git *)" to only spawn on git commands. Uses hookSpecificOutput pattern.

PostToolUse: Project Structure Validator

See ${CLAUDE_SKILL_DIR}/examples/posttooluse-project-structure-validator.py

Demonstrates anchor-based root finding and pre-flight sanity checks. Validates JSON manifests and checks referenced files exist.

Templates

Basic Validator Template

See ${CLAUDE_SKILL_DIR}/templates/validator-template.py

Copy and modify. Includes find_project_root(), verify_project_root(), and both decision output patterns (top-level for PostToolUse/Stop, hookSpecificOutput for PreToolUse).

File-Specific Validator Template

See ${CLAUDE_SKILL_DIR}/templates/file-validator-template.py

For validators that check specific file types (JSON, YAML, etc.)

Best Practices

  1. Use if to reduce hook overhead — Don't spawn a process for every Bash command when you only care about git
  2. Keep validators focused — One validator per concern
  3. Clear error messages — Tell Claude exactly what's wrong and how to fix it
  4. Fast execution — Validators run frequently, keep them under 5 seconds
  5. Use logging — Write to a file for debugging, don't spam stderr
  6. Guard Stop hooks — Check stop_hook_active to prevent infinite loops
  7. Use uv for dependencies — PEP 723 inline dependencies for portability
  8. Choose the right decision pattern — PreToolUse uses hookSpecificOutput, most others use top-level decision
  9. Test standalone — Pipe sample JSON to test without Claude
  10. Prefer if over script-level filtering — if: "Bash(git *)" is cheaper than spawning a script that checks tool_name == "Bash" and command.startswith("git")

Debugging

Test a validator standalone:

echo '{"tool_name":"Bash","tool_input":{"command":"git push --force"},"hook_event_name":"PreToolUse"}' | \
    python .claude/hooks/validators/git-policy.py

Browse configured hooks:

/hooks

Toggle verbose mode (Ctrl+O) to see hook output in the transcript.

Run with full debug logging:

claude --debug

Common issues:

  • Hook not firing → check matcher is correct (/hooks to verify)
  • JSON parse error → shell profile echoing text (wrap in if [[ $- == *i* ]])
  • Stop hook looping → missing stop_hook_active guard
  • PreToolUse returning wrong format → use hookSpecificOutput, not top-level decision
  • if field ignored → only works on tool events, requires v2.1.85+
  • Hook spawning too often → add if field to narrow scope