agent-roast 0.13.0 → 0.14.0

package/README.md

@@ -46,8 +46,8 @@ MCP can also call agent-roast as a read-only tool, `agent-roast mcp` ([setup](do
 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-W6JP5YWF.js → chunk-MZBP537U.js}

@@ -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;

package/dist/cli.js

@@ -38,7 +38,7 @@ import {
   terminalText,
   uninstallHooks,
   writeBaseline
-} from "./chunk-W6JP5YWF.js";
+} from "./chunk-MZBP537U.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -506,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];
@@ -516,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;
@@ -525,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);
@@ -533,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;
@@ -563,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).`);

package/dist/index.d.ts

@@ -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;
@@ -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 -->";

package/dist/index.js

@@ -91,7 +91,7 @@ import {
   unquoteGitPath,
   validateExceptions,
   writeBaseline
-} from "./chunk-W6JP5YWF.js";
+} from "./chunk-MZBP537U.js";
 export {
   AGENT_LABELS,
   CONFIG_FILENAMES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-roast",
-  "version": "0.13.0",
+  "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",