pi-code 0.5.0 → 0.7.0

package/extensions/plan-mode/index.ts

@@ -17,6 +17,8 @@ import type { AssistantMessage, TextContent } from '@earendil-works/pi-ai'
 import type { ExtensionAPI, ExtensionContext, SessionEntry } from '@earendil-works/pi-coding-agent'
 import { Key } from '@earendil-works/pi-tui'
 import { Type } from 'typebox'
+
+import { PLAN_MODE_CHANNEL } from '../internal/plan-mode-state.js'
 import { extractTodoItems, isSafeCommand, markCompletedSteps, planToTodos, type TodoItem } from './utils.js'
 
 // Tools
@@ -70,6 +72,11 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     }
   }
 
+  /** Hooks report Claude's permission_mode from this bus state. */
+  function publishPlanState(): void {
+    pi.events.emit(PLAN_MODE_CHANNEL, { active: planModeEnabled })
+  }
+
   pi.registerFlag('plan', {
     description: 'Start in plan mode (read-only exploration)',
     type: 'boolean',
@@ -116,6 +123,7 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     }
     // Persist the toggle so a resume does not restore a state the user left.
     persistState()
+    publishPlanState()
     updateStatus(ctx)
   }
 
@@ -158,6 +166,7 @@ export default function planModeExtension(pi: ExtensionAPI): void {
       executionMode = todoItems.length > 0
       planFromTool = false
       restoreTools()
+      publishPlanState()
       updateStatus(ctx)
 
       // Persist before the turn: a crash before the first turn_end must resume into
@@ -377,6 +386,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
       todoItems = planModeEntry.data.todos ?? todoItems
       executionMode = planModeEntry.data.executing ?? executionMode
     }
+    publishPlanState()
 
     // On resume: re-scan messages after the last "plan-mode-execute" to rebuild
     // completion state without picking up [DONE:n] from previous plans

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

@@ -13,6 +13,7 @@
  */
 
 import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
@@ -23,7 +24,8 @@ 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'
 
@@ -137,7 +139,7 @@ interface UsageStats {
 
 interface SingleResult {
   agent: string
-  agentSource: 'user' | 'project' | 'unknown'
+  agentSource: 'user' | 'project' | 'builtin' | 'unknown'
   task: string
   exitCode: number
   messages: Message[]
@@ -256,9 +258,25 @@ interface RunAgentOptions {
   signal?: AbortSignal
   onUpdate?: OnUpdateCallback
   makeDetails: (results: SingleResult[]) => SubagentDetails
+  onPhase?: SubagentPhaseSink
 }
 
+/** Publishes a child run's start/stop for the hooks extension's SubagentStart/Stop. */
+type SubagentPhaseSink = (phase: 'start' | 'stop', agentType: string, agentId: string) => void
+
 async function runSingleAgent(options: RunAgentOptions): Promise<SingleResult> {
+  const agent = options.agents.find((a) => a.name === options.agentName)
+  if (!agent) return runSingleAgentInner(options)
+  const agentId = `fg-${randomUUID().slice(0, 8)}`
+  options.onPhase?.('start', agent.name, agentId)
+  try {
+    return await runSingleAgentInner(options)
+  } finally {
+    options.onPhase?.('stop', agent.name, agentId)
+  }
+}
+
+async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResult> {
   const { defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails } = options
   const agent = agents.find((a) => a.name === agentName)
 
@@ -478,6 +496,7 @@ interface ModeContext {
   signal: AbortSignal | undefined
   onUpdate: OnUpdateCallback | undefined
   makeDetails: MakeDetails
+  onPhase?: SubagentPhaseSink
 }
 
 async function checkProjectAgentGate(params: SubagentParamsStatic, agents: AgentConfig[], ctx: ExtensionContext, projectAgentsDir: string | null, gateMode: SubagentMode, makeDetails: MakeDetails): Promise<ToolResult | null> {
@@ -572,6 +591,7 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
   const invocation = getPiInvocation(args)
   const id = startBackgroundRun(agent.name, task, { command: invocation.command, args: invocation.args, cwd: params.cwd ?? defaultCwd }, (run) => {
     removeTmpPrompt(tmpPrompt)
+    pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id })
     const output = capForContext(run.output ?? '') || '(no output)'
     pi.sendMessage(
       {
@@ -587,6 +607,7 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
     removeTmpPrompt(tmpPrompt)
     return backgroundCapResult(makeDetails)
   }
+  pi.events.emit(SUBAGENT_CHANNEL, { phase: 'start', agentType: agent.name, agentId: id })
   return {
     content: [{ type: 'text', text: `Started background run ${id} (${agent.name}). A notification will arrive on completion; check progress with {status: true}.` }],
     details: makeDetails('single')([]),
@@ -628,6 +649,7 @@ async function runChainMode(chain: ChainStepParam[], mode: ModeContext): Promise
       signal,
       onUpdate: chainUpdate,
       makeDetails: makeDetails('chain'),
+      onPhase: mode.onPhase,
     })
     results.push(result)
 
@@ -695,6 +717,7 @@ async function runParallelMode(tasks: TaskItemParam[], mode: ModeContext): Promi
       task: t.task,
       cwd: t.cwd,
       signal,
+      onPhase: mode.onPhase,
       // Per-task update callback
       onUpdate: (partial) => {
         const live = partial.details?.results[0]
@@ -741,6 +764,7 @@ async function runSingleMode(agentName: string, task: string, cwd: string | unde
     signal,
     onUpdate,
     makeDetails: makeDetails('single'),
+    onPhase: mode.onPhase,
   })
   const isError = result.exitCode !== 0 || result.stopReason === 'error' || result.stopReason === 'aborted'
   if (isError) {
@@ -1044,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',
@@ -1109,7 +1146,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 
       if (params.background) return runBackgroundMode(params, agents, ctx.cwd, pi, makeDetails)
 
-      const mode: ModeContext = { agents, defaultCwd: ctx.cwd, signal, onUpdate, makeDetails }
+      const mode: ModeContext = { agents, defaultCwd: ctx.cwd, signal, onUpdate, makeDetails, onPhase: (phase, agentType, agentId) => pi.events.emit(SUBAGENT_CHANNEL, { phase, agentType, agentId }) }
 
       if (params.chain?.length) return runChainMode(params.chain, mode)
       if (params.tasks?.length) return runParallelMode(params.tasks, mode)

package/package.json

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