pi-code 1.0.15 → 1.0.17

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, 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/commands.ts

@@ -3,9 +3,10 @@
  *
  * Registers Claude Code's custom slash commands with pi directly, rather than
  * handing `.claude/commands` to pi's prompt-template loader. Owning registration
- * is what makes the rest of Claude's command contract reachable: namespaced
- * subdirectories (`frontend/build.md` is `/frontend:build`), `$ARGUMENTS` and
- * positional substitution, `` !`cmd` `` bash output, `@file` inlining, and the
+ * is what makes the rest of Claude's command contract reachable: `$ARGUMENTS` and
+ * positional substitution, `` !`cmd` `` bash output, `@file` inlining, subdirectory
+ * commands (registered as `/frontend:build`; current Claude docs name a command by
+ * file name alone, so the qualified form is a pi-code divergence), and the
  * `allowed-tools`, `argument-hint` and `model` frontmatter (`model` switches the
  * session model for the command's run via `pi.setModel`, restored on agent_end).
  * `shell: powershell` runs a command's injected spans through PowerShell when a

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, which
- * is Claude's documented (non-deterministic) behavior. */
-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

@@ -34,10 +34,22 @@
  *
  * Every payload carries session_id, transcript_path (pi's session file), cwd,
  * permission_mode (plan-mode state off the shared bus) and effort; tool events add
- * tool_use_id. Every event honors the universal `systemMessage` output (a
- * user-facing warning).
+ * tool_use_id. The universal `systemMessage` output (a user-facing warning) is
+ * honored on the decision-bearing events; the observational paths (Notification,
+ * 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
@@ -79,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'
@@ -111,15 +124,27 @@ export function lastAssistantText(messages: ReadonlyArray<{ role: string; conten
 const DEFAULT_STOP_HOOK_BLOCK_CAP = 8
 
 /** The consecutive-block cap for the Stop hook: CLAUDE_CODE_STOP_HOOK_BLOCK_CAP when it
- * is a positive integer, else the default. A non-positive or malformed value falls back
- * to the default rather than capping at zero (which would suppress the very first block). */
+ * is a positive integer, the documented "disable the cap" for 0 (unbounded, not a
+ * zero-cap that would suppress the very first block), else the default for a negative
+ * or malformed value. */
 export function stopHookBlockCap(env: Record<string, string | undefined> = process.env): number {
   const override = Number.parseInt(env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP ?? '', 10)
+  if (override === 0) return Number.POSITIVE_INFINITY
   return Number.isInteger(override) && override > 0 ? override : DEFAULT_STOP_HOOK_BLOCK_CAP
 }
 
 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
@@ -150,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 }
@@ -277,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
@@ -322,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) {
@@ -338,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
@@ -367,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.
@@ -417,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
@@ -432,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/hooks/runners.ts

@@ -11,11 +11,13 @@ import { callMcpTool } from '../internal/mcp-call.js'
 import { completeText } from '../internal/model-complete.js'
 import { type HookCommand, httpUrlAllowed, isBackgroundHook } from './config.js'
 
-// Claude defaults to 600s and lets a timed-out hook proceed; here a timed-out
-// PreToolUse or UserPromptSubmit hook fails closed (pi has no permission prompt
-// to fall back on), so ten minutes of default budget would wedge the turn for
-// ten minutes on a hung hook. Hooks that legitimately run long can raise their
-// own per-hook `timeout`.
+// Claude's defaults vary by type and event (600s for command/http/mcp_tool, 30s
+// for prompt, 60s for agent, lowered to 30s on UserPromptSubmit and to a shared
+// 1.5s budget on SessionEnd) and a timed-out hook proceeds; here one flat default
+// applies and a timed-out PreToolUse or UserPromptSubmit hook fails closed (pi
+// has no permission prompt to fall back on), so ten minutes of default budget
+// would wedge the turn on a hung hook. Hooks that legitimately run long can
+// raise their own per-hook `timeout`.
 const DEFAULT_TIMEOUT_S = 60
 
 export interface HookRunResult {

package/extensions/internal/command-file.ts

@@ -99,10 +99,12 @@ export function normalizeToolName(name: string): string {
 }
 
 /**
- * Entries are comma-separated, except a comma inside an argument scope belongs to the
- * scope: `Bash(cat, tail)` is one grant, not three. Splitting on every comma made the
- * fragments between them top-level entries, so a command naming only `Bash` came away
- * with pi's `edit` tool active.
+ * Entries are comma- or space-separated, as Claude documents ("a space- or
+ * comma-separated string, or a YAML list"), except a separator inside an argument
+ * scope belongs to the scope: `Bash(cat, tail)` and `Bash(git add *)` are one grant
+ * each. Splitting on every comma made the fragments between them top-level entries,
+ * so a command naming only `Bash` came away with pi's `edit` tool active; splitting
+ * on no spaces mangled the docs' own space-separated examples into one garbage rule.
  *
  * Scanned rather than matched with a regex: the pattern form is quadratic on an input
  * of unclosed parens, and a command file comes from the repository.
@@ -114,7 +116,7 @@ function toolEntries(raw: string): string[] {
   for (const ch of raw) {
     if (ch === '(') depth++
     else if (ch === ')') depth = Math.max(0, depth - 1)
-    if (ch === ',' && depth === 0) {
+    if ((ch === ',' || ch === ' ' || ch === '\t') && depth === 0) {
       entries.push(current)
       current = ''
     } else {

package/extensions/mcp/index.ts

@@ -41,10 +41,11 @@ import { setMcpToolCaller } from '../internal/mcp-call.js'
 import { capForContext } from '../internal/output-guard.js'
 import { installedPlugins } from '../internal/plugins.js'
 import { isProjectApproved, isProjectApprovedSilently } from '../internal/project-approval.js'
+import { claudeSettingsChain } from '../internal/settings-chain.js'
 import { loadConfigFrom, loadPluginServers, loadUserScope, projectConfigPaths, type ServerConfig, warnOnTypelessUrl } from './config.js'
 import { collectServerResourceEntries, listAllPrompts, listAllTools, type McpToolInfo, resourceServerFilter } from './listing.js'
 import { formatPromptCommandName, formatToolName, type McpContentBlock, type McpPromptInfo, mapContent, mapPromptArguments, normalizeSchema, promptMessageContent } from './mapping.js'
-import { applyServerPolicy, loadManagedMcpServers, mcpAllowDeny, projectServerPolicy, splitByPolicy } from './policy.js'
+import { applyServerPolicy, loadManagedMcpServers, type McpPolicy, mcpAllowDeny, projectServerPolicy, splitByPolicy } from './policy.js'
 import { type AuthUi, callRequestOptions, callTimeoutMs, connect, connectTimeoutMs, withTimeout } from './transport.js'
 
 export { managedSettingsPath, setManagedSettingsPath } from '../internal/managed-settings.js'
@@ -57,7 +58,7 @@ export type { McpToolInfo } from './listing.js'
 export type { McpPromptArgumentInfo, McpPromptInfo, ToolContent } from './mapping.js'
 export { capTotal, formatPromptCommandName, formatToolName, mapContent, mapPromptArguments, normalizeSchema, promptMessageContent } from './mapping.js'
 export type { ProjectServerPolicy } from './policy.js'
-export { applyServerPolicy, loadManagedMcpServers, managedMcpPath, mcpAllowDeny, projectServerPolicy, splitByPolicy } from './policy.js'
+export { applyServerPolicy, loadManagedMcpServers, type McpPolicy, type McpPolicyEntry, managedMcpPath, mcpAllowDeny, projectServerPolicy, splitByPolicy, urlPatternMatches } from './policy.js'
 export type { AuthUi } from './transport.js'
 export { parseHelperHeaders, resolveBearerToken } from './transport.js'
 
@@ -401,8 +402,8 @@ export default async function mcpExtension(pi: ExtensionAPI) {
    * connected client not in the managed set (delete it from the map first so the onclose
    * handler's guard sees it gone and does not overwrite the status, then close it
    * best-effort and mark it disabled), then connect only the managed servers. */
-  async function connectManagedExclusive(managed: Record<string, ServerConfig>, allowed: Set<string> | null, denied: Set<string>, authUi?: AuthUi): Promise<void> {
-    const managedServers = applyServerPolicy(managed, allowed, denied)
+  async function connectManagedExclusive(managed: Record<string, ServerConfig>, policy: McpPolicy, authUi?: AuthUi): Promise<void> {
+    const managedServers = applyServerPolicy(managed, policy)
     const managedNames = new Set(Object.keys(managedServers))
     for (const [name, client] of Array.from(clients.entries())) {
       if (managedNames.has(name)) continue
@@ -420,11 +421,11 @@ export default async function mcpExtension(pi: ExtensionAPI) {
    * factory: pi runs the factory for invocations that never start a session. Names still
    * connected are filtered out, so a later session start only retries servers that failed
    * or whose transport dropped, without duplicate-name warnings. */
-  async function connectNormalScopes(ctx: ExtensionContext, allowed: Set<string> | null, denied: Set<string>, authUi?: AuthUi): Promise<void> {
+  async function connectNormalScopes(ctx: ExtensionContext, policy: McpPolicy, authUi?: AuthUi): Promise<void> {
     // Plugin servers merge under the user scope (plugins are user-installed);
     // the user's own entry wins a name clash with a plugin's.
     const pluginServers = loadPluginServers(installedPlugins(os.homedir()))
-    const scoped = applyServerPolicy({ ...pluginServers, ...loadUserScope(os.homedir(), ctx.cwd) }, allowed, denied)
+    const scoped = applyServerPolicy({ ...pluginServers, ...loadUserScope(os.homedir(), ctx.cwd) }, policy)
     // Claude's precedence is project over user for a duplicate name. A project .mcp.json
     // server only outranks the user's own when it will actually connect (the user already
     // consented to it, or an approved project's), so a merely-present untrusted project
@@ -434,7 +435,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // The stored project decision, read without prompting: consent recorded inside
     // the project only counts once the project itself has been approved.
     const projectPolicy = projectServerPolicy(ctx.cwd, os.homedir(), isProjectApprovedSilently(ctx))
-    const { consented, gated } = splitByPolicy(applyServerPolicy(loadConfigFrom(projectConfigPaths(ctx.cwd)), allowed, denied), projectPolicy)
+    const { consented, gated } = splitByPolicy(applyServerPolicy(loadConfigFrom(projectConfigPaths(ctx.cwd)), policy), projectPolicy)
     const projectWinners = new Set(Object.keys(consented))
     const userServers = Object.fromEntries(Object.entries(scoped).filter(([name]) => !clients.has(name) && !projectWinners.has(name)))
     // The consented project servers carry no ordering dependency on the user scope:
@@ -462,8 +463,10 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // is why serverToolCount reads from `registered` to recover the true count here.
     status.clear()
     const authUi = authUiFor(ctx)
-    // The managed allow/deny lists filter every scope, including a managed-mcp.json set.
-    const { allowed, denied } = mcpAllowDeny()
+    // The allow/deny lists filter every scope, including a managed-mcp.json set. They
+    // merge from managed settings plus the trust-gated settings chain, as Claude
+    // documents (a repo's file counts only once the project is approved).
+    const policy = mcpAllowDeny(claudeSettingsChain(ctx.cwd, os.homedir(), isProjectApprovedSilently(ctx)))
     // managed-mcp.json (beside managed-settings.json) takes exclusive control when present:
     // only its servers load, and the user, project, and plugin scopes plus the whole
     // project-approval flow below are skipped. An empty map disables MCP entirely. An absent
@@ -471,9 +474,9 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // empty set (see loadManagedMcpServers).
     const managed = loadManagedMcpServers()
     if (managed !== null) {
-      await connectManagedExclusive(managed, allowed, denied, authUi)
+      await connectManagedExclusive(managed, policy, authUi)
     } else {
-      await connectNormalScopes(ctx, allowed, denied, authUi)
+      await connectNormalScopes(ctx, policy, authUi)
     }
 
     pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])

package/extensions/mcp/policy.ts

@@ -9,7 +9,7 @@ import * as path from 'node:path'
 import { claudeConfigDir } from '../internal/config-dir.js'
 import { managedSettingsFile } from '../internal/managed-settings.js'
 import { findNearestFile } from '../internal/project-root.js'
-import type { ServerConfig } from './config.js'
+import { interpolateEnv, type ServerConfig } from './config.js'
 
 export interface ProjectServerPolicy {
   disabled: Set<string>
@@ -60,31 +60,133 @@ export function splitByPolicy(candidates: Record<string, ServerConfig>, policy:
   return { consented, gated }
 }
 
-/** Claude's `allowedMcpServers`/`deniedMcpServers`, read from managed settings only
- * (not user or project settings, so a repo can neither widen nor narrow the policy),
- * applied globally to every server across scopes. Entries are `{ serverName }` objects
- * (bare strings tolerated). `allowed` is null when unset (no restriction); an empty
- * set is an explicit lockdown, as Claude documents (empty allow array = deny all). */
-export function mcpAllowDeny(managedFile: string = managedSettingsFile()): { allowed: Set<string> | null; denied: Set<string> } {
-  let settings: Record<string, unknown> = {}
-  try {
-    const parsed = JSON.parse(fs.readFileSync(managedFile, 'utf-8'))
-    if (parsed && typeof parsed === 'object') settings = parsed
-  } catch {
-    // No managed policy on this machine: no restriction.
-  }
-  const entryName = (entry: unknown): string | undefined => {
-    if (typeof entry === 'string') return entry
-    const serverName = (entry as { serverName?: unknown })?.serverName
-    return typeof serverName === 'string' ? serverName : undefined
+/** One allow/deny list entry, keyed by exactly one of Claude's three match kinds. */
+export interface McpPolicyEntry {
+  /** Exact user-assigned label; never expanded. */
+  serverName?: string
+  /** Remote server URL, exact or with `*` wildcards anywhere. */
+  serverUrl?: string
+  /** Exact command and arguments that start a stdio server. */
+  serverCommand?: string[]
+}
+
+export interface McpPolicy {
+  /** null when no honored scope sets allowedMcpServers: every server passing the denylist loads. */
+  allowed: McpPolicyEntry[] | null
+  denied: McpPolicyEntry[]
+}
+
+/** A raw list entry into its typed form. A bare string is a name (Claude tolerates it);
+ * an object is keyed serverUrl > serverCommand > serverName; anything else is dropped. */
+function parsePolicyEntry(entry: unknown): McpPolicyEntry | undefined {
+  if (typeof entry === 'string') return entry.length > 0 ? { serverName: entry } : undefined
+  if (entry === null || typeof entry !== 'object') return undefined
+  const { serverName, serverUrl, serverCommand } = entry as Record<string, unknown>
+  if (typeof serverUrl === 'string' && serverUrl.length > 0) return { serverUrl }
+  if (Array.isArray(serverCommand) && serverCommand.length > 0 && serverCommand.every((part): part is string => typeof part === 'string')) return { serverCommand: serverCommand as string[] }
+  if (typeof serverName === 'string' && serverName.length > 0) return { serverName }
+  return undefined
+}
+
+/** Claude's `allowedMcpServers`/`deniedMcpServers`. Both lists merge from every honored
+ * settings scope (the caller passes the trust-gated chain, so a repo's file counts only
+ * once the project is approved); managed `allowManagedMcpServersOnly: true` keeps only
+ * the managed allowlist, while the denylist always merges from every scope, as Claude
+ * documents. An allowlist `serverName` entry is limited to letters, numbers, hyphens and
+ * underscores (a denylist name accepts any non-empty string). `allowed` is null when no
+ * honored scope sets the key; an empty list is an explicit lockdown (deny all). */
+export function mcpAllowDeny(scopeFiles: string[] = [], managedFile: string = managedSettingsFile()): McpPolicy {
+  const read = (file: string): Record<string, unknown> => {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      return parsed && typeof parsed === 'object' ? parsed : {}
+    } catch {
+      // Missing or invalid file contributes no policy.
+      return {}
+    }
   }
-  const names = (value: unknown): string[] => (Array.isArray(value) ? value.map(entryName).filter((name): name is string => typeof name === 'string' && name.length > 0) : [])
+  const entries = (value: unknown): McpPolicyEntry[] => (Array.isArray(value) ? value.map(parsePolicyEntry).filter((entry): entry is McpPolicyEntry => entry !== undefined) : [])
+  const managed = read(managedFile)
+  const scopes = scopeFiles.map(read)
+  const allowSources = managed.allowManagedMcpServersOnly === true ? [managed] : [managed, ...scopes]
+  const allowSet = allowSources.some((settings) => Array.isArray(settings.allowedMcpServers))
   return {
-    allowed: Array.isArray(settings.allowedMcpServers) ? new Set(names(settings.allowedMcpServers)) : null,
-    denied: new Set(names(settings.deniedMcpServers)),
+    allowed: allowSet ? allowSources.flatMap((settings) => entries(settings.allowedMcpServers)).filter((entry) => entry.serverName === undefined || /^[A-Za-z0-9_-]+$/.test(entry.serverName)) : null,
+    denied: [managed, ...scopes].flatMap((settings) => entries(settings.deniedMcpServers)),
   }
 }
 
+/** `*` in a policy URL pattern matches any run of characters; everything else is literal. */
+function wildcardRegExp(pattern: string): RegExp {
+  const source = pattern
+    .split('*')
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`))
+    .join('.*')
+  return new RegExp(`^${source}$`)
+}
+
+/** Claude's URL pattern match: `*` anywhere including the scheme; the scheme/host/port
+ * part compares case-insensitively and ignores a trailing FQDN dot, the path stays
+ * case-sensitive, and a pattern with no path matches any path. */
+export function urlPatternMatches(pattern: string, url: string): boolean {
+  const split = (value: string): { pre: string; path: string | undefined } => {
+    const schemeEnd = value.indexOf('://')
+    const slash = value.indexOf('/', schemeEnd === -1 ? 0 : schemeEnd + 3)
+    if (slash === -1) return { pre: value, path: undefined }
+    return { pre: value.slice(0, slash), path: value.slice(slash) }
+  }
+  const pre = (value: string): string => value.toLowerCase().replace(/\.(?=:\d+$|$)/, '')
+  const patternParts = split(pattern)
+  const urlParts = split(url)
+  if (!wildcardRegExp(pre(patternParts.pre)).test(pre(urlParts.pre))) return false
+  if (patternParts.path === undefined) return true
+  return wildcardRegExp(patternParts.path).test(urlParts.path ?? '/')
+}
+
+const configUrl = (config: ServerConfig): string | undefined => (config as { url?: string }).url
+const configArgv = (config: ServerConfig): string[] | undefined => {
+  const command = (config as { command?: string }).command
+  if (typeof command !== 'string') return undefined
+  const args = (config as { args?: unknown }).args
+  return [command, ...(Array.isArray(args) ? args.filter((part): part is string => typeof part === 'string') : [])]
+}
+const argvEqual = (a: string[], b: string[]): boolean => a.length === b.length && a.every((part, i) => part === b[i])
+/** Policy-side expansion. Divergence from Claude, documented: Claude expands policy
+ * entries from a pinned startup environment; pi-code expands from the live process env.
+ * The deny path compensates by also matching the unexpanded forms (see entryMatches),
+ * which can only widen a deny, never weaken it. */
+const expand = (value: string): string => interpolateEnv(value)
+
+/** Whether one policy entry matches a server. `includeRawForms` is the deny-side rule:
+ * raw and expanded forms both count, so expansion drift can only widen a deny. The
+ * allow side matches expanded forms only, mirroring Claude ignoring an allow entry
+ * whose expansion would change what it means. */
+function entryMatches(entry: McpPolicyEntry, name: string, config: ServerConfig, includeRawForms: boolean): boolean {
+  if (entry.serverUrl !== undefined) {
+    const url = configUrl(config)
+    if (url === undefined) return false
+    return urlPatternMatches(expand(entry.serverUrl), expand(url)) || (includeRawForms && urlPatternMatches(entry.serverUrl, url))
+  }
+  if (entry.serverCommand !== undefined) {
+    const argv = configArgv(config)
+    if (argv === undefined) return false
+    return argvEqual(entry.serverCommand.map(expand), argv.map(expand)) || (includeRawForms && argvEqual(entry.serverCommand, argv))
+  }
+  return entry.serverName === name
+}
+
+/** Claude's allowlist rule per server type: a remote server must match a `serverUrl`
+ * entry and a stdio server a `serverCommand` entry; a `serverName` match counts only
+ * when the allowlist contains no typed entries for that transport. */
+function serverAllowed(name: string, config: ServerConfig, allowed: McpPolicyEntry[] | null): boolean {
+  if (allowed === null) return true
+  const remote = configUrl(config) !== undefined
+  const typed = allowed.filter((entry) => (remote ? entry.serverUrl !== undefined : entry.serverCommand !== undefined))
+  if (typed.some((entry) => entryMatches(entry, name, config, false))) return true
+  if (typed.length > 0) return false
+  return allowed.some((entry) => entry.serverName === name)
+}
+
 /** The managed-mcp.json path: a sibling of managed-settings.json (same directory). Derived
  * through the same test seam so a test can write both into one temp dir. */
 export function managedMcpPath(managedFile: string = managedSettingsFile()): string {
@@ -126,14 +228,14 @@ export function loadManagedMcpServers(managedFile: string = managedSettingsFile(
   return servers as Record<string, ServerConfig>
 }
 
-/** Claude's managed allow/deny lists: `allowed` null means no allow list (keep all);
- * a set (even empty) is exclusive, so only its members survive; a deny list removes
- * servers on top, deny winning over allow. */
-export function applyServerPolicy(servers: Record<string, ServerConfig>, allowed: ReadonlySet<string> | null, denied: ReadonlySet<string>): Record<string, ServerConfig> {
+/** Claude's allow/deny lists: a denylist match by URL, command or name blocks, and
+ * nothing overrides it; then a null allowlist keeps all, while a present one (even
+ * empty) is exclusive per the typed rule in serverAllowed. */
+export function applyServerPolicy(servers: Record<string, ServerConfig>, policy: McpPolicy): Record<string, ServerConfig> {
   const out: Record<string, ServerConfig> = {}
   for (const [name, config] of Object.entries(servers)) {
-    if (denied.has(name)) continue
-    if (allowed !== null && !allowed.has(name)) continue
+    if (policy.denied.some((entry) => entryMatches(entry, name, config, true))) continue
+    if (!serverAllowed(name, config, policy.allowed)) continue
     out[name] = config
   }
   return out

package/extensions/mcp/transport.ts

@@ -144,7 +144,9 @@ export async function connect(name: string, config: ServerConfig, authUi?: AuthU
     // The SDK's WebSocket transport takes only a url: it carries no headers, bearer
     // token, or headersHelper output. Warn rather than silently dropping configured
     // auth, and skip the helper entirely (running it would block the connect for up to
-    // 10s while contributing nothing). A ws server must be reachable without auth.
+    // 10s while contributing nothing). Divergence: Claude documents header auth as the
+    // ws mechanism ("Authentication is header-only"); under pi an authenticated ws
+    // server cannot be used until the SDK transport grows header support.
     if (config.headers || config.bearerToken || config.bearerTokenEnv || config.headersHelper) {
       console.warn(`pi-code-mcp: server ${name} is a WebSocket server; the SDK ws transport is url-only, so its headers/bearerToken/headersHelper are ignored`)
     }

package/extensions/subagent/README.md

@@ -114,15 +114,16 @@ Claude Code fields map onto pi where a sensible seam exists: `tools` and
 `--exclude-tools`; `effort` becomes the `:thinking` suffix on a pinned model, or
 `--thinking` when no model is pinned;
 `permissionMode: plan` selects a read-only toolset unless `tools` is set. Model
-aliases (`sonnet`, `opus`, `haiku`) resolve against the models this machine is
-authenticated for, falling back to the session's default model when that tier is
+aliases (`sonnet`, `opus`, `haiku`, `fable`) resolve against the models this machine
+is authenticated for, falling back to the session's default model when that tier is
 unavailable; `inherit` is the session model by definition. `skills` names skills to preload: their bodies are inlined into the child's
 prompt, since a child pi process does not inherit the parent's skill discovery, and
 a name that resolves to nothing is reported in the prompt rather than dropped.
 Fields with no pi seam are ignored, each verified against pi's CLI rather than
-assumed: `maxTurns` (no turn-limit flag), `mcpServers` (a child reads MCP config
-from files, and writing config into the workspace to fake it would be worse than
-the gap), and `memory` (pi-code's memory is per project, not per agent).
+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).
 
 **Locations:**
 - `~/.claude/agents/*.md`, `~/.pi/agent/agents/*.md` - User-level (always loaded; `~/.pi` wins a name conflict)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "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",