writing-hooks

What this skill does

# Writing Hooks

## Overview

**Writing hooks IS creating automated quality gates.**

Hooks run on Claude Code events (PreToolUse, PostToolUse, etc.) and can block actions with exit code 2.

**Core principle:** Hooks enforce what humans forget. Fast checks only—slow hooks kill productivity.

**Violating the letter of the rules is violating the spirit of the rules.**

## Routing

**Pattern:** Skill Steps
**Handoff:** none
**Next:** none

## Task Initialization (MANDATORY)

Before ANY action, create task list using TaskCreate:

```
TaskCreate for EACH task below:
- Subject: "[writing-hooks] Task N: <action>"
- ActiveForm: "<doing action>"
```

**Tasks:**
0. Fetch latest official hook spec
1. Analyze requirements
2. RED - Test without hook
3. GREEN - Write hook script
4. Configure settings.json
5. Validate behavior
6. Test blocking
7. REFACTOR - Quality review

Announce: "Created 8 tasks (0–7). Starting execution..."

**Execution rules:**
1. `TaskUpdate status="in_progress"` BEFORE starting each task
2. `TaskUpdate status="completed"` ONLY after verification passes
3. If task fails → stay in_progress, diagnose, retry
4. NEVER skip to next task until current is completed
5. At end, `TaskList` to confirm all completed

## TDD Mapping for Hooks

| TDD Phase | Hook Creation | What You Do |
|-----------|---------------|-------------|
| **RED** | Test without hook | Write code, observe quality issues slip through |
| **Verify RED** | Document violations | Note specific issues that should be caught |
| **GREEN** | Write hook | Create script that catches those issues |
| **Verify GREEN** | Test blocking | Verify exit code 2 blocks violating code |
| **REFACTOR** | Optimize speed | Reduce hook runtime, filter file types |

## Task 0: Fetch Latest Official Spec

**Goal:** Pull the current Anthropic hook spec before designing — never trust cached memory.

**Action:**
```
Skill tool: fetching-claude-docs
  component: hook
  question: "hook events (PreToolUse, PostToolUse, etc.), matcher syntax,
             exit code contract, settings.json schema, additionalContext field,
             security considerations"
```

**Verification:** Received YAML with `source: https://code.claude.com/docs/en/hooks.md` and non-empty `spec_excerpt`. Use as authoritative reference; if any rule in this SKILL conflicts with the fetched spec, the fetched spec wins.

## Task 1: Analyze Requirements

**Goal:** Understand what quality gate to create.

**Questions to answer:**
- What violation should be blocked?
- Which files should be checked?
- What tool/command performs the check?
- What event triggers the hook?
- What is the project's primary language? (check `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `*.csproj`, etc.)

**Event Selection:**

| Event | When | Use For |
|-------|------|---------|
| `PreToolUse` | Before tool runs | Block bad writes before they happen |
| `PostToolUse` | After tool runs | Validate written code |
| `UserPromptSubmit` | Before prompt processed | Add context to prompts |
| `Stop` | When agent tries to end its turn | Self-verify loop — block stop until checks pass (Ralph Wiggum pattern, enables L-Thread) |

**Verification:** Can describe the violation and the command to detect it.

## Task 2: RED - Test Without Hook

**Goal:** Write code WITHOUT the hook. Observe violations that slip through.

**Process:**
1. Ask agent to write code in the target file type
2. Intentionally introduce the violation (bad format, type error, etc.)
3. Observe that Claude Code doesn't catch it
4. Document the specific violation

**Verification:** Documented at least 1 violation that should have been caught.

## Task 3: GREEN - Write Hook Script

**Goal:** Create Python script that catches the violations you documented.

### Hook Structure

```
.claude/hooks/
├── eslint_check.py
├── prettier_check.py
└── typecheck.py
```

### Exit Code Contract

| Code | Meaning | Effect |
|------|---------|--------|
| 0 | Pass | Continue, stdout shown in verbose |
| 2 | Block | Action blocked, stderr fed to Claude |
| Other | Warning | Continue, stderr shown in verbose |

### Hook Template

See [references/static-checks.md](references/static-checks.md) for complete hook templates. For performance-optimized security hooks, see [references/performance-optimization.md](references/performance-optimization.md). Key pattern: read JSON from stdin, filter by extension, run check, exit 2 to block.

### Stop Event Self-Verify (Ralph Wiggum / L-Thread)

When the agent tries to end its turn, block until deterministic checks pass — turning a one-shot agent into a loop that won't quit until the work is actually done.

**Use when:** long-running tasks, refactors, migrations, anything where "I think I'm done" is unreliable.

**Shape:**

```python
# .claude/hooks/stop_verify.py
import json, subprocess, sys

data = json.load(sys.stdin)
# Avoid infinite loop: respect stop_hook_active to bail after one retry
if data.get("stop_hook_active"):
    sys.exit(0)

result = subprocess.run(["pytest", "-x", "--tb=short"], capture_output=True, text=True)
if result.returncode != 0:
    print(result.stdout[-2000:], file=sys.stderr)
    sys.exit(2)  # Block stop, feed stderr to Claude
sys.exit(0)
```

```json
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop_verify.py",
        "timeout": 120
      }]
    }]
  }
}
```

**Critical:** always check `stop_hook_active` to bail after one retry — otherwise the agent loops forever on unfixable failures.

### Critical Requirements

- **Fast** - Under 5 seconds, hooks run synchronously
- **Performance constraints** - Total execution < 30s, parallel processing support
- **Graceful degradation** - Handle timeouts without blocking development
- **Filter files** - Only check relevant extensions  
- **Limit output** - First 5-10 errors, not all
- **Use Python** - Cross-platform, wrapped shell commands. In settings.json command, prefer `uv` → fallback `python3` → fallback `python` (see [cross-platform-scripts.md](../../references/cross-platform-scripts.md))
- **Progressive checks** - Fast/standard/thorough modes based on context
- **Cross-platform** - Must work on macOS, Linux, AND Windows

### Windows Compatibility (MANDATORY)

**Important:** Read [cross-platform-scripts.md](../../references/cross-platform-scripts.md) for full cross-platform rules covering paths, shell commands, line endings, and common pitfalls.

**Verification:**
- [ ] Script is executable (`chmod +x`) — skip on Windows
- [ ] Returns exit code 0 for valid files
- [ ] Returns exit code 2 for violations
- [ ] Runs under 5 seconds
- [ ] Uses `pathlib.Path` for all path operations
- [ ] No `shell=True` with string commands (use list args)
- [ ] No hardcoded `/tmp/` or path separators
- [ ] settings.json command uses three-runner fallback template (`uv` → `python3 --version` → `python`); `python3` probed by `--version` to avoid Windows Microsoft Store stub

## Task 4: Configure settings.json

**Goal:** Register hook in `.claude/settings.json`.

**Important:** Use `.claude/settings.json`, NOT `settings.local.json`. Settings are team-shared.

### Configuration Format

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/eslint_check.py",
          "timeout": 30
        }]
      }
    ]
  }
}
```

### Matcher Patterns

| Matcher | Matches |
|---------|---------|
| `Write\|Edit` | Write or Edit tools |
| `Bash` | Bash tool only |
| `.*` | All tools |

**Verification:**
- [ ] Hook registered in correct event
- [ ] Matcher targets correct tools
- [ ] Command path uses `$CLAUDE_PROJECT_DIR`
- [ ] Timeout is reasonable (5-30 seconds)

## Task 5: Validate Behavior

**Goal:** Verify hook script works correctly.

**Test command:**
```bash
echo '{"tool_input":{"file_path":"test.ts"}}' | .claude/hooks/you