Expand description
Hook system for intercepting agent lifecycle events.
Hooks allow SDK consumers to observe and modify tool executions by registering callbacks for specific lifecycle events (e.g., pre/post tool use). The hook system is optional — sessions without hooks behave normally.
§Architecture
Hooks are registered on ClientConfig as a list of
HookMatcher entries. Each matcher targets a specific HookEvent and
optionally filters by tool name. When a matching event occurs, the
HookCallback is invoked with the event details.
§Timeout Enforcement
Each hook callback is subject to a timeout. The effective timeout is
HookMatcher::timeout if set, otherwise ClientConfig::default_hook_timeout
(default: 30s). If a callback exceeds its timeout, the SDK logs a warning
and defaults to HookOutput::allow() (fail-open). This ensures a
misbehaving hook never permanently blocks a session.
§Internal Protocol
When hooks are registered, the SDK exchanges structured JSON messages with
the CLI via the control protocol. HookRequest and HookResponse are
the internal wire types (not exposed publicly).
Structs§
- Hook
Context - Additional context provided to hook callbacks.
- Hook
Input - Input data provided to a hook callback.
- Hook
Matcher - A hook registration that pairs a lifecycle event with a callback.
- Hook
Output - The output returned by a hook callback.
Enums§
- Hook
Decision - The decision a hook can make about the intercepted event.
- Hook
Event - Lifecycle events that hooks can intercept.
Type Aliases§
- Hook
Callback - The callback function invoked when a hook matches.