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

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 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

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)

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}/...