pi-daddy 0.28.0 → 0.32.1

package/dist/kernel/propagation.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Race-free grant propagation.
+ *
+ * The first implementation wrote each child's computed grant into `process.env` inside the `tool_call`
+ * handler. The environment is process-global, so two concurrent spawns could read each other's values —
+ * a real hole in a security control.
+ *
+ * The fix removes the need for a per-child channel entirely, rather than trying to build one:
+ *
+ *   1. Everything pushed to children is a property of the PARENT, not of the individual spawn — the
+ *      parent's own grant, the child depth (parent depth + 1), and the configured bounds. Those are
+ *      identical for every sibling, so concurrent spawns cannot disagree and there is nothing to race.
+ *      `ENV_APPROVED` (approvals a human granted at or above this level) is safe on the same global
+ *      channel for the same reason: it is intersected with the parent's own grant before being written,
+ *      which is itself a parent-level fact, so it too is identical for every sibling.
+ *   2. Each child derives ITS OWN grant on arrival: `inheritedParentGrant ∩ ownObservedTools`, where the
+ *      observed set comes from the `tools` array of its first provider request — authoritative, because
+ *      it is literally what pi sent the model.
+ *
+ * The environment is therefore written ONCE per session, before any spawn can occur (the first provider
+ * request precedes any tool call), and never mutated per spawn.
+ *
+ * The invariant still holds transitively: own = observed ∩ inheritedParent ⊆ inheritedParent, so no
+ * descendant can exceed the root. It is also defence in depth — even if a spawn slipped past the
+ * interceptor and pi handed the child more than the parent held, the intersection clamps it back.
+ */
+import type { Capability } from "./resolve.ts";
+import { type InheritableApproval } from "./approval.ts";
+export { ENV_GRANT, ENV_FANOUT, ENV_PARENT_ID, ENV_EXECUTION_ID, ENV_DEPTH, ENV_MAX_DEPTH, ENV_GATED, ENV_LEDGER, ENV_APPROVED, } from "./env-names.ts";
+/**
+ * Total descendants this session may create in its whole subtree (`src/kernel/fanout.ts`).
+ *
+ * In `GRANT_ENV_KEYS` and therefore stripped from a child's environment and re-supplied only by the spawn
+ * plan — like depth, and for the same reason: it is capability state that must ATTENUATE downward, not an
+ * operator preference that should inherit. `PI_DADDY_CHILD_TIMEOUT` is deliberately the other kind.
+ */
+/**
+ * This session's ledger id, so a child's records name their real parent (review finding F8).
+ *
+ * Without it every level restarts at `d0` and the ledger cannot be joined into a tree across processes.
+ */
+/** Unique identity of this governed execution occurrence; unlike ENV_PARENT_ID it is never reused. */
+/**
+ * Every variable this package uses to push governance state at a child.
+ *
+ * Named as a set so `mergeChildEnv` can guarantee that none of them survives from the parent's own
+ * environment into a child's — a governance variable a child inherits by accident is one nobody decided
+ * to give it.
+ */
+export declare const GRANT_ENV_KEYS: readonly ["PI_DADDY_GRANT", "PI_DADDY_DEPTH", "PI_DADDY_MAX_DEPTH", "PI_DADDY_GATED", "PI_DADDY_LEDGER", "PI_DADDY_APPROVED", "PI_DADDY_FANOUT", "PI_DADDY_PARENT_ID", "PI_DADDY_EXECUTION_ID"];
+export declare const parseList: (raw: string | undefined) => Capability[];
+/**
+ * Derive this session's own grant from what it inherited and what pi actually gave it.
+ *
+ * `observedTools` is the bare tool-name list from the session's own provider payload, or null when it
+ * has not been observed yet — in which case the inherited grant is used unchanged (it is already an
+ * upper bound, so this is safe, just less tight).
+ *
+ * A wildcard holder stays a wildcard holder: an enumerated observation must not silently downgrade an
+ * explicitly unlimited grant, or a root session would lose the authority it was configured with.
+ *
+ * **R-36 / ADR-0017 step 1: only tool-shaped capabilities are filtered.** The observation is a list of
+ * TOOLS, so it is evidence about `tool:` and `ext:` and about nothing else. Until this was fixed, a child
+ * inheriting `tool:read, skill:review` held only `tool:read` from its first provider request onward — it
+ * still *had* the skill (it arrives as `--skill`), but could not re-grant it and `/grants` stopped listing
+ * it. Silently, and in the narrowing direction, which is why it survived: nothing fails when a grant
+ * quietly shrinks. It also made ADR-0017's `agent:` prerequisite unsatisfiable below the root.
+ */
+export declare function deriveOwnGrant(inheritedParentGrant: Capability[], observedTools: string[] | null): Capability[];
+/**
+ * Parse a bound from the environment, distinguishing **absent** from **malformed**.
+ *
+ * G7 / A-S4 + B-I4. `Number.parseInt` is the wrong tool for reading configuration: it accepts a numeric
+ * prefix (`parseInt("2abc")` is `2`), returns `NaN` for anything else, and `NaN` silently passes every
+ * comparison as false — so a malformed `PI_DADDY_MAX_DEPTH` did not tighten the limit, it removed it.
+ *
+ * The three-way return is the point. `undefined` means "not configured, use the documented default";
+ * `null` means "configured wrongly", which callers must treat as a failure rather than a default,
+ * because a value someone tried to set and mistyped is not the same as one they never set.
+ */
+export declare function parseBound(raw: string | undefined): number | null | undefined;
+export interface DepthConfig {
+    depth: number;
+    maxDepth: number;
+    /** Names of the variables that were set but unreadable, for an operator-facing warning. */
+    malformed: string[];
+}
+/**
+ * Resolve this session's depth bounds, failing closed on anything malformed.
+ *
+ * **Malformed input disables spawning entirely (`maxDepth: 0`)** rather than falling back to a default,
+ * and that applies to a bad `PI_DADDY_DEPTH` just as much as a bad `PI_DADDY_MAX_DEPTH`. The old
+ * `|| 0` guard on depth failed open in a subtler way than the missing guard on maxDepth: a session that
+ * could not read its own depth was treated as a **root**, which is the most permissive answer available
+ * and precisely the value an attacker would choose. If we do not know how deep we are, we must not spawn.
+ */
+export declare function depthConfig(depthRaw: string | undefined, maxDepthRaw: string | undefined): DepthConfig;
+/** The documented default child-depth bound when `PI_DADDY_MAX_DEPTH` is not set. */
+export declare const DEFAULT_MAX_DEPTH = 2;
+/**
+ * Gated by default in a governed session (ADR-0012).
+ *
+ * `bash` is not one capability among others; it is an execution primitive. A child holding it can run
+ * `env -u PI_DADDY_GRANT pi …` and obtain a completely **ungoverned** descendant — measured, not
+ * theorised (probe `g5-bash-escape`). Handing that down silently is the thing worth changing.
+ *
+ * Subsumption-aware gating (also ADR-0012) means this single entry covers `write`, `edit`, `read`,
+ * `grep`, `find` and `ls` as well, since `bash` confers all of them.
+ */
+export declare const DEFAULT_GATED: Capability[];
+/**
+ * Read the gate list, distinguishing **absent** from **explicitly empty**.
+ *
+ * `parseList` alone cannot: it maps both `undefined` and `""` to `[]`. That distinction is the operator's
+ * only way to turn the default off — without it, someone who wants no gates would have to stop governing
+ * altogether, which is strictly worse than the thing they were trying to avoid.
+ */
+export declare function gatedFromEnv(raw: string | undefined): Capability[];
+export interface ChildEnvInput {
+    /** This session's own grant — becomes the child's inherited parent grant. */
+    ownGrant: Capability[];
+    /** This session's depth; children are one deeper. */
+    depth: number;
+    maxDepth: number;
+    gated: Capability[];
+    /**
+     * Gated capabilities a human approved at or above this level.
+     *
+     * Safe to push on the GLOBAL channel because it is intersected with THIS session's own grant, which is
+     * a parent-level fact — identical for every sibling, so there is nothing to race on. Each child then
+     * re-intersects with its own grant on arrival, exactly as it does for the grant itself.
+     */
+    /**
+     * Approvals eligible to cross the boundary (ADR-0014): capability, subject and scope. `once` is
+     * dropped by `inheritApprovals`, and the subject is preserved so it cannot satisfy another one.
+     */
+    approved?: InheritableApproval[];
+    ledgerPath?: string;
+    /**
+     * Whether THIS session is governed — i.e. `PI_DADDY_GRANT` was set for it.
+     *
+     * G7 / B-I8. Governance is opt-in: with the variable unset the README promises "nothing is blocked".
+     * That was true of the session itself and false of its children, because this function still exported
+     * a grant, a depth and a bound, so an ungoverned parent silently started governing its descendants —
+     * and the grant it exported was its own observed tool surface, which is a real restriction arrived at
+     * by accident. An ungoverned session must be transparent, not a source of policy.
+     *
+     * Defaults to `true` so that every existing caller keeps publishing; only the extension, which alone
+     * knows whether the variable was set, passes `false`.
+     */
+    governed?: boolean;
+}
+/**
+ * The environment a child should inherit. Constant across all of this session's children by
+ * construction, which is what makes concurrent spawning safe.
+ *
+ * **The wildcard is never inherited.** A root may HOLD `tool:*` — that is authority to grant anything —
+ * but handing it down would let every descendant reacquire the full catalog, which makes attenuation
+ * meaningless below the root. Children therefore inherit the ENUMERATED grant only.
+ *
+ * Consequence, deliberate: a wildcard root that has not yet observed its own tools hands children an
+ * empty grant, so they can spawn nothing. That fails closed. It is also unreachable in normal flow,
+ * because a session's first provider request always precedes its first tool call.
+ */
+/**
+ * The part of a grant a child may inherit: everything but the wildcards that are HELD, never handed down.
+ *
+ * `tool:*` for R-26's reason — a root that handed it down let every descendant reacquire the full catalog.
+ * `workspace:*` for the same reason one namespace over (R-131): a descendant holding it could route anywhere
+ * the registry lists, which is the attenuation failure ADR-0035 exists to close. `agent:*` is deliberately
+ * NOT stripped — ADR-0023 decided that a session authorised for any definition passes that on, because
+ * definitions are ceilings rather than roots.
+ *
+ * **Exported, and there is exactly one spelling of this rule on purpose.** It shipped as a filter inline in
+ * `childEnv` and nowhere else, so a grant travelling the OTHER path — `delegate.ts` building a child's
+ * `PI_DADDY_GRANT` from `result.effective` — carried `workspace:*` straight down. The test written beside
+ * that fix exercised `childEnv`, which is not the path a delegated child's grant travels, so it could not
+ * catch it. R-28's shape: two routes for one rule, with the guard on the quieter one. Both call this now.
+ */
+export declare function inheritableGrant(grant: readonly Capability[]): Capability[];
+export declare function childEnv(input: ChildEnvInput): Record<string, string>;
+/**
+ * The environment for a child this process spawns itself: the parent's environment with every governance
+ * variable stripped, then the per-child plan applied.
+ *
+ * Spreading `{ ...process.env, ...plan.env }` is not enough. `plan.env` omits keys that do not apply to
+ * this child (an empty approval set, no gated list), and an omitted key does not overwrite — so the
+ * parent's own value survives into the child. Stripping first makes the plan the ONLY source of every
+ * governance variable, which is what `delegate.ts`'s "nothing is written to the shared `process.env`"
+ * claim actually requires. Consumers re-clamp anyway; this is the defence in depth behind that.
+ */
+export declare function mergeChildEnv(parentEnv: NodeJS.ProcessEnv, planEnv: Record<string, string>): NodeJS.ProcessEnv;
+/** Extract bare tool names from a provider payload's tool array, tolerating provider shape differences. */
+export declare function observeToolNames(payload: unknown): string[] | null;
+//# sourceMappingURL=propagation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.ts","sourceRoot":"","sources":["../../src/kernel/propagation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAa3E,OAAO,EACL,SAAS,EACT,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB;;;;;;GAMG;AACH;;;;GAIG;AACH,sGAAsG;AAEtG;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,iMAUjB,CAAC;AAEX,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,UAAU,EAI9B,CAAC;AAkBjC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,oBAAoB,EAAE,UAAU,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,UAAU,EAAE,CAc/G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAO7E;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAStG;AAED,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE,UAAU,EAAkB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,EAAE,CAGlE;AAED,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB;;;;;;OAMG;IACH;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,EAAE,CAE3E;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,UAAU,CAI9G;AAED,2GAA2G;AAC3G,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,IAAI,CAoBlE"}

package/dist/kernel/propagation.js

@@ -0,0 +1,275 @@
+/**
+ * Race-free grant propagation.
+ *
+ * The first implementation wrote each child's computed grant into `process.env` inside the `tool_call`
+ * handler. The environment is process-global, so two concurrent spawns could read each other's values —
+ * a real hole in a security control.
+ *
+ * The fix removes the need for a per-child channel entirely, rather than trying to build one:
+ *
+ *   1. Everything pushed to children is a property of the PARENT, not of the individual spawn — the
+ *      parent's own grant, the child depth (parent depth + 1), and the configured bounds. Those are
+ *      identical for every sibling, so concurrent spawns cannot disagree and there is nothing to race.
+ *      `ENV_APPROVED` (approvals a human granted at or above this level) is safe on the same global
+ *      channel for the same reason: it is intersected with the parent's own grant before being written,
+ *      which is itself a parent-level fact, so it too is identical for every sibling.
+ *   2. Each child derives ITS OWN grant on arrival: `inheritedParentGrant ∩ ownObservedTools`, where the
+ *      observed set comes from the `tools` array of its first provider request — authoritative, because
+ *      it is literally what pi sent the model.
+ *
+ * The environment is therefore written ONCE per session, before any spawn can occur (the first provider
+ * request precedes any tool call), and never mutated per spawn.
+ *
+ * The invariant still holds transitively: own = observed ∩ inheritedParent ⊆ inheritedParent, so no
+ * descendant can exceed the root. It is also defence in depth — even if a spawn slipped past the
+ * interceptor and pi handed the child more than the parent held, the intersection clamps it back.
+ */
+import { WILDCARD } from "./pi-tools.js";
+import { WORKSPACE_WILDCARD } from "./resolve.js";
+import { inheritApprovals } from "./approval.js";
+import { assertCapabilitiesArePropagatable } from "./capabilities.js";
+import { ENV_GRANT, ENV_FANOUT, ENV_PARENT_ID, ENV_EXECUTION_ID, ENV_DEPTH, ENV_MAX_DEPTH, ENV_GATED, ENV_LEDGER, ENV_APPROVED, } from "./env-names.js";
+export { ENV_GRANT, ENV_FANOUT, ENV_PARENT_ID, ENV_EXECUTION_ID, ENV_DEPTH, ENV_MAX_DEPTH, ENV_GATED, ENV_LEDGER, ENV_APPROVED, } from "./env-names.js";
+/**
+ * Total descendants this session may create in its whole subtree (`src/kernel/fanout.ts`).
+ *
+ * In `GRANT_ENV_KEYS` and therefore stripped from a child's environment and re-supplied only by the spawn
+ * plan — like depth, and for the same reason: it is capability state that must ATTENUATE downward, not an
+ * operator preference that should inherit. `PI_DADDY_CHILD_TIMEOUT` is deliberately the other kind.
+ */
+/**
+ * This session's ledger id, so a child's records name their real parent (review finding F8).
+ *
+ * Without it every level restarts at `d0` and the ledger cannot be joined into a tree across processes.
+ */
+/** Unique identity of this governed execution occurrence; unlike ENV_PARENT_ID it is never reused. */
+/**
+ * Every variable this package uses to push governance state at a child.
+ *
+ * Named as a set so `mergeChildEnv` can guarantee that none of them survives from the parent's own
+ * environment into a child's — a governance variable a child inherits by accident is one nobody decided
+ * to give it.
+ */
+export const GRANT_ENV_KEYS = [
+    ENV_GRANT,
+    ENV_DEPTH,
+    ENV_MAX_DEPTH,
+    ENV_GATED,
+    ENV_LEDGER,
+    ENV_APPROVED,
+    ENV_FANOUT,
+    ENV_PARENT_ID,
+    ENV_EXECUTION_ID,
+];
+export const parseList = (raw) => (raw ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+/** Does a bare pi tool name correspond to this capability? `read` matches `tool:read` and `ext:pkg/read`. */
+function matchesToolName(capability, toolName) {
+    if (capability === `tool:${toolName}`)
+        return true;
+    return capability.startsWith("ext:") && capability.slice(capability.lastIndexOf("/") + 1) === toolName;
+}
+/**
+ * Is this capability something an observed tool array can speak about at all? (R-36, ADR-0017 step 1.)
+ *
+ * `tool:` and `ext:` name tools, so a tool array that omits one is evidence the session does not have it.
+ * `skill:` and `agent:` name a loadable instruction file and a spawnable definition — neither is ever a
+ * tool, so an observation says **nothing** about them and must not be read as evidence of absence.
+ */
+const isToolCapability = (capability) => capability.startsWith("tool:") || capability.startsWith("ext:");
+/**
+ * Derive this session's own grant from what it inherited and what pi actually gave it.
+ *
+ * `observedTools` is the bare tool-name list from the session's own provider payload, or null when it
+ * has not been observed yet — in which case the inherited grant is used unchanged (it is already an
+ * upper bound, so this is safe, just less tight).
+ *
+ * A wildcard holder stays a wildcard holder: an enumerated observation must not silently downgrade an
+ * explicitly unlimited grant, or a root session would lose the authority it was configured with.
+ *
+ * **R-36 / ADR-0017 step 1: only tool-shaped capabilities are filtered.** The observation is a list of
+ * TOOLS, so it is evidence about `tool:` and `ext:` and about nothing else. Until this was fixed, a child
+ * inheriting `tool:read, skill:review` held only `tool:read` from its first provider request onward — it
+ * still *had* the skill (it arrives as `--skill`), but could not re-grant it and `/grants` stopped listing
+ * it. Silently, and in the narrowing direction, which is why it survived: nothing fails when a grant
+ * quietly shrinks. It also made ADR-0017's `agent:` prerequisite unsatisfiable below the root.
+ */
+export function deriveOwnGrant(inheritedParentGrant, observedTools) {
+    if (observedTools === null)
+        return [...inheritedParentGrant];
+    // Capabilities an observation cannot speak about ride through both branches untouched.
+    const nonTool = inheritedParentGrant.filter((c) => !isToolCapability(c) && c !== WILDCARD);
+    if (inheritedParentGrant.includes(WILDCARD)) {
+        // Keep the wildcard, and additionally enumerate what was observed so descendants can be checked
+        // against concrete names too.
+        const enumerated = observedTools.map((t) => `tool:${t}`);
+        return [...new Set([WILDCARD, ...enumerated, ...nonTool])].sort();
+    }
+    return [
+        ...inheritedParentGrant.filter((c) => isToolCapability(c) && observedTools.some((t) => matchesToolName(c, t))),
+        ...nonTool,
+    ].sort();
+}
+/**
+ * Parse a bound from the environment, distinguishing **absent** from **malformed**.
+ *
+ * G7 / A-S4 + B-I4. `Number.parseInt` is the wrong tool for reading configuration: it accepts a numeric
+ * prefix (`parseInt("2abc")` is `2`), returns `NaN` for anything else, and `NaN` silently passes every
+ * comparison as false — so a malformed `PI_DADDY_MAX_DEPTH` did not tighten the limit, it removed it.
+ *
+ * The three-way return is the point. `undefined` means "not configured, use the documented default";
+ * `null` means "configured wrongly", which callers must treat as a failure rather than a default,
+ * because a value someone tried to set and mistyped is not the same as one they never set.
+ */
+export function parseBound(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    // Exact non-negative decimal integers only: no signs, no fractions, no 0x, no numeric prefixes.
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    const value = Number(trimmed);
+    return Number.isSafeInteger(value) ? value : null;
+}
+/**
+ * Resolve this session's depth bounds, failing closed on anything malformed.
+ *
+ * **Malformed input disables spawning entirely (`maxDepth: 0`)** rather than falling back to a default,
+ * and that applies to a bad `PI_DADDY_DEPTH` just as much as a bad `PI_DADDY_MAX_DEPTH`. The old
+ * `|| 0` guard on depth failed open in a subtler way than the missing guard on maxDepth: a session that
+ * could not read its own depth was treated as a **root**, which is the most permissive answer available
+ * and precisely the value an attacker would choose. If we do not know how deep we are, we must not spawn.
+ */
+export function depthConfig(depthRaw, maxDepthRaw) {
+    const depth = parseBound(depthRaw);
+    const maxDepth = parseBound(maxDepthRaw);
+    const malformed = [];
+    if (depth === null)
+        malformed.push(ENV_DEPTH);
+    if (maxDepth === null)
+        malformed.push(ENV_MAX_DEPTH);
+    if (malformed.length > 0)
+        return { depth: depth ?? 0, maxDepth: 0, malformed };
+    return { depth: depth ?? 0, maxDepth: maxDepth ?? DEFAULT_MAX_DEPTH, malformed };
+}
+/** The documented default child-depth bound when `PI_DADDY_MAX_DEPTH` is not set. */
+export const DEFAULT_MAX_DEPTH = 2;
+/**
+ * Gated by default in a governed session (ADR-0012).
+ *
+ * `bash` is not one capability among others; it is an execution primitive. A child holding it can run
+ * `env -u PI_DADDY_GRANT pi …` and obtain a completely **ungoverned** descendant — measured, not
+ * theorised (probe `g5-bash-escape`). Handing that down silently is the thing worth changing.
+ *
+ * Subsumption-aware gating (also ADR-0012) means this single entry covers `write`, `edit`, `read`,
+ * `grep`, `find` and `ls` as well, since `bash` confers all of them.
+ */
+export const DEFAULT_GATED = ["tool:bash"];
+/**
+ * Read the gate list, distinguishing **absent** from **explicitly empty**.
+ *
+ * `parseList` alone cannot: it maps both `undefined` and `""` to `[]`. That distinction is the operator's
+ * only way to turn the default off — without it, someone who wants no gates would have to stop governing
+ * altogether, which is strictly worse than the thing they were trying to avoid.
+ */
+export function gatedFromEnv(raw) {
+    if (raw === undefined)
+        return [...DEFAULT_GATED];
+    return parseList(raw);
+}
+/**
+ * The environment a child should inherit. Constant across all of this session's children by
+ * construction, which is what makes concurrent spawning safe.
+ *
+ * **The wildcard is never inherited.** A root may HOLD `tool:*` — that is authority to grant anything —
+ * but handing it down would let every descendant reacquire the full catalog, which makes attenuation
+ * meaningless below the root. Children therefore inherit the ENUMERATED grant only.
+ *
+ * Consequence, deliberate: a wildcard root that has not yet observed its own tools hands children an
+ * empty grant, so they can spawn nothing. That fails closed. It is also unreachable in normal flow,
+ * because a session's first provider request always precedes its first tool call.
+ */
+/**
+ * The part of a grant a child may inherit: everything but the wildcards that are HELD, never handed down.
+ *
+ * `tool:*` for R-26's reason — a root that handed it down let every descendant reacquire the full catalog.
+ * `workspace:*` for the same reason one namespace over (R-131): a descendant holding it could route anywhere
+ * the registry lists, which is the attenuation failure ADR-0035 exists to close. `agent:*` is deliberately
+ * NOT stripped — ADR-0023 decided that a session authorised for any definition passes that on, because
+ * definitions are ceilings rather than roots.
+ *
+ * **Exported, and there is exactly one spelling of this rule on purpose.** It shipped as a filter inline in
+ * `childEnv` and nowhere else, so a grant travelling the OTHER path — `delegate.ts` building a child's
+ * `PI_DADDY_GRANT` from `result.effective` — carried `workspace:*` straight down. The test written beside
+ * that fix exercised `childEnv`, which is not the path a delegated child's grant travels, so it could not
+ * catch it. R-28's shape: two routes for one rule, with the guard on the quieter one. Both call this now.
+ */
+export function inheritableGrant(grant) {
+    return grant.filter((c) => c !== WILDCARD && c !== WORKSPACE_WILDCARD);
+}
+export function childEnv(input) {
+    if (input.governed === false)
+        return {};
+    const inheritable = inheritableGrant(input.ownGrant);
+    const env = {
+        [ENV_GRANT]: (assertCapabilitiesArePropagatable(inheritable), inheritable.join(",")),
+        [ENV_DEPTH]: String(input.depth + 1),
+        [ENV_MAX_DEPTH]: String(input.maxDepth),
+    };
+    if (input.gated.length > 0)
+        env[ENV_GATED] = input.gated.join(",");
+    // ALWAYS written, empty string included. This is the one value that changes during a session (a human
+    // approves something, or the session's own grant narrows on observation), and the interceptor path
+    // publishes it by ASSIGNING into the process-global `process.env`. Omitting it when empty would leave
+    // whatever was there before — the parent's own, unclamped `PI_DADDY_APPROVED` — visible to every child.
+    // `parseList("")` is `[]`, so an empty value reads back exactly as an absent one.
+    env[ENV_APPROVED] = inheritApprovals(input.approved ?? [], inheritable).join(",");
+    // Empty is an explicit one-run ledger opt-out and must overwrite a prior publication too.
+    if (input.ledgerPath !== undefined)
+        env[ENV_LEDGER] = input.ledgerPath;
+    return env;
+}
+/**
+ * The environment for a child this process spawns itself: the parent's environment with every governance
+ * variable stripped, then the per-child plan applied.
+ *
+ * Spreading `{ ...process.env, ...plan.env }` is not enough. `plan.env` omits keys that do not apply to
+ * this child (an empty approval set, no gated list), and an omitted key does not overwrite — so the
+ * parent's own value survives into the child. Stripping first makes the plan the ONLY source of every
+ * governance variable, which is what `delegate.ts`'s "nothing is written to the shared `process.env`"
+ * claim actually requires. Consumers re-clamp anyway; this is the defence in depth behind that.
+ */
+export function mergeChildEnv(parentEnv, planEnv) {
+    const merged = { ...parentEnv };
+    for (const key of GRANT_ENV_KEYS)
+        delete merged[key];
+    return { ...merged, ...planEnv };
+}
+/** Extract bare tool names from a provider payload's tool array, tolerating provider shape differences. */
+export function observeToolNames(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const record = payload;
+    for (const key of ["tools", "functions"]) {
+        const candidate = record[key];
+        if (!Array.isArray(candidate))
+            continue;
+        const names = candidate
+            .map((entry) => {
+            if (!entry || typeof entry !== "object")
+                return undefined;
+            const e = entry;
+            // Anthropic/OpenAI tool objects, and OpenAI's nested `function.name` form.
+            const nested = e.function;
+            const name = e.name ?? nested?.name;
+            return typeof name === "string" ? name : undefined;
+        })
+            .filter((n) => Boolean(n));
+        // An empty tools array is a real observation (the session has no tools), not a failure to observe.
+        return names;
+    }
+    return null;
+}
+//# sourceMappingURL=propagation.js.map

package/dist/kernel/propagation.js.map

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

package/dist/kernel/refusals.d.ts

@@ -0,0 +1,16 @@
+export declare const REFUSAL_CODES: readonly ["CAPABILITY_ESCALATION", "GRANT_ID_MALFORMED", "DEFINITION_NOT_AUTHORIZED", "UNDECLARED_TOOLS", "UNKNOWN_TOOL", "GATED_UNAPPROVED", "APPROVAL_EXPIRED", "APPROVAL_SCOPE_MISMATCH", "APPROVAL_FLOW_FAILED", "DEPTH_EXCEEDED", "FANOUT_EXCEEDED", "EXECUTOR_UNAVAILABLE", "MODEL_UNRESOLVED", "GRANT_STORE_INVALID", "CHILD_TIMED_OUT", "CHILD_CANCELLED", "CHILD_EXIT_NONZERO", "TASK_MISSING", "UNKNOWN_DEFINITION", "CEILING_PATTERNS_UNRESOLVED", "NARROWING_VIOLATED", "DEFINITION_UNREADABLE", "CORRELATION_TOO_LARGE", "CORRELATION_INVALID", "LEDGER_WRITE_FAILED", "FANOUT_FAILED", "WORKSPACE_NOT_REGISTERED", "WORKSPACE_NOT_AUTHORIZED", "WORKSPACE_WRITE_CONFLICT", "WORKSPACE_LEASE_STALE", "LEDGER_DAMAGED"];
+export type RefusalCode = (typeof REFUSAL_CODES)[number];
+export interface StructuredRefusal {
+    code: RefusalCode;
+    /** Existing actionable diagnostic. Codes accompany rather than replace it. */
+    message: string;
+    details?: Record<string, string | number | boolean | null>;
+}
+export declare function refusal(code: RefusalCode, message: string, details?: StructuredRefusal["details"]): StructuredRefusal;
+/** Error shape for API callers. pi-facing tools still throw, as pi requires, while retaining a stable code. */
+export declare class GovernanceRefusal extends Error {
+    readonly code: RefusalCode;
+    readonly details?: StructuredRefusal["details"];
+    constructor(value: StructuredRefusal);
+}
+//# sourceMappingURL=refusals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refusals.d.ts","sourceRoot":"","sources":["../../src/kernel/refusals.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,qsBAqChB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,GAAG,iBAAiB,CAErH;AAED,+GAA+G;AAC/G,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;gBAEpC,KAAK,EAAE,iBAAiB;CAMrC"}

package/dist/kernel/refusals.js

@@ -0,0 +1,53 @@
+export const REFUSAL_CODES = [
+    "CAPABILITY_ESCALATION",
+    "GRANT_ID_MALFORMED",
+    "DEFINITION_NOT_AUTHORIZED",
+    "UNDECLARED_TOOLS",
+    "UNKNOWN_TOOL",
+    "GATED_UNAPPROVED",
+    "APPROVAL_EXPIRED",
+    "APPROVAL_SCOPE_MISMATCH",
+    "APPROVAL_FLOW_FAILED",
+    "DEPTH_EXCEEDED",
+    "FANOUT_EXCEEDED",
+    "EXECUTOR_UNAVAILABLE",
+    "MODEL_UNRESOLVED",
+    "GRANT_STORE_INVALID",
+    // Execution-phase outcomes. Without these, an external controller could distinguish a policy refusal
+    // from an internal error but not a lost writer lease from a user pressing stop (R-103).
+    "CHILD_TIMED_OUT",
+    "CHILD_CANCELLED",
+    "CHILD_EXIT_NONZERO",
+    // Planner refusals that previously carried a message and no code at all — including the narrowing
+    // violation, which is the hardest rule this package enforces (R-109).
+    "TASK_MISSING",
+    "UNKNOWN_DEFINITION",
+    "CEILING_PATTERNS_UNRESOLVED",
+    "NARROWING_VIOLATED",
+    "DEFINITION_UNREADABLE",
+    "CORRELATION_TOO_LARGE",
+    "CORRELATION_INVALID",
+    "LEDGER_WRITE_FAILED",
+    "FANOUT_FAILED",
+    "WORKSPACE_NOT_REGISTERED",
+    "WORKSPACE_NOT_AUTHORIZED",
+    "WORKSPACE_WRITE_CONFLICT",
+    "WORKSPACE_LEASE_STALE",
+    // ADR-0076 PR 3d: a ledger with a torn or tampered tail refuses appends until an explicit repair.
+    "LEDGER_DAMAGED",
+];
+export function refusal(code, message, details) {
+    return { code, message, ...(details && Object.keys(details).length > 0 ? { details: { ...details } } : {}) };
+}
+/** Error shape for API callers. pi-facing tools still throw, as pi requires, while retaining a stable code. */
+export class GovernanceRefusal extends Error {
+    code;
+    details;
+    constructor(value) {
+        super(value.message);
+        this.name = "GovernanceRefusal";
+        this.code = value.code;
+        this.details = value.details;
+    }
+}
+//# sourceMappingURL=refusals.js.map

package/dist/kernel/refusals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusals.js","sourceRoot":"","sources":["../../src/kernel/refusals.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,uBAAuB;IACvB,oBAAoB;IACpB,2BAA2B;IAC3B,kBAAkB;IAClB,cAAc;IACd,kBAAkB;IAClB,kBAAkB;IAClB,yBAAyB;IACzB,sBAAsB;IACtB,gBAAgB;IAChB,iBAAiB;IACjB,sBAAsB;IACtB,kBAAkB;IAClB,qBAAqB;IACrB,qGAAqG;IACrG,wFAAwF;IACxF,iBAAiB;IACjB,iBAAiB;IACjB,oBAAoB;IACpB,kGAAkG;IAClG,sEAAsE;IACtE,cAAc;IACd,oBAAoB;IACpB,6BAA6B;IAC7B,oBAAoB;IACpB,uBAAuB;IACvB,uBAAuB;IACvB,qBAAqB;IACrB,qBAAqB;IACrB,eAAe;IACf,0BAA0B;IAC1B,0BAA0B;IAC1B,0BAA0B;IAC1B,uBAAuB;IACvB,kGAAkG;IAClG,gBAAgB;CACR,CAAC;AAWX,MAAM,UAAU,OAAO,CAAC,IAAiB,EAAE,OAAe,EAAE,OAAsC;IAChG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/G,CAAC;AAED,+GAA+G;AAC/G,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,CAAc;IAClB,OAAO,CAAgC;IAEhD,YAAY,KAAwB;QAClC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC/B,CAAC;CACF"}