agent-roast 0.10.1 → 0.12.0

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import {
+  AGENT_LABELS,
   ConfigError,
   GitError,
   GitResolutionError,
+  HOOK_AGENTS,
   InvalidDetectorError,
   RULE_GUIDES,
   VALID_DETECTORS,
@@ -14,25 +16,46 @@ import {
   generateShieldsMarkdown,
   generateSvgBadge,
   gitOutputPath,
+  hookPausedUntil,
+  hookStatus,
   initProject,
+  installHooks,
+  installInstructions,
   loadConfig,
+  parseDuration,
+  pauseHook,
   readGit,
+  replayHistory,
+  repositoryRoot,
+  resumeHook,
   reviewChanges,
   reviewStagedChanges,
+  reviewWorktreeChanges,
   roastRepository,
+  runDemo,
+  runHook,
   terminalText,
+  uninstallHooks,
   writeBaseline
-} from "./chunk-FFKEBW6D.js";
+} from "./chunk-AP5Y4CH6.js";
 
 // src/cli.ts
 import { Command } from "commander";
 import { createRequire } from "module";
 import * as fs from "fs";
 import * as path from "path";
+import pc from "picocolors";
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
 var errorMessage = (error) => terminalText(error instanceof Error ? error.message : String(error));
-async function runContextReview(repoPath, options, staged) {
+function failOnOption(options) {
+  if (options.advisory) {
+    if (options.failOn !== void 0) throw new ConfigError("--advisory cannot be combined with --fail-on.");
+    return [];
+  }
+  return options.failOn?.split(",").map((rule) => rule.trim()).filter(Boolean);
+}
+async function runContextReview(repoPath, options, source) {
   const controller = new AbortController();
   const abort = () => controller.abort();
   process.once("SIGINT", abort);
@@ -40,12 +63,12 @@ async function runContextReview(repoPath, options, staged) {
   try {
     const common = {
       cwd: repoPath,
-      failOn: options.failOn !== void 0 ? options.failOn.split(",").map((rule) => rule.trim()).filter(Boolean) : void 0,
+      failOn: failOnOption(options),
       ignoreExceptions: options.ignoreExceptions,
       format: options.json ? "json" : options.format,
       signal: controller.signal
     };
-    const result = staged ? await reviewStagedChanges(common) : await reviewChanges({ ...common, base: options.base, head: options.head });
+    const result = source === "index" ? await reviewStagedChanges(common) : source === "worktree" ? await reviewWorktreeChanges(common) : await reviewChanges({ ...common, base: options.base, head: options.head });
     console.log(result.output);
     process.exitCode = result.exitCode;
     for (const [filename, content] of [
@@ -70,9 +93,117 @@ removed-count=${result.removedFindings.length}
     process.removeListener("SIGTERM", abort);
   }
 }
+function isDefaultInvocation(options) {
+  return !(options.all || options.base || options.staged || options.worktree || options.failUnder !== void 0 || options.verbose || options.authors || program.getOptionValueSource("since") === "cli" || program.getOptionValueSource("head") === "cli");
+}
+var NEXT_STEPS = [
+  "",
+  pc.bold("Next steps"),
+  `  ${pc.cyan("npx agent-roast hook install")}   stop your coding agent from weakening checks (Claude Code, Codex, Cursor)`,
+  `  ${pc.cyan("npx agent-roast init --ci")}      add the pull-request check (GitHub Actions)`,
+  `  ${pc.cyan("npx agent-roast demo")}           see a scripted example`,
+  ""
+].join("\n");
+async function runDefault(repoPath, options) {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
+  try {
+    const format = options.json ? "json" : options.format;
+    if (!["terminal", "json", "github", "markdown", "sarif"].includes(format)) throw new ConfigError("--format must be terminal, json, github, markdown or sarif.");
+    try {
+      await readGit(path.resolve(repoPath), ["rev-parse", "--show-toplevel"], controller.signal, 8192);
+    } catch (error) {
+      if (!(error instanceof GitError)) throw error;
+      console.error(`agent-roast reviews Git repositories, and ${terminalText(path.resolve(repoPath))} is not inside one.
+To see what it does without one: npx agent-roast demo`);
+      process.exitCode = 2;
+      return;
+    }
+    const review = await reviewWorktreeChanges({ cwd: repoPath, failOn: failOnOption(options), ignoreExceptions: options.ignoreExceptions, format, signal: controller.signal });
+    if (format === "terminal" && review.filesChanged === 0) {
+      console.log(pc.dim("\nNothing is uncommitted. Here is what a pull-request check would have said about your recent commits:"));
+      const progress = Boolean(process.stderr.isTTY);
+      try {
+        const replay = await replayHistory({
+          cwd: repoPath,
+          last: 50,
+          format: "terminal",
+          signal: controller.signal,
+          onProgress: progress ? (done, total) => process.stderr.write(`\r  reviewed ${done}/${total} commits`) : void 0
+        });
+        if (progress) process.stderr.write("\r\x1B[K");
+        console.log(replay.summary.commits ? replay.output.replace(/\s+$/, "") : "\n  There is no earlier commit to compare with yet, so there is nothing to replay.");
+        console.log(NEXT_STEPS);
+        process.exitCode = replay.exitCode;
+      } catch (error) {
+        if (progress) process.stderr.write("\r\x1B[K");
+        if (controller.signal.aborted) throw error;
+        console.log(`
+  ${errorMessage(error)}
+  To see what agent-roast does: npx agent-roast demo
+`);
+        process.exitCode = 0;
+      }
+      return;
+    }
+    console.log(review.output);
+    process.exitCode = review.exitCode;
+  } catch (error) {
+    console.error(`agent-roast error: ${errorMessage(error)}`);
+    process.exitCode = error instanceof ConfigError || error instanceof GitError || error instanceof GitResolutionError || error instanceof InvalidDetectorError ? 2 : 1;
+  } finally {
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+}
+function parseAgents(names) {
+  return names.map((name) => {
+    if (!HOOK_AGENTS.includes(name.toLowerCase())) throw new ConfigError(`Unknown agent '${name}'. Use ${HOOK_AGENTS.join(", ")}.`);
+    return name.toLowerCase();
+  });
+}
+async function readStdin(timeoutMs = 5e3) {
+  if (process.stdin.isTTY) return "";
+  return new Promise((resolve2) => {
+    const chunks = [];
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      process.stdin.pause();
+      resolve2(Buffer.concat(chunks).toString("utf8"));
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", finish);
+    process.stdin.on("error", finish);
+  });
+}
+function displayPath(file) {
+  const relative2 = path.relative(process.cwd(), file);
+  if (relative2 && !relative2.startsWith("..") && !path.isAbsolute(relative2)) return relative2;
+  const home = process.env.HOME || process.env.USERPROFILE;
+  return home && file.startsWith(home) ? "~" + file.slice(home.length) : file;
+}
 var program = new Command();
-program.name("agent-roast").description("Check current code, review changes and audit Git history for coding shortcuts").version(pkg.version || "0.4.0").argument("[path]", "Path to git repository (default: current directory)", ".").option("-a, --all", "Audit ALL commits regardless of AI attribution tags", false).option("-s, --since <time>", "Time window for git analysis", "90 days ago").option("-v, --verbose", "Show commit SHAs and line snippets for all infractions", false).option("--json", "Output results as raw JSON", false).option("--staged", "Compare full HEAD/index source and gate new staged findings (including the first commit)", false).option("--base <ref>", "Base git ref/branch for PR mode audit (e.g. origin/main)").option("--head <ref>", "Head git ref/SHA for PR mode audit (default: HEAD)", "HEAD").option("--ignore-exceptions", "Report findings even when accepted by reviewed, unexpired exceptions", false).option("--fail-on <rules>", "Comma-separated detectors that trigger CI failure").option("--fail-under <score>", "Fail CI if agent score is below threshold (0-100)").option("--format <format>", "Output format: terminal, json, github, markdown (check/review also support sarif)", "terminal").option("--authors", "Display author names and emails in report", false).action(async (repoPath, options) => {
+program.name("agent-roast").description("Check current code, review changes and audit Git history for coding shortcuts").version(pkg.version || "0.4.0").argument("[path]", "Path to git repository (default: current directory)", ".").option("-a, --all", "Audit ALL commits regardless of AI attribution tags", false).option("-s, --since <time>", "Time window for git analysis", "90 days ago").option("-v, --verbose", "Show commit SHAs and line snippets for all infractions", false).option("--json", "Output results as raw JSON", false).option("--staged", "Compare full HEAD/index source and gate new staged findings (including the first commit)", false).option("--worktree", "Compare HEAD with everything not committed yet: staged, unstaged and untracked files", false).option("--base <ref>", "Base git ref/branch for PR mode audit (e.g. origin/main)").option("--head <ref>", "Head git ref/SHA for PR mode audit (default: HEAD)", "HEAD").option("--ignore-exceptions", "Report findings even when accepted by reviewed, unexpired exceptions", false).option("--fail-on <rules>", "Comma-separated detectors that trigger CI failure").option("--advisory", "Report findings without failing the run, the same as an empty --fail-on (setup errors and incomplete scans still fail)", false).option("--fail-under <score>", "Fail CI if agent score is below threshold (0-100)").option("--format <format>", "Output format: terminal, json, github, markdown (check/review also support sarif)", "terminal").option("--authors", "Display author names and emails in report", false).action((repoPath, options) => rootAction(repoPath, options));
+async function rootAction(repoPath, options) {
   try {
+    if (!options.forceLegacy && isDefaultInvocation(options)) {
+      await runDefault(repoPath, options);
+      return;
+    }
+    if (options.worktree && (options.staged || options.base)) throw new ConfigError("--worktree compares HEAD with the working tree; --staged and --base do not apply.");
+    if (options.worktree) {
+      if (options.all || options.failUnder !== void 0 || program.getOptionValueSource("since") === "cli" || program.getOptionValueSource("head") === "cli") {
+        throw new ConfigError("--worktree compares HEAD and the working tree; --all, --since, --head and --fail-under do not apply.");
+      }
+      await runContextReview(repoPath, options, "worktree");
+      return;
+    }
     if (process.env.GITHUB_EVENT_NAME === "pull_request_target") {
       console.warn(
         "Warning: pull_request_target runs with elevated repository privileges. agent-roast recommends running on 'pull_request'."
@@ -83,7 +214,7 @@ program.name("agent-roast").description("Check current code, review changes and
       if (options.all || options.failUnder !== void 0 || program.getOptionValueSource("since") === "cli" || program.getOptionValueSource("head") === "cli") {
         throw new ConfigError("--staged compares HEAD and index; --all, --since, --head and --fail-under do not apply.");
       }
-      await runContextReview(repoPath, options, true);
+      await runContextReview(repoPath, options, "index");
       return;
     }
     if (options.ignoreExceptions) throw new ConfigError("--ignore-exceptions applies to check, review and --staged context checks.");
@@ -93,8 +224,8 @@ program.name("agent-roast").description("Check current code, review changes and
     if (options.failUnder !== void 0 && (options.failUnder.trim() === "" || !Number.isFinite(Number(options.failUnder)) || Number(options.failUnder) < 0 || Number(options.failUnder) > 100)) {
       throw new ConfigError("--fail-under must be a number between 0 and 100.");
     }
-    if (!options.base && !options.staged && options.failOn !== void 0) {
-      throw new ConfigError("--fail-on requires --base or --staged.");
+    if (!options.base && !options.staged && (options.failOn !== void 0 || options.advisory)) {
+      throw new ConfigError(`${options.advisory ? "--advisory" : "--fail-on"} requires --base or --staged.`);
     }
     if (!options.base && !options.staged && !options.json && !["terminal", "json"].includes(options.format)) {
       throw new ConfigError("Repository audits support terminal or json format; use --base or --staged for github/markdown.");
@@ -102,7 +233,7 @@ program.name("agent-roast").description("Check current code, review changes and
     const configRoot = gitOutputPath((await readGit(path.resolve(repoPath), ["rev-parse", "--show-toplevel"])).toString("utf8"));
     const config = loadConfig(configRoot);
     if (options.base || options.staged) {
-      const failOnRules = options.failOn !== void 0 ? options.failOn.split(",").map((s) => s.trim()).filter(Boolean) : config.failOn;
+      const failOnRules = failOnOption(options) ?? config.failOn;
       const chosenFormat = options.json ? "json" : options.format || "terminal";
       const prResult = await auditPullRequest({
         cwd: repoPath,
@@ -175,34 +306,69 @@ has-supported-changes=${prResult.hasSupportedChanges}
       process.exitCode = 1;
     }
   }
-});
-program.command("review").description("Compare full changed source at merge-base and head; gate only new findings").argument("[path]", "Path to the Git repository", ".").addHelpText("after", "\nRequired: --base <trusted-ref>  Optional: --head <ref> (default HEAD), or use --staged for HEAD/index\nOutput: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>\nExample: agent-roast review --base origin/main --format markdown").action(async (repoPath) => {
+}
+program.command("review").description("Compare full changed source at merge-base and head; gate only new findings").argument("[path]", "Path to the Git repository", ".").addHelpText("after", "\nRequired: --base <trusted-ref>  Optional: --head <ref> (default HEAD), or use --staged for HEAD/index, or --worktree for HEAD/everything uncommitted\nOutput: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>, --advisory\nExamples:\n  agent-roast review --base origin/main --format markdown\n  agent-roast review --worktree\n  agent-roast review --base HEAD~50 --advisory").action(async (repoPath) => {
   try {
     const options = program.opts();
-    if (options.staged ? options.base || program.getOptionValueSource("head") === "cli" : !options.base) {
-      throw new ConfigError("Use review --base <trusted-ref> or review --staged; --base/--head cannot be combined with --staged.");
+    if (options.worktree && options.staged) throw new ConfigError("--worktree and --staged cannot be combined.");
+    if (options.staged || options.worktree ? options.base || program.getOptionValueSource("head") === "cli" : !options.base) {
+      throw new ConfigError("Use review --base <trusted-ref>, review --staged or review --worktree; --base/--head cannot be combined with --staged or --worktree.");
     }
     if (options.all || options.failUnder !== void 0 || program.getOptionValueSource("since") === "cli") {
       throw new ConfigError("review compares source snapshots; --all, --since and --fail-under do not apply.");
     }
-    await runContextReview(repoPath, options, options.staged);
+    await runContextReview(repoPath, options, options.staged ? "index" : options.worktree ? "worktree" : "commits");
   } catch (error) {
     console.error(`agent-roast review error: ${errorMessage(error)}`);
     process.exitCode = 2;
   }
 });
-program.command("check").description("Check current tracked and non-ignored untracked source files").argument("[path]", "Path to a git repository", ".").option("--baseline <file>", "Report only findings not accepted in this baseline").option("--write-baseline <file>", "Save current findings for adoption (refuses to overwrite)").addHelpText("after", "\nOutput options: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>\nExamples:\n  agent-roast check\n  agent-roast check --write-baseline .agentroast-baseline.json\n  agent-roast check --baseline .agentroast-baseline.json --format json").action(async (repoPath, opts) => {
+program.command("replay").description("Review each of the newest commits on its own, to see what a pull-request check would have said").argument("[path]", "Path to the Git repository", ".").option("--last <n>", "How many of the newest commits to review (default 50, at most 1000)").option("--all-rules", "List line-pattern warnings (type-escape, swallowed-error, stub-abandonment) as well", false).addHelpText("after", "\nOutput: --format terminal|json, --json\nExamples:\n  agent-roast replay\n  agent-roast replay --last 200 --json").action(async (repoPath, opts) => {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
   try {
     const global = program.opts();
-    if (global.base || global.staged || global.failUnder !== void 0 || global.all || program.getOptionValueSource("head") === "cli" || program.getOptionValueSource("since") === "cli") {
-      throw new ConfigError("check inspects current files; history, --base, --head, --staged and --fail-under options do not apply.");
+    if (global.base || global.staged || global.worktree || global.failOn !== void 0 || global.advisory || global.failUnder !== void 0 || global.all || global.ignoreExceptions || program.getOptionValueSource("head") === "cli" || program.getOptionValueSource("since") === "cli") {
+      throw new ConfigError("replay reviews each commit on its own; --base, --head, --staged, --worktree, --fail-on, --advisory, --fail-under, --all, --since and --ignore-exceptions do not apply.");
+    }
+    const format = global.json ? "json" : global.format;
+    if (format !== "terminal" && format !== "json") throw new ConfigError("replay supports --format terminal or json.");
+    const last = opts.last === void 0 ? 50 : Number(opts.last);
+    if (!/^\d+$/.test(opts.last ?? "50") || last < 1 || last > 1e3) throw new ConfigError("--last must be a whole number between 1 and 1000.");
+    const progress = process.stderr.isTTY && format === "terminal";
+    const result = await replayHistory({
+      cwd: repoPath,
+      last,
+      allRules: opts.allRules,
+      format,
+      signal: controller.signal,
+      onProgress: progress ? (done, total) => process.stderr.write(`\r  reviewed ${done}/${total} commits`) : void 0
+    });
+    if (progress) process.stderr.write("\r\x1B[K");
+    console.log(result.output);
+    process.exitCode = result.exitCode;
+  } catch (error) {
+    console.error(`agent-roast replay error: ${errorMessage(error)}`);
+    process.exitCode = 2;
+  } finally {
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+});
+program.command("check").description("Check current tracked and non-ignored untracked source files").argument("[path]", "Path to a git repository", ".").option("--baseline <file>", "Report only findings not accepted in this baseline").option("--write-baseline <file>", "Save current findings for adoption (refuses to overwrite)").addHelpText("after", "\nOutput options: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>, --advisory\nExamples:\n  agent-roast check\n  agent-roast check --write-baseline .agentroast-baseline.json\n  agent-roast check --baseline .agentroast-baseline.json --format json").action(async (repoPath, opts) => {
+  try {
+    const global = program.opts();
+    if (global.base || global.staged || global.worktree || global.failUnder !== void 0 || global.all || program.getOptionValueSource("head") === "cli" || program.getOptionValueSource("since") === "cli") {
+      throw new ConfigError("check inspects current files; history, --base, --head, --staged, --worktree and --fail-under options do not apply.");
     }
     if (opts.baseline && opts.writeBaseline) throw new ConfigError("--baseline and --write-baseline cannot be combined.");
     const result = await checkProject({
       cwd: repoPath,
       baseline: opts.baseline,
       ignoreExceptions: global.ignoreExceptions,
-      failOn: global.failOn !== void 0 ? global.failOn.split(",").map((rule) => rule.trim()).filter(Boolean) : void 0,
+      failOn: failOnOption(global),
       format: global.json ? "json" : global.format
     });
     if (opts.writeBaseline) {
@@ -319,4 +485,109 @@ ${markdown}
     process.exitCode = err instanceof ConfigError || err instanceof GitError || err instanceof GitResolutionError ? 2 : 1;
   }
 });
+program.command("demo").description('See what agent-roast reports for a scripted "fix" that weakens the checks (a temporary repository; nothing of yours is read)').action(async () => {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
+  try {
+    if (program.opts().worktree || program.opts().staged || program.opts().base) throw new ConfigError("demo takes no review options.");
+    const demo = await runDemo({ signal: controller.signal });
+    console.log(demo.output);
+    process.exitCode = demo.exitCode;
+  } catch (error) {
+    console.error(`agent-roast demo error: ${errorMessage(error)}`);
+    process.exitCode = 2;
+  } finally {
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+});
+program.command("audit").description("Score the Git history by the shortcuts it adds (the original agent-roast report)").argument("[path]", "Path to git repository (default: current directory)", ".").action((repoPath) => rootAction(repoPath, { ...program.opts(), forceLegacy: true }));
+var hook = program.command("hook").description("Guard a coding agent: send it back to fix the code when it weakens a check (Claude Code, Codex, Cursor)");
+hook.command("run").description("Run by the agent when it is about to finish; reads the agent's JSON on stdin and answers in its dialect").option("--agent <agent>", `${HOOK_AGENTS.join(", ")} (detected from the input when omitted)`).action(async (opts) => {
+  let agent;
+  try {
+    agent = opts.agent === void 0 ? void 0 : parseAgents([opts.agent])[0];
+  } catch (error) {
+    console.error(`agent-roast hook: ${errorMessage(error)}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const outcome = await runHook(await readStdin(), { agent });
+    if (outcome.stdout) process.stdout.write(outcome.stdout);
+    if (outcome.stderr) process.stderr.write(outcome.stderr);
+    process.exitCode = outcome.exitCode;
+  } catch (error) {
+    console.error(`agent-roast hook: ${errorMessage(error)}`);
+    process.exitCode = 0;
+  }
+});
+hook.command("install").description("Add the hook to Claude Code, Codex or Cursor in this repository").argument("[agents...]", `${HOOK_AGENTS.join(", ")} (default: the agents that already have a folder in this repository)`).option("--global", "install for every repository of this user instead", false).option("--local", "Claude Code only: use .claude/settings.local.json, which stays out of Git", false).option("--command <program>", "program to run instead of 'npx --yes agent-roast@<version>', for example 'agent-roast' when installed globally").option("--instructions", "also write a short 'keep the checks honest' paragraph into AGENTS.md / CLAUDE.md", false).option("--dry-run", "show what would change without writing anything", false).action((names, opts) => {
+  try {
+    if (opts.global && opts.local) throw new ConfigError("Choose --global or --local, not both.");
+    let agents = parseAgents(names);
+    const root = repositoryRoot(process.cwd());
+    if (!agents.length) agents = HOOK_AGENTS.filter((agent) => fs.existsSync(path.join(root, { claude: ".claude", codex: ".codex", cursor: ".cursor" }[agent])));
+    if (!agents.length) throw new ConfigError("Name the agent to guard: agent-roast hook install claude (or codex, cursor).");
+    const scope = opts.global ? "global" : opts.local ? "local" : "project";
+    const changes = installHooks({ cwd: process.cwd(), agents, scope, command: opts.command, dryRun: opts.dryRun });
+    console.log(`${opts.dryRun ? "Would install" : "Installed"} the agent-roast hook (${scope}):`);
+    for (const change of changes) console.log(`  ${change.action === "unchanged" ? "=" : "+"} ${AGENT_LABELS[change.agent]}: ${displayPath(change.file)} (${change.action})
+      ${change.command}`);
+    if (opts.instructions) {
+      for (const change of installInstructions({ cwd: process.cwd(), dryRun: opts.dryRun })) console.log(`  + ${displayPath(change.file)} (${change.action}): keep-the-checks-honest paragraph`);
+    }
+    if (agents.includes("codex")) console.log("\nCodex runs a new hook only after you trust it: open Codex and review it with /hooks.");
+    if (!opts.dryRun) console.log("\nWhen the agent is about to finish with weakened checks it is sent back once to fix the code.\nTurn it off for a while: agent-roast hook pause   \xB7   remove it: agent-roast hook uninstall");
+  } catch (error) {
+    console.error(`agent-roast hook install error: ${errorMessage(error)}`);
+    process.exitCode = 2;
+  }
+});
+hook.command("uninstall").description("Remove the hook from Claude Code, Codex or Cursor").argument("[agents...]", `${HOOK_AGENTS.join(", ")} (default: all)`).option("--global", "remove it from the user-level files", false).option("--local", "Claude Code only: remove it from .claude/settings.local.json", false).option("--dry-run", "show what would change without writing anything", false).action((names, opts) => {
+  try {
+    if (opts.global && opts.local) throw new ConfigError("Choose --global or --local, not both.");
+    const agents = names.length ? parseAgents(names) : [...HOOK_AGENTS].filter((agent) => !(opts.local && agent !== "claude"));
+    const scope = opts.global ? "global" : opts.local ? "local" : "project";
+    for (const change of uninstallHooks({ cwd: process.cwd(), agents, scope, dryRun: opts.dryRun })) {
+      console.log(`  ${change.action === "removed" ? "-" : "="} ${AGENT_LABELS[change.agent]}: ${displayPath(change.file)} (${change.action === "removed" ? opts.dryRun ? "would be removed" : "removed" : "no agent-roast hook there"})`);
+    }
+  } catch (error) {
+    console.error(`agent-roast hook uninstall error: ${errorMessage(error)}`);
+    process.exitCode = 2;
+  }
+});
+hook.command("status").description("Show where the hook is installed").action(async () => {
+  try {
+    const rows = hookStatus({ cwd: process.cwd() });
+    for (const row of rows) console.log(`  ${row.installed ? pc.green("installed") : pc.dim("not set  ")}  ${AGENT_LABELS[row.agent].padEnd(11)} ${row.scope.padEnd(8)} ${displayPath(row.file)}`);
+    const paused = await hookPausedUntil(process.cwd());
+    if (paused) console.log(`
+  Paused in this repository until ${paused.toLocaleString()} (agent-roast hook resume).`);
+    if (!rows.some((row) => row.installed)) console.log("\n  Install it with: agent-roast hook install claude   (or codex, cursor)");
+  } catch (error) {
+    console.error(`agent-roast hook status error: ${errorMessage(error)}`);
+    process.exitCode = 2;
+  }
+});
+hook.command("pause").description("Let the agent finish without the check in this repository for a while (for a change you have approved)").option("--for <duration>", "how long: 30m, 2h, 1d", "4h").action(async (opts) => {
+  try {
+    const until = new Date(Date.now() + parseDuration(opts.for));
+    await pauseHook(process.cwd(), until);
+    console.log(`The hook is paused in this repository until ${until.toLocaleString()}. Resume now: agent-roast hook resume`);
+  } catch (error) {
+    console.error(`agent-roast hook pause error: ${errorMessage(error)}`);
+    process.exitCode = 2;
+  }
+});
+hook.command("resume").description("End a pause").action(async () => {
+  try {
+    console.log(await resumeHook(process.cwd()) ? "The hook is active again." : "The hook was not paused.");
+  } catch (error) {
+    console.error(`agent-roast hook resume error: ${errorMessage(error)}`);
+    process.exitCode = 2;
+  }
+});
 program.parse(process.argv);

package/dist/index.d.ts

@@ -156,7 +156,7 @@ type StagedReviewOptions = Omit<ReviewOptions, "base" | "head">;
 interface ReviewResult {
     schemaVersion: string;
     mode: "review";
-    source?: "commits" | "index";
+    source?: "commits" | "index" | "worktree";
     baseSha: string;
     headSha: string;
     mergeBaseSha: string;
@@ -317,6 +317,15 @@ declare function formatTerminalCard(summary: MetricSummary, options: {
     verbose?: boolean;
 }): string;
 declare function formatPrTerminalCard(result: PrAuditResult): string;
+/** Rules about the checks themselves (tests, assertions, quality gates), as opposed to line patterns such as `as any`. */
+declare function isCheckRule(type: string): boolean;
+/**
+ * Puts the findings that matter first, so a long list of warnings cannot push them below a
+ * display cap. The order inside each rank is unchanged.
+ */
+declare function mostImportantFirst<T extends {
+    type: string;
+}>(findings: readonly T[], failedRules: readonly string[]): T[];
 declare function formatGithubAnnotations(result: Pick<PrAuditResult, "infractions" | "failedRules">): string;
 /**
  * Generates GitHub Step Summary Markdown
@@ -409,6 +418,158 @@ declare function compareFindings(before: Infraction[], after: Infraction[], newP
 /** Compare full source blobs in changed files without executing or checking out the candidate. */
 declare function reviewChanges(options: ReviewOptions): Promise<ReviewResult>;
 declare function reviewStagedChanges(options?: StagedReviewOptions): Promise<ReviewResult>;
+/** Everything uncommitted (staged, unstaged and untracked files) against HEAD, under the policy committed at HEAD. */
+declare function reviewWorktreeChanges(options?: StagedReviewOptions): Promise<ReviewResult>;
+
+type ReplayStatus = "blocked" | "warned" | "noted" | "clean" | "untouched" | "incomplete" | "failed";
+interface ReplayCommit {
+    sha: string;
+    date: string;
+    subject: string;
+    /** blocked: a rule that blocks by default fired; warned: a check rule fired without blocking; noted: only line patterns. */
+    status: ReplayStatus;
+    failedRules: string[];
+    findings: Infraction[];
+    filesInspected: number;
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+    error?: string;
+}
+interface ReplayOptions {
+    cwd?: string;
+    /** How many of the newest commits to review (default 50). */
+    last?: number;
+    /** List the line-pattern findings (type-escape, swallowed-error, ...) as well as the check rules. */
+    allRules?: boolean;
+    format?: "terminal" | "json";
+    signal?: AbortSignal;
+    onProgress?: (done: number, total: number) => void;
+}
+interface ReplayResult {
+    schemaVersion: string;
+    mode: "replay";
+    head: string;
+    requested: number;
+    /** Commits without a parent (the first commit, or the edge of a shallow clone) have nothing to compare with. */
+    commitsWithoutParent: number;
+    /** A shallow clone holds only part of the history, so fewer commits than requested may have been replayed. */
+    shallow: boolean;
+    summary: Record<ReplayStatus | "commits", number> & {
+        findingsByRule: Record<string, number>;
+    };
+    commits: ReplayCommit[];
+    exitCode: number;
+    output: string;
+}
+/**
+ * Reviews each of the newest commits of the first-parent history on its own against its parent, which is what a
+ * pull-request check would have seen: one change per squash, merge or direct commit. Reads Git objects only.
+ */
+declare function replayHistory(options?: ReplayOptions): Promise<ReplayResult>;
+declare function formatReplayTerminal(result: ReplayResult, allRules?: boolean): string;
+
+/** Coding agents that can run a command when they are about to finish and feed its answer back. */
+type HookAgent = "claude" | "codex" | "cursor";
+declare const HOOK_AGENTS: readonly HookAgent[];
+interface HookOptions {
+    /** Which agent is calling. Detected from its input when omitted. */
+    agent?: HookAgent;
+    /** Repository to review. Defaults to the directory the agent reports. */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** The agent is waiting, so a slow review gives up and lets it finish. */
+    timeoutMs?: number;
+    now?: Date;
+}
+interface HookOutcome {
+    /** pass: nothing to say; block: the agent was sent back; warn: the user is told, the agent is not; skip: nothing could be checked. */
+    action: "pass" | "block" | "warn" | "skip";
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    result?: ReviewResult;
+}
+/**
+ * What the agent reads when it is sent back: the offending changes, then the instruction to fix the code rather than the
+ * checks. Short on purpose, since it is added to the agent's context.
+ */
+declare function formatAgentFeedback(result: ReviewResult): string;
+/** The time a pause lasts until, or null when the hook is active. Expired pauses are cleaned up. */
+declare function hookPausedUntil(cwd: string, now?: Date): Promise<Date | null>;
+declare function pauseHook(cwd: string, until: Date): Promise<string>;
+declare function resumeHook(cwd: string): Promise<boolean>;
+/** "30m", "2h", "1d": how long a pause lasts. */
+declare function parseDuration(text: string): number;
+/**
+ * The command an agent runs when it is about to finish. It reviews everything uncommitted against HEAD and, when that
+ * weakens the checks, sends the agent back once with a plain account of what to undo. It never fails the agent's run:
+ * anything it cannot check lets the agent finish, and an agent that already had its chance is not blocked a second time,
+ * so the person decides instead of the two looping.
+ */
+declare function runHook(rawInput: string, options?: HookOptions): Promise<HookOutcome>;
+
+/** project: shared with the team (committed); local: this checkout only (Claude Code); global: every repository of this user. */
+type HookScope = "project" | "local" | "global";
+interface HookInstallOptions {
+    /** Anywhere inside the repository. */
+    cwd?: string;
+    agents: readonly HookAgent[];
+    scope?: HookScope;
+    dryRun?: boolean;
+    /** Replaces `npx --yes agent-roast@<version>`, for example `agent-roast` when it is installed globally. */
+    command?: string;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+}
+interface HookInstallChange {
+    agent: HookAgent;
+    scope: HookScope;
+    file: string;
+    action: "created" | "updated" | "unchanged" | "removed" | "absent";
+    /** The command line the agent runs. */
+    command?: string;
+}
+declare const AGENT_LABELS: Record<HookAgent, string>;
+/** Version of this package, which the hook pins so an agent never runs unreviewed newer code. */
+declare function packageVersion(): string;
+/** The command an agent runs for this agent's Stop event. */
+declare function hookCommand(agent: HookAgent, command?: string): string;
+/** The top level of the repository containing `cwd`, or `cwd` itself outside a repository. */
+declare function repositoryRoot(cwd: string): string;
+/** Where an agent reads its hooks from. */
+declare function hookConfigPath(agent: HookAgent, scope: HookScope, root: string, home: string, env?: NodeJS.ProcessEnv): string;
+declare function installHooks(options: HookInstallOptions): HookInstallChange[];
+declare function uninstallHooks(options: Omit<HookInstallOptions, "command">): HookInstallChange[];
+/** Where the hook is installed right now, for every agent and scope that can hold one. */
+declare function hookStatus(options: Pick<HookInstallOptions, "cwd" | "home" | "env">): (HookInstallChange & {
+    installed: boolean;
+})[];
+declare const INSTRUCTIONS_START = "<!-- agent-roast:start -->";
+declare const INSTRUCTIONS_END = "<!-- agent-roast:end -->";
+declare const INSTRUCTIONS_BLOCK = "<!-- agent-roast:start -->\n## Keep the checks honest\n\nWhen a test, type check, linter or CI step fails, fix the code. Do not make the build green by skipping or deleting tests,\nweakening assertions, lowering coverage thresholds, switching off `strict`, or letting a CI step fail. If you think a check\nis wrong, say so and ask before changing it. Before you finish, run `npx agent-roast review --worktree`: it lists uncommitted\nchanges that weaken the checks.\n<!-- agent-roast:end -->\n";
+/** Writes the guidance into AGENTS.md and CLAUDE.md (whichever exist; AGENTS.md is created when neither does). Idempotent. */
+declare function installInstructions(options?: {
+    cwd?: string;
+    dryRun?: boolean;
+}): {
+    file: string;
+    action: "created" | "updated" | "unchanged";
+}[];
+
+interface DemoResult {
+    exitCode: number;
+    output: string;
+    result: ReviewResult;
+}
+/**
+ * A scripted example in a throwaway repository: a project with passing tests, then the kind of "fix" that turns a red build
+ * green by changing the checks. The review is the real one; nothing of the user's is read, and the repository is deleted.
+ */
+declare function runDemo(options?: {
+    signal?: AbortSignal;
+}): Promise<DemoResult>;
 
 /** Offline SARIF 2.1.0, with relative URIs and explicit incomplete-run status.
  * Snippets are omitted to avoid embedding source code in integration artifacts. */
@@ -452,4 +613,4 @@ declare function roastRepository(options?: RoastOptions): Promise<{
 }>;
 declare function auditPullRequest(options: PrAuditOptions): Promise<PrAuditResult>;
 
-export { type AgentRoastConfig, type AiAttributionResult, CONFIG_FILENAMES, type CheckOptions, type CheckResult, type CommitInfo, ConfigError, DEFAULT_CONFIG, DEFAULT_CONFIG_TEMPLATE, type DetectorType, FIELD_SEPARATOR, type FindingBaseline, type FindingException, GITHUB_WORKFLOW_TEMPLATE, GitError, GitResolutionError, HERMETIC_GIT_FLAGS, type Infraction, type InitOptions, type InitResult, InvalidDetectorError, MAX_CONFIG_BYTES, type MetricSummary, MetricsCollector, PRE_COMMIT_HOOK_TEMPLATE, type ParseDiffResult, type ParsedCommit, type ParsedDiffLine, type ParsedFileDiff, type PrAuditOptions, type PrAuditResult, RECORD_SEPARATOR, RULE_GUIDES, type ReviewFormat, type ReviewOptions, type ReviewResult, type RoastOptions, type RuleGuide, type ShieldsEndpointResponse, type StagedReviewOptions, type SuppressedFinding, VALID_DETECTORS, applyBaseline, applyExceptions, auditFileDiffs, auditPullRequest, checkProject, compareFindings, configFromText, createBaseline, detectAiAttribution, findMergeBase, findingFingerprint, formatCheckMarkdown, formatCheckTerminal, formatGithubAnnotations, formatGithubStepSummary, formatPrMarkdownComment, formatPrTerminalCard, formatReviewMarkdown, formatReviewTerminal, formatSarif, formatTerminalCard, generateShareUrl, generateShieldsJson, generateShieldsMarkdown, generateSvgBadge, getHermeticGitEnv, getScoreColor, gitOutputPath, initProject, isCodeFile, isTestFile, loadBaseline, loadConfig, matchIgnorePath, parseDiff, parseGitLogStream, resolveCommitSha, reviewChanges, reviewStagedChanges, roastRepository, streamGitDiff, streamGitLog, stripStringAndRegexLiterals, terminalText, unquoteGitPath, validateExceptions, writeBaseline };
+export { AGENT_LABELS, type AgentRoastConfig, type AiAttributionResult, CONFIG_FILENAMES, type CheckOptions, type CheckResult, type CommitInfo, ConfigError, DEFAULT_CONFIG, DEFAULT_CONFIG_TEMPLATE, type DemoResult, type DetectorType, FIELD_SEPARATOR, type FindingBaseline, type FindingException, GITHUB_WORKFLOW_TEMPLATE, GitError, GitResolutionError, HERMETIC_GIT_FLAGS, HOOK_AGENTS, type HookAgent, type HookInstallChange, type HookInstallOptions, type HookOptions, type HookOutcome, type HookScope, INSTRUCTIONS_BLOCK, INSTRUCTIONS_END, INSTRUCTIONS_START, type Infraction, type InitOptions, type InitResult, InvalidDetectorError, MAX_CONFIG_BYTES, type MetricSummary, MetricsCollector, PRE_COMMIT_HOOK_TEMPLATE, type ParseDiffResult, type ParsedCommit, type ParsedDiffLine, type ParsedFileDiff, type PrAuditOptions, type PrAuditResult, RECORD_SEPARATOR, RULE_GUIDES, type ReplayCommit, type ReplayOptions, type ReplayResult, type ReplayStatus, type ReviewFormat, type ReviewOptions, type ReviewResult, type RoastOptions, type RuleGuide, type ShieldsEndpointResponse, type StagedReviewOptions, type SuppressedFinding, VALID_DETECTORS, applyBaseline, applyExceptions, auditFileDiffs, auditPullRequest, checkProject, compareFindings, configFromText, createBaseline, detectAiAttribution, findMergeBase, findingFingerprint, formatAgentFeedback, formatCheckMarkdown, formatCheckTerminal, formatGithubAnnotations, formatGithubStepSummary, formatPrMarkdownComment, formatPrTerminalCard, formatReplayTerminal, formatReviewMarkdown, formatReviewTerminal, formatSarif, formatTerminalCard, generateShareUrl, generateShieldsJson, generateShieldsMarkdown, generateSvgBadge, getHermeticGitEnv, getScoreColor, gitOutputPath, hookCommand, hookConfigPath, hookPausedUntil, hookStatus, initProject, installHooks, installInstructions, isCheckRule, isCodeFile, isTestFile, loadBaseline, loadConfig, matchIgnorePath, mostImportantFirst, packageVersion, parseDiff, parseDuration, parseGitLogStream, pauseHook, replayHistory, repositoryRoot, resolveCommitSha, resumeHook, reviewChanges, reviewStagedChanges, reviewWorktreeChanges, roastRepository, runDemo, runHook, streamGitDiff, streamGitLog, stripStringAndRegexLiterals, terminalText, uninstallHooks, unquoteGitPath, validateExceptions, writeBaseline };