--- slug: hook type: pattern summary: "Attach automation to lifecycle points in an agentic workflow so checks, formatting, and bookkeeping happen without anyone remembering to do them." created: 2026-04-04 updated: 2026-05-22 related: approval-policy: relation: uses note: "Hooks can enforce approval requirements automatically." harness-agentic: relation: depends-on note: "The harness provides the lifecycle points where hooks attach." permission-classifier: relation: contrasts-with note: "A hook is a deterministic rule that fires on a specific tool call; the classifier is a probabilistic judgment over each action's content." progress-log: relation: enables note: "Hooks can automate log updates." ralph-wiggum-loop: relation: contrasts-with note: "When a hook fails opaquely, the agent may loop instead of recovering." verification-loop: relation: enables note: "Hooks automate parts of the verification process." --- # Hook > **Pattern** > > A named solution to a recurring problem. *Attach automation to lifecycle points in your agentic workflow so that checks, formatting, and bookkeeping happen without anyone remembering to do them.* ## Understand This First - [Harness (Agentic)](harness-agentic.md) — the harness provides the lifecycle points where hooks attach. ## Context At the **agentic** level, a hook is automation that fires at a specific lifecycle point in an agentic workflow. Hooks let you attach behavior to events (before a file is saved, after a commit is created, when a conversation starts, before a tool is invoked) without modifying the core logic of the [agent](agent.md) or [harness](harness-agentic.md). The idea is old. Git hooks, React lifecycle hooks, CI/CD webhooks all work this way: inject custom behavior at defined points without coupling it to the main process. Agentic harnesses adopt the same mechanism. ## Problem How do you enforce conventions, run checks, or trigger side effects at specific points in an agentic workflow without manually intervening every time? Some tasks should happen automatically: formatting code before a commit, running linters after a file is saved, updating a [progress log](progress-log.md) at the end of a session, or notifying a team channel when an agent completes a major task. Without hooks, these tasks rely on human discipline (remembering to do them) or on the agent's instructions (hoping it does them). Both are unreliable. ## Forces - **Consistency** requires that some actions happen every time, without exception. - **Human attention** is limited. Remembering to run a formatter or update a log after every change is error-prone. - **Agent instructions** are soft constraints. The model may skip steps, especially in long sessions. - **Workflow flexibility**: different projects need different automation at different lifecycle points. ## Solution Configure hooks at the appropriate lifecycle points in your agentic harness. Common hook points include: **Pre-commit hooks** run before a commit is finalized. They can enforce code formatting, run linters, or check for secrets in the diff. If the hook fails, the commit is blocked. **Post-save hooks** run after a file is modified. They can trigger type checking, auto-formatting, or incremental test runs. **Session hooks** run when a conversation starts or ends. A start hook might load project context or check the git status. An end hook might update a [progress log](progress-log.md) or summarize what was accomplished. **Tool hooks** run before or after a specific [tool](tool.md) invocation. A pre-tool hook might validate parameters or check [approval policies](approval-policy.md). A post-tool hook might log the result. Modern agentic harnesses also expose several hook families. Command, HTTP, and MCP tool hooks are best for deterministic work: policy checks, logging, formatting, and calls to shared services. Prompt hooks ask a small model to make a quick judgment from the hook input. Agent hooks spawn a short verifier when the decision needs file reads, searches, or commands. Pay attention to each event's control surface. A `PreToolUse` hook can deny or reshape a tool call, `UserPromptSubmit` and `SessionStart` can inject context, and `Stop` or `SubagentStop` can block completion. Other events, such as notifications or session-end cleanup, are side-effect points only. Treat them as observability, not authority. Hooks should be fast, focused, and non-interactive. A hook that takes thirty seconds or asks a human for input isn't a hook anymore. If the check needs judgment, don't hide it in hook configuration; put it in a [verification loop](verification-loop.md). > **⚠️ Warning** > > Don't let hook-triggered agents recurse. A `UserPromptSubmit` hook that spawns a subagent should check whether it is already running inside a hook or subagent session before launching more work. > **💡 Tip** > > Start with a small set of high-value hooks: a pre-commit linter and a post-session progress log are a good foundation. Add more hooks only when you identify a recurring manual step that should be automated. ## How It Plays Out A team configures a pre-commit hook that runs their linter and type checker. An agent completes a feature, attempts to commit, and the hook catches a type error the agent introduced in its last edit. The agent sees the hook failure, fixes the type error, and commits successfully. The hook caught an error that the agent missed and the human hadn't yet reviewed. A developer configures a session-start hook that automatically loads the latest git log and test results into the agent's context. Every conversation begins with the agent knowing what was last changed and whether the tests are passing, without the developer remembering to provide this information. > **💡 Example Prompt** > > "Set up a pre-commit hook that runs the linter and type checker. If either fails, block the commit and show me the errors." ## Consequences The main benefit is consistency without vigilance. A well-configured hook catches errors early and handles bookkeeping that neither the human nor the agent would reliably remember. The cognitive load drops because routine checks stop being tasks you track and become infrastructure you trust. The cost is real: configuration, maintenance, and debugging when hooks break. A flaky hook that intermittently blocks commits erodes more trust than it builds. Confusing error messages from a failed hook can send an agent into a [Ralph Wiggum Loop](ralph-wiggum-loop.md), retrying the same broken step without understanding why. Keep hooks fast, reliable, and few. Each one adds friction that compounds. ## Sources The hook/callback pattern originates in event-driven programming and the observer pattern cataloged by the Gang of Four in *[Design Patterns](https://openlibrary.org/works/OL2019764W/Design_Patterns)* (1994). [Git hooks](https://git-scm.com/docs/githooks) brought the concept into version control workflows; Junio Hamano and the Git community formalized the pre-commit/post-commit lifecycle that most developers encounter first. [React Hooks](https://react.dev/reference/react/hooks) popularized "lifecycle hooks" in frontend development, extending the idea from infrastructure events to component state transitions. In the agentic context, [Claude Code's hook reference](https://code.claude.com/docs/en/hooks) applies the same mechanism to prompt submission, tool use, permissions, subagent start and stop, compaction, notifications, setup, config changes, worktree lifecycle, and session end. The [Claude Code hooks guide](https://code.claude.com/docs/en/hooks-guide) distinguishes command, HTTP, prompt, and agent hooks, and the [Agent SDK hooks documentation](https://code.claude.com/docs/en/agent-sdk/hooks) frames hooks as runtime interception points that can allow, block, modify input, or inject context. --- - [Next: Instruction File](instruction-file.md) - [Previous: Skill](skill.md)