@selesai/code 0.5.29 → 0.6.1

package/dist/extensions/pi-subagents/src/agents/agent-management.ts

@@ -28,13 +28,14 @@ import { discoverAvailableSkills, resolveSkills } from "./skills.ts";
 import {
 	buildProactiveSkillSubagentRecommendationLines,
 } from "./proactive-skills.ts";
+import { formatTaskAwareAgentRecommendation, recommendTaskAwareAgent } from "./task-aware-routing.ts";
 import { parseFrontmatter } from "./frontmatter.ts";
 import { toModelInfo } from "../shared/model-info.ts";
 import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
 import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
-import type { AcceptanceInput, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
+import type { AcceptanceInput, CatalogAgentMetadata, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
 import { getProjectConfigDir } from "../shared/utils.ts";
 import { capabilityCeilingAgentRestrictionSources, isAgentAllowedByCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
 
@@ -48,10 +49,12 @@ interface ManagementParams {
 	chainName?: string;
 	agentScope?: string;
 	config?: unknown;
+	/** Optional advisory intent for action:'list' only; never launches work. */
+	task?: string;
 }
 
-function result(text: string, isError = false): AgentToolResult<Details> {
-	return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [] } };
+function result(text: string, isError = false, extraDetails: Partial<Details> = {}): AgentToolResult<Details> {
+	return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [], ...extraDetails } };
 }
 
 function parseCsv(value: string): string[] {
@@ -585,8 +588,13 @@ function renamePath(
 	return { filePath };
 }
 
+/** Effective declared tools: normal tools plus mcp:-prefixed direct MCP tools. */
+function effectiveAgentTools(agent: AgentConfig): string[] {
+	return [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
+}
+
 function formatAgentDetail(agent: AgentConfig): string {
-	const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
+	const tools = effectiveAgentTools(agent);
 	const lines: string[] = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
 	if (agent.packageName) {
 		lines.push(`Local name: ${frontmatterNameForConfig(agent)}`);
@@ -672,6 +680,33 @@ function formatChainDetail(chain: ChainConfig): string {
 	return lines.join("\n");
 }
 
+function formatCatalogAgentLine(agent: AgentConfig): string {
+	const parts: string[] = [agent.source, `context: ${agent.defaultContext ?? "fresh"}`];
+	if (agent.acceptanceRole) parts.push(`role: ${agent.acceptanceRole}`);
+	if (agent.aliases?.length) parts.push(`aliases: ${agent.aliases.join(", ")}`);
+	const tools = effectiveAgentTools(agent);
+	if (tools.length) parts.push(`tools: ${tools.join(", ")}`);
+	return `- ${agent.name} (${parts.join(", ")}): ${agent.description}`;
+}
+
+function catalogAgentMetadata(
+	agent: AgentConfig,
+	executable: boolean,
+	restrictionSources: string[] | undefined,
+): CatalogAgentMetadata {
+	return {
+		name: agent.name,
+		source: agent.source,
+		description: agent.description,
+		executable,
+		...(restrictionSources?.length ? { restrictionSources } : {}),
+		...(agent.aliases?.length ? { aliases: [...agent.aliases] } : {}),
+		defaultContext: agent.defaultContext ?? "fresh",
+		...(agent.acceptanceRole ? { acceptanceRole: agent.acceptanceRole } : {}),
+		tools: effectiveAgentTools(agent),
+	};
+}
+
 export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	const scope = normalizeListScope(params.agentScope) ?? "both";
 	const d = discoverAgentsAll(ctx.cwd);
@@ -690,23 +725,35 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 		config: ctx.config?.proactiveSkillSubagents,
 		discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
 	});
+	const taskAdvice = params.task?.trim()
+		? formatTaskAwareAgentRecommendation(recommendTaskAwareAgent({ task: params.task, agents, capabilityCeiling }))
+		: [];
 	const lines = [
 		"Executable agents:",
-		...(agents.length
-			? agents.map((a) => `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}${a.aliases?.length ? `, aliases: ${a.aliases.join(", ")}` : ""}): ${a.description}`)
-			: ["- (none)"]),
+		...(agents.length ? agents.map(formatCatalogAgentLine) : ["- (none)"]),
 		...(restrictedAgents.length ? [
 			"",
 			`Restricted agents (not executable in this session${restrictedSources?.length ? `; capability ceiling: ${restrictedSources.join(", ")}` : ""}):`,
-			...restrictedAgents.map((a) => `- ${a.name} (${a.source}${a.aliases?.length ? `, aliases: ${a.aliases.join(", ")}` : ""}): ${a.description}`),
+			...restrictedAgents.map(formatCatalogAgentLine),
 		] : []),
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
 		...(proactiveSuggestions.length ? ["", ...proactiveSuggestions] : []),
+		...(taskAdvice.length ? ["", ...taskAdvice] : []),
 		...(diagnostics.length ? ["", "Chain diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []),
 	];
-	return result(lines.join("\n"));
+	return result(lines.join("\n"), false, {
+		catalog: {
+			version: 1,
+			agents: [
+				...agents.map((a) => catalogAgentMetadata(a, true, undefined)),
+				...restrictedAgents.map((a) => catalogAgentMetadata(a, false, restrictedSources)),
+			],
+			chains: chains.map((c) => ({ name: c.name, source: c.source, description: c.description })),
+			...(restrictedSources?.length ? { capabilityCeilingSources: restrictedSources } : {}),
+		},
+	});
 }
 
 function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undefined): string {

package/dist/extensions/pi-subagents/src/agents/task-aware-routing.ts

@@ -0,0 +1,125 @@
+/**
+ * Pure task-aware advisory agent recommender.
+ *
+ * Given an already-discovered, effective agent set and the current capability
+ * ceiling, deterministically selects at most one canonical agent to recommend
+ * for a task, or returns recovery guidance when intent is unknown or no safe
+ * candidate exists. This module is deliberately pure: it performs no
+ * filesystem/discovery access, no alias/chains/executor/RPC/preflight/settings
+ * access, no mutation, launch, scheduling, or persistence, and never writes to
+ * params. Launching stays explicit: the caller must make a separate execution
+ * call with the recommended canonical `agent.name`.
+ */
+
+import type { AgentConfig, AgentSource } from "./agents.ts";
+import { agentHasWriteTools } from "./agent-memory.ts";
+import { classifyTaskMutationIntent, resolveAgentRoutingRole } from "../runs/shared/task-intent.ts";
+import { isAgentAllowedByCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
+
+/** Core tools that make an implementation agent able to write (matches agent-memory). */
+const WRITER_TOOLS = new Set(["edit", "write", "bash"]);
+
+/** Source precedence for deterministic ordering: project > user > package > builtin. */
+const AGENT_SOURCE_PRECEDENCE: Record<AgentSource, number> = { builtin: 0, package: 1, user: 2, project: 3 };
+
+export type TaskAwareAgentIntent = "implementation" | "read-only" | "unknown";
+
+export interface TaskAwareAgentRecommendationAgent {
+	/** Canonical runtime agent name accepted by execution; never an alias. */
+	name: string;
+	source: AgentSource;
+	role: "writer" | "read-only";
+	roleBasis: "declared" | "inferred";
+	reason: string;
+}
+
+export interface TaskAwareAgentRecommendation {
+	intent: TaskAwareAgentIntent;
+	agent?: TaskAwareAgentRecommendationAgent;
+	/** Recovery guidance when no safe recommendation exists (unknown intent or no candidate). */
+	next?: string;
+}
+
+/**
+ * Recommend a canonical agent for a trimmed non-empty task, or `undefined` for
+ * an empty/whitespace task (no-op). Never recommends disabled or
+ * capability-disallowed agents, never guesses for unknown intent, and never
+ * outputs an alias or a role-incompatible agent.
+ */
+export function recommendTaskAwareAgent(input: {
+	task: string;
+	agents: AgentConfig[];
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+}): TaskAwareAgentRecommendation | undefined {
+	const task = input.task.trim();
+	if (!task) return undefined;
+
+	const intent = classifyTaskMutationIntent("builder", task).kind;
+	if (intent === "unknown") {
+		return {
+			intent,
+			next: "Clarify whether the task is read-only analysis/review or implementation allowed to edit files.",
+		};
+	}
+
+	const candidates: TaskAwareAgentRecommendationAgent[] = [];
+	for (const agent of input.agents) {
+		if (agent.disabled) continue;
+		if (!isAgentAllowedByCapabilityCeiling(agent.name, input.capabilityCeiling)) continue;
+		const role = resolveAgentRoutingRole(agent.name, agent.acceptanceRole);
+		if (!role) continue;
+		const hasWriteTools = agentHasWriteTools(agent);
+		if (intent === "implementation") {
+			if (role !== "writer" || !hasWriteTools) continue;
+			const allowedTools = input.capabilityCeiling?.allowedTools;
+			if (allowedTools !== undefined && !allowedTools.some((tool) => WRITER_TOOLS.has(tool))) continue;
+		} else {
+			if (role !== "read-only" || hasWriteTools) continue;
+		}
+		const roleBasis = agent.acceptanceRole !== undefined ? "declared" : "inferred";
+		candidates.push({
+			name: agent.name,
+			source: agent.source,
+			role,
+			roleBasis,
+			reason: intent === "implementation"
+				? `${roleBasis} writer role with write tools`
+				: `${roleBasis} read-only role without known write tools`,
+		});
+	}
+
+	candidates.sort((a, b) => {
+		const sourceOrder = AGENT_SOURCE_PRECEDENCE[b.source] - AGENT_SOURCE_PRECEDENCE[a.source];
+		if (sourceOrder !== 0) return sourceOrder;
+		const declaredOrder = (a.roleBasis === "declared" ? 0 : 1) - (b.roleBasis === "declared" ? 0 : 1);
+		if (declaredOrder !== 0) return declaredOrder;
+		return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+	});
+
+	const agent = candidates[0];
+	if (!agent) {
+		return {
+			intent,
+			next: intent === "implementation"
+				? "No executable agent has a writer role with write tools for this task. Check the executable/restricted sections above or adjust the capability ceiling."
+				: "No executable agent has a read-only role without known write tools for this task. Check the executable/restricted sections above.",
+		};
+	}
+	return { intent, agent };
+}
+
+/** Text-only advisory lines; `undefined` (empty-task no-op) renders nothing. */
+export function formatTaskAwareAgentRecommendation(recommendation: TaskAwareAgentRecommendation | undefined): string[] {
+	if (!recommendation) return [];
+	const lines = ["Task-aware advisory routing:", `- Intent: ${recommendation.intent}`];
+	if (recommendation.agent) {
+		lines.push(`- Recommended: ${recommendation.agent.name} (${recommendation.agent.source})`);
+		lines.push(`- Reason: ${recommendation.agent.reason}`);
+		lines.push("- Advisory only: no subagent was launched. To proceed, explicitly call subagent with this canonical agent name and the task.");
+	} else {
+		lines.push("- Recommendation: none");
+		lines.push(`- Next: ${recommendation.next ?? "Refine the task wording and retry."}`);
+		lines.push("- Advisory only: no subagent was launched.");
+	}
+	return lines;
+}

package/dist/extensions/pi-subagents/src/api/preflight.ts

@@ -284,7 +284,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 		diagnostics.push({ code: "denied_required_tool", severity: "error", message });
 		return { ok: false, code: "denied_required_tool", message, diagnostics };
 	}
-	const artifactsEnabled = input.artifacts !== false;
+	const artifactsEnabled = input.artifacts === true;
 	const artifactsDir = artifactsEnabled ? getArtifactsDir(input.parentSessionFile ?? null, effectiveCwd, input.artifactDir ?? "project") : undefined;
 	const artifactPaths = artifactsDir ? getArtifactPaths(artifactsDir, runId, agent.name, 0) : undefined;
 	const outputPath = resolveSingleOutputPath(behavior.output, effectiveCwd, effectiveCwd, artifactsDir ? path.join(artifactsDir, "outputs", runId) : undefined);

package/dist/extensions/pi-subagents/src/extension/index.ts

@@ -51,7 +51,7 @@ import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/
 import { resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig } from "./config.ts";
-import { buildSubagentToolDescription } from "./tool-description.ts";
+import { buildSubagentToolDescription, SUBAGENT_PARENT_ROUTING_GUIDANCE } from "./tool-description.ts";
 import {
 	type Details,
 	type SubagentState,
@@ -405,6 +405,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		name: "subagent",
 		label: "Subagent",
 		description: buildSubagentToolDescription(config),
+		// Always-visible active-tool path: rendered into the main system prompt by
+		// buildSystemPrompt (default and custom-prompt branches). Parent-only; the
+		// child-safe fanout registration must not receive this guidance.
+		promptGuidelines: [SUBAGENT_PARENT_ROUTING_GUIDANCE],
 		parameters: SubagentParams,
 
 		prepareArguments(args) {

package/dist/extensions/pi-subagents/src/extension/schemas.ts

@@ -262,7 +262,7 @@ const ControlOverrides = Type.Object({
 
 const SubagentParamsSchema = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
-	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
+	task: Type.Optional(Type.String({ description: "Task for SINGLE-mode execution, or an optional advisory intent for action:'list' (list only appends a task-aware recommendation and never launches work; explicitly call subagent with the recommended canonical agent name and the task to execute)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
 		description: "Optional management/control action. Omit this field entirely for execution/delegation ({agent, task}, {tasks}, or {chain}); use it only for management/control actions."
@@ -321,7 +321,7 @@ const SubagentParamsSchema = Type.Object({
 	usageBudget: Type.Optional(UsageBudgetOverride),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),
-	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
+	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: false)" })),
 	includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
 	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
 	sessionDir: Type.Optional(

package/dist/extensions/pi-subagents/src/extension/tool-description.ts

@@ -6,13 +6,27 @@ import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
 const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
 
+/**
+ * Generic parent-only delegation routing contract. Deliberately contains no
+ * bundled agent names: agents are selected from runtime catalog metadata only.
+ * Attached to the parent `subagent` tool as promptGuidelines and embedded in
+ * the mandatory safety guidance so custom descriptions cannot remove it.
+ */
+export const SUBAGENT_PARENT_ROUTING_GUIDANCE = `PARENT-ONLY SUBAGENT ROUTING:
+• Before any execution, call { action: "list" } and select only an executable entry using its current role, context, and tool metadata.
+• Keep tiny targeted reads and simple answers local with the parent.
+• Send broad local investigation, external research, and mutation/implementation work to a capable delegated agent.
+• The parent remains the decision-maker and normally the sole writer.`;
+
 export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
 • Use { action: "list" } before execution and only run executable/non-disabled agents or chains.
 • Keep execution and management separate: omit action for SINGLE/PARALLEL/CHAIN execution; use action only for list/get/models/create/update/delete/status/grant-spawn-budget/interrupt/stop/resume/steer/append-step/approve-checkpoint/reject-checkpoint/doctor.
 • Async/background runs: launch with async:true only when work can proceed independently. Do not sleep or poll status just to wait. In an interactive session, normally return control and let Pi wake you; do not call subagent_wait merely to wait. Override that default and call subagent_wait when the current request is run-to-completion — for example, the user asked you to report results back before continuing or a skill must finish in one turn. Headless sessions auto-drain current-session work at agent_end; use subagent_wait when this turn must receive results before it ends.
 • Child-safety boundary: ordinary child subagents are not orchestrators and must not run subagents. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
 • Writing/review safety: keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers/validators for independent review, then have the parent synthesize and apply fixes as the sole writer unless an isolated worktree was intentionally requested.
-• Artifacts/status essentials: chain outputs live under {chain_dir}; async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Include output paths and residual risks when reporting results.`;
+• Artifacts/status essentials: chain outputs live under {chain_dir}; async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Normal delegated results are reference-first: completion returns saved-output references plus lifecycle/status information, not child prose — inspect full output through the saved output path, async status/transcript, or resume. Include output paths and residual risks when reporting results.
+
+${SUBAGENT_PARENT_ROUTING_GUIDANCE}`;
 
 export const FULL_SUBAGENT_TOOL_DESCRIPTION = `To delegate work, call with { agent, task }, { tasks }, or { chain }; omit action. Use action only for management/control actions listed below.
 
@@ -37,8 +51,9 @@ CHAIN EXAMPLES (quick reference for the nested schema):
 • Parallel fan-out: { chain: [{parallel: [{agent:"agent-a", task:"Check part of {task}", count: 3}]}] }
 • Mixed: { chain: [{agent:"agent-a", task:"Research {task}"}, {checkpoint:"review", message:"Approve implementation?"}, {parallel: [{agent:"agent-b", task:"Review {previous}", count: 2}]}, {agent:"agent-c", task:"Summarize {previous}"}] }
 
-MANAGEMENT (use action field, omit agent/task/chain/tasks):
+MANAGEMENT (use action field; omit agent/chain/tasks — the sole field exception is list's optional advisory task):
 • { action: "list" } - discover executable agents/chains
+• { action: "list", task: "..." } - same, plus optional task-aware advisory routing: recommends one canonical agent (implementation or read-only) for the task, or explains why none is safe. It only recommends and never launches; to proceed, explicitly call subagent with the recommended canonical agent name and the task.
 • { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
 • { action: "models", agent?: "name" } - show the runtime-loaded builtin subagent model mapping, optionally filtered to one builtin
 • { action: "watchdog.status" | "watchdog.check" | "watchdog.recommend-model" } - inspect the opt-in subagent watchdog and its strong complementary model recommendation
@@ -47,10 +62,10 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 • acceptanceRole affects inferred acceptance only, never tool access. Explicit task mutation/no-edit intent wins; omission preserves name heuristics. Update with false or an empty string to clear it.
 • { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
 • { action: "delete", agent: "code-analysis.custom-agent" }
-• { action: "eject", agent: "commentator", agentScope?: "user" | "project" } - copy a bundled/package agent to user/project scope as an editable custom file that shadows the original (default scope: user)
-• { action: "disable", agent: "commentator", agentScope?: "user" | "project" } - hide any agent from runtime discovery via a reversible settings override (default scope: user)
-• { action: "enable", agent: "commentator", agentScope?: "user" | "project" } - remove a disabled override and restore discovery
-• { action: "reset", agent: "commentator", agentScope?: "user" | "project" } - delete the scope's custom agent file and/or settings override, restoring the bundled default
+• { action: "eject", agent: "agent-name", agentScope?: "user" | "project" } - copy a bundled/package agent to user/project scope as an editable custom file that shadows the original (default scope: user)
+• { action: "disable", agent: "agent-name", agentScope?: "user" | "project" } - hide any agent from runtime discovery via a reversible settings override (default scope: user)
+• { action: "enable", agent: "agent-name", agentScope?: "user" | "project" } - remove a disabled override and restore discovery
+• { action: "reset", agent: "agent-name", agentScope?: "user" | "project" } - delete the scope's custom agent file and/or settings override, restoring the bundled default
 • { action: "grant-spawn-budget", additional: 10 } - add bounded capacity from the root interactive parent after native user confirmation; grants are rejected while children are active and cumulative grants cannot exceed the original configured cap
 • Use chainName for chain operations; packaged chains also use dotted runtime names
 
@@ -88,7 +103,8 @@ EXECUTE:
 • If list shows proactive skill subagent suggestions, use a small fresh-context fanout only when the task is broad enough.
 
 MANAGE / CONTROL:
-• Use action without execution fields: list, get, models, create, update, delete, eject, disable, enable, reset, grant-spawn-budget, doctor, watchdog.status, watchdog.check, watchdog.recommend-model, watchdog.configure.
+• Use action without execution fields (list may add an optional advisory task): list, get, models, create, update, delete, eject, disable, enable, reset, grant-spawn-budget, doctor, watchdog.status, watchdog.check, watchdog.recommend-model, watchdog.configure.
+• { action: "list", task: "..." } optionally appends task-aware advisory routing that recommends a canonical agent but never launches; execute the recommended agent explicitly in a separate call.
 • Agent acceptanceRole (read-only or writer) affects inferred acceptance only, never tools. Explicit task intent wins; omission keeps name heuristics. Update with false or an empty string to clear it.
 • Async control actions: status, interrupt, stop, resume, steer, append-step, approve-checkpoint, reject-checkpoint. Use stop with an id for current-session top-level async runs. Use status view:"fleet" for active-run overview, view:"transcript" to tail child output, steer for acknowledged top-level live async guidance, and resume for paused/completed/failed revival or a routed nested follow-up. Stopped runs are non-resumable. Steering delivery means Pi accepted the correlated user input, not model compliance; use index for a specific child.
 • Opt-in schedule actions: schedule, schedule-list, schedule-status, schedule-cancel. Schedule only explicit delayed runs the user asked for.
@@ -98,6 +114,7 @@ ASYNC / WAIT:
 • Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, session files, and { action:"status", id:"..." }.
 
 SAFETY:
+• Parent-only routing: call { action: "list" } before any execution and select only an executable entry using its current role, context, and tool metadata. Keep tiny targeted reads and simple answers local; send broad local investigation, external research, and mutation/implementation work to a capable delegated agent. The parent remains the decision-maker and normally the sole writer.
 • Ordinary child subagents are not orchestrators and must not run subagents. Only explicit fanout children may use child-safe subagent, still bounded by depth/session limits.
 • Keep one writer per cwd/worktree. Use fresh read-only review/validation fanout, then synthesize and apply fixes from the parent unless isolated worktrees were intentionally requested.`;
 

package/dist/extensions/pi-subagents/src/runs/background/async-execution.ts

@@ -686,9 +686,19 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const isFirstProgressAgent = behavior.progress && !progressPrecreated && !progressInstructionCreated;
 		if (behavior.progress) progressInstructionCreated = true;
 		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, progressDir, isFirstProgressAgent);
-		const outputPath = resolveSingleOutputPath(behavior.output, ctx.cwd, instructionCwd, outputBaseDir);
+		const explicitOutput = typeof behavior.output === "string" ? behavior.output : undefined;
+		// Omitted output generates a collision-safe per-child durable path
+		// `<asyncDir>/outputs/<flat-index>-<agent>.md`; omitted outputMode resolves
+		// to file-only whenever an output path is active. Explicit paths,
+		// `output: false`, and explicit `outputMode: "inline"` are preserved.
+		const outputPath = explicitOutput
+			? resolveSingleOutputPath(explicitOutput, ctx.cwd, instructionCwd, outputBaseDir)
+			: behavior.output === false && s.output !== false && s.output !== "false" && flatIndex !== undefined
+				? path.join(asyncDir, "outputs", `${flatIndex}-${s.agent}.md`)
+				: undefined;
 		if (!namespaceOutputPath) systemPrompt = injectOutputPathSystemPrompt(systemPrompt, outputPath, a);
-		const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${s.agent})`);
+		const effectiveOutputMode = s.outputMode ?? (outputPath ? "file-only" : "inline");
+		const validationError = validateFileOnlyOutputMode(effectiveOutputMode, outputPath, `Async step (${s.agent})`);
 		if (validationError) throw new AsyncStartValidationError(validationError);
 		let taskTemplate = s.task ?? "{previous}";
 		taskTemplate = taskTemplate.replace(/\{task\}/g, originalTask ?? "");
@@ -751,7 +761,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			skills: resolvedSkills.map((r) => r.name),
 			outputPath,
 			...(namespaceOutputPath ? { namespaceOutputPath: true } : {}),
-			outputMode: behavior.outputMode,
+			outputMode: effectiveOutputMode,
 			sessionFile,
 			maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, a.maxSubagentDepth),
 			waitToolEnabled: params.waitToolEnabled,
@@ -1228,9 +1238,17 @@ export function executeAsyncSingle(
 	}
 
 	const effectiveOutput = normalizeSingleOutputOverride(params.output, agentConfig.output);
-	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd, params.outputBaseDir ?? (artifactsDir ? path.join(artifactsDir, "outputs", id) : undefined));
+	// Omitted output resolves to a generated per-run durable path
+	// `<asyncDir>/outputs/0-<agent>.md`; omitted outputMode resolves to file-only
+	// whenever an output path is active. Explicit paths, `output: false`, and
+	// explicit `outputMode: "inline"` are preserved exactly.
+	const outputPath = typeof effectiveOutput === "string"
+		? resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd, params.outputBaseDir ?? (artifactsDir ? path.join(artifactsDir, "outputs", id) : undefined))
+		: effectiveOutput === false
+			? undefined
+			: path.join(asyncDir, "outputs", `0-${agent}.md`);
 	systemPrompt = injectOutputPathSystemPrompt(systemPrompt, outputPath, agentConfig);
-	const outputMode = params.outputMode ?? "inline";
+	const outputMode = params.outputMode ?? (outputPath ? "file-only" : "inline");
 	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
 	if (validationError) return formatAsyncStartError("single", validationError);
 	const taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath, agentConfig);

package/dist/extensions/pi-subagents/src/runs/background/notify.ts

@@ -192,6 +192,32 @@ function completionBatchKey(result: CompletionNotification): string {
 	return cwd ? `cwd:${cwd}` : "unknown";
 }
 
+/**
+ * Reference-first notification preview: compact child summaries built by the
+ * result watcher from each child's authoritative output path/log. Never uses
+ * `results[].output` or the run-level `summary` as parent-facing text; the run
+ * summary remains only a defensive fallback for legacy payloads without results.
+ */
+function buildReferenceFirstPreview(result: CompletionNotification): string {
+	const children = Array.isArray(result.results) ? result.results : [];
+	if (children.length === 0) {
+		return typeof result.summary === "string" ? result.summary : "";
+	}
+	if (children.length === 1) {
+		const childSummary = typeof children[0]?.summary === "string" && children[0].summary.trim()
+			? children[0].summary
+			: "(no output)";
+		return childSummary;
+	}
+	return children.map((child, index) => {
+		const agentLabel = typeof child?.agent === "string" ? child.agent : `step-${index + 1}`;
+		const childSummary = typeof child?.summary === "string" && child.summary.trim()
+			? child.summary
+			: "(no output)";
+		return `${index + 1}. ${agentLabel}\n${childSummary}`;
+	}).join("\n\n");
+}
+
 export function buildCompletionDetails(result: CompletionNotification): SubagentNotifyDetails {
 	const agent = result.agent ?? "unknown";
 	const summary = typeof result.summary === "string" ? result.summary : "";
@@ -229,7 +255,7 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		status,
 		...(result.source ? { source: result.source } : {}),
 		...(taskInfo ? { taskInfo } : {}),
-		resultPreview: summary,
+		resultPreview: buildReferenceFirstPreview(result),
 		...(typeof result.durationMs === "number" ? { durationMs: result.durationMs } : {}),
 		...(handoffPath ? { handoffPath } : {}),
 		...(session ? { sessionLabel: session.label, sessionValue: session.value } : {}),

package/dist/extensions/pi-subagents/src/runs/background/result-watcher.ts

@@ -20,6 +20,7 @@ import {
 } from "../../intercom/result-intercom.ts";
 import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-events.ts";
 import { resolveWatchPath } from "../../shared/utils.ts";
+import { formatBoundedPersistenceFallback, formatSavedOutputReference } from "../shared/single-output.ts";
 import type { CompletionNotifier, CompletionNotification } from "./notify.ts";
 
 const WATCHER_RESTART_DELAY_MS = 3000;
@@ -46,10 +47,14 @@ type ResultWatcherDeps = {
 type ResultFileChild = {
 	agent?: string;
 	output?: string;
+	/** Authoritative durable output location: explicit/generated saved path or async output log. */
+	outputPath?: string;
+	savedOutputPath?: string;
 	outputState?: SubagentOutputState;
 	error?: string;
 	success?: boolean;
 	state?: string;
+	exitCode?: number | null;
 	interrupted?: boolean;
 	timedOut?: boolean;
 	stopped?: boolean;
@@ -92,6 +97,57 @@ function isNotFound(error: unknown): boolean {
 	return errorCode(error) === "ENOENT";
 }
 
+/**
+ * Resolve the authoritative output location for one async child: explicit/generated
+ * saved output path first, else the persisted per-child output log
+ * (`asyncDir/output-<flat-index>.log`). Legacy result files without saved-path
+ * fields fall back to the output log when the run directory is known.
+ */
+function childOutputPath(data: ResultFileData, result: ResultFileChild | undefined, index: number): string | undefined {
+	if (typeof result?.outputPath === "string" && result.outputPath.trim()) return result.outputPath;
+	if (typeof result?.savedOutputPath === "string" && result.savedOutputPath.trim()) return result.savedOutputPath;
+	if (typeof data.asyncDir === "string" && data.asyncDir.trim()) return path.join(data.asyncDir, `output-${index}.log`);
+	return undefined;
+}
+
+/**
+ * Reference-only child summary for async delivery: the saved-output reference
+ * (or output-log reference) plus process error/status for failed children. Never
+ * emits `results[].output` or the run `summary` as parent-facing text; when the
+ * output location is absent or unreadable, a bounded fallback is used instead.
+ */
+function buildChildReferenceSummary(fsApi: ResultWatcherFs, input: {
+	outputPath: string | undefined;
+	outputText: string;
+	exitCode: number;
+	error?: string;
+}): string {
+	const statusError = input.exitCode !== 0 && input.error ? input.error : undefined;
+	if (input.outputPath) {
+		try {
+			const content = fsApi.readFileSync(input.outputPath, "utf-8");
+			const ref = formatSavedOutputReference(input.outputPath, content);
+			return statusError ? `${statusError}\n\n${ref.message}` : ref.message;
+		} catch (error) {
+			const fallback = formatBoundedPersistenceFallback({
+				error: `Failed to read saved output: ${error instanceof Error ? error.message : String(error)}`,
+				outputPath: input.outputPath,
+				fullOutput: input.outputText,
+				exitCode: input.exitCode,
+				processError: input.error,
+			});
+			return statusError ? `${statusError}\n\n${fallback}` : fallback;
+		}
+	}
+	const fallback = formatBoundedPersistenceFallback({
+		error: "No saved output path is available for this child.",
+		fullOutput: input.outputText,
+		exitCode: input.exitCode,
+		processError: input.error,
+	});
+	return statusError ? `${statusError}\n\n${fallback}` : fallback;
+}
+
 function shouldPoll(error: unknown): boolean {
 	const code = errorCode(error);
 	return code === "EMFILE" || code === "ENOSPC";
@@ -180,14 +236,16 @@ export function createResultWatcher(
 			const hasResultChildren = Array.isArray(data.results) && data.results.length > 0;
 			const resultChildren: ResultFileChild[] = hasResultChildren
 				? data.results!
-				: [{ agent: data.agent ?? undefined, output: data.summary, outputState: "unknown", success: data.success }];
+				: [{ agent: data.agent ?? undefined, outputPath: childOutputPath(data, undefined, 0), outputState: "unknown", success: data.success }];
 			const normalizedChildren = attachNestedChildrenToResultChildren(runId, resultChildren.map((result = {}, index): SubagentResultIntercomChild => {
 				const baseOutput = hasResultChildren ? result.output : result.output ?? data.summary;
-				const hasRealOutput = typeof baseOutput === "string" && baseOutput.trim().length > 0;
-				const output = hasRealOutput ? baseOutput : "(no output)";
-				const summary = result.success === false && result.error
-					? `${result.error}${hasRealOutput ? `\n\nOutput:\n${baseOutput}` : ""}`
-					: output;
+				const outputText = typeof baseOutput === "string" ? baseOutput : "";
+				const summary = buildChildReferenceSummary(fsApi, {
+					outputPath: childOutputPath(data, result, index),
+					outputText,
+					exitCode: result.success === false ? 1 : result.success === true ? 0 : typeof result.exitCode === "number" ? result.exitCode : data.success === false ? 1 : 0,
+					error: result.error ?? (result.success === false ? (typeof data.error === "string" ? data.error : undefined) : undefined),
+				});
 				const sessionPath = result.sessionFile ?? (resultChildren.length === 1 ? data.sessionFile : undefined);
 				const childNestedChildren = sanitizeNestedResultChildren(result.children, resultPath, `results[${index}].children`);
 				const childState = result.state === "paused" || result.state === "stopped"

package/dist/extensions/pi-subagents/src/runs/background/subagent-runner.ts

@@ -1476,7 +1476,11 @@ async function runSingleStep(
 
 	const rawOutput = finalResult?.finalOutput ?? "";
 	const outputForPersistence = stripAcceptanceReport(rawOutput);
-	const resolvedOutput = step.outputPath && finalResult?.exitCode === 0
+	// Persist whenever an output path is configured and meaningful output exists,
+	// not only for successful runs: failed children keep a readable result file
+	// and a saved-output reference instead of raw inline output. Synthetic
+	// failures without output stay "absent" and are not promoted to a reference.
+	const resolvedOutput = step.outputPath && (outputForPersistence.trim() || (finalResult?.exitCode ?? 1) === 0)
 		? resolveSingleOutput(step.outputPath, outputForPersistence, finalOutputSnapshot)
 		: { fullOutput: outputForPersistence };
 	const output = stripAcceptanceReport(resolvedOutput.fullOutput);
@@ -1515,6 +1519,9 @@ async function runSingleStep(
 		savedPath: resolvedOutput.savedPath,
 		outputReference,
 		saveError: resolvedOutput.saveError,
+		error: finalResult?.error
+			?? (finalResult?.stopped ? ctx.stopMessage ?? "Subagent stopped by user." : undefined)
+			?? (finalResult?.timedOut ? ctx.timeoutMessage ?? "Subagent timed out." : undefined),
 	});
 	outputForSummary = finalizedOutput.displayOutput;
 	const acceptance = step.effectiveAcceptance && !finalResult?.stopped && !finalResult?.turnBudgetExceeded && !ctx.timeoutSignal?.aborted && !ctx.stopSignal?.aborted && !ctx.skipAcceptance?.()
@@ -1596,6 +1603,10 @@ async function runSingleStep(
 		context: step.context,
 		...(step.agentContract ? { agentContract: step.agentContract } : {}),
 		launchContractDigest: actualLaunchContractDigest,
+		// Authoritative durable output location for parent-facing delivery: the
+		// explicit/generated saved output path when present, otherwise the async
+		// per-child output log (`asyncDir/output-<flat-index>.log`).
+		outputPath: step.outputPath ?? ctx.outputFile,
 		output: outputForSummary,
 		outputState,
 		exitCode: effectiveFinalExitCode,
@@ -3388,6 +3399,7 @@ async function runSubagent(
 					launchResolvedExtensions: pr.launchResolvedExtensions,
 					runtimeAcknowledgedExtensions: pr.runtimeAcknowledgedExtensions,
 					output: pr.output,
+					outputPath: pr.outputPath,
 					outputState: pr.outputState,
 					error: pr.error,
 					protocolError: pr.protocolError,
@@ -3797,6 +3809,7 @@ async function runSubagent(
 						launchContractDigest: pr.launchContractDigest,
 						launchResolvedExtensions: pr.launchResolvedExtensions,
 						output: pr.output,
+						outputPath: pr.outputPath,
 						outputState: pr.outputState,
 						error: pr.error,
 						protocolError: pr.protocolError,
@@ -3984,6 +3997,7 @@ async function runSubagent(
 				launchResolvedExtensions: singleResult.launchResolvedExtensions,
 				runtimeAcknowledgedExtensions: singleResult.runtimeAcknowledgedExtensions,
 				output: stopped || childStopped ? stopMessage : timedOut ? (timeoutMessage ?? "Subagent timed out.") : singleResult.output,
+				outputPath: singleResult.outputPath,
 				outputState: singleResult.outputState,
 				error: stopped || childStopped ? stopMessage : timedOut ? (timeoutMessage ?? "Subagent timed out.") : singleResult.error,
 				protocolError: singleResult.protocolError,
@@ -4311,6 +4325,7 @@ async function runSubagent(
 			results: results.map((r) => ({
 				agent: r.agent,
 				context: r.context,
+				outputPath: r.outputPath,
 				output: r.output,
 				outputState: r.outputState,
 				error: r.error,