Discover - Find hook files (.md, .sh, .json)
Classify - Identify hook type and event
Parse - Extract frontmatter and script content
Check - Run all pattern checks against knowledge below
Filter - Apply certainty filtering
Report - Generate markdown output
Fix - Apply auto-fixes if --fix flag present

Hook Knowledge Reference

What Are Hooks

Hooks are automated actions triggered at specific points in a Claude Code session. They enable validation, monitoring, and control of Claude's actions through bash commands or LLM-based evaluation.

Hook Lifecycle (Complete Reference)

Hooks fire in this sequence:

Order	Event	Description	Matcher Required
1	`SessionStart`	Session begins or resumes	No
2	`UserPromptSubmit`	User submits a prompt	No
3	`PreToolUse`	Before tool execution (can modify/block)	Yes
4	`PermissionRequest`	When permission dialog appears	Yes
5	`PostToolUse`	After tool succeeds	Yes
6	`SubagentStart`	When spawning a subagent	No
7	`SubagentStop`	When subagent finishes	No
8	`Stop`	Claude finishes responding	No
9	`PreCompact`	Before context compaction	No
10	`SessionEnd`	Session terminates	No
11	`Notification`	Claude Code sends notifications	No

Hook Types

Command Hooks (type: "command"):

Execute bash commands with full stdin/stdout control
Available for all events

Prompt Hooks (type: "prompt"):

Use LLM evaluation for intelligent, context-aware decisions
Only supported for Stop and SubagentStop events

Configuration Locations

File	Location	Scope	Committed
User settings	`~/.claude/settings.json`	All projects	No
Project settings	`.claude/settings.json`	Current project	Yes
Local settings	`.claude/settings.local.json`	Current project	No

Configuration Structure

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all requested tasks are complete.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Matcher Syntax

Pattern	Description
`Write`	Match exact tool name
`Edit\|Write`	Match multiple tools (regex OR)
`Notebook.*`	Regex pattern matching
`*` or `""`	Match all tools
(omitted)	Required for Stop, SubagentStop, UserPromptSubmit

Input Schema (JSON via stdin)

All hooks receive this JSON structure:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript",
  "cwd": "/project/root",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  }
}

Exit Codes

Exit Code	Behavior
0	Success - stdout shown to user or added as context
2	Blocking error - stderr shown, action blocked
Other	Non-blocking error - stderr shown in verbose mode

Output Schemas

PreToolUse Decision Control:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "Reason for decision",
    "updatedInput": {
      "command": "modified command"
    },
    "additionalContext": "Context for Claude"
  }
}

Stop/SubagentStop Control:

{
  "decision": "block",
  "reason": "Tasks incomplete: missing test coverage"
}

Environment Variables

Variable	Description	Available In
`CLAUDE_PROJECT_DIR`	Absolute path to project root	All hooks
`CLAUDE_CODE_REMOTE`	"true" if remote session	All hooks
`CLAUDE_ENV_FILE`	Path to persist env vars	SessionStart only
`CLAUDE_FILE_PATHS`	Space-separated file paths	PostToolUse (Write/Edit)

Practical Hook Examples

Security Firewall (PreToolUse):

#!/usr/bin/env bash
set -euo pipefail

cmd=$(jq -r '.tool_input.command // ""')

# Block dangerous patterns
if echo "$cmd" | grep -qE 'rm -rf|git reset --hard|curl.*\|.*sh'; then
  echo '{"decision": "block", "reason": "Dangerous command blocked"}' >&2
  exit 2
fi

exit 0

Auto-Formatter (PostToolUse):

#!/usr/bin/env bash
set -euo pipefail

files=$(jq -r '.tool_input.file_path // ""')

for file in $files; do
  case "$file" in
    *.py) black "$file" 2>/dev/null || true ;;
    *.js|*.ts) prettier --write "$file" 2>/dev/null || true ;;
  esac
done

exit 0

Command Logger (PreToolUse):

#!/usr/bin/env bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command // ""')
printf '%s %s\n' "$(date -Is)" "$cmd" >> .claude/bash-commands.log
exit 0

Workflow Orchestration (SubagentStop - prompt type):

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review the subagent's work. Did it complete all tasks?"
          }
        ]
      }
    ]
  }
}

Detection Patterns

1. Frontmatter Validation (HIGH Certainty)

Required:

YAML frontmatter with --- delimiters
name field in frontmatter
description field in frontmatter

Recommended:

timeout for command hooks (default: 30s)
Hook type specification

Flag:

Missing frontmatter delimiters
Missing name or description

2. Script Safety (HIGH Certainty)

Required Safety Patterns:

set -euo pipefail at script start
Error handling for jq/JSON parsing
Proper quoting of variables

Dangerous Patterns to Flag:

Pattern	Risk	Certainty
`rm -rf`	Destructive without confirmation	HIGH
`git reset --hard`	Data loss risk	HIGH
`curl \| sh`	Remote code execution	HIGH
`eval "$input"`	Arbitrary code execution	HIGH
`rm -r`	Recursive delete (may be intentional)	MEDIUM
`git push --force`	Force push (may be intentional)	MEDIUM

3. Exit Code Handling (HIGH Certainty)

Check: Scripts use correct exit codes

Flag:

Missing exit 0 for success path
Using exit code 1 for blocking (should be 2)
No exit code at end of script

4. Hook Type Appropriateness (HIGH Certainty)

Check: Hook type matches event

Flag:

Prompt hooks used for events other than Stop/SubagentStop
Missing type specification

5. Lifecycle Event Appropriateness (MEDIUM Certainty)

Event	Appropriate Use Cases
`PreToolUse`	Security validation, command blocking, input modification
`PostToolUse`	Formatting, logging, notifications
`Stop`	Completion checks, cleanup, summary
`SubagentStop`	Workflow orchestration, result validation
`SessionStart`	Environment setup, initialization

Flag:

PostToolUse hooks trying to block actions (too late)
PreToolUse hooks doing heavy processing (should be fast)
Prompt hooks on unsupported events

6. Timeout Configuration (MEDIUM Certainty)

Guidelines:

Default: 30 seconds for command hooks
Network operations: Always set explicit timeout
External service calls: Set timeout based on expected latency

Flag:

No timeout for network operations
Timeout missing for external service calls
Unreasonably long timeouts (>60s without justification)

7. Output Format (MEDIUM Certainty)

PreToolUse Output Fields:

permissionDecision: allow, deny, or ask
permissionDecisionReason: Explanation for decision
updatedInput: Modified tool input (optional)
additionalContext: Context for Claude (optional)

Flag:

Invalid permissionDecision values
Missing reason for deny decisions
Malformed JSON output

8. Matcher Patterns (MEDIUM Certainty)

Check: Matcher syntax is valid

Flag:

Invalid regex patterns
Too broad matchers (* without justification)
Matcher on events that don't support it (Stop, SubagentStop)

9. Anti-Patterns (LOW Certainty)

Complex logic in hooks (should be simple and fast)
Missing documentation/comments
Hardcoded paths (should use $CLAUDE_PROJECT_DIR)
Network calls without error handling
Secrets/credentials in hook scripts

Auto-Fix Implementations

1. Missing safety header

#!/usr/bin/env bash
set -euo pipefail

2. Missing exit code

Add exit 0 at end of script

3. Missing frontmatter fields

---
name: hook-name
description: Hook description
timeout: 30
---

4. Wrong blocking exit code

Replace exit 1 with exit 2 for blocking errors

Output Format

## Hook Analysis: {hook-name}

**File**: {path}
**Type**: {command|prompt|config}
**Event**: {PreToolUse|PostToolUse|Stop|...}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Frontmatter Issues ({n})
| Issue | Fix | Certainty |

### Safety Issues ({n})
| Issue | Fix | Certainty |

### Exit Code Issues ({n})
| Issue | Fix | Certainty |

### Lifecycle Issues ({n})
| Issue | Fix | Certainty |

### Output Format Issues ({n})
| Issue | Fix | Certainty |

Pattern Statistics

Category	Patterns	Auto-Fixable
Frontmatter	3	2
Safety	6	2
Exit Code	3	2
Hook Type	2	0
Lifecycle	5	0
Timeout	3	0
Output	3	0
Matcher	3	0
Anti-Pattern	5	0
Total	33	6

<bad_example>

#!/usr/bin/env bash
cmd=$(jq -r '.tool_input.command // ""')

Why it's bad: Missing set -euo pipefail means errors may silently pass. </bad_example>

<good_example>

#!/usr/bin/env bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command // ""')

Why it's good: Fails fast on errors, unset variables, and pipe failures. </good_example>

Example: Wrong Exit Code for Blocking

<bad_example>

if [[ "$cmd" == *"rm -rf"* ]]; then
  echo "Blocked dangerous command" >&2
  exit 1  # Wrong!
fi

Why it's bad: Exit code 1 is non-blocking. Action will still proceed. </bad_example>

<good_example>

if [[ "$cmd" == *"rm -rf"* ]]; then
  echo '{"decision": "block", "reason": "Dangerous command"}' >&2
  exit 2  # Correct blocking exit code
fi

Why it's good: Exit code 2 blocks the action. JSON output provides context. </good_example>

Example: Prompt Hook on Wrong Event

<bad_example>

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [{ "type": "prompt", "prompt": "Is this safe?" }]
      }
    ]
  }
}

Why it's bad: Prompt hooks only work for Stop and SubagentStop events. </bad_example>

<good_example>

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [{ "type": "command", "command": "./validate.sh" }]
      }
    ]
  }
}

Why it's good: Command hooks work for all events. </good_example>

Example: Dangerous Command Pattern

<bad_example>

if echo "$cmd" | grep -q 'rm'; then
  exit 2
fi

Why it's bad: Too broad - blocks legitimate rm file.tmp. </bad_example>

<good_example>

if echo "$cmd" | grep -qE 'rm\s+(-rf|-fr)\s+/'; then
  exit 2
fi

Why it's good: Specific pattern targets actual dangerous commands. </good_example>

Example: Hardcoded Path

<bad_example>

log_file="/home/user/project/.claude/commands.log"

Why it's bad: Hardcoded path breaks on other machines. </bad_example>

<good_example>

log_file="$CLAUDE_PROJECT_DIR/.claude/commands.log"

Why it's good: Uses environment variable for portability. </good_example>

Constraints

Only apply auto-fixes for HIGH certainty issues
Be cautious about security patterns - false negatives worse than false positives
Never remove content, only suggest improvements
Validate against embedded knowledge reference above

enhance-hooks

enhance-hooks

Parse Arguments

Workflow