Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    AssistantText {
        text: String,
        step: usize,
    },
    ToolCall {
        name: String,
        id: String,
        arguments: String,
        step: usize,
    },
    Latency {
        step: usize,
        llm_ms: u64,
    },
    ToolResult {
        id: String,
        name: String,
        output: String,
        step: usize,
    },
    Usage {
        input_tokens: u32,
        output_tokens: u32,
        step: usize,
    },
    PartialToken {
        text: String,
        step: usize,
    },
    Reasoning {
        text: String,
        step: usize,
    },
    Compacted {
        removed: usize,
        kept: usize,
        summary_chars: usize,
        step: usize,
    },
    TurnFinished {
        reason: String,
        steps: usize,
    },
    PlanModeRequested {
        reason: String,
    },
    PlanModeApproved,
    PlanModeRejected {
        reason: String,
    },
    PlanProposed {
        plan_text: String,
        tool_calls: Vec<Value>,
    },
    PlanConfirmed,
    PlanRejected {
        reason: String,
    },
    MessageAppended {
        message: Message,
        parent_uuid: Option<String>,
        usage: Option<UsageMeta>,
    },
    MessageAppendedWithAudit {
        message: Message,
        audit: AuditMeta,
    },
    CompactionBoundary {
        turn: u32,
        compacted_count: usize,
        summary_uuid: Option<String>,
    },
    TodoUpdated {
        todos: Vec<TodoItem>,
    },
    GoalSet {
        condition: String,
        max_turns: u32,
    },
    GoalContinuing {
        reason: String,
        turns: u32,
    },
    GoalAchieved {
        condition: String,
        turns: u32,
    },
    GoalCleared,
    HookStarted {
        hook_event: String,
        hook_name: String,
        status_message: Option<String>,
    },
    HookProgress {
        hook_event: String,
        hook_name: String,
        last_line: String,
    },
    HookFinished {
        hook_event: String,
        hook_name: String,
        outcome: String,
        duration_ms: u64,
    },
    HookSystemMessage {
        text: String,
    },
}

A serialisable, non-exhaustive agent lifecycle event.

Uses String for the finish reason to avoid coupling to the FinishReason type. New variants can be added without a breaking change (see #[non_exhaustive]).

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.

AssistantText

Model generated text without tool calls.

Fields

text: String

step: usize

ToolCall

Model requested to execute a tool.

Fields

name: String

id: String

arguments: String

step: usize

Latency

Time taken for the LLM request (excluding tool execution), in ms.

Fields

step: usize

llm_ms: u64

ToolResult

Result of executing a tool call.

Fields

id: String

name: String

output: String

step: usize

Usage

Token usage statistics from the LLM provider.

Fields

input_tokens: u32

output_tokens: u32

step: usize

PartialToken

Partial token from streaming response (if streaming enabled).

Fields

text: String

step: usize

Reasoning

Reasoning / thinking content from a model that exposes an explicit reasoning channel (DeepSeek R1, OpenAI o1, etc.). Carries the full reasoning text for the current step; providers that stream reasoning tokens (DeepSeek’s reasoning_content SSE deltas) accumulate them and emit the final, fully-joined string in this event. UI layers render it as a thinking… block separate from the assistant message body. Emitted exactly once per step that produced reasoning content; steps without reasoning skip the event.

Fields

text: String

step: usize

Compacted

Transcript was compacted to fit size constraints.

Fields

removed: usize

kept: usize

summary_chars: usize

step: usize

TurnFinished

Agent run completed.

Fields

reason: String

Human-readable reason for termination (e.g. “no_more_tool_calls”).

steps: usize

Number of iterations executed.

PlanModeRequested

Goal-202: Agent is requesting permission to enter plan mode. Emitted by RequestPlanModeTool before any exploration begins. The TUI / HTTP surface should prompt the user and call AgentRuntime::approve_plan_mode_request or reject_plan_mode_request.

Fields

reason: String

PlanModeApproved

Goal-202: The user approved the plan-mode entry request.

PlanModeRejected

Goal-202: The user rejected the plan-mode entry request.

Fields

reason: String

PlanProposed

Agent has produced a plan and is waiting for confirmation.

Fields

plan_text: String

tool_calls: Vec<Value>

PlanConfirmed

Plan was confirmed, execution will proceed.

PlanRejected

Plan was rejected with a reason.

Fields

reason: String

MessageAppended

A complete message was just appended to the agent transcript.

Fired exactly once per committed message inside the agent runtime: once for the user message that starts a turn, once for the compaction summary if cross-turn compaction fires, and once per message in the kernel’s output batch. Carries the full Message (role, content, tool_calls, tool_call_id, reasoning_content) so persistence consumers can write the canonical record without reassembling it from the finer AssistantText / ToolCall / ToolResult streaming events.

parent_uuid — if Some, the emitter wants this message to be written as a branch off the given UUID rather than the SessionWriter’s internal chain pointer. Used by subagent runtimes (g155).

usage — token usage for this message (non-None for assistant messages produced by an LLM call, g156).

Not emitted for seeded transcript messages loaded from an existing session on resume (those are already on disk).

Fields

message: Message

parent_uuid: Option<String>

Explicit parent UUID override for subagent branch points (g155).

usage: Option<UsageMeta>

Token usage for this message (g156).

MessageAppendedWithAudit

Variant of [MessageAppended] specifically for Role::Tool messages that have an associated [AuditMeta] (Goal 153). The persistence sink handles this identically to MessageAppended but populates the audit field of crate::session::TranscriptEntry.

Emitting a separate variant (rather than Option<AuditMeta> on MessageAppended) keeps the common path zero-cost and avoids making audit an optional field on every event.

Fields

message: Message

audit: AuditMeta

CompactionBoundary

Cross-turn compaction just fired; a compact_boundary marker should be written to the session JSONL (g157).

turn — the turn index when compaction occurred. compacted_count — how many messages were removed. summary_uuid — UUID of the compaction summary message that replaced them.

Fields

turn: u32

compacted_count: usize

summary_uuid: Option<String>

TodoUpdated

Goal-167: emitted when the agent updates its task checklist via todo_write. Carries the complete replacement list so consumers can render the current state without storing diffs.

Fields

todos: Vec<TodoItem>

GoalSet

A /goal was set for this session.

Fields

condition: String

The completion condition as written by the user.

max_turns: u32

Hard cap on autonomous turns.

GoalContinuing

The judge evaluated the condition and found it not yet met. The loop will continue with another turn.

Fields

reason: String

The judge’s explanation for why the condition is not yet met.

turns: u32

Number of turns elapsed so far.

GoalAchieved

The judge evaluated the condition and confirmed it is met.

Fields

condition: String

The original condition string.

turns: u32

Total turns taken to reach the goal.

GoalCleared

The active goal was cleared — either by /goal clear, turn-budget exhaustion, or an explicit DELETE /sessions/:id/goal call.

HookStarted

A hook started executing.

Fields

hook_event: String

hook_name: String

status_message: Option<String>

HookProgress

A hook produced incremental stdout output.

Fields

hook_event: String

hook_name: String

last_line: String

HookFinished

A hook finished executing.

Fields

hook_event: String

hook_name: String

outcome: String

duration_ms: u64

HookSystemMessage

A hook produced a system message to show to the user.

Fields

text: String

Trait Implementations

impl Clone for AgentEvent

fn clone(&self) -> AgentEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentEvent

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentEvent

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for AgentEvent

fn eq(&self, other: &AgentEvent) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for AgentEvent

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for AgentEvent