Hooks ReferenceSAFE

High-performance AI coding agent CLI written in Rust with zero unsafe code

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: hooks-reference
description: >-
  Use this skill when asked about "hooks", "PreToolUse", "PostToolUse",
  "SessionStart", "hook events", "validate tool use", "block commands",
  "add context on session start", or implementing event-driven automation.
---

# Hooks Reference Skill

This skill provides comprehensive guidance for implementing Claude Code hooks - event handlers that automate validation, context loading, and workflow enforcement.

## Hook Events Overview

| Event | When Triggered | Use Cases |
|-------|----------------|-----------|
| `PreToolUse` | Before tool executes | Validate, block, modify |
| `PostToolUse` | After tool completes | Audit, react, verify |
| `PermissionRequest` | Permission dialog shown | Auto-allow, auto-deny |
| `Stop` | Claude finishes | Force continue, verify |
| `SubagentStop` | Subagent finishes | Verify task complete |
| `SessionStart` | Session begins | Load context, setup |
| `SessionEnd` | Session ends | Cleanup, save state |
| `UserPromptSubmit` | Prompt submitted | Validate, add context |
| `PreCompact` | Before compaction | Preserve info |
| `Notification` | Notification sent | Alert, log |

## hooks.json Structure

Basic structure:
```json
{
  "description": "What these hooks do",
  "hooks": {
    "EventName": [
      {
        "matcher": "Pattern",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/handler.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

## Matcher Patterns

For tool events (PreToolUse, PostToolUse, PermissionRequest):
- `"Write"` - Match exact tool name
- `"Write|Edit"` - Match multiple tools (regex)
- `"Notebook.*"` - Regex pattern
- `"*"` or `""` - Match all tools

For SessionStart:
- `"startup"` - Initial startup
- `"resume"` - From --resume, --continue, /resume
- `"clear"` - From /clear
- `"compact"` - From auto/manual compact

For Notification:
- `"permission_prompt"` - Permission requests
- `"idle_prompt"` - Claude waiting for input

## Hook Types

### Command Hooks (type: "command")
Execute a bash script:
```json
{
  "type": "command",
  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
  "timeout": 30
}
```

### Prompt Hooks (type: "prompt")
LLM-based evaluation (Stop, SubagentStop only):
```json
{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete.",
  "timeout": 30
}
```

## Exit Codes

| Exit Code | Meaning | Behavior |
|-----------|---------|----------|
| 0 | Success | Action proceeds, stdout to user (verbose) |
| 2 | Block | Action blocked, stderr shown to Claude |
| Other | Error | Non-blocking, stderr to user (verbose) |

## Hook Input (stdin JSON)

Common fields:
```json
{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse"
}
```

PreToolUse specific:
```json
{
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_use_id": "toolu_01ABC..."
}
```

SessionStart specific:
```json
{
  "source": "startup"
}
```

Stop specific:
```json
{
  "stop_hook_active": false
}
```

## Advanced JSON Output

Return structured decisions via stdout (exit code 0):

### PreToolUse Decision Control
```json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Auto-approved documentation file",
    "updatedInput": {
      "field_to_modify": "new value"
    }
  }
}
```

Decision values: `"allow"`, `"deny"`, `"ask"`

### Stop Decision Control
```json
{
  "decision": "block",
  "reason": "Not all tasks complete - still need to run tests"
}
```

### UserPromptSubmit Context
```json
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current time: 2024-01-15 10:30:00"
  }
}
```

### SessionStart Context
```json
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project context loaded..."
  }
}
```

## Example Hooks

### 1. Validate File Writes (PreToolUse)

hooks/hooks.json:
```json
{
  "description": "Validate file write operations",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

scripts/validate-write.sh:
```bash
#!/usr/bin/env bash

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')

# Block writes to sensitive files
if [[ "$FILE_PATH" == *.env* ]] || [[ "$FILE_PATH" == *secret* ]]; then
  echo "Cannot write to sensitive files: $FILE_PATH" >&2
  exit 2
fi

# Block writes outside project
if [[ ! "$FILE_PATH" == "$CLAUDE_PROJECT_DIR"* ]]; then
  echo "Cannot write outside project directory" >&2
  exit 2
fi

exit 0
```

### 2. Block Dangerous Commands (PreToolUse)

hooks/hooks.json:
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bash.sh"
          }
        ]
      }
    ]
  }
}
```

scripts/validate-bash.sh:
```bash
#!/usr/bin/env bash

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block destructive commands
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  ":(){ :|:& };:"
  "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if [[ "$COMMAND" == *"$pattern"* ]]; then
    echo "Blocked dangerous command pattern: $pattern" >&2
    exit 2
  fi
done

exit 0
```

### 3. Load Project Context (SessionStart)

hooks/hooks.json:
```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

.beads/beads.jsonl

Gates applied: no_behavioural_pass.