pi-code 1.0.56 → 1.0.57

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
@@ -228,7 +229,7 @@ export async function runHttpHook(hook: { type?: string; command: string; url?:
     // 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: error instanceof Error ? error.message : String(error), timedOut: name === 'TimeoutError' || name === 'AbortError' }
+    return { code: 1, stdout: '', stderr: errorMessage(error), timedOut: name === 'TimeoutError' || name === 'AbortError' }
   }
 }
 
@@ -262,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> {
@@ -328,7 +329,7 @@ export async function runMcpToolHook(hook: HookCommand, payload: unknown, timeou
   })
   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 {

package/extensions/internal/command-file.ts

@@ -2,9 +2,13 @@
  * Parsing and discovery for Claude Code slash-command files.
  *
  * pi's own prompt-template loader reads only `description` and `argument-hint`
- * from one flat directory, so the rest of Claude's command contract (namespaced
- * subdirectories, `allowed-tools`, `model`, `!` bash blocks, `@file` refs) lives
- * here and is applied by commands.ts when it registers each command itself.
+ * from one flat directory, so the rest of Claude's command contract lives here and is
+ * applied by commands.ts when it registers each command itself: namespaced
+ * subdirectories, `allowed-tools`, `model`, and the argument substitutions.
+ *
+ * Running what a body carries, the `!` bash blocks and `@file` references, is the other
+ * half and lives in command-spans.ts; skills.ts and the subagent loader import this file
+ * alone and never pull a shell resolver in.
  *
  * Docs: https://code.claude.com/docs/en/slash-commands.md
  */
@@ -13,8 +17,6 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 
 import { parseFrontmatter } from '@earendil-works/pi-coding-agent'
-import { splitSegments } from './shell-split.js'
-import { type Fence, fenceMarker, stepFence } from './strip-comments.js'
 
 /** The pi file tools a Claude path rule can govern. */
 export type PathRuleTool = 'read' | 'edit' | 'write'
@@ -427,239 +429,3 @@ export function discoverCommandFiles(root: string): DiscoveredCommand[] {
   walk(root, '')
   return found
 }
-
-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, '$&$&')
-}
-
-import { bashBinary } from './shell-resolve.js'
-
-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)
-}