# Hooks Reference

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-a-ariff-ariff-claude-plugins-hooks-reference`
- **Verified:** Pending review
- **Seller:** [a-ariff](https://agentstack.voostack.com/s/a-ariff)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [a-ariff](https://github.com/a-ariff)
- **Source:** https://github.com/a-ariff/ariff-claude-plugins/tree/main/plugins/hooks-reference/skills/hooks-reference
- **Website:** https://github.com/a-ariff/ariff-claude-plugins#quick-start

## Install

```sh
agentstack add skill-a-ariff-ariff-claude-plugins-hooks-reference
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
          }
        ]
      }
    ]
  }
}
```

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

CONTEXT=""

# Load CLAUDE.md if exists
if [ -f "$CLAUDE_PROJECT_DIR/CLAUDE.md" ]; then
  CONTEXT+="Project instructions from CLAUDE.md have been loaded.\n"
fi

# Add git status
if [ -d "$CLAUDE_PROJECT_DIR/.git" ]; then
  BRANCH=$(git -C "$CLAUDE_PROJECT_DIR" branch --show-current 2>/dev/null)
  CONTEXT+="Current git branch: $BRANCH\n"
fi

# Output as JSON for structured context
cat > "$CLAUDE_ENV_FILE"
  echo 'export API_URL=http://localhost:3000' >> "$CLAUDE_ENV_FILE"
fi

exit 0
```

## Best Practices

1. **Always quote variables**: Use `"$VAR"` not `$VAR`
2. **Validate input**: Never trust stdin blindly
3. **Use portable paths**: `${CLAUDE_PLUGIN_ROOT}` for plugin files
4. **Set timeouts**: Prevent hanging hooks
5. **Handle errors**: Check for missing fields with `// empty`
6. **Keep hooks fast**: Target <1 second execution
7. **Use jq for JSON**: Safer than string parsing

## Debugging

Enable debug mode:
```bash
claude --debug
```

Test hook manually:
```bash
echo '{"tool_name":"Write","tool_input":{"file_path":"test.txt"}}' | \
  ./scripts/validate-write.sh
echo $?  # Check exit code
```

## References

- Hooks documentation: https://code.claude.com/docs/en/hooks
- Hooks guide: https://code.claude.com/docs/en/hooks-guide
- Example hooks: https://github.com/anthropics/claude-code/tree/main/examples/hooks

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [a-ariff](https://github.com/a-ariff)
- **Source:** [a-ariff/ariff-claude-plugins](https://github.com/a-ariff/ariff-claude-plugins)
- **License:** MIT
- **Homepage:** https://github.com/a-ariff/ariff-claude-plugins#quick-start

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-a-ariff-ariff-claude-plugins-hooks-reference
- Seller: https://agentstack.voostack.com/s/a-ariff
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.