pi-subagents 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-02-23
+
+### Added
+- **Background mode toggle in clarify TUI**: Press `b` to toggle background/async execution for any mode (single, parallel, chain). Shows `[b]g:ON` in footer when enabled. Previously async execution required programmatic `clarify: false, async: true` — now users can interactively choose background mode after previewing/editing parameters.
+- **`--bg` flag for slash commands**: `/run scout "task" --bg`, `/chain scout "task" -> planner --bg`, `/parallel scout "a" -> scout "b" --bg` now run in background without needing the TUI.
+
+### Fixed
+- Task edits in clarify TUI were lost when launching in background mode if no other behavior (model, output, reads) was modified. The async handoff now always applies the edited template.
+
 ## [0.10.0] - 2026-02-23
 
 ### Added

package/README.md

@@ -162,6 +162,18 @@ Append `[key=value,...]` to any agent name to override its defaults:
 
 Set `output=false`, `reads=false`, or `skills=false` to explicitly disable.
 
+### Background Execution
+
+Add `--bg` at the end of any slash command to run in the background:
+
+```
+/run scout "full security audit of the codebase" --bg
+/chain scout "analyze auth system" -> planner "design refactor plan" -> worker --bg
+/parallel scout "scan frontend" -> scout "scan backend" -> scout "scan infra" --bg
+```
+
+Background tasks run asynchronously and notify you when complete. Check status with `subagent_status`.
+
 ## Agents Manager
 
 Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay — a TUI for browsing, viewing, editing, creating, and launching agents and chains.
@@ -271,9 +283,9 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 |------|---------------|-------|
 | Single | Yes | `{ agent, task }` - agents with `output` write to temp dir |
 | Chain | Yes | `{ chain: [{agent, task}...] }` with `{task}`, `{previous}`, `{chain_dir}` variables |
-| Parallel | Sync only | `{ tasks: [{agent, task}...] }` - auto-downgrades if async requested |
+| Parallel | Yes | `{ tasks: [{agent, task}...] }` - via TUI toggle or converted to chain for async |
 
-Chain defaults to sync with TUI clarification. Use `clarify: false` to enable async. Chains with parallel steps (`{ parallel: [...] }`) are fully supported in async mode — parallel tasks run concurrently with configurable `concurrency` and `failFast` options.
+All modes support background/async execution. For programmatic async, use `clarify: false, async: true`. For interactive async, use `clarify: true` and press `b` in the TUI to toggle background mode before running. Chains with parallel steps (`{ parallel: [...] }`) run concurrently with configurable `concurrency` and `failFast` options.
 
 **Clarify TUI for single/parallel:**
 
@@ -290,13 +302,14 @@ Single and parallel modes also support the clarify TUI for previewing/editing pa
 **Clarification TUI keybindings:**
 
 *Navigation mode:*
-- `Enter` - Run
+- `Enter` - Run (foreground) or launch in background if `b` is toggled on
 - `Esc` - Cancel
 - `↑↓` - Navigate between steps/tasks (parallel, chain)
 - `e` - Edit task/template (all modes)
 - `m` - Select model (all modes)
 - `t` - Select thinking level (all modes)
 - `s` - Select skills (all modes)
+- `b` - Toggle background/async execution (all modes) — shows `[b]g:ON` when enabled
 - `w` - Edit writes/output file (single, chain only)
 - `r` - Edit reads list (chain only)
 - `p` - Toggle progress tracking (chain only)

package/chain-clarify.ts

@@ -42,6 +42,8 @@ export interface ChainClarifyResult {
 	templates: string[];
 	/** User-modified behavior overrides per step (undefined = no changes) */
 	behaviorOverrides: (BehaviorOverride | undefined)[];
+	/** User requested background/async execution */
+	runInBackground?: boolean;
 }
 
 type EditMode = "template" | "output" | "reads" | "model" | "thinking" | "skills";
@@ -88,6 +90,8 @@ export class ChainClarifyComponent implements Component {
 	private saveMessageTimer: ReturnType<typeof setTimeout> | null = null;
 	private saveChainNameState: TextEditorState = createEditorState();
 	private savingChain = false;
+	/** Run in background (async) mode */
+	private runInBackground = false;
 
 	constructor(
 		private tui: TUI,
@@ -463,7 +467,7 @@ export class ChainClarifyComponent implements Component {
 			for (let i = 0; i < this.agentConfigs.length; i++) {
 				overrides.push(this.behaviorOverrides.get(i));
 			}
-			this.done({ confirmed: true, templates: this.templates, behaviorOverrides: overrides });
+			this.done({ confirmed: true, templates: this.templates, behaviorOverrides: overrides, runInBackground: this.runInBackground });
 			return;
 		}
 
@@ -539,6 +543,13 @@ export class ChainClarifyComponent implements Component {
 			return;
 		}
 
+		// 'b' to toggle background/async execution (all modes)
+		if (data === "b") {
+			this.runInBackground = !this.runInBackground;
+			this.tui.requestRender();
+			return;
+		}
+
 		if (data === "S") {
 			this.saveOverridesToAgent();
 			return;
@@ -1179,13 +1190,14 @@ export class ChainClarifyComponent implements Component {
 
 	/** Get footer text based on mode */
 	private getFooterText(): string {
+		const bgLabel = this.runInBackground ? '[b]g:ON' : '[b]g';
 		switch (this.mode) {
 			case 'single':
-				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hink [w]rite [s]kill [S]ave ';
+				return ` [Enter] Run • [Esc] Cancel • e m t w s ${bgLabel} S `;
 			case 'parallel':
-				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hink [s]kill [S]ave • ↑↓ Nav ';
+				return ` [Enter] Run • [Esc] Cancel • e m t s ${bgLabel} S • ↑↓ Nav `;
 			case 'chain':
-				return ' [Enter] Run • [Esc] Cancel • e m t w r p s S W • ↑↓ Nav ';
+				return ` [Enter] Run • [Esc] Cancel • e m t w r p s ${bgLabel} S W • ↑↓ Nav `;
 		}
 	}
 

package/chain-execution.ts

@@ -83,6 +83,11 @@ export interface ChainExecutionResult {
 	content: Array<{ type: "text"; text: string }>;
 	details: Details;
 	isError?: boolean;
+	/** User requested async execution via TUI - caller should dispatch to executeAsyncChain */
+	requestedAsync?: {
+		chain: ChainStep[];
+		chainSkills: string[];
+	};
 }
 
 /**
@@ -210,6 +215,31 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				details: { mode: "chain", results: [] },
 			};
 		}
+
+		// User requested background execution - return early so caller can dispatch to async
+		if (result.runInBackground) {
+			removeChainDir(chainDir); // Will be recreated by async runner
+			// Apply TUI edits (templates + behavior overrides) to chain steps
+			const updatedChain = chainSteps.map((step, i) => {
+				if (isParallelStep(step)) return step; // Parallel steps unchanged (TUI skipped for parallel chains)
+				const override = result.behaviorOverrides[i];
+				return {
+					...step,
+					task: result.templates[i] as string, // Always use edited template
+					...(override?.model ? { model: override.model } : {}),
+					...(override?.output !== undefined ? { output: override.output } : {}),
+					...(override?.reads !== undefined ? { reads: override.reads } : {}),
+					...(override?.progress !== undefined ? { progress: override.progress } : {}),
+					...(override?.skills !== undefined ? { skill: override.skills } : {}),
+				};
+			});
+			return {
+				content: [{ type: "text", text: "Launching in background..." }],
+				details: { mode: "chain", results: [] },
+				requestedAsync: { chain: updatedChain as ChainStep[], chainSkills },
+			};
+		}
+
 		// Update templates from TUI result
 		templates = result.templates;
 		// Store behavior overrides from TUI (used below in sequential step execution)

package/index.ts

@@ -451,7 +451,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				const normalized = normalizeSkillInput(params.skill);
 				const chainSkills = normalized === false ? [] : (normalized ?? []);
 				// Use extracted chain execution module
-				return executeChain({
+				const chainResult = await executeChain({
 					chain: params.chain as ChainStep[],
 					task: params.task,
 					agents,
@@ -469,6 +469,33 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 					chainSkills,
 					chainDir: params.chainDir,
 				});
+
+				// User requested async via TUI - dispatch to async executor
+				if (chainResult.requestedAsync) {
+					if (!isAsyncAvailable()) {
+						return {
+							content: [{ type: "text", text: "Background mode requires jiti for TypeScript execution but it could not be found." }],
+							isError: true,
+							details: { mode: "chain" as const, results: [] },
+						};
+					}
+					const id = randomUUID();
+					const asyncCtx = { pi, cwd: ctx.cwd, currentSessionId: currentSessionId! };
+					return executeAsyncChain(id, {
+						chain: chainResult.requestedAsync.chain,
+						agents,
+						ctx: asyncCtx,
+						cwd: params.cwd,
+						maxOutput: params.maxOutput,
+						artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
+						artifactConfig,
+						shareEnabled,
+						sessionRoot,
+						chainSkills: chainResult.requestedAsync.chainSkills,
+					});
+				}
+
+				return chainResult;
 			}
 
 			if (hasTasks && params.tasks) {
@@ -545,6 +572,39 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 						if (override?.model) modelOverrides[i] = override.model;
 						if (override?.skills !== undefined) skillOverrides[i] = override.skills;
 					}
+
+					// User requested background execution
+					if (result.runInBackground) {
+						if (!isAsyncAvailable()) {
+							return {
+								content: [{ type: "text", text: "Background mode requires jiti for TypeScript execution but it could not be found." }],
+								isError: true,
+								details: { mode: "parallel" as const, results: [] },
+							};
+						}
+						const id = randomUUID();
+						const asyncCtx = { pi, cwd: ctx.cwd, currentSessionId: currentSessionId! };
+						// Convert parallel tasks to a chain with a single parallel step
+						const parallelTasks = params.tasks!.map((t, i) => ({
+							agent: t.agent,
+							task: tasks[i],
+							cwd: t.cwd,
+							...(modelOverrides[i] ? { model: modelOverrides[i] } : {}),
+							...(skillOverrides[i] !== undefined ? { skill: skillOverrides[i] } : {}),
+						}));
+						return executeAsyncChain(id, {
+							chain: [{ parallel: parallelTasks }],
+							agents,
+							ctx: asyncCtx,
+							cwd: params.cwd,
+							maxOutput: params.maxOutput,
+							artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
+							artifactConfig,
+							shareEnabled,
+							sessionRoot,
+							chainSkills: [],
+						});
+					}
 				}
 
 				// Execute with overrides (tasks array has same length as params.tasks)
@@ -691,6 +751,33 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 					if (override?.model) modelOverride = override.model;
 					if (override?.output !== undefined) effectiveOutput = override.output;
 					if (override?.skills !== undefined) skillOverride = override.skills;
+
+					// User requested background execution
+					if (result.runInBackground) {
+						if (!isAsyncAvailable()) {
+							return {
+								content: [{ type: "text", text: "Background mode requires jiti for TypeScript execution but it could not be found." }],
+								isError: true,
+								details: { mode: "single" as const, results: [] },
+							};
+						}
+						const id = randomUUID();
+						const asyncCtx = { pi, cwd: ctx.cwd, currentSessionId: currentSessionId! };
+						return executeAsyncSingle(id, {
+							agent: params.agent!,
+							task,
+							agentConfig,
+							ctx: asyncCtx,
+							cwd: params.cwd,
+							maxOutput: params.maxOutput,
+							artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
+							artifactConfig,
+							shareEnabled,
+							sessionRoot,
+							skills: skillOverride === false ? [] : skillOverride,
+							output: effectiveOutput,
+						});
+					}
 				}
 
 				const cleanTask = task;
@@ -921,6 +1008,15 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 		return { name: token.slice(0, bracket), config: parseInlineConfig(token.slice(bracket + 1, end !== -1 ? end : undefined)) };
 	};
 
+	/** Extract --bg flag from end of args, return cleaned args and whether flag was present */
+	const extractBgFlag = (args: string): { args: string; bg: boolean } => {
+		// Only match --bg at the very end to avoid false positives in quoted strings
+		if (args.endsWith(" --bg") || args === "--bg") {
+			return { args: args.slice(0, args.length - (args === "--bg" ? 4 : 5)).trim(), bg: true };
+		}
+		return { args, bg: false };
+	};
+
 	const setupDirectRun = (ctx: ExtensionContext) => {
 		const runId = randomUUID().slice(0, 8);
 		const sessionRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
@@ -980,7 +1076,35 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				...(i === 0 ? { task: result.task } : {}),
 			}));
 			executeChain({ chain, task: result.task, agents, ctx, ...exec, clarify: true })
-				.then((r) => pi.sendUserMessage(r.content[0]?.text || "(no output)"))
+				.then((r) => {
+					// User requested async via TUI - dispatch to async executor
+					if (r.requestedAsync) {
+						if (!isAsyncAvailable()) {
+							pi.sendUserMessage("Background mode requires jiti for TypeScript execution but it could not be found.");
+							return;
+						}
+						const id = randomUUID();
+						const asyncCtx = { pi, cwd: ctx.cwd, currentSessionId: ctx.sessionManager.getSessionId() ?? id };
+						const sessionRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+						executeAsyncChain(id, {
+							chain: r.requestedAsync.chain,
+							agents,
+							ctx: asyncCtx,
+							maxOutput: undefined,
+							artifactsDir: exec.artifactsDir,
+							artifactConfig: exec.artifactConfig,
+							shareEnabled: false,
+							sessionRoot,
+							chainSkills: r.requestedAsync.chainSkills,
+						}).then((asyncResult) => {
+							pi.sendUserMessage(asyncResult.content[0]?.text || "(launched in background)");
+						}).catch((err) => {
+							pi.sendUserMessage(`Async launch failed: ${err instanceof Error ? err.message : String(err)}`);
+						});
+						return;
+					}
+					pi.sendUserMessage(r.content[0]?.text || "(no output)");
+				})
 				.catch((err) => pi.sendUserMessage(`Chain failed: ${err instanceof Error ? err.message : String(err)}`));
 			return;
 		}
@@ -1017,15 +1141,16 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 	});
 
 	pi.registerCommand("run", {
-		description: "Run a subagent directly: /run agent[output=file] task",
+		description: "Run a subagent directly: /run agent[output=file] task [--bg]",
 		getArgumentCompletions: makeAgentCompletions(false),
 		handler: async (args, ctx) => {
-			const input = args.trim();
+			const { args: cleanedArgs, bg } = extractBgFlag(args);
+			const input = cleanedArgs.trim();
 			const firstSpace = input.indexOf(" ");
-			if (firstSpace === -1) { ctx.ui.notify("Usage: /run <agent> <task>", "error"); return; }
+			if (firstSpace === -1) { ctx.ui.notify("Usage: /run <agent> <task> [--bg]", "error"); return; }
 			const { name: agentName, config: inline } = parseAgentToken(input.slice(0, firstSpace));
 			const task = input.slice(firstSpace + 1).trim();
-			if (!task) { ctx.ui.notify("Usage: /run <agent> <task>", "error"); return; }
+			if (!task) { ctx.ui.notify("Usage: /run <agent> <task> [--bg]", "error"); return; }
 
 			const agents = discoverAgents(baseCwd, "both").agents;
 			if (!agents.find((a) => a.name === agentName)) { ctx.ui.notify(`Unknown agent: ${agentName}`, "error"); return; }
@@ -1038,6 +1163,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 			if (inline.output !== undefined) params.output = inline.output;
 			if (inline.skill !== undefined) params.skill = inline.skill;
 			if (inline.model) params.model = inline.model;
+			if (bg) params.async = true;
 			pi.sendUserMessage(`Call the subagent tool with these exact parameters: ${JSON.stringify({ ...params, agentScope: "both" })}`);
 		},
 	});
@@ -1115,10 +1241,11 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 	};
 
 	pi.registerCommand("chain", {
-		description: "Run agents in sequence: /chain scout \"scan code\" -> planner \"analyze auth\"",
+		description: "Run agents in sequence: /chain scout \"task\" -> planner [--bg]",
 		getArgumentCompletions: makeAgentCompletions(true),
 		handler: async (args, ctx) => {
-			const parsed = parseAgentArgs(args, "chain", ctx);
+			const { args: cleanedArgs, bg } = extractBgFlag(args);
+			const parsed = parseAgentArgs(cleanedArgs, "chain", ctx);
 			if (!parsed) return;
 			const chain = parsed.steps.map(({ name, config, task: stepTask }, i) => ({
 				agent: name,
@@ -1129,15 +1256,18 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				...(config.skill !== undefined ? { skill: config.skill } : {}),
 				...(config.progress !== undefined ? { progress: config.progress } : {}),
 			}));
-			pi.sendUserMessage(`Call the subagent tool with these exact parameters: ${JSON.stringify({ chain, task: parsed.task, clarify: false, agentScope: "both" })}`);
+			const params: Record<string, unknown> = { chain, task: parsed.task, clarify: false, agentScope: "both" };
+			if (bg) params.async = true;
+			pi.sendUserMessage(`Call the subagent tool with these exact parameters: ${JSON.stringify(params)}`);
 		},
 	});
 
 	pi.registerCommand("parallel", {
-		description: "Run agents in parallel: /parallel scout \"scan bugs\" -> reviewer \"check style\"",
+		description: "Run agents in parallel: /parallel scout \"task1\" -> reviewer \"task2\" [--bg]",
 		getArgumentCompletions: makeAgentCompletions(true),
 		handler: async (args, ctx) => {
-			const parsed = parseAgentArgs(args, "parallel", ctx);
+			const { args: cleanedArgs, bg } = extractBgFlag(args);
+			const parsed = parseAgentArgs(cleanedArgs, "parallel", ctx);
 			if (!parsed) return;
 			if (parsed.steps.length > MAX_PARALLEL) { ctx.ui.notify(`Max ${MAX_PARALLEL} parallel tasks`, "error"); return; }
 			const tasks = parsed.steps.map(({ name, config, task: stepTask }) => ({
@@ -1149,7 +1279,9 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				...(config.skill !== undefined ? { skill: config.skill } : {}),
 				...(config.progress !== undefined ? { progress: config.progress } : {}),
 			}));
-			pi.sendUserMessage(`Call the subagent tool with these exact parameters: ${JSON.stringify({ chain: [{ parallel: tasks }], task: parsed.task, clarify: false, agentScope: "both" })}`);
+			const params: Record<string, unknown> = { chain: [{ parallel: tasks }], task: parsed.task, clarify: false, agentScope: "both" };
+			if (bg) params.async = true;
+			pi.sendUserMessage(`Call the subagent tool with these exact parameters: ${JSON.stringify(params)}`);
 		},
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",