Trait AgentHooks 

pub trait AgentHooks: Send + Sync {
    // Provided methods
    fn on_event<'a>(&'a self, _event: &'a AgentEvent) -> BoxFuture<'a, ()> { ... }
    fn transform_context(
        &self,
        messages: Vec<Message>,
    ) -> BoxFuture<'_, Vec<Message>> { ... }
    fn convert_to_llm(&self, messages: Vec<Message>) -> Vec<Message> { ... }
    fn auth<'a>(&'a self, _model: &'a Model) -> BoxFuture<'a, Auth> { ... }
    fn before_tool_call<'a>(
        &'a self,
        _call: BeforeToolCall<'a>,
    ) -> BoxFuture<'a, Option<Block>> { ... }
    fn after_tool_call<'a>(
        &'a self,
        _call: AfterToolCall<'a>,
    ) -> BoxFuture<'a, Option<ResultPatch>> { ... }
    fn finish_turn<'a>(
        &'a self,
        _message: &'a AssistantMessage,
        _tool_results: &'a [ToolResultMessage],
    ) -> BoxFuture<'a, TurnDecision> { ... }
    fn finish_message(&self, message: Message) -> BoxFuture<'_, Message> { ... }
    fn complete_tool_result(&self, _message: &mut ToolResultMessage) { ... }
    fn next_turn_messages(
        &self,
    ) -> BoxFuture<'_, Result<Option<Vec<Message>>, String>> { ... }
    fn current_tools(&self) -> BoxFuture<'_, Option<Vec<Arc<dyn Tool>>>> { ... }
    fn steering_messages(&self) -> BoxFuture<'_, Vec<Message>> { ... }
    fn follow_up_messages(&self) -> BoxFuture<'_, Vec<Message>> { ... }
}

Hooks into the agent loop. Every method has a no-op default.

The loop awaits each hook before it continues, so a hook sees a consistent transcript. Hooks never call back into the loop.

Provided Methods

fn on_event<'a>(&'a self, _event: &'a AgentEvent) -> BoxFuture<'a, ()>

Receives every loop event, in order.

fn transform_context( &self, messages: Vec<Message>, ) -> BoxFuture<'_, Vec<Message>>

Rewrites the transcript before the loop converts it for the provider.

fn convert_to_llm(&self, messages: Vec<Message>) -> Vec<Message>

Converts session messages to the four roles providers accept.

fn auth<'a>(&'a self, _model: &'a Model) -> BoxFuture<'a, Auth>

Credentials for a request to model, resolved fresh for each request.

fn before_tool_call<'a>( &'a self, _call: BeforeToolCall<'a>, ) -> BoxFuture<'a, Option<Block>>

May block a validated call.

fn after_tool_call<'a>( &'a self, _call: AfterToolCall<'a>, ) -> BoxFuture<'a, Option<ResultPatch>>

May patch a result.

fn finish_turn<'a>( &'a self, _message: &'a AssistantMessage, _tool_results: &'a [ToolResultMessage], ) -> BoxFuture<'a, TurnDecision>

A turn finished: the loop emitted its assistant message and tool results, and turn_end is next (pi’s finishTurn). The loop ignores the decision after a failed or aborted response.

fn finish_message(&self, message: Message) -> BoxFuture<'_, Message>

The message to record in place of message once it is complete, before the loop emits its message_end (pi’s message_end replacement). Must keep the message’s role.

fn complete_tool_result(&self, _message: &mut ToolResultMessage)

Completes a tool result message before it is emitted, for example with the calls the tool made.

fn next_turn_messages( &self, ) -> BoxFuture<'_, Result<Option<Vec<Message>>, String>>

The transcript the next turn continues from, read before each turn after the first (pi’s prepareNextTurn context). None keeps the loop’s own. An error ends the run with it, as pi’s agent ends a run whose hook throws.

fn current_tools(&self) -> BoxFuture<'_, Option<Vec<Arc<dyn Tool>>>>

The tools for the next request, read before each turn. None keeps the current ones.

fn steering_messages(&self) -> BoxFuture<'_, Vec<Message>>

Messages the user queued to steer the current run. Reading drains them.

fn follow_up_messages(&self) -> BoxFuture<'_, Vec<Message>>

Messages to send once the run would otherwise stop. Reading drains them.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors