pi-daddy 0.13.0 → 0.14.0

package/dist/skill-packages.js

@@ -0,0 +1,216 @@
+/**
+ * Which installed npm packages ship `SKILL.md` definitions — read from their own manifests.
+ *
+ * `pi-daddy init` scaffolds a governed project from whatever skill packages are already installed, and
+ * this is how it finds them: **a package declares its skills in `package.json`'s `pi.skills` array**, which
+ * is pi's own convention and how pi itself loads them. Measured against `principal-pi-skills@2.3.1`:
+ *
+ * ```json
+ * "pi": { "skills": ["./decide", "./architect", "./plan", "./build", "./review", "./debug", "./git-ops"] }
+ * ```
+ *
+ * **A declaration, never a heuristic.** Walking `node_modules` looking for files called `SKILL.md` would
+ * find a package's test fixtures, its examples, and its vendored copies of someone else's skills — and
+ * would then offer to install them as spawnable sub-agents. A package that says which of its files are
+ * skills has said so on purpose, and that is the only list this reads.
+ *
+ * What it deliberately does NOT do: scan `~/.pi/agent/skills/`. Definitions already in a skill root are
+ * discovered by `loadDefinitions` and governed as they stand; copying them into a project would duplicate
+ * them under a name that shadows the original (project wins on collision), which is a change nobody asked
+ * for.
+ *
+ * **Everything read here comes from a third party**, so this module is also where the refusals live: a
+ * name, a declared capability id, or a path that cannot safely be written into a generated file is refused
+ * with a reason rather than passed on (R-77, R-78, R-80). `init` generates a shell file an operator
+ * `source`s; the only strings that may reach it are ones that survived a whitelist here.
+ */
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { ceilingForDefinition, parseSkillDefinition } from "./definitions.js";
+import { WILDCARD } from "./pi-tools.js";
+import { AGENT_WILDCARD } from "./resolve.js";
+/**
+ * May this definition's name be written into a capability id, a shell file and a path?
+ *
+ * **Measured before it was written, and it was a defect in this module's first version (R-77).** A
+ * definition's identity is its directory name, and `init` interpolates that name into three places at once:
+ * `agent:<name>` inside a **comma-separated** `PI_GRANTS_GRANT`, a `.pi/grants.env` an operator **sources**,
+ * and the path it writes the copy to. An installed package with a directory called `a,tool:bash` produced
+ *
+ * ```
+ * export PI_GRANTS_GRANT="agent:a,tool:bash,tool:delegate,tool:read"
+ * ```
+ *
+ * — `tool:bash` in an operator's grant, declared by nobody. A quote character reaches a file that gets
+ * `source`d, and a name of `..` writes outside `.pi/skills/`. One rule closes all three, and it is
+ * deliberately a **whitelist**: the safe set here is small and the unsafe set is the rest of Unicode.
+ *
+ * The first character must be alphanumeric, so `..` and dotfiles are refused along with everything else.
+ */
+export function isSafeName(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
+}
+/**
+ * May this DECLARED capability id be written into the generated grant? — R-78.
+ *
+ * **R-77's other half, and the reason a whitelist beats a blocklist twice.** R-77 was closed on the name
+ * channel; the `allowed-tools` *value* travels to the identical interpolation site and was unchecked, so a
+ * package declaring
+ *
+ * ```yaml
+ * allowed-tools: Read,ext:x";touch /tmp/pwned;PI_GRANTS_GRANT="
+ * ```
+ *
+ * produced a `.pi/grants.env` that executed arbitrary code the moment the operator ran the `source` line
+ * `init` itself prints. Reproduced end to end before this existed. `ceilingForDefinition` passes `ext:`,
+ * `skill:` and `agent:` entries through **as written** by design (a translation table would invent or drop
+ * grants), which is right for the enforcement path — the catalog refuses what it does not know — and is
+ * exactly why the check has to be here, at the boundary that *generates* rather than the one that enforces.
+ *
+ * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`, and
+ * `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused separately and
+ * loudly, because "you tried to grant yourself everything" is a different fact from "that is not a name".
+ */
+export function isSafeCapability(id) {
+    const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
+    return (new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
+        new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id));
+}
+/** The two ids that confer root authority. A package declaring one is claiming it, not describing a need. */
+function wildcardsIn(capabilities) {
+    return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD);
+}
+/**
+ * Everything about one declared skill that would make it unsafe to scaffold. `null` when it is fine.
+ *
+ * Ordered so the operator is told the most actionable thing: a wildcard is a deliberate claim, an unsafe id
+ * is probably a typo or an attack, and a bad name is neither.
+ */
+function refusalFor(skill) {
+    const name = skill.definition.name;
+    if (!isSafeName(name))
+        return { subject: name, reason: "unsafe-name", detail: [name] };
+    const ceiling = ceilingForDefinition(skill.definition);
+    const wildcards = wildcardsIn(ceiling.capabilities);
+    if (wildcards.length > 0)
+        return { subject: name, reason: "wildcard", detail: wildcards };
+    const unsafe = ceiling.capabilities.filter((c) => !isSafeCapability(c));
+    if (unsafe.length > 0)
+        return { subject: name, reason: "unsafe-capability", detail: unsafe };
+    return null;
+}
+/** One `pi.skills` entry: a directory holding `SKILL.md`, or a `.md` file — the same two shapes pi allows. */
+async function readSkill(packageDir, entry) {
+    const target = resolve(packageDir, entry);
+    // A manifest is data from another package, so an entry escaping its own directory is refused rather than
+    // followed. **`realpath`, not a lexical prefix test** (R-80): `resolve()` normalises `..` and knows
+    // nothing about symlinks, so a packaged symlink walked straight past the first version of this check and
+    // a definition from outside the package was copied in, with its `allowed-tools` landing in the operator's
+    // grant. Measured. This is the same lesson as the `realpathSync` fix in `cli.ts`, which was found by the
+    // smoke test one day earlier and not applied here.
+    const realPackageDir = await realpath(packageDir).catch(() => packageDir);
+    for (const path of [join(target, "SKILL.md"), ...(target.endsWith(".md") ? [target] : [])]) {
+        let bytes;
+        try {
+            bytes = await readFile(path);
+        }
+        catch {
+            continue;
+        }
+        const realPath = await realpath(path).catch(() => path);
+        if (!realPath.startsWith(realPackageDir + sep))
+            return null;
+        // "The file verbatim … nothing is lost in a round trip" is a claim this module makes, so bytes that
+        // cannot survive the round trip are refused rather than silently replaced. A latin-1 `0xE9` used to come
+        // back as U+FFFD, changing the file's length and its digest, with no warning.
+        const text = bytes.toString("utf8");
+        if (!Buffer.from(text, "utf8").equals(bytes))
+            return "not-utf8";
+        const definition = parseSkillDefinition(path, text);
+        return definition ? { definition, text, path } : null;
+    }
+    return null;
+}
+/** Read one installed package, if it declares skills. `null` means "not a skill package", not an error. */
+export async function readSkillPackage(packageDir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const declared = manifest.pi?.skills;
+    if (!Array.isArray(declared) || declared.length === 0)
+        return null;
+    const skills = [];
+    const unreadable = [];
+    const refused = [];
+    for (const entry of declared) {
+        if (typeof entry !== "string")
+            continue;
+        const skill = await readSkill(packageDir, entry);
+        if (skill === null) {
+            unreadable.push(entry);
+        }
+        else if (skill === "not-utf8") {
+            refused.push({ subject: entry, reason: "not-utf8", detail: [] });
+        }
+        else {
+            const refusal = refusalFor(skill);
+            if (refusal)
+                refused.push(refusal);
+            else
+                skills.push(skill);
+        }
+    }
+    return {
+        name: manifest.name ?? packageDir.split(sep).pop() ?? "(unnamed)",
+        version: manifest.version ?? "(no version)",
+        unreadable,
+        refused,
+        skills,
+    };
+}
+/**
+ * Every installed package under `<cwd>/node_modules` that declares `pi.skills`, sorted by name.
+ *
+ * Top level and one scope deep, which is what npm's layout has. Nothing recurses into a dependency's own
+ * `node_modules`: a transitive skill package is not something an operator asked to install definitions
+ * from, and scaffolding one into their project would be a surprise wearing a helpful face.
+ */
+export async function discoverSkillPackages(cwd) {
+    const root = join(cwd, "node_modules");
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return []; // no node_modules is a normal state, not a failure
+    }
+    const dirs = [];
+    for (const entry of entries.sort()) {
+        if (entry.startsWith("."))
+            continue; // .bin, .package-lock.json
+        if (entry.startsWith("@")) {
+            try {
+                for (const scoped of (await readdir(join(root, entry))).sort())
+                    dirs.push(join(root, entry, scoped));
+            }
+            catch {
+                continue;
+            }
+        }
+        else {
+            dirs.push(join(root, entry));
+        }
+    }
+    const packages = [];
+    for (const dir of dirs) {
+        const found = await readSkillPackage(dir);
+        if (found)
+            packages.push(found);
+    }
+    return packages.sort((a, b) => a.name.localeCompare(b.name));
+}
+//# sourceMappingURL=skill-packages.js.map

package/dist/skill-packages.js.map

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

package/extensions/grants.ts

@@ -36,6 +36,7 @@ import { registerDelegationTools } from "./delegation.ts";
 import { grantsCommand } from "./grants-command.ts";
 import { planWithApprovals } from "./run-delegation.ts";
 import { createGrantsSession } from "./session.ts";
+import { renderSpawnableSummary, summariseSpawnable } from "./spawn-summary.ts";
 
 const SPAWN_TOOLS = new Set(["Agent", "subagent", "spawn_agent"]);
 
@@ -207,6 +208,35 @@ export default function (pi: ExtensionAPI) {
           `grants: depth ${session.depth}/${session.maxDepth}, holding [${session.ownGrant.join(", ") || "nothing"}]`,
           "info",
         );
+        // B1 / P4. The grant alone never named the definitions, never said where they came from, and never
+        // said which ones were being WITHHELD — so an operator who had just installed a package of
+        // `SKILL.md` files could not tell governance-is-working from did-the-install-fail. Classified by the
+        // real planner (see `./spawn-summary.ts`), never by a second reading of the rules.
+        //
+        // Its own try/catch, and not because `summariseSpawnable` throws today: this is the R-60 shape
+        // exactly — one added `await` inside the blanket catch cancelling every control below it in
+        // silence. There is nothing below it now; there will be.
+        try {
+          const line = renderSpawnableSummary(
+            await summariseSpawnable(
+              session.definitions,
+              (name) => planWithApprovals(session, { task: "(preview)", agent: name }, {}, null),
+              // The session facts that make every per-definition verdict identical. `mayDelegate` in
+              // particular: without `tool:delegate` there is no delegate tool at all, and the line used to
+              // report definitions as spawnable in the one session where nothing can ever be spawned.
+              { mayDelegate: session.mayDelegate, depth: session.depth, maxDepth: session.maxDepth },
+            ),
+            session.definitions.size,
+          );
+          if (line) ctx.ui.notify(line, "info");
+        } catch (error) {
+          ctx.ui.notify(
+            `grants: could not work out which definitions are spawnable ` +
+              `(${error instanceof Error ? error.message : String(error)}) — run /grants for the per-definition ` +
+              `verdict. Nothing about the grant or its enforcement depends on this line.`,
+            "warning",
+          );
+        }
       }
     } catch (error) {
       // Rule 8 — fail closed, and be LOUD about it. Swallowing is still right: a startup fault must not

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.14.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).
  *