pi-code 1.0.5 → 1.0.6

package/extensions/context-imports.ts

@@ -159,34 +159,60 @@ function readImport(target: string, fromDir: string, home: string, allowedRoots:
   }
 }
 
-/**
- * Collect the contents of every file transitively imported via `@path`, in
- * discovery order. Imports are resolved through symlinks and kept within
- * `allowedRoots` (which must already be realpath'd).
- */
-export function collectImports(content: string, fromDir: string, home: string, allowedRoots: string[], seen: Set<string>, budget: ImportBudget = createImportBudget(), depth = 0, importer?: string, isExcluded?: (realPath: string) => boolean): ImportedFile[] {
+/** Optional controls for a collection run: the byte/file budget shared across the
+ * whole run, the path of the file this content came from (seeds each top-level
+ * import's `parent`), and the exclusion predicate. Recursion depth is internal. */
+export interface CollectImportsOptions {
+  budget?: ImportBudget
+  importer?: string
+  isExcluded?: (realPath: string) => boolean
+}
+
+/** The parts of a collection run that stay fixed across the recursion: resolution
+ * roots, the seen/budget accumulators, and the exclusion predicate. Only content,
+ * fromDir, depth and the parent path change from one level to the next. */
+interface ImportScan {
+  home: string
+  allowedRoots: string[]
+  seen: Set<string>
+  budget: ImportBudget
+  isExcluded?: (realPath: string) => boolean
+}
+
+/** One recursion level: read the imports named in `content`, then recurse into each. */
+function collectFrom(scan: ImportScan, content: string, fromDir: string, depth: number, importer?: string): ImportedFile[] {
   if (depth >= MAX_IMPORT_DEPTH) return []
   const out: ImportedFile[] = []
   for (const target of importTargets(content)) {
     // Checked before the read so an exhausted budget costs no I/O.
-    if (budget.files === 0 || budget.bytes === 0) {
-      budget.dropped += 1
+    if (scan.budget.files === 0 || scan.budget.bytes === 0) {
+      scan.budget.dropped += 1
       continue
     }
-    const file = readImport(target, fromDir, home, allowedRoots, seen, isExcluded)
+    const file = readImport(target, fromDir, scan.home, scan.allowedRoots, scan.seen, scan.isExcluded)
     if (!file) continue
-    budget.files -= 1
-    const kept = file.body.slice(0, budget.bytes)
-    budget.bytes -= kept.length
+    scan.budget.files -= 1
+    const kept = file.body.slice(0, scan.budget.bytes)
+    scan.budget.bytes -= kept.length
     const body = kept.length < file.body.length ? `${kept.trim()}\n${IMPORT_TRUNCATED_MARKER}` : kept.trim()
     // Comments are stripped before the scan for further imports, so a
     // commented-out @import stays dead at every depth, matching the top level
     // (whose bodies arrive here already stripped by the caller).
-    out.push({ path: file.real, body, parent: importer }, ...collectImports(stripBlockComments(kept), path.dirname(file.real), home, allowedRoots, seen, budget, depth + 1, file.real, isExcluded))
+    out.push({ path: file.real, body, parent: importer }, ...collectFrom(scan, stripBlockComments(kept), path.dirname(file.real), depth + 1, file.real))
   }
   return out
 }
 
+/**
+ * Collect the contents of every file transitively imported via `@path`, in
+ * discovery order. Imports are resolved through symlinks and kept within
+ * `allowedRoots` (which must already be realpath'd).
+ */
+export function collectImports(content: string, fromDir: string, home: string, allowedRoots: string[], seen: Set<string>, options: CollectImportsOptions = {}): ImportedFile[] {
+  const scan: ImportScan = { home, allowedRoots, seen, budget: options.budget ?? createImportBudget(), isExcluded: options.isExcluded }
+  return collectFrom(scan, content, fromDir, 0, options.importer)
+}
+
 /**
  * Roots an importing file may pull from.
  *
@@ -357,6 +383,114 @@ export function isExcludedPath(absPath: string, globs: string[], home: string):
   })
 }
 
+/** Apply claudeMdExcludes and comment-stripping to pi's native context blocks,
+ * rewriting the assembled prompt by exact substring: an excluded file's block is
+ * removed, a surviving file's block is replaced with its comment-stripped body. A
+ * wrapper not found in the prompt is skipped rather than risk corrupting it.
+ * Returns the rewritten prompt and the files that survived exclusion (stripped). */
+function rewriteNativeBlocks(prompt: string, native: Array<{ path: string; content: string }>, excluded: (absPath: string) => boolean): { prompt: string; changed: boolean; kept: Array<{ path: string; content: string }> } {
+  let changed = false
+  const kept: Array<{ path: string; content: string }> = []
+  for (const file of native) {
+    const wrapper = instructionsBlock(file.path, file.content)
+    if (excluded(file.path)) {
+      const removed = removeBlock(prompt, wrapper)
+      if (removed !== null) {
+        prompt = removed
+        changed = true
+      }
+      continue
+    }
+    const stripped = stripBlockComments(file.content)
+    if (stripped !== file.content) {
+      const replaced = replaceBlock(prompt, wrapper, instructionsBlock(file.path, stripped))
+      if (replaced !== null) {
+        prompt = replaced
+        changed = true
+      }
+    }
+    kept.push({ path: file.path, content: stripped })
+  }
+  return { prompt, changed, kept }
+}
+
+/** Claude's --add-dir memory files, minus any pi already loaded natively (added to
+ * `seenSet` here so an @import cannot pull one in twice) and any the excludes drop
+ * or that strip to nothing. Each survivor is comment-stripped and tagged with its
+ * additional dir, so its relative imports can resolve from there. */
+function additionalDirExtras(addDirs: string[], seenSet: Set<string>, excluded: (absPath: string) => boolean, includeLocal: boolean): Array<{ path: string; content: string; dir: string }> {
+  const extras: Array<{ path: string; content: string; dir: string }> = []
+  for (const dir of addDirs) {
+    for (const file of additionalDirContextFiles(dir, includeLocal)) {
+      const [real] = realRoots([file.path])
+      const key = real ?? file.path
+      if (seenSet.has(key)) continue // pi already loaded it natively
+      seenSet.add(key)
+      if (excluded(file.path)) continue
+      const stripped = stripBlockComments(file.content)
+      if (stripped.trim().length === 0) continue
+      extras.push({ path: file.path, content: stripped, dir })
+    }
+  }
+  return extras
+}
+
+/** Resolve every context and additional-dir file's @imports through the one shared
+ * budget, each with roots scoped to the importing file so a project file never
+ * reaches user config. */
+function expandImports(contextFiles: Array<{ path: string; content: string }>, extras: Array<{ path: string; content: string; dir: string }>, home: string, cwd: string, seenSet: Set<string>, excluded: (absPath: string) => boolean, budget: ImportBudget): ImportedFile[] {
+  const imported: ImportedFile[] = []
+  for (const file of contextFiles) {
+    const allowedRoots = rootsForImporter(file.path, home, cwd)
+    imported.push(...collectImports(file.content, path.dirname(file.path), home, allowedRoots, seenSet, { budget, importer: file.path, isExcluded: excluded }))
+  }
+  for (const extra of extras) {
+    // The additional dir itself is an allowed root, so its files' relative imports
+    // resolve even from .claude/rules two levels down.
+    const allowedRoots = [...realRoots([extra.dir]), ...rootsForImporter(extra.path, home, cwd)]
+    imported.push(...collectImports(extra.content, path.dirname(extra.path), home, allowedRoots, seenSet, { budget, importer: extra.path, isExcluded: excluded }))
+  }
+  return imported
+}
+
+/** The CLAUDE.local.md bodies appended after the native context, announced as they
+ * are added (only the non-empty ones, matching what actually reaches the prompt). */
+function localContextAddition(keptLocals: Array<{ path: string; content: string }>, announce: (event: InstructionLoadEvent) => void): string {
+  let addition = ''
+  for (const local of keptLocals) {
+    if (local.content.trim().length > 0) {
+      addition += `\n\n## CLAUDE.local.md (${local.path})\n\n${local.content.trim()}`
+      announce({ file_path: local.path, memory_type: 'Local', load_reason: 'session_start' })
+    }
+  }
+  return addition
+}
+
+/** The --add-dir memory files appended as extra project_instructions blocks.
+ * Additional dirs are extra working directories, so their files are Project-typed
+ * regardless of where the dir sits (Local for a CLAUDE.local.md). */
+function additionalDirsAddition(extras: Array<{ path: string; content: string; dir: string }>, announce: (event: InstructionLoadEvent) => void): string {
+  let addition = ''
+  for (const extra of extras) {
+    addition += `\n\n${instructionsBlock(extra.path, extra.content)}`
+    announce({ file_path: extra.path, memory_type: path.basename(extra.path) === 'CLAUDE.local.md' ? 'Local' : 'Project', load_reason: 'session_start' })
+  }
+  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. */
+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')
+  const notice = budget.dropped === 0 ? '' : `\n\n${budget.dropped} further @imports were skipped: the import budget (${MAX_IMPORT_FILES} files, ${MAX_IMPORT_BYTES} bytes) is spent.`
+  for (const entry of imported) {
+    announce({ file_path: entry.path, memory_type: memoryTypeForPath(entry.path, home, projectRoot), load_reason: 'include', ...(entry.parent === undefined ? {} : { parent_file_path: entry.parent }) })
+  }
+  return `\n\n## Imported context (@)\n\n${section}${notice}`
+}
+
 export default function contextImportsExtension(pi: ExtensionAPI) {
   let localContexts: Array<{ path: string; content: string }> = []
   // Whether project settings may contribute claudeMdExcludes; decided at session
@@ -416,37 +550,16 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     const excluded = (absPath: string): boolean => isExcludedPath(absPath, excludeGlobs, home)
     const projectRoot = repoRoot(cwd) ?? cwd
 
-    let prompt = event.systemPrompt
-    let changed = false
-
     // claudeMdExcludes drops an excluded file's block from the assembled prompt and
     // from import expansion; surviving blocks get block-level comments stripped.
-    // Both rewrite by exact substring: a wrapper that is not found in the prompt is
-    // skipped rather than risk corrupting it.
-    const keptNative: Array<{ path: string; content: string }> = []
-    for (const file of native) {
-      const wrapper = instructionsBlock(file.path, file.content)
-      if (excluded(file.path)) {
-        const removed = removeBlock(prompt, wrapper)
-        if (removed !== null) {
-          prompt = removed
-          changed = true
-        }
-        continue
-      }
-      const stripped = stripBlockComments(file.content)
-      if (stripped !== file.content) {
-        const replaced = replaceBlock(prompt, wrapper, instructionsBlock(file.path, stripped))
-        if (replaced !== null) {
-          prompt = replaced
-          changed = true
-        }
-      }
-      keptNative.push({ path: file.path, content: stripped })
-      // Exclusion is owned here, so the session_start InstructionsLoaded events
-      // for pi's native context files are published here too, only for files
-      // that actually survived it: Claude fires no event for a file it never
-      // loaded. The hooks extension consumes them off the shared bus.
+    const rewrite = rewriteNativeBlocks(event.systemPrompt, native, excluded)
+    let prompt = rewrite.prompt
+    let changed = rewrite.changed
+    // Exclusion is owned here, so the session_start InstructionsLoaded events for
+    // pi's native context files are published here too, only for files that
+    // survived it: Claude fires no event for a file it never loaded. The hooks
+    // extension consumes them off the shared bus.
+    for (const file of rewrite.kept) {
       announce({ file_path: file.path, memory_type: memoryTypeForPath(file.path, home, projectRoot), load_reason: 'session_start' })
     }
 
@@ -460,69 +573,27 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     }
 
     const keptLocals = localContexts.filter((local) => !excluded(local.path)).map((local) => ({ path: local.path, content: stripBlockComments(local.content) }))
-    const contextFiles = [...keptNative, ...keptLocals]
+    const contextFiles = [...rewrite.kept, ...keptLocals]
 
     // Seed with every loaded context file path, excluded ones included, so pi's own
     // files are never re-imported and an excluded file cannot return as an import.
-    const seen = realRoots([...native, ...localContexts].map((file) => file.path))
-    const seenSet = new Set(seen)
+    const seenSet = new Set(realRoots([...native, ...localContexts].map((file) => file.path)))
 
     // Claude's --add-dir memory loading, env-gated. The files join the seen set
     // before import expansion so an @import cannot pull one in twice, and they get
     // the same exclude and comment-strip treatment as native context files.
     const addDirs = additionalDirsClaudeMdEnabled() ? parseAdditionalDirs(pi.getFlag?.('add-dir'), home, cwd) : []
-    const extras: Array<{ path: string; content: string; dir: string }> = []
-    for (const dir of addDirs) {
-      for (const file of additionalDirContextFiles(dir, projectApproved)) {
-        const [real] = realRoots([file.path])
-        const key = real ?? file.path
-        if (seenSet.has(key)) continue // pi already loaded it natively
-        seenSet.add(key)
-        if (excluded(file.path)) continue
-        const stripped = stripBlockComments(file.content)
-        if (stripped.trim().length === 0) continue
-        extras.push({ path: file.path, content: stripped, dir })
-      }
-    }
+    const extras = additionalDirExtras(addDirs, seenSet, excluded, projectApproved)
 
-    const imported: ImportedFile[] = []
     // One budget for the whole run, so N context files cannot each spend a full one.
     // Exclusion applies inside the recursion: an excluded @import is skipped before
     // it is read, so its transitive imports never load and it spends no budget.
     const budget = createImportBudget()
-    for (const file of contextFiles) {
-      // Roots are scoped per importing file: a project file never reaches user config.
-      const allowedRoots = rootsForImporter(file.path, home, cwd)
-      imported.push(...collectImports(file.content, path.dirname(file.path), home, allowedRoots, seenSet, budget, 0, file.path, excluded))
-    }
-    for (const extra of extras) {
-      // The additional dir itself is an allowed root, so its files' relative
-      // imports resolve even from .claude/rules two levels down.
-      const allowedRoots = [...realRoots([extra.dir]), ...rootsForImporter(extra.path, home, cwd)]
-      imported.push(...collectImports(extra.content, path.dirname(extra.path), home, allowedRoots, seenSet, budget, 0, extra.path, excluded))
-    }
+    const imported = expandImports(contextFiles, extras, home, cwd, seenSet, excluded, budget)
 
-    let addition = ''
-    for (const local of keptLocals) {
-      if (local.content.trim().length > 0) {
-        addition += `\n\n## CLAUDE.local.md (${local.path})\n\n${local.content.trim()}`
-        announce({ file_path: local.path, memory_type: 'Local', load_reason: 'session_start' })
-      }
-    }
-    for (const extra of extras) {
-      addition += `\n\n${instructionsBlock(extra.path, extra.content)}`
-      // Additional dirs are extra working directories, so their memory files are
-      // Project-typed regardless of where the dir sits (Local for CLAUDE.local.md).
-      announce({ file_path: extra.path, memory_type: path.basename(extra.path) === 'CLAUDE.local.md' ? 'Local' : 'Project', load_reason: 'session_start' })
-    }
-    if (imported.length > 0) {
-      const section = imported.map((entry) => `### ${entry.path}\n\n${stripBlockComments(entry.body)}`).join('\n\n')
-      const notice = budget.dropped === 0 ? '' : `\n\n${budget.dropped} further @imports were skipped: the import budget (${MAX_IMPORT_FILES} files, ${MAX_IMPORT_BYTES} bytes) is spent.`
-      addition += `\n\n## Imported context (@)\n\n${section}${notice}`
-      for (const entry of imported) {
-        announce({ file_path: entry.path, memory_type: memoryTypeForPath(entry.path, home, projectRoot), load_reason: 'include', ...(entry.parent === undefined ? {} : { parent_file_path: entry.parent }) })
-      }
-    }
+    let addition = localContextAddition(keptLocals, announce)
+    addition += additionalDirsAddition(extras, announce)
+    addition += importedAddition(imported, budget, home, projectRoot, announce)
     if (!changed && addition.length === 0) return
 
     return { systemPrompt: prompt + addition }

package/extensions/hooks.ts

@@ -43,7 +43,10 @@
  *
  * Config is merged from ~/.claude/settings.json (always) plus the project's
  * .claude/settings.json and settings.local.json (only when the project is
- * trusted, since hooks execute arbitrary shell). Matchers follow Claude's rule:
+ * trusted, since hooks execute arbitrary shell). Claude's `disableAllHooks`
+ * setting (managed settings or any honored file in that chain) short-circuits
+ * the load entirely, so no event fires any hook; /hooks prints the resolved
+ * chain per event with each entry's source settings file. Matchers follow Claude's rule:
  * `*`/empty match all, plain names are exact (with `|`/`,` list separators), and
  * anything with other regex characters is an unanchored regex. Claude matchers
  * are PascalCase (`Bash`); pi tool names are lowercase (`bash`), so comparison
@@ -60,6 +63,7 @@ import type { Api, Model } from '@earendil-works/pi-ai'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { runAgent } from './internal/agent-run.js'
 import { INSTRUCTIONS_CHANNEL, isInstructionLoadEvent } from './internal/instruction-events.js'
+import { readManagedSettings } from './internal/managed-settings.js'
 import { isMcpToolAliases, MCP_TOOLS_CHANNEL } from './internal/mcp-alias.js'
 import { callMcpTool } from './internal/mcp-call.js'
 import { completeText } from './internal/model-complete.js'
@@ -94,7 +98,7 @@ interface HookCommand {
   model?: string
   systemPrompt?: string
 }
-interface HookMatcher {
+export interface HookMatcher {
   matcher?: string
   hooks: HookCommand[]
 }
@@ -133,7 +137,26 @@ export function hookFiles(cwd: string, home: string, trusted: boolean): string[]
   return files
 }
 
-export function loadHooks(files: string[]): HooksConfig {
+/** 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
+}
+
+export function loadHooks(files: string[], sources?: Map<HookMatcher, string>): HooksConfig {
   const config: HooksConfig = {}
   for (const file of files) {
     let raw: string
@@ -142,12 +165,12 @@ export function loadHooks(files: string[]): HooksConfig {
     } catch {
       continue
     }
-    mergeHooksJson(config, raw, file)
+    mergeHooksJson(config, raw, file, sources)
   }
   return config
 }
 
-function mergeHooksJson(config: HooksConfig, raw: string, source: string): void {
+function mergeHooksJson(config: HooksConfig, raw: string, source: string, sources?: Map<HookMatcher, string>): void {
   let parsed: { hooks?: HooksConfig }
   try {
     parsed = JSON.parse(raw)
@@ -161,26 +184,30 @@ function mergeHooksJson(config: HooksConfig, raw: string, source: string): void
     // 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) config[event] = [...(config[event] ?? []), ...usable]
+    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[]): void {
+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)`)
+      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)
+      mergeHooksJson(config, substitutePluginVars(fs.readFileSync(file, 'utf-8'), plugin), file, sources)
     } catch {
       // a plugin without hooks contributes nothing
     }
@@ -249,6 +276,23 @@ function isRunnableHook(hook: HookCommand): boolean {
   return typeof hook.command === 'string' && (hook.type === undefined || hook.type === 'command')
 }
 
+/** The synthetic identity of a non-shell hook entry: an http/prompt/agent/mcp_tool
+ * entry has no `command`, so its url / prompt / server:tool stands in. A shell hook
+ * (undefined or `command` type) already has one, so this is undefined. */
+function syntheticCommand(hook: HookCommand): string | undefined {
+  if (hook.type === 'http') return hook.url
+  if (hook.type === 'prompt' || hook.type === 'agent') return hook.prompt
+  if (hook.type === 'mcp_tool') return `${hook.server}:${hook.tool}`
+  return undefined
+}
+
+/** A matched entry with its `command` filled in: mirroring the synthetic identity into
+ * `command` keeps dedup, timeout messages and display working for non-shell hooks. */
+function withCommand(raw: HookCommand): HookCommand {
+  const identity = syntheticCommand(raw)
+  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[] {
@@ -258,11 +302,7 @@ export function matchingCommands(matchers: HookMatcher[] | undefined, names: str
   for (const entry of matchers ?? []) {
     if (!matcherApplies(entry.matcher, candidates)) continue
     for (const raw of (entry.hooks ?? []).filter(isRunnableHook)) {
-      // An http/prompt/agent/mcp_tool entry has no `command`; its identity is the
-      // url / prompt / server:tool. Mirroring it into `command` keeps dedup, timeout
-      // messages and display working.
-      const identity = raw.type === 'http' ? raw.url : raw.type === 'prompt' || raw.type === 'agent' ? raw.prompt : raw.type === 'mcp_tool' ? `${raw.server}:${raw.tool}` : undefined
-      const hook = identity !== undefined && typeof raw.command !== 'string' ? { ...raw, command: identity } : raw
+      const hook = withCommand(raw)
       // Claude runs a handler defined in more than one settings file once.
       if (seen.has(hook.command)) continue
       seen.add(hook.command)
@@ -272,6 +312,43 @@ export function matchingCommands(matchers: HookMatcher[] | undefined, names: str
   return result
 }
 
+/** 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')
+}
+
 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)
@@ -369,7 +446,7 @@ function interpolateHeaders(headers: Record<string, string> | undefined, allowed
   const allowedSet = new Set(allowed ?? [])
   const out: Record<string, string> = {}
   for (const [key, value] of Object.entries(headers ?? {})) {
-    out[key] = value.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_token, braced?: string, bare?: string) => {
+    out[key] = value.replace(/\$(?:\{([A-Za-z_]\w*)\}|([A-Za-z_]\w*))/g, (_token, braced?: string, bare?: string) => {
       const name = braced ?? bare ?? ''
       return allowedSet.has(name) ? (process.env[name] ?? '') : ''
     })
@@ -646,12 +723,32 @@ function claudeSpelling(map: Record<string, string>, raw: string): { names: stri
   return { names: value === raw ? [raw] : [raw, value], value }
 }
 
+/** 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. */
+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
+}
+
 export default function hooksExtension(pi: ExtensionAPI) {
   let config: HooksConfig = {}
   let projectDir = ''
   let pendingSessionContext: string[] = []
   let stopHookActive = false
   let sessionCtx: ExtensionContext | undefined
+  /** Claude's disableAllHooks escape hatch was set somewhere in the honored chain. */
+  let hooksDisabled = false
+  /** Which settings file each resolved entry came from, for the /hooks viewer. */
+  const hookSources = new Map<HookMatcher, 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 }
@@ -728,10 +825,20 @@ export default function hooksExtension(pi: ExtensionAPI) {
     // referencing $CLAUDE_PROJECT_DIR/.claude/hooks/helper.sh must resolve from a
     // subdirectory session too.
     projectDir = repoRoot(ctx.cwd) ?? ctx.cwd
-    config = loadHooks(hookFiles(ctx.cwd, os.homedir(), trusted))
+    const files = hookFiles(ctx.cwd, os.homedir(), trusted)
+    hookSources.clear()
+    // The disableAllHooks escape hatch, checked before any config loads: with no
+    // config resolved, no event, plugin hooks included, can fire a hook.
+    hooksDisabled = readDisableAllHooks(files)
+    if (hooksDisabled) {
+      config = {}
+      pendingSessionContext = []
+      return
+    }
+    config = loadHooks(files, hookSources)
     // Plugins are user-installed and enabled by user settings (see installedPlugins),
     // so a checked-out repo cannot toggle which code-bearing plugin hooks run.
-    loadPluginHooks(config, installedPlugins(os.homedir()))
+    loadPluginHooks(config, installedPlugins(os.homedir()), hookSources)
     // "reload" re-fires in-process with the same conversation and would double-run hooks;
     // a fork is a genuine session begin, which Claude reports as source "fork".
     if (event.reason === 'reload') return
@@ -784,16 +891,7 @@ export default function hooksExtension(pi: ExtensionAPI) {
     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: string[] = []
-    for (const result of results) {
-      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) feedback.push(`${eventName} hook: ${result.stderr.trim() || (event.isError ? 'hook reported an error' : 'Blocked by hook')}`)
-      else if (!event.isError && parsed?.decision === 'block') feedback.push(`PostToolUse hook: ${parsed.reason ?? 'Blocked by hook'}`)
-      const context = parsed?.hookSpecificOutput?.additionalContext
-      if (context) feedback.push(context)
-    }
+    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 }))] }
   })
@@ -869,4 +967,18 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const results = await runNotifyHooks(matchingCommands(config.SessionEnd, reason.names), { hook_event_name: 'SessionEnd', reason: reason.value }, boundRunner(ctx))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
   })
+
+  // Claude's /hooks manages hook configuration; pi-code's is a viewer: hook failures
+  // are otherwise opaque, so showing the resolved chain per event, with the settings
+  // file each entry came from, is the debugging surface.
+  pi.registerCommand('hooks', {
+    description: 'Show the hook configuration resolved from settings',
+    handler: async (_args, ctx) => {
+      if (hooksDisabled) {
+        ctx.ui.notify('All hooks are disabled by the disableAllHooks setting.', 'info')
+        return
+      }
+      ctx.ui.notify(formatHooksSummary(config, hookSources), 'info')
+    },
+  })
 }