getclaros 0.1.1 → 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`.
@@ -15,8 +16,13 @@ npx getclaros init
 To try a local build, run `node dist/cli.js init` with `GETCLAROS_LAUNCHER="node /abs/path/to/dist/cli.js"` so the
 configs launch your build instead of `npx -y getclaros`.
 
+One command for every kind of agent: it guards the MCP servers your agent clients run, and, when run in a Playwright
+or browser-use project, installs the browser hook with that project's own package manager (see
+[Browser agents](#browser-agents-playwright-browser-use)). `npx getclaros doctor` then says, per agent type, whether it
+is guarded and can reach Claros.
+
 ```
-  claros”  getclaros 0.1.1
+  claros”  getclaros 0.3.0
 
   Sign in  opening your browser
   › https://claros-eta.vercel.app/device?code=ZQRC-ZCTP
@@ -25,7 +31,7 @@ configs launch your build instead of `npx -y getclaros`.
   ✓ Signed in to workspace "Acme"  key clr_7f3a91c2_…
     <claros server> · key saved in ~/.config/getclaros/config.json, readable only by you
 
-  MCP servers
+  MCP agents
 
   Claude Code  ~/.claude.json
      1 ● erpnext                     npx -y frappe-mcp-server  Work Map "Process a supplier invoice"
@@ -81,9 +87,70 @@ 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>`):
+
+| Found | Install (never global) | Hook |
+|---|---|---|
+| `@playwright/test` in package.json | `pnpm add -D` / `yarn add -D` / `bun add -d` / `npm install -D getclaros-browser`, by lockfile | writes `claros.fixture.ts` next to `playwright.config.*`; you change each spec's `from "@playwright/test"` to `from "<rel>/claros.fixture"` (init prints the exact line) |
+| `playwright` (the library) in package.json | the same, as a dependency | printed: `import { guard } from "getclaros-browser"; await guard(page);` |
+| `browser-use` in pyproject.toml / requirements*.txt / uv.lock / poetry.lock | `uv add` / `poetry add claros-browser`, else `pip install` into the project's virtualenv (none: printed, not run) | printed: `from claros_browser import guard_tools; guard_tools(tools)`, with the file that builds the `Agent` |
+
+Each project gets its plan (the exact install command, the file it writes, where the key goes, the hook) and one
+question, `Set up Playwright? Enter = yes`. `--yes` says yes without asking; `--no-browser-hooks` shows the plan and
+changes nothing. User source files are never edited: the hook is printed.
+
+Why a fixture file for Playwright Test: Playwright has no config-level page hook, and a fixture is its supported way to
+run code for every test's `page`. The file lives in your repo (you can read it, compose it with your own fixtures), it
+imports `getclaros-browser` and `@playwright/test` from your own `node_modules` (works with pnpm's strict layout), and
+it re-exports everything from `@playwright/test`, so swapping the import never loses a type or helper. It also reads
+`CLAROS_*` from `.env` when the shell doesn't set them, because Playwright doesn't read `.env` itself.
+
+The browser hooks read `CLAROS_KEY` (and `CLAROS_URL` / `CLAROS_WEB_URL` when you aren't on the hosted Claros) from the
+environment. `init` writes them to the project's `.env` only when it already exists, git ignores it and git doesn't
+track it (no repo: the `.gitignore` next to it decides). Otherwise it prints an export line that reads the saved key
+without showing it: `export CLAROS_KEY="$(node -p "require('$HOME/.config/getclaros/config.json').key")"`.
+browser-use loads `.env` itself.
+
+The fixture file is new (undo deletes it, unless you changed it) and `.env` is backed up like any config (undo restores
+it, or, if you edited it since, removes only the `CLAROS_*` lines). Undo doesn't uninstall the package.
+
 ```
-npx getclaros test     # a made-up record that breaks one of your rules → prints the stop (rule, expert's words, who to ask)
-npx getclaros status   # which servers are guarded, Claros reachable, key valid
+npx getclaros test     # made-up records checked against your rules → prints the stop (and, in the demo, a nudge with its fix)
+npx getclaros doctor   # per agent type: guarded? reachable? (server, key, MCP wrapping, browser package + hook + key), with the fix
+npx getclaros status   # the same as doctor
 npx getclaros undo     # undo the last init; --all: every init, plus any guard wrapping it finds
 npx getclaros export <workflow_id> [--format agents|design|skill] > AGENTS.md   # a map's rules as markdown
 ```
@@ -99,7 +166,30 @@ rules page. Exit codes: 0 sent, 1 no such check / not valid, 2 bad usage, 3 unre
 
 `test` asks Claros for a record that breaks a precise rule of a Work Map for one of your guarded servers
 (`GET /v1/check/example?app=…`), checks it with `POST /v1/check` and prints the stop. Nothing is sent to the app.
-With no guarded server matching a map it uses the workspace's newest map and ends with a `Demo:` note.
+
+With no guarded server matching a map it runs a demo on two Starter maps (added to your workspace the first time, as
+drafts that are never enforced; delete them on the web and they stay deleted): a production deploy during a release
+freeze, which is stopped, and a coding agent's stylesheet with a raw hex colour, which the judge nudges with a fix.
+Both are checked side by side and it ends with a `Demo:` note:
+
+```
+  ◉ Stopped · ✎ Nudged  2 checks in 827 ms
+
+    ◉ stop  No production deploys during the release freeze.
+            “Nothing goes to prod during the freeze. Not even a typo fix.” — Release manager
+            Who to ask: Release manager
+            Test action: deploy deploy.environment = production, deploy.freeze_active = true
+
+    ✎ nudge No hand-picked hex values in UI code; use the design tokens (var(--primary) and the rest).
+            “If it's not a token, it's a bug. No hand-picked hex values.” — Design systems lead
+            → Replace #7C3AED and #FFFFFF with design tokens like var(--primary)
+            Test action: write_file file_path = src/components/Button.css, content = .button { background: #7C3AED; color: #FFFFFF; border-radius: 6px; }
+
+  Your agent gets a stop as the tool's error; a nudge lets the call through, with the fix. Nothing reached any app.
+  Demo: no server is guarded yet, so this used the Starter maps (examples, not enforced; delete them on the web).
+```
+
+For a guarded server whose app has a Work Map:
 
 ```
   ◉ Stopped in 1.3 s  Work Map "Process a supplier invoice" · check chk_0b14cb5eef

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,7 +405,11 @@ async function main(argv) {
     }
     if (argv[0] === "mcp")
         return void import("./bridge.js").then((m) => m.bridge());
-    if (["init", "test", "status", "undo", "export", "override"].includes(argv[0])) {
+    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));