Struct Hooks 

pub struct Hooks { /* private fields */ }

Stores and executes registered hook callbacks.

Callbacks at the same HookPoint fire in the order they were registered.

Example

Fluent builder pattern (recommended):

use agy_bridge::hooks::{HookResult, Hooks, PreToolCallDecideContext, PreTurnContext};

let hooks = Hooks::new()
    .with_pre_turn("logger", |ctx: &PreTurnContext| {
        println!("Turn {} prompt: {}", ctx.turn_number, ctx.prompt);
    })
    .with_pre_tool_call_decide("gate", |ctx: &PreToolCallDecideContext| {
        if ctx.tool_name == "dangerous_tool" {
            HookResult::deny("blocked by policy")
        } else {
            HookResult::allow()
        }
    });

hooks.run_pre_turn(&PreTurnContext {
    prompt: "hi".into(),
    turn_number: 1,
});
let result = hooks.run_pre_tool_call_decide(&PreToolCallDecideContext {
    tool_name: "safe_tool".into(),
    tool_args: serde_json::Value::Null,
});
assert!(result.allow);

For conditional or loop-based registration, use the on_*(&mut self) methods:

let mut hooks = Hooks::new();
hooks.on_pre_turn("logger", |ctx| {
    println!("Turn {}", ctx.turn_number);
});

Implementations

impl Hooks

pub const fn new() -> Self

Create an empty hook runner.

pub fn register( &mut self, name: impl Into<String>, callback: HookCallback, ) -> &mut Self

Register a named callback.

The HookPoint is derived automatically from the callback variant. If a callback with the same name AND hook point already exists, it is replaced and a warning is logged. Returns &mut Self for chaining.

pub fn run_pre_turn(&self, ctx: &PreTurnContext)

Run all HookPoint::PreTurn callbacks in registration order.

pub fn run_post_turn(&self, ctx: &PostTurnContext)

Run all HookPoint::PostTurn callbacks in registration order.

pub fn run_pre_tool_call_decide( &self, ctx: &PreToolCallDecideContext, ) -> HookResult

Run all HookPoint::PreToolCallDecide callbacks in registration order.

If any callback returns HookResult with allow: false, execution short-circuits and that deny result is returned immediately. Otherwise returns HookResult::allow().

If a callback panics, the tool call is denied as a safe default.

pub fn run_post_tool_call(&self, ctx: &PostToolCallContext)

Run all HookPoint::PostToolCall callbacks in registration order.

pub fn run_on_tool_error(&self, ctx: &OnToolErrorContext)

Run all HookPoint::OnToolError callbacks in registration order.

pub fn run_on_session_start(&self, ctx: &OnSessionStartContext)

Run all HookPoint::OnSessionStart callbacks in registration order.

pub fn run_on_session_end(&self, ctx: &OnSessionEndContext)

Run all HookPoint::OnSessionEnd callbacks in registration order.

pub fn run_on_compaction(&self, ctx: &OnCompactionContext)

Run all HookPoint::OnCompaction callbacks in registration order.

pub fn run_on_interaction(&self, ctx: &OnInteractionContext) -> HookResult

Run all HookPoint::OnInteraction callbacks in registration order.

If a callback panics, the panic is logged and execution continues (the interaction is not blocked).

pub fn run_transform_tool_input(&self, ctx: &PreToolCallDecideContext) -> Value

Run all TransformToolInput callbacks in registration order, threading the (possibly modified) tool arguments through each transform.

Returns the final tool arguments after all transforms have been applied. If no transform returns Some, the original arguments are returned unchanged.

Panicking transforms are logged and skipped (original args kept).

pub fn on_pre_turn( &mut self, name: impl Into<String>, f: impl Fn(&PreTurnContext) + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::PreTurn callback.

Convenience wrapper matching the Python SDK’s @on_pre_turn decorator.

pub fn on_post_turn( &mut self, name: impl Into<String>, f: impl Fn(&PostTurnContext) + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::PostTurn callback.

Convenience wrapper matching the Python SDK’s @on_post_turn decorator.

pub fn on_pre_tool_call_decide( &mut self, name: impl Into<String>, f: impl Fn(&PreToolCallDecideContext) -> HookResult + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::PreToolCallDecide callback.

Convenience wrapper matching the Python SDK’s @on_pre_tool_call_decide decorator.

pub fn on_post_tool_call( &mut self, name: impl Into<String>, f: impl Fn(&PostToolCallContext) + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::PostToolCall callback.

Convenience wrapper matching the Python SDK’s @on_post_tool_call decorator.

pub fn on_tool_error( &mut self, name: impl Into<String>, f: impl Fn(&OnToolErrorContext) + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::OnToolError callback.

Convenience wrapper matching the Python SDK’s @on_tool_error decorator.

pub fn on_compaction( &mut self, name: impl Into<String>, f: impl Fn(&OnCompactionContext) + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::OnCompaction callback.

Convenience wrapper matching the Python SDK’s @on_compaction decorator.

pub fn on_interaction( &mut self, name: impl Into<String>, f: impl Fn(&OnInteractionContext) -> HookResult + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::OnInteraction callback.

Convenience wrapper matching the Python SDK’s @on_interaction decorator.

pub fn on_session_start( &mut self, name: impl Into<String>, f: impl Fn(&OnSessionStartContext) + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::OnSessionStart callback.

Convenience wrapper matching the Python SDK’s @on_session_start decorator.

pub fn on_session_end( &mut self, name: impl Into<String>, f: impl Fn(&OnSessionEndContext) + Send + Sync + 'static, ) -> &mut Self

Register a HookPoint::OnSessionEnd callback.

Convenience wrapper matching the Python SDK’s @on_session_end decorator.

pub fn on_transform_tool_input( &mut self, name: impl Into<String>, f: impl Fn(&PreToolCallDecideContext) -> Option<Value> + Send + Sync + 'static, ) -> &mut Self

Register a TransformToolInput callback.

The closure receives the pre-tool-call context and may return Some(new_args) to replace tool arguments, or None to leave them unchanged.

pub fn with_pre_turn( self, name: impl Into<String>, f: impl Fn(&PreTurnContext) + Send + Sync + 'static, ) -> Self

Register a HookPoint::PreTurn callback, returning self for chaining.

This is the owned-self variant of on_pre_turn.

pub fn with_post_turn( self, name: impl Into<String>, f: impl Fn(&PostTurnContext) + Send + Sync + 'static, ) -> Self

Register a HookPoint::PostTurn callback, returning self for chaining.

This is the owned-self variant of on_post_turn.

pub fn with_pre_tool_call_decide( self, name: impl Into<String>, f: impl Fn(&PreToolCallDecideContext) -> HookResult + Send + Sync + 'static, ) -> Self

Register a HookPoint::PreToolCallDecide callback, returning self for chaining.

This is the owned-self variant of on_pre_tool_call_decide.

pub fn with_post_tool_call( self, name: impl Into<String>, f: impl Fn(&PostToolCallContext) + Send + Sync + 'static, ) -> Self

Register a HookPoint::PostToolCall callback, returning self for chaining.

This is the owned-self variant of on_post_tool_call.

pub fn with_tool_error( self, name: impl Into<String>, f: impl Fn(&OnToolErrorContext) + Send + Sync + 'static, ) -> Self

Register a HookPoint::OnToolError callback, returning self for chaining.

This is the owned-self variant of on_tool_error.

pub fn with_compaction( self, name: impl Into<String>, f: impl Fn(&OnCompactionContext) + Send + Sync + 'static, ) -> Self

Register a HookPoint::OnCompaction callback, returning self for chaining.

This is the owned-self variant of on_compaction.

pub fn with_interaction( self, name: impl Into<String>, f: impl Fn(&OnInteractionContext) -> HookResult + Send + Sync + 'static, ) -> Self

Register a HookPoint::OnInteraction callback, returning self for chaining.

This is the owned-self variant of on_interaction.

pub fn with_session_start( self, name: impl Into<String>, f: impl Fn(&OnSessionStartContext) + Send + Sync + 'static, ) -> Self

Register a HookPoint::OnSessionStart callback, returning self for chaining.

This is the owned-self variant of on_session_start.

pub fn with_session_end( self, name: impl Into<String>, f: impl Fn(&OnSessionEndContext) + Send + Sync + 'static, ) -> Self

Register a HookPoint::OnSessionEnd callback, returning self for chaining.

This is the owned-self variant of on_session_end.

pub fn with_transform_tool_input( self, name: impl Into<String>, f: impl Fn(&PreToolCallDecideContext) -> Option<Value> + Send + Sync + 'static, ) -> Self

Register a TransformToolInput callback, returning self for chaining.

This is the owned-self variant of on_transform_tool_input.

pub fn entries(&self) -> Vec<HookEntry>

Extract a list of HookEntry objects corresponding to the registered callbacks.

This allows the AgentBuilder to automatically populate the agent’s configuration with the necessary entries to connect the Python SDK’s hook dispatcher back to the Rust runner.

Trait Implementations

impl Default for Hooks

fn default() -> Self

Returns the “default value” for a type.