agent-sanitizer 2.67.2 → 2.69.0

package/types/claude-hooks/pretooluse-sanitize.d.mts

@@ -29,13 +29,14 @@
  * @param {boolean} [secretsOn]  the run's secret opt-in (decided once by
  *   buildPreToolUseResponse; a direct caller reads the env); only with it on
  *   does the context claim the restored bytes were redacted
- * @returns {{ updatedInput: any, context: string } | { deny: string } | null}
+ * @returns {{ updatedInput: any, context: string } | { deny: string, fault?: string } | null}
  */
 export function rehydrateLayer2(tool: string, toolInput: any, secretsOn?: boolean): {
     updatedInput: any;
     context: string;
 } | {
     deny: string;
+    fault?: string;
 } | null;
 /**
  * The declared stage chain after the gate. Every entry states the two properties
@@ -53,9 +54,12 @@ export function rehydrateLayer2(tool: string, toolInput: any, secretsOn?: boolea
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @param {boolean} [secretsOn]  the run's secret opt-in (see
  *   buildPreToolUseResponse, which decides it once and passes it here)
+ * @param {FaultLedger} [ledger]  where a fault deny the open posture lets
+ *   through leaves its warning; required as soon as a stage reports a fault,
+ *   since a warning with nowhere to go would let the call through silently
  * @returns {import("./lib/layer-pipeline.mjs").Layer[]}
  */
-export function preToolUseLayers(rehydrate: ((tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>) | null, env?: NodeJS.ProcessEnv | Record<string, string | undefined>, secretsOn?: boolean): import("./lib/layer-pipeline.mjs").Layer[];
+export function preToolUseLayers(rehydrate: ((tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>) | null, env?: NodeJS.ProcessEnv | Record<string, string | undefined>, secretsOn?: boolean, ledger?: FaultLedger): import("./lib/layer-pipeline.mjs").Layer[];
 /**
  * Compose the five stages. Returns the `hookSpecificOutput` fields to emit, or
  * null for a clean no-op. Throws only if a stage's engine throws; the caller
@@ -79,9 +83,11 @@ export function buildPreToolUseResponse(input: any, rehydrate?: (tool: string, t
  * ToolCallEvent and returns a Verdict, so a non-Claude host can run the same
  * sanitization pipeline through its own adapter. The wired Claude CLI below
  * routes through this judge and renders the Verdict with the Claude adapter; on
- * any throw (a control-plane package-load failure included) it falls back to
- * hookFailureFields — a native response that needs no package — so the
- * caller's fault posture holds even when the adapter never loaded.
+ * any throw (a control-plane package-load failure, or an event the adapter
+ * could not classify) it falls back to hookFailureFields — a native response
+ * that needs no package — so the caller's fault posture holds even when the
+ * adapter never loaded. A host calling this directly renders its throws the
+ * same way.
  * @param {import("agent-control-plane-core").ToolCallEvent} event
  * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} [rehydrate]
  * @param {{
@@ -147,8 +153,8 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
 }): Record<string, unknown>;
 /**
  * True when a faulting PreToolUse call is the one case the OPEN posture must
- * still not pass: a write-shaped tool whose input carries a redaction
- * placeholder, matched by the real grammar (containsPlaceholder) so
+ * not pass on the first try: a write-shaped tool whose input carries a
+ * redaction placeholder, matched by the real grammar (containsPlaceholder) so
  * hint-prefixed prose such as `[REDACTED…]` is not mistaken for one. Such a
  * placeholder stands for a secret the sanitizer redacted out of the model's
  * view; with the sanitizer down, rehydration cannot translate it back, so
@@ -159,7 +165,7 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
  *
  * Deliberately NOT exhaustive over every clobber path: Bash can also write a
  * placeholder to disk (`>`, `tee`, `sed -i`, a heredoc), but command strings
- * mention "[REDACTED" benignly far too often for an ask to hold precision
+ * mention "[REDACTED" benignly far too often for a refusal to hold precision
  * there. That is an accepted gap, named in THREAT-MODEL.md's carve-out.
  * @param {unknown} input raw parsed PreToolUse payload (undefined if unparsed)
  * @returns {boolean}
@@ -172,8 +178,9 @@ export function hintedWriteFault(input: unknown): boolean;
  * fail-CLOSED verdict of {@link failClosedFields} when the caller set
  * AGENT_SANITIZER_FAIL_OPEN=0. The open default has ONE carve-out, declared in
  * this hook's fault policy below: a write-shaped call whose input carries a
- * `[REDACTED…]` placeholder asks instead of passing (see
- * {@link hintedWriteFault}) — pass `input` so the policy can see it.
+ * `[REDACTED…]` placeholder is refused once, and its exact re-issue proceeds
+ * with a warning (see {@link hintedWriteFault}) — pass `input` so the policy
+ * can see it.
  *
  * The posture covers this hook's own failures, whatever their cause. What it
  * does NOT cover is the verdict of a sanitizer that ran: a payload
@@ -239,6 +246,17 @@ export const PRE_TOOL_USE_MESSAGES: Readonly<{
     remedy: string;
 }>;
 export const REDACTION_HINT: "[REDACTED";
+/**
+ * What the stage table hands back besides the pipeline's own result: the
+ * warnings of fault denies the open posture let through (the pipeline drops a
+ * stage's note when the input is unchanged, and these calls proceed unchanged),
+ * and the re-issue confirmations they rode on, consumed only once the call is
+ * known to proceed.
+ */
+export type FaultLedger = {
+    warnings: string[];
+    released: string[];
+};
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call
  * must be blocked, or null to let the pipeline continue. Hosts use these for

package/types/claude-hooks/sanitize-output.d.mts

@@ -177,7 +177,7 @@ export function emitFailClosed(input: any, message: string, emit?: (fields: Reco
  * fail-OPEN by default — a warning context and NO `updatedToolOutput`, leaving
  * the original tool output in the model's view — or the fail-closed
  * suppression of {@link emitFailClosed} when the caller set
- * AGENT_SANITIZER_FAIL_OPEN=0, or opted into Layer 4 (see the policy below).
+ * AGENT_SANITIZER_FAIL_OPEN=0.
  *
  * This is the hook where the two postures diverge the most, so state the open
  * one plainly: several of these layers throw on inputs an attacker composes (a

package/types/claude-hooks/sanitize-user-prompt.d.mts

@@ -2,8 +2,9 @@
  * Judge a normalized prompt-submit event. Agent-agnostic: consumes the
  * control-plane ToolCallEvent and returns a Verdict, so the same prompt gate
  * renders through any agent adapter, not just Claude's. Throws (into the
- * calling hook's catch) when the sanitizer package never loaded, so a prompt it
- * cannot classify takes the hook's fault posture rather than a silent ALLOW.
+ * calling hook's catch) when the sanitizer package never loaded or the payload
+ * is no recognizable event, so a prompt it cannot classify takes the hook's
+ * fault posture rather than a silent ALLOW.
  * @param {import("agent-control-plane-core").ToolCallEvent} event
  * @param {((s: string) => string) | null} [strip]  the ANSI stripper (defaults
  *   to the package's stripAnsiFully; injectable so the fault path is testable)

package/types/claude-hooks/scan-invisible-chars.d.mts

@@ -28,9 +28,9 @@ export function scanProject(dir?: string): {
     absent: string[];
 };
 /**
- * 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}
  */

package/types/output.d.mts

@@ -55,11 +55,10 @@ export function deleteVerbatimSpans(text: string, spans: string[]): {
  */
 /**
  * Run the configured layers over a single text blob. Layer 1 always runs; the
- * rest are opt-in via `options`. Layer 4 (`redact`) is the fail-closed path: a
- * redactor that throws is rethrown wrapped, so the caller suppresses the
- * output rather than emitting an unvetted value. That fail-closed behavior
- * also applies to Layer 4's re-scan after a Layer-5 span deletion (see Layer
- * 5, below) — a redactor failure there fails the whole call closed too.
+ * rest are opt-in via `options`. A Layer 4 (`redact`) redactor that throws is
+ * rethrown wrapped, so the caller answers it under its fault posture rather
+ * than receiving unvetted text as vetted. The same holds for Layer 4's re-scan
+ * after a Layer-5 span deletion (see Layer 5, below).
  * `reveal` is the pre-Layer-2 text, present only when the HTML splice removed
  * bytes, so a caller can persist what was hidden for later inspection (see
  * {@link applyMarkdownPipeline}); the field is omitted otherwise, and also when

package/types/rehydrate.d.mts

@@ -8,6 +8,12 @@
  * 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.
@@ -15,7 +21,7 @@
  * @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 function rehydrateRedacted(tool: string, toolInput: any, io: RehydrateIo, { hint }?: {
     hint?: string;
@@ -24,6 +30,7 @@ export function rehydrateRedacted(tool: string, toolInput: any, io: RehydrateIo,
     context: string;
 } | {
     deny: string;
+    fault?: string;
 } | null>;
 export const DEFAULT_HINT: "[REDACTED";
 /**