pi-code 0.6.0 → 0.7.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/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

@@ -92,6 +92,37 @@ 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 }
+}
+
 export function loadConfigFrom(files: string[]): Record<string, ServerConfig> {
   const servers: Record<string, ServerConfig> = {}
   for (const file of files) {
@@ -325,11 +356,27 @@ 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) {
+      const policy = projectServerPolicy(ctx.cwd, os.homedir())
+      const candidates = loadConfigFrom(projectConfigPaths(ctx.cwd))
+      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
+      }
+      if (Object.keys(consented).length > 0) await connectServers(consented)
+      if (Object.keys(gated).length === 0) projectConnected = true
+      else if (await isProjectApproved(ctx)) {
+        projectConnected = true
+        await connectServers(gated)
+      }
     }
 
     pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])

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/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

@@ -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/index.ts

@@ -24,7 +24,7 @@ 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'
@@ -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[]
@@ -1068,6 +1068,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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "0.6.0",
+  "version": "0.7.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.