pi-daddy 0.13.0

package/extensions/grants-command.ts

@@ -0,0 +1,310 @@
+/**
+ * The `/grants` command — session status, approvals, and ledger integrity.
+ *
+ * Extracted from `extensions/grants.ts` because that file is where every wiring bug in this package has
+ * lived (the G7 `NaN` bound, the discarded `isError`, the unconditional `delegate` registration, R-28's
+ * omitted argument), and three independent reviewers flagged its size before any of them was found. A
+ * read-only diagnostic is the cleanest thing to lift out: nothing calls it, so it cannot be part of a
+ * governance path.
+ *
+ * It takes its dependencies as an **explicit context object** rather than closing over module state. That is
+ * the point of the extraction: what this command can see is now written down in one interface instead of
+ * being whatever happened to be in scope.
+ */
+
+import type { Capability } from "../src/resolve.ts";
+import type { Catalog } from "../src/catalog.ts";
+import type { SkillDefinition } from "../src/definitions.ts";
+import type { GatedPlan } from "./run-delegation.ts";
+import { loadApprovals, revokeAll, revokeApproval, type SubjectLookup } from "../src/approval-store.ts";
+import { verifyLedger } from "../src/ledger.ts";
+
+export interface GrantsCommandContext {
+  cwd: string;
+  governed: boolean;
+  ownGrant: Capability[];
+  observed: boolean;
+  depth: number;
+  maxDepth: number;
+  ledgerPath?: string;
+  catalog: Catalog;
+  definitions: Map<string, SkillDefinition>;
+  sessionApprovals: Set<string>;
+  /** Key → body digest, as `parseInherited` returns it (ADR-0022). Only `.size` is read here. */
+  inheritedApprovals: Map<string, string | undefined>;
+  /** A definition's current ceiling and body digest, for the store's confused-deputy check (ADR-0019). */
+  snapshotOf: SubjectLookup;
+  /**
+   * What a real `delegate({agent: name})` would do, decided by the code that would do it.
+   *
+   * Was `delegationContext` plus a `planDelegation` call here, which shared the planner but not the
+   * **approval step** — so a definition whose one gated capability was covered by a valid persisted approval
+   * was listed as blocked while a spawn proceeded silently (R-38). Injecting the whole preview keeps the
+   * R-28 discipline where it belongs: this command asks what would happen instead of working it out.
+   */
+  previewDelegation: (name: string) => Promise<GatedPlan>;
+}
+
+/**
+ * How many definitions `/grants` previews. Each one runs the real planner, so this bounds work, not truth —
+ * and whatever it drops is now stated rather than silently omitted (R-48).
+ */
+const PREVIEW_LIMIT = 12;
+
+export const grantsCommand = {
+  description:
+    "Show this session's capability grant, delegation depth, and known agent-type ceilings; " +
+    "/grants approvals | /grants ledger | /grants revoke <key>|--all",
+handler: async (args: string, ctx: any) => {
+    // Everything this command may see, named in one place. Previously these were whatever happened to be in
+    // the enclosing closure — which is how a diagnostic came to disagree with the enforcer (R-28).
+    const {
+      cwd, governed, ownGrant, observed, depth, maxDepth, ledgerPath,
+      catalog, definitions, sessionApprovals, inheritedApprovals, snapshotOf, previewDelegation,
+    } = ctx.grants as GrantsCommandContext;
+
+    const [sub, target] = args.trim().split(/\s+/).filter(Boolean);
+
+    if (sub === "ledger") {
+      // The detector, made reachable. `verifyLedger` exists because nothing in this package had ever read
+      // a ledger back, so a torn line was indistinguishable from a spawn that never happened — and a
+      // check an operator cannot run is not a control.
+      if (!ledgerPath) {
+        ctx.ui.notify("grants: no ledger — set PI_GRANTS_LEDGER to record grants and refusals.", "warning");
+        return;
+      }
+      const report = await verifyLedger(ledgerPath);
+      if (!report.exists) {
+        ctx.ui.notify(`grants: ledger ${ledgerPath} does not exist yet (nothing has been delegated).`, "info");
+        return;
+      }
+      const lines = [
+        `grants: ledger ${ledgerPath}`,
+        `  records    ${report.records}`,
+        `  escalation ${report.escalationAttempts} attempt(s) — grants refused for exceeding what the session held`,
+        `  integrity  ${report.ok ? "OK" : `${report.corrupt.length} UNPARSEABLE LINE(S)`}`,
+      ];
+      for (const bad of report.corrupt.slice(0, 5)) lines.push(`    line ${bad.line}: ${bad.text}`);
+      // R-51. ADR-0018 advertises that the ledger answers "did these four children run the same
+      // instructions?" and "has this definition changed since?" — and nothing read `definitionDigest`, so
+      // both needed hand-written jq and the second was not reproducible with `sha256sum` (the digest covers
+      // the body, not the frontmatter). The comparison against disk uses the SAME `snapshotOf` the approval
+      // store uses, so this listing cannot disagree with what voids an approval.
+      if (report.definitions.length > 0) {
+        lines.push(`  instructions ${report.definitions.length} distinct version(s) across the recorded spawns`);
+        for (const d of report.definitions) {
+          const here = definitions.get(d.name);
+          const current = snapshotOf(d.name);
+          // F4: compare the SOURCE too. A ledger path exported once in a shell profile is shared by every
+          // project — nothing scopes `PI_GRANTS_LEDGER` per project — so two different `deploy` definitions
+          // in two checkouts were reported as one definition that had CHANGED, and the NOTE below called it
+          // a finding. `verifyLedger` has carried `source` all along; the listing simply never read it.
+          const state =
+            current === null
+              ? "no such definition here"
+              : here && here.source !== d.source
+                ? "another project's definition of the same name"
+                : current.bodySha256 === d.sha256
+                  ? "current"
+                  : "CHANGED since";
+          lines.push(`    ${d.name}  ${d.sha256.slice(0, 12)}  ${d.spawns} spawn(s)  — ${state}`);
+        }
+        // Two rows for one name is the finding, not a formatting quirk: the same definition ran under two
+        // different bodies inside this ledger.
+        // Only versions of the SAME file count as "ran under more than one version" — grouping by name
+        // alone turned two projects' same-named definitions into a fabricated instruction change.
+        const names = report.definitions.map((d) => `${d.name}\u0000${d.source}`);
+        for (const key of [...new Set(names)]) {
+          const name = key.slice(0, key.indexOf("\u0000"));
+          if (names.filter((n) => n === key).length > 1) {
+            lines.push(`    NOTE ${name} ran under more than one version of its instructions in this ledger`);
+          }
+        }
+      }
+      // ADR-0020's revisit trigger, made runnable. That ADR keeps the persistence layer on an ASSERTED
+      // fatigue argument and named the evidence that would settle it — `persisted` against `prompt` over a
+      // few weeks of real use — then said it "needs no new machinery". True of the data, false of the
+      // answer: nothing counted it, so the measurement required hand-written jq and never happened. R-51's
+      // shape exactly, and the reason that entry exists.
+      const { bySource, distinctBySource, unattributed, humanDenied, humanDeniedPairs } = report.approvals;
+      const attributed = Object.values(bySource).reduce((sum, n) => sum + n, 0);
+      // **Declines are reported on their own, not folded into the approvals block.** They were rendered
+      // inside this guard, so a ledger of nothing BUT declines — a session where the operator said no to
+      // everything, which is the strongest possible evidence the gate is working and the most alarming
+      // shape an audit can take — printed no mention of them at all. The number that argues hardest for
+      // this package's gating was invisible in exactly the ledger that argues hardest.
+      if (humanDenied > 0) {
+        lines.push(
+          `  declined   ${humanDenied} record(s) across ${humanDeniedPairs} distinct capability@subject ` +
+            `pair(s) — a human was asked and said no. Pairs is the number of DECISIONS: one *Deny* under a ` +
+            `fan-out writes one record per child.`,
+        );
+      }
+      if (attributed > 0 || unattributed > 0) {
+        lines.push(
+          `  approvals  ${bySource.prompt} prompt · ${bySource.persisted} persisted · ${bySource.session} session · ` +
+            `${bySource.inherited} inherited`,
+        );
+        // **Two numbers, because one of them would lie.** Counting `persisted` RECORDS as prompts avoided
+        // overstates the layer twentyfold in the obvious case: precedence is inherited → session →
+        // persisted → prompt, and `session` approvals are in memory and owe the store nothing, so twenty
+        // spawns under one persisted entry would have been ONE prompt and nineteen session hits without it.
+        // Distinct `capability@subject` pairs bounds it properly. The exact figure needs a session id the
+        // ledger does not carry, so the bound is printed AS a bound rather than dressed up as an answer.
+        // **Pairs against pairs.** The comparison ADR-0020 asks for is `persisted` vs `prompt`, and the
+        // first version printed persisted RECORDS against a denominator of ALL records — so widening a
+        // fan-out drove the ratio arbitrarily toward "delete the layer" with zero additional human
+        // decisions (`inherited` and `session` are written once per CHILD). Measured: the same two human
+        // approvals read as 69% at fan-out 8 and 3.8% at fan-out 512. `distinctBySource.prompt` was being
+        // computed and never shown, which is the number that makes the comparison honest.
+        lines.push(
+          `    ADR-0020: ${distinctBySource.persisted} persisted vs ${distinctBySource.prompt} prompted ` +
+            `capability@subject pair(s) — the comparison that decides Option 3.`,
+        );
+        lines.push(
+          `    (${bySource.persisted} persisted record(s) over ${attributed} attributed. RECORDS ARE AN ` +
+            `UPPER BOUND on prompts avoided, not a count: within one session only the first would have been ` +
+            `a prompt, and a wide fan-out inflates every per-record figure without any extra human decision. ` +
+            `Deleting the layer costs at most one prompt per pair per session.)`,
+        );
+        if (unattributed > 0) {
+          // States what was observed, not a cause. Pre-0.11.1 lines are the COMMON reason, and a torn line,
+          // a hand edit or an unrecognised source value produce the same count — asserting the version
+          // would be a guess dressed as a fact, in a report whose whole value is that its numbers mean what
+          // they say.
+          lines.push(
+            `    ${unattributed} not counted — the record named approved capabilities but no usable ` +
+              `per-capability source. Usually a line written before 0.11.1, where one scalar described the ` +
+              `whole set and over-claimed "prompt" (R-46); a damaged or hand-edited line reads the same.`,
+          );
+        }
+      }
+      if (!report.ok) {
+        // Deliberately not repaired. A corrupt line is evidence; rewriting the file to make it parse
+        // would destroy the one artifact an investigation has.
+        lines.push("  A corrupt line is EVIDENCE and is left alone. Concurrent writers on a non-POSIX");
+        lines.push("  filesystem (drvfs under /mnt, NFS) are the likely cause — move the ledger to a local path.");
+      }
+      ctx.ui.notify(lines.join("\n"), report.ok ? "info" : "error");
+      return;
+    }
+
+    if (sub === "approvals") {
+      const { valid, dropped } = await loadApprovals({ cwd, now: new Date(), snapshotOf });
+      // The count says "valid", and the ignored entries are listed below it — but a reader who stops at
+      // the first line would conclude the file is empty, so the ignored total goes on that same line.
+      const lines = [
+        `grants: ${valid.size} persisted approval${valid.size === 1 ? "" : "s"}` +
+          (dropped.length > 0 ? `, ${dropped.length} ignored` : ""),
+      ];
+      for (const [key, entry] of valid) {
+        lines.push(`  ${key}`);
+        lines.push(`    approved ${entry.approvedAt}, expires ${entry.expiresAt}`);
+      }
+      // Dropped entries are SHOWN, not silently omitted — otherwise a revoked-by-expiry approval looks
+      // like one that was never given. Malformed entries are also reported as "expired" by the store
+      // (a deliberate simplification so it need not extend EntryVerdict); relabel those here so a
+      // corrupt entry doesn't read as a timed-out one.
+      //
+      // This mirrors `isValidEntryShape` in `src/approval-store.ts` (all four required fields) and
+      // must be kept in step with it — it is a display-only relabeling of an entry the store already
+      // dropped, not a second validity decision, so it stays here rather than moving into `src/`.
+      for (const d of dropped) {
+        const raw = d.entry as Partial<Record<"approvedAt" | "expiresAt" | "cwd" | "grantAtApproval", unknown>>;
+        const shapeCorrupt =
+          typeof raw?.approvedAt !== "string" ||
+          typeof raw?.expiresAt !== "string" ||
+          typeof raw?.cwd !== "string" ||
+          !Array.isArray(raw?.grantAtApproval);
+        const verdict = shapeCorrupt ? "malformed" : d.verdict;
+        lines.push(`  (ignored) ${d.key} — ${verdict}`);
+      }
+      ctx.ui.notify(lines.join("\n"), "info");
+      return;
+    }
+
+    if (sub === "revoke") {
+      if (target === "--all") {
+        const ok = await revokeAll(cwd);
+        ctx.ui.notify(
+          // "in this project" is not padding: the store is shared by every project on the machine, and
+          // this used to clear all of them.
+          ok
+            ? "grants: all persisted approvals for this project revoked"
+            : "grants: failed to revoke — could not write the approvals file",
+          ok ? "info" : "warning",
+        );
+      } else if (!target) {
+        ctx.ui.notify("grants: usage — /grants revoke <capability>@<agent-type> | --all", "warning");
+      } else {
+        // R-49. This was a boolean, so a FAILED write printed "no persisted approval named X" — telling an
+        // operator that the thing they are revoking does not exist, while it survives. The three outcomes
+        // are three different facts and the worst of them was disguised as the most reassuring.
+        const outcome = await revokeApproval(cwd, target, snapshotOf, new Date());
+        ctx.ui.notify(
+          {
+            revoked: `grants: revoked ${target}`,
+            absent: `grants: no persisted approval named ${target}`,
+            // Says only what was checked. `failed` found the entry and could not remove it, so "still in
+            // effect" is verified; `busy` never got past the lock, so it claims nothing about the entry at
+            // all — asserting it there would be R-61 again, one size smaller.
+            failed:
+              `grants: ${target} was NOT revoked — the approvals file could not be written. It is still in ` +
+              `effect; check that the path is writable and try again.`,
+            // Names no cause, because at this point none was established: a lock held by another session,
+            // an exhausted file-descriptor table and a read-only path all land here identically, having
+            // read nothing. Guessing "another session is writing" would be wrong for two of the three.
+            busy:
+              `grants: ${target} could not be checked — the approvals file could not be opened for writing ` +
+              `(another session may hold it, or the path may not be writable). NOTHING was changed, and ` +
+              `this says nothing about whether that approval exists.`,
+          }[outcome],
+          outcome === "revoked" ? "info" : outcome === "absent" ? "warning" : "error",
+        );
+      }
+      return;
+    }
+
+    const { valid } = await loadApprovals({ cwd, now: new Date(), snapshotOf });
+    const lines = [
+      governed ? "grants: ACTIVE" : "grants: inactive (set PI_GRANTS_GRANT to govern this session)",
+      `  holding    ${ownGrant.join(", ") || "(nothing)"}${observed ? " (observed)" : " (inherited, not yet observed)"}`,
+      `  depth      ${depth} of max ${maxDepth}${maxDepth <= 0 ? " (spawning disabled)" : ""}`,
+      `  ledger     ${ledgerPath ?? "(not recording — set PI_GRANTS_LEDGER)"}`,
+      `  approvals  ${sessionApprovals.size} this session, ${valid.size} persisted` +
+        `${inheritedApprovals.size > 0 ? `, ${inheritedApprovals.size} inherited` : ""}` +
+        ` — /grants approvals`,
+      `  catalog    ${catalog.all.length} capabilities — ` +
+        `${catalog.byKind("builtin").length} builtin, ${catalog.byKind("extension").length} extension, ` +
+        `${catalog.byKind("skill").length} skill, ${catalog.byKind("agentType").length} agent-type`,
+    ];
+    // Runs the REAL planner AND the real approval step over each definition, so this listing cannot
+    // disagree with what a spawn would do — the R-28 lesson, kept structural rather than remembered.
+    const shown = [...definitions].slice(0, PREVIEW_LIMIT);
+    for (const [name] of shown) {
+      const { plan, approval } = await previewDelegation(name);
+      // Why it is allowed, when a standing approval is the reason. An `allow` that silently depends on a
+      // 30-day entry in a file elsewhere is precisely what an operator runs this command to discover, and
+      // R-38 was the version of this listing that could not have told them (it said BLOCK instead).
+      // R-46: name each capability's own source, since they can differ (persisted for one, a live prompt
+      // for another). The scalar this replaced picked one and applied it to the set.
+      const because =
+        plan.ok && approval && approval.approved.length > 0
+          ? `  (${approval.approved.map((c) => `${c} approved: ${approval.sources[c] ?? "?"}`).join("; ")})`
+          : "";
+      lines.push(
+        `    ${plan.ok ? "allow" : "BLOCK"}  ${name}` +
+          (plan.ok ? `  ${plan.effective.join(", ")}${because}` : ` — ${plan.reason}`),
+      );
+    }
+    // R-48. The cap is fine; the SILENCE was not. An operator running `/grants` to answer "what can this
+    // session spawn without asking me?" — the exact question R-38 was fixed for — cannot tell a definition
+    // that was omitted from one that does not exist, and the `catalog … N agent-type` line above
+    // contradicts the short list with no explanation. Map order is discovery order, so the entries dropped
+    // are the GLOBAL ones (`~/.pi/agent/skills`), which is the least obvious thing to lose.
+    if (definitions.size > shown.length) {
+      lines.push(`    … and ${definitions.size - shown.length} more not shown (first ${PREVIEW_LIMIT} only)`);
+    }
+    ctx.ui.notify(lines.join("\n"), "info");
+  },
+};

package/extensions/grants.ts

@@ -0,0 +1,346 @@
+/**
+ * pi-daddy — the extension entry point pi loads.
+ *
+ * Wiring only; every decision lives in `../src/` as a pure function so it can be tested without pi. What
+ * remains in *this* file is the part that is genuinely about pi: the hooks, the tripwire, and the four
+ * registrations. The session state moved to `./session.ts`, the approval flow to `./approvals.ts`, the two
+ * delegation tools to `./delegation.ts` and the `/grants` command to `./grants-command.ts`.
+ *
+ * That split is not cosmetic. Every wiring bug this package has had lived here — the G7 `NaN` bound, the
+ * discarded `isError`, the unconditionally-registered `delegate` (S-5), R-28's omitted argument — and all
+ * four were defects of *scope*: a value that was whatever happened to be in the closure at one call site.
+ * Each module now takes the session as an argument, so what it can see is written down.
+ *
+ * Propagation is race-free by construction — see `../src/propagation.ts`. Nothing per-child is pushed:
+ * the environment carries only parent-level facts (identical for every sibling), never a value computed
+ * for one specific spawn. It is published at session start, and republished whenever this session's own
+ * approvals change (a human approves something new for the session) — never per spawn, never keyed to a
+ * particular child. Each republish stays safe because the value is still `ownGrant`-shaped: this
+ * session's own approvals intersected with its own grant, identical for every sibling regardless of which
+ * spawn triggered the human prompt, and `childEnv` clamps it to the grant again on the way out. Each
+ * child derives its own grant from the tool array of its first provider request.
+ */
+
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WILDCARD } from "../src/pi-tools.ts";
+import { AGENT_WILDCARD } from "../src/resolve.ts";
+import { legacyApprovalsPath, sharedApprovalsPath } from "../src/approval-store.ts";
+import { buildCatalog } from "../src/catalog.ts";
+import { loadDefinitions } from "../src/definitions.ts";
+import { appendRecord, buildRecord, verifyLedger } from "../src/ledger.ts";
+import { deriveOwnGrant, observeToolNames } from "../src/propagation.ts";
+import { snapshotOf } from "./approvals.ts";
+import { registerDelegationTools } from "./delegation.ts";
+import { grantsCommand } from "./grants-command.ts";
+import { planWithApprovals } from "./run-delegation.ts";
+import { createGrantsSession } from "./session.ts";
+
+const SPAWN_TOOLS = new Set(["Agent", "subagent", "spawn_agent"]);
+
+export default function (pi: ExtensionAPI) {
+  // The path pi loads as the extension, so a child granted `tool:delegate` can be started with `-e <this>`.
+  // Only this file can say so about itself, which is why the session takes it rather than deriving it.
+  const extensionPath = (() => {
+    try {
+      return fileURLToPath(import.meta.url);
+    } catch {
+      return undefined;
+    }
+  })();
+
+  const session = createGrantsSession(extensionPath);
+
+  // Filled in by `registerDelegationTools` at the bottom of this function. A holder rather than a reordering,
+  // because the hooks below have to be registered before the tools and both need to call it — the tool
+  // schemas describe which definitions are spawnable, and nothing knows that until a hook has run (R-39).
+  const delegation = { refreshSpawnable: () => {} };
+
+  pi.on("session_start", async (_event, ctx) => {
+    session.cwd = ctx.cwd;
+    try {
+      // Guarded together, and guarded at all because of R-60 rather than because either one throws today:
+      // both loaders swallow their own filesystem errors, so this catch is currently unreachable. The point
+      // is that "currently" is not a property anyone can rely on — `verifyLedger` was also harmless until
+      // the day it was not, and the cost of finding out is every control below this line, silently.
+      // Discovery failing is worth its own sentence anyway: a session with no definitions can still
+      // delegate by `tools:`, and an operator whose `agent:` spawns have all started failing deserves to
+      // know it was the *scan* that broke rather than the grant.
+      try {
+        session.definitions = await loadDefinitions(ctx.cwd);
+        session.catalogReady = buildCatalog({ cwd: ctx.cwd, observedTools: session.observedTools });
+        session.catalog = await session.catalogReady;
+      } catch (error) {
+        ctx.ui.notify(
+          `grants: could not read this project's definitions or capability catalog ` +
+            `(${error instanceof Error ? error.message : String(error)}) — no SKILL.md definition can be ` +
+            `spawned this session, and delegation by tools: is unaffected. Governance itself is unaffected: ` +
+            `it is enforced by --tools when a child is spawned.`,
+          "error",
+        );
+      }
+      session.publishChildEnv();
+      // The definitions now exist, so the `delegate` schema can finally name them (R-39). pi serialises a
+      // tool's schema at REQUEST time, not at registration — measured — which is what makes this reach the
+      // model at all.
+      delegation.refreshSpawnable();
+      // A malformed bound is now loud as well as safe. Silently disabling spawning would be just as
+      // confusing as silently disabling the limit was dangerous — the operator set the variable, so
+      // they need to know it did not take effect (G7 / A-S4).
+      if (session.malformedBounds.length > 0) {
+        ctx.ui.notify(
+          `grants: ${session.malformedBounds.join(" and ")} could not be read as a non-negative integer — ` +
+            `spawning is disabled for this session (failing closed)`,
+          "warning",
+        );
+      }
+      // ADR-0014: a pre-0.6 in-workspace approvals file is IGNORED, not migrated — importing it would
+      // import exactly the entries whose trustworthiness the move exists to remove. Say so, because an
+      // operator whose approvals silently stopped applying deserves to know why.
+      // ADR-0020: the pre-0.11 single shared store is ignored, not migrated. Same reasoning shape as the
+      // legacy file below — an operator whose approvals silently stopped applying must be told why — but a
+      // different reason for not migrating: splitting it by `cwd` would be lossless, and it is still declined
+      // because one-shot migration code in the layer with nine defects buys less than one re-approval costs.
+      try {
+        if (existsSync(sharedApprovalsPath())) {
+          ctx.ui.notify(
+            `grants: ignoring ${sharedApprovalsPath()} — approvals are now stored one file per governed ` +
+              `directory (ADR-0020), because a single shared file could not hold two projects' approvals ` +
+              `for a same-named definition. Re-approve when next asked. **Deleting the old file is ` +
+              `recommended, not merely safe**: entries written by 0.10.x may contain the task text a model ` +
+              `composed at approval time, which this version no longer stores anywhere (ADR-0021).`,
+            "warning",
+          );
+        }
+      } catch {
+        /* never throw into the agent loop */
+      }
+      try {
+        if (existsSync(legacyApprovalsPath(ctx.cwd))) {
+          ctx.ui.notify(
+            `grants: ignoring ${legacyApprovalsPath(ctx.cwd)} — approvals now live outside the workspace ` +
+              `(it was writable by the very agents it gated). Re-approve when next asked; the old file is ` +
+              `safe to delete.`,
+            "warning",
+          );
+        }
+      } catch {
+        /* never throw into the agent loop */
+      }
+      // R-47. `gatedBlocked` filters `requested`, and for a definition spawn `requested` is that
+      // definition's CEILING — which never contains `agent:<name>`, because the authorisation check
+      // (ADR-0017) is a separate, ungated branch. So `PI_GRANTS_GATED=agent:deploy`, written by an operator
+      // who read "it attenuates like any other capability" and meant "ask me before deploy runs", produces
+      // no dialog and no warning. It DOES bite when a definition passes the id down in its own
+      // `allowed-tools`, so the flag half-works — which is worse than not working, and is R-25's shape in
+      // the namespace ADR-0017 just promoted out of exactly that state.
+      //
+      // Warned rather than enforced: making it gate the spawn is a behaviour change and wants a decision.
+      // Silence is the part that is indefensible either way.
+      // `agent:*` grants no tools, but it authorises every definition in BOTH skill roots — including
+      // `~/.pi/agent/skills/`, which other software installs into, so ADR-0017's "an operator-authored
+      // file" is not true of everything it covers. Paired with a shell that is every body on disk running
+      // with `bash`. `docs/SPEC.md` calls the combination poor and nothing detected it, which is R-47's
+      // shape in a control shipped one day later.
+      if (session.ownGrant.includes(AGENT_WILDCARD) && session.gated.length === 0 && session.ownGrant.includes("tool:bash")) {
+        ctx.ui.notify(
+          `grants: PI_GRANTS_GRANT pairs agent:* with tool:bash and gates nothing — every SKILL.md in ` +
+            `this project AND in ~/.pi/agent/skills (which other tools install into) may run with a shell. ` +
+            `Enumerate the agent: ids you mean, or leave PI_GRANTS_GATED at its default so bash is asked for.`,
+          "warning",
+        );
+      }
+      const inertGates = session.gated.filter((c) => c.startsWith("agent:"));
+      if (inertGates.length > 0) {
+        ctx.ui.notify(
+          `grants: ${inertGates.join(", ")} in PI_GRANTS_GATED does NOT gate spawning that definition — ` +
+            `the authorisation check for a definition is separate and ungated, so a human is never asked. ` +
+            `It applies only where a definition passes the id down in its own allowed-tools. To control ` +
+            `which definitions may run, withhold the agent: capability from PI_GRANTS_GRANT instead.`,
+          "warning",
+        );
+      }
+      // R-34. `verifyLedger` existed and nothing ran it, so a torn line was detectable and undetected —
+      // and a check an operator has to know to run is not a control, it is a feature. Setting
+      // `PI_GRANTS_LEDGER` already means "I want an audit trail"; noticing that the trail is damaged is
+      // part of keeping one.
+      //
+      // Corruption only, deliberately. The escalation count is a *query* — `/grants ledger` answers it —
+      // and reporting historical attempts unprompted at every start is the fatigue shape R-25 names, which
+      // ends with the operator ignoring the line that matters.
+      //
+      // Awaited rather than fired and forgotten: it is one read, on a path that already awaits two
+      // directory scans, and awaiting is what guarantees the warning reaches a live `ctx.ui`.
+      //
+      // R-60. `verifyLedger` RETHROWS every read error that is not ENOENT — right for `/grants ledger`,
+      // where an operator asked a direct question and deserves the failure — and this call is the only one
+      // that makes it inside the blanket catch below. So an unreadable ledger threw here and cancelled every
+      // remaining control **in silence**: no alarm, and not even the `holding [...]` line that is the one
+      // sign governance is on. Confirmed by execution — `PI_GRANTS_LEDGER` naming a directory produced ZERO
+      // notifications from a governed session. A trail that cannot be read at all is a worse failure than a
+      // torn line, and it was the one case this control said nothing about.
+      if (session.ledgerPath) {
+        try {
+          const report = await verifyLedger(session.ledgerPath);
+          if (report.exists && !report.ok) {
+            ctx.ui.notify(
+              `grants: ledger ${session.ledgerPath} has ${report.corrupt.length} unparseable line(s) — ` +
+                `first at line ${report.corrupt[0]?.line}. A torn line is indistinguishable from a spawn that ` +
+                `never happened, so this audit trail is incomplete. Run /grants ledger for detail; the file is ` +
+                `left alone because a corrupt line is evidence.`,
+              "error",
+            );
+          }
+        } catch (error) {
+          ctx.ui.notify(
+            `grants: ledger ${session.ledgerPath} could not be read ` +
+              `(${(error as { code?: string }).code ?? String(error)}) — nothing can be verified about this ` +
+              `audit trail, and the first spawn will refuse rather than proceed unrecorded. Check that ` +
+              `PI_GRANTS_LEDGER names a writable FILE.`,
+            "error",
+          );
+        }
+      }
+      if (session.governed) {
+        ctx.ui.notify(
+          `grants: depth ${session.depth}/${session.maxDepth}, holding [${session.ownGrant.join(", ") || "nothing"}]`,
+          "info",
+        );
+      }
+    } catch (error) {
+      // Rule 8 — fail closed, and be LOUD about it. Swallowing is still right: a startup fault must not
+      // reach the agent loop. Swallowing SILENTLY is what let R-60 exist, and would let the next one exist
+      // too, because every control added above this line is cancelled by any throw before it with no trace.
+      // Deliberately says which checks are affected rather than claiming they passed.
+      try {
+        ctx.ui.notify(
+          `grants: session start did not complete — ${error instanceof Error ? error.message : String(error)}. ` +
+            `Checks and setup after the failure did not run, so definitions may be missing and a delegation ` +
+            `may refuse. The grant itself is unaffected: it is enforced by --tools when a child is spawned.`,
+          "error",
+        );
+      } catch {
+        /* a UI that cannot be notified is the one failure there is nowhere to report */
+      }
+    }
+    return undefined;
+  });
+
+  // Observe this session's real tool surface once, and tighten the grant to it. Authoritative because
+  // it is exactly what pi sent the model.
+  pi.on("before_provider_request", (event) => {
+    try {
+      if (session.observed) return undefined;
+      const names = observeToolNames(event.payload);
+      if (names === null) return undefined;
+      session.observed = true;
+      session.observedTools = names;
+      session.ownGrant = deriveOwnGrant(session.inherited, names);
+      session.publishChildEnv();
+      // The grant can only have narrowed, so what is spawnable can only have shrunk. Refreshed for the NEXT
+      // request: this hook runs after the current payload's tools were already serialised.
+      delegation.refreshSpawnable();
+      // Refresh the catalog now that the real tool surface is known — this is the only moment extension
+      // tools become visible, so it is the only moment `ext:`/`tool:` grants can be validated.
+      // Keep the handle: a concurrent `delegate` awaits this rather than reading a half-built catalog.
+      // The `catch` resolves to the CURRENT catalog rather than rejecting, so a failed refresh degrades
+      // to the previous view instead of failing every delegation in the session.
+      session.catalogReady = buildCatalog({ cwd: session.cwd, observedTools: names })
+        .then((c) => (session.catalog = c))
+        .catch(() => session.catalog);
+    } catch {
+      /* never throw into the agent loop */
+    }
+    return undefined; // inspect only — never replace the payload
+  });
+
+  /**
+   * Tripwire, not a fence — ADR-0016 point 5.
+   *
+   * This hook used to compute what `@tintinweb/pi-subagents` would grant a child, by re-implementing
+   * that package's tool-resolution rules (ADR-0013). That port is gone with this change, and so is
+   * R-31: there is no longer another project's private function to keep in step, and no permissive
+   * drift when it moves.
+   *
+   * What remains is the reason not to simply delete the hook. This package is now the spawner, so a
+   * third-party spawn tool appearing in a governed session means something can create a descendant that
+   * this package does not provision, does not bound by depth, and does not record. Installing one is a
+   * single command. **Refusing is cheap and silence is not**, so the tripwire refuses and names itself.
+   *
+   * It cannot be complete, and says so rather than implying otherwise: `subagents:rpc:spawn` reaches
+   * `manager.spawn()` over the event bus and never produces a `tool_call` at all (ADR-0013 Finding 6),
+   * so a tool-name check cannot see it. This catches the ordinary case loudly; it is not a boundary.
+   */
+  pi.on("tool_call", async (event) => {
+    if (!session.governed || !SPAWN_TOOLS.has(event.toolName)) return undefined;
+
+    const reason =
+      `grants: "${event.toolName}" spawns sub-agents outside this session's governance — refused. ` +
+      `This session grants capabilities by spawning them itself (\`delegate\`), so a child created by ` +
+      `another extension would hold whatever that extension decided, with no grant, no depth bound and ` +
+      `no ledger entry. Use \`delegate\` instead. If you meant to run ungoverned, unset PI_GRANTS_GRANT.`;
+
+    if (session.ledgerPath) {
+      // Recorded like any other refusal: an audit that omits the spawns we turned away cannot answer
+      // "did anything try to get around this?", which is the one question a tripwire exists to answer.
+      await appendRecord(
+        { path: session.ledgerPath, strict: true },
+        buildRecord({
+          parentId: `d${session.depth}`,
+          childId: `${event.toolName}@d${session.depth + 1}`,
+          depth: session.depth + 1,
+          agentType: event.toolName,
+          // The wildcard is the honest record: an unknown spawner was going to hand this child whatever
+          // IT decided, and we have no way to know what that would have been.
+          requested: [WILDCARD],
+          parentGrant: session.ownGrant,
+          result: { effective: [], denied: [WILDCARD], clipped: [], gatedBlocked: [], universal: [], subsumedBy: [] },
+          blocked: true,
+          reason,
+          now: new Date(),
+        }),
+      );
+    }
+    return { block: true, reason };
+  });
+
+  // Governed delegation. Unlike the tripwire above this PROVISIONS: the grant is an argument, so the
+  // orchestrator hands each child exactly the capabilities it should have. Registered only when this
+  // session may delegate, so withholding `tool:delegate` genuinely makes a session a leaf.
+  //
+  // Registration necessarily happens HERE, before any hook has run, so the tools cannot yet know which
+  // definitions exist — hence `refreshSpawnable`, called from both hooks above once they do. R-39 is what
+  // happens without it: every model in every governed session is told `Available: none`.
+  delegation.refreshSpawnable = registerDelegationTools(pi, session).refreshSpawnable;
+
+  pi.registerCommand("grants", {
+    ...grantsCommand,
+    // Built per invocation and spelled out field by field, rather than passing the session whole: what a
+    // read-only diagnostic may see is a decision, and `GrantsCommandContext` is where it is recorded.
+    handler: (args, ctx) =>
+      grantsCommand.handler(args, {
+        ...ctx,
+        grants: {
+          cwd: session.cwd,
+          governed: session.governed,
+          ownGrant: session.ownGrant,
+          observed: session.observed,
+          depth: session.depth,
+          maxDepth: session.maxDepth,
+          ledgerPath: session.ledgerPath,
+          catalog: session.catalog,
+          definitions: session.definitions,
+          sessionApprovals: session.sessionApprovals,
+          inheritedApprovals: session.inheritedApprovals,
+          snapshotOf: (subject: string) => snapshotOf(session, subject),
+          // The REAL delegation path, minus the one thing a diagnostic must never do. `ctx: null` is what
+          // says so: stored approvals count exactly as they would for a spawn, and no human is asked
+          // (R-38). Passing `ctx` here would let `/grants` raise a dialog, and passing `hasUI: false` would
+          // make every gated definition report "no interactive user" instead of what actually blocks it.
+          previewDelegation: (name: string) =>
+            planWithApprovals(session, { task: "(preview)", agent: name }, {}, null),
+        },
+      }),
+  });
+}