glassbox-trace 0.9.0 → 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).
@@ -94,6 +99,8 @@ 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
 ```
 
 ```
@@ -106,7 +113,7 @@ Glassbox fence · 34 sessions under /home/aldo/.claude/projects · 212 MB
     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 SHA-256) — enough to know which key it is and to see the same key across sessions, never enough to use it. `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).
+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`
 
@@ -180,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)
@@ -215,3 +223,7 @@ Your context is private — by construction, not by promise.
 - **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.9.0';
+  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,6 +1,6 @@
 {
   "name": "glassbox-trace",
-  "version": "0.9.0",
+  "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": {

package/src/adhere.mjs

@@ -30,9 +30,31 @@ const ACTION = (w) => /^commit/i.test(w) ? 'commit' : /^push/i.test(w) ? 'push'
 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(/\.$/, ''); };
 
-// Each matcher returns the rule's parameters or null. Order matters: first match wins.
+// 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) => { let m = s.match(/\b(?:ask(?:\s+me)?|check with me|confirm(?:\s+with me)?|get (?:my )?(?:permission|approval|ok))\s*(?:first\s+)?(?:before|prior to)\s+(?:you\s+)?(?:\w+ing\s+)?(commit|push|delet|remov|install|creat|deploy|merg)\w*/i) || s.match(/\b(?:ask(?:\s+me)?|check with me)\s+before\s+(?:you\s+)?(commit|push|delet|remov|install|creat|deploy|merg)\w*/i); if (m) return { action: ACTION(m[1]) }; m = s.match(/\b(?:never|don't|do not|don’t)\s+(commit|push|delete|remove|install|deploy|merge)\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 { action: ACTION(m[1]) }; return null; } },
+  { 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; } },
@@ -58,10 +80,11 @@ export function parseRules(text, file) {
     const parts = body.split(/(?<=[.!])\s+(?=[A-Z`])/);
     for (const part of parts) {
       const s = part.trim(); if (!s) continue;
-      let hit = null;
-      for (const sh of SHAPES) { const p = sh.m(s); if (p) { hit = Object.assign({ kind: sh.kind }, p); break; } }
+      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 (hit) rules.push(Object.assign(rec, hit)); else unchecked.push(rec);
+      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 };
@@ -215,7 +238,8 @@ export function adhere(opts = {}) {
     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) }));
-    const row = { id: r.id, file: r.file, line: r.line, text: r.text, kind: r.kind, occasions: occ.length, obeyed, broken, rate, verdict, examples, sessionsBroken: new Set(occ.filter((o) => !o.obeyed).map((o) => o.session)).size };
+    // 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;
@@ -239,7 +263,7 @@ export function adhereText(rep) {
   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.kind.padEnd(17)} ${r.occasions ? `${r.obeyed}/${r.occasions} ${pct(r.rate).padStart(4)}` : '   —      '}  ${r.text}  (${r.file}:${r.line})`);
+    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})`); }
@@ -252,9 +276,9 @@ export function adhereMarkdown(rep) {
   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.kind}\` | ${r.occasions} | ${r.obeyed} | ${r.broken} | ${pct(r.rate)} | ${r.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.kind}\` · ${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 (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', 'claude-md', 'fail-under'].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,10 +366,11 @@ 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
@@ -367,7 +381,7 @@ export const HELP = `glassbox — other tools show you what happened in a Claude
                                  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]
+  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
@@ -520,13 +534,14 @@ 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') {
@@ -535,7 +550,7 @@ export async function main(argv, io = {}) {
       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 });
+      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` : ''})`); }

package/src/fence.mjs

@@ -5,6 +5,10 @@
 // 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';
@@ -23,7 +27,36 @@ const DUMP_CMD = /(?:^|[;&|]\s*)(?:cat|type|less|more|head|tail|Get-Content|gc)\
 
 // 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; }
-export const fingerprint = (v) => crypto.createHash('sha256').update(v).digest('hex').slice(0, 8);
+// 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
@@ -100,7 +133,8 @@ function fileReadHit(rec) {
 }
 
 // Scan raw transcript text. Returns hits in file order: { rule, severity, line, start, end, value, preview, fingerprint, where, tool?, path? }.
-export function scanText(text) {
+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
@@ -113,7 +147,7 @@ export function scanText(text) {
       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: fingerprint(value), line: lineAt(starts, start) });
+      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);
@@ -125,11 +159,11 @@ export function scanText(text) {
     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: fingerprint(fr.path), where: 'tool input', tool: fr.tool, path: fr.path });
+    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, parsed.get(h.line) || { where: 'other' });
+  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]);
 }
 
@@ -148,9 +182,13 @@ function rows(hits) {
 }
 
 export function scanFile(file, meta = {}) {
-  const text = fs.readFileSync(file, 'utf8');
-  const findings = rows(scanText(text)).map((r) => Object.assign(r, { file, session: meta.session || path.basename(file).replace(/\.jsonl$/, ''), project: meta.project || undefined }));
-  return { file, bytes: Buffer.byteLength(text), lines: text.split('\n').length, findings, text };
+  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,
@@ -158,30 +196,53 @@ export function scanFile(file, meta = {}) {
 // 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 text = opts.text != null ? opts.text : fs.readFileSync(file, 'utf8');
+  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' };
-  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` }; } }
+  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~';
-  fs.writeFileSync(tmp, out); fs.renameSync(tmp, file);
+  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, shred }.
+// 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); return { list, mode: 'home', home }; }
+  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) };
@@ -192,23 +253,31 @@ export function targets(opts = {}) {
 // The report. opts as `targets` plus { shred }.
 export function fence(opts = {}) {
   const tg = targets(opts);
-  const files = [], findings = []; let bytes = 0; const sessions = new Set();
+  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) {
-    let r; try { r = scanFile(t.file, { session: t.session, project: t.project }); } catch (e) { shredded.refused.push({ file: t.file, reason: e.message }); continue; }
-    files.push({ file: t.file, session: t.session, bytes: r.bytes, findings: r.findings.length });
-    bytes += r.bytes; sessions.add(t.session);
+    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 }); 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 }); }
+    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); s.sessions.add(f.session); s.files.add(f.file); s.occurrences += f.count; }
+  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: 1, generated: new Date().toISOString(), mode: tg.mode, home: tg.home, dir: tg.dir, since: opts.since ? new Date(opts.since).toISOString() : undefined,
-    scanned: { files: files.length, sessions: sessions.size, bytes },
+  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;
@@ -217,6 +286,8 @@ export function fence(opts = {}) {
 
 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 : ''}`;
 
@@ -224,7 +295,9 @@ 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;
-  L.push(`Glassbox fence · ${what} · ${fmtBytes(rep.scanned.bytes)}${rep.since ? ` · since ${rep.since.slice(0, 10)}` : ''}`);
+  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`, '');
@@ -237,12 +310,15 @@ export function fenceText(rep) {
     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'}, ${fmtBytes(rep.scanned.bytes)})${rep.since ? ` written since ${rep.since.slice(0, 10)}` : ''}. Previews are masked and fingerprints are the first 8 hex of SHA-256; this report holds no secret values.`, ''];
+  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.`, '');
@@ -251,11 +327,12 @@ export function fenceMarkdown(rep) {
   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}`, '', `session \`${list[0].session}\`${list[0].project ? ` · project ${list[0].project}` : ''}`, '', '| rule | severity | line | preview | where |', '|---|---|---:|---|---|');
+    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.9.0';
+  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 };
 });