pi-code 1.0.13 → 1.0.15

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; 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, 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` |
 | 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

@@ -51,7 +51,9 @@ import { capForContext } from './internal/output-guard.js'
 import { matchesPathRules } from './internal/path-rules.js'
 import { type InstalledPlugin, installedPlugins } from './internal/plugins.js'
 import { isProjectApproved } from './internal/project-approval.js'
-import { findNearestDir, findNearestFile, repoRoot } from './internal/project-root.js'
+import { findNearestDir, repoRoot } from './internal/project-root.js'
+import { claudeSettingsChain } from './internal/settings-chain.js'
+import { createTurnOverride } from './internal/turn-override.js'
 
 type PathRuleTool = 'read' | 'edit' | 'write'
 
@@ -136,7 +138,7 @@ export function collectCommands(dirs: string[]): DiscoveredCommand[] {
 
 /** A plugin's command files, namespaced `plugin:name` as Claude registers them.
  * The manifest may point `commands` somewhere else; the default is `commands/`. */
-export function pluginCommands(plugins: InstalledPlugin[]): DiscoveredCommand[] {
+function pluginCommands(plugins: InstalledPlugin[]): DiscoveredCommand[] {
   const found: DiscoveredCommand[] = []
   for (const plugin of plugins) {
     const declared = plugin.manifest.commands
@@ -166,12 +168,7 @@ type CommandPlugin = NonNullable<DiscoveredCommand['plugin']>
  */
 export function shellExecutionDisabled(cwd: string, home: string, trusted: boolean): boolean {
   if (readManagedSettings().disableSkillShellExecution === true) return true
-  const files = [path.join(claudeConfigDir(home), 'settings.json')]
-  if (trusted) {
-    for (const name of ['settings.json', 'settings.local.json']) {
-      files.push(findNearestFile(cwd, path.join('.claude', name)) ?? path.join(cwd, '.claude', name))
-    }
-  }
+  const files = claudeSettingsChain(cwd, home, trusted)
   return files.some((file) => {
     try {
       return (JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, unknown>).disableSkillShellExecution === true
@@ -307,10 +304,21 @@ export default function commandsExtension(pi: ExtensionAPI) {
   let pendingBashRules: string[] | undefined
   /** Read/Edit path scopes enforced the same way, per pi file tool. */
   let pendingPathRules: Partial<Record<PathRuleTool, string[]>> | undefined
-  /** The session model to restore after a command's `model:` override drove its run. */
-  let pendingModelRestore: ModelLike | undefined
-  /** The thinking level to restore after a command's `effort:` override drove its run. */
-  let pendingEffortRestore: string | undefined
+  /** The session model to restore after a command's `model:` override drove its run,
+   * captured once per turn so a second command restores the original session model. */
+  const modelOverride = createTurnOverride<ModelLike>({
+    // setModel can reject (e.g. auth resolution fails), and a floated rejection would
+    // escape as unhandled; surface it as a no-op instead of leaving the session silently
+    // on the command's override model.
+    set: (model) => {
+      void pi.setModel(model as Parameters<typeof pi.setModel>[0]).catch(() => {})
+    },
+  })
+  /** The thinking level to restore after a command's `effort:` override drove its run,
+   * captured once per turn the same way. */
+  const effortOverride = createTurnOverride<string>({
+    set: (level) => pi.setThinkingLevel(level as Parameters<typeof pi.setThinkingLevel>[0]),
+  })
 
   // Claude's contract is "the grant clears when you send your next message", and
   // pi's turn_end fires after every assistant step: restoring there stripped a
@@ -323,19 +331,8 @@ export default function commandsExtension(pi: ExtensionAPI) {
   pi.on('agent_settled', async () => {
     pendingBashRules = undefined
     pendingPathRules = undefined
-    if (pendingModelRestore) {
-      const restore = pendingModelRestore as Parameters<typeof pi.setModel>[0]
-      pendingModelRestore = undefined
-      // setModel can reject (e.g. auth resolution fails), and a floated rejection would
-      // escape as unhandled; surface it instead of leaving the session silently on the
-      // command's override model.
-      void pi.setModel(restore).catch(() => {})
-    }
-    if (pendingEffortRestore) {
-      const level = pendingEffortRestore as Parameters<typeof pi.setThinkingLevel>[0]
-      pendingEffortRestore = undefined
-      pi.setThinkingLevel(level)
-    }
+    modelOverride.settle()
+    effortOverride.settle()
     if (pendingRestore) {
       pi.setActiveTools(pendingRestore)
       pendingRestore = undefined
@@ -412,7 +409,7 @@ export default function commandsExtension(pi: ExtensionAPI) {
   async function applyModelOverride(parsed: ParsedCommand, varCtx: VarContext): Promise<void> {
     const target = resolveCommandModel(parsed.model, varCtx.modelRegistry?.getAvailable() ?? [])
     if (target && varCtx.model && target.id !== varCtx.model.id) {
-      pendingModelRestore = pendingModelRestore ?? varCtx.model
+      modelOverride.arm(varCtx.model)
       await pi.setModel(target as Parameters<typeof pi.setModel>[0])
     }
   }
@@ -421,11 +418,11 @@ export default function commandsExtension(pi: ExtensionAPI) {
    * the session level resumes; restore happens on agent_settled like the model restore.
    * Applied before sendUserMessage so the run it drives happens at the new level. Only the
    * first override in a turn records the restore target, so a second command restores to
-   * the original session level rather than the first command's override (as pendingModelRestore). */
+   * the original session level rather than the first command's override (as the model override). */
   function applyEffortOverride(parsed: ParsedCommand, varCtx: VarContext): void {
     const target = parsed.effort
     if (target && varCtx.thinkingLevel && target !== varCtx.thinkingLevel) {
-      pendingEffortRestore = pendingEffortRestore ?? varCtx.thinkingLevel
+      effortOverride.arm(varCtx.thinkingLevel)
       pi.setThinkingLevel(target as Parameters<typeof pi.setThinkingLevel>[0])
     }
   }
@@ -474,8 +471,8 @@ export default function commandsExtension(pi: ExtensionAPI) {
     pendingRestore = undefined
     pendingBashRules = undefined
     pendingPathRules = undefined
-    pendingModelRestore = undefined
-    pendingEffortRestore = undefined
+    modelOverride.reset()
+    effortOverride.reset()
     const trusted = await isProjectApproved(ctx)
     projectApproved = trusted
     // A resume/fork/new session can switch projects in-process. pi cannot unregister a

package/extensions/context-imports.ts

@@ -75,6 +75,8 @@ import { managedSettingsPath, readManagedSettings } from './internal/managed-set
 import { globToRegExpSource } from './internal/path-rules.js'
 import { isProjectApproved, isProjectApprovedSilently } from './internal/project-approval.js'
 import { ancestorFiles, findNearestFile, repoRoot } from './internal/project-root.js'
+import { claudeSettingsChain } from './internal/settings-chain.js'
+import { statToken } from './internal/stat-token.js'
 import { fenceMarker, stripBlockComments } from './internal/strip-comments.js'
 
 /** Claude documents "a maximum depth of four hops" for recursive imports. */
@@ -93,7 +95,7 @@ function isUnder(target: string, roots: string[]): boolean {
 }
 
 /** Realpath the roots that exist; used both to seed and to bound the import search. */
-export function realRoots(candidates: string[]): string[] {
+function realRoots(candidates: string[]): string[] {
   const roots: string[] = []
   for (const candidate of candidates) {
     try {
@@ -249,7 +251,7 @@ export function rootsForImporter(importer: string, home: string, cwd: string): s
 }
 
 /** Claude's env gate for loading memory files from --add-dir directories. */
-export const ADDITIONAL_DIRS_ENV = 'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD'
+const ADDITIONAL_DIRS_ENV = 'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD'
 
 /** Whether the env gate is on. Claude documents `=1`; any value that is not
  * empty/0/false/no counts, so `=true` behaves as a user would expect. */
@@ -319,7 +321,7 @@ export function managedClaudeMdPath(): string {
 }
 
 /** The managed CLAUDE.md file body, or '' when absent or unreadable. */
-export function readManagedClaudeMdFile(): string {
+function readManagedClaudeMdFile(): string {
   try {
     return fs.readFileSync(managedClaudeMdPath(), 'utf-8')
   } catch {
@@ -375,12 +377,7 @@ function withTopBlock(prompt: string, block: string): string {
  * settings.local.json (nearest at or above cwd) only when the project is
  * approved. Managed settings are read separately by the caller. */
 export function claudeMdExcludeFiles(cwd: string, home: string, approved: boolean): string[] {
-  const files = [path.join(claudeConfigDir(home), 'settings.json')]
-  if (!approved) return files
-  for (const name of ['settings.json', 'settings.local.json']) {
-    files.push(findNearestFile(cwd, path.join('.claude', name)) ?? path.join(cwd, '.claude', name))
-  }
-  return files
+  return claudeSettingsChain(cwd, home, approved)
 }
 
 /** Merged `claudeMdExcludes` globs across the settings chain plus managed
@@ -641,11 +638,6 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
         tokens: Array<[string, string]>
       }
     | undefined
-  // mtime plus size, so a same-mtime rewrite of a different length still invalidates.
-  const statToken = (file: string): string => {
-    const stat = fs.statSync(file)
-    return `${stat.mtimeMs}:${stat.size}`
-  }
   const memoIsFresh = (memo: NonNullable<typeof importMemo>): boolean => {
     try {
       return memo.tokens.every(([file, token]) => statToken(file) === token)

package/extensions/hooks/config.ts

@@ -0,0 +1,234 @@
+/**
+ * Hook configuration: the settings-chain resolution, the hooks loaders (settings
+ * files and plugins), the disableAllHooks / allowedHttpHookUrls readers, and the
+ * /hooks viewer formatting. Pure config-shape types and loading, no execution.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { readManagedSettings } from '../internal/managed-settings.js'
+import { type InstalledPlugin, substitutePluginVars } from '../internal/plugins.js'
+import { claudeSettingsChain } from '../internal/settings-chain.js'
+
+export interface HookCommand {
+  type?: string
+  command: string
+  /** exec-form: spawn `command` directly with these args and no shell (shell-form when
+   * absent). $ARGUMENTS in each arg is replaced with the event JSON. */
+  args?: string[]
+  timeout?: number
+  /** Claude's background contract, honored on `type: "command"` hooks only: `async` runs
+   * without blocking its event and with no timeout enforced; `asyncRewake` also runs in
+   * the background but keeps its timeout, and wakes the model when the hook exits 2
+   * (stderr, or stdout when stderr is empty, feeds back as a new turn). Background hooks
+   * render no decision; their JSON `systemMessage`/`additionalContext` reach the model on
+   * the next turn, and any still running are killed at session end. */
+  async?: boolean
+  asyncRewake?: boolean
+  /** http entries: the endpoint POSTed to; `command` mirrors it for dedup and display. */
+  url?: string
+  headers?: Record<string, string>
+  allowedEnvVars?: string[]
+  /** prompt entries: the prompt sent to the model (`$ARGUMENTS` = the event JSON). */
+  prompt?: string
+  /** mcp_tool entries: the connected server and tool to call, with optional input. */
+  server?: string
+  tool?: string
+  input?: Record<string, unknown>
+  /** prompt/agent entries: an optional model override; agent adds a system prompt. */
+  model?: string
+  systemPrompt?: string
+}
+export interface HookMatcher {
+  matcher?: string
+  hooks: HookCommand[]
+}
+
+/** Whether a hook runs in the background. Claude documents `async`/`asyncRewake` on
+ * `type: "command"` hooks only; on any other type the fields are inert and the hook
+ * blocks, exactly as Claude runs it. */
+export function isBackgroundHook(hook: HookCommand): boolean {
+  return (hook.type === undefined || hook.type === 'command') && (hook.async === true || hook.asyncRewake === true)
+}
+export type HooksConfig = Record<string, HookMatcher[]>
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Settings files to read, newest-winning. Project files load only when trusted, each
+ * the nearest of its name at or above cwd (bounded at the repository root, matching
+ * the approval walk), so a subdirectory session reads the settings that gated it. */
+export function hookFiles(cwd: string, home: string, trusted: boolean): string[] {
+  return claudeSettingsChain(cwd, home, trusted)
+}
+
+/** Claude's `disableAllHooks` setting: the escape hatch a user reaches for when a
+ * hook misbehaves, so it is honored before any hook runs. Disabled when managed
+ * settings or ANY file in the settings chain sets it to `true`; deliberately not
+ * last-file-wins, since a repository file re-enabling the hooks the user just
+ * disabled in their own settings would defeat the escape hatch. The chain itself
+ * already gates project files on trust (see hookFiles). */
+export function readDisableAllHooks(files: string[], managed: Record<string, unknown> = readManagedSettings()): boolean {
+  if (managed.disableAllHooks === true) return true
+  for (const file of files) {
+    try {
+      const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      if (isRecord(parsed) && parsed.disableAllHooks === true) return true
+    } catch {
+      // missing or invalid file: skip
+    }
+  }
+  return false
+}
+
+/** Claude's `allowedHttpHookUrls` setting: URL patterns http hooks may target, with
+ * `*` as a wildcard. Per Claude's documentation: undefined (no source sets the key)
+ * means no restrictions, an empty array blocks every http hook, and arrays merge
+ * across settings sources. Merging is a union of managed settings plus every file in
+ * the chain; the chain already gates project files on trust (see hookFiles), and a
+ * trusted project can run arbitrary shell hooks anyway, so letting it extend the
+ * allowlist is no escalation. */
+export function readAllowedHttpHookUrls(files: string[], managed: Record<string, unknown> = readManagedSettings()): string[] | undefined {
+  let found: string[] | undefined
+  const collect = (value: unknown): void => {
+    if (!Array.isArray(value)) return
+    found = [...(found ?? []), ...value.filter((entry): entry is string => typeof entry === 'string')]
+  }
+  collect(managed.allowedHttpHookUrls)
+  for (const file of files) {
+    try {
+      const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      if (isRecord(parsed)) collect(parsed.allowedHttpHookUrls)
+    } catch {
+      // missing or invalid file: skip
+    }
+  }
+  return found
+}
+
+/** Whether an http hook may target `url`. `*` in an allowlist entry matches any run
+ * of characters; everything else is literal and the whole URL must match. An
+ * undefined allowlist means the setting is absent, so there are no restrictions. */
+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`\$&`))
+    return new RegExp(`^${literal.join('.*')}$`).test(url)
+  })
+}
+
+export function loadHooks(files: string[], sources?: Map<HookMatcher, string>): HooksConfig {
+  const config: HooksConfig = {}
+  for (const file of files) {
+    let raw: string
+    try {
+      raw = fs.readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    mergeHooksJson(config, raw, file, sources)
+  }
+  return config
+}
+
+function mergeHooksJson(config: HooksConfig, raw: string, source: string, sources?: Map<HookMatcher, string>): void {
+  let parsed: { hooks?: HooksConfig }
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return
+  }
+  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.
+    const usable = matchers.filter((entry) => isUsableMatcher(entry, source, event))
+    if (usable.length === 0) continue
+    config[event] = [...(config[event] ?? []), ...usable]
+    // Each parse produces fresh entry objects, so object identity keys the /hooks
+    // viewer's source attribution without touching the entries themselves.
+    for (const entry of usable) sources?.set(entry, 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. */
+export function loadPluginHooks(config: HooksConfig, plugins: InstalledPlugin[], sources?: Map<HookMatcher, string>): void {
+  for (const plugin of plugins) {
+    const declared = plugin.manifest.hooks
+    // An inline hooks object; an array is not a valid hooks map (it would parse to
+    // numeric event keys), so it falls through to the default path rather than
+    // silently registering nothing.
+    if (declared !== null && typeof declared === 'object' && !Array.isArray(declared)) {
+      mergeHooksJson(config, substitutePluginVars(JSON.stringify({ hooks: declared }), plugin), `${plugin.name} (plugin.json)`, sources)
+      continue
+    }
+    const file = path.resolve(plugin.root, typeof declared === 'string' ? declared : path.join('hooks', 'hooks.json'))
+    try {
+      mergeHooksJson(config, substitutePluginVars(fs.readFileSync(file, 'utf-8'), plugin), file, sources)
+    } catch {
+      // a plugin without hooks contributes nothing
+    }
+  }
+}
+
+/** A matcher entry pi-code can run: an object whose `hooks` is a list. Anything else
+ * is reported by name and skipped, so one bad entry costs its own hooks, not the
+ * session's tool calls. */
+function isUsableMatcher(entry: unknown, file: string, event: string): entry is HookMatcher {
+  const candidate = entry as HookMatcher | null
+  if (candidate === null || typeof candidate !== 'object') {
+    console.warn(`pi-code-hooks: ignoring a non-object ${event} entry in ${file}`)
+    return false
+  }
+  if (candidate.hooks !== undefined && !Array.isArray(candidate.hooks)) {
+    console.warn(`pi-code-hooks: ignoring ${event} entry in ${file}: "hooks" must be a list`)
+    return false
+  }
+  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
+  }
+  return true
+}
+
+/** A hook entry's display identity for the /hooks viewer: the command for shell
+ * hooks, otherwise the type-qualified url / prompt / server:tool. A missing field
+ * is named rather than hidden, since a misconfigured entry is exactly what the
+ * viewer exists to surface. */
+function hookIdentity(hook: HookCommand | null | undefined): string {
+  // A hand-edited settings file can leave a null (or otherwise empty) entry in a
+  // hooks array; name it rather than let it crash the viewer that exists to surface
+  // exactly this kind of misconfiguration.
+  const record: Partial<HookCommand> = hook ?? {}
+  const type = record.type ?? 'command'
+  if (type === 'http') return `http: ${record.url ?? record.command ?? '(missing url)'}`
+  if (type === 'prompt' || type === 'agent') return `${type}: ${record.prompt ?? record.command ?? '(missing prompt)'}`
+  if (type === 'mcp_tool') return `mcp_tool: ${record.server ?? '(missing server)'}:${record.tool ?? '(missing tool)'}`
+  return `command: ${record.command ?? '(missing command)'}`
+}
+
+/** Render the resolved hooks config as a readable per-event summary for /hooks:
+ * one line per configured hook with its matcher, identity and, when known, the
+ * settings file it came from. Pure formatting of already-resolved data. */
+export function formatHooksSummary(config: HooksConfig, sources?: Map<HookMatcher, string>): string {
+  const lines: string[] = []
+  for (const [event, matchers] of Object.entries(config)) {
+    const entryLines: string[] = []
+    for (const entry of matchers) {
+      const matcher = entry.matcher || '*'
+      const source = sources?.get(entry)
+      const suffix = source ? ` (${source})` : ''
+      for (const hook of entry.hooks ?? []) {
+        entryLines.push(`  [${matcher}] ${hookIdentity(hook)}${suffix}`)
+      }
+    }
+    if (entryLines.length > 0) lines.push(`${event}:`, ...entryLines)
+  }
+  if (lines.length === 0) return 'No hooks configured. Add a "hooks" section to ~/.claude/settings.json or .claude/settings.json.'
+  return lines.join('\n')
+}

package/extensions/hooks/decisions.ts

@@ -0,0 +1,169 @@
+/**
+ * Turning hook output into decisions: parsing a hook's exit code / JSON into a
+ * block-or-allow verdict, running the gated PreToolUse and UserPromptSubmit passes,
+ * and shaping the PostToolUse feedback and system messages surfaced to the user.
+ */
+
+import type { ToolCallEventResult } from '@earendil-works/pi-coding-agent'
+import { type HookCommand, type HooksConfig, isRecord } from './config.js'
+import { matchingCommands } from './matcher.js'
+import { type HookRunner, type HookRunResult, timeoutMs } from './runners.js'
+
+export interface HookDecision {
+  block: boolean
+  reason?: string
+  /** Claude's `permissionDecision: "ask"`: the caller should prompt the user and
+   * block only on decline. `block` stays true as the no-UI fallback. */
+  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 {
+  try {
+    return JSON.parse(text)
+  } catch {
+    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)
+  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' }
+  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 }
+}
+
+/** Claude's updatedInput replaces the whole tool_input, and pi's tool_call contract is
+ * in-place mutation, so the target object is emptied and refilled rather than reassigned. */
+function replaceRecord(target: Record<string, unknown>, next: Record<string, unknown>): void {
+  for (const key of Object.keys(target)) delete target[key]
+  Object.assign(target, next)
+}
+
+/** Claude surfaces a hook error notice; on ungated events the action proceeds, while
+ * PreToolUse and UserPromptSubmit additionally fail closed on the same results (see
+ * their spawnFailed checks). Silence would hide that a guard never ran. */
+function surfaceHookFailures(commands: HookCommand[], results: HookRunResult[], notify?: SystemMessageSink): void {
+  if (!notify) return
+  for (const [i, result] of results.entries()) {
+    if (result.spawnFailed) notify(`Hook failed to run: ${commands[i].command}: ${result.stderr.trim() || 'unknown error'}`)
+  }
+}
+
+/** 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)
+  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.
+    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'}` }
+  }
+  if (onSystemMessage) surfaceSystemMessages(results, onSystemMessage)
+  // 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
+  for (const result of results) {
+    const decision = interpretHookResult(result.code, result.stdout, result.stderr)
+    if (decision.block && !decision.ask) return decision
+    if (decision.ask && ask === undefined) ask = decision
+  }
+  return ask ?? { block: false }
+}
+
+type SystemMessageSink = (message: string) => void
+
+/** Claude's universal systemMessage output field: a warning surfaced to the user. */
+export function surfaceSystemMessages(results: HookRunResult[], notify: SystemMessageSink): void {
+  for (const result of results) {
+    const message = tryParseJson(result.stdout)?.systemMessage
+    if (message) notify(message)
+  }
+}
+
+export interface PromptDecision {
+  block: boolean
+  reason?: string
+  context: string
+}
+
+/** Additional context a UserPromptSubmit hook contributes: an explicit
+ * hookSpecificOutput.additionalContext, or the raw stdout of a plain exit-0 hook. */
+export function promptContext(stdout: string): string {
+  const parsed = tryParseJson(stdout)
+  if (parsed) return parsed.hookSpecificOutput?.additionalContext ?? ''
+  return stdout.trim()
+}
+
+/** 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. */
+export async function runUserPromptSubmit(config: HooksConfig, prompt: string, runner: HookRunner, onSystemMessage?: SystemMessageSink): Promise<PromptDecision> {
+  const commands = matchingCommands(config.UserPromptSubmit, 'UserPromptSubmit')
+  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()) {
+    if (result.timedOut) return { block: true, reason: `Hook timed out after ${timeoutMs(commands[i])}ms: ${commands[i].command}`, context: '' }
+    // No verdict was delivered, so fail closed like a timeout (see runPreToolUse).
+    if (result.spawnFailed) return { block: true, reason: `Hook failed to run: ${commands[i].command}: ${result.stderr.trim() || 'unknown error'}`, context: '' }
+  }
+  if (onSystemMessage) surfaceSystemMessages(results, onSystemMessage)
+  const contexts: string[] = []
+  for (const result of results) {
+    const decision = interpretHookResult(result.code, result.stdout, result.stderr)
+    if (decision.block) return { block: true, reason: decision.reason, context: '' }
+    const context = promptContext(result.stdout)
+    if (context) contexts.push(context)
+  }
+  return { block: false, context: contexts.join('\n') }
+}
+
+/** The feedback lines one PostToolUse/PostToolUseFailure result appends next to the
+ * tool result: a block notice (exit-2 stderr, or decision:block on success) followed
+ * by any additionalContext. A failed tool cannot be blocked, so its stderr is shown
+ * but never a decision:block verdict. */
+export function postToolFeedback(result: HookRunResult, eventName: string, isError: boolean): string[] {
+  const lines: string[] = []
+  const parsed = tryParseJson(result.stdout)
+  // 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'}`)
+  const context = parsed?.hookSpecificOutput?.additionalContext
+  if (context) lines.push(context)
+  return lines
+}
+
+/** A blocked tool_call verdict carrying pi's `terminate` flag (#7715): with it set on
+ * an all-terminating tool batch, pi skips the automatic follow-up model call that a plain
+ * block would otherwise pay for. */
+export function blockedToolCall(reason: string | undefined): ToolCallEventResult {
+  return { block: true, reason, terminate: true }
+}