Hook Authoring — Official Best Practices

What Hooks Do

Hooks are deterministic shell commands (or LLM prompts) that execute at specific lifecycle points. They provide guaranteed behavior — not relying on the LLM to choose to run them.

Configuration Locations

Location	Scope	Shareable
~/.claude/settings.json	All projects	No
.claude/settings.json	Single project	Yes (commit)
.claude/settings.local.json	Single project	No (gitignored)
Agent/skill frontmatter	While component active	Yes
Plugin hooks/hooks.json	When plugin enabled	Yes

Hook Types

Type	How it works	Use when
command	Runs shell command, reads stdin JSON, uses exit codes	Deterministic validation, formatting, logging
prompt	Single-turn LLM call, returns {ok, reason}	Judgment-based decisions without tool access
agent	Multi-turn subagent with tool access	Verification requiring file reads or commands
http	POSTs event data to URL endpoint	External service integration, audit logging

Hook Events

See quick-ref/events-reference.md for full input/output schemas.

Event	Matcher input	Can block?	Common use
SessionStart	startup/resume/clear/compact	No	Re-inject context after compaction
UserPromptSubmit	(none)	Yes	Validate/transform user input
PreToolUse	Tool name	Yes	Block commands, validate operations
PermissionRequest	Tool name	Yes	Auto-allow/deny permissions
PostToolUse	Tool name	No*	Auto-format files, logging
PostToolUseFailure	Tool name	No	Error handling
Notification	Notification type	No	Desktop alerts
SubagentStart	Agent type	No	Setup before agent runs
SubagentStop	Agent type	No	Cleanup after agent
Stop	(none)	Yes	Verify completeness
ConfigChange	Config source	Yes	Audit, block unauthorized changes
PreCompact	manual/auto	No	Save context before compaction
SessionEnd	Exit reason	No	Cleanup

*PostToolUse Stop hooks can return {"decision": "block"} to keep Claude working.

Configuration Format

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

Input/Output Protocol

Input (stdin JSON)

Every hook receives JSON on stdin with common fields + event-specific data:

{
  "session_id": "abc123",
  "cwd": "/path/to/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

Output (exit codes)

Exit code	Effect
0	Allow — action proceeds. Stdout added to context (SessionStart, UserPromptSubmit)
2	Block — action cancelled. Stderr sent to Claude as feedback
Other	Allow — stderr logged (visible in verbose mode Ctrl+O)

Structured JSON output (exit 0 + JSON on stdout)

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

PreToolUse decisions: "allow", "deny", "ask".

Common Patterns

Auto-format after edits

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

Block protected files

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE" == *"$pattern"* ]]; then
    echo "Blocked: matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

Re-inject context after compaction

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

Notification on idle

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

Stop Hook Infinite Loop Prevention

Always check stop_hook_active to avoid loops:

INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Let Claude stop
fi
# ... your logic

Anti-Patterns

Anti-Pattern	Fix
Shell profile echo breaks JSON	Wrap in if [[ $- == *i* ]]
Stop hook without loop guard	Check stop_hook_active field
Using PostToolUse to undo actions	Too late — use PreToolUse to block instead
Relying on PermissionRequest in headless mode	Doesn't fire in -p mode. Use PreToolUse

Checklist

• Correct event chosen for the use case
• Matcher pattern tested (case-sensitive, regex)
• Script is executable (chmod +x)
• Uses jq for JSON parsing (or Python/Node)
• Exit code 2 for blocking, 0 for allowing
• Stop hooks check stop_hook_active
• Tested with sample JSON piped to stdin
• Hook script uses absolute paths or $CLAUDE_PROJECT_DIR

Reference

• All events with input/output schemas
• Hook types comparison