openclaw - 💡(How to fix) Fix Allow plugins to take over dispatch via before_dispatch without core marking inbound as completed

Affected version: openclaw 2026.5.27 (observed since 2026.5.18)

Context

I'm building a plugin (inbound-persistence) that persists every inbound WhatsApp message into a SQLite queue with per-sender FIFO semantics. The goal: serialize dispatch per peer so that 3 messages arriving in a 5-second window from the same sender are processed one at a time and the agent's responses arrive in the same order the user typed them.

Problem

The before_dispatch hook is exposed (see hook-types.d.ts), but if a plugin returns { handled: true } from it, the core treats the inbound as fully completed:

// dist/dispatch-BGwFKOyt.js around line 985-988
markIdle("plugin_binding_dispatch");
recordProcessed("completed", { reason: "plugin-bound-handled" });
commitInboundDedupeIfClaimed();
return attachSourceReplyDeliveryMode({...});

After this, any attempt by the plugin to re-dispatch the same msgId is silently swallowed by the inbound-dedupe layer. There is no way to say "I'm taking ownership, defer this, I'll re-inject it through the runtime later" without losing the message.

Expected behavior

A plugin should be able to defer dispatch — keep the message claimable, not commit dedupe — so that the plugin can later call the runtime's inject API on its own schedule.

Proposed solution (minimally invasive)

Extend the before_dispatch return contract with a new flag:

type BeforeDispatchResult = {
  handled?: boolean;
  takeover?: boolean;   // NEW
};

When { handled: true, takeover: true } is returned:

• Skip recordProcessed("completed", ...)
• Skip commitInboundDedupeIfClaimed()
• Keep the inbound in claimed state
• Expose a runtime API the plugin can call when ready: runtime.releaseTakeover(msgId, { redispatch: true })

The current behavior ({ handled: true } alone) stays unchanged for backwards compatibility.

Why this matters

Without it, plugins cannot implement:

• FIFO-per-sender message ordering
• Rate-limited agent calls per peer
• Priority queues across channels
• Any "deferred dispatch" pattern

Currently the only workarounds are (a) forking openclaw, (b) patching dist/*.js in place (lost on npm update), or (c) routing through an external broker that bypasses openclaw's channels entirely — all of which are significantly worse than the proposed flag.

Repro

1. Install openclaw 2026.5.27
2. Write a plugin with a before_dispatch handler that returns { handled: true }
3. From the same handler, try to call any runtime dispatch API to re-inject the same message a few seconds later
4. Observe: the re-dispatch is silently dropped by the inbound-dedupe layer

I have a complete failed attempt (plugin-side workaround code + post-mortem notes from 2026-05-28) I can share if useful — happy to provide it on request.

Environment

• openclaw 2026.5.27
• Ubuntu 24.04, node 22.22.2
• Use case: WhatsApp channel via Baileys, ~300+ inbounds/week, mix of groups + DMs