@synovitec/trellis 0.0.0-stage → 0.6.0-rc.2

package/src/agents/hooks.mjs

@@ -0,0 +1,780 @@
+// `trellis hook <event>`: what Claude Code runs at four moments of a session. The logic lives here,
+// in the package, so updating Trellis updates every repository's hooks at once.
+//
+//   session-start  snapshot the repository and the config; hand the agent the routing, what is
+//                  broken, and what it will be checked on
+//   pre-tool       refuse an edit the agent has not looked before making (the graph, the schema),
+//                  and any command that would tamper with the evidence or with Trellis itself
+//   post-tool      record evidence the moment a real tool call succeeds; one graph reminder
+//   stop           run the scanners itself and judge the session; "block" sends the agent back
+//                  (exit 2), up to `maxBlocks` times, then the person decides
+//
+// Evidence is recorded as it happens and only for a call Claude Code itself logged, never
+// reconstructed from what the agent says; the hooks fail closed and visibly.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_FILE, enabledTools, validateConfig } from "../core/config.mjs";
+import { parseJson } from "../core/context.mjs";
+import { mcpServers } from "../tools/registry.mjs";
+import { diagnose } from "../commands/doctor.mjs";
+import { ROLES } from "../tools/roles.mjs";
+import { readSession, editedPath, commandOf, relativeTo } from "./transcript.mjs";
+import { agentConfig, evaluate, gate, isBrowser, isContext7, isGraphify, isSchemaLookup, isSearch, mcpParts, modeOf, onOrigin, RULES } from "./rules.mjs";
+import { commandsIn, packagesAdded } from "./shell.mjs";
+import { changedSince, contentHash, dirtyFiles, excludeText, fileAt, flaggedFiles, ignoredEntries, ignoreRules, isRepo, sessionCommits, sessionRevs, startPoint, stashCount, headOf } from "./git.mjs";
+import { emptyLedger, loadState, prune, record, saveState, testOverride } from "./state.mjs";
+import { appendEvent, readWindow } from "../core/evidence.mjs";
+import { treeOf, worktreeDiff } from "../core/diff.mjs";
+import { matchesAny } from "./glob.mjs";
+import { addedDependencies, dependenciesOf } from "./manifests.mjs";
+
+/** @typedef {import("../core/context.mjs").Context} Context */
+/** @typedef {import("../core/config.mjs").Config} Config */
+/** @typedef {import("./state.mjs").SessionState} SessionState */
+/** @typedef {{ code: number, stdout?: string, stderr?: string }} HookResult */
+
+export const EVENTS = Object.freeze(["session-start", "pre-tool", "post-tool", "stop"]);
+
+/** After this many searches without a graph query, the reminder fires (once a session). */
+const NUDGE_AT = 3;
+/** Paths that hold the evidence, or Trellis itself. Writing them is tampering. */
+// The transcripts folder as a whole: `find ~/.claude/projects -name '*.jsonl' -exec ...` names
+// the folder, not a .jsonl path.
+const EVIDENCE = /trellis[\\/]sessions|trellis-sessions|info[\\/]exclude|\.git[\\/]logs|\.claude[\\/]projects([\\/]|\b)|node_modules[\\/]@synovitec[\\/]trellis/i;
+/** The signing key: not even reading it is harmless, since it signs evidence. */
+const KEY = /\.trellis([\\/]|\b)/i;
+/** A person's step named anywhere in a command, quoted or as list items: `trellis approve`, `'trellis', 'approve'`. */
+const NESTED_PERSON_STEP = /trellis(\.mjs)?["']?\s*[,\s]\s*["']?(approve|checkpoint|evidence|mcp["']?\s*[,\s]\s*["']?trust)\b/i;
+/** Clearing the markers that say an agent is at work: `env -u CLAUDECODE`, `unset`, `CLAUDECODE=`, PowerShell's Remove-Item env:. */
+const UNMARK = /(?:\s-u\s*|--unset[\s=]|\bunset\s+(?:-\S+\s+)*|Remove-Item\s+(?:-\S+\s+)*env:)(?:CLAUDECODE|TRELLIS_AGENT)\b|\b(?:CLAUDECODE|TRELLIS_AGENT)\s*=|\benv\s+(?:-\S+\s+)*(?:-i|--ignore-environment)\b/i;
+/** Setting one of Trellis's test overrides, in sh, cmd or PowerShell (`$env:NAME =`). */
+const OVERRIDES = /\b(TRELLIS_(STATE_DIR|KEY_FILE|AGENTSHIELD|GRAPHIFY)|NODE_TEST_CONTEXT)\s*=/i;
+const INDEX_FLAGS = /update-index\b[^\n;&|]*--(no-)?(assume-unchanged|skip-worktree)/;
+/** Commands that only read. Anything else naming evidence is treated as a write. */
+const READERS = new Set(["cat", "ls", "head", "tail", "less", "more", "type", "get-content", "stat", "wc", "grep", "rg", "find", "file", "git"]);
+/** What turns a `find` from a reader into a writer: it deletes, runs a command, or writes a file. */
+const FIND_ACTIONS = new Set(["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"]);
+/** The pinned AgentShield the Stop hook runs. */
+export const AGENTSHIELD = "ecc-agentshield@1.6.0";
+
+/**
+ * The repository a hook judges: the project Claude Code names, else the nearest folder above the
+ * session's working folder that holds a trellis.config.json.
+ * @param {Record<string, any>} input
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} fallback
+ */
+export function hookRoot(input, env, fallback) {
+  if (env.CLAUDE_PROJECT_DIR) return env.CLAUDE_PROJECT_DIR;
+  let dir = resolve(typeof input.cwd === "string" ? input.cwd : fallback);
+  for (;;) {
+    if (existsSync(join(dir, CONFIG_FILE))) return dir;
+    const up = dirname(dir);
+    if (up === dir) return typeof input.cwd === "string" ? input.cwd : fallback;
+    dir = up;
+  }
+}
+
+/**
+ * A hash of Trellis's own code as installed. Code that checks itself cannot catch every change
+ * to itself; this catches the edits that leave the check running, and the guard and the deny
+ * rules keep the agent's tools away from the rest.
+ */
+export function selfHash(root = fileURLToPath(new URL("../../", import.meta.url))) {
+  const h = createHash("sha256");
+  const walk = (/** @type {string} */ dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (/\.(mjs|js|json)$/.test(e.name)) h.update(e.name).update(readFileSync(p));
+    }
+  };
+  for (const d of ["src", "bin"]) if (existsSync(join(root, d))) walk(join(root, d));
+  return h.digest("hex");
+}
+
+/**
+ * @param {string | null | undefined} raw
+ * @returns {{ config: Config | null, errors: string[] }}
+ */
+function readConfig(raw) {
+  if (raw == null) return { config: null, errors: [] };
+  const config = parseJson(raw);
+  if (config == null) return { config: null, errors: [`${CONFIG_FILE} is not valid JSON`] };
+  const errors = validateConfig(config);
+  return { config: errors.length ? null : config, errors };
+}
+
+/**
+ * The config a session is judged by: the one it started with, and only that one. A config broken
+ * at the start fails closed: a permissive one written mid-session must not take its place. Without
+ * a start record (reported on its own), the current config is all there is.
+ * @param {SessionState | null} state
+ * @param {string | null} raw
+ */
+function judgedConfig(state, raw) {
+  const judged = readConfig(state ? state.configText : raw);
+  return { config: judged.config, errors: judged.config ? [] : judged.errors };
+}
+
+/**
+ * @param {string} event
+ * @param {Record<string, any>} input  the hook's JSON from stdin
+ * @param {Context} ctx
+ * @param {{ env?: NodeJS.ProcessEnv, now?: number }} [opts]
+ * @returns {HookResult}
+ */
+export function handleHook(event, input, ctx, opts = {}) {
+  const env = opts.env ?? process.env;
+  const raw = ctx.read(CONFIG_FILE);
+  if (event === "session-start") return sessionStart(input, ctx, raw, env, opts.now ?? Date.now());
+  const { state, status } = loadState(ctx.root, input.session_id, env);
+  const { config, errors } = judgedConfig(status === "ok" ? state : null, raw);
+  if (event === "pre-tool") return preTool(input, ctx, config, state);
+  if (event === "post-tool") return postTool(input, ctx, config, state, env);
+  if (event === "stop") return stop(input, ctx, raw, { config, errors }, { state, status }, env);
+  return { code: 0, stderr: `trellis hook: unknown event "${event}" (known: ${EVENTS.join(", ")})\n` };
+}
+
+/**
+ * What a hook does when Trellis itself fails: closed, and said. Stop sends the agent back once
+ * (then the person is told); pre-tool refuses the call. A crash must never read as a pass.
+ * @param {string} event
+ * @param {Record<string, any>} input
+ * @param {unknown} err
+ * @returns {HookResult}
+ */
+export function hookFailure(event, input, err) {
+  const why = err instanceof Error ? err.message : String(err);
+  if (event === "stop") {
+    if (input?.stop_hook_active) return tell(`the session check could not run (${why}); the session was not checked: decide yourself, and fix the cause.`);
+    return { code: 2, stderr: `[trellis] The session check could not run (${why}). Tell the person: the work was not checked.\n` };
+  }
+  if (event === "pre-tool") return deny(`Trellis could not check this call (${why}). Tell the person.`);
+  return { code: 1, stderr: `[trellis] hook ${event} failed: ${why}\n` };
+}
+
+/** @param {Context} ctx @param {string | null} raw @param {number} now @returns {SessionState} */
+function snapshot(ctx, raw, now) {
+  const repo = isRepo(ctx.root);
+  const start = repo ? startPoint(ctx.root) : { tips: [], remotes: [], reflog: 0 };
+  return {
+    v: 2,
+    startedAt: now,
+    head: repo ? headOf(ctx.root) : null,
+    tips: start.tips,
+    remotes: start.remotes,
+    reflog: start.reflog,
+    dirty: repo ? dirtyFiles(ctx.root) : {},
+    flagged: repo ? flaggedFiles(ctx.root) : [],
+    exclude: repo ? excludeText(ctx.root) : null,
+    ignored: repo ? ignoredEntries(ctx.root) : [],
+    ignoreRules: repo ? ignoreRules(ctx.root) : null,
+    stashes: repo ? stashCount(ctx.root) : 0,
+    configText: raw,
+    self: selfHash(),
+    blocks: 0,
+    ledger: emptyLedger(),
+  };
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {Context} ctx
+ * @param {string | null} raw
+ * @param {NodeJS.ProcessEnv} env
+ * @param {number} now
+ * @returns {HookResult}
+ */
+function sessionStart(input, ctx, raw, env, now) {
+  // Once per session, when it starts: a resume or a compaction fires this again and must keep the
+  // real start. With the record gone by then, starting a fresh one would make everything done
+  // before it the baseline, so it stays missing and Stop reports it.
+  const starting = input.source == null || input.source === "startup" || input.source === "clear";
+  if (input.session_id && starting && loadState(ctx.root, input.session_id, env).status === "missing") {
+    prune(ctx.root, env, now);
+    saveState(ctx.root, input.session_id, snapshot(ctx, raw, now), env);
+  }
+  const { config, errors } = readConfig(raw);
+  const lines = [];
+  if (errors.length) lines.push(`[trellis] ${errors.join("; ")}. The session cannot be checked against its rules until this is fixed: tell the person.`);
+  const enabled = enabledTools(ctx, config);
+  lines.push("[trellis] The tools of this repository, by role. Use them: what you do is checked as you work and when you stop.");
+  for (const role of ROLES) {
+    const tools = enabled.filter((e) => e.tool.role === role.id);
+    if (tools.length) lines.push(`[trellis] ${role.title}: ${tools.map((e) => `${e.tool.name} (${e.tool.use})`).join(" | ")}`);
+  }
+  const broken = diagnose(ctx).results.filter((r) => r.status === "missing" || r.status === "unwired");
+  if (broken.length) lines.push(`[trellis] Not working here: ${broken.map((r) => `${r.name} ${r.status}`).join(", ")}. Do not claim a check ran that cannot run.`);
+  const cfg = agentConfig(config?.agents);
+  const ids = new Set(enabled.map((e) => e.tool.id));
+  // What is checked is said; how strictly is not: a rule the agent knows only warns is a rule it skips.
+  const active = RULES.filter((r) => (!r.needs || ids.has(r.needs)) && modeOf(r, cfg) !== "off" && r.id !== "evidence-intact");
+  if (active.length) lines.push(`[trellis] You are checked on: ${active.map((r) => r.title.toLowerCase()).join("; ")}.`);
+  lines.push("[trellis] Off limits: Trellis's session files, its key (~/.trellis), its installed code, the transcripts, git's index flags, info/exclude and logs.");
+  return { code: 0, stdout: `${lines.join("\n")}\n` };
+}
+
+/** @param {string} reason */
+const deny = (reason) => ({ code: 0, stdout: `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: `[trellis] ${reason}` } })}\n` });
+/** @param {string} message */
+const tell = (message) => ({ code: 0, stdout: `${JSON.stringify({ systemMessage: `[trellis] ${message}` })}\n` });
+
+const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
+
+/**
+ * An everyday command that takes Trellis out of node_modules: `git clean -x`/`-X` (node_modules
+ * is ignored, so it goes), an install or prune without devDependencies (Trellis is one), or an
+ * install of Trellis itself, which could put another version, or another package, in its place.
+ * @param {{ prog: string, args: string[] }} c
+ */
+function removesTrellis(c) {
+  if (c.prog === "git") return c.args.includes("clean") && c.args.some((a) => /^-[a-zA-Z]*[xX]/.test(a));
+  if (!PACKAGE_MANAGERS.includes(c.prog)) return false;
+  const withoutDev = c.args.some((a, i) => ["--omit=dev", "--production", "--prod", "--production=true"].includes(a) || (a === "--omit" && c.args[i + 1] === "dev"));
+  const installsTrellis = ["install", "i", "add", "ci", "update", "up", "upgrade"].includes(c.args[0] ?? "") && c.args.some((a) => /@synovitec\/trellis/.test(a));
+  return withoutDev || installsTrellis;
+}
+
+/**
+ * A git command that would make the session's own commits read as received from a remote: a
+ * remote-tracking ref moved by `update-ref`, a fetch whose refspec writes one (`git fetch .
+ * HEAD:refs/remotes/origin/main` is logged as a fetch), or a reflog rewritten.
+ * @param {{ prog: string, args: string[] }} c
+ */
+const rewritesRemoteHistory = (c) =>
+  c.prog === "git" &&
+  ((c.args.includes("update-ref") && c.args.some((a) => /refs\/remotes\//.test(a))) ||
+    (c.args.includes("fetch") && c.args.some((a) => /:\+?refs\/remotes\//.test(a))) ||
+    (c.args.includes("reflog") && c.args.some((a) => a === "expire" || a === "delete")));
+
+/**
+ * Why a shell command must not run, or null: it would forge evidence, hide work from git, or
+ * take Trellis out from under the session.
+ * @param {string} cmd
+ */
+export function tampering(cmd) {
+  const cmds = commandsIn(cmd);
+  // The paths as the shell sees them too: `.trel''lis` and `.tr\ellis` are `.trellis` once it has
+  // removed the quotes and escapes, and a regex over the raw text would miss them.
+  const seen = [cmd, ...cmds.map((c) => [c.prog, ...c.args].join(" "))].join("\n");
+  if (INDEX_FLAGS.test(seen)) return "Telling git to ignore a file's changes (update-index) hides work from the session's checks. Leave the index flags alone.";
+  if (KEY.test(seen)) return "Trellis's signing key (~/.trellis) is off limits.";
+  if (UNMARK.test(seen)) return "Clearing CLAUDECODE or TRELLIS_AGENT makes the session's commits read as a person's. Leave the session's markers alone.";
+  if (OVERRIDES.test(seen)) return "Trellis's test settings (TRELLIS_STATE_DIR, TRELLIS_KEY_FILE, ...) move the evidence and the key away from where the commit checkpoint looks. They are for Trellis's own tests, not a session.";
+  if (cmds.some((c) => c.prog === "trellis" && c.args[0] === "hook")) return "Trellis's hooks are Claude Code's to run, not the session's: running one by hand would record evidence for a call that never happened.";
+  if (cmds.some((c) => c.prog === "trellis" && (c.args[0] === "approve" || c.args[0] === "checkpoint" || c.args[0] === "evidence"))) {
+    return "Approving a change (approve) and closing its evidence window (checkpoint) are the person's and git's steps, not an agent's. If a person must look, stop with `trellis escalate \"<why>\"`.";
+  }
+  if (cmds.some((c) => c.prog === "trellis" && c.args[0] === "mcp" && c.args[1] === "trust")) {
+    return "Trusting an MCP server lets the gateway run it as a command on this machine: that is the person's decision. Ask them to run `trellis mcp trust` themselves.";
+  }
+  // The same steps nested in another command's argument: `script -qc "trellis approve"`, a
+  // Python pty spawning ['trellis', 'approve'], which would give them the terminal they ask for.
+  if (NESTED_PERSON_STEP.test(seen)) return "A person's step (approve, checkpoint, evidence reset, mcp trust) run inside another command is still a person's step. If a person must look, stop with `trellis escalate \"<why>\"`.";
+  if (cmds.some((c) => c.prog === "trellis" && (c.args[0] === "uninstall" || c.args[0] === "init"))) {
+    return "Taking Trellis's hooks out (uninstall) or rewriting them (init) mid-session would leave the session unchecked. That is the person's decision: ask them.";
+  }
+  if (cmds.some((c) => ["npm", "pnpm", "yarn", "bun"].includes(c.prog) && ["uninstall", "un", "remove", "rm", "r"].includes(c.args[0]) && c.args.some((a) => /@synovitec\/trellis/.test(a)))) {
+    return "Removing Trellis mid-session would end the session unchecked. Ask the person.";
+  }
+  if (cmds.some(removesTrellis)) {
+    return "That command removes or replaces Trellis (it deletes ignored files, drops devDependencies, or reinstalls Trellis), which would end the session unchecked. Ask the person.";
+  }
+  if (cmds.some(rewritesRemoteHistory)) {
+    return "Moving a remote-tracking ref by hand, or rewriting a reflog, changes which commits read as the session's. Fetch, pull and push as usual.";
+  }
+  const removes = cmds.some((c) => ["rm", "rmdir", "del", "rd", "remove-item", "mv", "move", "ren", "rename-item"].includes(c.prog) && c.args.some((a) => /(^|[\\/])node_modules([\\/]|$)/.test(a)));
+  if (removes) return "Deleting or moving node_modules takes Trellis out from under the session. Ask the person.";
+  const writes = cmds.some((c) => !READERS.has(c.prog) || (c.prog === "find" && c.args.some((a) => FIND_ACTIONS.has(a)))) || /[^2]>{1,2}\s*\S/.test(cmd);
+  if (EVIDENCE.test(seen) && writes) return "That command touches the session's evidence or Trellis's installed code. Leave them alone.";
+  return null;
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {Context} ctx
+ * @param {Config | null} config
+ * @param {SessionState | null} state
+ * @returns {HookResult}
+ */
+function preTool(input, ctx, config, state) {
+  const cfg = agentConfig(config?.agents);
+  const intact = /** @type {import("./rules.mjs").Rule} */ (RULES.find((r) => r.id === "evidence-intact"));
+  const guard = modeOf(intact, cfg) !== "off";
+  const name = String(input.tool_name ?? "");
+  const tool = input.tool_input ?? {};
+  if (name === "Bash" || name === "PowerShell") {
+    const why = guard ? tampering(String(tool.command ?? "")) : null;
+    return why ? deny(why) : { code: 0 };
+  }
+  const abs = String(tool.file_path ?? tool.path ?? tool.notebook_path ?? tool.relative_path ?? "");
+  if (guard && (EVIDENCE.test(abs) || KEY.test(abs))) return deny("That file is part of the session's evidence or of Trellis itself. Leave it alone.");
+  const path = editedPath({ i: 0, t: 0, name, input: tool }, ctx.root, ctx.platform);
+  if (!path) return { code: 0 };
+  const enabled = new Set(enabledTools(ctx, config).map((e) => e.tool.id));
+  const ledger = state?.ledger ?? ledgerFromTranscript(readSession(input.transcript_path).uses, ctx);
+  // A graph to ask, not a graphify binary: installed with no graph built, a query cannot answer,
+  // and refusing every edit would leave the agent no way forward but the shell.
+  const graphReady = ctx.exists("graphify-out/graph.json");
+  const refusal = gate(path, ledger, enabled, config?.agents, { graphReady });
+  if (!refusal || refusal.mode === "off") return { code: 0 };
+  if (refusal.mode === "block") return deny(refusal.reason);
+  return tell(`${refusal.id}: ${refusal.reason}`);
+}
+
+/** Whether a tool call succeeded, as far as its response says. @param {any} r */
+export function succeeded(r) {
+  if (r == null || typeof r !== "object") return true;
+  if (r.is_error || r.isError || r.interrupted) return false;
+  for (const k of ["exitCode", "exit_code", "returnCode", "code"]) if (typeof r[k] === "number" && r[k] !== 0) return false;
+  return true;
+}
+
+/** A response's text, whatever its shape. @param {any} r */
+const outputOf = (r) => (r == null ? "" : typeof r === "string" ? r : [r.stdout, r.output, r.content, r.result].map((x) => (typeof x === "string" ? x : x ? JSON.stringify(x) : "")).join("\n"));
+
+/** What may run beside a graph query without being able to write an answer: a cd before it, a head after it. */
+const BESIDE_GRAPH = new Set(["graphify", "cd", "head"]);
+
+/**
+ * A graph query that answered: graphify's own output is in the response, graphify is all that
+ * ran (beside a `cd` or a `| head`), so no other command can have printed the answer, and the
+ * program run is not a script inside the repository (an agent-written `./graphify`).
+ * @param {{ name: string, input: any }} use
+ * @param {any} response
+ * @param {Context} ctx
+ */
+export function graphAnswered(use, response, ctx) {
+  if (mcpParts(use.name)) return isGraphify(use) && succeeded(response);
+  if (!isGraphify(use) || !succeeded(response)) return false;
+  const cmd = String(use.input.command ?? "");
+  if (repoLocal(cmd, "graphify", ctx) || /(^|[\s;&|])PATH=/.test(cmd)) return false;
+  if (commandsIn(cmd).some((c) => !BESIDE_GRAPH.has(c.prog))) return false;
+  return /^Graph: .*\bnodes?\b|^NODE /m.test(outputOf(response));
+}
+
+/**
+ * Whether a command runs `tool` from a path inside the repository: `./bin/graphify`, `tools/graphify`,
+ * or an absolute path under the root. The real tool lives outside it.
+ * @param {string} cmd
+ * @param {string} tool
+ * @param {Context} ctx
+ */
+function repoLocal(cmd, tool, ctx) {
+  for (const w of cmd.split(/[\s;&|()]+/)) {
+    const word = w.replace(/^["']|["']$/g, "");
+    if (!/[\\/]/.test(word) || !new RegExp(`[\\\\/]${tool}(\\.\\w+)?$`, "i").test(word)) continue;
+    if (!/^([a-zA-Z]:)?[\\/]/.test(word)) return true;
+    if (relativeTo(word, ctx.root, ctx.platform) != null) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether Claude Code itself logged this call: its id, or else the same tool with the same input,
+ * in the session's transcript (subagents' included). A hook run by hand from the shell has no
+ * such entry, so it records nothing.
+ * @param {Record<string, any>} input
+ * @param {import("./transcript.mjs").ToolUse[]} uses
+ */
+function logged(input, uses) {
+  const name = String(input.tool_name ?? "");
+  if (typeof input.tool_use_id === "string") return uses.some((u) => u.id === input.tool_use_id && u.name === name);
+  const want = JSON.stringify(input.tool_input ?? {});
+  return uses.some((u) => u.name === name && JSON.stringify(u.input) === want);
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {Context} ctx
+ * @param {Config | null} config
+ * @param {SessionState | null} state
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {HookResult}
+ */
+function postTool(input, ctx, config, state, env) {
+  const cfg = agentConfig(config?.agents);
+  const use = { name: String(input.tool_name ?? ""), input: input.tool_input ?? {} };
+  const response = input.tool_response;
+  const ok = succeeded(response);
+  const enabledList = enabledTools(ctx, config);
+  const graphOn = enabledList.some((e) => e.tool.id === "graphify");
+  const nudgeOn = graphOn && modeOf(/** @type {any} */ (RULES.find((r) => r.id === "graph-first")), cfg) !== "off";
+  // Most calls are no evidence of anything: answer them without reading the transcript, which
+  // can be large, so a session's every Bash and MCP call does not pay for it.
+  // That the agent is at work, once per window, as evidence: whether a commit is an agent's must
+  // not rest on CLAUDECODE, which `env -u CLAUDECODE git commit` removes.
+  const window = readWindow(ctx.root, env);
+  if (window.status === "ok" && !window.events.some((e) => e.agent === AGENT)) appendEvent(ctx.root, { kind: "agent", tool: use.name, agent: AGENT }, env);
+  const servers = serverKeys(ctx);
+  const relevant = isSearch(use) || isGraphify(use) || !!mcpParts(use.name) && (isBrowser(servers.playwright, use) || isContext7(servers.context7, use) || isSchemaLookup(servers.postgres, use));
+  if (!relevant) return { code: 0 };
+  const { uses } = readSession(input.transcript_path);
+  if (!state) {
+    // No session record: the reminder still works, from the transcript, at the threshold exactly.
+    if (!nudgeOn || uses.some(isGraphify) || uses.filter(isSearch).length !== NUDGE_AT) return { code: 0 };
+    return nudge();
+  }
+  if (!logged(input, uses)) return { code: 0 };
+  const sid = input.session_id;
+  const l = state.ledger;
+  const origin = /** @type {any} */ (enabledList.find((e) => e.tool.id === "playwright-mcp")?.opts)?.origin ?? null;
+  // The same evidence goes to the commit checkpoint's log, which every agent and person share.
+  const feed = (/** @type {Omit<import("../core/evidence.mjs").Event, "agent">} */ e) => appendEvent(ctx.root, { ...e, agent: AGENT }, env);
+  if (isSearch(use)) record(ctx.root, sid, { k: "search" }, env);
+  if (graphAnswered(use, response, ctx)) {
+    record(ctx.root, sid, { k: "graph" }, env);
+    feed({ kind: "graph", tool: "graphify", subject: String(use.input.command ?? use.name).slice(0, 300) });
+  }
+  if (ok && isSchemaLookup(servers.postgres, use)) {
+    record(ctx.root, sid, { k: "schema" }, env);
+    feed({ kind: "schema", tool: use.name });
+  }
+  if (ok && isContext7(servers.context7, use)) {
+    const q = JSON.stringify(use.input).toLowerCase().slice(0, 500);
+    record(ctx.root, sid, { k: "lookup", q }, env);
+    feed({ kind: "docs", tool: use.name, subject: q });
+  }
+  const p = mcpParts(use.name);
+  if (p && isBrowser(servers.playwright, use)) {
+    if (p.tool === "browser_navigate") record(ctx.root, sid, { k: "nav", on: ok && onOrigin(String(use.input.url ?? ""), origin) }, env);
+    else if ((p.tool === "browser_snapshot" || p.tool === "browser_take_screenshot") && ok && l.onPage) {
+      // The content the page could show is the content as it is now: record it, file by file.
+      /** @type {Record<string, string>} */
+      const files = {};
+      for (const c of changes(ctx, state, [])) if (matchesAny(c.path, cfg.uiPaths)) files[c.path] = c.hash;
+      record(ctx.root, sid, { k: "browser", files }, env);
+      const blobs = uiBlobs(ctx, cfg.uiPaths);
+      if (blobs) feed({ kind: "browser", tool: p.tool, blobs });
+    }
+  }
+  const searches = l.searches + (isSearch(use) ? 1 : 0);
+  const fire = nudgeOn && !l.nudged && !l.graph && searches >= NUDGE_AT;
+  if (fire) record(ctx.root, sid, { k: "nudged" }, env);
+  return fire ? nudge() : { code: 0 };
+}
+
+/** The agent these hooks speak for, as the evidence names it. */
+const AGENT = "claude-code";
+
+/**
+ * The git blob of every UI file that differs from HEAD, as it is on disk now: what a browser
+ * check just looked at, in the ids the commit will carry. Null when git cannot tell (no commit yet).
+ * @param {Context} ctx
+ * @param {string[]} uiPaths
+ * @returns {Record<string, string> | null}
+ */
+function uiBlobs(ctx, uiPaths) {
+  try {
+    /** @type {Record<string, string>} */
+    const blobs = {};
+    for (const c of worktreeDiff(ctx.root, treeOf(ctx.root, "HEAD"))) if (c.newBlob && matchesAny(c.path, uiPaths)) blobs[c.path] = c.newBlob;
+    return blobs;
+  } catch {
+    return null;
+  }
+}
+
+const nudge = () => ({
+  code: 0,
+  stdout: `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: "[trellis] Several file searches in a row: `graphify query \"<question>\"` answers where something lives and what depends on it in one call. Ask it before the next search." } })}\n`,
+});
+
+/** @param {Context} ctx */
+function serverKeys(ctx) {
+  const keys = (/** @type {RegExp} */ re) => new Set(mcpServers(ctx, re).map(([k]) => k));
+  return { playwright: keys(/@playwright\/mcp/), context7: keys(/context7-mcp/), postgres: keys(/postgres-mcp|postgres/) };
+}
+
+/**
+ * Files changed this session, by content. From git when there is a snapshot; else from the
+ * agent's own edit calls, which misses shell and subagent writes (the weak path, always said).
+ * @param {Context} ctx
+ * @param {SessionState | null} state
+ * @param {import("./transcript.mjs").ToolUse[]} uses
+ */
+function changes(ctx, state, uses) {
+  if (state && isRepo(ctx.root)) return changedSince(ctx.root, state);
+  const paths = new Set(uses.flatMap((u) => editedPath(u, ctx.root, ctx.platform) ?? []));
+  return [...paths].map((path) => ({ path, hash: contentHash(ctx.root, path) }));
+}
+
+/**
+ * The weak path's ledger, rebuilt from the transcript when no session record exists. It is only
+ * used together with an `evidence-intact` finding, so it never turns a missing record into a pass.
+ * @param {import("./transcript.mjs").ToolUse[]} uses
+ * @param {Context} ctx
+ */
+function ledgerFromTranscript(uses, ctx) {
+  const servers = serverKeys(ctx);
+  const l = emptyLedger();
+  l.searches = uses.filter(isSearch).length;
+  l.graph = uses.some(isGraphify);
+  l.schema = uses.some((u) => isSchemaLookup(servers.postgres, u));
+  l.lookups = uses.filter((u) => isContext7(servers.context7, u)).map((u) => JSON.stringify(u.input).toLowerCase());
+  return l;
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {Context} ctx
+ * @param {string | null} raw
+ * @param {{ config: Config | null, errors: string[] }} judged
+ * @param {{ state: SessionState | null, status: string }} loaded
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {HookResult}
+ */
+/**
+ * Work hidden from git's status by an ignore rule the session changed: when the rules differ from
+ * the start, every file ignored now under an entry that was not ignored then, where the rules
+ * look (code, UI, schema, agent setup). With the rules unchanged, a newly ignored file is one the
+ * repository always ignored (a build output), so there is nothing to compare. An older record
+ * without the start fingerprint compares nothing.
+ * @param {string} root
+ * @param {SessionState} state
+ * @param {Required<import("./rules.mjs").AgentConfig>} cfg
+ */
+function newlyIgnored(root, state, cfg) {
+  if (!state.ignoreRules || !Array.isArray(state.ignored) || ignoreRules(root) === state.ignoreRules) return [];
+  const before = new Set(state.ignored);
+  const fresh = ignoredEntries(root).filter((p) => !before.has(p));
+  const watched = [...cfg.codePaths, ...cfg.uiPaths, ...cfg.schemaPaths, ...cfg.agentSetupPaths];
+  return ignoredEntries(root, fresh).filter((p) => matchesAny(p, watched));
+}
+
+function stop(input, ctx, raw, judged, loaded, env) {
+  const { state, status } = loaded;
+  const { config } = judged;
+  const cfg = agentConfig(config?.agents);
+  const enabledList = enabledTools(ctx, config);
+  const enabled = new Set(enabledList.map((e) => e.tool.id));
+  const { uses, readable } = readSession(input.transcript_path);
+  const repo = isRepo(ctx.root);
+  const good = status === "ok" ? state : null;
+  const integrity = [];
+  const notes = [];
+  if (status === "tampered") integrity.push("The session's evidence was altered.");
+  if ((status === "missing" || status === "no-session") && uses.length) {
+    integrity.push("No evidence was recorded for this session (the session-start hook did not run, or its record was removed), so writes through the shell or by a subagent cannot be seen.");
+  }
+  if (good && repo) {
+    const flaggedNow = flaggedFiles(ctx.root).filter((f) => !good.flagged.includes(f));
+    if (flaggedNow.length) integrity.push(`git was told to ignore changes to ${flaggedNow.slice(0, 5).join(", ")} during the session (update-index).`);
+    if ((excludeText(ctx.root) ?? null) !== good.exclude) integrity.push(".git/info/exclude changed during the session.");
+    const hidden = newlyIgnored(ctx.root, good, cfg);
+    if (hidden.length) integrity.push(`Files were hidden from git during the session by an ignore rule (a .gitignore, core.excludesFile): ${hidden.slice(0, 5).join(", ")}.`);
+  }
+  if (good?.self && good.self !== selfHash()) integrity.push("Trellis's own installed code changed during the session.");
+  if (!repo) notes.push("not a git repository: changes are read from the agent's edit calls only, so shell writes are not seen");
+  if (!readable) notes.push("the session transcript could not be read");
+  const changed = changes(ctx, good, uses);
+  const ledger = good ? good.ledger : ledgerFromTranscript(uses, ctx);
+  const setupScan = enabled.has("agentshield") ? scanSetup(ctx, input.session_id, changed, ledger, cfg, good, env) : { status: /** @type {const} */ ("none") };
+  const session = {
+    changes: changed,
+    addedPackages: addedPackages(ctx, uses, changed, good),
+    enabled,
+    ledger,
+    setupScan,
+    secrets: enabled.has("gitleaks") ? scanCommits(ctx, good) : { status: /** @type {const} */ ("none") },
+    configChanged: good != null && norm(good.configText) !== norm(raw),
+    integrity,
+  };
+  const findings = evaluate(session, config?.agents);
+  if (!config && judged.errors.length) findings.unshift({ id: "config-invalid", mode: "block", reason: `${judged.errors[0]}: the session rules cannot run. Fix the file, or tell the person.` });
+  return decide(findings, notes, input, ctx, good, cfg.maxBlocks, env);
+}
+
+/** @param {string | null | undefined} s */
+const norm = (s) => (s ?? "").replace(/\r\n/g, "\n").trim();
+
+/**
+ * Packages added this session: from install commands the agent ran, and from every manifest whose
+ * dependencies grew. Only manifests are read at the start revision, one `git show` each, so the
+ * cost does not grow with the number of changed files.
+ * @param {Context} ctx
+ * @param {import("./transcript.mjs").ToolUse[]} uses
+ * @param {Array<{ path: string }>} changed
+ * @param {SessionState | null} state
+ */
+function addedPackages(ctx, uses, changed, state) {
+  const names = new Set(uses.flatMap((u) => commandsIn(commandOf(u)).flatMap(packagesAdded)));
+  for (const c of changed) {
+    if (dependenciesOf(c.path, "") == null) continue;
+    const before = state?.head ? fileAt(ctx.root, state.head, c.path) : null;
+    for (const d of addedDependencies(c.path, before, ctx.read(c.path))) names.add(d);
+  }
+  return [...names];
+}
+
+/**
+ * Runs AgentShield itself over the agent setup when it changed since the last clean run, rather
+ * than trusting an exit code the agent produced. A clean run is recorded with the content it saw.
+ * @param {Context} ctx
+ * @param {string | undefined} sid
+ * @param {Array<{ path: string, hash: string }>} changed
+ * @param {import("./state.mjs").Ledger} ledger
+ * @param {Required<import("./rules.mjs").AgentConfig>} cfg
+ * @param {SessionState | null} state
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ status: "none" | "clean" | "findings" | "unavailable", detail?: string }}
+ */
+/** @param {string} p */
+const slashes = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
+
+/**
+ * Runs AgentShield on the repository and reads its JSON report from a file (its output can run
+ * to megabytes). Without `--path` it scans the user's ~/.claude, so the report must name the
+ * repository as its target; a report that cannot be read, or that is about another folder, is
+ * an error, never a clean scan.
+ * @param {Context} ctx
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ findings: Array<{ severity?: string, file?: string }> } | { error: string }}
+ */
+function runAgentShield(ctx, env) {
+  const dir = mkdtempSync(join(tmpdir(), "trellis-agentshield-"));
+  try {
+    const out = join(dir, "report.json");
+    const custom = testOverride(env, "TRELLIS_AGENTSHIELD");
+    const run = agentShieldCommand(ctx.root, out, dir, custom);
+    const r = spawnSync(run.cmd, run.args, { ...run.opts, encoding: "utf8", timeout: 120_000, windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+    if (r.error || r.status == null) return { error: `AgentShield did not complete (${r.error?.message ?? "killed"})` };
+    const report = parseJson(existsSync(out) ? readFileSync(out, "utf8") : "");
+    if (!report || !Array.isArray(report.findings)) return { error: `AgentShield's report could not be read (exit ${r.status})` };
+    if (resolve(String(report.targetPath ?? "")).toLowerCase() !== resolve(ctx.root).toLowerCase()) {
+      return { error: `AgentShield scanned ${report.targetPath ?? "an unknown folder"}, not the repository` };
+    }
+    return { findings: report.findings };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * How the Stop hook runs AgentShield. npx runs from `away`, an empty temporary folder: run from the
+ * repository, it would take a `node_modules/ecc-agentshield` the session planted there over the
+ * pinned version, which it now fetches from the registry with npm's integrity check. The scan
+ * still targets the repository, by an absolute `--path`.
+ * @param {string} root
+ * @param {string} out    where the JSON report goes
+ * @param {string} away   an empty folder outside the repository
+ * @param {string} [custom]  a stand-in script (tests only, see testOverride)
+ * @returns {{ cmd: string, args: string[], opts: { cwd: string, shell?: boolean } }}
+ */
+export function agentShieldCommand(root, out, away, custom) {
+  const args = ["scan", "--path", resolve(root), "--format", "json", "--output", out];
+  if (custom) return { cmd: process.execPath, args: [custom, ...args], opts: { cwd: away } };
+  const win = process.platform === "win32";
+  return { cmd: "npx", args: ["--yes", AGENTSHIELD, ...args].map((a) => (win ? `"${a}"` : a)), opts: { cwd: away, shell: win } };
+}
+
+function scanSetup(ctx, sid, changed, ledger, cfg, state, env) {
+  const pending = changed.filter((c) => matchesAny(c.path, cfg.agentSetupPaths) && ledger.setup[c.path] !== c.hash);
+  if (!pending.length) return { status: "none" };
+  const report = runAgentShield(ctx, env);
+  if ("error" in report) return { status: "unavailable", detail: report.error };
+  const changedPaths = new Set(pending.map((c) => c.path));
+  const serious = report.findings.filter((f) => (f.severity === "critical" || f.severity === "high") && changedPaths.has(slashes(String(f.file ?? ""))));
+  if (serious.length) {
+    const count = (/** @type {string} */ s) => serious.filter((f) => f.severity === s).length;
+    const files = [...new Set(serious.map((f) => slashes(String(f.file))))].join(", ");
+    return { status: "findings", detail: `${count("critical")} critical and ${count("high")} high finding(s) in ${files}; run \`npx ${AGENTSHIELD} scan --path .\` to see them` };
+  }
+  if (state) {
+    /** @type {Record<string, string>} */
+    const files = {};
+    for (const c of pending) files[c.path] = c.hash;
+    record(ctx.root, sid, { k: "setup", files }, env);
+    for (const c of pending) ledger.setup[c.path] = c.hash;
+  }
+  return { status: "clean" };
+}
+
+/**
+ * Scans every commit the session made, on any branch or only in the reflog, chosen by
+ * reachability from where things stood at the start (a commit date can be set to anything). The
+ * hook runs the scanner itself; without gitleaks, the session's commits are reported unscanned.
+ * @param {Context} ctx
+ * @param {SessionState | null} state
+ * @returns {{ status: "none" | "clean" | "leaks" | "unavailable", detail?: string }}
+ */
+function scanCommits(ctx, state) {
+  if (!state?.tips) return { status: "none" };
+  const commits = sessionCommits(ctx.root, state);
+  if (!commits.length) return { status: "none" };
+  if (!ctx.which("gitleaks")) return { status: "unavailable", detail: `gitleaks is not installed, so the session's ${commits.length} commit(s) could not be scanned` };
+  const revs = sessionRevs(ctx.root, state).join(" ");
+  const pinned = mkdtempSync(join(tmpdir(), "trellis-gitleaks-"));
+  try {
+    // An allowlist is the agent's to write: an inline `gitleaks:allow` in its own commit never
+    // counts, and the repository's config and ignore file count only as they were at the start.
+    const args = ["git", `--log-opts=${revs}`, "--redact", "--no-banner", "--exit-code", "1", "--ignore-gitleaks-allow"];
+    if (allowlistChanged(ctx.root, state)) {
+      writeFileSync(join(pinned, "gitleaks.toml"), "[extend]\nuseDefault = true\n");
+      args.push("--config", join(pinned, "gitleaks.toml"), "--gitleaks-ignore-path", pinned);
+    }
+    const { GITLEAKS_CONFIG: _, GITLEAKS_CONFIG_TOML: __, ...env } = process.env;
+    const r = spawnSync("gitleaks", args, { cwd: ctx.root, encoding: "utf8", timeout: 40_000, windowsHide: true, env });
+    if (r.status === 0) return { status: "clean" };
+    const found = `${r.stdout}${r.stderr}`.match(/leaks found:\s*(\d+)/i);
+    if (r.status === 1 && found) return { status: "leaks", detail: `${found[1]} finding(s) in ${commits.length} commit(s)` };
+    return { status: "unavailable", detail: `gitleaks did not complete (${r.error?.message ?? `exit ${r.status}`})` };
+  } finally {
+    rmSync(pinned, { recursive: true, force: true });
+  }
+}
+
+const ALLOWLISTS = [".gitleaks.toml", ".gitleaksignore"];
+
+/**
+ * Whether the session touched gitleaks's allowlists: committed, staged or in the work tree,
+ * against HEAD at the start. Without a start HEAD, assume it did.
+ * @param {string} root
+ * @param {SessionState} state
+ */
+function allowlistChanged(root, state) {
+  if (!state.head) return true;
+  const diff = spawnSync("git", ["diff", "--quiet", state.head, "--", ...ALLOWLISTS], { cwd: root, windowsHide: true });
+  if (diff.status !== 0) return true;
+  const untracked = spawnSync("git", ["ls-files", "--others", "--", ...ALLOWLISTS], { cwd: root, encoding: "utf8", windowsHide: true });
+  return untracked.status !== 0 || untracked.stdout.trim() !== "";
+}
+
+/**
+ * Block, warn, or hand over to the person once the agent has been sent back `maxBlocks` times.
+ * Trellis counts its own blocks: Claude Code's `stop_hook_active` is set by any Stop hook's
+ * block, so trusting it would let another hook's block switch this one off.
+ * @param {Array<{ id: string, mode: string, reason: string }>} findings
+ * @param {string[]} notes
+ * @param {Record<string, any>} input
+ * @param {Context} ctx
+ * @param {SessionState | null} state
+ * @param {number} maxBlocks
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {HookResult}
+ */
+function decide(findings, notes, input, ctx, state, maxBlocks, env) {
+  const blocking = findings.filter((f) => f.mode === "block");
+  const others = findings.filter((f) => f.mode !== "block");
+  // Without a trustworthy record, the shared flag is the only memory: block once, then tell.
+  const used = state ? state.blocks : input.stop_hook_active ? maxBlocks : 0;
+  if (blocking.length && used < maxBlocks) {
+    if (state) saveState(ctx.root, input.session_id, { ...state, blocks: used + 1 }, env);
+    const text = [...blocking, ...others].map((f) => `- ${f.id}: ${f.reason}`).join("\n");
+    return { code: 2, stderr: `[trellis] Not done yet:\n${text}\n` };
+  }
+  // A stop that meets every blocking rule starts the count again for the next piece of work.
+  if (state && !blocking.length && state.blocks) saveState(ctx.root, input.session_id, { ...state, blocks: 0 }, env);
+  const parts = [
+    ...(blocking.length ? [`sent the agent back ${used} time(s) and these are still not met, so it is your call: ${blocking.map((f) => `${f.id}: ${f.reason}`).join(" | ")}`] : []),
+    ...others.map((f) => `${f.id}: ${f.reason}`),
+    ...notes,
+  ];
+  return parts.length ? tell(parts.join(" | ")) : { code: 0 };
+}
+