pi-code 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,16 @@
 # pi-code
 
+[![npm](https://img.shields.io/npm/v/pi-code)](https://www.npmjs.com/package/pi-code)
+[![npm](https://img.shields.io/npm/dt/pi-code)](https://www.npmjs.com/package/pi-code)
+[![GitHub](https://img.shields.io/github/license/ilovepixelart/pi-code)](https://github.com/ilovepixelart/pi-code/blob/main/LICENSE)
+\
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ilovepixelart_pi-code&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ilovepixelart_pi-code)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ilovepixelart_pi-code&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ilovepixelart_pi-code)
+\
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=ilovepixelart_pi-code&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=ilovepixelart_pi-code)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=ilovepixelart_pi-code&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=ilovepixelart_pi-code)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=ilovepixelart_pi-code&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=ilovepixelart_pi-code)
+
 Claude Code experience for the [pi](https://pi.dev) coding agent, in one package. Point pi at a project that already has a `.claude/` directory and it reads your existing config: rules, commands, skills, hooks, output styles, MCP servers, and agents. It also adds the Claude Code features pi lacks: a todo overlay, checkpoints, memory, web search, and subagents.
 
 ![pi-code demo](demos/hero.gif)
@@ -7,12 +18,18 @@ Claude Code experience for the [pi](https://pi.dev) coding agent, in one package
 ## Install
 
 ```bash
-pi install pi-code                       # from npm (when published)
+pi install npm:pi-code       # from npm
+pi install -l npm:pi-code    # project-local instead, writes .pi/settings.json
+```
+
+Other sources:
+
+```bash
 pi install git:github.com/ilovepixelart/pi-code
-pi install ~/Documents/pi-code           # local path, then /reload after edits
+pi install ./pi-code         # local checkout, then /reload after edits
 ```
 
-One `pi install`, everything below loads. Each feature is an extension under [`extensions/`](extensions).
+One `pi install` and everything below loads on the next start. `pi list` shows what is installed, `pi config` toggles individual resources, and `pi update pi-code` upgrades it. Each feature is an extension under [`extensions/`](extensions).
 
 ## What it does
 
@@ -24,8 +41,8 @@ One `pi install`, everything below loads. Each feature is an extension under [`e
 | Hooks | `.claude/settings.json` hooks on pi lifecycle events | `hooks.ts` |
 | Output styles | `.claude/output-styles` + active `outputStyle`, `/output-style` switcher | `output-styles.ts` |
 | CLAUDE.md `@imports` | resolves `@path` imports pi's native loader skips | `context-imports.ts` |
-| MCP servers | `.mcp.json`, `~/.claude.json`, `.pi/mcp.json`; stdio + HTTP | `mcp.ts` |
-| Subagents / Task | `~/.claude/agents` + project `.claude/agents`, background runs | `subagent/` |
+| MCP servers | `~/.claude.json`, `~/.pi/agent/mcp.json`, `.mcp.json`, `.pi/mcp.json` (later wins); stdio, HTTP, SSE | `mcp.ts` |
+| Subagents / Task | `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents`; background runs | `subagent/` |
 | Plan mode | `plan_mode_complete` tool, exact tool snapshot/restore | `plan-mode/` |
 | Todo list | persistent overlay, status machine, compaction-safe | `todo.ts` |
 | Checkpoints / rewind | shadow-repo snapshots, hard-reset restore | `git-checkpoint.ts` |
@@ -37,7 +54,7 @@ One `pi install`, everything below loads. Each feature is an extension under [`e
 
 `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.
 
-Vendored bases (`question`, `notify`, `status-line`) come from pi's MIT example extensions (see [LICENSE](LICENSE)). Personal config lives in [dot-pi](https://github.com/ilovepixelart/dot-pi) (`~/.pi/agent`).
+Vendored bases (`question`, `notify`, `status-line`) come from pi's MIT example extensions (see [LICENSE](LICENSE)).
 
 ## Development
 
@@ -48,4 +65,4 @@ scripts/e2e.sh          # drives the real pi TUI via tmux (needs a working model
 scripts/record-demos.sh # re-records demos/*.tape with vhs at low thinking
 ```
 
-Extensions live in `extensions/`, tests in `tests/`. Install locally with `pi install ~/Documents/pi-code`, then `/reload` after edits.
+Extensions live in `extensions/`, tests in `tests/`. Install a local checkout with `pi install ./pi-code`, then `/reload` after edits.

package/extensions/claude-rules.ts

@@ -42,10 +42,14 @@ function parsePaths(frontmatter: string): string[] {
   const inline = lines[index].replace(/^\s*paths\s*:/, '').trim()
   if (inline) return splitInline(inline)
   const items: string[] = []
+  // Matched with string ops rather than a regex: the equivalent pattern needs two
+  // adjacent whitespace quantifiers, which backtracks super-linearly on long lines.
   for (let i = index + 1; i < lines.length; i++) {
-    const match = /^\s*-\s*(.+)$/.exec(lines[i])
-    if (!match) break
-    items.push(unquote(match[1].trim()))
+    const entry = lines[i].trimStart()
+    if (!entry.startsWith('-')) break
+    const value = entry.slice(1).trim()
+    if (!value) break
+    items.push(unquote(value))
   }
   return items
 }

package/extensions/context-imports.ts

@@ -54,6 +54,41 @@ export interface ImportedFile {
   body: string
 }
 
+/** The `@path` targets of a context file, in document order, skipping fenced code blocks. */
+function importTargets(content: string): string[] {
+  const targets: string[] = []
+  let inFence = false
+  for (const line of content.split('\n')) {
+    if (line.trimStart().startsWith('```')) {
+      inFence = !inFence
+      continue
+    }
+    if (inFence) continue
+    for (const match of line.matchAll(/(^|\s)@(\S+)/g)) targets.push(match[2])
+  }
+  return targets
+}
+
+/** Read one `@path` target, or null when it is unresolvable, already seen, outside `allowedRoots`, or unreadable. */
+function readImport(target: string, fromDir: string, home: string, allowedRoots: string[], seen: Set<string>): { real: string; body: string } | null {
+  const resolved = path.resolve(fromDir, expandHome(target, home))
+  let real: string
+  try {
+    real = fs.realpathSync(resolved)
+  } catch {
+    return null
+  }
+  if (seen.has(real)) return null
+  seen.add(real)
+  if (!isUnder(real, allowedRoots)) return null
+  try {
+    // real may be a directory (EISDIR) or vanish after the realpath (ENOENT/EACCES).
+    return { real, body: fs.readFileSync(real, 'utf-8') }
+  } catch {
+    return null
+  }
+}
+
 /**
  * Collect the contents of every file transitively imported via `@path`, in
  * discovery order. Imports are resolved through symlinks and kept within
@@ -62,38 +97,29 @@ export interface ImportedFile {
 export function collectImports(content: string, fromDir: string, home: string, allowedRoots: string[], seen: Set<string>, depth = 0): ImportedFile[] {
   if (depth >= MAX_IMPORT_DEPTH) return []
   const out: ImportedFile[] = []
-  let inFence = false
-  for (const line of content.split('\n')) {
-    if (line.trimStart().startsWith('```')) {
-      inFence = !inFence
-      continue
-    }
-    if (inFence) continue
-    for (const match of line.matchAll(/(^|\s)@(\S+)/g)) {
-      const resolved = path.resolve(fromDir, expandHome(match[2], home))
-      let real: string
-      try {
-        real = fs.realpathSync(resolved)
-      } catch {
-        continue
-      }
-      if (seen.has(real)) continue
-      seen.add(real)
-      if (!isUnder(real, allowedRoots)) continue
-      let body: string
-      try {
-        // real may be a directory (EISDIR) or vanish after the realpath (ENOENT/EACCES).
-        body = fs.readFileSync(real, 'utf-8')
-      } catch {
-        continue
-      }
-      out.push({ path: real, body: body.trim() })
-      out.push(...collectImports(body, path.dirname(real), home, allowedRoots, seen, depth + 1))
-    }
+  for (const target of importTargets(content)) {
+    const file = readImport(target, fromDir, home, allowedRoots, seen)
+    if (!file) continue
+    out.push({ path: file.real, body: file.body.trim() }, ...collectImports(file.body, path.dirname(file.real), home, allowedRoots, seen, depth + 1))
   }
   return out
 }
 
+/**
+ * Roots an importing file may pull from.
+ *
+ * A context file under the user's own config may reach the whole config; a project
+ * file may not. `~/.claude` holds `.credentials.json`, global settings and every
+ * project's transcripts, so granting those roots to a cloned repo's `CLAUDE.md`
+ * would let it read them into the system prompt.
+ */
+export function rootsForImporter(importer: string, home: string, cwd: string): string[] {
+  const userRoots = realRoots([path.join(home, '.claude'), path.join(home, '.pi')])
+  const [real] = realRoots([importer])
+  const fromUserConfig = real !== undefined && isUnder(real, userRoots)
+  return fromUserConfig ? realRoots([cwd, ...userRoots]) : realRoots([cwd])
+}
+
 export default function contextImportsExtension(pi: ExtensionAPI) {
   pi.on('before_agent_start', async (event) => {
     const contextFiles: Array<{ path: string; content: string }> = event.systemPromptOptions?.contextFiles ?? []
@@ -101,13 +127,14 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
 
     const home = os.homedir()
     const cwd = event.systemPromptOptions?.cwd ?? process.cwd()
-    const allowedRoots = realRoots([cwd, path.join(home, '.claude'), path.join(home, '.pi')])
     // Seed with the loaded context file paths so pi's own files are never re-imported.
     const seen = realRoots(contextFiles.map((file) => file.path))
     const seenSet = new Set(seen)
 
     const imported: ImportedFile[] = []
     for (const file of contextFiles) {
+      // Roots are scoped per importing file: a project file never reaches user config.
+      const allowedRoots = rootsForImporter(file.path, home, cwd)
       imported.push(...collectImports(file.content, path.dirname(file.path), home, allowedRoots, seenSet))
     }
     if (imported.length === 0) return

package/extensions/git-checkpoint.ts

@@ -65,7 +65,21 @@ function checkpointLabel(checkpoint: Checkpoint, index: number): string {
   return `${index + 1}. ${time}  ${checkpoint.prompt || '(empty prompt)'}${marker}`
 }
 
-export default function (pi: ExtensionAPI) {
+async function restoreConversation(ctx: ExtensionCommandContext, entryId: string): Promise<boolean> {
+  try {
+    // navigateTree's published type omits editorText, but it is present at runtime (docs/extensions.md)
+    const result = (await ctx.navigateTree(entryId, { summarize: false })) as { cancelled: boolean; editorText?: string }
+    if (result.cancelled) return false
+    if (typeof result.editorText === 'string') ctx.ui.setEditorText(result.editorText)
+    return true
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    ctx.ui.notify(`Conversation restore failed: ${message}`, 'error')
+    return false
+  }
+}
+
+export default function gitCheckpointExtension(pi: ExtensionAPI) {
   const checkpoints = new Map<string, Checkpoint>()
   let pending: { ref: string; createdAt: string } | undefined
   let shadowDir: string | undefined
@@ -117,20 +131,6 @@ export default function (pi: ExtensionAPI) {
     return true
   }
 
-  async function restoreConversation(ctx: ExtensionCommandContext, entryId: string): Promise<boolean> {
-    try {
-      // navigateTree's published type omits editorText, but it is present at runtime (docs/extensions.md)
-      const result = (await ctx.navigateTree(entryId, { summarize: false })) as { cancelled: boolean; editorText?: string }
-      if (result.cancelled) return false
-      if (typeof result.editorText === 'string') ctx.ui.setEditorText(result.editorText)
-      return true
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      ctx.ui.notify(`Conversation restore failed: ${message}`, 'error')
-      return false
-    }
-  }
-
   async function runRestoreMode(ctx: ExtensionCommandContext, checkpoint: Checkpoint): Promise<void> {
     const mode = await ctx.ui.select('Restore mode:', [...RESTORE_MODES])
     if (!mode) return
@@ -178,7 +178,7 @@ export default function (pi: ExtensionAPI) {
         ctx.ui.notify('No checkpoints recorded yet', 'info')
         return
       }
-      const labels = ordered.map(checkpointLabel)
+      const labels = ordered.map((checkpoint, index) => checkpointLabel(checkpoint, index))
       const choice = await ctx.ui.select('Rewind to checkpoint:', labels)
       if (!choice) return
       const checkpoint = ordered[labels.indexOf(choice)]

package/extensions/hooks.ts

@@ -112,7 +112,8 @@ export function interpretHookResult(code: number, stdout: string, stderr: string
 
 export const runHookCommand: HookRunner = (command, payload, timeoutMs) =>
   new Promise((resolve) => {
-    const child = spawn('sh', ['-c', command], { stdio: ['pipe', 'pipe', 'pipe'] })
+    // Absolute path so the shell can't be resolved through an attacker-controlled PATH.
+    const child = spawn('/bin/sh', ['-c', command], { stdio: ['pipe', 'pipe', 'pipe'] })
     let stdout = ''
     let stderr = ''
     const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs)

package/extensions/mcp.ts

@@ -18,16 +18,22 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { Client } from '@modelcontextprotocol/sdk/client/index.js'
-import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.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.
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js' // NOSONAR
+import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
 import { Type } from 'typebox'
 
 const CONNECT_TIMEOUT_MS = 10_000
 const CALL_TIMEOUT_MS = 120_000
 const MAX_INLINE_RESULT = 50_000
-// pi's built-in tool names must never be shadowed by an MCP tool
-const RESERVED_NAMES = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls', 'mcp'])
+// Tool names an MCP server must never take over. formatToolName always emits
+// `<server>_<tool>`, so only names containing an underscore are actually reachable:
+// pi's own built-ins (read, bash, edit, ...) cannot be produced and are not listed.
+// These are pi-code's own tools, and mcp.ts registers before the extensions owning
+// them, so without this guard a server named `web` would replace the SSRF-checked fetch.
+const RESERVED_NAMES = new Set(['web_fetch', 'web_search', 'plan_mode_complete'])
 
 export interface StdioServerConfig {
   command: string
@@ -82,7 +88,7 @@ export function loadConfigFrom(files: string[]): Record<string, ServerConfig> {
 }
 
 export function formatToolName(server: string, tool: string): string {
-  return `${server}_${tool}`.replace(/-/g, '_')
+  return `${server}_${tool}`.replaceAll('-', '_')
 }
 
 export function normalizeSchema(schema: unknown): object {
@@ -143,7 +149,10 @@ async function withTimeout<T>(promise: Promise<T>, ms: number, label: string): P
 async function connect(name: string, config: ServerConfig): Promise<Client> {
   const client = new Client({ name: 'pi-code-mcp', version: '0.1.0' })
   if (isStdio(config)) {
-    const env: Record<string, string> = { ...(process.env as Record<string, string>) }
+    // Start from the SDK's allowlist (PATH, HOME, SHELL, ...) rather than the whole
+    // process env: a server should not receive ANTHROPIC_API_KEY or GITHUB_TOKEN just
+    // for being launched. A server that needs a variable names it in its own env block.
+    const env: Record<string, string> = { ...getDefaultEnvironment() }
     for (const [key, value] of Object.entries(config.env ?? {})) env[key] = interpolateEnv(value)
     const transport = new StdioClientTransport({
       command: config.command,
@@ -167,7 +176,7 @@ async function connect(name: string, config: ServerConfig): Promise<Client> {
   } catch (error) {
     if (String(error).includes('Unauthorized')) throw error
     const fallback = new Client({ name: 'pi-code-mcp', version: '0.1.0' })
-    const transport = new SSEClientTransport(url, { requestInit: { headers } })
+    const transport = new SSEClientTransport(url, { requestInit: { headers } }) // NOSONAR: deliberate legacy fallback
     await withTimeout(fallback.connect(transport), CONNECT_TIMEOUT_MS, `connect ${name} (sse)`)
     return fallback
   }
@@ -229,11 +238,16 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     }
   }
 
-  // User config is the user's own, so connect it eagerly.
-  await connectServers(loadConfigFrom(userConfigPaths(os.homedir())))
-
+  let userConnected = false
   let projectConnected = false
+
   pi.on('session_start', async (_event, ctx) => {
+    // Connecting spawns processes and opens sockets, so it belongs here rather than in
+    // the factory: pi runs the factory for invocations that never start a session.
+    if (!userConnected) {
+      userConnected = true
+      await connectServers(loadConfigFrom(userConfigPaths(os.homedir())))
+    }
     // A project .mcp.json can run arbitrary commands on connect, so only honor it once the project is trusted.
     if (!projectConnected && ctx.isProjectTrusted?.()) {
       projectConnected = true

package/extensions/memory.ts

@@ -11,7 +11,7 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import { StringEnum } from '@earendil-works/pi-ai'
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type ExtensionAPI, formatSize, truncateHead } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
 
 const INDEX_FILE = 'MEMORY.md'
@@ -28,8 +28,8 @@ export function slugifyName(name: string): string {
   return (
     name
       .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '')
+      .replaceAll(/[^a-z0-9]+/g, '-')
+      .replaceAll(/^-|-$/g, '')
       .slice(0, 64) || 'memory'
   )
 }
@@ -63,6 +63,17 @@ function readIndex(dir: string): string {
   }
 }
 
+/**
+ * Keep a memory inside pi's context budget. truncateHead keeps whole lines, so a
+ * single oversized line yields nothing; fall back to a hard slice in that case.
+ */
+function capForContext(body: string): string {
+  const cut = truncateHead(body, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES })
+  if (!cut.truncated) return body
+  const kept = cut.content || body.slice(0, DEFAULT_MAX_BYTES)
+  return `${kept}\n\n[truncated: ${formatSize(cut.totalBytes)} total]`
+}
+
 export default function memoryExtension(pi: ExtensionAPI) {
   let dir = memoryDir(process.cwd())
 
@@ -105,7 +116,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
         if (!name) return { content: [{ type: 'text' as const, text: 'read requires name.' }], details: {} }
         try {
           const body = fs.readFileSync(path.join(dir, `${name}.md`), 'utf-8')
-          return { content: [{ type: 'text' as const, text: body }], details: {} }
+          return { content: [{ type: 'text' as const, text: capForContext(body) }], details: {} }
         } catch {
           return { content: [{ type: 'text' as const, text: `No memory named ${name}.` }], details: {} }
         }

package/extensions/notify.ts

@@ -30,9 +30,11 @@ function notifyOSC99(title: string, body: string): void {
 
 function notifyWindows(title: string, body: string): void {
   const { execFile } = require('node:child_process')
-  // The callback captures a spawn failure (e.g. powershell.exe missing) instead of
-  // letting an unhandled 'error' event crash the host process.
-  execFile('powershell.exe', ['-NoProfile', '-Command', windowsToastScript(title, body)], () => {})
+  // Resolve powershell from a fixed system path rather than through PATH, and let the callback
+  // capture a spawn failure instead of an unhandled 'error' event crashing the host.
+  const root = process.env.SystemRoot ?? String.raw`C:\Windows`
+  const powershell = String.raw`${root}\System32\WindowsPowerShell\v1.0\powershell.exe`
+  execFile(powershell, ['-NoProfile', '-Command', windowsToastScript(title, body)], () => {})
 }
 
 function notify(title: string, body: string): void {
@@ -45,7 +47,7 @@ function notify(title: string, body: string): void {
   }
 }
 
-export default function (pi: ExtensionAPI) {
+export default function notifyExtension(pi: ExtensionAPI) {
   pi.on('agent_end', async () => {
     notify('Pi', 'Ready for input')
   })

package/extensions/output-styles.ts

@@ -26,7 +26,7 @@ export interface OutputStyle {
 }
 
 function field(frontmatter: string, key: string): string {
-  const match = new RegExp(`^\\s*${key}\\s*:\\s*(.+)$`, 'm').exec(frontmatter)
+  const match = new RegExp(String.raw`^\s*${key}\s*:\s*(.+)$`, 'm').exec(frontmatter)
   return match ? match[1].trim().replace(/^["']|["']$/g, '') : ''
 }
 

package/extensions/plan-mode/index.ts

@@ -14,7 +14,7 @@
 
 import type { AgentMessage } from '@earendil-works/pi-agent-core'
 import type { AssistantMessage, TextContent } from '@earendil-works/pi-ai'
-import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from '@earendil-works/pi-coding-agent'
 import { Key } from '@earendil-works/pi-tui'
 import { Type } from 'typebox'
 import { extractTodoItems, isSafeCommand, markCompletedSteps, planToTodos, type TodoItem } from './utils.js'
@@ -35,6 +35,23 @@ function getTextContent(message: AssistantMessage): string {
     .join('\n')
 }
 
+// Last element matching the predicate (the lib target predates Array.prototype.findLast)
+function findLast<T>(items: T[], match: (item: T) => boolean): T | undefined {
+  for (let i = items.length - 1; i >= 0; i--) {
+    if (match(items[i])) return items[i]
+  }
+  return undefined
+}
+
+// Index of the last plan-mode-execute entry, or -1 when the current run never started one
+function findLastExecuteIndex(entries: SessionEntry[]): number {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i] as { customType?: string }
+    if (entry.customType === 'plan-mode-execute') return i
+  }
+  return -1
+}
+
 export default function planModeExtension(pi: ExtensionAPI): void {
   let planModeEnabled = false
   let executionMode = false
@@ -108,6 +125,62 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     })
   }
 
+  // Announce completion and reset once every step is done
+  function finalizeCompletedExecution(ctx: ExtensionContext): void {
+    if (!todoItems.every((t) => t.completed)) return
+    const completedList = todoItems.map((t) => `~~${t.text}~~`).join('\n')
+    pi.sendMessage({ customType: 'plan-complete', content: `**Plan Complete!** ✓\n\n${completedList}`, display: true }, { triggerTurn: false })
+    executionMode = false
+    todoItems = []
+    restoreTools()
+    updateStatus(ctx)
+    persistState() // Save cleared state so resume doesn't restore old execution mode
+  }
+
+  // Fall back to extracting a plan from the last assistant message's prose
+  function deriveTodosFromProse(messages: AgentMessage[]): void {
+    const lastAssistant = [...messages].reverse().find(isAssistantMessage)
+    if (!lastAssistant) return
+    const extracted = extractTodoItems(getTextContent(lastAssistant))
+    if (extracted.length > 0) {
+      todoItems = extracted
+    }
+  }
+
+  // Ask the user how to proceed after a plan is ready
+  async function promptPlanNextAction(ctx: ExtensionContext): Promise<void> {
+    const choice = await ctx.ui.select('Plan mode - what next?', [todoItems.length > 0 ? 'Execute the plan (track progress)' : 'Execute the plan', 'Stay in plan mode', 'Refine the plan'])
+
+    if (choice?.startsWith('Execute')) {
+      planModeEnabled = false
+      executionMode = todoItems.length > 0
+      planFromTool = false
+      restoreTools()
+      updateStatus(ctx)
+
+      const execMessage = todoItems.length > 0 ? `Execute the plan. Start with: ${todoItems[0].text}` : 'Execute the plan you just created.'
+      pi.sendMessage({ customType: 'plan-mode-execute', content: execMessage, display: true }, { triggerTurn: true })
+    } else if (choice === 'Refine the plan') {
+      const refinement = await ctx.ui.editor('Refine the plan:', '')
+      if (refinement?.trim()) {
+        pi.sendUserMessage(refinement.trim())
+      }
+    }
+  }
+
+  // Rebuild completion state from assistant messages after the last execute marker
+  function rescanCompletion(entries: SessionEntry[]): void {
+    const executeIndex = findLastExecuteIndex(entries)
+    const messages: AssistantMessage[] = []
+    for (let i = executeIndex + 1; i < entries.length; i++) {
+      const entry = entries[i]
+      if (entry.type === 'message' && 'message' in entry && isAssistantMessage(entry.message as AgentMessage)) {
+        messages.push(entry.message as AssistantMessage)
+      }
+    }
+    markCompletedSteps(messages.map(getTextContent).join('\n'), todoItems)
+  }
+
   pi.registerCommand('plan', {
     description: 'Toggle plan mode (read-only exploration)',
     handler: async (_args, ctx) => togglePlanMode(ctx),
@@ -193,7 +266,8 @@ You are in plan mode - a read-only exploration mode for safe code analysis.
 Restrictions:
 - You can only use: read, bash, grep, find, ls, question
 - You CANNOT use: edit, write (file modifications are disabled)
-- Bash is restricted to an allowlist of read-only commands
+- Bash is limited to an allowlist of read-only commands, checked per subcommand. Treat it
+  as a reminder of intent, not a sandbox: do not look for ways around it
 
 Ask clarifying questions using the question tool.
 
@@ -244,15 +318,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
   pi.on('agent_end', async (event, ctx) => {
     // Check if execution is complete
     if (executionMode && todoItems.length > 0) {
-      if (todoItems.every((t) => t.completed)) {
-        const completedList = todoItems.map((t) => `~~${t.text}~~`).join('\n')
-        pi.sendMessage({ customType: 'plan-complete', content: `**Plan Complete!** ✓\n\n${completedList}`, display: true }, { triggerTurn: false })
-        executionMode = false
-        todoItems = []
-        restoreTools()
-        updateStatus(ctx)
-        persistState() // Save cleared state so resume doesn't restore old execution mode
-      }
+      finalizeCompletedExecution(ctx)
       return
     }
 
@@ -260,13 +326,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
 
     // Prefer an explicitly submitted plan; fall back to extracting from prose
     if (!planFromTool) {
-      const lastAssistant = [...event.messages].reverse().find(isAssistantMessage)
-      if (lastAssistant) {
-        const extracted = extractTodoItems(getTextContent(lastAssistant))
-        if (extracted.length > 0) {
-          todoItems = extracted
-        }
-      }
+      deriveTodosFromProse(event.messages)
     }
 
     // Show plan steps and prompt for next action
@@ -282,23 +342,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
       )
     }
 
-    const choice = await ctx.ui.select('Plan mode - what next?', [todoItems.length > 0 ? 'Execute the plan (track progress)' : 'Execute the plan', 'Stay in plan mode', 'Refine the plan'])
-
-    if (choice?.startsWith('Execute')) {
-      planModeEnabled = false
-      executionMode = todoItems.length > 0
-      planFromTool = false
-      restoreTools()
-      updateStatus(ctx)
-
-      const execMessage = todoItems.length > 0 ? `Execute the plan. Start with: ${todoItems[0].text}` : 'Execute the plan you just created.'
-      pi.sendMessage({ customType: 'plan-mode-execute', content: execMessage, display: true }, { triggerTurn: true })
-    } else if (choice === 'Refine the plan') {
-      const refinement = await ctx.ui.editor('Refine the plan:', '')
-      if (refinement?.trim()) {
-        pi.sendUserMessage(refinement.trim())
-      }
-    }
+    await promptPlanNextAction(ctx)
   })
 
   // Restore state on session start/resume
@@ -310,7 +354,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
     const entries = ctx.sessionManager.getEntries()
 
     // Restore persisted state
-    const planModeEntry = entries.filter((e: { type: string; customType?: string }) => e.type === 'custom' && e.customType === 'plan-mode').pop() as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean } } | undefined
+    const planModeEntry = findLast(entries, (e: { type: string; customType?: string }) => e.type === 'custom' && e.customType === 'plan-mode') as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean } } | undefined
 
     if (planModeEntry?.data) {
       planModeEnabled = planModeEntry.data.enabled ?? planModeEnabled
@@ -318,30 +362,11 @@ After completing a step, include a [DONE:n] tag in your response.`,
       executionMode = planModeEntry.data.executing ?? executionMode
     }
 
-    // On resume: re-scan messages to rebuild completion state
-    // Only scan messages AFTER the last "plan-mode-execute" to avoid picking up [DONE:n] from previous plans
+    // On resume: re-scan messages after the last "plan-mode-execute" to rebuild
+    // completion state without picking up [DONE:n] from previous plans
     const isResume = planModeEntry !== undefined
     if (isResume && executionMode && todoItems.length > 0) {
-      // Find the index of the last plan-mode-execute entry (marks when current execution started)
-      let executeIndex = -1
-      for (let i = entries.length - 1; i >= 0; i--) {
-        const entry = entries[i] as { type: string; customType?: string }
-        if (entry.customType === 'plan-mode-execute') {
-          executeIndex = i
-          break
-        }
-      }
-
-      // Only scan messages after the execute marker
-      const messages: AssistantMessage[] = []
-      for (let i = executeIndex + 1; i < entries.length; i++) {
-        const entry = entries[i]
-        if (entry.type === 'message' && 'message' in entry && isAssistantMessage(entry.message as AgentMessage)) {
-          messages.push(entry.message as AssistantMessage)
-        }
-      }
-      const allText = messages.map(getTextContent).join('\n')
-      markCompletedSteps(allText, todoItems)
+      rescanCompletion(entries)
     }
 
     if (planModeEnabled) {