@mcp-index/sdk 0.9.2 → 0.11.0

package/dist/src/gate.js

@@ -6,12 +6,12 @@
  * per-server POSTURE. NO credential, NO transport, NO network: the Gate reads
  * only the PUBLIC contract dict the caller observed.
  */
-import { Decision, hashTool, makeVerdict, utcNowIso, } from "./preflight.js";
-import { ChangeKind, classifyChange, isSafetyRelevant } from "./schemaDiff.js";
+import { Decision, HoldClass, hashTool, makeVerdict, utcNowIso, } from "./preflight.js";
+import { ChangeKind, classifyChange, isNumericOnlyDescriptionChange, isSafetyRelevant, } from "./schemaDiff.js";
 import { assess, blastRank } from "./risk.js";
 import { classifyToolDef } from "./actionClass.js";
 import { scanSchemaHasMarker } from "./scan.js";
-import { mdText } from "./render.js";
+import { mdText, stripControl } from "./render.js";
 import { redactGreenWords } from "./provenance.js";
 import { Operation } from "./errors.js";
 import { driftTelemetry } from "./driftTelemetry.js";
@@ -57,7 +57,7 @@ const BREAKING_KIND_REASON = {
     [ChangeKind.ENUM_VALUES_REMOVED]: "an allowed value was removed — a value your calls send may now be rejected",
     [ChangeKind.CONSTRAINT_NARROWED]: "an input rule was tightened — a value your calls send may now be rejected",
     [ChangeKind.TOOL_REMOVED]: "this tool was removed from the server",
-    [ChangeKind.DEEP_SCHEMA_UNDIFFABLE]: "this tool's schema changed too deeply to verify automatically; held to be safe",
+    [ChangeKind.DEEP_SCHEMA_UNDIFFABLE]: "this tool's schema changed too deeply to diff automatically; held rather than guessed",
 };
 const DANGEROUS_REASON_MARKERS = [
     "risk ESCALATED",
@@ -70,7 +70,24 @@ const DANGEROUS_REASON_MARKERS = [
 ];
 const BRAND_MARK = "⬡ mcpindex";
 export const HELD_PROVENANCE_UNAVAILABLE_BANNER = `${BRAND_MARK} — held a call before your agent ran it (provenance unavailable; no detail shown).`;
-export const INTERNAL_ERROR_HELD_MESSAGE = `${BRAND_MARK} internal error — held this call for safety. [Override]`;
+/** The AGENT-facing twin of the banner above. Same fact, no brand glyph, no chrome.
+ *
+ * INSTANCE FOURTEEN, found in round 9 and present in both languages. `heldSurface` has two
+ * early returns, one line apart, that both put a constant in the AGENT-message position and
+ * bypass `renderHoldMessage` entirely. Round 7 fixed the internal-error one and left this
+ * sibling, which shipped the brand glyph to the agent channel - the exact tell the suite's
+ * first test bans, and one the 2026-08-05 model named when it read the hold as a UI trying to
+ * persuade it. That test only ever ran against the renderer.
+ *
+ * The banner keeps its glyph: a HUMAN still reads it via `holdBanner()`. One fact, two
+ * readers, two renderings - the same split this whole change is about. */
+export const HELD_PROVENANCE_UNAVAILABLE_MESSAGE = 'mcpindex — local contract gate — held this call before your agent ran it. The record ' +
+    'behind it could not be assembled, so no detail is shown.';
+// NO AFFORDANCE, NO GREEN WORD - see the Python twin. `[Override]` points at
+// `Action.OVERRIDE`, which bypasses the gate entirely: strictly stronger than the repin
+// chips that were removed from this channel for exactly this reason.
+export const INTERNAL_ERROR_HELD_MESSAGE = "mcpindex — local contract gate — mcpindex's own code failed, so this call was NOT sent " +
+    "to the server. Nothing ran. This is our failure, not a finding about the tool.";
 const INTERNAL_ERROR_REASON_HOLD = "mcpindex internal error — held for safety";
 export function isInternalErrorVerdict(verdict) {
     return verdict.reason === INTERNAL_ERROR_REASON_HOLD;
@@ -81,6 +98,7 @@ export function internalErrorHold(serverId, toolName) {
         toolName,
         decision: Decision.HOLD,
         reason: INTERNAL_ERROR_REASON_HOLD,
+        holdClass: HoldClass.INTERNAL, // our own code failed
         isContractDiff: false,
     });
 }
@@ -151,7 +169,13 @@ function friendlyBreakingClause(verdict) {
 }
 function bannerWhatChanged(verdict) {
     if (verdict.descBefore !== null || verdict.descAfter !== null) {
-        return "a tool's description changed (the agent-consumed channel)";
+        const base = "a tool's description changed (the agent-consumed channel)";
+        if (verdict.descBefore !== null &&
+            verdict.descAfter !== null &&
+            isNumericOnlyDescriptionChange(verdict.descBefore, verdict.descAfter)) {
+            return base + "; only the numbers moved, the prose is identical";
+        }
+        return base;
     }
     const friendly = friendlyBreakingClause(verdict);
     if (friendly !== null)
@@ -167,10 +191,332 @@ function bannerWhatChanged(verdict) {
     }
     return mdText(verdict.reason);
 }
-export function renderHoldBanner(verdict, monthlyCount = null) {
+// ------------------------------------------------------------- agent-facing HOLD text
+// Byte-for-byte parity with the Python side (`gate.render_hold_message`). Bounds exist
+// because an attacker controls how many paths drift and what they are named: an unbounded
+// render is a denial-of-legibility vector - the agent stops reading and falls back to
+// "this looks like an attack".
+const EVIDENCE_ROW_CAP = 6;
+const SENT_KEY_CAP = 12;
+// Row caps bound CARDINALITY; this bounds LENGTH. Truncate BEFORE escaping so a cut can
+// never land mid-escape-sequence.
+const VALUE_CHAR_CAP = 120;
+/** Bound, escape, then redact one attacker-derived value. Order is load-bearing: redacting
+ * before escaping would turn the `[redacted]` placeholder into `\[redacted\]`. Per-value
+ * rather than over the joined message, so redaction can only touch attacker-derived spans -
+ * over the whole render it also hit our own prose and the pin path. */
+function untrusted(value) {
+    // Collapse whitespace RUNS first - see the Python twin. The block is column-aligned, so
+    // preserved consecutive spaces let an attacker forge a second column.
+    // Explicit class, NOT `\s` - the two languages' `\s` sets differ. See the Python twin.
+    const flat = value.replace(/[ \t\n\r\f\v\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+/gu, " ");
+    // Code POINTS, not UTF-16 units: `.slice` can split a surrogate pair and diverges from
+    // Python's codepoint slice, so the two SDKs would truncate at different offsets.
+    const cp = [...flat];
+    const bounded = cp.length > VALUE_CHAR_CAP ? `${cp.slice(0, VALUE_CHAR_CAP).join("")}...` : flat;
+    return redactGreenWords(mdText(bounded));
+}
+// The line that would have prevented the 2026-08-05 incident on its own. A mid-session
+// drift is caught against the LIVE contract, but the model's tool list is whatever it last
+// fetched, so the agent's own view legitimately disagrees with us. Left unsaid, the agent
+// experiences that as us asserting something demonstrably false - indistinguishable from
+// being lied to, and it correctly refused. Said plainly, the mismatch becomes corroborating.
+const STALE_LIST_NOTE = "Your cached tool list may still show the pinned contract; the change was observed at " +
+    "the server after this session listed tools. That mismatch is expected and is what was " +
+    "caught.";
+const HONESTY_NOTE = "This is a contract diff, not a safety verdict: no claim is made about intent.";
+// CONSTRAIN, NEVER EXPAND. This message travels on the wrapped server's own error channel -
+// from the agent's seat it is attacker-controlled text, so it may only narrow what the agent
+// does. It must never invite an action that CHANGES TRUST STATE: `[Review · Re-pin ·
+// Validate]` pointed at `repin()`, which makes a changed contract the new trusted baseline -
+// i.e. the gate was emitting, on an untrusted channel, precisely the text an attacker would
+// forge to get a hostile contract blessed. A forged "stop and ask your human" earns an
+// attacker nothing, which is what makes this direction safe to say here.
+const DISPOSITION_NOTE = "Retrying will not clear this, and supplying the changed parameter does not either — " +
+    "re-pinning is a trust decision for the person running this agent.";
+// INCONCLUSIVE resolution stated as a FACT, never as an offer: the behavioral check can move
+// a verdict, so inviting the agent to run it would be an action that changes trust state.
+// The RESULT-WITHHELD hold fires AFTER the call executed, and only for high-blast tools.
+// The contract-diff prose is false there - most dangerously the headline.
+const RESULT_HEADLINE = "mcpindex — local contract gate — this call RAN and its side effect, if any, already " +
+    "happened; only its RESULT was withheld. Do not retry.";
+const RESULT_HONESTY_NOTE = "This is a result-content finding, not a safety verdict and not a contract diff: the " +
+    "side effect, if any, has already happened.";
+const RESULT_DISPOSITION_NOTE = "Retrying would run the call again. Whether to read the withheld content is a decision " +
+    "for the person running this agent.";
+// `isContractDiff === false` covers TWO shapes with OPPOSITE execution semantics: a
+// result-withhold hold RAN, an internal-error hold did NOT - our own code failed before the
+// call left the process. See the Python twin.
+const INTERNAL_HEADLINE = "mcpindex — local contract gate — mcpindex's own code failed, so this call was NOT sent " +
+    "to the server. Nothing ran.";
+const INTERNAL_NOTE = "This is our failure, not a finding about the tool: no contract change was observed and " +
+    "no claim is made about this tool. The gate fails closed, so the call was held rather " +
+    "than let through unchecked.";
+const DRILL_DISPOSITION_NOTE = "Nothing about this tool changed. The rehearsal is over - it is one-shot and has already " +
+    "disarmed itself - so the next call to this tool proceeds normally.";
+// The un-checkable pre-flight shapes: no pin, tool absent from the listing, derivation error.
+// Nothing was COMPARED, and unlike a real drift the remedy is often just to list and retry.
+// A comparison RAN; something other than a diff fired. Distinct from "uncheckable" (nothing
+// was compared) and from "drift" (a difference was found).
+const FINDING_NOTE = "The contract was checked and something other than a difference stopped this call - the " +
+    "reason above says what. This is a finding about the tool's definition, not a claim " +
+    "about intent, and not a safety verdict.";
+const FINDING_DISPOSITION_NOTE = "Retrying will not clear this on its own. Whether to proceed is a decision for the " +
+    "person running this agent.";
+// The contract is FINE - this tool is held on what the call can DO, not on what it declares.
+const APPROVAL_NOTE = "Nothing about this tool's contract changed - it matches the pinned baseline. It is held " +
+    "because of what the call can do, not what it declares.";
+const APPROVAL_DISPOSITION_NOTE = "This class of action is never run unattended. It needs a person, and no retry or " +
+    "argument change reaches one.";
+const UNCHECKABLE_NOTE = "No contract comparison was possible here - the reason above says why. The gate fails " +
+    "closed rather than let an unverified call through.";
+// NEVER NAME THE UNBLOCKING ACTION - see the Python twin. `observe()` TOFU-writes the pin
+// store, so naming it here is an instruction for the one action that mints a trust baseline.
+// "No baseline exists for this tool in this session" was asserted here as flat fact and is
+// FALSE on six of the seven situations that reach this class - a pinned tool absent from the
+// live listing, a hash-derivation error, a declined battery. Attacker-triggerable on one: a
+// hostile server drops a PINNED tool from tools/list and the agent is told the tool was never
+// pinned rather than that its pinned tool vanished, nine lines above an anchor naming the pin
+// file. Fixed in the Python twin in round 7 and left live here for a release - which is why
+// `holdMessage.test.ts` now pins these constants across both languages.
+const UNCHECKABLE_DISPOSITION_NOTE = "Whether to establish or restore a baseline for this tool is a trust decision for the " +
+    "person running this agent.";
+const INTERNAL_DISPOSITION_NOTE = "Nothing has happened yet, so a retry repeats nothing - but it will likely fail the " +
+    "same way until the gate is fixed or removed.";
+const INCONCLUSIVE_NOTE = "Resolving this needs behavioral verification, which is a human-initiated action.";
+// A staged drill MUST be distinguishable from a real hold on the agent channel, not just in
+// `data.drill`. An agent that reads a rehearsal as a live security event escalates a false
+// alarm to its user - which is how you train someone to ignore the real thing.
+const DRILL_HEADLINE = "[DRILL] mcpindex — local contract gate — this is a STAGED REHEARSAL, not a real " +
+    "contract change. The call was not forwarded.";
+const DRILL_NOTE = "The change above is synthetic - nothing about this tool actually changed, and no " +
+    "parameter needs supplying.";
+function evidenceRows(verdict, sentKeys, drill = false) {
+    const rows = [["tool", untrusted(verdict.toolName)]];
+    // Sort before capping so the same drift always renders the same rows - non-determinism
+    // here would break cross-language parity with the Python renderer.
+    const changes = [...verdict.drift].sort((a, b) => {
+        if (a.safetyRelevant !== b.safetyRelevant)
+            return a.safetyRelevant ? -1 : 1;
+        // Codepoint compare, NOT localeCompare: the latter is locale/ICU-dependent and diverges
+        // from Python's `sorted()`, so with a 6-row cap the two SDKs could display different
+        // evidence for identical drift.
+        const ak = a.kind.toString();
+        const bk = b.kind.toString();
+        if (ak !== bk)
+            return ak < bk ? -1 : 1;
+        const ap = a.path ?? "";
+        const bp = b.path ?? "";
+        return ap < bp ? -1 : ap > bp ? 1 : 0;
+    });
+    for (const change of changes.slice(0, EVIDENCE_ROW_CAP)) {
+        // `kind` is a ChangeKind member - closed vocabulary. `path` IS attacker-derived and is
+        // escaped, exactly as before: the defence is unchanged, only its location moved.
+        const where = change.path ? ` at ${untrusted(change.path)}` : "";
+        // On a drill the change is INVENTED - see the Python twin.
+        rows.push([drill ? "staged change" : "change", `${change.kind.toString()}${where}`]);
+    }
+    if (changes.length > EVIDENCE_ROW_CAP) {
+        rows.push([drill ? "staged change" : "change", `... and ${changes.length - EVIDENCE_ROW_CAP} more`]);
+    }
+    // `reason` on a non-contract-diff hold is OURS, not the server's: truncating it deletes
+    // the corrective clause that distinguishes a result hold from a drift.
+    // See the Python twin: on the internal-error shape the headline states the whole case and
+    // the sentinel carries a green word, so the row is dropped rather than rendered.
+    if (changes.length === 0 && verdict.holdClass !== HoldClass.INTERNAL) {
+        rows.push([
+            "reason",
+            untrusted(verdict.reason),
+        ]);
+    }
+    // Plain-language CONSEQUENCE of the most-severe breaking kind, from the closed curated
+    // `BREAKING_KIND_REASON` vocabulary (never attacker-derived, so no escaping needed). An
+    // agent reasoning about how to report a hold needs the effect, not just the label.
+    // No `effect` row on a drill: the consequence it describes will never happen.
+    const friendly = drill ? null : friendlyBreakingClause(verdict);
+    if (friendly !== null)
+        rows.push(["effect", friendly]);
+    if (sentKeys !== null) {
+        // NAMES ONLY, NEVER VALUES. Values can carry credentials and PII; names are
+        // contract-level data already in the pinned schema and already held by the agent.
+        const shown = [...sentKeys].sort().slice(0, SENT_KEY_CAP);
+        const more = sentKeys.length - shown.length;
+        let rendered = shown.length > 0 ? shown.map(untrusted).join(", ") : "(none)";
+        if (more > 0)
+            rendered += `, ... and ${more} more`;
+        rows.push(["call sent", rendered]);
+    }
+    return rows;
+}
+/**
+ * The AGENT-facing HOLD text: evidence over assertion, constrain never expand.
+ *
+ * `renderHoldBanner` is the HUMAN brand moment and is unchanged - it still renders for
+ * hosts and operators. But it was ALSO the thrown message, which is read by a MODEL.
+ * Observed 2026-08-05: Claude Opus 4.8 classified that banner as a prompt-injection
+ * attempt, refused to act on it, retried the held call, and told the user something
+ * suspicious was intercepting its tools.
+ *
+ * Its load-bearing objection was not tone - it was that it could not VERIFY us: the gate
+ * diffs the pin against the LIVE contract, while the agent sees only its own cached tool
+ * list, a third view that legitimately disagrees. Asserting a change the reader cannot
+ * observe, then inviting it to act, is the exact shape of a manipulation attempt.
+ *
+ * Every defence is unchanged: `mdText` on each attacker-derived value, `redactGreenWords`
+ * over the whole output, fail-closed behaviour untouched.
+ */
+export function renderHoldMessage(verdict, sentKeys = null, pinPath = null, drill = false) {
+    // SPLIT FROM `assembleHoldMessage` for the reason the Python twin documents: when
+    // assembly and redaction were one function, `redactAgentUnsafe` stripped a banned token
+    // from OUR OWN prose before any test could observe it, so a mutation restoring instance
+    // twelve verbatim into a producer reason left the suite green. Redaction defends against
+    // the attacker; our prose has to be clean before it runs, and the suite asserts that
+    // against the RAW assembly.
+    const text = redactAgentUnsafe(assembleHoldMessage(verdict, sentKeys, pinPath, drill));
+    if (agentChannelViolation(verdict, text) !== null)
+        return MINIMAL_HOLD_MESSAGE;
+    return text;
+}
+/** The minimal HOLD text: claims nothing beyond "this did not complete normally". The
+ * fail-closed fallback for a whole-message invariant no span redaction can repair. */
+export const MINIMAL_HOLD_MESSAGE = "mcpindex — local contract gate — this call did not complete normally. " +
+    "The structured error data carries the detail.";
+// Wire-level names an agent can EMIT. Deliberately NARROWER than "any word about trust":
+// the discriminator is whether a reader can ACT on the string. `list_tools` is a method the
+// agent can send on its next turn, and `Gate.observe()` TOFU-writes the pin store when it
+// does — so a HOLD carrying that word mints the very baseline the HOLD exists to withhold.
+const AGENT_UNSAFE_TOKENS = ["list_tools", "listtools", "tools/list"];
+// Match through `mdText` escaping: `list_tools` also matches `list\_tools`. A plain
+// substring scan is precisely why round 7's test passed while the string was LIVE.
+const AGENT_UNSAFE_RE = new RegExp(AGENT_UNSAFE_TOKENS.map((t) => [...t].map((ch) => `\\\\?${ch.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")}`).join("")).join("|"), "gi");
+// Bracketed affordance chips — `[Review · Re-pin · Validate]`, `[Override]`. UNESCAPED
+// brackets only: our curated prose is never routed through `mdText` so OUR chips are
+// literal `[`, while attacker values always are and arrive as `\[` — already neutralised,
+// and worth SHOWING as evidence of an attempted forgery. The allowlist is our own state
+// labels, which name nothing for the reader to do.
+const AGENT_SAFE_BRACKETS = ["redacted", "DRILL"];
+const CHIP_RE = new RegExp(`(?<!\\\\)\\[(?!(?:${AGENT_SAFE_BRACKETS.join("|")})\\])[^\\]\\n]{1,60}(?<!\\\\)\\]`, "g");
+/** The single boundary every agent-facing HOLD string crosses. REDACTS, never suppresses.
+ *
+ * Span-level, because the first cut returned a minimal message on any violation — which
+ * handed a hostile server a SUPPRESSION PRIMITIVE: name a tool `[Override]` and the whole
+ * detailed HOLD collapses to a sentence that says nothing. This module refuses that same
+ * trade for the pin anchor ("drop only the poisoned span, never the whole line").
+ * Python twin: `cse.gate.redact_agent_unsafe`. */
+export function redactAgentUnsafe(text) {
+    return text.replace(AGENT_UNSAFE_RE, "[redacted]").replace(CHIP_RE, "[redacted]");
+}
+/** WHOLE-MESSAGE invariants no span redaction can repair. Returns a reason, or null.
+ * Python twin: `cse.gate.agent_channel_violation`. */
+export function agentChannelViolation(verdict, text) {
+    const low = text.toLowerCase();
+    // The execution claim decides whether retrying is safe, so it must match the producer's
+    // fact in BOTH directions: a phantom side effect blocks a legitimate retry, and a missing
+    // real one invites a double-send.
+    const ran = low.includes("already ran") || low.includes("this call ran");
+    if (verdict.alreadyExecuted === true && !ran)
+        return "verdict says the call already ran; the message does not say so";
+    if (verdict.alreadyExecuted !== true && ran)
+        return "verdict says the call did not run; the message claims it did";
+    return null;
+}
+function assertNever(x) {
+    throw new Error(`unhandled hold class: ${String(x)}`);
+}
+/** Raw assembly, before the channel boundary. Exported for the suite, which must see our
+ * prose as written — handed the redacted output, a no-op assertion is vacuous. */
+export function assembleHoldMessage(verdict, sentKeys = null, pinPath = null, drill = false) {
+    // ONE dispatch, on the ONE fact the producer set — the port of the Python rewrite.
+    //
+    // This was a chain of ternaries and `else if`s over `isContractDiff`, `drift.length`,
+    // `isInternalErrorVerdict()` and two holdClass comparisons: a PRIORITY ORDER, not a set of
+    // mutually exclusive facts. It disagreed with the producer on three of six classes and the
+    // chain won — including a SELF-CONTRADICTION that a hostile server can trigger by dropping
+    // a pinned tool from tools/list (holdClass=uncheckable WITH drift rows), which rendered
+    // "the change was observed at the server" and "no contract comparison was possible" nine
+    // lines apart in one message. `assertNever` makes an unhandled class a compile error.
+    const holdClass = verdict.holdClass ?? HoldClass.UNSET;
+    const headline = drill
+        ? DRILL_HEADLINE
+        : holdClass === HoldClass.INTERNAL
+            ? INTERNAL_HEADLINE
+            : holdClass === HoldClass.WITHHELD
+                ? RESULT_HEADLINE
+                : "mcpindex — local contract gate — did not forward this call to the server.";
+    const lines = [headline, ""];
+    const rows = evidenceRows(verdict, sentKeys, drill);
+    const width = Math.max(...rows.map(([label]) => label.length));
+    for (const [label, value] of rows)
+        lines.push(`  ${label.padEnd(width)}   ${value}`);
+    if (drill) {
+        // Orthogonal to the class: a drill is a STAGED drift, so every claim below would
+        // describe a change that was never made.
+        lines.push("", DRILL_NOTE, "", DRILL_DISPOSITION_NOTE);
+    }
+    else {
+        switch (holdClass) {
+            case HoldClass.DRIFT:
+                // STALE_LIST_NOTE belongs HERE and only here — it asserts "the change was observed
+                // at the server", true on exactly this class. Keyed off `drift.length` instead, it
+                // rode along on uncheckable and finding holds.
+                lines.push("", STALE_LIST_NOTE, "", HONESTY_NOTE, "", DISPOSITION_NOTE);
+                break;
+            case HoldClass.WITHHELD:
+                lines.push("", RESULT_HONESTY_NOTE, "", RESULT_DISPOSITION_NOTE);
+                break;
+            case HoldClass.INTERNAL:
+                lines.push("", INTERNAL_NOTE, "", INTERNAL_DISPOSITION_NOTE);
+                break;
+            case HoldClass.APPROVAL:
+                lines.push("", APPROVAL_NOTE, "", APPROVAL_DISPOSITION_NOTE);
+                break;
+            case HoldClass.UNCHECKABLE:
+                lines.push("", UNCHECKABLE_NOTE, "", UNCHECKABLE_DISPOSITION_NOTE);
+                break;
+            case HoldClass.FINDING:
+                // A comparison RAN and something other than a diff fired.
+                lines.push("", FINDING_NOTE, "", FINDING_DISPOSITION_NOTE);
+                break;
+            case HoldClass.UNSET:
+                // A producer forgot. That is a bug in OUR code; say only what is true of every hold
+                // rather than guess a class — guessing is what the old "drift" default did.
+                return MINIMAL_HOLD_MESSAGE;
+            default:
+                return assertNever(holdClass);
+        }
+    }
+    if (verdict.decision === Decision.INCONCLUSIVE)
+        lines.push("", INCONCLUSIVE_NOTE);
+    if (pinPath) {
+        // The anti-forgery anchor: a remote server can emit any string, but it cannot put a
+        // file on the caller's disk or a binary on their PATH. `pinPath` is OURS.
+        // Port of the Python hardening: neutralise, collapse $HOME, and drop only the poisoned
+        // span if the path itself would carry banned reassurance - never the whole line, which
+        // would hand an attacker a way to suppress the anchor by naming their server.
+        // `stripControl` mirrors Python `_strip_unsafe`, which does NOT fold newlines - fold
+        // them here so a newline in `pinPath` cannot inject a forged evidence row. Then collapse
+        // $HOME, which the previous comment claimed and the code did not do: the absolute form
+        // leaks the OS username AND names the exact file a hostile server would poison.
+        const flat = stripControl(pinPath).replace(/[\r\n]+/g, " ");
+        const home = typeof process !== "undefined" ? (process.env.HOME ?? "") : "";
+        const safePin = home && flat.startsWith(`${home}/`) ? `~${flat.slice(home.length)}` : flat;
+        const anchor = redactGreenWords(safePin) === safePin
+            ? `the pin is a file at ${safePin}`
+            : "the pin is a file under ~/.mcpindex/pins/";
+        lines.push("", `Checkable locally: ${anchor}, and \`mcpindex-report\` prints the record. ` +
+            "A remote server can write neither.");
+    }
+    // No whole-output redaction: every attacker-derived span already went through `untrusted`.
+    // Re-running it over the join would corrupt our own curated prose while adding no defence.
+    return lines.join("\n");
+}
+export function renderHoldBanner(verdict, monthlyCount = null, chips = true) {
     const what = bannerWhatChanged(verdict);
     let line = `${BRAND_MARK} — caught a silent change: ${what}. Held before your agent ran it.`;
-    line += "  [Review · Re-pin · Validate]";
+    // See the Python twin: suppressed at the source for `data.presentation`, never by
+    // splitting the rendered string.
+    if (chips)
+        line += "  [Review · Re-pin · Validate]";
     if (monthlyCount !== null && monthlyCount > 0) {
         line += `   · ${ordinal(monthlyCount)} silent change caught for you this month`;
     }
@@ -274,7 +620,10 @@ export class Gate {
     decideContract(name, observed) {
         const pinned = this.pin.get(this._serverId, name);
         if (pinned === null) {
-            return this.holdOrFailopen(name, "no pin for this tool on this session; observe it via list_tools before relying on it");
+            return this.holdOrFailopen(name, 
+            // NO REMEDY IN THIS STRING - it is rendered verbatim to the agent, and `observe()`
+            // TOFU-writes the pin store. See the Python twin.
+            "no pin for this tool on this session; the contract has not been observed yet");
         }
         if (observed === null) {
             return this.holdOrFailopen(name, "tool is pinned but ABSENT from the contracts observed this session; cannot verify the live contract");
@@ -332,10 +681,10 @@ export class Gate {
                     marked = scanSchemaHasMarker(obj);
                 }
                 catch {
-                    return this.driftHold(pinned.toolName, [], "outputSchema present but the content scan could not complete; fail-closed HOLD");
+                    return this.driftHold(pinned.toolName, [], "outputSchema present but the content scan could not complete; fail-closed HOLD", "finding");
                 }
                 if (marked) {
-                    return this.driftHold(pinned.toolName, [], "an injection/exfil marker is present in the tool's outputSchema (an unhashed, agent-consumed channel)");
+                    return this.driftHold(pinned.toolName, [], "an injection/exfil marker is present in the tool's outputSchema (an unhashed, agent-consumed channel)", "finding");
                 }
             }
         }
@@ -359,7 +708,7 @@ export class Gate {
             drift = this.classifyDrift(pinned, observed);
         }
         catch {
-            return this.driftHold(name, [], "contract DRIFTED and validation could not complete; fail-closed HOLD");
+            return this.driftHold(name, [], "contract DRIFTED and validation could not complete; fail-closed HOLD", HoldClass.DRIFT);
         }
         // FIX 1 (fail-closed, H2): the canonical hash CHANGED (we only reach here on a hash
         // mismatch), yet the classifier produced NO change — UN-EXPLAINABLE drift (an
@@ -375,13 +724,13 @@ export class Gate {
                 safetyRelevant: true,
                 detail: "contract hash DRIFTED but no structured change could be classified (an unmodeled schema facet narrowed the contract); cannot prove benign",
             };
-            return this.driftHold(name, [synthetic], "contract hash DRIFTED but no structured change could be classified; cannot prove benign — fail-closed HOLD");
+            return this.driftHold(name, [synthetic], "contract hash DRIFTED but no structured change could be classified; cannot prove benign — fail-closed HOLD", "finding");
         }
         const mandated = drift.filter((c) => this.behavioralMandatedKinds.has(c.kind)).map((c) => c.kind.toString());
         if (!this.autoAcceptBenign) {
             if (mandated.length > 0)
                 return this.behavioralInconclusive(name, drift, mandated);
-            return this.driftHold(name, drift, "contract DRIFTED from your pin");
+            return this.driftHold(name, drift, "contract DRIFTED from your pin", HoldClass.DRIFT);
         }
         if (mandated.length > 0)
             return this.behavioralInconclusive(name, drift, mandated);
@@ -395,27 +744,27 @@ export class Gate {
         ].sort();
         if (nonAllowlisted.length > 0) {
             return this.driftHold(name, drift, "contract DRIFTED; not in the benign allowlist (added-optional-param / tool-added with no description change): " +
-                nonAllowlisted.join(", "));
+                nonAllowlisted.join(", "), HoldClass.DRIFT);
         }
         let escalation;
         try {
             escalation = this.riskEscalation(pinned, observed);
         }
         catch {
-            return this.driftHold(name, drift, "contract DRIFTED and the risk assessment could not complete; fail-closed HOLD");
+            return this.driftHold(name, drift, "contract DRIFTED and the risk assessment could not complete; fail-closed HOLD", HoldClass.DRIFT);
         }
         if (escalation !== null) {
-            return this.driftHold(name, drift, "contract DRIFTED; risk ESCALATED on an otherwise-allowlisted change: " + escalation);
+            return this.driftHold(name, drift, "contract DRIFTED; risk ESCALATED on an otherwise-allowlisted change: " + escalation, HoldClass.DRIFT);
         }
         let hasMarker;
         try {
             hasMarker = this.markerIn(observed);
         }
         catch {
-            return this.driftHold(name, drift, "contract DRIFTED and the content scan could not complete; fail-closed HOLD");
+            return this.driftHold(name, drift, "contract DRIFTED and the content scan could not complete; fail-closed HOLD", HoldClass.DRIFT);
         }
         if (hasMarker) {
-            return this.driftHold(name, drift, "contract DRIFTED; an injection/exfil marker is present in the new definition (input schema or description)");
+            return this.driftHold(name, drift, "contract DRIFTED; an injection/exfil marker is present in the new definition (input schema or description)", HoldClass.DRIFT);
         }
         this.repinOne(name, observed);
         return makeVerdict({
@@ -476,14 +825,25 @@ export class Gate {
             serverId: this._serverId,
             toolName: name,
             decision: Decision.HOLD,
-            reason: "contract DRIFTED: the tool DESCRIPTION changed (the agent-consumed, attacker-controllable channel); review the before/after and re-pin if expected",
+            // APPEND, never rewrite: DANGEROUS_REASON_MARKERS matches the substring
+            // "DESCRIPTION changed", so rewording would silently stop GUARD blocking.
+            reason: "contract DRIFTED: the tool DESCRIPTION changed (the agent-consumed, attacker-controllable channel); review the before/after and re-pin if expected" +
+                (isNumericOnlyDescriptionChange(oldDesc, newDesc)
+                    ? "; only the embedded numbers moved, the prose is identical"
+                    : ""),
             drift,
+            holdClass: HoldClass.DRIFT, // description-poisoning: a comparison found a difference
             descBefore: oldDesc,
             descAfter: newDesc,
         });
     }
-    driftHold(name, drift, reason) {
-        return makeVerdict({ serverId: this._serverId, toolName: name, decision: Decision.HOLD, reason, drift });
+    driftHold(name, drift, reason, 
+    // REQUIRED, no default. The claim in the comment this replaces — "every CALLER states
+    // it" — was FALSE: `tsc` names 6 callers that inherited it silently, the same 10 that
+    // mypy surfaced in the Python twin. A defaulted parameter on a helper reintroduces at
+    // the call site exactly what removing the field default fixed at the constructor.
+    holdClass) {
+        return makeVerdict({ serverId: this._serverId, toolName: name, decision: Decision.HOLD, reason, drift, holdClass });
     }
     behavioralInconclusive(name, drift, mandatedKinds) {
         const kinds = [...new Set(mandatedKinds)].sort().join(", ");
@@ -493,6 +853,7 @@ export class Gate {
             decision: Decision.INCONCLUSIVE,
             reason: `contract DRIFTED in a class the declared contract cannot clear or condemn (${kinds}); behavioral validation needed before use`,
             drift,
+            holdClass: HoldClass.DRIFT, // a comparison found a difference; behaviour must adjudicate
         });
     }
     holdOrFailopen(name, reason) {
@@ -504,6 +865,7 @@ export class Gate {
                 reason,
                 failOpenWarning: true,
                 isContractDiff: false,
+                holdClass: HoldClass.UNCHECKABLE, // no comparison was possible
             });
         }
         return makeVerdict({
@@ -512,6 +874,7 @@ export class Gate {
             decision: Decision.HOLD,
             reason,
             isContractDiff: false,
+            holdClass: HoldClass.UNCHECKABLE, // no comparison was possible
         });
     }
     // ------------------------------------------------------------- posture layer
@@ -606,7 +969,7 @@ export class Gate {
         }
         if (observed === null) {
             return [
-                this.holdOrFailopen(toolName, "no observed contract to behaviorally validate; list_tools before validating"),
+                this.holdOrFailopen(toolName, "no observed contract to behaviorally validate; no baseline to validate against"),
                 null,
             ];
         }
@@ -651,7 +1014,7 @@ export class Gate {
         const reason = result.outcome === BehavioralOutcome.FAILED
             ? `behavioral validation FAILED (${suffix})`
             : `behavioral validation UNAVAILABLE (${suffix}); stay HOLD`;
-        return [this.driftHold(toolName, [...staticVerdict.drift], reason), result.outcome];
+        return [this.driftHold(toolName, [...staticVerdict.drift], reason, HoldClass.DRIFT), result.outcome];
     }
 }
 export { isSafetyRelevant, DEFAULT_BEHAVIORAL_MANDATED_KINDS };