@narumitw/pi-subagents 0.31.0 → 0.35.0

package/src/settings.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
 import {
 	type AgentConfig,
 	type CompletionDelivery,
@@ -80,6 +81,15 @@ export function normalizeSubagentSettings(value: unknown): SubagentSettings | un
 		}
 		if (Object.keys(agents).length > 0) settings.agents = agents;
 	}
+	if (hasOwn(value, "blocking")) {
+		if (!isPlainObject(value.blocking)) return undefined;
+		const blocking: NonNullable<SubagentSettings["blocking"]> = {};
+		if (hasOwn(value.blocking, "enabled")) {
+			if (typeof value.blocking.enabled !== "boolean") return undefined;
+			blocking.enabled = value.blocking.enabled;
+		}
+		settings.blocking = blocking;
+	}
 	if (hasOwn(value, "stateful")) {
 		if (!isPlainObject(value.stateful)) return undefined;
 		const runtime: NonNullable<SubagentSettings["stateful"]> = {};
@@ -132,13 +142,42 @@ export function normalizeSubagentSettings(value: unknown): SubagentSettings | un
 const SETTINGS_FILE = "pi-subagents.json";
 const LEGACY_SETTINGS_FILE = "pi-subagents-config.json";
 const DEFAULT_COMPLETION_DELIVERY: CompletionDelivery = "next-turn";
+const SETTINGS_LOCK_FS_ADAPTER = {
+	mkdir: fs.mkdir,
+	mkdirSync: fs.mkdirSync,
+	realpath: fs.realpath,
+	realpathSync: fs.realpathSync,
+	rmdir: fs.rmdir,
+	rmdirSync: fs.rmdirSync,
+	stat: fs.stat,
+	statSync: fs.statSync,
+	utimes: fs.utimes,
+	utimesSync: fs.utimesSync,
+};
 let pendingSettingsNotice: string | undefined;
 
-export function readSubagentSettings(): SubagentSettings | undefined {
-	pendingSettingsNotice = undefined;
+function resolveSubagentSettingsPaths(): {
+	canonicalPath: string;
+	legacyPath: string;
+	activePath?: string;
+} {
 	const canonicalPath = path.join(getAgentDir(), SETTINGS_FILE);
 	const legacyPath = path.join(getAgentDir(), LEGACY_SETTINGS_FILE);
-	if (fs.existsSync(canonicalPath)) {
+	return {
+		canonicalPath,
+		legacyPath,
+		activePath: fs.existsSync(canonicalPath)
+			? canonicalPath
+			: fs.existsSync(legacyPath)
+				? legacyPath
+				: undefined,
+	};
+}
+
+export function readSubagentSettings(): SubagentSettings | undefined {
+	pendingSettingsNotice = undefined;
+	const { canonicalPath, legacyPath, activePath } = resolveSubagentSettingsPaths();
+	if (activePath === canonicalPath) {
 		const canonical = readSettingsFile(canonicalPath);
 		const notices: string[] = [];
 		if (!canonical) notices.push(`${SETTINGS_FILE} is invalid and was ignored.`);
@@ -148,89 +187,24 @@ export function readSubagentSettings(): SubagentSettings | undefined {
 		if (notices.length > 0) pendingSettingsNotice = notices.join("\n");
 		return canonical;
 	}
-	if (!fs.existsSync(legacyPath)) return undefined;
-	const legacySnapshot = readSettingsSnapshot(legacyPath);
-	const legacy = legacySnapshot.settings;
+	if (activePath === undefined) return undefined;
+	const legacy = readSettingsFile(legacyPath);
+	if (fs.existsSync(canonicalPath)) {
+		const canonical = readSettingsFile(canonicalPath);
+		pendingSettingsNotice = [
+			...(!canonical ? [`${SETTINGS_FILE} is invalid and was ignored.`] : []),
+			`${LEGACY_SETTINGS_FILE} ignored because ${SETTINGS_FILE} was created concurrently.`,
+		].join("\n");
+		return canonical;
+	}
 	if (!legacy) {
 		pendingSettingsNotice = `${LEGACY_SETTINGS_FILE} is invalid and was ignored.`;
 		return undefined;
 	}
-	let installedIdentity: FileIdentity;
-	try {
-		installedIdentity = installFileExclusively(canonicalPath, legacySnapshot.contents ?? "");
-	} catch (error) {
-		if (fs.existsSync(canonicalPath)) {
-			const canonical = readSettingsFile(canonicalPath);
-			pendingSettingsNotice = [
-				...(!canonical ? [`${SETTINGS_FILE} is invalid and was ignored.`] : []),
-				`${LEGACY_SETTINGS_FILE} ignored because ${SETTINGS_FILE} was created concurrently.`,
-			].join("\n");
-			return canonical;
-		}
-		pendingSettingsNotice = `Subagent settings migration failed: ${formatError(error)}. The legacy file was used for this session.`;
-		return legacy;
-	}
-	if (!fileContentsEqual(legacyPath, legacySnapshot.contents ?? "")) {
-		pendingSettingsNotice = removeFileIfIdentityMatches(
-			canonicalPath,
-			installedIdentity,
-			legacySnapshot.contents ?? "",
-		)
-			? `${LEGACY_SETTINGS_FILE} changed during migration; the stale ${SETTINGS_FILE} snapshot was removed.`
-			: `${LEGACY_SETTINGS_FILE} changed during migration, but ${SETTINGS_FILE} was replaced concurrently and takes precedence on the next load.`;
-		return legacy;
-	}
-	try {
-		fs.rmSync(legacyPath);
-		pendingSettingsNotice = `Subagent settings migrated from ${LEGACY_SETTINGS_FILE} to ${SETTINGS_FILE}.`;
-	} catch (error) {
-		pendingSettingsNotice = `Subagent settings migrated to ${SETTINGS_FILE}, but ${LEGACY_SETTINGS_FILE} could not be removed: ${formatError(error)}.`;
-	}
+	pendingSettingsNotice = `Using legacy ${LEGACY_SETTINGS_FILE}; rename it to ${SETTINGS_FILE}. Future saves write ${SETTINGS_FILE} without modifying the legacy file.`;
 	return legacy;
 }
 
-type FileIdentity = { dev: number; ino: number };
-
-function installFileExclusively(filePath: string, contents: string): FileIdentity {
-	const tempFile = path.join(path.dirname(filePath), `.${SETTINGS_FILE}.${randomUUID()}.tmp`);
-	try {
-		fs.writeFileSync(tempFile, contents, { encoding: "utf8", flag: "wx" });
-		const identity = fs.lstatSync(tempFile);
-		fs.linkSync(tempFile, filePath);
-		return { dev: identity.dev, ino: identity.ino };
-	} finally {
-		try {
-			fs.rmSync(tempFile, { force: true });
-		} catch {
-			// Preserve the migration result if best-effort temp cleanup fails.
-		}
-	}
-}
-
-function removeFileIfIdentityMatches(
-	filePath: string,
-	expected: FileIdentity,
-	expectedContents: string,
-) {
-	try {
-		const current = fs.lstatSync(filePath);
-		if (current.dev !== expected.dev || current.ino !== expected.ino) return false;
-		if (fs.readFileSync(filePath, "utf8") !== expectedContents) return false;
-		fs.rmSync(filePath);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function fileContentsEqual(filePath: string, expected: string) {
-	try {
-		return fs.readFileSync(filePath, "utf8") === expected;
-	} catch {
-		return false;
-	}
-}
-
 export function consumeSubagentSettingsNotice() {
 	const notice = pendingSettingsNotice;
 	pendingSettingsNotice = undefined;
@@ -241,6 +215,15 @@ export function saveSubagentConfig(settings: SubagentSettings): void {
 	writeSettingsObject(settings);
 }
 
+export type DelegationWorkflow = "all" | "async-only" | "blocking-only" | "disabled";
+
+export interface DelegationWorkflowSettingsSnapshot {
+	path: string;
+	value: DelegationWorkflow;
+	source: "default" | "user settings";
+	error?: string;
+}
+
 export interface CompletionDeliverySettingsSnapshot {
 	path: string;
 	value: CompletionDelivery;
@@ -252,102 +235,217 @@ export function subagentSettingsFilePath(): string {
 	return path.join(getAgentDir(), SETTINGS_FILE);
 }
 
-export function inspectCompletionDeliverySettings(): CompletionDeliverySettingsSnapshot {
-	const configPath = subagentSettingsFilePath();
-	if (!fs.existsSync(configPath)) {
-		return { path: configPath, value: DEFAULT_COMPLETION_DELIVERY, source: "default" };
-	}
+export function resolveDelegationWorkflow(
+	blockingEnabled: boolean,
+	statefulEnabled: boolean,
+): DelegationWorkflow {
+	if (blockingEnabled && statefulEnabled) return "all";
+	if (statefulEnabled) return "async-only";
+	if (blockingEnabled) return "blocking-only";
+	return "disabled";
+}
+
+function inspectSubagentSettingsDocument(): {
+	path: string;
+	raw?: Record<string, unknown>;
+	settings?: SubagentSettings;
+	error?: string;
+} {
+	const { canonicalPath, activePath } = resolveSubagentSettingsPaths();
+	if (activePath === undefined) return { path: canonicalPath };
+	const inspected = inspectSubagentSettingsPath(activePath);
+	return activePath !== canonicalPath && fs.existsSync(canonicalPath)
+		? inspectSubagentSettingsPath(canonicalPath)
+		: inspected;
+}
+
+function inspectSubagentSettingsPath(configPath: string): {
+	path: string;
+	raw?: Record<string, unknown>;
+	settings?: SubagentSettings;
+	error?: string;
+} {
 	try {
-		const raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+		const raw: unknown = JSON.parse(fs.readFileSync(configPath, "utf8"));
 		const settings = normalizeSubagentSettings(raw);
-		if (!settings) throw new Error(`${SETTINGS_FILE} is not a valid settings object`);
-		const explicit = isPlainObject(raw.stateful) && hasOwn(raw.stateful, "completionDelivery");
+		if (!isPlainObject(raw) || !settings) {
+			throw new Error(`${path.basename(configPath)} is not a valid settings object`);
+		}
+		return { path: configPath, raw, settings };
+	} catch (error) {
+		return { path: configPath, error: formatError(error) };
+	}
+}
+
+export function inspectDelegationWorkflowSettings(): DelegationWorkflowSettingsSnapshot {
+	const inspected = inspectSubagentSettingsDocument();
+	if (!inspected.raw || !inspected.settings) {
 		return {
-			path: configPath,
-			value: settings.stateful?.completionDelivery ?? DEFAULT_COMPLETION_DELIVERY,
-			source: explicit ? "user settings" : "default",
+			path: inspected.path,
+			value: "all",
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
 		};
-	} catch (error) {
+	}
+	const explicit =
+		(isPlainObject(inspected.raw.blocking) && hasOwn(inspected.raw.blocking, "enabled")) ||
+		(isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "enabled"));
+	return {
+		path: inspected.path,
+		value: resolveDelegationWorkflow(
+			inspected.settings.blocking?.enabled !== false,
+			inspected.settings.stateful?.enabled !== false,
+		),
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function inspectCompletionDeliverySettings(): CompletionDeliverySettingsSnapshot {
+	const inspected = inspectSubagentSettingsDocument();
+	if (!inspected.raw || !inspected.settings) {
 		return {
-			path: configPath,
+			path: inspected.path,
 			value: DEFAULT_COMPLETION_DELIVERY,
 			source: "default",
-			error: formatError(error),
+			...(inspected.error ? { error: inspected.error } : {}),
 		};
 	}
+	const explicit =
+		isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "completionDelivery");
+	return {
+		path: inspected.path,
+		value: inspected.settings.stateful?.completionDelivery ?? DEFAULT_COMPLETION_DELIVERY,
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function updateDelegationWorkflowSetting(
+	value: Exclude<DelegationWorkflow, "disabled">,
+): void {
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const blocking = raw.blocking;
+		if (blocking !== undefined && !isPlainObject(blocking)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} blocking settings`);
+		}
+		const stateful = raw.stateful;
+		if (stateful !== undefined && !isPlainObject(stateful)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
+		}
+		writeSettingsObjectUnlocked(
+			{
+				...raw,
+				blocking: {
+					...(blocking ?? {}),
+					enabled: value !== "async-only",
+				},
+				stateful: {
+					...(stateful ?? {}),
+					enabled: value !== "blocking-only",
+				},
+			},
+			update.replaceCanonical,
+		);
+	});
 }
 
 export function updateCompletionDeliverySetting(value: CompletionDelivery): void {
-	const raw = readSettingsObjectForUpdate();
-	const stateful = raw.stateful;
-	if (stateful !== undefined && !isPlainObject(stateful)) {
-		throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
-	}
-	writeSettingsObject({
-		...raw,
-		stateful: {
-			...(stateful ?? {}),
-			completionDelivery: value,
-		},
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const stateful = raw.stateful;
+		if (stateful !== undefined && !isPlainObject(stateful)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
+		}
+		writeSettingsObjectUnlocked(
+			{
+				...raw,
+				stateful: {
+					...(stateful ?? {}),
+					completionDelivery: value,
+				},
+			},
+			update.replaceCanonical,
+		);
 	});
 }
 
 export function updateAgentToolsSetting(name: string, tools: string[] | undefined): void {
-	const raw = readSettingsObjectForUpdate();
-	const rawAgents = raw.agents;
-	if (rawAgents !== undefined && !isPlainObject(rawAgents)) {
-		throw new Error(`Cannot update invalid ${SETTINGS_FILE} agent settings`);
-	}
-	const agents = { ...(rawAgents ?? {}) };
-	const rawAgent = hasOwn(agents, name) ? agents[name] : undefined;
-	if (rawAgent !== undefined && !isPlainObject(rawAgent)) {
-		throw new Error(`Cannot update invalid ${SETTINGS_FILE} settings for ${name}`);
-	}
-	const agent = { ...(rawAgent ?? {}) };
-	if (tools === undefined) delete agent.tools;
-	else agent.tools = tools;
-	if (Object.keys(agent).length > 0) {
-		Object.defineProperty(agents, name, {
-			value: agent,
-			enumerable: true,
-			configurable: true,
-			writable: true,
-		});
-	} else {
-		delete agents[name];
-	}
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const rawAgents = raw.agents;
+		if (rawAgents !== undefined && !isPlainObject(rawAgents)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} agent settings`);
+		}
+		const agents = { ...(rawAgents ?? {}) };
+		const rawAgent = hasOwn(agents, name) ? agents[name] : undefined;
+		if (rawAgent !== undefined && !isPlainObject(rawAgent)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} settings for ${name}`);
+		}
+		const agent = { ...(rawAgent ?? {}) };
+		if (tools === undefined) delete agent.tools;
+		else agent.tools = tools;
+		if (Object.keys(agent).length > 0) {
+			Object.defineProperty(agents, name, {
+				value: agent,
+				enumerable: true,
+				configurable: true,
+				writable: true,
+			});
+		} else {
+			delete agents[name];
+		}
+
+		const updated = { ...raw };
+		if (Object.keys(agents).length > 0) updated.agents = agents;
+		else delete updated.agents;
+		writeSettingsObjectUnlocked(updated, update.replaceCanonical);
+	});
+}
 
-	const updated = { ...raw };
-	if (Object.keys(agents).length > 0) updated.agents = agents;
-	else delete updated.agents;
-	writeSettingsObject(updated);
+interface SettingsObjectForUpdate {
+	document: Record<string, unknown>;
+	replaceCanonical: boolean;
 }
 
-function readSettingsObjectForUpdate(): Record<string, unknown> {
-	const configPath = subagentSettingsFilePath();
-	if (!fs.existsSync(configPath)) return {};
+function readSettingsObjectForUpdate(): SettingsObjectForUpdate {
+	const { canonicalPath, activePath } = resolveSubagentSettingsPaths();
+	if (activePath === undefined) return { document: {}, replaceCanonical: false };
+	const activeFile = path.basename(activePath);
 	let parsed: unknown;
 	try {
-		parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+		parsed = JSON.parse(fs.readFileSync(activePath, "utf8"));
 	} catch (error) {
-		throw new Error(`Cannot update malformed ${SETTINGS_FILE}: ${formatError(error)}`);
+		throw new Error(`Cannot update malformed ${activeFile}: ${formatError(error)}`);
 	}
 	if (!isPlainObject(parsed) || !normalizeSubagentSettings(parsed)) {
-		throw new Error(`Cannot update invalid ${SETTINGS_FILE}`);
+		throw new Error(`Cannot update invalid ${activeFile}`);
 	}
-	return parsed;
+	return { document: parsed, replaceCanonical: activePath === canonicalPath };
+}
+
+function writeSettingsObject(settings: object, replaceCanonical?: boolean): void {
+	withSettingsMutationLock(() => writeSettingsObjectUnlocked(settings, replaceCanonical));
 }
 
-function writeSettingsObject(settings: object): void {
+function writeSettingsObjectUnlocked(settings: object, replaceCanonical?: boolean): void {
 	const agentDir = getAgentDir();
 	fs.mkdirSync(agentDir, { recursive: true });
 	const configPath = path.join(agentDir, SETTINGS_FILE);
 	const tempFile = path.join(agentDir, `.${SETTINGS_FILE}.${randomUUID()}.tmp`);
+	// Updates seeded from a missing or legacy document must remain exclusive even if the
+	// canonical path appears after the read and before publication.
+	const firstCanonicalPublication = !(replaceCanonical ?? pathEntryExists(configPath));
 	try {
 		fs.writeFileSync(tempFile, `${JSON.stringify(settings, null, "\t")}\n`, {
 			encoding: "utf8",
 			flag: "wx",
 		});
+		if (firstCanonicalPublication && pathEntryExists(configPath)) {
+			throw new Error(`${SETTINGS_FILE} was created concurrently; reopen settings and retry`);
+		}
 		fs.renameSync(tempFile, configPath);
 	} finally {
 		try {
@@ -358,6 +456,32 @@ function writeSettingsObject(settings: object): void {
 	}
 }
 
+function withSettingsMutationLock<T>(mutate: () => T): T {
+	const agentDir = getAgentDir();
+	fs.mkdirSync(agentDir, { recursive: true });
+	const configPath = path.join(agentDir, SETTINGS_FILE);
+	const release = lockfile.lockSync(configPath, {
+		fs: SETTINGS_LOCK_FS_ADAPTER,
+		lockfilePath: `${configPath}.mutation-lock`,
+		realpath: false,
+	});
+	try {
+		return mutate();
+	} finally {
+		release();
+	}
+}
+
+function pathEntryExists(filePath: string): boolean {
+	try {
+		fs.lstatSync(filePath);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
 function readSettingsFile(configPath: string): SubagentSettings | undefined {
 	return readSettingsSnapshot(configPath).settings;
 }

package/src/stateful.ts

@@ -12,6 +12,7 @@ import {
 	type CompletionDelivery,
 	discoverAgents,
 	isThinkingLevel,
+	type SubagentRuntimeSettings,
 	THINKING_LEVELS,
 } from "./agents.js";
 import { buildContextSnapshot, type ContextMode, redactPrivateText } from "./context.js";
@@ -52,11 +53,18 @@ const MAX_COMPLETION_ERROR_BYTES = 512;
 const MAX_COMPLETIONS_PER_MESSAGE = 16;
 const COMPLETION_BATCH_DELAY_MS = 10;
 
-function createSpawnPromptGuidelines(completionDelivery: CompletionDelivery): string[] {
+function createSpawnPromptGuidelines(
+	completionDelivery: CompletionDelivery,
+	blockingEnabled = true,
+): string[] {
 	const deliveryGuidance =
 		completionDelivery === "auto-resume"
-			? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
-			: "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or review only when the current response does not depend on its result; use the blocking subagent when the final answer depends on the detached result.";
+			? blockingEnabled
+				? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
+				: "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result."
+			: blockingEnabled
+				? "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or review only when the current response does not depend on its result; use the blocking subagent when the final answer depends on the detached result."
+				: "With subagent_spawn completion delivery set to next-turn (the default), use subagent_spawn only when the current response does not depend on its result; complete final-answer-dependent work directly because an idle root is not awakened.";
 	const noLocalWorkGuidance =
 		completionDelivery === "auto-resume"
 			? "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response; auto-resume will request a synthesis turn after completion."
@@ -66,8 +74,12 @@ function createSpawnPromptGuidelines(completionDelivery: CompletionDelivery): st
 		"Set subagent_spawn thinkingLevel to the lowest sufficient thinking level for the delegated task: use off or minimal for extraction, formatting, or mechanical work; low for straightforward bounded work; medium for ordinary multi-step research or implementation; high for complex debugging, design, review, or cross-file analysis; xhigh for highly ambiguous, cross-system, or high-risk analysis; and max only for the hardest tasks when quality clearly outweighs latency and cost. Omit subagent_spawn thinkingLevel only to preserve the agent or child default.",
 		deliveryGuidance,
 		"Use a single subagent_spawn only for a concrete bounded subtask that can run independently and has an isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation.",
-		"Use the blocking subagent instead of subagent_spawn when synchronous output is required before the main agent can continue and waiting is intentional; queued steering cannot be processed until that blocking call returns.",
-		"When subagent_spawn fits the completion-delivery policy, do not choose a blocking parallel subagent merely to keep delegation in the same turn.",
+		...(blockingEnabled
+			? [
+					"Use the blocking subagent instead of subagent_spawn when synchronous output is required before the main agent can continue and waiting is intentional; queued steering cannot be processed until that blocking call returns.",
+					"When subagent_spawn fits the completion-delivery policy, do not choose a blocking parallel subagent merely to keep delegation in the same turn.",
+				]
+			: []),
 		"Add another subagent_spawn only for truly independent work with safe workspace concurrency.",
 		noLocalWorkGuidance,
 		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
@@ -76,8 +88,10 @@ function createSpawnPromptGuidelines(completionDelivery: CompletionDelivery): st
 }
 
 export interface StatefulSubagentDependencies {
+	blockingEnabled?: boolean;
 	createInProcessSession?: ChildSessionFactory;
 	workspaceManager?: WorkspaceManager;
+	settings?: SubagentRuntimeSettings;
 }
 
 export interface StatefulSubagentRuntimeStatus {
@@ -106,7 +120,10 @@ export function registerStatefulSubagents(
 	pi: ExtensionAPI,
 	dependencies: StatefulSubagentDependencies = {},
 ): StatefulSubagentController {
-	const settings = readSubagentSettings()?.stateful ?? {};
+	const settings = Object.hasOwn(dependencies, "settings")
+		? (dependencies.settings ?? {})
+		: (readSubagentSettings()?.stateful ?? {});
+	const blockingEnabled = dependencies.blockingEnabled !== false;
 	const enabled = settings.enabled !== false;
 	const transportKind = resolveStatefulTransportKind(settings.transport);
 	let completionDelivery = resolveCompletionDelivery(settings.completionDelivery);
@@ -304,7 +321,7 @@ export function registerStatefulSubagents(
 		description:
 			"Start an addressable background subagent with an optional thinking level chosen for the task difficulty, return immediately with an agentId, and receive its completion asynchronously.",
 		promptSnippet: "Start a reusable detached subagent; completion is delivered asynchronously",
-		promptGuidelines: createSpawnPromptGuidelines(completionDelivery),
+		promptGuidelines: createSpawnPromptGuidelines(completionDelivery, blockingEnabled),
 		parameters: Type.Object({
 			agent: Type.String({ minLength: 1 }),
 			task: Type.String({ minLength: 1, maxLength: DEFAULT_MAX_CONTEXT_BYTES }),
@@ -382,7 +399,7 @@ export function registerStatefulSubagents(
 		},
 	});
 	refreshSpawnToolRegistration = () => {
-		spawnTool.promptGuidelines = createSpawnPromptGuidelines(completionDelivery);
+		spawnTool.promptGuidelines = createSpawnPromptGuidelines(completionDelivery, blockingEnabled);
 		pi.registerTool(spawnTool);
 	};
 	refreshSpawnToolRegistration();
@@ -531,39 +548,6 @@ export function registerStatefulSubagents(
 		},
 	});
 
-	pi.registerCommand("subagents:agents", {
-		description: "Inspect or clear current-session subagents",
-		getArgumentCompletions(prefix: string) {
-			return ["list", "clear"]
-				.filter((value) => value.startsWith(prefix))
-				.map((value) => ({ value, label: value }));
-		},
-		async handler(args, ctx) {
-			const subcommand = args.trim().toLowerCase() || "list";
-			if (subcommand === "clear") {
-				const count = await controller.clearAgents();
-				ctx.ui.notify(
-					count > 0
-						? `Cleared ${count} current-session subagent${count === 1 ? "" : "s"}.`
-						: statefulEmptyMessage(controller.getRuntimeStatus()),
-					"info",
-				);
-				return;
-			}
-			if (subcommand !== "list") {
-				ctx.ui.notify(`Unknown /subagents:agents subcommand: ${subcommand}`, "warning");
-				return;
-			}
-			const agents = controller.listAgents(true);
-			ctx.ui.notify(
-				agents.length
-					? agents.map(formatLine).join("\n")
-					: statefulEmptyMessage(controller.getRuntimeStatus()),
-				"info",
-			);
-		},
-	});
-
 	return controller;
 }
 
@@ -652,12 +636,6 @@ export function resolveSpawnContextMode(
 	return normalizeContextMode(value);
 }
 
-function statefulEmptyMessage(status: StatefulSubagentRuntimeStatus): string {
-	if (!status.enabled) return "Stateful subagents are disabled in user settings.";
-	if (!status.initialized) return "Stateful subagents are not initialized for this session.";
-	return "No current-session subagents.";
-}
-
 export function formatStatefulAgentLine(agent: ManagedAgent): string {
 	const elapsedSeconds = Math.max(0, Math.floor((Date.now() - agent.updatedAt) / 1000));
 	const actions =