Summary

Allow sub-agent completion announces to route to the parent session as a user-message trigger instead of directly to the channel, enabling the main agent to orchestrate multi-step workflows.

Problem to solve

When a sub-agent spawned via sessions_spawn completes, the completion announce is dispatched directly to the channel as a delivery-mirror assistant message. The parent (main) agent session does not receive this announce as a triggering event and cannot react to it.

This means the main agent cannot orchestrate multi-step workflows where it needs to:

• Review the sub-agent's output before presenting it to the user
• Decide the next step based on results (e.g., spawn another agent, ask for human input)
• Add analysis or commentary to the sub-agent's work
• Gate sub-agent output quality before it reaches the channel

The main agent spawns a sub-agent and then goes blind — it never learns the sub-agent finished. The user must manually prompt "what happened?" after every step, defeating the purpose of having an orchestrator.

The current workaround is giving each sub-agent explicit sessions_send callback instructions to message the parent session with a structured payload. This works but requires: boilerplate in every spawn task (parent session key, JSON format, announce suppression via NO_REPLY), sessions_send in the sub-agent tool allowlist, and previously also required manual subagents kill + TERMINATED state instructions to prevent ghost replies.

Proposed solution

Add an announceTarget option at two levels:

1. Config-level default:

agents:
  defaults:
    subagents:
      announceTarget: "channel"  # default, current behavior
      # announceTarget: "parent" — route to parent session

2. Per-spawn override (parameter on sessions_spawn):

sessions_spawn(task="...", mode="run", announceTarget="parent")

Behavior when announceTarget is "parent":

• Sub-agent completes — its final output (announce text) is injected into the parent session as a user-role message (not assistant/delivery-mirror)
• This triggers a parent agent turn — the parent wakes up, sees the summary, and decides what to do
• No direct channel announce — the parent controls what reaches the channel

Why user-role? The current delivery-mirror (assistant role, 0 tokens) does not trigger an agent turn. For orchestration, the parent must wake up and process the result. User-role injection (same as sessions_send today) is the minimal change.

Token cost: The announce text is just the sub-agent's final output — a short summary, not the full transcript. Equivalent cost to the sessions_send workaround users already employ.

Alternatives considered

1. sessions_send callback pattern (current workaround): Sub-agent manually sends structured JSON to parent session. Works, but requires boilerplate in every spawn task, extra tools in allowlist, NO_REPLY to suppress duplicate announces, and historically required kill + TERMINATED instructions to prevent ghost replies. Fragile and verbose.

2. Static workflow tools (Lobster): Deterministic YAML pipelines work well for predefined linear flows (e.g., SEO audit: scrape URL, analyze, report). But each workflow is purpose-built — 10 different workflow types need 10 separate flows. Cannot replace dynamic orchestration where the main agent adapts the plan based on intermediate results, chooses which sub-agent to spawn next, or handles unexpected edge cases. CI pipeline vs engineering lead.

3. File-based handoff: Sub-agent writes result to a file, main agent reads it later. Requires a separate wake-up mechanism and polling — overengineered compared to native announce routing.

4. Webhook/hook triggers: Custom hooks on sub-agent completion events. Adds infrastructure complexity without clear benefit over simply routing the existing announce to the parent session.

Impact

Affected: Any user running multi-agent orchestration (main agent + specialized sub-agents)

Severity: Blocks workflow — main agent cannot function as an orchestrator without workarounds

Frequency: Every sub-agent completion in orchestrated workflows (multiple times per task)

Consequence: Without this, users must either (a) manually prompt the main agent after each sub-agent step, or (b) maintain verbose callback boilerplate in every spawn task. Both defeat the purpose of autonomous orchestration and add friction/failure points to every multi-step workflow.

Evidence/examples

Example orchestration flow (currently broken without workaround):

User: "Research competitors in the German market and draft an outreach strategy"

Main agent:
  -> spawns Research agent — "analyze top 5 competitors in DE"
  <- [announce goes to channel, main agent never wakes up]
  ... user must manually say "what happened?" ...

With announceTarget "parent":

Main agent:
  -> spawns Research agent
  <- receives research summary (parent-targeted announce triggers turn)
  -> reviews: "missing pricing data" — spawns another research pass
  <- receives pricing data
  -> spawns Strategy agent with combined context
  <- receives strategy draft
  -> reviews, adds assessment, presents to user

Workaround comparison — without this feature, every spawn task requires ~15 lines of callback boilerplate: parent session key, JSON callback format, sessions_send call, NO_REPLY for announce suppression. With this feature, the spawn task is just the task itself, zero boilerplate.

Environment: OpenClaw 2026.2.25, arm64, Discord channel, Opus main + sub-agents (Sonnet, Gemini, MiniMax, Codex)

Additional information

• Default behavior (announceTarget "channel") should remain unchanged for backward compatibility
• Per-spawn override allows mixing both modes: fire-and-forget tasks use channel announce, orchestrated tasks use parent routing
• The 2026.2.25 refactor of announce dispatch into a queue/direct/fallback state machine (PR Subagent announce delivery broken across multiple surfaces on 2026.2.23 #26867) may make this easier to implement — the routing decision point already exists
• Related improvement in 2026.2.25: preserve inter-session input provenance (fix(cron): prevent duplicate delivery for isolated jobs with announce mode #15739) already distinguishes internal vs external messages, which is the same conceptual boundary this feature needs