fix(agents): harden subagent completion delivery by steipete · Pull Request #82834 · openclaw/openclaw

steipete · 2026-05-17T02:00:58Z

Summary

Fixes #82803.
Refs #44925, #82784, #82787, #82804, #79059, and #80223.

This consolidates the narrow subagent completion delivery fixes from the related partial PRs into one runtime change:

subagent_announce completion handoffs now participate in agent-mediated completion delivery, so group/channel requester sessions inherit the existing message_tool_only visible-reply policy instead of relying on a normal final reply that the user may never see.
Active requester sessions still get the first wake/steer attempt, but if that wake fails OpenClaw now falls through to the requester-agent handoff instead of returning early and letting the completion disappear.
Empty requester-agent handoffs remain treated as failed delivery and can fall back to steer/queue routing.
The completion prompt now tells the requester agent what to do when the runtime marks the route as message-tool-only.
Docs and changelog updated for the visible behavior change.

This intentionally does not solve the broader lifecycle/reconciliation work from #82784/#82787. Late-success watching and durable restart/reconcile semantics still belong in a follow-up.

Contributor credit preserved in the commit trailers for @galiniliev, @yozakura-ava, and @moeedahmed.

Verification

pnpm docs:list
pnpm exec oxfmt --write --threads=1 src/agents/subagent-announce-delivery.ts src/agents/subagent-announce.ts src/agents/subagent-announce-delivery.test.ts src/agents/subagent-announce.format.e2e.test.ts
node scripts/run-vitest.mjs src/agents/subagent-announce-delivery.test.ts src/agents/subagent-announce-dispatch.test.ts src/agents/subagent-announce.format.e2e.test.ts
- 4 files passed, 112 tests passed.
node scripts/run-vitest.mjs src/auto-reply/reply/completion-delivery-policy.test.ts
- 1 file passed, 16 tests passed.
node scripts/run-vitest.mjs src/agents/subagent-announce-delivery.test.ts src/agents/subagent-announce-dispatch.test.ts src/agents/subagent-announce.format.e2e.test.ts src/auto-reply/reply/completion-delivery-policy.test.ts
- 4/5 files passed and 127/128 tests passed; the first run hit a timeout in the existing legacy WhatsApp policy inference case, then the isolated policy file rerun passed all 16 tests.
git diff --check
/Users/steipete/Projects/agent-scripts/skills/codex-review/scripts/codex-review --mode branch
- clean: no accepted/actionable findings reported.

Behavior addressed: subagent completion announce delivery could disappear or arrive too late when the requester-agent handoff produced no visible output, active requester wake failed, or group/channel routes required message-tool delivery.
Real environment tested: local OpenClaw checkout on macOS, focused Vitest shards through node scripts/run-vitest.mjs, plus Codex review against origin/main.
Exact steps or command run after this patch: node scripts/run-vitest.mjs src/agents/subagent-announce-delivery.test.ts src/agents/subagent-announce-dispatch.test.ts src/agents/subagent-announce.format.e2e.test.ts; node scripts/run-vitest.mjs src/auto-reply/reply/completion-delivery-policy.test.ts; git diff --check; Codex review helper.
Evidence after fix: focused announce shard passed 112 tests; policy shard passed 16 tests; regression tests cover active-wake fallback, empty direct handoff steer fallback, channel message-tool-only subagent completions, and direct DM automatic delivery.
Observed result after fix: group/channel subagent completions request sourceReplyDeliveryMode: "message_tool_only" and require message-tool evidence; active requester wake failures continue into requester-agent handoff; empty handoff results can steer fallback instead of being accepted as delivered.
What was not tested: live chat-channel round trip, full suite, and the broader late-success/reconcile lifecycle work tracked by #82784/#82787.

clawsweeper · 2026-05-17T02:02:00Z

Codex review: needs real behavior proof before merge.

Summary
The PR updates subagent completion delivery to include subagent_announce in mediated completion handling, fall through to requester-agent handoff after failed active-requester wakeups, enforce message-tool-only policy for group/channel completions, and document/test the behavior.

Reproducibility: yes. The current-main source path shows active wake failures can return before requester-agent handoff, and group/channel subagent completions do not participate in the shared message-tool-only policy; linked reports add concrete delivery-drop evidence.

Real behavior proof
Not applicable: The PR is maintainer-labeled, so the external contributor proof gate is not applied; the body includes focused local terminal/test proof but no live chat-channel round trip.

Next step before merge
Protected maintainer label plus dirty merge state make this a maintainer landing/rebase decision, not an automated repair job.

Security
Cleared: The diff changes agents delivery logic, docs, changelog, and tests without adding dependencies, CI execution, permissions, secret handling, or new external code paths.

Review details

Best possible solution:

Land a rebased version of this consolidated runtime fix if maintainer review and CI stay clean, while keeping the broader late-success/reconcile lifecycle work in the separate linked follow-ups.

Do we have a high-confidence way to reproduce the issue?

Yes. The current-main source path shows active wake failures can return before requester-agent handoff, and group/channel subagent completions do not participate in the shared message-tool-only policy; linked reports add concrete delivery-drop evidence.

Is this the best way to solve the issue?

Yes for the narrow bug. The PR keeps delivery agent-mediated, reuses the existing visible-reply policy, and avoids raw child-output sends; late-success watching and durable reconciliation are correctly left to separate work.

Acceptance criteria:

node scripts/run-vitest.mjs src/agents/subagent-announce-delivery.test.ts src/agents/subagent-announce-dispatch.test.ts src/agents/subagent-announce.format.e2e.test.ts
node scripts/run-vitest.mjs src/auto-reply/reply/completion-delivery-policy.test.ts
git diff --check
Optional live Telegram proof for visible completion delivery after rebase

What I checked:

current-main active requester drop path: Current main returns a failed direct delivery when an active requester session cannot be woken unless the failure is a message-tool mode mismatch, which matches the active-wake drop this PR removes. (src/agents/subagent-announce-delivery.ts:675, 9e67f53b913a)
current-main subagent mediated tool set: Current main only treats image, music, and video generation as agent-mediated completion tools; subagent_announce is absent before the PR. (src/agents/subagent-announce-delivery.ts:60, 9e67f53b913a)
existing delivery policy contract: The shared completion policy resolves group/channel completions to message_tool_only by default and falls back to automatic only when configured, so reusing it for subagent completions is consistent with current contracts. (src/auto-reply/reply/completion-delivery-policy.ts:40, 9e67f53b913a)
PR diff shape: The PR imports completionRequiresMessageToolDelivery, adds subagent_announce to the mediated completion set, logs and falls through after active wake failure, and keeps empty handoffs as failed delivery rather than raw-sending child output. (src/agents/subagent-announce-delivery.ts:1, adf6bd7703c6)
PR regression coverage: The PR adds focused regression cases for active requester wake fallthrough, empty handoff steer fallback, channel subagent completions requiring message-tool delivery, and direct DM automatic delivery. (src/agents/subagent-announce-delivery.test.ts:1083, adf6bd7703c6)
related report and partial PR evidence: The body consolidates related evidence from [Bug]: Subagent completion direct announce fails with no visible reply #82803, fix(subagents): add sendMessage fallback + callGateway fallthrough for delivery drops #79059, and fix: require mediated delivery for subagent announce completions #80223; those reports/PRs describe live delivery drops and installed-runtime proof for active wake fallthrough and mediated subagent completion delivery.

Likely related people:

@steipete: Blame and recent commit history show substantial recent work on subagent announcement delivery and async/media completion delivery around the exact code paths touched here. (role: recent area contributor; confidence: high; commits: 80848fc0401a, 2d8fa2344758, 1a956b6ba156; files: src/agents/subagent-announce-delivery.ts, src/agents/subagent-announce.ts, src/auto-reply/reply/completion-delivery-policy.ts)
@funmerlin: Commit 16c27c1 introduced shared group/channel completion-routing policy and related tests that this PR builds on. (role: adjacent completion-routing contributor; confidence: medium; commits: 16c27c145958; files: src/auto-reply/reply/completion-delivery-policy.ts, src/tasks/task-registry.ts, src/agents/subagent-announce-delivery.test.ts)

Remaining risk / open question:

The PR head is behind current main and live metadata reports mergeable_state: dirty, so landing needs maintainer rebase/conflict handling.
No live chat-channel round trip is included for the consolidated PR; the body reports focused local Vitest shards and related prior live evidence, but not a fresh Telegram/group-channel runtime proof for this exact head.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 9e67f53b913a.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: adf6bd7703

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-17T02:05:19Z

+    const requiresMessageToolDelivery =
+      agentMediatedCompletion &&
+      (expectedMediaUrls.length > 0 ||
+        completionRequiresMessageToolDelivery({
+          cfg,


Skip message-tool-only checks for internal subagent handoffs

Do not apply completionRequiresMessageToolDelivery(...) to internal requester-agent handoffs (requesterIsSubagent=true), because these deliveries are intentionally deliver=false and should produce an internal orchestration reply, not a user-facing message-tool send. With this change, nested subagent completions that inherit a group/channel origin can be forced into message_tool_only, then fail with "completion agent did not deliver through the message tool", which causes retries/fallback and can drop completion propagation to the parent subagent.

Useful? React with 👍 / 👎.

Co-authored-by: Galin Iliev <galini@microsoft.com> Co-authored-by: Ava Daigo <theavadaigo@gmail.com> Co-authored-by: Moeed Ahmed <moeedahmed@users.noreply.github.com>

steipete · 2026-05-17T02:48:54Z

Landed in d887eb8dc2ccffb5f7068b436e4eacbbd069de58 from rebased head 67b3d73fdc4d227c5072b91e9f218312ea0844ee.

Thanks @galiniliev, @yozakura-ava, and @moeedahmed. I kept the co-author trailers on the landed commit and moved the changelog entry into the current Unreleased section.

Verification:

git diff --check
node scripts/run-vitest.mjs src/agents/subagent-announce-delivery.test.ts src/agents/subagent-announce-dispatch.test.ts src/agents/subagent-announce.format.e2e.test.ts src/auto-reply/reply/completion-delivery-policy.test.ts -> 5 files, 128 tests passed
Codex review on the branch before push
GitHub PR checks on head 67b3d73fdc4d227c5072b91e9f218312ea0844ee passed, including Real behavior proof after maintainer proof: override

openclaw-barnacle Bot added docs Improvements or additions to documentation agents Agent runtime and tooling size: M maintainer Maintainer-authored PR labels May 17, 2026

chatgpt-codex-connector Bot reviewed May 17, 2026

View reviewed changes

clawsweeper Bot added the mantis: telegram-visible-proof Mantis should capture Telegram visible proof. label May 17, 2026

This was referenced May 17, 2026

fix: Subagent completion direct announce often fails with no visible reply #82804

Closed

fix: require mediated delivery for subagent announce completions #80223

Closed

clawsweeper Bot mentioned this pull request May 17, 2026

Long subagent runs can time out silently without checkpointing or deliverable verification #82784

Closed

fix(agents): harden subagent completion delivery

67b3d73

Co-authored-by: Galin Iliev <galini@microsoft.com> Co-authored-by: Ava Daigo <theavadaigo@gmail.com> Co-authored-by: Moeed Ahmed <moeedahmed@users.noreply.github.com>

steipete force-pushed the codex/subagent-completion-delivery-consolidation branch from adf6bd7 to 67b3d73 Compare May 17, 2026 02:42

steipete added the proof: override Maintainer override for the external PR real behavior proof gate. label May 17, 2026

steipete merged commit d887eb8 into main May 17, 2026
116 of 117 checks passed

steipete deleted the codex/subagent-completion-delivery-consolidation branch May 17, 2026 02:48

steipete mentioned this pull request May 17, 2026

fix(subagents): add sendMessage fallback + callGateway fallthrough for delivery drops #79059

Closed

GanglyPuma22 mentioned this pull request May 18, 2026

fix(agents): prevent premature subagent completion from causing message loss and session-state drift [AI-assisted] #81621

Open

clawsweeper Bot mentioned this pull request May 21, 2026

[Bug]: Telegram forum-topic subagent completion fails when announce agent does not use message tool #85070

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(agents): harden subagent completion delivery#82834

fix(agents): harden subagent completion delivery#82834
steipete merged 1 commit into
mainfrom
codex/subagent-completion-delivery-consolidation

steipete commented May 17, 2026

Uh oh!

clawsweeper Bot commented May 17, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 17, 2026

Uh oh!

Uh oh!

steipete commented May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

steipete commented May 17, 2026

Summary

Verification

Uh oh!

clawsweeper Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

steipete commented May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

clawsweeper Bot commented May 17, 2026 •

edited

Loading