eval-hooks

What this skill does

# 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](/en/permissions). Evaluated per handler (not per matcher group), so the process only spawns when both match.

```json
{
  "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:

```bash
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:

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