docs: `session.idle` documents a removed `backgroundTasks` field instead of the current `aborted` field

[examon]

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.

[github-actions]

Documentation Gap Confirmed

Summary: The session.idle event documentation incorrectly references a removed backgroundTasks: BackgroundTasks field that no longer exists in the schema or any generated binding. Additionally, the current optional aborted: boolean field is entirely undocumented.

---

Affected files and locations

File	Line(s)	Issue
docs/features/streaming-events.md	~551	session.idle data-field table lists the removed backgroundTasks field
docs/features/streaming-events.md	~961	"at a glance" summary table also references backgroundTasks
nodejs/docs/examples.md	~422	Key Data Fields quick-reference includes backgroundTasks
nodejs/docs/agent-author.md	~273	Key Event Types quick-reference includes backgroundTasks

---

What needs to change

In all four locations above:

1. Remove the backgroundTasks / BackgroundTasks row — the field does not exist in session-events.schema.json, is absent from all six generated bindings, and is never present on the wire.

2. Add the aborted field — the actual current payload is:

   Data Field	Type	Required	Description
   aborted	boolean	optional	true when the session was cancelled via session.abort(); absent on normal completion

3. Optionally add a note explaining that background-task state is now signalled separately via session.background_tasks_changed (empty payload), which is why backgroundTasks was removed from session.idle.

This matters because session.idle is the event that sendAndWait() resolves on — readers currently reach for event.data.backgroundTasks (always undefined) and never discover that event.data.aborted is what distinguishes a cancelled turn from a completed one.

Generated by Documentation Handler for #2231 · sonnet46 17.1 AIC · ⌖ 5.11 AIC · ⊞ 5.4K · ◷