@clawling/clawchat-plugin-openclaw 2026.10.9-1 → 2026.10.9-3

package/README.md

@@ -18,7 +18,7 @@ OpenClaw channel plugin that connects an agent to ClawChat over ClawChat Protoco
 npm i @clawling/clawchat-plugin-openclaw
 ```
 
-Requires `openclaw >= 2026.5.4` as a peer host.
+Requires `openclaw >= 2026.8.1` as a peer host.
 
 Example LLM prompt:
 

package/dist/index.js

@@ -2,6 +2,7 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 import { openclawClawlingPlugin } from "./src/channel.js";
 import { registerOpenclawClawlingCommands } from "./src/commands.js";
 import { openclawClawlingConfigSchema } from "./src/config.js";
+import { registerHostToolsGuard } from "./src/host-tools-guard.js";
 import { registerClawChatPromptInjection, } from "./src/prompt-injection.js";
 import { setOpenclawClawlingRuntime } from "./src/runtime.js";
 import { registerOpenclawClawlingTools } from "./src/tools.js";
@@ -15,6 +16,9 @@ const channelEntry = defineChannelPluginEntry({
     registerFull(api) {
         registerClawChatPromptInjection(api);
         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/dist/src/clawchat-memory.js

@@ -332,7 +332,7 @@ function buildSearchMatch(target, file, queryLower) {
     }
     return { ...target, matchedFields, snippets: snippets.slice(0, 3) };
 }
-export async function searchClawChatMemory(root, params) {
+export async function searchClawChatMemory(root, params, options = {}) {
     const { query, queryLower, targetTypes, maxResults } = normalizeSearchParams(params);
     const rootPath = path.resolve(root);
     const rootRealPath = (await pathExists(rootPath)) ? await fs.realpath(rootPath) : rootPath;
@@ -340,6 +340,11 @@ export async function searchClawChatMemory(root, params) {
     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/dist/src/config.js

@@ -90,6 +90,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,
@@ -402,6 +403,10 @@ export const SESSION_INT_KEYS = {
     "note-cap-turn": [4000, 1000, 16000],
     "delta-budget-chars": [8000, 2000, 32000],
 };
+/** `approve` only when explicitly set; any other value (typo, `on`, boolean) means `off`. */
+export function parseNonOwnerHostTools(raw) {
+    return typeof raw === "string" && raw.trim().toLowerCase() === "approve" ? "approve" : "off";
+}
 function readSessionInt(channel, key) {
     const [factory, minimum, maximum] = SESSION_INT_KEYS[key];
     const raw = channel[key];
@@ -513,6 +518,7 @@ export function resolveOpenclawClawlingAccount(cfg, accountId, env = process.env
         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/dist/src/connect-check.js

@@ -1,4 +1,5 @@
 import { ClawlingApiError } from "./api-types.js";
+import { readConnectFailureGuidance } from "./connect-failure.js";
 import { AGENTS_CONNECT_PLATFORM, RECONNECT_GUIDE_URL } from "./onboarding-context.js";
 /**
  * Non-consuming pre-check of a connect code. Records the "checked" funnel
@@ -29,8 +30,14 @@ export async function preCheckConnectCode(client, input, log) {
         };
     }
     catch (err) {
+        // Still a degrade, never a gate: `/connect` re-evaluates the code and
+        // surfaces the same guidance on the error it throws. The guidance is only
+        // logged here so a rate-limit or dead code is visible early.
         const kind = err instanceof ClawlingApiError ? err.kind : "error";
-        log(`Connect-code pre-check unavailable (${kind}); continuing without it.`);
+        const guidance = err instanceof ClawlingApiError ? readConnectFailureGuidance(err.meta?.data) : {};
+        const action = guidance.nextAction ? `; next_action: ${guidance.nextAction}` : "";
+        const hint = guidance.hint ? `. ${guidance.hint}` : "";
+        log(`Connect-code pre-check unavailable (${kind}${action})${hint}; continuing without it.`);
         return null;
     }
 }

package/dist/src/connect-failure.js

@@ -0,0 +1,78 @@
+/** Default wait for `wait_retry` when the server omits / garbles the delay. */
+export const WAIT_RETRY_DEFAULT_SECONDS = 60;
+/** Upper bound on any `wait_retry` wait, whatever the server asks for. */
+export const WAIT_RETRY_MAX_SECONDS = 120;
+function readNonBlankString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function readConnectFailureGuidance(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return {};
+    const record = data;
+    const out = {};
+    const hint = readNonBlankString(record.hint);
+    if (hint)
+        out.hint = hint;
+    const nextAction = readNonBlankString(record.next_action);
+    if (nextAction)
+        out.nextAction = nextAction;
+    const retryAfter = record.retry_after_seconds;
+    if (typeof retryAfter === "number" && Number.isFinite(retryAfter)) {
+        out.retryAfterSeconds = retryAfter;
+    }
+    return out;
+}
+/** Delay before the single `wait_retry` retry: server value, capped, with a default. */
+export function waitRetryDelayMs(retryAfterSeconds) {
+    const seconds = typeof retryAfterSeconds === "number" && Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+        ? Math.min(retryAfterSeconds, WAIT_RETRY_MAX_SECONDS)
+        : WAIT_RETRY_DEFAULT_SECONDS;
+    return Math.round(seconds * 1000);
+}
+/**
+ * Error thrown by the invite-code login when `/v1/agents/connect` fails.
+ * The message keeps the historical `agents/connect failed (<kind>): <msg>`
+ * prefix; when the server sent guidance it is appended so an agent reading
+ * the CLI / chat-command output knows what to do next.
+ */
+export class ConnectFailedError extends Error {
+    kind;
+    code;
+    status;
+    hint;
+    nextAction;
+    retryAfterSeconds;
+    constructor(kind, serverMessage, meta = {}) {
+        super(formatConnectFailureMessage(kind, serverMessage, meta));
+        this.name = "ConnectFailedError";
+        this.kind = kind;
+        if (meta.code !== undefined)
+            this.code = meta.code;
+        if (meta.status !== undefined)
+            this.status = meta.status;
+        if (meta.hint !== undefined)
+            this.hint = meta.hint;
+        if (meta.nextAction !== undefined)
+            this.nextAction = meta.nextAction;
+        if (meta.retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = meta.retryAfterSeconds;
+    }
+}
+function formatConnectFailureMessage(kind, serverMessage, guidance) {
+    let text = `agents/connect failed (${kind}): ${serverMessage}`;
+    if (guidance.nextAction)
+        text += ` (next_action: ${guidance.nextAction})`;
+    if (guidance.hint)
+        text += `. ${guidance.hint}`;
+    return text;
+}
+export function connectFailedError(err) {
+    return new ConnectFailedError(err.kind, err.message, {
+        ...(err.meta?.code !== undefined ? { code: err.meta.code } : {}),
+        ...(err.meta?.status !== undefined ? { status: err.meta.status } : {}),
+        ...readConnectFailureGuidance(err.meta?.data),
+    });
+}

package/dist/src/host-tools-guard.js

@@ -0,0 +1,163 @@
+import { CHANNEL_ID, normalizeOpenclawClawlingAccountId, resolveOpenclawClawlingAccount } from "./config.js";
+import { classifyChat, clawChatSessionAccountId, NON_OWNER_TOOL_ALLOWLIST, parseClawChatSessionKey, } from "./turn-boundary.js";
+import { clawChatDbPathForStateDir, getClawChatStore } from "./storage.js";
+import { resolveOwnerIdentity } from "./owner-identity.js";
+import { getRegisteredClawChatToolNames } from "./tools.js";
+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.";
+/**
+ * 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 = Object.freeze(["tool_search", "tool_describe", "tool_call"]);
+const ACCOUNT_SCOPED_TOOLS = ["clawchat_mention_message", "clawchat_react_message"];
+const block = () => ({ 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) {
+    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, field = "") {
+    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) {
+    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.
+        const target = input.params.chatId;
+        if (typeof target !== "string" || !target.trim() || target.trim().toLowerCase() !== 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.
+}
+export function registerHostToolsGuard(api, options = {}) {
+    const warned = new Set();
+    const warn = (failure) => {
+        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) => {
+        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;
+        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 = 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/dist/src/host-version.js

@@ -0,0 +1,35 @@
+export const HOST_FLOOR = "2026.8.1";
+function parse(v) {
+    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, min) {
+    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) => 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) {
+    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/dist/src/login.runtime.js

@@ -8,10 +8,14 @@ import { CHANNEL_ID, mergeOpenclawClawchatRuntimePluginActivation, mergeOpenclaw
 import { getClawChatStore } from "./storage.js";
 import { buildOnboardingContext, RECONNECT_GUIDE_URL } from "./onboarding-context.js";
 import { boundCodeNewIdentityMessage, preCheckConnectCode, unpairableMessage } from "./connect-check.js";
+import { connectFailedError, readConnectFailureGuidance, waitRetryDelayMs } from "./connect-failure.js";
 // Re-exported: `src/login.runtime.test.ts` and `src/commands.ts` import these
 // from here, so the historical import path keeps working after the move.
 import { AGENTS_CONNECT_PLATFORM, AGENTS_CONNECT_TYPE, AGENT_NOT_FOUND_CODE, } from "./onboarding-context.js";
 export { AGENTS_CONNECT_PLATFORM, AGENTS_CONNECT_TYPE, AGENT_NOT_FOUND_CODE };
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Thrown when redeeming an invite code would silently replace a live activation.
  *
@@ -284,8 +288,31 @@ export async function runOpenclawClawlingLogin(params) {
     // A brand-new identity is precisely "do not replay" — the replay is the only
     // thing that would bind this code to the incumbent agent.
     const existingUserId = newAccount ? "" : storedUserId;
+    // Rate-limit (`next_action: wait_retry`) budget: one wait-and-retry per
+    // activation, shared across both requests below.
+    let waitRetryUsed = false;
+    const sleep = params.sleep ?? defaultSleep;
+    const redeem = async (body) => {
+        try {
+            return await apiClient.agentsConnect(body);
+        }
+        catch (err) {
+            if (!(err instanceof ClawlingApiError) || waitRetryUsed)
+                throw err;
+            const guidance = readConnectFailureGuidance(err.meta?.data);
+            // Only wait_retry is retried: a rate-limited request did not consume the
+            // code. Every other next_action (and any unknown one) is final.
+            if (guidance.nextAction !== "wait_retry")
+                throw err;
+            waitRetryUsed = true;
+            const delayMs = waitRetryDelayMs(guidance.retryAfterSeconds);
+            runtime.log(`Connect code redeem rate limited — retrying once in ${Math.round(delayMs / 1000)}s …`);
+            await sleep(delayMs);
+            return await apiClient.agentsConnect(body);
+        }
+    };
     try {
-        result = await apiClient.agentsConnect({
+        result = await redeem({
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
             type: AGENTS_CONNECT_TYPE,
@@ -306,7 +333,7 @@ export async function runOpenclawClawlingLogin(params) {
             if (existingUserId && err.meta?.code === AGENT_NOT_FOUND_CODE) {
                 runtime.log(`Stored userId ${existingUserId} no longer exists on this server — retrying as a fresh pairing …`);
                 try {
-                    result = await apiClient.agentsConnect({
+                    result = await redeem({
                         code: inviteCode,
                         platform: AGENTS_CONNECT_PLATFORM,
                         type: AGENTS_CONNECT_TYPE,
@@ -315,13 +342,13 @@ export async function runOpenclawClawlingLogin(params) {
                 }
                 catch (retryErr) {
                     if (retryErr instanceof ClawlingApiError) {
-                        throw new Error(`agents/connect failed (${retryErr.kind}): ${retryErr.message}`);
+                        throw connectFailedError(retryErr);
                     }
                     throw retryErr;
                 }
             }
             else {
-                throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+                throw connectFailedError(err);
             }
         }
         else {

package/dist/src/memory-scope.js

@@ -0,0 +1,166 @@
+// 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 } from "./clawchat-memory.js";
+import { resolveOwnerIdentity } from "./owner-identity.js";
+import { classifyTurn, parseClawChatSessionKey } from "./turn-boundary.js";
+/** Rows scanned for recent speakers when a group note has no participant list. */
+const SPEAKER_FALLBACK_ROWS = 200;
+const nothing = () => ({ kind: "unknown", chatId: "", members: new Set() });
+async function groupNoteIds(root) {
+    try {
+        return (await fs.readdir(path.join(root, "groups")))
+            .filter((name) => name.endsWith(".md"))
+            .map((name) => name.slice(0, -3));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+function participantIds(metadata) {
+    return new Set((metadata.participant_ids ?? "").split(",").map((id) => id.trim()).filter(Boolean));
+}
+function inboundSenderId(rawJson) {
+    if (!rawJson)
+        return null;
+    const sender = JSON.parse(rawJson)?.sender?.id;
+    return typeof sender === "string" && sender.trim() ? sender.trim() : null;
+}
+export async function resolveMemoryScope(input) {
+    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()
+            : 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) => 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, target) {
+    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, target) {
+    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) {
+    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;
+}

package/dist/src/owner-identity.js

@@ -0,0 +1,29 @@
+// The one definition of "who is the owner, and which chat is the owner's DM"
+// shared by dispatch, the host-tool guard and memory scope. The SQLite
+// activation row decides; the config `ownerUserId` mirror is only a fallback
+// once a working store has proved there is no activation row at all. An
+// unavailable store, a failed read, a cleared/rejected token or an incomplete
+// row never falls back to the mirror — the caller sees no owner (fail closed).
+export function resolveOwnerIdentity(store, accountId, configOwnerUserId, warn, rejectedActivationToken) {
+    const denied = { ownerUserId: null, conversationId: null };
+    try {
+        const lookup = store?.lookupActivationIdentity?.({ platform: "openclaw", accountId });
+        if (!lookup || lookup.status === "unavailable") {
+            warn?.("owner-identity");
+            return denied;
+        }
+        if (lookup.status === "absent") {
+            return { ownerUserId: configOwnerUserId?.trim() || null, conversationId: null };
+        }
+        const { row } = lookup;
+        // Mirror the runtime overlay: never trust the activation rejected during this lifecycle.
+        if (!row.accessToken || row.accessToken === rejectedActivationToken)
+            return denied;
+        const ownerUserId = row.ownerUserId?.trim() || null;
+        return { ownerUserId, conversationId: ownerUserId ? row.conversationId?.trim() || null : null };
+    }
+    catch {
+        warn?.("owner-identity");
+        return denied;
+    }
+}