@scopebond/hook 0.9.0 → 0.10.0

package/README.md

@@ -216,6 +216,35 @@ locally and retried if the workspace is unreachable. `npx @scopebond/hook flush`
 delivers anything still queued — run it on a session-end hook (and set
 `SCOPEBOND_HOOK_FLUSH_MS=0`) if you want zero per-call latency.
 
+### Rules set by your workspace
+
+A connected computer keeps its own rules (`.scopebond/rules.json`) until someone who manages
+the workspace changes a rule for it there. From then on the workspace decides, rule by rule,
+whether a matching action is **blocked** or only **recorded**, and can add entries to this
+computer's lists (protected branches, programs, allowed sites). The workspace never sends
+patterns: the hook compiles its choices with the same compiler as `rules apply`.
+
+- **When it applies.** At most once every five minutes, a tool call also checks for changes,
+  alongside sending its activity record and capped at about one and a half seconds
+  (`SCOPEBOND_POLICY_SYNC_MS`); every other call only reads two small files. A change therefore
+  applies within a few minutes of the agent's next action, and a workspace that is slow or
+  unreachable never holds up the agent for longer than the cap. The new rules govern from the
+  next action. `npx @scopebond/hook policy sync` checks right now.
+- **What is checked.** A rules document must be complete, issued for this computer, match its
+  digest and be newer than the one in force; the resulting policy must load. Anything else is
+  refused, the rules already in force stay, and the refusal is reported to the workspace.
+- **What is confirmed.** After loading, the hook tells the workspace exactly which version it
+  loaded, so the workspace shows *Applied* only for computers that confirmed it.
+- **What the workspace cannot change.** Protection of Scopebond's own settings and of the
+  agents' hook settings, the machine key policy, fail-closed handling of anything unreadable,
+  and this computer's own opt-ins (`allowed_roots`, `protect_remote_database`).
+- **Going back.** While the workspace sets the rules, `rules` edits and `policy load` are
+  refused here. If the connection is revoked, or the workspace stops setting rules for this
+  computer, the hook recompiles `policy.json` from `rules.json`: a computer is never left
+  without rules. `status` shows which rules are in force and when they were last checked.
+
+Set `SCOPEBOND_POLICY_SYNC=off` to stop the five-minute check (the rules in force stay).
+
 ### Session, health and action observations (opt-in)
 
 Beyond receipts, the hook can send a second kind of signed record, an *observation*,

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAwpBA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgqBA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}

package/dist/cli.js

@@ -35,13 +35,15 @@ import { mapClaudeToolUse, mapCodexToolUse, mapCursorEvent, fillPushBranch } fro
 import { createHookRuntime } from "./runtime.js";
 import { useDigestKey, loadOrCreateDigestKey } from "./minimize.js";
 import { scaffold, harnessSnippet, placeHook } from "./init.js";
-import { userHome, userHarnessFile, resolveConfigDir, writeHarnessConfig, removeHarnessConfig, cursorDetected, codexDetected, absoluteHookCommand, isHarnessConfigured, purgeHome, harnessScopes, harnessScopeLabel, configuredHookCommands, hookCommandResolves, projectHarnessFile, localHarnessFile, gitShareState, isMachineSpecificCommand, trustProjectPolicy, untrustedProjectPolicy, wireLifecycleHooks, unwireLifecycleHooks, } from "./install.js";
+import { userHome, userHarnessFile, resolveConfigDir, writeHarnessConfig, removeHarnessConfig, cursorDetected, codexDetected, absoluteHookCommand, isHarnessConfigured, purgeHome, harnessScopes, harnessScopeLabel, configuredHookCommands, hookCommandResolves, projectHarnessFile, localHarnessFile, gitShareState, isMachineSpecificCommand, trustProjectPolicy, untrustedProjectPolicy, isTrustedProject, wireLifecycleHooks, unwireLifecycleHooks, } from "./install.js";
 import { openObservations, describeObservations, observationStatus, stopReasonFromClaude, exitFromClaudeFailure, HEARTBEAT_INTERVAL_MS, OBSERVATIONS_SCOPE, } from "./obs-emitter.js";
 import { OBSERVATION_DB, ObservationStore } from "./obs-store.js";
 import { loadOrCreateBindingKey } from "./observation.js";
 import { uploadPending } from "./obs-upload.js";
 import { connectCloud, loadConnection } from "./cloud.js";
-import { loadPolicyExport } from "./policy-load.js";
+import { loadPolicyExport, policyBuilds } from "./policy-load.js";
+import { isManaged, readMeta, MANAGED_DOC_FILE } from "./managed.js";
+import { syncIfDue, syncPolicy } from "./policy-sync.js";
 import { loadBudgetExport } from "./budget-load.js";
 import { compile, defaultRules, describeRules, loadRules, saveRules, rulesPath, pathRuleFor } from "./rules.js";
 import { createSigner } from "@scopebond/sdk";
@@ -215,7 +217,8 @@ async function runPreToolUse(mapper, deny = denyClaude, raw, harness = "claude")
         useDigestKey(loadOrCreateDigestKey(dir));
         const decision = await runtime.evaluate([...fillPushBranch(mapper(input), currentBranch(cwd)), ...databaseGuard(dir, cwd, input)], { groupKey: callId(input) });
         const observer = recordObservations(dir, cwd, input, decision, harness);
-        await Promise.all([runtime.flush(), observer?.flush() ?? Promise.resolve()]);
+        // Workspace rules: at most every five minutes, a capped check alongside the record delivery. It never fails the call.
+        await Promise.all([runtime.flush(), observer?.flush() ?? Promise.resolve(), syncIfDue(dir, () => syncOptionsFor(dir))]);
         observer?.close();
         // Close before deciding: the receipt is already committed, and leaving the handle
         // open is what made the write-ahead log grow without bound.
@@ -326,7 +329,7 @@ async function runCursor() {
         const mapped = fillPushBranch(mapCursorEvent(event, input), currentBranch(cwd));
         const decision = await runtime.evaluate(mapped, { groupKey: callId(input) });
         const observer = recordObservations(dir, cwd, input, decision, "cursor");
-        await Promise.all([runtime.flush(), observer?.flush() ?? Promise.resolve()]);
+        await Promise.all([runtime.flush(), observer?.flush() ?? Promise.resolve(), syncIfDue(dir, () => syncOptionsFor(dir))]);
         observer?.close();
         // An `afterFileEdit` violation is real and recorded, but the edit has already
         // landed. Say so rather than letting "blocked" imply it was stopped.
@@ -677,6 +680,11 @@ function runRules(args) {
             printHelp("rules", true);
             process.exit(1);
     }
+    if (isManaged(dir)) {
+        console.error("The rules on this computer are set by your Scopebond workspace, so they cannot be changed here.");
+        console.error("Change them in the workspace (Rules), or disconnect this computer to manage its rules locally again.");
+        process.exit(1);
+    }
     // Changing what governs the agent is the same class of action as `init`.
     requireInteractive("rules", args);
     const policyPath = join(dir, "policy.json");
@@ -970,12 +978,21 @@ async function runFlush() {
  *  `--yes`, make it the active policy here; then acknowledge it (or its refusal) to the workspace. */
 async function runPolicy(args) {
     const [sub, file] = args;
+    if (sub === "sync") {
+        await runPolicySync(args.includes("--background"));
+        return;
+    }
     if (sub !== "load" || !file) {
-        console.error(`usage: ${cliCommand("policy load <export.json> [--yes]")}`);
+        console.error(`usage: ${cliCommand("policy sync")} | ${cliCommand("policy load <export.json> [--yes]")}`);
         process.exitCode = 2;
         return;
     }
     const dir = resolveConfigDir(process.cwd());
+    if (isManaged(dir)) {
+        console.error("The rules on this computer are set by your Scopebond workspace; a policy file cannot replace them here.");
+        process.exitCode = 1;
+        return;
+    }
     const apply = args.includes("--yes");
     const connection = loadConnection(dir);
     const outcome = loadPolicyExport(dir, file, { apply, environmentId: connection?.environment_id });
@@ -1002,6 +1019,41 @@ async function runPolicy(args) {
         return;
     await sendPolicyAck(dir, ack);
 }
+/** What a rules check needs for this config directory. A project policy governs only once trusted, so it is re-pinned after a
+ *  write, exactly when `rules apply` would. */
+function syncOptionsFor(dir) {
+    const home = userHome();
+    const repin = dir !== home && existsSync(join(home, "policy.json")) && isTrustedProject(dir);
+    const agentKid = createSigner({ privateKeyPem: readFileSync(join(dir, "agent.key"), "utf8") }).kid;
+    return { agentKid, hookVersion: hookVersion(), policyBuilds, afterPolicyWrite: repin ? (d) => { trustProjectPolicy(d); } : undefined };
+}
+/** `policy sync`: bring this computer's rules in line with its workspace now (the hook also checks every five minutes). */
+async function runPolicySync(background) {
+    const dir = resolveConfigDir(process.cwd());
+    let outcome;
+    try {
+        outcome = await syncPolicy(dir, syncOptionsFor(dir));
+    }
+    catch (error) {
+        outcome = { state: "unavailable", message: error.message };
+    }
+    if (background)
+        return;
+    const lines = {
+        not_connected: "This computer is not connected to a Scopebond workspace; it uses its own rules.",
+        own_rules: "Your workspace does not set rules for this computer; it uses its own rules.",
+        unchanged: "Up to date with your workspace.",
+        applied: "Updated to your workspace's latest rules.",
+        refused: "Could not apply your workspace's rules; the rules already in force stay.",
+        disconnected: "The workspace connection is no longer valid; this computer now uses its own rules.",
+        unavailable: "Could not reach your workspace; the rules already in force stay.",
+    };
+    console.log(lines[outcome.state]);
+    if (outcome.state === "refused" || outcome.state === "unavailable") {
+        console.log(`  ${outcome.message}`);
+        process.exitCode = 1;
+    }
+}
 /** Queue a `policy_ack` (loaded or rejected) through the observation outbox and try to deliver it now. */
 async function sendPolicyAck(dir, ack) {
     const observed = openObservations(dir, { adapterVersion: hookVersion(), spawnHeartbeat: false });
@@ -1299,6 +1351,16 @@ function runStatus() {
     console.log(`  Cursor           ${harnessScopeLabel(cursor) || (cursorDetected() ? "detected, not configured" : "not detected")}`);
     console.log(`  Codex            ${codex.project || codex.user ? `${harnessScopeLabel(codex)} — approve once with /hooks` : codexDetected() ? "detected, not configured" : "not detected"}`);
     console.log(`  cloud workspace  ${connected ? "connected" : "not connected (local only)"}`);
+    {
+        const activeDir = resolveConfigDir(process.cwd());
+        const meta = readMeta(activeDir);
+        const managed = existsSync(join(activeDir, MANAGED_DOC_FILE));
+        const checked = meta.checked_at ? `, last checked ${meta.checked_at}` : "";
+        console.log(`  rules            ${managed ? `set by your workspace (version ${meta.revision})${checked}` : `this computer's own (${rulesPath(activeDir)})${connected ? checked : ""}`}`);
+        console.log(`                   always on: protection of Scopebond's own settings and the agents' hook settings`);
+        if (meta.last_error)
+            console.log(`                   last problem: ${meta.last_error}`);
+    }
     const observationLines = describeObservations(resolveConfigDir(process.cwd()));
     console.log(`  observations     ${observationLines[0]}`);
     for (const line of observationLines.slice(1))