@pi-archimedes/subagent 2.10.3 → 2.11.0

package/src/agents-parse.test.ts

@@ -0,0 +1,252 @@
+/**
+ * The agent-config **read** path: frontmatter on disk → AgentConfig.
+ *
+ * `discoverAgents()` is pure filesystem (no ExtensionAPI handle, no tool
+ * registry), so this is where a config can be rejected on **lexical** grounds
+ * and nowhere that a name's membership in the tool set could be checked.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { discoverAgents } from "./agents.js";
+
+// Redirect getAgentDir() (and therefore the user agents dir) into a sandbox.
+const testDir = join(tmpdir(), "pi-test-agents-parse");
+process.env.PI_CODING_AGENT_DIR = testDir;
+
+const agentsDir = join(testDir, "agents");
+
+function writeAgent(file: string, frontmatter: string, body = "prompt"): void {
+  mkdirSync(agentsDir, { recursive: true });
+  writeFileSync(
+    join(agentsDir, `${file}.md`),
+    `---\nname: ${file}\ndescription: desc for ${file}\n${frontmatter}---\n${body}\n`,
+    "utf-8",
+  );
+}
+
+/** Discover the named agent from the sandbox user dir. */
+function readAgent(name: string) {
+  return discoverAgents(testDir).find((a) => a.name === name);
+}
+
+describe("agent config read: mcp opt-in", () => {
+  beforeEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("mcp: true is parsed onto the config, not left in extraFields", () => {
+    writeAgent("closed", "tools: read, bash\nmcp: true\n");
+    const agent = readAgent("closed");
+    expect(agent?.mcp).toBe(true);
+    expect(agent?.extraFields ?? {}).not.toHaveProperty("mcp");
+  });
+
+  it("an absent mcp key leaves the config untouched (the closed default needs no key)", () => {
+    writeAgent("quiet", "tools: read, bash\n");
+    const agent = readAgent("quiet");
+    expect(agent?.mcp).toBeUndefined();
+    expect(agent?.extraFields ?? {}).not.toHaveProperty("mcp");
+  });
+
+  it("mcp: false is not an opt-in and is not kept as an unknown field", () => {
+    writeAgent("off", "tools: read\nmcp: false\n");
+    const agent = readAgent("off");
+    expect(agent?.mcp).not.toBe(true);
+    expect(agent?.extraFields ?? {}).not.toHaveProperty("mcp");
+  });
+
+  it("a quoted mcp: \"true\" still means opted in (frontmatter strings survive quoting)", () => {
+    writeAgent("quoted", "tools: read\nmcp: \"true\"\n");
+    expect(readAgent("quoted")?.mcp).toBe(true);
+  });
+
+  it("mcp without a tools allowlist is parsed but changes nothing downstream", () => {
+    writeAgent("noallow", "mcp: true\n");
+    expect(readAgent("noallow")?.mcp).toBe(true);
+  });
+});
+
+// ── The lexical half of validation (ADR 0028) ───────────────────────────────
+//
+// This read path has no tool registry — `discoverAgents()` touches only the
+// filesystem — so nothing here may depend on whether a name is a real tool.
+// A rejected `tools:` list is never applied (an allowlist that silently becomes
+// a wider one is the failure this exists to prevent); the reason rides on the
+// config so dispatch refuses it and the panel can show it.
+
+describe("agent config read: malformed tools entries are rejected", () => {
+  beforeEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("accepts a well-formed list, unchanged", () => {
+    writeAgent("good", "tools: read, bash\n");
+    const agent = readAgent("good");
+    expect(agent?.tools).toEqual(["read", "bash"]);
+    expect(agent?.toolsError).toBeUndefined();
+  });
+
+  it("rejects an empty entry and names it on the config", () => {
+    writeAgent("empty", "tools: read, , bash\n");
+    const agent = readAgent("empty");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toContain('""');
+  });
+
+  it("rejects a trailing comma (the empty entry it creates)", () => {
+    writeAgent("trailing", "tools: read, bash,\n");
+    const agent = readAgent("trailing");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toBeTruthy();
+  });
+
+  it("rejects a duplicated entry and names it", () => {
+    writeAgent("dupe", "tools: read, bash, read\n");
+    const agent = readAgent("dupe");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toContain("read");
+  });
+
+  it("rejects a +name entry and names it", () => {
+    writeAgent("mod", "tools: read, +web_search\n");
+    const agent = readAgent("mod");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toContain("+web_search");
+  });
+
+  it("rejects a -name entry and names it", () => {
+    writeAgent("neg", "tools: read, -bash\n");
+    const agent = readAgent("neg");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toContain("-bash");
+  });
+
+  it("still preserves a rejected list in extraFields, so saving the agent does not delete the user's line", () => {
+    writeAgent("mod2", "tools: read, +web_search\n");
+    const agent = readAgent("mod2");
+    // Preserved verbatim for the writer's benefit; nothing downstream reads
+    // extraFields as a tool list, and dispatch refuses the agent outright.
+    expect(agent?.extraFields?.tools).toBe("read, +web_search");
+  });
+
+  it("the rejection message names the agent and the file it came from", () => {
+    writeAgent("dupe2", "tools: read, read\n");
+    const agent = readAgent("dupe2");
+    expect(agent?.toolsError).toContain("dupe2");
+    expect(agent?.toolsError).toContain(join(agentsDir, "dupe2.md"));
+  });
+
+  it("a rejected tools list does not disturb the rest of the config", () => {
+    writeAgent("mixed", "tools: read, read\nmodel: anthropic/claude-opus-4.5\n", "body text");
+    const agent = readAgent("mixed");
+    expect(agent?.model).toBe("anthropic/claude-opus-4.5");
+    expect(agent?.systemPrompt).toContain("body text");
+    expect(agent?.toolsError).toBeTruthy();
+  });
+
+  it("list_agents says which agents have a rejected tools list", async () => {
+    const { formatAgentList } = await import("./agents.js");
+    writeAgent("broken", "tools: read, +bash\n");
+    writeAgent("fine", "tools: read\n");
+    const out = formatAgentList(discoverAgents(testDir));
+    const brokenLine = out.split("\n").find((l) => l.includes("broken"));
+    const fineLine = out.split("\n").find((l) => l.includes("fine "));
+    expect(brokenLine).toMatch(/invalid tools|tools rejected/i);
+    expect(fineLine).not.toMatch(/invalid tools|tools rejected/i);
+  });
+});
+
+describe("agent config read: `tools:` written as a YAML list", () => {
+  // pi's own frontmatter parser turns both `tools: a, b`-style block lists and
+  // inline lists into real arrays, and a hand-written agent file is far more
+  // likely to use one than the comma form this suite's writer emits. Reading
+  // only the string form meant a list-shaped allowlist was dropped on the floor:
+  // no allowlist, no error, and a child that runs with every tool the host has —
+  // the exact "wider than the config asked for" outcome the read path exists to
+  // prevent (and which a live dispatch reproduced: `tools: [read]` + MCP on).
+  beforeEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("applies a block list as the allowlist", () => {
+    writeAgent("blocky", "tools:\n  - read\n  - bash\nmcp: true\n");
+    const agent = readAgent("blocky");
+    expect(agent?.tools).toEqual(["read", "bash"]);
+    expect(agent?.toolsError).toBeUndefined();
+    // The list is an allowlist, so the MCP opt-in still has to survive next to it.
+    expect(agent?.mcp).toBe(true);
+  });
+
+  it("applies an inline list the same way", () => {
+    writeAgent("inliney", "tools: [read, bash]\n");
+    expect(readAgent("inliney")?.tools).toEqual(["read", "bash"]);
+  });
+
+  it("applies a one-entry list (which YAML reads as a bare string only when written that way)", () => {
+    writeAgent("single", "tools:\n  - read\n");
+    expect(readAgent("single")?.tools).toEqual(["read"]);
+  });
+
+  it("rejects a list entry pi cannot read as a name, and applies nothing", () => {
+    writeAgent("blockbad", "tools:\n  - read\n  - +web_search\n");
+    const agent = readAgent("blockbad");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toContain("+web_search");
+    // Preserved for the writer, same contract as the comma form.
+    expect(agent?.extraFields?.tools).toEqual(["read", "+web_search"]);
+  });
+
+  it("rejects a duplicate inside a list", () => {
+    writeAgent("blockdupe", "tools:\n  - read\n  - read\n");
+    const agent = readAgent("blockdupe");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toContain("read");
+  });
+
+  it("rejects a list entry hiding a modifier behind a comma, naming the modifier", () => {
+    // The child re-splits `--tools` on commas, so this config is `--tools
+    // read,+bash` — which pi rejects outright, dropping the allowlist and
+    // leaving the child with the full default set. Read it as the two entries
+    // the child would see and refuse it here instead.
+    writeAgent("commainner", "tools:\n  - read,+web_search\n");
+    const agent = readAgent("commainner");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toContain("+web_search");
+  });
+
+  it("rejects a list holding something that is not a name at all", () => {
+    writeAgent("mixed", "tools:\n  - read\n  - count: 2\n");
+    const agent = readAgent("mixed");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toBeTruthy();
+  });
+
+  it("rejects a tools value that is neither a list nor a list of names, instead of ignoring it", () => {
+    // `tools: 42` used to be preserved in extraFields and otherwise ignored —
+    // silently unbounded again. A config that means something by the key gets an
+    // error, not a shrug.
+    writeAgent("scalar", "tools: 42\n");
+    const agent = readAgent("scalar");
+    expect(agent?.tools).toBeUndefined();
+    expect(agent?.toolsError).toBeTruthy();
+    expect(agent?.extraFields?.tools).toBe(42);
+  });
+});

package/src/agents.ts

@@ -8,16 +8,49 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { readLocalConfig } from "./local-config.js";
+import { readToolEntries, validateToolEntries } from "./tool-validation.js";
 
 export interface AgentConfig {
   name: string;
   description: string;
   tools?: string[];
+  /**
+   * Opt this agent's child back in to connecting its MCP servers.
+   *
+   * pi 1.0.4 stopped a non-empty `--tools` filtering MCP tools: they stay
+   * registered (reachable from codemode and `tool_search`) unless the list names
+   * an `mcp__` entry (ADR 0028). The suite therefore passes `--no-mcp` alongside
+   * a non-empty allowlist; `mcp: true` is the one way a config asks for the
+   * servers back. Absent or false means the closed reading. Note the honest
+   * limit, verified against a live 1.2.0 child: pi does not *declare* MCP tools
+   * to a model whose allowlist does not match them, so with a non-empty `tools:`
+   * list the child sees the same declared set with or without this flag — what
+   * the flag changes is whether the servers connect at all (ADR 0028
+   * verification note). Parsed in `loadAgentsFromDir`, written by
+   * `serializeAgent`, shown on the `/agents` detail screen.
+   */
+  mcp?: boolean;
   model?: string;
   thinking?: string;
   systemPrompt: string;
   source: "global" | "user" | "project";
   filePath: string;
+  /**
+   * Set when the `tools:` list was **rejected at config read** — an entry pi
+   * cannot read as a tool name (empty, duplicated, containing a comma, or a
+   * `+`/`-` modifier), or a value that is not a tool list in any spelling pi's
+   * YAML parser produces (comma string, block list, inline list) — a number, a
+   * mapping, or a list holding something that is not a name.
+   *
+   * The list is never applied in that case: a rejected allowlist that falls back
+   * to "no allowlist" would hand the child a *wider* tool set than the config
+   * asked for. Dispatch refuses such an agent (naming the entry and the file),
+   * and the `/agents` panel and `list_agents` report it. The raw value stays in
+   * `extraFields.tools` so saving the agent does not silently delete the line; a
+   * list committed through `applyToolEntries` retires both the raw value and this
+   * error, so the fix actually reaches the file.
+   */
+  toolsError?: string;
   // Extra fields preserved from frontmatter but not editable in TUI
   extraFields?: Record<string, unknown>;
 }
@@ -52,11 +85,35 @@ function loadAgentsFromDir(dir: string, source: "global" | "user" | "project"):
 
     // Handle tools specially — preserve non-string values in extraFields
     let parsedTools: string[] | undefined;
-    if (typeof frontmatter.tools === "string") {
-      parsedTools = frontmatter.tools.split(",").map((t: string) => t.trim()).filter(Boolean);
+    let toolsError: string | undefined;
+    if (frontmatter.tools !== undefined) {
+      // Every YAML spelling is read (comma string, block list, inline list);
+      // anything that is not a list of names is rejected loudly rather than
+      // dropped, because an unread allowlist means an unrestricted child.
+      const read = readToolEntries(frontmatter.tools, {
+        agentName: String(frontmatter.name),
+        agentFilePath: filePath,
+      });
+      if ("error" in read) {
+        toolsError = read.error;
+      } else {
+        const check = validateToolEntries(read.entries, {
+          agentName: String(frontmatter.name),
+          agentFilePath: filePath,
+        });
+        if (check.ok) {
+          parsedTools = read.entries;
+        } else {
+          toolsError = check.error;
+        }
+      }
     }
 
-    const knownKeys = new Set(["name", "description", "model", "thinking"]);
+    // `mcp: true` opts the child back in to MCP tools (ADR 0028). Quoted YAML
+    // gives the string "true", which means the same thing to a human reader.
+    const mcpOptIn = frontmatter.mcp === true || frontmatter.mcp === "true";
+
+    const knownKeys = new Set(["name", "description", "model", "thinking", "mcp"]);
     const extraFields: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(frontmatter)) {
       if (key === "tools") continue; // tools is handled separately above/below
@@ -66,7 +123,9 @@ function loadAgentsFromDir(dir: string, source: "global" | "user" | "project"):
         extraFields[key] = value;
       }
     }
-    // If tools was non-string, store it in extraFields for round-trip preservation
+    // If tools was non-string, store it in extraFields for round-trip preservation.
+    // A rejected string list is preserved for the same reason: the writer must not
+    // quietly delete a line the user typed.
     if (frontmatter.tools !== undefined && !parsedTools && "tools" in frontmatter) {
       extraFields.tools = frontmatter.tools;
     }
@@ -80,6 +139,8 @@ function loadAgentsFromDir(dir: string, source: "global" | "user" | "project"):
     };
     if (frontmatter.model) config.model = frontmatter.model as string;
     if (frontmatter.thinking) config.thinking = frontmatter.thinking as string;
+    if (mcpOptIn) config.mcp = true;
+    if (toolsError) config.toolsError = toolsError;
     if (parsedTools && parsedTools.length > 0) config.tools = parsedTools;
     if (Object.keys(extraFields).length > 0) config.extraFields = extraFields;
 
@@ -226,7 +287,13 @@ export function formatAgentList(agents: AgentConfig[]): string {
     let line = `• ${a.name} [${a.source}] — ${a.description}`;
     const extras: string[] = [];
     if (a.model) extras.push(`model: ${a.model}`);
-    if (a.tools && a.tools.length > 0) extras.push(`${a.tools.length} tools`);
+    if (a.toolsError) {
+      // The list was rejected at read, so no allowlist is in force — say so here
+      // rather than letting the agent look like an unconfigured one.
+      extras.push("tools rejected — fix the tools: field");
+    } else if (a.tools && a.tools.length > 0) {
+      extras.push(`${a.tools.length} tools`);
+    }
     if (extras.length > 0) line += ` (${extras.join(", ")})`;
     return line;
   });