@ferris1225/pi-subagents 0.5.0 → 0.6.0

package/README-zh.md

@@ -70,7 +70,7 @@ pi 从不把每个 agent 的描述展示给主模型——它只看到 `subagent
 3. **`Use PROACTIVELY when …` 描述** —— 在 Claude Code agent 生态被验证过的触发措辞。
 
 这段指令会引导出一条干净的流程：**`explore` → `worker` → `reviewer`**，独立任务并行扇出，
-以及「信任但需验证」的交接。
+以及「信任但需验证」的交接。由于子代理在后台运行，依赖前序结果的步骤必须等结果送达后再启动。
 
 ## 配置
 
@@ -121,20 +121,25 @@ pi 从不把每个 agent 的描述展示给主模型——它只看到 `subagent
 { "tasks": [ { "agent": "explore", "task": "..." }, { "agent": "explore", "task": "..." } ] }
 ```
 
+所有子代理默认在后台启动。工具会立即结束当前主代理回合，编辑器可直接继续输入，
+无需按 Escape；完成输出会显示出来，并在后续用户请求前加入上下文。启动完成后，
+Escape 只中止前台工作；切换会话、`/reload` 或退出才会清理仍在运行的后台进程。
+
 ## 实时状态与通知
 
 子代理运行期间，编辑器上方的挂件为每个运行显示一行状态（图标、agent、模型、
-token 用量、耗时），其下缩进一行显示它正在做什么：`thinking`、`writing`、
+token 用量、耗时），其下缩进一行显示它正在做什么：`thinking`、`responding`、
 `read src/index.ts`、`bash npm test`……（不会是一坨 JSON 参数）。
+`responding` 表示模型正在流式输出普通文本，**不**表示向文件系统写入。
 
 运行结束（成功**或**失败）时，该行立即从挂件消失，主窗口收到一条通知，
-给出最终摘要（`✓ worker · openai/gpt-5 · ↑12.4k ↓3.1k · 47s`）。工具结果
-本身仍是对话里的持久记录。
+给出最终摘要（`✓ worker · openai/gpt-5 · ↑12.4k ↓3.1k · 47s`）。完成结果消息
+才是对话中持久保留、并会供后续请求使用的记录。
 
 子代理使用配置的思考强度（默认 `--thinking max`）；pi 会按目标模型实际支持
 的级别自适应降级（`max → xhigh → high → … → off`），弱模型也能平稳运行。
 任务内容通过 stdin 传递，只有 agent system prompt 使用短生命周期临时文件。
-子进程输出在内存中流式处理；中止或卡住时会通过 watchdog 清理整个进程树。
+子进程输出在内存中流式处理；默认不设运行时限，只有显式中止时才清理整个进程树。
 
 ## 开发
 

package/README.md

@@ -79,7 +79,8 @@ tool. Three levers fix that:
    Claude Code agent ecosystem.
 
 The directive encourages a clean flow: **`explore` → `worker` → `reviewer`**, parallel
-fan-out for independent tasks, and trust-but-verify handoffs.
+fan-out for independent tasks, and trust-but-verify handoffs. Because runs are backgrounded,
+start dependent steps only after the preceding result is delivered.
 
 ## Configuration
 
@@ -130,24 +131,30 @@ Tool shape:
 { "tasks": [ { "agent": "explore", "task": "..." }, { "agent": "explore", "task": "..." } ] }
 ```
 
+Every run starts in the background. The tool immediately ends the current main-agent turn,
+so the editor is ready for another request without pressing Escape. The completed output is
+shown and added to the context before a later user prompt. Escape only interrupts foreground
+work after launch; session switch, reload, or exit cancels remaining background processes.
+
 ## Live status & notifications
 
 While sub-agents run, a widget above the editor shows one line per run — status
 icon, agent, model, token usage, elapsed time — plus a second, indented line
-with what the agent is doing right now: `thinking`, `writing`,
+with what the agent is doing right now: `thinking`, `responding`,
 `read src/index.ts`, `bash npm test`, … (never a raw JSON args blob).
+`responding` means the model is streaming normal text, **not** writing to the filesystem.
 
 When a run finishes (done **or** failed), its row disappears from the widget and
 the main window gets a notification with the final summary
-(`✓ worker · openai/gpt-5 · ↑12.4k ↓3.1k · 47s`). The tool result itself
-remains the durable record in the conversation.
+(`✓ worker · openai/gpt-5 · ↑12.4k ↓3.1k · 47s`). Its completed result message
+is the durable record in the conversation and context for a later request.
 
 Sub-agents use the configured thinking level (default `--thinking max`);
 pi clamps it adaptively to what the resolved model supports
 (`max → xhigh → high → … → off`), so weaker models degrade gracefully.
 The task is sent through stdin; only the agent system prompt uses a short-lived
-file. Child output is streamed in memory, with a watchdog and process-tree cleanup
-for aborted or stuck runs.
+file. Child output is streamed in memory. Runs have no default time limit;
+explicit cancellation cleans up the process tree.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/background.ts

@@ -0,0 +1,67 @@
+/**
+ * Bounded background task scheduler.
+ *
+ * Tasks get their own AbortSignal rather than inheriting the foreground agent
+ * turn's signal. The owning extension cancels all work only on session teardown.
+ */
+
+export type BackgroundTask = (signal: AbortSignal) => Promise<void>;
+
+interface PendingTask {
+	task: BackgroundTask;
+	controller: AbortController;
+	onCancelled?: () => void;
+}
+
+export class BackgroundTaskQueue {
+	private readonly concurrency: number;
+	private readonly pending: PendingTask[] = [];
+	private readonly active = new Set<AbortController>();
+	private stopped = false;
+
+	constructor(concurrency: number) {
+		this.concurrency = Math.max(1, concurrency);
+	}
+
+	enqueue(task: BackgroundTask, onCancelled?: () => void): AbortController {
+		const controller = new AbortController();
+		if (this.stopped) {
+			controller.abort();
+			onCancelled?.();
+			return controller;
+		}
+
+		this.pending.push({ task, controller, onCancelled });
+		this.drain();
+		return controller;
+	}
+
+	/** Stop queued work and request cancellation for running work. */
+	cancelAll(): void {
+		if (this.stopped) return;
+		this.stopped = true;
+
+		for (const entry of this.pending.splice(0)) {
+			entry.controller.abort();
+			entry.onCancelled?.();
+		}
+		for (const controller of this.active) controller.abort();
+	}
+
+	private drain(): void {
+		while (!this.stopped && this.active.size < this.concurrency) {
+			const entry = this.pending.shift();
+			if (!entry) return;
+			if (entry.controller.signal.aborted) {
+				entry.onCancelled?.();
+				continue;
+			}
+
+			this.active.add(entry.controller);
+			void entry.task(entry.controller.signal).catch(() => undefined).finally(() => {
+				this.active.delete(entry.controller);
+				this.drain();
+			});
+		}
+	}
+}

package/src/index.ts

@@ -13,11 +13,11 @@
  */
 
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { StringEnum } from "@earendil-works/pi-ai";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
+import { BackgroundTaskQueue } from "./background.ts";
 import { getConfigPath, loadConfig, saveConfig } from "./config.ts";
 import { repairUnavailableModelOverrides } from "./models.ts";
 import { buildDelegationDirective } from "./prompt.ts";
@@ -30,9 +30,7 @@ import {
 	getFinalOutput,
 	getResultOutput,
 	isFailedResult,
-	mapWithConcurrencyLimit,
 	runSingleAgent,
-	type OnUpdateCallback,
 	type SingleResult,
 	type SubagentDetails,
 	type SubagentLiveEvent,
@@ -57,6 +55,32 @@ function emptyUsage(): UsageStats {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 }
 
+function queuedResult(agent: AgentConfig, task: string): SingleResult {
+	return {
+		agent: agent.name,
+		agentSource: agent.source,
+		task,
+		exitCode: -1,
+		messages: [],
+		stderr: "",
+		usage: emptyUsage(),
+		model: agent.model,
+	};
+}
+
+function failedStartResult(agentName: string, task: string, errorMessage: string): SingleResult {
+	return {
+		agent: agentName,
+		agentSource: "unknown",
+		task,
+		exitCode: 1,
+		messages: [],
+		stderr: errorMessage,
+		usage: emptyUsage(),
+		errorMessage,
+	};
+}
+
 function aggregateUsage(results: SingleResult[]): UsageStats {
 	const total = emptyUsage();
 	for (const r of results) {
@@ -88,6 +112,8 @@ function formatUsage(usage: UsageStats): string {
 
 export default function (pi: ExtensionAPI): void {
 	const configPath = getConfigPath(getAgentDir());
+	const backgroundQueue = new BackgroundTaskQueue(MAX_CONCURRENCY);
+	let sessionActive = true;
 
 	// Recursion guard: child sub-agents are leaf processes and cannot delegate again.
 	if (currentSubagentDepth() >= MAX_SUBAGENT_DEPTH) {
@@ -100,6 +126,19 @@ export default function (pi: ExtensionAPI): void {
 		return;
 	}
 
+	pi.registerMessageRenderer("subagent-result", (message, _options, theme) =>
+		new Text(
+			`${theme.fg("toolTitle", theme.bold("subagent result"))}\n${message.content}`,
+			0,
+			0,
+		),
+	);
+
+	pi.on("session_shutdown", () => {
+		sessionActive = false;
+		backgroundQueue.cancelAll();
+	});
+
 	pi.registerTool({
 		name: "subagent",
 		label: "Subagent",
@@ -107,17 +146,18 @@ export default function (pi: ExtensionAPI): void {
 			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
 			"Agents: explore (read-only codebase recon), plan (implementation plan, opt-in), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
 			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
-			"Use it to keep the main conversation clean: delegate the work, then orchestrate and verify the results yourself.",
-			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
+			"It starts agents in the background and immediately returns control to the main window; completed results arrive in a later user prompt.",
+			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output)."
 		].join(" "),
 		promptSnippet:
-			"Delegate discrete tasks to isolated sub-agents: explore (read-only search), worker (implement), reviewer (adversarial pre-commit review); plan is opt-in.",
+			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completed results arrive in a later prompt.",
 		promptGuidelines: [
 			"Use subagent to delegate discrete, self-contained tasks so the main context stays clean; do orchestration and verification yourself.",
 			"Use subagent with agent 'explore' for broad or open-ended code search before large changes.",
 			"Use subagent with agent 'worker' to implement a well-scoped task; it plans internally.",
 			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
-			"Run independent tasks in parallel by passing a tasks array to subagent; keep dependent work sequential.",
+			"subagent launches work in the background and ends the current turn; do not assume a result is available until a later user prompt.",
+			"Run independent tasks in parallel by passing a tasks array to subagent; start dependent work only after its result arrives.",
 		],
 		parameters: SubagentParams,
 
@@ -143,12 +183,13 @@ export default function (pi: ExtensionAPI): void {
 				}
 			}
 
-			// Finished runs leave the widget immediately; the main window gets a
-			// notification instead (the tool result remains the durable record).
+			// Finished runs leave the widget immediately. Their final findings arrive
+			// as a custom message before the next foreground prompt.
 			const finishRun = (runId: number, status: "done" | "failed"): void => {
 				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
 				const run = monitor.removeRun(runId);
 				if (!run) return; // already finished — stay idempotent
+				if (!sessionActive) return;
 				const icon = status === "done" ? "✓" : "✗";
 				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
 			};
@@ -174,7 +215,8 @@ export default function (pi: ExtensionAPI): void {
 						monitor.setActivity(runId, "thinking");
 						break;
 					case "text":
-						monitor.setActivity(runId, "writing");
+						// A text delta is model output, not a filesystem write.
+						monitor.setActivity(runId, "responding");
 						break;
 				}
 			};
@@ -194,8 +236,8 @@ export default function (pi: ExtensionAPI): void {
 			const hasSingle = Boolean(params.agent && params.task);
 
 			const makeDetails =
-				(mode: "single" | "parallel") =>
-				(results: SingleResult[]): SubagentDetails => ({ mode, results });
+				(mode: "single" | "parallel", background = false) =>
+				(results: SingleResult[]): SubagentDetails => ({ mode, results, background });
 
 			const catalog = agents.map((a) => a.name).join(", ") || "none";
 
@@ -211,124 +253,104 @@ export default function (pi: ExtensionAPI): void {
 				};
 			}
 
-			// ---- Parallel mode ----
+			const startBackground = (agentName: string, task: string, cwd?: string): SingleResult => {
+				const agent = agents.find((candidate) => candidate.name === agentName);
+				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
+
+				const pending = queuedResult(agent, task);
+				const runId = monitor.addRun(agent.name, agent.model);
+				const onLive = makeLiveHandler(runId);
+
+				backgroundQueue.enqueue(
+					async (backgroundSignal) => {
+						let result: SingleResult;
+						try {
+							result = await runSingleAgent({
+								defaultCwd: ctx.cwd,
+								agent,
+								agentName,
+								task,
+								cwd,
+								thinkingLevel: config.thinkingLevel,
+								signal: backgroundSignal,
+								onLive,
+								makeDetails: makeDetails("single", true),
+							});
+						} catch (error) {
+							const errorMessage = error instanceof Error ? error.message : String(error);
+							result = {
+								...pending,
+								exitCode: 1,
+								stderr: errorMessage,
+								stopReason: backgroundSignal.aborted ? "aborted" : "error",
+								errorMessage,
+							};
+							finishRun(runId, "failed");
+						}
+
+						if (!sessionActive) return;
+						const status = isFailedResult(result) ? "failed" : "completed";
+						const usage = formatUsage(result.usage);
+						pi.sendMessage(
+							{
+								customType: "subagent-result",
+								content: `### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}\n\n${getResultOutput(result)}`,
+								display: true,
+							},
+							{ deliverAs: "nextTurn" },
+						);
+					},
+					() => finishRun(runId, "failed"),
+				);
+
+				return pending;
+			};
+
+			// Sub-agents intentionally detach from the foreground turn. This makes the
+			// editor available immediately; completed findings arrive before the next prompt.
 			if (params.tasks && params.tasks.length > 0) {
 				if (params.tasks.length > MAX_PARALLEL_TASKS) {
 					return {
 						content: [
 							{ type: "text", text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.` },
 						],
-						details: makeDetails("parallel")([]),
+						details: makeDetails("parallel", true)([]),
 					};
 				}
 
-				const allResults: SingleResult[] = params.tasks.map((t) => ({
-					agent: t.agent,
-					agentSource: "unknown",
-					task: t.task,
-					exitCode: -1,
-					messages: [],
-					stderr: "",
-					usage: emptyUsage(),
-				}));
-
-				const emitParallelUpdate = (): void => {
-					if (!onUpdate) return;
-					const done = allResults.filter((r) => r.exitCode !== -1).length;
-					onUpdate({
-						content: [{ type: "text", text: `Parallel: ${done}/${allResults.length} done...` }],
-						details: makeDetails("parallel")([...allResults]),
-					});
-				};
-
-				const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
-					const resolvedModel = agents.find((a) => a.name === t.agent)?.model;
-					const runId = monitor.addRun(t.agent, resolvedModel);
-					const onLive = makeLiveHandler(runId);
-					const perTaskUpdate: OnUpdateCallback | undefined = onUpdate
-						? (partial) => {
-								const current = partial.details?.results[0];
-								if (current) {
-									allResults[index] = current;
-									emitParallelUpdate();
-								}
-							}
-						: undefined;
-					let result: SingleResult;
-					try {
-						result = await runSingleAgent({
-							defaultCwd: ctx.cwd,
-							agent: agents.find((a) => a.name === t.agent),
-							agentName: t.agent,
-							task: t.task,
-							cwd: t.cwd,
-							thinkingLevel: config.thinkingLevel,
-							signal,
-							onUpdate: perTaskUpdate,
-							onLive,
-							makeDetails: makeDetails("parallel"),
-						});
-					} catch (err) {
-						finishRun(runId, "failed");
-						throw err;
-					}
-					allResults[index] = result;
-					emitParallelUpdate();
-					return result;
-				});
-
-				const successCount = results.filter((r) => !isFailedResult(r)).length;
-				const summaries = results.map((r) => {
-					const output = getResultOutput(r);
-					const status = isFailedResult(r) ? "failed" : "completed";
-					const usage = formatUsage(r.usage);
-					return `### [${r.agent}] ${status}${usage ? ` (${usage})` : ""}\n\n${output}`;
-				});
+				const results = params.tasks.map((task) => startBackground(task.agent, task.task, task.cwd));
+				const started = results.filter((result) => result.exitCode === -1).length;
+				const failures = results.filter((result) => result.exitCode !== -1);
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n---\n\n")}`,
+							text:
+								started > 0
+									? `Started ${started} background subagent${started === 1 ? "" : "s"}. Completed results will be added before a later user prompt.`
+									: failures.map((result) => getResultOutput(result)).join("\n"),
 						},
 					],
-					details: makeDetails("parallel")(results),
+					details: makeDetails("parallel", true)(results),
+					isError: failures.length > 0,
+					terminate: true,
 				};
 			}
 
-			// ---- Single mode ----
-			const resolvedModel = agents.find((a) => a.name === params.agent)?.model;
-			const runId = monitor.addRun(params.agent as string, resolvedModel);
-			const onLive = makeLiveHandler(runId);
-			let result: SingleResult;
-			try {
-				result = await runSingleAgent({
-					defaultCwd: ctx.cwd,
-					agent: agents.find((a) => a.name === params.agent),
-					agentName: params.agent as string,
-					task: params.task as string,
-					cwd: params.cwd,
-					thinkingLevel: config.thinkingLevel,
-					signal,
-					onUpdate,
-					onLive,
-					makeDetails: makeDetails("single"),
-				});
-			} catch (err) {
-				finishRun(runId, "failed");
-				throw err;
-			}
-
-			if (isFailedResult(result)) {
+			const result = startBackground(params.agent as string, params.task as string, params.cwd);
+			if (result.exitCode !== -1) {
 				return {
-					content: [{ type: "text", text: `Agent ${result.agent} ${result.stopReason || "failed"}: ${getResultOutput(result)}` }],
+					content: [{ type: "text", text: getResultOutput(result) }],
 					details: makeDetails("single")([result]),
 					isError: true,
 				};
 			}
 			return {
-				content: [{ type: "text", text: getFinalOutput(result.messages) || "(no output)" }],
-				details: makeDetails("single")([result]),
+				content: [{ type: "text", text: `Started ${result.agent} in the background. Its completed result will be added before a later user prompt.` }],
+				details: makeDetails("single", true)([result]),
+				terminate: true,
 			};
+
 		},
 
 		renderCall(args, theme) {
@@ -356,10 +378,11 @@ export default function (pi: ExtensionAPI): void {
 
 			if (details.mode === "single") {
 				const r = details.results[0];
-				const icon = statusIcon(isFailedResult(r) ? "failed" : "done", theme);
+				const pending = r.exitCode === -1;
+				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
 				const model = r.model ?? "?";
-				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${usage ? ` · ${usage}` : ""}`)}`;
+				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
 				return new Text(line, 0, 0);
 			}
 
@@ -368,10 +391,11 @@ export default function (pi: ExtensionAPI): void {
 				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${details.results.length})`)}`,
 			];
 			for (const r of details.results) {
-				const icon = statusIcon(isFailedResult(r) ? "failed" : "done", theme);
+				const pending = r.exitCode === -1;
+				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
 				const model = r.model ?? "?";
-				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${usage ? ` · ${usage}` : ""}`)}`);
+				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
 			}
 			return new Text(lines.join("\n"), 0, 0);
 		},

package/src/prompt.ts

@@ -37,18 +37,19 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-You have a \`subagent\` tool that runs specialized agents in ISOLATED context windows.
-Delegate discrete, self-contained tasks to it instead of doing everything inline, so the
-main window stays focused on orchestration, synthesis, and verification.
+You have a \`subagent\` tool that starts specialized agents in ISOLATED background processes.
+It immediately ends the current main-agent turn so the user can keep working. Completed
+findings are added before a later user prompt; do not assume a launched result is available
+in the same turn.
 
 Available agents:
 ${catalog}
 
 ${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
-- Default to delegating every discrete task to a sub-agent; do the orchestration and verification yourself in the main window.
+- Default to delegating every discrete task to a sub-agent; use completed findings in a later user turn for orchestration and verification.
 - Only handle inline: pure Q&A, a single trivial edit/lookup, or when the user explicitly says to do it directly. When in doubt, delegate.
 - For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
-${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Keep dependent work sequential (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
+${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
 - Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool.
 - Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
 

package/src/spawn.ts

@@ -27,8 +27,8 @@ export const SUBAGENT_THINKING_LEVEL: ThinkingLevel = DEFAULT_THINKING_LEVEL;
 /** Child processes are leaf agents: they never receive the subagent tool. */
 export const MAX_SUBAGENT_DEPTH = 1;
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
-/** Absolute limit so a child that stops emitting events cannot hang the parent forever. */
-export const SUBAGENT_TIMEOUT_MS = 10 * 60 * 1000;
+/** No default deadline: sub-agents may run until completion or explicit cancellation. */
+export const SUBAGENT_TIMEOUT_MS = 0;
 export const SUBAGENT_KILL_GRACE_MS = 5_000;
 
 export interface UsageStats {
@@ -57,6 +57,8 @@ export interface SingleResult {
 export interface SubagentDetails {
 	mode: "single" | "parallel";
 	results: SingleResult[];
+	/** The tool returned immediately while the child process continues in the background. */
+	background?: boolean;
 }
 
 export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
@@ -179,7 +181,7 @@ export interface RunSingleOptions {
 	cwd?: string;
 	/** Thinking level passed to the child pi process. */
 	thinkingLevel?: ThinkingLevel;
-	/** Override the watchdog timeout; intended for tests and controlled callers. */
+	/** Optional timeout; zero (the default) disables it. Intended for tests and controlled callers. */
 	timeoutMs?: number;
 	signal?: AbortSignal;
 	onUpdate?: OnUpdateCallback;