pi-daddy 0.13.0 → 0.15.0

package/extensions/init-command.ts

@@ -0,0 +1,132 @@
+/**
+ * `/grants init` — the one command in this package that writes.
+ *
+ * Split out of `extensions/grants.ts` when the file-size guard refused it, and the seam is the right one:
+ * `grants.ts` is wiring, and this is a decision procedure that asks a human questions and stores the
+ * answer. Keeping it here means the file that registers hooks stays readable, which is the property the
+ * guard exists to defend — every wiring bug this package has had lived in that file.
+ */
+
+import { discoverSkillPackages } from "../src/skill-packages.ts";
+import { applyInit, planInit } from "../src/init.ts";
+import { saveGrant, grantStorePath } from "../src/grant-store.ts";
+import { expandSubsumed, SUBSUMPTION, type Capability } from "../src/resolve.ts";
+import type { GrantsSession } from "./session.ts";
+
+/**
+ * `/grants init` — scaffold, ask about what is withheld, store it outside the workspace, apply it now.
+ *
+ * **The dialog covers the withheld capabilities and nothing else** (ADR-0030). Asking about all of them
+ * would be a dozen questions for a first run, and this project has a name for what that produces: R-25,
+ * where the operator learns to click through and the control becomes decorative. The read-only capabilities
+ * a skill declares are already bounded by the ceiling its author wrote and by pi's `--tools`; the ones that
+ * can change the machine are the decision, so they are the question.
+ *
+ * A refusal is not a failure. Answering *no* to `tool:bash` leaves four definitions unspawnable and says so
+ * — that is the same outcome `pi-daddy init` writes by default, reached deliberately rather than by
+ * omission.
+ */
+export async function runInit(
+  session: GrantsSession,
+  ctx: any,
+  /**
+   * Reload definitions and the catalog, and re-describe the delegation tools.
+   *
+   * **Without this the grant goes live and the definitions do not** — `session.definitions` and the catalog
+   * are read at `session_start`, which is before `init` wrote a single file, so a session would hold
+   * `agent:review` while believing no definition of that name exists. `/grants` showed `0 skill,
+   * 0 agent-type` and no verdicts, and the model would have been told `Available: none` — R-39 exactly,
+   * reintroduced by a feature whose whole selling point is "no restart". Found by running it.
+   */
+  refresh: () => Promise<void>,
+): Promise<void> {
+  const packages = await discoverSkillPackages(ctx.cwd);
+  if (packages.length === 0) {
+    ctx.ui.notify(
+      "grants: no packages declaring skills found in node_modules. Install one — e.g. " +
+        "`npm i principal-pi-skills` — then run /grants init again.",
+      "warning",
+    );
+    return;
+  }
+
+  const plan = planInit(packages, ctx.cwd);
+  const outcome = await applyInit(plan);
+  const lines = [
+    `grants: ${plan.skills.length} definition(s) from ${packages.map((p) => `${p.name}@${p.version}`).join(", ")}`,
+    `  wrote ${outcome.written.length}, kept ${outcome.kept.length} already present` +
+      `${outcome.failed.length > 0 ? `, ${outcome.failed.length} FAILED` : ""}`,
+  ];
+  for (const f of outcome.failed) lines.push(`    ${f.path}: ${f.error}`);
+
+  // The grant `init` would have written to `.pi/grants.env`: read-only, nothing that can change the
+  // machine. Everything below is added to it only by an explicit yes.
+  const grant = new Set<Capability>(plan.grant);
+  const granted: string[] = [];
+  const declined: string[] = [];
+  /** Withheld capabilities a previous *yes* already conferred, so no question was asked about them. */
+  const alreadyConferred: string[] = [];
+
+  for (const [capability, neededBy] of plan.withheldCapabilities) {
+    // **Do not ask a question whose answer cannot matter.** `tool:bash` subsumes `write`, `edit` and
+    // `edit-diff` (`SUBSUMPTION`, `src/resolve.ts`), so once bash is granted those are already conferred.
+    // The first version asked anyway: an operator could answer *no* to `tool:write`, watch `/grants` allow
+    // `build` with `tool:write`, and reasonably conclude the dialog was decorative. It was — that is R-47's
+    // shape, a control that appears to do something and does not, inside a control built to prevent it.
+    //
+    // Reported rather than silently skipped, because "you already granted this" is the useful sentence and
+    // silence is what made it confusing.
+    if (expandSubsumed([...grant]).includes(capability)) {
+      alreadyConferred.push(`${capability} (via ${subsumedBy([...grant], capability) ?? "a granted capability"})`);
+      for (const name of neededBy) grant.add(`agent:${name}` as Capability);
+      continue;
+    }
+    const answer = await ctx.ui.select(
+      `grants: grant ${capability} to sub-agents?\n  needed by: ${neededBy.join(", ")}\n` +
+        `  this can change your machine — ${capability === "tool:bash" ? "and bash also confers write and edit" : "it is not gated, so no dialog at spawn time"}`,
+      ["No", "Yes"],
+    );
+    if (answer === "Yes") {
+      grant.add(capability);
+      granted.push(capability);
+      // The `agent:` ids too: a definition authorised but unable to receive what it declares would be
+      // allowed to run and then refused, which is a worse answer than not being authorised (ADR-0029).
+      for (const name of neededBy) grant.add(`agent:${name}` as Capability);
+    } else {
+      declined.push(`${capability} (${neededBy.join(", ")})`);
+    }
+  }
+
+  const finalGrant = [...grant].sort();
+  const saved = await saveGrant(ctx.cwd, finalGrant);
+  if (saved !== "saved") {
+    lines.push(
+      `  NOT STORED — ${saved === "busy" ? "another session holds the grant store" : "the store could not be written"}. ` +
+        `Nothing was changed; this session's grant is unchanged. Retry, or export PI_GRANTS_GRANT yourself.`,
+    );
+    ctx.ui.notify(lines.join("\n"), "error");
+    return;
+  }
+
+  // Live, without a restart — the whole point of the store. Only after a successful write, so what runs and
+  // what is recorded cannot disagree.
+  session.adoptGrant(finalGrant);
+  // Order matters: the grant first, then the reload, because `refreshSpawnable` filters the definitions it
+  // advertises through `maySpawnDefinition` against the grant the session now holds.
+  await refresh();
+
+  lines.push(`  stored at ${grantStorePath(ctx.cwd)} — outside this project, so no child can rewrite it`);
+  if (granted.length > 0) lines.push(`  GRANTED: ${granted.join(", ")}`);
+  if (alreadyConferred.length > 0) {
+    lines.push(`  ALREADY CONFERRED, not asked about: ${alreadyConferred.join(", ")}`);
+  }
+  if (declined.length > 0) lines.push(`  withheld: ${declined.join("; ")}`);
+  lines.push(`  live now (${finalGrant.length} capabilities) — no restart. /grants shows the verdicts.`);
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+/** Which held capability confers `capability`, for a message that names the cause rather than the effect. */
+function subsumedBy(held: Capability[], capability: Capability): Capability | null {
+  for (const h of held) if ((SUBSUMPTION[h] ?? []).includes(capability)) return h;
+  return null;
+}

package/extensions/session.ts

@@ -37,6 +37,9 @@ import {
   parseList,
 } from "../src/propagation.ts";
 import type { Capability } from "../src/resolve.ts";
+import { loadDefinitions } from "../src/definitions.ts";
+import { buildCatalog } from "../src/catalog.ts";
+import { loadGrantSync, grantStorePath } from "../src/grant-store.ts";
 import { republishable } from "./approvals.ts";
 
 /**
@@ -54,8 +57,17 @@ export const ENV_HERDR_WORKSPACE = "PI_GRANTS_HERDR_WORKSPACE";
 export const ENV_HERDR_KEEP_PANE = "PI_GRANTS_HERDR_KEEP_PANE";
 
 export interface GrantsSession {
-  /** False when `PI_GRANTS_GRANT` is unset: the session holds the wildcard and nothing is governed. */
-  readonly governed: boolean;
+  /**
+   * False when neither `PI_GRANTS_GRANT` nor a stored grant applies: the session holds the wildcard and
+   * nothing is governed.
+   *
+   * **Mutable, because `/grants init` makes an ungoverned session governed mid-run.** The first version of
+   * ADR-0030 left this readonly on the reasoning that a store is read at creation and `init` only runs where
+   * one exists — which is false for the first `init` in a directory, the most common case there is. The
+   * session then bounded every spawn by the new grant while `/grants` reported "inactive", so the status
+   * line contradicted the enforcer. Found by running it.
+   */
+  governed: boolean;
   /** The upper bound handed down by the delegator, before this session's own tools are observed. */
   readonly inherited: Capability[];
   readonly depth: number;
@@ -129,6 +141,23 @@ export interface GrantsSession {
    * prompted the human. A value scoped to one specific child is never written to this global channel.
    */
   publishChildEnv(): void;
+  /**
+   * The directory whose stored grant this session read, or would read. `process.cwd()` — see the note in
+   * `createGrantsSession` for why the factory cannot use `ctx.cwd`.
+   */
+  readonly storeCwd: string;
+  /**
+   * Adopt a grant decided DURING the session — `/grants init` answering a human — without a restart.
+   *
+   * Narrow by design: it sets the session's own grant and republishes, so the very next spawn is bounded by
+   * it. It does **not** reach children that already exist; those are separate processes whose environment
+   * was fixed when they started, and reaching into them is neither possible nor desirable — a child's
+   * ceiling should not move under it mid-run.
+   *
+   * Only a human can reach this. Slash commands are user-invoked; no tool exposes it, so a model cannot
+   * widen its own session's ceiling by calling something.
+   */
+  adoptGrant(grant: Capability[]): void;
 }
 
 /**
@@ -138,12 +167,40 @@ export interface GrantsSession {
  * extension**, so a child granted `tool:delegate` can be started with `-e <that file>`. `grants.ts` is that
  * file, and only `grants.ts` can say so about itself.
  */
+/**
+ * Load this project's definitions and capability catalog into the session.
+ *
+ * **One loader, two callers.** `session_start` runs it, and so does `/grants init` — which writes the very
+ * files it reads, so a session that skipped this held `agent:review` while believing no definition of that
+ * name existed, and the model was told `Available: none` (R-39's shape, reintroduced by the feature whose
+ * selling point is "no restart"). Two copies of these three steps is how the two callers come to disagree
+ * about what loading means, so there is one.
+ */
+export async function loadProjectDefinitions(session: GrantsSession, cwd: string): Promise<void> {
+  session.definitions = await loadDefinitions(cwd);
+  session.catalogReady = buildCatalog({ cwd, observedTools: session.observedTools });
+  session.catalog = await session.catalogReady;
+}
+
 export function createGrantsSession(extensionPath: string | undefined): GrantsSession {
-  // Governance is opt-in: with PI_GRANTS_GRANT unset the session holds the wildcard and nothing is
-  // blocked. This extension must never silently tighten a normal workflow.
+  // Governance is opt-in: with PI_GRANTS_GRANT unset AND no stored grant for this directory, the session
+  // holds the wildcard and nothing is blocked. This extension must never silently tighten a normal
+  // workflow.
+  //
+  // **Two sources, and the environment always wins** (ADR-0030). The variable is how a CHILD is governed
+  // and how CI is configured, so a store that could override it would let a directory quietly widen or
+  // narrow a child its parent had already bounded. The store is consulted only when the variable is absent,
+  // which is exactly the case it was added for: a human at a terminal who ran `/grants init` here.
+  //
+  // `process.cwd()` rather than `ctx.cwd`, because this runs in the extension factory — before any hook,
+  // and therefore before `ctx` exists. That ordering is forced by S-5: whether `delegate` is registered at
+  // all is decided here, and a grant arriving later could not inform it. `session_start` re-checks the two
+  // against each other and says so if they differ, which is the only case this can get wrong.
   const grantRaw = process.env[ENV_GRANT];
-  const governed = grantRaw !== undefined;
-  const inherited: Capability[] = governed ? parseList(grantRaw) : [WILDCARD];
+  const storeCwd = process.cwd();
+  const stored = grantRaw === undefined ? loadGrantSync(storeCwd) : null;
+  const governed = grantRaw !== undefined || stored !== null;
+  const inherited: Capability[] = grantRaw !== undefined ? parseList(grantRaw) : (stored ?? [WILDCARD]);
   // G7 / A-S4 + B-I4: strict, three-way parsing that fails CLOSED. A malformed bound used to yield
   // `NaN`, and every comparison against `NaN` is false, so depth limiting switched itself off.
   const bounds = depthConfig(process.env[ENV_DEPTH], process.env[ENV_MAX_DEPTH]);
@@ -214,6 +271,18 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
       ...(approved ? { approved } : {}),
     }),
 
+    storeCwd,
+
+    adoptGrant: (grant: Capability[]) => {
+      // Governed too, not just bounded. A session that starts with no grant and then runs `/grants init` is
+      // governed from that moment: every spawn is bounded by what was just stored. Leaving this false made
+      // `/grants` print "inactive" while holding thirteen capabilities — a status line contradicting the
+      // enforcer, which is the defect R-28 is named for.
+      session.governed = true;
+      session.ownGrant = grant;
+      session.publishChildEnv();
+    },
+
     publishChildEnv: () => {
       const env = childEnv({
         ownGrant: session.ownGrant,

package/extensions/spawn-summary.ts

@@ -0,0 +1,214 @@
+/**
+ * "What can this session actually spawn?" — answered at session start, out loud (B1, P4).
+ *
+ * The startup line reported the *grant* and nothing else: `holding [agent:review, tool:read, …]`. An
+ * operator who has just installed a package of `SKILL.md` definitions cannot tell from that whether the
+ * install worked, whether their grant names the right ids, or whether anything at all is spawnable — and
+ * the failure they are most likely to be in (a definition declaring no `allowed-tools`, so it is discovered
+ * and refused) looks exactly like the success. **The withheld half is the important half**: it is the
+ * difference between "governance is working" and "did the install fail?".
+ *
+ * **Decided by the real planner, and — since a reviewer caught it — no longer re-classified afterwards.**
+ * The first version read two fields of `plan.result` and invented a category from them, which is the very
+ * thing this header claimed to have made inexpressible: `planDelegation` has six refusals that leave both
+ * fields empty, so a session at its depth limit, or one with a malformed `PI_GRANTS_MAX_DEPTH`, was told its
+ * **files** were written wrong while `/grants` in the same session said "delegation is disabled (maxDepth
+ * 0)". That is R-28's shape inside the fix for R-28's shape. The planner's own `reason` is now printed for
+ * anything the two designated signals do not explain.
+ *
+ * **What this does not establish.** It runs at `session_start`, before the first provider request, so the
+ * grant it classifies against is the one *inherited*; `deriveOwnGrant` narrows it to the observed tool
+ * surface only when a request is made, and a definition counted spawnable here can be refused afterwards if
+ * its ceiling names a tool this session turns out not to have (R-75, measured live). It is an upper bound,
+ * and `/grants` run after any request is the settled answer.
+ */
+
+import type { SkillDefinition } from "../src/definitions.ts";
+import type { GatedPlan } from "./run-delegation.ts";
+
+/** Why a definition is not spawnable right now. Three causes, three different fixes. */
+export type WithheldReason =
+  /** The grant lacks `agent:<name>`, or lacks a tool the ceiling declares. Fix: widen `PI_GRANTS_GRANT`. */
+  | "capability"
+  /** Everything is held, but a gated capability needs a human yes first. Fix: spawn it and answer. */
+  | "approval"
+  /** Anything else the planner refused — the file, an unknown capability, an unresolvable skill. */
+  | "declaration";
+
+export interface WithheldDefinition {
+  name: string;
+  reason: WithheldReason;
+  /** The capabilities that caused it, when the planner named any. */
+  missing: string[];
+  /** The planner's own words, used verbatim when the two designated signals do not explain the refusal. */
+  reasonText?: string;
+}
+
+export interface SpawnableSummary {
+  spawnable: string[];
+  withheld: WithheldDefinition[];
+  /**
+   * Set when NOTHING can be spawned for a reason about the SESSION rather than about any definition — no
+   * `tool:delegate`, or a depth bound that forbids spawning. Per-definition work is skipped entirely.
+   */
+  sessionBlocked?: string;
+  /** Definitions beyond `PREVIEW_LIMIT`, counted but not classified. Stated, never silently dropped. */
+  notChecked: number;
+}
+
+/** Names listed per clause before the rest are counted instead. Whatever is dropped is stated (R-48). */
+const NAMES_SHOWN = 8;
+
+/**
+ * How many definitions the startup line classifies.
+ *
+ * `/grants` has had the same cap from the start, with the comment *"Each one runs the real planner, so this
+ * bounds work, not truth"*; this path removed it and put the work on the blocking `session_start` hook.
+ * Measured by a reviewer: 1000 definitions against 1000 stored approvals cost **1.66s at every session
+ * start**, because a gate-blocked definition re-reads and re-verifies the whole approvals file. 50
+ * definitions cost 7ms, which is the real world — but a bound that only holds for the real world is not a
+ * bound, and this one is paid by every governed child too, including `--print` children that discard the
+ * output.
+ */
+const PREVIEW_LIMIT = 24;
+
+export interface SessionFacts {
+  /** False when the grant omits `tool:delegate`: no `delegate` tool is registered at all (S-5). */
+  mayDelegate: boolean;
+  depth: number;
+  maxDepth: number;
+}
+
+/**
+ * Classify every discovered definition by running the real planner over it.
+ *
+ * `preview` is `planWithApprovals(session, {agent: name, …}, {}, null)` — the enforcing path minus the one
+ * thing a startup line must not do, which is ask a human. Stored approvals count exactly as they would for
+ * a spawn, so a definition covered by a standing 30-day yes is reported spawnable, which is what it is.
+ */
+export async function summariseSpawnable(
+  definitions: Map<string, SkillDefinition>,
+  preview: (name: string) => Promise<GatedPlan>,
+  session: SessionFacts,
+): Promise<SpawnableSummary> {
+  const names = [...definitions.keys()].sort();
+
+  // Two session-level facts make every per-definition verdict identical and misleading, so they are
+  // answered before any planning happens. Previewing N definitions to print N copies of one environment
+  // problem is both wrong and wasteful.
+  //
+  // `mayDelegate` is the one a reviewer caught: `registerDelegationTools` returns early without it, so the
+  // session has NO `delegate` tool and can spawn nothing — while this line said `1 of 3 spawnable`. That is
+  // the exact question the line exists to answer, answered wrong in the one configuration where nothing can
+  // ever run. Not R-75: no later event changes it, and it is wrong from the first millisecond.
+  if (!session.mayDelegate) {
+    return {
+      spawnable: [],
+      withheld: [],
+      notChecked: 0,
+      sessionBlocked:
+        `this session holds no tool:delegate, so it has no delegate tool at all — nothing can be spawned, ` +
+        `whatever any definition declares. Add tool:delegate to PI_GRANTS_GRANT to make this session a ` +
+        `delegator rather than a leaf.`,
+    };
+  }
+  if (session.maxDepth <= 0 || session.depth + 1 > session.maxDepth) {
+    return {
+      spawnable: [],
+      withheld: [],
+      notChecked: 0,
+      sessionBlocked:
+        session.maxDepth <= 0
+          ? `spawning is disabled for this session (max depth ${session.maxDepth}), so no definition can ` +
+            `run whatever its file says. If you did not set PI_GRANTS_MAX_DEPTH to 0, check the warning ` +
+            `above: a malformed value disables spawning deliberately.`
+          : `this session is at its depth limit (${session.depth} of ${session.maxDepth}), so it may not ` +
+            `spawn — a definition refused here is not a problem with its file.`,
+    };
+  }
+
+  const spawnable: string[] = [];
+  const withheld: WithheldDefinition[] = [];
+
+  for (const name of names.slice(0, PREVIEW_LIMIT)) {
+    const { plan } = await preview(name);
+    if (plan.ok) {
+      spawnable.push(name);
+      continue;
+    }
+    // Read off the plan's own result, in the order `planDelegation` decides them: an escalation is reported
+    // before a gate, because a capability the session does not hold cannot be approved into existence.
+    // `denied` carries the ADR-0017 authorisation refusal too — asking to run a definition this session was
+    // not granted IS an attempt to exceed the grant, and it is recorded as one.
+    const denied = plan.result.denied;
+    const gated = plan.result.gatedBlocked;
+    if (denied.length > 0) withheld.push({ name, reason: "capability", missing: [...denied].sort() });
+    else if (gated.length > 0) withheld.push({ name, reason: "approval", missing: [...gated].sort() });
+    // Everything else: say what the ENFORCER said. Inventing a category here is what told an operator with
+    // an unknown capability, an unresolvable `skill:`, or a universal capability that their file was
+    // written wrong, in wording that contradicted `/grants` on the same screen.
+    else withheld.push({ name, reason: "declaration", missing: [], reasonText: plan.reason });
+  }
+
+  return { spawnable, withheld, notChecked: Math.max(0, names.length - PREVIEW_LIMIT) };
+}
+
+/** `a, b, c` — or the first few and a count, so a large skill root does not become the whole line. */
+function list(names: string[]): string {
+  if (names.length <= NAMES_SHOWN) return names.join(", ");
+  return `${names.slice(0, NAMES_SHOWN).join(", ")} … and ${names.length - NAMES_SHOWN} more`;
+}
+
+/**
+ * A definition name is a DIRECTORY name, so it is third-party text on a line this package composes.
+ *
+ * R-77 and R-78 were both "a name from somewhere else reached a generated artefact"; a newline here forges
+ * a whole `grants:` line in the operator's terminal. Same class, lower stakes, same treatment: rendered
+ * inert rather than trusted.
+ */
+function safeName(name: string): string {
+  return /[\n\r\t]/.test(name) ? JSON.stringify(name) : name;
+}
+
+/**
+ * Render the summary, or `null` when there is nothing to say.
+ *
+ * `null` means **no definitions were discovered at all** — a session delegating by `tools:` only, which is
+ * a legitimate configuration and not something to report every start. Every other case speaks, including
+ * "none of them is spawnable": that is P2's exact state (seven skills installed, zero declaring
+ * `allowed-tools`), and it is the one an operator most needs told.
+ */
+export function renderSpawnableSummary(summary: SpawnableSummary, total: number): string | null {
+  if (total === 0) return null;
+  if (summary.sessionBlocked) {
+    return `grants: ${total} definition${total === 1 ? "" : "s"} found, none spawnable — ${summary.sessionBlocked}`;
+  }
+
+  const lines = [
+    `grants: ${summary.spawnable.length} of ${total} definition${total === 1 ? "" : "s"} spawnable` +
+      (summary.spawnable.length > 0 ? ` — ${list(summary.spawnable.map(safeName))}` : ""),
+  ];
+
+  // PER DEFINITION, not per group. Grouping printed the UNION of every missing capability against every
+  // name in the group, so a definition missing only `agent:x` was reported as needing `tool:bash` as well —
+  // and naming the fix is this line's whole stated purpose.
+  const clause = (w: WithheldDefinition): string => {
+    const name = safeName(w.name);
+    if (w.reason === "capability") return `${name} (needs ${list(w.missing)})`;
+    // ADR-0024: a gated `agent:` id is the PARENT's authority to run the definition now, and is deliberately
+    // kept out of what the child receives. "before a child receives it" was wrong for exactly that case.
+    if (w.reason === "approval") return `${name} (needs your approval for ${list(w.missing)})`;
+    return `${name} (${w.reasonText ?? "cannot be spawned as its file is written"})`;
+  };
+
+  if (summary.withheld.length > 0) {
+    const shown = summary.withheld.slice(0, NAMES_SHOWN).map(clause);
+    const extra = summary.withheld.length - shown.length;
+    lines.push(`  withheld: ${shown.join("; ")}${extra > 0 ? `; … and ${extra} more` : ""}`);
+  }
+  if (summary.notChecked > 0) {
+    lines.push(`  ${summary.notChecked} more not checked (first ${PREVIEW_LIMIT} only) — /grants lists them`);
+  }
+
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",
@@ -84,8 +84,19 @@
     "./approval-prompt": {
       "types": "./dist/approval-prompt.d.ts",
       "default": "./dist/approval-prompt.js"
+    },
+    "./init": {
+      "types": "./dist/init.d.ts",
+      "default": "./dist/init.js"
+    },
+    "./skill-packages": {
+      "types": "./dist/skill-packages.d.ts",
+      "default": "./dist/skill-packages.js"
     }
   },
+  "bin": {
+    "pi-daddy": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "extensions",

package/src/catalog.ts

@@ -168,6 +168,98 @@ export function unknownCapabilities(requested: Capability[], catalog: Catalog):
   return requested.filter((c) => c !== WILDCARD && c !== AGENT_WILDCARD && !catalog.has(c)).sort();
 }
 
+/**
+ * Tool names that exist in OTHER harnesses' vocabularies, mapped to the pi tool that does the same job.
+ *
+ * This is a hint for an error message and nothing else. `ceilingForDefinition` deliberately refuses to
+ * translate names — lowercasing and no more — because a translation table there would have to decide what
+ * `Glob` *means* and would either invent a grant or silently drop one. Naming a likely intent in the
+ * refusal costs nothing and keeps that property: the delegation is still refused, and the author still
+ * edits the file.
+ *
+ * Populated from the names an author actually reaches for. `allowed-tools` is an Agent Skills field, so
+ * the frontmatter people copy in is usually written against Claude Code's toolset; `Glob` is the one that
+ * bit a real consumer (principal-pi-skills, seven definitions), because pi's equivalent is `find`.
+ */
+const FOREIGN_TOOL_NAMES: Readonly<Record<string, string>> = {
+  "tool:glob": "tool:find",
+  "tool:searchfiles": "tool:find",
+  "tool:bashtool": "tool:bash",
+  "tool:readfile": "tool:read",
+  "tool:writefile": "tool:write",
+  "tool:str_replace_editor": "tool:edit",
+  "tool:multiedit": "tool:edit",
+};
+
+/**
+ * Optimal string alignment distance — Levenshtein plus adjacent transposition.
+ *
+ * Transposition counts as ONE edit, not two, because it is the typo people actually make: `raed` for
+ * `read` is a single slip of the fingers, and plain Levenshtein scores it 2 — the same as two unrelated
+ * substitutions. With the threshold this small, that difference is the whole feature.
+ */
+function editDistance(a: string, b: string): number {
+  // Three rows, because a transposition needs the row before last.
+  const rows: number[][] = [
+    Array.from({ length: b.length + 1 }, (_, j) => j),
+    new Array<number>(b.length + 1).fill(0),
+    new Array<number>(b.length + 1).fill(0),
+  ];
+  let twoBack = rows[2];
+  let prev = rows[0];
+  let cur = rows[1];
+
+  for (let i = 1; i <= a.length; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let d = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        d = Math.min(d, twoBack[j - 2] + 1);
+      }
+      cur[j] = d;
+    }
+    const spent = twoBack;
+    twoBack = prev;
+    prev = cur;
+    cur = spent;
+  }
+  return prev[b.length];
+}
+
+/**
+ * The capability an unknown one was most likely meant to be, or null when nothing is close enough.
+ *
+ * Two sources, in order. A known foreign name wins outright — `Glob` is not a typo for `find`, so no
+ * distance metric would ever connect them, and that is exactly the case worth naming. Otherwise the
+ * nearest catalog entry within a small edit distance, which catches `raed`/`serach` and stops well short
+ * of guessing: the threshold scales with the name's length and never exceeds two.
+ */
+export function suggestForUnknown(unknown: Capability, catalog: Catalog): Capability | null {
+  const foreign = FOREIGN_TOOL_NAMES[unknown.toLowerCase()];
+  if (foreign && catalog.has(foreign)) return foreign;
+
+  // Only among capabilities of the same namespace: suggesting `skill:review` for a mistyped tool name
+  // would be a worse message than none, because it points the author at the wrong kind of fix.
+  const ns = unknown.slice(0, unknown.indexOf(":") + 1);
+  if (!ns) return null;
+  const bare = unknown.slice(ns.length);
+  const limit = Math.min(2, Math.floor(bare.length / 3));
+  if (limit < 1) return null;
+
+  let best: Capability | null = null;
+  let bestDistance = limit + 1;
+  for (const candidate of catalog.all) {
+    if (!candidate.startsWith(ns)) continue;
+    const d = editDistance(bare, candidate.slice(ns.length));
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = candidate;
+    }
+  }
+  return bestDistance <= limit ? best : null;
+}
+
 /**
  * Skill name -> absolute path, for `planSpawn`'s `--skill` flags (R-32).
  *