pi-code 0.2.4 → 0.3.0

package/README.md

@@ -37,16 +37,16 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 |---|---|---|
 | Global + project rules | `~/.claude/rules`, `.claude/rules` (+ `paths:` frontmatter scoping) | `claude-rules.ts` |
 | Custom slash commands | `.claude/commands/*.md` → pi prompt templates | `commands.ts` |
-| Skills | `.claude/skills` → pi skill discovery | `skills.ts` |
+| Skills | `.claude/skills` → pi skill discovery (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.ts` |
 | Hooks | `.claude/settings.json` hooks on pi lifecycle events | `hooks.ts` |
 | Output styles | `.claude/output-styles` + active `outputStyle`, `/output-style` switcher | `output-styles.ts` |
-| CLAUDE.md `@imports` | resolves `@path` imports pi's native loader skips | `context-imports.ts` |
+| CLAUDE.md `@imports` | resolves `@path` imports pi's native loader skips; loads `CLAUDE.local.md` (approval-gated) | `context-imports.ts` |
 | MCP servers | user `~/.claude.json`, `~/.pi/agent/mcp.json` (loaded on session start); project `.mcp.json`, `.pi/mcp.json` (only once the project is approved); stdio, HTTP, SSE | `mcp.ts` |
-| Project trust | prompts before loading project config (MCP servers, hooks, agents) that pi would otherwise trust silently | `project-approval.ts` |
+| Project trust | prompts before loading project config (MCP servers, hooks, agents, rules, output styles) that pi would otherwise trust silently | `internal/project-approval.ts` |
 | Subagents / Task | `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents`; background runs | `subagent/` |
 | Plan mode | `plan_mode_complete` tool, exact tool snapshot/restore | `plan-mode/` |
 | Todo list | persistent overlay, status machine, compaction-safe | `todo.ts` |
-| Checkpoints / rewind | shadow-repo snapshots, hard-reset restore | `git-checkpoint.ts` |
+| Checkpoints / rewind | shadow-repo snapshots; restore overwrites checkpointed files, keeps files created later | `git-checkpoint.ts` |
 | Persistent memory | per-project memories, index injected each session | `memory.ts` |
 | WebSearch / WebFetch | key-free DuckDuckGo search, SSRF-guarded fetch | `web.ts` |
 | AskUserQuestion | vendored example | `question.ts` |
@@ -55,7 +55,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.
 
-`output-guard.ts` and `web-transport.ts` are shared internals (context-budget truncation, DNS-pinned fetch) with no feature of their own; the tools above use them.
+`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.
 
 Vendored bases (`question`, `notify`, `status-line`) come from pi's MIT example extensions (see [LICENSE](LICENSE)).
 
@@ -64,7 +64,8 @@ Vendored bases (`question`, `notify`, `status-line`) come from pi's MIT example
 ```bash
 npm install
 npm run check           # biome + strict tsc + vitest, the whole gate
-scripts/e2e.sh          # drives the real pi TUI via tmux (needs a working model)
+scripts/e2e.sh          # quick smoke of the real pi TUI via tmux (needs a working model)
+scripts/e2e-full.sh     # every README feature end to end, model turns included (5-15 min)
 scripts/record-demos.sh # re-records demos/*.tape with vhs at low thinking
 ```
 

package/extensions/claude-rules.ts

@@ -2,13 +2,14 @@
  * Claude Rules Extension
  *
  * Replicates Claude Code's rules loading:
- * - Global rules (~/.claude/rules/*.md) are inlined in full into the system prompt.
- * - Project rules (.claude/rules/*.md) are listed as pointers the agent can read on demand.
+ * - Unscoped global rules (~/.claude/rules/*.md) are inlined in full into the system prompt.
+ * - Path-scoped global rules and all project rules (.claude/rules/*.md) are listed as
+ *   pointers the agent reads on demand.
  *
  * Path-scoped rules: a rule file may declare `paths:` frontmatter (a glob or
- * list of globs). Project-rule pointers surface that scope so the agent knows
- * to read the rule when working on matching files. Frontmatter is stripped
- * from inlined global rules.
+ * list of globs). Pointers surface that scope so the agent knows to read the
+ * rule when working on matching files. Frontmatter is stripped from inlined
+ * global rules.
  *
  * Adapted from the pi v0.74.2 claude-rules example.
  */
@@ -18,6 +19,8 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { isProjectApproved } from './internal/project-approval.js'
+
 export interface Frontmatter {
   paths: string[]
   body: string
@@ -61,39 +64,82 @@ export function parseFrontmatter(content: string): Frontmatter {
   return { paths: parsePaths(match[1]), body: content.slice(match[0].length) }
 }
 
-/** A project-rule pointer line, annotated with its path scope when present. */
-export function formatRulePointer(rel: string, paths: string[]): string {
-  const ref = `- .claude/rules/${rel}`
+/** A rule pointer line, annotated with its path scope when present. */
+export function formatRulePointer(rel: string, paths: string[], base = '.claude/rules'): string {
+  const ref = `- ${base}/${rel}`
   return paths.length > 0 ? `${ref} — applies when working on: ${paths.join(', ')}` : ref
 }
 
-/** Recursively find all .md files in a directory. */
-function findMarkdownFiles(dir: string, basePath = ''): string[] {
-  if (!fs.existsSync(dir)) return []
+/** A dirent's kind with symlinks resolved; nulls a dangling link. */
+function classifyEntry(entry: fs.Dirent, fullPath: string): { isDir: boolean; isFile: boolean } | null {
+  if (!entry.isSymbolicLink()) return { isDir: entry.isDirectory(), isFile: entry.isFile() }
+  try {
+    const stat = fs.statSync(fullPath)
+    return { isDir: stat.isDirectory(), isFile: stat.isFile() }
+  } catch {
+    return null
+  }
+}
+
+/** Recursively find all .md files, following symlinks (Claude Code documents symlinked
+ * shared rule dirs); `visited` realpaths keep a circular link from recursing forever. */
+function findMarkdownFiles(dir: string, basePath = '', visited = new Set<string>()): string[] {
   const results: string[] = []
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+  try {
+    const real = fs.realpathSync(dir)
+    if (visited.has(real)) return results
+    visited.add(real)
+  } catch {
+    return results
+  }
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return results // a missing or unreadable directory must not take down session start
+  }
+  for (const entry of entries) {
     const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name
-    if (entry.isDirectory()) {
-      results.push(...findMarkdownFiles(path.join(dir, entry.name), relativePath))
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+    const fullPath = path.join(dir, entry.name)
+    const kind = classifyEntry(entry, fullPath)
+    if (!kind) continue
+    if (kind.isDir) {
+      results.push(...findMarkdownFiles(fullPath, relativePath, visited))
+    } else if (kind.isFile && entry.name.endsWith('.md')) {
       results.push(relativePath)
     }
   }
   return results
 }
 
-function readGlobalRules(globalRulesDir: string): string {
-  return findMarkdownFiles(globalRulesDir)
-    .map((file) => parseFrontmatter(fs.readFileSync(path.join(globalRulesDir, file), 'utf-8')).body.trim())
-    .filter((content) => content.length > 0)
-    .join('\n\n')
-}
-
 interface ProjectRule {
   rel: string
   paths: string[]
 }
 
+interface GlobalRules {
+  inline: string
+  scoped: ProjectRule[]
+}
+
+/** Unscoped global rules are inlined; path-scoped ones keep their scope as pointers,
+ * mirroring Claude Code, where scoped rules attach only to matching files. */
+function readGlobalRules(globalRulesDir: string): GlobalRules {
+  const inline: string[] = []
+  const scoped: ProjectRule[] = []
+  for (const file of findMarkdownFiles(globalRulesDir)) {
+    let parsed: Frontmatter
+    try {
+      parsed = parseFrontmatter(fs.readFileSync(path.join(globalRulesDir, file), 'utf-8'))
+    } catch {
+      continue // one unreadable rule must not take down session start
+    }
+    if (parsed.paths.length > 0) scoped.push({ rel: file, paths: parsed.paths })
+    else if (parsed.body.trim().length > 0) inline.push(parsed.body.trim())
+  }
+  return { inline: inline.join('\n\n'), scoped }
+}
+
 function readProjectRules(projectRulesDir: string): ProjectRule[] {
   return findMarkdownFiles(projectRulesDir).map((rel) => {
     try {
@@ -106,26 +152,34 @@ function readProjectRules(projectRulesDir: string): ProjectRule[] {
 
 export default function claudeRulesExtension(pi: ExtensionAPI) {
   const globalRulesDir = path.join(os.homedir(), '.claude', 'rules')
-  let globalRules = ''
+  let globalRules: GlobalRules = { inline: '', scoped: [] }
   let projectRules: ProjectRule[] = []
 
   pi.on('session_start', async (_event, ctx) => {
     globalRules = readGlobalRules(globalRulesDir)
-    // Project rule filenames and their paths: frontmatter are surfaced in the system prompt,
-    // so read them only for a trusted project.
-    const trusted = ctx.isProjectTrusted?.() ?? false
-    projectRules = trusted ? readProjectRules(path.join(ctx.cwd, '.claude', 'rules')) : []
-
-    if (globalRules.length > 0 || projectRules.length > 0) {
-      ctx.ui.notify(`Rules loaded: global ${globalRules.length > 0 ? 'yes' : 'no'}, project ${projectRules.length}`, 'info')
+    // Project rule filenames and their paths: frontmatter are surfaced in the system prompt.
+    // isProjectTrusted alone is true for a repo pi never asked about; see project-approval.
+    const approved = await isProjectApproved(ctx)
+    projectRules = approved ? readProjectRules(path.join(ctx.cwd, '.claude', 'rules')) : []
+
+    const hasGlobal = globalRules.inline.length > 0 || globalRules.scoped.length > 0
+    if (hasGlobal || projectRules.length > 0) {
+      ctx.ui.notify(`Rules loaded: global ${hasGlobal ? 'yes' : 'no'}, project ${projectRules.length}`, 'info')
     }
   })
 
   pi.on('before_agent_start', async (event) => {
     let addition = ''
 
-    if (globalRules.length > 0) {
-      addition += `\n\n## Global Rules\n\nThese rules always apply:\n\n${globalRules}`
+    if (globalRules.inline.length > 0 || globalRules.scoped.length > 0) {
+      addition += `\n\n## Global Rules`
+      if (globalRules.inline.length > 0) {
+        addition += `\n\nThese rules always apply:\n\n${globalRules.inline}`
+      }
+      if (globalRules.scoped.length > 0) {
+        const scopedList = globalRules.scoped.map((rule) => formatRulePointer(rule.rel, rule.paths, '~/.claude/rules')).join('\n')
+        addition += `\n\nPath-scoped global rules, available in ~/.claude/rules/:\n\n${scopedList}\n\nRead the relevant rule file with the read tool before working on the files it covers.`
+      }
     }
 
     if (projectRules.length > 0) {

package/extensions/context-imports.ts

@@ -2,12 +2,13 @@
  * Context Imports Extension
  *
  * pi loads CLAUDE.md / AGENTS.md context files natively but does not resolve
- * Claude Code's `@path` imports inside them. This fills that one gap: on
- * before_agent_start it reads the already-loaded context files from
- * systemPromptOptions, resolves any `@path` imports (recursive, depth-capped,
- * cycle-safe, budget-capped; ~ expands to home, relative paths resolve against
- * the importing file), and appends ONLY the imported content. pi already
- * injected the base files, so nothing is duplicated.
+ * Claude Code's `@path` imports inside them, and skips CLAUDE.local.md
+ * entirely. This fills both gaps: on before_agent_start it reads the
+ * already-loaded context files from systemPromptOptions, resolves any `@path`
+ * imports (recursive, depth-capped, cycle-safe, budget-capped; ~ expands to
+ * home, relative paths resolve against the importing file), and appends the
+ * imported content plus the approval-gated CLAUDE.local.md body. The base
+ * files pi already injected are never re-appended.
  *
  * Security: context files can come from an untrusted project, so imports are
  * confined (after resolving symlinks) to the working directory and the user's
@@ -26,6 +27,8 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { isProjectApproved } from './internal/project-approval.js'
+
 const MAX_IMPORT_DEPTH = 5
 export const MAX_IMPORT_FILES = 50
 export const MAX_IMPORT_BYTES = 256 * 1024
@@ -70,17 +73,29 @@ export interface ImportBudget {
 
 export const createImportBudget = (): ImportBudget => ({ files: MAX_IMPORT_FILES, bytes: MAX_IMPORT_BYTES, dropped: 0 })
 
-/** The `@path` targets of a context file, in document order, skipping fenced code blocks. */
+function fenceMarker(lineStart: string): string | null {
+  if (lineStart.startsWith('```')) return '`'
+  if (lineStart.startsWith('~~~')) return '~'
+  return null
+}
+
+/** The `@path` targets of a context file, in document order. Claude Code evaluates
+ * imports neither in fenced code blocks (backtick or tilde) nor in inline spans. */
 function importTargets(content: string): string[] {
   const targets: string[] = []
-  let inFence = false
+  // A fence only closes with the character that opened it: a backtick-fenced
+  // example may legitimately contain tilde-fence lines, and vice versa.
+  let fence: string | null = null
   for (const line of content.split('\n')) {
-    if (line.trimStart().startsWith('```')) {
-      inFence = !inFence
+    const marker = fenceMarker(line.trimStart())
+    if (marker !== null && (fence === null || fence === marker)) {
+      fence = fence === null ? marker : null
       continue
     }
-    if (inFence) continue
-    for (const match of line.matchAll(/(^|\s)@(\S+)/g)) targets.push(match[2])
+    if (fence !== null) continue
+    // Backreference so a multi-backtick span (``literal `@x` backticks``) strips whole.
+    const withoutSpans = line.replace(/(`+)[^`]*?\1/g, '')
+    for (const match of withoutSpans.matchAll(/(^|\s)@(\S+)/g)) targets.push(match[2])
   }
   return targets
 }
@@ -146,8 +161,25 @@ export function rootsForImporter(importer: string, home: string, cwd: string): s
 }
 
 export default function contextImportsExtension(pi: ExtensionAPI) {
+  let localContext: { path: string; content: string } | null = null
+
+  pi.on('session_start', async (_event, ctx) => {
+    // CLAUDE.local.md is Claude Code's personal sidecar of CLAUDE.md; pi's own loader
+    // skips it. A cloned repo can ship one, so it is gated like other project config.
+    localContext = null
+    const candidate = path.join(ctx.cwd, 'CLAUDE.local.md')
+    if (!fs.existsSync(candidate)) return
+    if (!(await isProjectApproved(ctx))) return
+    try {
+      localContext = { path: candidate, content: fs.readFileSync(candidate, 'utf-8') }
+    } catch {
+      // unreadable: treat as absent
+    }
+  })
+
   pi.on('before_agent_start', async (event) => {
-    const contextFiles: Array<{ path: string; content: string }> = event.systemPromptOptions?.contextFiles ?? []
+    const contextFiles: Array<{ path: string; content: string }> = [...(event.systemPromptOptions?.contextFiles ?? [])]
+    if (localContext) contextFiles.push(localContext)
     if (contextFiles.length === 0) return
 
     const home = os.homedir()
@@ -164,10 +196,18 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
       const allowedRoots = rootsForImporter(file.path, home, cwd)
       imported.push(...collectImports(file.content, path.dirname(file.path), home, allowedRoots, seenSet, budget))
     }
-    if (imported.length === 0) return
 
-    const section = imported.map((entry) => `### ${entry.path}\n\n${entry.body}`).join('\n\n')
-    const notice = budget.dropped === 0 ? '' : `\n\n${budget.dropped} further @imports were skipped: the import budget (${MAX_IMPORT_FILES} files, ${MAX_IMPORT_BYTES} bytes) is spent.`
-    return { systemPrompt: `${event.systemPrompt}\n\n## Imported context (@)\n\n${section}${notice}` }
+    let addition = ''
+    if (localContext && localContext.content.trim().length > 0) {
+      addition += `\n\n## CLAUDE.local.md\n\n${localContext.content.trim()}`
+    }
+    if (imported.length > 0) {
+      const section = imported.map((entry) => `### ${entry.path}\n\n${entry.body}`).join('\n\n')
+      const notice = budget.dropped === 0 ? '' : `\n\n${budget.dropped} further @imports were skipped: the import budget (${MAX_IMPORT_FILES} files, ${MAX_IMPORT_BYTES} bytes) is spent.`
+      addition += `\n\n## Imported context (@)\n\n${section}${notice}`
+    }
+    if (addition.length === 0) return
+
+    return { systemPrompt: event.systemPrompt + addition }
   })
 }

package/extensions/hooks.ts

@@ -27,7 +27,7 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
-import { isProjectApproved } from './project-approval.js'
+import { isProjectApproved } from './internal/project-approval.js'
 
 const DEFAULT_TIMEOUT_S = 60
 
@@ -53,7 +53,7 @@ export interface HookRunResult {
   /** The hook was killed at its timeout, so its exit code carries no verdict. */
   timedOut: boolean
 }
-export type HookRunner = (command: string, payload: unknown, timeoutMs: number) => Promise<HookRunResult>
+export type HookRunner = (command: string, payload: unknown, timeoutMs: number, projectDir?: string) => Promise<HookRunResult>
 
 /** Settings files to read, newest-winning. Project files load only when trusted. */
 export function hookFiles(cwd: string, home: string, trusted: boolean): string[] {
@@ -87,11 +87,17 @@ function matcherApplies(matcher: string | undefined, name: string): boolean {
   }
 }
 
+/** Claude settings may carry prompt/agent hook types with no command; running one
+ * through `sh -c undefined` would throw out of the tool_call handler. */
+function isRunnableHook(hook: HookCommand): boolean {
+  return typeof hook.command === 'string' && (hook.type === undefined || hook.type === 'command')
+}
+
 /** Command specs whose matcher applies to the given tool/source name. */
 export function matchingCommands(matchers: HookMatcher[] | undefined, name: string): HookCommand[] {
   const result: HookCommand[] = []
   for (const entry of matchers ?? []) {
-    if (matcherApplies(entry.matcher, name)) result.push(...(entry.hooks ?? []))
+    if (matcherApplies(entry.matcher, name)) result.push(...(entry.hooks ?? []).filter(isRunnableHook))
   }
   return result
 }
@@ -137,12 +143,14 @@ function killTree(child: ChildProcess): void {
   child.kill('SIGKILL')
 }
 
-export const runHookCommand: HookRunner = (command, payload, timeoutMs) =>
+export const runHookCommand: HookRunner = (command, payload, timeoutMs, projectDir) =>
   new Promise((resolve) => {
     // Absolute path so the shell can't be resolved through an attacker-controlled PATH.
     // `detached` makes the shell its own process group leader so the timeout can kill
-    // the descendants too.
-    const child = spawn('/bin/sh', ['-c', command], { stdio: ['pipe', 'pipe', 'pipe'], detached: true })
+    // the descendants too. CLAUDE_PROJECT_DIR is Claude's documented way for a hook to
+    // reference project files regardless of the shell's cwd.
+    const env = projectDir ? { ...process.env, CLAUDE_PROJECT_DIR: projectDir } : process.env
+    const child = spawn('/bin/sh', ['-c', command], { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env })
     let stdout = ''
     let stderr = ''
     let settled = false
@@ -178,8 +186,15 @@ export const runHookCommand: HookRunner = (command, payload, timeoutMs) =>
     child.stdin?.end(JSON.stringify(payload))
   })
 
+/** Above 2^31-1 ms Node clamps a timer to 1ms, which would kill the hook instantly. */
+const MAX_TIMEOUT_S = 2_147_483
+
 function timeoutMs(command: HookCommand): number {
-  return (command.timeout ?? DEFAULT_TIMEOUT_S) * 1000
+  // Non-positive values fall back to the default: a 0ms timer would fire before the
+  // hook runs, and a timed-out PreToolUse hook fails closed, bricking the tool.
+  const declared = command.timeout
+  const seconds = typeof declared === 'number' && declared > 0 ? Math.min(declared, MAX_TIMEOUT_S) : DEFAULT_TIMEOUT_S
+  return seconds * 1000
 }
 
 /** Run PreToolUse hooks for a tool; the first blocking verdict wins. */
@@ -199,25 +214,45 @@ async function runNotifyHooks(commands: HookCommand[], payload: unknown, runner:
   await Promise.all(commands.map((command) => runner(command.command, payload, timeoutMs(command))))
 }
 
+/** Bound on remembered tool inputs, in case a blocked or aborted call never ends. */
+const MAX_PENDING_INPUTS = 100
+
 export default function hooksExtension(pi: ExtensionAPI) {
   let config: HooksConfig = {}
+  let projectDir = ''
+  // tool_execution_end does not carry the tool's input, but Claude's PostToolUse
+  // contract does, so remember it from tool_call keyed by the call id.
+  const pendingInputs = new Map<string, unknown>()
+  const runner: HookRunner = (command, payload, ms) => runHookCommand(command, payload, ms, projectDir)
 
   pi.on('session_start', async (event, ctx) => {
     const trusted = await isProjectApproved(ctx)
+    projectDir = ctx.cwd
     config = loadHooks(hookFiles(ctx.cwd, os.homedir(), trusted))
     // Only fire SessionStart hooks on a genuine session begin, matched by source (Claude uses
     // "startup"/"resume"/...). "reload" and "fork" re-fire in-process and would double-run hooks.
     if (event.reason === 'reload' || event.reason === 'fork') return
-    await runNotifyHooks(matchingCommands(config.SessionStart, event.reason), { hook_event_name: 'SessionStart', source: event.reason }, runHookCommand)
+    await runNotifyHooks(matchingCommands(config.SessionStart, event.reason), { hook_event_name: 'SessionStart', source: event.reason }, runner)
   })
 
   pi.on('tool_call', async (event) => {
-    const decision = await runPreToolUse(config, event.toolName, event.input, runHookCommand)
-    return decision.block ? { block: true, reason: decision.reason } : undefined
+    pendingInputs.set(event.toolCallId, event.input)
+    if (pendingInputs.size > MAX_PENDING_INPUTS) {
+      const oldest = pendingInputs.keys().next().value
+      if (oldest !== undefined) pendingInputs.delete(oldest)
+    }
+    const decision = await runPreToolUse(config, event.toolName, event.input, runner)
+    if (!decision.block) return undefined
+    // pi still emits tool_execution_end (isError) for a blocked call, which also
+    // cleans up; deleting here just avoids relying on that host detail.
+    pendingInputs.delete(event.toolCallId)
+    return { block: true, reason: decision.reason }
   })
 
   pi.on('tool_execution_end', async (event) => {
+    const toolInput = pendingInputs.get(event.toolCallId)
+    pendingInputs.delete(event.toolCallId)
     if (event.isError) return
-    await runNotifyHooks(matchingCommands(config.PostToolUse, event.toolName), { hook_event_name: 'PostToolUse', tool_name: event.toolName }, runHookCommand)
+    await runNotifyHooks(matchingCommands(config.PostToolUse, event.toolName), { hook_event_name: 'PostToolUse', tool_name: event.toolName, tool_input: toolInput, tool_response: event.result }, runner)
   })
 }

package/extensions/{project-approval.ts → internal/project-approval.ts}

@@ -22,7 +22,18 @@ import * as path from 'node:path'
 import { getAgentDir, hasTrustRequiringProjectResources, ProjectTrustStore } from '@earendil-works/pi-coding-agent'
 
 /** Project files pi-code acts on that pi's own trust check does not look for. */
-const CLAUDE_SHAPED = [path.join('.claude', 'settings.json'), path.join('.claude', 'settings.local.json'), path.join('.claude', 'agents'), path.join('.claude', 'hooks'), path.join('.claude', 'output-styles'), '.mcp.json', path.join('.pi', 'mcp.json'), path.join('.pi', 'agents')]
+const CLAUDE_SHAPED = [
+  path.join('.claude', 'settings.json'),
+  path.join('.claude', 'settings.local.json'),
+  path.join('.claude', 'agents'),
+  path.join('.claude', 'hooks'),
+  path.join('.claude', 'output-styles'),
+  path.join('.claude', 'rules'),
+  'CLAUDE.local.md',
+  '.mcp.json',
+  path.join('.pi', 'mcp.json'),
+  path.join('.pi', 'agents'),
+]
 
 export function hasClaudeShapedConfig(cwd: string): boolean {
   return CLAUDE_SHAPED.some((entry) => fs.existsSync(path.join(cwd, entry)))

package/extensions/mcp.ts

@@ -28,8 +28,8 @@ import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js' //
 import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
 import { Type } from 'typebox'
-import { capForContext } from './output-guard.js'
-import { isProjectApproved } from './project-approval.js'
+import { capForContext } from './internal/output-guard.js'
+import { isProjectApproved } from './internal/project-approval.js'
 
 const CONNECT_TIMEOUT_MS = 10_000
 const CALL_TIMEOUT_MS = 120_000
@@ -41,6 +41,7 @@ const CALL_TIMEOUT_MS = 120_000
 const RESERVED_NAMES = new Set(['web_fetch', 'web_search', 'plan_mode_complete'])
 
 export interface StdioServerConfig {
+  type?: 'stdio'
   command: string
   args?: string[]
   env?: Record<string, string>
@@ -48,6 +49,7 @@ export interface StdioServerConfig {
 }
 
 export interface HttpServerConfig {
+  type?: 'http' | 'streamable-http' | 'sse'
   url: string
   headers?: Record<string, string>
   bearerToken?: string
@@ -56,8 +58,14 @@ export interface HttpServerConfig {
 
 export type ServerConfig = StdioServerConfig | HttpServerConfig
 
+/** Claude's .mcp.json expansion: ${VAR}, and ${VAR:-default}. The syntax borrows
+ * shell's `:-`, which substitutes when the variable is unset OR empty. */
 export function interpolateEnv(value: string, env: NodeJS.ProcessEnv = process.env): string {
-  return value.replace(/\$\{(\w+)\}/g, (_, name) => env[name] ?? '')
+  return value.replace(/\$\{(\w+)(:-([^}]*))?\}/g, (_, name, hasDefault, fallback) => {
+    const current = env[name]
+    if (hasDefault !== undefined) return current || fallback
+    return current ?? ''
+  })
 }
 
 /** User-scoped MCP config (the user's own; safe to load without project trust). */
@@ -123,7 +131,8 @@ export function mapContent(content: McpContentBlock[] | undefined, structured?:
 }
 
 function isStdio(config: ServerConfig): config is StdioServerConfig {
-  return 'command' in config
+  // An explicit type wins; without one, a command field means stdio.
+  return 'command' in config && (config.type === undefined || config.type === 'stdio')
 }
 
 async function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
@@ -150,8 +159,8 @@ async function connect(name: string, config: ServerConfig): Promise<Client> {
     const env: Record<string, string> = { ...getDefaultEnvironment() }
     for (const [key, value] of Object.entries(config.env ?? {})) env[key] = interpolateEnv(value)
     const transport = new StdioClientTransport({
-      command: config.command,
-      args: config.args ?? [],
+      command: interpolateEnv(config.command),
+      args: (config.args ?? []).map((arg) => interpolateEnv(arg)),
       env,
       cwd: config.cwd?.replace(/^~(?=\/|$)/, os.homedir()),
       stderr: 'ignore',
@@ -164,12 +173,18 @@ async function connect(name: string, config: ServerConfig): Promise<Client> {
   const token = config.bearerToken ?? (config.bearerTokenEnv ? process.env[config.bearerTokenEnv] : undefined)
   if (token) headers.Authorization = `Bearer ${token}`
   const url = new URL(interpolateEnv(config.url))
+  if (config.type === 'sse') {
+    const transport = new SSEClientTransport(url, { requestInit: { headers } }) // NOSONAR: explicitly declared legacy transport
+    await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `connect ${name} (sse)`)
+    return client
+  }
   try {
     const transport = new StreamableHTTPClientTransport(url, { requestInit: { headers } })
     await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `connect ${name}`)
     return client
   } catch (error) {
-    if (String(error).includes('Unauthorized')) throw error
+    // An explicitly declared streamable transport must not silently degrade to SSE.
+    if (config.type !== undefined || String(error).includes('Unauthorized')) throw error
     const fallback = new Client({ name: 'pi-code-mcp', version: '0.1.0' })
     const transport = new SSEClientTransport(url, { requestInit: { headers } }) // NOSONAR: deliberate legacy fallback
     await withTimeout(fallback.connect(transport), CONNECT_TIMEOUT_MS, `connect ${name} (sse)`)
@@ -195,6 +210,13 @@ export default async function mcpExtension(pi: ExtensionAPI) {
 
   async function connectServers(servers: Record<string, ServerConfig>): Promise<void> {
     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
+      // the earlier server's status.
+      if (clients.has(name)) {
+        console.warn(`pi-code-mcp: skipping duplicate server name ${name}`)
+        continue
+      }
       try {
         const client = await connect(name, config)
         clients.set(name, client)

package/extensions/memory.ts

@@ -13,7 +13,7 @@ import * as path from 'node:path'
 import { StringEnum } from '@earendil-works/pi-ai'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
-import { capForContext } from './output-guard.js'
+import { capForContext } from './internal/output-guard.js'
 
 const INDEX_FILE = 'MEMORY.md'
 
@@ -35,17 +35,22 @@ export function slugifyName(name: string): string {
   )
 }
 
+/** The exact key prefix of a memory's index line; matching on a substring would also
+ * hit another entry whose description merely mentions this memory. */
+const entryPrefix = (name: string): string => `- [${name}](${name}.md):`
+
 /** Add or replace this memory's line in the index, keyed by its markdown link target. */
 export function upsertIndexLine(index: string, name: string, description: string): string {
-  const line = `- [${name}](${name}.md): ${description}`
-  const lines = index.split('\n').filter((l) => l.trim().length > 0 && !l.includes(`](${name}.md)`))
+  // One line per memory: a newline in the description would break line-based matching.
+  const line = `${entryPrefix(name)} ${description.replace(/\s+/g, ' ').trim()}`
+  const lines = index.split('\n').filter((l) => l.trim().length > 0 && !l.startsWith(entryPrefix(name)))
   if (lines.length === 0 || !lines[0].startsWith('#')) lines.unshift('# Memory index')
   lines.push(line)
   return `${lines.join('\n')}\n`
 }
 
 export function removeIndexLine(index: string, name: string): string {
-  const lines = index.split('\n').filter((l) => l.trim().length > 0 && !l.includes(`](${name}.md)`))
+  const lines = index.split('\n').filter((l) => l.trim().length > 0 && !l.startsWith(entryPrefix(name)))
   return lines.length > 0 ? `${lines.join('\n')}\n` : ''
 }
 

package/extensions/notify.ts

@@ -38,6 +38,8 @@ function notifyWindows(title: string, body: string): void {
 }
 
 function notify(title: string, body: string): void {
+  // Piped or headless stdout (pi -p, CI) must not receive raw escape bytes.
+  if (!process.stdout.isTTY) return
   if (process.env.WT_SESSION) {
     notifyWindows(title, body)
   } else if (process.env.KITTY_WINDOW_ID) {

package/extensions/output-styles.ts

@@ -19,6 +19,8 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { isProjectApproved } from './internal/project-approval.js'
+
 export interface OutputStyle {
   name: string
   description: string
@@ -69,7 +71,13 @@ export function loadStyles(dirs: string[]): OutputStyle[] {
     }
     for (const entry of entries) {
       if (!entry.endsWith('.md')) continue
-      const style = parseStyle(fs.readFileSync(path.join(dir, entry), 'utf-8'), entry.replace(/\.md$/, ''))
+      let content: string
+      try {
+        content = fs.readFileSync(path.join(dir, entry), 'utf-8')
+      } catch {
+        continue // a directory named *.md or an unreadable file must not take down session start
+      }
+      const style = parseStyle(content, entry.replace(/\.md$/, ''))
       byName.set(style.name, style)
     }
   }
@@ -121,8 +129,9 @@ export default function outputStylesExtension(pi: ExtensionAPI) {
   pi.on('session_start', async (_event, ctx) => {
     const home = os.homedir()
     // A project style body is injected verbatim into the system prompt, so only honor
-    // project styles / selection once the project is trusted.
-    const trusted = ctx.isProjectTrusted?.() ?? false
+    // project styles / selection once the project is approved. isProjectTrusted alone
+    // is true for a repo pi never asked about; see project-approval.
+    const trusted = await isProjectApproved(ctx)
     styles = loadStyles(styleDirs(ctx.cwd, home, trusted))
     localSettingsPath = path.join(ctx.cwd, '.claude', 'settings.local.json')
     activeName = readActiveStyleName(settingsFiles(ctx.cwd, home, trusted))

package/extensions/plan-mode/README.md

@@ -14,7 +14,7 @@ Read-only exploration mode for safe code analysis.
 ## Commands
 
 - `/plan` - Toggle plan mode
-- `/todos` - Show current plan progress
+- `/plan-todos` - Show current plan progress
 - `Ctrl+Alt+P` - Toggle plan mode (shortcut)
 
 ## Usage

package/extensions/plan-mode/index.ts

@@ -161,6 +161,9 @@ export default function planModeExtension(pi: ExtensionAPI): void {
       const execMessage = todoItems.length > 0 ? `Execute the plan. Start with: ${todoItems[0].text}` : 'Execute the plan you just created.'
       pi.sendMessage({ customType: 'plan-mode-execute', content: execMessage, display: true }, { triggerTurn: true })
     } else if (choice === 'Refine the plan') {
+      // The refined turn may answer in prose; without this reset agent_end would skip
+      // deriveTodosFromProse and re-display the superseded todo list.
+      planFromTool = false
       const refinement = await ctx.ui.editor('Refine the plan:', '')
       if (refinement?.trim()) {
         pi.sendUserMessage(refinement.trim())
@@ -240,6 +243,7 @@ export default function planModeExtension(pi: ExtensionAPI): void {
       messages: event.messages.filter((m) => {
         const msg = m as AgentMessage & { customType?: string }
         if (msg.customType === 'plan-mode-context') return false
+        if (msg.customType === 'plan-execution-context' && !executionMode) return false
         if (msg.role !== 'user') return true
 
         const content = msg.content

package/extensions/subagent/README.md

@@ -1,4 +1,4 @@
-# Subagent Example
+# Subagent Extension
 
 Delegate tasks to specialized subagents with isolated context windows.
 
@@ -7,6 +7,8 @@ Delegate tasks to specialized subagents with isolated context windows.
 - **Isolated context**: Each subagent runs in a separate `pi` process
 - **Streaming output**: See tool calls and progress as they happen
 - **Parallel streaming**: All parallel tasks stream updates simultaneously
+- **Background runs**: Fire-and-forget with a completion notification; max 8 running at once
+- **Bounded fan-out**: A subagent refuses to spawn subagents of its own (an env marker the tool honors: steering, not a sandbox)
 - **Markdown rendering**: Final output rendered with proper formatting (expanded view)
 - **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
 - **Abort support**: Ctrl+C propagates to kill subagent processes
@@ -18,6 +20,7 @@ subagent/
 ├── README.md            # This file
 ├── index.ts             # The extension (entry point)
 ├── agents.ts            # Agent discovery logic
+├── background.ts        # Background run registry and spawning
 ├── agents/              # Sample agent definitions
 │   ├── scout.md         # Fast recon, returns compressed context
 │   ├── planner.md       # Creates implementation plans
@@ -31,26 +34,7 @@ subagent/
 
 ## Installation
 
-From the repository root, symlink the files:
-
-```bash
-# Symlink the extension (must be in a subdirectory with index.ts)
-mkdir -p ~/.pi/agent/extensions/subagent
-ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.pi/agent/extensions/subagent/index.ts
-ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.pi/agent/extensions/subagent/agents.ts
-
-# Symlink agents
-mkdir -p ~/.pi/agent/agents
-for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do
-  ln -sf "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f")
-done
-
-# Symlink workflow prompts
-mkdir -p ~/.pi/agent/prompts
-for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do
-  ln -sf "$(pwd)/$f" ~/.pi/agent/prompts/$(basename "$f")
-done
-```
+Installed with pi-code (`pi install npm:pi-code`); nothing to set up separately.
 
 ## Security Model
 
@@ -58,9 +42,9 @@ This tool executes a separate `pi` subprocess with a delegated system prompt and
 
 **Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
 
-**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`.
+**Default behavior:** Only loads **user-level agents** from `~/.claude/agents` and `~/.pi/agent/agents`.
 
-To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
+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.
 
@@ -129,15 +113,25 @@ Agents are markdown files with YAML frontmatter:
 name: my-agent
 description: What this agent does
 tools: read, grep, find, ls
-model: claude-haiku-4-5
+disallowedTools: write, edit
+model: gpt-oss:20b
+effort: high
 ---
 
 System prompt for the agent goes here.
 ```
 
+Claude Code fields map onto pi where a sensible seam exists: `tools` and
+`disallowedTools` (comma string or YAML list) become pi's `--tools` /
+`--exclude-tools`; `effort` becomes the `:thinking` suffix on a pinned model;
+`permissionMode: plan` selects a read-only toolset unless `tools` is set. Model
+aliases (`sonnet`, `opus`, `haiku`, `inherit`) run on the session's default
+model. Fields with no pi equivalent are ignored: `skills`, `memory`,
+`mcpServers`, `maxTurns`.
+
 **Locations:**
-- `~/.pi/agent/agents/*.md` - User-level (always loaded)
-- `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
+- `~/.claude/agents/*.md`, `~/.pi/agent/agents/*.md` - User-level (always loaded; `~/.pi` wins a name conflict)
+- `.claude/agents/*.md`, `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`; `.pi` wins a name conflict)
 
 Project agents override user agents with the same name when `agentScope: "both"`.
 

package/extensions/subagent/agents.ts

@@ -23,13 +23,88 @@ function normalizeToolName(tool: string): string {
   return CLAUDE_TOOL_MAP[lower] ?? lower
 }
 
+/**
+ * `tools:` may be a comma-separated string (the Claude Code format) or a YAML block
+ * list. Anything else returns null: a restriction that failed to parse must not run
+ * the agent unrestricted.
+ */
+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)
+  return tools.length > 0 ? tools : undefined
+}
+
+/**
+ * Claude Code model aliases name Anthropic tiers. pi's resolver would partial-match
+ * one against an authenticated Anthropic provider, but for every other setup the
+ * child exits at boot on an unresolvable --model. Running on the session model
+ * (Claude's `inherit`) is the degradation that works everywhere; users who want a
+ * tier pinned should name a concrete model id.
+ */
+const CLAUDE_MODEL_ALIASES = new Set(['sonnet', 'opus', 'haiku', 'inherit'])
+
+function parseModelField(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined
+  const model = raw.trim()
+  return model && !CLAUDE_MODEL_ALIASES.has(model.toLowerCase()) ? model : undefined
+}
+
+/** pi's extended thinking levels; Claude's effort values are a subset, so they map 1:1. */
+const THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+
+function parseEffortField(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined
+  const effort = raw.trim().toLowerCase()
+  return THINKING_LEVELS.has(effort) ? effort : undefined
+}
+
+/** permissionMode has no pi equivalent; 'plan' means a research agent, so translate
+ * the intent into a read-only toolset unless the file pins tools itself. */
+const READ_ONLY_TOOLS = ['read', 'grep', 'find', 'ls']
+
+/** Parse one agent markdown file; null when it is not a usable agent definition. */
+function parseAgentFile(content: string, source: 'user' | 'project', filePath: string): AgentConfig | null {
+  let parsed: { frontmatter: Record<string, unknown>; body: string }
+  try {
+    parsed = parseFrontmatter<Record<string, unknown>>(content)
+  } catch {
+    return null // malformed YAML must not abort discovery for the whole directory
+  }
+  const { frontmatter, body } = parsed
+  const name = typeof frontmatter.name === 'string' ? frontmatter.name : ''
+  const description = typeof frontmatter.description === 'string' ? frontmatter.description : ''
+  if (!name || !description) return null
+  const tools = parseToolsField(frontmatter.tools)
+  if (tools === null) return null
+  const disallowedTools = parseToolsField(frontmatter.disallowedTools)
+  if (disallowedTools === null) return null
+  return {
+    name,
+    description,
+    tools: tools ?? (frontmatter.permissionMode === 'plan' ? [...READ_ONLY_TOOLS] : undefined),
+    disallowedTools,
+    model: parseModelField(frontmatter.model),
+    effort: parseEffortField(frontmatter.effort),
+    systemPrompt: body,
+    source,
+    filePath,
+  }
+}
+
 export type AgentScope = 'user' | 'project' | 'both'
 
 export interface AgentConfig {
   name: string
   description: string
   tools?: string[]
+  disallowedTools?: string[]
   model?: string
+  effort?: string
   systemPrompt: string
   source: 'user' | 'project'
   filePath: string
@@ -66,26 +141,8 @@ function loadAgentsFromDir(dir: string, source: 'user' | 'project'): AgentConfig
       continue
     }
 
-    const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content)
-
-    if (!frontmatter.name || !frontmatter.description) {
-      continue
-    }
-
-    const tools = frontmatter.tools
-      ?.split(',')
-      .map((t: string) => normalizeToolName(t.trim()))
-      .filter(Boolean)
-
-    agents.push({
-      name: frontmatter.name,
-      description: frontmatter.description,
-      tools: tools && tools.length > 0 ? tools : undefined,
-      model: frontmatter.model,
-      systemPrompt: body,
-      source,
-      filePath,
-    })
+    const agent = parseAgentFile(content, source, filePath)
+    if (agent) agents.push(agent)
   }
 
   return agents

package/extensions/subagent/background.ts

@@ -1,7 +1,8 @@
 /**
  * Background subagent runs: fire-and-forget children whose completion wakes
- * the parent agent via a notification message. Session-scoped (children die
- * with pi); state lives in an in-memory registry queried via {action:"status"}.
+ * the parent agent via a notification message. State lives in an in-memory
+ * registry queried via {status: true}; it is lost on restart, and a child
+ * still running when pi exits finishes on its own rather than being killed.
  */
 
 import { spawn } from 'node:child_process'
@@ -25,6 +26,13 @@ export interface BackgroundSpawn {
 
 const runs = new Map<string, BackgroundRun>()
 
+/** Cap on simultaneously running background children. */
+export const MAX_BACKGROUND_RUNS = 8
+
+export function activeBackgroundRuns(): number {
+  return [...runs.values()].filter((run) => run.state === 'running').length
+}
+
 /** Extract the final assistant text and turn count from a pi --mode json stdout stream. */
 export function parseFinalOutputFromJsonl(jsonl: string): { text: string; turns: number } {
   let text = ''
@@ -58,7 +66,11 @@ export function backgroundStatusText(): string {
   return formatStatus(runs.values())
 }
 
-export function startBackgroundRun(agent: string, task: string, invocation: BackgroundSpawn, onComplete: (run: BackgroundRun) => void): string {
+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
+  // could otherwise all pass that earlier check and overshoot the cap.
+  if (activeBackgroundRuns() >= MAX_BACKGROUND_RUNS) return null
   const id = `bg-${randomUUID().slice(0, 8)}`
   const run: BackgroundRun = { id, agent, task, state: 'running', turns: 0 }
   runs.set(id, run)
@@ -67,6 +79,8 @@ export function startBackgroundRun(agent: string, task: string, invocation: Back
     cwd: invocation.cwd,
     shell: false,
     stdio: ['ignore', 'pipe', 'ignore'],
+    // The marker lets the child's subagent tool refuse to nest further.
+    env: { ...process.env, PI_CODE_SUBAGENT: '1' },
   })
   let stdout = ''
   proc.stdout.on('data', (data) => {

package/extensions/subagent/index.ts

@@ -22,9 +22,10 @@ import { StringEnum } from '@earendil-works/pi-ai'
 import { type ExtensionAPI, type ExtensionContext, getMarkdownTheme, type Theme, withFileMutationQueue } from '@earendil-works/pi-coding-agent'
 import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui'
 import { type Static, Type } from 'typebox'
-import { isProjectApproved } from '../project-approval.js'
+import { capForContext } from '../internal/output-guard.js'
+import { isProjectApproved } from '../internal/project-approval.js'
 import { type AgentConfig, type AgentScope, discoverAgents } from './agents.js'
-import { backgroundStatusText, startBackgroundRun } from './background.js'
+import { activeBackgroundRuns, backgroundStatusText, MAX_BACKGROUND_RUNS, startBackgroundRun } from './background.js'
 
 const MAX_PARALLEL_TASKS = 8
 const MAX_CONCURRENCY = 4
@@ -274,9 +275,7 @@ async function runSingleAgent(options: RunAgentOptions): Promise<SingleResult> {
     }
   }
 
-  const args: string[] = ['--mode', 'json', '-p', '--no-session']
-  if (agent.model) args.push('--model', agent.model)
-  if (agent.tools && agent.tools.length > 0) args.push('--tools', agent.tools.join(','))
+  const args = agentInvocationArgs(agent)
 
   let tmpPromptDir: string | null = null
   let tmpPromptPath: string | null = null
@@ -319,6 +318,8 @@ async function runSingleAgent(options: RunAgentOptions): Promise<SingleResult> {
         cwd: cwd ?? defaultCwd,
         shell: false,
         stdio: ['ignore', 'pipe', 'pipe'],
+        // The marker lets the child's subagent tool refuse to nest further.
+        env: { ...process.env, PI_CODE_SUBAGENT: '1' },
       })
       let buffer = ''
 
@@ -504,6 +505,38 @@ async function checkProjectAgentGate(params: SubagentParamsStatic, agents: Agent
   return null
 }
 
+/** CLI args shared by foreground and background children, from the agent's config. */
+function agentInvocationArgs(agent: AgentConfig): string[] {
+  const args: string[] = ['--mode', 'json', '-p', '--no-session']
+  // pi reads a thinking level from the model pattern's :suffix, so Claude's effort
+  // has a seam only when the agent pins a concrete model.
+  if (agent.model) args.push('--model', agent.effort ? `${agent.model}:${agent.effort}` : agent.model)
+  if (agent.tools && agent.tools.length > 0) args.push('--tools', agent.tools.join(','))
+  if (agent.disallowedTools && agent.disallowedTools.length > 0) args.push('--exclude-tools', agent.disallowedTools.join(','))
+  return args
+}
+
+function backgroundCapResult(makeDetails: MakeDetails): ToolResult {
+  return {
+    content: [{ type: 'text', text: `Too many background runs (max ${MAX_BACKGROUND_RUNS} running). Wait for one to finish; check progress with {status: true}.` }],
+    details: makeDetails('single')([]),
+  }
+}
+
+function removeTmpPrompt(tmpPrompt: { dir: string; filePath: string } | undefined): void {
+  if (!tmpPrompt) return
+  try {
+    fs.unlinkSync(tmpPrompt.filePath)
+  } catch {
+    /* ignore */
+  }
+  try {
+    fs.rmdirSync(tmpPrompt.dir)
+  } catch {
+    /* ignore */
+  }
+}
+
 async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConfig[], defaultCwd: string, pi: ExtensionAPI, makeDetails: MakeDetails): Promise<ToolResult> {
   const task = params.task
   const agentName = params.agent
@@ -521,9 +554,10 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
       details: makeDetails('single')([]),
     }
   }
-  const args: string[] = ['--mode', 'json', '-p', '--no-session']
-  if (agent.model) args.push('--model', agent.model)
-  if (agent.tools && agent.tools.length > 0) args.push('--tools', agent.tools.join(','))
+  if (activeBackgroundRuns() >= MAX_BACKGROUND_RUNS) {
+    return backgroundCapResult(makeDetails)
+  }
+  const args = agentInvocationArgs(agent)
   let tmpPrompt: { dir: string; filePath: string } | undefined
   if (agent.systemPrompt.trim()) {
     tmpPrompt = await writePromptToTempFile(agent.name, agent.systemPrompt)
@@ -532,19 +566,8 @@ 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) => {
-    if (tmpPrompt) {
-      try {
-        fs.unlinkSync(tmpPrompt.filePath)
-      } catch {
-        /* ignore */
-      }
-      try {
-        fs.rmdirSync(tmpPrompt.dir)
-      } catch {
-        /* ignore */
-      }
-    }
-    const output = run.output || '(no output)'
+    removeTmpPrompt(tmpPrompt)
+    const output = capForContext(run.output ?? '') || '(no output)'
     pi.sendMessage(
       {
         customType: 'subagent-background',
@@ -554,6 +577,11 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
       { triggerTurn: true },
     )
   })
+  if (id === null) {
+    // Lost the cap race to a parallel batch: the atomic check inside startBackgroundRun refused.
+    removeTmpPrompt(tmpPrompt)
+    return backgroundCapResult(makeDetails)
+  }
   return {
     content: [{ type: 'text', text: `Started background run ${id} (${agent.name}). A notification will arrive on completion; check progress with {status: true}.` }],
     details: makeDetails('single')([]),
@@ -567,7 +595,8 @@ async function runChainMode(chain: ChainStepParam[], mode: ModeContext): Promise
 
   for (let i = 0; i < chain.length; i++) {
     const step = chain[i]
-    const taskWithContext = step.task.replaceAll('{previous}', previousOutput)
+    // Function replacement: a string here would interpret $-patterns in the output.
+    const taskWithContext = step.task.replaceAll('{previous}', () => previousOutput)
 
     // Create update callback that includes all previous results
     const chainUpdate: OnUpdateCallback | undefined = onUpdate
@@ -601,14 +630,14 @@ async function runChainMode(chain: ChainStepParam[], mode: ModeContext): Promise
     if (isError) {
       const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || '(no output)'
       return {
-        content: [{ type: 'text', text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}` }],
+        content: [{ type: 'text', text: capForContext(`Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}`) }],
         details: makeDetails('chain')(results),
       }
     }
     previousOutput = getFinalOutput(result.messages)
   }
   return {
-    content: [{ type: 'text', text: getFinalOutput(results.at(-1)?.messages ?? []) || '(no output)' }],
+    content: [{ type: 'text', text: capForContext(getFinalOutput(results.at(-1)?.messages ?? [])) || '(no output)' }],
     details: makeDetails('chain')(results),
   }
 }
@@ -678,15 +707,15 @@ async function runParallelMode(tasks: TaskItemParam[], mode: ModeContext): Promi
   const successCount = results.filter((r) => r.exitCode === 0).length
   const summaries = results.map((r) => {
     const output = getFinalOutput(r.messages)
-    const preview = output.slice(0, 100) + (output.length > 100 ? '...' : '')
     const status = r.exitCode === 0 ? 'completed' : 'failed'
-    return `[${r.agent}] ${status}: ${preview || '(no output)'}`
+    return `[${r.agent}] ${status}: ${output || '(no output)'}`
   })
   return {
     content: [
       {
         type: 'text',
-        text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join('\n\n')}`,
+        // Full reports, so a fan-out can be synthesized from; capped at pi's tool-output budget.
+        text: capForContext(`Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join('\n\n')}`),
       },
     ],
     details: makeDetails('parallel')(results),
@@ -709,12 +738,12 @@ async function runSingleMode(agentName: string, task: string, cwd: string | unde
   if (isError) {
     const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || '(no output)'
     return {
-      content: [{ type: 'text', text: `Agent ${result.stopReason || 'failed'}: ${errorMsg}` }],
+      content: [{ type: 'text', text: capForContext(`Agent ${result.stopReason || 'failed'}: ${errorMsg}`) }],
       details: makeDetails('single')([result]),
     }
   }
   return {
-    content: [{ type: 'text', text: getFinalOutput(result.messages) || '(no output)' }],
+    content: [{ type: 'text', text: capForContext(getFinalOutput(result.messages)) || '(no output)' }],
     details: makeDetails('single')([result]),
   }
 }
@@ -1014,13 +1043,21 @@ export default function subagentExtension(pi: ExtensionAPI) {
       'Delegate tasks to specialized subagents with isolated context.',
       'Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).',
       'Single mode also supports background: true for long tasks; a notification arrives on completion and {status: true} lists runs.',
-      'Default agent scope is "user" (from ~/.pi/agent/agents).',
-      'To enable project-local agents in .pi/agents, set agentScope: "both" (or "project").',
+      'Default agent scope is "user" (from ~/.claude/agents and ~/.pi/agent/agents).',
+      'To enable project-local agents in .claude/agents or .pi/agents, set agentScope: "both" (or "project").',
     ].join(' '),
     parameters: SubagentParams,
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const agentScope: AgentScope = params.agentScope ?? 'user'
+      // Children carry PI_CODE_SUBAGENT; without this check they could spawn
+      // grandchildren without limit.
+      if (process.env.PI_CODE_SUBAGENT) {
+        return {
+          content: [{ type: 'text', text: 'Nested subagent runs are not allowed: this session is already a subagent.' }],
+          details: { mode: 'single', agentScope, projectAgentsDir: null, results: [] },
+        }
+      }
       const discovery = discoverAgents(ctx.cwd, agentScope)
       const agents = discovery.agents
 

package/extensions/web.ts

@@ -12,7 +12,8 @@ import type { LookupFunction } from 'node:net'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
 
-import { httpFetch } from './web-transport.js'
+import { capForContext } from './internal/output-guard.js'
+import { httpFetch } from './internal/web-transport.js'
 
 const SEARCH_ENDPOINT = 'https://html.duckduckgo.com/html/?q='
 const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) pi-code-web/0.1'
@@ -59,16 +60,18 @@ export function resolveResultUrl(href: string): string {
 export function parseSearchResults(html: string, limit: number): SearchResult[] {
   const results: SearchResult[] = []
   const anchorPattern = /<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g
-  const snippetPattern = /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g
-  const snippets = [...html.matchAll(snippetPattern)].map((m) => stripTags(m[1]))
-  let index = 0
-  for (const match of html.matchAll(anchorPattern)) {
-    if (results.length >= limit) break
+  const snippetPattern = /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/
+  const anchors = [...html.matchAll(anchorPattern)]
+  for (let i = 0; i < anchors.length && results.length < limit; i++) {
+    const match = anchors[i]
     const url = resolveResultUrl(match[1])
     const title = stripTags(match[2])
     if (!title || url.includes('duckduckgo.com/y.js')) continue
-    results.push({ title, url, snippet: snippets[index] ?? '' })
-    index++
+    // A result's snippet sits between its anchor and the next one; pairing by block
+    // keeps attribution right when an ad anchor (skipped above) carries a snippet too.
+    const block = html.slice((match.index ?? 0) + match[0].length, anchors[i + 1]?.index ?? html.length)
+    const snippet = snippetPattern.exec(block)
+    results.push({ title, url, snippet: snippet ? stripTags(snippet[1]) : '' })
   }
   return results
 }
@@ -173,6 +176,9 @@ async function readCapped(response: Response): Promise<string> {
     if (done) break
     if (value) text += decoder.decode(value, { stream: true })
   }
+  // Flush: bytes of a character cut off by the end of the stream become U+FFFD
+  // instead of vanishing silently.
+  text += decoder.decode()
   await reader.cancel().catch(() => {})
   return text.slice(0, MAX_RAW_CHARS)
 }
@@ -233,7 +239,9 @@ export default function webExtension(pi: ExtensionAPI) {
       }
       const { text, contentType } = await fetchText(params.url)
       const body = contentType.includes('html') ? htmlToText(text) : text.slice(0, MAX_FETCH_CHARS)
-      return { content: [{ type: 'text' as const, text: body || '(empty response)' }], details: {} }
+      // The char cap alone admits thousands of short lines; pi's tool-output budget
+      // bounds lines too, which the shared guard enforces.
+      return { content: [{ type: 'text' as const, text: capForContext(body) || '(empty response)' }], details: {} }
     },
   })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "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-package"