context-mode 1.0.150 → 1.0.152

package/build/runtime.d.ts

@@ -7,7 +7,7 @@ export interface RuntimeInfo {
     preferred: boolean;
 }
 export interface RuntimeMap {
-    javascript: string;
+    javascript: string | null;
     typescript: string | null;
     python: string | null;
     shell: string;
@@ -20,8 +20,88 @@ export interface RuntimeMap {
     elixir: string | null;
     csharp: string | null;
 }
+/**
+ * Resolve the JavaScript runtime used by PolyglotExecutor.
+ *
+ * PR #190 (f69b0d2) made `process.execPath` the default so snap-Node
+ * envs would not re-invoke the snap wrapper via PATH. That assumed
+ * `process.execPath` always points at a JS runtime — true on Node,
+ * tsx, and snap-Node, but FALSE when context-mode runs in-process
+ * inside a bun-compiled self-contained binary (OpenCode, Kilo, …).
+ * In those hosts, `process.execPath` resolves to `opencode.exe` /
+ * `opencode` (NOT node), and spawning that with a `.js` argument
+ * triggers the yargs "Failed to change directory" error (#731).
+ *
+ * Fix: gate `process.execPath` on the existing `JS_RUNTIMES`
+ * allowlist (single source of truth — same set used by
+ * `buildNodeCommand()` in src/adapters/types.ts since PR #708). When
+ * the execPath basename is not a known JS runtime, fall back to a
+ * PATH-resolved `node`. If neither is reachable, return `null` and
+ * let ctx_doctor surface an actionable error.
+ *
+ * The cross-OS guard is the allowlist itself — NOT a `win32` check.
+ * OpenCode ships self-contained binaries on macOS and Linux too,
+ * and the bug reproduces identically there.
+ */
+export declare function resolveJavascriptRuntime(bun: string | null, deps?: {
+    execPath?: string;
+    commandExists?: (cmd: string) => boolean;
+}): string | null;
 export declare function detectRuntimes(): RuntimeMap;
 export declare function hasBunRuntime(): boolean;
+/**
+ * Resolved JS runtime for hook spawn commands. `path` is the absolute (or
+ * bare-name on POSIX where PATH resolution is reliable) binary path.
+ * `isBun` is true only when we successfully probed a Bun ≥1.0 install.
+ */
+export interface HookRuntime {
+    readonly path: string;
+    readonly isBun: boolean;
+}
+/**
+ * Reset the hook-runtime resolution cache. Test-only — production code
+ * should never call this. Vitest mocks `node:child_process`/`node:fs`
+ * per-test, so the per-process cache from a previous test would otherwise
+ * mask the mock and yield the host's real bun/node detection result.
+ */
+export declare function resetHookRuntimeCache(): void;
+/**
+ * Resolve the JS runtime to use for spawning hook scripts (issue #738).
+ *
+ * Returns Bun when:
+ *   - a bun binary is located via {@link bunCommand} (already handles the
+ *     Windows .cmd shim trap from #506 + absolute path fallbacks), AND
+ *   - `bun --version` exits 0 within the probe timeout, AND
+ *   - the reported semver major is ≥1.
+ *
+ * Returns Node (`process.execPath`) on every other path — missing bun,
+ * version probe failure, version <1, malformed version banner. Silent
+ * fallback: never throws, never logs to stderr (a noisy log would clutter
+ * the same MCP boot output that #719 tightened up).
+ *
+ * Result is cached at module load so the cost is amortised across every
+ * hook command emission for the lifetime of the process. The cache also
+ * keeps the behaviour deterministic — if the user `brew uninstall bun`
+ * mid-session, the cached resolution stays valid for that session and the
+ * next MCP boot re-detects.
+ *
+ * Why bun ≥1.0 instead of "any bun":
+ *   - Bun 0.x had multiple ESM/module-resolution regressions that broke
+ *     dynamic `import()` inside hooks (and our hooks do ~7 dynamic imports
+ *     in `pretooluse.mjs`).
+ *   - 1.0 ships stable npm-compat that our better-sqlite3-adjacent code
+ *     relies on indirectly (hooks share `ensure-deps.mjs` which is
+ *     bun-safe past 1.0 but not 0.x).
+ *
+ * NOT used by:
+ *   - `buildNodeCommand` — kept on `process.execPath` for openclaw doctor /
+ *     upgrade hints which must invoke the better-sqlite3-loading CLI on
+ *     Node (#543: bun cannot dlopen better-sqlite3's prebuilt .node).
+ *   - `ensure-deps.mjs` — separate path, must stay on Node for the same
+ *     reason.
+ *   - `ctx_upgrade` — separate path, must stay on Node for the same reason.
+ */
+export declare function resolveHookRuntime(): HookRuntime;
 export declare function getRuntimeSummary(runtimes: RuntimeMap): string;
 export declare function getAvailableLanguages(runtimes: RuntimeMap): Language[];
 export declare function buildCommand(runtimes: RuntimeMap, language: Language, filePath: string): string[];

package/build/runtime.js

@@ -1,5 +1,6 @@
 import { execFileSync, execSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { JS_RUNTIMES } from "./adapters/types.js";
 /**
  * Allowlist for SHELL env override. Only POSIX shells + Windows shells permit
  * arbitrary command interpretation; anything else (e.g., /usr/bin/python set
@@ -21,6 +22,11 @@ export function isAllowlistedShell(shellPath) {
     // Cross-OS basename: split on either separator, take the last segment.
     return ALLOWED_SHELL_BASENAMES.test(runtimeBasename(shellPath));
 }
+function isWindowsWslBash(shellPath) {
+    const lower = shellPath.toLowerCase().replace(/\//g, "\\");
+    return /\\windows\\(?:system32|sysnative)\\bash\.exe$/.test(lower) ||
+        /\\microsoft\\windowsapps\\bash\.exe$/.test(lower);
+}
 const isWindows = process.platform === "win32";
 function commandExists(cmd) {
     try {
@@ -189,24 +195,71 @@ function getVersion(cmd, args = ["--version"]) {
         return "unknown";
     }
 }
+/**
+ * Resolve the JavaScript runtime used by PolyglotExecutor.
+ *
+ * PR #190 (f69b0d2) made `process.execPath` the default so snap-Node
+ * envs would not re-invoke the snap wrapper via PATH. That assumed
+ * `process.execPath` always points at a JS runtime — true on Node,
+ * tsx, and snap-Node, but FALSE when context-mode runs in-process
+ * inside a bun-compiled self-contained binary (OpenCode, Kilo, …).
+ * In those hosts, `process.execPath` resolves to `opencode.exe` /
+ * `opencode` (NOT node), and spawning that with a `.js` argument
+ * triggers the yargs "Failed to change directory" error (#731).
+ *
+ * Fix: gate `process.execPath` on the existing `JS_RUNTIMES`
+ * allowlist (single source of truth — same set used by
+ * `buildNodeCommand()` in src/adapters/types.ts since PR #708). When
+ * the execPath basename is not a known JS runtime, fall back to a
+ * PATH-resolved `node`. If neither is reachable, return `null` and
+ * let ctx_doctor surface an actionable error.
+ *
+ * The cross-OS guard is the allowlist itself — NOT a `win32` check.
+ * OpenCode ships self-contained binaries on macOS and Linux too,
+ * and the bug reproduces identically there.
+ */
+export function resolveJavascriptRuntime(bun, deps = {}) {
+    if (bun)
+        return bun;
+    const execPath = deps.execPath ?? process.execPath;
+    const cmdExists = deps.commandExists ?? commandExists;
+    // Cross-OS basename: split on either separator, strip optional `.exe`.
+    const base = execPath
+        .split(/[\\/]/)
+        .pop()
+        .replace(/\.exe$/i, "");
+    if (JS_RUNTIMES.has(base)) {
+        // Real JS runtime (node, bun, deno) — preserves #190 snap-Node fix
+        // because the snap wrapper's binary is literally named `node`.
+        return execPath;
+    }
+    // Host binary (opencode/kilo/etc.) — fall back to node on PATH.
+    if (cmdExists("node"))
+        return "node";
+    // No usable runtime — doctor + summary must handle null gracefully.
+    return null;
+}
 export function detectRuntimes() {
     const hasBun = bunExists();
     const bun = hasBun ? bunCommand() : null;
     // Honor SHELL env var when it points at a real binary AND the basename is
-    // an allowlisted shell. Lets users with non-standard setups (WSL, custom
-    // bash, msys2) pin context-mode to their preferred shell.
+    // an allowlisted shell. Lets users with non-standard setups (custom bash,
+    // msys2, pwsh) pin context-mode to their preferred shell.
     //
     // Allowlist (PR #401 ops review): basename must match
-    // /^(bash|sh|zsh|dash|pwsh|cmd)(\.exe)?$/. Without this guard, an attacker
+    // /^(bash|sh|zsh|dash|pwsh|powershell|cmd)(\.exe)?$/. Without this guard, an attacker
     // who controls SHELL (e.g., supply-chain compromise of a profile script)
     // could redirect the executor to /usr/bin/python or any arbitrary binary.
     const userShell = process.env.SHELL;
-    const shellOverride = userShell && existsSync(userShell) && isAllowlistedShell(userShell)
+    const isWin = process.platform === "win32";
+    const shellOverride = userShell &&
+        existsSync(userShell) &&
+        isAllowlistedShell(userShell) &&
+        !(isWin && isWindowsWslBash(userShell))
         ? userShell
         : null;
-    const isWin = process.platform === "win32";
     return {
-        javascript: bun ?? process.execPath,
+        javascript: resolveJavascriptRuntime(bun),
         typescript: bun
             ? bun
             : commandExists("tsx")
@@ -241,10 +294,130 @@ export function detectRuntimes() {
 export function hasBunRuntime() {
     return bunExists();
 }
+/**
+ * Cached result of {@link resolveHookRuntime}. Populated on first call so the
+ * relatively expensive `bun --version` probe runs at most once per process.
+ * Reset via {@link resetHookRuntimeCache} (test-only).
+ */
+let _hookRuntimeCache = null;
+/**
+ * Reset the hook-runtime resolution cache. Test-only — production code
+ * should never call this. Vitest mocks `node:child_process`/`node:fs`
+ * per-test, so the per-process cache from a previous test would otherwise
+ * mask the mock and yield the host's real bun/node detection result.
+ */
+export function resetHookRuntimeCache() {
+    _hookRuntimeCache = null;
+}
+/**
+ * Parse a `bun --version` stdout string and return true when the version is
+ * ≥1.0.0. Anything that doesn't match `MAJOR.MINOR.PATCH` (with optional
+ * pre-release suffix) returns false — we refuse to trust runtimes whose
+ * version we can't read because the failure mode is silent miscompare
+ * (e.g. a banner line getting interpreted as "0.0.0").
+ */
+function bunVersionAtLeast1(versionOutput) {
+    const trimmed = versionOutput.trim();
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(trimmed);
+    if (!m)
+        return false;
+    const major = Number(m[1]);
+    return Number.isFinite(major) && major >= 1;
+}
+/**
+ * Resolve the JS runtime to use for spawning hook scripts (issue #738).
+ *
+ * Returns Bun when:
+ *   - a bun binary is located via {@link bunCommand} (already handles the
+ *     Windows .cmd shim trap from #506 + absolute path fallbacks), AND
+ *   - `bun --version` exits 0 within the probe timeout, AND
+ *   - the reported semver major is ≥1.
+ *
+ * Returns Node (`process.execPath`) on every other path — missing bun,
+ * version probe failure, version <1, malformed version banner. Silent
+ * fallback: never throws, never logs to stderr (a noisy log would clutter
+ * the same MCP boot output that #719 tightened up).
+ *
+ * Result is cached at module load so the cost is amortised across every
+ * hook command emission for the lifetime of the process. The cache also
+ * keeps the behaviour deterministic — if the user `brew uninstall bun`
+ * mid-session, the cached resolution stays valid for that session and the
+ * next MCP boot re-detects.
+ *
+ * Why bun ≥1.0 instead of "any bun":
+ *   - Bun 0.x had multiple ESM/module-resolution regressions that broke
+ *     dynamic `import()` inside hooks (and our hooks do ~7 dynamic imports
+ *     in `pretooluse.mjs`).
+ *   - 1.0 ships stable npm-compat that our better-sqlite3-adjacent code
+ *     relies on indirectly (hooks share `ensure-deps.mjs` which is
+ *     bun-safe past 1.0 but not 0.x).
+ *
+ * NOT used by:
+ *   - `buildNodeCommand` — kept on `process.execPath` for openclaw doctor /
+ *     upgrade hints which must invoke the better-sqlite3-loading CLI on
+ *     Node (#543: bun cannot dlopen better-sqlite3's prebuilt .node).
+ *   - `ensure-deps.mjs` — separate path, must stay on Node for the same
+ *     reason.
+ *   - `ctx_upgrade` — separate path, must stay on Node for the same reason.
+ */
+export function resolveHookRuntime() {
+    if (_hookRuntimeCache)
+        return _hookRuntimeCache;
+    const nodeFallback = { path: process.execPath, isBun: false };
+    try {
+        if (!bunExists()) {
+            _hookRuntimeCache = nodeFallback;
+            return _hookRuntimeCache;
+        }
+        const bun = bunCommand();
+        // Re-use the same probe shape as getVersion (POSIX execFile, Windows
+        // execSync quoted string for DEP0190 compliance).
+        let versionOutput;
+        try {
+            if (process.platform === "win32") {
+                const out = execSync(`"${bun}" --version`, {
+                    encoding: "utf-8",
+                    stdio: ["pipe", "pipe", "pipe"],
+                    timeout: 5000,
+                });
+                versionOutput = String(out);
+            }
+            else {
+                const out = execFileSync(bun, ["--version"], {
+                    encoding: "utf-8",
+                    stdio: ["pipe", "pipe", "pipe"],
+                    timeout: 5000,
+                });
+                versionOutput = String(out);
+            }
+        }
+        catch {
+            _hookRuntimeCache = nodeFallback;
+            return _hookRuntimeCache;
+        }
+        if (!bunVersionAtLeast1(versionOutput)) {
+            _hookRuntimeCache = nodeFallback;
+            return _hookRuntimeCache;
+        }
+        _hookRuntimeCache = { path: bun, isBun: true };
+        return _hookRuntimeCache;
+    }
+    catch {
+        _hookRuntimeCache = nodeFallback;
+        return _hookRuntimeCache;
+    }
+}
 export function getRuntimeSummary(runtimes) {
     const lines = [];
     const bunPreferred = runtimes.javascript?.endsWith("bun") ?? false;
-    lines.push(`  JavaScript: ${runtimes.javascript} (${getVersion(runtimes.javascript)})${bunPreferred ? " ⚡" : ""}`);
+    if (runtimes.javascript) {
+        lines.push(`  JavaScript: ${runtimes.javascript} (${getVersion(runtimes.javascript)})${bunPreferred ? " ⚡" : ""}`);
+    }
+    else {
+        // #731: host binary (opencode/kilo) AND no PATH-resolvable node.
+        // Surface actionable guidance instead of rendering literal `null`.
+        lines.push(`  JavaScript: not available (install node or bun — host process is not a JS runtime)`);
+    }
     if (runtimes.typescript) {
         lines.push(`  TypeScript: ${runtimes.typescript} (${getVersion(runtimes.typescript)})`);
     }
@@ -308,6 +481,12 @@ export function getAvailableLanguages(runtimes) {
 export function buildCommand(runtimes, language, filePath) {
     switch (language) {
         case "javascript":
+            if (!runtimes.javascript) {
+                // #731: in-process plugin host (opencode/kilo binary) AND no
+                // PATH-resolvable node. Refuse early with an actionable error
+                // instead of spawning the host binary (the original bug shape).
+                throw new Error("No JavaScript runtime available. Install Node.js or Bun on PATH (the host process is not itself a JS runtime).");
+            }
             return BUN_BASENAME.test(runtimeBasename(runtimes.javascript))
                 ? [runtimes.javascript, "run", filePath]
                 : [runtimes.javascript, filePath];
@@ -341,9 +520,16 @@ export function buildCommand(runtimes, language, filePath) {
                     return [runtimes.shell, "-c", `source '${escaped}'`];
                 }
                 if (shellName.includes("powershell") || shellName.includes("pwsh")) {
-                    return [runtimes.shell, "-File", filePath];
+                    // Windows PowerShell defaults to Restricted when no execution policy
+                    // is configured. Use process-scoped Bypass so generated temp scripts
+                    // run without changing machine/user policy.
+                    return [runtimes.shell, "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", filePath];
+                }
+                const shellBase = shellName.split(/[\\/]/).pop() ?? shellName;
+                if (shellBase === "cmd" || shellBase === "cmd.exe") {
+                    return [runtimes.shell, "/d", "/s", "/c", filePath];
                 }
-                // cmd.exe and others: direct file (cmd reads .cmd association safely).
+                // Other Windows shells: direct file.
             }
             return [runtimes.shell, filePath];
         }

package/build/search/ctx-search-schema.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ctx_search input-schema builder and project-scope resolver.
+ *
+ * Issue #737 introduces the optional `project:` parameter used by callers
+ * running in the shared-DB mode (`CONTEXT_MODE_PROJECT_DIR` is set). The
+ * field is registered conditionally so that in the default per-project DB
+ * mode the LLM physically cannot pass it — the parameter does not exist
+ * in the tool schema at all, which is a stronger guarantee than runtime
+ * validation that depends on the model honouring documentation.
+ *
+ * The handler in `src/server.ts` consumes both exports:
+ *   - {@link buildCtxSearchInputSchema} composes the Zod object used at
+ *     `registerTool` time, spreading the conditional `project` field only
+ *     when `isSharedMode` is true.
+ *   - {@link resolveProjectScope} normalises the raw param into the
+ *     three-state contract consumed by `searchAllSources`:
+ *       undefined → no filter
+ *       null      → explicit cross-project recall (no filter)
+ *       string    → restrict to that project directory
+ */
+import { z } from "zod";
+/**
+ * Build the Zod object passed to `server.registerTool("ctx_search", …)`.
+ *
+ * The base fields (`queries`, `limit`, `source`, `contentType`, `sort`)
+ * are always present and mirror today's contract exactly. The `project`
+ * field is only spread in when `isSharedMode` is true. When the host runs
+ * with the default per-project DB layout the schema does not expose the
+ * field at all, which keeps the tool surface honest about what is
+ * actionable in that mode.
+ */
+export declare function buildCtxSearchInputSchema(isSharedMode: boolean): z.ZodObject<{
+    queries: z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodString, "many">>, string[] | undefined, unknown>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    source: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodEnum<["code", "prose"]>>;
+    sort: z.ZodDefault<z.ZodOptional<z.ZodEnum<["relevance", "timeline"]>>>;
+} | {
+    project: z.ZodOptional<z.ZodString>;
+    queries: z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodString, "many">>, string[] | undefined, unknown>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    source: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodEnum<["code", "prose"]>>;
+    sort: z.ZodDefault<z.ZodOptional<z.ZodEnum<["relevance", "timeline"]>>>;
+}, "strip", z.ZodTypeAny, {
+    sort: "relevance" | "timeline";
+    limit: number;
+    source?: string | undefined;
+    contentType?: "code" | "prose" | undefined;
+    queries?: string[] | undefined;
+} | {
+    sort: "relevance" | "timeline";
+    limit: number;
+    source?: string | undefined;
+    contentType?: "code" | "prose" | undefined;
+    queries?: string[] | undefined;
+    project?: unknown;
+}, {
+    sort?: "relevance" | "timeline" | undefined;
+    source?: string | undefined;
+    limit?: number | undefined;
+    contentType?: "code" | "prose" | undefined;
+    queries?: unknown;
+} | {
+    sort?: "relevance" | "timeline" | undefined;
+    source?: string | undefined;
+    limit?: number | undefined;
+    contentType?: "code" | "prose" | undefined;
+    queries?: unknown;
+    project?: unknown;
+}>;
+/**
+ * Normalise the raw `project` value into the three-state contract consumed
+ * by {@link searchAllSources}.
+ *
+ *   - shared mode OFF                        → `undefined` (param ignored)
+ *   - shared mode ON, param `undefined`      → current project (`getProjectDirFn()`)
+ *   - shared mode ON, param `"global"`       → `null` (no filter — cross-project)
+ *   - shared mode ON, param `<string>`       → that string verbatim
+ *
+ * The function is pure so it stays trivially testable without spinning up
+ * the MCP server.
+ */
+export declare function resolveProjectScope(raw: string | undefined, isSharedMode: boolean, getProjectDirFn: () => string): string | null | undefined;
+/**
+ * Module-load snapshot of `CONTEXT_MODE_PROJECT_DIR`. Captured once so the
+ * tool schema registered with `server.registerTool` reflects the launch
+ * environment — the LLM-visible surface should never flip mid-session.
+ */
+export declare const CTX_SEARCH_SHARED_MODE: boolean;

package/build/search/ctx-search-schema.js

@@ -0,0 +1,135 @@
+/**
+ * ctx_search input-schema builder and project-scope resolver.
+ *
+ * Issue #737 introduces the optional `project:` parameter used by callers
+ * running in the shared-DB mode (`CONTEXT_MODE_PROJECT_DIR` is set). The
+ * field is registered conditionally so that in the default per-project DB
+ * mode the LLM physically cannot pass it — the parameter does not exist
+ * in the tool schema at all, which is a stronger guarantee than runtime
+ * validation that depends on the model honouring documentation.
+ *
+ * The handler in `src/server.ts` consumes both exports:
+ *   - {@link buildCtxSearchInputSchema} composes the Zod object used at
+ *     `registerTool` time, spreading the conditional `project` field only
+ *     when `isSharedMode` is true.
+ *   - {@link resolveProjectScope} normalises the raw param into the
+ *     three-state contract consumed by `searchAllSources`:
+ *       undefined → no filter
+ *       null      → explicit cross-project recall (no filter)
+ *       string    → restrict to that project directory
+ */
+import { z } from "zod";
+/**
+ * Helper that mirrors the Zod coercer used elsewhere in the server for
+ * array-shaped tool args. Kept inline so this module has no runtime
+ * dependency on `server.ts` (which would create a cycle).
+ *
+ * Behaviour mirrors `coerceJsonArray` in `server.ts`:
+ *   1. Empty / whitespace string → returned untouched so Zod surfaces the
+ *      "non-empty" error rather than masquerading as `[""]`.
+ *   2. Valid JSON array string → parsed and returned.
+ *   3. Any other plain string (a bare single query) → lifted to a
+ *      single-element array. Fixes #627 for the native OpenCode plugin
+ *      path where some providers deliver `queries: "search term"`.
+ */
+function coerceJsonArray(val) {
+    if (typeof val === "string") {
+        const trimmed = val.trim();
+        if (trimmed.length === 0)
+            return val;
+        try {
+            const parsed = JSON.parse(val);
+            if (Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            /* fall through — not JSON, treat as bare-string lift */
+        }
+        return [val];
+    }
+    return val;
+}
+/**
+ * Build the Zod object passed to `server.registerTool("ctx_search", …)`.
+ *
+ * The base fields (`queries`, `limit`, `source`, `contentType`, `sort`)
+ * are always present and mirror today's contract exactly. The `project`
+ * field is only spread in when `isSharedMode` is true. When the host runs
+ * with the default per-project DB layout the schema does not expose the
+ * field at all, which keeps the tool surface honest about what is
+ * actionable in that mode.
+ */
+export function buildCtxSearchInputSchema(isSharedMode) {
+    const projectField = isSharedMode
+        ? {
+            project: z
+                .string()
+                .optional()
+                .describe("Project scope. " +
+                "Default (omit): this session's project — auto-resolved from the host adapter. " +
+                "'global': span every project in the shared store (cross-project recall). " +
+                "<absolute-path>: scope to that specific project directory."),
+        }
+        : {};
+    return z.object({
+        queries: z.preprocess(coerceJsonArray, z
+            .array(z.string())
+            .optional()
+            .describe("Array of search queries. Batch ALL questions in one call.")),
+        // limit: z.coerce.number() (not z.number()) — OpenCode's native
+        // plugin path delivers tool args straight from the LLM provider's
+        // tool-call JSON, where several providers stringify primitives
+        // (limit:"4" instead of limit:4). Since v1.0.139 / #621 we run
+        // inputSchema.parse() on that path, so a plain z.number() rejects
+        // "4" with "Expected number, received string". z.coerce mirrors what
+        // ctx_batch_execute / ctx_fetch_and_index / ctx_execute already do.
+        // Fixes #627.
+        limit: z
+            .coerce.number()
+            .optional()
+            .default(3)
+            .describe("Results per query (default: 3)"),
+        source: z
+            .string()
+            .optional()
+            .describe("Filter to a specific indexed source (partial match)."),
+        contentType: z
+            .enum(["code", "prose"])
+            .optional()
+            .describe("Filter results by content type: 'code' or 'prose'."),
+        sort: z
+            .enum(["relevance", "timeline"])
+            .optional()
+            .default("relevance")
+            .describe("Sort mode. 'relevance' (default): BM25 ranked, current session only. " +
+            "'timeline': chronological across current session, prior sessions, and auto-memory."),
+        ...projectField,
+    });
+}
+/**
+ * Normalise the raw `project` value into the three-state contract consumed
+ * by {@link searchAllSources}.
+ *
+ *   - shared mode OFF                        → `undefined` (param ignored)
+ *   - shared mode ON, param `undefined`      → current project (`getProjectDirFn()`)
+ *   - shared mode ON, param `"global"`       → `null` (no filter — cross-project)
+ *   - shared mode ON, param `<string>`       → that string verbatim
+ *
+ * The function is pure so it stays trivially testable without spinning up
+ * the MCP server.
+ */
+export function resolveProjectScope(raw, isSharedMode, getProjectDirFn) {
+    if (!isSharedMode)
+        return undefined;
+    if (raw === undefined)
+        return getProjectDirFn();
+    if (raw === "global")
+        return null;
+    return raw;
+}
+/**
+ * Module-load snapshot of `CONTEXT_MODE_PROJECT_DIR`. Captured once so the
+ * tool schema registered with `server.registerTool` reflects the launch
+ * environment — the LLM-visible surface should never flip mid-session.
+ */
+export const CTX_SEARCH_SHARED_MODE = !!process.env.CONTEXT_MODE_PROJECT_DIR;

package/build/search/unified.d.ts

@@ -31,6 +31,18 @@ export interface SearchAllSourcesOpts {
     configDir?: string;
     /** Detected platform adapter — used for adapter-aware auto-memory. */
     adapter?: AutoMemoryAdapter;
+    /**
+     * Per-project scope for the ContentStore filter (#737). Only honoured
+     * when a `sessionDB` is also supplied (the 2-step IN-clause needs the
+     * SessionDB to translate `project_dir` → list of session ids).
+     *
+     *   - `undefined` — no project filter, today's behaviour.
+     *   - `null`      — cross-project recall in shared-DB mode (also no filter).
+     *   - `string`    — restrict ContentStore results to chunks attributed to
+     *                   session ids whose events match this `project_dir`,
+     *                   plus legacy `session_id=''` chunks (public surface).
+     */
+    projectScope?: string | null;
 }
 /**
  * Search across all available sources.

package/build/search/unified.js

@@ -20,14 +20,29 @@ const DEBUG = process.env.DEBUG?.includes("context-mode");
  * are always returned.
  */
 export function searchAllSources(opts) {
-    const { query, limit, store, sort = "relevance", source, contentType, sessionDB, projectDir, configDir, adapter, } = opts;
+    const { query, limit, store, sort = "relevance", source, contentType, sessionDB, projectDir, configDir, adapter, projectScope, } = opts;
     const results = [];
     // Capture session start time once — used as proxy for ContentStore items
     // (we don't know exact indexing time, but all content is from current session)
     const sessionStartTime = new Date().toISOString();
+    // ── Project scope (#737) ──
+    // Resolve the per-project session-id allow-set ONCE, before the
+    // ContentStore call. `projectScope === null` means cross-project recall —
+    // an explicit "no filter" choice surfaced by the ctx_search caller — and
+    // `undefined` falls back to today's unfiltered behaviour.
+    let sessionIdAllowSet;
+    if (typeof projectScope === "string" && sessionDB) {
+        try {
+            sessionIdAllowSet = new Set(sessionDB.getSessionIdsForProject(projectScope));
+        }
+        catch (e) {
+            if (DEBUG)
+                process.stderr.write(`[ctx] getSessionIdsForProject failed: ${e}\n`);
+        }
+    }
     // ── Source 1: ContentStore (always, both modes) ──
     try {
-        const storeResults = store.searchWithFallback(query, limit, source, contentType);
+        const storeResults = store.searchWithFallback(query, limit, source, contentType, "like", sessionIdAllowSet);
         results.push(...storeResults.map((r) => ({
             title: r.title,
             content: r.content,

package/build/server.d.ts

@@ -97,7 +97,8 @@ export declare function getProjectDir(): string;
  */
 export declare function positionsFromHighlight(highlighted: string): number[];
 export declare function extractSnippet(content: string, query: string, maxLen?: number, highlighted?: string): string;
-export declare function formatBatchQueryResults(store: ContentStore, queries: string[], source: string, maxOutput?: number): string[];
+export type BatchQueryScope = "batch" | "global";
+export declare function formatBatchQueryResults(store: ContentStore, queries: string[], source: string, maxOutput?: number, scope?: BatchQueryScope): string[];
 export interface BatchCommand {
     label: string;
     command: string;