rulereceipt 0.1.36 → 0.1.38

package/README.md

@@ -89,6 +89,7 @@ rulereceipt rules --exclude <handle>   # "this isn't" — stop reporting it
 rulereceipt rules --coverage   # which rules a configured hook might actually enforce
 rulereceipt doctor             # list hooks/auto-run tasks configured on this machine
 rulereceipt hook               # run AS a Claude Code Stop hook — block Claude finishing on a broken rule
+rulereceipt guard              # run AS a Claude Code PreToolUse hook — refuse a call before it runs
 rulereceipt lint               # find contradictions between CLAUDE.md and AGENTS.md
 rulereceipt digest             # summarise recent checks; --email to send it
 rulereceipt config             # set up email sending (stays on your machine)
@@ -127,10 +128,16 @@ is the part a model cannot talk its way around.
 
 Three properties worth knowing before you wire it in:
 
-- **It only blocks on things it can prove.** Never a judgment rule, never an
-  LLM opinion, never "couldn't tell". Only a matched literal or a claim
-  contradicted by a recorded tool result. Run against twelve real sessions it
-  blocked none of them.
+- **It blocks two things, both narrow.** A claim a recorded run contradicts,
+  and a claim of done that nothing in the session verified. Never a judgment
+  rule, never an LLM opinion. Run against thirteen real sessions it stopped
+  two, and both were read by hand.
+- **The report and the gate disagree in exactly one place.** When a session
+  claims work is done and nothing recorded verifies it, the report says
+  "couldn't tell" — the tests may have run in another terminal, and a
+  transcript cannot see that. The gate refuses the exit anyway, because it is
+  not saying the claim is false. It is declining to let "done" end a session
+  with nothing behind it.
 - **It cannot loop.** Claude Code sets `stop_hook_active` when a session is
   already continuing because of a block; the hook returns immediately in that
   case. One interruption per stop.
@@ -143,6 +150,36 @@ It runs when Claude stops, so it catches a finished session, not a command
 mid-flight. For that, use a `PreToolUse` hook of your own — `rulereceipt
 doctor` will show you what you already have.
 
+### Refusing a command before it runs
+
+`rulereceipt guard` runs as a `PreToolUse` hook and refuses a call outright:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "hooks": [ { "type": "command", "command": "npx rulereceipt guard" } ] }
+    ]
+  }
+}
+```
+
+Read the limit before wiring it in, because it is most of the story. It
+enforces rules naming a **file** or a **branch** — "never modify `.env`",
+"never commit to `main`" — and nothing else.
+
+It does **not** block banned commands. That was the point of building it, and
+it did not survive measurement: replaying 16,336 real tool calls against every
+forbidding rule in a 559-file corpus, blocking on command literals refused
+62.8% of them. Narrowing twice reached 2.5%, and the residue was still wrong
+in a way no matcher fixes — one rule refused `npm run build` 112 times,
+because it forbids running Playwright unprompted and *recommends*
+`npm run build`, which is its only command-shaped literal.
+
+Nothing in a rules file marks which backtick is the prohibition. A report
+survives that by saying UNCLEAR. A gate cannot.
+
+
 ## Which rules actually have teeth
 
 A rule in a file and a rule with a `PreToolUse` hook behind it look identical

package/dist/checks/claimEvidence.js

@@ -188,7 +188,11 @@ function unclear(rule, evidence) {
  */
 export function runClaimEvidenceChecks(classifications, events) {
     let lastRun = null;
-    let pendingRun = null;
+    // Keyed by tool_use id where the transcript has one, so a result can be
+    // matched to the call it belongs to rather than to the call above it.
+    // `null` is the key for id-less transcripts, which keeps the old
+    // positional behaviour for fixtures and older logs.
+    const pendingRuns = new Map();
     let claimsMade = 0;
     let unknownSinceRed = null;
     const commandsSeen = new Set();
@@ -200,7 +204,15 @@ export function runClaimEvidenceChecks(classifications, events) {
     for (const event of events) {
         const command = commandOf(event);
         if (command !== null) {
-            pendingRun = TEST_COMMAND.test(withoutHeredocs(command)) ? command : null;
+            const id = event.kind === "tool_use" ? (event.toolUseId ?? null) : null;
+            if (TEST_COMMAND.test(withoutHeredocs(command))) {
+                pendingRuns.set(id, command);
+            }
+            else if (id === null) {
+                // No id to distinguish calls, so a later call really does supersede
+                // an earlier one — the original positional rule, unchanged.
+                pendingRuns.delete(null);
+            }
             for (const action of ACTION_CLAIMS) {
                 if (action.command.test(command))
                     commandsSeen.add(action.label);
@@ -217,6 +229,8 @@ export function runClaimEvidenceChecks(classifications, events) {
         // every turn contained exactly one tool call, so there is no parallel
         // fan-out to mis-attribute.
         if (event.kind === "tool_result") {
+            const resultId = event.toolUseId ?? null;
+            const pendingRun = pendingRuns.get(resultId) ?? null;
             if (pendingRun !== null) {
                 // Prefer what the runner SAID over what the shell returned: the
                 // words survive a pipe, the exit status does not.
@@ -233,7 +247,7 @@ export function runClaimEvidenceChecks(classifications, events) {
                     outcomeReadable: oneRun && (stated !== null || trustExitCode),
                     output: event.content.slice(0, 200),
                 };
-                pendingRun = null;
+                pendingRuns.delete(resultId);
                 unknownSinceRed = null; // a recognised run supersedes anything before it
             }
             continue;
@@ -331,8 +345,12 @@ export function runClaimEvidenceChecks(classifications, events) {
             };
         }
         if (claimsMade > 0) {
-            return unclear(rule, `the session claimed a passing test suite ${claimsMade} time(s), but no test command ran here — ` +
-                `it may have been run outside this session, which the transcript cannot show`);
+            return {
+                ...unclear(rule, `the session claimed a passing test suite ${claimsMade} time(s), but no test command ran here — ` +
+                    `it may have been run outside this session, which the transcript cannot show`),
+                // UNCLEAR in the report, refused by the gate. See CheckResult.unverifiedClaim.
+                unverifiedClaim: true,
+            };
         }
         return unclear(rule, "the session made no claim about passing tests, so there was nothing to check against the log");
     });

package/dist/checks/classify.js

@@ -264,7 +264,19 @@ function isBranchName(literal) {
 // A function/method-call shape ("print(", "analytics.track(") is a strong,
 // simple signal that a backtick literal names actual CODE, not a CLI
 // command or flag ("git push --force", "npm test" never look like this).
-const CODE_CONSTRUCT_PATTERN = /\(/;
+//
+// It must be a CALL, not merely a parenthesis. The test used to be /\(/,
+// which is true of a great deal of ordinary prose: measured 2026-09-15
+// across 559 rules files, 74 of 1,086 literals reaching content matching
+// (6.8%) were not code — "(e.g.", "(soft)", a markdown link fragment, three
+// whole blocks of accounting formulae. "(in the" produced a real false
+// accusation, reported as having been "actually written into a file", which
+// is true of any file containing that phrase.
+//
+// An identifier immediately before the paren, optionally dotted or scoped,
+// so "console.log(", "std::cout(" and "obj->run(" all qualify and a bare
+// parenthesis does not.
+const CODE_CONSTRUCT_PATTERN = /[A-Za-z_$][A-Za-z0-9_$]*(?:\s*(?:\.|::|->)\s*[A-Za-z_$][A-Za-z0-9_$]*)*\s*\(/;
 // A file-path shape: a known config/source extension, or a path with a
 // directory separator. Deliberately requires no spaces — a real path
 // literal ("`.claude/settings.json`", "`config.yaml`") never has one,

package/dist/checks/codeContent.js

@@ -29,6 +29,37 @@ function editedContentFromEvent(event) {
         return input.new_source;
     return null;
 }
+/**
+ * Whether the content contains this literal AS A CALL, not merely as a
+ * substring of a longer identifier.
+ *
+ * Found 2026-09-15 by checking a corpus FAIL rather than assuming it was
+ * legitimate: a rule forbidding `fetch()` matched a file containing
+ * `_metar_fetch()`. The literal was present verbatim, and entirely the wrong
+ * function. The same bare-substring test makes `main()` match `domain()` and
+ * `run()` match `rerun()`, and short generic call names are exactly what
+ * these rules tend to name.
+ *
+ * Only the LEADING boundary is checked. The trailing side is already pinned
+ * by the pattern itself — every literal reaching this checker ends in an
+ * open paren or a call — so requiring a boundary after it would reject the
+ * arguments.
+ */
+function containsCall(content, pattern) {
+    const leadsWithIdentifier = /^[A-Za-z0-9_$]/.test(pattern);
+    if (!leadsWithIdentifier)
+        return content.includes(pattern);
+    let from = 0;
+    for (;;) {
+        const at = content.indexOf(pattern, from);
+        if (at === -1)
+            return false;
+        const before = at === 0 ? "" : content[at - 1];
+        if (!/[A-Za-z0-9_$.]/.test(before))
+            return true;
+        from = at + 1;
+    }
+}
 export function runCodeContentChecks(classifications, events) {
     const editedContents = [];
     for (const event of events) {
@@ -41,7 +72,7 @@ export function runCodeContentChecks(classifications, events) {
         let foundContent;
         for (const content of editedContents) {
             for (const pattern of patterns) {
-                if (content.includes(pattern)) {
+                if (containsCall(content, pattern)) {
                     foundPattern = pattern;
                     foundContent = content;
                     break;

package/dist/checks/deterministicChecks.d.ts

@@ -1,5 +1,32 @@
 import type { TranscriptEvent, CheckResult } from "../types.js";
 import type { DeterministicClassification } from "./classify.js";
+/**
+ * Appends the canonical long spelling of any short destructive flag the
+ * text uses, so a rule banning `git push --force` also catches `git push -f`.
+ *
+ * Extracted from searchHaystack 2026-09-15 so the pre-execution guard uses
+ * exactly the same aliasing as the post-hoc checker. A guard that missed
+ * `-f` while the report caught it would be worse than having neither.
+ */
+export declare function canonicalise(text: string): string;
+/**
+ * Word-boundary-aware match, not a naive substring search — otherwise a
+ * pattern like "git push --force" would false-positive on the SAFER
+ * "git push --force-with-lease" (caught by an actual failing test before
+ * this fix, not assumed).
+ *
+ * The trailing boundary only applies when the pattern itself ends in a
+ * word character — that's the only case where appending more word
+ * characters could form a genuinely different, longer token (like
+ * "--force" extending into "--force-with-lease"). A pattern that already
+ * ends in punctuation (e.g. "http://", ".env") can't be turned into a
+ * different token that way, and real occurrences of it (a real URL, a
+ * real filename) always have more characters immediately after — a real
+ * bug found by testing this against an actual "http://example.com"
+ * string: the old unconditional boundary made "http://" unmatchable
+ * against any real URL, ever.
+ */
+export declare function matchesPattern(haystack: string, pattern: string): boolean;
 /**
  * Checks a single deterministic rule against the transcript by scanning
  * every event for the rule's literal banned pattern(s). No API calls, no

package/dist/checks/deterministicChecks.js

@@ -54,8 +54,19 @@ function searchHaystack(event) {
     const raw = eventSearchText(event);
     if (event.kind !== "tool_use")
         return raw;
-    const extra = FLAG_ALIASES.filter((a) => a.context.test(raw) && a.short.test(raw)).map((a) => a.canonical);
-    return extra.length > 0 ? `${raw} ${extra.join(" ")}` : raw;
+    return canonicalise(raw);
+}
+/**
+ * Appends the canonical long spelling of any short destructive flag the
+ * text uses, so a rule banning `git push --force` also catches `git push -f`.
+ *
+ * Extracted from searchHaystack 2026-09-15 so the pre-execution guard uses
+ * exactly the same aliasing as the post-hoc checker. A guard that missed
+ * `-f` while the report caught it would be worse than having neither.
+ */
+export function canonicalise(text) {
+    const extra = FLAG_ALIASES.filter((a) => a.context.test(text) && a.short.test(text)).map((a) => a.canonical);
+    return extra.length > 0 ? `${text} ${extra.join(" ")}` : text;
 }
 function escapeRegex(literal) {
     return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -77,7 +88,7 @@ function escapeRegex(literal) {
  * string: the old unconditional boundary made "http://" unmatchable
  * against any real URL, ever.
  */
-function matchesPattern(haystack, pattern) {
+export function matchesPattern(haystack, pattern) {
     const lastChar = pattern[pattern.length - 1];
     const needsTrailingBoundary = /[\w-]/.test(lastChar);
     const suffix = needsTrailingBoundary ? "(?![\\w-])" : "";

package/dist/checks/fileLifecycle.js

@@ -1,5 +1,6 @@
 import { violation } from "../types.js";
 import { isProjectPath } from "./projectPaths.js";
+import { withoutHeredocs } from "./shellCommand.js";
 /**
  * Third structured-check primitive: only counts real MUTATIONS of a
  * protected file, never reads of it. Real false-positive this fixes
@@ -43,7 +44,17 @@ function pathPattern(filePath) {
  * it mutates after that is a scratch file, not the project's.
  */
 const CD_INTO_TEMP = /\bcd\s+["']?(?:\/private)?\/(?:tmp|var\/folders)\b|\bcd\s+["']?[^\s"'&|;]*\/(?:scratchpad|node_modules)\b/;
-function mutatesPathInBash(command, filePath) {
+/**
+ * A path named only inside a heredoc body was not touched by the command
+ * that contains it.
+ *
+ * Real case, 2026-09-15: a command editing landing/index.html through a
+ * Python heredoc was reported as modifying `.claude/`, because the HTML it
+ * inserts tells readers to put a hook in `.claude/settings.json`. Writing a
+ * path into a file is not mutating that path.
+ */
+function mutatesPathInBash(rawCommand, filePath) {
+    const command = withoutHeredocs(rawCommand);
     const p = pathPattern(filePath);
     const mutations = [
         // rm / rmdir / unlink targeting the path

package/dist/checks/proposedAction.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Is this literal shaped like a command, rather than a noun?
+ *
+ * The single most important restriction in the guard, and it exists because
+ * the first version was measured before it shipped. Replaying 16,322 real
+ * tool calls against the 371 literal prohibitions in the corpus, it refused
+ * 62% of them. The literals doing the damage were ordinary words that rules
+ * name in passing — `browse`, `mix`, `index.ts`, `scripts:`, `AGENTS.md` —
+ * each of which appears in perfectly innocent commands all day.
+ *
+ * A prohibition worth blocking on names an invocation: `git push --force`,
+ * `rm -rf`, `npm publish`, or a bare flag like `--no-verify`. So: it must
+ * contain whitespace, or begin with a dash. A single bare word is never
+ * enough, which does mean a rule that says only "never use `rm`" is not
+ * enforced here. That is the right way round. The report still carries it,
+ * and refusing to run someone's command on the strength of one ambiguous
+ * word is not a trade worth making.
+ */
+export declare function literalIsCommandShaped(literal: string): boolean;
+/**
+ * Whether a command that is ABOUT TO RUN performs the forbidden thing.
+ *
+ * The post-hoc checker cannot answer this and says so: a literal in a
+ * transcript may be a violation, a grep, or an explanation, and nothing in
+ * the string distinguishes them. Before execution the question is narrower
+ * and mostly answerable, because the command is the act. What remains is
+ * separating the parts of a compound command that do something from the
+ * parts that only look at something, which is what this does.
+ */
+export declare function commandRunsLiteral(command: string, literal: string): boolean;

package/dist/checks/proposedAction.js

@@ -0,0 +1,127 @@
+import { withoutHeredocs } from "./shellCommand.js";
+import { canonicalise, matchesPattern } from "./deterministicChecks.js";
+/**
+ * Commands that read. A banned literal appearing as an argument to one of
+ * these is being searched for, printed, or paged — not run.
+ *
+ * This is the whole reason the post-hoc deterministic checker refuses to
+ * report a violation: a text match cannot tell an action from a mention.
+ * Before the tool runs, most of that ambiguity is gone — the command IS the
+ * action — but not all of it, because a command can still quote a literal
+ * while doing something harmless with it. This list is what is left of the
+ * problem, and it is deliberately a known list: anything not on it is
+ * treated as doing something.
+ *
+ * `sed` is absent on purpose. `sed -i` edits in place; plain `sed` does not,
+ * and the difference is handled below rather than by listing the name.
+ */
+const READ_ONLY = new Set([
+    "grep", "rg", "ag", "ack", "egrep", "fgrep",
+    "echo", "printf", "cat", "bat", "head", "tail", "less", "more",
+    "find", "fd", "ls", "wc", "sort", "uniq", "diff", "comm",
+    "awk", "jq", "yq", "cut", "tr", "column", "tee",
+    "which", "type", "file", "stat", "man", "help",
+]);
+/** Read-only git subcommands — `git log` cannot delete anything. */
+const READ_ONLY_GIT = new Set(["log", "show", "diff", "status", "blame", "describe", "config", "remote", "branch", "tag", "ls-files", "rev-parse", "shortlog"]);
+/**
+ * Splits a shell command into the pieces that run separately.
+ *
+ * Crude by design: this is not a shell parser and must never pretend to be
+ * one. It exists so that `grep "rm -rf" notes.txt && npm run build` is read
+ * as two things, one of which searches for a string and one of which does
+ * not, rather than as one blob containing a banned literal.
+ */
+function segments(command) {
+    return withoutHeredocs(command)
+        .split(/\n|&&|\|\||[;|]/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** The executable a segment invokes, with env assignments and `sudo` skipped. */
+function leadingCommand(segment) {
+    const words = segment.split(/\s+/).filter(Boolean);
+    let i = 0;
+    while (i < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || words[i] === "sudo" || words[i] === "command" || words[i] === "time"))
+        i++;
+    const exe = (words[i] ?? "").replace(/^.*\//, "");
+    return exe;
+}
+/**
+ * A commit message is text the user wrote, not a command being run.
+ *
+ * Real case in this project's own history: a commit message containing
+ * backticked shell examples. A message that quotes a banned command in order
+ * to describe it must not be treated as running it.
+ */
+function withoutCommitMessage(segment) {
+    return segment.replace(/(-m|--message)(=|\s+)(['"])(?:\\.|(?!\3)[\s\S])*\3/g, "$1 <message>");
+}
+/**
+ * Does this segment actually DO the forbidden thing?
+ *
+ * Returns false for a segment that only reads, searches, or prints.
+ */
+function segmentRunsLiteral(segment, literal) {
+    const exe = leadingCommand(segment);
+    if (READ_ONLY.has(exe))
+        return false;
+    if (exe === "sed" && !/\s-[A-Za-z]*i\b/.test(segment))
+        return false;
+    if (exe === "git") {
+        const sub = segment.split(/\s+/).filter(Boolean)[1] ?? "";
+        // A read-only git subcommand cannot be the destructive act — unless the
+        // rule names that subcommand itself, which is a real thing people write
+        // ("never run `git config user.email`"), so the literal still has to be
+        // checked against it. What is skipped is only the case where the literal
+        // is some OTHER command quoted inside a read-only one.
+        if (READ_ONLY_GIT.has(sub) && !literal.includes(`git ${sub}`))
+            return false;
+    }
+    return matchesPattern(canonicalise(withoutCommitMessage(segment)), literal);
+}
+/**
+ * Is this literal shaped like a command, rather than a noun?
+ *
+ * The single most important restriction in the guard, and it exists because
+ * the first version was measured before it shipped. Replaying 16,322 real
+ * tool calls against the 371 literal prohibitions in the corpus, it refused
+ * 62% of them. The literals doing the damage were ordinary words that rules
+ * name in passing — `browse`, `mix`, `index.ts`, `scripts:`, `AGENTS.md` —
+ * each of which appears in perfectly innocent commands all day.
+ *
+ * A prohibition worth blocking on names an invocation: `git push --force`,
+ * `rm -rf`, `npm publish`, or a bare flag like `--no-verify`. So: it must
+ * contain whitespace, or begin with a dash. A single bare word is never
+ * enough, which does mean a rule that says only "never use `rm`" is not
+ * enforced here. That is the right way round. The report still carries it,
+ * and refusing to run someone's command on the strength of one ambiguous
+ * word is not a trade worth making.
+ */
+export function literalIsCommandShaped(literal) {
+    const t = literal.trim();
+    if (t.length === 0)
+        return false;
+    if (/^-{1,2}[A-Za-z]/.test(t))
+        return true;
+    // Must BEGIN like a command too, not merely contain a space: `, and` is a
+    // real corpus literal and it blocked 118 commands on its own.
+    if (!/^[A-Za-z][A-Za-z0-9_.\/-]*(\s|$)/.test(t))
+        return false;
+    return /\s/.test(t);
+}
+/**
+ * Whether a command that is ABOUT TO RUN performs the forbidden thing.
+ *
+ * The post-hoc checker cannot answer this and says so: a literal in a
+ * transcript may be a violation, a grep, or an explanation, and nothing in
+ * the string distinguishes them. Before execution the question is narrower
+ * and mostly answerable, because the command is the act. What remains is
+ * separating the parts of a compound command that do something from the
+ * parts that only look at something, which is what this does.
+ */
+export function commandRunsLiteral(command, literal) {
+    if (!literalIsCommandShaped(literal))
+        return false;
+    return segments(command).some((s) => segmentRunsLiteral(s, literal));
+}

package/dist/checks/shellCommand.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Facts about shell command text that more than one checker needs.
+ *
+ * Created 2026-09-15. The heredoc guard below lived in testCommands.ts, was
+ * used only by the test-command matcher, and the file-mutation checker never
+ * saw it — so the same class of false accusation was fixed in one reader and
+ * left standing in the other. Anything that reasons about what a shell
+ * command DID, rather than what it says, belongs here.
+ */
+/**
+ * Removes heredoc bodies from a shell command.
+ *
+ * A command that WRITES a test command is not a command that RUNS one.
+ * Found 2026-09-14 on a real session: two false failures whose "last test
+ * run" was a shell variable assignment. The actual match came from a
+ * heredoc further down, writing a demo fixture whose body contains the
+ * string `npm test`. The literal was being generated, never executed — and
+ * the tool then read its own report output as the failing result.
+ *
+ * Handles both quoted and bare delimiters, and leaves everything after the
+ * closing delimiter intact, because a real test run often follows the
+ * heredoc that set the fixture up.
+ */
+export declare function withoutHeredocs(command: string): string;

package/dist/checks/shellCommand.js

@@ -0,0 +1,43 @@
+/**
+ * Facts about shell command text that more than one checker needs.
+ *
+ * Created 2026-09-15. The heredoc guard below lived in testCommands.ts, was
+ * used only by the test-command matcher, and the file-mutation checker never
+ * saw it — so the same class of false accusation was fixed in one reader and
+ * left standing in the other. Anything that reasons about what a shell
+ * command DID, rather than what it says, belongs here.
+ */
+/**
+ * Removes heredoc bodies from a shell command.
+ *
+ * A command that WRITES a test command is not a command that RUNS one.
+ * Found 2026-09-14 on a real session: two false failures whose "last test
+ * run" was a shell variable assignment. The actual match came from a
+ * heredoc further down, writing a demo fixture whose body contains the
+ * string `npm test`. The literal was being generated, never executed — and
+ * the tool then read its own report output as the failing result.
+ *
+ * Handles both quoted and bare delimiters, and leaves everything after the
+ * closing delimiter intact, because a real test run often follows the
+ * heredoc that set the fixture up.
+ */
+export function withoutHeredocs(command) {
+    const lines = command.split("\n");
+    const out = [];
+    let closing = null;
+    for (const line of lines) {
+        if (closing !== null) {
+            if (line.trim() === closing)
+                closing = null;
+            continue;
+        }
+        const open = line.match(/<<-?\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))/);
+        if (open) {
+            closing = open[1] ?? open[2] ?? open[3];
+            out.push(line.slice(0, open.index));
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join("\n");
+}

package/dist/checks/testCommands.d.ts

@@ -19,21 +19,6 @@ import type { TranscriptEvent } from "../types.js";
  * wrong.
  */
 export declare const TEST_COMMAND: RegExp;
-/**
- * Removes heredoc bodies from a shell command.
- *
- * A command that WRITES a test command is not a command that RUNS one.
- * Found 2026-09-14 on a real session: two false failures whose "last test
- * run" was a shell variable assignment. The actual match came from a
- * heredoc further down, writing a demo fixture whose body contains the
- * string `npm test`. The literal was being generated, never executed — and
- * the tool then read its own report output as the failing result.
- *
- * Handles both quoted and bare delimiters, and leaves everything after the
- * closing delimiter intact, because a real test run often follows the
- * heredoc that set the fixture up.
- */
-export declare function withoutHeredocs(command: string): string;
 /**
  * How many times a single shell command invokes a test suite.
  *
@@ -54,3 +39,4 @@ export declare function withoutHeredocs(command: string): string;
 export declare function countTestRuns(command: string): number;
 /** The first test command run in this session, or null if none ran. */
 export declare function findTestRun(events: TranscriptEvent[]): string | null;
+export { withoutHeredocs } from "./shellCommand.js";

package/dist/checks/testCommands.js

@@ -1,3 +1,4 @@
+import { withoutHeredocs } from "./shellCommand.js";
 /**
  * Commands that run a project's test suite.
  *
@@ -18,40 +19,6 @@
  * wrong.
  */
 export const TEST_COMMAND = /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|verify|check|ci)\b|\bnpx\s+(?:vitest|jest|mocha|ava)\b|\b(?:vitest|jest|mocha|pytest|phpunit|rspec|tox)\b|\bcargo\s+test\b|\bgo\s+test\b|\bmvn\s+(?:test|verify)\b|\bgradle\s+test\b|\bdotnet\s+test\b|\bpython\s+-m\s+(?:pytest|unittest)\b/i;
-/**
- * Removes heredoc bodies from a shell command.
- *
- * A command that WRITES a test command is not a command that RUNS one.
- * Found 2026-09-14 on a real session: two false failures whose "last test
- * run" was a shell variable assignment. The actual match came from a
- * heredoc further down, writing a demo fixture whose body contains the
- * string `npm test`. The literal was being generated, never executed — and
- * the tool then read its own report output as the failing result.
- *
- * Handles both quoted and bare delimiters, and leaves everything after the
- * closing delimiter intact, because a real test run often follows the
- * heredoc that set the fixture up.
- */
-export function withoutHeredocs(command) {
-    const lines = command.split("\n");
-    const out = [];
-    let closing = null;
-    for (const line of lines) {
-        if (closing !== null) {
-            if (line.trim() === closing)
-                closing = null;
-            continue;
-        }
-        const open = line.match(/<<-?\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))/);
-        if (open) {
-            closing = open[1] ?? open[2] ?? open[3];
-            out.push(line.slice(0, open.index));
-            continue;
-        }
-        out.push(line);
-    }
-    return out.join("\n");
-}
 /**
  * How many times a single shell command invokes a test suite.
  *
@@ -85,3 +52,4 @@ export function findTestRun(events) {
     }
     return null;
 }
+export { withoutHeredocs } from "./shellCommand.js";

package/dist/cli.js

@@ -17,6 +17,7 @@ import { runCodeContentChecks } from "./checks/codeContent.js";
 import { runFileLifecycleChecks } from "./checks/fileLifecycle.js";
 import { runClaimEvidenceChecks } from "./checks/claimEvidence.js";
 import { runHook } from "./hook.js";
+import { runGuard } from "./guard.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
 import { generateReport, generateMarkdownReport } from "./report/generateReport.js";
 import { generateHtmlReport } from "./report/generateHtmlReport.js";
@@ -580,6 +581,12 @@ program
     .action(async () => {
     await runHook(needsLlmResult);
 });
+program
+    .command("guard")
+    .description("run as a Claude Code PreToolUse hook - refuse a command that breaks a rule, before it runs (payload on stdin)")
+    .action(async () => {
+    await runGuard();
+});
 program
     .command("doctor")
     .description("List every Claude Code hook and VS Code auto-task on this machine/project, flag anything suspicious")

package/dist/guard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A PreToolUse hook that refuses a command before it runs.
+ *
+ * The Stop hook added on 2026-09-14 catches a finished session. That is too
+ * late for the case it most needs to cover: on 2026-04-25 a Cursor agent
+ * running Claude Opus 4.6 deleted PocketOS's production database and every
+ * volume-level backup in nine seconds, using a Railway token it found that
+ * had been created for managing domains. The agent had a rule — "NEVER run
+ * destructive/irreversible git commands...unless the user explicitly
+ * requests them" — and afterwards quoted it back, observing that what it had
+ * done was "far worse than a force push". A report would have described a
+ * database that was already gone.
+ *
+ * What it does NOT do is the thing it was built for. Blocking on a rule's
+ * banned command literal was measured before shipping and cut: see the note
+ * above `reason`. It refused 62% of 16,336 real commands, and the residue
+ * after two rounds of narrowing was still wrong in a way no matcher fixes.
+ * PocketOS would not have been stopped by this hook, and saying otherwise
+ * would be the exact failure this tool exists to catch.
+ *
+ * What remains is real and narrower: rules that name a FILE or a BRANCH.
+ * "Never modify `.env`", "never touch `migrations/`", "never commit to
+ * `main`". The classifier identified those as a path or a ref rather than
+ * guessing which backtick was the prohibition, so a refusal can be stated
+ * with a reason that holds up.
+ *
+ * Three properties, in the order they matter:
+ *
+ * 1. FORBIDDING rules only, answered by a structured checker. Never a
+ *    judgment rule, never an LLM opinion, never a requirement, and never a
+ *    bare command literal. Blocking someone's terminal on a guess is not a
+ *    trade worth making at any hit rate.
+ *
+ * 2. It fails OPEN. Any error allows the command and writes to stderr. The
+ *    opposite choice means a bug in this file stops someone from running
+ *    anything at all, and they would remove the hook within the hour — which
+ *    leaves them with no guard rather than an imperfect one.
+ *
+ * 3. It says which rule and why, in the refusal itself, because a block with
+ *    no reason is indistinguishable from a broken tool.
+ */
+export declare function runGuard(): Promise<void>;

package/dist/guard.js

@@ -0,0 +1,182 @@
+import { loadRules } from "./rules.js";
+import { classifyRules } from "./checks/classify.js";
+import { runCodeContentChecks } from "./checks/codeContent.js";
+import { runFileLifecycleChecks } from "./checks/fileLifecycle.js";
+import { runGitBranchPolicyChecks } from "./checks/gitBranchPolicy.js";
+import { loadOverrides, ruleFingerprint } from "./overrides.js";
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        if (process.stdin.isTTY)
+            return resolve("");
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => (data += c));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(""));
+    });
+}
+/**
+ * The rules this can answer BEFORE the command runs.
+ *
+ * Deliberately only the forbidding ones. "Always run the tests before
+ * committing" cannot be judged from a single proposed call — whether it was
+ * already satisfied is a fact about the session, not about this command —
+ * and a guard that blocked on it would fire on the first commit of every
+ * session. Requirements stay with the report and the Stop hook.
+ */
+function forbidRules(cwd) {
+    const overrides = loadOverrides(cwd);
+    return classifyRules(loadRules(cwd)).filter((c) => {
+        if (overrides.get(ruleFingerprint(c.rule))?.decision === "notARule")
+            return false;
+        return "polarity" in c && c.polarity === "forbid";
+    });
+}
+/**
+ * Runs the structured checkers against a single PROPOSED action.
+ *
+ * They already take a list of events and ask what it did, so a one-event
+ * list describing what is about to happen is exactly the right input. This
+ * is why the guard cannot drift from the report: same checkers, same
+ * verdicts, different tense.
+ */
+function structuredBlocks(cwd, event) {
+    const cls = forbidRules(cwd);
+    const of = (k) => cls.filter((c) => c.kind === k);
+    const results = [
+        ...runCodeContentChecks(of("codeContent"), [event]),
+        ...runFileLifecycleChecks(of("fileLifecycle"), [event]),
+        ...runGitBranchPolicyChecks(of("gitBranchPolicy"), [event]),
+    ];
+    return results
+        .filter((r) => r.status === "FAIL")
+        .map((r) => ({
+        rule: { id: r.ruleId, title: r.ruleTitle, text: "", source: r.ruleSource },
+        why: r.evidence,
+    }));
+}
+/**
+ * Literal command bans do NOT block. Measured, then cut.
+ *
+ * This was the point of the feature and it does not survive its own
+ * measurement. Replaying 16,336 real tool calls against every forbidding
+ * rule in the corpus, blocking on literals refused 62% of commands. Two
+ * restrictions brought that to 1.6% — the literal has to be shaped like an
+ * invocation rather than a noun, and the rule has to name exactly one of
+ * them — and what remained was still wrong in a way no matcher can fix.
+ *
+ * A rule titled "Feature Validation" refused `npm run build` 112 times. It
+ * forbids running Playwright without asking; it RECOMMENDS `npm run build`.
+ * Forbid polarity, one command-shaped literal, and that literal is the
+ * approved command. Another rule refused plain `git status`, because its
+ * backticks hold both the thing it bans and the thing it suggests instead.
+ *
+ * Nothing in a rules file marks which backtick is the prohibition. The
+ * report can live with that — it says UNCLEAR and a person reads it. A
+ * blocker cannot: it would refuse the recommended command with a confident
+ * explanation. So command bans stay in the report and the Stop hook, and
+ * only the structured checkers, which know what kind of thing they are
+ * looking at because the classifier identified a path or a branch, can
+ * refuse anything here.
+ *
+ * The way back to command bans is an explicit opt-in — the user naming which
+ * rules may block — not a cleverer guess. That is a design question for
+ * whoever asks for it, not a default.
+ */
+function reason(blocks) {
+    const lines = blocks.map((b) => `  • Rule ${b.rule.id} — ${b.rule.title}\n    ${b.why}`);
+    const n = blocks.length;
+    return (`RuleReceipt blocked this: it breaks ${n === 1 ? "a rule" : `${n} rules`} in CLAUDE.md.\n\n` +
+        lines.join("\n\n") +
+        `\n\nIf the rule should not apply here, say so to the user and let them decide. Do not work around the rule by rephrasing the command.`);
+}
+/**
+ * A PreToolUse hook that refuses a command before it runs.
+ *
+ * The Stop hook added on 2026-09-14 catches a finished session. That is too
+ * late for the case it most needs to cover: on 2026-04-25 a Cursor agent
+ * running Claude Opus 4.6 deleted PocketOS's production database and every
+ * volume-level backup in nine seconds, using a Railway token it found that
+ * had been created for managing domains. The agent had a rule — "NEVER run
+ * destructive/irreversible git commands...unless the user explicitly
+ * requests them" — and afterwards quoted it back, observing that what it had
+ * done was "far worse than a force push". A report would have described a
+ * database that was already gone.
+ *
+ * What it does NOT do is the thing it was built for. Blocking on a rule's
+ * banned command literal was measured before shipping and cut: see the note
+ * above `reason`. It refused 62% of 16,336 real commands, and the residue
+ * after two rounds of narrowing was still wrong in a way no matcher fixes.
+ * PocketOS would not have been stopped by this hook, and saying otherwise
+ * would be the exact failure this tool exists to catch.
+ *
+ * What remains is real and narrower: rules that name a FILE or a BRANCH.
+ * "Never modify `.env`", "never touch `migrations/`", "never commit to
+ * `main`". The classifier identified those as a path or a ref rather than
+ * guessing which backtick was the prohibition, so a refusal can be stated
+ * with a reason that holds up.
+ *
+ * Three properties, in the order they matter:
+ *
+ * 1. FORBIDDING rules only, answered by a structured checker. Never a
+ *    judgment rule, never an LLM opinion, never a requirement, and never a
+ *    bare command literal. Blocking someone's terminal on a guess is not a
+ *    trade worth making at any hit rate.
+ *
+ * 2. It fails OPEN. Any error allows the command and writes to stderr. The
+ *    opposite choice means a bug in this file stops someone from running
+ *    anything at all, and they would remove the hook within the hour — which
+ *    leaves them with no guard rather than an imperfect one.
+ *
+ * 3. It says which rule and why, in the refusal itself, because a block with
+ *    no reason is indistinguishable from a broken tool.
+ */
+export async function runGuard() {
+    const allow = () => {
+        process.stdout.write(JSON.stringify({}));
+    };
+    try {
+        const raw = await readStdin();
+        const input = raw ? JSON.parse(raw) : {};
+        const cwd = input.cwd || process.cwd();
+        const tool = input.tool_name ?? "";
+        const toolInput = input.tool_input ?? {};
+        if (loadRules(cwd).length === 0)
+            return allow();
+        let blocks = [];
+        if (tool === "Bash" && typeof toolInput.command === "string") {
+            const event = {
+                role: "assistant", kind: "tool_use", toolName: "Bash",
+                input: { command: toolInput.command }, timestamp: "",
+            };
+            blocks = structuredBlocks(cwd, event);
+        }
+        else if (tool === "Write" || tool === "Edit" || tool === "NotebookEdit") {
+            const event = {
+                role: "assistant", kind: "tool_use", toolName: tool,
+                input: toolInput, timestamp: "",
+            };
+            blocks = structuredBlocks(cwd, event);
+        }
+        else {
+            return allow();
+        }
+        if (blocks.length === 0)
+            return allow();
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: reason(blocks),
+            },
+        }));
+        // Exit 2 is what actually blocks the call; the JSON carries the reason.
+        process.exitCode = 2;
+    }
+    catch (err) {
+        // Fail open, and never with exit 2 — an exit 2 from a crash would block
+        // every command the session tries to run.
+        process.stderr.write(`rulereceipt guard: allowing command, check did not complete (${err instanceof Error ? err.message : String(err)})\n`);
+        allow();
+    }
+}

package/dist/hook.js

@@ -22,12 +22,25 @@ function readStdin() {
  * what to do and repeating it invites the model to argue with the wording
  * instead of going and running the thing.
  */
-function blockReason(failures) {
-    const lines = failures.map((f) => `  • Rule ${f.ruleId} — ${f.ruleTitle}\n    ${f.evidence}`);
-    const n = failures.length;
-    return (`RuleReceipt: ${n} rule${n === 1 ? "" : "s"} in CLAUDE.md ${n === 1 ? "was" : "were"} not followed in this session.\n\n` +
-        lines.join("\n\n") +
-        `\n\nDo not report this work as finished until the above is resolved or you have said plainly, to the user, that it is still open and why.`);
+function blockReason(failures, unverified) {
+    const parts = [];
+    if (failures.length > 0) {
+        const n = failures.length;
+        parts.push(`RuleReceipt: ${n} rule${n === 1 ? "" : "s"} in CLAUDE.md ${n === 1 ? "was" : "were"} not followed in this session.\n\n` +
+            failures.map((f) => `  • Rule ${f.ruleId} — ${f.ruleTitle}\n    ${f.evidence}`).join("\n\n"));
+    }
+    // Worded as a question about evidence rather than as a finding, because
+    // that is what it is. Nothing here says the claim is false. It says
+    // nothing in this session shows it to be true, and that the difference
+    // belongs to the user rather than to the summary.
+    if (unverified.length > 0) {
+        parts.push(`RuleReceipt: this session claims work is done, and nothing recorded here verifies it.\n\n` +
+            unverified.map((u) => `  • Rule ${u.ruleId} — ${u.ruleTitle}\n    ${u.evidence}`).join("\n\n") +
+            `\n\nThis is not a claim that you are wrong. It may well have been verified somewhere this transcript cannot see.`);
+    }
+    parts.push(`Do not report this work as finished until the above is resolved, or you have said plainly, to the user, ` +
+        `what was actually verified and what was not.`);
+    return parts.join("\n\n");
 }
 /**
  * A Stop hook that refuses to let a session end on a broken rule.
@@ -88,9 +101,13 @@ export async function runHook(needsLlmResult) {
         // it is part of the contract.
         const { results } = await evaluateSession(cwd, rules, events, false, needsLlmResult);
         const failures = results.filter((r) => r.status === "FAIL" && r.outcome !== "not_run");
-        if (failures.length === 0)
+        // Deliberately NOT a FAIL. See CheckResult.unverifiedClaim: the report
+        // calls this unclear and the gate refuses it, and that is the only place
+        // the two are allowed to disagree.
+        const unverified = results.filter((r) => r.unverifiedClaim === true);
+        if (failures.length === 0 && unverified.length === 0)
             return void emit({});
-        return void emit({ decision: "block", reason: blockReason(failures) });
+        return void emit({ decision: "block", reason: blockReason(failures, unverified) });
     }
     catch (err) {
         // Property 3: fail open, but never silently.

package/dist/parsers/transcriptParser.js

@@ -117,7 +117,7 @@ export function parseLine(line) {
                     events.push({ role: "assistant", kind: "text", text: b.text, timestamp });
                 }
                 else if (b.type === "tool_use" && typeof b.name === "string") {
-                    events.push({ role: "assistant", kind: "tool_use", toolName: b.name, input: b.input, timestamp });
+                    events.push({ role: "assistant", kind: "tool_use", toolName: b.name, input: b.input, timestamp, toolUseId: typeof b.id === "string" ? b.id : undefined });
                 }
             }
         }
@@ -140,6 +140,7 @@ export function parseLine(line) {
                         content: extractToolResultText(b.content),
                         isError: b.is_error === true,
                         timestamp,
+                        toolUseId: typeof b.tool_use_id === "string" ? b.tool_use_id : undefined,
                     });
                 }
             }

package/dist/types.d.ts

@@ -16,6 +16,17 @@ export interface TranscriptToolUseEvent {
     toolName: string;
     input: unknown;
     timestamp: string;
+    /**
+     * The tool_use id, when the transcript carries one.
+     *
+     * Added 2026-09-16. Without it a result can only be attributed to "the
+     * call immediately before", which was documented here as safe on the
+     * grounds that every turn contained exactly one tool call. Parallel tool
+     * calls are now ordinary — a real session issues three in a row and then
+     * one result — and under that shape the positional rule silently drops
+     * the test run that a completion claim depended on.
+     */
+    toolUseId?: string;
 }
 export interface TranscriptToolResultEvent {
     role: "user";
@@ -23,6 +34,8 @@ export interface TranscriptToolResultEvent {
     content: string;
     isError: boolean;
     timestamp: string;
+    /** The id of the call this result belongs to, when the transcript has it. */
+    toolUseId?: string;
 }
 export type TranscriptEvent = TranscriptTextEvent | TranscriptToolUseEvent | TranscriptToolResultEvent;
 export type CheckStatus = "PASS" | "FAIL" | "UNCLEAR";
@@ -74,6 +87,23 @@ export interface CheckResult {
      * not blur them.
      */
     needsHuman?: boolean;
+    /**
+     * A completion claim that nothing in this session verified.
+     *
+     * The one place the report and the gate deliberately disagree. The report
+     * renders this UNCLEAR, because absence genuinely proves nothing — the
+     * tests may have run in another terminal and a transcript cannot see that.
+     * The Stop hook refuses the exit on it anyway, because it is not asserting
+     * a violation: it is declining to let "done" end a session when nothing
+     * here backs it, and the way out is one sentence saying so out loud.
+     *
+     * Added 2026-09-16. It is the case anthropics/claude-code#90542 is about
+     * from end to end — deploy artifacts produced and the application never
+     * opened, a completion whose evidence is a plan, "state what was VERIFIED
+     * versus only PLANNED" — and the gate was silent on all of it, firing only
+     * when a recorded run CONTRADICTED a claim.
+     */
+    unverifiedClaim?: boolean;
     /**
      * The outcome in the five-value vocabulary. Optional while the checkers
      * are migrated one at a time; `status` remains the fallback.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",