@arhen/pi-core-subagent 1.3.28 → 1.3.30

package/README.md

@@ -137,6 +137,18 @@ You are a strict API reviewer. Check auth, rate limiting, and error handling. Ci
 
 Within a directory the file with the highest description-overlap score wins (≥2 shared meaningful tokens). A file `model` is validated against the pi model registry (unknown model fails the task with a catalog message). Files without a `description` frontmatter never match.
 
+## Worktree isolation (write agents)
+
+In a git repo, a `write: true` subagent runs in an **isolated git worktree** at `<repo>/.git/subagents/<run>/<task>` on branch `subagents/<run>/<task>` — the child's cwd is the worktree, so project context (AGENTS.md chain) still loads, `node_modules` is symlinked, and the main tree stays clean while the child works. Parallel write agents can't collide on files.
+
+On completion the extension commits the child's changes (the child is told not to touch branches) and reports **branch + diffstat + changed files** in the result. The leader reviews, then merges:
+
+```
+git merge --no-ff subagents/<run>/<task>
+```
+
+Merged branches + their worktree dirs are cleaned automatically after the run. Failed/canceled tasks keep the branch (partial work survives for manual merging) but drop the worktree dir. Crash leftovers are swept at session start — worktree dirs are removed, branches are kept. Non-git repos fall back to in-place edits.
+
 ## 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`:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.28",
+	"version": "1.3.30",
 	"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

@@ -101,18 +101,7 @@ function themedTaskLine(task: TaskSnapshot, theme: Theme, activity = ""): string
  * unknown/custom tools then read fine too. Add a case only if one reads badly.
  */
 // Order matters: the most specific arg wins (grep's pattern beats its path).
-const ARG_KEYS = [
-	"pattern",
-	"query",
-	"command",
-	"path",
-	"file_path",
-	"filePath",
-	"url",
-	"name",
-	"subject",
-	"task",
-];
+const ARG_KEYS = ["pattern", "query", "command", "path", "file_path", "filePath", "url", "name", "subject", "task"];
 export function describeCall(toolName: string, args: unknown, cwd?: string): string {
 	const verb = toolName.charAt(0).toUpperCase() + toolName.slice(1);
 	const obj = args && typeof args === "object" ? (args as Record<string, unknown>) : undefined;
@@ -221,7 +210,7 @@ export function makeSummary(run: RunSnapshot): string {
 		// 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)")}`}`,
+			`\n## ${task.agent}${edge} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}${task.branch ? `\nBranch: ${task.branch}${task.changedFiles?.length ? ` (${task.changedFiles.length} file(s): ${truncateText(task.changedFiles.join(", "), 160)})` : ""} — merge with \`git merge --no-ff ${task.branch}\` after review.` : ""}`,
 		);
 	}
 	// Ceiling on the WHOLE summary — 16 tasks × 24KB would otherwise flood the parent context.
@@ -229,9 +218,14 @@ export function makeSummary(run: RunSnapshot): string {
 }
 /** Per-task notice: one task's outcome, small. Full output stays out of parent context. */
 export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: string): string {
+	const goal = truncateText(task.task, 120);
 	const detail = task.error ? task.error : truncateText(task.finalText || "(no output)", 200);
+	const wt = task.branch
+		? ` · branch ${task.branch}${task.changedFiles?.length ? `, ${task.changedFiles.length} file(s)` : ""}`
+		: "";
 	return [
-		`Task ${task.agent} (${task.id}) ${kind} in run ${run.id}: ${detail}`,
+		`Task ${task.agent} (${task.id}) ${kind} in run ${run.id}: ${detail}${wt}`,
+		`Goal: ${goal}`,
 		`Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`,
 	].join("\n");
 }

package/src/index.ts

@@ -18,7 +18,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { compactLines, formatUsage, makeSummary, statusIcon, taskLine, truncateText } from "./format.ts";
 import { waveNotation } from "./graph.ts";
-import { cloneRun, SubagentManager } from "./manager.ts";
+import { cloneRun, type ParkedMsg, SubagentManager } from "./manager.ts";
 import { createPeekPane, type PeekTask } from "./peek.ts";
 import {
 	AwaitParam,
@@ -30,6 +30,7 @@ import {
 	type SubagentParamsShape,
 } from "./schemas.ts";
 import { type RunDetails, type RunSnapshot, TERMINAL } from "./types.ts";
+import { cleanupMerged, repoRoot, sweepStale } from "./worktree.ts";
 
 export default function (pi: ExtensionAPI) {
 	const manager = new SubagentManager(pi);
@@ -109,6 +110,24 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		await manager.restoreFromSidecar(ctx);
+		// Crash leftovers: remove stale worktree dirs (branches survive for merging).
+		// Also reap branches the leader merged in a previous session (H1: cleanup can't
+		// fire at run end — the leader merges after).
+		const roots = new Set<string>();
+		const cwdRoot = repoRoot(ctx.cwd);
+		if (cwdRoot) roots.add(cwdRoot);
+		for (const run of manager.listRuns()) {
+			for (const task of run.tasks) {
+				if (task.branch) {
+					const root = repoRoot(task.cwd);
+					if (root) roots.add(root);
+				}
+			}
+		}
+		for (const root of roots) {
+			sweepStale(root);
+			cleanupMerged(root);
+		}
 	});
 	pi.on("session_shutdown", async (_event, ctx) => {
 		if (ctx?.hasUI) {
@@ -127,7 +146,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. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. 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.",
+			"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. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. Write agents run in an isolated git worktree: on completion the result reports the branch + changed files — review, then merge with `git merge --no-ff <branch>` (merged branches are cleaned automatically). 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.",
@@ -135,6 +154,7 @@ 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.",
 			"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.",
+			"For write agents (write:true) in a git repo, the child works in an isolated worktree and its changes are committed to a branch — the result reports branch + changed files. Review the diff, then merge with `git merge --no-ff <branch>`; merged branches are cleaned up automatically. Never leave a worktree branch unmerged at the end of the task.",
 			"Define each agent yourself: invented name, focused system prompt, and read-only (default) or write:true. Prefer read-only. A user agent file (`.agents/agents`, `.claude/agents`, `.pi/agents` — project first, then home) whose `description` matches the spawn goal (name + task) takes over: its body is the system prompt, frontmatter `model`/`tools` apply and are validated against the model registry. Matching is by description, not name — name the agent whatever fits the goal.",
 			"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.",
@@ -146,13 +166,23 @@ export default function (pi: ExtensionAPI) {
 			const typed = params as SubagentParamsShape;
 			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.
+				// awaitRun wakes on every child→leader message (ask/notify/done). Re-park
+				// until terminal — but surface an ask_parent: the child is waiting on the
+				// leader, so break out, reply via reply_subagent, then await again.
 				let run = details.run;
+				let intercom: ParkedMsg[] = [];
 				while (!TERMINAL.includes(run.status)) {
-					run = (await manager.awaitRun(details.run.id))?.run ?? run;
+					const awaited = await manager.awaitRun(details.run.id);
+					if (!awaited) break; // run gone (session shutdown) — stop, no busy-spin
+					if (awaited.run) run = awaited.run;
+					intercom = awaited.intercom;
+					if (intercom.some((m) => m.kind === "ask")) break;
 				}
-				return { content: [{ type: "text", text: makeSummary(run) }], details: { run } };
+				const asked = intercom.find((m) => m.kind === "ask");
+				const text = asked
+					? `${makeSummary(run)}\n\nA child is waiting for your answer (${asked.agent}, ${asked.taskId}): ${asked.text}\nReply with reply_subagent(runId: "${run.id}", taskId: "${asked.taskId}", message: ...), then await_subagent again for the result.`
+					: makeSummary(run);
+				return { content: [{ type: "text", text }], details: { run } };
 			}
 			return {
 				content: [
@@ -270,10 +300,12 @@ export default function (pi: ExtensionAPI) {
 			const tasks = taskId ? run.tasks.filter((t) => t.id === taskId) : run.tasks;
 			const text = [
 				`Run ${run.id} — ${run.status}`,
-				...tasks.map(
-					(t) =>
-						`\n## ${t.agent} ${statusIcon(t.status)}\n${t.error ? `Error: ${t.error}` : t.finalText || "(no output yet)"}\n${formatUsage(t.usage)}`,
-				),
+				...tasks.map((t) => {
+					const wt = t.branch
+						? `\nBranch: ${t.branch}\n${t.diffStat || "(no changes committed)"}\nMerge after review: \`git merge --no-ff ${t.branch}\``
+						: "";
+					return `\n## ${t.agent} ${statusIcon(t.status)}\nGoal: ${truncateText(t.task, 300)}\n${t.error ? `Error: ${t.error}` : t.finalText || "(no output yet)"}${wt}\n${formatUsage(t.usage)}`;
+				}),
 			].join("\n");
 			return { content: [{ type: "text", text: truncateText(text) }], details: { run: cloneRun(run) } };
 		},

package/src/manager.ts

@@ -1,7 +1,7 @@
 /** SubagentManager: run lifecycle, child sessions, intercom, persistence, widget plumbing. */
 import { existsSync, readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 import {
@@ -43,6 +43,17 @@ import {
 	TERMINAL,
 	type UsageStats,
 } from "./types.ts";
+import {
+	branchDiff,
+	cleanupMerged,
+	commitWorktree,
+	createWorktree,
+	removeByBranch,
+	removeWorktree,
+	repoRoot,
+	sweepStale,
+	type Worktree,
+} from "./worktree.ts";
 
 export const DEFAULT_CONCURRENCY = 3;
 export const MAX_CONCURRENCY = 8;
@@ -51,6 +62,8 @@ const DEFAULT_RUNTIME_MS = 0;
 const DEFAULT_STALL_MS = 180_000; // 3 min: long model thinking streams emit no events, but they're not stalled.
 const READONLY_TOOLS = ["read", "grep", "find", "ls"];
 const WRITE_TOOLS = ["read", "grep", "find", "ls", "bash", "edit", "write"];
+/** Task ids become git refs + filesystem paths. */
+const SAFE_TASK_ID = /^[A-Za-z0-9_-]{1,64}$/;
 const WIDGET_THROTTLE_MS = 150;
 
 // ── helpers ──────────────────────────────────────────────────────────────
@@ -638,8 +651,33 @@ export class SubagentManager {
 		const file = resolveAgentFile(input.agent, input.task, task.cwd, getAgentDir());
 		const prompt = file?.body ?? input.prompt?.trim();
 		const thinking = input.thinking;
-		const baseTools = file?.tools ?? input.tools ?? (input.write ? WRITE_TOOLS : READONLY_TOOLS);
+		// Trust boundary: a file can NARROW the toolset (intersect with the leader's
+		// intent) but never widen it — a repo-planted agent file can't grant write.
+		const allowedTools = input.write ? WRITE_TOOLS : READONLY_TOOLS;
+		const fileTools = file?.tools?.filter((t) => allowedTools.includes(t));
+		const baseTools = fileTools?.length ? fileTools : (input.tools ?? allowedTools);
 		const tools = [...baseTools, ...(run.allowIntercom ? CHILD_TALK_TOOLS : [])];
+		// Worktree whenever the child can write — whether the leader said write:true
+		// or a file granted write-capable tools.
+		const canWrite = input.write || (file?.tools?.some((t) => WRITE_TOOLS.includes(t)) ?? false);
+
+		// Write agents run in an isolated git worktree (branch subagents/<run>/<task>);
+		// non-git repos fall back to in-place. The worktree is created BEFORE session
+		// start so the child's cwd + AGENTS.md context chain are the worktree's.
+		let wt: Worktree | undefined;
+		if (canWrite) {
+			try {
+				wt = createWorktree(task.cwd, run.id, task.id);
+			} catch {
+				wt = undefined; // git failure → in-place
+			}
+		}
+		// Map a per-task cwd subpath into the worktree so relative paths stay correct.
+		let childCwd = wt?.path ?? task.cwd;
+		if (wt) {
+			const rel = relative(wt.root, task.cwd);
+			if (rel && !rel.startsWith("..") && rel !== ".") childCwd = join(wt.path, rel);
+		}
 
 		// Model + thinking resolve against the pi model registry; a bad request
 		// fails the TASK with a helpful message, not the whole run.
@@ -689,11 +727,11 @@ export class SubagentManager {
 		const key = `${run.id}:${task.id}`;
 		try {
 			const subagentInstruction = run.allowIntercom
-				? `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer. You MAY use ask_parent only when truly blocked on information only the parent has; notify_parent for one-way updates; send_agent_message/poll_agent_messages to coordinate with siblings. Your mailbox address and siblings: ${task.roster ?? "(none)"}. Use the exact task ids (e.g. task_2) as send_agent_message targets. Siblings run independently and may start late or finish early — never block indefinitely on their replies: poll at most 5 times, then proceed with your best judgment. A gated sibling (marked ↳ waits in the graph) may not be running yet; do not wait for it. Stalled waits get the whole run killed. When your work is done, call notify_parent ONCE with a concise result summary — key findings, verdicts, file:line evidence — so the leader can start consuming your output before the run finishes.`
-				: `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer for the parent agent.`;
+				? `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer. You MAY use ask_parent only when truly blocked on information only the parent has; notify_parent for one-way updates; send_agent_message/poll_agent_messages to coordinate with siblings. Your mailbox address and siblings: ${task.roster ?? "(none)"}. Use the exact task ids (e.g. task_2) as send_agent_message targets. Siblings run independently and may start late or finish early — never block indefinitely on their replies: poll at most 5 times, then proceed with your best judgment. A gated sibling (marked ↳ waits in the graph) may not be running yet; do not wait for it. Stalled waits get the whole run killed. When your work is done, call notify_parent ONCE with a concise result summary — key findings, verdicts, file:line evidence — so the leader can start consuming your output before the run finishes.${wt ? ` You work in an isolated git worktree (branch ${wt.branch}). Never run git commands that switch branches, create branches, or move the worktree (git switch/checkout/branch/worktree). The extension commits your changes when you finish. git status/diff are fine for inspecting your own changes.` : ""}`
+				: `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer for the parent agent.${wt ? ` You work in an isolated git worktree (branch ${wt.branch}). Never run git commands that switch branches, create branches, or move the worktree (git switch/checkout/branch/worktree). The extension commits your changes when you finish. git status/diff are fine for inspecting your own changes.` : ""}`;
 
 			const loader = new DefaultResourceLoader({
-				cwd: task.cwd,
+				cwd: childCwd,
 				agentDir: getAgentDir(),
 				noExtensions: true,
 				appendSystemPromptOverride: (base) => [
@@ -708,11 +746,11 @@ export class SubagentManager {
 				: [];
 
 			const created = await createAgentSession({
-				cwd: task.cwd,
+				cwd: childCwd,
 				agentDir: getAgentDir(),
 				modelRuntime: await createChildModelRuntime(ctx),
 				resourceLoader: loader,
-				sessionManager: SessionManager.create(task.cwd, undefined, { parentSession: getParentSessionFile(ctx) }),
+				sessionManager: SessionManager.create(childCwd, undefined, { parentSession: getParentSessionFile(ctx) }),
 				model,
 				thinkingLevel: thinking as ThinkingLevel | undefined,
 				tools,
@@ -790,6 +828,35 @@ export class SubagentManager {
 				truncateText((child.messages as AssistantMessage[]).map(getFirstText).filter(Boolean).at(-1) || "");
 			if (task.status !== "aborted") {
 				this.updateTask(run, task, { status: "completed", finalText, endedAt: Date.now() }, ctx, onUpdate);
+				if (wt) {
+					// Commit the child's changes, then report the branch + diff so the
+					// leader can review and merge (PR-style). The worktree dir stays
+					// until the branch is merged — cleanupMerged removes both then.
+					// Commit/diff failures must NOT downgrade a completed task or destroy
+					// its work: the error is reported, the status stays completed.
+					try {
+						commitWorktree(wt, `subagent ${task.agent}: ${truncateText(input.task, 60)}`);
+						const { stat, files } = branchDiff(wt);
+						this.updateTask(
+							run,
+							task,
+							{ branch: wt.branch, diffStat: stat || undefined, changedFiles: files.length ? files : undefined },
+							ctx,
+							onUpdate,
+						);
+					} catch (commitErr) {
+						this.updateTask(
+							run,
+							task,
+							{
+								branch: wt.branch,
+								error: `Worktree commit failed (changes remain in ${wt.path}): ${commitErr instanceof Error ? commitErr.message : String(commitErr)}`,
+							},
+							ctx,
+							onUpdate,
+						);
+					}
+				}
 			}
 		} catch (err) {
 			if (timeout) clearTimeout(timeout);
@@ -823,6 +890,17 @@ export class SubagentManager {
 			watchdog.dispose();
 			if (timeout) clearTimeout(timeout);
 			child?.dispose();
+			// Failed/aborted: commit whatever partial work exists FIRST (so the branch
+			// really keeps it), then drop the checkout dir.
+			if (wt && task.status !== "completed") {
+				try {
+					commitWorktree(wt, `subagent ${task.agent} (partial, ${task.status})`);
+				} catch {
+					/* nothing to commit */
+				}
+				this.updateTask(run, task, { branch: wt.branch }, ctx, onUpdate);
+				removeWorktree(wt);
+			}
 		}
 	}
 
@@ -854,13 +932,25 @@ export class SubagentManager {
 				? params.tasks!
 				: params.chain!;
 		if (inputs.length > MAX_TASKS) throw new Error(`Too many subagent tasks (${inputs.length}). Max is ${MAX_TASKS}.`);
+		// Task ids become git refs + filesystem paths — refuse anything unsafe.
+		// Explicit ids are checked against each other; generated ones are checked
+		// against explicit ones so a collision can't silently fall back to in-place.
 		const ids = new Set<string>();
 		for (const input of inputs) {
 			if (input.id !== undefined) {
+				if (!SAFE_TASK_ID.test(input.id)) {
+					throw new Error(`Unsafe task id: "${input.id}" (allowed: letters, digits, _ and - only).`);
+				}
 				if (ids.has(input.id)) throw new Error(`Duplicate task id: ${input.id}`);
 				ids.add(input.id);
 			}
 		}
+		for (let i = 0; i < inputs.length; i++) {
+			const generated = `task_${i + 1}`;
+			if (inputs[i]?.id === undefined && ids.has(generated)) {
+				throw new Error(`Generated task id ${generated} collides with an explicit id — rename the explicit id.`);
+			}
+		}
 		const edges = resolveNeeds(inputs, mode);
 
 		const run: RunSnapshot = {
@@ -924,14 +1014,19 @@ export class SubagentManager {
 		for (const task of run.tasks) {
 			if (TERMINAL.includes(task.status)) settled.add(task.id); // canceled before start
 		}
+		// id → input, immune to filtered-array index drift (C4).
+		const inputById = new Map(run.tasks.map((t, i) => [t.id, inputs[i]]));
 
 		const { skipped } = await runWaveScheduler(
 			run.tasks.filter((t) => !TERMINAL.includes(t.status)),
 			run.mode === "single" ? 1 : run.concurrency,
 			outputs,
 			settled,
-			async (task, index) => {
-				const input = inputs[index]!;
+			async (task) => {
+				// The scheduler passes the index into the FILTERED list — never use it
+				// against the unfiltered inputs. Look the input up by task id instead.
+				const input = inputById.get(task.id);
+				if (!input) return;
 				await this.runChild(
 					run,
 					task,
@@ -986,6 +1081,13 @@ export class SubagentManager {
 		this.runControllers.delete(run.id);
 		for (const task of run.tasks) this.mailboxes.close(`${run.id}:${task.id}`);
 		this.persist(ctx);
+		// Branches merged by the leader since the run ended: drop worktree dir + branch.
+		for (const task of run.tasks) {
+			if (task.branch) {
+				const root = repoRoot(task.cwd);
+				if (root) cleanupMerged(root);
+			}
+		}
 	}
 
 	/** Spawn a run that keeps executing after this call returns. Every run is background. */
@@ -1062,6 +1164,7 @@ export class SubagentManager {
 			task.error = task.error || "Canceled by subagent_cancel"; // never overwrite a real error
 			task.endedAt = Date.now();
 			aborted += 1;
+			if (task.branch) removeByBranch(task.cwd, task.branch); // dir only; branch keeps partial work
 		}
 		run.status = "aborted";
 		run.endedAt = Date.now();

package/src/types.ts

@@ -41,6 +41,10 @@ export interface TaskSnapshot {
 	usage: UsageStats;
 	/** Sibling addresses for intercom tools (send_agent_message targets). */
 	roster?: string;
+	/** Git worktree isolation (write agents): branch + diff of the child's changes. */
+	branch?: string;
+	diffStat?: string;
+	changedFiles?: string[];
 }
 
 export interface RunSnapshot {

package/src/worktree.ts

@@ -0,0 +1,206 @@
+/** Git worktree isolation for write subagents.
+ *  Worktrees live inside `<repo>/.git/subagents/<runId>/<taskId>` so the child's
+ *  ancestor walk still finds the project AGENTS.md chain. node_modules is
+ *  symlinked from the main tree. The extension commits the child's changes on
+ *  completion; the leader reviews and merges the branch manually; merged
+ *  branches are cleaned automatically, crash leftovers are swept at session
+ *  start (dir removed, branch kept — the work survives). */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+
+export interface Worktree {
+	root: string; // repo root (main tree)
+	path: string; // worktree checkout dir
+	branch: string; // subagents/<runId>/<taskId>
+	base: string; // SHA the branch was created from
+}
+
+function git(root: string, args: string[]): string {
+	return execFileSync("git", ["-C", root, ...args], { encoding: "utf8" }).trim();
+}
+
+/** Run git directly inside a directory (worktree ops). */
+function gitIn(dir: string, args: string[]): string {
+	return execFileSync("git", [...args], { cwd: dir, encoding: "utf8" }).trim();
+}
+
+function gitOk(root: string, args: string[]): boolean {
+	try {
+		git(root, args);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Repo root for cwd, or undefined when not a git repo (or cwd doesn't exist). */
+export function repoRoot(cwd: string): string | undefined {
+	if (!existsSync(cwd)) return undefined;
+	try {
+		return git(cwd, ["rev-parse", "--show-toplevel"]);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Create an isolated worktree for a write task. Returns undefined when not a git repo. */
+export function createWorktree(cwd: string, runId: string, taskId: string): Worktree | undefined {
+	const root = repoRoot(cwd);
+	if (!root) return undefined;
+	const path = join(root, ".git", "subagents", runId, taskId);
+	const branch = `subagents/${runId}/${taskId}`;
+	let base: string;
+	try {
+		base = git(root, ["rev-parse", "HEAD"]); // SHA — detached HEAD stays correct
+	} catch {
+		return undefined; // broken repo — fall back to in-place
+	}
+	git(root, ["worktree", "add", "-b", branch, path, "HEAD"]);
+	// Deps follow the child into the worktree; anything else the task needs is
+	// project content already checked out there.
+	const nm = join(root, "node_modules");
+	if (existsSync(nm) && !existsSync(join(path, "node_modules"))) {
+		try {
+			symlinkSync(nm, join(path, "node_modules"));
+		} catch {
+			/* non-fatal: task may not need deps */
+		}
+	}
+	return { root, path, branch, base };
+}
+
+/** Commit all child changes. No-op when the worktree is already clean. */
+export function commitWorktree(wt: Worktree, message: string): void {
+	if (gitIn(wt.path, ["status", "--porcelain"]).length === 0) return;
+	gitIn(wt.path, ["add", "-A", "--", ".", ":(exclude)node_modules"]); // never stage the dep symlink
+	gitIn(wt.path, ["commit", "-m", message, "--no-verify"]);
+}
+
+/** Diffstat + changed files of the branch vs its base SHA. */
+export function branchDiff(wt: Worktree): { stat: string; files: string[] } {
+	const files = git(wt.root, ["diff", "--name-only", `${wt.base}...${wt.branch}`])
+		.split("\n")
+		.filter(Boolean);
+	const stat = git(wt.root, ["diff", "--stat", `${wt.base}...${wt.branch}`]);
+	return { stat, files };
+}
+
+/** Remove the worktree dir. The branch is KEPT (the work survives for merging). */
+export function removeWorktree(wt: Worktree): void {
+	try {
+		git(wt.root, ["worktree", "remove", "--force", wt.path]);
+	} catch {
+		/* already gone */
+	}
+	prune(wt.root);
+}
+
+/** Remove a worktree dir by branch name (cancel paths that didn't keep a Worktree). */
+export function removeByBranch(cwd: string, branch: string): void {
+	const root = repoRoot(cwd);
+	if (!root) return;
+	const path = join(root, ".git", "subagents", branch.slice("subagents/".length));
+	try {
+		git(root, ["worktree", "remove", "--force", path]);
+	} catch {
+		/* already gone */
+	}
+	prune(root);
+}
+
+/** Drop git's stale worktree admin entries (they pile up under .git/worktrees). */
+function prune(root: string): void {
+	try {
+		git(root, ["worktree", "prune"]);
+	} catch {
+		/* ignore */
+	}
+}
+
+/**
+ * Delete branch + worktree for branches already merged into `target`.
+ * SAFETY: branches checked out in a LIVE worktree (concurrent run) are skipped —
+ * their tip equals the base until the child commits, so they look "merged".
+ */
+export function cleanupMerged(root: string, target = "HEAD"): number {
+	root = realpathSync(root);
+	const merged = git(root, ["branch", "--merged", target])
+		.split("\n")
+		.map((b) => b.trim().replace(/^[+*]\s*/, ""));
+	const live = new Set(worktreeBranches(root));
+	let cleaned = 0;
+	for (const branch of merged) {
+		if (!branch.startsWith("subagents/") || live.has(branch)) continue;
+		const path = join(root, ".git", "subagents", branch.slice("subagents/".length));
+		if (existsSync(path)) {
+			try {
+				git(root, ["worktree", "remove", "--force", path]);
+			} catch {
+				continue;
+			}
+		}
+		if (gitOk(root, ["branch", "-d", branch])) cleaned += 1;
+	}
+	prune(root);
+	return cleaned;
+}
+
+/** Branch names currently checked out in any worktree (incl. the main one). */
+function worktreeBranches(root: string): string[] {
+	try {
+		return git(root, ["worktree", "list", "--porcelain"])
+			.split("\n")
+			.filter((l) => l.startsWith("branch "))
+			.map((l) => l.slice("branch refs/heads/".length).trim());
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Remove worktree dirs that are NOT registered worktrees (crash leftovers).
+ * A crash leaves the dir AND the branch, so branch-existence can't identify
+ * leftovers — worktree registration can. Branches always survive.
+ */
+export function sweepStale(root: string): void {
+	root = realpathSync(root);
+	const sub = join(root, ".git", "subagents");
+	if (!existsSync(sub)) return;
+	const registered = new Set(worktreePaths(root));
+	for (const runDir of readDirs(sub)) {
+		for (const taskDir of readDirs(join(sub, runDir))) {
+			const dir = join(sub, runDir, taskDir);
+			if (registered.has(dir)) continue; // live worktree
+			try {
+				git(root, ["worktree", "remove", "--force", dir]);
+			} catch {
+				// dir not a registered worktree (partial crash) — plain rm
+				rmSync(dir, { recursive: true, force: true });
+			}
+		}
+	}
+	prune(root);
+}
+
+function worktreePaths(root: string): string[] {
+	try {
+		return git(root, ["worktree", "list", "--porcelain"])
+			.split("\n")
+			.filter((l) => l.startsWith("worktree "))
+			.map((l) => l.slice("worktree ".length).trim());
+	} catch {
+		return [];
+	}
+}
+
+function readDirs(dir: string): string[] {
+	try {
+		return readdirSync(dir, { withFileTypes: true })
+			.filter((d) => d.isDirectory())
+			.map((d) => d.name);
+	} catch {
+		return [];
+	}
+}