pi-code 1.0.63 → 1.0.64

package/README.md

@@ -56,7 +56,7 @@ Each topic links to its own doc with the full contract and any divergences from
 - **[Goal](docs/goal.md)**: `/goal <condition>` keeps the session working until a separate model check confirms the condition holds, with status, clear, block cap, background-work deferral, and resume.
 - **[Session extras](docs/session-extras.md)** — project trust, plan mode, todos, checkpoints/rewind, AskUserQuestion, notifications, think keywords, session titles, `/context`, `/init`.
 
-Slash commands: `/init`, `/context`, `/goal`, `/memory`, `/todos`, `/rewind`, `/tasks`, `/agents`, `/plan`, `/mcp`, `/hooks`, and `/output-style`, alongside your own `/dir:name` commands, `/skill:name` skills, `/plugin:name` plugin commands, and each connected server's `/mcp__server__prompt` prompts.
+Slash commands: `/init`, `/context`, `/goal`, `/memory`, `/todos`, `/rewind`, `/tasks`, `/agents`, `/plan`, `/plan-todos`, `/mcp`, `/hooks`, and `/output-style`, alongside your own `/dir:name` commands, `/skill:name` skills, `/plugin:name` plugin commands, and each connected server's `/mcp__server__prompt` prompts.
 
 pi has no general permission system, so most of what Claude routes through a permission prompt maps to hard behavior here: `allowed-tools` restricts the turn's tool set instead of pre-approving calls, and a hook that times out on PreToolUse or UserPromptSubmit fails closed. A hook's `permissionDecision: "ask"` is the exception: it shows a confirm dialog and lets the call through when you approve (a headless run has no dialog, so it blocks). Where a Claude restriction cannot be expressed at all (an argument-scoped grant in an agent's `tools:`), the definition is rejected rather than widened.
 

package/extensions/commands.ts

@@ -49,6 +49,7 @@ import { type CommandExec, expandDynamicContent, resolvePowershellBinary, spanEx
 import { claudeConfigDir } from './internal/config-dir.js'
 import { claudeEffortLevel } from './internal/effort.js'
 import { managedSettingsFile, readManagedSettings } from './internal/managed-settings.js'
+import { findModel } from './internal/model-lookup.js'
 import { capForContext } from './internal/output-guard.js'
 import { matchesPathRules } from './internal/path-rules.js'
 import { type InstalledPlugin, installedPlugins, pluginComponentPath } from './internal/plugins.js'
@@ -56,8 +57,9 @@ import { isProjectApproved } from './internal/project-approval.js'
 import { ancestorDirs, repoRoot } from './internal/project-root.js'
 import { agentNamesIn, matchesAgentRules, matchesDomainRules, matchesSkillRules } from './internal/scope-rules.js'
 import { claudeSettingsChain } from './internal/settings-chain.js'
+import { fileToolTarget } from './internal/tool-target.js'
 import { createTurnOverride } from './internal/turn-override.js'
-import { errorMessage, isDirectory } from './internal/values.js'
+import { errorMessage, isDirectory, parseNumericEnv } from './internal/values.js'
 
 /** Just enough of pi's Model to match and restore; getAvailable returns these. */
 interface ModelLike {
@@ -72,8 +74,7 @@ interface ModelLike {
  * subagent uses). `inherit` and an unresolvable name leave the model unchanged. */
 function resolveCommandModel(model: string | undefined, available: ReadonlyArray<ModelLike>): ModelLike | undefined {
   if (!model || model.toLowerCase() === 'inherit') return undefined
-  const needle = model.toLowerCase()
-  return available.find((m) => m.id.toLowerCase() === needle) ?? available.find((m) => m.id.toLowerCase().includes(needle) || (m.name ?? '').toLowerCase().includes(needle))
+  return findModel(model, available)
 }
 
 /** Substitute ${CLAUDE_*} into a path rule. A variable that expands to an absolute
@@ -276,8 +277,8 @@ const DEFAULT_TOOL_CHAR_BUDGET = 15_000
  * 1% of the model's context window (1% of the tokens at ~4 characters per token
  * is window / 25), else Claude's documented default. */
 export function slashCommandBudget(contextWindow: number | undefined, env: Record<string, string | undefined> = process.env): number {
-  const override = Number.parseInt(env.SLASH_COMMAND_TOOL_CHAR_BUDGET ?? '', 10)
-  if (Number.isInteger(override) && override > 0) return override
+  const override = parseNumericEnv(env.SLASH_COMMAND_TOOL_CHAR_BUDGET)
+  if (override !== undefined && Number.isInteger(override) && override > 0) return override
   if (contextWindow && contextWindow > 0) return Math.floor(contextWindow / 25)
   return DEFAULT_TOOL_CHAR_BUDGET
 }
@@ -394,7 +395,9 @@ export default function commandsExtension(pi: ExtensionAPI) {
     if (event.toolName === 'slash_command') return scopeVerdict(pendingSkillRules, 'slash_command', 'Command', text(input.command), (rules) => matchesSkillRules(text(input.command), rules))
     const rules = pendingPathRules?.[event.toolName as PathRuleTool]
     if (!rules) return
-    const filePath = typeof input.path === 'string' ? input.path : ''
+    // pi's read/edit/write accept `file_path` as an alias for `path`; the shared reader
+    // handles both, and the paired guard in hooks/matcher.ts reads both too.
+    const filePath = fileToolTarget(event) ?? ''
     const anchors = { cwd: ctx.cwd, projectRoot: repoRoot(ctx.cwd) ?? ctx.cwd, home: os.homedir() }
     if (filePath && matchesPathRules(filePath, rules, anchors)) return
     return {

package/extensions/context-imports.ts

@@ -743,9 +743,6 @@ function additionalDirsAddition(extras: Array<{ path: string; content: string; d
   return addition
 }
 
-/** The `## Imported context (@)` section for every resolved @import, with the
- * budget-exhaustion notice, announcing each as an `include`. Empty when nothing
- * was imported. */
 /** The refusal notice: every existing file an @import named that its importer may not
  * reach. Claude asks about these through an approval dialog and loads the ones you
  * allow; pi-code refuses them, and this is what says so. Silence was the real defect:
@@ -759,6 +756,9 @@ function refusedImportsAddition(refused: Set<string>): string {
   return `\n\n## Imports not loaded (@)\n\nThese files resolve outside what the file importing them may read, so their contents are not in context:\n\n${list}`
 }
 
+/** The `## Imported context (@)` section for every resolved @import, with the
+ * budget-exhaustion notice, announcing each as an `include`. Empty when nothing
+ * was imported. */
 function importedAddition(imported: ImportedFile[], budget: ImportBudget, home: string, projectRoot: string, announce: (event: InstructionLoadEvent) => void): string {
   if (imported.length === 0) return ''
   const section = imported.map((entry) => `### ${entry.path}\n\n${stripBlockComments(entry.body)}`).join('\n\n')

package/extensions/git-checkpoint.ts

@@ -3,10 +3,13 @@
  *
  * Claude Code style /rewind built on a per-session shadow git repo.
  *
- * Snapshots commit the entire working tree (untracked files included, the
- * project's .gitignore is honored) into a bare repo under
+ * Snapshots commit the files this session's edit tools touched (the project's
+ * .gitignore and .git/info/exclude are honored) into a bare repo under
  * ~/.pi/agent/checkpoints/<session>, using --git-dir/--work-tree so the
- * project's own git state is never touched. Each user prompt gets one
+ * project's own git state is never touched. Scope is the edit set, not the
+ * working tree: Claude tracks "only files that have been edited within the
+ * current session", and a whole-tree snapshot instead sizes every checkpoint
+ * by cwd, which has no bound when cwd is $HOME. Each user prompt gets one
  * checkpoint persisted as {entryId, ref, prompt, createdAt} in the session
  * file, so /rewind works across restarts, resumes, and forks. Code restore
  * checks the snapshot out over the working tree, resetting file contents to
@@ -17,13 +20,22 @@ import { createHash } from 'node:crypto'
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir } from '@earendil-works/pi-coding-agent'
 import { claudeConfigDir } from './internal/config-dir.js'
+import { readSettingsFile } from './internal/settings-chain.js'
+import { fileToolTarget } from './internal/tool-target.js'
 import { contentText, errorMessage } from './internal/values.js'
 
 const CUSTOM_TYPE = 'git-checkpoint'
 /** Sidecar inside the bare shadow repo recording the work tree it snapshots. */
 const WORK_TREE_FILE = 'pi-work-tree'
+/** pi's tools that change a file. `read` is deliberately absent: checkpoint scope is
+ * the set of files the session edited, and that set is what bounds the snapshot. */
+const EDIT_TOOLS: ReadonlySet<string> = new Set(['edit', 'write'])
+/** A run's checkpoint commit is published under a ref rather than recorded as a raw
+ * sha, so a file first edited in a later turn of the same run can still fold its
+ * pre-edit baseline into that run's checkpoint by moving the ref. */
+const CHECKPOINT_REF_PREFIX = 'refs/pi-code/checkpoints'
 const PROMPT_SNIPPET_LENGTH = 60
 const RESTORE_MODES = ['Code and conversation', 'Conversation only', 'Code only']
 
@@ -34,9 +46,9 @@ interface Checkpoint {
   createdAt: string
 }
 
-/** Claude deletes checkpoints after 30 days (cleanupPeriodDays). Shadow repos hold
- * full snapshots of every non-ignored file, so unbounded retention grows under $HOME
- * for the life of the machine. */
+/** Claude deletes checkpoints after 30 days (cleanupPeriodDays). Shadow repos hold a
+ * snapshot per edited file, so unbounded retention grows under $HOME for the life of
+ * the machine. */
 export const CHECKPOINT_RETENTION_DAYS = 30
 
 /** The retention period in effect: Claude keeps checkpoints for 30 days and says to
@@ -44,13 +56,8 @@ export const CHECKPOINT_RETENTION_DAYS = 30
  * setting about the user's own disk belongs; a non-positive or unreadable value keeps the
  * default rather than sweeping everything away. */
 export function checkpointRetentionDays(home: string = os.homedir()): number {
-  try {
-    const parsed: unknown = JSON.parse(fs.readFileSync(path.join(claudeConfigDir(home), 'settings.json'), 'utf-8'))
-    const declared = (parsed as { cleanupPeriodDays?: unknown }).cleanupPeriodDays
-    if (typeof declared === 'number' && Number.isFinite(declared) && declared > 0) return declared
-  } catch {
-    // No user settings, or unreadable: the default period stands.
-  }
+  const declared = readSettingsFile(path.join(claudeConfigDir(home), 'settings.json'))?.cleanupPeriodDays
+  if (typeof declared === 'number' && Number.isFinite(declared) && declared > 0) return declared
   return CHECKPOINT_RETENTION_DAYS
 }
 
@@ -163,6 +170,13 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
   let runNeedsSnapshot = true
   let shadowDir: string | undefined
   let workTree: string | undefined
+  // Absolute paths this session's edit tools targeted: the whole of what a checkpoint
+  // captures. Seeded on resume from the last commit, so a resumed session keeps
+  // snapshotting the files it was already tracking.
+  const touched = new Set<string>()
+  // The ref holding the in-flight run's checkpoint, moved as later baselines arrive.
+  let runRef: string | undefined
+  let refSeq = 0
 
   function gitShadow(args: string[]): ReturnType<ExtensionAPI['exec']> {
     if (!shadowDir || !workTree) return Promise.resolve({ stdout: '', stderr: 'shadow repo not initialized', code: 1, killed: false })
@@ -175,7 +189,7 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
   async function ensureShadow(ctx: ExtensionContext): Promise<void> {
     workTree = ctx.cwd
     const sessionFile = (ctx.sessionManager as { getSessionFile?: () => string | undefined }).getSessionFile?.()
-    const checkpointsRoot = path.join(os.homedir(), '.pi', 'agent', 'checkpoints')
+    const checkpointsRoot = path.join(getAgentDir(), 'checkpoints')
     shadowDir = path.join(checkpointsRoot, sessionSlug(sessionFile))
     // A resumed session can arrive from a different directory than the one the shadow
     // snapshotted; restoring those commits here would silently overwrite unrelated
@@ -233,6 +247,79 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
     }
   }
 
+  /** A tracked file as git names it: a work-tree-relative slash-separated path, or
+   * undefined for anything outside the work tree, which git refuses as a pathspec.
+   * Paths are compared in this form throughout, never as absolutes: git echoes a
+   * pathspec back verbatim, while the same file can spell its absolute path two ways
+   * on Windows (a short 8.3 temp directory against its long form). */
+  function workTreePath(file: string): string | undefined {
+    if (!workTree) return undefined
+    const rel = path.relative(workTree, file)
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return undefined
+    return rel.split(path.sep).join('/')
+  }
+
+  /** The paths the last checkpoint commit holds. A tracked file deleted since then still
+   * matches a pathspec through this, so its removal is staged instead of the stale index
+   * entry silently riding along into the next checkpoint. */
+  async function committedPaths(): Promise<Set<string>> {
+    const listed = await gitShadow(['ls-tree', '-r', '--name-only', 'HEAD'])
+    if (listed.code !== 0) return new Set()
+    return new Set(listed.stdout.split('\n').filter(Boolean))
+  }
+
+  /** git rejects the whole pathspec when one entry is ignored, so the ignored paths are
+   * dropped before the add rather than costing the run its checkpoint. */
+  async function withoutIgnored(files: string[]): Promise<string[]> {
+    const checked = await gitShadow(['-c', 'core.quotePath=false', 'check-ignore', '--', ...files])
+    if (checked.code !== 0) return files
+    const ignored = new Set(checked.stdout.split('\n').filter(Boolean))
+    return files.filter((file) => !ignored.has(file))
+  }
+
+  /** The tracked files git will accept: inside the work tree, and either on disk or in
+   * the last commit. A pathspec matching neither aborts the entire add, taking the
+   * checkpoint with it. */
+  async function addablePaths(): Promise<string[]> {
+    const inside: Array<{ file: string; rel: string }> = []
+    for (const file of touched) {
+      const rel = workTreePath(file)
+      if (rel !== undefined) inside.push({ file, rel })
+    }
+    if (inside.length === 0) return []
+    const committed = await committedPaths()
+    const live = inside.filter(({ file, rel }) => fs.existsSync(file) || committed.has(rel)).map(({ rel }) => rel)
+    return live.length === 0 ? [] : withoutIgnored(live)
+  }
+
+  /** Point this run's ref at the commit. Publishing a ref rather than the raw sha lets a
+   * baseline captured later in the run move the checkpoint forward without rewriting a
+   * commit that an earlier checkpoint may share. */
+  async function publishRun(sha: string, createdAt: string): Promise<{ ref: string; createdAt: string }> {
+    const ref = `${CHECKPOINT_REF_PREFIX}/${Date.now().toString(36)}-${++refSeq}`
+    const update = await gitShadow(['update-ref', ref, sha])
+    if (update.code !== 0) return { ref: sha, createdAt }
+    runRef = ref
+    return { ref, createdAt }
+  }
+
+  /** Fold a file's pre-edit content into the run's checkpoint. A file first edited part
+   * way through a run is absent from that run's pre-run snapshot, so without this its
+   * checkpoint holds no baseline and /rewind cannot undo that first edit. */
+  async function captureBaseline(file: string): Promise<void> {
+    const rel = workTreePath(file)
+    if (!runRef || rel === undefined || !fs.existsSync(file)) return
+    if ((await withoutIgnored([rel])).length === 0) return
+    const add = await gitShadow(['add', '--', rel])
+    if (add.code !== 0) return
+    // A commit, never an amend: the run's checkpoint can be a commit an earlier
+    // checkpoint also points at, and rewriting it would strand that one.
+    const commit = await commitShadow([])
+    if (commit.code !== 0) return
+    const sha = await gitShadow(['rev-parse', 'HEAD'])
+    if (sha.code === 0) await gitShadow(['update-ref', runRef, sha.stdout.trim()])
+  }
+
   /** `checkout -f <ref> -- .` errors when the ref's tree holds no files, so an empty
    * snapshot restores as a no-op rather than vetoing the whole rewind. */
   async function snapshotIsEmpty(ref: string): Promise<boolean> {
@@ -242,16 +329,21 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
 
   async function snapshot(): Promise<{ ref: string; createdAt: string } | undefined> {
     const createdAt = new Date().toISOString()
-    const add = await gitShadow(['add', '-A'])
-    if (add.code !== 0) return undefined
+    const paths = await addablePaths()
+    if (paths.length > 0) {
+      const add = await gitShadow(['add', '--', ...paths])
+      if (add.code !== 0) return undefined
+    }
     // Decide "nothing changed" from the index, not from the commit exit code: a commit can
     // also fail on the user's global signing or hooks config, and reusing HEAD then would
     // record a ref that predates the current tree, so /rewind restores the wrong state.
-    const status = await gitShadow(['status', '--porcelain'])
+    // Untracked files are excluded because the work tree is full of files this session
+    // never edited; counting them would make every run look changed.
+    const status = await gitShadow(['status', '--porcelain', '--untracked-files=no'])
     const nothingChanged = status.code === 0 && status.stdout.trim() === ''
     if (nothingChanged) {
       const head = await gitShadow(['rev-parse', 'HEAD'])
-      if (head.code === 0) return { ref: head.stdout.trim(), createdAt }
+      if (head.code === 0) return publishRun(head.stdout.trim(), createdAt)
       const empty = await commitShadow(['--allow-empty'])
       if (empty.code !== 0) return undefined
     } else {
@@ -259,7 +351,7 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
       if (commit.code !== 0) return undefined // real failure: do not record a stale ref
     }
     const sha = await gitShadow(['rev-parse', 'HEAD'])
-    return sha.code === 0 ? { ref: sha.stdout.trim(), createdAt } : undefined
+    return sha.code === 0 ? publishRun(sha.stdout.trim(), createdAt) : undefined
   }
 
   /** Commit in the shadow repo, isolated from the user's global signing and hook config. */
@@ -300,7 +392,10 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
     // own tree even though the prior run left it false.
     pending = undefined
     runNeedsSnapshot = true
+    runRef = undefined
     await ensureShadow(ctx)
+    touched.clear()
+    for (const rel of await committedPaths()) touched.add(path.resolve(ctx.cwd, rel))
     checkpoints.clear()
     const stored: Checkpoint[] = []
     for (const entry of ctx.sessionManager.getEntries()) {
@@ -338,13 +433,34 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
     pending = await snapshot()
   })
 
+  // A checkpoint covers the files the session edited, so the tracked set grows as the
+  // model works. The baseline is taken here, before the tool writes, because once the
+  // tool has run the pre-edit content is gone.
+  pi.on('tool_call', async (event, ctx) => {
+    if (!EDIT_TOOLS.has(event.toolName)) return
+    const target = fileToolTarget(event)
+    if (target === undefined) return
+    const file = path.resolve(ctx.cwd, target)
+    if (touched.has(file)) return
+    touched.add(file)
+    await captureBaseline(file)
+  })
+
   pi.on('turn_end', async (_event, ctx) => {
     const snap = pending
     pending = undefined
     if (!snap) return
 
     const target = findLastUserMessage(ctx)
-    if (!target || checkpoints.has(target.entryId)) return
+    if (!target) return
+    const recorded = checkpoints.get(target.entryId)
+    if (recorded) {
+      // A retry or follow-up re-ran agent_start and took a fresh snapshot, but this user
+      // message already has its checkpoint. Discard the new one and keep folding later
+      // baselines into the checkpoint that is actually recorded.
+      runRef = recorded.ref
+      return
+    }
 
     const checkpoint: Checkpoint = { entryId: target.entryId, ref: snap.ref, prompt: target.prompt, createdAt: snap.createdAt }
     checkpoints.set(checkpoint.entryId, checkpoint)

package/extensions/hooks/config.ts

@@ -9,7 +9,7 @@ import * as path from 'node:path'
 import { readManagedSettings } from '../internal/managed-settings.js'
 import { type InstalledPlugin, pluginComponentPath, substitutePluginVars } from '../internal/plugins.js'
 import { claudeSettingsChain, readSettingsChain } from '../internal/settings-chain.js'
-import { errorMessage, isRecord } from '../internal/values.js'
+import { errorMessage, escapeRegExp, isRecord } from '../internal/values.js'
 
 export interface HookCommand {
   type?: string
@@ -159,7 +159,7 @@ export function readAllowedHttpHookUrls(files: string[], managed: Record<string,
 export function httpUrlAllowed(url: string, allowlist: string[] | undefined): boolean {
   if (allowlist === undefined) return true
   return allowlist.some((pattern) => {
-    const literal = pattern.split('*').map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`))
+    const literal = pattern.split('*').map(escapeRegExp)
     return new RegExp(`^${literal.join('.*')}$`).test(url)
   })
 }
@@ -182,7 +182,7 @@ export function loadHooks(files: string[], sources?: Map<HookMatcher, string>):
  * stays separate, so plugin entries carry their origin into the dedup key. */
 function stampOrigin(entries: HookMatcher[], origin: string): void {
   for (const entry of entries) {
-    for (const hook of entry.hooks ?? []) hook.origin = origin
+    for (const hook of entry.hooks ?? []) if (isRecord(hook)) hook.origin = origin
   }
 }
 
@@ -209,10 +209,9 @@ function mergeHooksJson(config: HooksConfig, raw: string, source: string, source
   }
   for (const [event, matchers] of Object.entries(parsed?.hooks ?? {})) {
     if (!Array.isArray(matchers)) continue
-    // Entries are validated here rather than where they run: a hand-edited settings
-    // file that writes `hooks` as an object instead of a list used to throw out of
-    // the tool_call handler, and pi turns that into an error result, so every tool
-    // call for the rest of the session failed with an opaque type error.
+    // Entries are validated here rather than where they run: a malformed entry that
+    // throws from the tool_call handler becomes an error result there, so every tool
+    // call for the rest of the session fails with an opaque type error.
     const usable = matchers.filter((entry) => isUsableMatcher(entry, source, event))
     if (usable.length === 0) continue
     if (origin !== undefined) stampOrigin(usable, origin)
@@ -224,9 +223,6 @@ function mergeHooksJson(config: HooksConfig, raw: string, source: string, source
   }
 }
 
-/** Each enabled plugin's hooks (hooks/hooks.json, or wherever the manifest points),
- * with ${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PLUGIN_DATA} substituted before parsing so a
- * hook can name its bundled scripts by real path. */
 /** The substitution here lands inside raw JSON, so values must arrive escaped:
  * an unescaped Windows root injected \U-style sequences, the parse threw, and
  * every hook the plugin declared silently vanished. */
@@ -270,6 +266,9 @@ function withoutUserConfigShellCommands(raw: string, source: string): string {
   return dropped ? JSON.stringify(parsed) : raw
 }
 
+/** Each enabled plugin's hooks (hooks/hooks.json, or wherever the manifest points),
+ * with ${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PLUGIN_DATA} substituted before parsing so a
+ * hook can name its bundled scripts by real path. */
 export function loadPluginHooks(config: HooksConfig, plugins: InstalledPlugin[], sources?: Map<HookMatcher, string>): void {
   for (const plugin of plugins) {
     const declared = plugin.manifest.hooks
@@ -304,6 +303,13 @@ function isUsableMatcher(entry: unknown, file: string, event: string): entry is
     console.warn(`pi-code-hooks: ignoring ${event} entry in ${file}: "hooks" must be a list`)
     return false
   }
+  // The list's entries too: the dispatcher reads `.type` of each, so one `null` (a
+  // hand-edit that removed an entry's body) failed every tool call for the session.
+  if (Array.isArray(candidate.hooks)) {
+    const objects = candidate.hooks.filter((hook: unknown) => isRecord(hook))
+    if (objects.length !== candidate.hooks.length) console.warn(`pi-code-hooks: ignoring ${candidate.hooks.length - objects.length} non-object hook(s) in a ${event} entry in ${file}`)
+    candidate.hooks = objects as HookCommand[]
+  }
   if (candidate.matcher !== undefined && typeof candidate.matcher !== 'string') {
     console.warn(`pi-code-hooks: ignoring ${event} entry in ${file}: "matcher" must be a string`)
     return false

package/extensions/hooks/decisions.ts

@@ -170,15 +170,6 @@ 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. 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. */
@@ -215,6 +206,15 @@ function preToolContexts(results: HookRunResult[]): string[] {
   })
 }
 
+/** Run PreToolUse hooks for a tool, in parallel as Claude does; the first blocking
+ * 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). */
 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)

package/extensions/hooks/index.ts

@@ -109,7 +109,7 @@ import { watchSettingsFiles } from '../internal/settings-watch.js'
 import { isSkillHooksEvent, SKILL_HOOKS_CHANNEL } from '../internal/skill-hooks.js'
 import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
 import { setSubagentStartHookRunner } from '../internal/subagent-hooks.js'
-import { contentText } from '../internal/values.js'
+import { contentText, parseNumericEnv } from '../internal/values.js'
 import { claudeToolInput, claudeToolName, claudeToolResponse, piToolOutput } from './claude-tools.js'
 import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, isBackgroundHook, loadHooks, loadManagedHooks, loadPluginHooks, mergeAgentEnvHooks, mergeSkillHooks, readAllowedHttpHookUrls, readDisableAllHooks, readSettingsDisableAllHooks } from './config.js'
 import { blockedToolCall, jsonBlockVerdict, postToolFeedback, promptContext, runPreToolUse, runUserPromptSubmit, surfaceSystemMessages, tryParseJson } from './decisions.js'
@@ -142,9 +142,9 @@ const DEFAULT_STOP_HOOK_BLOCK_CAP = 8
  * 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)
+  const override = parseNumericEnv(env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP)
   if (override === 0) return Number.POSITIVE_INFINITY
-  return Number.isInteger(override) && override > 0 ? override : DEFAULT_STOP_HOOK_BLOCK_CAP
+  return override !== undefined && Number.isInteger(override) && override > 0 ? override : DEFAULT_STOP_HOOK_BLOCK_CAP
 }
 
 async function runNotifyHooks(commands: HookCommand[], payload: unknown, runner: HookRunner): Promise<HookRunResult[]> {
@@ -337,10 +337,10 @@ export default function hooksExtension(pi: ExtensionAPI) {
   })
   // Claude's InstructionsLoaded hook has NO decision control: exit codes are
   // ignored and every JSON output field (systemMessage included) is discarded, so
-  // dispatch is fire-and-forget on all paths. Two documented load reasons can
-  // never fire honestly and are deliberate gaps, not approximations:
-  // `nested_traversal` (pi does not lazily load a nested CLAUDE.md on subdirectory
-  // entry) and `compact` (pi does not re-load instruction files after compaction).
+  // dispatch is fire-and-forget on all paths. `nested_traversal` arrives from
+  // context-imports when a CLAUDE.md below cwd is attached on a file touch. The
+  // `compact` reason can never fire honestly and is a deliberate gap, not an
+  // approximation: pi does not re-load instruction files after compaction.
   const fireInstructionsLoaded = (payload: Record<string, unknown>): void => {
     if (!sessionCtx) return
     const commands = matchingCommands(config.InstructionsLoaded, String(payload.load_reason))
@@ -703,7 +703,11 @@ export default function hooksExtension(pi: ExtensionAPI) {
     // Claude's custom_instructions: the /compact arguments on a manual run, empty
     // on an automatic one; pi carries them on the event directly.
     const payload = { hook_event_name: 'PreCompact', trigger: trigger.value, custom_instructions: event.customInstructions ?? '' }
-    const results = await runNotifyHooks(matchingCommands(config.PreCompact, trigger.names), payload, boundRunner(ctx))
+    // Filtered here the way runNotifyHooks filters, so `results[index]` and
+    // `commands[index]` name the same hook: indexing the unfiltered list named the
+    // wrong command in the notice whenever an `if`-carrying hook preceded the blocker.
+    const commands = matchingCommands(config.PreCompact, trigger.names).filter((command) => passesIfFilter(command, undefined))
+    const results = await runNotifyHooks(commands, payload, boundRunner(ctx))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
     // Claude: "Exit with code 2 to block compaction. For a manual /compact, the stderr
     // message is shown to the user. You can also block by returning JSON with
@@ -713,7 +717,7 @@ export default function hooksExtension(pi: ExtensionAPI) {
       const parsed = tryParseJson(result.stdout)
       const blocked = result.code === 2 && !result.timedOut ? { reason: result.stderr.trim() || 'Compaction blocked by hook' } : jsonBlockVerdict(parsed, 'Compaction blocked by hook')
       if (!blocked) continue
-      ctx.ui.notify(`Compaction blocked by ${matchingCommands(config.PreCompact, trigger.names)[index]?.command ?? 'hook'}: ${blocked.reason}`, 'warning')
+      ctx.ui.notify(`Compaction blocked by ${commands[index]?.command ?? 'hook'}: ${blocked.reason}`, 'warning')
       return { cancel: true }
     }
   })

package/extensions/hooks/matcher.ts

@@ -93,7 +93,13 @@ function isRunnableHook(hook: HookCommand): boolean {
   if (hook.type === 'http') return typeof hook.url === 'string' && /^https?:\/\//.test(hook.url)
   if (hook.type === 'prompt' || hook.type === 'agent') return typeof hook.prompt === 'string' && hook.prompt.length > 0
   if (hook.type === 'mcp_tool') return typeof hook.server === 'string' && typeof hook.tool === 'string'
-  return typeof hook.command === 'string' && (hook.type === undefined || hook.type === 'command')
+  // A command hook needs a non-empty command, and exec-form args must all be strings:
+  // spawn('') throws ERR_INVALID_ARG_VALUE and a number has no replaceAll for argument
+  // substitution, both inside the runner's Promise executor, so the event's handler
+  // rejected instead of the hook reporting spawnFailed.
+  if (typeof hook.command !== 'string' || hook.command.length === 0) return false
+  if (hook.args !== undefined && !(Array.isArray(hook.args) && hook.args.every((arg) => typeof arg === 'string'))) return false
+  return hook.type === undefined || hook.type === 'command'
 }
 
 /** The synthetic identity of a non-shell hook entry: an http/prompt/agent/mcp_tool
@@ -188,18 +194,17 @@ export function passesIfFilter(hook: HookCommand, target: IfFilterTarget | undef
 
 /** One `if` pattern against a call's arguments. Claude evaluates the rule "against
  * the tool name and arguments together" in permission-rule syntax, so each tool uses
- * the same specifier engine its permission rules use:
+ * the same specifier engine its permission rules use: a command pattern for Bash, a
+ * `domain:` host for WebFetch, an agent name for Agent, a skill name for Skill, and a
+ * path rule for the file tools. A tool with no specifier syntax matches nothing,
+ * which is also what an unparseable rule does.
  *
  * PAIRED WITH commands.ts's tool_call guard, which dispatches the same tools to the
  * same matchers for `allowed-tools` scopes. The two are deliberately NOT merged: bash
  * differs on purpose (an allow scope requires every segment to match, an `if` filter is
  * best effort and errs toward running the hook), and merging would hide that. They are
  * two lists that must agree, so a new scoped tool has to be added in both places; the
- * shared roster is ARG_RULE_TOOLS in internal/command-file.ts.
- * a command pattern for Bash, a
- * `domain:` host for WebFetch, an agent name for Agent, a skill name for Skill, and a
- * path rule for the file tools. A tool with no specifier syntax matches nothing,
- * which is also what an unparseable rule does. */
+ * shared roster is ARG_RULE_TOOLS in internal/command-file.ts. */
 function matchesToolPattern(piName: string, input: Record<string, unknown> | null, pattern: string, anchors: PathAnchors): boolean {
   const str = (value: unknown): string => (typeof value === 'string' ? value : '')
   switch (piName) {

package/extensions/hooks/runners.ts

@@ -6,11 +6,11 @@
 
 import { type ChildProcess, spawn } from 'node:child_process'
 import * as fs from 'node:fs'
-import * as path from 'node:path'
 import type { Api, Model } from '@earendil-works/pi-ai'
 import { runAgent } from '../internal/agent-run.js'
 import { callMcpTool } from '../internal/mcp-call.js'
 import { completeText } from '../internal/model-complete.js'
+import { killProcessTree } from '../internal/process-tree.js'
 import { resolveShell } from '../internal/shell-resolve.js'
 import { errorMessage } from '../internal/values.js'
 import { type HookCommand, httpUrlAllowed, isBackgroundHook } from './config.js'
@@ -41,10 +41,6 @@ export interface HookRunResult {
 }
 /** Runs one configured hook entry, whatever its type; boundRunner dispatches. */
 export type HookRunner = (hook: HookCommand, payload: unknown, timeoutMs: number) => Promise<HookRunResult>
-/** The shell path specifically; the statusline reuses it for its own command. With an
- * `args` array it becomes the exec path: `command` is spawned directly with those args.
- * `onChild` hands the caller a kill for the spawned tree, so a background hook that is
- * still running at session end can be reaped (Claude kills async hooks at teardown). */
 /** How one command hook is spawned, beyond the payload and its budget. Grouped rather
  * than trailing off the parameter list: the exec form, the shell choice and the
  * declaring plugin are all per-hook fields that arrive together from one HookCommand. */
@@ -96,30 +92,9 @@ const MAX_HOOK_OUTPUT = 1_000_000
 /** Conventional exit code for a killed-on-timeout command, as `timeout(1)` reports it. */
 const TIMEOUT_EXIT_CODE = 124
 
-/**
- * Kill the shell and everything it spawned. `sh -c 'a; b'` forks, so signalling the
- * direct child alone leaves a grandchild alive holding stdout/stderr.
- */
+/** Kill the shell and everything it spawned; see internal/process-tree. */
 function killTree(child: ChildProcess): void {
-  if (process.platform === 'win32') {
-    // Windows has no process groups: taskkill /T ends the shell's whole tree. By
-    // absolute path, so a writable PATH entry cannot stand in for it. If taskkill itself
-    // cannot start, the direct kill is all that is left.
-    const taskkill = path.join(process.env.SystemRoot ?? String.raw`C:\Windows`, 'System32', 'taskkill.exe')
-    if (child.pid) spawn(taskkill, ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }).on('error', () => child.kill('SIGKILL'))
-    else child.kill('SIGKILL')
-    return
-  }
-  try {
-    // Negative pid targets the whole process group, which `detached` gave the shell.
-    if (child.pid) {
-      process.kill(-child.pid, 'SIGKILL')
-      return
-    }
-  } catch {
-    // Group already reaped, or the platform refused it; fall through to the direct kill.
-  }
-  child.kill('SIGKILL')
+  killProcessTree(child, 'SIGKILL')
 }
 
 /** Create the plugin data directory the moment its path is handed to a child. Claude
@@ -140,6 +115,10 @@ function shellInvocation(command: string, shell: string | undefined): { file: st
   return resolved ? { file: resolved.file, spawnArgs: resolved.argsFor(command) } : undefined
 }
 
+/** The shell path specifically; the statusline reuses it for its own command. With an
+ * `args` array it becomes the exec path: `command` is spawned directly with those args.
+ * `onChild` hands the caller a kill for the spawned tree, so a background hook that is
+ * still running at session end can be reaped (Claude kills async hooks at teardown). */
 export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, { projectDir, args, onChild, shell, plugin, sessionId } = {}) =>
   new Promise((resolve) => {
     // /bin/sh by absolute path off Windows, so the shell can't be resolved through an

package/extensions/internal/agent-run.ts

@@ -36,7 +36,7 @@ export function setAgentRunner(fn: AgentRunner | undefined): void {
   runner = fn
 }
 
-/** Whether a runner is registered, so agent hooks can be reported as runnable. */
+/** Test seam: whether a runner is registered. */
 export function hasAgentRunner(): boolean {
   return runner !== undefined
 }

package/extensions/internal/bash-rules.ts

@@ -11,8 +11,7 @@
  */
 
 import { hasSubstitution, splitSegments } from './shell-split.js'
-
-const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+import { escapeRegExp } from './values.js'
 
 /**
  * One rule against one command segment, per Claude's permission table: