@pi-archimedes/subagent 2.10.4 → 2.11.1

package/src/tool-schema.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Issue #114 — the parameter set `subagent` declares is the whole contract, so
+ * every name in it must be a name `execute` actually reads.
+ *
+ * #114 deleted a declared `async` boolean ("Run asynchronously
+ * (fire-and-forget)") that nothing read: a model that passed `async: true` got a
+ * fully synchronous run with no warning. That is a false statement in a
+ * model-facing contract, and worse than a missing feature, because the contract
+ * *is* what the model believes about the tool — it is what gets rendered into
+ * the tool list, what the model plans around, what a wrong answer gets blamed
+ * on. Deleting the claim is the fix; implementing fire-and-forget is out of
+ * scope and blocked on #113 (reaping subagent children across session
+ * replacement).
+ *
+ * The review that followed found a SECOND instance of the same defect class the
+ * issue never named: `count?: number` on the parallel task item, read nowhere.
+ * It differed from `async` in one instructive way: it lived only in the
+ * hand-written `params` type on `execute` in `index.ts`, never in `TaskItem`, so
+ * the JSON Schema the model sees never advertised it and a guard that enumerates
+ * the schema alone could not have caught it. The root cause of both was one
+ * contract stated twice — once for the model, once for TypeScript — with nothing
+ * keeping the two in step. So the fix is structural rather than another
+ * assertion: `SubagentParams` in `tool-schema.ts` is
+ * `Static<typeof SUBAGENT_PARAMS_SCHEMA>` and `execute` takes that, which is the
+ * `ask` / `sudo` precedent. There is no second list left to drift on its own, so
+ * the only low-friction way to introduce a `count` is to say so at one of the
+ * two surfaces a reviewer reads: the schema, or `execute`'s signature.
+ *
+ * What is guarded where, stated honestly:
+ *
+ *   - the schema's declared sets are pinned below, exactly and enumerated from
+ *     the schema object rather than restated;
+ *   - there is no second TS-side list left for a test to police. `tsc` does
+ *     reject a params type that *contradicts* the schema — `model?: number` at
+ *     the params position fails `registerTool`'s `execute` with TS2322 — but
+ *     that check is neither new nor the derivation's doing: `registerTool`
+ *     infers `TParams` from `parameters` and declares `execute`'s `params` as
+ *     `Static<TParams>` (`pi-coding-agent` `dist/core/extensions/types.d.ts:514`),
+ *     so the same TS2322 fires with or without `SubagentParams` (measured against
+ *     the pre-derivation literal, and it failed there too).
+ *   - what `tsc` never caught, and still does not, is the phantom itself. An
+ *     extra *optional* member only widens the params type, and pi declares
+ *     `execute` as a method, so method parameters are bivariant: `count?: number`
+ *     in the old literal, in `TaskItem` inside that literal, and spliced on as
+ *     `params: SubagentParams & { count?: number }` all compile (each measured).
+ *     So the derivation removes the *place* a phantom hid — it does not add a
+ *     compiler check that would catch one. Writing a phantom now takes a
+ *     deliberate `& { … }` at the params position, an edit a reviewer sees, where
+ *     before it was the default way to state the contract.
+ *   - the residual gap, stated against what this branch removed rather than
+ *     against the compiler. The ~370-line source-text scanner deleted in
+ *     `ca1a328` DID catch a declared-and-unread task field: it parsed
+ *     `index.ts` as text, derived the task fields the parallel branch reads
+ *     (`readTaskFields()`) and compared them against
+ *     `declaredTaskItemParams()`, pinning both directions — declared and not
+ *     read, and read and not declared. So type erasure was never what defeated
+ *     that guard: it read the file, and a test over source text does see what
+ *     the body reads. It was deleted for its false-positive cost, not because it
+ *     did not work — it could redden on an unrelated `index.ts` edit (Greptile's
+ *     P2 on PR #143), and that brittleness is why the maintainer took the
+ *     schema-shared-type option instead. Losing it has a real price: on the
+ *     task-item surface a schema field that `execute` declares but ignores is
+ *     once again undetectable here, which is exactly how `async` survived. The
+ *     cheap, non-brittle replacement is a BEHAVIOURAL pin, not a second parser:
+ *     `index.test.ts` ("the object forwarded to the executor") now asserts the
+ *     exact key set handed to `executeParallel` / `executeSubagent`, so dropping
+ *     a forwarded task field — or adding one nobody declared — fails a test. Its
+ *     limit, stated rather than sold: it pins the shape handed over, so a schema
+ *     field that `execute` never forwards at all is invisible to it, and it
+ *     cannot prove the executor reads a key it is handed. That residue is the
+ *     phantom class, and it is genuinely uncovered again. What still covers it is
+ *     the two pins below, a schema small enough to read in one screen — five
+ *     top-level parameters, four task fields — and review.
+ *
+ * If a name reappears here it has to arrive together with the behaviour that
+ * honours it (#113 first, for `async`) and a consumer that reads it; until then
+ * the honest description is the one that does not mention it.
+ */
+
+import { describe, it, expect } from "vitest";
+import { Value } from "typebox/value";
+import { SUBAGENT_PARAMS_SCHEMA } from "./tool-schema.js";
+
+/** Read a schema node's declared property names, failing loudly if it has none. */
+function propertyNames(node: unknown, what: string): string[] {
+  const properties = (node as { properties?: Record<string, unknown> }).properties;
+  if (!properties) throw new Error(`${what} declares no properties`);
+  return Object.keys(properties);
+}
+
+/** The top-level parameters `subagent` declares. Read from the schema, never restated. */
+function declaredParams(): string[] {
+  return propertyNames(SUBAGENT_PARAMS_SCHEMA, "SUBAGENT_PARAMS_SCHEMA");
+}
+
+/**
+ * The properties declared for ONE entry of the `tasks` array — `TaskItem`.
+ * Reached through the schema rather than exported from `tool-schema.ts`, so the
+ * guard depends on the contract the model actually receives and the module
+ * keeps its current public surface (`TaskItem` is deliberately unexported).
+ */
+function declaredTaskItemParams(): string[] {
+  const tasks = (SUBAGENT_PARAMS_SCHEMA as { properties?: Record<string, unknown> }).properties?.tasks;
+  if (!tasks) throw new Error("SUBAGENT_PARAMS_SCHEMA declares no `tasks` property");
+  const items = (tasks as { items?: unknown }).items;
+  if (!items) throw new Error("`tasks` is not an array schema — no item schema to enumerate");
+  return propertyNames(items, "The `tasks` item schema (TaskItem)");
+}
+
+describe("SUBAGENT_PARAMS_SCHEMA — declared parameter set (issue #114)", () => {
+  it("pins the five declared parameters", () => {
+    // Exact and sorted, so it fails in BOTH directions: adding a name the pin
+    // does not know (`async` would) and deleting one of the five. Read from the
+    // schema object, never restated by hand. And because `SubagentParams` is
+    // derived, adding a name here is also adding it to what `execute` is handed,
+    // so this pin is where a new name has to be justified. What it does NOT
+    // check is whether anything reads the name — that cross-surface claim
+    // belonged to the scanner described in the header and no longer exists, so
+    // the name says only what the body proves.
+    expect([...declaredParams()].sort()).toEqual(["agent", "cwd", "model", "task", "tasks"]);
+  });
+});
+
+describe("TaskItem — declared parallel task item (issue #114, second instance: `count`)", () => {
+  it("pins the four declared task-item properties", () => {
+    // `count` was the proof this surface needs its own pin: a phantom can be
+    // added to the task item while the top-level set above stays green. Like the
+    // pin above this one enumerates the SCHEMA only — with the scanner gone
+    // nothing here compares the four against what the parallel branch reads, so
+    // the name claims the enumeration and no more.
+    expect([...declaredTaskItemParams()].sort()).toEqual(["agent", "cwd", "model", "task"]);
+  });
+});
+
+// Legacy-caller compatibility check — a real behavioural guarantee, so it is
+// pinned rather than assumed. TypeBox `Type.Object` does not set
+// `additionalProperties: false`, so deleting `async` — and deleting `count` from
+// the TS type, which the schema never advertised anyway — stops promising the
+// option without turning an existing caller's payload into a validation error: a
+// caller still passing `async: true`, or a `count` on a task, keeps validating, it
+// just no longer gets a promise about it. That is what makes both deletions safe
+// to land in a patch release, and it is the one thing here that fails on its own
+// if anyone ever tightens the schema with `additionalProperties: false`.
+describe("SUBAGENT_PARAMS_SCHEMA — legacy callers passing the deleted fields still validate", () => {
+  it("accepts a payload carrying `async`", () => {
+    expect(Value.Check(SUBAGENT_PARAMS_SCHEMA as never, { task: "x", async: true })).toBe(true);
+  });
+
+  it("accepts a task item carrying `count`", () => {
+    expect(
+      Value.Check(SUBAGENT_PARAMS_SCHEMA as never, { tasks: [{ task: "x", count: 1 }] }),
+    ).toBe(true);
+  });
+});

package/src/tool-schema.ts

@@ -1,4 +1,5 @@
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
+import type { SubagentResult, SubagentRunReport } from "./types.js";
 
 // ── JSON Schema for tool parameters (TypeBox) ──────────────────────────────
 
@@ -24,10 +25,111 @@ export const SUBAGENT_PARAMS_SCHEMA = Type.Object({
   model: Type.Optional(Type.String({
     description: "Model override for the subagent",
   })),
-  async: Type.Optional(Type.Boolean({
-    description: "Run asynchronously (fire-and-forget)",
-  })),
   cwd: Type.Optional(Type.String({
     description: "Working directory for the subagent",
   })),
 });
+
+/**
+ * What `execute` is handed, derived from the schema rather than written out —
+ * the `ask` / `sudo` precedent (`AskParams`, `SudoExecInput`).
+ *
+ * #114's two phantoms were only possible because one contract was stated twice,
+ * independently: `async` in this schema, `count?: number` in the hand-written
+ * `params` type in `index.ts`. Nothing kept the two in step, and only one of them
+ * is what the model sees. Stating the contract once removes the second list: the
+ * schema is now the only *default* source of a name in `execute`'s declared
+ * params type — see the caveat below, which is the whole difference between
+ * "only default" and "only".
+ *
+ * That is a structural fix, not a check. It does not stop anyone reading a
+ * declared field, and it does not make a phantom a compile error — `execute` is
+ * declared as a method, so bivariant parameters accept a widening `& { … }` at
+ * the params position. See the header of `tool-schema.test.ts` for what is
+ * enforced where, measured.
+ */
+export type SubagentParams = Static<typeof SUBAGENT_PARAMS_SCHEMA>;
+
+// ── 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);
+  });
+});