@openscaffold/cli 0.1.4 → 0.1.6

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 { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { briefingFacts, briefingStatus, browserCommand, collectDiff, gitInfo, hasOpenScaffoldPlugin, hookBase, HOSTED, installedHooks, loadedEntry, loginResultLine, MCP_NAME, mcpText, nameFromDomain, cacheFromToolCall, callerSession, commandLine, editedPaths, filesModifiedSince, insideFolder, sessionFileChoice, sessionStartedAt, gitTracks, rememberedCache, DEFAULT_REVIEW_TITLE, parseReviewArgs, parseSetupArgs, planSummary, pluginServes, preCommitOutput, REVIEW_HELP, REVIEW_WAIT, reviewTitle, selectFiles, SETUP_EXTENSIONS, setupPrompt, setupResultLine, skillFile, statusReport, stopOutput, 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,19 @@ 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, transcript) {
+    mkdirSync(CACHE, { recursive: true });
+    // No briefing (a plain tool call named the deployment): keep the cached one, if any; review works without it.
+    if (briefing !== null)
+        writeFileSync(join(CACHE, `${deployment}.md`), briefing);
+    const entry = { deployment, at: new Date().toISOString(), login: loginKey(creds), ...(transcript ? { transcript } : {}) };
+    // 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 +370,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, false, hook.transcript_path);
     }
     catch {
         const last = index[cwd]?.login === loginKey(creds) ? index[cwd] : undefined; // a session started before a re-login may write late
@@ -388,14 +402,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 +417,125 @@ 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 any OpenScaffold tool: use_deployment / create_deployment switch this session (and, with no session, the
+ * folder); any other call naming a deployment_id makes it this session's, so `review` finds the customer the agent loaded
+ * with get_briefing. Only this login's server and workspace, never a foreign id (cacheFromToolCall). Local files only.
+ */
+async function useDeployment() {
+    const hook = await hookInput();
+    const creds = credentials();
+    if (!creds)
+        return;
+    const current = hook.session_id ? readJson(SESSIONS, {})[hook.session_id]?.deployment : undefined;
+    const got = cacheFromToolCall(hook, creds.api_url, knownDeployments(creds).map((d) => d.id), current);
+    if (got)
+        remember(creds, got.deployment, got.briefing, hook.cwd ?? process.cwd(), hook.session_id, true, hook.transcript_path);
+}
+/** The Claude session's transcript: the path its hooks cached, else ~/.claude/projects/<any>/<session id>.jsonl. */
+const transcriptOf = (sessionId, entry) => {
+    if (entry?.transcript && existsSync(entry.transcript))
+        return entry.transcript;
+    const projects = join(CLAUDE, "projects");
+    const dir = existsSync(projects) ? readdirSync(projects).find((d) => existsSync(join(projects, d, `${sessionId}.jsonl`))) : undefined;
+    return dir ? join(projects, dir, `${sessionId}.jsonl`) : undefined;
+};
+/** Outside git with no files named: what this Claude session changed under the cwd, from its transcript, else by mtime. */
+function sessionFiles(sessionId, cwd) {
+    if (!sessionId)
+        return null;
+    const entry = readJson(SESSIONS, {})[sessionId];
+    const transcript = transcriptOf(sessionId, entry);
+    const text = transcript ? readFileSync(transcript, "utf8") : null;
+    const edited = text === null ? null : editedPaths(text).map((p) => relative(cwd, resolve(cwd, p))).filter((p) => p && !p.startsWith("..") && !isAbsolute(p));
+    const since = sessionStartedAt(text, transcript ? statSync(transcript).birthtimeMs : null, entry?.started);
+    // Automatic picks only: links resolved, each must still be inside this folder (a path the agent names is sent as named).
+    return sessionFileChoice(edited && insideFolder(edited, cwd), since, (at) => insideFolder(filesModifiedSince(cwd, at), cwd));
+}
+/** OpenScaffold's own record of this Claude session's deployment (the session-start endpoint), cached for next time. */
+async function serverSession(creds, sessionId, cwd) {
+    try {
+        // peek: learn the deployment without marking the briefing read; an existing row for this session is reused, never duplicated.
+        const r = await api(creds.api_url, "/api/sessions/start", { claude_session_id: sessionId, cwd, peek: true, ...gitInfo(git(cwd, ["remote", "get-url", "origin"]), git(cwd, ["branch", "--show-current"])) }, { token: creds.token, timeoutMs: 5000 });
+        const dep = r.status === 200 ? r.body.deployment?.id : undefined;
+        if (dep)
+            remember(creds, dep, String(r.body.briefing), cwd, sessionId, true);
+        return dep;
+    }
+    catch {
+        return undefined;
+    }
+}
+// --- 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.
+    // Nothing cached (the agent loaded the customer some other way, or no hooks): ask OpenScaffold which deployment this session used.
+    const sid = callerSession(process.env);
+    const deployment = args.deployment ?? loadedHere(sid, process.cwd())?.deployment ?? (sid ? await serverSession(creds, sid, process.cwd()) : undefined);
+    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"] });
+    let repo = false;
+    try {
+        repo = git(["rev-parse", "--is-inside-work-tree"]).trim() === "true";
+    }
+    catch { }
+    if (!repo && !args.files.length) {
+        const found = sessionFiles(sid, process.cwd());
+        if (found?.files.length) {
+            args.files.push(...found.files);
+            console.log(`Not a git repo: reviewing the ${found.files.length} file${found.files.length === 1 ? "" : "s"} ${found.from}: ${found.files.join(", ")}`);
+        }
+    }
+    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 ${commandLine(["login"])}, then ${commandLine(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 +564,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 +597,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 +611,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 +625,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

@@ -1,20 +1,24 @@
 // Pure helpers for what `openscaffold login`/`logout` write into Claude Code (SPEC §8.4).
 // Formats checked against code.claude.com docs (hooks, mcp, skills), 2026-10-23.
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 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.*__.*", 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. */
@@ -74,8 +78,11 @@ export function gitInfo(remoteOut, branchOut) {
     const branch = branchOut?.trim() || undefined;
     return { git_remote: remote, git_branch: branch };
 }
-/** Which of our hooks are in settings.json, e.g. ["session-start", "pre-commit", "stop"]. */
-export const installedHooks = (settings) => OUR_HOOKS.filter((h) => (settings.hooks?.[h.event] ?? []).some((g) => g.hooks.some((x) => isOurs(x) && x.command.trim().replace(/"$/, "").endsWith(h.sub)))).map((h) => h.sub);
+/**
+ * Which of our hooks are in settings.json, e.g. ["session-start", "pre-commit", "stop"]: each with today's matcher, so an
+ * older login's (the use-deployment hook's narrow `(use|create)_deployment` matcher) reads as missing and status asks for login.
+ */
+export const installedHooks = (settings) => OUR_HOOKS.filter((h) => (settings.hooks?.[h.event] ?? []).some((g) => g.matcher === h.matcher && g.hooks.some((x) => isOurs(x) && x.command.trim().replace(/"$/, "").endsWith(h.sub)))).map((h) => h.sub);
 export const hasSessionHook = (settings) => installedHooks(settings).includes("session-start");
 /** The hosted app, which the Claude Code plugin's MCP server always points at (plugin/.mcp.json). */
 export const HOSTED = "https://app.openscaffold.ai";
@@ -94,7 +101,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 (an older login's 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 +170,204 @@ 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) {
+    const prev = sessionId ? sessions[sessionId] : undefined;
+    return {
+        index: switching && sessionId ? index : { ...index, [cwd]: { deployment: entry.deployment, at: entry.at, login: entry.login } },
+        sessions: sessionId ? withSession(sessions, sessionId, { ...entry, started: prev?.started ?? entry.at, transcript: entry.transcript ?? prev?.transcript }) : sessions,
+    };
+}
+/**
+ * What the use-deployment hook (PostToolUse on every OpenScaffold tool) caches, or null. use_deployment / create_deployment:
+ * the deployment it switched to, with its briefing. Any other call with a `deployment_id` (get_briefing, get_plan, …): that
+ * deployment, for the calling session only (`sessionOnly`; no session id, nothing), no briefing. Unchanged (`current`) or
+ * not this login's server and workspace (switchAllowed): null.
+ */
+export function cacheFromToolCall(call, apiUrl, known, current) {
+    const tool = /^mcp__.*openscaffold.*__(\w+)$/.exec(call.tool_name ?? "")?.[1];
+    if (!tool || toolFailed(call.tool_response))
+        return null; // an error ("No active deployment…") keeps the current cache
+    let got = null;
+    if (tool === "use_deployment" || tool === "create_deployment") {
+        const s = switchedTo(call.tool_response);
+        got = s && { ...s, sessionOnly: false };
+    }
+    else {
+        const id = call.tool_input?.deployment_id;
+        if (typeof id === "string" && /^dep_\w+$/.test(id) && call.session_id && id !== current)
+            got = { deployment: id, briefing: null, sessionOnly: true };
+    }
+    return got && switchAllowed(call.tool_name, got.deployment, apiUrl, known) ? got : null;
+}
+/** A tool_response that reports an error: MCP `isError`, an `{error}` object, or text that starts "Error" / "MCP error". */
+const toolFailed = (r) => (Boolean(r) && typeof r === "object" && !Array.isArray(r) && (r.isError === true || "error" in r))
+    || /^(MCP )?error\b/i.test(textOf(r).trim());
+/**
+ * A file automatic selection never sends (a path the agent names still goes): every dot-file (.env, .npmrc, .netrc, …)
+ * and names that look like keys or credentials. ponytail: name patterns, not content scanning; extend the list as found.
+ */
+export const looksSecret = (path) => {
+    const name = path.split(/[\\/]/).pop() ?? path;
+    return name.startsWith(".") || /\.(pem|key|p12|pfx|jks|keystore|asc|gpg|ppk)$|\.env$|\.env\.|^id_(rsa|dsa|ecdsa|ed25519)|credential|secret/i.test(name);
+};
+/**
+ * Outside git with no files named: the session's edited files (transcript) when any are usable, else files modified since
+ * `since` (sessionStart); likely secrets dropped either way. `edited`: null with no transcript.
+ */
+export function sessionFileChoice(edited, since, modifiedSince) {
+    const safe = (fs) => fs.filter((f) => !looksSecret(f));
+    const fromTranscript = safe(edited ?? []);
+    if (fromTranscript.length)
+        return { files: fromTranscript, from: "edited in this session" };
+    return { files: safe(modifiedSince(since.at)), from: `modified ${since.label}` };
+}
+/** The mtime fallback's window when nothing says when the session started. */
+export const UNKNOWN_START_WINDOW_MS = 12 * 3_600_000;
+/**
+ * When the Claude session started, independent of our cache: the earliest `"timestamp"` in its transcript, else the
+ * transcript file's birthtime, else the cache's `started` (first cache write: late when hooks are missing), else the
+ * last 12 hours.
+ */
+export function sessionStartedAt(transcript, birthtimeMs, cachedStarted, now = Date.now()) {
+    let first = Infinity;
+    for (const m of (transcript ?? "").matchAll(/"timestamp":"([^"]+)"/g)) {
+        const t = Date.parse(m[1]);
+        if (t < first)
+            first = t;
+    }
+    const iso = (t) => new Date(t).toISOString();
+    if (Number.isFinite(first))
+        return { at: first, label: `since this session started (${iso(first)})` };
+    if (birthtimeMs && birthtimeMs > 0)
+        return { at: birthtimeMs, label: `since this session started (${iso(birthtimeMs)})` };
+    // Our cache's `started` is only when we first cached a deployment (after a server recovery, moments ago), never the
+    // session's start: it can widen the window, never narrow it below the last 12 hours.
+    const cached = cachedStarted ? Date.parse(cachedStarted) : NaN;
+    const window = now - UNKNOWN_START_WINDOW_MS;
+    if (Number.isFinite(cached) && cached < window)
+        return { at: cached, label: `since ${cachedStarted}` };
+    return { at: window, label: "in the last 12 hours (session start unknown)" };
+}
+/**
+ * Automatic selection only: the paths (relative to `cwd`) whose real location, links resolved, is still inside the real
+ * `cwd`, so `linked/config.json` through a link to another folder is never sent. Missing or unreadable paths drop out.
+ */
+export function insideFolder(paths, cwd) {
+    let root;
+    try {
+        root = realpathSync(cwd);
+    }
+    catch {
+        return [];
+    }
+    return paths.filter((p) => {
+        try {
+            const r = relative(root, realpathSync(resolve(cwd, p)));
+            return Boolean(r) && r !== ".." && !r.startsWith(`..${sep}`) && !isAbsolute(r);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The files a session's transcript (JSONL) shows it wrote or edited, in order, each once: file_path / notebook_path. */
+export function editedPaths(jsonl) {
+    const out = new Set();
+    for (const line of jsonl.split("\n")) {
+        if (!line.includes('"tool_use"'))
+            continue;
+        let content;
+        try {
+            content = JSON.parse(line).message?.content;
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(content))
+            continue;
+        for (const c of content) {
+            const path = c?.input?.file_path ?? c?.input?.notebook_path;
+            if (c?.type === "tool_use" && EDIT_TOOLS.has(c.name ?? "") && typeof path === "string")
+                out.add(path);
+        }
+    }
+    return [...out];
+}
+/**
+ * Files under `root` modified after `since` (ms), paths relative to it, sorted: the change outside git when no transcript
+ * says what was edited. Skips node_modules, dot-folders (.git, .venv, …) and likely secrets (looksSecret); at most `cap` files.
+ */
+export function filesModifiedSince(root, since, cap = 200) {
+    const out = [];
+    const walk = (dir, rel) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (out.length >= cap)
+                return;
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (e.name !== "node_modules" && !e.name.startsWith("."))
+                    walk(join(dir, e.name), r);
+            }
+            else if (e.isFile() && !looksSecret(e.name)) {
+                try {
+                    if (statSync(join(dir, e.name)).mtimeMs > since)
+                        out.push(r);
+                }
+                catch { }
+            }
+        }
+    };
+    walk(root, "");
+    return out;
+}
 /** 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 +409,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 +437,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 +539,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 +561,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 @openscaffold/cli <args>` (no `@latest`: the version already on this machine), 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 @openscaffold/cli", ...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.6",
   "description": "Connect Claude Code to your OpenScaffold workspace: each session loads the right customer deployment.",
   "type": "module",
   "bin": {