@scopebond/hook 0.6.0 → 0.7.0

package/dist/rules.js

@@ -0,0 +1,216 @@
+// Rules you can actually read and change.
+//
+// The site says "set rules in plain terms" and "it is a plain JSON file — edit the
+// limits". What `init` wrote was 6.7 KB of generated regular expression: the `safe-shell`
+// clause alone is a ~700-character case-folded negative lookahead. Nobody edits that, so
+// in practice the starter policy was the *only* policy and "set your own rules" was not
+// true.
+//
+// The fix is not to weaken the patterns — they are careful, and the canonicalization
+// tests exist because bypasses are subtle. It is to stop making the pattern the
+// interface. The lists the patterns are built from live in `.scopebond/rules.json`, a
+// short readable file, and `policy.json` is compiled from it. The regex stays as the
+// compiled form.
+//
+// `compile()` reproduces the shipped starter policy's enforcement patterns exactly —
+// `rules.test.mjs` asserts that against `starterPolicy()`, so a change here cannot
+// quietly alter what is enforced.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ci, under, named, dir, DESTRUCTIVE } from "./runtime.js";
+export const RULES_FILE = "rules.json";
+const pathPattern = (rule) => rule.kind === "under" ? under(rule.value)
+    : rule.kind === "named" ? named(rule.value)
+        : rule.kind === "dir" ? dir(rule.value)
+            : rule.pattern;
+/** Escape every regular-expression metacharacter, backslash included.
+ *
+ *  A path the user typed is literal text, and this value goes straight into a rule that
+ *  decides what the agent may touch: if one metacharacter escapes escaping, the rule
+ *  silently protects something other than what they asked for. The class is therefore
+ *  complete on its own rather than relying on an earlier step having removed backslashes
+ *  (CodeQL js/incomplete-sanitization). */
+const escapeRegex = (text) => text.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
+/** A protected-path rule from a plain path the user typed. A trailing `/` (or a path with
+ *  no dot in its last segment) reads as a directory; anything else as a file name.
+ *
+ *  Normalisation is one obvious step at a time. The previous version folded separator
+ *  conversion and leading-`./` stripping into a single `^[./\\]+` replace with a callback,
+ *  which was both hard to read and quadratic on a path of many leading dots
+ *  (CodeQL js/polynomial-redos). */
+export function pathRuleFor(input) {
+    const trimmed = input.trim();
+    const withForwardSlashes = trimmed.split("\\").join("/");
+    const withoutDotSlash = withForwardSlashes.startsWith("./") ? withForwardSlashes.slice(2) : withForwardSlashes;
+    // Drop trailing separators without a quantifier, so the cost is plainly linear.
+    let clean = withoutDotSlash;
+    while (clean.endsWith("/"))
+        clean = clean.slice(0, -1);
+    // A trailing slash is an explicit directory; so is a last segment with no extension.
+    // Checked by string, not by `/\.[^/]*$/`: that pattern is unanchored at the front, so it
+    // retries at every position and goes quadratic on a long path.
+    const lastSegment = clean.slice(clean.lastIndexOf("/") + 1);
+    const isDirectory = trimmed.endsWith("/") || !lastSegment.includes(".");
+    return isDirectory
+        ? { kind: "under", value: escapeRegex(clean), label: `${clean}/ and everything in it` }
+        : { kind: "named", value: escapeRegex(clean), label: clean };
+}
+/** The branch pattern: deny the listed refs, plus the "every branch at once" flags and a
+ *  push whose destination could not be read. `--tags` alone is allowed. */
+function branchPattern(branches) {
+    const exact = branches.filter((b) => !b.endsWith("/*"));
+    const prefixes = branches.filter((b) => b.endsWith("/*")).map((b) => b.slice(0, -1));
+    const parts = [
+        exact.length ? `(?!(?:${exact.map(ci).join("|")})$)` : "",
+        ...prefixes.map((p) => `(?!${ci(p)})`),
+        `(?!-(?!-${ci("tags")}$))`,
+    ];
+    return `^${parts.join("")}.+`;
+}
+const programPattern = (programs) => `^(?!(?:${programs.map(ci).join("|")})(?:${ci("\\.(?:exe|cmd|bat|com|ps1)")})?$).+`;
+const pathsPattern = (rules) => `^${rules.map(pathPattern).join("")}.+`;
+/** A sentence listing what a clause covers, generated from the list rather than written by
+ *  hand — so it stays true after an edit. The block message quotes this, so a stale
+ *  description would be a lie told at the worst moment. */
+function sentence(items, limit = 12) {
+    const shown = items.slice(0, limit);
+    const rest = items.length - shown.length;
+    return shown.join(", ") + (rest > 0 ? `, and ${rest} more` : "");
+}
+/** Compile a rule set into the policy the gateway evaluates. */
+export function compile(rules, agentKid) {
+    return {
+        vocabulary_version: "1.0", policy_id: "coding-agent", version: 1,
+        clauses: [
+            {
+                id: "protect-branches", type: "action_allowlist", mode: "enforce", action_types: ["git.push"],
+                param_bounds: { ref: { pattern: branchPattern(rules.protected_branches) } },
+                description: `Deny pushes to ${sentence(rules.protected_branches)} (any case, any refspec spelling), pushes of every branch at once (--all, --mirror) and pushes whose destination cannot be read from the command (a git alias, a configured push refspec, send-pack). A tags-only push (--tags) is allowed. Change these in .scopebond/${RULES_FILE}.`,
+            },
+            {
+                id: "safe-shell", type: "action_allowlist", mode: "enforce", action_types: ["shell.exec"],
+                param_bounds: { program: { pattern: programPattern(rules.destructive_programs) } },
+                description: `Deny destructive programs (${sentence(rules.destructive_programs, 10)}) in any case and with or without .exe. An empty program — a command that could not be parsed, or whose program is only known at run time ($VAR, $(…), eval of a variable) — is denied. Argument-shaped deletion (find -delete, git clean) is not a program name and is not covered here. Change this list in .scopebond/${RULES_FILE}.`,
+            },
+            {
+                id: "protect-write", type: "action_allowlist", mode: "enforce", action_types: ["file.write"],
+                param_bounds: { path: { pattern: pathsPattern(rules.protected_write) } },
+                description: `Allow workspace writes, but never to ${sentence(rules.protected_write.map((r) => r.label))}. Case-insensitive. Change this list in .scopebond/${RULES_FILE}.`,
+            },
+            {
+                id: "protect-read", type: "action_allowlist", mode: "enforce", action_types: ["file.read"],
+                param_bounds: { path: { pattern: pathsPattern(rules.protected_read) } },
+                description: `Allow workspace reads, but never ${sentence(rules.protected_read.map((r) => r.label))}. Case-insensitive. Change this list in .scopebond/${RULES_FILE}.`,
+            },
+            {
+                id: "observe-net-mcp", type: "action_allowlist", mode: "monitor",
+                action_types: rules.observe,
+                description: `Observe ${sentence(rules.observe)} — recorded, not blocked. Add bounds to enforce. Change this list in .scopebond/${RULES_FILE}.`,
+            },
+            { id: "keys", type: "key_policy", active_keys: [agentKid], description: "Only the enrolled machine key may sign." },
+        ],
+    };
+}
+/** The shipped defaults. Every entry here reproduces one piece of the starter policy's
+ *  patterns; `rules.test.mjs` pins that equivalence. */
+export function defaultRules() {
+    return {
+        version: 1,
+        protected_branches: ["main", "master", "release/*"],
+        destructive_programs: [...DESTRUCTIVE],
+        protected_write: [
+            { kind: "under", value: "\\.scopebond", label: "the hook's own policy and keys (.scopebond)" },
+            { kind: "raw", pattern: `(?!(?:.*/)?${ci("\\.claude/settings")})`, label: "Claude Code settings" },
+            { kind: "under", value: "\\.claude/hooks", label: "Claude Code hooks" },
+            { kind: "under", value: "\\.claude/agents", label: "Claude Code agents" },
+            { kind: "raw", pattern: `(?!(?:.*/)?${ci("\\.cursor/hooks")})`, label: "Cursor hook settings" },
+            { kind: "named", value: "\\.codex/hooks\\.json", label: "Codex hook settings" },
+            { kind: "named", value: "\\.codex/config\\.toml", label: "Codex config" },
+            { kind: "named", value: "\\.mcp\\.json", label: ".mcp.json" },
+            { kind: "under", value: "\\.git/hooks", label: "git hooks" },
+            { kind: "named", value: "\\.git/config", label: "git config" },
+            { kind: "under", value: "\\.husky", label: "Husky hooks" },
+            { kind: "under", value: "\\.github/workflows", label: "GitHub workflows" },
+            { kind: "under", value: "\\.github/actions", label: "GitHub actions" },
+            { kind: "named", value: "\\.gitlab-ci\\.yml", label: ".gitlab-ci.yml" },
+            { kind: "named", value: "\\.gitlab-ci\\.yaml", label: ".gitlab-ci.yaml" },
+            { kind: "under", value: "\\.circleci", label: "CircleCI config" },
+            { kind: "named", value: "azure-pipelines\\.yml", label: "azure-pipelines.yml" },
+            { kind: "named", value: "Jenkinsfile", label: "Jenkinsfile" },
+        ],
+        protected_read: [
+            { kind: "under", value: "\\.scopebond", label: "the hook's own policy and keys (.scopebond)" },
+            { kind: "raw", pattern: `(?!.*${ci("\\.(?:key|pem|p12|pfx|jks|keystore)")}$)`, label: "signing keys and key containers (*.key, *.pem, *.p12, *.pfx, *.jks)" },
+            {
+                kind: "raw",
+                pattern: `(?!(?:.*/)?${ci("\\.env")}(?!(?:\\.[^/]*)?\\.(?:${ci("example")}|${ci("sample")}|${ci("template")}|${ci("dist")})$)(?:\\.[^/]*)?$)`,
+                label: "environment secret files (.env, .env.* — except .example/.sample/.template/.dist)",
+            },
+            { kind: "named", value: "\\.envrc", label: ".envrc" },
+            {
+                kind: "raw",
+                pattern: `(?!(?:.*/)?${ci("\\.ssh")}(?:$|/(?!.*${ci("\\.pub")}$)(?!${ci("known_hosts")}$)(?!${ci("config")}$)))`,
+                label: "SSH private keys and the .ssh directory (public keys, known_hosts and config are allowed)",
+            },
+            { kind: "raw", pattern: `(?!(?:.*/)?${ci("\\.aws")}(?:$|/(?!${ci("config")}$)))`, label: "AWS credentials (.aws, except .aws/config)" },
+            { kind: "named", value: "\\.npmrc", label: ".npmrc" },
+            { kind: "named", value: "\\.pypirc", label: ".pypirc" },
+            { kind: "named", value: "\\.netrc", label: ".netrc" },
+            { kind: "named", value: "_netrc", label: "_netrc" },
+            { kind: "named", value: "\\.git-credentials", label: ".git-credentials" },
+            { kind: "dir", value: "\\.kube", label: "the .kube directory" },
+            { kind: "named", value: "\\.kube/config", label: ".kube/config" },
+            { kind: "dir", value: "\\.docker", label: "the .docker directory" },
+            { kind: "named", value: "\\.docker/config\\.json", label: ".docker/config.json" },
+            { kind: "under", value: "\\.config/gcloud", label: "gcloud credentials" },
+            { kind: "under", value: "\\.azure", label: "Azure credentials" },
+            { kind: "under", value: "\\.gnupg", label: "GnuPG keys" },
+            { kind: "dir", value: "\\.config/gh", label: "the GitHub CLI config directory" },
+            { kind: "named", value: "\\.config/gh/hosts\\.yml", label: "the GitHub CLI's hosts.yml" },
+            { kind: "named", value: "\\.claude/\\.credentials\\.json", label: "Claude Code's .credentials.json" },
+        ],
+        observe: ["net.fetch", "mcp.tool.call"],
+    };
+}
+export const rulesPath = (dir) => join(dir, RULES_FILE);
+export function loadRules(configDir) {
+    const file = rulesPath(configDir);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed?.version !== 1 || !Array.isArray(parsed.protected_branches))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveRules(configDir, rules) {
+    const file = rulesPath(configDir);
+    writeFileSync(file, `${JSON.stringify(rules, null, 2)}\n`);
+    return file;
+}
+/** Plain English, for `scopebond-hook rules`. */
+export function describeRules(rules) {
+    const lines = [];
+    lines.push("Blocked before it runs:");
+    lines.push("");
+    lines.push(`  pushes to          ${rules.protected_branches.join(", ")}`);
+    lines.push(`                     and any push whose destination cannot be read`);
+    lines.push(`  programs           ${rules.destructive_programs.join(", ")}`);
+    lines.push("");
+    lines.push(`  writes to          ${rules.protected_write.length} protected location(s):`);
+    for (const rule of rules.protected_write)
+        lines.push(`                       ${rule.label}`);
+    lines.push("");
+    lines.push(`  reads of           ${rules.protected_read.length} protected location(s):`);
+    for (const rule of rules.protected_read)
+        lines.push(`                       ${rule.label}`);
+    lines.push("");
+    lines.push("Recorded, not blocked:");
+    lines.push(`  ${rules.observe.join(", ")}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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","sourcesContent":["// Rules you can actually read and change.\n//\n// The site says \"set rules in plain terms\" and \"it is a plain JSON file — edit the\n// limits\". What `init` wrote was 6.7 KB of generated regular expression: the `safe-shell`\n// clause alone is a ~700-character case-folded negative lookahead. Nobody edits that, so\n// in practice the starter policy was the *only* policy and \"set your own rules\" was not\n// true.\n//\n// The fix is not to weaken the patterns — they are careful, and the canonicalization\n// tests exist because bypasses are subtle. It is to stop making the pattern the\n// interface. The lists the patterns are built from live in `.scopebond/rules.json`, a\n// short readable file, and `policy.json` is compiled from it. The regex stays as the\n// compiled form.\n//\n// `compile()` reproduces the shipped starter policy's enforcement patterns exactly —\n// `rules.test.mjs` asserts that against `starterPolicy()`, so a change here cannot\n// quietly alter what is enforced.\n\nimport { existsSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { ci, under, named, dir, DESTRUCTIVE } from \"./runtime.js\";\n\n/** One protected location. `under`/`named`/`dir` are the readable, editable shapes;\n *  `raw` carries the few patterns with bespoke exceptions (`.env` templates are allowed,\n *  `.ssh/config` and `*.pub` are allowed) that no simple shape expresses. */\nexport type PathRule =\n  | { kind: \"under\"; value: string; label: string }\n  | { kind: \"named\"; value: string; label: string }\n  | { kind: \"dir\"; value: string; label: string }\n  | { kind: \"raw\"; pattern: string; label: string };\n\nexport interface RuleSet {\n  version: 1;\n  /** Refs an agent may not push to. `release/*` means the prefix `release/`. */\n  protected_branches: string[];\n  /** Programs an agent may not run, in any case and with or without .exe. */\n  destructive_programs: string[];\n  protected_write: PathRule[];\n  protected_read: PathRule[];\n  /** Action types recorded but not blocked. */\n  observe: string[];\n}\n\nexport const RULES_FILE = \"rules.json\";\n\nconst pathPattern = (rule: PathRule): string =>\n  rule.kind === \"under\" ? under(rule.value)\n    : rule.kind === \"named\" ? named(rule.value)\n    : rule.kind === \"dir\" ? dir(rule.value)\n    : rule.pattern;\n\n/** Escape every regular-expression metacharacter, backslash included.\n *\n *  A path the user typed is literal text, and this value goes straight into a rule that\n *  decides what the agent may touch: if one metacharacter escapes escaping, the rule\n *  silently protects something other than what they asked for. The class is therefore\n *  complete on its own rather than relying on an earlier step having removed backslashes\n *  (CodeQL js/incomplete-sanitization). */\nconst escapeRegex = (text: string): string => text.replace(/[\\\\^$.*+?()[\\]{}|/]/g, \"\\\\$&\");\n\n/** A protected-path rule from a plain path the user typed. A trailing `/` (or a path with\n *  no dot in its last segment) reads as a directory; anything else as a file name.\n *\n *  Normalisation is one obvious step at a time. The previous version folded separator\n *  conversion and leading-`./` stripping into a single `^[./\\\\]+` replace with a callback,\n *  which was both hard to read and quadratic on a path of many leading dots\n *  (CodeQL js/polynomial-redos). */\nexport function pathRuleFor(input: string): PathRule {\n  const trimmed = input.trim();\n  const withForwardSlashes = trimmed.split(\"\\\\\").join(\"/\");\n  const withoutDotSlash = withForwardSlashes.startsWith(\"./\") ? withForwardSlashes.slice(2) : withForwardSlashes;\n  // Drop trailing separators without a quantifier, so the cost is plainly linear.\n  let clean = withoutDotSlash;\n  while (clean.endsWith(\"/\")) clean = clean.slice(0, -1);\n  // A trailing slash is an explicit directory; so is a last segment with no extension.\n  // Checked by string, not by `/\\.[^/]*$/`: that pattern is unanchored at the front, so it\n  // retries at every position and goes quadratic on a long path.\n  const lastSegment = clean.slice(clean.lastIndexOf(\"/\") + 1);\n  const isDirectory = trimmed.endsWith(\"/\") || !lastSegment.includes(\".\");\n  return isDirectory\n    ? { kind: \"under\", value: escapeRegex(clean), label: `${clean}/ and everything in it` }\n    : { kind: \"named\", value: escapeRegex(clean), label: clean };\n}\n\n/** The branch pattern: deny the listed refs, plus the \"every branch at once\" flags and a\n *  push whose destination could not be read. `--tags` alone is allowed. */\nfunction branchPattern(branches: string[]): string {\n  const exact = branches.filter((b) => !b.endsWith(\"/*\"));\n  const prefixes = branches.filter((b) => b.endsWith(\"/*\")).map((b) => b.slice(0, -1));\n  const parts = [\n    exact.length ? `(?!(?:${exact.map(ci).join(\"|\")})$)` : \"\",\n    ...prefixes.map((p) => `(?!${ci(p)})`),\n    `(?!-(?!-${ci(\"tags\")}$))`,\n  ];\n  return `^${parts.join(\"\")}.+`;\n}\n\nconst programPattern = (programs: string[]): string =>\n  `^(?!(?:${programs.map(ci).join(\"|\")})(?:${ci(\"\\\\.(?:exe|cmd|bat|com|ps1)\")})?$).+`;\n\nconst pathsPattern = (rules: PathRule[]): string => `^${rules.map(pathPattern).join(\"\")}.+`;\n\n/** A sentence listing what a clause covers, generated from the list rather than written by\n *  hand — so it stays true after an edit. The block message quotes this, so a stale\n *  description would be a lie told at the worst moment. */\nfunction sentence(items: string[], limit = 12): string {\n  const shown = items.slice(0, limit);\n  const rest = items.length - shown.length;\n  return shown.join(\", \") + (rest > 0 ? `, and ${rest} more` : \"\");\n}\n\n/** Compile a rule set into the policy the gateway evaluates. */\nexport function compile(rules: RuleSet, agentKid: string): Record<string, unknown> {\n  return {\n    vocabulary_version: \"1.0\", policy_id: \"coding-agent\", version: 1,\n    clauses: [\n      {\n        id: \"protect-branches\", type: \"action_allowlist\", mode: \"enforce\", action_types: [\"git.push\"],\n        param_bounds: { ref: { pattern: branchPattern(rules.protected_branches) } },\n        description: `Deny pushes to ${sentence(rules.protected_branches)} (any case, any refspec spelling), pushes of every branch at once (--all, --mirror) and pushes whose destination cannot be read from the command (a git alias, a configured push refspec, send-pack). A tags-only push (--tags) is allowed. Change these in .scopebond/${RULES_FILE}.`,\n      },\n      {\n        id: \"safe-shell\", type: \"action_allowlist\", mode: \"enforce\", action_types: [\"shell.exec\"],\n        param_bounds: { program: { pattern: programPattern(rules.destructive_programs) } },\n        description: `Deny destructive programs (${sentence(rules.destructive_programs, 10)}) in any case and with or without .exe. An empty program — a command that could not be parsed, or whose program is only known at run time ($VAR, $(…), eval of a variable) — is denied. Argument-shaped deletion (find -delete, git clean) is not a program name and is not covered here. Change this list in .scopebond/${RULES_FILE}.`,\n      },\n      {\n        id: \"protect-write\", type: \"action_allowlist\", mode: \"enforce\", action_types: [\"file.write\"],\n        param_bounds: { path: { pattern: pathsPattern(rules.protected_write) } },\n        description: `Allow workspace writes, but never to ${sentence(rules.protected_write.map((r) => r.label))}. Case-insensitive. Change this list in .scopebond/${RULES_FILE}.`,\n      },\n      {\n        id: \"protect-read\", type: \"action_allowlist\", mode: \"enforce\", action_types: [\"file.read\"],\n        param_bounds: { path: { pattern: pathsPattern(rules.protected_read) } },\n        description: `Allow workspace reads, but never ${sentence(rules.protected_read.map((r) => r.label))}. Case-insensitive. Change this list in .scopebond/${RULES_FILE}.`,\n      },\n      {\n        id: \"observe-net-mcp\", type: \"action_allowlist\", mode: \"monitor\",\n        action_types: rules.observe,\n        description: `Observe ${sentence(rules.observe)} — recorded, not blocked. Add bounds to enforce. Change this list in .scopebond/${RULES_FILE}.`,\n      },\n      { id: \"keys\", type: \"key_policy\", active_keys: [agentKid], description: \"Only the enrolled machine key may sign.\" },\n    ],\n  };\n}\n\n/** The shipped defaults. Every entry here reproduces one piece of the starter policy's\n *  patterns; `rules.test.mjs` pins that equivalence. */\nexport function defaultRules(): RuleSet {\n  return {\n    version: 1,\n    protected_branches: [\"main\", \"master\", \"release/*\"],\n    destructive_programs: [...DESTRUCTIVE],\n    protected_write: [\n      { kind: \"under\", value: \"\\\\.scopebond\", label: \"the hook's own policy and keys (.scopebond)\" },\n      { kind: \"raw\", pattern: `(?!(?:.*/)?${ci(\"\\\\.claude/settings\")})`, label: \"Claude Code settings\" },\n      { kind: \"under\", value: \"\\\\.claude/hooks\", label: \"Claude Code hooks\" },\n      { kind: \"under\", value: \"\\\\.claude/agents\", label: \"Claude Code agents\" },\n      { kind: \"raw\", pattern: `(?!(?:.*/)?${ci(\"\\\\.cursor/hooks\")})`, label: \"Cursor hook settings\" },\n      { kind: \"named\", value: \"\\\\.codex/hooks\\\\.json\", label: \"Codex hook settings\" },\n      { kind: \"named\", value: \"\\\\.codex/config\\\\.toml\", label: \"Codex config\" },\n      { kind: \"named\", value: \"\\\\.mcp\\\\.json\", label: \".mcp.json\" },\n      { kind: \"under\", value: \"\\\\.git/hooks\", label: \"git hooks\" },\n      { kind: \"named\", value: \"\\\\.git/config\", label: \"git config\" },\n      { kind: \"under\", value: \"\\\\.husky\", label: \"Husky hooks\" },\n      { kind: \"under\", value: \"\\\\.github/workflows\", label: \"GitHub workflows\" },\n      { kind: \"under\", value: \"\\\\.github/actions\", label: \"GitHub actions\" },\n      { kind: \"named\", value: \"\\\\.gitlab-ci\\\\.yml\", label: \".gitlab-ci.yml\" },\n      { kind: \"named\", value: \"\\\\.gitlab-ci\\\\.yaml\", label: \".gitlab-ci.yaml\" },\n      { kind: \"under\", value: \"\\\\.circleci\", label: \"CircleCI config\" },\n      { kind: \"named\", value: \"azure-pipelines\\\\.yml\", label: \"azure-pipelines.yml\" },\n      { kind: \"named\", value: \"Jenkinsfile\", label: \"Jenkinsfile\" },\n    ],\n    protected_read: [\n      { kind: \"under\", value: \"\\\\.scopebond\", label: \"the hook's own policy and keys (.scopebond)\" },\n      { kind: \"raw\", pattern: `(?!.*${ci(\"\\\\.(?:key|pem|p12|pfx|jks|keystore)\")}$)`, label: \"signing keys and key containers (*.key, *.pem, *.p12, *.pfx, *.jks)\" },\n      {\n        kind: \"raw\",\n        pattern: `(?!(?:.*/)?${ci(\"\\\\.env\")}(?!(?:\\\\.[^/]*)?\\\\.(?:${ci(\"example\")}|${ci(\"sample\")}|${ci(\"template\")}|${ci(\"dist\")})$)(?:\\\\.[^/]*)?$)`,\n        label: \"environment secret files (.env, .env.* — except .example/.sample/.template/.dist)\",\n      },\n      { kind: \"named\", value: \"\\\\.envrc\", label: \".envrc\" },\n      {\n        kind: \"raw\",\n        pattern: `(?!(?:.*/)?${ci(\"\\\\.ssh\")}(?:$|/(?!.*${ci(\"\\\\.pub\")}$)(?!${ci(\"known_hosts\")}$)(?!${ci(\"config\")}$)))`,\n        label: \"SSH private keys and the .ssh directory (public keys, known_hosts and config are allowed)\",\n      },\n      { kind: \"raw\", pattern: `(?!(?:.*/)?${ci(\"\\\\.aws\")}(?:$|/(?!${ci(\"config\")}$)))`, label: \"AWS credentials (.aws, except .aws/config)\" },\n      { kind: \"named\", value: \"\\\\.npmrc\", label: \".npmrc\" },\n      { kind: \"named\", value: \"\\\\.pypirc\", label: \".pypirc\" },\n      { kind: \"named\", value: \"\\\\.netrc\", label: \".netrc\" },\n      { kind: \"named\", value: \"_netrc\", label: \"_netrc\" },\n      { kind: \"named\", value: \"\\\\.git-credentials\", label: \".git-credentials\" },\n      { kind: \"dir\", value: \"\\\\.kube\", label: \"the .kube directory\" },\n      { kind: \"named\", value: \"\\\\.kube/config\", label: \".kube/config\" },\n      { kind: \"dir\", value: \"\\\\.docker\", label: \"the .docker directory\" },\n      { kind: \"named\", value: \"\\\\.docker/config\\\\.json\", label: \".docker/config.json\" },\n      { kind: \"under\", value: \"\\\\.config/gcloud\", label: \"gcloud credentials\" },\n      { kind: \"under\", value: \"\\\\.azure\", label: \"Azure credentials\" },\n      { kind: \"under\", value: \"\\\\.gnupg\", label: \"GnuPG keys\" },\n      { kind: \"dir\", value: \"\\\\.config/gh\", label: \"the GitHub CLI config directory\" },\n      { kind: \"named\", value: \"\\\\.config/gh/hosts\\\\.yml\", label: \"the GitHub CLI's hosts.yml\" },\n      { kind: \"named\", value: \"\\\\.claude/\\\\.credentials\\\\.json\", label: \"Claude Code's .credentials.json\" },\n    ],\n    observe: [\"net.fetch\", \"mcp.tool.call\"],\n  };\n}\n\nexport const rulesPath = (dir: string): string => join(dir, RULES_FILE);\n\nexport function loadRules(configDir: string): RuleSet | null {\n  const file = rulesPath(configDir);\n  if (!existsSync(file)) return null;\n  try {\n    const parsed = JSON.parse(readFileSync(file, \"utf8\")) as RuleSet;\n    if (parsed?.version !== 1 || !Array.isArray(parsed.protected_branches)) return null;\n    return parsed;\n  } catch { return null; }\n}\n\nexport function saveRules(configDir: string, rules: RuleSet): string {\n  const file = rulesPath(configDir);\n  writeFileSync(file, `${JSON.stringify(rules, null, 2)}\\n`);\n  return file;\n}\n\n/** Plain English, for `scopebond-hook rules`. */\nexport function describeRules(rules: RuleSet): string {\n  const lines: string[] = [];\n  lines.push(\"Blocked before it runs:\");\n  lines.push(\"\");\n  lines.push(`  pushes to          ${rules.protected_branches.join(\", \")}`);\n  lines.push(`                     and any push whose destination cannot be read`);\n  lines.push(`  programs           ${rules.destructive_programs.join(\", \")}`);\n  lines.push(\"\");\n  lines.push(`  writes to          ${rules.protected_write.length} protected location(s):`);\n  for (const rule of rules.protected_write) lines.push(`                       ${rule.label}`);\n  lines.push(\"\");\n  lines.push(`  reads of           ${rules.protected_read.length} protected location(s):`);\n  for (const rule of rules.protected_read) lines.push(`                       ${rule.label}`);\n  lines.push(\"\");\n  lines.push(\"Recorded, not blocked:\");\n  lines.push(`  ${rules.observe.join(\", \")}`);\n  return lines.join(\"\\n\");\n}\n"]}

package/dist/runtime-install.d.ts

@@ -0,0 +1,25 @@
+/** Where pinned copies live: one directory per hook version. */
+export declare function runtimeRoot(): string;
+export declare function runtimeDirFor(version: string): string;
+/** The CLI inside a pinned copy. */
+export declare function pinnedCliPath(version: string): string;
+/** True when a path sits in npm's throwaway `npx` cache, which npm may clear at any
+ *  time. Anything else — a project `node_modules`, a global install, a pinned copy —
+ *  is durable enough to reference from a config file. */
+export declare function isEphemeralPath(file: string): boolean;
+/** Walk up from `dist/cli.js` to the `node_modules` directory that contains the whole
+ *  materialised dependency tree (`node_modules/@scopebond/hook/dist/cli.js` → four up).
+ *  Returns null if the layout is not what we expect, rather than copying the wrong thing. */
+export declare function nodeModulesRootOf(cliFile: string): string | null;
+export interface PinResult {
+    /** The CLI path to pin, or null to keep the `npx` form. */
+    cli: string | null;
+    /** Why, in one phrase, for the line `init` prints. */
+    how: "already-durable" | "pinned" | "reused" | "unavailable";
+}
+/** Make sure a durable copy of this CLI exists and say which path to pin.
+ *
+ *  Never throws: every failure degrades to `{ cli: null }` so the caller falls back
+ *  to `npx`, which is slower but always starts. */
+export declare function ensureDurableRuntime(cliFile: string, version: string): PinResult;
+//# sourceMappingURL=runtime-install.d.ts.map

package/dist/runtime-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-install.d.ts","sourceRoot":"","sources":["../src/runtime-install.ts"],"names":[],"mappings":"AAuBA,gEAAgE;AAChE,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,oCAAoC;AACpC,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;yDAEyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;6FAE6F;AAC7F,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAShE;AAeD,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,sDAAsD;IACtD,GAAG,EAAE,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC;CAC9D;AAED;;;mDAGmD;AACnD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CA0BhF"}

package/dist/runtime-install.js

@@ -0,0 +1,106 @@
+// Pinning the hook to a stable path, so the harness does not pay `npx` on every
+// tool call.
+//
+// `init` installs a hook command into the agent's config, and that command runs
+// once per tool call — hundreds of times an hour. The obvious command,
+// `npx -y @scopebond/hook@<version> claude`, costs about 830 ms a call on a warm
+// cache; running the same CLI directly costs about 110 ms. The ~720 ms difference
+// is npm resolving a package that is already on disk.
+//
+// The reason `init` used `npx` anyway is sound: a hook entry that cannot start is
+// worse than no hook, because a harness can read the failure as "no hook", and an
+// absolute path into npm's `_npx` cache is not durable — npm may clear it.
+//
+// So: copy the tree npx already materialised into the Scopebond home once per
+// machine and per version, and pin *that*. It is durable, self-contained, needs no
+// network, lives under the home the governed agent's own policy protects, and
+// `doctor` re-checks that the path still resolves. If anything here fails, the
+// caller keeps the `npx` form — slow beats broken.
+import { existsSync, mkdirSync, cpSync, rmSync, renameSync, readdirSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { userHome } from "./install.js";
+/** Where pinned copies live: one directory per hook version. */
+export function runtimeRoot() {
+    return join(userHome(), "runtime");
+}
+export function runtimeDirFor(version) {
+    return join(runtimeRoot(), version);
+}
+/** The CLI inside a pinned copy. */
+export function pinnedCliPath(version) {
+    return join(runtimeDirFor(version), "node_modules", "@scopebond", "hook", "dist", "cli.js");
+}
+/** True when a path sits in npm's throwaway `npx` cache, which npm may clear at any
+ *  time. Anything else — a project `node_modules`, a global install, a pinned copy —
+ *  is durable enough to reference from a config file. */
+export function isEphemeralPath(file) {
+    return `${sep}${file.replace(/[\\/]/g, sep)}${sep}`.includes(`${sep}_npx${sep}`);
+}
+/** Walk up from `dist/cli.js` to the `node_modules` directory that contains the whole
+ *  materialised dependency tree (`node_modules/@scopebond/hook/dist/cli.js` → four up).
+ *  Returns null if the layout is not what we expect, rather than copying the wrong thing. */
+export function nodeModulesRootOf(cliFile) {
+    let dir = dirname(cliFile); // .../dist
+    for (let i = 0; i < 6; i += 1) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        if (parent.endsWith(`${sep}node_modules`) || parent.endsWith("/node_modules"))
+            return parent;
+        dir = parent;
+    }
+    return null;
+}
+/** A pinned copy is usable only if the CLI and its sibling packages are all there —
+ *  a half-copied tree would fail closed on every tool call. */
+function pinnedCopyIsComplete(version) {
+    const cli = pinnedCliPath(version);
+    if (!existsSync(cli))
+        return false;
+    const scope = join(runtimeDirFor(version), "node_modules", "@scopebond");
+    try {
+        // The hook cannot run without the gateway and sdk it imports at startup.
+        const names = new Set(readdirSync(scope));
+        return names.has("hook") && names.has("gateway") && names.has("sdk");
+    }
+    catch {
+        return false;
+    }
+}
+/** Make sure a durable copy of this CLI exists and say which path to pin.
+ *
+ *  Never throws: every failure degrades to `{ cli: null }` so the caller falls back
+ *  to `npx`, which is slower but always starts. */
+export function ensureDurableRuntime(cliFile, version) {
+    try {
+        if (!existsSync(cliFile))
+            return { cli: null, how: "unavailable" };
+        // Already installed somewhere npm will not delete — pin it as it stands.
+        if (!isEphemeralPath(cliFile))
+            return { cli: cliFile, how: "already-durable" };
+        if (pinnedCopyIsComplete(version))
+            return { cli: pinnedCliPath(version), how: "reused" };
+        const source = nodeModulesRootOf(cliFile);
+        if (!source || !existsSync(source))
+            return { cli: null, how: "unavailable" };
+        const target = runtimeDirFor(version);
+        // Copy to a staging directory and move it into place, so an interrupted copy
+        // never leaves a partial tree that looks complete.
+        const staging = `${target}.incoming-${process.pid}`;
+        rmSync(staging, { recursive: true, force: true });
+        mkdirSync(staging, { recursive: true });
+        cpSync(source, join(staging, "node_modules"), { recursive: true, dereference: true });
+        rmSync(target, { recursive: true, force: true });
+        mkdirSync(dirname(target), { recursive: true });
+        renameSync(staging, target);
+        if (!pinnedCopyIsComplete(version)) {
+            rmSync(target, { recursive: true, force: true });
+            return { cli: null, how: "unavailable" };
+        }
+        return { cli: pinnedCliPath(version), how: "pinned" };
+    }
+    catch {
+        return { cli: null, how: "unavailable" };
+    }
+}
+//# sourceMappingURL=runtime-install.js.map

package/dist/runtime-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-install.js","sourceRoot":"","sources":["../src/runtime-install.ts"],"names":[],"mappings":"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","sourcesContent":["// Pinning the hook to a stable path, so the harness does not pay `npx` on every\n// tool call.\n//\n// `init` installs a hook command into the agent's config, and that command runs\n// once per tool call — hundreds of times an hour. The obvious command,\n// `npx -y @scopebond/hook@<version> claude`, costs about 830 ms a call on a warm\n// cache; running the same CLI directly costs about 110 ms. The ~720 ms difference\n// is npm resolving a package that is already on disk.\n//\n// The reason `init` used `npx` anyway is sound: a hook entry that cannot start is\n// worse than no hook, because a harness can read the failure as \"no hook\", and an\n// absolute path into npm's `_npx` cache is not durable — npm may clear it.\n//\n// So: copy the tree npx already materialised into the Scopebond home once per\n// machine and per version, and pin *that*. It is durable, self-contained, needs no\n// network, lives under the home the governed agent's own policy protects, and\n// `doctor` re-checks that the path still resolves. If anything here fails, the\n// caller keeps the `npx` form — slow beats broken.\n\nimport { existsSync, mkdirSync, cpSync, rmSync, renameSync, readdirSync } from \"node:fs\";\nimport { dirname, join, sep } from \"node:path\";\nimport { userHome } from \"./install.js\";\n\n/** Where pinned copies live: one directory per hook version. */\nexport function runtimeRoot(): string {\n  return join(userHome(), \"runtime\");\n}\n\nexport function runtimeDirFor(version: string): string {\n  return join(runtimeRoot(), version);\n}\n\n/** The CLI inside a pinned copy. */\nexport function pinnedCliPath(version: string): string {\n  return join(runtimeDirFor(version), \"node_modules\", \"@scopebond\", \"hook\", \"dist\", \"cli.js\");\n}\n\n/** True when a path sits in npm's throwaway `npx` cache, which npm may clear at any\n *  time. Anything else — a project `node_modules`, a global install, a pinned copy —\n *  is durable enough to reference from a config file. */\nexport function isEphemeralPath(file: string): boolean {\n  return `${sep}${file.replace(/[\\\\/]/g, sep)}${sep}`.includes(`${sep}_npx${sep}`);\n}\n\n/** Walk up from `dist/cli.js` to the `node_modules` directory that contains the whole\n *  materialised dependency tree (`node_modules/@scopebond/hook/dist/cli.js` → four up).\n *  Returns null if the layout is not what we expect, rather than copying the wrong thing. */\nexport function nodeModulesRootOf(cliFile: string): string | null {\n  let dir = dirname(cliFile); // .../dist\n  for (let i = 0; i < 6; i += 1) {\n    const parent = dirname(dir);\n    if (parent === dir) return null;\n    if (parent.endsWith(`${sep}node_modules`) || parent.endsWith(\"/node_modules\")) return parent;\n    dir = parent;\n  }\n  return null;\n}\n\n/** A pinned copy is usable only if the CLI and its sibling packages are all there —\n *  a half-copied tree would fail closed on every tool call. */\nfunction pinnedCopyIsComplete(version: string): boolean {\n  const cli = pinnedCliPath(version);\n  if (!existsSync(cli)) return false;\n  const scope = join(runtimeDirFor(version), \"node_modules\", \"@scopebond\");\n  try {\n    // The hook cannot run without the gateway and sdk it imports at startup.\n    const names = new Set(readdirSync(scope));\n    return names.has(\"hook\") && names.has(\"gateway\") && names.has(\"sdk\");\n  } catch { return false; }\n}\n\nexport interface PinResult {\n  /** The CLI path to pin, or null to keep the `npx` form. */\n  cli: string | null;\n  /** Why, in one phrase, for the line `init` prints. */\n  how: \"already-durable\" | \"pinned\" | \"reused\" | \"unavailable\";\n}\n\n/** Make sure a durable copy of this CLI exists and say which path to pin.\n *\n *  Never throws: every failure degrades to `{ cli: null }` so the caller falls back\n *  to `npx`, which is slower but always starts. */\nexport function ensureDurableRuntime(cliFile: string, version: string): PinResult {\n  try {\n    if (!existsSync(cliFile)) return { cli: null, how: \"unavailable\" };\n    // Already installed somewhere npm will not delete — pin it as it stands.\n    if (!isEphemeralPath(cliFile)) return { cli: cliFile, how: \"already-durable\" };\n    if (pinnedCopyIsComplete(version)) return { cli: pinnedCliPath(version), how: \"reused\" };\n    const source = nodeModulesRootOf(cliFile);\n    if (!source || !existsSync(source)) return { cli: null, how: \"unavailable\" };\n    const target = runtimeDirFor(version);\n    // Copy to a staging directory and move it into place, so an interrupted copy\n    // never leaves a partial tree that looks complete.\n    const staging = `${target}.incoming-${process.pid}`;\n    rmSync(staging, { recursive: true, force: true });\n    mkdirSync(staging, { recursive: true });\n    cpSync(source, join(staging, \"node_modules\"), { recursive: true, dereference: true });\n    rmSync(target, { recursive: true, force: true });\n    mkdirSync(dirname(target), { recursive: true });\n    renameSync(staging, target);\n    if (!pinnedCopyIsComplete(version)) {\n      rmSync(target, { recursive: true, force: true });\n      return { cli: null, how: \"unavailable\" };\n    }\n    return { cli: pinnedCliPath(version), how: \"pinned\" };\n  } catch {\n    return { cli: null, how: \"unavailable\" };\n  }\n}\n"]}

package/dist/runtime.d.ts

@@ -21,11 +21,18 @@ export interface RuntimeConfig {
 export interface Decision {
     decision: "allow" | "deny" | "not_evaluated";
     reason: string;
+    /** The clause that decided a deny, when the verdict named one. */
+    clauseId?: string | null;
     /** The deciding receipt (the denied one, or the first allow). */
     receipt?: unknown;
     /** Every receipt produced — one per simple command in a decomposed shell call. */
     receipts?: unknown[];
 }
+export declare const ci: (s: string) => string;
+export declare const under: (dir: string) => string;
+export declare const named: (file: string) => string;
+export declare const dir: (d: string) => string;
+export declare const DESTRUCTIVE: string[];
 /** Upgrade the starter-policy patterns an older hook wrote, in memory, so a user who
  *  installed an earlier version gets the current protections without re-running init.
  *  Only exact legacy strings are replaced; any other pattern is the operator's own. */
@@ -44,6 +51,12 @@ export declare function createHookRuntime(config: RuntimeConfig): {
     /** Deliver queued receipts to Cloud with a bounded timeout, then it is safe to
      *  exit. Undelivered receipts persist in the durable outbox for the next run. */
     flush(): Promise<void>;
+    /** Release the SQLite handles. The hook is a per-tool-call process, and a writer that
+     *  exits without closing leaves its write-ahead log on disk for the next process to
+     *  extend — measured at ~11 KiB of WAL per receipt against ~1.7 KiB when closed, so a
+     *  busy session was writing tens of megabytes of pure overhead into the user's project.
+     *  Always safe to call, and every exit path should. */
+    close(): void;
     /** Decide one mapped action, recording a receipt either way. */
     evaluateOne(mapped: Mapped): Promise<Decision>;
     /** Decide a whole tool call. A shell call decomposes into several simple

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAMA,OAAO,EAA6C,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/E,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf;;uFAEmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;sEACkE;IAClE,KAAK,CAAC,EAAE;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvF;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,eAAe,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB;AAoED;;uFAEuF;AACvF,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAQpD;AAED;;;0BAG0B;AAC1B,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgCvE;AAED;4EAC4E;AAC5E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa;;;;IAuBnD;qFACiF;aAClE,OAAO,CAAC,IAAI,CAAC;IAG5B,gEAAgE;wBACtC,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAapD;8EAC0E;qBACnD,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;EAkB/D"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAOA,OAAO,EAA6C,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAK/E,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf;;uFAEmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;sEACkE;IAClE,KAAK,CAAC,EAAE;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvF;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,eAAe,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB;AAWD,eAAO,MAAM,EAAE,GAAI,GAAG,MAAM,KAAG,MAAiF,CAAC;AACjH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,KAAG,MAAyC,CAAC;AAC9E,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,MAAoC,CAAC;AAC1E,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,MAAmC,CAAC;AA4BpE,eAAO,MAAM,WAAW,UAGvB,CAAC;AAuBF;;uFAEuF;AACvF,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAQpD;AAED;;;0BAG0B;AAC1B,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgCvE;AAED;4EAC4E;AAC5E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa;;;;IA8BnD;qFACiF;aAClE,OAAO,CAAC,IAAI,CAAC;IAG5B;;;;2DAIuD;aAC9C,IAAI;IAIb,gEAAgE;wBACtC,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IA+BpD;8EAC0E;qBACnD,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;EAkB/D"}

package/dist/runtime.js

@@ -2,11 +2,15 @@
 // machine key, policy and a durable local receipt log. Each mapped action is
 // signed by the machine key, decided against policy and countersigned — locally,
 // with no HTTP server and no Cloud dependency in 0.1.
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { createGateway, StaticPrincipalKeyRegistry } from "@scopebond/gateway";
 import { loadOrCreateAttester, openReceiptStore } from "@scopebond/gateway/node";
 import { createSigner } from "@scopebond/sdk";
 import { attachExporter, flushBounded } from "./cloud.js";
+import { explainDeny } from "./explain.js";
+import { RULES_FILE } from "./rules.js";
+import { cliCommand } from "./version.js";
 // The hook's own config and keys must be off-limits to the agent it governs:
 // otherwise the agent could rewrite its policy or read the signing keys and the
 // receipts stop meaning anything. These patterns are "allow if the path does NOT
@@ -16,10 +20,10 @@ import { attachExporter, flushBounded } from "./cloud.js";
 // Matching is case-insensitive — Windows and macOS open `.ENV` and `.env` as the
 // same file — by expanding each letter to a two-case class (policy patterns are
 // plain regular expressions with no flags). `ci()` is applied to literal text only.
-const ci = (s) => s.replace(/[A-Za-z]/g, (c) => `[${c.toLowerCase()}${c.toUpperCase()}]`);
-const under = (dir) => `(?!(?:.*/)?${ci(dir)}(?:/|$))`; // dir itself or anything inside it
-const named = (file) => `(?!(?:.*/)?${ci(file)}$)`; // exactly this file name
-const dir = (d) => `(?!(?:.*/)?${ci(d)}/?$)`; // the directory itself (a recursive read or copy)
+export const ci = (s) => s.replace(/[A-Za-z]/g, (c) => `[${c.toLowerCase()}${c.toUpperCase()}]`);
+export const under = (dir) => `(?!(?:.*/)?${ci(dir)}(?:/|$))`; // dir itself or anything inside it
+export const named = (file) => `(?!(?:.*/)?${ci(file)}$)`; // exactly this file name
+export const dir = (d) => `(?!(?:.*/)?${ci(d)}/?$)`; // the directory itself (a recursive read or copy)
 const PROTECTED_WRITE = "^" + [
     under("\\.scopebond"), `(?!(?:.*/)?${ci("\\.claude/settings")})`, under("\\.claude/hooks"), under("\\.claude/agents"),
     `(?!(?:.*/)?${ci("\\.cursor/hooks")})`, named("\\.codex/hooks\\.json"), named("\\.codex/config\\.toml"), named("\\.mcp\\.json"),
@@ -44,7 +48,7 @@ const PROTECTED_READ = "^" + [
 ].join("") + ".+";
 // Destructive programs, POSIX and Windows. The mapper records the program as typed,
 // so the pattern accepts any case and an executable suffix (`RM.exe`, `Remove-Item`).
-const DESTRUCTIVE = [
+export const DESTRUCTIVE = [
     "rm", "sudo", "doas", "shutdown", "reboot", "halt", "poweroff", "mkfs", "dd", "shred", "truncate", "unlink", "wipe", "srm",
     "del", "rd", "rmdir", "erase", "deltree", "format", "diskpart", "remove-item", "ri", "clear-content", "clc", "stop-computer", "restart-computer",
 ];
@@ -126,15 +130,22 @@ export function createHookRuntime(config) {
         { kid: agent.kid, publicKeyPem: agent.publicKeyPem, purposes: ["agent"], status: "active" },
     ]);
     const { attester } = loadOrCreateAttester({ file: config.attesterPath });
+    // When the project has a readable rule set, a denial names the command that edits it
+    // rather than the generated file.
+    const rulesRemedy = existsSync(join(dirname(config.policyPath), RULES_FILE))
+        ? `run \`${cliCommand("rules")}\` to see the limits in plain terms, or edit ${join(dirname(config.policyPath), RULES_FILE)}`
+        : undefined;
     const { store: baseStore } = openReceiptStore({ db: config.dbPath });
     // When connected, mirror every stored receipt to the hosted portal through a
     // durable outbox. The wrapped store's decision is unchanged; export is best-effort.
     let store = baseStore;
     let exporter;
+    let outbox;
     if (config.cloud) {
         const attached = attachExporter(config.dbPath + ".cloud-outbox.db", config.cloud.connection, baseStore, config.cloud.fetch);
         store = attached.store;
         exporter = attached.exporter;
+        outbox = attached.outbox;
     }
     const gateway = createGateway({ policy, authentication: { keys }, attester, store, mode: "check_only" });
     return {
@@ -147,6 +158,21 @@ export function createHookRuntime(config) {
             if (exporter)
                 await flushBounded(exporter, config.cloud?.flushTimeoutMs);
         },
+        /** Release the SQLite handles. The hook is a per-tool-call process, and a writer that
+         *  exits without closing leaves its write-ahead log on disk for the next process to
+         *  extend — measured at ~11 KiB of WAL per receipt against ~1.7 KiB when closed, so a
+         *  busy session was writing tens of megabytes of pure overhead into the user's project.
+         *  Always safe to call, and every exit path should. */
+        close() {
+            try {
+                baseStore.close?.();
+            }
+            catch { /* the decision is already recorded */ }
+            try {
+                outbox?.close();
+            }
+            catch { /* best effort */ }
+        },
         /** Decide one mapped action, recording a receipt either way. */
         async evaluateOne(mapped) {
             const signed = agent.sign(mapped.intent);
@@ -159,7 +185,26 @@ export function createHookRuntime(config) {
             // Evaluated actions, and (in strict mode) unmapped tool.<name>/opaque commands,
             // go through policy — a closed allowlist denies an unlisted action.
             const result = await gateway.handleAction({ intent: signed.intent, authorization: signed.authorization });
-            return { decision: result.allowed ? "allow" : "deny", reason: result.reason, receipt: result.receipt };
+            if (result.allowed)
+                return { decision: "allow", reason: result.reason, receipt: result.receipt };
+            // A deny is the one message the user and their agent actually read, so it is
+            // composed from the deciding clause's own words rather than the engine's
+            // internal reason ("param ref fails pattern").
+            const clauseId = result.verdict?.clause_id ?? null;
+            return {
+                decision: "deny",
+                reason: explainDeny({
+                    policy, clauseId, detail: result.reason,
+                    intent: signed.intent, policyPath: config.policyPath,
+                    postHoc: mapped.postHoc,
+                    // Point at the editable surface when there is one. `policy.json` is compiled
+                    // from `rules.json`, so telling someone to hand-edit it invites a change the
+                    // next `rules` run would overwrite.
+                    remedy: rulesRemedy,
+                }),
+                clauseId,
+                receipt: result.receipt,
+            };
         },
         /** Decide a whole tool call. A shell call decomposes into several simple
          *  commands; every one is recorded, and a single deny denies the call. */