@scopebond/hook 0.6.0 → 0.8.0

package/README.md

@@ -55,16 +55,99 @@ npx @scopebond/hook init --codex    # Codex, then approve it once with /hooks
 
 `init` scaffolds `.scopebond/` in the current project (a machine signing key, a
 countersigning key, a starter policy — "protect main and production paths" — and a
-`.gitignore` so none of it is committed) and configures `.claude/settings.json`,
-`.cursor/hooks.json`, or `.codex/hooks.json`. Then run one safe command in the agent and see the receipt in
-`.scopebond/receipts.db`. `init`, `trust` and `uninstall` are meant for a person at a
-terminal: in a script or CI, pass `--yes`.
+`.gitignore` so none of it is committed) and wires your agent to the hook. Then run one
+safe command in the agent and see the receipt in `.scopebond/receipts.db`. `init`, `trust`
+and `uninstall` are meant for a person at a terminal: in a script or CI, pass `--yes`.
+`npx @scopebond/hook init --dry-run` shows what it would write, and changes nothing.
+
+**Where the hook goes, and why.** `init` pins a copy of the hook on this machine so it
+starts fast on every tool call. That command names paths that exist only here, so it
+never goes into a file your team shares: for Claude Code it goes into
+`.claude/settings.local.json`, which `init` keeps out of git for this clone; for Cursor
+and Codex it goes into `.cursor/hooks.json` or `.codex/hooks.json` only while git does not
+already track that file, and a tracked file gets the portable command instead. A hook
+command that cannot start is treated by the agent as a non-blocking error — the agent
+carries on with no check — so a machine-specific path in a committed file would leave
+every teammate unprotected while the file says otherwise. `doctor` reports that case, and
+running `init` again moves an entry an older version wrote into `.claude/settings.json`.
+
+To give everyone who clones the project the hook, use `init --shared`: it writes the
+portable command (`npx -y @scopebond/hook@<version> claude`) to `.claude/settings.json`,
+`.cursor/hooks.json` or `.codex/hooks.json`. It starts on any machine, more slowly, and
+until a teammate runs `init` themselves it blocks their agent's actions with a message
+saying how to set it up.
+
+Check what it did with `npx @scopebond/hook status` (which agents are configured, in
+which scope) and `npx @scopebond/hook doctor` (whether each configured command can
+actually start).
+
+### Changing the rules
+
+`.scopebond/policy.json` is **generated**. The thing you edit is `.scopebond/rules.json`,
+a short readable list, and `policy.json` is compiled from it — so a limit is a line in a
+list, not a 700-character lookahead:
+
+```
+npx @scopebond/hook rules                      # what is blocked, in plain English
+npx @scopebond/hook rules allow dd             # stop blocking a program
+npx @scopebond/hook rules protect infra/       # never write there
+npx @scopebond/hook rules protect-branch production
+npx @scopebond/hook rules apply                # recompile after editing rules.json by hand
+```
+
+The compiled patterns are identical to the ones this package has always shipped — there
+is a test that pins them against the starter policy — so the readable front end cannot
+change what is enforced. Each clause description is generated from the list too, so it
+stays true after an edit, and a block message quotes it.
+
+### The hook command `init` installs
+
+The hook runs once per tool call, so the command has to start fast. `init` copies this
+package into `~/.scopebond/runtime/<version>/` once per machine and points your agent
+at that absolute path. Measured on one Windows machine, through a shell, warm cache:
+
+| Command in the agent config | Median per tool call |
+|---|---|
+| pinned absolute path (the default) | **151 ms** |
+| `npx -y @scopebond/hook@<version>` | 1053 ms |
+
+That ~900 ms is npm re-resolving a package already on disk, on every action. Pass
+`--npx` to `init` if you would rather have the portable command, and `init` falls back
+to it automatically when it cannot make a durable copy — slow beats broken. `doctor`
+re-checks that the pinned paths still resolve, so a cleared home or a switched Node
+version shows up as a problem rather than as a hook that silently cannot start.
+
+### What each agent can actually stop
+
+| | Claude Code | Cursor | Codex |
+|---|---|---|---|
+| Shell commands | prevented | prevented | prevented |
+| File reads | prevented | prevented | prevented |
+| MCP tool calls | prevented | prevented | prevented |
+| File writes / edits | prevented | **recorded, not prevented** | prevented |
+
+Cursor reports a file edit only *after* it is written (`afterFileEdit`; it has no
+before-edit hook), so an out-of-policy edit there is signed and flagged, not blocked —
+and the message says so rather than claiming otherwise. For edits that must be stopped
+before they land, make `@scopebond/github-action` a required check on pull requests.
 
 ## Connect it to your workspace (optional)
 
-To see the receipts in your hosted Scopebond workspace, create a connection from
-the portal's **Connect** step (it gives you a one-use enrollment bundle), save it
-as `scopebond-enrollment.json`, then:
+To see the receipts in your hosted Scopebond workspace, sign this computer in:
+
+```
+npx @scopebond/hook login https://<your-workspace>
+```
+
+It prints a short code and a link. Someone who manages the workspace opens the link,
+checks that the code matches, and approves it for an environment and agent. The
+command then finishes connecting on its own: nothing is copied or pasted, and the
+code expires after 10 minutes if nobody approves it. Add `--cursor` or `--codex`
+for those agents, or `--no-install` to leave the agent's settings alone.
+
+If your workspace does not offer sign-in codes, create a connection from the
+portal's **Connect** step (it gives you a one-use enrollment bundle), save it as
+`scopebond-enrollment.json`, then:
 
 ```
 npx @scopebond/hook connect https://<your-workspace> scopebond-enrollment.json
@@ -82,8 +165,8 @@ can hand you a single copy-paste command with nothing to save.
 
 From then on every receipt is mirrored to the workspace through a **durable outbox**:
 delivery is best-effort and never blocks a tool call, and receipts are retained
-locally and retried if the workspace is unreachable. `scopebond-hook flush` delivers
-anything still queued — run it on a session-end hook (and set
+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.
 
 ## How it works
@@ -91,14 +174,41 @@ anything still queued — run it on a session-end hook (and set
 Each tool call is mapped to a normalized [Action Taxonomy](https://github.com/avouro-com/scopebond)
 action (`shell.exec`, `git.push`, `file.write`, `mcp.tool.call`, …), signed by the
 machine key and decided against your policy by an in-process check-only gateway.
-An allowed action is recorded and left to the coding agent's normal permission
-prompt; the hook never auto-approves it. A denied action is blocked. Unknown tools are
-recorded as *not evaluated* and grant nothing. Anything unexpected fails closed
-(deny) with a repair message.
+An allowed action is recorded and the agent proceeds. A denied action is blocked.
+Unknown tools are recorded as *not evaluated* and grant nothing — they fall through to
+the coding agent's own permission prompt, so the hook never turns an unrecognised
+action into an approval. Anything unexpected fails closed (deny) with a repair message.
+
+**What a block says.** A denial names the action, the rule that decided, why that rule
+exists (the clause's own description), the engine's technical detail and where to change
+it. The same text goes to the agent, so it can choose another approach instead of
+retrying a blocked call:
+
+```
+Scopebond blocked git.push origin main — rule "protect-branches" (enforce).
+Why: Deny pushes to main, master and release/* (any case, any refspec spelling), …
+Detail: param ref fails pattern
+Change the rule: edit clause "protect-branches" in /repo/.scopebond/policy.json
+```
 
 Commands are stored as a scrubbed head plus a digest; file contents are never
 stored; common secret shapes are removed before signing.
 
+**Where receipts live, and how much room they take.** `.scopebond/receipts.db` in the
+project, roughly 25 KiB per tool call. Nothing is ever deleted automatically — these are
+your evidence — so `status` reports the count and size, and `prune` bounds it when you
+choose to:
+
+```
+npx @scopebond/hook prune                      # report the footprint
+npx @scopebond/hook prune --before 90d --yes   # archive, then remove, anything older
+```
+
+`prune` writes the receipts it will remove to a JSONL file beside the database first, so
+they stay verifiable, and it refuses outright once the log has been anchored — a receipt's
+position is its anchor leaf index, so removing one would make an existing anchor
+unverifiable.
+
 **What a shell command is checked for.** A command line is split into every command it
 runs (`&&`, `;`, pipes, `$( )` and backticks — also inside double quotes — `bash -c`,
 `eval`, `trap`, `su -c`, `script -c`, `watch`, `parallel`, `cmd /c`, `pwsh -Command`

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
-export {};
+/** A `--since` value: a duration (`7d`, `24h`, `30m`) or an ISO-ish date. */
+export declare function parseSince(value: string | undefined, now?: number): number | null;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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