context-mode 1.0.103 → 1.0.104

package/build/cli.d.ts

@@ -15,3 +15,18 @@
 export declare function toUnixPath(p: string): string;
 export declare function npmExecFile(args: string[], opts?: Record<string, unknown>): void;
 export declare function npmExec(command: string, opts?: Record<string, unknown>): void;
+/**
+ * Open a URL in the user's default browser without invoking a shell.
+ *
+ * Uses `execFile` with an arg array so the URL cannot be interpreted as
+ * shell metacharacters.  Original code used `execSync(`open "${url}"`)`
+ * which would shell-interpolate the URL — fragile if the URL ever
+ * becomes attacker-controlled (remote, weak port-validation, etc).
+ *
+ * Best-effort: if the OS opener is missing the function logs a copyable
+ * URL hint and returns; it never throws.  `runner` is injectable for
+ * tests; default is `child_process.execFile` (callback form, fire-and-
+ * forget).
+ */
+export type ExecFileFn = (file: string, args: readonly string[], opts?: Record<string, unknown>) => unknown;
+export declare function openInBrowser(url: string, platform?: NodeJS.Platform, runner?: ExecFileFn): void;

package/build/cli.js

@@ -13,7 +13,7 @@
  */
 import * as p from "@clack/prompts";
 import color from "picocolors";
-import { execFileSync } from "node:child_process";
+import { execFileSync, execFile as nodeExecFile } from "node:child_process";
 import { readFileSync, writeFileSync, cpSync, accessSync, existsSync, rmSync, closeSync, openSync, chmodSync, constants } from "node:fs";
 import { request as httpsRequest } from "node:https";
 import { resolve, dirname, join } from "node:path";
@@ -111,6 +111,11 @@ else if (args[0] === "hook") {
 else if (args[0] === "insight") {
     insight(args[1] ? Number(args[1]) : 4747);
 }
+else if (args[0] === "statusline") {
+    // Status line implementation lives in bin/statusline.mjs to keep it
+    // dependency-free and fast. Forward stdin and exit with its result.
+    statuslineForward();
+}
 else {
     // Default: start MCP server
     import("./server.js");
@@ -142,6 +147,37 @@ export function npmExec(command, opts = {}) {
         ...(isWin ? { shell: true } : {}),
     });
 }
+export function openInBrowser(url, platform = process.platform, runner = nodeExecFile) {
+    const opts = { stdio: "ignore" };
+    const hint = () => console.error(`\nCould not auto-open browser. Open manually: ${url}`);
+    try {
+        if (platform === "darwin") {
+            runner("open", [url], opts);
+        }
+        else if (platform === "win32") {
+            // `start` is a cmd.exe builtin; first arg after `start` is the
+            // window title — pass empty so the URL isn't consumed as a title.
+            runner("cmd", ["/c", "start", "", url], opts);
+        }
+        else {
+            // linux/bsd: try xdg-open, fall back to sensible-browser.
+            try {
+                runner("xdg-open", [url], opts);
+            }
+            catch {
+                try {
+                    runner("sensible-browser", [url], opts);
+                }
+                catch {
+                    hint();
+                }
+            }
+        }
+    }
+    catch {
+        hint();
+    }
+}
 function defaultPluginRoot() {
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
@@ -152,15 +188,19 @@ function defaultPluginRoot() {
     }
     return __dirname;
 }
-// Opencode/Kilocode install plugins from npm into .cache folder
+// Opencode/Kilocode install plugins from npm into a per-package cache folder.
+// Layout (changed silently in late 2024 — see PR #376 / KiloCode#9503):
+//   POSIX  : ~/.cache/<platform>/packages/context-mode@latest/node_modules/context-mode
+//   Windows: %LOCALAPPDATA%\<platform>\packages\context-mode@latest\node_modules\context-mode
 function cachePluginRoot(platform) {
+    const subPath = ["packages", "context-mode@latest", "node_modules", "context-mode"];
     if (process.platform === "win32") {
         const localApp = process.env.LOCALAPPDATA;
         if (localApp)
-            return resolve(localApp, platform, "node_modules", "context-mode");
-        return resolve(homedir(), "AppData", "Local", platform, "node_modules", "context-mode");
+            return resolve(localApp, platform, ...subPath);
+        return resolve(homedir(), "AppData", "Local", platform, ...subPath);
     }
-    return resolve(homedir(), ".cache", platform, "node_modules", "context-mode");
+    return resolve(homedir(), ".cache", platform, ...subPath);
 }
 function getPluginRoot() {
     const platform = detectPlatform().platform;
@@ -477,17 +517,8 @@ async function insight(port) {
             child.kill();
             process.exit(1);
         }
-        // Open browser
-        const platform = process.platform;
-        try {
-            if (platform === "darwin")
-                execSync(`open "${url}"`, { stdio: "pipe" });
-            else if (platform === "win32")
-                execSync(`start "" "${url}"`, { stdio: "pipe" });
-            else
-                execSync(`xdg-open "${url}" 2>/dev/null || sensible-browser "${url}" 2>/dev/null`, { stdio: "pipe" });
-        }
-        catch { /* best effort */ }
+        // Open browser — execFile with arg array, no shell interpolation.
+        openInBrowser(url);
         // Keep alive until Ctrl+C
         process.on("SIGINT", () => { child.kill(); process.exit(0); });
         process.on("SIGTERM", () => { child.kill(); process.exit(0); });
@@ -737,3 +768,18 @@ async function upgrade() {
             color.dim(` — restart your ${adapter.name} session to pick up the new version`));
     }
 }
+/* -------------------------------------------------------
+ * statusline — forward to bin/statusline.mjs
+ * ------------------------------------------------------- */
+function statuslineForward() {
+    const scriptPath = resolve(getPluginRoot(), "bin", "statusline.mjs");
+    if (!existsSync(scriptPath)) {
+        process.stderr.write(`statusline script missing: ${scriptPath}\n`);
+        process.exit(1);
+    }
+    // Re-exec via dynamic import so stdin/stdout are inherited cleanly.
+    import(pathToFileURL(scriptPath).href).catch((err) => {
+        process.stderr.write(`statusline failed: ${err?.message ?? err}\n`);
+        process.exit(1);
+    });
+}

package/build/concurrency/runPool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Generic in-flight-capped worker pool.
+ *
+ * Used by:
+ *   - runBatchCommands (ctx_batch_execute parallel branch)
+ *   - runBatchFetch    (ctx_fetch_and_index batch path)
+ *
+ * Returns Promise.allSettled-style results so one job's throw cannot
+ * strand siblings. Caller maps fulfilled/rejected per index. Output
+ * order is preserved by input index (not completion order).
+ *
+ * Designed to be the SINGLE concurrency primitive for the project —
+ * all "run N independent operations with at most M in flight" needs
+ * route here. Avoids the worker-pool copy-paste flagged in the
+ * concurrency PRD architectural review (finding G).
+ */
+export interface PoolJob<T> {
+    run(): Promise<T>;
+}
+export interface RunPoolOptions {
+    /** Hard concurrency cap (1-N). Auto-clamped to job count. */
+    concurrency: number;
+    /** Optional: also clamp by `os.cpus().length` (memory-pressure safety). Default false. */
+    capByCpuCount?: boolean;
+    /** Optional: per-settled callback (e.g. for progress reporting / metrics). */
+    onSettled?: (idx: number, result: PromiseSettledResult<unknown>) => void;
+}
+export interface RunPoolResult<T> {
+    /** Per-index settled result, ordered by input index. */
+    settled: PromiseSettledResult<T>[];
+    /** Concurrency actually used after all caps applied. */
+    effectiveConcurrency: number;
+    /** True when effectiveConcurrency < requested concurrency. */
+    capped: boolean;
+}
+export declare function runPool<T>(jobs: PoolJob<T>[], opts: RunPoolOptions): Promise<RunPoolResult<T>>;

package/build/concurrency/runPool.js

@@ -0,0 +1,51 @@
+/**
+ * Generic in-flight-capped worker pool.
+ *
+ * Used by:
+ *   - runBatchCommands (ctx_batch_execute parallel branch)
+ *   - runBatchFetch    (ctx_fetch_and_index batch path)
+ *
+ * Returns Promise.allSettled-style results so one job's throw cannot
+ * strand siblings. Caller maps fulfilled/rejected per index. Output
+ * order is preserved by input index (not completion order).
+ *
+ * Designed to be the SINGLE concurrency primitive for the project —
+ * all "run N independent operations with at most M in flight" needs
+ * route here. Avoids the worker-pool copy-paste flagged in the
+ * concurrency PRD architectural review (finding G).
+ */
+import { cpus } from "node:os";
+export async function runPool(jobs, opts) {
+    const { concurrency, capByCpuCount = false, onSettled } = opts;
+    if (jobs.length === 0) {
+        return { settled: [], effectiveConcurrency: 0, capped: false };
+    }
+    const requested = Math.max(1, concurrency);
+    const cpuCap = capByCpuCount ? Math.max(1, cpus().length) : requested;
+    const effectiveConcurrency = Math.min(requested, cpuCap, jobs.length);
+    const capped = effectiveConcurrency < requested;
+    const settled = new Array(jobs.length);
+    let nextIdx = 0;
+    async function worker() {
+        while (true) {
+            const idx = nextIdx++;
+            if (idx >= jobs.length)
+                return;
+            try {
+                const value = await jobs[idx].run();
+                settled[idx] = { status: "fulfilled", value };
+            }
+            catch (err) {
+                settled[idx] = { status: "rejected", reason: err };
+            }
+            onSettled?.(idx, settled[idx]);
+        }
+    }
+    const workers = [];
+    for (let w = 0; w < effectiveConcurrency; w++)
+        workers.push(worker());
+    // allSettled defends against any promise rejection escaping a worker
+    // (the worker already swallows its own errors, but this is belt-and-braces).
+    await Promise.allSettled(workers);
+    return { settled, effectiveConcurrency, capped };
+}

package/build/executor.d.ts

@@ -1,6 +1,16 @@
 import { type RuntimeMap, type Language } from "./runtime.js";
 export type { ExecResult } from "./types.js";
 import type { ExecResult } from "./types.js";
+/** Pure helper — exported for unit testing. Returns "script" or "script.<ext>". */
+export declare function buildScriptFilename(language: Language, platform: NodeJS.Platform): string;
+/**
+ * Pure helper — exported for unit testing. Adds `windowsHide: true` on Windows
+ * to prevent the spawned shell from creating a visible console window that
+ * intercepts stdout (issue #384).
+ */
+export declare function buildSpawnOptions(platform: NodeJS.Platform): {
+    windowsHide: boolean;
+};
 interface ExecuteOptions {
     language: Language;
     code: string;
@@ -15,7 +25,7 @@ export declare class PolyglotExecutor {
     #private;
     constructor(opts?: {
         hardCapBytes?: number;
-        projectRoot?: string;
+        projectRoot?: string | (() => string);
         runtimes?: RuntimeMap;
     });
     get runtimes(): RuntimeMap;

package/build/executor.js

@@ -4,6 +4,38 @@ import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { detectRuntimes, buildCommand, } from "./runtime.js";
 const isWin = process.platform === "win32";
+/**
+ * Pure helper: extension map for temp script files per language.
+ * On Windows, shell scripts get NO extension to avoid Windows file-association
+ * for `.sh` (which spawns a visible Git Bash window over the user's IDE).
+ */
+const SCRIPT_EXT = {
+    javascript: "js",
+    typescript: "ts",
+    python: "py",
+    shell: "sh",
+    ruby: "rb",
+    go: "go",
+    rust: "rs",
+    php: "php",
+    perl: "pl",
+    r: "R",
+    elixir: "exs",
+};
+/** Pure helper — exported for unit testing. Returns "script" or "script.<ext>". */
+export function buildScriptFilename(language, platform) {
+    if (platform === "win32" && language === "shell")
+        return "script";
+    return `script.${SCRIPT_EXT[language]}`;
+}
+/**
+ * Pure helper — exported for unit testing. Adds `windowsHide: true` on Windows
+ * to prevent the spawned shell from creating a visible console window that
+ * intercepts stdout (issue #384).
+ */
+export function buildSpawnOptions(platform) {
+    return { windowsHide: platform === "win32" };
+}
 /**
  * Resolve the real OS temp directory, bypassing any TMPDIR env override.
  * os.tmpdir() reads TMPDIR from the environment, which some shells/tools
@@ -39,15 +71,34 @@ function killTree(proc) {
 }
 export class PolyglotExecutor {
     #hardCapBytes;
-    #projectRoot;
+    /**
+     * Resolves the project root on every access. Stored as a thunk so the
+     * executor stays in sync with server-side env-cascade resolvers (e.g.
+     * `getProjectDir` in server.ts) instead of capturing a snapshot of
+     * `CLAUDE_PROJECT_DIR` at construction time. String inputs are wrapped
+     * to preserve constructor backward compatibility.
+     */
+    #projectRootResolver;
     #runtimes;
     /** PIDs of backgrounded processes — killed on cleanup to prevent zombies. */
     #backgroundedPids = new Set();
     constructor(opts) {
         this.#hardCapBytes = opts?.hardCapBytes ?? 100 * 1024 * 1024; // 100MB
-        this.#projectRoot = opts?.projectRoot ?? process.cwd();
+        const pr = opts?.projectRoot;
+        if (typeof pr === "function") {
+            this.#projectRootResolver = pr;
+        }
+        else if (typeof pr === "string") {
+            this.#projectRootResolver = () => pr;
+        }
+        else {
+            this.#projectRootResolver = () => process.cwd();
+        }
         this.#runtimes = opts?.runtimes ?? detectRuntimes();
     }
+    get #projectRoot() {
+        return this.#projectRootResolver();
+    }
     get runtimes() {
         return { ...this.#runtimes };
     }
@@ -101,19 +152,6 @@ export class PolyglotExecutor {
         return this.execute({ language, code: wrappedCode, timeout });
     }
     #writeScript(tmpDir, code, language) {
-        const extMap = {
-            javascript: "js",
-            typescript: "ts",
-            python: "py",
-            shell: "sh",
-            ruby: "rb",
-            go: "go",
-            rust: "rs",
-            php: "php",
-            perl: "pl",
-            r: "R",
-            elixir: "exs",
-        };
         // Go needs a main package wrapper if not present
         if (language === "go" && !code.includes("package ")) {
             code = `package main\n\nimport "fmt"\n\nfunc main() {\n${code}\n}\n`;
@@ -127,7 +165,7 @@ export class PolyglotExecutor {
             const escaped = JSON.stringify(join(this.#projectRoot, "_build/dev/lib"));
             code = `Path.wildcard(Path.join(${escaped}, "*/ebin"))\n|> Enum.each(&Code.prepend_path/1)\n\n${code}`;
         }
-        const fp = join(tmpDir, `script.${extMap[language]}`);
+        const fp = join(tmpDir, buildScriptFilename(language, process.platform));
         if (language === "shell") {
             writeFileSync(fp, code, { encoding: "utf-8", mode: 0o700 });
         }
@@ -186,6 +224,11 @@ export class PolyglotExecutor {
                 shell: needsShell,
                 // On Unix, create a new process group so killTree can kill all children
                 detached: !isWin,
+                // Hide the spawned-process console window on Windows. Without this,
+                // child_process.spawn creates a visible window that intercepts stdout,
+                // leaving the MCP response empty and popping a Git Bash terminal over
+                // the user's IDE. Issue #384.
+                ...buildSpawnOptions(process.platform),
             });
             let timedOut = false;
             let resolved = false;

package/build/fetch-cache.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cache-key / storage-label composition for ctx_fetch_and_index.
+ *
+ * Two distinct URLs that share a user-supplied `source` label MUST NOT collide
+ * in the cache (or in FTS5 storage, since indexing dedups by label). Compose
+ * `${source}::${url}` whenever a `source` is explicitly provided so cache
+ * lookup, dedup, and re-indexing are all per-(source,url). When no `source`
+ * is provided the URL itself is the unique key — no composition needed.
+ *
+ * `ctx_search(source: "Docs")` continues to work because LIKE-mode source
+ * filtering matches on the substring "Docs" inside "Docs::https://…".
+ */
+export declare function composeFetchCacheKey(source: string | undefined, url: string): string;

package/build/fetch-cache.js

@@ -0,0 +1,15 @@
+/**
+ * Cache-key / storage-label composition for ctx_fetch_and_index.
+ *
+ * Two distinct URLs that share a user-supplied `source` label MUST NOT collide
+ * in the cache (or in FTS5 storage, since indexing dedups by label). Compose
+ * `${source}::${url}` whenever a `source` is explicitly provided so cache
+ * lookup, dedup, and re-indexing are all per-(source,url). When no `source`
+ * is provided the URL itself is the unique key — no composition needed.
+ *
+ * `ctx_search(source: "Docs")` continues to work because LIKE-mode source
+ * filtering matches on the substring "Docs" inside "Docs::https://…".
+ */
+export function composeFetchCacheKey(source, url) {
+    return source === undefined ? url : `${source}::${url}`;
+}

package/build/lifecycle.d.ts

@@ -4,8 +4,12 @@
  * Detects parent process death (ppid polling) and OS signals to prevent
  * orphaned MCP server processes consuming 100% CPU (issue #103).
  *
- * Stdin close is NOT used as a shutdown signal — the MCP stdio transport
- * owns stdin and transient pipe events cause spurious -32000 errors (#236).
+ * Stdin close is NOT used as a *standalone* shutdown signal — the MCP stdio
+ * transport owns stdin and transient pipe events cause spurious -32000
+ * errors (#236). We do, however, treat stdin EOF as a hint to re-run the
+ * parent-liveness probe immediately (instead of waiting up to 30 s for the
+ * next poll tick), which closes the multi-day CPU-spin window seen in
+ * #311/#388 without reintroducing the false-positive shutdowns of #236.
  *
  * Cross-platform: macOS, Linux, Windows.
  */

package/build/lifecycle.js

@@ -4,8 +4,12 @@
  * Detects parent process death (ppid polling) and OS signals to prevent
  * orphaned MCP server processes consuming 100% CPU (issue #103).
  *
- * Stdin close is NOT used as a shutdown signal — the MCP stdio transport
- * owns stdin and transient pipe events cause spurious -32000 errors (#236).
+ * Stdin close is NOT used as a *standalone* shutdown signal — the MCP stdio
+ * transport owns stdin and transient pipe events cause spurious -32000
+ * errors (#236). We do, however, treat stdin EOF as a hint to re-run the
+ * parent-liveness probe immediately (instead of waiting up to 30 s for the
+ * next poll tick), which closes the multi-day CPU-spin window seen in
+ * #311/#388 without reintroducing the false-positive shutdowns of #236.
  *
  * Cross-platform: macOS, Linux, Windows.
  */
@@ -93,10 +97,33 @@ export function startLifecycleGuard(opts) {
         signals.push("SIGHUP");
     for (const sig of signals)
         process.on(sig, shutdown);
+    // P0: Stdin-EOF assist (#311/#388). The vendored MCP SDK's
+    // StdioServerTransport only registers 'data' / 'error' listeners — not
+    // 'end' — so when the parent (e.g. Claude Code) dies abruptly without
+    // sending SIGTERM, the server keeps reading from a half-closed pipe and
+    // CPU-spins until the 30 s ppid poll catches up. Observed in #388 with
+    // single processes accumulating ~80 h of CPU time before SIGKILL.
+    //
+    // We deliberately DO NOT call shutdown() unconditionally on 'end' — that
+    // is exactly the false-positive behavior #236 tore out. Instead we run
+    // the same isParentAlive() check the periodic timer uses, just earlier.
+    // If the parent is alive, this is a no-op and the existing #236
+    // regression test still passes; if the parent is gone, we collapse the
+    // 30 s detection window to ~0.
+    //
+    // Skipped on TTY (OpenCode ts-plugin) where stdin is not the MCP channel.
+    const onStdinEnd = () => {
+        if (!check())
+            shutdown();
+    };
+    if (!process.stdin.isTTY) {
+        process.stdin.on("end", onStdinEnd);
+    }
     return () => {
         stopped = true;
         clearInterval(timer);
         for (const sig of signals)
             process.removeListener(sig, shutdown);
+        process.stdin.removeListener("end", onStdinEnd);
     };
 }

package/build/opencode-plugin.d.ts

@@ -66,6 +66,12 @@ declare function createContextModePlugin(ctx: PluginContext): Promise<{
     "tool.execute.before": (input: BeforeHookInput, output: BeforeHookOutput) => Promise<void>;
     "tool.execute.after": (input: AfterHookInput, output: AfterHookOutput) => Promise<void>;
     "experimental.session.compacting": (input: CompactingHookInput, output: CompactingHookOutput) => Promise<string>;
+    "experimental.chat.messages.transform": (_input: unknown, output: {
+        messages?: Array<{
+            role: string;
+            content: string;
+        }>;
+    } | undefined) => Promise<void>;
 }>;
 declare const _default: {
     server: typeof createContextModePlugin;

package/build/opencode-plugin.js

@@ -25,9 +25,34 @@ import { SessionDB } from "./session/db.js";
 import { extractEvents } from "./session/extract.js";
 import { buildResumeSnapshot } from "./session/snapshot.js";
 import { OpenCodeAdapter } from "./adapters/opencode/index.js";
+import { PLATFORM_ENV_VARS } from "./adapters/detect.js";
 // ── Helpers ───────────────────────────────────────────────
+/**
+ * Detect whether the plugin is running under KiloCode or OpenCode.
+ *
+ * Reuses the canonical PLATFORM_ENV_VARS list (src/adapters/detect.ts) instead
+ * of hardcoding env var names — single source of truth, future-proof if Kilo
+ * or OpenCode add/rename env vars upstream.
+ *
+ * Order matters: KiloCode is an OpenCode fork and sets `OPENCODE=1` in
+ * addition to `KILO_PID`. PLATFORM_ENV_VARS lists `kilo` BEFORE `opencode`
+ * so KILO_PID wins the iteration.
+ *
+ * Pre-fix version was `return process.env.KILO_PID ? "kilo" : "opencode";` —
+ * surfaced by github.com/mksglu/context-mode/pull/376 (mikij). Full symmetric
+ * fix: also actively check opencode env vars instead of blind fallback.
+ */
 function getPlatform() {
-    return process.env.KILO_PID ? "kilo" : "opencode";
+    for (const [platform, vars] of PLATFORM_ENV_VARS) {
+        if (platform !== "kilo" && platform !== "opencode")
+            continue;
+        if (vars.some((v) => process.env[v])) {
+            return platform;
+        }
+    }
+    // Plugin host should always set one of the env vars. Fallback to opencode
+    // (the wider ecosystem) when neither is set, for predictable behavior.
+    return "opencode";
 }
 // ── Plugin Factory ────────────────────────────────────────
 /**
@@ -52,6 +77,10 @@ async function createContextModePlugin(ctx) {
     db.ensureSession(sessionId, projectDir);
     // Clean up old sessions on startup (replaces SessionStart hook)
     db.cleanupOldSessions(7);
+    // Track whether we've already injected the prior-session resume into
+    // a chat turn — `experimental.chat.messages.transform` fires on every
+    // turn, but we only want to inject once per process (SessionStart-equivalent).
+    let sessionStartInjected = false;
     return {
         // ── PreToolUse: Routing enforcement ─────────────────
         "tool.execute.before": async (input, output) => {
@@ -115,6 +144,36 @@ async function createContextModePlugin(ctx) {
                 return "";
             }
         },
+        // ── SessionStart equivalent (PR #376) ───────────────
+        // OpenCode lacks a real SessionStart hook (#14808, #5409) but
+        // recently added `experimental.chat.messages.transform`, which
+        // fires once per chat turn before messages are sent to the model.
+        // We piggyback on the *first* invocation per process to inject the
+        // most-recent resume snapshot from a prior session — matching what
+        // every other adapter's SessionStart hook does.
+        "experimental.chat.messages.transform": async (_input, output) => {
+            if (sessionStartInjected)
+                return;
+            sessionStartInjected = true;
+            try {
+                // Find the most recent resume snapshot for this project across
+                // any prior session. ContextSessionDB has no per-project resume
+                // lookup, so we fall back to the current session's resume row.
+                const row = db.getResume(sessionId);
+                const snapshot = row?.snapshot;
+                if (!snapshot || snapshot.length === 0)
+                    return;
+                if (output && Array.isArray(output.messages)) {
+                    output.messages.unshift({
+                        role: "system",
+                        content: snapshot,
+                    });
+                }
+            }
+            catch {
+                // Silent — never break the chat turn
+            }
+        },
     };
 }
 // ── Exports ──────────────────────────────────────────────

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