pi-daddy 0.13.0

package/extensions/run-delegation.ts

@@ -0,0 +1,270 @@
+/**
+ * Plan, gate, audit and run ONE governed child — the whole of a delegation except its tool surface.
+ *
+ * Split from `extensions/delegation.ts` when ADR-0019 pushed that file to 403 lines and
+ * `test/file-size.test.ts` refused it. Raising the cap the day after adding it would have neutered the
+ * guard, so the file was split the way the failure message said to. The seam is the natural one: this
+ * module is *what a delegation does*, `delegation.ts` is *how pi is told about it*.
+ *
+ * Everything reads the live session through the object it is handed; nothing here keeps its own copy of
+ * the grant, the catalog or the definitions, because a copy taken at load time is a copy taken before the
+ * tool surface is observed.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { DELEGATE_SUBJECT, shouldSeekApproval } from "../src/approval.ts";
+import { maySpawnDefinition, planDelegation } from "../src/delegate.ts";
+import { MAX_CHILDREN_PER_CALL, childSpawnId, splitBudget } from "../src/fanout.ts";
+import { appendRecord, buildRecord } from "../src/ledger.ts";
+import { mergeChildEnv } from "../src/propagation.ts";
+import type { Capability } from "../src/resolve.ts";
+import { ENV_CHILD_TIMEOUT, runChild, timeoutFromEnv } from "../src/run-child.ts";
+import { runHerdrPane } from "../src/run-herdr.ts";
+import { obtainApprovals, republishable, snapshotOf, type ApprovalOutcome, type ApprovalUIContext } from "./approvals.ts";
+import { ENV_HERDR_KEEP_PANE, ENV_HERDR_WORKSPACE, type GrantsSession } from "./session.ts";
+
+/** What one child was asked to do. The shape both tools accept, per child. */
+interface ChildSpec {
+  task: string;
+  agent?: string;
+  tools?: string[];
+  model?: string;
+}
+
+/**
+ * The slice of pi's `ExtensionContext` a delegation needs.
+ *
+ * It extends `ApprovalUIContext` rather than being cast to it at the call site. pi hands `execute` its full
+ * context, so `ui`/`hasUI`/`mode` were always present — but the local type omitted them and an `as never`
+ * bridged the gap, which is the same "a value that was whatever happened to be in scope" shape the module
+ * header lists four defects for.
+ */
+interface DelegationToolContext extends ApprovalUIContext {
+  cwd: string;
+  model?: { provider: string; id: string };
+}
+
+/** A planned delegation, plus whatever approvals contributed to it. */
+export interface GatedPlan {
+  plan: ReturnType<typeof planDelegation>;
+  /** Absent when the gate was never reached — i.e. the plan succeeded or failed for another reason. */
+  approval?: ApprovalOutcome;
+}
+
+/**
+ * Plan a delegation and satisfy its gate as far as approvals allow.
+ *
+ * **Spelled once, on purpose.** The enforcer and the `/grants` listing both come through here, so a preview
+ * cannot claim an outcome a spawn would not produce (R-38, and R-28 before it). The two differ in exactly
+ * one respect, which is the one thing a read-only diagnostic must not do: pass `ctx: null` and no human is
+ * asked — stored approvals still count, and the plan's own reason is left to speak for whatever is left.
+ *
+ * Deliberately NOT pre-filling `approved` on the first plan: pre-filling would satisfy an inherited-approval
+ * gate silently, before `gatedBlocked` ever surfaced, so `obtainApprovals` would never run and the ledger
+ * would lose the `approvalSource: "inherited"` record ADR-0010 relies on as inheritance's compensating
+ * control. `approved ⊆ grant` holds regardless — this is about the audit trail, not privilege.
+ */
+export async function planWithApprovals(
+  session: GrantsSession,
+  request: ChildSpec & { model?: string },
+  extra: Record<string, unknown>,
+  ctx: ApprovalUIContext | null,
+  signal?: AbortSignal,
+): Promise<GatedPlan> {
+  // Spelled ONCE. It is asked for twice — when the human is prompted, and when the answer is fed back into
+  // the re-plan — and two spellings of one argument is the defect R-28 was.
+  const approvalSubject = request.agent ?? DELEGATE_SUBJECT;
+
+  let plan = planDelegation(request, { ...(await session.delegationContext()), ...extra });
+  if (plan.ok || !shouldSeekApproval(plan.result)) return { plan };
+
+  let approval: ApprovalOutcome | undefined;
+  try {
+    approval = await obtainApprovals(
+      session,
+      plan.result?.gatedBlocked ?? [],
+      // ADR-0019. A definition IS a human-authored subject — operator-written, and nameable only by a
+      // session holding `agent:<name>` (ADR-0017) — so the approval is keyed to it and `always` is on
+      // offer. The `tools:` form keeps `<delegate>` and keeps being denied `always`, because there the
+      // original reasoning is untouched: the model chose both the task and the tool list.
+      approvalSubject,
+      request.agent ? "definition" : "delegate",
+      ctx,
+      request.task,
+      signal,
+    );
+    const outcome = approval;
+    if (outcome.approved.length > 0) {
+      plan = planDelegation(request, {
+        // The scope is the REAL one: a `once` approval still authorises this spawn, and
+        // `inheritApprovals` then keeps it from reaching the child. See ADR-0014. R-29 is what makes
+        // this safe under fan-out: a `once` is consumed by exactly one concurrent caller.
+        ...(await session.delegationContext([
+          ...republishable(session),
+          ...outcome.approved.map((capability) => ({
+            capability,
+            subject: approvalSubject,
+            // F1b: this capability's OWN scope. It was `outcome.scope` — one variable overwritten by the
+            // last capability answered — so approving A `once` and B `session` re-stamped A as `session`
+            // and handed a whole subtree an approval a human gave for a single spawn. That is ADR-0014's
+            // A-S1 defect, reopened by a mixed answer.
+            scope: outcome.scopes[capability] ?? ("once" as const),
+            // F1a: and the pin. Without it every freshly-approved capability crossed to the child
+            // UNPINNED, and `verifyInherited` honours an unpinned entry by decision — so ADR-0022's
+            // headline property was false on the hot path, for the approvals it was written to cover.
+            // Taken from this session's snapshot, the same source `republishable` uses.
+            bodySha256: snapshotOf(session, approvalSubject)?.bodySha256,
+          })),
+        ])),
+        ...extra,
+      });
+    }
+    if (!plan.ok && approval.reason) plan = { ...plan, reason: approval.reason };
+  } catch (error) {
+    plan = { ...plan, reason: `grants: approval flow failed, denying (${String(error)})` };
+  }
+
+  return { plan, approval };
+}
+
+interface DelegationOutcome {
+  ok: boolean;
+  text: string;
+  reason?: string;
+  granted: Capability[];
+  depth: number;
+  exitCode: number | null;
+}
+
+/**
+ * Plan, gate, audit and run ONE governed child. Shared by `delegate` and `delegate_all`.
+ *
+ * Extracted rather than copied, for the reason R-28 exists: this is where the grant is resolved, the
+ * human is asked, and the ledger is written, and two call sites spelling that out separately is how one
+ * of them comes to omit a step. `delegate_all` differs from `delegate` only in running several of these
+ * concurrently and reporting each outcome — not in any governance rule.
+ *
+ * Returns an outcome instead of throwing, because a fan-out must be able to report "three succeeded, one
+ * was refused". `delegate` converts a failure back into a throw to keep its own contract, which matters:
+ * `AgentToolResult` has no `isError` field, so a returned error is silently discarded by pi.
+ */
+export async function runOneDelegation(
+  session: GrantsSession,
+  spec: ChildSpec,
+  ids: { parentId: string; childId: string },
+  budget: number | undefined,
+  ctx: DelegationToolContext,
+  signal: AbortSignal | undefined,
+): Promise<DelegationOutcome> {
+  // pi resolves a BARE model id to an unauthenticated provider and the child dies at startup — the id
+  // alone is not enough, it must be qualified with its provider (`Model<Api>` carries both).
+  const defaultModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+  const request = { task: spec.task, agent: spec.agent, tools: spec.tools, model: spec.model ?? defaultModel };
+  const extra = { fanoutBudget: budget, spawnId: ids.parentId, childSpawnId: ids.childId };
+
+  // Planning and the gate live in `planWithApprovals`, shared with the `/grants` preview so the two cannot
+  // disagree (R-38). This call is the enforcing one: it passes `ctx`, so a human CAN be asked.
+  let { plan, approval: approvalOutcome } = await planWithApprovals(session, request, extra, ctx, signal);
+
+  // G6 / B-I3: no `&& plan.result` guard — `planDelegation` always carries one now.
+  if (session.ledgerPath) {
+    await appendRecord(
+      { path: session.ledgerPath, strict: true },
+      buildRecord({
+        // F8: real ids, not depth labels. Four concurrent siblings used to produce four lines identical
+        // except `ts`, so the ledger could not be joined to a result, a process, or the child's own
+        // lines one level down.
+        parentId: ids.parentId,
+        childId: ids.childId,
+        depth: plan.childDepth,
+        agentType: spec.agent ?? "delegate",
+        requested: plan.requested,
+        parentGrant: session.ownGrant,
+        result: plan.result,
+        blocked: !plan.ok,
+        reason: plan.reason,
+        approved: approvalOutcome?.approved,
+        approvalSources: approvalOutcome?.sources,
+        approvalScopes: approvalOutcome?.scopes,
+        humanDenied: approvalOutcome?.humanDenied,
+        gateOutcome: approvalOutcome?.gateOutcome,
+        // ADR-0018: taken from the PLAN, never re-derived here. The B-I3 lesson — a call site that
+        // recomputed the digest could record one the planner never used.
+        definitionDigest: plan.definitionDigest,
+        now: new Date(),
+      }),
+    ).catch((error) => {
+      // G6 / A-R4 + B-I2: fail closed. This path PROVISIONS, so an unrecorded delegation would be a
+      // child running with granted capabilities and no audit line.
+      plan = { ...plan, ok: false, reason: `grants: ledger write failed, denying — ${String(error)}` };
+    });
+  }
+
+  if (!plan.ok) {
+    return { ok: false, text: "", reason: plan.reason, granted: [], depth: plan.childDepth, exitCode: null };
+  }
+
+  // G8: bounded output, a wall-clock timeout with SIGTERM->SIGKILL escalation, and an abort observed
+  // even if it happened before we got here. See src/run-child.ts for why each one exists.
+  //
+  // ADR-0016 point 6: two executors, one plan. `runChild` is the default because it needs nothing
+  // installed; herdr gives the same governed argv a VISIBLE, attachable pane. Opt-in per session rather
+  // than auto-detected — a governed run must not silently relocate because a binary is on PATH.
+  const output = session.useHerdr
+    ? await runHerdrPane({
+        args: plan.args.slice(0, -1),
+        // The task is delivered as a prompt, so it never reaches argv at all. `plan.args` still ends
+        // with the neutralised task (planSpawn is executor-agnostic), hence the slice — and the leading
+        // space `neutralisePrompt` added is stripped because there is no parser to defend against here.
+        prompt: plan.args[plan.args.length - 1].trimStart(),
+        // Grant/depth/ledger go on the PANE: `herdr agent start` has no --env, but a pane's environment
+        // reaches the shell that launches the agent (docs/probes/g16-herdr).
+        env: plan.env,
+        cwd: ctx.cwd,
+        name: `${spec.agent ?? "delegate"}-${ids.childId}`,
+        workspace: process.env[ENV_HERDR_WORKSPACE],
+        signal,
+        timeoutMs: timeoutFromEnv(process.env[ENV_CHILD_TIMEOUT]),
+        keepPane: process.env[ENV_HERDR_KEEP_PANE] === "1",
+      })
+    : await runChild({
+        command: "pi",
+        args: plan.args,
+        // Explicit per-child env — the parent's own grant vars must not leak in. A plain spread would
+        // not achieve that: a key `plan.env` does not set is a key the parent's value survives into, so
+        // `mergeChildEnv` strips every governance variable first and lets only the plan put them back.
+        env: mergeChildEnv(process.env, plan.env),
+        cwd: ctx.cwd,
+        signal,
+        timeoutMs: timeoutFromEnv(process.env[ENV_CHILD_TIMEOUT]),
+      });
+
+  // G8: a child that failed is reported as a failure. A non-zero exit, a timeout and a truncated flood
+  // all used to come back as ordinary tool results, so the orchestrator read them as answers.
+  if (output.spawnError || output.aborted || output.timedOut || output.code !== 0) {
+    const why = output.spawnError
+      ? `could not be started: ${output.spawnError}`
+      : output.aborted
+        ? "was cancelled"
+        : output.timedOut
+          ? "exceeded its time limit and was killed"
+          : `exited with code ${output.code}`;
+    return {
+      ok: false,
+      text: output.text.trim(),
+      reason: `the sub-agent ${why}`,
+      granted: plan.effective,
+      depth: plan.childDepth,
+      exitCode: output.code,
+    };
+  }
+
+  return {
+    ok: true,
+    text: output.text.trim(),
+    granted: plan.effective,
+    depth: plan.childDepth,
+    exitCode: output.code,
+  };
+}

package/extensions/session.ts

@@ -0,0 +1,234 @@
+/**
+ * The session object — the one place this extension's state is named.
+ *
+ * Split out of `extensions/grants.ts`, which is where every wiring bug in this package has lived: the G7
+ * `NaN` bound, the discarded `isError`, the unconditionally-registered `delegate` (S-5) and R-28's omitted
+ * argument. Those four share a shape — a value that was *whatever happened to be in scope* at one call
+ * site. A closure over a dozen `let`s cannot be reviewed as a whole; an object whose fields are written
+ * down can, and it is the same move `grants-command.ts` was extracted under.
+ *
+ * Configuration is parsed once, at load time, and is `readonly`. The handful of genuinely mutable fields
+ * are the ones the hooks in `grants.ts` update as the session learns about itself — the grant tightens when
+ * the real tool surface is observed, the catalog and definitions arrive at `session_start`. Every other
+ * module reads them **through this object**, live, rather than capturing a copy at load time; capturing a
+ * copy of `ownGrant` before observation is exactly how a stale upper bound would become an enforced one.
+ */
+
+import { parseInherited, type InheritableApproval } from "../src/approval.ts";
+import { createApprovalGateProvider } from "../src/approval-prompt.ts";
+import { makeCatalog, skillPathsFromCatalog, type Catalog } from "../src/catalog.ts";
+import type { SkillDefinition } from "../src/definitions.ts";
+import { DELEGATE_CAPABILITY, type DelegationContext } from "../src/delegate.ts";
+import { budgetFromEnv } from "../src/fanout.ts";
+import { WILDCARD } from "../src/pi-tools.ts";
+import {
+  childEnv,
+  depthConfig,
+  deriveOwnGrant,
+  gatedFromEnv,
+  ENV_APPROVED,
+  ENV_DEPTH,
+  ENV_FANOUT,
+  ENV_GATED,
+  ENV_GRANT,
+  ENV_LEDGER,
+  ENV_MAX_DEPTH,
+  ENV_PARENT_ID,
+  parseList,
+} from "../src/propagation.ts";
+import type { Capability } from "../src/resolve.ts";
+import { republishable } from "./approvals.ts";
+
+/**
+ * Run governed children in herdr panes instead of captured child processes (ADR-0016 point 6).
+ *
+ * Opt-in, and deliberately not auto-detected from `herdr` being on PATH: where a governed child executes
+ * is an operator decision, and a run that silently relocates because a binary appeared is exactly the kind
+ * of invisible change this package exists to prevent. Both executors enforce the identical grant — the
+ * plan is the same, only the place it runs differs.
+ */
+export const ENV_HERDR = "PI_GRANTS_HERDR";
+/** herdr workspace for spawned panes. Omitted lets herdr choose. */
+export const ENV_HERDR_WORKSPACE = "PI_GRANTS_HERDR_WORKSPACE";
+/** Keep each child's pane after it finishes, for inspection. Off by default: fan-out would flood it. */
+export const ENV_HERDR_KEEP_PANE = "PI_GRANTS_HERDR_KEEP_PANE";
+
+export interface GrantsSession {
+  /** False when `PI_GRANTS_GRANT` is unset: the session holds the wildcard and nothing is governed. */
+  readonly governed: boolean;
+  /** The upper bound handed down by the delegator, before this session's own tools are observed. */
+  readonly inherited: Capability[];
+  readonly depth: number;
+  readonly maxDepth: number;
+  /** Bound variables that could not be read as non-negative integers — spawning is disabled, loudly. */
+  readonly malformedBounds: string[];
+  readonly gated: Capability[];
+  readonly ledgerPath?: string;
+  readonly useHerdr: boolean;
+  /** This session's ledger identity; children descend from it (F8). */
+  readonly ownSpawnId: string;
+  /** Descendants this subtree may still create — the cardinality bound ADR-0008 never had. */
+  readonly fanoutBudget: number;
+  /** Whether `delegate` / `delegate_all` are registered at all (S-5). Decided on the INHERITED grant. */
+  readonly mayDelegate: boolean;
+  /** Path to this extension, so a child granted `tool:delegate` can delegate in turn. */
+  readonly extensionPath?: string;
+
+  /** Approval keys approved for this session. In memory only — this dies with the process. */
+  readonly sessionApprovals: Set<string>;
+  /**
+   * Approvals inherited from the delegator, already clamped to this session's grant upstream.
+   *
+   * Key → body digest (ADR-0022), where the digest is absent for `<delegate>` and for a pre-0.11 parent.
+   * Deliberately kept RAW here and verified at the point of use (`storedApprovals`), because verification
+   * needs `session.definitions`, which does not exist until `session_start` — and this object is built
+   * before any hook has run.
+   */
+  readonly inheritedApprovals: Map<string, string | undefined>;
+  /** ONE single-flight queue for the whole session — see `obtainApprovals` for why it lives here. */
+  readonly approvalGateFor: ReturnType<typeof createApprovalGateProvider>;
+
+  /** Set at `session_start`; `process.cwd()` until then. */
+  cwd: string;
+  /** This session's own grant. Starts as the inherited upper bound, tightened once tools are observed. */
+  ownGrant: Capability[];
+  observed: boolean;
+  observedTools: string[] | null;
+  /** ADR-0016: `SKILL.md` definitions, keyed by name. The format this package spawns from now. */
+  definitions: Map<string, SkillDefinition>;
+  catalog: Catalog;
+  /**
+   * The in-flight catalog build, so `delegate` can wait for it instead of racing it.
+   *
+   * G7 / A-R5. The refresh in `before_provider_request` was fire-and-forget, so a `delegate` call
+   * early in a session could read a catalog that was still empty and refuse a perfectly valid grant
+   * as an "unknown capability". It failed closed, which is why it was Important rather than Critical,
+   * but non-deterministically: the same delegation succeeded or failed on timing alone.
+   */
+  catalogReady: Promise<Catalog>;
+
+  /**
+   * The one place a delegation context is built — and therefore the one place each field is spelled.
+   *
+   * R-28 is why this is a builder rather than an object literal at each call site. On the path this
+   * replaced, three call sites passed `extensionTools` and the one that ENFORCED did not, so every
+   * ordinary narrow definition was refused with a reason that misstated the file, while `/grants`
+   * cheerfully reported the opposite. The defect was in an argument list, and nothing tested argument
+   * lists. A builder makes the omission unspellable instead of merely corrected.
+   *
+   * `/grants` uses it too, deliberately: the listing runs the REAL planner over the REAL context, so a
+   * diagnostic that disagrees with enforcement is not expressible.
+   */
+  delegationContext(approved?: InheritableApproval[]): Promise<DelegationContext>;
+
+  /**
+   * Publish what children inherit. Written once at session start, and republished whenever this
+   * session's own approvals change (see `obtainApprovals`) — never once per spawn. That distinction is
+   * what keeps this race-free: every value ever written here is a PARENT-level fact (this session's own
+   * grant, intersected with its own approvals), identical for every sibling no matter which spawn
+   * prompted the human. A value scoped to one specific child is never written to this global channel.
+   */
+  publishChildEnv(): void;
+}
+
+/**
+ * Parse the environment once and build the session every other module reads through.
+ *
+ * `extensionPath` is passed in rather than derived here: it must name the file **pi loads as the
+ * extension**, so a child granted `tool:delegate` can be started with `-e <that file>`. `grants.ts` is that
+ * file, and only `grants.ts` can say so about itself.
+ */
+export function createGrantsSession(extensionPath: string | undefined): GrantsSession {
+  // Governance is opt-in: with PI_GRANTS_GRANT unset the session holds the wildcard and nothing is
+  // blocked. This extension must never silently tighten a normal workflow.
+  const grantRaw = process.env[ENV_GRANT];
+  const governed = grantRaw !== undefined;
+  const inherited: Capability[] = governed ? parseList(grantRaw) : [WILDCARD];
+  // G7 / A-S4 + B-I4: strict, three-way parsing that fails CLOSED. A malformed bound used to yield
+  // `NaN`, and every comparison against `NaN` is false, so depth limiting switched itself off.
+  const bounds = depthConfig(process.env[ENV_DEPTH], process.env[ENV_MAX_DEPTH]);
+  const { depth, maxDepth } = bounds;
+
+  const emptyCatalog = makeCatalog([]);
+
+  const session: GrantsSession = {
+    governed,
+    inherited,
+    depth,
+    maxDepth,
+    malformedBounds: bounds.malformed,
+    // ADR-0012: `bash` is gated by DEFAULT — but only in a governed session. An ungoverned one
+    // (no PI_GRANTS_GRANT) still blocks nothing, so "governance is opt-in" holds exactly where it always
+    // did. Inside a session the operator already chose to govern, handing a child `bash` hands it an
+    // ungoverned-descendant escape hatch, and doing that silently is what changes here.
+    // `PI_GRANTS_GATED=""` turns the default off; absent and empty are deliberately distinguishable.
+    gated: governed ? gatedFromEnv(process.env[ENV_GATED]) : parseList(process.env[ENV_GATED]),
+    ledgerPath: process.env[ENV_LEDGER],
+    useHerdr: process.env[ENV_HERDR] === "1",
+    // `ownSpawnId` comes from the parent (F8), so ids form one tree across process boundaries instead of
+    // every level restarting at `d0` and the ledger becoming unjoinable.
+    ownSpawnId: process.env[ENV_PARENT_ID]?.trim() || `d${depth}`,
+    // The cardinality bound ADR-0008 never had: it attenuates downward like depth, so a subtree can never
+    // create more descendants than its root was given — with no shared state, no lock and no counter file.
+    fanoutBudget: budgetFromEnv(process.env[ENV_FANOUT]),
+    /**
+     * Review finding S-5, fixed. The comment on the tools has always claimed conditional registration; the
+     * call was unconditional, `DELEGATE_CAPABILITY` was imported and never used, and "withhold it and the
+     * child is a leaf" was simply untrue on this path.
+     *
+     * Decided on the INHERITED grant rather than `ownGrant`, because registration happens at load time,
+     * before any tools are observed. An ungoverned session registers it as before.
+     */
+    mayDelegate: !governed || inherited.includes(DELEGATE_CAPABILITY) || inherited.includes(WILDCARD),
+    extensionPath,
+
+    sessionApprovals: new Set<string>(),
+    inheritedApprovals: parseInherited(process.env[ENV_APPROVED]),
+    approvalGateFor: createApprovalGateProvider(),
+
+    cwd: process.cwd(),
+    ownGrant: deriveOwnGrant(inherited, null),
+    observed: false,
+    observedTools: null,
+    definitions: new Map<string, SkillDefinition>(),
+    catalog: emptyCatalog,
+    catalogReady: Promise.resolve(emptyCatalog),
+
+    delegationContext: async (approved?: InheritableApproval[]) => ({
+      ownGrant: session.ownGrant,
+      depth: session.depth,
+      maxDepth: session.maxDepth,
+      gated: session.gated,
+      ledgerPath: session.ledgerPath,
+      extensionPath: session.extensionPath,
+      catalog: await session.catalogReady,
+      // R-32: where each granted skill lives, so `planSpawn` can pass `--skill` for those and only those.
+      // Derived from the catalog's own `source`, so it cannot drift from what was discovered.
+      skillPaths: skillPathsFromCatalog(await session.catalogReady),
+      // ADR-0016: operator-authored SKILL.md definitions, so `delegate({agent})` can name one.
+      definitions: session.definitions,
+      // The herdr executor drives the child after starting it, so its plan must NOT carry `--print`.
+      // Threaded through the plan rather than patched afterwards: the argv is what the ledger records, and
+      // an executor quietly rewriting it would make the record describe a spawn that did not happen.
+      interactive: session.useHerdr,
+      ...(approved ? { approved } : {}),
+    }),
+
+    publishChildEnv: () => {
+      const env = childEnv({
+        ownGrant: session.ownGrant,
+        depth: session.depth,
+        maxDepth: session.maxDepth,
+        gated: session.gated,
+        ledgerPath: session.ledgerPath,
+        approved: republishable(session),
+        // G7 / B-I8: an ungoverned session publishes nothing, so "governance is opt-in" holds for
+        // descendants too. Previously it exported its own observed tool surface as their grant.
+        governed: session.governed,
+      });
+      for (const [key, value] of Object.entries(env)) process.env[key] = value;
+    },
+  };
+
+  return session;
+}

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "pi-daddy",
+  "version": "0.13.0",
+  "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
+  "keywords": [
+    "pi-package",
+    "subagents",
+    "capabilities",
+    "least-privilege",
+    "governance",
+    "audit"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mojomanyana/pi-daddy.git",
+    "directory": "packages/pi-daddy"
+  },
+  "homepage": "https://github.com/mojomanyana/pi-daddy#readme",
+  "bugs": {
+    "url": "https://github.com/mojomanyana/pi-daddy/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./resolve": {
+      "types": "./dist/resolve.d.ts",
+      "default": "./dist/resolve.js"
+    },
+    "./ledger": {
+      "types": "./dist/ledger.d.ts",
+      "default": "./dist/ledger.js"
+    },
+    "./spawn": {
+      "types": "./dist/spawn.d.ts",
+      "default": "./dist/spawn.js"
+    },
+    "./delegate": {
+      "types": "./dist/delegate.d.ts",
+      "default": "./dist/delegate.js"
+    },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "default": "./dist/catalog.js"
+    },
+    "./propagation": {
+      "types": "./dist/propagation.d.ts",
+      "default": "./dist/propagation.js"
+    },
+    "./definitions": {
+      "types": "./dist/definitions.d.ts",
+      "default": "./dist/definitions.js"
+    },
+    "./fanout": {
+      "types": "./dist/fanout.d.ts",
+      "default": "./dist/fanout.js"
+    },
+    "./pi-tools": {
+      "types": "./dist/pi-tools.d.ts",
+      "default": "./dist/pi-tools.js"
+    },
+    "./run-herdr": {
+      "types": "./dist/run-herdr.d.ts",
+      "default": "./dist/run-herdr.js"
+    },
+    "./run-child": {
+      "types": "./dist/run-child.d.ts",
+      "default": "./dist/run-child.js"
+    },
+    "./approval": {
+      "types": "./dist/approval.d.ts",
+      "default": "./dist/approval.js"
+    },
+    "./approval-store": {
+      "types": "./dist/approval-store.d.ts",
+      "default": "./dist/approval-store.js"
+    },
+    "./approval-prompt": {
+      "types": "./dist/approval-prompt.d.ts",
+      "default": "./dist/approval-prompt.js"
+    }
+  },
+  "files": [
+    "dist",
+    "extensions",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "test": "node --test test/*.test.ts",
+    "test:integration": "node --test test-integration/*.it.ts",
+    "prepack": "npm run build",
+    "test:smoke": "node scripts/smoke-installed.mjs"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "pi": {
+    "extensions": [
+      "./extensions/grants.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.83.0",
+    "typebox": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.83.0",
+    "@types/node": "^22.0.0",
+    "typebox": ">=1.0.0",
+    "typescript": "^5.7.0"
+  }
+}