@henryqw/pi-subagent 2.10.2 → 2.11.7

package/README.md

@@ -60,10 +60,13 @@ Do not edit files.
 | `tools` | no | Omit for Pi defaults; when present, base tools are listed and every loaded Role/caller extension tool is added automatically. `[]` leaves extension tools only. |
 | `extensions` | no | Absolute/`~/` paths or package sources. Package-declared Skills and Pi `resources_discover` Skill paths load automatically. Repository-relative paths are rejected. |
 | `skills` | no | Additional effective Pi Skill names, resolved from Main's registry |
+| `isolation` | no | Set to `worktree` to give each delegated child its own git worktree branched from Main's current `HEAD` |
 | Markdown body | yes | Role system instructions |
 
 Missing skills warn and skip; they do not block delegation. No repo-controlled `.pi/agents` roles. No package-local model picker.
 
+With `isolation: worktree`, each child runs in `<primary-workspace>/.worktrees/subagent-<hash>` on branch `pi-subagent/subagent-<hash>`, using a fixed hash of the child ID so parallel children never clobber each other's files. This stable root keeps children outside removable linked checkouts. Git submodules reject worktree isolation because parent cleanup can remove their Git metadata. Non-git directories and repositories with no commits silently share Main's working directory; worktree setup failures in a real git repository reject the delegation instead of silently losing isolation. The directory is excluded from git status through the repository-local exclude file. The child is told to work only inside its worktree and commit to its branch; after each run the parent sees a worktree report (path, branch, commits, dirty, pruned) appended to the result — including failures and preserved background work during session shutdown, so kept work is always locatable. Worktrees are discarded only when the dedicated branch has no commits, `HEAD` still names that branch, and the full tree including ignored files and submodules is clean; anything holding work stays for the parent to review and merge — children never merge.
+
 ## Library API
 
 Package root exports shared `Role` loading, Skill resolution, task-routed Pi launch, and generic managed Herdr lifecycle:

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type HerdrExecutor } from "@henryqw/pi-herdr";
 import { type AvailableModel, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
+export { createChildWorktree, finalizeChildWorktree, worktreeContextNote, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
 export interface Role {
     name: string;
     description: string;
     tools?: string[];
+    isolation?: string;
     extensions: string[];
     skills: string[];
     systemPrompt: string;

package/dist/index.js

@@ -5,10 +5,12 @@ import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { createHerdrClient, herdrCommandFailure, hasHerdrErrorCode } from "@henryqw/pi-herdr";
 import { modelReference, orderedProfileRoutes, PROFILE_NAMES, readTaskModelsConfig, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
+export { createChildWorktree, finalizeChildWorktree, worktreeContextNote, } from "./worktree.js";
 const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;
 const MULTI_CODEX_EXTENSION = fileURLToPath(import.meta.resolve("@henryqw/pi-multi-codex/extensions/multi-codex.ts"));
 const ROLE_TOOLS_EXTENSION = fileURLToPath(new URL("../extensions/role-tools.ts", import.meta.url));
 const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+const CHILD_EXCLUDED_TOOLS = "delegate_task,ask_question,auto_dag_approve,auto_dag_start";
 export const isProfileName = (value) => typeof value === "string" && PROFILE_NAMES.includes(value);
 const cleanText = (value, field, source) => {
     if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
@@ -64,10 +66,14 @@ export function loadRoles(agentDir = getAgentDir()) {
             throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
         }
         const frontmatter = parsed.frontmatter;
+        const isolation = frontmatter.isolation === undefined ? undefined : cleanText(frontmatter.isolation, "isolation", file);
+        if (isolation !== undefined && isolation !== "worktree")
+            throw new Error(`${file}: isolation must be "worktree".`);
         return {
             name: cleanText(frontmatter.name, "name", file),
             description: cleanText(frontmatter.description, "description", file),
             tools: frontmatter.tools === undefined ? undefined : stringList(frontmatter.tools, "tools", file, true),
+            isolation,
             extensions: extensionList(frontmatter.extensions, file),
             skills: stringList(frontmatter.skills, "skills", file),
             systemPrompt: cleanText(parsed.body, "system prompt", file),
@@ -135,7 +141,7 @@ export function createRoleLaunch(pi, ctx, input) {
             throw new Error(`Invalid launch environment value: ${key}`);
         return [key, value];
     }));
-    const args = ["--no-session", "--no-extensions", "--no-skills"];
+    const args = ["--no-session", "--no-extensions", "--no-skills", "--exclude-tools", CHILD_EXCLUDED_TOOLS];
     for (const extension of new Set(extensions))
         args.push("--extension", extension);
     for (const skill of skills.paths)

package/dist/worktree.d.ts

@@ -0,0 +1,41 @@
+export interface WorktreeInfo {
+    path: string;
+    cwd: string;
+    branch: string;
+    repoRoot: string;
+    baseCommit: string;
+}
+export interface WorktreePayload {
+    path: string;
+    branch: string;
+    commits: number;
+    dirty: boolean;
+    pruned: boolean;
+    inspection_failed?: boolean;
+    note?: string;
+}
+export type GitRunner = (args: string[], cwd: string, signal?: AbortSignal) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Creates one worktree per child from parent HEAD. Returns undefined only when
+ * the workspace is not a git repository or HEAD is unborn — callers degrade
+ * silently to the shared working directory. Setup failures in a real git
+ * repository (unwritable path, stale branch, git lock) throw so an isolated
+ * role never silently loses its isolation.
+ */
+export declare function createChildWorktree(cwd: string, childId: string, run?: GitRunner, signal?: AbortSignal): Promise<WorktreeInfo | undefined>;
+/**
+ * Inspects and possibly prunes a child worktree after it finishes. Commit count
+ * reads the dedicated branch and refuses to prune when checkout HEAD no longer
+ * names it; the clean-tree proof includes untracked, ignored, and submodule
+ * changes despite repository config. A worktree with zero branch commits and a
+ * clean tree is removed only when every probe succeeds and base_commit was
+ * recorded; any probe failure keeps everything and reports `inspection_failed`
+ * so unmeasured state is never read as empty.
+ */
+export declare function finalizeChildWorktree(info: WorktreeInfo, run?: GitRunner): Promise<WorktreePayload>;
+/** Context block telling the child to work inside its isolated worktree. */
+export declare function worktreeContextNote(info: WorktreeInfo): string;

package/dist/worktree.js

@@ -0,0 +1,252 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync } from "node:fs";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+const GIT_TIMEOUT_MS = 30_000;
+const WORKTREES_DIRNAME = ".worktrees";
+const BRANCH_NAMESPACE = "pi-subagent";
+class WorktreeSetupError extends Error {
+    name = "WorktreeSetupError";
+}
+/** Runs git, capturing output; never throws on non-zero exit or spawn failure. */
+const runGit = (args, cwd, signal) => new Promise((resolve) => {
+    execFile("git", args, { cwd, timeout: GIT_TIMEOUT_MS, signal }, (error, stdout, stderr) => {
+        resolve({
+            code: error ? (typeof error.code === "number" ? error.code : -1) : 0,
+            stdout: String(stdout),
+            stderr: String(stderr),
+        });
+    });
+});
+const sanitizeShortId = (childId) => createHash("sha256").update(childId).digest("hex").slice(0, 24);
+const stripGitLineEnd = (value) => value.replace(/\r?\n$/, "");
+function hasRepositoryMarker(cwd) {
+    for (let directory = resolve(cwd);; directory = dirname(directory)) {
+        try {
+            lstatSync(join(directory, ".git"));
+            return true;
+        }
+        catch (error) {
+            if (!error || typeof error !== "object" || !("code" in error) || !["ENOENT", "ENOTDIR"].includes(String(error.code)))
+                return true;
+        }
+        if (dirname(directory) === directory)
+            return false;
+    }
+}
+/** Keeps ".worktrees/" out of git status via the common repository's exclude file; never dirties any checkout. */
+async function ensureLocalExclude(gitDir) {
+    const entry = `/${WORKTREES_DIRNAME}/`;
+    const exclude = join(gitDir, "info", "exclude");
+    try {
+        await mkdir(join(gitDir, "info"), { recursive: true });
+        let existing = "";
+        try {
+            existing = await readFile(exclude, "utf8");
+        }
+        catch (error) {
+            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT")
+                throw error;
+        }
+        if (existing.split("\n").some((line) => line.trim() === entry))
+            return;
+        await appendFile(exclude, `${existing && !existing.endsWith("\n") ? "\n" : ""}${entry}\n`);
+    }
+    catch (error) {
+        throw new WorktreeSetupError(`Could not update ${exclude}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Creates one worktree per child from parent HEAD. Returns undefined only when
+ * the workspace is not a git repository or HEAD is unborn — callers degrade
+ * silently to the shared working directory. Setup failures in a real git
+ * repository (unwritable path, stale branch, git lock) throw so an isolated
+ * role never silently loses its isolation.
+ */
+export async function createChildWorktree(cwd, childId, run = runGit, signal) {
+    const root = await run(["rev-parse", "--show-toplevel"], cwd, signal);
+    if (root.code !== 0) {
+        signal?.throwIfAborted();
+        const repository = await run(["-c", "safe.directory=*", "rev-parse", "--show-toplevel"], cwd, signal);
+        signal?.throwIfAborted();
+        if (repository.code !== 0 && !hasRepositoryMarker(cwd) && !process.env.GIT_DIR && !process.env.GIT_WORK_TREE)
+            return undefined;
+        throw new Error(`git rev-parse failed (${root.stderr.trim().slice(0, 200)})`); // dubious ownership, timeout, …
+    }
+    const repoRoot = stripGitLineEnd(root.stdout);
+    if (!repoRoot)
+        return undefined;
+    const prefix = await run(["rev-parse", "--show-prefix"], cwd, signal);
+    if (prefix.code !== 0)
+        throw new Error(`git rev-parse --show-prefix failed (${prefix.stderr.trim().slice(0, 200)})`);
+    const relativeCwd = stripGitLineEnd(prefix.stdout);
+    const base = await run(["rev-parse", "HEAD"], repoRoot, signal);
+    if (base.code !== 0) {
+        signal?.throwIfAborted();
+        const head = await run(["symbolic-ref", "--quiet", "HEAD"], repoRoot, signal);
+        signal?.throwIfAborted();
+        const reference = stripGitLineEnd(head.stdout);
+        if (head.code === 0 && reference) {
+            const exists = await run(["show-ref", "--verify", "--quiet", reference], repoRoot, signal);
+            signal?.throwIfAborted();
+            if (exists.code === 1)
+                return undefined; // unborn HEAD
+        }
+        throw new Error(`git rev-parse HEAD failed (${base.stderr.trim().slice(0, 200)})`);
+    }
+    const baseCommit = base.stdout.trim();
+    const superproject = await run(["rev-parse", "--show-superproject-working-tree"], repoRoot, signal);
+    if (superproject.code !== 0) {
+        throw new Error(`git rev-parse --show-superproject-working-tree failed (${superproject.stderr.trim().slice(0, 200)})`);
+    }
+    if (stripGitLineEnd(superproject.stdout)) {
+        throw new Error("Worktree isolation is unavailable inside Git submodules because parent cleanup can remove their Git metadata.");
+    }
+    const common = await run(["rev-parse", "--git-common-dir"], repoRoot, signal);
+    const rawCommonGitDir = stripGitLineEnd(common.stdout);
+    if (common.code !== 0 || !rawCommonGitDir) {
+        throw new Error(`git rev-parse --git-common-dir failed (${common.stderr.trim().slice(0, 200)})`);
+    }
+    const current = await run(["rev-parse", "--git-dir"], repoRoot, signal);
+    const rawCurrentGitDir = stripGitLineEnd(current.stdout);
+    if (current.code !== 0 || !rawCurrentGitDir) {
+        throw new Error(`git rev-parse --git-dir failed (${current.stderr.trim().slice(0, 200)})`);
+    }
+    const gitDir = isAbsolute(rawCommonGitDir) ? rawCommonGitDir : join(repoRoot, rawCommonGitDir);
+    const currentGitDir = isAbsolute(rawCurrentGitDir) ? rawCurrentGitDir : join(repoRoot, rawCurrentGitDir);
+    let stableRepoRoot = repoRoot;
+    if (currentGitDir !== gitDir) {
+        const worktrees = await run(["worktree", "list", "--porcelain", "-z"], repoRoot, signal);
+        const primary = worktrees.stdout.split("\0", 1)[0];
+        if (worktrees.code !== 0 || !primary?.startsWith("worktree ") || primary.length === "worktree ".length) {
+            throw new Error(`git worktree list failed (${worktrees.stderr.trim().slice(0, 200)})`);
+        }
+        stableRepoRoot = primary.slice("worktree ".length);
+    }
+    signal?.throwIfAborted();
+    const worktreesRoot = join(stableRepoRoot, WORKTREES_DIRNAME);
+    const name = `subagent-${sanitizeShortId(childId)}`;
+    const branch = `${BRANCH_NAMESPACE}/${name}`;
+    const path = join(worktreesRoot, name);
+    try {
+        await mkdir(worktreesRoot, { recursive: true });
+    }
+    catch (error) {
+        throw new Error(`Could not create ${worktreesRoot}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    await ensureLocalExclude(gitDir);
+    signal?.throwIfAborted();
+    const added = await run(["worktree", "add", path, "-b", branch, baseCommit], repoRoot, signal);
+    if (added.code !== 0) {
+        throw new WorktreeSetupError(`git worktree add failed; preserved ${path} and ${branch}: ${added.stderr.trim().slice(0, 200)}`);
+    }
+    return { path, cwd: join(path, relativeCwd), branch, repoRoot: stableRepoRoot, baseCommit };
+}
+/** Flags a payload whose state could not be measured (#88113): unmeasured is not zero. */
+function markUnproven(payload, reason, unmeasured = "commits/dirty") {
+    payload.inspection_failed = true;
+    payload.note =
+        `git inspection failed (${reason}): ${unmeasured} UNKNOWN — not proven zero/clean. `
+            + `Any remaining worktree or branch was preserved — inspect ${payload.path} (branch ${payload.branch}) before assuming no work.`;
+    return payload;
+}
+async function inspectDirty(run, cwd) {
+    const refreshed = await run(["update-index", "--really-refresh"], cwd);
+    if (refreshed.code !== 0 && refreshed.code !== 1) {
+        return { dirty: false, failure: `update-index exit ${refreshed.code}: ${refreshed.stderr.trim().slice(0, 200)}` };
+    }
+    const status = await run(["status", "--porcelain", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], cwd);
+    if (status.code !== 0)
+        return { dirty: false, failure: `status exit ${status.code}: ${status.stderr.trim().slice(0, 200)}` };
+    if (refreshed.code === 1 || status.stdout.trim())
+        return { dirty: true };
+    const flags = await run(["ls-files", "-v", "-z"], cwd);
+    if (flags.code !== 0)
+        return { dirty: false, failure: `ls-files exit ${flags.code}: ${flags.stderr.trim().slice(0, 200)}` };
+    if (flags.stdout.split("\0").some((entry) => /^(?:[a-z]|S) /.test(entry))) {
+        return { dirty: false, failure: "assume-unchanged or skip-worktree index entries remain" };
+    }
+    return { dirty: false };
+}
+/**
+ * Inspects and possibly prunes a child worktree after it finishes. Commit count
+ * reads the dedicated branch and refuses to prune when checkout HEAD no longer
+ * names it; the clean-tree proof includes untracked, ignored, and submodule
+ * changes despite repository config. A worktree with zero branch commits and a
+ * clean tree is removed only when every probe succeeds and base_commit was
+ * recorded; any probe failure keeps everything and reports `inspection_failed`
+ * so unmeasured state is never read as empty.
+ */
+export async function finalizeChildWorktree(info, run = runGit) {
+    const payload = { path: info.path, branch: info.branch, commits: 0, dirty: false, pruned: false };
+    const checkoutExists = existsSync(info.path);
+    const gitCwd = checkoutExists ? info.path : info.repoRoot || info.path;
+    if (!info.baseCommit)
+        return markUnproven(payload, "no base_commit recorded — commit count unmeasurable", "commits");
+    const counted = await run(["rev-list", "--count", `${info.baseCommit}..${info.branch}`], gitCwd);
+    const commits = Number.parseInt(counted.stdout.trim(), 10);
+    const countFailure = counted.code !== 0
+        ? `rev-list exit ${counted.code}: ${counted.stderr.trim().slice(0, 200)}`
+        : Number.isNaN(commits) ? "rev-list produced non-numeric output" : undefined;
+    const inspection = checkoutExists ? await inspectDirty(run, info.path) : undefined;
+    if (!countFailure)
+        payload.commits = commits;
+    if (inspection)
+        payload.dirty = inspection.dirty;
+    if (countFailure || inspection?.failure) {
+        return markUnproven(payload, [countFailure, inspection?.failure].filter(Boolean).join("; "), [countFailure && "commits", inspection?.failure && "dirty"].filter(Boolean).join("/"));
+    }
+    let forceRemove = false;
+    if (checkoutExists) {
+        if (payload.commits > 0 || payload.dirty)
+            return payload;
+        const head = await run(["symbolic-ref", "--quiet", "HEAD"], info.path);
+        if (head.code !== 0 || head.stdout.trim() !== `refs/heads/${info.branch}`) {
+            return markUnproven(payload, "HEAD is detached, switched, or unreadable", "checked-out commits");
+        }
+        const modules = await run(["submodule", "status", "--recursive"], info.path);
+        if (modules.code !== 0)
+            return markUnproven(payload, `submodule list exit ${modules.code}: ${modules.stderr.trim().slice(0, 200)}`, "dirty");
+        forceRemove = modules.stdout.split("\n").some((line) => line && !line.startsWith("-"));
+        if (forceRemove) {
+            const listed = await run(["submodule", "foreach", "--recursive", "--quiet", "printf '%s\\0' \"$PWD\""], info.path);
+            if (listed.code !== 0)
+                return markUnproven(payload, `submodule list exit ${listed.code}: ${listed.stderr.trim().slice(0, 200)}`, "dirty");
+            const paths = listed.stdout.split("\0").filter(Boolean);
+            if (!paths.length)
+                return markUnproven(payload, "initialized submodule paths unavailable", "dirty");
+            for (const path of paths) {
+                const nested = await inspectDirty(run, path);
+                if (nested.failure)
+                    return markUnproven(payload, `submodule ${path}: ${nested.failure}`, "dirty");
+                if (nested.dirty) {
+                    payload.dirty = true;
+                    return payload;
+                }
+            }
+        }
+        const rechecked = await inspectDirty(run, info.path);
+        if (rechecked.failure)
+            return markUnproven(payload, `final ${rechecked.failure}`, "dirty");
+        if (rechecked.dirty) {
+            payload.dirty = true;
+            return payload;
+        }
+    }
+    else if (payload.commits > 0)
+        return payload;
+    const cleanupCwd = info.repoRoot || info.path;
+    const removed = await run(["worktree", "remove", ...(forceRemove ? ["--force"] : []), info.path], cleanupCwd);
+    if (removed.code !== 0)
+        return markUnproven(payload, `worktree remove exit ${removed.code}: ${removed.stderr.trim().slice(0, 200)}`, "cleanup");
+    const deleted = await run(["update-ref", "-d", `refs/heads/${info.branch}`, info.baseCommit], cleanupCwd);
+    if (deleted.code !== 0)
+        return markUnproven(payload, `branch delete exit ${deleted.code}: ${deleted.stderr.trim().slice(0, 200)}`, "cleanup");
+    payload.pruned = true;
+    return payload;
+}
+/** Context block telling the child to work inside its isolated worktree. */
+export function worktreeContextNote(info) {
+    return `\n\n[WORKTREE ISOLATION] Work only in ${info.path} on ${info.branch}; do not use main checkout. Commit changes to this branch for parent review.`;
+}

package/extensions/role-tools.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+const CHILD_EXCLUDED_TOOLS = new Set(["delegate_task", "ask_question", "auto_dag_approve", "auto_dag_start"]);
 
 function configuredTools(value: unknown): string[] | undefined {
 	if (value === undefined) return;
@@ -28,6 +29,6 @@ export default function roleTools(pi: ExtensionAPI): void {
 		const extensionTools = pi.getAllTools()
 			.filter((tool) => !["builtin", "sdk", "inline"].includes(tool.sourceInfo.source))
 			.map((tool) => tool.name);
-		pi.setActiveTools([...new Set([...selected, ...extensionTools])]);
+		pi.setActiveTools([...new Set([...selected, ...extensionTools])].filter((name) => !CHILD_EXCLUDED_TOOLS.has(name)));
 	});
 }

package/extensions/subagent.ts

@@ -18,7 +18,7 @@ import {
 	taskThinkingLevels,
 } from "@henryqw/pi-task-models";
 import { Type } from "typebox";
-import { createRoleLaunch, isProfileName, loadRoles, resolveTaskRoute } from "@henryqw/pi-subagent";
+import { createChildWorktree, createRoleLaunch, finalizeChildWorktree, isProfileName, loadRoles, resolveTaskRoute, worktreeContextNote, type WorktreeInfo, type WorktreePayload } from "@henryqw/pi-subagent";
 
 const SUBAGENT_TASK = "pi-subagent/delegateTask";
 const MAX_OUTPUT_BYTES = 50 * 1024;
@@ -55,6 +55,11 @@ type ChildResult = {
 	stopReason?: string;
 	errorMessage?: string;
 };
+type DelegateResult = {
+	content: [{ type: "text"; text: string }];
+	details: Record<string, unknown>;
+	isError?: boolean;
+};
 type WidgetStatus = "working" | "success" | "failure" | "aborted";
 type WidgetItem = {
 	roleRoute: string;
@@ -130,6 +135,16 @@ function taskSummary(task: string): string {
 	return task.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().split(/\s+/).slice(0, 4).join(" ");
 }
 
+/** Finalizes an isolated child's worktree; returns its report, or undefined when absent/failed. */
+async function finalizeWorktreePayload(worktree: WorktreeInfo | undefined): Promise<WorktreePayload | undefined> {
+	if (!worktree) return undefined;
+	try {
+		return await finalizeChildWorktree(worktree);
+	} catch {
+		return undefined;
+	}
+}
+
 function formatTokens(tokens: number): string {
 	if (tokens < 1_000) return String(tokens);
 	if (tokens < 100_000) return `${(tokens / 1_000).toFixed(1)}k`;
@@ -311,12 +326,16 @@ async function runPi(
 			}
 		};
 
-		const killTree = (force: boolean) => {
+		const killTree = async (force: boolean): Promise<void> => {
 			if (!child.pid) return;
 			if (process.platform === "win32") {
-				spawn("taskkill", [...(force ? ["/F"] : []), "/T", "/PID", String(child.pid)], {
-					stdio: "ignore",
-					windowsHide: true,
+				await new Promise<void>((resolve) => {
+					const taskkill = spawn("taskkill", [...(force ? ["/F"] : []), "/T", "/PID", String(child.pid)], {
+						stdio: "ignore",
+						windowsHide: true,
+					});
+					taskkill.once("error", () => resolve());
+					taskkill.once("close", () => resolve());
 				});
 				return;
 			}
@@ -350,7 +369,7 @@ async function runPi(
 						lineBytes += Buffer.byteLength(part, "utf8");
 						if (lineBytes > MAX_JSON_EVENT_BYTES) {
 							protocolError = new Error(`Subagent JSON event exceeds ${MAX_JSON_EVENT_BYTES} bytes.`);
-							killTree(true);
+							void killTree(true);
 							return;
 						}
 						if (part) lineParts.push(part);
@@ -373,8 +392,8 @@ async function runPi(
 		child.on("error", (error) => { spawnError = error; });
 
 		const stop = () => {
-			killTree(false);
-			killTimer = setTimeout(() => killTree(true), 5_000);
+			void killTree(false);
+			killTimer = setTimeout(() => void killTree(true), 5_000);
 			killTimer.unref();
 		};
 		const abort = () => {
@@ -401,9 +420,11 @@ async function runPi(
 		signal?.addEventListener("abort", abort, { once: true });
 		if (signal?.aborted) abort();
 
-		child.on("close", (code) => {
+		child.on("close", async (code) => {
 			if (!protocolError && lineBytes) processLine(lineParts.join(""));
-			if (aborted || timedOutAfterMs !== undefined) killTree(true);
+			// Pi may exit while redirected background commands remain in its process
+			// group. Stop every descendant before callers inspect or prune its cwd.
+			await killTree(true);
 			if (softDeadlineTimer) clearTimeout(softDeadlineTimer);
 			if (hardDeadlineTimer) clearTimeout(hardDeadlineTimer);
 			if (killTimer) clearTimeout(killTimer);
@@ -499,7 +520,7 @@ export default function subagentExtension(
 	const timeoutPolicy: TimeoutPolicy = overrideTimeoutPolicy ?? resolveTimeoutPolicy(loadedConfig.config.timeout);
 	// Background children outlive the launching tool call, so they get their own
 	// abort signal: tied to the session, not to the turn that started them.
-	const backgroundTasks = new Map<string, AbortController>();
+	const backgroundTasks = new Map<string, { controller: AbortController; settled: Promise<void> }>();
 	// Latest known session context; refreshed on session lifecycle and model
 	// changes so queued background launches resolve against effective state.
 	let latestCtx: ExtensionContext | undefined;
@@ -617,16 +638,18 @@ export default function subagentExtension(
 		ensureWidget(ctx);
 		for (const warning of startupWarnings.splice(0)) ctx.ui.notify(warning, "warning");
 	});
-	pi.on("session_shutdown", (_event, ctx) => {
+	pi.on("session_shutdown", async (_event, ctx) => {
 		stopWidgetTimer();
 		widgetItems.clear();
 		activeTui = undefined;
 		widgetInstalled = false;
 		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
-		// Invalidate every outstanding background delivery: the aborting session
-		// is gone, and a later-settling child must not reach the next session.
+		// Invalidate ordinary outcomes, abort children, then let preserved isolated
+		// work report into the outgoing session before Pi tears it down.
 		sessionEpoch += 1;
-		for (const controller of backgroundTasks.values()) controller.abort();
+		const tasks = [...backgroundTasks.values()];
+		for (const { controller } of tasks) controller.abort();
+		await Promise.allSettled(tasks.map(({ settled }) => settled));
 		backgroundTasks.clear();
 	});
 	// btw-style context refresh: model_select carries the new model on the event,
@@ -644,16 +667,23 @@ export default function subagentExtension(
 		details: { role: string; model?: string; thinkingLevel?: string },
 		outcome: "completed" | "failed" | "aborted",
 		text: string,
+		worktreePayload?: WorktreePayload,
+		setupRecovery?: string,
 	): Promise<void> => {
-		if (launchEpoch !== sessionEpoch) return;
+		const stale = launchEpoch !== sessionEpoch;
+		if (stale && (!worktreePayload || worktreePayload.pruned) && !setupRecovery) return;
 		// Custom messages convert to user-role LLM messages, so the parent agent
 		// sees the outcome on its next turn without a forced turn now.
 		try {
 			pi.sendMessage({
 				customType: BACKGROUND_RESULT_TYPE,
-				content: `Background subagent ${taskId} (${details.role}) ${outcome}.\n\n${capOutput(text)}`,
+				content: stale
+					? worktreePayload && !worktreePayload.pruned
+						? `Background subagent ${taskId} (${details.role}) left recoverable isolated work after session shutdown.\n${JSON.stringify(worktreePayload)}`
+						: `Background subagent ${taskId} (${details.role}) left recoverable isolated setup state after session shutdown.\n${setupRecovery}`
+					: `Background subagent ${taskId} (${details.role}) ${outcome}.\n\n${capOutput(text)}${worktreePayload ? `\n${JSON.stringify(worktreePayload)}` : ""}`,
 				display: true,
-				details: { ...details, taskId, outcome },
+				details: { ...details, taskId, outcome, ...(stale ? { recovery: true } : {}) },
 			}, { triggerTurn: false });
 		} catch {
 			// Session may already be gone; the widget row still shows the outcome.
@@ -710,18 +740,21 @@ export default function subagentExtension(
 			if (params.background) {
 				const taskId = `bg-${++backgroundSequence}-${Date.now().toString(36)}`;
 				const controller = new AbortController();
-				backgroundTasks.set(taskId, controller);
 				// Freeze the launching session now: a task that settles after a
 				// reload must not deliver into whichever session is active then.
 				const launchEpoch = sessionEpoch;
-				void (async () => {
+				const settled = (async () => {
 					let acquired = false;
 					let widgetStatus: Exclude<WidgetStatus, "working"> = "failure";
 					// Role is known up front; model/thinking join after launch resolution.
 					let details: { role: string; model?: string; thinkingLevel?: string } = { role: role.name };
+					let worktree: WorktreeInfo | undefined;
 					try {
 						await acquireChildPermit(controller.signal);
 						acquired = true;
+						// Same contract as foreground: isolation only after the permit,
+						// setup failure fails closed via the catch below.
+						if (role.isolation === "worktree") worktree = await createChildWorktree(ctx.cwd, toolCallId, undefined, controller.signal);
 						// Resolve resources only once launched: a task queued past the
 						// cap must not start with model routes or skills resolved before
 						// registries or accounts changed while it waited.
@@ -730,8 +763,8 @@ export default function subagentExtension(
 						details = { role: role.name, model: modelReference(launch.model), thinkingLevel: launch.thinkingLevel };
 						startWidgetItem(taskId, role.name, launch.model.id, launch.thinkingLevel, task, ctx);
 						const result = await runPi(
-							["--mode", "json", "-p", ...launch.args, `Task: ${task}`],
-							ctx.cwd,
+							["--mode", "json", "-p", ...launch.args, `Task: ${worktree ? `${task}${worktreeContextNote(worktree)}` : task}`],
+							worktree?.cwd ?? ctx.cwd,
 							controller.signal,
 							undefined,
 							(tokens) => updateWidgetTokens(taskId, tokens),
@@ -739,25 +772,31 @@ export default function subagentExtension(
 						);
 						const failed = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 						widgetStatus = result.stopReason === "aborted" ? "aborted" : failed ? "failure" : "success";
-						const text = capOutput(failed
+						const text = failed
 							? result.errorMessage || result.stderr.trim() || result.output || `Subagent exited with code ${result.exitCode}.`
-							: result.output || "(no output)");
+							: result.output || "(no output)";
+						const payloadLine = await finalizeWorktreePayload(worktree);
 						await reportBackground(
 							launchEpoch,
 							taskId,
 							details,
 							result.stopReason === "aborted" ? "aborted" : failed ? "failed" : "completed",
 							text,
+							payloadLine,
 						);
 					} catch (error) {
 						const aborted = controller.signal.aborted && !(error instanceof SubagentTimeoutError);
 						widgetStatus = aborted ? "aborted" : "failure";
+						const failureText = error instanceof Error ? error.message : String(error);
+						const payloadLine = await finalizeWorktreePayload(worktree);
 						await reportBackground(
 							launchEpoch,
 							taskId,
 							details,
 							aborted ? "aborted" : "failed",
-							capOutput(error instanceof Error ? error.message : String(error)),
+							failureText,
+							payloadLine,
+							error instanceof Error && error.name === "WorktreeSetupError" ? failureText : undefined,
 						);
 					} finally {
 						if (acquired) releaseChildPermit();
@@ -765,6 +804,8 @@ export default function subagentExtension(
 						backgroundTasks.delete(taskId);
 					}
 				})();
+				backgroundTasks.set(taskId, { controller, settled });
+				void settled;
 				return {
 					content: [{ type: "text" as const, text: `Background subagent ${taskId} started (${role.name}). The outcome arrives as a message when the task settles; keep working or end your turn.` }],
 					details: { role: role.name, taskId, background: true },
@@ -775,32 +816,49 @@ export default function subagentExtension(
 			notifyMissingSkills(launch);
 			const modelReferenceValue = modelReference(launch.model);
 			const details = { role: role.name, model: modelReferenceValue, thinkingLevel: launch.thinkingLevel };
-
 			await acquireChildPermit(signal);
 			let widgetStatus: Exclude<WidgetStatus, "working"> = "failure";
+			let result: DelegateResult | undefined;
+			let worktree: WorktreeInfo | undefined;
+			let rethrow: unknown;
+			let worktreePayload: WorktreePayload | undefined;
 			try {
+				// Isolation is created only after preflight and permit acquisition so a
+				// rejected delegation cannot leak worktrees; setup failure fails closed.
+				if (role.isolation === "worktree") worktree = await createChildWorktree(ctx.cwd, toolCallId, undefined, signal);
 				startWidgetItem(toolCallId, role.name, launch.model.id, launch.thinkingLevel, task, ctx);
-				const result = await runPi(
-					["--mode", "json", "-p", ...launch.args, `Task: ${task}`],
-					ctx.cwd,
+				const child = await runPi(
+					["--mode", "json", "-p", ...launch.args, `Task: ${worktree ? `${task}${worktreeContextNote(worktree)}` : task}`],
+					worktree?.cwd ?? ctx.cwd,
 					signal,
 					(text) => onUpdate?.({ content: [{ type: "text", text }], details }),
 					(tokens) => updateWidgetTokens(toolCallId, tokens),
 					timeoutPolicy,
 				);
-				const failed = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-				widgetStatus = result.stopReason === "aborted" ? "aborted" : failed ? "failure" : "success";
+				const failed = child.exitCode !== 0 || child.stopReason === "error" || child.stopReason === "aborted";
+				widgetStatus = child.stopReason === "aborted" ? "aborted" : failed ? "failure" : "success";
 				const text = capOutput(failed
-					? result.errorMessage || result.stderr.trim() || result.output || `Subagent exited with code ${result.exitCode}.`
-					: result.output || "(no output)");
-				return { content: [{ type: "text" as const, text }], details, ...(failed ? { isError: true } : {}) };
+					? child.errorMessage || child.stderr.trim() || child.output || `Subagent exited with code ${child.exitCode}.`
+					: child.output || "(no output)");
+				result = { content: [{ type: "text" as const, text }], details, ...(failed ? { isError: true } : {}) };
+				return result;
 			} catch (error) {
 				if (signal?.aborted && !(error instanceof SubagentTimeoutError)) widgetStatus = "aborted";
-				throw error;
+				rethrow = error;
 			} finally {
 				releaseChildPermit();
 				finishWidgetItem(toolCallId, widgetStatus);
+				worktreePayload = await finalizeWorktreePayload(worktree);
+				if (result && worktreePayload) result.content[0].text += `\n${JSON.stringify(worktreePayload)}`;
+			}
+			if (rethrow !== undefined) {
+				// A kept-but-unreported worktree is unrecoverable: attach the report
+				// locating it (path/branch/dirty state) to whatever failure escapes.
+				throw worktreePayload
+					? new Error(`${rethrow instanceof Error ? rethrow.message : String(rethrow)}\n${JSON.stringify(worktreePayload)}`)
+					: rethrow;
 			}
+			return result!;
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "2.10.2",
+  "version": "2.11.7",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",
@@ -59,6 +59,6 @@
   "dependencies": {
     "@henryqw/pi-herdr": "^0.1.1",
     "@henryqw/pi-multi-codex": "^0.3.8",
-    "@henryqw/pi-task-models": "^0.6.0"
+    "@henryqw/pi-task-models": "^0.7.2"
   }
 }