Enum StepEvent 

#[non_exhaustive]
pub enum StepEvent<'a, M: CompletionModel> {
    CompletionCall {
        prompt: &'a Message,
        history: &'a [Message],
        turn: usize,
    },
    CompletionResponse {
        prompt: &'a Message,
        response: &'a CompletionResponse<M::Response>,
    },
    ModelTurnFinished {
        turn: usize,
        content: &'a OneOrMany<AssistantContent>,
        usage: Usage,
    },
    InvalidToolCall(&'a InvalidToolCallContext),
    ToolCall {
        tool_name: &'a str,
        tool_call_id: Option<&'a str>,
        internal_call_id: &'a str,
        args: &'a str,
    },
    ToolResult {
        tool_name: &'a str,
        tool_call_id: Option<&'a str>,
        internal_call_id: &'a str,
        args: &'a str,
        result: &'a str,
        outcome: &'a ToolOutcome,
        extensions: &'a ToolResultExtensions,
    },
    TextDelta {
        delta: &'a str,
        aggregated: &'a str,
    },
    ToolCallDelta {
        tool_call_id: &'a str,
        internal_call_id: &'a str,
        tool_name: Option<&'a str>,
        delta: &'a str,
    },
    StreamResponseFinish {
        prompt: &'a Message,
        response: &'a M::StreamingResponse,
    },
}

An observable point in an agent run, passed to AgentHook::on_event.

StepEvent borrows everything it carries (it is Copy), so a hook may inspect the event without taking ownership and a HookStack can forward the same event to each hook in turn.

The streaming-only variants (TextDelta, ToolCallDelta and StreamResponseFinish) are emitted only by AgentRunner::stream.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

CompletionCall

Before a completion request is sent to the model. Honors Flow::Continue, Flow::PatchRequest (patch this turn’s request) and Flow::Terminate. Across a HookStack, every hook’s PatchRequest is merged (see the module docs).

Fields

prompt: &'a Message

The prompt message for this turn.

history: &'a [Message]

The chat history preceding prompt.

turn: usize

One-based index of this model call within the run.

CompletionResponse

After a non-streaming completion response is received. Suppressed for turns recovered by invalid tool-call repair, skip, or retry. Honors Flow::Continue and Flow::Terminate. The medium-specific (non-streaming) counterpart of ModelTurnFinished, carrying the raw provider response.

Fields

prompt: &'a Message

The prompt message for this turn.

response: &'a CompletionResponse<M::Response>

The model’s completion response.

ModelTurnFinished

After a model turn is accepted into the run, on both surfaces, regardless of whether the turn produced text, tool calls, reasoning, or mixed content. This is the normalized, medium-neutral counterpart of CompletionResponse (non-streaming) and StreamResponseFinish (streaming) — use it for telemetry that must fire once per turn everywhere, including a streamed tool-only turn that fires no StreamResponseFinish. Suppressed for turns recovered by invalid tool-call repair, skip, or retry, and fired after the medium-specific raw event when one fires. Observe-only: honors Flow::Continue and Flow::Terminate.

Fields

turn: usize

One-based index of this model call within the run.

content: &'a OneOrMany<AssistantContent>

The model’s assistant content for this turn — the canonical committed model output. For an ordinary turn this is exactly what is recorded into the run. On a structured-output Tool-mode turn that finalizes by calling the output tool, this is the model-emitted content including that output-tool call; the run then persists the turn as assistant text (the structured output) with the tool call dropped, so the persisted message differs from this content.

usage: Usage

Token usage for this turn (zeroed if the provider reported none).

InvalidToolCall(&'a InvalidToolCallContext)

The model emitted a tool call that is unknown or disallowed for this turn. Honors Flow::Fail (the default), Flow::Retry, Flow::Repair, Flow::Skip and Flow::Terminate; Flow::Continue is treated as Flow::Fail.

ToolCall

Before a tool is executed. Honors Flow::Continue, Flow::RewriteArgs (execute the tool with rewritten arguments), Flow::Skip (return reason as the tool result without executing) and Flow::Terminate. Across a HookStack, RewriteArgs is chained: args reflects prior hooks’ rewrites (see the module docs).

Fields

tool_name: &'a str

Name of the tool about to be called.

tool_call_id: Option<&'a str>

Provider-supplied tool call ID, when available.

internal_call_id: &'a str

Internal Rig call ID correlating this call’s events.

args: &'a str

JSON arguments for the call.

ToolResult

After a tool has produced a result (or a ToolCall hook skipped it). Honors Flow::Continue, Flow::RewriteResult (substitute the result the model sees) and Flow::Terminate.

result is the model-visible output, and outcome / extensions are the structured execution result — the machine-visible half a hook inspects without parsing result. outcome distinguishes success from a classified ToolFailure (timeout, not-found, …), a Skipped call, or a Denied one; extensions carries provider/application metadata the tool attached that is never sent to the model.

For the first hook, result is the tool’s actual output and outcome its raw structured outcome; across a HookStack, RewriteResult is chained so a later hook sees the prior hook’s replacement in result. A rewrite changes only result (the model-visible text) — outcome and extensions are the tool’s raw structured result throughout, so a redaction hook cannot mask the true outcome from a later policy hook (see the module docs).

Fields

tool_name: &'a str

Name of the tool that was called.

tool_call_id: Option<&'a str>

Provider-supplied tool call ID, when available.

internal_call_id: &'a str

Internal Rig call ID correlating this call’s events.

args: &'a str

JSON arguments for the call.

result: &'a str

The model-visible tool result. Reflects any earlier hook’s RewriteResult; the first hook sees the tool’s actual output.

outcome: &'a ToolOutcome

The structured outcome of the execution (success / classified error / skipped / denied). The raw outcome, unaffected by RewriteResult.

extensions: &'a ToolResultExtensions

Metadata the tool attached to its result, never sent to the model.

TextDelta

Streaming only: a text delta was received. aggregated is the full text accumulated for the turn so far. Honors Flow::Continue and Flow::Terminate.

Fields

delta: &'a str

The newly received text fragment.

aggregated: &'a str

All text accumulated for the turn so far.

ToolCallDelta

Streaming only: a tool-call delta was received. tool_name is Some on the first delta for a tool call and None on subsequent deltas. Honors Flow::Continue and Flow::Terminate.

Fields

tool_call_id: &'a str

Provider-supplied tool call ID.

internal_call_id: &'a str

Internal Rig call ID correlating this call’s events.

tool_name: Option<&'a str>

Tool name, present on the first delta only.

delta: &'a str

The newly received argument fragment.

StreamResponseFinish

Streaming only: the provider finished streaming a completion response. This is the streaming counterpart of CompletionResponse and, like it, is suppressed for turns recovered by invalid tool-call repair, skip, or retry. Note one medium-specific difference from CompletionResponse: it fires only on turns that streamed assistant text — a turn that emits only a tool call (or only reasoning) does not fire it. For a per-turn event that fires on every turn on both surfaces, use ModelTurnFinished. Honors Flow::Continue and Flow::Terminate.

Fields

prompt: &'a Message

The prompt message for this turn.

response: &'a M::StreamingResponse

The provider’s final streaming response.

Implementations

impl<M: CompletionModel> StepEvent<'_, M>

pub fn kind(&self) -> StepEventKind

The StepEventKind discriminant of this event.

Trait Implementations

impl<M: CompletionModel> Clone for StepEvent<'_, M>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M: CompletionModel> Copy for StepEvent<'_, M>