getclaros 0.1.1 → 0.3.0

package/dist/setup.js

@@ -1,23 +1,28 @@
-// getclaros init | test | undo | status (| export: a map's rules as markdown): puts the guard in front of the MCP servers an agent client already runs.
-// Edits only existing config files, backs each one up first (~/.config/getclaros/backups/<time>/, 0600), writes
-// atomically, and never prints the key.
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { spawn } from "node:child_process";
+// getclaros init | test | undo | doctor (= status) (| export: a map's rules as markdown): puts the guard in front of
+// the MCP servers an agent client already runs, and in front of the browser agents (Playwright, browser-use) in this
+// project. Edits only existing config files (plus, for Playwright Test, one new fixture file and CLAROS_KEY in a
+// gitignored .env), backs each one up first (~/.config/getclaros/backups/<time>/, 0600), writes atomically, and never
+// prints the key.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
 import { homedir, hostname } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import { addClaros, argvOf, CLAROS, detect, launcher, load, removeEntry, sha, unwrapServer, wrapServer, writeAtomic, } from "./clients.js";
-import { cfgDir, loadConfig, relocate, resolve, saveConfig } from "./config.js";
+import { cfgDir, DEFAULT_WEB, loadConfig, relocate, resolve, saveConfig } from "./config.js";
+import { addHooks, hasHooks, hookAgents, hookFiles, removeHooks } from "./hooks.js";
+import { detectBrowser, envTarget, envValue, fixtureImport, fixtureText, setEnv, short } from "./projects.js";
 import { c, dur, header, mark, say, spinner, VERSION, wrap } from "./ui.js";
 const NAME = launcher().at(-1) === "getclaros" ? "npx getclaros" : "getclaros";
 const warn = (s) => process.stderr.write(s + "\n");
 const tilde = (p) => p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p;
 const keyId = (k) => k.split("_").slice(0, 2).join("_") + "_…"; // clr_<prefix>_… (the prefix is the lookup id, not the secret)
 const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
-export const USAGE = `usage: ${NAME} init   [--key clr_… | env CLAROS_KEY | --paste] [--no-browser] [--url <claros server> | --web <claros web app>] [--yes] [--servers a,b] [--project <dir>] [--no-mcp]
+export const USAGE = `usage: ${NAME} init   [--key clr_… | env CLAROS_KEY | --paste] [--no-browser] [--url <claros server> | --web <claros web app>] [--yes] [--servers a,b] [--project <dir>] [--no-mcp] [--no-browser-hooks]
+                [--no-hooks] [--user] [--fail-closed]   (coding-agent hooks: project scope, --user for all projects)
        ${NAME} test   [--app <server>]
-       ${NAME} status
+       ${NAME} doctor [--project <dir>]   (status: the same)
        ${NAME} undo   [--all]
        ${NAME} export <workflow_id> [--format agents|design|skill] [> AGENTS.md]
        ${NAME} override <check_id> --reason "…" [--rule <rule id>] [--verdict wrong_stop|wrong_nudge|missed|right]`;
@@ -28,8 +33,9 @@ export async function run(argv) {
         ({ values: v, positionals: pos } = parseArgs({ args: rest, allowPositionals: cmd === "export" || cmd === "override", options: {
                 url: { type: "string" }, web: { type: "string" }, key: { type: "string" }, yes: { type: "boolean", short: "y" }, servers: { type: "string" },
                 project: { type: "string" }, all: { type: "boolean" }, "no-mcp": { type: "boolean" }, app: { type: "string" },
-                paste: { type: "boolean" }, "no-browser": { type: "boolean" }, format: { type: "string" },
+                paste: { type: "boolean" }, "no-browser": { type: "boolean" }, "no-browser-hooks": { type: "boolean" }, format: { type: "string" },
                 reason: { type: "string" }, rule: { type: "string" }, verdict: { type: "string" },
+                user: { type: "boolean" }, "no-hooks": { type: "boolean" }, "fail-closed": { type: "boolean" },
             } }));
     }
     catch (e) {
@@ -41,8 +47,8 @@ export async function run(argv) {
         return init(v, project);
     if (cmd === "test")
         return test(v, project);
-    if (cmd === "status")
-        return status(v, project);
+    if (cmd === "status" || cmd === "doctor")
+        return doctor(v, project);
     if (cmd === "undo")
         return undo(v, project);
     if (cmd === "export" && pos.length === 1 && ["agents", "design", "skill"].includes(v.format ?? "agents")) {
@@ -209,16 +215,20 @@ function askHidden(q) {
 }
 const backupsDir = () => join(cfgDir(), "backups");
 const newRun = (suffix = "") => ({ dir: join(backupsDir(), new Date().toISOString().replace(/[:.]/g, "-") + suffix), files: [] });
-/** Backs up `before`, writes `after` atomically, records both hashes. */
-function commit(run, path, before, after) {
+/** Backs up `before` (null: a new file), writes `after` atomically, records both hashes. */
+function commit(run, path, before, after, vars) {
     if (!run.files.length) {
         mkdirSync(cfgDir(), { recursive: true, mode: 0o700 });
         mkdirSync(run.dir, { recursive: true, mode: 0o700 });
     }
     const backup = join(run.dir, `${run.files.length}-${basename(path)}`);
-    writeFileSync(backup, before, { mode: 0o600 });
-    writeAtomic(path, after);
-    run.files.push({ path, backup, before: sha(before), after: sha(after) });
+    writeFileSync(backup, before ?? "", { mode: 0o600 });
+    if (before === null)
+        writeFileSync(path, after, { flag: "wx" });
+    else
+        writeAtomic(path, after);
+    run.files.push({ path, backup, before: sha(before ?? ""), after: sha(after), ...(before === null ? { created: true } : {}),
+        ...(vars ? { vars } : {}) });
     writeFileSync(join(run.dir, "manifest.json"), JSON.stringify({ files: run.files }, null, 2), { mode: 0o600 });
 }
 function runs() {
@@ -285,12 +295,52 @@ async function init(v, project) {
         ? join(cfgDir(), "config.json") : saveConfig({ url, web, key, ...(workspace ? { workspace } : {}) });
     say(`  ${c.ask(mark.ok)} Signed in${workspace?.name ? ` to workspace ${c.bold(`"${workspace.name}"`)}` : ""}  ${c.dim(`key ${keyId(key)}`)}`);
     say(c.dim(`    ${url} ${mark.dot} key saved in ${tilde(cfg)}, readable only by you`));
-    const files = detect(project);
-    if (!files.length) {
+    const files = detect(project), browsers = detectBrowser(project), agents = v["no-hooks"] ? [] : hookAgents(project);
+    if (!files.length && !browsers.length && !agents.length) {
         say(`\n  See a stop now: ${c.bold(`${NAME} test`)}`);
-        say(c.dim(wrap("  To guard an agent's tools: add an MCP server to Claude Code, Claude Desktop, Cursor, VS Code or Codex (none has one yet), then run init again.", 2)));
+        say(c.dim(wrap("  To guard an agent: add an MCP server to Claude Code, Claude Desktop, Cursor, VS Code or Codex (none has one yet), or run init in a Playwright or browser-use project, then run init again.", 2)));
         return 1;
     }
+    const run = newRun();
+    let mcp = { changed: [], guardedIn: new Map(), added: [] };
+    if (files.length) {
+        const r = await mcpSetup(v, files, url, key, run);
+        if (typeof r === "number")
+            return r;
+        mcp = r;
+    }
+    else {
+        say(`\n  ${c.bold("MCP agents")}`);
+        say(c.dim(wrap("    none found (Claude Code, Claude Desktop, Cursor, VS Code, Codex); add an MCP server to one, then run init again", 4)));
+    }
+    const hk = await hookSetup(v, agents, project, run);
+    const br = await browserSetup(v, browsers, project, at, key, run);
+    const { guardedIn, added } = mcp, changed = [...mcp.changed, ...hk.clients];
+    if (!changed.length && !br.done.length) {
+        if (br.todo)
+            say(`  ${c.bold("Next")}  add the hook shown above, then run your browser agent`);
+        say("  Nothing to change.");
+        return 0;
+    }
+    const list = (xs) => [...new Set(xs)].join(", ");
+    for (const [n, cl] of guardedIn)
+        say(`  ${c.ask(mark.ok)} Guarded ${c.bold(n)}  ${c.dim(`in ${list(cl)}`)}`);
+    if (added.length)
+        say(`  ${c.ask(mark.ok)} Added the Claros MCP server  ${c.dim(`in ${list(added)}`)}`);
+    for (const l of hk.done)
+        say(`  ${c.ask(mark.ok)} ${l}`);
+    for (const l of br.done)
+        say(`  ${c.ask(mark.ok)} ${l}`);
+    if (run.files.length)
+        say(c.dim(`    every file backed up first: ${tilde(run.dir)}`));
+    say(`\n  ${c.bold("Next")}  ${changed.length ? `restart ${list(changed)}, then run  ${c.violet(`${NAME} test`)}` : `run  ${c.violet(`${NAME} test`)}`}`);
+    if (br.todo)
+        say(`        add the browser hook shown above, then run your browser agent`);
+    say(c.dim(`        check the setup: ${NAME} doctor ${mark.dot} undo anytime: ${NAME} undo`));
+    return 0;
+}
+/** MCP agents: list each client's servers, ask which to guard, wrap them. A number = exit with it. */
+async function mcpSetup(v, files, url, key, run) {
     const maps = await api(url, key, "/api/workflows").then((r) => (Array.isArray(r.json) ? r.json : []), () => []);
     const mapOf = (name) => maps.find((m) => (m.apps ?? []).some((a) => norm(a) && norm(name) && (norm(a).includes(norm(name)) || norm(name).includes(norm(a)))));
     // per client: the servers it can guard (numbered, ● = matches a Work Map), the ones already guarded; the remote
@@ -298,7 +348,7 @@ async function init(v, project) {
     const cands = [], gaps = new Map();
     const all = files.flatMap((f) => f.servers);
     const w = Math.min(28, Math.max(8, ...all.map((s) => (s.name + where(s)).length)));
-    say(`\n  ${c.bold("MCP servers")}`);
+    say(`\n  ${c.bold("MCP agents")}`);
     for (const f of files) {
         say(`\n  ${c.bold(f.client)}  ${c.dim(tilde(f.path))}`);
         if (f.error)
@@ -375,7 +425,6 @@ async function init(v, project) {
     else if (!picks.length && cands.length) {
         say(c.dim(wrap("  None of these servers matches a Work Map yet, so none is guarded. Pick them with --servers a,b.", 2)));
     }
-    const run = newRun();
     const changed = [], guardedIn = new Map(), added = [];
     const userClients = new Set(files.filter((f) => f.user && !f.error).map((f) => f.client));
     for (const f of files.filter((x) => !x.error)) {
@@ -413,19 +462,131 @@ async function init(v, project) {
                 added.push(f.client);
         }
     }
-    if (!changed.length) {
-        say("  Nothing to change.");
-        return 0;
+    return { changed, guardedIn, added };
+}
+// ---- coding-agent hooks (Claude Code, Codex, Cursor): shell commands and file edits checked before they run ----
+/** Adds `getclaros hook <agent>` to each detected agent's hooks file (project scope; --user: the user's), merged
+ *  into what is there. Never asks: like the Claros MCP entry, it is part of init (--no-hooks skips it). */
+async function hookSetup(v, agents, project, run) {
+    const done = [], clients = [];
+    if (!agents.length)
+        return { done, clients };
+    say(`\n  ${c.bold("Coding-agent hooks")}  ${c.dim("shell commands and file edits checked before they run")}`);
+    const cmd = [...launcher(), "hook"].join(" ");
+    for (const a of agents) {
+        const f = hookFiles(project).find((x) => x.agent === a && x.user === !!v.user);
+        const before = existsSync(f.path) ? readFileSync(f.path, "utf8") : null;
+        let after;
+        try {
+            after = await addHooks(before ?? "", a, `${cmd} ${a}${v["fail-closed"] ? " --fail-closed" : ""}`);
+        }
+        catch (e) {
+            warn(`  ${tilde(f.path)}: ${e.message}; left unchanged`);
+            continue;
+        }
+        if (after === before) {
+            say(c.dim(`    ${f.client}: already hooked in ${tilde(f.path)}`));
+            continue;
+        }
+        say(`    ${f.client.padEnd(12)} ${c.dim(tilde(f.path))}`);
+        if (before === null)
+            mkdirSync(dirname(f.path), { recursive: true });
+        commit(run, f.path, before, after);
+        done.push(`Hooked ${f.client}  ${c.dim(`in ${tilde(f.path)}`)}`);
+        clients.push(f.client);
+    }
+    if (clients.includes("Codex"))
+        say(c.dim(wrap("    Codex runs a new hook only after you trust it: open /hooks in Codex once (project hooks also need a trusted project).", 4)));
+    return { done, clients };
+}
+const isHookPath = (p, project) => /[\\/]\.(claude[\\/]settings|codex[\\/]hooks|cursor[\\/]hooks)\.json$/.test(p) || hookFiles(project).some((f) => f.path === p);
+// ---- browser agents (Playwright, browser-use) in this project ----
+/** A shell line that exports the saved key without printing it. */
+const exportKey = () => `export CLAROS_KEY="$(node -p "require('${join(cfgDir(), "config.json").replace(homedir(), "$HOME")}').key")"`;
+/** The 2-line hook for a project, as lines to print (Playwright Test: the import of the fixture init writes). */
+function hookLines(p) {
+    if (p.fixture)
+        return [fixtureImport(p)];
+    if (p.kind === "Playwright")
+        return ['import { guard } from "getclaros-browser";', "await guard(page);   // right after you create the page"];
+    return ["from claros_browser import guard_tools", "guard_tools(tools)   # the Tools() you pass to Agent(..., tools=tools)"];
+}
+/** Each detected project's plan (install, fixture, key, hook), a question per project (Enter = yes; --yes; skipped
+ *  with --no-browser-hooks), then the install, the fixture file and CLAROS_KEY in a gitignored .env. User source
+ *  files are never edited: the hook is printed. */
+async function browserSetup(v, ps, project, at, key, run) {
+    const done = [];
+    let todo = false, wantKey = false;
+    if (!ps.length)
+        return { done, todo };
+    const env = envTarget(project);
+    const vars = { CLAROS_KEY: key,
+        ...(at.source === "pinned" ? { CLAROS_URL: at.url } : at.web !== DEFAULT_WEB ? { CLAROS_WEB_URL: at.web } : {}) };
+    const keySet = Object.entries(vars).every(([k, x]) => process.env[k] === x || (env.ok && envValue(env.path, k) === x));
+    const rel = (f) => short(f, project);
+    say(`\n  ${c.bold("Browser agents in this project")}`);
+    for (const p of ps) {
+        const row = (what, s) => say(`    ${c.dim(what.padEnd(8))} ${s}`);
+        say(`\n  ${c.bold(p.kind)}  ${c.dim(`${tilde(p.dir)} ${mark.dot} ${p.via}`)}`);
+        row("install", p.installed ? c.dim("already installed") : p.install ? c.violet(p.install.map(tilde).join(" ")) : c.dim(p.installNote));
+        if (p.fixture && !existsSync(p.fixture))
+            row("write", `${rel(p.fixture)}  ${c.dim("a fixture: every test's page goes through the guard")}`);
+        row("key", keySet ? c.dim("CLAROS_KEY already set") : env.ok ? `CLAROS_KEY ${mark.to} .env  ${c.dim("gitignored")}`
+            : c.dim(`CLAROS_KEY: export it (${env.why})`));
+        if (p.hooked)
+            row("hook", c.dim("already in place"));
+        else {
+            say(`    ${c.dim("hook".padEnd(8))} ${p.fixture ? "in" : "add to"} ${p.hookFile ? c.bold(rel(p.hookFile)) : p.fixture ? "each spec" : p.kind === "Playwright"
+                ? "the file that opens the page" : "the file that builds your Agent"}${p.more ? ` (and ${p.more} more spec${p.more > 1 ? "s" : ""})` : ""}` +
+                c.dim(p.fixture ? `, instead of "@playwright/test":` : ":"));
+            for (const l of hookLines(p))
+                say(`             ${c.violet(l)}`);
+        }
+        if (v["no-browser-hooks"]) {
+            say(c.dim("    skipped (--no-browser-hooks)"));
+            continue;
+        }
+        if (!v.yes) {
+            if (!process.stdin.isTTY) {
+                say(c.dim(`    not set up: not a terminal, pass --yes`));
+                continue;
+            }
+            const a = (await ask(`  ${c.bold(`Set up ${p.kind}?`)} ${c.dim(`Enter = yes ${mark.dot} n = skip`)} ${c.violet(mark.arrow)} `)).trim().toLowerCase();
+            if (a && !a.startsWith("y"))
+                continue;
+        }
+        if (!p.installed && p.install) {
+            say(c.dim(`    running ${p.install.map(tilde).join(" ")}`));
+            const r = spawnSync(p.install[0], p.install.slice(1), { cwd: p.dir, stdio: ["ignore", 2, 2], shell: process.platform === "win32" });
+            if (r.status === 0)
+                done.push(`Installed ${p.kind === "Playwright" ? "getclaros-browser" : "claros-browser"}  ${c.dim(`with ${p.install[0].includes("python") ? "pip" : p.install[0]}`)}`);
+            else
+                warn(`  ${p.install.map(tilde).join(" ")} failed (${r.error?.message ?? `exit ${r.status}`}); run it yourself`);
+        }
+        if (p.fixture && !existsSync(p.fixture)) {
+            commit(run, p.fixture, null, fixtureText(p.fixture));
+            done.push(`Wrote ${rel(p.fixture)}`);
+        }
+        wantKey = true;
+        todo ||= !p.hooked;
     }
-    const list = (xs) => [...new Set(xs)].join(", ");
-    for (const [n, cl] of guardedIn)
-        say(`  ${c.ask(mark.ok)} Guarded ${c.bold(n)}  ${c.dim(`in ${list(cl)}`)}`);
-    if (added.length)
-        say(`  ${c.ask(mark.ok)} Added the Claros MCP server  ${c.dim(`in ${list(added)}`)}`);
-    say(c.dim(`    every file backed up first: ${tilde(run.dir)}`));
-    say(`\n  ${c.bold("Next")}  restart ${list(changed)}, then run  ${c.violet(`${NAME} test`)}`);
-    say(c.dim(`        undo anytime: ${NAME} undo`));
-    return 0;
+    say();
+    if (wantKey && !keySet) {
+        if (env.ok) {
+            const before = readFileSync(env.path, "utf8");
+            commit(run, env.path, before, setEnv(before, vars), Object.keys(vars));
+            done.push(`Set ${Object.keys(vars).join(", ")} in .env  ${c.dim(`key ${keyId(key)} ${mark.dot} gitignored`)}`);
+        }
+        else {
+            say(`  ${c.bold("CLAROS_KEY")}  ${c.dim(`not written to a file (${env.why}); in the shell that runs the agent:`)}`);
+            say(`    ${c.violet(exportKey())}  ${c.dim(`# key ${keyId(key)}`)}`);
+            for (const [k, x] of Object.entries(vars))
+                if (k !== "CLAROS_KEY")
+                    say(`    ${c.violet(`export ${k}=${x}`)}`);
+            say();
+        }
+    }
+    return { done, todo };
 }
 // ---- test ----
 async function test(v, project) {
@@ -452,7 +613,10 @@ async function test(v, project) {
         }
         if (ex.status !== 200)
             throw new Error(`HTTP ${ex.status}`);
-        const e = ex.json, t0 = Date.now();
+        const e = ex.json;
+        if (e.demo && e.examples?.length > 1)
+            return await demo(e, url, key, guarded);
+        const t0 = Date.now();
         const r = await api(url, key, "/v1/check", { workflow_id: e.workflow_id, app: e.app ?? guarded[0] ?? undefined,
             tool: "getclaros_test", actor: "getclaros test", state: e.state });
         if (r.status !== 200)
@@ -466,14 +630,7 @@ async function test(v, project) {
         const held = r.json.result === "ask", ink = held ? c.ask : c.stop;
         say(`  ${ink(c.bold(`${held ? mark.ask : mark.stop} ${held ? "Held to ask first" : "Stopped"} in ${dur(ms)}`))}  ` +
             c.dim(`Work Map "${e.name}" ${mark.dot} check ${r.json.check_id}`));
-        for (const x of r.json.violations.filter((x) => x.action === "stop" || x.action === "ask")) {
-            const ask = x.action === "ask", p = ask ? c.ask : c.stop;
-            say();
-            say(`    ${p(`${ask ? mark.ask : mark.stop} ${ask ? "ask " : "stop"}`)}  ${c.bold(wrap(x.rule, 12))}`);
-            if (x.quote)
-                say(`            ${wrap(`“${x.quote}”`, 12)}${x.expert ? c.dim(` ${mark.dash} ${x.expert}`) : ""}`);
-            say(`            ${c.dim("Who to ask:")} ${x.who_to_ask || x.owner || x.expert || "the process owner"}`);
-        }
+        stopCards(r.json);
         say();
         say(c.dim(wrap(`  Test action for ${e.app ?? "a demo app"}, made up, only checked: ${Object.entries(e.state).map(([k, x]) => `${k} = ${x}`).join(", ")}`, 4)));
         say(wrap(`  Your agent gets the rule as the tool's error. Nothing reached ${e.app ?? "any app"}.`, 2));
@@ -486,6 +643,57 @@ async function test(v, project) {
         return 3;
     }
 }
+/** a card per stop / ask rule the check broke: the rule, the expert's words, who to ask */
+function stopCards(r) {
+    for (const x of r.violations.filter((x) => x.action === "stop" || x.action === "ask")) {
+        const ask = x.action === "ask", p = ask ? c.ask : c.stop;
+        say();
+        say(`    ${p(`${ask ? mark.ask : mark.stop} ${ask ? "ask " : "stop"}`)}  ${c.bold(wrap(x.rule, 12))}`);
+        if (x.quote)
+            say(`            ${wrap(`“${x.quote}”`, 12)}${x.expert ? c.dim(` ${mark.dash} ${x.expert}`) : ""}`);
+        say(`            ${c.dim("Who to ask:")} ${x.who_to_ask || x.owner || x.expert || "the process owner"}`);
+    }
+}
+/** a made-up record on one line: whitespace in strings collapsed, long values cut */
+const record = (tool, state) => `${tool ? `${tool} ` : ""}${Object.entries(state).map(([k, x]) => {
+    const v = typeof x === "string" ? x.replace(/\s+/g, " ").trim() : String(x);
+    return `${k} = ${v.length > 80 ? v.slice(0, 79) + "…" : v}`;
+}).join(", ")}`;
+/** demo (no guarded server matches a map): the starter maps' examples, a stop then a nudge, checked side by side */
+async function demo(e, url, key, guarded) {
+    const t0 = Date.now();
+    const rs = await Promise.all(e.examples.map((x) => api(url, key, "/v1/check", { workflow_id: x.workflow_id, tool: x.tool, actor: "getclaros test", state: x.state })));
+    const bad = rs.find((r) => r.status !== 200);
+    if (bad)
+        throw new Error(`HTTP ${bad.status}`);
+    const ms = Date.now() - t0, [stop, ...rest] = rs.map((r) => r.json), [se, ...re] = e.examples;
+    if (stop.allowed) {
+        say(`  ${c.stop(mark.no)} Claros let it through (check ${stop.check_id}). It should have been stopped by rule ${se.guardrail_id}; tell the Claros team.`);
+        return 1;
+    }
+    const held = stop.result === "ask", nudged = rest.some((r) => r.result === "nudge");
+    const outcome = [(held ? c.ask : c.stop)(c.bold(`${held ? mark.ask : mark.stop} ${held ? "Held to ask first" : "Stopped"}`)),
+        ...(nudged ? [c.nudge(c.bold(`${mark.nudge} Nudged`))] : [])].join(` ${mark.dot} `);
+    say(`  ${outcome}  ${c.dim(`${rs.length} checks in ${dur(ms)}`)}`);
+    stopCards(stop);
+    say(c.dim(`            ${wrap(`Test action: ${record(se.tool, se.state)}`, 12)}`));
+    rest.forEach((r, i) => {
+        const x = r.violations.find((v) => v.action === "nudge"), ex = re[i];
+        say();
+        say(`    ${c.nudge(`${mark.nudge} nudge`)} ${c.bold(wrap(x?.rule ?? ex.rule ?? `Work Map "${ex.name}"`, 12))}`);
+        if (x?.quote)
+            say(`            ${wrap(`“${x.quote}”`, 12)}${x.expert ? c.dim(` ${mark.dash} ${x.expert}`) : ""}`);
+        if (x?.fix)
+            say(`            ${c.nudge(mark.to)} ${wrap(x.fix, 14)}`);
+        else if (!x)
+            say(c.dim(`            Not judged this time (${r.judge?.error ?? r.judge?.status ?? "the server's judge is off"}).`));
+        say(c.dim(`            ${wrap(`Test action: ${record(ex.tool, ex.state)}`, 12)}`));
+    });
+    say();
+    say(wrap("  Your agent gets a stop as the tool's error; a nudge lets the call through, with the fix. Nothing reached any app.", 2));
+    say(c.dim(wrap(`  Demo: ${guarded.length ? `none of your guarded servers (${guarded.join(", ")}) matches a Work Map` : "no server is guarded yet"}, so this used the Starter maps (examples, not enforced; delete them on the web).`, 2)));
+    return 0;
+}
 // ---- export ----
 /** A Work Map's rules as markdown on stdout (GET /v1/maps/<id>/export): redirect it into AGENTS.md, DESIGN.md or a
  *  skill's SKILL.md. An advisory copy: Claros still enforces the rules when an agent acts. */
@@ -542,8 +750,10 @@ async function override(v, checkId) {
         return 3;
     }
 }
-// ---- status ----
-async function status(v, project) {
+// ---- doctor (status is the same command) ----
+/** Per agent type: is it guarded and can it reach Claros, with the command that fixes what isn't.
+ *  Exit: 0 all good, 1 a browser agent here isn't set up, 2 no key, 3 Claros unreachable or the key rejected. */
+async function doctor(v, project) {
     header();
     const at = await locate(v);
     if (!at)
@@ -556,7 +766,16 @@ async function status(v, project) {
     const fine = up && ks === "valid";
     say(`  ${ok(fine, fine ? mark.ok : mark.no)} ${c.bold("Claros")}  ${url}  ${ok(up, up ? "reachable" : "unreachable")}` +
         `  key ${key ? keyId(key) + " " : ""}${ok(ks === "valid", ks)}${ws ? `  workspace "${ws}"` : ""}`);
-    for (const f of detect(project)) {
+    const fix = (s) => say(`    ${c.violet(mark.to)} ${s}`);
+    if (!key || /rejected|scope/.test(ks))
+        fix(`${NAME} init  ${c.dim("signs in and saves an agent key")}`);
+    else if (!up)
+        fix(c.dim(`check your network; a moved server is followed on the next run (or pass --url)`));
+    const files = detect(project);
+    say(`\n  ${c.bold("MCP agents")}`);
+    if (!files.length)
+        say(c.dim("    none found (Claude Code, Claude Desktop, Cursor, VS Code, Codex)"));
+    for (const f of files) {
         say(`\n  ${c.bold(f.client)}  ${c.dim(tilde(f.path))}${f.error ? `  couldn't read it (${f.error})` : ""}`);
         for (const s of f.servers) {
             const [m, state] = s.ours ? [c.violet(mark.dot), c.dim("Claros MCP server")] : s.guarded ? [c.ask(mark.ok), c.ask("guarded")]
@@ -564,9 +783,67 @@ async function status(v, project) {
             say(`    ${m} ${(s.name + where(s)).padEnd(24)} ${state}`);
         }
     }
-    return !key ? 2 : up && ks === "valid" ? 0 : 3;
+    const servers = files.flatMap((f) => f.servers.filter((s) => !s.ours));
+    if (servers.some((s) => !s.guarded && !s.gap))
+        fix(`${NAME} init  ${c.dim(`guards the servers you pick${servers.some((s) => s.guarded) ? "" : " (none is guarded yet)"}`)}`);
+    // coding-agent hooks: per agent, the files that hold ours
+    const agents = hookAgents(project), hooked = new Map();
+    for (const f of hookFiles(project))
+        if (await hasHooks(f.path))
+            hooked.set(f.client, [...(hooked.get(f.client) ?? []), tilde(f.path)]);
+    const named = { "claude-code": "Claude Code", codex: "Codex", cursor: "Cursor" };
+    const clientsHere = [...new Set([...agents.map((a) => named[a]), ...hooked.keys()])];
+    if (clientsHere.length)
+        say(`\n  ${c.bold("Coding-agent hooks")}  ${c.dim("shell commands and file edits")}`);
+    for (const cl of clientsHere) {
+        const at = hooked.get(cl);
+        say(`    ${at ? c.ask(mark.ok) : c.dim(mark.off)} ${cl.padEnd(24)} ${at ? `${c.ask("hooked")}  ${c.dim(at.join(", "))}` : "not hooked"}`);
+    }
+    if (clientsHere.some((cl) => !hooked.has(cl)))
+        fix(`${NAME} init  ${c.dim("adds the hooks (project scope; --user for all projects)")}`);
+    // browser agents: package installed, hook present, a key the agent can read (env or a safe .env)
+    let broken = false;
+    const ps = detectBrowser(project);
+    if (ps.length)
+        say(`\n  ${c.bold("Browser agents in this project")}`);
+    const env = envTarget(project), fromFile = envValue(env.path, "CLAROS_KEY");
+    const agentKey = process.env.CLAROS_KEY || fromFile;
+    const aks = !ps.length || !agentKey ? "" : agentKey === key ? ks : await keyStatus(url, agentKey);
+    for (const p of ps) {
+        const row = (good, s, hint) => {
+            broken ||= !good;
+            say(`    ${ok(good, good ? mark.ok : mark.no)} ${s}`);
+            if (!good && hint)
+                fix(hint);
+        };
+        say(`\n  ${c.bold(p.kind)}  ${c.dim(`${tilde(p.dir)} ${mark.dot} ${p.via}`)}`);
+        const pkg = p.kind === "Playwright" ? "getclaros-browser" : "claros-browser";
+        row(p.installed, `${pkg} ${p.installed ? "installed" : "not installed"}`, p.install ? `${p.install.map(tilde).join(" ")}  ${c.dim(`(or ${NAME} init)`)}` : p.installNote);
+        row(p.hooked, p.hooked ? `hook in place${p.fixture ? ` (${short(p.fixture, project)})` : ""}` : "no hook yet", p.fixture && !existsSync(p.fixture) ? `${NAME} init  ${c.dim(`writes ${short(p.fixture, project)}; then import from it in your specs`)}`
+            : `${p.hookFile ? `in ${short(p.hookFile, project)}` : "add"}:\n${hookLines(p).map((l) => `        ${l}`).join("\n")}`);
+        if (!agentKey)
+            row(false, "CLAROS_KEY not set", env.ok ? `${NAME} init  ${c.dim("writes it to .env (gitignored)")}` : `${exportKey()}  ${c.dim(`(${env.why})`)}`);
+        else if (fromFile && !process.env.CLAROS_KEY && !env.ok) {
+            row(false, `CLAROS_KEY is in .env, but ${env.why}`, `move it out of .env, and make a new key if it was ever committed`);
+        }
+        else
+            row(aks === "valid", `CLAROS_KEY ${keyId(agentKey)} from ${process.env.CLAROS_KEY ? "the environment" : ".env"} ${aks}`, `${NAME} init  ${c.dim("writes a valid key")}`);
+    }
+    return !key ? 2 : !(up && ks === "valid") ? 3 : broken ? 1 : 0;
 }
 // ---- undo ----
+/** Our hook entries out of a hooks file that changed since init; the rest stays. */
+async function unhook(safety, path, cur) {
+    try {
+        const t = await removeHooks(cur);
+        if (t !== cur)
+            commit(safety, path, cur, t);
+        say(`  ${c.ask(mark.ok)} ${tilde(path)}: changed since init, so removed the Claros hooks in place and kept the other edits`);
+    }
+    catch (e) {
+        warn(`${tilde(path)}: couldn't read it (${e.message}); remove the getclaros hook entries yourself`);
+    }
+}
 /** Unwraps every guarded server and removes our Claros entry in place; the rest of the file stays. */
 function unwrapAll(f) {
     let n = 0;
@@ -601,10 +878,29 @@ async function undo(v, project) {
         }
         const cur = readFileSync(path, "utf8");
         const same = sha(cur) === chain.at(-1).after && chain.every((b, i) => !i || b.before === chain[i - 1].after);
-        if (same) {
+        const vars = chain.flatMap((b) => b.vars ?? []);
+        if (chain[0].created) { // a file init wrote (the Playwright fixture): deleted only while it's exactly what init wrote
+            if (same) {
+                unlinkSync(path);
+                say(`  ${c.ask(mark.ok)} ${tilde(path)}: removed (init wrote it)`);
+            }
+            else if (isHookPath(path, project))
+                await unhook(safety, path, cur);
+            else
+                warn(`${tilde(path)}: changed since init wrote it; left in place (delete it yourself)`);
+        }
+        else if (!same && vars.length) { // a .env edited since: drop only the lines init set
+            const t = cur.replace(new RegExp(`^(export\\s+)?(${vars.join("|")})=.*(\\r?\\n|$)`, "gm"), "");
+            if (t !== cur)
+                commit(safety, path, cur, t);
+            say(`  ${c.ask(mark.ok)} ${tilde(path)}: changed since init, so removed ${vars.join(", ")} and kept the other lines`);
+        }
+        else if (same) {
             commit(safety, path, cur, readFileSync(chain[0].backup, "utf8"));
             say(`  ${c.ask(mark.ok)} ${tilde(path)}: restored from the backup taken before init (unchanged since)`);
         }
+        else if (isHookPath(path, project))
+            await unhook(safety, path, cur);
         else {
             const f = byPath.get(path) ?? detect(project).find((x) => x.path === path);
             if (!f || f.error) {
@@ -619,6 +915,9 @@ async function undo(v, project) {
         byPath.delete(path);
     }
     if (v.all) {
+        for (const f of hookFiles(project))
+            if (!chains.has(f.path) && await hasHooks(f.path))
+                await unhook(safety, f.path, readFileSync(f.path, "utf8"));
         for (const f of byPath.values()) {
             if (f.error)
                 continue;

package/dist/ui.js

@@ -27,7 +27,7 @@ const U = S.uni;
 /** stop = the seal, ask = the thread hooked to a person, nudge = the proofreader's pencil */
 export const mark = {
     stop: U ? "◉" : "x", ask: U ? "↳" : "?", nudge: U ? "✎" : "~", ok: U ? "✓" : "+", no: U ? "✗" : "x",
-    on: U ? "●" : "*", off: U ? "○" : "o", dot: U ? "·" : "-", arrow: U ? "›" : ">", dash: U ? "—" : "-",
+    on: U ? "●" : "*", off: U ? "○" : "o", dot: U ? "·" : "-", arrow: U ? "›" : ">", dash: U ? "—" : "-", to: U ? "→" : "->",
 };
 export const say = (s = "") => process.stdout.write(s + "\n");
 /** claros” and the version: only on a terminal (piped output starts with what it says) */

package/dist/verdict.js

@@ -0,0 +1,54 @@
+// What an agent reads when Claros stops, holds or nudges an action: shared by the MCP guard (cli.ts) and the coding-agent
+// hooks (hooks.ts).
+import { readFileSync } from "node:fs";
+const NAME = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).name;
+/** `head` replaces the first line (a decided ask: who said no, or that nobody answered). */
+export function stopText(r, head) {
+    const hits = (r.violations || []).filter((v) => v.action === "stop" || v.action === "ask");
+    const maps = [...new Set(hits.map((v) => v.workflow_id ?? r.workflow_id))];
+    const from = `expert-approved Work Map${maps.length > 1 ? "s" : ""} ${maps.map((m) => `"${m}"`).join(", ")}`;
+    const out = [head ?? (r.result === "ask" // ask only: not refused for good, waiting on a person
+            ? `Claros held this action: ${hits.length === 1 ? "a rule" : "rules"} from the ${from} ${hits.length === 1 ? "says" : "say"} to ask first. Do not run it without that answer.`
+            : `Claros stopped this action: it breaks ${hits.length === 1 ? "a rule" : "rules"} from the ${from}. Do not retry it as is.`)];
+    for (const v of hits) {
+        const who = v.who_to_ask || v.owner || v.expert || "the process owner";
+        out.push("", `Rule: ${v.rule}`);
+        if (v.reason)
+            out.push(`Why Claros stopped it: ${v.reason}`); // fuzzy rules: the judge's one-line reason
+        if (v.quote)
+            out.push(`${v.source === "doc" ? "In the written policy" : "In the expert's words"}${v.expert ? ` (${v.expert})` : ""}: "${v.quote}"`);
+        out.push(`Who to ask: ${who}`);
+        out.push(v.action === "ask"
+            ? `Next: stop and ask ${who} before doing this; continue only with their answer.`
+            : `Next: change the record so the rule holds, or ask ${who} to approve an exception. Tell the user why.`);
+    }
+    // an ask opened a question to the rule's owner (server: knowledge/approvals.py); its answer is at the decision URL
+    if (r.question?.decision_url && !head)
+        out.push("", `Claros asked the rule's owner (check ${r.check_id}); their answer: GET ${r.question.decision_url}`);
+    // an override goes to the rule's expert as a report; the rule stays as it is until they confirm a change
+    if (r.check_id) {
+        out.push("", "If this stop is wrong, tell the rule's expert why (the rule stays until they change it):");
+        for (const v of hits)
+            out.push(`npx ${NAME} override ${r.check_id} --rule ${v.guardrail_id} --reason "<why it was fine>"`);
+    }
+    return out.join("\n");
+}
+// a nudge lets the call through; "warn" is its old name (older Claros servers)
+export const nudgesOf = (r) => (r.violations || []).filter((v) => v.action === "nudge" || v.action === "warn");
+/** The extra text item on a nudged call's result: the rule, the expert's words and the fix, so the agent can
+ *  correct this record (if it still can) and the next ones. */
+export function nudgeText(r) {
+    const hits = nudgesOf(r);
+    const out = [`Claros nudge: the call went through, but it doesn't follow ${hits.length === 1 ? "a rule" : "rules"} ` +
+            `your team holds. Fix it if you still can, and follow ${hits.length === 1 ? "it" : "them"} from now on.`];
+    for (const v of hits) {
+        out.push("", `Rule: ${v.rule}`);
+        if (v.reason)
+            out.push(`Why: ${v.reason}`);
+        if (v.quote)
+            out.push(`${v.source === "doc" ? "In the written policy" : "In the expert's words"}${v.expert ? ` (${v.expert})` : ""}: "${v.quote}"`);
+        if (v.fix)
+            out.push(`Suggested fix: ${v.fix}`);
+    }
+    return out.join("\n");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "getclaros",
-  "version": "0.1.1",
-  "description": "Claros guard: checks an agent's MCP tool calls against your experts' rules before they run",
+  "version": "0.3.0",
+  "description": "Claros guard: checks an agent's MCP tool calls, shell commands and file edits against your experts' rules before they run",
   "license": "MIT",
   "type": "module",
   "bin": {