Struct ModelTurnFinished 

pub struct ModelTurnFinished<'a> {
    pub turn: usize,
    pub content: &'a Vec<AssistantContent>,
    pub usage: Usage,
    pub identity: &'a ResponseIdentity,
    pub finish_reason: Option<&'a FinishReason>,
    pub max_tokens: Option<u64>,
    pub raw: &'a Value,
}

Medium-neutral accepted model-turn event.

The turn is canonicalized and parked in the run state, but has not yet been advanced into tool execution or finalization. A hook may therefore reject a tool-free turn with ModelTurnAction::Retry.

Fields

turn: usize

One-based model-call index.

content: &'a Vec<AssistantContent>

Canonical assistant content parked for hook acceptance.

usage: Usage

Usage reported for the turn.

identity: &'a ResponseIdentity

This exact attempt’s response identity metadata. Fired for every completed model call on both surfaces — including streamed tool-only and reasoning-only turns, which fire no StreamResponseFinish — so a provider-neutral hook observing this event alone records identity for every accepted call. On a retry, this is the retried attempt’s own identity, never a previous attempt’s.

finish_reason: Option<&'a FinishReason>

Why the provider stopped generating this attempt, normalized.

FinishReason is the portable vocabulary — Stop, Length, ToolCalls, ContentFilter, and Other(String) carrying a provider’s own spelling verbatim for anything outside it — so a hook can decide whether to accept a turn without naming a provider or touching a raw response type. FinishReason::truncated_output is the predicate for “the provider cut this turn short”, which is the usual retry trigger.

None means the provider reported no reason at all, which is a real outcome for several OpenAI-compatible gateways; it is deliberately not smoothed into Stop, because “finished normally” and “did not say” are different facts to steer on.

The value is the one recorded for this attempt’s completion call, after the Stop→ToolCalls reconciliation that both surfaces apply, so a provider that reports a bare stop on a turn carrying tool calls still reads as ToolCalls here. On a retry this is the retried attempt’s own reason, never a previous attempt’s.

max_tokens: Option<u64>

The output-token cap this exact attempt was prepared with.

Resolved after the agent’s configured value, the runner/request override, and the merged completion-call RequestPatch — so a stateful completion-call hook that raises the cap for a retry sees its own new value here on the following turn, not the agent’s baseline. None means no cap was sent, so the provider’s own default applied.

Paired with finish_reason this is what makes a portable retry-on-truncation decision possible: a hook can tell a turn cut short at a cap it chose from one cut short at a cap it did not.

raw: &'a Value

The provider’s own response for this attempt — see CompletionResponse::raw in rig-core for the exact meaning of the payload: the value the model’s inherent raw_completion / raw_stream would have returned, serialized. Every provider seam populates it; Value::Null only when the response was built without a provider behind it (a hand-constructed model, a record persisted before the field). On a retry this is the retried attempt’s own, never a previous attempt’s.

Carried here, and not only on the surface-specific events, for the same reason identity is: this is the medium-neutral event, so a hook observing it alone sees the payload for every accepted call on both surfaces.

Trait Implementations

impl<'a> Clone for ModelTurnFinished<'a>

fn clone(&self) -> ModelTurnFinished<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for ModelTurnFinished<'a>