@selesai/code 0.13.15 → 0.13.18

package/dist/extensions/pi-subagents/test/unit/advertised-agent-prompt.test.ts

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { appendAdvertisedAgentPrompt, buildAdvertisedAgentPrompt } from "../../src/agents/advertised-agent-prompt.ts";
+import type { AgentConfig } from "../../src/agents/agents.ts";
+
+function agent(name: string, overrides: Partial<AgentConfig> = {}): AgentConfig {
+	return {
+		name,
+		description: `${name} agent`,
+		systemPrompt: `${name} prompt`,
+		systemPromptMode: "replace",
+		inheritProjectContext: false,
+		inheritSkills: false,
+		source: "project",
+		filePath: `/tmp/${name}.md`,
+		...overrides,
+	};
+}
+
+describe("advertised agent prompt", () => {
+	it("includes only opted-in, capability-permitted agents in stable order", () => {
+		const prompt = buildAdvertisedAgentPrompt([
+			agent("zeta", { advertise: true }),
+			agent("hidden"),
+			agent("disabled", { advertise: true, disabled: true }),
+			agent("alpha", { advertise: true }),
+		], {
+			version: 1,
+			allowedAgents: ["alpha", "hidden", "zeta"],
+			denyExtensions: false,
+			sources: ["test"],
+		});
+
+		assert.ok(prompt);
+		assert.match(prompt, /<name>alpha<\/name>/);
+		assert.match(prompt, /<name>zeta<\/name>/);
+		assert.doesNotMatch(prompt, /hidden|disabled/);
+		assert.ok(prompt.indexOf("alpha") < prompt.indexOf("zeta"));
+	});
+
+	it("escapes agent-owned metadata and bounds the catalog", () => {
+		const agents = Array.from({ length: 18 }, (_, index) => agent(`agent-${String(index).padStart(2, "0")}`, {
+			advertise: true,
+			description: index === 0 ? `<route>&${"x".repeat(700)}` : `agent ${index}`,
+		}));
+		const prompt = buildAdvertisedAgentPrompt(agents);
+
+		assert.ok(prompt);
+		assert.match(prompt, /&lt;route&gt;&amp;/);
+		assert.doesNotMatch(prompt, /<route>/);
+		assert.match(prompt, /…<\/description>/);
+		assert.match(prompt, /<omitted count="2" \/>/);
+	});
+
+	it("replaces an existing catalog instead of duplicating it", () => {
+		const first = buildAdvertisedAgentPrompt([agent("alpha", { advertise: true })]);
+		const second = buildAdvertisedAgentPrompt([agent("beta", { advertise: true })]);
+		assert.ok(first);
+		assert.ok(second);
+
+		const systemPrompt = appendAdvertisedAgentPrompt(appendAdvertisedAgentPrompt("base prompt", first), second);
+		assert.equal(systemPrompt.match(/<advertised_subagents>/gu)?.length, 1);
+		assert.doesNotMatch(systemPrompt, /<name>alpha<\/name>/);
+		assert.match(systemPrompt, /<name>beta<\/name>/);
+	});
+
+	it("returns no catalog when no agent opts in", () => {
+		assert.equal(buildAdvertisedAgentPrompt([agent("hidden")]), undefined);
+		assert.equal(appendAdvertisedAgentPrompt("base prompt\n\n", undefined), "base prompt\n\n");
+	});
+
+	it("admits an exact-budget canonical name and omits it one byte over", () => {
+		const emptyName = buildAdvertisedAgentPrompt([agent("", { advertise: true, description: "small" })])!;
+		const name = "x".repeat(12_288 - Buffer.byteLength(emptyName));
+		const exact = buildAdvertisedAgentPrompt([agent(name, { advertise: true, description: "small" })])!;
+		assert.equal(Buffer.byteLength(exact), 12_288);
+		assert.ok(exact.includes(`<name>${name}</name>`));
+		const over = buildAdvertisedAgentPrompt([agent(`${name}x`, { advertise: true, description: "small" })])!;
+		assert.doesNotMatch(over, /<name>/);
+		assert.match(over, /<omitted count="1"/);
+	});
+
+	it("withdraws a reused catalog when the last advertised agent disappears", () => {
+		const prior = appendAdvertisedAgentPrompt("base prompt", buildAdvertisedAgentPrompt([agent("alpha", { advertise: true })]));
+		assert.equal(appendAdvertisedAgentPrompt(prior, buildAdvertisedAgentPrompt([])), "base prompt");
+	});
+});

package/dist/extensions/pi-subagents/test/unit/advertised-agent-refresh.test.ts

@@ -0,0 +1,163 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { it } from "node:test";
+import { SUBAGENT_CHILD_ENV } from "../../src/runs/shared/child-runtime-config.ts";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+it("emits bounded file-only snapshots, refreshes through management, and performs zero prompt-time filesystem calls", () => {
+	const home = fs.mkdtempSync(path.join(os.tmpdir(), "advertised-refresh-"));
+	const env = { ...process.env, SELESAI_CODING_AGENT_DIR: home };
+	delete env[SUBAGENT_CHILD_ENV];
+	try {
+		const output = execFileSync(process.execPath, ["--experimental-strip-types", "--import", "./test/support/register-loader.mjs", "--input-type=module", "--eval", String.raw`
+			import assert from "node:assert/strict";
+			import fs from "node:fs";
+			import path from "node:path";
+			import { syncBuiltinESMExports } from "node:module";
+			import register from "./src/extension/index.ts";
+			import { registerSubagentCapabilityCeiling } from "./src/runs/shared/capability-ceiling.ts";
+			const home = process.env.SELESAI_CODING_AGENT_DIR;
+			const cwd = path.join(home, "project");
+			fs.mkdirSync(path.join(cwd, ".selesai"), { recursive: true });
+			const dir = path.join(home, "agents");
+			fs.mkdirSync(dir);
+			const write = (file, name, description, advertise = true) => fs.writeFileSync(path.join(dir, file + ".md"),
+				"---\nname: " + name + "\ndescription: " + description + "\nadvertise: " + advertise + "\n---\nAct narrowly.\n");
+			const handlers = new Map();
+			let tool;
+			let activeTools = ["subagent"];
+			const pi = new Proxy({
+				events: { on() { return () => {}; }, emit() {} },
+				on(event, handler) { handlers.set(event, [...(handlers.get(event) ?? []), handler]); },
+				registerTool(value) { if (value.name === "subagent") tool = value; },
+				getActiveTools() { return activeTools; },
+			}, { get(target, key) { return key in target ? target[key] : () => undefined; } });
+			register(pi);
+			const ctx = {
+				cwd, hasUI: false, model: { provider: "test", id: "test" },
+				modelRegistry: { getAvailable() { return []; }, getAll() { return []; } },
+				sessionManager: { getSessionId() { return "advertised-test"; }, getSessionFile() { return undefined; }, getBranch() { return []; } },
+			};
+			// Invoke the registered catalog lifecycle hook; unrelated host services are not started by this harness.
+			const refresh = (reason = "reload") => handlers.get("session_start").at(-1)({ reason }, ctx);
+			const emit = (systemPrompt = "base", selectedTools = activeTools) => {
+				const result = handlers.get("before_agent_start").at(-1)({ systemPrompt, systemPromptOptions: { selectedTools: selectedTools ?? undefined } }, ctx);
+				return result?.systemPrompt ?? systemPrompt;
+			};
+			const io = { statSync: 0, readdirSync: 0, readFileSync: 0 };
+			const originals = {};
+			for (const key of Object.keys(io)) {
+				originals[key] = fs[key];
+				fs[key] = (...args) => { io[key]++; return originals[key](...args); };
+			}
+			syncBuiltinESMExports();
+			const noIo = (fn) => {
+				const before = { ...io };
+				const result = fn();
+				assert.deepEqual(io, before, "prompt emission must not stat, readdir, or read files");
+				return result;
+			};
+			refresh("startup");
+			noIo(() => { for (let i = 0; i < 20; i++) assert.equal(emit(), "base"); });
+			for (let i = 0; i < 250; i++) write("hidden-" + i, "hidden-" + i, "hidden", false);
+			refresh();
+			noIo(() => { for (let i = 0; i < 20; i++) assert.equal(emit(), "base"); });
+			write("specialist", "specialist", "Original specialist");
+			assert.equal(noIo(() => emit()), "base", "external edits wait for reload");
+			refresh();
+			let prompt = noIo(() => emit());
+			assert.match(prompt, /<name>specialist<\/name>/);
+			assert.doesNotMatch(prompt, /hidden-/);
+			assert.match(prompt, /Before execution.*action: "list", capabilities: true/);
+			assert.equal(noIo(() => emit(prompt, ["read"])), "base");
+			activeTools = ["read"];
+			assert.equal(noIo(() => emit(prompt, null)), "base");
+			activeTools = ["subagent"];
+			const ceiling = registerSubagentCapabilityCeiling({ sessionId: "advertised-test", source: "test", ceiling: { allowedAgents: [] } });
+			assert.equal(noIo(() => emit(prompt)), "base");
+			ceiling.dispose();
+			assert.match(noIo(() => emit()), /Original specialist/);
+			const manage = async (params) => tool.execute("manage", params, new AbortController().signal, undefined, ctx);
+			write("pending", "pending", "External change awaiting refresh");
+			await manage({ action: "get", agent: "specialist" });
+			assert.doesNotMatch(noIo(() => emit()), /<name>pending<\/name>/, "reads must not refresh");
+			await assert.rejects(manage({ action: "update", agent: "specialist", config: { advertise: "invalid" } }), /config.advertise must be a boolean/);
+			assert.doesNotMatch(noIo(() => emit()), /<name>pending<\/name>/, "failed mutations must not refresh");
+			fs.unlinkSync(path.join(dir, "pending.md"));
+			let result = await manage({ action: "update", agent: "specialist", config: { description: "Updated specialist" } });
+			assert.notEqual(result.isError, true, JSON.stringify(result));
+			assert.match(noIo(() => emit(prompt)), /Updated specialist/);
+			assert.match(fs.readFileSync(path.join(dir, "specialist.md"), "utf8"), /advertise: true/);
+			result = await manage({ action: "disable", agent: "specialist", agentScope: "user" });
+			assert.notEqual(result.isError, true, JSON.stringify(result));
+			assert.equal(noIo(() => emit(prompt)), "base");
+			result = await manage({ action: "enable", agent: "specialist", agentScope: "user" });
+			assert.notEqual(result.isError, true, JSON.stringify(result));
+			prompt = noIo(() => emit());
+			assert.match(prompt, /Updated specialist/);
+			result = await manage({ action: "delete", agent: "specialist", agentScope: "user" });
+			assert.notEqual(result.isError, true, JSON.stringify(result));
+			assert.equal(noIo(() => emit(prompt)), "base");
+			result = await manage({ action: "create", config: { name: "created", description: "Created specialist", systemPrompt: "Act narrowly.", scope: "user", advertise: true } });
+			assert.notEqual(result.isError, true, JSON.stringify(result));
+			assert.match(noIo(() => emit()), /<name>created<\/name>/);
+			result = await manage({ action: "update", agent: "created", config: { name: "renamed" } });
+			assert.notEqual(result.isError, true, JSON.stringify(result));
+			prompt = noIo(() => emit());
+			assert.match(prompt, /<name>renamed<\/name>/);
+			assert.doesNotMatch(prompt, /<name>created<\/name>/);
+			result = await manage({ action: "update", agent: "renamed", config: { advertise: false } });
+			assert.notEqual(result.isError, true, JSON.stringify(result));
+			assert.equal(noIo(() => emit(prompt)), "base");
+			// Inject a refresh-only read failure after the management file write has succeeded.
+			await manage({ action: "update", agent: "renamed", config: { advertise: true } });
+			prompt = noIo(() => emit());
+			assert.match(prompt, /<name>renamed<\/name>/);
+			const writeFile = fs.writeFileSync;
+			fs.writeFileSync = (file, ...args) => {
+				const result = writeFile(file, ...args);
+				if (String(file).endsWith("renamed.md")) writeFile(path.join(home, "settings.json"), "{");
+				return result;
+			};
+			syncBuiltinESMExports();
+			result = await manage({ action: "update", agent: "renamed", config: { description: "Persisted despite refresh failure" } });
+			assert.notEqual(result.isError, true, "refresh failure must not change the persisted mutation result");
+			assert.match(fs.readFileSync(path.join(dir, "renamed.md"), "utf8"), /advertise: true/);
+			assert.equal(noIo(() => emit(prompt)), "base", "failed refresh withdraws stale guidance");
+			assert.throws(() => refresh(), /Failed to parse settings file/, "reload discovery errors must reach the host");
+			fs.writeFileSync = writeFile;
+			syncBuiltinESMExports();
+			fs.unlinkSync(path.join(home, "settings.json"));
+			refresh();
+			assert.match(noIo(() => emit()), /<name>renamed<\/name>/);
+			await manage({ action: "delete", agent: "renamed", agentScope: "user" });
+			write("huge", "a".repeat(100000), "huge name");
+			write("escaped-name", "b" + "&".repeat(4000), "escaped huge name");
+			for (let i = 0; i < 25; i++) write("opt-" + i, "pkg.opt-" + i, i % 2 ? '<>&"'.repeat(300) : "🦜界".repeat(300));
+			refresh();
+			prompt = noIo(() => { let result; for (let i = 0; i < 20; i++) result = emit(); return result; });
+			const catalog = prompt.slice(prompt.indexOf("<advertised_subagents>"));
+			assert.ok(Buffer.byteLength(catalog) <= 12288);
+			assert.doesNotMatch(catalog, /<name>[ab]/);
+			assert.match(catalog, /&lt;&gt;&amp;&quot;/);
+			assert.match(catalog, /not instructions to delegate/);
+			assert.match(catalog, /🦜界/);
+			assert.doesNotMatch(catalog, /�/);
+			assert.match(catalog, /<name>pkg\.opt-\d+<\/name>/);
+			assert.match(catalog, /<omitted count="\d+"/);
+			for (const file of fs.readdirSync(dir)) fs.unlinkSync(path.join(dir, file));
+			assert.equal(noIo(() => emit()), prompt, "external removal waits for reload");
+			refresh();
+			assert.equal(noIo(() => emit(prompt)), "base");
+			process.stdout.write("prompt contracts passed; zero prompt-time stat/readdir/readFile calls at 0, 250, and 277 definitions");
+		`], { cwd: root, env, encoding: "utf8", timeout: 60_000 });
+		assert.match(output, /prompt contracts passed/);
+	} finally {
+		fs.rmSync(home, { recursive: true, force: true });
+	}
+});

package/dist/extensions/pi-subagents/test/unit/agent-frontmatter.test.ts

@@ -9,7 +9,8 @@ import { serializeAgent } from "../../src/agents/agent-serializer.ts";
 import { parseChain, serializeChain } from "../../src/agents/chain-serializer.ts";
 import { discoverAgents, discoverAgentsAll, inspectAgentDefinitionDirectory, type AgentConfig } from "../../src/agents/agents.ts";
 import { parseFrontmatter } from "../../src/agents/frontmatter.ts";
-import { buildPiArgs } from "../../src/runs/shared/pi-args.ts";
+import { buildInProcessChildLaunch } from "../../src/runs/shared/child-launch.ts";
+import { applyThinkingSuffix } from "../../src/runs/shared/child-tool-plan.ts";
 import { THINKING_LEVELS } from "../../src/shared/model-info.ts";
 
 const tempDirs: string[] = [];
@@ -384,6 +385,31 @@ body`);
 	}));
 });
 
+describe("agent advertise frontmatter", () => {
+	it("parses and serializes explicit prompt advertisement", () => withTempHome(() => {
+		const project = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-advertised-agent-"));
+		tempDirs.push(project);
+		writeAgent(path.join(project, ".selesai", "agents", "worker.md"), `---
+name: worker
+description: Worker
+advertise: true
+---
+body`);
+
+		const worker = discoverAgents(project, "both").agents.find((agent) => agent.name === "worker")!;
+		assert.equal(worker.advertise, true);
+		assert.match(serializeAgent(worker), /^advertise: true$/m);
+	}));
+
+	it("rejects non-boolean advertise values", () => withTempHome(() => {
+		const project = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-invalid-advertise-"));
+		tempDirs.push(project);
+		writeAgent(path.join(project, ".selesai", "agents", "worker.md"), "---\nname: worker\ndescription: Worker\nadvertise: yes\n---\nbody");
+
+		assert.match(discoverAgents(project, "project").agentDiagnostics?.[0]?.error ?? "", /invalid advertise frontmatter; expected true or false/);
+	}));
+});
+
 describe("agent aliases", () => {
 	it("parses and serializes agent aliases", () => withTempHome(() => {
 		const project = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-alias-agent-"));
@@ -1037,7 +1063,7 @@ Review nested project work.
 		assert.equal(agent.filePath, path.join(packageRoot, "agents", "reviewer.md"));
 	}));
 
-	it("keeps nearest project root discovery by default when a nested .selesai exists", () => withTempHome(() => {
+	it("keeps nearest project root discovery by default when a nested .pi exists", () => withTempHome(() => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-nearest-root-default-"));
 		tempDirs.push(dir);
 		const nested = path.join(dir, "packages", "app", "src");
@@ -1103,7 +1129,7 @@ Plan outer project work.
 		assert.equal(reviewer?.override?.path, path.join(dir, ".selesai", "settings.json"));
 	}));
 
-	it("keeps git-root discovery stable when a nested linked worktree creates incidental .selesai state", () => withTempHome(() => {
+	it("keeps git-root discovery stable when a nested linked worktree creates incidental .pi state", () => withTempHome(() => {
 		const { repo, worktree } = createNestedLinkedWorktree();
 		const { packageAgentName, packageAgentPath, settingsPath } = writeLinkedWorktreePackage(repo);
 
@@ -1514,19 +1540,19 @@ Do work
 			assert.ok(agent);
 			assert.equal(agent.thinking, false);
 
-			const { args } = buildPiArgs({
-				baseArgs: ["-p"],
-				task: "hello",
+			const { session } = buildInProcessChildLaunch({
+				host: "parent",
+				cwd: dir,
 				sessionEnabled: false,
-				model: agent.model,
-				thinking: agent.thinking,
+				model: applyThinkingSuffix(agent.model, agent.thinking),
 				inheritProjectContext: agent.inheritProjectContext,
+				inheritGlobalContext: agent.inheritGlobalContext,
 				inheritSkills: agent.inheritSkills,
+				childAgentName: agent.name,
+				childIndex: 0,
 			});
 
-			assert.ok(args.includes("--model"));
-			assert.ok(args.includes("glm-5.2-short-fast"));
-			assert.ok(!args.some((arg) => arg.includes(":false")));
+			assert.equal(session.model, "glm-5.2-short-fast");
 		}
 	});
 
@@ -1769,26 +1795,22 @@ Do work
 	});
 
 	it("adds the fast extension only for allowlisted native models", () => {
-		const allowed = buildPiArgs({
-			baseArgs: ["-p"],
-			task: "hello",
+		const launch = {
+			host: "parent" as const,
+			cwd: process.cwd(),
 			sessionEnabled: false,
-			model: "openai-codex/gpt-5.6-luna:low",
-			fast: true,
 			inheritProjectContext: false,
+			inheritGlobalContext: false,
 			inheritSkills: false,
-		});
-
-		assert.ok(allowed.args.some((arg) => arg.endsWith("fast-mode-extension.ts")));
-		assert.throws(() => buildPiArgs({
-			baseArgs: ["-p"],
-			task: "hello",
-			sessionEnabled: false,
-			model: "anthropic/claude-sonnet-4",
+			childAgentName: "worker",
+			childIndex: 0,
 			fast: true,
-			inheritProjectContext: false,
-			inheritSkills: false,
-		}), /fast mode supports only/);
+		};
+		const allowed = buildInProcessChildLaunch({ ...launch, model: "openai-codex/gpt-5.6-luna:low" });
+
+		assert.ok(allowed.toolPlan.runtimeExtensions.some((extensionPath) => extensionPath.endsWith("fast-mode-extension.ts")));
+		assert.deepEqual(allowed.session.hooks.map((hook) => hook.name), ["pi-subagents:prompt-runtime", "pi-subagents:fast-mode"]);
+		assert.throws(() => buildInProcessChildLaunch({ ...launch, model: "anthropic/claude-sonnet-4" }), /fast mode supports only/);
 	});
 });
 
@@ -1865,7 +1887,7 @@ Do work
 		}
 	});
 
-	it("worker and delegate include the child-facing supervisor tool", () => {
+	it("bundled standard agents keep bounded tool allowlists", () => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-supervisor-tool-"));
 		const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-supervisor-tool-home-"));
 		tempDirs.push(dir);
@@ -1877,11 +1899,28 @@ Do work
 			process.env.HOME = homeDir;
 			process.env.USERPROFILE = homeDir;
 			const agents = discoverAgentsAll(dir).builtin;
-			for (const name of ["worker", "delegate"]) {
+			const expectedTools = {
+				worker: ["read", "grep", "find", "ls", "bash", "edit", "write", "contact_supervisor"],
+				delegate: ["read", "grep", "find", "ls", "bash", "edit", "write", "contact_supervisor"],
+				reviewer: ["read", "grep", "find", "ls", "contact_supervisor"],
+				scout: ["read", "grep", "find", "ls", "bash", "write", "contact_supervisor"],
+				researcher: ["read", "write", "web_search", "fetch_content", "get_search_content", "source_check"],
+			};
+			for (const [name, tools] of Object.entries(expectedTools)) {
 				const agent = agents.find((candidate) => candidate.name === name);
 				assert.ok(agent, `${name} builtin should be discovered`);
-				assert.deepEqual(agent?.tools, ["read", "grep", "find", "ls", "bash", "edit", "write", "contact_supervisor"]);
+				assert.deepEqual(agent?.tools, tools);
 			}
+
+			const researcherPrompt = agents.find((candidate) => candidate.name === "researcher")?.systemPrompt ?? "";
+			assert.match(researcherPrompt, /search-result summaries as discovery aids, not final evidence/);
+			assert.match(researcherPrompt, /source_check.*decision-critical or disputed claims/);
+			assert.match(researcherPrompt, /direct evidence, source interpretation, and researcher inference distinctly/);
+			assert.match(researcherPrompt, /Record contradictions.*Record missing evidence/);
+			assert.match(researcherPrompt, /Never invent dates, quotations, citations, or unsupported precision/);
+			assert.match(researcherPrompt, /`source_check` must be registered by the loaded provider before launch/);
+			assert.match(researcherPrompt, /If a registered `source_check` call fails, continue/);
+			assert.match(researcherPrompt, /\*\*Support:\*\* direct evidence \| interpretation\. \*\*Confidence:\*\* high \| medium \| low/);
 		} finally {
 			if (previousHome === undefined) delete process.env.HOME;
 			else process.env.HOME = previousHome;
@@ -2321,4 +2360,4 @@ Inspect project
 			else process.env.USERPROFILE = oldUserProfile;
 		}
 	});
-});
+});

package/dist/extensions/pi-subagents/test/unit/agent-management.test.ts

@@ -109,6 +109,81 @@ describe("agent management config parsing", () => {
 		assert.equal(JSON.stringify(capabilities).includes("SYSTEM_PROMPT_SENTINEL"), false);
 	});
 
+	it("reports bundled reviewer supervisor contact without mutation tools in capabilities", () => {
+		const listed = handleManagementAction("list", { agentScope: "project", capabilities: true }, {
+			cwd: tempDir,
+			modelRegistry: { getAvailable: () => [] },
+		});
+
+		assert.equal(listed.isError, false);
+		const capabilities = listed.details?.agentCapabilities;
+		assert.ok(capabilities);
+		const reviewer = capabilities.agents.find((agent) => agent.name === "reviewer");
+		assert.ok(reviewer, "reviewer builtin should be present in capability output");
+		assert.deepEqual(reviewer.tools.names, ["read", "grep", "find", "ls", "contact_supervisor"]);
+		assert.match(readText(listed), /Tools: read, grep, find, ls, contact_supervisor/);
+	});
+
+	it("reports passive external CLI availability for present and absent commands", () => {
+		const agentsDir = path.join(tempDir, ".selesai", "agents");
+		fs.mkdirSync(agentsDir, { recursive: true });
+		const presentCommand = path.basename(process.execPath, path.extname(process.execPath));
+		fs.writeFileSync(path.join(agentsDir, "present-external.md"), `---
+name: present-external
+description: Present external CLI
+runner:
+  type: external-cli
+  command: ${presentCommand}
+---
+Present.
+`);
+		fs.writeFileSync(path.join(agentsDir, "missing-external.md"), `---
+name: missing-external
+description: Missing external CLI
+runner:
+  type: external-cli
+  command: missing-external-cli
+---
+Missing.
+`);
+		const previousPath = process.env.PATH;
+		try {
+			process.env.PATH = path.dirname(process.execPath);
+			const listed = handleManagementAction("list", { agentScope: "project", capabilities: true }, {
+				cwd: tempDir,
+				modelRegistry: { getAvailable: () => [] },
+			});
+			assert.equal(listed.isError, false);
+			const text = readText(listed);
+			assert.match(text, new RegExp(`external-cli:${presentCommand} ✓`));
+			assert.match(text, /external-cli:missing-external-cli missing/);
+
+			const rows = listed.details?.agentCapabilities?.agents;
+			assert.ok(rows);
+			const present = rows.find((agent) => agent.name === "present-external");
+			const missing = rows.find((agent) => agent.name === "missing-external");
+			assert.ok(present);
+			assert.ok(missing);
+			assert.equal(present.executable, true);
+			assert.equal(missing.executable, true);
+			assert.equal(present.runner.type, "external-cli");
+			assert.equal(missing.runner.type, "external-cli");
+			if (present.runner.type !== "external-cli" || missing.runner.type !== "external-cli") return;
+			assert.equal(present.runner.command, presentCommand);
+			assert.equal(present.runner.available, true);
+			assert.equal("unavailableReason" in present.runner, false);
+			assert.equal(missing.runner.command, "missing-external-cli");
+			assert.equal(missing.runner.available, false);
+			assert.match(missing.runner.unavailableReason ?? "", /External CLI binary 'missing-external-cli' was not found on PATH\./);
+			assert.ok((missing.runner.unavailableReason ?? "").length <= 256);
+		} finally {
+			if (previousPath === undefined) delete process.env.PATH;
+			else process.env.PATH = previousPath;
+		}
+	});
+
+
+
 	it("lists valid agents and diagnoses malformed agent definitions", () => {
 		const agentsDir = path.join(tempDir, ".selesai", "agents");
 		fs.mkdirSync(agentsDir, { recursive: true });
@@ -343,7 +418,7 @@ Advise only.
 		assert.match(readText(result), /Agent 'foo' has invalid configuration: Agent 'foo' package is invalid after sanitization/);
 	});
 
-	it("blocks a malformed .selesai agent from falling back to a legacy project agent", () => {
+	it("blocks a malformed .pi agent from falling back to a legacy project agent", () => {
 		const canonicalAgentsDir = path.join(tempDir, ".selesai", "agents");
 		const legacyAgentsDir = path.join(tempDir, ".agents");
 		fs.mkdirSync(canonicalAgentsDir, { recursive: true });
@@ -1326,7 +1401,7 @@ Drive the failing test first.
 		assert.match(text, /Source: project override/);
 		assert.match(text, /Requested model setting:\n  claude-sonnet-4/);
 		assert.match(text, /Disabled: true/);
-		assert.match(text.replaceAll("\\", "/"), /Override file:\n  .*\.selesai[\\/]settings\.json/);
+		assert.match(text.replaceAll("\\", "/"), /Override file:\n  .*\.selesai\/settings\.json/);
 	});
 
 	it("rejects unknown agents for runtime model mappings", () => {
@@ -1405,4 +1480,4 @@ Inspect cleanup.
 		assert.doesNotMatch(readText(listed), /Proactive skill subagent suggestions:/);
 	});
 
-});
+});

package/dist/extensions/pi-subagents/test/unit/agent-overrides.test.ts

@@ -113,7 +113,7 @@ describe("builtin agent overrides", () => {
 
 		const builtins = discoverAgentsAll(tempProject).builtin;
 		assert.equal(builtins.find((agent) => agent.name === "researcher")?.tools, undefined);
-		assert.deepEqual(builtins.find((agent) => agent.name === "reviewer")?.tools, ["read", "grep", "find", "ls"]);
+		assert.deepEqual(builtins.find((agent) => agent.name === "reviewer")?.tools, ["read", "grep", "find", "ls", "contact_supervisor"]);
 	});
 
 	it("keeps explicit empty builtin tool allowlists distinct from inherited tools", () => {
@@ -719,7 +719,6 @@ describe("builtin agent overrides", () => {
 	it("agentOverrides replace frontmatter for a shadowing project agent", () => {
 		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
 		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
-
 			subagents: { agentOverrides: { reviewer: { model: "openai/gpt-5.4" } } },
 		});
 		writeProjectAgent(tempProject, "reviewer", `---\nname: reviewer\ndescription: Project reviewer\nmodel: google/gemini-3-pro\n---\n\nUse the project reviewer.\n`);
@@ -734,7 +733,6 @@ describe("builtin agent overrides", () => {
 	it("applies project agentOverrides to a custom project agent", () => {
 		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
 		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
-
 			subagents: {
 				agentOverrides: {
 					implementer: {
@@ -786,7 +784,6 @@ describe("builtin agent overrides", () => {
 
 	it("applies user agentOverrides to a custom user agent", () => {
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
-
 			subagents: { agentOverrides: { implementer: { model: "anthropic/claude-sonnet-4-6" } } },
 		});
 		writeUserAgent(tempHome, "implementer", `---\nname: implementer\ndescription: TDD implementer\n---\n\nDrive the failing test first.\n`);
@@ -832,7 +829,6 @@ describe("builtin agent overrides", () => {
 	it("agentOverrides replace explicit custom frontmatter fields", () => {
 		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
 		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
-
 			subagents: {
 				agentOverrides: {
 					implementer: {
@@ -877,7 +873,6 @@ describe("builtin agent overrides", () => {
 	it("lets false overrides clear explicit output and defaultReads frontmatter", () => {
 		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
 		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
-
 			subagents: { agentOverrides: { implementer: { output: false, defaultReads: false } } },
 		});
 		writeProjectAgent(tempProject, "implementer", `---\nname: implementer\ndescription: TDD implementer\noutput: explicit.md\ndefaultReads: explicit.md\n---\n\nDrive the failing test first.\n`);
@@ -1058,7 +1053,6 @@ describe("builtin agent overrides", () => {
 		writeJson(path.join(packageRoot, "package.json"), { "pi-subagents": { agents: ["agents"] } });
 		fs.writeFileSync(path.join(packageRoot, "agents", "package-scout.md"), `---\nname: package-scout\ndescription: Package scout\noutput: package-frontmatter.md\ndefaultReads: PACKAGE-FRONTMATTER.md\n---\n\nScout the package.\n`, "utf-8");
 		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
-
 			packages: [packageRoot],
 			subagents: { agentOverrides: { "package-scout": { output: "package.md", defaultReads: ["PACKAGE.md"] } } },
 		});
@@ -1171,4 +1165,4 @@ describe("builtin agent overrides", () => {
 		);
 		assert.equal(whitespaceDescription, undefined);
 	});
-});
+});

package/dist/extensions/pi-subagents/test/unit/async-execution.test.ts

@@ -77,7 +77,7 @@ describe("async runner execution", () => {
 				agents: [{ ...agent("worker"), model: "mock/denied" }],
 				ctx: { ...ctx, cwd: repo },
 				cwd: repo,
-				asyncDir: path.join(repo, ".selesai", "subagents", "async-step-rules"),
+				asyncDir: path.join(repo, ".pi-subagents", "async-step-rules"),
 				maxSubagentDepth: 1,
 			});