@selesai/code 0.5.28 → 0.6.1

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

@@ -57,6 +57,7 @@ export function defaultInheritSkills(): boolean {
 }
 
 export interface BuiltinAgentOverrideBase {
+	description?: string;
 	model?: string;
 	fallbackModels?: string[];
 	thinking?: string | false;
@@ -78,6 +79,7 @@ export interface BuiltinAgentOverrideBase {
 }
 
 interface BuiltinAgentOverrideConfig {
+	description?: string;
 	model?: string | false;
 	fallbackModels?: string[] | false;
 	thinking?: string | false;
@@ -114,6 +116,7 @@ export interface AgentConfig {
 	localName?: string;
 	packageName?: string;
 	description: string;
+	aliases?: string[];
 	tools?: string[];
 	mcpDirectTools?: string[];
 	model?: string;
@@ -150,6 +153,8 @@ export interface AgentConfig {
 	modelSource?: AgentModelSourceInfo;
 }
 
+type ProjectRootResolution = "nearest" | "git-root";
+
 interface SubagentSettings {
 	overrides: Record<string, BuiltinAgentOverrideConfig>;
 	defaultModel?: string;
@@ -420,7 +425,7 @@ function collectSettingsPackageRoots(settingsFile: string, baseDir: string): str
 
 function collectPackageSubagentPaths(cwd: string, options: { includeUser: boolean; includeProject: boolean } = { includeUser: true, includeProject: true }): PackageSubagentPaths {
 	const agentDir = getAgentDir();
-	const projectRoot = findNearestProjectRoot(cwd) ?? cwd;
+	const projectRoot = findConfiguredProjectRoot(cwd) ?? cwd;
 	const packageRoots = [
 		projectRoot,
 	];
@@ -469,6 +474,41 @@ function collectPackageSubagentPaths(cwd: string, options: { includeUser: boolea
 	return { agents, chains };
 }
 
+function normalizeAgentAliases(rawAliases: string[] | undefined, agentName: string): string[] | undefined {
+	const aliases = [...new Set((rawAliases ?? []).map((alias) => alias.trim()).filter(Boolean))]
+		.filter((alias) => alias !== agentName);
+	return aliases.length > 0 ? aliases : undefined;
+}
+
+function effectiveAgentMatch(matches: AgentConfig[]): { agent?: AgentConfig; error?: string } {
+	const distinctNames = [...new Set(matches.map((agent) => agent.name))];
+	if (distinctNames.length === 1) {
+		const sourceRank = new Map<AgentConfig["source"], number>([["builtin", 0], ["package", 1], ["user", 2], ["project", 3]]);
+		return { agent: [...matches].sort((a, b) => (sourceRank.get(b.source) ?? 0) - (sourceRank.get(a.source) ?? 0))[0] };
+	}
+	return {};
+}
+
+export function resolveAgentName(name: string, agents: AgentConfig[]): { agent?: AgentConfig; error?: string } {
+	const raw = name.trim();
+	const exact = agents.filter((agent) => agent.name === raw || agent.localName === raw);
+	if (exact.length === 1) return { agent: exact[0] };
+	if (exact.length > 1) {
+		const effective = effectiveAgentMatch(exact);
+		if (effective.agent) return effective;
+		return { error: `Ambiguous agent name '${name}': ${exact.map((agent) => agent.name).join(", ")}` };
+	}
+
+	const aliases = agents.filter((agent) => agent.aliases?.includes(raw));
+	if (aliases.length === 1) return { agent: aliases[0] };
+	if (aliases.length > 1) {
+		const effective = effectiveAgentMatch(aliases);
+		if (effective.agent) return effective;
+		return { error: `Ambiguous agent alias '${name}': ${aliases.map((agent) => agent.name).join(", ")}` };
+	}
+	return {};
+}
+
 function splitToolList(rawTools: string[] | undefined): { tools?: string[]; mcpDirectTools?: string[] } {
 	const mcpDirectTools: string[] = [];
 	const tools: string[] = [];
@@ -505,6 +545,7 @@ function arraysEqual(a: string[] | undefined, b: string[] | undefined): boolean
 
 function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 	return {
+		description: agent.description,
 		model: agent.model,
 		fallbackModels: agent.fallbackModels ? [...agent.fallbackModels] : undefined,
 		thinking: agent.thinking,
@@ -528,6 +569,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 
 function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentOverrideConfig {
 	return {
+		...(override.description !== undefined ? { description: override.description } : {}),
 		...(override.model !== undefined ? { model: override.model } : {}),
 		...(override.fallbackModels !== undefined
 			? { fallbackModels: override.fallbackModels === false ? false : [...override.fallbackModels] }
@@ -549,12 +591,26 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 	};
 }
 
-export function findNearestProjectRoot(cwd: string): string | null {
+function isProjectRootCandidate(dir: string): boolean {
+	return isDirectory(getProjectConfigDir(dir)) || isDirectory(path.join(dir, ".agents"));
+}
+
+function findProjectRootCandidates(cwd: string): string[] {
+	const roots: string[] = [];
 	let currentDir = cwd;
 	while (true) {
-		if (isDirectory(getProjectConfigDir(currentDir)) || isDirectory(path.join(currentDir, ".agents"))) {
-			return currentDir;
-		}
+		if (isProjectRootCandidate(currentDir)) roots.push(currentDir);
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return roots;
+		currentDir = parentDir;
+	}
+}
+
+function findNearestGitRoot(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		if (fs.existsSync(path.join(currentDir, ".git"))) return currentDir;
 
 		const parentDir = path.dirname(currentDir);
 		if (parentDir === currentDir) return null;
@@ -562,12 +618,46 @@ export function findNearestProjectRoot(cwd: string): string | null {
 	}
 }
 
+function readProjectRootResolution(projectRoot: string): ProjectRootResolution | undefined {
+	const settingsPath = path.join(getProjectConfigDir(projectRoot), "settings.json");
+	if (!fs.existsSync(settingsPath)) return undefined;
+	const settings = readSettingsFileStrict(settingsPath);
+	const subagents = settings.subagents;
+	if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return undefined;
+
+	const value = (subagents as Record<string, unknown>).projectRootResolution;
+	if (value === undefined) return undefined;
+	if (value === "nearest" || value === "git-root") return value;
+	throw new Error(`Subagent settings in '${settingsPath}' have invalid 'projectRootResolution'; expected 'nearest' or 'git-root'.`);
+}
+
+export function findNearestProjectRoot(cwd: string): string | null {
+	return findProjectRootCandidates(cwd)[0] ?? null;
+}
+
+function findConfiguredProjectRoot(cwd: string): string | null {
+	const candidates = findProjectRootCandidates(cwd);
+	const nearestRoot = candidates[0];
+	if (!nearestRoot) return null;
+
+	const nearestMode = readProjectRootResolution(nearestRoot);
+	if (nearestMode === "nearest") return nearestRoot;
+
+	const gitRoot = findNearestGitRoot(cwd);
+	const gitProjectRoot = gitRoot ? candidates.find((candidate) => path.resolve(candidate) === path.resolve(gitRoot)) : undefined;
+	if (gitProjectRoot && (nearestMode === "git-root" || readProjectRootResolution(gitProjectRoot) === "git-root")) {
+		return gitProjectRoot;
+	}
+
+	return nearestRoot;
+}
+
 function getUserAgentSettingsPath(): string {
 	return path.join(getAgentDir(), "settings.json");
 }
 
 function getProjectAgentSettingsPath(cwd: string): string | null {
-	const projectRoot = findNearestProjectRoot(cwd);
+	const projectRoot = findConfiguredProjectRoot(cwd);
 	return projectRoot ? path.join(getProjectConfigDir(projectRoot), "settings.json") : null;
 }
 
@@ -632,6 +722,14 @@ function parseBuiltinOverrideEntry(
 	const input = value as Record<string, unknown>;
 	const override: BuiltinAgentOverrideConfig = {};
 
+	if ("description" in input) {
+		if (typeof input.description === "string" && input.description.trim()) {
+			override.description = input.description.trim();
+		} else {
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'description'; expected a non-empty string.`);
+		}
+	}
+
 	if ("model" in input) {
 		if (typeof input.model === "string" || input.model === false) override.model = input.model;
 		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'model'; expected a string or false.`);
@@ -879,6 +977,7 @@ function applyBuiltinOverride(
 		override: { ...meta, base: cloneOverrideBase(agent) },
 	};
 
+	if (override.description !== undefined) next.description = override.description;
 	if (override.model !== undefined) next.model = override.model === false ? undefined : override.model;
 	if (override.fallbackModels !== undefined) {
 		next.fallbackModels = override.fallbackModels === false ? undefined : [...override.fallbackModels];
@@ -999,6 +1098,10 @@ function applyCustomAgentOverride(
 		anyFilled = true;
 	};
 
+	if (override.description !== undefined) {
+		mutable().description = override.description;
+		anyFilled = true;
+	}
 	if (override.model !== undefined) {
 		fill("model", ["model"], override.model === false ? undefined : override.model);
 	}
@@ -1089,10 +1192,14 @@ function applyCustomAgentOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget">,
+	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget"> & Partial<Pick<AgentConfig, "description">>,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
+	if (draft.description !== undefined) {
+		const description = draft.description.trim();
+		if (description && description !== base.description) override.description = description;
+	}
 	if (draft.model !== base.model) override.model = draft.model ?? false;
 	if (!arraysEqual(draft.fallbackModels, base.fallbackModels)) override.fallbackModels = draft.fallbackModels ? [...draft.fallbackModels] : false;
 	if (draft.thinking !== base.thinking) override.thinking = draft.thinking ?? false;
@@ -1333,6 +1440,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		const tools = parsedTools.tools ?? [];
 		const mcpDirectTools = parsedTools.mcpDirectTools ?? [];
 		const defaultReads = parseFrontmatterList(frontmatter.defaultReads);
+		const aliases = normalizeAgentAliases(parseFrontmatterList(frontmatter.aliases ?? frontmatter.alias), runtimeName);
 		const skillStr = frontmatter.skill || frontmatter.skills;
 		const skills = parseFrontmatterList(skillStr);
 		const skillPath = parseFrontmatterList(frontmatter.skillPath);
@@ -1413,6 +1521,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			localName,
 			packageName,
 			description: frontmatter.description,
+			aliases,
 			tools: rawTools !== undefined ? tools : undefined,
 			mcpDirectTools: mcpDirectTools.length > 0 ? mcpDirectTools : undefined,
 			model: frontmatter.model,
@@ -1489,7 +1598,7 @@ function isDirectory(p: string): boolean {
 }
 
 function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; preferredDir: string | null } {
-	const projectRoot = findNearestProjectRoot(cwd);
+	const projectRoot = findConfiguredProjectRoot(cwd);
 	if (!projectRoot) return { readDirs: [], preferredDir: null };
 
 	const legacyDir = path.join(projectRoot, ".agents");
@@ -1505,7 +1614,7 @@ function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; pref
 }
 
 function resolveNearestProjectChainDirs(cwd: string): { readDirs: string[]; preferredDir: string | null } {
-	const projectRoot = findNearestProjectRoot(cwd);
+	const projectRoot = findConfiguredProjectRoot(cwd);
 	if (!projectRoot) return { readDirs: [], preferredDir: null };
 
 	const preferredDir = path.join(getProjectConfigDir(projectRoot), "chains");

package/dist/extensions/pi-subagents/src/agents/skills.ts

@@ -379,19 +379,21 @@ function chooseHigherPrioritySkill(existing: CachedSkillEntry | undefined, candi
 	return candidate.order < existing.order ? candidate : existing;
 }
 
-function maybeReadSkillDescription(filePath: string): string | undefined {
-	try {
-		const content = fs.readFileSync(filePath, "utf-8");
-		const normalized = content.replace(/\r\n/g, "\n");
-		if (!normalized.startsWith("---")) return undefined;
+function parseSkillDescription(content: string): string | undefined {
+	const normalized = content.replace(/\r\n/g, "\n");
+	if (!normalized.startsWith("---")) return undefined;
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) return undefined;
 
-		const endIndex = normalized.indexOf("\n---", 3);
-		if (endIndex === -1) return undefined;
+	const frontmatter = normalized.slice(3, endIndex).trim();
+	const match = frontmatter.match(/^description:\s*(.+)$/m);
+	return match?.[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+}
 
-		const frontmatter = normalized.slice(3, endIndex).trim();
-		const match = frontmatter.match(/^description:\s*(.+)$/m);
-		if (!match) return undefined;
-		return match[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+function maybeReadSkillDescription(filePath: string): string | undefined {
+	try {
+		return parseSkillDescription(fs.readFileSync(filePath, "utf-8"));
 	} catch {
 		// Description parsing is best-effort metadata extraction.
 		return undefined;
@@ -585,7 +587,7 @@ function readSkill(
 
 		const raw = fs.readFileSync(skillPath, "utf-8");
 		const content = stripSkillFrontmatter(raw);
-		const description = maybeReadSkillDescription(skillPath);
+		const description = parseSkillDescription(raw);
 		const skill: ResolvedSkill = {
 			name: skillName,
 			path: skillPath,

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/delegation.ts

@@ -131,6 +131,7 @@ export interface SubagentDelegationStarted {
 }
 
 export interface SubagentDelegationUpdate extends SubagentDelegationStarted {
+	runId?: string;
 	currentTool?: string;
 	currentToolArgs?: string;
 	recentOutput?: string;
@@ -230,6 +231,7 @@ export interface SubagentDelegationV2Started {
 }
 
 export interface SubagentDelegationV2Update extends SubagentDelegationV2Started {
+	runId?: string;
 	currentTool?: string;
 	currentToolArgs?: string;
 	recentOutput?: string;
@@ -266,6 +268,7 @@ export interface SubagentDelegationV2TerminalResponse extends SubagentDelegation
 	model?: string;
 	thinking?: string;
 	exitCode?: number;
+	launchContractDigest?: string;
 	result?: SubagentDelegationV2Value;
 	usage?: SubagentDelegationV2Usage;
 }

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

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { discoverAgents, discoverAgentsAll, type AgentConfig, type AgentScope, type AgentSource } from "../agents/agents.ts";
+import { discoverAgents, discoverAgentsAll, resolveAgentName, type AgentConfig, type AgentScope, type AgentSource } from "../agents/agents.ts";
 import { resolveExecutionAgentScope } from "../agents/agent-scope.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../agents/skills.ts";
 import { buildAgentMemoryInjection } from "../agents/agent-memory.ts";
@@ -12,7 +12,7 @@ import { injectOutputPathSystemPrompt, normalizeSingleOutputOverride, resolveSin
 import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveEffectiveThinking } from "../shared/model-info.ts";
 import { SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, type ArtifactDirPreference, type ArtifactPaths, type JsonSchemaObject, type OutputMode } from "../shared/types.ts";
-import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
+import { capabilityCeilingAgentRestrictionMessage, intersectSubagentCapabilityCeilings, type ResolvedSubagentCapabilityCeiling, type SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
 import { appendTurnBudgetSystemPrompt } from "../runs/shared/turn-budget.ts";
 import type { ResolvedTurnBudget } from "../shared/types.ts";
 import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
@@ -31,7 +31,8 @@ export type SubagentLaunchContractReasonCode =
 	| "denied_required_tool"
 	| "invalid_artifact_dir"
 	| "invalid_cwd"
-	| "unsupported_mode";
+	| "unsupported_mode"
+	| "restricted_agent";
 
 export interface SubagentLaunchContractDiagnostic {
 	code: SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning";
@@ -191,7 +192,7 @@ function normalizeAvailableModels(models: SubagentLaunchContractInput["available
 function candidateList(inputAgent: string, selected: AgentConfig | undefined, cwd: string): SubagentLaunchContractAgentCandidate[] {
 	const all = discoverAgentsAll(cwd);
 	return [...all.builtin, ...all.package, ...all.user, ...all.project]
-		.filter((agent) => agent.name === inputAgent || agent.localName === inputAgent)
+		.filter((agent) => Boolean(resolveAgentName(inputAgent, [agent]).agent))
 		.map((agent) => ({
 			name: agent.name,
 			...(agent.localName ? { localName: agent.localName } : {}),
@@ -225,14 +226,17 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 	}
 	const scope = resolveExecutionAgentScope(input.agentScope);
 	const discovered = discoverAgents(effectiveCwd, scope);
-	const matches = discovered.agents.filter((agent) => agent.name === input.agent || agent.localName === input.agent);
-	if (matches.length === 0) {
-		return { ok: false, code: "missing_agent", message: `Unknown agent: ${input.agent}`, diagnostics };
+	const resolvedAgent = resolveAgentName(input.agent, discovered.agents);
+	if (resolvedAgent.error) {
+		return { ok: false, code: "ambiguous_agent", message: resolvedAgent.error, diagnostics };
 	}
-	if (matches.length > 1) {
-		return { ok: false, code: "ambiguous_agent", message: `Ambiguous agent: ${input.agent}`, diagnostics };
+	if (!resolvedAgent.agent) {
+		return { ok: false, code: "missing_agent", message: `Unknown agent: ${input.agent}`, diagnostics };
 	}
-	const agent = matches[0]!;
+	const agent = resolvedAgent.agent;
+	const effectiveCapabilityCeiling = intersectSubagentCapabilityCeilings(input.capabilityCeiling, input.inheritedCapabilityCeiling);
+	const restrictionMessage = capabilityCeilingAgentRestrictionMessage(agent.name, effectiveCapabilityCeiling);
+	if (restrictionMessage) return { ok: false, code: "restricted_agent", message: restrictionMessage, diagnostics };
 	const runId = input.runId ?? "preflight";
 	const skillInput = normalizeSkillInput(input.skill);
 	const outputOverride = normalizeSingleOutputOverride(input.output, agent.output);
@@ -272,15 +276,15 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 			cwd: effectiveCwd,
 			requireReadTool: resolvedSkills.resolved.length > 0,
 			structuredOutput: Boolean(input.outputSchema),
-			capabilityCeiling: input.capabilityCeiling,
-			inheritedCapabilityCeiling: input.inheritedCapabilityCeiling,
+			capabilityCeiling: effectiveCapabilityCeiling,
+			agentName: agent.name,
 		});
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		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/chain-validation.ts

@@ -43,7 +43,7 @@ export const EXPAND_KEYS = allowedKeysOf(DynamicExpandSchema);
 export const EXPAND_FROM_KEYS = allowedKeysOf(ExpandFromSchema);
 export const COLLECT_KEYS = allowedKeysOf(DynamicCollectSchema);
 
-const CHAIN_STEP_EXAMPLE = '{"agent": "builder", "task": "do X"}';
+const CHAIN_STEP_EXAMPLE = '{"agent": "builder", "task": "do X"} or {"checkpoint": "review", "message": "Approve before implementation?"}';
 const PARALLEL_TASK_EXAMPLE = '{"agent": "builder", "task": "do X"}';
 const DYNAMIC_TEMPLATE_EXAMPLE = '{"agent": "builder", "task": "Review {item.path}"}';
 const EXPAND_EXAMPLE = '{"from": {"output": "targets", "path": "/items"}, "maxItems": 4}';
@@ -58,6 +58,21 @@ function disallowedKeys(value: Record<string, unknown>, allowed: readonly string
 	return Object.keys(value).filter((key) => !allowed.includes(key));
 }
 
+function validateCheckpointShape(step: Record<string, unknown>, path: string): void {
+	if (step.checkpoint === undefined) return;
+	const allowed = new Set(["checkpoint", "message", "phase", "label"]);
+	const mixed = Object.keys(step).filter((key) => !allowed.has(key));
+	if (mixed.length > 0) {
+		throw new Error(`subagent ${path}: checkpoint steps cannot be mixed with child-launch properties ${quoteList(mixed)}.\n\nExample: {"checkpoint": "review", "message": "Approve before implementation?"}`);
+	}
+	if (typeof step.checkpoint !== "string" || !step.checkpoint.trim()) {
+		throw new Error(`subagent ${path}.checkpoint: expected a non-empty string.`);
+	}
+	if (step.message !== undefined && typeof step.message !== "string") {
+		throw new Error(`subagent ${path}.message: expected a string.`);
+	}
+}
+
 function typeName(value: unknown): string {
 	if (Array.isArray(value)) return "array";
 	return typeof value;
@@ -120,6 +135,7 @@ export function validateChainInput(args: unknown): void {
 		const stepPath = `chain step validation failed at chain[${index}]`;
 		expectObject(step, stepPath, CHAIN_STEP_KEYS, CHAIN_STEP_EXAMPLE);
 		checkNoExtraKeys(step, stepPath, ChainItem, CHAIN_STEP_KEYS, CHAIN_STEP_EXAMPLE);
+		validateCheckpointShape(step, stepPath);
 
 		if (step.expand !== undefined) {
 			const expandPath = `${stepPath}.expand`;

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

@@ -27,7 +27,7 @@ import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult } from "../tui/render.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
-import { SubagentFleetStatus } from "../tui/fleet-status.ts";
+import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-status.ts";
 import { SubagentParams } from "./schemas.ts";
 import { validateChainInput } from "./chain-validation.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.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,
@@ -144,10 +144,13 @@ function createSlashResultComponent(
 }
 
 class SubagentControlNoticeComponent implements Component {
-	constructor(
-		private readonly details: SubagentControlMessageDetails,
-		private readonly theme: ExtensionContext["ui"]["theme"],
-	) {}
+	private readonly details: SubagentControlMessageDetails;
+	private readonly theme: ExtensionContext["ui"]["theme"];
+
+	constructor(details: SubagentControlMessageDetails, theme: ExtensionContext["ui"]["theme"]) {
+		this.details = details;
+		this.theme = theme;
+	}
 
 	invalidate(): void {}
 
@@ -194,6 +197,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const waitToolConfig = resolveWaitToolConfig(config.waitTool);
 	const asyncByDefault = config.asyncByDefault === true;
 	const fleetViewEnabled = config.fleetView !== false;
+	const fleetViewPlacement = resolveFleetViewPlacement(config.fleetViewPlacement);
 	const asyncWidgetEnabled = config.asyncWidget === true || (!fleetViewEnabled && config.asyncWidget !== false);
 	const tempArtifactsDir = getArtifactsDir(null);
 	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
@@ -237,14 +241,17 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			const ctx = state.lastUiContext;
 			if (!ctx?.hasUI) return;
 			await openSubagentFleet(ctx, state, { initialKey: itemKey });
-		})
+		}, { placement: fleetViewPlacement })
 		: undefined;
 	const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
 		pi,
 		state,
 		RESULTS_DIR,
 		10 * 60 * 1000,
-		{ notifier: completionNotifier },
+		{
+			notifier: completionNotifier,
+			deliverIntercomResults: config.intercomBridge?.resultDelivery !== false,
+		},
 	);
 
 	const runtimeCleanup = () => {
@@ -383,6 +390,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		events: pi.events,
 		getContext: () => state.lastUiContext,
 		execute: (id, params, signal, onUpdate, ctx) => executor.execute(id, params, signal, onUpdate, ctx),
+		state,
 	});
 
 	function effectiveParallelTaskCount(tasks: Array<{ count?: unknown }> | undefined): number {
@@ -397,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) {
@@ -551,6 +563,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		state.lastUiContext = ctx;
 		cleanupSessionArtifacts(ctx);
 		clearPendingForegroundControlNotices(state);
+		state.foregroundControls.clear();
+		state.lastForegroundControlId = null;
 		resetJobs(ctx);
 		restoreActiveJobs(ctx);
 		scheduledRunManager.bindSession(ctx);