pi-crew 0.2.25 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.3.0] — Phase 3a+3b: Discovery Cache, Dynamic Agent Registry, Rich TUI Rendering (2026-05-23)
+
+### Phase 3a: Agent Discovery Cache
+- **500ms TTL cache** with max 32 entries and per-cwd invalidation
+- **FIFO eviction** when cache is full
+- Cache pruned on every `discoverAgents()` call
+- `invalidateAgentDiscoveryCache(cwd?)` exposed for explicit invalidation
+
+### Phase 3b: Dynamic Agent Registry
+- **`registerDynamicAgent(config)`** — runtime agent registration with cache invalidation
+- **`unregisterDynamicAgent(name)`** — throws on missing agent
+- **`listDynamicAgents()`** — returns all registered dynamic agents
+- Dynamic agents get **highest priority** over discovered agents (security: project < builtin < user < dynamic)
+- **CrewRegistry v2** — extended from v1 with `registerAgent`/`unregisterAgent`/`listDynamicAgents`
+- Factory `installCrewGlobalRegistry()` for clean initialization
+
+### Rich TUI Tool Rendering
+- **New `src/ui/tool-render.ts`** (304 lines) — shared rendering module ported from pi-subagent4
+- **`renderTeamToolCall`** — collapsed: `team action='run' (default) "goal preview"` / expanded: header + goal streaming
+- **`renderAgentToolCall`** — collapsed: `Agent explorer "prompt preview"` / expanded: header + prompt
+- **`renderTeamToolResult`** — `[status] goal text` for run actions / compact info for others
+- **`renderAgentToolResult`** — status icons (⟳○✓✗) + output lines for agent results
+- **`renderAgentProgress`** — icon + header + tool log + context gauge + usage line (↑↓RW$ctx)
+- Helpers: `formatTokens`, `formatDuration`, `formatContextUsage`, `truncLine`, `formatToolPreview`
+- All tools use **`@mariozechner/pi-tui`** Components (Container, Text, Spacer) directly
+- `renderCall`/`renderResult` added to: `team`, `Agent` tools
+
+### Tests
+- **1662 tests pass** (1652 unit + 46 integration + 4 new)
+- New test suites: `agent-discovery-cache.test.ts` (10 tests), `tool-render.test.ts` (10 tests)
+- Bug fix: `allAgents` priority corrected (discovery: project < builtin < user; dynamic separate/highest)
+
 ## [0.2.21] — 3 Bugs Fixed — Background Runner, Child-pi stdin, Phantom Runs (2026-05-22)
 
 ## [0.2.25] — CI Fixes & needs_attention Terminal Status (2026-05-22)

package/README.md

@@ -9,7 +9,7 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.2.21**: 3 bugs fixed — background runner session_shutdown survival, child-pi stdin hang, phantom runs from temp workspaces. See [CHANGELOG.md](CHANGELOG.md) and [docs/pi-crew-bugs.md](docs/pi-crew-bugs.md).
+**v0.2.25**: See [CHANGELOG.md](CHANGELOG.md) and [docs/pi-crew-bugs.md](docs/pi-crew-bugs.md).
 
 ---
 
@@ -116,33 +116,61 @@ security-reviewer  ·  test-engineer  ·  verifier  ·  writer
 
 ---
 
-## Runtime Safety
+## Runtime Modes
 
-By default, `run` launches each task as a **separate child Pi process**. Workers execute independently and stream output to durable state.
+pi-crew supports multiple runtime modes for task execution:
 
-Scaffold/dry-run mode (no real workers):
+| Mode | Description |
+|------|-------------|
+| `auto` (default) | Uses `child-process` unless overridden by config |
+| `child-process` | Spawns real `pi` child processes — each task runs in isolation |
+| `scaffold` | Dry-run mode — renders prompts and persists artifacts without executing |
+| `live-session` (experimental) | In-process session execution within the parent Pi |
 
 ```json
-{ "runtime": { "mode": "scaffold" } }
+// Use scaffold mode (no real workers, just prompts)
+{ "action": "run", "team": "default", "goal": "...", "runtime": { "mode": "scaffold" } }
+
+// Disable workers globally
+{ "executeWorkers": false }
 ```
 
-Disable workers globally:
+## Async Runs
+
+Async runs are **detached** from the session — they survive session switches and reloads. Pi-crew notifies when complete.
 
 ```json
-{ "executeWorkers": false }
+{ "action": "run", "team": "default", "goal": "...", "async": true }
+```
+
+```text
+/team-run --async Investigate failing tests
 ```
 
-Worktree mode is **opt-in** and requires a clean repo:
+Background runs use `node --import jiti-register.mjs` for TypeScript support. See [docs/runtime-flow.md](docs/runtime-flow.md) for details.
+
+## Worktree Isolation
+
+Worktree mode creates an **isolated git worktree per task** — safe for parallel edits to the same branch.
 
 ```json
 {
   "action": "run",
   "team": "implementation",
   "goal": "Refactor auth",
-  "workspaceMode": "worktree"
+  "worktree": { "enabled": true }
 }
 ```
 
+```text
+/team-run --worktree Refactor auth
+```
+
+Requirements:
+- Git repository
+- Clean working tree (no uncommitted changes in the main worktree)
+- Worktrees auto-cleanup on run completion/cancel
+
 ---
 
 ## Configuration
@@ -158,45 +186,85 @@ Worktree mode is **opt-in** and requires a clean repo:
 ### Quick Config
 
 ```text
-/team-config                                       # view
-/team-config asyncByDefault=true                    # update
-/team-config runtime.mode=scaffold                  # scaffold mode
-/team-config --unset=asyncByDefault                 # reset
-/team-config autonomous.profile=assisted --project  # project scope
+/team-config                           # view all settings
+/team-config get runtime.mode            # read one key
+/team-config set runtime.mode=scaffold  # scaffold mode
+/team-config set asyncByDefault=true    # async by default
+/team-config unset runtime.mode          # reset to default
+/team-config --project                  # project scope
+/team-settings path                     # show config file path
 ```
 
 ### Key Settings
 
-| Section | Key Settings | Default |
-|---------|-------------|---------|
-| **Runtime** | `mode`: `auto` \| `scaffold` \| `child-process` \| `live-session` | `auto` |
-| **Concurrency** | `limits.maxConcurrentWorkers` | workflow-dependent (2–4) |
-| **Async** | `asyncByDefault`, `runtime.groupJoin` | `false`, `smart` |
+| Section | Keys | Default |
+|---------|------|---------|
+| **Runtime** | `mode`: `auto` \| `child-process` \| `scaffold` \| `live-session` | `auto` |
+| | `maxTurns`, `graceTurns`, `groupJoin`, `requirePlanApproval` | various |
+| **Concurrency** | `limits.maxConcurrentWorkers` | workflow-dependent |
+| | `limits.maxTaskDepth`, `limits.maxChildrenPerTask` | 2, 5 |
+| **Async** | `asyncByDefault` | `false` |
+| | `runtime.groupJoin`: `off` \| `group` \| `smart` | `smart` |
 | **Autonomy** | `profile`: `manual` \| `suggested` \| `assisted` \| `aggressive` | `suggested` |
-| **UI** | `widgetPlacement`, `dashboardPlacement`, `showModel`, `showTokens` | compact widget |
-| **Reliability** | `autoRetry`, `autoRecover`, `deadletterThreshold`, `retryPolicy` | all opt-in |
-| **Observability** | `prometheus.enabled`, `otlp.enabled` | opt-in |
+| | `autonomous.injectPolicy`, `preferAsyncForLongTasks` | true, false |
+| **UI** | `widgetPlacement`, `dashboardPlacement` | compact widget |
+| | `showModel`, `showTokens` | display controls |
+| **Reliability** | `autoRetry`, `autoRecover`, `deadletterThreshold` | opt-in |
+| **Observability** | `prometheus.enabled`, `otlp.enabled`, `heartbeatStaleMs` | opt-in |
+| **Worktree** | `worktree.enabled` | disabled by default |
 
 > ⚠️ **Trust boundary**: project config cannot override sensitive execution controls (workers, runtime mode, autonomy, agent overrides). Set those in **user config** only.
 
-📖 Full config reference: [docs/configuration.md](docs/configuration.md) *(coming soon — see [docs/usage.md](docs/usage.md) for now)*
+📖 Full config reference: [docs/commands-reference.md#team-settings--config-management](docs/commands-reference.md) and [schema.json](schema.json)
 
 ---
 
 ## Tool Actions
 
 ```json
-{ "action": "run", "team": "default", "goal": "..." }       // execute
-{ "action": "status", "runId": "team_..." }                   // monitor
-{ "action": "cancel", "runId": "team_..." }                   // stop
-{ "action": "resume", "runId": "team_..." }                   // continue
-{ "action": "recommend", "goal": "..." }                       // get advice
-{ "action": "list" }                                            // discover
-{ "action": "create", "resource": "agent", ... }              // extend
-{ "action": "doctor" }                                          // diagnose
+// Execute workflow (foreground or async)
+{ "action": "run", "team": "default", "goal": "..." }
+{ "action": "run", "team": "default", "goal": "...", "async": true }
+
+// Monitor & control
+{ "action": "status", "runId": "team_..." }
+{ "action": "summary", "runId": "team_..." }
+{ "action": "events", "runId": "team_..." }
+{ "action": "artifacts", "runId": "team_..." }
+{ "action": "cancel", "runId": "team_..." }
+{ "action": "resume", "runId": "team_..." }
+
+// Discovery
+{ "action": "list" }
+{ "action": "get", "resource": "team", "name": "default" }
+{ "action": "recommend", "goal": "Refactor auth flow" }
+
+// Resource management
+{ "action": "create", "resource": "agent", "config": { "name": "api-reviewer", ... } }
+{ "action": "update", "resource": "team", "name": "backend", "config": { ... } }
+{ "action": "delete", "resource": "workflow", "name": "quick-review" }
+{ "action": "validate" }
+
+// Run maintenance
+{ "action": "cleanup", "runId": "team_..." }
+{ "action": "forget", "runId": "team_...", "confirm": true }
+{ "action": "prune", "olderThanDays": 7, "confirm": true }
+{ "action": "export", "runId": "team_..." }
+{ "action": "import", "path": "/path/to/bundle.tar.gz" }
+
+// Environment & configuration
+{ "action": "doctor", "config": { "smokeChildPi": true } }
+{ "action": "config" }
+{ "action": "init", "config": { "copyBuiltins": true } }
+{ "action": "autonomy", "profile": "assisted" }
+
+// Advanced
+{ "action": "api", "runId": "team_...", "operation": "read-manifest" }
+{ "action": "plan", "team": "default", "goal": "..." }
+{ "action": "worktrees", "runId": "team_..." }
 ```
 
-📖 Full actions reference: [docs/actions-reference.md](docs/actions-reference.md)
+📖 Full actions reference (28 actions): [docs/actions-reference.md](docs/actions-reference.md)
 
 ---
 

package/docs/TEST_MATRIX.md

@@ -16,20 +16,20 @@ Maps pi-crew behavior to proof. Every row must have real validation evidence.
 
 | Story | Contract | Unit | Integration | CI | Status | Evidence |
 |-------|----------|------|-------------|-----|--------|----------|
-| Core team run | `docs/product/team-run.md` | yes | yes | yes 3/3 | implemented | 1621 tests pass |
-| Child process runner | `docs/product/child-process.md` | yes | no | yes 3/3 | implemented | child-pi.ts tests |
-| Async runner | `docs/product/async-runner.md` | yes | no | yes 3/3 | implemented | async-runner tests |
-| Live session | `docs/product/live-session.md` | yes | no | yes 3/3 | implemented | live-session tests |
-| State durability | `docs/product/state.md` | yes | no | yes 3/3 | implemented | state-store tests |
-| Worktree isolation | `docs/product/worktree.md` | yes | no | yes 3/3 | implemented | worktree tests |
-| Team tool API | `docs/product/team-tool.md` | yes | no | yes 3/3 | implemented | api tests |
-| Group join | `docs/product/group-join.md` | yes | no | yes 3/3 | implemented | group-join tests |
-| Model fallback | `docs/product/model-fallback.md` | yes | no | yes 3/3 | implemented | model-fallback tests |
-| Conflict detection | `docs/product/conflict-detect.md` | yes | no | yes 3/3 | implemented | conflict-detect tests |
-| Crash recovery | `docs/product/crash-recovery.md` | yes | no | yes 3/3 | implemented | crash-recovery tests |
-| Effectiveness guard | `docs/product/effectiveness.md` | yes | no | yes 3/3 | implemented | effectiveness tests |
-| Windows EBUSY | `docs/product/platform.md` | yes | no | yes 3/3 | implemented | rmSyncRetry tests |
-| Depth guard | `docs/product/runtime-safety.md` | yes | no | yes 3/3 | implemented | depth-guard tests |
+| Core team run | `docs/product/team-run.md` | yes | yes | yes 3/3 | implemented | 1655 tests pass (268 unit + 14 integration files) |
+| Child process runner | `docs/product/child-process.md` | yes | yes | yes 3/3 | implemented | child-pi-pool.test.ts, child-pi-timeout.test.ts, mock-child-run.test.ts |
+| Async runner | `docs/product/async-runner.md` | yes | yes | yes 3/3 | implemented | async-runner.test.ts, async-restart-recovery.test.ts |
+| Live session | `docs/product/live-session.md` | yes | no | yes 3/3 | implemented | live-session-context.test.ts, live-session-runtime.test.ts |
+| State durability | `docs/product/state.md` | yes | yes | yes 3/3 | implemented | state-store.test.ts, state-contracts.test.ts, phase3-runtime.test.ts |
+| Worktree isolation | `docs/product/worktree.md` | yes | yes | yes 3/3 | implemented | worktree-manager.test.ts, worktree-run.test.ts |
+| Team tool API | `docs/product/team-tool.md` | yes | yes | yes 3/3 | implemented | team-tool-dispatch.test.ts, extension-api-surface.test.ts, operator-experience.test.ts |
+| Group join | `docs/product/group-join.md` | yes | yes | yes 3/3 | implemented | phase6-runtime-hardening.test.ts |
+| Model fallback | `docs/product/model-fallback.md` | yes | no | yes 3/3 | implemented | model-fallback.test.ts |
+| Conflict detection | `docs/product/conflict-detect.md` | yes | no | yes 3/3 | implemented | conflict-detect.test.ts, delta-conflict.test.ts |
+| Crash recovery | `docs/product/crash-recovery.md` | yes | yes | yes 3/3 | implemented | recovery-recipes.test.ts, async-restart-recovery.test.ts |
+| Effectiveness guard | `docs/product/effectiveness.md` | yes | no | yes 3/3 | implemented | effectiveness-guard.test.ts |
+| Windows EBUSY | `docs/product/platform.md` | yes | yes | yes 3/3 | implemented | phase6-runtime-hardening.test.ts |
+| Depth guard | `docs/product/runtime-safety.md` | yes | no | yes 3/3 | implemented | subagent-depth.test.ts, completion-guard.test.ts |
 
 ## Evidence Rules
 
@@ -42,8 +42,10 @@ Maps pi-crew behavior to proof. Every row must have real validation evidence.
 ## Validation Commands
 
 ```bash
-npm test                    # Run all unit tests (1600+)
+npm test                    # Run all unit tests (1655 tests across 268 unit files + 14 integration files)
 npm run typecheck           # TypeScript check + strip-types import
 npm run check               # Biome lint + format
+npm run test:unit           # Unit tests only (fast, parallel)
+npm run test:integration    # Integration tests only (sequential)
 gh run list --limit 1       # Check latest CI status
 ```

package/docs/feature-analysis-subagent4.md

@@ -0,0 +1,305 @@
+# Feature Analysis: 3 Features to Port from pi-subagent4
+
+## 1. Safe Bash Tool
+
+### Current State in pi-crew
+- **No dangerous command blocking** - pi-crew relies on user config
+- `src/utils/env-filter.ts` has `sanitizeEnvSecrets()` for env var filtering, but nothing for bash commands
+- `src/runtime/skill-instructions.ts` references `safe-bash` skill, but it's a guidance document, not enforcement
+
+### How subagent4 Does It
+
+```typescript
+// tools/safe-bash.ts
+const DANGEROUS_PATTERNS = [
+  /\brm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?(-[a-zA-Z]*r[a-zA-Z]*\s+)?(\/|~\/?\s|~\/?\b)/,
+  /\bsudo\b/,
+  /\bmkfs\b/,
+  /\bdd\s+if=/,
+  /:\(\)\s*\{\s*:\|:&\s*\}\s*;:/,
+  />\s*\/dev\/[sh]d[a-z]/,
+  /\bchmod\s+(-[a-zA-Z]+\s+)?777\s+\//,
+  /\bchown\s+(-[a-zA-Z]+\s+)?root/,
+  /\bcurl\s.*\|\s*(ba)?sh/,
+  /\bwget\s.*\|\s*(ba)?sh/,
+  /\bshutdown\b/,
+  /\breboot\b/,
+  /\binit\s+0\b/,
+  /\bkill\s+-9\s+1\b/,
+  /\bkillall\b/,
+];
+
+function isDangerous(command: string): string | null {
+  const normalized = command.replace(/\\\n/g, " ");
+  for (const pattern of DANGEROUS_PATTERNS) {
+    if (pattern.test(normalized)) {
+      return `Command blocked by safe_bash: matches dangerous pattern ${pattern}`;
+    }
+  }
+  return null;
+}
+
+// Wraps pi's built-in bash tool
+pi.registerTool({
+  name: "safe_bash",
+  execute(toolCallId, params, signal, onUpdate, ctx) {
+    const danger = isDangerous(params.command);
+    if (danger) throw new Error(danger);
+    return bashTool.execute(toolCallId, params, signal, onUpdate);
+  }
+});
+```
+
+### Implementation Options for pi-crew
+
+**Option A: Wrapper Tool (Recommended)**
+```typescript
+// src/tools/safe-bash.ts
+// Extends pi's bash tool with pattern blocking
+// Registered as a custom tool that agents can use instead of bash
+```
+
+**Option B: Config-based Pattern Matching**
+```typescript
+// In pi-crew config
+{
+  "tools": {
+    "bash": {
+      "safeMode": true,
+      "blockedPatterns": ["rm -rf /", "sudo", "mkfs", ...]
+    }
+  }
+}
+```
+
+**Option C: Skill-based Guidance**
+```typescript
+// Already exists: skills/safe-bash/SKILL.md
+// But this is guidance only, not enforcement
+```
+
+### Effort Assessment
+| Aspect | Estimate |
+|--------|----------|
+| Code complexity | Low (~60 lines) |
+| Integration points | 1 (bash tool wrapper) |
+| Testing needed | Medium (regex pattern coverage) |
+| **Total effort** | **0.5-1 day** |
+
+### Risks
+- **Pattern gaps**: Regex may miss edge cases (e.g., `curl -sL` with `|` on separate line)
+- **Performance**: Pattern matching on every command adds latency
+- **User override**: Users might need to bypass for legitimate uses
+
+### Recommendation
+**IMPLEMENT** - Low effort, high value. Start with Option A (wrapper tool) and iterate.
+
+---
+
+## 2. Dynamic Agent Registration
+
+### Current State in pi-crew
+- **Static configuration**: Agents defined in `.team.md` files
+- **No runtime API**: Can't add/remove agents after startup
+- **Manifest-based**: Agents loaded from manifest at run start
+
+### How subagent4 Does It
+
+```typescript
+// Global bridge for cross-module access
+(globalThis as any).__pi_subagents = { registerAgent, unregisterAgent };
+
+export function registerAgent(config: AgentConfig): void {
+  // Validate not already registered
+  if (agents.find((a) => a.name === config.name)) {
+    throw new Error(`Agent already registered: ${config.name}`);
+  }
+  // Check allowlist if PI_SUBAGENT_ALLOWED is set
+  if (SUBAGENT_ALLOWLIST && !SUBAGENT_ALLOWLIST.includes(config.name)) return;
+  agents.push(config);
+}
+
+export function unregisterAgent(name: string): void {
+  agents = agents.filter((a) => a.name !== name);
+}
+
+// Agent config schema
+interface AgentConfig {
+  name: string;           // "scout", "researcher", "worker"
+  model: string;          // "haiku-4-5", "sonnet-4-6"
+  tools: string[];       // ["read", "grep", "find", "ls"]
+  systemPrompt?: string;  // Custom system prompt
+  subagentAgents?: string[];  // For worker: ["scout", "researcher"]
+}
+```
+
+### Implementation Options for pi-crew
+
+**Option A: Manifest Extension API**
+```typescript
+// Add to team-tool.ts
+export function registerAgent(config: AgentConfig): void {
+  // Validate against schema
+  // Add to global agent registry
+  // Notify active runs to reload
+}
+```
+
+**Option B: globalThis Bridge (subagent4 style)**
+```typescript
+// In extension/register.ts
+(globalThis as any).__pi_crew = {
+  registerAgent: (config: AgentConfig) => { ... },
+  unregisterAgent: (name: string) => { ... },
+  listAgents: () => { ... }
+};
+```
+
+**Option C: File-based Hot Reload**
+```typescript
+// Watch .team.md files for changes
+// Reload agents on file change
+// No API change needed
+```
+
+### Effort Assessment
+| Aspect | Estimate |
+|--------|----------|
+| Code complexity | Medium (~150 lines) |
+| Integration points | 3 (extension, team-tool, runtime) |
+| State management | Complex (need to handle active runs) |
+| **Total effort** | **2-3 days** |
+
+### Use Cases Enabled
+1. **Plugin system**: Third-party agents can register at runtime
+2. **Dynamic workflows**: Agents added based on project needs
+3. **A/B testing**: Swap agents without restart
+
+### Risks
+- **Race conditions**: Concurrent registration could cause duplicates
+- **State sync**: Active runs might use stale agent list
+- **Security**: Allowlist enforcement needed to prevent unauthorized agents
+
+### Recommendation
+**DEFER** - Medium effort, unclear value. Current manifest-based approach works for most use cases. Revisit if plugin system becomes a priority.
+
+---
+
+## 3. JSON Event Stream Parsing
+
+### Current State in pi-crew
+- **Lifecycle events**: spawn, spawn_error, response_timeout, etc.
+- **No tool-level events**: No visibility into what tools are running
+- **Completion-based**: Only sees final result, not progress
+
+### How subagent4 Does It
+
+```typescript
+// stdout JSON event stream parsing
+child.stdout.on("data", (data) => {
+  const lines = data.toString().split("\n");
+  for (const line of lines) {
+    if (!line.trim() || !line.startsWith("{")) continue;
+    const evt = JSON.parse(line);
+
+    // Event types handled
+    if (evt.type === "tool_execution_start") {
+      // Tool started - update UI, track count
+    }
+    if (evt.type === "tool_execution_update") {
+      // Tool progress - nested subagent results
+    }
+    if (evt.type === "tool_execution_end") {
+      // Tool completed - finalize
+    }
+    if (evt.type === "message_end") {
+      // Final output + usage stats
+    }
+  }
+});
+
+// Tool args preview extraction
+function extractToolArgsPreview(args: Record<string, unknown>): string {
+  if (args.command) return flatten(String(args.command));
+  if (args.path) return flatten(String(args.path));
+  if (args.query) return `"${flatten(String(args.query))}"`;
+  // ... more types
+}
+```
+
+### Implementation Options for pi-crew
+
+**Option A: Event Stream Bridge (Recommended)**
+```typescript
+// src/runtime/event-stream-bridge.ts
+// Parses JSON events from child stdout
+// Emits structured events to event bus
+// Updates task state in real-time
+
+interface ToolEvent {
+  type: "tool_execution_start" | "tool_execution_end" | "tool_execution_update";
+  toolName: string;
+  toolCallId: string;
+  args?: Record<string, unknown>;
+  result?: unknown;
+  timestamp: number;
+}
+```
+
+**Option B: Periodic Snapshot Polling**
+```typescript
+// Poll child process state every N seconds
+// Less real-time, but simpler implementation
+// Lower fidelity but still useful
+```
+
+**Option C: Log-based Analysis**
+```typescript
+// Parse .events.jsonl files after completion
+// No real-time, but enables post-run analysis
+// Good for debugging, not for live UI
+```
+
+### Effort Assessment
+| Aspect | Estimate |
+|--------|----------|
+| Code complexity | High (~300 lines) |
+| Integration points | 4 (child-pi, event-bus, task-runner, UI) |
+| Error handling | Complex (malformed JSON, partial events) |
+| **Total effort** | **3-5 days** |
+
+### Benefits Enabled
+1. **Live tool progress**: See what tools are running in real-time
+2. **Nested subagent visibility**: See child subagent activity
+3. **Token usage tracking**: Real-time context window monitoring
+4. **Error isolation**: Know exactly which tool failed
+5. **Better UX**: Progress indicators, not just spinner
+
+### Risks
+- **Event format changes**: Pi might change JSON event format
+- **Performance overhead**: JSON parsing on every stdout chunk
+- **Buffer handling**: Partial JSON lines need buffering
+
+### Recommendation
+**IMPLEMENT** - High effort, high value. This would significantly improve UX. Start with Option A and target `tool_execution_start/end` events first (most impactful).
+
+---
+
+## Summary
+
+| Feature | Effort | Value | Priority | Recommendation |
+|---------|--------|-------|----------|----------------|
+| Safe Bash | Low (0.5-1 day) | High | P0 | **IMPLEMENT NOW** |
+| Dynamic Registration | Medium (2-3 days) | Medium | P2 | DEFER |
+| JSON Event Stream | High (3-5 days) | High | P1 | **IMPLEMENT** |
+
+### Recommended Roadmap
+
+**Phase 1 (This week)**
+- Safe bash tool with pattern blocklist
+
+**Phase 2 (Next sprint)**
+- JSON event stream parsing for tool progress
+
+**Phase 3 (Future)**
+- Dynamic agent registration (if needed)