pi-daddy 0.13.0

package/extensions/approvals.ts

@@ -0,0 +1,285 @@
+/**
+ * The human-approval flow: what this session may inherit, republish, and ask a person for.
+ *
+ * Split out of `extensions/grants.ts`. Everything here takes the session as an explicit first argument
+ * rather than closing over module state — the same discipline `grants-command.ts` was extracted under, and
+ * for the same reason: R-28 was a defect in an *argument list*, invisible to 226 pure tests because
+ * nothing tested argument lists. A parameter can be read; a closure has to be reconstructed.
+ *
+ * The session is passed whole, not destructured, because `ownGrant`, `definitions` and `cwd` all change
+ * during a session. Reading them through the object is what keeps this flow looking at the live values
+ * instead of whatever they were when the extension loaded.
+ */
+
+import {
+  approvalKey,
+  expiryFor,
+  resolveApprovals,
+  verifyInherited,
+  type ApprovalPath,
+  type ApprovalScope,
+  type ApprovalSource,
+  type InheritableApproval,
+  type ResolveApprovalsResult,
+  type SubjectSnapshot,
+} from "../src/approval.ts";
+import { loadApprovals, saveApproval } from "../src/approval-store.ts";
+import type { createApprovalGate } from "../src/approval-prompt.ts";
+import { timeoutMsFromEnv, type PromptOutcomeKind } from "../src/approval-prompt.ts";
+import { ceilingForDefinition, digestDefinition } from "../src/definitions.ts";
+import type { Capability } from "../src/resolve.ts";
+import type { GrantsSession } from "./session.ts";
+
+/**
+ * What a subject looks like right now, for the confused-deputy check in the approval store.
+ *
+ * ADR-0010's property is unchanged: an `always` approval is void once the thing it was granted for has
+ * changed. Two things moved. The source is a `SKILL.md`'s `allowed-tools` rather than an agent type's
+ * frontmatter (ADR-0016); and "the thing it was granted for" now includes the **body** as well as the
+ * tools (ADR-0019), because a definition whose instructions were rewritten is not the definition the human
+ * approved. An undeclared definition yields an EMPTY ceiling, not a wildcard, so a stored approval for it
+ * can never be revalidated by accident.
+ *
+ * `<delegate>` — the `tools:` form's subject — resolves to `null` here and always will: it names no file,
+ * so there is nothing to compare against. That is also why that path is never offered `always`.
+ */
+export function snapshotOf(session: GrantsSession, subject: string): SubjectSnapshot | null {
+  const definition = session.definitions.get(subject);
+  if (!definition) return null;
+  return {
+    ceiling: ceilingForDefinition(definition).capabilities,
+    bodySha256: digestDefinition(definition).sha256,
+  };
+}
+
+/**
+ * What this session may republish to children (ADR-0014).
+ *
+ * Two changes from the version that published bare capability names. Each entry keeps its **subject**,
+ * so an approval given for one agent type cannot satisfy another; and each keeps its **scope**, so
+ * `inheritApprovals` can drop `once` rather than handing a whole subtree an approval a human gave for
+ * a single spawn.
+ *
+ * `once` never enters `sessionApprovals` in the first place, so everything here is `session` or
+ * `always` — but the scope is carried rather than assumed, because assuming it is what went wrong.
+ */
+export function republishable(session: GrantsSession): InheritableApproval[] {
+  const fromKey = (key: string) => {
+    const subject = key.slice(key.indexOf("@") + 1);
+    return {
+      capability: key.slice(0, key.indexOf("@")),
+      subject,
+      scope: "session" as const,
+      // ADR-0022: the digest is taken from THIS session's view of the definition, not carried over from
+      // whatever the parent sent. Republishing a stale hash would let a rewritten body travel one more hop
+      // on a pin nobody re-checked, which is the hole this closes rather than moves.
+      bodySha256: snapshotOf(session, subject)?.bodySha256,
+    };
+  };
+  return [
+    // Inherited keys arrive already clamped and already `once`-free from the level above — but NOT already
+    // verified, and republishing an unverified one launders it. `fromKey` stamps this session's current
+    // digest, so a key whose pin no longer matches would go out looking valid and be honoured by a child
+    // that loaded the same current body: the approval was given about a different text and would travel
+    // one hop further on a pin nobody checked. That is ADR-0022's own hole, reappearing inside the fix.
+    ...[...verifyInherited(session.inheritedApprovals, (name) => snapshotOf(session, name))].map(fromKey),
+    ...[...session.sessionApprovals].map(fromKey),
+  ];
+}
+
+export interface ApprovalOutcome {
+  approved: Capability[];
+  /**
+   * How far EACH capability's yes reaches (F1b/F5).
+   *
+   * Was a single `scope`, declared outside the prompt loop and overwritten by the last capability answered.
+   * Approve `tool:bash` *once* and `tool:write` *for this session* and both were re-stamped `session` —
+   * so ADR-0014's rule that "`once` stops at the boundary" was reopened by a mixed answer, and the ledger's
+   * `approvalScope` described one capability while claiming to describe the set.
+   *
+   * Only prompted capabilities appear here. One satisfied from the store or by inheritance is deliberately
+   * absent, so the caller's `?? "once"` keeps it out of what a child inherits — the conservative reading,
+   * and the behaviour that was already in place.
+   */
+  scopes: Record<Capability, ApprovalScope>;
+  /**
+   * Where EACH approved capability's yes came from (R-46).
+   *
+   * Was a single `source`, chosen as `scope ? "prompt" : sources[approved[0]]` — which told the ledger a
+   * human had been asked about capabilities satisfied silently from the store. `resolveApprovals` has
+   * always computed this map; the bug was that it was thrown away.
+   */
+  sources: Record<Capability, ApprovalSource>;
+  humanDenied: boolean;
+  /**
+   * Which of the five prompt outcomes ended the loop, when one did (ADR-0026's F5).
+   *
+   * `humanDenied` is one bit of a five-way discriminant. `no-ui`, `dismissed` and `error` all produced the
+   * same record with only free-text `reason` to separate them, and they call for different responses: a
+   * dismissal is a queue or a longer timeout, `no-ui` is an operator pre-approving, `error` is a defect.
+   */
+  gateOutcome?: PromptOutcomeKind;
+  reason?: string;
+}
+
+/** The slice of pi's `ExtensionContext` this flow needs — a UI to ask through, and how to ask. */
+export interface ApprovalUIContext {
+  ui: Parameters<typeof createApprovalGate>[0]["ui"];
+  hasUI: boolean;
+  mode: string;
+}
+
+/**
+ * The approvals already in hand: inherited, given earlier this session, or persisted from a previous one.
+ *
+ * No dialog, and no I/O beyond reading the store. Extracted (R-38) so that a **read-only preview can run
+ * the same resolution the enforcer runs**. `/grants` used to list each definition from `planDelegation`
+ * alone, which knows nothing about approvals — so a definition whose only gated capability was covered by a
+ * valid persisted approval was listed as `BLOCK  … requires explicit approval` while a real spawn proceeded
+ * with no human in the loop. That is R-28's shape (a diagnostic disagreeing with the enforcer) and it hid a
+ * standing approval from the operator who ran the command to find exactly that.
+ */
+export async function storedApprovals(
+  session: GrantsSession,
+  gated: Capability[],
+  subject: string,
+): Promise<ResolveApprovalsResult> {
+  const { valid } = await loadApprovals({
+    cwd: session.cwd,
+    now: new Date(),
+    snapshotOf: (name) => snapshotOf(session, name),
+  });
+  return resolveApprovals({
+    gated,
+    subject,
+    sessionApprovals: session.sessionApprovals,
+    persisted: valid,
+    // ADR-0022. Verified HERE rather than at parse time because it needs `session.definitions`, which
+    // arrives at `session_start` — after the session object is built.
+    inherited: verifyInherited(session.inheritedApprovals, (name) => snapshotOf(session, name)),
+  });
+}
+
+/**
+ * Satisfy as many gated capabilities as possible, asking a human only for what is left.
+ *
+ * Returns what was approved and how, so the caller can re-resolve with the same pure `resolve()` and
+ * the ledger can record which of the three flavours of "no" applies (see `ledger.ts`'s `GrantRecord`).
+ *
+ * **`ctx: null` means preview**: report what is already in hand and ask nobody. Deliberately not expressed
+ * as `hasUI: false`, which means *"there is nobody here to ask"* — that path replaces the plan's reason with
+ * a message about pre-approving in an interactive session, which is right for a governed child and both
+ * wrong and noisy for a listing that never intended to ask. The two are different facts and are kept
+ * distinguishable.
+ */
+export async function obtainApprovals(
+  session: GrantsSession,
+  gatedBlocked: Capability[],
+  subject: string,
+  path: ApprovalPath,
+  ctx: ApprovalUIContext | null,
+  task?: string,
+  signal?: AbortSignal,
+): Promise<ApprovalOutcome> {
+  const snapshot = (name: string) => snapshotOf(session, name);
+  const pre = await storedApprovals(session, gatedBlocked, subject);
+  if (ctx === null || pre.needsPrompt.length === 0) {
+    return { approved: pre.approved, sources: pre.sources, scopes: {}, humanDenied: false };
+  }
+
+  // The gate PROVIDER lives on the session, not here: `obtainApprovals` runs once per `tool_call` and once
+  // per `delegate.execute`, so a queue built per call would start empty every time and de-duplicate
+  // nothing. Two concurrent delegations would stack two dialogs asking the identical question, which is
+  // precisely what spec §6.1 exists to prevent. Options are per-call; the queue is session-long.
+  const gate = session.approvalGateFor({
+    ui: ctx.ui,
+    hasUI: ctx.hasUI,
+    mode: ctx.mode,
+    timeoutMs: timeoutMsFromEnv(process.env.PI_GRANTS_APPROVAL_TIMEOUT),
+  });
+
+  const approved = [...pre.approved];
+  // Seeded with what the store already answered, then one entry added per capability a human is asked
+  // about — so a mixed set reports exactly which yes came from where.
+  const sources: Record<Capability, ApprovalSource> = { ...pre.sources };
+  const scopes: Record<Capability, ApprovalScope> = {};
+  let humanDenied = false;
+  let gateOutcome: PromptOutcomeKind | undefined;
+  let reason: string | undefined;
+
+  for (const capability of pre.needsPrompt) {
+    const outcome = await gate.request({ capability, subject, path, task, signal });
+    if (outcome.scope === null) {
+      // Forward the gate's own discriminant rather than re-deriving it from `hasUI`: `hasUI` is true in
+      // RPC mode too, so an automated client's timeout or dismissal there would misreport as "a human
+      // declined" if we asked `ctx.hasUI` instead. Only `kind === "declined"` means a person said no.
+      humanDenied = outcome.kind === "declined";
+      // The full discriminant, not just the one bit of it that had a field. `no-ui`, `dismissed` and
+      // `error` used to produce records identical to each other, separated only by free-text `reason` —
+      // so "was there an operator who timed out, or was there nobody?" had no answer, and the two want
+      // different fixes. It was computed here all along and thrown away.
+      gateOutcome = outcome.kind;
+      reason = outcome.reason;
+      break;
+    }
+    approved.push(capability);
+    // R-66: `prompt` means A HUMAN SAW A DIALOG FOR THIS. A caller that joined another's in-flight answer
+    // did not, so it records the source it actually had — the session approval that answer created. Eight
+    // concurrent children under one *Allow for this session* used to write eight lines each claiming a
+    // prompt. Same repair as R-46, one level up: stop asserting a human was asked on a path where they
+    // were not.
+    sources[capability] = outcome.joined ? "session" : "prompt";
+    scopes[capability] = outcome.scope;
+
+    if (outcome.scope === "session" || outcome.scope === "always") {
+      session.sessionApprovals.add(approvalKey(capability, subject));
+    }
+    if (outcome.scope === "always") {
+      const now = new Date();
+      const current = snapshot(subject);
+      // No readable ceiling means the entry would carry `grantAtApproval: []`, which `entryVerdict`
+      // compares against the type's ceiling on every load — so it could only ever come back
+      // "type-missing" or "type-changed". Writing it is not unsafe (it fails closed), it is simply a
+      // dead entry that silently accumulates in the file. Skip it and say so, taking the same
+      // downgrade-to-session path as a failed write below: the human's yes still stands.
+      const written =
+        current === null
+          ? false
+          : await saveApproval(
+              session.cwd,
+              approvalKey(capability, subject),
+              {
+                approvedAt: now.toISOString(),
+                expiresAt: expiryFor(now),
+                cwd: session.cwd,
+                grantAtApproval: current.ceiling,
+                // ADR-0019: the tools AND the instructions the human actually saw. Pinning only the
+                // former would let a rewritten body inherit a yes that was given about different text.
+                bodyAtApproval: current.bodySha256,
+                // The TASK is deliberately absent (ADR-0021). It is shown in the dialog, where a human
+                // needs it, and never written down, because the model assembles it from the parent's
+                // context and it can carry anything the parent could see.
+              },
+              snapshot,
+              now,
+            );
+      if (!written) {
+        // The human already said yes; the security decision stands. Only the convenience cache
+        // failed, so this downgrades scope rather than refusing the delegation (see approval-store.ts).
+        ctx.ui.notify(
+          current === null
+            ? `grants: cannot persist the approval for ${capability} — no definition named ${subject} is ` +
+                `readable here, so a stored entry could never be valid; it applies for this session only`
+            : `grants: could not persist the approval for ${capability} — it applies for this session only`,
+          "warning",
+        );
+        // The human's yes stands; only the cache failed. Downgrade THIS capability, not the set — under
+        // the old scalar this also rewrote the scope of every other capability answered in the same call.
+        scopes[capability] = "session";
+      }
+    }
+    session.publishChildEnv(); // a new session approval widens what children may inherit — republish now
+  }
+
+  return { approved, sources, scopes, humanDenied, gateOutcome, reason };
+}

package/extensions/delegation.ts

@@ -0,0 +1,237 @@
+/**
+ * Governed delegation, as pi sees it: the `delegate` and `delegate_all` tool registrations.
+ *
+ * Unlike the tripwire in `grants.ts` this PROVISIONS — the grant is an argument, so the orchestrator hands
+ * each child exactly the capabilities it should have. Both tools are registered only when this session may
+ * delegate, so withholding `tool:delegate` genuinely makes a session a leaf (S-5).
+ *
+ * What a delegation actually DOES lives in `./run-delegation.ts`; this file is the pi-facing surface —
+ * schemas, descriptions, and turning an outcome into the throw-or-return contract pi expects.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { maySpawnDefinition } from "../src/delegate.ts";
+import { MAX_CHILDREN_PER_CALL, childSpawnId, splitBudget } from "../src/fanout.ts";
+import { runOneDelegation } from "./run-delegation.ts";
+import { type GrantsSession } from "./session.ts";
+
+export interface DelegationRegistration {
+  /**
+   * Re-derive "which definitions may this session spawn?" into the registered tool schemas.
+   *
+   * Must be called once the session knows the answer — `session_start` loads the definitions, and the first
+   * provider request tightens `ownGrant`. Both change the list, and neither has happened when the tools are
+   * registered. See R-39: without this the answer is permanently `none`.
+   */
+  refreshSpawnable: () => void;
+}
+
+
+/**
+ * Register `delegate` and `delegate_all` — but only if this session may delegate.
+ *
+ * The conditional is the whole of S-5: an unconditionally-registered `delegate` appears in every child's
+ * ceiling, so a delegator without it was told every single agent type "requires tool:delegate".
+ */
+export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession): DelegationRegistration {
+  if (!session.mayDelegate) return { refreshSpawnable: () => {} };
+
+  /**
+   * Definitions this session is actually authorised to spawn (ADR-0017), for the tool description.
+   *
+   * Listing all of them would tell the model it can spawn things every attempt at which is refused — the
+   * R-28 shape again, a description disagreeing with the enforcer. Computed from the same
+   * `maySpawnDefinition` the planner uses.
+   */
+  const spawnable = () =>
+    [...session.definitions.keys()].filter((name) => maySpawnDefinition(session.ownGrant, name)).sort();
+
+  /**
+   * **R-39.** This used to be computed once, right here, and it was always `[]`.
+   *
+   * `registerDelegationTools` is called synchronously from the extension factory, while
+   * `session.definitions` is only populated in the `session_start` hook — which fires afterwards. So every
+   * model in every governed session was told `Available: none.` and did the reasonable thing: it used
+   * `delegate({tools})`, the path with no operator-authored instructions, no `agent:` prerequisite, no body
+   * digest on the record, and no `always` approval available. **ADR-0017 and ADR-0019 bought expressiveness
+   * the model was structurally prevented from using**, and every dialog was a `<delegate>` dialog again.
+   *
+   * The comment this replaces reasoned carefully about grant staleness and never noticed the map was empty.
+   *
+   * The repair rests on a measured fact: **pi serialises a tool's schema at request time, not at
+   * registration**, so mutating the description after the definitions load reaches the provider. Verified
+   * directly — a probe that rewrote a parameter description in `session_start` saw the new text arrive in
+   * `before_provider_request`'s payload.
+   */
+  const describeAgent = (names: string[]) =>
+    `Name of a definition to spawn — its allowed-tools become the grant and its instructions ` +
+    `become the sub-agent's system prompt. Available: ${names.join(", ") || "none"}.`;
+
+  const childShape = Type.Object({
+    task: Type.String({ description: "The task for this sub-agent. It receives only this." }),
+    agent: Type.Optional(Type.String({ description: describeAgent(spawnable()) })),
+    tools: Type.Optional(Type.Array(Type.String(), { description: "Capabilities, when no 'agent' fits." })),
+    model: Type.Optional(Type.String({ description: "Model as provider/id. Defaults to this session's." })),
+  });
+
+  const delegateAllParams = Type.Object({
+    children: Type.Array(childShape, {
+      minItems: 1,
+      maxItems: MAX_CHILDREN_PER_CALL,
+      description: "The sub-agents to run concurrently. Each is independent and unaware of the others.",
+    }),
+  });
+
+  const delegateParams = Type.Object({
+      task: Type.String({ description: "The task for the sub-agent. It receives only this." }),
+      agent: Type.Optional(Type.String({ description: describeAgent(spawnable()) })),
+      tools: Type.Optional(
+        Type.Array(Type.String(), {
+          description:
+            "Capabilities to grant when no 'agent' is named, e.g. [\"read\",\"grep\"] or " +
+            "[\"tool:read\",\"ext:pkg/tool\"]. Empty means no tools. Ignored when 'agent' is given.",
+        }),
+      ),
+      model: Type.Optional(
+        Type.String({
+          // A bare id resolves across all known providers and can land on one there is no key for, so the
+          // form is named rather than implied — see the "Verified live" defect in the README.
+          description:
+            "Model for the sub-agent as provider/id, e.g. \"openai-codex/gpt-5.6-sol\". " +
+            "Defaults to this session's model, already provider-qualified.",
+        }),
+      ),
+  });
+
+  pi.registerTool({
+    name: "delegate",
+    label: "Delegate (governed)",
+    description:
+      "Delegate a task to a sub-agent holding ONLY the capabilities you grant it. You cannot grant what " +
+      "you do not hold. Prefer 'agent' — it spawns a definition whose capabilities and instructions were " +
+      "written by the operator. Use 'tools' only when no definition fits. Grant 'delegate' if the " +
+      "sub-agent must itself delegate further; withhold it to make the sub-agent a leaf.",
+    parameters: delegateParams,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const outcome = await runOneDelegation(
+        session,
+        { task: params.task, agent: params.agent, tools: params.tools, model: params.model },
+        { parentId: session.ownSpawnId, childId: childSpawnId(session.ownSpawnId, 0) },
+        // A single blocking delegation spends nothing from the subtree budget: cardinality is already
+        // bounded to one by the call being blocking, which is the accident fan-out removes. Passing the
+        // budget through unchanged means a child can still fan out with what this session was given.
+        session.fanoutBudget,
+        ctx,
+        signal,
+      );
+
+      if (!outcome.ok) {
+        // THROW, do not return. `AgentToolResult` has no `isError` field: pi sets it only when `execute`
+        // throws (`pi-agent-core/dist/agent-loop.js` — a normal return is hardcoded `isError: false`).
+        // Returning `isError: true` was silently discarded, so every refusal this package made was
+        // recorded by pi as a SUCCESSFUL tool call. Found by the integration suite on its first run.
+        const detail = outcome.text ? `\n\n${outcome.text}` : "";
+        throw new Error(`delegation refused: ${outcome.reason}${detail}`);
+      }
+
+      return {
+        content: [{ type: "text", text: outcome.text || "(no output)" }],
+        details: { granted: outcome.granted, depth: outcome.depth, exitCode: outcome.exitCode },
+      };
+    },
+  });
+
+  /**
+   * Bounded SYNCHRONOUS fan-out — ADR-0015's option A′.
+   *
+   * One call spawns several governed children concurrently and returns when the last one finishes. There is
+   * deliberately no background mode, no result-by-id and no child registry, and that scoping is the whole
+   * design: **fan-out and background are separable, fan-out carries most of the value, and background
+   * carries nearly all of the state-machine holes.** Because the turn still owns the children, the parent
+   * cannot exit before them, the tool-call signal is still live, the timeout still outlives every child,
+   * results are returned rather than stored, and there are no ids to dangle across a compaction.
+   *
+   * Every child goes through `runOneDelegation`, so each one is planned, gated, audited and bounded by
+   * exactly the same rules as a single `delegate`. What fan-out adds is a **cardinality bound** (the
+   * budget) and **sibling identity** (F8) — the two things ADR-0008 never had, because a blocking
+   * `delegate` bounded cardinality to one by accident.
+   */
+  pi.registerTool({
+    name: "delegate_all",
+    label: "Delegate to several sub-agents (governed, parallel)",
+    description:
+      "Run several sub-agents CONCURRENTLY and return all their results. Each child is governed exactly " +
+      "as with `delegate`: it holds only what you grant it, and you cannot grant what you do not hold. " +
+      `At most ${MAX_CHILDREN_PER_CALL} children per call, and a session-wide budget bounds the total ` +
+      "across the whole delegation subtree. Children cannot see each other or share context. Use this " +
+      "when independent tasks can proceed in parallel — several reviewers over one diff, say — and read " +
+      "every child's outcome, because one can be refused while the others succeed.",
+    parameters: delegateAllParams,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const children = params.children ?? [];
+      const split = splitBudget(session.fanoutBudget, children.length);
+      if (!split.ok) {
+        // Thrown, not returned: a returned `isError` is discarded by pi, so a refusal that came back as a
+        // normal result would read to the orchestrator as a successful fan-out of zero children.
+        throw new Error(`fan-out refused: ${split.reason}`);
+      }
+
+      // Concurrent by construction. Each child gets its own budget share and its own ledger id, so the
+      // records form a tree and two siblings can never be confused for one another.
+      const outcomes = await Promise.all(
+        children.map((child, index) =>
+          runOneDelegation(
+            session,
+            child,
+            { parentId: session.ownSpawnId, childId: childSpawnId(session.ownSpawnId, index) },
+            split.perChild,
+            ctx,
+            signal,
+          ),
+        ),
+      );
+
+      const failed = outcomes.filter((o) => !o.ok);
+      // Every child is reported, including the ones that failed. R-03's rule: a missing result must never
+      // be indistinguishable from an empty one, and a fan-out that hid its refusals would let an
+      // orchestrator summarise four reviews when only three happened.
+      const report = outcomes
+        .map((outcome, index) => {
+          const label = `### child ${index + 1}${children[index].agent ? ` (${children[index].agent})` : ""}`;
+          return outcome.ok
+            ? `${label} — completed\n\n${outcome.text || "(no output)"}`
+            : `${label} — FAILED: ${outcome.reason}${outcome.text ? `\n\n${outcome.text}` : ""}`;
+        })
+        .join("\n\n---\n\n");
+
+      if (failed.length === children.length) {
+        // All of them failed, so there is no partial result to hand back — and a tool that returns text
+        // when nothing ran is exactly how a wrong summary gets written.
+        throw new Error(`fan-out failed: every child was refused or failed.\n\n${report}`);
+      }
+
+      return {
+        content: [{ type: "text", text: report }],
+        details: {
+          children: outcomes.length,
+          failed: failed.length,
+          budgetPerChild: split.perChild,
+          granted: outcomes.map((o) => o.granted),
+        },
+      };
+    },
+  });
+
+  return {
+    // Written through the CONSTRUCTED schema (`properties.agent`) rather than the object handed to
+    // `Type.Optional`, because `Optional` shallow-copies — mutating the input would update a discarded
+    // clone. Both tools are refreshed from one place so they cannot disagree about what is spawnable.
+    refreshSpawnable: () => {
+      const names = spawnable();
+      const description = describeAgent(names);
+      (delegateParams.properties.agent as { description?: string }).description = description;
+      (childShape.properties.agent as { description?: string }).description = description;
+    },
+  };
+}