@arhen/pi-core-subagent 1.3.24 → 1.3.25

package/README.md

@@ -238,7 +238,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 | Tool | Purpose |
 |---|---|
-| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); background is the default (`background:false` for inline result in this turn); `allowIntercom:true` enables child talk tools; `notifyPerTask` (default true) wakes you as each task completes (background runs only) |
+| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); every run is background — returns a runId, completion notifies you; `autoAwait:true` parks the call until the run finishes and returns the final result inline; `allowIntercom:true` enables child talk tools; `notifyPerTask` (default true) wakes you as each task completes |
 | `subagent_status` | live per-task snapshot (non-blocking), including each child's session file path |
 | `subagent_result` | full output of a run or one task |
 | `await_subagent` | block until a run finishes (optional `timeoutMs`) |
@@ -248,7 +248,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 ### Per-task fields
 
-`agent` (name you invent — required), `task` (required), `prompt` (system prompt, optional — minimal default used), `write` (toolset, default read-only), plus optional `model` (`provider/model-id`), `thinking` (validated enum: `off|minimal|low|medium|high|xhigh|max`), `tools` (explicit allowlist), `cwd`, `maxRuntimeMs`, `id`, `needs` (dependency edges — see [Graph mode](#graph-mode--needs)). Top-level only: `background`, `notifyPerTask`, `allowIntercom`, `concurrency`.
+`agent` (name you invent — required), `task` (required), `prompt` (system prompt, optional — minimal default used), `write` (toolset, default read-only), plus optional `model` (`provider/model-id`), `thinking` (validated enum: `off|minimal|low|medium|high|xhigh|max`), `tools` (explicit allowlist), `cwd`, `maxRuntimeMs`, `id`, `needs` (dependency edges — see [Graph mode](#graph-mode--needs)). Top-level only: `autoAwait`, `notifyPerTask`, `allowIntercom`, `concurrency`.
 
 ### Child talk tools (when `allowIntercom: true`)
 
@@ -259,13 +259,12 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 | `send_agent_message` | message to a sibling subagent's mailbox (`to` = its task id, or `"leader"`) |
 | `poll_agent_messages` | drain this subagent's mailbox |
 
-> **Intercom anti-deadlock:** children are told to never block indefinitely on intercom replies — `ask_parent` keeps the stall watchdog fed while awaiting a parent reply (background runs), and sibling polls are capped (~5 tries) with a proceed-with-best-judgment fallback. Gated siblings (later waves) may not be running yet — waiting on them is the top stall cause, so children are instructed not to.
+> **Intercom anti-deadlock:** children are told to never block indefinitely on intercom replies — `ask_parent` keeps the stall watchdog fed while awaiting a parent reply, and sibling polls are capped (~5 tries) with a proceed-with-best-judgment fallback. Gated siblings (later waves) may not be running yet — waiting on them is the top stall cause, so children are instructed not to.
 
 ## Commands
 
 - `/subagents` — list runs; `/subagents peek` (or `ctrl+shift+a`) — browsable pane
-- `/subagents auto-bg on|off` — toggle background-by-default for subagent calls (persists to `~/.pi/agent/subagents-config.json`; default on). `off` makes calls block until the run finishes, result inline in the same turn. Bare `/subagents auto-bg` shows the current state.
-- `/subagents auto-limit on|off` — toggle leader-imposed `maxRuntimeMs` caps (persists to the same config; default on). `off` strips ALL task timeouts: tasks run unlimited until done, stalled, or aborted — only for runs where a hard bound is genuinely required is a cap kept (none, when off). Bare `/subagents auto-limit` shows the current state.
+- `/subagents auto-limit on|off` — toggle leader-imposed `maxRuntimeMs` caps (persists to `~/.pi/agent/subagents-config.json`; default on). `off` strips ALL task timeouts: tasks run unlimited until done, stalled, or aborted — only for runs where a hard bound is genuinely required is a cap kept (none, when off). Bare `/subagents auto-limit` shows the current state.
 
 ## Peek — `/subagents peek` or `ctrl+shift+a`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.24",
+	"version": "1.3.25",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/format.ts

@@ -213,7 +213,7 @@ export function makeSummary(run: RunSnapshot): string {
 	const aborted = run.tasks.filter((t) => t.status === "aborted").length;
 	const done = TERMINAL.includes(run.status) ? "finished" : "running";
 	const lines = [
-		`Run ${run.id}: Subagents ${run.mode}${run.background ? " (background)" : ""} ${done}: ${succeeded}/${run.tasks.length} succeeded${failed ? `, ${failed} failed` : ""}${aborted ? `, ${aborted} aborted` : ""}.`,
+		`Run ${run.id}: Subagents ${run.mode} ${done}: ${succeeded}/${run.tasks.length} succeeded${failed ? `, ${failed} failed` : ""}${aborted ? `, ${aborted} aborted` : ""}.`,
 	];
 	const usage = formatUsage(run.aggregateUsage);
 	if (usage) lines.push(`Usage: ${usage}`);

package/src/index.ts

@@ -16,15 +16,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
-import {
-	compactLines,
-	formatUsage,
-	makeSummary,
-	statusIcon,
-	taskLine,
-	themedTaskLine,
-	truncateText,
-} from "./format.ts";
+import { compactLines, formatUsage, makeSummary, statusIcon, taskLine, truncateText } from "./format.ts";
 import { waveNotation } from "./graph.ts";
 import { cloneRun, SubagentManager } from "./manager.ts";
 import { createPeekPane, type PeekTask } from "./peek.ts";
@@ -77,8 +69,7 @@ export default function (pi: ExtensionAPI) {
 		);
 	};
 	pi.registerCommand("subagents", {
-		description:
-			"List subagent runs. `/subagents peek` opens the browsable pane; `/subagents auto-bg on|off` toggles background-by-default.",
+		description: "List subagent runs. `/subagents peek` opens the browsable pane.",
 		handler: async (args, ctx) => {
 			const arg = String(args ?? "")
 				.trim()
@@ -100,22 +91,6 @@ export default function (pi: ExtensionAPI) {
 				}
 				return;
 			}
-			if (arg === "auto-bg" || arg.startsWith("auto-bg ")) {
-				const value = arg.split(/\s+/)[1];
-				if (value === "on" || value === "off") {
-					const next = manager.setAutoBg(value === "on");
-					ctx.ui.notify(
-						`auto-bg ${next ? "on" : "off"} — subagent calls default to ${next ? "background" : "blocking (inline result)"}.`,
-						"info",
-					);
-				} else {
-					ctx.ui.notify(
-						`auto-bg is ${manager.autoBgOn ? "on" : "off"} — use \`/subagents auto-bg on|off\` to change it.`,
-						"info",
-					);
-				}
-				return;
-			}
 			const runs = manager.listRuns().slice(0, 10);
 			if (runs.length === 0) {
 				ctx.ui.notify("No subagent runs in this session.", "info");
@@ -152,7 +127,7 @@ export default function (pi: ExtensionAPI) {
 		// ponytail: this string is billed on every request. No example block — an example
 		// biases the model toward one shape; guidelines + JSON schema describe all of them.
 		description:
-			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. background is the default (returns a runId immediately; toggle via `/subagents auto-bg off`); set background:false when you need the result inline in this turn. allowIntercom:true lets children talk to you and each other.",
+			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. Every run is background: the call returns a runId immediately and completion notifies you. Set autoAwait:true when you need the result before your next step — the call parks until the run finishes and returns runId + final result in one response. allowIntercom:true lets children talk to you and each other.",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
@@ -161,28 +136,33 @@ export default function (pi: ExtensionAPI) {
 			"Prefer flat `tasks` (plain parallel) unless a real dependency exists — only add `needs` edges when ordering genuinely matters.",
 			"End each task with a runnable check, e.g. 'Verify: npx tsc --noEmit && bun test'. A subagent's claim of success is not evidence.",
 			"Define each agent yourself: invented name, focused system prompt, and read-only (default) or write:true. Prefer read-only.",
-			"Prefer blocking (background:false) whenever the run's result is something you must wait for before your next step — do not default to background for work you depend on inline. When a background run is active, settle its pending results and task dependencies (await_subagent / subagent_result, then continue dependent work) before starting unrelated work.",
-			"For long multi-task runs, don't park the whole turn on one blocking call: start it in the background, then loop await_subagent with short timeoutMs slices (e.g. 20s), processing whichever tasks completed in each slice while the rest keep running. You get incremental results instead of one big blocking wait.",
+			"When you need a run's result before your next step, spawn with autoAwait:true — the call returns runId + final result in one response. Otherwise spawn background and settle results (await_subagent / subagent_result) before continuing dependent work.",
+			"For long multi-task runs, don't autoAwait the whole run: spawn background, then loop await_subagent with short timeoutMs slices (e.g. 20s), processing whichever tasks completed in each slice while the rest keep running. You get incremental results instead of one big wait.",
 			"allowIntercom:true only when a child may need to ask you something.",
 		],
 		parameters: SubagentParams,
 		executionMode: "parallel", // sibling subagent calls run concurrently, not serialized
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const typed = params as SubagentParamsShape;
-			if ((typed.background ?? manager.autoBgOn) && typed.background !== false) {
-				const details = manager.startInBackground(typed, ctx);
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nUse subagent_status / subagent_result / await_subagent / reply_subagent / subagent_cancel to interact.`,
-						},
-					],
-					details,
-				};
+			const details = manager.startInBackground(typed, ctx);
+			if (typed.autoAwait) {
+				// awaitRun wakes on every child→leader message (ask/notify/done) — that's the
+				// slice-loop feature. autoAwait wants the final result: re-park until terminal.
+				let run = details.run;
+				while (!TERMINAL.includes(run.status)) {
+					run = (await manager.awaitRun(details.run.id))?.run ?? run;
+				}
+				return { content: [{ type: "text", text: makeSummary(run) }], details: { run } };
 			}
-			const details = await manager.runBlocking(typed, signal, onUpdate, ctx);
-			return { content: [{ type: "text", text: makeSummary(details.run) }], details };
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nUse subagent_status / subagent_result / await_subagent / reply_subagent / subagent_cancel to interact.`,
+					},
+				],
+				details,
+			};
 		},
 		renderCall(args, theme) {
 			// ponytail: args stream in partially, so mode is unknowable until JSON closes. Show "preparing…" instead of a wrong "single ?".
@@ -194,9 +174,7 @@ export default function (pi: ExtensionAPI) {
 					: args.agent
 						? `single ${args.agent}`
 						: "preparing…";
-			const flags = [(args.background ?? manager.autoBgOn) ? "bg" : "blocking", args.allowIntercom ? "a2a" : ""]
-				.filter(Boolean)
-				.join(" · ");
+			const flags = [args.autoAwait ? "await" : "bg", args.allowIntercom ? "a2a" : ""].filter(Boolean).join(" · ");
 			// Params used, dimmed: model, thinking, toolset, per-task write count.
 			const tasks = args.tasks ?? args.chain ?? [];
 			const writeCount = tasks.filter((t) => t.write).length;
@@ -237,18 +215,12 @@ export default function (pi: ExtensionAPI) {
 			const run = result.details?.run;
 			if (!run) return new Text(result.content[0]?.type === "text" ? result.content[0].text : "", 0, 0);
 			// ponytail: mode/count already shown on the call line above; result header only adds progress + status.
-			const header = `${statusIcon(run.status)} ${theme.fg("accent", `${run.tasks.filter((t) => t.status === "completed").length}/${run.tasks.length} done`)}${run.background ? ` ${theme.fg("muted", "(background)")}` : ""} ${theme.fg("muted", run.status)}`;
+			const header = `${statusIcon(run.status)} ${theme.fg("accent", `${run.tasks.filter((t) => t.status === "completed").length}/${run.tasks.length} done`)} ${theme.fg("muted", run.status)}`;
 			if (!expanded) {
-				// Background: the spawn snapshot is always "0 tools" noise and the footer widget
-				// already shows live per-task state — keep the card to the header only.
-				if (run.background) {
-					const usage = formatUsage(run.aggregateUsage);
-					return new Text(usage ? `${header}\n${theme.fg("dim", usage)}` : header, 0, 0);
-				}
-				const lines = [header, ...run.tasks.map((task) => `  ${themedTaskLine(task, theme)}`)];
+				// Every run is background: the spawn snapshot is always "0 tools" noise and the footer
+				// widget already shows live per-task state — keep the card to the header only.
 				const usage = formatUsage(run.aggregateUsage);
-				if (usage) lines.push(theme.fg("dim", usage));
-				return new Text(lines.join("\n"), 0, 0);
+				return new Text(usage ? `${header}\n${theme.fg("dim", usage)}` : header, 0, 0);
 			}
 			const lines = [header];
 			for (const task of run.tasks) {

package/src/manager.ts

@@ -211,9 +211,6 @@ export class SubagentManager {
 	private widgetRuns: RunSnapshot[] = [];
 	private eventSeq = 0;
 
-	/** Default for `background` when the agent doesn't say — toggle via `/subagents auto-bg on|off`. */
-	private autoBg = true;
-
 	/** When false, strip leader-imposed maxRuntimeMs so tasks run unlimited — toggle via `/subagents auto-limit on|off`. */
 	private autoLimit = true;
 
@@ -222,37 +219,21 @@ export class SubagentManager {
 	constructor(private readonly pi: ExtensionAPI) {
 		try {
 			const cfg = JSON.parse(readFileSync(join(getAgentDir(), "subagents-config.json"), "utf8"));
-			if (typeof cfg.autoBg === "boolean") this.autoBg = cfg.autoBg;
 			if (typeof cfg.autoLimit === "boolean") this.autoLimit = cfg.autoLimit;
 		} catch {
 			/* no config yet — defaults */
 		}
 	}
 
-	/** Flip the background-by-default flag; persists to the agent dir. Returns the new value. */
-	setAutoBg(on: boolean): boolean {
-		this.autoBg = on;
-		void writeFile(
-			join(getAgentDir(), "subagents-config.json"),
-			JSON.stringify({ autoBg: on, autoLimit: this.autoLimit }, null, 2),
-		).catch(() => {});
-		return on;
-	}
-
 	/** Flip the auto-limit flag; persists to the agent dir. Returns the new value. */
 	setAutoLimit(on: boolean): boolean {
 		this.autoLimit = on;
-		void writeFile(
-			join(getAgentDir(), "subagents-config.json"),
-			JSON.stringify({ autoBg: this.autoBg, autoLimit: on }, null, 2),
-		).catch(() => {});
+		void writeFile(join(getAgentDir(), "subagents-config.json"), JSON.stringify({ autoLimit: on }, null, 2)).catch(
+			() => {},
+		);
 		return on;
 	}
 
-	get autoBgOn(): boolean {
-		return this.autoBg;
-	}
-
 	get autoLimitOn(): boolean {
 		return this.autoLimit;
 	}
@@ -392,7 +373,7 @@ export class SubagentManager {
 		if (kind !== "asked" && run.awaited) return; // parent already got the result via await_subagent
 		const body =
 			kind === "asked"
-				? `A background subagent is asking you a question (task ${extra?.taskId}): ${extra?.question ?? ""}\nReply with reply_subagent(runId: "${run.id}", taskId: "${extra?.taskId}", message: ...).`
+				? `A subagent is asking you a question (task ${extra?.taskId}): ${extra?.question ?? ""}\nReply with reply_subagent(runId: "${run.id}", taskId: "${extra?.taskId}", message: ...).`
 				: makeNotice(run, kind);
 		try {
 			this.pi.sendUserMessage(body, { deliverAs: "followUp" });
@@ -509,13 +490,6 @@ export class SubagentManager {
 				if (this.collectParked(run.id, { kind: "ask", taskId: task.id, agent: task.agent, text: question })) {
 					return "Your question was delivered to the parent (they're waiting on this run). Keep working; the answer arrives via the pending reply.";
 				}
-				// A blocking run's parent can't reply mid-tool (followUp only fires after the
-				// tool returns) — only background runs can truly wait for the answer.
-				if (!run.background) {
-					this.updateTask(run, task, { status: "running" }, ctx);
-					this.liveChildren.get(`${run.id}:${task.id}`)?.touchWatchdog();
-					return "Parent cannot answer while this run is blocking. Continue autonomously with your best judgment.";
-				}
 				this.notifyParent(run, "asked", { taskId: task.id, question });
 				// M3: a waiting child is not stalled — keep the watchdog fed until the reply.
 				const keepAlive = setInterval(() => this.liveChildren.get(`${run.id}:${task.id}`)?.touchWatchdog(), 30_000);
@@ -890,7 +864,6 @@ export class SubagentManager {
 			id: newId("run"),
 			mode,
 			status: "queued",
-			background: params.background ?? this.autoBg,
 			allowIntercom: Boolean(params.allowIntercom),
 			notifyPerTask: params.notifyPerTask ?? true,
 			createdAt: Date.now(),
@@ -965,7 +938,7 @@ export class SubagentManager {
 					onUpdate,
 				);
 				if (task.status === "completed") outputs.set(task.id, task.finalText ?? "");
-				if (run.notifyPerTask && run.background && TERMINAL.includes(task.status)) {
+				if (run.notifyPerTask && TERMINAL.includes(task.status)) {
 					this.notifyTask(run, task, task.status as "completed" | "failed" | "aborted");
 				}
 			},
@@ -1012,17 +985,7 @@ export class SubagentManager {
 		this.persist(ctx);
 	}
 
-	async runBlocking(
-		params: SubagentParamsShape,
-		signal: AbortSignal | undefined,
-		onUpdate: ((partial: any) => void) | undefined,
-		ctx: ExtensionContext,
-	): Promise<RunDetails> {
-		const { run, inputs } = this.createRun(params, ctx);
-		await this.executeTasks(run, inputs, ctx, signal, onUpdate);
-		return { run: cloneRun(run) };
-	}
-
+	/** Spawn a run that keeps executing after this call returns. Every run is background. */
 	startInBackground(params: SubagentParamsShape, ctx: ExtensionContext): RunDetails {
 		const { run, inputs } = this.createRun(params, ctx);
 		void this.executeTasks(run, inputs, ctx, undefined, undefined)
@@ -1050,7 +1013,7 @@ export class SubagentManager {
 				this.notifyParent(run, "failed");
 				this.persist(ctx);
 			});
-		return { run: cloneRun(run), background: true };
+		return { run: cloneRun(run) };
 	}
 
 	/** Push a steering message into a live child's session. Returns false when unknown or not running. */

package/src/schemas.ts

@@ -55,17 +55,15 @@ export const SubagentParams = Type.Object({
 				"Per-task timeout, ms. Omit for no cap (default): tasks run until done, stalled, or user-aborted. Do not add arbitrary caps — only set when a hard bound is genuinely required.",
 		}),
 	),
-	background: Type.Optional(
+	autoAwait: Type.Optional(
 		Type.Boolean({
 			description:
-				"Fire-and-forget: return immediately with a runId; you'll be notified on completion. Default true — set false when you need the result inline in this turn.",
-			default: true,
+				"Start the run in the background, then park this tool call until it finishes and return the final result inline (runId + summary in one response). Default false.",
 		}),
 	),
 	notifyPerTask: Type.Optional(
 		Type.Boolean({
-			description:
-				"Wake you (queued follow-up turn) as each task completes — background runs only, since blocking runs can't be woken mid-tool. Default true.",
+			description: "Wake you (queued follow-up turn) as each task completes. Default true.",
 			default: true,
 		}),
 	),

package/src/types.ts

@@ -47,7 +47,6 @@ export interface RunSnapshot {
 	id: string;
 	mode: RunMode;
 	status: RunStatus;
-	background: boolean;
 	allowIntercom: boolean;
 	notifyPerTask: boolean;
 	createdAt: number;
@@ -62,7 +61,6 @@ export interface RunSnapshot {
 
 export interface RunDetails {
 	run: RunSnapshot;
-	background?: boolean;
 }
 
 export interface PendingReply {