context-mode 1.0.151 → 1.0.152

package/hooks/kimi/platform.mjs

@@ -0,0 +1 @@
+process.env.CONTEXT_MODE_PLATFORM = "kimi";

package/hooks/kimi/posttooluse.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import "./platform.mjs";
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Kimi Code CLI postToolUse hook — session event capture.
+ */
+
+import { readStdin, parseStdin, getSessionId, getSessionDBPath, getInputProjectDir, KIMI_OPTS } from "../session-helpers.mjs";
+import { createSessionLoaders, attributeAndInsertEvents } from "../session-loaders.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const { loadSessionDB, loadExtract, loadProjectAttribution } = createSessionLoaders(HOOK_DIR);
+const OPTS = KIMI_OPTS;
+
+function normalizeToolName(toolName) {
+  if (toolName === "Shell") return "Bash";
+  return toolName;
+}
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const projectDir = getInputProjectDir(input, OPTS);
+
+  const { extractEvents } = await loadExtract();
+  const { resolveProjectAttributions } = await loadProjectAttribution();
+  const { SessionDB } = await loadSessionDB();
+
+  const dbPath = getSessionDBPath(OPTS, projectDir);
+  const db = new SessionDB({ dbPath });
+  const sessionId = getSessionId(input, OPTS);
+
+  db.ensureSession(sessionId, projectDir);
+
+  // Kimi Code sends tool_output on success (no tool_response field).
+  // Normalize tool_response to a clean string — when the host omits it,
+  // surface the empty string rather than `JSON.stringify(undefined ?? "")`
+  // which yields `'""'` and tricks downstream extractEvents into treating
+  // an empty response as a non-empty payload.
+  let toolResponse = "";
+  if (typeof input.tool_response === "string") {
+    toolResponse = input.tool_response;
+  } else if (input.tool_response !== undefined && input.tool_response !== null) {
+    toolResponse = JSON.stringify(input.tool_response);
+  }
+  const normalizedInput = {
+    tool_name: normalizeToolName(input.tool_name ?? ""),
+    tool_input: input.tool_input ?? {},
+    tool_response: toolResponse,
+    tool_output: input.tool_output
+      ? {
+        ...input.tool_output,
+        isError: input.tool_output.isError === true || input.tool_output.is_error === true,
+      }
+      : undefined,
+  };
+
+  const events = extractEvents(normalizedInput);
+
+  attributeAndInsertEvents(db, sessionId, events, input, projectDir, "PostToolUse", resolveProjectAttributions);
+
+  db.close();
+} catch {
+  // Swallow errors — hook must not fail
+}
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: "" },
+}) + "\n");

package/hooks/kimi/precompact.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import "./platform.mjs";
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Kimi Code CLI PreCompact hook - snapshot generation.
+ */
+
+import {
+  readStdin,
+  parseStdin,
+  getSessionId,
+  getSessionDBPath,
+  getInputProjectDir,
+  resolveConfigDir,
+  KIMI_OPTS,
+} from "../session-helpers.mjs";
+import { createSessionLoaders } from "../session-loaders.mjs";
+import { appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const { loadSessionDB, loadSnapshot } = createSessionLoaders(HOOK_DIR);
+const OPTS = KIMI_OPTS;
+// Diagnostic log is opt-in via CONTEXT_MODE_DEBUG. Long-running installs hit
+// compaction repeatedly; an unbounded append-only file under the user's data
+// root accrues on every transient error. Gating the write behind an env flag
+// preserves the diagnostic for contributors who want it without burdening
+// everyone else's disk. Match the pattern used by other hooks for error
+// telemetry — most stay silent unless explicitly enabled.
+const DEBUG_LOG = process.env.CONTEXT_MODE_DEBUG
+  ? join(resolveConfigDir(OPTS), "context-mode", "precompact-debug.log")
+  : null;
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const projectDir = getInputProjectDir(input, OPTS);
+
+  const { buildResumeSnapshot } = await loadSnapshot();
+  const { SessionDB } = await loadSessionDB();
+
+  const dbPath = getSessionDBPath(OPTS, projectDir);
+  const db = new SessionDB({ dbPath });
+  const sessionId = getSessionId(input, OPTS);
+
+  const events = db.getEvents(sessionId);
+
+  if (events.length > 0) {
+    const stats = db.getSessionStats(sessionId);
+    const snapshot = buildResumeSnapshot(events, {
+      compactCount: (stats?.compact_count ?? 0) + 1,
+    });
+
+    db.upsertResume(sessionId, snapshot, events.length);
+    db.incrementCompactCount(sessionId);
+
+    const fileEvents = events.filter((event) => event.category === "file");
+    db.insertEvent(sessionId, {
+      type: "compaction_summary",
+      category: "compaction",
+      data: `Session compacted. ${events.length} events, ${fileEvents.length} files touched.`,
+      priority: 1,
+    }, "PreCompact");
+  }
+
+  db.close();
+} catch (err) {
+  if (DEBUG_LOG) {
+    try {
+      appendFileSync(DEBUG_LOG, `[${new Date().toISOString()}] ${err?.message || err}\n`);
+    } catch {
+      // Hook errors must not break Kimi Code compaction.
+    }
+  }
+  // Without CONTEXT_MODE_DEBUG, swallow silently — same shape as other hooks.
+}
+
+process.stdout.write(JSON.stringify({}) + "\n");

package/hooks/kimi/pretooluse.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import "./platform.mjs";
+import "../suppress-stderr.mjs";
+/**
+ * Kimi Code CLI preToolUse hook for context-mode.
+ *
+ * Kimi Code PreToolUse supports:
+ *   - Exit code 0 with JSON:
+ *     { hookSpecificOutput: { permissionDecision: "deny", permissionDecisionReason: "..." } }
+ *     → block the tool call
+ *   - Exit code 2 → block (stderr used as reason)
+ *
+ * Like Codex, Kimi Code only acts on `permissionDecision === "deny"` —
+ * `ask` / `allow + updatedInput` / `additionalContext` are explicitly stripped
+ * by the host's runner (refs/platforms/kimi-code/.../session/hooks/runner.ts:
+ * 36-39,162-178) and its HookResult type has no additionalContext field
+ * (types.ts:28-37). The central formatter at hooks/core/formatters.mjs
+ * therefore returns null for those branches; see the codex precedent at #225
+ * (commit 607dc70).
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readStdin, parseStdin, getInputProjectDir, getSessionId, KIMI_OPTS } from "../session-helpers.mjs";
+import { routePreToolUse, initSecurity } from "../core/routing.mjs";
+import { formatDecision } from "../core/formatters.mjs";
+
+const __hookDir = dirname(fileURLToPath(import.meta.url));
+await initSecurity(resolve(__hookDir, "..", "..", "build"));
+
+const raw = await readStdin();
+const input = parseStdin(raw);
+const tool = input.tool_name ?? "";
+const toolInput = input.tool_input ?? {};
+const projectDir = getInputProjectDir(input, KIMI_OPTS);
+
+const decision = routePreToolUse(tool, toolInput, projectDir, "kimi", getSessionId(input, KIMI_OPTS));
+const response = formatDecision("kimi", decision);
+const output = response ?? {
+  hookSpecificOutput: { hookEventName: "PreToolUse" },
+};
+process.stdout.write(JSON.stringify(output) + "\n");

package/hooks/kimi/sessionend.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import "./platform.mjs";
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Kimi Code CLI SessionEnd hook — record genuine session close.
+ *
+ * Wired to the upstream `SessionEnd` event, distinct from `Stop`:
+ *   refs/platforms/kimi-code/packages/agent-core/src/session/index.ts:
+ *     192  — `await this.triggerSessionEnd('exit')` inside `close()`
+ *     502  — `triggerSessionEnd(reason: 'exit')` signature
+ *     11   — `'SessionEnd'` in `HOOK_EVENT_TYPES` (types.ts)
+ *   refs/platforms/kimi-cli/src/kimi_cli/hooks/events.py:108-114 — Python
+ *     runtime emits `session_end(session_id, cwd, reason)` independently
+ *     of `Stop`.
+ *
+ * Stop fires at the end of every assistant turn — writing a `session_end`
+ * SessionDB row from Stop produced one such row per turn. SessionEnd
+ * fires once when the host's session closes, which is what consumers of
+ * `type === "session_end"` (analytics, resume) actually mean.
+ */
+
+import { readStdin, parseStdin, getSessionId, getSessionDBPath, getInputProjectDir, KIMI_OPTS } from "../session-helpers.mjs";
+import { createSessionLoaders } from "../session-loaders.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
+const OPTS = KIMI_OPTS;
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const projectDir = getInputProjectDir(input, OPTS);
+
+  const { SessionDB } = await loadSessionDB();
+  const dbPath = getSessionDBPath(OPTS, projectDir);
+  const db = new SessionDB({ dbPath });
+  const sessionId = getSessionId(input, OPTS);
+
+  db.ensureSession(sessionId, projectDir);
+  // SessionEvent contract (src/types.ts:33-47) requires `type`, `category`,
+  // `data`, `priority`. Encode the payload — including `reason`, which
+  // upstream currently only emits as `'exit'` but is typed as a free string
+  // for forward compatibility — into `data` so dedup-hashing succeeds and
+  // the row lands.
+  const reason = typeof input.reason === "string" ? input.reason : "exit";
+  db.insertEvent(sessionId, {
+    type: "session_end",
+    category: "session",
+    data: JSON.stringify({ status: "completed", reason }),
+    priority: 1,
+  }, "SessionEnd");
+
+  db.close();
+} catch {
+  // Kimi Code hooks must not block session shutdown.
+}
+
+process.stdout.write("{}\n");

package/hooks/kimi/sessionstart.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import "./platform.mjs";
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Kimi Code CLI sessionStart hook for context-mode.
+ */
+
+import { createRoutingBlock } from "../routing-block.mjs";
+import { createToolNamer } from "../core/tool-naming.mjs";
+
+const toolNamer = createToolNamer("kimi");
+const ROUTING_BLOCK = createRoutingBlock(toolNamer);
+import {
+  writeSessionEventsFile,
+  buildSessionDirective,
+  getSessionEvents,
+} from "../session-directive.mjs";
+import {
+  readStdin,
+  parseStdin,
+  getSessionId,
+  getSessionDBPath,
+  getSessionEventsPath,
+  getCleanupFlagPath,
+  getInputProjectDir,
+  resolveConfigDir,
+  KIMI_OPTS,
+} from "../session-helpers.mjs";
+import { createSessionLoaders } from "../session-loaders.mjs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOK_DIR = fileURLToPath(new URL(".", import.meta.url));
+const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
+const OPTS = KIMI_OPTS;
+
+let additionalContext = ROUTING_BLOCK;
+
+function captureKimiInstructionRules(db, sessionId, projectDir) {
+  const paths = [];
+  for (const baseDir of [resolveConfigDir(OPTS), projectDir]) {
+    paths.push(join(baseDir, "AGENTS.md"));
+    paths.push(join(baseDir, "AGENTS.override.md"));
+  }
+
+  for (const p of [...new Set(paths)]) {
+    try {
+      if (!existsSync(p)) continue;
+      const content = readFileSync(p, "utf8");
+      db.insertEvent(sessionId, { type: "rule", category: "rule", data: p, priority: 1 });
+      db.insertEvent(sessionId, { type: "rule_content", category: "rule", data: content, priority: 1 });
+    } catch {
+      // Missing or unreadable rule files should never break SessionStart.
+    }
+  }
+}
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  // Kimi Code emits ONLY 'startup' | 'resume' for SessionStart.source:
+  //   refs/platforms/kimi-code/.../session/index.ts:153,181,495
+  //     (triggerSessionStart signature is `source: 'startup' | 'resume'`)
+  //   refs/platforms/kimi-cli/src/kimi_cli/cli/__init__.py:642
+  //     (`_session_source = "resume" if resumed else "startup"`)
+  // Default unknown values to 'startup' rather than branching on a
+  // 'compact' path that the host never reaches.
+  const source = input.source === "resume" ? "resume" : "startup";
+  const projectDir = getInputProjectDir(input, KIMI_OPTS);
+
+  if (source === "resume") {
+    const { SessionDB } = await loadSessionDB();
+    const dbPath = getSessionDBPath(OPTS, projectDir);
+    const db = new SessionDB({ dbPath });
+    const sessionId = getSessionId(input, OPTS);
+
+    try { unlinkSync(getCleanupFlagPath(OPTS, projectDir)); } catch { /* no flag */ }
+
+    const events = sessionId ? getSessionEvents(db, sessionId) : [];
+    if (events.length > 0) {
+      const eventMeta = writeSessionEventsFile(events, getSessionEventsPath(OPTS, projectDir));
+      additionalContext += buildSessionDirective(source, eventMeta, toolNamer);
+    }
+
+    db.close();
+  } else {
+    // source === "startup"
+    const { SessionDB } = await loadSessionDB();
+    const dbPath = getSessionDBPath(OPTS, projectDir);
+    const db = new SessionDB({ dbPath });
+    try { unlinkSync(getSessionEventsPath(OPTS, projectDir)); } catch { /* no stale file */ }
+
+    db.cleanupOldSessions(7);
+    // Single source of truth lives in SessionDB. Reaching through `db.db.exec`
+    // duplicated schema knowledge in the hook and would silently drift if
+    // `session_events` ever renamed its FK column.
+    db.pruneOrphanedEvents();
+
+    const sessionId = getSessionId(input, OPTS);
+    db.ensureSession(sessionId, projectDir);
+    captureKimiInstructionRules(db, sessionId, projectDir);
+
+    db.close();
+  }
+} catch {
+  // Swallow errors — hook must not fail
+}
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: { hookEventName: "SessionStart", additionalContext },
+}) + "\n");

package/hooks/kimi/stop.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import "./platform.mjs";
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Kimi Code CLI Stop hook — record turn-end state for continuity.
+ *
+ * Stop fires at the END OF EACH ASSISTANT TURN, not at session close.
+ * Kimi Code emits a distinct `SessionEnd` event for genuine session
+ * shutdown (refs/platforms/kimi-code/.../session/index.ts:192,502 —
+ * `triggerSessionEnd('exit')`); the matching `hooks/kimi/sessionend.mjs`
+ * owns the `session_end` SessionDB row. Writing `session_end` here would
+ * have produced one such row per turn.
+ *   Cross-reference: refs/platforms/kimi-cli/src/kimi_cli/hooks/events.py:
+ *     99-114 — `session_start` and `session_end` are distinct emitters.
+ */
+
+import { readStdin, parseStdin, getSessionId, getSessionDBPath, getInputProjectDir, KIMI_OPTS } from "../session-helpers.mjs";
+import { createSessionLoaders } from "../session-loaders.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
+const OPTS = KIMI_OPTS;
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const projectDir = getInputProjectDir(input, OPTS);
+
+  const { SessionDB } = await loadSessionDB();
+  const dbPath = getSessionDBPath(OPTS, projectDir);
+  const db = new SessionDB({ dbPath });
+  const sessionId = getSessionId(input, OPTS);
+
+  db.ensureSession(sessionId, projectDir);
+  // SessionEvent contract (src/types.ts:33-47) requires `type`, `category`,
+  // `data`, `priority`. SessionDB.insertEvent hashes `event.data` for the
+  // dedup key — passing `undefined` throws inside the wrapping try and the
+  // row silently never lands. Encode the turn snapshot into `data` so the
+  // hash is stable and the row actually persists.
+  const payload = {
+    stop_hook_active: input.stop_hook_active ?? false,
+    last_assistant_message: typeof input.last_assistant_message === "string"
+      ? input.last_assistant_message.slice(0, 2000)
+      : null,
+  };
+  db.insertEvent(sessionId, {
+    type: "turn_end",
+    category: "session",
+    data: JSON.stringify(payload),
+    priority: 1,
+  }, "Stop");
+
+  db.close();
+} catch {
+  // Kimi Code hooks must not block the session.
+}
+
+process.stdout.write("{}\n");

package/hooks/kimi/userpromptsubmit.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import "./platform.mjs";
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Kimi Code CLI UserPromptSubmit hook — capture user prompts for continuity.
+ *
+ * Kimi Code sends `prompt` as a ContentPart[] array. We normalize it to
+ * a single string so downstream extractors work correctly.
+ */
+
+import { readStdin, parseStdin, getSessionId, getSessionDBPath, getInputProjectDir, KIMI_OPTS } from "../session-helpers.mjs";
+import { createSessionLoaders, attributeAndInsertEvents } from "../session-loaders.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const { loadSessionDB, loadExtract, loadProjectAttribution } = createSessionLoaders(HOOK_DIR);
+const OPTS = KIMI_OPTS;
+
+function extractPromptText(input) {
+  const raw = input.prompt ?? input.message ?? "";
+  if (Array.isArray(raw)) {
+    // ContentPart[] — Kimi Code sends { type: "text", text: "..." } objects
+    return raw
+      .filter((p) => p && (p.type === "text" || typeof p.text === "string"))
+      .map((p) => p.text)
+      .join("\n");
+  }
+  return String(raw);
+}
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const projectDir = getInputProjectDir(input, OPTS);
+
+  const prompt = extractPromptText(input);
+  const trimmed = (prompt || "").trim();
+
+  const isSystemMessage = trimmed.startsWith("<task-notification>")
+    || trimmed.startsWith("<system-reminder>")
+    || trimmed.startsWith("<context_guidance>")
+    || trimmed.startsWith("<tool-result>");
+
+  if (trimmed.length > 0 && !isSystemMessage) {
+    const { SessionDB } = await loadSessionDB();
+    const { extractUserEvents } = await loadExtract();
+    const { resolveProjectAttributions } = await loadProjectAttribution();
+    const dbPath = getSessionDBPath(OPTS, projectDir);
+    const db = new SessionDB({ dbPath });
+    const sessionId = getSessionId(input, OPTS);
+
+    db.ensureSession(sessionId, projectDir);
+
+    const promptEvent = {
+      type: "user_prompt",
+      category: "user-prompt",
+      data: prompt,
+      priority: 1,
+    };
+    const promptAttributions = attributeAndInsertEvents(
+      db, sessionId, [promptEvent], input, projectDir, "UserPromptSubmit", resolveProjectAttributions,
+    );
+
+    const userEvents = extractUserEvents(trimmed);
+    const savedLastKnown = promptAttributions[0]?.projectDir || null;
+    const sessionStats = db.getSessionStats(sessionId);
+    const lastKnownProjectDir = typeof db.getLatestAttributedProjectDir === "function"
+      ? db.getLatestAttributedProjectDir(sessionId)
+      : null;
+    const userAttributions = resolveProjectAttributions(userEvents, {
+      sessionOriginDir: sessionStats?.project_dir || projectDir,
+      inputProjectDir: projectDir,
+      workspaceRoots: Array.isArray(input.workspace_roots) ? input.workspace_roots : [],
+      lastKnownProjectDir: savedLastKnown || lastKnownProjectDir,
+    });
+    for (let i = 0; i < userEvents.length; i++) {
+      db.insertEvent(sessionId, userEvents[i], "UserPromptSubmit", userAttributions[i]);
+    }
+
+    db.close();
+  }
+} catch {
+  // Kimi Code hooks must not block the session.
+}
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: "" },
+}) + "\n");

package/hooks/normalize-hooks.mjs

@@ -219,29 +219,55 @@ export function normalizePluginJson(content, nodePath, pluginRoot) {
 }
 
 /**
- * Apply normalization to hooks.json and plugin.json on startup.
+ * Apply normalization to hooks/hooks.json ONLY (not plugin.json).
+ *
+ * Why a narrow variant exists (#711 + #414 / #528):
+ *   - plugin.json is read by Claude Code's plugin manager and carried forward
+ *     into NEW versioned cache dirs on auto-update. Baking absolute paths into
+ *     it during /ctx-upgrade poisons the next version (#711).
+ *   - hooks/hooks.json lives in the per-version dir and is read by the SAME
+ *     Node process that needs to spawn a child. On Windows + Git Bash, Claude
+ *     Code fires SessionStart/PreToolUse BEFORE MCP boot — the unresolved
+ *     `${CLAUDE_PLUGIN_ROOT}` placeholder yields MODULE_NOT_FOUND for the
+ *     first hook fire after /ctx-upgrade (#414).
+ *
+ * So /ctx-upgrade calls THIS narrow function (hooks.json only) to close the
+ * Windows first-hook-fire window without re-introducing #711.
  *
  * Options:
- *   - pluginRoot: absolute path to plugin install dir (e.g. __dirname of start.mjs)
- *   - nodePath:   process.execPath
- *   - platform:   process.platform ("win32" and "linux" trigger a write)
+ *   - pluginRoot:     absolute path to plugin install dir
+ *   - nodePath:       process.execPath (the Node binary running this script)
+ *   - jsRuntimePath:  optional — resolved Bun ≥1.0 path (#738). When set, the
+ *                     rewrite uses this instead of nodePath so hook invocations
+ *                     gain Bun's ~40-60ms cold-start advantage. Falls back to
+ *                     nodePath when omitted (back-compat).
+ *   - platform:       process.platform. Triggers a write on:
+ *                       • "win32" / "linux" — the original #378 path
+ *                         (#369/#372 MSYS / nvm fixes), AND
+ *                       • any platform when jsRuntimePath !== nodePath
+ *                         (#738 — bun swap is a perf optimisation that should
+ *                         not be gated by the historical Windows-only check;
+ *                         issue was filed from macOS).
  *
  * Best-effort — never throws.
  */
-export function normalizeHooksOnStartup({ pluginRoot, nodePath, platform }) {
-  // Normalize on Windows (MSYS path mangling, #369/#372/#378) and Linux
-  // (bare `node` not in PATH when invoked via /bin/sh, e.g. nvm users).
-  // macOS ships a system node so bare `node` resolves reliably there.
-  if (platform !== "win32" && platform !== "linux") return;
-  if (!pluginRoot || !nodePath) return;
+export function normalizeHooksJsonOnly({ pluginRoot, nodePath, jsRuntimePath, platform }) {
+  const effectiveRuntime = jsRuntimePath || nodePath;
+  // #378 path: always normalize on Windows/Linux to heal placeholder + bare-node.
+  // #738 path: also fire on macOS when we have a real bun swap to perform — the
+  // legacy gate skipped darwin because system node was reliable there, but bun
+  // resolution is the new perf-win that the gate now needs to allow through.
+  const isPlatformGated = platform !== "win32" && platform !== "linux";
+  const hasBunSwap = jsRuntimePath && jsRuntimePath !== nodePath;
+  if (isPlatformGated && !hasBunSwap) return;
+  if (!pluginRoot || !effectiveRuntime) return;
 
-  // hooks/hooks.json
   try {
     const hooksPath = resolve(pluginRoot, "hooks", "hooks.json");
     if (existsSync(hooksPath)) {
       const original = readFileSync(hooksPath, "utf-8");
       if (needsHookNormalization(original, pluginRoot)) {
-        const next = normalizeHooksJson(original, nodePath, pluginRoot);
+        const next = normalizeHooksJson(original, effectiveRuntime, pluginRoot);
         if (next !== original) {
           writeFileSync(hooksPath, next, "utf-8");
         }
@@ -250,6 +276,34 @@ export function normalizeHooksOnStartup({ pluginRoot, nodePath, platform }) {
   } catch {
     /* best effort */
   }
+}
+
+/**
+ * Apply normalization to hooks.json and plugin.json on startup.
+ *
+ * Options:
+ *   - pluginRoot:     absolute path to plugin install dir (e.g. __dirname of start.mjs)
+ *   - nodePath:       process.execPath
+ *   - jsRuntimePath:  optional Bun ≥1.0 path (#738) — used for hooks.json only,
+ *                     never for plugin.json (the MCP server itself must stay on
+ *                     Node — better-sqlite3 ABI, #543)
+ *   - platform:       process.platform ("win32" and "linux" trigger plugin.json
+ *                     rewrite for #378; hooks.json also rewrites on darwin when
+ *                     `jsRuntimePath` !== `nodePath` for #738)
+ *
+ * Best-effort — never throws.
+ */
+export function normalizeHooksOnStartup({ pluginRoot, nodePath, jsRuntimePath, platform }) {
+  // Delegate the hooks.json branch to the narrow helper so /ctx-upgrade and
+  // boot share one implementation. plugin.json normalization stays here —
+  // start.mjs and postinstall still need it; /ctx-upgrade must NOT (#711).
+  normalizeHooksJsonOnly({ pluginRoot, nodePath, jsRuntimePath, platform });
+
+  // plugin.json rewrite: ALWAYS uses nodePath (MCP server must stay on Node,
+  // #543). Bun resolution is irrelevant here — `jsRuntimePath` is consumed
+  // exclusively by the hooks.json branch above.
+  if (platform !== "win32" && platform !== "linux") return;
+  if (!pluginRoot || !nodePath) return;
 
   // .claude-plugin/plugin.json
   try {

package/hooks/routing-block.mjs

@@ -14,13 +14,19 @@ import { createToolNamer } from "./core/tool-naming.mjs";
 // ── Factory functions ─────────────────────────────────────
 
 export function createRoutingBlock(t, options = {}) {
-  const { includeCommands = true } = options;
+  const { includeCommands = true, toolSearchBootstrap = false } = options;
   return `
 <context_window_protection>
   <priority_instructions>
     Every byte a tool returns enters your conversation memory and costs reasoning capacity for the rest of the session. The context-mode tools let you do the work in a sandbox and surface only the derived answer — the raw bytes stay out. Think-in-Code: program the analysis, do not compute it by reading raw data into your conversation.
   </priority_instructions>
-
+${toolSearchBootstrap ? `
+  <deferred_tool_bootstrap>
+    The context-mode tools below may be DEFERRED in your harness — their schemas are not loaded yet, so calling them directly fails (e.g. "tool not found" / InputValidationError). Load them ONCE before your first ctx_* call:
+    ToolSearch(query: "select:${t("ctx_batch_execute")},${t("ctx_search")},${t("ctx_execute")},${t("ctx_execute_file")},${t("ctx_fetch_and_index")}")
+    After that they are callable. If any ctx_* call fails as not-found, ToolSearch it and retry — do NOT fall back to Bash/Read just because the schema was not loaded yet.
+  </deferred_tool_bootstrap>
+` : ''}
   <tool_selection_hierarchy>
     0. MEMORY: ${t("ctx_search")}(sort: "timeline")
        - On resume or compaction, query prior decisions, errors, plans, user prompts before asking the user — auto-captured session memory is searchable.