context-mode 1.0.134 → 1.0.136

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.134",
+  "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.134",
+  "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.134",
+  "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/detect.d.ts

@@ -11,7 +11,9 @@
  *                     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/
+ *   - OpenCode:       OPENCODE_PROJECT_DIR, OPENCODE_CLIENT,
+ *                     OPENCODE_TERMINAL, OPENCODE, OPENCODE_PID |
+ *                     ~/.config/opencode/
  *   - OpenClaw:       OPENCLAW_HOME, OPENCLAW_CLI | ~/.openclaw/
  *   - Codex CLI:      CODEX_CI, CODEX_THREAD_ID | ~/.codex/
  *   - Cursor:         CURSOR_TRACE_ID (MCP), CURSOR_CLI (terminal) | ~/.cursor/

package/build/adapters/detect.js

@@ -11,7 +11,9 @@
  *                     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/
+ *   - OpenCode:       OPENCODE_PROJECT_DIR, OPENCODE_CLIENT,
+ *                     OPENCODE_TERMINAL, OPENCODE, OPENCODE_PID |
+ *                     ~/.config/opencode/
  *   - OpenClaw:       OPENCLAW_HOME, OPENCLAW_CLI | ~/.openclaw/
  *   - Codex CLI:      CODEX_CI, CODEX_THREAD_ID | ~/.codex/
  *   - Cursor:         CURSOR_TRACE_ID (MCP), CURSOR_CLI (terminal) | ~/.cursor/
@@ -109,12 +111,15 @@ const _PLATFORM_ENV_VARS_RAW = [
             { name: "KILO_PID", role: "identification" },
         ]],
     // opencode — sst/opencode packages/opencode/src/index.ts:108-109 sets
-    // OPENCODE=1 + OPENCODE_PID=<pid> on every CLI invocation.
+    // OPENCODE=1 + OPENCODE_PID=<pid> on CLI invocations. OpenCode desktop
+    // shells also expose OPENCODE_CLIENT=desktop and OPENCODE_TERMINAL=1.
     // OPENCODE_PROJECT_DIR is the documented workspace var (consumed by the
     // legacy resolver cascade) — listed first so the workspace cascade picks
     // it up under strict mode.
     ["opencode", [
             { name: "OPENCODE_PROJECT_DIR", role: "workspace" },
+            { name: "OPENCODE_CLIENT", role: "identification" },
+            { name: "OPENCODE_TERMINAL", role: "identification" },
             { name: "OPENCODE", role: "identification" },
             { name: "OPENCODE_PID", role: "identification" },
         ]],

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)
@@ -85,6 +101,28 @@ export declare class MCPStdioClient {
     initialize(): Promise<void>;
     listTools(): Promise<MCPTool[]>;
     callTool(name: string, args: unknown): Promise<MCPCallResult>;
+    /**
+     * Respawn the MCP child after an exit (clean idle shutdown or crash).
+     * Resets state so a fresh `start()` + `initialize()` cycle runs, then
+     * the caller's pending request flows through the new child.
+     *
+     * 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;
 }
 /**
@@ -98,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";
@@ -136,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,8 +394,42 @@ export class MCPStdioClient {
         return Array.isArray(result.tools) ? result.tools : [];
     }
     async callTool(name, args) {
+        // 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);
     }
+    /**
+     * Respawn the MCP child after an exit (clean idle shutdown or crash).
+     * Resets state so a fresh `start()` + `initialize()` cycle runs, then
+     * the caller's pending request flows through the new child.
+     *
+     * 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() {
+        this.child = null;
+        this.buffer = "";
+        this.exited = false;
+        this.initialized = false;
+        this.start();
+        await this.initialize();
+    }
     shutdown() {
         if (!this.child)
             return;
@@ -366,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/cli.js

@@ -933,6 +933,22 @@ async function upgrade(opts) {
                 const message = err instanceof Error ? err.message : String(err);
                 throw new Error(`.mcp.json drift check failed: ${message}`);
             }
+            // v1.0.X — Layer 7 heal: update user-level ~/.claude.json MCP server
+            // registrations that point to old context-mode version dirs.
+            // (anthropics/claude-code#59310 workaround — see heal-installed-plugins.mjs)
+            try {
+                // @ts-expect-error — JS module, no TS declarations
+                const { healClaudeJsonMcpArgs } = await import("../scripts/heal-installed-plugins.mjs");
+                const dotClaudeJson = resolve(homedir(), ".claude.json");
+                const pluginCacheParent = resolve(resolveClaudeConfigDir(), "plugins", "cache", "context-mode", "context-mode");
+                const result = healClaudeJsonMcpArgs({ dotClaudeJsonPath: dotClaudeJson, pluginCacheParent, newPluginRoot: pluginRoot });
+                if (result.healed && result.healed.length > 0) {
+                    p.log.info(color.dim("  ~/.claude.json user MCP registrations updated → " + newVersion));
+                }
+            }
+            catch {
+                /* best effort — never block upgrade */
+            }
             // v1.0.114 hotfix — marketplace post-pull assertion: clone (if
             // present) MUST be on newVersion. Mert's case showed marketplace
             // stuck at v1.0.89 — the sync block above swallowed that silently.
@@ -1151,6 +1167,7 @@ async function upgrade(opts) {
             stdio: "inherit",
             timeout: 30000,
             cwd: pluginRoot,
+            env: { ...process.env, CONTEXT_MODE_PLATFORM: detection.platform },
         });
     }
     catch {