hooks-guidelisted

# Hooks Guide — Agent Lifecycle Interception A hook is a function or script that fires at a specific point in an agent's lifecycle — before a tool call, after a tool call, on session start, on session end, or on compaction. Hooks enable governance enforcement, audit logging, credential scanning, and pre-flight validation without modifying the agent runtime's source code. ## Layer 1: Concept Core ### What hooks are Hooks are interception points in the agent's execution loop. Instead of modifying the agent runtime, you register scripts or callbacks that the runtime invokes at defined moments. The hook receives the pending action as input and returns a decision: allow, block, or modify. ### Key lifecycle events | Event | Fires when | Use cases | |---|---|---| | `pre_tool_use` | Before any tool call is executed | Governance enforcement, file-write gates, credential scanning, scope limiting | | `post_tool_use` | After a tool call completes | Audit logging, result validation, auto-commit, metrics collection | | `on_session_start` | When a new agent session begins | Bootstrap checks, environment validation, injection of standing instructions | | `on_session_end` | Before the session is finalized | Wrapup triggers, session summaries, cleanup | | `on_compaction` | When context is being compressed | Save critical state before compression, checkpoint summaries | | `on_error` | When the agent encounters an unrecoverable error | Alerting, graceful degradation, fallback dispatch | N