agent-sanitizer 2.68.0 → 2.69.0

package/claude-hooks/scan-invisible-chars.mjs

@@ -25,7 +25,7 @@ import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import {
   awaitLazyDependency,
-  emitHookResponse,
+  createEnvelopeBuffer,
   safeErrMessage,
   hookgateMarkerPath,
   HookEvent,
@@ -157,36 +157,76 @@ function faultLine(ctx) {
   );
 }
 
-// This hook's entry in the one posture table (lib/hook-fault.mjs). It has no
-// stdout verdict channel — SessionStart cannot deny — so BOTH arms are stated
-// explicitly rather than taking the shared additionalContext default: the only
-// enforcement a SessionStart hook can reach is the cross-hook alert, which makes
-// the PreToolUse gate ask once on the next tool call.
+/**
+ * The open-posture parts for instruction files the scan could not READ, or null
+ * when the fault is anything else. Exit 0 with an envelope, not the fault arm's
+ * bare exit 1: the hook ran and is reporting what it could not check, so the
+ * user (systemMessage) and the model (additionalContext) are both told, and the
+ * launcher forwards it rather than reporting a broken bundle.
+ * @param {import("./lib/hook-fault.mjs").FaultContext} ctx
+ * @returns {import("./lib/hook-fault.mjs").FaultParts | null}
+ */
+function openGapParts(ctx) {
+  if (ctx.gapNotice === undefined) return null;
+  const warning =
+    `${ctx.gapNotice}\n${HOOK_NAME}: failing open — nothing is blocked. Set ` +
+    "AGENT_SANITIZER_FAIL_OPEN=0 to have the next tool call ask instead.";
+  return {
+    stderr: `${warning}\n`,
+    envelope: {
+      systemMessage: warning,
+      hookSpecificOutput: {
+        hookEventName: HookEvent.SESSION_START,
+        additionalContext: warning,
+      },
+    },
+  };
+}
+
+// This hook's entry in the one posture table (lib/hook-fault.mjs). SessionStart
+// cannot deny, so the only enforcement either arm can reach is the cross-hook
+// alert, which makes the PreToolUse gate ask once on the next tool call — and
+// only the CLOSED arm arms it. An unreadable instruction file (`gapNotice`) is
+// rendered here too: the scan worked, but whether a gap may stop the session is
+// the same operator choice a fault is.
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.SESSION_START,
   guarded: "instruction files",
-  open: (ctx) => ({
-    stderr: `${faultLine(ctx)} Passing through unguarded; set AGENT_SANITIZER_FAIL_OPEN=0 to arm the tool-call gate instead.\n`,
-    exitCode: 1,
-  }),
-  closed: (ctx) => ({
-    stderr: `${faultLine(ctx)} Arming the tool-call gate (AGENT_SANITIZER_FAIL_OPEN=0).\n`,
-    exitCode: 1,
-    armAlert: true,
-  }),
+  open: (ctx) =>
+    openGapParts(ctx) ?? {
+      stderr: `${faultLine(ctx)} Passing through unguarded; set AGENT_SANITIZER_FAIL_OPEN=0 to arm the tool-call gate instead.\n`,
+      exitCode: 1,
+    },
+  closed: (ctx) =>
+    ctx.gapNotice === undefined
+      ? {
+          stderr: `${faultLine(ctx)} Arming the tool-call gate (AGENT_SANITIZER_FAIL_OPEN=0).\n`,
+          exitCode: 1,
+          armAlert: true,
+        }
+      : { stderr: `${ctx.gapNotice}\n`, armAlert: true },
 });
 
 /**
- * Render this hook's fault under the declared posture, and return the text (if
- * any) that must ride in the cross-hook alert so a later gate carries the
- * posture this hook cannot express itself.
+ * Render this hook's fault (or, with `gapNotice`, its unreadable-file report)
+ * under the declared posture, and return the text (if any) that must ride in
+ * the cross-hook alert so a later gate carries the posture this hook cannot
+ * express itself.
  * @param {unknown} err
+ * @param {string | undefined} gapNotice  the {@link formatSkipped} report
+ * @param {import("./lib/hook-io.mjs").EnvelopeBuffer} out  this run's one stdout
+ *   buffer
  * @returns {string[]}
  */
-function reportFault(err) {
-  const outcome = hookFaultOutcome(HOOK_NAME, err);
-  process.exitCode = writeFaultOutcome(outcome);
-  return outcome.armAlert ? [/** @type {string} */ (outcome.stderr)] : [];
+function reportFault(err, gapNotice, out) {
+  const outcome = hookFaultOutcome(HOOK_NAME, err, { gapNotice });
+  // Buffered, not written: the timing wrapper may still owe stdout a slow-hook
+  // notice, and two envelopes on one stdout are invalid hook output.
+  process.exitCode = writeFaultOutcome(outcome, (chunk) =>
+    out.add(JSON.parse(chunk)),
+  );
+  if (!outcome.armAlert) return [];
+  return [gapNotice ?? /** @type {string} */ (outcome.stderr)];
 }
 
 /**
@@ -331,9 +371,9 @@ export function scanProject(dir = PROJECT_DIR) {
 }
 
 /**
- * The report for targets the scan could not read. Rendered into the alert the
- * PreToolUse gate surfaces, so an incomplete scan reaches the operator as a
- * checkpoint rather than as silence.
+ * The report for targets the scan could not read: a SessionStart warning under
+ * the open posture, and the alert the PreToolUse gate surfaces under the closed
+ * one — either way an incomplete scan reaches the operator rather than silence.
  * @param {Array<{file: string, reason: string}>} skipped
  * @returns {string}
  */
@@ -383,12 +423,15 @@ export async function cliMain(opts = {}) {
   // reporting an overrun in band is what turned a 30-second scan from a rumor
   // into a bug report (see lib/hook-timing.mjs).
   const timer = startHookTimer();
+  // One stdout document per run: the scan's own envelope (a fault or the
+  // unreadable-file notice) and the slow-hook notice below fold into it.
+  const out = createEnvelopeBuffer();
   try {
     // Charged to provisioning when the session's setup is installing THROUGHOUT
     // this run: that install saturates the machine, and a scan that merely
     // waited it out has no per-call cost to report (see hook-timing.mjs).
     await excludeConcurrentProvisioning(
-      () => runScanCli(opts),
+      () => runScanCli(opts, out),
       () => setupRunning(hookgateMarkerPath()),
     );
   } finally {
@@ -396,7 +439,7 @@ export async function cliMain(opts = {}) {
       HOOK_NAME,
       timer.wallMs(),
       HookEvent.SESSION_START,
-      emitHookResponse,
+      out.emit,
       undefined,
       // All four windows, including the two this scan normally leaves empty: a
       // measured 0 rules a window OUT, where an omitted one leaves the notice
@@ -407,6 +450,7 @@ export async function cliMain(opts = {}) {
         hostMs: timer.hostMs(),
       },
     );
+    out.flush();
   }
 }
 
@@ -419,9 +463,10 @@ export async function cliMain(opts = {}) {
  *   scan?: () => ReturnType<typeof scanProject>,
  *   sessionId?: string,
  * }} opts  see {@link cliMain}
+ * @param {import("./lib/hook-io.mjs").EnvelopeBuffer} out  see {@link cliMain}
  * @returns {Promise<void>}
  */
-async function runScanCli({ trace: sink, scan: runScan, sessionId }) {
+async function runScanCli({ trace: sink, scan: runScan, sessionId }, out) {
   // Bound best-effort: the announcements below run BEFORE the auto-clean and
   // the alert write, with no catch above them, so a throwing host sink would
   // abort the scan silently (see hookTrace).
@@ -452,9 +497,13 @@ async function runScanCli({ trace: sink, scan: runScan, sessionId }) {
           "agent-sanitizer failed to load (node deps not installed and " +
             "session-setup did not finish in time); run `pnpm install`",
         ),
+        undefined,
+        out,
       ),
     );
     persistAlert(alertParts, sessionId);
+    // process.exit skips cliMain's `finally`, which would otherwise flush.
+    out.flush();
     process.exit(1);
   }
   /* c8 ignore stop */
@@ -480,14 +529,14 @@ async function runScanCli({ trace: sink, scan: runScan, sessionId }) {
     scan = (runScan ?? scanProject)();
   } catch (err) {
     emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "skipped" });
-    alertParts.push(...reportFault(err));
+    alertParts.push(...reportFault(err, undefined, out));
     persistAlert(alertParts, sessionId);
     return;
   }
   const { findings: allFindings, skipped, absent, scanned } = scan;
 
   // The three buckets of classifyReadFailure, rendered: only `skipped` may
-  // withhold "clean" and arm the gate.
+  // withhold "clean", and it arms the gate only under the closed posture.
   if (skipped.length > 0) {
     emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, {
       outcome: "partial",
@@ -496,9 +545,13 @@ async function runScanCli({ trace: sink, scan: runScan, sessionId }) {
       absent: absent.length,
       files: allFindings.length,
     });
-    const notice = formatSkipped(skipped);
-    process.stderr.write(notice + "\n");
-    alertParts.push(notice);
+    alertParts.push(
+      ...reportFault(
+        new Error(`${skipped.length} instruction file(s) could not be read`),
+        formatSkipped(skipped),
+        out,
+      ),
+    );
   } else if (allFindings.length === 0) {
     emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, {
       outcome: "clean",

package/claude-hooks/scan-loaded-instructions.mjs

@@ -19,7 +19,7 @@
  */
 import { readFileSync } from "node:fs";
 import {
-  emitHookResponse,
+  createEnvelopeBuffer,
   EmptyStdinError,
   hookgateMarkerPath,
   HookEvent,
@@ -268,12 +268,15 @@ export { HOOK_NAME };
 export async function cliMain({ trace: sink } = {}) {
   const timer = startHookTimer();
   const emitTrace = hookTrace(sink);
+  // One stdout document per run: the finding/fault envelope and the slow-hook
+  // notice below fold into it, never written as two.
+  const out = createEnvelopeBuffer();
   try {
     // Charged to provisioning when the session's setup is installing THROUGHOUT
     // this run: that install saturates the machine, and a scan that merely
     // waited it out has no per-call cost to report (see hook-timing.mjs).
     await excludeConcurrentProvisioning(
-      () => runLoadedScanCli(emitTrace),
+      () => runLoadedScanCli(emitTrace, out),
       () => setupRunning(hookgateMarkerPath()),
     );
   } finally {
@@ -281,7 +284,7 @@ export async function cliMain({ trace: sink } = {}) {
       HOOK_NAME,
       timer.wallMs(),
       HookEvent.INSTRUCTIONS_LOADED,
-      emitHookResponse,
+      out.emit,
       undefined,
       // All four windows, including the two this scan normally leaves empty: a
       // measured 0 rules a window OUT, where an omitted one leaves the notice
@@ -292,6 +295,7 @@ export async function cliMain({ trace: sink } = {}) {
         hostMs: timer.hostMs(),
       },
     );
+    out.flush();
   }
 }
 
@@ -300,9 +304,11 @@ export async function cliMain({ trace: sink } = {}) {
  * single call to bracket — every early return here is an exit that wrapper must
  * still measure.
  * @param {import("./lib/trace.mjs").TraceFn} emitTrace
+ * @param {import("./lib/hook-io.mjs").EnvelopeBuffer} out  this run's one stdout
+ *   buffer
  * @returns {Promise<void>}
  */
-async function runLoadedScanCli(emitTrace) {
+async function runLoadedScanCli(emitTrace, out) {
   /** @type {string | undefined} */
   let sessionId;
   try {
@@ -340,19 +346,19 @@ async function runLoadedScanCli(emitTrace) {
     // systemMessage reaches the user, additionalContext the model. Both, because
     // this hook cannot block and the file is already loaded: the user is the one
     // who can act on it, and the model is the one currently reading it.
-    process.stdout.write(
-      JSON.stringify({
-        systemMessage: message,
-        hookSpecificOutput: {
-          hookEventName: HookEvent.INSTRUCTIONS_LOADED,
-          additionalContext: message,
-        },
-      }),
-    );
+    out.add({
+      systemMessage: message,
+      hookSpecificOutput: {
+        hookEventName: HookEvent.INSTRUCTIONS_LOADED,
+        additionalContext: message,
+      },
+    });
   } catch (err) {
     emitTrace(TraceEvent.SCAN_LOADED_INSTRUCTIONS_RAN, { outcome: "skipped" });
     const outcome = hookFaultOutcome(HOOK_NAME, err);
-    process.exitCode = writeFaultOutcome(outcome);
+    process.exitCode = writeFaultOutcome(outcome, (chunk) =>
+      out.add(JSON.parse(chunk)),
+    );
     // `sessionId`, captured before the throw: a payload read that itself failed
     // leaves it undefined, and the fault then lands in the shared fallback store
     // rather than in no store at all.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.68.0",
+  "version": "2.69.0",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/src/html.mjs

@@ -1592,16 +1592,17 @@ function isSelfClosedForeign(tagName, value) {
 // under fragment parsing (scripting disabled) parse5 parses its content as
 // normal markup, so scanning it is correct. Once `plaintext` opens it runs to
 // EOF and never closes.
-const RAW_TEXT_ELEMENTS = new Set([
-  "script",
-  "style",
-  "textarea",
-  "title",
-  "xmp",
-  "iframe",
-  "noembed",
-  "noframes",
-  "plaintext",
+// Each end-tag matcher is spelled per tag, so none compiles a document's text.
+const RAW_TEXT_END_TAGS = new Map([
+  ["script", /<\/script(?![a-z0-9-])/i],
+  ["style", /<\/style(?![a-z0-9-])/i],
+  ["textarea", /<\/textarea(?![a-z0-9-])/i],
+  ["title", /<\/title(?![a-z0-9-])/i],
+  ["xmp", /<\/xmp(?![a-z0-9-])/i],
+  ["iframe", /<\/iframe(?![a-z0-9-])/i],
+  ["noembed", /<\/noembed(?![a-z0-9-])/i],
+  ["noframes", /<\/noframes(?![a-z0-9-])/i],
+  ["plaintext", /<\/plaintext(?![a-z0-9-])/i],
 ]);
 
 // Keywords that take the parent's value of an inherited property: `revert`
@@ -2608,9 +2609,9 @@ function scanInlineChildren(node, text, ranges, warned) {
   // "Inside an unterminated tag / bogus comment" — parse5 absorbs following
   // markup into it until the next `>`.
   let absorbing = false;
-  // Non-null while inside a raw-text element (its lowercased tag name); content
-  // is opaque until the matching end tag.
-  let rawText = /** @type {string | null} */ (null);
+  // Non-null while inside a raw-text element (the matcher for its end tag);
+  // content is opaque until that end tag.
+  let rawTextEnd = /** @type {RegExp | null} */ (null);
   // End offset of the last html node processed; the raw slice from here to the
   // next html node is what parse5 tokenizes between them.
   let prevEnd = node.position.start.offset;
@@ -2622,10 +2623,9 @@ function scanInlineChildren(node, text, ranges, warned) {
     // into the absorb state before deciding what to do with this html node.
     absorbing = foldAbsorb(absorbing, text.slice(prevEnd, base));
 
-    if (rawText) {
+    if (rawTextEnd) {
       // Raw-text content is opaque; only the matching end tag ends the region.
-      if (new RegExp(`</${rawText}(?![a-z0-9-])`, "i").test(value))
-        rawText = null;
+      if (rawTextEnd.test(value)) rawTextEnd = null;
     } else if (state.depth > 0) {
       updateHiddenState(state, value, end, ranges);
     } else if (!absorbing) {
@@ -2655,7 +2655,7 @@ function scanInlineChildren(node, text, ranges, warned) {
         if (el) {
           // A raw-text open tag starts an opaque region (a self-closing `/>`
           // does not apply to these in HTML — they always open).
-          if (RAW_TEXT_ELEMENTS.has(el.tagName)) rawText = el.tagName;
+          rawTextEnd = RAW_TEXT_END_TAGS.get(el.tagName) ?? null;
           // `el` is one tag parsed alone, so a `<template>` inside an inline
           // `<svg>`/`<math>` reads as HTML here and is reported, where the
           // source branch, which sees the namespace, does not: this errs toward

package/src/output.mjs

@@ -365,8 +365,9 @@ function processLayer1(text, sgrCarveOut) {
  * Refuse to START a parse with no budget left. Each of Layers 2/3 parses the
  * whole document in ONE synchronous call, so nothing interrupts it, and a host
  * that kills the overrun hook shows the RAW text. Called before EACH parse, and
- * only after a pre-gate passed, so a declined call costs no time. Fails closed,
- * as Layer 4 does.
+ * only after a pre-gate passed, so a declined call costs no time. Throws, as
+ * Layer 4 does: whether the unchecked text then passes or is withheld is the
+ * caller's fault posture, never this layer's.
  * @param {Deadline | undefined} deadline
  * @returns {void}
  */
@@ -374,8 +375,8 @@ function refuseIfSpent(deadline) {
   if (deadline && deadline.remainingMs() <= 0)
     throw new Error(
       "CRITICAL: the sanitization time budget ran out before the hidden-HTML " +
-        "and exfil-URL layers finished, so this text was not fully checked. " +
-        "Failing closed — tool output suppressed.",
+        "and exfil-URL layers finished, so this text was not fully checked " +
+        "and must be treated as UNSANITIZED.",
     );
 }
 

package/src/rehydrate.mjs

@@ -823,6 +823,12 @@ function isCandidate(tool, ti) {
  * there is nothing to do. Throws only on internal error (the caller fails
  * closed).
  *
+ * A deny carrying `fault` is not a verdict on the input but this module being
+ * unable to do its job (an unreadable target, a redactor map that fails
+ * validation): `fault` states what proceeding un-rehydrated would write, and the
+ * caller's failure posture decides whether the deny stands. A deny without it
+ * is a verdict and stands in every posture.
+ *
  * `io` is the injected I/O (file read + redactor map/plain). `hint` is the
  * redaction-placeholder prefix (defaults to {@link DEFAULT_HINT}); override it
  * only if the injected redactor emits a different placeholder shape.
@@ -830,7 +836,7 @@ function isCandidate(tool, ti) {
  * @param {any} toolInput
  * @param {RehydrateIo} io
  * @param {{ hint?: string }} [options]
- * @returns {Promise<{updatedInput: any, context: string} | {deny: string} | null>}
+ * @returns {Promise<{updatedInput: any, context: string} | {deny: string, fault?: string} | null>}
  */
 export async function rehydrateRedacted(
   tool,
@@ -911,12 +917,17 @@ export async function rehydrateRedacted(
       if (tool !== "Write") throw err;
       return null;
     }
+    const cause = nodeErr?.code ?? nodeErr?.message;
     return {
       deny:
         `could not read ${toolInput.file_path} to rehydrate its secrets ` +
-        `(${nodeErr?.code ?? nodeErr?.message}); the file likely still exists, so writing ` +
+        `(${cause}); the file likely still exists, so writing ` +
         `the placeholder text as-is risks overwriting a real secret. Retry the read, or ` +
         `ask the user to make this change directly`,
+      fault:
+        `${toolInput.file_path} could not be read (${cause}) to rehydrate its ` +
+        `secrets, so this call is not rehydrated and its ${hint}…] placeholder ` +
+        `text is written to the file literally`,
     };
   }
   const { layer1Cleaned, cleaned } = layer1View(content);
@@ -949,8 +960,14 @@ export async function rehydrateRedacted(
     // reaches its own resolver-backed pass-through.
     if (tool === "MultiEdit") return multiEditDeny(toolInput.file_path);
     if (!hinted) return null;
+    // A verdict, not a fault: the file itself defeats mapping on every call, so
+    // a released re-issue would overwrite the real secret with its placeholder.
+    // The escape is to stop writing the placeholder, which the reason names.
     return {
-      deny: `cannot resolve redaction placeholders in ${toolInput.file_path}: ${mapped.unmappable}`,
+      deny:
+        `cannot resolve redaction placeholders in ${toolInput.file_path}: ` +
+        `${mapped.unmappable}. Leave every ${hint}…] placeholder out of this ` +
+        `call (edit around it), or ask the user to make this change`,
     };
   }
   // The redactor emits code-point offsets; the offset machinery below works in
@@ -970,9 +987,8 @@ export async function rehydrateRedacted(
   // before acting: construction re-checks range/ordering (the throws in
   // assertPairsOrdered and pairsToUtf16), viewMapDefect proves the view
   // reconstructs `cleaned` exactly. A defective map DENIES for every tool and
-  // hint state, and is deliberately NOT allowed to throw out of this module: a
-  // throw lands in the host's failure posture, whose shipped default is fail
-  // OPEN, i.e. the unsanitized placeholder write this module exists to prevent.
+  // hint state with a `fault`, never a throw: the deny lets the caller refuse
+  // the call once and name what proceeding writes, which a throw cannot.
   let view = null;
   let mapDefect = null;
   try {
@@ -993,14 +1009,25 @@ export async function rehydrateRedacted(
     // Reaching this line at all means the fast pass-through did not fire — the
     // file provably holds redacted content or diverges from its view — so an
     // unhinted pass-through here would hand the real Edit bytes inside spans
-    // nothing can vet (the R1 hidden-span oracle). Deny everything until the
-    // redactor is fixed.
+    // nothing can vet (the R1 hidden-span oracle). Deny, as a fault: the
+    // engine, not the input, is what is wrong.
     if (tool === "MultiEdit") return multiEditDeny(toolInput.file_path);
+    // A Write replaces the whole file, and the secret-drop guard reads this
+    // same broken map, so the loss it would name has to be named here instead.
+    const dropped =
+      tool === "Write"
+        ? `; it replaces the whole file, so any redacted secret it does not ` +
+          `reproduce is removed, and which secrets those are cannot be checked`
+        : "";
     return {
       deny:
         `cannot safely edit ${toolInput.file_path}: ${mapDefect}; the file holds ` +
         `redacted content whose location cannot be trusted, so no edit can be ` +
-        `verified. Retry later, or ask the user to make this change`,
+        `verified${dropped}. Retry later, or ask the user to make this change`,
+      fault:
+        `${mapDefect} for ${toolInput.file_path}, so this call is not ` +
+        `rehydrated: any ${hint}…] placeholder text in it is written to the ` +
+        `file literally, and it is applied without the redacted-span checks${dropped}`,
     };
   }
   // View identical to disk: any placeholders in an Edit's old_string are

package/types/claude-hooks/lib/hook-fault.d.mts

@@ -110,8 +110,10 @@ export type FaultContext = Record<string, any> & {
 /**
  * A hook's declared posture. There is deliberately no way for a policy to pin
  * the CLOSED arm: AGENT_SANITIZER_FAIL_OPEN alone decides, so no hook fault can
- * withhold a tool output or block a prompt unless the operator set the knob to
- * `0`. A pin turns any bug in the guarded layer into every tool call failing.
+ * withhold a tool output, block a prompt, or hold a tool call for good unless the
+ * operator set the knob to `0` (an open arm may refuse a call once, releasing the
+ * exact re-issue). A pin turns any bug in the guarded layer into every tool call
+ * failing.
  */
 export type FaultPolicy = {
     event: string | null;

package/types/claude-hooks/lib/hook-io.d.mts

@@ -286,6 +286,25 @@ export function safeErrMessage(err: unknown, cap?: number): string;
  * @returns {void}
  */
 export function emitHookResponse(hookEventName: string, fields: Record<string, unknown>): void;
+/**
+ * @typedef {{
+ *   add: (envelope: Record<string, any>) => void,
+ *   emit: (hookEventName: string, fields: Record<string, unknown>) => void,
+ *   flush: () => void,
+ * }} EnvelopeBuffer
+ */
+/**
+ * Collect everything a hook run wants to say on stdout and write it as exactly
+ * ONE JSON object on `flush`. Claude Code parses a hook's stdout as a single
+ * document, so two envelopes written by two reporters (a fault notice, then the
+ * slow-hook notice from the timing wrapper's `finally`) concatenate into invalid
+ * output and the host DROPS the whole response — the model never sees either
+ * warning. Every reporter in a run therefore adds here instead of writing, and
+ * the entry point flushes once, last.
+ * @param {(chunk: string) => void} [write]  injectable stdout sink, for tests
+ * @returns {EnvelopeBuffer}
+ */
+export function createEnvelopeBuffer(write?: (chunk: string) => void): EnvelopeBuffer;
 /**
  * The directory the session-lifetime stores live under: the alert markers and
  * findings (invisible-alert.mjs) and the reveal sidecars (reveal.mjs). They must
@@ -522,14 +541,16 @@ export function touchLiveState(path: string): void;
  * file the hook's user owns. Unlink any existing entry first (removing a squatted
  * symlink), then create exclusively (O_EXCL) so a symlink re-planted in the race
  * window fails the open rather than being dereferenced. Content is irrelevant —
- * callers test only for existence — so the file is left empty. Best-effort: a
- * missing/read-only $TMPDIR or a lost race just leaves the sentinel absent, and
- * every caller treats "absent" as "not yet done" (a repeated ask, never a crash),
- * so all failures are swallowed.
+ * callers test only for existence — so the file is left empty. Never throws: a
+ * missing/read-only $TMPDIR or a lost race leaves the sentinel absent, and the
+ * return value says so. A caller whose refusal is released only by a later read
+ * of this sentinel must branch on it, because a refusal that records nothing can
+ * never be released.
  * @param {string} path
- * @returns {void}
+ * @returns {boolean}  whether a sentinel this uid owns now exists at `path`
+ *   (the same test {@link markerIsTrusted} applies when a reader looks for it)
  */
-export function writeSentinelFile(path: string): void;
+export function writeSentinelFile(path: string): boolean;
 /**
  * Write `content` to `path` without following a symlink a co-tenant may have
  * pre-planted there — the content-bearing counterpart to writeSentinelFile. These
@@ -635,6 +656,11 @@ export const STATE_ROOT: string;
  * says it locks may be judged by the lock.
  */
 export const SETUP_LOCK_DECLARATION: "flock";
+export type EnvelopeBuffer = {
+    add: (envelope: Record<string, any>) => void;
+    emit: (hookEventName: string, fields: Record<string, unknown>) => void;
+    flush: () => void;
+};
 /**
  * EVERY process-wide slot these helpers keep — the four a host can observe or
  * steer, so a second instance that adopts this object is steered in all four at

package/types/claude-hooks/lib/invisible-alert.d.mts

@@ -193,11 +193,14 @@ export function alertAcknowledged(sessionId?: string): boolean;
 /**
  * Record that the gate has surfaced its blocking ask, so later tool calls get a
  * passive reminder instead of an ask on every call. Session-keyed, so the next
- * session re-asks once without anything having to clear this.
+ * session re-asks once without anything having to clear this. Returns false
+ * when the ack could not be recorded, so the caller knows the next call will
+ * ask again: under the fail-open posture it surfaces the finding as a warning
+ * rather than asking on every tool call for the rest of the session.
  * @param {string} [sessionId]
- * @returns {void}
+ * @returns {boolean}
  */
-export function acknowledgeAlert(sessionId?: string): void;
+export function acknowledgeAlert(sessionId?: string): boolean;
 /**
  * The blocking ask. The heading states only that the scan did not finish clean:
  * the alert carries injection findings, unreadable targets, or a scanner fault,