pi-code 1.0.55 → 1.0.57

package/README.md

@@ -13,7 +13,7 @@
 
 Claude Code experience for the [pi](https://pi.dev) coding agent, in one package. Point pi at a project that already has a `.claude/` directory and it reads your existing config: rules, commands, skills, hooks, output styles, MCP servers, and agents. It also adds the Claude Code features pi lacks: a todo overlay, checkpoints, memory, web search, subagents, and goals.
 
-What a repository ships is treated as untrusted until you approve it: project MCP servers, hooks, agents, rules, output styles, commands and skills load only once you say yes.
+What a repository ships is treated as untrusted until you approve it: project MCP servers, hooks, agents, rules, output styles, commands and skills load only once you say yes. A headless run (`pi -p`) cannot ask, so an undecided project loads none of them there, which is stricter than Claude, where a headless run uses them without showing the dialog.
 
 ![pi-code demo](demos/hero.gif)
 
@@ -45,7 +45,7 @@ Each topic links to its own doc with the full contract and any divergences from
 - **[MCP servers](docs/mcp.md)** — every Claude config scope, all four transports, OAuth, managed policy, timeouts, prompts, and resources.
 - **[Custom slash commands](docs/commands.md)** — `.claude/commands` with arguments, bash spans, `@file` inlining, frontmatter, and model invocation.
 - **[Skills](docs/skills.md)** — `.claude/skills` discovery plus the same dynamic content commands get.
-- **[Subagents / Task](docs/subagents.md)** — built-in and custom agents, background runs, per-agent memory, worktree isolation.
+- **[Subagents](docs/subagents.md)** — built-in and custom agents, background runs, per-agent memory, worktree isolation.
 - **[CLAUDE.md, @imports, and rules](docs/claude-md.md)** — the context files and path-scoped rules pi does not load natively.
 - **[Settings `env`](docs/settings-env.md)** — env blocks from every settings scope, exported with Claude's precedence.
 - **[Output styles](docs/output-styles.md)** — replace semantics, bundled built-ins, `/output-style`.

package/extensions/commands.ts

@@ -44,7 +44,8 @@ import * as path from 'node:path'
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
 import { matchesBashRules } from './internal/bash-rules.js'
-import { type CommandExec, type DiscoveredCommand, discoverCommandFiles, expandDynamicContent, type ParsedCommand, type PathRuleTool, parseCommandFile, resolvePowershellBinary, spanExec, substituteArgsDetailed, substituteVars } from './internal/command-file.js'
+import { type DiscoveredCommand, discoverCommandFiles, type ParsedCommand, type PathRuleTool, parseCommandFile, substituteArgsDetailed, substituteVars } from './internal/command-file.js'
+import { type CommandExec, expandDynamicContent, resolvePowershellBinary, spanExec } from './internal/command-spans.js'
 import { claudeConfigDir } from './internal/config-dir.js'
 import { claudeEffortLevel } from './internal/effort.js'
 import { managedSettingsFile, readManagedSettings } from './internal/managed-settings.js'
@@ -55,6 +56,7 @@ import { isProjectApproved } from './internal/project-approval.js'
 import { ancestorDirs, repoRoot } from './internal/project-root.js'
 import { claudeSettingsChain } from './internal/settings-chain.js'
 import { createTurnOverride } from './internal/turn-override.js'
+import { errorMessage, isDirectory } from './internal/values.js'
 
 /** Just enough of pi's Model to match and restore; getAvailable returns these. */
 interface ModelLike {
@@ -105,14 +107,6 @@ interface VarContext {
   modelRegistry?: { getAvailable(): ReadonlyArray<ModelLike> }
 }
 
-function isDirectory(target: string): boolean {
-  try {
-    return fs.statSync(target).isDirectory()
-  } catch {
-    return false
-  }
-}
-
 /** Existing `.claude/commands` directories in Claude's precedence order (later
  * directories win in collectCommands): project first, then personal, then the
  * enterprise directory beside the managed settings file, per "enterprise
@@ -328,7 +322,7 @@ export default function commandsExtension(pi: ExtensionAPI) {
       // A refused switch leaves the turn on the session model rather than the one the
       // command named, and the reply gives no sign of it, so the refusal is reported.
       void pi.setModel(model as Parameters<typeof pi.setModel>[0]).catch((error: unknown) => {
-        console.warn(`pi-code-commands: could not switch to ${typeof model === 'object' && model !== null && 'id' in model ? String((model as { id: unknown }).id) : String(model)}: ${error instanceof Error ? error.message : String(error)}`)
+        console.warn(`pi-code-commands: could not switch to ${typeof model === 'object' && model !== null && 'id' in model ? String((model as { id: unknown }).id) : String(model)}: ${errorMessage(error)}`)
       })
     },
   })
@@ -455,7 +449,7 @@ export default function commandsExtension(pi: ExtensionAPI) {
     } catch (error) {
       // A failed injected command aborts the invocation; the model never sees a
       // half-expanded body. The notify carries Claude's failure message format.
-      ctx.ui.notify(error instanceof Error ? error.message : String(error), 'error')
+      ctx.ui.notify(errorMessage(error), 'error')
       return
     }
 
@@ -513,7 +507,7 @@ export default function commandsExtension(pi: ExtensionAPI) {
         // An unreadable file must not take down session start, but the command is then
         // absent from /help and unresolvable by the model, which looks like one that was
         // never written.
-        console.warn(`pi-code-commands: ignoring ${command.filePath}: ${error instanceof Error ? error.message : String(error)}`)
+        console.warn(`pi-code-commands: ignoring ${command.filePath}: ${errorMessage(error)}`)
         continue
       }
       discovered.set(command.name, command)

package/extensions/context-imports.ts

@@ -76,7 +76,7 @@ import { sliceBytes } from './internal/output-guard.js'
 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 { claudeSettingsChain, readSettingsChain } from './internal/settings-chain.js'
 import { statToken } from './internal/stat-token.js'
 import { type Fence, fenceMarker, stepFence, stripBlockComments } from './internal/strip-comments.js'
 
@@ -406,15 +406,7 @@ export function readClaudeMdExcludes(files: string[], managed: Record<string, un
       if (typeof entry === 'string' && entry.trim().length > 0) globs.push(entry)
     }
   }
-  for (const file of files) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      if (settings === null || typeof settings !== 'object') continue
-      collect((settings as Record<string, unknown>).claudeMdExcludes)
-    } catch {
-      // missing or invalid settings file: skip
-    }
-  }
+  for (const settings of readSettingsChain(files)) collect(settings.claudeMdExcludes)
   collect(managed.claudeMdExcludes)
   return globs
 }

package/extensions/env-settings.ts

@@ -36,15 +36,11 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
-
 import { claudeConfigDir } from './internal/config-dir.js'
 import { readManagedSettings } from './internal/managed-settings.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { claudeSettingsChain } from './internal/settings-chain.js'
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
+import { isRecord } from './internal/values.js'
 
 /** The `env` object of one settings scope, coerced to string values. A string is kept
  * as-is, a number or boolean becomes its String() form, and anything else (object,

package/extensions/git-checkpoint.ts

@@ -19,6 +19,7 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { claudeConfigDir } from './internal/config-dir.js'
+import { contentText, errorMessage } from './internal/values.js'
 
 const CUSTOM_TYPE = 'git-checkpoint'
 /** Sidecar inside the bare shadow repo recording the work tree it snapshots. */
@@ -116,17 +117,8 @@ function rememberWorkTree(shadowDir: string, cwd: string): void {
   }
 }
 
-function extractText(content: unknown): string {
-  if (typeof content === 'string') return content
-  if (!Array.isArray(content)) return ''
-  return content
-    .filter((part) => part?.type === 'text' && typeof part.text === 'string')
-    .map((part) => part.text)
-    .join(' ')
-}
-
 function promptSnippet(content: unknown): string {
-  const text = extractText(content).replace(/\s+/g, ' ').trim()
+  const text = contentText(content, ' ').replace(/\s+/g, ' ').trim()
   if (text.length <= PROMPT_SNIPPET_LENGTH) return text
   return `${text.slice(0, PROMPT_SNIPPET_LENGTH)}…`
 }
@@ -156,7 +148,7 @@ async function restoreConversation(ctx: ExtensionCommandContext, entryId: string
     if (typeof result.editorText === 'string') ctx.ui.setEditorText(result.editorText)
     return true
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
+    const message = errorMessage(error)
     ctx.ui.notify(`Conversation restore failed: ${message}`, 'error')
     return false
   }
@@ -237,7 +229,7 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
     } catch (error) {
       // Without the mirror, files the user excluded locally are snapshotted into the
       // checkpoint store and restored by /rewind, so this is not a silent fallback.
-      ctx.ui.notify(`Checkpoints cannot honor this repository's .git/info/exclude: ${error instanceof Error ? error.message : String(error)}`, 'warning')
+      ctx.ui.notify(`Checkpoints cannot honor this repository's .git/info/exclude: ${errorMessage(error)}`, 'warning')
     }
   }
 

package/extensions/goal.ts

@@ -37,7 +37,6 @@
 
 import * as os from 'node:os'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
-
 import { hookFiles, readSettingsDisableAllHooks, stopHookBlockCap } from './hooks/index.js'
 import {
   checkinIntervalMs,
@@ -66,6 +65,7 @@ import { completeText } from './internal/model-complete.js'
 import { resolveModelOverride } from './internal/model-lookup.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from './internal/subagent-events.js'
+import { errorMessage } from './internal/values.js'
 
 /** Session entry type the goal state persists under, and the custom message type its
  * transcript lines (kickoff, verdicts, check-ins) carry. */
@@ -340,7 +340,7 @@ export default function goalExtension(pi: ExtensionAPI) {
       // A user interrupt is not an evaluator failure: the goal stays, nothing to say.
       if (ctx.signal?.aborted) return
       // No verdict is a hook error in Claude's terms: the turn ends and the goal stays.
-      if (generation === startedGeneration) tell(ctx, `Goal evaluator error: ${error instanceof Error ? error.message : String(error)}. The goal stays set; the next turn is evaluated again.`, 'warning')
+      if (generation === startedGeneration) tell(ctx, `Goal evaluator error: ${errorMessage(error)}. The goal stays set; the next turn is evaluated again.`, 'warning')
       return
     }
     // Interrupted, cleared, or replaced during the await: this verdict must not act.

package/extensions/hooks/config.ts

@@ -8,7 +8,8 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { readManagedSettings } from '../internal/managed-settings.js'
 import { type InstalledPlugin, pluginComponentPath, substitutePluginVars } from '../internal/plugins.js'
-import { claudeSettingsChain } from '../internal/settings-chain.js'
+import { claudeSettingsChain, readSettingsChain } from '../internal/settings-chain.js'
+import { errorMessage, isRecord } from '../internal/values.js'
 
 export interface HookCommand {
   type?: string
@@ -67,10 +68,6 @@ export function isBackgroundHook(hook: HookCommand): boolean {
 }
 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. */
@@ -92,13 +89,8 @@ export function readDisableAllHooks(files: string[], managed: Record<string, unk
  * disableAllHooks cannot disable hooks configured through managed policy settings,
  * so the caller keeps managed hooks running when only this half is set. */
 export function readSettingsDisableAllHooks(files: string[]): boolean {
-  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
-    }
+  for (const settings of readSettingsChain(files)) {
+    if (settings.disableAllHooks === true) return true
   }
   return false
 }
@@ -152,14 +144,7 @@ export function readAllowedHttpHookUrls(files: string[], managed: Record<string,
     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
-    }
-  }
+  for (const settings of readSettingsChain(files)) collect(settings.allowedHttpHookUrls)
   return found
 }
 
@@ -203,7 +188,7 @@ function mergeHooksJson(config: HooksConfig, raw: string, source: string, source
   } catch (error) {
     // Every hook this source declares is now absent, a policy hook among them, so the
     // failure is named rather than left to look like a file with no hooks in it.
-    console.warn(`pi-code-hooks: ignoring the hooks in ${source}: ${error instanceof Error ? error.message : String(error)}`)
+    console.warn(`pi-code-hooks: ignoring the hooks in ${source}: ${errorMessage(error)}`)
     return
   }
   for (const [event, matchers] of Object.entries(parsed?.hooks ?? {})) {

package/extensions/hooks/decisions.ts

@@ -6,8 +6,9 @@
 
 import type { ToolCallEventResult } from '@earendil-works/pi-coding-agent'
 import type { PathAnchors } from '../internal/path-rules.js'
+import { errorMessage, isRecord } from '../internal/values.js'
 import { claudeToolInput, claudeToolName, piToolInput } from './claude-tools.js'
-import { type HookCommand, type HooksConfig, isRecord } from './config.js'
+import type { HookCommand, HooksConfig } from './config.js'
 import { allCommands, matchingCommands, passesIfFilter } from './matcher.js'
 import { type HookRunner, type HookRunResult, timeoutMs } from './runners.js'
 
@@ -63,7 +64,7 @@ export function hookJsonError(text: string): string | undefined {
     JSON.parse(trimmed)
     return undefined
   } catch (error) {
-    parseError = error instanceof Error ? error.message : String(error)
+    parseError = errorMessage(error)
   }
   const lines = trimmed
     .split('\n')

package/extensions/hooks/index.ts

@@ -109,6 +109,7 @@ import { watchSettingsFiles } from '../internal/settings-watch.js'
 import { isSkillHooksEvent, SKILL_HOOKS_CHANNEL } from '../internal/skill-hooks.js'
 import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
 import { setSubagentStartHookRunner } from '../internal/subagent-hooks.js'
+import { contentText } from '../internal/values.js'
 import { claudeToolInput, claudeToolName, claudeToolResponse, piToolOutput } from './claude-tools.js'
 import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, isBackgroundHook, loadHooks, loadManagedHooks, loadPluginHooks, mergeAgentEnvHooks, mergeSkillHooks, readAllowedHttpHookUrls, readDisableAllHooks, readSettingsDisableAllHooks } from './config.js'
 import { blockedToolCall, jsonBlockVerdict, postToolFeedback, promptContext, runPreToolUse, runUserPromptSubmit, surfaceSystemMessages, tryParseJson } from './decisions.js'
@@ -127,12 +128,7 @@ export function lastAssistantText(messages: ReadonlyArray<{ role: string; conten
   for (let i = messages.length - 1; i >= 0; i--) {
     const message = messages[i]
     if (message.role !== 'assistant') continue
-    if (typeof message.content === 'string') return message.content
-    if (!Array.isArray(message.content)) return ''
-    return message.content
-      .filter((part): part is { type: 'text'; text: string } => typeof part === 'object' && part !== null && (part as { type?: unknown }).type === 'text')
-      .map((part) => part.text)
-      .join('')
+    return contentText(message.content)
   }
   return ''
 }
@@ -157,14 +153,6 @@ async function runNotifyHooks(commands: HookCommand[], payload: unknown, runner:
   return await Promise.all(runnable.map((command) => runner(command, payload, timeoutMs(command))))
 }
 
-/** The text of a result's content blocks, for Claude-shaped tool_response fields. */
-function textContent(content: ReadonlyArray<{ type: string; text?: string }>): string {
-  return content
-    .filter((block) => block.type === 'text' && typeof block.text === 'string')
-    .map((block) => block.text)
-    .join('\n')
-}
-
 /** pi's lifecycle vocabularies differ from Claude's documented ones. The matcher is
  * offered both spellings so existing configs keep firing either way, and the payload
  * reports the Claude value, which is what a Claude-written hook script parses. */
@@ -531,13 +519,13 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const commands = matchingCommands(event.isError ? config.PostToolUseFailure : config.PostToolUse, names).filter((command) => passesIfFilter(command, target))
     if (commands.length === 0 && pending.length === 0) return
     const translatedInput = alias === undefined ? claudeToolInput(event.toolName, event.input, ctx.cwd) : undefined
-    const response = (alias === undefined && !event.isError ? claudeToolResponse(event.toolName, event.input, textContent(event.content), event.isError, ctx.cwd) : undefined) ?? { content: event.content, details: event.details, isError: event.isError }
+    const response = (alias === undefined && !event.isError ? claudeToolResponse(event.toolName, event.input, contentText(event.content, '\n'), event.isError, ctx.cwd) : undefined) ?? { content: event.content, details: event.details, isError: event.isError }
     const startedAt = toolStartTimes.get(event.toolCallId)
     toolStartTimes.delete(event.toolCallId)
     // Claude delivers a failure as top-level fields rather than a tool_response: "error
     // information as top-level fields ... error ... is_interrupt". is_interrupt is false
     // here because pi reports a cancelled tool through the result, not this event.
-    const failure = event.isError ? { error: textContent(event.content), is_interrupt: false } : { tool_response: response }
+    const failure = event.isError ? { error: contentText(event.content, '\n'), is_interrupt: false } : { tool_response: response }
     const payload = { hook_event_name: eventName, tool_name: translatedName ?? event.toolName, tool_input: translatedInput ?? event.input, ...failure, ...(startedAt === undefined ? {} : { duration_ms: Date.now() - startedAt }) }
     const run = boundRunner(ctx, { tool_use_id: event.toolCallId })
     const results = await Promise.all(commands.map((command) => run(command, payload, timeoutMs(command))))

package/extensions/hooks/matcher.ts

@@ -6,6 +6,7 @@
 
 import { matchesBashIfFilter } from '../internal/bash-rules.js'
 import { matchesPathRules, type PathAnchors } from '../internal/path-rules.js'
+import { errorMessage } from '../internal/values.js'
 import type { HookCommand, HookMatcher } from './config.js'
 
 /** Claude's rule: a matcher of only letters, digits, `_`, `-`, spaces, `,` and `|`
@@ -62,7 +63,7 @@ function compileMatcher(matcher: string): CompiledMatcher {
     } catch (error) {
       // The fallback matches the literal text, which almost never matches a tool name, so
       // the hook simply never fires. Say so: the matcher reads as merely wrong otherwise.
-      console.warn(`pi-code-hooks: matcher ${matcher} is not a valid regular expression (${error instanceof Error ? error.message : String(error)}); it will only match a tool of that exact name`)
+      console.warn(`pi-code-hooks: matcher ${matcher} is not a valid regular expression (${errorMessage(error)}); it will only match a tool of that exact name`)
       compiled = { tokens: exactTokens(matcher) }
     }
   }

package/extensions/hooks/runners.ts

@@ -11,6 +11,7 @@ import { runAgent } from '../internal/agent-run.js'
 import { callMcpTool } from '../internal/mcp-call.js'
 import { completeText } from '../internal/model-complete.js'
 import { resolveShell } from '../internal/shell-resolve.js'
+import { errorMessage } from '../internal/values.js'
 import { type HookCommand, httpUrlAllowed, isBackgroundHook } from './config.js'
 
 // Claude's defaults vary by type and event (600s for command/http/mcp_tool, 30s
@@ -224,7 +225,11 @@ export async function runHttpHook(hook: { type?: string; command: string; url?:
     }
     return { code: 0, stdout: body, stderr: '', timedOut: false }
   } catch (error) {
-    return { code: 1, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: false }
+    // A timeout is the abort that AbortSignal.timeout raises. Mark it as one so a gated
+    // event fails closed on it, exactly as a command hook that ran out of time does: the
+    // hook never answered, whichever transport it used.
+    const name = error instanceof Error ? error.name : ''
+    return { code: 1, stdout: '', stderr: errorMessage(error), timedOut: name === 'TimeoutError' || name === 'AbortError' }
   }
 }
 
@@ -258,7 +263,7 @@ function substituteArguments(prompt: string | undefined, payload: unknown): stri
  * produced no verdict and is non-blocking. */
 function abortAwareFailure(signal: AbortSignal, error: unknown): HookRunResult {
   const aborted = signal.aborted || (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError'))
-  return { code: aborted ? TIMEOUT_EXIT_CODE : 1, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: aborted }
+  return { code: aborted ? TIMEOUT_EXIT_CODE : 1, stdout: '', stderr: errorMessage(error), timedOut: aborted }
 }
 
 export async function runPromptHook(hook: HookCommand, payload: unknown, model: Model<Api> | undefined, timeoutMs: number): Promise<HookRunResult> {
@@ -319,11 +324,12 @@ export async function runMcpToolHook(hook: HookCommand, payload: unknown, timeou
   const input = hook.input && typeof hook.input === 'object' ? (substituteInputPaths(hook.input, payload) as Record<string, unknown>) : {}
   let timer: ReturnType<typeof setTimeout> | undefined
   const deadline = new Promise<HookRunResult>((resolve) => {
-    timer = setTimeout(() => resolve({ code: 1, stdout: '', stderr: `mcp_tool hook timed out after ${timeoutMs}ms`, timedOut: false }), timeoutMs)
+    // Marked as a timeout so a gated event fails closed on it, like a command hook.
+    timer = setTimeout(() => resolve({ code: 1, stdout: '', stderr: `mcp_tool hook timed out after ${timeoutMs}ms`, timedOut: true }), timeoutMs)
   })
   const call = callMcpTool(hook.server, hook.tool, input)
     .then((result): HookRunResult => ({ code: result.isError ? 1 : 0, stdout: result.text, stderr: '', timedOut: false }))
-    .catch((error): HookRunResult => ({ code: 1, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: false }))
+    .catch((error): HookRunResult => ({ code: 1, stdout: '', stderr: errorMessage(error), timedOut: false }))
   try {
     return await Promise.race([call, deadline])
   } finally {