Trait AgentHook 

pub trait AgentHook: WasmCompatSend + WasmCompatSync {
    // Provided methods
    fn on_model_select(
        &self,
        _ctx: &HookContext,
        _event: ModelSelection<'_>,
    ) -> ModelSelectionAction { ... }
    fn on_completion_call(
        &self,
        _ctx: &HookContext,
        _event: CompletionCall<'_>,
    ) -> impl Future<Output = CompletionCallAction> + WasmCompatSend { ... }
    fn on_completion_response(
        &self,
        _ctx: &HookContext,
        _event: CompletionResponse<'_>,
    ) -> impl Future<Output = ObservationAction> + WasmCompatSend { ... }
    fn on_model_turn_finished(
        &self,
        _ctx: &HookContext,
        _event: ModelTurnFinished<'_>,
    ) -> impl Future<Output = ModelTurnAction> + WasmCompatSend { ... }
    fn on_invalid_tool_call(
        &self,
        _ctx: &HookContext,
        _event: &InvalidToolCallContext,
    ) -> impl Future<Output = Option<InvalidToolCallAction>> + WasmCompatSend { ... }
    fn on_tool_call(
        &self,
        _ctx: &HookContext,
        _event: ToolCall<'_>,
    ) -> impl Future<Output = ToolCallAction> + WasmCompatSend { ... }
    fn on_tool_result(
        &self,
        _ctx: &HookContext,
        _event: ToolResultEvent<'_>,
    ) -> impl Future<Output = ToolResultAction> + WasmCompatSend { ... }
    fn on_text_delta(
        &self,
        _ctx: &HookContext,
        _event: TextDelta<'_>,
    ) -> impl Future<Output = ObservationAction> + WasmCompatSend { ... }
    fn on_reasoning_delta(
        &self,
        _ctx: &HookContext,
        _event: ReasoningDelta<'_>,
    ) -> impl Future<Output = ObservationAction> + WasmCompatSend { ... }
    fn on_tool_call_delta(
        &self,
        _ctx: &HookContext,
        _event: ToolCallDelta<'_>,
    ) -> impl Future<Output = ObservationAction> + WasmCompatSend { ... }
    fn on_stream_response_finish(
        &self,
        _ctx: &HookContext,
        _event: StreamResponseFinish<'_>,
    ) -> impl Future<Output = ObservationAction> + WasmCompatSend { ... }
    fn observes(&self, _kind: StepEventKind) -> bool { ... }
}

Per-run lifecycle observer and steerer.

Provided Methods

fn on_model_select( &self, _ctx: &HookContext, _event: ModelSelection<'_>, ) -> ModelSelectionAction

Selects the model for the pending model-call boundary.

Selection is synchronous, local, and non-blocking: it operates only on already-constructed ModelHandle values and may read or write the run Scratchpad, but must not perform blocking I/O. It runs once per CallModel step whose completion-call hooks proceed — including retries and post-tool calls — never after a completion-call stop, and in-flight attempts never rebind. In a HookStack, selections are passed to later hooks in registration order; the last selection wins and a stop is terminal. The default action keeps the current candidate. See ModelSelection for the full ordering contract.

fn on_completion_call( &self, _ctx: &HookContext, _event: CompletionCall<'_>, ) -> impl Future<Output = CompletionCallAction> + WasmCompatSend

Runs before a completion request is sent.

Return a per-turn patch, continue without one, or stop the run. Patches from a HookStack are merged in hook registration order.

fn on_completion_response( &self, _ctx: &HookContext, _event: CompletionResponse<'_>, ) -> impl Future<Output = ObservationAction> + WasmCompatSend

Observes a completed model response.

The default action continues the run.

fn on_model_turn_finished( &self, _ctx: &HookContext, _event: ModelTurnFinished<'_>, ) -> impl Future<Output = ModelTurnAction> + WasmCompatSend

Observes or rejects the content produced at the end of a model turn.

A retry is valid only for a tool-free turn and consumes the existing total model-call budget. The default action accepts the turn.

fn on_invalid_tool_call( &self, _ctx: &HookContext, _event: &InvalidToolCallContext, ) -> impl Future<Output = Option<InvalidToolCallAction>> + WasmCompatSend

Resolves a model-emitted tool call that cannot be dispatched as written.

The call may be failed, retried, repaired, skipped, or used to stop the run. Return None to leave the decision to a later hook. If every hook in a HookStack returns None, the agent preserves fail-fast behavior.

fn on_tool_call( &self, _ctx: &HookContext, _event: ToolCall<'_>, ) -> impl Future<Output = ToolCallAction> + WasmCompatSend

Runs before a valid tool call is executed.

The hook may rewrite the current arguments, skip execution, or stop the run. Rewrites in a HookStack are passed to subsequent hooks. The default action executes with the current arguments.

fn on_tool_result( &self, _ctx: &HookContext, _event: ToolResultEvent<'_>, ) -> impl Future<Output = ToolResultAction> + WasmCompatSend

Runs after a tool call resolves and before its presentation is sent to the model.

This includes framework-skipped calls whose tool body did not execute. Rewrites affect the model-visible presentation and result-content telemetry, but not the raw structured result or execution-outcome metadata. A stop omits result content from telemetry. The default action keeps the current presentation.

fn on_text_delta( &self, _ctx: &HookContext, _event: TextDelta<'_>, ) -> impl Future<Output = ObservationAction> + WasmCompatSend

Observes a text delta from a streaming response.

The default action continues the run.

fn on_reasoning_delta( &self, _ctx: &HookContext, _event: ReasoningDelta<'_>, ) -> impl Future<Output = ObservationAction> + WasmCompatSend

Observes a reasoning delta from a streaming response.

The aggregate is scoped to the reasoning part identified by the event’s correlator. Like all streamed deltas, it remains provisional until the model turn is accepted. The default action continues the run.

fn on_tool_call_delta( &self, _ctx: &HookContext, _event: ToolCallDelta<'_>, ) -> impl Future<Output = ObservationAction> + WasmCompatSend

Observes an argument delta for a streaming tool call.

The default action continues the run.

fn on_stream_response_finish( &self, _ctx: &HookContext, _event: StreamResponseFinish<'_>, ) -> impl Future<Output = ObservationAction> + WasmCompatSend

Observes a completed streaming response in canonical Rig form.

The default action continues the run.

fn observes(&self, _kind: StepEventKind) -> bool

Observation interest hint, primarily for high-frequency deltas.

Dyn Compatibility

This trait is not dyn compatible.

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

Implementations on Foreign Types

impl AgentHook for ()

fn observes(&self, _kind: StepEventKind) -> bool

Implementors

impl AgentHook for HookStack