@arhen/pi-core-subagent 1.1.23 → 1.2.0

package/README.md

@@ -4,16 +4,27 @@
 [![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)
 
-Minimalist pi extension: **fast in-process subagents** with single / parallel / chain modes, background runs, cancellation, intercom (child↔leader) and an agent↔agent mailbox.
+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**.
 
+One rule underneath everything else:
+
+> **A task is a graph, not a checklist.** Nodes are workers, edges are data dependencies. The edge both gates the dependent *and* hands it the upstream output — so "the coordinator forgot to pass X" stops being a failure mode. Where there are no edges, there is no graph: flat fan-out stays flat.
+
+That is [Graph Protocol](#graph-protocol), applied to the runtime rather than to the prompt.
+
 ![Subagents widget](docs/subagents-widget.png)
 
 *The `subagent` tool call plus the live above-editor widget: per-agent activity, tool counts, turns, token counters and timers.*
 
 ## Design principles
 
+- **The delegation is the graph.** `needs` declares edges; the scheduler runs each wave of ready tasks in parallel and gates the rest. One code path for single, parallel, chain and graph — `chain` is just `needs: [previous]`. ([why](#why-waves-instead-of-more-agents))
+- **Edges carry data, not just order.** An upstream task's output is prepended to its dependents' prompts automatically. The coordinator cannot forget to pass it, because it never passes it.
+- **A bad graph fails before it spawns.** Unknown ids, self-edges and cycles are rejected at call time — never halfway through a run with three children already burning tokens.
+- **Proof is an exit code, never a self-report.** Tasks are asked for a runnable `Verify:` command; the leader checks `git diff --stat`. Agents auditing their own work score ~0. ([why](#why-9-is-a-verification-command-not-a-self-report))
+- **No ceremony without edges.** Six independent reviewers stay six independent reviewers — no waves, no gates, no graph vocabulary imposed on flat work.
 - **No agent files, no discovery.** The leader defines every subagent inline per call — name, system prompt, toolset. Nothing is read from or written to disk.
 - **Two toolsets only.** Read-only (`read, grep, find, ls` — default) or write (`read, grep, find, ls, bash, edit, write` — `write: true`). No per-agent tool config surface.
 - **In-process** — children are `AgentSession`s in the same runtime. No process spawn, no context bleed.
@@ -64,6 +75,38 @@ Chain — `{previous}` is replaced with the prior agent's output:
 }
 ```
 
+## Graph mode — `needs`
+
+`parallel` runs everything at once; `chain` runs everything one at a time. Most real work is neither. Give a task an `id` and list the ids it `needs`:
+
+```json
+{
+  "tasks": [
+    { "id": "api", "agent": "api-mapper", "task": "Map every route in src/api/" },
+    { "id": "db",  "agent": "db-mapper",  "task": "Map the schema in src/db/" },
+    { "id": "doc", "agent": "writer", "needs": ["api", "db"], "write": true,
+      "task": "Write ARCHITECTURE.md from the maps above. Verify: test -s ARCHITECTURE.md" }
+  ]
+}
+```
+
+```
+wave 1: api ∥ db     →  gate  →  wave 2: doc
+```
+
+What the edge does:
+
+- **Gates** — `doc` starts only after both `api` and `db` finish.
+- **Carries** — `api`'s and `db`'s outputs are prepended to `doc`'s prompt as `## Output of api` / `## Output of db`. You do not pass them yourself, and you cannot forget to.
+- **Skips on breakage** — if an upstream fails or is aborted, dependents are marked aborted instead of running against a prompt with a hole in it.
+
+Rules:
+
+- Tasks with no unmet `needs` run together, throttled by `concurrency`.
+- Unknown ids, self-edges and cycles are rejected **before any child spawns**.
+- `chain` is exactly `needs: [previous]` — same scheduler, kept for convenience. `{previous}` still expands.
+- Zero `needs` anywhere = plain parallel. No ceremony added to flat fan-out.
+
 Background + intercom:
 
 ```json
@@ -80,7 +123,7 @@ Background + intercom:
 
 | Tool | Purpose |
 |---|---|
-| `subagent` | single / `tasks` (parallel) / `chain` (`{previous}`); `background:true` fire-and-forget; `allowIntercom:true` enables child talk tools; `notifyPerTask: true` wakes you as each task completes (default off) |
+| `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 (default off) |
 | `subagent_status` | live per-task snapshot (non-blocking) |
 | `subagent_result` | full output of a run or one task |
 | `await_subagent` | block until a run finishes (optional `timeoutMs`) |
@@ -89,7 +132,7 @@ Background + intercom:
 
 ### 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`. 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: `background`, `notifyPerTask`, `allowIntercom`, `concurrency`.
 
 ### Child talk tools (when `allowIntercom: true`)
 
@@ -115,12 +158,61 @@ Read-only pane over the session's subagents:
 - Background completion: 3-line notice. Full text only via `subagent_result`.
 - Children: isolated sessions; talk tools injected only when `allowIntercom`; each child's prompt states its own task id and its siblings' so mailbox addressing works. Model resolution: explicit `provider/model-id` or bare id via the pi model registry → the parent's current model → settings default. Thinking levels validated against the resolved model's `thinkingLevelMap`.
 
+## What this is built on
+
+### Graph Protocol
+<a id="graph-protocol"></a>
+
+`needs` is an implementation of [Graph Protocol](https://gist.github.com/r17x/90eb2f7be93932b5693753aedb09c01a) — a delegation discipline that treats a task as a graph (`Delegation<A, E, R>`) rather than a checklist. Its ten sections map onto this extension as follows:
+
+| § | Protocol | Here |
+|---|---|---|
+| §1 | nodes, domains, edges | one `agent` owns one task; `needs` are the edges |
+| §2 | happy path as execution graph, waves + gates | wave scheduler: `ready = tasks whose needs are settled` |
+| §3 | one worker or many | `single` vs `tasks` |
+| §4 | break points: wrong context, **missing input**, misinterpretation | missing input is structurally impossible — the edge carries the output |
+| §5 | R: subgraph, method, **verification command**, WHY | prompt guidelines require a runnable `Verify:` line per task |
+| §6 | structured at the boundary | in: upstream outputs prepended as named blocks. out: prose (see below) |
+| §7 | observe without changing the graph | the widget and `/subagents peek` are read-only |
+| §8 | worker attention acquired and released | spawn → terminal status; aborted upstream releases dependents immediately |
+| §9 | prove it: delegated vs implemented | **deliberately not self-reported** — see below |
+| §10 | prompt = subgraph, return = implemented graph | prompt yes; return kept as prose |
+
+### Why §9 is a verification command, not a self-report
+
+The protocol asks the coordinator to compare the delegated subgraph against the graph the worker says it implemented. We implement the comparison against **the filesystem and the exit code**, not against the worker's account of itself, because self-reports carry close to zero signal about exactly the failure §9 exists to catch:
+
+- Asked to audit its own work against 34 real violations, an agent reported **0** — at 90–100 confidence. A *fresh* instance of the same model shown the same output caught 7 (p = 0.0156). A deterministic checker caught all 34. ([Armalo Labs, 2026](https://www.armalo.ai/labs/research/2026-06-11-zero-bit-self-audit))
+- Across 9,876 τ2-bench and 1,879 AppWorld trajectories, "false success" reached **75.8%** of self-assessing coding-agent failures; adding an LLM judge scored **0.54–0.65 AUROC** (0.5 = coin flip). ([arXiv:2606.09863](https://doi.org/10.48550/arxiv.2606.09863))
+- LLM judges reading agent traces can be flipped by rewriting the trace — the exact surface a self-reported graph exposes. ([arXiv:2601.14691](https://arxiv.org/html/2601.14691))
+
+So §9 in practice is two things you already have:
+
+```sh
+# in the task text — the worker must prove it, not claim it
+Verify: npx tsc --noEmit && bun test
+
+# in the leader, after the run — ground truth, not narrative
+git diff --stat
+```
+
+If files outside a worker's subgraph were touched, the diff says so. A structured return schema would only add a second, less trustworthy witness.
+
+### Why waves instead of "more agents"
+
+Flat fan-out is not free — orchestration cost is `critical path + α × cross-agent communication`, and ignoring the second term is what makes added agents *lose* to a single one:
+
+- Dependency-graph partitioning vs flat file-parallel spawning across 28 real repos: **+14.0% pass rate, 2.10× wall-clock, −35% API cost**, with the largest gains on the most dependency-dense projects. Flat parallel inflated cost 60% for a 1.56× speedup; an agent-team baseline was fastest but scored *below sequential* on code quality. ([arXiv:2606.00953](https://arxiv.org/html/2606.00953v1))
+- Dynamic task graphs across 300 trials: 47.5% of baseline token cost, 79.7% accuracy vs 57.6% for a static graph — and, notably, **static tied dynamic when the structure was genuinely known up front**, which is the case `needs` targets. The "frontier" (ready set) in this scheduler is theirs. ([arXiv:2605.06320](https://arxiv.org/html/2605.06320))
+
+The corollary is in the design principles: when there are no edges, don't draw a graph. Six independent reviewers stay six independent reviewers.
+
 ## Development
 
 ```sh
 bun install        # dev deps (typecheck/test only; runtime uses pi's bundled SDK)
 npx tsc --noEmit
-bun test           # pure-logic smoke tests (mailbox, failure classification, watchdog)
+bun test           # pure-logic tests (wave scheduling, edge payload, mailbox, failure classification, watchdog)
 ```
 
 Runtime state: runs persist to `<parent-session>.subagents.json` sidecar; restored (non-terminal → aborted) on session start.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@arhen/pi-core-subagent",
-  "version": "1.1.23",
+  "version": "1.2.0",
   "type": "module",
-  "description": "pi extension: fast in-process subagents with single/parallel/chain, background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
+  "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",
   "main": "./src/index.ts",
   "files": [
@@ -16,7 +16,10 @@
     "pi-extension",
     "pi-package",
     "subagent",
-    "agent-orchestration"
+    "agent-orchestration",
+    "task-graph",
+    "dag",
+    "graph-protocol"
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.2",

package/src/index.ts

@@ -55,6 +55,8 @@ interface TaskInput {
 	/** Name the leader invents for this subagent (display + mailbox addressing). */
 	agent: string;
 	task: string;
+	/** Task ids this task depends on. The edge carries the upstream output into this prompt. */
+	needs?: string[];
 	/** System prompt the leader writes for this agent. Optional — a minimal default is used. */
 	prompt?: string;
 	/** true = write toolset; false/omitted = read-only toolset. */
@@ -73,6 +75,8 @@ interface TaskSnapshot {
 	task: string;
 	cwd: string;
 	status: TaskStatus;
+	/** Resolved dependency edges (task ids). Empty/absent = wave 1. */
+	needs?: string[];
 	sessionId?: string;
 	sessionFile?: string;
 	model?: string;
@@ -241,10 +245,12 @@ export function colorNums(text: string, theme: Theme): string {
  */
 function themedTaskLine(task: TaskSnapshot, theme: Theme, activity = ""): string {
 	const tail = `${taskStatsWithUsage(task)} · ${taskTimer(task)}`;
+	// Queued task with unmet needs: show the gate it's waiting on instead of empty stats.
+	const gate = task.status === "queued" && task.needs?.length ? `${theme.fg("muted", `↳ waits ${task.needs.join(",")}`)} · ` : "";
 	if (TERMINAL.includes(task.status)) {
 		return theme.fg("dim", `${statusIcon(task.status)} ${task.agent} · ${tail}`);
 	}
-	return `${statusIcon(task.status)} ${task.agent} · ${activity}${colorNums(tail, theme)}`;
+	return `${statusIcon(task.status)} ${task.agent} · ${gate}${activity}${colorNums(tail, theme)}`;
 }
 /**
  * Human-readable activity line: "Read src/index.ts", "Grep wrapSingleLine".
@@ -339,7 +345,9 @@ function makeSummary(run: RunSnapshot): string {
 	const usage = formatUsage(run.aggregateUsage);
 	if (usage) lines.push(`Usage: ${usage}`);
 	for (const task of run.tasks) {
-		lines.push(`\n## ${task.agent} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}`);
+		// Edges are named so the leader can compare what it delegated against what came back.
+		const edge = task.needs?.length ? ` (${task.id}, needs ${task.needs.join(", ")})` : ` (${task.id})`;
+		lines.push(`\n## ${task.agent}${edge} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}`);
 	}
 	// Ceiling on the WHOLE summary — 16 tasks × 24KB would otherwise flood the parent context.
 	return truncateText(lines.join("\n"));
@@ -425,6 +433,62 @@ export function validateThinking(model: Model<Api> | undefined, level: string |
 // Cached catalog removed: agents are defined inline by the leader per call,
 // so there is nothing to inject into the parent context. Zero per-request cost.
 
+/**
+ * Resolve dependency edges (Graph Protocol §2). Returns one id list per task,
+ * in input order. Chain mode is just `needs: [previous]`, so both modes run
+ * through the same wave scheduler.
+ *
+ * Throws on unknown ids, self-edges, and cycles — a bad graph must fail before
+ * any child is spawned, never halfway through a run.
+ */
+export function resolveNeeds(inputs: { id?: string; needs?: string[] }[], mode: RunMode): string[][] {
+	const ids = inputs.map((input, index) => input.id ?? `task_${index + 1}`);
+	const known = new Set(ids);
+	const edges = inputs.map((input, index) => {
+		if (mode === "chain") return index === 0 ? [] : [ids[index - 1] as string];
+		const needs = input.needs ?? [];
+		for (const need of needs) {
+			if (!known.has(need)) throw new Error(`Task ${ids[index]} needs unknown task id: ${need}`);
+			if (need === ids[index]) throw new Error(`Task ${ids[index]} cannot need itself.`);
+		}
+		return [...new Set(needs)];
+	});
+	// Kahn's algorithm: if any task never becomes ready, the remainder is a cycle.
+	const done = new Set<string>();
+	let progress = true;
+	while (progress) {
+		progress = false;
+		for (const [index, id] of ids.entries()) {
+			if (done.has(id)) continue;
+			if ((edges[index] as string[]).every((need) => done.has(need))) {
+				done.add(id);
+				progress = true;
+			}
+		}
+	}
+	if (done.size !== ids.length) {
+		throw new Error(`Cycle in subagent needs: ${ids.filter((id) => !done.has(id)).join(", ")}`);
+	}
+	return edges;
+}
+
+/**
+ * Graph Protocol §6: the edge carries the upstream output, not just ordering.
+ * Upstream results are prepended verbatim; `{previous}` stays supported so old
+ * chain prompts keep working (it expands to the first need's output).
+ */
+export function applyUpstream(task: string, needs: string[], outputs: Map<string, string>): string {
+	if (needs.length === 0) {
+		return task.includes("{previous}")
+			? `${task.replace(/\{previous\}/g, () => "")}\n\n(Note: {previous} was empty — no prior step output existed yet.)`
+			: task;
+	}
+	const first = outputs.get(needs[0] as string) ?? "";
+	const body = task.replace(/\{previous\}/g, () => first); // replacer fn: no $ corruption
+	const blocks = needs.map((need) => `## Output of ${need}\n${outputs.get(need) ?? "(no output)"}`);
+	return `${blocks.join("\n\n")}\n\n---\n\n${body}`;
+}
+
 async function mapWithConcurrency<T>(items: T[], concurrency: number, fn: (item: T, index: number) => Promise<void>): Promise<void> {
 	let next = 0;
 	const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, async () => {
@@ -745,6 +809,9 @@ class SubagentManager {
 		this.updateTask(run, task, {
 			status: "starting",
 			startedAt: Date.now(),
+			// Upstream outputs were spliced in by the scheduler; the snapshot must show
+			// the prompt the child actually receives.
+			task: input.task,
 			model: input.model,
 			thinking,
 			tools,
@@ -927,6 +994,7 @@ class SubagentManager {
 				ids.add(input.id);
 			}
 		}
+		const edges = resolveNeeds(inputs, mode);
 
 		const run: RunSnapshot = {
 			id: newId("run"),
@@ -944,6 +1012,7 @@ class SubagentManager {
 				task: input.task,
 				cwd: input.cwd ?? ctx.cwd,
 				status: "queued" as TaskStatus,
+				needs: edges[index],
 				model: input.model,
 				thinking: input.thinking,
 				tools: input.tools ?? (input.write ? WRITE_TOOLS : READONLY_TOOLS),
@@ -973,33 +1042,44 @@ class SubagentManager {
 		run.startedAt = Date.now();
 		this.updateRun(run, ctx, onUpdate);
 
-		if (run.mode === "chain") {
-			let previous = "";
-			for (let i = 0; i < inputs.length; i++) {
-				const task = run.tasks[i]!;
-				if (TERMINAL.includes(task.status)) continue; // canceled
-				const rawTask = inputs[i]!.task;
-				let next = rawTask.replace(/\{previous\}/g, () => previous); // replacer fn: no $ corruption
-				if (previous === "" && rawTask.includes("{previous}")) {
-					next += "\n\n(Note: {previous} was empty — no prior step output existed yet.)";
-				}
-				const input = { ...inputs[i]!, task: next };
-				task.task = input.task;
-				await this.runChild(run, task, input, ctx, signal, onUpdate);
-				if (run.notifyPerTask && run.background && TERMINAL.includes(task.status)) {
-					this.notifyTask(run, task, task.status as "completed" | "failed" | "aborted");
-				}
-				if (task.status !== "completed") break; // aborted/failed link stops the chain
-				previous = task.finalText ?? "";
-			}
-		} else {
-			await mapWithConcurrency(run.tasks, run.mode === "single" ? 1 : run.concurrency, async (task) => {
+		// One wave scheduler for every mode. A wave is the set of tasks whose needs
+		// are all satisfied; the loop boundary between waves IS the gate. Chain mode
+		// reaches here as needs: [previous], so it needs no special case.
+		const outputs = new Map<string, string>();
+		const settled = new Set<string>();
+		let remaining = run.tasks.filter((t) => !TERMINAL.includes(t.status));
+		for (const task of run.tasks) {
+			if (TERMINAL.includes(task.status)) settled.add(task.id); // canceled before start
+		}
+
+		while (remaining.length > 0) {
+			const ready = remaining.filter((t) => (t.needs ?? []).every((need) => settled.has(need)));
+			// resolveNeeds() rejects cycles up front, so an empty frontier here means every
+			// remaining task is downstream of one that never settled (canceled mid-run).
+			if (ready.length === 0) break;
+
+			await mapWithConcurrency(ready, run.mode === "single" ? 1 : run.concurrency, async (task) => {
 				const index = run.tasks.indexOf(task);
-				await this.runChild(run, task, inputs[index]!, ctx, signal, onUpdate);
+				const input = inputs[index]!;
+				const needs = task.needs ?? [];
+				// An upstream failure means this task's input never existed. Running it anyway
+				// burns a full child session on a prompt with a hole in it.
+				const broken = needs.filter((need) => !outputs.has(need));
+				if (broken.length > 0) {
+					this.updateTask(run, task, { status: "aborted", error: `Skipped: upstream task(s) did not complete: ${broken.join(", ")}`, endedAt: Date.now() }, ctx, onUpdate);
+				} else {
+					await this.runChild(run, task, { ...input, task: applyUpstream(input.task, needs, outputs) }, ctx, signal, onUpdate);
+				}
 				if (run.notifyPerTask && run.background && TERMINAL.includes(task.status)) {
 					this.notifyTask(run, task, task.status as "completed" | "failed" | "aborted");
 				}
 			});
+
+			for (const task of ready) {
+				settled.add(task.id);
+				if (task.status === "completed") outputs.set(task.id, task.finalText ?? "");
+			}
+			remaining = remaining.filter((t) => !settled.has(t.id));
 		}
 
 		const failed = run.tasks.some((t) => t.status === "failed");
@@ -1145,6 +1225,12 @@ const TaskItem = Type.Object({
 	cwd: Type.Optional(Type.String({ description: "Working directory for this task. Default: current project." })),
 	tools: Type.Optional(Type.Array(Type.String(), { description: "Explicit tool allowlist (overrides the toolset)" })),
 	maxRuntimeMs: Type.Optional(Type.Number({ description: "Per-task timeout (ms)" })),
+	needs: Type.Optional(
+		Type.Array(Type.String(), {
+			description:
+				"Task ids this task depends on (requires those tasks to declare id). It starts only after they finish, and their outputs are prepended to its prompt. Tasks with no unmet needs run together as a wave.",
+		}),
+	),
 });
 
 type SubagentParamsShape = {
@@ -1267,12 +1353,14 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool<typeof SubagentParams, RunDetails>({
 		name: "subagent",
 		label: "Subagent",
-		description: "Define and run isolated subagents (own context, own session). You invent the agent: name, optional system prompt, toolset (read-only default, write:true for edits). Modes: single, parallel (tasks), chain ({previous}). background:true fire-and-forgets with completion notice. allowIntercom:true lets children ask you questions and message each other.\n\nExamples (copy these shapes):\nSingle: subagent({ agent: \"reviewer\", prompt: \"You review code for correctness\", task: \"Review src/auth.ts\" })\nParallel: subagent({ tasks: [{ agent: \"mapper\", task: \"Map all API routes\" }, { agent: \"critic\", task: \"Review auth for vulnerabilities\" }] })\nChain: subagent({ chain: [{ agent: \"planner\", task: \"Plan the change\" }, { agent: \"doer\", write: true, task: \"Execute: {previous}\" }] })\nBackground: subagent({ agent: \"auditor\", task: \"Audit deps\", background: true })",
+		description: "Define and run isolated subagents (own context, own session). You invent the agent: name, optional system prompt, toolset (read-only default, write:true for edits). Modes: single, parallel (tasks), chain ({previous}). Tasks with `needs` form a dependency graph: each wave of tasks with satisfied needs runs in parallel, and an upstream task's output is prepended to its dependents' prompts. background:true fire-and-forgets with completion notice. allowIntercom:true lets children ask you questions and message each other.\n\nExamples (copy these shapes):\nSingle: subagent({ agent: \"reviewer\", prompt: \"You review code for correctness\", task: \"Review src/auth.ts\" })\nParallel: subagent({ tasks: [{ agent: \"mapper\", task: \"Map all API routes\" }, { agent: \"critic\", task: \"Review auth for vulnerabilities\" }] })\nGraph: subagent({ 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\" }] })\nChain: subagent({ chain: [{ agent: \"planner\", task: \"Plan the change\" }, { agent: \"doer\", write: true, task: \"Execute: {previous}\" }] })\nBackground: subagent({ agent: \"auditor\", task: \"Audit deps\", background: true })",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
 			"Decompose parallelizable work: if the request has 2+ independent sub-tasks (separate files, separate concerns, independent research/review), spawn N agents with a SINGLE call: subagent({ tasks: [{agent, task}, ...] }). NEVER make multiple parallel subagent calls for parallel work — one call, one run, N tasks.",
 			"If independent sub-tasks are sequential (each builds on the previous one's output), use chain mode with {previous}.",
+			"When some tasks depend on others but not all do, give tasks an `id` and list `needs`. Independent tasks then still run in parallel while dependents wait, and each dependent receives its upstream outputs automatically — do not re-describe them in the prompt.",
+			"Give every task a way to check itself: end the task text with a runnable command, e.g. 'Verify: npx tsc --noEmit && bun test'. A subagent's own claim of success is not evidence.",
 			"Define each subagent yourself: an invented name, a focused system prompt (prompt:), and a toolset — read-only (default) or write (write:true).",
 			"Prefer read-only subagents unless the task explicitly needs edits.",
 			"Use background:true for long-running work; you'll be notified on completion.",
@@ -1294,10 +1382,11 @@ export default function (pi: ExtensionAPI) {
 		},
 		renderCall(args, theme) {
 			// ponytail: args stream in partially, so mode is unknowable until JSON closes. Show "preparing…" instead of a wrong "single ?".
+			const hasEdges = args.tasks?.some((t: any) => t.needs?.length);
 			const mode = args.chain?.length
 				? `chain ${args.chain.length}`
 				: args.tasks?.length
-					? `parallel ${args.tasks.length}`
+					? `${hasEdges ? "graph" : "parallel"} ${args.tasks.length}`
 					: args.agent
 						? `single ${args.agent}`
 						: "preparing…";