@danielblomma/cortex-mcp 1.7.1 → 2.0.2

package/scaffold/mcp/src/hooks/session-end.ts

@@ -0,0 +1,73 @@
+import { call } from "../daemon/client.js";
+import type {
+  AuditLogPayload,
+  AuditLogResult,
+  TelemetryFlushPayload,
+  TelemetryFlushResult,
+} from "../daemon/protocol.js";
+import {
+  ensureDaemon,
+  parseInput,
+  readStdin,
+  resolveDaemonEntry,
+  sendHeartbeat,
+} from "./shared.js";
+
+/**
+ * SessionEnd hook. Final telemetry push + audit log when Claude Code's
+ * session terminates entirely (more authoritative than Stop, which fires
+ * each turn).
+ */
+
+type ClaudeSessionEndInput = {
+  session_id?: string;
+  cwd?: string;
+};
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  const input = parseInput(raw) as ClaudeSessionEndInput;
+  const cwd = input.cwd ?? process.cwd();
+
+  ensureDaemon(resolveDaemonEntry(import.meta.url));
+
+  // Audit first — even if telemetry push fails, we want the session-end
+  // record locally so cortex-web can later derive missing data.
+  const auditPayload: AuditLogPayload = {
+    cwd,
+    entry: {
+      timestamp: new Date().toISOString(),
+      tool: "session.end",
+      input: { session_id: input.session_id ?? null },
+      event_type: "session",
+      evidence_level: "diagnostic",
+      resource_type: "session",
+      session_id: input.session_id,
+    },
+  };
+  await call<AuditLogResult>("audit.log", auditPayload, { timeoutMs: 3000 });
+
+  // Final flush — best-effort, may have nothing on disk if MCP already
+  // flushed during shutdown.
+  const flushPayload: TelemetryFlushPayload = {
+    reason: "session_end",
+    session_id: input.session_id,
+    cwd,
+  };
+  await call<TelemetryFlushResult>("telemetry.flush", flushPayload, {
+    timeoutMs: 5000,
+  });
+
+  if (input.session_id) {
+    await sendHeartbeat({
+      cli: "claude",
+      hook: "SessionEnd",
+      session_id: input.session_id,
+      cwd,
+    });
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/scaffold/mcp/src/hooks/session-start.ts

@@ -0,0 +1,78 @@
+import { call } from "../daemon/client.js";
+import type { AuditLogPayload, AuditLogResult } from "../daemon/protocol.js";
+import {
+  ensureDaemon,
+  isEnforcedMode,
+  parseInput,
+  readStdin,
+  readTamperLockJson,
+  resolveDaemonEntry,
+  sendHeartbeat,
+} from "./shared.js";
+
+/**
+ * SessionStart hook for Claude Code.
+ *
+ * Phase 6 additions:
+ *  - In enforced mode, refuses session start if a tamper-lock exists.
+ *    The user must run `cortex enterprise repair` (sudo) to clear it.
+ *  - Always sends a heartbeat so the daemon's tamper-tracker can spot
+ *    silent post-startup hook removal.
+ *
+ * Audit/telemetry/heartbeat failures must never block legitimate session
+ * startup — only the explicit tamper-lock check does.
+ */
+
+type ClaudeSessionStartInput = {
+  session_id?: string;
+  cwd?: string;
+};
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  const input = parseInput(raw) as ClaudeSessionStartInput;
+  const cwd = input.cwd ?? process.cwd();
+  const sessionId = input.session_id ?? "";
+
+  // Tamper-lock check happens BEFORE we spawn the daemon. We don't want
+  // a tampered project to keep getting fresh daemons started.
+  const lock = readTamperLockJson(cwd);
+  if (lock && isEnforcedMode(cwd)) {
+    process.stderr.write(
+      "[cortex] Govern enforced: session blocked because hook tampering was detected.\n" +
+        "        Run 'sudo cortex enterprise repair' to verify managed-settings\n" +
+        "        integrity and clear .context/.cortex-tamper.lock, then retry.\n",
+    );
+    process.exit(2);
+  }
+
+  ensureDaemon(resolveDaemonEntry(import.meta.url));
+
+  const payload: AuditLogPayload = {
+    cwd,
+    entry: {
+      timestamp: new Date().toISOString(),
+      tool: "session.start",
+      input: { session_id: sessionId || null },
+      event_type: "session",
+      evidence_level: "diagnostic",
+      resource_type: "session",
+      session_id: sessionId,
+    },
+  };
+
+  await call<AuditLogResult>("audit.log", payload, { timeoutMs: 3000 });
+
+  if (sessionId) {
+    await sendHeartbeat({
+      cli: "claude",
+      hook: "SessionStart",
+      session_id: sessionId,
+      cwd,
+    });
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/scaffold/mcp/src/hooks/shared.ts

@@ -0,0 +1,134 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { call, isDaemonRunning, spawnDaemon } from "../daemon/client.js";
+import { fileURLToPath } from "node:url";
+import type { HeartbeatPayload, HeartbeatResult } from "../daemon/protocol.js";
+
+/**
+ * Shared utilities for hook scripts.
+ *
+ * Hook flow (Claude Code spec):
+ *   1. Claude Code spawns the hook script with input JSON on stdin
+ *   2. Hook reads stdin, makes a decision
+ *   3. Hook prints JSON to stdout (or exits non-zero to block)
+ *   4. exit 0 = allow, exit 2 = block, other non-zero = error
+ */
+
+export type HookInput = {
+  // Claude Code's documented hook input shape — varies by hook type.
+  // We read it as a generic record and let the hook narrow.
+  [key: string]: unknown;
+};
+
+export async function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    // If stdin is a TTY (running interactively for testing), don't hang.
+    if (process.stdin.isTTY) resolve("");
+  });
+}
+
+export function parseInput(raw: string): HookInput {
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw) as HookInput;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Detect whether the current project is running enterprise mode.
+ * Lightweight YAML peek — we don't want to load the full config parser
+ * on every hook invocation.
+ */
+export function isEnterpriseProject(cwd: string): boolean {
+  const candidates = [
+    join(cwd, ".context", "enterprise.yml"),
+    join(cwd, ".context", "enterprise.yaml"),
+  ];
+  for (const path of candidates) {
+    if (!existsSync(path)) continue;
+    try {
+      const raw = readFileSync(path, "utf8");
+      // Look for an api_key under enterprise: section.
+      // Conservative: any non-empty api_key value implies "intent to be enterprise".
+      const match = raw.match(/^\s*api_key:\s*(\S.*?)\s*$/m);
+      if (match && match[1] && match[1] !== "") return true;
+    } catch {
+      // ignore
+    }
+  }
+  return false;
+}
+
+export function ensureDaemon(daemonEntry: string): void {
+  if (isDaemonRunning()) return;
+  spawnDaemon(daemonEntry);
+}
+
+/**
+ * Resolve daemon entry script path relative to this hook script's location.
+ * Hooks live at dist/hooks/<name>.js, daemon at dist/daemon/main.js.
+ */
+export function resolveDaemonEntry(hookFileUrl: string): string {
+  const hookPath = fileURLToPath(hookFileUrl);
+  // dist/hooks/<x>.js → dist/daemon/main.js
+  return join(hookPath, "..", "..", "daemon", "main.js");
+}
+
+/**
+ * Send a heartbeat to the daemon for tamper-detection bookkeeping.
+ * Failure to reach the daemon is non-fatal — daemon-down is treated as
+ * "we don't know" rather than tamper. Returns whether the daemon
+ * reported an active tamper-lock for this cwd.
+ */
+export async function sendHeartbeat(
+  payload: Omit<HeartbeatPayload, "ts">,
+): Promise<{ tamperLockActive: boolean }> {
+  const result = await call<HeartbeatResult>(
+    "heartbeat",
+    { ...payload, ts: new Date().toISOString() } satisfies HeartbeatPayload,
+    { timeoutMs: 1500 },
+  );
+  if (!result.ok) return { tamperLockActive: false };
+  return { tamperLockActive: result.result.tamper_lock_active === true };
+}
+
+const TAMPER_LOCK_FILENAME = ".cortex-tamper.lock";
+
+export function readTamperLockJson(cwd: string): unknown | null {
+  const path = join(cwd, ".context", TAMPER_LOCK_FILENAME);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True iff this cwd is in enforced govern mode. Reads govern.local.json,
+ * which is written by the install/install-flow. We don't fall back to
+ * enterprise.yml because the user's intent is captured at install time.
+ */
+export function isEnforcedMode(cwd: string): boolean {
+  const path = join(cwd, ".context", "govern.local.json");
+  if (!existsSync(path)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as {
+      installs?: Record<string, { mode?: string }>;
+    };
+    for (const inst of Object.values(parsed.installs ?? {})) {
+      if (inst.mode === "enforced") return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}

package/scaffold/mcp/src/hooks/stop.ts

@@ -0,0 +1,60 @@
+import { call } from "../daemon/client.js";
+import type { TelemetryFlushPayload, TelemetryFlushResult } from "../daemon/protocol.js";
+import {
+  ensureDaemon,
+  parseInput,
+  readStdin,
+  resolveDaemonEntry,
+} from "./shared.js";
+
+/**
+ * Stop hook for Claude Code.
+ *
+ * Fires when Claude finishes responding. We use this to guarantee a
+ * telemetry flush — historically metrics.json was lost when MCP exited
+ * abruptly. The Stop hook runs in Claude Code's process tree, not the
+ * MCP server's, so it survives MCP shutdown.
+ *
+ * Always exits 0 — telemetry failures must never block the user.
+ */
+
+type ClaudeStopInput = {
+  session_id?: string;
+  cwd?: string;
+};
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  const input = parseInput(raw) as ClaudeStopInput;
+
+  ensureDaemon(resolveDaemonEntry(import.meta.url));
+
+  const payload: TelemetryFlushPayload = {
+    reason: "stop",
+    session_id: input.session_id,
+    cwd: input.cwd ?? process.cwd(),
+  };
+
+  const res = await call<TelemetryFlushResult>("telemetry.flush", payload, {
+    timeoutMs: 5000,
+  });
+
+  if (res.ok && res.result.flushed) {
+    process.stderr.write(
+      `[cortex] Telemetry flushed: ${res.result.events_pushed} events\n`,
+    );
+  } else if (!res.ok) {
+    // Best-effort: silent in normal output. Daemon-reachability is logged
+    // through other channels (PreToolUse warnings, daemon log).
+    process.stderr.write(
+      `[cortex] Telemetry flush skipped: ${res.error}\n`,
+    );
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => {
+  // Telemetry must never block. Swallow all errors.
+  process.exit(0);
+});

package/scaffold/mcp/src/hooks/user-prompt-submit.ts

@@ -0,0 +1,64 @@
+import { call } from "../daemon/client.js";
+import type { AuditLogPayload, AuditLogResult } from "../daemon/protocol.js";
+import {
+  ensureDaemon,
+  parseInput,
+  readStdin,
+  resolveDaemonEntry,
+  sendHeartbeat,
+} from "./shared.js";
+
+/**
+ * UserPromptSubmit hook. Fires when the user submits a prompt to Claude.
+ *
+ * v2.0.0 MVP: logs the event for audit. A future commit will use this
+ * hook to inject mandatory rules / ADRs as system context so Claude
+ * cannot proceed without seeing them.
+ */
+
+type ClaudeUserPromptInput = {
+  session_id?: string;
+  cwd?: string;
+  // Claude passes the prompt — we only log length, not contents, to
+  // avoid logging sensitive user input by default.
+  prompt?: string;
+};
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  const input = parseInput(raw) as ClaudeUserPromptInput;
+  const cwd = input.cwd ?? process.cwd();
+
+  ensureDaemon(resolveDaemonEntry(import.meta.url));
+
+  const promptLen = typeof input.prompt === "string" ? input.prompt.length : 0;
+
+  const payload: AuditLogPayload = {
+    cwd,
+    entry: {
+      timestamp: new Date().toISOString(),
+      tool: "user.prompt",
+      input: { prompt_length: promptLen },
+      event_type: "session",
+      evidence_level: "diagnostic",
+      resource_type: "user_input",
+      session_id: input.session_id,
+      metadata: { prompt_length: promptLen },
+    },
+  };
+
+  await call<AuditLogResult>("audit.log", payload, { timeoutMs: 3000 });
+
+  if (input.session_id) {
+    await sendHeartbeat({
+      cli: "claude",
+      hook: "UserPromptSubmit",
+      session_id: input.session_id,
+      cwd,
+    });
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/scaffold/mcp/src/plugin.ts

@@ -0,0 +1,150 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export type ToolCallHook = (toolName: string, resultCount: number, tokensSaved: number) => void;
+
+export type ToolExecutionPhase = "start" | "success" | "error";
+
+export type ToolExecutionEvent = {
+  phase: ToolExecutionPhase;
+  tool: string;
+  timestamp: string;
+  input: Record<string, unknown>;
+  query?: string;
+  query_length?: number;
+  result_count?: number;
+  estimated_tokens_saved?: number;
+  entities_returned?: string[];
+  rules_applied?: string[];
+  duration_ms?: number;
+  error?: string;
+};
+
+export type SessionCallRecord = {
+  tool: string;
+  query?: string;
+  resultCount: number;
+  time: string;
+  outcome?: "success" | "error";
+  duration_ms?: number;
+  error?: string;
+};
+
+export type SessionEndHook = (calls: SessionCallRecord[]) => Promise<void>;
+
+export type SessionPhase = "start" | "end";
+
+export type SessionEvent = {
+  phase: SessionPhase;
+  timestamp: string;
+  duration_ms?: number;
+  tool_calls?: number;
+  successful_tool_calls?: number;
+  failed_tool_calls?: number;
+  calls?: SessionCallRecord[];
+};
+
+export type ToolEventHook = (event: ToolExecutionEvent) => void | Promise<void>;
+export type SessionEventHook = (event: SessionEvent) => void | Promise<void>;
+
+export type CortexPlugin = {
+  name: string;
+  version: string;
+  register: (server: McpServer) => void | Promise<void>;
+  onToolCall?: ToolCallHook;
+  onSessionEnd?: SessionEndHook;
+  onToolEvent?: ToolEventHook;
+  onSessionEvent?: SessionEventHook;
+};
+
+export type EditionInfo = {
+  edition: "community" | "enterprise";
+  name?: string;
+  version?: string;
+};
+
+let loadedEdition: EditionInfo = { edition: "community" };
+let toolCallHook: ToolCallHook | null = null;
+let sessionEndHook: SessionEndHook | null = null;
+let toolEventHook: ToolEventHook | null = null;
+let sessionEventHook: SessionEventHook | null = null;
+
+export function getEdition(): EditionInfo {
+  return loadedEdition;
+}
+
+export function getToolCallHook(): ToolCallHook | null {
+  return toolCallHook;
+}
+
+export function getSessionEndHook(): SessionEndHook | null {
+  return sessionEndHook;
+}
+
+export function getToolEventHook(): ToolEventHook | null {
+  return toolEventHook;
+}
+
+export function getSessionEventHook(): SessionEventHook | null {
+  return sessionEventHook;
+}
+
+export async function loadPlugins(server: McpServer): Promise<void> {
+  // v2.0.0: enterprise is now in-process. We still gate registration on
+  // whether enterprise activation succeeds (license + config), so community
+  // users get a no-op when no api_key is present.
+  try {
+    const enterprise = await import("./enterprise/index.js");
+    const { resolveEnterpriseActivation, loadEnterpriseConfig } = await import("./core/config.js");
+    const path = await import("node:path");
+    const projectRoot = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+    const contextDir = path.join(projectRoot, ".context");
+    const config = loadEnterpriseConfig(contextDir);
+    const activation = resolveEnterpriseActivation(config);
+
+    if (!activation.active) {
+      // Community mode: no api_key or invalid config. Skip registration.
+      return;
+    }
+
+    // v2.0.0: validate license against cortex-web before activating.
+    // The verifier uses 24h cache + 7d grace period so transient endpoint
+    // outages don't degrade enterprise users immediately.
+    const { verifyLicense } = await import("./core/license.js");
+    const license = await verifyLicense(contextDir, config.enterprise.endpoint, config.enterprise.api_key, {
+      client_version: process.env.CORTEX_VERSION,
+    });
+
+    if (!license.valid) {
+      process.stderr.write(
+        `[cortex] Enterprise inactive: license check failed (${license.reason}, source=${license.source})\n`
+      );
+      return;
+    }
+
+    if (typeof enterprise.register === "function") {
+      await enterprise.register(server);
+      loadedEdition = {
+        edition: "enterprise",
+        name: enterprise.name ?? "enterprise",
+        version: enterprise.version ?? "unknown",
+      };
+      if (typeof enterprise.onToolCall === "function") {
+        toolCallHook = enterprise.onToolCall;
+      }
+      if (typeof enterprise.onSessionEnd === "function") {
+        sessionEndHook = enterprise.onSessionEnd;
+      }
+      if (typeof enterprise.onToolEvent === "function") {
+        toolEventHook = enterprise.onToolEvent;
+      }
+      if (typeof enterprise.onSessionEvent === "function") {
+        sessionEventHook = enterprise.onSessionEvent;
+      }
+      process.stderr.write(`[cortex] Enterprise loaded: ${loadedEdition.version}\n`);
+    }
+  } catch (error: unknown) {
+    process.stderr.write(
+      `[cortex] Enterprise activation failed: ${error instanceof Error ? error.message : "unknown error"}\n`
+    );
+  }
+}