hook-dev

What this skill does

# Hook Dev Skill

This skill helps create production-ready Claude Code hooks following Anthropic's official specifications.

## What are Hooks?

**Hooks** are user-defined shell commands that execute at various points in Claude Code's lifecycle. They provide:

- **Deterministic control**: Ensure actions happen automatically, not relying on LLM decisions
- **Workflow automation**: Format code, run linters, log commands
- **Custom notifications**: Alert when Claude needs input
- **Permission systems**: Block sensitive file modifications
- **Feedback loops**: Validate code changes against conventions

## Hook vs Skill vs Command

| Feature | Hook | Skill | Command |
|---------|------|-------|---------|
| **Trigger** | Lifecycle event | Context match | User invocation |
| **Type** | Shell command | AI capability | Prompt template |
| **Use case** | Automation, validation | Autonomous features | Reusable prompts |
| **Control** | Deterministic | LLM-driven | User-initiated |

**When to use Hooks**: Automatic formatting, logging, notifications, permission control, code validation

## Hook Events

Ten lifecycle events trigger hooks:

### 1. PreToolUse
Executes **after Claude creates tool parameters but before processing**.

**Use cases**:
- Block edits to sensitive files (.env, production configs)
- Validate bash commands before execution
- Request confirmation for destructive operations
- Log all tool usage for auditing
- Modify tool inputs programmatically

**Blocking capability**: Yes - exit code 2 blocks with error fed to Claude; JSON output with `"permissionDecision": "deny"` also blocks

### 2. PostToolUse
Runs **immediately after successful tool completion**.

**Use cases**:
- Format code after edits (Prettier, Black, gofmt)
- Run linters after file modifications
- Sync changes to external systems
- Update indexes or caches

**Blocking capability**: No - tool already executed

### 3. UserPromptSubmit
Fires when users **submit prompts, before Claude processes them**.

**Use cases**:
- Inject context automatically (git status, env variables)
- Log user interactions
- Validate prompt safety
- Add project-specific context

**Blocking capability**: Yes - JSON output with `"decision": "block"` prevents submission

### 4. PermissionRequest
Activates when **permission dialogs appear to users**.

**Use cases**:
- Auto-approve safe operations
- Auto-deny dangerous operations
- Log permission requests
- Provide context for decisions

**Blocking capability**: Yes - can allow, deny, or pass through to user

### 5. Notification
Triggers when **Claude Code sends notifications**.

**Use cases**:
- Custom notification sounds
- Desktop notifications (macOS, Linux, Windows)
- Send to Slack/Discord
- Visual alerts

**Blocking capability**: No - notification already generated

### 6. Stop
Activates when **the main agent finishes responding**.

**Use cases**:
- Run tests after code generation
- Update documentation
- Commit changes automatically
- Trigger deployments

**Blocking capability**: Yes - JSON output with `"decision": "block"` prevents stop

### 7. SubagentStop
Runs when **subagent tasks complete**.

**Use cases**:
- Log subagent results
- Validate subagent outputs
- Trigger next workflow steps
- Aggregate subagent data

**Blocking capability**: Yes - JSON output with `"decision": "block"` prevents stop

### 8. PreCompact
Executes **before context window compaction operations**.

**Use cases**:
- Save conversation state
- Export conversation history
- Archive important context

**Blocking capability**: Yes - can prevent compaction

### 9. SessionStart
Triggers at **session initialization or resumption**.

**Use cases**:
- Load project context
- Initialize environment variables
- Display project status
- Check for updates

**Blocking capability**: No - session already started

### 10. SessionEnd
Runs when **sessions terminate**.

**Use cases**:
- Save session state
- Cleanup temporary files
- Export logs
- Trigger cleanup scripts

**Blocking capability**: No - session already ending

## Hook Configuration

Hooks are configured in `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Editing file' >> /tmp/claude-audit.log"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.py$'; then black \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}
```

### Configuration Structure

```json
{
  "hooks": {
    "EventName": [                     // Event type (PreToolUse, PostToolUse, etc.)
      {
        "matcher": "ToolPattern",      // Tool name, regex (pipe-separated), or "*" for all
        "hooks": [                     // Array of hooks for this matcher
          {
            "type": "command",         // "command" or "prompt"
            "command": "shell command", // Shell command to execute
            "timeout": 60              // Optional timeout in seconds (default: 60)
          }
        ]
      }
    ]
  }
}
```

### Configuration Locations

- **User-level**: `~/.claude/settings.json` (all projects)
- **Project-level**: `.claude/settings.json` (this project, team-shared)
- **Local**: `.claude/settings.local.json` (uncommitted, project-specific overrides)
- **Plugin-level**: `plugin-name/hooks/hooks.json` (bundled with plugin)

## Matchers

### Tool Matching

**Exact match**:
```json
{
  "matcher": "Edit"
}
```

**Regex pattern** (use pipe for OR):
```json
{
  "matcher": "Edit|Write|MultiEdit"
}
```

**Wildcard** (match all tools):
```json
{
  "matcher": "*"
}
```

**Common tool names**: Bash, Read, Write, Edit, MultiEdit, Glob, Grep, Task, WebFetch, WebSearch, TodoRead, TodoWrite, NotebookRead, NotebookEdit

**MCP tools**: Use `mcp__<server>__<tool>` pattern (e.g., `mcp__github__create_issue`)

### Accessing Tool Data

Hook input arrives via **stdin as JSON**. Use `jq` to extract values:

```bash
# Access file_path from Edit tool
jq -r '.tool_input.file_path'

# Access bash command
jq -r '.tool_input.command'

# Check if file matches pattern
jq -r '.tool_input.file_path' | { read file_path; if echo "$file_path" | grep -q '\.py$'; then echo "Python file"; fi; }

# Access tool response (PostToolUse only)
jq -r '.tool_response'
```

**Common JSON fields**:
- `.session_id` - Current session identifier
- `.transcript_path` - Path to conversation transcript
- `.cwd` - Current working directory
- `.tool_name` - Name of the tool being used
- `.tool_input` - Tool parameters (varies by tool)
- `.tool_response` - Tool output (PostToolUse only)
- `.hook_event_name` - Name of the event

**Environment variables**:
- `$CLAUDE_PROJECT_DIR` - Project root absolute path
- `$CLAUDE_ENV_FILE` - For SessionStart hooks to persist environment variables
- `$CLAUDE_CODE_REMOTE` - "true" if remote execution, empty if local
- `${CLAUDE_PLUGIN_ROOT}` - Plugin directory path (plugin hooks only). Use this to reference scripts bundled with your plugin:
  ```json
  {
    "type": "command",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
  }
  ```

## Hook Types

### Command Hooks

Execute bash scripts with stdin JSON input:

```json
{
  "type": "command",
  "command": "jq -r '.tool_input.file_path' | xargs -I {} prettier --write {}"
}
```

**Exit codes**:
- `0` - Success; stdout shown to user (except UserPromptSubmit shows to Claude)
- `2` - Blocking error; stderr fed to Claude as context
- Other - Non-blocking error; stderr shown to user

### Prompt Hooks

Send input to LLM (Haiku) for decisions (PreToolUse, Stop, SubagentStop, UserPromptSubmit):

```json
{
  "type": "prompt",
  "prompt": "Analyze this tool use and decide if it should be allowed: {{input}}"
}
```

Returns JSON with decision fields.

## Con