Repository navigation
docs: session.idle documents a removed backgroundTasks field instead of the current aborted field #2231
Description
Summary
The session.idle event reference documents a data field, backgroundTasks of type BackgroundTasks, that the event no longer carries. The optional field the event may carry, aborted, is not documented at all.
session.idle did carry backgroundTasks? when the reference guide was first written, but it was removed from the payload some time ago and the documentation was never updated. The type name BackgroundTasks does not exist in the schema at all today.
Where
Four places across three files still name the removed field:
| File | Line | Table |
|---|---|---|
docs/features/streaming-events.md |
551 | the session.idle data-field table |
docs/features/streaming-events.md |
961 | the "at a glance" event summary table |
nodejs/docs/examples.md |
422 | Key Data Fields quick reference |
nodejs/docs/agent-author.md |
273 | Key Event Types quick reference |
Current docs/features/streaming-events.md L549-551:
| Data Field | Type | Required | Description |
|------------|------|----------|-------------|
| `backgroundTasks` | `BackgroundTasks` | | Background agents/shells still running when the agent became idle |What the payload actually is
The shipped session-events.schema.json defines the session.idle payload as (field descriptions elided):
{
"type": "object",
"properties": {
"aborted": { "type": "boolean" }
},
"additionalProperties": false,
"title": "IdleData"
}additionalProperties is false, and the string backgroundTasks does not appear anywhere in session-events.schema.json or api.schema.json. All six generated bindings agree:
| Binding | Generated type |
|---|---|
| Node.js | interface IdleData { aborted?: boolean } |
| Python | class SessionIdleData: aborted: bool | None = None |
| Go | type SessionIdleData struct { Aborted *bool } |
| Rust | pub struct SessionIdleData { pub aborted: Option<bool> } |
| Java | record SessionIdleEventData(Boolean aborted) |
| .NET | class SessionIdleData { bool? Aborted } |
Confirmed on the wire against CLI 1.0.78-2, capturing the raw JSON-RPC frames:
// normal completion
{"type":"session.idle","data":{},"ephemeral":true, ...}
// after session.abort()
{"type":"session.idle","data":{"aborted":true},"ephemeral":true, ...}backgroundTasks is no longer present. session.idle is now emitted only after tracked active background work has quiesced, so a backgroundTasks snapshot on that payload would always be empty. Changes to background-task state are signalled separately, by the empty-payload session.background_tasks_changed event.
Impact
docs/features/streaming-events.md opens by describing itself as "a field-level reference for each event type so you know exactly what data to expect without reading the SDK source". For session.idle -- the event the guide calls the signal that a turn is fully complete, and the one sendAndWait() resolves on -- that reference is wrong in both directions: a reader reaches for event.data.backgroundTasks, which is always undefined, and never learns that event.data.aborted distinguishes a cancelled turn from a completed one.
Expected
The session.idle tables should document aborted (optional boolean) and drop the removed backgroundTasks field.
Activity
github-actions commentedon Aug 3, 2026
Documentation Gap Confirmed
Summary: The
session.idleevent documentation incorrectly references a removedbackgroundTasks: BackgroundTasksfield that no longer exists in the schema or any generated binding. Additionally, the current optionalaborted: booleanfield is entirely undocumented.Affected files and locations
docs/features/streaming-events.mdsession.idledata-field table lists the removedbackgroundTasksfielddocs/features/streaming-events.mdbackgroundTasksnodejs/docs/examples.mdbackgroundTasksnodejs/docs/agent-author.mdbackgroundTasksWhat needs to change
In all four locations above:
Remove the
backgroundTasks/BackgroundTasksrow — the field does not exist insession-events.schema.json, is absent from all six generated bindings, and is never present on the wire.Add the
abortedfield — the actual current payload is:abortedbooleantruewhen the session was cancelled viasession.abort(); absent on normal completionOptionally add a note explaining that background-task state is now signalled separately via
session.background_tasks_changed(empty payload), which is whybackgroundTaskswas removed fromsession.idle.This matters because
session.idleis the event thatsendAndWait()resolves on — readers currently reach forevent.data.backgroundTasks(alwaysundefined) and never discover thatevent.data.abortedis what distinguishes a cancelled turn from a completed one.