--- title: "08 — Hooks — Deterministic Triggers at the Loop's Lifecycle Points" uid: hooks tags: ["lifecycle", "roadmap:claude-code", "automation", "ci", "hooks", "claude-code"] excerpt: "A hook is a deterministic script fired at a lifecycle event that can approve, block, or enrich the next step — a hard guarantee where CLAUDE.md gives soft instructions." date: 2026-08-13T03:28:21+0000 source: https://www.aveshina.my.id/en/blog/hooks --- "Git hooks but for AI" was the nearest hook to hand, and it captured the deterministic part but not the integration. The cleaner frame: **a hook is a deterministic script or check fired at a specific lifecycle event of the agent, communicating via JSON to approve, block, or enrich the next step.** [1] Where CLAUDE.md gives soft instructions the model might ignore, hooks give hard guarantees — something that runs _every single time_ a certain event occurs, regardless of what the model "decides." The framing that clicked is the contrast with skills and subagents. Skills add knowledge the model loads on demand; subagents isolate work into bubbles. Hooks are different: they sit _outside_ the model entirely, on the lifecycle events of the loop itself. The model doesn't choose to call a hook — the harness fires it when the event happens, and the hook's output feeds back into what the model does next [1]. That determinism is the whole point, and it's why hooks are the right tool for enforcement (lint after every edit, block risky commands) rather than suggestion. ## The lifecycle events The roadmap names the lifecycle moments where a hook can fire, and reading them as points on the loop made them click [1][2]: - **SessionStart** — fires at the very beginning, before the first prompt. Bootstraps the environment and injects high-priority context. - **UserPromptSubmit** — fires the moment I press Enter, before the text reaches the model. Lets me programmatically rewrite, validate, or enhance the prompt on the fly. - **PreToolUse** — fires after the model decides to use a tool but before it runs. The validation gate: security checks, policy enforcement, input sanitization. - **PostToolUse** — fires immediately after a tool completes. For cleanup and quality control — format the file after an edit, run a check after a command. - **Stop** — fires once at the very end of a turn, when the model is about to return control to me. A final check or notification. - **SessionEnd** — fires on exit. Cleanup, archiving, final reporting. Two ideas make this powerful. First, **events have matchers** — regex filters that decide which specific actions within an event fire the hook (e.g. a PreToolUse hook that only triggers on Bash, not on Read) [3]. Second, the placement lets me intercept at exactly the right granularity: prompt-level (UserPromptSubmit), tool-level (Pre/PostToolUse), or turn-level (Stop). ```figure ``` ## The three hook types For each event I can configure one of three handler types, and the roadmap is explicit about the distinction [4]: - **Command hooks (type: "command")** — deterministic shell scripts. They run a standard command (like npm run lint) and use exit codes to approve or block. Exit 0 approves; a non-zero code blocks with the error message shown to the model. This is the "I want a hard guarantee" option. - **Prompt hooks (type: "prompt")** — a lightweight Claude model makes a single-turn judgement call ("is this commit message descriptive?") and returns a JSON yes/no. Use when the check itself needs interpretation, not just a fixed command. - **Agent hooks (type: "agent")** — the most sophisticated: spawns a multi-turn subagent with tool access (Read, Grep) to conduct deep, autonomous verification before deciding whether the main agent should proceed. The rule of thumb I use: start with a command hook (deterministic, cheap, no model involved). Reach for a prompt hook when the check is a judgement ("is this good?"). Reach for an agent hook only when verification needs real investigation across files. ## Inputs, outputs, and the JSON contract Hooks communicate through a standardized JSON interface, and getting this straight was what made them usable [5]: - **Inputs arrive via stdin** — a context object with session metadata and event-specific data, such as the tool name and its arguments (the exact code being written or command being run). - **Outputs return via stdout** — a JSON object that influences the agent's next move. The shape of the output decides whether the action proceeds, gets blocked with a message, or gets enriched with extra context. For command hooks specifically, the exit code is the blunt instrument: 0 to allow, non-zero (commonly 2) to block. This is what makes a PreToolUse command hook a real security gate — it can refuse a dangerous command before it ever runs, deterministically, every time. ## The slash commands that manage them - **/hooks** — opens the interactive management menu for configuring automated workflows at lifecycle points [6]. - **/config** — the central customization menu (global and project settings, defaults, permissions) [7]. - **/permissions** — the security interface for granting permanent trust to specific tools or commands, reducing interruptions [8]. - **/model** — switches the model mid-session (relevant because prompt/agent hooks use a model) [9]. - **/agents** — manages subagents (relevant because agent hooks spawn one) [10]. - **/mcp** — the MCP integration hub (covered in its own post) [11]. ## How I use this The habit these notes left me with is a simple rule: _if a standard must hold every single time, it's a hook; if it's a preference, it's CLAUDE.md._ So PostToolUse command hook to run the formatter after every edit (the codebase is always formatted), PreToolUse command hook to block commands matching destructive patterns (the dangerous action never runs), Stop hook to notify me when a long turn ends. Soft preferences ("prefer named exports") stay in the memory file where the model can weigh them. Hard guarantees become hooks because the model cannot choose to skip them. ## References [1] Anthropic, "Automate workflows with hooks," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/hooks-guide](https://code.claude.com/docs/en/hooks-guide) [2] Anthropic, "Hooks reference," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks) [3] Anthropic, "Event Matchers," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/hooks#matcher-patterns](https://code.claude.com/docs/en/hooks#matcher-patterns) [4] Anthropic, "Hook Types," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks) [5] Anthropic, "Hook Inputs & Outputs," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/hooks#hook-input-and-output](https://code.claude.com/docs/en/hooks#hook-input-and-output) [6] Anthropic, "The /hooks menu," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/hooks#the-hooks-menu](https://code.claude.com/docs/en/hooks#the-hooks-menu) [7] Anthropic, "Claude Code settings," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/settings](https://code.claude.com/docs/en/settings) [8] Anthropic, "Manage permissions," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) [9] Anthropic, "Model configuration — /model," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/model-config#setting-your-model](https://code.claude.com/docs/en/model-config#setting-your-model) [10] Anthropic, "Create custom subagents — /agents," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/sub-agents#use-the-agents-command](https://code.claude.com/docs/en/sub-agents#use-the-agents-command) [11] Anthropic, "Connect Claude Code to tools via MCP — /mcp," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp) ```quiz Q: What is the core difference between a CLAUDE.md rule and a hook? - They are the same; both are soft instructions - CLAUDE.md is a soft instruction the model may ignore; a hook is a deterministic script that fires every time its event occurs correct: 1 explain: CLAUDE.md gives preferences the model weighs. Hooks fire on lifecycle events regardless of the model's decision — they sit outside the model, which is why they're the right tool for hard guarantees. Q: Which lifecycle event fires AFTER the model decides to use a tool but BEFORE the tool runs? - PostToolUse - PreToolUse correct: 1 explain: PreToolUse is the validation gate — it can block a risky action via exit code before it ever executes. PostToolUse fires after the tool completes. Q: You need a check that decides whether a commit message is "descriptive enough." Which hook type fits? - Command hook (shell script with exit codes) - Prompt hook (a lightweight model makes a single-turn yes/no judgement) correct: 1 explain: "Descriptive enough" is a judgement, not a fixed command. A prompt hook uses a lightweight model for a single-turn evaluation and returns a JSON decision. Command hooks suit deterministic checks like running a linter. Q: How do hooks receive and return data? - Via environment variables only - Inputs arrive on stdin as JSON; outputs return via stdout as JSON (command hooks also use exit codes to approve/block) correct: 1 explain: The JSON contract is standardized: a context object on stdin, a decision object on stdout. For command hooks, exit 0 allows and non-zero (often 2) blocks with a message. Q: What do event matchers do? - They replace the need for a hook script - They are regex filters that decide which specific actions within an event fire the hook (e.g. only Bash, not Read) correct: 1 explain: Matchers scope a hook to the relevant actions. A PreToolUse hook with a Bash matcher fires only on shell commands, leaving Read/Edit untouched. ```