context-mode 1.0.53 → 1.0.56

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.53",
+  "version": "1.0.56",
   "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

@@ -5,14 +5,6 @@
 [![users](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcdn.jsdelivr.net%2Fgh%2Fmksglu%2Fcontext-mode%40main%2Fstats.json&query=%24.message&label=users&color=brightgreen)](https://www.npmjs.com/package/context-mode) [![npm](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcdn.jsdelivr.net%2Fgh%2Fmksglu%2Fcontext-mode%40main%2Fstats.json&query=%24.npm&label=npm&color=blue)](https://www.npmjs.com/package/context-mode) [![marketplace](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcdn.jsdelivr.net%2Fgh%2Fmksglu%2Fcontext-mode%40main%2Fstats.json&query=%24.marketplace&label=marketplace&color=blue)](https://github.com/mksglu/context-mode) [![GitHub stars](https://img.shields.io/github/stars/mksglu/context-mode?style=flat&color=yellow)](https://github.com/mksglu/context-mode/stargazers) [![GitHub forks](https://img.shields.io/github/forks/mksglu/context-mode?style=flat&color=blue)](https://github.com/mksglu/context-mode/network/members) [![Last commit](https://img.shields.io/github/last-commit/mksglu/context-mode?color=green)](https://github.com/mksglu/context-mode/commits) [![License: ELv2](https://img.shields.io/badge/License-ELv2-blue.svg)](LICENSE)
 [![Discord](https://img.shields.io/discord/1478479412700909750?label=Discord&logo=discord&color=5865f2)](https://discord.gg/DCN9jUgN5v)
 
-## Privacy & Architecture
-
-Context Mode is not a CLI output filter or a cloud analytics dashboard. It operates at the MCP protocol layer — raw data stays in a sandboxed subprocess and never enters your context window. Web pages, API responses, file analysis, Playwright snapshots, log files — everything is processed in complete isolation.
-
-**Nothing leaves your machine.** No telemetry, no cloud sync, no usage tracking, no account required. Your code, your prompts, your session data — all local. The SQLite databases live in your home directory and die when you're done.
-
-This is a deliberate architectural choice, not a missing feature. Context optimization should happen at the source, not in a dashboard behind a per-seat subscription. Privacy-first is our philosophy — and every design decision follows from it. [License →](#license)
-
 ## The Problem
 
 Every MCP tool call dumps raw data into your context window. A Playwright snapshot costs 56 KB. Twenty GitHub issues cost 59 KB. One access log — 45 KB. After 30 minutes, 40% of your context is gone. And when the agent compacts the conversation to free space, it forgets which files it was editing, what tasks are in progress, and what you last asked for.
@@ -290,15 +282,69 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
 
    The `mcp` entry registers the 6 sandbox tools. The `plugin` entry enables hooks — OpenCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing.
 
-3. Restart OpenCode.
+3. *(Optional)* Copy the routing rules file. OpenCode lacks a SessionStart hook, so the model needs an `AGENTS.md` file for routing awareness:
+
+   ```bash
+   cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md
+   ```
+
+   This tells the model which tools to use and which commands are blocked. Without it, hooks still enforce routing — but the model won't know *why* a command was denied.
+
+4. Restart OpenCode.
 
 **Verify:** In the OpenCode session, type `ctx stats`. Context-mode tools should appear and respond.
 
-**Routing:** Automatic. The plugin intercepts tool calls at runtime via `tool.execute.before` and `tool.execute.after`. No routing file is written to your project. The `experimental.session.compacting` hook builds resume snapshots when the conversation compacts.
+**Routing:** Hooks enforce routing programmatically via `tool.execute.before` and `tool.execute.after`. The optional [`AGENTS.md`](configs/opencode/AGENTS.md) file provides routing instructions for model awareness. The `experimental.session.compacting` hook builds resume snapshots when the conversation compacts.
 
 > **Note:** OpenCode's SessionStart hook is not yet available ([#14808](https://github.com/sst/opencode/issues/14808)), so startup/resume session restore is not supported. Compaction recovery works fully via the plugin.
 
-Full config: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
+Full configs: [`configs/opencode/opencode.json`](configs/opencode/opencode.json) | [`configs/opencode/AGENTS.md`](configs/opencode/AGENTS.md)
+
+</details>
+
+<details>
+<summary><strong>KiloCode</strong> — TypeScript plugin with hooks</summary>
+
+**Prerequisites:** Node.js 18+, KiloCode installed.
+
+**Install:**
+
+1. Install context-mode globally:
+
+   ```bash
+   npm install -g context-mode
+   ```
+
+2. Add to `kilo.json` in your project root (or `~/.config/kilo/kilo.json` for global):
+
+   ```json
+   {
+     "$schema": "https://app.kilo.ai/config.json",
+     "mcp": {
+       "context-mode": {
+         "type": "local",
+         "command": ["context-mode"]
+       }
+     },
+     "plugin": ["context-mode"]
+   }
+   ```
+
+   The `mcp` entry registers the 6 sandbox tools. The `plugin` entry enables hooks — KiloCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing.
+
+3. *(Optional)* Copy the routing rules file. KiloCode shares the OpenCode plugin architecture and lacks SessionStart, so the model needs an `AGENTS.md` file for routing awareness:
+
+   ```bash
+   cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md
+   ```
+
+4. Restart KiloCode.
+
+**Verify:** In the KiloCode session, type `ctx stats`. Context-mode tools should appear and respond.
+
+**Routing:** Hooks enforce routing programmatically via `tool.execute.before` and `tool.execute.after`. The optional [`AGENTS.md`](configs/opencode/AGENTS.md) file provides routing instructions for model awareness. The `experimental.session.compacting` hook builds resume snapshots when the conversation compacts.
+
+> **Note:** KiloCode shares the same plugin architecture as OpenCode, using the OpenCodeAdapter with platform-specific configuration paths (`kilo.json` instead of `opencode.json`, `~/.config/kilo/` instead of `~/.config/opencode/`). SessionStart hook availability depends on KiloCode's implementation.
 
 </details>
 
@@ -601,7 +647,7 @@ npm install -g context-mode
 | `ctx_execute_file` | Process files in sandbox. Raw content never leaves. | 45 KB → 155 B |
 | `ctx_index` | Chunk markdown into FTS5 with BM25 ranking. | 60 KB → 40 B |
 | `ctx_search` | Query indexed content with multiple queries in one call. | On-demand retrieval |
-| `ctx_fetch_and_index` | Fetch URL, detect content type (HTML/JSON/text), chunk and index. | 60 KB → 40 B |
+| `ctx_fetch_and_index` | Fetch URL, chunk and index. 24h TTL cache — repeat calls skip network. `force: true` to bypass. | 60 KB → 40 B |
 | `ctx_stats` | Show context savings, call counts, and session statistics. | — |
 | `ctx_doctor` | Diagnose installation: runtimes, hooks, FTS5, versions. | — |
 | `ctx_upgrade` | Upgrade to latest version from GitHub, rebuild, reconfigure hooks. | — |
@@ -643,6 +689,19 @@ Levenshtein distance corrects typos before re-searching. "kuberntes" becomes "ku
 
 Search results use intelligent extraction instead of truncation. Instead of returning the first N characters (which might miss the important part), Context Mode finds where your query terms appear in the content and returns windows around those matches.
 
+### TTL Cache
+
+Indexed content persists in a per-project SQLite database at `~/.context-mode/content/`. When `ctx_fetch_and_index` is called for a URL that was already indexed within the last 24 hours, the fetch is skipped entirely. The model searches the existing index directly.
+
+- **Fresh (<24h):** Returns a cache hint (0.3KB) instead of re-fetching (48KB+). Model proceeds to `ctx_search`.
+- **Stale (>24h):** Re-fetches silently. No user action needed.
+- **`force: true`:** Bypasses cache and re-fetches regardless of TTL.
+- **14-day cleanup:** Content databases and sources older than 14 days are removed on startup.
+
+This means `--continue` sessions preserve indexed docs across restarts. No re-fetching, no wasted context tokens.
+
+`ctx_stats` reports cache performance separately: hits, data avoided, network requests saved, and total context savings including cache.
+
 ### Progressive Throttling
 
 - **Calls 1-3:** Normal results (2 per query)
@@ -657,15 +716,15 @@ Context Mode captures every meaningful event during your session and persists th
 
 Session continuity requires 4 hooks working together:
 
-| Hook | Role | Claude Code | Gemini CLI | VS Code Copilot | Cursor | OpenCode | OpenClaw | Codex CLI | Antigravity | Kiro | Zed | Pi |
-|---|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| **PostToolUse** | Captures events after each tool call | Yes | Yes | Yes | Yes | Plugin | Plugin | -- | -- | Yes | -- | ✓ (via tool_result event) |
-| **UserPromptSubmit** | Captures user decisions and corrections | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
-| **PreCompact** | Builds snapshot before compaction | Yes | Yes | Yes | -- | Plugin | Plugin | -- | -- | -- | -- | ✓ (via session_before_compact) |
-| **SessionStart** | Restores state after compaction or resume | Yes | Yes | Yes | -- | -- | Plugin | -- | -- | -- | -- | ✓ (via session_start event) |
-| | **Session completeness** | **Full** | **High** | **High** | **Partial** | **High** | **High** | **--** | **--** | **Partial** | **--** | **High** |
+| Hook | Role | Claude Code | Gemini CLI | VS Code Copilot | Cursor | OpenCode | KiloCode | OpenClaw | Codex CLI | Antigravity | Kiro | Zed | Pi |
+|---|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| **PostToolUse** | Captures events after each tool call | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | -- | -- | Yes | -- | ✓ (via tool_result event) |
+| **UserPromptSubmit** | Captures user decisions and corrections | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
+| **PreCompact** | Builds snapshot before compaction | Yes | Yes | Yes | -- | Plugin | Plugin | Plugin | -- | -- | -- | -- | ✓ (via session_before_compact) |
+| **SessionStart** | Restores state after compaction or resume | Yes | Yes | Yes | -- | -- | -- | Plugin | -- | -- | -- | -- | ✓ (via session_start event) |
+| | **Session completeness** | **Full** | **High** | **High** | **Partial** | **High** | **High** | **High** | **--** | **--** | **Partial** | **--** | **High** |
 
-> **Note:** Full session continuity (capture + snapshot + restore) works on **Claude Code**, **Gemini CLI**, **VS Code Copilot**, and **OpenCode**. **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. **OpenCode** uses the `experimental.session.compacting` plugin hook for compaction recovery, but SessionStart is not yet available ([#14808](https://github.com/sst/opencode/issues/14808)), so startup/resume is not supported. **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**, **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**, and **VS Code 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**, **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>
@@ -744,6 +803,8 @@ Detailed event data is also indexed into FTS5 for on-demand retrieval via `searc
 
 **OpenCode** — Partial. The TypeScript plugin captures PostToolUse events via `tool.execute.after`, but SessionStart is not yet available ([#14808](https://github.com/sst/opencode/issues/14808)). Events are stored but not automatically restored after compaction.
 
+**KiloCode** — Partial. Shares the same plugin architecture as OpenCode via the OpenCodeAdapter. The TypeScript plugin captures PostToolUse events via `tool.execute.after`, but SessionStart availability depends on KiloCode's implementation. Events are stored but may not be automatically restored after compaction.
+
 **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** — No session support. No hooks means no event capture. Each compaction or new session starts fresh. Requires manually copying `AGENTS.md` to your project root.
@@ -760,21 +821,23 @@ Detailed event data is also indexed into FTS5 for on-demand retrieval via `searc
 
 ## Platform Compatibility
 
-| Feature | Claude Code | Gemini CLI | VS Code Copilot | Cursor | OpenCode | OpenClaw | Codex CLI | Antigravity | Kiro | Zed | Pi |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| MCP Server | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
-| PreToolUse Hook | Yes | Yes | Yes | Yes | Plugin | Plugin | -- | -- | Yes | -- | Yes (extension) |
-| PostToolUse Hook | Yes | Yes | Yes | Yes | Plugin | Plugin | -- | -- | Yes | -- | Yes (extension) |
-| SessionStart Hook | Yes | Yes | Yes | -- | -- | Plugin | -- | -- | -- | -- | Yes (extension) |
-| PreCompact Hook | Yes | Yes | Yes | -- | Plugin | Plugin | -- | -- | -- | -- | Yes (extension) |
-| Can Modify Args | Yes | Yes | Yes | Yes | Plugin | Plugin | -- | -- | -- | -- | Yes (extension) |
-| Can Block Tools | Yes | Yes | Yes | Yes | Plugin | Plugin | -- | -- | Yes | -- | Yes (extension) |
-| Utility Commands (ctx) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes (/ctx-stats, /ctx-doctor) |
-| Slash Commands | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
-| Plugin Marketplace | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
+| Feature | Claude Code | Gemini CLI | VS Code Copilot | Cursor | OpenCode | KiloCode | OpenClaw | Codex CLI | Antigravity | Kiro | Zed | Pi |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| MCP Server | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| PreToolUse Hook | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | -- | -- | Yes | -- | Yes (extension) |
+| PostToolUse Hook | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | -- | -- | Yes | -- | Yes (extension) |
+| SessionStart Hook | Yes | Yes | Yes | -- | -- | -- | Plugin | -- | -- | -- | -- | Yes (extension) |
+| PreCompact Hook | Yes | Yes | Yes | -- | Plugin | Plugin | Plugin | -- | -- | -- | -- | Yes (extension) |
+| Can Modify Args | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | -- | -- | -- | -- | Yes (extension) |
+| Can Block Tools | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | -- | -- | Yes | -- | Yes (extension) |
+| Utility Commands (ctx) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes (/ctx-stats, /ctx-doctor) |
+| Slash Commands | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
+| Plugin Marketplace | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
 
 > **OpenCode** uses a TypeScript plugin paradigm — hooks run as in-process functions via `tool.execute.before`, `tool.execute.after`, and `experimental.session.compacting`, providing the same routing enforcement and session continuity as shell-based hooks. SessionStart is not yet available ([#14808](https://github.com/sst/opencode/issues/14808)), but compaction recovery works via the plugin's compacting hook.
 >
+> **KiloCode** shares the same TypeScript plugin architecture as OpenCode via the OpenCodeAdapter, with platform-specific configuration paths (`kilo.json` instead of `opencode.json`, `~/.config/kilo/` instead of `~/.config/opencode/`). Hook capabilities depend on KiloCode's implementation of the plugin interface.
+>
 > **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**, **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.
@@ -887,6 +950,14 @@ event count. When context compacts, the model continues from your last prompt
 with tasks, files, and decisions intact — no re-prompting needed.
 ```
 
+## Privacy & Architecture
+
+Context Mode is not a CLI output filter or a cloud analytics dashboard. It operates at the MCP protocol layer — raw data stays in a sandboxed subprocess and never enters your context window. Web pages, API responses, file analysis, Playwright snapshots, log files — everything is processed in complete isolation.
+
+**Nothing leaves your machine.** No telemetry, no cloud sync, no usage tracking, no account required. Your code, your prompts, your session data — all local. The SQLite databases live in your home directory and die when you're done.
+
+This is a deliberate architectural choice, not a missing feature. Context optimization should happen at the source, not in a dashboard behind a per-seat subscription. Privacy-first is our philosophy — and every design decision follows from it. [License →](#license)
+
 ## Security
 
 Context Mode enforces the same permission rules you already use — but extends them to the MCP sandbox. If you block `sudo`, it's also blocked inside `ctx_execute`, `ctx_execute_file`, and `ctx_batch_execute`.

package/build/adapters/antigravity/index.d.ts

@@ -16,7 +16,7 @@
  *   - MCP support: https://antigravity.google/docs/mcp
  *   - Tool list: System prompt leak (21 verified tools)
  */
-import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration, RoutingInstructionsConfig } from "../types.js";
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration } from "../types.js";
 export declare class AntigravityAdapter implements HookAdapter {
     readonly name = "Antigravity";
     readonly paradigm: HookParadigm;
@@ -43,7 +43,5 @@ export declare class AntigravityAdapter implements HookAdapter {
     backupSettings(): string | null;
     setHookPermissions(_pluginRoot: string): string[];
     updatePluginRegistry(_pluginRoot: string, _version: string): void;
-    getRoutingInstructionsConfig(): RoutingInstructionsConfig;
-    writeRoutingInstructions(projectDir: string, pluginRoot: string): string | null;
     getRoutingInstructions(): string;
 }

package/build/adapters/antigravity/index.js

@@ -175,36 +175,6 @@ export class AntigravityAdapter {
     updatePluginRegistry(_pluginRoot, _version) {
         // Antigravity plugin registry is managed via mcp_config.json
     }
-    // ── Routing Instructions (soft enforcement) ────────────
-    getRoutingInstructionsConfig() {
-        return {
-            fileName: "GEMINI.md",
-            globalPath: resolve(homedir(), ".gemini", "GEMINI.md"),
-            projectRelativePath: "GEMINI.md",
-        };
-    }
-    writeRoutingInstructions(projectDir, pluginRoot) {
-        const config = this.getRoutingInstructionsConfig();
-        const targetPath = resolve(projectDir, config.projectRelativePath);
-        const sourcePath = resolve(pluginRoot, "configs", "antigravity", config.fileName);
-        try {
-            const content = readFileSync(sourcePath, "utf-8");
-            try {
-                const existing = readFileSync(targetPath, "utf-8");
-                if (existing.includes("context-mode"))
-                    return null;
-                writeFileSync(targetPath, existing.trimEnd() + "\n\n" + content, "utf-8");
-                return targetPath;
-            }
-            catch {
-                writeFileSync(targetPath, content, "utf-8");
-                return targetPath;
-            }
-        }
-        catch {
-            return null;
-        }
-    }
     getRoutingInstructions() {
         const instructionsPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "configs", "antigravity", "GEMINI.md");
         try {

package/build/adapters/claude-code/hooks.d.ts

@@ -53,3 +53,21 @@ export declare function isContextModeHook(entry: {
  * Falls back to CLI dispatcher if pluginRoot is not provided.
  */
 export declare function buildHookCommand(hookType: HookType, pluginRoot?: string): string;
+/**
+ * Extract the hook script file path from a command string.
+ * Returns the path if the command uses the `node "/path/to/hook.mjs"` format,
+ * or null if it uses the CLI dispatcher format (which is path-independent).
+ *
+ * Handles both quoted and unquoted paths, and both forward/back slashes.
+ */
+export declare function extractHookScriptPath(command: string): string | null;
+/**
+ * Check if a hook entry is a context-mode hook (any hook type).
+ * Broader than `isContextModeHook` — matches any context-mode script name
+ * without requiring a specific hookType.
+ */
+export declare function isAnyContextModeHook(entry: {
+    hooks?: Array<{
+        command?: string;
+    }>;
+}): boolean;

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

@@ -93,3 +93,26 @@ export function buildHookCommand(hookType, pluginRoot) {
     }
     return `context-mode hook claude-code ${hookType.toLowerCase()}`;
 }
+/**
+ * Extract the hook script file path from a command string.
+ * Returns the path if the command uses the `node "/path/to/hook.mjs"` format,
+ * or null if it uses the CLI dispatcher format (which is path-independent).
+ *
+ * Handles both quoted and unquoted paths, and both forward/back slashes.
+ */
+export function extractHookScriptPath(command) {
+    // Match: node "/path/to/hooks/scriptname.mjs" or node /path/to/hooks/scriptname.mjs
+    const match = command.match(/node\s+"?([^"]+\.mjs)"?/);
+    return match?.[1] ?? null;
+}
+/**
+ * Check if a hook entry is a context-mode hook (any hook type).
+ * Broader than `isContextModeHook` — matches any context-mode script name
+ * without requiring a specific hookType.
+ */
+export function isAnyContextModeHook(entry) {
+    const scriptNames = Object.values(HOOK_SCRIPTS);
+    return (entry.hooks?.some((h) => h.command != null &&
+        (scriptNames.some((s) => h.command.includes(s)) ||
+            h.command.includes("context-mode hook"))) ?? false);
+}

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

@@ -13,7 +13,7 @@
  *   - Config: ~/.claude/settings.json
  *   - Session dir: ~/.claude/context-mode/sessions/
  */
-import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration, RoutingInstructionsConfig } from "../types.js";
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration } from "../types.js";
 export declare class ClaudeCodeAdapter implements HookAdapter {
     readonly name = "Claude Code";
     readonly paradigm: HookParadigm;
@@ -44,8 +44,6 @@ export declare class ClaudeCodeAdapter implements HookAdapter {
     backupSettings(): string | null;
     setHookPermissions(pluginRoot: string): string[];
     updatePluginRegistry(pluginRoot: string, version: string): void;
-    getRoutingInstructionsConfig(): RoutingInstructionsConfig;
-    writeRoutingInstructions(projectDir: string, pluginRoot: string): string | null;
     /**
      * Extract session ID from Claude Code hook input.
      * Priority: transcript_path UUID > session_id field > CLAUDE_SESSION_ID env > ppid fallback.

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

@@ -14,10 +14,10 @@
  *   - Session dir: ~/.claude/context-mode/sessions/
  */
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, readdirSync, chmodSync, constants, } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, existsSync, readdirSync, chmodSync, constants, } from "node:fs";
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
-import { HOOK_TYPES, HOOK_SCRIPTS, PRE_TOOL_USE_MATCHER_PATTERN, isContextModeHook, buildHookCommand, } from "./hooks.js";
+import { HOOK_TYPES, HOOK_SCRIPTS, REQUIRED_HOOKS, PRE_TOOL_USE_MATCHER_PATTERN, isContextModeHook, isAnyContextModeHook, extractHookScriptPath, buildHookCommand, } from "./hooks.js";
 // ─────────────────────────────────────────────────────────
 // Adapter implementation
 // ─────────────────────────────────────────────────────────
@@ -383,6 +383,52 @@ export class ClaudeCodeAdapter {
         const settings = this.readSettings() ?? {};
         const hooks = (settings.hooks ?? {});
         const changes = [];
+        // Remove stale context-mode hook entries across ALL hook types (fixes #187).
+        // After a marketplace auto-update or version change, settings.json may contain
+        // hardcoded paths pointing to deleted version directories (e.g., .../0.9.17/hooks/...).
+        // Clean these before registering fresh entries to prevent SessionStart errors.
+        for (const hookType of Object.keys(hooks)) {
+            const entries = hooks[hookType];
+            if (!Array.isArray(entries))
+                continue;
+            const filtered = entries.filter((entry) => {
+                const typedEntry = entry;
+                if (!isAnyContextModeHook(typedEntry))
+                    return true; // preserve non-context-mode hooks
+                // Keep CLI dispatcher entries (path-independent, never stale)
+                const commands = typedEntry.hooks ?? [];
+                const hasOnlyDispatcherCommands = commands.every((h) => !h.command || !extractHookScriptPath(h.command));
+                if (hasOnlyDispatcherCommands)
+                    return true;
+                // For node path commands, check if the referenced script file exists
+                return commands.every((h) => {
+                    const scriptPath = h.command ? extractHookScriptPath(h.command) : null;
+                    if (!scriptPath)
+                        return true; // not a path-based command
+                    return existsSync(scriptPath);
+                });
+            });
+            const removed = entries.length - filtered.length;
+            if (removed > 0) {
+                hooks[hookType] = filtered;
+                changes.push(`Removed ${removed} stale ${hookType} hook(s)`);
+            }
+        }
+        // If plugin hooks.json already covers all required hooks, skip settings.json
+        // registration entirely (Issue #198). Plugin installs don't need settings.json
+        // entries — hooks.json with ${CLAUDE_PLUGIN_ROOT} is the source of truth.
+        const pluginHooks = this.readPluginHooks(pluginRoot);
+        if (pluginHooks) {
+            const allCovered = REQUIRED_HOOKS.every((ht) => this.checkHookType(undefined, pluginHooks, ht));
+            if (allCovered) {
+                // Still write cleaned settings (stale removal) but don't add new entries
+                settings.hooks = hooks;
+                this.writeSettings(settings);
+                changes.push("Skipped settings.json registration — plugin hooks.json is sufficient");
+                return changes;
+            }
+        }
+        // Register fresh hooks for required hook types
         const hookTypes = [
             HOOK_TYPES.PRE_TOOL_USE,
             HOOK_TYPES.SESSION_START,
@@ -486,39 +532,6 @@ export class ClaudeCodeAdapter {
             /* best effort */
         }
     }
-    // ── Routing Instructions (soft enforcement) ────────────
-    getRoutingInstructionsConfig() {
-        return {
-            fileName: "CLAUDE.md",
-            globalPath: resolve(homedir(), ".claude", "CLAUDE.md"),
-            projectRelativePath: "CLAUDE.md",
-        };
-    }
-    writeRoutingInstructions(projectDir, pluginRoot) {
-        const config = this.getRoutingInstructionsConfig();
-        const targetPath = resolve(projectDir, config.projectRelativePath);
-        const sourcePath = resolve(pluginRoot, "configs", "claude-code", config.fileName);
-        try {
-            const content = readFileSync(sourcePath, "utf-8");
-            // Check if file exists and already has context-mode instructions
-            try {
-                const existing = readFileSync(targetPath, "utf-8");
-                if (existing.includes("context-mode"))
-                    return null;
-                // Append to existing file
-                writeFileSync(targetPath, existing.trimEnd() + "\n\n" + content, "utf-8");
-                return targetPath;
-            }
-            catch {
-                // File doesn't exist — create it
-                writeFileSync(targetPath, content, "utf-8");
-                return targetPath;
-            }
-        }
-        catch {
-            return null;
-        }
-    }
     // ── Internal helpers ───────────────────────────────────
     /**
      * Extract session ID from Claude Code hook input.

package/build/adapters/client-map.js

@@ -14,6 +14,7 @@ export const CLIENT_NAME_TO_PLATFORM = {
     "Visual-Studio-Code": "vscode-copilot",
     "Codex": "codex",
     "codex-mcp-client": "codex",
+    "Kilo Code": "kilo",
     "Kiro CLI": "kiro",
     "Pi CLI": "pi",
     "Pi Coding Agent": "pi",

package/build/adapters/codex/index.d.ts

@@ -11,7 +11,7 @@
  *   - All capabilities are false — MCP is the only integration path
  *   - Session dir: ~/.codex/context-mode/sessions/
  */
-import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration, RoutingInstructionsConfig } from "../types.js";
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration } from "../types.js";
 export declare class CodexAdapter implements HookAdapter {
     readonly name = "Codex CLI";
     readonly paradigm: HookParadigm;
@@ -38,7 +38,5 @@ export declare class CodexAdapter implements HookAdapter {
     backupSettings(): string | null;
     setHookPermissions(_pluginRoot: string): string[];
     updatePluginRegistry(_pluginRoot: string, _version: string): void;
-    getRoutingInstructionsConfig(): RoutingInstructionsConfig;
-    writeRoutingInstructions(projectDir: string, pluginRoot: string): string | null;
     getRoutingInstructions(): string;
 }

package/build/adapters/codex/index.js

@@ -12,7 +12,7 @@
  *   - Session dir: ~/.codex/context-mode/sessions/
  */
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, constants, } from "node:fs";
+import { readFileSync, mkdirSync, copyFileSync, accessSync, constants, } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -180,36 +180,6 @@ export class CodexAdapter {
     updatePluginRegistry(_pluginRoot, _version) {
         // Codex CLI has no plugin registry
     }
-    // ── Routing Instructions (soft enforcement) ────────────
-    getRoutingInstructionsConfig() {
-        return {
-            fileName: "AGENTS.md",
-            globalPath: resolve(homedir(), ".codex", "AGENTS.md"),
-            projectRelativePath: "AGENTS.md",
-        };
-    }
-    writeRoutingInstructions(projectDir, pluginRoot) {
-        const config = this.getRoutingInstructionsConfig();
-        const targetPath = resolve(projectDir, config.projectRelativePath);
-        const sourcePath = resolve(pluginRoot, "configs", "codex", config.fileName);
-        try {
-            const content = readFileSync(sourcePath, "utf-8");
-            try {
-                const existing = readFileSync(targetPath, "utf-8");
-                if (existing.includes("context-mode"))
-                    return null;
-                writeFileSync(targetPath, existing.trimEnd() + "\n\n" + content, "utf-8");
-                return targetPath;
-            }
-            catch {
-                writeFileSync(targetPath, content, "utf-8");
-                return targetPath;
-            }
-        }
-        catch {
-            return null;
-        }
-    }
     getRoutingInstructions() {
         const instructionsPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "configs", "codex", "AGENTS.md");
         try {

package/build/adapters/cursor/index.d.ts

@@ -4,7 +4,7 @@
  * Native Cursor hooks use lower-camel hook names and flat command entries in
  * `.cursor/hooks.json` / `~/.cursor/hooks.json`.
  */
-import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, SessionStartResponse, HookRegistration, RoutingInstructionsConfig } from "../types.js";
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, SessionStartResponse, HookRegistration } from "../types.js";
 export declare class CursorAdapter implements HookAdapter {
     readonly name = "Cursor";
     readonly paradigm: HookParadigm;
@@ -29,8 +29,6 @@ export declare class CursorAdapter implements HookAdapter {
     backupSettings(): string | null;
     setHookPermissions(pluginRoot: string): string[];
     updatePluginRegistry(_pluginRoot: string, _version: string): void;
-    getRoutingInstructionsConfig(): RoutingInstructionsConfig;
-    writeRoutingInstructions(_projectDir: string, _pluginRoot: string): string | null;
     private getCandidateHookConfigPaths;
     private getProjectDir;
     private extractSessionId;

package/build/adapters/cursor/index.js

@@ -338,17 +338,6 @@ export class CursorAdapter {
     updatePluginRegistry(_pluginRoot, _version) {
         // Cursor manages extensions and native hooks internally.
     }
-    getRoutingInstructionsConfig() {
-        return {
-            fileName: "AGENTS.md",
-            globalPath: "",
-            projectRelativePath: "AGENTS.md",
-        };
-    }
-    writeRoutingInstructions(_projectDir, _pluginRoot) {
-        // Native Cursor hook support ships independently from any instruction-file story.
-        return null;
-    }
     getCandidateHookConfigPaths() {
         const paths = [this.getSettingsPath(), join(homedir(), ".cursor", "hooks.json")];
         if (process.platform === "darwin") {

package/build/adapters/detect.d.ts

@@ -9,6 +9,7 @@
  * Verified env vars per platform (from source code audit):
  *   - Claude Code:    CLAUDE_PROJECT_DIR, CLAUDE_SESSION_ID | ~/.claude/
  *   - Gemini CLI:     GEMINI_PROJECT_DIR (hooks), GEMINI_CLI (MCP) | ~/.gemini/
+ *   - KiloCode:       KILO, KILO_PID | ~/.config/kilo/
  *   - OpenCode:       OPENCODE, OPENCODE_PID | ~/.config/opencode/
  *   - OpenClaw:       OPENCLAW_HOME, OPENCLAW_CLI | ~/.openclaw/
  *   - Codex CLI:      CODEX_CI, CODEX_THREAD_ID | ~/.codex/