`sendAndWait` returns prematurely when orchestrator dispatches sub-agents via `task` and ends its turn

[kevinlims]

Summary

sendAndWait awaits session.idle. The CLI fires session.idle when the orchestrator's turn ends — including when the orchestrator ends its turn after dispatching task calls. The SDK does not track in-flight sub-agents; task is fire-and-forget from the SDK's perspective. Consumers' code believes the session is complete and tears down state while sub-agents are still running.

Repro

const session = await client.createSession({
  customAgents: [
    { name: "scanner", description: "Scans codebase", prompt: "..." },
    { name: "triager", description: "Triages findings", prompt: "..." },
  ],
});

await session.sendAndWait({
  prompt: "Dispatch a scanner agent to analyze the codebase, then a triager to rank findings.",
});

// `sendAndWait` resolves shortly after the orchestrator's `task(scanner)` + `task(triager)` calls
// — BEFORE the sub-agents have completed their work.

Expected

sendAndWait resolves only when all dispatched sub-agents have completed.

Actual

sendAndWait resolves on the first session.idle event. If the orchestrator's turn ends after dispatching but before sub-agent completion, the session is considered idle and sendAndWait returns. Sub-agents may still be running.

Frequency observed in another harness: ~30% of multi-sub-agent dispatch sessions.

Evidence (SDK source)

nodejs/src/session.ts: sendAndWait() listens for event.type === "session.idle" and calls resolveIdle() on the first occurrence. No task-dispatch tracking, no sub-agent counter, no subagent.completed accumulation.

Workaround (consumer-side)

Either:

• Poll for a terminal artifact path on the filesystem (works if the sub-agents are expected to write a known output file).
• Maintain a sub-agent counter in user code, incremented on subagent.started and decremented on subagent.completed. Only treat the session as complete when session.idle AND counter == 0.

Both reinvent state machine logic the SDK is best positioned to provide.

Suggested fix

• Make sendAndWait track dispatched sub-agents (via subagent.started / subagent.completed) and resolve only when the session is idle AND all sub-agents have completed.
• Or add a new sendAndWaitForCompletion({ prompt }) API consumers can opt into.

Related

• SessionHooks (onPreToolUse / onPostToolUse) are not invoked for tool calls made by sub-agents spawned via task #1097 — SessionHooks (onPreToolUse / onPostToolUse) not invoked for tool calls made by sub-agents spawned via task. Same theme of "sub-agent lifecycle isn't fully surfaced through the SDK's consumer-facing surface."
• Subagent sessions don't inherit parent SessionFs state, breaking spill-then-delegate flows #1168 — Subagent sessions don't inherit parent SessionFs state. Another instance of "sub-agents don't inherit X from the parent session."
• session.disconnect() is cooperative; doesn't abort sendAndWait or close the transport #1273 — session.disconnect() cooperative. Compounds with this issue: when the consumer notices premature resolution and tries to recover, the disconnect path is also broken.
• No heartbeat event during LLM-streamed tool-argument construction; watchdogs can't distinguish working from hung #1274 — No heartbeat during tool-argument streaming. Adjacent observability gap on the same "consumer can't reliably tell what the session is doing" theme.

Environment

- SDK: @github/copilot-sdk@0.3.0
- CLI: @github/copilot@1.0.45
- Node: 22 LTS
- OS: Windows 11
- Model: claude-sonnet-4-6

[github-actions]

Investigation findings

Label applied: bug

What I investigated

• nodejs/src/session.ts lines 224–277 – the sendAndWait implementation
• nodejs/src/generated/session-events.ts – IdleEvent / IdleData schema, and subagent.started / subagent.completed / subagent.failed event definitions
• go/session.go and python/copilot/session.py – equivalent SendAndWait / send_and_wait implementations in other SDKs

What I found

All three SDKs (Node, Go, Python) have the same implementation pattern: register a listener, then resolve/unblock on the first session.idle event with no sub-agent tracking whatsoever.

The IdleData interface in the generated schema is documented as:

"Payload indicating the session is idle with no background agents in flight"

This is the stated contract — session.idle should only fire when all sub-agents have completed. However, as you observe, the CLI fires session.idle when the orchestrator's turn ends, which can happen before dispatched sub-agents (task(...) calls) have finished their work. This breaks the documented contract.

The sub-agent lifecycle events (subagent.started, subagent.completed, subagent.failed) do exist in the schema and are surfaced through the event stream, but sendAndWait ignores them entirely.

Why this is a bug

There is a contract violation: either —

1. The CLI is incorrectly emitting session.idle before all dispatched sub-agents complete (violating the "no background agents in flight" guarantee), or
2. The SDK should defensively track in-flight sub-agents and not resolve sendAndWait until session.idle arrives and the sub-agent counter is zero.

Either way, the consumer-visible outcome — sendAndWait resolving while work is still in progress — is unambiguously broken behavior. The workarounds described in the issue (polling filesystem artifacts, maintaining a sub-agent counter in user code) are logic the SDK is best positioned to encapsulate, given that subagent.started / subagent.completed / subagent.failed events are already available in the event stream.

The bug affects all three SDKs that expose sendAndWait-style APIs (Node, Go, Python) since they share the same implementation pattern.

Generated by Bug Handler for issue #1275 · ● 770.3K · ◷