pi-code 1.0.56 → 1.0.57

package/extensions/internal/command-spans.ts

@@ -0,0 +1,246 @@
+/**
+ * Running the `!` command spans and `@path` references a command or skill body carries.
+ *
+ * Split from the parsing half: only commands.ts drives spans, while skills.ts and the
+ * subagent loader import parsing alone and have no business pulling a shell resolver in.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import { bashBinary } from './shell-resolve.js'
+import { splitSegments } from './shell-split.js'
+import { type Fence, fenceMarker, stepFence } from './strip-comments.js'
+export type CommandExec = (command: string) => Promise<{ stdout: string; stderr: string; code: number; killed?: boolean }>
+
+/** PowerShell single-quote escaping: inside a '...' literal the only special
+ * characters are the quote delimiters themselves, written doubled. PowerShell's
+ * lexer treats U+2018 through U+201B as single quotes too, so each is doubled the
+ * same way; leaving them bare let a projectDir like `Alex’s Projects` end the
+ * literal mid-path with a ParserError. sh's '\'' form must not be used here,
+ * since PowerShell would keep the backslash and reopen the string. */
+export function powershellQuote(value: string): string {
+  return value.replaceAll(/['‘’‚‛]/g, '$&$&')
+}
+
+export { resolvePowershellBinary } from './shell-resolve.js'
+
+export interface SpanExec {
+  command: string
+  args: string[]
+  /** Set when the shell cannot merge stderr into stdout in-script (pwsh 7 drops a
+   * native command's stderr from `& { } 2>&1`), asking the caller to append the
+   * exec result's stderr to its stdout instead. The sh path merges in-script and
+   * leaves this unset. */
+  mergeStreams?: boolean
+}
+
+/** The sh invocation for a span: CLAUDE_PROJECT_DIR and CLAUDECODE=1 exported in-script
+ * (pi.exec takes no env; CLAUDECODE marks every subprocess Claude spawns), stderr merged
+ * with 2>&1. The group opens with a `:` null command: `{ }` around an empty or
+ * comment-only span is a hard sh syntax error (exit 2) that aborted the whole
+ * invocation, and `:` keeps such a span the harmless no-op it was on HEAD while the
+ * group still merges stderr for real spans. */
+function shSpan(binary: string, projectDir: string, script: string): SpanExec {
+  const quoted = projectDir.replaceAll("'", String.raw`'\''`)
+  return { command: binary, args: ['-c', `export CLAUDE_PROJECT_DIR='${quoted}'\nexport CLAUDECODE=1\n{ :\n${script}\n} 2>&1`] }
+}
+
+/** The PowerShell invocation for a span. No in-script 2>&1: under pwsh 7 it does not
+ * merge a native command's stderr on a script block, so mergeStreams has the caller
+ * append it. The trailing exit forwards a failed native command's code, which pwsh
+ * -Command otherwise swallows (the process exited 0 and a failure never aborted the
+ * invocation). An empty or cmdlet-only span leaves $LASTEXITCODE unset and exits 0.
+ * Residual gap vs sh: a failing cmdlet sets no exit code, so it cannot abort; its
+ * error text still reaches the model through the merged stderr. */
+function powershellSpan(binary: string, projectDir: string, script: string): SpanExec {
+  const preamble = `$ErrorActionPreference='Continue'\n$env:CLAUDE_PROJECT_DIR='${powershellQuote(projectDir)}'\n$env:CLAUDECODE='1'`
+  return { command: binary, args: ['-NoProfile', '-NonInteractive', '-Command', `${preamble}\n& {\n${script}\n}\nexit $LASTEXITCODE`], mergeStreams: true }
+}
+
+/**
+ * The exec invocation for one injected span, honoring the `shell:` frontmatter per
+ * Claude's shell matrix (skills.md). `powershell` runs through a PowerShell binary when
+ * one resolves. Otherwise the span runs through bash: /bin/sh off Windows, Git Bash on
+ * Windows. Without Git Bash, a skill that declared `shell: bash` fails before any
+ * command runs ("requires bash"), an undeclared one falls to PowerShell, and with
+ * neither shell the invocation fails. Both paths export CLAUDE_PROJECT_DIR (each
+ * shell's own quoting) and merge stderr into stdout, as the Bash tool does when it
+ * runs these for Claude: the sh script in-line with 2>&1, the pwsh path via
+ * mergeStreams in the caller.
+ *
+ * The resolvers are parameters so a caller (or test) controls the lookups: the
+ * PowerShell one is passed as an imported binding, the bash one defaults to the
+ * platform rule.
+ */
+export function spanExec(shell: string | undefined, projectDir: string, script: string, resolveBinary: () => string | undefined, resolveBash: () => string | undefined = bashBinary): SpanExec {
+  if (shell === 'powershell') {
+    const binary = resolveBinary()
+    if (binary !== undefined) return powershellSpan(binary, projectDir, script)
+  }
+  const bash = resolveBash()
+  if (bash !== undefined) return shSpan(bash, projectDir, script)
+  if (shell === 'bash') throw new Error('shell: bash requires Git Bash, which was not found (install Git for Windows or set CLAUDE_CODE_GIT_BASH_PATH)')
+  const binary = resolveBinary()
+  if (binary !== undefined) return powershellSpan(binary, projectDir, script)
+  throw new Error('no shell found for the injected commands: install Git for Windows or PowerShell')
+}
+
+interface FenceBlock {
+  start: number
+  end: number
+  /** A fence opened with ```! runs its content as one script; any other fence protects. */
+  exec: boolean
+  content: string
+}
+
+/** Fenced blocks of a body: Claude's dynamic syntax is literal text inside a plain
+ * fence, while a ```! fence is itself a placeholder that executes. Fences follow
+ * CommonMark: any indentation, closed only by the opener's character in a run at
+ * least as long, so a tilde line or a shorter fence inside stays content. */
+function fenceBlocks(body: string): FenceBlock[] {
+  const blocks: FenceBlock[] = []
+  let fence: Fence | null = null
+  let open: { index: number; exec: boolean; contentStart: number } | undefined
+  let offset = 0
+  for (const line of body.split('\n')) {
+    const trimmed = line.trimStart()
+    const step = stepFence(fence, trimmed, fenceMarker(trimmed))
+    const lineEnd = offset + line.length
+    if (fence === null && step.fence !== null) {
+      // Only the exact, unindented ```! opener executes, as Claude documents it.
+      open = { index: offset, exec: line.startsWith('```') && step.fence.length === 3 && trimmed.slice(3).trim() === '!', contentStart: lineEnd + 1 }
+    } else if (fence !== null && step.fence === null && open !== undefined) {
+      blocks.push({ start: open.index, end: lineEnd, exec: open.exec, content: body.slice(Math.min(open.contentStart, offset), offset).replace(/\n$/, '') })
+      open = undefined
+    }
+    fence = step.fence
+    offset = lineEnd + 1
+  }
+  // An unterminated fence protects to the end of the body rather than executing.
+  if (open !== undefined) blocks.push({ start: open.index, end: body.length, exec: false, content: '' })
+  return blocks
+}
+
+/** Exit 1 is a normal result for Claude's documented search and comparison commands
+ * (no matches, files differ); exit 2 and up fails even for these. The PowerShell
+ * shell uses a different set, which "includes grep and git diff but not find or
+ * diff" (test/[ are bash builtins and do not apply there either). */
+const EXIT_ONE_OK = new Set(['grep', 'rg', 'egrep', 'fgrep', 'find', 'diff', 'test', '['])
+const EXIT_ONE_OK_POWERSHELL = new Set(['grep', 'rg', 'egrep', 'fgrep'])
+
+export type SpanShell = 'bash' | 'powershell'
+
+const isCarveoutSegment = (segment: string, shell: SpanShell): boolean => {
+  const words = segment.trim().split(/\s+/)
+  if (words[0] === 'git') return words[1] === 'diff' || words[1] === 'grep'
+  return (shell === 'powershell' ? EXIT_ONE_OK_POWERSHELL : EXIT_ONE_OK).has(words[0])
+}
+
+export function benignExitOne(command: string, shell: SpanShell = 'bash'): boolean {
+  const segments = splitSegments(command)
+  if (segments.length === 0) return false
+  // A `&&`/`||` chain can short-circuit, so an earlier segment's exit 1 becomes the
+  // result and the last segment is not the one that set the code: `cd nope && grep x`
+  // exits 1 from cd, not a benign grep miss. Only when every segment is a carveout is
+  // the exit benign whichever ran last. Without short-circuit operators the exit is
+  // the last segment's (a `|` pipeline exits with its final command, `;`/newline with
+  // the last statement), so the last segment decides.
+  if (/&&|\|\|/.test(command)) return segments.every((segment) => isCarveoutSegment(segment, shell))
+  return isCarveoutSegment(segments.at(-1) ?? '', shell)
+}
+
+/** Run one injected span. A failure aborts the whole invocation, as Claude
+ * documents: the model never sees a half-expanded body. */
+async function runSpan(exec: CommandExec, command: string, pattern: string, shell: SpanShell): Promise<string> {
+  const result = await exec(command)
+  // A timeout kill arrives as killed:true with code 0 (a signal death has no exit code),
+  // so the code alone would paste the partial output as a success. Claude kills a span
+  // at the Bash timeout and that failure aborts the invocation.
+  if (result.killed) throw new Error(`Shell command timed out for pattern "${pattern}"`)
+  if (result.code !== 0 && !(result.code === 1 && benignExitOne(command, shell))) {
+    throw new Error(`Shell command failed for pattern "${pattern}"\n[stderr]\n${(result.stderr || result.stdout).trim()}`)
+  }
+  return result.stdout.trimEnd()
+}
+
+const inRanges = (ranges: Array<[number, number]>, index: number): boolean => ranges.some(([start, end]) => index >= start && index < end)
+
+/** Read a `@path` reference, confined to the working directory. Returns undefined
+ * when the path escapes it or cannot be read, so the reference stays literal. */
+function readReference(cwd: string, reference: string): string | undefined {
+  try {
+    // Both sides canonicalised: on macOS /var is itself a symlink, so comparing a
+    // resolved path against an unresolved root rejects every legitimate read.
+    const root = fs.realpathSync(cwd)
+    // Confinement is checked after symlinks resolve: a lexical check passes a link
+    // that points outside the project, and the read would follow it.
+    const real = fs.realpathSync(path.resolve(cwd, reference))
+    if (real !== root && !real.startsWith(root + path.sep)) return undefined
+    if (!fs.statSync(real).isFile()) return undefined
+    return fs.readFileSync(real, 'utf-8')
+  } catch {
+    return undefined
+  }
+}
+
+interface DynamicSpan {
+  start: number
+  end: number
+  run: () => Promise<string>
+}
+
+/** Claude's dynamic command content: `` !`cmd` `` runs a shell command and pastes
+ * its output (recognized only at a word start), a ```! fenced block runs its lines
+ * as one script, and `@path` inlines a file. Inline spans and `@` refs are skipped
+ * inside plain fenced code blocks. A failed command rejects, aborting the
+ * invocation, per the skills docs.
+ *
+ * Every placeholder is located in the ORIGINAL body and the whole body is expanded
+ * in one pass, so a command's output (or a file's content) is inserted verbatim and
+ * never re-scanned for further placeholders. Re-scanning was both a parity break
+ * (Claude expands once) and a command-injection path: output of a `` ```! `` block
+ * such as a commit message could smuggle its own `` !`cmd` `` for a later pass. */
+export async function expandDynamicContent(body: string, cwd: string, exec: CommandExec, shell: SpanShell = 'bash'): Promise<string> {
+  const blocks = fenceBlocks(body)
+  const protectedRanges = blocks.filter((block) => !block.exec).map((block): [number, number] => [block.start, block.end])
+  const execRanges = blocks.filter((block) => block.exec).map((block): [number, number] => [block.start, block.end])
+  // An inline span or @ ref inside a ```! block is part of that block's script, not a
+  // placeholder of its own; the block already covers those bytes.
+  const literal = (index: number): boolean => inRanges(protectedRanges, index) || inRanges(execRanges, index)
+
+  const spans: DynamicSpan[] = []
+  for (const block of blocks) {
+    if (block.exec) spans.push({ start: block.start, end: block.end, run: () => runSpan(exec, block.content, '```!', shell) })
+  }
+  // `!` counts only at the start of a line or after whitespace; `KEY=!`cmd`` is literal.
+  const bashPattern = /(^|\s)!`([^`]+)`/g
+  for (let m = bashPattern.exec(body); m !== null; m = bashPattern.exec(body)) {
+    if (literal(m.index)) continue
+    const [span, lead, command] = m
+    spans.push({ start: m.index, end: m.index + span.length, run: async () => lead + (await runSpan(exec, command, `!\`${command}\``, shell)) })
+  }
+  const atPattern = /(^|\s)@(\S+)/g
+  for (let m = atPattern.exec(body); m !== null; m = atPattern.exec(body)) {
+    if (literal(m.index)) continue
+    const [whole, lead, reference] = m
+    spans.push({
+      start: m.index,
+      end: m.index + whole.length,
+      run: async () => {
+        const content = readReference(cwd, reference)
+        return content === undefined ? whole : `${lead}\n<file path="${reference}">\n${content.trimEnd()}\n</file>\n`
+      },
+    })
+  }
+
+  spans.sort((a, b) => a.start - b.start)
+  let out = ''
+  let cursor = 0
+  for (const span of spans) {
+    if (span.start < cursor) continue // a rare @/inline overlap: keep the first, skip the nested
+    out += body.slice(cursor, span.start) + (await span.run())
+    cursor = span.end
+  }
+  return out + body.slice(cursor)
+}

package/extensions/internal/managed-settings.ts

@@ -12,6 +12,8 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 
+import { isRecord } from './values.js'
+
 /** The OS managed-settings.json path Claude Code documents per platform. */
 export function managedSettingsPath(platform: NodeJS.Platform = process.platform): string {
   if (platform === 'darwin') return '/Library/Application Support/ClaudeCode/managed-settings.json'
@@ -42,16 +44,12 @@ function readOneSettingsFile(file: string): Record<string, unknown> {
   return {}
 }
 
-function isRecordValue(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
-
 /** Claude's managed-settings.d merge rules: a later single value replaces, lists
  * combine with duplicates removed, and nested blocks merge key by key with each
  * key following these same rules. */
 function mergeManagedKey(base: unknown, next: unknown): unknown {
   if (Array.isArray(base) && Array.isArray(next)) return [...new Set([...base, ...next])]
-  if (isRecordValue(base) && isRecordValue(next)) {
+  if (isRecord(base) && isRecord(next)) {
     const merged: Record<string, unknown> = { ...base }
     for (const [key, value] of Object.entries(next)) merged[key] = key in merged ? mergeManagedKey(merged[key], value) : value
     return merged

package/extensions/internal/plugins.ts

@@ -15,9 +15,9 @@
 import * as crypto from 'node:crypto'
 import * as fs from 'node:fs'
 import * as path from 'node:path'
-
 import { claudeConfigDir } from './config-dir.js'
 import { readManagedSettings } from './managed-settings.js'
+import { errorMessage } from './values.js'
 
 export interface InstalledPlugin {
   name: string
@@ -43,7 +43,7 @@ function readJson(file: string): Record<string, unknown> {
   } catch (error) {
     // A manifest that does not parse leaves the plugin with no components at all, and
     // settings that do not parse drop the enablement or configuration they carried.
-    console.warn(`pi-code-plugins: ignoring ${file}: ${error instanceof Error ? error.message : String(error)}`)
+    console.warn(`pi-code-plugins: ignoring ${file}: ${errorMessage(error)}`)
     return {}
   }
 }

package/extensions/internal/settings-chain.ts

@@ -7,9 +7,11 @@
  * and the skill-shell policy all resolve their files through this one chain.
  */
 
+import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { claudeConfigDir } from './config-dir.js'
 import { repoRoot } from './project-root.js'
+import { isRecord } from './values.js'
 
 /** The user settings.json, then (only when `includeProject`) the project files by
  * Claude's placement rules: the shared `.claude/settings.json` is read from the
@@ -28,3 +30,20 @@ export function claudeSettingsChain(cwd: string, home: string, includeProject: b
   files.push(path.join(localDir, '.claude', 'settings.local.json'))
   return files
 }
+
+/** Every readable settings object in the chain, in order, so the last one a caller
+ * sees for a key is the one that wins. A file that is missing, unparseable, or not a
+ * JSON object is skipped: a corrupt settings.json must not end the chain, or the
+ * user-level values behind it would silently vanish along with it. Lazy, so a caller
+ * that stops early does not read the rest. */
+export function* readSettingsChain(files: readonly string[]): Generator<Record<string, unknown>> {
+  for (const file of files) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+    } catch {
+      continue
+    }
+    if (isRecord(parsed)) yield parsed
+  }
+}

package/extensions/internal/values.ts

@@ -0,0 +1,38 @@
+/**
+ * The shapes every extension here needed its own copy of: an error's message, a plain
+ * object check, whether a path is a directory, and the text of a message content. Each
+ * was written three to five times with the same body, and the error one appeared in
+ * seventeen files.
+ */
+
+import * as fs from 'node:fs'
+
+/** The message of a thrown value, whatever was thrown. */
+export const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+/** A JSON object, as opposed to null, an array, or a primitive. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** Whether the path is a directory today. A missing or unreadable path is not one. */
+export function isDirectory(target: string): boolean {
+  try {
+    return fs.statSync(target).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** The text of a message or tool-result content, dropping thinking and tool parts. A
+ * plain-string content is already the text. The separator is the caller's: Claude's
+ * last_assistant_message concatenates, a hook payload joins with newlines, a title or a
+ * prompt snippet with spaces. */
+export function contentText(content: unknown, separator = ''): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter((part): part is { type: 'text'; text: string } => isRecord(part) && part.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join(separator)
+}

package/extensions/mcp/index.ts

@@ -44,6 +44,7 @@ import { installedPlugins } from '../internal/plugins.js'
 import { isProjectApproved, isProjectApprovedSilently } from '../internal/project-approval.js'
 import { repoRoot } from '../internal/project-root.js'
 import { claudeSettingsChain } from '../internal/settings-chain.js'
+import { errorMessage } from '../internal/values.js'
 import { disabledServerNames, loadConfigFrom, loadPluginServers, loadUserScope, localScopeServerNames, projectConfigPaths, type ServerConfig, warnOnTypelessUrl } from './config.js'
 import { collectServerResourceEntries, listAllPrompts, listAllTools, type McpToolInfo, resourceServerFilter } from './listing.js'
 import { formatPromptCommandName, formatToolName, type McpContentBlock, type McpPromptInfo, mapContent, mapPromptArguments, normalizeSchema, promptMessageContent } from './mapping.js'
@@ -272,7 +273,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
             // streaming, so mid-stream invocations queue as a follow-up turn.
             pi.sendUserMessage(content, ctx.isIdle() ? {} : { deliverAs: 'followUp' })
           } catch (error) {
-            ctx.ui.notify(`${commandName}: ${error instanceof Error ? error.message : String(error)}`, 'error')
+            ctx.ui.notify(`${commandName}: ${errorMessage(error)}`, 'error')
           }
         },
       })
@@ -286,7 +287,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     try {
       registerPrompts(name, await withTimeout(listAllPrompts(client), connectTimeoutMs(), `list prompts ${name}`))
     } catch (error) {
-      console.warn(`pi-code-mcp: prompt listing failed for ${name}: ${error instanceof Error ? error.message : String(error)}`)
+      console.warn(`pi-code-mcp: prompt listing failed for ${name}: ${errorMessage(error)}`)
     }
   }
 
@@ -298,7 +299,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
         try {
           registerPrompts(name, await withTimeout(listAllPrompts(client), connectTimeoutMs(), `list prompts ${name}`))
         } catch (error) {
-          console.warn(`pi-code-mcp: prompt refresh failed for ${name}: ${error instanceof Error ? error.message : String(error)}`)
+          console.warn(`pi-code-mcp: prompt refresh failed for ${name}: ${errorMessage(error)}`)
         }
       })
     } catch {
@@ -386,7 +387,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
           status.set(name, { state: current?.state ?? 'connected', tools: serverToolCount(name) })
           pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])
         } catch (error) {
-          console.warn(`pi-code-mcp: tool refresh failed for ${name}: ${error instanceof Error ? error.message : String(error)}`)
+          console.warn(`pi-code-mcp: tool refresh failed for ${name}: ${errorMessage(error)}`)
         }
       })
     } catch {
@@ -445,7 +446,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
             if (!shuttingDown && !serverCallTuning(config).stdio) void reconnectWithBackoff(name, config)
           }
         } catch (error) {
-          status.set(name, { state: `failed: ${error instanceof Error ? error.message : String(error)}`, tools: 0 })
+          status.set(name, { state: `failed: ${errorMessage(error)}`, tools: 0 })
           // Connected but failed after (tool listing hung or errored): left in the
           // map, the client idles its process for the whole session and the
           // duplicate-name guard blocks the name for every later attempt.

package/extensions/mcp/listing.ts

@@ -4,6 +4,7 @@
  */
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { errorMessage } from '../internal/values.js'
 import type { McpPromptInfo } from './mapping.js'
 import { callRequestOptions, withTimeout } from './transport.js'
 
@@ -76,7 +77,7 @@ export async function collectServerResourceEntries(entries: Array<Record<string,
   try {
     await collectResources(entries, name, client, budget)
   } catch (error) {
-    entries.push({ server: name, error: error instanceof Error ? error.message : String(error) })
+    entries.push({ server: name, error: errorMessage(error) })
   }
   try {
     await collectResourceTemplates(entries, name, client, budget)

package/extensions/mcp/oauth-flow.ts

@@ -7,6 +7,7 @@
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { FileOAuthProvider, type OAuthServerConfig, openBrowser, startCallbackServer, waitForAuthCode } from '../internal/mcp-oauth.js'
+import { errorMessage } from '../internal/values.js'
 import { type AuthUi, connectWithTimeout, isUnauthorized, type MakeTransport, OAuthRequiredError } from './transport.js'
 
 /** Browser logins are human-paced; a connect-sized timeout would cut them off. */
@@ -16,7 +17,7 @@ const OAUTH_FLOW_TIMEOUT_MS = 180_000
  * unchanged so its message is not doubled. */
 function asOAuthRequiredError(name: string, error: unknown): OAuthRequiredError {
   if (error instanceof OAuthRequiredError) return error
-  const detail = error instanceof Error ? error.message : String(error)
+  const detail = errorMessage(error)
   return new OAuthRequiredError(`login for ${name} failed: ${detail}`)
 }
 

package/extensions/mcp/policy.ts

@@ -9,6 +9,7 @@ import * as path from 'node:path'
 import { claudeConfigDir } from '../internal/config-dir.js'
 import { managedSettingsFile } from '../internal/managed-settings.js'
 import { findNearestFile } from '../internal/project-root.js'
+import { errorMessage } from '../internal/values.js'
 import { interpolateEnv, type ServerConfig } from './config.js'
 
 export interface ProjectServerPolicy {
@@ -151,7 +152,13 @@ export function urlPatternMatches(pattern: string, url: string): boolean {
   return wildcardRegExp(patternParts.path).test(urlParts.path ?? '/')
 }
 
-const configUrl = (config: ServerConfig): string | undefined => (config as { url?: string }).url
+/** A config file is user- or repo-written JSON, so any field can hold any value. Only a
+ * string `url` makes a server remote: a config that carries some other value there is
+ * still gated by its command, and no policy entry is evaluated against a non-string. */
+const configUrl = (config: ServerConfig): string | undefined => {
+  const url = (config as { url?: unknown }).url
+  return typeof url === 'string' ? url : undefined
+}
 const configArgv = (config: ServerConfig): string[] | undefined => {
   const command = (config as { command?: string }).command
   if (typeof command !== 'string') return undefined
@@ -227,7 +234,7 @@ export function loadManagedMcpServers(managedFile: string = managedSettingsFile(
   } catch (error) {
     // Present but corrupt: fail closed to an empty managed set, exactly like an empty map,
     // rather than reopening the user/project/plugin scopes.
-    console.warn(`pi-code-mcp: managed-mcp.json is present but not valid JSON (${file}); failing closed to no MCP servers: ${error instanceof Error ? error.message : String(error)}`)
+    console.warn(`pi-code-mcp: managed-mcp.json is present but not valid JSON (${file}); failing closed to no MCP servers: ${errorMessage(error)}`)
     return {}
   }
   if (parsed === null || typeof parsed !== 'object') return {}

package/extensions/memory.ts

@@ -20,8 +20,9 @@ import { readManagedSettings } from './internal/managed-settings.js'
 import { capForContext } from './internal/output-guard.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { 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 { errorMessage } from './internal/values.js'
 
 export const INDEX_FILE = 'MEMORY.md'
 
@@ -152,7 +153,7 @@ export function migrateLegacyStore(cwd: string): void {
     } catch (error) {
       // A failed migration must not take down session start, but the session then has no
       // memories while they sit under the old slug, which reads as having lost them.
-      console.warn(`pi-code-memory: could not move ${legacy} to ${current}: ${error instanceof Error ? error.message : String(error)}; this session starts without those memories`)
+      console.warn(`pi-code-memory: could not move ${legacy} to ${current}: ${errorMessage(error)}; this session starts without those memories`)
     }
     return
   }
@@ -236,7 +237,7 @@ function readMemory(dir: string, name: string): MemoryToolResult {
     // Only a missing file is "no such memory"; anything else (a directory in its place, a
     // permission problem) sends the model hunting for a name that is actually there.
     if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-      return { content: [{ type: 'text', text: `Memory ${name} could not be read: ${error instanceof Error ? error.message : String(error)}` }], details: {} }
+      return { content: [{ type: 'text', text: `Memory ${name} could not be read: ${errorMessage(error)}` }], details: {} }
     }
     return { content: [{ type: 'text', text: `No memory named ${name}.` }], details: {} }
   }
@@ -257,7 +258,7 @@ async function deleteMemory(dir: string, indexPath: string, name: string): Promi
       return { content: [{ type: 'text', text: `Deleted memory ${name}.` }], details: {} }
     })
   } catch (error) {
-    return { content: [{ type: 'text', text: `Memory delete failed: ${error instanceof Error ? error.message : String(error)}. Nothing was deleted.` }], details: {} }
+    return { content: [{ type: 'text', text: `Memory delete failed: ${errorMessage(error)}. Nothing was deleted.` }], details: {} }
   }
 }
 
@@ -350,15 +351,9 @@ export function memorySettingsFiles(cwd: string, home: string, approved: boolean
  * managed policy settings win over every file, per Claude's settings precedence. */
 export function readMemorySettings(files: string[], managed: Record<string, unknown> = readManagedSettings()): { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } {
   const merged: { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } = {}
-  for (const file of files) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      if (settings === null || typeof settings !== 'object') continue
-      if ('autoMemoryEnabled' in settings) merged.autoMemoryEnabled = settings.autoMemoryEnabled
-      if ('autoMemoryDirectory' in settings) merged.autoMemoryDirectory = settings.autoMemoryDirectory
-    } catch {
-      // missing or invalid settings file: skip
-    }
+  for (const settings of readSettingsChain(files)) {
+    if ('autoMemoryEnabled' in settings) merged.autoMemoryEnabled = settings.autoMemoryEnabled
+    if ('autoMemoryDirectory' in settings) merged.autoMemoryDirectory = settings.autoMemoryDirectory
   }
   if ('autoMemoryEnabled' in managed) merged.autoMemoryEnabled = managed.autoMemoryEnabled
   if ('autoMemoryDirectory' in managed) merged.autoMemoryDirectory = managed.autoMemoryDirectory
@@ -478,7 +473,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
           // Awaited here, not returned: the catch must see a queued write's rejection.
           return await saveMemory(dir, indexPath, name, params.description, params.content)
         } catch (error) {
-          return { content: [{ type: 'text' as const, text: `Memory save failed: ${error instanceof Error ? error.message : String(error)}. The index was left untouched.` }], details: {} }
+          return { content: [{ type: 'text' as const, text: `Memory save failed: ${errorMessage(error)}. The index was left untouched.` }], details: {} }
         } finally {
           indexCache = null
         }
@@ -520,7 +515,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
         try {
           result = setAutoMemoryEnabledSetting(home, next)
         } catch (error) {
-          ctx.ui.notify(`Could not update auto memory: ${error instanceof Error ? error.message : String(error)}`, 'error')
+          ctx.ui.notify(`Could not update auto memory: ${errorMessage(error)}`, 'error')
           return
         }
         if (!result.ok) {

package/extensions/output-styles.ts

@@ -24,13 +24,13 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { atomicWriteFile } from './internal/atomic-write.js'
-
 import { claudeConfigDir } from './internal/config-dir.js'
 import { readManagedSettings } from './internal/managed-settings.js'
 import { installedPlugins, pluginComponentPath } from './internal/plugins.js'
 import { isProjectApproved } from './internal/project-approval.js'
 import { ancestorDirs, findNearestDir, findNearestFile } from './internal/project-root.js'
-import { claudeSettingsChain } from './internal/settings-chain.js'
+import { claudeSettingsChain, readSettingsChain } from './internal/settings-chain.js'
+import { isDirectory } from './internal/values.js'
 
 export interface OutputStyle {
   name: string
@@ -87,14 +87,6 @@ export function applyStyle(systemPrompt: string, style: OutputStyle): string {
   return `${systemPrompt}\n\n${styleSection}`
 }
 
-function isDirectory(target: string): boolean {
-  try {
-    return fs.statSync(target).isDirectory()
-  } catch {
-    return false
-  }
-}
-
 /**
  * Existing `.claude/output-styles` directories, user first then project. The project
  * directory is included only for trusted projects, since its style body is injected
@@ -159,13 +151,8 @@ export function settingsFiles(cwd: string, home: string, trusted: boolean): stri
 export function readActiveStyleName(files: string[], managed: Record<string, unknown> = readManagedSettings()): string | undefined {
   if (typeof managed.outputStyle === 'string') return managed.outputStyle
   let name: string | undefined
-  for (const file of files) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      if (typeof settings.outputStyle === 'string') name = settings.outputStyle
-    } catch {
-      // missing or invalid file: skip
-    }
+  for (const settings of readSettingsChain(files)) {
+    if (typeof settings.outputStyle === 'string') name = settings.outputStyle
   }
   return name
 }

package/extensions/plan-mode/index.ts

@@ -19,7 +19,7 @@ import { Key } from '@earendil-works/pi-tui'
 import { Type } from 'typebox'
 
 import { PLAN_MODE_CHANNEL } from '../internal/plan-mode-state.js'
-import { extractTodoItems, isSafeCommand, markCompletedSteps, planToTodos, type TodoItem } from './utils.js'
+import { extractTodoItems, isSafeCommand, markCompletedSteps, planToTodos, restoredPlanState, type TodoItem } from './utils.js'
 
 // Tools
 const PLAN_MODE_TOOLS = ['read', 'bash', 'grep', 'find', 'ls', 'question', 'plan_mode_complete']
@@ -433,14 +433,14 @@ After completing a step, include a [DONE:n] tag in your response.`,
     // rewind past a plan it would resurrect the abandoned plan and its tool restriction.
     const entries = ctx.sessionManager.getBranch()
 
-    // Restore persisted state
-    const planModeEntry = findLast(entries, (e: { type: string; customType?: string }) => e.type === 'custom' && e.customType === 'plan-mode') as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean; savedTools?: string[] } } | undefined
+    // Restore persisted state. The entry is JSON on disk, so every field is checked
+    // before it is used: savedTools reaches pi.setActiveTools.
+    const planModeEntry = findLast(entries, (e: { type: string; customType?: string }) => e.type === 'custom' && e.customType === 'plan-mode') as { data?: unknown } | undefined
+    const restored = restoredPlanState(planModeEntry?.data)
 
-    if (planModeEntry?.data) {
-      planModeEnabled = planModeEntry.data.enabled ?? planModeEnabled
-      todoItems = planModeEntry.data.todos ?? todoItems
-      executionMode = planModeEntry.data.executing ?? executionMode
-    }
+    planModeEnabled = restored.enabled ?? planModeEnabled
+    todoItems = restored.todos ?? todoItems
+    executionMode = restored.executing ?? executionMode
     publishPlanState()
 
     // On resume: re-scan messages after the last "plan-mode-execute" to rebuild
@@ -456,7 +456,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
       // across /reload and cost the session edit and write for good; applying the
       // snapshot when plan mode is off would instead push a stale set over whatever
       // pi has registered since, so it stays scoped to this branch.
-      savedTools = planModeEntry?.data?.savedTools ?? pi.getActiveTools()
+      savedTools = restored.savedTools ?? pi.getActiveTools()
       pi.setActiveTools(PLAN_MODE_TOOLS.filter((t) => savedTools.includes(t)))
       // --plan enters plan mode without ever toggling, so nothing has persisted yet
       // and a /reload would find no snapshot to restore from. Record it now, while