Events & Errors

StreamEvent

Unified stream event emitted by all adapters. Tagged enum serialized with a type discriminant in snake_case.

pub enum StreamEvent {
    TextDelta { text: String },

    ThinkingDelta { text: String },

    ToolStart {
        tool_name: String,
        tool_id: String,
        args: Option<HashMap<String, serde_json::Value>>,
    },

    ToolEnd {
        tool_id: String,
        success: bool,
        output: Option<String>,
        error: Option<String>,
    },

    TurnEnd,

    Error {
        message: String,
        severity: Option<Severity>,
    },

    Done {
        result: RunResult,
    },

    Raw {
        provider: CliName,
        event: serde_json::Value,
    },
}

Variants

TextDelta

Incremental text output from the agent. Concatenate all deltas to build the full response.

ThinkingDelta

Reasoning/thinking output. Only emitted by providers that support extended thinking (Claude) or reasoning (Codex).

ToolStart

A tool call has started. args contains the parsed arguments as a JSON map, or None if no arguments were provided.

ToolEnd

A tool call has completed. Check success to determine the outcome. On failure, error contains the error message. On success, output contains the tool's output text.

TurnEnd

A full agent turn has completed. In multi-turn runs, you'll see multiple TurnEnd events.

Error

An error or warning from the adapter or the CLI process. Check severity to distinguish warnings from errors. This is also emitted when timeouts fire or the tool failure limit is reached.

Done

The run has completed. Always the last event emitted. Contains the final RunResult with success status, output text, stats, and session ID.

Raw

Escape hatch for provider-specific events that don't map to the unified types. Contains the raw JSON and the provider name.

Serialization

StreamEvent uses #[serde(tag = "type", rename_all = "snake_case")], so JSON output looks like:

{"type":"text_delta","text":"Hello"}
{"type":"tool_start","toolName":"Read","toolId":"t1","args":{"file_path":"/tmp/test.rs"}}
{"type":"done","result":{"success":true,"text":"..."}}

Severity

pub enum Severity {
    Warning,
    Error,
}

Serializes to lowercase: "warning", "error".

Error

Errors returned by cli-agents operations.

pub enum Error {
    NoCli,
    CliRequiredWithExecutable,
    Process(String),
    Io(std::io::Error),
    Json(serde_json::Error),
    Other(String),
}

The crate also exports pub type Result<T> = std::result::Result<T, Error>;.