pi-code 0.1.0

package/extensions/plan-mode/utils.ts

@@ -0,0 +1,175 @@
+/**
+ * Pure utility functions for plan mode.
+ * Extracted for testability.
+ */
+
+// Destructive commands blocked in plan mode
+const DESTRUCTIVE_PATTERNS = [
+  /\brm\b/i,
+  /\brmdir\b/i,
+  /\bmv\b/i,
+  /\bcp\b/i,
+  /\bmkdir\b/i,
+  /\btouch\b/i,
+  /\bchmod\b/i,
+  /\bchown\b/i,
+  /\bchgrp\b/i,
+  /\bln\b/i,
+  /\btee\b/i,
+  /\btruncate\b/i,
+  /\bdd\b/i,
+  /\bshred\b/i,
+  /(^|[^<])>(?!>)/,
+  />>/,
+  /\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
+  /\byarn\s+(add|remove|install|publish)/i,
+  /\bpnpm\s+(add|remove|install|publish)/i,
+  /\bpip\s+(install|uninstall)/i,
+  /\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
+  /\bbrew\s+(install|uninstall|upgrade)/i,
+  /\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+  /\bsudo\b/i,
+  /\bsu\b/i,
+  /\bkill\b/i,
+  /\bpkill\b/i,
+  /\bkillall\b/i,
+  /\breboot\b/i,
+  /\bshutdown\b/i,
+  /\bsystemctl\s+(start|stop|restart|enable|disable)/i,
+  /\bservice\s+\S+\s+(start|stop|restart)/i,
+  /\b(vim?|nano|emacs|code|subl)\b/i,
+]
+
+// Safe read-only commands allowed in plan mode
+const SAFE_PATTERNS = [
+  /^\s*cat\b/,
+  /^\s*head\b/,
+  /^\s*tail\b/,
+  /^\s*less\b/,
+  /^\s*more\b/,
+  /^\s*grep\b/,
+  /^\s*find\b/,
+  /^\s*ls\b/,
+  /^\s*pwd\b/,
+  /^\s*echo\b/,
+  /^\s*printf\b/,
+  /^\s*wc\b/,
+  /^\s*sort\b/,
+  /^\s*uniq\b/,
+  /^\s*diff\b/,
+  /^\s*file\b/,
+  /^\s*stat\b/,
+  /^\s*du\b/,
+  /^\s*df\b/,
+  /^\s*tree\b/,
+  /^\s*which\b/,
+  /^\s*whereis\b/,
+  /^\s*type\b/,
+  /^\s*env\b/,
+  /^\s*printenv\b/,
+  /^\s*uname\b/,
+  /^\s*whoami\b/,
+  /^\s*id\b/,
+  /^\s*date\b/,
+  /^\s*cal\b/,
+  /^\s*uptime\b/,
+  /^\s*ps\b/,
+  /^\s*top\b/,
+  /^\s*htop\b/,
+  /^\s*free\b/,
+  /^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
+  /^\s*git\s+ls-/i,
+  /^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
+  /^\s*yarn\s+(list|info|why|audit)/i,
+  /^\s*node\s+--version/i,
+  /^\s*python\s+--version/i,
+  /^\s*curl\s/i,
+  /^\s*wget\s+-O\s*-/i,
+  /^\s*jq\b/,
+  /^\s*sed\s+-n/i,
+  /^\s*awk\b/,
+  /^\s*rg\b/,
+  /^\s*fd\b/,
+  /^\s*bat\b/,
+  /^\s*eza\b/,
+]
+
+export function isSafeCommand(command: string): boolean {
+  const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(command))
+  const isSafe = SAFE_PATTERNS.some((p) => p.test(command))
+  return !isDestructive && isSafe
+}
+
+export interface TodoItem {
+  step: number
+  text: string
+  completed: boolean
+}
+
+export function cleanStepText(text: string): string {
+  let cleaned = text
+    .replace(/\*{1,2}([^*]+)\*{1,2}/g, '$1') // Remove bold/italic
+    .replace(/`([^`]+)`/g, '$1') // Remove code
+    .replace(/^(Use|Run|Execute|Create|Write|Read|Check|Verify|Update|Modify|Add|Remove|Delete|Install)\s+(the\s+)?/i, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+
+  if (cleaned.length > 0) {
+    cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1)
+  }
+  if (cleaned.length > 50) {
+    cleaned = `${cleaned.slice(0, 47)}...`
+  }
+  return cleaned
+}
+
+export function extractTodoItems(message: string): TodoItem[] {
+  const items: TodoItem[] = []
+  const headerMatch = message.match(/\*{0,2}Plan:\*{0,2}\s*\n/i)
+  if (!headerMatch) return items
+
+  const planSection = message.slice(message.indexOf(headerMatch[0]) + headerMatch[0].length)
+  const numberedPattern = /^\s*(\d+)[.)]\s+\*{0,2}([^*\n]+)/gm
+
+  for (const match of planSection.matchAll(numberedPattern)) {
+    const text = match[2]
+      .trim()
+      .replace(/\*{1,2}$/, '')
+      .trim()
+    if (text.length > 5 && !text.startsWith('`') && !text.startsWith('/') && !text.startsWith('-')) {
+      const cleaned = cleanStepText(text)
+      if (cleaned.length > 3) {
+        items.push({ step: items.length + 1, text: cleaned, completed: false })
+      }
+    }
+  }
+  return items
+}
+
+export function extractDoneSteps(message: string): number[] {
+  const steps: number[] = []
+  for (const match of message.matchAll(/\[DONE:(\d+)\]/gi)) {
+    const step = Number(match[1])
+    if (Number.isFinite(step)) steps.push(step)
+  }
+  return steps
+}
+
+export function markCompletedSteps(text: string, items: TodoItem[]): number {
+  const doneSteps = extractDoneSteps(text)
+  for (const step of doneSteps) {
+    const item = items.find((t) => t.step === step)
+    if (item) item.completed = true
+  }
+  return doneSteps.length
+}
+
+/**
+ * Parse an explicitly submitted plan (from the plan_mode_complete tool) into
+ * todo items. Unlike extractTodoItems, the Plan: header is optional because
+ * the tool input is already known to be the plan itself.
+ */
+export function planToTodos(plan: string): TodoItem[] {
+  const withHeader = /\*{0,2}Plan:\*{0,2}\s*\n/i.test(plan) ? plan : `Plan:\n${plan}`
+  return extractTodoItems(withHeader)
+}

package/extensions/question.ts

@@ -0,0 +1,258 @@
+/**
+ * Question Tool - Single question with options
+ * Full custom UI: options list + inline editor for "Type something..."
+ * Escape in editor returns to options, Escape in options cancels
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from '@earendil-works/pi-tui'
+import { Type } from 'typebox'
+
+interface OptionWithDesc {
+  label: string
+  description?: string
+}
+
+type DisplayOption = OptionWithDesc & { isOther?: boolean }
+
+interface QuestionDetails {
+  question: string
+  options: string[]
+  answer: string | null
+  wasCustom?: boolean
+}
+
+// Options with labels and optional descriptions
+const OptionSchema = Type.Object({
+  label: Type.String({ description: 'Display label for the option' }),
+  description: Type.Optional(Type.String({ description: 'Optional description shown below label' })),
+})
+
+const QuestionParams = Type.Object({
+  question: Type.String({ description: 'The question to ask the user' }),
+  options: Type.Array(OptionSchema, { description: 'Options for the user to choose from' }),
+})
+
+export default function question(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: 'question',
+    label: 'Question',
+    description: 'Ask the user a question and let them pick from options. Use when you need user input to proceed.',
+    parameters: QuestionParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (!ctx.hasUI) {
+        return {
+          content: [{ type: 'text', text: 'Error: UI not available (running in non-interactive mode)' }],
+          details: {
+            question: params.question,
+            options: params.options.map((o) => o.label),
+            answer: null,
+          } as QuestionDetails,
+        }
+      }
+
+      if (params.options.length === 0) {
+        return {
+          content: [{ type: 'text', text: 'Error: No options provided' }],
+          details: { question: params.question, options: [], answer: null } as QuestionDetails,
+        }
+      }
+
+      const allOptions: DisplayOption[] = [...params.options, { label: 'Type something.', isOther: true }]
+
+      const result = await ctx.ui.custom<{ answer: string; wasCustom: boolean; index?: number } | null>((tui, theme, _kb, done) => {
+        let optionIndex = 0
+        let editMode = false
+        let cachedLines: string[] | undefined
+
+        const editorTheme: EditorTheme = {
+          borderColor: (s) => theme.fg('accent', s),
+          selectList: {
+            selectedPrefix: (t) => theme.fg('accent', t),
+            selectedText: (t) => theme.fg('accent', t),
+            description: (t) => theme.fg('muted', t),
+            scrollInfo: (t) => theme.fg('dim', t),
+            noMatch: (t) => theme.fg('warning', t),
+          },
+        }
+        const editor = new Editor(tui, editorTheme)
+
+        editor.onSubmit = (value) => {
+          const trimmed = value.trim()
+          if (trimmed) {
+            done({ answer: trimmed, wasCustom: true })
+          } else {
+            editMode = false
+            editor.setText('')
+            refresh()
+          }
+        }
+
+        function refresh() {
+          cachedLines = undefined
+          tui.requestRender()
+        }
+
+        function handleInput(data: string) {
+          if (editMode) {
+            if (matchesKey(data, Key.escape)) {
+              editMode = false
+              editor.setText('')
+              refresh()
+              return
+            }
+            editor.handleInput(data)
+            refresh()
+            return
+          }
+
+          if (matchesKey(data, Key.up)) {
+            optionIndex = Math.max(0, optionIndex - 1)
+            refresh()
+            return
+          }
+          if (matchesKey(data, Key.down)) {
+            optionIndex = Math.min(allOptions.length - 1, optionIndex + 1)
+            refresh()
+            return
+          }
+
+          if (matchesKey(data, Key.enter)) {
+            const selected = allOptions[optionIndex]
+            if (selected.isOther) {
+              editMode = true
+              refresh()
+            } else {
+              done({ answer: selected.label, wasCustom: false, index: optionIndex + 1 })
+            }
+            return
+          }
+
+          if (matchesKey(data, Key.escape)) {
+            done(null)
+          }
+        }
+
+        function render(width: number): string[] {
+          if (cachedLines) return cachedLines
+
+          const lines: string[] = []
+          const add = (s: string) => lines.push(truncateToWidth(s, width))
+
+          add(theme.fg('accent', '─'.repeat(width)))
+          add(theme.fg('text', ` ${params.question}`))
+          lines.push('')
+
+          for (let i = 0; i < allOptions.length; i++) {
+            const opt = allOptions[i]
+            const selected = i === optionIndex
+            const isOther = opt.isOther === true
+            const prefix = selected ? theme.fg('accent', '> ') : '  '
+
+            if (isOther && editMode) {
+              add(prefix + theme.fg('accent', `${i + 1}. ${opt.label} ✎`))
+            } else if (selected) {
+              add(prefix + theme.fg('accent', `${i + 1}. ${opt.label}`))
+            } else {
+              add(`  ${theme.fg('text', `${i + 1}. ${opt.label}`)}`)
+            }
+
+            // Show description if present
+            if (opt.description) {
+              add(`     ${theme.fg('muted', opt.description)}`)
+            }
+          }
+
+          if (editMode) {
+            lines.push('')
+            add(theme.fg('muted', ' Your answer:'))
+            for (const line of editor.render(width - 2)) {
+              add(` ${line}`)
+            }
+          }
+
+          lines.push('')
+          if (editMode) {
+            add(theme.fg('dim', ' Enter to submit • Esc to go back'))
+          } else {
+            add(theme.fg('dim', ' ↑↓ navigate • Enter to select • Esc to cancel'))
+          }
+          add(theme.fg('accent', '─'.repeat(width)))
+
+          cachedLines = lines
+          return lines
+        }
+
+        return {
+          render,
+          invalidate: () => {
+            cachedLines = undefined
+          },
+          handleInput,
+        }
+      })
+
+      // Build simple options list for details
+      const simpleOptions = params.options.map((o) => o.label)
+
+      if (!result) {
+        return {
+          content: [{ type: 'text', text: 'User cancelled the selection' }],
+          details: { question: params.question, options: simpleOptions, answer: null } as QuestionDetails,
+        }
+      }
+
+      if (result.wasCustom) {
+        return {
+          content: [{ type: 'text', text: `User wrote: ${result.answer}` }],
+          details: {
+            question: params.question,
+            options: simpleOptions,
+            answer: result.answer,
+            wasCustom: true,
+          } as QuestionDetails,
+        }
+      }
+      return {
+        content: [{ type: 'text', text: `User selected: ${result.index}. ${result.answer}` }],
+        details: {
+          question: params.question,
+          options: simpleOptions,
+          answer: result.answer,
+          wasCustom: false,
+        } as QuestionDetails,
+      }
+    },
+
+    renderCall(args, theme, _context) {
+      let text = theme.fg('toolTitle', theme.bold('question ')) + theme.fg('muted', args.question)
+      const opts = Array.isArray(args.options) ? args.options : []
+      if (opts.length) {
+        const labels = opts.map((o: OptionWithDesc) => o.label)
+        const numbered = [...labels, 'Type something.'].map((o, i) => `${i + 1}. ${o}`)
+        text += `\n${theme.fg('dim', `  Options: ${numbered.join(', ')}`)}`
+      }
+      return new Text(text, 0, 0)
+    },
+
+    renderResult(result, _options, theme, _context) {
+      const details = result.details as QuestionDetails | undefined
+      if (!details) {
+        const text = result.content[0]
+        return new Text(text?.type === 'text' ? text.text : '', 0, 0)
+      }
+
+      if (details.answer === null) {
+        return new Text(theme.fg('warning', 'Cancelled'), 0, 0)
+      }
+
+      if (details.wasCustom) {
+        return new Text(theme.fg('success', '✓ ') + theme.fg('muted', '(wrote) ') + theme.fg('accent', details.answer), 0, 0)
+      }
+      const idx = details.options.indexOf(details.answer) + 1
+      const display = idx > 0 ? `${idx}. ${details.answer}` : details.answer
+      return new Text(theme.fg('success', '✓ ') + theme.fg('accent', display), 0, 0)
+    },
+  })
+}

package/extensions/skills.ts

@@ -0,0 +1,41 @@
+/**
+ * Claude Skills Extension
+ *
+ * Bridges Claude Code's skills into pi. On resources_discover it hands pi the
+ * existing `.claude/skills` directories (user then project) as skill paths, so
+ * pi discovers Claude Code skills the same way it loads its own `.pi/skills`.
+ * pi implements the Agent Skills standard, so `SKILL.md` directories work
+ * unchanged and register as `/skill:name`.
+ *
+ * Docs: https://code.claude.com/docs/en/skills.md, https://agentskills.io
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+function isDirectory(target: string): boolean {
+  try {
+    return fs.statSync(target).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** Existing `.claude/skills` directories, user first then project. */
+export function skillDirs(cwd: string, home: string): string[] {
+  const candidates = [path.join(home, '.claude', 'skills'), path.join(cwd, '.claude', 'skills')]
+  const dirs: string[] = []
+  for (const dir of candidates) {
+    if (!dirs.includes(dir) && isDirectory(dir)) dirs.push(dir)
+  }
+  return dirs
+}
+
+export default function skillsExtension(pi: ExtensionAPI) {
+  pi.on('resources_discover', async (_event, ctx) => {
+    const skillPaths = skillDirs(ctx.cwd, os.homedir())
+    return skillPaths.length > 0 ? { skillPaths } : undefined
+  })
+}

package/extensions/status-line.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ *
+ * pi's built-in footer already shows path, branch, context, and model;
+ * this extension only adds what is missing instead of replacing the footer.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+
+interface UsageEntry {
+  type: string
+  message?: { usage?: { cost?: { total?: number } } }
+}
+
+function sessionCost(ctx: ExtensionContext): number {
+  let total = 0
+  for (const entry of ctx.sessionManager.getBranch() as UsageEntry[]) {
+    total += entry.message?.usage?.cost?.total ?? 0
+  }
+  return total
+}
+
+function formatCost(cost: number): string {
+  return cost >= 0.01 ? `$${cost.toFixed(2)}` : `$${cost.toFixed(4)}`
+}
+
+export default function statusLine(pi: ExtensionAPI) {
+  let turnCount = 0
+
+  function showIdle(ctx: ExtensionContext, symbol: string): void {
+    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)
+  }
+
+  pi.on('session_start', async (_event, ctx) => {
+    showIdle(ctx, ctx.ui.theme.fg('dim', '○'))
+  })
+
+  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}...`))
+  })
+
+  pi.on('turn_end', async (_event, ctx) => {
+    showIdle(ctx, ctx.ui.theme.fg('success', '✓'))
+  })
+
+  pi.on('agent_end', async (_event, ctx) => {
+    showIdle(ctx, ctx.ui.theme.fg('success', '✓'))
+  })
+}

package/extensions/subagent/README.md

@@ -0,0 +1,172 @@
+# Subagent Example
+
+Delegate tasks to specialized subagents with isolated context windows.
+
+## Features
+
+- **Isolated context**: Each subagent runs in a separate `pi` process
+- **Streaming output**: See tool calls and progress as they happen
+- **Parallel streaming**: All parallel tasks stream updates simultaneously
+- **Markdown rendering**: Final output rendered with proper formatting (expanded view)
+- **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
+- **Abort support**: Ctrl+C propagates to kill subagent processes
+
+## Structure
+
+```
+subagent/
+├── README.md            # This file
+├── index.ts             # The extension (entry point)
+├── agents.ts            # Agent discovery logic
+├── 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
+```
+
+## Installation
+
+From the repository root, symlink the files:
+
+```bash
+# Symlink the extension (must be in a subdirectory with index.ts)
+mkdir -p ~/.pi/agent/extensions/subagent
+ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.pi/agent/extensions/subagent/index.ts
+ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.pi/agent/extensions/subagent/agents.ts
+
+# Symlink agents
+mkdir -p ~/.pi/agent/agents
+for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f")
+done
+
+# Symlink workflow prompts
+mkdir -p ~/.pi/agent/prompts
+for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/prompts/$(basename "$f")
+done
+```
+
+## Security Model
+
+This tool executes a separate `pi` subprocess with a delegated system prompt and tool/model configuration.
+
+**Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
+
+**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`.
+
+To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
+
+When running interactively, the tool prompts for confirmation before running project-local agents. Set `confirmProjectAgents: false` to disable.
+
+## Usage
+
+### Single agent
+```
+Use scout to find all authentication code
+```
+
+### Parallel execution
+```
+Run 2 scouts 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
+```
+
+## Tool Modes
+
+| Mode | Parameter | Description |
+|------|-----------|-------------|
+| Single | `{ agent, task }` | One agent, one task |
+| Parallel | `{ tasks: [...] }` | Multiple agents run concurrently (max 8, 4 concurrent) |
+| Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder |
+
+## Output Display
+
+**Collapsed view** (default):
+- Status icon (✓/✗/⏳) and agent name
+- Last 5-10 items (tool calls and text)
+- Usage stats: `3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model`
+
+**Expanded view** (Ctrl+O):
+- Full task text
+- All tool calls with formatted arguments
+- Final output rendered as Markdown
+- Per-task usage (for chain/parallel)
+
+**Parallel mode streaming**:
+- Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
+- Updates as each task makes progress
+- Shows "2/3 done, 1 running" status
+
+**Tool call formatting** (mimics built-in tools):
+- `$ command` for bash
+- `read ~/path:1-10` for read
+- `grep /pattern/ in ~/path` for grep
+- etc.
+
+## Agent Definitions
+
+Agents are markdown files with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+tools: read, grep, find, ls
+model: claude-haiku-4-5
+---
+
+System prompt for the agent goes here.
+```
+
+**Locations:**
+- `~/.pi/agent/agents/*.md` - User-level (always loaded)
+- `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
+
+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) |
+
+## Workflow Prompts
+
+| Prompt | Flow |
+|--------|------|
+| `/implement <query>` | scout → planner → worker |
+| `/scout-and-plan <query>` | scout → planner |
+| `/implement-and-review <query>` | worker → reviewer → worker |
+
+## Error Handling
+
+- **Exit code != 0**: Tool returns error with stderr/output
+- **stopReason "error"**: LLM error propagated with error message
+- **stopReason "aborted"**: User abort (Ctrl+C) kills subprocess, throws error
+- **Chain mode**: Stops at first failing step, reports which step failed
+
+## Limitations
+
+- Output truncated to last 10 items in collapsed view (expand to see all)
+- Agents discovered fresh on each invocation (allows editing mid-session)
+- Parallel mode limited to 8 tasks, 4 concurrent