@selesai/code 0.5.29 → 0.6.2

package/dist/extensions/pi-subagents/test/integration/result-watcher.test.ts

@@ -341,7 +341,11 @@ describe("result watcher", () => {
 				assert.notEqual(state.watcherRestartTimer, null);
 
 				fs.writeFileSync(childSessionPath, "", "utf-8");
-				fs.writeFileSync(path.join(resultsDir, "async-fallback.json"), JSON.stringify({
+				const childOutputA = path.join(resultsDir, "child-a.md");
+			const childOutputB = path.join(resultsDir, "child-b.md");
+			fs.writeFileSync(childOutputA, "Result from a", "utf-8");
+			fs.writeFileSync(childOutputB, "Result from b", "utf-8");
+			fs.writeFileSync(path.join(resultsDir, "async-fallback.json"), JSON.stringify({
 					id: "async-fallback",
 					runId: "run-fallback",
 					agent: "parallel:a+b",
@@ -350,8 +354,8 @@ describe("result watcher", () => {
 					state: "complete",
 					summary: "Combined summary",
 					results: [
-						{ agent: "a", output: "Result from a", success: true, sessionFile: childSessionPath, intercomTarget: "subagent-a-run-fallback-1" },
-						{ agent: "b", output: "Result from b", success: false, error: "B failed", intercomTarget: "subagent-b-run-fallback-2" },
+						{ agent: "a", output: "Result from a", outputPath: childOutputA, success: true, sessionFile: childSessionPath, intercomTarget: "subagent-a-run-fallback-1" },
+						{ agent: "b", output: "Result from b", outputPath: childOutputB, success: false, error: "B failed", intercomTarget: "subagent-b-run-fallback-2" },
 					],
 					sessionId: "session-1",
 					intercomTarget: "subagent-chat-main",
@@ -377,8 +381,12 @@ describe("result watcher", () => {
 			assert.equal(completion?.results?.[0]?.sessionPath, childSessionPath);
 			assert.equal(payload.children?.[1]?.status, "failed");
 			assert.equal(completion?.results?.[1]?.status, "failed");
-			assert.equal(payload.children?.[1]?.summary, "B failed\n\nOutput:\nResult from b");
-			assert.equal(completion?.results?.[1]?.summary, "B failed\n\nOutput:\nResult from b");
+			// Reference-only async delivery: child summaries are built from the
+			// authoritative output path (error/status first for failed children).
+			assert.match(payload.children?.[1]?.summary ?? "", /^B failed\n\nOutput saved to: .*child-b\.md/);
+			assert.match(completion?.results?.[1]?.summary ?? "", /^B failed\n\nOutput saved to: /);
+			assert.match(payload.children?.[0]?.summary ?? "", /^Output saved to: .*child-a\.md/);
+			assert.doesNotMatch(payload.children?.[1]?.summary ?? "", /Result from b/);
 		} finally {
 			fs.rmSync(resultsDir, { recursive: true, force: true });
 		}
@@ -1063,6 +1071,74 @@ describe("result watcher", () => {
 		}
 	});
 
+	it("uses a bounded fallback when a child output path is absent or unreadable", async () => {
+		const resultsDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-result-watcher-fallback-"));
+		try {
+			const emitted: Array<{ event: string; data: unknown }> = [];
+			const listeners = new Map<string, Set<(payload: unknown) => void>>();
+			const pi = {
+				events: {
+					on(event: string, handler: (payload: unknown) => void) {
+						const set = listeners.get(event) ?? new Set();
+						set.add(handler);
+						listeners.set(event, set);
+						return () => set.delete(handler);
+					},
+					emit(event: string, data: unknown) {
+						emitted.push({ event, data });
+						for (const handler of listeners.get(event) ?? []) handler(data);
+					},
+				},
+			};
+			const state = createState();
+			state.currentSessionId = "session-1";
+			const watcher = createResultWatcher(pi, state, resultsDir, 60_000);
+			const missingOutputPath = path.join(resultsDir, "missing-child.md");
+			const unreadablePath = path.join(resultsDir, "unreadable-child.md");
+			fs.writeFileSync(unreadablePath, "unreadable child output", "utf-8");
+			fs.chmodSync(unreadablePath, 0o000);
+			try {
+				fs.writeFileSync(path.join(resultsDir, "fallback.json"), JSON.stringify({
+					id: "fallback",
+					runId: "run-fallback",
+					agent: "parallel:a+b",
+					mode: "parallel",
+					success: false,
+					state: "failed",
+					summary: "run summary that must never leak",
+					results: [
+						{ agent: "a", outputPath: missingOutputPath, output: "internal a", success: false, error: "A exploded" },
+						{ agent: "b", outputPath: unreadablePath, output: "internal b", success: false, error: "B exploded" },
+					],
+					sessionId: "session-1",
+				}), "utf-8");
+				watcher.primeExistingResults();
+				await new Promise((resolve) => setTimeout(resolve, 100));
+			} finally {
+				fs.chmodSync(unreadablePath, 0o644);
+				watcher.stopResultWatcher();
+			}
+			const completion = emitted.find((entry) => entry.event === "subagent:async-complete")?.data as { results?: Array<{ summary?: string }> } | undefined;
+			assert.ok(completion, "expected an async completion");
+			const summaryA = completion.results?.[0]?.summary ?? "";
+			const summaryB = completion.results?.[1]?.summary ?? "";
+			assert.match(summaryA, /\[Full output unavailable\]/);
+			assert.match(summaryA, /Failed to read saved output: ENOENT/);
+			assert.match(summaryA, /missing-child\.md/);
+			assert.match(summaryB, /\[Full output unavailable\]/);
+			assert.match(summaryB, /Failed to read saved output: EACCES: permission denied/);
+			assert.match(summaryB, /unreadable-child\.md/);
+			// Only a bounded excerpt of the internal text is exposed, never the raw
+			// full output shape or the run summary.
+			assert.match(summaryA, /internal a/);
+			assert.match(summaryB, /internal b/);
+			assert.doesNotMatch(summaryA, /Output:\ninternal a/);
+			assert.doesNotMatch(summaryA + summaryB, /run summary that must never leak/);
+		} finally {
+			fs.rmSync(resultsDir, { recursive: true, force: true });
+		}
+	});
+
 	it("delivers a result when a previous duplicate key has expired", async () => {
 		const resultsDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-result-watcher-expired-"));
 		try {

package/dist/extensions/pi-subagents/test/integration/single-execution.test.ts

@@ -374,7 +374,8 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 		);
 
 		assert.equal(result.isError, undefined);
-		assert.match(result.content[0]?.text ?? "", /single alias finished/);
+		assert.match(result.content[0]?.text ?? "", /Output saved to: /);
+		assert.doesNotMatch(result.content[0]?.text ?? "", /single alias finished/);
 	});
 
 	it("admits a zero run-level tool budget only for marked v2 delegated execution", { skip: !createSubagentExecutor ? "executor not importable" : undefined }, async () => {
@@ -412,7 +413,13 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 			ctx,
 		);
 		assert.equal(v2Delegated.isError, undefined);
-		const env = JSON.parse(v2Delegated.content[0]?.text ?? "{}") as Record<string, string>;
+		// Reference-first delegated completion: the full echoed env snapshot is
+		// persisted to the generated result file; the content is the reference.
+		const delegatedOutputsDir = path.join(tempDir, ".pi-subagents", "artifacts", "outputs");
+		const delegatedRunDirs = fs.readdirSync(delegatedOutputsDir);
+		assert.equal(delegatedRunDirs.length, 1);
+		const persistedEnv = fs.readFileSync(path.join(delegatedOutputsDir, delegatedRunDirs[0]!, "result.md"), "utf-8");
+		const env = JSON.parse(persistedEnv) as Record<string, string>;
 		assert.deepEqual(JSON.parse(env[TOOL_BUDGET_ENV] ?? "null"), zeroBudget);
 		assert.equal(env[TOOL_BUDGET_ZERO_AUTH_ENV], "1");
 		assert.equal(mockPi.callCount(), 1);
@@ -1248,7 +1255,7 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 
 			const result = await executor.execute(
 				"single-schema-file-only-missing-path",
-				{ agent: "echo", task: "Return structured data", outputSchema: { type: "object", required: ["ok"], properties: { ok: { type: "boolean" } } }, outputMode: "file-only", acceptance: false, artifacts: false },
+				{ agent: "echo", task: "Return structured data", outputSchema: { type: "object", required: ["ok"], properties: { ok: { type: "boolean" } } }, outputMode: "file-only", output: false, acceptance: false, artifacts: false },
 				new AbortController().signal,
 				undefined,
 				makeMinimalCtx(tempDir),
@@ -1305,7 +1312,7 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 
 		const result = await executor.execute(
 			"failed-single-output",
-			{ agent: "oracle", task: "Implement the approved file changes" },
+			{ agent: "oracle", task: "Implement the approved file changes", artifacts: true },
 			new AbortController().signal,
 			undefined,
 			makeMinimalCtx(tempDir),
@@ -1314,8 +1321,14 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 		const text = result.content[0]?.text ?? "";
 		assert.equal(result.isError, true);
 		assert.match(text, /completed without making edits/);
-		assert.match(text, /Output:\nOracle review:\n- finding one\n- finding two/);
-		assert.match(text, /Output artifact: /);
+		// Reference-first failure: error/status plus the saved-output reference;
+		// the full output stays readable in the persisted result file.
+		assert.match(text, /Output saved to: /);
+		assert.doesNotMatch(text, /Output:\nOracle review:/);
+		const outputsDir = path.join(tempDir, ".pi-subagents", "artifacts", "outputs");
+		const runDirs = fs.readdirSync(outputsDir);
+		assert.equal(runDirs.length, 1);
+		assert.equal(fs.readFileSync(path.join(outputsDir, runDirs[0]!, "result.md"), "utf-8"), "Oracle review:\n- finding one\n- finding two");
 	});
 
 	it("fails future-tense implementation summaries when no mutation attempt occurred", async () => {
@@ -1399,7 +1412,8 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 
 		assert.equal(result.isError, undefined);
 		assert.equal(result.details?.results[0]?.agent, "worker");
-		assert.match(result.content[0]?.text ?? "", /Implemented/);
+		assert.match(result.content[0]?.text ?? "", /Output saved to: /);
+		assert.doesNotMatch(result.content[0]?.text ?? "", /^Implemented$/);
 	});
 
 	it("returns error for unknown agent", async () => {
@@ -2283,6 +2297,29 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 		assert.ok(!JSON.stringify(result.launchResolvedExtensions).includes(tempDir), "projection should not expose raw extension paths");
 	});
 
+	it("does not write debug artifacts by default", { skip: !createSubagentExecutor ? "executor not importable" : undefined }, async () => {
+		mockPi.onCall({ output: "plain result" });
+		const executor = makeExecutor([makeAgent("echo")]);
+		const result = await executor.execute(
+			"default-no-artifacts",
+			{ agent: "echo", task: "Run without debug artifacts", runId: "default-no-artifacts" },
+			new AbortController().signal,
+			undefined,
+			makeMinimalCtx(tempDir),
+		);
+
+		assert.equal(result.isError, undefined);
+		assert.equal(result.details?.artifacts, undefined);
+		// Generated durable output persists even with artifacts:false; per-child
+		// debug artifacts (_input/_output/_meta/_transcript) remain opt-in.
+		const defaultOutputsDir = path.join(tempDir, ".pi-subagents", "artifacts", "outputs");
+		const defaultRunDirs = fs.readdirSync(defaultOutputsDir);
+		assert.equal(defaultRunDirs.length, 1);
+		const defaultRunDir = path.join(defaultOutputsDir, defaultRunDirs[0]!);
+		assert.equal(fs.readFileSync(path.join(defaultRunDir, "result.md"), "utf-8"), "plain result");
+		assert.deepEqual(fs.readdirSync(defaultRunDir), ["result.md"]);
+	});
+
 	it("routes foreground artifacts to the configured session directory", { skip: !createSubagentExecutor ? "executor not importable" : undefined }, async () => {
 		mockPi.onCall({ output: "session artifact result" });
 		const sessionFile = path.join(tempDir, "sessions", "parent-session", "session.jsonl");
@@ -2292,7 +2329,7 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 
 		const result = await executor.execute(
 			"session-artifact-dir",
-			{ agent: "echo", task: "Write session-scoped artifacts", runId: "session-artifacts" },
+			{ agent: "echo", task: "Write session-scoped artifacts", runId: "session-artifacts", artifacts: true },
 			new AbortController().signal,
 			undefined,
 			ctx,
@@ -2686,7 +2723,8 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 		);
 
 		assert.equal(result.isError, undefined);
-		assert.match(result.content[0]?.text ?? "", /agent foreground default finished/);
+		assert.match(result.content[0]?.text ?? "", /Output saved to: /);
+		assert.doesNotMatch(result.content[0]?.text ?? "", /agent foreground default finished/);
 		assert.equal(result.details?.asyncId, undefined);
 	});
 
@@ -2715,7 +2753,8 @@ describe("single sync execution", { skip: !available ? "pi packages not availabl
 		);
 
 		assert.equal(result.isError, undefined);
-		assert.match(result.content[0]?.text ?? "", /explicit foreground finished/);
+		assert.match(result.content[0]?.text ?? "", /Output saved to: /);
+		assert.doesNotMatch(result.content[0]?.text ?? "", /explicit foreground finished/);
 		assert.equal(result.details?.asyncId, undefined);
 	});
 

package/dist/extensions/pi-subagents/test/support/real-session-runner.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -47,6 +47,21 @@ export function subagentCall(args: Record<string, unknown>, id = "call-subagent-
 	return fauxToolCall("subagent", args, { id });
 }
 
+function resolvedSubagentResultText(resultText: string): string {
+	// Reference-first completion: the tool result carries "Output saved to:
+	// <path> (…)". Resolve the durable file so the scripted parent can relay the
+	// exact child output.
+	if (!resultText.includes("Output saved to: ")) return resultText;
+	const rest = resultText.split("Output saved to: ")[1];
+	if (!rest) return resultText;
+	const outputPath = rest.split(" (")[0];
+	try {
+		return readFileSync(outputPath, "utf-8");
+	} catch {
+		return resultText;
+	}
+}
+
 export function routeParentThroughSubagent(input: {
 	childMarker: string;
 	subagentArgs: Record<string, unknown>;
@@ -56,7 +71,8 @@ export function routeParentThroughSubagent(input: {
 		if (!isParent) return "Unexpected non-parent model call.";
 		const resultText = latestSubagentToolResultText(context.messages as Array<{ role?: string; toolName?: string; content?: unknown }>);
 		if (resultText !== undefined) {
-			return `Parent relays: ${resultText.includes(input.childMarker) ? input.childMarker : "CHILD_MISSING"}`;
+			const resolved = resolvedSubagentResultText(resultText);
+			return `Parent relays: ${resolved.includes(input.childMarker) ? input.childMarker : "CHILD_MISSING"}`;
 		}
 		return subagentCall(input.subagentArgs);
 	};

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

@@ -177,7 +177,7 @@ describe("builtin agent disabling", () => {
 			{ cwd: tempProject, modelRegistry: { getAvailable: () => [] } },
 		));
 
-		assert.match(text, /Executable agents:\n- helper \(project\): Helper/);
+		assert.match(text, /Executable agents:\n- helper \(project, context: fresh\): Helper/);
 		assert.doesNotMatch(text, /Disabled builtins:/);
 		for (const name of disabledBuiltinNames) {
 			assert.doesNotMatch(text, new RegExp(`^- ${name} \\(builtin`, "m"));

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

@@ -6,7 +6,7 @@ import { afterEach, describe, it } from "node:test";
 import { handleManagementAction } from "../../src/agents/agent-management.ts";
 import { serializeAgent } from "../../src/agents/agent-serializer.ts";
 import { parseChain, serializeChain } from "../../src/agents/chain-serializer.ts";
-import { discoverAgents, discoverAgentsAll, type AgentConfig } from "../../src/agents/agents.ts";
+import { BUILTIN_AGENT_NAMES, discoverAgents, discoverAgentsAll, type AgentConfig } from "../../src/agents/agents.ts";
 import { parseFrontmatter } from "../../src/agents/frontmatter.ts";
 import { buildPiArgs } from "../../src/runs/shared/pi-args.ts";
 import { THINKING_LEVELS } from "../../src/shared/model-info.ts";
@@ -357,14 +357,54 @@ Do work
 		assert.equal(worker?.defaultContext, "fork");
 	});
 
-	it("loads packaged architect and recapper with fork defaultContext", () => {
+	it("loads builtin agents with the authoritative six-agent defaultContext map", () => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-default-context-"));
 		tempDirs.push(dir);
 		const agents = discoverAgentsAll(dir).builtin;
 
-		for (const name of ["architect", "recapper"]) {
+		const expected: Record<string, "fresh" | "fork"> = {
+			architect: "fork",
+			recapper: "fork",
+			builder: "fresh",
+			commentator: "fresh",
+			explorer: "fresh",
+			researcher: "fresh",
+		};
+		assert.deepEqual(
+			agents.map((agent) => agent.name).sort(),
+			[...BUILTIN_AGENT_NAMES].sort(),
+		);
+		for (const [name, context] of Object.entries(expected)) {
+			const agent = agents.find((candidate) => candidate.name === name);
+			assert.equal(agent?.defaultContext, context, `${name} should default to ${context} context`);
+		}
+	});
+});
+
+describe("bundled agent descriptions and acceptance roles", () => {
+	it("survives discovery with declared descriptions and acceptance roles", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-bundled-catalog-roles-"));
+		tempDirs.push(dir);
+		const agents = discoverAgentsAll(dir).builtin;
+
+		const expected: Record<string, { description: string; acceptanceRole: "read-only" | "writer" }> = {
+			architect: { description: "Read-only architecture and implementation planning", acceptanceRole: "read-only" },
+			builder: { description: "Mutation-capable scoped implementation", acceptanceRole: "writer" },
+			commentator: { description: "Read-only evidence-based review", acceptanceRole: "read-only" },
+			explorer: { description: "Read-only local codebase reconnaissance", acceptanceRole: "read-only" },
+			recapper: { description: "Read-only handoff and context synthesis", acceptanceRole: "read-only" },
+			researcher: { description: "Read-only external and code-first research", acceptanceRole: "read-only" },
+		};
+
+		assert.deepEqual(
+			agents.map((agent) => agent.name).sort(),
+			[...BUILTIN_AGENT_NAMES].sort(),
+		);
+		for (const [name, expectedEntry] of Object.entries(expected)) {
 			const agent = agents.find((candidate) => candidate.name === name);
-			assert.equal(agent?.defaultContext, "fork", `${name} should default to fork context`);
+			assert.ok(agent, `bundled agent ${name} not discovered`);
+			assert.equal(agent.description, expectedEntry.description, `${name} description`);
+			assert.equal(agent.acceptanceRole, expectedEntry.acceptanceRole, `${name} acceptanceRole`);
 		}
 	});
 });
@@ -1331,7 +1371,7 @@ Do work
 		}
 	});
 
-	it("builder includes the child-facing supervisor tool", () => {
+	it("builder builtin tools exclude the bridge-injected supervisor tool", () => {
 		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);
@@ -1344,7 +1384,31 @@ Do work
 			process.env.USERPROFILE = homeDir;
 			const agent = discoverAgentsAll(dir).builtin.find((candidate) => candidate.name === "builder");
 			assert.ok(agent, "builder builtin should be discovered");
-			assert.deepEqual(agent?.tools, ["read", "grep", "find", "ls", "bash", "edit", "write", "contact_supervisor"]);
+			assert.deepEqual(agent?.tools, ["read", "grep", "find", "ls", "bash", "edit", "write"]);
+			assert.equal(agent?.tools?.includes("contact_supervisor"), false);
+		} finally {
+			if (previousHome === undefined) delete process.env.HOME;
+			else process.env.HOME = previousHome;
+			if (previousUserProfile === undefined) delete process.env.USERPROFILE;
+			else process.env.USERPROFILE = previousUserProfile;
+		}
+	});
+
+	it("researcher builtin routes grep.app tools into mcpDirectTools", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-researcher-tools-"));
+		const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-researcher-tools-home-"));
+		tempDirs.push(dir);
+		tempDirs.push(homeDir);
+		const previousHome = process.env.HOME;
+		const previousUserProfile = process.env.USERPROFILE;
+
+		try {
+			process.env.HOME = homeDir;
+			process.env.USERPROFILE = homeDir;
+			const agent = discoverAgentsAll(dir).builtin.find((candidate) => candidate.name === "researcher");
+			assert.ok(agent, "researcher builtin should be discovered");
+			assert.deepEqual(agent?.tools, ["read", "web_explore"]);
+			assert.deepEqual(agent?.mcpDirectTools, ["grep_app_search", "grep_app_fetch"]);
 		} finally {
 			if (previousHome === undefined) delete process.env.HOME;
 			else process.env.HOME = previousHome;

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

@@ -53,7 +53,7 @@ describe("agent management config parsing", () => {
 		);
 
 		assert.equal(result.isError, false);
-		assert.match(readText(result), /- scout \(project\): Project scout override/);
+		assert.match(readText(result), /- scout \(project, context: fresh\): Project scout override/);
 		assert.doesNotMatch(readText(result), /- scout \(builtin/);
 	});
 
@@ -722,6 +722,126 @@ Drive the failing test first.
 		assert.match(content, /inheritSkills: false/);
 	});
 
+	it("exposes a rich human and machine catalog for a custom project agent and chain", () => {
+		const ctx = { cwd: tempDir, modelRegistry: { getAvailable: () => [] } };
+		const created = handleCreate(
+			{
+				config: {
+					name: "Catalog Writer",
+					description: "Scoped catalog writer",
+					scope: "project",
+					aliases: "catw",
+					acceptanceRole: "writer",
+					defaultContext: "fork",
+					tools: "read, grep, find, ls, bash, edit, write, mcp:fixture_search",
+					systemPrompt: "Implement scoped changes.",
+				},
+			},
+			ctx,
+		);
+		assert.equal(created.isError, false);
+
+		const chainCreated = handleCreate(
+			{ config: { name: "Review Flow", description: "Catalog review flow", scope: "project", steps: [{ agent: "catalog-writer", task: "Inspect" }] } },
+			ctx,
+		);
+		assert.equal(chainCreated.isError, false);
+
+		const listed = handleManagementAction("list", {}, ctx);
+		assert.equal(listed.isError, false);
+		const text = readText(listed);
+		assert.match(text, /Executable agents:/);
+		assert.match(
+			text,
+			/- catalog-writer \(project, context: fork, role: writer, aliases: catw, tools: read, grep, find, ls, bash, edit, write, mcp:fixture_search\): Scoped catalog writer/,
+		);
+		assert.match(text, /Chains:\n- review-flow \(project\): Catalog review flow/);
+
+		const details = (listed as { details: { catalog: unknown } }).details.catalog as {
+			version: number;
+			agents: Array<{
+				name: string;
+				source: string;
+				description: string;
+				executable: boolean;
+				aliases?: string[];
+				defaultContext: string;
+				acceptanceRole?: string;
+				tools?: string[];
+			}>;
+			chains: Array<{ name: string; source: string; description: string }>;
+		};
+		assert.equal(details.version, 1);
+		const entry = details.agents.find((agent) => agent.name === "catalog-writer");
+		assert.ok(entry, "catalog must include the custom project agent");
+		assert.equal(entry.source, "project");
+		assert.equal(entry.description, "Scoped catalog writer");
+		assert.equal(entry.executable, true);
+		assert.deepEqual(entry.aliases, ["catw"]);
+		assert.equal(entry.defaultContext, "fork");
+		assert.equal(entry.acceptanceRole, "writer");
+		assert.deepEqual(entry.tools, ["read", "grep", "find", "ls", "bash", "edit", "write", "mcp:fixture_search"]);
+		assert.deepEqual(details.chains, [{ name: "review-flow", source: "project", description: "Catalog review flow" }]);
+	});
+
+	it("normalizes unset defaultContext to fresh in the machine catalog", () => {
+		const ctx = { cwd: tempDir, modelRegistry: { getAvailable: () => [] } };
+		const created = handleCreate(
+			{ config: { name: "No Context", description: "No explicit context", scope: "project", systemPrompt: "Work" } },
+			ctx,
+		);
+		assert.equal(created.isError, false);
+
+		const listed = handleManagementAction("list", {}, ctx);
+		const details = (listed as { details: { catalog: unknown } }).details.catalog as {
+			agents: Array<{ name: string; defaultContext: string }>;
+		};
+		const entry = details.agents.find((agent) => agent.name === "no-context");
+		assert.ok(entry);
+		assert.equal(entry.defaultContext, "fresh");
+		assert.match(readText(listed), /- no-context \(project, context: fresh\)/);
+	});
+
+	it("omits disabled agents from both human text and machine catalog metadata", () => {
+		const ctx = { cwd: tempDir, modelRegistry: { getAvailable: () => [] } };
+		const created = handleCreate(
+			{ config: { name: "Hidden Writer", description: "Should stay hidden", scope: "project", systemPrompt: "Work" } },
+			ctx,
+		);
+		assert.equal(created.isError, false);
+
+		const disabled = handleManagementAction("disable", { agent: "hidden-writer" }, ctx);
+		assert.equal(disabled.isError, false);
+
+		const listed = handleManagementAction("list", {}, ctx);
+		assert.equal(listed.isError, false);
+		assert.doesNotMatch(readText(listed), /hidden-writer/);
+		const details = (listed as { details: { catalog: unknown } }).details.catalog as {
+			agents: Array<{ name: string }>;
+		};
+		assert.equal(details.agents.some((agent) => agent.name === "hidden-writer"), false);
+	});
+
+	it("returns (none) text and an empty versioned catalog when no agents are discovered", () => {
+		fs.mkdirSync(path.join(tempDir, "agent-home"), { recursive: true });
+		fs.writeFileSync(
+			path.join(tempDir, "agent-home", "settings.json"),
+			JSON.stringify({ subagents: { disableBuiltins: true } }, null, 2),
+			"utf-8",
+		);
+		const ctx = { cwd: tempDir, modelRegistry: { getAvailable: () => [] } };
+		const listed = handleManagementAction("list", {}, ctx);
+		assert.equal(listed.isError, false);
+		const text = readText(listed);
+		assert.match(text, /Executable agents:\n- \(none\)/);
+		assert.match(text, /Chains:\n- \(none\)/);
+		assert.deepEqual((listed as { details: { catalog: unknown } }).details.catalog, {
+			version: 1,
+			agents: [],
+			chains: [],
+		});
+	});
+
 	it("lists proactive skill subagent suggestions from repeated configured skill use", () => {
 		const ctx = { cwd: tempDir, modelRegistry: { getAvailable: () => [] } };
 		fs.mkdirSync(path.join(tempDir, ".selesai", "agents"), { recursive: true });
@@ -774,4 +894,44 @@ Inspect cleanup.
 		assert.doesNotMatch(readText(listed), /Proactive skill subagent suggestions:/);
 	});
 
+	it("appends explicit-only task-aware advisory routing to list output when task is provided", () => {
+		const ctx = { cwd: tempDir, modelRegistry: { getAvailable: () => [] } };
+		handleCreate(
+			{ config: { name: "Code Reviewer", description: "Reviews without editing", scope: "project", acceptanceRole: "read-only", tools: "read, grep, find, ls", systemPrompt: "Review." } },
+			ctx,
+		);
+		handleCreate(
+			{ config: { name: "Fixer", description: "Implements changes", scope: "project", acceptanceRole: "writer", tools: "read, grep, bash, edit, write", systemPrompt: "Fix." } },
+			ctx,
+		);
+
+		const implementation = handleManagementAction("list", { task: "Implement the fix" }, ctx);
+		assert.equal(implementation.isError, false);
+		assert.deepEqual((implementation as { details: { results: unknown[] } }).details.results, []);
+		const implementationText = readText(implementation);
+		assert.match(implementationText, /Task-aware advisory routing:/);
+		assert.match(implementationText, /- Intent: implementation/);
+		assert.match(implementationText, /- Recommended: fixer \(project\)/);
+		assert.match(implementationText, /- Advisory only: no subagent was launched\. To proceed, explicitly call subagent with this canonical agent name and the task\./);
+
+		const review = handleManagementAction("list", { task: "Review only; do not edit files" }, ctx);
+		assert.equal(review.isError, false);
+		const reviewText = readText(review);
+		assert.match(reviewText, /- Intent: read-only/);
+		assert.match(reviewText, /- Recommended: code-reviewer \(project\)/);
+
+		const vague = handleManagementAction("list", { task: "Look into this" }, ctx);
+		assert.equal(vague.isError, false);
+		const vagueText = readText(vague);
+		assert.match(vagueText, /- Intent: unknown/);
+		assert.match(vagueText, /- Recommendation: none/);
+		assert.match(vagueText, /Clarify whether the task is read-only analysis\/review or implementation allowed to edit files\./);
+
+		for (const noTaskParams of [{}, { task: "   " }]) {
+			const noTask = handleManagementAction("list", noTaskParams, ctx);
+			assert.equal(noTask.isError, false);
+			assert.doesNotMatch(readText(noTask), /Task-aware advisory routing:/);
+		}
+	});
+
 });

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

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { BUILTIN_AGENT_NAMES } from "../../src/agents/agents.ts";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const README_PATH = path.join(packageRoot, "README.md");
+const PROMPTING_AND_ROLES_PATH = path.join(packageRoot, "skills", "pi-subagents", "references", "prompting-and-roles.md");
+
+const README_TABLE_HEADING = "## Builtin agents in plain English";
+const PROMPTING_AND_ROLES_TABLE_HEADING = "## Builtin Agents";
+
+/**
+ * Extracts the first-column agent names from every table row under the given
+ * markdown section heading. Skips the header row and the separator row.
+ */
+function tableFirstColumnNames(markdown: string, sectionHeading: string): string[] {
+	const lines = markdown.split(/\r?\n/);
+	const headingIndex = lines.findIndex((line) => line.trim() === sectionHeading);
+	assert.ok(headingIndex >= 0, `missing section heading: ${sectionHeading}`);
+
+	const names: string[] = [];
+	for (let i = headingIndex + 1; i < lines.length; i++) {
+		const line = lines[i]!.trim();
+		if (line.startsWith("#")) break;
+		if (!line.startsWith("|")) continue;
+
+		const cells = line.split("|").map((cell) => cell.trim());
+		const firstCell = (cells[1] ?? "").replaceAll("`", "").trim();
+		if (firstCell === "Agent") continue;
+		if (/^:?-+:?$/.test(firstCell)) continue;
+		if (firstCell.length === 0) continue;
+		names.push(firstCell);
+	}
+	return names;
+}
+
+function assertExactlySixBuiltins(tablePath: string, heading: string, markdown: string): void {
+	const names = tableFirstColumnNames(markdown, heading);
+
+	assert.equal(names.length, 6, `${path.basename(tablePath)}: role table must contain exactly six builtin rows`);
+	assert.equal(new Set(names).size, names.length, `${path.basename(tablePath)}: role table contains duplicate rows`);
+	assert.deepEqual(
+		[...names].sort(),
+		[...BUILTIN_AGENT_NAMES].sort(),
+		`${path.basename(tablePath)}: role table must list exactly ${BUILTIN_AGENT_NAMES.join(", ")} once each, with no aliases`,
+	);
+}
+
+describe("builtin agent documentation role tables", () => {
+	it("README lists exactly the six canonical builtins once, with no duplicates or aliases", () => {
+		const markdown = fs.readFileSync(README_PATH, "utf-8");
+		assertExactlySixBuiltins(README_PATH, README_TABLE_HEADING, markdown);
+	});
+
+	it("prompting-and-roles reference lists exactly the six canonical builtins once, with no duplicates or aliases", () => {
+		const markdown = fs.readFileSync(PROMPTING_AND_ROLES_PATH, "utf-8");
+		assertExactlySixBuiltins(PROMPTING_AND_ROLES_PATH, PROMPTING_AND_ROLES_TABLE_HEADING, markdown);
+	});
+});