Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Hook

Pattern

A reusable solution you can apply to your work.

Understand This First

  • Harness (Agentic) – 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 or harness.

Hooks are a well-established concept in software (Git hooks, React lifecycle hooks, CI/CD webhooks). In agentic coding, they serve the same purpose: injecting custom behavior at defined points in the workflow without coupling that behavior to the main process.

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 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 or summarize what was accomplished.

Tool hooks run before or after a specific tool invocation. A pre-tool hook might validate parameters or check approval policies. A post-tool hook might log the result.

The key principle is that hooks should be fast, focused, and non-interactive. A hook that takes thirty seconds or requires human input defeats the purpose. If the check is complex enough to require judgment, it belongs in the verification loop, not in a hook.

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

Hooks enforce consistency by removing reliance on human memory or agent compliance. They catch errors early, maintain project standards, and automate routine bookkeeping. They work silently in the background, reducing the cognitive load on both the human and the agent.

The cost is configuration and maintenance. Hooks can fail, slow down the workflow, or produce confusing error messages. A flaky hook that intermittently blocks commits is worse than no hook at all. Keep hooks fast, reliable, and well-documented. Resist the temptation to hook everything; each hook adds a small amount of friction that accumulates.

  • Depends on: Harness (Agentic) — the harness provides the lifecycle points where hooks attach.
  • Enables: Verification Loop — hooks automate parts of the verification process.
  • Uses: Approval Policy — hooks can enforce approval requirements automatically.
  • Enables: Progress Log — hooks can automate log updates.