pi-code 0.6.0 → 0.8.0

package/README.md

@@ -39,18 +39,18 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 | Custom slash commands | `.claude/commands/*.md` → pi prompt templates | `commands.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: 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`, `/output-style` switcher | `output-styles.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` |
 | 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` (incl. per-project `projects[cwd]` local scope), `~/.pi/agent/mcp.json`; project `.mcp.json`, `.pi/mcp.json` (once approved); stdio/HTTP/SSE by `type`; `${VAR:-default}` expansion; `MCP_TIMEOUT`/`MCP_TOOL_TIMEOUT` | `mcp.ts` |
+| 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` | `mcp.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/` |
+| 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; 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; 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 | one question with `header`, single- or `multiSelect` options, plus free-text; no multi-question batching | `question.ts` |
-| Statusline | turn state + session cost | `status-line.ts` |
+| Statusline | Claude `statusLine` command contract (stdin JSON, `padding`, `refreshInterval`); built-in turn state + session cost fallback | `status-line.ts` |
 | Notifications | vendored example | `notify.ts` |
 
 `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.

package/extensions/git-checkpoint.ts

@@ -13,6 +13,7 @@
  * the checkpoint (files created after the checkpoint are left in place).
  */
 
+import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent'
@@ -28,6 +29,35 @@ interface Checkpoint {
   createdAt: string
 }
 
+/** Claude deletes checkpoints after 30 days (cleanupPeriodDays). Shadow repos hold
+ * full snapshots of every non-ignored file, so unbounded retention grows under $HOME
+ * for the life of the machine. */
+export const CHECKPOINT_RETENTION_DAYS = 30
+
+/** Remove shadow repos untouched for longer than the retention window. The live
+ * session's repo is always kept, whatever its age: a long session's directory mtime
+ * can predate the window. Failures are ignored; this is housekeeping, not a gate. */
+export function pruneCheckpointRepos(root: string, retentionDays: number, keepDir?: string): void {
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true })
+  } catch {
+    return
+  }
+  const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const dir = path.join(root, entry.name)
+    if (keepDir && path.resolve(dir) === path.resolve(keepDir)) continue
+    try {
+      if (fs.statSync(dir).mtimeMs >= cutoff) continue
+      fs.rmSync(dir, { recursive: true, force: true })
+    } catch {
+      // a repo we cannot stat or remove stays; housekeeping must not break startup
+    }
+  }
+}
+
 export function sessionSlug(sessionFile: string | undefined): string {
   if (!sessionFile) return `ephemeral-${process.pid}`
   return path.basename(sessionFile).replace(/[^\w.-]+/g, '_')
@@ -93,7 +123,9 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
   async function ensureShadow(ctx: ExtensionContext): Promise<void> {
     workTree = ctx.cwd
     const sessionFile = (ctx.sessionManager as { getSessionFile?: () => string | undefined }).getSessionFile?.()
-    shadowDir = path.join(os.homedir(), '.pi', 'agent', 'checkpoints', sessionSlug(sessionFile))
+    const checkpointsRoot = path.join(os.homedir(), '.pi', 'agent', 'checkpoints')
+    shadowDir = path.join(checkpointsRoot, sessionSlug(sessionFile))
+    pruneCheckpointRepos(checkpointsRoot, CHECKPOINT_RETENTION_DAYS, shadowDir)
     const check = await pi.exec('git', ['--git-dir', shadowDir, 'rev-parse', '--git-dir'], { cwd: ctx.cwd })
     if (check.code !== 0) {
       await pi.exec('git', ['init', '--bare', '-b', 'main', shadowDir], { cwd: ctx.cwd })

package/extensions/internal/builtin-styles/explanatory.md

@@ -0,0 +1,15 @@
+---
+name: Explanatory
+description: Educational insights while completing tasks
+keep-coding-instructions: true
+---
+
+Between completing software engineering tasks, provide brief educational "Insights" that help the user understand implementation choices and codebase patterns.
+
+Mark each one clearly:
+
+`✻ Insight ─────`
+(2-3 sentences on why this approach, what pattern it follows, or what tradeoff it makes)
+`─────`
+
+Share an insight when there is a genuine decision or pattern worth understanding, not after every step. Keep the work itself unchanged: insights are commentary, never a substitute for doing the task.

package/extensions/internal/builtin-styles/learning.md

@@ -0,0 +1,15 @@
+---
+name: Learning
+description: Collaborative learn-by-doing with small human-written pieces
+keep-coding-instructions: true
+---
+
+Work collaboratively, learn-by-doing style: share brief "Insights" explaining implementation choices as you work, and regularly ask the user to contribute small, strategic pieces of code themselves.
+
+When a piece is well-scoped for the user to write (a condition, a small function body, a test assertion), leave a marker instead of writing it:
+
+```
+// TODO(human): <one sentence describing exactly what to implement here>
+```
+
+Then stop and ask the user to fill it in, explaining what the piece needs to do and why it matters. Choose pieces that teach something about the codebase or the problem, not busywork. Keep your own contributions moving the task forward between their turns.

package/extensions/internal/builtin-styles/proactive.md

@@ -0,0 +1,9 @@
+---
+name: Proactive
+description: Execute immediately, prefer action over planning
+keep-coding-instructions: true
+---
+
+Execute immediately. Make reasonable assumptions instead of pausing for routine decisions, and prefer action over planning: when a step is reversible and follows from the task, do it rather than proposing it.
+
+Ask only when a decision is genuinely the user's to make (destructive actions, real scope changes). Report what you did and why afterward, concisely.

package/extensions/internal/project-approval.ts

@@ -69,6 +69,16 @@ const APPROVAL_BODY = 'It ships Claude Code configuration that pi-code loads. MC
  * `defaultProjectTrust` at all, so there is no user preference to fall back on. A run
  * that cannot ask has not been approved.
  */
+/** The same decision as isProjectApproved, but never prompts: an undecided project
+ * reads as unapproved. For surfaces that only display project config, like the
+ * subagent roster, where a mid-turn dialog would be wrong. */
+export function isProjectApprovedSilently(ctx: Pick<ApprovalContext, 'cwd' | 'isProjectTrusted'>, deps: ApprovalDeps = defaultDeps): boolean {
+  if (ctx.isProjectTrusted?.() !== true) return false
+  if (!deps.hasClaudeShaped(ctx.cwd)) return true
+  if (deps.piWouldAsk(ctx.cwd)) return true
+  return deps.savedDecision(ctx.cwd) === true
+}
+
 export async function isProjectApproved(ctx: ApprovalContext, deps: ApprovalDeps = defaultDeps): Promise<boolean> {
   if (ctx.isProjectTrusted?.() !== true) return false // pi already declined, or never trusted
   if (!deps.hasClaudeShaped(ctx.cwd)) return true // nothing here pi's own check would miss

package/extensions/mcp.ts

@@ -21,7 +21,7 @@
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionContext } 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.
@@ -60,6 +60,8 @@ export interface StdioServerConfig {
   args?: string[]
   env?: Record<string, string>
   cwd?: string
+  /** Per-call wall-clock budget in ms, overriding MCP_TOOL_TIMEOUT for this server. */
+  timeout?: number
 }
 
 export interface HttpServerConfig {
@@ -68,6 +70,8 @@ export interface HttpServerConfig {
   headers?: Record<string, string>
   bearerToken?: string
   bearerTokenEnv?: string
+  /** Per-call wall-clock budget in ms, overriding MCP_TOOL_TIMEOUT for this server. */
+  timeout?: number
 }
 
 export type ServerConfig = StdioServerConfig | HttpServerConfig
@@ -92,6 +96,50 @@ export function projectConfigPaths(cwd: string): string[] {
   return [path.join(cwd, '.mcp.json'), path.join(cwd, '.pi', 'mcp.json')]
 }
 
+export interface ProjectServerPolicy {
+  disabled: Set<string>
+  consented: Set<string>
+  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 {
+  const read = (file: string): Record<string, unknown> => {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf-8'))
+    } catch {
+      return {}
+    }
+  }
+  const names = (value: unknown): string[] => (Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [])
+  const userSettings = read(path.join(home, '.claude', 'settings.json'))
+  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 consented = new Set(consentSources.flatMap((settings) => names(settings.enabledMcpjsonServers)))
+  const consentAll = consentSources.some((settings) => settings.enableAllProjectMcpServers === true)
+  return { disabled, consented, consentAll }
+}
+
+/** Split project servers by the per-server policy: never-connect, connect without the
+ * whole-project confirm, and still gated behind it. */
+export function splitByPolicy(candidates: Record<string, ServerConfig>, policy: ProjectServerPolicy): { consented: Record<string, ServerConfig>; gated: Record<string, ServerConfig> } {
+  const consented: Record<string, ServerConfig> = {}
+  const gated: Record<string, ServerConfig> = {}
+  for (const [name, config] of Object.entries(candidates)) {
+    if (policy.disabled.has(name)) continue
+    if (policy.consentAll || policy.consented.has(name)) consented[name] = config
+    else gated[name] = config
+  }
+  return { consented, gated }
+}
+
 export function loadConfigFrom(files: string[]): Record<string, ServerConfig> {
   const servers: Record<string, ServerConfig> = {}
   for (const file of files) {
@@ -122,6 +170,28 @@ export function loadUserScope(home: string, cwd: string): Record<string, ServerC
   return servers
 }
 
+/** Claude reports a config entry that has a url but no type as an error; pi-code
+ * still connects (streamable HTTP with SSE fallback) but says the entry is wrong. */
+/** An inline bearerToken (interpolated) wins over bearerTokenEnv, which names an
+ * environment variable read as-is. */
+export function resolveBearerToken(config: { bearerToken?: string; bearerTokenEnv?: string }): string | undefined {
+  if (config.bearerToken) return interpolateEnv(config.bearerToken)
+  if (config.bearerTokenEnv) return process.env[config.bearerTokenEnv]
+  return undefined
+}
+
+/** A server cwd expands ${VAR} then a leading ~, or stays unset. */
+export function expandCwd(cwd: string | undefined): string | undefined {
+  if (!cwd) return undefined
+  return interpolateEnv(cwd).replace(/^~(?=\/|$)/, os.homedir())
+}
+
+export function warnOnTypelessUrl(name: string, config: ServerConfig): void {
+  if ('url' in config && config.type === undefined) {
+    console.warn(`pi-code-mcp: server ${name} declares a url with no "type"; add "type": "http" or "sse"`)
+  }
+}
+
 export function formatToolName(server: string, tool: string): string {
   return `${server}_${tool}`.replaceAll('-', '_')
 }
@@ -197,7 +267,7 @@ async function connect(name: string, config: ServerConfig): Promise<Client> {
       command: interpolateEnv(config.command),
       args: (config.args ?? []).map((arg) => interpolateEnv(arg)),
       env,
-      cwd: config.cwd?.replace(/^~(?=\/|$)/, os.homedir()),
+      cwd: expandCwd(config.cwd),
       stderr: 'ignore',
     })
     await connectWithTimeout(client, transport, `connect ${name}`)
@@ -205,7 +275,7 @@ async function connect(name: string, config: ServerConfig): Promise<Client> {
   }
   const headers: Record<string, string> = {}
   for (const [key, value] of Object.entries(config.headers ?? {})) headers[key] = interpolateEnv(value)
-  const token = config.bearerToken ? interpolateEnv(config.bearerToken) : config.bearerTokenEnv ? process.env[config.bearerTokenEnv] : undefined
+  const token = resolveBearerToken(config)
   if (token) headers.Authorization = `Bearer ${token}`
   const url = new URL(interpolateEnv(config.url))
   if (config.type === 'sse') {
@@ -274,6 +344,7 @@ 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)
@@ -296,7 +367,10 @@ export default async function mcpExtension(pi: ExtensionAPI) {
             async execute(_id, params) {
               // Pass the timeout to the SDK too: its own default request timeout is 60s and
               // would otherwise reject first, so the outer race at CALL_TIMEOUT_MS was dead.
-              const result = await withTimeout(client.callTool({ name: tool.name, arguments: params as Record<string, unknown> }, undefined, { timeout: callTimeoutMs() }), callTimeoutMs(), toolName)
+              // Claude's per-server timeout wins over MCP_TOOL_TIMEOUT, with a 1s floor.
+              const declared = typeof config.timeout === 'number' && config.timeout >= 1000 ? config.timeout : undefined
+              const budget = declared ?? callTimeoutMs()
+              const result = await withTimeout(client.callTool({ name: tool.name, arguments: params as Record<string, unknown> }, undefined, { timeout: budget }), budget, toolName)
               const content = mapContent(result.content as McpContentBlock[], result.structuredContent)
               const details: { error?: string } = {}
               if (result.isError) {
@@ -315,6 +389,18 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     }
   }
 
+  /** 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())
+    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
+    if (!(await isProjectApproved(ctx))) return false
+    await connectServers(gated)
+    return true
+  }
+
   let userConnected = false
   let projectConnected = false
 
@@ -325,12 +411,12 @@ export default async function mcpExtension(pi: ExtensionAPI) {
       userConnected = true
       await connectServers(loadUserScope(os.homedir(), ctx.cwd))
     }
-    // A project .mcp.json can run arbitrary commands on connect, so only honor it once the project is trusted.
-    // isProjectTrusted alone is true for a repo pi never asked about; see project-approval.
-    if (!projectConnected && (await isProjectApproved(ctx))) {
-      projectConnected = true
-      await connectServers(loadConfigFrom(projectConfigPaths(ctx.cwd)))
-    }
+    // A project .mcp.json can run arbitrary commands on connect, so only honor it once
+    // the project is trusted. Per-server settings refine that: disabled servers never
+    // connect, servers the user consented to individually connect without the
+    // whole-project confirm, and the rest stay behind it. Reconnect attempts after a
+    // refusal are safe: connectServers skips names that already connected.
+    if (!projectConnected) projectConnected = await connectProjectScope(ctx)
 
     pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])
 

package/extensions/memory.ts

@@ -7,6 +7,7 @@
  * memories through the memory tool (save / read / delete / list).
  */
 
+import { createHash } from 'node:crypto'
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
@@ -17,7 +18,27 @@ import { capForContext } from './internal/output-guard.js'
 
 const INDEX_FILE = 'MEMORY.md'
 
+/** Claude loads the first 200 lines or 25KB of the memory index at startup. */
+export const INDEX_MAX_LINES = 200
+export const INDEX_MAX_BYTES = 25_000
+
+/** Windows drive letters are case-insensitive, so C:\x and c:\x are one project. */
+function normalizeCwd(cwd: string): string {
+  return cwd.replace(/^([A-Za-z]):(?=[/\\])/, (_match, letter: string) => letter.toUpperCase())
+}
+
+/** Readable dashed path plus a short digest of the real path. The digest is what makes
+ * the slug injective: every separator becomes a dash, so /a/b, /a-b and \a\b share a
+ * dashed form and would otherwise share one store. */
 export function projectSlug(cwd: string): string {
+  const normalized = normalizeCwd(cwd)
+  const readable = normalized.replace(/[/\\]/g, '-').replace(/^-+/, '-')
+  const digest = createHash('sha256').update(normalized).digest('hex').slice(0, 8)
+  return `${readable}-${digest}`
+}
+
+/** The pre-digest slug, kept only to migrate an existing store to the new name. */
+function legacySlug(cwd: string): string {
   return cwd
     .replace(/^([A-Za-z]):(?=[/\\])/, '$1')
     .replace(/[/\\]/g, '-')
@@ -28,6 +49,34 @@ export function memoryDir(cwd: string): string {
   return path.join(os.homedir(), '.pi', 'agent', 'memory', projectSlug(cwd))
 }
 
+/** Move a store written under the pre-digest slug to the current one, once. Without
+ * this the slug change would silently orphan every memory a user already has. */
+export function migrateLegacyStore(cwd: string): void {
+  const current = memoryDir(cwd)
+  if (fs.existsSync(current)) return
+  const legacy = path.join(os.homedir(), '.pi', 'agent', 'memory', legacySlug(cwd))
+  if (!fs.existsSync(legacy)) return
+  try {
+    fs.renameSync(legacy, current)
+  } catch {
+    // A failed migration must not take down session start; the store stays legacy.
+  }
+}
+
+/** The index as injected into the prompt, bounded like Claude's startup load. */
+export function capIndexForPrompt(index: string): string {
+  const withinLines = index.split('\n').slice(0, INDEX_MAX_LINES)
+  let dropped = index.split('\n').length - withinLines.length
+  let text = withinLines.join('\n')
+  while (Buffer.byteLength(text, 'utf-8') > INDEX_MAX_BYTES && withinLines.length > 1) {
+    withinLines.pop()
+    dropped++
+    text = withinLines.join('\n')
+  }
+  if (dropped <= 0) return index
+  return `${text}\n(${dropped} more memories not shown; use the memory tool with action "list")`
+}
+
 export function slugifyName(name: string): string {
   return (
     name
@@ -76,6 +125,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
   let dir = memoryDir(process.cwd())
 
   pi.on('session_start', async (_event, ctx) => {
+    migrateLegacyStore(ctx.cwd)
     dir = memoryDir(ctx.cwd)
     const count = readIndex(dir)
       .split('\n')
@@ -87,7 +137,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
     const index = readIndex(dir)
     if (!index.trim()) return
     return {
-      systemPrompt: `${event.systemPrompt}\n\n## Memory\n\nPersistent memories from earlier sessions (index):\n\n${index}\nUse the memory tool with action "read" to load a memory's full content when relevant.`,
+      systemPrompt: `${event.systemPrompt}\n\n## Memory\n\nPersistent memories from earlier sessions (index):\n\n${capIndexForPrompt(index)}\nUse the memory tool with action "read" to load a memory's full content when relevant.`,
     }
   })
 

package/extensions/output-styles.ts

@@ -8,8 +8,11 @@
  * tone and role. `/output-style` lists the styles and persists a choice to the
  * project's settings.local.json.
  *
- * pi keeps its own base system prompt (tools, safety); the style is layered on
- * top rather than replacing it wholesale.
+ * Claude semantics: a style replaces the built-in coding instructions unless its
+ * frontmatter sets `keep-coding-instructions: true`. The replacement excises pi's
+ * default coding prose up to a stable marker line and keeps everything after it
+ * (append text, project context, skills, other extensions' additions); when the
+ * marker is absent (custom SYSTEM.md), the style falls back to appending.
  *
  * Docs: https://code.claude.com/docs/en/output-styles.md
  */
@@ -25,6 +28,7 @@ export interface OutputStyle {
   name: string
   description: string
   body: string
+  keepCodingInstructions: boolean
 }
 
 function field(frontmatter: string, key: string): string {
@@ -37,7 +41,27 @@ export function parseStyle(content: string, fallbackName: string): OutputStyle {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)
   const frontmatter = match ? match[1] : ''
   const body = match ? content.slice(match[0].length) : content
-  return { name: field(frontmatter, 'name') || fallbackName, description: field(frontmatter, 'description'), body: body.trim() }
+  return { name: field(frontmatter, 'name') || fallbackName, description: field(frontmatter, 'description'), body: body.trim(), keepCodingInstructions: field(frontmatter, 'keep-coding-instructions') === 'true' }
+}
+
+/** Equivalents of Claude's built-in styles, shipped with pi-code as the
+ * lowest-precedence source: a user or project style of the same name wins. */
+export const BUILTIN_STYLES_DIR = path.join(import.meta.dirname, 'internal', 'builtin-styles')
+
+/** The last line of pi's default coding instructions. Everything after it (append
+ * text, project context, skills, cwd, other extensions' additions) survives a style
+ * replacement. Tracks pi's dist/core/system-prompt.js; a canary test pins it. */
+export const CODING_BASE_MARKER = '- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)'
+
+/** Apply a style per Claude semantics: replace the coding instructions unless the
+ * style keeps them; fall back to appending when the marker is absent. */
+export function applyStyle(systemPrompt: string, style: OutputStyle): string {
+  const styleSection = `## Output Style: ${style.name}\n\n${style.body}`
+  if (!style.keepCodingInstructions) {
+    const idx = systemPrompt.indexOf(CODING_BASE_MARKER)
+    if (idx !== -1) return `${styleSection}${systemPrompt.slice(idx + CODING_BASE_MARKER.length)}`
+  }
+  return `${systemPrompt}\n\n${styleSection}`
 }
 
 function isDirectory(target: string): boolean {
@@ -132,7 +156,7 @@ export default function outputStylesExtension(pi: ExtensionAPI) {
     // 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))
+    styles = loadStyles([BUILTIN_STYLES_DIR, ...styleDirs(ctx.cwd, home, trusted)])
     localSettingsPath = path.join(ctx.cwd, '.claude', 'settings.local.json')
     activeName = readActiveStyleName(settingsFiles(ctx.cwd, home, trusted))
     const active = styleForName(styles, activeName)
@@ -142,12 +166,24 @@ export default function outputStylesExtension(pi: ExtensionAPI) {
   pi.on('before_agent_start', async (event) => {
     const active = styleForName(styles, activeName)
     if (!active || active.body.length === 0) return
-    return { systemPrompt: `${event.systemPrompt}\n\n## Output Style: ${active.name}\n\n${active.body}` }
+    return { systemPrompt: applyStyle(event.systemPrompt, active) }
   })
 
   pi.registerCommand('output-style', {
-    description: 'Choose the active Claude output style',
-    handler: async (_args, ctx) => {
+    description: 'Choose the active Claude output style (or /output-style <name>)',
+    handler: async (args, ctx) => {
+      const requested = args.trim()
+      if (requested) {
+        const picked = styles.find((style) => style.name.toLowerCase() === requested.toLowerCase())
+        if (!picked) {
+          ctx.ui.notify(`Unknown output style: ${requested}. Available: ${styles.map((style) => style.name).join(', ')}`, 'error')
+          return
+        }
+        activeName = picked.name
+        persistActiveStyle(localSettingsPath, picked.name)
+        ctx.ui.notify(`Output style set to ${picked.name} (applies next turn)`, 'info')
+        return
+      }
       if (!ctx.hasUI) {
         ctx.ui.notify('/output-style requires interactive mode', 'error')
         return

package/extensions/plan-mode/utils.ts

@@ -194,8 +194,10 @@ export function cleanStepText(text: string): string {
 // Anchored to line start (m flag) so a prose line merely ending in "plan:" is not taken
 // for the header, which would slice the plan section mid-list and drop earlier steps.
 // Horizontal whitespace only ([^\S\n]): \s would include \n itself and overlap the
-// following \n, which is what backtracks super-linearly.
-const PLAN_HEADER = /^[^\S\n]*\*{0,2}Plan:\*{0,2}[^\S\n]*\n/im
+// following \n. The runs are bounded rather than unbounded: an unbounded run retried
+// from every position on a long whitespace-only line is what backtracks super-linearly,
+// and a real header carries at most a few spaces of indentation.
+const PLAN_HEADER = /^[^\S\n]{0,8}\*{0,2}Plan:\*{0,2}[^\S\n]{0,8}\n/im
 
 const isBlank = (ch: string | undefined): boolean => ch !== undefined && ch !== '\n' && ch.trim() === ''
 

package/extensions/question.ts

@@ -32,10 +32,10 @@ const OptionSchema = Type.Object({
   description: Type.Optional(Type.String({ description: 'Optional description shown below label' })),
 })
 
-const QuestionParams = Type.Object({
+export const QuestionParams = Type.Object({
   question: Type.String({ description: 'The question to ask the user' }),
-  header: Type.Optional(Type.String({ description: 'Short label for the question, shown above it' })),
-  options: Type.Array(OptionSchema, { description: 'Options for the user to choose from' }),
+  header: Type.Optional(Type.String({ description: 'Short label for the question, shown above it (max 12 characters)', maxLength: 12 })),
+  options: Type.Array(OptionSchema, { description: 'Options for the user to choose from (1-4)', minItems: 1, maxItems: 4 }),
   multiSelect: Type.Optional(Type.Boolean({ description: 'Allow selecting several options (space toggles, enter confirms)' })),
 })
 

package/extensions/status-line.ts

@@ -1,16 +1,36 @@
 /**
  * Status Line Extension
  *
- * Adds a Claude Code style status segment to pi's footer: turn state plus
- * running session cost. Cost is summed from per-message usage on the current
- * branch, so it stays correct across /tree navigation and forks.
+ * Honors Claude Code's `statusLine` settings contract: a configured command runs
+ * with the session JSON on stdin (model, workspace, cost, context_window, effort,
+ * output_style, session ids) and its first stdout line becomes the footer segment,
+ * padded per `padding`. It re-runs, debounced 300ms as Claude does, at session
+ * start, after turns, after compaction, on plan-mode changes (the permission-mode
+ * analogue, off the shared bus), and on the optional `refreshInterval` timer
+ * (minimum 1s). A project-defined command is arbitrary shell, so project settings
+ * count only once the project is already approved, read without prompting.
  *
- * pi's built-in footer already shows path, branch, context, and model;
- * this extension only adds what is missing instead of replacing the footer.
+ * Without a configured statusLine, the built-in segment shows turn state plus
+ * running session cost, summed from per-message usage on the current branch so it
+ * stays correct across /tree navigation and forks. The built-in segment is also
+ * the fallback while a configured command produces no output. Multi-line output
+ * is truncated to its first line: the segment is one footer row in pi.
+ *
+ * Docs: https://code.claude.com/docs/en/statusline.md
  */
 
+import * as fs from 'node:fs'
+import * as os from 'node:os'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 
+import { hookFiles, runHookCommand } from './hooks.js'
+import { isPlanModeState, PLAN_MODE_CHANNEL } from './internal/plan-mode-state.js'
+import { isProjectApprovedSilently } from './internal/project-approval.js'
+import { readActiveStyleName, settingsFiles } from './output-styles.js'
+
+const COMMAND_TIMEOUT_MS = 5_000
+const DEBOUNCE_MS = 300
+
 interface UsageEntry {
   type: string
   message?: { usage?: { cost?: { total?: number } } }
@@ -28,34 +48,156 @@ function formatCost(cost: number): string {
   return cost >= 0.01 ? `$${cost.toFixed(2)}` : `$${cost.toFixed(4)}`
 }
 
+export interface StatusLineConfig {
+  command: string
+  padding: number
+  refreshInterval: number | undefined
+}
+
+/** The `statusLine` recorded in settings, last file winning. Claude's shape is
+ * `{type: "command", command, padding?, refreshInterval?}`; entries without a
+ * command string are ignored, and refreshInterval has a documented minimum of 1. */
+export function readStatusLineConfig(files: string[]): StatusLineConfig | undefined {
+  let found: StatusLineConfig | undefined
+  for (const file of files) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      const entry = settings.statusLine
+      if (!entry || typeof entry.command !== 'string') continue
+      if (entry.type !== undefined && entry.type !== 'command') continue
+      found = {
+        command: entry.command,
+        padding: typeof entry.padding === 'number' && entry.padding > 0 ? entry.padding : 0,
+        refreshInterval: typeof entry.refreshInterval === 'number' && entry.refreshInterval >= 1 ? entry.refreshInterval : undefined,
+      }
+    } catch {
+      // missing or invalid file: skip
+    }
+  }
+  return found
+}
+
 export default function statusLine(pi: ExtensionAPI) {
   let turnCount = 0
+  let config: StatusLineConfig | undefined
+  let sessionCtx: ExtensionContext | undefined
+  let commandLine: string | undefined
+  let permissionMode = 'default'
+  let refreshTimer: ReturnType<typeof setInterval> | undefined
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined
+  let running = false
+  let rerunQueued = false
 
-  function showIdle(ctx: ExtensionContext, symbol: string): void {
+  function segmentText(ctx: ExtensionContext, symbol: string): string {
     const theme = ctx.ui.theme
     const cost = sessionCost(ctx)
     const costText = cost > 0 ? theme.fg('muted', ` ${formatCost(cost)}`) : ''
     const turnText = turnCount > 0 ? theme.fg('dim', ` turn ${turnCount}`) : theme.fg('dim', ' ready')
-    ctx.ui.setStatus('pi-code-status', symbol + turnText + costText)
+    return symbol + turnText + costText
+  }
+
+  function show(ctx: ExtensionContext, builtIn: string): void {
+    ctx.ui.setStatus('pi-code-status', commandLine ?? builtIn)
+  }
+
+  /** 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))
+    const payload: Record<string, unknown> = {
+      session_id: ctx.sessionManager.getSessionId(),
+      cwd: ctx.cwd,
+      workspace: { current_dir: ctx.cwd, project_dir: ctx.cwd },
+      model: { id: (ctx.model as { id?: string } | undefined)?.id ?? '' },
+      cost: { total_cost_usd: sessionCost(ctx) },
+      context_window: { context_window_size: usage.contextWindow, used_percentage: usage.percent, total_input_tokens: usage.tokens },
+      permission_mode: permissionMode,
+    }
+    const transcript = ctx.sessionManager.getSessionFile()
+    if (transcript) payload.transcript_path = transcript
+    if (ctx.thinkingLevel) payload.effort = { level: ctx.thinkingLevel }
+    if (styleName) payload.output_style = { name: styleName }
+    return payload
+  }
+
+  async function runCommand(ctx: ExtensionContext): Promise<void> {
+    if (!config) return
+    if (running) {
+      rerunQueued = true
+      return
+    }
+    running = true
+    try {
+      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', '○')))
+    } finally {
+      running = false
+      if (rerunQueued) {
+        rerunQueued = false
+        void runCommand(ctx)
+      }
+    }
   }
 
+  /** Claude debounces statusline updates at 300ms so rapid triggers batch. */
+  function scheduleRefresh(): void {
+    if (!config || !sessionCtx) return
+    const ctx = sessionCtx
+    clearTimeout(debounceTimer)
+    debounceTimer = setTimeout(() => {
+      void runCommand(ctx)
+    }, DEBOUNCE_MS)
+  }
+
+  pi.events.on(PLAN_MODE_CHANNEL, (data) => {
+    if (!isPlanModeState(data)) return
+    permissionMode = data.active ? 'plan' : 'default'
+    scheduleRefresh()
+  })
+
   pi.on('session_start', async (_event, ctx) => {
-    // One instance serves every session, so a fresh session must not inherit the count.
+    // One instance serves every session, so a fresh session must not inherit state.
     turnCount = 0
-    showIdle(ctx, ctx.ui.theme.fg('dim', '○'))
+    commandLine = undefined
+    sessionCtx = ctx
+    clearInterval(refreshTimer)
+    // Reading config must never open a trust dialog: several extensions resolve
+    // 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)
+    config = readStatusLineConfig(hookFiles(ctx.cwd, os.homedir(), trusted))
+    if (config?.refreshInterval) {
+      refreshTimer = setInterval(() => scheduleRefresh(), config.refreshInterval * 1000)
+    }
+    show(ctx, segmentText(ctx, ctx.ui.theme.fg('dim', '○')))
+    scheduleRefresh()
   })
 
   pi.on('turn_start', async (_event, ctx) => {
     turnCount++
     const theme = ctx.ui.theme
-    ctx.ui.setStatus('pi-code-status', theme.fg('accent', '●') + theme.fg('dim', ` turn ${turnCount}...`))
+    show(ctx, theme.fg('accent', '●') + theme.fg('dim', ` turn ${turnCount}...`))
   })
 
   pi.on('turn_end', async (_event, ctx) => {
-    showIdle(ctx, ctx.ui.theme.fg('success', '✓'))
+    show(ctx, segmentText(ctx, ctx.ui.theme.fg('success', '✓')))
+    scheduleRefresh()
   })
 
   pi.on('agent_end', async (_event, ctx) => {
-    showIdle(ctx, ctx.ui.theme.fg('success', '✓'))
+    show(ctx, segmentText(ctx, ctx.ui.theme.fg('success', '✓')))
+    scheduleRefresh()
+  })
+
+  pi.on('session_compact', async (_event, _ctx) => {
+    scheduleRefresh()
+  })
+
+  pi.on('session_shutdown', async () => {
+    clearInterval(refreshTimer)
+    clearTimeout(debounceTimer)
   })
 }

package/extensions/subagent/README.md

@@ -7,7 +7,7 @@ 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
+- **Background runs**: `{background: true}` returns a run id and notifies on completion; `{status: true}` lists runs and `{cancel: "<id>"}` stops one (signalling its process group); 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
@@ -21,15 +21,10 @@ subagent/
 ├── 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
-│   ├── reviewer.md      # Code review
-│   └── worker.md        # General-purpose (full capabilities)
-└── prompts/             # Workflow presets (prompt templates)
-    ├── implement.md     # scout -> planner -> worker
-    ├── scout-and-plan.md    # scout -> planner (no implementation)
-    └── implement-and-review.md  # worker -> reviewer -> worker
+├── agents/              # Bundled builtin agents, always available (lowest precedence)
+│   ├── explore.md       # Explore: fast read-only codebase exploration
+│   ├── plan.md          # Plan: read-only implementation planning
+│   └── general-purpose.md   # general-purpose: full capabilities
 ```
 
 ## Installation
@@ -42,7 +37,7 @@ 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 `~/.claude/agents` and `~/.pi/agent/agents`.
+**Default behavior:** Loads the bundled builtin agents (Explore, Plan, general-purpose) plus **user-level agents** from `~/.claude/agents` and `~/.pi/agent/agents`. A user or project agent with the same name overrides a builtin. Discovered agents and their descriptions are listed in the system prompt each turn, so the model can pick one itself; project agent descriptions appear only once the project is approved.
 
 To enable project-local agents (`.claude/agents`, `.pi/agents`), pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
 
@@ -52,24 +47,17 @@ When running interactively, the tool prompts for confirmation before running pro
 
 ### Single agent
 ```
-Use scout to find all authentication code
+Use Explore to find all authentication code
 ```
 
 ### Parallel execution
 ```
-Run 2 scouts in parallel: one to find models, one to find providers
+Run 2 Explore agents in parallel: one to find models, one to find providers
 ```
 
 ### Chained workflow
 ```
-Use a chain: first have scout find the read tool, then have planner suggest improvements
-```
-
-### Workflow prompts
-```
-/implement add Redis caching to the session store
-/scout-and-plan refactor auth to support OAuth
-/implement-and-review add input validation to API endpoints
+Use a chain: first have Explore find the read tool, then have Plan suggest improvements
 ```
 
 ## Tool Modes
@@ -135,22 +123,15 @@ model. Fields with no pi equivalent are ignored: `skills`, `memory`,
 
 Project agents override user agents with the same name when `agentScope: "both"`.
 
-## Sample Agents
-
-| Agent | Purpose | Model | Tools |
-|-------|---------|-------|-------|
-| `scout` | Fast codebase recon | Haiku | read, grep, find, ls, bash |
-| `planner` | Implementation plans | Sonnet | read, grep, find, ls |
-| `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
-| `worker` | General-purpose | Sonnet | (all default) |
+## Builtin Agents
 
-## Workflow Prompts
+| Agent | Purpose | Tools |
+|-------|---------|-------|
+| `Explore` | Fast read-only codebase exploration | read, grep, find, ls |
+| `Plan` | Read-only implementation planning | read, grep, find, ls |
+| `general-purpose` | Full capabilities, isolated context | (all default) |
 
-| Prompt | Flow |
-|--------|------|
-| `/implement <query>` | scout → planner → worker |
-| `/scout-and-plan <query>` | scout → planner |
-| `/implement-and-review <query>` | worker → reviewer → worker |
+No model is pinned: each runs on the session's default model.
 
 ## Error Handling
 

package/extensions/subagent/agents/explore.md

@@ -0,0 +1,18 @@
+---
+name: Explore
+description: Fast read-only codebase exploration that returns compressed findings
+tools: read, grep, find, ls
+---
+
+You are an exploration agent. Quickly investigate the codebase and return structured findings that another agent can use without re-reading everything.
+
+You must NOT make any changes: only read, search, and summarize.
+
+Your output goes to an agent who has NOT seen the files you explored. Report:
+
+1. Relevant files with paths and one-line roles
+2. Key functions/types with `file:line` references
+3. How the pieces connect (data flow, call flow)
+4. Anything surprising or risky
+
+Be selective: compressed, load-bearing findings beat exhaustive dumps.

package/extensions/subagent/agents/general-purpose.md

@@ -0,0 +1,10 @@
+---
+name: general-purpose
+description: General-purpose agent with full capabilities in an isolated context
+---
+
+You are a general-purpose agent with full capabilities, operating in an isolated context window to handle delegated tasks without polluting the main conversation.
+
+Work autonomously to complete the assigned task, using the available tools as needed.
+
+When finished, report: what was done, what was verified (commands run, tests passed), and anything the delegator must know (caveats, follow-ups, files changed).

package/extensions/subagent/agents/plan.md

@@ -0,0 +1,16 @@
+---
+name: Plan
+description: Designs implementation plans from context and requirements, read-only
+tools: read, grep, find, ls
+---
+
+You are a planning specialist. You receive context and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes: only read, analyze, and plan.
+
+Deliver:
+
+1. Step-by-step plan, each step small and independently verifiable
+2. Files to touch per step, with `file:line` anchors where known
+3. Risks and open questions, each with a suggested resolution
+4. What to test and how the tests would fail without the change

package/extensions/subagent/agents.ts

@@ -68,7 +68,7 @@ function parseEffortField(raw: unknown): string | undefined {
 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 {
+function parseAgentFile(content: string, source: AgentSource, filePath: string): AgentConfig | null {
   let parsed: { frontmatter: Record<string, unknown>; body: string }
   try {
     parsed = parseFrontmatter<Record<string, unknown>>(content)
@@ -106,7 +106,7 @@ export interface AgentConfig {
   model?: string
   effort?: string
   systemPrompt: string
-  source: 'user' | 'project'
+  source: AgentSource
   filePath: string
 }
 
@@ -115,7 +115,7 @@ export interface AgentDiscoveryResult {
   projectAgentsDir: string | null
 }
 
-function loadAgentsFromDir(dir: string, source: 'user' | 'project'): AgentConfig[] {
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
   const agents: AgentConfig[] = []
 
   if (!fs.existsSync(dir)) {
@@ -202,6 +202,11 @@ function buildAgentMap(userAgents: AgentConfig[], projectAgents: AgentConfig[],
   return agentMap
 }
 
+export type AgentSource = 'user' | 'project' | 'builtin'
+
+/** Bundled default agents (Explore, Plan, general-purpose), lowest precedence. */
+export const BUILTIN_AGENTS_DIR = path.join(import.meta.dirname, 'agents')
+
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
   const userDir = path.join(getAgentDir(), 'agents')
   const claudeUserDir = path.join(os.homedir(), '.claude', 'agents')
@@ -209,7 +214,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
   const projectClaudeDir = findNearestDir(cwd, path.join('.claude', 'agents'))
 
   // ~/.claude/agents loads first so ~/.pi/agent/agents wins on name conflicts
-  const userAgents = scope === 'project' ? [] : [...loadAgentsFromDir(claudeUserDir, 'user'), ...loadAgentsFromDir(userDir, 'user')]
+  const userAgents = scope === 'project' ? [] : [...loadAgentsFromDir(BUILTIN_AGENTS_DIR, 'builtin'), ...loadAgentsFromDir(claudeUserDir, 'user'), ...loadAgentsFromDir(userDir, 'user')]
   // project .claude/agents loads first so project .pi/agents wins on name conflicts
   const projectAgents = scope === 'user' ? [] : [...(projectClaudeDir ? loadAgentsFromDir(projectClaudeDir, 'project') : []), ...(projectPiDir ? loadAgentsFromDir(projectPiDir, 'project') : [])]
 

package/extensions/subagent/background.ts

@@ -12,10 +12,12 @@ export interface BackgroundRun {
   id: string
   agent: string
   task: string
-  state: 'running' | 'done' | 'failed'
+  state: 'running' | 'done' | 'failed' | 'cancelled'
   exitCode?: number
   output?: string
   turns: number
+  /** Set while running so the run can be cancelled; cleared on completion. */
+  kill?: () => void
 }
 
 export interface BackgroundSpawn {
@@ -63,6 +65,18 @@ export function formatStatus(all: Iterable<BackgroundRun>): string {
   return lines.length > 0 ? lines.join('\n') : 'No background runs in this session.'
 }
 
+/** Cancel a running background child. Returns what the caller should tell the model:
+ * unknown id, already finished, or cancelled. */
+export function cancelBackgroundRun(id: string): 'cancelled' | 'not-running' | 'unknown' {
+  const run = runs.get(id)
+  if (!run) return 'unknown'
+  if (run.state !== 'running' || !run.kill) return 'not-running'
+  run.state = 'cancelled'
+  run.kill()
+  run.kill = undefined
+  return 'cancelled'
+}
+
 export function backgroundStatusText(): string {
   return formatStatus(runs.values())
 }
@@ -80,9 +94,18 @@ export function startBackgroundRun(agent: string, task: string, invocation: Back
     cwd: invocation.cwd,
     shell: false,
     stdio: ['ignore', 'pipe', 'ignore'],
+    // Its own group, so cancelling reaches any grandchild the agent spawned.
+    detached: true,
     // The marker lets the child's subagent tool refuse to nest further.
     env: { ...process.env, PI_CODE_SUBAGENT: '1' },
   })
+  run.kill = () => {
+    try {
+      process.kill(-proc.pid!, 'SIGTERM')
+    } catch {
+      proc.kill('SIGTERM')
+    }
+  }
   let stdout = ''
   // Node fires both 'error' and 'close' on a spawn failure (ENOENT); complete once.
   let completed = false
@@ -96,13 +119,16 @@ export function startBackgroundRun(agent: string, task: string, invocation: Back
   })
   proc.on('close', (code) => {
     const { text, turns } = parseFinalOutputFromJsonl(stdout)
-    run.state = code === 0 ? 'done' : 'failed'
+    run.kill = undefined
+    // A cancelled run keeps that state: its non-zero exit is the cancellation.
+    if (run.state !== 'cancelled') run.state = code === 0 ? 'done' : 'failed'
     run.exitCode = code ?? 0
     run.output = text
     run.turns = turns
     complete()
   })
   proc.on('error', () => {
+    run.kill = undefined
     run.state = 'failed'
     run.exitCode = 1
     complete()

package/extensions/subagent/index.ts

@@ -24,10 +24,10 @@ import { type ExtensionAPI, type ExtensionContext, getMarkdownTheme, type Theme,
 import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui'
 import { type Static, Type } from 'typebox'
 import { capForContext } from '../internal/output-guard.js'
-import { isProjectApproved } from '../internal/project-approval.js'
+import { isProjectApproved, isProjectApprovedSilently } from '../internal/project-approval.js'
 import { SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
 import { type AgentConfig, type AgentScope, discoverAgents } from './agents.js'
-import { activeBackgroundRuns, backgroundStatusText, MAX_BACKGROUND_RUNS, startBackgroundRun } from './background.js'
+import { activeBackgroundRuns, backgroundStatusText, cancelBackgroundRun, MAX_BACKGROUND_RUNS, startBackgroundRun } from './background.js'
 
 const MAX_PARALLEL_TASKS = 8
 const MAX_CONCURRENCY = 4
@@ -139,7 +139,7 @@ interface UsageStats {
 
 interface SingleResult {
   agent: string
-  agentSource: 'user' | 'project' | 'unknown'
+  agentSource: 'user' | 'project' | 'builtin' | 'unknown'
   task: string
   exitCode: number
   messages: Message[]
@@ -460,6 +460,7 @@ const SubagentParams = Type.Object({
   cwd: Type.Optional(Type.String({ description: 'Working directory for the agent process (single mode)' })),
   background: Type.Optional(Type.Boolean({ description: 'Run the single-mode task in the background: returns a run id immediately and a notification arrives when it completes.' })),
   status: Type.Optional(Type.Boolean({ description: 'Set true (alone, no other params) to list background runs instead of running anything.' })),
+  cancel: Type.Optional(Type.String({ description: 'Background run id to cancel (from the id returned when it started, or from status).' })),
 })
 
 /**
@@ -489,6 +490,14 @@ type SubagentParamsStatic = Static<typeof SubagentParams>
 type ChainStepParam = Static<typeof ChainItem>
 type TaskItemParam = Static<typeof TaskItem>
 
+/** What to tell the model about a cancel request. */
+export function cancelResultText(id: string): string {
+  const outcome = cancelBackgroundRun(id)
+  if (outcome === 'cancelled') return `Cancelled background run ${id}.`
+  if (outcome === 'not-running') return `Background run ${id} already finished; nothing to cancel.`
+  return `Unknown background run: ${id}.\n\n${backgroundStatusText()}`
+}
+
 /** Everything a mode handler needs from the surrounding execute() call. */
 interface ModeContext {
   agents: AgentConfig[]
@@ -1068,6 +1077,19 @@ function renderParallelResult(results: SingleResult[], expanded: boolean, theme:
 }
 
 export default function subagentExtension(pi: ExtensionAPI) {
+  // Claude surfaces each agent's description so the model can pick one autonomously.
+  // Rebuilt per turn (agents are rediscovered per invocation too); project agents are
+  // included only when the project is already approved, read without prompting, since
+  // a trust dialog must not appear mid-turn and their descriptions are project text.
+  pi.on('before_agent_start', async (event, ctx) => {
+    const scope = isProjectApprovedSilently(ctx) ? 'both' : 'user'
+    const { agents } = discoverAgents(ctx.cwd, scope)
+    if (agents.length === 0) return
+    const line = (text: string): string => text.replace(/\s+/g, ' ').trim().slice(0, 200)
+    const roster = agents.map((agent) => `- ${agent.name} (${agent.source}): ${line(agent.description)}`).join('\n')
+    return { systemPrompt: `${event.systemPrompt}\n\n## Subagents\n\nDelegate isolated tasks with the subagent tool ({agent, task}). Available agents:\n${roster}` }
+  })
+
   pi.registerTool({
     name: 'subagent',
     label: 'Subagent',
@@ -1107,6 +1129,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
           results,
         })
 
+      if (params.cancel) {
+        return { content: [{ type: 'text', text: cancelResultText(params.cancel) }], details: makeDetails('single')([]) }
+      }
+
       if (params.status) {
         return { content: [{ type: 'text', text: backgroundStatusText() }], details: makeDetails('single')([]) }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "0.6.0",
+  "version": "0.8.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/extensions/subagent/agents/planner.md

@@ -1,37 +0,0 @@
----
-name: planner
-description: Creates implementation plans from context and requirements
-tools: read, grep, find, ls
-model: claude-sonnet-4-5
----
-
-You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
-
-You must NOT make any changes. Only read, analyze, and plan.
-
-Input format you'll receive:
-- Context/findings from a scout agent
-- Original query or requirements
-
-Output format:
-
-## Goal
-One sentence summary of what needs to be done.
-
-## Plan
-Numbered steps, each small and actionable:
-1. Step one - specific file/function to modify
-2. Step two - what to add/change
-3. ...
-
-## Files to Modify
-- `path/to/file.ts` - what changes
-- `path/to/other.ts` - what changes
-
-## New Files (if any)
-- `path/to/new.ts` - purpose
-
-## Risks
-Anything to watch out for.
-
-Keep the plan concrete. The worker agent will execute it verbatim.

package/extensions/subagent/agents/reviewer.md

@@ -1,35 +0,0 @@
----
-name: reviewer
-description: Code review specialist for quality and security analysis
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
----
-
-You are a senior code reviewer. Analyze code for quality, security, and maintainability.
-
-Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
-Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
-
-Strategy:
-1. Run `git diff` to see recent changes (if applicable)
-2. Read the modified files
-3. Check for bugs, security issues, code smells
-
-Output format:
-
-## Files Reviewed
-- `path/to/file.ts` (lines X-Y)
-
-## Critical (must fix)
-- `file.ts:42` - Issue description
-
-## Warnings (should fix)
-- `file.ts:100` - Issue description
-
-## Suggestions (consider)
-- `file.ts:150` - Improvement idea
-
-## Summary
-Overall assessment in 2-3 sentences.
-
-Be specific with file paths and line numbers.

package/extensions/subagent/agents/scout.md

@@ -1,50 +0,0 @@
----
-name: scout
-description: Fast codebase recon that returns compressed context for handoff to other agents
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
----
-
-You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
-
-Your output will be passed to an agent who has NOT seen the files you explored.
-
-Thoroughness (infer from task, default medium):
-- Quick: Targeted lookups, key files only
-- Medium: Follow imports, read critical sections
-- Thorough: Trace all dependencies, check tests/types
-
-Strategy:
-1. grep/find to locate relevant code
-2. Read key sections (not entire files)
-3. Identify types, interfaces, key functions
-4. Note dependencies between files
-
-Output format:
-
-## Files Retrieved
-List with exact line ranges:
-1. `path/to/file.ts` (lines 10-50) - Description of what's here
-2. `path/to/other.ts` (lines 100-150) - Description
-3. ...
-
-## Key Code
-Critical types, interfaces, or functions:
-
-```typescript
-interface Example {
-  // actual code from the files
-}
-```
-
-```typescript
-function keyFunction() {
-  // actual implementation
-}
-```
-
-## Architecture
-Brief explanation of how the pieces connect.
-
-## Start Here
-Which file to look at first and why.

package/extensions/subagent/agents/worker.md

@@ -1,24 +0,0 @@
----
-name: worker
-description: General-purpose subagent with full capabilities, isolated context
-model: claude-sonnet-4-5
----
-
-You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
-
-Work autonomously to complete the assigned task. Use all available tools as needed.
-
-Output format when finished:
-
-## Completed
-What was done.
-
-## Files Changed
-- `path/to/file.ts` - what changed
-
-## Notes (if any)
-Anything the main agent should know.
-
-If handing off to another agent (e.g. reviewer), include:
-- Exact file paths changed
-- Key functions/types touched (short list)

package/extensions/subagent/prompts/implement-and-review.md

@@ -1,10 +0,0 @@
----
-description: Worker implements, reviewer reviews, worker applies feedback
----
-Use the subagent tool with the chain parameter to execute this workflow:
-
-1. First, use the "worker" agent to implement: $@
-2. Then, use the "reviewer" agent to review the implementation from the previous step (use {previous} placeholder)
-3. Finally, use the "worker" agent to apply the feedback from the review (use {previous} placeholder)
-
-Execute this as a chain, passing output between steps via {previous}.

package/extensions/subagent/prompts/implement.md

@@ -1,10 +0,0 @@
----
-description: Full implementation workflow - scout gathers context, planner creates plan, worker implements
----
-Use the subagent tool with the chain parameter to execute this workflow:
-
-1. First, use the "scout" agent to find all code relevant to: $@
-2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
-3. Finally, use the "worker" agent to implement the plan from the previous step (use {previous} placeholder)
-
-Execute this as a chain, passing output between steps via {previous}.

package/extensions/subagent/prompts/scout-and-plan.md

@@ -1,9 +0,0 @@
----
-description: Scout gathers context, planner creates implementation plan (no implementation)
----
-Use the subagent tool with the chain parameter to execute this workflow:
-
-1. First, use the "scout" agent to find all code relevant to: $@
-2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
-
-Execute this as a chain, passing output between steps via {previous}. Do NOT implement - just return the plan.