Enum HandlerEvent 

#[non_exhaustive]
pub enum HandlerEvent {
    SessionEvent {
        session_id: SessionId,
        event: SessionEvent,
    },
    PermissionRequest {
        session_id: SessionId,
        request_id: RequestId,
        data: PermissionRequestData,
    },
    UserInput {
        session_id: SessionId,
        question: String,
        choices: Option<Vec<String>>,
        allow_freeform: Option<bool>,
    },
    ExternalTool {
        invocation: ToolInvocation,
    },
    ElicitationRequest {
        session_id: SessionId,
        request_id: RequestId,
        request: ElicitationRequest,
    },
    ExitPlanMode {
        session_id: SessionId,
        data: ExitPlanModeData,
    },
    AutoModeSwitch {
        session_id: SessionId,
        error_code: Option<String>,
        retry_after_seconds: Option<u64>,
    },
}

Events dispatched by the SDK session event loop to the handler.

The handler returns a HandlerResponse indicating how the SDK should respond to the CLI. For fire-and-forget events (SessionEvent), the response is ignored.

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.

SessionEvent

Informational session event from the timeline (e.g. assistant.message_delta, session.idle, tool.execution_start). Fire-and-forget — return HandlerResponse::Ok.

Fields

session_id: SessionId

The session that emitted this event.

event: SessionEvent

The event payload.

PermissionRequest

The CLI requests permission for an action. Return HandlerResponse::Permission(..).

Fields

session_id: SessionId

The requesting session.

request_id: RequestId

Unique ID to correlate the response.

data: PermissionRequestData

Permission request payload.

UserInput

The CLI requests user input. Return HandlerResponse::UserInput(..). The handler may block (e.g. awaiting a UI dialog) — this is expected.

Fields

session_id: SessionId

The requesting session.

question: String

The question text to present.

choices: Option<Vec<String>>

Optional multiple-choice options.

allow_freeform: Option<bool>

Whether free-form text input is allowed.

ExternalTool

The CLI requests execution of a client-defined tool. Return HandlerResponse::ToolResult(..).

Fields

invocation: ToolInvocation

The tool call to execute.

ElicitationRequest

The CLI broadcasts an elicitation request for the provider to handle. Return HandlerResponse::Elicitation(..).

Fields

session_id: SessionId

The requesting session.

request_id: RequestId

Unique ID to correlate the response.

request: ElicitationRequest

The elicitation request payload.

ExitPlanMode

The CLI requests exiting plan mode. Return HandlerResponse::ExitPlanMode(..).

Fields

session_id: SessionId

The requesting session.

data: ExitPlanModeData

Plan mode exit payload.

AutoModeSwitch

The CLI asks whether to switch to auto model when an eligible rate limit is hit. Return HandlerResponse::AutoModeSwitch.

Fields

session_id: SessionId

The requesting session.

error_code: Option<String>

The specific rate-limit error code that triggered the request, if known (e.g. user_weekly_rate_limited, user_global_rate_limited).

retry_after_seconds: Option<u64>

Seconds until the rate limit resets, when known. Per RFC 9110’s Retry-After delta-seconds form, this is an integer count of seconds. Handlers can use it to render a humanized reset time alongside the prompt.

Trait Implementations

impl Debug for HandlerEvent

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

Formats the value using the given formatter.