ktg-plugin-marketplace/plugins/config-audit/knowledge/hook-events-reference.md

Hook Events Reference

All 26 hook events as of April 2026. Source: code.claude.com/docs/en/hooks.md Verified 2026-04-19 against research/03-claude-code-changes-config-surfaces.md — no new hook events introduced in v2.1.83–v2.1.111. Sandbox + managed-only flags (2026-04) operate at the settings layer, not as new hook events.

---

Event Table

Event	Trigger	Blocking?	Matcher Support	Common Use Cases
SessionStart	Session begins or resumes	No	startup, resume, clear, compact	Inject git branch/env into context; show session state; load external context
InstructionsLoaded	CLAUDE.md / .claude/rules files are loaded	No	session_start, nested_traversal, path_glob_match, include, compact	Debug which instruction files loaded; log instruction sources; validate rule sets
UserPromptSubmit	User submits a prompt	Yes	No matcher	Validate prompt length; inject context; block disallowed prompt patterns; add mandatory context
PreToolUse	Before any tool executes	Yes	Tool name (e.g., Bash, Write, mcp__.*)	Security validation; confirm destructive ops; log tool calls; rate limiting
PermissionRequest	Permission dialog appears	Yes	Tool name	Auto-approve known-safe patterns; add approval context; integrate with approval workflows
PermissionDenied	Auto mode denies a tool call	No (info only)	Tool name	Log denied operations; alert on unexpected denials; track permission patterns
PostToolUse	Tool completes successfully	No	Tool name	Auto-format after Write/Edit; run linting; update docs; log completions
PostToolUseFailure	Tool ends in error	No	Tool name	Log failures; send alerts; trigger retry logic; update error tracking
SubagentStart	Subagent is spawned	No	Agent type (name)	Log agent invocations; inject agent-specific context; record spawn times
SubagentStop	Subagent finishes	Yes	Agent type (name)	Quality gates (exit 2 to reject); validate agent output; run post-agent checks
TaskCreated	A task is created in the task list	Yes	No matcher	Validate task format; enforce naming conventions; block disallowed task types
TaskCompleted	A task is marked complete	Yes	No matcher	Verify completion criteria; run acceptance checks; require sign-off
Stop	Claude finishes a response turn	Yes	No matcher	Session summaries; commit prompts; send desktop notifications; log turn metadata
StopFailure	Turn ends in an API error	No	Error type	Alert on API errors; retry logic; log error context
TeammateIdle	An agent team member has no tasks	Yes	No matcher	Assign next task (exit 2 to keep working); log team status; rebalance work
Notification	A notification is sent (permission prompt, idle, auth)	No	permission_prompt, idle_prompt, auth_success, elicitation_dialog	Desktop notifications; Slack/webhook alerts; mobile push; audio cues
ConfigChange	A config file changes on disk	Yes	user_settings, project_settings, local_settings, policy_settings, skills	Validate config changes; block invalid edits; reload dependent processes
CwdChanged	Working directory changes	No	No matcher	Inject new directory context; update env vars via $CLAUDE_ENV_FILE; log navigation
FileChanged	A watched file changes	No	Filename pattern	Auto-reload when config changes; trigger builds on source change; sync state
WorktreeCreate	A git worktree is being created	Yes (path return)	No matcher	Custom worktree path via stdout; non-git VCS support; worktree naming conventions
WorktreeRemove	A git worktree is removed	No	No matcher	Cleanup resources; log worktree lifecycle; update team state
PreCompact	Before context compaction	No	manual, auto	Save current state; checkpoint important context; log pre-compact state
PostCompact	After context compaction	No	manual, auto	Reinject critical context; validate compaction; log post-compact state
Elicitation	An MCP server requests user input	Yes	MCP server name	Control which servers can request input; log elicitations; pre-fill responses
ElicitationResult	User responds to MCP elicitation	Yes	MCP server name	Validate responses; log user input; transform before sending to MCP
SessionEnd	Session terminates	No	clear, resume, logout, prompt_input_exit, other	Final session summary; save state; cleanup temp files; send end-of-session report

---

Hook Handler Types

Type	Description	Use When
command	Shell command (bash/powershell)	Fast scripts, file checks, security validation
http	HTTP POST to endpoint	Remote logging, webhooks, approval systems
prompt	LLM evaluation (yes/no decision)	Semantic validation that needs language understanding
agent	Full subagent with tools	Complex validation requiring file reads or multi-step logic

---

Handler Configuration Fields

Field	Type	Description
type	string	command, http, prompt, agent
command	string	Shell command (type: command only)
url	string	HTTP endpoint (type: http only)
prompt	string	LLM prompt (type: prompt only)
if	string	Conditional expression — only fires when true (e.g., Bash(rm *))
timeout	number	Milliseconds before hook is killed (default: varies)
statusMessage	string	Message shown in UI while hook runs
async	bool	true = fire and forget, don't wait for result
shell	string	"bash" or "powershell"

---

Exit Code Semantics

Exit Code	Blocking Event	Non-Blocking Event
0	Proceed; JSON on stdout is parsed	Success; JSON on stdout parsed
2	Block — stderr shown to Claude as error	Non-blocking; treated as informational
other	Non-blocking; stderr in verbose log only	Non-blocking; stderr in verbose log only

---

Blocking Event Output Fields

PreToolUse (exit 0):

• permissionDecision: "allow" / "deny" / "ask" / "defer"
• updatedInput: modified tool input
• additionalContext: string appended to Claude's context

PermissionRequest (exit 0):

• decision.behavior: "allow" / "deny"
• updatedInput: modified input
• updatedPermissions: modified permission set

WorktreeCreate (exit 0):

• stdout: path string OR hookSpecificOutput.worktreePath

SessionStart (exit 0):

• additionalContext: string injected into context
• Or: write env vars to $CLAUDE_ENV_FILE

---

Environment Variables Available in Hooks

Variable	Available In	Description
$CLAUDE_PROJECT_DIR	All hooks	Absolute path to project root
${CLAUDE_PLUGIN_ROOT}	Plugin hooks	Plugin installation directory
${CLAUDE_PLUGIN_DATA}	Plugin hooks	Plugin persistent data directory
$CLAUDE_ENV_FILE	SessionStart, CwdChanged, FileChanged	Path to write env var exports
$CLAUDE_CODE_REMOTE	All hooks	"true" when running in web sessions

---

MCP Tool Matcher Patterns

Pattern	Matches
mcp__memory__.*	All tools from the memory server
mcp__.*__write.*	Any tool named write* from any server
mcp__filesystem__read_file	Specific tool on specific server
mcp__.*	All MCP tools from all servers