pi-code 1.0.17 → 1.0.18

package/extensions/subagent/README.md

@@ -123,7 +123,14 @@ Fields with no pi seam are ignored, each verified against pi's CLI rather than
 assumed: `mcpServers` (a child reads MCP config from files, and writing config
 into the workspace to fake it would be worse than the gap). `maxTurns` and
 `memory` are honored (turn cap enforced at the turn boundary; per-agent memory
-directories injected into the child's prompt).
+directories injected into the child's prompt). `isolation: worktree` is honored:
+the child runs in a temporary git worktree branched from the repository's default
+branch, removed afterwards when the agent made no changes and reported in the
+run's output when kept; a run that cannot get its worktree fails rather than
+touching the real checkout, and an unrecognized `isolation` value rejects the
+definition. Divergence: pi sets the child's working directory into the worktree
+but does not police commands that navigate back out, which Claude additionally
+enforces per call.
 
 **Locations:**
 - `~/.claude/agents/*.md`, `~/.pi/agent/agents/*.md` - User-level (always loaded; `~/.pi` wins a name conflict)

package/extensions/subagent/agents.ts

@@ -179,6 +179,13 @@ function parseAgentFile(content: string, source: AgentSource, filePath: string):
   }
   const disallowedTools = parseToolsField(frontmatter.disallowedTools, false)
   if (disallowedTools === null) return null
+  const isolation = parseIsolationField(frontmatter.isolation)
+  if (isolation === null) {
+    // isolation is a declared safety boundary: an unrecognized value must reject
+    // the definition rather than run the agent against the real checkout.
+    console.warn(`pi-code-subagent: ignoring agent ${filePath}: isolation value ${JSON.stringify(frontmatter.isolation)} is not supported (only "worktree" is)`)
+    return null
+  }
   return {
     name,
     description,
@@ -190,12 +197,22 @@ function parseAgentFile(content: string, source: AgentSource, filePath: string):
     skills: parseSkillsField(frontmatter.skills),
     memory: parseMemoryField(frontmatter.memory),
     maxTurns: parseMaxTurns(frontmatter.maxTurns),
+    isolation,
     systemPrompt: body,
     source,
     filePath,
   }
 }
 
+/** Claude's `isolation:` field: `worktree` (case-insensitive) runs the child in a
+ * temporary git worktree. Absent is fine (undefined); any other value is null so
+ * the caller rejects the definition instead of silently dropping the boundary. */
+function parseIsolationField(raw: unknown): 'worktree' | undefined | null {
+  if (raw === undefined) return undefined
+  if (typeof raw === 'string' && raw.trim().toLowerCase() === 'worktree') return 'worktree'
+  return null
+}
+
 /** Claude's `maxTurns`: a positive integer cap on the subagent's agentic turns.
  * Anything else (0, negative, non-number) is ignored, so the run is uncapped. */
 function parseMaxTurns(raw: unknown): number | undefined {
@@ -219,6 +236,8 @@ export interface AgentConfig {
   memory?: AgentMemoryScope
   /** Cap on the child's agentic turns, enforced by killing at the turn boundary. */
   maxTurns?: number
+  /** Claude's `isolation: worktree`: run the child in a temporary git worktree. */
+  isolation?: 'worktree'
   systemPrompt: string
   source: AgentSource
   filePath: string

package/extensions/subagent/background.ts

@@ -166,12 +166,16 @@ export function backgroundRun(id: string): BackgroundRun | undefined {
 /** Re-spawn a finished run's session with a new task. The child is started with the
  * same --session-id, so it continues with everything it already saw rather than
  * re-deriving context the parent would have to repeat. */
-export function resumeBackgroundRun(id: string, task: string, onComplete: (run: BackgroundRun) => void): 'resumed' | 'still-running' | 'at-capacity' | 'unknown' {
+export function resumeBackgroundRun(id: string, task: string, onComplete: (run: BackgroundRun) => void): 'resumed' | 'still-running' | 'at-capacity' | 'cwd-gone' | 'unknown' {
   const run = runs.get(id)
   if (!run) return 'unknown'
   if (run.state === 'running' || run.live) return 'still-running'
   // A resume spawns a child like a fresh start does, so it counts against the cap.
   if (activeBackgroundRuns() >= MAX_BACKGROUND_RUNS) return 'at-capacity'
+  // A worktree-isolated run's directory is removed once the run ends without
+  // changes; a resume cannot re-enter it, and spawning in a missing cwd would
+  // only produce an opaque ENOENT.
+  if (!fs.existsSync(run.spawn.cwd)) return 'cwd-gone'
   // Persisted so the rebuild happens once: rebuilding per resume leaked one temp
   // prompt dir every follow-up.
   const rebuilt = withRebuiltPrompt(run.spawn)

package/extensions/subagent/index.ts

@@ -34,6 +34,7 @@ import { skillDirs } from '../skills.js'
 import { type AgentConfig, type AgentMemoryScope, type AgentScope, type AgentSource, discoverAgents, resolveModelAlias, withPreloadedSkills } from './agents.js'
 import { activeBackgroundRuns, type BackgroundRun, backgroundRun, backgroundStatusText, cancelAllBackgroundRuns, cancelBackgroundRun, MAX_BACKGROUND_RUNS, resumeBackgroundRun, startBackgroundRun } from './background.js'
 import { type DisplayItem, formatToolCall, formatUsageStats, getDisplayItems, getFinalOutput } from './render.js'
+import { type AgentWorktree, cleanupAgentWorktree, createAgentWorktree } from './worktree.js'
 
 // Re-exported so the render formatters stay importable from the subagent entry point,
 // where the tests and the tool itself have always reached for them.
@@ -158,6 +159,20 @@ interface RunAgentOptions {
 /** Publishes a child run's start/stop for the hooks extension's SubagentStart/Stop. */
 type SubagentPhaseSink = (phase: 'start' | 'stop', agentType: string, agentId: string) => void
 
+/** Tell the parent where a kept worktree lives: appended to the final assistant
+ * message so it rides the run's normal output; stderr when there is none. */
+function appendWorktreeNote(result: SingleResult, worktree: AgentWorktree): void {
+  const note = `[isolation: worktree kept at ${worktree.dir} (branch ${worktree.branch}); the agent's changes live there]`
+  for (let i = result.messages.length - 1; i >= 0; i--) {
+    const msg = result.messages[i]
+    if (msg.role === 'assistant') {
+      msg.content.push({ type: 'text', text: note })
+      return
+    }
+  }
+  result.stderr = result.stderr ? `${result.stderr}\n${note}` : note
+}
+
 async function runSingleAgent(options: RunAgentOptions): Promise<SingleResult> {
   const agent = options.agents.find((a) => a.name === options.agentName)
   if (!agent) return runSingleAgentInner(options)
@@ -189,6 +204,26 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
   }
 
   const runCwd = cwd ?? defaultCwd
+  // Claude's isolation: worktree gives the child an isolated copy of the repository.
+  // A boundary that cannot be created fails the run: running against the real
+  // checkout would silently drop the isolation the agent declared.
+  let worktree: AgentWorktree | undefined
+  if (agent.isolation === 'worktree') {
+    const created = await createAgentWorktree(runCwd, agent.name)
+    if ('error' in created) {
+      return {
+        agent: agentName,
+        agentSource: agent.source,
+        task,
+        exitCode: 1,
+        messages: [],
+        stderr: `isolation: worktree could not be created: ${created.error}`,
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+        step,
+      }
+    }
+    worktree = created
+  }
   // Project/local memory is anchored at the SESSION project (defaultCwd), not the
   // model-supplied runCwd: projectApproved gates the session's repo, so anchoring the
   // store on a different (possibly unapproved) cwd would inject that repo's memory as
@@ -238,7 +273,7 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
     const exitCode = await new Promise<number>((resolve) => {
       const invocation = getPiInvocation(args)
       const proc = spawn(invocation.command, invocation.args, {
-        cwd: runCwd,
+        cwd: worktree?.dir ?? runCwd,
         shell: false,
         stdio: ['ignore', 'pipe', 'pipe'],
         // Its own group, so an abort reaches grandchildren too: killing only the
@@ -337,6 +372,11 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
     if (wasAborted) throw new Error('Subagent was aborted')
     return currentResult
   } finally {
+    // Cleanup runs on abort too: it only removes a pristine worktree, so an
+    // interrupted agent's changes always survive.
+    if (worktree && (await cleanupAgentWorktree(runCwd, worktree)) === 'kept') {
+      appendWorktreeNote(currentResult, worktree)
+    }
     if (tmpPromptPath)
       try {
         fs.unlinkSync(tmpPromptPath)
@@ -430,6 +470,7 @@ export function resumeResultText(id: string, task: string | undefined, onComplet
   }
   if (outcome === 'still-running') return `Background run ${id} is still running; wait for it or cancel it first.`
   if (outcome === 'at-capacity') return `Background run cap reached (${MAX_BACKGROUND_RUNS} concurrent); wait for a run to finish before resuming ${id}.`
+  if (outcome === 'cwd-gone') return `Background run ${id} ran in a working directory that no longer exists (an isolation worktree is cleaned up after an unchanged run); start a new run instead.`
   return `Unknown background run: ${id}.\n\n${backgroundStatusText()}`
 }
 
@@ -708,6 +749,18 @@ async function runBackgroundMode(params: SubagentParamsStatic, context: Backgrou
     return backgroundCapResult(makeDetails)
   }
   const runCwd = params.cwd ?? defaultCwd
+  // The same isolation boundary as the foreground path: no worktree, no run.
+  let worktree: AgentWorktree | undefined
+  if (agent.isolation === 'worktree') {
+    const created = await createAgentWorktree(runCwd, agent.name)
+    if ('error' in created) {
+      return {
+        content: [{ type: 'text', text: `isolation: worktree could not be created for ${agent.name}: ${created.error}` }],
+        details: makeDetails('single')([]),
+      }
+    }
+    worktree = created
+  }
   // Anchor project/local memory at the session project (defaultCwd), which is the one
   // projectApproved gated; see the foreground path for why runCwd must not be used.
   const memorySection = agentMemoryPromptSection(agent, defaultCwd, projectApproved)
@@ -720,13 +773,32 @@ async function runBackgroundMode(params: SubagentParamsStatic, context: Backgrou
   }
   args.push(`Task: ${task}`)
   const invocation = getPiInvocation(args)
-  const id = startBackgroundRun(agent.name, task, { command: invocation.command, args: invocation.args, cwd: runCwd, promptBody: tmpPrompt ? promptBody : undefined, maxTurns: agent.maxTurns }, (run) => {
+  const id = startBackgroundRun(agent.name, task, { command: invocation.command, args: invocation.args, cwd: worktree?.dir ?? runCwd, promptBody: tmpPrompt ? promptBody : undefined, maxTurns: agent.maxTurns }, (run) => {
     removeTmpPrompt(tmpPrompt)
-    // Both calls throw once the session that started the run is disposed; driveRun
-    // catches for the whole callback, so neither can escape into the child's close
-    // listener and become an uncaughtException.
-    pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id })
-    pi.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
+    const finish = (): void => {
+      // Both calls throw once the session that started the run is disposed. driveRun's
+      // catch covers the synchronous path, but the worktree branch reaches here from an
+      // async continuation outside it, so the guard must live in finish itself.
+      try {
+        pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id })
+        pi.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
+      } catch {
+        // Session disposed after the run outlived it; nothing to notify.
+      }
+    }
+    if (!worktree) {
+      finish()
+      return
+    }
+    // Cleanup only removes a pristine worktree; a kept one is reported in the
+    // completion text so the parent knows where the changes live.
+    const keptWorktree = worktree
+    void cleanupAgentWorktree(runCwd, keptWorktree)
+      .then((outcome) => {
+        if (outcome === 'kept') run.output = `${run.output ?? ''}\n[isolation: worktree kept at ${keptWorktree.dir} (branch ${keptWorktree.branch}); the agent's changes live there]`.trim()
+      })
+      .catch(() => {})
+      .finally(finish)
   })
   if (id === null) {
     // Lost the cap race to a parallel batch: the atomic check inside startBackgroundRun refused.

package/extensions/subagent/worktree.ts

@@ -0,0 +1,83 @@
+/**
+ * Claude's subagent `isolation: worktree`: a temporary git worktree giving the
+ * child an isolated copy of the repository, branched from the repository's default
+ * branch (origin/HEAD, falling back to main/master, then the current HEAD) rather
+ * than the parent session's HEAD, and automatically cleaned up when the subagent
+ * makes no changes. Divergence, documented in the subagent README: pi sets the
+ * child's working directory into the worktree but does not police commands that
+ * navigate back out, which Claude additionally enforces per call.
+ */
+
+import { execFile } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { promisify } from 'node:util'
+
+const git = async (cwd: string, ...args: string[]): Promise<string> => {
+  const { stdout } = await promisify(execFile)('git', args, { cwd })
+  return stdout.trim()
+}
+
+export interface AgentWorktree {
+  dir: string
+  branch: string
+  /** The commit the worktree started from; unchanged HEAD plus a clean tree means
+   * the agent made no changes and the worktree can go. */
+  baseSha: string
+}
+
+async function defaultBranch(repoCwd: string): Promise<string> {
+  try {
+    return await git(repoCwd, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD')
+  } catch {
+    // No origin/HEAD (local-only repo, or never fetched): try the conventional names.
+  }
+  for (const name of ['main', 'master']) {
+    try {
+      await git(repoCwd, 'show-ref', '--verify', `refs/heads/${name}`)
+      return name
+    } catch {
+      // Not this one.
+    }
+  }
+  return 'HEAD'
+}
+
+/** Create the temporary worktree, or explain why it cannot exist (not a git
+ * repository, git failure): the caller must fail the run rather than silently
+ * dropping the isolation boundary the agent declared. */
+export async function createAgentWorktree(repoCwd: string, agentName: string): Promise<AgentWorktree | { error: string }> {
+  try {
+    await git(repoCwd, 'rev-parse', '--is-inside-work-tree')
+  } catch {
+    return { error: `${repoCwd} is not a git repository` }
+  }
+  const suffix = randomUUID().slice(0, 8)
+  const safeName = agentName.replace(/[^A-Za-z0-9_-]+/g, '-')
+  const dir = path.join(os.tmpdir(), `pi-agent-worktree-${safeName}-${suffix}`)
+  const branch = `agent/${safeName}-${suffix}`
+  try {
+    await git(repoCwd, 'worktree', 'add', '-b', branch, dir, await defaultBranch(repoCwd))
+    return { dir, branch, baseSha: await git(dir, 'rev-parse', 'HEAD') }
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/** Remove the worktree and its branch when the agent made no changes (clean tree,
+ * HEAD still at the base), as Claude documents; keep both otherwise so the changes
+ * survive for the parent to inspect. A cleanup that fails keeps the worktree:
+ * losing work is the only unacceptable outcome here. */
+export async function cleanupAgentWorktree(repoCwd: string, worktree: AgentWorktree): Promise<'removed' | 'kept'> {
+  try {
+    const status = await git(worktree.dir, 'status', '--porcelain')
+    const head = await git(worktree.dir, 'rev-parse', 'HEAD')
+    if (status.length > 0 || head !== worktree.baseSha) return 'kept'
+    await git(repoCwd, 'worktree', 'remove', worktree.dir)
+    await git(repoCwd, 'branch', '-D', worktree.branch)
+    return 'removed'
+  } catch {
+    return 'kept'
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Claude Code experience for the pi coding agent: reads your .claude config (rules, commands, skills, hooks, output styles, MCP servers, agents) and adds todo, checkpoints, memory, web, and subagents",
   "keywords": [
     "pi",