agent-roast 0.12.2 → 0.14.0

package/README.md

@@ -40,13 +40,14 @@ npx agent-roast          # review what you have not committed yet (on a clean tr
 npx agent-roast hook install          # Claude Code, Codex and Cursor
 ```
 
-For Claude Code there is also a plugin: `/plugin install agent-roast --marketplace Nari-Ab/agent-roast`.
+For Claude Code there is also a plugin: `/plugin install agent-roast --marketplace Nari-Ab/agent-roast`. Any agent that speaks
+MCP can also call agent-roast as a read-only tool, `agent-roast mcp` ([setup](docs/integrations.md#mcp-server)).
 
 When the agent is about to finish, agent-roast reviews everything it changed. If a check got weaker, the agent is **sent back
 once**, with the file, the line and the before and after, and told to fix the code instead. If it tries again, you get a
 warning rather than an endless loop. Anything agent-roast cannot check lets the agent finish: it never breaks a session. An
-intended change is accepted by committing it. Setup for each agent, what it does not do, and how to pause it:
-[docs/integrations.md](docs/integrations.md).
+intended change is accepted by committing it. Not sure yet? `npx agent-roast hook install --advisory` only warns you and never
+sends the agent back. Setup for each agent, what it does not do, and how to pause it: [docs/integrations.md](docs/integrations.md).
 
 > The agent hooks follow each agent's documented hook protocol and are tested with simulated hook input, not yet in long live
 > sessions with every agent. Reports of what you see are welcome.

package/dist/{chunk-FA47T742.js → chunk-MZBP537U.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import path11 from "path";
+import path12 from "path";
 
 // src/git.ts
 import { spawn, spawnSync } from "child_process";
@@ -3711,10 +3711,10 @@ var plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
 function clipEvidence(text, limit = 200) {
   if (text.length <= limit) return text;
   const arrow = text.indexOf(" \u2192 ");
-  const clip2 = (part, size) => part.length > size ? `${part.slice(0, size - 1)}\u2026` : part;
-  if (arrow < 0) return clip2(text, limit);
+  const clip3 = (part, size) => part.length > size ? `${part.slice(0, size - 1)}\u2026` : part;
+  if (arrow < 0) return clip3(text, limit);
   const side = Math.floor((limit - 3) / 2);
-  return `${clip2(text.slice(0, arrow), side)} \u2192 ${clip2(text.slice(arrow + 3), side)}`;
+  return `${clip3(text.slice(0, arrow), side)} \u2192 ${clip3(text.slice(arrow + 3), side)}`;
 }
 async function replayHistory(options = {}) {
   assertNotAborted(options.signal);
@@ -3848,11 +3848,11 @@ function describe(finding2, index) {
   const evidence = clip(finding2.lineSnippet || finding2.reason, 220);
   return [`${index}. ${where} [${finding2.type}]`, `   ${evidence}`];
 }
-function formatAgentFeedback(result) {
+function formatAgentFeedback(result, subject = "the uncommitted changes") {
   const ranked = mostImportantFirst(result.infractions, result.failedRules);
   const blocking = ranked.filter((finding2) => result.failedRules.includes(finding2.type));
   const notes = ranked.filter((finding2) => !result.failedRules.includes(finding2.type) && isCheckRule(finding2.type));
-  const lines = ["agent-roast: the uncommitted changes make the checks easier to pass instead of making the code correct.", ""];
+  const lines = [`agent-roast: ${subject} make the checks easier to pass instead of making the code correct.`, ""];
   blocking.slice(0, LISTED).forEach((finding2, index) => lines.push(...describe(finding2, index + 1)));
   if (blocking.length > LISTED) lines.push(`   \u2026 and ${blocking.length - LISTED} more.`);
   if (notes.length) {
@@ -3911,7 +3911,9 @@ async function runHook(rawInput, options = {}) {
   } catch {
     return outcome("skip", "", "agent-roast hook: input was not JSON; nothing was checked.\n");
   }
-  if (["off", "0", "false"].includes((env.AGENT_ROAST_HOOK ?? "").toLowerCase())) return outcome("skip");
+  const mode = (env.AGENT_ROAST_HOOK ?? "").toLowerCase();
+  if (["off", "0", "false"].includes(mode)) return outcome("skip");
+  const advisory = options.advisory === true || mode === "advisory";
   const agent = options.agent ?? detectAgent(input);
   const event = String(input.hook_event_name ?? "Stop");
   if (event.toLowerCase() !== "stop") return outcome("skip");
@@ -3932,8 +3934,10 @@ async function runHook(rawInput, options = {}) {
   }
   if (!result.failedRules.length) return outcome("pass", agent === "cursor" ? "{}\n" : "", "", result);
   const alreadyAsked = input.stop_hook_active === true || typeof input.loop_count === "number" && input.loop_count > 0;
-  if (alreadyAsked) {
-    return outcome("warn", agent === "cursor" ? "{}\n" : JSON.stringify({ systemMessage: formatUserWarning(result) }) + "\n", "", result);
+  if (alreadyAsked || advisory) {
+    const warning = formatUserWarning(result);
+    return outcome("warn", agent === "cursor" ? "{}\n" : JSON.stringify({ systemMessage: warning }) + "\n", agent === "cursor" && advisory ? `${warning}
+` : "", result);
   }
   const message = formatAgentFeedback(result);
   return outcome("block", JSON.stringify(agent === "cursor" ? { followup_message: message } : { decision: "block", reason: message }) + "\n", "", result);
@@ -3952,9 +3956,10 @@ function packageVersion() {
   const require3 = createRequire2(import.meta.url);
   return String(require3("../package.json").version);
 }
-function hookCommand(agent, command = `npx --yes agent-roast@${packageVersion()}`) {
-  return `${command.trim()} hook run --agent ${agent}`;
+function hookCommand(agent, command = `npx --yes agent-roast@${packageVersion()}`, advisory = false) {
+  return `${command.trim()} hook run --agent ${agent}${advisory ? " --advisory" : ""}`;
 }
+var isAdvisory = (command) => Boolean(command && /(^|\s)--advisory(\s|$)/.test(command));
 var isOurs = (command) => typeof command === "string" && /\bagent-roast\b.*\bhook\s+run\b/.test(command);
 function repositoryRoot(cwd) {
   const absolute = fs8.realpathSync(path9.resolve(cwd));
@@ -4051,7 +4056,7 @@ function installHooks(options) {
   const { root, scope, home, env } = context(options);
   return options.agents.map((agent) => {
     const file = hookConfigPath(agent, scope, root, home, env);
-    const command = hookCommand(agent, options.command);
+    const command = hookCommand(agent, options.command, options.advisory);
     const json = readJsonFile(file);
     const changed = addStopHook(agent, json.data, command);
     if (changed && !options.dryRun) writeJsonFile(file, json);
@@ -4082,7 +4087,7 @@ function hookStatus(options) {
         command = handlers.map((handler) => handler?.command).find(isOurs);
       } catch {
       }
-      rows.push({ agent, scope, file, command, installed: Boolean(command), action: command ? "unchanged" : "absent" });
+      rows.push({ agent, scope, file, command, installed: Boolean(command), advisory: isAdvisory(command), action: command ? "unchanged" : "absent" });
     }
   }
   return rows;
@@ -4116,10 +4121,278 @@ function installInstructions(options = {}) {
   });
 }
 
+// src/mcp.ts
+import * as fs9 from "fs/promises";
+import path10 from "path";
+import readline from "readline";
+var MODERN_VERSIONS = ["2026-07-28"];
+var LEGACY_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+var VERSION_KEY = "io.modelcontextprotocol/protocolVersion";
+var TOOL_TIMEOUT_MS = 25e3;
+var CACHE_MS = 36e5;
+var MAX_TEXT = 6e3;
+var LISTED_NOTES = 3;
+var INSTRUCTIONS = "Call review_worktree before you tell the user a task is done. It compares your uncommitted changes with HEAD and reports any test, assertion, coverage threshold, lint rule or CI step that was made weaker instead of fixing the code. If it reports findings, fix the code and leave the checks as they were; if a change to a check is really intended, ask the user first.";
+var READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var PATH_SCHEMA = { type: "string", description: "A directory inside the project. Defaults to the project the server was started in." };
+var MCP_TOOLS = [
+  {
+    name: "review_worktree",
+    title: "Review uncommitted changes",
+    description: "Compare everything not committed yet (staged, unstaged and untracked files) with HEAD and report changes that make tests, assertions, coverage thresholds, lint rules or CI easier to pass instead of fixing the code. Read-only and offline: nothing is run, written or sent.",
+    inputSchema: { type: "object", properties: { path: PATH_SCHEMA }, additionalProperties: false },
+    annotations: { title: "Review uncommitted changes", ...READ_ONLY }
+  },
+  {
+    name: "review_changes",
+    title: "Review a range of commits",
+    description: "Compare two committed revisions, for example a branch against main, and report changes that weaken tests, assertions, coverage thresholds, lint rules or CI. The rules come from the base revision, so the change under review cannot switch them off. Read-only and offline.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        base: { type: "string", description: "The revision to compare against, for example main or origin/main." },
+        head: { type: "string", description: "The revision under review. Defaults to HEAD." },
+        path: PATH_SCHEMA
+      },
+      required: ["base"],
+      additionalProperties: false
+    },
+    annotations: { title: "Review a range of commits", ...READ_ONLY }
+  },
+  {
+    name: "stop_hook",
+    title: "Stop hook adapter",
+    description: "Runs the same check as `agent-roast hook run` for plugin hooks of type mcp_tool and answers with the hook's JSON: it sends an agent back once when its changes weaken checks. Meant to be called by a hook, not by hand.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: PATH_SCHEMA,
+        stop_hook_active: { type: "string", description: '"true" when the agent is already continuing because of a Stop hook.' },
+        loop_count: { type: "string", description: "How many times the agent was already sent back, for agents that count." }
+      },
+      additionalProperties: true
+    },
+    annotations: { title: "Stop hook adapter", ...READ_ONLY }
+  }
+];
+var ToolInputError = class extends Error {
+};
+var ok = (id, result) => ({ jsonrpc: "2.0", id, result });
+var fail = (id, code, message, data) => ({ jsonrpc: "2.0", id, error: data === void 0 ? { code, message } : { code, message, data } });
+var clip2 = (text) => text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT - 1)}\u2026` : text;
+function optionalText(value, name) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (typeof value !== "string" || value.length > 300 || value.includes("\0")) throw new ToolInputError(`${name} must be a revision name of at most 300 characters.`);
+  return value;
+}
+function summarize(result, subject) {
+  const blocking = result.infractions.filter((finding2) => result.failedRules.includes(finding2.type));
+  const lines = [];
+  if (blocking.length) lines.push(formatAgentFeedback(result, subject));
+  else {
+    lines.push(result.filesChanged ? `agent-roast: no weakened checks in ${subject} (${result.filesInspected} of ${result.filesChanged} changed files compared).` : `agent-roast: nothing changed in ${subject}, so there is nothing to review.`);
+    const notes = result.infractions.filter((finding2) => isCheckRule(finding2.type));
+    if (notes.length) {
+      lines.push("Worth a second look (these do not block):");
+      for (const note of notes.slice(0, LISTED_NOTES)) {
+        const where = `${terminalText(note.file ?? "unknown location")}${note.lineNumber ? `:${note.lineNumber}` : ""}`;
+        lines.push(`- ${where} [${note.type}] ${terminalText(note.lineSnippet || note.reason).replace(/\s+/g, " ").trim().slice(0, 120)}`);
+      }
+      if (notes.length > LISTED_NOTES) lines.push(`- \u2026 and ${notes.length - LISTED_NOTES} more.`);
+    }
+  }
+  if (!result.complete) {
+    const first = result.skippedFiles[0];
+    lines.push(`agent-roast could not compare ${result.skippedFiles.length} changed file${result.skippedFiles.length === 1 ? "" : "s"}${first ? ` (for example ${terminalText(first.file)}: ${terminalText(first.reason).slice(0, 120)})` : ""}, so this result may be incomplete.`);
+  }
+  return lines.join("\n");
+}
+function createMcpServer(options) {
+  const env = options.env ?? process.env;
+  const timeoutMs = options.timeoutMs ?? TOOL_TIMEOUT_MS;
+  const serverInfo = { name: "agent-roast", title: "Agent Roast", version: options.version };
+  const inflight = /* @__PURE__ */ new Map();
+  const cancelled = /* @__PURE__ */ new Set();
+  let allowed;
+  const startDirectory = () => path10.resolve(options.cwd ?? (env.CLAUDE_PROJECT_DIR || env.CURSOR_PROJECT_DIR || process.cwd()));
+  const roots = () => allowed ??= Promise.all(
+    (options.roots?.length ? options.roots : [startDirectory()]).map((root) => fs9.realpath(path10.resolve(root)).catch(() => path10.resolve(root)))
+  );
+  async function gitCommonDirectory(directory) {
+    try {
+      const output = gitOutputPath((await readGit(directory, ["rev-parse", "--git-common-dir"], void 0, 8192)).toString());
+      return await fs9.realpath(path10.resolve(directory, output));
+    } catch {
+      return null;
+    }
+  }
+  async function permitted(real, list) {
+    for (const root of list) {
+      const relative2 = path10.relative(root, real);
+      if (relative2 === "" || relative2 !== ".." && !relative2.startsWith(".." + path10.sep) && !path10.isAbsolute(relative2)) return true;
+    }
+    const common = await gitCommonDirectory(real);
+    if (!common) return false;
+    for (const root of list) if (common === await gitCommonDirectory(root)) return true;
+    return false;
+  }
+  async function project(requested) {
+    if (requested !== void 0 && requested !== null && requested !== "" && (typeof requested !== "string" || requested.includes("\0"))) throw new ToolInputError("path must be a directory path.");
+    const list = await roots();
+    if (!options.roots?.length && list.every((root) => path10.parse(root).root === root)) {
+      throw new ToolInputError("The server was started outside a project (its working directory is the filesystem root). Add --root <directory> to the server's command line.");
+    }
+    const target = typeof requested === "string" && requested ? path10.resolve(list[0], requested) : list[0];
+    let real;
+    try {
+      real = await fs9.realpath(target);
+    } catch {
+      throw new ToolInputError(`${terminalText(typeof requested === "string" && requested ? requested : target)} does not exist.`);
+    }
+    if (!await permitted(real, list)) throw new ToolInputError("That path is outside the project this server was started in. Add --root <directory> to the server's command line to allow another location.");
+    return real;
+  }
+  async function callTool(name, args, signal) {
+    switch (name) {
+      case "review_worktree":
+        return summarize(await reviewWorktreeChanges({ cwd: await project(args.path), signal }), "the uncommitted changes");
+      case "review_changes": {
+        const base = optionalText(args.base, "base");
+        if (!base) throw new ToolInputError("base is required, for example main or origin/main.");
+        const head = optionalText(args.head, "head");
+        const cwd = await project(args.path);
+        return summarize(await reviewChanges({ cwd, base, head, signal }), `the changes between ${terminalText(base)} and ${terminalText(head ?? "HEAD")}`);
+      }
+      case "stop_hook": {
+        const cwd = await project(args.cwd);
+        const input = { hook_event_name: "Stop", cwd, stop_hook_active: args.stop_hook_active === true || args.stop_hook_active === "true" };
+        const loops = Number(args.loop_count);
+        if (args.loop_count !== void 0 && args.loop_count !== "" && Number.isFinite(loops)) input.loop_count = loops;
+        const outcome2 = await runHook(JSON.stringify(input), { agent: "claude", cwd, env, timeoutMs });
+        if (outcome2.stderr) process.stderr.write(outcome2.stderr);
+        return outcome2.stdout.trim() || "{}";
+      }
+      default:
+        throw new ToolInputError(`Unknown tool: ${terminalText(name).slice(0, 100)}`);
+    }
+  }
+  async function toolResult(id, name, rawArguments) {
+    const controller = new AbortController();
+    inflight.set(id, controller);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const args = rawArguments ?? {};
+      if (typeof args !== "object" || Array.isArray(args)) throw new ToolInputError("arguments must be an object.");
+      return { text: clip2(await callTool(name, args, controller.signal)), isError: false };
+    } catch (error) {
+      if (cancelled.has(id)) return null;
+      if (controller.signal.aborted) {
+        const limit = timeoutMs >= 1e3 ? `${Math.round(timeoutMs / 1e3)} seconds` : `${timeoutMs} ms`;
+        return { text: `agent-roast: the check took longer than ${limit} and was stopped. Nothing was changed.`, isError: true };
+      }
+      const message = terminalText(error instanceof Error ? error.message : String(error));
+      return { text: clip2(error instanceof ToolInputError ? message : `agent-roast: ${message}`), isError: true };
+    } finally {
+      clearTimeout(timer);
+      inflight.delete(id);
+      cancelled.delete(id);
+    }
+  }
+  async function dispatch(id, method, params) {
+    const meta = params._meta && typeof params._meta === "object" ? params._meta : {};
+    const requested = meta[VERSION_KEY];
+    const modern = typeof requested === "string";
+    if (modern && !MODERN_VERSIONS.includes(requested)) {
+      return fail(id, -32022, "Unsupported protocol version", { supported: [...MODERN_VERSIONS, ...LEGACY_VERSIONS], requested });
+    }
+    const capabilities = { tools: { listChanged: false } };
+    switch (method) {
+      case "initialize": {
+        const asked = params.protocolVersion;
+        const protocolVersion = typeof asked === "string" && LEGACY_VERSIONS.includes(asked) ? asked : LEGACY_VERSIONS[0];
+        return ok(id, { protocolVersion, capabilities, serverInfo, instructions: INSTRUCTIONS });
+      }
+      case "ping":
+        return ok(id, {});
+      case "server/discover":
+        return ok(id, { resultType: "complete", supportedVersions: [...MODERN_VERSIONS, ...LEGACY_VERSIONS], capabilities, serverInfo, instructions: INSTRUCTIONS, ttlMs: CACHE_MS, cacheScope: "public" });
+      case "tools/list":
+        return ok(id, modern ? { resultType: "complete", tools: MCP_TOOLS, ttlMs: CACHE_MS, cacheScope: "public" } : { tools: MCP_TOOLS });
+      case "tools/call": {
+        const name = params.name;
+        if (typeof name !== "string" || !MCP_TOOLS.some((tool) => tool.name === name)) {
+          return fail(id, -32602, `Unknown tool: ${typeof name === "string" ? terminalText(name).slice(0, 100) : "(no name)"}`);
+        }
+        const outcome2 = await toolResult(id, name, params.arguments);
+        if (!outcome2) return void 0;
+        const content = [{ type: "text", text: outcome2.text }];
+        return ok(id, modern ? { resultType: "complete", content, isError: outcome2.isError } : { content, isError: outcome2.isError });
+      }
+      default:
+        return fail(id, -32601, `Method not found: ${terminalText(method).slice(0, 100)}`);
+    }
+  }
+  async function handleOne(message) {
+    if (!message || typeof message !== "object" || Array.isArray(message) || message.jsonrpc !== "2.0") return fail(null, -32600, "Invalid Request");
+    const request = message;
+    if (typeof request.method !== "string") return void 0;
+    const params = request.params && typeof request.params === "object" && !Array.isArray(request.params) ? request.params : {};
+    if (typeof request.id !== "string" && typeof request.id !== "number") {
+      const target = params.requestId;
+      if (request.method === "notifications/cancelled" && (typeof target === "string" || typeof target === "number") && inflight.has(target)) {
+        cancelled.add(target);
+        inflight.get(target)?.abort();
+      }
+      return void 0;
+    }
+    return dispatch(request.id, request.method, params);
+  }
+  return {
+    async handle(message) {
+      if (!Array.isArray(message)) return handleOne(message);
+      if (!message.length) return fail(null, -32600, "Invalid Request");
+      const responses = (await Promise.all(message.map(handleOne))).filter((response) => response !== void 0);
+      return responses.length ? responses : void 0;
+    }
+  };
+}
+async function serveMcp(options) {
+  const server = createMcpServer(options);
+  const output = options.output ?? process.stdout;
+  output.on("error", () => {
+  });
+  const write = (message) => {
+    output.write(JSON.stringify(message) + "\n");
+  };
+  const lines = readline.createInterface({ input: options.input ?? process.stdin, crlfDelay: Infinity });
+  const running = /* @__PURE__ */ new Set();
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      write(fail(null, -32700, "Parse error"));
+      return;
+    }
+    const task = server.handle(message).then((response) => {
+      if (response !== void 0) write(response);
+    }).catch((error) => {
+      process.stderr.write(`agent-roast mcp: ${terminalText(error instanceof Error ? error.message : String(error))}
+`);
+    }).finally(() => {
+      running.delete(task);
+    });
+    running.add(task);
+  });
+  await new Promise((resolve2) => lines.once("close", () => resolve2()));
+  await Promise.allSettled([...running]);
+}
+
 // src/demo.ts
-import * as fs9 from "fs";
+import * as fs10 from "fs";
 import os2 from "os";
-import path10 from "path";
+import path11 from "path";
 import { spawnSync as spawnSync4 } from "child_process";
 import pc2 from "picocolors";
 var CART = `export function total(prices: number[], discount = 0): number {
@@ -4161,7 +4434,7 @@ jobs:
 ${lenient ? "        continue-on-error: true\n" : ""}        run: npm test
 `;
 async function runDemo(options = {}) {
-  const dir = fs9.mkdtempSync(path10.join(os2.tmpdir(), "agent-roast-demo-"));
+  const dir = fs10.mkdtempSync(path11.join(os2.tmpdir(), "agent-roast-demo-"));
   try {
     const git2 = (...args) => {
       const run = spawnSync4(
@@ -4175,7 +4448,7 @@ async function runDemo(options = {}) {
           "-c",
           "commit.gpgsign=false",
           "-c",
-          `core.hooksPath=${path10.join(dir, ".no-hooks")}`,
+          `core.hooksPath=${path11.join(dir, ".no-hooks")}`,
           ...args
         ],
         { cwd: dir, env: getHermeticGitEnv(), encoding: "utf8", timeout: 3e4, windowsHide: true }
@@ -4183,9 +4456,9 @@ async function runDemo(options = {}) {
       if (run.error || run.status !== 0) throw new ConfigError(`The demo needs Git to create a temporary repository: ${run.error?.message ?? run.stderr.trim()}`);
     };
     const write = (file, text) => {
-      const destination = path10.join(dir, file);
-      fs9.mkdirSync(path10.dirname(destination), { recursive: true });
-      fs9.writeFileSync(destination, text);
+      const destination = path11.join(dir, file);
+      fs10.mkdirSync(path11.dirname(destination), { recursive: true });
+      fs10.writeFileSync(destination, text);
     };
     git2("init", "-q", "-b", "main");
     write("src/cart.ts", CART);
@@ -4219,7 +4492,7 @@ async function runDemo(options = {}) {
     ].join("\n");
     return { exitCode: result.failedRules.length ? 0 : 1, output, result };
   } finally {
-    fs9.rmSync(dir, { recursive: true, force: true });
+    fs10.rmSync(dir, { recursive: true, force: true });
   }
 }
 
@@ -4231,9 +4504,9 @@ var InvalidDetectorError = class extends Error {
   }
 };
 async function roastRepository(options = {}) {
-  const cwd = path11.resolve(options.cwd || process.cwd());
+  const cwd = path12.resolve(options.cwd || process.cwd());
   const since = options.since || "90 days ago";
-  const repoName = path11.basename(cwd);
+  const repoName = path12.basename(cwd);
   const collector = new MetricsCollector({ all: options.all, ignorePaths: options.ignorePaths, rules: options.rules, panicLoopWindowMinutes: options.panicLoopWindowMinutes });
   const gitStream = streamGitLog(cwd, since);
   await parseGitLogStream(gitStream, (commit, stats) => {
@@ -4248,7 +4521,7 @@ async function roastRepository(options = {}) {
   return { summary, output };
 }
 async function auditPullRequest(options) {
-  const cwd = path11.resolve(options.cwd || process.cwd());
+  const cwd = path12.resolve(options.cwd || process.cwd());
   const format = options.format || "terminal";
   const failOn = (options.failOn || ["test-skip"]).map((s) => s.trim()).filter(Boolean);
   for (const det of failOn) {
@@ -4416,6 +4689,9 @@ export {
   INSTRUCTIONS_END,
   INSTRUCTIONS_BLOCK,
   installInstructions,
+  MCP_TOOLS,
+  createMcpServer,
+  serveMcp,
   runDemo,
   InvalidDetectorError,
   roastRepository,

package/dist/cli.js

@@ -34,10 +34,11 @@ import {
   roastRepository,
   runDemo,
   runHook,
+  serveMcp,
   terminalText,
   uninstallHooks,
   writeBaseline
-} from "./chunk-FA47T742.js";
+} from "./chunk-MZBP537U.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -505,7 +506,7 @@ program.command("demo").description('See what agent-roast reports for a scripted
 });
 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) => {
+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)`).option("--advisory", "only warn the person; never send the agent back", false).action(async (opts) => {
   let agent;
   try {
     agent = opts.agent === void 0 ? void 0 : parseAgents([opts.agent])[0];
@@ -515,7 +516,7 @@ hook.command("run").description("Run by the agent when it is about to finish; re
     return;
   }
   try {
-    const outcome = await runHook(await readStdin(), { agent });
+    const outcome = await runHook(await readStdin(), { agent, advisory: opts.advisory || program.opts().advisory === true });
     if (outcome.stdout) process.stdout.write(outcome.stdout);
     if (outcome.stderr) process.stderr.write(outcome.stderr);
     process.exitCode = outcome.exitCode;
@@ -524,7 +525,7 @@ hook.command("run").description("Run by the agent when it is about to finish; re
     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) => {
+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("--advisory", "try it without risk: the hook only warns you and never sends the agent back", false).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);
@@ -532,15 +533,17 @@ hook.command("install").description("Add the hook to Claude Code, Codex or Curso
     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}):`);
+    const advisory = opts.advisory || program.opts().advisory === true;
+    const changes = installHooks({ cwd: process.cwd(), agents, scope, command: opts.command, advisory, dryRun: opts.dryRun });
+    console.log(`${opts.dryRun ? "Would install" : "Installed"} the agent-roast hook${advisory ? " in advisory mode" : ""} (${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");
+    if (!opts.dryRun && advisory) console.log("\nAdvisory mode: when the agent finishes with weakened checks you get a one-line warning and the agent is never sent back.\nStart sending it back: agent-roast hook install (without --advisory)   \xB7   remove it: agent-roast hook uninstall");
+    else 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   only warn instead: agent-roast hook install --advisory   \xB7   remove it: agent-roast hook uninstall");
   } catch (error) {
     console.error(`agent-roast hook install error: ${errorMessage(error)}`);
     process.exitCode = 2;
@@ -562,7 +565,7 @@ hook.command("uninstall").description("Remove the hook from Claude Code, Codex o
 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)}`);
+    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)}${row.advisory ? pc.yellow("  (advisory: warns, never sends the agent back)") : ""}`);
     const paused = await hookPausedUntil(process.cwd());
     if (paused) console.log(`
   Paused in this repository until ${paused.toLocaleString()} (agent-roast hook resume).`);
@@ -590,4 +593,12 @@ hook.command("resume").description("End a pause").action(async () => {
     process.exitCode = 2;
   }
 });
+program.command("mcp").description("Run as an MCP server over stdio, so any MCP-capable coding agent can review its own changes (read-only, offline)").option("--root <directory...>", "a directory the tools may review (repeatable); defaults to the project the server was started in").action(async (opts) => {
+  try {
+    await serveMcp({ version: pkg.version, roots: opts.root });
+  } catch (error) {
+    console.error(`agent-roast mcp: ${errorMessage(error)}`);
+    process.exitCode = 1;
+  }
+});
 program.parse(process.argv);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Readable } from 'stream';
+import { Readable, Writable } from 'stream';
 
 /** A reviewed allowance for a precise pattern and number of occurrences.
  * No wildcard, inline bypass, source snippet or executable policy is needed. */
@@ -478,6 +478,8 @@ interface HookOptions {
     agent?: HookAgent;
     /** Repository to review. Defaults to the directory the agent reports. */
     cwd?: string;
+    /** Only tell the person: the agent is never sent back. AGENT_ROAST_HOOK=advisory does the same. */
+    advisory?: boolean;
     env?: NodeJS.ProcessEnv;
     /** The agent is waiting, so a slow review gives up and lets it finish. */
     timeoutMs?: number;
@@ -493,9 +495,9 @@ interface HookOutcome {
 }
 /**
  * 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.
+ * checks. Short on purpose, since it is added to the agent's context. `subject` names what was reviewed.
  */
-declare function formatAgentFeedback(result: ReviewResult): string;
+declare function formatAgentFeedback(result: ReviewResult, subject?: string): 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>;
@@ -506,7 +508,7 @@ 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.
+ * so the person decides instead of the two looping. In advisory mode the agent is never sent back at all.
  */
 declare function runHook(rawInput: string, options?: HookOptions): Promise<HookOutcome>;
 
@@ -520,6 +522,8 @@ interface HookInstallOptions {
     dryRun?: boolean;
     /** Replaces `npx --yes agent-roast@<version>`, for example `agent-roast` when it is installed globally. */
     command?: string;
+    /** Install the hook in advisory mode: it warns the person and never sends the agent back. */
+    advisory?: boolean;
     home?: string;
     env?: NodeJS.ProcessEnv;
 }
@@ -535,7 +539,7 @@ 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;
+declare function hookCommand(agent: HookAgent, command?: string, advisory?: boolean): 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. */
@@ -545,6 +549,7 @@ declare function uninstallHooks(options: Omit<HookInstallOptions, "command">): H
 /** 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;
+    advisory: boolean;
 })[];
 declare const INSTRUCTIONS_START = "<!-- agent-roast:start -->";
 declare const INSTRUCTIONS_END = "<!-- agent-roast:end -->";
@@ -558,6 +563,129 @@ declare function installInstructions(options?: {
     action: "created" | "updated" | "unchanged";
 }[];
 
+/**
+ * A small MCP server over stdio, so any agent that speaks MCP can ask "did my changes weaken a check?" before it says it is
+ * done. It is read-only and offline like the rest of agent-roast, and written without a dependency on purpose: the built files
+ * contain no network code, which a test checks. It answers both protocol eras: the initialize handshake of 2025-11-25 and
+ * earlier, and the per-request metadata of 2026-07-28 (modelcontextprotocol.io/specification/2026-07-28/basic/versioning).
+ */
+type RpcId = string | number;
+type RpcResponse = {
+    jsonrpc: "2.0";
+    id: RpcId | null;
+} & ({
+    result: unknown;
+} | {
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+});
+declare const MCP_TOOLS: readonly [{
+    readonly name: "review_worktree";
+    readonly title: "Review uncommitted changes";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "A directory inside the project. Defaults to the project the server was started in.";
+            };
+        };
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+        readonly title: "Review uncommitted changes";
+    };
+}, {
+    readonly name: "review_changes";
+    readonly title: "Review a range of commits";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly base: {
+                readonly type: "string";
+                readonly description: "The revision to compare against, for example main or origin/main.";
+            };
+            readonly head: {
+                readonly type: "string";
+                readonly description: "The revision under review. Defaults to HEAD.";
+            };
+            readonly path: {
+                readonly type: "string";
+                readonly description: "A directory inside the project. Defaults to the project the server was started in.";
+            };
+        };
+        readonly required: readonly ["base"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+        readonly title: "Review a range of commits";
+    };
+}, {
+    readonly name: "stop_hook";
+    readonly title: "Stop hook adapter";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly cwd: {
+                readonly type: "string";
+                readonly description: "A directory inside the project. Defaults to the project the server was started in.";
+            };
+            readonly stop_hook_active: {
+                readonly type: "string";
+                readonly description: "\"true\" when the agent is already continuing because of a Stop hook.";
+            };
+            readonly loop_count: {
+                readonly type: "string";
+                readonly description: "How many times the agent was already sent back, for agents that count.";
+            };
+        };
+        readonly additionalProperties: true;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+        readonly title: "Stop hook adapter";
+    };
+}];
+interface McpServerOptions {
+    /** The version reported to clients. */
+    version: string;
+    /** Directories the tools may read. Defaults to the project the server was started in. */
+    roots?: string[];
+    /** The project directory when the server was started; defaults to CLAUDE_PROJECT_DIR, CURSOR_PROJECT_DIR, then the working directory. */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** How long one tool call may take before it is stopped. */
+    timeoutMs?: number;
+}
+interface McpServer {
+    /** Answers one JSON-RPC message (or a batch), or nothing for a notification. */
+    handle(message: unknown): Promise<RpcResponse | RpcResponse[] | undefined>;
+}
+declare function createMcpServer(options: McpServerOptions): McpServer;
+interface ServeMcpOptions extends McpServerOptions {
+    input?: Readable;
+    output?: Writable;
+}
+/** Reads newline-delimited JSON-RPC from the input and writes responses to the output until the input closes. */
+declare function serveMcp(options: ServeMcpOptions): Promise<void>;
+
 interface DemoResult {
     exitCode: number;
     output: string;
@@ -613,4 +741,4 @@ declare function roastRepository(options?: RoastOptions): Promise<{
 }>;
 declare function auditPullRequest(options: PrAuditOptions): Promise<PrAuditResult>;
 
-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 };
+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, MCP_TOOLS, type McpServer, type McpServerOptions, 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 ServeMcpOptions, type ShieldsEndpointResponse, type StagedReviewOptions, type SuppressedFinding, VALID_DETECTORS, applyBaseline, applyExceptions, auditFileDiffs, auditPullRequest, checkProject, compareFindings, configFromText, createBaseline, createMcpServer, 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, serveMcp, streamGitDiff, streamGitLog, stripStringAndRegexLiterals, terminalText, uninstallHooks, unquoteGitPath, validateExceptions, writeBaseline };

package/dist/index.js

@@ -16,6 +16,7 @@ import {
   INSTRUCTIONS_START,
   InvalidDetectorError,
   MAX_CONFIG_BYTES,
+  MCP_TOOLS,
   MetricsCollector,
   PRE_COMMIT_HOOK_TEMPLATE,
   RECORD_SEPARATOR,
@@ -29,6 +30,7 @@ import {
   compareFindings,
   configFromText,
   createBaseline,
+  createMcpServer,
   detectAiAttribution,
   findMergeBase,
   findingFingerprint,
@@ -80,6 +82,7 @@ import {
   roastRepository,
   runDemo,
   runHook,
+  serveMcp,
   streamGitDiff,
   streamGitLog,
   stripStringAndRegexLiterals,
@@ -88,7 +91,7 @@ import {
   unquoteGitPath,
   validateExceptions,
   writeBaseline
-} from "./chunk-FA47T742.js";
+} from "./chunk-MZBP537U.js";
 export {
   AGENT_LABELS,
   CONFIG_FILENAMES,
@@ -106,6 +109,7 @@ export {
   INSTRUCTIONS_START,
   InvalidDetectorError,
   MAX_CONFIG_BYTES,
+  MCP_TOOLS,
   MetricsCollector,
   PRE_COMMIT_HOOK_TEMPLATE,
   RECORD_SEPARATOR,
@@ -119,6 +123,7 @@ export {
   compareFindings,
   configFromText,
   createBaseline,
+  createMcpServer,
   detectAiAttribution,
   findMergeBase,
   findingFingerprint,
@@ -170,6 +175,7 @@ export {
   roastRepository,
   runDemo,
   runHook,
+  serveMcp,
   streamGitDiff,
   streamGitLog,
   stripStringAndRegexLiterals,

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "agent-roast",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Stops AI coding agents (and rushed humans) from turning a build green by weakening tests, coverage gates or CI. Hook for Claude Code, Codex and Cursor, pre-commit, GitHub Action. Offline.",
+  "mcpName": "io.github.Nari-Ab/agent-roast",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",