hook-developer

SKILL.md

Hook Developer

Complete reference for developing Claude Code hooks. Use this to write hooks with correct input/output schemas.

When to Use

Creating a new hook

Debugging hook input/output format

Understanding what fields are available

Setting up hook registration in settings.json

Learning what hooks can block vs inject context

Quick Reference

Hook
Fires When
Can Block?
Primary Use

PreToolUse
Before tool executes
YES
Block/modify tool calls

PostToolUse
After tool completes
Partial
React to tool results

UserPromptSubmit
User sends prompt
YES
Validate/inject context

PermissionRequest
Permission dialog shows
YES
Auto-approve/deny

SessionStart
Session begins
NO
Load context, set env vars

SessionEnd
Session ends
NO
Cleanup/save state

Stop
Agent finishes
YES
Force continuation

SubagentStart
Subagent spawns
NO
Pattern coordination

SubagentStop
Subagent finishes
YES
Force continuation

PreCompact
Before compaction
NO
Save state

Notification
Notification sent
NO
Custom alerts

Hook type options: type: "command" (bash) or type: "prompt" (LLM evaluation)

Hook Input/Output Schemas

PreToolUse

Purpose: Block or modify tool execution before it happens.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "default|plan|acceptEdits|bypassPermissions",
  "hook_event_name": "PreToolUse",
  "tool_name": "string",
  "tool_input": {
    "file_path": "string",
    "command": "string"
  },
  "tool_use_id": "string"
}

Output (JSON):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "string",
    "updatedInput": {}
  },
  "continue": true,
  "stopReason": "string",
  "systemMessage": "string",
  "suppressOutput": true
}

Exit code 2: Blocks tool, stderr shown to Claude.

Common matchers: Bash, Edit|Write, Read, Task, mcp__.*

PostToolUse

Purpose: React to tool execution results, provide feedback to Claude.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "PostToolUse",
  "tool_name": "string",
  "tool_input": {},
  "tool_response": {
    "filePath": "string",
    "success": true,
    "output": "string",
    "exitCode": 0
  },
  "tool_use_id": "string"
}

CRITICAL: The response field is tool_response, NOT tool_result.

Output (JSON):

{
  "decision": "block",
  "reason": "string",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "string"
  },
  "continue": true,
  "stopReason": "string",
  "suppressOutput": true
}

Blocking: "decision": "block" with "reason" prompts Claude to address the issue.

Common matchers: Edit|Write, Bash

UserPromptSubmit

Purpose: Validate user prompts, inject context before Claude processes.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "string"
}

Output (Plain text):

Any stdout text is added to context for Claude.

Output (JSON):

{
  "decision": "block",
  "reason": "string",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "string"
  }
}

Blocking: "decision": "block" erases prompt, shows "reason" to user only (not Claude).

Exit code 2: Blocks prompt, shows stderr to user only.

PermissionRequest

Purpose: Automate permission dialog decisions.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "PermissionRequest",
  "tool_name": "string",
  "tool_input": {}
}

Output:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow|deny",
      "updatedInput": {},
      "message": "string",
      "interrupt": false
    }
  }
}

SessionStart

Purpose: Initialize session, load context, set environment variables.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "SessionStart",
  "source": "startup|resume|clear|compact"
}

Environment variable: CLAUDE_ENV_FILE - write export VAR=value to persist env vars.

Output (Plain text or JSON):

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "string"
  },
  "suppressOutput": true
}

Plain text stdout is added as context.

SessionEnd

Purpose: Cleanup, save state, log session.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "SessionEnd",
  "reason": "clear|logout|prompt_input_exit|other"
}

Output: Cannot affect session (already ending). Use for cleanup only.

Stop

Purpose: Control when Claude stops, force continuation.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "Stop",
  "stop_hook_active": false
}

CRITICAL: Check stop_hook_active: true to prevent infinite loops!

Output:

{
  "decision": "block",
  "reason": "string"
}

Blocking: "decision": "block" forces Claude to continue with "reason" as prompt.

SubagentStart

Purpose: Run when a subagent (Task tool) is spawned.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "SubagentStart",
  "agent_id": "string"
}

Output: Context injection only (cannot block).

SubagentStop

Purpose: Control when subagents (Task tool) stop.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false
}

Output: Same as Stop.

PreCompact

Purpose: Save state before context compaction.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "PreCompact",
  "trigger": "manual|auto",
  "custom_instructions": "string"
}

Matchers: manual, auto

Output:

{
  "continue": true,
  "systemMessage": "string"
}

Notification

Purpose: Custom notification handling.

Input:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "Notification",
  "message": "string",
  "notification_type": "permission_prompt|idle_prompt|auth_success|elicitation_dialog"
}

Matchers: permission_prompt, idle_prompt, auth_success, elicitation_dialog, *

Output:

{
  "continue": true,
  "suppressOutput": true,
  "systemMessage": "string"
}

Registration in settings.json

Standard Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/my-hook.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Matcher Patterns

Pattern
Matches

Bash
Exactly Bash tool

Edit|Write
Edit OR Write

Read.*
Regex: Read*

mcp__.*__write.*
MCP write tools

*
All tools

Case-sensitive: Bash ≠ bash

Events Requiring Matchers

PreToolUse - YES (required)

PostToolUse - YES (required)

PermissionRequest - YES (required)

Notification - YES (optional)

SessionStart - YES (startup|resume|clear|compact)

PreCompact - YES (manual|auto)

Events Without Matchers

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{ "type": "command", "command": "/path/to/hook.sh" }]
      }
    ]
  }
}

Hook Types

Command Hooks (type: "command")

Default type. Executes bash commands or scripts.

{
  "type": "command",
  "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/my-hook.sh",
  "timeout": 60
}

Prompt-Based Hooks (type: "prompt")

Uses LLM (Haiku) for context-aware decisions. Best for Stop/SubagentStop.

{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop. Context: $ARGUMENTS. Check if all tasks are complete.",
  "timeout": 30
}

Response schema:

{
  "decision": "approve" | "block",
  "reason": "Explanation",
  "continue": false,
  "stopReason": "Message to user",
  "systemMessage": "Warning"
}

MCP Tool Naming

MCP tools use pattern mcp__<server>__<tool>:

Pattern
Matches

mcp__memory__.*
All memory server tools

mcp__.*__write.*
All MCP write tools

mcp__github__.*
All GitHub tools

Environment Variables

Available to All Hooks

Variable
Description

CLAUDE_PROJECT_DIR
Absolute path to project root

CLAUDE_CODE_REMOTE
"true" if remote/web, empty if local CLI

SessionStart Only

Variable
Description

CLAUDE_ENV_FILE
Path to write export VAR=value lines

Plugin Hooks Only

Variable
Description

CLAUDE_PLUGIN_ROOT
Absolute path to plugin directory

Exit Codes

Exit Code
Behavior
stdout
stderr

0
Success
JSON processed
Ignored

2
Blocking error
IGNORED
Error message

Other
Non-blocking error
Ignored
Verbose mode

Exit Code 2 by Hook

Hook
Effect

PreToolUse
Blocks tool, stderr to Claude

PostToolUse
stderr to Claude (tool already ran)

UserPromptSubmit
Blocks prompt, stderr to user only

Stop
Blocks stop, stderr to Claude

Shell Wrapper Pattern

#!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
cat | npx tsx src/my-hook.ts

Or for bundled:

#!/bin/bash
set -e
cd "$HOME/.claude/hooks"
cat | node dist/my-hook.mjs

TypeScript Handler Pattern

import { readFileSync } from 'fs';

interface HookInput {
  session_id: string;
  hook_event_name: string;
  tool_name?: string;
  tool_input?: Record<string, unknown>;
  tool_response?: Record<string, unknown>;
  // ... other fields per hook type
}

function readStdin(): string {
  return readFileSync(0, 'utf-8');
}

async function main() {
  const input: HookInput = JSON.parse(readStdin());

  // Process input

  const output = {
    decision: 'block',  // or undefined to allow
    reason: 'Why blocking'
  };

  console.log(JSON.stringify(output));
}

main().catch(console.error);

Testing Hooks

Manual Test Commands

# PostToolUse (Write)
echo '{"tool_name":"Write","tool_input":{"file_path":"test.md"},"tool_response":{"success":true},"session_id":"test"}' | \
  .claude/hooks/my-hook.sh

# PreToolUse (Bash)
echo '{"tool_name":"Bash","tool_input":{"command":"ls"},"session_id":"test"}' | \
  .claude/hooks/my-hook.sh

# SessionStart
echo '{"hook_event_name":"SessionStart","source":"startup","session_id":"test"}' | \
  .claude/hooks/session-start.sh

# SessionEnd
echo '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"test"}' | \
  .claude/hooks/session-end.sh

# UserPromptSubmit
echo '{"prompt":"test prompt","session_id":"test"}' | \
  .claude/hooks/prompt-submit.sh

Rebuild After TypeScript Edits

cd .claude/hooks
npx esbuild src/my-hook.ts \
  --bundle --platform=node --format=esm \
  --outfile=dist/my-hook.mjs

Common Patterns

Block Dangerous Files (PreToolUse)

#!/usr/bin/env python3
import json, sys

data = json.load(sys.stdin)
path = data.get('tool_input', {}).get('file_path', '')

BLOCKED = ['.env', 'secrets.json', '.git/']
if any(b in path for b in BLOCKED):
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": f"Blocked: {path} is protected"
        }
    }))
else:
    print('{}')

Auto-Format Files (PostToolUse)

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" == *.ts ]] || [[ "$FILE" == *.tsx ]]; then
  npx prettier --write "$FILE" 2>/dev/null
fi

echo '{}'

Inject Git Context (UserPromptSubmit)

#!/bin/bash
echo "Git status:"
git status --short 2>/dev/null || echo "(not a git repo)"
echo ""
echo "Recent commits:"
git log --oneline -5 2>/dev/null || echo "(no commits)"

Force Test Verification (Stop)

#!/usr/bin/env python3
import json, sys, subprocess

data = json.load(sys.stdin)

# Prevent infinite loops
if data.get('stop_hook_active'):
    print('{}')
    sys.exit(0)

# Check if tests pass
result = subprocess.run(['npm', 'test'], capture_output=True)
if result.returncode != 0:
    print(json.dumps({
        "decision": "block",
        "reason": "Tests are failing. Please fix before stopping."
    }))
else:
    print('{}')

Debugging Checklist

 Hook registered in settings.json?

 Shell script has +x permission?

 Bundle rebuilt after TS changes?

 Using tool_response not tool_result?

 Output is valid JSON (or plain text)?

 Checking stop_hook_active in Stop hooks?

 Using $CLAUDE_PROJECT_DIR for paths?

Key Learnings from Past Sessions

Field names matter - tool_response not tool_result

Output format - decision: "block" + reason for blocking

Exit code 2 - stderr goes to Claude/user, stdout IGNORED

Rebuild bundles - TypeScript source edits don't auto-apply

Test manually - echo '{}' | ./hook.sh before relying on it

Check outputs first - ls .claude/cache/ before editing code

Detached spawn hides errors - add logging to debug

See Also

/debug-hooks - Systematic debugging workflow

.claude/rules/hooks.md - Hook development rules

1d