@pi-archimedes/subagent 2.10.3 → 2.11.0

package/src/tool-schema.ts

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import type { SubagentResult, SubagentRunReport } from "./types.js";
 
 // ── JSON Schema for tool parameters (TypeBox) ──────────────────────────────
 
@@ -31,3 +32,87 @@ export const SUBAGENT_PARAMS_SCHEMA = Type.Object({
     description: "Working directory for the subagent",
   })),
 });
+
+// ── JSON Schema for `structuredContent` ────────────────────────────────
+//
+// One report per run: what ran, how it ended, what it cost, what it answered.
+// It is `details` minus the live-progress blob — `details.progress[i].output`
+// is the child's whole streamed scrollback and `toolCalls` its call history, for
+// the row renderer, and a script that wants the answer already has
+// `finalOutput`. `usageAccountedElsewhere` is left out too: it is this session's
+// bookkeeping flag (ADR 0028), not a fact about the run.
+//
+// pi hands this to a codemode script instead of the text and validates it
+// against nothing, so `index.output-schema.test.ts` runs the handler and checks
+// the payload against this declaration.
+//
+// A single run that reports itself as failed is `isError` and carries none of it
+// (see the note in `index.ts`), so a script keeps rejecting with the text it
+// rejects with today. A parallel batch is the other case: one failed run inside
+// a batch does not make the batch an error — it stays a report of N runs, with
+// that run's `error` field set inside `results` (pre-existing shape, unchanged
+// by these schemas; see the per-run failure markers in `formatParallelResults`).
+
+const UsageSchema = Type.Object({
+  input: Type.Number(),
+  output: Type.Number(),
+  cacheRead: Type.Number(),
+  cacheWrite: Type.Number(),
+  cost: Type.Number(),
+  turns: Type.Number(),
+});
+
+const ProgressSummarySchema = Type.Object({
+  toolCount: Type.Number(),
+  tokens: Type.Number(),
+  durationMs: Type.Number(),
+});
+
+const RunReportSchema = Type.Object({
+  agent: Type.String(),
+  task: Type.String(),
+  exitCode: Type.Number(),
+  childSessionId: Type.Optional(Type.String()),
+  outcome: Type.Optional(
+    Type.Union([Type.Literal("completed"), Type.Literal("truncated"), Type.Literal("aborted")]),
+  ),
+  usage: UsageSchema,
+  model: Type.Optional(Type.String()),
+  finalOutput: Type.Optional(Type.String({ description: "The run's answer text, when it produced one" })),
+  error: Type.Optional(Type.String({ description: "Set when the run failed before or during execution" })),
+  progressSummary: Type.Optional(ProgressSummarySchema),
+});
+
+export const SUBAGENT_OUTPUT_SCHEMA = Type.Object({
+  mode: Type.Union([Type.Literal("single"), Type.Literal("parallel")]),
+  results: Type.Array(RunReportSchema),
+});
+
+/** The report for one run; `undefined` fields are omitted, not null. */
+export function subagentStructuredContent(
+  mode: "single" | "parallel",
+  results: SubagentResult[],
+): { mode: "single" | "parallel"; results: SubagentRunReport[] } {
+  return {
+    mode,
+    results: results.map((result) => ({
+      agent: result.agent,
+      task: result.task,
+      exitCode: result.exitCode,
+      ...(result.childSessionId !== undefined && { childSessionId: result.childSessionId }),
+      ...(result.outcome !== undefined && { outcome: result.outcome }),
+      usage: {
+        input: result.usage.input,
+        output: result.usage.output,
+        cacheRead: result.usage.cacheRead,
+        cacheWrite: result.usage.cacheWrite,
+        cost: result.usage.cost,
+        turns: result.usage.turns,
+      },
+      ...(result.model !== undefined && { model: result.model }),
+      ...(result.finalOutput !== undefined && { finalOutput: result.finalOutput }),
+      ...(result.error !== undefined && { error: result.error }),
+      ...(result.progressSummary !== undefined && { progressSummary: { ...result.progressSummary } }),
+    })),
+  };
+}

package/src/tool-validation.test.ts

@@ -0,0 +1,321 @@
+import { describe, it, expect } from "vitest";
+import {
+  splitToolEntries,
+  readToolEntries,
+  validateToolEntries,
+  applyToolEntries,
+  unknownToolEntries,
+  formatUnknownToolsWarning,
+} from "./tool-validation.js";
+import type { AgentConfig } from "./agents.js";
+
+// ── The split this module encodes ───────────────────────────────────────────
+//
+// Two questions, asked at two different moments:
+//
+//   * Can this string be a tool name at all? — **lexical**. Answerable anywhere,
+//     including at config read, where there is no tool registry: `discoverAgents()`
+//     is pure filesystem. Rejects here.
+//   * Does pi have this tool right now? — **membership**. Needs the ExtensionAPI
+//     handle (`pi.getAllTools()`), so it can only be asked at dispatch, and the
+//     answer is a warning, never a refusal: a legitimate name is absent whenever
+//     its plugin is toggled off or its MCP server is disconnected.
+//
+// Nothing in this file asserts that a name is or is not a known tool except in
+// the `unknownToolEntries` block, which is the membership half.
+
+function makeAgent(overrides: Partial<AgentConfig> = {}): AgentConfig {
+  return {
+    name: "reviewer",
+    description: "d",
+    systemPrompt: "p",
+    source: "user",
+    filePath: "/tmp/agents/reviewer.md",
+    ...overrides,
+  };
+}
+
+const CTX = { agentName: "reviewer", agentFilePath: "/tmp/agents/reviewer.md" };
+
+describe("splitToolEntries", () => {
+  it("keeps empty entries so they can be reported instead of filtered away", () => {
+    expect(splitToolEntries("read,,bash")).toEqual(["read", "", "bash"]);
+    expect(splitToolEntries("read, bash ")).toEqual(["read", "bash"]);
+    expect(splitToolEntries(" ")).toEqual([""]);
+    expect(splitToolEntries("")).toEqual([]);
+  });
+});
+
+describe("validateToolEntries (lexical only)", () => {
+  it("accepts a plain list of names", () => {
+    expect(validateToolEntries(["read", "bash", "mcp__radius__query"], CTX)).toEqual({ ok: true });
+    expect(validateToolEntries([], CTX)).toEqual({ ok: true });
+  });
+
+  it("rejects an empty entry and names it", () => {
+    const result = validateToolEntries(["read", "", "bash"], CTX);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain('""');
+      expect(result.error).toContain("reviewer");
+      expect(result.error).toContain("/tmp/agents/reviewer.md");
+    }
+  });
+
+  it("rejects a whitespace-only entry as the empty entry it parses to", () => {
+    const result = validateToolEntries(splitToolEntries("read,   , bash"), CTX);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain('""');
+      expect(result.error).toMatch(/empty/i);
+    }
+  });
+
+  it("rejects a leading-+ entry as a modifier and names it", () => {
+    const result = validateToolEntries(["read", "+web_search"], CTX);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("+web_search");
+      // The reason matters: pi reads it as a modifier, not a name.
+      expect(result.error).toMatch(/modifier/i);
+    }
+  });
+
+  it("rejects a leading-- entry as a modifier and names it", () => {
+    const result = validateToolEntries(["-bash"], CTX);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("-bash");
+  });
+
+  it("rejects a duplicated entry and names it", () => {
+    const result = validateToolEntries(["read", "bash", "read"], CTX);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("read");
+      expect(result.error).toMatch(/twice|more than once/i);
+    }
+  });
+
+  it("reports the first problem it finds, in list order", () => {
+    const result = validateToolEntries(["read", "read", "+bash"], CTX);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).not.toContain("+bash");
+  });
+
+  it("says the field and file when both are known, and degrades to a generic message when not", () => {
+    const named = validateToolEntries(["read", "read"], { agentName: "explore" });
+    expect(!named.ok && named.error).toContain("explore");
+    const bare = validateToolEntries(["read", "read"]);
+    expect(bare.ok).toBe(false);
+    if (!bare.ok) expect(bare.error).toContain("read");
+  });
+});
+
+describe("applyToolEntries (the edit-site half: reject leaves the previous value alone)", () => {
+  it("applies a valid list", () => {
+    const agent = makeAgent({ tools: ["bash"] });
+    const error = applyToolEntries(agent, ["read", "bash"], CTX);
+    expect(error).toBeNull();
+    expect(agent.tools).toEqual(["read", "bash"]);
+  });
+
+  it("an empty list means no allowlist, and clears the field", () => {
+    const agent = makeAgent({ tools: ["bash"] });
+    expect(applyToolEntries(agent, [], CTX)).toBeNull();
+    expect(agent.tools).toBeUndefined();
+  });
+
+  it("a rejected entry leaves the previous list intact", () => {
+    const agent = makeAgent({ tools: ["read", "bash"] });
+    const error = applyToolEntries(agent, ["read", "+bash"], CTX);
+    expect(error).toBeTruthy();
+    expect(agent.tools).toEqual(["read", "bash"]);
+  });
+
+  it("a rejected empty entry leaves the previous list intact", () => {
+    const agent = makeAgent({ tools: ["read"] });
+    expect(applyToolEntries(agent, ["read", "  "], CTX)).toBeTruthy();
+    expect(agent.tools).toEqual(["read"]);
+  });
+
+  it("a rejected duplicate leaves the previous list intact", () => {
+    const agent = makeAgent();
+    expect(applyToolEntries(agent, ["read", "read"], CTX)).toBeTruthy();
+    expect(agent.tools).toBeUndefined();
+  });
+});
+
+describe("applyToolEntries: a commit replaces the rejected value it is superseding", () => {
+  // The config read keeps an unreadable `tools:` in `extraFields` so that saving
+  // an agent cannot silently delete the line the user typed (`agents.ts`). That
+  // promise is to the *rejected* value. Once the panel commits a list, the old
+  // raw value has to go with the rejection: `serializeAgent` writes `tools` and
+  // then every extra field, so a surviving `extraFields.tools` puts a SECOND
+  // `tools:` key in the file (or the only one, when the list was cleared) and the
+  // agent comes back broken after a reload.
+  const rejected = () =>
+    makeAgent({
+      toolsError:
+        'Agent "reviewer" has a tools entry starting with "+" (in /tmp/agents/reviewer.md): "+web_search".',
+      extraFields: { tools: "read, +web_search", owner: "someone" },
+    });
+
+  it("drops the preserved raw value when a valid list is committed", () => {
+    const agent = rejected();
+    expect(applyToolEntries(agent, ["read"], CTX)).toBeNull();
+    expect(agent.tools).toEqual(["read"]);
+    expect(agent.extraFields ?? {}).not.toHaveProperty("tools");
+    // Only the superseded value goes; unrelated extras stay.
+    expect(agent.extraFields?.owner).toBe("someone");
+  });
+
+  it("drops the preserved raw value when the allowlist is cleared", () => {
+    // Clearing is the case that used to look like success and change nothing:
+    // `tools` was deleted, the raw value stayed, and the writer put the broken
+    // line straight back.
+    const agent = rejected();
+    expect(applyToolEntries(agent, [], CTX)).toBeNull();
+    expect(agent.tools).toBeUndefined();
+    expect(agent.extraFields ?? {}).not.toHaveProperty("tools");
+  });
+
+  it("clears the stale rejection so the agent dispatches again in this session", () => {
+    const agent = rejected();
+    expect(applyToolEntries(agent, ["read"], CTX)).toBeNull();
+    expect(agent.toolsError).toBeUndefined();
+  });
+
+  it("a REFUSED commit destroys neither the list, the raw value, nor the rejection", () => {
+    const agent = rejected();
+    expect(applyToolEntries(agent, ["read", "+x"], CTX)).toBeTruthy();
+    expect(agent.tools).toBeUndefined();
+    expect(agent.extraFields?.tools).toBe("read, +web_search");
+    expect(agent.toolsError).toBeTruthy();
+  });
+
+  it("never mutates the extraFields object it was handed", () => {
+    // `/agents` builds its edit copy with `{ ...agent }` (`agent-panel.ts`), so
+    // `extraFields` is ONE object shared with `state.editOriginal` and with the
+    // discovered agent. Deleting a key in place therefore discards the preserved
+    // raw value from the *original* too: commit, then discard the edit, and the
+    // next save writes no `tools:` line at all — the allowlist disappears from
+    // the file without the user asking. Copy instead.
+    const shared = { tools: "read, +web_search", owner: "someone" };
+    const agent = makeAgent({ extraFields: shared });
+    expect(applyToolEntries(agent, ["read"], CTX)).toBeNull();
+    expect(shared.tools).toBe("read, +web_search");
+    expect(agent.extraFields).not.toBe(shared);
+    expect(agent.extraFields?.owner).toBe("someone");
+  });
+
+  it("drops the whole extraFields object when tools was the only field", () => {
+    // An empty record would otherwise render as an empty "extra fields" section
+    // and be re-written as nothing at all.
+    const agent = makeAgent({ extraFields: { tools: "read, +x" } });
+    expect(applyToolEntries(agent, ["read"], CTX)).toBeNull();
+    expect(agent.extraFields).toBeUndefined();
+  });
+});
+
+describe("unknownToolEntries (membership, asked at dispatch)", () => {
+  const KNOWN = ["read", "bash", "mcp__radius__query"];
+
+  it("reports entries pi does not currently have", () => {
+    expect(unknownToolEntries(["read", "web_search"], KNOWN)).toEqual(["web_search"]);
+  });
+
+  it("reports nothing when every entry is available", () => {
+    expect(unknownToolEntries(["read", "bash"], KNOWN)).toEqual([]);
+  });
+
+  it("treats a * entry as a pattern over the tools pi actually has", () => {
+    expect(unknownToolEntries(["mcp__radius__*"], KNOWN)).toEqual([]);
+    expect(unknownToolEntries(["mcp__nope__*"], KNOWN)).toEqual(["mcp__nope__*"]);
+  });
+
+  it("names every offending entry in the warning", () => {
+    const warning = formatUnknownToolsWarning("reviewer", ["web_search", "sudo_exec"]);
+    expect(warning).toContain("web_search");
+    expect(warning).toContain("sudo_exec");
+    // The whole point of warn-not-fail: the run still happens.
+    expect(warning).toMatch(/proceed|continues/i);
+  });
+});
+
+describe("readToolEntries: every YAML spelling of a tools value", () => {
+  // pi's frontmatter parser hands the config read whatever YAML said, so the
+  // comma string this suite writes is only one of three shapes that mean
+  // "allowlist". Reading only that one silently dropped list-shaped configs —
+  // no allowlist at all, which is the unrestricted child ADR 0028 forbids.
+  const ok = (r: ReturnType<typeof readToolEntries>) => ("entries" in r ? r.entries : undefined);
+
+  it("reads the comma-separated form the suite's writer emits", () => {
+    expect(ok(readToolEntries("read, bash"))).toEqual(["read", "bash"]);
+  });
+
+  it("reads a block list, trimming each entry", () => {
+    expect(ok(readToolEntries(["read", " bash "]))).toEqual(["read", "bash"]);
+  });
+
+  it("reads an inline list, and keeps an empty entry visible for the name rules to reject", () => {
+    expect(ok(readToolEntries(["read", ""]))).toEqual(["read", ""]);
+  });
+
+  it("reports an entry that is not a string, naming it", () => {
+    const r = readToolEntries(["read", { count: 2 }], { agentName: "probe" });
+    expect("error" in r ? r.error : undefined).toMatch(/not a tool name/);
+    expect("error" in r ? r.error : "").toContain('{"count":2}');
+    expect("error" in r ? r.error : "").toContain('Agent "probe"');
+  });
+
+  it("reports a value that is not a list at all, and says what to write instead", () => {
+    const r = readToolEntries(42, { agentFilePath: "/x/probe.md" });
+    expect("error" in r ? r.error : undefined).toMatch(/not a list of tool names/);
+    expect("error" in r ? r.error : "").toContain("/x/probe.md");
+    expect("error" in r ? r.error : "").toContain("read, bash");
+  });
+
+  it("an absent key is the caller's business, not an error here (it never reaches this gate)", () => {
+    expect(ok(readToolEntries(""))).toEqual([]);
+  });
+
+  it("splits a list entry that carries a comma, because the child splits it too", () => {
+    // `--tools` is ONE argv string the host re-splits on commas
+    // (`pi/dist/cli/args.js`: `args[++i].split(",")`), so an entry written
+    // `"read,+bash"` in a YAML list reaches the child as two entries — the
+    // validator has to look at the same list the child will run with, or it
+    // certifies a shape it never sees.
+    expect(ok(readToolEntries(["read,+bash"]))).toEqual(["read", "+bash"]);
+    expect(ok(readToolEntries([" read , bash "]))).toEqual(["read", "bash"]);
+  });
+
+  it("keeps a hidden modifier visible for the name rules, so the read rejects it", () => {
+    const entries = readToolEntries(["read,+bash"]);
+    if (!("entries" in entries)) throw new Error("expected entries");
+    const check = validateToolEntries(entries.entries, CTX);
+    expect(check.ok).toBe(false);
+    if (!check.ok) expect(check.error).toContain("+bash");
+  });
+});
+
+describe("validateToolEntries: a comma inside one entry", () => {
+  it("is refused rather than certified, because the child would split it", () => {
+    // The read path splits, so this rule guards every *other* caller —
+    // `applyToolEntries` and anything that builds an AgentConfig directly. A
+    // list we validated must be the list the child runs with: pi would turn
+    // `["read,+bash"]` into `--tools read,+bash`, reject the whole flag as
+    // mixed names-and-modifiers, and run the child with NO allowlist at all
+    // (verified against a live 1.2.0 child: exit 1, `Error: --tools: tool
+    // names cannot be mixed with +name or -name entries`).
+    const result = validateToolEntries(["read", "read,+bash"], CTX);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("read,+bash");
+      expect(result.error).toContain("reviewer");
+    }
+  });
+
+  it("is refused even when it is the only entry", () => {
+    expect(validateToolEntries(["a,b"], CTX).ok).toBe(false);
+  });
+});

package/src/tool-validation.ts

@@ -0,0 +1,262 @@
+import type { AgentConfig } from "./agents.js";
+
+// ── Tool-name validation, split by what each site is allowed to know ────────
+//
+// Two questions look similar and are not:
+//
+//   **Lexical** — can this string be a tool *name* at all? Empty/whitespace
+//   entries, duplicates, entries containing a comma (the child re-splits the one
+//   argv string on commas, so a comma means two entries by then), and entries
+//   starting with `+` or `-` cannot. pi 1.1.0
+//   made `+name`/`-name` **modifiers** on the default tool set, and its own CLI
+//   parser rejects a `--tools` list that mixes them with plain names outright —
+//   the flag is dropped with `Error: --tools: tool names cannot be mixed with
+//   +name or -name entries` and exit code 1, so such a list does not merely
+//   misbehave, it takes the whole allowlist (and the run) down with it. Nothing
+//   else about the entry matters here, and that is what lets the config read
+//   (`agents.ts`) and the `/agents` panel reject malformed input: neither site has
+//   a tool registry — `discoverAgents()` is pure filesystem and
+//   `pi.getAllTools()` needs the `ExtensionAPI` handle.
+//
+//   **Membership** — does pi have this tool *right now*? Needs the handle, so it
+//   is asked at dispatch, and the answer is a warning naming the entry, never a
+//   refusal: a legitimate name is absent whenever the plugin that provides it is
+//   toggled off or the MCP server behind it is disconnected. Failing there would
+//   make `tools: web_search` unusable for anyone who disabled `web`.
+//
+// Shape and wording follow the model pre-validation precedent (ADR 0008,
+// `model-validation.ts`): a pure gate returning `{ ok }`, a message that names
+// the offending value and the file it came from, and says what to do instead.
+
+export interface ValidateToolsContext {
+  /** Agent name the entry belongs to (used to address the message). */
+  agentName?: string | undefined;
+  /** File path of the agent config whose `tools:` field is being validated. */
+  agentFilePath?: string | undefined;
+}
+
+export type ValidateToolsResult = { ok: true } | { ok: false; error: string };
+
+function address(context: ValidateToolsContext): { subject: string; where: string } {
+  return {
+    subject: context.agentName ? `Agent "${context.agentName}"` : "This agent config",
+    where: context.agentFilePath ? ` (in ${context.agentFilePath})` : "",
+  };
+}
+
+/**
+ * Split a `tools:` value into entries.
+ *
+ * Empty entries are **kept** — filtering them here is what made a malformed list
+ * look legitimate. Entries are trimmed, because that is what the child receives.
+ */
+export function splitToolEntries(raw: string): string[] {
+  if (raw.length === 0) return [];
+  return raw.split(",").map((entry) => entry.trim());
+}
+
+/**
+ * Split one YAML list entry the way the child will.
+ *
+ * `--tools` is a single argv string that the host re-splits on commas
+ * (`pi/dist/cli/args.js`: `args[++i].split(",")`), so a list entry written
+ * `"read,+bash"` is *two* entries by the time anything judges it. Validating the
+ * unsplit form certifies a list the child never runs with — and the resulting
+ * mix of names and modifiers is rejected wholesale by pi, so the child ends up
+ * with no allowlist at all. An entry without a comma is returned as the trimmed
+ * single entry, so a deliberate empty entry (`- ""`) stays visible for the name
+ * rules to report rather than vanishing here.
+ */
+function splitListEntry(item: string): string[] {
+  return item.includes(",") ? splitToolEntries(item) : [item.trim()];
+}
+
+export type ReadToolEntriesResult = { entries: string[] } | { error: string };
+
+/**
+ * Read a `tools:` **frontmatter value** as entries, before any name rules apply.
+ *
+ * pi's frontmatter parser hands over whatever YAML said, and there are three
+ * spellings in the wild: the comma-separated string this suite's writer emits,
+ * a hand-written block list (`tools:\n  - read`), and an inline list
+ * (`tools: [read]`) — the two list forms both arrive as real arrays. All three
+ * mean the same allowlist, and a list entry is comma-split on the way in so the
+ * entries judged here are the entries the child receives (`splitListEntry`).
+ * Anything else (a number, a mapping, a list holding a
+ * mapping) is not a tool list, and must be *said* to be broken rather than
+ * skipped: an allowlist this function refuses to read is a child that runs with
+ * every tool the host has, which is the whole thing ADR 0028 is about.
+ */
+export function readToolEntries(
+  raw: unknown,
+  context: ValidateToolsContext = {},
+): ReadToolEntriesResult {
+  const { subject, where } = address(context);
+  if (typeof raw === "string") return { entries: splitToolEntries(raw) };
+  if (Array.isArray(raw)) {
+    const entries: string[] = [];
+    for (const item of raw) {
+      if (typeof item !== "string") {
+        return {
+          error: `${subject} has a tools entry that is not a tool name${where}: ${JSON.stringify(item) ?? String(item)}. Each entry is a tool name on its own line (or one comma-separated list).`,
+        };
+      }
+      entries.push(...splitListEntry(item));
+    }
+    return { entries };
+  }
+  return {
+    error: `${subject}'s tools field${where} is not a list of tool names: ${JSON.stringify(raw) ?? String(raw)}. Write it as "read, bash" or as a YAML list with one tool name per entry.`,
+  };
+}
+
+/**
+ * Reject entries that cannot be tool names. Order matters: the first problem in
+ * list order is reported, so the user fixes one thing at a time.
+ */
+export function validateToolEntries(
+  entries: readonly string[],
+  context: ValidateToolsContext = {},
+): ValidateToolsResult {
+  const { subject, where } = address(context);
+  const seen = new Set<string>();
+
+  for (const [index, entry] of entries.entries()) {
+    // An entry that is only whitespace is the empty entry it trims to; the list
+    // the child receives is trimmed, so it is reported that way.
+    if (entry.trim() === "") {
+      return {
+        ok: false,
+        error: `${subject} has an empty entry${where} in its tools list: "" (entry ${index + 1} of ${entries.length}). Entries are comma-separated tool names — remove the stray comma.`,
+      };
+    }
+    const sign = entry.startsWith("+") ? "+" : entry.startsWith("-") ? "-" : "";
+    if (sign !== "") {
+      return {
+        ok: false,
+        error: `${subject} has a tools entry starting with "${sign}"${where}: "${entry}". pi reads +name/-name entries as modifiers on the default tool set, not as tool names, and a list that mixes them with names is rejected outright — the whole allowlist is dropped. Use the bare name "${entry.slice(1)}" to allow it, or leave it out.`,
+      };
+    }
+    // The comma rule sits *after* the modifier rule deliberately: for an entry
+    // like `+a,b` the modifier is what the child chokes on first, and that
+    // message says more. `readToolEntries` already splits commas on the read
+    // path, so this rule guards every other caller (`applyToolEntries`, and
+    // anything that builds an AgentConfig directly): the list we validate has to
+    // be the list the child runs with, because pi re-splits the one argv string
+    // it is handed and drops a mixed list outright.
+    if (entry.includes(",")) {
+      const parts = entry.split(",").map((part) => part.trim()).filter((part) => part !== "");
+      return {
+        ok: false,
+        error: `${subject} has a tools entry containing a comma${where}: "${entry}". The allowlist reaches the child as one comma-separated list, so this entry becomes ${parts.length} entries by the time pi reads it — write them separately (${parts.map((part) => `"${part}"`).join(", ")}).`,
+      };
+    }
+    if (seen.has(entry)) {
+      return {
+        ok: false,
+        error: `${subject} lists the tool "${entry}" twice${where} in its tools list. List each tool once.`,
+      };
+    }
+    seen.add(entry);
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Write a tools list onto an agent config, or refuse it.
+ *
+ * The edit-site half of the rule: a rejected value leaves `agent.tools` exactly
+ * as it was — a half-applied list is what a user would otherwise hand to a child
+ * without noticing. Returns the error message, or `null` when it applied.
+ *
+ * A commit also settles the two pieces of state that describe the list it is
+ * replacing. The config read keeps an unreadable `tools:` in `extraFields` so a
+ * save cannot delete the user's line, and records `toolsError` so dispatch and
+ * the panel refuse the agent; both are claims about the *old* value, and
+ * `serializeAgent` writes `tools` and every extra field — so leaving them
+ * behind puts a second (or, after a clear, the only) `tools:` key back in the
+ * file and the agent reads as broken again after a reload.
+ */
+export function applyToolEntries(
+  agent: AgentConfig,
+  entries: readonly string[],
+  context: ValidateToolsContext = {},
+): string | null {
+  // Normalised first: the allowlist reaches the child as names, so " read " and
+  // "read" are the same entry here, not two.
+  const normalized = entries.map((entry) => entry.trim());
+  const result = validateToolEntries(normalized, {
+    agentName: context.agentName ?? agent.name,
+    agentFilePath: context.agentFilePath ?? agent.filePath,
+  });
+  if (!result.ok) return result.error;
+  if (normalized.length > 0) {
+    agent.tools = [...normalized];
+  } else {
+    delete agent.tools;
+  }
+  delete agent.toolsError;
+  // Copy, never mutate in place: `/agents` builds its edit copy with
+  // `{ ...agent }`, so `extraFields` is one object shared with `editOriginal`
+  // and the discovered agent. Deleting the key there would erase the preserved
+  // raw value from the original too, so a commit followed by a discard would
+  // save the agent with no `tools:` line at all.
+  if (agent.extraFields && "tools" in agent.extraFields) {
+    const rest: Record<string, unknown> = { ...agent.extraFields };
+    delete rest.tools;
+    if (Object.keys(rest).length > 0) agent.extraFields = rest;
+    else delete agent.extraFields;
+  }
+  return null;
+}
+
+/**
+ * `*` matches any characters, as pi's own `--tools` / `--exclude-tools` entries
+ * accept it (mirrors `createToolNameMatcher` in pi's `core/mcp-servers.js`, which
+ * is not part of pi's public API surface).
+ */
+function patternRegExp(pattern: string): RegExp {
+  const source = pattern
+    .split("*")
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${source}$`);
+}
+
+/**
+ * Entries that no currently-registered tool satisfies.
+ *
+ * Membership, so this belongs at dispatch (where `pi.getAllTools()` is in
+ * scope). A `*` entry is judged the way the host judges it — satisfied when at
+ * least one available tool matches — so `mcp__radius__*` is not reported while
+ * that server's tools are connected.
+ */
+export function unknownToolEntries(
+  entries: readonly string[],
+  knownNames: Iterable<string>,
+): string[] {
+  const known = [...knownNames];
+  return entries.filter((entry) => {
+    if (entry.includes("*")) {
+      const pattern = patternRegExp(entry);
+      return !known.some((name) => pattern.test(name));
+    }
+    return !known.includes(entry);
+  });
+}
+
+/**
+ * The dispatch warning for unavailable entries.
+ *
+ * It says the run is proceeding because that is the decision worth reading:
+ * the alternative reading of an absent tool is "this config is broken", and it
+ * is usually wrong (plugin off, MCP server down).
+ */
+export function formatUnknownToolsWarning(agentName: string, entries: readonly string[]): string {
+  const listed = entries.map((entry) => `"${entry}"`).join(", ");
+  return [
+    `Subagent "${agentName}" asked for tool(s) pi does not currently have: ${listed}.`,
+    "The run proceeds without them — expected while the plugin that provides a tool is off, or its MCP server is disconnected.",
+  ].join(" ");
+}