Module subscription 

Event subscription handles returned by subscribe() methods. Subscription handles for observing session and lifecycle events.

Returned by Session::subscribe and Client::subscribe_lifecycle.

Each subscription is an opt-in observer of events that are also delivered to the per-event handlers installed on the session config (see crate::handler). Subscribers receive a clone of every event but cannot influence permission decisions, tool results, or any other event whose handler return value affects the runtime.

Async iteration

The subscription types implement tokio_stream::Stream, so consumers can use adapter combinators from tokio_stream::StreamExt or futures::StreamExt (filtering, mapping, batching, racing with tokio::select!, etc.) without learning the SDK’s internal channel choice. A simple while let Ok(event) = sub.recv().await { ... } loop also works for callers who don’t need the Stream surface.

Lag policy

Each subscriber maintains its own internal queue. If a consumer cannot keep up, the oldest events are dropped and the next call yields Lagged reporting how many events were skipped. Slow subscribers do not block the producer.

Structs

EventSubscription

Subscription to runtime events for a single Session.

Lagged

The subscription fell behind the producer.

LifecycleSubscription

Subscription to lifecycle events on a Client.

RecvError

Error returned by crate::subscription::EventSubscription::recv and crate::subscription::LifecycleSubscription::recv.

Enums

RecvErrorKind

Error kind for subscription receive operations.