@clawling/clawchat-plugin-openclaw 2026.10.9-2 → 2026.10.9-4

package/src/tools.ts

@@ -22,8 +22,10 @@ import {
   getClawChatStore,
   makeOwnerProfilePersister,
   type ClawChatStore,
+  type SeenMessage,
 } from "./storage.ts";
-import { sendOpenclawClawlingMentionMessage, sendOpenclawClawlingReaction } from "./outbound.ts";
+import { isPlausibleMessageId, sendOpenclawClawlingMentionMessage, sendOpenclawClawlingReaction } from "./outbound.ts";
+import { isValidChatId } from "./ws-client.ts";
 import {
   getOpenclawClawlingClient,
 } from "./runtime.ts";
@@ -36,6 +38,14 @@ import {
   writeClawChatMemoryBody,
   type ClawChatMemoryTargetType,
 } from "./clawchat-memory.ts";
+import {
+  canReadMemory,
+  memoryScopeNote,
+  memoryScopeRefusal,
+  resolveMemoryScope,
+  type MemoryScope,
+} from "./memory-scope.ts";
+import { clawChatSessionAccountId, NON_OWNER_TOOL_ALLOWLIST, normalizeToolChatId } from "./turn-boundary.ts";
 import {
   pullGroupMetadata,
   pullOwnerMetadata,
@@ -215,6 +225,16 @@ function validationError(message: string) {
   return jsonResponse({ error: "validation", message });
 }
 
+function reactionBlockedError(chatId: string, reason: "invalid_chat_id" | "chat_rejected_by_server") {
+  return jsonResponse({
+    error: "send_blocked",
+    reason,
+    message: reason === "invalid_chat_id"
+      ? `clawchat-plugin-openclaw: "${chatId}" is not a ClawChat chat id (expected cnv_…); the reaction was not sent`
+      : "clawchat-plugin-openclaw: this chat was rejected by the server; the reaction was not sent",
+  });
+}
+
 function genericError(err: unknown) {
   return jsonResponse({
     error: "unknown",
@@ -254,14 +274,26 @@ const MEMORY_READ_MAX_LIMIT = 100_000;
 type ToolStore = Pick<
   ClawChatStore,
   "recordToolCall"
->;
+> &
+  Partial<Pick<
+    ClawChatStore,
+    | "lookupActivationIdentity"
+    | "listRecentGroupMessages"
+    | "findSeenMessageInChat"
+    | "findStoredChatId"
+    | "claimMessageOnce"
+    | "markMessageAcknowledged"
+  >>;
 
 function toolDescription(...parts: string[]): string {
   return `${parts.join("")} ${DIRECT_TOOL_GUARD}`;
 }
 
+const MEMORY_SCOPE_DESCRIPTION =
+  "In a non-owner direct chat only that person's note is readable; in a group only that group's note and its members' notes are readable. owner.md is readable only in the owner's direct chat. Replace, edit and metadata operations require a readable target; append may add facts to any target without revealing existing content.";
+
 function memoryToolDescription(...parts: string[]): string {
-  return parts.join("");
+  return `${parts.join("")} ${MEMORY_SCOPE_DESCRIPTION}`;
 }
 
 function inferMimeFromPath(filePath: string): string {
@@ -313,6 +345,13 @@ function planMomentImages(
   return { ok: true, entries };
 }
 
+const MESSAGE_ID_ECHO_LIMIT = 64;
+
+function notAMessageIdMessage(field: string, value: string): string {
+  const shown = value.length > MESSAGE_ID_ECHO_LIMIT ? `${value.slice(0, MESSAGE_ID_ECHO_LIMIT)}…` : value;
+  return `clawchat-plugin-openclaw: ${field} "${shown}" is not a message in this chat; use the real message id from this chat's message metadata (e.g. msg-…), or omit it`;
+}
+
 function validateMentionMessageParams(params: unknown):
   | { ok: true; params: ClawchatMentionMessageParams }
   | { ok: false; message: string } {
@@ -320,7 +359,8 @@ function validateMentionMessageParams(params: unknown):
     return { ok: false, message: "clawchat-plugin-openclaw: params are required" };
   }
   const p = params as Partial<ClawchatMentionMessageParams>;
-  if (typeof p.chatId !== "string" || !p.chatId.trim()) {
+  const chatId = normalizeToolChatId(p.chatId);
+  if (!chatId) {
     return { ok: false, message: "clawchat-plugin-openclaw: chatId is required" };
   }
   if (p.chatType !== undefined && p.chatType !== "group" && p.chatType !== "direct") {
@@ -356,11 +396,12 @@ function validateMentionMessageParams(params: unknown):
       ok: true,
       params: {
         ...p,
+        chatId,
         replyToMessageId,
       } as ClawchatMentionMessageParams,
     };
   }
-  return { ok: true, params: p as ClawchatMentionMessageParams };
+  return { ok: true, params: { ...p, chatId } as ClawchatMentionMessageParams };
 }
 
 /**
@@ -392,6 +433,48 @@ export function resolveOpenclawClawlingToolAccountId(ctx: OpenClawPluginToolCont
   return null;
 }
 
+/**
+ * True when the host says this tool call's run is a ClawChat run: every
+ * channel the trusted ctx names (`deliveryContext.channel`, `messageChannel`)
+ * is this channel, and at least one is present. Missing or foreign → false.
+ */
+export function isClawChatToolRun(ctx: OpenClawPluginToolContext): boolean {
+  const channels = [ctx.deliveryContext?.channel, ctx.messageChannel]
+    .map((channel) => (typeof channel === "string" ? channel.trim().toLowerCase() : ""))
+    .filter(Boolean);
+  return channels.length > 0 && channels.every((channel) => channel === CHANNEL_ID);
+}
+
+// Names this plugin registered through its wrapper below. The host-tool guard
+// lets an allowlisted `clawchat_*` name through only when it is in this set,
+// so another plugin's tool under a lookalike name is not trusted by prefix.
+const registeredClawChatToolNames = new Set<string>();
+
+/** Snapshot of the tool names this plugin registered; callers cannot mutate the record. */
+export function getRegisteredClawChatToolNames(): ReadonlySet<string> {
+  return new Set(registeredClawChatToolNames);
+}
+
+type RegistrableTool = Parameters<OpenClawPluginApi["registerTool"]>[0];
+type PluginTool = Exclude<RegistrableTool, (...args: never[]) => unknown>;
+
+// Host tool search (OpenClaw 2026.9.6+) hides every tool not marked
+// `catalogMode: "direct-only"` behind tool_search/tool_call, whose hook ctx has
+// no requester. The allowlisted tools stay directly callable so non-owner
+// turns keep the full hook ctx; older hosts ignore the field.
+function markDirectOnly(tool: PluginTool): PluginTool {
+  return Object.assign(tool, { catalogMode: "direct-only" as const });
+}
+
+function directOnlyTool(tool: RegistrableTool): RegistrableTool {
+  if (typeof tool !== "function") return markDirectOnly(tool);
+  return (ctx) => {
+    const resolved = tool(ctx);
+    if (Array.isArray(resolved)) return resolved.map(markDirectOnly);
+    return resolved ? markDirectOnly(resolved) : resolved;
+  };
+}
+
 export function registerOpenclawClawlingTools(
   api: OpenClawPluginApi,
   options: { store?: ToolStore | null } = {},
@@ -405,8 +488,14 @@ export function registerOpenclawClawlingTools(
   // the end is derived from what was actually registered, not hand-maintained.
   const registeredToolNames: string[] = [];
   const registerTool: OpenClawPluginApi["registerTool"] = (tool, opts) => {
-    if (opts?.name) registeredToolNames.push(opts.name);
-    api.registerTool(tool, opts);
+    const directOnly = Boolean(opts?.name && NON_OWNER_TOOL_ALLOWLIST.includes(opts.name));
+    api.registerTool(directOnly ? directOnlyTool(tool) : tool, opts);
+    // Recorded only after registerTool returned without throwing (the SDK
+    // returns void, so host-side duplicate rejection is not observable here).
+    if (opts?.name) {
+      registeredToolNames.push(opts.name);
+      registeredClawChatToolNames.add(opts.name);
+    }
   };
 
   // Re-resolve at call time so config reloads pick up new tokens / baseUrl.
@@ -428,6 +517,94 @@ export function registerOpenclawClawlingTools(
     }
   }
 
+  let warnedMessageIdStore = false;
+  /**
+   * An explicit message id (react target, mention reply) must be one the
+   * plugin has stored for this chat; the stored chat id and message id (their
+   * real case) are what gets sent. When the store cannot answer, fall back to
+   * the message-id shape check rather than block every call, keep the ids as
+   * given, and warn once without ids or arguments.
+   */
+  function resolveExplicitMessageId(input: {
+    field: "targetMessageId" | "replyToMessageId";
+    value: string;
+    accountId: string;
+    chatId: string;
+  }): { ok: true; chatId: string; messageId: string } | { ok: false; error: ReturnType<typeof validationError> } {
+    let seen: SeenMessage | false | null = null;
+    try {
+      const store = resolveStore();
+      seen = store?.findSeenMessageInChat
+        ? store.findSeenMessageInChat({
+            platform: "openclaw",
+            accountId: input.accountId,
+            chatId: input.chatId,
+            messageId: input.value,
+          })
+        : null;
+    } catch {
+      seen = null;
+    }
+    if (seen) return { ok: true, chatId: seen.chatId, messageId: seen.messageId };
+    if (seen === null) {
+      if (!warnedMessageIdStore) {
+        warnedMessageIdStore = true;
+        api.logger.warn(
+          "clawchat-plugin-openclaw: message-id store check unavailable; falling back to the message-id shape check",
+        );
+      }
+      if (isPlausibleMessageId(input.value)) return { ok: true, chatId: input.chatId, messageId: input.value };
+    }
+    return { ok: false, error: validationError(notAMessageIdMessage(input.field, input.value)) };
+  }
+
+  /**
+   * The chat id in the case the ledger already stores for it, so a send, its
+   * terminal marker and its ledger row all name the chat as the inbound path
+   * does (a second case splits the chat for memory scope). The id as given
+   * when the ledger has no row for the chat or cannot answer.
+   */
+  function storedChatIdCase(accountId: string, chatId: string): string {
+    try {
+      const stored = resolveStore()?.findStoredChatId?.({ platform: "openclaw", accountId, chatId });
+      return typeof stored === "string" && stored ? stored : chatId;
+    } catch {
+      return chatId;
+    }
+  }
+
+  /**
+   * Best-effort ledger row for a sent mention, so its id can be reacted to or
+   * quoted later. Written after the ack; a store failure never affects the send.
+   */
+  function recordMentionSent(input: { accountId: string; chatId: string; messageId: string; text: string; acceptedAt?: number }): void {
+    try {
+      const store = resolveStore();
+      const claimed = store?.claimMessageOnce?.({
+        platform: "openclaw",
+        accountId: input.accountId,
+        kind: "message",
+        direction: "outbound",
+        eventType: "message.send",
+        chatId: input.chatId,
+        messageId: input.messageId,
+        text: input.text,
+        raw: { mode: "tool-mention" },
+      });
+      if (claimed !== true) return;
+      store?.markMessageAcknowledged?.({
+        accountId: input.accountId,
+        kind: "message",
+        direction: "outbound",
+        messageId: input.messageId,
+        protocolMessageId: input.messageId,
+        ackedAt: input.acceptedAt ?? Date.now(),
+      });
+    } catch {
+      // Diagnostics only; the mention has already been sent.
+    }
+  }
+
   function detailsError(details: unknown): string | null {
     if (!details || typeof details !== "object") return null;
     const raw = details as { error?: unknown; message?: unknown };
@@ -636,6 +813,48 @@ export function registerOpenclawClawlingTools(
     return /Unsafe clawchat memory|Resolved clawchat memory path is outside root/i.test(message);
   }
 
+  // One warning per failure class per registration; never tool arguments.
+  const scopeWarnings = new Set<string>();
+  function warnScopeOnce(failure: string): void {
+    if (scopeWarnings.has(failure)) return;
+    scopeWarnings.add(failure);
+    try {
+      api.logger.warn(`clawchat-plugin-openclaw: memory scope ${failure}; no additional notes readable`);
+    } catch {
+      // Logging must not widen or break the (restrictive) scope.
+    }
+  }
+
+  /**
+   * Scope of the conversation behind this call, resolved fresh on every call
+   * (activation and group membership can change between calls). The account
+   * comes from the direct session key and/or the trusted tool context; a
+   * missing or contradictory account reads nothing.
+   */
+  async function memoryScopeFor(ctx: OpenClawPluginToolContext, root: string): Promise<MemoryScope> {
+    const sessionAccount = clawChatSessionAccountId(ctx.sessionKey) ?? null;
+    const contextAccount = resolveOpenclawClawlingToolAccountId(ctx);
+    if (sessionAccount && contextAccount && sessionAccount !== contextAccount) {
+      warnScopeOnce("account-mismatch");
+      return { kind: "unknown", chatId: "", members: new Set() };
+    }
+    const accountId = sessionAccount ?? contextAccount;
+    if (!accountId) return { kind: "unknown", chatId: "", members: new Set() };
+    const delivery = ctx.deliveryContext;
+    return resolveMemoryScope({
+      root,
+      ctx: {
+        sessionKey: ctx.sessionKey,
+        requesterSenderId: ctx.requesterSenderId,
+        deliveryContext: delivery?.channel === CHANNEL_ID ? { to: delivery.to } : undefined,
+      },
+      accountId,
+      configOwnerUserId: resolveCurrent(accountId).ownerUserId,
+      store: resolveStore(),
+      warn: warnScopeOnce,
+    });
+  }
+
   function memoryToolError(err: unknown) {
     if (err instanceof ClawlingApiError) return apiError(err);
     const message = err instanceof Error ? err.message : String(err);
@@ -665,13 +884,14 @@ export function registerOpenclawClawlingTools(
           }
           try {
             const p = params as ClawchatMemorySearchParams;
-            return jsonResponse(
-              await searchClawChatMemory(root, {
-                query: p.query,
-                targetTypes: p.targetTypes,
-                maxResults: p.maxResults,
-              }),
-            );
+            const scope = await memoryScopeFor(ctx, root);
+            const result = await searchClawChatMemory(root, {
+              query: p.query,
+              targetTypes: p.targetTypes,
+              maxResults: p.maxResults,
+            }, { readable: (target) => canReadMemory(scope, target) });
+            const scopeNote = memoryScopeNote(scope);
+            return jsonResponse({ ...result, ...(scopeNote ? { scopeNote } : {}) });
           } catch (err) {
             return memoryToolError(err);
           }
@@ -700,8 +920,11 @@ export function registerOpenclawClawlingTools(
             const p = params as ClawchatMemoryReadParams;
             const targetError = validateTarget(root, p);
             if (targetError) return memoryToolError(new Error(targetError));
+            const target = targetFromParams(p);
+            const scope = await memoryScopeFor(ctx, root);
+            if (!canReadMemory(scope, target)) return jsonResponse(memoryScopeRefusal(scope, target));
             const { offset, limit } = normalizeReadBounds(p);
-            const file = await readClawChatMemoryFile(root, targetFromParams(p));
+            const file = await readClawChatMemoryFile(root, target);
             if (!file.exists) {
               return jsonResponse({
                 exists: false,
@@ -751,13 +974,23 @@ export function registerOpenclawClawlingTools(
           if (!root) {
             return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
           }
+          const p = params as ClawchatMemoryWriteParams;
+          let readable = false;
           try {
-            const p = params as ClawchatMemoryWriteParams;
             const targetError = validateTarget(root, p);
             if (targetError) return memoryToolError(new Error(targetError));
-            await writeClawChatMemoryBody(root, targetFromParams(p), p.mode, p.content);
+            const target = targetFromParams(p);
+            const scope = await memoryScopeFor(ctx, root);
+            readable = canReadMemory(scope, target);
+            // Replacing wipes what is there; append may go to any note.
+            if (p.mode !== "append" && !readable) return jsonResponse(memoryScopeRefusal(scope, target));
+            await writeClawChatMemoryBody(root, target, p.mode, p.content);
             return jsonResponse({ ok: true, targetType: p.targetType, targetId: p.targetId, mode: p.mode });
           } catch (err) {
+            // An unreadable note's failure text could reveal its state.
+            if (p.mode === "append" && !readable) {
+              return jsonResponse({ error: "memory_write_failed", message: "The memory append could not be completed." });
+            }
             return memoryToolError(err);
           }
         },
@@ -787,7 +1020,10 @@ export function registerOpenclawClawlingTools(
             const p = params as ClawchatMemoryEditParams;
             const targetError = validateTarget(root, p);
             if (targetError) return memoryToolError(new Error(targetError));
-            await editClawChatMemoryBody(root, targetFromParams(p), p.oldText, p.newText);
+            const target = targetFromParams(p);
+            const scope = await memoryScopeFor(ctx, root);
+            if (!canReadMemory(scope, target)) return jsonResponse(memoryScopeRefusal(scope, target));
+            await editClawChatMemoryBody(root, target, p.oldText, p.newText);
             return jsonResponse({ ok: true, targetType: p.targetType, targetId: p.targetId });
           } catch (err) {
             return memoryToolError(err);
@@ -818,12 +1054,15 @@ export function registerOpenclawClawlingTools(
             if (!root) {
               return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
             }
-            const built = buildClient(accountId);
-            if (!built.ok) return built.error;
             try {
               const p = params as ClawchatMetadataSyncParams;
               const targetError = validateTarget(root, p);
               if (targetError) return memoryToolError(new Error(targetError));
+              const target = targetFromParams(p);
+              const scope = await memoryScopeFor(ctx, root);
+              if (!canReadMemory(scope, target)) return jsonResponse(memoryScopeRefusal(scope, target));
+              const built = buildClient(accountId);
+              if (!built.ok) return built.error;
               const account = resolveCurrent(accountId);
               if (p.direction === "push") {
                 if (!Array.isArray(p.fields) || p.fields.length === 0) {
@@ -899,14 +1138,17 @@ export function registerOpenclawClawlingTools(
             if (!root) {
               return validationError("clawchat-plugin-openclaw: OpenClaw workspaceDir is required");
             }
-            const built = buildClient(accountId);
-            if (!built.ok) return built.error;
             try {
               const p = params as ClawchatMetadataUpdateParams;
               const targetError = validateTarget(root, p);
               if (targetError) return memoryToolError(new Error(targetError));
               const patchError = validateMetadataUpdatePatch(p);
               if (patchError) return validationError(patchError);
+              const target = targetFromParams(p);
+              const scope = await memoryScopeFor(ctx, root);
+              if (!canReadMemory(scope, target)) return jsonResponse(memoryScopeRefusal(scope, target));
+              const built = buildClient(accountId);
+              if (!built.ok) return built.error;
               const account = resolveCurrent(accountId);
               if (p.targetType === "owner" && !account.agentId) {
                 return configError("clawchat-plugin-openclaw: agentId is required");
@@ -1175,7 +1417,7 @@ export function registerOpenclawClawlingTools(
             const built = buildClient(accountId);
             if (!built.ok) return built.error;
             try {
-              const data = await built.client.getConversation(p.conversationId);
+              const data = await built.client.getConversation(normalizeToolChatId(p.conversationId));
               return jsonResponse(data);
             } catch (err) {
               if (err instanceof ClawlingApiError) {
@@ -1245,7 +1487,7 @@ export function registerOpenclawClawlingTools(
             const built = buildClient(accountId);
             if (!built.ok) return built.error;
             try {
-              const data = await built.client.leaveConversation(p.conversationId);
+              const data = await built.client.leaveConversation(normalizeToolChatId(p.conversationId));
               return jsonResponse(data);
             } catch (err) {
               if (err instanceof ClawlingApiError) {
@@ -1280,7 +1522,7 @@ export function registerOpenclawClawlingTools(
             const built = buildClient(accountId);
             if (!built.ok) return built.error;
             try {
-              const data = await built.client.addConversationMember(p.conversationId, p.userId);
+              const data = await built.client.addConversationMember(normalizeToolChatId(p.conversationId), p.userId);
               return jsonResponse(data);
             } catch (err) {
               if (err instanceof ClawlingApiError) {
@@ -1321,6 +1563,19 @@ export function registerOpenclawClawlingTools(
             }
             try {
               const p = validated.params;
+              let chatId = isValidChatId(p.chatId) ? storedChatIdCase(account.accountId, p.chatId) : p.chatId;
+              let replyToMessageId = p.replyToMessageId;
+              if (replyToMessageId) {
+                const resolved = resolveExplicitMessageId({
+                  field: "replyToMessageId",
+                  value: replyToMessageId,
+                  accountId: account.accountId,
+                  chatId,
+                });
+                if (!resolved.ok) return resolved.error;
+                chatId = resolved.chatId;
+                replyToMessageId = resolved.messageId;
+              }
               const client = getOpenclawClawlingClient(account.accountId);
               if (!client) {
                 return configError("ClawChat websocket client is not ready");
@@ -1329,26 +1584,38 @@ export function registerOpenclawClawlingTools(
                 client,
                 account,
                 to: {
-                  chatId: p.chatId.trim(),
+                  chatId,
                   chatType: p.chatType ?? "group",
                 },
                 ...(p.text !== undefined ? { text: p.text } : {}),
                 mentions: p.mentions,
-                ...(p.replyToMessageId
+                ...(replyToMessageId
                   ? {
                       replyCtx: {
-                        replyToMessageId: p.replyToMessageId,
+                        replyToMessageId,
                       },
                     }
                   : {}),
                 log: api.logger,
               });
               if (!result) return jsonResponse(result);
-              markTerminalClawChatSend({
+              recordMentionSent({
                 accountId: account.accountId,
-                chatId: p.chatId.trim(),
+                chatId,
                 messageId: result.messageId,
+                text: p.text ?? "",
+                ...(result.acceptedAt !== undefined ? { acceptedAt: result.acceptedAt } : {}),
               });
+              // Same trust rule as the react defaults: only a ClawChat run's
+              // turn may have its follow-up reply suppressed.
+              if (isClawChatToolRun(ctx)) {
+                markTerminalClawChatSend({
+                  accountId: account.accountId,
+                  chatId,
+                  messageId: result.messageId,
+                  sessionKey: ctx.sessionKey,
+                });
+              }
               return jsonResponse({
                 sent: true,
                 terminal: true,
@@ -1376,7 +1643,7 @@ export function registerOpenclawClawlingTools(
         description: toolDescription(
           "React to a ClawChat message with a single quick emoji (the bubble long-press reaction), instead of sending a text message. " +
             "TRIGGER - invoke when a short acknowledgement or emotional beat (agreement, thanks, laughter, celebration, sympathy) reads more naturally as an emoji on the message than as a sentence, e.g. a simple 👍 to \"done\" or ❤️ to good news. " +
-            "Omit targetMessageId and chatId to react to the message that triggered the current turn; pass targetMessageId to react to an earlier message. " +
+            "In the owner's direct chat, omit targetMessageId and chatId to react to the message that triggered the current turn; pass targetMessageId to react to an earlier message. In group chats and other direct chats, always pass this chat's chatId. " +
             "Set remove:true to take back your reaction. " +
             "Prefer the quick set 👍 ❤️ 😂 😮 😢 🙏 🎉 👏 🔥 😍 🤔. " +
             "When a reaction is all you want to send, do not also send a normal text reply.",
@@ -1392,9 +1659,31 @@ export function registerOpenclawClawlingTools(
             if (!account.configured) {
               return configError("clawchat-plugin-openclaw: account is not configured");
             }
-            const scope = getCurrentTerminalSendScope();
-            const chatId = p.chatId?.trim() || scope?.chatId;
-            const targetMessageId = p.targetMessageId?.trim() || scope?.messageId;
+            // Defaults come only from this call's own turn: the open turn in
+            // its async context registered for the same session key as the
+            // trusted tool ctx (see terminal-send.ts). Anything else fails as
+            // a validation error asking for explicit ids.
+            // The run must also be a ClawChat run: under a session key shared
+            // with another channel, that channel's turns never register or
+            // supersede a ClawChat turn, so its calls get no defaults.
+            const scope = isClawChatToolRun(ctx)
+              ? getCurrentTerminalSendScope({ sessionKey: ctx.sessionKey })
+              : null;
+            // Only a missing or blank chatId defaults. A given one that strips
+            // to nothing (`clawchat-plugin-openclaw:`, `group:`) stays as given
+            // so outbound refuses it as invalid_chat_id instead of it silently
+            // reaching the current turn's chat.
+            const rawChatId = typeof p.chatId === "string" ? p.chatId.trim() : "";
+            let chatId = rawChatId ? normalizeToolChatId(rawChatId) || rawChatId : scope?.chatId;
+            const explicitTargetMessageId = typeof p.targetMessageId === "string" ? p.targetMessageId.trim() : "";
+            // The default target is the current turn's message, so it applies
+            // only to that turn's chat: chatId omitted, or naming the scope's
+            // chat (any case, host target form). The send then goes to the
+            // scope's chat id. In any other chat that id names no message.
+            const defaultsToScopeChat = Boolean(scope)
+              && (!rawChatId || (chatId ?? "").toLowerCase() === scope!.chatId.toLowerCase());
+            let targetMessageId = explicitTargetMessageId || (defaultsToScopeChat ? scope!.messageId : undefined);
+            if (!explicitTargetMessageId && defaultsToScopeChat) chatId = scope!.chatId;
             if (!chatId) {
               return validationError(
                 "clawchat-plugin-openclaw: chatId is required (no current-turn chat to default from)",
@@ -1405,6 +1694,21 @@ export function registerOpenclawClawlingTools(
                 "clawchat-plugin-openclaw: targetMessageId is required (no current-turn message to default from)",
               );
             }
+            // Only an explicit id is checked; the current-turn default is the
+            // triggering message's own id. A chat id outbound would refuse is
+            // reported as that refusal first.
+            if (explicitTargetMessageId) {
+              if (!isValidChatId(chatId)) return reactionBlockedError(chatId, "invalid_chat_id");
+              const resolved = resolveExplicitMessageId({
+                field: "targetMessageId",
+                value: explicitTargetMessageId,
+                accountId: account.accountId,
+                chatId,
+              });
+              if (!resolved.ok) return resolved.error;
+              chatId = resolved.chatId;
+              targetMessageId = resolved.messageId;
+            }
             const client = getOpenclawClawlingClient(account.accountId);
             if (!client) {
               return configError("ClawChat websocket client is not ready");
@@ -1412,7 +1716,10 @@ export function registerOpenclawClawlingTools(
             const emoji = p.emoji.trim();
             const removed = p.remove === true;
             try {
-              sendOpenclawClawlingReaction({ client, chatId, targetMessageId, emoji, removed, log: api.logger });
+              const sent = sendOpenclawClawlingReaction({ client, chatId, targetMessageId, emoji, removed, log: api.logger });
+              // A locally refused reaction never left the plugin: report the
+              // refusal so the model does not tell the user it reacted.
+              if (!sent.sent) return reactionBlockedError(chatId, sent.reason);
               return jsonResponse({ reacted: true, targetMessageId, emoji, removed });
             } catch (err) {
               return genericError(err);
@@ -2023,7 +2330,7 @@ export function registerOpenclawClawlingTools(
         async execute(_callId, params) {
           return await recordClawchatToolCall(accountId, "clawchat_orchestrate_get_group", params, async () => {
             const p = params as ClawchatOrchGetGroupParams;
-            return await withClient(accountId, (c) => c.orchGetGroup(p.conversationId));
+            return await withClient(accountId, (c) => c.orchGetGroup(normalizeToolChatId(p.conversationId)));
           });
         },
       };
@@ -2056,7 +2363,7 @@ export function registerOpenclawClawlingTools(
             params,
             async () => {
               const p = params as ClawchatOrchSetGroupPromptParams;
-              return await withClient(accountId, (c) => c.orchSetGroupPrompt(p.conversationId, p.description));
+              return await withClient(accountId, (c) => c.orchSetGroupPrompt(normalizeToolChatId(p.conversationId), p.description));
             },
           );
         },
@@ -2106,7 +2413,7 @@ export function registerOpenclawClawlingTools(
             params,
             async () => {
               const p = params as ClawchatOrchGroupMemberParams;
-              return await withClient(accountId, (c) => c.orchAddGroupMember(p.conversationId, p.agentId));
+              return await withClient(accountId, (c) => c.orchAddGroupMember(normalizeToolChatId(p.conversationId), p.agentId));
             },
           );
         },
@@ -2133,7 +2440,7 @@ export function registerOpenclawClawlingTools(
             params,
             async () => {
               const p = params as ClawchatOrchGroupMemberParams;
-              return await withClient(accountId, (c) => c.orchRemoveGroupMember(p.conversationId, p.agentId));
+              return await withClient(accountId, (c) => c.orchRemoveGroupMember(normalizeToolChatId(p.conversationId), p.agentId));
             },
           );
         },
@@ -2163,7 +2470,7 @@ export function registerOpenclawClawlingTools(
             async () => {
               const p = params as ClawchatOrchSetGroupAgentSettingsParams;
               return await withClient(accountId, (c) =>
-                c.orchSetGroupAgentSettings(p.conversationId, p.agentId, {
+                c.orchSetGroupAgentSettings(normalizeToolChatId(p.conversationId), p.agentId, {
                   muted: p.muted,
                   replyMode: p.replyMode,
                   batchDelaySeconds: p.batchDelaySeconds,