context-mode 1.0.162 → 1.0.164

package/build/lifecycle.js

@@ -11,6 +11,12 @@
  * next poll tick), which closes the multi-day CPU-spin window seen in
  * #311/#388 without reintroducing the false-positive shutdowns of #236.
  *
+ * Additionally, for MCP BRIDGE CHILDREN only (CONTEXT_MODE_BRIDGE_DEPTH>0), a
+ * request-idle self-shutdown reaps a child that a pi/omp sub-context abandoned
+ * while its long-lived parent keeps running (#854) — gated so the depth-0
+ * keep-alive servers #602 restored are never reaped, never via stdin EOF, and
+ * never while a tool call is in flight (#643).
+ *
  * Cross-platform: macOS, Linux, Windows.
  */
 import { execFileSync } from "node:child_process";
@@ -94,6 +100,80 @@ export function lifecycleGuardIntervalForEnv(env = process.env) {
         return 30_000;
     return 1000;
 }
+/**
+ * #854: idle-shutdown timeout (ms) for an MCP BRIDGE CHILD. Returns 0 (disabled)
+ * unless this process is a bridge child (CONTEXT_MODE_BRIDGE_DEPTH>0). depth-0 /
+ * absent always returns 0, so the long-lived keep-alive servers that #602
+ * restored are NEVER reaped on idle. Default for bridge children is 3 min;
+ * override with CONTEXT_MODE_BRIDGE_IDLE_MS (a non-positive value disables it).
+ * The reaper additionally never fires while a tool call is in flight (see
+ * {@link noteRequestStart}), so the window only bounds how fast *abandoned*
+ * children drain — it does not cap legitimate long-running calls.
+ *
+ * Exported for unit-testing.
+ */
+export function bridgeChildIdleTimeoutMs(env = process.env) {
+    const depth = Number.parseInt(env.CONTEXT_MODE_BRIDGE_DEPTH ?? "", 10);
+    if (!Number.isFinite(depth) || depth <= 0)
+        return 0;
+    const raw = env.CONTEXT_MODE_BRIDGE_IDLE_MS;
+    if (raw !== undefined) {
+        const v = Number.parseInt(raw, 10);
+        return Number.isFinite(v) && v > 0 ? v : 0;
+    }
+    return 180_000;
+}
+// #854 idle-reaper state, module-level by design: an MCP server is exactly one
+// process (one StdioServerTransport + one lifecycle guard), so these are never
+// shared across concurrent servers in production. Multiple startLifecycleGuard()
+// instances arise only in tests, which pair/reset these explicitly.
+/** Last MCP activity timestamp (inbound message, tool-call start/end, or response). */
+let _lastMcpActivity = Date.now();
+/** In-flight tool-call count — the reaper never fires while this is > 0. */
+let _inFlight = 0;
+/**
+ * #854: record MCP activity (inbound message or response). The server calls this
+ * so the bridge-child idle reaper in {@link startLifecycleGuard} can distinguish
+ * an actively-used child from an abandoned one. Cheap; safe on the hot path.
+ */
+export function noteMcpActivity() {
+    _lastMcpActivity = Date.now();
+}
+/**
+ * #854: mark a tool call as started. Suppresses the bridge-child idle reaper so a
+ * single long-running ctx_execute / ctx_batch_execute (which sends one inbound
+ * frame then runs unbounded, #643) is never reaped mid-execution.
+ */
+export function noteRequestStart() {
+    _inFlight++;
+    _lastMcpActivity = Date.now();
+}
+/** #854: mark a tool call as finished (success or error). */
+export function noteRequestEnd() {
+    if (_inFlight > 0)
+        _inFlight--;
+    _lastMcpActivity = Date.now();
+}
+/**
+ * #854: wrap an MCP stdio transport's `onmessage` so each inbound message
+ * refreshes the idle clock. Best-effort: call after `connect()` (onmessage set);
+ * a no-op if it isn't a function, and a throw in noteMcpActivity never breaks
+ * dispatch. No stdin touch (preserves the #236 contract). Exported for testing.
+ */
+export function attachMcpActivityTap(transport) {
+    if (!transport)
+        return;
+    const prev = typeof transport.onmessage === "function" ? transport.onmessage.bind(transport) : null;
+    if (!prev)
+        return;
+    transport.onmessage = (message, extra) => {
+        try {
+            noteMcpActivity();
+        }
+        catch { /* never break message dispatch */ }
+        return prev(message, extra);
+    };
+}
 /**
  * Start the lifecycle guard. Returns a cleanup function.
  * Skipped automatically when stdin is a TTY (e.g. OpenCode ts-plugin).
@@ -142,9 +222,40 @@ export function startLifecycleGuard(opts) {
     if (!process.stdin.isTTY) {
         process.stdin.on("end", onStdinEnd);
     }
+    // #854: request-idle self-shutdown for MCP BRIDGE CHILDREN only
+    // (CONTEXT_MODE_BRIDGE_DEPTH>0). Pi/omp loads the extension once per
+    // sub-context and spawns one bridge child each, tearing them down only at
+    // session_shutdown — which never fires for sub-contexts while the long-lived
+    // parent stays alive, so idle children accumulate (#854, same class as #565).
+    // A bridge child that receives no inbound MCP message for `idleMs` exits
+    // itself; the extension's single-flight path respawns one on the next call.
+    //
+    // Scoped strictly to depth>0 so the depth-0 keep-alive servers that #602
+    // restored are never reaped on idle. The trigger is idle TIME via
+    // noteMcpActivity() (NOT stdin EOF), so the #236 contract — and lifecycle's
+    // hands-off-stdin invariant — are untouched.
+    const idleMs = opts.bridgeIdleMs ?? bridgeChildIdleTimeoutMs();
+    let idleTimer;
+    if (idleMs > 0) {
+        _lastMcpActivity = Date.now();
+        idleTimer = setInterval(() => {
+            // Reap only when truly quiescent: NO tool call in flight AND no MCP
+            // activity for `idleMs`. The in-flight guard prevents reaping a child
+            // mid-execution during a long single ctx_execute/batch that sends no
+            // further messages (#643 unbounded calls) — the false-reap regression the
+            // adversarial review flagged.
+            if (_inFlight === 0 && Date.now() - _lastMcpActivity >= idleMs) {
+                process.stderr.write(`[context-mode] idle MCP bridge child self-shutdown after ${idleMs}ms with no activity (#854)\n`);
+                shutdown();
+            }
+        }, Math.max(1000, Math.min(Math.floor(idleMs / 4), 30_000)));
+        idleTimer.unref();
+    }
     return () => {
         stopped = true;
         clearInterval(timer);
+        if (idleTimer)
+            clearInterval(idleTimer);
         for (const sig of signals)
             process.removeListener(sig, shutdown);
         process.stdin.removeListener("end", onStdinEnd);

package/build/opencode-plugin.js

@@ -179,7 +179,7 @@ async function createContextModePlugin(ctx) {
             const toolInput = output.args ?? {};
             let decision;
             try {
-                decision = routing.routePreToolUse(toolName, toolInput, projectDir, getPlatform());
+                decision = routing.routePreToolUse(toolName, toolInput, projectDir, platform);
             }
             catch {
                 return; // Routing failure → allow passthrough
@@ -194,7 +194,10 @@ async function createContextModePlugin(ctx) {
                 // Mutate output.args — OpenCode reads the mutated output object
                 Object.assign(output.args, decision.updatedInput);
             }
-            // "context" action → no-op (OpenCode doesn't support context injection)
+            if (decision.action === "context" && decision.additionalContext) {
+                // Mutate output.args — OpenCode reads the mutated output object
+                output.args.additionalContext = decision.additionalContext;
+            }
         },
         // ── PostToolUse: Session event capture ──────────────
         "tool.execute.after": async (input, output) => {

package/build/routing-block.d.ts

@@ -0,0 +1,8 @@
+import type { ToolNamer } from "./tool-naming.js";
+export interface RoutingBlockOptions {
+    includeCommands?: boolean;
+}
+export declare function createRoutingBlock(t: ToolNamer, options?: RoutingBlockOptions): string;
+export declare function createReadGuidance(t: ToolNamer): string;
+export declare function createGrepGuidance(t: ToolNamer): string;
+export declare function createBashGuidance(t: ToolNamer): string;

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);
+    }
+}