pi-daddy 0.17.0 → 0.18.0

package/dist/correlation.js

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+import { GovernanceRefusal, refusal } from "./refusals.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/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",
+]);
+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));
+}
+/**
+ * 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] = 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 (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 });
+        }
+        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 } : {}),
+        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,
+        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"].every((key) => {
+            const value = binding[key];
+            return value === undefined || typeof value === "string";
+        }) &&
+        // 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/correlation.js.map

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

package/dist/delegate-types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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";
+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;
+    /** 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;
+    /** 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, 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;
+    /** 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/delegate-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-types.d.ts","sourceRoot":"","sources":["../src/delegate-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGvD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,qFAAqF;IACrF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sFAAsF;IACtF,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,8FAA8F;IAC9F,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,sGAAsG;IACtG,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;;GAKG"}

package/dist/delegate-types.js

@@ -0,0 +1,8 @@
+export {};
+/**
+ * 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/delegate-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-types.js","sourceRoot":"","sources":["../src/delegate-types.ts"],"names":[],"mappings":";AA0IA;;;;;GAKG"}

package/dist/delegate.d.ts

@@ -1,133 +1,9 @@
 /**
- * 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.
+ * 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 { type DefinitionDigest, type SkillDefinition } from "./definitions.ts";
-import { type Capability, type ResolveResult } from "./resolve.ts";
 export { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
-import { type InheritableApproval } from "./approval.ts";
-import { 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).
- */
+import type { Delegation, DelegationContext, DelegationRequest } from "./delegate-types.ts";
+export type { Delegation, DelegationContext, DelegationRequest } from "./delegate-types.ts";
 export declare function planDelegation(request: DelegationRequest, ctx: DelegationContext): Delegation;
 //# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAA0C,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvH,OAAO,EAA4B,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAO7F,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAElH,OAAO,EAAsC,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAA0C,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAEpF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,qFAAqF;IACrF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sFAAsF;IACtF,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,EAAE,iBAAiB,GAAG,UAAU,CA8P7F"}
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAYlH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC5F,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE5F,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,EAAE,iBAAiB,GAAG,UAAU,CA+Q7F"}