pi-daddy 0.13.0

package/src/definitions.ts

@@ -0,0 +1,233 @@
+/**
+ * Agent Skills (`SKILL.md`) as this package's definition format — ADR-0016.
+ *
+ * A subagent is a skill you spawn: the `SKILL.md` body becomes the child's system prompt
+ * (`--append-system-prompt`) and `allowed-tools` becomes its capability ceiling, enforced through
+ * `--tools`. That collapses a duplication `principal-pi-skills` already strains against, where
+ * `plan`/`review`/`debug` exist twice — once as a skill and once as a subagent prompt — and are
+ * generated from one contract precisely so the two cannot drift.
+ *
+ * **The spec's own words about `allowed-tools`:** *"a space-separated string of tools that are
+ * pre-approved to run"*, marked **experimental**. Pre-approved, not enforced — the field declares intent
+ * and blocks nothing, and implementations differ on whether they honour it at all. Turning that
+ * declaration into something structural is this package's entire value here.
+ *
+ * **One inversion is deliberate and load-bearing.** In pi-subagents' frontmatter an absent `tools:` key
+ * means *pi's full default toolset*, so an undeclared definition was the most powerful kind and any
+ * parse failure produced a wildcard — the direction that caused R-28 and review finding F18. Here an
+ * absent `allowed-tools` means **undeclared, therefore not spawnable**. A typo or an unreadable YAML
+ * form now costs a refusal instead of a grant.
+ */
+
+import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { skillDirs } from "./catalog.ts";
+import type { Capability } from "./resolve.ts";
+
+/**
+ * Identifies WHICH instructions a child was given, without reproducing them (ADR-0018).
+ *
+ * The ledger's standing rule is *capability ids, counts and identifiers only — never prompts, tool
+ * arguments or results*. A hash is an identifier: it names a version of an operator-authored file. The
+ * **task** is model-assembled from the parent's context and is never recorded anywhere, by decision.
+ */
+export interface DefinitionDigest {
+  name: string;
+  /** Where the definition was read from, so a reader can go and rehash it. */
+  source: string;
+  /** SHA-256 of the body — the exact text passed as `--append-system-prompt`. */
+  sha256: string;
+}
+
+/**
+ * Digest a definition's body.
+ *
+ * Over the **body alone**, deliberately: that is precisely the text the child receives, so a digest that
+ * also covered the frontmatter would change when `description` was reworded and report an instruction
+ * change that never happened. `allowed-tools` is already recorded in full on every record.
+ */
+export function digestDefinition(definition: SkillDefinition): DefinitionDigest {
+  return {
+    name: definition.name,
+    source: definition.source,
+    sha256: createHash("sha256").update(definition.body, "utf8").digest("hex"),
+  };
+}
+
+export interface SkillDefinition {
+  /** From the path, never the frontmatter — see `parseSkillDefinition`. */
+  name: string;
+  description: string;
+  /** Raw `allowed-tools` value. `undefined` means the key was absent; `""` means it declared none. */
+  allowedTools?: string;
+  /** The spec's sanctioned extension point: a map of string keys to string values. */
+  metadata?: Record<string, string>;
+  /** Everything after the frontmatter — the child's system prompt. */
+  body: string;
+  source: string;
+}
+
+export interface DefinitionCeiling {
+  /** The declared capabilities, as this package's ids. */
+  capabilities: Capability[];
+  /**
+   * Entries carrying a sub-tool pattern, e.g. `Bash(git:*)`.
+   *
+   * ADR-0016 refuses these rather than reinterpreting them, because every reinterpretation is wrong:
+   * granting bare `bash` **widens** a deliberately narrow declaration, dropping the tool silently
+   * **narrows** and yields a child that mysteriously cannot work, and matching patterns inside a wrapper
+   * would be a security control implemented by string-matching a shell command. Non-empty means the
+   * caller must refuse and say so.
+   */
+  patterns: string[];
+  /** The `allowed-tools` key was absent entirely: the definition is not spawnable. */
+  undeclared: boolean;
+}
+
+/**
+ * Read a `SKILL.md`.
+ *
+ * The frontmatter reader handles the subset these files use — `key: value`, block scalars (`>` / `|`),
+ * and a one-level `metadata:` map. Anything it cannot read leaves the key **absent**, which for
+ * `allowed-tools` means *undeclared* and therefore refused. That is the whole reason this parser can be
+ * hand-rolled without the hazard its sibling in `agent-types.ts` carries.
+ */
+export function parseSkillDefinition(source: string, text: string): SkillDefinition | null {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  if (!match) return null;
+
+  const fields = new Map<string, string>();
+  const metadata: Record<string, string> = {};
+  const lines = match[1].split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[i]);
+    if (!kv) continue;
+    const [, key, rawValue] = kv;
+    const value = rawValue.trim();
+
+    // A folded/literal scalar: fold the indented continuation into one line. `principal-pi-skills`
+    // writes every description this way, and the sibling parser SKIPS these — which is safe there only
+    // because it never needs the value. Here a skipped `description` would be a missing required field.
+    if (value === ">" || value === "|") {
+      const parts: string[] = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (!/^\s+\S/.test(lines[j])) break;
+        parts.push(lines[j].trim());
+        i = j;
+      }
+      fields.set(key, parts.join(" "));
+      continue;
+    }
+
+    // `metadata:` introduces a one-level map of string keys to string values (the spec's shape).
+    if (key === "metadata" && value === "") {
+      for (let j = i + 1; j < lines.length; j++) {
+        const item = /^\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[j]);
+        if (!item) break;
+        metadata[item[1]] = item[2].trim().replace(/^["']|["']$/g, "");
+        i = j;
+      }
+      continue;
+    }
+
+    fields.set(key, value);
+  }
+
+  const description = fields.get("description");
+  if (description === undefined) return null;
+
+  return {
+    // Identity comes from the PATH. ADR-0013 learned this the hard way on the other format: pi keys
+    // skills by their directory, so trusting a frontmatter `name` lets our view and the loader's
+    // disagree about which file a name refers to. The spec requires `name` to match the parent
+    // directory anyway, so a mismatch is the file's defect and not something to honour.
+    name: nameFromPath(source),
+    description,
+    allowedTools: fields.get("allowed-tools"),
+    metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    body: text.slice(match[0].length).trim(),
+    source,
+  };
+}
+
+/** `/skills/review/SKILL.md` -> `review`; `/skills/triage.md` -> `triage`. */
+function nameFromPath(source: string): string {
+  const parts = source.split("/").filter((p) => p.length > 0);
+  const last = parts.at(-1) ?? "";
+  if (last.toLowerCase() === "skill.md") return parts.at(-2) ?? "";
+  return last.replace(/\.md$/i, "");
+}
+
+/**
+ * Turn a definition's `allowed-tools` into a capability ceiling.
+ *
+ * Name mapping is **lowercasing and nothing else**, deliberately. A translation table from Claude
+ * Code's names to pi's would have to decide what `Glob` means, and pi has no glob tool — so the table
+ * would either invent a grant or quietly drop one. Lowercasing leaves `Glob` as `tool:glob`, which the
+ * catalog then refuses as unknown, naming the actual problem to whoever wrote the file.
+ */
+export function ceilingForDefinition(definition: SkillDefinition): DefinitionCeiling {
+  const raw = definition.allowedTools;
+  if (raw === undefined) return { capabilities: [], patterns: [], undeclared: true };
+
+  const capabilities = new Set<Capability>();
+  const patterns: string[] = [];
+
+  // The spec says space-separated. Commas are tolerated because `Read, Grep` is what people type, and
+  // accepting them grants nothing extra — it only avoids a comma becoming part of a capability name.
+  for (const entry of raw.split(/[\s,]+/).filter((e) => e.length > 0)) {
+    if (entry.includes("(")) {
+      patterns.push(entry);
+      continue;
+    }
+    if (entry.startsWith("ext:") || entry.startsWith("skill:") || entry.startsWith("agent:")) {
+      capabilities.add(entry);
+      continue;
+    }
+    capabilities.add(`tool:${entry.toLowerCase()}`);
+  }
+
+  return { capabilities: [...capabilities].sort(), patterns, undeclared: false };
+}
+
+/**
+ * Discover `SKILL.md` definitions under pi's skill roots.
+ *
+ * Deliberately the SAME roots and the same convention the catalog uses (`skillDirs`): a directory
+ * containing `SKILL.md` is one definition named after the directory, and a top-level `.md` is one named
+ * after the file. If discovery and the catalog disagreed, a definition could be spawnable but not
+ * grantable, or listed but unspawnable.
+ *
+ * Earlier directories win on a name collision, matching pi's own precedence — project before global.
+ */
+export async function loadDefinitions(cwd: string): Promise<Map<string, SkillDefinition>> {
+  const definitions = new Map<string, SkillDefinition>();
+  for (const dir of skillDirs(cwd)) {
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch {
+      continue; // an absent skill root is normal
+    }
+    for (const name of [...names].sort()) {
+      // A directory holding SKILL.md, or a top-level .md — try the former first, exactly as the
+      // catalog does, so the two cannot disagree about what exists.
+      const candidates = [join(dir, name, "SKILL.md"), ...(name.endsWith(".md") ? [join(dir, name)] : [])];
+      for (const path of candidates) {
+        let text: string;
+        try {
+          text = await readFile(path, "utf8");
+        } catch {
+          continue; // not this shape; try the next candidate
+        }
+        const parsed = parseSkillDefinition(path, text);
+        // First writer wins, so project definitions shadow global ones rather than the reverse.
+        if (parsed && !definitions.has(parsed.name)) definitions.set(parsed.name, parsed);
+        break;
+      }
+    }
+  }
+  return definitions;
+}

package/src/delegate.ts

@@ -0,0 +1,383 @@
+/**
+ * Governed delegation — provisioning, not merely enforcement.
+ *
+ * The `tool_call` interceptor can only *permit or refuse* a `pi-subagents` spawn, because that package's
+ * `Agent` tool has no `tools` parameter. When we do the spawning ourselves the grant becomes an argument,
+ * which is what "give them some tools but not others" actually requires.
+ *
+ * Two properties fall out of owning the spawn:
+ *
+ *  1. **No propagation race at all.** Each child receives its own explicit `env` object, so nothing is
+ *     written to the shared `process.env`. The interceptor's constraint (only parent-level facts may be
+ *     pushed, because the channel is global) does not apply here.
+ *  2. **Depth control by capability.** `tool:delegate` is itself a capability. Grant it and the child can
+ *     sub-delegate; withhold it and the child is a leaf. No separate depth mechanism is required, though
+ *     `maxDepth` remains as a cheap backstop.
+ */
+
+import { planSpawn } from "./spawn.ts";
+import { ceilingForDefinition, digestDefinition, type DefinitionDigest, type SkillDefinition } from "./definitions.ts";
+import { resolve, assertNarrowing, type Capability, type ResolveResult } from "./resolve.ts";
+import { AGENT_WILDCARD } from "./resolve.ts";
+import { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
+
+// Re-exported so the split stays internal: `delegate.ts` has been the import site for these since 0.6.0 and
+// four modules plus the test suite name it. Moving the definitions without moving the door would be churn
+// charged to every caller for a line count they did not cause.
+export { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
+import { ENV_APPROVED, ENV_DEPTH, ENV_FANOUT, ENV_GATED, ENV_GRANT, ENV_LEDGER, ENV_MAX_DEPTH, ENV_PARENT_ID } from "./propagation.ts";
+import { inheritApprovals, type InheritableApproval } from "./approval.ts";
+import { unknownCapabilities, type Catalog } from "./catalog.ts";
+
+export interface DelegationRequest {
+  task: string;
+  /**
+   * Capabilities the delegator wants the child to hold.
+   *
+   * Optional since ADR-0016: prefer `agent`, which names an operator-authored definition. This form
+   * lets the MODEL choose the capability set, which is the weaker arrangement — it is still bounded by
+   * the session grant (ADR-0008), so it cannot escalate, but nothing about it was reviewed by a human.
+   */
+  tools?: string[];
+  /**
+   * Name of a `SKILL.md` definition to spawn (ADR-0016).
+   *
+   * When given, the definition's `allowed-tools` is the ceiling and its body is the child's system
+   * prompt. The model chooses only *which* definition and *what* task; the capability set is the
+   * operator's, written down in a file.
+   */
+  agent?: string;
+  model?: string;
+  provider?: string;
+  thinking?: string;
+}
+
+export interface DelegationContext {
+  ownGrant: Capability[];
+  depth: number;
+  maxDepth: number;
+  gated: Capability[];
+  /**
+   * Approvals in force for this delegation, with subject and scope (ADR-0014).
+   *
+   * One source of truth for two different questions. The **gate check here** honours every entry,
+   * including `once` — that approval applies to *this* spawn, which is exactly what the human said yes
+   * to. What crosses to the CHILD is `inheritApprovals`, which drops `once` and keeps the subject, so
+   * the same list cannot silently authorise a subtree.
+   */
+  approved?: InheritableApproval[];
+  ledgerPath?: string;
+  /** Path to this extension, so a child granted `tool:delegate` can delegate in turn. */
+  extensionPath?: string;
+  /** Live capability catalog. When supplied, capabilities absent from it are refused as unknown. */
+  catalog?: Catalog;
+  /**
+   * Absolute path per skill NAME, from the catalog's `source` field (R-32).
+   *
+   * Without it every granted `skill:` capability is unresolvable and the delegation is refused, which
+   * is the correct direction: a caller that cannot say where a skill lives cannot honestly grant it.
+   */
+  skillPaths?: Record<string, string>;
+  /** Let the child load `AGENTS.md` / `CLAUDE.md`. Default false — see `planSpawn`. */
+  contextFiles?: boolean;
+  /** Known `SKILL.md` definitions by name, for `DelegationRequest.agent` (ADR-0016). */
+  definitions?: Map<string, SkillDefinition>;
+  /**
+   * Build an INTERACTIVE plan — no `--print` — for an executor that drives the child after starting it.
+   *
+   * `runHerdrPane` requires this: `--print` makes pi process the prompt and exit, so it never reaches the
+   * interactive readiness `herdr agent start` waits for and the agent is never detected. Default is the
+   * non-interactive plan, because a governed child should not sit waiting for a human by accident.
+   */
+  interactive?: boolean;
+  /**
+   * Total descendants this session may still create (`src/fanout.ts`). Split among children by the caller.
+   *
+   * Omitted means unbounded, which is the pre-fan-out behaviour and correct for a single blocking
+   * delegation — the accident that used to bound cardinality to one.
+   */
+  fanoutBudget?: number;
+  /** This session's ledger id, so a child's `parentId` names its real parent (F8). */
+  spawnId?: string;
+  /** Ledger id assigned to THIS child, distinguishing it from its siblings (F8). */
+  childSpawnId?: string;
+}
+
+export interface Delegation {
+  ok: boolean;
+  reason?: string;
+  args: string[];
+  /** Per-child environment — never merged into the parent's process.env. */
+  env: Record<string, string>;
+  effective: Capability[];
+  /**
+   * The result this plan was made from. **Required** (B-I3): while it was optional the extension
+   * guarded its ledger write with `if (ledgerPath && plan.result)`, silently dropping every refusal
+   * that returned before `resolve()` ran. The type is what keeps a new early exit auditable.
+   */
+  result: ResolveResult;
+  childDepth: number;
+  /**
+   * The capabilities this delegation asked for, whatever route named them.
+   *
+   * Carried on the plan rather than re-derived by the caller (the B-I3 lesson): with `agent`, the
+   * request names a DEFINITION and the capabilities come from its `allowed-tools`, so a ledger that
+   * read the tool parameters would record an empty request for every definition spawn.
+   */
+  requested: Capability[];
+  /** Ledger id for this child, if the caller assigned one (F8). */
+  childId?: string;
+  /**
+   * Which operator-authored instructions this spawn used (ADR-0018).
+   *
+   * Absent for a `tools:`-style delegation, which has no definition and therefore no instructions to
+   * identify — and absent on an ADR-0017 authorisation refusal, which is decided before the file is read.
+   */
+  definitionDigest?: DefinitionDigest;
+}
+
+/**
+ * Plan a governed delegation. Pure: returns argv and env, spawns nothing.
+ *
+ * Fails closed on depth, on any requested capability the delegator does not hold, on gated capabilities
+ * without approval, and on a grant that cannot narrow (a universal capability slipping through).
+ */
+export function planDelegation(request: DelegationRequest, ctx: DelegationContext): Delegation {
+  const childDepth = ctx.depth + 1;
+  // G6 / B-I3: every refusal carries a result, including the four below that return before `resolve()`
+  // is ever called. The extension guarded its ledger write with `if (ledgerPath && plan.result)`, so
+  // those four governance decisions — disabled, too deep, no task, unknown capability — were never
+  // audited at all. An empty result is the honest record: nothing was resolved, and that is the fact.
+  const empty: Delegation = {
+    ok: false,
+    args: [],
+    env: {},
+    effective: [],
+    childDepth,
+    requested: [],
+    result: { effective: [], denied: [], clipped: [], gatedBlocked: [], universal: [], subsumedBy: [] },
+  };
+
+  if (ctx.maxDepth <= 0) return { ...empty, reason: "delegation is disabled (maxDepth 0)" };
+  if (childDepth > ctx.maxDepth) {
+    return { ...empty, reason: `delegation depth limit reached (${ctx.maxDepth})` };
+  }
+  if (!request.task?.trim()) return { ...empty, reason: "a delegation needs a task" };
+
+  // ADR-0016. A named definition replaces the model's tool list with an operator-authored ceiling.
+  let requested: Capability[];
+  let systemPrompt: string | undefined;
+  let definitionDigest: DefinitionDigest | undefined;
+  /** The definition being spawned, hoisted so the gate below can name its authorising id (ADR-0024). */
+  let spawned: SkillDefinition | undefined;
+
+  if (request.agent) {
+    const definition = ctx.definitions?.get(request.agent);
+    spawned = definition;
+    // No fallback, deliberately. pi-subagents resolves an unknown type to `general-purpose`, whose
+    // omitted tool list means EVERY tool — so a typo there granted the full surface. An unknown name
+    // here is simply an error.
+    if (!definition) {
+      const known = [...(ctx.definitions?.keys() ?? [])].sort();
+      return {
+        ...empty,
+        reason:
+          `unknown agent "${request.agent}"` +
+          (known.length > 0 ? ` — known definitions: ${known.join(", ")}` : " — no definitions were found"),
+      };
+    }
+
+    // ADR-0017: authorisation comes BEFORE anything is said about the file. Which definitions this
+    // session may spawn is a governance question about the SESSION; whether the file declares its tools
+    // properly is a diagnostic about the DEFINITION, and answering the second one first would report a
+    // malformed-file error to a caller who was never allowed to spawn it either way.
+    //
+    // Recorded as a denial rather than a bare refusal, deliberately: `denied` is the escalation signal
+    // ADR-0008 designates, and asking to run a definition this session was not granted IS an attempt to
+    // exceed the grant. A refusal that left `denied` empty would keep it out of every audit query.
+    if (!maySpawnDefinition(ctx.ownGrant, definition.name)) {
+      const authorising = agentCapability(definition.name);
+      const held = ctx.ownGrant.filter((c) => c.startsWith("agent:")).sort();
+      return {
+        ...empty,
+        requested: [authorising],
+        result: { ...empty.result, denied: [authorising] },
+        reason:
+          `cannot spawn "${definition.name}" — this session does not hold ${authorising} ` +
+          `(the definition lives at ${definition.source}). ` +
+          (held.length > 0
+            ? `It may spawn: ${held.join(", ")}.`
+            : `It may spawn no definitions at all; add ${authorising} to its grant to allow this one.`),
+      };
+    }
+
+    // ADR-0018. Recorded from here on — after authorisation, because the digest is a fact about a file
+    // this caller was allowed to read, and before every remaining outcome, because a spawn refused for a
+    // malformed declaration is still a spawn of THIS version of the definition.
+    //
+    // Assigned into `empty`, which every subsequent refusal spreads. That is the R-28 discipline applied
+    // to a record field rather than an argument: instead of eight `definitionDigest` spellings that a
+    // ninth return could forget, there is one, and forgetting it is not expressible. The success return
+    // does not spread `empty`, so it names the field explicitly.
+    definitionDigest = digestDefinition(definition);
+    Object.assign(empty, { definitionDigest });
+
+    const ceiling = ceilingForDefinition(definition);
+    if (ceiling.undeclared) {
+      return {
+        ...empty,
+        reason:
+          `agent "${definition.name}" declares no \`allowed-tools\`, so it cannot be spawned — add one ` +
+          `to ${definition.source}. An undeclared capability set is treated as NONE, never as everything.`,
+      };
+    }
+    if (ceiling.patterns.length > 0) {
+      return {
+        ...empty,
+        reason:
+          `agent "${definition.name}" restricts a tool with a pattern (${ceiling.patterns.join(", ")}), ` +
+          `which pi's --tools cannot express — it matches whole tool names only. Granting the bare tool ` +
+          `would widen the declaration and dropping it would silently narrow, so neither is done.`,
+      };
+    }
+    requested = ceiling.capabilities;
+    systemPrompt = definition.body;
+  } else {
+    requested = (request.tools ?? []).map(normaliseCapability);
+  }
+
+  // Unknown is reported before denied, and separately: "does not exist here" and "you lack authority"
+  // have different causes and different fixes. Collapsing them hides typos and stale grants.
+  if (ctx.catalog) {
+    const unknown = unknownCapabilities(requested, ctx.catalog);
+    if (unknown.length > 0) {
+      return {
+        ...empty,
+        requested,
+        reason:
+          `unknown capabilit${unknown.length === 1 ? "y" : "ies"}: ${unknown.join(", ")} — not present in ` +
+          `this session's catalog (typo, or an uninstalled package?)`,
+      };
+    }
+  }
+
+  const approvedCapabilities = (ctx.approved ?? []).map((a) => a.capability);
+  const result = resolve({
+    requested,
+    parentGrant: ctx.ownGrant,
+    gated: ctx.gated,
+    approved: approvedCapabilities,
+  });
+
+  /**
+   * ADR-0024: gating `agent:<name>` asks a human before that definition runs.
+   *
+   * `gatedBlocked` is a filter over `requested`, and for a definition spawn `requested` is the definition's
+   * CEILING — so the id that authorises it was never a candidate, and `PI_GRANTS_GATED=agent:deploy` did
+   * nothing at all on the path an operator writing it means. It half-worked when some *other* definition
+   * passed the id down in its own `allowed-tools`, which is worse than not working (R-47, R-25's shape).
+   *
+   * Evaluated here rather than by adding the id to `requested`, and that is the load-bearing part: a
+   * capability in `requested` flows to `effective`, which becomes the CHILD's grant — so the child would
+   * hold `agent:deploy` and could spawn `deploy` itself without anyone being asked. This is the parent's
+   * authority to run the definition *now*, not something the child receives.
+   *
+   * `agent:*` in the gate covers every definition, so "ask me before any definition runs" is one variable.
+   */
+  if (spawned) {
+    const authorising = agentCapability(spawned.name);
+    const gatedHere = ctx.gated.includes(authorising) || ctx.gated.includes(AGENT_WILDCARD);
+    if (gatedHere && !approvedCapabilities.includes(authorising)) {
+      result.gatedBlocked = [...result.gatedBlocked, authorising];
+    }
+  }
+
+  if (result.denied.length > 0) {
+    return {
+      ...empty,
+      requested,
+      result,
+      reason: `cannot grant ${result.denied.join(", ")} — this session does not hold it (capability escalation blocked)`,
+    };
+  }
+  // ADR-0011: narrowing is checked BEFORE the gate, and the order is load-bearing rather than
+  // stylistic. `assertNarrowing` refuses regardless of approval, so with the old order this returned
+  // "requires explicit approval" for a delegation that could never be approved — telling the operator
+  // to go and find a human who cannot help. `shouldSeekApproval` now also refuses to prompt in this
+  // case; this reordering makes the reported *reason* agree with what actually blocks the spawn.
+  try {
+    assertNarrowing(result);
+  } catch (error) {
+    return { ...empty, requested, result, reason: String(error instanceof Error ? error.message : error) };
+  }
+  if (result.gatedBlocked.length > 0) {
+    return { ...empty, requested, result, reason: `${result.gatedBlocked.join(", ")} requires explicit approval` };
+  }
+
+  const canSubDelegate = result.effective.includes(DELEGATE_CAPABILITY);
+  const plan = planSpawn({
+    effective: result.effective,
+    prompt: request.task,
+    model: request.model,
+    provider: request.provider,
+    thinking: request.thinking,
+    skillPaths: ctx.skillPaths,
+    contextFiles: ctx.contextFiles,
+    systemPrompt,
+    print: ctx.interactive ? false : undefined,
+  });
+
+  // R-32. A `skill:` capability the catalog cannot place is refused rather than dropped. Dropping it
+  // would hand back a child whose grant claims a skill it does not have — the ledger would record a
+  // capability that never reached the process, which is precisely the kind of lie an audit trail must
+  // not contain. `unknownCapabilities` above catches names absent from the catalog entirely; this
+  // catches one that is known but whose path we could not resolve, which is a different fault.
+  if (plan.unresolvedSkills.length > 0) {
+    return {
+      ...empty,
+      requested,
+      result,
+      reason:
+        `cannot locate ${plan.unresolvedSkills.join(", ")} on disk — granted but unresolvable, so the ` +
+        `child would silently lack it`,
+    };
+  }
+
+  // A child may only delegate further if it was granted the capability AND has the extension to do it.
+  const args = [...plan.args];
+  if (canSubDelegate && ctx.extensionPath) {
+    // `-e` loads even under `--no-extensions`, which planSpawn sets — that is precisely why the
+    // extension is added explicitly here and nowhere else.
+    args.splice(args.length - 1, 0, "-e", ctx.extensionPath);
+  }
+
+  const env: Record<string, string> = {
+    [ENV_GRANT]: result.effective.join(","),
+    [ENV_DEPTH]: String(childDepth),
+    [ENV_MAX_DEPTH]: String(ctx.maxDepth),
+  };
+  // The child's own share of the subtree budget, and its identity. Both attenuate downward like depth: a
+  // child can never be handed more budget than its parent had left, so the total bound holds across
+  // process boundaries with no shared state.
+  if (ctx.fanoutBudget !== undefined) env[ENV_FANOUT] = String(ctx.fanoutBudget);
+  if (ctx.childSpawnId) env[ENV_PARENT_ID] = ctx.childSpawnId;
+  if (ctx.gated.length > 0) env[ENV_GATED] = ctx.gated.join(",");
+  // Approvals ride down with the grant, but only ever for what this child actually received — so
+  // `approved ⊆ grant` holds at every level (ADR-0010). Written even when empty, so this object states
+  // the child's approval set outright rather than leaving it to whatever the caller merges over; see
+  // `mergeChildEnv`, which is what actually stops the parent's value leaking through.
+  env[ENV_APPROVED] = inheritApprovals(ctx.approved ?? [], result.effective).join(",");
+  if (ctx.ledgerPath) env[ENV_LEDGER] = ctx.ledgerPath;
+
+  return {
+    ok: true,
+    args,
+    env,
+    effective: result.effective,
+    result,
+    childDepth,
+    requested,
+    childId: ctx.childSpawnId,
+    ...(definitionDigest ? { definitionDigest } : {}),
+  };
+}