attocode 0.1.5 → 0.1.7

package/dist/src/agent.js

@@ -18,17 +18,19 @@
  * - Execution Policies (Lesson 23)
  * - Thread Management (Lesson 24)
  */
-import { buildConfig, isFeatureEnabled, getEnabledFeatures, } from './defaults.js';
-import { createModeManager, formatModeList, parseMode, } from './modes.js';
+import { buildConfig, isFeatureEnabled, getEnabledFeatures, getSubagentTimeout, getSubagentMaxIterations, } from './defaults.js';
+import { createModeManager, formatModeList, parseMode, calculateTaskSimilarity, SUBAGENT_PLAN_MODE_ADDITION, } from './modes.js';
 import { createLSPFileTools, } from './agent-tools/index.js';
-import { HookManager, MemoryManager, PlanningManager, ObservabilityManager, SafetyManager, RoutingManager, MultiAgentManager, ReActManager, ExecutionPolicyManager, ThreadManager, RulesManager, DEFAULT_RULE_SOURCES, ExecutionEconomicsManager, STANDARD_BUDGET, AgentRegistry, filterToolsForAgent, formatAgentList, createCancellationManager, isCancellationError, createTimeoutToken, createLinkedToken, race, createResourceManager, createLSPManager, createSemanticCacheManager, createSkillManager, formatSkillList, createContextEngineering, stableStringify, createCodebaseContext, buildContextFromChunks, createPendingPlanManager, createInteractivePlanner, createRecursiveContext, createLearningStore, createCompactor, createAutoCompactionManager, createFileChangeTracker, createCapabilitiesRegistry, } from './integrations/index.js';
+import { HookManager, MemoryManager, PlanningManager, ObservabilityManager, SafetyManager, RoutingManager, MultiAgentManager, ReActManager, ExecutionPolicyManager, ThreadManager, RulesManager, DEFAULT_RULE_SOURCES, ExecutionEconomicsManager, STANDARD_BUDGET, AgentRegistry, filterToolsForAgent, formatAgentList, createCancellationManager, isCancellationError, createTimeoutToken, createLinkedToken, race, createResourceManager, createLSPManager, createSemanticCacheManager, createSkillManager, formatSkillList, createContextEngineering, stableStringify, createCodebaseContext, buildContextFromChunks, createPendingPlanManager, createInteractivePlanner, createRecursiveContext, createLearningStore, createCompactor, createAutoCompactionManager, createFileChangeTracker, createCapabilitiesRegistry, createSharedBlackboard, createTaskManager, } from './integrations/index.js';
 // Lesson 26: Tracing & Evaluation integration
 import { createTraceCollector } from './tracing/trace-collector.js';
 // Model registry for context window limits
 import { modelRegistry } from './costs/index.js';
 import { getModelContextLength } from './integrations/openrouter-pricing.js';
-// Spawn agent tool for LLM-driven subagent delegation
-import { createBoundSpawnAgentTool } from './tools/agent.js';
+// Spawn agent tools for LLM-driven subagent delegation
+import { createBoundSpawnAgentTool, createBoundSpawnAgentsParallelTool, } from './tools/agent.js';
+// Task tools for Claude Code-style task management
+import { createTaskTools, } from './tools/tasks.js';
 // =============================================================================
 // PRODUCTION AGENT
 // =============================================================================
@@ -71,6 +73,17 @@ export class ProductionAgent {
     fileChangeTracker = null;
     capabilitiesRegistry = null;
     toolResolver = null;
+    blackboard = null;
+    taskManager = null;
+    // Duplicate spawn prevention - tracks recently spawned tasks to prevent doom loops
+    // Map<taskKey, { timestamp: number; result: string; queuedChanges: number }>
+    spawnedTasks = new Map();
+    static SPAWN_DEDUP_WINDOW_MS = 60000; // 60 seconds
+    // Parent iteration tracking for total budget calculation
+    parentIterations = 0;
+    // External cancellation token (for subagent timeout propagation)
+    // When set, the agent will check this token in addition to its own cancellation manager
+    externalCancellationToken = null;
     // Initialization tracking
     initPromises = [];
     initComplete = false;
@@ -106,6 +119,18 @@ export class ProductionAgent {
         this.modeManager = createModeManager(this.config.tools);
         // Initialize pending plan manager for plan mode write interception
         this.pendingPlanManager = createPendingPlanManager();
+        // Shared Blackboard - enables coordination between parallel subagents
+        // Subagents inherit parent's blackboard; parent agents create their own
+        if (userConfig.blackboard) {
+            this.blackboard = userConfig.blackboard;
+        }
+        else if (this.config.subagent !== false) {
+            this.blackboard = createSharedBlackboard({
+                maxFindings: 500,
+                defaultClaimTTL: 120000, // 2 minutes for file claims
+                deduplicateFindings: true,
+            });
+        }
         // Initialize enabled features
         this.initializeFeatures();
     }
@@ -215,8 +240,25 @@ export class ProductionAgent {
             console.warn('[ProductionAgent] Failed to load user agents:', err);
         }));
         // Register spawn_agent tool so LLM can delegate to subagents
-        const boundSpawnTool = createBoundSpawnAgentTool((name, task) => this.spawnAgent(name, task));
+        const boundSpawnTool = createBoundSpawnAgentTool((name, task, constraints) => this.spawnAgent(name, task, constraints));
         this.tools.set(boundSpawnTool.name, boundSpawnTool);
+        // Register spawn_agents_parallel tool for parallel subagent execution
+        const boundParallelSpawnTool = createBoundSpawnAgentsParallelTool((tasks) => this.spawnAgentsParallel(tasks));
+        this.tools.set(boundParallelSpawnTool.name, boundParallelSpawnTool);
+        // Task Manager - Claude Code-style task system for coordination
+        this.taskManager = createTaskManager();
+        // Forward task events
+        this.taskManager.on('task.created', (data) => {
+            this.emit({ type: 'task.created', task: data.task });
+        });
+        this.taskManager.on('task.updated', (data) => {
+            this.emit({ type: 'task.updated', task: data.task });
+        });
+        // Register task tools
+        const taskTools = createTaskTools(this.taskManager);
+        for (const tool of taskTools) {
+            this.tools.set(tool.name, tool);
+        }
         // Cancellation Support
         if (isFeatureEnabled(this.config.cancellation)) {
             this.cancellation = createCancellationManager();
@@ -313,6 +355,11 @@ export class ProductionAgent {
                 cacheResults: true,
                 cacheTTL: 5 * 60 * 1000, // 5 minutes
             });
+            // Connect LSP manager to codebase context for enhanced code selection
+            // This enables LSP-based relevance boosting (Phase 4.1)
+            if (this.lspManager) {
+                this.codebaseContext.setLSPManager(this.lspManager);
+            }
         }
         // Forward context engineering events
         this.contextEngineering.on(event => {
@@ -792,9 +839,13 @@ export class ProductionAgent {
                 this.observability?.logger?.warn('Plan task failed', { taskId: currentTask.id });
                 // Continue with other tasks if possible
             }
-            // Check iteration limit
-            if (this.state.iteration >= this.config.maxIterations) {
-                this.observability?.logger?.warn('Max iterations reached');
+            // Check iteration limit (using total iterations to account for parent)
+            if (this.getTotalIterations() >= this.config.maxIterations) {
+                this.observability?.logger?.warn('Max iterations reached', {
+                    iteration: this.state.iteration,
+                    parentIterations: this.parentIterations,
+                    total: this.getTotalIterations(),
+                });
                 break;
             }
         }
@@ -832,10 +883,16 @@ export class ProductionAgent {
                 });
                 // =======================================================================
                 // CANCELLATION CHECK
+                // Checks both internal cancellation (ESC key) and external cancellation
+                // (parent timeout when this agent is a subagent)
                 // =======================================================================
                 if (this.cancellation?.isCancelled) {
                     this.cancellation.token.throwIfCancellationRequested();
                 }
+                // Also check external cancellation token (from parent when spawned as subagent)
+                if (this.externalCancellationToken?.isCancellationRequested) {
+                    this.externalCancellationToken.throwIfCancellationRequested();
+                }
                 // =======================================================================
                 // RESOURCE CHECK - system resource limits
                 // =======================================================================
@@ -945,7 +1002,11 @@ export class ProductionAgent {
                         });
                         // Emit appropriate event
                         if (budgetCheck.budgetType === 'iterations') {
-                            this.emit({ type: 'error', error: `Max iterations reached (${this.state.iteration})` });
+                            const totalIter = this.getTotalIterations();
+                            const iterMsg = this.parentIterations > 0
+                                ? `${this.state.iteration} + ${this.parentIterations} parent = ${totalIter}`
+                                : `${this.state.iteration}`;
+                            this.emit({ type: 'error', error: `Max iterations reached (${iterMsg})` });
                         }
                         else {
                             this.emit({ type: 'error', error: budgetCheck.reason || 'Budget exceeded' });
@@ -963,8 +1024,13 @@ export class ProductionAgent {
                 }
                 else {
                     // Fallback to simple iteration check if economics not available
-                    if (this.state.iteration >= this.config.maxIterations) {
-                        this.observability?.logger?.warn('Max iterations reached');
+                    // Use getTotalIterations() to account for parent iterations (subagent hierarchy)
+                    if (this.getTotalIterations() >= this.config.maxIterations) {
+                        this.observability?.logger?.warn('Max iterations reached', {
+                            iteration: this.state.iteration,
+                            parentIterations: this.parentIterations,
+                            total: this.getTotalIterations(),
+                        });
                         break;
                     }
                 }
@@ -1167,6 +1233,15 @@ export class ProductionAgent {
                 messages.push(assistantMessage);
                 this.state.messages.push(assistantMessage);
                 lastResponse = response.content;
+                // In plan mode: capture exploration findings as we go (not just at the end)
+                // This ensures we collect context from exploration iterations before writes are queued
+                if (this.modeManager.getMode() === 'plan' && response.content && response.content.length > 50) {
+                    const hasReadOnlyTools = response.toolCalls?.every(tc => ['read_file', 'list_files', 'glob', 'grep', 'search', 'mcp_'].some(prefix => tc.name.startsWith(prefix) || tc.name === prefix));
+                    // Capture substantive exploration content (not just "let me read..." responses)
+                    if (hasReadOnlyTools && !response.content.match(/^(Let me|I'll|I will|I need to|First,)/i)) {
+                        this.pendingPlanManager.appendExplorationFinding(response.content.slice(0, 1000));
+                    }
+                }
                 // Check for tool calls
                 // When forceTextOnly is set (max iterations reached), ignore any tool calls
                 const hasToolCalls = response.toolCalls && response.toolCalls.length > 0;
@@ -1182,6 +1257,14 @@ export class ProductionAgent {
                     // The model has "consumed" the tool outputs and produced a response,
                     // so we can replace verbose outputs with compact summaries
                     this.compactToolOutputs();
+                    // In plan mode: capture exploration summary from the final response
+                    // This provides context for what was learned during exploration before proposing changes
+                    if (this.modeManager.getMode() === 'plan' && this.pendingPlanManager.hasPendingPlan()) {
+                        const explorationContent = response.content || '';
+                        if (explorationContent.length > 0) {
+                            this.pendingPlanManager.setExplorationSummary(explorationContent);
+                        }
+                    }
                     // Final validation: warn if response is still empty after all retries
                     if (!response.content || response.content.length === 0) {
                         this.observability?.logger?.error('Agent finished with empty response after all retries', {
@@ -1683,11 +1766,8 @@ export class ProductionAgent {
                 // =====================================================================
                 // In plan mode, intercept write operations and queue them as proposed changes
                 if (this.modeManager.shouldInterceptTool(toolCall.name, toolCall.arguments)) {
-                    // Extract reason from context - use last assistant message or generate one
-                    const lastAssistantMsg = [...this.state.messages].reverse().find(m => m.role === 'assistant');
-                    const reason = typeof lastAssistantMsg?.content === 'string'
-                        ? lastAssistantMsg.content.slice(0, 200)
-                        : `Proposed change: ${toolCall.name}`;
+                    // Extract contextual reasoning instead of simple truncation
+                    const reason = this.extractChangeReasoning(toolCall, this.state.messages);
                     // Start a new plan if needed
                     if (!this.pendingPlanManager.hasPendingPlan()) {
                         const lastUserMsg = [...this.state.messages].reverse().find(m => m.role === 'user');
@@ -1823,10 +1903,45 @@ export class ProductionAgent {
                 if (process.env.DEBUG && toolCall.name.startsWith('mcp_') && wasPreloaded) {
                     console.log(`  ✓ Using pre-loaded MCP tool: ${toolCall.name}`);
                 }
+                // =====================================================================
+                // BLACKBOARD FILE COORDINATION (Parallel Subagent Support)
+                // =====================================================================
+                // Claim file resources before write operations to prevent conflicts
+                if (this.blackboard && (toolCall.name === 'write_file' || toolCall.name === 'edit_file')) {
+                    const args = toolCall.arguments;
+                    const filePath = String(args.path || args.file_path || '');
+                    if (filePath) {
+                        const agentId = this.config.systemPrompt?.slice(0, 50) || 'agent';
+                        const claimed = this.blackboard.claim(filePath, agentId, 'write', {
+                            ttl: 60000, // 1 minute claim
+                            intent: `${toolCall.name}: ${filePath}`,
+                        });
+                        if (!claimed) {
+                            const existingClaim = this.blackboard.getClaim(filePath);
+                            throw new Error(`File "${filePath}" is being edited by another agent (${existingClaim?.agentId || 'unknown'}). ` +
+                                `Wait for the other agent to complete or choose a different file.`);
+                        }
+                    }
+                }
                 // Execute tool (with sandbox if available)
                 let result;
                 if (this.safety?.sandbox) {
-                    result = await this.safety.sandbox.executeWithLimits(() => tool.execute(toolCall.arguments));
+                    // CRITICAL: spawn_agent and spawn_agents_parallel need MUCH longer timeouts
+                    // The default 60s sandbox timeout would kill subagents prematurely
+                    // Subagents may run for minutes (per their own timeout config)
+                    const isSpawnAgent = toolCall.name === 'spawn_agent';
+                    const isSpawnParallel = toolCall.name === 'spawn_agents_parallel';
+                    const isSubagentTool = isSpawnAgent || isSpawnParallel;
+                    const subagentConfig = this.config.subagent;
+                    const hasSubagentConfig = subagentConfig !== false && subagentConfig !== undefined;
+                    const subagentTimeout = hasSubagentConfig
+                        ? subagentConfig.defaultTimeout ?? 600000 // 10 min default
+                        : 600000;
+                    // Use subagent timeout + buffer for spawn tools, default for others
+                    // For spawn_agents_parallel, multiply by number of agents (they run in parallel,
+                    // but the total wall-clock time should still allow the slowest agent to complete)
+                    const toolTimeout = isSubagentTool ? subagentTimeout + 30000 : undefined;
+                    result = await this.safety.sandbox.executeWithLimits(() => tool.execute(toolCall.arguments), toolTimeout);
                 }
                 else {
                     result = await tool.execute(toolCall.arguments);
@@ -1859,6 +1974,15 @@ export class ProductionAgent {
                     callId: toolCall.id,
                     result,
                 });
+                // Release blackboard claim after successful file write
+                if (this.blackboard && (toolCall.name === 'write_file' || toolCall.name === 'edit_file')) {
+                    const args = toolCall.arguments;
+                    const filePath = String(args.path || args.file_path || '');
+                    if (filePath) {
+                        const agentId = this.config.systemPrompt?.slice(0, 50) || 'agent';
+                        this.blackboard.release(filePath, agentId);
+                    }
+                }
                 this.observability?.tracer?.endSpan(spanId);
             }
             catch (err) {
@@ -1895,8 +2019,32 @@ export class ProductionAgent {
         }
         return results;
     }
+    /**
+     * Get recently modified file paths from the file change tracker.
+     * Returns paths of files modified in this session (not undone).
+     */
+    getRecentlyModifiedFiles(limit = 5) {
+        if (!this.fileChangeTracker)
+            return [];
+        try {
+            const changes = this.fileChangeTracker.getChanges();
+            const recentFiles = new Set();
+            // Iterate in reverse to get most recent first
+            for (let i = changes.length - 1; i >= 0 && recentFiles.size < limit; i--) {
+                const change = changes[i];
+                if (!change.isUndone) {
+                    recentFiles.add(change.filePath);
+                }
+            }
+            return Array.from(recentFiles);
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * Select relevant code synchronously using cached repo analysis.
+     * Uses LSP-enhanced selection when available to boost related files.
      * Returns empty result if analysis hasn't been run yet.
      */
     selectRelevantCodeSync(task, maxTokens) {
@@ -1907,6 +2055,30 @@ export class ProductionAgent {
         if (!repoMap) {
             return { chunks: [], totalTokens: 0 };
         }
+        // Get recently modified files for LSP-enhanced selection
+        const recentFiles = this.getRecentlyModifiedFiles();
+        const priorityFileSet = new Set(recentFiles);
+        // LSP-related files (files that reference or are referenced by recent files)
+        const lspRelatedFiles = new Set();
+        if (this.codebaseContext.hasActiveLSP() && recentFiles.length > 0) {
+            // Use dependency graph as a synchronous proxy for LSP relationships
+            for (const file of recentFiles) {
+                // Files that this file depends on
+                const deps = repoMap.dependencyGraph.get(file);
+                if (deps) {
+                    for (const dep of deps) {
+                        lspRelatedFiles.add(dep);
+                    }
+                }
+                // Files that depend on this file
+                const reverseDeps = repoMap.reverseDependencyGraph.get(file);
+                if (reverseDeps) {
+                    for (const dep of reverseDeps) {
+                        lspRelatedFiles.add(dep);
+                    }
+                }
+            }
+        }
         // Get all chunks and score by relevance
         const allChunks = Array.from(repoMap.chunks.values());
         const taskLower = task.toLowerCase();
@@ -1930,13 +2102,22 @@ export class ProductionAgent {
                 }
             }
             // Combine with base importance
-            const combinedScore = chunk.importance * 0.4 + Math.min(relevance, 1) * 0.6;
+            let combinedScore = chunk.importance * 0.4 + Math.min(relevance, 1) * 0.6;
+            // Boost recently modified files (highest priority)
+            if (priorityFileSet.has(chunk.filePath)) {
+                combinedScore = Math.min(1.0, combinedScore + 0.4);
+            }
+            // Boost LSP-related files (files connected to recent edits)
+            else if (lspRelatedFiles.has(chunk.filePath)) {
+                combinedScore = Math.min(1.0, combinedScore + 0.25);
+            }
             return { chunk, score: combinedScore };
         });
         // Sort by score and select within budget
         scored.sort((a, b) => b.score - a.score);
         const selected = [];
         let totalTokens = 0;
+        const boostedFiles = [];
         for (const { chunk, score } of scored) {
             if (score < 0.1)
                 continue; // Skip very low relevance
@@ -1949,8 +2130,16 @@ export class ProductionAgent {
                 importance: score,
             });
             totalTokens += chunk.tokenCount;
+            // Track which files were boosted by LSP/dependency relationships
+            if (lspRelatedFiles.has(chunk.filePath)) {
+                boostedFiles.push(chunk.filePath);
+            }
         }
-        return { chunks: selected, totalTokens };
+        return {
+            chunks: selected,
+            totalTokens,
+            lspBoostedFiles: boostedFiles.length > 0 ? boostedFiles : undefined,
+        };
     }
     /**
      * Analyze the codebase (async). Call this once at startup for optimal performance.
@@ -2032,6 +2221,57 @@ export class ProductionAgent {
         // Generic
         return `Args: ${JSON.stringify(args).slice(0, 100)}...`;
     }
+    /**
+     * Extract contextual reasoning for a proposed change in plan mode.
+     * Looks at recent assistant messages to find relevant explanation.
+     * Returns a more complete reason than simple truncation.
+     */
+    extractChangeReasoning(toolCall, messages) {
+        // Get last few assistant messages (most recent first)
+        const assistantMsgs = messages
+            .filter(m => m.role === 'assistant' && typeof m.content === 'string')
+            .slice(-3)
+            .reverse();
+        if (assistantMsgs.length === 0) {
+            return `Proposed change: ${toolCall.name}`;
+        }
+        // Use the most recent assistant message
+        const lastMsg = assistantMsgs[0];
+        const content = lastMsg.content;
+        // For spawn_agent, the task itself is usually the reason
+        if (toolCall.name === 'spawn_agent') {
+            const args = toolCall.arguments;
+            const task = String(args.task || args.prompt || args.goal || '');
+            if (task.length > 0) {
+                // Use first paragraph or 500 chars of task as reason
+                const firstPara = task.split(/\n\n/)[0];
+                return firstPara.length > 500 ? firstPara.slice(0, 500) + '...' : firstPara;
+            }
+        }
+        // For file operations, look for context about the file
+        if (['write_file', 'edit_file'].includes(toolCall.name)) {
+            const args = toolCall.arguments;
+            const path = String(args.path || args.file_path || '');
+            // Look for mentions of this file in the assistant's explanation
+            if (path && content.toLowerCase().includes(path.toLowerCase().split('/').pop() || '')) {
+                // Extract the sentence(s) mentioning this file
+                const sentences = content.split(/[.!?\n]+/).filter(s => s.toLowerCase().includes(path.toLowerCase().split('/').pop() || ''));
+                if (sentences.length > 0) {
+                    const relevant = sentences.slice(0, 2).join('. ').trim();
+                    return relevant.length > 500 ? relevant.slice(0, 500) + '...' : relevant;
+                }
+            }
+        }
+        // Fallback: use first 500 chars instead of 200
+        // Look for the first meaningful paragraph/section
+        const paragraphs = content.split(/\n\n+/).filter(p => p.trim().length > 20);
+        if (paragraphs.length > 0) {
+            const firstPara = paragraphs[0].trim();
+            return firstPara.length > 500 ? firstPara.slice(0, 500) + '...' : firstPara;
+        }
+        // Ultimate fallback
+        return content.length > 500 ? content.slice(0, 500) + '...' : content;
+    }
     /**
      * Update memory statistics.
      * Memory stats are retrieved via memory manager, not stored in state.
@@ -2084,6 +2324,13 @@ export class ProductionAgent {
     getTraceCollector() {
         return this.traceCollector;
     }
+    /**
+     * Set a trace collector for this agent.
+     * Used for subagents to share the parent's trace collector (with subagent context).
+     */
+    setTraceCollector(collector) {
+        this.traceCollector = collector;
+    }
     /**
      * Get the learning store for cross-session learning.
      * Returns null if learning store is not enabled.
@@ -2603,6 +2850,11 @@ export class ProductionAgent {
         if (!this.threadManager) {
             throw new Error('Thread management not enabled. Enable it in config to use createCheckpoint()');
         }
+        // CRITICAL: Sync current state.messages to threadManager before checkpoint
+        // The run() method adds messages directly to this.state.messages but doesn't sync
+        // to threadManager, so thread.messages would be empty without this sync
+        const thread = this.threadManager.getActiveThread();
+        thread.messages = [...this.state.messages];
         const checkpoint = this.threadManager.createCheckpoint({
             label,
             agentState: this.state,
@@ -2777,8 +3029,12 @@ export class ProductionAgent {
     /**
      * Spawn an agent to execute a task.
      * Returns the result when the agent completes.
+     *
+     * @param agentName - Name of the agent to spawn (researcher, coder, etc.)
+     * @param task - The task description for the agent
+     * @param constraints - Optional constraints to keep the subagent focused
      */
-    async spawnAgent(agentName, task) {
+    async spawnAgent(agentName, task, constraints) {
         if (!this.agentRegistry) {
             return {
                 success: false,
@@ -2794,6 +3050,65 @@ export class ProductionAgent {
                 metrics: { tokens: 0, duration: 0, toolCalls: 0 },
             };
         }
+        // DUPLICATE SPAWN PREVENTION with SEMANTIC SIMILARITY
+        // First try exact string match, then check semantic similarity for similar tasks
+        const SEMANTIC_SIMILARITY_THRESHOLD = 0.75; // 75% similarity = duplicate
+        const taskKey = `${agentName}:${task.slice(0, 150).toLowerCase().replace(/\s+/g, ' ').trim()}`;
+        const now = Date.now();
+        // Clean up old entries (older than dedup window)
+        for (const [key, entry] of this.spawnedTasks.entries()) {
+            if (now - entry.timestamp > ProductionAgent.SPAWN_DEDUP_WINDOW_MS) {
+                this.spawnedTasks.delete(key);
+            }
+        }
+        // Check for exact match first
+        let existingMatch = this.spawnedTasks.get(taskKey);
+        let matchType = 'exact';
+        // If no exact match, check for semantic similarity among same agent's tasks
+        if (!existingMatch) {
+            for (const [key, entry] of this.spawnedTasks.entries()) {
+                // Only compare tasks from the same agent type
+                if (!key.startsWith(`${agentName}:`))
+                    continue;
+                if (now - entry.timestamp >= ProductionAgent.SPAWN_DEDUP_WINDOW_MS)
+                    continue;
+                // Extract the task portion from the key
+                const existingTask = key.slice(agentName.length + 1);
+                const similarity = calculateTaskSimilarity(task, existingTask);
+                if (similarity >= SEMANTIC_SIMILARITY_THRESHOLD) {
+                    existingMatch = entry;
+                    matchType = 'semantic';
+                    this.observability?.logger?.debug('Semantic duplicate detected', {
+                        agent: agentName,
+                        newTask: task.slice(0, 80),
+                        existingTask: existingTask.slice(0, 80),
+                        similarity: (similarity * 100).toFixed(1) + '%',
+                    });
+                    break;
+                }
+            }
+        }
+        if (existingMatch && now - existingMatch.timestamp < ProductionAgent.SPAWN_DEDUP_WINDOW_MS) {
+            // Same or semantically similar task spawned within the dedup window
+            this.observability?.logger?.warn('Duplicate spawn prevented', {
+                agent: agentName,
+                task: task.slice(0, 100),
+                matchType,
+                originalTimestamp: existingMatch.timestamp,
+                elapsedMs: now - existingMatch.timestamp,
+            });
+            const duplicateMessage = `[DUPLICATE SPAWN PREVENTED${matchType === 'semantic' ? ' - SEMANTIC MATCH' : ''}]\n` +
+                `This task was already spawned ${Math.round((now - existingMatch.timestamp) / 1000)}s ago.\n` +
+                `${existingMatch.queuedChanges > 0
+                    ? `The previous spawn queued ${existingMatch.queuedChanges} change(s) to the pending plan.\n` +
+                        `These changes are already in your plan - do NOT spawn again.\n`
+                    : ''}Previous result summary:\n${existingMatch.result.slice(0, 500)}`;
+            return {
+                success: true, // Mark as success since original task completed
+                output: duplicateMessage,
+                metrics: { tokens: 0, duration: 0, toolCalls: 0 },
+            };
+        }
         this.emit({ type: 'agent.spawn', agentId: `spawn-${Date.now()}`, name: agentName, task });
         this.observability?.logger?.info('Spawning agent', { name: agentName, task });
         const startTime = Date.now();
@@ -2807,16 +3122,88 @@ export class ProductionAgent {
             const resolvedModel = (agentDef.model && agentDef.model.includes('/'))
                 ? agentDef.model
                 : this.config.model;
-            // Get subagent config with defaults
-            // Note: subagent config is SubagentConfig | false from buildConfig
+            // Get subagent config with agent-type-specific timeouts and iteration limits
+            // Uses dynamic configuration based on agent type (researcher needs more time than reviewer)
             const subagentConfig = this.config.subagent;
             const hasSubagentConfig = subagentConfig !== false && subagentConfig !== undefined;
-            const defaultMaxIterations = hasSubagentConfig
-                ? subagentConfig.defaultMaxIterations ?? 10
-                : 10;
-            const subagentTimeout = hasSubagentConfig
-                ? subagentConfig.defaultTimeout ?? 120000
-                : 120000;
+            // Agent-type-specific timeout: researchers get 5min, reviewers get 2min, etc.
+            const agentTypeTimeout = getSubagentTimeout(agentName);
+            const configTimeout = hasSubagentConfig
+                ? subagentConfig.defaultTimeout
+                : undefined;
+            const subagentTimeout = configTimeout ?? agentTypeTimeout;
+            // Agent-type-specific iteration limit: researchers get 25, documenters get 10, etc.
+            const agentTypeMaxIter = getSubagentMaxIterations(agentName);
+            const configMaxIter = hasSubagentConfig
+                ? subagentConfig.defaultMaxIterations
+                : undefined;
+            const defaultMaxIterations = agentDef.maxIterations ?? configMaxIter ?? agentTypeMaxIter;
+            // BLACKBOARD CONTEXT INJECTION
+            // Gather relevant context from the blackboard for the subagent
+            let blackboardContext = '';
+            const parentAgentId = `parent-${Date.now()}`;
+            if (this.blackboard) {
+                // Post parent's exploration context before spawning
+                this.blackboard.post(parentAgentId, {
+                    topic: 'spawn.parent_context',
+                    content: `Parent spawning ${agentName} for task: ${task.slice(0, 200)}`,
+                    type: 'progress',
+                    confidence: 1,
+                    metadata: { agentName, taskPreview: task.slice(0, 100) },
+                });
+                // Gather recent findings that might help the subagent
+                const recentFindings = this.blackboard.query({
+                    limit: 5,
+                    types: ['discovery', 'analysis', 'progress'],
+                    minConfidence: 0.7,
+                });
+                if (recentFindings.length > 0) {
+                    const findingsSummary = recentFindings
+                        .map(f => `- [${f.agentId}] ${f.topic}: ${f.content.slice(0, 150)}${f.content.length > 150 ? '...' : ''}`)
+                        .join('\n');
+                    blackboardContext = `\n\n**BLACKBOARD CONTEXT (from parent/sibling agents):**\n${findingsSummary}\n`;
+                }
+            }
+            // Check for files already being modified in parent's pending plan
+            const currentPlan = this.pendingPlanManager.getPendingPlan();
+            if (currentPlan && currentPlan.proposedChanges.length > 0) {
+                const pendingFiles = currentPlan.proposedChanges
+                    .filter((c) => c.tool === 'write_file' || c.tool === 'edit_file')
+                    .map((c) => c.args.path || c.args.file_path)
+                    .filter(Boolean);
+                if (pendingFiles.length > 0) {
+                    blackboardContext += `\n**FILES ALREADY IN PENDING PLAN (do not duplicate):**\n${pendingFiles.slice(0, 10).join('\n')}\n`;
+                }
+            }
+            // CONSTRAINT INJECTION
+            // Add constraints to the subagent's context if provided
+            let constraintContext = '';
+            if (constraints) {
+                const constraintParts = [];
+                if (constraints.focusAreas && constraints.focusAreas.length > 0) {
+                    constraintParts.push(`**FOCUS AREAS (limit exploration to these paths):**\n${constraints.focusAreas.map(a => `  - ${a}`).join('\n')}`);
+                }
+                if (constraints.excludeAreas && constraints.excludeAreas.length > 0) {
+                    constraintParts.push(`**EXCLUDED AREAS (do NOT explore these):**\n${constraints.excludeAreas.map(a => `  - ${a}`).join('\n')}`);
+                }
+                if (constraints.requiredDeliverables && constraints.requiredDeliverables.length > 0) {
+                    constraintParts.push(`**REQUIRED DELIVERABLES (you must produce these):**\n${constraints.requiredDeliverables.map(d => `  - ${d}`).join('\n')}`);
+                }
+                if (constraints.maxTokens) {
+                    constraintParts.push(`**TOKEN BUDGET:** ${constraints.maxTokens} tokens maximum`);
+                }
+                if (constraints.timeboxMinutes) {
+                    constraintParts.push(`**TIME LIMIT:** ${constraints.timeboxMinutes} minutes (soft limit - wrap up if approaching)`);
+                }
+                if (constraintParts.length > 0) {
+                    constraintContext = `\n\n**EXECUTION CONSTRAINTS:**\n${constraintParts.join('\n\n')}\n`;
+                }
+            }
+            // Build subagent system prompt with subagent-specific plan mode addition
+            const parentMode = this.getMode();
+            const subagentSystemPrompt = parentMode === 'plan'
+                ? `${agentDef.systemPrompt}\n\n${SUBAGENT_PLAN_MODE_ADDITION}${blackboardContext}${constraintContext}`
+                : `${agentDef.systemPrompt}${blackboardContext}${constraintContext}`;
             // Create a sub-agent with the agent's config
             const subAgent = new ProductionAgent({
                 provider: this.provider,
@@ -2825,7 +3212,7 @@ export class ProductionAgent {
                 toolResolver: this.toolResolver || undefined,
                 // Pass MCP tool summaries so subagent knows what tools are available
                 mcpToolSummaries: this.config.mcpToolSummaries,
-                systemPrompt: agentDef.systemPrompt,
+                systemPrompt: subagentSystemPrompt,
                 model: resolvedModel,
                 maxIterations: agentDef.maxIterations || defaultMaxIterations,
                 // Inherit some features but keep subagent simpler
@@ -2843,7 +3230,31 @@ export class ProductionAgent {
                     builtIn: { logging: false, timing: false, metrics: false },
                     custom: [],
                 },
+                // Share parent's blackboard for coordination between parallel subagents
+                blackboard: this.blackboard || undefined,
             });
+            // CRITICAL: Subagent inherits parent's mode
+            // This ensures that if parent is in plan mode:
+            // - Subagent's read operations execute immediately (visible exploration)
+            // - Subagent's write operations get queued in the subagent's pending plan
+            // - User maintains control over what actually gets written
+            if (parentMode !== 'build') {
+                subAgent.setMode(parentMode);
+            }
+            // Pass parent's iteration count to subagent for accurate budget tracking
+            // This prevents subagents from consuming excessive iterations when parent already used many
+            subAgent.setParentIterations(this.getTotalIterations());
+            // UNIFIED TRACING: Share parent's trace collector with subagent context
+            // This ensures all subagent events are written to the same trace file as the parent,
+            // tagged with subagent context for proper aggregation in /trace output
+            if (this.traceCollector) {
+                const subagentTraceView = this.traceCollector.createSubagentView({
+                    parentSessionId: this.traceCollector.getSessionId() || 'unknown',
+                    agentType: agentName,
+                    spawnedAtIteration: this.state.iteration,
+                });
+                subAgent.setTraceCollector(subagentTraceView);
+            }
             // Forward events from subagent with context
             subAgent.subscribe(event => {
                 // Tag event with subagent source so TUI can display it properly
@@ -2857,20 +3268,77 @@ export class ProductionAgent {
             const effectiveSource = parentSource
                 ? createLinkedToken(parentSource, timeoutSource)
                 : timeoutSource;
+            // CRITICAL: Pass the cancellation token to the subagent so it can check and stop
+            // gracefully when timeout fires. Without this, the subagent continues running as
+            // a "zombie" even after race() returns with a timeout error.
+            subAgent.setExternalCancellation(effectiveSource.token);
             try {
                 // Run the task with cancellation propagation from parent
                 const result = await race(subAgent.run(task), effectiveSource.token);
                 const duration = Date.now() - startTime;
-                const spawnResult = {
+                // BEFORE cleanup - extract subagent's pending plan and merge into parent's plan
+                // This ensures that when a subagent in plan mode queues writes, they bubble up to the parent
+                let queuedChangeSummary = '';
+                let queuedChangesCount = 0;
+                if (subAgent.hasPendingPlan()) {
+                    const subPlan = subAgent.getPendingPlan();
+                    if (subPlan && subPlan.proposedChanges.length > 0) {
+                        queuedChangesCount = subPlan.proposedChanges.length;
+                        // Emit event for TUI to display
+                        this.emit({
+                            type: 'agent.pending_plan',
+                            agentId: agentName,
+                            changes: subPlan.proposedChanges,
+                        });
+                        // Build detailed summary of what was queued for the return message
+                        // This prevents the "doom loop" where parent doesn't know what subagent did
+                        const changeSummaries = subPlan.proposedChanges.map(c => {
+                            if (c.tool === 'write_file' || c.tool === 'edit_file') {
+                                const path = c.args.path || c.args.file_path || '(unknown file)';
+                                return `  - [${c.tool}] ${path}: ${c.reason}`;
+                            }
+                            else if (c.tool === 'bash') {
+                                const cmd = String(c.args.command || '').slice(0, 60);
+                                return `  - [bash] ${cmd}${String(c.args.command || '').length > 60 ? '...' : ''}: ${c.reason}`;
+                            }
+                            return `  - [${c.tool}]: ${c.reason}`;
+                        });
+                        queuedChangeSummary = `\n\n[PLAN MODE - CHANGES QUEUED TO PARENT]\n` +
+                            `The following ${subPlan.proposedChanges.length} change(s) have been queued in the parent's pending plan:\n` +
+                            changeSummaries.join('\n') + '\n' +
+                            `\nThese changes are now in YOUR pending plan. The task for this subagent is COMPLETE.\n` +
+                            `Do NOT spawn another agent for the same task - the changes are already queued.\n` +
+                            `Use /show-plan to see all pending changes, /approve to execute them.`;
+                        // Merge into parent's pending plan with subagent context
+                        for (const change of subPlan.proposedChanges) {
+                            this.pendingPlanManager.addProposedChange(change.tool, { ...change.args, _fromSubagent: agentName }, `[${agentName}] ${change.reason}`, change.toolCallId);
+                        }
+                    }
+                    // Also merge exploration summary if available
+                    if (subPlan?.explorationSummary) {
+                        this.pendingPlanManager.appendExplorationFinding(`[${agentName}] ${subPlan.explorationSummary}`);
+                    }
+                }
+                // If subagent queued changes, override output with informative message
+                // This is critical to prevent doom loops where parent doesn't understand what happened
+                const finalOutput = queuedChangeSummary
+                    ? (result.response || '') + queuedChangeSummary
+                    : (result.response || result.error || '');
+                const spawnResultFinal = {
                     success: result.success,
-                    output: result.response || result.error || '',
+                    output: finalOutput,
                     metrics: {
                         tokens: result.metrics.totalTokens,
                         duration,
                         toolCalls: result.metrics.toolCalls,
                     },
                 };
-                this.emit({ type: 'agent.complete', agentId: agentName, success: result.success });
+                this.emit({
+                    type: 'agent.complete',
+                    agentId: agentName,
+                    success: result.success,
+                    output: finalOutput.slice(0, 500), // Include output preview
+                });
                 // Enhanced tracing: Record subagent completion
                 this.traceCollector?.record({
                     type: 'subagent.link',
@@ -2898,7 +3366,14 @@ export class ProductionAgent {
                     },
                 });
                 await subAgent.cleanup();
-                return spawnResult;
+                // Cache result for duplicate spawn prevention
+                // Use the same taskKey from the dedup check above
+                this.spawnedTasks.set(taskKey, {
+                    timestamp: Date.now(),
+                    result: finalOutput,
+                    queuedChanges: queuedChangesCount,
+                });
+                return spawnResultFinal;
             }
             catch (err) {
                 // Handle cancellation (user ESC or timeout) for cleaner error messages
@@ -2909,6 +3384,55 @@ export class ProductionAgent {
                         ? 'User cancelled'
                         : `Timed out after ${subagentTimeout}ms`;
                     this.emit({ type: 'agent.error', agentId: agentName, error: reason });
+                    // =======================================================================
+                    // PRESERVE PARTIAL RESULTS
+                    // Instead of discarding all work, capture whatever the subagent produced
+                    // before timeout. This prevents the "zombie agent" problem where tokens
+                    // are consumed but results are lost.
+                    // =======================================================================
+                    const subagentState = subAgent.getState();
+                    const subagentMetrics = subAgent.getMetrics();
+                    // Extract partial response from the last assistant message
+                    const assistantMessages = subagentState.messages.filter(m => m.role === 'assistant');
+                    const lastAssistantMsg = assistantMessages[assistantMessages.length - 1];
+                    const partialResponse = typeof lastAssistantMsg?.content === 'string'
+                        ? lastAssistantMsg.content
+                        : '';
+                    // Extract pending plan before cleanup (even on cancellation, preserve any queued work)
+                    let cancelledQueuedSummary = '';
+                    if (subAgent.hasPendingPlan()) {
+                        const subPlan = subAgent.getPendingPlan();
+                        if (subPlan && subPlan.proposedChanges.length > 0) {
+                            this.emit({
+                                type: 'agent.pending_plan',
+                                agentId: agentName,
+                                changes: subPlan.proposedChanges,
+                            });
+                            // Build summary of changes that were queued before cancellation
+                            const changeSummaries = subPlan.proposedChanges.map(c => {
+                                if (c.tool === 'write_file' || c.tool === 'edit_file') {
+                                    const path = c.args.path || c.args.file_path || '(unknown file)';
+                                    return `  - [${c.tool}] ${path}: ${c.reason}`;
+                                }
+                                else if (c.tool === 'bash') {
+                                    const cmd = String(c.args.command || '').slice(0, 60);
+                                    return `  - [bash] ${cmd}...: ${c.reason}`;
+                                }
+                                return `  - [${c.tool}]: ${c.reason}`;
+                            });
+                            cancelledQueuedSummary = `\n\n[PLAN MODE - CHANGES QUEUED BEFORE CANCELLATION]\n` +
+                                `${subPlan.proposedChanges.length} change(s) were queued to the parent plan:\n` +
+                                changeSummaries.join('\n') + '\n' +
+                                `These changes are preserved in your pending plan.`;
+                            for (const change of subPlan.proposedChanges) {
+                                this.pendingPlanManager.addProposedChange(change.tool, { ...change.args, _fromSubagent: agentName }, `[${agentName}] ${change.reason}`, change.toolCallId);
+                            }
+                        }
+                        // Also preserve exploration summary
+                        if (subPlan?.explorationSummary) {
+                            this.pendingPlanManager.appendExplorationFinding(`[${agentName}] ${subPlan.explorationSummary}`);
+                        }
+                    }
                     // Try to cleanup the subagent gracefully
                     try {
                         await subAgent.cleanup();
@@ -2916,13 +3440,50 @@ export class ProductionAgent {
                     catch {
                         // Ignore cleanup errors on cancellation
                     }
-                    const output = isUserCancellation
+                    // Build output message with partial results
+                    const baseOutput = isUserCancellation
                         ? `Subagent '${agentName}' was cancelled by user.`
-                        : `Subagent '${agentName}' timed out after ${Math.round(subagentTimeout / 1000)}s. The task may be too complex or the model may be slow.`;
+                        : `Subagent '${agentName}' timed out after ${Math.round(subagentTimeout / 1000)}s.`;
+                    // Include partial response if we have one
+                    const partialResultSection = partialResponse
+                        ? `\n\n[PARTIAL RESULTS BEFORE TIMEOUT]\n${partialResponse.slice(0, 2000)}${partialResponse.length > 2000 ? '...(truncated)' : ''}`
+                        : '';
+                    // Enhanced tracing: Record subagent timeout with partial results
+                    this.traceCollector?.record({
+                        type: 'subagent.link',
+                        data: {
+                            parentSessionId: this.traceCollector.getSessionId() || 'unknown',
+                            childSessionId,
+                            childTraceId,
+                            childConfig: {
+                                agentType: agentName,
+                                model: resolvedModel || 'default',
+                                task,
+                                tools: agentTools.map(t => t.name),
+                            },
+                            spawnContext: {
+                                reason: `Delegated task: ${task.slice(0, 100)}`,
+                                expectedOutcome: agentDef.description,
+                                parentIteration: this.state.iteration,
+                            },
+                            result: {
+                                success: false,
+                                summary: `[TIMEOUT] ${baseOutput}\n${partialResponse.slice(0, 200)}`,
+                                tokensUsed: subagentMetrics.totalTokens,
+                                durationMs: duration,
+                            },
+                        },
+                    });
                     return {
                         success: false,
-                        output,
-                        metrics: { tokens: 0, duration, toolCalls: 0 },
+                        output: baseOutput + partialResultSection + cancelledQueuedSummary,
+                        // IMPORTANT: Use actual metrics instead of zeros
+                        // This ensures accurate token tracking in /trace output
+                        metrics: {
+                            tokens: subagentMetrics.totalTokens,
+                            duration,
+                            toolCalls: subagentMetrics.toolCalls,
+                        },
                     };
                 }
                 throw err; // Re-throw non-cancellation errors
@@ -2943,6 +3504,33 @@ export class ProductionAgent {
             };
         }
     }
+    /**
+     * Spawn multiple agents in parallel to work on independent tasks.
+     * Uses the shared blackboard for coordination and conflict prevention.
+     */
+    async spawnAgentsParallel(tasks) {
+        // Emit start event for TUI visibility
+        this.emit({
+            type: 'parallel.spawn.start',
+            count: tasks.length,
+            agents: tasks.map(t => t.agent),
+        });
+        // Execute all tasks in parallel
+        const promises = tasks.map(({ agent, task }) => this.spawnAgent(agent, task));
+        const results = await Promise.all(promises);
+        // Emit completion event
+        this.emit({
+            type: 'parallel.spawn.complete',
+            count: tasks.length,
+            successCount: results.filter(r => r.success).length,
+            results: results.map((r, i) => ({
+                agent: tasks[i].agent,
+                success: r.success,
+                tokens: r.metrics?.tokens || 0,
+            })),
+        });
+        return results;
+    }
     /**
      * Get a formatted list of available agents.
      */
@@ -3277,6 +3865,37 @@ If the task is a simple question or doesn't need specialized handling, set bestA
             this.emit({ type: 'mode.changed', from: this.getMode(), to: parsed });
         }
     }
+    /**
+     * Set the parent's iteration count for total budget tracking.
+     * When this agent is a subagent, the parent passes its iteration count
+     * so the subagent can account for total iterations across the hierarchy.
+     */
+    setParentIterations(count) {
+        this.parentIterations = count;
+    }
+    /**
+     * Set an external cancellation token for this agent.
+     * Used when spawning subagents to propagate parent timeout/cancellation.
+     * The agent will check this token in its main loop and stop gracefully
+     * when cancellation is requested, preserving partial results.
+     */
+    setExternalCancellation(token) {
+        this.externalCancellationToken = token;
+    }
+    /**
+     * Check if external cancellation has been requested.
+     * Returns true if the external token signals cancellation.
+     */
+    isExternallyCancelled() {
+        return this.externalCancellationToken?.isCancellationRequested ?? false;
+    }
+    /**
+     * Get total iterations (this agent + parent).
+     * Used for accurate budget tracking across subagent hierarchies.
+     */
+    getTotalIterations() {
+        return this.state.iteration + this.parentIterations;
+    }
     /**
      * Cycle to the next mode (for Tab key).
      */
@@ -3351,20 +3970,21 @@ If the task is a simple question or doesn't need specialized handling, set bestA
     /**
      * Approve the pending plan and execute the changes.
      * @param count - If provided, only approve first N changes
-     * @returns Result of executing the approved changes
+     * @returns Result of executing the approved changes, including tool outputs
      */
     async approvePlan(count) {
         const result = this.pendingPlanManager.approve(count);
         if (result.changes.length === 0) {
-            return { success: true, executed: 0, errors: [] };
+            return { success: true, executed: 0, errors: [], results: [] };
         }
         // Switch to build mode for execution
         const previousMode = this.getMode();
         this.setMode('build');
         this.emit({ type: 'plan.approved', changeCount: result.changes.length });
         const errors = [];
+        const results = [];
         let executed = 0;
-        // Execute each change
+        // Execute each change and CAPTURE results
         for (let i = 0; i < result.changes.length; i++) {
             const change = result.changes[i];
             this.emit({ type: 'plan.executing', changeIndex: i, totalChanges: result.changes.length });
@@ -3372,14 +3992,37 @@ If the task is a simple question or doesn't need specialized handling, set bestA
                 const tool = this.tools.get(change.tool);
                 if (!tool) {
                     errors.push(`Unknown tool: ${change.tool}`);
+                    this.emit({
+                        type: 'plan.change.complete',
+                        changeIndex: i,
+                        tool: change.tool,
+                        result: null,
+                        error: `Unknown tool: ${change.tool}`,
+                    });
                     continue;
                 }
-                await tool.execute(change.args);
+                // CRITICAL: Capture tool result instead of discarding it
+                const toolResult = await tool.execute(change.args);
+                results.push({ tool: change.tool, output: toolResult });
                 executed++;
+                // Emit result for TUI display
+                this.emit({
+                    type: 'plan.change.complete',
+                    changeIndex: i,
+                    tool: change.tool,
+                    result: toolResult,
+                });
             }
             catch (err) {
                 const error = err instanceof Error ? err.message : String(err);
                 errors.push(`${change.tool}: ${error}`);
+                this.emit({
+                    type: 'plan.change.complete',
+                    changeIndex: i,
+                    tool: change.tool,
+                    result: null,
+                    error,
+                });
             }
         }
         // Restore previous mode if it wasn't build
@@ -3390,6 +4033,7 @@ If the task is a simple question or doesn't need specialized handling, set bestA
             success: errors.length === 0,
             executed,
             errors,
+            results,
         };
     }
     /**
@@ -3426,6 +4070,12 @@ If the task is a simple question or doesn't need specialized handling, set bestA
     getAgentRegistry() {
         return this.agentRegistry;
     }
+    /**
+     * Get the task manager instance for task tracking.
+     */
+    getTaskManager() {
+        return this.taskManager;
+    }
     /**
      * Get all loaded skills.
      */