@nebutra/agent-runtime 0.2.0

package/src/permission-ruleset.test.ts

@@ -0,0 +1,301 @@
+import { describe, expect, it } from "vitest";
+import {
+  type Action,
+  BUILTIN_ARITY,
+  commandPermissionKey,
+  commandPrefix,
+  evaluate,
+  type Rule,
+  type Ruleset,
+  wildcardMatch,
+} from "./permission-ruleset.js";
+
+describe("wildcardMatch — anchored full-string glob", () => {
+  it("matches literal strings exactly", () => {
+    expect(wildcardMatch("git", "git")).toBe(true);
+    expect(wildcardMatch("git", "npm")).toBe(false);
+  });
+
+  it("is anchored (no partial matches)", () => {
+    expect(wildcardMatch("git status", "git")).toBe(false);
+    expect(wildcardMatch("agit", "git")).toBe(false);
+    expect(wildcardMatch("gitx", "git")).toBe(false);
+  });
+
+  it("treats * as any run including empty", () => {
+    expect(wildcardMatch("", "*")).toBe(true);
+    expect(wildcardMatch("anything at all", "*")).toBe(true);
+    expect(wildcardMatch("abc", "a*c")).toBe(true);
+    expect(wildcardMatch("ac", "a*c")).toBe(true);
+    expect(wildcardMatch("abbbbc", "a*c")).toBe(true);
+    expect(wildcardMatch("abd", "a*c")).toBe(false);
+  });
+
+  it("treats ? as exactly one char", () => {
+    expect(wildcardMatch("a", "?")).toBe(true);
+    expect(wildcardMatch("", "?")).toBe(false);
+    expect(wildcardMatch("ab", "?")).toBe(false);
+    expect(wildcardMatch("abc", "a?c")).toBe(true);
+    expect(wildcardMatch("ac", "a?c")).toBe(false);
+  });
+
+  it("combines * and ? together", () => {
+    expect(wildcardMatch("file.test.ts", "*.ts")).toBe(true);
+    // `*` swallows "file.test", then ".t" + one `?` (= "s") consumes ".ts"
+    expect(wildcardMatch("file.test.ts", "*.t?")).toBe(true);
+    // ".t??" needs two trailing chars after ".t" — only one ("s") remains
+    expect(wildcardMatch("file.test.ts", "*.t??")).toBe(false);
+    expect(wildcardMatch("file.test.tsx", "*.t??")).toBe(true);
+  });
+
+  it("treats regex metacharacters in the pattern as literals", () => {
+    expect(wildcardMatch("a.b", "a.b")).toBe(true);
+    expect(wildcardMatch("axb", "a.b")).toBe(false);
+    expect(wildcardMatch("a+b", "a+b")).toBe(true);
+    expect(wildcardMatch("(x)", "(x)")).toBe(true);
+    expect(wildcardMatch("a$b^", "a$b^")).toBe(true);
+    expect(wildcardMatch("a[b]c", "a[b]c")).toBe(true);
+  });
+
+  it("empty pattern matches only empty string", () => {
+    expect(wildcardMatch("", "")).toBe(true);
+    expect(wildcardMatch("x", "")).toBe(false);
+  });
+
+  describe("SPECIAL RULE — trailing ' *' is optional", () => {
+    it('pattern "git *" matches the head-only "git"', () => {
+      expect(wildcardMatch("git", "git *")).toBe(true);
+    });
+
+    it('pattern "git *" matches "git <rest>"', () => {
+      expect(wildcardMatch("git status", "git *")).toBe(true);
+      expect(wildcardMatch("git commit -m x", "git *")).toBe(true);
+    });
+
+    it('pattern "git *" still requires the head prefix', () => {
+      expect(wildcardMatch("npm", "git *")).toBe(false);
+      expect(wildcardMatch("gitx", "git *")).toBe(false);
+      expect(wildcardMatch("", "git *")).toBe(false);
+    });
+
+    it("the space before * is required for the optional rule (the space is consumed)", () => {
+      // "git " (head + trailing space, nothing after) does NOT match the
+      // head-only branch (which is exactly "git"), but matches via "git " + empty *
+      expect(wildcardMatch("git ", "git *")).toBe(true);
+      expect(wildcardMatch("git", "git *")).toBe(true);
+    });
+
+    it('multi-token head before " *"', () => {
+      expect(wildcardMatch("npm run", "npm run *")).toBe(true);
+      expect(wildcardMatch("npm run dev", "npm run *")).toBe(true);
+      expect(wildcardMatch("npm", "npm run *")).toBe(false);
+    });
+
+    it('a bare "*" pattern is not treated as the optional-suffix rule', () => {
+      expect(wildcardMatch("", "*")).toBe(true);
+      expect(wildcardMatch("x", "*")).toBe(true);
+    });
+  });
+
+  it("handles adversarial patterns with many wildcards without catastrophic backtracking", () => {
+    const pattern = "*".repeat(30);
+    const subject = "a".repeat(200);
+    const start = Date.now();
+    expect(wildcardMatch(subject, pattern)).toBe(true);
+    expect(wildcardMatch("", pattern)).toBe(true);
+    // a near-worst-case alternation that would explode under naive regex backtracking
+    const mixed = `${"*a".repeat(30)}*`;
+    expect(wildcardMatch(`${"a".repeat(100)}`, mixed)).toBe(true);
+    expect(wildcardMatch(`${"b".repeat(100)}`, mixed)).toBe(false);
+    expect(Date.now() - start).toBeLessThan(500);
+  });
+
+  it("is deterministic across repeated calls", () => {
+    for (let i = 0; i < 50; i++) {
+      expect(wildcardMatch("git push origin main", "git *")).toBe(true);
+      expect(wildcardMatch("rm -rf /", "git *")).toBe(false);
+    }
+  });
+});
+
+describe("evaluate — two-dimensional first-match wildcard resolution", () => {
+  const allowGitRead: Rule = { permission: "bash", pattern: "git status", action: "allow" };
+  const denyRm: Rule = { permission: "bash", pattern: "rm *", action: "deny" };
+  const askGit: Rule = { permission: "bash", pattern: "git *", action: "ask" };
+
+  it("returns the first matching rule (order matters)", () => {
+    const set: Ruleset = [allowGitRead, askGit, denyRm];
+    const r = evaluate("bash", "git status", set);
+    expect(r).toEqual(allowGitRead);
+  });
+
+  it("falls through to the next rule when the first does not match", () => {
+    const set: Ruleset = [allowGitRead, askGit];
+    const r = evaluate("bash", "git push", set);
+    expect(r).toEqual(askGit);
+  });
+
+  it("requires BOTH permission AND pattern to match (two-dimensional)", () => {
+    const set: Ruleset = [{ permission: "edit", pattern: "git *", action: "allow" }];
+    // pattern matches but permission does not -> no match -> default ask
+    const r = evaluate("bash", "git status", set);
+    expect(r).toEqual({ permission: "bash", pattern: "*", action: "ask" });
+  });
+
+  it("supports wildcard permissions", () => {
+    const set: Ruleset = [{ permission: "*", pattern: "git *", action: "allow" }];
+    expect(evaluate("bash", "git status", set).action).toBe("allow");
+    expect(evaluate("edit", "git status", set).action).toBe("allow");
+  });
+
+  it("concatenates multiple rulesets in argument order", () => {
+    const base: Ruleset = [{ permission: "bash", pattern: "*", action: "ask" }];
+    const overrides: Ruleset = [{ permission: "bash", pattern: "git *", action: "allow" }];
+    // base comes first -> its catch-all wins over the later override
+    expect(evaluate("bash", "git status", base, overrides).action).toBe("ask");
+    // reversed order -> the specific allow is reached first
+    expect(evaluate("bash", "git status", overrides, base).action).toBe("allow");
+  });
+
+  it("returns the fail-safe default (ask) when nothing matches", () => {
+    const r = evaluate("bash", "curl http://evil", []);
+    expect(r).toEqual({ permission: "bash", pattern: "*", action: "ask" });
+  });
+
+  it("default carries the queried permission and pattern verbatim", () => {
+    const r = evaluate("net", "https://example.com/x", [
+      { permission: "bash", pattern: "*", action: "allow" },
+    ]);
+    expect(r.permission).toBe("net");
+    expect(r.pattern).toBe("*");
+    expect(r.action).toBe("ask");
+  });
+
+  it("does not mutate the input rulesets", () => {
+    const a: Ruleset = [{ permission: "bash", pattern: "git *", action: "allow" }];
+    const b: Ruleset = [{ permission: "bash", pattern: "*", action: "deny" }];
+    const aSnap = JSON.stringify(a);
+    const bSnap = JSON.stringify(b);
+    evaluate("bash", "git status", a, b);
+    evaluate("bash", "rm -rf", a, b);
+    expect(JSON.stringify(a)).toBe(aSnap);
+    expect(JSON.stringify(b)).toBe(bSnap);
+    expect(a.length).toBe(1);
+    expect(b.length).toBe(1);
+  });
+
+  it("is deterministic", () => {
+    const set: Ruleset = [askGit, denyRm];
+    for (let i = 0; i < 25; i++) {
+      expect(evaluate("bash", "git pull", set).action).toBe("ask");
+      expect(evaluate("bash", "rm x", set).action).toBe("deny");
+    }
+  });
+
+  it("Action type accepts the three documented values", () => {
+    const actions: Action[] = ["allow", "deny", "ask"];
+    expect(actions).toHaveLength(3);
+  });
+});
+
+describe("commandPrefix — longest-prefix-wins extraction", () => {
+  it("uses the built-in arity for git (2)", () => {
+    expect(commandPrefix(["git", "checkout", "main"])).toEqual(["git", "checkout"]);
+    expect(commandPrefix(["git", "status"])).toEqual(["git", "status"]);
+  });
+
+  it("prefers the longest matching prefix (npm run = 3 over npm = 2)", () => {
+    expect(commandPrefix(["npm", "run", "dev"])).toEqual(["npm", "run", "dev"]);
+    expect(commandPrefix(["npm", "install", "left-pad"])).toEqual(["npm", "install"]);
+  });
+
+  it("falls back to the first token for unknown commands", () => {
+    expect(commandPrefix(["foobar", "a", "b", "c"])).toEqual(["foobar"]);
+  });
+
+  it("returns an empty array for empty tokens", () => {
+    expect(commandPrefix([])).toEqual([]);
+  });
+
+  it("clamps the slice when arity exceeds the token count", () => {
+    expect(commandPrefix(["git"])).toEqual(["git"]);
+  });
+
+  it("respects single-arity commands", () => {
+    expect(commandPrefix(["ls", "-la", "src"])).toEqual(["ls"]);
+    expect(commandPrefix(["cat", "file.ts"])).toEqual(["cat"]);
+    expect(commandPrefix(["rm", "x", "y"])).toEqual(["rm"]);
+  });
+
+  it("merges a caller-supplied arity over the built-in table", () => {
+    expect(commandPrefix(["git", "checkout", "main"], { git: 1 })).toEqual(["git"]);
+    // extend with a new command
+    expect(commandPrefix(["terraform", "apply", "-auto"], { terraform: 2 })).toEqual([
+      "terraform",
+      "apply",
+    ]);
+    // a multi-word override
+    expect(commandPrefix(["pnpm", "dlx", "create-x", "y"], { "pnpm dlx": 3 })).toEqual([
+      "pnpm",
+      "dlx",
+      "create-x",
+    ]);
+  });
+
+  it("does not mutate the caller arity or the built-in table", () => {
+    const override = { git: 1 };
+    const snap = JSON.stringify(override);
+    const builtinSnap = JSON.stringify(BUILTIN_ARITY);
+    commandPrefix(["git", "a", "b"], override);
+    expect(JSON.stringify(override)).toBe(snap);
+    expect(JSON.stringify(BUILTIN_ARITY)).toBe(builtinSnap);
+  });
+
+  it("is deterministic", () => {
+    for (let i = 0; i < 25; i++) {
+      expect(commandPrefix(["docker", "compose", "up"])).toEqual(["docker", "compose"]);
+    }
+  });
+});
+
+describe("commandPermissionKey — flag-stripped prefix key", () => {
+  it("strips dash-prefixed tokens then applies the prefix", () => {
+    // Faithful model: tokens starting with "-" are dropped wholesale. There
+    // is no flag-argument awareness, so non-dash operands survive.
+    expect(commandPermissionKey("git --no-pager commit -m x")).toBe("git commit");
+    // "." is not a flag, so it survives and fills the git:2 slot.
+    expect(commandPermissionKey("git -C . commit -m x")).toBe("git .");
+  });
+
+  it("derives a simple key for unknown commands (first token)", () => {
+    expect(commandPermissionKey("curl -sSL https://example.com")).toBe("curl");
+  });
+
+  it("handles npm run with flags interleaved", () => {
+    expect(commandPermissionKey("npm --silent run build --prod")).toBe("npm run build");
+  });
+
+  it("collapses arbitrary whitespace between tokens", () => {
+    expect(commandPermissionKey("git   checkout\tmain")).toBe("git checkout");
+  });
+
+  it("returns an empty string for an empty/whitespace command", () => {
+    expect(commandPermissionKey("")).toBe("");
+    expect(commandPermissionKey("   ")).toBe("");
+    expect(commandPermissionKey("--only --flags")).toBe("");
+  });
+
+  it("feeds cleanly into evaluate as the pattern dimension", () => {
+    const set: Ruleset = [{ permission: "bash", pattern: "git commit", action: "ask" }];
+    const key = commandPermissionKey("git -C /repo commit -m 'msg'");
+    expect(evaluate("bash", key, set).action).toBe("ask");
+  });
+
+  it("is deterministic", () => {
+    for (let i = 0; i < 25; i++) {
+      // No flag-argument awareness: "-n" is dropped, "ns" survives and fills
+      // the kubectl:2 slot, yielding a stable "kubectl ns".
+      expect(commandPermissionKey("kubectl -n ns get pods")).toBe("kubectl ns");
+    }
+  });
+});

package/src/permission-ruleset.ts

@@ -0,0 +1,200 @@
+/**
+ * Permission ruleset evaluator.
+ *
+ * A small, pure, stateless re-expression of a two-dimensional wildcard
+ * permission model plus a bash-command-prefix extractor. No global state,
+ * no I/O, no mutation of inputs — every function is referentially transparent.
+ *
+ * The model has two independent dimensions per rule:
+ *   - `permission` — the capability namespace (e.g. "bash", "edit", "net")
+ *   - `pattern`    — the concrete subject within that namespace
+ * A rule applies only when BOTH dimensions match the query via {@link wildcardMatch}.
+ */
+
+/** The decision a rule yields. Unknown queries fail safe to "ask". */
+export type Action = "allow" | "deny" | "ask";
+
+/** A single permission rule. Both dimensions are matched as wildcard globs. */
+export interface Rule {
+  permission: string;
+  pattern: string;
+  action: Action;
+}
+
+/** An ordered list of rules. Earlier rules take precedence. */
+export type Ruleset = Rule[];
+
+/**
+ * Anchored full-string glob matcher.
+ *
+ * Semantics:
+ *   - `*` matches any run of characters, including the empty run.
+ *   - `?` matches exactly one character.
+ *   - Every other character is matched literally (regex metacharacters in
+ *     `pattern` carry no special meaning).
+ *   - The match is anchored: the entire `str` must be consumed.
+ *
+ * Special rule (ported faithfully): if `pattern` ends with `" *"` (a single
+ * space immediately followed by `*`), that trailing ` *` is OPTIONAL. The
+ * pattern then matches both `"<head> <rest>"` and exactly `"<head>"` with
+ * nothing after it. For example `"git *"` matches `"git"` and `"git status"`.
+ *
+ * Implemented with a backtracking two-pointer scan whose `*` handling uses a
+ * single saved restart position, giving O(|str| * |pattern|) worst case with
+ * no catastrophic blow-up.
+ */
+export function wildcardMatch(str: string, pattern: string): boolean {
+  if (isOptionalTrailingStar(pattern)) {
+    const head = pattern.slice(0, -2); // drop the trailing " *"
+    // Head-only branch: the whole string equals the head, matched as a glob.
+    if (globMatch(str, head)) {
+      return true;
+    }
+    // Otherwise the full "<head> *" pattern must match (space is consumed).
+    return globMatch(str, pattern);
+  }
+  return globMatch(str, pattern);
+}
+
+/**
+ * True when `pattern` ends in a literal space followed by `*`, and that `*`
+ * is the final character. A bare `"*"` (no preceding space) is NOT treated
+ * as the optional-suffix form.
+ */
+function isOptionalTrailingStar(pattern: string): boolean {
+  return pattern.length >= 2 && pattern.endsWith(" *");
+}
+
+/**
+ * Core anchored glob match using linear-time backtracking. Only `*` can
+ * backtrack, and it uses a single restart marker (the classic two-pointer
+ * algorithm), so there is no exponential backtracking.
+ */
+function globMatch(str: string, pattern: string): boolean {
+  let s = 0;
+  let p = 0;
+  let starP = -1;
+  let starS = 0;
+
+  while (s < str.length) {
+    const pc = p < pattern.length ? pattern[p] : undefined;
+    if (pc === "*") {
+      // Record the restart point and tentatively consume zero chars.
+      starP = p;
+      starS = s;
+      p += 1;
+    } else if (pc === "?" || pc === str[s]) {
+      p += 1;
+      s += 1;
+    } else if (starP !== -1) {
+      // Backtrack: let the last `*` swallow one more character.
+      p = starP + 1;
+      starS += 1;
+      s = starS;
+    } else {
+      return false;
+    }
+  }
+
+  // Consume any trailing `*` segments in the pattern.
+  while (p < pattern.length && pattern[p] === "*") {
+    p += 1;
+  }
+
+  return p === pattern.length;
+}
+
+/**
+ * Resolve a permission query against one or more rulesets.
+ *
+ * Rulesets are concatenated in argument order (no mutation) and scanned
+ * front-to-back. The FIRST rule whose `permission` and `pattern` both match
+ * the query (via {@link wildcardMatch}) is returned. If no rule matches, a
+ * fail-safe default is returned: the queried permission/pattern with action
+ * `"ask"` (unknown → ask, never silently allow).
+ */
+export function evaluate(permission: string, pattern: string, ...rulesets: Ruleset[]): Rule {
+  for (const ruleset of rulesets) {
+    for (const rule of ruleset) {
+      if (wildcardMatch(permission, rule.permission) && wildcardMatch(pattern, rule.pattern)) {
+        return rule;
+      }
+    }
+  }
+  return { permission, pattern: "*", action: "ask" };
+}
+
+/**
+ * Built-in command arity table. Maps a (possibly multi-word) command prefix
+ * to the number of leading tokens that constitute its "human-understandable
+ * command" for permission matching. Longest matching prefix wins.
+ *
+ * Frozen so the shared default cannot be mutated by callers.
+ */
+export const BUILTIN_ARITY: Readonly<Record<string, number>> = Object.freeze({
+  git: 2,
+  npm: 2,
+  "npm run": 3,
+  docker: 2,
+  kubectl: 2,
+  cargo: 2,
+  pnpm: 2,
+  yarn: 2,
+  go: 2,
+  ls: 1,
+  cat: 1,
+  cd: 1,
+  rm: 1,
+  cp: 1,
+  mv: 1,
+  mkdir: 1,
+  echo: 1,
+  grep: 1,
+  python: 1,
+  node: 1,
+});
+
+/**
+ * Extract the human-understandable command from already-split, flag-free
+ * shell tokens.
+ *
+ * Strategy: try the longest prefix first. For `len` from `tokens.length` down
+ * to 1, if `tokens.slice(0, len).join(" ")` is a key in the (merged) arity
+ * table, return `tokens.slice(0, arity[thatPrefix])`. If the tokens are empty,
+ * return `[]`. Otherwise default to the first token only.
+ *
+ * `arity` is shallow-merged OVER the built-in table; neither the caller's
+ * object nor the built-in table is mutated.
+ */
+export function commandPrefix(
+  tokens: string[],
+  arity?: Record<string, number> | undefined,
+): string[] {
+  if (tokens.length === 0) {
+    return [];
+  }
+  const table: Record<string, number> = { ...BUILTIN_ARITY, ...(arity ?? {}) };
+
+  for (let len = tokens.length; len >= 1; len -= 1) {
+    const prefixKey = tokens.slice(0, len).join(" ");
+    const take = table[prefixKey];
+    if (take !== undefined) {
+      // Clamp to the available token count; never expand beyond the input.
+      return tokens.slice(0, Math.min(take, tokens.length));
+    }
+  }
+
+  return tokens.slice(0, 1);
+}
+
+/**
+ * Derive the `pattern` to feed {@link evaluate} for a bash permission.
+ *
+ * Splits `command` on arbitrary whitespace, drops tokens that begin with `-`
+ * (flags are not conceptually part of the command identity), applies
+ * {@link commandPrefix}, and joins the result with single spaces.
+ */
+export function commandPermissionKey(command: string): string {
+  const tokens = command.split(/\s+/).filter((token) => token.length > 0 && !token.startsWith("-"));
+  return commandPrefix(tokens).join(" ");
+}

package/src/policy.ts

@@ -0,0 +1,151 @@
+/**
+ * Approval + capability policy (WRAP — capability #8).
+ *
+ * Faithful re-expression of the upstream two orthogonal axes:
+ *   1. Approval policy  — *when* to ask a human (AskForApproval).
+ *   2. Capability policy — *what* an external executor is permitted to do
+ *      (SandboxPolicy). Policy/semantics only; enforcement is out of scope
+ *      and lives behind the external-sandbox seam (see ./sandbox).
+ *
+ * Plus the static rule decision (execpolicy `Decision`) and the human's rich
+ * answer (`ReviewDecision`). Built on `@nebutra/permissions` for *who may
+ * approve*; this module models *what tier / what answer*.
+ */
+
+import { z } from "zod";
+
+// ── Axis 1: approval policy ──────────────────────────────────────────────────
+
+/** Fine-grained per-category gates. `false` = auto-reject (not auto-ask). */
+export const granularApprovalConfigSchema = z.object({
+  sandboxApproval: z.boolean(),
+  rules: z.boolean(),
+  skillApproval: z.boolean().default(false),
+  requestPermissions: z.boolean().default(false),
+  mcpElicitations: z.boolean(),
+});
+export type GranularApprovalConfig = z.infer<typeof granularApprovalConfigSchema>;
+
+/**
+ * Approval tier.
+ *  - `unless_trusted` : only known-safe read-only ops auto-approved; else ask.
+ *  - `on_failure`     : DEPRECATED — auto-run sandboxed, escalate on failure.
+ *  - `on_request`     : the model decides when to ask (default).
+ *  - `granular`       : per-category booleans.
+ *  - `never`          : failures returned to the model, never escalated.
+ */
+export const approvalPolicySchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("unless_trusted") }),
+  z.object({ kind: z.literal("on_failure") }),
+  z.object({ kind: z.literal("on_request") }),
+  z.object({ kind: z.literal("granular"), config: granularApprovalConfigSchema }),
+  z.object({ kind: z.literal("never") }),
+]);
+export type ApprovalPolicy = z.infer<typeof approvalPolicySchema>;
+
+export const DEFAULT_APPROVAL_POLICY: ApprovalPolicy = { kind: "on_request" };
+
+// ── Axis 2: capability policy ────────────────────────────────────────────────
+
+/** A writable root with read-only sub-paths and escalation-protected names. */
+export const writableRootSchema = z.object({
+  root: z.string(),
+  readOnlySubpaths: z.array(z.string()).default([]),
+  /** Names that must never be writable even under this root (e.g. ".git/hooks"). */
+  protectedMetadataNames: z.array(z.string()).default([]),
+});
+export type WritableRoot = z.infer<typeof writableRootSchema>;
+
+/**
+ * Capability policy — a vocabulary of *capabilities*, not OS mechanisms.
+ * Per the dual-track governance decision, `external_sandbox` is the default
+ * posture: this runtime never enforces isolation itself.
+ */
+export const capabilityPolicySchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("danger_full_access") }),
+  z.object({ kind: z.literal("read_only"), networkAccess: z.boolean().default(false) }),
+  z.object({
+    kind: z.literal("external_sandbox"),
+    networkAccess: z.boolean().default(false),
+  }),
+  z.object({
+    kind: z.literal("workspace_write"),
+    writableRoots: z.array(writableRootSchema).default([]),
+    networkAccess: z.boolean().default(false),
+    excludeTmpdir: z.boolean().default(false),
+    excludeSlashTmp: z.boolean().default(false),
+  }),
+]);
+export type CapabilityPolicy = z.infer<typeof capabilityPolicySchema>;
+
+/** Default posture for a multi-tenant web runtime (governance: ExternalSandbox). */
+export const DEFAULT_CAPABILITY_POLICY: CapabilityPolicy = {
+  kind: "external_sandbox",
+  networkAccess: false,
+};
+
+// ── Static rule decision (policy-as-data evaluator output) ────────────────────
+
+/** Classification of a command *before* approval. */
+export type RuleDecision = "allow" | "prompt" | "forbidden";
+
+// ── The human's answer ───────────────────────────────────────────────────────
+
+/** A session-scoped amendment that remembers an allowed command prefix. */
+export interface RuleAmendment {
+  readonly allowPrefix: readonly string[];
+}
+
+/** Persist allow/deny for future requests to the same host. */
+export interface NetworkPolicyAmendment {
+  readonly host: string;
+  readonly effect: "allow" | "deny";
+}
+
+/**
+ * The reviewer's rich answer. Mirrors upstream `ReviewDecision`; `denied`
+ * is the safe default.
+ */
+export type ReviewDecision =
+  | { readonly kind: "approved" }
+  | { readonly kind: "approved_rule_amendment"; readonly amendment: RuleAmendment }
+  | { readonly kind: "approved_for_session" }
+  | { readonly kind: "network_policy_amendment"; readonly amendment: NetworkPolicyAmendment }
+  | { readonly kind: "denied" }
+  | { readonly kind: "timed_out" }
+  | { readonly kind: "abort" };
+
+export const DENIED: ReviewDecision = { kind: "denied" };
+
+/** Whether a decision permits the action to proceed. */
+export function isApproval(decision: ReviewDecision): boolean {
+  return (
+    decision.kind === "approved" ||
+    decision.kind === "approved_rule_amendment" ||
+    decision.kind === "approved_for_session"
+  );
+}
+
+/**
+ * Resolve a static rule decision against an approval policy into whether the
+ * action proceeds without a human, must be asked, or is auto-rejected.
+ * Pure; the actual prompting/escalation transport lives in ./protocol.
+ */
+export function resolveRuleDecision(
+  rule: RuleDecision,
+  policy: ApprovalPolicy,
+): "auto_allow" | "ask_human" | "auto_reject" {
+  if (rule === "forbidden") return "auto_reject";
+  if (rule === "allow") return "auto_allow";
+  // rule === "prompt"
+  switch (policy.kind) {
+    case "never":
+      return "auto_reject";
+    case "unless_trusted":
+    case "on_request":
+    case "on_failure":
+      return "ask_human";
+    case "granular":
+      return policy.config.rules ? "ask_human" : "auto_reject";
+  }
+}