pi-daddy 0.28.0 → 0.32.0

package/src/kernel/approval.ts

@@ -0,0 +1,406 @@
+/**
+ * Approval model for gated capabilities — pure, so it is exhaustively testable without pi.
+ *
+ * `resolve()` computes `gatedBlocked`: capabilities a session legitimately holds but which may not enter
+ * a child's grant without a human saying so. This module decides WHAT a yes means — how far it reaches,
+ * how long it lasts, and what it is keyed to. It never performs I/O and never prompts; see
+ * `approval-store.ts` and `approval-prompt.ts` for those.
+ *
+ * ADR-0010 records the four decisions encoded here.
+ */
+
+import { WILDCARD } from "./pi-tools.ts";
+import type { Capability, ResolveResult } from "./resolve.ts";
+import { approvalBindingsEqual, type ApprovalBinding } from "./correlation.ts";
+
+/** How far a single yes reaches in time. */
+export const APPROVAL_SCOPES = ["once", "session", "always"] as const;
+export type ApprovalScope = (typeof APPROVAL_SCOPES)[number];
+
+/** Where a yes came from, for the ledger. These call for different follow-ups, so they stay distinct. */
+export const APPROVAL_SOURCES = ["prompt", "session", "persisted", "inherited"] as const;
+export type ApprovalSource = (typeof APPROVAL_SOURCES)[number];
+
+/** Which call site is asking. Determines the scopes offered — see `offeredScopes`. */
+export type ApprovalPath = "definition" | "delegate";
+
+/**
+ * Subject used for delegate-path approvals.
+ *
+ * The delegate tool has no human-authored subject: the only things naming a child are the task string and
+ * the tool list, both chosen by the model. A key the model controls is not a key, so delegate approvals
+ * use this fixed literal — "allow write for delegations this session" — and are never persisted.
+ * Angle brackets cannot appear in an agent-type name (`parseAgentType` reads an identifier), so this can
+ * never collide with a real type.
+ */
+export const DELEGATE_SUBJECT = "<delegate>";
+
+/**
+ * Lifetime of a persisted approval.
+ *
+ * Deliberately a constant rather than an environment variable: a knob that silently extends every gate is
+ * the first thing an impatient operator would reach for.
+ */
+export const APPROVAL_TTL_DAYS = 30;
+
+const DAY_MS = 86_400_000;
+
+/** `tool:write` + `docs-writer` -> `tool:write@docs-writer`. */
+export function approvalKey(capability: Capability, subject: string): string {
+  return `${capability}@${subject}`;
+}
+
+/**
+ * May this resolution raise an approval dialog?
+ *
+ * `resolve()` computes `denied` and `gatedBlocked` INDEPENDENTLY (deliberately — each rejection reason is
+ * reported rather than masked by whichever filter ran first), and both `decideSpawn` and `planDelegation`
+ * refuse outright on `denied` while still attaching the full result. So a request mixing a gated capability
+ * with one the session does not hold at all would otherwise prompt a human about the gated one and then be
+ * refused anyway for the other.
+ *
+ * That is not merely noise. A *session* yes is recorded and republished to children, and an *always* yes is
+ * written to disk for 30 days — both banked against a spawn that never happened, and both reachable by a
+ * model that appends one unheld capability to an otherwise ordinary request. A person is therefore only
+ * asked about a spawn that would actually proceed if they said yes.
+ *
+ * `clipped` is deliberately NOT a bar: it does not refuse a spawn, it just drops those capabilities from
+ * the child's grant, so the spawn does proceed and the question is real.
+ */
+export function shouldSeekApproval(result: ResolveResult | undefined): boolean {
+  if (!result) return false;
+  if (result.denied.length > 0) return false;
+  // ADR-0011. A grant retaining a universal capability is refused by `assertNarrowing` no matter what
+  // a human says, so asking is worse than useless: the dialog cannot change the outcome, and a
+  // `session`- or `always`-scoped yes given there is banked and reused for later spawns that DO
+  // proceed. Same harm the `denied` guard above exists to prevent.
+  if (result.universal.length > 0) return false;
+  return result.gatedBlocked.length > 0;
+}
+
+/**
+ * Scopes a given call site may offer. `always` requires a **human-authored subject**.
+ *
+ * ADR-0019. The rule is unchanged; which paths satisfy it is not. `"interceptor"` used to be the only one
+ * and ADR-0016 deleted it, leaving `always` offerable from nowhere — 220 lines of persistence no live path
+ * could write to. `"definition"` is `delegate({agent})`, where ADR-0017 makes the subject an
+ * operator-authored file the session must hold `agent:<name>` to name at all. `"delegate"` is the `tools:`
+ * form, where the original reasoning stands untouched: the only things naming that child are the task and
+ * the tool list, both model-chosen, and a key the model controls is not a key.
+ */
+export function offeredScopes(path: ApprovalPath): ApprovalScope[] {
+  return path === "definition" ? ["once", "session", "always"] : ["once", "session"];
+}
+
+/**
+ * The approval an inheriting child may hold.
+ *
+ * Intersecting with the child's grant is what keeps ADR-0008 intact once approvals became inheritable:
+ * `approved ⊆ grant` at every level, by construction. An approval can therefore never name a capability
+ * the session does not hold — it only ever unblocks part of a grant, never widens one.
+ *
+ * The wildcard is filtered for the same reason `childEnv` filters it out of grants (R-26): inheriting it
+ * would let a descendant treat every future gate as pre-approved.
+ */
+/** An approval as it crosses a boundary: the capability, WHO it was for, and HOW LONG it was meant to last. */
+export interface InheritableApproval {
+  capability: Capability;
+  /** The agent type, or `<delegate>`. Carried because an approval is for a subject, not for a word. */
+  subject: string;
+  scope: ApprovalScope;
+  /**
+   * The definition's body digest at the time of approval (ADR-0022). Absent for `<delegate>`, which names
+   * no file to hash — and, per ADR-0019, is never persisted or offered `always` for the same reason.
+   */
+  bodySha256?: string;
+  /**
+   * Exact delegation binding for controllers that supply correlation/workspace context (ADR-0034).
+   * Bound approvals are deliberately not inherited: authority for one task must not become subtree-wide.
+   */
+  binding?: ApprovalBinding;
+}
+
+/**
+ * What a child may inherit, as `capability@subject` keys.
+ *
+ * ADR-0014 changed this in two ways, and both were cases of a human's explicit choice being discarded
+ * one hop down:
+ *
+ *  - **`once` is dropped** (A-S1). The scope chosen was not carried, so a `once` approval was written
+ *    into the child's `PI_DADDY_APPROVED` and republished onward — the most conservative answer a human
+ *    can give produced the least conservative outcome, across an entire descendant subtree.
+ *  - **The subject is kept** (A-S6). Bare capabilities were published, so a `<delegate>`-subject approval
+ *    matched *any* subject below. `approvalKey`'s own doc argues at length that a model-controlled name
+ *    is not a key; erasing the subject made that argument moot exactly where it mattered.
+ *
+ * The clamp to `grant` is unchanged and still load-bearing: **approval cannot conjure a capability**, so
+ * an inherited yes is only ever honoured for something the child independently holds.
+ */
+export function inheritApprovals(approved: InheritableApproval[], grant: Capability[]): string[] {
+  const held = new Set(grant);
+  return [
+    ...new Set(
+      approved
+        .filter(
+          (a) => a.scope !== "once" && a.binding === undefined && a.capability !== WILDCARD && held.has(a.capability),
+        )
+        // A definition subject MUST carry a pin to cross a boundary (ADR-0022, hardened after F1).
+        //
+        // `verifyInherited` honours an unpinned entry by decision — `<delegate>` names no file and a
+        // pre-0.11 parent sends none — so an unpinned entry for a subject that *does* name a file is an
+        // approval exempt from the digest check. Enforcing it at the point of PUBLICATION rather than
+        // trusting each caller to attach a digest is what makes it structural: two call sites build these
+        // entries, one of them forgot, and every fresh approval crossed unpinned as a result. A caller that
+        // cannot produce a digest (the definition is not on disk here) now publishes nothing, which is the
+        // fail-closed direction.
+        .filter((a) => a.subject === DELEGATE_SUBJECT || Boolean(a.bodySha256))
+        .map((a) => approvalKey(a.capability, a.subject) + (a.bodySha256 ? `#${a.bodySha256}` : "")),
+    ),
+  ].sort();
+}
+
+/**
+ * Read the inherited set back on the child side.
+ *
+ * Anything that is not a well-formed `capability@subject` pair is dropped rather than guessed at. An
+ * unparseable entry granting nothing is a missing prompt; an unparseable entry granting *something* is a
+ * silent escalation, so the direction of the failure is not a matter of taste.
+ */
+export function parseInherited(raw: string | undefined): Map<string, string | undefined> {
+  const out = new Map<string, string | undefined>();
+  for (const item of (raw ?? "").split(",")) {
+    const trimmed = item.trim();
+    // ADR-0022 appends `#<sha256>`. Split it off FIRST: a `#` cannot appear in a capability id or in a
+    // definition name (identity comes from a path component), so this is unambiguous.
+    const hash = trimmed.indexOf("#");
+    const key = hash === -1 ? trimmed : trimmed.slice(0, hash);
+    const digest = hash === -1 ? undefined : trimmed.slice(hash + 1);
+    const at = key.indexOf("@");
+    if (at <= 0 || at === key.length - 1) continue;
+    if (hash !== -1 && !digest) continue; // `key#` promises a pin and carries none — drop it, do not guess
+    out.set(key, digest);
+  }
+  return out;
+}
+
+/**
+ * Drop inherited approvals that were given for different instructions (ADR-0022).
+ *
+ * The hole this closes: `resolveApprovals` checks `inherited` FIRST and none of it had ever been through
+ * `entryVerdict`, so ADR-0019's headline property — an approval is void once the instructions change — held
+ * on the one path that persists and neither of the two that do not. A child is a fresh process: it re-reads
+ * the definition from disk, so a `git pull` between the parent's approval and the child's spawn meant the
+ * child ran a rewritten body under a yes given about the old one, recording `approvalSource: "inherited"`.
+ *
+ * An entry with **no** digest is honoured, and that is not a hole: `<delegate>` legitimately has none, and
+ * neither does a pre-0.11 parent. It is the same trade `entryVerdict` refuses to make for a *persisted*
+ * entry — but that entry is 30 days old and read off disk, whereas this one was handed over by a live parent
+ * process in the same tree, which is a much shorter chain to trust.
+ */
+export function verifyInherited(
+  parsed: ReadonlyMap<string, string | undefined>,
+  snapshotOf: (subject: string) => SubjectSnapshot | null,
+): Set<string> {
+  const out = new Set<string>();
+  for (const [key, digest] of parsed) {
+    if (digest === undefined) {
+      out.add(key);
+      continue;
+    }
+    const current = snapshotOf(key.slice(key.indexOf("@") + 1));
+    if (current && current.bodySha256 === digest) out.add(key);
+  }
+  return out;
+}
+
+/** When an approval granted now stops being valid. Computed once at write time and stored, so an entry's
+ *  lifetime is visible in the file rather than implied by whichever version of the code reads it. */
+export function expiryFor(approvedAt: Date): string {
+  return new Date(approvedAt.getTime() + APPROVAL_TTL_DAYS * DAY_MS).toISOString();
+}
+
+/** A persisted approval, keyed externally by subject and capability. Only the `"definition"` path writes one. */
+export interface ApprovalEntry {
+  approvedAt: string;
+  expiresAt: string;
+  /** The directory the human was sitting in. See `entryVerdict` and R-27. */
+  cwd: string;
+  /** The agent type's ceiling AT APPROVAL TIME. Load-bearing, not decorative — see `entryVerdict`. */
+  grantAtApproval: Capability[];
+  /*
+   * `taskAtApproval` was here and is GONE (ADR-0021). It stored the model-authored task string, which
+   * `src/governance/ledger.ts` forbids in unqualified terms — "the task is not recorded, anywhere, ever" — and the
+   * approval store is a worse home for it than the ledger by ADR-0018's own criteria: always-on, outside
+   * the repository, kept for 30 days. It also read as a scope it never was, since the entry authorises ANY
+   * task for that definition. Both reviewers found it independently. `approval-store.ts`'s `sanitise`
+   * strips it from any entry this version rewrites.
+   */
+  /**
+   * The definition's body digest AT APPROVAL TIME (ADR-0019, using ADR-0018's hash).
+   *
+   * `grantAtApproval` pins the tools; this pins the INSTRUCTIONS. Without it an `always` approval survives
+   * a total rewrite of what the child is told to do, because `ceilingForDefinition` reads only
+   * `allowed-tools` — R-35's hazard reappearing inside the persistence layer. Absent means the entry
+   * predates 0.10.0 and cannot be verified, which `entryVerdict` treats as changed: fail closed.
+   */
+  bodyAtApproval?: string;
+  /** Exact task/grant/workspace/context/parent binding for correlated controller calls (ADR-0034). */
+  binding?: ApprovalBinding;
+}
+
+export type EntryVerdict =
+  "valid" | "expired" | "foreign-cwd" | "type-changed" | "instructions-changed" | "type-missing";
+
+/**
+ * What a subject looks like RIGHT NOW — one lookup, not two (ADR-0019).
+ *
+ * Deliberately a single snapshot rather than parallel `ceilingOf` / `digestOf` callbacks. R-28 was one
+ * call site supplying one argument and omitting another; a shape that cannot be half-supplied is the
+ * structural form of remembering.
+ */
+export interface SubjectSnapshot {
+  ceiling: Capability[];
+  /** SHA-256 of the definition body — `digestDefinition(...).sha256`. */
+  bodySha256: string;
+}
+
+export interface EntryValidityInput {
+  entry: ApprovalEntry;
+  /** The directory this session is running in. */
+  cwd: string;
+  now: Date;
+  /** The subject's CURRENT ceiling and body digest, or null when it no longer exists. */
+  current: SubjectSnapshot | null;
+}
+
+/**
+ * Decide whether a persisted approval still means what the human meant.
+ *
+ * Four ways it can stop meaning that, and each is reported distinctly so `/grants approvals` can explain
+ * itself rather than silently showing fewer rows:
+ *
+ *  - `foreign-cwd`  — the file was copied or committed and opened somewhere else. Nobody in THIS checkout
+ *                     was asked, so it authorises nothing here (R-27).
+ *  - `expired`      — a gate opened during one project must not still be open next quarter.
+ *  - `type-changed` — the confused deputy. The key names a file whose contents can change after approval:
+ *                     approve `tool:write@docs-writer` when it declares `read, write`, and later that file
+ *                     gains `bash`. The entry would still match the key while describing something the
+ *                     human never saw.
+ *  - `instructions-changed` — the same confused deputy, one level deeper. The tools are untouched but the
+ *                     BODY was rewritten, so the child would now be told to do something the human never
+ *                     saw. Only checkable since ADR-0018 gave the body a digest; an entry carrying no body
+ *                     pin lands here too, because unverifiable is not the same as unchanged.
+ *  - `type-missing` — the type was deleted or renamed; a new file could later claim the same name.
+ */
+export function entryVerdict(input: EntryValidityInput): EntryVerdict {
+  if (input.entry.cwd !== input.cwd) return "foreign-cwd";
+  const expiresAt = new Date(input.entry.expiresAt).getTime();
+  // NaN <= x is false in JS, so an unparseable date would otherwise fail OPEN. A cache we cannot
+  // read the expiry of is a cache we do not trust — treat it as expired, per the spec's rule that a
+  // broken cache grants nothing.
+  if (!Number.isFinite(expiresAt) || expiresAt <= input.now.getTime()) return "expired";
+  if (input.current === null) return "type-missing";
+  // Compare as sorted lists: reformatting or reordering a `tools:` line is not a change; adding,
+  // removing, or renaming a capability is.
+  const approved = [...input.entry.grantAtApproval].sort().join(",");
+  const current = [...input.current.ceiling].sort().join(",");
+  if (approved !== current) return "type-changed";
+  // Fail closed on an unpinned entry: it was written before bodies were digested, so "unchanged" is not
+  // something this code can assert about it. One re-approval is the honest cost.
+  if (input.entry.bodyAtApproval !== input.current.bodySha256) return "instructions-changed";
+  return "valid";
+}
+
+export interface ResolveApprovalsInput {
+  /** `ResolveResult.gatedBlocked` — held and within ceiling, but awaiting a human. */
+  gated: Capability[];
+  subject: string;
+  /** Approval KEYS approved for this session, in memory only. */
+  sessionApprovals: ReadonlySet<string>;
+  /** Exact bindings for correlated session approvals. Kept separate so legacy keys remain compatible. */
+  sessionApprovalBindings?: ReadonlyMap<string, ApprovalBinding>;
+  /** Persisted entries by key, ALREADY definition/expiry-filtered by the store. */
+  persisted: ReadonlyMap<string, ApprovalEntry>;
+  /** When present, only an exact binding may satisfy this gate. */
+  expectedBinding?: ApprovalBinding;
+  /** Same-key persisted entries dropped specifically because their expiry passed. */
+  expiredKeys?: ReadonlySet<string>;
+  /**
+   * `capability@subject` keys inherited from the delegator (ADR-0014).
+   *
+   * Was `Capability[]` — bare names that matched any subject, and included `once` approvals that were
+   * never meant to leave the level they were given at.
+   */
+  inherited?: Set<string>;
+}
+
+export interface ResolveApprovalsResult {
+  approved: Capability[];
+  /** Gated capabilities still requiring a live human. */
+  needsPrompt: Capability[];
+  /** A same-key approval existed but named another task/workspace/context/parent. */
+  scopeMismatched: Capability[];
+  expired: Capability[];
+  sources: Record<Capability, ApprovalSource>;
+  scopes: Record<Capability, ApprovalScope>;
+  expiresAt: Record<Capability, string>;
+}
+
+/**
+ * Satisfy as much of `gated` as possible without asking anyone.
+ *
+ * Precedence is inherited -> session -> persisted -> prompt. Order matters only for what gets REPORTED
+ * (the ledger's `approvalSource`); any hit satisfies equally. Checking all three before prompting is what
+ * stops an orchestrator's tenth delegation from raising a tenth identical dialog.
+ */
+export function resolveApprovals(input: ResolveApprovalsInput): ResolveApprovalsResult {
+  // ADR-0014: these are `capability@subject` keys now, not bare capabilities, so an approval given for
+  // one subject can no longer satisfy another.
+  const inherited = input.inherited ?? new Set<string>();
+  const approved: Capability[] = [];
+  const needsPrompt: Capability[] = [];
+  const scopeMismatched: Capability[] = [];
+  const expired: Capability[] = [];
+  const sources: Record<Capability, ApprovalSource> = {},
+    scopes: Record<Capability, ApprovalScope> = {};
+  const expiresAt: Record<Capability, string> = {};
+
+  for (const capability of [...new Set(input.gated)].sort()) {
+    const key = approvalKey(capability, input.subject);
+    const expected = input.expectedBinding;
+    const sessionBinding = input.sessionApprovalBindings?.get(key);
+    const persisted = input.persisted.get(key);
+    const inheritedApplies = expected === undefined && inherited.has(key);
+    const legacySessionApplies = expected === undefined && input.sessionApprovals.has(key);
+    const boundSessionApplies = expected !== undefined && approvalBindingsEqual(sessionBinding, expected);
+    const persistedApplies =
+      persisted !== undefined &&
+      (expected === undefined ? persisted.binding === undefined : approvalBindingsEqual(persisted.binding, expected));
+
+    if (inheritedApplies) {
+      approved.push(capability);
+      sources[capability] = "inherited";
+      scopes[capability] = "session";
+    } else if (legacySessionApplies || boundSessionApplies) {
+      approved.push(capability);
+      sources[capability] = "session";
+      scopes[capability] = "session";
+    } else if (persistedApplies) {
+      approved.push(capability);
+      sources[capability] = "persisted";
+      scopes[capability] = "always";
+      expiresAt[capability] = persisted!.expiresAt;
+    } else {
+      needsPrompt.push(capability);
+      if (input.expiredKeys?.has(key)) expired.push(capability);
+      else if (
+        expected !== undefined &&
+        (sessionBinding !== undefined || persisted !== undefined || input.sessionApprovals.has(key))
+      ) {
+        scopeMismatched.push(capability);
+      }
+    }
+  }
+
+  return { approved, needsPrompt, scopeMismatched, expired, sources, scopes, expiresAt };
+}

package/src/kernel/capabilities.ts

@@ -0,0 +1,216 @@
+/**
+ * Capability ids: their grammar, and the two authority predicates over them.
+ *
+ * Split out of `delegate.ts` when ADR-0024 pushed that file past the 400-line ceiling and
+ * `test/file-size.test.ts` refused it — for the second time, and answered the same way as the first: split
+ * the file the way the failure message says rather than raise the cap on the guard.
+ *
+ * The seam is not arbitrary. Three modules outside `delegate.ts` already imported these
+ * (`extensions/session.ts` for `DELEGATE_CAPABILITY`, `extensions/delegation.ts` and
+ * `extensions/run-delegation.ts` for `maySpawnDefinition`), which is the evidence that they were a separate
+ * concern living in the wrong file: *what an id means and who may use it* is a different question from
+ * *what one delegation does*.
+ */
+
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
+import { WILDCARD } from "./pi-tools.ts";
+import { GovernanceRefusal, refusal } from "./refusals.ts";
+
+/** The capability that authorises spawning a definition (ADR-0017). `tool:*` satisfies any of them. */
+export const agentCapability = (name: string): Capability => `agent:${name}`;
+
+/**
+ * May this grant spawn that definition? (ADR-0017.)
+ *
+ * `resolve()` is exact-match plus subsumption and has no wildcard rule — a wildcard session works only
+ * because `deriveOwnGrant` *enumerates* its observed tools alongside `tool:*`. Definitions are not tools,
+ * so nothing enumerates them, and the wildcard has to be honoured here explicitly. Without that an
+ * UNGOVERNED session would stop being able to spawn, and "governance is opt-in" is the one rule this
+ * package must never break by accident.
+ */
+export function maySpawnDefinition(ownGrant: Capability[], name: string): boolean {
+  // ADR-0023 adds the middle case. `tool:*` is authority to grant every tool and satisfies this too;
+  // `agent:*` is authority to spawn any definition and grants no tools at all, which is the configuration
+  // an operator wanting "any of our definitions, narrow tools" previously had to fake with `tool:*`.
+  return ownGrant.includes(WILDCARD) || ownGrant.includes(AGENT_WILDCARD) || ownGrant.includes(agentCapability(name));
+}
+
+/** The tool name that confers the ability to delegate further. */
+export const DELEGATE_CAPABILITY: Capability = "tool:delegate";
+
+/**
+ * Every namespace a capability id may carry, as its literal prefix.
+ *
+ * **One list, because there were three and adding a namespace only updated some of them.** ADR-0035 taught
+ * `normaliseCapability` about `workspace:` and left `ceilingForDefinition` (which mangled it into
+ * `tool:workspace:<id>`) and `isSafeCapability` (which called it malformed) behind. The two places that parse
+ * an id's namespace read this, so a fifth namespace is one entry rather than a third divergence.
+ *
+ * **Not every prefix decision in the package.** Inline `startsWith("` tests on a capability namespace are
+ * scattered across `src/` and `extensions/`; this list is read by two of them. **No number is written here,
+ * and the history is why:** SPEC first claimed the list was "what every site reads"; a correction said "six"
+ * while its own enumeration listed seven; this docstring then said "nine" in the sentence claiming it gave no
+ * number; and the correction to *that* said "fourteen", which counted every file containing any
+ * `startsWith("` — CLI flags, `git worktree list` parsing, an assurance sentinel and node_modules entries
+ * among them. Four numbers, four wrong. The command, so nobody has to quote a predecessor:
+ *
+ *     grep -rl 'startsWith("\(tool:\|ext:\|agent:\|skill:\|workspace:\)' src extensions
+ *
+ * Consolidating the sites is a separate change, and a count nobody re-derives is the defect this list exists
+ * to prevent.
+ *
+ * `docs/SPEC.md`'s grammar section is the prose statement of the same list and is kept in step with it.
+ */
+export const CAPABILITY_NAMESPACE_PREFIXES = ["tool:", "ext:", "skill:", "agent:", "workspace:"] as const;
+
+/** Accept `read` or `tool:read` or `ext:pkg/tool` and normalise to a capability id. */
+export function normaliseCapability(raw: string): Capability {
+  const value = raw.trim();
+  if (CAPABILITY_NAMESPACE_PREFIXES.some((prefix) => value.startsWith(prefix))) return value;
+  return `tool:${value}`;
+}
+
+/** The capability that authorises routing a child to one registered workspace (ADR-0035). */
+export function workspaceCapability(workspaceId: string): Capability {
+  return `workspace:${workspaceId}`;
+}
+
+/**
+ * May this session route a child to workspace `id`?
+ *
+ * Mirrors `maySpawnDefinition` deliberately — same shape, same wildcard handling, same reason. Routing was
+ * the one governance dimension that did not attenuate (R-131, measured in
+ * `docs/probes/g36-workspace-attenuation`): the registry inherited into every child and nothing checked the
+ * caller's authority, so a child routed to `staging` could route its grandchild to `prod`.
+ *
+ * `tool:*` satisfies it because governance is opt-in — an ungoverned session holds the wildcard and must
+ * keep working exactly as before.
+ */
+export function mayRouteToWorkspace(ownGrant: readonly Capability[], workspaceId: string): boolean {
+  const held = new Set(ownGrant);
+  return held.has(WILDCARD) || held.has(WORKSPACE_WILDCARD) || held.has(workspaceCapability(workspaceId));
+}
+
+/**
+ * Characters that make a capability id mean something OTHER than one capability.
+ *
+ * A capability id is never a list. `PI_DADDY_GRANT` is comma-separated and `parseList` trims and splits
+ * it, so a comma inside a single id means the child reads it as several — including ones nothing granted.
+ * Newlines are here for the same reason one level out: the grant travels through an environment variable
+ * and, via `assertGrantIsWritable`, a shell-sourced file.
+ *
+ * **Measured, on the published 0.18.0.** A root holding `agent:*` (or `tool:*`) that requested
+ * `agent:x,tool:bash` had it admitted by the wildcard's prefix rule, written verbatim into the child's
+ * grant, and split by the child into `agent:x` + `tool:bash` — minting a capability the root never held,
+ * with `denied: []` so nothing recorded an escalation and the ledger line looked clean.
+ *
+ * Deliberately a blocklist of structurally dangerous characters rather than the full grammar whitelist in
+ * `isSafeCapability`. That whitelist is right where it lives — the boundary that GENERATES a grant — but
+ * this is the enforcement path, which must keep accepting whatever ids operators already have. A security
+ * patch to a released version should close the hole without inventing a new way to refuse a legitimate
+ * setup. `grant-env.ts` predicted this channel: "the third channel — whatever it turns out to be — should
+ * cost a refusal rather than an injection."
+ */
+const CAPABILITY_ID_SEPARATORS = /[,\r\n\0]/;
+
+/** False when an id would be read as more than one capability by any channel that carries it. */
+export function isWellFormedCapability(id: string): boolean {
+  return id.length > 0 && !CAPABILITY_ID_SEPARATORS.test(id) && id.trim() === id;
+}
+
+/**
+ * The STRICT grammar: a whitelist of what a capability id may look like, not a blocklist of what it may not.
+ *
+ * **Two consumers, and they are two different reasons for the same rule.** It lives here rather than in
+ * either of them because it shipped in one and was needed by both:
+ *
+ *  1. `skill-packages.ts` — the boundary that GENERATES a grant. R-77/R-78: a package declaring
+ *     `allowed-tools: Read,ext:x";touch /tmp/pwned;PI_DADDY_GRANT="` produced a `.pi/grants.env` that ran
+ *     arbitrary code the moment an operator sourced the line `init` prints.
+ *  2. `workspace.ts` — the operator registry, since ADR-0035 made a registry id the tail of a capability id
+ *     (`workspace:<id>`). That made the registry an input to this grammar, and it got the LOOSE
+ *     `isWellFormedCapability` blocklist instead, which review showed costs three things:
+ *     an id of literally `*` loaded and minted `WORKSPACE_WILDCARD`, so an operator naming ONE worktree held
+ *     routing authority over every id in the registry including ones added later;
+ *     an id containing a space became TWO capabilities, because `ceilingForDefinition` splits `allowed-tools`
+ *     on `[\s,]+` — `allowed-tools: read, workspace:prod bash` measured as
+ *     `['tool:bash','tool:read','workspace:prod']`, i.e. routing over production plus a shell, neither typed
+ *     by anyone (0.18.1's comma, one namespace over);
+ *     and quote/`$()`/backtick ids reached the `ROUTABLE WORKSPACES` block of the generated file, whose own
+ *     instructions tell the operator to paste them into `PI_DADDY_GRANT`.
+ *
+ * **A blocklist was the wrong shape for this and the comment on `isWellFormedCapability` says why it is the
+ * right shape THERE**: that one guards the enforcement path, which must keep accepting whatever ids operators
+ * already have. A registry is a file the operator writes and can rename, so refusing a hostile id costs
+ * nothing — and `grant-env.ts`'s standing warning applies to it exactly: *"the third channel — whatever it
+ * turns out to be — should cost a refusal rather than an injection."* The registry was the third channel.
+ */
+/**
+ * A workspace registry id, which is NOT a tool name and needed its own rule.
+ *
+ * `isSafeCapability` was reused here first, and that was the error: it is the grammar for a *tool* name, and
+ * it refused ids that published 0.18.1 accepted — `feature/x` above all. Git worktrees are routinely named
+ * after their branch, so a slash is the ordinary case, and a slash splits nothing: not the comma-separated
+ * grant, not `allowed-tools`' `[\s,]+`. Refusing it bought no safety and broke the common setup.
+ *
+ * What is refused, and why each one earns it:
+ *  - **whitespace** — `ceilingForDefinition` splits `allowed-tools` on `[\s,]+`, so `workspace:prod bash`
+ *    measured as `['tool:bash','tool:read','workspace:prod']`: routing over production plus a shell, neither
+ *    typed by anyone. 0.18.1's comma, one namespace over.
+ *  - **comma, CR, LF, NUL** — split a grant.
+ *  - **`*`** — collides with `WORKSPACE_WILDCARD`, so registering a worktree as `*` and granting
+ *    `workspace:*` believing it named that one root minted routing authority over the whole registry.
+ *  - **quotes, `$`, backticks, `;`, `&`, `|`, `<`, `>`, `(`, `)`, `\`, `#`** — reach the ROUTABLE WORKSPACES
+ *    block of a generated `.pi/grants.env`, whose own instructions tell the operator to paste the id into
+ *    `PI_DADDY_GRANT`. Sourcing the file was safe; following its instructions executed. R-77/R-78.
+ *  - **control characters and non-ASCII** — the generated file is reviewed in an editor and `/grants` prints
+ *    these; backspace and ANSI escapes let one id render as another. This is the one refusal that costs a
+ *    legitimate user something (a non-English worktree name), and it is a deliberate trade recorded as
+ *    breaking rather than asserted to cost nothing.
+ */
+export function isSafeWorkspaceId(id: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(id);
+}
+
+export function isSafeCapability(id: Capability): boolean {
+  const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
+  // `workspace:` delegates to the WORKSPACE grammar rather than reusing `segment`, and that is the fifth
+  // site of the same defect. `isSafeWorkspaceId` allows a slash because a git worktree is routinely named
+  // after its branch; `segment` does not, so this function refused `workspace:feature/x` — dropping the whole
+  // definition, exiting 1, and telling the operator "a capability id is tool:/skill:/agent:<name> or
+  // ext:<pkg>/<tool>", which does not even mention the namespace. Meanwhile the CHANGELOG told them slashes
+  // are fine. **The boundary that GENERATES grants could not emit the id shape the release advertises**, so
+  // the migration path for a breaking change was closed by the commit that documented it as open.
+  if (id.startsWith("workspace:")) return isSafeWorkspaceId(id.slice("workspace:".length));
+  return (
+    new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
+    new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id)
+  );
+}
+
+/**
+ * The write-side backstop, for every channel that joins capabilities into one string.
+ *
+ * `covered()` already refuses to GRANT a malformed id, so this should be unreachable — which is exactly
+ * why it exists. `grant-env.ts` says it better than I can: "the third channel — whatever it turns out to
+ * be — should cost a refusal rather than an injection. A guard that depends on my enumeration being
+ * complete is not a guard." The propagation channel turned out to be that third channel, and it had no
+ * backstop while the file-writing channel did.
+ *
+ * Loud rather than silently filtered: a malformed id here means something upstream admitted one, and
+ * dropping it quietly would hide the defect that produced it.
+ */
+export function assertCapabilitiesArePropagatable(grant: readonly Capability[]): void {
+  const malformed = grant.filter((c) => !isWellFormedCapability(c));
+  if (malformed.length === 0) return;
+  throw new GovernanceRefusal(
+    refusal(
+      "GRANT_ID_MALFORMED",
+      `refusing to build a child environment: ${JSON.stringify(malformed)} contain characters that are not ` +
+        `part of a capability id. The grant is comma-separated, so a child would read these as several ` +
+        `capabilities — including ones nothing granted. Report this: a malformed id reached propagation, ` +
+        `which means a guard upstream admitted it.`,
+      { malformed: malformed.join(" ") },
+    ),
+  );
+}