Enum ToolAuditOutcome 

#[non_exhaustive]
pub enum ToolAuditOutcome {
    Blocked {
        reason: String,
    },
    RequiresConfirmation {
        description: String,
        listen_context: Option<ListenExecutionContext>,
    },
    Cached {
        result: ToolResult,
    },
    Replayed {
        result: ToolResult,
    },
    Invalidated {
        reason: String,
    },
    Completed {
        result: ToolResult,
    },
    PersistenceFailed {
        result: Option<ToolResult>,
        error: String,
    },
}

Lifecycle outcome for a single tool call.

Every variant is an authoritative terminal state the server must persist — including paths that bypass tool execution entirely (blocked, confirmation, cached replay) or that fail persistence after the tool already ran.

Variants are ordered roughly by lifecycle position: policy check → cache lookup → execution → post-execution persistence.

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.

Blocked

The policy hook rejected the tool call.

The tool never executed. The reason is the string returned by ToolDecision::Block.

Fields

reason: String

Reason provided by the policy hook.

RequiresConfirmation

The policy hook yielded for user approval.

The tool is paused pending a resume decision. The turn loop will emit a follow-up record on resume (either Completed after execution or Blocked if policy now rejects).

Fields

description: String

Human-readable confirmation description shown to the user.

listen_context: Option<ListenExecutionContext>

Optional listen-context captured at confirmation time.

Cached

The execution store already held a completed result for this tool call — the idempotency layer replayed the cached outcome instead of calling the tool again.

Fields

result: ToolResult

The cached ToolResult that was replayed.

Replayed

The caller resubmitted external tool results for an already processed handoff, and the SDK served the previously recorded result rather than re-accepting the payload.

Distinct from Cached in that this fires on the external runtime path where the SDK did not execute the tool itself in any attempt.

Fields

result: ToolResult

The ToolResult previously recorded for this tool call.

Invalidated

A listen-tool snapshot expired or was invalidated before the user could confirm it.

This is a non-completion path: no final ToolResult is produced because the confirmation window closed.

Fields

reason: String

Reason the listen-tool invalidated its snapshot.

Completed

The tool ran to completion (success or failure).

result.success indicates whether the tool itself succeeded; even a failing run is considered a completed lifecycle.

Fields

result: ToolResult

Final ToolResult produced by the tool.

PersistenceFailed

The tool executed but the server could not durably persist the outcome (event store, execution store, or message append failed).

The record preserves the in-memory ToolResult so that audit consumers can reason about divergence between what the tool produced and what made it to durable storage.

Fields

result: Option<ToolResult>

The ToolResult that would have been persisted, if any.

None when the persistence layer failed before a result was produced (e.g. a tool_call_start event failed to append).

error: String

Short, human-readable description of the persistence failure.

Implementations

impl ToolAuditOutcome

pub const fn kind(&self) -> &'static str

Static discriminant string used for metrics, tracing attributes, and durable audit rows.

pub const fn result(&self) -> Option<&ToolResult>

Returns the ToolResult associated with this outcome, if one is available.

Present for Cached, Replayed, Completed, and most PersistenceFailed paths. Absent for Blocked, RequiresConfirmation, and Invalidated.

Trait Implementations

impl Clone for ToolAuditOutcome

fn clone(&self) -> ToolAuditOutcome

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolAuditOutcome

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ToolAuditOutcome

fn deserialize<__D>( __deserializer: __D, ) -> Result<ToolAuditOutcome, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ToolAuditOutcome

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.