@mxalbert/context-mode 2.0.0

package/hooks/core/codex-caps.mjs

@@ -0,0 +1,112 @@
+/**
+ * Codex capability detection for the PreToolUse formatter (#845).
+ *
+ * Recent Codex builds honor PreToolUse `permissionDecision:"allow" + updatedInput`
+ * (command rewrite) and `additionalContext`. Older builds reject/ignore those
+ * fields. context-mode must emit the rewrite shape ONLY when the running Codex
+ * supports it and otherwise fail closed (deny) — it must never silently pass a
+ * redirect through.
+ *
+ * Detection parses `codex --version` and compares it against the first version
+ * verified to honor the contract. The result is cached to a temp file with a
+ * short TTL so the hot PreToolUse path does not spawn a process on every tool
+ * call. Any failure (no codex on PATH, parse error) → false → fail closed.
+ *
+ * There is intentionally NO opt-in env flag — those rot into dead code because
+ * nobody exercises the off-by-default path. The correct behavior is detected at
+ * runtime so it is always the default.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * First Codex release verified to honor PreToolUse allow+updatedInput and
+ * additionalContext: codex-cli 0.141.0 (#845, validated against the shipped
+ * binary's output_parser). Below this we fail closed.
+ */
+export const MIN_REWRITE_VERSION = [0, 141, 0];
+
+const CACHE_TTL_MS = 60 * 60 * 1000; // re-probe at most hourly
+const CACHE_FILE = "context-mode-codex-caps.json";
+
+/** Parse a `codex --version` line ("codex-cli 0.141.0") → [major, minor, patch]. */
+export function parseCodexVersion(raw) {
+  const s = String(raw ?? "");
+  const isDigit = (c) => c >= "0" && c <= "9";
+  for (let i = 0; i < s.length; i++) {
+    let j = i;
+    const parts = [];
+    while (parts.length < 3) {
+      const start = j;
+      while (j < s.length && isDigit(s[j])) j++;
+      if (j === start) break; // no digits where a number was expected
+      parts.push(Number(s.slice(start, j)));
+      if (parts.length < 3) {
+        if (s[j] !== ".") break; // separator must be a dot
+        j++;
+      }
+    }
+    if (parts.length === 3) return parts;
+  }
+  return null;
+}
+
+/** Semantic ">=" over [major, minor, patch] tuples. */
+export function versionGte(a, b) {
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return true;
+}
+
+function defaultRunVersion() {
+  const opts = { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] };
+  // Mirror the adapter's cross-platform probe (src/adapters/codex/index.ts):
+  // on Windows `codex` resolves to a .cmd shim that execFile cannot launch
+  // directly, so route through cmd.exe.
+  return process.platform === "win32"
+    ? execFileSync("cmd.exe", ["/d", "/s", "/c", "codex --version"], opts)
+    : execFileSync("codex", ["--version"], opts);
+}
+
+/**
+ * Whether the running Codex honors PreToolUse allow+updatedInput /
+ * additionalContext. Fails closed (false) on any error. Cached to a temp file
+ * with a TTL so the hot path avoids per-call process spawns.
+ *
+ * @param {object} [io] test seams
+ * @param {() => string} [io.runVersion] returns `codex --version` stdout
+ * @param {() => number}  [io.now]        clock in ms
+ * @param {string}        [io.cachePath]  cache file path
+ * @returns {boolean}
+ */
+export function codexSupportsUpdatedInput(io = {}) {
+  const now = io.now ?? Date.now;
+  const cachePath = io.cachePath ?? join(tmpdir(), CACHE_FILE);
+  const runVersion = io.runVersion ?? defaultRunVersion;
+
+  // Fast path: a non-expired cache entry.
+  try {
+    const cached = JSON.parse(readFileSync(cachePath, "utf8"));
+    if (cached && typeof cached.at === "number" && now() - cached.at < CACHE_TTL_MS) {
+      return cached.supported === true;
+    }
+  } catch { /* cache miss / corrupt — re-detect below */ }
+
+  let supported = false;
+  try {
+    const version = parseCodexVersion(runVersion());
+    supported = version ? versionGte(version, MIN_REWRITE_VERSION) : false;
+  } catch {
+    supported = false; // no codex on PATH / probe failed → fail closed
+  }
+
+  try { writeFileSync(cachePath, JSON.stringify({ at: now(), supported })); } catch { /* best effort */ }
+
+  return supported;
+}

package/hooks/core/formatters.mjs

@@ -0,0 +1,356 @@
+/**
+ * Platform-specific response formatters.
+ * Takes normalized decision from routing.mjs -> platform-specific JSON output.
+ */
+
+export const formatters = {
+  "claude-code": {
+    deny: (reason) => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
+    }),
+    ask: () => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "ask",
+      },
+    }),
+    // Tool-aware modify handling for claude-code:
+    //
+    // - Bash redirect (updatedInput.command): CC v2.1.x ignores
+    //   `updatedInput.command` substitution under `permissionDecision: "allow"`
+    //   — original command runs unchanged. Verified via /diagnose Phase 4
+    //   forced-deny probe: only `permissionDecision: "deny"` is honored for
+    //   Bash blocking. Emit deny + extract echo payload into
+    //   `permissionDecisionReason`.
+    //
+    // - Agent prompt injection (updatedInput.prompt): CC honors
+    //   allow+updatedInput for Agent tool — modified prompt reaches the
+    //   subagent. Keep modify shape so subagent routing-block injection works.
+    //
+    // - Any other shape: pass through as modify and let CC decide.
+    //
+    // Other adapters (gemini-cli, vscode-copilot, etc.) keep their own modify
+    // semantics — their hosts implement updatedInput differently or not at all.
+    modify: (updatedInput) => {
+      const ui = updatedInput ?? {};
+      const isBashCommandRedirect = "command" in ui;
+      if (!isBashCommandRedirect) {
+        return {
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            updatedInput: ui,
+          },
+        };
+      }
+      // routing.mjs wraps the redirect guidance in `echo "..."` form.
+      // Extract the quoted payload as the deny reason. Fall back to a generic
+      // ADR-0003 CASE A message if the shape doesn't match.
+      const cmd = ui.command ?? "";
+      const m = cmd.match(/^echo\s+"(.+)"$/s);
+      const reason = m
+        ? m[1]
+        : "Redirected to ctx_execute / ctx_fetch_and_index. Call ctx_execute(language, code) to fetch and derive your answer in one round trip, or call ctx_fetch_and_index(url, source) when you want to query the response later via ctx_search. Both have full network access. Retry the same call on a transient DNS error (EAI_AGAIN, ETIMEDOUT, ENETUNREACH).";
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: reason,
+        },
+      };
+    },
+    context: (additionalContext) => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext,
+      },
+    }),
+  },
+
+  "gemini-cli": {
+    deny: (reason) => ({ decision: "deny", reason }),
+    ask: () => null, // Gemini CLI has no "ask" concept
+    modify: (updatedInput) => ({
+      hookSpecificOutput: { tool_input: updatedInput },
+    }),
+    context: (additionalContext) => ({
+      hookSpecificOutput: { additionalContext },
+    }),
+  },
+
+  "vscode-copilot": {
+    deny: (reason) => ({
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    }),
+    ask: () => ({
+      permissionDecision: "ask",
+    }),
+    modify: (updatedInput) => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "allow",
+        permissionDecisionReason: "Routed to context-mode sandbox",
+        updatedInput,
+      },
+    }),
+    context: (additionalContext) => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext,
+      },
+    }),
+  },
+
+  // GitHub Copilot CLI uses top-level decision fields (NOT the VS Code
+  // hookSpecificOutput wrapper) — matches CopilotCliAdapter.format*Response.
+  "copilot-cli": {
+    deny: (reason) => ({
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    }),
+    // Carry the reason on `ask` too, so the user sees WHY confirmation is
+    // requested (Copilot CLI honors permissionDecisionReason; matches the
+    // adapter's formatPreToolUseResponse ask branch). Fall back when the
+    // routing decision carries no reason, so the prompt is never bare.
+    ask: (reason) => ({
+      permissionDecision: "ask",
+      permissionDecisionReason: reason ?? "Action requires user confirmation",
+    }),
+    modify: (updatedInput) => ({
+      modifiedArgs: updatedInput,
+    }),
+    context: (additionalContext) => ({
+      additionalContext,
+    }),
+  },
+
+  "jetbrains-copilot": {
+    deny: (reason) => ({
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    }),
+    ask: () => ({
+      permissionDecision: "ask",
+    }),
+    modify: (updatedInput) => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "allow",
+        permissionDecisionReason: "Routed to context-mode sandbox",
+        updatedInput,
+      },
+    }),
+    context: (additionalContext) => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext,
+      },
+    }),
+  },
+
+  "codex": {
+    deny: (reason) => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
+    }),
+    // Codex still rejects permissionDecision:"ask" in PreToolUse (verified
+    // against codex-cli 0.141.0 output_parser.rs). Keep dropping it.
+    ask: () => null,
+    // #845: modern Codex (>= 0.141.0) honors permissionDecision:"allow" +
+    // updatedInput (command rewrite). Emit it when the running Codex supports
+    // it; otherwise FAIL CLOSED — turn the redirect into an enforceable deny
+    // carrying the same guidance, so the bytes-flood guard never silently
+    // passes through. `codexSupportsRewrite` is detected at runtime by the
+    // codex hook (hooks/core/codex-caps.mjs) and threaded in via formatDecision.
+    modify: (updatedInput, { codexSupportsRewrite } = {}) => {
+      if (codexSupportsRewrite) {
+        return {
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            updatedInput,
+          },
+        };
+      }
+      const ui = updatedInput ?? {};
+      // Only command redirects must fail closed. Non-command rewrites (e.g.
+      // Agent prompt injection) are advisory — drop rather than block the tool.
+      if (!("command" in ui)) return null;
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: codexRedirectReason(ui.command),
+        },
+      };
+    },
+    // #845: surface additionalContext on Codex builds that support it; older
+    // builds ignore the field, so drop the advisory nudge rather than emit a
+    // shape they reject.
+    context: (additionalContext, { codexSupportsRewrite } = {}) =>
+      codexSupportsRewrite
+        ? { hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext } }
+        : null,
+  },
+
+  "kimi": {
+    // Kimi Code / Kimi CLI hook runners parse ONLY `permissionDecision === "deny"`
+    // for structured PreToolUse output. Anything else (ask / allow+updatedInput /
+    // additionalContext) is silently dropped, and the host's HookResult type has
+    // no `additionalContext` field at all.
+    //   Evidence: refs/platforms/kimi-code/packages/agent-core/src/session/hooks/
+    //     runner.ts:36-39,162-178  (HookSpecificOutputSchema + structuredOutput())
+    //   Evidence: refs/platforms/kimi-code/packages/agent-core/src/session/hooks/
+    //     types.ts:28-37            (HookResult has no additionalContext)
+    //   Evidence: refs/platforms/kimi-cli/src/kimi_cli/hooks/runner.py:62-89
+    //     (Python runtime behaves identically)
+    // This mirrors the codex precedent established at commit 607dc70 (#225),
+    // where the same upstream "deny-only" parser forced ask/modify/context to
+    // return null in the formatter rather than emit fields the host ignores.
+    deny: (reason) => ({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
+    }),
+    ask: () => null,     // Kimi runner ignores permissionDecision !== "deny"
+    modify: () => null,  // Kimi runner has no updatedInput channel
+    context: () => null, // Kimi HookResult has no additionalContext field
+  },
+
+  "antigravity-cli": {
+    // agy PreToolUse accepts the Claude-compatible top-level decision shape.
+    // agy 1.0.6 does NOT honor PreToolUse additionalContext (verified by
+    // transcript probe), so context guidance must become an enforceable deny
+    // or it disappears and the native tool runs unchanged.
+    deny: (reason) => ({ decision: "deny", reason }),
+    // Carry a fallback reason on `ask` so a security-policy ask (routing emits
+    // {action:"ask"} with no reason) never shows a bare, unexplained prompt.
+    ask: (reason) => ({ decision: "ask", reason: reason ?? "Action requires user confirmation" }),
+    // agy cannot modify tool args, so a routing `modify` becomes a deny. Surface
+    // the per-tool redirect guidance routing carried in `updatedInput.command`
+    // (an `echo "<guidance>"` payload that already uses agy's context-mode/<tool>
+    // surface) instead of a generic line; fall back to the generic redirect.
+    modify: (updatedInput) => {
+      const cmd = updatedInput?.command ?? updatedInput?.CommandLine ?? "";
+      const m = String(cmd).match(/^echo\s+"([\s\S]*)"\s*$/);
+      const guidance = m ? m[1].replace(/\\(["\\])/g, "$1") : "";
+      return {
+        decision: "deny",
+        reason:
+          guidance ||
+          "context-mode: redirected. Use the context-mode MCP tools (ctx_execute / ctx_fetch_and_index / ctx_search) so raw bytes stay out of the conversation.",
+      };
+    },
+    context: (additionalContext) => ({
+      decision: "deny",
+      reason: agyContextReason(additionalContext),
+    }),
+  },
+
+  "cursor": {
+    deny: (reason) => ({
+      permission: "deny",
+      user_message: reason,
+    }),
+    ask: () => ({
+      permission: "ask",
+    }),
+    modify: (updatedInput) => ({
+      updated_input: updatedInput,
+    }),
+    context: (additionalContext) => ({
+      agent_message: additionalContext,
+    }),
+  },
+};
+
+// Keep in sync with the identical agyContextReason in
+// src/adapters/antigravity-cli/index.ts: this bundled .mjs formatter (runtime
+// hook path) and the TS adapter are separate layers; the text must not drift.
+function agyContextReason(additionalContext) {
+  const text = String(additionalContext ?? "")
+    .replace(/<\/?context_guidance>/g, " ")
+    .replace(/<\/?tip>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text
+    ? `context-mode: use the context-mode MCP tools instead of this native tool. ${text}`
+    : "context-mode: use the context-mode MCP tools instead of this native tool so raw bytes stay out of the conversation.";
+}
+
+// #845: routing wraps redirect guidance as `echo "<guidance>"`. Unwrap a command
+// that is exactly `echo "<inner>"` (with optional surrounding whitespace) and
+// return the inner string, or null when the shape doesn't match. Greedy: inner
+// runs from the first `"` after `echo` to the last `"` before trailing space.
+function unwrapEcho(command) {
+  const s = String(command ?? "");
+  // Match the regex `\s` class exactly: space, tab, newline, carriage return,
+  // form feed, vertical tab (so behavior is identical to /^echo\s+"…"\s*$/).
+  const isWs = (c) =>
+    c === " " || c === "\t" || c === "\n" || c === "\r" || c === "\f" || c === "\v";
+  if (!s.startsWith("echo")) return null;
+  let i = 4;
+  if (i >= s.length || !isWs(s[i])) return null; // `echo` must be followed by whitespace
+  while (i < s.length && isWs(s[i])) i++;
+  if (s[i] !== "\"") return null; // payload must open with a quote
+  let end = s.length;
+  while (end > 0 && isWs(s[end - 1])) end--; // drop trailing whitespace
+  if (end <= i + 1 || s[end - 1] !== "\"") return null; // must close with a quote
+  return s.slice(i + 1, end - 1);
+}
+
+// Reverse the shell double-quote escaping routing applied: `\"` → `"`, `\\` → `\`.
+function unescapeDquote(s) {
+  let out = "";
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\" && (s[i + 1] === "\"" || s[i + 1] === "\\")) {
+      out += s[i + 1];
+      i++;
+    } else {
+      out += s[i];
+    }
+  }
+  return out;
+}
+
+// When Codex cannot rewrite the command we surface that guidance as the deny
+// reason instead (mirrors the claude-code / antigravity-cli echo extraction).
+function codexRedirectReason(command) {
+  const inner = unwrapEcho(command);
+  if (inner !== null) return unescapeDquote(inner);
+  return "context-mode: command redirected. Use the context-mode MCP tools (ctx_execute / ctx_fetch_and_index / ctx_search) so raw output stays out of the conversation.";
+}
+
+/**
+ * Apply a formatter to a normalized routing decision.
+ * Returns the platform-specific JSON response, or null for passthrough.
+ *
+ * `opts` carries optional per-platform capability hints (e.g. codex
+ * `codexSupportsRewrite`). Formatters that ignore the extra argument are
+ * unaffected.
+ */
+export function formatDecision(platform, decision, opts = {}) {
+  if (!decision) return null;
+
+  const fmt = formatters[platform];
+  if (!fmt) return null;
+
+  switch (decision.action) {
+    case "deny": return fmt.deny(decision.reason);
+    // Pass the reason to ask() too — platforms whose ask formatter ignores it
+    // (legacy `ask: () => …`) are unaffected; copilot-cli surfaces it.
+    case "ask": return fmt.ask(decision.reason);
+    case "modify": return fmt.modify(decision.updatedInput, opts);
+    case "context": return fmt.context(decision.additionalContext, opts);
+    default: return null;
+  }
+}

package/hooks/core/mcp-ready.mjs

@@ -0,0 +1,109 @@
+/**
+ * MCP readiness sentinel — checks if MCP server has started.
+ *
+ * Server writes sentinel (containing its PID) after connect().
+ * Hooks scan for any live sentinel to detect MCP readiness.
+ *
+ * Fix for #347: Claude Code spawns hooks via `bash -c "node ..."` on Linux/WSL2.
+ * The intermediate shell makes process.ppid point to a transient bash PID, not
+ * Claude Code. Directory-scan + PID liveness probe works regardless of spawn topology.
+ *
+ * Sentinel path: <tmpRoot>/context-mode-mcp-ready-<MCP_PID>
+ * Scan: glob all context-mode-mcp-ready-* files, probe each PID.
+ */
+import { readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const SENTINEL_PREFIX = "context-mode-mcp-ready-";
+
+/**
+ * Sentinel freshness window (#844). The MCP server refreshes its sentinel's
+ * mtime every 30s while alive (see `main()` in src/server.ts). A sentinel
+ * touched within this window is treated as a live server even when
+ * `process.kill(pid, 0)` cannot see the PID — e.g. a sandbox sharing /tmp
+ * across an isolated PID namespace, where the live host PID is invisible.
+ * 90s = 3x the server refresh interval, tolerant of scheduler jitter / load.
+ */
+const SENTINEL_FRESH_MS = 90_000;
+
+/**
+ * Resolve the temp root — hardcoded /tmp on Unix to avoid TMPDIR mismatch.
+ * Tests may override via CONTEXT_MODE_MCP_SENTINEL_DIR to isolate scan from
+ * leftover sentinels in the real /tmp.
+ */
+export function sentinelDir() {
+  const override = process.env.CONTEXT_MODE_MCP_SENTINEL_DIR;
+  if (override && override.length > 0) return override;
+  return process.platform === "win32" ? tmpdir() : "/tmp";
+}
+
+/**
+ * Build sentinel path for a given PID.
+ * Used by server.ts to write its own sentinel.
+ */
+export function sentinelPathForPid(pid) {
+  return join(sentinelDir(), `${SENTINEL_PREFIX}${pid}`);
+}
+
+/**
+ * @deprecated Use sentinelPathForPid(process.pid) from server.ts.
+ * Kept for backward compat during migration — tests that still
+ * write sentinels with process.ppid will work for one release cycle.
+ */
+export function sentinelPath() {
+  return join(sentinelDir(), `${SENTINEL_PREFIX}${process.ppid}`);
+}
+
+/**
+ * Check if any MCP server is alive by scanning sentinel files.
+ *
+ * Scans sentinelDir() for context-mode-mcp-ready-* files, reads the PID
+ * from each, and probes with kill(pid, 0). Cleans up stale sentinels
+ * from crashed servers.
+ *
+ * Handles:
+ * - PPID mismatch (WSL2 shell wrappers) — no ppid dependency
+ * - Stale sentinels (SIGKILL, OOM) — PID liveness check + age threshold
+ * - TMPDIR mismatch — hardcoded /tmp on Unix
+ * - Shared /tmp across isolated PID namespaces (#844) — a live host PID is
+ *   invisible to `kill(pid, 0)` from a sandbox, so a recently-refreshed
+ *   sentinel is trusted instead of being deleted.
+ */
+export function isMCPReady() {
+  try {
+    const dir = sentinelDir();
+    const files = readdirSync(dir).filter(f => f.startsWith(SENTINEL_PREFIX));
+    const now = Date.now();
+    for (const f of files) {
+      const fullPath = join(dir, f);
+      let pid;
+      try {
+        pid = parseInt(readFileSync(fullPath, "utf8"), 10);
+      } catch {
+        // Unreadable (torn mid-write) — leave it for the owner / a later scan.
+        continue;
+      }
+      if (isNaN(pid)) continue;
+      try {
+        process.kill(pid, 0); // throws if the PID is not signalable from here
+        return true;          // same-namespace liveness confirmed
+      } catch (err) {
+        // EPERM: the process exists but is owned by another user → alive.
+        if (err && err.code === "EPERM") return true;
+        // ESRCH (or anything else): the PID is invisible from THIS namespace.
+        // That is NOT proof the server is dead — a shared /tmp across isolated
+        // PID namespaces (#844) hides a live host PID. Trust a recently
+        // refreshed sentinel rather than delete a live server's marker.
+        let ageMs = Infinity;
+        try { ageMs = now - statSync(fullPath).mtimeMs; } catch { /* stat failed → treat as stale */ }
+        if (ageMs < SENTINEL_FRESH_MS) return true;
+        // Old AND unprobeable → genuinely stale (crash / OOM / SIGKILL) → clean up.
+        try { unlinkSync(fullPath); } catch { /* best effort */ }
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}

package/hooks/core/platform-detect.mjs

@@ -0,0 +1,49 @@
+/**
+ * Platform detection from process env vars.
+ *
+ * Each supported platform sets a distinctive env var when invoking
+ * hook scripts; we use those to pick the correct tool-namer prefix
+ * and routing block. Falls back to "claude-code" when nothing matches
+ * so existing CC behavior is preserved.
+ *
+ * SINGLE SOURCE OF TRUTH: this table mirrors `PLATFORM_ENV_VARS` in
+ * `src/adapters/detect.ts:33-77`. Every entry has been verified against
+ * the platform's own runtime source code (full audit May 2026, see
+ * git blame). DO NOT add platform env vars here that aren't also in
+ * detect.ts — the two MUST stay in lock-step or detection will diverge
+ * between MCP-server-side and hook-script-side.
+ *
+ * Order matters — same as detect.ts. Forks listed BEFORE the fork's
+ * parent so collision detection works (e.g. cursor BEFORE vscode-copilot
+ * because Cursor inherits VSCODE_PID as a fork; antigravity BEFORE
+ * vscode-copilot for the same reason).
+ */
+
+// Mirror of `PLATFORM_ENV_VARS` in src/adapters/detect.ts:33-77.
+// Keep in lock-step. If you change one, change the other.
+const PLATFORM_ENV_VARS_MIRROR = [
+  ["claude-code",        ["CLAUDE_PROJECT_DIR", "CLAUDE_SESSION_ID"]],
+  ["antigravity",        ["ANTIGRAVITY_CLI_ALIAS"]],
+  ["cursor",             ["CURSOR_TRACE_ID", "CURSOR_CLI"]],
+  ["kilo",               ["KILO_PID"]],
+  ["opencode",           ["OPENCODE_CLIENT", "OPENCODE_TERMINAL", "OPENCODE", "OPENCODE_PID"]],
+  ["zed",                ["ZED_SESSION_ID", "ZED_TERM"]],
+  ["codex",              ["CODEX_THREAD_ID", "CODEX_CI"]],
+  ["gemini-cli",         ["GEMINI_PROJECT_DIR", "GEMINI_CLI"]],
+  ["vscode-copilot",     ["VSCODE_PID", "VSCODE_CWD"]],
+  ["jetbrains-copilot",  ["IDEA_INITIAL_DIRECTORY"]],
+  ["qwen-code",          ["QWEN_PROJECT_DIR"]],
+  ["pi",                 ["PI_PROJECT_DIR"]],
+  // openclaw — no auto-set process env vars; falls through to default
+  // kiro — no auto-set process env vars; falls through to default
+];
+
+export function detectPlatformFromEnv(env = process.env) {
+  for (const [platform, vars] of PLATFORM_ENV_VARS_MIRROR) {
+    if (vars.some((v) => env[v])) return platform;
+  }
+  return "claude-code";
+}
+
+// Re-exported for tests so they can assert against the same canonical table.
+export { PLATFORM_ENV_VARS_MIRROR };