pi-code 1.0.17 → 1.0.19

package/README.md

@@ -44,7 +44,7 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 | Global + project rules | `~/.claude/rules`, `.claude/rules` (nearest at or above cwd); unscoped rules inlined in full, `paths:`-scoped rules surfaced as pointers and auto-attached (the rule body is appended to a read/edit/write result when a matching file is touched, once per rule per session) | `claude-rules.ts` |
 | Custom slash commands | `.claude/commands/**/*.md` (namespaced `/dir:name`); `$ARGUMENTS` (with the `ARGUMENTS:` append when unused), 0-based `$ARGUMENTS[N]`/`$N`, named `arguments:` frontmatter, `${CLAUDE_SESSION_ID}`/`${CLAUDE_EFFORT}`/`${CLAUDE_SKILL_DIR}`/`${CLAUDE_PROJECT_DIR}` (in bodies and `allowed-tools` rules); `` !`cmd` `` and multi-line ```` ```! ```` bash (whitespace-bounded, merged stderr, 2-minute budget, a failure aborts the invocation with the documented exit-1 carveout), `@file` inlining; `allowed-tools` with `Bash(...)` and `Read`/`Edit`/`Write` path scopes enforced at call time (gitignore anchors, Edit governs writes), `disallowed-tools`, `argument-hint`, `model` (switches the session model for the command's turn, restored after), `effort` (raises reasoning for the turn, restored after), `shell: powershell` (injected spans run through PowerShell when a `pwsh` binary is present, else `/bin/sh`); the model can also run a command itself through the `SlashCommand` tool (Claude's `SlashCommand` in `allowed-tools`), steered by `when_to_use` and opted out per file with `disable-model-invocation` (`user-invocable: false` hides a command from the menu while still exposing it to the model); `disableSkillShellExecution` (managed and user always, project when trusted) replaces every `!` span with a policy-disabled placeholder; project commands gated on approval | `commands.ts` |
 | `/init` | generates a project context file: detects an existing `AGENTS.md`/`CLAUDE.md` (proposes improvements) or none (creates `AGENTS.md`, pi's preferred name), ingesting `.cursor/rules`, `.cursorrules`, and `.github/copilot-instructions.md` when present; drives the main agent with full tools via a prompt (not a tool-less completion) so it analyzes the codebase and writes the file itself | `init.ts` |
-| Skills | `.claude/skills` → pi skill discovery, project skills gated on approval (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.ts` |
+| Skills | `.claude/skills` → pi skill discovery, project skills gated on approval (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader); invoking `/skill:name` expands the body through the command pipeline, as Claude documents commands and skills "work the same way": `` !`cmd` `` spans, `@file` references, `$ARGUMENTS`/positional substitution and `${CLAUDE_*}` variables, with a malformed-frontmatter skill degrading to pi's plain expansion | `skills.ts` |
 | Hooks | `.claude/settings.json` hooks: PreToolUse (blocks, rewrites input via `updatedInput`), PostToolUse (feedback and `additionalContext` land next to the tool result), PostToolUseFailure, SessionStart (context injection), UserPromptSubmit (blocks and injects context), Stop (a block continues the conversation), SubagentStart/SubagentStop, PreCompact, PostCompact, SessionEnd, Notification (idle_prompt, the type pi can source), InstructionsLoaded (observational: fires per loaded context file at session start, plus `path_glob_match` on a scoped-rule attach and `include` per resolved `@import`; deduped per session; `nested_traversal`/`compact` reasons never fire since pi does not lazily load nested CLAUDE.md or reload after compaction); `type: http` entries POST the payload (a 2xx JSON body renders the decision, everything else is non-blocking per Claude's contract), `type: prompt` evaluates in-process against the session model, `type: mcp_tool` calls a connected server's tool, and `type: agent` (experimental) spawns a read-only Read/Grep/Glob subagent that returns the JSON decision (a missing model/server/runner is non-blocking, only a PreToolUse timeout fails closed); Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort; `permissionDecision: "ask"` prompts via a confirm dialog (blocks when headless), SubagentStop/PostToolUseFailure are notify-only, and a timed-out PreToolUse/UserPromptSubmit hook fails closed at a 60s default (Claude: 600s for PreToolUse, 30s for UserPromptSubmit, both non-blocking) since pi has no permission backstop; `async`/`asyncRewake` command hooks run in the background on every event (never blocking, no decision, no timeout enforced on `async` while asyncRewake keeps its own; an asyncRewake exit 2 wakes the model with the hook's stderr as a new turn, other completions deliver `systemMessage`/`additionalContext` to the model on the next turn, and hooks still running at session end are killed); payloads use Claude's vocabulary for pi's built-ins (Bash/Edit/Write/Read/Grep/Glob names, documented input and Bash/Write response shapes, absolute `file_path`, `updatedInput` translated back); PreToolUse `additionalContext` lands beside the tool result, `updatedToolOutput`/`updatedMCPToolOutput` replace what the model sees, `permissionDecision: "defer"` blocks (pi cannot resume a deferred call), the `if` permission-rule filter runs on tool events only (a hook carrying it never runs elsewhere), Stop/UserPromptSubmit ignore stray matchers, and a Stop hook's `additionalContext` continues the conversation under the block cap; a `command` hook may use exec form (`command` as an argv array, run with no shell) and executes with `CLAUDECODE=1` and `CLAUDE_PROJECT_DIR` set; a user-typed `!`/`!!` bash line runs PreToolUse (there is no PostToolUse for it); `type: http` targets are gated by `allowedHttpHookUrls` (union of managed and settings scopes; unset allows all, `[]` blocks every http hook); a Stop hook may block at most 8 times before the turn ends (`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`); `disableAllHooks` in any scope turns the system off; `/hooks` prints the resolved configuration | `hooks.ts` |
 | Output styles | `.claude/output-styles` + active `outputStyle`; plus styles shipped by enabled plugins (manifest `outputStyles`, default `output-styles/`, ranked below the user's and project's own); Claude replace semantics with `keep-coding-instructions`; bundled Explanatory/Learning/Proactive; `/output-style [name]` | `output-styles.ts` |
 | CLAUDE.md `@imports` and rewriting | resolves `@path` imports pi's native loader skips (4-hop depth, budget-capped); loads the user `~/.claude/CLAUDE.md` and the project `.claude/CLAUDE.md` (approval-gated, deduped against the repo-root `CLAUDE.md`/`AGENTS.md` pi loads natively) that pi's own loader does not; loads every `CLAUDE.local.md` from the repo root down to cwd (approval-gated, root first); injects the managed `CLAUDE.md` (a per-OS file beside `managed-settings.json`) and the `claudeMd` string from `managed-settings.json` at the top of context (managed content is never excludable); honors `claudeMdExcludes` (glob/absolute-path skip list from user, approved-project, and managed settings, merged; managed content never excluded); strips block-level HTML comments from CLAUDE.md, rule, and imported bodies (fenced-code comments preserved), so a commented-out `@import` does not expand; with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` set, loads `CLAUDE.md`/`.claude/CLAUDE.md`/`.claude/rules/*.md`/`CLAUDE.local.md` from each `--add-dir` directory (comma-separated for several, since pi's flag is single-value) | `context-imports.ts` |

package/extensions/skills.ts

@@ -7,14 +7,25 @@
  * pi implements the Agent Skills standard, so `SKILL.md` directories work
  * unchanged and register as `/skill:name`.
  *
+ * Claude documents that a command file and a skill "work the same way", so a
+ * SKILL.md body carries the dynamic features command bodies do: `` !`cmd` ``
+ * spans, `@file` references, `$ARGUMENTS`/positional substitution and
+ * `${CLAUDE_*}` variables. pi's loader delivers the raw text, so this extension
+ * intercepts `/skill:name` input for the skills it contributed, expands the body
+ * through the shared command pipeline, and hands pi the already-expanded content
+ * in pi's own skill-block format (pi emits the input event before its own
+ * expansion, and skips text that no longer starts with `/`).
+ *
  * Docs: https://code.claude.com/docs/en/skills.md, https://agentskills.io
  */
 
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { type ExtensionAPI, type ExtensionContext, parseFrontmatter } from '@earendil-works/pi-coding-agent'
 
+import { expandCommand, shellExecutionDisabled } from './commands.js'
+import { parseCommandFile } from './internal/command-file.js'
 import { claudeConfigDir } from './internal/config-dir.js'
 import { installedPlugins } from './internal/plugins.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
@@ -28,7 +39,6 @@ function isDirectory(target: string): boolean {
   }
 }
 
-/** Existing `.claude/skills` directories, user first then project. */
 /** Existing `.claude/skills` directories, user first then project. The project
  * directory is included only for approved projects: pi's loader surfaces every skill's
  * name and description to the model, so an untrusted repository would otherwise get
@@ -51,6 +61,50 @@ export function skillDirs(cwd: string, home: string, trusted: boolean): string[]
   return dirs
 }
 
+interface FoundSkill {
+  filePath: string
+  baseDir: string
+}
+
+/** The skill a directory entry holds, named as pi's loader names it (frontmatter
+ * `name`, else the directory name); undefined without a readable SKILL.md. */
+function skillAt(root: string, dirName: string): { name: string; filePath: string } | undefined {
+  const filePath = path.join(root, dirName, 'SKILL.md')
+  let content: string
+  try {
+    content = fs.readFileSync(filePath, 'utf-8')
+  } catch {
+    return undefined
+  }
+  let name = dirName
+  try {
+    const declared = parseFrontmatter<Record<string, unknown>>(content).frontmatter.name
+    if (typeof declared === 'string' && declared.trim()) name = declared.trim()
+  } catch {
+    // Malformed frontmatter: pi's loader falls back to the directory name too.
+  }
+  return { name, filePath }
+}
+
+/** A Claude-contributed skill by the name pi's loader gives it. One directory
+ * level, the standard layout. */
+export function findClaudeSkill(name: string, roots: string[]): FoundSkill | undefined {
+  for (const root of roots) {
+    let entries: fs.Dirent[]
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const skill = skillAt(root, entry.name)
+      if (skill?.name === name) return { filePath: skill.filePath, baseDir: path.dirname(skill.filePath) }
+    }
+  }
+  return undefined
+}
+
 export default function skillsExtension(pi: ExtensionAPI) {
   pi.on('resources_discover', async (_event, ctx) => {
     // resources_discover fires after session_start, so the approval is already
@@ -58,4 +112,38 @@ export default function skillsExtension(pi: ExtensionAPI) {
     const skillPaths = skillDirs(ctx.cwd, os.homedir(), isProjectApprovedSilently(ctx))
     return skillPaths.length > 0 ? { skillPaths } : undefined
   })
+
+  // The dynamic-content shim: only for skills this extension contributed; pi's own
+  // `.pi/skills` (or an unknown name) pass through to pi's plain expansion.
+  pi.on('input', async (event, ctx) => {
+    if (event.source === 'extension') return
+    return expandSkillInvocation(pi, event.text, ctx)
+  })
+}
+
+/** A `/skill:name args` invocation into its expanded skill block, or undefined to
+ * pass the input through to pi untouched. The expanded body is wrapped in pi's
+ * skill-block format so downstream behavior (the baseDir note for relative
+ * references) matches an untouched invocation. */
+async function expandSkillInvocation(pi: ExtensionAPI, rawText: string, ctx: ExtensionContext): Promise<{ action: 'transform'; text: string } | undefined> {
+  const text = rawText.trimStart()
+  if (!text.startsWith('/skill:')) return
+  const space = text.indexOf(' ')
+  const name = (space === -1 ? text.slice(7) : text.slice(7, space)).trim()
+  const args = space === -1 ? '' : text.slice(space + 1).trim()
+  if (!name) return
+  const trusted = isProjectApprovedSilently(ctx)
+  const found = findClaudeSkill(name, skillDirs(ctx.cwd, os.homedir(), trusted))
+  if (!found) return
+  let parsed: ReturnType<typeof parseCommandFile>
+  try {
+    parsed = parseCommandFile(fs.readFileSync(found.filePath, 'utf-8'))
+  } catch {
+    // Unreadable, or malformed frontmatter: pass through to pi's plain expansion
+    // (the loader registered the skill and delivers the raw body), rather than
+    // failing the invocation over the dynamic features it cannot have.
+    return
+  }
+  const expanded = await expandCommand(pi, parsed, args, { cwd: ctx.cwd }, found.filePath, undefined, { allowShell: !shellExecutionDisabled(ctx.cwd, os.homedir(), trusted) })
+  return { action: 'transform', text: `<skill name="${name}" location="${found.filePath}">\nReferences are relative to ${found.baseDir}.\n\n${expanded}\n</skill>` }
 }

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