caveat-cli 0.13.0 → 0.14.1

package/dist/index.js

@@ -27,6 +27,7 @@ import {
   loadConfig,
   markHit,
   openDb,
+  readCodexSessionSignals,
   readSessionSignals,
   rebuildAll,
   recordEntry,
@@ -39,7 +40,7 @@ import {
   toolErrorReminderText,
   updateEntry,
   userPromptSubmitReminderText
-} from "./chunk-WTHGWCPM.js";
+} from "./chunk-CSXD73IX.js";
 
 // ../../node_modules/.pnpm/ajv@8.18.0/node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS({
@@ -6860,6 +6861,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync as readFileSync2, wri
 import { dirname as dirname2, join as join3 } from "node:path";
 var EVENT_USER_PROMPT_SUBMIT = "UserPromptSubmit";
 var EVENT_POST_TOOL_USE = "PostToolUse";
+var EVENT_POST_TOOL_USE_FAILURE = "PostToolUseFailure";
 var EVENT_STOP = "Stop";
 function quote(p) {
   return p.includes(" ") ? `"${p}"` : p;
@@ -6891,6 +6893,15 @@ function removeHook(settings, event, command) {
   settings.hooks[event] = filtered;
   return true;
 }
+function findExistingHookCommand(settings, event, command) {
+  const list = settings.hooks?.[event];
+  if (!list) return void 0;
+  for (const entry of list) {
+    const found = entry.hooks?.find((h) => isSameHookCommand(h.command, command));
+    if (found) return found.command;
+  }
+  return void 0;
+}
 function isSameHookCommand(actual, expected) {
   return actual === expected || actual.endsWith(` ${expected}`);
 }
@@ -6970,21 +6981,31 @@ function installClaudeIntegration(opts) {
   const usCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "user-prompt-submit");
   const ptCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "post-tool-use");
   const stopCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "stop");
+  const ptInstallCmd = findExistingHookCommand(settings, EVENT_POST_TOOL_USE, ptCmd) ?? ptCmd;
   const userPromptSubmit = upsertHook(settings, EVENT_USER_PROMPT_SUBMIT, usCmd);
-  const postToolUse = upsertHook(settings, EVENT_POST_TOOL_USE, ptCmd);
+  const postToolUse = upsertHook(settings, EVENT_POST_TOOL_USE, ptInstallCmd);
+  const postToolUseFailure = upsertHook(
+    settings,
+    EVENT_POST_TOOL_USE_FAILURE,
+    ptInstallCmd
+  );
   const stop = upsertHook(settings, EVENT_STOP, stopCmd);
   let backupPath;
-  const anyAdded = userPromptSubmit === "added" || postToolUse === "added" || stop === "added";
+  const anyAdded = userPromptSubmit === "added" || postToolUse === "added" || postToolUseFailure === "added" || stop === "added";
   if (!opts.dryRun && anyAdded) {
     const backup = writeSettings(settingsPath, settings);
     if (backup) backupPath = backup;
   } else if (opts.dryRun) {
     opts.logger.info(
-      `[dry-run] would ${userPromptSubmit === "added" ? "add" : "keep"} UserPromptSubmit, ${postToolUse === "added" ? "add" : "keep"} PostToolUse, ${stop === "added" ? "add" : "keep"} Stop hook in ${settingsPath}`
+      `[dry-run] would ${userPromptSubmit === "added" ? "add" : "keep"} UserPromptSubmit, ${postToolUse === "added" ? "add" : "keep"} PostToolUse, ${postToolUseFailure === "added" ? "add" : "keep"} PostToolUseFailure, ${stop === "added" ? "add" : "keep"} Stop hook in ${settingsPath}`
     );
   }
   const mcp = opts.skipMcpRegistration ? { action: "skipped", detail: "skipped by caller" } : registerMcp(opts.nodePath, opts.cliScriptPath, opts.dryRun, opts.logger);
-  return { mcp, hooks: { userPromptSubmit, postToolUse, stop }, backupPath };
+  return {
+    mcp,
+    hooks: { userPromptSubmit, postToolUse, postToolUseFailure, stop },
+    backupPath
+  };
 }
 function uninstallClaudeIntegration(opts) {
   const settingsPath = join3(opts.claudeDir, "settings.json");
@@ -6994,9 +7015,10 @@ function uninstallClaudeIntegration(opts) {
   const stopCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "stop");
   const removedUs = removeHook(settings, EVENT_USER_PROMPT_SUBMIT, usCmd);
   const removedPt = removeHook(settings, EVENT_POST_TOOL_USE, ptCmd);
+  const removedPtf = removeHook(settings, EVENT_POST_TOOL_USE_FAILURE, ptCmd);
   const removedStop = removeHook(settings, EVENT_STOP, stopCmd);
   let backupPath;
-  if (!opts.dryRun && (removedUs || removedPt || removedStop)) {
+  if (!opts.dryRun && (removedUs || removedPt || removedPtf || removedStop)) {
     const backup = writeSettings(settingsPath, settings);
     if (backup) backupPath = backup;
   }
@@ -7006,6 +7028,7 @@ function uninstallClaudeIntegration(opts) {
     hooks: {
       userPromptSubmit: removedUs ? "added" : "unchanged",
       postToolUse: removedPt ? "added" : "unchanged",
+      postToolUseFailure: removedPtf ? "added" : "unchanged",
       stop: removedStop ? "added" : "unchanged"
     },
     backupPath
@@ -7109,6 +7132,12 @@ function runUninstall(ctx, opts) {
   ctx.logger.info(
     `UserPromptSubmit hook: ${result.hooks.userPromptSubmit === "added" ? "removed" : "not present"}`
   );
+  ctx.logger.info(
+    `PostToolUse hook: ${result.hooks.postToolUse === "added" ? "removed" : "not present"}`
+  );
+  ctx.logger.info(
+    `PostToolUseFailure hook: ${result.hooks.postToolUseFailure === "added" ? "removed" : "not present"}`
+  );
   ctx.logger.info(
     `Stop hook: ${result.hooks.stop === "added" ? "removed" : "not present"}`
   );
@@ -7124,6 +7153,10 @@ function reportInstallResult(ctx, result, dryRun) {
   ctx.logger.info(
     `${prefix}UserPromptSubmit hook: ${result.hooks.userPromptSubmit}`
   );
+  ctx.logger.info(`${prefix}PostToolUse hook: ${result.hooks.postToolUse}`);
+  ctx.logger.info(
+    `${prefix}PostToolUseFailure hook: ${result.hooks.postToolUseFailure}`
+  );
   ctx.logger.info(`${prefix}Stop hook: ${result.hooks.stop}`);
   if (result.backupPath) {
     ctx.logger.info(`settings.json backed up: ${result.backupPath}`);
@@ -7312,7 +7345,7 @@ function runStats(ctx) {
 
 // src/commands/serve.ts
 async function runServe(opts) {
-  const { startServer } = await import("./server-IWDZZESV.js");
+  const { startServer } = await import("./server-BP54BTEL.js");
   const { port, host } = startServer({ port: opts.port });
   process.stdout.write(`[caveat] web portal: http://${host}:${port}/
 `);
@@ -21934,11 +21967,13 @@ function extractToolResponseText(response) {
   return "";
 }
 function isToolError(payload) {
+  if (payload.hook_event_name === "PostToolUseFailure") return true;
   const resp = payload.tool_response ?? payload.toolResponse;
   if (resp !== null && typeof resp === "object" && !Array.isArray(resp)) {
     if (resp.is_error === true) return true;
   }
   if (payload.is_error === true) return true;
+  if (typeof payload.error === "string" && payload.error.length > 0) return true;
   return false;
 }
 function spawnWorker(job) {
@@ -22162,7 +22197,9 @@ async function runHook(name, arg) {
   }
   if (name === "post-tool-use") {
     if (!isToolError(payload)) process.exit(0);
-    const errText = extractToolResponseText(payload.tool_response ?? payload);
+    const errText = extractToolResponseText(
+      payload.tool_response ?? payload.toolResponse ?? payload.error ?? payload
+    );
     if (errText) {
       spawnWorker({ sessionId, searchText: errText });
     }
@@ -22183,11 +22220,570 @@ async function runHook(name, arg) {
   process.exit(0);
 }
 
+// src/commands/codexHookCmd.ts
+import { spawn as spawn2, spawnSync as spawnSync3 } from "node:child_process";
+import { existsSync as existsSync7, readFileSync as readFileSync5, unlinkSync as unlinkSync2, writeFileSync as writeFileSync5 } from "node:fs";
+import { homedir as homedir3, tmpdir as tmpdir2 } from "node:os";
+import { join as join10 } from "node:path";
+import { randomBytes as randomBytes2 } from "node:crypto";
+
+// src/codexHookInstall.ts
+import { copyFileSync as copyFileSync2, existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname5, join as join9 } from "node:path";
+function quote2(p) {
+  return p.includes(" ") ? `"${p}"` : p;
+}
+function hookCommand2(nodePath, cliScriptPath, event) {
+  return `${quote2(nodePath)} ${quote2(cliScriptPath)} codex-hook ${event}`;
+}
+function eventCommandFragment(event) {
+  return `codex-hook ${event}`;
+}
+function isSameHookCommand2(actual, expected) {
+  return actual === expected || actual.endsWith(` ${expected}`);
+}
+function hasCaveatHook(hooksJson, event, fragment) {
+  return hooksJson.hooks?.[event]?.some(
+    (entry) => entry.hooks?.some((h) => h.command.includes(fragment))
+  ) ?? false;
+}
+function readHooks(path) {
+  if (!existsSync6(path)) return {};
+  return JSON.parse(readFileSync4(path, "utf-8"));
+}
+function writeJsonWithBackup(path, value) {
+  const dir = dirname5(path);
+  if (!existsSync6(dir)) mkdirSync4(dir, { recursive: true });
+  let backupPath = "";
+  if (existsSync6(path)) {
+    backupPath = `${path}.caveat-backup-${Date.now()}`;
+    copyFileSync2(path, backupPath);
+  }
+  writeFileSync4(path, `${JSON.stringify(value, null, 2)}
+`, "utf-8");
+  return backupPath;
+}
+function upsertHook2(hooksJson, event, command) {
+  hooksJson.hooks ??= {};
+  const list = hooksJson.hooks[event] ??= [];
+  const alreadyPresent = list.some(
+    (entry) => entry.hooks?.some((h) => isSameHookCommand2(h.command, command))
+  );
+  if (alreadyPresent) return "unchanged";
+  list.push({
+    hooks: [
+      {
+        type: "command",
+        command,
+        timeoutSec: 5,
+        async: false,
+        statusMessage: null
+      }
+    ]
+  });
+  return "added";
+}
+function removeHook2(hooksJson, event, command) {
+  const list = hooksJson.hooks?.[event];
+  if (!list) return false;
+  const before = list.length;
+  const filtered = list.filter(
+    (entry) => !entry.hooks?.some((h) => isSameHookCommand2(h.command, command))
+  );
+  if (filtered.length === before) return false;
+  hooksJson.hooks[event] = filtered;
+  return true;
+}
+function enableCodexHooksFeature(raw) {
+  if (/^\s*codex_hooks\s*=\s*true\s*$/m.test(raw)) return { text: raw, changed: false };
+  const lines = raw.split(/\r?\n/);
+  const featuresStart = lines.findIndex((line) => /^\s*\[features]\s*$/.test(line));
+  if (featuresStart === -1) {
+    const prefix = raw.trimEnd();
+    const text = `${prefix}${prefix ? "\n\n" : ""}[features]
+codex_hooks = true
+`;
+    return { text, changed: true };
+  }
+  let insertAt = featuresStart + 1;
+  for (let i = featuresStart + 1; i < lines.length; i += 1) {
+    if (/^\s*\[.+]\s*$/.test(lines[i])) {
+      break;
+    }
+    if (/^\s*codex_hooks\s*=/.test(lines[i])) {
+      lines[i] = "codex_hooks = true";
+      return { text: `${lines.join("\n").trimEnd()}
+`, changed: true };
+    }
+  }
+  lines.splice(insertAt, 0, "codex_hooks = true");
+  return { text: `${lines.join("\n").trimEnd()}
+`, changed: true };
+}
+function writeConfigWithBackup(path, text) {
+  const dir = dirname5(path);
+  if (!existsSync6(dir)) mkdirSync4(dir, { recursive: true });
+  let backupPath = "";
+  if (existsSync6(path)) {
+    backupPath = `${path}.caveat-backup-${Date.now()}`;
+    copyFileSync2(path, backupPath);
+  }
+  writeFileSync4(path, text, "utf-8");
+  return backupPath;
+}
+function installCodexHooks(opts) {
+  const hooksPath = join9(opts.codexHome, "hooks.json");
+  const configPath = join9(opts.codexHome, "config.toml");
+  const hooksJson = readHooks(hooksPath);
+  const userPromptSubmit = upsertHook2(
+    hooksJson,
+    "UserPromptSubmit",
+    hookCommand2(opts.nodePath, opts.cliScriptPath, "user-prompt-submit")
+  );
+  const postToolUse = upsertHook2(
+    hooksJson,
+    "PostToolUse",
+    hookCommand2(opts.nodePath, opts.cliScriptPath, "post-tool-use")
+  );
+  const stop = upsertHook2(
+    hooksJson,
+    "Stop",
+    hookCommand2(opts.nodePath, opts.cliScriptPath, "stop")
+  );
+  const rawConfig = existsSync6(configPath) ? readFileSync4(configPath, "utf-8") : "";
+  const enabled = enableCodexHooksFeature(rawConfig);
+  const anyHookAdded = userPromptSubmit === "added" || postToolUse === "added" || stop === "added";
+  let backupPath;
+  let configBackupPath;
+  if (opts.dryRun) {
+    opts.logger.info(`[dry-run] would update ${hooksPath}`);
+    opts.logger.info(`[dry-run] would ensure [features].codex_hooks = true in ${configPath}`);
+  } else {
+    if (anyHookAdded) {
+      const backup = writeJsonWithBackup(hooksPath, hooksJson);
+      if (backup) backupPath = backup;
+    }
+    if (enabled.changed) {
+      const backup = writeConfigWithBackup(configPath, enabled.text);
+      if (backup) configBackupPath = backup;
+    }
+  }
+  return {
+    hooks: { userPromptSubmit, postToolUse, stop },
+    feature: enabled.changed ? "enabled" : "unchanged",
+    backupPath,
+    configBackupPath
+  };
+}
+function uninstallCodexHooks(opts) {
+  const hooksPath = join9(opts.codexHome, "hooks.json");
+  const hooksJson = readHooks(hooksPath);
+  const userPromptSubmitRemoved = removeHook2(
+    hooksJson,
+    "UserPromptSubmit",
+    hookCommand2(opts.nodePath, opts.cliScriptPath, "user-prompt-submit")
+  );
+  const postToolUseRemoved = removeHook2(
+    hooksJson,
+    "PostToolUse",
+    hookCommand2(opts.nodePath, opts.cliScriptPath, "post-tool-use")
+  );
+  const stopRemoved = removeHook2(
+    hooksJson,
+    "Stop",
+    hookCommand2(opts.nodePath, opts.cliScriptPath, "stop")
+  );
+  let backupPath;
+  if (opts.dryRun) {
+    opts.logger.info(`[dry-run] would remove Caveat Codex hooks from ${hooksPath}`);
+  } else if (userPromptSubmitRemoved || postToolUseRemoved || stopRemoved) {
+    const backup = writeJsonWithBackup(hooksPath, hooksJson);
+    if (backup) backupPath = backup;
+  }
+  return {
+    hooks: {
+      userPromptSubmit: userPromptSubmitRemoved ? "added" : "unchanged",
+      postToolUse: postToolUseRemoved ? "added" : "unchanged",
+      stop: stopRemoved ? "added" : "unchanged"
+    },
+    feature: "unchanged",
+    backupPath
+  };
+}
+function detectCodexHookInstallation(codexHome) {
+  const hooksPath = join9(codexHome, "hooks.json");
+  const hooksJson = readHooks(hooksPath);
+  const hooks = {
+    userPromptSubmit: hasCaveatHook(
+      hooksJson,
+      "UserPromptSubmit",
+      eventCommandFragment("user-prompt-submit")
+    ),
+    postToolUse: hasCaveatHook(hooksJson, "PostToolUse", eventCommandFragment("post-tool-use")),
+    stop: hasCaveatHook(hooksJson, "Stop", eventCommandFragment("stop"))
+  };
+  const count = Object.values(hooks).filter(Boolean).length;
+  return {
+    installation: count === 0 ? "not-installed" : count === 3 ? "installed" : "partial",
+    hooksPath,
+    hooks
+  };
+}
+
+// src/commands/codexHookCmd.ts
+var silentLogger2 = {
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: (m) => process.stderr.write(`[caveat:codex-hook] ${m}
+`)
+};
+async function readStdin2() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+function parsePayload2(raw) {
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[caveat:codex-hook] json parse error: ${msg}
+`);
+    return {};
+  }
+}
+function buildContextSafely2() {
+  try {
+    return buildContext(silentLogger2);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[caveat:codex-hook] context error: ${msg}
+`);
+    return null;
+  }
+}
+function searchCaveatsFromTextSafely2(text) {
+  if (!text) return [];
+  let db;
+  try {
+    const ctx = buildContextSafely2();
+    if (!ctx || !existsSync7(ctx.paths.dbPath)) return [];
+    db = openDb({ path: ctx.paths.dbPath });
+    const hits = findCaveatsForPrompt(db, text, {
+      selfIdentity: defaultSelfIdentityTokens()
+    });
+    if (hits.length > 0) {
+      try {
+        markHit(db, hits);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[caveat:codex-hook] markHit error: ${msg}
+`);
+      }
+    }
+    return hits;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[caveat:codex-hook] search error: ${msg}
+`);
+    return [];
+  } finally {
+    db?.close();
+  }
+}
+function loadSignalsSafely2(path) {
+  try {
+    return readCodexSessionSignals(path);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[caveat:codex-hook] transcript read error: ${msg}
+`);
+    return null;
+  }
+}
+function codexSessionId(payload) {
+  const v = payload.session_id ?? payload.sessionId;
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+function extractToolResponseText2(response) {
+  if (typeof response === "string") return response;
+  if (Array.isArray(response)) {
+    return response.map((item) => {
+      if (typeof item === "string") return item;
+      if (item !== null && typeof item === "object") {
+        const text = item.text;
+        return typeof text === "string" ? text : "";
+      }
+      return "";
+    }).filter(Boolean).join(" ");
+  }
+  if (response !== null && typeof response === "object") {
+    const r = response;
+    if (typeof r.content === "string") return r.content;
+    if (Array.isArray(r.content)) return extractToolResponseText2(r.content);
+    if (typeof r.output === "string") return r.output;
+    if (typeof r.stdout === "string" || typeof r.stderr === "string") {
+      return [r.stdout, r.stderr].filter((x) => typeof x === "string").join(" ");
+    }
+  }
+  return "";
+}
+function numericExitCode(v) {
+  return typeof v === "number" && Number.isInteger(v) ? v : null;
+}
+function processExitCodeFromText(text) {
+  const m = /Process exited with code\s+(-?\d+)/.exec(text);
+  return m ? Number(m[1]) : null;
+}
+function transcriptToolOutput(transcriptPath, toolUseId) {
+  if (!transcriptPath || !toolUseId || !existsSync7(transcriptPath)) return null;
+  let raw = "";
+  try {
+    raw = readFileSync5(transcriptPath, "utf-8");
+  } catch {
+    return null;
+  }
+  for (const line of raw.split("\n")) {
+    if (!line.includes(toolUseId)) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (parsed === null || typeof parsed !== "object") continue;
+    const payloadObj = parsed.payload;
+    if (payloadObj === null || typeof payloadObj !== "object") continue;
+    const p = payloadObj;
+    if (p.type !== "function_call_output" || p.call_id !== toolUseId) continue;
+    return typeof p.output === "string" ? p.output : "";
+  }
+  return null;
+}
+function transcriptExitCode(payload) {
+  const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
+  const toolUseId = typeof payload.tool_use_id === "string" ? payload.tool_use_id : "";
+  const output = transcriptToolOutput(transcriptPath, toolUseId);
+  return output === null ? null : processExitCodeFromText(output);
+}
+function isShellLikeTool(payload) {
+  const name = typeof payload.tool_name === "string" ? payload.tool_name : "";
+  if (name === "Bash" || name === "exec_command") return true;
+  const input = payload.tool_input;
+  if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+    const r = input;
+    return typeof r.command === "string" || typeof r.cmd === "string";
+  }
+  return false;
+}
+function toolInputText(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) return "";
+  const r = input;
+  const command = r.command ?? r.cmd;
+  return typeof command === "string" ? command : "";
+}
+function isCodexToolError(payload) {
+  if (payload.is_error === true) return true;
+  const topExit = numericExitCode(payload.exit_code ?? payload.exitCode);
+  if (topExit !== null) return topExit !== 0;
+  const resp = payload.tool_response ?? payload.toolResponse;
+  if (resp !== null && typeof resp === "object" && !Array.isArray(resp)) {
+    const r = resp;
+    if (r.is_error === true) return true;
+    const exit2 = numericExitCode(r.exit_code ?? r.exitCode);
+    if (exit2 !== null) return exit2 !== 0;
+  }
+  const responseExit = processExitCodeFromText(extractToolResponseText2(resp));
+  if (responseExit !== null) return responseExit !== 0;
+  const transcriptExit = transcriptExitCode(payload);
+  if (transcriptExit !== null) return transcriptExit !== 0;
+  return false;
+}
+function buildCodexPostToolUseWorkerJob(payload) {
+  const sessionId = codexSessionId(payload);
+  if (!sessionId) return null;
+  const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : void 0;
+  const toolUseId = typeof payload.tool_use_id === "string" ? payload.tool_use_id : void 0;
+  const responseText = extractToolResponseText2(payload.tool_response ?? payload.toolResponse);
+  const inputText = toolInputText(payload.tool_input);
+  const transcriptOutput = transcriptPath && toolUseId ? transcriptToolOutput(transcriptPath, toolUseId) : null;
+  const searchText = [inputText, responseText, transcriptOutput ?? ""].map((s) => s.trim()).filter(Boolean).join("\n");
+  const knownError = isCodexToolError(payload);
+  if (knownError) {
+    return { sessionId, searchText, knownError: true, transcriptPath, toolUseId };
+  }
+  if (transcriptPath && toolUseId && isShellLikeTool(payload) && searchText) {
+    return {
+      sessionId,
+      searchText,
+      knownError: false,
+      allowSymptomOnly: true,
+      transcriptPath,
+      toolUseId
+    };
+  }
+  return null;
+}
+function codexContextOutput(text, eventName = "UserPromptSubmit") {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: text
+    }
+  });
+}
+function codexStopOutput(text) {
+  return JSON.stringify({
+    decision: "block",
+    reason: text
+  });
+}
+function drainForSession2(sessionId, eventName = "UserPromptSubmit") {
+  const ctx = buildContextSafely2();
+  if (!ctx) return;
+  const reminders = drainPendingReminders(ctx.caveatHome, sessionId);
+  for (const text of reminders) {
+    process.stdout.write(`${codexContextOutput(text, eventName)}
+`);
+  }
+}
+async function waitForTranscriptOutput(transcriptPath, toolUseId) {
+  const deadline = Date.now() + 2e3;
+  while (Date.now() <= deadline) {
+    const output = transcriptToolOutput(transcriptPath, toolUseId);
+    if (output !== null) return output;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return null;
+}
+async function processCodexWorkerJob(job, opts = { waitForTranscript: true }) {
+  if (!job.searchText || !job.sessionId) return;
+  let searchText = job.searchText;
+  let knownError = job.knownError === true;
+  if (opts.waitForTranscript && job.transcriptPath && job.toolUseId) {
+    const transcriptOutput = await waitForTranscriptOutput(job.transcriptPath, job.toolUseId);
+    if (transcriptOutput) {
+      const exit2 = processExitCodeFromText(transcriptOutput);
+      if (exit2 !== null) {
+        if (exit2 === 0) return;
+        knownError = true;
+      }
+      searchText = [searchText, transcriptOutput].filter(Boolean).join("\n");
+    }
+  }
+  if (!knownError && job.allowSymptomOnly !== true) return;
+  const hits = searchCaveatsFromTextSafely2(searchText);
+  if (hits.length === 0) return;
+  const ctx = buildContextSafely2();
+  if (!ctx) return;
+  try {
+    appendPendingReminder(ctx.caveatHome, job.sessionId, toolErrorReminderText(hits));
+  } catch {
+  }
+}
+async function runCodexWorker(workFile) {
+  let raw;
+  try {
+    raw = readFileSync5(workFile, "utf-8");
+  } catch {
+    process.exit(0);
+  }
+  try {
+    unlinkSync2(workFile);
+  } catch {
+  }
+  let job;
+  try {
+    job = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  await processCodexWorkerJob(job);
+  process.exit(0);
+}
+function runDiagnostics(codexHome = process.env.CODEX_HOME ?? join10(homedir3(), ".codex")) {
+  const features = spawnSync3("codex", ["features", "list"], {
+    encoding: "utf-8",
+    maxBuffer: 1024 * 1024
+  });
+  const featureOutput = [features.stdout, features.stderr].filter(Boolean).join("\n");
+  const hasHooks = /^codex_hooks\s+\S+\s+true\b/m.test(featureOutput);
+  const installation = detectCodexHookInstallation(codexHome);
+  const result = {
+    availability: features.error || features.status !== 0 || !hasHooks ? "unavailable" : "available",
+    codexBinary: features.error ? "missing" : "present",
+    codexHooksFeature: hasHooks ? "enabled" : "not-enabled",
+    installation: installation.installation,
+    codexHome,
+    hooksPath: installation.hooksPath,
+    installedHooks: installation.hooks,
+    evidence: featureOutput.split("\n").find((line) => line.trim().startsWith("codex_hooks")) ?? null
+  };
+  process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+}
+async function runCodexHook(name, arg) {
+  if (name === "diagnostics") {
+    runDiagnostics(arg);
+    return;
+  }
+  if (name === "worker") {
+    if (!arg) process.exit(0);
+    await runCodexWorker(arg);
+    return;
+  }
+  let raw = "";
+  try {
+    raw = await readStdin2();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[caveat:codex-hook] stdin read error: ${msg}
+`);
+    process.exit(0);
+  }
+  const payload = parsePayload2(raw);
+  const sessionId = codexSessionId(payload);
+  if (sessionId && name === "user-prompt-submit") drainForSession2(sessionId);
+  else if (!sessionId) process.stderr.write("[caveat:codex-hook] missing session_id; pending drain disabled\n");
+  if (name === "user-prompt-submit") {
+    const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+    const hits = searchCaveatsFromTextSafely2(prompt);
+    if (hits.length > 0) {
+      process.stdout.write(`${codexContextOutput(userPromptSubmitReminderText(hits))}
+`);
+    }
+    process.exit(0);
+  }
+  if (name === "post-tool-use") {
+    const job = buildCodexPostToolUseWorkerJob(payload);
+    if (job) await processCodexWorkerJob(job, { waitForTranscript: false });
+    process.exit(0);
+  }
+  if (name === "stop") {
+    if (payload.stop_hook_active === true) process.exit(0);
+    const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
+    const signals = transcriptPath ? loadSignalsSafely2(transcriptPath) : null;
+    if (!signals || !hasAnyStruggleSignal(signals)) process.exit(0);
+    const related = searchCaveatsFromTextSafely2(struggleSearchText(signals));
+    process.stdout.write(`${codexStopOutput(stopReminderText(signals, related))}
+`);
+    process.exit(0);
+  }
+  process.stderr.write(`[caveat:codex-hook] unknown hook name: ${name}
+`);
+  process.exit(0);
+}
+
 // src/commands/pull.ts
-import { existsSync as existsSync6, readdirSync as readdirSync4 } from "node:fs";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync8, readdirSync as readdirSync4 } from "node:fs";
+import { join as join11 } from "node:path";
 async function runPull(ctx) {
-  if (!existsSync6(ctx.paths.communityDir)) {
+  if (!existsSync8(ctx.paths.communityDir)) {
     ctx.logger.info(
       "no community repos yet \u2014 add one with `caveat community add <github-url>`."
     );
@@ -22207,15 +22803,15 @@ async function runPull(ctx) {
   const db = openDb({ path: ctx.paths.dbPath, logger: ctx.logger });
   try {
     rebuildAll(db);
-    if (existsSync6(ctx.paths.entriesDir)) {
+    if (existsSync8(ctx.paths.entriesDir)) {
       const own = scanSource({ db, source: "own", entriesRoot: ctx.paths.entriesDir });
       ctx.logger.info(`own: +${own.added}`);
     }
     for (const entry of readdirSync4(ctx.paths.communityDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
       const source = `community/${entry.name}`;
-      const root = join9(ctx.paths.communityDir, entry.name, "entries");
-      if (!existsSync6(root)) continue;
+      const root = join11(ctx.paths.communityDir, entry.name, "entries");
+      if (!existsSync8(root)) continue;
       const scan = scanSource({ db, source, entriesRoot: root });
       ctx.logger.info(`${source}: +${scan.added}`);
     }
@@ -22225,10 +22821,10 @@ async function runPull(ctx) {
 }
 
 // src/commands/codexSidecar.ts
-import { spawnSync as spawnSync3 } from "node:child_process";
-import { mkdirSync as mkdirSync4, mkdtempSync as mkdtempSync2, rmSync as rmSync2, writeFileSync as writeFileSync4 } from "node:fs";
-import { tmpdir as tmpdir2 } from "node:os";
-import { dirname as dirname5, join as join10 } from "node:path";
+import { spawnSync as spawnSync4 } from "node:child_process";
+import { mkdirSync as mkdirSync5, mkdtempSync as mkdtempSync2, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "node:fs";
+import { tmpdir as tmpdir3 } from "node:os";
+import { dirname as dirname6, join as join12 } from "node:path";
 import { cwd, exit } from "node:process";
 function runCodexSidecarDiagnostics(logger, opts) {
   const plan = buildCodexSidecarDiagnosticsCommand({
@@ -22260,8 +22856,8 @@ function runCodexSidecarWithCaveats(ctx, workflow, prompt, opts) {
     process.stdout.write(JSON.stringify({ status: "skipped", decision }, null, 2) + "\n");
     exit(0);
   }
-  const contextDir = mkdtempSync2(join10(tmpdir2(), "caveat-sidecar-context-"));
-  const contextFile = join10(contextDir, "context.json");
+  const contextDir = mkdtempSync2(join12(tmpdir3(), "caveat-sidecar-context-"));
+  const contextFile = join12(contextDir, "context.json");
   let status = 1;
   try {
     const blocks = collectCaveatContextBlocks(ctx, {
@@ -22270,7 +22866,7 @@ function runCodexSidecarWithCaveats(ctx, workflow, prompt, opts) {
       source: opts.source,
       visibility: opts.visibility
     });
-    writeFileSync4(contextFile, JSON.stringify({ context: blocks }, null, 2) + "\n", "utf-8");
+    writeFileSync6(contextFile, JSON.stringify({ context: blocks }, null, 2) + "\n", "utf-8");
     const plan = buildCodexSidecarRunCommand({
       workflow,
       projectRoot: opts.project ?? cwd(),
@@ -22325,7 +22921,7 @@ function defaultPreset(workflow) {
 }
 function executePlan(logger, command, args, options = {}) {
   logger.info(`[codex-sidecar] ${command} ${args.map(shellDisplayQuote).join(" ")}`);
-  const result = spawnSync3(command, args, { encoding: "utf-8", stdio: "pipe" });
+  const result = spawnSync4(command, args, { encoding: "utf-8", stdio: "pipe" });
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.stderr) process.stderr.write(result.stderr);
   if (options.saveResult && result.stdout) {
@@ -22339,8 +22935,8 @@ function executePlan(logger, command, args, options = {}) {
 }
 function saveStructuredResult(path, stdout) {
   const parsed = JSON.parse(stdout);
-  mkdirSync4(dirname5(path), { recursive: true });
-  writeFileSync4(path, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+  mkdirSync5(dirname6(path), { recursive: true });
+  writeFileSync6(path, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
 }
 function shellDisplayQuote(value) {
   return /[\s"'$`]/.test(value) ? JSON.stringify(value) : value;
@@ -22493,6 +23089,62 @@ program.command("hook <name> [arg]").description(
 ).action(async (name, arg) => {
   await runHook(name, arg);
 });
+var codexHook = program.command("codex-hook").description("Install or run Codex hooks for Caveat");
+codexHook.command("install").description("Install Caveat hooks into ~/.codex/hooks.json and enable codex_hooks").option("--dry-run", "show planned changes without writing", false).option("--codex-home <path>", "Codex home directory", process.env.CODEX_HOME ?? `${process.env.HOME}/.codex`).action((opts) => {
+  const cliScriptPath = process.argv[1];
+  if (!cliScriptPath) {
+    process.stderr.write("[caveat:error] cannot determine CLI script path\n");
+    process.exit(1);
+  }
+  const result = installCodexHooks({
+    codexHome: opts.codexHome,
+    cliScriptPath,
+    nodePath: process.execPath,
+    dryRun: opts.dryRun,
+    logger: stdoutLogger
+  });
+  stdoutLogger.info(`UserPromptSubmit hook: ${result.hooks.userPromptSubmit}`);
+  stdoutLogger.info(`PostToolUse hook: ${result.hooks.postToolUse}`);
+  stdoutLogger.info(`Stop hook: ${result.hooks.stop}`);
+  stdoutLogger.info(`codex_hooks feature: ${result.feature}`);
+  if (result.backupPath) stdoutLogger.info(`hooks.json backed up: ${result.backupPath}`);
+  if (result.configBackupPath) {
+    stdoutLogger.info(`config.toml backed up: ${result.configBackupPath}`);
+  }
+});
+codexHook.command("uninstall").description("Remove Caveat-owned Codex hooks from ~/.codex/hooks.json").option("--dry-run", "show planned changes without writing", false).option("--codex-home <path>", "Codex home directory", process.env.CODEX_HOME ?? `${process.env.HOME}/.codex`).action((opts) => {
+  const cliScriptPath = process.argv[1];
+  if (!cliScriptPath) {
+    process.stderr.write("[caveat:error] cannot determine CLI script path\n");
+    process.exit(1);
+  }
+  const result = uninstallCodexHooks({
+    codexHome: opts.codexHome,
+    cliScriptPath,
+    nodePath: process.execPath,
+    dryRun: opts.dryRun,
+    logger: stdoutLogger
+  });
+  stdoutLogger.info(`UserPromptSubmit hook: ${result.hooks.userPromptSubmit === "added" ? "removed" : "not present"}`);
+  stdoutLogger.info(`PostToolUse hook: ${result.hooks.postToolUse === "added" ? "removed" : "not present"}`);
+  stdoutLogger.info(`Stop hook: ${result.hooks.stop === "added" ? "removed" : "not present"}`);
+  if (result.backupPath) stdoutLogger.info(`hooks.json backed up: ${result.backupPath}`);
+});
+codexHook.command("diagnostics").description("Check local Codex hook availability").option("--codex-home <path>", "Codex home directory", process.env.CODEX_HOME ?? `${process.env.HOME}/.codex`).action(async (opts) => {
+  await runCodexHook("diagnostics", opts.codexHome);
+});
+codexHook.command("user-prompt-submit").description("Run the Codex UserPromptSubmit hook").action(async () => {
+  await runCodexHook("user-prompt-submit");
+});
+codexHook.command("post-tool-use").description("Run the Codex PostToolUse hook").action(async () => {
+  await runCodexHook("post-tool-use");
+});
+codexHook.command("stop").description("Run the Codex Stop hook").action(async () => {
+  await runCodexHook("stop");
+});
+codexHook.command("worker <workFile>").description("Run the detached Codex hook worker").action(async (workFile) => {
+  await runCodexHook("worker", workFile);
+});
 var codexSidecar = program.command("codex-sidecar").description("Check Codex sidecar availability for the current repository");
 codexSidecar.command("diagnostics").description("Run codex-sidecar diagnostics for this repository").option("--project <path>", "repository root to check").option("--preset <preset>", "codex-sidecar preset", "review").option("--command <command>", "codex-sidecar executable", "codex-sidecar").option("--node-cli <path>", "development path to codex-sidecar CLI JS").option("--save-result <path>", "write structured SidecarResult JSON to this path").action((opts) => {
   runCodexSidecarDiagnostics(stdoutLogger, opts);