failproofai 0.0.8 → 0.0.9-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.8",
+  "version": "0.0.9-beta.0",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"
@@ -90,7 +90,7 @@
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.18",
     "typescript": "^6.0.2",
-    "@anthropic-ai/sdk": "^0.90.0",
+    "@anthropic-ai/sdk": "^0.91.1",
     "vitest": "^4.0.18"
   },
   "dependencies": {

package/src/hooks/builtin-policies.ts

@@ -10,15 +10,36 @@ import { allow, deny, instruct } from "./policy-helpers";
 import { normalizePolicyName, registerPolicy } from "./policy-registry";
 import { hookLogWarn } from "./hook-logger";
 
-function isClaudeInternalPath(resolved: string): boolean {
-  const claudeDir = join(homedir(), ".claude");
-  return resolved === claudeDir || resolved.startsWith(claudeDir + "/");
+/**
+ * Whether `resolved` lives under an agent CLI's home directory
+ * (~/.claude/ or ~/.codex/). Used to whitelist agent self-reads of their own
+ * config and transcripts.
+ */
+function isAgentInternalPath(resolved: string): boolean {
+  for (const dir of [".claude", ".codex"]) {
+    const root = join(homedir(), dir);
+    if (resolved === root || resolved.startsWith(root + "/")) return true;
+  }
+  return false;
 }
 
-function isClaudeSettingsFile(resolved: string): boolean {
-  return /[\\/]\.claude[\\/]settings(?:\.[^/\\]+)?\.json$/.test(resolved);
+/**
+ * Whether `resolved` is a settings/hooks file for an agent CLI:
+ *   • Claude Code: `.claude/settings.json`, `.claude/settings.local.json`, etc.
+ *   • Codex: `.codex/hooks.json`
+ * These must NEVER be edited by the agent itself — that would let it disable
+ * its own protections.
+ */
+function isAgentSettingsFile(resolved: string): boolean {
+  if (/[\\/]\.claude[\\/]settings(?:\.[^/\\]+)?\.json$/.test(resolved)) return true;
+  if (/[\\/]\.codex[\\/]hooks\.json$/.test(resolved)) return true;
+  return false;
 }
 
+// Back-compat aliases — kept for any caller that imports the old names.
+const isClaudeInternalPath = isAgentInternalPath;
+const isClaudeSettingsFile = isAgentSettingsFile;
+
 function getCommand(ctx: PolicyContext): string {
   return (ctx.toolInput?.command as string) ?? "";
 }
@@ -1483,7 +1504,9 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
     name: "block-sudo",
     description: "Block sudo commands",
     fn: blockSudo,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
+    // PermissionRequest is Codex's escalation-approval event; fire the same
+    // sudo guard there so Codex sandbox bypasses are blocked too.
+    match: { events: ["PreToolUse", "PermissionRequest"], toolNames: ["Bash"] },
     defaultEnabled: true,
     category: "Dangerous Commands",
     params: {

package/src/hooks/handler.ts

@@ -5,7 +5,8 @@
  * ~/.failproofai/policies-config.json, evaluates matching policies, persists
  * activity to disk, and returns the appropriate exit code + stdout response.
  */
-import type { HookEventType, SessionMetadata } from "./types";
+import type { HookEventType, IntegrationType, SessionMetadata, CodexHookEventType } from "./types";
+import { CODEX_EVENT_MAP } from "./types";
 import type { PolicyFunction, PolicyResult } from "./policy-types";
 import { readMergedHooksConfig } from "./hooks-config";
 import { registerBuiltinPolicies } from "./builtin-policies";
@@ -15,10 +16,28 @@ import { loadAllCustomHooks } from "./custom-hooks-loader";
 import type { CustomHook } from "./policy-types";
 import { persistHookActivity } from "./hook-activity-store";
 import { trackHookEvent } from "./hook-telemetry";
+import { resolvePermissionMode } from "./resolve-permission-mode";
 import { getInstanceId } from "../../lib/telemetry-id";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
 
-export async function handleHookEvent(eventType: string): Promise<number> {
+/**
+ * Canonicalize an event name to PascalCase. Codex sends snake_case event names
+ * on stdin and as the --hook arg; Claude Code sends PascalCase. The internal
+ * registry, builtin policies, and policy.match.events all key on PascalCase.
+ */
+function canonicalizeEventType(raw: string, cli: IntegrationType): HookEventType {
+  if (cli === "codex") {
+    const mapped = CODEX_EVENT_MAP[raw as CodexHookEventType];
+    if (mapped) return mapped;
+  }
+  // Already PascalCase or unknown — pass through; HOOK_EVENT_TYPES type-checks downstream.
+  return raw as HookEventType;
+}
+
+export async function handleHookEvent(
+  eventType: string,
+  cli: IntegrationType = "claude",
+): Promise<number> {
   const startTime = performance.now();
 
   // Read stdin payload (Claude passes JSON)
@@ -57,13 +76,18 @@ export async function handleHookEvent(eventType: string): Promise<number> {
     }
   }
 
+  // Canonicalize event name (Codex sends snake_case; internals expect PascalCase)
+  const canonicalEventType = canonicalizeEventType(eventType, cli);
+
   // Extract session metadata from payload
+  const sessionId = parsed.session_id as string | undefined;
   const session: SessionMetadata = {
-    sessionId: parsed.session_id as string | undefined,
+    sessionId,
     transcriptPath: parsed.transcript_path as string | undefined,
     cwd: parsed.cwd as string | undefined,
-    permissionMode: parsed.permission_mode as string | undefined,
+    permissionMode: resolvePermissionMode(cli, parsed, sessionId),
     hookEventName: parsed.hook_event_name as string | undefined,
+    cli,
   };
 
   // Load enabled policies (merge across project/local/global scopes)
@@ -98,6 +122,7 @@ export async function handleHookEvent(eventType: string): Promise<number> {
           hook_name: hookName,
           error_type: isTimeout ? "timeout" : "exception",
           event_type: eventType,
+          cli,
           is_convention_policy: isConvention,
           convention_scope: conventionScope ?? null,
         });
@@ -116,6 +141,7 @@ export async function handleHookEvent(eventType: string): Promise<number> {
   // Fire telemetry once per invocation for custom hook loads
   if (customHooksList.length > 0) {
     void trackHookEvent(getInstanceId(), "custom_hooks_loaded", {
+      cli,
       custom_hooks_count: customHooksList.length,
       custom_hook_names: customHooksList.map((h) => h.name),
       event_types_covered: [...new Set(customHooksList.flatMap((h) => h.match?.events ?? []))],
@@ -125,7 +151,8 @@ export async function handleHookEvent(eventType: string): Promise<number> {
   // Fire telemetry for convention-based policy discovery
   if (loadResult.conventionSources.length > 0) {
     void trackHookEvent(getInstanceId(), "convention_policies_loaded", {
-      event_type: eventType,
+      event_type: canonicalEventType,
+      cli,
       project_file_count: loadResult.conventionSources.filter((s) => s.scope === "project").length,
       user_file_count: loadResult.conventionSources.filter((s) => s.scope === "user").length,
       convention_hook_count: conventionHookNames.size,
@@ -133,10 +160,10 @@ export async function handleHookEvent(eventType: string): Promise<number> {
     });
   }
 
-  hookLogInfo(`event=${eventType} policies=${config.enabledPolicies.length} custom=${customHooksList.length} convention=${conventionHookNames.size}`);
+  hookLogInfo(`event=${canonicalEventType} cli=${cli} policies=${config.enabledPolicies.length} custom=${customHooksList.length} convention=${conventionHookNames.size}`);
 
-  // Evaluate policies
-  const result = await evaluatePolicies(eventType as HookEventType, parsed, session, config);
+  // Evaluate policies (use canonical PascalCase event type)
+  const result = await evaluatePolicies(canonicalEventType, parsed, session, config);
   const durationMs = Math.round(performance.now() - startTime);
   hookLogInfo(`result=${result.decision} policy=${result.policyName ?? "none"} duration=${durationMs}ms`);
 
@@ -150,7 +177,8 @@ export async function handleHookEvent(eventType: string): Promise<number> {
   // Persist activity to disk (visible in /policies activity tab)
   const activityEntry = {
     timestamp: Date.now(),
-    eventType,
+    eventType: canonicalEventType,
+    integration: cli,
     toolName: (parsed.tool_name as string) ?? null,
     policyName: result.policyName,
     policyNames: result.policyNames,
@@ -203,7 +231,8 @@ export async function handleHookEvent(eventType: string): Promise<number> {
         : [];
       const distinctId = getInstanceId();
       await trackHookEvent(distinctId, "hook_policy_triggered", {
-        event_type: eventType,
+        event_type: canonicalEventType,
+        cli,
         tool_name: (parsed.tool_name as string) ?? null,
         policy_name: result.policyName,
         decision: result.decision,

package/src/hooks/hook-activity-store.ts

@@ -41,6 +41,8 @@ let rotateSeq = 0;
 export interface HookActivityEntry {
   timestamp: number;
   eventType: string;
+  /** Which agent CLI fired the hook (claude | codex). */
+  integration?: string;
   toolName: string | null;
   policyName: string | null;
   policyNames?: string[];

package/src/hooks/install-prompt.ts

@@ -11,6 +11,8 @@
  */
 import * as readline from "node:readline";
 import { BUILTIN_POLICIES } from "./builtin-policies";
+import { detectInstalledClis, getIntegration } from "./integrations";
+import type { IntegrationType } from "./types";
 
 interface SelectItem {
   name: string;
@@ -28,6 +30,73 @@ export interface PromptOptions {
   includeBeta?: boolean;
 }
 
+/**
+ * Resolve which agent CLIs to install hooks for.
+ *
+ * Rules:
+ *   • If `explicit` is provided (from `--cli`), use it as-is.
+ *   • Else, detect installed CLIs (PATH probe).
+ *   • If exactly one detected → use just that one (no prompt).
+ *   • If both detected and stdin is a TTY → ask single-keypress B/C/D.
+ *   • Otherwise → default to ["claude"] for back-compat.
+ *
+ * Returns the selected IntegrationType[] (always non-empty).
+ */
+export async function resolveTargetClis(explicit?: IntegrationType[]): Promise<IntegrationType[]> {
+  if (explicit && explicit.length > 0) return [...new Set(explicit)];
+
+  const detected = detectInstalledClis();
+
+  if (detected.length === 0) {
+    console.log(
+      "\x1B[33mWarning: no agent CLI binary found in PATH (claude, codex). " +
+        "Defaulting to Claude Code; hooks will activate when an agent is installed.\x1B[0m",
+    );
+    return ["claude"];
+  }
+
+  if (detected.length === 1) {
+    const integration = getIntegration(detected[0]);
+    console.log(`Detected ${integration.displayName}; installing hooks for it.`);
+    return detected;
+  }
+
+  // Both detected. Prompt or default.
+  if (!process.stdin.isTTY) return detected; // non-interactive: install for both
+
+  const labels = detected.map((id) => getIntegration(id).displayName).join(" + ");
+  process.stdout.write(
+    `Detected ${labels}. Install for [B]oth (default), [C]laude Code only, or co[D]ex only? `,
+  );
+
+  return new Promise<IntegrationType[]>((resolve) => {
+    readline.emitKeypressEvents(process.stdin);
+    const wasRaw = process.stdin.isRaw;
+    if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+    const restore = () => {
+      if (process.stdin.setRawMode) process.stdin.setRawMode(wasRaw ?? false);
+      process.stdin.removeListener("keypress", onKey);
+    };
+    const onKey = (str: string, key: { ctrl?: boolean; name?: string } | undefined) => {
+      // Honor Ctrl+C / Ctrl+D as abort — restore terminal and exit, never
+      // silently install for both. Mirrors the keypress contract used by
+      // promptPolicySelection().
+      if (key && key.ctrl && (key.name === "c" || key.name === "d")) {
+        restore();
+        process.stdout.write("\n");
+        process.exit(130); // SIGINT-equivalent
+      }
+      const ch = (str || "").toLowerCase();
+      restore();
+      process.stdout.write("\n");
+      if (ch === "c") resolve(["claude"]);
+      else if (ch === "d") resolve(["codex"]);
+      else resolve(detected); // Enter, B, anything else → both
+    };
+    process.stdin.on("keypress", onKey);
+  });
+}
+
 /**
  * Show interactive searchable policy selector.
  * @param preSelected — policy names to pre-check (e.g. from existing config).

package/src/hooks/integrations.ts

@@ -0,0 +1,373 @@
+/**
+ * Per-CLI hook integration registry.
+ *
+ * An `Integration` describes how failproofai hooks are installed, detected, and
+ * read for a specific agent CLI (Claude Code, OpenAI Codex). The runtime hot
+ * path (`handler.ts`, `policy-evaluator.ts`, `BUILTIN_POLICIES`, `policy-helpers`)
+ * is agent-agnostic — only install/uninstall plumbing varies.
+ */
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import {
+  HOOK_EVENT_TYPES,
+  HOOK_SCOPES,
+  CODEX_HOOK_EVENT_TYPES,
+  CODEX_HOOK_SCOPES,
+  CODEX_EVENT_MAP,
+  FAILPROOFAI_HOOK_MARKER,
+  INTEGRATION_TYPES,
+  type IntegrationType,
+  type HookScope,
+  type ClaudeSettings,
+  type ClaudeHookMatcher,
+  type ClaudeHookEntry,
+  type CodexHookEventType,
+} from "./types";
+
+// ── Generic helpers ─────────────────────────────────────────────────────────
+
+function readJsonFile(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf8");
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+function writeJsonFile(path: string, data: Record<string, unknown>): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function isMarkedHook(hook: Record<string, unknown>): boolean {
+  if (hook[FAILPROOFAI_HOOK_MARKER] === true) return true;
+  // Fallback for legacy installs predating the marker
+  const cmd = typeof hook.command === "string" ? hook.command : "";
+  return cmd.includes("failproofai") && cmd.includes("--hook");
+}
+
+function binaryExists(name: string): boolean {
+  try {
+    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
+    execSync(cmd, { encoding: "utf8", stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Integration interface ───────────────────────────────────────────────────
+
+export interface Integration {
+  id: IntegrationType;
+  displayName: string;
+  /** Settings scopes this integration supports (e.g. claude: user/project/local; codex: user/project). */
+  scopes: readonly HookScope[];
+  /** Hook events this integration fires (Claude: PascalCase, Codex: snake_case stored as Pascal in settings). */
+  eventTypes: readonly string[];
+
+  /** Resolve the per-scope settings/hooks file path. */
+  getSettingsPath(scope: HookScope, cwd?: string): string;
+
+  /** Read the raw settings/hooks file (returns {} when missing). */
+  readSettings(settingsPath: string): Record<string, unknown>;
+
+  /** Write the settings/hooks file. */
+  writeSettings(settingsPath: string, settings: Record<string, unknown>): void;
+
+  /** Build a single hook entry for a given event. */
+  buildHookEntry(binaryPath: string, eventType: string, scope?: HookScope): Record<string, unknown>;
+
+  /** Whether a hook entry is owned by failproofai. */
+  isFailproofaiHook(hook: Record<string, unknown>): boolean;
+
+  /** Mutate `settings` in place, registering failproofai across all event types. Idempotent. */
+  writeHookEntries(settings: Record<string, unknown>, binaryPath: string, scope?: HookScope): void;
+
+  /** Remove all failproofai hook entries from a settings file. Returns the number removed. */
+  removeHooksFromFile(settingsPath: string): number;
+
+  /** Whether failproofai hooks are present in a given scope. */
+  hooksInstalledInSettings(scope: HookScope, cwd?: string): boolean;
+
+  /** Whether the agent CLI binary is installed (probes PATH). */
+  detectInstalled(): boolean;
+}
+
+// ── Claude Code integration ─────────────────────────────────────────────────
+
+export const claudeCode: Integration = {
+  id: "claude",
+  displayName: "Claude Code",
+  scopes: HOOK_SCOPES,
+  eventTypes: HOOK_EVENT_TYPES,
+
+  getSettingsPath(scope, cwd) {
+    const base = cwd ? resolve(cwd) : process.cwd();
+    switch (scope) {
+      case "user":
+        return resolve(homedir(), ".claude", "settings.json");
+      case "project":
+        return resolve(base, ".claude", "settings.json");
+      case "local":
+        return resolve(base, ".claude", "settings.local.json");
+    }
+  },
+
+  readSettings(settingsPath) {
+    return readJsonFile(settingsPath);
+  },
+
+  writeSettings(settingsPath, settings) {
+    writeJsonFile(settingsPath, settings);
+  },
+
+  buildHookEntry(binaryPath, eventType, scope) {
+    // No --cli flag on the Claude command line: the handler defaults to
+    // claude when --cli is omitted, preserving back-compat with hooks
+    // installed before multi-CLI support was added.
+    const command =
+      scope === "project"
+        ? `npx -y failproofai --hook ${eventType}`
+        : `"${binaryPath}" --hook ${eventType}`;
+    return {
+      type: "command",
+      command,
+      timeout: 60_000,
+      [FAILPROOFAI_HOOK_MARKER]: true,
+    };
+  },
+
+  isFailproofaiHook: isMarkedHook,
+
+  writeHookEntries(settings, binaryPath, scope) {
+    const s = settings as ClaudeSettings;
+    if (!s.hooks) s.hooks = {};
+
+    for (const eventType of HOOK_EVENT_TYPES) {
+      const hookEntry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as ClaudeHookEntry;
+      if (!s.hooks[eventType]) s.hooks[eventType] = [];
+      const matchers: ClaudeHookMatcher[] = s.hooks[eventType];
+
+      let found = false;
+      for (const matcher of matchers) {
+        if (!matcher.hooks) continue;
+        const idx = matcher.hooks.findIndex((h) => isMarkedHook(h as Record<string, unknown>));
+        if (idx >= 0) {
+          matcher.hooks[idx] = hookEntry;
+          found = true;
+          break;
+        }
+      }
+      if (!found) matchers.push({ hooks: [hookEntry] });
+    }
+  },
+
+  removeHooksFromFile(settingsPath) {
+    const settings = this.readSettings(settingsPath) as ClaudeSettings;
+    if (!settings.hooks) return 0;
+
+    let removed = 0;
+    for (const eventType of Object.keys(settings.hooks)) {
+      const matchers = settings.hooks[eventType];
+      if (!Array.isArray(matchers)) continue;
+      for (let i = matchers.length - 1; i >= 0; i--) {
+        const matcher = matchers[i];
+        if (!matcher.hooks) continue;
+        const before = matcher.hooks.length;
+        matcher.hooks = matcher.hooks.filter((h) => !isMarkedHook(h as Record<string, unknown>));
+        removed += before - matcher.hooks.length;
+        if (matcher.hooks.length === 0) matchers.splice(i, 1);
+      }
+      if (matchers.length === 0) delete settings.hooks[eventType];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+    this.writeSettings(settingsPath, settings as Record<string, unknown>);
+    return removed;
+  },
+
+  hooksInstalledInSettings(scope, cwd) {
+    const settingsPath = this.getSettingsPath(scope, cwd);
+    if (!existsSync(settingsPath)) return false;
+    try {
+      const settings = this.readSettings(settingsPath) as ClaudeSettings;
+      if (!settings.hooks) return false;
+      for (const matchers of Object.values(settings.hooks)) {
+        if (!Array.isArray(matchers)) continue;
+        for (const matcher of matchers) {
+          if (!matcher.hooks) continue;
+          if (matcher.hooks.some((h) => isMarkedHook(h as Record<string, unknown>))) return true;
+        }
+      }
+    } catch {
+      // Corrupt settings — treat as not installed
+    }
+    return false;
+  },
+
+  detectInstalled() {
+    return binaryExists("claude") || binaryExists("claude-code");
+  },
+};
+
+// ── OpenAI Codex integration ────────────────────────────────────────────────
+//
+// Codex's hook protocol is Claude-compatible by design (see the parity matrix
+// in plans/great-in-failproofai-i-vectorized-treasure.md). The only material
+// differences are:
+//   • Settings paths: ~/.codex/hooks.json (user) and <cwd>/.codex/hooks.json (project)
+//   • Stdin event names arrive snake_case (pre_tool_use); we canonicalize to PascalCase before policy lookup
+//   • No "local" scope
+//   • Settings file carries a top-level "version": 1 marker
+
+interface CodexSettingsFile {
+  version?: number;
+  hooks?: Record<string, ClaudeHookMatcher[]>;
+  [key: string]: unknown;
+}
+
+export const codex: Integration = {
+  id: "codex",
+  displayName: "OpenAI Codex",
+  scopes: CODEX_HOOK_SCOPES,
+  eventTypes: CODEX_HOOK_EVENT_TYPES,
+
+  getSettingsPath(scope, cwd) {
+    const base = cwd ? resolve(cwd) : process.cwd();
+    switch (scope) {
+      case "user":
+        return resolve(homedir(), ".codex", "hooks.json");
+      case "project":
+        return resolve(base, ".codex", "hooks.json");
+      case "local":
+        // Codex has no "local" scope; fall back to project so callers don't crash.
+        // The CLI rejects --cli codex --scope local before reaching here.
+        return resolve(base, ".codex", "hooks.json");
+    }
+  },
+
+  readSettings(settingsPath) {
+    const raw = readJsonFile(settingsPath);
+    if (raw.version === undefined) raw.version = 1;
+    return raw;
+  },
+
+  writeSettings(settingsPath, settings) {
+    writeJsonFile(settingsPath, settings);
+  },
+
+  buildHookEntry(binaryPath, eventType, scope) {
+    // `eventType` here is the snake_case Codex event name; Codex stores under
+    // PascalCase keys but invokes the command with the snake_case form, which
+    // we canonicalize on the way into policy-evaluator.
+    const command =
+      scope === "project"
+        ? `npx -y failproofai --hook ${eventType} --cli codex`
+        : `"${binaryPath}" --hook ${eventType} --cli codex`;
+    return {
+      type: "command",
+      command,
+      timeout: 60_000,
+      [FAILPROOFAI_HOOK_MARKER]: true,
+    };
+  },
+
+  isFailproofaiHook: isMarkedHook,
+
+  writeHookEntries(settings, binaryPath, scope) {
+    const s = settings as CodexSettingsFile;
+    if (s.version === undefined) s.version = 1;
+    if (!s.hooks) s.hooks = {};
+
+    for (const eventType of CODEX_HOOK_EVENT_TYPES) {
+      const pascalKey = CODEX_EVENT_MAP[eventType as CodexHookEventType];
+      const hookEntry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as ClaudeHookEntry;
+      if (!s.hooks[pascalKey]) s.hooks[pascalKey] = [];
+      const matchers: ClaudeHookMatcher[] = s.hooks[pascalKey];
+
+      let found = false;
+      for (const matcher of matchers) {
+        if (!matcher.hooks) continue;
+        const idx = matcher.hooks.findIndex((h) => isMarkedHook(h as Record<string, unknown>));
+        if (idx >= 0) {
+          matcher.hooks[idx] = hookEntry;
+          found = true;
+          break;
+        }
+      }
+      if (!found) matchers.push({ hooks: [hookEntry] });
+    }
+  },
+
+  removeHooksFromFile(settingsPath) {
+    const settings = this.readSettings(settingsPath) as CodexSettingsFile;
+    if (!settings.hooks) return 0;
+
+    let removed = 0;
+    for (const eventType of Object.keys(settings.hooks)) {
+      const matchers = settings.hooks[eventType];
+      if (!Array.isArray(matchers)) continue;
+      for (let i = matchers.length - 1; i >= 0; i--) {
+        const matcher = matchers[i];
+        if (!matcher.hooks) continue;
+        const before = matcher.hooks.length;
+        matcher.hooks = matcher.hooks.filter((h) => !isMarkedHook(h as Record<string, unknown>));
+        removed += before - matcher.hooks.length;
+        if (matcher.hooks.length === 0) matchers.splice(i, 1);
+      }
+      if (matchers.length === 0) delete settings.hooks[eventType];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+    this.writeSettings(settingsPath, settings as Record<string, unknown>);
+    return removed;
+  },
+
+  hooksInstalledInSettings(scope, cwd) {
+    const settingsPath = this.getSettingsPath(scope, cwd);
+    if (!existsSync(settingsPath)) return false;
+    try {
+      const settings = this.readSettings(settingsPath) as CodexSettingsFile;
+      if (!settings.hooks) return false;
+      for (const matchers of Object.values(settings.hooks)) {
+        if (!Array.isArray(matchers)) continue;
+        for (const matcher of matchers) {
+          if (!matcher.hooks) continue;
+          if (matcher.hooks.some((h) => isMarkedHook(h as Record<string, unknown>))) return true;
+        }
+      }
+    } catch {
+      // Corrupt settings — treat as not installed
+    }
+    return false;
+  },
+
+  detectInstalled() {
+    return binaryExists("codex");
+  },
+};
+
+// ── Registry ────────────────────────────────────────────────────────────────
+
+const INTEGRATIONS: Record<IntegrationType, Integration> = {
+  claude: claudeCode,
+  codex,
+};
+
+export function getIntegration(id: IntegrationType): Integration {
+  const integration = INTEGRATIONS[id];
+  if (!integration) {
+    throw new Error(`Unknown integration: ${id}. Valid: ${INTEGRATION_TYPES.join(", ")}`);
+  }
+  return integration;
+}
+
+export function listIntegrations(): Integration[] {
+  return INTEGRATION_TYPES.map((id) => INTEGRATIONS[id]);
+}
+
+/** Detect which agent CLIs are installed on PATH. */
+export function detectInstalledClis(): IntegrationType[] {
+  return INTEGRATION_TYPES.filter((id) => INTEGRATIONS[id].detectInstalled());
+}