dabit3/agent-hooks-in-depth

This repository is an in-depth guide and working demo for "agent hooks", a way to add predictable, rule-based control to AI agent workflows. When you use an AI coding agent (a tool that autonomously writes and edits code), it normally relies on the AI model to remember and follow instructions. Hooks let you move specific rules out of the model's memory and into code that runs automatically at defined moments in the agent's session. The guide explains six lifecycle points where hooks can attach: when a session starts (to load project context), when a user submits a prompt (to add extra information or block bad requests), before a tool runs (to block or modify an action), after a tool runs (to validate the result), when the agent tries to stop (to check if it should be allowed to finish), and when the session ends (to write logs or clean up). Each lifecycle point receives event data and can return decisions, context, or side effects. The accompanying demo uses a small checkout-calculator application as a test subject. The hooks around it enforce realistic workflow rules: blocking edits to protected or generated files, preventing dangerous shell commands, running tests automatically after code changes, and writing an audit log at session end. This demonstrates the core idea, use prompts for open-ended guidance, use hooks for rules that must run every single time regardless of what the model decides. The code is written in Python and is designed to work with AI agent tools that support hooks such as Claude Code, Codex, and Cursor. The full README is longer than what was provided.