Summary
Claude Code hooks are user-defined shell commands that run automatically at specific lifecycle points in a Claude Code session. Their central purpose is determinism: certain actions always happen, rather than relying on the LLM to choose to run them. Hooks cover session lifecycle events, prompt submission, notifications, and tool use before/after points, and can also be implemented as prompt-based, agent-based, asynchronous, or MCP-tool hooks.
Key Points
- Hooks execute shell commands deterministically at defined lifecycle events.
- Core events include
SessionStart,SessionEnd,Stop,UserPromptSubmit,Notification,PreToolUse, andPostToolUse. - They are useful for enforcing reproducible policies, logging, validation, and environment setup.
- Because hooks run unconditionally, the trust boundary around them is stronger than around prompt-level instructions: an untrusted hook executes without needing to persuade a model.
Concepts
- Lifecycle event — a defined point in Claude Code's operation where a hook may fire.
- Determinism — hooks make behaviors reliable and repeatable, independent of model judgment.
- PreToolUse / PostToolUse — hooks that run before or after a tool call, enabling validation, logging, or policy enforcement around tool execution.
- SessionStart / SessionEnd / Stop — session-level hooks for when a session begins, ends, or the agent stops.
- UserPromptSubmit — a hook triggered when the user submits a prompt.
- Notification — a hook triggered on notifications, typically used for asynchronous handling.
- Async hooks — non-blocking hooks that run without interrupting the main interaction.
- MCP-tool hooks — hooks that integrate with Model Context Protocol tool execution.
- Trust boundary — the security consideration raised by deterministic execution of external shell code.