@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/scripts/lib/hooks.mjs

@@ -0,0 +1,741 @@
+/**
+ * hooks.mjs — Drift-check hook registration logic for all surfaces.
+ *
+ * Supports: claude, codex, cursor, enact
+ *
+ * Per-surface registration details:
+ *
+ * CLAUDE:
+ *   Writes to <claudeHome>/settings.json (creates/merges JSON).
+ *   Adds a `hooks.SessionStart` array entry with a command that invokes the
+ *   drift-check script via `node <abs path>`. Idempotent (keyed by a stable
+ *   marker string in the command). This matches the Claude Code hook format:
+ *   https://docs.anthropic.com/en/docs/claude-code/hooks
+ *
+ * CODEX / ENACT:
+ *   Writes to <home>/config.toml.
+ *   Adds a `[[hooks.session_start]]` entry. The codex-fork's exact TOML hook
+ *   schema is approximated from the enact-agent config conventions. The entry
+ *   is clearly namespaced (`[hooks]` / `[[hooks.session_start]]`) and is
+ *   idempotent (guarded by a stable comment marker). If the exact schema is
+ *   different in a given codex/enact build, the TOML entry is still safe to
+ *   have present (unknown sections are ignored by most TOML parsers).
+ *
+ * CURSOR:
+ *   Cursor uses a settings.json at <cursorHome>/settings.json, similar to
+ *   Claude. Registration mirrors the claude approach (SessionStart hooks array).
+ *   If Cursor's actual hook schema differs, the entry is still reversible and
+ *   clearly marked.
+ *
+ * All registrations are IDEMPOTENT (safe to run twice) and REVERSIBLE
+ * (--remove cleanly undoes them).
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, "..", "..");
+
+// Absolute path to the drift-check hook script.
+const DRIFT_CHECK_SCRIPT = join(REPO_ROOT, "scripts", "hooks", "session-start-drift-check.mjs");
+
+// Stable marker used to detect an existing entry (idempotency key).
+const CLAUDE_HOOK_MARKER = "enact-extensions:session-start-drift-check";
+const TOML_HOOK_MARKER = "enact-extensions:session-start-drift-check";
+
+// ---------------------------------------------------------------------------
+// Default home paths per surface
+// ---------------------------------------------------------------------------
+function defaultHome(surface) {
+  const home = homedir();
+  switch (surface) {
+    case "claude": return join(home, ".claude");
+    case "codex":  return join(home, ".codex");
+    case "enact":  return join(home, ".enact", "agent");
+    case "cursor": return join(home, ".cursor");
+    default:       throw new Error(`Unknown surface: ${surface}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Claude settings.json helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the SessionStart hook entry object for Claude's settings.json.
+ * The command invokes node directly with the absolute hook script path.
+ *
+ * Claude Code hook format (from docs + live ~/.claude/settings.json):
+ *   { matcher: ".*", hooks: [{ type: "command", command: "..." }] }
+ *
+ * The stable marker lives in the command string itself for idempotency
+ * detection (see CLAUDE_HOOK_MARKER / "session-start-drift-check").
+ *
+ * @returns {object} Claude hook entry in the required shape.
+ */
+function makeClaudeHookEntry() {
+  return {
+    matcher: ".*",
+    hooks: [
+      {
+        type: "command",
+        command: `node ${DRIFT_CHECK_SCRIPT}`,
+      },
+    ],
+  };
+}
+
+/**
+ * Read and parse settings.json. Returns empty object on missing/error.
+ */
+function readSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return {};
+  try {
+    return JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write settings.json (pretty-printed JSON, creates parent dir).
+ */
+function writeSettings(settingsPath, settings) {
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+}
+
+/**
+ * Register the drift-check hook in Claude's (or Cursor's) settings.json.
+ * Idempotent: skips if marker already present.
+ *
+ * @param {string} settingsPath - Absolute path to settings.json
+ * @returns {"registered"|"already_registered"} result
+ */
+function registerClaudeHook(settingsPath) {
+  const settings = readSettings(settingsPath);
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionStart)) settings.hooks.SessionStart = [];
+
+  // Check if already registered (idempotency).
+  // Marker is the path substring "session-start-drift-check" in the nested command.
+  const entryMatchesDriftCheck = (e) =>
+    e &&
+    (
+      // New schema: { matcher, hooks: [{ type, command }] }
+      (Array.isArray(e.hooks) && e.hooks.some((h) => (h.command ?? "").includes("session-start-drift-check"))) ||
+      // Old schema (pre-fix): { _enact_marker, command } — tolerate during transition.
+      e._enact_marker === CLAUDE_HOOK_MARKER ||
+      (e.command ?? "").includes("session-start-drift-check")
+    );
+  const alreadyPresent = settings.hooks.SessionStart.some(entryMatchesDriftCheck);
+  if (alreadyPresent) return "already_registered";
+
+  settings.hooks.SessionStart.push(makeClaudeHookEntry());
+  writeSettings(settingsPath, settings);
+  return "registered";
+}
+
+/**
+ * Remove the drift-check hook from Claude's (or Cursor's) settings.json.
+ * Idempotent: safe if entry not present.
+ *
+ * @param {string} settingsPath
+ * @returns {"removed"|"not_found"} result
+ */
+function removeClaudeHook(settingsPath) {
+  if (!existsSync(settingsPath)) return "not_found";
+  const settings = readSettings(settingsPath);
+  if (!settings.hooks?.SessionStart) return "not_found";
+
+  const before = settings.hooks.SessionStart.length;
+  settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+    (e) => !(
+      e &&
+      (
+        // New schema: { matcher, hooks: [{ type, command }] }
+        (Array.isArray(e.hooks) && e.hooks.some((h) => (h.command ?? "").includes("session-start-drift-check"))) ||
+        // Old schema (pre-fix): { _enact_marker, command }
+        e._enact_marker === CLAUDE_HOOK_MARKER ||
+        (e.command ?? "").includes("session-start-drift-check")
+      )
+    ),
+  );
+  if (settings.hooks.SessionStart.length === before) return "not_found";
+
+  writeSettings(settingsPath, settings);
+  return "removed";
+}
+
+// ---------------------------------------------------------------------------
+// Codex / Enact config.toml helpers
+//
+// Assumption: the codex-fork and enact-agent config.toml supports a
+// `[[hooks.session_start]]` array of tables, each with a `command` field.
+// This mirrors common codex-rs config patterns. If the exact schema differs,
+// the entry is still safely parseable as TOML and clearly marked for removal.
+// ---------------------------------------------------------------------------
+
+const TOML_HOOK_BLOCK = (scriptPath) => `
+# [enact-extensions:session-start-drift-check] BEGIN — do not edit this line
+[[hooks.session_start]]
+command = "node ${scriptPath}"
+# [enact-extensions:session-start-drift-check] END
+`;
+
+const TOML_BEGIN_MARKER = `# [${TOML_HOOK_MARKER}] BEGIN`;
+const TOML_END_MARKER = `# [${TOML_HOOK_MARKER}] END`;
+
+function pluginMarker(pluginName) {
+  return `enact-extensions:plugin-hooks:${pluginName}`;
+}
+
+function eventTomlName(eventName) {
+  return String(eventName)
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+/**
+ * Map a PascalCase Claude/Enact event name to the camelCase key Cursor uses
+ * in its plugin-shipped hooks.json.
+ *
+ * Cursor hook events (from spec/cursor.md and plugin format):
+ *   SessionStart       → sessionStart
+ *   UserPromptSubmit   → beforeSubmitPrompt
+ *   PreToolUse         → preToolUse
+ *   PostToolUse        → postToolUse
+ *   Stop               → stop
+ *   PreCompact         → preCompact
+ *   SessionEnd         → sessionEnd
+ *   SubagentStart      → subagentStart
+ *   SubagentStop       → subagentStop
+ *
+ * Any unmapped event falls back to lowercase-first (simple camelCase).
+ *
+ * NOTE: Cursor reads hooks from the plugin-bundled hooks/hooks.json
+ * (installed into ~/.cursor/plugins/local/<name>/hooks/hooks.json via
+ * installCursorPluginBundle). There is NO global ~/.cursor/hooks.json.
+ * This function exists so the bundled hooks.json can be serialised with
+ * the Cursor-native camelCase event keys when needed.
+ *
+ * @param {string} event — PascalCase event name
+ * @returns {string} camelCase Cursor event name
+ */
+export function eventCursorName(event) {
+  const MAP = {
+    SessionStart:     "sessionStart",
+    UserPromptSubmit: "beforeSubmitPrompt",
+    PreToolUse:       "preToolUse",
+    PostToolUse:      "postToolUse",
+    Stop:             "stop",
+    PreCompact:       "preCompact",
+    SessionEnd:       "sessionEnd",
+    SubagentStart:    "subagentStart",
+    SubagentStop:     "subagentStop",
+  };
+  const mapped = MAP[String(event)];
+  if (mapped) return mapped;
+  // Fallback: lowercase the first character.
+  const s = String(event);
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function flattenHookCommands(hookConfig) {
+  const out = [];
+  const hooks = hookConfig?.hooks && typeof hookConfig.hooks === "object" ? hookConfig.hooks : {};
+  for (const [eventName, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!group || typeof group !== "object") continue;
+      const commands = Array.isArray(group.hooks) ? group.hooks : [];
+      for (const hook of commands) {
+        if (!hook || typeof hook !== "object" || hook.type !== "command" || typeof hook.command !== "string") {
+          continue;
+        }
+        out.push({
+          eventName,
+          matcher: typeof group.matcher === "string" ? group.matcher : undefined,
+          command: hook.command,
+          statusMessage: typeof hook.statusMessage === "string" ? hook.statusMessage : undefined,
+          timeout: typeof hook.timeout === "number" ? hook.timeout : undefined,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function commandLooksPluginOwned(command) {
+  return /^enact-(?:operator|context)\s+hook\s+/.test(String(command));
+}
+
+/**
+ * True when `command` is owned by the named plugin's runtime CLI, i.e. it
+ * starts with `<pluginName> hook ` (the operator/context binaries invoke their
+ * hooks as `enact-operator hook <x>` / `enact-context hook <x>`).
+ *
+ * Scoping removal to the SPECIFIC plugin avoids reconciling one plugin from
+ * stripping a sibling plugin's marker-less entries. Falls back to the broad
+ * operator|context match when no plugin name is given.
+ */
+function commandOwnedByPlugin(command, pluginName) {
+  if (!pluginName) return commandLooksPluginOwned(command);
+  const esc = String(pluginName).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${esc}\\s+hook\\s+`).test(String(command));
+}
+
+function registerJsonPluginHooks(settingsPath, pluginName, hookConfig) {
+  const settings = readSettings(settingsPath);
+  if (!settings.hooks) settings.hooks = {};
+  const marker = pluginMarker(pluginName);
+  let registered = 0;
+  let already = 0;
+
+  for (const entry of flattenHookCommands(hookConfig)) {
+    if (!commandLooksPluginOwned(entry.command)) continue;
+    if (!Array.isArray(settings.hooks[entry.eventName])) settings.hooks[entry.eventName] = [];
+    const exists = settings.hooks[entry.eventName].some((group) =>
+      group?._enact_marker === marker &&
+      Array.isArray(group.hooks) &&
+      group.hooks.some((hook) => hook?.command === entry.command),
+    );
+    if (exists) {
+      already += 1;
+      continue;
+    }
+    settings.hooks[entry.eventName].push({
+      _enact_marker: marker,
+      ...(entry.matcher ? { matcher: entry.matcher } : {}),
+      hooks: [
+        {
+          type: "command",
+          command: entry.command,
+          ...(entry.statusMessage ? { statusMessage: entry.statusMessage } : {}),
+          ...(entry.timeout ? { timeout: entry.timeout } : {}),
+        },
+      ],
+    });
+    registered += 1;
+  }
+
+  if (registered > 0) writeSettings(settingsPath, settings);
+  return registered > 0 ? "registered" : already > 0 ? "already_registered" : "skipped";
+}
+
+function removeJsonPluginHooks(settingsPath, pluginName) {
+  if (!existsSync(settingsPath)) return "not_found";
+  const settings = readSettings(settingsPath);
+  if (!settings.hooks || typeof settings.hooks !== "object") return "not_found";
+  const marker = pluginMarker(pluginName);
+  let removed = 0;
+
+  for (const [eventName, groups] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const next = groups.filter((group) => {
+      const markerMatch = group?._enact_marker === marker;
+      const commandMatch =
+        Array.isArray(group?.hooks) &&
+        group.hooks.some((hook) => commandOwnedByPlugin(hook?.command, pluginName));
+      const shouldRemove = markerMatch || commandMatch;
+      if (shouldRemove) removed += 1;
+      return !shouldRemove;
+    });
+    // Drop event keys we have fully emptied so a removed/unsupported event
+    // (e.g. SessionIdle) does not linger as `[]` and trip host "unknown hook
+    // event" warnings. Personal/other-plugin entries keep the key alive.
+    if (next.length === 0) delete settings.hooks[eventName];
+    else settings.hooks[eventName] = next;
+  }
+
+  if (removed === 0) return "not_found";
+  writeSettings(settingsPath, settings);
+  return "removed";
+}
+
+function pluginTomlBlock(pluginName, entry) {
+  const marker = pluginMarker(pluginName);
+  const eventName = eventTomlName(entry.eventName);
+  const suffix = `${entry.eventName}:${entry.command}`;
+  const fields = [
+    `# [${marker}] BEGIN ${suffix}`,
+    `[[hooks.${eventName}]]`,
+    ...(entry.matcher ? [`matcher = ${tomlString(entry.matcher)}`] : []),
+    `command = ${tomlString(entry.command)}`,
+    ...(entry.statusMessage ? [`status_message = ${tomlString(entry.statusMessage)}`] : []),
+    ...(entry.timeout ? [`timeout = ${entry.timeout}`] : []),
+    `# [${marker}] END ${suffix}`,
+  ];
+  return `${fields.join("\n")}\n`;
+}
+
+function registerTomlPluginHooks(configPath, pluginName, hookConfig) {
+  const existing = readToml(configPath);
+  const marker = pluginMarker(pluginName);
+  const blocks = [];
+  let already = 0;
+  for (const entry of flattenHookCommands(hookConfig)) {
+    if (!commandLooksPluginOwned(entry.command)) continue;
+    const suffix = `${entry.eventName}:${entry.command}`;
+    if (existing.includes(`# [${marker}] BEGIN ${suffix}`)) {
+      already += 1;
+      continue;
+    }
+    blocks.push(pluginTomlBlock(pluginName, entry));
+  }
+  if (blocks.length === 0) return already > 0 ? "already_registered" : "skipped";
+  const next = `${existing.replace(/\s+$/, "")}${existing.trim() ? "\n\n" : ""}${blocks.join("\n")}`;
+  writeToml(configPath, next.endsWith("\n") ? next : `${next}\n`);
+  return "registered";
+}
+
+function removeTomlPluginHooks(configPath, pluginName) {
+  const existing = readToml(configPath);
+  const marker = pluginMarker(pluginName);
+  const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`\\n?# \\[${escaped}\\] BEGIN[^\\n]*\\n[\\s\\S]*?# \\[${escaped}\\] END[^\\n]*\\n?`, "g");
+  let next = existing.replace(pattern, "\n");
+  let removed = next !== existing;
+
+  // Legacy cleanup: older codex installs could preserve the hook tables while
+  // dropping the marker comments when config.toml was reserialized. Remove any
+  // remaining plain [[hooks.*]] blocks that still point at the operator runtime
+  // command set.
+  const lines = next.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length;) {
+    const line = lines[i];
+    if (line.startsWith("[[hooks.")) {
+      const block = [line];
+      i += 1;
+      while (
+        i < lines.length &&
+        !lines[i].startsWith("[[hooks.") &&
+        !/^\[[^\[]/.test(lines[i]) &&
+        !lines[i].startsWith(`# [${marker}] BEGIN`)
+      ) {
+        block.push(lines[i]);
+        i += 1;
+      }
+      const commandLine = block.find((entry) => entry.trim().startsWith("command = "));
+      const commandMatch = commandLine
+        ? commandOwnedByPlugin(commandLine.replace(/^command\s*=\s*/, "").replace(/^"|"$/g, ""), pluginName)
+        : false;
+      const markerMatch = block.some((entry) => entry.includes(marker));
+      if (markerMatch || commandMatch) {
+        removed = true;
+        continue;
+      }
+      out.push(...block);
+      continue;
+    }
+    out.push(line);
+    i += 1;
+  }
+
+  if (!removed) return "not_found";
+  next = out.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+  writeToml(configPath, next.endsWith("\n") ? next : `${next}\n`);
+  return "removed";
+}
+
+/**
+ * Read config.toml content. Returns empty string on missing.
+ */
+function readToml(configPath) {
+  if (!existsSync(configPath)) return "";
+  try {
+    return readFileSync(configPath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Write config.toml (creates parent dir).
+ */
+function writeToml(configPath, content) {
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, content, "utf8");
+}
+
+/**
+ * Register the drift-check hook in a codex/enact config.toml.
+ * Idempotent: checks for the BEGIN marker before appending.
+ *
+ * @param {string} configPath
+ * @returns {"registered"|"already_registered"} result
+ */
+function registerTomlHook(configPath) {
+  const existing = readToml(configPath);
+  if (existing.includes(TOML_BEGIN_MARKER)) return "already_registered";
+
+  const block = TOML_HOOK_BLOCK(DRIFT_CHECK_SCRIPT);
+  writeToml(configPath, existing + block);
+  return "registered";
+}
+
+/**
+ * Remove the drift-check hook block from config.toml.
+ * Removes the content between BEGIN and END markers (inclusive).
+ *
+ * @param {string} configPath
+ * @returns {"removed"|"not_found"} result
+ */
+function removeTomlHook(configPath) {
+  const existing = readToml(configPath);
+  if (!existing.includes(TOML_BEGIN_MARKER)) return "not_found";
+
+  // Remove the marked block (BEGIN line through END line, inclusive).
+  const beginIdx = existing.indexOf(TOML_BEGIN_MARKER);
+  const endIdx = existing.indexOf(TOML_END_MARKER);
+  if (beginIdx === -1 || endIdx === -1) return "not_found";
+
+  // Include the newline before BEGIN and after END.
+  const beforeBegin = existing.slice(0, beginIdx).replace(/\n$/, "");
+  const afterEnd = existing.slice(endIdx + TOML_END_MARKER.length).replace(/^\n/, "");
+  const newContent = beforeBegin + (afterEnd ? "\n" + afterEnd : "");
+
+  writeToml(configPath, newContent);
+  return "removed";
+}
+
+// ---------------------------------------------------------------------------
+// Public API: registerHook / removeHook for each surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the session-start drift-check hook for a given surface.
+ *
+ * @param {string} surface — "claude" | "codex" | "cursor" | "enact"
+ * @param {object} [opts]
+ * @param {string} [opts.claudeHome]
+ * @param {string} [opts.codexHome]
+ * @param {string} [opts.cursorHome]
+ * @param {string} [opts.enactHome]
+ * @param {boolean} [opts.local] — if true, use project-local home under cwd
+ * @param {string} [opts.cwd] — cwd for --local resolution
+ * @returns {{ surface: string, result: "registered"|"already_registered"|"skipped", note?: string }}
+ */
+export function registerHook(surface, opts = {}) {
+  try {
+    switch (surface) {
+      case "claude": {
+        const home = opts.claudeHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".claude") : defaultHome("claude"));
+        const settingsPath = join(home, "settings.json");
+        const result = registerClaudeHook(settingsPath);
+        return { surface, result, location: settingsPath };
+      }
+
+      case "cursor": {
+        // Cursor mirrors Claude's settings.json approach.
+        // NOTE: Cursor's actual hook schema may differ — this uses the same
+        // SessionStart format as Claude. Reverse with --remove if unwanted.
+        const home = opts.cursorHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".cursor") : defaultHome("cursor"));
+        const settingsPath = join(home, "settings.json");
+        const result = registerClaudeHook(settingsPath);
+        return {
+          surface,
+          result,
+          location: settingsPath,
+          note: "Assumption: Cursor uses settings.json SessionStart hooks (same as Claude Code). Verify if Cursor's actual hook schema differs.",
+        };
+      }
+
+      case "codex": {
+        const home = opts.codexHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".codex") : defaultHome("codex"));
+        const configPath = join(home, "config.toml");
+        const result = registerTomlHook(configPath);
+        return {
+          surface,
+          result,
+          location: configPath,
+          note: "Assumption: codex config.toml supports [[hooks.session_start]] with a command field.",
+        };
+      }
+
+      case "enact": {
+        const home = opts.enactHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".enact", "agent") : defaultHome("enact"));
+        const configPath = join(home, "config.toml");
+        const result = registerTomlHook(configPath);
+        return {
+          surface,
+          result,
+          location: configPath,
+          note: "Assumption: enact-agent config.toml supports [[hooks.session_start]] with a command field.",
+        };
+      }
+
+      default:
+        return { surface, result: "skipped", note: `Unknown surface: ${surface}` };
+    }
+  } catch (err) {
+    // Never crash — return skipped with the error note.
+    return {
+      surface,
+      result: "skipped",
+      note: `Error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+/**
+ * Remove the session-start drift-check hook for a given surface.
+ *
+ * @param {string} surface
+ * @param {object} [opts] — same as registerHook
+ * @returns {{ surface: string, result: "removed"|"not_found"|"skipped", note?: string }}
+ */
+export function removeHook(surface, opts = {}) {
+  try {
+    switch (surface) {
+      case "claude": {
+        const home = opts.claudeHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".claude") : defaultHome("claude"));
+        const settingsPath = join(home, "settings.json");
+        const result = removeClaudeHook(settingsPath);
+        return { surface, result, location: settingsPath };
+      }
+
+      case "cursor": {
+        const home = opts.cursorHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".cursor") : defaultHome("cursor"));
+        const settingsPath = join(home, "settings.json");
+        const result = removeClaudeHook(settingsPath);
+        return { surface, result, location: settingsPath };
+      }
+
+      case "codex": {
+        const home = opts.codexHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".codex") : defaultHome("codex"));
+        const configPath = join(home, "config.toml");
+        const result = removeTomlHook(configPath);
+        return { surface, result, location: configPath };
+      }
+
+      case "enact": {
+        const home = opts.enactHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".enact", "agent") : defaultHome("enact"));
+        const configPath = join(home, "config.toml");
+        const result = removeTomlHook(configPath);
+        return { surface, result, location: configPath };
+      }
+
+      default:
+        return { surface, result: "skipped", note: `Unknown surface: ${surface}` };
+    }
+  } catch (err) {
+    return {
+      surface,
+      result: "skipped",
+      note: `Error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+export function registerPluginHooks(surface, pluginName, hookConfig, opts = {}) {
+  try {
+    switch (surface) {
+      case "claude": {
+        const home = opts.claudeHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".claude") : defaultHome("claude"));
+        const settingsPath = join(home, "settings.json");
+        const result = registerJsonPluginHooks(settingsPath, pluginName, hookConfig);
+        return { surface, result, location: settingsPath };
+      }
+
+      case "cursor": {
+        // Cursor reads hooks from the plugin-bundled hooks/hooks.json
+        // (installed to ~/.cursor/plugins/local/<name>/hooks/hooks.json by
+        // installCursorPluginBundle). There is NO global ~/.cursor/hooks.json
+        // to write to. Registering into ~/.cursor/settings.json is incorrect.
+        // Hook lifecycle is handled by the plugin bundle itself — skip here.
+        return {
+          surface,
+          result: "skipped",
+          note: "Cursor reads hooks from the plugin bundle (hooks/hooks.json installed via installCursorPluginBundle). No global hook file to register into.",
+        };
+      }
+
+      case "codex": {
+        const home = opts.codexHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".codex") : defaultHome("codex"));
+        const configPath = join(home, "config.toml");
+        const result = registerTomlPluginHooks(configPath, pluginName, hookConfig);
+        return { surface, result, location: configPath };
+      }
+
+      case "enact": {
+        const home = opts.enactHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".enact", "agent") : defaultHome("enact"));
+        const configPath = join(home, "config.toml");
+        const result = registerTomlPluginHooks(configPath, pluginName, hookConfig);
+        return { surface, result, location: configPath };
+      }
+
+      default:
+        return { surface, result: "skipped", note: `Unknown surface: ${surface}` };
+    }
+  } catch (err) {
+    return {
+      surface,
+      result: "skipped",
+      note: `Error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+export function removePluginHooks(surface, pluginName, opts = {}) {
+  try {
+    switch (surface) {
+      case "claude": {
+        const home = opts.claudeHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".claude") : defaultHome("claude"));
+        const settingsPath = join(home, "settings.json");
+        const result = removeJsonPluginHooks(settingsPath, pluginName);
+        return { surface, result, location: settingsPath };
+      }
+
+      case "cursor": {
+        // Cursor reads hooks from the plugin bundle — nothing to remove globally.
+        return {
+          surface,
+          result: "skipped",
+          note: "Cursor reads hooks from the plugin bundle (hooks/hooks.json installed via installCursorPluginBundle). No global hook file to remove from.",
+        };
+      }
+
+      case "codex": {
+        const home = opts.codexHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".codex") : defaultHome("codex"));
+        const configPath = join(home, "config.toml");
+        const result = removeTomlPluginHooks(configPath, pluginName);
+        return { surface, result, location: configPath };
+      }
+
+      case "enact": {
+        const home = opts.enactHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".enact", "agent") : defaultHome("enact"));
+        const configPath = join(home, "config.toml");
+        const result = removeTomlPluginHooks(configPath, pluginName);
+        return { surface, result, location: configPath };
+      }
+
+      default:
+        return { surface, result: "skipped", note: `Unknown surface: ${surface}` };
+    }
+  } catch (err) {
+    return {
+      surface,
+      result: "skipped",
+      note: `Error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+// The 4 supported surfaces.
+export const SUPPORTED_SURFACES = ["claude", "codex", "cursor", "enact"];