What Are Hooks

A hook is a mechanism that automatically runs logic at predetermined points in an AI agent’s execution — right before or after a tool call, at session start or end, and similar moments. Rather than leaving every rule to the AI’s judgment, a hook mechanically inserts predetermined rules into the flow.

Why Hooks Matter

An AI agent acts according to the instructions in its prompt, but instructions alone can’t guarantee a rule is “always” followed. A hook is logic that runs at a fixed point without waiting on the AI’s judgment. It’s a way to make the “verification,” “logging,” and “human approval points” covered in harness engineering into a concrete execution mechanism.

Common Points Where Hooks Fire

Scroll horizontally→

Timing	Example use
Session start	Automatically load the required context or rules
Right before a tool call	Judge whether the action is risky, and request approval if needed
Right after a tool call	Validate and format the result, then log it. On failure, decide whether to retry or notify a human
Right before the response	Inspect what the AI is about to output
Session end	Summarize the work and store it in long-term memory

This table scrolls horizontally. Keyboard users can focus the table and use the left and right arrow keys.

Each of these five timings is covered in detail in Hook Trigger Points.

A Concrete Example

Hook: pre-tool-use
Condition: the tool being called involves "file deletion" or "production deploy"
Action: pause execution and request human approval

Hook: post-tool-use
Condition: any tool call
Action: log the command that ran and its result

Hooks turn “the AI needs to remember to be careful every time” into “this rule always runs, as a mechanism.”

Principles to Follow

1. Limit Hooks to Important Points

Attaching a heavy hook to every operation slows things down and hurts the development experience. Focus hooks on important points — destructive operations, operations with wide-reaching visibility.

2. Automate Verification and Logging

Relying only on human eyes leads to the same mistakes recurring. Anything that can be checked mechanically — lint, tests, diff review — belongs in a hook.

3. Make the Stopping Points Explicit

Hooks are also a way to design where the AI should stop. Placing an approval hook before an irreversible action balances the AI’s autonomy against safety.

Pages in This Section

Scroll horizontally→

Page	Content
Hook Trigger Points	What each timing makes possible
Hook Use Cases	Quality gates, safety checks, recording, consistent baseline
Points to Note When Using Hooks	Infinite loops, latency, over-blocking

This table scrolls horizontally. Keyboard users can focus the table and use the left and right arrow keys.

Summary

• A hook is a trigger that automatically runs logic at predetermined points
• Hooks are commonly attached to tool calls and session start/end
• Hooks guarantee verification, logging, and approval as mechanisms rather than leaving them to the AI’s judgment
• Attaching hooks to too many points slows execution down — focus on the points that matter