context-mode 1.0.148 → 1.0.150

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.148"
+    "version": "1.0.150"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.148",
+      "version": "1.0.150",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.148",
+  "version": "1.0.150",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.148",
+  "version": "1.0.150",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.148",
+  "version": "1.0.150",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.148",
+  "version": "1.0.150",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/build/cache-heal.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Plugin cache self-heal — fixes broken CLAUDE_PLUGIN_ROOT references.
+ *
+ * Claude Code's plugin auto-update can leave installed_plugins.json pointing
+ * to a non-existent directory (anthropics/claude-code#46915). This module
+ * detects and repairs the mismatch by creating symlinks.
+ *
+ * 4-layer defense:
+ *   1. start.mjs startup — reverse heal (registry → symlink to us)
+ *   2. server.ts first tool call — mid-session heal
+ *   3. postinstall.mjs — backward symlink on new install
+ *   4. global hook auto-deploy — survives total plugin cache breakage
+ */
+export interface HealResult {
+    healed: boolean;
+    action?: "symlink" | "global-hook" | "none";
+    from?: string;
+    to?: string;
+}
+/**
+ * Core heal: if installed_plugins.json points to a non-existent directory,
+ * create a symlink from that path to our actual directory.
+ *
+ * @param currentDir - The directory we're actually running from
+ * @param installedPluginsPath - Path to installed_plugins.json (injectable for testing)
+ */
+export declare function healRegistryMismatch(currentDir: string, installedPluginsPath?: string): HealResult;
+/**
+ * Deploy a global SessionStart hook that heals plugin cache mismatches.
+ * This hook lives outside the plugin directory, so it survives cache breakage.
+ *
+ * Written to ~/.claude/hooks/context-mode-cache-heal.sh
+ */
+export declare function deployGlobalHealHook(): HealResult;
+/**
+ * Backward symlink: during postinstall, if the registry points to a
+ * non-existent OLD path, create a symlink from old → new (our directory).
+ * Same as healRegistryMismatch but called from postinstall context.
+ */
+export { healRegistryMismatch as healBackwardCompat };
+/**
+ * Mid-session heal — call on first MCP tool invocation.
+ * Checks if registry path differs from our running directory.
+ * Creates symlink if needed. Runs only once per process.
+ */
+export declare function healMidSession(currentDir: string): HealResult;
+/** Reset mid-session flag (for testing only) */
+export declare function _resetMidSession(): void;

package/build/cache-heal.js

@@ -0,0 +1,150 @@
+/**
+ * Plugin cache self-heal — fixes broken CLAUDE_PLUGIN_ROOT references.
+ *
+ * Claude Code's plugin auto-update can leave installed_plugins.json pointing
+ * to a non-existent directory (anthropics/claude-code#46915). This module
+ * detects and repairs the mismatch by creating symlinks.
+ *
+ * 4-layer defense:
+ *   1. start.mjs startup — reverse heal (registry → symlink to us)
+ *   2. server.ts first tool call — mid-session heal
+ *   3. postinstall.mjs — backward symlink on new install
+ *   4. global hook auto-deploy — survives total plugin cache breakage
+ */
+import { existsSync, readFileSync, symlinkSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Core heal: if installed_plugins.json points to a non-existent directory,
+ * create a symlink from that path to our actual directory.
+ *
+ * @param currentDir - The directory we're actually running from
+ * @param installedPluginsPath - Path to installed_plugins.json (injectable for testing)
+ */
+export function healRegistryMismatch(currentDir, installedPluginsPath) {
+    const ipPath = installedPluginsPath ?? resolve(homedir(), ".claude", "plugins", "installed_plugins.json");
+    if (!existsSync(ipPath))
+        return { healed: false, action: "none" };
+    if (!existsSync(currentDir))
+        return { healed: false, action: "none" };
+    let ip;
+    try {
+        ip = JSON.parse(readFileSync(ipPath, "utf-8"));
+    }
+    catch {
+        return { healed: false, action: "none" };
+    }
+    for (const [key, entries] of Object.entries(ip.plugins ?? {})) {
+        if (!key.toLowerCase().includes("context-mode"))
+            continue;
+        for (const entry of entries) {
+            const registryPath = entry.installPath;
+            if (!registryPath)
+                continue;
+            // Registry path exists — no healing needed
+            if (existsSync(registryPath))
+                continue;
+            // Registry path doesn't exist — create symlink to our directory
+            try {
+                const parent = dirname(registryPath);
+                if (!existsSync(parent))
+                    mkdirSync(parent, { recursive: true });
+                if (process.platform === "win32") {
+                    // Windows: use junction (no admin required)
+                    symlinkSync(currentDir, registryPath, "junction");
+                }
+                else {
+                    symlinkSync(currentDir, registryPath);
+                }
+                return { healed: true, action: "symlink", from: registryPath, to: currentDir };
+            }
+            catch {
+                return { healed: false, action: "none" };
+            }
+        }
+    }
+    return { healed: false, action: "none" };
+}
+/**
+ * Deploy a global SessionStart hook that heals plugin cache mismatches.
+ * This hook lives outside the plugin directory, so it survives cache breakage.
+ *
+ * Written to ~/.claude/hooks/context-mode-cache-heal.sh
+ */
+export function deployGlobalHealHook() {
+    const hooksDir = resolve(homedir(), ".claude", "hooks");
+    const hookPath = resolve(hooksDir, "context-mode-cache-heal.sh");
+    // Already deployed
+    if (existsSync(hookPath))
+        return { healed: false, action: "none" };
+    try {
+        if (!existsSync(hooksDir))
+            mkdirSync(hooksDir, { recursive: true });
+        const script = `#!/usr/bin/env bash
+# context-mode plugin cache self-heal — auto-deployed by context-mode MCP server
+# Fixes anthropics/claude-code#46915: auto-update breaks CLAUDE_PLUGIN_ROOT
+# This hook runs at SessionStart (global, not plugin-level) so it works even
+# when the plugin cache is broken.
+
+set -euo pipefail
+
+PLUGINS_FILE="$HOME/.claude/plugins/installed_plugins.json"
+[[ -f "$PLUGINS_FILE" ]] || exit 0
+
+# Find context-mode entries and heal missing directories
+node -e '
+const fs = require("fs");
+const path = require("path");
+try {
+  const ip = JSON.parse(fs.readFileSync(process.argv[1], "utf-8"));
+  for (const [key, entries] of Object.entries(ip.plugins || {})) {
+    if (!key.toLowerCase().includes("context-mode")) continue;
+    for (const entry of entries) {
+      const p = entry.installPath;
+      if (!p || fs.existsSync(p)) continue;
+      const parent = path.dirname(p);
+      if (!fs.existsSync(parent)) continue;
+      const dirs = fs.readdirSync(parent).filter(d => /^\\d+\\.\\d+/.test(d) && fs.statSync(path.join(parent, d)).isDirectory());
+      if (dirs.length === 0) continue;
+      dirs.sort((a, b) => {
+        const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+        for (let i = 0; i < 3; i++) { if ((pa[i]||0) !== (pb[i]||0)) return (pa[i]||0) - (pb[i]||0); }
+        return 0;
+      });
+      const target = path.join(parent, dirs[dirs.length - 1]);
+      try { fs.symlinkSync(target, p); } catch {}
+    }
+  }
+} catch {}
+' "$PLUGINS_FILE" 2>/dev/null || true
+`;
+        writeFileSync(hookPath, script, { mode: 0o755 });
+        return { healed: true, action: "global-hook", from: hookPath };
+    }
+    catch {
+        return { healed: false, action: "none" };
+    }
+}
+/**
+ * Backward symlink: during postinstall, if the registry points to a
+ * non-existent OLD path, create a symlink from old → new (our directory).
+ * Same as healRegistryMismatch but called from postinstall context.
+ */
+export { healRegistryMismatch as healBackwardCompat };
+/** One-shot flag for mid-session heal in server.ts */
+let _midSessionHealed = false;
+/**
+ * Mid-session heal — call on first MCP tool invocation.
+ * Checks if registry path differs from our running directory.
+ * Creates symlink if needed. Runs only once per process.
+ */
+export function healMidSession(currentDir) {
+    if (_midSessionHealed)
+        return { healed: false, action: "none" };
+    _midSessionHealed = true;
+    return healRegistryMismatch(currentDir);
+}
+/** Reset mid-session flag (for testing only) */
+export function _resetMidSession() {
+    _midSessionHealed = false;
+}

package/build/executor.d.ts

@@ -19,6 +19,15 @@ interface ExecuteOptions {
     timeout?: number;
     /** Keep process running after timeout instead of killing it. */
     background?: boolean;
+    /**
+     * Issue #45 — per-call cwd override for the shell language. When set,
+     * the shell script runs in this directory instead of `#projectRoot`.
+     * Non-shell languages keep their tmpDir sandbox cwd regardless (the
+     * script file lives there). Used by Codex MCP handlers to pin shell
+     * commands to a resolved project root when the spawning host inherited
+     * a non-project cwd (e.g. $HOME).
+     */
+    cwd?: string;
 }
 interface ExecuteFileOptions extends ExecuteOptions {
     path: string;

package/build/executor.js

@@ -130,7 +130,7 @@ export class PolyglotExecutor {
         this.#backgroundedPids.clear();
     }
     async execute(opts) {
-        const { language, code, timeout, background = false } = opts;
+        const { language, code, timeout, background = false, cwd: cwdOverride } = opts;
         const tmpDir = mkdtempSync(join(OS_TMPDIR, ".ctx-mode-"));
         try {
             const filePath = this.#writeScript(tmpDir, code, language);
@@ -142,7 +142,11 @@ export class PolyglotExecutor {
             // Shell commands run in the project directory so git, relative paths,
             // and other project-aware tools work naturally. Non-shell languages
             // run in the temp directory where their script file is written.
-            const cwd = language === "shell" ? this.#projectRoot : tmpDir;
+            // Issue #45 — `cwdOverride` lets per-call sites (Codex MCP handlers)
+            // pin shell cwd without mutating process-wide state.
+            const cwd = language === "shell"
+                ? (cwdOverride ?? this.#projectRoot)
+                : tmpDir;
             const result = await this.#spawn(cmd, cwd, tmpDir, timeout, background);
             // Skip tmpDir cleanup if process was backgrounded — it may still need files
             if (!result.backgrounded) {

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/server.d.ts

@@ -78,6 +78,18 @@ export declare function resolveSessionIdFromSessionDB(opts?: {
     sessionsDir?: string;
     bypassCache?: boolean;
 }): string | undefined;
+/**
+ * Project directory detection across supported platforms.
+ *
+ * Priority:
+ *   1. Platform-specific env var (set by host IDE before MCP server spawn)
+ *   2. CONTEXT_MODE_PROJECT_DIR (set by start.mjs for ALL platforms — universal)
+ *   3. process.cwd() (last resort)
+ *
+ * CONTEXT_MODE_PROJECT_DIR guarantees correct projectDir even for platforms
+ * that don't set their own env var (Cursor, OpenClaw, Codex, Kiro, Zed).
+ */
+export declare function getProjectDir(): string;
 /**
  * Parse FTS5 highlight markers to find match positions in the
  * original (marker-free) text. Returns character offsets into the

package/build/server.js

@@ -465,7 +465,7 @@ function getSessionDir() {
  * CONTEXT_MODE_PROJECT_DIR guarantees correct projectDir even for platforms
  * that don't set their own env var (Cursor, OpenClaw, Codex, Kiro, Zed).
  */
-function getProjectDir() {
+export function getProjectDir() {
     const override = projectDirOverride.getStore();
     if (override)
         return override.projectDir;
@@ -500,14 +500,22 @@ function getProjectDir() {
     // and the legacy literal cascade is preserved there for semver safety.
     let transcriptsRoot;
     let strictPlatform;
+    let codexHome;
     try {
         const detected = detectPlatform().platform;
         strictPlatform = detected;
         if (detected === "claude-code") {
             transcriptsRoot = join(homedir(), ".claude", "projects");
         }
+        // Issue #45 — Codex publishes no workspace env var, so the resolver
+        // reads `meta.cwd` from the most-recently-modified session.jsonl under
+        // `${codexHome}/sessions/`. Wire codexHome at the call site so the
+        // resolver can be exercised under test without process-level mutation.
+        if (detected === "codex") {
+            codexHome = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+        }
     }
-    catch { /* detection failure — leave both undefined, resolver uses legacy cascade */ }
+    catch { /* detection failure — leave undefined, resolver uses legacy cascade */ }
     return resolveProjectDir({
         env: process.env,
         cwd: process.cwd(),
@@ -515,6 +523,7 @@ function getProjectDir() {
         transcriptsRoot,
         transcriptMaxAgeMs: 5 * 60 * 1000,
         strictPlatform,
+        codexHome,
     });
 }
 /**
@@ -1731,13 +1740,20 @@ EXAMPLE: ctx_index(path: "/path/to/large-spec.md", source: "openapi-v2-spec")`,
         path: z
             .string()
             .optional()
-            .describe("File path to read and index (content never enters context). Provide this OR content."),
+            .describe("File OR directory path to read and index (content never enters context). Provide this OR content. Directory paths trigger a bounded recursive walk (#687)."),
         source: z
             .string()
             .optional()
             .describe("Label for the indexed content (e.g., 'Context7: React useEffect', 'Skill: frontend-design')"),
+        include: z.array(z.string()).optional().describe("Directory-only: glob patterns to include (default: all matching extensions)."),
+        exclude: z.array(z.string()).optional().describe("Directory-only: glob patterns to exclude. Merged with defaults (node_modules, .git, dist, build, .next, coverage, .venv, __pycache__, .DS_Store)."),
+        maxDepth: z.number().int().min(0).optional().describe("Directory-only: max recursion depth from root (default: 5)."),
+        maxFiles: z.number().int().min(1).optional().describe("Directory-only: hard cap on files indexed (default: 200) — FTS5 blow-up guard."),
+        extensions: z.array(z.string()).optional().describe("Directory-only: allowed file extensions (default: .md .mdx .txt .json .yaml .yml .ts .tsx .js .jsx .py .rs .go .sh)."),
+        respectGitignore: z.boolean().optional().describe("Directory-only: apply nearest .gitignore (default: true)."),
+        followSymlinks: z.boolean().optional().describe("Directory-only: follow directory symlinks (default: false — cycle hazard + escape risk)."),
     }),
-}, async ({ content, path, source }) => {
+}, async ({ content, path, source, include, exclude, maxDepth, maxFiles, extensions, respectGitignore, followSymlinks }) => {
     if (!content && !path) {
         return trackResponse("ctx_index", {
             content: [
@@ -1760,6 +1776,54 @@ EXAMPLE: ctx_index(path: "/path/to/large-spec.md", source: "openapi-v2-spec")`,
     }
     try {
         const resolvedPath = path ? resolveProjectPath(path) : undefined;
+        // Directory dispatch (#687, reported by @matiasduartee). When the
+        // resolved path is a directory, walk it bounded and re-enter `index()`
+        // per-file so the security gate at store.ts:845 (TOCTOU defense from
+        // #442 round-3) keeps running for every file.
+        if (resolvedPath && existsSync(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+            const store = getStore();
+            const projectDir = getProjectDir();
+            const denyGlobs = readToolDenyPatterns("Read", projectDir);
+            const isWin32 = process.platform === "win32";
+            const perFileDeny = (absPath) => {
+                try {
+                    return evaluateFilePath(absPath, denyGlobs, isWin32, projectDir).denied;
+                }
+                catch {
+                    return false; // fail-open consistent with checkFilePathDenyPolicy
+                }
+            };
+            const dirResult = store.indexDirectory({
+                path: resolvedPath,
+                source: source ?? resolvedPath,
+                attribution: currentAttribution(),
+                perFileDeny,
+                include,
+                exclude,
+                maxDepth,
+                maxFiles,
+                extensions,
+                respectGitignore,
+                followSymlinks,
+            });
+            const capNote = dirResult.capped
+                ? ` (cap reached — only first ${dirResult.filesIndexed} of ${dirResult.totalSeen}+ files; raise maxFiles to index more)`
+                : "";
+            const denyNote = dirResult.denied > 0
+                ? ` (${dirResult.denied} file${dirResult.denied === 1 ? "" : "s"} blocked by Read deny policy)`
+                : "";
+            const failNote = dirResult.failed > 0
+                ? ` (${dirResult.failed} file${dirResult.failed === 1 ? "" : "s"} failed to read)`
+                : "";
+            return trackResponse("ctx_index", {
+                content: [
+                    {
+                        type: "text",
+                        text: `Indexed ${dirResult.filesIndexed} file${dirResult.filesIndexed === 1 ? "" : "s"} (${dirResult.totalChunks} sections) from directory: ${dirResult.label}${capNote}${denyNote}${failNote}\nUse ctx_search(queries: ["..."]) to query this content.`,
+                    },
+                ],
+            });
+        }
         // Track the raw bytes being indexed (content or file)
         if (content)
             trackIndexed(Buffer.byteLength(content));

package/build/store-directory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * walkDirectory — bounded recursive directory walker for ctx_index (#687).
+ *
+ * Issue: ctx_index refused directory paths via the security gate at
+ * src/store.ts:845 ("refusing to index <path>: not a regular file"). The gate
+ * is a TOCTOU defense from #442 round-3 and MUST be preserved — directory
+ * support is layered as a separate concern here. Each file produced by
+ * walkDirectory is then read via the existing per-file
+ * `openSync + fstatSync.isFile()` invariant in `ContentStore.index()`.
+ *
+ * Reported by @matiasduartee across 4 clients × Windows 11.
+ * https://github.com/anthropic-experimental/context-mode/issues/687
+ *
+ * Design constraints:
+ *   - No new dependencies (avoid the `ignore` package — issue #687 Diagnose).
+ *   - Cross-OS: path.sep / path.join everywhere, never raw "/" string ops.
+ *   - Symlink cycle detection via a resolved-path Set.
+ *   - Symlink-escape rejection: refuse to follow symlinks that resolve outside
+ *     the rootPath (defense-in-depth alongside per-file checkFilePathDenyPolicy).
+ *   - FTS5-blowup guard: hard cap maxFiles (default 200, per Architect).
+ */
+export interface WalkOptions {
+    /** Glob-ish include patterns. Empty/undefined means include all (subject to extensions). */
+    include?: string[];
+    /** Glob-ish exclude patterns. Merged with sensible defaults. */
+    exclude?: string[];
+    /** Max recursion depth from rootPath (0 = root only). Default 5. */
+    maxDepth?: number;
+    /** Hard cap on total files. Default 200 — FTS5 blow-up guard. */
+    maxFiles?: number;
+    /** Allowed file extensions (with leading dot). Empty/undefined means default set. */
+    extensions?: string[];
+    /** Apply nearest .gitignore rules during walk. Default true. */
+    respectGitignore?: boolean;
+    /** Follow directory symlinks. Default false (cycle hazard + escape risk). */
+    followSymlinks?: boolean;
+}
+export interface WalkResult {
+    files: string[];
+    /** True when maxFiles cap was hit and traversal halted early. */
+    capped: boolean;
+    /** Total files discovered before cap (for reporting). */
+    totalSeen: number;
+}
+/**
+ * Walk `rootPath` recursively under the given bounds and return absolute file
+ * paths matching the filters. Pure synchronous traversal — no allocations
+ * beyond the result array. Symlink cycles are detected via a resolved-path
+ * Set; symlink escapes (resolving outside rootPath) are silently skipped.
+ */
+export declare function walkDirectory(rootPath: string, opts?: WalkOptions): string[];
+/**
+ * Same as walkDirectory but returns capped + totalSeen so callers can surface
+ * a "capped at N files" notice in their response.
+ */
+export declare function walkDirectoryDetailed(rootPath: string, opts?: WalkOptions): WalkResult;