eval-hooks

name	eval-hooks
description	Audit Claude Code hooks defined in settings.json files for validity, performance safety, and correctness. Resolves each command against the filesystem, checks exit-code strategy for blocking hooks, flags missing timeouts, and reviews interactive vs async patterns. Use when setting up hooks for the first time, debugging a hook that never fires or hangs the agent, or doing a periodic hooks hygiene pass.
allowed-tools	Read Glob Bash Edit
effort	medium
argument-hint	[path to settings file or dir, default: all settings files]

Hooks Evaluator

Discover all Claude Code hooks across every settings file in scope, validate each one against the filesystem and hook semantics, then run an interactive session to confirm or improve them.

The goal is not just to score; it is to leave every hook working, correctly scoped, and safe to run.

When to Use

• First time adding hooks (validate before committing)
• A hook never fires, or fires on every tool call
• The agent hangs noticeably before executing a tool
• A PreToolUse hook is supposed to block but doesn't
• After copying hooks from another project or machine
• Periodic hygiene: "are all these hooks still doing something useful?"

Key Concepts

Event types

Event	When it fires	Can block? (exit 2)
PreToolUse	Before any tool call	Yes
PermissionRequest	When a permission dialog appears	Yes
PostToolUse	After tool completes successfully	No (shows stderr to Claude)
PostToolUseFailure	After a tool fails	No
PostToolBatch	After a full batch of parallel tool calls resolves	Yes (stops agentic loop)
UserPromptSubmit	When user submits a prompt	Yes
UserPromptExpansion	When a slash command expands	Yes
Stop	When Claude finishes responding	Yes (continues the turn)
SubagentStop	When a subagent finishes	Yes (continues the subagent)
TeammateIdle	When an agent team teammate goes idle	Yes
TaskCreated	When a task is being created	Yes
TaskCompleted	When a task is being marked as completed	Yes
PreCompact	Before context compaction	Yes
ConfigChange	When a configuration file changes	Yes (except policy_settings)
PermissionDenied	When auto-mode classifier denies a tool call	No
SessionStart	When a session starts or resumes	No
Setup	On --init-only or -p --init/--maintenance	No
StopFailure	When the turn ends due to API error	No
Notification	When Claude sends a notification	No
MessageDisplay	While assistant message streams	No
SubagentStart	When a subagent is spawned	No
InstructionsLoaded	When a CLAUDE.md or rules file is loaded	No
CwdChanged	When working directory changes	No
FileChanged	When a watched file changes on disk	No
WorktreeCreate	When a worktree is created (replaces default git behavior)	Yes (any non-zero fails)
WorktreeRemove	When a worktree is removed	No
PostCompact	After compaction completes	No
SessionEnd	When a session terminates	No
ElicitationResult	After user responds to MCP elicitation	Yes
Elicitation	When MCP server requests user input	Yes

Events that do NOT support matchers: UserPromptSubmit, PostToolBatch, Stop, TeammateIdle, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, CwdChanged, MessageDisplay.

Exit codes (command hooks)

• Exit 0: success. Claude Code parses stdout for JSON output. JSON is only processed on exit 0.
• Exit 2: blocking error. Stderr is fed to Claude as error message. The tool call or action is prevented on events that support blocking.
• Any other non-zero: non-blocking error. Shows a hook error notice in the transcript (first line of stderr). Execution continues.

Warning: only exit code 2 blocks. Exit code 1 is a non-blocking error and proceeds with the action. Use exit 2 for policy enforcement.

Timeout defaults

Hook type	Default timeout
command, http, mcp_tool	600s
UserPromptSubmit (command/http/mcp_tool)	30s
MessageDisplay (command/http/mcp_tool)	10s
prompt	30s
agent	60s
SessionEnd	1.5s (overall budget)

Hook types

• command: shell command, receives JSON on stdin, communicates via exit codes and stdout
• http: POST request to a URL, same JSON, response body as output
• mcp_tool: calls a tool on a connected MCP server
• prompt: sends prompt to a Claude model, returns { "ok": true/false } decision
• agent: spawns a subagent with tool access (experimental)

Matcher patterns

For PreToolUse, PostToolUse, and related tool events, the matcher filters on tool name:

• Letters/digits/underscores/pipe only: exact match or pipe-separated list (Edit|Write)
• Contains any other character: treated as JavaScript regex (mcp__memory__.*)
• "*", "", or absent: matches all tool calls

Other events match different fields (e.g. SessionStart matches on source: startup|resume|clear|compact). For the complete per-event matcher field reference, see guide/core/hooks-events-reference.md.

The if field (v2.1.85+)

The if field narrows a handler further by tool name AND arguments together, using permission rule syntax. Evaluated per handler (not per matcher group), so the process only spawns when both match.

{
  "matcher": "Bash",
  "hooks": [
    { "type": "command", "if": "Bash(git *)", "command": "my-git-policy.sh" }
  ]
}

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

---

Settings Files Scanned

File	Scope	Committed?
~/.claude/settings.json	Global user	No
~/.claude/settings.local.json	Global local	No
.claude/settings.json	Project	Yes
.claude/settings.local.json	Project local	No
Plugin hooks/hooks.json	Per plugin	Yes (in plugin)
Skill/agent frontmatter hooks:	Per component	Yes

If an argument is provided (e.g. /eval-hooks .claude/settings.local.json), audit only that file. Otherwise scan the four standard locations.

---

Scoring Criteria (10 pts per hook)

#	Criterion	Max	What is checked
1	valid event type	1	Type is one of the 30 known event types listed above
2	matcher	2	Absent for events that don't support matchers (1pt); not an overly broad pattern with a heavy command (1pt)
3	command	3	Non-empty (1pt); referenced script or binary resolves on disk (1pt); script is executable (chmod +x) (1pt)
4	timeout	2	Blocking hooks (PreToolUse, UserPromptSubmit) have explicit timeout field (1pt); value is ≤ 30s for interactive hooks (1pt)
5	blocking awareness	2	Blocking hooks: exit 2 used (not exit 1) for policy enforcement (1pt); no interactive commands that would hang (1pt)
Bonus	hygiene	+1	No duplicate (event + matcher + command) combination found across all scanned files

Thresholds:

• ✅ Good: ≥8/10 (≥80%)
• ⚠️ Needs work: 5-7/10 (50-79%)
• ❌ Fix: <5/10 (<50%)

Non-blocking events (PostToolUse, SessionEnd, Notification, etc.): skip criterion 5 (blocking awareness). Score on 8 pts max. Flag with 🔵.

---

Execution Instructions

Step 1: Discovery

Parse each settings file found:

ls ~/.claude/settings.json ~/.claude/settings.local.json \
   .claude/settings.json .claude/settings.local.json 2>/dev/null

For each file that exists, extract the hooks object. Parse every entry across all event types.

Build a flat list of hook records:

• source_file: which settings file it came from
• event_type: e.g. PreToolUse
• matcher: string or absent
• type: command / http / mcp_tool / prompt / agent
• command: shell command string (command hooks only)
• timeout: seconds or absent (note: JSON uses seconds, not ms)
• async: boolean

If no hooks are found in any file, report it and stop.

Step 2: Resolve commands (command hooks only)

For each command hook, resolve the first token to a binary or script:

CMD=$(echo "$command" | awk '{print $1}')
CMD="${CMD/#\~/$HOME}"
which "$CMD" 2>/dev/null || test -f "$CMD" && echo "found" || echo "not found"
test -x "$CMD" && echo "executable" || echo "not executable"

Flag:

• Not found: script or binary does not exist at that path
• Not executable: file exists but chmod +x was never run (most common source of silent failures)
• Tilde path: command starts with ~ (usually safe since hooks run via shell, but absolute paths are preferred)
• Relative path: path does not start with / or ~ (resolves from working directory, which may vary)

Also flag patterns that indicate the hook will hang:

• read, fzf, gum, any interactive TUI command: flag as ❌ (hangs the agent, hooks run without a controlling terminal since v2.1.139)

Step 3: Check blocking hooks for exit code strategy

For PreToolUse, UserPromptSubmit, UserPromptExpansion, Stop, SubagentStop hooks whose command is a local script:

1. Read the script file
2. Check for exit 2 statements vs exit 1 or generic exit $?
3. Classify:
   • Uses exit 2 for blocking: ✅ correct pattern
   • Uses exit 1 for blocking: ⚠️ exit 1 is non-blocking, action will proceed
   • No explicit exit: the last command's exit code propagates, may not block as intended
   • Always exits 0: will never block (may be intentional for context-only hooks)

Flag any PreToolUse script that contains slow operations (curl, sleep, network calls) without a surrounding timeout guard.

Step 4: Check for duplicates

Compare all hook records by (event_type + matcher + command). Report exact duplicates across files: they fire twice and consume double the latency.

Also flag: a matcher field on an event that doesn't support matchers (silently ignored by Claude Code).

Step 5: Interactive review (core of the skill)

Process hooks one by one. Do not batch and skip the interaction.

For each hook:

Show:

Hook: PreToolUse → Bash [~/.claude/settings.json]
type: command
command: /Users/me/.claude/hooks/confirm-git-push.sh
timeout: (none, default 600s)
Script: found (executable ✅)
Exit strategy: uses exit 2 ✅

Ask three questions:

1. "Does this hook fire at the right time and scope? (y = yes / n = adjust matcher or event)"
2. "Is the command still working correctly? (y / broken / unsure)"
3. "Anything to change (matcher, command, timeout, remove it)? (describe or skip)"

For lifecycle hooks (no matcher):

Show:

Hook: SessionEnd [~/.claude/settings.local.json]
type: command
command: ~/.claude/hooks/session-summary.sh
timeout: (none, default 1.5s for SessionEnd, very short!)
Script: found (executable ✅)

Ask:

1. "Does this hook still serve a useful purpose? (y / n)"
2. "Is the command working within the timeout? (y / broken / unsure)"

If the user provides changes during the interaction: apply them using Edit, confirm each change, then move to the next hook.

Step 6: Output report

After all hooks are reviewed:

# Hooks Audit: [project or global]
Date: [today] | Scanned: N hooks across M settings files

## Summary

| Status | Count |
|--------|-------|
| ✅ Good (≥80%) | N |
| ⚠️ Needs work (50-79%) | N |
| ❌ Fix (<50%) | N |
| 🔵 Non-blocking event | N |
| ✅ User confirmed useful | N |
| ⚠️ User flagged for update | N |
| 🗑️ User marked as stale | N |

---

## Per-Hook Results

### PreToolUse → Bash [~/.claude/settings.json] (7/10 ⚠️)

type: command
command: `~/.claude/hooks/confirm-git-push.sh`
timeout: (none)

| Criterion | Score | Notes |
|-----------|-------|-------|
| valid event type | ✅ 1/1 | PreToolUse |
| matcher | ✅ 2/2 | scoped to Bash |
| command | ✅ 3/3 | found, executable, absolute path |
| timeout | ❌ 0/2 | no timeout (UserPromptSubmit default is 30s, others 600s) |
| blocking awareness | ✅ 2/2 | exit 2 used for blocking ✅ |

**Priority fixes:**
1. Add `"timeout": 10` to cap blocking time
2. Verify script doesn't block on network calls without internal timeout

User feedback: ✅ scope correct
Content: timeout added ✅

---

### PostToolUse → Edit|Write [~/.claude/settings.json] (10/10 ✅) 🔵

type: command
command: `~/.claude/hooks/anti-ai-markers.sh`
timeout: 2

Non-blocking event: exit 2 shows stderr to Claude but doesn't prevent the action. All criteria pass. User confirmed still useful.

---

Step 7: Fix Summary

## What Changed This Session

confirm-git-push.sh hook:
  - Added timeout: 10

session-summary.sh hook:
  - User confirmed useful, no changes

rtk-baseline.sh hook:
  - User flagged as stale (awaiting explicit deletion confirmation)

---
N hooks audited · N edits applied · N flagged as stale · N duplicates found

For any hook the user marked as stale: ask for explicit confirmation before removing it from the settings file. Never delete without a clear "yes, remove it".

---

Edge Cases

• Command is a one-liner inline (e.g. rtk hook claude): skip script-level checks, verify the binary rtk exists in PATH
• Command uses bash -c '...' inline: parse the inner script string for interactive commands and exit code logic
• exit 1 in a PreToolUse hook: flag as ⚠️ (exit 1 is a non-blocking error, the tool call will proceed even if the intent was to block)
• Same hook in both global and project settings: not a duplicate (each fires in its own scope), but note both locations in the report
• timeout: 0: flag as likely invalid (may be treated as no timeout)
• Unknown event type (e.g. PreToolCall typo): flag as ❌, report exact string, suggest the correct name
• Script not executable: hook fails silently on most systems, suggest chmod +x immediately
• Matcher on non-matcher event (e.g. UserPromptSubmit with a matcher): flag as silently ignored, suggest removing it
• async: true hook returning decision: "block": flag as ⚠️ (async hooks cannot block, decision fields have no effect)
• asyncRewake: true hook: implies async: true but additionally wakes Claude when the background process exits with code 2. The hook's stderr (or stdout if stderr is empty) is shown to Claude as a system reminder. Flag hooks that need to signal background failures back to Claude but use async instead of asyncRewake
• prompt or agent type hook: these don't have a command to resolve; check that the prompt field is present and non-empty
• SessionEnd hooks: the default timeout budget is 1.5s. Even if a hook declares timeout: 30, it may be cut off. Flag any SessionEnd hook without an explicit timeout, and warn that heavy work here risks being killed
• Hooks not firing as expected: advise using /hooks menu in Claude Code to verify configuration, and checking ~/.claude/logs/ or running with --debug
• PermissionRequest hook in -p mode: these hooks don't fire in non-interactive mode. Flag and suggest migrating to PreToolUse instead
• if field on non-tool event: hook never runs silently. Flag and suggest removing if or changing the event type
• Multiple PreToolUse hooks with updatedInput: when several hooks modify tool input, the last to finish wins (execution is parallel, order is non-deterministic). Flag when more than one PreToolUse hook on the same matcher returns updatedInput
• Stop hook without stop_hook_active check: a Stop hook that always blocks will hit the 8-consecutive-blocks cap and be overridden. Check that the script reads the stop_hook_active field from stdin JSON and exits 0 when it is true, to let Claude stop once it has already continued
• $CLAUDE_PROJECT_DIR in command: preferred over hardcoded absolute paths for project scripts. Flag any command containing an absolute path that looks project-local and suggest replacing with ${CLAUDE_PROJECT_DIR}/...