Enum AgentEvent 

pub enum AgentEvent {
    Token {
        content: String,
    },
    ReasoningToken {
        content: String,
    },
    ToolToken {
        tool_call_id: String,
        content: String,
    },
    ToolStart {
        tool_call_id: String,
        tool_name: String,
        arguments: Value,
    },
    ToolComplete {
        tool_call_id: String,
        result: ToolResult,
    },
    ToolError {
        tool_call_id: String,
        error: String,
    },
    ToolLifecycle {
        tool_call_id: String,
        tool_name: String,
        phase: String,
        elapsed_ms: Option<u64>,
        is_mutating: bool,
        auto_approved: bool,
        summary: Option<String>,
        error: Option<String>,
    },
    NeedClarification {
        question: String,
        options: Option<Vec<String>>,
        tool_call_id: Option<String>,
        allow_custom: bool,
    },
    TaskListUpdated {
        task_list: TaskList,
    },
    TaskListItemProgress {
        session_id: String,
        item_id: String,
        status: TaskItemStatus,
        tool_calls_count: usize,
        version: u64,
    },
    TaskListCompleted {
        session_id: String,
        completed_at: DateTime<Utc>,
        total_rounds: u32,
        total_tool_calls: usize,
    },
    TaskEvaluationStarted {
        session_id: String,
        items_count: usize,
    },
    TaskEvaluationCompleted {
        session_id: String,
        updates_count: usize,
        reasoning: String,
    },
    TokenBudgetUpdated {
        usage: TokenBudgetUsage,
    },
    ContextCompressionStatus {
        phase: String,
        status: String,
    },
    ContextSummarized {
        summary: String,
        messages_summarized: usize,
        tokens_saved: u32,
        usage_before_percent: f64,
        usage_after_percent: f64,
        trigger_type: String,
    },
    ContextPressureNotification {
        percent: f64,
        level: String,
        message: String,
    },
    SubSessionStarted {
        parent_session_id: String,
        child_session_id: String,
        title: Option<String>,
    },
    SubSessionEvent {
        parent_session_id: String,
        child_session_id: String,
        event: Box<AgentEvent>,
    },
    SubSessionHeartbeat {
        parent_session_id: String,
        child_session_id: String,
        timestamp: DateTime<Utc>,
    },
    SubSessionCompleted {
        parent_session_id: String,
        child_session_id: String,
        status: String,
        error: Option<String>,
    },
    PlanModeEntered {
        session_id: String,
        reason: Option<String>,
        pre_permission_mode: String,
    },
    PlanModeExited {
        session_id: String,
        approved: bool,
        restored_mode: String,
        plan: Option<String>,
    },
    PlanFileUpdated {
        session_id: String,
        file_path: String,
        content_summary: String,
    },
    RunnerProgress {
        session_id: String,
        round_count: u32,
    },
    Complete {
        usage: TokenUsage,
    },
    Error {
        message: String,
    },
}

Represents events emitted during agent execution.

These events are streamed to clients via SSE to provide real-time feedback on agent progress, tool execution, and completion.

Variants

Text Generation

• Token - Streaming text token
• ReasoningToken - Streaming reasoning/thinking token (separate channel)

Tool Execution

• ToolStart - Tool execution started
• ToolComplete - Tool finished successfully
• ToolError - Tool execution failed

User Interaction

• NeedClarification - Agent needs user input

Progress Tracking

• TaskListUpdated - Task list created or modified
• TaskListItemProgress - Individual item progress
• TaskListCompleted - All items completed
• TaskEvaluationStarted - Task evaluation began
• TaskEvaluationCompleted - Task evaluation finished

Context Management

• TokenBudgetUpdated - Context budget changed
• ContextCompressionStatus - Context compression lifecycle progress
• ContextSummarized - Old messages summarized

Sub-sessions (Async Spawn)

• SubSessionStarted - A child session is created and scheduled to run
• SubSessionEvent - Forwarded raw child event (full fidelity)
• SubSessionHeartbeat - Periodic heartbeat while the child is running
• SubSessionCompleted - Child session finished (completed/cancelled/error)

Terminal Events

• Complete - Execution finished successfully
• Error - Execution failed

Serialization

Events are serialized as JSON with a type field for discrimination:

{"type": "token", "content": "Hello"}
{"type": "complete", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}

Variants

Token

Text token generated by the LLM.

Fields

content: String

Generated text content

ReasoningToken

Reasoning/thinking token generated by the LLM.

This is streamed separately from assistant answer tokens so the UI can choose whether and how to display model reasoning traces.

Fields

content: String

Generated reasoning content

ToolToken

Streaming output emitted while a specific tool call is running.

This is used to render “live output” inside a tool-call card in the UI without mixing tool output into the assistant’s main token stream.

Fields

tool_call_id: String

Tool call identifier that this output belongs to.

content: String

Output chunk.

ToolStart

Tool execution started.

Fields

tool_call_id: String

Unique tool call identifier

tool_name: String

Name of the tool being executed

arguments: Value

Tool arguments (JSON)

ToolComplete

Tool execution completed successfully.

Fields

tool_call_id: String

Tool call identifier

result: ToolResult

Tool execution result

ToolError

Tool execution failed.

Fields

tool_call_id: String

Tool call identifier

error: String

Error message

ToolLifecycle

Structured lifecycle event for tool execution tracking.

These events complement ToolStart/ToolComplete/ToolError with richer metadata (mutability, auto-approval, wall-clock timing) and are emitted by ToolEmitter (in bamboo-agent-tools).

Fields

tool_call_id: String

Tool call identifier

tool_name: String

Canonical tool name

phase: String

Lifecycle phase: “begin”, “finished”, “error”, “cancelled”

elapsed_ms: Option<u64>

Wall-clock milliseconds since the call began (None for begin)

is_mutating: bool

Whether the tool mutates state (writes files, runs commands)

auto_approved: bool

Whether execution was auto-approved (no user prompt needed)

summary: Option<String>

Human-readable summary

error: Option<String>

Error message (if phase == “error”)

NeedClarification

Agent needs clarification from the user.

Fields

question: String

Question to ask the user

options: Option<Vec<String>>

Optional predefined options

tool_call_id: Option<String>

Tool call identifier that triggered this clarification

allow_custom: bool

Whether the user can provide a free-text response

TaskListUpdated

Emitted when task list is created or updated.

Fields

task_list: TaskList

Current task list state.

TaskListItemProgress

Emitted when a task item makes progress (delta update).

Fields

session_id: String

Session identifier

item_id: String

Item identifier

status: TaskItemStatus

New item status

tool_calls_count: usize

Number of tool calls made

version: u64

Item version (for optimistic concurrency)

TaskListCompleted

Emitted when all task items are completed.

Fields

session_id: String

Session identifier

completed_at: DateTime<Utc>

Completion timestamp

total_rounds: u32

Total agent rounds executed

total_tool_calls: usize

Total tool calls made

TaskEvaluationStarted

Emitted when task evaluation starts.

Fields

session_id: String

Session identifier

items_count: usize

Number of items to evaluate

TaskEvaluationCompleted

Emitted when task evaluation completes.

Fields

session_id: String

Session identifier

updates_count: usize

Number of items updated

reasoning: String

Evaluation reasoning

TokenBudgetUpdated

Emitted when token budget is prepared (after context truncation)

Fields

usage: TokenBudgetUsage

Token budget details

ContextCompressionStatus

Emitted when host-side context compression lifecycle changes.

Fields

phase: String

Compression phase label (for example: pre-turn, mid-turn).

status: String

Compression status: started | completed | failed | skipped

ContextSummarized

Emitted when conversation context is summarized

Fields

summary: String

Generated summary text

messages_summarized: usize

Number of old messages summarized

tokens_saved: u32

Tokens saved by summarization

usage_before_percent: f64

Context usage percentage before compression

usage_after_percent: f64

Context usage percentage after compression

trigger_type: String

What triggered the compression: “auto” | “manual” | “critical”

ContextPressureNotification

Emitted when context pressure reaches warning or critical levels. Frontend should display this to the user as a proactive notification.

Fields

percent: f64

Context usage as a percentage of the context window.

level: String

Severity level: “warning” (70%) or “critical” (90%).

message: String

Human-readable message describing the pressure state.

SubSessionStarted

A child session was spawned from a parent session (async background job).

Fields

parent_session_id: String

child_session_id: String

title: Option<String>

Optional title (useful for UI lists).

SubSessionEvent

Forwarded raw child event to the parent session stream.

Child sessions are not allowed to spawn further sessions, so this should not nest.

Fields

parent_session_id: String

child_session_id: String

event: Box<AgentEvent>

SubSessionHeartbeat

Heartbeat emitted while a child session is running.

Fields

parent_session_id: String

child_session_id: String

timestamp: DateTime<Utc>

SubSessionCompleted

Child session finished (completed/cancelled/error).

Fields

parent_session_id: String

child_session_id: String

status: String

One of: “completed” | “cancelled” | “error” | “skipped”

error: Option<String>

PlanModeEntered

Plan mode was entered.

Fields

session_id: String

Session identifier

reason: Option<String>

Optional reason for entering plan mode

pre_permission_mode: String

Previous permission mode before entering plan mode

PlanModeExited

Plan mode was exited.

Fields

session_id: String

Session identifier

approved: bool

Whether the exit was approved by the user

restored_mode: String

The permission mode restored after exiting

plan: Option<String>

Plan content that was reviewed, if any

PlanFileUpdated

Plan file was updated.

Fields

session_id: String

Session identifier

file_path: String

Path to the plan file

content_summary: String

Summary of the plan content (truncated)

RunnerProgress

Runner progress update emitted at the start of each agent turn.

Used to track live execution progress (round count, current activity) for diagnostic visibility, especially for child sessions.

Fields

session_id: String

Session identifier

round_count: u32

Current turn/round count

Complete

Agent execution completed successfully.

Fields

usage: TokenUsage

Final token usage statistics

Error

Agent execution failed.

Fields

message: String

Error message

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<(), Error>

Formats the value using the given formatter.

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

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentEvent

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.