@remnic/core 9.33.0 → 9.34.0

package/src/orchestration/extraction-persist.ts

@@ -82,6 +82,7 @@ import {
   stripCitationForTemplate,
 } from "../source-attribution.js";
 import { classifyMemoryKind } from "../himem.js";
+import { shouldPromoteGlobalFactToShared, withholdToolScopedFromSharedNamespace } from "../tool-scoped-memory.js";
 import {
   buildBehaviorSignalsForMemory,
   dedupeBehaviorSignalsByMemoryAndHash,
@@ -394,6 +395,7 @@ export class ExtractionPersistCoordinator {
     // (pre-judge + write-loop) so no new scattered config.*Enabled read is
     // introduced (ratchet scatteredConfigFlagReads; see #1523).
     const namespacesEnabled = resolveNamespaceCapabilities(this.deps.config).namespaces;
+    const sourceConnector = sourceContext?.sourceConnector; // #2183 tool-scope guard input
     const promoteMemoryToProfileTargets = async (options: {
       sourceStorage: StorageManager;
       category: string;
@@ -607,11 +609,14 @@ export class ExtractionPersistCoordinator {
       observedAt?: string;
       eventTimeSource?: "extracted" | "assumed";
       source: string;
+      sourceConnector?: string;
+      procedureSteps?: ReadonlyArray<{ toolCall?: { kind?: string } }>;
       /** Claim-level provenance spans (issue #1575 PR 2). */
       sources?: ProvenanceSource[];
       provenance?: "verified" | "unverified" | "none";
     }): Promise<void> => {
       await promoteMemoryToProfileTargets(options);
+      if (lifecycleCaps.extractionScopeClassification && withholdToolScopedFromSharedNamespace(options)) return;
       if (
         !shouldPromoteToShared(
           this.deps.config,
@@ -629,7 +634,6 @@ export class ExtractionPersistCoordinator {
           this.deps.config.sharedNamespace,
         );
         // Dedup gate: canonicalize content before hashing.
-        //
         // Issue #369 (PR #401): When inline attribution is enabled,
         // `applyInlineCitation` appends a timestamp-bearing marker (e.g.
         // `[Source: ..., ts=2026-04-11T...]`).  Because the timestamp changes
@@ -639,7 +643,6 @@ export class ExtractionPersistCoordinator {
         // `fact.content`, which can already carry an inline citation (e.g. a
         // relayed or reprocessed fact).  Strip any pre-existing citation so the
         // dedup key matches the hash stored from the original un-cited write.
-        //
         // PR #402 round-6 (Fix #2 / chatgpt-codex P1 PRRT_kwDORJXyws56U74n):
         // Compute the enriched content before the hash-dedup check so the
         // lookup uses the same content that writeMemory will actually store.
@@ -652,7 +655,6 @@ export class ExtractionPersistCoordinator {
         // key order and casing are canonical — identical to the enrichment
         // applied by storage.writeMemory — preventing spurious hash misses
         // when attribute maps arrive with different insertion orders or casing.
-        //
         // Fix #4 (Low PRRT_kwDORJXyws56VHth): sanitize the base content before
         // building dedupContent.  writeMemory runs sanitizeMemoryContent on the
         // enriched body before hashing; if sanitization redacts the content to
@@ -660,7 +662,6 @@ export class ExtractionPersistCoordinator {
         // the raw form.  Computing dedupContent from sanitized.text here ensures
         // the hash lookup and the normalizedIncoming comparison both use the
         // same content that writeMemory will actually store.
-        //
         // Combined fix: strip any pre-existing citation FIRST to obtain
         // rawContent (the canonical body), then sanitize rawContent (not
         // options.content) when building dedupContent, so that citation
@@ -1350,20 +1351,18 @@ export class ExtractionPersistCoordinator {
           // + PBJEe/PBKAj).
           let factRedactionRules = preJudgeRedactionRules;
           let factNs = preRoutedNamespaceByFact[fi];
-          // #1713 (codex PRRT_kwDORJXyws6PBj5X): scope classification can route
-          // a scope=global fact to the shared namespace independent of routing
-          // rules. If so, the pre-judge filter must consult the shared
-          // namespace's rules too, or a never-store pattern under shared is
-          // missed at pre-judge and only caught at the write gate — letting the
-          // content reach the extraction judge/training path. Mirror the write
-          // loop's scope-routing conditions exactly.
+          // #1713: predict the same target namespace the write loop will route
+          // this global fact to (shared, via shouldPromoteGlobalFactToShared) so
+          // the pre-judge redaction filter consults that namespace's rules.
           if (
             !factNs &&
             lifecycleCaps.extractionScopeClassification &&
             namespacesEnabled &&
             f.scope === "global" &&
             profileAllowsSharedWrites &&
-            this.deps.storageDirNamespace(storage.dir) !== this.deps.config.sharedNamespace
+            this.deps.storageDirNamespace(storage.dir) !== this.deps.config.sharedNamespace &&
+            shouldPromoteGlobalFactToShared({ scope: f.scope, content: f.content,
+              sourceConnector, procedureSteps: f.procedureSteps })
           ) {
             factNs = this.deps.config.sharedNamespace;
           }
@@ -1611,14 +1610,9 @@ export class ExtractionPersistCoordinator {
         }
       }
 
-      // Scope-based namespace routing: when scope classification is enabled
-      // and the LLM tagged this fact as "global", route it to the shared
-      // namespace so cross-project knowledge is visible everywhere. Only
-      // applies when namespaces are enabled and the fact was not already
-      // routed to a specific namespace by a routing rule (routing rules
-      // that set an explicit namespace take precedence; category-only rules
-      // do not block scope routing). Rule 30: gated by
-      // extractionScopeClassificationEnabled.
+      // Scope-based namespace routing: a `global` fact (scope classification
+      // on, no explicit routing-rule namespace) is promoted to the shared
+      // namespace unless the tool-scope guard withholds it (#2183).
       if (
         lifecycleCaps.extractionScopeClassification &&
         namespacesEnabled &&
@@ -1627,18 +1621,21 @@ export class ExtractionPersistCoordinator {
       ) {
         const currentNs = this.deps.storageDirNamespace(targetStorage.dir);
         if (currentNs !== this.deps.config.sharedNamespace && profileAllowsSharedWrites) {
-          try {
-            targetStorage = await this.deps.getStorageRouter().storageFor(
-              this.deps.config.sharedNamespace,
-            );
-            targetNamespaceName = this.deps.config.sharedNamespace;
-            log.debug(
-              `scope-routing: fact "${fact.content.slice(0, 60)}…" routed to shared namespace (scope=global)`,
-            );
-          } catch (scopeRouteErr) {
-            log.warn(
-              `scope-routing: failed to resolve shared namespace storage; writing to session namespace (fail-open): ${scopeRouteErr}`,
-            );
+          if (shouldPromoteGlobalFactToShared({ scope: fact.scope, content: fact.content,
+            sourceConnector, procedureSteps: fact.procedureSteps })) {
+            try {
+              targetStorage = await this.deps.getStorageRouter().storageFor(
+                this.deps.config.sharedNamespace,
+              );
+              targetNamespaceName = this.deps.config.sharedNamespace;
+              log.debug(
+                `scope-routing: fact "${fact.content.slice(0, 60)}…" routed to shared namespace (scope=global)`,
+              );
+            } catch (scopeRouteErr) {
+              log.warn(
+                `scope-routing: failed to resolve shared namespace storage; writing to session namespace (fail-open): ${scopeRouteErr}`,
+              );
+            }
           }
         } else if (currentNs !== this.deps.config.sharedNamespace) {
           log.debug(
@@ -2404,6 +2401,7 @@ export class ExtractionPersistCoordinator {
               : {}),
             source: extractionWriteSource,
             ...(extractionSourceConnector ? { sourceConnector: extractionSourceConnector } : {}),
+            ...(fact.procedureSteps && fact.procedureSteps.length ? { procedureSteps: fact.procedureSteps } : {}),
             ...(fact.sources && fact.sources.length > 0 ? { sources: fact.sources } : {}),
             ...(fact.provenance ? { provenance: fact.provenance } : {}),
           });
@@ -2704,6 +2702,7 @@ export class ExtractionPersistCoordinator {
             : {}),
           source: extractionWriteSource,
           ...(extractionSourceConnector ? { sourceConnector: extractionSourceConnector } : {}),
+          ...(fact.procedureSteps && fact.procedureSteps.length ? { procedureSteps: fact.procedureSteps } : {}),
           ...(fact.sources && fact.sources.length > 0 ? { sources: fact.sources } : {}),
           ...(fact.provenance ? { provenance: fact.provenance } : {}),
         });

package/src/tool-scoped-memory.test.ts

@@ -0,0 +1,199 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  referencesAgentSpecificTool,
+  shouldPromoteGlobalFactToShared,
+  withholdToolScopedFromSharedNamespace,
+} from "./tool-scoped-memory.js";
+
+// ---------------------------------------------------------------------------
+// referencesAgentSpecificTool — table-driven, both polarities.
+//
+// Tuning bias (issue #2183): a FALSE POSITIVE is cheap (the fact stays in the
+// narrower namespace — the documented safe default); a FALSE NEGATIVE is the
+// cross-integration tool-collision bug. Detection leans permissive but must not
+// fire on ordinary prose. Keywords and generic names are word-anchored so
+// "tooling"/"commander" and the "search" inside "research" do not match.
+// ---------------------------------------------------------------------------
+
+const REF_CASES: Array<{ content: string; expected: boolean; note: string }> = [
+  // ---- MUST match --------------------------------------------------------
+  { content: "Prefer the search tool and provide a path when locating code.", expected: true, note: "generic name adjacent to 'tool'" },
+  { content: "Use the `read` tool before editing a file.", expected: true, note: "backticked token adjacent to 'tool'" },
+  { content: "The exec tool requires an absolute cwd.", expected: true, note: "generic name 'exec' adjacent to 'tool'" },
+  { content: "Use `search` when locating code.", expected: true, note: "imperative invocation + backticked identifier" },
+  { content: "Run `rg` before editing.", expected: true, note: "imperative invocation + backticked identifier" },
+  { content: "Use /search with a path.", expected: true, note: "slash-command syntax" },
+  // ---- MUST NOT match ----------------------------------------------------
+  { content: "User prefers dark mode in all editors", expected: false, note: "portable preference; no tool/command context" },
+  { content: "PostgreSQL 15 requires the uuid-ossp extension for gen_random_uuid()", expected: false, note: "portable framework knowledge" },
+  { content: "Magento 2.4.8 has a race condition in checkout", expected: false, note: "'condition' is not a keyword; 'checkout' is not generic" },
+  { content: "The user reads documentation before starting a task", expected: false, note: "the bare verb 'reads' is not a tool reference" },
+  { content: "Search tooling improves developer productivity", expected: false, note: "'tool' must not match the prefix of 'tooling'" },
+  { content: "Research tool improves accuracy", expected: false, note: "'search' must not match inside 'research'" },
+];
+
+for (const { content, expected, note } of REF_CASES) {
+  test(`referencesAgentSpecificTool: ${expected ? "detects" : "ignores"} "${content.slice(0, 44)}…" (${note})`, () => {
+    assert.equal(referencesAgentSpecificTool(content), expected, note);
+  });
+}
+
+const EXTRA_POSITIVE: string[] = [
+  "The `checkout` command switches branches.",
+  "The browser tool navigates to the URL first.",
+  "Always run the memory tool after a context switch.",
+  "the tool named search returns repo hits",
+  "Pi exposes a search tool; OpenClaw exposes a same-named web tool.",
+  "Invoke `memory_store` to persist the reflection.",
+  "Use search when locating implementation",
+  "Run rg before editing",
+  "Call memory_store to persist the result",
+  "Run grep before editing",
+  "Use curl to fetch the URL",
+  "The memory_store tool persists results",
+  "Use the grep command to search files",
+  "Call memory_store() to persist the result",
+  "Use search() when locating code",
+  "Run rg() to find symbols",
+  "Use --force when reinstalling",
+  "The --format cli flag selects JSON",
+  "Run rg --files before editing",
+  "Use grep -n TODO when reviewing",
+  "Run `rg --files` before editing",
+  "The Bash tool executes commands",
+  "Use the Edit tool before saving",
+  "The WebFetch tool retrieves pages",
+  "Run git status before committing",
+  "Use npm install to add dependencies",
+  "The Bash Tool executes commands",
+  "Run git checkout -b feature before editing",
+  "Run `git status` before committing",
+  "Use `npm install` to add dependencies",
+  "Run `git checkout -b feature` before editing",
+  "Use edit before saving",
+  "Use bashExecution before editing",
+  "The bashExecution tool executes commands",
+  "Call bashExecution() to persist data",
+  "Use /remnic flush before reset",
+  "The /remnic command controls memory",
+  "Use `/remnic flush` before reset",
+  "Use `search --path src` when locating code",
+];
+for (const content of EXTRA_POSITIVE) {
+  test(`referencesAgentSpecificTool detects: "${content.slice(0, 44)}…"`, () => {
+    assert.equal(referencesAgentSpecificTool(content), true);
+  });
+}
+
+const EXTRA_NEGATIVE: string[] = [
+  "Git is a useful tool for version control.",
+  "The command line is faster than the GUI for this workflow.",
+  "She has a good command of the deployment process.",
+  "Communication is the main tool of a leader.",
+  "PostgreSQL read replicas lag under heavy load.",
+  "Memory usage spikes during compaction.",
+  "The browser caches static assets aggressively.",
+  "Reading long files is slow.",
+  "He writes detailed notes after every meeting.",
+  "Leadership requires command of the subject matter.",
+  "Writers use memory and emotion to craft stories.",
+  "I use search engines daily for research.",
+  "Use memory wisely and rest often.",
+  "Visit https://example.com/search for docs.",
+  "The service reads configuration from /etc/remnic/config.json",
+  "Logs live under /var/log/remnic",
+  "Restore the backup from /tmp/dump.sql",
+  "Use /etc/remnic/config.json for configuration",
+  "The service should use /health for readiness checks",
+  "Use PostgreSQL for durable storage",
+  "Use TypeScript in new packages",
+  "Run migrations after deployment",
+  "Use Redis for caching",
+  "Use 'least privilege' when designing authorization",
+  'Run "database migrations" after deployment',
+  "Use SQL for analytics",
+  "Use API for integration",
+  "Use Go for backend services",
+  "Use `/etc/remnic/config.json` for configuration",
+  "Run `/var/log/remnic` cleanup",
+  "Call me before you leave",
+  "Use it to simplify the workflow",
+  "Run in before deploying",
+  "Use 2024-2025 data for the baseline",
+  "The tool — a recent addition — is optional",
+  "Use `TypeScript` for new packages",
+  "Use `config.json` for configuration",
+  "Use `/health` for readiness checks",
+  "Writers use edit passes",
+  "Use macOS for development",
+  "Use iOS for mobile apps",
+  "Use eBay for purchases",
+  "Automation tool reduces repetitive work",
+  "Encryption tool selection should follow the threat model",
+  "Monitoring tool availability affects reliability",
+  "Use user_id in API responses",
+  "Use database_name for the connection",
+  "Use feature_flag when rolling out changes",
+  "Use least-privilege when designing authorization",
+  "Use TypeScript-first for new packages",
+];
+for (const content of EXTRA_NEGATIVE) {
+  test(`referencesAgentSpecificTool ignores prose: "${content.slice(0, 44)}…"`, () => {
+    assert.equal(referencesAgentSpecificTool(content), false);
+  });
+}
+
+test("referencesAgentSpecificTool: empty/non-string input is false (no throw)", () => {
+  assert.equal(referencesAgentSpecificTool(""), false);
+  assert.equal(referencesAgentSpecificTool("   "), false);
+});
+
+// ---------------------------------------------------------------------------
+// shouldPromoteGlobalFactToShared — composed scope-routing predicate.
+// ---------------------------------------------------------------------------
+
+const PROMOTION_CASES: Array<{ name: string; args: { scope: string | null | undefined; content: string; sourceConnector?: string; procedureSteps?: ReadonlyArray<{ intent?: string; toolCall?: { kind?: string; signature?: string } }> }; expected: boolean }> = [
+  { name: "global portable fact, no connector -> promote", args: { scope: "global", content: "User prefers dark mode in all editors" }, expected: true },
+  { name: "global tool-scoped fact WITH connector -> withhold (#2183)", args: { scope: "global", content: "Prefer the search tool when locating code.", sourceConnector: "pi" }, expected: false },
+  { name: "global tool-scoped fact, no knob -> withheld when connector known", args: { scope: "global", content: "The exec tool requires an absolute cwd.", sourceConnector: "openclaw" }, expected: false },
+  { name: "global tool-scoped fact WITHOUT connector -> promote (unattributed)", args: { scope: "global", content: "Prefer the search tool when locating code." }, expected: true },
+  { name: "project-scoped fact -> never promote via this path", args: { scope: "project", content: "Prefer the search tool when locating code.", sourceConnector: "pi" }, expected: false },
+  { name: "empty connector string is treated as unknown -> promote", args: { scope: "global", content: "Prefer the search tool when locating code.", sourceConnector: "" }, expected: true },
+  { name: "global portable-title procedure with tool-bearing steps + connector -> withhold (#2183 P2, scope-routing)", args: { scope: "global", content: "Workflow for locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "find the symbol", toolCall: { kind: "search", signature: "search('foo')" } }, { intent: "open the file", toolCall: { kind: "read", signature: "read('bar')" } }] }, expected: false },
+];
+for (const { name, args, expected } of PROMOTION_CASES) {
+  test(`shouldPromoteGlobalFactToShared: ${name}`, () => {
+    assert.equal(shouldPromoteGlobalFactToShared(args), expected);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// withholdToolScopedFromSharedNamespace — the SINGLE primitive every shared-
+// namespace promotion path consults. Includes structured procedure tool
+// identity (issue #2183 P2): a portable title + tool-bearing steps withholds.
+// ---------------------------------------------------------------------------
+
+const WITHHOLD_CASES: Array<{
+  name: string;
+  args: { content: string; sourceConnector?: string; procedureSteps?: ReadonlyArray<{ intent?: string; toolCall?: { kind?: string; signature?: string } }> };
+  expected: boolean;
+}> = [
+  { name: "tool-scoped + connector -> withhold", args: { content: "Prefer the search tool when locating code.", sourceConnector: "pi" }, expected: true },
+  { name: "tool-scoped + empty connector -> do not withhold", args: { content: "Prefer the search tool when locating code.", sourceConnector: "" }, expected: false },
+  { name: "tool-scoped + whitespace-only connector -> do not withhold", args: { content: "Prefer the search tool when locating code.", sourceConnector: "   " }, expected: false },
+  { name: "tool-scoped + no connector -> do not withhold", args: { content: "Prefer the search tool when locating code." }, expected: false },
+  { name: "portable + connector -> do not withhold", args: { content: "User prefers dark mode in all editors", sourceConnector: "pi" }, expected: false },
+  { name: "portable title + connector + tool-bearing steps -> withhold (#2183 P2)", args: { content: "When locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "find", toolCall: { kind: "search", signature: "search('foo')" } }] }, expected: true },
+  { name: "portable title + connector + steps without toolCall -> do not withhold", args: { content: "When locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "read the docs" }] }, expected: false },
+  { name: "portable title + connector + steps with empty kind -> do not withhold", args: { content: "When locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "x", toolCall: { kind: "  ", signature: "y" } }] }, expected: false },
+  { name: "tool-bearing steps but NO connector -> do not withhold (unattributed)", args: { content: "When locating implementation", procedureSteps: [{ intent: "find", toolCall: { kind: "search", signature: "search('foo')" } }] }, expected: false },
+  { name: "portable title + intent-only tool step + connector -> withhold (#2183 intent text)", args: { content: "Workflow for locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "Run grep before editing" }] }, expected: true },
+  { name: "portable title + all-portable steps + connector -> do not withhold", args: { content: "Workflow for code review", sourceConnector: "pi", procedureSteps: [{ intent: "Read the changes carefully" }, { intent: "Approve the work" }] }, expected: false },
+];
+for (const { name, args, expected } of WITHHOLD_CASES) {
+  test(`withholdToolScopedFromSharedNamespace: ${name}`, () => {
+    assert.equal(withholdToolScopedFromSharedNamespace(args), expected);
+  });
+}

package/src/tool-scoped-memory.ts

@@ -0,0 +1,190 @@
+/**
+ * Tool-scoped memory guard (issue #2183).
+ *
+ * A tool-related fact extracted from a specific agent integration carries an
+ * UNQUALIFIED tool name — "use the search tool" — with no agent identity
+ * attached (the conversation handed to the extraction LLM is rendered as
+ * `[role] content` only). Promoting such a fact to the shared namespace lets a
+ * DIFFERENT integration that exposes a same-named but incompatible tool (Pi
+ * `search` = repo code search vs OpenClaw `search` = web search) consume it.
+ *
+ * `referencesAgentSpecificTool` flags fact text that references a specific
+ * tool/command invocation rather than portable knowledge. The promotion guard
+ * in `orchestration/extraction-persist.ts` uses it — when the producing
+ * integration is known (`sourceConnector`) — to keep such a fact in that
+ * integration's own namespace.
+ *
+ * Tuning bias: a FALSE POSITIVE is cheap — the fact stays in the narrower
+ * namespace, the documented safe default. A FALSE NEGATIVE is the actual
+ * cross-integration collision bug, so detection leans permissive — but it must
+ * not fire on ordinary prose.
+ */
+
+const BT = "`";
+
+// Generic tool names + host-tool names emitted by the agent adapters.
+// Evidence: "edit" — Pi messages.test.ts:43 ({ type: "toolCall", name: "edit" }).
+// "bash" — Pi messages.test.ts:70 (bashExecution tool rendering). "glob",
+// "webfetch", "task" — standard Claude Code tools (Pi wraps Claude Code).
+const GENERIC_TOOL_NAMES = [
+  "read", "write", "search", "fetch", "browser", "exec", "shell", "memory",
+  "edit", "bash", "glob", "webfetch", "task",
+  "remnic",
+];
+const KNOWN_CLI_NAMES = [
+  "grep", "curl", "git", "npm", "pnpm", "sed", "awk", "jq", "cat", "ssh",
+  "docker", "kubectl", "make", "rg", "ls", "cd",
+];
+const GENERIC_NAMES_ALT = GENERIC_TOOL_NAMES.join("|");
+const KNOWN_NAMES_ALT = [...GENERIC_TOOL_NAMES, ...KNOWN_CLI_NAMES].join("|");
+const CLI_NAMES_ALT = KNOWN_CLI_NAMES.join("|");
+
+const FS_ROOTS = "(?:etc|var|usr|tmp|home|opt|srv|proc|dev)";
+const FLAG = "(?:--|-)[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*\\b";
+const FLAG_NAKED = "(?:--|-)[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*";
+const OPCODE = "[A-Za-z0-9_./-]{1,20}";
+
+const NO_SLASH_TOKEN = "[A-Za-z0-9_.-]{1,60}";
+const SLASH_CMD_TOKEN = "/(?:" + GENERIC_NAMES_ALT + ")\\b";
+const QUOTED_CONTENT = "(?:" + NO_SLASH_TOKEN + "|" + SLASH_CMD_TOKEN + ")";
+const QUOTED_PERMISSIVE =
+  "(?:" + BT + QUOTED_CONTENT + BT + "|\"" + QUOTED_CONTENT + "\"|'" + QUOTED_CONTENT + "')";
+
+const SNAKE = "(?:[a-z][a-z0-9]*(?:_[a-z0-9]+)+)\\b";
+const SNAKE_NON_DATA = "(?:[a-z][a-z0-9]*(?:_[a-z0-9]+)*(?:_(?!id\\b|name\\b|flag\\b|count\\b|at\\b|url\\b|key\\b|type\\b)[a-z0-9]+))\\b";
+const SNAKE_KEBAB = "(?:[a-z][a-z0-9]*(?:[_-][a-z0-9]+)+)\\b";
+
+const KNOWN_NAMES_CI = "\\b(?:" + KNOWN_NAMES_ALT + ")\\b";
+const CLI_NAMES_CI = "\\b(?:" + CLI_NAMES_ALT + ")\\b";
+const KEYWORD = "\\b(?:mcp[ _]tool|slash[ _]command|cli[ _]flag|subcommand|tool|command)\\b";
+
+const IDENT = "(?:" + QUOTED_PERMISSIVE + "|" + KNOWN_NAMES_CI + "|" + SNAKE_KEBAB + "|" + FLAG + ")";
+
+const IMM = "[\\s'\"" + BT + "]{1,4}";
+const CONN = "\\s+(?:named|called|aka)\\s+";
+const VERB = "\\b(?:use|run|call|invoke)\\b";
+const SLASH_GENERIC = "/(?:" + GENERIC_NAMES_ALT + ")\\b";
+const CLAUSE_BOUNDARY = "(?:$|[.,;(:]|(?:when|before|after|to|with|for|on|in|if|unless|whenever)\\b)";
+const ARGS = "(?:\\s+" + FLAG + "(?:\\s+" + OPCODE + "){0,4})?";
+const CLI_ARG_TOKEN = "(?:[a-z][a-z0-9-]{0,15}|" + FLAG_NAKED + "|" + OPCODE + ")";
+const CLI_ARG_RUN = "(?:\\s+" + CLI_ARG_TOKEN + "){1,4}";
+
+// Shared: a CLI tool or slash command optionally followed by a bounded
+// argument run. Used by BOTH the quoted and unquoted invocation arms so
+// quoting cannot diverge from unquoted again (#2183 round 20).
+const CMD_WITH_ARGS = "(?:(?:" + CLI_NAMES_CI + "|" + SLASH_GENERIC + ")" + CLI_ARG_RUN + ")";
+const QSTRICT_CONTENT =
+  "(?:" + KNOWN_NAMES_ALT + "|[a-z][a-z0-9]*(?:[_-][a-z0-9]+)+" + "|" + FLAG_NAKED + "|" + SLASH_CMD_TOKEN +
+  "|" + CMD_WITH_ARGS + "|(?:" + KNOWN_NAMES_ALT + ")" + CLI_ARG_RUN + ")";
+const QUOTED_STRICT =
+  "(?:" + BT + QSTRICT_CONTENT + BT + "|\"" + QSTRICT_CONTENT + "\"|'" + QSTRICT_CONTENT + "')";
+
+const INVOCATION_FLAG_ARGS =
+  VERB + "\\s+(?:" + QUOTED_STRICT + "|" + KNOWN_NAMES_CI + "|" + SNAKE_NON_DATA + "|" + SLASH_GENERIC + "|" + FLAG + ")" + ARGS + "(?=\\s*" + CLAUSE_BOUNDARY + ")";
+const INVOCATION_CLI_ARGS =
+  VERB + "\\s+" + CMD_WITH_ARGS + "(?=\\s*" + CLAUSE_BOUNDARY + ")";
+const INVOCATION = "(?:" + INVOCATION_FLAG_ARGS + "|" + INVOCATION_CLI_ARGS + ")";
+
+const TOOL_REFERENCE_CI = new RegExp(
+  "(?:" +
+    IDENT + IMM + KEYWORD + "|" + KEYWORD + IMM + IDENT + "|" +
+    KEYWORD + CONN + IDENT + "|" + IDENT + CONN + KEYWORD + "|" +
+    INVOCATION +
+  ")",
+  "i",
+);
+
+function hasCapitalisedToolName(content: string): boolean {
+  // Structural discriminator: a capitalised identifier beside a tool/command
+  // keyword qualifies ONLY when preceded by an article or invocation verb (not
+  // sentence-initial), or connected via named/called/aka. This replaces the
+  // blocklist approach — a structural rule beats a growing STOP_WORDS set.
+  for (const re of [
+    /(?:the|a|an|this|that|these|those|use|run|call|invoke)\s+([A-Za-z][A-Za-z0-9]+)\b[\s'`<>]{0,4}\b(?:tool|command|subcommand)\b/gi,
+    /\b(?:tool|command|subcommand)\b\s+(?:named|called|aka)\s+([A-Za-z][A-Za-z0-9]+)\b/gi,
+  ]) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+      const w = match[1];
+      if (w && w[0] >= "A" && w[0] <= "Z") return true;
+    }
+  }
+  return false;
+}
+
+function hasCamelCaseToolName(content: string): boolean {
+  // Case-sensitive: camelCase (lowercase start, interior uppercase) is a common
+  // host-tool naming convention (bashExecution, memoryStore, webFetch). Ordinary
+  // English words are never camelCase, and PascalCase (PostgreSQL, TypeScript)
+  // starts uppercase so is handled by hasCapitalisedToolName instead.
+  const camelRe = /\b([a-z]{3,}[a-z0-9]*[A-Z][a-z][A-Za-z0-9]*)\b/g;
+  let m;
+  while ((m = camelRe.exec(content)) !== null) {
+    const token = m[1];
+    const start = m.index!;
+    const end = start + token.length;
+    const before = content.slice(Math.max(0, start - 20), start);
+    const after = content.slice(end);
+    // Invocation: preceded by a verb, followed by a clause boundary or call syntax.
+    if (/(?:^|\s)(?:use|run|call|invoke)\s*$/i.test(before) &&
+        /^(?:\s*(?:$|[.,;(:]|(?:when|before|after|to|with|for|on|in|if|unless|whenever)\b))/i.test(after)) {
+      return true;
+    }
+    // Keyword-adjacent: camelCase beside a tool/command keyword.
+    if (/^(?:\s*(?:tool|command|subcommand)\b)/i.test(after) ||
+        /(?:tool|command|subcommand)\s*$/i.test(before)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function referencesAgentSpecificTool(content: string): boolean {
+  if (typeof content !== "string" || content.length === 0) return false;
+  return TOOL_REFERENCE_CI.test(content) || hasCapitalisedToolName(content) || hasCamelCaseToolName(content);
+}
+
+export interface ToolScopeWithholdInputs {
+  content: string;
+  sourceConnector?: string;
+  procedureSteps?: ReadonlyArray<{ intent?: string; expectedOutcome?: string; toolCall?: { kind?: string } }>;
+}
+
+export function withholdToolScopedFromSharedNamespace({
+  content,
+  sourceConnector,
+  procedureSteps,
+}: ToolScopeWithholdInputs): boolean {
+  if (typeof sourceConnector !== "string" || sourceConnector.trim().length === 0) return false;
+  if (referencesAgentSpecificTool(content)) return true;
+  if (
+    procedureSteps?.some((s) => {
+      const kind = s.toolCall?.kind;
+      if (typeof kind === "string" && kind.trim().length > 0) return true;
+      const stepText = [s.intent, s.expectedOutcome]
+        .filter((t): t is string => typeof t === "string" && t.length > 0)
+        .join(" ");
+      return stepText.length > 0 && referencesAgentSpecificTool(stepText);
+    })
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export interface GlobalFactPromotionInputs {
+  scope: string | null | undefined;
+  content: string;
+  sourceConnector?: string;
+  procedureSteps?: ReadonlyArray<{ toolCall?: { kind?: string } }>;
+}
+
+export function shouldPromoteGlobalFactToShared(inputs: GlobalFactPromotionInputs): boolean {
+  if (inputs.scope !== "global") return false;
+  return !withholdToolScopedFromSharedNamespace({
+    content: inputs.content,
+    sourceConnector: inputs.sourceConnector,
+    procedureSteps: inputs.procedureSteps,
+  });
+}