openclaw - 💡(How to fix) Fix [Feature]: Background sub-agent spawn mode — parent session completes immediately while children run async [1 participants]

Summary

Add a sub-agent spawn mode where the parent's run completes immediately after dispatching children, leaving the parent session free to accept new user messages while sub-agents work in the background. Results are delivered asynchronously via injected messages, notifications, or kanban updates.

Problem

When a parent agent spawns sub-agents via sessions_spawn, the parent's turn stays alive for the entire duration of the sub-agent work — it calls agent.wait(childRunId) which blocks until all children complete. During this time:

• The user cannot send new messages — the parent session has an active run, so chat.send is rejected
• The UI appears frozen — even though children are working independently on separate sessions
• Simple follow-ups are impossible — "what's the status?", "also do X", or just casual chatting must wait until all orchestration completes

This is the #1 UX complaint for desktop/chat interfaces built on OpenClaw (e.g. Cookie OS). Long-running sub-agent tasks (web research, multi-step file processing, complex analysis) can take minutes, during which the entire chat is locked.

Current behavior

User sends message
  → Parent spawns child 1 (returns immediately with runId)
  → Parent spawns child 2 (returns immediately)
  → Parent calls agent.wait(child1) — BLOCKS
  → Child 1 completes → announcement delivered
  → Parent calls agent.wait(child2) — BLOCKS
  → Child 2 completes → announcement delivered
  → Parent synthesizes and responds
  → User can finally send another message

sessions_yield gets close but the parent's lifecycle is still coupled to the children — the parent is suspended waiting for wake events, not truly free.

Proposed behavior

A new parameter on sessions_spawn — e.g. mode: "background" or detach: true:

User sends message
  → Parent spawns child 1 (mode: "background")
  → Parent spawns child 2 (mode: "background")  
  → Parent responds: "I've started both tasks. I'll update you when they're done."
  → Parent's run completes (final) ← session is now FREE
  → User can chat normally
  → [Later] Child 1 finishes → result injected as message / notification / kanban update
  → [Later] Child 2 finishes → result injected as message / notification / kanban update

Implementation notes

Most infrastructure already exists:

• Async spawn — spawnSubagentDirect() already returns immediately with status: "accepted"
• Separate sessions — children already run on isolated sessions (agent:X:subagent:UUID)
• Announcement system — subagent-announce.ts already formats completion results
• SubagentRegistry — already tracks child runs independently
• Task system — task-executor.ts provides durable lifecycle tracking

What's needed:

1. New spawn parameter (mode: "background" or detach: true) in SpawnSubagentParams
2. Skip expectsCompletionMessage: true for background spawns — parent doesn't wait
3. On child completion, deliver results through an async channel:
   • Option A: Inject as a new user/system message into the parent session (like cron job results do)
   • Option B: Write to kanban task / memory note
   • Option C: Emit a gateway event that control UIs can surface as a notification
4. System prompt guidance for when to use background vs. foreground spawning

Use case

Cookie OS — an Electron desktop app using OpenClaw as its agent runtime — provides a chat interface where users interact with their agent. When sub-agents are working, the entire chat is locked. Users expect to keep conversing while background work proceeds. The OpenClaw gateway enforces one active run per session, so this cannot be worked around at the client level.

Related issues

• #55481 — HTTP endpoint for fire-and-forget spawn (external callers). Our issue is about the in-session agent experience.
• #53483 — Auto-yield parent after mode=run ACP spawn. Addresses a related symptom but doesn't free the parent session.
• #38626 — Subagent lifecycle observability. Complementary — background spawns would benefit from better observability.
• #46413 — Long task notification after WebSocket disconnect. Related delivery problem.