@narumitw/pi-subagents 0.30.1 → 0.33.0

package/src/limits.ts

@@ -31,7 +31,10 @@ export function truncateUtf8(text: string, maxBytes: number): BoundedText {
 			originalBytes,
 		};
 	}
-	const prefix = Buffer.from(text, "utf8").subarray(0, limit - marker.length).toString("utf8").replace(/�+$/g, "");
+	const prefix = Buffer.from(text, "utf8")
+		.subarray(0, limit - marker.length)
+		.toString("utf8")
+		.replace(/�+$/g, "");
 	return { text: `${prefix}${TRUNCATION_MARKER}`, truncated: true, originalBytes };
 }
 
@@ -45,7 +48,10 @@ export function truncateUtf8Tail(text: string, maxBytes: number): BoundedText {
 	const marker = Buffer.from(TAIL_TRUNCATION_MARKER, "utf8");
 	if (marker.length >= limit) {
 		return {
-			text: bytes.subarray(originalBytes - limit).toString("utf8").replace(/^�+/g, ""),
+			text: bytes
+				.subarray(originalBytes - limit)
+				.toString("utf8")
+				.replace(/^�+/g, ""),
 			truncated: true,
 			originalBytes,
 		};

package/src/params.ts

@@ -1,5 +1,5 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import { Type, type Static } from "typebox";
+import { type Static, Type } from "typebox";
 import { THINKING_LEVELS } from "./agents.js";
 
 const TimeoutMs = Type.Number({
@@ -31,9 +31,15 @@ const ChainItem = Type.Object({
 
 const AggregatorItem = Type.Object(
 	{
-		agent: Type.String({ description: "Name of the fan-in agent to invoke after parallel tasks complete" }),
-		task: Type.String({ description: "Fan-in task. Use {previous} to include all parallel outputs." }),
-		cwd: Type.Optional(Type.String({ description: "Working directory for the aggregator process" })),
+		agent: Type.String({
+			description: "Name of the fan-in agent to invoke after parallel tasks complete",
+		}),
+		task: Type.String({
+			description: "Fan-in task. Use {previous} to include all parallel outputs.",
+		}),
+		cwd: Type.Optional(
+			Type.String({ description: "Working directory for the aggregator process" }),
+		),
 		timeoutMs: Type.Optional(TimeoutMs),
 		thinkingLevel: Type.Optional(ThinkingLevelSchema),
 	},
@@ -50,16 +56,27 @@ const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
 });
 
 export const SubagentParams = Type.Object({
-	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (for single mode)" })),
+	agent: Type.Optional(
+		Type.String({ description: "Name of the agent to invoke (for single mode)" }),
+	),
 	task: Type.Optional(Type.String({ description: "Task to delegate (for single mode)" })),
-	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
-	chain: Type.Optional(Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" })),
+	tasks: Type.Optional(
+		Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" }),
+	),
+	chain: Type.Optional(
+		Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" }),
+	),
 	aggregator: Type.Optional(AggregatorItem),
 	agentScope: Type.Optional(AgentScopeSchema),
 	confirmProjectAgents: Type.Optional(
-		Type.Boolean({ description: "Prompt before running project-local agents. Default: true.", default: true }),
+		Type.Boolean({
+			description: "Prompt before running project-local agents. Default: true.",
+			default: true,
+		}),
+	),
+	cwd: Type.Optional(
+		Type.String({ description: "Working directory for the agent process (single mode)" }),
 	),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 	timeoutMs: Type.Optional(TimeoutMs),
 	thinkingLevel: Type.Optional(ThinkingLevelSchema),
 });

package/src/render.ts

@@ -440,8 +440,7 @@ export function renderSubagentResult(
 			const collapsed = getCollapsedDisplayItems(r);
 			const finalOutput = getResultFinalOutput(r).trim();
 			text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", r.agent)} ${rIcon}`;
-			if (rFailed && r.errorMessage)
-				text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
+			if (rFailed && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
 			if (collapsed.items.length > 0)
 				text += `\n${renderDisplayItems(collapsed.items, 5, collapsed.total)}`;
 			else if (currentIsRunning && r === currentResult)
@@ -605,8 +604,7 @@ export function renderSubagentResult(
 			const collapsed = getCollapsedDisplayItems(r);
 			const finalOutput = getResultFinalOutput(r).trim();
 			text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`;
-			if (rFailed && r.errorMessage)
-				text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
+			if (rFailed && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
 			if (collapsed.items.length > 0)
 				text += `\n${renderDisplayItems(collapsed.items, 5, collapsed.total)}`;
 			else if (rRunning) text += `\n${theme.fg("muted", "(running...)")}`;

package/src/settings.ts

@@ -80,6 +80,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"]> = {};
@@ -241,6 +250,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,6 +270,46 @@ export function subagentSettingsFilePath(): string {
 	return path.join(getAgentDir(), SETTINGS_FILE);
 }
 
+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";
+}
+
+export function inspectDelegationWorkflowSettings(): DelegationWorkflowSettingsSnapshot {
+	const configPath = subagentSettingsFilePath();
+	if (!fs.existsSync(configPath)) {
+		return { path: configPath, value: "all", source: "default" };
+	}
+	try {
+		const raw = 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.blocking) && hasOwn(raw.blocking, "enabled")) ||
+			(isPlainObject(raw.stateful) && hasOwn(raw.stateful, "enabled"));
+		return {
+			path: configPath,
+			value: resolveDelegationWorkflow(
+				settings.blocking?.enabled !== false,
+				settings.stateful?.enabled !== false,
+			),
+			source: explicit ? "user settings" : "default",
+		};
+	} catch (error) {
+		return {
+			path: configPath,
+			value: "all",
+			source: "default",
+			error: formatError(error),
+		};
+	}
+}
+
 export function inspectCompletionDeliverySettings(): CompletionDeliverySettingsSnapshot {
 	const configPath = subagentSettingsFilePath();
 	if (!fs.existsSync(configPath)) {
@@ -261,8 +319,7 @@ export function inspectCompletionDeliverySettings(): CompletionDeliverySettingsS
 		const raw = 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");
+		const explicit = isPlainObject(raw.stateful) && hasOwn(raw.stateful, "completionDelivery");
 		return {
 			path: configPath,
 			value: settings.stateful?.completionDelivery ?? DEFAULT_COMPLETION_DELIVERY,
@@ -278,6 +335,31 @@ export function inspectCompletionDeliverySettings(): CompletionDeliverySettingsS
 	}
 }
 
+export function updateDelegationWorkflowSetting(
+	value: Exclude<DelegationWorkflow, "disabled">,
+): void {
+	const raw = readSettingsObjectForUpdate();
+	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`);
+	}
+	writeSettingsObject({
+		...raw,
+		blocking: {
+			...(blocking ?? {}),
+			enabled: value !== "async-only",
+		},
+		stateful: {
+			...(stateful ?? {}),
+			enabled: value !== "blocking-only",
+		},
+	});
+}
+
 export function updateCompletionDeliverySetting(value: CompletionDelivery): void {
 	const raw = readSettingsObjectForUpdate();
 	const stateful = raw.stateful;

package/src/stateful-prompt.ts

@@ -1,14 +1,11 @@
 import type { AgentConfig } from "./agents.js";
+import { redactPrivateText } from "./context.js";
 import { resolveDefaultSubagentTimeoutMs } from "./execution.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
-import { redactPrivateText } from "./context.js";
 import type { ManagedAgent } from "./registry.js";
 
 export function buildStatefulTurnPrompt(
-	record: Pick<
-		ManagedAgent,
-		"context" | "history" | "mailbox" | "currentMailboxMessageIds"
-	>,
+	record: Pick<ManagedAgent, "context" | "history" | "mailbox" | "currentMailboxMessageIds">,
 	task: string,
 	maxBytes = DEFAULT_MAX_CONTEXT_BYTES,
 ): { text: string; truncated: boolean } {

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 =

package/src/subagents.ts

@@ -22,6 +22,33 @@ import { consumeSubagentSettingsNotice, readSubagentSettings } from "./settings.
 import { registerStatefulSubagents } from "./stateful.js";
 
 export default function (pi: ExtensionAPI) {
+	const settings = readSubagentSettings();
+	if (settings?.blocking?.enabled !== false) registerBlockingSubagent(pi);
+
+	pi.on("session_start", (_event, ctx) => {
+		// Preserve a one-shot migration notice from extension load while refreshing
+		// validation against settings that may have changed before this session.
+		const loadNotice = consumeSubagentSettingsNotice();
+		readSubagentSettings();
+		const refreshedNotice = consumeSubagentSettingsNotice();
+		const notice = [
+			...new Set([loadNotice, refreshedNotice].filter((value) => value !== undefined)),
+		].join("\n");
+		if (notice) ctx.ui.notify(notice, "warning");
+	});
+
+	const blockingEnabled = settings?.blocking?.enabled !== false;
+	const statefulRuntime = registerStatefulSubagents(pi, {
+		blockingEnabled,
+		settings: settings?.stateful,
+	});
+	registerSubagentConfigCommand(pi, {
+		...statefulRuntime,
+		getBlockingEnabled: () => blockingEnabled,
+	});
+}
+
+function registerBlockingSubagent(pi: ExtensionAPI) {
 	pi.registerTool<typeof SubagentParams, SubagentDetails>({
 		name: "subagent",
 		label: "Blocking Subagent",
@@ -65,24 +92,14 @@ export default function (pi: ExtensionAPI) {
 		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError)
 			return { isError: true };
 	});
-
-	pi.on("session_start", (_event, ctx) => {
-		let notice = consumeSubagentSettingsNotice();
-		if (!notice) {
-			readSubagentSettings();
-			notice = consumeSubagentSettingsNotice();
-		}
-		if (notice) ctx.ui.notify(notice, "warning");
-	});
-
-	const statefulRuntime = registerStatefulSubagents(pi);
-	registerSubagentConfigCommand(pi, statefulRuntime);
 }
+
 export { parsePositiveInteger } from "./execution.js";
 export { formatTokens, formatUsageStats } from "./render.js";
 export { buildPiArgs } from "./runner.js";
 export {
 	inspectCompletionDeliverySettings,
+	inspectDelegationWorkflowSettings,
 	normalizeAgentSettings,
 	normalizeSubagentSettings,
 	readSubagentSettings,
@@ -93,4 +110,5 @@ export {
 	uniqueToolNames,
 	updateAgentToolsSetting,
 	updateCompletionDeliverySetting,
+	updateDelegationWorkflowSetting,
 } from "./settings.js";

package/src/workspace.ts

@@ -27,10 +27,10 @@ export class WorkspaceManager {
 		if (relativeCwd.startsWith("..") || path.isAbsolute(relativeCwd)) {
 			throw new Error("Subagent cwd is outside the Git repository");
 		}
-		const status = (
-			await execFileAsync("git", ["-C", repositoryRoot, "status", "--porcelain"])
-		).stdout;
-		if (status.trim()) throw new Error("Isolated subagent workspace requires a clean Git repository");
+		const status = (await execFileAsync("git", ["-C", repositoryRoot, "status", "--porcelain"]))
+			.stdout;
+		if (status.trim())
+			throw new Error("Isolated subagent workspace requires a clean Git repository");
 		const rootPath = await fs.promises.mkdtemp(path.join(os.tmpdir(), WORKTREE_PREFIX));
 		let registered = false;
 		try {
@@ -86,8 +86,9 @@ export class WorkspaceManager {
 			workspace.rootPath,
 		]).catch(async () => {
 			await fs.promises.rm(workspace.rootPath, { recursive: true, force: true });
-			await execFileAsync("git", ["-C", workspace.repositoryRoot, "worktree", "prune"])
-				.catch(() => undefined);
+			await execFileAsync("git", ["-C", workspace.repositoryRoot, "worktree", "prune"]).catch(
+				() => undefined,
+			);
 		});
 		await fs.promises.rm(`${workspace.rootPath}.owner`, { force: true });
 	}