Summary

The new optional deliveryStatus object distinguishes sent, suppressed, partial_failed, and failed delivery outcomes, including per-payload outcomes when durable delivery provides them. deliverySucceeded remains the legacy retry-marker compatibility field: sent and suppressed are terminal no-retry results, while partial_failed and failed do not clear retry state. One deliberate tightening: the compatibility boolean now follows the final durable send status rather than incidental onError callbacks, so non-fatal delivery hiccups do not incorrectly mark a final sent/suppressed outcome as retryable.

Value proposition

Automation can now tell what happened after an agent produced payloads. Scripts and supervisors using openclaw agent --json --deliver can distinguish successful sends, intentional hook suppressions, partial sends, preflight failures, and hard delivery failures without parsing human stderr or guessing from a coarse boolean.

Anticipated consumers

• CLI automation using openclaw agent --json --deliver.
• Gateway/agent callers that need a structured retry/no-retry decision.
• Session-final-delivery cleanup logic that currently relies on deliverySucceeded.
• Hook authors and channel maintainers who need hook cancellations surfaced as intentional suppressions rather than ambiguous delivery failures.

Why maintainers should consider this

This follows Peter's guidance from #57843 by anchoring the public status projection on sendDurableMessageBatch, not by extending deprecated deliverOutboundPayloads semantics. The change is additive, documented, and covered by focused tests for sent, suppressed, no-payload, preflight, partial failure, strict JSON failure, and best-effort failure paths.

Verification

• timeout 600s claude --print --tools "" --no-session-persistence --output-format text < /tmp/claude-review-current.txt (external local review; no blocking findings)
• pnpm test src/agents/command/delivery.test.ts (16 tests passed; covers sent delivery, hook suppression, no-payload suppression, preflight failure with reason and no errorMessage, partial failure with errorMessage, strict delivery failure with errorMessage, strict preflight failure, and best-effort failure paths)
• pnpm exec oxfmt --check --threads=1 docs/cli/agent.md
• git diff --check
• pnpm check:deprecated-api-usage
• pnpm tsgo:core
• pnpm build
• pnpm exec oxfmt --check --threads=1 CHANGELOG.md docs/cli/agent.md src/agents/command/delivery.ts src/agents/command/delivery.test.ts
• pnpm exec oxlint --tsconfig config/tsconfig/oxlint.core.json src/agents/command/delivery.ts src/agents/command/delivery.test.ts
• pnpm docs:check-links

pnpm check:docs passed docs formatting, markdown lint, and MDX checks, then failed in docs:check-i18n-glossary on broad existing zh-CN glossary drift across many docs. The failure was not specific to this new deliveryStatus section.

Real behavior proof

• Behavior or issue addressed: openclaw agent --json --deliver and deliverAgentCommandResult now expose durable delivery status from sendDurableMessageBatch, including sent, suppressed, partial-failed, and failed outcomes, without changing the legacy deliverySucceeded compatibility field shape.
• Real environment tested: Local OpenClaw source build with OPENCLAW_BUILD_PRIVATE_QA=1, real QA gateway child, qa-channel plugin, Pi runtime, and mock-openai/gpt-5.5 provider. The run used a synthetic QA channel only; no external chat service was contacted.
• Exact steps or command run after this patch: Gateway RPC equivalent of node dist/index.js agent --agent qa --message 'Finish with exactly delivery-proof-ok.' --json --deliver --reply-channel qa-channel --reply-to dm:delivery-proof --model mock-openai/gpt-5.5 --timeout 120.
• Evidence after fix: Terminal output from the local QA gateway RPC run:

{
  "waitResult": { "status": "ok" },
  "mockProvider": { "requestCount": 1, "lastRequest": { "model": "gpt-5.5", "providerVariant": "openai" } },
  "payloads": [{ "text": "delivery-proof-ok", "mediaUrl": null }],
  "deliveryStatus": {
    "requested": true,
    "attempted": true,
    "status": "sent",
    "succeeded": true,
    "resultCount": 1,
    "payloadOutcomes": [{ "index": 0, "status": "sent", "resultCount": 1 }]
  },
  "qaChannel": {
    "outboundCount": 1,
    "outbound": [{ "conversation": { "id": "delivery-proof", "kind": "direct" }, "text": "delivery-proof-ok" }]
  }
}

• Observed result after fix: The gateway turn completed with waitResult.status: "ok", produced the payload text delivery-proof-ok, delivered one QA-channel outbound message, and returned deliveryStatus.status: "sent" with per-payload status: "sent" and resultCount: 1.
• What was not tested: The public CLI proof command through the same QA gateway still times out in the CLI client's expectFinal/embedded-fallback path even though the equivalent gateway RPC completes and delivers. I am treating that as a separate CLI QA harness/client issue rather than part of this delivery-status projection.

This PR supersedes draft PRs #53961 and #57755 after #57843 was closed because that approach tried to extend delivery-result semantics on an API that maintainers consider basically deprecated. Instead, this projects the newer sendDurableMessageBatch result model into deliverAgentCommandResult and openclaw agent --json --deliver output.