Claude Code Hooks — I/O API Reference (May 2026)

JSON schemas for hook stdin input and stdout output per event. For hook system fundamentals, activate /plugin-creator:hooks-core-reference. For working examples, activate /plugin-creator:hooks-patterns.

---

Hook Input (JSON via stdin)

Common Fields (All Events)

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse"
}

permission_mode values: "default", "plan", "acceptEdits", "auto", "dontAsk", "bypassPermissions"

When running with --agent or inside a subagent, two additional fields are included:

| Field | Description | | --- | --- | | agent_id | Unique identifier for the subagent. Present only when the hook fires inside a subagent call | | agent_type | Agent name (e.g. "Explore" or "security-reviewer"). For custom subagents, this is the name field from the agent's frontmatter, not the filename |

PreToolUse Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "psql -c 'SELECT * FROM users'",
    "description": "Query the users table",
    "timeout": 120000
  },
  "tool_use_id": "toolu_01ABC123"
}

Tool-specific tool_input fields:

| Tool | Fields | | --- | --- | | Bash | command, description, timeout, run_in_background | | Write | file_path, content | | Edit | file_path, old_string, new_string, replace_all | | Read | file_path, offset, limit | | Glob | pattern, path | | Grep | pattern, path, glob, output_mode, -i, multiline | | WebFetch | url, prompt | | WebSearch | query, allowed_domains, blocked_domains | | Agent | prompt, description, subagent_type, model |

PostToolUse Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  },
  "tool_use_id": "toolu_01ABC123",
  "duration_ms": 12
}

duration_ms: tool execution time in milliseconds, excluding permission prompts and PreToolUse hooks.

PostToolUseFailure Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" },
  "tool_use_id": "toolu_01ABC123",
  "error": "Command exited with non-zero status code 1",
  "is_interrupt": false,
  "duration_ms": 4187
}

PostToolBatch Input

Fires once after every tool call in a parallel batch resolves, before the next model call. No matcher support.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": { "file_path": "/path/to/file.py" },
      "tool_use_id": "toolu_01...",
      "tool_response": "     1\tfile contents..."
    }
  ]
}

Note: tool_response in PostToolBatch is the serialized tool_result content the model sees — different from PostToolUse's structured Output object.

PermissionRequest Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

PermissionDenied Input

Fires when the auto mode classifier denies a tool call. Does not fire on manual denials or PreToolUse blocks.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf /tmp/build" },
  "tool_use_id": "toolu_01ABC123",
  "reason": "Auto mode denied: command targets a path outside the project"
}

Notification Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission to use Bash",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

notification_type values: permission_prompt, idle_prompt, auth_success, elicitation_dialog, elicitation_complete, elicitation_response

UserPromptSubmit Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate factorial"
}

UserPromptExpansion Input

Fires when a user-typed slash command expands into a prompt, before it reaches Claude.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "UserPromptExpansion",
  "expansion_type": "slash_command",
  "command_name": "example-skill",
  "command_args": "arg1 arg2",
  "command_source": "plugin",
  "prompt": "/example-skill arg1 arg2"
}

Matcher filters on command_name. expansion_type is slash_command for skills/commands or mcp_prompt for MCP server prompts.

Stop Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

• stop_hook_active: true when Claude is already continuing due to a stop hook — check to prevent infinite loops. Claude Code overrides after 8 consecutive blocks.
• last_assistant_message: text content of Claude's final response (no transcript parsing needed)
• background_tasks: in-flight background tasks (v2.1.145+). Each entry: id, type (shell/subagent/monitor/workflow/teammate/etc.), status, description, plus type-specific fields (command, agent_type, server, tool, name)
• session_crons: scheduled session wakeups (v2.1.145+). Each entry: id, schedule, recurring, prompt

StopFailure Input

Fires instead of Stop when the turn ends due to an API error. Output and exit code are ignored.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

error values: rate_limit, authentication_failed, oauth_org_not_allowed, billing_error, invalid_request, model_not_found, server_error, max_output_tokens, unknown

SubagentStart Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

• agent_type: built-in agent names ("general-purpose", "Explore", "Plan") or, for custom agents, the name field from the agent's frontmatter (not the filename). Matcher filters on this value.

SubagentStop Input

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "docs-review-agent",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

• agent_type: the name field from the agent's frontmatter (not the filename). Matcher filters on this value — same matcher values as SubagentStart.
• agent_transcript_path: path to the subagent's own transcript in nested subagents/ folder
• last_assistant_message: text content of the subagent's final response (no transcript parsing needed)
• background_tasks, session_crons: scoped to the parent session, not the subagent (v2.1.145+)

TaskCreated Input

Fires when a task is being created via TaskCreate. No matcher support.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "my-project"
}

TaskCompleted Input

Fires when a task is being marked as completed. No matcher support.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "my-project"
}

TeammateIdle Input

Fires when an agent team teammate is about to go idle. No matcher support.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "my-project"
}

ConfigChange Input

Fires when a configuration file changes during a session. Matcher filters on source.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/path/to/.claude/settings.json"
}

source / matcher values: user_settings, project_settings, local_settings, policy_settings, skills

CwdChanged Input

Fires when working directory changes. No matcher support. Has access to CLAUDE_ENV_FILE.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/new/dir",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/path/to/project",
  "new_cwd": "/path/to/project/src"
}

FileChanged Input

Fires when a watched file changes. Matcher serves dual role: builds the watch list (literal filenames split on |) AND filters which hooks run.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "FileChanged",
  "file_path": "/path/to/project/.envrc",
  "event": "change"
}

event values: change (modified), add (created), unlink (deleted)

WorktreeCreate Input

Fires when a worktree is being created. Replaces default git worktree behavior when configured.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

WorktreeRemove Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/path/to/.claude/worktrees/feature-auth"
}

PreCompact Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

trigger / matcher values: manual, auto

PostCompact Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

InstructionsLoaded Input

Fires when a CLAUDE.md or .claude/rules/*.md file is loaded. Matcher filters on load_reason.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "/path/to/project/CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}

load_reason / matcher values: session_start, nested_traversal, path_glob_match, include, compact

Elicitation Input

Fires when an MCP server requests user input. Matcher filters on MCP server name.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

ElicitationResult Input

Fires after a user responds to an MCP elicitation. Matcher filters on MCP server name.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

Setup Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "Setup",
  "trigger": "init"
}

• trigger: "init" (from --init or --init-only) or "maintenance" (from --maintenance)
• Has access to CLAUDE_ENV_FILE for persisting environment variables

SessionStart Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "SessionStart",
  "source": "startup",
  "model": "claude-sonnet-4-6"
}

• source / matcher values: startup, resume, clear, compact
• model: model identifier
• agent_type: present when Claude Code started with claude --agent <name>
• Has access to CLAUDE_ENV_FILE for persisting environment variables

SessionEnd Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

reason / matcher values: clear, resume, logout, prompt_input_exit, bypass_permissions_disabled, other

---

Hook Output

Exit Codes

| Code | Behavior | | --- | --- | | 0 | Success. stdout processed (JSON or plain text) | | 2 | Blocking error. stderr fed back to Claude (or shown to user, event-dependent) | | Other | Non-blocking error. stderr shown in verbose mode (Ctrl+O). Execution continues |

Important: JSON output is only processed on exit 0. Exit code 2 uses stderr only.

Note: Exit code 1 is non-blocking for most events — execution continues. Only exit code 2 blocks. Exception: WorktreeCreate — any non-zero exit code fails worktree creation.

Exit Code 2 Behavior Per Event

| Event | Can Block? | Exit Code 2 Effect | | --- | --- | --- | | PreToolUse | Yes | Blocks tool call, shows stderr to Claude | | PermissionRequest | Yes | Denies permission, shows stderr to Claude | | UserPromptSubmit | Yes | Blocks prompt, erases it, shows stderr to user | | UserPromptExpansion | Yes | Blocks the expansion | | Stop | Yes | Blocks stoppage, shows stderr to Claude | | SubagentStop | Yes | Blocks stoppage, shows stderr to Claude subagent | | TeammateIdle | Yes | Prevents teammate going idle, shows stderr as feedback | | TaskCreated | Yes | Rolls back task creation, shows stderr as feedback | | TaskCompleted | Yes | Prevents task completion, shows stderr as feedback | | ConfigChange | Yes | Blocks config change (except policy_settings) | | PreCompact | Yes | Blocks compaction | | PostToolBatch | Yes | Stops agentic loop before next model call | | Elicitation | Yes | Denies the elicitation | | ElicitationResult | Yes | Blocks the response (action becomes decline) | | WorktreeCreate | Yes | Any non-zero exit fails worktree creation | | PostToolUse | No | Shows stderr to Claude (tool already ran) | | PostToolUseFailure | No | Shows stderr to Claude (tool already failed) | | PermissionDenied | No | Exit code ignored. Use JSON hookSpecificOutput.retry: true to allow retry | | Notification | No | Shows stderr to user only | | SubagentStart | No | Shows stderr to user only | | StopFailure | No | Output and exit code ignored | | PreCompact | Yes | Blocks compaction, stderr shown to user | | PostCompact | No | Shows stderr to user only | | Setup | No | Shows stderr to user only | | SessionStart | No | Shows stderr to user only | | SessionEnd | No | Shows stderr to user only | | CwdChanged | No | Shows stderr to user only | | FileChanged | No | Shows stderr to user only | | WorktreeRemove | No | Failures logged in debug mode only | | InstructionsLoaded | No | Exit code ignored |

---

JSON Output Control

Important: JSON output only processed with exit code 0. Exit code 2 uses stderr only.

Common JSON Fields (All Events)

{
  "continue": true,
  "stopReason": "Message shown when continue is false",
  "suppressOutput": false,
  "systemMessage": "Optional warning message shown to user",
  "terminalSequence": "]777;notify;Claude Code;Needs attention"
}

| Field | Type | Effect | | --- | --- | --- | | continue | boolean | false stops Claude entirely (takes precedence over all other fields) | | stopReason | string | Shown to user when continue is false | | suppressOutput | boolean | Hide stdout from transcript mode | | systemMessage | string | Warning message shown to user | | terminalSequence | string | Terminal escape sequence emitted by Claude Code on your behalf. Restricted to OSC 0/1/2/9/99/777 and BEL. Use instead of writing to /dev/tty (hooks run without a controlling terminal) |

PreToolUse JSON Output

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Auto-approved documentation file",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

| Field | Values | Effect | | --- | --- | --- | | permissionDecision | allow, deny, ask, defer | Controls tool execution. defer only valid in non-interactive -p mode — pauses for resume | | permissionDecisionReason | string | Shown to user (allow/ask) or Claude (deny). Ignored for defer | | updatedInput | object | Modifies tool input before execution. Include all fields, not just changed ones | | additionalContext | string | Added to Claude's context alongside the tool result |

Precedence when multiple hooks return different decisions: deny > defer > ask > allow

Note: Top-level decision and reason fields are deprecated for PreToolUse. Use hookSpecificOutput.permissionDecision and hookSpecificOutput.permissionDecisionReason. Deprecated "approve" maps to "allow", "block" maps to "deny".

PermissionRequest JSON Output

Allow with modified input:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": { "command": "npm run lint" }
    }
  }
}

Deny with message:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Command not allowed by policy",
      "interrupt": true
    }
  }
}

PermissionDenied JSON Output

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

retry: true tells the model it may retry the denied tool call. Only command hooks can return this — prompt/agent hook output is discarded for this event.

PostToolUse JSON Output

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

• decision: "block" adds reason next to the tool result as feedback to Claude
• updatedToolOutput: replaces what Claude sees (tool has already run — files written, commands executed are not reversed). Value must match the tool's output shape exactly. For Bash: { stdout, stderr, interrupted, isImage }
• updatedMCPToolOutput: same as updatedToolOutput but for MCP tools only

UserPromptSubmit JSON Output

{
  "decision": "block",
  "reason": "Prompt contains sensitive data",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here",
    "sessionTitle": "My session title"
  }
}

• decision: "block" prevents prompt processing, erases prompt from context
• reason shown to user but not added to context
• sessionTitle: sets the session title automatically based on prompt content
• Plain text stdout also adds context (no JSON needed for simple use cases)

UserPromptExpansion JSON Output

{
  "decision": "block",
  "reason": "This slash command is not available",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptExpansion",
    "additionalContext": "Additional context for this expansion"
  }
}

Stop / SubagentStop JSON Output

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

• decision: "block" prevents stopping. reason is required and becomes Claude's next instruction
• SubagentStop does not support additionalContext. To inject context into the parent session after a subagent returns, use a PostToolUse hook on the Agent tool instead

TeammateIdle / TaskCreated / TaskCompleted JSON Output

Two control options:

• Exit code 2: feeds stderr back to the model as feedback; action is blocked
• JSON {"continue": false, "stopReason": "..."}: stops the teammate entirely

PostToolBatch JSON Output

{
  "decision": "block",
  "reason": "Reason to stop before next model call",
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "Context injected once before the next model call"
  }
}

ConfigChange JSON Output

{
  "decision": "block",
  "reason": "Configuration changes require admin approval"
}

policy_settings changes cannot be blocked — hooks fire but blocking decisions are ignored.

WorktreeCreate JSON Output

Hook replaces default git worktree behavior. Must return the absolute path to the created worktree directory:

• Command hooks: print path on stdout
• HTTP hooks: return { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }

Elicitation JSON Output

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": { "username": "alice" }
  }
}

action values: accept, decline, cancel

ElicitationResult JSON Output

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

PreCompact JSON Output

{
  "decision": "block",
  "reason": "Cannot compact — CI check in progress"
}

Setup / SessionStart JSON Output

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project context loaded successfully",
    "initialUserMessage": "Check the build status",
    "watchPaths": ["/path/to/watch"]
  }
}

• additionalContext: added to Claude's context at the start of the conversation
• initialUserMessage: SessionStart only — used as the first user message in non-interactive (-p) mode
• watchPaths: SessionStart only — array of absolute paths to watch for FileChanged events
• Multiple hooks' additionalContext values are concatenated

---

Events With No Decision Control

These events support side-effects only — logging, notifications, cleanup. No blocking or decision output is processed:

StopFailure, PostCompact, Notification, WorktreeRemove, SessionEnd, InstructionsLoaded, CwdChanged, FileChanged

---

Sources

• Hooks Reference (accessed 2026-05-21)
• Hooks Guide
• Settings Reference
• Plugin Components Reference