@scopebond/hook 0.15.1 → 0.16.0

package/README.md

@@ -266,6 +266,15 @@ patterns: the hook compiles its choices with the same compiler as `rules apply`.
 - **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`).
+- **Overrides.** The workspace can set a rule to *Block, user may override* and say who may
+  override. A matching action is then blocked until the person at the computer allows it once,
+  with a reason, in the Scopebond Agent's window (`@scopebond/agent`): the hook asks the running
+  agent and waits up to 45 seconds (20 seconds for Codex and Cursor), then blocks. The receipt
+  records the override, the reason's digest and the rule; the workspace adds who and why. Where the
+  workspace allows it and the window is not available, Claude Code's own prompt is offered instead,
+  but only in a permission mode where Claude Code really asks; that prompt takes no reason and is
+  recorded as *offered*. Scopebond's own protection, rules set to Block and the kill switch are
+  never overridable, and the workspace's daily limit holds.
 - **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

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAoqBA,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":";AA+rBA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}

package/dist/cli.js

@@ -35,6 +35,7 @@ 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 { onboardingSteps } from "./onboarding.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";
@@ -44,6 +45,7 @@ import { connectCloud, ingestUrl, loadConnection } from "./cloud.js";
 import { recoverEarlierReceipts } from "./recover.js";
 import { loadPolicyExport, policyBuilds } from "./policy-load.js";
 import { isManaged, readMeta, MANAGED_DOC_FILE } from "./managed.js";
+import { createOverrideHandler, overrideHint } from "./override.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";
@@ -128,6 +130,17 @@ function readStdin() {
         return "";
     }
 }
+/** How long a hook waits for a person in the Scopebond window: well inside each agent's hook timeout (Claude Code 60 s by
+ *  default; the Codex entry Scopebond writes says 30 s), so the wait ends as a block, never as a timed-out hook. */
+const OVERRIDE_WAIT_MS = { claude: 45_000, codex: 20_000, cursor: 20_000 };
+/** Warn mode: Claude Code shows the person its own prompt for this action (only where the workspace allows it and Claude Code
+ *  really asks; see override.ts). */
+function askClaude(reason) {
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask", permissionDecisionReason: reason },
+    }) + "\n");
+    process.exit(0);
+}
 function denyClaude(reason) {
     process.stdout.write(JSON.stringify({
         hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason },
@@ -217,7 +230,11 @@ async function runPreToolUse(mapper, deny = denyClaude, raw, harness = "claude")
     try {
         const cwd = input?.cwd ? String(input.cwd) : process.cwd();
         const dir = resolveConfigDir(cwd);
-        runtime = createHookRuntime(runtimePaths(dir, cwd));
+        const permissionMode = typeof input.permission_mode === "string" ? input.permission_mode : null;
+        runtime = createHookRuntime({ ...runtimePaths(dir, cwd), override: (agentKid) => {
+                const made = createOverrideHandler({ dir, home: userHome(), agentKid, harness, permissionMode, waitMs: OVERRIDE_WAIT_MS[harness] });
+                return made ? { handler: made.handler, hint: () => overrideHint(made.note()) } : null;
+            } });
         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);
@@ -230,6 +247,12 @@ async function runPreToolUse(mapper, deny = denyClaude, raw, harness = "claude")
         runtime = undefined;
         if (decision.decision === "deny")
             deny(decision.reason);
+        // Only Claude Code is ever offered "ask" (override.ts); any other harness treats it as a denial.
+        if (decision.decision === "ask") {
+            if (harness === "claude")
+                askClaude(decision.reason);
+            deny(decision.reason);
+        }
         // Stay silent on allow/not_evaluated so the coding agent's normal permission
         // flow remains in charge. Scopebond blocks; it never silently approves.
         process.exit(0);
@@ -328,9 +351,15 @@ async function runCursor() {
     try {
         const cwd = input?.cwd ? String(input.cwd) : process.cwd();
         const dir = resolveConfigDir(cwd);
-        runtime = createHookRuntime(runtimePaths(dir, cwd));
-        useDigestKey(loadOrCreateDigestKey(dir));
+        const permissionMode = typeof input.permission_mode === "string" ? input.permission_mode : null;
         const mapped = fillPushBranch(mapCursorEvent(event, input), currentBranch(cwd));
+        // An edit Cursor reports after saving it cannot be overridden: it already happened.
+        const overridable = !mapped.some((m) => m.postHoc);
+        runtime = createHookRuntime({ ...runtimePaths(dir, cwd), override: (agentKid) => {
+                const made = overridable ? createOverrideHandler({ dir, home: userHome(), agentKid, harness: "cursor", permissionMode, waitMs: OVERRIDE_WAIT_MS.cursor }) : null;
+                return made ? { handler: made.handler, hint: () => overrideHint(made.note()) } : null;
+            } });
+        useDigestKey(loadOrCreateDigestKey(dir));
         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(), syncIfDue(dir, () => syncOptionsFor(dir))]);
@@ -481,7 +510,7 @@ function runInit(args) {
     // `scopebond-hook` binary on PATH, so a bare `scopebond-hook log` would fail.
     console.log(`Next: run one command in the agent, then \`${cliCommand("log")}\` to see the receipt`);
     console.log(`and \`${cliCommand("verify")}\` to check it offline. Try \`${cliCommand('test "rm -rf /"')}\`.`);
-    console.log(`To send receipts to a workspace: ${cliCommand("connect <workspace-url> <enrollment>")}`);
+    console.log(onboardingSteps({ harness, command: cliCommand, project: true }).join("\n"));
 }
 function decisionOf(payload) {
     const rr = String(payload.realtime_result ?? "");
@@ -956,6 +985,7 @@ async function finishConnect(dir, url, bundle, harness, args) {
             console.log(`Observations: ${observing.reason}`);
         console.log("");
         console.log("Run your agent — the first action appears in your workspace within seconds.");
+        console.log(onboardingSteps({ harness, command: cliCommand, connected: true }).join("\n"));
     }
     catch (error) {
         const message = error.message;
@@ -1355,7 +1385,7 @@ function runInstall(args) {
     console.log("");
     console.log(`A project's own .scopebond policy applies only after you trust it there (${cliCommand("trust")}).`);
     console.log(`Check it: ${cliCommand("doctor")} · see decisions: ${cliCommand("log")}`);
-    console.log(`To send receipts to a workspace: ${cliCommand("connect <workspace-url> <enrollment>")}`);
+    console.log(onboardingSteps({ harness: harnesses[0], command: cliCommand }).join("\n"));
 }
 /** Size and count of the local receipt store, plus its write-ahead log. Signed evidence
  *  accumulates in the user's project directory and there is no automatic deletion — so