caveat-cli 0.16.0 → 0.16.2

package/dist/index.js

@@ -11,11 +11,12 @@ import {
   __export,
   __toESM,
   acquireReindexLock,
-  appendPendingReminder,
+  buildAndPublishPendingReminder,
   buildCodexSidecarDiagnosticsCommand,
   buildCodexSidecarReadOnlySmokeCommand,
   buildCodexSidecarRunCommand,
   buildHookSignalSidecarContextBlock,
+  buildPendingSemanticKey,
   caveatEntriesToSidecarContextBlocks,
   cleanupStalePendingDirs,
   communityAdd,
@@ -26,11 +27,11 @@ import {
   createKeyserverKeyProvider,
   decideCodexSidecarExecution,
   defaultSelfIdentityTokens,
-  drainGlobalPendingReminders,
-  drainPendingReminders,
+  drainPendingRemindersDetailed,
   ensureUserConfig,
   findCaveatHome,
-  findCaveatsForPrompt,
+  findCaveatsForHook,
+  findCaveatsForHookSegments,
   get,
   hasAnyStruggleSignal,
   initOwnSync,
@@ -63,7 +64,7 @@ import {
   userPromptSubmitReminderText,
   writeDigestMarker,
   writeUserConfigPatch
-} from "./chunk-ZNAFNCPW.js";
+} from "./chunk-3MLJQLWY.js";
 
 // ../../node_modules/.pnpm/ajv@8.18.0/node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS({
@@ -7075,6 +7076,7 @@ function uninstallClaudeIntegration(opts) {
 // src/codexHookInstall.ts
 import { copyFileSync as copyFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname3, join as join4 } from "node:path";
+import { parse as parseToml } from "smol-toml";
 function quote2(p) {
   return p.includes(" ") ? `"${p}"` : p;
 }
@@ -7154,74 +7156,183 @@ function removeHook2(hooksJson, event, command, subcommand) {
   return true;
 }
 function enableCodexHooksFeature(raw) {
-  const lines = raw.split(/\r?\n/);
-  const unsupportedFeatureShape = lines.find(
-    (line) => /^\s*(?:["']features["']|features)\s*(?:\.|=)/.test(line) || /^\s*\[\[?\s*(?:["']features["']|features\.)/.test(line)
-  );
-  if (unsupportedFeatureShape) {
+  let parsed;
+  try {
+    parsed = parseToml(raw);
+  } catch {
     return {
       status: "blocked",
       text: raw,
       changed: false,
-      reason: "config.toml uses a non-canonical features table shape that Caveat will not rewrite safely"
+      reason: "config.toml is invalid TOML; fix it before installing Caveat hooks"
     };
   }
-  const featureHeaders = lines.map((line, index) => /^\s*\[features]\s*(?:#.*)?$/.test(line) ? index : -1).filter((index) => index >= 0);
-  if (featureHeaders.length > 1) {
+  const featureValue = parsed.features;
+  if (featureValue !== void 0 && !isPlainRecord(featureValue)) {
+    return {
+      status: "blocked",
+      text: raw,
+      changed: false,
+      reason: "config.toml features value is not a table"
+    };
+  }
+  const features = featureValue;
+  const canonicalValue = features?.hooks;
+  const legacyValue = features?.codex_hooks;
+  if (canonicalValue !== void 0 && typeof canonicalValue !== "boolean") {
+    return { status: "blocked", text: raw, changed: false, reason: "[features].hooks must be boolean" };
+  }
+  if (legacyValue !== void 0 && typeof legacyValue !== "boolean") {
+    return { status: "blocked", text: raw, changed: false, reason: "[features].codex_hooks must be boolean" };
+  }
+  if (canonicalValue === false) {
+    return { status: "blocked", text: raw, changed: false, reason: "[features].hooks is explicitly false" };
+  }
+  if (legacyValue === false) {
     return {
       status: "blocked",
       text: raw,
       changed: false,
-      reason: "config.toml contains more than one [features] table"
+      reason: canonicalValue === true ? "[features].hooks conflicts with the deprecated codex_hooks alias" : "[features].codex_hooks is explicitly false"
     };
   }
-  const featuresStart = featureHeaders[0] ?? -1;
-  if (featuresStart === -1) {
+  if (canonicalValue === true && legacyValue === void 0) {
+    return { status: "enabled", text: raw, changed: false };
+  }
+  const lines = raw.split(/\r?\n/);
+  const codeLines = maskTomlStringsAndComments(raw).split(/\r?\n/);
+  const featureHeaders = codeLines.map((line, index) => /^\s*\[\s*features\s*]\s*$/.test(line) ? index : -1).filter((index) => index >= 0);
+  if (featureValue === void 0) {
     const prefix = raw.trimEnd();
     const text = `${prefix}${prefix ? "\n\n" : ""}[features]
-codex_hooks = true
+hooks = true
 `;
     return { status: "enabled", text, changed: true };
   }
+  if (featureHeaders.length !== 1) {
+    return {
+      status: "blocked",
+      text: raw,
+      changed: false,
+      reason: "config.toml uses a features table shape that Caveat will not rewrite safely"
+    };
+  }
+  const featuresStart = featureHeaders[0];
   const assignments = [];
   for (let i = featuresStart + 1; i < lines.length; i += 1) {
-    if (/^\s*\[\[?.+?\]?]\s*(?:#.*)?$/.test(lines[i])) {
+    if (/^\s*\[\[?/.test(codeLines[i])) {
       break;
     }
-    const assignment = /^\s*codex_hooks\s*=\s*([^#]*?)\s*(?:#.*)?$/.exec(lines[i]);
+    const assignment = /^\s*(hooks|codex_hooks)\s*=/.exec(codeLines[i]);
     if (assignment) {
-      assignments.push({ index: i, value: assignment[1].trim() });
-    } else if (/^\s*["']codex_hooks["']\s*=/.test(lines[i])) {
-      return {
-        status: "blocked",
-        text: raw,
-        changed: false,
-        reason: "[features].codex_hooks uses a quoted key that Caveat will not rewrite safely"
-      };
+      assignments.push({ index: i, key: assignment[1] });
     }
   }
-  if (assignments.length > 1) {
+  const canonical = assignments.filter((assignment) => assignment.key === "hooks");
+  const legacy = assignments.filter((assignment) => assignment.key === "codex_hooks");
+  if (canonicalValue !== void 0 && canonical.length !== 1 || legacyValue !== void 0 && legacy.length !== 1) {
     return {
       status: "blocked",
       text: raw,
       changed: false,
-      reason: "[features].codex_hooks is defined more than once"
+      reason: "[features].hooks uses a key shape that Caveat will not rewrite safely"
     };
   }
-  const existing = assignments[0];
-  if (existing) {
-    if (existing.value === "true") return { status: "enabled", text: raw, changed: false };
-    return {
-      status: "blocked",
-      text: raw,
-      changed: false,
-      reason: `[features].codex_hooks is explicitly ${existing.value || "set to a non-true value"}`
-    };
+  const current = canonical[0];
+  const deprecated = legacy[0];
+  if (canonicalValue === true && legacyValue === true && current && deprecated) {
+    const inlineComment = /(#.*)$/.exec(lines[deprecated.index])?.[1];
+    lines.splice(deprecated.index, 1);
+    if (inlineComment) {
+      const canonicalIndex = current.index > deprecated.index ? current.index - 1 : current.index;
+      lines.splice(canonicalIndex + 1, 0, inlineComment);
+    }
+    return { status: "enabled", text: `${lines.join("\n").trimEnd()}
+`, changed: true };
   }
-  lines.splice(featuresStart + 1, 0, "codex_hooks = true");
+  if (legacyValue === true && canonicalValue === void 0 && deprecated) {
+    lines[deprecated.index] = lines[deprecated.index].replace(/\bcodex_hooks\b/, "hooks");
+    return { status: "enabled", text: `${lines.join("\n").trimEnd()}
+`, changed: true };
+  }
+  lines.splice(featuresStart + 1, 0, "hooks = true");
   return { status: "enabled", text: `${lines.join("\n").trimEnd()}
 `, changed: true };
 }
+function isPlainRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function maskTomlStringsAndComments(raw) {
+  let state = "code";
+  let output = "";
+  for (let i = 0; i < raw.length; i += 1) {
+    const char = raw[i];
+    const triple = raw.slice(i, i + 3);
+    if (char === "\n") {
+      output += "\n";
+      if (state === "comment") state = "code";
+      continue;
+    }
+    if (state === "comment") {
+      output += " ";
+      continue;
+    }
+    if (state === "basic") {
+      output += " ";
+      if (char === "\\" && i + 1 < raw.length) {
+        output += raw[i + 1] === "\n" ? "\n" : " ";
+        i += 1;
+      } else if (char === '"') state = "code";
+      continue;
+    }
+    if (state === "literal") {
+      output += " ";
+      if (char === "'") state = "code";
+      continue;
+    }
+    if (state === "multi-basic") {
+      if (triple === '"""') {
+        output += "   ";
+        i += 2;
+        state = "code";
+      } else {
+        output += " ";
+        if (char === "\\" && i + 1 < raw.length) {
+          output += raw[i + 1] === "\n" ? "\n" : " ";
+          i += 1;
+        }
+      }
+      continue;
+    }
+    if (state === "multi-literal") {
+      if (triple === "'''") {
+        output += "   ";
+        i += 2;
+        state = "code";
+      } else output += " ";
+      continue;
+    }
+    if (char === "#") {
+      output += " ";
+      state = "comment";
+    } else if (triple === '"""') {
+      output += "   ";
+      i += 2;
+      state = "multi-basic";
+    } else if (triple === "'''") {
+      output += "   ";
+      i += 2;
+      state = "multi-literal";
+    } else if (char === '"') {
+      output += " ";
+      state = "basic";
+    } else if (char === "'") {
+      output += " ";
+      state = "literal";
+    } else output += char;
+  }
+  return output;
+}
 function writeConfigWithBackup(path, text) {
   const dir = dirname3(path);
   if (!existsSync2(dir)) mkdirSync2(dir, { recursive: true });
@@ -7269,7 +7380,7 @@ function installCodexHooks(opts) {
   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}`);
+    opts.logger.info(`[dry-run] would ensure [features].hooks = true in ${configPath}`);
   } else {
     if (anyHookAdded) {
       const backup = writeJsonWithBackup(hooksPath, hooksJson);
@@ -7434,6 +7545,16 @@ import { spawnSync as spawnSync3 } from "node:child_process";
 import { mkdtempSync, readFileSync as readFileSync4, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join as join6 } from "node:path";
+var DEFAULT_HOOK_SIDECAR_TIMEOUT_MS = 12e4;
+var MAX_HOOK_SIDECAR_TIMEOUT_MS = 24e4;
+function resolveHookSidecarTimeoutMs(raw) {
+  if (raw === void 0) return DEFAULT_HOOK_SIDECAR_TIMEOUT_MS;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_HOOK_SIDECAR_TIMEOUT_MS) {
+    throw new Error(`CAVEAT_HOOK_CODEX_SIDECAR_TIMEOUT_MS must be an integer from 1 to ${MAX_HOOK_SIDECAR_TIMEOUT_MS}`);
+  }
+  return value;
+}
 function compactFailureMessage(message) {
   const singleLine = message.replace(/\s+/g, " ").trim();
   if (!singleLine) return "unknown error";
@@ -7497,7 +7618,9 @@ function runCodexSidecarAdvisory(input) {
     const result = spawnSync3(process.execPath, args, {
       cwd: input.projectRoot,
       encoding: "utf-8",
-      timeout: Number(process.env.CAVEAT_HOOK_CODEX_SIDECAR_TIMEOUT_MS ?? 12e4),
+      // Keep at least one minute between the longest supported model call and
+      // the pending single-flight claim TTL (five minutes).
+      timeout: resolveHookSidecarTimeoutMs(process.env.CAVEAT_HOOK_CODEX_SIDECAR_TIMEOUT_MS),
       maxBuffer: 10 * 1024 * 1024
     });
     if (result.error) {
@@ -7794,7 +7917,7 @@ async function runInit(ctx, opts = { skipClaude: false, dryRun: false }, depende
       if (result.feature === "blocked") {
         codexHookState = "skipped";
         ctx.logger.warn(
-          `${result.blockedReason}; preserving explicit consent. Set \`codex_hooks = true\` in ${join8(codexHome, "config.toml")}, then rerun \`caveat init\`.`
+          `${result.blockedReason}; preserving explicit consent. Set \`hooks = true\` in ${join8(codexHome, "config.toml")}, then rerun \`caveat init\`.`
         );
       } else if (opts.dryRun) {
         codexHookState = "skipped";
@@ -8095,7 +8218,7 @@ function runStats(ctx) {
 
 // src/commands/serve.ts
 async function runServe(opts) {
-  const { startServer } = await import("./server-SZAVLE56.js");
+  const { startServer } = await import("./server-LAJCQXS3.js");
   const { port, host } = startServer({ port: opts.port });
   process.stdout.write(`[caveat] web portal: http://${host}:${port}/
 `);
@@ -32560,8 +32683,10 @@ function buildContextSafely() {
     return null;
   }
 }
-function searchCaveatsFromTextSafely(text, surface) {
-  if (!text) return [];
+function searchCaveatsSafely(input) {
+  const inputs = Array.isArray(input) ? input : [input];
+  const queryForLog = inputs.map((item) => item.surface === "user_prompt" ? item.topicText || item.failureText : item.failureText).filter(Boolean).join("\n");
+  if (inputs.length === 0 || inputs.every((item) => !item.topicText && !item.failureText)) return [];
   let db;
   let caveatHome;
   let hits;
@@ -32570,9 +32695,10 @@ function searchCaveatsFromTextSafely(text, surface) {
     if (!ctx || !existsSync10(ctx.paths.dbPath)) return [];
     caveatHome = ctx.caveatHome;
     db = openDb({ path: ctx.paths.dbPath });
-    hits = findCaveatsForPrompt(db, text, {
+    const searchOptions = {
       selfIdentity: defaultSelfIdentityTokens()
-    });
+    };
+    hits = inputs.length === 1 ? findCaveatsForHook(db, inputs[0], searchOptions) : findCaveatsForHookSegments(db, inputs, searchOptions);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[caveat:hook] search error: ${msg}
@@ -32589,7 +32715,7 @@ function searchCaveatsFromTextSafely(text, surface) {
     }
   } else {
     try {
-      logHookQueryMiss({ caveatHome, agent: "claude", surface, query: text });
+      logHookQueryMiss({ caveatHome, agent: "claude", surface: inputs[0].surface, query: queryForLog });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`[caveat:hook] query log error: ${msg}
@@ -32615,13 +32741,19 @@ function loadSignalsSafely(path) {
 function systemReminderOutput(text) {
   return `<system-reminder>${text.replace(/</g, "\u2039").replace(/>/g, "\u203A")}</system-reminder>`;
 }
+function claudePendingCleanupFailureText() {
+  return "[caveat:hook] pending reminder cleanup failed";
+}
 function drainForSession(sessionId) {
   const ctx = buildContextSafely();
   if (!ctx) return [];
-  return [
-    ...drainPendingReminders(ctx.caveatHome, sessionId),
-    ...drainGlobalPendingReminders(ctx.caveatHome)
-  ];
+  const local = drainPendingRemindersDetailed(ctx.caveatHome, sessionId);
+  const global = drainPendingRemindersDetailed(ctx.caveatHome, "_global");
+  for (const _failure of [...local.cleanupFailures, ...global.cleanupFailures]) {
+    process.stderr.write(`${claudePendingCleanupFailureText()}
+`);
+  }
+  return [...local.reminders, ...global.reminders];
 }
 function claudeContextDedupeKey(text) {
   if (text.startsWith(CLAUDE_STOP_REMINDER_PREFIX)) return "claude-stop-reminder";
@@ -32640,7 +32772,7 @@ function compactClaudeContexts(contexts) {
   }
   selected.reverse();
   const limited = selected.slice(-CLAUDE_MAX_CONTEXT_BLOCKS);
-  const omitted = contexts.filter((t) => t.trim().length > 0).length - limited.length;
+  const omitted = selected.length - limited.length;
   if (omitted > 0) {
     limited.push(
       `[caveat] pending reminder ${omitted} \u4EF6\u3092\u91CD\u8907\u307E\u305F\u306F\u4E0A\u9650\u306B\u3088\u308A\u7701\u7565\u3057\u307E\u3057\u305F\u3002`
@@ -32685,8 +32817,20 @@ function queueStopForSession(sessionId, signals, related) {
   if (!ctx) return;
   const key = stopSignalKey(signals, related);
   if (wasStopReminderQueued(ctx.caveatHome, sessionId, key)) return;
+  let result;
+  try {
+    result = buildAndPublishPendingReminder(ctx.caveatHome, sessionId, buildPendingSemanticKey({
+      agent: "claude",
+      surface: "stop",
+      refs: related,
+      stopSignalDigest: key
+    }), () => buildStopReminder(signals, related));
+  } catch {
+    process.stderr.write("[caveat:hook] pending reminder build or publish failed\n");
+    return;
+  }
+  if (!result.ran) return;
   try {
-    appendPendingReminder(ctx.caveatHome, sessionId, buildStopReminder(signals, related));
     markStopReminderQueued(ctx.caveatHome, sessionId, key);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -32717,6 +32861,20 @@ function extractToolResponseText(response) {
   }
   return "";
 }
+function toolTopicText(payload) {
+  const parts = [];
+  const toolName = payload.tool_name ?? payload.toolName;
+  if (typeof toolName === "string") parts.push(toolName);
+  const input = payload.tool_input ?? payload.toolInput;
+  if (typeof input === "string") parts.push(input);
+  if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+    const record2 = input;
+    for (const key of ["command", "cmd", "query", "url"]) {
+      if (typeof record2[key] === "string") parts.push(record2[key]);
+    }
+  }
+  return parts.join("\n");
+}
 function isToolError(payload) {
   if (payload.hook_event_name === "PostToolUseFailure") return true;
   const resp = payload.tool_response ?? payload.toolResponse;
@@ -32740,7 +32898,7 @@ function spawnWorker(job) {
     workDir = mkdtempSync2(join12(root, "job-"));
     chmodSync(workDir, 448);
     workFile = join12(workDir, `${randomBytes(4).toString("hex")}.json`);
-    writeFileSync5(workFile, JSON.stringify({ ...job, schemaVersion: "caveat-worker-job/v1" }), { encoding: "utf-8", mode: 384, flag: "wx" });
+    writeFileSync5(workFile, JSON.stringify({ ...job, schemaVersion: "caveat-worker-job/v2" }), { encoding: "utf-8", mode: 384, flag: "wx" });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[caveat:hook] worker writefile error: ${msg}
@@ -32784,15 +32942,27 @@ async function runWorker(workFile) {
   } catch {
     process.exit(0);
   }
-  if (!job.searchText || !job.sessionId) process.exit(0);
-  const hits = searchCaveatsFromTextSafely(job.searchText, "tool_error");
+  if (!job.failureText || !job.sessionId) process.exit(0);
+  const hits = searchCaveatsSafely({
+    topicText: job.topicText,
+    failureText: job.failureText,
+    surface: "tool_error"
+  });
   if (hits.length === 0) process.exit(0);
   const ctx = buildContextSafely();
   if (!ctx) process.exit(0);
+  let result;
   try {
-    appendPendingReminder(ctx.caveatHome, job.sessionId, buildToolErrorReminder(job, hits));
+    result = buildAndPublishPendingReminder(ctx.caveatHome, job.sessionId, buildPendingSemanticKey({
+      agent: "claude",
+      surface: "tool_error",
+      refs: hits
+    }), () => buildToolErrorReminder(job, hits));
   } catch {
+    process.stderr.write("[caveat:hook] pending reminder build or publish failed\n");
+    process.exit(0);
   }
+  if (!result.ran) process.exit(0);
   process.exit(0);
 }
 function cleanupWorkerDir(workDir, root) {
@@ -32859,12 +33029,20 @@ function isStaleWorkerJobDir(path) {
   const stat = lstatSync(file2);
   const uid = typeof process.getuid === "function" ? process.getuid() : void 0;
   if (!stat.isFile() || stat.isSymbolicLink() || !hasPrivateOwnership(stat, uid)) return false;
-  return isWorkerJob(JSON.parse(readFileSync5(file2, "utf-8")));
+  return isKnownStaleWorkerJob(JSON.parse(readFileSync5(file2, "utf-8")));
 }
 function hasPrivateOwnership(stat, uid) {
   return process.platform === "win32" || (stat.mode & 63) === 0 && (uid === void 0 || stat.uid === uid);
 }
 function isWorkerJob(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const job = value;
+  const keys = Object.keys(job).sort();
+  if (!(keys.length === 4 && keys.join(",") === "failureText,schemaVersion,sessionId,topicText") && !(keys.length === 5 && keys.join(",") === "additionalContext,failureText,schemaVersion,sessionId,topicText")) return false;
+  return job.schemaVersion === "caveat-worker-job/v2" && typeof job.sessionId === "string" && typeof job.topicText === "string" && typeof job.failureText === "string" && (job.additionalContext === void 0 || job.additionalContext !== null && typeof job.additionalContext === "object" && !Array.isArray(job.additionalContext));
+}
+function isKnownStaleWorkerJob(value) {
+  if (isWorkerJob(value)) return true;
   if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
   const job = value;
   const keys = Object.keys(job).sort();
@@ -32960,7 +33138,7 @@ function buildToolErrorReminder(job, hits) {
   const hasSidecarConfig = existsSync10(join12(projectRoot, ".codex-sidecar.yml"));
   if (mode === "auto" && !hasSidecarConfig) return base;
   const advisory = runCodexSidecarAdvisory({
-    searchText: job.searchText,
+    searchText: job.failureText,
     limit: hits.length,
     projectRoot,
     prompt: [
@@ -33060,7 +33238,7 @@ async function runHook(name, arg) {
   const contexts = name === "stop" ? [] : drainForSession(sessionId);
   if (name === "user-prompt-submit") {
     const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
-    const hits = searchCaveatsFromTextSafely(prompt, "user_prompt");
+    const hits = searchCaveatsSafely({ topicText: prompt, failureText: prompt, surface: "user_prompt" });
     if (hits.length > 0) {
       contexts.push(userPromptSubmitReminderText(hits));
     }
@@ -33088,7 +33266,8 @@ async function runHook(name, arg) {
         toolName: payload.tool_name ?? payload.toolName,
         failureKind
       });
-      spawnWorker({ sessionId, searchText: errText, ...additionalContext ? { additionalContext } : {} });
+      const topicText = toolTopicText(payload);
+      spawnWorker({ sessionId, topicText, failureText: errText, ...additionalContext ? { additionalContext } : {} });
     }
     process.exit(0);
   }
@@ -33121,7 +33300,11 @@ async function runHook(name, arg) {
     const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
     const signals = transcriptPath ? loadSignalsSafely(transcriptPath) : null;
     if (!signals || !hasAnyStruggleSignal(signals)) process.exit(0);
-    const related = searchCaveatsFromTextSafely(struggleSearchText(signals), "stop");
+    const related = searchCaveatsSafely(signals.errorSnippets.map((failureText) => ({
+      topicText: "",
+      failureText,
+      surface: "stop"
+    })));
     queueStopForSession(sessionId, signals, related);
     process.exit(0);
   }
@@ -33175,8 +33358,10 @@ function buildContextSafely2() {
     return null;
   }
 }
-function searchCaveatsFromTextSafely2(text, surface) {
-  if (!text) return [];
+function searchCaveatsSafely2(input) {
+  const inputs = Array.isArray(input) ? input : [input];
+  const queryForLog = inputs.map((item) => item.surface === "user_prompt" ? item.topicText || item.failureText : item.failureText).filter(Boolean).join("\n");
+  if (inputs.length === 0 || inputs.every((item) => !item.topicText && !item.failureText)) return [];
   let db;
   let caveatHome;
   let hits;
@@ -33185,9 +33370,10 @@ function searchCaveatsFromTextSafely2(text, surface) {
     if (!ctx || !existsSync11(ctx.paths.dbPath)) return [];
     caveatHome = ctx.caveatHome;
     db = openDb({ path: ctx.paths.dbPath });
-    hits = findCaveatsForPrompt(db, text, {
+    const searchOptions = {
       selfIdentity: defaultSelfIdentityTokens()
-    });
+    };
+    hits = inputs.length === 1 ? findCaveatsForHook(db, inputs[0], searchOptions) : findCaveatsForHookSegments(db, inputs, searchOptions);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[caveat:codex-hook] search error: ${msg}
@@ -33204,7 +33390,7 @@ function searchCaveatsFromTextSafely2(text, surface) {
     }
   } else {
     try {
-      logHookQueryMiss({ caveatHome, agent: "codex", surface, query: text });
+      logHookQueryMiss({ caveatHome, agent: "codex", surface: inputs[0].surface, query: queryForLog });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`[caveat:codex-hook] query log error: ${msg}
@@ -33333,15 +33519,17 @@ function buildCodexPostToolUseWorkerJob(payload) {
   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 topicText = inputText.trim();
+  const failureText = [responseText, transcriptOutput ?? ""].map((s) => s.trim()).filter(Boolean).join("\n");
   const knownError = isCodexToolError(payload);
   if (knownError) {
-    return { sessionId, searchText, knownError: true, transcriptPath, toolUseId };
+    return { sessionId, topicText, failureText, knownError: true, transcriptPath, toolUseId };
   }
-  if (transcriptPath && toolUseId && isShellLikeTool(payload) && searchText) {
+  if (transcriptPath && toolUseId && isShellLikeTool(payload) && (topicText || failureText)) {
     return {
       sessionId,
-      searchText,
+      topicText,
+      failureText,
       knownError: false,
       allowSymptomOnly: true,
       transcriptPath,
@@ -33358,13 +33546,19 @@ function codexContextOutput(text, eventName = "UserPromptSubmit") {
     }
   });
 }
+function codexPendingCleanupFailureText() {
+  return "[caveat:codex-hook] pending reminder cleanup failed";
+}
 function drainForSession2(sessionId) {
   const ctx = buildContextSafely2();
   if (!ctx) return [];
-  return [
-    ...drainPendingReminders(ctx.caveatHome, sessionId),
-    ...drainGlobalPendingReminders(ctx.caveatHome)
-  ];
+  const local = drainPendingRemindersDetailed(ctx.caveatHome, sessionId);
+  const global = drainPendingRemindersDetailed(ctx.caveatHome, "_global");
+  for (const _failure of [...local.cleanupFailures, ...global.cleanupFailures]) {
+    process.stderr.write(`${codexPendingCleanupFailureText()}
+`);
+  }
+  return [...local.reminders, ...global.reminders];
 }
 function codexContextDedupeKey(text) {
   if (text.startsWith(CODEX_STOP_REMINDER_PREFIX)) return "codex-stop-reminder";
@@ -33383,7 +33577,7 @@ function compactCodexContexts(contexts) {
   }
   selected.reverse();
   const limited = selected.slice(-CODEX_MAX_CONTEXT_BLOCKS);
-  const omitted = contexts.filter((t) => t.trim().length > 0).length - limited.length;
+  const omitted = selected.length - limited.length;
   if (omitted > 0) {
     limited.push(`[caveat] pending reminder ${omitted} \u4EF6\u3092\u91CD\u8907\u307E\u305F\u306F\u4E0A\u9650\u306B\u3088\u308A\u7701\u7565\u3057\u307E\u3057\u305F\u3002`);
   }
@@ -33426,8 +33620,20 @@ function queueStopForSession2(sessionId, signals, related) {
   if (!ctx) return;
   const key = stopSignalKey2(signals, related);
   if (wasStopReminderQueued2(ctx.caveatHome, sessionId, key)) return;
+  let result;
+  try {
+    result = buildAndPublishPendingReminder(ctx.caveatHome, sessionId, buildPendingSemanticKey({
+      agent: "codex",
+      surface: "stop",
+      refs: related,
+      stopSignalDigest: key
+    }), () => stopReminderText(signals, related));
+  } catch {
+    process.stderr.write("[caveat:codex-hook] pending reminder build or publish failed\n");
+    return;
+  }
+  if (!result.ran) return;
   try {
-    appendPendingReminder(ctx.caveatHome, sessionId, stopReminderText(signals, related));
     markStopReminderQueued2(ctx.caveatHome, sessionId, key);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -33445,8 +33651,8 @@ async function waitForTranscriptOutput(transcriptPath, toolUseId) {
   return null;
 }
 async function processCodexWorkerJob(job, opts = { waitForTranscript: true }) {
-  if (!job.searchText || !job.sessionId) return;
-  let searchText = job.searchText;
+  if (!job.topicText && !job.failureText || !job.sessionId) return;
+  let failureText = job.failureText;
   let knownError = job.knownError === true;
   if (opts.waitForTranscript && job.transcriptPath && job.toolUseId) {
     const transcriptOutput = await waitForTranscriptOutput(job.transcriptPath, job.toolUseId);
@@ -33456,18 +33662,30 @@ async function processCodexWorkerJob(job, opts = { waitForTranscript: true }) {
         if (exit2 === 0) return;
         knownError = true;
       }
-      searchText = [searchText, transcriptOutput].filter(Boolean).join("\n");
+      failureText = [failureText, transcriptOutput].filter(Boolean).join("\n");
     }
   }
   if (!knownError && job.allowSymptomOnly !== true) return;
-  const hits = searchCaveatsFromTextSafely2(searchText, "tool_error");
+  const hits = searchCaveatsSafely2({
+    topicText: job.topicText,
+    failureText,
+    surface: "tool_error"
+  });
   if (hits.length === 0) return;
   const ctx = buildContextSafely2();
   if (!ctx) return;
+  let result;
   try {
-    appendPendingReminder(ctx.caveatHome, job.sessionId, toolErrorReminderText(hits));
+    result = buildAndPublishPendingReminder(ctx.caveatHome, job.sessionId, buildPendingSemanticKey({
+      agent: "codex",
+      surface: "tool_error",
+      refs: hits
+    }), () => toolErrorReminderText(hits));
   } catch {
+    process.stderr.write("[caveat:codex-hook] pending reminder build or publish failed\n");
+    return;
   }
+  if (!result.ran) return;
 }
 async function runCodexWorker(workFile) {
   let raw;
@@ -33492,10 +33710,11 @@ async function runCodexWorker(workFile) {
 function runDiagnostics(codexHome = process.env.CODEX_HOME ?? join13(homedir3(), ".codex")) {
   const features = spawnSync5("codex", ["features", "list"], {
     encoding: "utf-8",
-    maxBuffer: 1024 * 1024
+    maxBuffer: 1024 * 1024,
+    env: codexFeatureListEnv(codexHome)
   });
   const featureOutput = [features.stdout, features.stderr].filter(Boolean).join("\n");
-  const hasHooks = /^codex_hooks\s+\S+\s+true\b/m.test(featureOutput);
+  const hasHooks = /^hooks\s+\S+\s+true\b/m.test(featureOutput);
   const installation = detectCodexHookInstallation(codexHome);
   const result = {
     availability: features.error || features.status !== 0 || !hasHooks ? "unavailable" : "available",
@@ -33505,11 +33724,14 @@ function runDiagnostics(codexHome = process.env.CODEX_HOME ?? join13(homedir3(),
     codexHome,
     hooksPath: installation.hooksPath,
     installedHooks: installation.hooks,
-    evidence: featureOutput.split("\n").find((line) => line.trim().startsWith("codex_hooks")) ?? null
+    evidence: featureOutput.split("\n").find((line) => line.trim().startsWith("hooks")) ?? null
   };
   process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
 }
+function codexFeatureListEnv(codexHome, inherited = process.env) {
+  return { ...inherited, CODEX_HOME: codexHome };
+}
 async function runCodexHook(name, arg) {
   if (name === "diagnostics") {
     runDiagnostics(arg);
@@ -33535,7 +33757,7 @@ async function runCodexHook(name, arg) {
   if (name === "user-prompt-submit") {
     const contexts = sessionId ? drainForSession2(sessionId) : [];
     const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
-    const hits = searchCaveatsFromTextSafely2(prompt, "user_prompt");
+    const hits = searchCaveatsSafely2({ topicText: prompt, failureText: prompt, surface: "user_prompt" });
     if (hits.length > 0) {
       contexts.push(userPromptSubmitReminderText(hits));
     }
@@ -33580,7 +33802,11 @@ async function runCodexHook(name, arg) {
     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), "stop");
+    const related = searchCaveatsSafely2(signals.errorSnippets.map((failureText) => ({
+      topicText: "",
+      failureText,
+      surface: "stop"
+    })));
     if (sessionId) queueStopForSession2(sessionId, signals, related);
     process.exit(0);
   }
@@ -34068,7 +34294,7 @@ program.command("hook <name> [arg]").description(
   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) => {
+codexHook.command("install").description("Install Caveat hooks into ~/.codex/hooks.json and enable 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");
@@ -34084,10 +34310,10 @@ codexHook.command("install").description("Install Caveat hooks into ~/.codex/hoo
   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}`);
+  stdoutLogger.info(`hooks feature: ${result.feature}`);
   if (result.feature === "blocked") {
     stdoutLogger.warn(
-      `${result.blockedReason}; preserving explicit consent. Set \`codex_hooks = true\` in ${opts.codexHome}/config.toml, then rerun \`caveat codex-hook install\`.`
+      `${result.blockedReason}; preserving explicit consent. Set \`hooks = true\` in ${opts.codexHome}/config.toml, then rerun \`caveat codex-hook install\`.`
     );
   }
   if (result.backupPath) stdoutLogger.info(`hooks.json backed up: ${result.backupPath}`);