agent-sanitizer 2.43.12 → 2.44.0

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

@@ -1,16 +1,36 @@
+/**
+ * The path prefix every alert artifact of ONE session under this project shares.
+ *
+ * Session-keying is what makes the gate's one-time ask correct by construction.
+ * The store and its ack used to be keyed by PROJECT alone and reset by a
+ * destructive clear at SessionStart, which left two ways for a session to
+ * inherit the previous one's answer: an early-exiting scanner arm (a dep-load
+ * failure) returns before the clear, and nothing pins SessionStart against the
+ * InstructionsLoaded events fired for the files loaded at launch. A session that
+ * cannot see another session's files needs neither the clear nor the ordering —
+ * past sessions' artifacts simply age out through {@link sweepStaleSessions}.
+ * @param {string} [sessionId]  the harness's session identity
+ * @returns {string}
+ */
+export function sessionPrefix(sessionId?: string): string;
+/**
+ * The directory holding this session's alert findings, one file per finding.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function alertDir(sessionId?: string): string;
+/**
+ * Companion marker the PreToolUse gate writes once it has surfaced the alert
+ * this session, so the gate asks ONCE then degrades to a passive reminder
+ * instead of prompting on every tool call. Session-keyed like the findings it
+ * answers for, so a fresh session cannot read an older session's answer.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function alertAckFile(sessionId?: string): string;
 /**
  * Marker the InstructionsLoaded scanner writes on every fire, so another hook
  * can tell whether that event is being scanned at all this session.
- *
- * Keyed by the SESSION, and never cleared at SessionStart like the alert pair
- * above (a later session sweeps it once it is older than the TTL):
- * nothing pins the order of SessionStart against the InstructionsLoaded events
- * Claude Code fires for the files it loads at launch, so a clear could erase a
- * marker written moments earlier and produce the notice on a session that IS
- * covered. Session-keyed, the question each session asks is answered by that
- * session's own file and no ordering matters. A host that exports no session id
- * falls back to one shared name — where the marker can outlive its session, and
- * a later session on a host that stopped emitting the event stays quiet.
  * @param {string} [sessionId]
  * @returns {string}
  */
@@ -31,13 +51,25 @@ export function instructionsLoadedNoticeFile(sessionId?: string): string;
  * @returns {boolean}
  */
 export function instructionsLoadedSeen(sessionId?: string): boolean;
+/**
+ * Delete this project's artifacts from OTHER sessions once they are older than
+ * the TTL. The current session's own prefix is skipped, so the sweep can never
+ * answer its own question wrong; every other session's files are past history
+ * that nothing reads.
+ *
+ * This replaces the destructive SessionStart clear: with the store session-keyed
+ * there is nothing to reset, only old state to age out.
+ * @param {string} [sessionId]  the session whose artifacts must be kept
+ * @returns {void}
+ */
+export function sweepStaleSessions(sessionId?: string): void;
 /**
  * Record that the InstructionsLoaded scanner engaged. Symlink-safe presence
  * write (see writeSentinelFile) at a predictable $TMPDIR path.
  *
  * The event fires once per instruction file loaded, so the already-recorded case
- * returns without a write — and the stale-marker sweep rides the FIRST fire of a
- * session, where one readdir is paid once rather than per loaded file.
+ * returns without a write — and the stale-session sweep rides the FIRST fire of
+ * a session, where one readdir is paid once rather than per loaded file.
  * @param {string} [sessionId]
  * @returns {void}
  */
@@ -45,8 +77,12 @@ export function recordInstructionsLoaded(sessionId?: string): void;
 /**
  * The one-time context line for a session where no InstructionsLoaded scan ran,
  * or null when the scan has been seen or the notice was already surfaced this
- * session. Records the notice as it hands it out, so it rides on ONE tool call
- * rather than every one — the per-call repeat is what trains a reader to skip it.
+ * session.
+ *
+ * PURE: it does not record that the notice was handed out. The caller records
+ * separately, once the notice has actually landed in a response — a deny
+ * assembled after this call discards the notice, and a marker written here would
+ * have burned the session's one chance to report the loss.
  *
  * The loss it names is real and otherwise invisible: SessionStart scans the
  * instruction files that load at launch, and everything a subdirectory loads
@@ -63,48 +99,67 @@ export function recordInstructionsLoaded(sessionId?: string): void;
  * @returns {string | null}
  */
 export function instructionsLoadedGapNotice(sessionId?: string): string | null;
+/**
+ * Record that the gap notice above was surfaced, so it rides on ONE tool call
+ * rather than every one — the per-call repeat is what trains a reader to skip it.
+ * Called only once the notice is in a response that is actually being returned.
+ * @param {string} [sessionId]
+ * @returns {void}
+ */
+export function recordInstructionsLoadedNotice(sessionId?: string): void;
 /**
  * The alert findings if invisible-char injection was detected in instruction
- * files and couldn't be auto-cleaned, else null. ALERT_FILE lives at a predictable,
- * world-visible $TMPDIR path, so its contents are attacker-writable (a co-tenant can
- * plant a file/symlink there): trust it only when markerIsTrusted confirms a regular
- * file THIS uid owns (a squatted symlink/foreign file reads as no alert), then scrub
- * the bytes through Layer-1 before any caller splices them into a reason — the report
- * would otherwise carry ANSI/invisible spoofing into the model's context.
+ * files and couldn't be auto-cleaned, else null.
+ *
+ * The store is a DIRECTORY of one file per finding, all at predictable,
+ * world-visible $TMPDIR paths, so both the directory and every entry in it are
+ * attacker-plantable: trust the directory only when it is a real directory this
+ * uid owns (a symlink would let a co-tenant aim this reader at unrelated files),
+ * each entry only when markerIsTrusted confirms a regular file this uid owns,
+ * then scrub the bytes through Layer-1 before any caller splices them into a
+ * reason — the report would otherwise carry ANSI/invisible spoofing into the
+ * model's context.
+ * This session's store AND the shared `no-session` fallback, because a hook that
+ * faults BEFORE it can parse its payload has no session identity to key by: its
+ * finding lands in the fallback, and a strictly session-keyed read would leave
+ * the one report of an unscanned instruction file unreachable. The ack stays
+ * strictly session-keyed, so the gate still asks exactly once per session.
+ * @param {string} [sessionId]
  * @returns {string | null}
  */
-export function invisibleCharAlert(): string | null;
+export function invisibleCharAlert(sessionId?: string): string | null;
 /**
- * Add `text` to the alert the PreToolUse gate surfaces, keeping whatever is
- * already there.
+ * Add `text` to the alert the PreToolUse gate surfaces this session, keeping
+ * whatever is already there.
  *
- * Appending, where the SessionStart scanner TRUNCATES: that scan runs once and
- * owns the session's reset, while an instruction file loaded mid-session is one
- * more finding on top of whatever the launch scan left — a truncating write here
- * would silently drop the earlier report. Symlink-refusing (writeFileNoFollow)
- * and ownership-checked on read, because ALERT_FILE sits at a predictable,
- * world-visible $TMPDIR path; a foreign or squatted file reads as empty and is
- * replaced rather than appended to.
+ * One O_EXCL-created, randomly-named file per finding. The store used to be a
+ * single file appended through a read-modify-write, so two hooks recording a
+ * finding at once silently dropped one of them; a fresh file per finding has no
+ * shared cell to lose. Symlink-refusing (writeFileNoFollow) because the store
+ * sits at a predictable, world-visible $TMPDIR path.
  * @param {string} text
- * @returns {void}
+ * @param {string} [sessionId]
+ * @returns {boolean} whether the finding was recorded
  */
-export function appendAlert(text: string): void;
+export function appendAlert(text: string, sessionId?: string): boolean;
 /**
  * True once the gate has surfaced its blocking ask this session. Validates
- * ownership (not mere existence): a co-tenant could pre-create ALERT_ACK_FILE at its
- * predictable $TMPDIR path to permanently suppress the one-time blocking ask down to
- * the passive reminder, so trust the marker only when it is a regular file this uid
- * wrote (markerIsTrusted), mirroring how acknowledgeAlert writes it.
+ * ownership (not mere existence): a co-tenant could pre-create the ack at its
+ * predictable $TMPDIR path to permanently suppress the one-time blocking ask down
+ * to the passive reminder, so trust the marker only when it is a regular file
+ * this uid wrote (markerIsTrusted), mirroring how acknowledgeAlert writes it.
+ * @param {string} [sessionId]
  * @returns {boolean}
  */
-export function alertAcknowledged(): boolean;
+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. Cleared at SessionStart by
- * the scanner so each fresh session re-asks once.
+ * passive reminder instead of an ask on every call. Session-keyed, so the next
+ * session re-asks once without anything having to clear this.
+ * @param {string} [sessionId]
  * @returns {void}
  */
-export function acknowledgeAlert(): void;
+export function acknowledgeAlert(sessionId?: string): void;
 /**
  * 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,
@@ -121,10 +176,9 @@ export function gateAskReason(findings: string): string;
  * @returns {string}
  */
 export function gateReminderContext(): string;
-/** The project the hooks are guarding; the alert paths are keyed to it. */
-export const PROJECT_DIR: string;
-/** Short project digest keying this project's $TMPDIR marker names. */
-export const PROJECT_HASH: string;
-/** Findings the SessionStart scanner could not clean, for the PreToolUse gate. */
-export const ALERT_FILE: string;
-export const ALERT_ACK_FILE: string;
+/**
+ * The path prefix every alert artifact of this PROJECT shares. Never a file
+ * itself — only {@link sessionPrefix} and the sweep read it — so that one
+ * `startsWith` covers every artifact the sweep must age out.
+ */
+export const ALERT_BASE: string;

package/types/claude-hooks/lib/reveal.d.mts

@@ -5,6 +5,15 @@
  * @returns {string}
  */
 export function revealDir(): string;
+/**
+ * Delete this project's reveal sidecars and spans older than {@link REVEAL_TTL_MS}.
+ *
+ * Nothing else removes them: every entry is content-addressed, so a store that is
+ * never swept grows for the life of the machine. Called from SessionStart, the one
+ * touchpoint that runs once per session rather than once per tool call.
+ * @returns {void}
+ */
+export function sweepStaleReveals(): void;
 /**
  * Persist one reveal's pre-splice text and return the model-facing hint naming
  * its path, or null when the write fails (the splice already protected the
@@ -68,6 +77,13 @@ export function readSpan(key: string): string | null;
  * @returns {boolean}
  */
 export function isRevealRead(toolName: string, toolInput: any): boolean;
+/**
+ * How long a reveal sidecar or span file is kept before a later session sweeps it.
+ * It must outlast the longest session that could still rehydrate a placeholder the
+ * model is holding, so it is generous rather than tight — these files are small,
+ * and the cost of sweeping one too early is a rehydration that fails closed.
+ */
+export const REVEAL_TTL_MS: number;
 /**
  * The model-facing line telling it Layer-2 placeholders round-trip: pushed once
  * per tool output whose splices were persisted, so the model knows to leave the

package/types/claude-hooks/lib/secret-drop-guard.d.mts

@@ -18,6 +18,17 @@ export function dropFingerprint(filePath: string, content: string, dropped?: str
  * @returns {string}
  */
 export function confirmMarkerPath(fingerprint: string): string;
+/**
+ * Delete this project's confirm sentinels older than {@link CONFIRM_TTL_MS}.
+ *
+ * consumeConfirm removes the sentinel it honors, but an abandoned confirmation —
+ * denied, never retried — is removed by nothing, so the store grows for the life
+ * of the machine. Called from SessionStart, the one touchpoint that runs once per
+ * session rather than once per tool call. A sentinel past the TTL is already inert
+ * (consumeConfirm refuses it), so this reclaims space without changing a verdict.
+ * @returns {void}
+ */
+export function sweepStaleConfirms(): void;
 /**
  * Whether git tracks `filePath`. Exit 0 is tracked; exit 1 (untracked) and 128
  * (not a repository) both mean "no git recovery exists", which is what the

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

@@ -46,18 +46,33 @@ export function formatSkipped(skipped: Array<{
  * @param {{
  *   trace?: import("./lib/trace.mjs").TraceFn,
  *   scan?: () => ReturnType<typeof scanProject>,
+ *   sessionId?: string,
  * }} [opts]  `trace` is where this scan announces engagement; a host with its
  *   own trace channel passes its sink so the announcement lands where its
  *   detector reads (see lib/trace.mjs). `scan` is the scanner, injectable so the
  *   FAULT path below — a scanner that throws something other than an errno, i.e.
  *   a bug — is drivable end to end; no filesystem state can force it, and an
  *   untested fault path is how a posture goes missing in the first place.
+ *   `sessionId` keys the alert store this scan writes; the CLI entry reads it off
+ *   the SessionStart payload, and an in-process caller passes it directly.
  * @returns {Promise<void>}
  */
 export function cliMain(opts?: {
     trace?: import("./lib/trace.mjs").TraceFn;
     scan?: () => ReturnType<typeof scanProject>;
+    sessionId?: string;
 }): Promise<void>;
+/**
+ * The session identity from the SessionStart payload on stdin, or undefined when
+ * the host sent none.
+ *
+ * Swallowing: the payload is read for ONE optional field, and a host that pipes
+ * nothing (or malformed JSON) must still get the scan — a session-start scan
+ * refused over an unparseable envelope is a strictly worse outcome than one
+ * keyed to the shared `no-session` fallback.
+ * @returns {Promise<string | undefined>}
+ */
+export function sessionIdFromStdin(): Promise<string | undefined>;
 /**
  * Read one file and run the SSOT scan over it. The scan logic itself (long-run
  * decode + scattered threshold-evasion counting) is `scanText`'s — a local
@@ -108,9 +123,9 @@ export function decodeRun(run: string): {
  * @returns {string[]}
  */
 export function findInstructionFiles(dir: string): string[];
-import { ALERT_FILE } from "./lib/invisible-alert.mjs";
-import { ALERT_ACK_FILE } from "./lib/invisible-alert.mjs";
+import { alertAckFile } from "./lib/invisible-alert.mjs";
+import { alertDir } from "./lib/invisible-alert.mjs";
 export let LONG_RUN_RE: RegExp;
 export let LONG_RUN_THRESHOLD: 10;
 export let TOTAL_INVISIBLE_THRESHOLD: 30;
-export { CLAUDE_CONTEXT_SUBDIRS, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, ALERT_FILE, ALERT_ACK_FILE };
+export { CLAUDE_CONTEXT_SUBDIRS, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, alertAckFile, alertDir };