getclaros 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,8 @@
 # getclaros guard
 
-A local stdio MCP proxy. It wraps an app's MCP server and checks every write tool call against the company's
-expert-approved Work Maps (`POST /v1/check`) before the call reaches the app. A call that breaks a rule is never
+A local stdio MCP proxy, plus native hooks for coding agents. It wraps an app's MCP server and checks every write tool
+call against the company's expert-approved Work Maps (`POST /v1/check`) before the call reaches the app; the hooks
+check a coding agent's shell commands and file edits the same way ([Coding agents](#coding-agents-claude-code-codex-cursor-shell-commands-and-file-edits)). A call that breaks a rule is never
 forwarded; the agent gets a tool error with the rule, the expert's words and who to ask.
 
 The package name (`getclaros`) is a placeholder and lives only in `package.json`.
@@ -21,7 +22,7 @@ or browser-use project, installs the browser hook with that project's own packag
 is guarded and can reach Claros.
 
 ```
-  claros”  getclaros 0.2.0
+  claros”  getclaros 0.3.0
 
   Sign in  opening your browser
   › https://claros-eta.vercel.app/device?code=ZQRC-ZCTP
@@ -86,6 +87,37 @@ What it changes, in files that already exist (it never creates a client config):
   up front with `get_workflow`; in each client's user config (or its project config when it has no user config).
 - Every file is backed up before it changes (`~/.config/getclaros/backups/<time>/`) and written atomically.
 
+### Coding agents (Claude Code, Codex, Cursor): shell commands and file edits
+
+The MCP guard sees MCP tool calls only. A coding agent also runs shell commands and edits files with its own built-in
+tools, so `init` adds a native hook to each coding agent it finds (its directory exists in your home or the project):
+the agent runs `npx -y getclaros hook <agent>` before each shell command or file edit, the hook asks Claros
+(`POST /v1/check`) and answers in the agent's own protocol. MCP calls stay with the MCP guard, so nothing is checked
+twice.
+
+| Agent | Hooks file (project scope; `--user`: all projects) | Checked | stop | ask | nudge |
+|---|---|---|---|---|---|
+| Claude Code | `.claude/settings.json` (`~/.claude/settings.json`), `PreToolUse` on `Bash\|PowerShell\|Edit\|Write\|NotebookEdit` | shell, edits | denied; the rule, the expert's words and who to ask go to Claude | Claude Code's own ask: you confirm, with the owner and check id | allowed, the rule and fix added to Claude's context |
+| Codex | `.codex/hooks.json` (`$CODEX_HOME/hooks.json`), `PreToolUse` on `Bash` and `apply_patch` | shell, edits (the files named in the patch) | denied, with the rule | denied with "ask <owner>" and the check id (Codex has no ask on `PreToolUse`) | allowed, added as context |
+| Cursor | `.cursor/hooks.json` (`~/.cursor/hooks.json`), `beforeShellExecution` + `preToolUse` on `Write\|Delete` | shell, edits | denied; the rule goes to the agent | shell: Cursor's own ask; edits: denied with the owner (Cursor doesn't enforce ask on `preToolUse` yet) | allowed, the rule and fix go to the agent |
+
+- The action Claros sees: `tool` `shell` with `{command, cwd, project}`, or `write_file` / `edit_file` /
+  `delete_file` with `{file_path (relative to the project), content or diff, project}`; `actor` is the agent. The
+  project is the agent's project directory, else the git root, else the working directory. Content over 20,000
+  characters is cut.
+- Merged into what the file holds: your own hooks and settings stay, ours is appended once, and `init` again changes
+  nothing. `undo` restores the file from its backup, or, if you changed it since, removes only our entries.
+- Fail-open by default: when Claros can't be reached, times out (`--timeout`, 5000 ms) or rejects the key, the action
+  runs and the agent shows a warning ("Claros couldn't check … it ran unchecked"). `init --fail-closed` installs
+  `hook <agent> --fail-closed`, which blocks instead.
+- The hook reads the key from `$CLAROS_KEY`, the saved config or the project's `.env`, and the server from the saved
+  config (asked from the web app once, then cached). Nothing secret goes into the hooks file, so a project
+  `.claude/settings.json` can be committed; a teammate without a key gets the fail-open warning until they run `init`.
+- Codex runs a new or changed hook only after you trust it in `/hooks`, and project hooks only in a trusted project.
+- Each call starts `npx`; for less latency install the package (`npm i -g getclaros`) and run `init` with
+  `GETCLAROS_LAUNCHER=getclaros`.
+- `--no-hooks` skips this part of `init`; `doctor` lists which agents are hooked and where.
+
 ### Browser agents (Playwright, browser-use)
 
 `init` also looks at the project directory (the current one, or `--project <dir>`):

package/dist/cli.js

@@ -7,11 +7,15 @@
 // When Claros needs the record a call targets (a submit by name, a partial record, an item's group), it answers
 // `need`; the guard reads those records itself through the wrapped server's read tools (ids the client never sees),
 // or through another guarded server's guard when the need names its app (peers.ts), and asks again. stdout carries the protocol: every log line goes to stderr.
+// An "ask" opens a question to the rule's owner in Claros: the guard waits (--ask-wait, default 120 s) on the decision
+// URL and forwards the call only when it is approved for this exact call (sha256 of {app, tool, arguments}); a denial
+// or no answer comes back as the stop, with the reason.
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { reduceRows, rowsOf } from "./query.js";
+import { nudgesOf, nudgeText, stopText } from "./verdict.js";
 import { ask, serve } from "./peers.js";
 import { DEFAULT_WEB, loadConfig, relocate, resolve } from "./config.js";
 // the package name lives in package.json only (placeholder until decided)
@@ -20,8 +24,11 @@ const NAME = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)
 const READ = /^(get|list|search|read|find|describe|fetch)|^(check|run|export)_|^(version|ping)$/i;
 const LOOKUP_TTL = 60_000, KINDS_TTL = 30_000;
 const GUARD_USAGE = `       ${NAME} guard --server <name> [--url <claros server> | --web <claros web app>] [--key <key> | env CLAROS_KEY]
-                [--timeout <ms>] [--fail-open] (-- <command> [args...] | --remote <mcp url> [--header "K: V" ...])
+                [--timeout <ms>] [--fail-open] [--ask-wait <seconds, 0 = don't wait>]
+                (-- <command> [args...] | --remote <mcp url> [--header "K: V" ...])
        ${NAME} mcp     (the Claros MCP server over stdio, with the saved key)
+       ${NAME} hook <claude-code|codex|cursor> [--fail-closed] [--timeout <ms>]   (run by the agent per shell
+                command or file edit; init installs it)
 Server: --url / CLAROS_URL, else the saved one, else asked from the web app (--web / CLAROS_WEB, default
 https://claros-eta.vercel.app, at /.well-known/claros.json). Help: ${NAME} <command> --help`;
 const log = (s) => process.stderr.write(`[${NAME} guard] ${s}\n`);
@@ -60,52 +67,11 @@ function parse(b) {
         return undefined;
     }
 }
-function stopText(r) {
-    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 = [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 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)
-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. */
-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");
-}
+/** JSON with sorted keys, as the server's approvals.payload_hash canonicalises it. */
+const canon = (v) => Array.isArray(v) ? v.map(canon) : v !== null && typeof v === "object"
+    ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canon(v[k])])) : v;
+/** sha256 of the exact action: an approval in Claros carries the hash of the call it was given for. */
+const payloadHash = (app, tool, args) => createHash("sha256").update(JSON.stringify(canon({ app, tool, arguments: args }))).digest("hex");
 /** fetch, and once more at the web app's current server address if this one didn't answer (it moved). */
 async function reach(o, path, init = {}) {
     const go = async () => {
@@ -128,12 +94,34 @@ async function check(o, tool, args, fetched = {}) {
         method: "POST",
         headers: { "content-type": "application/json", ...(o.key ? { authorization: `Bearer ${o.key}` } : {}) },
         body: JSON.stringify({ app: o.server, tool, action: tool, state: flatten(args ?? {}), arguments: args ?? {},
-            ...(Object.keys(fetched).length ? { fetched } : {}) }),
+            ...(Object.keys(fetched).length ? { fetched } : {}), ...(o.askWait > 0 ? { ask_wait: o.askWait } : {}) }),
     });
     if (!res.ok)
         throw new Error(`HTTP ${res.status}`);
     return res.json();
 }
+/** An ask's answer: long-polls the decision URL until the owner decides or Claros times the question out (at
+ *  ask_wait, plus a few seconds' grace). null = still open (Claros unreachable or late). */
+async function decision(o, r, hash) {
+    const end = Date.now() + o.askWait * 1000 + 5000;
+    const headers = o.key ? { authorization: `Bearer ${o.key}` } : {};
+    while (Date.now() < end) {
+        const wait = Math.max(1, Math.min(25, Math.ceil((end - Date.now()) / 1000)));
+        try {
+            const res = await fetch(`${o.url}${r.question.decision_url}?wait=${wait}&payload_sha256=${hash}`, { headers, signal: AbortSignal.timeout(wait * 1000 + o.timeout) });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const v = await res.json();
+            if (v.status !== "open")
+                return v;
+        }
+        catch (e) {
+            log(`decision poll failed (${e.message}); retrying`);
+            await new Promise((ok) => setTimeout(ok, 1000));
+        }
+    }
+    return null;
+}
 /** A read tool's result → the record: structuredContent, else JSON in the text (whole, or its outermost {...}). */
 function recordOf(tool, m) {
     if (m?.error || m?.result?.isError)
@@ -369,7 +357,20 @@ function guard(o, connect) {
             return toServer(line);
         }
         log(`${o.server} ${name} → ${r.result === "ask" ? "ask" : "stop"} ${wf} ${ids} ${ms} ${r.check_id ?? ""}`);
-        reply(stopText(r));
+        if (r.result !== "ask" || !r.question?.decision_url || o.askWait <= 0)
+            return reply(stopText(r));
+        const hash = payloadHash(o.server, name, args ?? {});
+        const who = r.violations?.find((v) => v.action === "ask")?.who_to_ask || "the rule's owner";
+        log(`  waiting up to ${o.askWait}s for ${who}'s answer`);
+        const v = await decision(o, r, hash);
+        if (v?.decision === "approve" && v.payload_sha256 === hash) {
+            log(`${o.server} ${name} → approved by ${v.approver} (${v.authority}) ${r.check_id}`);
+            return toServer(line);
+        }
+        log(`${o.server} ${name} → ${v?.decision ?? "no answer"} ${r.check_id}`);
+        reply(stopText(r, v?.decision === "approve" ? "Claros stopped this action: the approval was for a different action than this call. Do not run it."
+            : v?.decision === "deny" ? `Claros stopped this action: ${v.approver ?? who} said no${v.reason ? `: ${v.reason}` : "."} Do not retry it as is.`
+                : `Claros stopped this action: no answer from ${who} within ${o.askWait} s. Do not run it without their answer.`));
     }
     lines(process.stdin, (line) => {
         const msg = parse(line);
@@ -404,6 +405,10 @@ async function main(argv) {
     }
     if (argv[0] === "mcp")
         return void import("./bridge.js").then((m) => m.bridge());
+    if (argv[0] === "hook") { // a coding agent's per-tool-call hook (hooks.ts)
+        process.exitCode = await (await import("./hooks.js")).main(argv.slice(1));
+        return;
+    }
     if (["init", "test", "status", "doctor", "undo", "export", "override"].includes(argv[0])) {
         process.exitCode = await (await import("./setup.js")).run(argv);
         return;
@@ -421,7 +426,7 @@ async function main(argv) {
             options: {
                 server: { type: "string" }, url: { type: "string" }, web: { type: "string" }, key: { type: "string" },
                 timeout: { type: "string" }, "fail-open": { type: "boolean" }, remote: { type: "string" },
-                header: { type: "string", multiple: true },
+                header: { type: "string", multiple: true }, "ask-wait": { type: "string" },
             },
         }).values;
     }
@@ -432,6 +437,9 @@ async function main(argv) {
         return fail(); // a command or a remote URL, not both
     if (v.remote && !/^https?:\/\/\S+$/.test(v.remote))
         return fail("--remote wants an http(s) URL\n");
+    const askWait = Number(v["ask-wait"] ?? 120);
+    if (!(askWait >= 0))
+        return fail("--ask-wait wants seconds (0 = don't wait)\n");
     const headers = {};
     for (const h of v.header ?? []) {
         const i = h.indexOf(":");
@@ -451,6 +459,6 @@ async function main(argv) {
     }
     if (!at.key)
         log("no key (set CLAROS_KEY): every write check will fail" + (v["fail-open"] ? " open" : " closed"));
-    guard({ ...at, server: v.server, failOpen: !!v["fail-open"], timeout: Number(v.timeout ?? 5000) }, v.remote ? http(v.remote, headers) : stdio(cmd[0], cmd.slice(1)));
+    guard({ ...at, server: v.server, failOpen: !!v["fail-open"], timeout: Number(v.timeout ?? 5000), askWait }, v.remote ? http(v.remote, headers) : stdio(cmd[0], cmd.slice(1)));
 }
 main(process.argv.slice(2));

package/dist/hooks.js

@@ -0,0 +1,348 @@
+// Coding-agent hooks: `getclaros hook <agent>` runs once per tool call, reads the agent's hook payload on stdin, maps a
+// shell command or a file edit to a Claros action, asks POST /v1/check and answers in the agent's own protocol.
+// MCP tool calls are left to the MCP guard (cli.ts), so nothing is checked twice.
+// Protocols (official docs, read 2026-10-24):
+// - Claude Code  https://code.claude.com/docs/en/hooks  settings.json {hooks: {PreToolUse: [{matcher, hooks: [{type:
+//     "command", command, timeout}]}]}}; stdin {cwd, tool_name, tool_input}; stdout hookSpecificOutput {permissionDecision
+//     allow|deny|ask, permissionDecisionReason (deny: to Claude, ask: to the user), additionalContext}, systemMessage.
+// - Codex  https://developers.openai.com/codex/hooks  hooks.json, same shape; shell = Bash, edits = apply_patch (the
+//     patch in tool_input.command). "ask" is not supported on PreToolUse (the call would run): ask blocks instead.
+//     Hooks run only after the user trusts them in /hooks; project hooks only in a trusted project.
+// - Cursor  https://cursor.com/docs/hooks  hooks.json {version: 1, hooks: {beforeShellExecution: [{command}],
+//     preToolUse: [{command, matcher}]}}; stdout {permission allow|deny|ask, user_message, agent_message}. There is no
+//     before-edit event: preToolUse on Write/Delete gates edits; its "ask" isn't enforced yet, so ask blocks there.
+// Kept light: node builtins, config.js and verdict.js at run time; jsonc-parser only when installing.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { loadConfig, relocate, resolve, saveConfig } from "./config.js";
+import { nudgesOf, nudgeText, stopText } from "./verdict.js";
+export const AGENTS = ["claude-code", "codex", "cursor"];
+const MAX = 20_000; // ponytail: a huge write is checked on its first 20k chars; send a summary if rules need the rest
+const cut = (s) => { const t = String(s ?? ""); return t.length > MAX ? t.slice(0, MAX) + "\n…(truncated)" : t; };
+/** The project root: the agent's own variable, else the nearest git root above cwd, else cwd. */
+export function rootOf(p, cwd, env = process.env) {
+    const set = env.CLAUDE_PROJECT_DIR || env.CURSOR_PROJECT_DIR || p.workspace_roots?.[0];
+    if (set)
+        return set;
+    for (let d = cwd;; d = dirname(d)) {
+        if (existsSync(join(d, ".git")))
+            return d;
+        if (dirname(d) === d)
+            return cwd;
+    }
+}
+const rel = (f, root) => {
+    const r = isAbsolute(f) ? relative(root, f) : f;
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r.split(sep).join("/") : f;
+};
+const diffOf = (edits) => edits.map((e) => [...String(e.old_string ?? "").split("\n").map((l) => `-${l}`), ...String(e.new_string ?? "").split("\n").map((l) => `+${l}`)].join("\n"))
+    .join("\n");
+/** Files an apply_patch envelope touches (*** Add / Update / Delete File: …, *** Move to: …). */
+export const patchFiles = (patch) => [...patch.matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/gm)].map((m) => m[1].trim());
+/** A hook payload → the action Claros checks, or null (not a shell command or an edit: let it run unchecked). */
+export function actionOf(agent, p, env = process.env) {
+    const cwd = String(p.cwd ?? p.tool_input?.working_directory ?? process.cwd()), root = rootOf(p, cwd, env);
+    const base = { project: basename(root), cwd: cwd === root ? "." : rel(cwd, root) };
+    const t = p.tool_name, i = p.tool_input ?? {};
+    const shell = (command) => ({ tool: "shell", state: { command: cut(command), ...base }, arguments: { command } });
+    const file = (tool, f, more) => ({ tool, state: { file_path: rel(f, root), ...more, project: base.project }, arguments: i });
+    if (agent === "cursor") {
+        if (p.hook_event_name === "beforeShellExecution")
+            return shell(String(p.command ?? ""));
+        if (t === "Shell")
+            return shell(String(i.command ?? ""));
+        // ponytail: Cursor documents no tool_input for Write / Delete; these are the field names its other events use
+        if (t === "Write") {
+            const f = String(i.file_path ?? i.path ?? "");
+            return file("write_file", f, i.edits ? { diff: cut(diffOf(i.edits)) } : { content: cut(i.content ?? i.contents ?? "") });
+        }
+        if (t === "Delete")
+            return file("delete_file", String(i.file_path ?? i.path ?? ""), {});
+        return null;
+    }
+    if (t === "Bash" || t === "PowerShell")
+        return shell(String(i.command ?? ""));
+    if (agent === "codex") {
+        if (t !== "apply_patch")
+            return null;
+        const patch = String(i.command ?? i.patch ?? ""), files = patchFiles(patch);
+        return file("edit_file", files[0] ?? "", { diff: cut(patch), ...(files.length > 1 ? { files: files.map((f) => rel(f, root)).join(", ") } : {}) });
+    }
+    if (t === "Write")
+        return file("write_file", String(i.file_path ?? ""), { content: cut(i.content) });
+    if (t === "Edit")
+        return file("edit_file", String(i.file_path ?? ""), { diff: cut(diffOf([i])) });
+    if (t === "MultiEdit")
+        return file("edit_file", String(i.file_path ?? ""), { diff: cut(diffOf(i.edits ?? [])) });
+    if (t === "NotebookEdit")
+        return file("edit_file", String(i.notebook_path ?? ""), { content: cut(i.new_source) });
+    return null;
+}
+const who = (r) => {
+    const v = (r.violations ?? []).find((x) => x.action === "ask" || x.action === "stop") ?? {};
+    return v.who_to_ask || v.owner || v.expert || "the rule's owner";
+};
+const firstRule = (r) => (r.violations ?? []).find((x) => x.action === "ask" || x.action === "stop")?.rule ?? "a team rule";
+/** A /v1/check answer (or why the check failed) → the agent's hook output. `cursorPre`: Cursor's preToolUse (no ask). */
+export function outputOf(agent, r, err, o = {}) {
+    const what = o.tool ?? "this action";
+    let kind, text = "", short = "";
+    if (err) {
+        if (o.failClosed) {
+            kind = "stop";
+            text = `Claros couldn't check this action (${err}), so it was not run. Ask a person to confirm it is allowed before trying again.`;
+            short = `Claros couldn't check ${what} (${err}); blocked (fail-closed).`;
+        }
+        else {
+            kind = "warn";
+            short = `Claros couldn't check ${what} (${err}); it ran unchecked. Run: npx getclaros doctor`;
+        }
+    }
+    else if (r.allowed) {
+        kind = nudgesOf(r).length ? "nudge" : "silent";
+        text = kind === "nudge" ? nudgeText(r) : "";
+    }
+    else {
+        kind = r.result === "ask" ? "ask" : "stop";
+        text = stopText(r) + (kind === "ask" && r.check_id && !r.question ? `\nCheck: ${r.check_id} (give it to ${who(r)} with the question)` : "");
+        short = kind === "ask" ? `Claros: ask ${who(r)} before ${what}: ${firstRule(r)}${r.check_id ? ` (check ${r.check_id})` : ""}`
+            : `Claros stopped ${what}: ${firstRule(r)}`;
+    }
+    const json = (x) => ({ stdout: JSON.stringify(x), stderr: "", code: 0 });
+    if (agent === "cursor") {
+        const noAsk = o.event === "preToolUse"; // Cursor: ask accepted but not enforced on preToolUse
+        if (kind === "silent")
+            return json({ permission: "allow" });
+        if (kind === "warn")
+            return json({ permission: "allow", user_message: short });
+        if (kind === "nudge")
+            return json({ permission: "allow", agent_message: text });
+        if (kind === "ask" && !noAsk)
+            return json({ permission: "ask", user_message: short, agent_message: text });
+        return json({ permission: "deny", user_message: short, agent_message: text });
+    }
+    const hso = (x) => ({ hookSpecificOutput: { hookEventName: "PreToolUse", ...x } });
+    if (kind === "silent")
+        return { stdout: "", stderr: "", code: 0 };
+    if (kind === "warn")
+        return json({ systemMessage: short });
+    if (kind === "nudge")
+        return json(hso({ additionalContext: text.slice(0, 10_000) }));
+    if (kind === "ask" && agent === "claude-code") { // native ask: the person at the keyboard decides, with the reason
+        return json({ ...hso({ permissionDecision: "ask", permissionDecisionReason: short, additionalContext: text.slice(0, 10_000) }) });
+    }
+    return json({ ...hso({ permissionDecision: "deny", permissionDecisionReason: text }), systemMessage: short });
+}
+/** The key: flag → CLAROS_KEY → saved config → the project's .env. */
+function keyFor(flag, root) {
+    if (flag || process.env.CLAROS_KEY)
+        return (flag || process.env.CLAROS_KEY);
+    const saved = loadConfig().key;
+    if (saved)
+        return saved;
+    try {
+        return /^(?:export\s+)?CLAROS_KEY=["']?([^"'\r\n]*)/m.exec(readFileSync(join(root, ".env"), "utf8"))?.[1].trim() ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+async function check(at, a, actor, timeout) {
+    const go = async () => {
+        const res = await fetch(at.url + "/v1/check", { method: "POST", signal: AbortSignal.timeout(timeout),
+            headers: { "content-type": "application/json", ...(at.key ? { authorization: `Bearer ${at.key}` } : {}) },
+            body: JSON.stringify({ tool: a.tool, action: a.tool, actor, state: a.state, arguments: a.arguments }) });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return res.json();
+    };
+    try {
+        return await go();
+    }
+    catch (e) {
+        if (e.name === "TimeoutError" || !(await relocate(at)))
+            throw e;
+        return go(); // the server moved: the saved address is updated for the next call
+    }
+}
+/** `getclaros hook <agent> [--fail-closed] [--timeout ms] [--url …] [--web …] [--key …]` → exit code. */
+export async function main(argv) {
+    let v, agent;
+    try {
+        const p = parseArgs({ args: argv, allowPositionals: true, options: { "fail-closed": { type: "boolean" },
+                timeout: { type: "string" }, url: { type: "string" }, web: { type: "string" }, key: { type: "string" } } });
+        v = p.values;
+        agent = p.positionals[0];
+        if (!AGENTS.includes(agent))
+            throw new Error(`usage: getclaros hook <${AGENTS.join("|")}> [--fail-closed] [--timeout ms]`);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(0, "utf8"));
+    }
+    catch {
+        payload = null;
+    }
+    const emit = (o) => {
+        if (o.stdout)
+            process.stdout.write(o.stdout + "\n");
+        if (o.stderr)
+            process.stderr.write(o.stderr + "\n");
+        return o.code;
+    };
+    // Cursor also runs Claude Code's hooks (.claude/settings.json); its own hooks.json entry checks those calls
+    if (agent !== "cursor" && payload?.cursor_version)
+        return 0;
+    const a = payload && actionOf(agent, payload);
+    if (!payload)
+        return emit(outputOf(agent, null, "unreadable hook payload", { failClosed: v["fail-closed"] }));
+    if (!a)
+        return emit(outputOf(agent, { allowed: true }, null, { event: payload.hook_event_name }));
+    const o = { failClosed: !!v["fail-closed"], tool: a.tool === "shell" ? `\`${String(a.state.command).slice(0, 80)}\``
+            : `${a.tool} ${a.state.file_path}`, event: payload.hook_event_name };
+    let r = null, err = null;
+    try {
+        const root = rootOf(payload, String(payload.cwd ?? process.cwd()));
+        const at = await resolve({ url: v.url, web: v.web, key: keyFor(v.key, root) });
+        const s = loadConfig();
+        if (at.source === "discovered" && !s.url)
+            saveConfig({ ...s, url: at.url, web: at.web }); // cache discovery
+        if (!at.key)
+            throw new Error("no Claros key: run npx getclaros init");
+        r = await check(at, a, agent, Number(v.timeout ?? 5000));
+        if (r?.need?.length)
+            throw new Error("the check needs records from an app the hook can't read");
+    }
+    catch (e) {
+        err = e.name === "TimeoutError" ? `timed out after ${v.timeout ?? 5000}ms` : e.message;
+    }
+    return emit(outputOf(agent, r, err, o));
+}
+const isOurs = (cmd) => /(getclaros|[\\/]dist[\\/]cli\.js)\s+hook\s/.test(String(cmd ?? "") + " ");
+/** Where each agent keeps its hooks, project and user scope. */
+export function hookFiles(project) {
+    const h = homedir(), codex = process.env.CODEX_HOME || join(h, ".codex");
+    return [
+        { agent: "claude-code", client: "Claude Code", path: join(project, ".claude", "settings.json"), user: false },
+        { agent: "claude-code", client: "Claude Code", path: join(h, ".claude", "settings.json"), user: true },
+        { agent: "codex", client: "Codex", path: join(project, ".codex", "hooks.json"), user: false },
+        { agent: "codex", client: "Codex", path: join(codex, "hooks.json"), user: true },
+        { agent: "cursor", client: "Cursor", path: join(project, ".cursor", "hooks.json"), user: false },
+        { agent: "cursor", client: "Cursor", path: join(h, ".cursor", "hooks.json"), user: true },
+    ].filter((f, i, all) => all.findIndex((x) => x.path === f.path) === i);
+}
+/** Agents installed on this machine (their home directory exists) or configured in this project. */
+export function hookAgents(project) {
+    const h = homedir(), codex = process.env.CODEX_HOME || join(h, ".codex");
+    const dirs = { "claude-code": [join(h, ".claude"), join(project, ".claude")],
+        codex: [codex, join(project, ".codex")], cursor: [join(h, ".cursor"), join(project, ".cursor")] };
+    return AGENTS.filter((a) => dirs[a].some((d) => existsSync(d)));
+}
+/** [event, entry] pairs init adds for an agent. */
+export function entriesFor(agent, command) {
+    if (agent === "claude-code")
+        return [["PreToolUse", { matcher: "Bash|PowerShell|Edit|Write|NotebookEdit",
+                    hooks: [{ type: "command", command, timeout: 30 }] }]];
+    if (agent === "codex")
+        return [["PreToolUse", { matcher: "^Bash$|^apply_patch$",
+                    hooks: [{ type: "command", command, timeout: 30, statusMessage: "Checking with Claros" }] }]];
+    return [["beforeShellExecution", { command, timeout: 30 }], ["preToolUse", { command, matcher: "Write|Delete", timeout: 30 }]];
+}
+const entryOurs = (e) => isOurs(e?.command) || (Array.isArray(e?.hooks) && e.hooks.some((h) => isOurs(h?.command)));
+async function jsonc() {
+    const j = await import("jsonc-parser");
+    const fmt = (text) => {
+        const ind = text.match(/^([ \t]+)\S/m)?.[1] ?? "  ";
+        return { insertSpaces: !ind.startsWith("\t"), tabSize: ind.startsWith("\t") ? 1 : ind.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+    };
+    const set = (t, path, value) => j.applyEdits(t, j.modify(t, path, value, { formattingOptions: fmt(t) }));
+    const items = (t, path) => j.findNodeAtLocation(j.parseTree(t), path)?.children ?? [];
+    const cut = (t, a, b, r = "") => t.slice(0, a) + r + t.slice(b);
+    // by hand, like clients.ts addClaros / removeEntry: jsonc's modify would reformat the neighbouring entries
+    /** value appended to the array at path, or as `key` to the object at path */
+    const put = (t, path, value, key) => {
+        const last = items(t, path).at(-1);
+        if (!last)
+            return set(t, key === undefined ? path : [...path, key], key === undefined ? [value] : value);
+        const at = last.offset + last.length, indent = /^[ \t]*/.exec(t.slice(t.lastIndexOf("\n", last.offset) + 1))[0];
+        return cut(t, at, at, `,${fmt(t).eol}${indent}${key === undefined ? "" : `${JSON.stringify(key)}: `}${JSON.stringify(value)}`);
+    };
+    /** the k-th element (array) or property (object) at path out, with its comma */
+    const drop = (t, path, k) => {
+        const xs = items(t, path), p = xs[k];
+        if (k > 0)
+            return cut(t, xs[k - 1].offset + xs[k - 1].length, p.offset + p.length);
+        if (xs.length > 1)
+            return cut(t, p.offset, xs[1].offset);
+        return set(t, [...path, p.type === "property" ? p.children[0].value : k], undefined);
+    };
+    const read = (t) => {
+        const errors = [], doc = j.parse(t, errors, { allowTrailingComma: true });
+        if (errors.length || (doc !== undefined && (typeof doc !== "object" || Array.isArray(doc))))
+            throw new Error("not valid JSON");
+        return doc ?? {};
+    };
+    return { set, read, put, drop };
+}
+/** The file's text with our hooks in it (added once; a changed launcher is updated in place). Throws on bad JSON. */
+export async function addHooks(text, agent, command) {
+    const { set, read, put } = await jsonc();
+    let t = text.trim() ? text : "{}\n";
+    if (agent === "cursor" && read(t).version === undefined)
+        t = put(t, [], 1, "version");
+    for (const [event, entry] of entriesFor(agent, command)) {
+        const hooks = read(t).hooks, list = hooks?.[event];
+        if (!hooks || typeof hooks !== "object") {
+            t = put(t, [], { [event]: [entry] }, "hooks");
+            continue;
+        }
+        if (!Array.isArray(list)) {
+            t = list === undefined ? put(t, ["hooks"], [entry], event) : set(t, ["hooks", event], [entry]);
+            continue;
+        }
+        const at = list.findIndex(entryOurs);
+        if (at < 0)
+            t = put(t, ["hooks", event], entry);
+        else if (JSON.stringify(list[at]) !== JSON.stringify(entry))
+            t = set(t, ["hooks", event, at], entry);
+    }
+    return t;
+}
+/** The inverse: our entries out; an event list or `hooks` object left empty by that goes too. */
+export async function removeHooks(text) {
+    const { read, drop } = await jsonc();
+    let t = text;
+    for (const [event, list] of Object.entries(read(t).hooks ?? {})) {
+        if (!Array.isArray(list) || !list.some(entryOurs))
+            continue;
+        if (list.every(entryOurs))
+            t = drop(t, ["hooks"], Object.keys(read(t).hooks).indexOf(event));
+        else
+            for (let i = list.length - 1; i >= 0; i--)
+                if (entryOurs(list[i]))
+                    t = drop(t, ["hooks", event], i);
+    }
+    const doc = read(t);
+    if (doc.hooks && typeof doc.hooks === "object" && !Object.keys(doc.hooks).length && text !== t) {
+        t = drop(t, [], Object.keys(doc).indexOf("hooks"));
+    }
+    return t;
+}
+/** Does this file hold our hooks? (false when absent or unreadable) */
+export async function hasHooks(path) {
+    if (!existsSync(path))
+        return false;
+    try {
+        const { read } = await jsonc();
+        return Object.values(read(readFileSync(path, "utf8")).hooks ?? {}).some((l) => Array.isArray(l) && l.some(entryOurs));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/setup.js

@@ -6,11 +6,12 @@
 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, 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";
@@ -19,6 +20,7 @@ const tilde = (p) => p.startsWith(homedir()) ? "~" + p.slice(homedir().length) :
 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] [--no-browser-hooks]
+                [--no-hooks] [--user] [--fail-closed]   (coding-agent hooks: project scope, --user for all projects)
        ${NAME} test   [--app <server>]
        ${NAME} doctor [--project <dir>]   (status: the same)
        ${NAME} undo   [--all]
@@ -33,6 +35,7 @@ export async function run(argv) {
                 project: { type: "string" }, all: { type: "boolean" }, "no-mcp": { type: "boolean" }, app: { 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) {
@@ -292,8 +295,8 @@ 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), browsers = detectBrowser(project);
-    if (!files.length && !browsers.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: 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;
@@ -310,8 +313,9 @@ async function init(v, project) {
         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 { changed, guardedIn, added } = mcp;
+    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`);
@@ -323,6 +327,8 @@ async function init(v, project) {
         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)
@@ -458,6 +464,42 @@ async function mcpSetup(v, files, url, key, run) {
     }
     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")"`;
@@ -744,6 +786,21 @@ async function doctor(v, project) {
     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);
@@ -775,6 +832,18 @@ async function doctor(v, project) {
     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;
@@ -815,6 +884,8 @@ async function undo(v, project) {
                 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)`);
         }
@@ -828,6 +899,8 @@ async function undo(v, project) {
             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) {
@@ -842,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/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.2.0",
-  "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": {