context-mode 1.0.161 → 1.0.163

package/build/routing-block.js

@@ -0,0 +1,86 @@
+export function createRoutingBlock(t, options = {}) {
+    const { includeCommands = true } = options;
+    return `
+<context_window_protection>
+  <priority_instructions>
+    Raw tool output floods context window. MUST use context-mode MCP tools. Keep raw data in sandbox.
+  </priority_instructions>
+
+  <tool_selection_hierarchy>
+    0. MEMORY: ${t("ctx_search")}(sort: "timeline")
+       - After resume, check prior context before asking user.
+    1. GATHER: ${t("ctx_batch_execute")}(commands, queries)
+       - Primary research tool. Runs commands, auto-indexes, searches. ONE call replaces many steps.
+       - Each command: {label: "section header", command: "shell command"}
+       - label becomes FTS5 chunk title — descriptive labels improve search.
+    2. FOLLOW-UP: ${t("ctx_search")}(queries: ["q1", "q2", ...])
+       - All follow-up questions. ONE call, many queries (default relevance mode).
+    3. PROCESSING: ${t("ctx_execute")}(language, code) | ${t("ctx_execute_file")}(path, language, code)
+       - API calls, log analysis, data processing.
+  </tool_selection_hierarchy>
+
+  <forbidden_actions>
+    - NO Bash for commands producing >20 lines output.
+    - NO Read for analysis — use execute_file. Read IS correct for files you intend to Edit.
+    - NO WebFetch — use ${t("ctx_fetch_and_index")}.
+    - Bash ONLY for git/mkdir/rm/mv/navigation.
+    - NO ${t("ctx_execute")} or ${t("ctx_execute_file")} for file creation/modification.
+      ctx_execute is for analysis, processing, computation only.
+  </forbidden_actions>
+
+  <file_writing_policy>
+    ALWAYS use native Write/Edit tools for file creation/modification.
+    NEVER use ${t("ctx_execute")}, ${t("ctx_execute_file")}, or Bash to write files.
+    Applies to all file types: code, configs, plans, specs, YAML, JSON, markdown.
+  </file_writing_policy>
+
+  <output_constraints>
+    <communication_style>
+      Terse like caveman. Technical substance exact. Only fluff die.
+      Use fragments when clear. Short synonyms (fix not "implement a solution for").
+      Technical terms exact. Code blocks unchanged.
+      Auto-expand for: security warnings, irreversible actions, user confusion.
+    </communication_style>
+    <artifact_policy>
+      Write artifacts (code, configs, PRDs) to FILES. NEVER inline.
+      Return only: file path + 1-line description.
+    </artifact_policy>
+    <response_format>
+      Concise summary:
+      - Actions taken (2-3 bullets)
+      - File paths created/modified
+      - Key findings
+    </response_format>
+  </output_constraints>
+  <session_continuity>
+    Skills, roles, and decisions set during this session remain active until the user revokes them.
+    Do not drop behavioral directives as context grows.
+  </session_continuity>
+${includeCommands ? `
+  <ctx_commands>
+    "ctx stats" | "ctx-stats" | "/ctx-stats" | context savings question
+    → Call stats MCP tool, display full output verbatim.
+
+    "ctx doctor" | "ctx-doctor" | "/ctx-doctor" | diagnose context-mode
+    → Call doctor MCP tool, run returned shell command, display as checklist.
+
+    "ctx upgrade" | "ctx-upgrade" | "/ctx-upgrade" | update context-mode
+    → Call upgrade MCP tool, run returned shell command, display as checklist.
+
+    "ctx purge" | "ctx-purge" | "/ctx-purge" | wipe/reset knowledge base
+    → Call purge MCP tool with confirm: true. Warn: irreversible.
+
+    After /clear or /compact: knowledge base preserved. Tell user: "context-mode knowledge base preserved. Use \`ctx purge\` to start fresh."
+  </ctx_commands>
+` : ''}
+</context_window_protection>`;
+}
+export function createReadGuidance(t) {
+    return '<context_guidance>\n  <tip>\n    Reading to Edit? Read is correct — Edit needs content in context.\n    Reading to analyze/explore? Use ' + t("ctx_execute_file") + '(path, language, code) — only printed summary enters context.\n  </tip>\n</context_guidance>';
+}
+export function createGrepGuidance(t) {
+    return '<context_guidance>\n  <tip>\n    May flood context. Use ' + t("ctx_execute") + '(language: "shell", code: "...") to run searches in sandbox. Only printed summary enters context.\n  </tip>\n</context_guidance>';
+}
+export function createBashGuidance(t) {
+    return '<context_guidance>\n  <tip>\n    May produce large output. Use ' + t("ctx_batch_execute") + '(commands, queries) for multiple commands, ' + t("ctx_execute") + '(language: "shell", code: "...") for single. Only printed summary enters context. Bash only for: git, mkdir, rm, mv, navigation.\n  </tip>\n</context_guidance>';
+}

package/build/runtime.d.ts

@@ -65,42 +65,6 @@ export interface HookRuntime {
  * 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[];

package/build/runtime.js

@@ -27,6 +27,10 @@ function isWindowsWslBash(shellPath) {
     return /\\windows\\(?:system32|sysnative)\\bash\.exe$/.test(lower) ||
         /\\microsoft\\windowsapps\\bash\.exe$/.test(lower);
 }
+function isWindowsSystemCmd(shellPath) {
+    const lower = shellPath.toLowerCase().replace(/\//g, "\\");
+    return /\\windows\\(?:system32|sysnative)\\cmd\.exe$/.test(lower);
+}
 const isWindows = process.platform === "win32";
 function commandExists(cmd) {
     try {
@@ -130,38 +134,69 @@ function bunFallbackPaths() {
     }
     return home ? [`${home}/.bun/bin/bun`] : [];
 }
+/** Well-known Git-for-Windows bash.exe locations (MSYS bash that performs
+ *  Windows→POSIX path conversion for native git — #826). */
+const KNOWN_GIT_BASH_PATHS = [
+    "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+    "C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe",
+];
 /**
- * On Windows, resolve the first non-WSL bash in PATH.
- * WSL bash (C:\Windows\System32\bash.exe) cannot handle Windows paths,
- * so we skip it and prefer Git Bash or MSYS2 bash instead.
+ * On Windows, resolve the first non-WSL bash that is actually available.
+ *
+ * Availability is gated by `where bash` (#796): bash must be discoverable on
+ * PATH for us to claim it. WSL bash (C:\Windows\System32\bash.exe) cannot
+ * handle Windows paths, so we skip it and prefer Git Bash / MSYS2 bash.
+ *
+ * Routing the gate through `where bash` — rather than probing the known Git
+ * Bash paths with existsSync first — is deliberate: when bash is genuinely
+ * unavailable, the caller must fall through to pwsh (PR intent). Probing the
+ * filesystem first re-detected a real Git Bash on the runner even though the
+ * scenario was "bash unavailable", so pwsh was never reached.
+ *
+ * #826 is preserved: when `where bash` surfaces a Git Bash candidate we
+ * canonicalize it to the absolute Git\usr\bin\bash.exe path (so native git
+ * keeps MSYS path conversion) by preferring a matching known path that exists.
  */
 function resolveWindowsBash() {
-    // First, try well-known Git Bash locations directly (works even when
-    // Git\usr\bin is not on PATH, which is common in MCP server environments
-    // that only inherit Git\cmd from the system PATH).
-    const knownPaths = [
-        "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
-        "C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe",
-    ];
-    for (const p of knownPaths) {
-        if (existsSync(p))
-            return p;
-    }
-    // Fallback: scan PATH via `where bash`, skipping WSL and WindowsApps entries.
+    let candidates;
     try {
         const result = execSync("where bash", { encoding: "utf-8", stdio: "pipe" });
-        const candidates = result.trim().split(/\r?\n/).map(p => p.trim()).filter(Boolean);
-        for (const p of candidates) {
-            const lower = p.toLowerCase();
-            if (lower.includes("system32") || lower.includes("windowsapps"))
-                continue;
-            return p;
-        }
-        return null;
+        candidates = result.trim().split(/\r?\n/).map(p => p.trim()).filter(Boolean);
     }
     catch {
+        // bash not on PATH → genuinely unavailable. Fall through to pwsh/etc.
         return null;
     }
+    for (const p of candidates) {
+        const lower = p.toLowerCase();
+        if (lower.includes("system32") || lower.includes("windowsapps"))
+            continue;
+        // Prefer the canonical Git\usr\bin\bash.exe so native git retains MSYS
+        // path conversion. `where bash` on a Git-for-Windows install may surface
+        // the Git\cmd\bash shim or usr\bin path; upgrade to a known absolute path
+        // when one exists on disk.
+        for (const known of KNOWN_GIT_BASH_PATHS) {
+            if (existsSync(known))
+                return known;
+        }
+        return p;
+    }
+    return null;
+}
+function resolveWindowsShell(windowsBash = resolveWindowsBash()) {
+    // Prefer Git Bash (#826) so native git keeps its MSYS path conversion.
+    // The caller passes the already-resolved windowsBash to avoid probing the
+    // filesystem twice (it also feeds the cmd.exe shellOverride guard above).
+    // Fall back through POSIX sh, then PowerShell Core (pwsh) for proper UTF-8
+    // handling, then Windows PowerShell, then cmd.exe as the last resort.
+    return windowsBash
+        ?? (commandExists("sh")
+            ? "sh"
+            : commandExists("pwsh")
+                ? "pwsh"
+                : commandExists("powershell")
+                    ? "powershell"
+                    : "cmd.exe");
 }
 function getVersion(cmd, args = ["--version"]) {
     try {
@@ -231,7 +266,17 @@ export function resolveJavascriptRuntime(bun, deps = {}) {
     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;
+        //
+        // Issue #800 — liveness guard: on Homebrew, process.execPath points into
+        // the versioned Cellar (/opt/homebrew/Cellar/node/26.0.0/bin/node).
+        // `brew upgrade` + `brew cleanup` deletes the old Cellar, so the path
+        // dangles for the life of the already-running MCP server.  If the path
+        // doesn't exist on disk, skip it and fall through to PATH node.
+        if (existsSync(execPath)) {
+            return execPath;
+        }
+        // Stale execPath (deleted Cellar, corrupted install, uninstall while
+        // process alive).  Fall through to PATH resolution below.
     }
     // Host binary (opencode/kilo/etc.) — fall back to node on PATH.
     if (cmdExists("node"))
@@ -252,10 +297,15 @@ export function detectRuntimes() {
     // could redirect the executor to /usr/bin/python or any arbitrary binary.
     const userShell = process.env.SHELL;
     const isWin = process.platform === "win32";
+    const windowsBash = isWin ? resolveWindowsBash() : null;
     const shellOverride = userShell &&
         existsSync(userShell) &&
         isAllowlistedShell(userShell) &&
-        !(isWin && isWindowsWslBash(userShell))
+        !(isWin && isWindowsWslBash(userShell)) &&
+        // Windows OpenSSH can inject the system cmd.exe as ambient SHELL. When
+        // Git Bash is installed, treating that as an explicit override breaks the
+        // POSIX shell executor path restored by #36/#384/#791.
+        !(isWin && windowsBash && isWindowsSystemCmd(userShell))
         ? userShell
         : null;
     return {
@@ -275,7 +325,7 @@ export function detectRuntimes() {
                     ? "py"
                     : null,
         shell: shellOverride ?? (isWin
-            ? (resolveWindowsBash() ?? (commandExists("sh") ? "sh" : commandExists("powershell") ? "powershell" : "cmd.exe"))
+            ? resolveWindowsShell(windowsBash)
             : commandExists("bash") ? "bash" : "sh"),
         ruby: commandExists("ruby") ? "ruby" : null,
         go: commandExists("go") ? "go" : null,
@@ -360,10 +410,40 @@ function bunVersionAtLeast1(versionOutput) {
  *     reason.
  *   - `ctx_upgrade` — separate path, must stay on Node for the same reason.
  */
+/**
+ * Liveness-guarded Node path for the hook-runtime fallback (issue #841).
+ *
+ * `process.execPath` is pinned into every baked hook command because PATH
+ * resolution is unreliable for hooks (#190 snap-Node re-invokes the wrapper;
+ * #369 Windows Git Bash / MSYS can't resolve a bare `node`). But under a
+ * version manager (mise / asdf / nvm) execPath is a *version-pinned* absolute
+ * path — e.g. `~/.local/share/mise/installs/node/20.1.0/bin/node`. A routine
+ * `mise upgrade node` installs the next patch and DELETES the 20.1.0 dir, so
+ * the cached path dangles and every hook spawn fails with ENOENT — silently
+ * killing context-mode for that user.
+ *
+ * Same liveness-guard shape as the #800/#803 fix in
+ * {@link resolveJavascriptRuntime}: use the pinned execPath IFF it still
+ * exists on disk (preserving the #190/#369 reasons it was pinned), otherwise
+ * re-resolve a working `node` from PATH. The version manager's shim dir is on
+ * PATH and always points at the current patch, so bare `node` heals the host
+ * without a re-install. Falls back to the (stale) execPath only when no PATH
+ * node is reachable either — a strictly-better last resort than a dangling
+ * versioned path, and the doctor/upgrade flows surface the actionable error.
+ */
+function liveNodeRuntime() {
+    if (existsSync(process.execPath)) {
+        return { path: process.execPath, isBun: false };
+    }
+    if (commandExists("node")) {
+        return { path: "node", isBun: false };
+    }
+    return { path: process.execPath, isBun: false };
+}
 export function resolveHookRuntime() {
     if (_hookRuntimeCache)
         return _hookRuntimeCache;
-    const nodeFallback = { path: process.execPath, isBun: false };
+    const nodeFallback = liveNodeRuntime();
     try {
         if (!bunExists()) {
             _hookRuntimeCache = nodeFallback;

package/build/search/flood-guard.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ctx_search flood-guard — per-agent-context progressive throttle.
+ *
+ * Background (#79 / #155 / #697): ctx_search carries a progressive throttle
+ * so a single actor cannot spam dozens of individual searches and flood the
+ * context window instead of batching via ctx_batch_execute. The original
+ * implementation kept ONE module-global counter on the MCP server process.
+ *
+ * Issue #769: a parallel multi-agent fan-out (Claude Code Task/Workflow)
+ * runs N subagents concurrently against the SAME per-session MCP server
+ * process. With a single global counter their independent calls are summed
+ * into one budget, so legitimate fan-out ("10 agents x 2 calls") trips the
+ * guard that was only ever meant to catch ONE actor spamming. The budget is
+ * tool-availability state that is logically per-agent-context, so the counter
+ * must be keyed per agent-context — NOT removed. Single-actor flood
+ * protection is preserved exactly; only the bucketing changes.
+ *
+ * This module is pure and transport-free so the policy is unit-testable
+ * without spinning up the MCP server. `src/server.ts` owns the singleton and
+ * supplies the per-call agent key (the session/agent id from
+ * currentAttribution()).
+ */
+export interface FloodGuardConfig {
+    /** Rolling window length in ms. After this elapses a key's counter resets. */
+    windowMs: number;
+    /** After this many calls in the window, results taper to 1 per query. */
+    softCapAfter: number;
+    /** After this many calls in the window, the call is hard-blocked. */
+    blockAfter: number;
+}
+export interface FloodDecision {
+    /** This key's call count within the current rolling window (1-based). */
+    count: number;
+    /** Window start timestamp (ms) for this key — used for the "in Ns" message. */
+    windowStart: number;
+    /** True once count exceeds blockAfter — caller must refuse the search. */
+    blocked: boolean;
+    /** True once count exceeds softCapAfter — caller trims to 1 result/query. */
+    softCapped: boolean;
+}
+/**
+ * A rolling-window call counter bucketed per agent-context key. Each key gets
+ * an independent window + counter, so concurrent subagents do not consume one
+ * another's budget while a single greedy actor is still throttled and blocked
+ * exactly as before.
+ */
+export declare class FloodGuard {
+    #private;
+    constructor(cfg: FloodGuardConfig, maxKeys?: number);
+    /**
+     * Record one ctx_search call for `key` at time `now` (ms) and return the
+     * throttle decision. Pure aside from the internal per-key counter state.
+     */
+    record(key: string, now?: number): FloodDecision;
+    /** Test/diagnostics helper — number of distinct keys currently tracked. */
+    size(): number;
+}

package/build/search/flood-guard.js

@@ -0,0 +1,80 @@
+/**
+ * ctx_search flood-guard — per-agent-context progressive throttle.
+ *
+ * Background (#79 / #155 / #697): ctx_search carries a progressive throttle
+ * so a single actor cannot spam dozens of individual searches and flood the
+ * context window instead of batching via ctx_batch_execute. The original
+ * implementation kept ONE module-global counter on the MCP server process.
+ *
+ * Issue #769: a parallel multi-agent fan-out (Claude Code Task/Workflow)
+ * runs N subagents concurrently against the SAME per-session MCP server
+ * process. With a single global counter their independent calls are summed
+ * into one budget, so legitimate fan-out ("10 agents x 2 calls") trips the
+ * guard that was only ever meant to catch ONE actor spamming. The budget is
+ * tool-availability state that is logically per-agent-context, so the counter
+ * must be keyed per agent-context — NOT removed. Single-actor flood
+ * protection is preserved exactly; only the bucketing changes.
+ *
+ * This module is pure and transport-free so the policy is unit-testable
+ * without spinning up the MCP server. `src/server.ts` owns the singleton and
+ * supplies the per-call agent key (the session/agent id from
+ * currentAttribution()).
+ */
+/**
+ * A rolling-window call counter bucketed per agent-context key. Each key gets
+ * an independent window + counter, so concurrent subagents do not consume one
+ * another's budget while a single greedy actor is still throttled and blocked
+ * exactly as before.
+ */
+export class FloodGuard {
+    #cfg;
+    #buckets = new Map();
+    /**
+     * Hard ceiling on tracked keys — a defensive bound so a pathological host
+     * that mints unbounded distinct agent ids cannot grow the map without limit.
+     * When exceeded, the oldest-window bucket is evicted (its actor simply gets
+     * a fresh window on its next call — fail-open, never a false block).
+     */
+    #maxKeys;
+    constructor(cfg, maxKeys = 4096) {
+        this.#cfg = cfg;
+        this.#maxKeys = Math.max(1, maxKeys);
+    }
+    /**
+     * Record one ctx_search call for `key` at time `now` (ms) and return the
+     * throttle decision. Pure aside from the internal per-key counter state.
+     */
+    record(key, now = Date.now()) {
+        let bucket = this.#buckets.get(key);
+        if (!bucket || now - bucket.windowStart > this.#cfg.windowMs) {
+            bucket = { count: 0, windowStart: now };
+            this.#buckets.set(key, bucket);
+            this.#evictIfNeeded();
+        }
+        bucket.count++;
+        return {
+            count: bucket.count,
+            windowStart: bucket.windowStart,
+            blocked: bucket.count > this.#cfg.blockAfter,
+            softCapped: bucket.count > this.#cfg.softCapAfter,
+        };
+    }
+    /** Test/diagnostics helper — number of distinct keys currently tracked. */
+    size() {
+        return this.#buckets.size;
+    }
+    #evictIfNeeded() {
+        if (this.#buckets.size <= this.#maxKeys)
+            return;
+        let oldestKey;
+        let oldestStart = Infinity;
+        for (const [k, b] of this.#buckets) {
+            if (b.windowStart < oldestStart) {
+                oldestStart = b.windowStart;
+                oldestKey = k;
+            }
+        }
+        if (oldestKey !== undefined)
+            this.#buckets.delete(oldestKey);
+    }
+}

package/build/security.d.ts

@@ -41,14 +41,19 @@ export declare function fileGlobToRegex(glob: string, caseInsensitive?: boolean)
  */
 export declare function matchesAnyPattern(command: string, patterns: string[], caseInsensitive?: boolean): string | null;
 /**
- * Split a shell command on chain operators (&&, ||, ;, |) while
- * respecting single/double quotes and backticks.
+ * Split a shell command on chain operators (&&, ||, ;, |, \n, \r, &) while
+ * respecting single/double quotes, backticks, subshells, and escape backslashes.
  *
  * "echo hello && sudo rm -rf /" → ["echo hello", "sudo rm -rf /"]
  *
  * This prevents bypassing deny patterns by prepending innocent commands.
  */
 export declare function splitChainedCommands(command: string): string[];
+/**
+ * Recursively extract all nested subshell commands from `$()` and `` `...` ``.
+ * Handles escaping and quote contexts to ensure correct command boundary detection.
+ */
+export declare function extractSubshellCommands(command: string): string[];
 /**
  * Read Bash permission policies from up to 3 settings files.
  *
@@ -93,7 +98,7 @@ export declare function evaluateCommand(command: string, policies: SecurityPolic
  * The server has no UI for "ask" prompts, so allow/ask patterns are
  * irrelevant. Returns "deny" if any deny pattern matches, otherwise "allow".
  *
- * Also splits chained commands to prevent bypass.
+ * Also splits chained commands and nested subshells to prevent bypass.
  */
 export declare function evaluateCommandDenyOnly(command: string, policies: SecurityPolicy[], caseInsensitive?: boolean): {
     decision: "deny" | "allow";