HOOKS.md

Hooks System

The hooks system enables extensible agent functionality through strongly-typed event callbacks.

Terminology

• Paired events: Events that denote the beginning and end of an operation
• Hook callback: A function that receives a strongly-typed event argument
• Hook provider: An object implementing HookProvider that registers callbacks via register_hooks()

Naming Conventions

• All hook events have a suffix of Event
• Paired events follow Before{Action}Event and After{Action}Event
• Action words come after the lifecycle indicator (e.g., BeforeToolCallEvent not BeforeToolEvent)

Paired Events

• For every Before event there is a corresponding After event, even if an exception occurs
• After events invoke callbacks in reverse registration order (for proper cleanup)

Writable Properties

Some events have writable properties that modify agent behavior. Values are re-read after callbacks complete. For example, BeforeToolCallEvent.selected_tool is writable - after invoking the callback, the modified selected_tool takes effect for the tool call.