context-mode 1.0.135 → 1.0.136

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/.codex-plugin/hooks.json

@@ -0,0 +1,65 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "local_shell|shell|shell_command|exec_command|Bash|Shell|apply_patch|Edit|Write|grep_files|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex/pretooluse.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex/posttooluse.mjs\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex/sessionstart.mjs\""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex/precompact.mjs\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex/userpromptsubmit.mjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/codex/stop.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/.codex-plugin/mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "context-mode": {
+      "command": "node",
+      "args": ["./start.mjs"],
+      "cwd": "."
+    }
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "context-mode",
+  "version": "1.0.136",
+  "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",
+    "url": "https://github.com/mksglu"
+  },
+  "homepage": "https://github.com/mksglu/context-mode#readme",
+  "repository": "https://github.com/mksglu/context-mode",
+  "license": "Elastic-2.0",
+  "keywords": [
+    "mcp",
+    "context-window",
+    "sandbox",
+    "code-execution",
+    "fts5",
+    "bm25",
+    "playwright",
+    "context7"
+  ],
+  "mcpServers": "./.codex-plugin/mcp.json",
+  "hooks": "./.codex-plugin/hooks.json",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "context-mode",
+    "shortDescription": "98% context window savings via FTS5 + sandboxed execution",
+    "developerName": "Mert Koseoğlu",
+    "category": "Productivity"
+  }
+}

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.135",
+  "version": "1.0.136",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

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

@@ -424,7 +424,10 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
      "mcp": {
        "context-mode": {
          "type": "local",
-         "command": ["context-mode"]
+         "command": ["context-mode"],
+         "environment": {
+           "CONTEXT_MODE_IDLE_TIMEOUT_MS": "900000"
+         }
        }
      },
      "plugin": ["context-mode"]
@@ -474,7 +477,10 @@ Full configs: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
      "mcp": {
        "context-mode": {
          "type": "local",
-         "command": ["context-mode"]
+         "command": ["context-mode"],
+         "environment": {
+           "CONTEXT_MODE_IDLE_TIMEOUT_MS": "900000"
+         }
        }
      },
      "plugin": ["context-mode"]
@@ -545,6 +551,45 @@ Full documentation: [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)
 
 **Install:**
 
+1. Add the context-mode marketplace and install the plugin from Codex's plugin UI:
+
+   ```bash
+   codex plugin marketplace add mksglu/context-mode
+   ```
+
+2. Enable plugin-provided hooks while the Codex feature is still gated:
+
+   ```toml
+   [features]
+   plugin_hooks = true
+   hooks = true
+   ```
+
+   > **Feature flag note:** Current Codex builds expose hooks under `[features].hooks`
+   > (or `codex --enable hooks`). Prefer `[features].hooks`; `[features].codex_hooks`
+   > remains accepted as a legacy alias in current Codex builds. Bundled plugin hooks
+   > additionally require `plugin_hooks` until Codex enables plugin hooks by default.
+
+3. Restart Codex CLI and verify MCP with `ctx stats`.
+
+   `ctx stats` proves the plugin MCP server is installed and reachable; it does
+   not prove hooks are trusted or running.
+
+4. Review and trust the context-mode plugin hooks if Codex prompts for hook
+   approval. Plugin hooks are only active after both feature flags are enabled
+   and Codex has accepted the hook commands.
+
+The Codex plugin manifest provides MCP via `.codex-plugin/mcp.json`, skills via
+`skills/`, and bundled hooks via `.codex-plugin/hooks.json`. No manual
+`[mcp_servers.context-mode]` block or `$CODEX_HOME/hooks.json` is needed when
+`plugin_hooks` is enabled and the plugin hooks are trusted.
+
+> **Node/PATH note:** context-mode still needs `node` visible to the Codex process.
+> The plugin removes manual Codex config, but it does not vendor Node or inherit
+> login-shell PATH fixes automatically.
+
+**Manual fallback for Codex builds without `plugin_hooks`:**
+
 1. Install context-mode globally:
 
    ```bash
@@ -561,11 +606,7 @@ Full documentation: [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)
    command = "context-mode"
    ```
 
-   > **Feature flag note:** Current Codex builds expose hooks under `[features].hooks`
-   > (or `codex --enable hooks`). Prefer `[features].hooks`; `[features].codex_hooks`
-   > remains accepted as a legacy alias in current Codex builds.
-
-3. Add hooks for routing enforcement and session tracking. Create `$CODEX_HOME/hooks.json` (or `~/.codex/hooks.json` when `CODEX_HOME` is unset):
+3. Create `$CODEX_HOME/hooks.json` (or `~/.codex/hooks.json` when `CODEX_HOME` is unset):
 
    ```json
    {
@@ -597,9 +638,9 @@ Full documentation: [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)
 
 5. Restart Codex CLI.
 
-**Verify:** Start a session and type `ctx stats`. Context-mode tools should appear and respond.
+**Verify:** Start a session and type `ctx stats` to verify MCP. To verify hook routing, confirm Codex lists/trusts the context-mode plugin hooks, then run a command that matches the routing rules.
 
-**Routing:** MCP tools work. Hook-based routing is active when `$CODEX_HOME/hooks.json` or `~/.codex/hooks.json` is configured. The `AGENTS.md` file provides routing instructions for model awareness.
+**Routing:** MCP tools work after plugin install. Plugin hook routing is active only when `hooks` and `plugin_hooks` are enabled and Codex trusts the plugin hook commands. Manual hook routing is active when `$CODEX_HOME/hooks.json` or `~/.codex/hooks.json` is configured. The `AGENTS.md` file provides routing instructions for model awareness.
 
 </details>
 
@@ -1157,6 +1198,7 @@ Detailed event data is also indexed into FTS5 for on-demand retrieval via `ctx_s
 **Kiro** — Partial coverage. Native `preToolUse` and `postToolUse` hooks capture tool events and enforce sandbox routing. `agentSpawn` (the Kiro equivalent of SessionStart) is not yet implemented, so session restore after compaction is not available. Requires manually copying `KIRO.md` to your project root. Auto-detected via MCP protocol handshake (`clientInfo.name`).
 
 **Pi Coding Agent** — High coverage. The extension registers all key lifecycle events: `tool_call` (PreToolUse), `tool_result` (PostToolUse), `session_start` (SessionStart), and `session_before_compact` (PreCompact). File edits, git ops, errors, and tasks are fully tracked. Session restore after compaction works via the extension's event hooks.
+Tool call output can be collapsed/expanded with the default Pi's default keybinding (Ctrl+O)
 
 **OMP (Oh My Pi)** — High coverage. The plugin (installed via `omp plugin install context-mode`) registers all key lifecycle events: `tool_call` (PreToolUse), `tool_result` (PostToolUse), `session_start` (SessionStart), and `session_before_compact` (PreCompact). Storage roots cleanly under `~/.omp/context-mode/` so OMP and Pi installs never share state (issue [#473](https://github.com/mksglu/context-mode/issues/473)). Auto-detected via `PI_CODING_AGENT_DIR` env var or presence of `~/.omp/`.
 
@@ -1363,14 +1405,20 @@ That blocks loopback + RFC1918 + ULA in addition to the always-blocked ranges. U
 
 ### Lifecycle environment variables
 
-Two runtime knobs control how MCP server processes self-manage. Defaults are safe — only set these to opt-out of the leak-fix introduced in v1.0.132 ([#565](https://github.com/mksglu/context-mode/issues/565) / [#568](https://github.com/mksglu/context-mode/pull/568)).
+Two runtime knobs control how MCP server processes self-manage. Defaults are conservative after [#592](https://github.com/mksglu/context-mode/issues/592): idle self-shutdown is disabled unless a host config explicitly opts in. OpenCode and KiloCode opt in because they open one MCP child per session/subagent; Claude Code/Codex/editor hosts keep registered tool handles after a clean MCP exit and therefore must not idle-exit by default.
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `CONTEXT_MODE_IDLE_TIMEOUT_MS` | `900000` (15 min) | An MCP child self-exits cleanly after this many milliseconds of stdin/request inactivity. Hosts like OpenCode and KiloCode open one MCP child per session and per subagent — without this, idle children accumulate to 25+ processes / 1.6 GB RSS in long-lived shells. Set to `0` to disable self-shutdown (rarely needed; useful only for daemons that must outlive their parent). |
+| `CONTEXT_MODE_IDLE_TIMEOUT_MS` | `0` (disabled) | When set to a positive integer, an MCP child self-exits cleanly after this many milliseconds of stdin/request inactivity. OpenCode and KiloCode configs set `900000` (15 min) because those hosts can accumulate one MCP child per session/subagent. Leave disabled for hosts that do not auto-respawn after MCP EOF (Claude Code, Codex, editor MCP clients) or ctx_* tools may go stale after idle. |
 | `CONTEXT_MODE_STARTUP_SWEEP` | `1` (enabled) | At boot, a newly-spawned MCP child reaps any other context-mode MCP server pids that share its parent process (`sameParentOnly: true` — never touches MCP children of a different host). This reclaims accumulated siblings immediately instead of waiting for each idle timer to fire. Set to `0` or `false` to disable (useful when you intentionally want multiple concurrent MCP children under the same host, e.g. multi-tenant test runners). |
 
-Both vars are read fresh at MCP server start — no restart of the host CLI is required, just spawn a new MCP child (open a new session) for changes to take effect. Invalid values (non-numeric `CONTEXT_MODE_IDLE_TIMEOUT_MS`, unrecognized `CONTEXT_MODE_STARTUP_SWEEP`) fall back to defaults silently.
+Both vars are read fresh at MCP server start — no restart of the host CLI is required, just spawn a new MCP child (open a new session) for changes to take effect. Invalid/non-numeric `CONTEXT_MODE_IDLE_TIMEOUT_MS` values fall back to `0` (disabled); unrecognized `CONTEXT_MODE_STARTUP_SWEEP` values fall back to enabled.
+
+### Routing-guidance environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY` | `10` | Cadence (in tool calls) at which the PreToolUse hook re-injects the "wrap large external-MCP payloads in `ctx_execute`" guidance. The original implementation ([#529](https://github.com/mksglu/context-mode/pull/529)) fired only once per session, which got lost after context compaction in MCP-heavy sessions (e.g. 50+ Jira/Slack/Notion calls — see [#567](https://github.com/mksglu/context-mode/issues/567) follow-up). The default re-fires every 10th matching call, keeping the guidance in the model's recent window. Range `[1, 100]`; invalid values fall back to `10`. Set to `1` for "every call" (most aggressive — adds ~250 tokens/call) or to a larger value for less frequent reminders. |
 
 ## Contributing
 

package/build/adapters/pi/mcp-bridge.d.ts

@@ -47,6 +47,13 @@ export interface MCPCallResult {
     }>;
     isError?: boolean;
 }
+interface PiRenderTheme {
+    bold(text: string): string;
+    fg(color: string, text: string): string;
+}
+interface PiRenderContext {
+    lastComponent?: unknown;
+}
 /**
  * Minimal stdio JSON-RPC client targeting the context-mode MCP server.
  *
@@ -69,6 +76,15 @@ export declare class MCPStdioClient {
     private buffer;
     private initialized;
     private exited;
+    /**
+     * In-flight respawn promise — set while {@link respawn} runs so
+     * concurrent callers awaiting `request()` after an idle exit observe
+     * the SAME respawn, not N parallel ones. Without this guard, two
+     * simultaneous `callTool` calls would each see `this.exited === true`,
+     * each fire their own `respawn()`, and the loser leaks an orphaned
+     * child process the GC cannot reach (no `.kill()` reference).
+     */
+    private respawnPromise;
     /**
      * Live env passed to the spawned child — exposed (read-only intent)
      * so tests can pin the fork-bomb-prevention env counter (#516)
@@ -90,7 +106,21 @@ export declare class MCPStdioClient {
      * Resets state so a fresh `start()` + `initialize()` cycle runs, then
      * the caller's pending request flows through the new child.
      *
-     * Internal — exposed only via the public `callTool()` happy path.
+     * Single-flight — concurrent callers share one in-flight respawn via
+     * {@link respawnPromise}. Internal — only entered via {@link request}.
+     *
+     * Sequencing pinned (do not reorder without updating the regression
+     * test in tests/adapters/pi-mcp-bridge.test.ts):
+     *   1. `this.child = null`     — drop stale handle
+     *   2. `this.buffer = ""`       — discard leftover bytes from old child
+     *   3. `this.exited = false`    — must precede `start()` + `initialize()`,
+     *                                 because `request("initialize", …)`
+     *                                 inside `initialize()` re-checks this
+     *                                 flag and would otherwise re-enter
+     *                                 respawn in an infinite loop
+     *   4. `this.initialized = false`
+     *   5. `this.start()`
+     *   6. `await this.initialize()` — flows through `request()` recursively
      */
     private respawn;
     shutdown(): void;
@@ -106,6 +136,11 @@ export interface PiToolRegistration {
     label: string;
     description: string;
     parameters: unknown;
+    renderCall?: (args: unknown, theme: PiRenderTheme, context: PiRenderContext) => unknown;
+    renderResult?: (result: MCPCallResult, options: {
+        expanded: boolean;
+        isPartial: boolean;
+    }, theme: PiRenderTheme, context: PiRenderContext) => unknown;
     execute: (toolCallId: string, params: Record<string, unknown>) => Promise<{
         content: Array<{
             type: "text";
@@ -144,3 +179,4 @@ export interface BootstrapOptions {
     _resolveJsRuntime?: () => string | null;
 }
 export declare function bootstrapMCPTools(pi: PiLikeAPI, serverScript: string, options?: BootstrapOptions): Promise<BridgeHandle>;
+export {};

package/build/adapters/pi/mcp-bridge.js

@@ -96,6 +96,87 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 // Tools/call may run shell commands or fetch URLs — wider window than
 // initialize/list, but still bounded so a hung server can't block Pi.
 const DEFAULT_CALL_TIMEOUT_MS = 120_000;
+class PiTextComponent {
+    text;
+    constructor(text = "") {
+        this.text = text;
+    }
+    setText(text) {
+        this.text = text;
+    }
+    invalidate() {
+        // Stateless renderer: no cached layout to invalidate.
+    }
+    render(width) {
+        if (!this.text || this.text.trim() === "")
+            return [];
+        return this.text
+            .replace(/\t/g, "   ")
+            .split(/\r?\n/)
+            .map((line) => truncateAnsiLine(line, Math.max(1, width)));
+    }
+}
+const ANSI_PATTERN = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07]*(?:\x07|\x1b\\)/g;
+function truncateAnsiLine(line, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    let output = "";
+    let visible = 0;
+    let index = 0;
+    ANSI_PATTERN.lastIndex = 0;
+    for (;;) {
+        const match = ANSI_PATTERN.exec(line);
+        const end = match?.index ?? line.length;
+        const chunk = line.slice(index, end);
+        for (const char of chunk) {
+            if (visible >= maxWidth)
+                return output;
+            output += char;
+            visible++;
+        }
+        if (!match)
+            return output;
+        output += match[0];
+        index = ANSI_PATTERN.lastIndex;
+    }
+}
+function createContextModeCallRenderer(toolName) {
+    return (_args, theme, context) => {
+        const text = context.lastComponent instanceof PiTextComponent
+            ? context.lastComponent
+            : new PiTextComponent();
+        text.setText(theme.fg("toolTitle", theme.bold(toolName)));
+        return text;
+    };
+}
+function createContextModeResultRenderer(toolName) {
+    return (result, { expanded, isPartial }, theme, context) => {
+        const text = context.lastComponent instanceof PiTextComponent
+            ? context.lastComponent
+            : new PiTextComponent();
+        if (isPartial) {
+            text.setText(theme.fg("warning", "indexing/searching..."));
+            return text;
+        }
+        const output = (result.content ?? [])
+            .filter((c) => c?.type === "text" && typeof c.text === "string")
+            .map((c) => c.text)
+            .join("\n");
+        if (expanded) {
+            text.setText(theme.fg("toolOutput", output));
+            return text;
+        }
+        const firstLine = output
+            .split(/\r?\n/)
+            .find((line) => line.trim().length > 0)
+            ?.trim();
+        const status = firstLine && firstLine.length <= 180
+            ? firstLine
+            : `${toolName} completed`;
+        text.setText(theme.fg("toolOutput", status));
+        return text;
+    };
+}
 /**
  * Minimal stdio JSON-RPC client targeting the context-mode MCP server.
  *
@@ -118,6 +199,15 @@ export class MCPStdioClient {
     buffer = "";
     initialized = false;
     exited = false;
+    /**
+     * In-flight respawn promise — set while {@link respawn} runs so
+     * concurrent callers awaiting `request()` after an idle exit observe
+     * the SAME respawn, not N parallel ones. Without this guard, two
+     * simultaneous `callTool` calls would each see `this.exited === true`,
+     * each fire their own `respawn()`, and the loser leaks an orphaned
+     * child process the GC cannot reach (no `.kill()` reference).
+     */
+    respawnPromise = null;
     /**
      * Live env passed to the spawned child — exposed (read-only intent)
      * so tests can pin the fork-bomb-prevention env counter (#516)
@@ -232,11 +322,31 @@ export class MCPStdioClient {
                 handler.resolve(msg.result);
         }
     }
-    request(method, params, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    async request(method, params, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+        // Respawn-on-idle-exit (#583, #583-followup).
+        //
+        // Initial #583 fix patched callTool() only. The structural location is
+        // here: `request()` is the single chokepoint for `initialize`,
+        // `tools/list`, `tools/call`, and any future method. Patching at this
+        // layer means listTools / re-initialize paths after an idle exit also
+        // self-heal, not just the registered-tool happy path.
+        //
+        // Sequencing is critical: respawn() resets `exited`, `child`, and
+        // `buffer` BEFORE start() + initialize(). The initialize() call inside
+        // respawn() goes through this same request() — recursion is safe
+        // because by the time we re-enter, `exited` is false again. We use a
+        // single-flight `respawnPromise` so concurrent callers share the same
+        // respawn (orphan-child guard, see field comment).
+        if (this.exited) {
+            if (!this.respawnPromise) {
+                this.respawnPromise = this.respawn().finally(() => {
+                    this.respawnPromise = null;
+                });
+            }
+            await this.respawnPromise;
+        }
         if (!this.child)
             throw new Error("MCP client not started");
-        if (this.exited)
-            return Promise.reject(new Error("MCP server has exited"));
         const id = ++this.requestId;
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -284,20 +394,11 @@ export class MCPStdioClient {
         return Array.isArray(result.tools) ? result.tools : [];
     }
     async callTool(name, args) {
-        // Respawn-on-idle-exit (#583). The MCP server gained an idle
-        // self-shutdown in 1.0.132 (#565/#568, src/lifecycle.ts). When the
-        // Pi-spawned child exits cleanly after the idle window, Pi keeps the
-        // tool handles registered, but the bridge client is `exited=true`
-        // and every subsequent request would reject with
-        // "MCP server has exited" — leaving Pi's ctx_* tools permanently
-        // broken until the user restarts Pi.
-        //
-        // The structural fix is here, not in lifecycle.ts: the bridge owns
-        // the child lifecycle, so it transparently respawns + re-initialises
-        // the server on the next call. Restores parity with adapters whose
-        // host MCP client respawns on EOF (Claude Code, Codex, etc.).
-        if (this.exited)
-            await this.respawn();
+        // Respawn-on-idle-exit is now handled centrally in `request()`
+        // (#583 follow-up). Originally patched here in #583 — moving it up
+        // one layer covers `listTools` / `initialize` paths too, with a
+        // single-flight guard against orphan child processes from
+        // concurrent callers.
         return this.request("tools/call", { name, arguments: args ?? {} }, DEFAULT_CALL_TIMEOUT_MS);
     }
     /**
@@ -305,12 +406,23 @@ export class MCPStdioClient {
      * Resets state so a fresh `start()` + `initialize()` cycle runs, then
      * the caller's pending request flows through the new child.
      *
-     * Internal — exposed only via the public `callTool()` happy path.
+     * Single-flight — concurrent callers share one in-flight respawn via
+     * {@link respawnPromise}. Internal — only entered via {@link request}.
+     *
+     * Sequencing pinned (do not reorder without updating the regression
+     * test in tests/adapters/pi-mcp-bridge.test.ts):
+     *   1. `this.child = null`     — drop stale handle
+     *   2. `this.buffer = ""`       — discard leftover bytes from old child
+     *   3. `this.exited = false`    — must precede `start()` + `initialize()`,
+     *                                 because `request("initialize", …)`
+     *                                 inside `initialize()` re-checks this
+     *                                 flag and would otherwise re-enter
+     *                                 respawn in an infinite loop
+     *   4. `this.initialized = false`
+     *   5. `this.start()`
+     *   6. `await this.initialize()` — flows through `request()` recursively
      */
     async respawn() {
-        // Drop the dead child handle and clear stream buffer so leftover
-        // bytes from the previous incarnation don't get parsed as JSON-RPC
-        // for the new one. Pending map is already cleared by onExit().
         this.child = null;
         this.buffer = "";
         this.exited = false;
@@ -398,6 +510,8 @@ export async function bootstrapMCPTools(pi, serverScript, options = {}) {
             // for type inference). Empty-object fallback keeps tools that
             // declare no parameters callable.
             parameters: tool.inputSchema ?? { type: "object", properties: {} },
+            renderCall: createContextModeCallRenderer(tool.name),
+            renderResult: createContextModeResultRenderer(tool.name),
             async execute(_toolCallId, params) {
                 const result = await client.callTool(tool.name, params ?? {});
                 const text = (result.content ?? [])

package/build/lifecycle.d.ts

@@ -23,7 +23,7 @@ export interface LifecycleGuardOptions {
     /**
      * Idle shutdown threshold in ms (#565). When the server has handled no
      * MCP activity for this long, `onShutdown` fires. `0` disables.
-     * Default: env `CONTEXT_MODE_IDLE_TIMEOUT_MS`, else 15 minutes.
+     * Default: env `CONTEXT_MODE_IDLE_TIMEOUT_MS`, else 0 (disabled).
      * Skipped on TTY stdin (interactive dev / OpenCode ts-plugin standalone).
      *
      * Pair with the returned `recordActivity()` callback — call it on every
@@ -50,20 +50,20 @@ export interface LifecycleGuardHandle {
 /**
  * Resolve the idle-shutdown threshold (#565).
  *
- * OpenCode + KiloCode open a fresh MCP client per session AND per subagent
- * task, but never tear them down for the host's lifetime. A host alive for
- * a working day accumulates one stdio child per session — observed live at
- * 26 children / 1.6 GB RSS under a single `opencode serve` parent.
+ * Idle shutdown is OFF by default (#592) because most hosts (Claude
+ * Code, Codex, editor MCP clients) keep registered tool handles after a
+ * clean MCP child exit and do NOT transparently respawn on the next call.
+ * The global 15 min default introduced in #568 solved OpenCode's child
+ * accumulation, but stranded ctx_* tools in Claude Code/Codex-style
+ * hosts once the MCP server exited cleanly while the editor stayed alive.
  *
- * None of the existing exit paths (ppid poll, grandparent reparent, stdin
- * EOF, SIGTERM) fire while the host stays alive. Idle shutdown is the
- * structural fix: a server with no work to do should release its memory.
+ * Hosts that are known to benefit from idle shutdown MUST opt in via
+ * CONTEXT_MODE_IDLE_TIMEOUT_MS in their MCP config. Today that is
+ * OpenCode/KiloCode (their configs set 900000 = 15 min). Users and test
+ * harnesses can also opt in explicitly with any positive integer.
  *
- * Default 15 min strikes a balance — long enough that a paused
- * conversation does not pay a cold-start on every resume, short enough
- * that 8 hours of unused sessions do not pin GB of RAM.
- *
- * Set env to `0` to disable entirely.
+ * Missing or malformed env = 0 (disabled, safe default). Set env to
+ * `0` to disable explicitly.
  *
  * Exported for unit-testing.
  */

package/build/lifecycle.js

@@ -17,30 +17,30 @@ import { execFileSync } from "node:child_process";
 /**
  * Resolve the idle-shutdown threshold (#565).
  *
- * OpenCode + KiloCode open a fresh MCP client per session AND per subagent
- * task, but never tear them down for the host's lifetime. A host alive for
- * a working day accumulates one stdio child per session — observed live at
- * 26 children / 1.6 GB RSS under a single `opencode serve` parent.
+ * Idle shutdown is OFF by default (#592) because most hosts (Claude
+ * Code, Codex, editor MCP clients) keep registered tool handles after a
+ * clean MCP child exit and do NOT transparently respawn on the next call.
+ * The global 15 min default introduced in #568 solved OpenCode's child
+ * accumulation, but stranded ctx_* tools in Claude Code/Codex-style
+ * hosts once the MCP server exited cleanly while the editor stayed alive.
  *
- * None of the existing exit paths (ppid poll, grandparent reparent, stdin
- * EOF, SIGTERM) fire while the host stays alive. Idle shutdown is the
- * structural fix: a server with no work to do should release its memory.
+ * Hosts that are known to benefit from idle shutdown MUST opt in via
+ * CONTEXT_MODE_IDLE_TIMEOUT_MS in their MCP config. Today that is
+ * OpenCode/KiloCode (their configs set 900000 = 15 min). Users and test
+ * harnesses can also opt in explicitly with any positive integer.
  *
- * Default 15 min strikes a balance — long enough that a paused
- * conversation does not pay a cold-start on every resume, short enough
- * that 8 hours of unused sessions do not pin GB of RAM.
- *
- * Set env to `0` to disable entirely.
+ * Missing or malformed env = 0 (disabled, safe default). Set env to
+ * `0` to disable explicitly.
  *
  * Exported for unit-testing.
  */
 export function idleTimeoutForEnv(env = process.env) {
     const raw = env.CONTEXT_MODE_IDLE_TIMEOUT_MS;
     if (raw === undefined)
-        return 15 * 60 * 1000;
+        return 0;
     const n = Number.parseInt(raw, 10);
     if (!Number.isFinite(n) || n < 0)
-        return 15 * 60 * 1000;
+        return 0;
     return n;
 }
 /** Read grandparent PID via `ps -o ppid= -p $PPID`. Returns NaN on failure or Windows. */