[Bug]: Sub-agent completion announce fails with "unsupported channel: telegram"

Summary

Sub-agent completion announcements fail silently when spawned from Telegram sessions. The Gateway attempts direct delivery 3 times, each failing with unsupported channel: telegram, then gives up. The requester never receives notification that the sub-agent completed.

This affects all sub-agents spawned from Telegram (both DMs and groups) using sessions_spawn.

Environment

• OpenClaw version: 2026.2.17+ (confirmed on 2026.2.17)
• OS: Linux 6.8.0-90-generic (x64)
• Node: v22.22.0
• Channel: Telegram (affects both DMs and groups)
• Spawn method: sessions_spawn tool

Steps to Reproduce

1. Configure OpenClaw with Telegram channel
2. From a Telegram session (DM or group), spawn a sub-agent:

   sessions_spawn(task="Create a report on XYZ", model="sonnet")
   

3. Wait for the sub-agent to complete its task
4. Check Gateway logs: journalctl --user -u openclaw-gateway -f

Expected Behavior

1. Sub-agent completes successfully
2. OpenClaw announces the completion back to the Telegram session
3. User receives the sub-agent's result

Actual Behavior

1. Sub-agent completes successfully ✅
2. OpenClaw attempts to announce the completion via "direct announce" mechanism
3. Each attempt fails with: Subagent completion direct announce failed for run <id>: unsupported channel: telegram
4. After 3 retries, OpenClaw gives up and marks cleanup as complete
5. User never receives the notification ❌

Evidence

Gateway Logs

Feb 20 14:46:51 srv1304246 node[2097444]: 2026-02-20T14:46:51.851+00:00 Subagent completion direct announce failed for run 1495559a-7e44-465a-b24f-bd5d595fc4b4: unsupported channel: telegram
Feb 20 14:46:52 srv1304246 node[2097444]: 2026-02-20T14:46:52.904+00:00 Subagent completion direct announce failed for run 1495559a-7e44-465a-b24f-bd5d595fc4b4: unsupported channel: telegram
Feb 20 14:46:54 srv1304246 node[2097444]: 2026-02-20T14:46:54.940+00:00 Subagent completion direct announce failed for run 1495559a-7e44-465a-b24f-bd5d595fc4b4: unsupported channel: telegram
Feb 20 14:46:54 srv1304246 node[2097444]: 2026-02-20T14:46:54.942+00:00 [warn] Subagent announce give up (retry-limit) run=1495559a-7e44-465a-b24f-bd5d595fc4b4 child=agent:main:subagent:2455ac6a-4e01-4f48-80dd-65752c0c01a2 requester=agent:main:main retries=3 endedAgo=3s

Subagent Run Metadata

From /home/openclaw/.openclaw/subagents/runs.json:

{
  "runId": "1495559a-7e44-465a-b24f-bd5d595fc4b4",
  "requesterSessionKey": "agent:main:main",
  "requesterOrigin": {
    "channel": "telegram",
    "to": "telegram:8517717047",
    "accountId": "default"
  },
  "expectsCompletionMessage": true,
  "outcome": { "status": "ok" },
  "announceRetryCount": 3,  ← Tried 3 times
  "lastAnnounceRetryAt": 1771598814941,
  "cleanupCompletedAt": 1771598814941
}

Root Cause Analysis

Looking at src/agents/subagent-announce.ts, the sendSubagentAnnounceDirectly() function uses two delivery paths:

1. For completion messages (expectsCompletionMessage=true): Uses callGateway({ method: "send", ... })
2. For trigger messages: Uses callGateway({ method: "agent", ... })

The send method path (used for completion messages) calls src/gateway/server-methods/send.ts, which:

1. Normalizes the channel via normalizeChannelId(channelInput)
2. Calls getChannelPlugin(channel) to fetch the plugin
3. If plugin is null, returns unsupported channel: <channel>

The bug: When getChannelPlugin() is called during sub-agent announce, Telegram plugin may not be fully initialized at the Gateway level, causing it to return null even though Telegram is configured and working.

The agent method path works fine because it routes through the standard agent execution pipeline, which properly resolves channels regardless of plugin initialization state.

Impact

• Severity: High — breaks core sub-agent workflow for Telegram users
• Scope: All sub-agents spawned from Telegram sessions
• User experience: Silent failure — users think sub-agents are "sleeping" when they've actually finished
• Workarounds: None (users must manually check session history or poll subagents list)

Affected Channels

Based on code inspection, this likely affects:

• ✅ Telegram (confirmed)
• ❓ Discord (unconfirmed, but same code path)
• ❓ Slack (unconfirmed, but same code path)
• ✅ WhatsApp — Already reported in [Bug]: Cron job announce delivery ignores configured channel, routes to unconfigured whatsapp #13420, Bug: Cron job delivery fails with 'Unsupported channel: whatsapp' despite correct telegram configuration #21595 (same root cause)

Channels that likely work fine:

• IRC, Signal, Google Chat (if they use agent method fallback)

Proposed Solution

Option 1: Always use agent method for direct delivery (simplest, most consistent)

Change sendSubagentAnnounceDirectly() to always use callGateway({ method: "agent", ... }) instead of conditionally using send. The agent method handles all deliverable channels correctly.

Option 2: Fix channel plugin initialization race

Ensure getChannelPlugin() always returns the correct plugin during sub-agent announce, even if called before full Gateway initialization.

Option 3: Retry with agent method on send failure

If send fails with "unsupported channel", fallback to agent method automatically.

Recommendation: Option 1 — simplest, most consistent, eliminates the race condition entirely.

Related Issues

• [Bug]: Cron job announce delivery ignores configured channel, routes to unconfigured whatsapp #13420 — Cron job announce delivery routing bug (same root cause: channel resolution fails)
• Bug: Cron job delivery fails with 'Unsupported channel: whatsapp' despite correct telegram configuration #21595 — Cron job delivery fails with "Unsupported channel: whatsapp" (same root cause)
• Sub-agent announce fails with gateway timeout when parent session is active #7666 — Sub-agent announce fails with gateway timeout (different root cause, but same symptom)
• sessions_spawn completion notification fires indefinitely (dedup failure) #19197 — Sub-agent completion notifications fire infinitely (different bug, but related to delivery failures)

Additional Context

This bug was discovered when investigating why sub-agents consistently complete successfully but users never receive notifications. The sub-agent runs are logged in subagents/runs.json with status: "ok" and announceRetryCount: 3, confirming the completion succeeded but delivery failed.

The issue is specific to the direct announce delivery path and does not affect queued announces (which use a different code path through enqueueAnnounce).

Reproducible: Yes (100% reproduction rate on Telegram)
Regression: Likely introduced in recent channel routing refactor (needs bisection to confirm)
Fix complexity: Low (one-line change to use agent method consistently)