pi-code 1.0.16 → 1.0.18

package/README.md

@@ -45,7 +45,7 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 | 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` |
-| 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); 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` |
+| 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` |
 | Settings `env` | `env` blocks from `managed-settings.json`, `~/.claude/settings.json`, and the project `.claude/settings.json`/`settings.local.json` exported into the session (per-key `managed > user > project`); the project scope is approval-gated (a repo's env can redirect providers), a shell `export` outranks user and project but a managed key overrides even that, and a key an approved project set is unset once a later session no longer defines it | `env-settings.ts` |

package/extensions/hooks/claude-tools.ts

@@ -0,0 +1,132 @@
+/**
+ * Claude-vocabulary translation for hook payloads on pi's built-in tools.
+ *
+ * Claude-written hook scripts branch on documented names ("Bash", "Edit") and read
+ * documented input shapes (`tool_input.file_path`); pi's tools carry their own
+ * names (`bash`, `edit`) and shapes (`path`, `edits[]`). Payloads report the
+ * Claude form, exactly as MCP aliases and user_bash already do, and the decision
+ * outputs that reference input/output shapes (`updatedInput`, `updatedToolOutput`)
+ * are translated back. Mappings against pi's schemas in
+ * node_modules/@earendil-works/pi-coding-agent/dist/core/tools and Claude's hooks
+ * reference (per-tool input tables, PostToolUse response shapes).
+ *
+ * Translation choices the shapes force, each documented on its function:
+ * - pi's multi-entry `edits[]` maps to Claude's single Edit with the first entry in
+ *   `old_string`/`new_string` and the full array carried alongside as `edits`.
+ * - Bash `timeout` converts between pi's seconds and Claude's milliseconds.
+ * - pi's bash output is one combined stream, so the Bash response reports it all as
+ *   `stdout` with an empty `stderr`.
+ */
+
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+/** pi built-in -> Claude tool name for hook payloads and matchers. MCP tools ride
+ * the alias bus instead; pi tools with no Claude counterpart (ls) stay untranslated. */
+const CLAUDE_NAMES: Record<string, string> = { bash: 'Bash', edit: 'Edit', write: 'Write', read: 'Read', grep: 'Grep', find: 'Glob' }
+
+export function claudeToolName(piName: string): string | undefined {
+  return CLAUDE_NAMES[piName]
+}
+
+/** Claude file-tool paths are always absolute with `~` expanded before hooks run,
+ * so a path guard cannot be bypassed by a relative or `~` spelling of the same path. */
+function absolutePath(value: unknown, cwd: string): unknown {
+  if (typeof value !== 'string' || value.length === 0) return value
+  const expanded = value === '~' || value.startsWith('~/') ? path.join(os.homedir(), value.slice(1)) : value
+  return path.resolve(cwd, expanded)
+}
+
+const record = (value: unknown): Record<string, unknown> | undefined => (value !== null && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined)
+
+/** Only the entries whose value passes the filter, so optional fields stay absent
+ * rather than arriving as explicit undefined. */
+function pick(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined))
+}
+
+type InputMapper = (raw: Record<string, unknown>, cwd: string) => Record<string, unknown>
+
+const TO_CLAUDE_INPUT: Record<string, InputMapper> = {
+  // pi timeout is seconds, Claude's is milliseconds.
+  bash: (raw) => pick({ command: raw.command, timeout: typeof raw.timeout === 'number' ? raw.timeout * 1000 : undefined }),
+  write: (raw, cwd) => ({ file_path: absolutePath(raw.path, cwd), content: raw.content }),
+  read: (raw, cwd) => pick({ file_path: absolutePath(raw.path, cwd), offset: raw.offset, limit: raw.limit }),
+  // Claude's Edit is a single replacement; pi's edit call carries one or more. The
+  // documented fields expose the first entry, and the full array rides along as
+  // `edits` so a hook auditing the whole call loses nothing.
+  edit: (raw, cwd) => {
+    const edits = Array.isArray(raw.edits) ? raw.edits : []
+    const first = record(edits[0]) ?? {}
+    return { file_path: absolutePath(raw.path, cwd), old_string: first.oldText ?? '', new_string: first.newText ?? '', replace_all: false, ...(edits.length > 1 ? { edits } : {}) }
+  },
+  grep: (raw, cwd) => pick({ pattern: raw.pattern, path: raw.path === undefined ? undefined : absolutePath(raw.path, cwd), glob: raw.glob, '-i': raw.ignoreCase === true ? true : undefined }),
+  find: (raw, cwd) => pick({ pattern: raw.pattern, path: raw.path === undefined ? undefined : absolutePath(raw.path, cwd) }),
+}
+
+/** pi input -> Claude `tool_input` for the translated built-ins; undefined keeps the
+ * pi shape (MCP and unknown tools). */
+export function claudeToolInput(piName: string, input: unknown, cwd: string): Record<string, unknown> | undefined {
+  const raw = record(input)
+  if (!raw) return undefined
+  return TO_CLAUDE_INPUT[piName]?.(raw, cwd)
+}
+
+type RewriteMapper = (updated: Record<string, unknown>) => Record<string, unknown> | undefined
+
+const FROM_CLAUDE_INPUT: Record<string, RewriteMapper> = {
+  bash: (updated) => (typeof updated.command === 'string' ? pick({ command: updated.command, timeout: typeof updated.timeout === 'number' ? updated.timeout / 1000 : undefined }) : undefined),
+  write: (updated) => (typeof updated.file_path === 'string' && typeof updated.content === 'string' ? { path: updated.file_path, content: updated.content } : undefined),
+  read: (updated) => (typeof updated.file_path === 'string' ? pick({ path: updated.file_path, offset: updated.offset, limit: updated.limit }) : undefined),
+  edit: (updated) => {
+    if (typeof updated.file_path !== 'string') return undefined
+    if (Array.isArray(updated.edits)) return { path: updated.file_path, edits: updated.edits }
+    if (typeof updated.old_string !== 'string' || typeof updated.new_string !== 'string') return undefined
+    return { path: updated.file_path, edits: [{ oldText: updated.old_string, newText: updated.new_string }] }
+  },
+  grep: (updated) => (typeof updated.pattern === 'string' ? pick({ pattern: updated.pattern, path: updated.path, glob: updated.glob, ignoreCase: updated['-i'] === true ? true : undefined }) : undefined),
+  find: (updated) => (typeof updated.pattern === 'string' ? pick({ pattern: updated.pattern, path: updated.path }) : undefined),
+}
+
+/** Claude-shaped `updatedInput` back into pi's input shape for a translated tool.
+ * Returns undefined when the rewrite is missing the tool's required fields, so the
+ * caller keeps the ORIGINAL input rather than handing pi a corrupted one; for an
+ * untranslated tool the caller applies the rewrite verbatim. Claude's Edit
+ * `replace_all` has no pi counterpart (pi requires a unique oldText) and is dropped. */
+export function piToolInput(piName: string, updated: Record<string, unknown>): Record<string, unknown> | undefined {
+  return FROM_CLAUDE_INPUT[piName]?.(updated)
+}
+
+/** pi result -> Claude `tool_response` where the docs pin a shape: Bash's structured
+ * object (pi's single combined stream reported as stdout) and Write's
+ * `{filePath, success}`. Other tools keep pi's `{content, details, isError}`. */
+export function claudeToolResponse(piName: string, input: unknown, text: string, isError: boolean, cwd: string): Record<string, unknown> | undefined {
+  const raw = record(input)
+  switch (piName) {
+    case 'bash':
+      return { stdout: text, stderr: '', interrupted: false, isImage: false }
+    case 'write':
+      return { filePath: absolutePath(raw?.path, cwd), success: !isError }
+    default:
+      return undefined
+  }
+}
+
+/** A hook's `updatedToolOutput` back into pi text content. Claude validates built-in
+ * replacements against the tool's output schema and ignores mismatches (returns
+ * undefined here, keeping the original); MCP output passes through unvalidated. */
+export function piToolOutput(piName: string, value: unknown, isMcp: boolean): string | undefined {
+  if (isMcp) {
+    if (typeof value === 'string') return value
+    return value === undefined ? undefined : JSON.stringify(value)
+  }
+  if (piName === 'bash') {
+    const raw = record(value)
+    if (!raw || typeof raw.stdout !== 'string') return undefined
+    const stderr = typeof raw.stderr === 'string' && raw.stderr.length > 0 ? `\n${raw.stderr}` : ''
+    return `${raw.stdout}${stderr}`
+  }
+  // pi's other tool outputs are text content, so a string replacement is
+  // shape-valid; a structured value has no pi counterpart and is ignored.
+  return typeof value === 'string' ? value : undefined
+}

package/extensions/hooks/config.ts

@@ -25,6 +25,9 @@ export interface HookCommand {
    * the next turn, and any still running are killed at session end. */
   async?: boolean
   asyncRewake?: boolean
+  /** Claude's permission-rule filter (`"Bash(git *)"`, `"Edit(*.ts)"`): evaluated only
+   * on tool events; on any other event a hook carrying `if` never runs. */
+  if?: string
   /** http entries: the endpoint POSTed to; `command` mirrors it for dedup and display. */
   url?: string
   headers?: Record<string, string>

package/extensions/hooks/decisions.ts

@@ -5,8 +5,10 @@
  */
 
 import type { ToolCallEventResult } from '@earendil-works/pi-coding-agent'
+import type { PathAnchors } from '../internal/path-rules.js'
+import { claudeToolInput, claudeToolName, piToolInput } from './claude-tools.js'
 import { type HookCommand, type HooksConfig, isRecord } from './config.js'
-import { matchingCommands } from './matcher.js'
+import { allCommands, matchingCommands, passesIfFilter } from './matcher.js'
 import { type HookRunner, type HookRunResult, timeoutMs } from './runners.js'
 
 export interface HookDecision {
@@ -17,7 +19,19 @@ export interface HookDecision {
   ask?: boolean
 }
 
-export function tryParseJson(text: string): { hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string; additionalContext?: string; updatedInput?: unknown }; decision?: string; reason?: string; continue?: boolean; stopReason?: string; systemMessage?: string } | undefined {
+export function tryParseJson(text: string):
+  | {
+      hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string; additionalContext?: string; updatedInput?: unknown }
+      decision?: string
+      reason?: string
+      continue?: boolean
+      stopReason?: string
+      systemMessage?: string
+      updatedToolOutput?: unknown
+      updatedMCPToolOutput?: unknown
+      ok?: boolean
+    }
+  | undefined {
   try {
     return JSON.parse(text)
   } catch {
@@ -25,16 +39,42 @@ export function tryParseJson(text: string): { hookSpecificOutput?: { permissionD
   }
 }
 
+/** The reason a JSON body's blocking decision carries, whichever spelling made it. */
+function jsonBlockingReason(parsed: ReturnType<typeof tryParseJson>): string | undefined {
+  if (parsed?.hookSpecificOutput?.permissionDecision === 'deny') return parsed.hookSpecificOutput.permissionDecisionReason
+  if (parsed?.decision === 'block') return parsed.reason
+  if (parsed?.continue === false) return parsed.stopReason
+  return undefined
+}
+
+/** A blocking verdict in any of the JSON spellings a hook can answer with: the
+ * command-hook fields, and the prompt/agent reply schemas (`permissionDecision:
+ * "deny"` from pi's prompt-hook system prompt, `ok: false` from Claude's documented
+ * prompt-hook response). Undefined when the body renders no block. */
+export function jsonBlockVerdict(parsed: ReturnType<typeof tryParseJson>, fallback: string): { reason: string } | undefined {
+  if (parsed?.decision === 'block') return { reason: parsed.reason ?? fallback }
+  if (parsed?.hookSpecificOutput?.permissionDecision === 'deny') return { reason: parsed.hookSpecificOutput.permissionDecisionReason ?? fallback }
+  if (parsed?.ok === false) return { reason: parsed.reason ?? fallback }
+  return undefined
+}
+
 /** Map a hook's exit code / output to a block-or-allow decision. */
 export function interpretHookResult(code: number, stdout: string, stderr: string): HookDecision {
-  if (code === 2) return { block: true, reason: stderr.trim() || 'Blocked by hook' }
   const parsed = tryParseJson(stdout)
+  // Claude: on exit 2 the blocking message is the JSON blocking decision's reason
+  // when it makes one, and the stderr text otherwise.
+  if (code === 2) return { block: true, reason: jsonBlockingReason(parsed) ?? (stderr.trim() || 'Blocked by hook') }
   const specific = parsed?.hookSpecificOutput
   // Claude's "ask" prompts the user; the tool_call handler turns this into a
   // ctx.ui.confirm and blocks only on decline. block:true is the fallback for a
   // headless run with no dialog to show, which is the safe reading on a gated path.
   if (specific?.permissionDecision === 'ask') return { block: true, ask: true, reason: specific.permissionDecisionReason ?? 'A hook asks you to confirm this tool call.' }
   if (specific?.permissionDecision === 'deny') return { block: true, reason: specific.permissionDecisionReason ?? 'Blocked by hook' }
+  // Claude's "defer" exits gracefully so the tool can be resumed later; pi cannot
+  // resume a deferred call, so running it now would invert the intent. The block
+  // carries its own explanation (the hook's reason is ignored for defer, as
+  // documented).
+  if (specific?.permissionDecision === 'defer') return { block: true, reason: 'Tool call deferred by hook; pi cannot resume a deferred call, so it was not run.' }
   if (parsed?.decision === 'block') return { block: true, reason: parsed.reason ?? 'Blocked by hook' }
   if (parsed?.continue === false) return { block: true, reason: parsed.stopReason ?? 'Blocked by hook' }
   return { block: false }
@@ -57,36 +97,80 @@ function surfaceHookFailures(commands: HookCommand[], results: HookRunResult[],
   }
 }
 
+/** What PreToolUse resolved to: the decision, plus any additionalContext strings
+ * the hooks contributed, delivered alongside the eventual tool result. */
+export interface PreToolUseOutcome extends HookDecision {
+  context?: string[]
+}
+
 /** Run PreToolUse hooks for a tool, in parallel as Claude does; the first blocking
- * verdict in config order wins. For MCP tools the matcher sees both the pi name and
- * the Claude alias, and the payload reports the alias, which is the name a
- * Claude-written hook script expects in tool_name. Every hook sees the original
- * tool input; hookSpecificOutput.updatedInput replaces the input in place as each
- * hook completes, so with several rewrites the last to finish takes effect (the
- * docs leave multi-rewrite ordering unspecified). */
-export async function runPreToolUse(config: HooksConfig, toolName: string, toolInput: unknown, runner: HookRunner, claudeName?: string, onSystemMessage?: SystemMessageSink): Promise<HookDecision> {
-  const names = claudeName ? [toolName, claudeName] : [toolName]
-  const commands = matchingCommands(config.PreToolUse, names)
-  const results = await Promise.all(
-    commands.map((command) =>
-      runner(command, { hook_event_name: 'PreToolUse', tool_name: claudeName ?? toolName, tool_input: toolInput }, timeoutMs(command)).then((result) => {
-        const updated = tryParseJson(result.stdout)?.hookSpecificOutput?.updatedInput
-        if (isRecord(updated) && isRecord(toolInput)) replaceRecord(toolInput, updated)
-        return result
-      }),
-    ),
-  )
-  surfaceHookFailures(commands, results, onSystemMessage)
+ * verdict in config order wins. The payload reports the Claude vocabulary: the MCP
+ * alias for MCP tools, and the documented name and tool_input shape for pi's
+ * built-ins (see claude-tools). Every hook sees the original tool input;
+ * hookSpecificOutput.updatedInput replaces the input in place as each hook
+ * completes, translated back to the pi shape for a built-in (an incomplete rewrite
+ * keeps the original input rather than corrupting it), so with several rewrites
+ * the last to finish takes effect (the docs leave multi-rewrite ordering
+ * unspecified). */
+/** Apply a hook's updatedInput rewrite in place, translating a built-in rewrite
+ * back to the pi shape; an incomplete built-in rewrite keeps the original input
+ * rather than corrupting it. */
+function applyUpdatedInput(toolName: string, toolInput: unknown, translated: boolean, stdout: string): void {
+  const updated = tryParseJson(stdout)?.hookSpecificOutput?.updatedInput
+  if (!isRecord(updated) || !isRecord(toolInput)) return
+  const replacement = translated ? piToolInput(toolName, updated) : updated
+  if (replacement) replaceRecord(toolInput, replacement)
+}
+
+/** The fail-closed scan for the gated events: a timed-out or never-spawned hook
+ * reached no verdict, and its silence must not read as an allow. */
+function failClosedVerdict(commands: HookCommand[], results: HookRunResult[]): HookDecision | undefined {
   for (const [i, result] of results.entries()) {
-    // A killed hook never reached its verdict, and SIGKILL leaves a null exit code that
-    // would otherwise read as a clean allow. Fail closed instead.
+    // A killed hook never reached its verdict, and SIGKILL leaves a null exit code
+    // that would otherwise read as a clean allow.
     if (result.timedOut) return { block: true, reason: `Hook timed out after ${timeoutMs(commands[i])}ms: ${commands[i].command}` }
     // A hook that never spawned (EMFILE, missing /bin/sh) reached no verdict either;
     // its code 0 must fail closed like a timeout, not read as an allow exactly when
     // the machine is degraded.
     if (result.spawnFailed) return { block: true, reason: `Hook failed to run: ${commands[i].command}: ${result.stderr.trim() || 'unknown error'}` }
   }
+  return undefined
+}
+
+/** additionalContext strings the PreToolUse hooks contributed; delivered alongside
+ * the tool result, so a deferring hook's context is discarded, as Claude documents. */
+function preToolContexts(results: HookRunResult[]): string[] {
+  return results.flatMap((result) => {
+    const parsed = tryParseJson(result.stdout)
+    if (parsed?.hookSpecificOutput?.permissionDecision === 'defer') return []
+    const text = parsed?.hookSpecificOutput?.additionalContext
+    return typeof text === 'string' && text.length > 0 ? [text] : []
+  })
+}
+
+export async function runPreToolUse(config: HooksConfig, toolName: string, toolInput: unknown, runner: HookRunner, claudeName?: string, onSystemMessage?: SystemMessageSink, anchors?: PathAnchors): Promise<PreToolUseOutcome> {
+  const cwd = anchors?.cwd ?? process.cwd()
+  const translatedName = claudeName ?? claudeToolName(toolName)
+  // A built-in's payload input is the translated Claude shape; MCP and unknown
+  // tools keep the pi shape (MCP input passes through untranslated in Claude too).
+  const translatedInput = claudeName === undefined ? claudeToolInput(toolName, toolInput, cwd) : undefined
+  const names = translatedName ? [toolName, translatedName] : [toolName]
+  const target = anchors ? { piName: toolName, claudeName: translatedName, input: toolInput, anchors } : undefined
+  const commands = matchingCommands(config.PreToolUse, names).filter((command) => passesIfFilter(command, target))
+  const payload = { hook_event_name: 'PreToolUse', tool_name: translatedName ?? toolName, tool_input: translatedInput ?? toolInput }
+  const results = await Promise.all(
+    commands.map((command) =>
+      runner(command, payload, timeoutMs(command)).then((result) => {
+        applyUpdatedInput(toolName, toolInput, translatedInput !== undefined, result.stdout)
+        return result
+      }),
+    ),
+  )
+  surfaceHookFailures(commands, results, onSystemMessage)
+  const failClosed = failClosedVerdict(commands, results)
+  if (failClosed) return failClosed
   if (onSystemMessage) surfaceSystemMessages(results, onSystemMessage)
+  const context = preToolContexts(results)
   // A hard deny wins over an ask, matching Claude's deny > ask > allow precedence:
   // scan for any deny first, and only fall back to the first ask.
   let ask: HookDecision | undefined
@@ -95,7 +179,7 @@ export async function runPreToolUse(config: HooksConfig, toolName: string, toolI
     if (decision.block && !decision.ask) return decision
     if (decision.ask && ask === undefined) ask = decision
   }
-  return ask ?? { block: false }
+  return ask ?? { block: false, context: context.length > 0 ? context : undefined }
 }
 
 type SystemMessageSink = (message: string) => void
@@ -124,9 +208,10 @@ export function promptContext(stdout: string): string {
 
 /** Run UserPromptSubmit hooks, in parallel as Claude does: the first blocking
  * verdict in config order wins; otherwise their additional context is concatenated
- * in config order for injection ahead of the prompt. */
+ * in config order for injection ahead of the prompt. The event has no matcher
+ * support (a stray matcher is ignored) and an `if`-carrying hook never runs here. */
 export async function runUserPromptSubmit(config: HooksConfig, prompt: string, runner: HookRunner, onSystemMessage?: SystemMessageSink): Promise<PromptDecision> {
-  const commands = matchingCommands(config.UserPromptSubmit, 'UserPromptSubmit')
+  const commands = allCommands(config.UserPromptSubmit).filter((command) => passesIfFilter(command, undefined))
   const results = await Promise.all(commands.map((command) => runner(command, { hook_event_name: 'UserPromptSubmit', prompt }, timeoutMs(command))))
   surfaceHookFailures(commands, results, onSystemMessage)
   for (const [i, result] of results.entries()) {
@@ -155,7 +240,12 @@ export function postToolFeedback(result: HookRunResult, eventName: string, isErr
   // A failed tool cannot be blocked, but the hook's stderr is still shown; on
   // success, exit-2 / decision:block feed back as a block notice.
   if (!result.timedOut && result.code === 2) lines.push(`${eventName} hook: ${result.stderr.trim() || (isError ? 'hook reported an error' : 'Blocked by hook')}`)
-  else if (!isError && parsed?.decision === 'block') lines.push(`PostToolUse hook: ${parsed.reason ?? 'Blocked by hook'}`)
+  else if (!isError) {
+    // Any JSON blocking spelling feeds back, including the prompt/agent hook reply
+    // schemas (permissionDecision deny, ok:false), which arrive as stdout here.
+    const verdict = jsonBlockVerdict(parsed, 'Blocked by hook')
+    if (verdict) lines.push(`PostToolUse hook: ${verdict.reason}`)
+  }
   const context = parsed?.hookSpecificOutput?.additionalContext
   if (context) lines.push(context)
   return lines

package/extensions/hooks/index.ts

@@ -39,6 +39,17 @@
  * InstructionsLoaded) ignore it, as Claude documents for them.
  * `suppressOutput` is accepted and inert: pi never echoes hook stdout to the
  * transcript in the first place.
+ * Payloads speak Claude's vocabulary for pi's built-in tools: tool_name Bash/Edit/
+ * Write/Read/Grep/Glob, the documented tool_input shapes with absolute file_path,
+ * and the documented Bash/Write tool_response shapes, with `updatedInput`
+ * translated back to pi's shape (see claude-tools; an incomplete rewrite keeps
+ * the original input). PreToolUse `additionalContext` lands next to the tool
+ * result; `updatedToolOutput` replaces the output the model sees (schema-checked
+ * for built-ins, unvalidated for MCP); `permissionDecision: "defer"` blocks the
+ * call, since pi cannot resume a deferred one. The `if` permission-rule filter is
+ * honored on tool events, and a hook carrying it never runs elsewhere; Stop and
+ * UserPromptSubmit ignore a stray matcher, and a Stop hook's `additionalContext`
+ * continues the conversation under the same block cap.
  * `async`/`asyncRewake` (command hooks only, as Claude documents) run in the
  * background on every event: they never block or delay the event that fired them
  * and render no decision. An asyncRewake hook exiting 2 wakes the model with its
@@ -80,9 +91,10 @@ import { installedPlugins } from '../internal/plugins.js'
 import { isProjectApproved } from '../internal/project-approval.js'
 import { repoRoot } from '../internal/project-root.js'
 import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
+import { claudeToolInput, claudeToolName, claudeToolResponse, piToolOutput } from './claude-tools.js'
 import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, isBackgroundHook, loadHooks, loadPluginHooks, readAllowedHttpHookUrls, readDisableAllHooks } from './config.js'
-import { blockedToolCall, postToolFeedback, promptContext, runPreToolUse, runUserPromptSubmit, surfaceSystemMessages, tryParseJson } from './decisions.js'
-import { matchingCommands } from './matcher.js'
+import { blockedToolCall, jsonBlockVerdict, postToolFeedback, promptContext, runPreToolUse, runUserPromptSubmit, surfaceSystemMessages, tryParseJson } from './decisions.js'
+import { allCommands, matchingCommands, passesIfFilter } from './matcher.js'
 import { type HookRunner, type HookRunResult, runAgentHook, runHookCommand, runHttpHook, runMcpToolHook, runPromptHook, timeoutMs } from './runners.js'
 
 export * from './config.js'
@@ -122,7 +134,17 @@ export function stopHookBlockCap(env: Record<string, string | undefined> = proce
 }
 
 async function runNotifyHooks(commands: HookCommand[], payload: unknown, runner: HookRunner): Promise<HookRunResult[]> {
-  return await Promise.all(commands.map((command) => runner(command, payload, timeoutMs(command))))
+  // Non-tool events: a hook carrying `if` never runs, as Claude documents.
+  const runnable = commands.filter((command) => passesIfFilter(command, undefined))
+  return await Promise.all(runnable.map((command) => runner(command, payload, timeoutMs(command))))
+}
+
+/** The text of a result's content blocks, for Claude-shaped tool_response fields. */
+function textContent(content: ReadonlyArray<{ type: string; text?: string }>): string {
+  return content
+    .filter((block) => block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('\n')
 }
 
 /** pi's lifecycle vocabularies differ from Claude's documented ones. The matcher is
@@ -153,6 +175,8 @@ export default function hooksExtension(pi: ExtensionAPI) {
   let hooksDisabled = false
   /** Which settings file each resolved entry came from, for the /hooks viewer. */
   const hookSources = new Map<HookMatcher, string>()
+  /** PreToolUse additionalContext per tool call, delivered alongside its result. */
+  const pendingToolContext = new Map<string, string[]>()
   /** Claude sends session_id, transcript_path, cwd and effort on every payload. */
   const commonPayload = (ctx: ExtensionContext): Record<string, unknown> => {
     const common: Record<string, unknown> = { session_id: ctx.sessionManager.getSessionId(), cwd: ctx.cwd, permission_mode: permissionMode }
@@ -280,6 +304,7 @@ export default function hooksExtension(pi: ExtensionAPI) {
     // carry into the next session, so reset before any early return (disableAllHooks below).
     stopHookActive = false
     stopHookBlockCount = 0
+    pendingToolContext.clear()
     const trusted = await isProjectApproved(ctx)
     // Claude's CLAUDE_PROJECT_DIR is the project root, not the session cwd; a hook
     // referencing $CLAUDE_PROJECT_DIR/.claude/hooks/helper.sh must resolve from a
@@ -325,8 +350,14 @@ export default function hooksExtension(pi: ExtensionAPI) {
   })
 
   pi.on('tool_call', async (event, ctx) => {
-    const decision = await runPreToolUse(config, event.toolName, event.input, boundRunner(ctx, { tool_use_id: event.toolCallId }), mcpAliases.get(event.toolName), (message) => ctx.ui.notify(message, 'warning'))
-    if (!decision.block) return undefined
+    const anchors = { cwd: ctx.cwd, projectRoot: projectDir || ctx.cwd, home: os.homedir() }
+    const decision = await runPreToolUse(config, event.toolName, event.input, boundRunner(ctx, { tool_use_id: event.toolCallId }), mcpAliases.get(event.toolName), (message) => ctx.ui.notify(message, 'warning'), anchors)
+    if (!decision.block) {
+      // additionalContext is delivered alongside the tool result, so stash it for
+      // this call's tool_result to append.
+      if (decision.context && decision.context.length > 0) pendingToolContext.set(event.toolCallId, decision.context)
+      return undefined
+    }
     // Claude's "ask": prompt the user and let the call through if they approve.
     // With no UI (headless) the block stands, which is the safe default.
     if (decision.ask && ctx.hasUI) {
@@ -341,20 +372,45 @@ export default function hooksExtension(pi: ExtensionAPI) {
   // stderr) and additionalContext are appended, which is where Claude documents they
   // land. The failure branch shows the hook's stderr to the model too ("Shows stderr
   // to Claude; the tool already failed"), it just cannot block a call that failed.
+  // Payloads report the Claude vocabulary (names, input shapes, and the documented
+  // Bash/Write response shapes; see claude-tools), and a schema-valid
+  // updatedToolOutput replaces the output the model sees.
   pi.on('tool_result', async (event, ctx) => {
     const alias = mcpAliases.get(event.toolName)
-    const names = alias ? [event.toolName, alias] : [event.toolName]
-    const response = { content: event.content, details: event.details, isError: event.isError }
+    const translatedName = alias ?? claudeToolName(event.toolName)
+    const names = translatedName ? [event.toolName, translatedName] : [event.toolName]
     const eventName = event.isError ? 'PostToolUseFailure' : 'PostToolUse'
-    const commands = matchingCommands(event.isError ? config.PostToolUseFailure : config.PostToolUse, names)
-    if (commands.length === 0) return
-    const payload = { hook_event_name: eventName, tool_name: alias ?? event.toolName, tool_input: event.input, tool_response: response }
+    // Contexts stashed by this call's PreToolUse hooks land next to the result even
+    // when no PostToolUse hook is configured.
+    const pending = pendingToolContext.get(event.toolCallId) ?? []
+    pendingToolContext.delete(event.toolCallId)
+    const anchors = { cwd: ctx.cwd, projectRoot: projectDir || ctx.cwd, home: os.homedir() }
+    const target = { piName: event.toolName, claudeName: translatedName, input: event.input, anchors }
+    const commands = matchingCommands(event.isError ? config.PostToolUseFailure : config.PostToolUse, names).filter((command) => passesIfFilter(command, target))
+    if (commands.length === 0 && pending.length === 0) return
+    const translatedInput = alias === undefined ? claudeToolInput(event.toolName, event.input, ctx.cwd) : undefined
+    const response = (alias === undefined && !event.isError ? claudeToolResponse(event.toolName, event.input, textContent(event.content), event.isError, ctx.cwd) : undefined) ?? { content: event.content, details: event.details, isError: event.isError }
+    const payload = { hook_event_name: eventName, tool_name: translatedName ?? event.toolName, tool_input: translatedInput ?? event.input, tool_response: response }
     const run = boundRunner(ctx, { tool_use_id: event.toolCallId })
     const results = await Promise.all(commands.map((command) => run(command, payload, timeoutMs(command))))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
-    const feedback = results.flatMap((result) => postToolFeedback(result, eventName, event.isError))
-    if (feedback.length === 0) return
-    return { content: [...event.content, ...feedback.map((text) => ({ type: 'text' as const, text }))] }
+    // Claude's updatedToolOutput replaces the output the model sees; a value that
+    // doesn't match the tool's output schema is ignored, MCP output passes through
+    // unvalidated, and a failed call keeps its error output.
+    const replacement = event.isError
+      ? undefined
+      : results
+          .filter((result) => !result.timedOut)
+          .map((result) => {
+            const parsed = tryParseJson(result.stdout)
+            const value = alias !== undefined ? (parsed?.updatedMCPToolOutput ?? parsed?.updatedToolOutput) : parsed?.updatedToolOutput
+            return value === undefined ? undefined : piToolOutput(event.toolName, value, alias !== undefined)
+          })
+          .find((text) => text !== undefined)
+    const feedback = [...pending, ...results.flatMap((result) => postToolFeedback(result, eventName, event.isError))]
+    if (replacement === undefined && feedback.length === 0) return
+    const base = replacement !== undefined ? [{ type: 'text' as const, text: replacement }] : event.content
+    return { content: [...base, ...feedback.map((text) => ({ type: 'text' as const, text }))] }
   })
 
   // Claude's PreToolUse for Bash, extended to a command the user runs directly with the
@@ -370,7 +426,7 @@ export default function hooksExtension(pi: ExtensionAPI) {
   // no execution result and fires only before the command runs, so there is deliberately
   // no PostToolUse for it.
   pi.on('user_bash', async (event, ctx) => {
-    const decision = await runPreToolUse(config, 'bash', { command: event.command }, boundRunner(ctx), 'Bash', (message) => ctx.ui.notify(message, 'warning'))
+    const decision = await runPreToolUse(config, 'bash', { command: event.command }, boundRunner(ctx), 'Bash', (message) => ctx.ui.notify(message, 'warning'), { cwd: ctx.cwd, projectRoot: projectDir || ctx.cwd, home: os.homedir() })
     if (!decision.block) return undefined
     // Claude's "ask": prompt before running and let the command through on approval; with
     // no UI (headless) the block stands, the same safe default as the tool_call path.
@@ -420,7 +476,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
       void runNotifyHooks(notifyCommands, { hook_event_name: 'Notification', notification_type: 'idle_prompt', message: 'pi is waiting for your input' }, boundRunner(ctx)).catch(() => {})
     }
 
-    const commands = matchingCommands(config.Stop, 'Stop')
+    // Stop has no matcher support (a stray matcher is ignored, as Claude documents)
+    // and an `if`-carrying hook never runs on a non-tool event.
+    const commands = allCommands(config.Stop).filter((command) => passesIfFilter(command, undefined))
     if (commands.length === 0) {
       stopHookActive = false
       return
@@ -435,9 +493,18 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const block = results
       .filter((result) => !result.timedOut)
       .map((result) => {
-        if (result.code === 2) return { block: true, reason: result.stderr.trim() || 'Stop blocked by hook' }
         const parsed = tryParseJson(result.stdout)
-        if (parsed?.decision === 'block') return { block: true, reason: parsed.reason ?? 'Stop blocked by hook' }
+        if (result.code === 2) return { block: true, reason: jsonBlockVerdict(parsed, 'Stop blocked by hook')?.reason ?? (result.stderr.trim() || 'Stop blocked by hook') }
+        // Any JSON blocking spelling counts, including the prompt/agent hook reply
+        // schemas (permissionDecision deny, ok:false), which arrive as stdout here.
+        const verdict = jsonBlockVerdict(parsed, 'Stop blocked by hook')
+        if (verdict) return { block: true, reason: verdict.reason }
+        // Claude's non-error continue: additionalContext feeds back and the
+        // conversation continues so Claude can act on it. It rides the same
+        // continuation path (and the same block cap) so a hook emitting it every
+        // firing cannot loop the turn forever.
+        const context = parsed?.hookSpecificOutput?.additionalContext
+        if (typeof context === 'string' && context.length > 0) return { block: true, reason: context }
         return { block: false, reason: '' }
       })
       .find((verdict) => verdict.block)

package/extensions/hooks/matcher.ts

@@ -4,6 +4,8 @@
  * commands an event fires. Owns the module-level compiled-matcher cache.
  */
 
+import { matchesBashRules } from '../internal/bash-rules.js'
+import { matchesPathRules, type PathAnchors } from '../internal/path-rules.js'
 import type { HookCommand, HookMatcher } from './config.js'
 
 /** Claude's rule: a matcher of only letters, digits, `_`, `-`, spaces, `,` and `|`
@@ -106,14 +108,11 @@ function withCommand(raw: HookCommand): HookCommand {
   return identity !== undefined && typeof raw.command !== 'string' ? { ...raw, command: identity } : raw
 }
 
-/** Command specs whose matcher applies to any of the given tool/source names.
- * Multiple candidates let one event offer both the pi name and its Claude alias. */
-export function matchingCommands(matchers: HookMatcher[] | undefined, names: string | readonly string[]): HookCommand[] {
-  const candidates = typeof names === 'string' ? [names] : names
+function collectCommands(matchers: HookMatcher[] | undefined, applies: (entry: HookMatcher) => boolean): HookCommand[] {
   const result: HookCommand[] = []
   const seen = new Set<string>()
   for (const entry of matchers ?? []) {
-    if (!matcherApplies(entry.matcher, candidates)) continue
+    if (!applies(entry)) continue
     for (const raw of (entry.hooks ?? []).filter(isRunnableHook)) {
       const hook = withCommand(raw)
       // Claude runs a handler defined in more than one settings file once.
@@ -124,3 +123,53 @@ export function matchingCommands(matchers: HookMatcher[] | undefined, names: str
   }
   return result
 }
+
+/** Command specs whose matcher applies to any of the given tool/source names.
+ * Multiple candidates let one event offer both the pi name and its Claude alias. */
+export function matchingCommands(matchers: HookMatcher[] | undefined, names: string | readonly string[]): HookCommand[] {
+  const candidates = typeof names === 'string' ? [names] : names
+  return collectCommands(matchers, (entry) => matcherApplies(entry.matcher, candidates))
+}
+
+/** Command specs for an event without matcher support (Stop, UserPromptSubmit): a
+ * stray `matcher` on such an event is silently ignored, as Claude documents, so
+ * every entry's hooks run. */
+export function allCommands(matchers: HookMatcher[] | undefined): HookCommand[] {
+  return collectCommands(matchers, () => true)
+}
+
+/** The tool call an `if` filter evaluates against; absent on non-tool events. */
+export interface IfFilterTarget {
+  piName: string
+  claudeName?: string
+  input: unknown
+  anchors: PathAnchors
+}
+
+/** Claude's `if` handler field: permission-rule syntax evaluated only on tool
+ * events; on any other event a hook carrying `if` never runs. A bare tool name
+ * matches by name; `Bash(pattern)` evaluates against the command via the shared
+ * bash-rule matcher and file-tool patterns against the path via the shared
+ * permission path rules. A pattern for any other tool matches nothing, which is
+ * also what an unparseable rule does. */
+export function passesIfFilter(hook: HookCommand, target: IfFilterTarget | undefined): boolean {
+  if (hook.if === undefined) return true
+  if (target === undefined) return false
+  const parsed = /^([A-Za-z_|]+?)(?:\((.*)\))?$/.exec(hook.if.trim())
+  if (!parsed) return false
+  const fold = (name: string): string => name.toLowerCase().replaceAll('-', '_')
+  const ruleTools = new Set(parsed[1].split('|').map(fold))
+  const toolMatches = ruleTools.has(fold(target.piName)) || (target.claudeName !== undefined && ruleTools.has(fold(target.claudeName)))
+  if (!toolMatches) return false
+  const pattern = parsed[2]
+  if (pattern === undefined) return true
+  const input = target.input as Record<string, unknown> | null
+  if (fold(target.piName) === 'bash' || (target.claudeName !== undefined && fold(target.claudeName) === 'bash')) {
+    const command = typeof input?.command === 'string' ? input.command : ''
+    return command.length > 0 && matchesBashRules(command, [pattern])
+  }
+  let filePath = ''
+  if (typeof input?.path === 'string') filePath = input.path
+  else if (typeof input?.file_path === 'string') filePath = input.file_path
+  return filePath.length > 0 && matchesPathRules(filePath, [pattern], target.anchors)
+}

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.16",
+  "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",