pi-daddy 0.27.4 → 0.32.0

package/dist/kernel/approval.js

@@ -0,0 +1,270 @@
+/**
+ * Approval model for gated capabilities — pure, so it is exhaustively testable without pi.
+ *
+ * `resolve()` computes `gatedBlocked`: capabilities a session legitimately holds but which may not enter
+ * a child's grant without a human saying so. This module decides WHAT a yes means — how far it reaches,
+ * how long it lasts, and what it is keyed to. It never performs I/O and never prompts; see
+ * `approval-store.ts` and `approval-prompt.ts` for those.
+ *
+ * ADR-0010 records the four decisions encoded here.
+ */
+import { WILDCARD } from "./pi-tools.js";
+import { approvalBindingsEqual } from "./correlation.js";
+/** How far a single yes reaches in time. */
+export const APPROVAL_SCOPES = ["once", "session", "always"];
+/** Where a yes came from, for the ledger. These call for different follow-ups, so they stay distinct. */
+export const APPROVAL_SOURCES = ["prompt", "session", "persisted", "inherited"];
+/**
+ * Subject used for delegate-path approvals.
+ *
+ * The delegate tool has no human-authored subject: the only things naming a child are the task string and
+ * the tool list, both chosen by the model. A key the model controls is not a key, so delegate approvals
+ * use this fixed literal — "allow write for delegations this session" — and are never persisted.
+ * Angle brackets cannot appear in an agent-type name (`parseAgentType` reads an identifier), so this can
+ * never collide with a real type.
+ */
+export const DELEGATE_SUBJECT = "<delegate>";
+/**
+ * Lifetime of a persisted approval.
+ *
+ * Deliberately a constant rather than an environment variable: a knob that silently extends every gate is
+ * the first thing an impatient operator would reach for.
+ */
+export const APPROVAL_TTL_DAYS = 30;
+const DAY_MS = 86_400_000;
+/** `tool:write` + `docs-writer` -> `tool:write@docs-writer`. */
+export function approvalKey(capability, subject) {
+    return `${capability}@${subject}`;
+}
+/**
+ * May this resolution raise an approval dialog?
+ *
+ * `resolve()` computes `denied` and `gatedBlocked` INDEPENDENTLY (deliberately — each rejection reason is
+ * reported rather than masked by whichever filter ran first), and both `decideSpawn` and `planDelegation`
+ * refuse outright on `denied` while still attaching the full result. So a request mixing a gated capability
+ * with one the session does not hold at all would otherwise prompt a human about the gated one and then be
+ * refused anyway for the other.
+ *
+ * That is not merely noise. A *session* yes is recorded and republished to children, and an *always* yes is
+ * written to disk for 30 days — both banked against a spawn that never happened, and both reachable by a
+ * model that appends one unheld capability to an otherwise ordinary request. A person is therefore only
+ * asked about a spawn that would actually proceed if they said yes.
+ *
+ * `clipped` is deliberately NOT a bar: it does not refuse a spawn, it just drops those capabilities from
+ * the child's grant, so the spawn does proceed and the question is real.
+ */
+export function shouldSeekApproval(result) {
+    if (!result)
+        return false;
+    if (result.denied.length > 0)
+        return false;
+    // ADR-0011. A grant retaining a universal capability is refused by `assertNarrowing` no matter what
+    // a human says, so asking is worse than useless: the dialog cannot change the outcome, and a
+    // `session`- or `always`-scoped yes given there is banked and reused for later spawns that DO
+    // proceed. Same harm the `denied` guard above exists to prevent.
+    if (result.universal.length > 0)
+        return false;
+    return result.gatedBlocked.length > 0;
+}
+/**
+ * Scopes a given call site may offer. `always` requires a **human-authored subject**.
+ *
+ * ADR-0019. The rule is unchanged; which paths satisfy it is not. `"interceptor"` used to be the only one
+ * and ADR-0016 deleted it, leaving `always` offerable from nowhere — 220 lines of persistence no live path
+ * could write to. `"definition"` is `delegate({agent})`, where ADR-0017 makes the subject an
+ * operator-authored file the session must hold `agent:<name>` to name at all. `"delegate"` is the `tools:`
+ * form, where the original reasoning stands untouched: the only things naming that child are the task and
+ * the tool list, both model-chosen, and a key the model controls is not a key.
+ */
+export function offeredScopes(path) {
+    return path === "definition" ? ["once", "session", "always"] : ["once", "session"];
+}
+/**
+ * What a child may inherit, as `capability@subject` keys.
+ *
+ * ADR-0014 changed this in two ways, and both were cases of a human's explicit choice being discarded
+ * one hop down:
+ *
+ *  - **`once` is dropped** (A-S1). The scope chosen was not carried, so a `once` approval was written
+ *    into the child's `PI_DADDY_APPROVED` and republished onward — the most conservative answer a human
+ *    can give produced the least conservative outcome, across an entire descendant subtree.
+ *  - **The subject is kept** (A-S6). Bare capabilities were published, so a `<delegate>`-subject approval
+ *    matched *any* subject below. `approvalKey`'s own doc argues at length that a model-controlled name
+ *    is not a key; erasing the subject made that argument moot exactly where it mattered.
+ *
+ * The clamp to `grant` is unchanged and still load-bearing: **approval cannot conjure a capability**, so
+ * an inherited yes is only ever honoured for something the child independently holds.
+ */
+export function inheritApprovals(approved, grant) {
+    const held = new Set(grant);
+    return [
+        ...new Set(approved
+            .filter((a) => a.scope !== "once" && a.binding === undefined && a.capability !== WILDCARD && held.has(a.capability))
+            // A definition subject MUST carry a pin to cross a boundary (ADR-0022, hardened after F1).
+            //
+            // `verifyInherited` honours an unpinned entry by decision — `<delegate>` names no file and a
+            // pre-0.11 parent sends none — so an unpinned entry for a subject that *does* name a file is an
+            // approval exempt from the digest check. Enforcing it at the point of PUBLICATION rather than
+            // trusting each caller to attach a digest is what makes it structural: two call sites build these
+            // entries, one of them forgot, and every fresh approval crossed unpinned as a result. A caller that
+            // cannot produce a digest (the definition is not on disk here) now publishes nothing, which is the
+            // fail-closed direction.
+            .filter((a) => a.subject === DELEGATE_SUBJECT || Boolean(a.bodySha256))
+            .map((a) => approvalKey(a.capability, a.subject) + (a.bodySha256 ? `#${a.bodySha256}` : ""))),
+    ].sort();
+}
+/**
+ * Read the inherited set back on the child side.
+ *
+ * Anything that is not a well-formed `capability@subject` pair is dropped rather than guessed at. An
+ * unparseable entry granting nothing is a missing prompt; an unparseable entry granting *something* is a
+ * silent escalation, so the direction of the failure is not a matter of taste.
+ */
+export function parseInherited(raw) {
+    const out = new Map();
+    for (const item of (raw ?? "").split(",")) {
+        const trimmed = item.trim();
+        // ADR-0022 appends `#<sha256>`. Split it off FIRST: a `#` cannot appear in a capability id or in a
+        // definition name (identity comes from a path component), so this is unambiguous.
+        const hash = trimmed.indexOf("#");
+        const key = hash === -1 ? trimmed : trimmed.slice(0, hash);
+        const digest = hash === -1 ? undefined : trimmed.slice(hash + 1);
+        const at = key.indexOf("@");
+        if (at <= 0 || at === key.length - 1)
+            continue;
+        if (hash !== -1 && !digest)
+            continue; // `key#` promises a pin and carries none — drop it, do not guess
+        out.set(key, digest);
+    }
+    return out;
+}
+/**
+ * Drop inherited approvals that were given for different instructions (ADR-0022).
+ *
+ * The hole this closes: `resolveApprovals` checks `inherited` FIRST and none of it had ever been through
+ * `entryVerdict`, so ADR-0019's headline property — an approval is void once the instructions change — held
+ * on the one path that persists and neither of the two that do not. A child is a fresh process: it re-reads
+ * the definition from disk, so a `git pull` between the parent's approval and the child's spawn meant the
+ * child ran a rewritten body under a yes given about the old one, recording `approvalSource: "inherited"`.
+ *
+ * An entry with **no** digest is honoured, and that is not a hole: `<delegate>` legitimately has none, and
+ * neither does a pre-0.11 parent. It is the same trade `entryVerdict` refuses to make for a *persisted*
+ * entry — but that entry is 30 days old and read off disk, whereas this one was handed over by a live parent
+ * process in the same tree, which is a much shorter chain to trust.
+ */
+export function verifyInherited(parsed, snapshotOf) {
+    const out = new Set();
+    for (const [key, digest] of parsed) {
+        if (digest === undefined) {
+            out.add(key);
+            continue;
+        }
+        const current = snapshotOf(key.slice(key.indexOf("@") + 1));
+        if (current && current.bodySha256 === digest)
+            out.add(key);
+    }
+    return out;
+}
+/** When an approval granted now stops being valid. Computed once at write time and stored, so an entry's
+ *  lifetime is visible in the file rather than implied by whichever version of the code reads it. */
+export function expiryFor(approvedAt) {
+    return new Date(approvedAt.getTime() + APPROVAL_TTL_DAYS * DAY_MS).toISOString();
+}
+/**
+ * Decide whether a persisted approval still means what the human meant.
+ *
+ * Four ways it can stop meaning that, and each is reported distinctly so `/grants approvals` can explain
+ * itself rather than silently showing fewer rows:
+ *
+ *  - `foreign-cwd`  — the file was copied or committed and opened somewhere else. Nobody in THIS checkout
+ *                     was asked, so it authorises nothing here (R-27).
+ *  - `expired`      — a gate opened during one project must not still be open next quarter.
+ *  - `type-changed` — the confused deputy. The key names a file whose contents can change after approval:
+ *                     approve `tool:write@docs-writer` when it declares `read, write`, and later that file
+ *                     gains `bash`. The entry would still match the key while describing something the
+ *                     human never saw.
+ *  - `instructions-changed` — the same confused deputy, one level deeper. The tools are untouched but the
+ *                     BODY was rewritten, so the child would now be told to do something the human never
+ *                     saw. Only checkable since ADR-0018 gave the body a digest; an entry carrying no body
+ *                     pin lands here too, because unverifiable is not the same as unchanged.
+ *  - `type-missing` — the type was deleted or renamed; a new file could later claim the same name.
+ */
+export function entryVerdict(input) {
+    if (input.entry.cwd !== input.cwd)
+        return "foreign-cwd";
+    const expiresAt = new Date(input.entry.expiresAt).getTime();
+    // NaN <= x is false in JS, so an unparseable date would otherwise fail OPEN. A cache we cannot
+    // read the expiry of is a cache we do not trust — treat it as expired, per the spec's rule that a
+    // broken cache grants nothing.
+    if (!Number.isFinite(expiresAt) || expiresAt <= input.now.getTime())
+        return "expired";
+    if (input.current === null)
+        return "type-missing";
+    // Compare as sorted lists: reformatting or reordering a `tools:` line is not a change; adding,
+    // removing, or renaming a capability is.
+    const approved = [...input.entry.grantAtApproval].sort().join(",");
+    const current = [...input.current.ceiling].sort().join(",");
+    if (approved !== current)
+        return "type-changed";
+    // Fail closed on an unpinned entry: it was written before bodies were digested, so "unchanged" is not
+    // something this code can assert about it. One re-approval is the honest cost.
+    if (input.entry.bodyAtApproval !== input.current.bodySha256)
+        return "instructions-changed";
+    return "valid";
+}
+/**
+ * Satisfy as much of `gated` as possible without asking anyone.
+ *
+ * Precedence is inherited -> session -> persisted -> prompt. Order matters only for what gets REPORTED
+ * (the ledger's `approvalSource`); any hit satisfies equally. Checking all three before prompting is what
+ * stops an orchestrator's tenth delegation from raising a tenth identical dialog.
+ */
+export function resolveApprovals(input) {
+    // ADR-0014: these are `capability@subject` keys now, not bare capabilities, so an approval given for
+    // one subject can no longer satisfy another.
+    const inherited = input.inherited ?? new Set();
+    const approved = [];
+    const needsPrompt = [];
+    const scopeMismatched = [];
+    const expired = [];
+    const sources = {}, scopes = {};
+    const expiresAt = {};
+    for (const capability of [...new Set(input.gated)].sort()) {
+        const key = approvalKey(capability, input.subject);
+        const expected = input.expectedBinding;
+        const sessionBinding = input.sessionApprovalBindings?.get(key);
+        const persisted = input.persisted.get(key);
+        const inheritedApplies = expected === undefined && inherited.has(key);
+        const legacySessionApplies = expected === undefined && input.sessionApprovals.has(key);
+        const boundSessionApplies = expected !== undefined && approvalBindingsEqual(sessionBinding, expected);
+        const persistedApplies = persisted !== undefined &&
+            (expected === undefined ? persisted.binding === undefined : approvalBindingsEqual(persisted.binding, expected));
+        if (inheritedApplies) {
+            approved.push(capability);
+            sources[capability] = "inherited";
+            scopes[capability] = "session";
+        }
+        else if (legacySessionApplies || boundSessionApplies) {
+            approved.push(capability);
+            sources[capability] = "session";
+            scopes[capability] = "session";
+        }
+        else if (persistedApplies) {
+            approved.push(capability);
+            sources[capability] = "persisted";
+            scopes[capability] = "always";
+            expiresAt[capability] = persisted.expiresAt;
+        }
+        else {
+            needsPrompt.push(capability);
+            if (input.expiredKeys?.has(key))
+                expired.push(capability);
+            else if (expected !== undefined &&
+                (sessionBinding !== undefined || persisted !== undefined || input.sessionApprovals.has(key))) {
+                scopeMismatched.push(capability);
+            }
+        }
+    }
+    return { approved, needsPrompt, scopeMismatched, expired, sources, scopes, expiresAt };
+}
+//# sourceMappingURL=approval.js.map

package/dist/kernel/approval.js.map

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

package/dist/kernel/capabilities.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Capability ids: their grammar, and the two authority predicates over them.
+ *
+ * Split out of `delegate.ts` when ADR-0024 pushed that file past the 400-line ceiling and
+ * `test/file-size.test.ts` refused it — for the second time, and answered the same way as the first: split
+ * the file the way the failure message says rather than raise the cap on the guard.
+ *
+ * The seam is not arbitrary. Three modules outside `delegate.ts` already imported these
+ * (`extensions/session.ts` for `DELEGATE_CAPABILITY`, `extensions/delegation.ts` and
+ * `extensions/run-delegation.ts` for `maySpawnDefinition`), which is the evidence that they were a separate
+ * concern living in the wrong file: *what an id means and who may use it* is a different question from
+ * *what one delegation does*.
+ */
+import { type Capability } from "./resolve.ts";
+/** The capability that authorises spawning a definition (ADR-0017). `tool:*` satisfies any of them. */
+export declare const agentCapability: (name: string) => Capability;
+/**
+ * May this grant spawn that definition? (ADR-0017.)
+ *
+ * `resolve()` is exact-match plus subsumption and has no wildcard rule — a wildcard session works only
+ * because `deriveOwnGrant` *enumerates* its observed tools alongside `tool:*`. Definitions are not tools,
+ * so nothing enumerates them, and the wildcard has to be honoured here explicitly. Without that an
+ * UNGOVERNED session would stop being able to spawn, and "governance is opt-in" is the one rule this
+ * package must never break by accident.
+ */
+export declare function maySpawnDefinition(ownGrant: Capability[], name: string): boolean;
+/** The tool name that confers the ability to delegate further. */
+export declare const DELEGATE_CAPABILITY: Capability;
+/**
+ * Every namespace a capability id may carry, as its literal prefix.
+ *
+ * **One list, because there were three and adding a namespace only updated some of them.** ADR-0035 taught
+ * `normaliseCapability` about `workspace:` and left `ceilingForDefinition` (which mangled it into
+ * `tool:workspace:<id>`) and `isSafeCapability` (which called it malformed) behind. The two places that parse
+ * an id's namespace read this, so a fifth namespace is one entry rather than a third divergence.
+ *
+ * **Not every prefix decision in the package.** Inline `startsWith("` tests on a capability namespace are
+ * scattered across `src/` and `extensions/`; this list is read by two of them. **No number is written here,
+ * and the history is why:** SPEC first claimed the list was "what every site reads"; a correction said "six"
+ * while its own enumeration listed seven; this docstring then said "nine" in the sentence claiming it gave no
+ * number; and the correction to *that* said "fourteen", which counted every file containing any
+ * `startsWith("` — CLI flags, `git worktree list` parsing, an assurance sentinel and node_modules entries
+ * among them. Four numbers, four wrong. The command, so nobody has to quote a predecessor:
+ *
+ *     grep -rl 'startsWith("\(tool:\|ext:\|agent:\|skill:\|workspace:\)' src extensions
+ *
+ * Consolidating the sites is a separate change, and a count nobody re-derives is the defect this list exists
+ * to prevent.
+ *
+ * `docs/SPEC.md`'s grammar section is the prose statement of the same list and is kept in step with it.
+ */
+export declare const CAPABILITY_NAMESPACE_PREFIXES: readonly ["tool:", "ext:", "skill:", "agent:", "workspace:"];
+/** Accept `read` or `tool:read` or `ext:pkg/tool` and normalise to a capability id. */
+export declare function normaliseCapability(raw: string): Capability;
+/** The capability that authorises routing a child to one registered workspace (ADR-0035). */
+export declare function workspaceCapability(workspaceId: string): Capability;
+/**
+ * May this session route a child to workspace `id`?
+ *
+ * Mirrors `maySpawnDefinition` deliberately — same shape, same wildcard handling, same reason. Routing was
+ * the one governance dimension that did not attenuate (R-131, measured in
+ * `docs/probes/g36-workspace-attenuation`): the registry inherited into every child and nothing checked the
+ * caller's authority, so a child routed to `staging` could route its grandchild to `prod`.
+ *
+ * `tool:*` satisfies it because governance is opt-in — an ungoverned session holds the wildcard and must
+ * keep working exactly as before.
+ */
+export declare function mayRouteToWorkspace(ownGrant: readonly Capability[], workspaceId: string): boolean;
+/** False when an id would be read as more than one capability by any channel that carries it. */
+export declare function isWellFormedCapability(id: string): boolean;
+/**
+ * The STRICT grammar: a whitelist of what a capability id may look like, not a blocklist of what it may not.
+ *
+ * **Two consumers, and they are two different reasons for the same rule.** It lives here rather than in
+ * either of them because it shipped in one and was needed by both:
+ *
+ *  1. `skill-packages.ts` — the boundary that GENERATES a grant. R-77/R-78: a package declaring
+ *     `allowed-tools: Read,ext:x";touch /tmp/pwned;PI_DADDY_GRANT="` produced a `.pi/grants.env` that ran
+ *     arbitrary code the moment an operator sourced the line `init` prints.
+ *  2. `workspace.ts` — the operator registry, since ADR-0035 made a registry id the tail of a capability id
+ *     (`workspace:<id>`). That made the registry an input to this grammar, and it got the LOOSE
+ *     `isWellFormedCapability` blocklist instead, which review showed costs three things:
+ *     an id of literally `*` loaded and minted `WORKSPACE_WILDCARD`, so an operator naming ONE worktree held
+ *     routing authority over every id in the registry including ones added later;
+ *     an id containing a space became TWO capabilities, because `ceilingForDefinition` splits `allowed-tools`
+ *     on `[\s,]+` — `allowed-tools: read, workspace:prod bash` measured as
+ *     `['tool:bash','tool:read','workspace:prod']`, i.e. routing over production plus a shell, neither typed
+ *     by anyone (0.18.1's comma, one namespace over);
+ *     and quote/`$()`/backtick ids reached the `ROUTABLE WORKSPACES` block of the generated file, whose own
+ *     instructions tell the operator to paste them into `PI_DADDY_GRANT`.
+ *
+ * **A blocklist was the wrong shape for this and the comment on `isWellFormedCapability` says why it is the
+ * right shape THERE**: that one guards the enforcement path, which must keep accepting whatever ids operators
+ * already have. A registry is a file the operator writes and can rename, so refusing a hostile id costs
+ * nothing — and `grant-env.ts`'s standing warning applies to it exactly: *"the third channel — whatever it
+ * turns out to be — should cost a refusal rather than an injection."* The registry was the third channel.
+ */
+/**
+ * A workspace registry id, which is NOT a tool name and needed its own rule.
+ *
+ * `isSafeCapability` was reused here first, and that was the error: it is the grammar for a *tool* name, and
+ * it refused ids that published 0.18.1 accepted — `feature/x` above all. Git worktrees are routinely named
+ * after their branch, so a slash is the ordinary case, and a slash splits nothing: not the comma-separated
+ * grant, not `allowed-tools`' `[\s,]+`. Refusing it bought no safety and broke the common setup.
+ *
+ * What is refused, and why each one earns it:
+ *  - **whitespace** — `ceilingForDefinition` splits `allowed-tools` on `[\s,]+`, so `workspace:prod bash`
+ *    measured as `['tool:bash','tool:read','workspace:prod']`: routing over production plus a shell, neither
+ *    typed by anyone. 0.18.1's comma, one namespace over.
+ *  - **comma, CR, LF, NUL** — split a grant.
+ *  - **`*`** — collides with `WORKSPACE_WILDCARD`, so registering a worktree as `*` and granting
+ *    `workspace:*` believing it named that one root minted routing authority over the whole registry.
+ *  - **quotes, `$`, backticks, `;`, `&`, `|`, `<`, `>`, `(`, `)`, `\`, `#`** — reach the ROUTABLE WORKSPACES
+ *    block of a generated `.pi/grants.env`, whose own instructions tell the operator to paste the id into
+ *    `PI_DADDY_GRANT`. Sourcing the file was safe; following its instructions executed. R-77/R-78.
+ *  - **control characters and non-ASCII** — the generated file is reviewed in an editor and `/grants` prints
+ *    these; backspace and ANSI escapes let one id render as another. This is the one refusal that costs a
+ *    legitimate user something (a non-English worktree name), and it is a deliberate trade recorded as
+ *    breaking rather than asserted to cost nothing.
+ */
+export declare function isSafeWorkspaceId(id: string): boolean;
+export declare function isSafeCapability(id: Capability): boolean;
+/**
+ * The write-side backstop, for every channel that joins capabilities into one string.
+ *
+ * `covered()` already refuses to GRANT a malformed id, so this should be unreachable — which is exactly
+ * why it exists. `grant-env.ts` says it better than I can: "the third channel — whatever it turns out to
+ * be — should cost a refusal rather than an injection. A guard that depends on my enumeration being
+ * complete is not a guard." The propagation channel turned out to be that third channel, and it had no
+ * backstop while the file-writing channel did.
+ *
+ * Loud rather than silently filtered: a malformed id here means something upstream admitted one, and
+ * dropping it quietly would hide the defect that produced it.
+ */
+export declare function assertCapabilitiesArePropagatable(grant: readonly Capability[]): void;
+//# sourceMappingURL=capabilities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/kernel/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAsC,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAInF,uGAAuG;AACvG,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,UAA6B,CAAC;AAE7E;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKhF;AAED,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAE,UAA4B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,6BAA6B,8DAA+D,CAAC;AAE1G,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAI3D;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAEnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAGjG;AAwBD,iGAAiG;AACjG,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,CAcxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAapF"}

package/dist/kernel/capabilities.js

@@ -0,0 +1,199 @@
+/**
+ * Capability ids: their grammar, and the two authority predicates over them.
+ *
+ * Split out of `delegate.ts` when ADR-0024 pushed that file past the 400-line ceiling and
+ * `test/file-size.test.ts` refused it — for the second time, and answered the same way as the first: split
+ * the file the way the failure message says rather than raise the cap on the guard.
+ *
+ * The seam is not arbitrary. Three modules outside `delegate.ts` already imported these
+ * (`extensions/session.ts` for `DELEGATE_CAPABILITY`, `extensions/delegation.ts` and
+ * `extensions/run-delegation.ts` for `maySpawnDefinition`), which is the evidence that they were a separate
+ * concern living in the wrong file: *what an id means and who may use it* is a different question from
+ * *what one delegation does*.
+ */
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD } from "./resolve.js";
+import { WILDCARD } from "./pi-tools.js";
+import { GovernanceRefusal, refusal } from "./refusals.js";
+/** The capability that authorises spawning a definition (ADR-0017). `tool:*` satisfies any of them. */
+export const agentCapability = (name) => `agent:${name}`;
+/**
+ * May this grant spawn that definition? (ADR-0017.)
+ *
+ * `resolve()` is exact-match plus subsumption and has no wildcard rule — a wildcard session works only
+ * because `deriveOwnGrant` *enumerates* its observed tools alongside `tool:*`. Definitions are not tools,
+ * so nothing enumerates them, and the wildcard has to be honoured here explicitly. Without that an
+ * UNGOVERNED session would stop being able to spawn, and "governance is opt-in" is the one rule this
+ * package must never break by accident.
+ */
+export function maySpawnDefinition(ownGrant, name) {
+    // ADR-0023 adds the middle case. `tool:*` is authority to grant every tool and satisfies this too;
+    // `agent:*` is authority to spawn any definition and grants no tools at all, which is the configuration
+    // an operator wanting "any of our definitions, narrow tools" previously had to fake with `tool:*`.
+    return ownGrant.includes(WILDCARD) || ownGrant.includes(AGENT_WILDCARD) || ownGrant.includes(agentCapability(name));
+}
+/** The tool name that confers the ability to delegate further. */
+export const DELEGATE_CAPABILITY = "tool:delegate";
+/**
+ * Every namespace a capability id may carry, as its literal prefix.
+ *
+ * **One list, because there were three and adding a namespace only updated some of them.** ADR-0035 taught
+ * `normaliseCapability` about `workspace:` and left `ceilingForDefinition` (which mangled it into
+ * `tool:workspace:<id>`) and `isSafeCapability` (which called it malformed) behind. The two places that parse
+ * an id's namespace read this, so a fifth namespace is one entry rather than a third divergence.
+ *
+ * **Not every prefix decision in the package.** Inline `startsWith("` tests on a capability namespace are
+ * scattered across `src/` and `extensions/`; this list is read by two of them. **No number is written here,
+ * and the history is why:** SPEC first claimed the list was "what every site reads"; a correction said "six"
+ * while its own enumeration listed seven; this docstring then said "nine" in the sentence claiming it gave no
+ * number; and the correction to *that* said "fourteen", which counted every file containing any
+ * `startsWith("` — CLI flags, `git worktree list` parsing, an assurance sentinel and node_modules entries
+ * among them. Four numbers, four wrong. The command, so nobody has to quote a predecessor:
+ *
+ *     grep -rl 'startsWith("\(tool:\|ext:\|agent:\|skill:\|workspace:\)' src extensions
+ *
+ * Consolidating the sites is a separate change, and a count nobody re-derives is the defect this list exists
+ * to prevent.
+ *
+ * `docs/SPEC.md`'s grammar section is the prose statement of the same list and is kept in step with it.
+ */
+export const CAPABILITY_NAMESPACE_PREFIXES = ["tool:", "ext:", "skill:", "agent:", "workspace:"];
+/** Accept `read` or `tool:read` or `ext:pkg/tool` and normalise to a capability id. */
+export function normaliseCapability(raw) {
+    const value = raw.trim();
+    if (CAPABILITY_NAMESPACE_PREFIXES.some((prefix) => value.startsWith(prefix)))
+        return value;
+    return `tool:${value}`;
+}
+/** The capability that authorises routing a child to one registered workspace (ADR-0035). */
+export function workspaceCapability(workspaceId) {
+    return `workspace:${workspaceId}`;
+}
+/**
+ * May this session route a child to workspace `id`?
+ *
+ * Mirrors `maySpawnDefinition` deliberately — same shape, same wildcard handling, same reason. Routing was
+ * the one governance dimension that did not attenuate (R-131, measured in
+ * `docs/probes/g36-workspace-attenuation`): the registry inherited into every child and nothing checked the
+ * caller's authority, so a child routed to `staging` could route its grandchild to `prod`.
+ *
+ * `tool:*` satisfies it because governance is opt-in — an ungoverned session holds the wildcard and must
+ * keep working exactly as before.
+ */
+export function mayRouteToWorkspace(ownGrant, workspaceId) {
+    const held = new Set(ownGrant);
+    return held.has(WILDCARD) || held.has(WORKSPACE_WILDCARD) || held.has(workspaceCapability(workspaceId));
+}
+/**
+ * Characters that make a capability id mean something OTHER than one capability.
+ *
+ * A capability id is never a list. `PI_DADDY_GRANT` is comma-separated and `parseList` trims and splits
+ * it, so a comma inside a single id means the child reads it as several — including ones nothing granted.
+ * Newlines are here for the same reason one level out: the grant travels through an environment variable
+ * and, via `assertGrantIsWritable`, a shell-sourced file.
+ *
+ * **Measured, on the published 0.18.0.** A root holding `agent:*` (or `tool:*`) that requested
+ * `agent:x,tool:bash` had it admitted by the wildcard's prefix rule, written verbatim into the child's
+ * grant, and split by the child into `agent:x` + `tool:bash` — minting a capability the root never held,
+ * with `denied: []` so nothing recorded an escalation and the ledger line looked clean.
+ *
+ * Deliberately a blocklist of structurally dangerous characters rather than the full grammar whitelist in
+ * `isSafeCapability`. That whitelist is right where it lives — the boundary that GENERATES a grant — but
+ * this is the enforcement path, which must keep accepting whatever ids operators already have. A security
+ * patch to a released version should close the hole without inventing a new way to refuse a legitimate
+ * setup. `grant-env.ts` predicted this channel: "the third channel — whatever it turns out to be — should
+ * cost a refusal rather than an injection."
+ */
+const CAPABILITY_ID_SEPARATORS = /[,\r\n\0]/;
+/** False when an id would be read as more than one capability by any channel that carries it. */
+export function isWellFormedCapability(id) {
+    return id.length > 0 && !CAPABILITY_ID_SEPARATORS.test(id) && id.trim() === id;
+}
+/**
+ * The STRICT grammar: a whitelist of what a capability id may look like, not a blocklist of what it may not.
+ *
+ * **Two consumers, and they are two different reasons for the same rule.** It lives here rather than in
+ * either of them because it shipped in one and was needed by both:
+ *
+ *  1. `skill-packages.ts` — the boundary that GENERATES a grant. R-77/R-78: a package declaring
+ *     `allowed-tools: Read,ext:x";touch /tmp/pwned;PI_DADDY_GRANT="` produced a `.pi/grants.env` that ran
+ *     arbitrary code the moment an operator sourced the line `init` prints.
+ *  2. `workspace.ts` — the operator registry, since ADR-0035 made a registry id the tail of a capability id
+ *     (`workspace:<id>`). That made the registry an input to this grammar, and it got the LOOSE
+ *     `isWellFormedCapability` blocklist instead, which review showed costs three things:
+ *     an id of literally `*` loaded and minted `WORKSPACE_WILDCARD`, so an operator naming ONE worktree held
+ *     routing authority over every id in the registry including ones added later;
+ *     an id containing a space became TWO capabilities, because `ceilingForDefinition` splits `allowed-tools`
+ *     on `[\s,]+` — `allowed-tools: read, workspace:prod bash` measured as
+ *     `['tool:bash','tool:read','workspace:prod']`, i.e. routing over production plus a shell, neither typed
+ *     by anyone (0.18.1's comma, one namespace over);
+ *     and quote/`$()`/backtick ids reached the `ROUTABLE WORKSPACES` block of the generated file, whose own
+ *     instructions tell the operator to paste them into `PI_DADDY_GRANT`.
+ *
+ * **A blocklist was the wrong shape for this and the comment on `isWellFormedCapability` says why it is the
+ * right shape THERE**: that one guards the enforcement path, which must keep accepting whatever ids operators
+ * already have. A registry is a file the operator writes and can rename, so refusing a hostile id costs
+ * nothing — and `grant-env.ts`'s standing warning applies to it exactly: *"the third channel — whatever it
+ * turns out to be — should cost a refusal rather than an injection."* The registry was the third channel.
+ */
+/**
+ * A workspace registry id, which is NOT a tool name and needed its own rule.
+ *
+ * `isSafeCapability` was reused here first, and that was the error: it is the grammar for a *tool* name, and
+ * it refused ids that published 0.18.1 accepted — `feature/x` above all. Git worktrees are routinely named
+ * after their branch, so a slash is the ordinary case, and a slash splits nothing: not the comma-separated
+ * grant, not `allowed-tools`' `[\s,]+`. Refusing it bought no safety and broke the common setup.
+ *
+ * What is refused, and why each one earns it:
+ *  - **whitespace** — `ceilingForDefinition` splits `allowed-tools` on `[\s,]+`, so `workspace:prod bash`
+ *    measured as `['tool:bash','tool:read','workspace:prod']`: routing over production plus a shell, neither
+ *    typed by anyone. 0.18.1's comma, one namespace over.
+ *  - **comma, CR, LF, NUL** — split a grant.
+ *  - **`*`** — collides with `WORKSPACE_WILDCARD`, so registering a worktree as `*` and granting
+ *    `workspace:*` believing it named that one root minted routing authority over the whole registry.
+ *  - **quotes, `$`, backticks, `;`, `&`, `|`, `<`, `>`, `(`, `)`, `\`, `#`** — reach the ROUTABLE WORKSPACES
+ *    block of a generated `.pi/grants.env`, whose own instructions tell the operator to paste the id into
+ *    `PI_DADDY_GRANT`. Sourcing the file was safe; following its instructions executed. R-77/R-78.
+ *  - **control characters and non-ASCII** — the generated file is reviewed in an editor and `/grants` prints
+ *    these; backspace and ANSI escapes let one id render as another. This is the one refusal that costs a
+ *    legitimate user something (a non-English worktree name), and it is a deliberate trade recorded as
+ *    breaking rather than asserted to cost nothing.
+ */
+export function isSafeWorkspaceId(id) {
+    return /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(id);
+}
+export function isSafeCapability(id) {
+    const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
+    // `workspace:` delegates to the WORKSPACE grammar rather than reusing `segment`, and that is the fifth
+    // site of the same defect. `isSafeWorkspaceId` allows a slash because a git worktree is routinely named
+    // after its branch; `segment` does not, so this function refused `workspace:feature/x` — dropping the whole
+    // definition, exiting 1, and telling the operator "a capability id is tool:/skill:/agent:<name> or
+    // ext:<pkg>/<tool>", which does not even mention the namespace. Meanwhile the CHANGELOG told them slashes
+    // are fine. **The boundary that GENERATES grants could not emit the id shape the release advertises**, so
+    // the migration path for a breaking change was closed by the commit that documented it as open.
+    if (id.startsWith("workspace:"))
+        return isSafeWorkspaceId(id.slice("workspace:".length));
+    return (new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
+        new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id));
+}
+/**
+ * The write-side backstop, for every channel that joins capabilities into one string.
+ *
+ * `covered()` already refuses to GRANT a malformed id, so this should be unreachable — which is exactly
+ * why it exists. `grant-env.ts` says it better than I can: "the third channel — whatever it turns out to
+ * be — should cost a refusal rather than an injection. A guard that depends on my enumeration being
+ * complete is not a guard." The propagation channel turned out to be that third channel, and it had no
+ * backstop while the file-writing channel did.
+ *
+ * Loud rather than silently filtered: a malformed id here means something upstream admitted one, and
+ * dropping it quietly would hide the defect that produced it.
+ */
+export function assertCapabilitiesArePropagatable(grant) {
+    const malformed = grant.filter((c) => !isWellFormedCapability(c));
+    if (malformed.length === 0)
+        return;
+    throw new GovernanceRefusal(refusal("GRANT_ID_MALFORMED", `refusing to build a child environment: ${JSON.stringify(malformed)} contain characters that are not ` +
+        `part of a capability id. The grant is comma-separated, so a child would read these as several ` +
+        `capabilities — including ones nothing granted. Report this: a malformed id reached propagation, ` +
+        `which means a guard upstream admitted it.`, { malformed: malformed.join(" ") }));
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/kernel/capabilities.js.map

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