pi-code 1.0.5 → 1.0.7

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,62 @@ 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
+}
+
+/** 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
@@ -142,12 +201,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 +220,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 +312,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 +338,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 +348,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 +482,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] ?? '') : ''
     })
@@ -382,12 +495,15 @@ function interpolateHeaders(headers: Record<string, string> | undefined, allowed
  * with a valid JSON body renders a decision, read exactly like command stdout.
  * Everything else, including non-2xx statuses, connection failures and timeouts,
  * is a non-blocking error by contract, so none of these outcomes ever reports
- * `timedOut`, which PreToolUse fails closed on. The user wrote the URL into their
- * own settings, so it carries the same trust as a command hook's shell string and
- * gets no SSRF screening.
+ * `timedOut`, which PreToolUse fails closed on. Claude's `allowedHttpHookUrls`
+ * allowlist gates the fetch itself: a URL matching no entry is never contacted,
+ * so a settings file cannot point a hook at an arbitrary endpoint and exfiltrate
+ * the payload; when the setting is absent there are no restrictions, as Claude
+ * documents. A blocked hook renders no decision, like every other http failure.
  */
-export async function runHttpHook(hook: { type?: string; command: string; url?: string; headers?: Record<string, string>; allowedEnvVars?: string[] }, payload: unknown, timeoutMs: number): Promise<HookRunResult> {
+export async function runHttpHook(hook: { type?: string; command: string; url?: string; headers?: Record<string, string>; allowedEnvVars?: string[] }, payload: unknown, timeoutMs: number, allowedUrls?: string[]): Promise<HookRunResult> {
   const url = hook.url ?? hook.command
+  if (!httpUrlAllowed(url, allowedUrls)) return { code: 1, stdout: '', stderr: `${url} does not match allowedHttpHookUrls; the hook was not called`, timedOut: false }
   try {
     const response = await fetch(url, {
       method: 'POST',
@@ -538,8 +654,9 @@ function replaceRecord(target: Record<string, unknown>, next: Record<string, unk
   Object.assign(target, next)
 }
 
-/** Claude surfaces a hook error notice and the action proceeds; silence would read a
- * guard that never ran as a clean allow. */
+/** 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()) {
@@ -571,6 +688,10 @@ export async function runPreToolUse(config: HooksConfig, toolName: string, toolI
     // 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:
@@ -621,6 +742,8 @@ export async function runUserPromptSubmit(config: HooksConfig, prompt: string, r
   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[] = []
@@ -646,12 +769,34 @@ 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 = ''
+  /** Claude's allowedHttpHookUrls allowlist, resolved from the settings chain. */
+  let allowedHttpHookUrls: string[] | undefined
   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 }
@@ -666,7 +811,7 @@ export default function hooksExtension(pi: ExtensionAPI) {
     (ctx: ExtensionContext, extra?: Record<string, unknown>): HookRunner =>
     (hook, payload, ms) => {
       const merged = { ...commonPayload(ctx), ...extra, ...(payload as Record<string, unknown>) }
-      if (hook.type === 'http') return runHttpHook(hook, merged, ms)
+      if (hook.type === 'http') return runHttpHook(hook, merged, ms, allowedHttpHookUrls)
       if (hook.type === 'prompt') return runPromptHook(hook, merged, ctx.model, ms)
       if (hook.type === 'agent') return runAgentHook(hook, merged, ms, (ctx.model as { id?: string } | undefined)?.id)
       if (hook.type === 'mcp_tool') return runMcpToolHook(hook, merged, ms)
@@ -717,8 +862,14 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const ctx = sessionCtx
     const eventName = data.phase === 'start' ? 'SubagentStart' : 'SubagentStop'
     const payload = { hook_event_name: eventName, agent_type: data.agentType, agent_id: data.agentId }
-    const results = await runNotifyHooks(matchingCommands(config[eventName], data.agentType), payload, boundRunner(ctx))
-    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    try {
+      const results = await runNotifyHooks(matchingCommands(config[eventName], data.agentType), payload, boundRunner(ctx))
+      surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    } catch {
+      // The bus outlives the session: an event landing between /new disposing this
+      // ctx and the next session_start hits disposed getters, and nothing awaits a
+      // bus listener, so a throw here would escape as an unhandled rejection.
+    }
   })
 
   pi.on('session_start', async (event, ctx) => {
@@ -728,10 +879,21 @@ 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()
+    allowedHttpHookUrls = readAllowedHttpHookUrls(files)
+    // 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 +946,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 +1022,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')
+    },
+  })
 }

package/extensions/internal/command-file.ts

@@ -16,6 +16,9 @@ import { parseFrontmatter } from '@earendil-works/pi-coding-agent'
 
 import { splitSegments } from './shell-split.js'
 
+/** The pi file tools a Claude path rule can govern. */
+export type PathRuleTool = 'read' | 'edit' | 'write'
+
 export interface ParsedCommand {
   description: string
   argumentHint?: string
@@ -23,7 +26,7 @@ export interface ParsedCommand {
   /** Claude `Bash(...)` specifiers, present only when every bash grant is scoped. */
   bashRules?: string[]
   /** Claude path rules per pi file tool, from Read(...)/Edit(...)/Write(...) grants. */
-  pathRules?: Partial<Record<'read' | 'edit' | 'write', string[]>>
+  pathRules?: Partial<Record<PathRuleTool, string[]>>
   /** Names from the `arguments:` frontmatter list, mapped to positions in order. */
   argumentNames?: string[]
   /** Tools removed from the pool while the command's turn runs. */
@@ -66,6 +69,10 @@ const CLAUDE_TOOL_MAP: Record<string, string> = {
   task: 'subagent',
   askuserquestion: 'question',
   exitplanmode: 'plan_mode_complete',
+  // Claude's name for the tool this package registers so the model can run user slash
+  // commands; without it `allowed-tools: SlashCommand` matched nothing and the grant
+  // could neither keep nor drop the tool.
+  slashcommand: 'slash_command',
 }
 
 /**
@@ -118,18 +125,78 @@ export interface ToolGrants {
   /** Claude path rules per pi file tool, absent for a tool with an unscoped grant.
    * Edit scopes govern writes too, as Claude documents; Write scopes are honored
    * rather than Claude's accept-and-warn-then-ignore, which would fail open here. */
-  pathRules?: Partial<Record<'read' | 'edit' | 'write', string[]>>
+  pathRules?: Partial<Record<PathRuleTool, string[]>>
   /** Entries that carried an argument scope, in their original spelling. */
   scopedEntries: string[]
 }
 
 /** The pi file tools one Claude path-ruled entry governs. */
-const PATH_RULE_TOOLS: Record<string, Array<'read' | 'edit' | 'write'>> = {
+const PATH_RULE_TOOLS: Record<string, Array<PathRuleTool>> = {
   read: ['read'],
   edit: ['edit', 'write'],
   write: ['write'],
 }
 
+/** The tools, scopes, and path rules accumulated while scanning one grant list. */
+interface GrantAccumulator {
+  tools: string[]
+  scopedEntries: string[]
+  bashRules: string[]
+  bashUnscoped: boolean
+  pathScopes: Record<PathRuleTool, string[]>
+  pathUnscoped: Set<PathRuleTool>
+}
+
+function createGrantAccumulator(): GrantAccumulator {
+  return { tools: [], scopedEntries: [], bashRules: [], bashUnscoped: false, pathScopes: { read: [], edit: [], write: [] }, pathUnscoped: new Set() }
+}
+
+/** Coerce a raw grant value to its string entries: a YAML list stays a list, a
+ * comma-separated string is split, and anything else (or a list with a non-string
+ * member) is rejected as undefined, the same "not a grant" signal as an absent field. */
+function coerceGrantItems(raw: unknown): string[] | undefined {
+  let items: unknown[]
+  if (Array.isArray(raw)) items = raw
+  else if (typeof raw === 'string') items = toolEntries(raw)
+  else return undefined
+  if (items.some((item) => typeof item !== 'string')) return undefined
+  return items as string[]
+}
+
+/** Fold one grant entry into the accumulator: the base tool is granted, an unscoped
+ * entry marks its tools wide, and a scoped entry records the scope for bash and the
+ * file tools it governs. */
+function addGrantEntry(acc: GrantAccumulator, item: string): void {
+  const entry = item.trim()
+  const name = normalizeToolName(entry)
+  if (!name) return
+  if (!acc.tools.includes(name)) acc.tools.push(name)
+  const open = entry.indexOf('(')
+  if (open === -1) {
+    if (name === 'bash') acc.bashUnscoped = true
+    for (const tool of PATH_RULE_TOOLS[name] ?? []) acc.pathUnscoped.add(tool)
+    return
+  }
+  acc.scopedEntries.push(entry)
+  const scope = entry.slice(open + 1, entry.endsWith(')') ? -1 : undefined).trim()
+  // An empty specifier (`Bash()`, `Read()`) matches nothing and must not read as
+  // the unscoped grant it explicitly is not: it is recorded so the tool stays
+  // restricted, and the matchers treat an empty rule as matching no input.
+  if (name === 'bash') acc.bashRules.push(scope)
+  for (const tool of PATH_RULE_TOOLS[name] ?? []) acc.pathScopes[tool].push(scope)
+}
+
+/** The per-tool path rules from a scan: a tool with any unscoped grant is omitted
+ * (it is wide), one with only scoped grants keeps them, and the whole map is absent
+ * when no tool carries a rule. */
+function buildPathRules(acc: GrantAccumulator): ToolGrants['pathRules'] {
+  const pathRules: NonNullable<ToolGrants['pathRules']> = {}
+  for (const tool of ['read', 'edit', 'write'] as const) {
+    if (!acc.pathUnscoped.has(tool) && acc.pathScopes[tool].length > 0) pathRules[tool] = acc.pathScopes[tool]
+  }
+  return Object.keys(pathRules).length > 0 ? pathRules : undefined
+}
+
 /**
  * A tool grant is either a comma-separated string or a YAML list, and the two mean the
  * same thing. An empty list is not the same as an absent one: it says no tools, so it
@@ -143,47 +210,15 @@ const PATH_RULE_TOOLS: Record<string, Array<'read' | 'edit' | 'write'>> = {
  * whose widening reaches everything, so it is the one enforced.
  */
 export function parseToolGrants(raw: unknown): ToolGrants | undefined {
-  if (raw === undefined || raw === null) return undefined
-  let items: unknown[]
-  if (Array.isArray(raw)) items = raw
-  else if (typeof raw === 'string') items = toolEntries(raw)
-  else return undefined
-  if (items.some((item) => typeof item !== 'string')) return undefined
-
-  const tools: string[] = []
-  const scopedEntries: string[] = []
-  const bashRules: string[] = []
-  let bashUnscoped = false
-  const pathScopes: Record<'read' | 'edit' | 'write', string[]> = { read: [], edit: [], write: [] }
-  const pathUnscoped = new Set<'read' | 'edit' | 'write'>()
-  for (const item of items as string[]) {
-    const entry = item.trim()
-    const name = normalizeToolName(entry)
-    if (!name) continue
-    if (!tools.includes(name)) tools.push(name)
-    const open = entry.indexOf('(')
-    if (open === -1) {
-      if (name === 'bash') bashUnscoped = true
-      for (const tool of PATH_RULE_TOOLS[name] ?? []) pathUnscoped.add(tool)
-      continue
-    }
-    scopedEntries.push(entry)
-    const scope = entry.slice(open + 1, entry.endsWith(')') ? -1 : undefined).trim()
-    // An empty specifier (`Bash()`, `Read()`) matches nothing and must not read as
-    // the unscoped grant it explicitly is not: it is recorded so the tool stays
-    // restricted, and the matchers treat an empty rule as matching no input.
-    if (name === 'bash') bashRules.push(scope)
-    for (const tool of PATH_RULE_TOOLS[name] ?? []) pathScopes[tool].push(scope)
-  }
-  const pathRules: ToolGrants['pathRules'] = {}
-  for (const tool of ['read', 'edit', 'write'] as const) {
-    if (!pathUnscoped.has(tool) && pathScopes[tool].length > 0) pathRules[tool] = pathScopes[tool]
-  }
+  const items = coerceGrantItems(raw)
+  if (items === undefined) return undefined
+  const acc = createGrantAccumulator()
+  for (const item of items) addGrantEntry(acc, item)
   return {
-    tools,
-    scopedEntries,
-    bashRules: !bashUnscoped && bashRules.length > 0 ? bashRules : undefined,
-    pathRules: Object.keys(pathRules).length > 0 ? pathRules : undefined,
+    tools: acc.tools,
+    scopedEntries: acc.scopedEntries,
+    bashRules: !acc.bashUnscoped && acc.bashRules.length > 0 ? acc.bashRules : undefined,
+    pathRules: buildPathRules(acc),
   }
 }
 
@@ -193,17 +228,25 @@ const text = (value: unknown): string => {
   return typeof value === 'number' || typeof value === 'boolean' ? String(value) : ''
 }
 
+/** YAML's affirmative boolean spellings. Claude documents `disable-model-invocation:
+ * true`, but a command file is hand-written YAML where `yes`, `on`, and `1` are all
+ * ordinary spellings of true, and pi's parser hands those back as the raw string or
+ * number rather than a boolean. A flag that gates a command off from the model has to
+ * honor them, or a command the user marked off-limits is silently offered to it. */
+const YAML_TRUE = new Set(['true', 'yes', 'on', 'y', '1'])
+const isFlagEnabled = (value: unknown): boolean => value === true || YAML_TRUE.has(text(value).toLowerCase())
+
 /** Claude writes `argument-hint: [pr]`, which YAML reads as a list; render it back. */
 const hint = (value: unknown): string => (Array.isArray(value) ? `[${value.join(', ')}]` : text(value))
 
-const ARGUMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+const ARGUMENT_NAME = /^[A-Za-z_]\w*$/
 
 /** The `arguments:` frontmatter: a YAML list or a space- or comma-separated string
  * of names mapping to positions in order. Invalid names are dropped, and ARGUMENTS
  * itself is reserved by the built-in placeholder. */
 function parseArgumentNames(raw: unknown): string[] | undefined {
   let items: string[]
-  if (Array.isArray(raw)) items = raw.map((entry) => String(entry))
+  if (Array.isArray(raw)) items = raw.map(String)
   else if (typeof raw === 'string') items = raw.split(/[\s,]+/)
   else return undefined
   const names = items.map((name) => name.trim()).filter((name) => ARGUMENT_NAME.test(name) && name !== 'ARGUMENTS')
@@ -233,7 +276,7 @@ export function parseCommandFile(content: string): ParsedCommand {
     disallowedTools: parseToolGrants(frontmatter['disallowed-tools'])?.tools,
     shell: SHELLS.has(shell) ? shell : undefined,
     model: text(frontmatter.model) || undefined,
-    disableModelInvocation: disable === true || text(disable) === 'true',
+    disableModelInvocation: isFlagEnabled(disable),
     body,
   }
 }
@@ -300,8 +343,8 @@ export function substituteArgsDetailed(body: string, args: string, names: string
     return value
   }
   const text = body.replaceAll(argPattern(names), (token, bracketIdx?: string, defIdx?: string, defVal?: string, argsDefault?: string, shorthandIdx?: string, name?: string) => {
-    if (token === '\\\\') return token
-    if (token === '\\$') return '$'
+    if (token === String.raw`\\`) return token
+    if (token === String.raw`\$`) return '$'
     if (bracketIdx !== undefined) return fill(parts[Number(bracketIdx)], token)
     if (defIdx !== undefined) return fill(parts[Number(defIdx)], defVal ?? '')
     if (argsDefault !== undefined) {

package/extensions/internal/html-markdown.ts

@@ -20,6 +20,16 @@ function decodeAllEntities(text: string): string {
 
 const stripInnerTags = (html: string): string => html.replace(/<[^<>]*>/g, '')
 
+// Strip leading and trailing newline runs in linear time. The equivalent
+// /^\n+|\n+$/g backtracks super-linearly on a long run of newlines (S8786).
+const trimNewlines = (value: string): string => {
+  let start = 0
+  let end = value.length
+  while (start < end && value[start] === '\n') start++
+  while (end > start && value[end - 1] === '\n') end--
+  return value.slice(start, end)
+}
+
 export function htmlToMarkdown(html: string): string {
   // Pre blocks are lifted out first so no later transform touches their content.
   const preBodies: string[] = []
@@ -27,7 +37,7 @@ export function htmlToMarkdown(html: string): string {
     .replace(/<!--[\s\S]*?-->/g, ' ')
     .replace(/<(script|style|noscript|head|svg)\b[^<>]*>[\s\S]*?<\/\1[^<>]*>/gi, ' ')
     .replace(/<pre\b[^<>]*>([\s\S]*?)<\/pre>/gi, (_whole, inner: string) => {
-      preBodies.push(decodeAllEntities(stripInnerTags(inner)).replace(/^\n+|\n+$/g, ''))
+      preBodies.push(trimNewlines(decodeAllEntities(stripInnerTags(inner))))
       return `\n\n\uE000PRE${preBodies.length - 1}\uE000\n\n`
     })