pi-daddy 0.28.0 → 0.32.1

package/src/kernel/delegate-types.ts

@@ -0,0 +1,162 @@
+/**
+ * The shapes `planDelegation` consumes and produces. Split out of `./delegate.ts` only to stay under the
+ * 400-line module ceiling this project enforces mechanically; `./delegate.ts` re-exports all three, so
+ * "the delegate module" remains one import for every caller.
+ */
+import type { Capability, ResolveResult } from "./resolve.ts";
+import type { DefinitionDigest, SkillDefinition } from "./definitions.ts";
+import type { InheritableApproval } from "./approval.ts";
+import type { Catalog } from "./catalog.ts";
+import type { ApprovalBinding, CorrelationMetadata } from "./correlation.ts";
+import type { StructuredRefusal } from "./refusals.ts";
+
+/** The two ways a child can be started. Defined here, below the executors, so the ledger and the planner can name it without importing an executor (ADR-0076 layering). */
+export const EXECUTOR_KINDS = ["process", "herdr"] as const;
+export type ExecutorKind = (typeof EXECUTOR_KINDS)[number];
+
+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;
+  /** Optional external join metadata. It never participates in capability authority. */
+  correlation?: CorrelationMetadata;
+  /**
+   * Trusted binding scope, supplied by the caller that actually resolved and leased the
+   * workspace. Deliberately separate from `correlation`, whose values are a model-supplied
+   * claim: reading the workspace id out of correlation let a bound approval be spent outside
+   * the workspace it named (R-110).
+   */
+  boundWorkspaceId?: string;
+  boundContextId?: 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;
+  /** No-tool activity observer injected only for governed leaf children. */
+  observerExtensionPath?: string;
+  /**
+   * Extra per-child environment supplied by the composition layer (today: the activity timeline's local
+   * observation identity). Evaluated once the child's execution id is known. The kernel refuses any key in
+   * the `PI_DADDY_` namespace, so nothing supplied here can widen a grant, a depth or an approval
+   * (ADR-0076: the kernel imports no product; products contribute through this hook).
+   */
+  childEnv?: (child: { childExecutionId?: string }) => Readonly<Record<string, 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;
+  /** Explicit host-owned pi persistence target; never model-facing and never enabled by archive observation. */
+  sessionFile?: string;
+  /**
+   * Total descendants this session may still create (`src/kernel/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 logical siblings (F8). */
+  childSpawnId?: string;
+  /** Unique identity assigned to THIS execution occurrence; never derive joins from childSpawnId. */
+  childExecutionId?: string;
+}
+
+export interface Delegation {
+  ok: boolean;
+  reason?: string;
+  /** Stable machine-readable refusal accompanying the unchanged human diagnostic. */
+  refusal?: StructuredRefusal;
+  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's readable logical position, if the caller assigned one (F8). */
+  childId?: string;
+  /** Unique identity for this occurrence, if the caller assigned one. */
+  executionId?: 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;
+  /** Trusted SHA-256 of the exact model-authored task. The task text itself is never stored. */
+  taskDigest: string;
+  /** Non-authoritative external join metadata, snapshotted at planning time. */
+  correlation?: CorrelationMetadata;
+  /** Exact approval scope, present when correlation/workspace context requested task-bound approval. */
+  approvalBinding?: ApprovalBinding;
+}
+
+/**
+ * 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).
+ */

package/src/kernel/delegate.ts

@@ -0,0 +1,375 @@
+/**
+ * Governed delegation planning. Owning the spawn makes the grant an argument; each child receives its own
+ * environment, and `tool:delegate` determines whether it is a delegator or a leaf.
+ */
+
+import { planSpawn } from "./spawn.ts";
+import { ceilingForDefinition, digestDefinition, type DefinitionDigest, type SkillDefinition } from "./definitions.ts";
+import { assertNarrowing, type Capability, type ResolveResult } from "./resolve.ts";
+import { checkRoutingAuthority, checkWorkspaceWildcardRequest } from "./routing-authority.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_EXECUTION_ID,
+  ENV_FANOUT,
+  ENV_GATED,
+  ENV_GRANT,
+  ENV_LEDGER,
+  ENV_MAX_DEPTH,
+  ENV_PARENT_ID,
+  inheritableGrant,
+} from "./propagation.ts";
+import { inheritApprovals, type InheritableApproval } from "./approval.ts";
+import { explainDoubledNamespace, suggestForUnknown, unknownCapabilities, type Catalog } from "./catalog.ts";
+import { GovernanceRefusal, refusal, type RefusalCode, type StructuredRefusal } from "./refusals.ts";
+import { digestTask, normaliseCorrelation, type ApprovalBinding, type CorrelationMetadata } from "./correlation.ts";
+import { resolveDelegationApproval } from "./delegation-approval.ts";
+import type { Delegation, DelegationContext, DelegationRequest } from "./delegate-types.ts";
+import { assertCapabilitiesArePropagatable } from "./capabilities.ts";
+export type { Delegation, DelegationContext, DelegationRequest } from "./delegate-types.ts";
+import { GOVERNANCE_ENV_KEYS } from "./env-names.ts";
+
+export function planDelegation(request: DelegationRequest, ctx: DelegationContext): Delegation {
+  const childDepth = ctx.depth + 1;
+  const denied = (plan: Delegation, code: RefusalCode): Delegation =>
+    plan.reason ? { ...plan, refusal: refusal(code, plan.reason) } : plan;
+  // 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.
+  // Bounded/whitelisted correlation is a REFUSAL, not an exception escaping the planner. It is reachable
+  // from a model-facing tool parameter on all three delegation tools, and throwing from here produced a
+  // governed refusal with no code and no ledger line at all — the ledger file was never even created
+  // (R-112). Caught here so it becomes an ordinary recorded decision.
+  let correlation: CorrelationMetadata | undefined;
+  let correlationRefused: StructuredRefusal | undefined;
+  try {
+    correlation = normaliseCorrelation(request.correlation);
+  } catch (error) {
+    correlationRefused =
+      error instanceof GovernanceRefusal
+        ? { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) }
+        : refusal("CORRELATION_INVALID", String(error instanceof Error ? error.message : error));
+  }
+  const taskDigest = digestTask(request.task ?? "");
+  const empty: Delegation = {
+    ok: false,
+    args: [],
+    env: {},
+    effective: [],
+    childDepth,
+    requested: [],
+    taskDigest,
+    ...(correlation ? { correlation } : {}),
+    result: { effective: [], denied: [], clipped: [], gatedBlocked: [], universal: [], subsumedBy: [] },
+  };
+
+  if (correlationRefused) {
+    return { ...empty, reason: correlationRefused.message, refusal: correlationRefused };
+  }
+  if (ctx.maxDepth <= 0) {
+    return denied({ ...empty, reason: "delegation is disabled (maxDepth 0)" }, "DEPTH_EXCEEDED");
+  }
+  if (childDepth > ctx.maxDepth) {
+    return denied({ ...empty, reason: `delegation depth limit reached (${ctx.maxDepth})` }, "DEPTH_EXCEEDED");
+  }
+  if (!request.task?.trim()) return denied({ ...empty, reason: "a delegation needs a task" }, "TASK_MISSING");
+
+  // ADR-0035's routing guards live in `routing-authority.ts` with their rationale; both are checked here,
+  // before anything is said about the target, because they are governance questions about the SESSION.
+  const routing = checkRoutingAuthority(request.boundWorkspaceId, ctx.ownGrant);
+  if (routing) {
+    return denied(
+      {
+        ...empty,
+        ...(routing.denied ? { requested: routing.denied, result: { ...empty.result, denied: routing.denied } } : {}),
+        reason: routing.reason,
+      },
+      routing.code,
+    );
+  }
+
+  // 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 denied(
+        {
+          ...empty,
+          reason:
+            `unknown agent "${request.agent}"` +
+            (known.length > 0 ? ` — known definitions: ${known.join(", ")}` : " — no definitions were found"),
+        },
+        "UNKNOWN_DEFINITION",
+      );
+    }
+
+    // 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 denied(
+        {
+          ...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.`),
+        },
+        "DEFINITION_NOT_AUTHORIZED",
+      );
+    }
+
+    // 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 denied(
+        {
+          ...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.`,
+        },
+        "UNDECLARED_TOOLS",
+      );
+    }
+    if (ceiling.patterns.length > 0) {
+      return denied(
+        {
+          ...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.`,
+        },
+        "CEILING_PATTERNS_UNRESOLVED",
+      );
+    }
+    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) {
+      // Name the likely intent where there is one. `ceilingForDefinition` refuses to TRANSLATE names
+      // (lowercasing and no more), so an author who wrote Claude Code's `Glob` gets `tool:glob` and a
+      // refusal — correct, and previously unhelpful, because pi's equivalent is `find` and no amount of
+      // staring at "not present in this session's catalog" says so. The hint changes nothing about the
+      // refusal; it just stops the author having to guess which of nine built-ins was meant.
+      // A doubled namespace is answered first and instead: it is not a guess about what the author meant
+      // but a statement of what the field did, and "did you mean tool:read?" beside `tool:tool:read` shows
+      // the author a correction without ever saying that `allowed-tools` supplies the `tool:` itself.
+      const hints = unknown
+        .map((c) => {
+          const doubled = explainDoubledNamespace(c);
+          if (doubled !== null) return doubled;
+          const s = suggestForUnknown(c, ctx.catalog!);
+          return s === null ? null : `${c} → did you mean ${s}?`;
+        })
+        .filter((h): h is string => h !== null);
+      return denied(
+        {
+          ...empty,
+          requested,
+          reason:
+            `unknown capabilit${unknown.length === 1 ? "y" : "ies"}: ${unknown.join(", ")} — not present in ` +
+            `this session's catalog (typo, or an uninstalled package?)` +
+            (hints.length > 0 ? ` — ${hints.join("; ")}` : ""),
+        },
+        "UNKNOWN_TOOL",
+      );
+    }
+  }
+
+  // See `checkWorkspaceWildcardRequest`: refused for a HOLDER (the ledger must not record authority the
+  // child will not receive), and left to `resolve()` for anyone else, so the probe lands in `denied`.
+  const wildcardRequest = checkWorkspaceWildcardRequest(requested, ctx.ownGrant);
+  if (wildcardRequest) {
+    return denied({ ...empty, requested, reason: wildcardRequest.reason }, wildcardRequest.code);
+  }
+
+  const { result, approvalBinding, bindingMismatch } = resolveDelegationApproval({
+    task: request.task,
+    agent: request.agent,
+    boundWorkspaceId: request.boundWorkspaceId,
+    boundContextId: request.boundContextId,
+    requested,
+    parentGrant: ctx.ownGrant,
+    gated: ctx.gated,
+    approved: ctx.approved,
+    spawned,
+    definitionDigest,
+    correlation,
+    parentId: ctx.spawnId ?? `d${ctx.depth}`,
+  });
+  if (approvalBinding) Object.assign(empty, { approvalBinding });
+
+  if (result.denied.length > 0) {
+    return denied(
+      {
+        ...empty,
+        requested,
+        result,
+        reason: `cannot grant ${result.denied.join(", ")} — this session does not hold it (capability escalation blocked)`,
+      },
+      "CAPABILITY_ESCALATION",
+    );
+  }
+  // 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) {
+    // ADR-0011's narrowing invariant is the hardest rule this package enforces, and it was the one
+    // refusal an external controller could not identify by code (R-109).
+    return denied(
+      { ...empty, requested, result, reason: String(error instanceof Error ? error.message : error) },
+      "NARROWING_VIOLATED",
+    );
+  }
+  if (result.gatedBlocked.length > 0) {
+    const code = bindingMismatch ? "APPROVAL_SCOPE_MISMATCH" : "GATED_UNAPPROVED";
+    const suffix = bindingMismatch ? " (an approval exists, but its task/workspace/context scope does not match)" : "";
+    return denied(
+      { ...empty, requested, result, reason: `${result.gatedBlocked.join(", ")} requires explicit approval${suffix}` },
+      code,
+    );
+  }
+
+  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,
+    sessionFile: ctx.sessionFile,
+    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 denied(
+      {
+        ...empty,
+        requested,
+        result,
+        reason:
+          `cannot locate ${plan.unresolvedSkills.join(", ")} on disk — granted but unresolvable, so the ` +
+          `child would silently lack it`,
+      },
+      "DEFINITION_UNREADABLE",
+    );
+  }
+
+  // `-e` loads even under `--no-extensions`. A delegate-capable child loads the governance extension;
+  // a leaf gets only the no-tool observer. Neither path alters --tools or the computed grant.
+  const args = [...plan.args];
+  const observer = canSubDelegate ? ctx.extensionPath : ctx.observerExtensionPath;
+  if (observer) args.splice(args.length - 1, 0, "-e", observer);
+
+  // `inheritableGrant`, not `result.effective` directly: this is the path a DELEGATED child's grant
+  // actually travels, and the "held but never inherited" rule for `tool:*` and `workspace:*` was enforced
+  // only in `childEnv`. A parent holding `workspace:*` could request it for its child and this line handed
+  // it over, so the rule ADR-0035 advertises held by accident — masked downstream rather than enforced
+  // here. One spelling of the rule, called from both paths.
+  const inheritable = inheritableGrant(result.effective);
+  const env: Record<string, string> = {
+    [ENV_GRANT]: (assertCapabilitiesArePropagatable(inheritable), inheritable.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.childExecutionId) env[ENV_EXECUTION_ID] = ctx.childExecutionId;
+  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.
+  // Clamped to what the child actually INHERITS, not to what it was granted. The two differ only for a
+  // non-inheritable wildcard, and passing down an approval for a capability the child does not hold would
+  // leave banked authority with nothing to spend it on — `childEnv` clamps to `inheritable` for the same
+  // reason on the other path.
+  env[ENV_APPROVED] = inheritApprovals(ctx.approved ?? [], inheritable).join(",");
+  if (ctx.ledgerPath) env[ENV_LEDGER] = ctx.ledgerPath;
+  // Composition-supplied per-child environment (the activity timeline's observation identity today).
+  // Never process-global grant state: a key in the governance namespace is a programming error in the
+  // caller, refused loudly rather than letting a product widen what the child inherits.
+  for (const [key, value] of Object.entries(ctx.childEnv?.({ childExecutionId: ctx.childExecutionId }) ?? {})) {
+    if (GOVERNANCE_ENV_KEYS.includes(key) || key in env) throw new Error(`childEnv may not set governance key ${key}`);
+    env[key] = value;
+  }
+
+  return {
+    ok: true,
+    args,
+    env,
+    effective: result.effective,
+    result,
+    childDepth,
+    requested,
+    childId: ctx.childSpawnId,
+    executionId: ctx.childExecutionId,
+    taskDigest,
+    ...(correlation ? { correlation } : {}),
+    ...(approvalBinding ? { approvalBinding } : {}),
+    ...(definitionDigest ? { definitionDigest } : {}),
+  };
+}

package/src/kernel/delegation-approval.ts

@@ -0,0 +1,126 @@
+import { DELEGATE_SUBJECT, type InheritableApproval } from "./approval.ts";
+import { agentCapability, workspaceCapability } from "./capabilities.ts";
+import {
+  approvalBindingsEqual,
+  buildApprovalBinding,
+  type ApprovalBinding,
+  type CorrelationMetadata,
+} from "./correlation.ts";
+import type { DefinitionDigest, SkillDefinition } from "./definitions.ts";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, resolve, type Capability, type ResolveResult } from "./resolve.ts";
+
+/**
+ * Resolve the approval half of one delegation after its requested capability set is known.
+ *
+ * Kept as one function because the ordering is security-relevant: compute the unapproved and potential
+ * effective sets first, derive the exact binding from those trusted values, then decide which approvals
+ * match. An approval must never define the scope against which it is checked.
+ */
+export function resolveDelegationApproval(input: {
+  task: string;
+  agent?: string;
+  requested: Capability[];
+  parentGrant: Capability[];
+  gated: Capability[];
+  approved?: InheritableApproval[];
+  spawned?: SkillDefinition;
+  definitionDigest?: DefinitionDigest;
+  /**
+   * Present iff this call is task-bound. Most values remain labels; optional tree_sha/last_change_seq enter
+   * the binding only to narrow a supplied approval to the upstream tree state that was reviewed.
+   */
+  correlation?: CorrelationMetadata;
+  /** Trusted: an id that was resolved against the operator registry and leased. Never a caller claim. */
+  boundWorkspaceId?: string;
+  /** Caller-declared label. Narrows the binding only; asserts nothing about enforcement. */
+  boundContextId?: string;
+  parentId: string;
+}): { result: ResolveResult; approvalBinding?: ApprovalBinding; bindingMismatch: boolean } {
+  const subject = input.agent ?? DELEGATE_SUBJECT;
+  const unapproved = resolve({
+    requested: input.requested,
+    parentGrant: input.parentGrant,
+    gated: input.gated,
+    approved: [],
+  });
+
+  /**
+   * Authorities the PARENT is spending on this one delegation, gated as such.
+   *
+   * ADR-0024 established the shape for `agent:<name>`: the id is gated as the parent's authority to run
+   * that definition *now*, and never joins requested/effective, because that would hand the child authority
+   * to recursively spawn itself. ADR-0035 added a second member of the category — `workspace:<id>`, the
+   * authority to route this child somewhere — and shipped without it, so `PI_DADDY_GATED=workspace:prod`
+   * was accepted, recorded, and silently inert: no human was ever asked. The ADR claimed the opposite in
+   * three places.
+   *
+   * A LIST rather than two variables on purpose. This is the third namespace whose authorising id is gated
+   * per-delegation rather than granted downward, and the first two were written as one special case each;
+   * a fourth should extend an array, not add a third `if` and a third field to thread through.
+   */
+  const authorisingCapabilities: Capability[] = [];
+  const gateAuthority = (authorising: Capability, wildcard: Capability) => {
+    if (input.gated.includes(authorising) || input.gated.includes(wildcard)) {
+      authorisingCapabilities.push(authorising);
+      unapproved.gatedBlocked = [...unapproved.gatedBlocked, authorising];
+    }
+  };
+  if (input.spawned) gateAuthority(agentCapability(input.spawned.name), AGENT_WILDCARD);
+  // Trusted: `boundWorkspaceId` is set only from a routing spec resolved against the operator registry,
+  // never from a model-supplied `correlation` claim (R-110).
+  if (input.boundWorkspaceId) {
+    gateAuthority(workspaceCapability(input.boundWorkspaceId), WORKSPACE_WILDCARD);
+  }
+
+  const potential = resolve({
+    requested: input.requested,
+    parentGrant: input.parentGrant,
+    gated: input.gated,
+    // If the definition also declares its own authorising `agent:<name>`, the same approval unblocks
+    // that requested child capability too; excluding it here would bind a smaller set than we provision.
+    approved: unapproved.gatedBlocked,
+  });
+  const approvalBinding = input.correlation
+    ? buildApprovalBinding({
+        task: input.task,
+        requested: input.requested,
+        effective: potential.effective,
+        definitionSha256: input.definitionDigest?.sha256,
+        parentId: input.parentId,
+        workspaceId: input.boundWorkspaceId,
+        contextId: input.boundContextId,
+        treeSha: input.correlation?.tree_sha,
+        lastChangeSeq: input.correlation?.last_change_seq,
+      })
+    : undefined;
+
+  const forSubject = (input.approved ?? []).filter((approval) => approval.subject === subject);
+  const approvedCapabilities = forSubject
+    .filter((approval) =>
+      approvalBinding ? approvalBindingsEqual(approval.binding, approvalBinding) : approval.binding === undefined,
+    )
+    .map((approval) => approval.capability);
+  const bindingMismatch =
+    approvalBinding !== undefined &&
+    forSubject.some(
+      (approval) => approval.binding !== undefined && !approvalBindingsEqual(approval.binding, approvalBinding),
+    );
+  const result = resolve({
+    requested: input.requested,
+    parentGrant: input.parentGrant,
+    gated: input.gated,
+    approved: approvedCapabilities,
+  });
+  // Filtered against what `resolve()` already listed, not just against approvals. In the ORDINARY chained
+  // configuration — route the child to `prod` AND grant it `workspace:prod` so it can route onward — the
+  // authorising id and the requested id are spelled identically, so appending unconditionally produced
+  // `gatedBlocked: ["workspace:prod","workspace:prod"]`, which reached the refusal text a model reads
+  // (*"workspace:prod, workspace:prod requires explicit approval"*) and the append-only ledger, whose schema
+  // has no `uniqueItems`. The old `agent:`-only code had the same shape and never hit it, because a
+  // self-recursive `agent:X` ceiling is not a thing anybody writes.
+  const stillGated = authorisingCapabilities.filter(
+    (c) => !approvedCapabilities.includes(c) && !result.gatedBlocked.includes(c),
+  );
+  if (stillGated.length > 0) result.gatedBlocked = [...result.gatedBlocked, ...stillGated];
+  return { result, ...(approvalBinding ? { approvalBinding } : {}), bindingMismatch };
+}