Skip to content
Home › Claude Code Configuration & Workflows

Hook Types And Events

Claude Code Configuration & Workflows

Definition

Hooks are user-configured handlers that fire at defined lifecycle events in Claude Code, letting you observe, block, or modify actions deterministically instead of relying on model behaviour.

Key points

  • Handler type: command | http | mcp_tool | prompt | agent.
  • Config shape: hooks.<EVENT>[].{matcher, hooks:[{type, command, args, if, timeout, statusMessage, once}]}. once: true runs once per session then self-removes.
  • Common events (both TS callbacks and settings-file): PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PreCompact, PermissionRequest, Notification.
  • TS-only SDK callbacks: SessionStart/SessionEnd, PostToolBatch, MessageDisplay, Setup, TeammateIdle, TaskCompleted, ConfigChange, WorktreeCreate/Remove. In Python SessionStart/SessionEnd exist only as settings-file shell hooks.
  • Full settings-file event list also includes: UserPromptExpansion, PermissionDenied, TaskCreated, StopFailure, InstructionsLoaded, CwdChanged, FileChanged, PostCompact, Elicitation, ElicitationResult.
  • Matcher rules: */empty/omitted = all. Only letters/digits/_/-/space/,/| → exact match (alternatives split by | or ,). Any other char → unanchored JS regex (^mcp__ = all MCP; Edit.* = Edit + NotebookEdit). MCP tools match as mcp__<server>__<tool>; mcp__memory alone matches nothing → use mcp__memory__.*. Stop ignores matchers.
  • Hot-reload: hooks reload mid-session (unlike model/outputStyle).

Why it matters for the exam

  • D3 (20% of scored content) tests which event to attach to (e.g. PreToolUse to gate a call) and the matcher syntax, especially the mcp__<server>__<tool> pattern.
  • PreToolUse is the answer for deterministic guardrails — see PreToolUse hook enforcement.

Common gotchas

  • Python SDK lacks SessionStart/SessionEnd callbacks → use settings-file shell hooks instead.
  • A bare mcp__memory matcher matches nothing; you must write mcp__memory__.*.
  • Stop ignores the matcher field entirely.

See also

Sources

Referenced by