context-mode 1.0.53 → 1.0.54

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.54"
   },
   "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.54",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.53",
+  "version": "1.0.54",
   "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.54",
   "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.54",
   "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.
@@ -302,6 +294,46 @@ Full config: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
 
 </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. Restart KiloCode.
+
+**Verify:** In the KiloCode 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.
+
+> **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>
+
 <details>
 <summary><strong>OpenClaw / Pi Agent</strong> — native gateway plugin</summary>
 
@@ -601,7 +633,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 +675,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 +702,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**, **VS Code Copilot**, and **OpenCode**. **KiloCode** shares the same plugin architecture as OpenCode via the OpenCodeAdapter. **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.
 
 <details>
 <summary><strong>What gets captured</strong></summary>
@@ -744,6 +789,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 +807,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 +936,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/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.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, PRE_TOOL_USE_MATCHER_PATTERN, isContextModeHook, isAnyContextModeHook, extractHookScriptPath, buildHookCommand, } from "./hooks.js";
 // ─────────────────────────────────────────────────────────
 // Adapter implementation
 // ─────────────────────────────────────────────────────────
@@ -383,6 +383,38 @@ 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)`);
+            }
+        }
+        // Register fresh hooks for required hook types
         const hookTypes = [
             HOOK_TYPES.PRE_TOOL_USE,
             HOOK_TYPES.SESSION_START,

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/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/

package/build/adapters/detect.js

@@ -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/
@@ -41,7 +42,7 @@ export function detectPlatform(clientInfo) {
     const platformOverride = process.env.CONTEXT_MODE_PLATFORM;
     if (platformOverride) {
         const validPlatforms = [
-            "claude-code", "gemini-cli", "opencode", "codex",
+            "claude-code", "gemini-cli", "kilo", "opencode", "codex",
             "vscode-copilot", "cursor", "antigravity", "kiro", "pi", "zed",
         ];
         if (validPlatforms.includes(platformOverride)) {
@@ -74,6 +75,13 @@ export function detectPlatform(clientInfo) {
             reason: "OPENCLAW_HOME or OPENCLAW_CLI env var set",
         };
     }
+    if (process.env.KILO || process.env.KILO_PID) {
+        return {
+            platform: "kilo",
+            confidence: "high",
+            reason: "KILO or KILO_PID env var set",
+        };
+    }
     if (process.env.OPENCODE || process.env.OPENCODE_PID) {
         return {
             platform: "opencode",
@@ -153,6 +161,13 @@ export function detectPlatform(clientInfo) {
             reason: "~/.openclaw/ directory exists",
         };
     }
+    if (existsSync(resolve(home, ".config", "kilo"))) {
+        return {
+            platform: "kilo",
+            confidence: "medium",
+            reason: "~/.config/kilo/ directory exists",
+        };
+    }
     if (existsSync(resolve(home, ".config", "opencode"))) {
         return {
             platform: "opencode",
@@ -189,9 +204,10 @@ export async function getAdapter(platform) {
             const { GeminiCLIAdapter } = await import("./gemini-cli/index.js");
             return new GeminiCLIAdapter();
         }
+        case "kilo":
         case "opencode": {
             const { OpenCodeAdapter } = await import("./opencode/index.js");
-            return new OpenCodeAdapter();
+            return new OpenCodeAdapter(target);
         }
         case "openclaw": {
             const { OpenClawAdapter } = await import("./openclaw/index.js");

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

@@ -15,12 +15,15 @@
  *   - Config: opencode.json plugin array, .opencode/plugins/*.ts
  *   - Session dir: ~/.config/opencode/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, RoutingInstructionsConfig, PlatformId } from "../types.js";
+export type AdapterPlatformType = Extract<PlatformId, "opencode" | "kilo">;
 export declare class OpenCodeAdapter implements HookAdapter {
-    readonly name = "OpenCode";
+    get name(): string;
     readonly paradigm: HookParadigm;
     private settingsPath?;
     readonly capabilities: PlatformCapabilities;
+    private platform;
+    constructor(platform?: AdapterPlatformType);
     parsePreToolUseInput(raw: unknown): PreToolUseEvent;
     parsePostToolUseInput(raw: unknown): PostToolUseEvent;
     parsePreCompactInput(raw: unknown): PreCompactEvent;

package/build/adapters/opencode/index.js

@@ -23,11 +23,10 @@ import { homedir } from "node:os";
 // Hook constants (re-exported from hooks.ts)
 // ─────────────────────────────────────────────────────────
 import { HOOK_TYPES as OPENCODE_HOOK_NAMES } from "./hooks.js";
-// ─────────────────────────────────────────────────────────
-// Adapter implementation
-// ─────────────────────────────────────────────────────────
 export class OpenCodeAdapter {
-    name = "OpenCode";
+    get name() {
+        return this.platform === "kilo" ? "KiloCode" : "OpenCode";
+    }
     paradigm = "ts-plugin";
     settingsPath;
     capabilities = {
@@ -39,6 +38,10 @@ export class OpenCodeAdapter {
         canModifyOutput: true, // with TUI bug caveat for bash (#13575)
         canInjectSessionContext: false,
     };
+    platform;
+    constructor(platform = "opencode") {
+        this.platform = platform;
+    }
     // ── Input parsing ──────────────────────────────────────
     parsePreToolUseInput(raw) {
         const input = raw;
@@ -134,9 +137,17 @@ export class OpenCodeAdapter {
     }
     // ── Configuration ──────────────────────────────────────
     getSettingsPath() {
-        return this.settingsPath ?? resolve("opencode.json");
+        // OpenCode uses opencode.json in the project root or .opencode/opencode.json
+        return this.settingsPath ?? resolve(`${this.platform}.json`);
     }
     paths() {
+        if (this.platform === "kilo") {
+            return [
+                resolve("kilo.json"),
+                resolve(".kilocode", "kilo.json"),
+                join(homedir(), ".config", "kilo", "kilo.json"),
+            ];
+        }
         return [
             resolve("opencode.json"),
             resolve(".opencode", "opencode.json"),
@@ -144,7 +155,7 @@ export class OpenCodeAdapter {
         ];
     }
     getSessionDir() {
-        const dir = join(homedir(), ".config", "opencode", "context-mode", "sessions");
+        const dir = join(homedir(), ".config", this.platform, "context-mode", "sessions");
         mkdirSync(dir, { recursive: true });
         return dir;
     }
@@ -203,6 +214,9 @@ export class OpenCodeAdapter {
         };
     }
     readSettings() {
+        // Try project-local paths first, then global config
+        // const paths = this.getConfigFilePaths();
+        // for (const configPath of paths) {
         this.settingsPath = undefined;
         for (const configPath of this.paths()) {
             try {
@@ -217,6 +231,7 @@ export class OpenCodeAdapter {
         return null;
     }
     writeSettings(settings) {
+        // Write to opencode.json/kilo.json in current directory
         writeFileSync(this.getSettingsPath(), JSON.stringify(settings, null, 2) + "\n", "utf-8");
     }
     // ── Diagnostics (doctor) ─────────────────────────────────
@@ -293,7 +308,7 @@ export class OpenCodeAdapter {
     getInstalledVersion() {
         // Check ~/.cache/opencode/node_modules/ for context-mode
         try {
-            const pkgPath = resolve(homedir(), ".cache", "opencode", "node_modules", "context-mode", "package.json");
+            const pkgPath = resolve(homedir(), ".cache", this.platform, "node_modules", "context-mode", "package.json");
             const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
             if (typeof pkg.version === "string")
                 return pkg.version;
@@ -347,14 +362,14 @@ export class OpenCodeAdapter {
     getRoutingInstructionsConfig() {
         return {
             fileName: "AGENTS.md",
-            globalPath: resolve(homedir(), ".config", "opencode", "AGENTS.md"),
+            globalPath: resolve(homedir(), ".config", this.platform, "AGENTS.md"),
             projectRelativePath: "AGENTS.md",
         };
     }
     writeRoutingInstructions(projectDir, pluginRoot) {
         const config = this.getRoutingInstructionsConfig();
         const targetPath = resolve(projectDir, config.projectRelativePath);
-        const sourcePath = resolve(pluginRoot, "configs", "opencode", config.fileName);
+        const sourcePath = resolve(pluginRoot, "configs", this.platform, config.fileName);
         try {
             const content = readFileSync(sourcePath, "utf-8");
             try {

package/build/adapters/types.d.ts

@@ -206,7 +206,7 @@ export interface DiagnosticResult {
     fix?: string;
 }
 /** Supported platform identifiers. */
-export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "openclaw" | "codex" | "vscode-copilot" | "cursor" | "antigravity" | "kiro" | "pi" | "zed" | "unknown";
+export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "cursor" | "antigravity" | "kiro" | "pi" | "zed" | "unknown";
 /** Detection signal used to identify which platform is running. */
 export interface DetectionSignal {
     /** Platform identifier. */

package/build/cli.js

@@ -13,8 +13,8 @@
  */
 import * as p from "@clack/prompts";
 import color from "picocolors";
-import { execSync } from "node:child_process";
-import { readFileSync, writeFileSync, cpSync, accessSync, existsSync, readdirSync, rmSync, closeSync, openSync, constants } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, cpSync, accessSync, existsSync, rmSync, closeSync, openSync, chmodSync, constants } from "node:fs";
 import { request as httpsRequest } from "node:https";
 import { resolve, dirname, join } from "node:path";
 import { tmpdir, devNull } from "node:os";
@@ -351,7 +351,7 @@ async function upgrade() {
     const tmpDir = join(tmpdir(), `context-mode-upgrade-${Date.now()}`);
     s.start("Cloning mksglu/context-mode");
     try {
-        execSync(`git clone --depth 1 https://github.com/mksglu/context-mode.git "${tmpDir}"`, { stdio: "pipe", timeout: 30000 });
+        execFileSync("git", ["clone", "--depth", "1", "https://github.com/mksglu/context-mode.git", tmpDir], { stdio: "pipe", timeout: 30000 });
         s.stop("Downloaded");
         const srcDir = tmpDir;
         const newPkg = JSON.parse(readFileSync(resolve(srcDir, "package.json"), "utf-8"));
@@ -364,12 +364,12 @@ async function upgrade() {
         }
         // Step 2: Install dependencies + build
         s.start("Installing dependencies & building");
-        execSync("npm install --no-audit --no-fund", {
+        execFileSync("npm", ["install", "--no-audit", "--no-fund"], {
             cwd: srcDir,
             stdio: "pipe",
             timeout: 120000,
         });
-        execSync("npm run build", {
+        execFileSync("npm", ["run", "build"], {
             cwd: srcDir,
             stdio: "pipe",
             timeout: 60000,
@@ -377,24 +377,8 @@ async function upgrade() {
         s.stop("Built successfully");
         // Step 3: Update in-place
         s.start("Updating files in-place");
-        const cacheParentMatch = pluginRoot.match(/^(.*[\\/]plugins[\\/]cache[\\/][^\\/]+[\\/][^\\/]+[\\/])/);
-        if (cacheParentMatch) {
-            const cacheParent = cacheParentMatch[1];
-            const myDir = pluginRoot.replace(cacheParent, "").replace(/[\\/]/g, "");
-            try {
-                const oldDirs = readdirSync(cacheParent).filter(d => d !== myDir);
-                for (const d of oldDirs) {
-                    try {
-                        rmSync(resolve(cacheParent, d), { recursive: true, force: true });
-                    }
-                    catch { /* skip */ }
-                }
-                if (oldDirs.length > 0) {
-                    p.log.info(color.dim(`  Cleaned ${oldDirs.length} stale cache dir(s)`));
-                }
-            }
-            catch { /* parent may not exist */ }
-        }
+        // Old version dirs are cleaned lazily by sessionstart.mjs (age-gated >1h)
+        // to avoid breaking active sessions that still reference them (#181).
         const items = [
             "build", "src", "hooks", "skills", "scripts", ".claude-plugin",
             "start.mjs", "server.bundle.mjs", "cli.bundle.mjs", "package.json",
@@ -422,7 +406,7 @@ async function upgrade() {
         p.log.info(color.dim("  Registry synced to " + pluginRoot));
         // Install production deps
         s.start("Installing production dependencies");
-        execSync("npm install --production --no-audit --no-fund", {
+        execFileSync("npm", ["install", "--production", "--no-audit", "--no-fund"], {
             cwd: pluginRoot,
             stdio: "pipe",
             timeout: 60000,
@@ -431,7 +415,7 @@ async function upgrade() {
         // Rebuild native addons for current Node.js ABI (fixes #131)
         s.start("Rebuilding native addons");
         try {
-            execSync("npm rebuild better-sqlite3", {
+            execFileSync("npm", ["rebuild", "better-sqlite3"], {
                 cwd: pluginRoot,
                 stdio: "pipe",
                 timeout: 60000,
@@ -449,7 +433,7 @@ async function upgrade() {
         // Update global npm
         s.start("Updating npm global package");
         try {
-            execSync(`npm install -g "${pluginRoot}" --no-audit --no-fund`, {
+            execFileSync("npm", ["install", "-g", pluginRoot, "--no-audit", "--no-fund"], {
                 stdio: "pipe",
                 timeout: 30000,
             });
@@ -507,7 +491,7 @@ async function upgrade() {
             const binPath = resolve(pluginRoot, bin);
             try {
                 accessSync(binPath, constants.F_OK);
-                execSync(`chmod +x "${binPath}"`, { stdio: "ignore" });
+                chmodSync(binPath, 0o755);
                 permSet.push(binPath);
             }
             catch { /* not found — skip */ }
@@ -535,7 +519,7 @@ async function upgrade() {
         const cliBundlePath = resolve(pluginRoot, "cli.bundle.mjs");
         const cliBuildPath = resolve(pluginRoot, "build", "cli.js");
         const cliPath = existsSync(cliBundlePath) ? cliBundlePath : cliBuildPath;
-        execSync(`node "${cliPath}" doctor`, {
+        execFileSync("node", [cliPath, "doctor"], {
             stdio: "inherit",
             timeout: 30000,
             cwd: pluginRoot,