Hook Events

Claude Code has 33 hook events. Each event fires at one point in a session. Each event gets its own input fields and accepts its own output fields. This page lists them in groups: tool, tool result, session, prompt and turn, agent and task, and other events. The fields that every event shares are on Input and Output.

Add the event key to the hooks map to enable an event. Remove it to disable the event.

Example

A SessionStart hook that adds your open tickets as context.

.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [{ "type": "command", "command": ".claude/hooks/tickets.sh" }]
      }
    ]
  }
}

.claude/hooks/tickets.sh

#!/bin/bash
# Plain stdout on SessionStart becomes context for Claude.
echo "Open tickets: $(gh issue list --limit 5 --json title -q '.[].title' | paste -sd ';' -)"

All Events

Event	Group	Fires when	Matcher	Can block
PreToolUse	Tool	Before a tool runs.	Tool name	✅
PermissionRequest	Tool	A permission prompt would show.	Tool name	❌ (use a decision)
PermissionDenied	Tool	Auto mode denies a call.	Tool name	❌
PostToolUse	Tool result	A tool call succeeds.	Tool name	❌
PostToolUseFailure	Tool result	A tool call fails.	Tool name	❌
PostToolBatch	Tool result	All tool calls of a batch finish.	None	✅
SessionStart	Session	A session starts or resumes.	Start source	❌
Setup	Session	--init-only, or --init or --maintenance with -p.	CLI flag	❌
SessionEnd	Session	A session ends.	End reason	❌
InstructionsLoaded	Session	A CLAUDE.md or rules file loads.	Load reason	❌
ConfigChange	Session	A settings or skill file changes.	Config source	✅
CwdChanged	Session	A shell command changes the directory.	None	❌
FileChanged	Session	A watched file changes on disk.	File names	❌
DirectoryAdded	Session	You add a directory with /add-dir.	Add source	❌
UserPromptSubmit	Prompt	You submit a prompt.	None	✅
UserPromptExpansion	Prompt	A typed command expands to a prompt.	Command name	✅
MessageDisplay	Prompt	Assistant text streams to the screen.	None	❌
Notification	Prompt	Claude Code sends a notification.	Notification type	❌
Stop	Prompt	The main agent finishes.	None	✅ (keeps working)
StopFailure	Prompt	The turn ends on an API error.	Error type	❌
SubagentStart	Agent	A subagent starts or resumes.	Agent type	❌
SubagentStop	Agent	A subagent finishes.	Agent type	✅ (keeps working)
TaskCreated	Agent	TaskCreate makes a task.	None	✅
TaskCompleted	Agent	A task changes to done.	None	✅
TeammateIdle	Agent	A teammate is about to go idle.	None	✅ (keeps working)
PreCompact	Other	Before a compaction.	Trigger	✅
PostCompact	Other	After a compaction.	Trigger	❌
PreModelSwitch	Other	Before a requested model switch.	Target model	✅
PostModelSwitch	Other	After the model changes.	Target model	❌
Elicitation	Other	An MCP server asks you for input.	Server name	✅ (declines)
ElicitationResult	Other	You answered an MCP question.	Server name	✅
WorktreeCreate	Other	Claude Code needs a worktree.	None	✅ (fails)
WorktreeRemove	Other	Claude Code removes a hook-made worktree.	None	✅ (fails)

Event Pages

Page	Events
Tool Hook Events	Tool events, tool result events, and the PostToolUse tool_response shapes.
Session, Prompt, and Turn Hook Events	Session events, and prompt and turn events.
Agent, Task, and Other Hook Events	Agent and task events, compaction, model switch, elicitation, and worktree events.

Related Pages

• Hooks: the overview.
• Configuration: matchers and timeouts.
• Input and Output: common fields, decisions, and exit codes.
• Subagent Runtime: subagents and teams.

Source: Hooks Reference, the HookInput types in the program type file, and the hook output schema in the program. Probed in -p: a Workflow call has tool_input {script}, and its PostToolUse tool_response has status (async_launched), taskId, taskType (local_workflow), workflowName, runId, summary, and transcriptDir. A Skill call has tool_input {skill} and tool_response {success, commandName}. An MCP tool's tool_response is the list of content blocks that the server returned, for example [{"type":"text","text":"pong"}]. Built-in tool outputs differ per tool (see PostToolUse tool_response Shapes). We did not probe every built-in tool, and WebFetch, ScheduleWakeup, and NotebookEdit calls did not reach PostToolUse in our run.