pi-code 1.0.3 → 1.0.5

package/extensions/internal/command-file.ts

@@ -14,19 +14,34 @@ import * as path from 'node:path'
 
 import { parseFrontmatter } from '@earendil-works/pi-coding-agent'
 
+import { splitSegments } from './shell-split.js'
+
 export interface ParsedCommand {
   description: string
   argumentHint?: string
   allowedTools?: string[]
+  /** Claude `Bash(...)` specifiers, present only when every bash grant is scoped. */
+  bashRules?: string[]
+  /** Claude path rules per pi file tool, from Read(...)/Edit(...)/Write(...) grants. */
+  pathRules?: Partial<Record<'read' | 'edit' | 'write', string[]>>
+  /** Names from the `arguments:` frontmatter list, mapped to positions in order. */
+  argumentNames?: string[]
+  /** Tools removed from the pool while the command's turn runs. */
+  disallowedTools?: string[]
+  /** `shell:` frontmatter: `bash` (the default) or `powershell`, choosing how the
+   * command's injected spans run (see spanExec). */
+  shell?: string
   model?: string
   disableModelInvocation: boolean
   body: string
 }
 
 export interface DiscoveredCommand {
-  /** Claude's namespaced name: a nested file is `dir:name`. */
+  /** Claude's namespaced name: a nested file is `dir:name`, a plugin's is `plugin:name`. */
   name: string
   filePath: string
+  /** Set for plugin commands, carrying the ${CLAUDE_PLUGIN_*} and ${user_config.*} substitution sources. */
+  plugin?: { root: string; dataDir: string; userConfig?: Record<string, string> }
 }
 
 /** Claude tool names are PascalCase and do not all exist in pi: `Glob` is pi's
@@ -54,11 +69,11 @@ const CLAUDE_TOOL_MAP: Record<string, string> = {
 }
 
 /**
- * Claude scopes a grant to arguments: `Bash(git add:*)` allows exactly those commands.
- * pi's active-tool list is per tool, with no argument dimension, so the scope is
- * dropped and the base tool is granted. Keeping the scope in the name matched nothing
- * when the list was intersected with the active tools, which left a command declaring
- * only scoped grants running with no tools at all.
+ * The pi tool name for one grant entry, scope and all: `Bash(git add:*)` is `bash`.
+ * Keeping the scope in the name matched nothing when the list was intersected with
+ * the active tools, which left a command declaring only scoped grants running with
+ * no tools at all. The scope itself is not dropped: parseToolGrants keeps bash
+ * scopes for call-time enforcement.
  */
 export function normalizeToolName(name: string): string {
   const lower = name.trim().toLowerCase()
@@ -94,19 +109,82 @@ export function toolEntries(raw: string): string[] {
   return entries.map((entry) => entry.trim()).filter(Boolean)
 }
 
+export interface ToolGrants {
+  /** pi tool names to grant, deduplicated in first-seen order. */
+  tools: string[]
+  /** Claude `Bash(...)` specifiers, present only when every bash grant is scoped:
+   * an unscoped `Bash` entry is the wider grant and wins over its scoped siblings. */
+  bashRules?: string[]
+  /** Claude path rules per pi file tool, absent for a tool with an unscoped grant.
+   * Edit scopes govern writes too, as Claude documents; Write scopes are honored
+   * rather than Claude's accept-and-warn-then-ignore, which would fail open here. */
+  pathRules?: Partial<Record<'read' | 'edit' | 'write', string[]>>
+  /** Entries that carried an argument scope, in their original spelling. */
+  scopedEntries: string[]
+}
+
+/** The pi file tools one Claude path-ruled entry governs. */
+const PATH_RULE_TOOLS: Record<string, Array<'read' | 'edit' | 'write'>> = {
+  read: ['read'],
+  edit: ['edit', 'write'],
+  write: ['write'],
+}
+
 /**
  * A tool grant is either a comma-separated string or a YAML list, and the two mean the
  * same thing. An empty list is not the same as an absent one: it says no tools, so it
- * comes back as an empty array rather than undefined.
+ * comes back with an empty `tools` array rather than as undefined.
+ *
+ * Claude scopes a grant to arguments: `Bash(git add:*)` allows exactly those commands.
+ * pi's active-tool list is per tool, with no argument dimension, so the base tool is
+ * granted and the scope is kept: commands.ts enforces bash scopes at tool_call time,
+ * and the subagent's frontmatter parsing rejects a scoped grant it cannot express.
+ * A scope on any other tool is dropped, which widens that grant; bash is the one
+ * whose widening reaches everything, so it is the one enforced.
  */
-export function parseToolList(raw: unknown): string[] | undefined {
+export function parseToolGrants(raw: unknown): ToolGrants | undefined {
   if (raw === undefined || raw === null) return undefined
   let items: unknown[]
   if (Array.isArray(raw)) items = raw
   else if (typeof raw === 'string') items = toolEntries(raw)
   else return undefined
   if (items.some((item) => typeof item !== 'string')) return undefined
-  return [...new Set((items as string[]).map(normalizeToolName).filter(Boolean))]
+
+  const tools: string[] = []
+  const scopedEntries: string[] = []
+  const bashRules: string[] = []
+  let bashUnscoped = false
+  const pathScopes: Record<'read' | 'edit' | 'write', string[]> = { read: [], edit: [], write: [] }
+  const pathUnscoped = new Set<'read' | 'edit' | 'write'>()
+  for (const item of items as string[]) {
+    const entry = item.trim()
+    const name = normalizeToolName(entry)
+    if (!name) continue
+    if (!tools.includes(name)) tools.push(name)
+    const open = entry.indexOf('(')
+    if (open === -1) {
+      if (name === 'bash') bashUnscoped = true
+      for (const tool of PATH_RULE_TOOLS[name] ?? []) pathUnscoped.add(tool)
+      continue
+    }
+    scopedEntries.push(entry)
+    const scope = entry.slice(open + 1, entry.endsWith(')') ? -1 : undefined).trim()
+    // An empty specifier (`Bash()`, `Read()`) matches nothing and must not read as
+    // the unscoped grant it explicitly is not: it is recorded so the tool stays
+    // restricted, and the matchers treat an empty rule as matching no input.
+    if (name === 'bash') bashRules.push(scope)
+    for (const tool of PATH_RULE_TOOLS[name] ?? []) pathScopes[tool].push(scope)
+  }
+  const pathRules: ToolGrants['pathRules'] = {}
+  for (const tool of ['read', 'edit', 'write'] as const) {
+    if (!pathUnscoped.has(tool) && pathScopes[tool].length > 0) pathRules[tool] = pathScopes[tool]
+  }
+  return {
+    tools,
+    scopedEntries,
+    bashRules: !bashUnscoped && bashRules.length > 0 ? bashRules : undefined,
+    pathRules: Object.keys(pathRules).length > 0 ? pathRules : undefined,
+  }
 }
 
 /** YAML types a bare scalar, so a model named `3.5` arrives as a number, not a string. */
@@ -118,6 +196,22 @@ const text = (value: unknown): string => {
 /** Claude writes `argument-hint: [pr]`, which YAML reads as a list; render it back. */
 const hint = (value: unknown): string => (Array.isArray(value) ? `[${value.join(', ')}]` : text(value))
 
+const ARGUMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** The `arguments:` frontmatter: a YAML list or a space- or comma-separated string
+ * of names mapping to positions in order. Invalid names are dropped, and ARGUMENTS
+ * itself is reserved by the built-in placeholder. */
+function parseArgumentNames(raw: unknown): string[] | undefined {
+  let items: string[]
+  if (Array.isArray(raw)) items = raw.map((entry) => String(entry))
+  else if (typeof raw === 'string') items = raw.split(/[\s,]+/)
+  else return undefined
+  const names = items.map((name) => name.trim()).filter((name) => ARGUMENT_NAME.test(name) && name !== 'ARGUMENTS')
+  return names.length > 0 ? names : undefined
+}
+
+const SHELLS = new Set(['bash', 'powershell'])
+
 export function parseCommandFile(content: string): ParsedCommand {
   // pi's own parser, rather than a hand-rolled one: it reads the YAML shapes Claude
   // command files actually use (flow sequences, block lists, quoted and multi-line
@@ -126,10 +220,18 @@ export function parseCommandFile(content: string): ParsedCommand {
   const body = raw.trim()
   const firstLine = body.split('\n').find((line) => line.trim().length > 0) ?? ''
   const disable = frontmatter['disable-model-invocation']
+  const grants = parseToolGrants(frontmatter['allowed-tools'])
+  const shell = text(frontmatter.shell).toLowerCase()
   return {
     description: text(frontmatter.description) || firstLine.slice(0, 60),
     argumentHint: hint(frontmatter['argument-hint']) || undefined,
-    allowedTools: parseToolList(frontmatter['allowed-tools']),
+    allowedTools: grants?.tools,
+    bashRules: grants?.bashRules,
+    pathRules: grants?.pathRules,
+    argumentNames: parseArgumentNames(frontmatter.arguments),
+    // A scope on a disallow entry only denies more than asked, so the drop is safe.
+    disallowedTools: parseToolGrants(frontmatter['disallowed-tools'])?.tools,
+    shell: SHELLS.has(shell) ? shell : undefined,
     model: text(frontmatter.model) || undefined,
     disableModelInvocation: disable === true || text(disable) === 'true',
     body,
@@ -148,16 +250,80 @@ export function splitArgs(args: string): string[] {
   return out
 }
 
-/** Claude's substitutions: `$ARGUMENTS`, `$@`, `$1`..`$n`, `${n:-default}`. An
- * unfilled positional becomes empty rather than leaking its literal token. */
-export function substituteArgs(body: string, args: string): string {
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+
+/** One alternation covering every argument placeholder plus the two escape forms.
+ * Alternation order is load-bearing: escapes first (so `\$1` never expands), the
+ * bracketed forms before `$ARGUMENTS` (so `$ARGUMENTS[0]` is not read as the bare
+ * placeholder plus literal brackets). `(?!)` never matches, standing in when no
+ * names are declared. */
+function argPattern(names: string[]): RegExp {
+  const nameAlt = names.length > 0 ? names.map(escapeRegExp).join('|') : '(?!)'
+  return new RegExp(
+    String.raw`\\{2}(?=\$)` + // doubled backslash: both stay, the token after still expands
+      String.raw`|\\\$(?=\d|@|\{|ARGUMENTS\b|(?:${nameAlt})\b)` + // escape: before any placeholder this expands, incl. $@ and ${...:-}
+      String.raw`|\$ARGUMENTS\[(\d+)\]` +
+      String.raw`|\$\{(\d+):-([^}]*)\}` +
+      String.raw`|\$\{ARGUMENTS:-([^}]*)\}` +
+      String.raw`|\$ARGUMENTS\b` +
+      String.raw`|\$@` +
+      String.raw`|\$(\d+)` +
+      String.raw`|\$(${nameAlt})\b`,
+    'g',
+  )
+}
+
+export interface SubstitutedArgs {
+  text: string
+  /** Whether any placeholder actually read the arguments; drives Claude's
+   * `ARGUMENTS: <value>` append when a command never looks at what was passed. */
+  consumed: boolean
+}
+
+/**
+ * Claude's substitutions, per the current skills docs: `$ARGUMENTS`,
+ * `$ARGUMENTS[N]` and its `$N` shorthand (0-based: `$0` is the first argument),
+ * `$name` for names declared in `arguments:` frontmatter, plus the pi extras `$@`
+ * and `${N:-default}`/`${ARGUMENTS:-default}`. An unfilled indexed placeholder
+ * stays literal; a declared name with no argument becomes empty; `\$` escapes only
+ * a real placeholder and a doubled backslash keeps both while still expanding.
+ * One pass with a replacer function: sequential string passes both interpreted
+ * `$&`-style metacharacters in the arguments and re-scanned substituted text.
+ */
+export function substituteArgsDetailed(body: string, args: string, names: string[] = []): SubstitutedArgs {
   const parts = splitArgs(args)
-  return body
-    .replaceAll(/\$\{(\d+):-([^}]*)\}/g, (_m, index: string, fallback: string) => parts[Number(index) - 1] ?? fallback)
-    .replaceAll(/\$\{ARGUMENTS:-([^}]*)\}/g, (_m, fallback: string) => (args.trim() ? args.trim() : fallback))
-    .replaceAll(/\$ARGUMENTS\b/g, args.trim())
-    .replaceAll('$@', args.trim())
-    .replaceAll(/\$(\d+)/g, (_m, index: string) => parts[Number(index) - 1] ?? '')
+  const all = args.trim()
+  let consumed = false
+  const fill = (value: string | undefined, orElse: string): string => {
+    if (value === undefined) return orElse
+    consumed = true
+    return value
+  }
+  const text = body.replaceAll(argPattern(names), (token, bracketIdx?: string, defIdx?: string, defVal?: string, argsDefault?: string, shorthandIdx?: string, name?: string) => {
+    if (token === '\\\\') return token
+    if (token === '\\$') return '$'
+    if (bracketIdx !== undefined) return fill(parts[Number(bracketIdx)], token)
+    if (defIdx !== undefined) return fill(parts[Number(defIdx)], defVal ?? '')
+    if (argsDefault !== undefined) {
+      consumed = true
+      return all || argsDefault
+    }
+    if (shorthandIdx !== undefined) return fill(parts[Number(shorthandIdx)], token)
+    if (name !== undefined) return fill(parts[names.indexOf(name)], '')
+    consumed = true
+    return all // $ARGUMENTS or $@
+  })
+  return { text, consumed }
+}
+
+export function substituteArgs(body: string, args: string, names: string[] = []): string {
+  return substituteArgsDetailed(body, args, names).text
+}
+
+/** Claude's `${CLAUDE_*}` string substitutions. A backslash does not prevent these,
+ * per the docs, and an unknown variable stays literal. */
+export function substituteVars(text: string, vars: Record<string, string | undefined>): string {
+  return text.replaceAll(/\$\{(CLAUDE_[A-Z0-9_]+)\}/g, (token, name: string) => vars[name] ?? token)
 }
 
 /** `a/b/c.md` becomes Claude's `a:b:c`. */
@@ -187,23 +353,150 @@ export function discoverCommandFiles(root: string): DiscoveredCommand[] {
 
 export type CommandExec = (command: string) => Promise<{ stdout: string; stderr: string; code: number }>
 
-/** Spans of a body that are inside a fenced code block, where Claude's dynamic
- * syntax is literal text rather than an instruction. */
-function fencedRanges(body: string): Array<[number, number]> {
-  const ranges: Array<[number, number]> = []
-  const fence = /^(```|~~~)[^\n]*$/gm
-  let open: number | undefined
+/** 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, '$&$&')
+}
+
+/** The PowerShell names worth trying: pwsh everywhere it installs, plus the
+ * Windows spellings on win32, where powershell.exe ships with the OS. */
+const powershellCandidates = (platform: string): string[] => (platform === 'win32' ? ['pwsh', 'pwsh.exe', 'powershell.exe'] : ['pwsh'])
+
+/** First PowerShell binary found on PATH, or undefined when none is installed. */
+export function resolvePowershellBinary(platform: string = process.platform, env: Record<string, string | undefined> = process.env): string | undefined {
+  const dirs = (env.PATH ?? '').split(path.delimiter).filter(Boolean)
+  for (const candidate of powershellCandidates(platform)) {
+    for (const dir of dirs) {
+      const full = path.join(dir, candidate)
+      try {
+        fs.accessSync(full, fs.constants.X_OK)
+        if (fs.statSync(full).isFile()) return full
+      } catch {
+        // not here; keep looking
+      }
+    }
+  }
+  return undefined
+}
+
+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 exec invocation for one injected span, honoring the `shell:` frontmatter.
+ * The default (absent or `bash`) runs through /bin/sh; `powershell` resolves a
+ * PowerShell binary and runs the span with -Command, falling back to /bin/sh when
+ * none is installed so the command still works, per Claude's shell matrix. 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 resolver is a parameter rather than a default so the caller passes its own
+ * imported binding, which keeps the lookup mockable in tests.
+ */
+export function spanExec(shell: string | undefined, projectDir: string, script: string, resolveBinary: () => string | undefined): SpanExec {
+  if (shell === 'powershell') {
+    const binary = resolveBinary()
+    if (binary !== undefined) {
+      const preamble = `$ErrorActionPreference='Continue'\n$env:CLAUDE_PROJECT_DIR='${powershellQuote(projectDir)}'`
+      // 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.
+      return { command: binary, args: ['-NoProfile', '-NonInteractive', '-Command', `${preamble}\n& {\n${script}\n}\nexit $LASTEXITCODE`], mergeStreams: true }
+    }
+  }
+  const quoted = projectDir.replaceAll("'", String.raw`'\''`)
+  // 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.
+  return { command: '/bin/sh', args: ['-c', `export CLAUDE_PROJECT_DIR='${quoted}'\n{ :\n${script}\n} 2>&1`] }
+}
+
+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. */
+function fenceBlocks(body: string): FenceBlock[] {
+  const blocks: FenceBlock[] = []
+  const fence = /^(```|~~~)([^\n]*)$/gm
+  let open: { index: number; exec: boolean; contentStart: number } | undefined
   let match = fence.exec(body)
   while (match !== null) {
-    if (open === undefined) open = match.index
-    else {
-      ranges.push([open, match.index + match[0].length])
+    if (open === undefined) {
+      open = { index: match.index, exec: match[1] === '```' && match[2].trim() === '!', contentStart: match.index + match[0].length + 1 }
+    } else {
+      blocks.push({ start: open.index, end: match.index + match[0].length, exec: open.exec, content: body.slice(Math.min(open.contentStart, match.index), match.index).replace(/\n$/, '') })
       open = undefined
     }
     match = fence.exec(body)
   }
-  if (open !== undefined) ranges.push([open, body.length])
-  return ranges
+  // 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
+}
+
+/** Spans of a body inside a protective fenced code block. */
+function fencedRanges(body: string): Array<[number, number]> {
+  return fenceBlocks(body)
+    .filter((block) => !block.exec)
+    .map((block) => [block.start, block.end])
+}
+
+/** 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. */
+const EXIT_ONE_OK = new Set(['grep', 'rg', 'egrep', 'fgrep', 'find', 'diff', 'test', '['])
+
+const isCarveoutSegment = (segment: string): boolean => {
+  const words = segment.trim().split(/\s+/)
+  if (words[0] === 'git') return words[1] === 'diff' || words[1] === 'grep'
+  return EXIT_ONE_OK.has(words[0])
+}
+
+function benignExitOne(command: string): 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(isCarveoutSegment)
+  return isCarveoutSegment(segments.at(-1) ?? '')
+}
+
+/** 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): Promise<string> {
+  const result = await exec(command)
+  if (result.code !== 0 && !(result.code === 1 && benignExitOne(command))) {
+    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)
@@ -226,32 +519,63 @@ function readReference(cwd: string, reference: string): string | undefined {
   }
 }
 
+interface DynamicSpan {
+  start: number
+  end: number
+  run: () => Promise<string>
+}
+
 /** Claude's dynamic command content: `` !`cmd` `` runs a shell command and pastes
- * its output, `@path` inlines a file. Both are skipped inside fenced code blocks. */
+ * 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): Promise<string> {
-  const fenced = fencedRanges(body)
-
-  const commands: Array<{ span: string; command: string; index: number }> = []
-  const bashPattern = /!`([^`]+)`/g
-  let bashMatch = bashPattern.exec(body)
-  while (bashMatch !== null) {
-    if (!inRanges(fenced, bashMatch.index)) commands.push({ span: bashMatch[0], command: bashMatch[1], index: bashMatch.index })
-    bashMatch = bashPattern.exec(body)
-  }
+  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)
 
-  let expanded = body
-  for (const entry of commands) {
-    const result = await exec(entry.command)
-    const output = result.code === 0 ? result.stdout.trimEnd() : `(command failed: ${entry.command})\n${result.stderr.trim() || result.stdout.trim()}`
-    expanded = expanded.replace(entry.span, output)
+  const spans: DynamicSpan[] = []
+  for (const block of blocks) {
+    if (block.exec) spans.push({ start: block.start, end: block.end, run: () => runSpan(exec, block.content, '```!') })
+  }
+  // `!` 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}\``)) })
+  }
+  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`
+      },
+    })
   }
 
-  // Ranges are recomputed: command output can change offsets.
-  const fencedAfter = fencedRanges(expanded)
-  return expanded.replaceAll(/(^|\s)@(\S+)/g, (whole, lead: string, reference: string, offset: number) => {
-    if (inRanges(fencedAfter, offset)) return whole
-    const content = readReference(cwd, reference)
-    if (content === undefined) return whole
-    return `${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/html-markdown.ts

@@ -0,0 +1,61 @@
+/**
+ * HTML to markdown conversion for web_fetch, mirroring Claude's WebFetch, which
+ * converts pages to markdown before the model reads them.
+ *
+ * A regex pipeline, not a DOM: pi ships no HTML parser and the output is prose
+ * for a model, not a rendering. Every pattern bounds its tag matches with
+ * [^<>]* so a failed match stops at the next tag instead of rescanning to the
+ * end of input, keeping the pass linear on hostile pages.
+ */
+
+const NAMED_ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' }
+
+function decodeAllEntities(text: string): string {
+  return text.replace(/&(?:#x([0-9a-fA-F]+)|#(\d+)|(amp|lt|gt|quot|apos|nbsp));/g, (token, hex?: string, dec?: string, named?: string) => {
+    if (named) return NAMED_ENTITIES[named] ?? token
+    const code = hex ? Number.parseInt(hex, 16) : Number(dec)
+    return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : token
+  })
+}
+
+const stripInnerTags = (html: string): string => html.replace(/<[^<>]*>/g, '')
+
+export function htmlToMarkdown(html: string): string {
+  // Pre blocks are lifted out first so no later transform touches their content.
+  const preBodies: string[] = []
+  let work = html
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<(script|style|noscript|head|svg)\b[^<>]*>[\s\S]*?<\/\1[^<>]*>/gi, ' ')
+    .replace(/<pre\b[^<>]*>([\s\S]*?)<\/pre>/gi, (_whole, inner: string) => {
+      preBodies.push(decodeAllEntities(stripInnerTags(inner)).replace(/^\n+|\n+$/g, ''))
+      return `\n\n\uE000PRE${preBodies.length - 1}\uE000\n\n`
+    })
+
+  work = work
+    .replace(/<code\b[^<>]*>([\s\S]*?)<\/code>/gi, (_whole, inner: string) => `\`${stripInnerTags(inner)}\``)
+    // Only real web links become markdown links; fragment and javascript hrefs
+    // keep their label and lose the target.
+    .replace(/<a\b[^<>]*?href=(?:"([^"]*)"|'([^']*)')[^<>]*>([\s\S]*?)<\/a>/gi, (_whole, dq: string | undefined, sq: string | undefined, inner: string) => {
+      const href = decodeAllEntities(dq ?? sq ?? '')
+      const label = stripInnerTags(inner).trim()
+      if (!label) return ' '
+      return /^https?:\/\//i.test(href) ? `[${label}](${href})` : label
+    })
+    .replace(/<(strong|b)\b[^<>]*>([\s\S]*?)<\/\1>/gi, (_whole, _tag, inner: string) => `**${stripInnerTags(inner).trim()}**`)
+    .replace(/<(em|i)\b[^<>]*>([\s\S]*?)<\/\1>/gi, (_whole, _tag, inner: string) => `*${stripInnerTags(inner).trim()}*`)
+    .replace(/<h([1-6])\b[^<>]*>([\s\S]*?)<\/h\1>/gi, (_whole, level: string, inner: string) => `\n\n${'#'.repeat(Number(level))} ${stripInnerTags(inner).trim()}\n\n`)
+    .replace(/<img\b[^<>]*?alt=(?:"([^"]*)"|'([^']*)')[^<>]*>/gi, (_whole, dq?: string, sq?: string) => dq ?? sq ?? '')
+    .replace(/<li\b[^<>]*>/gi, '\n- ')
+    .replace(/<blockquote\b[^<>]*>/gi, '\n\n> ')
+    .replace(/<\/(?:td|th)>/gi, ' | ')
+    .replace(/<(?:br|hr)\b[^<>]*>/gi, '\n')
+    .replace(/<\/(?:p|div|section|article|ul|ol|li|table|tr|blockquote|tbody|thead|header|footer|main|nav)[^<>]*>/gi, '\n\n')
+
+  const text = decodeAllEntities(work.replace(/<[^<>]*>/g, ''))
+    .replace(/[ \t]+/g, ' ')
+    .replace(/ ?\n ?/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+
+  return text.replace(/\uE000PRE(\d+)\uE000/g, (_whole, index: string) => `\`\`\`\n${preBodies[Number(index)]}\n\`\`\``)
+}

package/extensions/internal/instruction-events.ts

@@ -0,0 +1,70 @@
+/**
+ * Channel and payload for instruction-file loads published on pi's shared extension
+ * event bus. Producers are claude-rules (a scoped rule lazily attaching on a matching
+ * file touch, load_reason `path_glob_match`) and context-imports (resolved `@imports`,
+ * load_reason `include`, and CLAUDE.local.md loads, load_reason `session_start`).
+ * Hooks bridge them to Claude's InstructionsLoaded event, which is strictly
+ * observational. pi loads extensions without a shared module cache, so state rides
+ * the bus, mirroring subagent-events.
+ */
+
+import * as path from 'node:path'
+
+export const INSTRUCTIONS_CHANNEL = 'pi-code:instructions'
+
+/** Claude's memory_type vocabulary for InstructionsLoaded payloads. */
+export type InstructionMemoryType = 'User' | 'Project' | 'Local' | 'Managed'
+
+const MEMORY_TYPES: readonly string[] = ['User', 'Project', 'Local', 'Managed']
+
+export interface InstructionLoadEvent {
+  /** Absolute path of the instruction file that entered context. */
+  file_path: string
+  memory_type: InstructionMemoryType
+  /** What caused the load; InstructionsLoaded matchers run against this. */
+  load_reason: string
+  /** The rule's `paths:` globs; present only for path_glob_match. */
+  globs?: string[]
+  /** The file whose access triggered a lazy load. */
+  trigger_file_path?: string
+  /** The importing file, for include loads. */
+  parent_file_path?: string
+}
+
+export function isInstructionLoadEvent(data: unknown): data is InstructionLoadEvent {
+  const event = data as InstructionLoadEvent | null
+  if (event === null || typeof event !== 'object') return false
+  if (typeof event.file_path !== 'string' || typeof event.load_reason !== 'string') return false
+  if (!MEMORY_TYPES.includes(event.memory_type)) return false
+  if (event.globs !== undefined && !(Array.isArray(event.globs) && event.globs.every((glob) => typeof glob === 'string'))) return false
+  if (event.trigger_file_path !== undefined && typeof event.trigger_file_path !== 'string') return false
+  if (event.parent_file_path !== undefined && typeof event.parent_file_path !== 'string') return false
+  return true
+}
+
+/** Claude's memory_type from a file's location: CLAUDE.local.md is Local wherever it
+ * sits; a file under home but outside the project is User; everything else, the
+ * project itself included (which commonly lives under home), is Project. */
+export function memoryTypeForPath(filePath: string, home: string, projectRoot: string): InstructionMemoryType {
+  if (path.basename(filePath) === 'CLAUDE.local.md') return 'Local'
+  const isUnder = (root: string): boolean => root.length > 0 && (filePath === root || filePath.startsWith(root + path.sep))
+  if (isUnder(projectRoot)) return 'Project'
+  // Monorepo: repoRoot stops at the nearest .git OR package.json, so a git-root
+  // CLAUDE.md can sit above the projectRoot a subpackage session reports. A file
+  // whose directory is a strict ancestor of the project root is still project
+  // memory. The home directory itself stays User: a home-level context file is
+  // user config even when the project lives under home.
+  const dir = path.dirname(filePath)
+  if (dir !== home && (projectRoot === dir || projectRoot.startsWith(dir + path.sep))) return 'Project'
+  if (isUnder(home)) return 'User'
+  return 'Project'
+}
+
+/** The emit half of pi's EventBus; producers may run under stub hosts without one. */
+export interface InstructionBus {
+  emit(channel: string, data: unknown): void
+}
+
+export function publishInstructionLoad(events: InstructionBus | undefined, event: InstructionLoadEvent): void {
+  events?.emit(INSTRUCTIONS_CHANNEL, event)
+}