Problem

When a subagent (sessions_spawn with mode: "run") completes its work, the completion announcement is delivered to the requester session via a direct in-process dispatch that requires the requester session to be available and responsive.

If the requester session is busy (streaming a response, compacting, waiting for tools), the direct announce call times out after 120 seconds. The announce system retries 3 times, but each attempt hits the same busy-session condition, eventually giving up with:

[warn] Subagent completion direct announce failed for run X: gateway request timeout for agent
[warn] Subagent announce give up (retry-limit) run=X child=... retries=3 deliveryError="completion agent handoff is still pending"

The subagent itself has completed its work (all tool calls finished, report generated). The announcement is permanently lost.

Key observations

• Subagent and requester run on the same host (no network disconnect)
• The requester session is simply too busy to process the announce call within 120 seconds
• 3 retries do not help — the requester is consistently busy across the retry window
• This is distinct from the LLM stream idle timeout (Issue fix: Reset subagent session idle timeout on successful tool calls to prevent premature termination #94124)

Proposed Design

Persist the completion announcement so the requester can fetch it on its next available turn, instead of pushing directly to a busy session.

Option A: Session entry annotation

1. On subagent completion, write metadata to the requester session entry (e.g. metadata.subagentCompletions[])
2. Before the requester starts its next LLM turn, scan and process pending announcements
3. Durable (written to disk), survives restarts, decouples timing completely

Option B: Message queue event

1. Subagent completion emits an internal event to a shared message queue
2. Requester consumes from the queue on its next available turn
3. More architecturally clean but requires queue infrastructure

Option C: Session file message injection

1. Write a system event into the requester session file
2. The requester picks it up on the next read cycle

Workarounds

• Increasing the announce timeout only delays the failure — does not fix the race
• Manually checking subagent session output — not practical

Related

• Issue fix: Reset subagent session idle timeout on successful tool calls to prevent premature termination #94124 — subagent idle timeout during tool execution (different problem, same user impact: lost subagent output)
• PR fix: refresh subagent idle timeout on successful tool calls #94133 — fixes fix: Reset subagent session idle timeout on successful tool calls to prevent premature termination #94124 (tool-activity heartbeat)