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 SessionHandler. Subscribers receive a clone of every event but cannot influence permission decisions, tool results, or anything else that requires returning a HandlerResponse.

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.

Enums

RecvError

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