pi-daddy 0.27.4 → 0.32.0

package/dist/kernel/correlation.js

@@ -0,0 +1,267 @@
+import { createHash } from "node:crypto";
+import { GovernanceRefusal, refusal } from "./refusals.js";
+import { isLedgerCorrelationIdentifier } from "./ledger-identifiers.js";
+const MAX_CORRELATION_BYTES = 32 * 1024;
+/**
+ * Per-field bound on the STRING fields — most are an id, a digest, a label or a timestamp. It does not
+ * apply to the three sequence numbers or to `assurance_scope`, which are checked separately; an earlier
+ * version of this comment claimed it covered every declared field.
+ */
+const MAX_CORRELATION_FIELD_CHARS = 512;
+/** `assurance_scope` is the one structured field, so it gets its own, larger bound. */
+const MAX_CORRELATION_SCOPE_BYTES = 4 * 1024;
+/**
+ * The exact field set of the pinned schema 1.0 contract. Anything else is refused by name.
+ *
+ * This is a whitelist rather than a size cap because `correlation` is a MODEL-FACING tool parameter that
+ * is copied verbatim onto every append-only ledger event. `src/governance/ledger.ts` states the invariant — capability
+ * ids, counts and identifiers only, never prompts, tool arguments or results — and ADR-0034 repeats that the
+ * ledger must never carry task text. A 32 KB "bounded JSON object" with no key whitelist and no per-field
+ * length bound satisfied neither: `assurance_scope` was declared `Type.Any()`, undeclared keys survived the
+ * round trip, and every string was unbounded, so a model could write 32 KB of arbitrary text into the
+ * ledger through it (R-111). Refusing an unknown key is also the loud option: if upstream adds a field, the
+ * refusal names it, which is an actionable break rather than a silent secrets sink.
+ */
+const CORRELATION_FIELDS = new Set([
+    "schema_version",
+    "run_id",
+    "task_id",
+    "workspace_id",
+    "context_id",
+    "phase",
+    "assurance",
+    "assurance_effective",
+    "policy_label",
+    "assurance_source",
+    "assurance_scope",
+    "activated_at",
+    "plan_digest",
+    "definition_digest",
+    "task_digest",
+    "base_sha",
+    "head_sha",
+    "tree_sha",
+    "event_seq",
+    "last_change_seq",
+    "last_authority_seq",
+    "check_receipt_id",
+]);
+const CORRELATION_NUMERIC = new Set(["event_seq", "last_change_seq", "last_authority_seq"]);
+// These fields are rendered as labels/identities. Treating arbitrary prose as an "id" let a model copy
+// task or output text into the ledger and dashboard through correlation while staying schema-valid.
+const CORRELATION_IDENTIFIERS = new Set([
+    "schema_version",
+    "run_id",
+    "task_id",
+    "workspace_id",
+    "context_id",
+    "phase",
+    "assurance",
+    "assurance_effective",
+    "policy_label",
+    "assurance_source",
+]);
+function correlationRefusal(message, details) {
+    return new GovernanceRefusal(refusal("CORRELATION_INVALID", `correlation metadata: ${message}`, details));
+}
+/**
+ * Size refusals get their own code, because they call for a different response: "you sent too much" is
+ * retryable by truncating, "you sent a field we do not recognise" is not. `CORRELATION_TOO_LARGE` was
+ * declared in the taxonomy and constructed nowhere, so the union advertised a distinction the code did not
+ * make — and the enumeration test kept the dead member green.
+ */
+function correlationTooLarge(message, details) {
+    return new GovernanceRefusal(refusal("CORRELATION_TOO_LARGE", `correlation metadata: ${message}`, details));
+}
+function normaliseAssuranceScope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw correlationRefusal("assurance_scope must be an object with type and selectors");
+    }
+    const scope = value;
+    const keys = Object.keys(scope).sort();
+    if (keys.length !== 2 || keys[0] !== "selectors" || keys[1] !== "type") {
+        throw correlationRefusal("assurance_scope must contain only type and selectors");
+    }
+    if (!Array.isArray(scope.selectors) ||
+        !scope.selectors.every((selector) => typeof selector === "string" && selector.length > 0)) {
+        throw correlationRefusal("assurance_scope selectors must be non-empty strings");
+    }
+    if (scope.type === "entire-run") {
+        if (scope.selectors.length !== 0)
+            throw correlationRefusal("entire-run assurance_scope requires empty selectors");
+        return { type: "entire-run", selectors: [] };
+    }
+    if (scope.type === "selectors") {
+        if (scope.selectors.length === 0)
+            throw correlationRefusal("selectors scope requires at least one selector");
+        return { type: "selectors", selectors: [...scope.selectors] };
+    }
+    throw correlationRefusal("assurance_scope type must be entire-run or selectors");
+}
+/**
+ * Snapshot bounded JSON metadata so a caller cannot mutate a record after planning, and so nothing
+ * unbounded or undeclared can reach the ledger through it.
+ *
+ * Refuses with a stable code rather than a bare `Error`: this is reachable from a model-facing tool
+ * parameter on all three delegation tools, and it used to throw outside every try, producing a governed
+ * refusal with no code and no ledger line at all (R-112).
+ */
+export function normaliseCorrelation(input) {
+    if (input === undefined)
+        return undefined;
+    let encoded;
+    try {
+        encoded = JSON.stringify(input);
+    }
+    catch (error) {
+        throw correlationRefusal(`must be JSON serializable (${String(error)})`);
+    }
+    if (encoded === undefined)
+        throw correlationRefusal("must be a JSON object");
+    if (Buffer.byteLength(encoded) > MAX_CORRELATION_BYTES) {
+        throw correlationTooLarge(`exceeds ${MAX_CORRELATION_BYTES} bytes`, { limit: MAX_CORRELATION_BYTES });
+    }
+    const parsed = JSON.parse(encoded);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw correlationRefusal("must be a JSON object");
+    }
+    const source = parsed;
+    const undeclared = Object.keys(source).filter((key) => !CORRELATION_FIELDS.has(key));
+    if (undeclared.length > 0) {
+        throw correlationRefusal(`carries fields outside the pinned schema 1.0 contract: ${undeclared.sort().join(", ")}`, {
+            undeclared: undeclared.sort().join(","),
+        });
+    }
+    const output = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined || value === null)
+            continue;
+        if (key === "assurance_scope") {
+            const size = Buffer.byteLength(JSON.stringify(value) ?? "");
+            if (size > MAX_CORRELATION_SCOPE_BYTES) {
+                throw correlationTooLarge(`assurance_scope exceeds ${MAX_CORRELATION_SCOPE_BYTES} bytes`, {
+                    limit: MAX_CORRELATION_SCOPE_BYTES,
+                    actual: size,
+                });
+            }
+            output[key] = normaliseAssuranceScope(value);
+            continue;
+        }
+        if (CORRELATION_NUMERIC.has(key)) {
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                throw correlationRefusal(`${key} must be a finite number`, { field: key });
+            }
+            output[key] = value;
+            continue;
+        }
+        if (typeof value !== "string")
+            throw correlationRefusal(`${key} must be a string`, { field: key });
+        if (key === "schema_version" && value !== "1.0") {
+            throw correlationRefusal(`unsupported schema_version ${value}; supported version is 1.0`, {
+                field: key,
+                supported: "1.0",
+            });
+        }
+        if (value.length > MAX_CORRELATION_FIELD_CHARS) {
+            throw correlationTooLarge(`${key} exceeds ${MAX_CORRELATION_FIELD_CHARS} characters`, {
+                field: key,
+                limit: MAX_CORRELATION_FIELD_CHARS,
+                actual: value.length,
+            });
+        }
+        if (CORRELATION_IDENTIFIERS.has(key) && !isLedgerCorrelationIdentifier(value)) {
+            throw correlationRefusal(`${key} must be an ASCII identifier, not free-form text`, { field: key });
+        }
+        output[key] = value;
+    }
+    return output;
+}
+export function digestTask(task) {
+    return createHash("sha256").update(task, "utf8").digest("hex");
+}
+export function digestCapabilities(capabilities) {
+    const canonical = [...new Set(capabilities)].sort();
+    return createHash("sha256").update(JSON.stringify(canonical), "utf8").digest("hex");
+}
+/**
+ * Builds the binding from TRUSTED values only. It deliberately does not take a `CorrelationMetadata`.
+ *
+ * It used to read `workspace_id` and `context_id` straight out of caller-supplied correlation into what
+ * the comment above calls the trusted scope, and a bound approval could then be spent outside the
+ * workspace it named (R-110): approve a delegation carrying a real, registry-validated `workspace` spec,
+ * then re-issue the identical task with `correlation.workspace_id` set and NO `workspace` field — no
+ * registry lookup, no lease, the parent's own cwd, and every digest still matching. The guard that would
+ * have caught it can only fire when there is a spec to disagree with.
+ *
+ * `workspaceId` must therefore be the id of a workspace that was actually resolved and leased.
+ * `contextId` is a caller-declared label that nothing validates; it is included because it can only
+ * ever NARROW a binding, and a mismatch fails closed.
+ */
+export function buildApprovalBinding(input) {
+    const requested = [...new Set(input.requested)].sort();
+    const effective = [...new Set(input.effective)].sort();
+    return {
+        version: "1",
+        task_sha256: digestTask(input.task),
+        requested_sha256: digestCapabilities(requested),
+        effective_sha256: digestCapabilities(effective),
+        requested,
+        effective,
+        ...(input.definitionSha256 ? { definition_sha256: input.definitionSha256 } : {}),
+        ...(input.workspaceId ? { workspace_id: input.workspaceId } : {}),
+        ...(input.contextId ? { context_id: input.contextId } : {}),
+        ...(input.treeSha !== undefined ? { tree_sha: input.treeSha } : {}),
+        ...(input.lastChangeSeq !== undefined ? { last_change_seq: input.lastChangeSeq } : {}),
+        parent_id: input.parentId,
+    };
+}
+export function approvalBindingDigest(binding) {
+    const ordered = {
+        version: binding.version,
+        task_sha256: binding.task_sha256,
+        requested_sha256: binding.requested_sha256,
+        effective_sha256: binding.effective_sha256,
+        requested: binding.requested,
+        effective: binding.effective,
+        definition_sha256: binding.definition_sha256 ?? null,
+        workspace_id: binding.workspace_id ?? null,
+        context_id: binding.context_id ?? null,
+        // Keep the exact pre-ADR-0039 serialization when both additions are absent: persisted approvals store
+        // this digest, so unconditional null placeholders would invalidate every existing bound approval.
+        ...(binding.tree_sha !== undefined ? { tree_sha: binding.tree_sha } : {}),
+        ...(binding.last_change_seq !== undefined ? { last_change_seq: binding.last_change_seq } : {}),
+        parent_id: binding.parent_id,
+    };
+    return createHash("sha256").update(JSON.stringify(ordered), "utf8").digest("hex");
+}
+export function isApprovalBinding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const binding = value;
+    return (binding.version === "1" &&
+        [binding.task_sha256, binding.requested_sha256, binding.effective_sha256].every((digest) => typeof digest === "string" && /^[a-f0-9]{64}$/i.test(digest)) &&
+        Array.isArray(binding.requested) &&
+        binding.requested.every((item) => typeof item === "string") &&
+        Array.isArray(binding.effective) &&
+        binding.effective.every((item) => typeof item === "string") &&
+        typeof binding.parent_id === "string" &&
+        ["definition_sha256", "workspace_id", "context_id", "tree_sha"].every((key) => {
+            const value = binding[key];
+            return value === undefined || typeof value === "string";
+        }) &&
+        (binding.last_change_seq === undefined ||
+            (typeof binding.last_change_seq === "number" && Number.isFinite(binding.last_change_seq))) &&
+        // Self-consistency. This guard's only trust boundary is a binding parsed off DISK
+        // (`approval-store.ts`), so an internally contradictory record — digests that do not match the
+        // capability arrays sitting beside them — must be unrepresentable rather than merely unlikely.
+        binding.requested_sha256 === digestCapabilities(binding.requested) &&
+        binding.effective_sha256 === digestCapabilities(binding.effective));
+}
+export function approvalBindingsEqual(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    if (!isApprovalBinding(a) || !isApprovalBinding(b))
+        return false;
+    return approvalBindingDigest(a) === approvalBindingDigest(b);
+}
+//# sourceMappingURL=correlation.js.map

package/dist/kernel/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../../src/kernel/correlation.ts"],"names":[],"mappings":"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"}

package/dist/kernel/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/kernel/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,eAAe,GAAG,gBAAgB,CAM9E;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oFAAoF;IACpF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA8DzF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,eAAe,GAAG,iBAAiB,CA2BnF;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAaxF"}

package/dist/kernel/definitions.js

@@ -0,0 +1,164 @@
+/**
+ * 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 } from "node:fs/promises";
+import { resolveSkillResources, skillResourceName } from "./skill-resources.js";
+import { CAPABILITY_NAMESPACE_PREFIXES } from "./capabilities.js";
+/**
+ * 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) {
+    return {
+        name: definition.name,
+        source: definition.source,
+        sha256: createHash("sha256").update(definition.body, "utf8").digest("hex"),
+    };
+}
+/**
+ * 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, text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    if (!match)
+        return null;
+    const fields = new Map();
+    const metadata = {};
+    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 = [];
+            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;
+        }
+        // A YAML collection/block we cannot parse is not an explicit empty ceiling.
+        if (key === "allowed-tools" && value === "") {
+            const nextValue = lines.slice(i + 1).find((line) => line.trim() !== "" && !/^\s*#/.test(line));
+            if (/^\s+\S/.test(nextValue ?? ""))
+                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: skillResourceName(source),
+        description,
+        allowedTools: fields.get("allowed-tools"),
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+        body: text.slice(match[0].length).trim(),
+        source,
+    };
+}
+/**
+ * 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) {
+    const raw = definition.allowedTools;
+    if (raw === undefined)
+        return { capabilities: [], patterns: [], undeclared: true };
+    const capabilities = new Set();
+    const patterns = [];
+    // 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;
+        }
+        // Every namespaced id passes through untouched; only a BARE tool name gets the `tool:` prefix and the
+        // lowercasing. `workspace:` was missing here after ADR-0035 taught `normaliseCapability` about it, so a
+        // definition declaring `allowed-tools: workspace:prod` produced `tool:workspace:prod` — a capability
+        // that names nothing, refused as unknown, and dropped by `init` as "probably a typo or an attack". Two
+        // spellings of one grammar with this one wrong is R-28's shape; the list is now shared.
+        if (CAPABILITY_NAMESPACE_PREFIXES.some((prefix) => entry.startsWith(prefix))) {
+            capabilities.add(entry);
+            continue;
+        }
+        capabilities.add(`tool:${entry.toLowerCase()}`);
+    }
+    return { capabilities: [...capabilities].sort(), patterns, undeclared: false };
+}
+/**
+ * Read definitions from Pi's enabled resources, including installed packages and local overrides.
+ * Resolver precedence and filters are shared with the capability catalog; unregistered npm packages
+ * are not runtime resources until legacy init explicitly scaffolds them.
+ */
+export async function loadDefinitions(cwd) {
+    const definitions = new Map();
+    for (const { path } of (await resolveSkillResources(cwd)).skills) {
+        let text;
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseSkillDefinition(path, text);
+        if (parsed && !definitions.has(parsed.name))
+            definitions.set(parsed.name, parsed);
+    }
+    return definitions;
+}
+//# sourceMappingURL=definitions.js.map

package/dist/kernel/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/kernel/definitions.ts"],"names":[],"mappings":"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"}

package/dist/kernel/delegate-types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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 declare const EXECUTOR_KINDS: readonly ["process", "herdr"];
+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).
+ */
+//# sourceMappingURL=delegate-types.d.ts.map

package/dist/kernel/delegate-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-types.d.ts","sourceRoot":"","sources":["../../src/kernel/delegate-types.ts"],"names":[],"mappings":"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"}

package/dist/kernel/delegate-types.js

@@ -0,0 +1,9 @@
+/** 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"];
+/**
+ * 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).
+ */
+//# sourceMappingURL=delegate-types.js.map

package/dist/kernel/delegate-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-types.js","sourceRoot":"","sources":["../../src/kernel/delegate-types.ts"],"names":[],"mappings":"AAYA,2KAA2K;AAC3K,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,OAAO,CAAU,CAAC;AA+I5D;;;;;GAKG"}

package/dist/kernel/delegate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../../src/kernel/delegate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAkBlH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE5F,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG5F,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,EAAE,iBAAiB,GAAG,UAAU,CA4U7F"}