@arhen/pi-core-subagent 1.3.4 → 1.3.6

package/README.md

@@ -5,6 +5,15 @@
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://github.com/earendil-works/pi)
 
+## Install
+
+Requires the [pi coding agent](https://github.com/earendil-works/pi) — install it first: `npm install -g @earendil-works/pi-coding-agent`.
+
+```sh
+pi install npm:@arhen/pi-core-subagent
+# or locally: pi install /path/to/pi-subagents
+```
+
 Minimalist pi extension: **fast in-process subagents** with single / parallel / graph modes, background runs, cancellation, intercom (child↔leader) and an agent↔agent mailbox.
 
 Built for one job: delegate work to isolated subagents **without bloating the parent context**.
@@ -72,13 +81,6 @@ flowchart TB
 
 The dotted arrows are the whole point: a child may burn 200k tokens reading files, and the leader receives only its final answer.
 
-## Install
-
-```sh
-pi install npm:@arhen/pi-core-subagent
-# or locally: pi install /path/to/pi-subagents
-```
-
 ## Usage — the leader invents the agents
 
 Define agents inline per call — never creates or reads agent files. Model resolution: explicit `provider/model-id` (or bare id) via the pi model registry → agent-file `model` → the parent's current model → settings default.
@@ -219,14 +221,13 @@ flowchart LR
 
 And the rule that keeps this from becoming ceremony: **zero `needs` anywhere = plain parallel.** No waves, no gates, no graph vocabulary imposed on flat work.
 
-Background + intercom:
+Background (default) + intercom — the run returns a runId immediately; you stay steerable while it works:
 
 ```json
 {
   "agent": "auditor",
   "prompt": "You audit dependencies.",
   "task": "Audit package.json for outdated deps",
-  "background": true,
   "allowIntercom": true
 }
 ```
@@ -235,7 +236,7 @@ Background + intercom:
 
 | Tool | Purpose |
 |---|---|
-| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); `background:true` fire-and-forget; `allowIntercom:true` enables child talk tools; `notifyPerTask: true` wakes you as each task completes (background runs only; default off) |
+| `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_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`) |
@@ -255,6 +256,11 @@ Background + intercom:
 | `send_agent_message` | message to a sibling subagent's mailbox (`to` = its task id, or `"leader"`) |
 | `poll_agent_messages` | drain this subagent's mailbox |
 
+## 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.
+
 ## Peek — `/subagents peek` or `ctrl+shift+a`
 
 Read-only pane over the session's subagents:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.4",
+	"version": "1.3.6",
 	"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/index.ts

@@ -76,14 +76,22 @@ export default function (pi: ExtensionAPI) {
 		);
 	};
 	pi.registerCommand("subagents", {
-		description: "List subagent runs. `/subagents peek` opens the browsable pane.",
+		description: "List subagent runs. `/subagents peek` opens the browsable pane; `/subagents auto-bg on|off` toggles background-by-default.",
 		handler: async (args, ctx) => {
-			if (
-				String(args ?? "")
-					.trim()
-					.toLowerCase() === "peek"
-			)
-				return openPeek(ctx);
+			const arg = String(args ?? "")
+				.trim()
+				.toLowerCase();
+			if (arg === "peek") return openPeek(ctx);
+			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");
@@ -120,7 +128,7 @@ export default function (pi: ExtensionAPI) {
 		// ponytail: this string is billed on every request. One example — the graph one —
 		// covers ids, needs, write and Verify; the simpler shapes are subsets of it.
 		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:true returns immediately; allowIntercom:true lets children talk to you and each other.\n\nsubagent({ tasks: [{ id: "api", agent: "api-mapper", task: "Map API routes" }, { id: "db", agent: "db-mapper", task: "Map DB schema" }, { id: "doc", agent: "writer", needs: ["api", "db"], write: true, task: "Write ARCHITECTURE.md. Verify: test -s ARCHITECTURE.md" }] })',
+			'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.\n\nsubagent({ tasks: [{ id: "api", agent: "api-mapper", task: "Map API routes" }, { id: "db", agent: "db-mapper", task: "Map DB schema" }, { id: "doc", agent: "writer", needs: ["api", "db"], write: true, task: "Write ARCHITECTURE.md. Verify: test -s ARCHITECTURE.md" }] })',
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
@@ -128,13 +136,14 @@ export default function (pi: ExtensionAPI) {
 			"Order comes from `needs`, not from separate calls: give tasks an `id`, list the ids each depends on. Tasks with no unmet needs run in parallel; dependents receive their upstream outputs automatically — do not restate them.",
 			"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.",
-			"Use background:true for long work; allowIntercom:true only when a child may need to ask you something.",
+			"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.",
+			"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) {
+			if ((typed.background ?? manager.autoBgOn) && typed.background !== false) {
 				const details = manager.startInBackground(typed, ctx);
 				return {
 					content: [

package/src/manager.ts

@@ -200,9 +200,30 @@ 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;
+
 	turnActivity = false;
 
-	constructor(private readonly pi: ExtensionAPI) {}
+	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;
+		} catch {
+			/* no config yet — default true */
+		}
+	}
+
+	/** 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 }, null, 2)).catch(() => {});
+		return on;
+	}
+
+	get autoBgOn(): boolean {
+		return this.autoBg;
+	}
 
 	/** Any run still has queued/running tasks? */
 	hasActiveRun(): boolean {
@@ -798,9 +819,9 @@ export class SubagentManager {
 			id: newId("run"),
 			mode,
 			status: "queued",
-			background: Boolean(params.background),
+			background: params.background ?? this.autoBg,
 			allowIntercom: Boolean(params.allowIntercom),
-			notifyPerTask: params.notifyPerTask ?? false,
+			notifyPerTask: params.notifyPerTask ?? true,
 			createdAt: Date.now(),
 			concurrency: Math.max(1, Math.min(params.concurrency ?? DEFAULT_CONCURRENCY, MAX_CONCURRENCY)),
 			tasks: inputs.map((input, index) => ({

package/src/schemas.ts

@@ -55,12 +55,17 @@ export const SubagentParams = Type.Object({
 		}),
 	),
 	background: Type.Optional(
-		Type.Boolean({ description: "Fire-and-forget: return immediately with a runId; you'll be notified on completion" }),
+		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,
+		}),
 	),
 	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 false.",
+				"Wake you (queued follow-up turn) as each task completes — background runs only, since blocking runs can't be woken mid-tool. Default true.",
+			default: true,
 		}),
 	),
 	allowIntercom: Type.Optional(