Hook Event Payload Reference

Every hook receives a JSON payload on stdin. All events share common fields, plus event-specific data.

Common Fields (all events)

session_idCurrent session identifier cwdWorking directory of the Claude Code session hook_event_nameWhich event fired (e.g. "Stop", "PreToolUse")

Lifecycle Events lifecycle

`Stop`

Main agent finishes its turn

stop_hook_activeBoolean — true if this is a re-trigger (prevents infinite loops) last_assistant_messageThe agent's final response text

`SessionStart`

Session begins (startup, resume)

sourceHow session started (e.g. "new", "resume") modelModel in use (e.g. "claude-opus-4-6")

`SessionEnd`

Session terminates (exit, clear, logout)

reasonWhy the session ended (e.g. "user_exit", "clear")

`PreCompact`

Before context window compaction

trigger"manual" or "auto" — how compaction was initiated custom_instructionsAny custom compaction instructions provided

`Setup`

Initial setup or maintenance tasks

trigger"init" or "maintenance" — how setup was initiated

Tool Events tool

`PreToolUse`

Before any tool executes

tool_nameName of the tool about to execute (e.g. "Bash", "Edit") tool_inputThe input/arguments being passed to the tool

`PostToolUse`

After tool executes successfully

tool_nameName of the tool that executed tool_responseThe tool's output/response

`PostToolUseFailure`

After tool execution fails

tool_nameName of the tool that failed errorError message from the failure is_interruptBoolean — whether user interrupted the tool

`PermissionRequest`

Tool requests user permission before executing

tool_nameTool requesting permission tool_inputWhat the tool wants to do permission_suggestionsOptional suggested permission responses

Agent Events agent

`SubagentStart`

Subagent is spawned

agent_idUnique identifier for the subagent agent_typeType of subagent (e.g. "Explore", "Agent")

`SubagentStop`

Subagent finishes delegated task

agent_idUnique identifier for the subagent agent_typeType of subagent stop_hook_activeBoolean — re-trigger guard last_assistant_messageSubagent's final response agent_transcript_pathPath to full subagent conversation log

`TeammateIdle`

Teammate agent becomes idle

teammate_nameName of the teammate that went idle

`TaskCompleted`

Background task is marked as completed

task_idIdentifier for the completed task task_subjectDescription/subject of the task

System Events system

`UserPromptSubmit`

User submits a prompt

promptThe user's submitted prompt text

`Notification`

System notification displayed

messageNotification body text titleNotification title notification_typeType classification of the notification

`InstructionsLoaded`

Context files (CLAUDE.md, settings) have been loaded

instructionsThe loaded instructions content

`ConfigChange`

Configuration has been updated

config_keyWhich configuration value changed

`WorktreeCreate`

A git worktree has been created

worktree_pathPath to the new worktree

`WorktreeRemove`

A git worktree has been removed

worktree_pathPath of the removed worktree

Official documentation: Hooks Reference | Payload fields sourced from Claude Code v2.1.71 binary and official docs