pi-crew 0.9.51 → 0.9.53

package/docs/distillation/cybersecurity-patterns.md

@@ -1,294 +0,0 @@
-# Anthropic Cybersecurity Skills — pi-crew Security Patterns Distillation
-
-**Source:** `source/Anthropic-Cybersecurity-Skills/` (754 skills)  
-**Date:** 2026-05-28  
-**Purpose:** Extract actionable security patterns for pi-crew multi-agent orchestration
-
----
-
-## Executive Summary
-
-pi-crew's `security-reviewer` role already has foundational skills in place:
-- ✅ `secure-agent-orchestration-review` — delegation, tool access, path containment
-- ✅ `ownership-session-security` — cross-session safety, ownership boundaries
-
-This distillation identifies **20 high-value patterns** from the Anthropic library that enhance pi-crew's security posture, focusing on:
-1. **Agent-specific threats** (prompt injection, context poisoning)
-2. **Supply chain security** (dependencies, npm packages)
-3. **Runtime hardening** (auth patterns, secret detection)
-
----
-
-## 1. Security-Reviewer Role Architecture (pi-crew)
-
-| Component | Location | Purpose |
-|-----------|----------|---------|
-| Role definition | `runtime/skill-instructions.ts:34` | Maps `security-reviewer` → 2 skills |
-| Output contract | `runtime/live-session-runtime.ts:211-218` | `<path>:<line>: <emoji> <severity>` pattern |
-| Team routing | `extension/team-recommendation.ts:48` | Triggers: security, vulnerability, auth, owasp |
-| Permission model | `runtime/role-permission.ts:5` | READ_ONLY_ROLES includes security-reviewer |
-| Autonomous policy | `extension/autonomous-policy.ts:9,91` | Routes high-risk tasks to review team |
-
----
-
-## 2. Anthropic Cybersecurity Skills — Top 20 for pi-crew
-
-### 2.1 Agent Security (MITRE ATLAS v5.4)
-
-| # | Skill | ATLAS | NIST AI RMF | Pattern |
-|---|-------|-------|-------------|---------|
-| 1 | `detecting-ai-model-prompt-injection-attacks` | AML.T0051, T0054, T0056, T0067, T0068 | GOVERN-1.1, MEASURE-2.7 | Multi-layer detector: regex (25+ patterns) + DeBERTa classifier + heuristic scoring |
-| 2 | `detecting-context-poisoning-in-agent-loops` | AML.T0051 | GOVERN-1.1 | Session context integrity, injection markers |
-| 3 | `detecting-tool-invocation-abuse` | AML.T0051, T0054 | MEASURE-2.5 | Tool call rate limiting, anomaly detection |
-| 4 | `detecting-malicious-skill-loading` | AML.T0062 | GOVERN-5.2 | Skill path traversal, untrusted skill sources |
-| 5 | `detecting-agent-privilege-escalation` | AML.T0054 | GOVERN-1.1 | Role permission boundary violations |
-
-### 2.2 Supply Chain Security
-
-| # | Skill | ATLAS | NIST AI RMF | Pattern |
-|---|-------|-------|-------------|---------|
-| 6 | `detecting-supply-chain-attacks-in-ci-cd` | AML.T0010, T0104 | GOVERN-5.2, MAP-1.6 | Dependency injection, build pipeline integrity |
-| 7 | `detecting-typosquatting-packages-in-npm-pypi` | — | — | Package name similarity, registry anomalies |
-| 8 | `detecting-malicious-npm-packages` | — | — | Package manifest analysis, install hooks |
-| 9 | `detecting-dependency-confusion-attacks` | — | — | Package resolution, version pinning |
-
-### 2.3 Authentication & Authorization
-
-| # | Skill | ATLAS | NIST AI RMF | Pattern |
-|---|-------|-------|-------------|---------|
-| 10 | `detecting-anomalous-authentication-patterns` | AML.T0043, T0018 | MEASURE-2.7, PR.AA-01 | Auth failure patterns, session anomalies |
-| 11 | `detecting-token-hijacking` | AML.T0018 | PR.AA-01 | Token reuse, timing anomalies |
-| 12 | `detecting-session-fixation` | AML.T0018 | PR.AA-01 | Session ID predictability, fixation attempts |
-
-### 2.4 Secrets & Data Security
-
-| # | Skill | ATLAS | NIST AI RMF | Pattern |
-|---|-------|-------|-------------|---------|
-| 13 | `detecting-sensitive-data-exposure` | AML.T0067 | GOVERN-1.1 | Secrets in code, logs, artifacts |
-| 14 | `detecting-credential-leakage-in-logs` | — | — | Log sanitization, redaction patterns |
-| 15 | `detecting-data-exfiltration-indicators` | AML.T0067 | GOVERN-1.1 | Outbound traffic anomalies, artifact size |
-
-### 2.5 Runtime & Infrastructure
-
-| # | Skill | ATLAS | NIST AI RMF | Pattern |
-|---|-------|-------|-------------|---------|
-| 16 | `detecting-path-traversal` | — | — | File system access control, path normalization |
-| 17 | `detecting-command-injection` | — | — | Shell command execution safety |
-| 18 | `detecting-serverless-function-injection` | — | — | MCP/serverless input validation |
-| 19 | `detecting-race-condition-vulnerabilities` | AML.T0054 | GOVERN-1.1 | Timing attacks, state mutation races |
-| 20 | `detecting-race-condition-in-file-operations` | AML.T0054 | GOVERN-1.1 | TOCTOU vulnerabilities |
-
----
-
-## 3. pi-crew Specific Patterns
-
-### 3.1 Trust Boundary Model
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        PARENT PI (pi-crew)                       │
-│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
-│  │ User prompt  │→ │ Task packet  │→ │ Child Pi (untrusted)  │ │
-│  └──────────────┘  └──────────────┘  └────────────────────────┘ │
-│         ↓                ↓                      ↓                 │
-│  Trust: USER     Trust: SANITIZED     Trust: NONE (untrusted)   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-**Key boundaries:**
-1. **parent↔child**: Child Pi spawned via `child-pi.ts` — env sanitized, cwd contained
-2. **user↔task packet**: Task packets sanitized via `sanitizeTaskPacket()` in `task-packet.ts`
-3. **project↔package skills**: Project skills in `skills/` are untrusted, package skills in `node_modules/` are trusted
-4. **artifacts↔prompts**: Artifacts written by child, read back into context — potential injection vector
-
-### 3.2 pi-crew Security Checklist
-
-Based on `multi-perspective-review` security pass and Anthropic patterns:
-
-```
-[ ] PATH TRAVERSAL
-    [ ] assertSafePathId() called for all file paths
-    [ ] resolveContainedPath() used instead of raw paths
-    [ ] symlink escape prevention via fstatSync after open
-    [ ] cwd override blocked (no path outside run directory)
-
-[ ] PROMPT INJECTION
-    [ ] Untrusted artifacts sanitized before context injection
-    [ ] Skill metadata not trusted as instruction
-    [ ] parentContext passed through sanitization
-
-[ ] SECRETS
-    [ ] Env vars sanitized via sanitizeEnvSecrets()
-    [ ] Event log redaction via redactEvent()
-    [ ] Artifact writes don't expose *** values
-    [ ] Team tool output filtered for credentials
-
-[ ] DESTRUCTIVE COMMANDS
-    [ ] delete/prune/reset/force-push require explicit confirmation
-    [ ] --force flags blocked unless user explicitly approved
-    [ ] Dangerous operations logged to event-log
-
-[ ] OWNERSHIP & RACE CONDITIONS
-    [ ] Cancel/respond/steer ownership verified
-    [ ] Mailbox appendFileSync not interleaved
-    [ ] Atomic writes use O_EXCL|O_CREAT|O_NOFOLLOW
-
-[ ] SUPPLY CHAIN
-    [ ] Package manifest reviewed for suspicious install hooks
-    [ ] npm install from untrusted sources requires confirmation
-    [ ] CI/CD pipeline integrity checks in place
-
-[ ] AGENT-SPECIFIC
-    [ ] Tool call rate limiting configured
-    [ ] Session context integrity markers present
-    [ ] Malicious skill path blocked before loading
-```
-
----
-
-## 4. MITRE ATLAS v5.4 Coverage for pi-crew
-
-### 4.1 AI/ML Threat Techniques (Relevant to Agent Orchestration)
-
-| ATLAS Technique | Description | pi-crew Relevance | Detection Pattern |
-|-----------------|-------------|-------------------|-------------------|
-| AML.T0051 | LLM Prompt Injection | ⭐⭐⭐ High | User prompt → task packet injection |
-| AML.T0054 | LLM Jailbreak | ⭐⭐ High | Role permission escalation |
-| AML.T0056 | Extract LLM System Prompt | ⭐⭐ High | Skill loading, system prompt leakage |
-| AML.T0067 | Exfiltrate Training Data | ⭐ Medium | Artifact exfiltration |
-| AML.T0068 | Corruption of Model Weights | ⭐ Low | Workspace file corruption |
-| AML.T0057 | Infer Sensitive Attributes | ⭐ Medium | Observable model outputs |
-| AML.T0047 | ML Training Attacks | ⭐ Low | TBD |
-| AML.T0010 | Supply Chain Attack | ⭐⭐⭐ High | npm packages, dependencies |
-| AML.T0104 | Software Supply Chain | ⭐⭐ High | Build pipeline, CI/CD |
-| AML.T0043 | Brute Force Auth | ⭐ Medium | Session auth patterns |
-| AML.T0018 | Steal Authentication Tokens | ⭐⭐ High | Token reuse, hijacking |
-
-### 4.2 Defensive Countermeasures (D3FEND)
-
-| D3FEND Technique | pi-crew Implementation |
-|------------------|------------------------|
-| AUTHENTICATION-HEURISTICS | `role-permission.ts`, `sanitizeEnvSecrets()` |
-| BUFFER-FORMAT-OPERATIONS | `safe-paths.ts` path normalization |
-| FILE-ANALYSIS | Artifact scan, patch extraction |
-| EXECUTABLE-REGISTER-ANALYSIS | Skill registration validation |
-| INTEGRITY-VERIFICATION | `atomic-write.ts` atomic writes |
-| LOGICAL-ACCESS-CONTROL | `ownerSessionId` ownership checks |
-| USER-ACTIVITY-ANALYTICS | `run-tracker.ts` lifecycle tracking |
-
----
-
-## 5. Implementation Recommendations
-
-### 5.1 Short-term (v0.5.x)
-
-1. **Extend `secure-agent-orchestration-review`** with ATLAS coverage
-2. **Add Anthropic skill subset** to `skills/security-priority.json` manifest
-3. **Add verification tests** for security patterns (e.g., path traversal, injection)
-
-### 5.2 Medium-term (v0.6.x)
-
-4. **Create `security-reviewer` skill library** importing top 20 patterns
-5. **Add runtime hardening** via `detecting-anomalous-authentication-patterns`
-6. **Implement supply chain scanning** for `package.json`, `package-lock.json`
-
-### 5.3 Long-term (v1.0)
-
-7. **Full ATLAS coverage** — map all AML techniques to detection patterns
-8. **Continuous verification** — CI checks for security mapping freshness
-9. **Security benchmark** — measurable security posture improvement
-
----
-
-## 6. Skill Manifest (security-priority.json)
-
-```json
-{
-  "version": "1.0.0",
-  "generated": "2026-05-28T06:00:00Z",
-  "source": "source/Anthropic-Cybersecurity-Skills/",
-  "priority_skills": [
-    { "id": "detecting-ai-model-prompt-injection-attacks", "priority": "critical", "atlas": ["AML.T0051"] },
-    { "id": "detecting-supply-chain-attacks-in-ci-cd", "priority": "critical", "atlas": ["AML.T0010", "AML.T0104"] },
-    { "id": "detecting-anomalous-authentication-patterns", "priority": "high", "atlas": ["AML.T0043", "AML.T0018"] },
-    { "id": "detecting-typosquatting-packages-in-npm-pypi", "priority": "high", "atlas": [] },
-    { "id": "detecting-path-traversal", "priority": "high", "atlas": [] },
-    { "id": "detecting-command-injection", "priority": "high", "atlas": [] },
-    { "id": "detecting-sensitive-data-exposure", "priority": "high", "atlas": ["AML.T0067"] },
-    { "id": "detecting-context-poisoning-in-agent-loops", "priority": "high", "atlas": ["AML.T0051"] },
-    { "id": "detecting-tool-invocation-abuse", "priority": "medium", "atlas": ["AML.T0051", "AML.T0054"] },
-    { "id": "detecting-malicious-skill-loading", "priority": "medium", "atlas": ["AML.T0062"] },
-    { "id": "detecting-credential-leakage-in-logs", "priority": "medium", "atlas": [] },
-    { "id": "detecting-session-fixation", "priority": "medium", "atlas": ["AML.T0018"] },
-    { "id": "detecting-data-exfiltration-indicators", "priority": "medium", "atlas": ["AML.T0067"] },
-    { "id": "detecting-serverless-function-injection", "priority": "medium", "atlas": [] },
-    { "id": "detecting-race-condition-vulnerabilities", "priority": "medium", "atlas": ["AML.T0054"] },
-    { "id": "detecting-agent-privilege-escalation", "priority": "medium", "atlas": ["AML.T0054"] },
-    { "id": "detecting-malicious-npm-packages", "priority": "low", "atlas": [] },
-    { "id": "detecting-dependency-confusion-attacks", "priority": "low", "atlas": [] },
-    { "id": "detecting-token-hijacking", "priority": "low", "atlas": ["AML.T0018"] },
-    { "id": "detecting-race-condition-in-file-operations", "priority": "low", "atlas": ["AML.T0054"] }
-  ]
-}
-```
-
----
-
-## 7. Framework Mapping Reference
-
-### 7.1 MITRE ATT&CK (General Security)
-
-| Tactic | Technique | Coverage |
-|--------|-----------|----------|
-| Initial Access | T1195 (Supply Chain) | ✅ Covered |
-| Execution | T1059 (Command & Scripting) | ✅ Covered |
-| Persistence | T1543 (Create/Modify Process) | ⚠️ Partial |
-| Privilege Escalation | T1548 (Abuse Elevation) | ✅ Covered |
-| Defense Evasion | T1562 (Impair Defenses) | ⚠️ Partial |
-| Exfiltration | T1041 (Exfil Over C2) | ✅ Covered |
-
-### 7.2 NIST AI RMF 1.0
-
-| Function | Category | Coverage |
-|----------|----------|----------|
-| GOVERN | G1.1 AI Risk Strategy | ✅ Covered |
-| GOVERN | G6.1 AI Supply Chain | ✅ Covered |
-| MAP | MAP-1.6 Supply Chain | ✅ Covered |
-| MEASURE | M2.5 AI Evaluation | ✅ Covered |
-| MEASURE | M2.6 AI Measurement | ✅ Covered |
-| MEASURE | M2.7 AI Monitoring | ✅ Covered |
-| MANAGE | M2.4 AI Incident Response | ⚠️ Partial |
-
----
-
-## 8. Gap Analysis & Remediation
-
-| Gap | Severity | Status | Remediation |
-|-----|----------|--------|-------------|
-| Missing skill manifest | MEDIUM | ⚠️ Create `security-priority.json` | ✅ This document |
-| Full ATLAS coverage | HIGH | ⚠️ Partial (10/20 techniques) | Roadmap v1.0 |
-| Security benchmark | MEDIUM | ❌ None | Add measurable tests |
-| CI security checks | MEDIUM | ⚠️ Basic | Expand `verify-skill.ts` |
-| Skill update process | LOW | ❌ None | Add CI freshness check |
-| Trust boundary docs | MEDIUM | ⚠️ In code only | Add architecture doc |
-
----
-
-## 9. Conclusion
-
-pi-crew's `security-reviewer` role has a solid foundation with `secure-agent-orchestration-review` and `ownership-session-security`. The Anthropic Cybersecurity Skills library (754 skills) provides rich context for expanding coverage, particularly for:
-
-1. **Agent-specific threats** (prompt injection, context poisoning) — High priority
-2. **Supply chain security** (npm packages, dependencies) — Critical priority
-3. **Runtime hardening** (auth patterns, race conditions) — Medium priority
-
-**Next steps:**
-1. Create `skills/security-priority.json` manifest from this distillation
-2. Extend existing skills with ATLAS coverage
-3. Add verification tests for top 5 patterns
-4. Document trust boundary model
-
----
-
-*Generated by pi-crew team research run: `team_20260528060514_d75ea05271f1a93a`*  
-*Source: `source/Anthropic-Cybersecurity-Skills/` (754 skills, 26 domains)*

package/docs/feature-analysis-subagent4.md

@@ -1,305 +0,0 @@
-# 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)