context-mode 1.0.98 → 1.0.99

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.98"
+    "version": "1.0.99"
   },
   "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.98",
+      "version": "1.0.99",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.98",
+  "version": "1.0.99",
   "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.98",
+  "version": "1.0.99",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.98",
+  "version": "1.0.99",
   "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/README.md

@@ -523,12 +523,14 @@ Full documentation: [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)
      "hooks": {
        "PreToolUse": [{ "matcher": "local_shell|shell|shell_command|exec_command|container.exec|Bash|Shell|grep_files|mcp__plugin_context-mode_context-mode__ctx_execute|mcp__plugin_context-mode_context-mode__ctx_execute_file|mcp__plugin_context-mode_context-mode__ctx_batch_execute", "hooks": [{ "type": "command", "command": "context-mode hook codex pretooluse" }] }],
        "PostToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex posttooluse" }] }],
-       "SessionStart": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex sessionstart" }] }]
+       "SessionStart": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex sessionstart" }] }],
+       "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex userpromptsubmit" }] }],
+       "Stop": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex stop" }] }]
      }
    }
    ```
 
-   `PreToolUse` enforces deny/block routing today and is prepared for input rewrites once Codex supports them. `PostToolUse` captures session events. `SessionStart` restores state after compaction.
+   `PreToolUse` enforces deny/block routing today and is prepared for input rewrites once Codex supports them. `PostToolUse` captures session events. `SessionStart` restores state after compaction. `UserPromptSubmit` captures user decisions and corrections. `Stop` records turn-end state.
 
    > **Note:** Codex PreToolUse routing currently supports deny rules only (blocks dangerous commands). It still needs upstream `updatedInput` support before context-mode can rewrite tool input; track [openai/codex#18491](https://github.com/openai/codex/issues/18491). Context injection (`additionalContext`) is not supported in Codex PreToolUse — it works via PostToolUse and SessionStart instead. This is handled automatically.
 
@@ -912,12 +914,12 @@ Session continuity requires 4 hooks working together:
 |---|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 | **PreToolUse** | Enforces sandbox routing before tool execution | Yes | -- | -- | -- | Yes | -- | -- | -- | Yes | -- | Yes | -- | ✓ (via tool_call event) |
 | **PostToolUse** | Captures events after each tool call | Yes | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | Yes | -- | Yes | -- | ✓ (via tool_result event) |
-| **UserPromptSubmit** | Captures user decisions and corrections | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
+| **UserPromptSubmit** | Captures user decisions and corrections | Yes | -- | -- | -- | -- | -- | -- | -- | Yes | -- | -- | -- | -- |
 | **PreCompact** | Builds snapshot before compaction | Yes | Yes | Yes | Yes | -- | Plugin | Plugin | Plugin | -- | -- | -- | -- | ✓ (via session_before_compact) |
 | **SessionStart** | Restores state after compaction or resume | Yes | Yes | Yes | Yes | -- | -- | -- | Plugin | Yes | -- | -- | -- | ✓ (via session_start event) |
 | | **Session completeness** | **Full** | **High** | **High** | **High** | **Partial** | **High** | **High** | **High** | **Partial** | **--** | **Partial** | **--** | **High** |
 
-> **Note:** Full session continuity (capture + snapshot + restore) works on **Claude Code**, **Gemini CLI**, **VS Code Copilot**, and **JetBrains Copilot**. **OpenCode** provides **high** session continuity: it captures tool events and injects compaction snapshots via the plugin, but SessionStart is not yet available ([#14808](https://github.com/sst/opencode/issues/14808)), so startup/resume restore is not supported. **KiloCode** shares the same plugin architecture as OpenCode via the OpenCodeAdapter, so its continuity level depends on KiloCode's SessionStart support. **Cursor** captures tool events via `preToolUse`/`postToolUse`, but `sessionStart` is currently rejected by Cursor's validator ([forum report](https://forum.cursor.com/t/unknown-hook-type-sessionstart/149566)), so session restore after compaction is not available yet. **OpenClaw** uses native gateway plugin hooks (`api.on()`) for full session continuity. **Pi Coding Agent** provides high session continuity via extension hooks (`tool_call`, `tool_result`, `session_start`, `session_before_compact`). **Codex CLI** provides partial hook-based session tracking through PreToolUse, PostToolUse, and SessionStart; MCP tools work. **Antigravity**, **Kiro**, and **Zed** have no hook support in the current release, so session tracking is not available.
+> **Note:** Full session continuity (capture + snapshot + restore) works on **Claude Code**, **Gemini CLI**, **VS Code Copilot**, and **JetBrains Copilot**. **OpenCode** provides **high** session continuity: it captures tool events and injects compaction snapshots via the plugin, but SessionStart is not yet available ([#14808](https://github.com/sst/opencode/issues/14808)), so startup/resume restore is not supported. **KiloCode** shares the same plugin architecture as OpenCode via the OpenCodeAdapter, so its continuity level depends on KiloCode's SessionStart support. **Cursor** captures tool events via `preToolUse`/`postToolUse`, but `sessionStart` is currently rejected by Cursor's validator ([forum report](https://forum.cursor.com/t/unknown-hook-type-sessionstart/149566)), so session restore after compaction is not available yet. **OpenClaw** uses native gateway plugin hooks (`api.on()`) for full session continuity. **Pi Coding Agent** provides high session continuity via extension hooks (`tool_call`, `tool_result`, `session_start`, `session_before_compact`). **Codex CLI** provides partial hook-based session tracking through PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, and Stop; MCP tools work. **Antigravity**, **Kiro**, and **Zed** have no hook support in the current release, so session tracking is not available.
 
 <details>
 <summary><strong>What gets captured</strong></summary>
@@ -979,7 +981,7 @@ After compaction, the model receives a **Session Guide** — a structured narrat
 - **Session Intent** — mode classification (implement, investigate, review, discuss)
 - **User Role** — behavioral directives set during the session
 
-Detailed event data is also indexed into FTS5 for on-demand retrieval via `search()`.
+Detailed event data is also indexed into FTS5 for on-demand retrieval via `ctx_search()`.
 
 </details>
 
@@ -1002,7 +1004,7 @@ Detailed event data is also indexed into FTS5 for on-demand retrieval via `searc
 
 **OpenClaw / Pi Agent** — High coverage. All tool lifecycle hooks (`after_tool_call`, `before_compaction`, `session_start`) fire via the native gateway plugin. User decisions aren't captured but file edits, git ops, errors, and tasks are fully tracked. Falls back to DB snapshot reconstruction if compaction hooks fail on older gateway versions. See [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md).
 
-**Codex CLI** — MCP active, hooks stable. Hook scripts (PreToolUse, PostToolUse, SessionStart) are implemented and tested. PreToolUse deny routing works; input rewriting still depends on upstream `updatedInput` support ([openai/codex#18491](https://github.com/openai/codex/issues/18491)).
+**Codex CLI** — MCP active, hooks stable. Hook scripts (PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop) are implemented and tested. PreToolUse deny routing works; input rewriting still depends on upstream `updatedInput` support ([openai/codex#18491](https://github.com/openai/codex/issues/18491)).
 
 **Antigravity** — No session support. No hooks, no event capture. Requires manually copying `GEMINI.md` to your project root. Auto-detected via MCP protocol handshake (`clientInfo.name`).
 
@@ -1035,7 +1037,7 @@ Detailed event data is also indexed into FTS5 for on-demand retrieval via `searc
 >
 > **OpenClaw** runs context-mode as a native gateway plugin targeting Pi Agent sessions. Hooks register via `api.on()` (tool/lifecycle) and `api.registerHook()` (commands). All tool interception and compaction hooks are supported. See [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md).
 >
-> **Codex CLI** hooks are stable. MCP tools work, and hook scripts activate through `~/.codex/hooks.json`. PreToolUse supports `permissionDecision: "deny"` only; input modification still needs upstream `updatedInput` support ([openai/codex#18491](https://github.com/openai/codex/issues/18491)). `additionalContext` is not supported in PreToolUse (context injection works via PostToolUse and SessionStart instead; the codex formatter handles this automatically). See the Codex install section for setup. **Antigravity** and **Zed** do not support hooks. They rely solely on manually-copied routing instruction files (`AGENTS.md` / `GEMINI.md`) for enforcement (~60% compliance). See each platform's install section for copy instructions. Antigravity and Zed are auto-detected via MCP protocol handshake — no manual platform configuration needed.
+> **Codex CLI** hooks are stable. MCP tools work, and hook scripts activate through `~/.codex/hooks.json`. PreToolUse supports `permissionDecision: "deny"` only; input modification still needs upstream `updatedInput` support ([openai/codex#18491](https://github.com/openai/codex/issues/18491)). `additionalContext` is not supported in PreToolUse (context injection works via PostToolUse and SessionStart instead; the codex formatter handles this automatically). UserPromptSubmit and Stop capture prompt and turn-end continuity events. See the Codex install section for setup. **Antigravity** and **Zed** do not support hooks. They rely solely on manually-copied routing instruction files (`AGENTS.md` / `GEMINI.md`) for enforcement (~60% compliance). See each platform's install section for copy instructions. Antigravity and Zed are auto-detected via MCP protocol handshake — no manual platform configuration needed.
 >
 > **Kiro** supports native `preToolUse` and `postToolUse` hooks for routing enforcement and tool event capture. `agentSpawn` (SessionStart equivalent) and `stop` are not yet wired. Requires manually copying `KIRO.md` to your project root. Kiro is auto-detected via MCP protocol handshake (`clientInfo.name`).
 >

package/build/adapters/claude-code-base.js

@@ -26,7 +26,7 @@ export class ClaudeCodeBaseAdapter extends BaseAdapter {
             toolName: input.tool_name ?? "",
             toolInput: input.tool_input ?? {},
             sessionId: this.extractSessionId(input),
-            projectDir: process.env[this.projectDirEnvVar],
+            projectDir: process.env[this.projectDirEnvVar] ?? process.cwd(),
             raw,
         };
     }
@@ -38,7 +38,7 @@ export class ClaudeCodeBaseAdapter extends BaseAdapter {
             toolOutput: input.tool_output,
             isError: input.is_error,
             sessionId: this.extractSessionId(input),
-            projectDir: process.env[this.projectDirEnvVar],
+            projectDir: process.env[this.projectDirEnvVar] ?? process.cwd(),
             raw,
         };
     }
@@ -46,7 +46,7 @@ export class ClaudeCodeBaseAdapter extends BaseAdapter {
         const input = raw;
         return {
             sessionId: this.extractSessionId(input),
-            projectDir: process.env[this.projectDirEnvVar],
+            projectDir: process.env[this.projectDirEnvVar] ?? process.cwd(),
             raw,
         };
     }
@@ -70,7 +70,7 @@ export class ClaudeCodeBaseAdapter extends BaseAdapter {
         return {
             sessionId: this.extractSessionId(input),
             source,
-            projectDir: process.env[this.projectDirEnvVar],
+            projectDir: process.env[this.projectDirEnvVar] ?? process.cwd(),
             raw,
         };
     }

package/build/adapters/codex/index.js

@@ -182,6 +182,28 @@ export class CodexAdapter extends BaseAdapter {
                     ],
                 },
             ],
+            UserPromptSubmit: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `node ${pluginRoot}/hooks/codex/userpromptsubmit.mjs`,
+                        },
+                    ],
+                },
+            ],
+            Stop: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `node ${pluginRoot}/hooks/codex/stop.mjs`,
+                        },
+                    ],
+                },
+            ],
         };
     }
     readSettings() {
@@ -208,7 +230,7 @@ export class CodexAdapter extends BaseAdapter {
             {
                 check: "Hook support",
                 status: "pass",
-                message: "Codex CLI hooks are stable. Configure ~/.codex/hooks.json for PreToolUse, PostToolUse, and SessionStart.",
+                message: "Codex CLI hooks are stable. Configure ~/.codex/hooks.json for PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, and Stop.",
             },
         ];
     }

package/build/adapters/qwen-code/index.d.ts

@@ -27,7 +27,7 @@ export declare class QwenCodeAdapter extends ClaudeCodeBaseAdapter implements Ho
     validateHooks(_pluginRoot: string): DiagnosticResult[];
     checkPluginRegistration(): DiagnosticResult;
     getInstalledVersion(): string;
-    configureAllHooks(_pluginRoot: string): string[];
+    configureAllHooks(pluginRoot: string): string[];
     setHookPermissions(_pluginRoot: string): string[];
     updatePluginRegistry(_pluginRoot: string, _version: string): void;
     getRoutingInstructionsConfig(): {

package/build/adapters/qwen-code/index.js

@@ -12,7 +12,7 @@
  *   - MCP clientInfo: qwen-cli-mcp-client-* (pattern)
  *   - 12 hook events (superset of Claude's 5, but context-mode uses the shared 5)
  */
-import { readFileSync, } from "node:fs";
+import { readFileSync, existsSync, } from "node:fs";
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { ClaudeCodeBaseAdapter } from "../claude-code-base.js";
@@ -63,7 +63,7 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
             ],
             PostToolUse: [
                 {
-                    matcher: "",
+                    matcher: "run_shell_command|read_file|write_file|edit|glob|grep_search|todo_write|agent|ask_user_question|mcp__",
                     hooks: [
                         { type: "command", command: `node ${pluginRoot}/hooks/posttooluse.mjs` },
                     ],
@@ -162,10 +162,116 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
         }
     }
     getInstalledVersion() {
+        const settings = this.readSettings();
+        if (!settings)
+            return "not installed";
+        const hooks = settings.hooks;
+        if (!hooks)
+            return "not installed";
+        // Check if any hook type has context-mode scripts configured
+        const contextModeScripts = [
+            "pretooluse.mjs",
+            "posttooluse.mjs",
+            "precompact.mjs",
+            "sessionstart.mjs",
+            "userpromptsubmit.mjs",
+        ];
+        for (const [, entries] of Object.entries(hooks)) {
+            if (!Array.isArray(entries))
+                continue;
+            for (const entry of entries) {
+                const e = entry;
+                if (e.hooks?.some((h) => h.command && contextModeScripts.some((s) => h.command.includes(s)))) {
+                    return "installed (hooks configured)";
+                }
+            }
+        }
         return "not installed";
     }
-    configureAllHooks(_pluginRoot) {
-        return [];
+    configureAllHooks(pluginRoot) {
+        const settings = this.readSettings() ?? {};
+        const hooks = (settings.hooks ?? {});
+        const changes = [];
+        // ── Phase 1: Clean stale context-mode hooks ──────────
+        // After an upgrade, settings.json may contain hardcoded paths
+        // pointing to deleted version directories. Remove those.
+        for (const hookType of Object.keys(hooks)) {
+            const entries = hooks[hookType];
+            if (!Array.isArray(entries))
+                continue;
+            const filtered = entries.filter((entry) => {
+                const e = entry;
+                const commands = e.hooks ?? [];
+                // Preserve entries that are not context-mode hooks
+                const isContextMode = commands.some((h) => h.command && /context-mode|pretooluse|posttooluse|precompact|sessionstart|userpromptsubmit/i.test(h.command));
+                if (!isContextMode)
+                    return true;
+                // For context-mode hooks, check if referenced script files exist
+                return commands.every((h) => {
+                    if (!h.command)
+                        return true;
+                    // Extract path from "node /path/to/script.mjs" format
+                    const match = h.command.match(/node\s+"?([^"]+\.mjs)"?/);
+                    if (!match)
+                        return true; // CLI dispatcher format, always valid
+                    return existsSync(match[1]);
+                });
+            });
+            const removed = entries.length - filtered.length;
+            if (removed > 0) {
+                hooks[hookType] = filtered;
+                changes.push(`Removed ${removed} stale ${hookType} hook(s)`);
+            }
+        }
+        // ── Phase 2: Register fresh hooks ────────────────────
+        const hookTypes = [
+            {
+                name: "PreToolUse",
+                script: "pretooluse.mjs",
+                matcher: [
+                    "run_shell_command", "read_file", "read_many_files", "grep_search",
+                    "web_fetch", "agent",
+                    "mcp__plugin_context-mode_context-mode__ctx_execute",
+                    "mcp__plugin_context-mode_context-mode__ctx_execute_file",
+                    "mcp__plugin_context-mode_context-mode__ctx_batch_execute",
+                ].join("|"),
+            },
+            {
+                name: "SessionStart",
+                script: "sessionstart.mjs",
+                matcher: "",
+            },
+        ];
+        for (const { name, script, matcher } of hookTypes) {
+            const entry = {
+                matcher,
+                hooks: [{ type: "command", command: `node ${pluginRoot}/hooks/${script}` }],
+            };
+            const existing = hooks[name];
+            if (existing && Array.isArray(existing)) {
+                // Replace existing context-mode entry or append
+                const idx = existing.findIndex((e) => {
+                    const typed = e;
+                    return typed.hooks?.some((h) => h.command?.includes(script)) ?? false;
+                });
+                if (idx >= 0) {
+                    existing[idx] = entry;
+                    changes.push(`Updated ${name} hook`);
+                }
+                else {
+                    existing.push(entry);
+                    changes.push(`Added ${name} hook`);
+                }
+                hooks[name] = existing;
+            }
+            else {
+                hooks[name] = [entry];
+                changes.push(`Created ${name} hooks`);
+            }
+        }
+        settings.hooks = hooks;
+        this.writeSettings(settings);
+        return changes;
     }
     setHookPermissions(_pluginRoot) {
         return [];

package/build/cli.js

@@ -55,6 +55,8 @@ const HOOK_MAP = {
         pretooluse: "hooks/codex/pretooluse.mjs",
         posttooluse: "hooks/codex/posttooluse.mjs",
         sessionstart: "hooks/codex/sessionstart.mjs",
+        userpromptsubmit: "hooks/codex/userpromptsubmit.mjs",
+        stop: "hooks/codex/stop.mjs",
     },
     "kiro": {
         pretooluse: "hooks/kiro/pretooluse.mjs",

package/build/opencode-plugin.js

@@ -27,7 +27,7 @@ import { buildResumeSnapshot } from "./session/snapshot.js";
 import { OpenCodeAdapter } from "./adapters/opencode/index.js";
 // ── Helpers ───────────────────────────────────────────────
 function getPlatform() {
-    return process.env.KILO ? "kilo" : "opencode";
+    return process.env.KILO_PID ? "kilo" : "opencode";
 }
 // ── Plugin Factory ────────────────────────────────────────
 /**

package/build/server.js

@@ -58,7 +58,7 @@ const executor = new PolyglotExecutor({
     projectRoot: process.env.CLAUDE_PROJECT_DIR,
 });
 // ─────────────────────────────────────────────────────────
-// FS read tracking preload for batch_execute
+// FS read tracking preload for ctx_batch_execute
 // ─────────────────────────────────────────────────────────
 // NODE_OPTIONS is denied by the executor's #buildSafeEnv (security).
 // Instead, we inject it as an inline shell env prefix in each batch command.
@@ -515,7 +515,7 @@ export function formatBatchQueryResults(store, queries, source, maxOutput = 80 *
     let outputSize = 0;
     for (const query of queries) {
         if (outputSize > maxOutput) {
-            sections.push(`## ${query}\n(output cap reached — use search(queries: ["${query}"]) for details)\n`);
+            sections.push(`## ${query}\n(output cap reached — use ctx_search(queries: ["${query}"]) for details)\n`);
             continue;
         }
         const results = store.searchWithFallback(query, 3, source, undefined, "exact");
@@ -577,7 +577,7 @@ server.registerTool("ctx_execute", {
             .optional()
             .describe("What you're looking for in the output. When provided and output is large (>5KB), " +
             "indexes output into knowledge base and returns section titles + previews — not full content. " +
-            "Use search(queries: [...]) to retrieve specific sections. Example: 'failing tests', 'HTTP 500 errors'." +
+            "Use ctx_search(queries: [...]) to retrieve specific sections. Example: 'failing tests', 'HTTP 500 errors'." +
             "\n\nTIP: Use specific technical terms, not just concepts. Check 'Searchable terms' in the response for available vocabulary."),
     }),
 }, async ({ language, code, timeout, background, intent }) => {
@@ -779,7 +779,7 @@ function indexStdout(stdout, source) {
         content: [
             {
                 type: "text",
-                text: `Indexed ${indexed.totalChunks} sections (${indexed.codeChunks} with code) from: ${indexed.label}\nUse search(queries: ["..."]) to query this content. Use source: "${indexed.label}" to scope results.`,
+                text: `Indexed ${indexed.totalChunks} sections (${indexed.codeChunks} with code) from: ${indexed.label}\nUse ctx_search(queries: ["..."]) to query this content. Use source: "${indexed.label}" to scope results.`,
             },
         ],
     };
@@ -792,7 +792,7 @@ const LARGE_OUTPUT_THRESHOLD = 102_400; // 100KB — auto-index into FTS5, retur
 function intentSearch(stdout, intent, source, maxResults = 5) {
     const totalLines = stdout.split("\n").length;
     const totalBytes = Buffer.byteLength(stdout);
-    // Index into the PERSISTENT store so user can search() later
+    // Index into the PERSISTENT store so user can ctx_search() later
     const persistent = getStore();
     const indexed = persistent.indexPlainText(stdout, source);
     // Search the persistent store directly (porter → trigram → fuzzy)
@@ -809,7 +809,7 @@ function intentSearch(stdout, intent, source, maxResults = 5) {
             lines.push(`Searchable terms: ${distinctiveTerms.join(", ")}`);
         }
         lines.push("");
-        lines.push("Use search() to explore the indexed content.");
+        lines.push("Use ctx_search(queries: [...]) to explore the indexed content.");
         return lines.join("\n");
     }
     // Return ONLY titles + first-line previews — not full content
@@ -827,7 +827,7 @@ function intentSearch(stdout, intent, source, maxResults = 5) {
         lines.push(`Searchable terms: ${distinctiveTerms.join(", ")}`);
     }
     lines.push("");
-    lines.push("Use search(queries: [...]) to retrieve full content of any section.");
+    lines.push("Use ctx_search(queries: [...]) to retrieve full content of any section.");
     return lines.join("\n");
 }
 // ─────────────────────────────────────────────────────────
@@ -977,9 +977,9 @@ server.registerTool("ctx_index", {
         "- Skill prompts and instructions that are too large for context\n" +
         "- README files, migration guides, changelog entries\n" +
         "- Any content with code examples you may need to reference precisely\n\n" +
-        "After indexing, use 'search' to retrieve specific sections on-demand.\n" +
+        "After indexing, use 'ctx_search' to retrieve specific sections on-demand.\n" +
         "When `path` is provided, a content hash is stored for automatic stale detection in search results.\n" +
-        "Do NOT use for: log files, test output, CSV, build output — use 'execute_file' for those.",
+        "Do NOT use for: log files, test output, CSV, build output — use 'ctx_execute_file' for those.",
     inputSchema: z.object({
         content: z
             .string()
@@ -1023,7 +1023,7 @@ server.registerTool("ctx_index", {
             content: [
                 {
                     type: "text",
-                    text: `Indexed ${result.totalChunks} sections (${result.codeChunks} with code) from: ${result.label}\nUse search(queries: ["..."]) to query this content. Use source: "${result.label}" to scope results.`,
+                    text: `Indexed ${result.totalChunks} sections (${result.codeChunks} with code) from: ${result.label}\nUse ctx_search(queries: ["..."]) to query this content. Use source: "${result.label}" to scope results.`,
                 },
             ],
         });
@@ -1151,7 +1151,7 @@ server.registerTool("ctx_search", {
                         type: "text",
                         text: `BLOCKED: ${searchCallCount} search calls in ${Math.round((now - searchWindowStart) / 1000)}s. ` +
                             "You're flooding context. STOP making individual search calls. " +
-                            "Use batch_execute(commands, queries) for your next research step.",
+                            "Use ctx_batch_execute(commands, queries) for your next research step.",
                     }],
                 isError: true,
             });
@@ -1193,7 +1193,7 @@ server.registerTool("ctx_search", {
         if (searchCallCount >= SEARCH_MAX_RESULTS_AFTER) {
             output += `\n\n⚠ search call #${searchCallCount}/${SEARCH_BLOCK_AFTER} in this window. ` +
                 `Results limited to ${effectiveLimit}/query. ` +
-                `Batch queries: search(queries: ["q1","q2","q3"]) or use batch_execute.`;
+                `Batch queries: ctx_search(queries: ["q1","q2","q3"]) or use ctx_batch_execute.`;
         }
         if (output.trim().length === 0) {
             const sources = store.listSources();
@@ -1296,7 +1296,7 @@ main();
 server.registerTool("ctx_fetch_and_index", {
     title: "Fetch & Index URL",
     description: "Fetches URL content, converts HTML to markdown, indexes into searchable knowledge base, " +
-        "and returns a ~3KB preview. Full content stays in sandbox — use search() for deeper lookups.\n\n" +
+        "and returns a ~3KB preview. Full content stays in sandbox — use ctx_search() for deeper lookups.\n\n" +
         "Better than WebFetch: preview is immediate, full content is searchable, raw HTML never enters context.\n\n" +
         "Content-type aware: HTML is converted to markdown, JSON is chunked by key paths, plain text is indexed directly.\n\n" +
         "When reporting results — terse like caveman. Technical substance exact. Only fluff die. Pattern: [thing] [action] [reason]. [next step].",
@@ -1332,7 +1332,7 @@ server.registerTool("ctx_fetch_and_index", {
                 return trackResponse("ctx_fetch_and_index", {
                     content: [{
                             type: "text",
-                            text: `Cached: **${meta.label}** — ${meta.chunkCount} sections, indexed ${ageStr} (fresh, TTL: 24h).\nTo refresh: call ctx_fetch_and_index again with \`force: true\`.\n\nYou MUST call search() to answer questions about this content — this cached response contains no content.\nUse: search(queries: [...], source: "${meta.label}")`,
+                            text: `Cached: **${meta.label}** — ${meta.chunkCount} sections, indexed ${ageStr} (fresh, TTL: 24h).\nTo refresh: call ctx_fetch_and_index again with \`force: true\`.\n\nYou MUST call ctx_search() to answer questions about this content — this cached response contains no content.\nUse: ctx_search(queries: [...], source: "${meta.label}")`,
                         }],
                 });
             }
@@ -1406,12 +1406,12 @@ server.registerTool("ctx_fetch_and_index", {
         // Build preview — first ~3KB of markdown for immediate use
         const PREVIEW_LIMIT = 3072;
         const preview = markdown.length > PREVIEW_LIMIT
-            ? markdown.slice(0, PREVIEW_LIMIT) + "\n\n…[truncated — use search() for full content]"
+            ? markdown.slice(0, PREVIEW_LIMIT) + "\n\n…[truncated — use ctx_search() for full content]"
             : markdown;
         const totalKB = (Buffer.byteLength(markdown) / 1024).toFixed(1);
         const text = [
             `Fetched and indexed **${indexed.totalChunks} sections** (${totalKB}KB) from: ${indexed.label}`,
-            `Full content indexed in sandbox — use search(queries: [...], source: "${indexed.label}") for specific lookups.`,
+            `Full content indexed in sandbox — use ctx_search(queries: [...], source: "${indexed.label}") for specific lookups.`,
             "",
             "---",
             "",
@@ -1445,8 +1445,8 @@ server.registerTool("ctx_batch_execute", {
     title: "Batch Execute & Search",
     description: "Execute multiple commands in ONE call, auto-index all output, and search with multiple queries. " +
         "Returns search results directly — no follow-up calls needed.\n\n" +
-        "THIS IS THE PRIMARY TOOL. Use this instead of multiple execute() calls.\n\n" +
-        "One batch_execute call replaces 30+ execute calls + 10+ search calls.\n" +
+        "THIS IS THE PRIMARY TOOL. Use this instead of multiple ctx_execute() calls.\n\n" +
+        "One ctx_batch_execute call replaces 30+ ctx_execute calls + 10+ ctx_search calls.\n" +
         "Provide all commands to run and all queries to search — everything happens in one round trip.\n\n" +
         "THINK IN CODE: When commands produce data you need to analyze, add processing commands that filter and summarize. Don't pull raw output into context — let the sandbox do the work.\n\n" +
         "When reporting results — terse like caveman. Technical substance exact. Only fluff die. Pattern: [thing] [action] [reason]. [next step].",
@@ -1560,7 +1560,7 @@ server.registerTool("ctx_batch_execute", {
             sectionTitles.push(s.title);
         }
         // Run all search queries — source scoped only.
-        // Cross-source search remains available via explicit search().
+        // Cross-source search remains available via explicit ctx_search().
         const queryResults = formatBatchQueryResults(store, queries, source);
         // Get searchable terms for edge cases where follow-up is needed
         const distinctiveTerms = store.getDistinctiveTerms

package/build/store.js

@@ -218,6 +218,40 @@ function findAllPositions(text, term) {
     }
     return positions;
 }
+/**
+ * Count matched adjacent pairs across consecutive query terms.
+ * For each pair (term[i], term[i+1]), pairs each left position with at most one
+ * right position whose offset falls within `gap` chars of `p + len(term[i])`.
+ * `positionLists` must be sorted ascending (output of `findAllPositions` is).
+ * Each right position is consumed by at most one left, so `"foo foo bar"`
+ * counts 1 pair, not 2 — matches IR phrase-occurrence intent and avoids
+ * inflating boosts for repeated-token queries.
+ * Used by reranker to layer a frequency signal on top of minSpan proximity:
+ * 30-char gap covers natural prose without rewarding distant matches.
+ */
+function countAdjacentPairs(positionLists, terms, gap = 30) {
+    if (positionLists.length < 2 || terms.length < 2)
+        return 0;
+    let total = 0;
+    const pairs = Math.min(positionLists.length, terms.length) - 1;
+    for (let i = 0; i < pairs; i++) {
+        const left = positionLists[i];
+        const right = positionLists[i + 1];
+        const leftLen = terms[i].length;
+        let j = 0;
+        for (const p of left) {
+            const minStart = p + leftLen;
+            const maxStart = minStart + gap;
+            while (j < right.length && right[j] < minStart)
+                j++;
+            if (j < right.length && right[j] <= maxStart) {
+                total++;
+                j++;
+            }
+        }
+    }
+    return total;
+}
 /**
  * Find minimum span (window) covering at least one position from each list.
  * Uses a sweep-line approach: advance the pointer at the current minimum.
@@ -603,10 +637,16 @@ export class ContentStore {
     // ── Index ──
     index(options) {
         const { content, path, source } = options;
-        if (!content && !path) {
+        // Treat empty string as "no content" so an empty `content` paired with a
+        // valid `path` falls back to reading the file. Some MCP clients
+        // materialize optional string fields as `""` and the previous
+        // `content ?? readFileSync(path)` kept the empty string, indexing 0
+        // chunks. See issue #350.
+        const hasContent = typeof content === "string" && content.length > 0;
+        if (!hasContent && !path) {
             throw new Error("Either content or path must be provided");
         }
-        const text = content ?? readFileSync(path, "utf-8");
+        const text = hasContent ? content : readFileSync(path, "utf-8");
         const label = source ?? path ?? "untitled";
         const chunks = this.#chunkMarkdown(text);
         // Stale detection: store file_path + SHA-256 for file-backed sources
@@ -859,17 +899,24 @@ export class ContentStore {
             const titleHits = terms.filter((t) => titleLower.includes(t)).length;
             const titleWeight = r.contentType === "code" ? 0.6 : 0.3;
             const titleBoost = titleHits > 0 ? titleWeight * (titleHits / terms.length) : 0;
-            // Proximity boost for multi-term queries
+            // Proximity boost for multi-term queries. minSpan picks the single
+            // tightest window — frequency doesn't move it, so a long doc with one
+            // tight occurrence outranks a short doc with several. Phrase-frequency
+            // reward layers a saturating frequency signal on top: cap 0.5 (below
+            // proximity max ≈1.0, in title-boost range), saturates at 4 hits.
             let proximityBoost = 0;
+            let phraseBoost = 0;
             if (terms.length >= 2) {
                 const content = r.content.toLowerCase();
                 const positions = terms.map((t) => findAllPositions(content, t));
                 if (!positions.some((p) => p.length === 0)) {
                     const minSpan = findMinSpan(positions);
                     proximityBoost = 1 / (1 + minSpan / Math.max(content.length, 1));
+                    const adjacentPairs = countAdjacentPairs(positions, terms);
+                    phraseBoost = 0.5 * Math.min(1, adjacentPairs / 4);
                 }
             }
-            return { result: r, boost: titleBoost + proximityBoost };
+            return { result: r, boost: titleBoost + proximityBoost + phraseBoost };
         })
             .sort((a, b) => b.boost - a.boost || a.result.rank - b.result.rank)
             .map(({ result }) => result);