@narumitw/pi-subagents 1.0.1 → 2.0.0

package/src/stateful.ts

@@ -7,7 +7,6 @@ import { randomUUID } from "node:crypto";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { discoverAgents } from "./agents/discovery.js";
 import {
 	type AgentScope,
 	type CompletionDelivery,
@@ -17,20 +16,10 @@ import {
 	type SubagentTransportKind,
 	THINKING_LEVELS,
 } from "./agents/types.js";
-import { issueCapabilityGrant } from "./capability-grant.js";
-import { CompletionDeliveryBroker } from "./completion-delivery.js";
-import { buildContextSnapshot, type ContextMode, redactPrivateText } from "./context.js";
-import {
-	type CreateStatefulTransportOptions,
-	createStatefulTransport,
-} from "./create-stateful-transport.js";
-import {
-	assertDelegationTargetAllowed,
-	resolveSubagentTarget,
-	targetPolicyAudit,
-} from "./cwd-policy.js";
-import { DelegationContractSchema, normalizeDelegationContract } from "./delegation-contract.js";
-import { assertSubagentDepthAllowed } from "./execution/runtime-policy.js";
+import type { CompletionDeliveryBroker } from "./completion-delivery.js";
+import type { ContextMode } from "./context.js";
+import type { CreateStatefulTransportOptions } from "./create-stateful-transport.js";
+import { DelegationContractSchema } from "./delegation-contract.js";
 import type { ChildSessionFactory, ParentRuntimeSnapshot } from "./in-process-transport.js";
 import {
 	DEFAULT_MAX_CONTEXT_BYTES,
@@ -38,46 +27,31 @@ import {
 	MAX_TOOL_MESSAGE_BYTES,
 	truncateUtf8,
 } from "./limits.js";
-import { AgentPersistence } from "./persistence.js";
-import {
+import type { AgentPersistence } from "./persistence.js";
+import type {
 	AgentRegistry,
-	type AgentRunInspectionDetail,
-	type AgentRunInspectionSummary,
-	type ManagedAgent,
+	AgentRunInspectionDetail,
+	AgentRunInspectionSummary,
+	ManagedAgent,
 } from "./registry.js";
 import { SUBAGENT_RESULT_FORMATS, type SubagentResultFormat } from "./result-contract.js";
-import { buildRetainedSemanticState } from "./retained-semantic-state.js";
-import { evaluateSemanticCompatibility } from "./semantic-snapshot.js";
 import { DEFAULT_DELEGATION_CWD_POLICY } from "./settings/inspection.js";
 import { readSubagentSettings } from "./settings.js";
 import {
 	assertSpawnIdempotencyKey,
-	hashSpawnRequest,
 	MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH,
 } from "./spawn-idempotency.js";
 import { summarizeStatefulAgent } from "./stateful-agent-view.js";
 import { resolveCompletionDelivery, resolveStatefulTransportKind } from "./stateful-config.js";
 import { createSpawnPromptGuidelines } from "./stateful-guidance.js";
-import {
-	assertCurrentSpawn,
-	cleanupPersistedWorkspaces,
-	disposeStatefulRuntime,
-	waitForOwnedSpawn,
-} from "./stateful-lifecycle.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,
@@ -85,7 +59,126 @@ import {
 	validateMailboxParams,
 	validateManageParams,
 } from "./stateful-tool-params.js";
-import { WorkspaceManager } from "./workspace.js";
+import type { WorkspaceManager } from "./workspace.js";
+
+type CwdPolicyModule = typeof import("./cwd-policy.js");
+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;
+	persistence: typeof import("./persistence.js");
+	registry: typeof import("./registry.js");
+	lifecycle: StateLifecycleModule;
+};
+
+type StatefulSpawnModules = {
+	agents: typeof import("./agents/discovery.js");
+	capabilityGrant: typeof import("./capability-grant.js");
+	context: typeof import("./context.js");
+	cwdPolicy: CwdPolicyModule;
+	delegationContract: typeof import("./delegation-contract.js");
+	runtimePolicy: typeof import("./execution/runtime-policy.js");
+	retainedSemanticState: typeof import("./retained-semantic-state.js");
+	semanticSnapshot: typeof import("./semantic-snapshot.js");
+	spawnIdempotency: typeof import("./spawn-idempotency.js");
+};
+
+let statefulSessionModules: Promise<StatefulSessionModules> | undefined;
+let statefulSpawnModules: Promise<StatefulSpawnModules> | undefined;
+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"),
+		import("./persistence.js"),
+		import("./registry.js"),
+		import("./stateful-lifecycle.js"),
+	])
+		.then(
+			([
+				broker,
+				peerCommunication,
+				context,
+				transport,
+				cwdPolicy,
+				persistence,
+				registry,
+				lifecycle,
+			]) => ({
+				broker,
+				peerCommunication,
+				context,
+				transport,
+				cwdPolicy,
+				persistence,
+				registry,
+				lifecycle,
+			}),
+		)
+		.catch((error: unknown) => {
+			statefulSessionModules = undefined;
+			throw error;
+		});
+	return statefulSessionModules;
+}
+
+function loadStatefulSpawnModules(): Promise<StatefulSpawnModules> {
+	statefulSpawnModules ??= Promise.all([
+		import("./agents/discovery.js"),
+		import("./capability-grant.js"),
+		import("./context.js"),
+		import("./cwd-policy.js"),
+		import("./delegation-contract.js"),
+		import("./execution/runtime-policy.js"),
+		import("./retained-semantic-state.js"),
+		import("./semantic-snapshot.js"),
+		import("./spawn-idempotency.js"),
+	])
+		.then(
+			([
+				agents,
+				capabilityGrant,
+				context,
+				cwdPolicy,
+				delegationContract,
+				runtimePolicy,
+				retainedSemanticState,
+				semanticSnapshot,
+				spawnIdempotency,
+			]) => ({
+				agents,
+				capabilityGrant,
+				context,
+				cwdPolicy,
+				delegationContract,
+				runtimePolicy,
+				retainedSemanticState,
+				semanticSnapshot,
+				spawnIdempotency,
+			}),
+		)
+		.catch((error: unknown) => {
+			statefulSpawnModules = undefined;
+			throw error;
+		});
+	return statefulSpawnModules;
+}
+
+async function loadWorkspaceModule(): Promise<typeof import("./workspace.js")> {
+	workspaceModule ??= import("./workspace.js").catch((error: unknown) => {
+		workspaceModule = undefined;
+		throw error;
+	});
+	return workspaceModule;
+}
 
 const ContextModeSchema = Type.Union([
 	StringEnum(["none", "all", "summary"] as const),
@@ -180,13 +273,20 @@ 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;
 	let sweepTimer: NodeJS.Timeout | undefined;
 	let runtimeGeneration = 0;
 	let runtimeTransition: Promise<void> = Promise.resolve();
-	const workspaceManager = dependencies.workspaceManager ?? new WorkspaceManager();
+	let workspaceManager = dependencies.workspaceManager;
+	const getWorkspaceManager = async () => {
+		if (workspaceManager) return workspaceManager;
+		const { WorkspaceManager } = await loadWorkspaceModule();
+		workspaceManager = new WorkspaceManager();
+		return workspaceManager;
+	};
 	const isolatedAgents = new Map<string, string>();
 	const seenMessageIds = new Set<string>();
 	type PendingIdempotentSpawn = {
@@ -206,11 +306,12 @@ export function registerStatefulSubagents(
 		const currentRegistry = registry;
 		const currentPersistence = persistence;
 		if (!currentRegistry) return 0;
+		const currentWorkspaceManager = await getWorkspaceManager();
 		const count = currentRegistry.list().length;
 		const clear = async () => {
 			await currentRegistry.closeAll();
 			if (generation !== runtimeGeneration) return;
-			await workspaceManager.cleanupAll();
+			await currentWorkspaceManager.cleanupAll();
 			isolatedAgents.clear();
 			seenMessageIds.clear();
 			await currentPersistence?.delete();
@@ -268,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;
@@ -277,7 +380,13 @@ export function registerStatefulSubagents(
 		seenMessageIds.clear();
 		pendingIdempotentSpawns.clear();
 		const initialize = async () => {
-			const cleanupErrors = await disposeStatefulRuntime(previousRegistry, workspaceManager);
+			await previousPeerBroker?.close();
+			const currentWorkspaceManager = await getWorkspaceManager();
+			const modules = await loadStatefulSessionModules();
+			const cleanupErrors = await modules.lifecycle.disposeStatefulRuntime(
+				previousRegistry,
+				currentWorkspaceManager,
+			);
 			if (generation !== runtimeGeneration) return;
 			if (cleanupErrors.length > 0 && ctx.hasUI) {
 				ctx.ui.notify(
@@ -293,39 +402,75 @@ export function registerStatefulSubagents(
 				ctx.sessionManager.getSessionId?.() ??
 				ctx.sessionManager.getSessionFile?.() ??
 				`ephemeral:${ctx.cwd}`;
-			const sessionPersistence = new AgentPersistence(owner, {
+			const sessionPersistence = new modules.persistence.AgentPersistence(owner, {
 				retentionDays: sessionSettings.retentionDays,
 				maxStoredAgents: nextLimits.maxStoredAgents,
 			});
 			let nextRegistry: AgentRegistry;
-			const sessionBroker = new CompletionDeliveryBroker(pi, ctx, completionDelivery, {
-				onDeliveryError: (error) => {
-					if (!ctx.hasUI) return;
-					const reason = error instanceof Error ? error.message : String(error);
-					ctx.ui.notify(`Subagent completion delivery failed: ${reason}`, "warning");
+			let transport: import("./transport.js").SubagentTransport;
+			const sessionBroker = new modules.broker.CompletionDeliveryBroker(
+				pi,
+				ctx,
+				completionDelivery,
+				{
+					onDeliveryError: (error) => {
+						if (!ctx.hasUI) return;
+						const reason = error instanceof Error ? error.message : String(error);
+						ctx.ui.notify(`Subagent completion delivery failed: ${reason}`, "warning");
+					},
+					onAcknowledged: (completions, deliveredAt) => {
+						if (generation !== runtimeGeneration) return;
+						for (const completion of completions) {
+							void nextRegistry
+								.markCompletionDelivered(completion.completionId, deliveredAt)
+								.catch((error: unknown) => {
+									if (!ctx.hasUI || generation !== runtimeGeneration) return;
+									const reason = error instanceof Error ? error.message : String(error);
+									ctx.ui.notify(`Subagent completion acknowledgement failed: ${reason}`, "warning");
+								});
+						}
+					},
 				},
-				onAcknowledged: (completions, deliveredAt) => {
-					if (generation !== runtimeGeneration) return;
-					for (const completion of completions) {
-						void nextRegistry
-							.markCompletionDelivered(completion.completionId, deliveredAt)
-							.catch((error: unknown) => {
-								if (!ctx.hasUI || generation !== runtimeGeneration) return;
-								const reason = error instanceof Error ? error.message : String(error);
-								ctx.ui.notify(`Subagent completion acknowledgement failed: ${reason}`, "warning");
-							});
-					}
+			);
+			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,
 			});
-			const transport = createStatefulTransport({
+			transport = modules.transport.createStatefulTransport({
 				kind: transportKind,
 				modelRegistry: ctx.modelRegistry,
 				getParentRuntime: () => ({ ...parentRuntime }),
 				getSettings: getCurrentSettings,
 				createInProcessSession: dependencies.createInProcessSession,
+				peerRuntime: sessionPeerBroker,
 				loadTransport: dependencies.loadTransport,
 			});
-			nextRegistry = new AgentRegistry(transport, {
+			nextRegistry = new modules.registry.AgentRegistry(transport, {
 				maxAgents: nextLimits.maxAgents,
 				maxActiveTurns: nextLimits.maxActiveTurns,
 				maxDepth: nextLimits.maxDepth,
@@ -344,17 +489,42 @@ export function registerStatefulSubagents(
 							pi.appendEntry("pi-subagent-message", {
 								senderId: message.senderId,
 								recipientId: message.recipientId,
-								content: redactPrivateText(message.content).slice(0, 160),
+								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();
-			const orphanCleanupFailures = await cleanupPersistedWorkspaces(persisted, workspaceManager);
+			const orphanCleanupFailures = await modules.lifecycle.cleanupPersistedWorkspaces(
+				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");
 			}
@@ -367,12 +537,14 @@ export function registerStatefulSubagents(
 				)
 				.flatMap((agent) => {
 					try {
-						const target = resolveSubagentTarget({
+						const target = modules.cwdPolicy.resolveSubagentTarget({
 							workspace: ctx.cwd,
 							requestedCwd: agent.cwd,
 							currentProjectTrusted: ctx.isProjectTrusted(),
 						});
-						return [{ ...agent, cwd: target.cwd, target: targetPolicyAudit(target) }];
+						return [
+							{ ...agent, cwd: target.cwd, target: modules.cwdPolicy.targetPolicyAudit(target) },
+						];
 					} catch {
 						return [];
 					}
@@ -383,14 +555,16 @@ export function registerStatefulSubagents(
 			nextRegistry.restore(restored);
 			if (generation !== runtimeGeneration) {
 				sessionBroker.close();
-				await disposeStatefulRuntime(nextRegistry, workspaceManager);
+				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?.();
@@ -436,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;
@@ -445,7 +621,10 @@ export function registerStatefulSubagents(
 		seenMessageIds.clear();
 		pendingIdempotentSpawns.clear();
 		const shutdown = async () => {
-			const errors = await disposeStatefulRuntime(previousRegistry, workspaceManager);
+			await previousPeerBroker?.close();
+			const currentWorkspaceManager = await getWorkspaceManager();
+			const { disposeStatefulRuntime } = await import("./stateful-lifecycle.js");
+			const errors = await disposeStatefulRuntime(previousRegistry, currentWorkspaceManager);
 			if (errors.length > 0 && ctx.hasUI) {
 				ctx.ui.notify(`Subagent shutdown cleanup reported ${errors.length} error(s).`, "warning");
 			}
@@ -456,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",
@@ -465,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),
@@ -476,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),
@@ -502,30 +695,47 @@ export function registerStatefulSubagents(
 		}),
 		...createStatefulToolRenderer("spawn"),
 		async execute(_id, params, signal, _update, ctx) {
+			const generation = runtimeGeneration;
+			const capturedRegistry = registry;
+			let modules: StatefulSpawnModules;
+			try {
+				modules = await loadStatefulSpawnModules();
+			} catch (error) {
+				assertCurrentSpawn(signal, generation, runtimeGeneration);
+				throw error;
+			}
+			assertCurrentSpawn(signal, generation, runtimeGeneration);
+			let currentWorkspaceManager: WorkspaceManager;
+			try {
+				currentWorkspaceManager = await getWorkspaceManager();
+			} catch (error) {
+				assertCurrentSpawn(signal, generation, runtimeGeneration);
+				throw error;
+			}
+			assertCurrentSpawn(signal, generation, runtimeGeneration);
 			const scope = (params.agentScope ?? "user") as AgentScope;
 			const resultFormat = (params.resultFormat ?? "text") as SubagentResultFormat;
-			const contract = normalizeDelegationContract(params.contract);
+			const contract = modules.delegationContract.normalizeDelegationContract(params.contract);
 			if (params.contract !== undefined && !contract) {
 				throw new Error(
 					"subagent_spawn contract must be a valid pi-subagents:delegation:v2 object",
 				);
 			}
-			assertSubagentDepthAllowed();
+			modules.runtimePolicy.assertSubagentDepthAllowed();
 			assertSpawnIdempotencyKey(params.idempotencyKey);
-			const generation = runtimeGeneration;
 			const currentSettings = getCurrentSettings();
-			const target = resolveSubagentTarget({
+			const target = modules.cwdPolicy.resolveSubagentTarget({
 				workspace: ctx.cwd,
 				requestedCwd: params.cwd,
 				currentProjectTrusted: ctx.isProjectTrusted(),
 			});
-			assertDelegationTargetAllowed(
+			modules.cwdPolicy.assertDelegationTargetAllowed(
 				target,
 				currentSettings?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY,
 			);
 			const cwd = target.cwd;
 			const mode = resolveSpawnContextMode(params.context, params.contextEntryIds);
-			const snapshot = buildContextSnapshot(
+			const snapshot = modules.context.buildContextSnapshot(
 				ctx.sessionManager.getBranch(),
 				mode,
 				DEFAULT_MAX_CONTEXT_BYTES,
@@ -534,28 +744,30 @@ export function registerStatefulSubagents(
 			if ((scope === "project" || scope === "both") && !ctx.isProjectTrusted()) {
 				throw new Error("Project-local subagent definitions require a trusted project");
 			}
-			const resolvedAgents = discoverAgents(cwd, scope, currentSettings).agents;
+			const resolvedAgents = modules.agents.discoverAgents(cwd, scope, currentSettings).agents;
 			const resolvedAgent = resolvedAgents.find((agent) => agent.name === params.agent);
 			if (!resolvedAgent) {
 				const available = resolvedAgents.map((agent) => agent.name).join(", ") || "none";
 				throw new Error(`Unknown subagent ${params.agent}. Available agents: ${available}`);
 			}
-			const targetSnapshot = targetPolicyAudit(target);
-			const { executionPlan, semanticSnapshot } = await buildRetainedSemanticState({
-				agent: resolvedAgent,
-				contract,
-				target: targetSnapshot,
-				cwd,
-				workspaceMode: params.workspaceMode === "worktree" ? "worktree" : "shared",
-				transport: transportKind,
-				resultFormat,
-				thinkingLevel: params.thinkingLevel,
-				timeoutMs: params.timeoutMs,
-				taskGeneration: 1,
-			});
+			const targetSnapshot = modules.cwdPolicy.targetPolicyAudit(target);
+			const { executionPlan, semanticSnapshot } =
+				await modules.retainedSemanticState.buildRetainedSemanticState({
+					agent: resolvedAgent,
+					contract,
+					target: targetSnapshot,
+					cwd,
+					workspaceMode: params.workspaceMode === "worktree" ? "worktree" : "shared",
+					transport: transportKind,
+					resultFormat,
+					thinkingLevel: params.thinkingLevel,
+					timeoutMs: params.timeoutMs,
+					taskGeneration: 1,
+				});
 			assertCurrentSpawn(signal, generation, runtimeGeneration);
-			const requestHash = hashSpawnRequest({
+			const requestHash = modules.spawnIdempotency.hashSpawnRequest({
 				agent: params.agent,
+				taskName: params.taskName,
 				task: params.task,
 				cwd,
 				agentScope: scope,
@@ -572,7 +784,10 @@ export function registerStatefulSubagents(
 				contract,
 				resultFormat,
 			});
-			const ownedRegistry = requireRegistry();
+			if (!capturedRegistry) {
+				throw new Error("Stateful subagents are not initialized for this session");
+			}
+			const ownedRegistry = capturedRegistry;
 			const retained = ownedRegistry.findBySpawnIdempotencyKey(params.idempotencyKey, requestHash);
 			if (retained) return result(retained, `Reused ${retained.agent} as ${retained.id}.`);
 			const foundPending = params.idempotencyKey
@@ -621,35 +836,27 @@ 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"
-						? await workspaceManager.create(workspaceOwner, requestedCwd)
+						? await currentWorkspaceManager.create(workspaceOwner, requestedCwd)
 						: undefined;
 				try {
 					assertCurrentSpawn(signal, generation, runtimeGeneration);
 				} catch (error) {
-					if (workspace) await workspaceManager.cleanup(workspaceOwner);
+					if (workspace) await currentWorkspaceManager.cleanup(workspaceOwner);
 					throw error;
 				}
 				let agent: ManagedAgent | undefined;
 				try {
-					const capabilityGrant = issueCapabilityGrant(
+					const capabilityGrant = modules.capabilityGrant.issueCapabilityGrant(
 						executionPlan,
 						Date.now(),
 						Math.max(1, (params.timeoutMs ?? resolvedAgent.timeoutMs ?? 600_000) + 60_000),
 					);
 					agent = await ownedRegistry.spawn({
 						agent: params.agent,
+						taskName: params.taskName,
 						task: params.task,
 						cwd: workspace?.path ?? requestedCwd,
 						agentScope: scope,
@@ -678,21 +885,21 @@ export function registerStatefulSubagents(
 					assertCurrentSpawn(signal, generation, runtimeGeneration);
 				} catch (error) {
 					if (agent) await ownedRegistry.closeTree(agent.id).catch(() => undefined);
-					if (workspace) await workspaceManager.cleanup(workspaceOwner);
+					if (workspace) await currentWorkspaceManager.cleanup(workspaceOwner);
 					throw error;
 				}
 				if (!agent) throw new Error("Subagent spawn completed without a retained agent");
 				if (workspace && agent.cwd === workspace.path) isolatedAgents.set(agent.id, workspaceOwner);
-				else if (workspace) await workspaceManager.cleanup(workspaceOwner);
+				else if (workspace) await currentWorkspaceManager.cleanup(workspaceOwner);
 				assertCurrentSpawn(signal, generation, runtimeGeneration);
 				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);
@@ -722,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({
@@ -740,32 +947,41 @@ 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"),
 		async execute(_id, params, signal, _update, ctx) {
 			const generation = runtimeGeneration;
 			const ownedRegistry = requireRegistry();
+			let modules: StatefulSpawnModules;
+			try {
+				modules = await loadStatefulSpawnModules();
+			} catch (error) {
+				assertCurrentSpawn(signal, generation, runtimeGeneration);
+				throw error;
+			}
+			assertCurrentSpawn(signal, generation, runtimeGeneration);
 			const currentSettings = getCurrentSettings();
 			const existing = ownedRegistry.get(params.agentId);
 			if (!existing) throw new Error(`Unknown subagent: ${params.agentId}`);
-			const currentAgent = discoverAgents(
-				existing.cwd,
-				existing.agentScope ?? "user",
-				currentSettings,
-			).agents.find((agent) => agent.name === existing.agent);
+			const currentAgent = modules.agents
+				.discoverAgents(existing.cwd, existing.agentScope ?? "user", currentSettings)
+				.agents.find((agent) => agent.name === existing.agent);
 			if (!currentAgent) throw new Error(`Unknown retained subagent definition: ${existing.agent}`);
 			const resolvedFollowUpTarget =
 				existing.workspaceMode === "worktree"
 					? undefined
-					: resolveSubagentTarget({
+					: modules.cwdPolicy.resolveSubagentTarget({
 							workspace: ctx.cwd,
 							requestedCwd: existing.cwd,
 							currentProjectTrusted: ctx.isProjectTrusted(),
 						});
 			if (resolvedFollowUpTarget) {
-				assertDelegationTargetAllowed(
+				modules.cwdPolicy.assertDelegationTargetAllowed(
 					resolvedFollowUpTarget,
 					currentSettings?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY,
 				);
@@ -776,9 +992,11 @@ export function registerStatefulSubagents(
 			const currentTarget =
 				existing.workspaceMode === "worktree" && existing.target
 					? existing.target
-					: targetPolicyAudit(resolvedFollowUpTarget as NonNullable<typeof resolvedFollowUpTarget>);
+					: modules.cwdPolicy.targetPolicyAudit(
+							resolvedFollowUpTarget as NonNullable<typeof resolvedFollowUpTarget>,
+						);
 			const { executionPlan: currentPlan, semanticSnapshot: currentSnapshot } =
-				await buildRetainedSemanticState({
+				await modules.retainedSemanticState.buildRetainedSemanticState({
 					agent: currentAgent,
 					contract: existing.contract,
 					target: currentTarget,
@@ -798,7 +1016,10 @@ export function registerStatefulSubagents(
 				});
 			assertCurrentSpawn(signal, generation, runtimeGeneration);
 			const compatibility = existing.semanticSnapshot
-				? evaluateSemanticCompatibility(existing.semanticSnapshot, currentSnapshot)
+				? modules.semanticSnapshot.evaluateSemanticCompatibility(
+						existing.semanticSnapshot,
+						currentSnapshot,
+					)
 				: { status: "warning" as const, changedComponents: ["legacy-missing-snapshot"] };
 			if (
 				(compatibility.status === "needs-revalidation" || compatibility.status === "rejected") &&
@@ -817,14 +1038,7 @@ export function registerStatefulSubagents(
 				currentSettings,
 			);
 			assertCurrentSpawn(signal, generation, runtimeGeneration);
-			assertFollowUpWriteAllowed(
-				ownedRegistry,
-				existing,
-				params.allowConcurrentWrites ?? false,
-				isolatedAgents.has(existing.id),
-				currentSettings,
-			);
-			const currentGrant = issueCapabilityGrant(
+			const currentGrant = modules.capabilityGrant.issueCapabilityGrant(
 				currentPlan,
 				Date.now(),
 				Math.max(1, (params.timeoutMs ?? existing.timeoutMs ?? 600_000) + 60_000),
@@ -838,6 +1052,7 @@ export function registerStatefulSubagents(
 					? { status: "warning", changedComponents: compatibility.changedComponents }
 					: compatibility,
 			);
+			assertCurrentSpawn(signal, generation, runtimeGeneration);
 			const agent = await ownedRegistry.followUp(params.agentId, params.task, {
 				timeoutMs: params.timeoutMs,
 				idleTimeoutMs: params.idleTimeoutMs,
@@ -860,6 +1075,14 @@ export function registerStatefulSubagents(
 		async execute(_id, params, signal): Promise<StatefulActionToolResult> {
 			const generation = runtimeGeneration;
 			const ownedRegistry = requireRegistry();
+			let currentWorkspaceManager: WorkspaceManager;
+			try {
+				currentWorkspaceManager = await getWorkspaceManager();
+			} catch (error) {
+				assertCurrentSpawn(signal, generation, runtimeGeneration);
+				throw error;
+			}
+			assertCurrentSpawn(signal, generation, runtimeGeneration);
 			const ownedAgent = (agentId: string): ManagedAgent => {
 				const value = ownedRegistry.get(agentId);
 				if (!value) throw new Error(`Unknown subagent: ${agentId}`);
@@ -886,7 +1109,7 @@ export function registerStatefulSubagents(
 			const existing = ownedRegistry.get(agentId);
 			if (existing?.state === "closed" && !operation.subtree) {
 				const pendingOwner = isolatedAgents.get(existing.id);
-				if (pendingOwner) await workspaceManager.cleanup(pendingOwner);
+				if (pendingOwner) await currentWorkspaceManager.cleanup(pendingOwner);
 				assertCurrentSpawn(signal, generation, runtimeGeneration);
 				isolatedAgents.delete(existing.id);
 				return result(existing, `Closed ${existing.id}.`);
@@ -896,7 +1119,7 @@ export function registerStatefulSubagents(
 				try {
 					agents = await ownedRegistry.closeTree(agentId);
 				} finally {
-					await cleanupClosedWorkspaces(ownedRegistry, isolatedAgents, workspaceManager);
+					await cleanupClosedWorkspaces(ownedRegistry, isolatedAgents, currentWorkspaceManager);
 				}
 				assertCurrentSpawn(signal, generation, runtimeGeneration);
 				return {
@@ -911,7 +1134,7 @@ export function registerStatefulSubagents(
 			try {
 				agent = await ownedRegistry.close(agentId);
 			} finally {
-				await cleanupClosedWorkspaces(ownedRegistry, isolatedAgents, workspaceManager);
+				await cleanupClosedWorkspaces(ownedRegistry, isolatedAgents, currentWorkspaceManager);
 			}
 			assertCurrentSpawn(signal, generation, runtimeGeneration);
 			return result(agent, `Closed ${agent.id}.`);