@bacnh85/pi-subagent 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.14.1 (2026-08-07)
+
+### Improvements
+
+- Widen peer dependency range to support Pi 0.84.0 (`>=0.80.0 <0.85.0`).
+  No code changes — verified compatible against the 0.84.0 SDK types.
+
+## 0.14.0 (2026-08-05)
+
+### Git worktree isolation (`sandbox: worktree`)
+
+Agents can now run in an isolated **git worktree** instead of the parent's
+working tree — the safe way to run parallel implementation agents that edit
+files. Set `sandbox: worktree` in agent frontmatter (see `agent-format.md`).
+
+- Child file mutations land in `.pi-worktrees/<id>` under the repo root; the
+  main checkout stays untouched, so two parallel `worker` agents can never
+  clobber each other's edits.
+- On completion, a unified diff of the child's changes is returned as
+  `result.patch` and shown in the thread viewer as a `🌿 worktree` badge.
+- **Merging is explicit** — the parent receives the diff and applies it via
+  `apply_patch` / cherry-pick / discard; nothing is auto-merged.
+- The worktree is removed in a `finally` on success, error, or abort.
+- Falls back to in-process execution with a warning when the cwd is not a git
+  repo (`ponytail`: isolation optimization, not a hard requirement).
+- Wired through the `subagent` tool, the service path (`pi-subagent:run` for
+  pi-review), and `runner.ts`'s `runSubAgent` (new `sandbox` + `exec` options).
+
 ## 0.13.0 (2026-07-31)
 
 ### Subagents inherit parent extensions & tools by default

package/README.md

@@ -84,6 +84,25 @@ Child agent tools are validated against a fixed allowlist:
 
 Unknown or misspelled tool names produce clear diagnostics. Duplicate tool names are deduplicated.
 
+### Git worktree isolation (`sandbox: worktree`)
+
+Set `sandbox: worktree` in an agent's frontmatter to run it in an isolated git
+worktree (`.pi-worktrees/<id>` under the repo root) instead of the parent's
+working tree. This is the safe way to run **parallel implementation** agents:
+two `worker` agents editing the same files can no longer clobber each other —
+each writes into its own checkout.
+
+- All file mutations land in the worktree; the main checkout stays untouched.
+- On completion, a unified diff of the child's changes is returned in the
+  result and shown in the thread viewer as a `🌿 worktree` badge.
+- **Merging is explicit**: the parent receives the diff and applies it via
+  `apply_patch` / cherry-pick / discard. Nothing is auto-merged.
+- The worktree is removed on completion (success, error, or abort).
+- Requires git; when the cwd is not a git repo, the agent falls back to
+  in-process execution with a warning (`ponytail`: isolation optimization,
+  not a hard requirement).
+
+
 ### Timeouts
 
 Every child execution receives a timeout:

package/agent-format.md

@@ -24,7 +24,7 @@ models:                   # Optional ordered fallbacks; comma form also accepted
   - provider/fast-model
   - provider/backup-model
 thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
-sandbox: read-only        # Optional: read-only | workspace-write. Auto-derives tool restrictions.
+sandbox: read-only        # Optional: read-only | workspace-write | worktree. Auto-derives tool restrictions.
 color: cyan               # Optional: red|blue|green|yellow|purple|orange|pink|cyan.
 ---
 ```
@@ -33,6 +33,7 @@ color: cyan               # Optional: red|blue|green|yellow|purple|orange|pink|c
 
 - `read-only`: Restricts tools to `read`, `grep`, `find`, `ls`. Overrides any `tools` field.
 - `workspace-write` (default): Uses the agent's `tools` list or defaults to all tools.
+- `worktree`: Runs the agent in an isolated git worktree (`.pi-worktrees/<id>` under the repo root). All file mutations land in the worktree; the main checkout is untouched. On completion, a unified diff of the changes is returned in the result (visible in the thread viewer as a `🌿 worktree` badge) — the parent merges explicitly via `apply_patch`/cherry-pick; nothing is applied automatically. Falls back to in-process execution when the cwd is not a git repo (with a warning). Requires git.
 
 ### `color`
 

package/extensions/agents.ts

@@ -22,7 +22,7 @@ export interface AgentConfig {
   model?: string;
   models?: string[];
   thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-  sandbox?: "read-only" | "workspace-write";
+  sandbox?: "read-only" | "workspace-write" | "worktree";
   color?: AgentColor;
   systemPrompt: string;
   source: "user" | "project" | "bundled";
@@ -203,7 +203,7 @@ function loadAgentsFromDir(
     }
 
     if (typeof frontmatter.sandbox === "string" && frontmatter.sandbox) {
-      const validSandboxes = ["read-only", "workspace-write"];
+      const validSandboxes = ["read-only", "workspace-write", "worktree"];
       if (!validSandboxes.includes(frontmatter.sandbox)) {
         diagnostics.push({
           filePath,
@@ -231,8 +231,8 @@ function loadAgentsFromDir(
       thinking: typeof frontmatter.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(frontmatter.thinking)
         ? frontmatter.thinking as AgentConfig["thinking"]
         : undefined,
-      sandbox: typeof frontmatter.sandbox === "string" && ["read-only", "workspace-write"].includes(frontmatter.sandbox)
-        ? frontmatter.sandbox as "read-only" | "workspace-write"
+      sandbox: typeof frontmatter.sandbox === "string" && ["read-only", "workspace-write", "worktree"].includes(frontmatter.sandbox)
+        ? frontmatter.sandbox as "read-only" | "workspace-write" | "worktree"
         : undefined,
       color: typeof frontmatter.color === "string" && VALID_COLORS.includes(frontmatter.color as any)
         ? frontmatter.color as AgentColor

package/extensions/index.ts

@@ -647,6 +647,7 @@ export default function (pi: ExtensionAPI) {
 
             const result = await runSubAgent({
               cwd: safeCwd,
+              sandbox: agent.sandbox === "worktree" ? "worktree" : undefined,
               systemPrompt: params.instructions
               ? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}`
               : agent.systemPrompt,

package/extensions/render.ts

@@ -236,6 +236,15 @@ export function renderSingleResult(
       container.addChild(new Spacer(1));
       container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
     }
+    if (result.patch) {
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("success", "🌿 worktree"), 0, 0));
+      const patchLines = result.patch.split("\n").length;
+      container.addChild(new Text(theme.fg("dim", `${patchLines} diff lines — merge explicitly via apply_patch/cherry-pick`), 0, 0));
+      if (result.patch !== "(no changes)") {
+        container.addChild(new Text(theme.fg("muted", result.patch.slice(0, 2000)), 0, 0));
+      }
+    }
     return container;
   }
 
@@ -258,6 +267,7 @@ export function renderSingleResult(
   }
   const usageStr = formatUsageStats(result.usage, result.model);
   if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
+  if (result.patch) text += `\n${theme.fg("success", "🌿 worktree")} (${result.patch.split("\n").length} diff lines)`;
   return new Text(text, 0, 0);
 }
 

package/extensions/runner.ts

@@ -16,6 +16,7 @@
 
 import type { Message, Model } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import * as path from "node:path";
 import {
   createAgentSession,
   createExtensionRuntime,
@@ -115,6 +116,8 @@ export interface SubAgentResult {
   model?: string;
   stopReason?: string;
   errorMessage?: string;
+  /** Unified diff of changes made in an isolated worktree (sandbox: "worktree"). */
+  patch?: string;
   /** Canonical result status (added in 0.6.0). */
   status?: SubagentStatus;
 }
@@ -135,6 +138,8 @@ export async function runSubAgent(options: {
   task: string;
   tools: string[];
   model: Model<any>;
+  /** "worktree" runs the child in an isolated git worktree; the resulting diff is returned as result.patch. */
+  sandbox?: "worktree";
   /** Pi 0.80.10's canonical credential/model runtime. */
   modelRuntime?: unknown;
   /** Legacy Pi SDK session options retained for 0.80.6 tests and hosts. */
@@ -147,6 +152,8 @@ export async function runSubAgent(options: {
   onProgress?: (progress: SubAgentProgress) => void;
   timeoutMs?: number;
   hardTimeoutMs?: number;
+  /** Exec used for the git worktree lifecycle (add/remove/diff). Defaults to a child_process spawn when unset. */
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>;
   /**
    * When true, build a DefaultResourceLoader so the child inherits the parent's
    * extensions (and thus extension tools: web, serena, munin, …). When false or
@@ -164,7 +171,7 @@ export async function runSubAgent(options: {
     cwd, systemPrompt, task, tools, model, modelRuntime, authStorage, modelRegistry, signal,
     agentName = "subagent", thinkingLevel = "off", onMessage, onProgress,
     timeoutMs = DEFAULT_INACTIVITY_TIMEOUT_MS, hardTimeoutMs = HARD_TIMEOUT_MS,
-    loadExtensions = false, projectTrusted = true,
+    loadExtensions = false, projectTrusted = true, sandbox, exec,
   } = options;
   const result: SubAgentResult = {
     agent: agentName, task, exitCode: 0, messages: [], stderr: "",
@@ -210,12 +217,36 @@ export async function runSubAgent(options: {
       result.status = classifyStopReason(result.stopReason, !timedOut, timedOut);
       return result;
     }
-    const { session } = await createAgentSession({
-      cwd, model, thinkingLevel, resourceLoader, tools, sessionManager: SessionManager.inMemory(cwd), settingsManager,
-      ...(modelRuntime ? { modelRuntime } : {}),
-      // Pi 0.80.10 owns credentials in ModelRuntime; older SDKs still accept these.
-      ...(authStorage ? { authStorage, modelRegistry } : {}),
-    } as any);
+
+    // Isolated git worktree: the child edits a sibling checkout; the resulting
+    // diff is returned as result.patch and the worktree is removed on exit.
+    // ponytail: falls back to the in-process cwd when git is unavailable — the
+    // worktree is an isolation optimization, not a hard requirement.
+    let worktreeDir: string | undefined;
+    let childCwd = cwd;
+    if (sandbox === "worktree") {
+      const wt = await createWorktree(cwd, exec);
+      if (wt.ok) {
+        worktreeDir = wt.path;
+        childCwd = wt.path!;
+      } else if (wt.error) {
+        result.stderr = `Worktree unavailable (${wt.error}); running in workspace.`;
+      }
+    }
+
+    let session: Awaited<ReturnType<typeof createAgentSession>>["session"];
+    try {
+      const created = await createAgentSession({
+        cwd: childCwd, model, thinkingLevel, resourceLoader, tools, sessionManager: SessionManager.inMemory(childCwd), settingsManager,
+        ...(modelRuntime ? { modelRuntime } : {}),
+        // Pi 0.80.10 owns credentials in ModelRuntime; older SDKs still accept these.
+        ...(authStorage ? { authStorage, modelRegistry } : {}),
+      } as any);
+      session = created.session;
+    } catch (error) {
+      if (worktreeDir) await removeWorktree(cwd, worktreeDir, exec);
+      throw error;
+    }
     let unsubscribe: (() => void) | undefined;
     let removeAbort: (() => void) | undefined;
     try {
@@ -257,10 +288,17 @@ export async function runSubAgent(options: {
       else if (combinedSignal.aborted) { result.stopReason = "aborted"; result.errorMessage ||= "Sub-agent aborted"; }
       result.status = classifyStopReason(result.stopReason, result.stopReason === "aborted", result.stopReason === "timeout");
       result.exitCode = result.status === "success" || result.status === "partial" ? 0 : 1;
+      if (worktreeDir) {
+        // Capture the child's changes as a unified diff before tearing down.
+        const diff = await captureWorktreeDiff(cwd, worktreeDir, exec);
+        if (diff.ok) result.patch = diff.diff;
+        else if (diff.error) result.stderr = result.stderr ? `${result.stderr}; diff unavailable (${diff.error})` : `Diff unavailable (${diff.error})`;
+      }
       return result;
     } finally {
       unsubscribe?.(); removeAbort?.();
       try { session.dispose(); } catch { /* best effort */ }
+      if (worktreeDir) await removeWorktree(cwd, worktreeDir, exec);
     }
   } catch (error) {
     result.exitCode = 1;
@@ -277,6 +315,88 @@ export async function runSubAgent(options: {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Minimal exec fallback (child_process spawn) used when no exec is injected. */
+async function defaultExec(
+  command: string,
+  args: string[],
+  options?: { cwd?: string; timeout?: number },
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd: options?.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    // Decode each chunk as a complete UTF-8 stream (Buffer.toString per chunk
+    // would corrupt multi-byte sequences straddling chunk boundaries).
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    let stdout = ""; let stderr = "";
+    const timer = options?.timeout ? setTimeout(() => child.kill("SIGKILL"), options.timeout) : undefined;
+    child.stdout.on("data", (d) => { stdout += d; });
+    child.stderr.on("data", (d) => { stderr += d; });
+    child.on("error", (err) => { if (timer) clearTimeout(timer); resolve({ code: 1, stdout, stderr: String(err.message ?? err) }); });
+    child.on("close", (code) => { if (timer) clearTimeout(timer); resolve({ code: code ?? 1, stdout, stderr }); });
+  });
+}
+
+async function runGit(
+  cwd: string,
+  args: string[],
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  const run = exec ?? defaultExec;
+  const res = await run("git", args, { cwd, timeout: 30_000 });
+  return { ok: res.code === 0, stdout: res.stdout, stderr: res.stderr };
+}
+
+/** Create a detached git worktree at .pi-worktrees/<rand> under the repo root. */
+export async function createWorktree(
+  cwd: string,
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<{ ok: boolean; path?: string; error?: string }> {
+  try {
+    const root = await runGit(cwd, ["rev-parse", "--show-toplevel"], exec);
+    if (!root.ok) return { ok: false, error: root.stderr.trim() || "not a git repo" };
+    const repoRoot = root.stdout.trim();
+    if (!repoRoot) return { ok: false, error: "empty git root" };
+    const id = `pi-subagent-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const wtPath = path.join(repoRoot, ".pi-worktrees", id);
+    const add = await runGit(repoRoot, ["worktree", "add", "--detach", wtPath, "HEAD"], exec);
+    if (!add.ok) return { ok: false, error: add.stderr.trim() || "git worktree add failed" };
+    return { ok: true, path: wtPath };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Unified diff of ALL changes in the worktree vs HEAD (tracked edits, staged
+ *  changes, AND new untracked files). Stages first so untracked files are
+ *  captured — the worktree is removed right after, so mutating its index is
+ *  safe. A single `diff --cached HEAD` avoids duplicate hunks from combining
+ *  `diff HEAD` + `diff --cached`. */
+export async function captureWorktreeDiff(
+  repoRoot: string,
+  worktreeDir: string,
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<{ ok: boolean; diff?: string; error?: string }> {
+  const add = await runGit(worktreeDir, ["add", "-A"], exec);
+  if (!add.ok) return { ok: false, error: add.stderr.trim() || "git add -A failed" };
+  const diff = await runGit(worktreeDir, ["diff", "--cached", "HEAD"], exec);
+  if (!diff.ok) return { ok: false, error: diff.stderr.trim() || "git diff --cached HEAD failed" };
+  const text = diff.stdout.trim();
+  return { ok: true, diff: text || "(no changes)" };
+}
+
+/** Remove a worktree and its metadata, best-effort. */
+export async function removeWorktree(
+  repoRoot: string,
+  worktreeDir: string,
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<void> {
+  try {
+    await runGit(repoRoot, ["worktree", "remove", "--force", worktreeDir], exec);
+  } catch { /* best effort */ }
+}
+
+
 export function getFinalOutput(messages: Message[]): string {
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];

package/extensions/service.ts

@@ -117,6 +117,7 @@ export async function runNamedAgent(options: {
 
     const result = await runSubAgent({
       cwd: safeCwd.path,
+      sandbox: options.agent.sandbox === "worktree" ? "worktree" : undefined,
       systemPrompt: contract ? `${options.agent.systemPrompt}\n\n## Task Contract\n${contract}` : options.agent.systemPrompt,
       task: options.task,
       tools: toolValidation.tools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",
@@ -56,17 +56,17 @@
     "check": "npm run typecheck && npm test"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.84.0",
-    "@earendil-works/pi-ai": ">=0.80.0 <0.84.0",
-    "@earendil-works/pi-agent-core": ">=0.80.0 <0.84.0",
-    "@earendil-works/pi-tui": ">=0.80.0 <0.84.0",
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.85.0",
+    "@earendil-works/pi-ai": ">=0.80.0 <0.85.0",
+    "@earendil-works/pi-agent-core": ">=0.80.0 <0.85.0",
+    "@earendil-works/pi-tui": ">=0.80.0 <0.85.0",
     "typebox": ">=1.3.0 <2.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.83.0",
-    "@earendil-works/pi-ai": "^0.83.0",
-    "@earendil-works/pi-coding-agent": "^0.83.0",
-    "@earendil-works/pi-tui": "^0.83.0",
+    "@earendil-works/pi-agent-core": "^0.84.0",
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
     "@types/mocha": "^10.0.10",
     "@types/node": "^20.19.43",
     "mocha": "^10.8.2",