glassbox-trace 0.7.1 → 0.9.1

package/README.md

@@ -56,10 +56,15 @@ The npm package is `glassbox-trace` (plain `glassbox` was already taken); the co
 
 Feedback at the end of a session can only change that session's last reply. Add `--context` to carry it forward: the Stop hook keeps the findings (and, with `--feedback`, the agent's answer) in `<project>/.glassbox/last-session.md` — git-ignored, deleted after a clean session — and a SessionStart hook gives them to the next session in that project.
 
+**Stop a loop before it happens.** `--guard` adds a PreToolUse hook: when the agent is about to repeat a call that has already failed twice in a row, unchanged, in the current turn, it blocks the call and tells the agent why, with the last error, and to change something or ask you rather than try again. It is deliberately narrow. Anything that could change the outcome in between — an edit, another command, a success, a new prompt — resets it, so re-running the tests after a fix is never blocked; calls a person stopped don't count; it never approves anything, so your permission prompts are untouched. Replayed over 4,121 real tool calls it blocked none, so it stays out of the way until an agent is actually stuck. It runs before every tool call, so it needs an installed copy: `--guard` writes a direct `node "…/bin/glassbox.mjs" hook …` command (for the Stop hook too) and refuses to install from an `npx` cache, where each call would cost seconds. The plugin doesn't include the guard ([why](docs/PLUGIN.md#the-loop-guard-is-not-in-the-plugin)); if both are installed, the plugin sees the CLI hook and steps aside.
+
 ```
 glassbox hook install --feedback --context --fail-on warn   # summary, feedback, and notes for the next session
 glassbox hook install                                       # summary only
 glassbox hook uninstall
+
+npm i -g glassbox-trace                                     # the guard needs an installed copy, not npx
+glassbox hook install --feedback --context --guard          # all of the above, plus the loop guard
 ```
 
 **Or install it as a Claude Code plugin** — the same hooks plus `/glassbox:check` and a skill Claude uses when you ask "what went wrong in this session?", running the bundled code (no npx): `/plugin marketplace add aldohushi1-stack/glassbox`, then `/plugin install glassbox@glassbox-trace`. Feedback and context are opt-in plugin options. See [docs/PLUGIN.md](docs/PLUGIN.md).
@@ -84,6 +89,54 @@ Read top to bottom: stats → timeline (with minimap, search, fit-to-turn) → c
 
 **Accessibility:** WCAG 2.2 AA contrast in both themes, full keyboard operation with roving focus on the timeline and chart, screen-reader names on every span and row, live announcements on load and search, focus-managed detail panel, reduced-motion respected. `npm run audit` re-checks all of it with axe-core and fails the build on regressions.
 
+### Secrets in transcripts — `glassbox fence`
+
+Every session transcript is plain text, and everything the agent read is in it: the `.env` it opened to find a port, the token `git remote -v` printed, the key you pasted. `fence` scans them and tells you what is there — never the value itself:
+
+```
+glassbox fence                         every session under ~/.claude — exit 1 if a credential was found
+glassbox fence 81c4cbfd                one session (and its subagents)
+glassbox fence ./archive               every .jsonl under a folder
+glassbox fence --format md --out fence.md
+glassbox fence --shred                 overwrite each value in place with [FENCED:<rule>:<fingerprint>]
+glassbox fence --sessions-only         transcripts only (the default sweep also covers prompt history, paste cache, file history, debug logs, shell snapshots)
+glassbox fence --key team.key          one shared fingerprint key for a fleet
+```
+
+```
+Glassbox fence · 34 sessions under /home/aldo/.claude/projects · 212 MB
+  3 error · 1 warn · 2 info · 3 distinct secrets in 2 of 41 files
+
+  /home/aldo/.claude/projects/-home-aldo-api/7c1e…jsonl
+    ERROR anthropic-key   line   212  sk-a…oP (62 chars)  ×2  — tool result · Read /home/aldo/api/.env
+    ERROR github-token    line   340  ghp_…r8 (40 chars)      — tool input · Bash
+    INFO  credential-file-read line 211  /home/aldo/api/.env  — tool input · Read
+```
+
+Each row is a masked preview and a fingerprint (first 8 hex of HMAC-SHA256 under a key that stays on the machine, so even a weak password's fingerprint can't be guessed against) — enough to know which key it is and to see the same key across sessions, never enough to use it. A sweep of the whole home also covers the other places Claude Code keeps text: prompt history, the paste cache, file-history snapshots, debug logs and shell snapshots. `error` is a credential whose format identifies it (AWS, GitHub, Anthropic, OpenAI, Slack, Stripe, Google, npm, SendGrid, a private key block, a database URL with its password); `warn` is a secret named by its context (`password=`, `api_key:`, `Bearer …`, a URL with credentials, a JWT), kept only when the value has the entropy of a real one and is not a placeholder; `info` is a read of a credential file (`.env`, `.npmrc`, `.netrc`, `~/.aws/credentials`, `id_rsa`, `*.pem` …) whose contents are now in the transcript whether or not a rule recognised them. A secret that reached a transcript reached a disk, and whatever backs that disk up: rotate it, then `--shred`. Shredded transcripts still open and check. It verifies nothing against any provider (no network), and a password in prose with no context word passes through — it is a net, not a guarantee. Details in [docs/FENCE.md](docs/FENCE.md).
+
+### Is my CLAUDE.md doing anything? — `glassbox adhere`
+
+Every rule in the project's instruction files, judged against every session of that project, per occasion, with evidence:
+
+```
+glassbox adhere                        the project in the current folder
+glassbox adhere --project ~/code/api --since 30d --format md --out adhere.md
+glassbox adhere --fail-under 80        exit 1 below that rate
+```
+
+```
+Glassbox adhere · /home/aldo/api
+  11 rules · 9 checkable · 2 not checkable yet · 34 sessions · obeyed 212 of 301 occasions (70%)
+
+  IGNORED        prefer-tool       0/38   0%  Use rg rather than grep.  (CLAUDE.md:11)
+                   ↳ 535876c9 t3  "Continue from where you left off."  →  grep -n "^export" src/cli.mjs | sed -n 1,80p
+  IGNORED        ask-before        0/1    0%  Ask before committing.  (CLAUDE.md:7)
+  OBEYED         never-touch       8/8  100%  Never edit files in dist/ by hand.  (CLAUDE.md:5)
+```
+
+Nine rule shapes are checkable from tool calls — run X before commit/push, run X after changes, use A not B, never run, never touch, ask before, read before edit, commit message format, no new docs — and everything else is listed as *not checkable yet* with its line number, so the report never claims more than it measured. Commands are judged on their shell surface (a `git push --force` inside a document being written is not a force push). The first real run, on the session that built it, scored 22%. Details and the honest caveats in [docs/ADHERE.md](docs/ADHERE.md).
+
 ## What it flags
 
 | rule | fires when |
@@ -134,6 +187,7 @@ src/trace-core.js     pure engine: parseTrace · diagnose · estimateCost · red
 src/viewer.html       the UI; the build inlines trace-core and the demo
 src/cli.mjs           CLI library (session discovery, embed, check, compare, hook); bin/glassbox.mjs is the entry point
 src/tail.mjs          live tail: byte-offset tailer + loopback SSE server for `glassbox watch`
+src/guard.mjs         the PreToolUse loop guard (`hook --guard`)
 scripts/build.mjs     build
 scripts/sanitize.mjs  turn a real transcript into a shareable fixture (demo or structure mode)
 scripts/corpus-audit.mjs  run every rule over your local sessions; counts only (--baseline to diff two runs)
@@ -165,6 +219,11 @@ Your context is private — by construction, not by promise.
 - **Nothing leaves.** The viewer makes no network requests at all — fonts, scripts and the demo are inside the one file, and the test suite fails if a build references anything outside it. The CLI sends nothing anywhere. `glassbox watch` binds to `127.0.0.1` only and stops with the command. The one network activity is installation: `npx` fetching the package, or the plugin marketplace fetching this repo.
 - **What it touches.** It reads `~/.claude/projects/**` and writes only what you ask for: `open` writes a self-contained HTML to your temp folder (transcript included — delete it when done, or use `--out`), `hook install` edits `~/.claude/settings.json` with a backup beside it, `--context` writes `<project>/.glassbox/last-session.md`, `--legend` writes the legend. The full inventory — files, processes, hooks, network, uninstall — is in [docs/IT.md](docs/IT.md), written for whoever has to approve it.
 - **Counts, not text.** Transcripts contain everything the agent saw; that's why share mode and `--redact` exist. Redacted output keeps tool names, numbers, timings and cost and drops every string — prompts, commands, results, titles. Where a finding would quote something it says `«240 chars»`.
+- **What is already on disk.** `glassbox fence` finds credentials that reached a transcript (known key formats, secrets named by context, credential-file reads), reports them masked and fingerprinted, and `--shred` overwrites them in place. See above.
 - **The shape, not the names.** A redacted report still needs to say "this one file was read 48 times and 6 of those failed". `check --redact --legend audit.legend.json` replaces every path with a keyed hash (`file:b94b1a35`, HMAC-SHA256 with a random salt) and writes the key → path map to the legend file, which stays on your machine. The redacted JSON carries `summary.files` (reads, writes, failures, agents, chars per key) and `evidence.files` on findings; `duplicate-subagent-read` keeps its sentence with the key in it. `glassbox reveal report.md --legend audit.legend.json` turns the keys back into paths for you. Re-using the legend keeps keys stable across runs; two machines with two legends produce different keys for the same file. Treat the legend like a password file: local, git-ignored, never attached to the same email as the report. Design notes in DESIGN.md §12.
 
 Source: [github.com/aldohushi1-stack/glassbox](https://github.com/aldohushi1-stack/glassbox) · MIT © Aldo Hushi
+
+## Security
+
+Found a way Glassbox could leak, run something it shouldn't, or be tampered with? Please report it privately — see [SECURITY.md](SECURITY.md).

package/dist/glassbox.html

@@ -408,7 +408,7 @@ kbd{font:11px var(--mono);border:1px solid var(--line);border-bottom-width:2px;b
 })(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict';
 
-  const VERSION = '0.7.1';
+  const VERSION = '0.9.1';
 
   // ---------------------------------------------------------------------------
   // Rate card (USD per million tokens). Prefix-matched against model ids so dated
@@ -1575,7 +1575,7 @@ kbd{font:11px var(--mono);border:1px solid var(--line);border-bottom-width:2px;b
   }
   function toJsonl(records) { return records.map((r) => JSON.stringify(r)).join('\n') + '\n'; }
 
-  return { VERSION, RATES, DEFAULTS, ADVICE, METRICS, parseLines, parseTrace, diagnose, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, fmtMetric, fmtRatio, fmtChange, stableStringify, inputSummary, adviceFor, redactDetail, reportMarkdown, compare, compareMarkdown, toolTable, fileStats, filePathOf, normalisePath };
+  return { VERSION, RATES, DEFAULTS, ADVICE, METRICS, parseLines, parseTrace, diagnose, denialKind, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, fmtMetric, fmtRatio, fmtChange, stableStringify, inputSummary, adviceFor, redactDetail, reportMarkdown, compare, compareMarkdown, toolTable, fileStats, filePathOf, normalisePath };
 });
 </script>
 <script>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "glassbox-trace",
-  "version": "0.7.1",
-  "description": "Other tools show what happened in a Claude Code session; Glassbox tells you what went wrong. Timeline, token and cost burn, auto-diagnostics with evidence and advice, session compare, live tail, a CLI and a Claude Code Stop hook that feeds the findings back to the agent.",
+  "version": "0.9.1",
+  "description": "Other tools show what happened in a Claude Code session; Glassbox tells you what went wrong. Timeline, token and cost burn, auto-diagnostics with evidence and advice, session compare, live tail, a fleet view, a secrets scanner for transcripts (fence), a CLAUDE.md compliance report (adhere), a CLI and a Claude Code Stop hook that feeds the findings back to the agent.",
   "main": "src/trace-core.js",
   "scripts": {
     "test": "node --test test/*.test.mjs",
@@ -30,6 +30,10 @@
   "keywords": [
     "claude-code",
     "claude-code-log",
+    "secrets",
+    "secret-scanning",
+    "claude-md",
+    "adherence",
     "compare",
     "live-tail",
     "claude",

package/src/adhere.mjs

@@ -0,0 +1,285 @@
+// glassbox adhere — is my CLAUDE.md doing anything?
+//
+// A CLAUDE.md is a list of instructions loaded into every session; the evidence of whether any of them worked is
+// scattered across thirty transcripts nobody reads. `adhere` turns the file into rules, finds every session whose
+// cwd is the project, and judges each rule on each occasion it applied to. Only nine rule shapes are checkable
+// mechanically (see DESIGN.md §15); everything else is listed as "not checkable yet" so the report never claims
+// more than it measured. Nothing leaves the machine.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { findSessions, loadSessionFiles, analyse, claudeHome } from './cli.mjs';
+import { readTextFile } from './textfile.mjs';
+const require = createRequire(import.meta.url);
+const core = require('./trace-core.js');
+
+// Claude Code files a project's sessions under projects/<path with every separator and colon as '-'>.
+export const encodeProject = (p) => String(p).replace(/[\\/:]/g, '-');
+const norm = (p) => String(p || '').replace(/\\/g, '/').toLowerCase();
+const WRITE_TOOLS = new Set(['Edit', 'MultiEdit', 'Write', 'NotebookEdit']);
+const EDIT_TOOLS = new Set(['Edit', 'MultiEdit', 'NotebookEdit']);
+const READ_TOOLS = new Set(['Read', 'NotebookRead']);
+
+// ---------------------------------------------------------------------------
+// Rules
+// ---------------------------------------------------------------------------
+const PM_PAIRS = { pnpm: ['npm', 'yarn'], yarn: ['npm', 'pnpm'], bun: ['npm', 'yarn', 'pnpm'], npm: ['yarn', 'pnpm'], uv: ['pip', 'poetry'], poetry: ['pip'], pip: [], rg: ['grep'], ripgrep: ['grep'], fd: ['find'], grep: [], find: [] };
+const PREFER_FOR = { npm: 'pnpm', yarn: 'pnpm', pnpm: 'npm', bun: 'npm', pip: 'uv', poetry: 'uv', grep: 'rg', find: 'fd' };
+const TOOLS_RE = 'pnpm|npm|yarn|bun|uv|pip|poetry|rg|ripgrep|fd|grep|find';
+const ACTION = (w) => /^commit/i.test(w) ? 'commit' : /^push/i.test(w) ? 'push' : /^(delet|remov)/i.test(w) ? 'delete' : /^install/i.test(w) ? 'install' : /^creat/i.test(w) ? 'create' : /^deploy/i.test(w) ? 'deploy' : /^merg/i.test(w) ? 'merge' : w.toLowerCase();
+const strip = (s) => s.replace(/`/g, '').replace(/\s+/g, ' ').trim();
+const whatOf = (s) => { const w = strip(s).replace(/^(?:the|all|your|our)\s+/i, ''); if (/^(?:tests?|test suite|unit tests|the tests)$/i.test(w)) return 'tests'; if (/^(?:formatter|code formatter)$/i.test(w)) return 'formatter'; if (/^(?:linter|lint)$/i.test(w)) return 'linter'; return w.replace(/\.$/, ''); };
+
+// ask-before: the actions named in a clause, in order, once each ("any commit / push / deploy" is three rules).
+const ACT_WORD = String.raw`(?:commit|push|delet|remov|install|creat|deploy|merg)\w*`;
+const actionsIn = (s) => [...new Set((s.match(new RegExp(String.raw`\b${ACT_WORD}`, 'gi')) || []).map(ACTION))];
+// A run of actions joined by , / or and: "committing, pushing or deploying". Stops at the first non-action word.
+const actList = (w) => String.raw`${w}(?:\s*(?:,|\/|\bor\b|\band\b)\s*(?:(?:or|and)\s+)?(?:any\s+|a\s+|an\s+)?${w})*`;
+const ACT_LIST = actList(ACT_WORD);
+const ACT_LIST_NC = actList(ACT_WORD.replace('creat|', '')); // "don't create … unless I ask" belongs to no-new-docs
+const ASK_VERB = String.raw`(?:ask(?:\s+me)?|check with me|confirm(?:\s+with me)?|get (?:my )?(?:explicit\s+)?(?:permission|approval|ok|confirmation)|wait for (?:my\s+|your\s+|an?\s+)?(?:explicit\s+)?(?:confirmation|approval|permission|go-?ahead|ok))`;
+const CONFIRM_NOUN = String.raw`(?:wait(?:ing)? for|get(?:ting)?|obtain(?:ing)?|ask(?:ing)? for|receiv(?:e|ing))\s+(?:my\s+|your\s+|an?\s+|the\s+)?(?:explicit\s+|express\s+|written\s+|clear\s+)?(?:confirmation|approval|permission|sign-?off|go-?ahead|ok)\b`;
+
+// Each matcher returns the rule's parameters (an array for one rule per action) or null. Order matters: first match wins.
+const SHAPES = [
+  { kind: 'ask-before', m: (s) => {
+    const each = (acts) => acts.length ? acts.map((action) => ({ action })) : null;
+    // "ask before committing or pushing" · "wait for approval before any deploy"
+    let m = s.match(new RegExp(String.raw`\b${ASK_VERB}\s*(?:first\s+)?(?:before|prior to)\s+(?:you\s+)?(?:any\s+|a\s+|an\s+)?(?:\w+ing\s+)?(${ACT_LIST})`, 'i'));
+    if (m) return each(actionsIn(m[1]));
+    // Reversed: "Before editing X, or any commit / push / deploy, state the change and wait for explicit confirmation."
+    m = s.match(new RegExp(String.raw`\b(?:before|prior to)\s+([^.]*?)\b${CONFIRM_NOUN}`, 'i'));
+    if (m) { const r = each(actionsIn(m[1])); if (r) return r; }
+    // "never push without asking" · "do not commit or push unless I ask"
+    m = s.match(new RegExp(String.raw`\b(?:never|don't|do not|don’t)\s+(${ACT_LIST_NC})\b[^.]*?\b(?:without|unless)\s+(?:first\s+)?(?:asking|being asked|i ask|you ask|i tell|told|permission|approval|confirm|checking|explicit)`, 'i'));
+    if (m) return each(actionsIn(m[1]));
+    return null;
+  } },
+  { kind: 'run-before', m: (s) => { let m = s.match(/\b(?:always\s+)?run\s+(?:the\s+)?(`[^`]+`|[\w][\w .:/-]*?)\s+(?:before|prior to)\s+(?:you\s+|every\s+|each\s+|any\s+|a\s+)?(?:\w+ing\s+)?(commit|push|merg|pull request|pr\b|open)/i); if (m) return { what: whatOf(m[1]), trigger: /^(commit)/i.test(m[2]) ? 'commit' : 'push' }; m = s.match(/\b(?:never|don't|do not|don’t)\s+(commit|push)\b[^.]*?\b(?:without|unless)\s+(?:first\s+)?(?:running\s+|you(?:'ve| have)?\s+run\s+|the\s+)?(`[^`]+`|[\w][\w .:/-]*?)(?:\s+(?:pass(?:es|ing)?|first|succeed\w*))?\.?$/i); if (m && !/\bask|permission|approv|confirm|check/i.test(s)) return { what: whatOf(m[2]), trigger: m[1].toLowerCase() }; m = s.match(/\b(tests?|test suite|linter|lint|build|typecheck|type check)\s+(?:must|should|need to|has to|have to)\s+(?:pass|succeed|be green)\s+(?:before|prior to)\s+(?:you\s+|every\s+|each\s+|any\s+)?(?:\w+ing\s+)?(commit|push|merg)/i); if (m) return { what: whatOf(m[1]), trigger: /^commit/i.test(m[2]) ? 'commit' : 'push' }; return null; } },
+  { kind: 'run-after', m: (s) => { let m = s.match(/\brun\s+(?:the\s+)?(`[^`]+`|[\w][\w .:/-]*?)\s+after\s+(?:you\s+)?(?:making\s+|every\s+|each\s+|any\s+|all\s+)?(?:change|edit|modif|writ)/i); if (m) return { what: whatOf(m[1]) }; m = s.match(/\b(format|lint|typecheck)\s+(?:the\s+)?(?:code|files?)\s+after\s+(?:you\s+)?(?:making\s+|every\s+|each\s+|any\s+)?(?:change|edit|modif)/i); if (m) return { what: /^format/i.test(m[1]) ? 'formatter' : /^lint/i.test(m[1]) ? 'linter' : m[1] }; return null; } },
+  { kind: 'prefer-tool', m: (s) => { let m = s.match(new RegExp(`\\b(?:never|don't|do not|don\u2019t|avoid)\\s+(?:us(?:e|ing)\\s+)?\`?(${TOOLS_RE})\`?\\b`, 'i')); if (m) { const avoid = m[1].toLowerCase(); return { prefer: PREFER_FOR[avoid] || null, avoid: [avoid] }; } m = s.match(new RegExp(`\\buse\\s+\`?(${TOOLS_RE})\`?\\b(?:[^.]*?\\b(?:not|instead of|rather than|never|over)\\s+\`?(${TOOLS_RE})\`?)?`, 'i')); if (m) { const prefer = m[1].toLowerCase(); const avoid = m[2] ? [m[2].toLowerCase()] : (PM_PAIRS[prefer] || []); return avoid.length ? { prefer, avoid } : null; } return null; } },
+  { kind: 'never-run', m: (s) => { if (/\b(?:never|don't|do not|don’t)\s+(?:force[- ]push|push\s+(?:with\s+)?--force|use\s+--force\s+(?:with|on|when)\s+push)/i.test(s)) return { pattern: 'git push --force' }; let m = s.match(/\b(?:never|don't|do not|don’t)\s+(?:run|execute|use|call|invoke)\s+`([^`]+)`/i); if (m) return { pattern: strip(m[1]) }; m = s.match(/\b(?:never|don't|do not|don’t)\s+(?:run|execute)\s+((?:git|rm|sudo|npm|pnpm|yarn|docker|curl|wget|kubectl|terraform|aws|gcloud|az|make|chmod|chown|dd|mkfs)\b[\w .:/-]*?)(?:\s+(?:anywhere|ever|in\b|on\b|under|unless|without|against)|[.,;]|$)/i); if (m) return { pattern: strip(m[1]) }; return null; } },
+  { kind: 'never-touch', m: (s) => { const m = s.match(/\b(?:never|don't|do not|don’t)\s+(?:ever\s+)?(?:edit|modify|touch|change|alter|write to|delete|remove|rewrite|overwrite)\s+(?:the\s+|any\s+|anything\s+in\s+)?(?:files?\s+(?:in|under|inside|within)\s+)?(?:the\s+)?`?([\w][\w./*\\-]*)`?/i); if (m && !/^(?:it|them|this|that|anything|code|files?)$/i.test(m[1])) return { path: m[1] }; return null; } },
+  { kind: 'read-before-edit', m: (s) => /\b(?:read|understand|look at|review|inspect)\s+(?:the\s+|an?\s+|existing\s+|any\s+)?(?:file|files|code|codebase|existing code|source)\b[^.]*?\b(?:before|prior to)\s+(?:you\s+)?(?:edit|modif|chang|writ|touch)/i.test(s) ? {} : null },
+  { kind: 'commit-format', m: (s) => { if (/\bconventional\s+commits?\b/i.test(s)) return { style: 'conventional' }; if (/\bcommit\s+messages?\s+(?:must|should|need to|have to|has to|always)\s+(?:start with|be prefixed|begin with|follow|use|include|reference)/i.test(s)) return { style: /ticket|issue|jira|[A-Z]{2,}-\d+/.test(s) ? 'ticket' : 'conventional' }; return null; } },
+  { kind: 'no-new-docs', m: (s) => /\b(?:never|don't|do not|don’t)\s+(?:create|add|write|generate|make)\s+(?:new\s+|any\s+|extra\s+)?(?:markdown|\.md\b|md\b|readme|documentation|docs?\b)/i.test(s) ? {} : null },
+];
+
+// CLAUDE.md → rules + not-checkable lines. Headings, blank lines and code fences are skipped; list markers and
+// bold are stripped; multi-sentence lines are split; rule text is kept verbatim (minus backticks).
+export function parseRules(text, file) {
+  const rules = [], unchecked = [];
+  let fence = false, n = 0;
+  for (const raw of String(text).split(/\r?\n/)) {
+    n++;
+    const line = raw.trim();
+    if (/^(```|~~~)/.test(line)) { fence = !fence; continue; }
+    if (fence || !line || /^#/.test(line) || /^[-*_]{3,}$/.test(line) || /^<!--/.test(line)) continue;
+    const body = line.replace(/^(?:[-*+]|\d+[.)])\s+/, '').replace(/^\[[ x]\]\s+/i, '').replace(/\*\*|__/g, '').trim();
+    if (!body) continue;
+    const parts = body.split(/(?<=[.!])\s+(?=[A-Z`])/);
+    for (const part of parts) {
+      const s = part.trim(); if (!s) continue;
+      let hits = null;
+      for (const sh of SHAPES) { const p = sh.m(s); if (p) { hits = [].concat(p).map((x) => Object.assign({ kind: sh.kind }, x)); break; } }
+      const rec = { id: `${file}:${n}${parts.length > 1 ? ':' + (parts.indexOf(part) + 1) : ''}`, file, line: n, text: strip(s) };
+      if (!hits) unchecked.push(rec);
+      else for (const h of hits) rules.push(Object.assign({}, rec, hits.length > 1 ? { id: `${rec.id}#${h.action}` } : null, h));
+    }
+  }
+  return { rules, unchecked };
+}
+
+export function findInstructionFiles(project, home) {
+  const out = [];
+  const add = (p, label) => { if (fs.existsSync(p) && fs.statSync(p).isFile()) out.push({ file: p, label }); };
+  add(path.join(project, 'CLAUDE.md'), 'CLAUDE.md');
+  add(path.join(project, '.claude', 'CLAUDE.md'), '.claude/CLAUDE.md');
+  add(path.join(project, 'CLAUDE.local.md'), 'CLAUDE.local.md');
+  add(path.join(home || claudeHome(), 'CLAUDE.md'), '~/.claude/CLAUDE.md (global)');
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Judging
+// ---------------------------------------------------------------------------
+const TEST_RE = /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test\b|\bnpx\s+(?:vitest|jest|mocha|ava)\b|\bpytest\b|\bpython3?\s+-m\s+(?:pytest|unittest)\b|\bcargo\s+test\b|\bgo\s+test\b|\bnode\s+--test\b|\bvitest\b|\bjest\b|\bmocha\b|\bphpunit\b|\brspec\b|\bmvn\s+(?:test|verify)\b|\bgradle(?:w)?\s+test\b|\bdotnet\s+test\b|\bmake\s+(?:test|check)\b|\bctest\b/i;
+const FORMAT_RE = /\bprettier\b|\bcargo\s+fmt\b|\bgofmt\b|\bgo\s+fmt\b|\brustfmt\b|\bblack\b|\bruff\s+format\b|\bbiome\s+format\b|\bdprint\b|\bclang-format\b|\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:format|fmt|prettier)\b/i;
+const LINT_RE = /\beslint\b|\bruff(?:\s+check)?\b|\bflake8\b|\bpylint\b|\bcargo\s+clippy\b|\bgolangci-lint\b|\bbiome\s+(?:lint|check)\b|\bstylelint\b|\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?lint\b/i;
+const pmNorm = (s) => String(s).replace(/\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?/g, 'run ').replace(/\brun\s+run\s+/g, 'run ').replace(/\s+/g, ' ').trim().toLowerCase();
+function commandMatches(cmd, what) {
+  const c = surface(cmd);
+  if (what === 'tests') return TEST_RE.test(c);
+  if (what === 'formatter') return FORMAT_RE.test(c);
+  if (what === 'linter') return LINT_RE.test(c);
+  return pmNorm(c).includes(pmNorm(what));
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function forbiddenRe(pattern) {
+  if (/^git push --force$/i.test(pattern)) return new RegExp(GIT + 'push\\b.*\\s(?:--force(?:-with-lease)?|-f)\\b', 'i');
+  return new RegExp('^' + escapeRe(pattern).replace(/\\\s+|\s+/g, '\\s+') + '(?=\\s|$)', 'i');
+}
+// A command's shell surface: heredoc bodies and inline programs (node -e "…", python -c "…") are content, not
+// commands — a `git push --force` inside a document being written is not a force push.
+export function surface(cmd) {
+  return String(cmd)
+    .replace(/<<-?\s*(['"]?)(\w+)\1[^\n]*\n[\s\S]*?\n\s*\2(?=\s|$|\))/g, '<<HEREDOC')
+    .replace(/\b(?:node|python3?|ruby|perl|php|deno)\s+(?:-[a-zA-Z]+\s+)*(?:-e|-c|--eval|eval)\s+("(?:[^"\\]|\\[\s\S])*"|'(?:[^'\\]|\\[\s\S])*')/g, (m, q) => m.slice(0, m.length - q.length) + '"…"');
+}
+// Shell segments (split on && || | ; and newlines), each with env assignments, sudo, time and exec looked through.
+export function segments(cmd) {
+  const out = [];
+  for (const seg of surface(cmd).split(/\s*(?:&&|\|\||\||;|\n)\s*/)) {
+    const toks = seg.trim().replace(/^[(\s]+/, '').split(/\s+/).filter(Boolean);
+    let i = 0; while (i < toks.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i]) || /^(?:sudo|time|exec|nice|nohup|env)$/.test(toks[i]))) i++;
+    if (i < toks.length) out.push(toks.slice(i).join(' '));
+  }
+  return out;
+}
+// The tool a segment starts with: `python -m pip` is pip, `pip3` is pip, a path prefix is dropped.
+function segmentTools(cmd) {
+  return segments(cmd).map((seg) => { const toks = seg.split(/\s+/); let t = toks[0].replace(/^.*[\\/]/, '').toLowerCase(); if (/^python3?$/.test(t) && toks[1] === '-m' && toks[2]) t = toks[2].toLowerCase(); if (t === 'pip3') t = 'pip'; return t; });
+}
+const hasSeg = (cmd, re) => segments(cmd).some((seg) => re.test(seg));
+function commitMessage(cmd) {
+  cmd = String(cmd);
+  const hd = cmd.match(/<<-?\s*['"]?(\w+)['"]?\n([\s\S]*?)\n\1/); if (hd) return hd[2].split('\n')[0].trim();
+  const q = cmd.match(/(?:^|\s)(?:-m|--message)(?:=|\s+)(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|(\S+))/); if (q) return (q[1] != null ? q[1] : q[2] != null ? q[2] : q[3]).split('\n')[0].trim();
+  return null;
+}
+const CONVENTIONAL = /^(?:feat|fix|chore|docs|refactor|test|perf|ci|build|style|revert)(?:\([^)]*\))?!?: \S/;
+const TICKET = /^\[?[A-Z][A-Z0-9]+-\d+\]?[:\s-]/;
+const pathHits = (rulePath, filePath, project) => {
+  let rel = norm(filePath); const pj = norm(project).replace(/\/$/, '');
+  if (pj && rel.startsWith(pj + '/')) rel = rel.slice(pj.length + 1);
+  const rp = norm(rulePath).replace(/^\.\//, '');
+  if (rp.includes('*')) return new RegExp('(?:^|/)' + escapeRe(rp).replace(/\\\*\\\*/g, '.*').replace(/\\\*/g, '[^/]*') + '$').test(rel);
+  if (rp.endsWith('/')) return rel.startsWith(rp) || rel.includes('/' + rp);
+  return rel === rp || rel.endsWith('/' + rp) || rel.startsWith(rp + '/') || rel.includes('/' + rp + '/');
+};
+// `git -c k=v -C dir --no-pager commit …` is still a commit.
+const OPTV = String.raw`(?:"[^"]*"|'[^']*'|\S)+`;
+const GIT = String.raw`^git\s+(?:(?:-c\s+${OPTV}|-C\s+${OPTV}|--no-pager|--git-dir=${OPTV}|--work-tree=${OPTV})\s+)*`;
+const git = (sub) => new RegExp(GIT + sub + '\\b');
+const actionRe = { commit: git('commit'), push: git('push'), delete: new RegExp('^(?:rm|rmdir|del|Remove-Item)\\b|' + GIT + 'rm\\b'), install: /^(?:npm|pnpm|yarn|bun|pip3?|uv|poetry|cargo|gem|brew|apt(?:-get)?|choco|winget)\s+(?:install|add|i)\b/, deploy: /^(?:vercel|netlify|fly\s+deploy|wrangler\s+(?:publish|deploy)|gcloud\s+run\s+deploy|serverless\s+deploy|eb\s+deploy)\b|^\S+\s+deploy\b/i, merge: git('merge') };
+const askedRe = { commit: /\bcommit/i, push: /\bpush/i, delete: /\b(?:delete|remove|rm\b|clean up|get rid)/i, install: /\binstall|\badd (?:the )?(?:package|dependency|dep)/i, create: /\b(?:create|make|add|write|new)\b/i, deploy: /\bdeploy|ship|release/i, merge: /\bmerge/i };
+
+// Judge every rule against one session. Returns per-rule { occasions:[{obeyed, session, turn, prompt, detail, at}] }.
+function judgeSession(rules, s, project) {
+  const { trace, cost } = analyse(loadSessionFiles(s));
+  const calls = trace.toolCalls.filter((c) => !c.unmatched).slice().sort((a, b) => a.start - b.start);
+  const turns = trace.turns;
+  const turnPrompt = (i) => { const t = turns.find((x) => x.index === i && x.agent === 'main') || turns.find((x) => x.index === i); return t ? { text: t.promptText || '', kind: t.promptKind } : { text: '', kind: null }; };
+  const prevTurnAsked = (i) => { const prev = trace.requests.filter((r) => r.turnIndex === i - 1 && r.agent === 'main'); if (!prev.length) return false; const last = prev[prev.length - 1]; const texts = (last.blocks || []).filter((b) => b.type === 'text').map((b) => b.text).join(' ').trim(); return /\?\s*$/.test(texts); };
+  const short = (t) => String(t == null ? '' : t).replace(/\s+/g, ' ').trim().slice(0, 160);
+  const occ = (c, obeyed, detail) => ({ obeyed, session: s.id, turn: c.turnIndex, prompt: turnPrompt(c.turnIndex).text.replace(/\s+/g, ' ').slice(0, 80), detail: short(detail), at: c.start });
+  const sessionOcc = (obeyed, detail, c) => ({ obeyed, session: s.id, turn: c ? c.turnIndex : null, prompt: c ? turnPrompt(c.turnIndex).text.replace(/\s+/g, ' ').slice(0, 80) : '', detail: short(detail), at: c ? c.start : trace.meta.start });
+  const bash = calls.filter((c) => c.name === 'Bash' && typeof c.input?.command === 'string');
+  const writes = calls.filter((c) => WRITE_TOOLS.has(c.name) && c.input && typeof c.input.file_path === 'string');
+  const out = rules.map(() => []);
+  rules.forEach((r, i) => {
+    const O = out[i];
+    if (r.kind === 'run-before') {
+      const trig = actionRe[r.trigger];
+      let lastAt = -Infinity;
+      for (const c of bash) { if (!hasSeg(c.input.command, trig)) continue; const ran = bash.some((b) => b.start > lastAt && b.start < c.start && commandMatches(b.input.command, r.what)); O.push(occ(c, ran, c.input.command)); lastAt = c.start; }
+    } else if (r.kind === 'run-after') {
+      if (writes.length) { const last = writes[writes.length - 1]; const ran = bash.some((b) => b.start > last.start && commandMatches(b.input.command, r.what)); O.push(sessionOcc(ran, `last write ${last.input.file_path}${ran ? '' : ' — no ' + r.what + ' after it'}`, last)); }
+    } else if (r.kind === 'prefer-tool') {
+      for (const c of bash) { const tools = segmentTools(c.input.command); const used = tools.filter((t) => t === r.prefer || r.avoid.includes(t)); if (!used.length) continue; const bad = used.some((t) => r.avoid.includes(t)); O.push(occ(c, !bad, c.input.command)); }
+    } else if (r.kind === 'never-run') {
+      const re = forbiddenRe(r.pattern); const hits = bash.filter((c) => hasSeg(c.input.command, re));
+      if (hits.length) for (const c of hits) O.push(occ(c, false, c.input.command)); else O.push(sessionOcc(true, 'no match in ' + bash.length + ' commands', null));
+    } else if (r.kind === 'never-touch') {
+      for (const c of writes) O.push(occ(c, !pathHits(r.path, c.input.file_path, project), c.input.file_path));
+    } else if (r.kind === 'ask-before') {
+      const targets = r.action === 'create' ? calls.filter((c) => c.name === 'Write') : bash.filter((c) => actionRe[r.action] && hasSeg(c.input.command, actionRe[r.action]));
+      for (const c of targets) {
+        const p = turnPrompt(c.turnIndex);
+        const inPrompt = p.kind === 'human' && askedRe[r.action].test(p.text);
+        const askedTool = calls.some((k) => k.name === 'AskUserQuestion' && k.turnIndex === c.turnIndex && k.start < c.start);
+        const replied = p.kind === 'human' && prevTurnAsked(c.turnIndex);
+        O.push(occ(c, inPrompt || askedTool || replied, r.action === 'create' ? c.input.file_path : c.input.command));
+      }
+    } else if (r.kind === 'read-before-edit') {
+      for (const c of calls.filter((k) => EDIT_TOOLS.has(k.name) && k.input && typeof k.input.file_path === 'string')) { const p = norm(c.input.file_path); const read = calls.some((k) => (READ_TOOLS.has(k.name) || k.name === 'Write') && k.agent === c.agent && k.start < c.start && k.input && norm(k.input.file_path || k.input.notebook_path) === p); O.push(occ(c, read, c.input.file_path)); }
+    } else if (r.kind === 'commit-format') {
+      for (const c of bash) { if (!hasSeg(c.input.command, actionRe.commit)) continue; const msg = commitMessage(c.input.command); if (msg == null) continue; const ok = r.style === 'ticket' ? TICKET.test(msg) : CONVENTIONAL.test(msg); O.push(occ(c, ok, msg)); }
+    } else if (r.kind === 'no-new-docs') {
+      const hits = calls.filter((c) => c.name === 'Write' && c.input && /\.(?:md|mdx|markdown|rst|txt)$/i.test(String(c.input.file_path || '')));
+      const asked = (c) => { const p = turnPrompt(c.turnIndex); return p.kind === 'human' && /\b(?:doc|docs|documentation|readme|markdown|\.md\b|notes?|write[- ]?up|report|pdf|release notes|changelog|guide)\b/i.test(p.text); };
+      if (hits.length) for (const c of hits) O.push(occ(c, r.unlessAsked && asked(c), c.input.file_path)); else O.push(sessionOcc(true, 'no new docs in ' + writes.length + ' writes', null));
+    }
+  });
+  return { perRule: out, session: { id: s.id, start: trace.meta.start ? new Date(trace.meta.start).toISOString() : null, cost: cost && cost.total != null ? cost.total : null, title: trace.meta.title || null } };
+}
+
+// ---------------------------------------------------------------------------
+// The report
+// ---------------------------------------------------------------------------
+const NOTES = { 'ask-before': 'The least certain of the nine checks: "asked" means the turn\'s own prompt names the action, an AskUserQuestion ran earlier in the turn, or the previous turn ended with a question. A standing instruction from an earlier turn counts as unasked.', 'run-before': 'Counts that the command ran, not that it passed.', 'read-before-edit': 'A read by another agent does not count — the editing agent must have seen the file.' };
+export function adhere(opts = {}) {
+  const home = opts.home || claudeHome();
+  const project = path.resolve(opts.project || process.cwd());
+  const files = opts.claudeMd ? [{ file: path.resolve(opts.claudeMd), label: path.basename(opts.claudeMd) }] : findInstructionFiles(project, home);
+  if (!files.length) throw new Error(`adhere: no CLAUDE.md found for ${project}\n  Looked for CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md there and ~/.claude/CLAUDE.md.\n  Point at one with --claude-md FILE, or at the project with --project DIR.`);
+  const rules = [], unchecked = [], fileRows = [];
+  for (const f of files) { if (!fs.existsSync(f.file)) throw new Error(`adhere: ${f.file} not found`); const r = parseRules(readTextFile(f.file), f.label); rules.push(...r.rules); unchecked.push(...r.unchecked); fileRows.push({ file: f.file, label: f.label, rules: r.rules.length, unchecked: r.unchecked.length }); }
+  // Sessions of this project: the folder name Claude Code would use; else a decoded-path substring match.
+  const enc = encodeProject(project).toLowerCase();
+  let list = findSessions({ home }).filter((s) => path.basename(s.projectDir).toLowerCase() === enc);
+  if (!list.length) list = findSessions({ home, project: project.replace(/\\/g, '/') });
+  if (opts.since != null) list = list.filter((s) => s.mtime >= opts.since);
+  const perRule = rules.map(() => []); const sessions = [];
+  for (const s of list) { const j = judgeSession(rules, s, project); j.perRule.forEach((o, i) => perRule[i].push(...o)); sessions.push(j.session); }
+  const R = (t) => opts.redact ? `«${String(t).length} chars»` : t;
+  const rows = rules.map((r, i) => {
+    const occ = perRule[i]; const obeyed = occ.filter((o) => o.obeyed).length; const broken = occ.length - obeyed;
+    const rate = occ.length ? obeyed / occ.length : null;
+    const verdict = !occ.length ? 'never came up' : rate === 1 ? 'obeyed' : rate >= 0.8 ? 'mostly obeyed' : rate > 0 ? 'often ignored' : 'ignored';
+    const examples = occ.filter((o) => !o.obeyed).slice(0, 3).map((o) => ({ session: o.session, turn: o.turn, prompt: R(o.prompt), detail: R(o.detail) }));
+    // One line can hold several ask-before rules ("commit / push / deploy"); the label tells them apart.
+    const row = { id: r.id, file: r.file, line: r.line, text: r.text, kind: r.kind, label: r.id.includes('#') ? `${r.kind}:${r.action}` : r.kind, occasions: occ.length, obeyed, broken, rate, verdict, examples, sessionsBroken: new Set(occ.filter((o) => !o.obeyed).map((o) => o.session)).size };
+    for (const k of ['what', 'trigger', 'prefer', 'avoid', 'pattern', 'path', 'action', 'style', 'unlessAsked']) if (r[k] !== undefined) row[k] = r[k];
+    if (NOTES[r.kind]) row.note = NOTES[r.kind];
+    return row;
+  });
+  const occasions = rows.reduce((n, r) => n + r.occasions, 0), obeyed = rows.reduce((n, r) => n + r.obeyed, 0);
+  const brokenSessions = new Set(); rules.forEach((r, i) => perRule[i].filter((o) => !o.obeyed).forEach((o) => brokenSessions.add(o.session)));
+  const breachCost = sessions.filter((s) => brokenSessions.has(s.id)).reduce((n, s) => n + (s.cost || 0), 0);
+  return { glassbox: core.VERSION, kind: 'adhere', schema: 1, generated: new Date().toISOString(), project, home, since: opts.since ? new Date(opts.since).toISOString() : undefined, redacted: !!opts.redact,
+    files: fileRows, sessions: sessions.map((s) => Object.assign({}, s, { title: R(s.title || ''), breached: brokenSessions.has(s.id) })),
+    rules: rows, unchecked,
+    summary: { rules: rules.length, checkable: rules.length, unchecked: unchecked.length, sessions: sessions.length, occasions, obeyed, broken: occasions - obeyed, rate: occasions ? obeyed / occasions : null, neverCameUp: rows.filter((r) => !r.occasions).length, sessionsWithBreach: brokenSessions.size, breachCost } };
+}
+
+const pct = (r) => r == null ? '—' : Math.round(r * 100) + '%';
+const usd = (n) => n == null ? '—' : '$' + n.toFixed(2);
+function headline(rep) { const s = rep.summary; return `${s.rules} rule${s.rules === 1 ? '' : 's'} · ${s.checkable} checkable · ${s.unchecked} not checkable yet · ${s.sessions} session${s.sessions === 1 ? '' : 's'} · obeyed ${s.obeyed} of ${s.occasions} occasions${s.rate == null ? '' : ` (${pct(s.rate)})`}`; }
+
+export function adhereText(rep) {
+  const L = [`Glassbox adhere · ${rep.project}${rep.since ? ` · since ${rep.since.slice(0, 10)}` : ''}`, `  ${headline(rep)}`];
+  if (rep.summary.sessionsWithBreach) L.push(`  ${rep.summary.sessionsWithBreach} session${rep.summary.sessionsWithBreach === 1 ? '' : 's'} broke at least one rule (${usd(rep.summary.breachCost)} of spend in those sessions — not the cost of the breach, just where it happened)`);
+  L.push('');
+  const order = { 'ignored': 0, 'often ignored': 1, 'mostly obeyed': 2, 'obeyed': 3, 'never came up': 4 };
+  for (const r of rep.rules.slice().sort((a, b) => order[a.verdict] - order[b.verdict] || b.occasions - a.occasions)) {
+    L.push(`  ${r.verdict.toUpperCase().padEnd(14)} ${r.label.padEnd(17)} ${r.occasions ? `${r.obeyed}/${r.occasions} ${pct(r.rate).padStart(4)}` : '   —      '}  ${r.text}  (${r.file}:${r.line})`);
+    for (const e of r.examples) L.push(`                   ↳ ${e.session.slice(0, 8)} t${e.turn == null ? '?' : e.turn}  "${e.prompt}"  →  ${e.detail}`);
+  }
+  if (rep.unchecked.length) { L.push('', `  Not checkable yet (${rep.unchecked.length}) — no mechanical test for these shapes; they are loaded every session all the same:`); for (const u of rep.unchecked) L.push(`    · ${u.text}  (${u.file}:${u.line})`); }
+  L.push('', '  Rules are judged per occasion from tool calls only; "asked" and "ran the tests" are inferred, not known. Read the examples before believing a number.');
+  return L.join('\n') + '\n';
+}
+
+export function adhereMarkdown(rep) {
+  const s = rep.summary;
+  const L = ['# Is my CLAUDE.md doing anything?', '', `Project \`${rep.project}\` · ${rep.generated.slice(0, 10)}${rep.since ? ` · sessions since ${rep.since.slice(0, 10)}` : ''}`, '', `**${headline(rep)}**`, ''];
+  if (s.sessionsWithBreach) L.push(`${s.sessionsWithBreach} of ${s.sessions} sessions broke at least one rule; those sessions cost ${usd(s.breachCost)} in total (where the breaches happened, not what they cost).`, '');
+  L.push('## Rules', '', '| rule | kind | occasions | obeyed | broken | rate | verdict |', '|---|---|---:|---:|---:|---:|---|');
+  for (const r of rep.rules) L.push(`| ${r.text.replace(/\|/g, '\\|')} <br><sub>${r.file}:${r.line}</sub> | \`${r.label}\` | ${r.occasions} | ${r.obeyed} | ${r.broken} | ${pct(r.rate)} | ${r.verdict} |`);
+  const withEx = rep.rules.filter((r) => r.examples.length);
+  if (withEx.length) { L.push('', '## Evidence', ''); for (const r of withEx) { L.push(`### ${r.text}`, '', `\`${r.label}\` · ${r.broken} of ${r.occasions} occasions broken across ${r.sessionsBroken} session${r.sessionsBroken === 1 ? '' : 's'}${r.note ? ` · ${r.note}` : ''}`, ''); for (const e of r.examples) L.push(`- \`${e.session.slice(0, 8)}\` turn ${e.turn == null ? '?' : e.turn} — prompt: "${e.prompt}" — ${e.detail.replace(/\|/g, '\\|')}`); L.push(''); } }
+  if (rep.unchecked.length) { L.push('## Not checkable yet', '', 'No mechanical test exists for these shapes; they are loaded into every session all the same.', ''); for (const u of rep.unchecked) L.push(`- ${u.text} <sub>${u.file}:${u.line}</sub>`); L.push(''); }
+  L.push('## How to read this', '', 'Every number comes from tool calls in the transcripts, judged per occasion (a commit, a write, a command). "Asked" means the turn\'s own prompt named the action, an AskUserQuestion ran first, or the previous turn ended with a question — a standing instruction from an earlier turn counts as unasked. "Ran the tests" means a test command ran, not that it passed. A rule that never came up is not an obeyed rule. `glassbox adhere --format json` has every occasion.', '');
+  return L.join('\n');
+}

package/src/cli.mjs

@@ -7,6 +7,7 @@ import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { readTextFile } from './textfile.mjs';
+import { guardResponse } from './guard.mjs';
 const require = createRequire(import.meta.url);
 const core = require('./trace-core.js');
 // fileURLToPath, not URL.pathname: on Windows the latter gives "/C:/…" which path.resolve turns into "\C:\…".
@@ -248,6 +249,8 @@ export function hookResponse(input, opts = {}) {
   const failOn = opts.failOn || 'warn';
   const feedback = !!opts.feedback;
   if (input && input.hook_event_name === 'SessionStart') return opts.context ? sessionStartResponse(input) : { suppressOutput: true };
+  // PreToolUse: null means "say nothing" (normal permission flow), never an approval.
+  if (input && input.hook_event_name === 'PreToolUse') return opts.guard ? guardResponse(input) : null;
   // Second Stop after a feedback block: record what the agent said it would do differently, then let it stop.
   if (opts.context && input && input.hook_event_name === 'Stop' && input.stop_hook_active) {
     const file = notesPath(input.cwd);
@@ -289,23 +292,33 @@ export function readStdinJson() {
   return new Promise((resolve) => { let buf = ''; process.stdin.setEncoding('utf8'); process.stdin.on('data', (d) => { buf += d; }); process.stdin.on('end', () => { try { resolve(JSON.parse(buf || '{}')); } catch (e) { resolve({}); } }); if (process.stdin.isTTY) resolve({}); });
 }
 
-const HOOK_RE = /\bglassbox(?:-trace)?\s+hook\b/;
+// A Glassbox hook command in settings.json: `npx -y glassbox-trace hook …`, `glassbox hook …`, or the direct
+// form `node "…/bin/glassbox.mjs" hook …` that --guard installs.
+export const HOOK_RE = /\bglassbox(?:-trace)?(?:\.mjs)?["']?\s+hook\b/;
 export function settingsPath(home) { return path.join(home || claudeHome(), 'settings.json'); }
 export function installHook(opts = {}) {
   const file = settingsPath(opts.home);
   let settings = {};
   if (fs.existsSync(file)) { try { settings = JSON.parse(readTextFile(file)); } catch (e) { throw new Error(`${file} is not valid JSON — fix it first (nothing was changed)`); } fs.copyFileSync(file, file + '.glassbox-backup'); }
   settings.hooks = settings.hooks || {};
-  const cmd = `${opts.command || 'npx -y glassbox-trace'} hook${opts.feedback ? ' --feedback' : ''}${opts.context ? ' --context' : ''}${opts.failOn ? ' --fail-on ' + opts.failOn : ''}`;
-  for (const ev of opts.events || (opts.context ? ['Stop', 'SessionStart'] : ['Stop'])) {
+  const cmd = `${opts.command || 'npx -y glassbox-trace'} hook${opts.feedback ? ' --feedback' : ''}${opts.context ? ' --context' : ''}${opts.guard ? ' --guard' : ''}${opts.failOn ? ' --fail-on ' + opts.failOn : ''}`;
+  const events = opts.events || ['Stop', ...(opts.context ? ['SessionStart'] : []), ...(opts.guard ? ['PreToolUse'] : [])];
+  for (const ev of events) {
     const list = Array.isArray(settings.hooks[ev]) ? settings.hooks[ev] : [];
     const kept = list.filter((entry) => !(entry && Array.isArray(entry.hooks) && entry.hooks.some((h) => h && typeof h.command === 'string' && HOOK_RE.test(h.command))));
-    kept.push({ hooks: [{ type: 'command', command: cmd, timeout: 60 }] });
+    // PreToolUse runs before every tool call, so it gets a short timeout; no matcher means all tools.
+    kept.push({ hooks: [{ type: 'command', command: cmd, timeout: ev === 'PreToolUse' ? 10 : 60 }] });
     settings.hooks[ev] = kept;
   }
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return { file, command: cmd };
+  return { file, command: cmd, events };
+}
+// The guard runs before every tool call, so it can't go through npx (seconds per call). Point the hook at
+// this install's own entry point instead — unless this *is* a throwaway npx cache copy.
+export function guardCommand(root) {
+  if (/[\\/]_npx[\\/]/.test(root)) throw new Error('--guard runs before every tool call, and through npx that takes seconds each time. Install Glassbox once (npm i -g glassbox-trace) and run `glassbox hook install --guard` again, or pass --command with a direct path.');
+  return `node "${path.join(root, 'bin', 'glassbox.mjs')}"`;
 }
 export function uninstallHook(opts = {}) {
   const file = settingsPath(opts.home);
@@ -325,7 +338,7 @@ export function parseArgs(argv) {
   const args = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a.startsWith('--')) { const [k, v] = a.slice(2).split('='); if (v !== undefined) args.flags[k] = v; else if (i + 1 < argv.length && !argv[i + 1].startsWith('-') && ['last', 'grep', 'project', 'out', 'fail-on', 'home', 'command', 'events', 'format', 'label-a', 'label-b', 'port', 'rates', 'since', 'legend'].includes(k)) args.flags[k] = argv[++i]; else args.flags[k] = true; }
+    if (a.startsWith('--')) { const [k, v] = a.slice(2).split('='); if (v !== undefined) args.flags[k] = v; else if (i + 1 < argv.length && !argv[i + 1].startsWith('-') && ['last', 'grep', 'project', 'out', 'fail-on', 'home', 'command', 'events', 'format', 'label-a', 'label-b', 'port', 'rates', 'since', 'legend', 'claude-md', 'fail-under', 'key'].includes(k)) args.flags[k] = argv[++i]; else args.flags[k] = true; }
     else args._.push(a);
   }
   return args;
@@ -353,16 +366,26 @@ export const HELP = `glassbox — other tools show you what happened in a Claude
                                  same task, two sessions: what changed in time, tokens, cost, tools and findings
   glassbox watch [ID|FILE] [--port N] [--no-open]
                                  live tail: serves the viewer on 127.0.0.1 and pushes the transcript as it grows
-  glassbox hook install [--feedback] [--context] [--fail-on warn]
+  glassbox hook install [--feedback] [--context] [--guard] [--fail-on warn]
                                  add a Claude Code Stop hook so every session ends with a Glassbox summary;
                                  --feedback also hands the findings back to the agent once, so it can learn from them;
-                                 --context keeps them in <project>/.glassbox/last-session.md and gives them to the next session
+                                 --context keeps them in <project>/.glassbox/last-session.md and gives them to the next session;
+                                 --guard blocks a tool call that already failed twice in a row, unchanged, and says why
   glassbox hook uninstall        remove it (a .glassbox-backup of settings.json is kept)
   glassbox collect DIR [--since 30d] [--format text|md|json] [--out FILE] [--top N]
                                  fleet view from a folder of check reports: each machine writes one with
                                  check --all --redact --legend audit.legend.json --format json > <share>/<name>.json
                                  (unredacted reports are skipped unless --allow-unredacted)
   glassbox clean                 delete what open and the hook left in the temp folder (viewer files, hook state)
+  glassbox adhere [--project DIR] [--claude-md FILE] [--since 30d] [--format text|md|json] [--out FILE] [--redact] [--fail-under N]
+                                 is my CLAUDE.md doing anything? every rule in the project's instruction files judged
+                                 against every session of that project: obeyed / broken per occasion, with evidence;
+                                 shapes it cannot check are listed as such. --fail-under 80 exits 1 below that rate
+  glassbox fence [ID|FILE|DIR] [--since 30d] [--format text|md|json] [--out FILE] [--fail-on error|warn|info] [--shred] [--key FILE] [--sessions-only]
+                                 secrets that reached a transcript: known key formats, secrets named by context,
+                                 credential-file reads — with a masked preview and a fingerprint, never the value.
+                                 no target = every session under the home; exit 1 when anything at/above --fail-on was found
+                                 --shred overwrites each value in place with [FENCED:<rule>:<fingerprint>] (no backup)
   glassbox hook                  (what Claude Code runs: reads the hook JSON on stdin, replies on stdout)
 
   Options   --home DIR   use DIR instead of ~/.claude (or set GLASSBOX_HOME)
@@ -511,15 +534,41 @@ export async function main(argv, io = {}) {
     }
     if (cmd === 'hook') {
       const sub = args._[1];
-      if (sub === 'install') { const r = installHook({ home, feedback: !!args.flags.feedback, context: !!args.flags.context, failOn: args.flags['fail-on'], command: args.flags.command, events: args.flags.events ? String(args.flags.events).split(',') : undefined }); out(`Installed ${args.flags.context ? 'Stop and SessionStart hooks' : 'Stop hook'} in ${r.file}\n  ${r.command}\nEvery session now ends with a Glassbox summary${args.flags.feedback ? ', and findings are handed back to the agent once' : ''}${args.flags.context ? `; findings are kept in <project>/${NOTES_FILE.replace(/\\/g, '/')} and handed to the next session there` : ''}. Restart Claude Code to pick it up.`); return 0; }
+      if (sub === 'install') { const r = installHook({ home, feedback: !!args.flags.feedback, context: !!args.flags.context, guard: !!args.flags.guard, failOn: args.flags['fail-on'], command: args.flags.command || (args.flags.guard ? guardCommand(ROOT) : undefined), events: args.flags.events ? String(args.flags.events).split(',') : undefined }); out(`Installed ${r.events.join(', ')} hook${r.events.length > 1 ? 's' : ''} in ${r.file}\n  ${r.command}\nEvery session now ends with a Glassbox summary${args.flags.feedback ? ', and findings are handed back to the agent once' : ''}${args.flags.context ? `; findings are kept in <project>/${NOTES_FILE.replace(/\\/g, '/')} and handed to the next session there` : ''}${args.flags.guard ? '; a call that already failed twice in a row, unchanged, is blocked with the reason' : ''}. Restart Claude Code to pick it up.`); return 0; }
       if (sub === 'uninstall') { const r = uninstallHook({ home }); out(`Removed ${r.removed} Glassbox hook${r.removed === 1 ? '' : 's'} from ${r.file}`); return 0; }
       // A hook must never fail loudly: exit 2 from a Stop hook blocks Claude with the error as the reason.
-      let reply;
-      try { const input = io.stdin !== undefined ? io.stdin : await readStdinJson(); reply = hookResponse(input, { failOn: args.flags['fail-on'], feedback: !!args.flags.feedback, context: !!args.flags.context, rates, stateDir: io.stateDir }); }
-      catch (e) { reply = { systemMessage: 'Glassbox: ' + e.message, suppressOutput: true }; }
-      out(JSON.stringify(reply));
+      // A null reply prints nothing, which for PreToolUse means "no decision".
+      let reply = null, event = null;
+      try { const input = io.stdin !== undefined ? io.stdin : await readStdinJson(); event = input && input.hook_event_name; reply = hookResponse(input, { failOn: args.flags['fail-on'], feedback: !!args.flags.feedback, context: !!args.flags.context, guard: !!args.flags.guard, rates, stateDir: io.stateDir }); }
+      catch (e) { reply = event === 'PreToolUse' ? null : { systemMessage: 'Glassbox: ' + e.message, suppressOutput: true }; }
+      if (reply != null) out(JSON.stringify(reply));
       return 0;
     }
+    if (cmd === 'fence') {
+      // Secrets that reached a transcript. No target = every session under the home; an id, a file, or a folder of .jsonl.
+      const { fence, fenceText, fenceMarkdown, failedAt } = await import('./fence.mjs');
+      const since = args.flags.since ? Date.now() - parseSince(args.flags.since) : null;
+      const failOn = args.flags['fail-on'] || 'error';
+      const fmtOut = outputFormat(args.flags);
+      const rep = fence({ home, target: args._[1], since, project: args.flags.project, shred: !!args.flags.shred, keyFile: args.flags.key, sessionsOnly: !!args.flags['sessions-only'] });
+      const failed = failedAt(rep, failOn);
+      const text = fmtOut === 'json' ? JSON.stringify(rep, null, 2) : fmtOut === 'md' ? fenceMarkdown(rep) : fenceText(rep);
+      if (args.flags.out) { const f = path.resolve(args.flags.out); fs.writeFileSync(f, text); out(`${f}  (${rep.scanned.files} files, ${rep.findings.length} findings${rep.shredded ? `, ${rep.shredded.values} values shredded` : ''})`); }
+      else out(text.replace(/\n$/, ''));
+      return failed ? 1 : 0;
+    }
+    if (cmd === 'adhere') {
+      // Is my CLAUDE.md doing anything? Rules from the instruction files, occasions from the project's transcripts.
+      const { adhere, adhereText, adhereMarkdown } = await import('./adhere.mjs');
+      const since = args.flags.since ? Date.now() - parseSince(args.flags.since) : null;
+      const fmtOut = outputFormat(args.flags);
+      let failUnder = null; if (args.flags['fail-under'] !== undefined) { failUnder = Number(args.flags['fail-under']); if (!Number.isFinite(failUnder) || failUnder < 0 || failUnder > 100) throw new Error(`--fail-under must be a percentage 0–100 (got "${args.flags['fail-under']}")`); }
+      const rep = adhere({ home, project: args.flags.project, claudeMd: args.flags['claude-md'], since, redact: !!args.flags.redact });
+      const text = fmtOut === 'json' ? JSON.stringify(rep, null, 2) : fmtOut === 'md' ? adhereMarkdown(rep) : adhereText(rep);
+      if (args.flags.out) { const f = path.resolve(args.flags.out); fs.writeFileSync(f, text); out(`${f}  (${rep.summary.rules} rules, ${rep.summary.sessions} sessions, ${rep.summary.rate == null ? 'no occasions' : Math.round(rep.summary.rate * 100) + '% obeyed'})`); }
+      else out(text.replace(/\n$/, ''));
+      return failUnder != null && rep.summary.rate != null && rep.summary.rate * 100 < failUnder ? 1 : 0;
+    }
     err('Unknown command: ' + cmd + '\n'); out(HELP); return 2;
   } catch (e) { err('glassbox: ' + e.message); return 2; }
 }

package/src/fence.mjs

@@ -0,0 +1,338 @@
+// glassbox fence — secrets that reached a transcript: find them, fingerprint them, shred them.
+//
+// Every Claude Code session is a plain-text JSONL under ~/.claude/projects, and everything the agent read is in
+// it: the .env it opened to find a port, the token `git remote -v` printed, the key the user pasted. Those files
+// are never deleted, they sync wherever the home folder syncs, and they get attached to bug reports. `fence`
+// scans them (a session, a file, a folder, or the whole home), reports each hit with a masked preview and a
+// fingerprint (never the value), and with --shred rewrites the value in place as [FENCED:<rule>:<fingerprint>].
+// Run over the whole home it also scans the other places Claude Code keeps text (STORES: prompt history, the
+// paste cache, file-history snapshots, debug logs, shell snapshots).
+// Fingerprints are keyed (HMAC-SHA256 under a 32-byte key that stays on the machine), so a report holding the
+// fingerprint of a weak password gives nobody anything to check guesses against.
+// No network: nothing is verified against a provider, and the report is meant to stay on the machine.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { findSessions, subagentFiles, resolveTarget, claudeHome } from './cli.mjs';
+const require = createRequire(import.meta.url);
+const core = require('./trace-core.js');
+
+const SEV = { error: 0, warn: 1, info: 2 };
+const PLACEHOLDER = /your[_-]?|example|sample|placeholder|changeme|change[_-]me|xxxx|dummy|redacted|fenced|<|>|\$\{|\*\*\*/i;
+const CRED_FILE = /(^|[\\/])(?:\.env(?:\.[\w.-]+)?|\.npmrc|\.netrc|\.pgpass|\.git-credentials|credentials(?:\.json)?|id_rsa|id_ed25519|id_ecdsa|id_dsa|[\w.-]*_key|[\w.-]*\.(?:pem|key|p12|pfx|ppk)|secrets?\.(?:json|ya?ml|toml|env|txt)|service[_-]?account[\w.-]*\.json)$/i;
+const CRED_FILE_NOT = /\.env\.(?:example|sample|template|dist|schema)$|\.pub$/i;
+export const isCredentialFile = (p) => !!p && CRED_FILE.test(String(p).trim()) && !CRED_FILE_NOT.test(String(p).trim());
+const DUMP_CMD = /(?:^|[;&|]\s*)(?:cat|type|less|more|head|tail|Get-Content|gc)\s+(?:-\S+\s+)*(\S+)|(?:^|[;&|]\s*)(?:printenv|env)\s*(?:$|[;&|])|echo\s+\$\{?\w*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD)\w*\}?/im;
+
+// Shannon entropy in bits per character.
+export function entropy(s) { const n = s.length; if (!n) return 0; const c = new Map(); for (const ch of s) c.set(ch, (c.get(ch) || 0) + 1); let h = 0; for (const k of c.values()) { const p = k / n; h -= p * Math.log2(p); } return h; }
+// Keyed fingerprint: the first 8 hex of HMAC-SHA256(key, value). Without a key (pure use, tests) a random key for
+// this process is used, so fingerprints are stable within a run and are never a plain, guessable hash.
+const PROCESS_KEY = crypto.randomBytes(32);
+export const fingerprint = (v, key) => crypto.createHmac('sha256', key || PROCESS_KEY).update(String(v)).digest('hex').slice(0, 8);
+export const defaultKeyFile = (home) => path.join(home || claudeHome(), 'glassbox', 'fence.key');
+// A key file holds 64 hex characters. loadKey(file) reads one; ensureKey(file) creates it (owner-only) when missing.
+export function loadKey(file) {
+  let raw; try { raw = fs.readFileSync(file, 'utf8').trim(); } catch (e) { throw new Error(`--key ${file}: not found`); }
+  if (!/^[0-9a-fA-F]{64}$/.test(raw)) throw new Error(`--key ${file}: must hold 64 hex characters (a 32-byte key)`);
+  return Buffer.from(raw, 'hex');
+}
+export function ensureKey(file) {
+  if (fs.existsSync(file)) return loadKey(file);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const key = crypto.randomBytes(32);
+  fs.writeFileSync(file, key.toString('hex') + '\n', { mode: 0o600, flag: 'wx' });
+  return key;
+}
+
+// The other places under the Claude home that hold text a secret can land in (anthropics/claude-code#50014).
+// Scanned when fence runs over the whole home without --project or --sessions-only.
+export const STORES = [
+  { id: 'history', where: 'prompt history', file: 'history.jsonl' },
+  { id: 'paste-cache', where: 'paste cache', dir: 'paste-cache' },
+  { id: 'file-history', where: 'file history', dir: 'file-history', session: (rel) => rel.split(/[\\/]/)[0] },
+  { id: 'debug', where: 'debug log', dir: 'debug', session: (rel) => path.basename(rel).replace(/\.[^.]+$/, '') },
+  { id: 'shell-snapshots', where: 'shell snapshot', dir: 'shell-snapshots' },
+];
+const STORE_MAX_BYTES = 64 * 1024 * 1024;
+const isBinary = (buf) => buf.subarray(0, 8192).includes(0);
+export function mask(v) { const s = String(v); if (/-----BEGIN/.test(s)) return `PRIVATE KEY block (${s.length} chars)`; return `${s.length > 6 ? s.slice(0, 4) : ''}…${s.slice(-2)} (${s.length} chars)`; }
+
+// Detectors, most specific first: a hit whose span overlaps an earlier hit is dropped, so a GitHub token after
+// "Bearer" is one github-token, not also a generic-secret, and a database URL is not also a basic-auth URL.
+// `re` must have the g flag; `value(m)` picks the secret out of the match (default: the whole match).
+// In raw JSONL a newline inside a string is the two characters \n, so a key at the start of a line sits right after
+// an "n"; B is the word boundary that also accepts an escaped \n, \r or \t before the match.
+const B = String.raw`(?:(?<![A-Za-z0-9_])|(?<=\\[nrt]))`;
+const R = (src, flags = 'g') => new RegExp(B + src, flags);
+export const DETECTORS = [
+  { id: 'private-key', severity: 'error', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/g, what: 'a private key' },
+  { id: 'aws-access-key', severity: 'error', re: R(String.raw`(?:AKIA|ASIA)[0-9A-Z]{16}\b`), what: 'an AWS access key id' },
+  { id: 'github-token', severity: 'error', re: R(String.raw`(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})\b`), what: 'a GitHub token' },
+  { id: 'anthropic-key', severity: 'error', re: R(String.raw`sk-ant-[A-Za-z0-9_-]{20,}`), what: 'an Anthropic API key' },
+  { id: 'openai-key', severity: 'error', re: R(String.raw`sk-(?!ant-)(?:proj-|svcacct-)?[A-Za-z0-9_-]{20,}`), what: 'an OpenAI API key' },
+  { id: 'slack-token', severity: 'error', re: R(String.raw`xox[abprs]-[A-Za-z0-9-]{10,}`), what: 'a Slack token' },
+  { id: 'stripe-key', severity: 'error', re: R(String.raw`[sr]k_(?:live|test)_[A-Za-z0-9]{16,}\b`), what: 'a Stripe key' },
+  { id: 'google-api-key', severity: 'error', re: R(String.raw`AIza[0-9A-Za-z_-]{35}\b`), what: 'a Google API key' },
+  { id: 'npm-token', severity: 'error', re: R(String.raw`npm_[A-Za-z0-9]{36}\b`), what: 'an npm token' },
+  { id: 'sendgrid-key', severity: 'error', re: R(String.raw`SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b`), what: 'a SendGrid key' },
+  { id: 'db-url-password', severity: 'error', re: R(String.raw`(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis|rediss|amqp|amqps|mssql|clickhouse):\/\/[^\s:/@'"\\]+:[^\s@'"\\]{4,}@[^\s'"\\]+`), what: 'a database URL with its password' },
+  { id: 'basic-auth-url', severity: 'warn', re: R(String.raw`https?:\/\/[^\s:/@'"\\]+:[^\s@'"\\]{4,}@[^\s'"\\]+`), what: 'a URL with credentials in it' },
+  { id: 'jwt', severity: 'warn', re: R(String.raw`eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b`), what: 'a JWT' },
+  { id: 'generic-secret', severity: 'warn', re: R(String.raw`(?:(?:api[_-]?key|secret[_-]?key|client[_-]?secret|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|token|passwd|password|pwd)\b(?:\\?["']?\s*[:=]\s*\\?["']?)|bearer\s+)([A-Za-z0-9_\-/+=.]{16,})`, 'gi'), value: (m) => m[1], ok: (v) => !PLACEHOLDER.test(v) && /[0-9]/.test(v) && /[A-Za-z]/.test(v) && entropy(v) >= 3.5, what: 'a secret named by its context' },
+];
+export const ADVICE = {
+  'private-key': 'Generate a new key pair and remove the old public key everywhere it is authorised; then shred.',
+  'aws-access-key': 'Deactivate the key in IAM and issue a new one; check CloudTrail for use; then shred.',
+  'github-token': 'Revoke it under Settings → Developer settings; then shred.',
+  'anthropic-key': 'Revoke it in the Console and issue a new one; then shred.',
+  'openai-key': 'Revoke it in the dashboard and issue a new one; then shred.',
+  'slack-token': 'Revoke the token or reinstall the app; then shred.',
+  'stripe-key': 'Roll the key in the Stripe dashboard; then shred.',
+  'google-api-key': 'Regenerate the key in Google Cloud and restrict it; then shred.',
+  'npm-token': 'Revoke it on npmjs.com (Access Tokens); then shred.',
+  'sendgrid-key': 'Delete the key in SendGrid and create a new one; then shred.',
+  'db-url-password': 'Change the database password and update the app; then shred.',
+  'basic-auth-url': 'Change the password behind the URL; prefer a credential helper over a URL with the password in it; then shred.',
+  'jwt': 'Short-lived by design, but treat as live until it expires; shred.',
+  'generic-secret': 'Confirm what it is, rotate it, then shred. If it is not a secret, nothing to do.',
+  'credential-file-read': 'The file\'s contents are in the transcript. Rotate anything it held that the rules above did not name; shred what they did.',
+};
+
+// A line-start index so a match offset maps to a 1-based line number by binary search.
+function lineIndex(text) { const starts = [0]; for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) starts.push(i + 1); return starts; }
+function lineAt(starts, off) { let lo = 0, hi = starts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= off) lo = mid; else hi = mid - 1; } return lo + 1; }
+function lineText(text, starts, n) { const a = starts[n - 1], b = n < starts.length ? starts[n] - 1 : text.length; return text.slice(a, b).replace(/\r$/, ''); }
+
+// Where a hit sits: the record type and, for tool traffic, the tool (and the path for a Read).
+function locate(rec, tools) {
+  if (!rec || typeof rec !== 'object') return { where: 'other' };
+  const m = rec.message;
+  if (rec.type === 'assistant' && m && Array.isArray(m.content)) {
+    const tu = m.content.find((b) => b && b.type === 'tool_use');
+    if (tu) { tools.set(tu.id, { name: tu.name, path: core.filePathOf(tu), input: tu.input }); return { where: 'tool input', tool: tu.name, path: tools.get(tu.id).path || undefined }; }
+    return { where: 'assistant text' };
+  }
+  if (rec.type === 'user' && m) {
+    if (Array.isArray(m.content)) { const tr = m.content.find((b) => b && b.type === 'tool_result'); if (tr) { const t = tools.get(tr.tool_use_id); return { where: 'tool result', tool: t ? t.name : undefined, path: t && t.path || undefined }; } }
+    return { where: rec.isMeta || rec.isCompactSummary ? 'system' : 'user prompt' };
+  }
+  return { where: rec.type || 'other' };
+}
+
+// Credential-file reads: a Read of a credential file, or a Bash command that dumps one.
+function fileReadHit(rec) {
+  if (!rec || rec.type !== 'assistant' || !rec.message || !Array.isArray(rec.message.content)) return null;
+  const tu = rec.message.content.find((b) => b && b.type === 'tool_use'); if (!tu || !tu.input) return null;
+  const p = core.filePathOf(tu);
+  if (p && /^(Read|View|Cat|NotebookRead)$/i.test(tu.name) && isCredentialFile(p)) return { tool: tu.name, path: String(p) };
+  const cmd = typeof tu.input.command === 'string' ? tu.input.command : null;
+  if (cmd) { const m = cmd.match(DUMP_CMD); if (m && (m[1] === undefined ? true : isCredentialFile(m[1]))) return { tool: tu.name, path: m[1] || cmd.trim().slice(0, 60) }; }
+  return null;
+}
+
+// Scan raw transcript text. Returns hits in file order: { rule, severity, line, start, end, value, preview, fingerprint, where, tool?, path? }.
+export function scanText(text, opts = {}) {
+  const fp = (v) => fingerprint(v, opts.key);
+  const starts = lineIndex(text);
+  const hits = [];
+  const spans = []; // [start, end] of accepted hits, for overlap suppression
+  const overlaps = (a, b) => spans.some(([x, y]) => a < y && b > x);
+  for (const d of DETECTORS) {
+    d.re.lastIndex = 0; let m;
+    while ((m = d.re.exec(text))) {
+      const value = d.value ? d.value(m) : m[0];
+      const start = d.value ? m.index + m[0].length - value.length : m.index, end = start + value.length;
+      if (d.ok && !d.ok(value)) continue;
+      if (overlaps(start, end)) continue;
+      spans.push([start, end]);
+      hits.push({ rule: d.id, severity: d.severity, start, end, value, preview: mask(value), fingerprint: fp(value), line: lineAt(starts, start) });
+    }
+  }
+  hits.sort((a, b) => a.start - b.start);
+  // Attribution needs the record; parse each line once, and walk every line for tool_use ids (results come after calls)
+  // and for credential-file reads.
+  const tools = new Map(); const parsed = new Map(); const fileReads = [];
+  const hitLines = new Set(hits.map((h) => h.line));
+  for (let n = 1; n <= starts.length; n++) {
+    const raw = lineText(text, starts, n); if (!raw.trim()) continue;
+    let rec = null; try { rec = JSON.parse(raw); } catch (e) { continue; }
+    const fr = fileReadHit(rec);
+    if (fr) fileReads.push({ rule: 'credential-file-read', severity: 'info', line: n, start: starts[n - 1], end: starts[n - 1], value: null, preview: fr.path, fingerprint: fp(fr.path), where: 'tool input', tool: fr.tool, path: fr.path });
+    const loc = locate(rec, tools);
+    if (hitLines.has(n)) parsed.set(n, loc);
+  }
+  for (const h of hits) Object.assign(h, opts.where ? { where: opts.where } : parsed.get(h.line) || { where: 'other' });
+  return hits.concat(fileReads).sort((a, b) => a.start - b.start || SEV[a.severity] - SEV[b.severity]);
+}
+
+// Same value in the same place collapses to one finding with a count. Values are kept on the object (for shred)
+// but never serialised: `toJSON` drops them.
+function rows(hits) {
+  const map = new Map();
+  for (const h of hits) {
+    const k = [h.rule, h.fingerprint, h.where, h.tool || '', h.path || ''].join('|');
+    if (map.has(k)) { const r = map.get(k); r.count++; r.spans.push([h.start, h.end]); continue; }
+    map.set(k, Object.defineProperties({ rule: h.rule, severity: h.severity, where: h.where, tool: h.tool, path: h.path, line: h.line, preview: h.preview, fingerprint: h.fingerprint, count: 1 }, {
+      value: { value: h.value, enumerable: false }, spans: { value: h.value == null ? [] : [[h.start, h.end]], enumerable: false },
+    }));
+  }
+  return [...map.values()];
+}
+
+export function scanFile(file, meta = {}) {
+  const buf = fs.readFileSync(file);
+  if (meta.store && isBinary(buf)) return { file, bytes: buf.length, skipped: 'binary file', findings: [] };
+  const text = buf.toString('utf8');
+  const hits = scanText(text, { key: meta.key, where: meta.where });
+  const findings = rows(meta.store ? hits.filter((h) => h.rule !== 'credential-file-read') : hits).map((r) => Object.assign(r, {
+    file, session: meta.store ? meta.session || undefined : meta.session || path.basename(file).replace(/\.jsonl$/, ''), project: meta.project || undefined, store: meta.store || undefined }));
+  return { file, bytes: buf.length, lines: text.split('\n').length, findings, text, raw: buf };
+}
+
+// Rewrite every hit in place. `replacer(finding)` gives the replacement text; the default contains no quote,
+// backslash or control character so a JSON string stays a JSON string. Every changed line is parsed again before
+// anything is written; on failure the file is left as it was.
+export function shredFile(file, findings, opts = {}) {
+  const replacer = opts.replacer || ((f) => `[FENCED:${f.rule}:${f.fingerprint}]`);
+  const raw = opts.raw || fs.readFileSync(file);
+  const text = opts.text != null ? opts.text : raw.toString('utf8');
+  const json = opts.json != null ? opts.json : /\.jsonl$/i.test(file);
+  const spans = [];
+  for (const f of findings) for (const [s, e] of (f.spans || [])) spans.push({ s, e, rep: replacer(f) });
+  if (!spans.length) return { written: false, values: 0, reason: 'nothing to shred' };
+  if (!Buffer.from(text, 'utf8').equals(raw)) return { written: false, values: spans.length, reason: 'not plain UTF-8 text; nothing written' };
+  spans.sort((a, b) => a.s - b.s);
+  let out = '', pos = 0;
+  for (const sp of spans) { if (sp.s < pos) continue; out += text.slice(pos, sp.s) + sp.rep; pos = sp.e; }
+  out += text.slice(pos);
+  const before = text.split('\n'), after = out.split('\n');
+  if (before.length !== after.length) return { written: false, values: spans.length, reason: 'line count changed; nothing written' };
+  if (json) for (let i = 0; i < after.length; i++) { if (after[i] === before[i]) continue; const l = after[i].replace(/\r$/, ''); if (!l.trim()) continue; try { JSON.parse(l); } catch (e) { return { written: false, values: spans.length, reason: `line ${i + 1} would not parse after the rewrite; nothing written` }; } }
+  const tmp = file + '.glassbox-shred~';
+  const mode = fs.statSync(file).mode & 0o777;
+  fs.writeFileSync(tmp, out, { mode }); fs.renameSync(tmp, file);
+  return { written: true, values: spans.length };
+}
+
+// Which files to scan. opts: { home, target, since (ms epoch), project, sessionsOnly }.
+export function targets(opts = {}) {
+  const home = opts.home || claudeHome();
+  const list = [];
+  const add = (file, session, project) => list.push({ file, session, project });
+  const addSession = (s) => { add(s.file, s.id, s.project); for (const f of subagentFiles(s)) add(f.path, s.id, s.project); };
+  const t = opts.target;
+  if (!t) {
+    for (const s of findSessions({ home, project: opts.project })) if (opts.since == null || s.mtime >= opts.since) addSession(s);
+    const res = { list, mode: 'home', home };
+    if (opts.sessionsOnly) return res;
+    if (opts.project) { res.storesNote = 'prompt history, paste cache, file history, debug logs and shell snapshots are not scanned with --project (they are not kept per project)'; return res; }
+    res.stores = {};
+    const recent = (p) => opts.since == null || fs.statSync(p).mtimeMs >= opts.since;
+    for (const st of STORES) {
+      const found = [];
+      if (st.file) { const p = path.join(home, st.file); if (fs.existsSync(p) && fs.statSync(p).isFile() && recent(p)) found.push({ p, rel: st.file }); }
+      else {
+        const root = path.join(home, st.dir);
+        const walk = (dir) => { let ents; try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; } for (const e of ents.sort((a, b) => a.name.localeCompare(b.name))) { const p = path.join(dir, e.name); if (e.isDirectory()) walk(p); else if (e.isFile() && recent(p)) found.push({ p, rel: path.relative(root, p) }); } };
+        walk(root);
+      }
+      for (const f of found) list.push({ file: f.p, store: st.id, where: st.where, session: st.session ? st.session(f.rel) : null });
+      if (found.length) res.stores[st.id] = found.length;
+    }
+    return res;
+  }
+  if (fs.existsSync(t) && fs.statSync(t).isDirectory()) {
+    const walk = (dir) => { for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) { const p = path.join(dir, e.name); if (e.isDirectory()) walk(p); else if (e.isFile() && /\.jsonl$/i.test(e.name) && e.name !== 'journal.jsonl' && (opts.since == null || fs.statSync(p).mtimeMs >= opts.since)) add(p, e.name.replace(/\.jsonl$/i, ''), null); } };
+    walk(path.resolve(t)); return { list, mode: 'dir', dir: path.resolve(t) };
+  }
+  const s = resolveTarget(t, { home }); addSession(s); return { list, mode: s.project == null ? 'file' : 'session', home };
+}
+
+// The report. opts as `targets` plus { shred }.
+export function fence(opts = {}) {
+  const tg = targets(opts);
+  const home = opts.home || claudeHome();
+  const keyFile = opts.keyFile ? path.resolve(opts.keyFile) : defaultKeyFile(home);
+  const key = opts.keyFile ? loadKey(keyFile) : ensureKey(keyFile);
+  const files = [], findings = [], skipped = []; let bytes = 0; const sessions = new Set();
+  const shredded = { files: 0, values: 0, refused: [] };
+  for (const t of tg.list) {
+    if (t.store && fs.statSync(t.file).size > STORE_MAX_BYTES) { skipped.push({ file: t.file, reason: `larger than ${STORE_MAX_BYTES / 1048576} MB` }); continue; }
+    let r; try { r = scanFile(t.file, { session: t.session, project: t.project, store: t.store, where: t.where, key }); } catch (e) { shredded.refused.push({ file: t.file, reason: e.message }); continue; }
+    if (r.skipped) { skipped.push({ file: t.file, reason: r.skipped }); continue; }
+    files.push({ file: t.file, session: t.session || undefined, store: t.store, bytes: r.bytes, findings: r.findings.length });
+    bytes += r.bytes; if (!t.store) sessions.add(t.session);
+    findings.push(...r.findings);
+    if (opts.shred) { const s = shredFile(t.file, r.findings, { text: r.text, raw: r.raw }); if (s.written) { shredded.files++; shredded.values += s.values; } else if (s.reason !== 'nothing to shred') shredded.refused.push({ file: t.file, reason: s.reason }); }
+  }
+  findings.sort((a, b) => SEV[a.severity] - SEV[b.severity] || a.file.localeCompare(b.file) || a.line - b.line);
+  // Files actually scanned per store (skipped ones are listed under scanned.skipped); undefined when stores were not in scope.
+  let storeCounts; if (tg.stores) { storeCounts = {}; for (const st of STORES) { const n = files.filter((f) => f.store === st.id).length; if (n) storeCounts[st.id] = n; } }
+  const bySeverity = { error: 0, warn: 0, info: 0 }; for (const f of findings) bySeverity[f.severity]++;
+  const byRule = {}; for (const f of findings) byRule[f.rule] = (byRule[f.rule] || 0) + f.count;
+  const secretMap = new Map();
+  for (const f of findings) { if (f.rule === 'credential-file-read') continue; const k = f.fingerprint; if (!secretMap.has(k)) secretMap.set(k, { fingerprint: k, rule: f.rule, severity: f.severity, preview: f.preview, sessions: new Set(), files: new Set(), occurrences: 0, advice: ADVICE[f.rule] }); const s = secretMap.get(k); if (f.session && !f.store) s.sessions.add(f.session); s.files.add(f.file); s.occurrences += f.count; }
+  const secrets = [...secretMap.values()].map((s) => Object.assign(s, { sessions: s.sessions.size, files: s.files.size })).sort((a, b) => SEV[a.severity] - SEV[b.severity] || b.sessions - a.sessions || b.occurrences - a.occurrences);
+  const rep = { glassbox: core.VERSION, kind: 'fence', schema: 2, generated: new Date().toISOString(), mode: tg.mode, home: tg.home, dir: tg.dir, since: opts.since ? new Date(opts.since).toISOString() : undefined,
+    fingerprint: { alg: 'hmac-sha256', chars: 8, key: keyFile },
+    scanned: { files: files.length, sessions: sessions.size, bytes, stores: storeCounts, storesNote: tg.storesNote, skipped },
+    summary: { bySeverity, byRule, filesWithFindings: files.filter((f) => f.findings).length, distinctSecrets: secrets.length, secrets },
+    findings, files };
+  if (opts.shred) rep.shredded = shredded;
+  return rep;
+}
+
+export function failedAt(rep, failOn = 'error') { if (!(failOn in SEV)) throw new Error(`--fail-on must be error, warn or info (got "${failOn}")`); return rep.findings.some((f) => SEV[f.severity] <= SEV[failOn]); }
+
+const STORE_WORDS = { history: 'prompt history', 'paste-cache': 'paste cache', 'file-history': 'file history', debug: 'debug logs', 'shell-snapshots': 'shell snapshots' };
+const storeLine = (stores) => { const n = Object.values(stores).reduce((a, b) => a + b, 0); return `${n} other Claude Code file${n === 1 ? '' : 's'} (${Object.keys(stores).map((k) => STORE_WORDS[k] || k).join(', ')})`; };
+const fmtBytes = (n) => n >= 1048576 ? (n / 1048576).toFixed(1) + ' MB' : n >= 1024 ? Math.round(n / 1024) + ' KB' : n + ' B';
+const place = (f) => `${f.where}${f.tool ? ' · ' + f.tool : ''}${f.path && f.rule !== 'credential-file-read' ? ' ' + f.path : ''}`;
+
+export function fenceText(rep) {
+  const L = [];
+  const what = rep.mode === 'home' ? `${rep.scanned.sessions} session${rep.scanned.sessions === 1 ? '' : 's'} under ${path.join(rep.home, 'projects')}` : rep.mode === 'dir' ? `${rep.scanned.files} file${rep.scanned.files === 1 ? '' : 's'} under ${rep.dir}` : `${rep.scanned.files} file${rep.scanned.files === 1 ? '' : 's'}`;
+  const s = rep.summary.bySeverity;
+  const nStore = rep.scanned.stores ? Object.values(rep.scanned.stores).reduce((a, b) => a + b, 0) : 0;
+  L.push(`Glassbox fence · ${what}${nStore ? ` + ${storeLine(rep.scanned.stores)}` : ''} · ${fmtBytes(rep.scanned.bytes)}${rep.since ? ` · since ${rep.since.slice(0, 10)}` : ''}`);
+  if (rep.scanned.storesNote) L.push(`  (${rep.scanned.storesNote})`);
+  if (!rep.findings.length) { L.push('  nothing found — no known credential formats, no secrets named by context, no credential-file reads'); }
+  else {
+    L.push(`  ${s.error} error · ${s.warn} warn · ${s.info} info · ${rep.summary.distinctSecrets} distinct secret${rep.summary.distinctSecrets === 1 ? '' : 's'} in ${rep.summary.filesWithFindings} of ${rep.scanned.files} files`, '');
+    let last = null;
+    for (const f of rep.findings) {
+      if (f.file !== last) { L.push(`  ${f.file}${f.session && !f.file.includes(f.session) ? `  (session ${f.session.slice(0, 8)})` : ''}`); last = f.file; }
+      L.push(`    ${f.severity.toUpperCase().padEnd(5)} ${f.rule.padEnd(21)} line ${String(f.line).padStart(6)}  ${f.preview}${f.count > 1 ? `  ×${f.count}` : ''}  — ${place(f)}`);
+    }
+    L.push('', '  Secrets, by how far they spread:');
+    for (const x of rep.summary.secrets.slice(0, 20)) L.push(`    ${x.severity.toUpperCase().padEnd(5)} ${x.rule.padEnd(21)} ${x.fingerprint}  ${x.preview}  in ${x.sessions} session${x.sessions === 1 ? '' : 's'}, ${x.occurrences} place${x.occurrences === 1 ? '' : 's'}`);
+    L.push('', '  A secret that reached a transcript reached a disk: rotate it, then run again with --shred to overwrite it in place.');
+  }
+  if (rep.scanned.skipped && rep.scanned.skipped.length) L.push(`  skipped ${rep.scanned.skipped.length} file${rep.scanned.skipped.length === 1 ? '' : 's'} (binary or too large)`);
+  L.push(`  fingerprints: HMAC-SHA256 under ${rep.fingerprint.key} (keep that file on this machine)`);
+  if (rep.shredded) { L.push('', `  Shredded ${rep.shredded.values} value${rep.shredded.values === 1 ? '' : 's'} in ${rep.shredded.files} file${rep.shredded.files === 1 ? '' : 's'} (each is now [FENCED:<rule>:<fingerprint>]; no backup was kept).`); for (const r of rep.shredded.refused) L.push(`  refused ${r.file}: ${r.reason}`); }
+  return L.join('\n') + '\n';
+}
+
+export function fenceMarkdown(rep) {
+  const L = [`# Glassbox fence — ${rep.generated.slice(0, 10)}`, '', `Scanned ${rep.scanned.files} file${rep.scanned.files === 1 ? '' : 's'} (${rep.scanned.sessions} session${rep.scanned.sessions === 1 ? '' : 's'}${rep.scanned.stores && Object.keys(rep.scanned.stores).length ? ` + ${storeLine(rep.scanned.stores)}` : ''}, ${fmtBytes(rep.scanned.bytes)})${rep.since ? ` written since ${rep.since.slice(0, 10)}` : ''}. Previews are masked and fingerprints are the first 8 hex of HMAC-SHA256 under a key kept on this machine; this report holds no secret values.`, ''];
+  if (rep.scanned.storesNote) L.push(`_${rep.scanned.storesNote}._`, '');
+  const s = rep.summary.bySeverity;
+  if (!rep.findings.length) { L.push('**Nothing found.** No known credential formats, no secrets named by context, no credential-file reads.'); return L.join('\n') + '\n'; }
+  L.push(`**${s.error} error · ${s.warn} warn · ${s.info} info** — ${rep.summary.distinctSecrets} distinct secret${rep.summary.distinctSecrets === 1 ? '' : 's'} in ${rep.summary.filesWithFindings} of ${rep.scanned.files} files.`, '');
+  L.push('## Secrets, by how far they spread', '', '| severity | rule | fingerprint | preview | sessions | places | do |', '|---|---|---|---|---:|---:|---|');
+  for (const x of rep.summary.secrets) L.push(`| ${x.severity} | \`${x.rule}\` | \`${x.fingerprint}\` | ${x.preview} | ${x.sessions} | ${x.occurrences} | ${x.advice} |`);
+  L.push('', '## Where, file by file', '');
+  const byFile = new Map(); for (const f of rep.findings) { if (!byFile.has(f.file)) byFile.set(f.file, []); byFile.get(f.file).push(f); }
+  for (const [file, list] of byFile) {
+    L.push(`### ${file}`, '', list[0].store ? `${STORE_WORDS[list[0].store] || list[0].store}${list[0].session ? ` · session \`${list[0].session}\`` : ''}` : `session \`${list[0].session}\`${list[0].project ? ` · project ${list[0].project}` : ''}`, '', '| rule | severity | line | preview | where |', '|---|---|---:|---|---|');
+    for (const f of list) L.push(`| \`${f.rule}\` | ${f.severity} | ${f.line} | ${f.preview}${f.count > 1 ? ` ×${f.count}` : ''} | ${place(f)} |`);
+    L.push('');
+  }
+  L.push('## What to do', '', 'A secret that reached a transcript reached a disk, and whatever backs that disk up. Rotate each one above, then run `glassbox fence --shred` to overwrite the values in place with `[FENCED:<rule>:<fingerprint>]`. Shredded transcripts still open and check.', '');
+  if (rep.scanned.skipped && rep.scanned.skipped.length) L.push(`Skipped ${rep.scanned.skipped.length} file${rep.scanned.skipped.length === 1 ? '' : 's'} (binary or too large).`, '');
+  if (rep.shredded) { L.push(`Shredded ${rep.shredded.values} value${rep.shredded.values === 1 ? '' : 's'} in ${rep.shredded.files} file${rep.shredded.files === 1 ? '' : 's'}; no backup was kept.`); for (const r of rep.shredded.refused) L.push(`- refused ${r.file}: ${r.reason}`); L.push(''); }
+  return L.join('\n');
+}

package/src/guard.mjs

@@ -0,0 +1,96 @@
+// Glassbox guard — a PreToolUse hook that stops the one loop worth stopping live: the agent is
+// about to make a call that has already failed, unchanged, twice in a row this turn.
+//
+// Deliberately narrow, so it doesn't get in the way:
+//  - only failures count (denied-by-the-human and interrupted calls don't; they have their own flow);
+//  - the chain is broken by anything that could have changed the outcome: an edit, another command,
+//    any non-read call, a success, or a new human prompt. Re-running tests after a fix is never blocked;
+//  - calls are compared on what they do, not how they're labelled: Bash/PowerShell `description`,
+//    `timeout` and `run_in_background` are ignored, because the agent often rewords them on a retry.
+// It never approves anything: when it has nothing to say it prints nothing, which leaves Claude Code's
+// normal permission flow in charge ("allow" would skip the user's permission prompts).
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const core = require('./trace-core.js');
+
+export const GUARD_DEFAULTS = { maxFailures: 2, tailBytes: 4 * 1048576 };
+const IGNORED_KEYS = new Set(['description', 'timeout', 'run_in_background']);
+
+export function guardKey(name, input) {
+  const i = {};
+  for (const [k, v] of Object.entries(input || {})) if (!IGNORED_KEYS.has(k)) i[k] = v;
+  return name + '|' + core.stableStringify(i);
+}
+
+// The last few MB of a transcript: the current turn is at the end, and a PreToolUse hook runs before
+// every tool call, so it must not parse a 20 MB session each time.
+function readTail(file, bytes) {
+  const size = fs.statSync(file).size;
+  const start = Math.max(0, size - bytes);
+  const fd = fs.openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(size - start); fs.readSync(fd, buf, 0, buf.length, start);
+    let text = buf.toString('utf8');
+    if (start > 0) text = text.slice(text.indexOf('\n') + 1); // drop the partial first line
+    return text;
+  } finally { fs.closeSync(fd); }
+}
+
+function isHumanPrompt(rec) {
+  if (rec.type !== 'user' || rec.isMeta || rec.isCompactSummary) return false;
+  const c = rec.message && rec.message.content;
+  if (Array.isArray(c) && c.some((b) => b && b.type === 'tool_result')) return false;
+  const text = core.textOf(c).trim();
+  return !!text && !/^<(system-reminder|local-command|command-name|bash-input|bash-stdout)/.test(text) && !/^\[Request interrupted by user/.test(text);
+}
+
+// Returns null (say nothing) or the PreToolUse deny reply.
+export function guardResponse(input, opts = {}) {
+  const o = Object.assign({}, GUARD_DEFAULTS, opts);
+  if (!input || !input.tool_name) return null;
+  const file = input.agent_transcript_path || input.transcript_path;
+  if (!file || !fs.existsSync(file)) return null;
+  const text = readTail(file, o.tailBytes);
+  if (!/"is_error":\s*true/.test(text)) return null; // nothing has failed recently: the common case, and fast
+
+  const agent = input.agent_id || null;
+  const calls = []; const results = new Map(); let turnStart = 0;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let rec; try { rec = JSON.parse(line); } catch (e) { continue; }
+    if ((rec.agentId || null) !== agent && !(agent && input.agent_transcript_path)) continue; // other agents' records in a shared file
+    if (isHumanPrompt(rec)) { turnStart = calls.length; continue; }
+    const content = rec.message && Array.isArray(rec.message.content) ? rec.message.content : [];
+    if (rec.type === 'assistant') for (const b of content) if (b && b.type === 'tool_use') calls.push({ id: b.id, name: b.name, key: guardKey(b.name, b.input) });
+    if (rec.type === 'user') for (const b of content) if (b && b.type === 'tool_result') {
+      const t = core.textOf(b.content);
+      results.set(b.tool_use_id, { isError: !!b.is_error, text: t, denial: b.is_error ? core.denialKind(rec, t) : null });
+    }
+  }
+
+  const target = guardKey(input.tool_name, input.tool_input);
+  let failures = 0, lastError = null;
+  for (let i = calls.length - 1; i >= turnStart; i--) {
+    const c = calls[i];
+    if (c.id === input.tool_use_id) continue; // the call being decided may already be in the transcript
+    const r = results.get(c.id);
+    if (!r) continue; // still running (a parallel call): no outcome yet
+    if (c.key === target) {
+      if (!r.isError || r.denial) break; // it worked last time, or a person stopped it: not a loop
+      failures++; if (lastError == null) lastError = r.text;
+      continue;
+    }
+    if (core.toolCategory(c.name) === 'read') continue; // looking around changes nothing
+    break; // an edit, another command, any action: the outcome may be different now
+  }
+  if (failures < o.maxFailures) return null;
+  const err = String(lastError || '').split('\n').map((l) => l.trim()).find(Boolean) || 'no error text';
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: `Glassbox guard: this exact ${input.tool_name} call has already failed ${failures} times in a row this turn, with nothing changed in between. Last error: ${err.slice(0, 300)}\nDon't repeat it unchanged. Read the error, then change the input, fix what it depends on, try a different approach, or ask the user. A call that differs, or comes after an edit or another command, is not blocked.`,
+    },
+  };
+}

package/src/trace-core.js

@@ -9,7 +9,7 @@
 })(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict';
 
-  const VERSION = '0.7.1';
+  const VERSION = '0.9.1';
 
   // ---------------------------------------------------------------------------
   // Rate card (USD per million tokens). Prefix-matched against model ids so dated
@@ -1176,5 +1176,5 @@
   }
   function toJsonl(records) { return records.map((r) => JSON.stringify(r)).join('\n') + '\n'; }
 
-  return { VERSION, RATES, DEFAULTS, ADVICE, METRICS, parseLines, parseTrace, diagnose, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, fmtMetric, fmtRatio, fmtChange, stableStringify, inputSummary, adviceFor, redactDetail, reportMarkdown, compare, compareMarkdown, toolTable, fileStats, filePathOf, normalisePath };
+  return { VERSION, RATES, DEFAULTS, ADVICE, METRICS, parseLines, parseTrace, diagnose, denialKind, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, fmtMetric, fmtRatio, fmtChange, stableStringify, inputSummary, adviceFor, redactDetail, reportMarkdown, compare, compareMarkdown, toolTable, fileStats, filePathOf, normalisePath };
 });