context-mode 1.0.151 → 1.0.152

package/build/adapters/openclaw/plugin.js

@@ -50,6 +50,14 @@ const SYSTEM_REMINDER_PREFIXES = [
     "<context_guidance>",
     "<tool-result>",
 ];
+const SKILL_FRONTMATTER_REGEX = /^---\s*\n[\s\S]*?\n---\s*\n?/;
+const OPENCLAW_SKILL_PROMPT_CHAR_LIMIT = 6000;
+const SKILL_SECTION_HEADINGS = [
+    "MANDATORY RULE",
+    "Decision Tree",
+    "When to Use Each Tool",
+    "Critical Rules",
+];
 function isSystemReminderMessage(msg) {
     const trimmed = msg.trimStart();
     for (const prefix of SYSTEM_REMINDER_PREFIXES) {
@@ -58,6 +66,40 @@ function isSystemReminderMessage(msg) {
     }
     return false;
 }
+function stripMarkdownFrontmatter(markdown) {
+    const normalized = markdown.replace(/\r\n/g, "\n");
+    return normalized.replace(SKILL_FRONTMATTER_REGEX, "").trim();
+}
+function extractMarkdownSection(markdown, heading) {
+    const sectionHeader = `## ${heading}`;
+    const start = markdown.indexOf(sectionHeader);
+    if (start === -1)
+        return null;
+    const afterHeader = markdown.slice(start + sectionHeader.length);
+    const nextHeadingOffset = afterHeader.search(/\n##\s+|\n#\s+/);
+    const body = (nextHeadingOffset === -1 ? afterHeader : afterHeader.slice(0, nextHeadingOffset)).trim();
+    if (!body)
+        return null;
+    return `${sectionHeader}\n\n${body}`;
+}
+function buildOpenClawSkillLikeGuidance(skillMarkdown) {
+    const skillBody = stripMarkdownFrontmatter(skillMarkdown);
+    const skillTitle = skillBody.match(/^#\s+.+$/m)?.[0]?.trim() ?? "# Context Mode Skill";
+    const selectedSections = SKILL_SECTION_HEADINGS
+        .map((heading) => extractMarkdownSection(skillBody, heading))
+        .filter((section) => Boolean(section));
+    const rawContent = (selectedSections.length > 0
+        ? [skillTitle, ...selectedSections].join("\n\n")
+        : skillBody).trim();
+    const boundedContent = rawContent.length > OPENCLAW_SKILL_PROMPT_CHAR_LIMIT
+        ? `${rawContent.slice(0, OPENCLAW_SKILL_PROMPT_CHAR_LIMIT).trimEnd()}\n\n[skill excerpt truncated for prompt budget]`
+        : rawContent;
+    return [
+        "<context_mode_skill_like_guidance source=\"skills/context-mode/SKILL.md\">",
+        boundedContent,
+        "</context_mode_skill_like_guidance>",
+    ].join("\n");
+}
 /** Plugin config schema for OpenClaw validation. */
 const configSchema = {
     type: "object",
@@ -154,11 +196,34 @@ export default {
         // info/error always emit; debug only when api.logger.debug is present
         // (i.e. OpenClaw running with --log-level debug or lower).
         const log = {
-            info: (...args) => api.logger?.info("[context-mode]", ...args),
-            error: (...args) => api.logger?.error("[context-mode]", ...args),
+            info: (...args) => api.logger?.info?.("[context-mode]", ...args),
+            error: (...args) => api.logger?.error?.("[context-mode]", ...args),
             debug: (...args) => api.logger?.debug?.("[context-mode]", ...args),
             warn: (...args) => api.logger?.warn?.("[context-mode]", ...args),
         };
+        const registerCommandHook = (event, handler, meta) => {
+            if (api.registerHook) {
+                api.registerHook(event, handler, meta);
+                return;
+            }
+            try {
+                api.on(event, handler);
+                log.debug("command hook registered via api.on fallback", { event });
+            }
+            catch (err) {
+                log.warn?.("command hook registration skipped", { event }, err);
+            }
+        };
+        const registerAutoReplyCommand = (command) => {
+            if (!api.registerCommand)
+                return;
+            try {
+                api.registerCommand(command);
+            }
+            catch (err) {
+                log.warn?.("registerCommand failed; skipping auto-reply command", { name: command.name }, err);
+            }
+        };
         // Get shared DB singleton (lazy-init on first register() call)
         const db = getOrCreateDB(projectDir);
         // Start with temp UUID — session_start will assign the real ID + sessionKey
@@ -180,6 +245,7 @@ export default {
         // with createRoutingBlock(createToolNamer("openclaw")) so OpenClaw-specific
         // MCP-prefix substitution stays in lockstep with hooks/routing-block.mjs.
         let routingInstructions = "";
+        let skillLikeInstructions = "";
         const initPromise = (async () => {
             const routingPath = resolve(buildDir, "..", "..", "..", "hooks", "core", "routing.mjs");
             const routing = await import(pathToFileURL(routingPath).href);
@@ -207,6 +273,18 @@ export default {
                     // best effort
                 }
             }
+            try {
+                const skillPath = resolve(pluginRoot, "skills", "context-mode", "SKILL.md");
+                if (existsSync(skillPath)) {
+                    skillLikeInstructions = buildOpenClawSkillLikeGuidance(readFileSync(skillPath, "utf-8"));
+                }
+                else {
+                    log.debug("context-mode skill file missing; skipping skill-like prompt injection", { skillPath });
+                }
+            }
+            catch (err) {
+                log.warn?.("failed to build skill-like guidance from SKILL.md", err);
+            }
             return { routing };
         })();
         // ── 1. tool_call:before — Routing enforcement ──────────
@@ -307,7 +385,7 @@ export default {
             }
         });
         // ── 3. command:new — Session initialization ────────────
-        api.registerHook("command:new", async () => {
+        registerCommandHook("command:new", async () => {
             try {
                 log.debug("command:new", { sessionId: sessionId.slice(0, 8) });
                 db.cleanupOldSessions(7);
@@ -320,7 +398,7 @@ export default {
             description: "Session initialization — cleans up old sessions on /new command",
         });
         // ── 3b. command:reset / command:stop — Session cleanup ────
-        api.registerHook("command:reset", async () => {
+        registerCommandHook("command:reset", async () => {
             try {
                 log.debug("command:reset", { sessionId: sessionId.slice(0, 8) });
                 db.cleanupOldSessions(7);
@@ -332,7 +410,7 @@ export default {
             name: "context-mode.session-reset",
             description: "Session cleanup on /reset command",
         });
-        api.registerHook("command:stop", async () => {
+        registerCommandHook("command:stop", async () => {
             try {
                 log.debug("command:stop", { sessionId: sessionId.slice(0, 8), sessionKey });
                 if (sessionKey) {
@@ -472,14 +550,23 @@ export default {
         // call-time, so the first prompt-build firing after dynamic-import resolution
         // sees the dynamic ROUTING_BLOCK XML (matching hooks/routing-block.mjs).
         api.on("before_prompt_build", () => {
-            if (!routingInstructions)
+            if (!routingInstructions && !skillLikeInstructions)
                 return undefined;
-            log.debug("before_prompt_build[routing]", { hasInstructions: !!routingInstructions });
-            // v1.0.107 — visible marker so OpenClaw users can verify the routing
-            // block reached the model (Mickey-class verification path; mirrors
-            // OpenCode + Pi adapters).
-            const marker = `<!-- context-mode: routing block injected (sessionID=${String(sessionId).slice(0, 8)}) -->`;
-            return { appendSystemContext: marker + "\n" + routingInstructions };
+            log.debug("before_prompt_build[routing+skill]", {
+                hasRoutingInstructions: !!routingInstructions,
+                hasSkillLikeInstructions: !!skillLikeInstructions,
+            });
+            const injectedBlocks = [];
+            if (routingInstructions) {
+                // v1.0.107 — visible marker so OpenClaw users can verify the routing
+                // block reached the model (Mickey-class verification path; mirrors
+                // OpenCode + Pi adapters).
+                const marker = `<!-- context-mode: routing block injected (sessionID=${String(sessionId).slice(0, 8)}) -->`;
+                injectedBlocks.push(marker + "\n" + routingInstructions);
+            }
+            if (skillLikeInstructions)
+                injectedBlocks.push(skillLikeInstructions);
+            return { appendSystemContext: injectedBlocks.join("\n\n") };
         }, { priority: 5 });
         // ── 8b. registerTool — Expose 11 ctx_* tools (SLICE OClaw-1) ────
         // Phase 7 audit (v1.0.107-adapter-openclaw.json) flagged severity=CRITICAL:
@@ -531,14 +618,22 @@ export default {
             try {
                 const e = (event ?? {});
                 const basePrompt = e?.input?.prompt ?? "";
-                if (!routingInstructions)
+                if (!routingInstructions && !skillLikeInstructions)
                     return undefined;
+                const injectedBlocks = [];
+                if (routingInstructions)
+                    injectedBlocks.push(routingInstructions);
+                if (skillLikeInstructions)
+                    injectedBlocks.push(skillLikeInstructions);
+                const injectedPromptBlock = injectedBlocks.join("\n\n");
                 const newPrompt = basePrompt
-                    ? `${basePrompt}\n\n${routingInstructions}`
-                    : routingInstructions;
-                log.debug("subagent_spawning[inject-routing]", {
+                    ? `${basePrompt}\n\n${injectedPromptBlock}`
+                    : injectedPromptBlock;
+                log.debug("subagent_spawning[inject-routing+skill]", {
                     basePromptLen: basePrompt.length,
-                    blockLen: routingInstructions.length,
+                    hasRoutingInstructions: !!routingInstructions,
+                    hasSkillLikeInstructions: !!skillLikeInstructions,
+                    blockLen: injectedPromptBlock.length,
                 });
                 return { inputOverride: { ...(e.input ?? {}), prompt: newPrompt } };
             }
@@ -547,26 +642,31 @@ export default {
             }
         });
         // ── 9. Context engine — Compaction management ──────────
-        api.registerContextEngine("context-mode", () => ({
-            info: {
-                id: "context-mode",
-                name: "Context Mode",
-                ownsCompaction: false,
-            },
-            async ingest() {
-                return { ingested: true };
-            },
-            async assemble({ messages }) {
-                return { messages, estimatedTokens: 0 };
-            },
-            async compact() {
-                // No-op: session continuity is handled by before_compaction / after_compaction hooks.
-                // Returning ownsCompaction: false + compacted: false lets the host platform (OpenClaw)
-                // manage conversation truncation, preserving Anthropic thinking/redacted_thinking blocks.
-                // See: https://github.com/mksglu/context-mode/issues/191
-                return { ok: true, compacted: false };
-            },
-        }));
+        if (api.registerContextEngine) {
+            api.registerContextEngine("context-mode", () => ({
+                info: {
+                    id: "context-mode",
+                    name: "Context Mode",
+                    ownsCompaction: false,
+                },
+                async ingest() {
+                    return { ingested: true };
+                },
+                async assemble({ messages }) {
+                    return { messages, estimatedTokens: 0 };
+                },
+                async compact() {
+                    // No-op: session continuity is handled by before_compaction / after_compaction hooks.
+                    // Returning ownsCompaction: false + compacted: false lets the host platform (OpenClaw)
+                    // manage conversation truncation, preserving Anthropic thinking/redacted_thinking blocks.
+                    // See: https://github.com/mksglu/context-mode/issues/191
+                    return { ok: true, compacted: false };
+                },
+            }));
+        }
+        else {
+            log.warn?.("api.registerContextEngine unavailable — skipping context engine registration");
+        }
         // ── 10. Auto-reply commands — ctx slash commands ──────
         // Update module-level refs so command handlers (registered once) always
         // read the latest session's db/sessionId/pluginRoot.
@@ -574,7 +674,7 @@ export default {
         _latestSessionId = sessionId;
         _latestPluginRoot = pluginRoot;
         if (api.registerCommand) {
-            api.registerCommand({
+            registerAutoReplyCommand({
                 name: "ctx-stats",
                 description: "Show context-mode session statistics",
                 handler: () => {
@@ -582,7 +682,7 @@ export default {
                     return { text };
                 },
             });
-            api.registerCommand({
+            registerAutoReplyCommand({
                 name: "ctx-doctor",
                 description: "Run context-mode diagnostics",
                 handler: () => {
@@ -603,7 +703,7 @@ export default {
                     };
                 },
             });
-            api.registerCommand({
+            registerAutoReplyCommand({
                 name: "ctx-upgrade",
                 description: "Upgrade context-mode to the latest version",
                 handler: () => {

package/build/adapters/opencode/plugin.js

@@ -246,9 +246,10 @@ async function createContextModePlugin(ctx) {
                 : typeof inputSchema?._def?.shape === "function"
                     ? inputSchema._def.shape()
                     : {};
-            const argsForHost = platform === "kilo"
-                ? zod3ShapeToV4(shape)
-                : shape;
+            // Both KiloCode and recent OpenCode bundle Zod v4 in-host; v3 schemas
+            // crash with `n._zod.def` undefined. Gate widened from kilo-only (#632)
+            // because every consumer of this file is an OpenCode-family host.
+            const argsForHost = zod3ShapeToV4(shape);
             tools[registered.name] = {
                 description: String(config.description ?? ""),
                 args: argsForHost,

package/build/adapters/opencode/zod3tov4.js

@@ -1,13 +1,13 @@
 /**
- * Zod 3 → Zod 4 shape conversion (KiloCode only).
+ * Zod 3 → Zod 4 shape conversion for in-process plugin hosts that bundle Zod v4.
  *
- * KiloCode's runtime bundles Zod v4 internally. When it receives plugin tool
- * definitions whose `args` contain Zod v3 schemas (with `_def` but no `_zod`),
- * it crashes with `undefined is not an object (evaluating 'n._zod.def')`.
+ * KiloCode (since its inception) and recent OpenCode releases (≥ ~1.14.x)
+ * bundle Zod v4 internally. When they receive plugin tool definitions whose
+ * `args` contain Zod v3 schemas (with `_def` but no `_zod.def`), they crash
+ * with `TypeError: undefined is not an object (evaluating 'n._zod.def')`.
  *
- * This module converts Zod 3 schema shapes into Zod 4 equivalents so KiloCode
- * can process them natively. Only called when `platform === "kilo"`.
- * OpenCode uses Zod 3 natively and receives the original shapes unchanged.
+ * This module converts Zod 3 schema shapes into Zod 4 equivalents so both
+ * hosts can process them natively.
  */
 import z from 'zod/v4';
 export function zod3ShapeToV4(shape, depth = 0) {
@@ -101,7 +101,7 @@ function zod3ToV4(v, depth = 0) {
             result = zod3ToV4(def.schema, depth + 1);
             break;
         default:
-            // Never leak raw Zod 3 schemas back to KiloCode.
+            // Never leak raw Zod 3 schemas back to a v4 host.
             result = z.unknown();
             break;
     }

package/build/adapters/pi/extension.js

@@ -141,22 +141,6 @@ let _mcpBridge = null;
  * a prior load.
  */
 export let _mcpBridgeReady = Promise.resolve();
-// Cached routing-block string (built once per process from hooks/routing-block.mjs).
-let _routingBlock = null;
-async function getRoutingBlock(pluginRoot) {
-    if (_routingBlock !== null)
-        return _routingBlock;
-    try {
-        const routingMod = await import(pathToFileURL(join(pluginRoot, "hooks", "routing-block.mjs")).href);
-        const namingMod = await import(pathToFileURL(join(pluginRoot, "hooks", "core", "tool-naming.mjs")).href);
-        const t = namingMod.createToolNamer("pi");
-        _routingBlock = String(routingMod.createRoutingBlock(t));
-    }
-    catch {
-        _routingBlock = "";
-    }
-    return _routingBlock;
-}
 // Cached buildAutoInjection (500-token cap, prioritized).
 let _buildAutoInjection = undefined;
 async function getAutoInjection(pluginRoot) {
@@ -546,14 +530,15 @@ export default function piExtension(pi) {
             const parts = [];
             if (existingPrompt)
                 parts.push(existingPrompt);
-            // Pi-1: Inject routing block every turn.
-            // Unlike Claude Code where the SessionStart hook injects once into a persistent
-            // context, Pi rebuilds the system prompt fresh on every before_agent_start call.
-            // The routing block must be re-injected each turn or it disappears after turn 1.
-            const routingBlock = await getRoutingBlock(pluginRoot);
-            if (routingBlock) {
-                parts.push(routingBlock);
-            }
+            // Pi-1: Lightweight routing anchor — 7KB routing block is too heavy
+            // for Pi's context budget. Tool descriptions from pi.registerTool()
+            // already tell the model what each tool does. This anchor gives the
+            // deliberate choice (which tool for which scenario) without the full
+            // block/redirect/memory/tool-selection hierarchy.
+            parts.push("context-mode active. Hierarchy: ctx_batch_execute > ctx_execute > ctx_execute_file > ctx_search. " +
+                "Read/edit files → ctx_execute_file. Multi-command research → ctx_batch_execute. " +
+                "Web pages → ctx_fetch_and_index then ctx_search. Index docs → ctx_index. " +
+                "Stats → ctx_stats. Doctor → ctx_doctor. Upgrade → ctx_upgrade. Purge → ctx_purge.");
             // Pi-3 + Pi-4: Always build active_memory (not just post-compact),
             // capped at 500 tokens via buildAutoInjection. Falls back to inline
             // budget loop if the helper is unavailable.

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

@@ -20,6 +20,8 @@
  *
  * No external dependencies — pure node:child_process + JSON line frames.
  */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { spawn, execSync } from "node:child_process";
 import { detectRuntimes } from "../../runtime.js";
 import { foreignWorkspaceEnv, foreignIdentificationEnv } from "../detect.js";
@@ -393,6 +395,41 @@ export class MCPStdioClient {
         for (const banned of foreignIdentificationEnv("pi")) {
             delete childEnv[banned];
         }
+        // Issue #561 regression fix: Pi detection vars are empty after
+        // foreign env scrubbing (CLAUDE_CODE_ENTRYPOINT / CLAUDE_PLUGIN_ROOT
+        // are deleted by the ban above). Without PI_CONFIG_DIR,
+        // detectPlatform() finds zero Pi identification vars and falls
+        // through to Claude Code default — stats land in ~/.claude/ instead
+        // of ~/.pi/. Set PI_CONFIG_DIR from the child's HOME env var so the
+        // child resolves to Pi correctly. (Use childEnv.HOME, not homedir(),
+        // because homedir() reads getpwent() which ignores our HOME override
+        // in test environments.)
+        //
+        // Cross-OS PI_CONFIG_DIR rescue (PR #741 follow-up):
+        //   1. If the parent already exported PI_CONFIG_DIR, trust it
+        //      verbatim — Pi's launcher owns that path and may pin it to
+        //      a non-default location (corporate setup, CI, etc.).
+        //   2. POSIX: ~/.pi (HOME-rooted).
+        //   3. Windows: probe both %USERPROFILE%\.pi (rare native install)
+        //      AND %APPDATA%\.pi (XDG-on-Windows, Pi's documented Windows
+        //      layout). Without the APPDATA fallback, every Pi-on-Windows
+        //      install silently drops back to the Claude Code default and
+        //      Pi's sessions write into the wrong directory.
+        if (!childEnv.PI_CONFIG_DIR) {
+            const home = childEnv.HOME ?? childEnv.USERPROFILE ?? childEnv.HOMEPATH;
+            const appData = childEnv.APPDATA; // Windows-only, undefined on POSIX
+            const candidates = [];
+            if (home)
+                candidates.push(join(home, ".pi"));
+            if (appData)
+                candidates.push(join(appData, ".pi"));
+            for (const candidate of candidates) {
+                if (existsSync(candidate)) {
+                    childEnv.PI_CONFIG_DIR = candidate;
+                    break;
+                }
+            }
+        }
         this._spawnEnv = childEnv;
         this.child = spawn(runtime, [this.serverScript], {
             // Pipe stderr (#472 round-3): swallowing it via "ignore" hides

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

@@ -17,7 +17,7 @@ import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { ClaudeCodeBaseAdapter } from "../claude-code-base.js";
 import { EXTERNAL_MCP_MATCHER_PATTERN } from "./hooks.js";
-import { buildNodeCommand, } from "../types.js";
+import { buildHookRuntimeCommand, } from "../types.js";
 // ─────────────────────────────────────────────────────────
 // Adapter implementation
 // ─────────────────────────────────────────────────────────
@@ -65,7 +65,7 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
                 {
                     matcher: preToolUseMatcher,
                     hooks: [
-                        { type: "command", command: buildNodeCommand(`${pluginRoot}/hooks/pretooluse.mjs`) },
+                        { type: "command", command: buildHookRuntimeCommand(`${pluginRoot}/hooks/pretooluse.mjs`) },
                     ],
                 },
             ],
@@ -73,7 +73,7 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
                 {
                     matcher: "run_shell_command|read_file|write_file|edit|glob|grep_search|todo_write|agent|ask_user_question|mcp__",
                     hooks: [
-                        { type: "command", command: buildNodeCommand(`${pluginRoot}/hooks/posttooluse.mjs`) },
+                        { type: "command", command: buildHookRuntimeCommand(`${pluginRoot}/hooks/posttooluse.mjs`) },
                     ],
                 },
             ],
@@ -81,7 +81,7 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
                 {
                     matcher: "",
                     hooks: [
-                        { type: "command", command: buildNodeCommand(`${pluginRoot}/hooks/sessionstart.mjs`) },
+                        { type: "command", command: buildHookRuntimeCommand(`${pluginRoot}/hooks/sessionstart.mjs`) },
                     ],
                 },
             ],
@@ -89,7 +89,7 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
                 {
                     matcher: "",
                     hooks: [
-                        { type: "command", command: buildNodeCommand(`${pluginRoot}/hooks/precompact.mjs`) },
+                        { type: "command", command: buildHookRuntimeCommand(`${pluginRoot}/hooks/precompact.mjs`) },
                     ],
                 },
             ],
@@ -97,7 +97,7 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
                 {
                     matcher: "",
                     hooks: [
-                        { type: "command", command: buildNodeCommand(`${pluginRoot}/hooks/userpromptsubmit.mjs`) },
+                        { type: "command", command: buildHookRuntimeCommand(`${pluginRoot}/hooks/userpromptsubmit.mjs`) },
                     ],
                 },
             ],
@@ -279,7 +279,7 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
         for (const { name, script, matcher } of hookTypes) {
             const entry = {
                 matcher,
-                hooks: [{ type: "command", command: buildNodeCommand(`${pluginRoot}/hooks/${script}`) }],
+                hooks: [{ type: "command", command: buildHookRuntimeCommand(`${pluginRoot}/hooks/${script}`) }],
             };
             const existing = hooks[name];
             if (existing && Array.isArray(existing)) {

package/build/adapters/types.d.ts

@@ -286,7 +286,39 @@ export interface HealthCheck {
  *
  * Safe on macOS/Linux — quoting and forward slashes are no-ops there.
  */
-export declare function buildNodeCommand(scriptPath: string): string;
+export declare function buildNodeCommand(scriptPath: string, opts?: {
+    platform?: string;
+    jsRuntime?: string;
+}): string;
+/**
+ * Build a cross-platform hook spawn command using the resolved JS runtime
+ * (issue #738). Identical wire-format to {@link buildNodeCommand} — two
+ * double-quoted, forward-slashed tokens separated by whitespace — so it
+ * round-trips through {@link parseNodeCommand} unchanged.
+ *
+ * The only difference is the runtime path: when a Bun ≥1.0 install is
+ * detected at process start, that path is used in place of `process.execPath`.
+ * Hooks run end-to-end in pure JS (no native modules) so swapping the
+ * runtime is a no-op for output but cuts ~40-60ms of Node cold-start per
+ * tool call.
+ *
+ * Why a SEPARATE helper instead of repurposing {@link buildNodeCommand}:
+ *   `buildNodeCommand` is also called by openclaw plugin (doctor / upgrade
+ *   command suggestions in `src/adapters/openclaw/plugin.ts`). Those CLI
+ *   targets MUST stay on Node because they load better-sqlite3, which has
+ *   no Bun-compatible prebuild yet (#543). Keeping the two helpers separate
+ *   makes the audit trivial: anything emitting a hook spawn command uses
+ *   `buildHookRuntimeCommand`; anything emitting a user-visible CLI command
+ *   stays on `buildNodeCommand`.
+ *
+ * `opts.platform` is forwarded to {@link isInProcessPluginPlatform} so the
+ * existing opencode/kilo in-process JS-runtime substitution still works
+ * (those platforms inject their own runtime via `opts.jsRuntime`).
+ */
+export declare function buildHookRuntimeCommand(scriptPath: string, opts?: {
+    platform?: string;
+    jsRuntime?: string;
+}): string;
 /**
  * Strict inverse of `buildNodeCommand`.
  *
@@ -309,8 +341,13 @@ export declare function parseNodeCommand(cmd: string): {
     nodePath: string;
     scriptPath: string;
 } | null;
+/** Known JS runtime binary names (base filename without extension). */
+export declare const JS_RUNTIMES: ReadonlySet<string>;
+/** Platforms where context-mode runs as an in-process TS plugin (not MCP stdio). */
+export declare const IN_PROCESS_PLUGIN_PLATFORMS: ReadonlySet<string>;
+export declare function isInProcessPluginPlatform(p: string | undefined): boolean;
 /** Supported platform identifiers. */
-export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "jetbrains-copilot" | "cursor" | "antigravity" | "kiro" | "pi" | "omp" | "zed" | "qwen-code" | "unknown";
+export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "jetbrains-copilot" | "cursor" | "antigravity" | "kiro" | "pi" | "omp" | "kimi" | "zed" | "qwen-code" | "unknown";
 /** Detection signal used to identify which platform is running. */
 export interface DetectionSignal {
     /** Platform identifier. */

package/build/adapters/types.js

@@ -11,6 +11,10 @@
  * Only the hook layer requires platform-specific adapters.
  */
 // ─────────────────────────────────────────────────────────
+// Hook paradigm
+// ─────────────────────────────────────────────────────────
+import { resolveHookRuntime } from "../runtime.js";
+// ─────────────────────────────────────────────────────────
 // Platform detection
 // ─────────────────────────────────────────────────────────
 // ─────────────────────────────────────────────────────────
@@ -28,11 +32,53 @@
  *
  * Safe on macOS/Linux — quoting and forward slashes are no-ops there.
  */
-export function buildNodeCommand(scriptPath) {
-    const nodePath = process.execPath.replace(/\\/g, "/");
+export function buildNodeCommand(scriptPath, opts) {
+    let nodePath = process.execPath.replace(/\\/g, "/");
+    if (isInProcessPluginPlatform(opts?.platform)) {
+        const base = nodePath.split("/").pop().replace(/\.exe$/i, "");
+        if (!JS_RUNTIMES.has(base)) {
+            nodePath = opts?.jsRuntime?.replace(/\\/g, "/") ?? "node";
+        }
+    }
     const safePath = scriptPath.replace(/\\/g, "/");
     return `"${nodePath}" "${safePath}"`;
 }
+/**
+ * Build a cross-platform hook spawn command using the resolved JS runtime
+ * (issue #738). Identical wire-format to {@link buildNodeCommand} — two
+ * double-quoted, forward-slashed tokens separated by whitespace — so it
+ * round-trips through {@link parseNodeCommand} unchanged.
+ *
+ * The only difference is the runtime path: when a Bun ≥1.0 install is
+ * detected at process start, that path is used in place of `process.execPath`.
+ * Hooks run end-to-end in pure JS (no native modules) so swapping the
+ * runtime is a no-op for output but cuts ~40-60ms of Node cold-start per
+ * tool call.
+ *
+ * Why a SEPARATE helper instead of repurposing {@link buildNodeCommand}:
+ *   `buildNodeCommand` is also called by openclaw plugin (doctor / upgrade
+ *   command suggestions in `src/adapters/openclaw/plugin.ts`). Those CLI
+ *   targets MUST stay on Node because they load better-sqlite3, which has
+ *   no Bun-compatible prebuild yet (#543). Keeping the two helpers separate
+ *   makes the audit trivial: anything emitting a hook spawn command uses
+ *   `buildHookRuntimeCommand`; anything emitting a user-visible CLI command
+ *   stays on `buildNodeCommand`.
+ *
+ * `opts.platform` is forwarded to {@link isInProcessPluginPlatform} so the
+ * existing opencode/kilo in-process JS-runtime substitution still works
+ * (those platforms inject their own runtime via `opts.jsRuntime`).
+ */
+export function buildHookRuntimeCommand(scriptPath, opts) {
+    // In-process plugin platforms (opencode/kilo) inject their own runtime —
+    // delegate to buildNodeCommand which already handles that special case.
+    if (isInProcessPluginPlatform(opts?.platform)) {
+        return buildNodeCommand(scriptPath, opts);
+    }
+    const runtime = resolveHookRuntime();
+    const runtimePath = runtime.path.replace(/\\/g, "/");
+    const safePath = scriptPath.replace(/\\/g, "/");
+    return `"${runtimePath}" "${safePath}"`;
+}
 /**
  * Strict inverse of `buildNodeCommand`.
  *
@@ -62,3 +108,10 @@ export function parseNodeCommand(cmd) {
         return null;
     return { nodePath: m[1], scriptPath: m[2] };
 }
+/** Known JS runtime binary names (base filename without extension). */
+export const JS_RUNTIMES = new Set(["node", "bun", "deno"]);
+/** Platforms where context-mode runs as an in-process TS plugin (not MCP stdio). */
+export const IN_PROCESS_PLUGIN_PLATFORMS = new Set(["opencode", "kilo"]);
+export function isInProcessPluginPlatform(p) {
+    return !!p && IN_PROCESS_PLUGIN_PLATFORMS.has(p);
+}