Claude Code Hook Writer

Creates Python hooks for Claude Code with correct JSON output schemas and fail-open patterns.

Hook Types

Event	Trigger	Use Case
PreToolUse	Before tool execution	Block dangerous commands, validate inputs
PostToolUse	After tool execution	Log results, trigger follow-up actions
UserPromptSubmit	Before prompt processing	Validate/transform user input
Stop	Session ends	Cleanup, summary generation
SubagentStop	Subagent completes	Aggregate results, status reporting

JSON Output Schema

PreToolUse/PostToolUse (Permission Decisions)

json

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Optional explanation"
  }
}

Field	Values	Required
`hookEventName`	`"PreToolUse"` or `"PostToolUse"`	Yes
`permissionDecision`	`"allow"`, `"deny"`, `"ask"`	Yes
`permissionDecisionReason`	String explanation	No (recommended for deny)

DEPRECATED FORMAT (DO NOT USE):

json

{"decision": "allow", "message": null}

UserPromptSubmit

json

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "modifiedPrompt": "Transformed user prompt"
  }
}

Stop/SubagentStop

json

{
  "hookSpecificOutput": {
    "hookEventName": "Stop"
  }
}

Python TypedDict Templates

PreToolUse/PostToolUse

python

from typing import TypedDict


class HookSpecificOutput(TypedDict, total=False):
    """Inner hook output structure."""
    hookEventName: str
    permissionDecision: str  # "allow" | "deny" | "ask"
    permissionDecisionReason: str


class HookOutput(TypedDict):
    """JSON output returned via stdout."""
    hookSpecificOutput: HookSpecificOutput

UserPromptSubmit

python

from typing import TypedDict


class HookSpecificOutput(TypedDict, total=False):
    """Inner hook output structure."""
    hookEventName: str
    modifiedPrompt: str


class HookOutput(TypedDict):
    """JSON output returned via stdout."""
    hookSpecificOutput: HookSpecificOutput

Hook Input Schema

Hooks receive JSON via stdin:

python

class ToolInput(TypedDict, total=False):
    """Tool parameters from Claude Code."""
    command: str      # Bash commands
    file_path: str    # Write/Edit/Read targets
    content: str      # Write content
    old_string: str   # Edit source
    new_string: str   # Edit replacement


class HookInput(TypedDict):
    """JSON input received via stdin."""
    tool_name: str    # "Bash", "Write", "Edit", "Read", etc.
    tool_input: ToolInput

Complete Hook Template

python

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Pretooluse hook for Claude Code that [PURPOSE].

[DETAILED DESCRIPTION]
Fail-open principle: allow operations if hook encounters errors.
"""

import json
import sys
from typing import TypedDict


class ToolInput(TypedDict, total=False):
    """Tool parameters from Claude Code."""
    command: str


class HookInput(TypedDict):
    """JSON input received via stdin."""
    tool_name: str
    tool_input: ToolInput


class HookSpecificOutput(TypedDict, total=False):
    """Inner hook output structure."""
    hookEventName: str
    permissionDecision: str  # "allow" | "deny"
    permissionDecisionReason: str


class HookOutput(TypedDict):
    """JSON output returned via stdout."""
    hookSpecificOutput: HookSpecificOutput


def should_block_tool(tool_name: str, tool_input: ToolInput) -> tuple[bool, str | None]:
    """
    Determine if tool should be blocked.

    Returns:
        (should_block, message): Tuple of block decision and optional message
    """
    # Only inspect specific tools
    if tool_name != "Bash":
        return False, None

    command = tool_input.get("command", "")

    # Add detection logic here
    if "dangerous_pattern" in command:
        return True, "Blocked: explanation of why this is blocked."

    return False, None


def main() -> None:
    """Main hook execution."""
    try:
        # Read input from stdin
        input_data: HookInput = json.load(sys.stdin)
        tool_name = input_data.get("tool_name", "")
        tool_input = input_data.get("tool_input", {})

        # Determine if should block
        should_block, message = should_block_tool(tool_name, tool_input)

        # Return decision in Claude Code hook format
        hook_output: HookSpecificOutput = {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny" if should_block else "allow",
        }
        if message:
            hook_output["permissionDecisionReason"] = message

        output: HookOutput = {"hookSpecificOutput": hook_output}
        print(json.dumps(output))

    except Exception as e:
        # Fail-open: if hook crashes, allow the operation
        output: HookOutput = {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "allow",
            }
        }
        print(json.dumps(output))
        print(f"Hook error: {e}", file=sys.stderr)
        sys.exit(0)


if __name__ == "__main__":
    main()

settings.json Configuration

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "uv run --no-project --script /path/to/hook.py"
      }
    ]
  }
}

Matcher Options

Matcher	Matches
`"Bash"`	Bash tool only
`"Write"`	Write tool only
`"*"`	All tools
`["Bash", "Write"]`	Multiple specific tools

Fail-Open Principle

Hooks MUST fail-open to prevent blocking legitimate operations due to hook errors:

•Wrap main logic in try/except
•Exception handler outputs "permissionDecision": "allow"
•Log error to stderr (optional)
•Exit with 0 (not error code)

python

except Exception as e:
    # Fail-open: if hook crashes, allow the operation
    output: HookOutput = {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "allow",
        }
    }
    print(json.dumps(output))
    print(f"Hook error: {e}", file=sys.stderr)
    sys.exit(0)  # Exit cleanly even on error

Reference Implementations

Hook	Purpose	Location
dry-run-guard.py	Block file-writing in dry-run mode	`core/hooks/pretooluse/`
git-commit-guard.py	Block --no-verify flag	`core/hooks/pretooluse/`
gsuite-public-asset-guard.py	Block public asset creation	`core/hooks/pretooluse/`

Workflow

•Identify the tool(s) to monitor
•Define blocking conditions (patterns, state checks)
•Create hook using template above
•Test manually: echo '{"tool_name":"Bash","tool_input":{"command":"test"}}' | python hook.py
•Configure in settings.json
•Verify hook triggers on actual tool use