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

package/dist/src/turn-boundary.js

@@ -0,0 +1,68 @@
+// Who started this turn? The owner's turns are exactly the ones in the owner's
+// activation direct chat (whoever the sender is — plugin-started turns there
+// count). Every group turn and every other direct chat is someone else's.
+// Anything we cannot place is treated as someone else's (fail closed).
+import { CHANNEL_ID, normalizeOpenclawClawlingAccountId } from "./config.js";
+/** Tools a turn the owner did not start may still see and call. */
+export const NON_OWNER_TOOL_ALLOWLIST = Object.freeze([
+    "clawchat_memory_search", "clawchat_memory_read", "clawchat_memory_write", "clawchat_memory_edit",
+    "clawchat_mention_message", "clawchat_react_message", "clawchat_get_user_profile", "clawchat_metadata_sync",
+    "web_search",
+]);
+const norm = (v) => (typeof v === "string" ? v.trim().toLowerCase() : "");
+// `<channel>:` then `direct:`/`group:`, each optional and stripped at most once.
+const TOOL_CHAT_ID_TARGET_PREFIX = new RegExp(`^(?:${CHANNEL_ID}:)?(?:(?:direct|group):)?`, "i");
+/**
+ * The bare ClawChat chat id a tool argument names. The host shows the model
+ * this chat's `chat_id` as the channel-prefixed origin target
+ * (`clawchat-plugin-openclaw:cnv_…` / `clawchat-plugin-openclaw:group:cnv_…`)
+ * and a group's label as `group:cnv_…`; models copy either form into tool
+ * arguments. Only that form is stripped; case is kept, and whatever remains is
+ * still validated by the send path (`isValidChatId`) or the server. Every tool
+ * that takes a ClawChat chat id, and the non-owner current-chat check, use
+ * this one helper so they agree on which chat an argument names.
+ */
+export function normalizeToolChatId(value) {
+    if (typeof value !== "string")
+        return "";
+    return value.trim().replace(TOOL_CHAT_ID_TARGET_PREFIX, "").trim();
+}
+/**
+ * Host session keys (dmScope per-account-channel-peer):
+ *   agent:<agent>:<channel>:<account>:direct:<chat>
+ *   agent:<agent>:<channel>:group:<chat>
+ */
+export function parseClawChatSessionKey(sessionKey) {
+    const parts = norm(sessionKey).split(":");
+    if (parts.length < 5 || parts[0] !== "agent" || parts[2] !== CHANNEL_ID)
+        return null;
+    if (parts[3] === "group" && parts.length === 5 && parts[4])
+        return { kind: "group", chatId: parts[4] };
+    if (parts[4] === "direct" && parts.length === 6 && parts[5])
+        return { kind: "direct", chatId: parts[5] };
+    return null;
+}
+/**
+ * Account id carried by a ClawChat direct session key, normalized exactly once
+ * with the plugin's account-id normalizer. Group keys carry no account
+ * segment, and a blank segment is missing (never silently "default").
+ */
+export function clawChatSessionAccountId(sessionKey) {
+    if (parseClawChatSessionKey(sessionKey)?.kind !== "direct")
+        return undefined;
+    const segment = (sessionKey ?? "").trim().split(":")[3]?.trim();
+    return segment ? normalizeOpenclawClawlingAccountId(segment) : undefined;
+}
+export function classifyChat(input) {
+    const owner = norm(input.ownerDirectConversationId);
+    const chat = norm(input.chatId);
+    if (input.kind !== "direct" || !owner || !chat)
+        return "non-owner";
+    return chat === owner ? "owner" : "non-owner";
+}
+export function classifyTurn(input) {
+    const parsed = parseClawChatSessionKey(input.sessionKey);
+    if (!parsed)
+        return "non-owner";
+    return classifyChat({ ...parsed, ownerDirectConversationId: input.ownerDirectConversationId });
+}

package/index.ts

@@ -3,6 +3,7 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { openclawClawlingPlugin } from "./src/channel.ts";
 import { registerOpenclawClawlingCommands } from "./src/commands.ts";
 import { openclawClawlingConfigSchema } from "./src/config.ts";
+import { registerHostToolsGuard } from "./src/host-tools-guard.ts";
 import {
   registerClawChatPromptInjection,
   type ClawChatPromptInjectionApi,
@@ -20,6 +21,9 @@ const channelEntry = defineChannelPluginEntry({
   registerFull(api) {
     registerClawChatPromptInjection(api as unknown as ClawChatPromptInjectionApi);
     registerOpenclawClawlingTools(api);
+    // Fail-closed host-tool guard for turns the owner did not start. After the
+    // tools so their names are recorded; not gated by conversation access.
+    registerHostToolsGuard(api);
     // NOTE: the legacy-rename config migration is intentionally NOT registered
     // here. The host's setup-migration runner only loads a plugin's SETUP source
     // (`openclaw.setupEntry`/`runtimeSetupEntry` → setup-entry.ts) and calls its

package/openclaw.plugin.json

@@ -132,6 +132,7 @@
       "note-cap-group": { "type": "integer" },
       "note-cap-turn": { "type": "integer" },
       "delta-budget-chars": { "type": "integer" },
+      "non-owner-host-tools": { "type": "string", "enum": ["off", "approve"] },
       "reconnect": {
         "type": "object",
         "additionalProperties": false,
@@ -210,6 +211,7 @@
             "note-cap-group": { "type": "integer" },
             "note-cap-turn": { "type": "integer" },
             "delta-budget-chars": { "type": "integer" },
+            "non-owner-host-tools": { "type": "string", "enum": ["off", "approve"] },
             "reconnect": {
               "type": "object",
               "additionalProperties": false,
@@ -294,6 +296,7 @@
           "note-cap-group": { "type": "integer" },
           "note-cap-turn": { "type": "integer" },
           "delta-budget-chars": { "type": "integer" },
+          "non-owner-host-tools": { "type": "string", "enum": ["off", "approve"] },
           "reconnect": {
             "type": "object",
             "additionalProperties": false,
@@ -372,6 +375,7 @@
                 "note-cap-group": { "type": "integer" },
                 "note-cap-turn": { "type": "integer" },
                 "delta-budget-chars": { "type": "integer" },
+                "non-owner-host-tools": { "type": "string", "enum": ["off", "approve"] },
                 "reconnect": {
                   "type": "object",
                   "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.10.9-2",
+  "version": "2026.10.9-4",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",
@@ -52,7 +52,7 @@
     "@sinclair/typebox": "0.34.48"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.5.4"
+    "openclaw": ">=2026.8.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -93,7 +93,7 @@
     "install": {
       "npmSpec": "@clawling/clawchat-plugin-openclaw",
       "defaultChoice": "npm",
-      "minHostVersion": ">=2026.5.4"
+      "minHostVersion": ">=2026.8.1"
     }
   }
 }

package/src/clawchat-memory.ts

@@ -34,6 +34,13 @@ export interface ClawChatMemorySearchResult {
   query: string;
   matches: ClawChatMemorySearchMatch[];
   truncated: boolean;
+  /** Set by callers whose conversation scope left notes out (never a count). */
+  scopeNote?: string;
+}
+
+export interface ClawChatMemorySearchOptions {
+  /** Targets this caller may see; others are skipped before any content read. */
+  readable?: (target: ClawChatMemoryTarget) => boolean;
 }
 
 const metadataStart = "<!-- clawchat:metadata:start -->";
@@ -434,6 +441,7 @@ function buildSearchMatch(
 export async function searchClawChatMemory(
   root: string,
   params: ClawChatMemorySearchParams,
+  options: ClawChatMemorySearchOptions = {},
 ): Promise<ClawChatMemorySearchResult> {
   const { query, queryLower, targetTypes, maxResults } = normalizeSearchParams(params);
   const rootPath = path.resolve(root);
@@ -443,6 +451,11 @@ export async function searchClawChatMemory(
   for (const targetType of targetTypes) {
     const targets = await listSafeMemoryFiles(rootPath, rootRealPath, targetType);
     for (const target of targets) {
+      // Filter before reading, matching and counting so unreadable notes
+      // leave no trace in matches or `truncated`.
+      if (options.readable && !options.readable(target)) {
+        continue;
+      }
       const file = await readClawChatMemoryFile(rootPath, target);
       if (!file.exists) {
         continue;

package/src/config.ts

@@ -125,6 +125,8 @@ export type OpenclawClawlingAccountConfig = {
   "note-cap-group"?: number;
   "note-cap-turn"?: number;
   "delta-budget-chars"?: number;
+  /** Host tools in turns the owner did not start: `off` | `approve` (approve currently behaves as off). */
+  "non-owner-host-tools"?: string;
   reconnect?: OpenclawClawlingReconnectConfig;
   heartbeat?: OpenclawClawlingHeartbeatConfig;
   ack?: OpenclawClawlingAckConfig;
@@ -190,6 +192,7 @@ export const openclawClawlingAccountConfigSchema = {
     "note-cap-group": { type: "integer" },
     "note-cap-turn": { type: "integer" },
     "delta-budget-chars": { type: "integer" },
+    "non-owner-host-tools": { type: "string", enum: ["off", "approve"] },
     reconnect: {
       type: "object",
       additionalProperties: false,
@@ -337,6 +340,8 @@ export type ResolvedOpenclawClawlingAccount = {
   noteCapTurn: number;
   /** `delta-budget-chars`: characters of unseen group messages an @-mention adds. */
   deltaBudgetChars: number;
+  /** `non-owner-host-tools`: parsed mode; `approve` is reserved and currently behaves like `off`. */
+  nonOwnerHostTools: "off" | "approve";
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
   heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
@@ -597,6 +602,11 @@ export const SESSION_INT_KEYS = {
   "delta-budget-chars": [8000, 2000, 32000],
 } as const satisfies Record<string, readonly [number, number, number]>;
 
+/** `approve` only when explicitly set; any other value (typo, `on`, boolean) means `off`. */
+export function parseNonOwnerHostTools(raw: unknown): "off" | "approve" {
+  return typeof raw === "string" && raw.trim().toLowerCase() === "approve" ? "approve" : "off";
+}
+
 function readSessionInt(channel: Record<string, unknown>, key: keyof typeof SESSION_INT_KEYS): number {
   const [factory, minimum, maximum] = SESSION_INT_KEYS[key];
   const raw = channel[key];
@@ -739,6 +749,7 @@ export function resolveOpenclawClawlingAccount(
     noteCapGroup: readSessionInt(channel, "note-cap-group"),
     noteCapTurn: readSessionInt(channel, "note-cap-turn"),
     deltaBudgetChars: readSessionInt(channel, "delta-budget-chars"),
+    nonOwnerHostTools: parseNonOwnerHostTools(channel["non-owner-host-tools"]),
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),
     heartbeat: readHeartbeat(channel.heartbeat),

package/src/host-tools-guard.ts

@@ -0,0 +1,189 @@
+// Layer 2 of the non-owner turn boundary: a fail-closed `before_tool_call`
+// hook. Dispatch (layer 1) already narrows the offered tools for turns the
+// owner did not start; this hook blocks anything else that still reaches
+// execution. Only calls whose session key carries the ClawChat prefix are
+// in scope (D8); everything else passes untouched. Tool arguments are never
+// logged.
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { CHANNEL_ID, normalizeOpenclawClawlingAccountId, resolveOpenclawClawlingAccount } from "./config.ts";
+import {
+  classifyChat,
+  clawChatSessionAccountId,
+  NON_OWNER_TOOL_ALLOWLIST,
+  normalizeToolChatId,
+  parseClawChatSessionKey,
+} from "./turn-boundary.ts";
+import { clawChatDbPathForStateDir, getClawChatStore } from "./storage.ts";
+import { resolveOwnerIdentity } from "./owner-identity.ts";
+import { getRegisteredClawChatToolNames } from "./tools.ts";
+
+export const BLOCK_MESSAGE =
+  "This tool is not available here: only your owner's direct chat may use host tools on this machine. Do not try to reach them another way; answer without them, or tell the person to ask your owner.";
+
+export type HostToolDecision = { block: true; blockReason: string } | undefined;
+export type HostToolInput = {
+  toolName: string;
+  params: Record<string, unknown>;
+  sessionKey?: string;
+  ownerDirectConversationId?: string | null;
+  registeredTools: ReadonlySet<string>;
+};
+
+/**
+ * Host tool-search controls (OpenClaw 2026.9.6+). The host adds them to every
+ * run on its own and builds their catalog from the run's allowed tools, so in
+ * a non-owner turn they reach only the allowlisted tools; the host fires this
+ * hook again for the inner tool a `tool_call` runs, and that inner call gets
+ * every check below. They are not part of the dispatch allowlist.
+ */
+export const HOST_TOOL_SEARCH_CONTROLS: readonly string[] = Object.freeze(["tool_search", "tool_describe", "tool_call"]);
+const ACCOUNT_SCOPED_TOOLS: readonly string[] = ["clawchat_mention_message", "clawchat_react_message"];
+
+const block = (): HostToolDecision => ({ block: true, blockReason: BLOCK_MESSAGE });
+const CLAWCHAT_SESSION_PREFIX = new RegExp(`^agent:[^:]+:${CHANNEL_ID}:`, "i");
+const PATH_FIELD = /^(?:filePath|media|iconPath|path|attachments)$/i;
+
+/** D8: only the ClawChat session-key prefix ties a call to ClawChat; requester channel alone never does. */
+export function isClawChatToolCall(input: Pick<HostToolInput, "sessionKey">): boolean {
+  return CLAWCHAT_SESSION_PREFIX.test(input.sessionKey?.trim() ?? "");
+}
+
+/** True when any argument looks like a local file path; only http(s) URLs are allowed. */
+export function hasLocalPathArgument(value: unknown, field = ""): boolean {
+  if (typeof value === "string") {
+    const text = value.trim();
+    if (/^https?:\/\//i.test(text)) return false;
+    if (/^(?:\/|[a-z]:[\\/]|\\\\|file:|~|\.\.?[\\/])/i.test(text)) return true;
+    return PATH_FIELD.test(field) && text.length > 0;
+  }
+  if (Array.isArray(value)) return value.some(item => hasLocalPathArgument(item, field));
+  return Boolean(value && typeof value === "object" && Object.entries(value).some(
+    ([key, item]) => hasLocalPathArgument(item, PATH_FIELD.test(field) ? field : key),
+  ));
+}
+
+/** Pure decision for one tool call. `undefined` lets the call run. */
+export function decideHostToolCall(input: HostToolInput): HostToolDecision {
+  if (!isClawChatToolCall(input)) return undefined;
+  const parsed = parseClawChatSessionKey(input.sessionKey);
+  if (!parsed) return block();
+  if (classifyChat({ ...parsed, ownerDirectConversationId: input.ownerDirectConversationId }) === "owner") {
+    return undefined;
+  }
+  // Outer pre-check only. The inner tool call is checked again and that check
+  // is authoritative: the host also accepts dotted/flattened argument keys
+  // that this outer check may not recognise.
+  if (hasLocalPathArgument(input.params)) return block();
+  if (HOST_TOOL_SEARCH_CONTROLS.includes(input.toolName)) return undefined;
+  if (ACCOUNT_SCOPED_TOOLS.includes(input.toolName)) {
+    // D9: a non-owner turn may only act on its own chat, named explicitly.
+    // The tool resolves the same argument with the same helper, so the chat
+    // checked here is the chat the call reaches.
+    const target = normalizeToolChatId(input.params.chatId).toLowerCase();
+    if (!target || target !== parsed.chatId) {
+      return {
+        block: true,
+        blockReason: input.toolName === "clawchat_react_message"
+          ? "Pass this chat's chatId to react here."
+          : "Pass this chat's chatId to mention here.",
+      };
+    }
+  }
+  if (NON_OWNER_TOOL_ALLOWLIST.includes(input.toolName)) {
+    return input.toolName.startsWith("clawchat_") && !input.registeredTools.has(input.toolName)
+      ? block()
+      : undefined;
+  }
+  return block(); // `off` and the reserved `approve` both block in this release.
+}
+
+type RequesterContext = { channel?: string; accountId?: string };
+
+export function registerHostToolsGuard(
+  api: OpenClawPluginApi,
+  options: { ownerConversation?: (accountId: string) => string | null } = {},
+): void {
+  const warned = new Set<string>();
+  const warn = (failure: string) => {
+    if (warned.has(failure)) return;
+    warned.add(failure);
+    try {
+      api.logger.warn(`clawchat-plugin-openclaw: host-tool guard ${failure}; enforcing non-owner policy`);
+    } catch {
+      // Logging cannot unlock a call.
+    }
+  };
+  const lookupOwnerConversation = (accountId: string): string | null => {
+    if (options.ownerConversation) return options.ownerConversation(accountId);
+    const account = resolveOpenclawClawlingAccount(api.config, accountId);
+    const stateDir = api.runtime.state?.resolveStateDir?.();
+    const store = getClawChatStore({
+      ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+      log: { error: message => api.logger.error?.(message) },
+    });
+    return resolveOwnerIdentity(store, accountId, account.ownerUserId).conversationId;
+  };
+
+  api.on("before_tool_call", (event, sdkCtx) => {
+    // `requester` is host 2026.8.1+ (the floor); the development SDK types predate it.
+    const ctx = sdkCtx as (typeof sdkCtx & { requester?: RequesterContext }) | undefined;
+    try {
+      if (!ctx) {
+        warn("missing-context");
+        return block();
+      }
+      const sessionKey = ctx.sessionKey;
+      if (!isClawChatToolCall({ sessionKey })) return undefined;
+      const requester = ctx.requester;
+      const parsed = parseClawChatSessionKey(sessionKey);
+      if (!parsed || (requester?.channel && requester.channel !== CHANNEL_ID)) {
+        warn("unknown-session");
+        return block();
+      }
+      // Direct keys carry their account; group keys do not. A group turn is
+      // non-owner whoever speaks, so a group call without the requester
+      // account (host tool-search controls and the inner calls they run get
+      // a run-level ctx without one) still gets the non-owner policy; only
+      // the tools that act as an account need it. Conflicting ids block.
+      const keyAccountId = clawChatSessionAccountId(sessionKey);
+      const requesterAccountId = requester?.accountId?.trim()
+        ? normalizeOpenclawClawlingAccountId(requester.accountId)
+        : undefined;
+      const accountId = requesterAccountId ?? keyAccountId;
+      if (keyAccountId && keyAccountId !== accountId) {
+        warn("account-identity");
+        return block();
+      }
+      if (!accountId) {
+        if (parsed.kind !== "group" || ACCOUNT_SCOPED_TOOLS.includes(event.toolName)) {
+          warn("account-identity");
+          return block();
+        }
+        return decideHostToolCall({
+          toolName: event.toolName,
+          params: event.params ?? {},
+          sessionKey,
+          ownerDirectConversationId: null,
+          registeredTools: getRegisteredClawChatToolNames(),
+        });
+      }
+      let ownerDirectConversationId: string | null = null;
+      try {
+        ownerDirectConversationId = lookupOwnerConversation(accountId);
+      } catch {
+        // Treated as missing below; the allowlist still applies.
+      }
+      if (!ownerDirectConversationId?.trim()) warn("missing-owner-conversation");
+      return decideHostToolCall({
+        toolName: event.toolName,
+        params: event.params ?? {},
+        sessionKey,
+        ownerDirectConversationId,
+        registeredTools: getRegisteredClawChatToolNames(),
+      });
+    } catch {
+      warn("handler-exception");
+      return block();
+    }
+  });
+}

package/src/host-version.ts

@@ -0,0 +1,35 @@
+export const HOST_FLOOR = "2026.8.1";
+
+function parse(v: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** Prerelease suffixes count as their base version (10.1-beta.2 ≥ 8.1). Unparseable ⇒ false. */
+export function hostAtLeast(version: string | undefined, min: string): boolean {
+  const a = version ? parse(version) : null;
+  const b = parse(min);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return true;
+}
+
+/** First host release where tool search is on unless `tools.toolSearch` turns it off. */
+export const HOST_TOOL_SEARCH_DEFAULT_ON = "2026.9.6";
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * Whether the host's `tools.toolSearch` setting leaves tool search on, read the
+ * way the host reads it (2026.9.6+): unset or `true` ⇒ on; `false` ⇒ off; an
+ * object ⇒ its `enabled` flag, else on only when it sets other options.
+ */
+export function hostToolSearchEnabled(config: unknown): boolean {
+  const tools = isRecord(config) ? config.tools : undefined;
+  const raw = isRecord(tools) ? tools.toolSearch : undefined;
+  if (raw === undefined || raw === true) return true;
+  if (!isRecord(raw)) return false;
+  if (typeof raw.enabled === "boolean") return raw.enabled;
+  return Object.keys(raw).some(key => key !== "enabled");
+}

package/src/memory-scope.ts

@@ -0,0 +1,191 @@
+// Which ClawChat notes the conversation behind a memory / metadata tool call
+// may read. A tool result stays in the calling session's history, and a group
+// is one session for everyone in it, so a note read there can surface to
+// anyone present later. Scope therefore follows the conversation (tool
+// factory ctx), never a parameter or the process environment:
+//
+//   owner DM (incl. plugin-started turns there) → every note
+//   friend DM → only users/<requesterSenderId>.md
+//   group     → groups/<this chat>.md + users/<id>.md of present members
+//   anything else (unknown session, missing store / peer, contradictions,
+//   ambiguous chat-id case, resolution errors) → nothing
+//
+// Chat ids compare case-insensitively (the host lowercases session keys);
+// the original case is recovered before any group file / SQL lookup. Member
+// user ids stay case-sensitive.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readClawChatMemoryFile, type ClawChatMemoryTarget } from "./clawchat-memory.ts";
+import { resolveOwnerIdentity } from "./owner-identity.ts";
+import type { ClawChatStore } from "./storage.ts";
+import { classifyTurn, parseClawChatSessionKey } from "./turn-boundary.ts";
+
+export type MemoryToolContext = {
+  sessionKey?: string;
+  requesterSenderId?: string | null;
+  deliveryContext?: { to?: string };
+};
+
+export type MemoryScope = {
+  kind: "owner" | "direct" | "group" | "unknown";
+  chatId: string;
+  members: ReadonlySet<string>;
+};
+
+export type MemoryScopeStore = Partial<Pick<ClawChatStore, "lookupActivationIdentity" | "listRecentGroupMessages">>;
+
+/** Rows scanned for recent speakers when a group note has no participant list. */
+const SPEAKER_FALLBACK_ROWS = 200;
+
+const nothing = (): MemoryScope => ({ kind: "unknown", chatId: "", members: new Set() });
+
+async function groupNoteIds(root: string): Promise<string[]> {
+  try {
+    return (await fs.readdir(path.join(root, "groups")))
+      .filter((name) => name.endsWith(".md"))
+      .map((name) => name.slice(0, -3));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+function participantIds(metadata: Record<string, string>): Set<string> {
+  return new Set((metadata.participant_ids ?? "").split(",").map((id) => id.trim()).filter(Boolean));
+}
+
+function inboundSenderId(rawJson: string | null): string | null {
+  if (!rawJson) return null;
+  const sender = (JSON.parse(rawJson) as { sender?: { id?: unknown } } | null)?.sender?.id;
+  return typeof sender === "string" && sender.trim() ? sender.trim() : null;
+}
+
+export async function resolveMemoryScope(input: {
+  root: string;
+  ctx: MemoryToolContext;
+  accountId: string;
+  configOwnerUserId?: string | null;
+  store: MemoryScopeStore | null;
+  warn?: (failureClass: string) => void;
+}): Promise<MemoryScope> {
+  const { root, ctx, accountId, store, warn } = input;
+  try {
+    const parsed = parseClawChatSessionKey(ctx.sessionKey);
+    if (!parsed) return nothing();
+    if (!store) {
+      warn?.("store-unavailable");
+      return nothing();
+    }
+    const lowered = parsed.chatId; // the parser lowercases
+    let chatId = lowered;
+    let caseKnown = false;
+
+    // 1. The trusted delivery route usually carries the original-case id.
+    const destination = ctx.deliveryContext?.to?.trim()
+      .replace(/^(?:clawchat-plugin-openclaw:)?(?:group|direct):/i, "");
+    if (destination && destination.toLowerCase() === lowered) {
+      chatId = destination;
+      caseKnown = true;
+    }
+
+    // 2. A group note filename, which wins: it is the file that will be read.
+    //    Two notes differing only in case are ambiguous.
+    const fileMatches = (await groupNoteIds(root)).filter((id) => id.toLowerCase() === lowered);
+    if (fileMatches.length > 1) {
+      warn?.("ambiguous-chat-case");
+      return nothing();
+    }
+    const groupFileId = fileMatches[0];
+    if (groupFileId !== undefined) {
+      chatId = groupFileId;
+      caseKnown = true;
+    }
+    const members = groupFileId === undefined
+      ? new Set<string>()
+      : participantIds((await readClawChatMemoryFile(root, { targetType: "group", targetId: groupFileId })).metadata);
+
+    if (parsed.kind === "direct") {
+      // A chat the plugin knows as a group can never be a direct chat.
+      if (members.size) {
+        warn?.("contradictory-chat-kind");
+        return nothing();
+      }
+      const ownerConversationId = resolveOwnerIdentity(store, accountId, input.configOwnerUserId, warn).conversationId;
+      if (classifyTurn({ sessionKey: ctx.sessionKey, ownerDirectConversationId: ownerConversationId }) === "owner") {
+        return { kind: "owner", chatId: ownerConversationId!, members: new Set() };
+      }
+      const peer = typeof ctx.requesterSenderId === "string" ? ctx.requesterSenderId.trim() : "";
+      if (!peer) warn?.("missing-dm-peer");
+      return { kind: "direct", chatId: parsed.chatId, members: new Set(peer ? [peer] : []) };
+    }
+
+    // 3. No cached participant list: recent inbound speakers. When neither the
+    //    route nor a filename supplied the case, the case-insensitive query is
+    //    the recovery path and its stored chat_id supplies the original case.
+    if (!members.size) {
+      if (!store.listRecentGroupMessages) {
+        warn?.("store-unavailable");
+        return nothing();
+      }
+      const rows = store.listRecentGroupMessages("openclaw", accountId, chatId, SPEAKER_FALLBACK_ROWS, {
+        ignoreCase: !caseKnown,
+      });
+      if (!caseKnown) {
+        const storedIds = new Set(rows.map((row) => row.chat_id)
+          .filter((id): id is string => typeof id === "string" && id.toLowerCase() === lowered));
+        if (storedIds.size > 1) {
+          warn?.("ambiguous-chat-case");
+          return nothing();
+        }
+        if (storedIds.size === 1) chatId = [...storedIds][0]!;
+      }
+      for (const row of rows) {
+        if (row.direction !== "inbound") continue;
+        try {
+          const sender = inboundSenderId(row.raw_json);
+          if (sender) members.add(sender);
+        } catch {
+          warn?.("malformed-group-row");
+        }
+      }
+    }
+    return { kind: "group", chatId, members };
+  } catch {
+    warn?.("scope-resolution");
+    return nothing();
+  }
+}
+
+export function canReadMemory(scope: MemoryScope, target: ClawChatMemoryTarget): boolean {
+  if (scope.kind === "owner") return true;
+  if (scope.kind === "unknown" || target.targetType === "owner") return false;
+  if (target.targetType === "user") return scope.members.has(target.targetId);
+  return scope.kind === "group" && target.targetType === "group" && target.targetId === scope.chatId;
+}
+
+export function memoryScopeRefusal(scope: MemoryScope, target: ClawChatMemoryTarget): {
+  error: "not_readable_here";
+  code: "memory_scope";
+  message: string;
+} {
+  const message = target.targetType === "owner"
+    ? "owner.md can only be read in your owner's direct chat. Tool results stay in this conversation's history. Do not try to get the owner's notes another way."
+    : scope.kind === "direct"
+      ? "In this direct chat you can only read the note about the person you are talking to."
+      : scope.kind === "group"
+        ? "In a group you can only read this group's note and its members' notes."
+        : "This conversation could not be identified; no ClawChat notes are readable here.";
+  return { error: "not_readable_here", code: "memory_scope", message };
+}
+
+/** What a restricted search left out, for the model (never counts). */
+export function memoryScopeNote(scope: MemoryScope): string | undefined {
+  if (scope.kind === "direct") {
+    return "In this direct chat only the note about the person you are talking to is searched; owner.md, other people's notes and group notes are left out.";
+  }
+  if (scope.kind === "group") {
+    return "In a group only this group's note and its members' notes are searched; owner.md, other groups' notes and notes about non-members are left out.";
+  }
+  if (scope.kind === "unknown") return "This conversation could not be identified; no ClawChat notes were searched.";
+  return undefined;
+}