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