@rubytech/taskmaster 1.16.2 → 1.17.0

package/dist/gateway/server-methods-list.js

@@ -95,6 +95,12 @@ const BASE_METHODS = [
     "chat.history",
     "chat.abort",
     "chat.send",
+    // WhatsApp conversation browser
+    "whatsapp.conversations",
+    "whatsapp.messages",
+    "whatsapp.groupInfo",
+    "whatsapp.setActivation",
+    "whatsapp.sendMessage",
 ];
 export function listGatewayMethods() {
     const channelMethods = listChannelPlugins().flatMap((plugin) => plugin.gatewayMethods ?? []);

package/dist/gateway/server-methods.js

@@ -40,6 +40,7 @@ import { wifiHandlers } from "./server-methods/wifi.js";
 import { workspacesHandlers } from "./server-methods/workspaces.js";
 import { brandHandlers } from "./server-methods/brand.js";
 import { businessHandlers } from "./server-methods/business.js";
+import { whatsappConversationsHandlers } from "./server-methods/whatsapp-conversations.js";
 const ADMIN_SCOPE = "operator.admin";
 const READ_SCOPE = "operator.read";
 const WRITE_SCOPE = "operator.write";
@@ -109,6 +110,9 @@ const READ_METHODS = new Set([
     "memory.audit",
     "qr.generate",
     "business.openingHours.get",
+    "whatsapp.conversations",
+    "whatsapp.messages",
+    "whatsapp.groupInfo",
 ]);
 const WRITE_METHODS = new Set([
     "send",
@@ -124,6 +128,8 @@ const WRITE_METHODS = new Set([
     "node.invoke",
     "chat.send",
     "chat.abort",
+    "whatsapp.setActivation",
+    "whatsapp.sendMessage",
 ]);
 function authorizeGatewayMethod(method, client) {
     // Access methods bypass all scope checks — needed before PIN login
@@ -250,6 +256,7 @@ export const coreGatewayHandlers = {
     ...networkHandlers,
     ...tailscaleHandlers,
     ...wifiHandlers,
+    ...whatsappConversationsHandlers,
 };
 export async function handleGatewayRequest(opts) {
     const { req, respond, client, isWebchatConnect, context } = opts;

package/dist/gateway/server.impl.js

@@ -475,11 +475,13 @@ export async function startGatewayServer(port = 18789, opts = {}) {
         if (!bundledSkillsDir)
             return;
         try {
+            const workspaceIds = Object.keys(cfgAtStart.workspaces ?? {});
+            const accountIds = workspaceIds.length > 0 ? workspaceIds : [DEFAULT_ACCOUNT_ID];
             const seeded = await seedPreloadedCronJobs({
                 bundledSkillsDir,
                 trackerPath: DEFAULT_SEED_TRACKER_PATH,
                 cronService: cron,
-                defaultAccountId: DEFAULT_ACCOUNT_ID,
+                accountIds,
             });
             if (seeded > 0) {
                 logCron.info(`cron: seeded ${seeded} preloaded job(s)`);

package/dist/gateway/sessions-patch.js

@@ -274,7 +274,7 @@ export async function applySessionsPatchToStore(params) {
         else if (raw !== undefined) {
             const normalized = normalizeGroupActivation(String(raw));
             if (!normalized) {
-                return invalid('invalid groupActivation (use "mention"|"always")');
+                return invalid('invalid groupActivation (use "mention"|"always"|"off")');
             }
             next.groupActivation = normalized;
         }

package/dist/hooks/bundled/ride-dispatch/HOOK.md

@@ -7,7 +7,7 @@ metadata:
     "taskmaster":
       {
         "emoji": "🚕",
-        "events": ["memory:add", "message:inbound"],
+        "events": ["memory:add", "message:before-dispatch"],
         "requires": { "config": ["workspace.dir"] },
         "install": [{ "id": "bundled", "kind": "bundled", "label": "Bundled with Taskmaster" }],
       },
@@ -28,13 +28,13 @@ When the public agent writes a file matching `shared/dispatch/{jobId}-{phase}.md
 2. **Dispatches to admin agent** in a session scoped to the booking (`ride-{jobId}`)
 3. **Admin agent autonomously processes** — contacts drivers, generates payment links, or finalises bookings
 
-### Driver Replies (message:inbound)
+### Driver Replies (message:before-dispatch)
 
-When a driver replies on WhatsApp (routed to the public agent's DM session):
+Before a WhatsApp DM is dispatched to the public agent's LLM:
 
 1. **Checks the active negotiation index** at `shared/active-negotiations/{phone}.md`
-2. **If the driver has an active negotiation**, dispatches their message to the admin's ride session for that job
-3. **If no active negotiation**, ignores the message (normal public agent handling)
+2. **If the driver has an active negotiation**, sets `event.suppress = true` and dispatches the reply to the admin's ride session — the public agent never sees the message
+3. **If no active negotiation**, does nothing — the message proceeds normally to the public agent
 
 ## Why This Exists
 
@@ -44,7 +44,8 @@ The public agent must not have `contact_lookup` or `message` tools — exposing
 
 - Only fires for **Beagle Zanzibar agents** (detected by `beagle` in agent ID)
 - **Deduplicates** — same dispatch file within 30 seconds is ignored
-- **Non-blocking** — dispatch is fire-and-forget so neither agent's reply is delayed
+- **Driver suppression** — driver replies set `event.suppress = true` so the public agent's LLM is never invoked for driver messages
+- **Non-blocking** — admin dispatch is fire-and-forget after suppression is set
 - Admin agent uses `contact_lookup` → `message` → `memory_write` for driver outreach
 - Admin agent uses `message` to inject results (offers, payment links, driver details) into tourist's conversation via cross-agent echo
 

package/dist/hooks/bundled/ride-dispatch/handler.js

@@ -86,25 +86,54 @@ function extractPeerFromSessionKey(sessionKey) {
     return null;
 }
 /**
- * Find the admin agent ID from config.
- * The admin agent is the one marked `default: true`.
+ * Find the sibling admin agent for a given public agent.
+ *
+ * Convention: if the public agent is `beagle-zanzibar-public`, the admin is
+ * `beagle-zanzibar-admin`. Falls back to any admin agent that shares the same
+ * Beagle prefix, then the global default.
  */
-function findAdminAgentId(cfg) {
+function findSiblingAdminAgentId(cfg, publicAgentId) {
     const agents = cfg.agents?.list ?? [];
+    // Derive sibling: beagle-zanzibar-public → beagle-zanzibar-admin
+    if (publicAgentId.endsWith("-public")) {
+        const siblingId = publicAgentId.replace(/-public$/, "-admin");
+        if (agents.some((a) => a.id === siblingId))
+            return siblingId;
+    }
+    // Fallback: any admin agent sharing a Beagle prefix
+    const prefix = publicAgentId.replace(/-public$/, "");
+    const match = agents.find((a) => a.id?.startsWith(prefix) && a.id?.endsWith("-admin"));
+    if (match?.id)
+        return match.id;
+    // Last resort: global default
     const admin = agents.find((a) => a.default === true);
     if (admin?.id)
         return admin.id;
-    const defaultId = resolveDefaultAgentId(cfg);
-    return defaultId || null;
+    return resolveDefaultAgentId(cfg) || null;
+}
+/**
+ * Find the admin agent for a given account ID (used by payment webhooks
+ * where there's no public agent context). Convention: accountId
+ * "beagle-zanzibar" → admin agent "beagle-zanzibar-admin".
+ */
+function findAdminAgentForAccount(cfg, accountId) {
+    const agents = cfg.agents?.list ?? [];
+    const candidateId = `${accountId}-admin`;
+    if (agents.some((a) => a.id === candidateId))
+        return candidateId;
+    // Fallback: any admin agent whose ID starts with the account prefix
+    const match = agents.find((a) => a.id?.startsWith(accountId) && a.id?.endsWith("-admin"));
+    if (match?.id)
+        return match.id;
+    return resolveDefaultAgentId(cfg) || null;
 }
 /** Check if an agent ID belongs to a Beagle instance. */
 function isBeagleAgent(agentId) {
     return Boolean(agentId && agentId.toLowerCase().includes("beagle"));
 }
-/** Check if an agent is the public (non-admin) agent. */
-function isPublicAgentConfig(cfg, agentId) {
-    const agent = cfg.agents?.list?.find((a) => a.id === agentId);
-    return agent?.default !== true;
+/** Check if an agent is a public (non-admin) agent by naming convention. */
+function isPublicAgent(agentId) {
+    return agentId.endsWith("-public");
 }
 /**
  * Read the active negotiation index file for a driver phone.
@@ -140,6 +169,7 @@ async function dispatchToAdmin(params) {
         agentId: adminAgentId,
         channel: "system",
         peer: { kind: "dm", id: `ride-${jobId.toLowerCase()}` },
+        dmScope: "per-peer",
     }).toLowerCase();
     const envelopeOptions = resolveEnvelopeFormatOptions(cfg);
     const envelope = formatInboundEnvelope({
@@ -189,7 +219,7 @@ async function dispatchToAdmin(params) {
 // ---------------------------------------------------------------------------
 // Build instruction text for each dispatch phase
 // ---------------------------------------------------------------------------
-function buildTripRequestInstruction(fields) {
+function buildTripRequestInstruction(fields, resolvedAccountId) {
     const jobId = fields.job_id ?? "UNKNOWN";
     const touristPhone = fields.tourist_phone ?? "unknown";
     const touristName = fields.tourist_name ?? "Tourist";
@@ -201,7 +231,7 @@ function buildTripRequestInstruction(fields) {
     const luggage = fields.luggage ?? "none";
     const specialRequests = fields.special_requests ?? "none";
     const fareEstimate = fields.fare_estimate ?? "unknown";
-    const accountId = fields.account_id ?? "default";
+    const accountId = resolvedAccountId;
     return (`[System: Ride Dispatch — Trip Request]\n\n` +
         `A tourist has requested a ride. Process this by contacting available drivers.\n\n` +
         `Job ID: ${jobId}\n` +
@@ -230,13 +260,13 @@ function buildTripRequestInstruction(fields) {
         `9. Message the tourist with up to 3 competing offers: fare, driver rating, vehicle type, estimated journey time\n` +
         `   Do NOT reveal driver name, phone, or plate — those are gated by payment\n`);
 }
-function buildBookingConfirmInstruction(fields) {
+function buildBookingConfirmInstruction(fields, resolvedAccountId) {
     const jobId = fields.job_id ?? "UNKNOWN";
     const touristPhone = fields.tourist_phone ?? "unknown";
     const driverName = fields.driver_name ?? "unknown";
     const driverPhone = fields.driver_phone ?? "unknown";
     const fare = fields.fare ?? "unknown";
-    const accountId = fields.account_id ?? "default";
+    const accountId = resolvedAccountId;
     return (`[System: Ride Dispatch — Booking Confirmation]\n\n` +
         `The tourist has selected a driver. Generate a Stripe payment link and send it.\n\n` +
         `Job ID: ${jobId}\n` +
@@ -290,8 +320,8 @@ async function handleMemoryAdd(event) {
         return;
     const jobId = match[1]; // e.g. BGL-0042
     const phase = match[2]; // trip-request | booking-confirm
-    // Dedup
-    const dedupKey = `dispatch:${relativePath}`;
+    // Dedup (use jobId+phase, not relativePath, since multiple watchers report different paths)
+    const dedupKey = `dispatch:${jobId}:${phase}`;
     if (isDuplicate(dedupKey))
         return;
     // Read the dispatch file
@@ -317,18 +347,21 @@ async function handleMemoryAdd(event) {
         console.warn("[ride-dispatch] Could not read config");
         return;
     }
-    const adminAgentId = findAdminAgentId(cfg);
+    const adminAgentId = findSiblingAdminAgentId(cfg, agentId);
     if (!adminAgentId) {
-        console.warn("[ride-dispatch] No admin agent found in config");
+        console.warn("[ride-dispatch] No admin agent found for public agent:", agentId);
         return;
     }
-    const accountId = fields.account_id ?? resolveAgentBoundAccountId(cfg, agentId, "whatsapp") ?? "default";
+    // Resolve account: binding first, then derive from agent ID prefix
+    // (beagle-zanzibar-public → beagle-zanzibar), which matches WhatsApp account naming.
+    const accountId = resolveAgentBoundAccountId(cfg, agentId, "whatsapp") ??
+        (agentId.replace(/-(public|admin)$/, "") || "default");
     let instruction;
     if (phase === "trip-request") {
-        instruction = buildTripRequestInstruction(fields);
+        instruction = buildTripRequestInstruction(fields, accountId);
     }
     else if (phase === "booking-confirm") {
-        instruction = buildBookingConfirmInstruction(fields);
+        instruction = buildBookingConfirmInstruction(fields, accountId);
     }
     else {
         return;
@@ -347,7 +380,13 @@ async function handleMemoryAdd(event) {
     });
 }
 /**
- * Handle message:inbound events — driver replies routed to the public agent.
+ * Handle message:before-dispatch events — intercept driver replies before they
+ * reach the public agent's LLM.
+ *
+ * Sets event.suppress = true when the sender is a driver in active negotiation,
+ * then dispatches the reply to the admin agent's ride session instead.
+ * Because this handler is awaited by the caller, suppress takes effect before
+ * processForRoute is invoked.
  */
 async function handleDriverReply(event) {
     const context = event.context || {};
@@ -359,7 +398,7 @@ async function handleDriverReply(event) {
     const agentId = resolveAgentIdFromSessionKey(event.sessionKey);
     if (!agentId || !isBeagleAgent(agentId))
         return;
-    if (!isPublicAgentConfig(cfg, agentId))
+    if (!isPublicAgent(agentId))
         return;
     // Extract sender phone from session key
     const senderPhone = extractPeerFromSessionKey(event.sessionKey);
@@ -367,18 +406,22 @@ async function handleDriverReply(event) {
         return;
     // Resolve workspace dir from the agent config to find active-negotiations
     const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
-    // Check active negotiation index
+    // Check active negotiation index (synchronous — must complete before we return
+    // so that event.suppress is set before the caller checks it)
     const jobId = readActiveNegotiation(workspaceDir, senderPhone);
     if (!jobId)
-        return; // Not a driver in active negotiation
+        return; // Not a driver in active negotiation — let public agent handle it
+    // Suppress delivery to the public agent before doing anything else
+    event.suppress = true;
     // Dedup
     const dedupKey = `reply:${senderPhone}:${Date.now().toString().slice(0, -4)}`; // ~10s granularity
     if (isDuplicate(dedupKey))
         return;
-    const adminAgentId = findAdminAgentId(cfg);
+    const adminAgentId = findSiblingAdminAgentId(cfg, agentId);
     if (!adminAgentId)
         return;
-    const accountId = resolveAgentBoundAccountId(cfg, agentId, "whatsapp") ?? "default";
+    const accountId = resolveAgentBoundAccountId(cfg, agentId, "whatsapp") ??
+        (agentId.replace(/-(public|admin)$/, "") || "default");
     const instruction = `[System: Ride Dispatch — Driver Reply]\n\n` +
         `A driver has replied regarding job ${jobId}.\n\n` +
         `Driver phone: ${senderPhone}\n` +
@@ -387,7 +430,7 @@ async function handleDriverReply(event) {
         `If this is a fare quote, note it and compile offers when ready.\n` +
         `If the driver is declining, update their status and active negotiation index.\n`;
     console.log(`[ride-dispatch] Driver reply from ${senderPhone} for ${jobId}, dispatching to admin agent "${adminAgentId}"`);
-    // Fire and forget
+    // Fire and forget — suppress is already set, caller will skip processForRoute
     dispatchToAdmin({
         cfg,
         adminAgentId,
@@ -420,9 +463,11 @@ export async function dispatchPaymentConfirmed(params) {
         console.warn("[ride-dispatch] Could not read config for payment dispatch");
         return;
     }
-    const adminAgentId = findAdminAgentId(cfg);
+    // Payment webhooks don't have a public agent context. Derive admin from
+    // the accountId (e.g. "beagle-zanzibar" → "beagle-zanzibar-admin").
+    const adminAgentId = findAdminAgentForAccount(cfg, accountId);
     if (!adminAgentId) {
-        console.warn("[ride-dispatch] No admin agent for payment dispatch");
+        console.warn("[ride-dispatch] No admin agent for payment dispatch, accountId:", accountId);
         return;
     }
     const instruction = buildPaymentConfirmedInstruction({ bookingId, touristPhone, accountId });
@@ -443,7 +488,7 @@ const handleRideDispatch = async (event) => {
     if (event.type === "memory" && event.action === "add") {
         await handleMemoryAdd(event);
     }
-    else if (event.type === "message" && event.action === "inbound") {
+    else if (event.type === "message" && event.action === "before-dispatch") {
         await handleDriverReply(event);
     }
 };

package/dist/memory/manager.js

@@ -538,7 +538,7 @@ export class MemoryIndexManager {
         return this.syncing;
     }
     async readFile(params) {
-        const relPath = ensureMemoryPrefix(normalizeGroupIdInMemoryPath(normalizePhoneInMemoryPath(normalizeRelPath(params.relPath))));
+        const relPath = normalizeGroupIdInMemoryPath(normalizePhoneInMemoryPath(ensureMemoryPrefix(normalizeRelPath(params.relPath))));
         if (!relPath || !isMemoryPath(relPath)) {
             throw new Error(relPath
                 ? `invalid path "${relPath}" — must start with "memory/" (e.g. "memory/admin/file.md")`
@@ -578,7 +578,7 @@ export class MemoryIndexManager {
      * matching the session's scope configuration.
      */
     async writeFile(params) {
-        const relPath = ensureMemoryPrefix(normalizeGroupIdInMemoryPath(normalizePhoneInMemoryPath(normalizeRelPath(params.relPath))));
+        const relPath = normalizeGroupIdInMemoryPath(normalizePhoneInMemoryPath(ensureMemoryPrefix(normalizeRelPath(params.relPath))));
         if (!relPath || !isMemoryPath(relPath)) {
             throw new Error(relPath
                 ? `invalid path "${relPath}" — must start with "memory/" (e.g. "memory/admin/file.md")`
@@ -626,7 +626,7 @@ export class MemoryIndexManager {
         let relPath;
         if (params.destFolder) {
             // Explicit folder — use as-is (scope checking enforces access)
-            relPath = normalizeGroupIdInMemoryPath(normalizePhoneInMemoryPath(`${params.destFolder}/${params.destFilename}`));
+            relPath = normalizeGroupIdInMemoryPath(normalizePhoneInMemoryPath(ensureMemoryPrefix(`${params.destFolder}/${params.destFilename}`)));
         }
         else {
             // Default: memory/users/{peer}/media/{filename}

package/dist/tui/tui-command-handlers.js

@@ -363,7 +363,7 @@ export function createCommandHandlers(context) {
                 try {
                     await client.patchSession({
                         key: state.currentSessionKey,
-                        groupActivation: args === "always" ? "always" : "mention",
+                        groupActivation: args === "always" ? "always" : args === "off" ? "off" : "mention",
                     });
                     chatLog.addSystem(`activation set to ${args}`);
                     await refreshSessionInfo();

package/dist/web/auto-reply/monitor/group-activation.js

@@ -1,6 +1,5 @@
-import { normalizeGroupActivation } from "../../../auto-reply/group-activation.js";
-import { resolveChannelGroupPolicy, resolveChannelGroupRequireMention, } from "../../../config/group-policy.js";
-import { loadSessionStore, resolveGroupSessionKey, resolveStorePath, } from "../../../config/sessions.js";
+import { resolveChannelGroupActivation, resolveChannelGroupPolicy, resolveChannelGroupRequireMention, } from "../../../config/group-policy.js";
+import { resolveGroupSessionKey } from "../../../config/sessions.js";
 export function resolveGroupPolicyFor(cfg, conversationId) {
     const groupId = resolveGroupSessionKey({
         From: conversationId,
@@ -26,12 +25,15 @@ export function resolveGroupRequireMentionFor(cfg, conversationId) {
     });
 }
 export function resolveGroupActivationFor(params) {
-    const storePath = resolveStorePath(params.cfg.session?.store, {
-        agentId: params.agentId,
+    const groupId = resolveGroupSessionKey({
+        From: params.conversationId,
+        ChatType: "group",
+        Provider: "whatsapp",
+    })?.id;
+    const configActivation = resolveChannelGroupActivation({
+        cfg: params.cfg,
+        channel: "whatsapp",
+        groupId: groupId ?? params.conversationId,
     });
-    const store = loadSessionStore(storePath);
-    const entry = store[params.sessionKey];
-    const requireMention = resolveGroupRequireMentionFor(params.cfg, params.conversationId);
-    const defaultActivation = requireMention === false ? "always" : "mention";
-    return normalizeGroupActivation(entry?.groupActivation) ?? defaultActivation;
+    return configActivation ?? "mention";
 }

package/dist/web/auto-reply/monitor/group-gating.js

@@ -58,6 +58,10 @@ export function applyGroupGating(params) {
         sessionKey: params.sessionKey,
         conversationId: params.conversationId,
     });
+    if (activation === "off") {
+        params.logVerbose(`Group ${params.conversationId} activation=off, ignoring`);
+        return { shouldProcess: false };
+    }
     const requireMention = activation !== "always";
     const selfJid = params.msg.selfJid?.replace(/:\\d+/, "");
     const replySenderJid = params.msg.replyToSenderJid?.replace(/:\\d+/, "");
@@ -76,8 +80,25 @@ export function applyGroupGating(params) {
     });
     params.msg.wasMentioned = mentionGate.effectiveWasMentioned;
     if (!shouldBypassMention && requireMention && mentionGate.shouldSkip) {
-        params.logVerbose(`Group message (no mention) — agent will process silently in ${params.conversationId}: ${params.msg.body}`);
-        return { shouldProcess: true, mentionGated: true };
+        params.logVerbose(`Group message (no mention) — accumulating context only in ${params.conversationId}: ${params.msg.body}`);
+        // Record the un-mentioned message in the group history buffer so it is
+        // available as context when the bot is eventually @mentioned.
+        const sender = params.msg.senderName && params.msg.senderE164
+            ? `${params.msg.senderName} (${params.msg.senderE164})`
+            : (params.msg.senderName ?? params.msg.senderE164 ?? "Unknown");
+        recordPendingHistoryEntryIfEnabled({
+            historyMap: params.groupHistories,
+            historyKey: params.groupHistoryKey,
+            limit: params.groupHistoryLimit,
+            entry: {
+                sender,
+                body: params.msg.body,
+                timestamp: params.msg.timestamp,
+                id: params.msg.id,
+                senderJid: params.msg.senderJid,
+            },
+        });
+        return { shouldProcess: true, contextOnly: true };
     }
     return { shouldProcess: true };
 }

package/dist/web/auto-reply/monitor/on-message.js

@@ -1,3 +1,4 @@
+import { loadConfig } from "../../../config/config.js";
 import { logVerbose } from "../../../globals.js";
 import { isLicensed } from "../../../license/state.js";
 import { createInternalHookEvent, triggerInternalHook } from "../../../hooks/internal-hooks.js";
@@ -29,7 +30,7 @@ export function createWebOnMessageHandler(params) {
         buildCombinedEchoKey: params.echoTracker.buildCombinedKey,
         groupHistory: opts?.groupHistory,
         suppressGroupHistoryClear: opts?.suppressGroupHistoryClear,
-        suppressDelivery: opts?.suppressDelivery,
+        contextOnly: opts?.contextOnly,
     });
     return async (msg) => {
         // Block all message processing when unlicensed.
@@ -40,8 +41,12 @@ export function createWebOnMessageHandler(params) {
         logVerbose(`[on-message] processing message from=${msg.from} body=${msg.body?.slice(0, 60)}`);
         const conversationId = msg.conversationId ?? msg.from;
         const peerId = resolvePeerId(msg);
+        // Read config fresh for routing so that binding changes (e.g. admin revocation)
+        // take effect on the next message without requiring a channel restart.
+        // `loadConfig()` has a 200ms cache so this is cheap under normal message rates.
+        const routingCfg = loadConfig();
         const route = resolveAgentRoute({
-            cfg: params.cfg,
+            cfg: routingCfg,
             channel: "whatsapp",
             accountId: msg.accountId,
             peer: {
@@ -67,7 +72,7 @@ export function createWebOnMessageHandler(params) {
             params.echoTracker.forget(msg.body);
             return;
         }
-        let mentionGated = false;
+        let contextOnly = false;
         if (msg.chatType === "group") {
             const metaCtx = {
                 From: msg.from,
@@ -132,7 +137,7 @@ export function createWebOnMessageHandler(params) {
                 }
                 return;
             }
-            mentionGated = gating.mentionGated ?? false;
+            contextOnly = gating.contextOnly ?? false;
         }
         else {
             // Ensure `peerId` for DMs is stable and stored as E.164 when possible.
@@ -153,8 +158,25 @@ export function createWebOnMessageHandler(params) {
         })) {
             return;
         }
+        // Fire message:before-dispatch awaited so hooks can suppress processing.
+        // Unlike message:inbound (fire-and-forget inside processMessage), this is
+        // awaited here, allowing a handler to set event.suppress = true before
+        // the public agent's LLM is invoked. Used by ride-dispatch to intercept
+        // driver replies and route them to the admin agent instead.
+        const beforeDispatch = createInternalHookEvent("message", "before-dispatch", route.sessionKey, {
+            from: msg.senderE164 ?? msg.from,
+            to: msg.to,
+            text: msg.body,
+            chatType: msg.chatType,
+            agentId: route.agentId,
+            channel: "whatsapp",
+            cfg: params.cfg,
+        });
+        await triggerInternalHook(beforeDispatch);
+        if (beforeDispatch.suppress)
+            return;
         await processForRoute(msg, route, groupHistoryKey, {
-            suppressDelivery: mentionGated || undefined,
+            contextOnly: contextOnly || undefined,
         });
     };
 }