pi-code 1.0.56 → 1.0.58

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)
-}

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