agent-polygraph 0.1.0 → 0.2.0

package/README.md

@@ -4,18 +4,18 @@
 
 Your coding agent said "all tests pass". Did a test pass after its last edit?
 
-agent-polygraph reads the Claude Code and Codex session logs already on your machine and checks every "tests pass" claim against what ran. No setup, no API key, nothing uploaded.
+agent-polygraph is an audit of your past sessions. It reads the Claude Code and Codex session logs already on your machine and checks every "tests pass" claim against what ran: was there a passing test run after the agent's last code edit? It tells you how often your agents claimed something they hadn't verified, and shows the evidence for each case. No setup, no API key, nothing uploaded.
+
+The audit and guard **read evidence; they do not execute tests**. A flagged claim is not proof the code is wrong: it means the available evidence does not support the claim at that point. If you want automatic test execution, use a separate test-running hook or CI.
 
 ```sh
 npx agent-polygraph          # your own sessions
 npx agent-polygraph --demo   # generated sample sessions
 ```
 
-<img src="docs/guard.gif" alt="guard stops a coding agent that claims tests pass without rerunning them" width="760">
-
-> This is a beta. It has been tested on my own logs and on public Claude Code sessions ([evaluation](docs/evaluation.md)). If a verdict looks wrong, please [open an issue](https://github.com/EleChon-pixel/agent-polygraph/issues/new/choose) with the redacted example from the report. Each one becomes a regression test.
+> **Beta / evidence limitations:** The parser has been evaluated on the author's own sessions and public Claude Code traces ([evaluation](docs/evaluation.md)). Controlled replays and real executed tests exist, but **independent, blinded human-validated accuracy has not been established**. If you report a wrong verdict, [open an issue](https://github.com/EleChon-pixel/agent-polygraph/issues/new/choose) with a *manually redacted* example—never upload an unreviewed raw session log.
 
-My own sessions, July to October 2026:
+Historical example from the author's sessions, July–October 2026 (not a representative benchmark or a current-user measurement):
 
 ```
 agent-polygraph  32 working sessions · Jul 30 – Oct 31, 2026 · 11.0s
@@ -45,6 +45,10 @@ Where the time went
 
 Under the tables it prints the latest examples: what the agent claimed, the last test command and its result, what was edited afterwards, and the session file, so you can check it yourself.
 
+**What the benchmarks actually show:** agent-polygraph detects stale test claims more reliably than a *simple any-prior-pass rule* in [25 authored replay scenarios](docs/benchmark.md) (14/14 unbacked claims versus 7/14). In [12 instrumented projects using real test executions](docs/live-evaluation.md), its selective guard requested **5** additional tests and detected **3 of 7** failing final suites; rerunning the full suite every time required **12** additional tests and detected **all 7**. That is an efficiency-versus-coverage trade-off, **not** evidence that the guard improves overall defect detection. [Public-session workload projections](docs/benchmark.md) are separate from actual executed tests. The independently labeled human study is [still open](https://github.com/EleChon-pixel/agent-polygraph/issues/3).
+
+**npm release status:** The [public npm registry](https://www.npmjs.com/package/agent-polygraph) still serves **0.1.0**, while GitHub `main` contains the security-hardened **0.2.0 release candidate**. The automated tarball test passes, but new npm code will not be available to `npx` until it has been published. For the exact manual publishing procedure (GitHub OIDC trusted publisher), see [Release instructions](docs/releasing.md).
+
 ## Share your numbers
 
 ```sh
@@ -55,7 +59,7 @@ This writes `polygraph.html`, a self-contained card with numbers only. Prompts,
 
 <img src="docs/card.png" alt="agent-polygraph report card from my own sessions" width="600">
 
-## Stop unbacked claims as they happen
+## Catch unbacked claims as they happen (optional)
 
 ```sh
 npx agent-polygraph guard --install            # this project (.claude/settings.json, .codex/hooks.json)
@@ -63,13 +67,38 @@ npx agent-polygraph guard --install --global   # every project (~/.claude, ~/.co
 npx agent-polygraph guard --uninstall
 ```
 
+<img src="docs/guard.gif" alt="staged demo: guard stops a coding agent that claims tests pass after editing code, and the rerun fails" width="760">
+
 `guard` is a Stop hook that runs the same checks on the live session. When the agent's final message says tests pass and the session doesn't back it up, the agent is sent back once:
 
 > agent-polygraph: your final message says "All tests pass.", but you edited calc.js after the last test run. Run the relevant tests now and report the actual result. If they can't be run, say so instead of claiming they pass.
 
 It blocks at most once per stop, looks only at the final message (so a claim the agent already corrected doesn't count), stays quiet when it can't tell, and never fails the turn because of its own errors. Install it globally (`npm i -g agent-polygraph`) so the hook doesn't start `npx` on every stop.
 
-I tested it with both agents by having them edit code after a test run and then claim the tests pass. Both were stopped, reran `npm test` and reported the failure. Codex needs one extra step: it only runs hooks you have approved, and only reads a project's `.codex/` folder if you trust it. After installing, open `codex` in the project once, trust the folder and approve the hook.
+I tested it with both agents in a staged setup: they were told to edit code after a test run and then claim the tests pass (the GIF above is one of these runs). Both were stopped, reran `npm test` and reported the failure. Codex needs one extra step: it only runs hooks you have approved, and only reads a project's `.codex/` folder if you trust it. After installing, open `codex` in the project once, trust the folder and approve the hook.
+
+### Do you need it?
+
+Maybe not. Two simpler setups also work, and they are more thorough:
+
+- A Stop hook that runs your test suite after every turn and gives the agent the result. This also catches breakage when the agent doesn't claim anything.
+- A Stop hook that always asks the agent to double-check its results. When I tried this on small tasks where the agent had edited code after its last run, it reran the tests every time (6 of 6, Claude Haiku).
+
+The trade-off is cost. Both fire on every stop, so every turn ends with a test run, and the second also adds a model turn, even when nothing changed or nothing was claimed. A test-running hook also has to know each project's test command and setup (a virtualenv, environment variables, a subfolder, a database). `guard` runs nothing: it reads the session in well under a second and only sends the agent back when the final message claims a pass that no run after the last edit supports (about 6% of claims in my logs), naming the edit that made the run stale.
+
+If your suite runs in a few seconds and needs no setup, running it on every stop is the better choice. `guard` is for suites that are slow or fiddly to run, and for when you don't want an extra turn on every stop.
+
+### As a Claude Code plugin
+
+In Claude Code you can install the guard as a plugin instead:
+
+```
+/plugin install agent-polygraph --marketplace EleChon-pixel/agent-polygraph
+```
+
+On Claude Code older than 2.1.275, run `/plugin marketplace add EleChon-pixel/agent-polygraph` first, then `/plugin install agent-polygraph@agent-polygraph`.
+
+The plugin runs the same Stop hook from its own copy, so nothing is downloaded when the agent stops, and it adds `/agent-polygraph:check` for the report (it takes the same options, for example `/agent-polygraph:check --since 30d`). If you also installed the hook with `guard --install`, the plugin's copy stays quiet so the agent isn't sent back twice. The plugin doesn't include `record`; turn that on separately if you want it.
 
 ## Evidence the logs don't have
 
@@ -77,13 +106,13 @@ Some things never show up in the logs: tests you ran yourself in another termina
 
 ```sh
 npx agent-polygraph record --install           # this project; add --global for all of them
-npx agent-polygraph record --install --shell   # your own terminals
+agent-polygraph record --install --shell       # your own terminals (requires a persistent install)
 npx agent-polygraph --ci                       # GitHub Actions (online)
 ```
 
-`record --install` adds a PostToolUse hook to Claude Code and Codex. After a test command, or a command that may write files, it saves a snapshot of the working tree and the test runner's full result. The snapshot is a git tree built with a temporary index and a separate object store, so your repository, its index and its history are never touched. Ignored files are left out. If the logs can't tell whether a script changed your code after the last test run, the two snapshots answer it, and a changed source file is named in the report. Everything stays in `~/.agent-polygraph` (or `$AGENT_POLYGRAPH_HOME`). It applies to sessions started after you install it.
+`record --install` adds a PostToolUse hook to Claude Code and Codex. After a test or a command that may write files, it records the test outcome and an HMAC-fingerprinted source snapshot. The snapshot reads bounded source files without writing copies to Git or storing raw contents. Ignored and non-source files are excluded; symlinks, unreadable files and exceeded size limits make a snapshot inconclusive. Comparing snapshots can resolve scripts that modify dynamically chosen source files. All new records stay in `~/.agent-polygraph` (or `$AGENT_POLYGRAPH_HOME`). Recording starts with new sessions.
 
-`record --install --shell` adds one line to `~/.bashrc` and `~/.zshrc`. From then on, test commands you run in an interactive bash or zsh terminal are logged with their folder, start and end time and exit code. Output is never saved. If you ran the tests yourself in the session's folder after the agent's last edit, that run counts for the agent's claim. `record --uninstall --shell` removes the line.
+`record --install --shell` adds one line to `~/.bashrc` and `~/.zshrc`. Supported test commands you run in interactive Bash/Zsh shells produce a minimal receipt: runner category, working directory, timestamps and exit code. Raw commands and output are never saved. To avoid unsafe shell redirection, the shell hook invokes the installed Node CLI, which validates and writes the receipt with private permissions and no-follow checks. **Use a persistent installation** (`npm i -g agent-polygraph` or a durable checkout) for shell integration; temporary `npx` cache paths may disappear. Shell mode recognizes a conservative subset of direct test commands. `record --uninstall --shell` removes its startup line.
 
 `--ci` goes online. Through your [`gh`](https://cli.github.com) login, it asks the GitHub API for the workflow runs of the repositories your sessions pushed to. The request contains the repository name and a date range, nothing from your sessions. A test workflow on a pushed commit counts as a test run of the code as it was at the push, so later edits still make it stale. Runs are matched to pushes by commit id, which has to appear in the session (in the push output, or from `git commit` or `git log` before it). Branch names and timing alone are not enough. With `--ci`, claims about CI itself ("CI is green", "all checks on the PR pass") are checked too. Workflows with no job or step named like a test, and runs GitHub never started, are ignored.
 
@@ -126,25 +155,29 @@ Everything is deterministic pattern matching over the logs. There is no LLM invo
 
 The rules are in [`src/classify.js`](src/classify.js) and the tests in [`test/`](test), including a labelled set of claim and non-claim sentences ([`test/claims.corpus.test.js`](test/claims.corpus.test.js)). A false positive or a missed claim makes a good [issue](https://github.com/EleChon-pixel/agent-polygraph/issues/new/choose); include the redacted sentence and it goes into that set.
 
-## Accuracy
+## Validation and accuracy
+
+The historical analysis of the author's own Claude Code and Codex sessions includes manual spot checks of claims and flagged evidence. In a small, author-selected review, approximately 95% of 25 detected claim candidates were genuine claims, and a separate sample suggested some real claims were missed. **These are preliminary, author-reviewed observations, not externally validated precision or recall.** See the [original evaluation protocol](docs/evaluation.md).
 
-I checked it by hand on my own logs, several hundred claims across Claude Code and Codex. Of 25 detected claims picked at random, about 95% were real claims. About 10% of real claims are missed, judging by a sample of sentences that mention tests passing but weren't detected; most of those also mention an unrelated failure ("passes alone, failed in the full run"). I traced every flag back through its session. Almost all were real unbacked claims, and the rest were borderline partial claims.
+The public Claude Code evaluation reviewed 26 parsed sessions and identified 24 backed claims and three stale findings (one confirmed and two considered likely). It is useful for parser regression coverage but does **not** establish accuracy on an independent, representative population. A separately pinned, redacted holdout audit inspected 103 public sessions; under its conservative automated reference rules, **no eligible claims were found**, so **no holdout accuracy percentage was produced**. Additional dataset limitations and exact counts are documented in [live-evaluation.md](docs/live-evaluation.md).
 
-On other people's sessions (26 public Claude Code sessions, mostly from [Trace Commons](https://huggingface.co/datasets/trace-commons/agent-traces)) every verdict was reviewed by hand. The first run found parser gaps, such as Windows PowerShell sessions, custom test runners and Gradle, which are now fixed. The result is 89% backed. All 24 backed verdicts match the output the agent saw, and of the 3 stale flags, 1 is confirmed and 2 are likely. [docs/evaluation.md](docs/evaluation.md) has the method, every fix and a one-command reproduction.
+Two reproducible controlled experiments test narrower propositions:
 
-An outside review found ten ways a verdict could go wrong (a later result backing an earlier claim, one output shared by several commands, failed edits counted as changes). They are fixed and kept as tests in [`test/review.test.js`](test/review.test.js).
+- [Stop-hook replay](docs/benchmark.md): 25 authored Claude Code/Codex scenarios. Agent-polygraph correctly blocked 14/14 labeled unbacked claims versus 7/14 for a naive “any test passed earlier” hook, with zero false blocks in these selected cases.
+- [Executed-test policy comparison](docs/live-evaluation.md): 12 authored scenarios with actual Node.js test executions. The selective guard required five extra test executions and detected three of seven failing final suites; running the full suite after every response required 12 executions and detected all seven.
 
-There was no public Codex data, so Codex has only been checked on my logs. Your phrasing and tools will differ from mine. Treat the numbers as a strong hint, and open the session file before relying on any one verdict.
+The replay labels and scenarios were constructed by the project authors. The guard cannot discover failures the agent never claimed away, or infer whether a narrow passing test establishes a full-suite pass. **An independent, blinded human evaluation is still needed.** The [review issue](https://github.com/EleChon-pixel/agent-polygraph/issues/3) describes the protocol; `scripts/blind-review.mjs` prepares prediction-free review packets. No raw private session logs should be shared with reviewers or issues without permission and redaction.
 
 ## Limits
 
-These are the gaps that remain. `record` and `--ci` close most of them once you turn them on.
+These are the gaps that remain. `record` and `--ci` can reduce some of them, but neither replaces running tests or provides independent proof of correctness.
 
 - Tests outside the logs. Tests the agent ran, test runs Claude Code recorded from hooks, commands you typed with `!` in Claude Code, and test output you pasted into the chat all count. So do your own bash and zsh runs with `record --shell`, and GitHub Actions runs on pushed commits with `--ci`. Other shells (fish, PowerShell, an IDE's test button), other CI services, and CI runs on commits the session never printed are still invisible.
 - "The full suite passes" is compared with the latest run about as large as the largest one in that folder, using the counts the runner printed. If no run printed a count, it's compared with the latest run, which may have been narrower. Claims that name no count, test file or full suite are compared with the latest run.
-- Output with no summary. Codex keeps each command's full output. Claude Code saves output that is too long for the transcript to a file, which is read as long as it exists, and `record` keeps the full result too. A run abandoned before printing a result leaves nothing to read.
+- Output with no summary. Codex keeps each command's full output. Claude Code may save long output to a separate file that the analyzer reads if it still exists. New `record` entries retain **parsed test outcomes and pass counts, not raw test output**. A run abandoned before printing a result leaves nothing to read.
 - Files a script names at run time. Without `record` these make a claim "couldn't tell", never "backed". `record` settles them, but only in git checkouts and only for sessions after it was installed.
 - New agent versions can change the log format. Supported: Claude Code 2.x (Bash and PowerShell tools; Linux, macOS and Windows paths) and Codex CLI. The report lists the versions it read, warns about newer ones, and counts files it couldn't parse instead of dropping them silently.
+- Unbacked is not the same as false. "Code edited after the last run" means the claim wasn't verified after the edit; the edit may have been harmless, such as a comment or a test file. The report can't tell whether the tests would have passed, because nobody ran them at that point.
 - The numbers describe your sessions, projects and prompts. They are not a benchmark of the models.
 
 ## Options
@@ -163,9 +196,31 @@ These are the gaps that remain. `record` and `--ci` close most of them once you
 --codex-dir <dir>   Codex sessions dir (default ~/.codex/sessions, or $CODEX_HOME/sessions)
 ```
 
+## Running the repository version
+
+The GitHub source and the npm-distributed package are different delivery paths. To try the **current `main` code** without assuming npm is up to date:
+
+```sh
+git clone https://github.com/EleChon-pixel/agent-polygraph.git
+cd agent-polygraph
+node bin/polygraph.js --demo
+npm test
+npm run benchmark:replay
+npm run benchmark:live
+```
+
+Before distributing a new version, verify `npm view agent-polygraph version`, the published tarball (`npm pack --dry-run`), and that a clean install really contains the latest privacy and guard fixes. The repository declares version `0.2.0` as the **next release candidate**; until it is published, `npx agent-polygraph` still installs the older public registry version. A green GitHub Actions badge does **not** prove npm has been updated.
+
 ## Privacy
 
-It reads files and works offline. The exceptions are all opt-in:
+New recordings intentionally minimize local data. The agent hook stores a keyed command fingerprint, the runner's result and optional fingerprints of source files. It does **not** save raw command text, test output or copies of repository files in its snapshot store. The shell integration saves only a recognized test-runner category, time, folder and exit code. Local record files, key and snapshot metadata are owner-only on Unix. Hook settings and shell startup files are replaced atomically, preserving their permissions and creating private recovery backups under `~/.agent-polygraph/backups` (see [recovery](docs/releasing.md#recovery-for-installed-hooks)). The secret fingerprint key is stored in `$AGENT_POLYGRAPH_HOME/record-key` (default `~/.agent-polygraph/record-key`).
+
+**Existing installations:** records made before this update may still include full commands, and older versions may have created a local Git object store with duplicate source contents. Upgrading does **not** remove those files. After reviewing whether you still need the historical evidence, uninstall recording and manually remove the old `~/.agent-polygraph/records` and `~/.agent-polygraph/objects` directories. Removing historical records means those sessions will lose their supplemental evidence; the original Claude Code/Codex transcripts remain untouched. Do not delete `record-key` while retaining version 2 records that rely on matching fingerprints.
+
+Stored fingerprints are **not** a guarantee of anonymity: recording metadata includes timestamps, working directories and relative source-file paths, and existing v1 records may still contain raw commands. The original Claude Code/Codex transcripts can also contain secrets and confidential data. The terminal report and `--json` may quote transcript text and paths; do not share them without review. The `--html` report intentionally excludes excerpts, prompts, commands and paths. The recorder only supports bounded source-file snapshots in Git checkouts and skips symbolic links; when evidence cannot be read it must stay inconclusive rather than certifying a pass. New source-file fingerprints include relative filenames and are not an anonymization guarantee.
+
+
+It reads files and works offline. These operations are opt-in:
 
 - `guard` and `record` edit the hook config files they print when you install or uninstall them, and `record --shell` adds or removes one marked line in `~/.bashrc` and `~/.zshrc`.
 - `record` saves snapshots and logs in `~/.agent-polygraph`.

package/bin/polygraph.js

@@ -67,11 +67,18 @@ async function record(argv) {
       uninstall: { type: "boolean" },
       global: { type: "boolean" },
       shell: { type: "boolean" },
+      "shell-event": { type: "boolean" },
       agent: { type: "string", multiple: true },
       command: { type: "string" },
     },
   });
   const rec = await import("../src/record.js");
+  if (values["shell-event"]) {
+    const chunks = [];
+    for await (const piece of process.stdin) chunks.push(piece);
+    rec.runShellRecord(Buffer.concat(chunks).toString("utf8"));
+    return;
+  }
   if (!values.install && !values.uninstall) {
     // invoked by the agent as a PostToolUse hook: quiet, and never in the way
     const chunks = [];
@@ -86,10 +93,14 @@ async function record(argv) {
   for (const r of hooks) {
     const verb = values.install ? (r.changed ? "added PostToolUse hook to" : "already installed in") : r.changed ? "removed PostToolUse hook from" : "nothing to remove in";
     console.log(`${r.agent === "claude" ? "Claude Code" : "Codex"}: ${verb} ${r.file}`);
+    if (r.backup) console.log(`  Recovery backup: ${r.backup}`);
   }
   if (values.shell) {
     const out = values.install ? rec.installShell() : rec.uninstallShell();
-    for (const r of out.rcs) console.log(`Shell: ${values.install ? (r.changed ? "added a line to" : "already in") : "removed the line from"} ${r.file}`);
+    for (const r of out.rcs) {
+      console.log(`Shell: ${values.install ? (r.changed ? "added a line to" : "already in") : "removed the line from"} ${r.file}`);
+      if (r.backup) console.log(`  Recovery backup: ${r.backup}`);
+    }
     if (values.install) console.log(`Shell: ${out.rcs.length ? "open a new terminal to start logging" : "no ~/.bashrc or ~/.zshrc found; source " + out.script + " from your shell's startup file"}. Only interactive bash and zsh are supported.`);
   }
   if (values.install) {
@@ -111,6 +122,7 @@ async function guard(argv) {
       global: { type: "boolean" },
       agent: { type: "string", multiple: true },
       command: { type: "string" },
+      "from-plugin": { type: "boolean" },
     },
   });
   const { runHook, install, uninstall } = await import("../src/guard.js");
@@ -119,7 +131,7 @@ async function guard(argv) {
     try {
       const chunks = [];
       for await (const c of process.stdin) chunks.push(c);
-      const out = await runHook(Buffer.concat(chunks).toString("utf8"));
+      const out = await runHook(Buffer.concat(chunks).toString("utf8"), { plugin: values["from-plugin"] });
       if (out) process.stdout.write(JSON.stringify(out));
     } catch (e) {
       if (process.env.POLYGRAPH_DEBUG) console.error(e);
@@ -131,6 +143,7 @@ async function guard(argv) {
   for (const r of results) {
     const verb = values.install ? (r.changed ? "added Stop hook to" : "already installed in") : r.changed ? "removed Stop hook from" : "nothing to remove in";
     console.log(`${r.agent === "claude" ? "Claude Code" : "Codex"}: ${verb} ${r.file}`);
+    if (r.backup) console.log(`  Recovery backup: ${r.backup}`);
   }
   if (values.install) {
     console.log(`\nHook command: ${results[0].command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-polygraph",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Check your coding agents' \"tests pass\" claims against what actually ran. Reads Claude Code and Codex session logs locally.",
   "type": "module",
   "bin": {
@@ -14,8 +14,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test 'test/*.test.js'",
-    "start": "node bin/polygraph.js"
+    "test": "node --test",
+    "start": "node bin/polygraph.js",
+    "benchmark:demo": "node scripts/benchmark.mjs --demo",
+    "benchmark:replay": "node scripts/benchmark-guard-replay.mjs",
+    "benchmark:live": "node scripts/benchmark-live.mjs"
   },
   "engines": {
     "node": ">=18.3"

package/src/analyze.js

@@ -1,4 +1,5 @@
 import os from "node:os";
+import fs from "node:fs";
 import path from "node:path";
 import {
   isTestCommand,
@@ -211,7 +212,7 @@ export function analyzeSession(session) {
   /** Files that differ between two `record` snapshots of one checkout, or null if unknown. */
   const snapshotDiff = (a, b) => {
     if (!a || !b || !session.treeDiff || a.root !== b.root) return null;
-    if (a.tree === b.tree) return [];
+    if (a.tree && b.tree && a.tree === b.tree) return [];
     try {
       const out = session.treeDiff(a, b);
       return Array.isArray(out) ? out : null;
@@ -364,7 +365,16 @@ export function analyzeSession(session) {
             uncertain = false;
             s.evidence.snapshot = (s.evidence.snapshot || 0) + 1;
             // the whole checkout is compared; only changes where the test ran count, as for edits
-            const code = changed.filter((p) => isCodePath(p) && !SCRATCH_NAME.test(p.split("/").pop()) && within(path.posix.join(norm(ref.tree.root), p), ref.dir));
+            // Git may report the canonical checkout path even when the transcript
+            // used a symlinked directory (/var vs /private/var on macOS), and
+            // Windows requires native path joining for drive-letter roots.
+            const canonical = (p) => {
+              try { return fs.realpathSync.native(p); } catch { return p; }
+            };
+            const canonicalRoot = canonical(ref.tree.root);
+            const canonicalDir = canonical(ref.dir || session.cwd || ref.tree.root);
+            const code = changed.filter((p) => isCodePath(p) && !SCRATCH_NAME.test(p.split("/").pop()) &&
+              within(path.resolve(canonicalRoot, ...p.split("/")), canonicalDir));
             if (code.length) staleEdit = { path: code[0], snapshot: true };
           }
         }

package/src/guard.js

@@ -11,10 +11,11 @@ import * as codex from "./sources/codex.js";
 import { analyzeSession } from "./analyze.js";
 import { findTestClaim, findTestClaims } from "./classify.js";
 import { applyRecords } from "./record.js";
+import { readSettings, writeSettings } from "./safe-config.js";
 
 
 /** Hook entry point: read the Stop payload on stdin, maybe print a block decision. */
-export async function runHook(stdinText) {
+export async function runHook(stdinText, { plugin = false } = {}) {
   let payload;
   try {
     payload = JSON.parse(stdinText || "{}");
@@ -22,6 +23,9 @@ export async function runHook(stdinText) {
     return null;
   }
   if (payload.stop_hook_active) return null; // we already sent the agent back once
+  // The Claude Code plugin's hook steps aside when `guard --install` put one in settings
+  // too, so the agent isn't sent back twice with the same message.
+  if (plugin && settingsHasGuard(payload.cwd)) return null;
   const transcript = payload.transcript_path;
   if (!transcript || !fs.existsSync(transcript)) return null;
 
@@ -81,6 +85,23 @@ function reasonFor(d) {
   ].join(" ");
 }
 
+/** Is a guard hook installed in Claude Code settings that apply to `cwd` (user or project)? */
+export function settingsHasGuard(cwd, home = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude")) {
+  const files = [path.join(home, "settings.json"), path.join(home, "settings.local.json")];
+  // Claude Code reads project settings from where it was started, which may be above cwd
+  for (let d = cwd ? path.resolve(cwd) : null; d; d = path.dirname(d) === d ? null : path.dirname(d)) {
+    files.push(path.join(d, ".claude", "settings.json"), path.join(d, ".claude", "settings.local.json"));
+  }
+  return files.some((file) => {
+    try {
+      const stop = JSON.parse(fs.readFileSync(file, "utf8")).hooks?.Stop;
+      return Array.isArray(stop) && stop.some((g) => (g.hooks || []).some((h) => isOurHook(h, "guard")));
+    } catch {
+      return false;
+    }
+  });
+}
+
 function sniffCodex(file) {
   try {
     const fd = fs.openSync(file, "r");
@@ -180,7 +201,8 @@ export function install(opts) {
     }
     if (changed) {
       fs.mkdirSync(path.dirname(file), { recursive: true });
-      fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+      const save = writeSettings(file, JSON.stringify(config, null, 2) + "\n");
+      return { agent, file, changed, command, backup: save.backup };
     }
     return { agent, file, changed, command };
   });
@@ -201,14 +223,16 @@ export function uninstall(opts) {
     if (kept.length) config.hooks[event] = kept;
     else delete config.hooks[event];
     if (!Object.keys(config.hooks).length) delete config.hooks;
-    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
-    return { agent, file, changed: true };
+    const save = writeSettings(file, JSON.stringify(config, null, 2) + "\n");
+    return { agent, file, changed: true, backup: save.backup };
   });
 }
 
 function readJson(file) {
   try {
-    return JSON.parse(fs.readFileSync(file, "utf8"));
+    const { text } = readSettings(file);
+    if (text === null) return {};
+    return JSON.parse(text);
   } catch (e) {
     if (e.code === "ENOENT") return {};
     throw new Error(`${file} is not valid JSON; fix or remove it first (${e.message})`);

package/src/record.js

@@ -1,11 +1,9 @@
 // `agent-polygraph record`: optional evidence the session logs don't carry.
 //
-// - A PostToolUse hook (Claude Code and Codex). After a test command or a command that may
-//   write files, it saves a snapshot of the working tree (a git tree id, stored in
-//   agent-polygraph's own object store so your repository is never written to) and, for
-//   test commands, the outcome the runner printed in full. With snapshots, a change the
-//   logs can't follow ("a script that computes its file names") is settled by comparing the
-//   tree after the test run with the tree before the claim.
+// - A PostToolUse hook (Claude Code and Codex). After a test or potential write,
+//   it records bounded, keyed source-file fingerprints and test outcomes.
+//   It does not store raw commands, test output, source contents or Git objects.
+//   Comparing snapshots can resolve changes not identifiable from shell text.
 // - Shell integration (bash, zsh): test commands you run in your own terminals are logged
 //   with their folder, start and end time and exit code. No output is kept.
 //
@@ -15,14 +13,112 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { readSettings, writeSettings } from "./safe-config.js";
 import { execFileSync } from "node:child_process";
-import { isTestCommand, mayWriteFiles, shellWrites, outcomeFromOutput, passedCount } from "./classify.js";
+import { isTestCommand, isCodePath, mayWriteFiles, shellWrites, outcomeFromOutput, passedCount } from "./classify.js";
 
 export const home = () => process.env.AGENT_POLYGRAPH_HOME || path.join(os.homedir(), ".agent-polygraph");
 const hash = (s) => crypto.createHash("sha1").update(String(s)).digest("hex").slice(0, 16);
 export const recordsFile = (transcript) => path.join(home(), "records", hash(path.resolve(transcript)) + ".jsonl");
 export const terminalFile = () => path.join(home(), "records", "terminal.jsonl");
 
+// Refuse redirected or shared record paths. These files are local evidence,
+// not a place to follow arbitrary symlinks or overwrite somebody else's files.
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+function verifyPrivateFile(fd, file = null) {
+  const st = fs.fstatSync(fd);
+  if (file && process.platform === "win32") {
+    // Windows lacks O_NOFOLLOW; inspect the entry and opened file before I/O.
+    const entry = fs.lstatSync(file);
+    if (entry.isSymbolicLink() || !entry.isFile() || entry.dev !== st.dev || entry.ino !== st.ino)
+      throw new Error("Unsafe linked record file: " + file);
+  }
+  if (!st.isFile() || st.nlink !== 1) throw new Error("Unsafe record file (not regular or multiply linked)");
+  if (process.platform !== "win32") {
+    if (st.uid !== process.getuid()) throw new Error("Record file belongs to another user");
+    fs.fchmodSync(fd, 0o600);
+  }
+}
+function secureDirectory(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // Act on the opened directory, not on a pathname that may be replaced
+  // with a symlink between an lstat() check and chmod().
+  const entry = fs.lstatSync(dir);
+  if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error("Unsafe linked record directory");
+  const fd = fs.openSync(dir, fs.constants.O_RDONLY | (fs.constants.O_DIRECTORY || 0) | NOFOLLOW);
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isDirectory()) throw new Error("Unsafe record directory");
+    if (process.platform === "win32" && fs.lstatSync(dir).isSymbolicLink())
+      throw new Error("Unsafe linked record directory");
+    if (process.platform !== "win32") {
+      if (st.uid !== process.getuid()) throw new Error("Record directory belongs to another user");
+      fs.fchmodSync(fd, 0o700);
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function secureWrite(file, data, append = false) {
+  secureDirectory(path.dirname(file));
+  // Never truncate before validating an existing file. O_NOFOLLOW rejects final
+  // symlinks, and nlink/owner checks reject hard links and unrelated files.
+  try {
+    const entry = fs.lstatSync(file);
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Unsafe linked record file: " + file);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  const fd = fs.openSync(file, fs.constants.O_CREAT | fs.constants.O_WRONLY | (append ? fs.constants.O_APPEND : 0) | NOFOLLOW, 0o600);
+  try {
+    verifyPrivateFile(fd, file);
+    if (!append) fs.ftruncateSync(fd, 0);
+    fs.writeSync(fd, data);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// The key stays on the local machine. A keyed digest lets us correlate commands
+// without ever persisting their text (which may contain tokens/passwords).
+let keyCache;
+let keyCachePath;
+function localKey() {
+  const file = path.join(home(), "record-key");
+  if (keyCachePath === file && keyCache) return keyCache;
+  secureDirectory(home());
+  let key;
+  const readKey = () => {
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+    try {
+      verifyPrivateFile(fd, file);
+      return fs.readFileSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  };
+  try {
+    key = readKey();
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    const candidate = crypto.randomBytes(32);
+    try {
+      const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, 0o600);
+      try { verifyPrivateFile(fd, file); fs.writeSync(fd, candidate); } finally { fs.closeSync(fd); }
+      key = candidate;
+    } catch (race) {
+      if (race.code !== "EEXIST") throw race;
+      key = readKey();
+    }
+  }
+  if (key.length !== 32) throw new Error("Invalid agent-polygraph local record key");
+  keyCache = key;
+  keyCachePath = file;
+  return key;
+}
+export const commandFingerprint = (cmd) => crypto.createHmac("sha256", localKey()).update(String(cmd)).digest("hex");
+
 // --- the hook --------------------------------------------------------------------------
 
 /** PostToolUse entry point. Never throws, never prints: a recorder must not get in the way. */
@@ -34,7 +130,7 @@ export function runRecordHook(stdinText) {
     const test = isTestCommand(cmd);
     if (!test && !mayWriteFiles(cmd) && !shellWrites(cmd).unresolved) return;
     const cwd = p.cwd || process.cwd();
-    const rec = { v: 1, ts: Date.now(), id: p.tool_use_id || null, tool: p.tool_name || null, cmd, cwd };
+    const rec = { v: 2, ts: Date.now(), id: p.tool_use_id || null, tool: p.tool_name || null, cmdKey: commandFingerprint(cmd), cwd };
     try {
       rec.tree = snapshot(cwd);
     } catch {}
@@ -47,8 +143,7 @@ export function runRecordHook(stdinText) {
     }
     if (!rec.tree && !rec.outcome) return;
     const file = recordsFile(p.transcript_path);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.appendFileSync(file, JSON.stringify(rec) + "\n");
+    secureWrite(file, JSON.stringify(rec) + "\n", true);
   } catch {}
 }
 
@@ -69,46 +164,90 @@ function outputOf(r) {
   return parts.filter((x) => typeof x === "string").join("\n");
 }
 
-// --- working-tree snapshots ---------------------------------------------------------------
+// --- working-tree fingerprints -------------------------------------------------------------
 
-/**
- * The working tree as a git tree id, untracked files included, ignored files left out.
- * Built with a temporary index and a private object store (the repository's own objects
- * are read through git's alternates), so nothing in the repository changes.
- */
-export function snapshot(cwd) {
-  const git = (args, env = {}, dir = cwd) =>
-    execFileSync("git", args, { cwd: dir, env: { ...process.env, ...env }, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 8000, maxBuffer: 8 << 20 }).trim();
-  const root = git(["rev-parse", "--show-toplevel"]);
-  const [index, objects] = git(["rev-parse", "--git-path", "index", "--git-path", "objects"])
-    .split("\n")
-    .map((p) => path.resolve(cwd, p));
-  const store = path.join(home(), "objects", hash(objects));
-  fs.mkdirSync(store, { recursive: true });
-  const tmp = path.join(os.tmpdir(), `agent-polygraph-${process.pid}-${Date.now()}.index`);
+// No git objects or copies of source files are written. Snapshots contain
+// bounded HMACs, which cannot be used as a substitute for the source contents.
+const MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+const MAX_SNAPSHOT_BYTES = 64 * 1024 * 1024;
+const MAX_SNAPSHOT_FILES = 10000;
+
+function safeParents(root, relative) {
+  let parent = root;
+  for (const part of relative.split(/[\\/]/).slice(0, -1)) {
+    if (!part || part === "." || part === "..") return false;
+    parent = path.join(parent, part);
+    const st = fs.lstatSync(parent);
+    if (!st.isDirectory() || st.isSymbolicLink()) return false;
+  }
+  return true;
+}
+
+function sourceFingerprint(root, name, key) {
+  const file = path.join(root, name);
+  // Refuse symlinks in the path. Open the leaf with O_NOFOLLOW too: a symlink
+  // substitution between lstat and open must not make us read its target.
+  if (path.isAbsolute(name) || name.split(/[\\/]/).includes("..") || !safeParents(root, name)) return null;
+  const initial = fs.lstatSync(file, { bigint: true });
+  if (!initial.isFile() || initial.nlink !== 1n || initial.size > BigInt(MAX_SOURCE_BYTES)) return null;
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
   try {
-    // starting from the real index keeps git's stat cache: only changed files are hashed
-    if (fs.existsSync(index)) fs.copyFileSync(index, tmp);
-    const env = { GIT_INDEX_FILE: tmp, GIT_OBJECT_DIRECTORY: store, GIT_ALTERNATE_OBJECT_DIRECTORIES: objects };
-    git(["add", "-A", "--ignore-errors", "--", "."], env, root);
-    const tree = git(["write-tree"], env, root);
-    return { root, tree, objects, store };
+    const before = fs.fstatSync(fd, { bigint: true });
+    if (!before.isFile() || before.dev !== initial.dev || before.ino !== initial.ino ||
+        before.nlink !== 1n || before.size > BigInt(MAX_SOURCE_BYTES)) return null;
+    const bytes = fs.readFileSync(fd);
+    const after = fs.fstatSync(fd, { bigint: true });
+    if (before.size !== after.size || before.mtimeNs !== after.mtimeNs ||
+        before.ctimeNs !== after.ctimeNs || bytes.length !== Number(before.size)) return null;
+    // A path replacement during the read must remain inconclusive.
+    const current = fs.lstatSync(file, { bigint: true });
+    if (!current.isFile() || current.dev !== after.dev || current.ino !== after.ino ||
+        current.mtimeNs !== after.mtimeNs || current.ctimeNs !== after.ctimeNs) return null;
+    // Linux exposes the opened descriptor's actual path. Reject a race that
+    // redirected a parent directory outside the checkout after safeParents().
+    if (process.platform === "linux") {
+      const opened = fs.realpathSync(`/proc/self/fd/${fd}`);
+      const relative = path.relative(fs.realpathSync(root), opened);
+      if (relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) return null;
+    }
+    return { bytes: bytes.length, digest: crypto.createHmac("sha256", key).update(bytes).digest("hex") };
   } finally {
-    fs.rmSync(tmp, { force: true });
+    fs.closeSync(fd);
   }
 }
 
-/** Paths (relative to the checkout) that differ between two snapshots of it. */
-export function treeDiff(a, b) {
-  const gitDir = path.dirname(a.objects);
-  const out = execFileSync("git", ["diff", "--name-only", "-z", "--no-renames", a.tree, b.tree], {
-    env: { ...process.env, GIT_DIR: gitDir, GIT_OBJECT_DIRECTORY: a.store, GIT_ALTERNATE_OBJECT_DIRECTORIES: [a.objects, b.store].join(path.delimiter) },
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"],
-    timeout: 10000,
-    maxBuffer: 16 << 20,
+export function snapshot(cwd) {
+  const git = (args, options = {}) => execFileSync("git", args, {
+    cwd, encoding: options.encoding ?? "utf8", stdio: ["ignore", "pipe", "ignore"],
+    timeout: 8000, maxBuffer: 16 << 20,
   });
-  return out.split("\0").filter(Boolean);
+  const root = git(["rev-parse", "--show-toplevel"]).trim();
+  const files = Object.create(null);
+  const paths = git(["ls-files", "--cached", "--others", "--exclude-standard", "-z"], { encoding: "buffer" }).toString("utf8").split("\0").filter(Boolean);
+  const key = localKey();
+  let complete = true;
+  let total = 0;
+  let count = 0;
+  for (const name of paths) {
+    if (!isCodePath(name)) continue;
+    if (++count > MAX_SNAPSHOT_FILES) { complete = false; break; }
+    try {
+      const data = sourceFingerprint(root, name, key);
+      if (!data) { complete = false; continue; }
+      if (total + data.bytes > MAX_SNAPSHOT_BYTES) { complete = false; break; }
+      total += data.bytes;
+      files[name] = data.digest;
+    } catch {
+      complete = false;
+    }
+  }
+  return { root, files, complete };
+}
+
+export function treeDiff(a, b) {
+  if (!a || !b || a.root !== b.root || !a.complete || !b.complete) return null;
+  const names = new Set([...Object.keys(a.files), ...Object.keys(b.files)]);
+  return [...names].filter((name) => a.files[name] !== b.files[name]);
 }
 
 // --- using the records -----------------------------------------------------------------------
@@ -127,11 +266,12 @@ export function applyRecords(session, { terminal = loadTerminal() } = {}) {
   if (recs.length) {
     session.treeDiff = treeDiff;
     // a record belongs to the command with the same text, recorded after it started
-    const free = recs.map((r) => ({ ...r, key: squash(r.cmd) }));
+    const free = recs.map((r) => ({ ...r, key: r.cmdKey || (r.cmd ? squash(r.cmd) : null) }));
     for (const ev of session.events) {
       if (ev.kind !== "cmd" || ev.external) continue;
-      const key = squash(ev.cmd);
-      const k = free.findIndex((r) => r && (ev.id && r.id ? r.id === ev.id : r.key === key && r.ts >= (ev.ts ?? 0) - 2000));
+      const key = commandFingerprint(ev.cmd);
+      const legacyKey = squash(ev.cmd);
+      const k = free.findIndex((r) => r && (ev.id && r.id ? r.id === ev.id : r.key != null && r.key === (r.cmdKey ? key : legacyKey) && r.ts >= (ev.ts ?? 0) - 2000));
       if (k < 0) continue;
       const r = free[k];
       free[k] = null;
@@ -154,6 +294,24 @@ export function loadTerminal() {
   return terminalCache;
 }
 
+// Shell hook receipts use the same no-follow, owner-only writer as agent hooks.
+// Accept an allowlisted category, never an arbitrary command or untrusted output.
+const SHELL_RUNNERS = new Set(["pytest", "npm test", "node --test", "go test", "cargo test", "mvn test", "gradle test", "dotnet test", "vitest run"]);
+export function runShellRecord(input) {
+  try {
+    const r = JSON.parse(input);
+    if (!SHELL_RUNNERS.has(r.runner) || !isTestCommand(r.runner)) return false;
+    if (!Number.isFinite(r.start) || !Number.isFinite(r.end) || r.end < r.start ||
+        !Number.isInteger(r.exit) || typeof r.cwd !== "string" ||
+        !path.isAbsolute(r.cwd) || r.cwd.length > 4096) return false;
+    const rec = { v: 2, kind: "terminal", start: r.start, end: r.end, exit: r.exit, cwd: r.cwd, runner: r.runner };
+    secureWrite(terminalFile(), JSON.stringify(rec) + "\n", true);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function addTerminalRuns(session, runs) {
   if (!runs.length || !session.cwd || session.start == null || session.end == null) return;
   const cwd = slash(session.cwd);
@@ -165,8 +323,9 @@ function addTerminalRuns(session, runs) {
   for (const r of runs) {
     const start = Math.round(r.start * 1000);
     const end = Math.round((r.end ?? r.start) * 1000);
-    if (!(start >= session.start && start <= session.end) || !r.cwd || !related(r.cwd) || !isTestCommand(r.cmd)) continue;
-    const ev = { kind: "cmd", ts: start, seq: Number.MAX_SAFE_INTEGER, cmd: r.cmd, workdir: r.cwd, external: "terminal", sub: false };
+    const runner = r.runner || r.cmd; // legacy raw-command records are still readable
+    if (!(start >= session.start && start <= session.end) || !r.cwd || !related(r.cwd) || !runner || !isTestCommand(runner)) continue;
+    const ev = { kind: "cmd", ts: start, seq: Number.MAX_SAFE_INTEGER, cmd: runner, workdir: r.cwd, external: "terminal", sub: false };
     session.events.push(ev, { kind: "result", of: ev, ts: end, seq: Number.MAX_SAFE_INTEGER, exitCode: typeof r.exit === "number" ? r.exit : null, isError: null, output: "" });
     added++;
   }
@@ -191,26 +350,30 @@ function readLines(file) {
 const MARK = "# agent-polygraph record";
 export const shellScript = () => path.join(home(), "shell.sh");
 
-const SHELL_SNIPPET = () => fs.readFileSync(new URL("./shell/record.sh", import.meta.url), "utf8");
+const shQuote = (s) => "'" + String(s).replaceAll("'", "'\"'\"'") + "'";
+const SHELL_SNIPPET = () => fs.readFileSync(new URL("./shell/record.sh", import.meta.url), "utf8")
+  .replace("__APG_NODE__", shQuote(process.execPath))
+  .replace("__APG_ENTRY__", shQuote(fs.realpathSync(fileURLToPath(new URL("../bin/polygraph.js", import.meta.url)))));
 
-const RC_FILES = () => [".bashrc", ".zshrc"].map((f) => path.join(os.homedir(), f));
+const RC_FILES = () => [".bashrc", ".zshrc"].map((f) => path.join(process.env.HOME || os.homedir(), f));
 
 export function installShell() {
   const script = shellScript();
-  fs.mkdirSync(path.join(home(), "records"), { recursive: true });
-  fs.writeFileSync(script, SHELL_SNIPPET());
-  const line = `[ -f "${script}" ] && . "${script}"  ${MARK}`;
+  secureWrite(script, SHELL_SNIPPET());
+  secureDirectory(path.join(home(), "records"));
+  const quoted = shQuote(script);
+  const line = `[ -f ${quoted} ] && . ${quoted}  ${MARK}`;
   const out = [];
   for (const rc of RC_FILES()) {
     const shell = rc.endsWith("zshrc") ? "zsh" : "bash";
     if (!fs.existsSync(rc) && !onPath(shell)) continue;
-    const text = fs.existsSync(rc) ? fs.readFileSync(rc, "utf8") : "";
+    const text = readSettings(rc).text ?? "";
     if (text.includes(MARK)) {
       out.push({ file: rc, changed: false });
       continue;
     }
-    fs.appendFileSync(rc, (text && !text.endsWith("\n") ? "\n" : "") + line + "\n");
-    out.push({ file: rc, changed: true });
+    const result = writeSettings(rc, text + (text && !text.endsWith("\n") ? "\n" : "") + line + "\n");
+    out.push({ file: rc, changed: result.changed, backup: result.backup });
   }
   return { script, rcs: out };
 }
@@ -219,10 +382,11 @@ export function uninstallShell() {
   const out = [];
   for (const rc of RC_FILES()) {
     if (!fs.existsSync(rc)) continue;
-    const text = fs.readFileSync(rc, "utf8");
+    const text = readSettings(rc).text;
+    if (text == null) continue;
     if (!text.includes(MARK)) continue;
-    fs.writeFileSync(rc, text.split("\n").filter((l) => !l.includes(MARK)).join("\n"));
-    out.push({ file: rc, changed: true });
+    const result = writeSettings(rc, text.split("\n").filter((l) => !l.includes(MARK)).join("\n"));
+    out.push({ file: rc, changed: result.changed, backup: result.backup });
   }
   fs.rmSync(shellScript(), { force: true });
   return { rcs: out };

package/src/safe-config.js

@@ -0,0 +1,85 @@
+// Atomic, permission-preserving edits for user-owned hook and shell settings.
+// Original content is backed up outside the repository before every change.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+const statKey = (s) => [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].map(String).join(":");
+const backupRoot = () => path.join(process.env.AGENT_POLYGRAPH_HOME || path.join(os.homedir(), ".agent-polygraph"), "backups");
+
+function checkDirectory(dir, create = false) {
+  if (create) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const st = fs.lstatSync(dir);
+  if (!st.isDirectory() || st.isSymbolicLink()) throw new Error("Unsafe settings directory: " + dir);
+  // A directory owned by someone else could redirect the settings file.
+  if (process.platform !== "win32" && st.uid !== process.getuid()) throw new Error("Settings directory is not owned by this user: " + dir);
+}
+
+export function readSettings(file) {
+  let fd;
+  try {
+    const st = fs.lstatSync(file, { bigint: true });
+    if (!st.isFile() || st.nlink !== 1n) throw new Error("Unsafe settings file: " + file);
+    fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+    const opened = fs.fstatSync(fd, { bigint: true });
+    if (!opened.isFile() || opened.nlink !== 1n || opened.dev !== st.dev || opened.ino !== st.ino)
+      throw new Error("Settings file changed while opening: " + file);
+    if (process.platform !== "win32" && opened.uid !== BigInt(process.getuid()))
+      throw new Error("Settings file belongs to another user: " + file);
+    const data = fs.readFileSync(fd);
+    const after = fs.fstatSync(fd, { bigint: true });
+    if (statKey(after) !== statKey(opened)) throw new Error("Settings file changed during read: " + file);
+    return { text: data.toString("utf8"), stat: after, mode: Number(opened.mode & 0o777n) };
+  } catch (e) {
+    if (e.code === "ENOENT") return { text: null, stat: null, mode: 0o600 };
+    throw e;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function backupOriginal(file, previous) {
+  if (previous.text === null) return null;
+  const dir = backupRoot();
+  checkDirectory(dir, true);
+  if (process.platform !== "win32") fs.chmodSync(dir, 0o700);
+  const id = crypto.createHash("sha256").update(path.resolve(file)).digest("hex").slice(0, 16);
+  const target = path.join(dir, id + "-" + Date.now() + "-" + crypto.randomBytes(5).toString("hex") + ".bak");
+  fs.writeFileSync(target, previous.text, { flag: "wx", mode: 0o600 });
+  return target;
+}
+
+// Never truncate the user's existing config. Write a sibling temp file, fsync,
+// and atomically rename it only after confirming the source is still unchanged.
+export function writeSettings(file, text) {
+  const parent = path.dirname(file);
+  checkDirectory(parent, true);
+  const previous = readSettings(file);
+  if (previous.text === text) return { changed: false, backup: null };
+  const backup = backupOriginal(file, previous);
+  const tmp = path.join(parent, "." + path.basename(file) + ".apg-" + crypto.randomBytes(10).toString("hex"));
+  let created = false;
+  try {
+    const fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, previous.mode);
+    created = true;
+    try {
+      fs.writeFileSync(fd, text);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const current = readSettings(file);
+    if ((previous.stat === null) !== (current.stat === null) ||
+        (previous.stat && statKey(previous.stat) !== statKey(current.stat)))
+      throw new Error("Settings changed concurrently; original not overwritten: " + file);
+    fs.renameSync(tmp, file);
+    created = false;
+    return { changed: true, backup };
+  } finally {
+    if (created) fs.rmSync(tmp, { force: true });
+  }
+}
+
+export function backupDirectory() { return backupRoot(); }

package/src/shell/record.sh

@@ -1,37 +1,51 @@
-# agent-polygraph record: logs test commands you run in this terminal (folder, start and end
-# time, exit code; never their output) to ~/.agent-polygraph/records/terminal.jsonl, so a
-# test you ran yourself counts as evidence. Stays on this machine.
+# agent-polygraph record: store only a recognized test-runner label, timestamps,
+# working directory and exit code. Never persist the shell command or its output.
 # Remove with: agent-polygraph record --uninstall --shell
 case $- in *i*) ;; *) return 0 2>/dev/null ;; esac
-# not inside coding agents' own shells: their commands are in their logs already
 [ -n "${CLAUDECODE:-}${CODEX_SANDBOX:-}${CODEX_THREAD_ID:-}${CODEX_MANAGED_BY_NPM:-}" ] && return 0 2>/dev/null
 
-__apg_file="${AGENT_POLYGRAPH_HOME:-$HOME/.agent-polygraph}/records/terminal.jsonl"
-# a cheap prefilter; agent-polygraph applies its real test-command rules when it reads the log
-__apg_re='(test|spec|pytest|jest|vitest|mocha|rspec|phpunit|ctest|tox|nox|check|verify)'
-__apg_cmd=
+# Substituted with an installed, persistent CLI path by record --install --shell.
+__apg_node=__APG_NODE__
+__apg_entry=__APG_ENTRY__
+__apg_runner=
 
 __apg_now() {
   if [ -n "${EPOCHREALTIME:-}" ]; then printf '%s' "${EPOCHREALTIME/,/.}"; else date +%s; fi
 }
 __apg_esc() {
   local s=$1
-  s=${s//\\/\\\\}; s=${s//\"/\\\"}; s=${s//$'\n'/\\n}; s=${s//$'\t'/\\t}; s=${s//$'\r'/}
+  s=${s//\\/\\\\}; s=${s//\"/\\\"}; s=${s//$'\n'/\\n}; s=${s//$'\t'/\\t}; s=${s//$'\r'/\\r}
   printf '%s' "$s"
 }
 __apg_pre() {
-  __apg_cmd=
-  [[ $1 =~ $__apg_re ]] || return 0
-  __apg_cmd=$1
+  __apg_runner=
+  # Conservative: do not treat compound commands (e.g. npm test; true) as proof.
+  case "$1" in *';'*|*'|'*|*'&'*|*'`'*|*'$('*|*$'\n'*) return 0 ;; esac
+  local c="${1#${1%%[![:space:]]*}}"
+  case "$c" in
+    "pytest"|"pytest "*|"python -m pytest"*|"python3 -m pytest"*) __apg_runner="pytest" ;;
+    "npm test"|"npm test "*|"npm run test"|"npm run test "*|"npm run test:"*) __apg_runner="npm test" ;;
+    "node --test"|"node --test "*) __apg_runner="node --test" ;;
+    "go test"|"go test "*) __apg_runner="go test" ;;
+    "cargo test"|"cargo test "*) __apg_runner="cargo test" ;;
+    "mvn test"|"mvn test "*) __apg_runner="mvn test" ;;
+    "gradle test"|"gradle test "*|"./gradlew test"|"./gradlew test "*) __apg_runner="gradle test" ;;
+    "dotnet test"|"dotnet test "*) __apg_runner="dotnet test" ;;
+    "vitest"|"vitest "*|"jest"|"jest "*) __apg_runner="vitest run" ;;
+  esac
+  [ -n "$__apg_runner" ] || return 0
   __apg_dir=$PWD
   __apg_t0=$(__apg_now)
 }
 __apg_post() {
   local s=$?
-  if [ -n "$__apg_cmd" ]; then
-    printf '{"v":1,"kind":"terminal","start":%s,"end":%s,"exit":%s,"cwd":"%s","cmd":"%s"}\n' \
-      "$__apg_t0" "$(__apg_now)" "$s" "$(__apg_esc "$__apg_dir")" "$(__apg_esc "$__apg_cmd")" >>"$__apg_file" 2>/dev/null
-    __apg_cmd=
+  if [ -n "$__apg_runner" ]; then
+    # The CLI validates input and writes with O_NOFOLLOW; shell redirection
+    # cannot be used here because it would follow an attacker-created symlink.
+    printf '{"v":2,"kind":"terminal","start":%s,"end":%s,"exit":%s,"cwd":"%s","runner":"%s"}\n' \
+      "$__apg_t0" "$(__apg_now)" "$s" "$(__apg_esc "$__apg_dir")" "$__apg_runner" |
+      "$__apg_node" "$__apg_entry" record --shell-event >/dev/null 2>&1
+    __apg_runner=
   fi
   return $s
 }
@@ -40,11 +54,9 @@ if [ -n "${ZSH_VERSION:-}" ]; then
   autoload -Uz add-zsh-hook && add-zsh-hook preexec __apg_pre && add-zsh-hook precmd __apg_post
 elif [ -n "${BASH_VERSION:-}" ]; then
   if [ -n "${bash_preexec_imported:-}${__bp_imported:-}" ]; then
-    # bash-preexec is loaded: use its hooks instead of a DEBUG trap of our own
     preexec_functions+=(__apg_pre)
     precmd_functions=(__apg_post "${precmd_functions[@]}")
   elif [ -z "$(trap -p DEBUG)" ]; then
-    # one DEBUG trap call per command line: $HISTCMD changes only when a new line is entered
     __apg_last=$HISTCMD
     __apg_debug() {
       [[ ${BASH_COMMAND:-} == __apg_* ]] && return