@mutmutco/claude-plugin 3.131.0

package/scripts/secret-redact.mjs

@@ -0,0 +1,552 @@
+// Claude PostToolUse secret redaction (#1589). No throttling, no compaction; fail-soft always.
+// Patterns are self-contained here (conservative, prefix-anchored secret shapes).
+
+import { appendHookActivity } from './hook-trace.mjs';
+
+export const REDACTED = '[REDACTED]';
+
+// #2967 asked for redaction to be VISIBLY redaction: a bare `[REDACTED]` can read as a legitimate
+// rendering of the file, which is how #2967 happened — the agent could not tell the text it was shown
+// was not verbatim, used it as an Edit old_string, and the edit failed. So every match is replaced with
+// `[REDACTED](secret)`, a superset of REDACTED (`x.includes(REDACTED)` still holds, so nothing that
+// already checks "was anything redacted" breaks).
+//
+// The marker names the MECHANISM, never the provider. A per-pattern label (`[REDACTED](aws-key)`)
+// leaks classification metadata about a value we just decided was too sensitive to show: it tells a
+// reader which provider to target and lets an attacker tune a bypass pattern-by-pattern. That argument
+// still stands and per-provider labels stay refused.
+//
+// #3296 refines it to TWO levels, which the per-provider argument does not cover. There is a real
+// difference between "this matched an anchored credential shape" and "this matched a generic 40-char
+// blob", and collapsing them has its own security cost: when an agent repeatedly sees `(secret)` on
+// things it knows are not secrets — worktree paths, schedule names, its own help text — the marker
+// stops being a trustworthy signal, and routing around it becomes a habit. That habit is exactly what
+// you do not want the day a real credential appears.
+//
+// Two levels leak almost nothing (the patterns are committed source; an attacker reads them directly)
+// and repair that trust erosion. Both mask IDENTICALLY — same fail-closed posture, same bytes removed.
+// The label describes WHAT MATCHED, never HOW MUCH TO WORRY: no "low confidence", no "probably public".
+// A confidence grade would teach the agent to discount the backstop, which is the failure mode above
+// wearing a different hat.
+const REDACTION_MARKER = `${REDACTED}(secret)`;
+// Shape-only matches: the high-entropy blob and bare-hex heuristics. No provider was identified — the
+// text merely has credential-like SHAPE. Still fully masked; the reader just learns not to conclude a
+// credential was detected.
+const SHAPE_MARKER = `${REDACTED}(token-shape)`;
+
+// #3121 cheap pre-filter: skip full regex machinery for small payloads that contain none of the
+// candidate secret-pattern markers. Conservative: when in doubt (any marker found, or payload
+// exceeds the budget) the full scan runs. Coverage must never shrink.
+//
+// Pre-filter surface is JSON.stringify(input) — same recursive surface the full scanner visits.
+// Every pattern family from PATTERNS + SECRET_ASSIGNMENT is represented:
+//   PEM (-----BEGIN), JWT (eyJ), AWS (AKIA etc.), GitHub (ghp_ etc., github_pat_), Stripe/OpenAI
+//   (sk-, sk_live_, sk_test_, pk_live_, pk_test_), NPM (npm_), Slack (xox, xapp, hooks.slack.com),
+//   Discord (discord), Google (AIza, GOCSPX), URL creds (://), Bearer/Basic (case-insensitive),
+//   high-entropy blob / hex (32+ [A-Za-z0-9_-] run), secret-assignment key words (case-insensitive).
+const PRE_FILTER_BUDGET = 1024;
+
+const CANDIDATE_PREFIXES = [
+  '-----BEGIN',
+  'eyJ',
+  'AKIA', 'ASIA', 'AGPA', 'AROA', 'AIDA', 'ANPA', 'ANVA', 'AIPA',
+  'ghp_', 'gho_', 'ghu_', 'ghs_', 'ghr_',
+  'github_pat_',
+  'sk-', 'sk_live_', 'sk_test_',
+  'pk_live_', 'pk_test_',
+  'npm_',
+  'xox', 'xapp',
+  'AIza',
+  'GOCSPX',
+  'hooks.slack.com',
+  'discord',
+  '://',
+];
+
+// Plain SUBSTRING keywords, deliberately NOT \b-anchored: underscore is a word character, so
+// \bsecret\b never matches STRIPE_SECRET — the exact head-noun shape SECRET_ASSIGNMENT redacts.
+// Substring matching over-triggers (more full scans); that is the conservative direction here.
+const CI_KEYWORDS = [
+  'bearer', 'basic', 'apikey', 'api_key', 'api-key',
+  'appkey', 'app_key', 'app-key',
+  'applicationkey', 'application_key', 'application-key',
+  'secret', 'token',
+  'password', 'passwd', 'passphrase', 'credential', 'accesskey', 'access_key', 'access-key',
+  'privatekey', 'private_key', 'private-key',
+];
+const hasCiKeyword = (raw) => {
+  const lower = raw.toLowerCase();
+  return CI_KEYWORDS.some((k) => lower.includes(k));
+};
+
+// Char class must be a superset of ENTROPY_BLOB_RE's ([A-Za-z0-9+/\-_]): a slash/plus-bearing blob
+// (e.g. an AWS secret access key) splits into sub-32 runs under a narrower class and slips the filter.
+const ENTROPY_PREFILTER_RE = /[A-Za-z0-9+/_-]{32,}/;
+
+// Tools whose output the harness lets a PostToolUse hook REPLACE via a structured
+// updatedToolOutput. Read/Edit/Write/WebFetch/Task/Agent/mcp__* are NOT replaceable.
+const UPDATABLE_TOOLS = new Set(['Bash', 'PowerShell', 'Shell', 'Grep', 'Glob']);
+
+// Multi-line PEM/private-key block. Kept as a named const so it can be applied to the
+// WHOLE text before chunking — a private key can span more than one chunk, and chunk-local
+// scanning would split the BEGIN..END span and miss it (#2821 chunk-boundary defect).
+const PRIVATE_KEY_RE =
+  /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g;
+const PRIVATE_KEY_REPLACEMENT = '[REDACTED PRIVATE KEY]';
+
+// High-entropy catch-all. Its two forward `.*` lookaheads are O(n^2) worst-case and it matches
+// UNBOUNDED-length runs, so — unlike every other pattern — it is NOT safe to run across the whole
+// text; it stays inside the budgeted per-chunk loop. A boundary split of an unbounded heuristic
+// blob in dense whitespace-free content is the one documented residual (bounded, anchored
+// credential shapes are all handled whole-text and can never be split by a chunk edge).
+//
+// #2942: the char class contains `/`, `\-` and `_`, so a long slash-joined PATH or URL tail matched as one
+// "high-entropy blob" and was masked: `https://github.com/mutmutco/MMI-Hub/actions/runs/…` came back as
+// `https://github.[REDACTED]`, and worktree/temp paths were destroyed outright. A path is not a credential.
+//
+// The fix is CONTEXTUAL, not a narrower char class. Dropping `/` from the class would stop matching an AWS
+// secret access key (`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` — 40 chars, two slashes), and an entropy
+// threshold would stop matching the pinned 40-char `XXX…yyy` fixture (1.0 bits/char). Both are true
+// positives we must keep. What actually separates them is the surrounding text: a matched blob that is a
+// SLICE of a longer path or URL is glued to a path separator, while a credential sits on a word boundary.
+//
+// #3299 — KNOWN, ACCEPTED BYPASS. Read this before touching anything below.
+//
+// This exemption is inferred from attacker-influenced printable text, so anyone who can shape what a
+// command prints can satisfy it. One adjacent character is enough. Reproduced against the AWS-published
+// example secret access key:
+//
+//   bare                       masked
+//   leading slash              LEAKED
+//   leading dot                LEAKED
+//   leading backslash          LEAKED
+//   in a sentence              masked
+//   sentence, slash-prefixed   LEAKED
+//   trailing slash             LEAKED
+//
+// BOTH arms are reachable — a trailing separator leaks exactly like a leading one.
+//
+// It reaches a real credential because the AWS SECRET ACCESS KEY has no anchored pattern of its own: the
+// `AKIA|ASIA|…` family matches key IDs, not secret keys. This heuristic is its only cover, and this
+// exemption is what disables it.
+//
+// It is NOT fixed, by owner decision, because every available fix is worse:
+//   - deleting the exemption resurrects #2942 wholesale (URLs, worktree paths, Actions run URLs all
+//     destroyed again) — a shipped functional regression, not a hypothetical;
+//   - widening the lookback to tolerate spaces enlarges the hole, since a forged path-shaped prefix is
+//     as easy to print as a real one;
+//   - a generic 40-char base64 "AWS" pattern over-matches catastrophically.
+//
+// So: treat the entropy heuristic as a BACKSTOP, never as primary defence, and do not build new
+// protection on top of it. `infra/secret-redact.test.mjs` pins this behaviour deliberately — if one of
+// those tests starts failing, someone has changed the exemption and must revisit #3299, not "fix" the
+// test.
+//
+// Second defect, also unfixed and deliberately so: in the chunked pass this function receives the CHUNK,
+// not the whole text, so at a chunk edge it inspects characters that are not the real neighbours — the
+// same input can mask or not depending on size. It is NOT safe to fix in isolation: supplying the real
+// neighbours would ACTIVATE the exemption where it currently misses, masking LESS rather than more.
+// It must be fixed together with whatever finally settles the path policy.
+//
+// #3469 / #3338 — A PATH CONTAINING A SPACE HAS ITS TAIL MASKED. THAT IS THE ACCEPTED OUTCOME.
+// Do not re-attempt the exemption; this is the third time it has been proposed.
+//
+// A space is not in the char class, so a spaced path splits into separate runs and the TAIL run is no
+// longer glued to a recognisable prefix — it matches as a bare token. Every path this org uses contains a
+// space (`E:\AI Projects\…`, `E:\Jerv's Vault\`, `E:\Cold Storage\`, `C:\Program Files\`), so on
+// forward-slash output it fires constantly: `git worktree list` renders as
+// `E:/AI Projects/Mutatis [REDACTED](token-shape)  1d4c2aab [3240-clock-fp]`.
+//
+// The obvious fix — look BACKWARDS across whitespace and suppress when the run is preceded on the same
+// line by a rooted path anchor (`X:\`, `X:/`, `//`, `./`, `~/`) — was BUILT as PR #3373 and closed
+// unmerged. Cross-vendor security review (GPT-5.6 Sol) blocked it twice, because a rooted path followed
+// by one space and a slash-bearing token is STRUCTURALLY IDENTICAL to a real spaced path:
+//
+//   E:/AI Projects/Mutatis ‹Mutandis/mmi-worktrees/3469-…›   one path; the space is inside a dir name
+//   E:/logs/archive        ‹wJalrXUtnFEMI/K7MDENG/bPxRfi…›   a path, then a separate credential field
+//
+// Every knob on that lookback was measured, including narrowings PR #3373 did not have (single-space gaps
+// only, so column-aligned output cannot exempt the next column; `:` excluded from the segment charset, so
+// `file:line:` and `KEY=value` shapes break the span). Bounding the lookback to ONE gap defeats Sol's
+// first counterexample (`E:/logs/archive contains leak <key>` — prose rides in as the final segment) but
+// then no longer fixes `git worktree list` at all, because that path needs two gaps to reach its root. At
+// two gaps the path survives and the second counterexample leaks. There is no setting of the knob where
+// the path survives and the credential masks.
+//
+// That second leak is why this is BIGGER than the #3299 bypass above, not the same size: #3299 needs an
+// attacker to place one character next to the secret, whereas plain `<rooted-path> <value>` on one line is
+// ORDINARY tool output. The exemption would stop masking accidental leaks with no attacker present.
+//
+// OWNER RULING 2026-07-22 (#3338 closed, PR #3373 closed unmerged): fix the PATH EMITTERS, leave the
+// backstop untouched. `cli/src/gc.ts` `toNativePath()` converts git's forward slashes to native separators
+// on Windows at the emission boundary. `\` is outside the char class, so runs BREAK at every separator —
+// but that alone does not make a native path safe: a single directory name of 40+ mixed-case chars still
+// forms a run on its own (`E:\src\ThisIsAVeryLongCamelCaseDirectoryName123\index.ts` does, verified). What
+// actually exempts it is the `before === '\\'` arm below — any run that does form inside a native path is
+// preceded by a separator. Reason from that, not from "a native path can never form a run", or you will
+// reason from a false invariant. Where the emitter is not ours (raw `git worktree list` through Bash),
+// the mask is the accepted cost — read the path via `mmi-cli worktree list --json`, which emits native
+// separators. `infra/secret-redact.test.mjs` pins BOTH directions — the accepted mask AND Sol's two
+// counterexamples — so a fourth attempt fails a test instead of shipping.
+export function isPathContext(text, start, end) {
+  const before = text[start - 1] ?? '';
+  const after = text[end] ?? '';
+  // Preceded by `/`, `\` or `.` → we are mid-path or mid-URL (`github.` + `com/mutmutco/…`).
+  if (before === '/' || before === '\\' || before === '.') return true;
+  // Followed by a separator → the blob continues into more path.
+  if (after === '/' || after === '\\') return true;
+  return false;
+}
+
+// ACCEPTED OVER-REDACTION, deliberately not "fixed" (#2966 security review — do not undo this):
+// the char class also matches a long bare camelCase FILENAME with no path separator to anchor it
+// (`SomeVeryLongCamelCaseModuleFileNameWithoutSlashes.md`), so such a name is masked. That is the safe
+// failure mode and it stays. Two exculpation schemes were built here and both were rejected on review:
+//   - exempting a blob followed by `.` + a letter ("it's a file extension") is a secret-smuggling BYPASS:
+//     append `.txt` to any secret and it walks through (`leak AbCdEf…789abcd.txt`);
+//   - exempting word-structured, low-entropy tokens is ALSO a bypass, because passphrase, diceware and
+//     BIP39 mnemonic credentials are word-structured BY DESIGN:
+//     `credential: correct-Horse-battery-staple-planet-museum-lantern.md` passes any such gate.
+// Content-based innocence cannot be proven from the token itself. Over-redacting a rare long filename
+// costs one Read; an attacker-controlled exemption costs a credential. Fail closed.
+// #3296: the case-diversity lookaheads are TOKEN-SCOPED. They were `(?=.*[a-z])(?=.*[A-Z])`, and `.`
+// stops only at a newline, so the requirement could be satisfied by text later on the same LINE,
+// outside the token — and because the entropy pass runs per-chunk, by where the input happened to be
+// split. That is not the rule the comment above describes.
+//
+// The cross-vendor security review challenged this, arguing a 40-char one-case hex credential (Datadog
+// app key shape) loses its only cover, since the bare-hex fallback starts at 48. Measured against both
+// regex forms directly, that objection does not hold — the lookaheads scan FORWARD from the match
+// start, so an uppercase key NAME sitting before the value never satisfied them:
+//
+//   DATADOG_APP_KEY=<40 hex>        loose: NOT matched    scoped: NOT matched
+//   export DATADOG_APP_KEY=<40 hex> loose: NOT matched    scoped: NOT matched
+//   <40 hex> SOME TRAILING TEXT     loose: matched        scoped: NOT matched
+//   commit <git sha> Merge PR       loose: matched        scoped: NOT matched
+//
+// So the loose form never covered the realistic assignment shape. It only fired when uppercase happened
+// to FOLLOW the token — and in that case it also masked git SHA-1s in ordinary `git log` output, which
+// is one of the false positives #3296 was filed about. The looseness bought coincidence, not coverage.
+//
+// The genuine gap it exposed — a one-case 40-char credential has no cover under EITHER form — is real
+// and was pre-existing. It cannot be closed by lowering the bare-hex threshold to 40, because 40 hex
+// chars is exactly a git SHA-1 and every commit hash in every log would be masked. Closed as #3300 by
+// widening SECRET_ASSIGNMENT's name list (APP_KEY / APPLICATION_KEY — a NAME is not the value's
+// content, so it does not reopen #2966), not by loosening anything here.
+const ENTROPY_BLOB_RE =
+  /\b(?=[A-Za-z0-9+/\-_]{40,})(?=[A-Za-z0-9+/\-_]*[a-z])(?=[A-Za-z0-9+/\-_]*[A-Z])[A-Za-z0-9+/\-_]{40,}\b/g;
+const ENTROPY_HEURISTIC = {
+  re: ENTROPY_BLOB_RE,
+  replace: (match, offset, whole) =>
+    (isPathContext(whole, offset, offset + match.length) ? match : SHAPE_MARKER),
+};
+
+const PATTERNS = [
+  { re: PRIVATE_KEY_RE, replace: PRIVATE_KEY_REPLACEMENT },
+  { re: /\b([a-z][a-z0-9+.\-]*:\/\/[^\s:@\/]+):[^\s:@\/]+@/gi, replace: `$1:${REDACTION_MARKER}@` },
+  { re: /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/\-]+=*/gi, replace: `$1 ${REDACTION_MARKER}` },
+  { re: /\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\b/g, replace: REDACTION_MARKER },
+  { re: /\b(?:AKIA|ASIA|AGPA|AROA|AIDA|ANPA|ANVA|AIPA)[0-9A-Z]{16}\b/g, replace: REDACTION_MARKER },
+  { re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, replace: REDACTION_MARKER },
+  { re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, replace: REDACTION_MARKER },
+  { re: /\bAIza[0-9A-Za-z_\-]{35}\b/g, replace: REDACTION_MARKER },
+  { re: /\bGOCSPX-[A-Za-z0-9_\-]{20,}\b/g, replace: REDACTION_MARKER },
+  { re: /\bsk-[A-Za-z0-9_\-]{20,}\b/g, replace: REDACTION_MARKER },
+  { re: /\bsk_(?:live|test)_[A-Za-z0-9]{16,}\b/g, replace: REDACTION_MARKER },
+  { re: /\bpk_(?:live|test)_[A-Za-z0-9]{16,}\b/g, replace: REDACTION_MARKER },
+  { re: /\bnpm_[A-Za-z0-9]{36}\b/g, replace: REDACTION_MARKER },
+  { re: /\b(?:xox[baprs]|xapp)-[A-Za-z0-9-]{10,}\b/g, replace: REDACTION_MARKER },
+  {
+    re: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/gi,
+    replace: REDACTION_MARKER,
+  },
+  {
+    re: /https:\/\/discord(?:app)?\.com\/api\/webhooks\/\d+\/[A-Za-z0-9_\-]+/gi,
+    replace: REDACTION_MARKER,
+  },
+  ENTROPY_HEURISTIC,
+  // Shape-only, like the entropy blob: a long bare hex run names no provider (#3296).
+  { re: /\b[a-fA-F0-9]{48,}\b/g, replace: SHAPE_MARKER },
+];
+
+// Every pattern EXCEPT the high-entropy heuristic is linear and matches a bounded, anchored shape,
+// so it is cheap and correct to apply across the whole text — a chunk edge can never split it.
+const WHOLE_TEXT_PATTERNS = PATTERNS.filter((p) => p !== ENTROPY_HEURISTIC);
+
+const SECRET_ASSIGNMENT =
+  /\b([A-Za-z0-9_]*(?:API[_-]?KEY|APPLICATION[_-]?KEY|APP[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PASSPHRASE|PRIVATE[_-]?KEY|CLIENT[_-]?SECRET|ACCESS[_-]?KEY|CREDENTIALS?)[A-Za-z0-9_]*)(\s*["']?\s*[=:]\s*)("[^"\n]{4,}"|'[^'\n]{4,}'|[^\s"']{4,})/gi;
+
+// #2942: the NAME group above only requires the secret word to appear as a SUBSTRING, so an ordinary
+// camelCase identifier matched it — `const tokenBefore = "..."` had its value blanked in Grep/Bash output
+// of plain source code. (Worse: the redactor rewrites shell/Grep output but NOT Read/Edit, so an Edit
+// old_string copied from redacted Grep output could not match the real bytes on disk.)
+//
+// A name is a secret name when the secret word is the HEAD NOUN — what the thing IS — not merely a prefix:
+//   accessToken, api_key, GITHUB_TOKEN, client_secret, SECRET_KEY, AWS_SECRET_ACCESS_KEY,
+//   DATADOG_APP_KEY, appKey, APPLICATION_KEY                                              → yes
+//   tokenBefore, tokenExpiry, tokenizer, sortKey, foreignKey, publicKey, projectKey       → no
+// So: split the name into word parts (camelCase, snake_case, kebab-case all normalise the same way) and
+// test the TRAILING one or two parts against the term list. This keeps every real config/env shape,
+// including lowercase JSON/YAML keys, which an UPPER_SNAKE-only rule would have dropped.
+//
+// #3300: APP_KEY / APPLICATION_KEY are credential head nouns (Datadog app keys, etc.). Bare KEY and
+// arbitrary *KEY (sortKey, publicKey, …) stay refused — that recreates the #2942 tokenBefore class.
+const SECRET_NAME_TERMS = new Set([
+  'apikey', 'appkey', 'applicationkey', 'secret', 'secretkey', 'token', 'password', 'passwd',
+  'passphrase', 'privatekey', 'clientsecret', 'accesskey', 'credential', 'credentials',
+]);
+
+/** Split an identifier into lowercase word parts: `AWS_SECRET_ACCESS_KEY` / `accessToken` / `api-key`. */
+export function splitNameParts(name) {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[\s_\-]+/)
+    .filter(Boolean)
+    .map((p) => p.toLowerCase());
+}
+
+/** True when the secret word is the head noun of `name` (see SECRET_NAME_TERMS above). */
+export function isSecretAssignmentName(name) {
+  const parts = splitNameParts(name);
+  if (!parts.length) return false;
+  // The trailing part, or the trailing two joined (`access`+`key` → `accesskey`, `api`+`key` → `apikey`).
+  return SECRET_NAME_TERMS.has(parts[parts.length - 1])
+    || (parts.length >= 2 && SECRET_NAME_TERMS.has(parts.slice(-2).join('')));
+}
+
+/** Apply a list of {re, replace} patterns to text, in order. */
+function applyPatterns(text, patterns) {
+  let out = text;
+  for (const { re, replace } of patterns) out = out.replace(re, replace);
+  return out;
+}
+
+/** Redact secret assignments (NAME = "value") — value replaced, name/sep kept. A name whose secret word is
+ *  only a prefix (`tokenBefore`) is left ALONE: it is ordinary source code, not a credential (#2942). */
+function redactAssignments(text) {
+  return text.replace(SECRET_ASSIGNMENT, (match, name, sep) =>
+    (isSecretAssignmentName(name) ? `${name}${sep}${REDACTION_MARKER}` : match));
+}
+
+// Large tool outputs are scanned in chunks under a per-call time budget. Anything
+// past the budget is truncated and flagged with a visible warning — never silently
+// skipped, since skipping large output is itself an exfil path. #2597
+const CHUNK_SIZE = 64 * 1024;       // 64 KB per chunk
+const CHUNK_OVERLAP = 1024; // when chunking the high-entropy pass, prefer to cut at a whitespace
+                            // boundary within this window so a dense run is less likely to split
+const SCAN_BUDGET_MS = 3000;        // per-call wall-clock budget (hook timeout is 5s)
+export const TRUNCATION_WARNING =
+  '[mmi-hook] WARNING: tool output exceeded the secret-redaction scan time budget; ' +
+  'the unscanned remainder was truncated to avoid passing unredacted content to model ' +
+  'context. Inspect the source tool output directly for possible secrets.';
+
+/** Apply ALL redaction patterns to a single chunk (used for small inputs scanned in one pass). */
+function redactChunk(text) {
+  return redactAssignments(applyPatterns(text, PATTERNS));
+}
+
+/** Strip secret-shaped substrings from tool output before it enters model context.
+ *  Small inputs are scanned in one whole pass. Large inputs are handled in two stages so a
+ *  secret can never be split by a chunk boundary: (1) every bounded/anchored pattern (incl.
+ *  multi-line PEM) plus secret assignments runs across the WHOLE text — these are linear and
+ *  cannot be split; (2) only the O(n^2), unbounded-length high-entropy heuristic is scanned in
+ *  chunks under a per-call time budget, and any unscanned tail is truncated with a visible
+ *  warning so it can never pass through silently (#2597, #2821). */
+export function redactSecrets(text, opts = {}) {
+  if (typeof text !== 'string') text = String(text ?? '');
+  const chunkSize = opts.chunkSize ?? CHUNK_SIZE;
+  const budgetMs = opts.budgetMs ?? SCAN_BUDGET_MS;
+  const overlap = Math.min(opts.overlap ?? CHUNK_OVERLAP, chunkSize);
+  if (text.length <= chunkSize) return redactChunk(text);
+
+  // Stage 1 — boundary-free whole-text pass for every bounded/anchored pattern + assignments.
+  // A chunk edge can never split any of these, so dense whitespace-free tokens (AKIA, gh*, JWT,
+  // hex, PEM, …) are caught regardless of where they fall (#2821 chunk-boundary defect).
+  text = redactAssignments(applyPatterns(text, WHOLE_TEXT_PATTERNS));
+
+  // Stage 2 — only the high-entropy heuristic remains; scan it in chunks under the time budget.
+  const start = Date.now();
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    let end = Math.min(i + chunkSize, text.length);
+    if (end < text.length) {
+      // prefer a whitespace cut within the overlap window so a dense run is less likely to split
+      const floor = Math.max(i + 1, end - overlap);
+      let sp = end;
+      while (sp > floor && !/\s/.test(text[sp - 1])) sp--;
+      if (sp > floor) end = sp;
+    }
+    out += text.slice(i, end).replace(ENTROPY_HEURISTIC.re, ENTROPY_HEURISTIC.replace);
+    i = end;
+    if (i < text.length && Date.now() - start >= budgetMs) {
+      out += `\n${TRUNCATION_WARNING}`;
+      break;
+    }
+  }
+  return out;
+}
+
+/** Deep-redact every string field of a tool response, preserving structure and
+ *  non-string fields. Scans stdout AND stderr AND text/content — no field skipped,
+ *  and an empty stdout no longer short-circuits the scan. */
+export function redactToolResponse(resp) {
+  if (typeof resp === 'string') return redactSecrets(resp);
+  if (Array.isArray(resp)) return resp.map(redactToolResponse);
+  if (resp && typeof resp === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(resp)) out[k] = redactToolResponse(v);
+    return out;
+  }
+  return resp;
+}
+
+export function toolResponseToString(resp) {
+  if (resp == null) return '';
+  if (typeof resp === 'string') return resp;
+  if (typeof resp === 'object') {
+    const parts = [];
+    if (typeof resp.text === 'string') parts.push(resp.text);
+    if (typeof resp.content === 'string') parts.push(resp.content);
+    if (typeof resp.stdout === 'string') parts.push(resp.stdout);
+    if (typeof resp.stderr === 'string') parts.push(resp.stderr);
+    if (Array.isArray(resp.content)) {
+      const fromArray = resp.content
+        .map((b) => (typeof b === 'string' ? b : typeof b?.text === 'string' ? b.text : ''))
+        .filter(Boolean)
+        .join('\n');
+      if (fromArray) parts.push(fromArray);
+    }
+    if (parts.length) return parts.join('\n');
+    try {
+      return JSON.stringify(resp);
+    } catch {
+      return String(resp);
+    }
+  }
+  return String(resp);
+}
+
+/** @returns {null | { hookSpecificOutput: object|null, redactable: boolean, toolName: string }} */
+export function postToolUseRedactDecision(input) {
+  const resp = input?.tool_response;
+  if (resp == null) return null;
+  const redacted = redactToolResponse(resp);
+  if (JSON.stringify(redacted) === JSON.stringify(resp)) return null; // clean
+  const toolName = typeof input?.tool_name === 'string' ? input.tool_name : '';
+  if (UPDATABLE_TOOLS.has(toolName)) {
+    return {
+      toolName,
+      redactable: true,
+      hookSpecificOutput: { hookEventName: 'PostToolUse', updatedToolOutput: redacted },
+    };
+  }
+  return { toolName, redactable: false, hookSpecificOutput: null };
+}
+
+/** The tool name the HOST actually fired, for the trace. hook-run.mjs rewrites a host's shell spelling
+ *  into the Claude vocabulary UPDATABLE_TOOLS is written in (#4118) and stamps the original beside it;
+ *  logging the rewritten name recorded Codex `shell` and `local_shell` as identical "PowerShell" rows. */
+function tracedTool(input) {
+  return typeof input?.mmi_host_tool_name === 'string' ? input.mmi_host_tool_name : input?.tool_name;
+}
+
+/** Shared entry (#4118): awaitable and exit-free so hook-run.mjs can import it in-process instead of
+ *  booting a second node. `input` is the buffered payload when the runner already drained stdin. */
+export async function runHookGate({ input: buffered } = {}) {
+  let input;
+  try {
+    const { readHookInput } = await import('./hook-io.mjs');
+    input = await readHookInput(buffered);
+  } catch {
+    appendHookActivity({
+      event: 'PostToolUse',
+      script: 'secret-redact',
+      outcome: 'failed',
+      action: 'could not read hook input',
+    });
+    return;
+  }
+
+  const raw = JSON.stringify(input);
+  if (raw.length <= PRE_FILTER_BUDGET && !CANDIDATE_PREFIXES.some((p) => raw.includes(p)) && !hasCiKeyword(raw) && !ENTROPY_PREFILTER_RE.test(raw)) {
+    appendHookActivity({
+      event: 'PostToolUse',
+      script: 'secret-redact',
+      outcome: 'ran',
+      action: 'clean (pre-filter)',
+      tool: tracedTool(input),
+    });
+    return;
+  }
+
+  try {
+    const decision = postToolUseRedactDecision(input);
+    // #3563/#3920: `updatedToolOutput` is a Claude Code capability. Codex's PostToolUse contract supports
+    // `{decision, reason}` only, Kimi is observation-only, and Cursor can replace MCP output only, so
+    // on those hosts the rewrite is DROPPED and ordinary tool output stays visible. Emitting it there
+    // and logging `heal` recorded a masking that never happened — false assurance in the one place a
+    // leak would be audited from (cross-vendor check, openai-sol, kimi-k3).
+    const canRewriteOutput = !['codex', 'kimi', 'cursor'].includes(process.env.MMI_HOOK_SURFACE || 'claude');
+    if (decision?.hookSpecificOutput && canRewriteOutput) {
+      process.stdout.write(`${JSON.stringify({ hookSpecificOutput: decision.hookSpecificOutput })}\n`);
+    }
+    const healed = Boolean(decision?.redactable) && canRewriteOutput;
+    const outcome = !decision ? 'ran' : healed ? 'heal' : 'observe';
+    // #4015/#4021: every operator- and log-facing string names the tool the HOST fired, never
+    // `decision.toolName` — that one is the name hook-run.mjs rewrote into the Claude vocabulary so it can
+    // be tested against UPDATABLE_TOOLS, and it collapsed Codex `shell` and `local_shell` into "PowerShell".
+    // #4012 fixed this call's `tool` FIELD and #4015 the stderr arms; the `action` TEXT below was converted
+    // by neither, so one row read `{"tool":"shell","action":"secret detected in PowerShell output …"}` and
+    // disagreed with itself — in the log doctor, the Stop summary and Archive/scrooge.md's detection counts read.
+    const alarmTool = tracedTool(input) || decision?.toolName || 'tool';
+    const action = !decision
+      ? 'clean'
+      : healed
+        ? 'redacted secrets from tool output'
+        : decision.redactable
+          ? `secret detected in ${alarmTool} output and NOT masked — this host cannot rewrite tool output (no updatedToolOutput channel on this surface)`
+          : `secret detected in ${alarmTool} output but PostToolUse cannot redact this tool (harness limitation)`;
+    // Detection without masking must be audible, not just logged: on Codex the value is still on screen.
+    if (decision?.redactable && !canRewriteOutput) {
+      process.stderr.write(`[mmi-hook] secret-redact: a secret-shaped value was detected in ${alarmTool} output and could NOT be masked on this host — treat the transcript as exposed.\n`);
+    }
+    // #3630: same audibility for the non-redactable-TOOL arm. A detection in Read/WebFetch/Agent/mcp__*
+    // output landed only in the trace file — silent on the one surface where the value is still visible.
+    if (decision && !decision.redactable) {
+      process.stderr.write(`[mmi-hook] secret-redact: a secret-shaped value was detected in ${alarmTool} output and cannot be masked for this tool (no updatedToolOutput channel) — treat the transcript as exposed.\n`);
+    }
+    appendHookActivity({ event: 'PostToolUse', script: 'secret-redact', outcome, action, tool: tracedTool(input) });
+  } catch (err) {
+    // #2610: the redactor stays fail-open (PostToolUse — the bytes already left the tool, blocking buys
+    // nothing; see #2598 rescope), but its death must be LOUD. Record a greppable crash marker so a
+    // recurring silent failure is never invisible forever — doctor + the Stop summary read this line.
+    appendHookActivity({
+      event: 'PostToolUse',
+      script: 'secret-redact',
+      outcome: 'failed',
+      action: 'redactor crashed during scan',
+      error: err && typeof err === 'object' && 'message' in err ? String(err.message) : String(err),
+      tool: tracedTool(input),
+    });
+  }
+}
+
+if (
+  process.argv[1] &&
+  (process.argv[1].endsWith('secret-redact.mjs') ||
+    process.argv[1].replace(/\\/g, '/').endsWith('scripts/secret-redact.mjs'))
+) {
+  // #2610: a rejection from runHookGate() itself (e.g. the dynamic import blew up before the inner try) must
+  // not be swallowed silently either — record a crash marker, then keep the fail-open exit-0 contract.
+  runHookGate().then(() => process.exit(0)).catch((err) => {
+    appendHookActivity({
+      event: 'PostToolUse',
+      script: 'secret-redact',
+      outcome: 'failed',
+      action: 'redactor crashed before scan',
+      error: err && typeof err === 'object' && 'message' in err ? String(err.message) : String(err),
+    });
+    process.exit(0);
+  });
+}