Hooks — Enforced Automation

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

timeout defaults to 60 s per command · "once": true runs a hook a single time per session · all matching hooks run in parallel, identical commands deduplicated.

Tool-name patterns

Common PreToolUse matchers: Task, Bash, Glob, Grep, Read, Edit, Write, WebFetch, WebSearch.

Events match other things

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.js",
    "content": "..."
  },
  "tool_use_id": "toolu_01ABC123...",
  "agent_id": "agent-abc123",
  "agent_type": "main",
  "worktree": "/path/to/worktree",
  "effort": { "level": "medium" }
}

Event-specific extras ride along: tool events add tool_name + tool_input, Stop adds last_assistant_message, PostToolUse adds duration_ms.

{
  "continue": true,
  "stopReason": "Optional message if stopping",
  "suppressOutput": false,
  "systemMessage": "Optional warning message",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "File is in allowed directory",
    "updatedInput": {
      "file_path": "/modified/path.js"
    }
  }
}

// prompt-type hook on Stop
{
  "type": "prompt",
  "prompt": "Review if Claude completed all
    requested tasks. Check: 1) Were all files
    created/modified? 2) Were there unresolved
    errors? If incomplete, explain what's missing.",
  "timeout": 30
}

// the LLM answers with a structured decision
{
  "decision": "approve",
  "reason": "All tasks completed successfully",
  "continue": false,
  "stopReason": "Task complete"
}

• Both events receive last_assistant_message in their input — the final message before stopping, exactly what a completion check needs
• A blocking decision sends Claude back to work with the reason as feedback
• SubagentStop does the same for subagents — matcher is the agent type name
• prompt hooks are single-turn judgment; agent hooks can gather evidence with tools first

SessionStart — setup with side effects

#!/bin/bash
# persist env vars into the session
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=development' \
    >> "$CLAUDE_ENV_FILE"
fi
exit 0

Matchers: startup / resume / clear / compact. Since v2.1.152, returned JSON can set reloadSkills: true (re-scan skills — same as /reload-skills, so just-installed skills work immediately) and hookSpecificOutput.sessionTitle (names the session on startup/resume).

SessionEnd — the exit interview

• Fires once when the session terminates — cleanup and final logging
• Cannot block termination — the session is ending either way
• Input includes a reason: clear, logout, prompt_input_exit, or other
• Timeout configurable via CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS

# in SKILL.md / agent.md / command.md
---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/check.sh"
          once: true  # only once per session
---

Supported events in component frontmatter: PreToolUse, PostToolUse, Stop. The hook lives for the component's lifetime — related code stays together.

• Subagent auto-conversion: a Stop hook in a subagent's frontmatter becomes a SubagentStop hook scoped to that agent — it fires when that subagent completes, not when the main session stops
• Plugins ship hooks in hooks/hooks.json, same structure as settings
• ${CLAUDE_PLUGIN_ROOT} resolves to the plugin's install directory — portable paths like ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh
• ${CLAUDE_PLUGIN_DATA} points at the plugin's data directory

#!/usr/bin/env python3
# .claude/hooks/validate-bash.py
import json, sys, re

BLOCKED = [
  (r"\brm\s+-rf\s+/", "Blocking dangerous rm -rf /"),
  (r"\bsudo\s+rm",    "Blocking sudo rm command"),
]

data = json.load(sys.stdin)
if data.get("tool_name") != "Bash":
    sys.exit(0)
cmd = data.get("tool_input", {}).get("command", "")
for pattern, message in BLOCKED:
    if re.search(pattern, cmd):
        print(message, file=sys.stderr)
        sys.exit(2)  # exit 2 = block
sys.exit(0)

The bundled big sibling: three tiers

• pre-tool-check.sh grades each Bash command BLOCK / WARN / ALLOW — fork bombs and mkfs exit 2; git push --force and DROP TABLE warn and proceed
• stderr discipline: on exit 2, the block reason must go to stderr (>&2) — stdout shows "No stderr output" instead of your explanation
• On exit 0, stderr is silently dropped — so the WARN tier writes an audit log (.claude/hooks/audit.log) as the only reliable record
• Anchor patterns carefully: rm -rf /([[:space:]]|$), or /tmp/foo gets falsely flagged

No official offline tokenizer exists — both are approximations. The transcript covers prompts, responses, and tool outputs, but not system prompts or internal context.

• Sessions isolated via session_id in the temp filename — parallel sessions don't collide
• Report goes to stderr so it never interferes with hook JSON on stdout
• Ships in two variants: zero-dependency estimation and a tiktoken upgrade

session-end.sh — the learning diary

A companion browser tracker stores progress in localStorage, with export/import as JSON.

And the rest of the shelf

• format-code.sh — PostToolUse on Write/Edit; runs prettier/black/gofmt by extension
• security-scan.sh — warns on hardcoded secrets via additionalContext, non-blocking
• log-bash.sh — appends every Bash command to an audit log
• validate-prompt.sh — UserPromptSubmit gate: blocks production deploys unless .deployment-approved exists; nudges "add tests" on refactor prompts via additionalContext
• dependency-check.sh — npm/pip/go/cargo vulnerability scan on manifest writes; advisory, always exits 0
• notify-team.sh — Slack/Discord/email webhooks; note: no native PostPush event exists — filter PostToolUse:Bash for "git push"
• A one-time permissions seeder (~67 safe allow rules) — a setup script, not a hook

# watch hook execution live
claude --debug
# or press Ctrl+O in-session for verbose mode

# test a hook outside Claude entirely
echo '{"tool_name": "Bash",
  "tool_input": {"command": "ls -la"}}' \
  | python3 .claude/hooks/validate-bash.py
echo $?   # 0 = allow, 2 = block