pi-daddy 0.28.0 → 0.32.0

package/src/kernel/propagation.ts

@@ -0,0 +1,341 @@
+/**
+ * Race-free grant propagation.
+ *
+ * The first implementation wrote each child's computed grant into `process.env` inside the `tool_call`
+ * handler. The environment is process-global, so two concurrent spawns could read each other's values —
+ * a real hole in a security control.
+ *
+ * The fix removes the need for a per-child channel entirely, rather than trying to build one:
+ *
+ *   1. Everything pushed to children is a property of the PARENT, not of the individual spawn — the
+ *      parent's own grant, the child depth (parent depth + 1), and the configured bounds. Those are
+ *      identical for every sibling, so concurrent spawns cannot disagree and there is nothing to race.
+ *      `ENV_APPROVED` (approvals a human granted at or above this level) is safe on the same global
+ *      channel for the same reason: it is intersected with the parent's own grant before being written,
+ *      which is itself a parent-level fact, so it too is identical for every sibling.
+ *   2. Each child derives ITS OWN grant on arrival: `inheritedParentGrant ∩ ownObservedTools`, where the
+ *      observed set comes from the `tools` array of its first provider request — authoritative, because
+ *      it is literally what pi sent the model.
+ *
+ * The environment is therefore written ONCE per session, before any spawn can occur (the first provider
+ * request precedes any tool call), and never mutated per spawn.
+ *
+ * The invariant still holds transitively: own = observed ∩ inheritedParent ⊆ inheritedParent, so no
+ * descendant can exceed the root. It is also defence in depth — even if a spawn slipped past the
+ * interceptor and pi handed the child more than the parent held, the intersection clamps it back.
+ */
+
+import type { Capability } from "./resolve.ts";
+import { WILDCARD } from "./pi-tools.ts";
+import { WORKSPACE_WILDCARD } from "./resolve.ts";
+import { inheritApprovals, type InheritableApproval } from "./approval.ts";
+import { assertCapabilitiesArePropagatable } from "./capabilities.ts";
+import {
+  ENV_GRANT,
+  ENV_FANOUT,
+  ENV_PARENT_ID,
+  ENV_EXECUTION_ID,
+  ENV_DEPTH,
+  ENV_MAX_DEPTH,
+  ENV_GATED,
+  ENV_LEDGER,
+  ENV_APPROVED,
+} from "./env-names.ts";
+export {
+  ENV_GRANT,
+  ENV_FANOUT,
+  ENV_PARENT_ID,
+  ENV_EXECUTION_ID,
+  ENV_DEPTH,
+  ENV_MAX_DEPTH,
+  ENV_GATED,
+  ENV_LEDGER,
+  ENV_APPROVED,
+} from "./env-names.ts";
+
+/**
+ * Total descendants this session may create in its whole subtree (`src/kernel/fanout.ts`).
+ *
+ * In `GRANT_ENV_KEYS` and therefore stripped from a child's environment and re-supplied only by the spawn
+ * plan — like depth, and for the same reason: it is capability state that must ATTENUATE downward, not an
+ * operator preference that should inherit. `PI_DADDY_CHILD_TIMEOUT` is deliberately the other kind.
+ */
+/**
+ * This session's ledger id, so a child's records name their real parent (review finding F8).
+ *
+ * Without it every level restarts at `d0` and the ledger cannot be joined into a tree across processes.
+ */
+/** Unique identity of this governed execution occurrence; unlike ENV_PARENT_ID it is never reused. */
+
+/**
+ * Every variable this package uses to push governance state at a child.
+ *
+ * Named as a set so `mergeChildEnv` can guarantee that none of them survives from the parent's own
+ * environment into a child's — a governance variable a child inherits by accident is one nobody decided
+ * to give it.
+ */
+export const GRANT_ENV_KEYS = [
+  ENV_GRANT,
+  ENV_DEPTH,
+  ENV_MAX_DEPTH,
+  ENV_GATED,
+  ENV_LEDGER,
+  ENV_APPROVED,
+  ENV_FANOUT,
+  ENV_PARENT_ID,
+  ENV_EXECUTION_ID,
+] as const;
+
+export const parseList = (raw: string | undefined): Capability[] =>
+  (raw ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+/** Does a bare pi tool name correspond to this capability? `read` matches `tool:read` and `ext:pkg/read`. */
+function matchesToolName(capability: Capability, toolName: string): boolean {
+  if (capability === `tool:${toolName}`) return true;
+  return capability.startsWith("ext:") && capability.slice(capability.lastIndexOf("/") + 1) === toolName;
+}
+
+/**
+ * Is this capability something an observed tool array can speak about at all? (R-36, ADR-0017 step 1.)
+ *
+ * `tool:` and `ext:` name tools, so a tool array that omits one is evidence the session does not have it.
+ * `skill:` and `agent:` name a loadable instruction file and a spawnable definition — neither is ever a
+ * tool, so an observation says **nothing** about them and must not be read as evidence of absence.
+ */
+const isToolCapability = (capability: Capability): boolean =>
+  capability.startsWith("tool:") || capability.startsWith("ext:");
+
+/**
+ * Derive this session's own grant from what it inherited and what pi actually gave it.
+ *
+ * `observedTools` is the bare tool-name list from the session's own provider payload, or null when it
+ * has not been observed yet — in which case the inherited grant is used unchanged (it is already an
+ * upper bound, so this is safe, just less tight).
+ *
+ * A wildcard holder stays a wildcard holder: an enumerated observation must not silently downgrade an
+ * explicitly unlimited grant, or a root session would lose the authority it was configured with.
+ *
+ * **R-36 / ADR-0017 step 1: only tool-shaped capabilities are filtered.** The observation is a list of
+ * TOOLS, so it is evidence about `tool:` and `ext:` and about nothing else. Until this was fixed, a child
+ * inheriting `tool:read, skill:review` held only `tool:read` from its first provider request onward — it
+ * still *had* the skill (it arrives as `--skill`), but could not re-grant it and `/grants` stopped listing
+ * it. Silently, and in the narrowing direction, which is why it survived: nothing fails when a grant
+ * quietly shrinks. It also made ADR-0017's `agent:` prerequisite unsatisfiable below the root.
+ */
+export function deriveOwnGrant(inheritedParentGrant: Capability[], observedTools: string[] | null): Capability[] {
+  if (observedTools === null) return [...inheritedParentGrant];
+  // Capabilities an observation cannot speak about ride through both branches untouched.
+  const nonTool = inheritedParentGrant.filter((c) => !isToolCapability(c) && c !== WILDCARD);
+  if (inheritedParentGrant.includes(WILDCARD)) {
+    // Keep the wildcard, and additionally enumerate what was observed so descendants can be checked
+    // against concrete names too.
+    const enumerated = observedTools.map((t) => `tool:${t}`);
+    return [...new Set([WILDCARD, ...enumerated, ...nonTool])].sort();
+  }
+  return [
+    ...inheritedParentGrant.filter((c) => isToolCapability(c) && observedTools.some((t) => matchesToolName(c, t))),
+    ...nonTool,
+  ].sort();
+}
+
+/**
+ * Parse a bound from the environment, distinguishing **absent** from **malformed**.
+ *
+ * G7 / A-S4 + B-I4. `Number.parseInt` is the wrong tool for reading configuration: it accepts a numeric
+ * prefix (`parseInt("2abc")` is `2`), returns `NaN` for anything else, and `NaN` silently passes every
+ * comparison as false — so a malformed `PI_DADDY_MAX_DEPTH` did not tighten the limit, it removed it.
+ *
+ * The three-way return is the point. `undefined` means "not configured, use the documented default";
+ * `null` means "configured wrongly", which callers must treat as a failure rather than a default,
+ * because a value someone tried to set and mistyped is not the same as one they never set.
+ */
+export function parseBound(raw: string | undefined): number | null | undefined {
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim();
+  // Exact non-negative decimal integers only: no signs, no fractions, no 0x, no numeric prefixes.
+  if (!/^\d+$/.test(trimmed)) return null;
+  const value = Number(trimmed);
+  return Number.isSafeInteger(value) ? value : null;
+}
+
+export interface DepthConfig {
+  depth: number;
+  maxDepth: number;
+  /** Names of the variables that were set but unreadable, for an operator-facing warning. */
+  malformed: string[];
+}
+
+/**
+ * Resolve this session's depth bounds, failing closed on anything malformed.
+ *
+ * **Malformed input disables spawning entirely (`maxDepth: 0`)** rather than falling back to a default,
+ * and that applies to a bad `PI_DADDY_DEPTH` just as much as a bad `PI_DADDY_MAX_DEPTH`. The old
+ * `|| 0` guard on depth failed open in a subtler way than the missing guard on maxDepth: a session that
+ * could not read its own depth was treated as a **root**, which is the most permissive answer available
+ * and precisely the value an attacker would choose. If we do not know how deep we are, we must not spawn.
+ */
+export function depthConfig(depthRaw: string | undefined, maxDepthRaw: string | undefined): DepthConfig {
+  const depth = parseBound(depthRaw);
+  const maxDepth = parseBound(maxDepthRaw);
+  const malformed: string[] = [];
+  if (depth === null) malformed.push(ENV_DEPTH);
+  if (maxDepth === null) malformed.push(ENV_MAX_DEPTH);
+
+  if (malformed.length > 0) return { depth: depth ?? 0, maxDepth: 0, malformed };
+  return { depth: depth ?? 0, maxDepth: maxDepth ?? DEFAULT_MAX_DEPTH, malformed };
+}
+
+/** The documented default child-depth bound when `PI_DADDY_MAX_DEPTH` is not set. */
+export const DEFAULT_MAX_DEPTH = 2;
+
+/**
+ * Gated by default in a governed session (ADR-0012).
+ *
+ * `bash` is not one capability among others; it is an execution primitive. A child holding it can run
+ * `env -u PI_DADDY_GRANT pi …` and obtain a completely **ungoverned** descendant — measured, not
+ * theorised (`docs/probes/g5-bash-escape`). Handing that down silently is the thing worth changing.
+ *
+ * Subsumption-aware gating (also ADR-0012) means this single entry covers `write`, `edit`, `read`,
+ * `grep`, `find` and `ls` as well, since `bash` confers all of them.
+ */
+export const DEFAULT_GATED: Capability[] = ["tool:bash"];
+
+/**
+ * Read the gate list, distinguishing **absent** from **explicitly empty**.
+ *
+ * `parseList` alone cannot: it maps both `undefined` and `""` to `[]`. That distinction is the operator's
+ * only way to turn the default off — without it, someone who wants no gates would have to stop governing
+ * altogether, which is strictly worse than the thing they were trying to avoid.
+ */
+export function gatedFromEnv(raw: string | undefined): Capability[] {
+  if (raw === undefined) return [...DEFAULT_GATED];
+  return parseList(raw);
+}
+
+export interface ChildEnvInput {
+  /** This session's own grant — becomes the child's inherited parent grant. */
+  ownGrant: Capability[];
+  /** This session's depth; children are one deeper. */
+  depth: number;
+  maxDepth: number;
+  gated: Capability[];
+  /**
+   * Gated capabilities a human approved at or above this level.
+   *
+   * Safe to push on the GLOBAL channel because it is intersected with THIS session's own grant, which is
+   * a parent-level fact — identical for every sibling, so there is nothing to race on. Each child then
+   * re-intersects with its own grant on arrival, exactly as it does for the grant itself.
+   */
+  /**
+   * Approvals eligible to cross the boundary (ADR-0014): capability, subject and scope. `once` is
+   * dropped by `inheritApprovals`, and the subject is preserved so it cannot satisfy another one.
+   */
+  approved?: InheritableApproval[];
+  ledgerPath?: string;
+  /**
+   * Whether THIS session is governed — i.e. `PI_DADDY_GRANT` was set for it.
+   *
+   * G7 / B-I8. Governance is opt-in: with the variable unset the README promises "nothing is blocked".
+   * That was true of the session itself and false of its children, because this function still exported
+   * a grant, a depth and a bound, so an ungoverned parent silently started governing its descendants —
+   * and the grant it exported was its own observed tool surface, which is a real restriction arrived at
+   * by accident. An ungoverned session must be transparent, not a source of policy.
+   *
+   * Defaults to `true` so that every existing caller keeps publishing; only the extension, which alone
+   * knows whether the variable was set, passes `false`.
+   */
+  governed?: boolean;
+}
+
+/**
+ * The environment a child should inherit. Constant across all of this session's children by
+ * construction, which is what makes concurrent spawning safe.
+ *
+ * **The wildcard is never inherited.** A root may HOLD `tool:*` — that is authority to grant anything —
+ * but handing it down would let every descendant reacquire the full catalog, which makes attenuation
+ * meaningless below the root. Children therefore inherit the ENUMERATED grant only.
+ *
+ * Consequence, deliberate: a wildcard root that has not yet observed its own tools hands children an
+ * empty grant, so they can spawn nothing. That fails closed. It is also unreachable in normal flow,
+ * because a session's first provider request always precedes its first tool call.
+ */
+/**
+ * The part of a grant a child may inherit: everything but the wildcards that are HELD, never handed down.
+ *
+ * `tool:*` for R-26's reason — a root that handed it down let every descendant reacquire the full catalog.
+ * `workspace:*` for the same reason one namespace over (R-131): a descendant holding it could route anywhere
+ * the registry lists, which is the attenuation failure ADR-0035 exists to close. `agent:*` is deliberately
+ * NOT stripped — ADR-0023 decided that a session authorised for any definition passes that on, because
+ * definitions are ceilings rather than roots.
+ *
+ * **Exported, and there is exactly one spelling of this rule on purpose.** It shipped as a filter inline in
+ * `childEnv` and nowhere else, so a grant travelling the OTHER path — `delegate.ts` building a child's
+ * `PI_DADDY_GRANT` from `result.effective` — carried `workspace:*` straight down. The test written beside
+ * that fix exercised `childEnv`, which is not the path a delegated child's grant travels, so it could not
+ * catch it. R-28's shape: two routes for one rule, with the guard on the quieter one. Both call this now.
+ */
+export function inheritableGrant(grant: readonly Capability[]): Capability[] {
+  return grant.filter((c) => c !== WILDCARD && c !== WORKSPACE_WILDCARD);
+}
+
+export function childEnv(input: ChildEnvInput): Record<string, string> {
+  if (input.governed === false) return {};
+  const inheritable = inheritableGrant(input.ownGrant);
+  const env: Record<string, string> = {
+    [ENV_GRANT]: (assertCapabilitiesArePropagatable(inheritable), inheritable.join(",")),
+    [ENV_DEPTH]: String(input.depth + 1),
+    [ENV_MAX_DEPTH]: String(input.maxDepth),
+  };
+  if (input.gated.length > 0) env[ENV_GATED] = input.gated.join(",");
+  // ALWAYS written, empty string included. This is the one value that changes during a session (a human
+  // approves something, or the session's own grant narrows on observation), and the interceptor path
+  // publishes it by ASSIGNING into the process-global `process.env`. Omitting it when empty would leave
+  // whatever was there before — the parent's own, unclamped `PI_DADDY_APPROVED` — visible to every child.
+  // `parseList("")` is `[]`, so an empty value reads back exactly as an absent one.
+  env[ENV_APPROVED] = inheritApprovals(input.approved ?? [], inheritable).join(",");
+  // Empty is an explicit one-run ledger opt-out and must overwrite a prior publication too.
+  if (input.ledgerPath !== undefined) env[ENV_LEDGER] = input.ledgerPath;
+  return env;
+}
+
+/**
+ * The environment for a child this process spawns itself: the parent's environment with every governance
+ * variable stripped, then the per-child plan applied.
+ *
+ * Spreading `{ ...process.env, ...plan.env }` is not enough. `plan.env` omits keys that do not apply to
+ * this child (an empty approval set, no gated list), and an omitted key does not overwrite — so the
+ * parent's own value survives into the child. Stripping first makes the plan the ONLY source of every
+ * governance variable, which is what `delegate.ts`'s "nothing is written to the shared `process.env`"
+ * claim actually requires. Consumers re-clamp anyway; this is the defence in depth behind that.
+ */
+export function mergeChildEnv(parentEnv: NodeJS.ProcessEnv, planEnv: Record<string, string>): NodeJS.ProcessEnv {
+  const merged: NodeJS.ProcessEnv = { ...parentEnv };
+  for (const key of GRANT_ENV_KEYS) delete merged[key];
+  return { ...merged, ...planEnv };
+}
+
+/** Extract bare tool names from a provider payload's tool array, tolerating provider shape differences. */
+export function observeToolNames(payload: unknown): string[] | null {
+  if (!payload || typeof payload !== "object") return null;
+  const record = payload as Record<string, unknown>;
+  for (const key of ["tools", "functions"]) {
+    const candidate = record[key];
+    if (!Array.isArray(candidate)) continue;
+    const names = candidate
+      .map((entry) => {
+        if (!entry || typeof entry !== "object") return undefined;
+        const e = entry as Record<string, unknown>;
+        // Anthropic/OpenAI tool objects, and OpenAI's nested `function.name` form.
+        const nested = e.function as Record<string, unknown> | undefined;
+        const name = e.name ?? nested?.name;
+        return typeof name === "string" ? name : undefined;
+      })
+      .filter((n): n is string => Boolean(n));
+    // An empty tools array is a real observation (the session has no tools), not a failure to observe.
+    return names;
+  }
+  return null;
+}

package/src/kernel/refusals.ts

@@ -0,0 +1,64 @@
+export const REFUSAL_CODES = [
+  "CAPABILITY_ESCALATION",
+  "GRANT_ID_MALFORMED",
+  "DEFINITION_NOT_AUTHORIZED",
+  "UNDECLARED_TOOLS",
+  "UNKNOWN_TOOL",
+  "GATED_UNAPPROVED",
+  "APPROVAL_EXPIRED",
+  "APPROVAL_SCOPE_MISMATCH",
+  "APPROVAL_FLOW_FAILED",
+  "DEPTH_EXCEEDED",
+  "FANOUT_EXCEEDED",
+  "EXECUTOR_UNAVAILABLE",
+  "MODEL_UNRESOLVED",
+  "GRANT_STORE_INVALID",
+  // Execution-phase outcomes. Without these, an external controller could distinguish a policy refusal
+  // from an internal error but not a lost writer lease from a user pressing stop (R-103).
+  "CHILD_TIMED_OUT",
+  "CHILD_CANCELLED",
+  "CHILD_EXIT_NONZERO",
+  // Planner refusals that previously carried a message and no code at all — including the narrowing
+  // violation, which is the hardest rule this package enforces (R-109).
+  "TASK_MISSING",
+  "UNKNOWN_DEFINITION",
+  "CEILING_PATTERNS_UNRESOLVED",
+  "NARROWING_VIOLATED",
+  "DEFINITION_UNREADABLE",
+  "CORRELATION_TOO_LARGE",
+  "CORRELATION_INVALID",
+  "LEDGER_WRITE_FAILED",
+  "FANOUT_FAILED",
+  "WORKSPACE_NOT_REGISTERED",
+  "WORKSPACE_NOT_AUTHORIZED",
+  "WORKSPACE_WRITE_CONFLICT",
+  "WORKSPACE_LEASE_STALE",
+  // ADR-0076 PR 3d: a ledger with a torn or tampered tail refuses appends until an explicit repair.
+  "LEDGER_DAMAGED",
+] as const;
+
+export type RefusalCode = (typeof REFUSAL_CODES)[number];
+
+export interface StructuredRefusal {
+  code: RefusalCode;
+  /** Existing actionable diagnostic. Codes accompany rather than replace it. */
+  message: string;
+  details?: Record<string, string | number | boolean | null>;
+}
+
+export function refusal(code: RefusalCode, message: string, details?: StructuredRefusal["details"]): StructuredRefusal {
+  return { code, message, ...(details && Object.keys(details).length > 0 ? { details: { ...details } } : {}) };
+}
+
+/** Error shape for API callers. pi-facing tools still throw, as pi requires, while retaining a stable code. */
+export class GovernanceRefusal extends Error {
+  readonly code: RefusalCode;
+  readonly details?: StructuredRefusal["details"];
+
+  constructor(value: StructuredRefusal) {
+    super(value.message);
+    this.name = "GovernanceRefusal";
+    this.code = value.code;
+    this.details = value.details;
+  }
+}

package/src/kernel/resolve.ts

@@ -0,0 +1,258 @@
+/**
+ * Grant resolution — the entire security surface of capability governance, as a pure function.
+ *
+ * The invariant (ADR-0008): a capability set may only ever SHRINK as it passes down a delegation
+ * tree. Escalation is impossible by construction rather than by policy, because a parent can never
+ * confer what it does not itself hold.
+ *
+ *   effective = ( requested ∩ parentGrant ∩ ceiling ) \ (gated \ approved)
+ *
+ * Being pure — no I/O, no model, no network — this is exhaustively testable, which matters because it
+ * is the only place an escalation could be introduced.
+ */
+
+/** `tool:read` · `ext:pi-web-access/web_search` · `skill:review` · `agent:researcher` */
+export type Capability = string;
+
+/**
+ * Capabilities that transitively confer everything else. Granting one is equivalent to granting the
+ * whole catalog, so they can never be a *narrowing* grant.
+ *
+ * `ext:pi-fabric/fabric_exec` is here on measured evidence, not suspicion: a child granted
+ * `tools: []` (nothing at all) plus `recursive: true` still reached `pi.write` and `pi.bash` and
+ * spawned a grandchild that wrote to disk. See docs/probes/pi-fabric-eval (probes 2, 4, 7, 8).
+ */
+export const UNIVERSAL_CAPABILITIES: readonly Capability[] = ["ext:pi-fabric/fabric_exec", "tool:fabric_exec"];
+
+/**
+ * Capabilities that functionally contain others.
+ *
+ * `bash` can run `grep`, `find`, `ls`, `cat`, and `sed` — so a session holding it can already do
+ * everything the file and search tools do, whatever the tool list says. Modelling this explicitly serves
+ * two purposes:
+ *
+ *  1. It removes false escalation reports. pi's *default* surface is only `read`, `bash`, `edit`, `write`
+ *     (measured, not assumed), so an agent type declaring `tools: read, grep, find, ls` would otherwise
+ *     look like an escalation from any normal parent — despite being strictly weaker.
+ *  2. It makes the uncomfortable truth visible rather than implied: **a grant containing `bash` is not a
+ *     narrow grant.** `subsumedBy` in the result says so, so a reviewer can see what the grant really means.
+ */
+export const SUBSUMPTION: Readonly<Record<Capability, readonly Capability[]>> = {
+  "tool:bash": ["tool:grep", "tool:find", "tool:ls", "tool:read", "tool:write", "tool:edit", "tool:edit-diff"],
+};
+
+/** Expand a grant to everything it functionally confers. */
+export function expandSubsumed(grant: Capability[]): Capability[] {
+  const expanded = new Set(grant);
+  for (const held of grant) {
+    for (const implied of SUBSUMPTION[held] ?? []) expanded.add(implied);
+  }
+  return [...expanded].sort();
+}
+
+import { WILDCARD } from "./pi-tools.ts";
+import { isWellFormedCapability } from "./capabilities.ts";
+
+/**
+ * "Any definition" — ADR-0023, and one of two wildcards this module understands.
+ *
+ * Declared here rather than beside `WILDCARD` because `pi-tools.ts` imports `Capability` from this module.
+ * That import is `import type`, so it is erased and the runtime dependency runs one way only — which is
+ * what makes importing `WILDCARD` back safe.
+ *
+ * Deliberately weaker than `tool:*`: it confers **no tool authority**, so `agent:*,tool:read` may spawn
+ * every definition on disk and hand each of them nothing but `read`. It exists because the alternative was
+ * `tool:*` — authority to grant every tool — which made the safe configuration the laborious one.
+ */
+export const AGENT_WILDCARD: Capability = "agent:*";
+/**
+ * `workspace:*` covers any `workspace:<id>` — ADR-0035, and the second namespace wildcard.
+ *
+ * Added as a deliberate edit, which is what the comment in `resolve()` below asks for: there is no
+ * generalised `<ns>:*` rule, so a namespace does not acquire a wildcard by existing. Unlike `agent:*` this
+ * one is **not inheritable** (`childEnv` strips it) — R-26's rule, because a root that handed
+ * `workspace:*` down would make routing attenuation meaningless below the root, which is the exact defect
+ * R-131 records.
+ */
+export const WORKSPACE_WILDCARD: Capability = "workspace:*";
+
+export interface ResolveInput {
+  /** What the delegating agent asked to give the child. */
+  requested: Capability[];
+  /** What the delegating agent itself holds. The root's grant is configured, never defaulted to all. */
+  parentGrant: Capability[];
+  /** Declarative maximum for the child's agent type (its frontmatter). Omit for no ceiling. */
+  ceiling?: Capability[];
+  /** Destructive capabilities that may never enter a grant without explicit human approval. */
+  gated?: Capability[];
+  /** Gated capabilities a human has approved for this specific spawn. */
+  approved?: Capability[];
+  /**
+   * Honour functional subsumption when deciding what the parent covers (default true).
+   * Set false for a strict name-equality check.
+   */
+  subsumption?: boolean;
+}
+
+export interface ResolveResult {
+  /** The capability set the child may hold. */
+  effective: Capability[];
+  /** Requested but NOT held by the parent — the escalation-attempt signal. Log every one. */
+  denied: Capability[];
+  /** Held by the parent but outside the child type's declared ceiling. */
+  clipped: Capability[];
+  /** Allowed by the tree but gated and unapproved. */
+  gatedBlocked: Capability[];
+  /** Universal capabilities that survived resolution — see `assertNarrowing`. */
+  universal: Capability[];
+  /**
+   * Capabilities the parent covers only through subsumption, not by holding them directly — e.g. `grep`
+   * covered because the parent holds `bash`. Non-empty means the grant is broader than its list suggests.
+   */
+  subsumedBy: Capability[];
+}
+
+const unique = (xs: Capability[]): Capability[] => [...new Set(xs)].sort();
+
+/**
+ * Resolve a child's grant. Total and side-effect free; every rejected capability is reported rather
+ * than silently dropped, because a grant nobody can audit proves nothing.
+ */
+export function resolve(input: ResolveInput): ResolveResult {
+  const requested = unique(input.requested);
+  const held = new Set(input.parentGrant);
+  const parent = input.subsumption === false ? held : new Set(expandSubsumed(input.parentGrant));
+  /**
+   * `agent:*` covers any `agent:<name>` — ADR-0023. It was the only wildcard rule in this function when
+   * that was written; ADR-0035 added a third, so `covered()` now has `tool:*`, `agent:*` and `workspace:*`.
+   * There is still no GENERALISED `<ns>:*` rule: each is a deliberate edit, which is the property worth
+   * keeping. Corrected because the sentence sat eighty lines above "all THREE wildcards are excluded".
+   *
+   * `resolve` is otherwise exact-match plus subsumption, deliberately: `tool:*` works not because anything
+   * here understands it, but because `deriveOwnGrant` *enumerates* a session's observed tool names beside
+   * it. Definitions are not tools, so nothing enumerates them — which is why `maySpawnDefinition` had to
+   * special-case the wildcard, and why this needs stating rather than falling out.
+   *
+   * Scoped to one namespace on purpose. There is no generalised `<ns>:*` rule, so a namespace added later
+   * does not silently acquire a wildcard; adding one is a deliberate edit and another decision.
+   */
+  const anyDefinition = held.has(AGENT_WILDCARD);
+  /**
+   * `tool:*` satisfies **any** capability, including `skill:` and `agent:` ids.
+   *
+   * Missing until 0.11.2, and the omission broke the one rule this package must never break by accident:
+   * *governance is opt-in*. An ungoverned session holds `[tool:*, …observed tools]` and nothing else, so
+   * spawning a definition whose `allowed-tools` names `agent:worker` or `skill:review` — the composition
+   * ADR-0017 created and ADR-0023's own example uses — was refused with **"capability escalation
+   * blocked"**, and recorded as an escalation attempt, in a session that had opted out.
+   *
+   * `maySpawnDefinition` had always honoured `tool:*` for definition ids and `docs/SPEC.md` had always
+   * claimed it "satisfies any capability". This function disagreed with both, which is R-28's shape: two
+   * spellings of one rule, and the enforcing one was wrong.
+   */
+  const anyCapability = held.has(WILDCARD);
+  const anyWorkspace = held.has(WORKSPACE_WILDCARD);
+  // A malformed id is never covered — not by an exact hold, and above all not by a wildcard's PREFIX rule,
+  // which is how `agent:x,tool:bash` got admitted and then split into two capabilities in the child.
+  // Landing in `denied` is the right outcome rather than a throw: it fails closed AND records an
+  // escalation attempt, so the ledger shows the attempt instead of a clean line.
+  const covered = (c: Capability): boolean =>
+    isWellFormedCapability(c) &&
+    (parent.has(c) ||
+      anyCapability ||
+      (anyDefinition && c.startsWith("agent:")) ||
+      (anyWorkspace && c.startsWith("workspace:")));
+
+  const ceiling = input.ceiling === undefined ? null : new Set(input.ceiling);
+  const gated = new Set(input.gated ?? []);
+  const approved = new Set(input.approved ?? []);
+
+  // Order is irrelevant to the outcome (set intersection is commutative), so each rejection reason is
+  // reported independently rather than being masked by whichever filter happened to run first.
+  const denied = requested.filter((c) => !covered(c));
+  const clipped = requested.filter((c) => covered(c) && ceiling !== null && !ceiling.has(c));
+  /**
+   * Is this capability gated, directly or by subsuming something gated?
+   *
+   * ADR-0012. Exact-name gating was defeatable by handing down a broader capability: the package's own
+   * `SUBSUMPTION` table says `bash` confers `write`, so gating `write` produced **no prompt** when `bash`
+   * was granted instead. The gate read as satisfied because the string never appeared.
+   *
+   * The direction is load-bearing and easy to invert. A capability is gated when it **subsumes**
+   * something gated — never when it **is subsumed by** something gated. Gating `bash` must not quietly
+   * gate a plain `write` grant, which would make gating a broad capability restrict the narrow ones and
+   * invert least privilege.
+   */
+  const isGated = (c: Capability): boolean => {
+    if (gated.has(c)) return true;
+    if (input.subsumption === false) return false;
+    return (SUBSUMPTION[c] ?? []).some((implied) => gated.has(implied));
+  };
+
+  const gatedBlocked = requested.filter(
+    (c) => covered(c) && (ceiling === null || ceiling.has(c)) && isGated(c) && !approved.has(c),
+  );
+
+  const rejected = new Set([...denied, ...clipped, ...gatedBlocked]);
+  const effective = requested.filter((c) => !rejected.has(c));
+
+  return {
+    effective,
+    denied,
+    clipped,
+    gatedBlocked,
+    universal: effective.filter((c) => UNIVERSAL_CAPABILITIES.includes(c)),
+    // F9: capabilities covered by a WILDCARD are not "subsumed" — this field means "the grant is broader
+    // than its list suggests", which is the `bash`-covers-`grep` warning. A wildcard holder already knows
+    // its grant is broad; listing every id under it would bury the signal the field exists to carry.
+    //
+    // All THREE wildcards are excluded. `anyWorkspace` was missing, so a caller holding `workspace:*` saw
+    // its own `workspace:prod` reported as subsumed while the `agent:*` holder correctly saw nothing — the
+    // field contradicting its own rule, and a false "broader than it looks" flag in the ledger and in
+    // `/grants`. Every wildcard added to `covered()` above needs a line here; that is now three for three.
+    subsumedBy: effective.filter(
+      (c) =>
+        !held.has(c) &&
+        !anyCapability &&
+        !(anyDefinition && c.startsWith("agent:")) &&
+        !(anyWorkspace && c.startsWith("workspace:")),
+    ),
+  };
+}
+
+/**
+ * Fail closed on a grant that cannot actually narrow anything.
+ *
+ * A universal capability in an "attenuated" grant is not a narrow grant with one extra item — it is
+ * full authority wearing a narrow grant's clothing. Callers must opt in explicitly rather than
+ * discover this at runtime.
+ */
+export function assertNarrowing(result: ResolveResult, allowUniversal = false): void {
+  if (!allowUniversal && result.universal.length > 0) {
+    throw new Error(
+      `refusing to issue a grant containing universal capabilities: ${result.universal.join(", ")}. ` +
+        `These transitively confer the whole catalog, so the grant would not narrow anything. ` +
+        `Pass allowUniversal to override deliberately.`,
+    );
+  }
+}
+
+/**
+ * Project an effective grant onto pi's `--tools` allowlist.
+ *
+ * pi core is the enforcement point — verified: `--tools` and `--no-tools` both hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them
+ * (docs/probes/pi-fabric-eval probes 9–11). That is why enforcement needs no in-descendant runtime.
+ *
+ * Returns `null` when the grant contains no callable tools, meaning the caller should pass
+ * `--no-tools` rather than an empty `--tools` (an empty list is not a valid allowlist).
+ */
+export function toPiToolsAllowlist(effective: Capability[]): string[] | null {
+  const names = effective
+    .filter((c) => c.startsWith("tool:") || c.startsWith("ext:"))
+    // `tool:read` -> `read`; `ext:pkg/web_search` -> `web_search` (pi matches on bare tool name)
+    .map((c) => (c.startsWith("tool:") ? c.slice(5) : c.slice(c.lastIndexOf("/") + 1)))
+    .filter((n) => n.length > 0);
+  const deduped = [...new Set(names)].sort();
+  return deduped.length > 0 ? deduped : null;
+}