altimate-receipts 0.18.1 → 0.20.0

package/README.md

@@ -177,6 +177,38 @@ Humans pushing from a terminal, other agents, or repos that won't commit `.claud
 config → **[the onboarding guide](./docs/onboarding.md)** has a one-command fallback for
 each.
 
+### Live guard (optional — prevention, not just record)
+
+The Work Record is *post-hoc* — it documents what the agent did. The **live guard** is the
+*pre-execution* arm: a PreToolUse hook that classifies a tool call **before it runs** and
+either blocks it, asks you to confirm, or just records it.
+
+```sh
+npx altimate-receipts init --guard
+```
+
+It uses the **same FP-aware policy** as the Work Record (`policy/guardrails.policy.json`), in
+three tiers:
+
+- **deny** — never-legitimate catastrophes only (`rm -rf /` / `~` / `.git` / `.receipts`,
+  force-push to a *protected* branch, `mkfs`, `DROP DATABASE`). Hard-blocked.
+- **ask** — ambiguous-but-dangerous (`rm -rf` of an unknown dir, `git reset --hard`,
+  `--no-verify`, pipe-a-script-from-the-internet, force-push to a *feature* branch). Routed to
+  your normal confirmation prompt — never silently blocked.
+- **warn** — surfaced + recorded, never blocked (editing a CI workflow / a grader / an `.env`).
+
+Blocked calls never reach the transcript, so the guard **records each deny/ask/warn into the
+Receipt** — the highest-signal line a record can carry: *what the agent was stopped from doing.*
+
+**It's off by default, and opt-out is one env var.** Active gating is your call:
+
+```sh
+RECEIPTS_GUARD=0   # turn the guard off without un-installing (fail-open, records nothing)
+```
+
+The guard is **fail-open by contract** — any error, or the opt-out, allows the call. The
+post-hoc Record is the backstop, so live enforcement favors letting work through.
+
 ## Going deeper (optional)
 
 - **`receipts --json`** — a portable, vendor-neutral [in-toto](https://in-toto.io)

package/dist/{chunk-JWDZLJDG.js → chunk-7LROPRL2.js}

@@ -1,9 +1,25 @@
 #!/usr/bin/env node
 import {
   destructiveOutsideRepo,
+  isProtectedBranch,
   regenerableBuildArtifact,
-  regenerableReceiptRm
-} from "./chunk-LYLHXQAU.js";
+  regenerableReceiptRm,
+  stripHeredocs
+} from "./chunk-RYOBPBGP.js";
+
+// src/version.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+function getVersion() {
+  try {
+    const pkgUrl = new URL("../package.json", import.meta.url);
+    const raw = readFileSync(fileURLToPath(pkgUrl), "utf8");
+    const pkg = JSON.parse(raw);
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 
 // src/findings/gitParse.ts
 var WRAPPER = /* @__PURE__ */ new Set(["sudo", "env", "nohup", "command", "stdbuf", "time", "timeout", "xargs"]);
@@ -233,6 +249,12 @@ var has = (inv, ...names) => [...inv.flags, ...inv.globalFlags].some((f) => name
 function isHardForcePush(inv) {
   return inv.subcommand === "push" && has(inv, "force", "f") && !has(inv, "force-with-lease", "force-if-includes");
 }
+function forcePushTargetProtected(inv) {
+  return inv.positionals.some((p) => {
+    const dst = p.includes(":") ? p.split(":").pop() ?? "" : p;
+    return isProtectedBranch(dst);
+  });
+}
 function isNoVerify(inv) {
   if (inv.subcommand === "commit") {
     return has(inv, "no-verify", "n");
@@ -667,6 +689,25 @@ function uncachedCost(usage, model) {
   return (usage.input * price.input + usage.output * price.output + (usage.cacheRead + usage.cacheWrite) * price.input) / m;
 }
 
+// src/findings/paths.ts
+var WORKTREE_PREFIX = /^.*\/\.claude\/worktrees\/[^/]+\//;
+var AGENT_RUNTIME = /(?:^|\/)\.claude\/(?:projects|todos|statsig|shell-snapshots|history)\//;
+function isAgentRuntimePath(p) {
+  return AGENT_RUNTIME.test(p);
+}
+function repoRelativePath(p) {
+  return p.replace(WORKTREE_PREFIX, "").replace(/^\.\//, "");
+}
+function repoFilePath(raw) {
+  if (!raw) {
+    return void 0;
+  }
+  if (isAgentRuntimePath(raw)) {
+    return void 0;
+  }
+  return repoRelativePath(raw);
+}
+
 // src/findings/toolRoles.ts
 var EDIT_NAMES = /^(edit|multiedit|write|notebookedit|str_replace_editor|str_replace|apply_patch|search_replace|create_file|edit_file|insert_edit_into_file|replace_string_in_file|patch|write_file|create)$/i;
 var CREATE_NAMES = /^(write|create_file|write_file|create|notebookedit)$/i;
@@ -709,7 +750,7 @@ function filePathOf(input) {
     return void 0;
   }
   const v = r.file_path ?? r.filePath ?? r.path ?? r.target_file ?? r.targetFile ?? r.filename ?? r.fileName ?? r.uri ?? r.fsPath;
-  return typeof v === "string" ? v : void 0;
+  return typeof v === "string" ? repoFilePath(v) : void 0;
 }
 function commandOf(input) {
   if (typeof input === "string") {
@@ -795,6 +836,27 @@ function toolInputField(input, keys) {
   }
   return void 0;
 }
+var READ_ONLY_FILE_CMD = /^(?:cat|bat|head|tail|less|more|nl)$/i;
+function extractReadPaths(command) {
+  const out = [];
+  for (const stmt of command.split(/\n|;|&&|\|\||\|/)) {
+    const toks = stmt.trim().split(/\s+/).filter(Boolean);
+    const head = toks[0]?.replace(/.*\//, "");
+    if (!head || !READ_ONLY_FILE_CMD.test(head)) {
+      continue;
+    }
+    for (const t of toks.slice(1)) {
+      if (/^\d*&?[<>]/.test(t)) {
+        break;
+      }
+      if (t.startsWith("-") || /^\d+$/.test(t) || /[*?]/.test(t)) {
+        continue;
+      }
+      out.push(t.replace(/^["']|["']$/g, ""));
+    }
+  }
+  return out;
+}
 var DESTRUCTIVE_PATTERNS = [
   /(?<!git )\brm\s+(-[a-z]*\s+)*-?[a-z]*[rf]/i,
   // rm -rf, rm -fr, rm -r -f (NOT `git rm`)
@@ -809,11 +871,6 @@ var DESTRUCTIVE_PATTERNS = [
   // writing to a raw disk
   /\bmkfs\b|\bdd\s+if=/i
 ];
-function stripHeredocs(command) {
-  const closed = /<<-?\s*(['"]?)([A-Za-z_]\w*)\1[\s\S]*?\n[ \t]*\2(?![A-Za-z0-9_])/g;
-  const stripped = command.replace(closed, "<<heredoc");
-  return stripped.replace(/<<-?\s*(['"]?)[A-Za-z_]\w*\1[\s\S]*$/, "<<heredoc");
-}
 function stripCodeStringsAndComments(code) {
   let out = "";
   let state = "code";
@@ -1024,7 +1081,9 @@ function classifyDestructive(name, input) {
   if (DESTRUCTIVE_PATTERNS.some((re) => re.test(scannable))) {
     return true;
   }
-  return parseGitInvocations(scannable).some(destroysGitData);
+  return parseGitInvocations(scannable).some(
+    (inv) => destroysGitData(inv) && !(isHardForcePush(inv) && !forcePushTargetProtected(inv))
+  );
 }
 function destructiveMatch(command) {
   const scannable = destructiveScannable(command);
@@ -1116,10 +1175,22 @@ function deriveSpans(session) {
   for (const m of session.messages) {
     for (const c of m.toolCalls ?? []) {
       if (FILE_READ_TOOLS.has(c.name)) {
-        const fp = toolInputField(c.input, ["file_path", "path", "filename", "target_file"]);
+        const fp = repoFilePath(
+          toolInputField(c.input, ["file_path", "path", "filename", "target_file"])
+        );
         if (fp) {
           filesReadSet.add(fp);
         }
+      } else if (CMD_TOOLS.has(c.name)) {
+        const cmd = toolInputField(c.input, ["command", "cmd"]);
+        if (cmd) {
+          for (const p of extractReadPaths(cmd)) {
+            const fp = repoFilePath(p);
+            if (fp) {
+              filesReadSet.add(fp);
+            }
+          }
+        }
       }
     }
   }
@@ -1230,12 +1301,16 @@ function deriveSpans(session) {
         loopCounts.set(sig, { count: 1, name: call.name, preview: String(preview).slice(0, 80) });
       }
       if (FILE_WRITE_TOOLS.has(call.name)) {
-        const fp = toolInputField(call.input, ["file_path", "path", "filename", "target_file"]);
+        const fp = repoFilePath(
+          toolInputField(call.input, ["file_path", "path", "filename", "target_file"])
+        );
         if (fp) {
           filesChangedMap.set(fp, "write");
         }
       } else if (FILE_EDIT_TOOLS.has(call.name)) {
-        const fp = toolInputField(call.input, ["file_path", "path", "filename", "target_file"]);
+        const fp = repoFilePath(
+          toolInputField(call.input, ["file_path", "path", "filename", "target_file"])
+        );
         if (fp && !filesChangedMap.has(fp)) {
           filesChangedMap.set(fp, "edit");
         }
@@ -3560,8 +3635,9 @@ function diffEffort(derived, files, window) {
   let tokens = 0;
   for (const s of derived.spans) {
     if (s.kind === "generation" && editedGens.has(s.spanId)) {
-      cost += s.cost || estimateCost(s.tokens, s.name);
-      tokens += s.tokens?.total ?? 0;
+      const t = s.tokens;
+      tokens += (t?.input ?? 0) + (t?.output ?? 0) + (t?.cacheWrite ?? 0);
+      cost += t ? estimateCost({ ...t, cacheRead: 0 }, s.name) : s.cost || 0;
     }
   }
   return { cost, tokens, turns: editedGens.size };
@@ -3635,20 +3711,6 @@ function applyDiffScope(derived, findings, files, projectPath) {
   };
 }
 
-// src/version.ts
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-function getVersion() {
-  try {
-    const pkgUrl = new URL("../package.json", import.meta.url);
-    const raw = readFileSync(fileURLToPath(pkgUrl), "utf8");
-    const pkg = JSON.parse(raw);
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-
 // src/receipt/hash.ts
 import { createHash } from "crypto";
 import { promises as fs } from "fs";
@@ -4006,7 +4068,12 @@ async function buildReceipt(session, derived, findings, opts = {}) {
     session: {
       agent: session.source,
       model: session.model,
-      title: session.title,
+      // Prefer the BRANCH name for a diff-scoped receipt. `session.title` is the session's first
+      // user message, which is shared across every branch a long multi-branch session produces (and
+      // contaminated across resumed sessions) — so 5 unrelated branches all read "Plan SaaS layer…".
+      // The branch is recorded in `scope` (so L1 re-derivation reproduces this exact title) and
+      // actually describes the branch. Fall back to the session title only when there's no branch.
+      title: opts.scope?.branch || session.title,
       startedAt: session.startedAt,
       endedAt: session.endedAt,
       durationMs: session.totals.durationMs
@@ -5678,6 +5745,7 @@ function redactReceipt(receipt) {
 }
 
 export {
+  getVersion,
   deriveSpans,
   cwdAtFirstGit,
   formatTokens,
@@ -5690,7 +5758,6 @@ export {
   narrowEffort,
   windowedEffort,
   applyDiffScope,
-  getVersion,
   hashTranscriptFile,
   sha256Hex,
   PREDICATE_TYPE,
@@ -5719,4 +5786,4 @@ export {
   redact,
   redactReceipt
 };
-//# sourceMappingURL=chunk-JWDZLJDG.js.map
+//# sourceMappingURL=chunk-7LROPRL2.js.map