agent-sanitizer 2.25.0 → 2.26.0

package/README.md

@@ -31,16 +31,17 @@ Code](#using-it-with-claude-code) covers each hook and hand-wiring.
 import { sanitize } from "agent-sanitizer";
 
 // Layer 1 (invisible chars + ANSI), zero heavy deps:
-const { cleaned, found, warnings } = await sanitize(untrustedText);
+const { cleaned, found, warnings, notes } = await sanitize(untrustedText);
 
 // Opt into the HTML layers for web ingress (lazy-loads ~200 ms of deps):
 const result = await sanitize(pageSource, { html: true });
 ```
 
 `sanitize` never throws and never silently drops content—any change comes with
-at least one `warnings` entry. `found` names the neutralized category codes
-(e.g. `["cf-format", "hidden-html"]`); `cleaned` is the safe text, with
-placeholders where hidden HTML was spliced out.
+at least one `warnings` or `notes` entry. `found` names the neutralized category
+codes (e.g. `["cf-format", "hidden-html"]`); `cleaned` is the safe text, with
+placeholders where hidden HTML was spliced out. See [warnings vs
+notes](#warnings-vs-notes) for which findings land where.
 
 ## Entry points
 
@@ -79,6 +80,26 @@ without notice.
 | `hidden-html`         | Elements hidden via CSS/attribute (`display:none`, `hidden`, etc.) spliced out by Layer 2               |
 | `exfil-urls`          | Exfil-shaped URLs detected by Layer 3 (reported, not removed)                                           |
 
+### warnings vs notes
+
+Findings come back at two volumes, on `sanitize` and on `/output` alike:
+
+- **`warnings`** — injection-shaped. Something was hidden from a human reader,
+  something a payload would have used was removed, or a secret was redacted.
+  This is the set to surface.
+- **`notes`** — it happened, and here is how to look at it, but nothing about it
+  is attack-shaped: a preserved `<script>` on a fetched page, a plain link whose
+  URL merely looks exfil-shaped, or (in `/output`, under `sgrCarveOut`) an
+  incidental strip of pasted terminal colour or a stray soft hyphen.
+
+The tier changes nothing about what is removed—the same bytes are stripped,
+spliced and redacted either way, and a note is still reported. It exists so the
+banner keeps meaning something. A caller that ignores `notes` is exactly as loud
+as before the split. `/output` also returns `sgrNote: true` when a result is
+note-only, so a caller can pick the quiet line without inspecting the arrays.
+[`THREAT-MODEL.md`](./THREAT-MODEL.md#severity-warnings-vs-notes) lists which
+finding lands at which tier and why.
+
 ### `FILTER_WARNING` codes (Layer 5)
 
 The Layer-5 `filterInjection` seam is deliberately thin: the filter may only
@@ -428,8 +449,9 @@ field selects the entry point (default `sanitize`); the self-contained ones —
 `sanitizeText`, `classifyPrompt`, `scanInstructionFiles`, `cleanFile` — are
 bridged, while entry points taking a JS callback have no wire form. Bridged
 `sanitizeText` runs Layers 1–3 only: no secret redaction (Layer 4), no injection
-filtering (Layer 5), and `sgrNote` is always `false` since the bridge never
-wires `sgrCarveOut`.
+filtering (Layer 5), and—since the bridge never wires `sgrCarveOut`—Layer 1's
+findings are never downgraded, so `notes` carries only the Layer-2/3 tiers and
+`sgrNote` is `true` only when those were the whole story.
 
 ```sh
 echo '{"text":"a​b"}' | npx sanitize-cli           # default op: sanitize

package/THREAT-MODEL.md

@@ -69,8 +69,9 @@ it exactly—the idempotence the Edit-repair rehydrator's soundness gate assumes
 One tokenizer answers every ANSI question (what to splice, and whether what was
 removed was INERT—display-only SGR colour, or a lone 7-bit `ESC` that opened
 nothing at all), so the stripper and the operator warning cannot disagree about
-what a sequence is. That inert/injection-shaped split is what keeps the warning
-worth reading: a stray `ESC` sitting in a file is reported as a terse note, while
+what a sequence is. That inert/injection-shaped split is one input to the
+[severity tier](#severity-warnings-vs-notes) that keeps the warning worth
+reading: a stray `ESC` sitting in a file is reported as a terse note, while
 a cursor move, an erase, an OSC string, or a raw C1 introducer (which no
 legitimate UTF-8 text carries, and which includes the DCS/SOS/PM/APC string
 introducers) keeps the WARNING. An `ESC` that _opened_ a CSI it never completed
@@ -122,7 +123,17 @@ attributes (`src`/`href`/`background`/`srcset`/`ping`, form `action`/`formaction
 - `javascript:` / `vbscript:` targets
 
 Each threat carries a `reason` and the destination `target` (never the
-payload-bearing query/fragment), suitable for a warning shown to the operator.
+payload-bearing query/fragment) — the finding is shown to the operator with the
+target named and the payload withheld, since re-presenting the exfil payload in
+the model's context would hand the model the very bytes the finding is about.
+
+It also carries `autoFetched`, which is what its [severity](#severity-warnings-vs-notes)
+turns on: an `<img src>`, a stylesheet `<link>`, a `srcset`, a `ping`, a form
+`action` or a `meta refresh` exfiltrates the moment the content renders, with
+nobody deciding anything, while an `<a href>` or a markdown link cannot until
+the model chooses to follow it — and the sentence reporting it is precisely the
+instruction not to. A target whose kind cannot be resolved is treated as
+auto-fetched (fail closed).
 
 ## Confusable folding (tool input)
 
@@ -309,6 +320,47 @@ positive costs a sentence of context, never a mangled input):
   committed content survives, and probing index-vs-worktree state would trade
   precision for recall.
 
+## Severity: warnings vs notes
+
+Findings come back split into two tiers, and the split is a security property in
+its own right — a detector whose banner fires on every ordinary page teaches its
+reader to skip the banner, and then the one that mattered scrolls past with it.
+
+| Tier        | Means                                                                                                                                                      |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **WARNING** | This text is injection-shaped: something was hidden from a human reader, something a payload would have used was removed, or a secret was redacted.        |
+| **NOTE**    | This happened, and here is how to look at it, but nothing about it is attack-shaped: incidental bytes, or content that was PRESERVED and merely described. |
+
+The tier never changes what the pipeline **does**. The same bytes are stripped,
+spliced and redacted either way, and a note is still reported — all that rides on
+it is which banner the operator sees. That asymmetry is why a note is the right
+answer whenever the evidence is thin: an under-loud true finding is still
+delivered, while an over-loud false one costs the channel its credibility.
+
+Four decisions currently land at NOTE:
+
+- **An incidental Layer-1 strip** — inert ANSI (display-only SGR colour, or a
+  lone `ESC` that opened nothing) together with too few invisible characters to
+  spell anything. Both axes must be incidental; a cursor move, an erase, an OSC,
+  a raw C1 introducer or a payload-length run of invisibles keeps the WARNING.
+- **A preserved scripting/resource tag** (Layer 2) — nothing was removed and
+  nothing was hidden, and a `<script>` is on essentially every page ever fetched.
+  The Layer-2 **splice** stays a WARNING: those bytes were invisible to a human
+  reading the rendered page.
+- **An exfil-shaped URL that is not auto-fetched** (Layer 3) — see above.
+- **The prompt gate's inert-escape carve-out**, which predates the tier and is
+  the same judgement (see [User-prompt verdict](#user-prompt-verdict)).
+
+Layer 4 (a redacted secret) and Layer 5 (a filter finding) are always WARNINGs.
+
+The Layer-1 downgrade is gated on the caller asserting first-party ingress
+(`sgrCarveOut` in `./output`, set for local tool output). Without it — the
+`./sanitize` door, a fetched page, an MCP connector — Layer 1 stays loud however
+few the bytes, because that is the channel where a hidden character was _put_
+there. The `sgrNote` flag on a `./output` result means "nothing here rose above a
+note", so a caller can show the quiet line instead of the banner; one warning
+anywhere in the walk clears it.
+
 ## Failure posture (`AGENT_SANITIZER_FAIL_OPEN`)
 
 Installed as Claude Code hooks, these fail **open**: a hook that could not

package/bin/sanitize-cli.mjs

@@ -14,8 +14,8 @@
  * Protocol — a request is a JSON object with an `op` (default `"sanitize"` so a
  * bare `{ text, html }` keeps working). Per op:
  *
- *   sanitize           { text, html? }            -> { cleaned, found, warnings }
- *   sanitizeText       { text, html?, exfilScan? } -> { cleaned, warnings, modified, sgrNote }
+ *   sanitize           { text, html? }            -> { cleaned, found, warnings, notes }
+ *   sanitizeText       { text, html?, exfilScan? } -> { cleaned, warnings, notes, modified, sgrNote }
  *   classifyPrompt     { text }                    -> { action, reason? }
  *   scanInstructionFiles { globs, cwd? }           -> { findings: [{ file, findings }] }
  *   cleanFile          { path }                    -> { changed }
@@ -109,10 +109,10 @@ const OPS = {
   /** @param {Record<string, unknown>} req */
   async sanitize(req) {
     const text = requireString(req, "text");
-    const { cleaned, found, warnings } = await sanitize(text, {
+    const { cleaned, found, warnings, notes } = await sanitize(text, {
       html: Boolean(req.html),
     });
-    return { cleaned, found, warnings };
+    return { cleaned, found, warnings, notes };
   },
 
   /** @param {Record<string, unknown>} req */
@@ -121,11 +121,14 @@ const OPS = {
     // Layers 1–3 only: redact (Layer 4) and filterInjection (Layer 5) are
     // injected JS callbacks with no wire form, so they're never set here.
     const { sanitizeText } = await import("../src/output.mjs");
-    const { cleaned, warnings, modified, sgrNote } = await sanitizeText(text, {
-      html: Boolean(req.html),
-      exfilScan: Boolean(req.exfilScan),
-    });
-    return { cleaned, warnings, modified, sgrNote };
+    const { cleaned, warnings, notes, modified, sgrNote } = await sanitizeText(
+      text,
+      {
+        html: Boolean(req.html),
+        exfilScan: Boolean(req.exfilScan),
+      },
+    );
+    return { cleaned, warnings, notes, modified, sgrNote };
   },
 
   /** @param {Record<string, unknown>} req */

package/claude-hooks/lib/control-plane.mjs

@@ -17,7 +17,11 @@ import {
   probeSetupAlive,
   readStdinJson,
 } from "./hook-io.mjs";
-import { startHookTimer, withSlowHookNotice } from "./hook-timing.mjs";
+import {
+  startHookTimer,
+  withSlowHookNotice,
+  writeSlowHookNotice,
+} from "./hook-timing.mjs";
 
 // Loaded via a *caught* dynamic import — never a bare static `import … from`.
 // A static npm import resolves before any try/catch, so a missing node_modules
@@ -156,12 +160,19 @@ export async function runJudgeCli(
   },
 ) {
   let input;
+  // Hoisted out of the try so the CATCH can read it: a judge that spent thirty
+  // seconds and THEN threw is the slow run most worth naming, and reporting only
+  // on the success path hides exactly the case where the hook is both slow and
+  // broken. Null until stdin arrives — a read that throws measured nothing, and
+  // an invented number is worse than none.
+  /** @type {(() => number) | null} */
+  let elapsed = null;
   try {
     input = await readInput();
     // Timed from HERE, not from process start: the wait for the harness to hand
     // over stdin is not this hook's cost, and blaming it for one would send
     // operators chasing a bug report that is not theirs to fix.
-    const elapsed = startHookTimer();
+    elapsed = startHookTimer();
     const { claudeAdapter: adapter } = controlPlane();
     const event = adapter.parse(transformInput(input));
     // Awaited into its own binding first: as an inline argument, `elapsed()`
@@ -173,6 +184,11 @@ export async function runJudgeCli(
     if (out !== null) write(out);
   } catch (err) {
     process.stderr.write(`${hookName} hook error: ${errMessage(err)}\n`);
+    // After the error line, before the posture: the fault is what the reader
+    // must act on first, and the timing is context for it. stderr only — the
+    // model-facing channel here belongs to onError's fail-closed message, and a
+    // performance aside must not dilute a "this output was never vetted".
+    if (elapsed !== null) writeSlowHookNotice(hookName, elapsed());
     onError(err, input);
   }
 }

package/claude-hooks/lib/hook-timing.mjs

@@ -34,10 +34,41 @@
  */
 export const SLOW_HOOK_THRESHOLD_MS = 1000;
 
+/**
+ * Wall-clock a ONE-TIME provisioning step may spend before it is reported.
+ *
+ * Two orders of magnitude above {@link SLOW_HOOK_THRESHOLD_MS}, because it
+ * measures something categorically different: a dependency install that a
+ * session pays once, not a cost every tool call repeats. A cold `uv` install of
+ * the redactor engine is seconds and a cold `pip` one can be tens of them, so a
+ * budget anywhere near a second would report every first session — the alert
+ * fatigue this whole module exists to avoid. Past a minute, something is
+ * actually wrong (a serial pip resolve, a wedged mirror, or an idempotence bug
+ * re-provisioning every session), which is worth saying out loud.
+ */
+export const SLOW_PROVISION_THRESHOLD_MS = 60000;
+
 /** Where a reader is asked to send the timing. */
 const ISSUE_URL =
   "https://github.com/AlexanderMattTurner/agent-sanitizer/issues/new";
 
+/**
+ * Milliseconds as the seconds string every notice below prints.
+ *
+ * Rounds tenths half-UP from an exact integer count of hundredths, rather than
+ * `(ms / 1000).toFixed(1)`: the shell port of this module
+ * (plugin/scripts/lib/hook-timing.sh) has to produce the byte-identical string
+ * with integer arithmetic, and `toFixed` rounds the underlying double — so 1150
+ * would print "1.1" here (1.15 is below its decimal value as a double) and "1.2"
+ * there. `ms / 100` lands exactly on a half only when `ms` ends in 50, and every
+ * such quotient is dyadic, so this rounding is exact for every input.
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatSeconds(ms) {
+  return (Math.round(ms / 100) / 10).toFixed(1);
+}
+
 // Process-wide total of milliseconds spent in one-time provisioning. A running
 // total rather than a flag because a single hook run can pay more than one (a
 // dependency wait AND a cold daemon spawn), and they may not nest.
@@ -103,12 +134,72 @@ export function slowHookNotice(
   if (elapsedMs <= thresholdMs) return null;
   return (
     `agent-sanitizer PERFORMANCE: the ${hookName} hook took ` +
-    `${(elapsedMs / 1000).toFixed(1)}s, over its ${(thresholdMs / 1000).toFixed(1)}s budget — ` +
+    `${formatSeconds(elapsedMs)}s, over its ${formatSeconds(thresholdMs)}s budget — ` +
     "this delay is the sanitizer's, not the model's, and every affected call pays it. " +
     `Tell the user, and suggest they report it at ${ISSUE_URL} with the hook name and timing.`
   );
 }
 
+/**
+ * The line for a ONE-TIME provisioning step that overran
+ * {@link SLOW_PROVISION_THRESHOLD_MS}, or null when it did not.
+ *
+ * Deliberately NOT {@link slowHookNotice} with a bigger threshold: that message
+ * says "every affected call pays it", which is false here and would send the
+ * reader hunting a per-call cost that does not exist. What is actionable about a
+ * slow install is the installer (uv resolves in a fraction of pip's time) and
+ * the fact that a repeat means the idempotence check is broken — so this asks
+ * for a report only on the repeat, which is the version of this that is a bug.
+ *
+ * The one caller is the shell provisioner, whose port of this module
+ * (plugin/scripts/lib/hook-timing.sh) must emit this exact string; that port and
+ * this definition are pinned to each other by a contract test rather than left
+ * as two independently-worded copies.
+ * @param {string} stepName
+ * @param {number} elapsedMs
+ * @param {number} [thresholdMs]
+ * @returns {string | null}
+ */
+export function slowProvisionNotice(
+  stepName,
+  elapsedMs,
+  thresholdMs = SLOW_PROVISION_THRESHOLD_MS,
+) {
+  if (elapsedMs <= thresholdMs) return null;
+  return (
+    `agent-sanitizer PERFORMANCE: one-time setup (${stepName}) took ` +
+    `${formatSeconds(elapsedMs)}s, over its ${formatSeconds(thresholdMs)}s budget — ` +
+    "this is paid once per install, not per tool call, so the session is not slow from here on. " +
+    `Installing uv makes it faster; if it happens on EVERY new session, report it at ${ISSUE_URL}.`
+  );
+}
+
+/**
+ * Write the slow-hook notice to stderr and return it, or return null when the
+ * run was within budget (writing nothing, so the quiet path stays quiet).
+ *
+ * The one place the notice reaches stderr: every reporter below needs the
+ * transcript copy, and a hook whose run ENDED IN AN ERROR has nothing but this —
+ * its verdict is the fail-closed one its `onError` composed, and diluting that
+ * message with a performance aside would bury the fault. A judge that spent
+ * thirty seconds and then threw is exactly the case the timing exists to name,
+ * so the error path measures and reports; it just reports on the human channel.
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {string | null}
+ */
+export function writeSlowHookNotice(
+  hookName,
+  elapsedMs,
+  writeErr = (chunk) => process.stderr.write(chunk),
+) {
+  const notice = slowHookNotice(hookName, elapsedMs);
+  if (notice === null) return null;
+  writeErr(notice + "\n");
+  return notice;
+}
+
 /**
  * `verdict` with the slow-hook notice folded into its `additional_context`, or
  * the verdict untouched when the run was within budget. Also writes the notice
@@ -130,9 +221,8 @@ export function withSlowHookNotice(
   verdict,
   writeErr = (chunk) => process.stderr.write(chunk),
 ) {
-  const notice = slowHookNotice(hookName, elapsedMs);
+  const notice = writeSlowHookNotice(hookName, elapsedMs, writeErr);
   if (notice === null) return verdict;
-  writeErr(notice + "\n");
   return {
     ...verdict,
     additional_context: verdict.additional_context
@@ -162,9 +252,8 @@ export function reportSlowHook(
   emit,
   writeErr = (chunk) => process.stderr.write(chunk),
 ) {
-  const notice = slowHookNotice(hookName, elapsedMs);
+  const notice = writeSlowHookNotice(hookName, elapsedMs, writeErr);
   if (notice === null) return false;
-  writeErr(notice + "\n");
   emit(hookEventName, { additionalContext: notice });
   return true;
 }

package/claude-hooks/sanitize-output.mjs

@@ -98,13 +98,12 @@ const SANITIZE_BUDGET_MS = positiveMsOr(
 
 // Non-WARNING note for a strip whose only change was INERT ANSI on a local tool:
 // the display-only colour git/pytest/npm/etc. emit by default, and/or a stray
-// escape byte that formed no sequence at all (a truncated write, a log fragment,
-// a raw ESC sitting in a file the tool echoed back). Neither can move the cursor,
-// erase the screen, or open an OSC string — those need a complete CSI/OSC token,
-// which keeps the WARNING. The note keeps the "escapes were here, and here is how
-// to see them" signal without the WARNING prefix, whose constant firing on inert
-// bytes would desensitize the reader to the strips that matter (invisible-char
-// payloads, redacted secrets).
+// escape byte that formed no sequence at all. The engine now returns this text
+// itself, as a NOTE-severity finding alongside the warnings, so this copy is the
+// FALLBACK for exactly one case: a bundle built against a pinned engine older
+// than that severity split, whose result carries `sgrNote` but no `notes`. Same
+// sentence, so a plugin on the old pin keeps today's wording instead of falling
+// back to a bare "output sanitized".
 const SGR_OUTPUT_NOTE =
   "Inert ANSI stripped (display-only colour and/or a stray escape byte that " +
   "formed no control sequence); pipe through cat -v to inspect raw escapes.";
@@ -228,7 +227,7 @@ async function redactSecrets(text, webIngress = false, deadline) {
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   all leaves of one hook run; a direct caller gets a fresh full budget
  * @param {SanitizeExtensions} [ext]
- * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @returns {Promise<{ cleaned: string, warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export async function sanitizeText(
   text,
@@ -280,10 +279,15 @@ export async function sanitizeText(
         : { text: secrets.text, found: secrets.found };
     },
   };
-  const result =
-    /** @type {{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }} */ (
+  const seamResult =
+    /** @type {{ cleaned: string, warnings: string[], notes?: string[], modified: boolean, sgrNote: boolean, reveal?: string }} */ (
       await sanitizeTextSeam(text, seamOptions)
     );
+  // The one place the seam's shape is normalized: `notes` is absent when the
+  // engine predates the severity split, which is the shipped plugin's pinned
+  // case (see SGR_OUTPUT_NOTE). Defaulting here means nothing downstream has to
+  // know that, and the banner composer sees one shape either way.
+  const result = { ...seamResult, notes: seamResult.notes ?? [] };
   return ext.postText
     ? applyPostText(
         result,
@@ -300,12 +304,13 @@ export async function sanitizeText(
  * Fold a `postText` callback's result into the seam's, leaving the seam's result
  * untouched when the callback declined (null/undefined) or returned no `cleaned`.
  * `modified` widens to cover the callback's rewrite, and `sgrNote` is dropped
- * when it does: that flag downgrades the model-facing banner to "display-only
- * ANSI color stripped", which would be a false statement about bytes a callback
- * has since rewritten for its own reasons.
- * @param {{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }} result
+ * when it does: that flag downgrades the model-facing banner to the seam's
+ * notes, which would be a false account of bytes a callback has since rewritten
+ * for its own reasons. A callback's `warning` is taken at face value as a
+ * WARNING — the composer that linked it owns its wording and its volume alike.
+ * @param {{ cleaned: string, warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }} result
  * @param {{ cleaned?: string, warning?: string } | null | undefined} post
- * @returns {{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }}
+ * @returns {{ cleaned: string, warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }}
  */
 function applyPostText(result, post) {
   if (post === null || post === undefined) return result;
@@ -332,10 +337,10 @@ function applyPostText(result, post) {
  * too (a connector can hide a secret in a field name); non-string leaves
  * (booleans, numbers, null) pass through untouched, and `warnings` accumulates
  * across leaves.
- * `sgrNote` is the OR across leaves: true when some leaf was an SGR-only strip.
+ * `sgrNote` is the OR across leaves: true when some leaf came back note-only.
  * `reveals` accumulates each leaf's pre-Layer-2 text (when the HTML splice
- * removed something) for the orchestrator to persist — same mutated-accumulator
- * shape as `warnings`.
+ * removed something) for the orchestrator to persist, and `notes` the leaves'
+ * NOTE-severity findings — same mutated-accumulator shape as `warnings`.
  * @param {any} value
  * @param {string} toolName
  * @param {string[]} warnings
@@ -343,6 +348,8 @@ function applyPostText(result, post) {
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   every leaf of this value (created once by the top-level caller)
  * @param {SanitizeExtensions} [ext]
+ * @param {string[]} [notes]  appended last so an existing caller's positional
+ *   arguments keep their meaning
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
 export async function sanitizeValue(
@@ -352,10 +359,12 @@ export async function sanitizeValue(
   reveals = [],
   deadline = makeDeadline(SANITIZE_BUDGET_MS),
   ext = {},
+  notes = [],
 ) {
   if (typeof value === "string") {
     const result = await sanitizeText(value, toolName, deadline, ext);
     warnings.push(...result.warnings);
+    notes.push(...result.notes);
     if (result.reveal !== undefined) reveals.push(result.reveal);
     return {
       value: result.cleaned,
@@ -375,6 +384,7 @@ export async function sanitizeValue(
         reveals,
         deadline,
         ext,
+        notes,
       );
       out.push(result.value);
       if (result.modified) modified = true;
@@ -383,7 +393,15 @@ export async function sanitizeValue(
     return { value: out, modified, sgrNote };
   }
   if (value !== null && typeof value === "object")
-    return sanitizeObject(value, toolName, warnings, reveals, deadline, ext);
+    return sanitizeObject(
+      value,
+      toolName,
+      warnings,
+      reveals,
+      deadline,
+      ext,
+      notes,
+    );
   return { value, modified: false, sgrNote: false };
 }
 
@@ -398,6 +416,7 @@ export async function sanitizeValue(
  * @param {string[]} reveals
  * @param {{remainingMs: () => number}} deadline shared wall-clock budget
  * @param {SanitizeExtensions} ext
+ * @param {string[]} notes  accumulates the leaves' NOTE-severity findings
  * @returns {Promise<{ value: Record<string, any>, modified: boolean, sgrNote: boolean }>}
  */
 async function sanitizeObject(
@@ -407,6 +426,7 @@ async function sanitizeObject(
   reveals,
   deadline,
   ext,
+  notes,
 ) {
   /** @type {Record<string, any>} */
   const out = {};
@@ -420,6 +440,7 @@ async function sanitizeObject(
     // value leaves.
     const keyResult = await sanitizeText(key, toolName, deadline);
     warnings.push(...keyResult.warnings);
+    notes.push(...keyResult.notes);
     if (keyResult.reveal !== undefined) reveals.push(keyResult.reveal);
     if (keyResult.modified) modified = true;
     if (keyResult.sgrNote) sgrNote = true;
@@ -430,6 +451,7 @@ async function sanitizeObject(
       reveals,
       deadline,
       ext,
+      notes,
     );
     // Two distinct raw keys can sanitize to the same name (e.g. `token` and a
     // `token` carrying a zero-width space stripped by Layer 1). Overwriting would
@@ -725,6 +747,8 @@ export async function evaluateToolOutput(input, ext = {}) {
   /** @type {string[]} */
   const warnings = [];
   /** @type {string[]} */
+  const notes = [];
+  /** @type {string[]} */
   const reveals = [];
   // One shared wall-clock budget for every blocking daemon call this hook makes —
   // across all leaves of the walk AND the reveal-redaction loop below — so their
@@ -741,6 +765,7 @@ export async function evaluateToolOutput(input, ext = {}) {
     reveals,
     deadline,
     ext,
+    notes,
   );
   // Persist each leaf's pre-Layer-2 text (deduped by content) so the model can
   // Read back what the HTML splice removed; a successful write appends a hint
@@ -776,9 +801,13 @@ export async function evaluateToolOutput(input, ext = {}) {
     containsPlaceholder(toolOutput)
   )
     warnings.push(ON_DISK_PLACEHOLDER_WARNING);
-  // sgrNote implies modified (the carve-out lives inside the Layer-1 strip), so
-  // it never independently survives this guard — `modified` covers it.
-  if (!modified && warnings.length === 0)
+  // `notes` is part of the guard, not covered by `modified`. The Layer-1
+  // carve-out that used to be the only note DID imply a strip, but the
+  // detect-only tiers do not: a preserved `<script>` and a plain-link exfil URL
+  // change no bytes and raise no warning, so without this clause the walk would
+  // return `clean` and the note would not be quieter — it would be GONE, taking
+  // "do not fetch, relay, or embed these URLs" with it.
+  if (!modified && warnings.length === 0 && notes.length === 0)
     return revealRead
       ? emit("flagged", { additional_context: REVEAL_READ_ENVELOPE })
       : emit("clean", null);
@@ -790,13 +819,16 @@ export async function evaluateToolOutput(input, ext = {}) {
   // the model's view, not the side effects. Detect-only findings (preserved
   // scripting tags, exfil-shaped URLs) carry warnings with no text change; they
   // emit additional_context alone, leaving the output as the tool produced it. A
-  // pure display-only-SGR strip (sgrNote, no warning) gets the terse note instead
-  // of the WARNING prefix; once any real warning exists the WARNING path wins and
-  // the color note is dropped (warnings and sgrNote can co-occur across leaves of
-  // one tool output).
+  // note-only result (some leaf reported, none of it injection-shaped) gets the
+  // seam's own note text instead of the WARNING prefix — including the
+  // detect-only ones above, which reach here with `modified === false` and land
+  // on the `flagged` verdict below; once any real warning
+  // exists the WARNING path wins and the notes are dropped (warnings and notes
+  // can co-occur across leaves of one tool output, and the reader who has a
+  // hidden-HTML splice to read about does not also need the colour codes).
   const baseContext =
     sgrNote && warnings.length === 0
-      ? SGR_OUTPUT_NOTE
+      ? noteContext(notes)
       : composeContext(modified, warnings, input.tool_name);
   const additionalContext = revealRead
     ? `${REVEAL_READ_ENVELOPE} ${baseContext}`
@@ -807,6 +839,20 @@ export async function evaluateToolOutput(input, ext = {}) {
   return emit(modified ? "modified" : "flagged", fields);
 }
 
+/**
+ * The model-facing line for a note-only result: the seam's own note text,
+ * deduped and joined, with no WARNING prefix.
+ *
+ * Empty only against a pinned engine that predates the severity split (see
+ * SGR_OUTPUT_NOTE): there `sgrNote` still arrives true with no `notes` to go
+ * with it, and printing nothing would drop the one thing that run had to say.
+ * @param {string[]} notes
+ * @returns {string}
+ */
+function noteContext(notes) {
+  return notes.length === 0 ? SGR_OUTPUT_NOTE : [...new Set(notes)].join(" ");
+}
+
 /**
  * Judge a normalized PostToolUse event: run the sanitization pipeline and
  * express its outcome as a control-plane Verdict. sanitize-output only ever