@narumitw/pi-subagents 1.0.2 → 2.0.1

package/src/stateful.ts

@@ -47,18 +47,11 @@ import { createSpawnPromptGuidelines } from "./stateful-guidance.js";
 import { assertCurrentSpawn, waitForOwnedSpawn } from "./stateful-lifecycle.js";
 import { resolveStatefulLimits, type StatefulLimits } from "./stateful-limits.js";
 import { createStatefulToolRenderer } from "./stateful-render.js";
-import {
-	assertFollowUpWriteAllowed,
-	assertNoSharedWriteConflict,
-	confirmProjectAgent,
-} from "./stateful-safety.js";
+import { confirmProjectAgent } from "./stateful-safety.js";
+import { MAX_TASK_NAME_LENGTH } from "./task-path.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
 
-export {
-	assertFollowUpWriteAllowed,
-	assertNoSharedWriteConflict,
-	isWriteCapable,
-} from "./stateful-safety.js";
+export { isWriteCapable } from "./stateful-safety.js";
 
 import {
 	MailboxParamsSchema,
@@ -73,6 +66,7 @@ type StateLifecycleModule = typeof import("./stateful-lifecycle.js");
 
 type StatefulSessionModules = {
 	broker: typeof import("./completion-delivery.js");
+	peerCommunication: typeof import("./peer-communication.js");
 	context: typeof import("./context.js");
 	transport: typeof import("./create-stateful-transport.js");
 	cwdPolicy: CwdPolicyModule;
@@ -100,6 +94,7 @@ let workspaceModule: Promise<typeof import("./workspace.js")> | undefined;
 function loadStatefulSessionModules(): Promise<StatefulSessionModules> {
 	statefulSessionModules ??= Promise.all([
 		import("./completion-delivery.js"),
+		import("./peer-communication.js"),
 		import("./context.js"),
 		import("./create-stateful-transport.js"),
 		import("./cwd-policy.js"),
@@ -107,15 +102,27 @@ function loadStatefulSessionModules(): Promise<StatefulSessionModules> {
 		import("./registry.js"),
 		import("./stateful-lifecycle.js"),
 	])
-		.then(([broker, context, transport, cwdPolicy, persistence, registry, lifecycle]) => ({
-			broker,
-			context,
-			transport,
-			cwdPolicy,
-			persistence,
-			registry,
-			lifecycle,
-		}))
+		.then(
+			([
+				broker,
+				peerCommunication,
+				context,
+				transport,
+				cwdPolicy,
+				persistence,
+				registry,
+				lifecycle,
+			]) => ({
+				broker,
+				peerCommunication,
+				context,
+				transport,
+				cwdPolicy,
+				persistence,
+				registry,
+				lifecycle,
+			}),
+		)
 		.catch((error: unknown) => {
 			statefulSessionModules = undefined;
 			throw error;
@@ -266,6 +273,7 @@ export function registerStatefulSubagents(
 	let runtimeLimits = resolveStatefulLimits(settings);
 	let agentCatalog = "";
 	let completionBroker: CompletionDeliveryBroker | undefined;
+	let peerBroker: import("./peer-communication.js").PeerCommunicationBroker | undefined;
 	let refreshSpawnToolRegistration: (() => void) | undefined;
 	let registry: AgentRegistry | undefined;
 	let persistence: AgentPersistence | undefined;
@@ -361,6 +369,8 @@ export function registerStatefulSubagents(
 		const generation = ++runtimeGeneration;
 		completionBroker?.close();
 		completionBroker = undefined;
+		const previousPeerBroker = peerBroker;
+		peerBroker = undefined;
 		if (sweepTimer) clearInterval(sweepTimer);
 		sweepTimer = undefined;
 		const previousRegistry = registry;
@@ -370,6 +380,7 @@ export function registerStatefulSubagents(
 		seenMessageIds.clear();
 		pendingIdempotentSpawns.clear();
 		const initialize = async () => {
+			await previousPeerBroker?.close();
 			const currentWorkspaceManager = await getWorkspaceManager();
 			const modules = await loadStatefulSessionModules();
 			const cleanupErrors = await modules.lifecycle.disposeStatefulRuntime(
@@ -396,6 +407,7 @@ export function registerStatefulSubagents(
 				maxStoredAgents: nextLimits.maxStoredAgents,
 			});
 			let nextRegistry: AgentRegistry;
+			let transport: import("./transport.js").SubagentTransport;
 			const sessionBroker = new modules.broker.CompletionDeliveryBroker(
 				pi,
 				ctx,
@@ -420,12 +432,42 @@ export function registerStatefulSubagents(
 					},
 				},
 			);
-			const transport = modules.transport.createStatefulTransport({
+			const sessionPeerBroker = new modules.peerCommunication.PeerCommunicationBroker({
+				getRegistry: () => nextRegistry,
+				sendRoot: ({ message, senderPath }) => {
+					pi.appendEntry("pi-subagent-peer-message", {
+						messageId: message.id,
+						senderId: message.senderId,
+						senderPath,
+						content: modules.context.redactPrivateText(message.content),
+					});
+					pi.sendMessage(
+						{
+							customType: "pi-subagent-peer-message",
+							content: [
+								"Message Type: SUBAGENT_PEER_MESSAGE",
+								"Protocol: pi-subagents:v1",
+								`Message ID: ${message.id}`,
+								`Sender ID: ${message.senderId}`,
+								`Sender Path: ${senderPath}`,
+								"Payload:",
+								message.content,
+							].join("\n"),
+							display: true,
+							details: { ...message, senderPath },
+						},
+						{ deliverAs: "steer", triggerTurn: false },
+					);
+				},
+				dispatch: (recipient, message) => transport.deliverMessage?.(recipient, message) ?? false,
+			});
+			transport = modules.transport.createStatefulTransport({
 				kind: transportKind,
 				modelRegistry: ctx.modelRegistry,
 				getParentRuntime: () => ({ ...parentRuntime }),
 				getSettings: getCurrentSettings,
 				createInProcessSession: dependencies.createInProcessSession,
+				peerRuntime: sessionPeerBroker,
 				loadTransport: dependencies.loadTransport,
 			});
 			nextRegistry = new modules.registry.AgentRegistry(transport, {
@@ -449,11 +491,27 @@ export function registerStatefulSubagents(
 								recipientId: message.recipientId,
 								content: modules.context.redactPrivateText(message.content).slice(0, 160),
 							});
+							if (
+								agent.state === "running" &&
+								message.deduplicationKey?.startsWith("completion:")
+							) {
+								try {
+									await transport.deliverMessage?.(agent, {
+										...message,
+										content: modules.context.redactPrivateText(message.content),
+									});
+								} catch {
+									// The durable parent mailbox remains the retry path for the next turn.
+								}
+								if (generation !== runtimeGeneration) return;
+							}
 						}
 					}
 				},
 				onTurnComplete: (completion) => {
-					if (generation === runtimeGeneration) sessionBroker.enqueue(completion);
+					if (generation === runtimeGeneration && completion.recipientId === "root") {
+						sessionBroker.enqueue(completion);
+					}
 				},
 			});
 			const persisted = sessionPersistence.load();
@@ -461,6 +519,12 @@ export function registerStatefulSubagents(
 				persisted,
 				currentWorkspaceManager,
 			);
+			if (generation !== runtimeGeneration) {
+				sessionBroker.close();
+				await sessionPeerBroker.close();
+				await modules.lifecycle.disposeStatefulRuntime(nextRegistry, currentWorkspaceManager);
+				return;
+			}
 			if (ctx.hasUI && orphanCleanupFailures > 0) {
 				ctx.ui.notify("Some orphaned subagent worktrees could not be cleaned", "warning");
 			}
@@ -491,14 +555,16 @@ export function registerStatefulSubagents(
 			nextRegistry.restore(restored);
 			if (generation !== runtimeGeneration) {
 				sessionBroker.close();
+				await sessionPeerBroker.close();
 				await modules.lifecycle.disposeStatefulRuntime(nextRegistry, currentWorkspaceManager);
 				return;
 			}
 			registry = nextRegistry;
 			persistence = sessionPersistence;
 			completionBroker = sessionBroker;
+			peerBroker = sessionPeerBroker;
 			for (const completion of nextRegistry.listPendingCompletions()) {
-				sessionBroker.enqueue(completion);
+				if (completion.recipientId === "root") sessionBroker.enqueue(completion);
 			}
 			runtimeLimits = nextLimits;
 			refreshSpawnToolRegistration?.();
@@ -544,6 +610,8 @@ export function registerStatefulSubagents(
 		runtimeGeneration++;
 		completionBroker?.close();
 		completionBroker = undefined;
+		const previousPeerBroker = peerBroker;
+		peerBroker = undefined;
 		if (sweepTimer) clearInterval(sweepTimer);
 		sweepTimer = undefined;
 		const previousRegistry = registry;
@@ -553,6 +621,7 @@ export function registerStatefulSubagents(
 		seenMessageIds.clear();
 		pendingIdempotentSpawns.clear();
 		const shutdown = async () => {
+			await previousPeerBroker?.close();
 			const currentWorkspaceManager = await getWorkspaceManager();
 			const { disposeStatefulRuntime } = await import("./stateful-lifecycle.js");
 			const errors = await disposeStatefulRuntime(previousRegistry, currentWorkspaceManager);
@@ -566,7 +635,7 @@ export function registerStatefulSubagents(
 	});
 
 	const baseSpawnDescription = () =>
-		`Start an addressable background subagent with an optional thinking level and execution budgets chosen for the task difficulty, return immediately with an agentId, and receive its completion asynchronously. Detached capacity: ${runtimeLimits.maxAgents} retained agents, ${runtimeLimits.maxActiveTurns} active turns, ${runtimeLimits.maxChildrenPerAgent} direct children per agent, and depth ${runtimeLimits.maxDepth}. Working-directory target policy: ${dependencies.getSettings?.()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`;
+		`Start an addressable background subagent with an opaque agentId and canonical taskPath, plus an optional thinking level and execution budgets chosen for the task difficulty, return immediately with an agentId, and receive its completion asynchronously. Detached capacity: ${runtimeLimits.maxAgents} retained agents, ${runtimeLimits.maxActiveTurns} active turns, ${runtimeLimits.maxChildrenPerAgent} direct children per agent, and depth ${runtimeLimits.maxDepth}. Working-directory target policy: ${dependencies.getSettings?.()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`;
 	const spawnTool = defineTool({
 		name: "subagent_spawn",
 		label: "Spawn Subagent",
@@ -575,6 +644,15 @@ export function registerStatefulSubagents(
 		promptGuidelines: createSpawnPromptGuidelines(completionDelivery, blockingEnabled),
 		parameters: Type.Object({
 			agent: Type.String({ minLength: 1 }),
+			taskName: Type.Optional(
+				Type.String({
+					minLength: 1,
+					maxLength: MAX_TASK_NAME_LENGTH,
+					pattern: "^[a-z0-9_]+$",
+					description:
+						"Canonical path segment for this task; use lowercase letters, digits, and underscores.",
+				}),
+			),
 			task: Type.String({ minLength: 1, maxLength: DEFAULT_MAX_CONTEXT_BYTES }),
 			thinkingLevel: Type.Optional(StatefulThinkingLevelSchema),
 			timeoutMs: Type.Optional(StatefulTimeoutSchema),
@@ -586,13 +664,18 @@ export function registerStatefulSubagents(
 			contextEntryIds: Type.Optional(
 				Type.Array(Type.String(), { description: "Optional selected session entry IDs." }),
 			),
-			parentId: Type.Optional(Type.String({ description: "Optional parent agent ID." })),
+			parentId: Type.Optional(
+				Type.String({ description: "Optional parent agent ID or canonical task path." }),
+			),
 			allowConcurrentWrites: Type.Optional(
-				Type.Boolean({ description: "Override the shared-workspace write conflict guard." }),
+				Type.Boolean({
+					description:
+						"Deprecated compatibility field; shared-workspace concurrency is allowed by default.",
+				}),
 			),
 			workspaceMode: Type.Optional(
 				StringEnum(["shared", "worktree"] as const, {
-					description: "Use the shared workspace or an opt-in disposable Git worktree.",
+					description: "Use the shared workspace (default) or an opt-in disposable Git worktree.",
 				}),
 			),
 			contract: Type.Optional(DelegationContractSchema),
@@ -684,6 +767,7 @@ export function registerStatefulSubagents(
 			assertCurrentSpawn(signal, generation, runtimeGeneration);
 			const requestHash = modules.spawnIdempotency.hashSpawnRequest({
 				agent: params.agent,
+				taskName: params.taskName,
 				task: params.task,
 				cwd,
 				agentScope: scope,
@@ -752,15 +836,6 @@ export function registerStatefulSubagents(
 					throw new Error("Project-local subagent definitions cannot run in a detached worktree");
 				}
 				const requestedCwd = cwd;
-				if ((params.workspaceMode ?? "shared") === "shared" && !params.allowConcurrentWrites) {
-					assertNoSharedWriteConflict(
-						ownedRegistry,
-						params.agent,
-						requestedCwd,
-						scope,
-						currentSettings,
-					);
-				}
 				const workspaceOwner = `pending-${randomUUID()}`;
 				const workspace =
 					params.workspaceMode === "worktree"
@@ -781,6 +856,7 @@ export function registerStatefulSubagents(
 					);
 					agent = await ownedRegistry.spawn({
 						agent: params.agent,
+						taskName: params.taskName,
 						task: params.task,
 						cwd: workspace?.path ?? requestedCwd,
 						agentScope: scope,
@@ -819,11 +895,11 @@ export function registerStatefulSubagents(
 				resolvePending?.(agent);
 				const deliveryNote =
 					completionDelivery === "auto-resume"
-						? "If no useful local work remains, briefly tell the user what was launched and end the response; auto-resume will request synthesis after completion."
-						: "End the response without the result only when the current response does not depend on it; next-turn delivery will not wake an idle root.";
+						? "Auto-resume will request synthesis after completion."
+						: "The current response must not depend on the result because next-turn delivery will not wake an idle root.";
 				return result(
 					agent,
-					`Spawned ${agent.agent} as ${agent.id}. Do useful non-overlapping work immediately. ${deliveryNote} Do not poll for progress.`,
+					`Spawned ${agent.agent} as ${agent.taskPath ?? agent.id} (${agent.id}). Continue the identified non-overlapping local work immediately; do not merely announce the spawn or end while useful local work remains. Only an explicit user-requested specialist model, tool-profile, or isolation exception may lack concurrent local work. ${deliveryNote} Do not poll for progress.`,
 				);
 			} catch (error) {
 				rejectPending?.(error);
@@ -853,7 +929,7 @@ export function registerStatefulSubagents(
 			"Send follow-up work to a reusable retained subagent and start a new turn. Semantic resource skew requires explicit revalidation. Use subagent_mailbox for queue-only messages.",
 		promptSnippet: "Start a new detached follow-up turn on a retained subagent",
 		parameters: Type.Object({
-			agentId: Type.String(),
+			agentId: Type.String({ description: "Retained agent ID or canonical task path." }),
 			task: Type.String({ minLength: 1, maxLength: DEFAULT_MAX_CONTEXT_BYTES }),
 			timeoutMs: Type.Optional(
 				Type.Integer({
@@ -871,7 +947,10 @@ export function registerStatefulSubagents(
 				}),
 			),
 			allowConcurrentWrites: Type.Optional(
-				Type.Boolean({ description: "Override the shared-workspace write conflict guard." }),
+				Type.Boolean({
+					description:
+						"Deprecated compatibility field; shared-workspace concurrency is allowed by default.",
+				}),
 			),
 		}),
 		...createStatefulToolRenderer("send"),
@@ -959,13 +1038,6 @@ export function registerStatefulSubagents(
 				currentSettings,
 			);
 			assertCurrentSpawn(signal, generation, runtimeGeneration);
-			assertFollowUpWriteAllowed(
-				ownedRegistry,
-				existing,
-				params.allowConcurrentWrites ?? false,
-				isolatedAgents.has(existing.id),
-				currentSettings,
-			);
 			const currentGrant = modules.capabilityGrant.issueCapabilityGrant(
 				currentPlan,
 				Date.now(),

package/src/subagents.ts

@@ -21,11 +21,8 @@ import type {
 	DelegationCwdPolicy,
 	SubagentSettings,
 } from "./agents/types.js";
-import {
-	type AutomationRegistrationDependencies,
-	registerSubagentAutomation,
-} from "./automation-registration.js";
 import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
+import { renderCompletionMessage, SUBAGENT_COMPLETION_MESSAGE_TYPE } from "./completion-render.js";
 import {
 	type ConfigRegistrationDependencies,
 	registerSubagentConfigCommand,
@@ -60,13 +57,13 @@ type BlockingExecutionModule = Pick<typeof import("./execution.js"), "executeSub
 export interface SubagentsDependencies {
 	loadBlockingExecution?: () => Promise<BlockingExecutionModule>;
 	loadStatefulTransport?: () => Promise<SubagentTransport>;
-	automation?: AutomationRegistrationDependencies;
 	config?: ConfigRegistrationDependencies;
 	consult?: ConsultRegistrationDependencies;
 	inspect?: InspectRegistrationDependencies;
 }
 
 export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies = {}) {
+	pi.registerMessageRenderer(SUBAGENT_COMPLETION_MESSAGE_TYPE, renderCompletionMessage);
 	const loadBlockingExecution = cachedModuleLoader(
 		dependencies.loadBlockingExecution ?? (() => import("./execution.js")),
 	);
@@ -78,9 +75,6 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 	const refreshBlockingCatalog = blockingEnabled
 		? registerBlockingSubagent(pi, () => currentSettings, loadBlockingExecution)
 		: () => undefined;
-	if (blockingEnabled) {
-		registerSubagentAutomation(pi, { getSettings: () => currentSettings }, dependencies.automation);
-	}
 	let refreshStatefulCatalog: (catalog: string) => void = () => undefined;
 	let refreshConsultCatalog: (catalog: string) => void = () => undefined;
 
@@ -225,7 +219,11 @@ function registerBlockingSubagent(
 		].join(" ");
 	const promptGuidelines = () => [
 		"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
+		"The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
 		"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
+		"One ordinary implementation worker should not replace work the main agent can perform directly; use a blocking single only when intentional synchronous isolation or a user-requested specialist justifies waiting.",
+		"Keep ordinary planning in the main agent, or use explicit workflow mode when a genuine dependency graph requires caller-authored orchestration.",
+		"Keep ordinary review in the main agent with a review skill and deterministic checks; reserve panel mode or custom verifier agents for consequential independent verification.",
 		"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
 		"Use a blocking subagent single, parallel, chain, workflow, panel, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
 		`If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured max ${resolveBlockingMaxParallelTasks(getSettings())}, and avoid write-heavy implementation touching the same files or shared state.`,

package/src/subprocess-transport.ts

@@ -1,5 +1,11 @@
 import { discoverAgents } from "./agents/discovery.js";
 import type { AgentConfig, SubagentSettings, SubagentThinkingLevel } from "./agents/types.js";
+import {
+	CHILD_PEER_TOOL_NAMES,
+	childPeerBridgePath,
+	type PeerTransportRuntime,
+	peerBridgeEnvironment,
+} from "./peer-transport.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
 import type { ManagedAgent, TurnOutcome } from "./registry.js";
 import { getResultFinalOutput, runSingleAgent, type SubagentDetails } from "./runner.js";
@@ -17,6 +23,7 @@ export function resolveStatefulSubprocessThinkingLevel(
 
 export interface SubprocessTransportOptions {
 	getSettings?: () => SubagentSettings | undefined;
+	peerRuntime?: PeerTransportRuntime;
 }
 
 export class SubprocessTransport implements SubagentTransport {
@@ -54,35 +61,49 @@ export class SubprocessTransport implements SubagentTransport {
 			projectAgentsDir: discovery.projectAgentsDir,
 			results,
 		});
-		const single = await runSingleAgent(
-			record.cwd,
-			discovery.agents,
-			record.agent,
-			boundedTask.text,
-			undefined,
-			undefined,
-			signal,
-			resolveStatefulSubprocessThinkingLevel(discovery.agents, record),
-			record.currentTimeoutMs ?? record.timeoutMs ?? resolveStatefulTurnTimeout(agent),
-			undefined,
-			makeDetails,
-			undefined,
-			{
-				projectTrust,
-				...(record.executionPlan ? { tools: record.executionPlan.effectiveTools } : {}),
-				appendSystemPromptPaths: promptResources?.appendSystemPromptPaths,
-				timeoutResultFormat: record.resultFormat,
-				turnLimits: {
-					idleTimeoutMs: record.currentIdleTimeoutMs ?? record.idleTimeoutMs,
-					maxTurns: record.currentMaxTurns ?? record.maxTurns,
-					maxToolCalls: record.currentMaxToolCalls ?? record.maxToolCalls,
+		const credentials = this.options.peerRuntime
+			? await this.options.peerRuntime.issueCredentials(
+					record.id,
+					record.currentTurnGeneration ?? record.turnGeneration ?? 1,
+				)
+			: undefined;
+		let single: Awaited<ReturnType<typeof runSingleAgent>>;
+		try {
+			single = await runSingleAgent(
+				record.cwd,
+				discovery.agents,
+				record.agent,
+				boundedTask.text,
+				undefined,
+				undefined,
+				signal,
+				resolveStatefulSubprocessThinkingLevel(discovery.agents, record),
+				record.currentTimeoutMs ?? record.timeoutMs ?? resolveStatefulTurnTimeout(agent),
+				undefined,
+				makeDetails,
+				undefined,
+				{
+					projectTrust,
+					...(record.executionPlan ? { tools: record.executionPlan.effectiveTools } : {}),
+					appendSystemPromptPaths: promptResources?.appendSystemPromptPaths,
+					extensionPaths: credentials ? [childPeerBridgePath()] : undefined,
+					additionalTools: credentials ? [...CHILD_PEER_TOOL_NAMES] : undefined,
+					env: credentials ? peerBridgeEnvironment(credentials) : undefined,
+					timeoutResultFormat: record.resultFormat,
+					turnLimits: {
+						idleTimeoutMs: record.currentIdleTimeoutMs ?? record.idleTimeoutMs,
+						maxTurns: record.currentMaxTurns ?? record.maxTurns,
+						maxToolCalls: record.currentMaxToolCalls ?? record.maxToolCalls,
+					},
+					resultFormat: record.resultFormat,
+					contract: record.contract,
+					executionPlan: record.executionPlan,
+					displayTask: task,
 				},
-				resultFormat: record.resultFormat,
-				contract: record.contract,
-				executionPlan: record.executionPlan,
-				displayTask: task,
-			},
-		);
+			);
+		} finally {
+			this.options.peerRuntime?.revoke(record.id);
+		}
 		const settledAt = Date.now();
 		const telemetry: TransportTelemetry = {
 			...starting,

package/src/task-path.ts

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+
+export const ROOT_TASK_PATH = "/root";
+export const MAX_TASK_NAME_LENGTH = 128;
+export const MAX_TASK_PATH_LENGTH = 2_048;
+
+const TASK_NAME_PATTERN = /^[a-z0-9_]+$/u;
+
+export function validateTaskName(value: string): string {
+	if (!value) throw new Error("Subagent taskName must not be empty");
+	if (value === "root" || value === "." || value === "..") {
+		throw new Error(`Subagent taskName ${JSON.stringify(value)} is reserved`);
+	}
+	if (value.length > MAX_TASK_NAME_LENGTH) {
+		throw new Error(`Subagent taskName cannot exceed ${MAX_TASK_NAME_LENGTH} characters`);
+	}
+	if (value.includes("/")) throw new Error("Subagent taskName must not contain `/`");
+	if (!TASK_NAME_PATTERN.test(value)) {
+		throw new Error(
+			"Subagent taskName must use only lowercase ASCII letters, digits, and underscores",
+		);
+	}
+	return value;
+}
+
+export function validateTaskPath(value: string): string {
+	if (!value.startsWith(`${ROOT_TASK_PATH}/`) && value !== ROOT_TASK_PATH) {
+		throw new Error("Canonical subagent task paths must start with `/root`");
+	}
+	if (value.length > MAX_TASK_PATH_LENGTH) {
+		throw new Error(
+			`Canonical subagent task paths cannot exceed ${MAX_TASK_PATH_LENGTH} characters`,
+		);
+	}
+	if (value.endsWith("/") || value.includes("//")) {
+		throw new Error("Canonical subagent task paths must not contain empty segments");
+	}
+	for (const segment of value.slice(ROOT_TASK_PATH.length + 1).split("/")) {
+		if (segment) validateTaskName(segment);
+	}
+	return value;
+}
+
+export function joinTaskPath(parentPath: string, taskName: string): string {
+	const parent = validateTaskPath(parentPath);
+	const name = validateTaskName(taskName);
+	return validateTaskPath(`${parent}/${name}`);
+}
+
+export function resolveTaskPath(senderPath: string, reference: string): string {
+	if (!reference) throw new Error("Subagent task path reference must not be empty");
+	if (reference.startsWith("/")) return validateTaskPath(reference);
+	const sender = validateTaskPath(senderPath);
+	if (reference.endsWith("/")) {
+		throw new Error("Relative subagent task paths must not end with `/`");
+	}
+	let path = sender;
+	for (const segment of reference.split("/")) path = joinTaskPath(path, segment);
+	return path;
+}
+
+export function deriveTaskName(agentId: string): string {
+	const digest = createHash("sha256").update(agentId).digest("hex").slice(0, 32);
+	return `agent_${digest}`;
+}

package/src/transport-ui.ts

@@ -148,12 +148,6 @@ export function responsivenessSetupScreen(runtime: TransportUiRuntime) {
 				description: "Choose separately whether an idle root resumes for synthesis",
 				to: "settings" as const,
 			},
-			{
-				id: "thinking",
-				label: "Thinking profiles",
-				description: "Preview explicit Fast, Balanced, or Deep per-agent defaults",
-				to: "execution-profiles" as const,
-			},
 			{ id: "back", label: "Back", action: "back" as const },
 		],
 		hint: "back" as const,

package/src/transport.ts

@@ -1,4 +1,4 @@
-import type { ManagedAgent, TurnOutcome } from "./registry.js";
+import type { AgentMailboxMessage, ManagedAgent, TurnOutcome } from "./registry.js";
 import type { TransportProgressCallback } from "./transport-types.js";
 
 export interface SubagentTransport {
@@ -9,6 +9,7 @@ export interface SubagentTransport {
 		signal: AbortSignal,
 		onProgress?: TransportProgressCallback,
 	): Promise<TurnOutcome>;
+	deliverMessage?(agent: ManagedAgent, message: AgentMailboxMessage): Promise<boolean>;
 	release?(agent: ManagedAgent): Promise<void>;
 	shutdown?(): Promise<void>;
 }

package/src/workflow-ui.ts

@@ -46,15 +46,15 @@ function workflowEffects(current: DelegationWorkflow, next: DelegationWorkflow):
 	if (blockingEnabled(current) !== blockingEnabled(next)) {
 		effects.push(
 			blockingEnabled(next)
-				? "Add blocking `subagent`, explicit `subagent_auto`, and read-only `subagent_consult`"
-				: "Remove blocking `subagent`, explicit `subagent_auto`, and read-only `subagent_consult`",
+				? "Add blocking `subagent` and read-only `subagent_consult`"
+				: "Remove blocking `subagent` and read-only `subagent_consult`",
 		);
 	}
 	if (asyncEnabled(current) !== asyncEnabled(next)) {
 		effects.push(
 			asyncEnabled(next)
-				? "Add reusable async lifecycle tools"
-				: "Remove reusable async lifecycle tools",
+				? "Add async `subagent_spawn`, `subagent_send`, `subagent_manage`, and `subagent_mailbox`"
+				: "Remove async `subagent_spawn`, `subagent_send`, `subagent_manage`, and `subagent_mailbox`",
 		);
 	}
 	return effects;