@openscaffold/cli 0.1.4 → 0.1.5

package/README.md

@@ -7,6 +7,7 @@ start, in any repo, loads the right customer deployment's briefing, and the Open
 ```sh
 npx @openscaffold/cli setup acme.com ./customer-docs   # sign in if needed, create the deployment, upload the folder, print the cited plan
 npx @openscaffold/cli login    # opens your browser: click Approve. That's it.
+npx @openscaffold/cli review --req req_1             # review this folder's change against the customer's plan (agents run it)
 npx @openscaffold/cli status   # what's set up and the next step (--json for coding agents)
 npx @openscaffold/cli logout   # removes everything it installed and revokes the login
 npx @openscaffold/cli help     # commands and environment variables
@@ -26,6 +27,11 @@ MCP server and `/openscaffold:*` commands).
 - `~/.config/openscaffold/credentials.json` (your login, mode 0600)
 - the `openscaffold` MCP server in Claude Code (user scope)
 - a SessionStart hook in `~/.claude/settings.json` that prints the briefing
+- two guardrail hooks in the same file: before a `git commit`, the customer's rules and must-haves as context; at Stop,
+  once per session, if Claude edited files without a review, it's asked to run `openscaffold review` (or `request_review`) and then
+  call `report_session`; and after Claude switches or creates a customer (`use_deployment`, `create_deployment`), a hook that makes `review` and the guardrails follow it
+
+Logged in before 2026-10-29? Run `npx @openscaffold/cli login` again to add the customer-switch hook (`status` says so).
 - `/os-requirements`, `/os-what-changed`, `/os-check-plan`, `/os-demo-check` in `~/.claude/skills/`
 
 Requires Node 22+ and Claude Code. Set `OPENSCAFFOLD_URL` to point at a self-hosted OpenScaffold. Set

package/dist/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 // `npx @openscaffold/cli setup | login | status | session-start | logout` (SPEC §8.4). Node 22+, standard library only.
 import { execFileSync, spawn } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { briefingStatus, browserCommand, gitInfo, hasOpenScaffoldPlugin, hookBase, HOSTED, installedHooks, loadedEntry, loginResultLine, MCP_NAME, mcpText, nameFromDomain, parseSetupArgs, planSummary, pluginServes, preCommitOutput, selectFiles, SETUP_EXTENSIONS, setupPrompt, setupResultLine, skillFile, statusReport, stopOutput, transcriptActivity, windowsCommandLine, withHooks, withoutHooks, withSession, } from "./install.js";
+import { briefingFacts, briefingStatus, browserCommand, collectDiff, gitInfo, hasOpenScaffoldPlugin, hookBase, HOSTED, installedHooks, loadedEntry, loginResultLine, MCP_NAME, mcpText, nameFromDomain, callerSession, commandLine, gitTracks, rememberedCache, DEFAULT_REVIEW_TITLE, parseReviewArgs, parseSetupArgs, planSummary, pluginServes, preCommitOutput, REVIEW_HELP, REVIEW_WAIT, reviewTitle, selectFiles, SETUP_EXTENSIONS, setupPrompt, setupResultLine, skillFile, statusReport, stopOutput, switchAllowed, switchedTo, transcriptActivity, whichCustomerError, windowsCommandLine, withHooks, withoutHooks, } from "./install.js";
 const CONFIG = join(homedir(), ".config", "openscaffold");
 const CREDENTIALS = join(CONFIG, "credentials.json");
 const CACHE = join(CONFIG, "cache");
@@ -113,8 +113,8 @@ async function login({ next = true } = {}) {
         throw new Error(`Couldn't reach OpenScaffold at ${url} (${start.status}).`);
     const { code, login_url, poll } = start.body;
     console.log(BY_AGENT
-        ? `Tell the person: open ${login_url} and click Approve. The page shows the code ${code}. Signing up, if they need to, happens on that page too.`
-        : `Opening ${login_url}\nClick Approve in your browser. The page should show the code ${code}.`);
+        ? `Tell the person: open ${login_url}, check the workspace on the page, then click Approve. The page shows the code ${code}. Signing up, if they need to, happens on that page too.`
+        : `Opening ${login_url}\nCheck the workspace on the page, then click Approve. The page should show the code ${code}.`);
     openBrowser(login_url);
     let creds = null;
     const deadline = Date.now() + 10 * 60_000;
@@ -282,6 +282,7 @@ async function setup() {
     console.log("\nReading the sources, then writing the plan (usually 2–4 minutes).");
     const deadline = Date.now() + 20 * 60_000;
     let last = "";
+    const shown = new Set(); // facts already printed, so each prints once as it's found
     let idle = 0;
     let nudged = false;
     for (;;) {
@@ -296,6 +297,13 @@ async function setup() {
         }
         if (status && status !== last)
             console.log(`  ${(last = status)}`);
+        const facts = briefing ? briefingFacts(briefing).filter((f) => !shown.has(f)) : [];
+        if (facts.length && !shown.size)
+            console.log("  Found so far, quoted from their sources:");
+        for (const f of facts) {
+            console.log(`    ${f}`);
+            shown.add(f);
+        }
         idle = status?.startsWith("No plan yet") ? idle + 1 : 0;
         if (idle >= 2) {
             if (nudged)
@@ -328,6 +336,17 @@ const git = (cwd, args) => {
         return null;
     }
 };
+/** Caches a deployment's briefing as this folder's (and this Claude session's) deployment, for the guardrail hooks and review. */
+function remember(creds, deployment, briefing, cwd, sessionId, switching = false) {
+    mkdirSync(CACHE, { recursive: true });
+    writeFileSync(join(CACHE, `${deployment}.md`), briefing);
+    const entry = { deployment, at: new Date().toISOString(), login: loginKey(creds) };
+    // Per Claude session too: two sessions in one folder on different customers each keep their own guardrails.
+    const next = rememberedCache(readJson(join(CACHE, "index.json"), {}), readJson(SESSIONS, {}), cwd, sessionId, entry, switching);
+    writeJson(join(CACHE, "index.json"), next.index);
+    if (sessionId)
+        writeJson(SESSIONS, next.sessions);
+}
 /** Prints the briefing. Never breaks a session: on any problem, a cached briefing or one line, exit 0. */
 async function sessionStart() {
     let hook = {};
@@ -349,15 +368,8 @@ async function sessionStart() {
         const briefing = String(r.body.briefing);
         console.log(briefing);
         const dep = r.body.deployment?.id;
-        if (dep) {
-            mkdirSync(CACHE, { recursive: true });
-            writeFileSync(join(CACHE, `${dep}.md`), briefing);
-            const entry = { deployment: dep, at: new Date().toISOString(), login: loginKey(creds) };
-            writeJson(join(CACHE, "index.json"), { ...index, [cwd]: entry });
-            // Per Claude session too: two sessions in one folder on different customers each keep their own guardrails.
-            if (hook.session_id)
-                writeJson(SESSIONS, withSession(readJson(SESSIONS, {}), hook.session_id, entry));
-        }
+        if (dep)
+            remember(creds, dep, briefing, cwd, hook.session_id);
     }
     catch {
         const last = index[cwd]?.login === loginKey(creds) ? index[cwd] : undefined; // a session started before a re-login may write late
@@ -388,14 +400,14 @@ async function preCommit() {
     if (out)
         console.log(out);
 }
-/** Stop: once per session, if it edited files and never called report_session, ask the agent to report. */
+/** Stop: once per session, if it edited files and never called request_review (or report_session), ask for it. */
 async function stop() {
     const hook = await hookInput();
     if (!hook.session_id || hook.stop_hook_active)
         return;
     const marker = join(CACHE, `reminded-${hook.session_id.replace(/[^\w-]/g, "")}`);
     const transcript = hook.transcript_path?.replace(/^~(?=[\\/])/, homedir());
-    const activity = transcript && existsSync(transcript) ? transcriptActivity(readFileSync(transcript, "utf8")) : { edited: false, reported: false };
+    const activity = transcript && existsSync(transcript) ? transcriptActivity(readFileSync(transcript, "utf8")) : { edited: false, reported: false, reviewed: false };
     const out = stopOutput({ stopHookActive: false, reminded: existsSync(marker), loaded: Boolean(loadedHere(hook.session_id, hook.cwd ?? process.cwd())), ...activity });
     if (!out)
         return;
@@ -403,6 +415,74 @@ async function stop() {
     writeFileSync(marker, new Date().toISOString());
     console.log(out);
 }
+/** The deployments this login has cached (session-start or an earlier switch), newest first, with their names when cached. */
+const knownDeployments = (creds) => {
+    const entries = [...Object.values(readJson(SESSIONS, {})), ...Object.values(readJson(join(CACHE, "index.json"), {}))];
+    const ids = [...new Set(entries.filter((e) => e.login === loginKey(creds)).sort((a, b) => b.at.localeCompare(a.at)).map((e) => e.deployment))];
+    return ids.map((id) => {
+        const file = join(CACHE, `${id}.md`);
+        return { id, name: existsSync(file) ? /^# OpenScaffold — (.+)$/m.exec(readFileSync(file, "utf8"))?.[1]?.trim() ?? null : null };
+    });
+};
+/**
+ * PostToolUse after use_deployment / create_deployment: the new deployment becomes this session's and folder's, so review
+ * and the hooks follow it; only when it is this login's server and workspace (switchAllowed), never a foreign id.
+ */
+async function useDeployment() {
+    const hook = await hookInput();
+    const creds = credentials();
+    const got = switchedTo(hook.tool_response);
+    if (!creds || !got || !switchAllowed(hook.tool_name, got.deployment, creds.api_url, knownDeployments(creds).map((d) => d.id)))
+        return;
+    remember(creds, got.deployment, got.briefing, hook.cwd ?? process.cwd(), hook.session_id, true);
+}
+// --- review -------------------------------------------------------------------------------------
+/**
+ * `review [--req ids] [--title "…"] [--deployment dep_…] [files…]`: the coding agent's one command for a review. It
+ * collects the change itself (git, or the listed files where git sees none), calls request_review, waits on
+ * get_review (which holds up to 50 s per call) and prints the verdict. Nothing to paste, nothing to poll.
+ */
+async function review() {
+    const args = parseReviewArgs(process.argv.slice(3), (p) => existsSync(p) || gitTracks(p, (a) => execFileSync("git", a, { stdio: "ignore" })));
+    if ("help" in args)
+        return console.log(REVIEW_HELP);
+    if ("error" in args)
+        throw new Error(args.error);
+    const creds = credentials();
+    const again = process.argv.slice(2);
+    if (!creds)
+        throw new Error(`Not signed in here. Run ${commandLine(["login"])} (one click in the browser), then ${commandLine(again)}. With the plugin or OAuth only, send the diff with the request_review tool instead.`);
+    // The calling Claude session's deployment first (another session in this folder may have switched), else the folder's.
+    const deployment = args.deployment ?? loadedHere(callerSession(process.env), process.cwd())?.deployment;
+    if (!deployment)
+        throw new Error(whichCustomerError(again, knownDeployments(creds)));
+    const git = (a) => execFileSync("git", a, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+    const got = collectDiff(args.files, git, (f) => (lstatSync(f).isSymbolicLink() ? { link: readlinkSync(f) } : readFileSync(f, "utf8")));
+    if ("error" in got)
+        throw new Error(got.error);
+    const cached = join(CACHE, `${deployment}.md`);
+    const briefing = existsSync(cached) ? readFileSync(cached, "utf8") : null;
+    const name = briefing && /^# OpenScaffold — (.+)$/m.exec(briefing)?.[1]?.trim();
+    const title = args.title === DEFAULT_REVIEW_TITLE ? reviewTitle(args.reqs, briefing) : args.title;
+    // No --deployment and no Claude session id in this shell: the folder's default, said out loud.
+    const which = !args.deployment && !callerSession(process.env) ? " (this folder's default customer; pass --deployment to choose)" : "";
+    console.log(`Reviewing "${title}" for ${name ? `${name} (${deployment})` : deployment}${which}. ${REVIEW_WAIT}`);
+    try {
+        const queued = JSON.parse(await tool(creds, "request_review", { deployment_id: deployment, title, requirement_ids: args.reqs, diff: got.diff }, 60_000));
+        if (!queued.review_id)
+            return console.log(queued.note ?? "Nothing to review.");
+        let out = "";
+        // Each get_review waits up to 50 s on the server; a review that outlasts four of them is reported as still running.
+        for (let i = 0; i < 4 && (!out || out.includes("Still reviewing")); i++)
+            out = await tool(creds, "get_review", { deployment_id: deployment, review_id: queued.review_id }, 90_000);
+        console.log(out);
+    }
+    catch (e) {
+        if (e instanceof LoggedOut)
+            throw new Error(`${e.message} Run \`npx -y @openscaffold/cli@latest login\`, then review again.`);
+        throw e;
+    }
+}
 // --- status -------------------------------------------------------------------------------------
 /** Read-only: what's set up on this machine and the next step. `--json` for agents. Always exits 0. */
 async function status() {
@@ -431,7 +511,7 @@ async function status() {
         server,
         mcp,
         hook: hooks.includes("session-start"),
-        guardrails: hooks.includes("pre-commit") && hooks.includes("stop"),
+        guardrails: hooks.includes("pre-commit") && hooks.includes("stop") && hooks.includes("use-deployment"),
         skills: names.filter((n) => onDisk.includes(n)).length,
         skillsExpected: names.length,
         plugin: mcp === null ? false : pluginInstalled() && pluginServes(creds?.api_url),
@@ -464,10 +544,13 @@ Usage: npx @openscaffold/cli@latest <command>
                    Everything in one go: sign in if needed, create the customer's deployment, upload
                    every .vtt .srt .txt .md .csv .json in the folder (default .), wait for the plan, print it
   login            Sign in (one browser click on Approve) and connect Claude Code
+  review [--req req_1,req_2] [--title "…"] [--deployment dep_…] [files…]
+                   Review this folder's change against the customer's plan and rules: sends the git diff
+                   (or the listed files, where git sees no change) and prints the verdict. review --help for more
   status [--json]  What's set up on this machine, and the next step
   logout           Remove everything login added and revoke this machine's login
   help             This text
-  (session-start, pre-commit and stop are run by Claude Code's hooks)
+  (session-start, pre-commit, stop and use-deployment are run by Claude Code's hooks)
 
 Environment:
   OPENSCAFFOLD_URL         Server to sign in to (default ${DEFAULT_URL}; e.g. http://localhost:3000)
@@ -475,7 +558,7 @@ Environment:
                            (SSH and headless Linux are detected and skip the browser by themselves)`;
 const [cmd] = process.argv.slice(2);
 /** Run by a hook: must never break the session or block a tool, so any problem exits 0 quietly. */
-const HOOKS = new Set(["session-start", "pre-commit", "stop"]);
+const HOOKS = new Set(["session-start", "pre-commit", "stop", "use-deployment"]);
 if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     console.log(HELP);
     process.exit(0);
@@ -489,7 +572,7 @@ if (Number(process.versions.node.split(".")[0]) < 22) {
         console.log(msg);
     process.exit(HOOKS.has(cmd ?? "") ? 0 : 1);
 }
-const commands = { setup, login: () => login(), status, "session-start": sessionStart, "pre-commit": preCommit, stop, logout };
+const commands = { setup, login: () => login(), review, status, "session-start": sessionStart, "pre-commit": preCommit, stop, "use-deployment": useDeployment, logout };
 const run = commands[cmd ?? ""];
 if (!run) {
     console.error(HELP);

package/dist/install.js

@@ -2,19 +2,21 @@
 // Formats checked against code.claude.com docs (hooks, mcp, skills), 2026-10-23.
 export const MCP_NAME = "openscaffold";
 /** Our hook commands mention openscaffold and end in one of our subcommands (npx form or a local build path). */
-const isOurCommand = (cmd) => /openscaffold/.test(cmd) && /\b(session-start|pre-commit|stop)"?$/.test(cmd.trim());
+const isOurCommand = (cmd) => /openscaffold/.test(cmd) && /\b(session-start|pre-commit|stop|use-deployment)"?$/.test(cmd.trim());
 const HOOK_MATCHER = "startup|resume|clear|compact";
 const isOurs = (h) => typeof h.command === "string" && isOurCommand(h.command);
 /**
  * The hooks login installs (Claude Code docs, hooks, 2026-10-27): the briefing at session start; before a
  * `git commit` (the handler's `if` is one permission rule, `Bash(git commit *)` also matches a bare `git commit`),
- * the deployment's constraints and must-haves as context; at Stop, a one-time report_session reminder.
+ * the deployment's constraints and must-haves as context; at Stop, a one-time ask to review the changes (request_review) and report_session;
+ * after the agent's use_deployment or create_deployment, the local cache follows the switch (so review, pre-commit and Stop use the new customer).
  * Timeouts are seconds. None ever blocks a tool call.
  */
 export const OUR_HOOKS = [
     { event: "SessionStart", sub: "session-start", matcher: HOOK_MATCHER, handler: { timeout: 10 } },
     { event: "PreToolUse", sub: "pre-commit", matcher: "Bash", handler: { if: "Bash(git commit *)", timeout: 2 } },
     { event: "Stop", sub: "stop", matcher: undefined, handler: { timeout: 5 } },
+    { event: "PostToolUse", sub: "use-deployment", matcher: "mcp__.*openscaffold.*__(use|create)_deployment", handler: { timeout: 2 } },
 ];
 const withoutOurs = (groups = []) => groups.map((g) => ({ ...g, hooks: g.hooks.filter((h) => !isOurs(h)) })).filter((g) => g.hooks.length > 0);
 /** Adds (or replaces) our hooks, `<base> <subcommand>` each; leaves everything else in settings.json as it was. */
@@ -94,7 +96,7 @@ export function statusReport(s) {
         `Signed in:    ${s.workspace ? `yes, workspace "${s.workspace}" (${s.apiUrl}${s.server === "down" ? ", not answering" : s.server === "revoked" ? ", login revoked" : ""})` : "no"}`,
         `MCP server:   ${s.plugin ? "from the openscaffold plugin" : s.mcp === null ? "unknown (Claude Code not on PATH)" : s.mcp ? "added" : "missing"}`,
         `Session hook: ${s.hook ? "installed" : "missing"}`,
-        ...(s.guardrails === undefined ? [] : [`Guardrails:   ${s.guardrails ? "pre-commit plan check and end-of-session report reminder" : "missing"}`]),
+        ...(s.guardrails === undefined ? [] : [`Guardrails:   ${s.guardrails ? "pre-commit plan check and end-of-session report reminder" : "missing or out of date (logins before 2026-10-29 lack the customer-switch hook): re-run npx @openscaffold/cli login"}`]),
         `Commands:     ${s.plugin ? "/openscaffold:* from the plugin" : commandsOk ? `${s.skills} /os-* commands` : s.skills ? `${s.skills} of ${s.skillsExpected || "?"} /os-* commands` : "missing"}`,
     ];
     const next = !s.workspace || s.server === "revoked" || mcpOk === false || !s.hook || s.guardrails === false || !commandsOk
@@ -163,11 +165,53 @@ export function deploymentForCwd(index, cwd) {
         dir = up;
     }
 }
+/** A tool's output as text: a string, MCP content blocks, or `{content}` / `{text}` objects (transcripts, hook input). */
+const textOf = (r) => typeof r === "string" ? r : Array.isArray(r) ? r.map(textOf).join("\n") : r && typeof r === "object" ? textOf(r.text ?? r.content) : "";
+/**
+ * A use_deployment or create_deployment result (PostToolUse `tool_response`) → the deployment it switched to and a briefing
+ * to cache: use_deployment's own, or for create_deployment (JSON `{deployment: {id, name}}`, no briefing yet) just its name line.
+ */
+export function switchedTo(response) {
+    const briefing = textOf(response);
+    const deployment = /^Deployment id: (dep_\w+)/m.exec(briefing)?.[1];
+    if (deployment)
+        return { deployment, briefing };
+    try {
+        const created = JSON.parse(briefing).deployment;
+        if (typeof created?.id === "string" && /^dep_\w+$/.test(created.id))
+            return { deployment: created.id, briefing: `# OpenScaffold — ${String(created.name ?? created.id)}\n` };
+    }
+    catch { }
+    return null;
+}
+/**
+ * Whether a switch seen by the use-deployment hook may replace the CLI's cache. The user-scope server (`mcp__openscaffold__…`)
+ * is the one login added with this CLI's token: same server and workspace. The plugin's server is the hosted app signed in
+ * by its own OAuth, maybe another workspace: only a deployment this login already cached (`known`) on the hosted app. Else no.
+ */
+export function switchAllowed(toolName, deployment, apiUrl, known) {
+    if (toolName?.startsWith(`mcp__${MCP_NAME}__`))
+        return true;
+    return Boolean(toolName?.startsWith("mcp__plugin_")) && pluginServes(apiUrl) && new Set(known).has(deployment);
+}
+/** The Claude Code session a CLI command runs in, when Claude Code says (env), so `review` follows that session's deployment. */
+export const callerSession = (env) => env.CLAUDE_SESSION_ID || env.CLAUDE_CODE_SESSION_ID || undefined;
 /** session-start's per-Claude-session record (cache sessions.json): this session's entry added, only the newest `keep` kept. */
 export function withSession(sessions, sessionId, entry, keep = 200) {
     const all = Object.entries({ ...sessions, [sessionId]: entry }).sort(([, a], [, b]) => b.at.localeCompare(a.at));
     return Object.fromEntries(all.slice(0, keep));
 }
+/**
+ * The cache after loading a deployment: the Claude session's own entry, and the folder's default. A mid-session switch
+ * with a known session moves only that session's entry, so another session in the folder (or a `review` that can't tell
+ * which session called it) never picks it up; a session start, or a switch with no session, sets the folder default. Pure.
+ */
+export function rememberedCache(index, sessions, cwd, sessionId, entry, switching = false) {
+    return {
+        index: switching && sessionId ? index : { ...index, [cwd]: entry },
+        sessions: sessionId ? withSession(sessions, sessionId, entry) : sessions,
+    };
+}
 /** The deployment a hook's session loaded: by its Claude session_id first (two sessions can share a folder), else the folder's. */
 export const loadedEntry = (sessions, index, sessionId, cwd) => (sessionId ? sessions[sessionId] : undefined) ?? deploymentForCwd(index, cwd);
 /** A briefing section's list lines (§8.3), citations dropped: `- On-prem only` from `- On-prem only [Ticket · doc_… “…”]`. */
@@ -209,12 +253,23 @@ export function preCommitOutput(briefing, plugin) {
 const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
 /** Our report_session tool, from the user-scope server or the plugin's (`mcp__plugin_openscaffold_openscaffold__…`). */
 const REPORT = /^mcp__.*openscaffold.*__report_session$/;
-/** From a session transcript (JSONL): did the agent edit files, and did it call report_session? */
+/** The calls whose output can be a review: our get_review (user-scope or plugin), or the CLI's `review` through Bash. */
+const GET_REVIEW = /^mcp__.*openscaffold.*__get_review$/;
+const CLI_REVIEW = /(@openscaffold\/cli(@\S+)?|\bopenscaffold)\s+review\b/;
+/** A finished review's verdict line (get_review's Markdown, which the CLI prints). Running and failed reviews have none. */
+const VERDICT = "\nVerdict: ";
+/**
+ * From a session transcript (JSONL): did the agent edit files, get a finished review back, call report_session? A review
+ * counts only as the tool_result of a get_review or Bash `… review` call (matched by tool_use_id) holding a verdict, so a
+ * failed or still-running review, or reading a file that contains one, doesn't.
+ */
 export function transcriptActivity(jsonl) {
     let edited = false;
     let reported = false;
+    let reviewed = false;
+    const reviewCalls = new Set();
     for (const line of jsonl.split("\n")) {
-        if (!line.includes('"tool_use"'))
+        if (!line.includes('"tool_use"') && !(line.includes('"tool_result"') && line.includes("Verdict: ")))
             continue;
         let content;
         try {
@@ -226,25 +281,35 @@ export function transcriptActivity(jsonl) {
         if (!Array.isArray(content))
             continue;
         for (const c of content) {
+            if (c?.type === "tool_result" && c.tool_use_id && reviewCalls.has(c.tool_use_id) && textOf(c.content).includes(VERDICT))
+                reviewed = true;
             if (c?.type !== "tool_use" || typeof c.name !== "string")
                 continue;
             if (EDIT_TOOLS.has(c.name))
                 edited = true;
             if (REPORT.test(c.name))
                 reported = true;
+            if (c.id && (GET_REVIEW.test(c.name) || (c.name === "Bash" && typeof c.input?.command === "string" && CLI_REVIEW.test(c.input.command))))
+                reviewCalls.add(c.id);
         }
     }
-    return { edited, reported };
+    return { edited, reported, reviewed };
 }
 export const STOP_REASON = "Before you finish, call report_session with what you did.";
+export const STOP_REVIEW_REASON = "Before you finish, review your changes against the customer's plan: run `npx -y @openscaffold/cli@latest review --req req_1,req_2` with the requirement ids you worked on (it sends the diff and prints the verdict; usually 30–90 s, up to ~7 min; don't wrap it in `timeout`), then report_session.";
 /**
- * The Stop hook's stdout: the documented block decision, once per session, when this session loaded a deployment,
- * edited files and hasn't reported; else "". Never while Claude is already continuing for a stop hook.
+ * The Stop hook's stdout: the documented block decision, once per session, when this session loaded a deployment and
+ * edited files: first ask for a review (§8.4) if no review result came back, else for report_session if it never
+ * reported; else "". Never twice, and never while Claude is already continuing for a stop hook.
  */
 export function stopOutput(s) {
-    if (s.stopHookActive || s.reminded || !s.loaded || !s.edited || s.reported)
+    if (s.stopHookActive || s.reminded || !s.loaded || !s.edited)
         return "";
-    return JSON.stringify({ decision: "block", reason: STOP_REASON });
+    if (!s.reviewed)
+        return JSON.stringify({ decision: "block", reason: STOP_REVIEW_REASON });
+    if (!s.reported)
+        return JSON.stringify({ decision: "block", reason: STOP_REASON });
+    return "";
 }
 // --- setup: one command from a folder of customer files to a cited plan (SPEC §8.4) -------------
 /** What `setup` uploads: the upload panel's file types (§6.1). CSV/JSON become one ticket per row. */
@@ -318,6 +383,10 @@ export function briefingStatus(briefing) {
     // Written for an agent: drop the sentences that tell it which tool to call next.
     return line.split(/(?<=[.;])\s+/).filter((x) => !/`|tell the FDE/i.test(x)).join(" ").replace(/;$/, ".");
 }
+/** The verified facts a pre-plan briefing's Status lists ("- Goal: … [title · doc_… “quote”]"), without the document ids. */
+export function briefingFacts(briefing) {
+    return section(briefing, "Status").filter((l) => l.startsWith("- ")).map((l) => l.replace(/ · doc_\w+/, ""));
+}
 /**
  * One MCP `tools/call` response body (JSON, or a streamable-HTTP SSE frame) → the tool's text, or its error. The first
  * content block only: a second one may carry the "Since your briefing" freshness line.
@@ -336,3 +405,147 @@ export function mcpText(raw) {
     const text = msg.result?.content?.[0]?.text ?? "";
     return msg.result?.isError ? { error: text || "OpenScaffold refused the call." } : { text };
 }
+// --- review: send this folder's change to OpenScaffold's reviewer (SPEC §8.1 request_review) ------
+/** request_review's limit (web/lib/pipeline/review.ts MAX_DIFF_BYTES). */
+export const MAX_DIFF_BYTES = 400 * 1024;
+const REVIEW_CMD = "npx -y @openscaffold/cli@latest review";
+const REVIEW_USAGE = `Usage: ${REVIEW_CMD} [--req req_1,req_2] [--title "…"] [--deployment dep_…] [files…], e.g. ${REVIEW_CMD} --req req_1`;
+export const REVIEW_WAIT = "Usually 30–90 s, up to ~7 min; don't wrap it in `timeout`.";
+export const REVIEW_HELP = [
+    REVIEW_USAGE,
+    "",
+    "Reviews this folder's change against the customer's plan and rules: sends the git diff (or the listed files, where git",
+    "sees no change) and prints the verdict.",
+    "  --req ids          The plan's requirement ids this change works on (from the briefing or get_plan)",
+    '  --title "…"        One line: what the change does (default: those requirements\' titles); a bare phrase works too',
+    "  --deployment id    The customer (default: the one this folder's session loaded)",
+    "  files…             Narrow the change to these paths; outside git, the files to send whole",
+    REVIEW_WAIT,
+].join("\n");
+/** The title when none is given and the cached briefing names none of the claimed requirements. */
+export const DEFAULT_REVIEW_TITLE = "Review of current changes";
+/**
+ * `review` arguments; files are optional (git finds the change) and needed only where git sees none. A bare argument
+ * that isn't a file (`exists`) is the title, so `review "Fix X"` works. With no title, DEFAULT_REVIEW_TITLE (see reviewTitle).
+ */
+export function parseReviewArgs(args, exists = () => true) {
+    const out = { title: "", reqs: [], deployment: undefined, files: [] };
+    for (let i = 0; i < args.length; i++) {
+        const eq = args[i].startsWith("--") ? args[i].indexOf("=") : -1;
+        const [flag, inline] = eq < 0 ? [args[i], undefined] : [args[i].slice(0, eq), args[i].slice(eq + 1)];
+        const value = () => inline ?? args[++i];
+        if (flag === "--help" || flag === "-h")
+            return { help: true };
+        if (flag === "--title")
+            out.title = value() ?? "";
+        else if (flag === "--req" || flag === "--requirements")
+            out.reqs.push(...(value() ?? "").split(/[,\s]+/).filter(Boolean));
+        else if (flag === "--deployment")
+            out.deployment = value();
+        else if (/^-./.test(args[i]))
+            return { error: `Unknown option ${flag}. ${REVIEW_USAGE}` };
+        else if (/^req_\w+$/.test(args[i]) && !exists(args[i]))
+            out.reqs.push(args[i]); // `--req req_1 req_2`
+        // `exists` also knows paths git tracks (a deleted file), so a listed deletion is a file, not the title.
+        else if (!out.title && !exists(args[i]))
+            out.title = args[i];
+        else
+            out.files.push(args[i]);
+    }
+    return { ...out, title: out.title.trim() || DEFAULT_REVIEW_TITLE, reqs: [...new Set(out.reqs)] };
+}
+/**
+ * A CLI command line to copy and run: `npx -y @openscaffold/cli@latest <args>`, each argument single-quoted when a shell
+ * would split or expand it ($, backticks, spaces), so the copy keeps the exact text: PowerShell's form on Windows.
+ */
+export const commandLine = (args, platform = process.platform) => ["npx -y @openscaffold/cli@latest", ...args.map((a) => /^[\w./:@=,-]+$/.test(a) ? a
+        // PowerShell: single quotes are literal and a quote is doubled; elsewhere POSIX's '\'' escape.
+        : platform === "win32" ? `'${a.replace(/'/g, "''")}'` : `'${a.replace(/'/g, `'\\''`)}'`)].join(" ");
+/**
+ * Whether git tracks a path given relative to the current folder: in the index, or in HEAD (a staged deletion).
+ * `HEAD:./p` resolves against the current folder, not the repository root. `git` runs git and throws on failure.
+ */
+export function gitTracks(path, git) {
+    return [["ls-files", "--error-unmatch", "--", path], ["cat-file", "-e", `HEAD:./${path.replace(/^\.\//, "")}`]].some((a) => {
+        try {
+            git(a);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** `review` with no --deployment and none cached for this session or folder: the same command with each cached customer's id. */
+export function whichCustomerError(args, known) {
+    const head = "Which customer? This session has no OpenScaffold deployment cached here.";
+    if (!known.length)
+        return `${head} Add the id from the OpenScaffold briefing ("Deployment id: …", or call list_deployments), e.g. ${commandLine([...args, "--deployment", "dep_01EXAMPLE"])}`;
+    return [`${head} Run one of:`, ...known.map((d) => `  ${commandLine([...args, "--deployment", d.id])}${d.name ? `   # ${d.name}` : ""}`)].join("\n");
+}
+/** The default title: the claimed requirements' titles from the cached briefing's must-haves (`- req_1 Title — status`). */
+export function reviewTitle(reqs, briefing) {
+    const line = (id) => briefing?.split("\n").find((l) => l.startsWith(`- ${id} `));
+    const titles = reqs.map((id) => line(id)?.slice(id.length + 3).replace(/^\[[^\]]*\] /, "").replace(/ — \S+$/, "")).filter(Boolean);
+    return titles.length ? titles.join("; ").slice(0, 300) : DEFAULT_REVIEW_TITLE;
+}
+/**
+ * A whole file as an added-file diff, as `git diff --no-index /dev/null <file>` prints it. Empty or binary: "". A
+ * symbolic link is a link (mode 120000, its target path as the content), as git records it.
+ */
+export function newFileDiff(path, file) {
+    const link = typeof file === "object";
+    const text = link ? file.link : file;
+    if (!text || text.includes("\0"))
+        return "";
+    const lines = link ? [text] : text.replace(/\r\n/g, "\n").split("\n");
+    const newline = !link && lines.at(-1) === "";
+    if (newline)
+        lines.pop();
+    return [`diff --git a/${path} b/${path}`, `new file mode ${link ? "120000" : "100644"}`, "--- /dev/null", `+++ b/${path}`, `@@ -0,0 +1,${lines.length} @@`,
+        ...lines.map((l) => `+${l}`), ...(newline ? [] : ["\"]), ""].join("\n");
+}
+/**
+ * The change to review, from where the agent works: in a git repo, everything since HEAD (staged, unstaged, and
+ * untracked files as new files), narrowed to `files` when given. Where git sees nothing (not a repo, a git-ignored
+ * folder, a repo with no commit), the listed files are sent whole as new files. `git` runs one git command in the
+ * folder and throws when git fails; `read` reads a file.
+ */
+export function collectDiff(files, git, read) {
+    let diff = "";
+    let repo = false;
+    try {
+        repo = git(["rev-parse", "--is-inside-work-tree"]).trim() === "true";
+    }
+    catch { }
+    if (repo) {
+        const only = files.length ? ["--", ...files] : [];
+        let head = true;
+        try {
+            git(["rev-parse", "--verify", "-q", "HEAD"]);
+        }
+        catch {
+            head = false;
+        }
+        // No commit yet: compare with the empty tree, so staged and unstaged files both show.
+        const base = head ? "HEAD" : git(["hash-object", "-t", "tree", "/dev/null"]).trim();
+        // --no-ext-diff / --no-textconv: a repo's configured diff drivers and converters are commands; we never run them.
+        diff = git(["diff", "--no-color", "--no-ext-diff", "--no-textconv", base, ...only]);
+        const untracked = git(["ls-files", "--others", "--exclude-standard", "-z", ...only]).split("\0").filter(Boolean);
+        // Files the agent named that git ignores still get reviewed, even when other files changed.
+        if (files.length)
+            untracked.push(...git(["ls-files", "--others", "--ignored", "--exclude-standard", "-z", ...only]).split("\0").filter(Boolean));
+        const prefix = git(["rev-parse", "--show-prefix"]).trim();
+        diff += untracked.map((f) => newFileDiff(prefix + f, read(f))).join(""); // ls-files paths are from this folder; diff paths from the root
+    }
+    if (!diff.trim() && files.length)
+        diff = files.map((f) => newFileDiff(f.replace(/^\.\//, ""), read(f))).join("");
+    if (!diff.trim()) {
+        return { error: repo
+                ? `Nothing to review: git sees no change here. If your files are in a git-ignored folder, list them: ${REVIEW_USAGE}`
+                : `This folder isn't a git repo, so list the files you changed (each is sent whole as a new file), e.g. ${REVIEW_CMD} --req req_1 src/report.py. Or send \`git diff --no-index /dev/null <file>\` for each file with the request_review tool.` };
+    }
+    if (Buffer.byteLength(diff) > MAX_DIFF_BYTES)
+        return { error: `This change is ${Math.ceil(Buffer.byteLength(diff) / 1024)} KB; a review takes up to 400 KB. Review it in parts: list the files for one work item at a time.` };
+    return { diff };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openscaffold/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Connect Claude Code to your OpenScaffold workspace: each session loads the right customer deployment.",
   "type": "module",
   "bin": {