Problem

When a user triggers a sub-agent task via Discord/Telegram (e.g., "analyze this codebase"), the assistant says "I'll notify you when done." But the main session is passive — it only activates on incoming messages. So the user always has to ask "is it done yet?" instead of being notified.

Current Behavior

• sessions_spawn with mode: "run" sends a completion event back to the parent session
• But the parent session may be dormant (no heartbeat, user not chatting)
• Result: completion goes undelivered until the user sends another message

Proposed Solution

Add an optional notifyOnComplete parameter to sessions_spawn:

{
  "task": "analyze codebase",
  "mode": "run",
  "notifyOnComplete": {
    "channel": "discord",
    "target": "1473294190094848133",
    "message": "✅ Analysis complete: {summary}"
  }
}

When the sub-agent finishes, OpenClaw Gateway sends the notification directly to the specified channel, bypassing the parent session's active/dormant state.

Alternative: Webhook callback

{
  "task": "...",
  "onComplete": {
    "webhook": "https://example.com/callback",
    "headers": { "Authorization": "Bearer ..." }
  }
}

Use Case

We run codex-autopilot — a multi-project Codex CLI automation system. We solved this problem at the application layer (watchdog monitors tmux Codex sessions and sends Discord notifications on completion). But a first-class OpenClaw solution would benefit all users.

Workarounds We've Tried

1. Heartbeat checks — 30-min interval, too slow
2. Cron polling — works but hacky
3. Application-layer watchdog — our current solution, but requires custom infrastructure

A built-in notifyOnComplete would eliminate all of these.