Imported from gabrielgadea/claude-code-kazuba (claude_code_kazuba/data/modules/skills-meta/skills/hook-master/SKILL.md). Install upstream with npx skills add gabrielgadea/claude-code-kazuba --skill hook-master. Copyright stays with the author.

Hook Master

Philosophy

Hooks are the nervous system of Claude Code. They intercept events, enforce policies, and inject context — silently, reliably, and fail-safe.

Hook Event Reference (18 events)

Exit Code Contract

Critical rule: Hooks MUST fail-open. If your hook crashes or times out, the exit code should be 0 (allow). Never let a broken hook block the user's workflow.

JSON Output Schemas

UserPromptSubmit Output

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Injected context string visible to Claude"
  }
}

PreToolUse Output (allow)

{}

PreToolUse Output (block with reason for Claude)

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "decision": "block",
    "reason": "Writing to protected path /etc/passwd"
  }
}

PostToolUse Output

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "suppressOutput": false
  }
}

Python Hook Template

#!/usr/bin/env python3
"""Hook: [EVENT_NAME] — [brief description].

Exit codes: 0=ALLOW, 1=BLOCK(user), 2=DENY(Claude)
"""
from __future__ import annotations

import json
import sys
from dataclasses import dataclass, field


@dataclass(frozen=True)
class HookConfig:
    """Static configuration for this hook."""
    enabled: bool = True
    timeout_seconds: int = 10
    # Add hook-specific config here


@dataclass(frozen=True)
class HookInput:
    """Parsed stdin from Claude Code."""
    session_id: str
    cwd: str
    hook_event_name: str
    # Add event-specific fields here

    @classmethod
    def from_stdin(cls) -> HookInput:
        raw = json.loads(sys.stdin.read())
        return cls(
            session_id=raw.get("session_id", ""),
            cwd=raw.get("cwd", ""),
            hook_event_name=raw.get("hook_event_name", ""),
        )


@dataclass(frozen=True)
class HookResult:
    """Output to stdout for Claude Code."""
    exit_code: int = 0
    output: dict | None = None
    error: str = ""

    def emit(self) -> None:
        if self.output:
            json.dump(self.output, sys.stdout)
        if self.error:
            print(self.error, file=sys.stderr)
        sys.exit(self.exit_code)


def main() -> None:
    config = HookConfig()
    if not config.enabled:
        sys.exit(0)

    try:
        hook_input = HookInput.from_stdin()
        # --- Hook logic here ---
        result = HookResult(exit_code=0)
        result.emit()
    except Exception:
        # FAIL-OPEN: never block on hook errors
        sys.exit(0)


if __name__ == "__main__":
    main()

Shell Hook Template

#!/usr/bin/env bash
# Hook: [EVENT_NAME] — [brief description]
# Exit codes: 0=ALLOW, 1=BLOCK(user), 2=DENY(Claude)
set -euo pipefail

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))")

# --- Hook logic here ---
# Example: block Write to /etc/
if [[ "$TOOL_NAME" == "Write" ]]; then
    FILE_PATH=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))")
    if [[ "$FILE_PATH" == /etc/* ]]; then
        echo "Blocked: cannot write to /etc/" >&2
        exit 2
    fi
fi

# ALLOW by default
exit 0

Testing Methodology

1. Unit Test: stdin mock

# Test with mock input
echo '{"session_id":"test","cwd":"/tmp","hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"/etc/passwd"}}' \
  | python3 hooks/my_hook.py
echo "Exit code: $?"

2. Exit Code Verification

import subprocess
import json

def test_hook_blocks_etc():
    inp = json.dumps({
        "session_id": "test",
        "cwd": "/tmp",
        "hook_event_name": "PreToolUse",
        "tool_name": "Write",
        "tool_input": {"file_path": "/etc/passwd"},
    })
    result = subprocess.run(
        ["python3", "hooks/my_hook.py"],
        input=inp, capture_output=True, text=True,
    )
    assert result.returncode == 2
    assert "Blocked" in result.stderr

3. Integration Test

Register the hook in settings.json, then trigger the event manually:

# Add to .claude/settings.json hooks section
# Run claude with a prompt that triggers the hook event
# Verify behavior via logs or output

Common Pitfalls

Debugging Tips

1. Log to stderr: Stderr is captured but does not affect hook behavior (unless exit != 0).
2. Temp file logging: Write debug info to /tmp/hook_debug.log during development.
3. Dry run mode: Add --dry-run flag that prints what the hook would do without acting.
4. Check hook registration: cat .claude/settings.json | python3 -m json.tool | grep hooks
5. Verify event fires: Add a simple echo hook first to confirm the event triggers.