feat(cursor): add IDE abstraction layer and Cursor hook adapter

Phase 1 / 3 of cursor-full-support series — purely additive abstractions
that let later PRs ship Cursor setup writers and a Cursor SDK adapter
without re-touching the hook hot path.

- New src/utils/ide-detect.ts: IdeKind type + parseIdeFlag(argv) +
  detectIdeFromEnv + detectIdeFromHookStdin + resolveIde precedence
  (argv → env → stdin heuristic → claude-code default).
- New src/hooks/adapters/{types,claude-code,cursor}.ts: NormalizedHookEvent
  + HookInputAdapter / HookOutputAdapter contracts; per-IDE stdin parsers
  (Cursor: conversation_id, cursor_version, transcript_path|null);
  per-IDE deny emitters (Claude: hookSpecificOutput JSON, exit 0;
  Cursor: flat permission/user_message JSON, exit 2).
- Refactor src/hooks/{pre,post,session-end}.ts to consume
  NormalizedHookEvent + a HookOutputAdapter. Safety-checking core in
  pre-tool-use.ts is byte-identical for Claude Code users.
- src/cli.ts case "hook" now parses --ide and forwards into the right
  adapter; defaults to claude-code so existing setups are unaffected.
- src/audit-spawner.ts forwards --ide to the detached worker argv (used
  by PR-3 to dispatch the correct transcript parser).
- src/types.ts: add IdeKind type; ClaudeSessionRef gains optional
  ide?: IdeKind. ensureAxmeSessionForClaude / attachClaudeSession in
  src/storage/sessions.ts thread the optional ide param through.

Tests (+30): test/ide-detect.test.ts covers flag/env/stdin precedence;
test/cursor-hook-adapter.test.ts covers Cursor stdin parsing (incl.
session_id vs conversation_id selection per hook kind, transcript_path
null-preservation) and exit-code-2 deny emission; test/
claude-code-hook-adapter.test.ts asserts byte-for-byte regression of
the existing deny JSON.

Full suite: 572 / 572 (was 542). tsc --noEmit clean. npm run build
clean. No behaviour change for Claude Code users.

Decisions: D-145 (Phase 1 ships before VS Code Extension). Memories
saved: cursor-sdk-system-prompt-via-inline-agent-definition,
cursor-hook-protocol-exit-code-2-deny, cursor-sdk-1-0-12-no-win-arm64,
cursor-agent-transcript-format-jsonl-with-top-level-role.

#!axme pr=none repo=AxmeAI/axme-code

Author: George-iam

src/audit-spawner.ts

@@ -30,6 +30,7 @@ import { openSync, closeSync } from "node:fs";
 import { join } from "node:path";
 import { ensureDir } from "./storage/engine.js";
 import { AXME_CODE_DIR } from "./types.js";
+import type { IdeKind } from "./types.js";
 
 const AUDIT_WORKER_LOGS_DIR = "audit-worker-logs";
 
@@ -49,7 +50,14 @@ const AUDIT_WORKER_LOGS_DIR = "audit-worker-logs";
  *     parent may be exiting imminently and holding a pipe fd open would
  *     kill the writer once the reader closes)
  */
-export function spawnDetachedAuditWorker(workspacePath: string, sessionId: string): void {
+export function spawnDetachedAuditWorker(
+  workspacePath: string,
+  sessionId: string,
+  /** Which IDE produced this session — forwarded to the worker so the
+   *  auditor can dispatch the right transcript parser. Optional for
+   *  backward compatibility; absent value means "claude-code". */
+  ide?: IdeKind,
+): void {
   const logsDir = join(workspacePath, AXME_CODE_DIR, AUDIT_WORKER_LOGS_DIR);
   ensureDir(logsDir);
   const logPath = join(logsDir, `${sessionId}.log`);
@@ -62,9 +70,11 @@ export function spawnDetachedAuditWorker(workspacePath: string, sessionId: strin
   try {
     const cliPath = process.argv[1];
     if (!cliPath) throw new Error("audit-spawner: cannot determine CLI path from process.argv[1]");
+    const argv: string[] = [cliPath, "audit-session", "--workspace", workspacePath, "--session", sessionId];
+    if (ide) argv.push("--ide", ide);
     const child = spawn(
       process.execPath,
-      [cliPath, "audit-session", "--workspace", workspacePath, "--session", sessionId],
+      argv,
       {
         detached: true,
         stdio: ["ignore", fd, fd],
@@ -73,7 +83,7 @@ export function spawnDetachedAuditWorker(workspacePath: string, sessionId: strin
     );
     child.unref();
     process.stderr.write(
-      `AXME: spawned detached audit worker pid=${child.pid} session=${sessionId} log=${logPath}\n`,
+      `AXME: spawned detached audit worker pid=${child.pid} session=${sessionId} ide=${ide ?? "claude-code"} log=${logPath}\n`,
     );
   } finally {
     // The child now holds its own dup of the fd; we can close our copy.

src/cli.ts

@@ -558,16 +558,19 @@ async function main() {
       // Parse --workspace flag from CLI args
       const wsIdx = args.indexOf("--workspace");
       const workspacePath = wsIdx >= 0 && args[wsIdx + 1] ? args[wsIdx + 1] : undefined;
+      // Parse --ide flag from CLI args (defaults to claude-code).
+      const { parseIdeFlag } = await import("./utils/ide-detect.js");
+      const ide = parseIdeFlag(args) ?? "claude-code";
 
       if (hookName === "pre-tool-use") {
         const { runPreToolUseHook } = await import("./hooks/pre-tool-use.js");
-        await runPreToolUseHook(workspacePath);
+        await runPreToolUseHook(workspacePath, ide);
       } else if (hookName === "post-tool-use") {
         const { runPostToolUseHook } = await import("./hooks/post-tool-use.js");
-        await runPostToolUseHook(workspacePath);
+        await runPostToolUseHook(workspacePath, ide);
       } else if (hookName === "session-end") {
         const { runSessionEndHook } = await import("./hooks/session-end.js");
-        await runSessionEndHook(workspacePath);
+        await runSessionEndHook(workspacePath, ide);
       }
       break;
     }

src/hooks/adapters/claude-code.ts

@@ -0,0 +1,55 @@
+/**
+ * Claude Code hook adapter.
+ *
+ * Stdin shape (per Anthropic's hooks API):
+ *   { tool_name, tool_input, session_id?, transcript_path? }
+ *
+ * Deny is signalled by writing a JSON object to stdout and exiting 0. Exit
+ * codes are not used to convey allow/deny; only the JSON payload matters:
+ *
+ *   { hookSpecificOutput: { hookEventName, permissionDecision, permissionDecisionReason } }
+ */
+
+import type { HookInputAdapter, HookKind, HookOutputAdapter, NormalizedHookEvent, DenyResult } from "./types.js";
+
+function pascalCaseFor(kind: HookKind): string {
+  switch (kind) {
+    case "preToolUse": return "PreToolUse";
+    case "postToolUse": return "PostToolUse";
+    case "sessionEnd": return "SessionEnd";
+  }
+}
+
+export const claudeCodeInputAdapter: HookInputAdapter = {
+  parse(raw, kind): NormalizedHookEvent {
+    const obj = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+    const toolName = typeof obj.tool_name === "string" ? obj.tool_name : undefined;
+    const toolInput = (obj.tool_input && typeof obj.tool_input === "object")
+      ? obj.tool_input as Record<string, unknown>
+      : undefined;
+    const sessionId = typeof obj.session_id === "string" ? obj.session_id : undefined;
+    const transcriptPath = typeof obj.transcript_path === "string" ? obj.transcript_path : undefined;
+    return {
+      kind,
+      ide: "claude-code",
+      toolName,
+      toolInput,
+      sessionId,
+      transcriptPath,
+      raw: obj,
+    };
+  },
+};
+
+export const claudeCodeOutputAdapter: HookOutputAdapter = {
+  emitDeny(reason, kind): DenyResult {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: pascalCaseFor(kind),
+        permissionDecision: "deny",
+        permissionDecisionReason: `[AXME Safety] ${reason}`,
+      },
+    };
+    return { stdout: JSON.stringify(output), exitCode: 0 };
+  },
+};

src/hooks/adapters/cursor.ts

@@ -0,0 +1,84 @@
+/**
+ * Cursor hook adapter.
+ *
+ * Stdin shape (verified against cursor.com/docs/agent/hooks, 2026-05):
+ *   common base fields:
+ *     conversation_id, generation_id, model, hook_event_name,
+ *     cursor_version, workspace_roots[], user_email?, transcript_path|null
+ *   preToolUse / postToolUse add:
+ *     tool_name, tool_input, tool_use_id, cwd, agent_message
+ *   sessionEnd adds:
+ *     session_id, reason ("completed"|"aborted"|"error"|"window_close"|...),
+ *     duration_ms, is_background_agent, final_status, error_message?
+ *
+ * Deny on preToolUse / beforeShellExecution / beforeMCPExecution:
+ *   stdout JSON: { permission: "allow"|"deny"|"ask", user_message, agent_message, updated_input? }
+ *   exit code 0 = success, 2 = deny, other = fail-open
+ */
+
+import type { HookInputAdapter, HookKind, HookOutputAdapter, NormalizedHookEvent, DenyResult } from "./types.js";
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+function asObject(v: unknown): Record<string, unknown> | undefined {
+  return v && typeof v === "object" && !Array.isArray(v)
+    ? v as Record<string, unknown>
+    : undefined;
+}
+
+export const cursorInputAdapter: HookInputAdapter = {
+  parse(raw, kind): NormalizedHookEvent {
+    const obj = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+    const toolName = asString(obj.tool_name);
+    const toolInput = asObject(obj.tool_input);
+
+    // Pre/postToolUse: Cursor identifies the running session via
+    // conversation_id (per-conversation) + generation_id (per-turn).
+    // Use conversation_id as the stable session id so consecutive tool calls
+    // in the same conversation route to the same AXME session.
+    // sessionEnd: Cursor sends a top-level session_id that may differ from
+    // conversation_id (it identifies the SDK session, not the chat).
+    let sessionId: string | undefined;
+    if (kind === "sessionEnd") {
+      sessionId = asString(obj.session_id) ?? asString(obj.conversation_id);
+    } else {
+      sessionId = asString(obj.conversation_id) ?? asString(obj.session_id);
+    }
+
+    // transcript_path may legitimately be null on Cursor (e.g. very first
+    // turn). Preserve null so callers can distinguish "no transcript yet"
+    // from "field absent".
+    let transcriptPath: string | null | undefined;
+    if (obj.transcript_path === null) transcriptPath = null;
+    else transcriptPath = asString(obj.transcript_path);
+
+    const reason = kind === "sessionEnd" ? asString(obj.reason) : undefined;
+
+    return {
+      kind,
+      ide: "cursor",
+      toolName,
+      toolInput,
+      sessionId,
+      transcriptPath,
+      reason,
+      raw: obj,
+    };
+  },
+};
+
+export const cursorOutputAdapter: HookOutputAdapter = {
+  emitDeny(reason, _kind): DenyResult {
+    const message = `[AXME Safety] ${reason}`;
+    const output = {
+      permission: "deny",
+      user_message: message,
+      agent_message: message,
+    };
+    // Exit code 2 is Cursor's documented "deny" signal; the JSON body is
+    // also required so Cursor's UI shows the reason. Both must agree.
+    return { stdout: JSON.stringify(output), exitCode: 2 };
+  },
+};

src/hooks/adapters/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared types for IDE-specific hook input parsers and deny-output emitters.
+ *
+ * Both Claude Code and Cursor hooks deliver per-event JSON to the hook
+ * subprocess on stdin, but the field names, the deny-response shape, and the
+ * exit-code semantics differ. The adapter pattern keeps the safety-checking
+ * core logic in pre-tool-use.ts byte-identical across IDEs and isolates the
+ * IDE-specific shapes here.
+ */
+
+import type { IdeKind } from "../../types.js";
+
+export type HookKind = "preToolUse" | "postToolUse" | "sessionEnd";
+
+/**
+ * The IDE-agnostic shape of a hook event after parsing. Hook handlers in
+ * src/hooks/* read from this type instead of touching raw IDE-specific keys.
+ */
+export interface NormalizedHookEvent {
+  kind: HookKind;
+  ide: IdeKind;
+  /** PreToolUse / PostToolUse only — the tool the agent is about to run. */
+  toolName?: string;
+  /** PreToolUse / PostToolUse only — the arguments the agent passed. */
+  toolInput?: Record<string, unknown>;
+  /** IDE's own session id (Claude Code session_id, Cursor session_id, etc.). */
+  sessionId?: string;
+  /** Path to the IDE's transcript file, if any. May be null on Cursor. */
+  transcriptPath?: string | null;
+  /** SessionEnd only — Cursor reports a `reason` (completed/aborted/...). */
+  reason?: string;
+  /** The original parsed JSON, for debug logging or fallback inspection. */
+  raw: Record<string, unknown>;
+}
+
+/** Parses a raw stdin JSON value into a NormalizedHookEvent. */
+export interface HookInputAdapter {
+  parse(raw: unknown, kind: HookKind): NormalizedHookEvent;
+}
+
+/** Result of an IDE-specific deny: stdout payload + exit code to use. */
+export interface DenyResult {
+  stdout: string;
+  exitCode: number;
+}
+
+/** Emits a deny response in the IDE's native protocol. */
+export interface HookOutputAdapter {
+  emitDeny(reason: string, kind: HookKind): DenyResult;
+}

src/hooks/post-tool-use.ts

@@ -1,42 +1,48 @@
 /**
- * PostToolUse hook - runs after Edit/Write tool calls.
+ * PostToolUse hook — runs after Edit/Write tool calls.
  *
- * Tracks filesChanged in session metadata, and attaches the Claude Code
- * session (session_id + transcript_path from the hook event) to the current
- * AXME session so the LLM auditor can later read the full transcript.
+ * Tracks filesChanged in session metadata, and attaches the IDE's session
+ * (id + transcript_path from the hook event) to the current AXME session
+ * so the LLM auditor can later read the full transcript.
  *
- * Input: JSON on stdin from Claude Code hooks system.
- * Workspace path: passed via --workspace flag (hardcoded at setup time).
+ * Input: JSON on stdin from the IDE's hooks system. Stdin shape varies by
+ * IDE (Claude Code vs Cursor); the adapter in src/hooks/adapters/ handles
+ * the per-IDE field renames before the handler core runs.
  *
- * Session ID: read from .axme-code/active-session (written by MCP server),
- * NOT from Claude Code's session_id (which is a different ID).
+ * Session ID: read from `.axme-code/active-sessions/<ide-session-id>.txt`
+ * (written by MCP server / earlier hooks), NOT from the IDE's session id
+ * directly (which is a different ID space).
  */
 
 import { trackFileChanged, ensureAxmeSessionForClaude } from "../storage/sessions.js";
 import { pathExists } from "../storage/engine.js";
 import { join } from "node:path";
 import { AXME_CODE_DIR } from "../types.js";
+import type { IdeKind } from "../types.js";
+import { claudeCodeInputAdapter } from "./adapters/claude-code.js";
+import { cursorInputAdapter } from "./adapters/cursor.js";
+import type { HookInputAdapter, NormalizedHookEvent } from "./adapters/types.js";
 
-interface HookInput {
-  tool_name: string;
-  tool_input: Record<string, any>;
-  session_id?: string;
-  transcript_path?: string;
+function inputAdapterFor(ide: IdeKind): HookInputAdapter {
+  return ide === "cursor" ? cursorInputAdapter : claudeCodeInputAdapter;
 }
 
-function handlePostToolUse(workspacePath: string, event: HookInput): void {
-  const { tool_name, tool_input } = event;
+function handlePostToolUse(workspacePath: string, event: NormalizedHookEvent): void {
+  const tool_name = event.toolName ?? "";
+  const tool_input = (event.toolInput ?? {}) as Record<string, any>;
 
   if (!pathExists(join(workspacePath, AXME_CODE_DIR))) return;
 
   // Ensure the AXME session exists for this Claude session_id (lazy creation).
   // Without session_id we cannot route this hook call — silently skip.
-  if (!event.session_id || !event.transcript_path) return;
+  if (!event.sessionId || !event.transcriptPath) return;
 
   const axmeSessionId = ensureAxmeSessionForClaude(
     workspacePath,
-    event.session_id,
-    event.transcript_path,
+    event.sessionId,
+    event.transcriptPath,
+    undefined,
+    event.ide,
   );
 
   // filesChanged tracking only for mutation tools
@@ -52,8 +58,9 @@ function handlePostToolUse(workspacePath: string, event: HookInput): void {
 /**
  * CLI entry point - reads JSON from stdin.
  * @param workspacePath - from --workspace CLI flag
+ * @param ide - from --ide CLI flag (defaults to "claude-code")
  */
-export async function runPostToolUseHook(workspacePath?: string): Promise<void> {
+export async function runPostToolUseHook(workspacePath?: string, ide: IdeKind = "claude-code"): Promise<void> {
   if (!workspacePath) workspacePath = process.cwd();
   if (!workspacePath) return;
 
@@ -66,8 +73,9 @@ export async function runPostToolUseHook(workspacePath?: string): Promise<void>
   try {
     const chunks: Buffer[] = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
-    const input = JSON.parse(Buffer.concat(chunks).toString("utf-8")) as HookInput;
-    handlePostToolUse(workspacePath, input);
+    const raw = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+    const event = inputAdapterFor(ide).parse(raw, "postToolUse");
+    handlePostToolUse(workspacePath, event);
   } catch (err) {
     // Hook failures must be silent — but reported to telemetry for visibility.
     // Use blocking send: hook subprocess exits ms after this catch and would