pi-code 1.0.1 → 1.0.3

package/README.md

@@ -38,7 +38,7 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 | Feature | Reads / provides | Extension |
 |---|---|---|
 | Global + project rules | `~/.claude/rules`, `.claude/rules` (+ `paths:` frontmatter scoping) | `claude-rules.ts` |
-| Custom slash commands | `.claude/commands/**/*.md` (namespaced `/dir:name`), `$ARGUMENTS`/`$1`, `` !`cmd` `` bash output, `@file` inlining, `allowed-tools`/`model`/`argument-hint` frontmatter; project commands gated on approval | `commands.ts` |
+| Custom slash commands | `.claude/commands/**/*.md` (namespaced `/dir:name`), `$ARGUMENTS`/`$1`, `` !`cmd` `` bash output, `@file` inlining, `allowed-tools`/`argument-hint` frontmatter (`model` is parsed but not yet applied); project commands gated on approval | `commands.ts` |
 | Skills | `.claude/skills` → pi skill discovery, project skills gated on approval (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.ts` |
 | Hooks | `.claude/settings.json` hooks: PreToolUse (blocks, rewrites input via `updatedInput`), PostToolUse (feedback and `additionalContext` land next to the tool result), PostToolUseFailure, SessionStart (context injection), UserPromptSubmit (blocks and injects context), Stop (a block continues the conversation), SubagentStart/SubagentStop, PreCompact, PostCompact, SessionEnd; Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort | `hooks.ts` |
 | Output styles | `.claude/output-styles` + active `outputStyle`; Claude replace semantics with `keep-coding-instructions`; bundled Explanatory/Learning/Proactive; `/output-style [name]` | `output-styles.ts` |
@@ -46,7 +46,7 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 | MCP servers | user `~/.claude.json` (incl. per-project `projects[cwd]` local scope), `~/.pi/agent/mcp.json`; project `.mcp.json`, `.pi/mcp.json` (once approved; `enabledMcpjsonServers`/`disabledMcpjsonServers`/`enableAllProjectMcpServers` honored, consent keys only from non-repo settings); stdio/HTTP/SSE by `type`; `${VAR:-default}` expansion; `MCP_TIMEOUT`/`MCP_TOOL_TIMEOUT`; tools refresh on `list_changed` | `mcp.ts` |
 | Project trust | prompts before loading project config (MCP servers, hooks, agents, rules, output styles, commands, skills) that pi would otherwise trust silently | `internal/project-approval.ts` |
 | Subagents / Task | builtin Explore/Plan/general-purpose agents, `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents`; agent roster with descriptions in the system prompt; `skills` preload; background runs with cancel and resume | `subagent/` |
-| Plan mode | `plan_mode_complete` tool, exact tool snapshot/restore | `plan-mode/` |
+| Plan mode | `plan_mode_complete` tool, tool snapshot/restore that survives `/reload` | `plan-mode/` |
 | Todo list | persistent overlay, status machine, compaction-safe | `todo.ts` |
 | Checkpoints / rewind | shadow-repo snapshots; restore overwrites checkpointed files, keeps files created later; 100 per session, repos pruned after 30 days | `git-checkpoint.ts` |
 | Persistent memory | per-project memories, index injected each session within Claude's 200-line/25KB bound; a save that would overflow it reports why | `memory.ts` |
@@ -57,7 +57,7 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 
 `CLAUDE.md` itself needs no extension: pi loads `CLAUDE.md` / `AGENTS.md` context files natively (global + walking cwd to root). `context-imports.ts` only adds the `@import` resolution pi's loader lacks, appending the imported files without re-injecting the base.
 
-`extensions/internal/` holds shared modules pi's loader must not treat as extensions: `output-guard.ts` (context-budget truncation), `web-transport.ts` (DNS-pinned fetch), and `project-approval.ts` (the trust decision above). The extensions use them; only `internal/` keeps them out of pi's extension scan.
+`extensions/internal/` holds shared modules pi's loader must not treat as extensions: `output-guard.ts` (context-budget truncation), `web-transport.ts` (DNS-pinned fetch), `project-approval.ts` (the trust decision above), `command-file.ts` (slash-command parsing and dynamic content), and the shared-bus contracts `mcp-alias.ts`, `plan-mode-state.ts` and `subagent-events.ts`. The extensions use them; only `internal/` keeps them out of pi's extension scan.
 
 Vendored bases (`question`, `notify`, `status-line`) come from pi's MIT example extensions (see [LICENSE](LICENSE)).
 

package/extensions/commands.ts

@@ -6,8 +6,10 @@
  * is what makes the rest of Claude's command contract reachable: namespaced
  * subdirectories (`frontend/build.md` is `/frontend:build`), `$ARGUMENTS` and
  * positional substitution, `` !`cmd` `` bash output, `@file` inlining, and the
- * `allowed-tools` / `model` / `argument-hint` / `disable-model-invocation`
- * frontmatter.
+ * `allowed-tools` and `argument-hint` frontmatter. `model` and
+ * `disable-model-invocation` are parsed but not applied yet: pi has seams for both
+ * (`pi.setModel`, and commands are user-invoked anyway), so they are a gap rather
+ * than an impossibility.
  *
  * A project command body is repository-controlled text that can now run shell
  * commands and read files, so project commands load only once the project is
@@ -59,6 +61,14 @@ export function collectCommands(dirs: string[]): DiscoveredCommand[] {
 
 export default function commandsExtension(pi: ExtensionAPI) {
   const registered = new Set<string>()
+  /** Tool set to put back once the turn a restricted command drove has ended. */
+  let pendingRestore: string[] | undefined
+
+  pi.on('turn_end', async () => {
+    if (!pendingRestore) return
+    pi.setActiveTools(pendingRestore)
+    pendingRestore = undefined
+  })
 
   async function runCommand(parsed: ParsedCommand, args: string, ctx: ExtensionCommandContext): Promise<void> {
     const withArgs = substituteArgs(parsed.body, args)
@@ -71,17 +81,23 @@ export default function commandsExtension(pi: ExtensionAPI) {
       return { stdout: result.stdout, stderr: result.stderr, code: result.code }
     })
 
-    // allowed-tools restricts the turn the command drives, then the previous set is
-    // restored: the restriction belongs to the command, not to the rest of the session.
-    const saved = parsed.allowedTools ? pi.getActiveTools() : undefined
-    if (parsed.allowedTools && saved) {
-      pi.setActiveTools(parsed.allowedTools.filter((tool) => saved.includes(tool)))
-    }
-    try {
-      pi.sendUserMessage(expanded)
-    } finally {
-      if (saved) pi.setActiveTools(saved)
+    // allowed-tools restricts the turn the command drives, and the previous set is
+    // restored when that turn ends. Restoring inline does not work: sendUserMessage is
+    // fire-and-forget, so the restore would land before the agent ever read the tool
+    // list, leaving the command running with everything enabled.
+    if (parsed.allowedTools) {
+      const saved = pi.getActiveTools()
+      const granted = parsed.allowedTools.filter((tool) => saved.includes(tool))
+      // Only the first restriction in a turn knows the unrestricted set; a second
+      // command would otherwise record the first one's narrowed set as the thing to
+      // restore, and the tools the first command dropped would never come back.
+      pendingRestore ??= saved
+      // `allowed-tools: []` says no tools, and is honored. A non-empty list that
+      // intersects to nothing named only tools pi has none of: that restriction cannot
+      // be expressed, and applying it as "no tools" is not what the command asked for.
+      if (granted.length > 0 || parsed.allowedTools.length === 0) pi.setActiveTools(granted)
     }
+    pi.sendUserMessage(expanded)
   }
 
   pi.on('session_start', async (_event, ctx) => {

package/extensions/hooks.ts

@@ -97,8 +97,14 @@ export function loadHooks(files: string[]): HooksConfig {
     } catch {
       continue
     }
-    for (const [event, matchers] of Object.entries(parsed.hooks ?? {})) {
-      if (Array.isArray(matchers)) config[event] = [...(config[event] ?? []), ...matchers]
+    for (const [event, matchers] of Object.entries(parsed?.hooks ?? {})) {
+      if (!Array.isArray(matchers)) continue
+      // Entries are validated here rather than where they run: a hand-edited settings
+      // file that writes `hooks` as an object instead of a list used to throw out of
+      // the tool_call handler, and pi turns that into an error result, so every tool
+      // call for the rest of the session failed with an opaque type error.
+      const usable = matchers.filter((entry) => isUsableMatcher(entry, file, event))
+      if (usable.length > 0) config[event] = [...(config[event] ?? []), ...usable]
     }
   }
   return config
@@ -124,6 +130,26 @@ function exactListApplies(matcher: string, names: readonly string[]): boolean {
   return names.some((name) => tokens.has(foldName(name)))
 }
 
+/** A matcher entry pi-code can run: an object whose `hooks` is a list. Anything else
+ * is reported by name and skipped, so one bad entry costs its own hooks, not the
+ * session's tool calls. */
+function isUsableMatcher(entry: unknown, file: string, event: string): entry is HookMatcher {
+  const candidate = entry as HookMatcher | null
+  if (candidate === null || typeof candidate !== 'object') {
+    console.warn(`pi-code-hooks: ignoring a non-object ${event} entry in ${file}`)
+    return false
+  }
+  if (candidate.hooks !== undefined && !Array.isArray(candidate.hooks)) {
+    console.warn(`pi-code-hooks: ignoring ${event} entry in ${file}: "hooks" must be a list`)
+    return false
+  }
+  if (candidate.matcher !== undefined && typeof candidate.matcher !== 'string') {
+    console.warn(`pi-code-hooks: ignoring ${event} entry in ${file}: "matcher" must be a string`)
+    return false
+  }
+  return true
+}
+
 function matcherApplies(matcher: string | undefined, names: readonly string[]): boolean {
   if (!matcher || matcher === '*') return true
   if (EXACT_MATCHER.test(matcher)) return exactListApplies(matcher, names)

package/extensions/internal/command-file.ts

@@ -12,6 +12,8 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 
+import { parseFrontmatter } from '@earendil-works/pi-coding-agent'
+
 export interface ParsedCommand {
   description: string
   argumentHint?: string
@@ -27,28 +29,109 @@ export interface DiscoveredCommand {
   filePath: string
 }
 
-/** Claude tool names are PascalCase; pi's are lowercase. */
-function normalizeToolName(name: string): string {
-  return name.trim().toLowerCase()
+/** Claude tool names are PascalCase and do not all exist in pi: `Glob` is pi's
+ * `find`. Lowercasing alone left `glob` in the list, and since pi has no tool by
+ * that name the grant was silently dropped when the list was intersected with the
+ * active tools. Shared with the subagent's own frontmatter parsing. */
+const CLAUDE_TOOL_MAP: Record<string, string> = {
+  read: 'read',
+  write: 'write',
+  edit: 'edit',
+  bash: 'bash',
+  grep: 'grep',
+  glob: 'find',
+  ls: 'ls',
+  // Claude's names for the tools this package registers itself. Without these a
+  // perfectly ordinary `allowed-tools: WebFetch, WebSearch` matched no pi tool and
+  // the intersection left the turn with nothing.
+  webfetch: 'web_fetch',
+  websearch: 'web_search',
+  todowrite: 'todo',
+  todoread: 'todo',
+  task: 'subagent',
+  askuserquestion: 'question',
+  exitplanmode: 'plan_mode_complete',
 }
 
-function field(frontmatter: string, key: string): string {
-  const match = new RegExp(String.raw`^\s*${key}\s*:\s*(.+)$`, 'm').exec(frontmatter)
-  return match ? match[1].trim().replace(/^["']|["']$/g, '') : ''
+/**
+ * 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.
+ */
+export function normalizeToolName(name: string): string {
+  const lower = name.trim().toLowerCase()
+  const scope = lower.indexOf('(')
+  const base = (scope === -1 ? lower : lower.slice(0, scope)).trim()
+  return CLAUDE_TOOL_MAP[base] ?? base
 }
 
+/**
+ * Entries are comma-separated, except a comma inside an argument scope belongs to the
+ * scope: `Bash(cat, tail)` is one grant, not three. Splitting on every comma made the
+ * fragments between them top-level entries, so a command naming only `Bash` came away
+ * with pi's `edit` tool active.
+ *
+ * Scanned rather than matched with a regex: the pattern form is quadratic on an input
+ * of unclosed parens, and a command file comes from the repository.
+ */
+export function toolEntries(raw: string): string[] {
+  const entries: string[] = []
+  let current = ''
+  let depth = 0
+  for (const ch of raw) {
+    if (ch === '(') depth++
+    else if (ch === ')') depth = Math.max(0, depth - 1)
+    if (ch === ',' && depth === 0) {
+      entries.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  entries.push(current)
+  return entries.map((entry) => entry.trim()).filter(Boolean)
+}
+
+/**
+ * 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.
+ */
+export function parseToolList(raw: unknown): string[] | 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))]
+}
+
+/** YAML types a bare scalar, so a model named `3.5` arrives as a number, not a string. */
+const text = (value: unknown): string => {
+  if (typeof value === 'string') return value.trim()
+  return typeof value === 'number' || typeof value === 'boolean' ? String(value) : ''
+}
+
+/** 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))
+
 export function parseCommandFile(content: string): ParsedCommand {
-  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)
-  const frontmatter = match ? match[1] : ''
-  const body = (match ? content.slice(match[0].length) : content).trim()
-  const tools = field(frontmatter, 'allowed-tools')
+  // 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
+  // values), and a value this misreads is a restriction silently not applied.
+  const { frontmatter, body: raw } = parseFrontmatter(content)
+  const body = raw.trim()
   const firstLine = body.split('\n').find((line) => line.trim().length > 0) ?? ''
+  const disable = frontmatter['disable-model-invocation']
   return {
-    description: field(frontmatter, 'description') || firstLine.slice(0, 60),
-    argumentHint: field(frontmatter, 'argument-hint') || undefined,
-    allowedTools: tools ? tools.split(',').map(normalizeToolName).filter(Boolean) : undefined,
-    model: field(frontmatter, 'model') || undefined,
-    disableModelInvocation: field(frontmatter, 'disable-model-invocation') === 'true',
+    description: text(frontmatter.description) || firstLine.slice(0, 60),
+    argumentHint: hint(frontmatter['argument-hint']) || undefined,
+    allowedTools: parseToolList(frontmatter['allowed-tools']),
+    model: text(frontmatter.model) || undefined,
+    disableModelInvocation: disable === true || text(disable) === 'true',
     body,
   }
 }
@@ -128,12 +211,16 @@ const inRanges = (ranges: Array<[number, number]>, index: number): boolean => ra
 /** 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 {
-  const resolved = path.resolve(cwd, reference)
-  const root = path.resolve(cwd)
-  if (resolved !== root && !resolved.startsWith(root + path.sep)) return undefined
   try {
-    if (!fs.statSync(resolved).isFile()) return undefined
-    return fs.readFileSync(resolved, 'utf-8')
+    // 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
   }

package/extensions/internal/output-guard.ts

@@ -12,11 +12,22 @@
 
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from '@earendil-works/pi-coding-agent'
 
+/**
+ * Trim `text` to a byte budget. `String.slice` counts UTF-16 units, so slicing a CJK
+ * string by a byte budget keeps up to three times the bytes asked for; cutting the
+ * encoded buffer is exact. A character straddling the cut decodes to U+FFFD.
+ * Shorter input comes back whole and a negative budget yields nothing, so callers
+ * need no length check of their own.
+ */
+export function sliceBytes(text: string, maxBytes: number): string {
+  return Buffer.from(text, 'utf-8').subarray(0, Math.max(0, maxBytes)).toString('utf-8')
+}
+
 /** Trim `text` to pi's documented tool-output budget, noting what was dropped. */
 export function capForContext(text: string): string {
   const cut = truncateHead(text, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES })
   if (!cut.truncated) return text
-  const kept = cut.content || text.slice(0, DEFAULT_MAX_BYTES)
+  const kept = cut.content || sliceBytes(text, DEFAULT_MAX_BYTES)
   const capped = `${kept}\n\n[truncated: ${formatSize(cut.totalBytes)} total, ${cut.totalLines} lines]`
   // Just over the budget, the notice can cost more than the trim saves.
   return capped.length < text.length ? capped : text

package/extensions/internal/project-approval.ts

@@ -29,14 +29,33 @@ const CLAUDE_SHAPED = [
   path.join('.claude', 'hooks'),
   path.join('.claude', 'output-styles'),
   path.join('.claude', 'rules'),
+  path.join('.claude', 'skills'),
+  path.join('.claude', 'commands'),
   'CLAUDE.local.md',
   '.mcp.json',
   path.join('.pi', 'mcp.json'),
   path.join('.pi', 'agents'),
 ]
 
+/** Markers that end the upward walk, matching the subagent's own discovery bound. */
+const ROOT_MARKERS = ['.git', 'package.json']
+
+/** Claude-shaped config anywhere between `cwd` and the repository root.
+ *
+ * The walk matters: agent discovery already searches upward, so starting pi in a
+ * subdirectory of a repository whose `.claude/agents` sits at the root found those
+ * agents while a cwd-only check reported nothing to gate, and the short-circuit
+ * approved the project without ever asking. The bound is the repository root, so a
+ * directory outside any repository never inherits a parent's config. */
 export function hasClaudeShapedConfig(cwd: string): boolean {
-  return CLAUDE_SHAPED.some((entry) => fs.existsSync(path.join(cwd, entry)))
+  let currentDir = cwd
+  while (true) {
+    if (CLAUDE_SHAPED.some((entry) => fs.existsSync(path.join(currentDir, entry)))) return true
+    if (ROOT_MARKERS.some((marker) => fs.existsSync(path.join(currentDir, marker)))) return false
+    const parentDir = path.dirname(currentDir)
+    if (parentDir === currentDir) return false
+    currentDir = parentDir
+  }
 }
 
 export interface ApprovalContext {

package/extensions/mcp.ts

@@ -22,6 +22,7 @@ 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 { DEFAULT_MAX_BYTES } from '@earendil-works/pi-coding-agent'
 import { Client } from '@modelcontextprotocol/sdk/client/index.js'
 // SSE is deprecated in favour of Streamable HTTP, but the SDK notes servers still on
 // the old spec exist, so this stays as a fallback for the migration period.
@@ -32,7 +33,7 @@ import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/typ
 import { Type } from 'typebox'
 import { MCP_TOOLS_CHANNEL, type McpToolAlias } from './internal/mcp-alias.js'
 import { capForContext } from './internal/output-guard.js'
-import { isProjectApproved } from './internal/project-approval.js'
+import { isProjectApproved, isProjectApprovedSilently } from './internal/project-approval.js'
 
 const DEFAULT_CONNECT_TIMEOUT_MS = 10_000
 const DEFAULT_CALL_TIMEOUT_MS = 120_000
@@ -103,13 +104,18 @@ export interface ProjectServerPolicy {
   consentAll: boolean
 }
 
-/** Claude's per-server approvals for project .mcp.json servers. Consent-granting keys
- * (enabledMcpjsonServers, enableAllProjectMcpServers) count only from files the repo
- * does not control (user settings and settings.local.json), so a checked-in
- * settings.json cannot approve its own servers. disabledMcpjsonServers counts from
- * every file and wins over consent. Lists union across files: for denies the union is
- * the restrictive reading, and consent is the union of the user's own two files. */
-export function projectServerPolicy(cwd: string, home: string): ProjectServerPolicy {
+/** Claude's per-server approvals for project .mcp.json servers.
+ *
+ * Consent-granting keys (enabledMcpjsonServers, enableAllProjectMcpServers) count
+ * from the user's own settings always, and from the project's settings.local.json
+ * only once the project itself is approved. That file is gitignored by convention,
+ * not by enforcement: a repository can commit one, and honoring it unconditionally
+ * let a hostile repo self-approve a server whose `command` runs on connect, even
+ * after the user declined the trust prompt.
+ *
+ * disabledMcpjsonServers counts from every file, including the repo's own, and wins
+ * over consent: a repo may always restrict itself further, never less. */
+export function projectServerPolicy(cwd: string, home: string, projectApproved: boolean): ProjectServerPolicy {
   const read = (file: string): Record<string, unknown> => {
     try {
       return JSON.parse(fs.readFileSync(file, 'utf-8'))
@@ -122,7 +128,7 @@ export function projectServerPolicy(cwd: string, home: string): ProjectServerPol
   const projectSettings = read(path.join(cwd, '.claude', 'settings.json'))
   const localSettings = read(path.join(cwd, '.claude', 'settings.local.json'))
   const disabled = new Set([...names(userSettings.disabledMcpjsonServers), ...names(projectSettings.disabledMcpjsonServers), ...names(localSettings.disabledMcpjsonServers)])
-  const consentSources = [userSettings, localSettings]
+  const consentSources = projectApproved ? [userSettings, localSettings] : [userSettings]
   const consented = new Set(consentSources.flatMap((settings) => names(settings.enabledMcpjsonServers)))
   const consentAll = consentSources.some((settings) => settings.enableAllProjectMcpServers === true)
   return { disabled, consented, consentAll }
@@ -217,12 +223,14 @@ export type ToolContent = { type: 'text'; text: string } | { type: 'image'; data
 export function mapContent(content: McpContentBlock[] | undefined, structured?: unknown): ToolContent[] {
   // capForContext every text output, whatever its source: a server can blow the tool-output
   // budget through a resource block, a JSON-stringified block, or the structured fallback,
-  // not only a text block.
+  // not only a text block. The per-block cap alone is not a budget, though: a server
+  // answering with one block per file multiplies it by the block count, so the blocks
+  // are capped again as a whole below.
   const text = (value: string): ToolContent => ({ type: 'text', text: capForContext(value) })
   if (!content || content.length === 0) {
     return [text(structured !== undefined ? JSON.stringify(structured, null, 2) : '(empty result)')]
   }
-  return content.map((block) => {
+  const mapped: ToolContent[] = content.map((block): ToolContent => {
     if (block.type === 'text') {
       return text(block.text ?? '')
     }
@@ -234,6 +242,50 @@ export function mapContent(content: McpContentBlock[] | undefined, structured?:
     }
     return text(JSON.stringify(block))
   })
+  return capTotal(mapped)
+}
+
+/**
+ * Bound a result's text as a whole, not each block. The per-block cap multiplies by
+ * the block count, so a server answering with one block per file still injects
+ * megabytes.
+ *
+ * Blocks are kept whole. Each has already been capped on its own, so keeping the one
+ * that crosses the budget bounds the text at roughly a single cap rather than at the
+ * block count times it, and it preserves that block's own truncation notice, which
+ * states how much of it was dropped. Blocks after it are omitted rather than skipped
+ * over, so what reaches the model is a prefix of what the server sent, and the number
+ * omitted is stated so a truncated set is distinguishable from a complete one.
+ *
+ * Images pass through uncut and do not spend the budget: base64 cut short is a broken
+ * image rather than a smaller one, so nothing here can bound them, and charging the
+ * budget for one would only delete the caption that accompanies a screenshot.
+ */
+export function capTotal(blocks: ToolContent[]): ToolContent[] {
+  const kept: ToolContent[] = []
+  let spent = 0
+  let full = false
+  let dropped = 0
+  for (const block of blocks) {
+    if (block.type !== 'text') {
+      kept.push(block)
+      continue
+    }
+    const size = Buffer.byteLength(block.text, 'utf-8')
+    // The first text block always goes through: a lone oversized one is better read
+    // truncated, with its own notice, than replaced by a marker saying it existed.
+    if (full || (spent > 0 && spent + size > DEFAULT_MAX_BYTES)) {
+      full = true
+      dropped++
+      continue
+    }
+    kept.push(block)
+    spent += size
+  }
+  if (dropped > 0) {
+    kept.push({ type: 'text', text: `[${dropped} further content block${dropped === 1 ? '' : 's'} omitted: tool output budget spent]` })
+  }
+  return kept
 }
 
 function isStdio(config: ServerConfig): config is StdioServerConfig {
@@ -374,7 +426,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
           if (result.isError) {
             details.error = 'tool_error'
             const hint = JSON.stringify(normalizeSchema(tool.inputSchema))
-            content.push({ type: 'text', text: `Tool reported an error. Expected input schema: ${hint}` })
+            content.push({ type: 'text', text: capForContext(`Tool reported an error. Expected input schema: ${hint}`) })
           }
           return { content, details }
         },
@@ -406,6 +458,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
   }
 
   async function connectServers(servers: Record<string, ServerConfig>): Promise<void> {
+    const pending: [string, ServerConfig][] = []
     for (const [name, config] of Object.entries(servers)) {
       // A later scope must not take the name of a server that already connected: it
       // would evict that client from the map, leaking it at shutdown, and misreport
@@ -414,24 +467,34 @@ export default async function mcpExtension(pi: ExtensionAPI) {
         console.warn(`pi-code-mcp: skipping duplicate server name ${name}`)
         continue
       }
-      warnOnTypelessUrl(name, config)
-      try {
-        const client = await connect(name, config)
-        clients.set(name, client)
-        const tools = await withTimeout(listAllTools(client), connectTimeoutMs(), `list tools ${name}`)
-        const count = registerTools(name, config, client, tools)
-        subscribeToToolChanges(name, config, client)
-        status.set(name, { state: 'connected', tools: count })
-      } catch (error) {
-        status.set(name, { state: `failed: ${error instanceof Error ? error.message : String(error)}`, tools: 0 })
-      }
+      // Seed in config order before connecting: parallel connects settle in completion
+      // order, and /mcp plus the session summary iterate the map's insertion order.
+      status.set(name, { state: 'connecting', tools: 0 })
+      pending.push([name, config])
     }
+    await Promise.all(
+      pending.map(async ([name, config]) => {
+        warnOnTypelessUrl(name, config)
+        try {
+          const client = await connect(name, config)
+          clients.set(name, client)
+          const tools = await withTimeout(listAllTools(client), connectTimeoutMs(), `list tools ${name}`)
+          const count = registerTools(name, config, client, tools)
+          subscribeToToolChanges(name, config, client)
+          status.set(name, { state: 'connected', tools: count })
+        } catch (error) {
+          status.set(name, { state: `failed: ${error instanceof Error ? error.message : String(error)}`, tools: 0 })
+        }
+      }),
+    )
   }
 
   /** Connect the project scope under the per-server policy. Returns whether the scope
    * is settled, so a refused confirm can be retried on a later session start. */
   async function connectProjectScope(ctx: ExtensionContext): Promise<boolean> {
-    const policy = projectServerPolicy(ctx.cwd, os.homedir())
+    // The stored decision, read without prompting: consent recorded inside the
+    // project only counts once the project itself has been approved.
+    const policy = projectServerPolicy(ctx.cwd, os.homedir(), isProjectApprovedSilently(ctx))
     const { consented, gated } = splitByPolicy(loadConfigFrom(projectConfigPaths(ctx.cwd)), policy)
     if (Object.keys(consented).length > 0) await connectServers(consented)
     if (Object.keys(gated).length === 0) return true

package/extensions/plan-mode/README.md

@@ -4,9 +4,9 @@ Read-only exploration mode for safe code analysis.
 
 ## Features
 
-- **Read-only tools**: Restricts available tools to read, bash, grep, find, ls, question
+- **Read-only tools**: Restricts available tools to read, bash, grep, find, ls, question, and `plan_mode_complete`
 - **Bash allowlist**: Only read-only bash commands are allowed
-- **Plan extraction**: Extracts numbered steps from `Plan:` sections
+- **Plan extraction**: Takes the plan from the `plan_mode_complete` tool call, falling back to numbered steps under a `Plan:` header when the model writes prose instead
 - **Progress tracking**: Widget shows completion status during execution
 - **[DONE:n] markers**: Explicit step completion tracking
 - **Session persistence**: State survives session resume
@@ -21,7 +21,7 @@ Read-only exploration mode for safe code analysis.
 
 1. Enable plan mode with `/plan` or `--plan` flag
 2. Ask the agent to analyze code and create a plan
-3. The agent should output a numbered plan under a `Plan:` header:
+3. The agent calls `plan_mode_complete` with the finished plan. If it writes prose instead, a numbered plan under a `Plan:` header is still picked up:
 
 ```
 Plan:

package/extensions/plan-mode/index.ts

@@ -132,6 +132,11 @@ export default function planModeExtension(pi: ExtensionAPI): void {
       enabled: planModeEnabled,
       todos: todoItems,
       executing: executionMode,
+      // The pre-plan tool set has to survive with the state that caused it to shrink.
+      // /reload rebuilds this extension with an empty snapshot while pi carries the
+      // restricted tools into the new runtime, so a restore has no way to work out
+      // what was active before plan mode unless it was written down here.
+      savedTools,
     })
   }
 
@@ -379,7 +384,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
     const entries = ctx.sessionManager.getEntries()
 
     // Restore persisted state
-    const planModeEntry = findLast(entries, (e: { type: string; customType?: string }) => e.type === 'custom' && e.customType === 'plan-mode') as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean } } | undefined
+    const planModeEntry = findLast(entries, (e: { type: string; customType?: string }) => e.type === 'custom' && e.customType === 'plan-mode') as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean; savedTools?: string[] } } | undefined
 
     if (planModeEntry?.data) {
       planModeEnabled = planModeEntry.data.enabled ?? planModeEnabled
@@ -396,7 +401,23 @@ After completing a step, include a [DONE:n] tag in your response.`,
     }
 
     if (planModeEnabled) {
-      enterPlanTools()
+      // Restoring into plan mode is the only case the recorded snapshot is for.
+      // Re-reading the active set here would capture the restriction pi carried
+      // across /reload and cost the session edit and write for good; applying the
+      // snapshot when plan mode is off would instead push a stale set over whatever
+      // pi has registered since, so it stays scoped to this branch.
+      savedTools = planModeEntry?.data?.savedTools ?? pi.getActiveTools()
+      pi.setActiveTools(PLAN_MODE_TOOLS.filter((t) => savedTools.includes(t)))
+      // --plan enters plan mode without ever toggling, so nothing has persisted yet
+      // and a /reload would find no snapshot to restore from. Record it now, while
+      // the active set still says what was there before the restriction.
+      //
+      // Only with no entry at all: an entry written before this field existed means
+      // the active set has already been through a restore and may be the restriction
+      // itself. Those tools are lost for this process either way, but persisting a
+      // guess would write the loss into the session file, where a later resume would
+      // inherit it instead of starting over.
+      if (!planModeEntry) persistState()
     } else {
       // A prior session in this instance may have shrunk the tool set; undo that when
       // the restored/fresh state is not plan mode.

package/extensions/status-line.ts

@@ -83,6 +83,7 @@ export default function statusLine(pi: ExtensionAPI) {
   let sessionCtx: ExtensionContext | undefined
   let commandLine: string | undefined
   let permissionMode = 'default'
+  let projectApproved = false
   let refreshTimer: ReturnType<typeof setInterval> | undefined
   let debounceTimer: ReturnType<typeof setTimeout> | undefined
   let running = false
@@ -103,7 +104,9 @@ export default function statusLine(pi: ExtensionAPI) {
   /** The stdin payload per Claude's documented statusline contract. */
   function buildPayload(ctx: ExtensionContext): Record<string, unknown> {
     const usage = ctx.getContextUsage() ?? { tokens: null, contextWindow: 0, percent: null }
-    const styleName = readActiveStyleName(settingsFiles(ctx.cwd, os.homedir(), true))
+    // Same gate as the config read above: an unapproved project's style is not applied,
+    // so reporting it here would describe a style the session is not using.
+    const styleName = readActiveStyleName(settingsFiles(ctx.cwd, os.homedir(), projectApproved))
     const payload: Record<string, unknown> = {
       session_id: ctx.sessionManager.getSessionId(),
       cwd: ctx.cwd,
@@ -128,11 +131,17 @@ export default function statusLine(pi: ExtensionAPI) {
     }
     running = true
     try {
+      // Everything below can touch ctx after an await, and every ctx getter throws
+      // once the session is disposed. This promise is started from a timer with no
+      // awaiter, so an escaping rejection becomes an uncaughtException and exits pi.
       const result = await runHookCommand(config.command, buildPayload(ctx), COMMAND_TIMEOUT_MS)
       const first = result.stdout.split('\n')[0].trimEnd()
       const pad = ' '.repeat(config.padding)
       commandLine = first ? `${pad}${first}${pad}` : undefined
       show(ctx, segmentText(ctx, ctx.ui.theme.fg('dim', '○')))
+    } catch {
+      // A replaced or reloaded session invalidates ctx while the command is in
+      // flight; there is nothing left to update, and the next session starts fresh.
     } finally {
       running = false
       if (rerunQueued) {
@@ -168,6 +177,7 @@ export default function statusLine(pi: ExtensionAPI) {
     // approval at session start, and a second prompt stacks over the first and eats
     // the keys meant for it. An undecided project simply skips project settings.
     const trusted = isProjectApprovedSilently(ctx)
+    projectApproved = trusted
     config = readStatusLineConfig(hookFiles(ctx.cwd, os.homedir(), trusted))
     if (config?.refreshInterval) {
       refreshTimer = setInterval(() => scheduleRefresh(), config.refreshInterval * 1000)

package/extensions/subagent/README.md

@@ -41,7 +41,7 @@ This tool executes a separate `pi` subprocess with a delegated system prompt and
 
 To enable project-local agents (`.claude/agents`, `.pi/agents`), pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
 
-When running interactively, the tool prompts for confirmation before running project-local agents. Set `confirmProjectAgents: false` to disable.
+When running interactively, the tool prompts for confirmation before running project-local agents. `confirmProjectAgents: false` skips that prompt for a project you have already approved; an unapproved project is still asked about.
 
 ## Usage
 

package/extensions/subagent/agents.ts

@@ -5,23 +5,12 @@
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import { getAgentDir, parseFrontmatter } from '@earendil-works/pi-coding-agent'
-
-// Claude Code tool names -> pi tool names; unmapped names pass through lowercased
-const CLAUDE_TOOL_MAP: Record<string, string> = {
-  read: 'read',
-  write: 'write',
-  edit: 'edit',
-  bash: 'bash',
-  grep: 'grep',
-  glob: 'find',
-  ls: 'ls',
-}
+import { getAgentDir, parseFrontmatter, stripFrontmatter } from '@earendil-works/pi-coding-agent'
 
-function normalizeToolName(tool: string): string {
-  const lower = tool.toLowerCase()
-  return CLAUDE_TOOL_MAP[lower] ?? lower
-}
+// The same mapping a command's `allowed-tools` gets: an agent's `tools:` is the same
+// Claude field, and `--tools` is an exact-name allowlist, so a name pi has no tool for
+// is not merely ignored, it narrows the child's registry.
+import { parseToolList } from '../internal/command-file.js'
 
 /**
  * `tools:` may be a comma-separated string (the Claude Code format) or a YAML block
@@ -30,12 +19,12 @@ function normalizeToolName(tool: string): string {
  */
 function parseToolsField(raw: unknown): string[] | undefined | null {
   if (raw === undefined) return undefined
-  let items: unknown[]
-  if (Array.isArray(raw)) items = raw
-  else if (typeof raw === 'string') items = raw.split(',')
-  else return null
-  if (items.some((item) => typeof item !== 'string')) return null
-  const tools = (items as string[]).map((item) => normalizeToolName(item.trim())).filter(Boolean)
+  // Shares the command parser's splitting, so a comma inside an argument scope stays
+  // inside it here too: `Bash(mv, write, cp)` used to hand the child pi's real `write`.
+  if (raw !== null && !Array.isArray(raw) && typeof raw !== 'string') return null
+  if (Array.isArray(raw) && raw.some((item) => typeof item !== 'string')) return null
+  const tools = parseToolList(raw)
+  if (!tools) return null
   return tools.length > 0 ? tools : undefined
 }
 
@@ -110,21 +99,31 @@ export function withPreloadedSkills(prompt: string, skills: string[] | undefined
  * prompt sent to the model, so a traversal would be an arbitrary-file read. */
 const SKILL_NAME = /^[A-Za-z0-9_.-]+$/
 
+/** Read one candidate file, but only if it really sits under `root` once symlinks
+ * are resolved. Both sides are canonicalised: on macOS /var is itself a symlink, so
+ * comparing a resolved path against an unresolved root rejects every valid read. */
+function readConfined(candidate: string, root: string): string | undefined {
+  try {
+    const real = fs.realpathSync(candidate)
+    if (real !== root && !real.startsWith(root + path.sep)) return undefined
+    return stripFrontmatter(fs.readFileSync(real, 'utf-8'))
+  } catch {
+    return undefined
+  }
+}
+
 function readSkillBody(name: string, skillDirs: string[]): string | undefined {
   if (!SKILL_NAME.test(name) || name === '.' || name === '..') return undefined
   for (const dir of skillDirs) {
-    const root = path.resolve(dir)
+    let root: string
+    try {
+      root = fs.realpathSync(dir)
+    } catch {
+      continue // a skills directory that does not exist simply contributes nothing
+    }
     for (const candidate of [path.join(dir, name, 'SKILL.md'), path.join(dir, `${name}.md`)]) {
-      // Belt and braces against symlinks and platform path quirks: the file actually
-      // read must still sit under the skills directory it was resolved from.
-      if (!path.resolve(candidate).startsWith(root + path.sep)) continue
-      try {
-        const content = fs.readFileSync(candidate, 'utf-8')
-        const match = /^---\r?\n[\s\S]*?\r?\n---/.exec(content)
-        return match ? content.slice(match[0].length) : content
-      } catch {
-        // try the next shape
-      }
+      const body = readConfined(candidate, root)
+      if (body !== undefined) return body
     }
   }
   return undefined

package/extensions/subagent/background.ts

@@ -7,6 +7,9 @@
 
 import { spawn } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
 
 export interface BackgroundRun {
   id: string
@@ -28,6 +31,10 @@ export interface BackgroundSpawn {
   command: string
   args: string[]
   cwd: string
+  /** The --append-system-prompt body, kept so a resume can rebuild the file the
+   * completing run deleted. Without it the resumed child is handed a path that no
+   * longer exists, and pi falls back to using that path as the prompt text. */
+  promptBody?: string
 }
 
 const runs = new Map<string, BackgroundRun>()
@@ -97,7 +104,7 @@ export function resumeBackgroundRun(id: string, task: string, onComplete: (run:
   const run = runs.get(id)
   if (!run) return 'unknown'
   if (run.state === 'running') return 'still-running'
-  const args = run.spawn.args.map((arg) => (arg.startsWith('Task: ') ? `Task: ${task}` : arg))
+  const args = withRebuiltPrompt(run.spawn).map((arg) => (arg.startsWith('Task: ') ? `Task: ${task}` : arg))
   run.state = 'running'
   run.task = task
   run.output = undefined
@@ -106,6 +113,26 @@ export function resumeBackgroundRun(id: string, task: string, onComplete: (run:
   return 'resumed'
 }
 
+/** Re-point --append-system-prompt at a fresh file when the original is gone. */
+function withRebuiltPrompt(spawnSpec: BackgroundSpawn): string[] {
+  const flag = spawnSpec.args.indexOf('--append-system-prompt')
+  if (flag === -1 || !spawnSpec.promptBody) return spawnSpec.args
+  const current = spawnSpec.args[flag + 1]
+  if (current && fs.existsSync(current)) return spawnSpec.args
+  try {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-subagent-'))
+    const file = path.join(dir, 'prompt.md')
+    fs.writeFileSync(file, spawnSpec.promptBody, { mode: 0o600 })
+    const rebuilt = [...spawnSpec.args]
+    rebuilt[flag + 1] = file
+    return rebuilt
+  } catch {
+    // Cannot rewrite it: drop the pair rather than hand pi a path it will treat as
+    // prompt text, which would replace the agent persona with a temp path.
+    return spawnSpec.args.filter((_arg, i) => i !== flag && i !== flag + 1)
+  }
+}
+
 export function startBackgroundRun(agent: string, task: string, invocation: BackgroundSpawn, onComplete: (run: BackgroundRun) => void): string | null {
   // Checked here, synchronously with registration: callers await temp-file writes
   // between any check of their own and this call, so a parallel tool-call batch
@@ -148,11 +175,25 @@ function driveRun(run: BackgroundRun, invocation: BackgroundSpawn, onComplete: (
   const complete = (): void => {
     if (completed) return
     completed = true
-    onComplete(run)
+    // A run outlives the session that started it, and pi's loader wires assertActive()
+    // into every runtime call, so notifying a disposed session throws. This fires from
+    // the child's 'close'/'error' listener, where nothing upstream catches: an escaping
+    // error reaches Node as an uncaughtException and takes pi down with it. The run
+    // state is already recorded by this point, so there is nothing to do but drop the
+    // notification for a session that is no longer there to receive it.
+    try {
+      onComplete(run)
+    } catch {
+      // the session that asked for this run is gone
+    }
   }
   proc.stdout.on('data', (data) => {
     stdout += data.toString()
   })
+  // An 'error' on a stream with no listener is rethrown by EventEmitter, and this one
+  // belongs to a detached child, so a pipe read failure would exit pi the same way an
+  // unguarded completion would. The foreground runner guards its streams the same way.
+  proc.stdout.on('error', () => {})
   proc.on('close', (code) => {
     const { text, turns } = parseFinalOutputFromJsonl(stdout)
     run.kill = undefined

package/extensions/subagent/index.ts

@@ -626,8 +626,11 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
   }
   args.push(`Task: ${task}`)
   const invocation = getPiInvocation(args)
-  const id = startBackgroundRun(agent.name, task, { command: invocation.command, args: invocation.args, cwd: params.cwd ?? defaultCwd }, (run) => {
+  const id = startBackgroundRun(agent.name, task, { command: invocation.command, args: invocation.args, cwd: params.cwd ?? defaultCwd, promptBody: tmpPrompt ? promptWithSkills : undefined }, (run) => {
     removeTmpPrompt(tmpPrompt)
+    // Both calls throw once the session that started the run is disposed; driveRun
+    // catches for the whole callback, so neither can escape into the child's close
+    // listener and become an uncaughtException.
     pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id })
     pi.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
   })
@@ -749,6 +752,10 @@ async function runParallelMode(tasks: TaskItemParam[], mode: ModeContext): Promi
       cwd: t.cwd,
       signal,
       onPhase: mode.onPhase,
+      // Same context single and chain mode pass: without these, an agent's skills
+      // preload and its model tier alias silently do nothing in parallel mode only.
+      skillRoots: mode.skillRoots,
+      availableModels: mode.availableModels,
       // Per-task update callback
       onUpdate: (partial) => {
         const live = partial.details?.results[0]
@@ -1102,6 +1109,7 @@ function renderParallelResult(results: SingleResult[], expanded: boolean, theme:
 
 export default function subagentExtension(pi: ExtensionAPI) {
   const notifyBackgroundCompletion = (run: { id: string; agent: string; state: string; turns: number; output?: string }): void => {
+    // Runs through driveRun's guard, same as the background-mode callback above.
     pi.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
   }
 

package/extensions/todo.ts

@@ -335,8 +335,11 @@ export default function todoExtension(pi: ExtensionAPI) {
       const msg = entry.message
       if (msg.role !== 'toolResult' || msg.toolName !== TOOL_NAME) continue
 
-      const details = msg.details as (Omit<TodoDetails, 'todos'> & { todos: LegacyTodo[] }) | undefined
-      if (details) {
+      const details = msg.details as (Omit<TodoDetails, 'todos'> & { todos?: LegacyTodo[] }) | undefined
+      // pi persists a failed tool call as `details: {}`, which is truthy: a rejected
+      // or blocked call would otherwise throw here and break replay for the rest of
+      // the session, losing the list on every resume, fork and compaction.
+      if (Array.isArray(details?.todos)) {
         replayTodos = details.todos.map(normalizeTodo)
         replayNextId = details.nextId
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Claude Code experience for the pi coding agent: reads your .claude config (rules, commands, skills, hooks, output styles, MCP servers, agents) and adds todo, checkpoints, memory, web, and subagents",
   "keywords": [
     "pi",