@selesai/code 0.5.29 → 0.6.1

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);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/capability-ceiling-agent-allowlist.test.ts

@@ -58,6 +58,40 @@ describe("capability ceiling agent allowlist", () => {
 			assert.match(text, /- commentator /);
 			assert.match(text, /Restricted agents \(not executable in this session; capability ceiling: plan-mode\):/);
 			assert.match(text, /- builder /);
+
+			const catalog = (result as { details: { catalog?: unknown } }).details.catalog as
+				| undefined
+				| {
+					version: number;
+					agents: Array<{ name: string; executable: boolean; restrictionSources?: string[]; defaultContext: string }>;
+					capabilityCeilingSources?: string[];
+				};
+			assert.ok(catalog, "list result must include machine catalog metadata");
+			assert.equal(catalog.version, 1);
+			assert.deepEqual(catalog.capabilityCeilingSources, ["plan-mode"]);
+			const commentator = catalog.agents.find((entry) => entry.name === "commentator");
+			const builder = catalog.agents.find((entry) => entry.name === "builder");
+			assert.equal(commentator?.executable, true);
+			assert.equal(commentator?.restrictionSources, undefined);
+			assert.equal(commentator?.defaultContext, "fresh");
+			assert.equal(builder?.executable, false);
+			assert.deepEqual(builder?.restrictionSources, ["plan-mode"]);
+		} finally {
+			handle.dispose();
+		}
+	});
+
+	it("never recommends a capability-restricted writer for implementation list task advice", () => {
+		const sessionId = `allowlist-advice-${Date.now()}-${Math.random()}`;
+		const handle = registerSubagentCapabilityCeiling({ sessionId, source: "plan-mode", ceiling: { allowedAgents: ["commentator"] } });
+		try {
+			const result = handleList({ task: "Implement the fix" }, { cwd: process.cwd(), currentSessionId: sessionId, modelRegistry: { getAvailable: () => [] } });
+			assert.equal(result.isError, false);
+			const text = result.content[0]?.text ?? "";
+			assert.match(text, /Task-aware advisory routing:/);
+			assert.match(text, /- Intent: implementation/);
+			assert.match(text, /- Recommendation: none/);
+			assert.doesNotMatch(text, /- Recommended: /);
 		} finally {
 			handle.dispose();
 		}

package/dist/extensions/pi-subagents/test/unit/delegation-api.test.ts

@@ -17,6 +17,7 @@ import {
 	type SubagentDelegationV2Response,
 } from "../../src/api/delegation.ts";
 import { parseSubagentDelegationRequest } from "../../src/slash/delegation-request.ts";
+import { toSubagentDelegationExecutionParams } from "../../src/slash/delegation-adapters.ts";
 import {
 	registerPromptTemplateDelegationBridge,
 	type PromptTemplateBridgeEvents,
@@ -508,6 +509,29 @@ describe("public subagent delegation contract", () => {
 		assert.deepEqual(responses, []);
 	});
 
+	it("resolves an omitted v1 outputMode to explicit inline so response.output stays populated", () => {
+		const minimal: SubagentDelegationRequest = {
+			version: 1,
+			requestId: "adapter-default-1",
+			agent: "reviewer",
+			task: "Review evidence",
+			context: "fresh",
+			cwd: "/repo",
+		};
+		// Omitted outputMode on a strict v1 request keeps the legacy full-text
+		// contract: explicit inline, so `SubagentDelegationResponse.output` stays
+		// populated instead of degrading to the reference-first file-only default.
+		const params = toSubagentDelegationExecutionParams(minimal);
+		assert.equal(params.outputMode, "inline");
+		assert.equal(params.output, undefined);
+
+		// Explicit v1 modes are forwarded exactly; v2 stays unaffected (output: false).
+		assert.equal(toSubagentDelegationExecutionParams(request).outputMode, "file-only");
+		const inline = toSubagentDelegationExecutionParams({ ...request, outputMode: "inline" });
+		assert.equal(inline.outputMode, "inline");
+		assert.equal(toSubagentDelegationExecutionParams({ ...request, outputMode: undefined }).outputMode, "inline");
+	});
+
 	it("runs one v1 request through the existing executor and returns structured metadata", async () => {
 		const events = new FakeEvents();
 		let executeCalls = 0;

package/dist/extensions/pi-subagents/test/unit/index-child-registration.test.ts

@@ -599,14 +599,19 @@ describe("subagent extension child mode", () => {
 			};
 			registerFanoutChildSubagentExtension(fakePi);
 			if (!registeredTool) throw new Error("tool not registered");
+			if (registeredTool.promptGuidelines !== undefined) {
+				throw new Error("child-safe fanout tool must not carry parent-only routing promptGuidelines");
+			}
 			const ctx = {
 				cwd: process.cwd(),
 				hasUI: false,
 				sessionManager: { getSessionId() { return "session-test"; }, getSessionFile() { return null; } },
 				modelRegistry: { getAvailable() { return []; } },
 			};
-			const list = await registeredTool.execute("list-check", { action: "list" }, new AbortController().signal, undefined, ctx);
+			const list = await registeredTool.execute("list-check", { action: "list", task: "Review only; do not edit files" }, new AbortController().signal, undefined, ctx);
 			if (list.isError) throw new Error("list should be allowed: " + JSON.stringify(list.content));
+			const listText = list.content?.[0]?.text ?? "";
+			if (!listText.includes("Task-aware advisory routing:")) throw new Error("list task advice missing in child mode: " + listText.slice(0, 200));
 			const create = await registeredTool.execute("create-check", { action: "create", config: { name: "x" } }, new AbortController().signal, undefined, ctx);
 			if (!create.isError) throw new Error("create should be blocked");
 			const text = create.content?.[0]?.text ?? "";

package/dist/extensions/pi-subagents/test/unit/notify.test.ts

@@ -485,4 +485,33 @@ describe("completion formatting helpers", () => {
 		assert.equal(details.agent, "unknown");
 		assert.equal(details.status, "completed");
 	});
+
+	it("buildCompletionDetails prefers compact child summaries over the run summary", () => {
+		const details = buildCompletionDetails({
+			id: "x",
+			agent: "worker",
+			success: true,
+			summary: "alpha:\nfull child prose that must not leak",
+			timestamp: 1,
+			results: [
+				{ agent: "alpha", status: "completed", summary: "Output saved to: /tmp/alpha.md (12 B, 1 line). Read this file if needed." },
+				{ agent: "beta", status: "failed", summary: "boom\n\nOutput saved to: /tmp/beta.md (5 B, 1 line). Read this file if needed." },
+			],
+		});
+		assert.match(details.resultPreview, /1\. alpha\nOutput saved to: \/tmp\/alpha\.md/);
+		assert.match(details.resultPreview, /2\. beta\nboom\n\nOutput saved to: \/tmp\/beta\.md/);
+		assert.doesNotMatch(details.resultPreview, /full child prose that must not leak/);
+	});
+
+	it("buildCompletionDetails uses the single child summary without an index prefix", () => {
+		const details = buildCompletionDetails({
+			id: "x",
+			agent: "worker",
+			success: true,
+			summary: "ignored run summary",
+			timestamp: 1,
+			results: [{ agent: "worker", status: "completed", summary: "Output saved to: /tmp/out.md (8 B, 1 line). Read this file if needed." }],
+		});
+		assert.equal(details.resultPreview, "Output saved to: /tmp/out.md (8 B, 1 line). Read this file if needed.");
+	});
 });

package/dist/extensions/pi-subagents/test/unit/preflight.test.ts

@@ -107,6 +107,7 @@ Project prompt.
 					{ provider: "test", id: "fallback", fullId: "test/fallback" },
 				],
 				capabilityCeiling: ceiling,
+				artifacts: true,
 			});
 
 			assert.equal(result.ok, true);
@@ -143,6 +144,7 @@ Project prompt.
 					{ provider: "test", id: "fallback", fullId: "test/fallback" },
 				],
 				capabilityCeiling: ceiling,
+				artifacts: true,
 			});
 			assert.equal(repeated.ok, true);
 			assert.equal(repeated.contract.digest, result.contract.digest);

package/dist/extensions/pi-subagents/test/unit/schemas.test.ts

@@ -194,6 +194,18 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.doesNotMatch(description, /orchestration\./);
 	});
 
+	it("documents list task as an optional advisory intent and keeps action a free string", () => {
+		const taskSchema = (SubagentParams?.properties as Record<string, JsonSchemaNode> | undefined)?.task;
+		assert.ok(taskSchema, "task schema should exist");
+		const description = String(taskSchema?.description ?? "");
+		assert.match(description, /action:'list'/);
+		assert.match(description, /never launches/);
+		assert.match(description, /explicitly call subagent/);
+		const actionSchema = SubagentParams?.properties?.action;
+		assert.equal(actionSchema?.type, "string");
+		assert.equal(actionSchema?.enum, undefined);
+	});
+
 	it("includes foreground timeout aliases and turn budget", () => {
 		const timeoutSchema = SubagentParams?.properties?.timeoutMs;
 		const maxRuntimeSchema = SubagentParams?.properties?.maxRuntimeMs;

package/dist/extensions/pi-subagents/test/unit/single-output.test.ts

@@ -6,8 +6,10 @@ import * as path from "node:path";
 import type { Message, Usage } from "@earendil-works/pi-ai";
 import {
 	captureSingleOutputSnapshot,
+	CONTEXT_FALLBACK_LIMIT,
 	extractChildWrittenOutput,
 	finalizeSingleOutput,
+	formatBoundedPersistenceFallback,
 	formatSavedOutputReference,
 	injectOutputPathSystemPrompt,
 	injectSingleOutputInstruction,
@@ -269,6 +271,49 @@ describe("validateFileOnlyOutputMode", () => {
 	});
 });
 
+describe("CONTEXT_FALLBACK_LIMIT and formatBoundedPersistenceFallback", () => {
+	it("exports the fixed internal 80-line/4-KiB context fallback cap", () => {
+		assert.equal(CONTEXT_FALLBACK_LIMIT.lines, 80);
+		assert.equal(CONTEXT_FALLBACK_LIMIT.bytes, 4096);
+	});
+
+	it("includes error, process status, intended path, and a bounded slice", () => {
+		const fallback = formatBoundedPersistenceFallback({
+			error: "EACCES: permission denied",
+			outputPath: "/tmp/report.md",
+			fullOutput: "line one\nline two",
+			exitCode: 1,
+			processError: "boom",
+		});
+		assert.match(fallback, /\[Full output unavailable\] EACCES: permission denied/);
+		assert.match(fallback, /Process status: boom/);
+		assert.match(fallback, /Intended output path: \/tmp\/report\.md/);
+		assert.match(fallback, /Full output is unavailable; showing a bounded excerpt \(first 80 lines \/ 4 KiB\)\./);
+		assert.match(fallback, /line one\nline two/);
+		assert.doesNotMatch(fallback, /Output saved to:/);
+	});
+
+	it("never returns unbounded output when the source exceeds the cap", () => {
+		const longOutput = Array.from({ length: 500 }, (_, i) => `line ${i} ${`x`.repeat(50)}`).join("\n");
+		const fallback = formatBoundedPersistenceFallback({
+			error: "disk full",
+			fullOutput: longOutput,
+			exitCode: 0,
+		});
+		const body = fallback.split("\n").filter((line) => /^line \d+/.test(line)).length;
+		assert.ok(body <= 80, `fallback kept ${body} lines, expected at most 80`);
+		assert.ok(Buffer.byteLength(fallback, "utf-8") <= 12 * 1024, "fallback header plus 4-KiB slice stays bounded");
+		assert.doesNotMatch(fallback, /line 400/);
+	});
+
+	it("states completed status for exit code 0 and failed status otherwise", () => {
+		const completed = formatBoundedPersistenceFallback({ error: "read failed", fullOutput: "x", exitCode: 0 });
+		assert.match(completed, /Process status: completed/);
+		const failed = formatBoundedPersistenceFallback({ error: "read failed", fullOutput: "x", exitCode: 2 });
+		assert.match(failed, /Process status: failed \(exit 2\)/);
+	});
+});
+
 describe("finalizeSingleOutput", () => {
 	it("formats saved-path messaging around the already-resolved output", () => {
 		const result = finalizeSingleOutput({
@@ -298,13 +343,58 @@ describe("finalizeSingleOutput", () => {
 		assert.match(result.displayOutput, /3 lines/);
 	});
 
-	it("does not add save messaging on failed runs", () => {
+	it("returns error/status plus the saved-output reference on failed runs with a persisted result", () => {
 		const result = finalizeSingleOutput({
 			fullOutput: "full output",
 			truncatedOutput: "truncated output",
 			outputPath: "/tmp/review.md",
 			savedPath: "/tmp/review.md",
 			exitCode: 1,
+			error: "exploded",
+		});
+
+		assert.match(result.displayOutput, /^exploded\n\nOutput saved to: \/tmp\/review\.md/);
+		assert.doesNotMatch(result.displayOutput, /truncated output/);
+		assert.equal(result.savedPath, "/tmp/review.md");
+		assert.ok(result.outputReference);
+	});
+
+	it("returns only the bounded persistence-failure fallback when saving failed", () => {
+		const result = finalizeSingleOutput({
+			fullOutput: "full output text",
+			truncatedOutput: "truncated output",
+			outputPath: "/tmp/review.md",
+			exitCode: 0,
+			saveError: "EACCES: permission denied",
+		});
+
+		assert.match(result.displayOutput, /\[Full output unavailable\]/);
+		assert.match(result.displayOutput, /Intended output path: \/tmp\/review\.md/);
+		assert.match(result.displayOutput, /full output text/);
+		assert.doesNotMatch(result.displayOutput, /Output saved to:/);
+		assert.equal(result.savedPath, undefined);
+		assert.equal(result.saveError, "EACCES: permission denied");
+	});
+
+	it("returns only the bounded persistence-failure fallback on failed runs with a save error", () => {
+		const result = finalizeSingleOutput({
+			fullOutput: "partial child output",
+			outputPath: "/tmp/review.md",
+			exitCode: 1,
+			saveError: "Failed to read changed output file: boom",
+			error: "step failed",
+		});
+
+		assert.match(result.displayOutput, /\[Full output unavailable\] Failed to read changed output file: boom/);
+		assert.match(result.displayOutput, /Process status: step failed/);
+		assert.doesNotMatch(result.displayOutput, /Output saved to:/);
+	});
+
+	it("keeps the legacy full inline output for successful inline runs without a saved path", () => {
+		const result = finalizeSingleOutput({
+			fullOutput: "legacy inline output",
+			truncatedOutput: "truncated output",
+			exitCode: 0,
 		});
 
 		assert.equal(result.displayOutput, "truncated output");

package/dist/extensions/pi-subagents/test/unit/task-aware-routing.test.ts

@@ -0,0 +1,213 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	formatTaskAwareAgentRecommendation,
+	recommendTaskAwareAgent,
+} from "../../src/agents/task-aware-routing.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: "append",
+		inheritProjectContext: false,
+		inheritSkills: false,
+		source: "builtin",
+		filePath: `/tmp/${name}.md`,
+		...overrides,
+	};
+}
+
+describe("recommendTaskAwareAgent", () => {
+	it("no-ops for empty or whitespace-only tasks", () => {
+		assert.equal(recommendTaskAwareAgent({ task: "", agents: [] }), undefined);
+		assert.equal(recommendTaskAwareAgent({ task: "   \n\t ", agents: [] }), undefined);
+	});
+
+	it("recommends a canonical writer for an implementation task, never a read-only agent", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("commentator", { tools: ["read", "grep"] }),
+				agent("builder"),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.intent, "implementation");
+		assert.equal(recommendation.agent?.name, "builder");
+		assert.equal(recommendation.agent?.role, "writer");
+		assert.equal(recommendation.agent?.roleBasis, "inferred");
+	});
+
+	it("recommends a read-only agent without known write tools, never a writer", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Review only; do not edit files",
+			agents: [
+				agent("builder"),
+				agent("commentator", { tools: ["read", "grep", "find", "ls"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.intent, "read-only");
+		assert.equal(recommendation.agent?.name, "commentator");
+		assert.equal(recommendation.agent?.role, "read-only");
+		assert.equal(recommendation.agent?.roleBasis, "inferred");
+	});
+
+	it("never recommends a read-only agent whose tools are unset or include bash", () => {
+		for (const candidate of [
+			agent("commentator"),
+			agent("commentator", { tools: ["read", "bash"] }),
+		]) {
+			const recommendation = recommendTaskAwareAgent({
+				task: "Review only; do not edit files",
+				agents: [candidate],
+			});
+			assert.ok(recommendation);
+			assert.equal(recommendation.agent, undefined);
+			assert.match(recommendation.next ?? "", /read-only role without known write tools/);
+		}
+	});
+
+	it("gives recovery guidance, not a guess, for unknown intent", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Look into this",
+			agents: [agent("builder"), agent("commentator", { tools: ["read", "grep"] })],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.intent, "unknown");
+		assert.equal(recommendation.agent, undefined);
+		assert.match(recommendation.next ?? "", /Clarify whether the task is read-only analysis\/review or implementation allowed to edit files/);
+	});
+
+	it("excludes disabled agents even when they match the task role", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("builder", { disabled: true }),
+				agent("fixer", { source: "project", acceptanceRole: "writer", tools: ["edit"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "fixer");
+	});
+
+	it("excludes agents denied by the capability ceiling allowedAgents", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [agent("builder"), agent("fixer", { source: "project", acceptanceRole: "writer", tools: ["edit"] })],
+			capabilityCeiling: { version: 1, allowedAgents: ["builder"], denyExtensions: false, sources: ["plan"] },
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "builder");
+	});
+
+	it("refuses a writer recommendation when allowedTools has no writer tool", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [agent("builder")],
+			capabilityCeiling: { version: 1, allowedTools: ["read", "grep"], denyExtensions: false, sources: ["plan"] },
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.intent, "implementation");
+		assert.equal(recommendation.agent, undefined);
+		assert.match(recommendation.next ?? "", /capability ceiling/);
+	});
+
+	it("recommends a writer when allowedTools includes a writer tool", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [agent("builder")],
+			capabilityCeiling: { version: 1, allowedTools: ["read", "edit"], denyExtensions: false, sources: ["plan"] },
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "builder");
+	});
+
+	it("prefers project over user, package, and builtin candidates", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("builder", { source: "builtin" }),
+				agent("builder", { source: "package" }),
+				agent("builder", { source: "user" }),
+				agent("builder", { source: "project" }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "builder");
+		assert.equal(recommendation.agent?.source, "project");
+	});
+
+	it("sorts equal candidates by canonical name", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("zeta-builder", { source: "user", acceptanceRole: "writer", tools: ["edit"] }),
+				agent("alpha-builder", { source: "user", acceptanceRole: "writer", tools: ["edit"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "alpha-builder");
+	});
+
+	it("prefers a declared role over an inferred role at the same source", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("builder", { source: "user" }),
+				agent("fixer", { source: "user", acceptanceRole: "writer", tools: ["edit"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "fixer");
+		assert.equal(recommendation.agent?.roleBasis, "declared");
+	});
+
+	it("never emits an alias as the recommended launch name", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("canonical-builder", { aliases: ["developer"], source: "user", acceptanceRole: "writer", tools: ["edit"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "canonical-builder");
+	});
+});
+
+describe("formatTaskAwareAgentRecommendation", () => {
+	it("renders nothing for an empty-task no-op", () => {
+		assert.deepEqual(formatTaskAwareAgentRecommendation(undefined), []);
+	});
+
+	it("renders a safe recommendation with the canonical agent and explicit-launch note", () => {
+		const lines = formatTaskAwareAgentRecommendation({
+			intent: "implementation",
+			agent: { name: "builder", source: "project", role: "writer", roleBasis: "declared", reason: "declared writer role with write tools" },
+		});
+		assert.deepEqual(lines, [
+			"Task-aware advisory routing:",
+			"- Intent: implementation",
+			"- Recommended: builder (project)",
+			"- Reason: declared writer role with write tools",
+			"- Advisory only: no subagent was launched. To proceed, explicitly call subagent with this canonical agent name and the task.",
+		]);
+	});
+
+	it("renders recovery guidance without an agent name", () => {
+		const lines = formatTaskAwareAgentRecommendation({
+			intent: "unknown",
+			next: "Clarify whether the task is read-only analysis/review or implementation allowed to edit files.",
+		});
+		assert.deepEqual(lines, [
+			"Task-aware advisory routing:",
+			"- Intent: unknown",
+			"- Recommendation: none",
+			"- Next: Clarify whether the task is read-only analysis/review or implementation allowed to edit files.",
+			"- Advisory only: no subagent was launched.",
+		]);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/task-intent.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { classifyTaskMutationIntent, expectsImplementationMutation, taskMayMutate } from "../../src/runs/shared/task-intent.ts";
+import { classifyTaskMutationIntent, expectsImplementationMutation, resolveAgentRoutingRole, taskMayMutate } from "../../src/runs/shared/task-intent.ts";
 
 describe("classifyTaskMutationIntent", () => {
 	it("keeps write imperatives despite investigative wording", () => {
@@ -69,6 +69,28 @@ describe("classifyTaskMutationIntent", () => {
 	});
 });
 
+describe("resolveAgentRoutingRole", () => {
+	it("lets a declared acceptanceRole override name heuristics", () => {
+		assert.equal(resolveAgentRoutingRole("commentator", "writer"), "writer");
+		assert.equal(resolveAgentRoutingRole("builder", "read-only"), "read-only");
+		assert.equal(resolveAgentRoutingRole("custom-agent", "writer"), "writer");
+		assert.equal(resolveAgentRoutingRole("custom-agent", "read-only"), "read-only");
+	});
+
+	it("infers writer for builder-named agents and read-only for reviewer-style names", () => {
+		assert.equal(resolveAgentRoutingRole("builder"), "writer");
+		assert.equal(resolveAgentRoutingRole("package.builder"), "writer");
+		for (const name of ["architect", "commentator", "explorer", "recapper", "researcher", "analyst"]) {
+			assert.equal(resolveAgentRoutingRole(name), "read-only", name);
+		}
+	});
+
+	it("returns undefined for names without an established role", () => {
+		assert.equal(resolveAgentRoutingRole("custom-agent"), undefined);
+		assert.equal(resolveAgentRoutingRole("reviewer"), undefined);
+	});
+});
+
 describe("taskMayMutate", () => {
 	it("treats any bare write verb as write-capable", () => {
 		for (const task of ["Write the code", "Commit the changes", "Delete temporary data", "Remove obsolete assets", "Update dependencies"]) {