@narumitw/pi-subagents 0.31.0 → 0.33.0

package/README.md

@@ -2,13 +2,13 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-subagents)](https://www.npmjs.com/package/@narumitw/pi-subagents) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. The blocking batch `subagent` tool keeps isolated Pi subprocesses, while four detached tools run reusable agents either as subprocess-backed logical sessions or as public-SDK in-process child sessions. Together they form a fixed five-tool surface.
+`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. By default, the blocking batch `subagent` tool uses isolated Pi subprocesses while four detached tools run reusable agents either as subprocess-backed logical sessions or as public-SDK in-process child sessions. Users can keep all five tools, choose async-only delegation, or retain only blocking batches.
 
 Use it to split independent research, planning, implementation, and review work across focused workers. Under the default next-turn delivery policy, background delegation is for work the current response does not depend on. Opt-in auto-resume also supports final-answer-dependent background work by requesting a synthesis turn after completion.
 
 ## ✨ Features
 
-- Registers a `subagent` tool for single-agent, parallel, fan-in, and chained delegation.
+- Offers all delegation methods by default, with goal-oriented presets for async-only or blocking-only workflows.
 - Keeps batch workers isolated in `pi --mode json -p --no-session` subprocesses.
 - Registers detached stateful lifecycle tools by default; completion can stay queued for the next turn or opt into an idle root synthesis turn.
 - Supports an opt-in public-SDK `in-process` stateful transport with one reusable child `AgentSession` per `agentId`.
@@ -43,7 +43,17 @@ pi -e ./extensions/pi-subagents
 
 ## 🛠️ Pi tool
 
-`pi-subagents` always registers the primary batch tool and registers the stateful lifecycle tools unless `stateful.enabled` is `false`:
+`pi-subagents` registers all five tools by default. Run `/subagents`, choose **Change delegation**, review the concrete tool changes, then select **Save and reload** to apply one of these workflows:
+
+| Workflow | Registered tools |
+| --- | --- |
+| **All delegation methods** (default) | Blocking `subagent` plus all four detached lifecycle tools |
+| **Async only** | `subagent_spawn`, `subagent_send`, `subagent_manage`, and `subagent_mailbox`; blocking `subagent` is omitted |
+| **Blocking only** | Blocking `subagent` only; equivalent to the existing `stateful.enabled: false` behavior |
+
+The preview compares the selection with the tools registered in the current session, even when a manual settings edit is pending, and remains read-only until confirmation. Escape or **Cancel** leaves settings unchanged. Tool removal requires an extension reload because Pi does not expose extension tool unregistration. To avoid aborting work or removing isolated worktrees during `session_shutdown`, workflow changes are blocked while detached agents are retained; finish or clear them through **Current agents** first. Pi owns reload-error reporting and does not return a success result to extensions, so the save notification also tells users to run `/reload` if the tool surface does not refresh.
+
+The available tools are:
 
 - `subagent` — delegate blocking single, parallel, fan-in, or chained batch work. The main agent cannot process queued steering until the call returns.
 - `subagent_spawn` and related lifecycle tools — when enabled, start reusable detached work, return immediately, and receive bounded completion messages automatically.
@@ -52,7 +62,7 @@ Choose the API by lifecycle:
 
 | Need | Use |
 | --- | --- |
-| A delegated result is required before the root's next action under default next-turn delivery | One blocking `subagent` call (`tasks` for synchronous parallel work) |
+| A delegated result is required before the root's next action under default next-turn delivery | Use one blocking `subagent` call when registered. In **Async only**, complete the critical-path work directly or switch workflows before delegating it |
 | Broad research/review the current response does not depend on | Prefer one `subagent_spawn` covering related branches, when lifecycle tools are enabled |
 | Final-answer-dependent broad work with `completionDelivery: "auto-resume"` | Prefer one `subagent_spawn`; completion requests a synthesis turn |
 | Reusable history, follow-ups, or mailboxes | `subagent_spawn` and lifecycle tools, when enabled |
@@ -75,7 +85,7 @@ For `subagent_spawn`, the root agent selects the lowest thinking level sufficien
 
 ## 🧭 Proactive use
 
-The always-available `subagent` tool advertises only blocking guidance. When stateful lifecycle tools
+When registered, the blocking `subagent` tool advertises only blocking guidance. When stateful lifecycle tools
 are registered, `subagent_spawn` adds detached guidance for the active completion-delivery policy.
 Changing the policy through `/subagents settings` refreshes that guidance immediately.
 
@@ -86,8 +96,10 @@ Count-selection guidance:
 - `subagent` is deliberately blocking: while it runs, the main agent cannot answer queued steering.
   Use it when delegated outputs are required before the next root action and waiting is intentional.
 - With default `completionDelivery: "next-turn"`, prefer **one detached `subagent_spawn`** for broad
-  research or review only when the current response does not depend on its result. Keep
-  final-answer-dependent delegated work on the blocking path because an idle root is not awakened.
+  research or review only when the current response does not depend on its result. When blocking
+  `subagent` is registered, use it for required delegated output because an idle root is not awakened.
+  In **Async only**, complete required work directly, opt into `auto-resume` when a later synthesis
+  turn is appropriate, or switch delegation workflows.
 - With `completionDelivery: "auto-resume"`, prefer one detached `subagent_spawn` for broad related
   research or review even when the final answer depends on it; completion requests a later synthesis
   turn. Do not choose blocking parallel fan-out merely to keep delegation in one turn.
@@ -215,7 +227,7 @@ Run a chain where each step receives the previous output:
 
 Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects a bounded `pi-subagent-completion` custom message. Completions that settle in the same dispatch window are batched, and the broker allows at most one in-flight root wake until that parent turn starts.
 
-Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result; if it does, use blocking `subagent`. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_manage` with `action: "list"` or `subagent_mailbox` with `action: "read"`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
+Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result. If it does, use blocking `subagent` when registered; in **Async only**, complete required work directly, opt into `auto-resume` when a later synthesis turn is appropriate, or switch workflows. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_manage` with `action: "list"` or `subagent_mailbox` with `action: "read"`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
 
 A detached agent additionally needs a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation. Simple work that the main agent can perform directly should not be delegated.
 
@@ -228,13 +240,17 @@ Auto-resume is best-effort because Pi's custom-message API is fire-and-forget. S
 
 The default `subprocess` transport preserves compatibility: each turn starts a fresh isolated `pi --mode json -p --no-session` child and receives sanitized, bounded history. Set `transport` to `in-process` to retain one public Pi SDK `AgentSession` per stateful `agentId`, avoiding repeated process startup while preserving native child history in memory.
 
-Run `/subagents` in TUI mode to open the primary manager. It separates current-session lifecycle state, transport, completion delivery, and active/retained counts from user settings that persist across sessions. Its actions open completion settings, per-agent tool settings, current-session agent inspection/clear, status, and help. Escape returns from a nested screen to a newly refreshed manager and then closes it.
+Run `/subagents` in TUI mode to open the primary manager. It leads with the current delegation workflow, human-readable async completion behavior, and active/retained counts. **Change delegation**, **Current agents**, and **Completion behavior** cover the common workflows; agent permissions, transport/runtime details, source, and settings path remain under **Advanced settings**. Escape returns from a nested screen to a newly refreshed manager and then closes it.
 
-The direct routes remain predictable: `/subagents settings` changes user completion delivery and applies it immediately, including refreshing the model-facing spawn guidance; `/subagents status` reports current-session runtime values separately from the configured value, source, and path; `/subagents help` summarizes commands and compatibility routes. In RPC mode, bare `/subagents` emits the same bounded status through Pi's notification protocol instead of opening a custom TUI. JSON and print modes do not emit ad hoc command output. Manual edits use `~/.pi/agent/pi-subagents.json` and take effect after reloading Pi:
+The direct routes remain predictable: `/subagents settings` changes user completion delivery and applies it immediately, including refreshing the model-facing spawn guidance; `/subagents status` reports current-session runtime values separately from the configured value, source, and path; `/subagents help` summarizes the single-command interface. In RPC mode, bare `/subagents` emits the same bounded status through Pi's notification protocol instead of opening a custom TUI. JSON and print modes do not emit ad hoc command output. Manual edits use `~/.pi/agent/pi-subagents.json` and take effect after reloading Pi:
 
 ```json
 {
+  "blocking": {
+    "enabled": false
+  },
   "stateful": {
+    "enabled": true,
     "transport": "in-process",
     "completionDelivery": "auto-resume",
     "maxAgents": 16,
@@ -250,7 +266,7 @@ The direct routes remain predictable: `/subagents settings` changes user complet
 }
 ```
 
-The settings UI patches the raw JSON atomically and preserves unknown fields; it refuses to overwrite malformed or invalid settings. Set `"enabled": false` to remove all four stateful tools. Otherwise, the extension keeps the following tool membership fixed across spawn, completion, interrupt, close, and mailbox transitions. This avoids lifecycle-driven tool-schema churn and preserves a stable provider prompt prefix for KV caching.
+The settings UI patches the raw JSON atomically and preserves unknown fields; it refuses to overwrite malformed or invalid settings. `blocking.enabled` defaults to `true`; set it to `false` for async-only delegation. `stateful.enabled` also defaults to `true`; its existing `false` value remains the blocking-only workflow. When stateful tools are enabled, their membership stays fixed across spawn, completion, interrupt, close, and mailbox transitions. This avoids lifecycle-driven tool-schema churn and preserves a stable provider prompt prefix for KV caching.
 
 | Tool | Purpose |
 | --- | --- |
@@ -277,7 +293,7 @@ The action schemas are flat for provider compatibility and reject parameters tha
 }
 ```
 
-Use the **Current-session agents** action in `/subagents` to inspect the indented agent tree, lifecycle state, unread count, and available actions, or to confirm clearing retained agents. `/subagents:agents list|clear` remains the compatibility command for the same current-session operations. Active turns are FIFO-limited by `maxActiveTurns`; excess retained work remains in `starting` state until a slot is available. `maxAgents` separately bounds running, queued, and idle records. `parentId` creates a bounded child relationship; subtree interrupt and close operate child-first.
+Use the **Current agents** action in `/subagents` to inspect the indented agent tree, lifecycle state, unread count, and available actions, or to confirm clearing retained agents. Active turns are FIFO-limited by `maxActiveTurns`; excess retained work remains in `starting` state until a slot is available. `maxAgents` separately bounds running, queued, and idle records. `parentId` creates a bounded child relationship; subtree interrupt and close operate child-first.
 
 ### Migrating from the seven-tool lifecycle surface
 
@@ -366,7 +382,7 @@ Built-in agents inherit the active/default Pi model instead of forcing a provide
 
 ## ⚙️ Configure agent tools
 
-Open `/subagents` and choose **Agent tool settings** in an interactive Pi session to edit the tools each subagent may use. `/subagents:config` remains a documented compatibility route to the same screen. These are user settings stored in `~/.pi/agent/pi-subagents.json` and affect future sessions.
+Open `/subagents`, choose **Advanced settings**, then **Agent tool settings** in an interactive Pi session to edit the tools each subagent may use. These are user settings stored in `~/.pi/agent/pi-subagents.json` and affect future sessions.
 
 Compatibility: a valid legacy `pi-subagents-config.json` is migrated automatically to `pi-subagents.json`. If both files exist, the new filename takes precedence.
 
@@ -491,7 +507,7 @@ The runner explicitly reports policy continuity in result details:
 
 Treat project-local agent prompts like executable project configuration: only enable them in trusted repositories. Stateful project agents require Pi's project trust; interactive use also keeps confirmation enabled by default.
 
-Stateful records are stored as versioned mode-0600 JSON under `~/.pi/agent/pi-subagents-state/` (or the configured Pi agent directory). Records contain sanitized logical history, never process IDs or credentials. Corrupt or unsupported state is quarantined, restored agents are always inert `idle` records, and no prior side effect is automatically resumed. Retention and count limits are configurable. Downgrading is safe: older extension versions ignore this separate state directory; use `/subagents:agents clear` before downgrade if the histories should be removed.
+Stateful records are stored as versioned mode-0600 JSON under `~/.pi/agent/pi-subagents-state/` (or the configured Pi agent directory). Records contain sanitized logical history, never process IDs or credentials. Corrupt or unsupported state is quarantined, restored agents are always inert `idle` records, and no prior side effect is automatically resumed. Retention and count limits are configurable. Downgrading is safe: older extension versions ignore this separate state directory; clear **Current agents** from `/subagents` before downgrade if the histories should be removed.
 
 ## 🗂️ Package layout
 
@@ -509,7 +525,7 @@ extensions/pi-subagents/
 └── package.json
 ```
 
-`index.ts` is the Pi entrypoint and forwards to `subagents.ts`; the other source modules are internal. The package exposes its Pi extension through `package.json`:
+`index.ts` is the Pi entrypoint and forwards to `subagents.ts`; the other source modules are internal. Workflow settings remain backward compatible: older files without `blocking.enabled` keep the five-tool default, existing `stateful.enabled: false` files remain blocking-only, and older package releases ignore the new `blocking` object. The package exposes its Pi extension through `package.json`:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.31.0",
+	"version": "0.33.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/agents.ts

@@ -41,6 +41,10 @@ export type SubagentTransportKind = "subprocess" | "in-process";
 
 export type CompletionDelivery = "next-turn" | "auto-resume";
 
+export interface SubagentBlockingSettings {
+	enabled?: boolean;
+}
+
 export interface SubagentRuntimeSettings {
 	enabled?: boolean;
 	transport?: SubagentTransportKind;
@@ -58,6 +62,7 @@ export interface SubagentRuntimeSettings {
 
 export interface SubagentSettings {
 	agents?: Record<string, SubagentAgentConfig>;
+	blocking?: SubagentBlockingSettings;
 	stateful?: SubagentRuntimeSettings;
 }
 
@@ -242,7 +247,7 @@ export function discoverAgents(
 		for (const agent of projectAgents) agentMap.set(agent.name, agent);
 	}
 
-	// Apply user-configured overrides (from /subagents:config) on top of
+	// Apply user-configured overrides (from /subagents → Agent tool settings) on top of
 	// the final resolved agent map, regardless of agent source.
 	for (const [name, override] of Object.entries(config?.agents ?? {})) {
 		const agent = agentMap.get(name);

package/src/config-ui.ts

@@ -16,23 +16,27 @@ import {
 import { type CompletionDelivery, discoverAgents } from "./agents.js";
 import type { ManagedAgent } from "./registry.js";
 import {
+	type DelegationWorkflow,
 	hasOwn,
 	inspectCompletionDeliverySettings,
+	inspectDelegationWorkflowSettings,
 	readSubagentSettings,
 	sameToolSet,
 	uniqueToolNames,
 	updateAgentToolsSetting,
 	updateCompletionDeliverySetting,
+	updateDelegationWorkflowSetting,
 } from "./settings.js";
 import { formatStatefulAgentLine, type StatefulSubagentRuntimeStatus } from "./stateful.js";
 
 const SUBCOMMANDS: AutocompleteItem[] = [
-	{ value: "settings", label: "settings", description: "Configure completion delivery" },
+	{ value: "settings", label: "settings", description: "Configure completion behavior" },
 	{ value: "status", label: "status", description: "Show effective subagent settings" },
 	{ value: "help", label: "help", description: "Show subagent settings help" },
 ];
 
 export interface SubagentSettingsRuntime {
+	getBlockingEnabled(): boolean;
 	getCompletionDelivery(): CompletionDelivery;
 	setCompletionDelivery(value: CompletionDelivery): void;
 	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
@@ -102,17 +106,11 @@ export class ToolToggleList {
 
 export function registerSubagentConfigCommand(pi: ExtensionAPI, runtime: SubagentSettingsRuntime) {
 	registerSubagentPrimaryCommand(pi, runtime);
-	pi.registerCommand("subagents:config", {
-		description: "Configure user tool settings for each subagent",
-		handler: async (_args, ctx) => {
-			await showSubagentToolSettings(pi, ctx);
-		},
-	});
 }
 
 async function showSubagentToolSettings(pi: ExtensionAPI, ctx: ExtensionCommandContext) {
 	if (ctx.mode !== "tui") {
-		if (ctx.hasUI) ctx.ui.notify("/subagents:config requires TUI mode", "info");
+		if (ctx.hasUI) ctx.ui.notify("Agent tool settings require TUI mode", "info");
 		return;
 	}
 
@@ -292,7 +290,8 @@ async function showSubagentToolSettings(pi: ExtensionAPI, ctx: ExtensionCommandC
 	}
 }
 
-type ManagerAction = "settings" | "agent-tools" | "agents" | "status" | "help";
+type ManagerAction = "workflow" | "agents" | "completion" | "advanced" | "help";
+type AdvancedAction = "agent-tools" | "status" | "back";
 type AgentManagerAction = "back" | "clear";
 
 function registerSubagentPrimaryCommand(pi: ExtensionAPI, runtime: SubagentSettingsRuntime) {
@@ -317,7 +316,7 @@ function registerSubagentPrimaryCommand(pi: ExtensionAPI, runtime: SubagentSetti
 					showSubagentStatus(ctx, runtime);
 					return;
 				case "help":
-					showSubagentHelp(ctx, runtime);
+					showSubagentHelp(ctx);
 					return;
 				default:
 					if (ctx.mode === "tui" || ctx.hasUI) {
@@ -341,20 +340,20 @@ async function showSubagentManager(
 		const action = await selectManagerAction(ctx, runtime);
 		if (!action) return;
 		switch (action) {
-			case "settings":
-				await showSubagentSettings(ctx, runtime);
-				break;
-			case "agent-tools":
-				await showSubagentToolSettings(pi, ctx);
+			case "workflow":
+				if (await showDelegationWorkflow(ctx, runtime)) return;
 				break;
 			case "agents":
 				await showCurrentSessionAgents(ctx, runtime);
 				break;
-			case "status":
-				showSubagentStatus(ctx, runtime);
+			case "completion":
+				await showSubagentSettings(ctx, runtime);
+				break;
+			case "advanced":
+				await showAdvancedSettings(pi, ctx, runtime);
 				break;
 			case "help":
-				showSubagentHelp(ctx, runtime);
+				showSubagentHelp(ctx);
 				break;
 		}
 	}
@@ -365,24 +364,28 @@ async function selectManagerAction(
 	runtime: SubagentSettingsRuntime,
 ): Promise<ManagerAction | null> {
 	const status = runtime.getRuntimeStatus();
-	const settings = inspectCompletionDeliverySettings();
+	const workflow = inspectDelegationWorkflowSettings();
 	const items: SelectItem[] = [
 		{
-			value: "settings",
-			label: "Completion settings",
-			description: "Change user completion delivery for this and future sessions",
-		},
-		{
-			value: "agent-tools",
-			label: "Agent tool settings",
-			description: "Configure persistent per-agent tool allow-lists",
+			value: "workflow",
+			label: "Change delegation",
+			description: "Choose all methods, async only, or blocking only",
 		},
 		{
 			value: "agents",
-			label: "Current-session agents",
+			label: "Current agents",
 			description: `${status.activeAgents} active · ${status.retainedAgents} retained`,
 		},
-		{ value: "status", label: "Status", description: "Show effective runtime and settings state" },
+		{
+			value: "completion",
+			label: "Completion behavior",
+			description: "Choose whether async completion waits or resumes automatically",
+		},
+		{
+			value: "advanced",
+			label: "Advanced settings",
+			description: "Agent permissions, runtime details, and settings path",
+		},
 		{ value: "help", label: "Help", description: "Show commands and manual configuration" },
 	];
 	return ctx.ui.custom<ManagerAction | null>((tui, theme, _keybindings, done) => {
@@ -390,7 +393,9 @@ async function selectManagerAction(
 		container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
 		container.addChild(new Text(theme.fg("accent", theme.bold("Subagents")), 1, 0));
 		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("muted", formatManagerSummary(status, settings)), 1, 0));
+		container.addChild(
+			new Text(theme.fg("muted", formatManagerSummary(runtime, status, workflow)), 1, 0),
+		);
 		container.addChild(new Spacer(1));
 		const selectList = new SelectList(items, Math.min(items.length + 2, 15), {
 			selectedPrefix: (text: string) => theme.fg("accent", text),
@@ -415,6 +420,257 @@ async function selectManagerAction(
 	});
 }
 
+async function showDelegationWorkflow(
+	ctx: ExtensionCommandContext,
+	runtime: SubagentSettingsRuntime,
+): Promise<boolean> {
+	const snapshot = inspectDelegationWorkflowSettings();
+	if (ctx.mode !== "tui") {
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				`Edit delegation settings manually: ${safeTerminalText(snapshot.path)}`,
+				"info",
+			);
+		}
+		return false;
+	}
+	if (snapshot.error) {
+		ctx.ui.notify(
+			`Delegation settings cannot be edited: ${safeTerminalText(snapshot.error)}. Repair ${safeTerminalText(snapshot.path)} and retry.`,
+			"error",
+		);
+		return false;
+	}
+	const activeWorkflow = currentWorkflow(runtime, runtime.getRuntimeStatus());
+	const choices: SelectItem[] = [
+		{
+			value: "all",
+			label: "All delegation methods",
+			description: "Allow blocking batches and reusable async agents",
+		},
+		{
+			value: "async-only",
+			label: "Async only",
+			description: "Keep the root responsive; remove blocking subagent",
+		},
+		{
+			value: "blocking-only",
+			label: "Blocking only",
+			description: "Keep blocking batches; remove reusable async agents",
+		},
+	];
+	const selected = await ctx.ui.custom<DelegationWorkflow | null>(
+		(tui, theme, _keybindings, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+			container.addChild(new Text(theme.fg("accent", theme.bold("Change Delegation")), 1, 0));
+			container.addChild(
+				new Text(
+					theme.fg(
+						"muted",
+						[
+							`Current: ${workflowLabel(activeWorkflow)}`,
+							...(snapshot.value !== activeWorkflow
+								? [`Configured after reload: ${workflowLabel(snapshot.value)}`]
+								: []),
+						].join("\n"),
+					),
+					1,
+					0,
+				),
+			);
+			container.addChild(new Spacer(1));
+			const selectList = new SelectList(choices, Math.min(choices.length + 2, 10), {
+				selectedPrefix: (text: string) => theme.fg("accent", text),
+				selectedText: (text: string) => theme.fg("accent", text),
+				description: (text: string) => theme.fg("muted", text),
+				scrollInfo: (text: string) => theme.fg("dim", text),
+				noMatch: (text: string) => theme.fg("warning", text),
+			});
+			selectList.setSelectedIndex(
+				Math.max(
+					0,
+					choices.findIndex((item) => item.value === snapshot.value),
+				),
+			);
+			selectList.onSelect = (item) => done(item.value as DelegationWorkflow);
+			selectList.onCancel = () => done(null);
+			container.addChild(selectList);
+			container.addChild(new Text(theme.fg("dim", "↑↓ navigate · enter preview · esc back"), 1, 0));
+			container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+			return {
+				render: (width: number) => container.render(width),
+				invalidate: () => container.invalidate(),
+				handleInput(data: string) {
+					selectList.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		},
+	);
+	if (!selected) return false;
+	if (selected === activeWorkflow && selected === snapshot.value) {
+		ctx.ui.notify(`Delegation already uses ${workflowLabel(selected)}.`, "info");
+		return false;
+	}
+	const requiresReload = selected !== activeWorkflow;
+	if (requiresReload && blockReloadWithRetainedAgents(ctx, runtime)) return false;
+
+	const confirmed = await showWorkflowPreview(ctx, activeWorkflow, selected, requiresReload);
+	if (!confirmed) return false;
+	if (requiresReload && blockReloadWithRetainedAgents(ctx, runtime)) return false;
+	try {
+		updateDelegationWorkflowSetting(selected as Exclude<DelegationWorkflow, "disabled">);
+	} catch (error) {
+		ctx.ui.notify(
+			`Delegation settings were not saved: ${formatError(error)}. The current workflow is unchanged.`,
+			"error",
+		);
+		return false;
+	}
+	if (!requiresReload) {
+		ctx.ui.notify(
+			`Saved ${workflowLabel(selected)}. The current tool surface already matches.`,
+			"info",
+		);
+		return false;
+	}
+	ctx.ui.notify(
+		`Saved ${workflowLabel(selected)}. Reloading subagent tools… If the tool surface does not refresh, run /reload.`,
+		"info",
+	);
+	await ctx.reload();
+	return true;
+}
+
+function blockReloadWithRetainedAgents(
+	ctx: ExtensionCommandContext,
+	runtime: SubagentSettingsRuntime,
+): boolean {
+	const status = runtime.getRuntimeStatus();
+	if (status.retainedAgents === 0) return false;
+	ctx.ui.notify(
+		`Cannot reload while ${status.retainedAgents} detached subagent${status.retainedAgents === 1 ? " is" : "s are"} retained (${status.activeAgents} active). Open Current agents and clear them after their work is safe to discard, then change delegation.`,
+		"warning",
+	);
+	return true;
+}
+
+async function showWorkflowPreview(
+	ctx: ExtensionCommandContext,
+	current: DelegationWorkflow,
+	next: DelegationWorkflow,
+	requiresReload: boolean,
+): Promise<boolean> {
+	const workflowChanges = workflowEffects(current, next);
+	const effects = (
+		workflowChanges.length > 0
+			? workflowChanges
+			: ["Keep the current registered tools and cancel the pending workflow change"]
+	)
+		.map((effect) => `- ${effect}`)
+		.join("\n");
+	return ctx.ui.custom<boolean>((tui, theme, _keybindings, done) => {
+		const container = new Container();
+		container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+		container.addChild(new Text(theme.fg("accent", theme.bold("Review Delegation Change")), 1, 0));
+		container.addChild(
+			new Text(
+				theme.fg(
+					"muted",
+					`Current: ${workflowLabel(current)}\nNew: ${workflowLabel(next)}\n\nEffect:\n${effects}\n- ${requiresReload ? "Reload the extension to apply this tool surface" : "No reload is needed because the active tools already match"}`,
+				),
+				1,
+				0,
+			),
+		);
+		container.addChild(new Spacer(1));
+		const actions: SelectItem[] = [
+			{
+				value: "save",
+				label: requiresReload ? "Save and reload" : "Save",
+				description: requiresReload
+					? "Persist and apply this workflow"
+					: "Persist the workflow that is already active",
+			},
+			{ value: "cancel", label: "Cancel", description: "Leave settings and tools unchanged" },
+		];
+		const selectList = new SelectList(actions, 4, {
+			selectedPrefix: (text: string) => theme.fg("accent", text),
+			selectedText: (text: string) => theme.fg("accent", text),
+			description: (text: string) => theme.fg("muted", text),
+			scrollInfo: (text: string) => theme.fg("dim", text),
+			noMatch: (text: string) => theme.fg("warning", text),
+		});
+		selectList.onSelect = (item) => done(item.value === "save");
+		selectList.onCancel = () => done(false);
+		container.addChild(selectList);
+		container.addChild(new Text(theme.fg("dim", "↑↓ navigate · enter choose · esc cancel"), 1, 0));
+		container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput(data: string) {
+				selectList.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	});
+}
+
+async function showAdvancedSettings(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	runtime: SubagentSettingsRuntime,
+) {
+	while (true) {
+		const action = await ctx.ui.custom<AdvancedAction | null>((tui, theme, _keybindings, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+			container.addChild(
+				new Text(theme.fg("accent", theme.bold("Advanced Subagent Settings")), 1, 0),
+			);
+			container.addChild(new Spacer(1));
+			const items: SelectItem[] = [
+				{
+					value: "agent-tools",
+					label: "Agent tool permissions",
+					description: "Customize persistent per-agent tool allow-lists",
+				},
+				{
+					value: "status",
+					label: "Runtime details",
+					description: "Show transport, configured source, and settings path",
+				},
+				{ value: "back", label: "Back", description: "Return to the Subagents manager" },
+			];
+			const selectList = new SelectList(items, 5, {
+				selectedPrefix: (text: string) => theme.fg("accent", text),
+				selectedText: (text: string) => theme.fg("accent", text),
+				description: (text: string) => theme.fg("muted", text),
+				scrollInfo: (text: string) => theme.fg("dim", text),
+				noMatch: (text: string) => theme.fg("warning", text),
+			});
+			selectList.onSelect = (item) => done(item.value as AdvancedAction);
+			selectList.onCancel = () => done(null);
+			container.addChild(selectList);
+			container.addChild(new Text(theme.fg("dim", "↑↓ navigate · enter select · esc back"), 1, 0));
+			container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+			return {
+				render: (width: number) => container.render(width),
+				invalidate: () => container.invalidate(),
+				handleInput(data: string) {
+					selectList.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		});
+		if (!action || action === "back") return;
+		if (action === "agent-tools") await showSubagentToolSettings(pi, ctx);
+		else showSubagentStatus(ctx, runtime);
+	}
+}
+
 async function showCurrentSessionAgents(
 	ctx: ExtensionCommandContext,
 	runtime: SubagentSettingsRuntime,
@@ -516,11 +772,11 @@ async function showSubagentSettings(
 		const items: SettingItem[] = [
 			{
 				id: "completionDelivery",
-				label: "Completion delivery",
+				label: "When async work finishes",
 				description:
-					"User setting applied now and to future sessions. next-turn queues completion; auto-resume requests synthesis after settlement.",
-				currentValue,
-				values: ["next-turn", "auto-resume"],
+					"Wait for your next turn, or request one synthesis turn after the root settles.",
+				currentValue: completionLabel(currentValue),
+				values: ["Wait until my next turn", "Resume automatically when finished"],
 			},
 		];
 		const container = new Container();
@@ -541,17 +797,15 @@ async function showSubagentSettings(
 			(id, newValue) => {
 				if (id !== "completionDelivery") return;
 				const previous = currentValue;
-				const next = newValue as CompletionDelivery;
+				const next: CompletionDelivery =
+					newValue === "Resume automatically when finished" ? "auto-resume" : "next-turn";
 				try {
 					updateCompletionDeliverySetting(next);
 					runtime.setCompletionDelivery(next);
 					currentValue = next;
-					ctx.ui.notify(
-						`User completion delivery set to ${next} for this and future sessions.`,
-						"info",
-					);
+					ctx.ui.notify(`Saved and applied: ${completionLabel(next)}.`, "info");
 				} catch (error) {
-					settingsList.updateValue(id, previous);
+					settingsList.updateValue(id, completionLabel(previous));
 					ctx.ui.notify(`Subagent settings were not saved: ${formatError(error)}`, "error");
 				}
 				tui.requestRender();
@@ -574,25 +828,20 @@ function showSubagentStatus(ctx: ExtensionCommandContext, runtime: SubagentSetti
 	if (ctx.mode !== "tui" && !ctx.hasUI) return;
 	const snapshot = inspectCompletionDeliverySettings();
 	ctx.ui.notify(
-		formatStatus(runtime.getRuntimeStatus(), snapshot),
+		formatStatus(runtime.getRuntimeStatus(), snapshot, runtime),
 		snapshot.error ? "warning" : "info",
 	);
 }
 
-function showSubagentHelp(ctx: ExtensionCommandContext, runtime: SubagentSettingsRuntime) {
+function showSubagentHelp(ctx: ExtensionCommandContext) {
 	if (ctx.mode !== "tui" && !ctx.hasUI) return;
 	const snapshot = inspectCompletionDeliverySettings();
-	const runtimeStatus = runtime.getRuntimeStatus();
 	ctx.ui.notify(
 		[
-			"/subagents — open the current-session manager",
-			"/subagents settings — configure user completion delivery",
+			"/subagents — choose delegation workflow, manage current agents, and configure agent tools",
+			"/subagents settings — configure async completion behavior",
 			"/subagents status — show current-session and user-setting values",
 			"/subagents help — show this help",
-			"/subagents:config — compatibility route for per-agent user tool settings",
-			runtimeStatus.enabled
-				? "/subagents:agents list|clear — compatibility route for current-session agents"
-				: "/subagents:agents — unavailable while stateful lifecycle tools are disabled",
 			`User settings: ${safeTerminalText(snapshot.path)}`,
 		].join("\n"),
 		"info",
@@ -600,41 +849,48 @@ function showSubagentHelp(ctx: ExtensionCommandContext, runtime: SubagentSetting
 }
 
 function formatManagerSummary(
+	runtime: SubagentSettingsRuntime,
 	status: StatefulSubagentRuntimeStatus,
-	settings: ReturnType<typeof inspectCompletionDeliverySettings>,
+	configured: ReturnType<typeof inspectDelegationWorkflowSettings>,
 ): string {
+	const current = currentWorkflow(runtime, status);
 	return [
-		"Current session",
-		`Lifecycle: ${status.enabled ? "enabled" : "disabled"}${status.initialized ? " · initialized" : " · not initialized"}`,
-		`Transport: ${status.transport}`,
-		`Completion delivery: ${status.completionDelivery}`,
+		`Delegation: ${workflowLabel(current)}`,
+		`Completion: ${completionLabel(status.completionDelivery)}`,
 		`Agents: ${status.activeAgents} active · ${status.retainedAgents} retained`,
-		"",
-		"User settings",
-		`Completion source: ${settings.source}`,
-		`Path: ${safeTerminalText(settings.path)}`,
-		...(settings.error ? [`Warning: ${safeTerminalText(settings.error)}`] : []),
+		...(configured.value !== current
+			? [`Configured after reload: ${workflowLabel(configured.value)}`]
+			: []),
+		...(configured.error ? ["Settings need repair; open Advanced settings for details."] : []),
 	].join("\n");
 }
 
 function formatStatus(
 	status: StatefulSubagentRuntimeStatus,
 	snapshot: ReturnType<typeof inspectCompletionDeliverySettings>,
+	runtime?: SubagentSettingsRuntime,
 ): string {
+	const configuredWorkflow = inspectDelegationWorkflowSettings();
+	const current = runtime ? currentWorkflow(runtime, status) : configuredWorkflow.value;
 	return [
 		"Current session",
-		`  Lifecycle: ${status.enabled ? "enabled" : "disabled"}`,
-		`  Runtime: ${status.initialized ? "initialized" : "not initialized"}`,
+		`  Delegation: ${workflowLabel(current)}`,
+		`  Async runtime: ${status.initialized ? "initialized" : status.enabled ? "not initialized" : "disabled"}`,
 		`  Transport: ${status.transport}`,
-		`  Completion delivery: ${status.completionDelivery}`,
+		`  Completion: ${completionLabel(status.completionDelivery)}`,
 		`  Agents: ${status.activeAgents} active, ${status.retainedAgents} retained`,
 		"User settings",
+		`  Delegation source: ${configuredWorkflow.source}`,
+		`  Configured delegation: ${workflowLabel(configuredWorkflow.value)}`,
 		`  Completion source: ${snapshot.source}`,
+		`  Configured completion: ${completionLabel(snapshot.value)}`,
 		`  Path: ${safeTerminalText(snapshot.path)}`,
-		`  Configured completion delivery: ${snapshot.value}`,
-		snapshot.error ? `  Warning: ${safeTerminalText(snapshot.error)}` : "  Warning: none",
-		"User settings persist for future sessions; /subagents settings also applies changes now.",
-		"Manual file changes require /reload.",
+		configuredWorkflow.error || snapshot.error
+			? `  Warning: ${safeTerminalText(configuredWorkflow.error ?? snapshot.error ?? "invalid settings")}`
+			: "  Warning: none",
+		configuredWorkflow.value !== current
+			? "Configured delegation differs from this session. Run /reload to apply it."
+			: "Manual file changes require /reload.",
 	].join("\n");
 }
 
@@ -644,6 +900,52 @@ function formatEmptyRuntime(status: StatefulSubagentRuntimeStatus): string {
 	return "No current-session subagents.";
 }
 
+function currentWorkflow(
+	runtime: SubagentSettingsRuntime,
+	status: StatefulSubagentRuntimeStatus,
+): DelegationWorkflow {
+	const blocking = runtime.getBlockingEnabled();
+	if (blocking && status.enabled) return "all";
+	if (status.enabled) return "async-only";
+	if (blocking) return "blocking-only";
+	return "disabled";
+}
+
+function workflowLabel(value: DelegationWorkflow): string {
+	switch (value) {
+		case "all":
+			return "All delegation methods";
+		case "async-only":
+			return "Async only";
+		case "blocking-only":
+			return "Blocking only";
+		case "disabled":
+			return "Delegation disabled";
+	}
+}
+
+function completionLabel(value: CompletionDelivery): string {
+	return value === "auto-resume" ? "Resume automatically when finished" : "Wait until my next turn";
+}
+
+function workflowEffects(current: DelegationWorkflow, next: DelegationWorkflow): string[] {
+	const blockingEnabled = (value: DelegationWorkflow) =>
+		value === "all" || value === "blocking-only";
+	const asyncEnabled = (value: DelegationWorkflow) => value === "all" || value === "async-only";
+	const effects: string[] = [];
+	if (blockingEnabled(current) !== blockingEnabled(next)) {
+		effects.push(blockingEnabled(next) ? "Add blocking `subagent`" : "Remove blocking `subagent`");
+	}
+	if (asyncEnabled(current) !== asyncEnabled(next)) {
+		effects.push(
+			asyncEnabled(next)
+				? "Add reusable async lifecycle tools"
+				: "Remove reusable async lifecycle tools",
+		);
+	}
+	return effects;
+}
+
 function safeTerminalText(value: string): string {
 	// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.
 	return value.replace(/[\u0000-\u001f\u007f-\u009f]/gu, "?");

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)) {
@@ -277,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.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";