@syv-ai/rulecast 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 Your project's conventions are written down in `AGENTS.md` or `CLAUDE.md`, and your coding agent read them once, forty tool calls ago. rulecast delivers them again at the moment they matter: when the agent is about to break one.
 
-A rule pairs a check with a message and a pointer to the doc section it enforces. rulecast runs as an agent hook, so when the agent edits a file that breaks a rule, it gets told — in the same turn, before it moves on.
+A rule pairs a check with a message and a pointer to the doc section it enforces. rulecast runs as an agent hook, so when the agent changes a file that breaks a rule — with its edit tools or with Bash — it gets told, in the same turn, before it moves on.
 
 ```
 rulecast: 1 rule violated in app/services/users.py
@@ -20,6 +20,8 @@ Services raise domain exceptions. `app/api/errors.py` maps each one to a status
 
 That is real output. The agent sees the finding *and* the paragraph of your documentation that explains it, without having to go looking.
 
+A file the agent rewrites with `sed -i` or a script is checked like one it changes with `Edit`: rulecast compares the working tree before and after each Bash call. A change no call explains — your own editor, a formatter, a job the agent left running — is reported when the agent stops, and never blocks it.
+
 ## Getting started
 
 ```sh
@@ -85,6 +87,8 @@ Some rules are not advice. `refuse_write: true` refuses the edit before it happe
 
 A refusal only ever rests on the text the agent is writing, never on a reconstruction rulecast is unsure of, and it happens once per file per session — so a rule can stop a mistake without trapping the agent. Generated code, vendored directories, files that must not change. Everything else is better reported after the write, which is what the other rules do.
 
+That covers the edit tools. A write through Bash cannot be refused before it runs, because nothing knows what a command will write, so rulecast catches it right after: the agent is told the file is protected and how to revert it, it cannot stop until it has, and you are told which file it changed.
+
 ## Commands
 
 | Command | Does |
@@ -220,7 +224,7 @@ rulecast up itself:
 
 ```text
 Set up rulecast in this project. Read
-https://raw.githubusercontent.com/syv-ai/rulecast/v0.4.0/agents/SETUP.md
+https://raw.githubusercontent.com/syv-ai/rulecast/v0.5.0/agents/SETUP.md
 and follow it. Show me every file it creates or changes before I commit anything.
 ```
 
@@ -256,6 +260,8 @@ Node ≥ 20.12. Linux and macOS; Windows is not supported.
 
 The edit hook is budgeted to finish in under 500 ms at p95 — measured from process start to exit, on a 30-rule project with warm caches, excluding `llm` rules. `pnpm perf` replays 50 edit events and checks it. The last measurement, on an Apple M3 Pro with all six detectors configured, was p50 170 ms and p95 187 ms.
 
+The hook before every Bash call only records the working tree: it is held to 150 ms over a hook that does nothing, and adds 135–150 ms at p95 on a 20,000-file repository (`microsoft/vscode`), nearly all of it git finding untracked files. The hook after a Bash call that changed a file is an edit event, under the same 500 ms budget.
+
 The budget is what shapes the design: one detector run per kind per event, kinds in parallel, slow tools defaulted to `verify`, content-addressed caches on disk, no daemon. When an edit runs long, rulecast delivers what finished and builds the rest in the background rather than making the agent wait.
 
 ## Status

package/dist/{chunk-DQUCE2IK.js → chunk-4XS34SYW.js}

@@ -1,5 +1,5 @@
 // src/core/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 function parseVersion(text) {
   const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(text);
   return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
@@ -568,6 +568,15 @@ var BACKLOG_HEADING = "backlog in files you touched (not from your edit; leave i
 var WARNINGS_HEADING = "rulecast warnings:";
 var CONVENTIONS_TITLE = "rulecast: conventions for the files you are working on";
 var NOTICES_HEADING = "rulecast notices (for the user):";
+var SWEPT_HEADING = "changed outside your tool calls (fix them if a process you started made them; they do not block):";
+var SWEPT_BLOCK = "\0swept:";
+var PROTECTED = "This file is protected; revert your change.";
+var DIRTY_ADVICE = "It had uncommitted changes before this session: undo only your change, not the whole file.";
+var refusedLines = (refused) => [
+  `${refused.file} (${refused.rule}): ${PROTECTED}`,
+  `  ${refused.dirtyAtStart ? DIRTY_ADVICE : `git checkout -- ${refused.file}`}`
+];
+var SHELL_TRIGGER = "changed by your Bash command";
 var backlogLine = (summary) => `  ${summary.rule} \xD7${summary.count} in ${summary.file}`;
 var backlogMoreLine = (count) => `  \u2026and ${count} more`;
 var warningLine = (warning) => `  - ${warning}`;
@@ -578,12 +587,16 @@ var overflowLines = (rules, path7) => [
 ];
 var WRAP = 96;
 var plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+function violatedTitle(rules, file, via) {
+  const where = via === "shell" ? file === null ? ` in files ${SHELL_TRIGGER}` : ` in ${file}, ${SHELL_TRIGGER}` : file === null ? "" : ` in ${file}`;
+  return `rulecast: ${plural(rules, "rule")} violated${where}`;
+}
 function header(delivery) {
   if (delivery.findings.length > 0) {
     const rules = new Set(delivery.findings.map((finding) => finding.rule)).size + delivery.omitted.rules;
     const files = new Set(delivery.findings.map((finding) => finding.file));
-    const where = files.size === 1 && delivery.omitted.rules === 0 ? ` in ${[...files][0]}` : "";
-    return `rulecast: ${plural(rules, "rule")} violated${where}`;
+    const file = files.size === 1 && delivery.omitted.rules === 0 ? [...files][0] : null;
+    return violatedTitle(rules, file, delivery.via);
   }
   if (delivery.references.length > 0 || delivery.preexistingSummary.length > 0) {
     return CONVENTIONS_TITLE;
@@ -642,8 +655,8 @@ function referenceLines(reference) {
     }
   }
 }
-function omittedFor(omitted, rule) {
-  const entry = omitted.findings.find((finding) => finding.rule === rule);
+function omittedFor(omitted, rule, swept) {
+  const entry = omitted.findings.find((finding) => finding.rule === rule && finding.swept === true === swept);
   return { count: entry?.count ?? 0, files: entry?.files ?? 0 };
 }
 function ruleBlock(rule, findings, template, dropped, options) {
@@ -677,12 +690,13 @@ var deliveryCost = {
    * It names a file when every *delivered* finding is in one, and the budget may cut a rule down to
    * findings in a single file however many files it fired in; so the longest file name is charged.
    * And if the budget drops every rule that fired, no findings are left and the conventions title
-   * prints instead; so with `conventions` the longer of the two is charged.
+   * prints instead; so with `conventions` the longer of the two is charged. A shell edit's title
+   * names the file or says "files", so both forms are measured and the longer charged.
    */
-  header(rules, files, conventions) {
+  header(rules, files, conventions, via) {
     const longest = [...files].reduce((most, file) => file.length > most.length ? file : most, "");
-    const where = longest === "" ? "" : ` in ${longest}`;
-    const violated = rules > 0 ? linesCost([`rulecast: ${plural(rules, "rule")} violated${where}`, ""]) : 0;
+    const titles = [violatedTitle(rules, longest === "" ? null : longest, via), violatedTitle(rules, null, via)];
+    const violated = rules > 0 ? Math.max(...titles.map((title) => linesCost([title, ""]))) : 0;
     return Math.max(violated, conventions ? linesCost([CONVENTIONS_TITLE, ""]) : 0);
   },
   /**
@@ -696,6 +710,12 @@ var deliveryCost = {
   referenceContent(ref, content, location) {
     return linesCost(referenceLines({ ref, state: "full", content })) - deliveryCost.referenceLine(ref, location);
   },
+  /** What to undo for one protected file changed with the shell, and the blank line after it. */
+  refused(refused) {
+    return linesCost([...refusedLines(refused), ""]);
+  },
+  /** The heading over findings in swept files, once. */
+  sweptFrame: linesCost([SWEPT_HEADING]),
   /** The blank line that closes the references, once. */
   referencesEnd: 1,
   /** The warnings heading, once. */
@@ -725,15 +745,28 @@ function renderAgentText(delivery, options) {
   if (title === null && warnings.length === 0 && notices.length === 0) return "";
   const out = [];
   if (title !== null) out.push(title, "");
-  const byRule = /* @__PURE__ */ new Map();
-  for (const finding of delivery.findings) {
-    const group = byRule.get(finding.rule);
-    if (group === void 0) byRule.set(finding.rule, [finding]);
-    else group.push(finding);
-  }
-  for (const [rule, findings] of byRule) {
-    out.push(...ruleBlock(rule, findings, delivery.templates[rule], omittedFor(delivery.omitted, rule), options));
-    out.push("");
+  const swept = new Set(delivery.swept ?? []);
+  const blocks = (findings, isSwept) => {
+    const byRule = /* @__PURE__ */ new Map();
+    for (const finding of findings) {
+      const group = byRule.get(finding.rule);
+      if (group === void 0) byRule.set(finding.rule, [finding]);
+      else group.push(finding);
+    }
+    for (const [rule, ruleFindings] of byRule) {
+      const dropped = omittedFor(delivery.omitted, rule, isSwept);
+      out.push(...ruleBlock(rule, ruleFindings, delivery.templates[rule], dropped, options), "");
+    }
+  };
+  blocks(
+    delivery.findings.filter((finding) => !swept.has(finding.file)),
+    false
+  );
+  for (const refused of delivery.refused ?? []) out.push(...refusedLines(refused), "");
+  const outside = delivery.findings.filter((finding) => swept.has(finding.file));
+  if (outside.length > 0) {
+    out.push(SWEPT_HEADING);
+    blocks(outside, true);
   }
   if (delivery.preexistingSummary.length > 0 || delivery.omitted.preexisting > 0) {
     out.push(BACKLOG_HEADING);
@@ -1081,6 +1114,7 @@ export {
   LLM_PROVIDERS,
   defaultDetectorSettings,
   emptyDelivery,
+  SWEPT_BLOCK,
   measureRuleBlock,
   deliveryCost,
   renderAgentText,

package/dist/{chunk-IKONOTME.js → chunk-MB4F7ZXC.js}

@@ -3,6 +3,7 @@ import {
   DeadlineError,
   LlmUnavailableError,
   MODEL_ALIASES,
+  emptyDelivery,
   errorMessage,
   isNotFound,
   lineStarts,
@@ -15,7 +16,7 @@ import {
   renderAgentText,
   resolveModel,
   sourceReader
-} from "./chunk-DQUCE2IK.js";
+} from "./chunk-4XS34SYW.js";
 
 // src/core/detection/registry.ts
 function createRegistry(detectors) {
@@ -1048,7 +1049,9 @@ var common = z7.object({
   agent_id: z7.string().min(1).optional(),
   agent_type: z7.string().optional(),
   source: z7.string().optional(),
-  prompt: z7.string().optional()
+  prompt: z7.string().optional(),
+  tool_name: z7.string().optional(),
+  tool_use_id: z7.string().min(1).optional()
 });
 var fileTool = z7.object({
   tool_name: z7.string(),
@@ -1078,7 +1081,9 @@ function parseClaudeCode(input) {
     agent_id: agentId,
     agent_type: agentType,
     source,
-    prompt
+    prompt,
+    tool_name: toolName,
+    tool_use_id: toolUseId
   } = head.data;
   const session = agentId === void 0 ? { id } : { id, agentId };
   const result = (kind, files = [], completeRead) => ({
@@ -1086,6 +1091,23 @@ function parseClaudeCode(input) {
     event: kind === null ? null : { kind, files, cwd, session, ...completeRead === void 0 ? {} : { completeRead } },
     warmup: false
   });
+  const shell = (kind, failed = false) => ({
+    cwd,
+    event: {
+      kind,
+      files: [],
+      cwd,
+      session,
+      ...toolUseId === void 0 ? {} : { toolUseId },
+      ...failed ? { failed } : {}
+    },
+    warmup: false
+  });
+  if (toolName === "Bash") {
+    if (hook === "PreToolUse") return shell("shell-before");
+    if (hook === "PostToolUse") return shell("shell-after");
+    if (hook === "PostToolUseFailure") return shell("shell-after", true);
+  }
   switch (hook) {
     case "PreToolUse": {
       const tool = fileTool.safeParse(input);
@@ -1127,7 +1149,9 @@ function parseClaudeCode(input) {
       return result(prompt?.startsWith("<task-notification>") ? null : "prompt");
     case "SessionStart":
       if (source === "compact") return result("reset");
-      return { ...result(null), warmup: source === "startup" || source === "resume" };
+      if (source === "startup" || source === "resume") return { ...result("start"), warmup: true };
+      if (source === "clear" || source === "fork") return result("start");
+      return result(null);
     default:
       return result(null);
   }
@@ -1147,10 +1171,18 @@ function hookGroups(verifyMs) {
     { event: "PreToolUse", matcher: "Edit|Write", timeout: 5 },
     { event: "PostToolUse", matcher: "Read", timeout: 5 },
     { event: "PostToolUse", matcher: "Edit|Write", timeout: 5 },
+    // Around every shell call: the working tree before and after it is how rulecast sees what a
+    // command wrote. After can run an edit event; a command that fails fires the Failure hook instead.
+    { event: "PreToolUse", matcher: "Bash", timeout: 5 },
+    { event: "PostToolUse", matcher: "Bash", timeout: 5 },
+    { event: "PostToolUseFailure", matcher: "Bash", timeout: 5 },
     { event: "Stop", timeout: verifyTimeout },
     { event: "SubagentStop", timeout: verifyTimeout },
     { event: "UserPromptSubmit", timeout: 5 },
-    { event: "SessionStart", matcher: "startup|resume|compact", timeout: 5 }
+    { event: "SessionStart", matcher: "startup|resume|compact", timeout: 5 },
+    // A group of its own rather than a wider matcher on the one above: an older install's group
+    // would then no longer match, and upgrading it would leave two hooks firing on every startup.
+    { event: "SessionStart", matcher: "clear|fork", timeout: 5 }
   ];
 }
 function installed(groups, matcher2) {
@@ -1230,6 +1262,7 @@ var CONTEXT_LIMIT = 1e4;
 var CONTEXT_BUDGET = 9e3;
 var BLOCK_PREAMBLE = `This project's rulecast rules (.rulecast-config.yaml) found problems in code changed in this session. Fix them before you finish. If you believe a finding is wrong, say so to the user rather than changing .rulecast-config.yaml; add a "rulecast-ignore: <rule> <reason>" comment only if they agree.`;
 var CAP_PREAMBLE = "rulecast: the agent stopped with these findings unresolved (stop gate limit reached).";
+var SWEPT_PREAMBLE = "rulecast: files changed outside the agent's tool calls this session have findings (not blocking the agent).";
 var DENY_PREAMBLE = "This project's rulecast rules (.rulecast-config.yaml) refuse this write. Change what you are writing, or the file you are writing it to, and try again.";
 var NOT_INSTALLED = "rulecast is configured in this project but not installed. Run npm install (or pnpm install), then rulecast doctor.";
 var LOCAL_COMMAND = `B="$CLAUDE_PROJECT_DIR"/node_modules/.bin/rulecast; [ -x "$B" ] && exec "$B" hook claude-code; grep -q '"hook_event_name": *"SessionStart"' && printf '%s' '${JSON.stringify({ systemMessage: NOT_INSTALLED })}'; exit 0`;
@@ -1281,9 +1314,14 @@ ${text2}`, delivery, event)
         });
       case "touch":
       case "edit":
+      case "shell-after":
         return json2(
           withNotices({
-            hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: withinLimit(text2, delivery, event) }
+            hookSpecificOutput: {
+              // A command that failed fired PostToolUseFailure, which takes context only under its own name.
+              hookEventName: event.failed === true ? "PostToolUseFailure" : "PostToolUse",
+              additionalContext: withinLimit(text2, delivery, event)
+            }
           })
         );
       case "reset":
@@ -1309,6 +1347,23 @@ ${text2}`, delivery, event);
           return json2({ systemMessage: notices === "" ? cap : `${notices}
 
 ${cap}` });
+        }
+        if ((delivery.swept ?? []).length > 0) {
+          const swept = new Set(delivery.swept);
+          const onlySwept = {
+            ...emptyDelivery(),
+            findings: delivery.findings.filter((finding) => swept.has(finding.file)),
+            templates: delivery.templates,
+            omitted: { ...delivery.omitted, findings: delivery.omitted.findings.filter((cut) => cut.swept === true) },
+            swept: delivery.swept
+          };
+          const sweptText = renderAgentText(onlySwept, { ...options, notices: false, warnings: false });
+          const outside = withinLimit(`${SWEPT_PREAMBLE}
+
+${sweptText}`, delivery, event);
+          return json2({ systemMessage: notices === "" ? outside : `${notices}
+
+${outside}` });
         }
         return notices === "" ? NONE : json2({ systemMessage: notices });
       default:

package/dist/{chunk-WUFU4LW2.js → chunk-Y3FXJRZB.js}

@@ -1,6 +1,7 @@
 import {
   DeadlineError,
   LLM_PROVIDERS,
+  SWEPT_BLOCK,
   VERSION,
   compileFilter,
   compileRule,
@@ -24,7 +25,7 @@ import {
   sectionRange,
   sectionText,
   templateBindings
-} from "./chunk-DQUCE2IK.js";
+} from "./chunk-4XS34SYW.js";
 
 // src/core/config/load.ts
 import { readFile } from "fs/promises";
@@ -689,8 +690,8 @@ function fixedRepo(dir, label) {
 }
 
 // src/core/pipeline.ts
-import { createHash as createHash4 } from "crypto";
-import path14 from "path";
+import { createHash as createHash5 } from "crypto";
+import path15 from "path";
 
 // src/core/content.ts
 var WORKTREE = { kind: "worktree" };
@@ -1156,16 +1157,31 @@ async function recordFingerprints(input) {
 
 // src/core/baseline/stage.ts
 async function touchRecords(input, state, files) {
+  return (await snapshotRecords(input, state, files, null)).records;
+}
+var START_SNAPSHOT_MAX = 200;
+async function startRecords(input, state, files) {
+  return snapshotRecords(input, state, files, {
+    max: START_SNAPSHOT_MAX,
+    deadlineAt: Date.now() + input.limits.editDeadlineMs
+  });
+}
+async function snapshotRecords(input, state, files, bounds) {
   const records = [];
   const snapshotted = [];
-  for (const file of files) {
-    if (state.snapshots.has(file)) continue;
+  const pending = files.filter((file) => !state.snapshots.has(file));
+  let taken = 0;
+  for (const file of pending) {
+    if (bounds !== null && (taken >= bounds.max || Date.now() >= bounds.deadlineAt)) break;
+    taken++;
     const text = await readSourceFile(input.root, file);
     if (text === null) continue;
     records.push(snapshotRecord(file, snapshotOf(text)));
     snapshotted.push(file);
   }
-  if (snapshotted.length === 0) return records;
+  const skipped = pending.length - taken;
+  const timeoutMs = bounds === null ? input.limits.editDeadlineMs : bounds.deadlineAt - Date.now();
+  if (snapshotted.length === 0 || timeoutMs <= 0) return { records, skipped };
   records.push(
     ...await recordFingerprints({
       detection: input.detection,
@@ -1175,11 +1191,11 @@ async function touchRecords(input, state, files) {
       read: (file) => readSourceFile(input.root, file),
       event: "edit",
       source: "disk",
-      timeoutMs: input.limits.editDeadlineMs,
+      timeoutMs,
       ceiling: { maxFileBytes: input.limits.maxFileBytes, sizeOf: (file) => fileBytes(input.root, file) }
     })
   );
-  return records;
+  return { records, skipped };
 }
 async function changesFor(input, event, state, files, read) {
   let snapshots = state?.snapshots ?? /* @__PURE__ */ new Map();
@@ -1274,16 +1290,16 @@ async function resolveRuleContext(resolver, context) {
 }
 function createReferenceResolver(root) {
   const texts = /* @__PURE__ */ new Map();
-  const read = (path15) => {
-    let text = texts.get(path15);
+  const read = (path16) => {
+    let text = texts.get(path16);
     if (!text) {
-      text = readSourceFile(root, path15);
-      texts.set(path15, text);
+      text = readSourceFile(root, path16);
+      texts.set(path16, text);
     }
     return text;
   };
-  const contentOf = async (path15, anchor) => {
-    const text = await read(path15);
+  const contentOf = async (path16, anchor) => {
+    const text = await read(path16);
     if (text === null) return null;
     if (anchor === null) return text.trimEnd();
     const section = sectionRange(text, anchor);
@@ -1295,14 +1311,14 @@ function createReferenceResolver(root) {
       if (content === null) return { spec, found: false };
       return { spec, found: true, content, hash: fnv1a(content), bytes: Buffer.byteLength(content) };
     },
-    async currentHash(path15, anchor) {
-      const content = await contentOf(path15, anchor);
+    async currentHash(path16, anchor) {
+      const content = await contentOf(path16, anchor);
       return content === null ? null : fnv1a(content);
     },
-    async contains(path15, parent, child) {
+    async contains(path16, parent, child) {
       if (parent === null) return true;
       if (child === null) return false;
-      const text = await read(path15);
+      const text = await read(path16);
       return text !== null && sectionContains(text, parent, child);
     }
   };
@@ -1447,7 +1463,13 @@ function emptyWork() {
     refusals: /* @__PURE__ */ new Map(),
     disabled: /* @__PURE__ */ new Map(),
     accessed: /* @__PURE__ */ new Map(),
-    noticed: /* @__PURE__ */ new Set()
+    noticed: /* @__PURE__ */ new Set(),
+    editedVia: /* @__PURE__ */ new Map(),
+    swept: [],
+    latestTree: /* @__PURE__ */ new Map(),
+    sessionLatestTree: null,
+    beforeTrees: /* @__PURE__ */ new Map(),
+    startTree: null
   };
 }
 function emptyContext() {
@@ -1459,6 +1481,19 @@ function foldWork(records) {
     switch (record.t) {
       case "edited":
         state.edited = [...state.edited.filter((file) => file !== record.file), record.file];
+        state.editedVia.set(record.file, record.via ?? "tool");
+        state.swept = state.swept.filter((file) => file !== record.file);
+        break;
+      case "swept":
+        state.swept = [...state.swept.filter((file) => file !== record.file), record.file];
+        break;
+      case "tree":
+        state.latestTree.set(record.agent, record.state);
+        state.sessionLatestTree = record.state;
+        if (record.phase === "before" && record.toolUseId !== void 0) {
+          state.beforeTrees.set(record.toolUseId, record.state);
+        }
+        if (record.phase === "start" && state.startTree === null) state.startTree = record.state;
         break;
       case "accessed": {
         const files = state.accessed.get(record.agent) ?? [];
@@ -1486,6 +1521,13 @@ function foldWork(records) {
   }
   return state;
 }
+function referenceState(work, agent, toolUseId) {
+  const before = toolUseId === void 0 ? void 0 : work.beforeTrees.get(toolUseId);
+  return before ?? work.latestTree.get(agent) ?? work.sessionLatestTree;
+}
+function dirtyAtStart(work, file) {
+  return work.startTree !== null && file in work.startTree.entries;
+}
 function foldContext(records) {
   let state = emptyContext();
   for (const record of records) {
@@ -1579,11 +1621,16 @@ async function isCovered(spec, delivered, resolver) {
 }
 async function assemble(input) {
   const delivery = emptyDelivery();
+  if (input.via !== void 0) delivery.via = input.via;
   const context = [];
   const touches = input.touches ?? [];
   const state = input.context ?? emptyContext();
   const fresh = input.findings.filter((finding) => finding.status === "new");
   delivery.findings = renderFindings(fresh);
+  const swept = new Set(input.swept ?? []);
+  const sweptWithFindings = [...new Set(fresh.map(({ match }) => match.file))].filter((file) => swept.has(file));
+  if (sweptWithFindings.length > 0) delivery.swept = sweptWithFindings.sort();
+  if ((input.refused ?? []).length > 0) delivery.refused = [...input.refused ?? []];
   for (const { rule } of fresh) if (rule.message !== null) delivery.templates[rule.id] = rule.message;
   const summaries = /* @__PURE__ */ new Map();
   for (const { rule, match, status } of input.findings) {
@@ -1641,14 +1688,27 @@ function trim(assembled, limits) {
   const rulesById = new Map(assembled.fresh.map(({ rule }) => [rule.id, rule]));
   const limit = limits.maxContextChars;
   const render = { maxMatchesPerRule: limits.maxMatchesPerRule };
+  const swept = new Set(delivery.swept ?? []);
+  const blockOf = (finding) => swept.has(finding.file) ? `${SWEPT_BLOCK}${finding.rule}` : finding.rule;
+  const ruleOf = (block) => block.startsWith(SWEPT_BLOCK) ? block.slice(SWEPT_BLOCK.length) : block;
   const byRule = /* @__PURE__ */ new Map();
-  for (const finding of delivery.findings) {
-    const group = byRule.get(finding.rule);
-    if (group === void 0) byRule.set(finding.rule, [finding]);
+  const ordered = [
+    ...delivery.findings.filter((finding) => !swept.has(finding.file)),
+    ...delivery.findings.filter((finding) => swept.has(finding.file))
+  ];
+  for (const finding of ordered) {
+    const group = byRule.get(blockOf(finding));
+    if (group === void 0) byRule.set(blockOf(finding), [finding]);
     else group.push(finding);
   }
   const conventions = delivery.references.length > 0 || delivery.preexistingSummary.length > 0;
-  let used = deliveryCost.header(byRule.size, new Set(delivery.findings.map((finding) => finding.file)), conventions) + (delivery.references.length > 0 ? deliveryCost.referencesEnd : 0);
+  let used = deliveryCost.header(
+    byRule.size,
+    new Set(delivery.findings.map((finding) => finding.file)),
+    conventions,
+    delivery.via
+  ) + (delivery.references.length > 0 ? deliveryCost.referencesEnd : 0) + (swept.size > 0 ? deliveryCost.sweptFrame : 0) + // Never cut: what to undo is the one thing the agent must not miss.
+  (delivery.refused ?? []).reduce((sum, refused) => sum + deliveryCost.refused(refused), 0);
   const fits = (size) => limit === null || used + size <= limit;
   const kept = /* @__PURE__ */ new Map();
   const specs = /* @__PURE__ */ new Map();
@@ -1661,16 +1721,16 @@ function trim(assembled, limits) {
   const charged = /* @__PURE__ */ new Set();
   const orphaned = /* @__PURE__ */ new Set();
   const floorWithin = (cap) => {
-    const spent = { chars: 0, kept: /* @__PURE__ */ new Map(), refs: /* @__PURE__ */ new Set(), dropped: 0 };
+    const spent = { chars: 0, kept: /* @__PURE__ */ new Map(), refs: /* @__PURE__ */ new Set(), dropped: /* @__PURE__ */ new Set() };
     const uncharged = (rule) => [
       ...new Set(rule.context.map((spec) => spec.ref).filter((ref) => resolvedRefs.has(ref) && !spent.refs.has(ref)))
     ];
     for (const [id, findings] of byRule) {
-      const rule = rulesById.get(id);
+      const rule = rulesById.get(ruleOf(id));
       const refs = rule === void 0 ? [] : uncharged(rule);
-      const size = measureRuleBlock(id, [findings[0]], findings, delivery.templates[id], render) + refs.reduce((sum, ref) => sum + lineCost(ref), 0);
+      const size = measureRuleBlock(ruleOf(id), [findings[0]], findings, delivery.templates[ruleOf(id)], render) + refs.reduce((sum, ref) => sum + lineCost(ref), 0);
       if (used + spent.chars + size > cap) {
-        spent.dropped++;
+        spent.dropped.add(id);
         continue;
       }
       spent.chars += size;
@@ -1685,12 +1745,15 @@ function trim(assembled, limits) {
     }
     return spent;
   };
+  let droppedBlocks = 0;
   if (limit !== null) {
     let floor = floorWithin(limit);
     const notice = deliveryCost.overflowNotice(byRule.size);
-    if (floor.dropped > 0) floor = floorWithin(limit - notice);
-    used += floor.chars + (floor.dropped > 0 ? notice : 0);
-    delivery.omitted.rules = floor.dropped;
+    if (floor.dropped.size > 0) floor = floorWithin(limit - notice);
+    used += floor.chars + (floor.dropped.size > 0 ? notice : 0);
+    const keptRules = new Set([...floor.kept.keys()].map(ruleOf));
+    droppedBlocks = floor.dropped.size;
+    delivery.omitted.rules = new Set([...floor.dropped].map(ruleOf).filter((rule) => !keptRules.has(rule))).size;
     for (const [id, findings] of floor.kept) kept.set(id, findings);
     for (const ref of floor.refs) charged.add(ref);
     for (const ref of resolvedRefs) if (!charged.has(ref)) orphaned.add(ref);
@@ -1757,8 +1820,8 @@ function trim(assembled, limits) {
       for (const [rule, findings] of byRule) {
         const shown = kept.get(rule);
         if (shown === void 0 || shown.length >= Math.min(findings.length, limits.maxMatchesPerRule)) continue;
-        const template = delivery.templates[rule];
-        const delta = measureRuleBlock(rule, [...shown, findings[shown.length]], findings, template, render) - measureRuleBlock(rule, shown, findings, template, render);
+        const template = delivery.templates[ruleOf(rule)];
+        const delta = measureRuleBlock(ruleOf(rule), [...shown, findings[shown.length]], findings, template, render) - measureRuleBlock(ruleOf(rule), shown, findings, template, render);
         if (!fits(delta)) continue;
         used += delta;
         shown.push(findings[shown.length]);
@@ -1771,17 +1834,22 @@ function trim(assembled, limits) {
       const shownFiles = new Set(shown.map((finding) => finding.file));
       const dropped = findings.slice(shown.length);
       delivery.omitted.findings.push({
-        rule,
+        rule: ruleOf(rule),
         count: dropped.length,
-        files: new Set(dropped.map((finding) => finding.file).filter((file) => !shownFiles.has(file))).size
+        files: new Set(dropped.map((finding) => finding.file).filter((file) => !shownFiles.has(file))).size,
+        ...rule === ruleOf(rule) ? {} : { swept: true }
       });
     }
-    delivery.findings = delivery.findings.filter((finding) => kept.get(finding.rule)?.includes(finding) === true);
+    delivery.findings = delivery.findings.filter((finding) => kept.get(blockOf(finding))?.includes(finding) === true);
   }
-  return { delivery, overflow: delivery.omitted.rules > 0 ? assembled.delivery : null, context };
+  return { delivery, overflow: droppedBlocks > 0 ? assembled.delivery : null, context };
 }
-function gate(fresh, work, agent, maxBlocks) {
-  if (!fresh.some(({ rule }) => rule.severity === "error")) return { stop: "allow", work: [] };
+function gate(fresh, work, agent, maxBlocks, swept = /* @__PURE__ */ new Set()) {
+  const blocking = fresh.filter(({ match }) => !swept.has(match.file));
+  const refused = ({ rule, match }) => rule.refuseWrite && work.editedVia.get(match.file) === "shell";
+  if (!blocking.some((finding) => finding.rule.severity === "error" || refused(finding))) {
+    return { stop: "allow", work: [] };
+  }
   if ((work.stopBlocks.get(agent) ?? 0) < maxBlocks) return { stop: "block", work: [{ t: "stopBlock", agent }] };
   return { stop: "capReached", work: [] };
 }
@@ -1793,7 +1861,7 @@ async function decide(input) {
   });
   const context = [...assembled.context, ...trimmed.context];
   if (!input.stopGate) return { delivery: trimmed.delivery, overflow: trimmed.overflow, work: [], context };
-  const gated = gate(assembled.fresh, input.work, input.agent, input.maxBlocks);
+  const gated = gate(assembled.fresh, input.work, input.agent, input.maxBlocks, new Set(input.swept ?? []));
   const delivery = { ...trimmed.delivery, stop: gated.stop };
   if (gated.stop === "allow") return { delivery, overflow: null, work: gated.work, context: [] };
   if (gated.stop === "capReached") return { delivery, overflow: trimmed.overflow, work: gated.work, context: [] };
@@ -1861,6 +1929,11 @@ import { readFile as readFile4 } from "fs/promises";
 import path12 from "path";
 function notices(input) {
   const out = [];
+  for (const { file, rule } of input.refused ?? []) {
+    const key = `refused:${rule}:${file}`;
+    if (input.told.has(key)) continue;
+    out.push({ key, text: `rulecast: the agent changed a protected file with Bash: ${file} (${rule})` });
+  }
   const configKey = `config:${input.currentConfigHash ?? "gone"}`;
   if (input.startConfigHash !== null && input.startConfigHash !== input.currentConfigHash && !input.told.has(configKey)) {
     out.push({
@@ -1922,11 +1995,87 @@ async function commitSession(dir, agent, decideWith) {
   });
 }
 
+// src/core/session/tree.ts
+import { createHash as createHash4 } from "crypto";
+import { lstat, readFile as readFile5 } from "fs/promises";
+import path14 from "path";
+var HASHED_MAX_BYTES = 1024 * 1024;
+var GONE = -1;
+function isGone(state, file) {
+  return state.entries[file]?.[1] === GONE;
+}
+function parseStatus(stdout) {
+  const fields = stdout.split("\0");
+  let head = null;
+  const paths = [];
+  for (let index = 0; index < fields.length; index++) {
+    const field = fields[index];
+    if (field.startsWith("# branch.oid ")) {
+      const oid = field.slice("# branch.oid ".length);
+      head = oid === "(initial)" ? null : oid;
+    } else if (field.startsWith("1 ")) {
+      paths.push(field.split(" ").slice(8).join(" "));
+    } else if (field.startsWith("2 ")) {
+      paths.push(field.split(" ").slice(9).join(" "));
+      const original = fields[++index];
+      if (original) paths.push(original);
+    } else if (field.startsWith("u ")) {
+      paths.push(field.split(" ").slice(10).join(" "));
+    }
+  }
+  return { head, paths };
+}
+async function treeState(root) {
+  const [status, untracked, prefix] = await Promise.all([
+    git(root, ["status", "--porcelain=v2", "--branch", "-z", "--untracked-files=no", "--", "."]),
+    git(root, ["ls-files", "-z", "--others", "--exclude-standard"]),
+    git(root, ["rev-parse", "--show-prefix"])
+  ]);
+  if (!status.ok || !untracked.ok || !prefix.ok) return null;
+  const top = prefix.stdout.trim();
+  const { head, paths } = parseStatus(status.stdout);
+  const files = [
+    ...paths.filter((listed) => listed.startsWith(top)).map((listed) => listed.slice(top.length)),
+    ...untracked.stdout.split("\0").filter(Boolean)
+  ];
+  const entries = {};
+  await Promise.all(
+    files.map(async (file) => {
+      try {
+        const stats = await lstat(path14.join(root, file));
+        entries[file] = stats.isFile() && stats.size <= HASHED_MAX_BYTES ? [stats.mtimeMs, stats.size, await contentHash(path14.join(root, file))] : [stats.mtimeMs, stats.size];
+      } catch (error) {
+        if (!isNotFound(error)) throw error;
+        entries[file] = [0, GONE];
+      }
+    })
+  );
+  return { head, entries };
+}
+async function contentHash(file) {
+  return createHash4("sha1").update(await readFile5(file)).digest("hex").slice(0, 16);
+}
+function same([mtime, size, hash], [wasMtime, wasSize, wasHash]) {
+  if (hash !== void 0 && wasHash !== void 0) return hash === wasHash && size === wasSize;
+  return mtime === wasMtime && size === wasSize;
+}
+function treeChanges(before, after) {
+  if (before.head !== after.head) return { gitOperation: true };
+  const files = /* @__PURE__ */ new Set();
+  for (const [file, entry] of Object.entries(after.entries)) {
+    const was = before.entries[file];
+    if (was === void 0 || !same(entry, was)) files.add(file);
+  }
+  for (const file of Object.keys(before.entries)) if (!(file in after.entries)) files.add(file);
+  return { gitOperation: false, files: [...files].sort() };
+}
+
 // src/core/pipeline.ts
+var TREE_UNAVAILABLE = "rulecast cannot see the working tree here; edits made with Bash are checked only by git hooks and CI";
 var SUMMARY_THRESHOLD = 3;
 var DEFAULT_HINT = "rulecast validate";
 function summaryKey(prefix, ids) {
-  const digest = createHash4("sha256").update([...ids].sort().join("\n")).digest("hex").slice(0, 16);
+  const digest = createHash5("sha256").update([...ids].sort().join("\n")).digest("hex").slice(0, 16);
   return `${prefix}:${digest}`;
 }
 function compileWarnings(errors) {
@@ -1979,7 +2128,8 @@ First: ${text(group[0])}`
   return summarised;
 }
 async function runPipeline(options) {
-  const { project, stateDir, event, registry } = options;
+  const { project, stateDir, registry } = options;
+  let event = options.event;
   const { root, config } = project;
   const log = options.log ?? (() => {
   });
@@ -2005,6 +2155,27 @@ async function runPipeline(options) {
     if (session) await appendWork(session.dir, [{ t: "prompt", agent: session.agent }]);
     return { delivery: emptyDelivery(), failed, deadlineMissed };
   }
+  const empty = () => ({ work: emptyWork(), context: emptyContext() });
+  const relevant = (files) => files.filter((file) => project.rules.some((rule) => rule.matches(file)));
+  if (event.kind === "shell-before") {
+    const open2 = session;
+    const now = open2 ? await treeState(root) : null;
+    if (open2 && now !== null) {
+      const { work } = await readingStore(() => openSession(open2.dir, open2.agent), empty());
+      const reference = referenceState(work, open2.agent);
+      const gap = reference === null ? null : treeChanges(reference, now);
+      const edited = new Set(work.edited);
+      const swept2 = gap === null || gap.gitOperation ? [] : relevant(gap.files.filter((file) => !isGone(now, file) && !edited.has(file)));
+      const id = event.toolUseId === void 0 ? {} : { toolUseId: event.toolUseId };
+      if (session !== null) {
+        await appendWork(open2.dir, [
+          ...swept2.map((file) => ({ t: "swept", file })),
+          { t: "tree", phase: "before", agent: open2.agent, ...id, state: now }
+        ]);
+      }
+    }
+    return { delivery: emptyDelivery(), failed, deadlineMissed };
+  }
   if (event.kind === "reset") {
     if (session) await appendContext(session.dir, session.agent, [{ t: "reset" }]);
     if (!session || restoredFiles === 0) return { delivery: emptyDelivery(), failed, deadlineMissed };
@@ -2023,13 +2194,27 @@ async function runPipeline(options) {
       baseline = await readingStore(() => readBaseline(dir), baseline);
     }
   }
-  const empty = () => ({ work: emptyWork(), context: emptyContext() });
   const view = session ? await readingStore(() => openSession(session.dir, session.agent), empty()) : empty();
   const disabled = new Set(view.work.disabled.keys());
   const resolver = createReferenceResolver(root);
   const detection = detectionFor(project, registry, stateDir, resolver);
   const workRecords = [];
-  const relevant = (files) => files.filter((file) => project.rules.some((rule) => rule.matches(file)));
+  let via;
+  let swept = [];
+  const refused = [];
+  if (event.kind === "shell-after") {
+    const open2 = session;
+    const now = open2 ? await treeState(root) : null;
+    if (!open2 || now === null) return { delivery: emptyDelivery(), failed, deadlineMissed };
+    const reference = referenceState(view.work, open2.agent, event.toolUseId);
+    const id = event.toolUseId === void 0 ? {} : { toolUseId: event.toolUseId };
+    await appendWork(open2.dir, [{ t: "tree", phase: "after", agent: open2.agent, ...id, state: now }]);
+    const call = reference === null ? null : treeChanges(reference, now);
+    const files = call === null || call.gitOperation ? [] : relevant(call.files.filter((file) => !isGone(now, file)));
+    if (files.length === 0) return { delivery: emptyDelivery(), failed, deadlineMissed };
+    via = "shell";
+    event = { ...event, kind: "edit", files };
+  }
   if (event.kind === "guard") {
     const open2 = session;
     const delivery = await guardWrite({
@@ -2083,15 +2268,33 @@ async function runPipeline(options) {
     if (event.completeRead) agentRead = event.files[0] ?? null;
     if (session) await appendBaseline(session.dir, await touchRecords(baselineInput, baseline, relevant(event.files)));
   }
+  if (event.kind === "start" && session) {
+    const tree = await treeState(root);
+    if (tree === null) warnings.push({ key: "tree-unavailable", text: TREE_UNAVAILABLE });
+    else {
+      await appendWork(session.dir, [{ t: "tree", phase: "start", agent: session.agent, state: tree }]);
+      const start = await startRecords(baselineInput, baseline, relevant(Object.keys(tree.entries).sort()));
+      if (start.records.length > 0) await appendBaseline(session.dir, start.records);
+      if (start.skipped > 0) {
+        log(`session start: ${start.skipped} dirty files past the snapshot limits; their baseline is the start commit`);
+      }
+    }
+  }
   if (event.kind === "edit" || event.kind === "verify") {
     let requested = relevant(event.files);
     if (event.kind === "edit" && session) {
       await appendWork(
         session.dir,
-        requested.map((file) => ({ t: "edited", file }))
+        requested.map((file) => ({ t: "edited", file, ...via === void 0 ? {} : { via } }))
       );
     }
-    if (event.kind === "verify" && event.files.length === 0 && session) requested = relevant(view.work.edited);
+    if (event.kind === "verify" && event.files.length === 0 && session) {
+      requested = relevant(view.work.edited);
+      if (options.stopGate === true) {
+        swept = await sweep(session, new Set(requested));
+        requested = [...requested, ...swept];
+      }
+    }
     const read = contentReader(root, event.kind === "verify" ? event.content ?? WORKTREE : WORKTREE);
     const stage = await changesFor(
       baselineInput,
@@ -2153,17 +2356,27 @@ async function runPipeline(options) {
     }
     warnings.push(...detectorWarnings(output.errors, session === null ? "run" : "session"));
     ignored = output.ignored;
-    if (options.stopGate === true && event.kind === "verify" && session !== null) {
+    const shellEdited = (file) => via === "shell" ? requested.includes(file) : view.work.editedVia.get(file) === "shell";
+    const seen = /* @__PURE__ */ new Set();
+    for (const { rule, match, status } of findings) {
+      if (status !== "new" || !rule.refuseWrite || !shellEdited(match.file)) continue;
+      if (seen.has(`${rule.id} ${match.file}`)) continue;
+      seen.add(`${rule.id} ${match.file}`);
+      refused.push({ file: match.file, rule: rule.id, dirtyAtStart: dirtyAtStart(view.work, match.file) });
+    }
+    const atStop = options.stopGate === true && event.kind === "verify" && session !== null;
+    if (session !== null && (atStop || refused.length > 0)) {
       told = notices({
-        startConfigHash: baseline.startConfigHash ?? null,
-        currentConfigHash: await configHash(root),
-        ignored: ignored.map(({ rule, match, reason }) => ({
+        startConfigHash: atStop ? baseline.startConfigHash ?? null : null,
+        currentConfigHash: atStop ? await configHash(root) : null,
+        ignored: atStop ? ignored.map(({ rule, match, reason }) => ({
           rule: rule.id,
           match,
           reason,
           status: classify(match, rule.scope, rule.id, baselineChanges, fingerprints)
-        })),
-        told: view.work.noticed
+        })) : [],
+        told: view.work.noticed,
+        refused
       });
       for (const notice of told) for (const key of notice.key.split("\n")) workRecords.push({ t: "noticed", key });
     }
@@ -2193,6 +2406,21 @@ async function runPipeline(options) {
       }
     }
   }
+  async function sweep(open2, edited) {
+    const now = await treeState(root);
+    let found = [];
+    if (now !== null) {
+      const reference = referenceState(view.work, open2.agent);
+      const gap = reference === null ? null : treeChanges(reference, now);
+      if (gap !== null && !gap.gitOperation) found = relevant(gap.files.filter((file) => !edited.has(file)));
+      await appendWork(open2.dir, [
+        ...found.map((file) => ({ t: "swept", file })),
+        { t: "tree", phase: "stop", agent: open2.agent, state: now }
+      ]);
+    }
+    const all = [.../* @__PURE__ */ new Set([...relevant(view.work.swept), ...found])].filter((file) => !edited.has(file));
+    return now === null ? all : all.filter((file) => !isGone(now, file));
+  }
   const inputFor = (state) => ({
     agent: session?.agent ?? "main",
     findings,
@@ -2206,21 +2434,24 @@ async function runPipeline(options) {
     maxBlocks: config.stopGate.maxBlocks,
     maxContextChars: options.maxContextChars,
     maxMatchesPerRule: config.maxMatchesPerRule,
-    stopGate: options.stopGate === true && event.kind === "verify" && session !== null
+    stopGate: options.stopGate === true && event.kind === "verify" && session !== null,
+    ...via === void 0 ? {} : { via },
+    ...swept.length === 0 ? {} : { swept },
+    ...refused.length === 0 ? {} : { refused }
   });
-  const home = path14.dirname(path14.dirname(stateDir));
+  const home = path15.dirname(path15.dirname(stateDir));
   const persisted = (decision) => {
     if (decision.overflow !== null) {
       let written = null;
       try {
-        written = writeOverflow(path14.join(agentDir(root), "deliveries"), event.session?.id ?? null, decision.overflow);
+        written = writeOverflow(path15.join(agentDir(root), "deliveries"), event.session?.id ?? null, decision.overflow);
       } catch {
         written = null;
       }
-      decision.delivery.overflowPath = written === null ? null : path14.relative(root, written).split(path14.sep).join("/");
+      decision.delivery.overflowPath = written === null ? null : path15.relative(root, written).split(path15.sep).join("/");
     }
     for (const reference of decision.delivery.references) {
-      if (reference.location === void 0 || !path14.isAbsolute(reference.location)) continue;
+      if (reference.location === void 0 || !path15.isAbsolute(reference.location)) continue;
       const copied = copyIntoProject(root, home, reference.location);
       if (copied !== null) reference.location = copied;
     }

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   createRegistry,
   renderBacklog,
   summarise
-} from "./chunk-IKONOTME.js";
+} from "./chunk-MB4F7ZXC.js";
 import {
   CONFIG_FILE,
   LockTimeoutError,
@@ -48,7 +48,7 @@ import {
   stagedFiles,
   withLock,
   withScratchTree
-} from "./chunk-WUFU4LW2.js";
+} from "./chunk-Y3FXJRZB.js";
 import {
   VERSION,
   detectorCacheDir,
@@ -64,7 +64,7 @@ import {
   renderTemplate,
   scanHeadings,
   tagsOf
-} from "./chunk-DQUCE2IK.js";
+} from "./chunk-4XS34SYW.js";
 import {
   Cancelled
 } from "./chunk-K37BHCEK.js";
@@ -218,24 +218,29 @@ async function hookCommandResolves(root, signal) {
 async function hookState(root, adapter, verifyMs) {
   const install = installOf(adapter);
   const command = install.command(existsSync2(path2.join(root, "node_modules", ".bin", "rulecast")));
+  let partial = null;
   for (const { file } of install.scopes) {
     const current = await readSettings(root, file);
     if (current === null) continue;
     const merged = inFile(file, () => install.merge(current.value, command, verifyMs));
-    if (merged.added.length === 0) return { file, stale: merged.updated ?? [] };
+    if (merged.added.length === 0) return { file, stale: merged.updated ?? [], missing: [] };
+    const ours = inFile(file, () => install.remove(current.value)).removed.length > 0;
+    if (ours && partial === null) partial = { file, stale: merged.updated ?? [], missing: merged.added };
   }
-  return null;
+  return partial;
 }
 async function installHooks(root, adapter, scope, verifyMs) {
   const install = installOf(adapter);
   const command = install.command(existsSync2(path2.join(root, "node_modules", ".bin", "rulecast")));
   const already = await hookState(root, adapter, verifyMs);
-  if (already !== null && already.stale.length === 0) return { file: already.file, added: [] };
+  if (already !== null && already.stale.length === 0 && already.missing.length === 0) {
+    return { file: already.file, added: [] };
+  }
   if (already !== null) {
     const current2 = (await readSettings(root, already.file))?.value ?? {};
     const merged2 = inFile(already.file, () => install.merge(current2, command, verifyMs));
     await writeSettings(root, already.file, merged2.settings);
-    return { file: already.file, added: [], updated: merged2.updated ?? [] };
+    return { file: already.file, added: merged2.added, updated: merged2.updated ?? [] };
   }
   const target = install.scopes.find((candidate) => candidate.scope === scope);
   if (!target) throw new UsageError(`${adapter.name} has no ${scope} settings`);
@@ -274,12 +279,18 @@ async function loadProjectConfig(root, command) {
 }
 function printInstall(io, adapter, result) {
   const updated = result.updated ?? [];
-  io.stdout(
-    updated.length > 0 ? `updated ${adapter.label} hooks in ${result.file} to the current command: ${updated.join(", ")}
-` : result.added.length === 0 ? `${adapter.label} hooks already installed in ${result.file}
-` : `installed ${adapter.label} hooks in ${result.file}: ${result.added.join(", ")}
-`
-  );
+  if (updated.length > 0) {
+    io.stdout(`updated ${adapter.label} hooks in ${result.file} to the current command: ${updated.join(", ")}
+`);
+  }
+  if (result.added.length > 0) {
+    io.stdout(`installed ${adapter.label} hooks in ${result.file}: ${result.added.join(", ")}
+`);
+  }
+  if (updated.length === 0 && result.added.length === 0) {
+    io.stdout(`${adapter.label} hooks already installed in ${result.file}
+`);
+  }
 }
 async function fetchMissingRepos(config, io) {
   const home = cacheHome(io.env);
@@ -412,6 +423,10 @@ function naming(rules) {
   if (rules.length <= 3) return ` (${rules.join(", ")})`;
   return ` (${rules.slice(0, 3).join(", ")} and ${rules.length - 3} more)`;
 }
+function missingNames(groups) {
+  const names = groups.map((group) => /ToolUse/.test(group) ? /\((.*)\)$/.exec(group)?.[1] ?? group : group);
+  return [...new Set(names)].join(", ");
+}
 function plural(count, noun) {
   return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
@@ -468,9 +483,10 @@ async function doctorCommand(root, args, registry, io) {
     const state = await hookState(root, adapter, project.config.timeouts.verifyMs);
     const file = state?.file ?? null;
     const stale = (state?.stale ?? []).length > 0;
-    const level = file === null || !resolves || stale ? "warning" : "ok";
+    const missing = state?.missing ?? [];
+    const level = file === null || !resolves || stale || missing.length > 0 ? "warning" : "ok";
     count(level);
-    const detail = file === null ? "not installed (run rulecast install)" : stale ? `${file} \u2014 but the hooks use an old command; run rulecast install` : resolves ? file : `${file} \u2014 but "rulecast" is on neither the PATH nor node_modules/.bin, so the hooks do nothing. Add it to the project (pnpm add -D @syv-ai/rulecast) and run rulecast install again.`;
+    const detail = file === null ? "not installed (run rulecast install)" : missing.length > 0 ? `${file} \u2014 but hooks for ${missingNames(missing)} missing; run rulecast install` : stale ? `${file} \u2014 but the hooks use an old command; run rulecast install` : resolves ? file : `${file} \u2014 but "rulecast" is on neither the PATH nor node_modules/.bin, so the hooks do nothing. Add it to the project (pnpm add -D @syv-ai/rulecast) and run rulecast install again.`;
     io.stdout(line(level, adapter.label, detail));
   }
   io.stdout("\ncache\n");

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as Adapter, e as Delivery, g as DetectorRun, h as DetectorRuleInput, M as Match, i as Detector, j as AnyDetector, k as AdapterInput, E as Event } from './types-Dcra5LXR.js';
-export { l as AdapterInstall, m as Cache, n as ChangeSet, b as CheckResult, o as CompiledDetector, a as CompiledRule, p as ContentSource, q as DeliveredReference, s as DetectorCheck, t as DetectorEvent, D as DetectorRegistry, u as DetectorResult, d as DetectorRule, c as DetectorSettings, v as DetectorWarm, w as EventKind, F as Finding, I as InstallScope, x as LLM_PROVIDERS, y as LlmFinding, f as LlmProvider, L as LlmProviderName, z as LlmRequest, B as LlmSettings, G as LlmUnavailableError, O as Omitted, H as ReferenceMode, J as ReferenceSpec, K as RenderOptions, N as ResolvedReference, P as RuleExample, Q as RuleExamples, T as RuleScope, U as Severity, S as Stage, V as TouchRule, W as WriteIntent, X as createRegistry, Y as defaultDetectorSettings, Z as emptyDelivery, _ as isDetectorRule, r as renderAgentText } from './types-Dcra5LXR.js';
+import { A as Adapter, e as Delivery, g as DetectorRun, h as DetectorRuleInput, M as Match, i as Detector, j as AnyDetector, k as AdapterInput, E as Event } from './types-D5y_IokF.js';
+export { l as AdapterInstall, m as Cache, n as ChangeSet, b as CheckResult, o as CompiledDetector, a as CompiledRule, p as ContentSource, q as DeliveredReference, s as DetectorCheck, t as DetectorEvent, D as DetectorRegistry, u as DetectorResult, d as DetectorRule, c as DetectorSettings, v as DetectorWarm, w as EventKind, F as Finding, I as InstallScope, x as LLM_PROVIDERS, y as LlmFinding, f as LlmProvider, L as LlmProviderName, z as LlmRequest, B as LlmSettings, G as LlmUnavailableError, O as Omitted, H as ReferenceMode, J as ReferenceSpec, K as RenderOptions, N as ResolvedReference, P as RuleExample, Q as RuleExamples, T as RuleScope, U as Severity, S as Stage, V as TouchRule, W as WriteIntent, X as createRegistry, Y as defaultDetectorSettings, Z as emptyDelivery, _ as isDetectorRule, r as renderAgentText } from './types-D5y_IokF.js';
 import 'zod';
 
 declare const claudeCodeAdapter: Adapter;
@@ -119,7 +119,7 @@ declare function runTool(command: string, args: readonly string[], options: {
 }): Promise<string>;
 
 /** The running rulecast version. test/core/version.test.ts keeps it equal to package.json. */
-declare const VERSION = "0.4.0";
+declare const VERSION = "0.5.0";
 
 declare const builtinDetectors: readonly AnyDetector[];
 

package/dist/index.js

@@ -9,7 +9,7 @@ import {
   repoRelativeTo,
   runTool,
   summarise
-} from "./chunk-IKONOTME.js";
+} from "./chunk-MB4F7ZXC.js";
 import {
   LlmUnavailableError,
   VERSION,
@@ -25,7 +25,7 @@ import {
   readSourceFile,
   renderAgentText,
   sourceReader
-} from "./chunk-DQUCE2IK.js";
+} from "./chunk-4XS34SYW.js";
 
 // src/testing/adapter-contract.ts
 import assert from "assert/strict";
@@ -79,7 +79,7 @@ function adapterContract(adapter, fixture) {
           if (!event) continue;
           assert.ok(event.cwd.length > 0, `${name}: event.cwd must not be empty`);
           for (const file of event.files) assert.equal(typeof file, "string", `${name}: files must be strings`);
-          if (event.kind === "prompt" || event.kind === "reset") {
+          if (["prompt", "reset", "start", "shell-before", "shell-after"].includes(event.kind)) {
             assert.deepEqual(event.files, [], `${name}: ${event.kind} carries no files`);
           }
         }

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
-import { D as DetectorRegistry, C as Config, a as CompiledRule, b as CheckResult, c as DetectorSettings, d as DetectorRule, M as Match, E as Event, e as Delivery, L as LlmProviderName, f as LlmProvider } from './types-Dcra5LXR.js';
-export { R as RuleEntry, S as Stage, r as renderAgentText } from './types-Dcra5LXR.js';
+import { D as DetectorRegistry, C as Config, a as CompiledRule, b as CheckResult, c as DetectorSettings, d as DetectorRule, M as Match, E as Event, e as Delivery, L as LlmProviderName, f as LlmProvider } from './types-D5y_IokF.js';
+export { R as RuleEntry, S as Stage, r as renderAgentText } from './types-D5y_IokF.js';
 import 'zod';
 
 type Checkout = {

package/dist/internal.js

@@ -11,13 +11,13 @@ import {
   fixedRepo,
   projectStateDir,
   runPipeline
-} from "./chunk-WUFU4LW2.js";
+} from "./chunk-Y3FXJRZB.js";
 import {
   MODEL_ALIASES,
   providerByName,
   renderAgentText,
   resolveModel
-} from "./chunk-DQUCE2IK.js";
+} from "./chunk-4XS34SYW.js";
 export {
   CONFIG_FILE,
   MANIFEST_FILE,

package/dist/{types-Dcra5LXR.d.ts → types-D5y_IokF.d.ts}

@@ -1,6 +1,10 @@
 import { ZodType, ZodTypeDef, z } from 'zod';
 
-type EventKind = "touch" | "edit" | "verify" | "prompt" | "reset" | "guard";
+/**
+ * `start`: the session began or resumed. `shell-before` / `shell-after`: around one call of the
+ * agent's shell tool, whose writes rulecast finds by comparing the working tree (session/tree.ts).
+ */
+type EventKind = "touch" | "edit" | "verify" | "prompt" | "reset" | "guard" | "start" | "shell-before" | "shell-after";
 type DetectorEvent = "edit" | "verify";
 type Severity = "error" | "warning";
 type ReferenceMode = "inject" | "read";
@@ -34,8 +38,12 @@ type ContentSource = {
 };
 interface Event {
     kind: EventKind;
-    /** Repo-relative paths (adapters may give absolute ones; the hook command converts them). Empty for prompt and reset. */
+    /** Repo-relative paths (adapters may give absolute ones; the hook command converts them). Empty for prompt, reset, start and shell events. */
     files: string[];
+    /** shell events: pairs a call's before and after states when the agent's payloads carry an id. */
+    toolUseId?: string;
+    /** shell-after: the command exited non-zero. It may still have written files; an adapter may answer it differently. */
+    failed?: boolean;
     /** guard only: what the agent is about to write to `files[0]`. */
     intent?: WriteIntent;
     /** touch from a read: the whole file was read. */
@@ -246,6 +254,7 @@ interface Omitted {
         rule: string;
         count: number;
         files: number;
+        swept?: true;
     }[];
     /** Rules dropped whole, with their findings: only when the floor itself did not fit. */
     rules: number;
@@ -267,6 +276,23 @@ interface Delivery {
     omitted: Omitted;
     /** Absolute path of the untrimmed delivery, written when even the floor did not fit; null when it did. */
     overflowPath: string | null;
+    /** The findings are in files the agent's shell command changed: the title says so. Absent: an edit tool. */
+    via?: "shell";
+    /**
+     * Files with findings that changed outside the agent's tool calls (spec §9, Shell edits): printed
+     * under their own heading, after the agent's own, and never blocking. Set at a stop.
+     */
+    swept?: string[];
+    /**
+     * Findings of `refuse_write` rules in files the agent changed with its shell (spec §9, Shell
+     * edits): the write could not be refused before it happened, so the agent is told to revert it.
+     * `dirtyAtStart`: the file had the user's uncommitted changes, so reverting the whole file is wrong.
+     */
+    refused?: {
+        file: string;
+        rule: string;
+        dirtyAtStart: boolean;
+    }[];
     /**
      * For the user, not the agent (spec §9, Oversight): the config changed this session, ignores were
      * added. Attached after the budget is spent and never part of agent context under a hook adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syv-ai/rulecast",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Deliver project conventions to coding agents at the moment they matter.",
   "keywords": [
     "claude-code",