context-mode 1.0.103 → 1.0.105

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

@@ -1,3 +1,4 @@
+export declare function isAllowlistedShell(shellPath: string): boolean;
 export type Language = "javascript" | "typescript" | "python" | "shell" | "ruby" | "go" | "rust" | "php" | "perl" | "r" | "elixir";
 export interface RuntimeInfo {
     command: string;

package/build/runtime.js

@@ -1,5 +1,23 @@
 import { execFileSync, execSync } from "node:child_process";
 import { existsSync } from "node:fs";
+/**
+ * Allowlist for SHELL env override. Only POSIX shells + Windows shells permit
+ * arbitrary command interpretation; anything else (e.g., /usr/bin/python set
+ * as SHELL) would let an attacker redirect the executor to a non-shell binary.
+ *
+ * basename split handles BOTH `/` and `\` separators so a Windows-style path
+ * (`C:\Program Files\PowerShell\7\pwsh.exe`) classifies correctly even when
+ * the runtime is on POSIX (where node:path.basename only splits on `/`).
+ *
+ * Match is case-insensitive; `.exe` extension tolerated for Windows binaries.
+ */
+const ALLOWED_SHELL_BASENAMES = /^(bash|sh|zsh|dash|pwsh|powershell|cmd)(\.exe)?$/i;
+export function isAllowlistedShell(shellPath) {
+    // Cross-OS basename: split on either separator, take the last segment.
+    const segments = shellPath.split(/[\\/]/);
+    const base = segments[segments.length - 1];
+    return ALLOWED_SHELL_BASENAMES.test(base);
+}
 const isWindows = process.platform === "win32";
 function commandExists(cmd) {
     try {
@@ -93,6 +111,19 @@ function getVersion(cmd, args = ["--version"]) {
 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.
+    //
+    // Allowlist (PR #401 ops review): basename must match
+    // /^(bash|sh|zsh|dash|pwsh|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)
+        ? userShell
+        : null;
+    const isWin = process.platform === "win32";
     return {
         javascript: bun ?? process.execPath,
         typescript: bun
@@ -107,9 +138,9 @@ export function detectRuntimes() {
             : commandExists("python")
                 ? "python"
                 : null,
-        shell: isWindows
+        shell: shellOverride ?? (isWin
             ? (resolveWindowsBash() ?? (commandExists("sh") ? "sh" : commandExists("powershell") ? "powershell" : "cmd.exe"))
-            : commandExists("bash") ? "bash" : "sh",
+            : commandExists("bash") ? "bash" : "sh"),
         ruby: commandExists("ruby") ? "ruby" : null,
         go: commandExists("go") ? "go" : null,
         rust: commandExists("rustc") ? "rustc" : null,
@@ -206,8 +237,28 @@ export function buildCommand(runtimes, language, filePath) {
                 throw new Error("No Python runtime available. Install python3 or python.");
             }
             return [runtimes.python, filePath];
-        case "shell":
+        case "shell": {
+            // Re-evaluate platform per call so detection-time and command-build-time
+            // can be tested independently (and to allow tests to stub process.platform).
+            const winNow = process.platform === "win32";
+            if (winNow) {
+                const shellName = runtimes.shell.toLowerCase();
+                if (shellName.includes("bash") || shellName.endsWith("/sh") || shellName.endsWith("\\sh.exe")) {
+                    // bash -c "source 'path'" — avoids MSYS2 path mangling on non-C:
+                    // drives. When bash.exe receives a script as a direct argument,
+                    // MSYS rewrites D:\tmp\script → D:\c\tmp\script and execution
+                    // breaks. The -c flag prevents MSYS from touching the file arg.
+                    // Single-quote escape: ' → '\''
+                    const escaped = filePath.replace(/'/g, "'\\''");
+                    return [runtimes.shell, "-c", `source '${escaped}'`];
+                }
+                if (shellName.includes("powershell") || shellName.includes("pwsh")) {
+                    return [runtimes.shell, "-File", filePath];
+                }
+                // cmd.exe and others: direct file (cmd reads .cmd association safely).
+            }
             return [runtimes.shell, filePath];
+        }
         case "ruby":
             if (!runtimes.ruby) {
                 throw new Error("Ruby not available. Install ruby.");

package/build/search/auto-memory.d.ts

@@ -1,6 +1,7 @@
 /**
- * Auto-memory search — searches CLAUDE.md and MEMORY.md files for
- * persisted decisions, preferences, and context from prior sessions.
+ * Auto-memory search — searches CLAUDE.md / AGENTS.md / GEMINI.md / etc.
+ * and the platform's persistent memory directory for decisions,
+ * preferences, and context from prior sessions.
  *
  * Returns results in a format compatible with the unified search pipeline.
  */
@@ -12,18 +13,30 @@ export interface AutoMemoryResult {
     timestamp?: string;
 }
 /**
- * Search auto-memory files (CLAUDE.md, MEMORY.md, user identity files)
- * for content matching any of the given queries.
+ * Minimal adapter contract used by searchAutoMemory.
+ * Avoids depending on the full HookAdapter type to keep this module standalone.
+ */
+export interface AutoMemoryAdapter {
+    getConfigDir(): string;
+    getInstructionFiles(): string[];
+    getMemoryDir(): string;
+}
+/**
+ * Search auto-memory files for content matching any of the given queries.
+ *
+ * When `adapter` is provided, the per-platform conventions are used:
+ *   1. Project-level: <projectDir>/<each instructionFile>
+ *   2. User-level: <configDir>/<each instructionFile>
+ *   3. Memory dir: <memoryDir>/*.md
  *
- * Scans:
- *   1. Project-level: <projectDir>/CLAUDE.md
- *   2. User-level: <configDir>/CLAUDE.md
- *   3. User memory: <configDir>/memory/*.md
+ * Without an adapter (legacy callers), defaults to Claude conventions
+ * (CLAUDE.md + ~/.claude/memory) for backwards compatibility.
  *
  * @param queries  Array of search terms
  * @param limit    Max results to return
  * @param projectDir  Project directory path
- * @param configDir   Config directory (e.g. ~/.claude)
+ * @param configDir   Explicit config dir override (legacy callers)
+ * @param adapter     Platform adapter — supplies instruction files + memory dir
  * @returns Matching auto-memory results
  */
-export declare function searchAutoMemory(queries: string[], limit?: number, projectDir?: string, configDir?: string): AutoMemoryResult[];
+export declare function searchAutoMemory(queries: string[], limit?: number, projectDir?: string, configDir?: string, adapter?: AutoMemoryAdapter): AutoMemoryResult[];

package/build/search/auto-memory.js

@@ -1,48 +1,68 @@
 /**
- * Auto-memory search — searches CLAUDE.md and MEMORY.md files for
- * persisted decisions, preferences, and context from prior sessions.
+ * Auto-memory search — searches CLAUDE.md / AGENTS.md / GEMINI.md / etc.
+ * and the platform's persistent memory directory for decisions,
+ * preferences, and context from prior sessions.
  *
  * Returns results in a format compatible with the unified search pipeline.
  */
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, isAbsolute } from "node:path";
 import { homedir } from "node:os";
 const DEBUG = process.env.DEBUG?.includes("context-mode");
 /**
- * Search auto-memory files (CLAUDE.md, MEMORY.md, user identity files)
- * for content matching any of the given queries.
+ * Search auto-memory files for content matching any of the given queries.
  *
- * Scans:
- *   1. Project-level: <projectDir>/CLAUDE.md
- *   2. User-level: <configDir>/CLAUDE.md
- *   3. User memory: <configDir>/memory/*.md
+ * When `adapter` is provided, the per-platform conventions are used:
+ *   1. Project-level: <projectDir>/<each instructionFile>
+ *   2. User-level: <configDir>/<each instructionFile>
+ *   3. Memory dir: <memoryDir>/*.md
+ *
+ * Without an adapter (legacy callers), defaults to Claude conventions
+ * (CLAUDE.md + ~/.claude/memory) for backwards compatibility.
  *
  * @param queries  Array of search terms
  * @param limit    Max results to return
  * @param projectDir  Project directory path
- * @param configDir   Config directory (e.g. ~/.claude)
+ * @param configDir   Explicit config dir override (legacy callers)
+ * @param adapter     Platform adapter — supplies instruction files + memory dir
  * @returns Matching auto-memory results
  */
-export function searchAutoMemory(queries, limit = 5, projectDir, configDir) {
+export function searchAutoMemory(queries, limit = 5, projectDir, configDir, adapter) {
     const results = [];
-    const effectiveConfigDir = configDir || join(homedir(), ".claude");
+    // Resolve conventions — adapter wins over explicit configDir, which wins
+    // over the historical Claude defaults.
+    const instructionFiles = adapter?.getInstructionFiles() ?? ["CLAUDE.md"];
+    const adapterConfigDir = adapter?.getConfigDir();
+    const effectiveConfigDir = adapterConfigDir
+        ? resolveAgainst(projectDir, adapterConfigDir)
+        : (configDir || join(homedir(), ".claude"));
+    const adapterMemoryDir = adapter?.getMemoryDir();
+    const memoryDir = adapterMemoryDir
+        ? resolveAgainst(projectDir, adapterMemoryDir)
+        : join(effectiveConfigDir, "memory");
     // Collect candidate files
     const candidates = [];
-    // 1. Project-level CLAUDE.md
+    // 1. Project-level instruction files
     if (projectDir) {
-        const projectClaude = join(projectDir, "CLAUDE.md");
-        if (existsSync(projectClaude)) {
-            candidates.push({ path: projectClaude, label: "project/CLAUDE.md" });
+        for (const fileName of instructionFiles) {
+            const p = join(projectDir, fileName);
+            if (existsSync(p)) {
+                candidates.push({ path: p, label: `project/${fileName}` });
+            }
         }
     }
-    // 2. User-level CLAUDE.md
-    const userClaude = join(effectiveConfigDir, "CLAUDE.md");
-    if (existsSync(userClaude)) {
-        candidates.push({ path: userClaude, label: "user/CLAUDE.md" });
+    // 2. User-level instruction files (skip when configDir resolves to the
+    //    project root — already covered by step 1, would emit dup labels).
+    if (effectiveConfigDir && effectiveConfigDir !== projectDir) {
+        for (const fileName of instructionFiles) {
+            const p = join(effectiveConfigDir, fileName);
+            if (existsSync(p)) {
+                candidates.push({ path: p, label: `user/${fileName}` });
+            }
+        }
     }
-    // 3. User memory directory
-    const memoryDir = join(effectiveConfigDir, "memory");
-    if (existsSync(memoryDir)) {
+    // 3. Memory directory
+    if (memoryDir && existsSync(memoryDir)) {
         try {
             const files = readdirSync(memoryDir).filter(f => f.endsWith(".md"));
             for (const file of files) {
@@ -62,9 +82,13 @@ export function searchAutoMemory(queries, limit = 5, projectDir, configDir) {
         if (results.length >= limit)
             break;
         try {
-            // Skip files larger than 1MB to avoid memory issues
+            // Single stat for both size guard and timestamp — saves one syscall
+            // per candidate file. Cross-platform: statSync semantics identical
+            // on macOS / Linux / Windows; size+mtime read in the same inode probe.
+            let stat;
             try {
-                if (statSync(candidate.path).size > 1_000_000)
+                stat = statSync(candidate.path);
+                if (stat.size > 1_000_000)
                     continue;
             }
             catch {
@@ -106,7 +130,7 @@ export function searchAutoMemory(queries, limit = 5, projectDir, configDir) {
                         content: snippet,
                         source: candidate.label,
                         origin: "auto-memory",
-                        timestamp: statSync(candidate.path).mtime.toISOString(),
+                        timestamp: stat.mtime.toISOString(),
                     });
                     break; // one result per file per query batch
                 }
@@ -119,3 +143,17 @@ export function searchAutoMemory(queries, limit = 5, projectDir, configDir) {
     }
     return results.slice(0, limit);
 }
+/**
+ * Resolve a possibly-relative path (e.g. ".github", "memory") against a
+ * project directory. Absolute paths and empty strings are returned as-is
+ * (empty == "use projectDir directly").
+ */
+function resolveAgainst(projectDir, p) {
+    if (!p)
+        return projectDir ?? "";
+    if (isAbsolute(p))
+        return p;
+    if (!projectDir)
+        return p;
+    return join(projectDir, p);
+}

package/build/search/unified.d.ts

@@ -7,6 +7,7 @@
  */
 import type { ContentStore } from "../store.js";
 import type { SessionDB } from "../session/db.js";
+import { type AutoMemoryAdapter } from "./auto-memory.js";
 export interface UnifiedSearchResult {
     title: string;
     content: string;
@@ -28,6 +29,8 @@ export interface SearchAllSourcesOpts {
     sessionDB?: SessionDB | null;
     projectDir?: string;
     configDir?: string;
+    /** Detected platform adapter — used for adapter-aware auto-memory. */
+    adapter?: AutoMemoryAdapter;
 }
 /**
  * Search across all available sources.

package/build/search/unified.js

@@ -20,7 +20,7 @@ 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, } = opts;
+    const { query, limit, store, sort = "relevance", source, contentType, sessionDB, projectDir, configDir, adapter, } = 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)
@@ -65,7 +65,7 @@ export function searchAllSources(opts) {
         }
         // Source 3: Auto-memory
         try {
-            const memResults = searchAutoMemory([query], limit, projectDir, configDir);
+            const memResults = searchAutoMemory([query], limit, projectDir, configDir, adapter);
             results.push(...memResults);
         }
         catch (e) {

package/build/server.d.ts

@@ -8,3 +8,50 @@ import { ContentStore } from "./store.js";
 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 interface BatchCommand {
+    label: string;
+    command: string;
+}
+export interface BatchRunResult {
+    outputs: string[];
+    timedOut: boolean;
+}
+export interface BatchRunOptions {
+    /**
+     * Total budget (concurrency=1, shared) or per-command (concurrency>1).
+     * When `undefined`, no server-side timer fires — the MCP host's RPC
+     * timeout governs (Issue #406).
+     */
+    timeout: number | undefined;
+    concurrency: number;
+    nodeOptsPrefix: string;
+    onFsBytes?: (bytes: number) => void;
+}
+interface BatchExecutor {
+    execute(input: {
+        language: "shell";
+        code: string;
+        timeout: number | undefined;
+    }): Promise<{
+        stdout: string;
+        timedOut?: boolean;
+    }>;
+}
+/**
+ * Execute batch commands. concurrency=1 preserves the legacy serial path
+ * (shared timeout budget + cascading skip-on-timeout). concurrency>1 runs
+ * commands concurrently with at most N in flight; each command receives the
+ * full timeout, output is collated by input index, and per-command timeouts
+ * record `(timed out)` blocks without skipping siblings.
+ */
+export declare function runBatchCommands(commands: BatchCommand[], opts: BatchRunOptions, executor: BatchExecutor): Promise<BatchRunResult>;
+/**
+ * Classify an IP address.
+ *   - "block":    always blocked (link-local/IMDS/multicast/reserved/malformed)
+ *   - "private":  loopback or RFC1918 — allowed by default, blocked in strict mode
+ *   - "public":   safe to fetch
+ *
+ * Exported (via the function name) so SSRF tests can exercise the matcher directly.
+ */
+export declare function classifyIp(ip: string): "block" | "private" | "public";
+export {};