@mxalbert/context-mode 2.0.0

package/hooks/core/stdin.mjs

@@ -0,0 +1,90 @@
+/**
+ * Shared stdin reader for all hook scripts.
+ * Cross-platform (Windows/macOS/Linux) — no bash/jq dependency.
+ *
+ * Uses event-based flowing mode to avoid two platform bugs:
+ * - `for await (process.stdin)` hangs on macOS when piped via spawnSync
+ * - `readFileSync(0)` throws EOF/EISDIR on Windows, EAGAIN on Linux
+ *
+ * Idle-timeout semantics (override via env `CONTEXT_MODE_HOOK_STDIN_IDLE_MS`,
+ * default 1500 ms):
+ * - EOF before any data → resolve("")  — the original well-behaved path.
+ * - EOF after data       → resolve(buffer) with BOM strip (#139 — Cursor on
+ *                          Windows can emit a leading U+FEFF that crashes
+ *                          downstream JSON.parse).
+ * - Idle with 0 bytes    → resolve("")  — covers hosts that hold the pipe open
+ *                          without ever closing it (issue #639 — Bun re-exec
+ *                          EOF path) so the hook still terminates.
+ * - Idle with > 0 bytes  → reject(Error) — partial data after a stall MUST NOT
+ *                          be silently truncated, otherwise downstream
+ *                          JSON.parse corrupts on large `tool_response`
+ *                          payloads (issue #242 — Gemini AfterTool >1MB).
+ *                          Visible non-zero exit is correct here; the host
+ *                          surfaces the failure in its hook diagnostics.
+ */
+
+export function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    const idleMs = Number(process.env.CONTEXT_MODE_HOOK_STDIN_IDLE_MS || 1500);
+    let done = false;
+    let timer;
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      process.stdin.removeListener("data", onData);
+      process.stdin.removeListener("end", onEnd);
+      process.stdin.removeListener("error", onError);
+      try { process.stdin.pause(); } catch {}
+      try { process.stdin.destroy?.(); } catch {}
+    };
+    const resolveBuffer = () => {
+      if (done) return;
+      done = true;
+      cleanup();
+      // Preserves #139 BOM strip \u2014 applies on both EOF and idle-empty paths.
+      resolve(data.replace(/^\uFEFF/, ""));
+    };
+    const rejectIdle = () => {
+      if (done) return;
+      done = true;
+      cleanup();
+      reject(new Error(
+        `stdin idle for ${idleMs}ms with ${data.length} bytes buffered`,
+      ));
+    };
+    const onIdle = () => {
+      // Zero-buffer idle = host never wrote anything (issue #639). Resolve
+      // empty so the hook can no-op. Non-zero buffer = partial data, which
+      // must reject to avoid silent JSON.parse corruption (issue #242).
+      if (data.length === 0) {
+        resolveBuffer();
+      } else {
+        rejectIdle();
+      }
+    };
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(onIdle, idleMs);
+      timer.unref?.();
+    };
+    const onData = (chunk) => {
+      data += chunk;
+      arm();
+    };
+    const onEnd = () => resolveBuffer();
+    const onError = (error) => {
+      if (done) return;
+      done = true;
+      cleanup();
+      reject(error);
+    };
+
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+    process.stdin.on("error", onError);
+    process.stdin.resume();
+    arm();
+  });
+}

package/hooks/core/tool-naming.mjs

@@ -0,0 +1,57 @@
+/**
+ * Platform-aware MCP tool naming.
+ * Each platform has its own convention for how MCP tool names appear to the LLM.
+ *
+ * Evidence-based naming conventions (from official docs):
+ * | Platform           | Pattern                                                    |
+ * |--------------------|------------------------------------------------------------|
+ * | Claude Code        | mcp__plugin_context-mode_context-mode__<tool>               |
+ * | Gemini CLI         | mcp__context-mode__<tool>                                  |
+ * | Antigravity        | mcp__context-mode__<tool>                                  |
+ * | Antigravity CLI    | context-mode/<tool>                                        |
+ * | OpenCode           | context-mode_<tool>                                        |
+ * | VS Code Copilot    | context-mode_<tool>                                        |
+ * | Kiro               | @context-mode/<tool>                                       |
+ * | Zed                | mcp:context-mode:<tool>                                    |
+ * | Cursor / Codex / OpenClaw / Pi | bare <tool>                                    |
+ */
+
+const TOOL_PREFIXES = {
+  "claude-code":    (tool) => `mcp__plugin_context-mode_context-mode__${tool}`,
+  "gemini-cli":     (tool) => `mcp__context-mode__${tool}`,
+  "antigravity":    (tool) => `mcp__context-mode__${tool}`,
+  "antigravity-cli": (tool) => `context-mode/${tool}`,
+  "opencode":       (tool) => `context-mode_${tool}`,
+  "kilo":           (tool) => `context-mode_${tool}`,
+  "vscode-copilot": (tool) => `context-mode_${tool}`,
+  "jetbrains-copilot": (tool) => `context-mode_${tool}`,
+  "copilot-cli":    (tool) => `context-mode_${tool}`,
+  "kiro":           (tool) => `@context-mode/${tool}`,
+  "zed":            (tool) => `mcp:context-mode:${tool}`,
+  "cursor":         (tool) => tool,
+  "codex":          (tool) => tool,
+  "kimi":           (tool) => `mcp__context-mode__${tool}`,
+  "openclaw":       (tool) => tool,
+  "pi":             (tool) => tool,
+  "qwen-code":      (tool) => `mcp__context-mode__${tool}`,
+};
+
+/**
+ * Get the platform-specific MCP tool name for a bare tool name.
+ * Falls back to claude-code convention if platform is unknown.
+ */
+export function getToolName(platform, bareTool) {
+  const fn = TOOL_PREFIXES[platform] || TOOL_PREFIXES["claude-code"];
+  return fn(bareTool);
+}
+
+/**
+ * Create a namer function bound to a specific platform.
+ * Returns (bareTool) => platformSpecificToolName.
+ */
+export function createToolNamer(platform) {
+  return (bareTool) => getToolName(platform, bareTool);
+}
+
+/** List of all known platform IDs. */
+export const KNOWN_PLATFORMS = Object.keys(TOOL_PREFIXES);

package/hooks/cursor/afteragentresponse.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Cursor afterAgentResponse hook — fires once Cursor finishes streaming
+ * the assistant turn back to the user (per Cursor v1 hook docs:
+ * https://cursor.com/docs/agent/hooks#afteragentresponse).
+ *
+ * Input:  { "conversation_id": "...", "generation_id": "...", "text": "<final assistant message>" }
+ * Output: { "additional_context": "" }  (Cursor rejects empty stdout, so emit a no-op payload)
+ *
+ * The hook records the agent_response event so session analytics + the
+ * resume directive can reconstruct the last assistant turn. Mirrors
+ * stop.mjs (turn lifecycle telemetry) — afterAgentResponse fires
+ * BEFORE stop, so we capture the produced text here while stop captures
+ * loop_count + final status.
+ */
+
+import {
+  readStdin,
+  parseStdin,
+  getSessionId,
+  getSessionDBPath,
+  getInputProjectDir,
+  CURSOR_OPTS,
+} from "../session-helpers.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createSessionLoaders } from "../session-loaders.mjs";
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
+const OPTS = CURSOR_OPTS;
+
+// Truncate large assistant responses before persisting — keeps the
+// session_events table from ballooning when an agent emits long output.
+const MAX_TEXT_BYTES = 8 * 1024;
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const projectDir = getInputProjectDir(input, CURSOR_OPTS);
+
+  if (projectDir && !process.env.CURSOR_CWD) {
+    process.env.CURSOR_CWD = projectDir;
+  }
+
+  const text = typeof input.text === "string" ? input.text : "";
+  const truncated = text.length > MAX_TEXT_BYTES
+    ? text.slice(0, MAX_TEXT_BYTES)
+    : text;
+
+  const { SessionDB } = await loadSessionDB();
+  const dbPath = getSessionDBPath(OPTS, projectDir);
+  const db = new SessionDB({ dbPath });
+  const sessionId = getSessionId(input, OPTS);
+
+  db.ensureSession(sessionId, projectDir);
+  db.insertEvent(sessionId, {
+    type: "agent_response",
+    generation_id: input.generation_id ?? null,
+    text_bytes: text.length,
+    truncated: text.length > MAX_TEXT_BYTES,
+    text: truncated,
+  }, "AfterAgentResponse");
+
+  db.close();
+} catch {
+  // Cursor treats stderr as hook failure; swallow and continue.
+}
+
+// Cursor rejects empty stdout as "no valid response", so emit a no-op
+// additional_context payload (same convention as sessionstart.mjs).
+process.stdout.write(JSON.stringify({ additional_context: "" }) + "\n");

package/hooks/cursor/hooks.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "npx -y @mxalbert/context-mode hook cursor pretooluse",
+        "matcher": "Shell|Read|Grep|WebFetch|mcp_web_fetch|mcp_fetch_tool|Task|MCP:ctx_execute|MCP:ctx_execute_file|MCP:ctx_batch_execute|MCP:(?!ctx_)"
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": "npx -y @mxalbert/context-mode hook cursor posttooluse"
+      }
+    ],
+    "sessionStart": [
+      {
+        "command": "npx -y @mxalbert/context-mode hook cursor sessionstart"
+      }
+    ],
+    "afterAgentResponse": [
+      {
+        "command": "npx -y @mxalbert/context-mode hook cursor afteragentresponse"
+      }
+    ],
+    "stop": [
+      {
+        "command": "npx -y @mxalbert/context-mode hook cursor stop"
+      }
+    ]
+  }
+}

package/hooks/cursor/posttooluse.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Cursor postToolUse hook — session event capture.
+ */
+
+import { readStdin, parseStdin, getSessionId, getSessionDBPath, getInputProjectDir, CURSOR_OPTS } from "../session-helpers.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createSessionLoaders, attributeAndInsertEvents } from "../session-loaders.mjs";
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const { loadSessionDB, loadExtract, loadProjectAttribution } = createSessionLoaders(HOOK_DIR);
+const OPTS = CURSOR_OPTS;
+
+function normalizeToolName(toolName) {
+  if (toolName === "Shell") return "Bash";
+  if (toolName === "MCP:ctx_execute") {
+    return "mcp__plugin_context-mode_context-mode__ctx_execute";
+  }
+  if (toolName === "MCP:ctx_execute_file") {
+    return "mcp__plugin_context-mode_context-mode__ctx_execute_file";
+  }
+  if (toolName === "MCP:ctx_batch_execute") {
+    return "mcp__plugin_context-mode_context-mode__ctx_batch_execute";
+  }
+  return toolName;
+}
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const projectDir = getInputProjectDir(input, CURSOR_OPTS);
+
+  if (projectDir && !process.env.CURSOR_CWD) {
+    process.env.CURSOR_CWD = projectDir;
+  }
+
+  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);
+
+  const normalizedInput = {
+    tool_name: normalizeToolName(input.tool_name ?? ""),
+    tool_input: input.tool_input ?? {},
+    tool_response: typeof input.tool_output === "string"
+      ? input.tool_output
+      : JSON.stringify(input.tool_output ?? input.error_message ?? ""),
+    tool_output: input.error_message
+      ? { isError: true }
+      : undefined,
+  };
+
+  const events = extractEvents(normalizedInput);
+
+  attributeAndInsertEvents(db, sessionId, events, input, projectDir, "PostToolUse", resolveProjectAttributions);
+
+  db.close();
+} catch {
+  // Cursor treats stderr as hook failure; swallow and continue.
+}
+
+// Cursor treats empty stdout as an invalid hook response,
+// so we emit an explicit no-op payload after persisting events.
+process.stdout.write(JSON.stringify({ additional_context: "" }) + "\n");

package/hooks/cursor/pretooluse.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import "../suppress-stderr.mjs";
+/**
+ * Cursor preToolUse hook for context-mode.
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readStdin, parseStdin, getInputProjectDir, getSessionId, CURSOR_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, CURSOR_OPTS);
+
+const decision = routePreToolUse(tool, toolInput, projectDir, "cursor", getSessionId(input, CURSOR_OPTS));
+const response = formatDecision("cursor", decision);
+// Cursor treats empty stdout as an invalid hook response,
+// so even passthrough decisions must emit a syntactically valid no-op payload.
+process.stdout.write(JSON.stringify(response ?? { agent_message: "" }) + "\n");

package/hooks/cursor/sessionstart.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Cursor sessionStart hook for context-mode.
+ */
+
+import { createRoutingBlock } from "../routing-block.mjs";
+import { createToolNamer } from "../core/tool-naming.mjs";
+
+const toolNamer = createToolNamer("cursor");
+const ROUTING_BLOCK = createRoutingBlock(toolNamer);
+import {
+  writeSessionEventsFile,
+  buildSessionDirective,
+  getSessionEvents,
+} from "../session-directive.mjs";
+import {
+  readStdin,
+  parseStdin,
+  getSessionId,
+  getSessionDBPath,
+  getSessionEventsPath,
+  getCleanupFlagPath,
+  getInputProjectDir,
+  CURSOR_OPTS,
+} from "../session-helpers.mjs";
+import { unlinkSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createSessionLoaders } from "../session-loaders.mjs";
+
+const HOOK_DIR = fileURLToPath(new URL(".", import.meta.url));
+const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
+const OPTS = CURSOR_OPTS;
+
+let additionalContext = ROUTING_BLOCK;
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const source = input.source ?? input.trigger ?? "startup";
+  const projectDir = getInputProjectDir(input, CURSOR_OPTS);
+
+  if (projectDir && !process.env.CURSOR_CWD) {
+    process.env.CURSOR_CWD = projectDir;
+  }
+
+  if (source === "compact" || source === "resume") {
+    const { SessionDB } = await loadSessionDB();
+    const dbPath = getSessionDBPath(OPTS, projectDir);
+    const db = new SessionDB({ dbPath });
+
+    if (source === "compact") {
+      const sessionId = getSessionId(input, OPTS);
+      const resume = db.getResume(sessionId);
+      if (resume && !resume.consumed) {
+        db.markResumeConsumed(sessionId);
+      }
+    } else {
+      try { unlinkSync(getCleanupFlagPath(OPTS, projectDir)); } catch { /* no flag */ }
+    }
+
+    // Filter events to the session being resumed/compacted. Falling back to
+    // getLatestSessionEvents(db) for resume leaks events from any other
+    // session whose session_meta.started_at is more recent — observed
+    // cross-session bleed when a different session started after this one
+    // and before the resume.
+    const sessionId = getSessionId(input, OPTS);
+    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 if (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);
+    db.db.exec(`DELETE FROM session_events WHERE session_id NOT IN (SELECT session_id FROM session_meta)`);
+
+    const sessionId = getSessionId(input, OPTS);
+    db.ensureSession(sessionId, projectDir);
+
+    db.close();
+  }
+  // clear => routing block only
+} catch {
+  // Cursor treats stderr as hook failure; swallow and continue.
+}
+
+// Cursor treats empty stdout as an invalid hook response,
+// so SessionStart always emits an explicit additional_context payload.
+process.stdout.write(JSON.stringify({ additional_context: additionalContext }) + "\n");

package/hooks/cursor/stop.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import "../suppress-stderr.mjs";
+import "../ensure-deps.mjs";
+/**
+ * Cursor stop hook — fires when the agent turn ends.
+ *
+ * Input:  { "conversation_id": "...", "status": "completed"|"error", "loop_count": N, "transcript_path": "..." }
+ * Output: { "followup_message": "" }  (empty = don't continue the loop)
+ */
+
+import { readStdin, parseStdin, getSessionId, getSessionDBPath, getInputProjectDir, CURSOR_OPTS } from "../session-helpers.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createSessionLoaders } from "../session-loaders.mjs";
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
+const OPTS = CURSOR_OPTS;
+
+try {
+  const raw = await readStdin();
+  const input = parseStdin(raw);
+  const projectDir = getInputProjectDir(input, CURSOR_OPTS);
+
+  if (projectDir && !process.env.CURSOR_CWD) {
+    process.env.CURSOR_CWD = projectDir;
+  }
+
+  const { SessionDB } = await loadSessionDB();
+
+  const dbPath = getSessionDBPath(OPTS, projectDir);
+  const db = new SessionDB({ dbPath });
+  const sessionId = getSessionId(input, OPTS);
+
+  db.ensureSession(sessionId, projectDir);
+  db.insertEvent(sessionId, {
+    type: "session_end",
+    status: input.status ?? "completed",
+    loop_count: input.loop_count ?? 0,
+  }, "Stop");
+
+  db.close();
+} catch {
+  // Cursor treats stderr as hook failure; swallow and continue.
+}
+
+// Emit empty followup — don't continue the agent loop.
+process.stdout.write(JSON.stringify({ followup_message: "" }) + "\n");