agent-sanitizer 2.54.1 → 2.55.0

package/README.md

@@ -1,18 +1,6 @@
 # `agent-sanitizer`
 
-**Cleans untrusted text before your agent reads it.** An attacker hides a payload where a person cannot see it but the model still reads it: invisible Unicode, ANSI escapes, human-hidden HTML, confusable glyphs, look-alike hosts, and exfil-shaped URLs.
-
-This library handles each channel on its own terms. It strips invisible characters and ANSI escapes by default, splices out hidden HTML when you opt in, and _reports_ exfil-shaped URLs and look-alike hosts rather than rewriting them — mangling a legitimate link is the worse failure. Every layer is a deterministic transform, so you can unit-test it with equality assertions. There is no classifier and no model call, so nothing rests on whether a prediction generalized.
-
-**As a library:**
-
-```sh
-npm install agent-sanitizer
-```
-
-**As a Claude Code plugin:**
-
-Enter one at a time:
+**Cleans untrusted text before your agent reads it.** An attacker hides a payload where a person cannot see it but the model still reads it: invisible Unicode, ANSI escapes, human-hidden HTML, confusable glyphs, look-alike hosts, and exfil-shaped URLs. This library handles each channel. Easy to use as a Claude Code plugin, and the plugin itself is recommended by [`alignment-hive`](https://github.com/crazytieguy/alignment-hive/)!
 
 ```
 /plugin marketplace add AlexanderMattTurner/agent-sanitizer
@@ -291,7 +279,7 @@ singleton, and two copies in one bundle double-fire the inlined CLIs.
 | `claude-hooks/scan-loaded-instructions` | InstructionsLoaded scan of each instruction file as Claude Code loads it                   |
 | `claude-hooks/lib/hook-io`              | Shared hook I/O: the lazy-module registry, the CLI slot, deadlines, the hookgate marker    |
 | `claude-hooks/lib/control-plane`        | Bridge to `agent-control-plane-core` and the shared judge-CLI transport                    |
-| `claude-hooks/lib/authored-content`     | Stego + terminal-control stripping of the fields the MODEL authors                         |
+| `claude-hooks/lib/authored-content`     | Stego + terminal-control stripping of the fields the MODEL authors (colour is kept)        |
 | `claude-hooks/lib/env-config`           | The env-bound secret vocabulary the Layer-4 pre-gate and the redactor client share         |
 | `claude-hooks/lib/invisible-alert`      | Cross-hook alert state for uncleanable invisible-char injection in instruction files       |
 | `claude-hooks/lib/redactor-client`      | Client for the long-lived `agent-secret-redactor-daemon` (Layer 4's transport)             |

package/THREAT-MODEL.md

@@ -290,6 +290,51 @@ reconstitute a secret the first pass never saw intact. On `Bash.command` it runs
 before `sanitizeAuthoredContent`, which is the assumption the confusable-folding
 soundness argument below relies on.
 
+## Model-authored writes (tool input)
+
+`claude-hooks/lib/authored-content` scrubs what the model EMITS — the file
+content, edits, notebook cells and command bodies that get persisted or executed
+— rather than what it reads. Two protections, with different gates. Stego
+(format characters, variation selectors) is stripped only when the volume can
+carry a message, because authored content is persisted and incidental joiners
+are legitimate. Terminal-control sequences are stripped on sight: one cursor
+move, erase or OSC string in a file is a latent bomb the next `cat` fires, and
+one in a command spoofs what the user is shown as it runs.
+
+Display-only SGR colour is the exception, and is preserved byte-for-byte. The
+SGR grammar is closed — parameters and a final `m` — so it restyles visible text
+and can do nothing else; stripping it costs a model the colourized fixture, TUI
+golden file or prompt string it deliberately wrote, and buys no safety. Two
+shapes end the exception, both of them the model-sees/human-sees divergence
+rather than a display choice: a CONCEAL parameter (`ESC[8m`), which blanks the
+text that follows for a human while its bytes stay readable to a model, and a
+run of sequences with nothing that RENDERS between them, which puts no glyph on
+the screen at all and is therefore carrying data rather than colour. Either one
+strips the whole field.
+
+Both shapes are read as terminal semantics rather than token shapes, because a
+reader that matches shapes is one encoding away from the wrong answer. Conceal
+is threaded as STATE, so a reveal or reset later in the same sequence cancels it
+(`ESC[8;28;31m` renders red and visible) while an erase between two sequences
+does not. The parameters are read the way a terminal reads them, so an
+extended-colour argument is never mistaken for a parameter — `ESC[38;5;8m` is
+bright-black foreground, not conceal. And the run is counted over characters
+that render, so a zero-width separator between two sequences is as transparent
+here as it is to a terminal, while a space — which is what an ANSI-art colour
+bar puts between its codes — breaks the run.
+
+What that exception does NOT claim: a message spread thinly through
+legitimately coloured text — a sequence per line, encoding a bit — is
+indistinguishable from styling, and is left alone. That is the same bargain the
+invisible-character thresholds strike, in the same direction: an unprovable
+payload costs a false negative, while a wrong strip costs every colourized file
+its colour.
+
+Both protections run to a fixed point over each field rather than once each,
+because they feed one another: removing an invisible character completes a
+sequence that was incomplete when the terminal stage ran (`ESC[`⟨ZWSP⟩`2J`), and
+removing a sequence makes invisibles adjacent that were not.
+
 ## Confusable folding (tool input)
 
 `./confusables` folds look-alike glyphs in tool-call **input** fields (paths,

package/claude-hooks/lib/authored-content.mjs

@@ -15,11 +15,17 @@
  *      authored into a command — echoed and executed live — or into file
  *      content (a latent bomb when the file is later `cat`'d) can clear the
  *      screen, reposition the cursor, or overwrite what the user sees, hiding
- *      the real command behind spoofed output. Stripped *unconditionally*: a
- *      single sequence already does harm, so there is no volume threshold. The
- *      false-positive rate is low because real source represents escapes as
- *      *literals* (`\033`, `\x1b`, `\e`) — a *raw* ESC byte in authored content
- *      is anomalous.
+ *      the real command behind spoofed output. A single such sequence already
+ *      does harm, so there is no volume threshold: one of them strips the whole
+ *      field. Display-only SGR colour is the exception and is PRESERVED
+ *      byte-for-byte — it restyles text and can neither move the cursor nor
+ *      carry an OSC payload, so stripping it only costs a model the colourized
+ *      fixture, TUI golden file or prompt string it deliberately wrote. The
+ *      carve-out ends where SGR stops being styling (see the engine's
+ *      sgrCarriesPayload): a CONCEAL parameter blanks text for a human while a
+ *      model still reads it, and a long run of sequences with nothing that
+ *      renders between them puts no glyph on the screen at all, which is a
+ *      covert channel rather than colour.
  *
  * SCOPE IS DECLARED, NOT INFERRED. Which tools this layer touches is a
  * partition — {@link AUTHORED_FIELDS} (covered, with the field list) and
@@ -50,9 +56,10 @@ import { lazyImport } from "./hook-io.mjs";
 // static import of this module, before its fail-closed catch runs). A failed
 // load leaves these bindings undefined, so sanitizeField's calls throw into
 // the fail-closed catch (ask) instead.
-const { stripAnsiFully } = /** @type {typeof import("agent-sanitizer")} */ (
-  await lazyImport("agent-sanitizer")
-);
+const { stripAnsiFully, isBenignAnsiKinds, sgrCarriesPayload } =
+  /** @type {typeof import("agent-sanitizer")} */ (
+    await lazyImport("agent-sanitizer")
+  );
 const { STRIP, SCATTERED_THRESHOLD, hasLongRun, stripInvisible } =
   /** @type {typeof import("agent-sanitizer/invisible")} */ (
     await lazyImport("agent-sanitizer/invisible")
@@ -147,38 +154,84 @@ function isPayloadCapable(text) {
   return (text.match(STRIP)?.length ?? 0) >= SCATTERED_THRESHOLD;
 }
 
+/**
+ * The de-ANSI'd `text`, or `text` itself when its escapes are display-only
+ * colour a reader authored on purpose.
+ *
+ * The two questions are answered by two different views, deliberately.
+ * `isBenignAnsiKinds` reads the kinds the strip actually REMOVED, so a sequence
+ * that only reconstitutes mid-strip is judged as the sequence it becomes rather
+ * than as the incomplete one it started as. `sgrCarriesPayload` reads the RAW
+ * bytes, because those are the bytes a terminal renders on the preserve path —
+ * it makes no second pass, so there is nothing to reconstitute there.
+ *
+ * Only COMPLETE tokens reach `kinds`: an introducer that opens no sequence is
+ * left in place by `stripAnsiFully` (it rewrites no display), so the orphan arms
+ * of `isBenignAnsiKinds` never decide anything here.
+ * @param {string} text
+ * @returns {string}
+ */
+function stripTerminalControls(text) {
+  /** @type {Set<string>} TOKEN_KINDs the strip removed. */
+  const kinds = new Set();
+  const deAnsi = stripAnsiFully(text, kinds);
+  if (deAnsi === text) return text;
+  if (isBenignAnsiKinds(kinds) && !sgrCarriesPayload(text)) return text;
+  return deAnsi;
+}
+
+// How many rounds of {terminal-control, invisible} the field may take. The two
+// protections FEED each other: removing invisibles completes a sequence that was
+// incomplete when the terminal stage ran (`ESC[` ZWSP `2J` is an orphan until the
+// ZWSP goes), and removing a sequence makes invisibles adjacent that were not.
+// One round of each therefore leaves the composition unfinished. Each round
+// deletes at least one character, so the loop converges on its own; the bound is
+// a DoS guard. No residual sweep stands behind it — unlike the engine's
+// MAX_LAYER1_PASSES — so an unconverged value would persist a live sequence into
+// the file, and reaching the bound while still changing throws instead.
+const MAX_FIELD_PASSES = 3;
+
 // Returns the cleaned value plus the human-readable actions applied, or null if
 // the field is already clean. Each protection has its own opt-out (see the
 // header) so a deployment can keep one while dropping the other.
 /** @param {string} value */
 function sanitizeField(value) {
-  const actions = [];
+  // A Set, so a protection that fires in more than one round is described once.
+  /** @type {Set<string>} */
+  const actions = new Set();
   let cleaned = value;
 
-  // Strip terminal-control sequences first, so the invisible scan below runs on
-  // the same de-ANSI'd view sanitize-output uses (both go through the package's
-  // stripAnsiFully, which strips to a fixed point — so a sequence reconstituted
-  // when an inner one is removed is itself stripped on the next pass). Compare
-  // before/after rather than pre-testing for ESC: a lone control byte that forms
-  // no real sequence does not rewrite the display and is left alone, so we only
-  // report a genuine strip.
-  if (process.env.AGENT_SANITIZER_TERMINAL_DISABLED !== "1") {
-    const deAnsi = stripAnsiFully(cleaned);
-    if (deAnsi !== cleaned) {
-      cleaned = deAnsi;
-      actions.push("terminal-control sequences");
+  for (let pass = 0; pass < MAX_FIELD_PASSES; pass++) {
+    const before = cleaned;
+    // Terminal controls first, so the invisible scan runs on the same de-ANSI'd
+    // view sanitize-output uses. Compare before/after rather than pre-testing
+    // for ESC: escapes this layer deliberately leaves in place — a lone control
+    // byte, display-only colour — must not be reported as a strip.
+    if (process.env.AGENT_SANITIZER_TERMINAL_DISABLED !== "1") {
+      const deAnsi = stripTerminalControls(cleaned);
+      if (deAnsi !== cleaned) {
+        cleaned = deAnsi;
+        actions.add("terminal-control sequences");
+      }
     }
-  }
 
-  if (
-    process.env.AGENT_SANITIZER_INVISIBLE_DISABLED !== "1" &&
-    isPayloadCapable(cleaned)
-  ) {
-    cleaned = stripInvisible(cleaned);
-    actions.push("invisible characters");
+    if (
+      process.env.AGENT_SANITIZER_INVISIBLE_DISABLED !== "1" &&
+      isPayloadCapable(cleaned)
+    ) {
+      cleaned = stripInvisible(cleaned);
+      actions.add("invisible characters");
+    }
+    if (cleaned === before) break;
+    // This refusal is what blocks a still-changing value — one whose next round
+    // would remove another live sequence — from being written to the file.
+    if (pass === MAX_FIELD_PASSES - 1)
+      throw new Error(
+        "authored content did not reach a fixed point within MAX_FIELD_PASSES",
+      );
   }
 
-  return actions.length > 0 ? { cleaned, actions } : null;
+  return actions.size > 0 ? { cleaned, actions: [...actions] } : null;
 }
 
 /** @param {string[]} changed */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.54.1",
+  "version": "2.55.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/ansi.mjs

@@ -205,6 +205,32 @@ export const ESCAPE_SEQUENCE_SOURCE = (() => {
   return `(?:${stringArm}|${csiArm})`;
 })();
 
+// The three SGR parameters that move the CONCEAL state (ECMA-48 § 8.3.117).
+// Conceal renders the text that follows as blank while its bytes stay in the
+// file, so a human reading with `cat` sees nothing where a model reads
+// everything — a model-sees/human-sees divergence rather than a display choice.
+const SGR_RESET = 0;
+const SGR_CONCEAL = 8;
+const SGR_REVEAL = 28;
+// The extended-colour selectors. Their ARGUMENTS follow as further semicolon
+// parameters, so a reader that does not consume them reads a colour component as
+// a parameter of its own: `ESC[38;5;8m` is bright-black foreground, not conceal.
+const SGR_EXTENDED_COLOUR = new Set([38, 48, 58]);
+// How many parameters an extended-colour selector consumes after itself, keyed
+// by the colour-space selector that follows it, per ITU T.416 § 13.1.8: the
+// implementation-defined and transparent forms take none, direct-colour RGB and
+// CMY take three components, CMYK four, and indexed takes one palette entry.
+// Every selector the spec defines, so a value missing from this table is
+// malformed rather than merely unimplemented.
+const SGR_COLOUR_ARGS = new Map([
+  [0, 0],
+  [1, 0],
+  [2, 3],
+  [3, 3],
+  [4, 4],
+  [5, 1],
+]);
+
 /** The seven things an introducer can turn out to be. */
 export const TOKEN_KIND = Object.freeze({
   /** A display-only `ESC[…m` / `U+009B…m` colour sequence. */
@@ -424,3 +450,51 @@ export function scanAnsi(text) {
   }
   return tokens;
 }
+
+/**
+ * The CONCEAL state after the SGR token `token` is applied to a terminal already
+ * in state `concealed` — the state in which a terminal renders what follows as
+ * blank while its bytes stay readable to anything reading the file.
+ *
+ * A TRANSITION, not a property of the token: conceal is terminal state that
+ * outlives the sequence that set it, so `ESC[8m` followed by `ESC[31m` is still
+ * concealed — a per-token predicate would read the second token as "no conceal
+ * here" and lose the state. Only `8` (set), `28` (reveal) and `0` (reset all)
+ * move it, and the token's parameters are applied in order, so a later reveal or
+ * reset in the SAME token cancels an earlier `8`: `ESC[8;28;31m` renders red and
+ * visible.
+ *
+ * The parameters are read the way a terminal reads them rather than scanned for
+ * the digit. `38`/`48`/`58` take their colour arguments from the parameters that
+ * FOLLOW them in the semicolon form, so `ESC[38;5;8m` is bright-black foreground
+ * and its `8` is a palette index; a parameter carrying its arguments as ITU T.416
+ * sub-parameters (`38:5:8`) is self-contained, so only its head counts and
+ * nothing after it is consumed. A colour-space selector T.416 gives no argument
+ * count for is malformed, and a terminal that ignores the colour form still
+ * applies what follows it, so the scan CONTINUES from the next parameter rather
+ * than consuming arguments it cannot size — reading one parameter too many costs
+ * a token shape no emitter produces, while stopping there would hand
+ * `ESC[38;9;8m` a pass.
+ * @param {string} token  a token {@link scanAnsi} classified {@link TOKEN_KIND.SGR}
+ * @param {boolean} concealed  the state before this token
+ * @returns {boolean}
+ */
+export function sgrConcealState(token, concealed) {
+  // The parameter bytes: everything between the introducer (two characters in
+  // the 7-bit `ESC [` form, one in the 8-bit C1 form) and the final `m`.
+  const params = token
+    .slice(token.charCodeAt(0) === ESC ? 2 : 1, -1)
+    .split(";");
+  let state = concealed;
+  for (let i = 0; i < params.length; i++) {
+    const colonForm = params[i].includes(":");
+    // An omitted parameter is 0 (`ESC[m` is `ESC[0m`), which `Number("")` gives.
+    const value = Number(params[i].split(":")[0]);
+    if (value === SGR_CONCEAL) state = true;
+    else if (value === SGR_REVEAL || value === SGR_RESET) state = false;
+    if (colonForm || !SGR_EXTENDED_COLOUR.has(value)) continue;
+    const args = SGR_COLOUR_ARGS.get(Number(params[i + 1]));
+    if (args !== undefined) i += 1 + args;
+  }
+  return state;
+}

package/src/index.mjs

@@ -30,6 +30,8 @@ export {
   isBenignAnsiKinds,
   normalizeLoneSurrogates,
   stripAnsiFully,
+  sgrCarriesPayload,
+  SGR_RUN_THRESHOLD,
   LONE_SURROGATE_RE,
 } from "./layer1.mjs";
 

package/src/layer1.mjs

@@ -21,12 +21,13 @@
  * runs, and a consumer deriving offsets for redaction or view mapping wants that
  * one — see its own doc for why the choice matters.
  */
-import { stripInvisibleWithReport, CATEGORY } from "./invisible.mjs";
+import { stripInvisibleWithReport, CATEGORY, STRIP } from "./invisible.mjs";
 import {
   CONTROL_INTRODUCER_SOURCE,
   isOrphanKind,
   orphanKindFor,
   scanAnsi,
+  sgrConcealState,
   TOKEN_KIND,
 } from "./ansi.mjs";
 
@@ -172,6 +173,79 @@ export function isBenignAnsiKinds(kinds) {
   );
 }
 
+/**
+ * How many SGR sequences may sit back to back, with nothing that RENDERS between
+ * them, before the run is read as a covert channel rather than styling.
+ *
+ * A styling emitter puts colour AROUND text: `ls --color`, chalk and pygments
+ * chain at most a handful of attributes before the glyphs they style. A run of
+ * escape sequences that puts no glyph on the screen renders as literally nothing
+ * to a human while a model reads every byte, so past some length the run is not
+ * styling any more — it is a message, in the same shape (and for the same
+ * reason) as the invisible layer's LONG_RUN_THRESHOLD. Ten matches that
+ * threshold and sits well above what a real emitter chains.
+ */
+export const SGR_RUN_THRESHOLD = 10;
+
+/**
+ * True when nothing in `gap` puts a glyph on the screen — the one primitive both
+ * arms of {@link sgrCarriesPayload} ask about. {@link STRIP} is the engine's
+ * single definition of a character with no visible presence, so a zero-width
+ * separator between two sequences is transparent here exactly as it is to a
+ * terminal, while a SPACE is not.
+ * @param {string} gap
+ * @returns {boolean}
+ */
+function rendersNothing(gap) {
+  return gap.replace(STRIP, "") === "";
+}
+
+/**
+ * True when the SGR sequences in `text` do more than style visible text — the
+ * question a consumer must answer before PRESERVING escapes rather than
+ * stripping them. Two arms, both model-sees/human-sees divergences:
+ *
+ *   1. CONCEAL is on while text that would otherwise render goes by, or the text
+ *      ENDS concealed (hiding its own tail, and everything the terminal prints
+ *      afterwards). Only SGR moves that state (see {@link sgrConcealState}) — a
+ *      cursor move or an erase leaves a terminal exactly as concealed as it was.
+ *   2. {@link SGR_RUN_THRESHOLD} sequences with nothing that renders between
+ *      them: the run puts no glyph on the screen, so it carries data rather than
+ *      styling.
+ *
+ * What it does NOT claim: a message spread thinly through legitimately coloured
+ * text — one sequence per line, say — is indistinguishable from styling, and
+ * this answers no for it. That is the same bargain the invisible layer's
+ * thresholds strike, and the same direction: an unprovable payload is left alone
+ * rather than costing every colourized file its colour.
+ *
+ * Scans the RAW text in one pass, which is what a terminal does with these
+ * bytes — no reconstitution across passes, because a preserved byte is never
+ * removed to complete a sequence around it.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function sgrCarriesPayload(text) {
+  let concealed = false;
+  let run = 0;
+  let previousEnd = 0;
+  for (const token of scanAnsi(text)) {
+    const blankGap = rendersNothing(text.slice(previousEnd, token.start));
+    previousEnd = token.end;
+    if (token.kind !== TOKEN_KIND.SGR) {
+      run = 0;
+      continue;
+    }
+    // This refusal is what blocks `ESC[8m` from hiding text from the human
+    // while leaving its bytes for the model.
+    if (concealed && !blankGap) return true;
+    run = blankGap ? run + 1 : 1;
+    if (run >= SGR_RUN_THRESHOLD) return true;
+    concealed = sgrConcealState(text.slice(token.start, token.end), concealed);
+  }
+  return concealed;
+}
+
 /**
  * {@link isBenignAnsiKinds} for callers that hold only the text — it runs the
  * full Layer-1 composition to get the fixed-point view. Callers that already

package/types/ansi.d.mts

@@ -38,6 +38,35 @@ export function orphanKindFor(ch: string, next?: string): string;
  * @returns {AnsiToken[]}
  */
 export function scanAnsi(text: string): AnsiToken[];
+/**
+ * The CONCEAL state after the SGR token `token` is applied to a terminal already
+ * in state `concealed` — the state in which a terminal renders what follows as
+ * blank while its bytes stay readable to anything reading the file.
+ *
+ * A TRANSITION, not a property of the token: conceal is terminal state that
+ * outlives the sequence that set it, so `ESC[8m` followed by `ESC[31m` is still
+ * concealed — a per-token predicate would read the second token as "no conceal
+ * here" and lose the state. Only `8` (set), `28` (reveal) and `0` (reset all)
+ * move it, and the token's parameters are applied in order, so a later reveal or
+ * reset in the SAME token cancels an earlier `8`: `ESC[8;28;31m` renders red and
+ * visible.
+ *
+ * The parameters are read the way a terminal reads them rather than scanned for
+ * the digit. `38`/`48`/`58` take their colour arguments from the parameters that
+ * FOLLOW them in the semicolon form, so `ESC[38;5;8m` is bright-black foreground
+ * and its `8` is a palette index; a parameter carrying its arguments as ITU T.416
+ * sub-parameters (`38:5:8`) is self-contained, so only its head counts and
+ * nothing after it is consumed. A colour-space selector T.416 gives no argument
+ * count for is malformed, and a terminal that ignores the colour form still
+ * applies what follows it, so the scan CONTINUES from the next parameter rather
+ * than consuming arguments it cannot size — reading one parameter too many costs
+ * a token shape no emitter produces, while stopping there would hand
+ * `ESC[38;9;8m` a pass.
+ * @param {string} token  a token {@link scanAnsi} classified {@link TOKEN_KIND.SGR}
+ * @param {boolean} concealed  the state before this token
+ * @returns {boolean}
+ */
+export function sgrConcealState(token: string, concealed: boolean): boolean;
 /**
  * The ONE ANSI grammar: the raw control-introducer charset and the tokenizer
  * every consumer scans with.

package/types/index.d.mts

@@ -58,6 +58,6 @@ export function sanitize(text: string, options?: {
         original: string;
     }>;
 }>;
-export { applyLayer1, applyLayer1WellFormed, isBenignAnsi, isBenignAnsiKinds, normalizeLoneSurrogates, stripAnsiFully, LONE_SURROGATE_RE } from "./layer1.mjs";
+export { applyLayer1, applyLayer1WellFormed, isBenignAnsi, isBenignAnsiKinds, normalizeLoneSurrogates, stripAnsiFully, sgrCarriesPayload, SGR_RUN_THRESHOLD, LONE_SURROGATE_RE } from "./layer1.mjs";
 export { stripInvisible, stripInvisibleWithReport, isSgrOnly, STRIP, SGR_RE, CHECKS, CATEGORY, CATEGORY_LABELS, LINGUISTIC_SCRIPTS, VS, BLANK_NON_CF, LONG_RUN_RE, LONG_RUN_THRESHOLD, SCATTERED_THRESHOLD, findLongRuns, hasLongRun } from "./invisible.mjs";
 export { HTML_TAG_PRESENT, MD_LINK_HINT, SECRET_HINT, SECRET_HINT_EXT, matchesSecretHint } from "./gates.mjs";

package/types/layer1.d.mts

@@ -49,6 +49,32 @@ export function stripAnsiFully(input: string, kinds?: Set<string>): string;
  * @returns {boolean}
  */
 export function isBenignAnsiKinds(kinds: readonly string[] | Set<string>): boolean;
+/**
+ * True when the SGR sequences in `text` do more than style visible text — the
+ * question a consumer must answer before PRESERVING escapes rather than
+ * stripping them. Two arms, both model-sees/human-sees divergences:
+ *
+ *   1. CONCEAL is on while text that would otherwise render goes by, or the text
+ *      ENDS concealed (hiding its own tail, and everything the terminal prints
+ *      afterwards). Only SGR moves that state (see {@link sgrConcealState}) — a
+ *      cursor move or an erase leaves a terminal exactly as concealed as it was.
+ *   2. {@link SGR_RUN_THRESHOLD} sequences with nothing that renders between
+ *      them: the run puts no glyph on the screen, so it carries data rather than
+ *      styling.
+ *
+ * What it does NOT claim: a message spread thinly through legitimately coloured
+ * text — one sequence per line, say — is indistinguishable from styling, and
+ * this answers no for it. That is the same bargain the invisible layer's
+ * thresholds strike, and the same direction: an unprovable payload is left alone
+ * rather than costing every colourized file its colour.
+ *
+ * Scans the RAW text in one pass, which is what a terminal does with these
+ * bytes — no reconstitution across passes, because a preserved byte is never
+ * removed to complete a sequence around it.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function sgrCarriesPayload(text: string): boolean;
 /**
  * {@link isBenignAnsiKinds} for callers that hold only the text — it runs the
  * full Layer-1 composition to get the fixed-point view. Callers that already
@@ -147,3 +173,16 @@ export const LONE_SURROGATE_RE: RegExp;
  * colour codes, and here is how to look at the raw bytes".
  */
 export const INERT_ANSI_NOTE: string;
+/**
+ * How many SGR sequences may sit back to back, with nothing that RENDERS between
+ * them, before the run is read as a covert channel rather than styling.
+ *
+ * A styling emitter puts colour AROUND text: `ls --color`, chalk and pygments
+ * chain at most a handful of attributes before the glyphs they style. A run of
+ * escape sequences that puts no glyph on the screen renders as literally nothing
+ * to a human while a model reads every byte, so past some length the run is not
+ * styling any more — it is a message, in the same shape (and for the same
+ * reason) as the invisible layer's LONG_RUN_THRESHOLD. Ten matches that
+ * threshold and sits well above what a real emitter chains.
+ */
+export const SGR_RUN_THRESHOLD: 10;