@arhen/pi-core-subagent 1.3.28 → 1.3.29

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.29",
 	"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

@@ -30,6 +30,7 @@ import {
 	type SubagentParamsShape,
 } from "./schemas.ts";
 import { type RunDetails, type RunSnapshot, TERMINAL } from "./types.ts";
+import { repoRoot, sweepStale } from "./worktree.ts";
 
 export default function (pi: ExtensionAPI) {
 	const manager = new SubagentManager(pi);
@@ -109,6 +110,16 @@ 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).
+		sweepStale(ctx.cwd);
+		for (const run of manager.listRuns()) {
+			for (const task of run.tasks) {
+				if (task.branch) {
+					const root = repoRoot(task.cwd);
+					if (root) sweepStale(root);
+				}
+			}
+		}
 	});
 	pi.on("session_shutdown", async (_event, ctx) => {
 		if (ctx?.hasUI) {
@@ -127,7 +138,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 +146,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.",
@@ -270,10 +282,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

@@ -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;
@@ -641,6 +652,19 @@ export class SubagentManager {
 		const baseTools = file?.tools ?? input.tools ?? (input.write ? WRITE_TOOLS : READONLY_TOOLS);
 		const tools = [...baseTools, ...(run.allowIntercom ? CHILD_TALK_TOOLS : [])];
 
+		// 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 (input.write) {
+			try {
+				wt = createWorktree(task.cwd, run.id, task.id);
+			} catch {
+				wt = undefined; // git failure → in-place
+			}
+		}
+		const childCwd = wt?.path ?? task.cwd;
+
 		// Model + thinking resolve against the pi model registry; a bad request
 		// fails the TASK with a helpful message, not the whole run.
 		let model: Model<Api> | undefined;
@@ -689,11 +713,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 +732,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 +814,20 @@ 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.
+					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 (err) {
 			if (timeout) clearTimeout(timeout);
@@ -823,6 +861,12 @@ export class SubagentManager {
 			watchdog.dispose();
 			if (timeout) clearTimeout(timeout);
 			child?.dispose();
+			// Failed/aborted: the branch keeps any partial work for manual merging, the
+			// checkout dir is removed so it can't linger on disk.
+			if (wt && task.status !== "completed") {
+				this.updateTask(run, task, { branch: wt.branch }, ctx, onUpdate);
+				removeWorktree(wt);
+			}
 		}
 	}
 
@@ -986,6 +1030,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 +1113,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,163 @@
+/** 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, 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; // branch HEAD 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", "--abbrev-ref", "HEAD"]);
+	} catch {
+		return undefined; // detached or 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"]);
+	gitIn(wt.path, ["commit", "-m", message, "--no-verify"]);
+}
+
+/** Diffstat + changed files of the branch vs its base. */
+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 */
+	}
+}
+
+/** 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 */
+	}
+}
+
+/** Delete branch + worktree for branches already merged into `target`. */
+export function cleanupMerged(root: string, target = "HEAD"): number {
+	const merged = git(root, ["branch", "--merged", target])
+		.split("\n")
+		.map((b) => b.trim().replace(/^[+*]\s*/, ""));
+	let cleaned = 0;
+	for (const branch of merged) {
+		if (!branch.startsWith("subagents/")) 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;
+	}
+	return cleaned;
+}
+
+/** Remove worktree dirs of branches that no longer exist (crash leftovers). */
+export function sweepStale(root: string): void {
+	const sub = join(root, ".git", "subagents");
+	if (!existsSync(sub)) return;
+	const branches = new Set(
+		git(root, ["branch", "--list", "subagents/*"])
+			.split("\n")
+			.map((b) => b.trim().replace(/^[+*]\s*/, "")),
+	);
+	for (const runDir of readDirs(sub)) {
+		for (const taskDir of readDirs(join(sub, runDir))) {
+			const branch = `subagents/${runDir}/${taskDir}`;
+			if (branches.has(branch)) continue; // live branch, dir may be an active worktree
+			try {
+				git(root, ["worktree", "remove", "--force", join(sub, runDir, taskDir)]);
+			} catch {
+				// dir not a registered worktree (partial crash) — plain rm
+				rmSync(join(sub, runDir, taskDir), { recursive: true, force: true });
+			}
+		}
+	}
+}
+
+function readDirs(dir: string): string[] {
+	try {
+		return readdirSync(dir, { withFileTypes: true })
+			.filter((d) => d.isDirectory())
+			.map((d) => d.name);
+	} catch {
+		return [];
+	}
+}