stravinsky 0.4.18__py3-none-any.whl → 0.4.66__py3-none-any.whl

mcp_bridge/tools/agent_manager.py

@@ -5,82 +5,98 @@ Spawns background agents using Claude Code CLI with full tool access.
 This replaces the simple model-only invocation with true agentic execution.
 """
 
-import asyncio
 import json
+import logging
 import os
 import shutil
-import subprocess
 import signal
+import asyncio
+import sys
+import threading
 import time
-import uuid
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass
 from datetime import datetime
+from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, List, Optional
-import threading
-import logging
+from typing import Any, Optional, List, Dict
+import subprocess
+from .mux_client import get_mux, MuxClient
+try:
+    from . import semantic_search
+except ImportError:
+    # Fallback or lazy import
+    semantic_search = None
 
 logger = logging.getLogger(__name__)
 
+
+# Output formatting modes
+class OutputMode(Enum):
+    """Control verbosity of agent spawn output."""
+
+    CLEAN = "clean"  # Concise single-line output
+    VERBOSE = "verbose"  # Full details with colors
+    SILENT = "silent"  # No output to stdout (logs only)
+
+
 # Model routing configuration
-# Specialized agents call external models via MCP tools:
-#   explore/dewey/document_writer/multimodal → invoke_gemini(gemini-3-flash)
-#   frontend → invoke_gemini(gemini-3-pro-high)
-#   delphi → invoke_openai(gpt-5.2)
-# Non-specialized coding tasks use Claude CLI with --model sonnet
 AGENT_MODEL_ROUTING = {
-    # Specialized agents - no CLI model flag, they call invoke_* tools
     "explore": None,
     "dewey": None,
     "document_writer": None,
     "multimodal": None,
     "frontend": None,
     "delphi": None,
-    "research-lead": None,  # Hierarchical orchestrator using gemini-3-flash
-    "implementation-lead": None,  # Hierarchical orchestrator using haiku
-    # Planner uses Opus for superior reasoning about dependencies and parallelization
+    "research-lead": None,
+    "implementation-lead": "sonnet",
+    "momus": None,
+    "comment_checker": None,
+    "debugger": "sonnet",
+    "code-reviewer": None,
     "planner": "opus",
-    # Default for unknown agent types (coding tasks) - use Sonnet 4.5
     "_default": "sonnet",
 }
 
-# Cost tier classification (from oh-my-opencode pattern)
 AGENT_COST_TIERS = {
-    "explore": "CHEAP",  # Uses gemini-3-flash
-    "dewey": "CHEAP",  # Uses gemini-3-flash
-    "document_writer": "CHEAP",  # Uses gemini-3-flash
-    "multimodal": "CHEAP",  # Uses gemini-3-flash
-    "research-lead": "CHEAP",  # Uses gemini-3-flash
-    "implementation-lead": "CHEAP",  # Uses haiku
-    "frontend": "MEDIUM",  # Uses gemini-3-pro-high
-    "delphi": "EXPENSIVE",  # Uses gpt-5.2 (OpenAI GPT)
-    "planner": "EXPENSIVE",  # Uses Claude Opus 4.5
-    "_default": "EXPENSIVE",  # Claude Sonnet 4.5 via CLI
+    "explore": "CHEAP",
+    "dewey": "CHEAP",
+    "document_writer": "CHEAP",
+    "multimodal": "CHEAP",
+    "research-lead": "CHEAP",
+    "implementation-lead": "MEDIUM",
+    "momus": "CHEAP",
+    "comment_checker": "CHEAP",
+    "debugger": "MEDIUM",
+    "code-reviewer": "CHEAP",
+    "frontend": "MEDIUM",
+    "delphi": "EXPENSIVE",
+    "planner": "EXPENSIVE",
+    "_default": "EXPENSIVE",
 }
 
-# Display model names for output formatting (user-visible)
 AGENT_DISPLAY_MODELS = {
     "explore": "gemini-3-flash",
     "dewey": "gemini-3-flash",
     "document_writer": "gemini-3-flash",
     "multimodal": "gemini-3-flash",
     "research-lead": "gemini-3-flash",
-    "implementation-lead": "haiku",
+    "implementation-lead": "claude-sonnet-4.5",
+    "momus": "gemini-3-flash",
+    "comment_checker": "gemini-3-flash",
+    "debugger": "claude-sonnet-4.5",
+    "code-reviewer": "gemini-3-flash",
     "frontend": "gemini-3-pro-high",
     "delphi": "gpt-5.2",
     "planner": "opus-4.5",
     "_default": "sonnet-4.5",
 }
 
-# Cost tier emoji indicators for visual differentiation
-# Colors indicate cost: 🟢 cheap/free, 🔵 medium, 🟣 expensive (GPT), 🟠 Claude
 COST_TIER_EMOJI = {
-    "CHEAP": "🟢",  # Free/cheap models (gemini-3-flash, haiku)
-    "MEDIUM": "🔵",  # Medium cost (gemini-3-pro-high)
-    "EXPENSIVE": "🟣",  # Expensive models (gpt-5.2, opus)
+    "CHEAP": "🟢",
+    "MEDIUM": "🔵",
+    "EXPENSIVE": "🟣",
 }
 
-# Model family indicators
 MODEL_FAMILY_EMOJI = {
     "gemini-3-flash": "🟢",
     "gemini-3-pro-high": "🔵",
@@ -90,14 +106,13 @@ MODEL_FAMILY_EMOJI = {
     "gpt-5.2": "🟣",
 }
 
-# ANSI color codes for terminal output
+
 class Colors:
     """ANSI color codes for colorized terminal output."""
+
     RESET = "\033[0m"
     BOLD = "\033[1m"
     DIM = "\033[2m"
-
-    # Foreground colors
     BLACK = "\033[30m"
     RED = "\033[31m"
     GREEN = "\033[32m"
@@ -106,8 +121,6 @@ class Colors:
     MAGENTA = "\033[35m"
     CYAN = "\033[36m"
     WHITE = "\033[37m"
-
-    # Bright foreground colors
     BRIGHT_BLACK = "\033[90m"
     BRIGHT_RED = "\033[91m"
     BRIGHT_GREEN = "\033[92m"
@@ -129,6 +142,90 @@ def get_model_emoji(model_name: str) -> str:
     return MODEL_FAMILY_EMOJI.get(model_name, "⚪")
 
 
+ORCHESTRATOR_AGENTS = ["stravinsky", "research-lead", "implementation-lead"]
+WORKER_AGENTS = [
+    "explore",
+    "dewey",
+    "delphi",
+    "frontend",
+    "debugger",
+    "code-reviewer",
+    "momus",
+    "comment_checker",
+    "document_writer",
+    "multimodal",
+    "planner",
+]
+
+AGENT_TOOLS = {
+    "stravinsky": ["all"],
+    "research-lead": ["agent_spawn", "agent_output", "invoke_gemini", "Read", "Grep", "Glob"],
+    "implementation-lead": [
+        "agent_spawn",
+        "agent_output",
+        "lsp_diagnostics",
+        "Read",
+        "Edit",
+        "Write",
+        "Grep",
+        "Glob",
+    ],
+    "explore": [
+        "Read",
+        "Grep",
+        "Glob",
+        "Bash",
+        "semantic_search",
+        "ast_grep_search",
+        "lsp_workspace_symbols",
+    ],
+    "dewey": ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"],
+    "frontend": ["Read", "Edit", "Write", "Grep", "Glob", "Bash", "invoke_gemini"],
+    "delphi": ["Read", "Grep", "Glob", "Bash", "invoke_openai"],
+    "debugger": ["Read", "Grep", "Glob", "Bash", "lsp_diagnostics", "lsp_hover", "ast_grep_search"],
+    "code-reviewer": ["Read", "Grep", "Glob", "Bash", "lsp_diagnostics", "ast_grep_search"],
+    "momus": ["Read", "Grep", "Glob", "Bash", "lsp_diagnostics", "ast_grep_search"],
+    "comment_checker": ["Read", "Grep", "Glob", "Bash", "ast_grep_search", "lsp_document_symbols"],
+    # Specialized agents
+    "document_writer": ["Read", "Write", "Grep", "Glob", "Bash", "invoke_gemini"],
+    "multimodal": ["Read", "invoke_gemini"],
+    "planner": ["Read", "Grep", "Glob", "Bash"],
+}
+
+
+def validate_agent_tools(agent_type: str, required_tools: list[str]) -> None:
+    if agent_type not in AGENT_TOOLS:
+        raise ValueError(
+            f"Unknown agent_type '{agent_type}'. Valid types: {list(AGENT_TOOLS.keys())}"
+        )
+
+    allowed_tools = AGENT_TOOLS[agent_type]
+    if "all" in allowed_tools:
+        return
+
+    missing_tools = [tool for tool in required_tools if tool not in allowed_tools]
+    if missing_tools:
+        raise ValueError(
+            f"Agent type '{agent_type}' does not have access to required tools: {missing_tools}\n"
+            f"Allowed tools for {agent_type}: {allowed_tools}"
+        )
+
+
+def validate_agent_hierarchy(spawning_agent: str, target_agent: str) -> None:
+    if spawning_agent in ORCHESTRATOR_AGENTS:
+        return
+
+    if spawning_agent in WORKER_AGENTS and target_agent in ORCHESTRATOR_AGENTS:
+        raise ValueError(
+            f"Worker agent '{spawning_agent}' cannot spawn orchestrator agent '{target_agent}'."
+        )
+
+    if spawning_agent in WORKER_AGENTS and target_agent in WORKER_AGENTS:
+        raise ValueError(
+            f"Worker agent '{spawning_agent}' cannot spawn another worker agent '{target_agent}'."
+        )
+
+
 def colorize_agent_spawn_message(
     cost_emoji: str,
     agent_type: str,
@@ -136,20 +233,7 @@ def colorize_agent_spawn_message(
     description: str,
     task_id: str,
 ) -> str:
-    """
-    Create a colorized agent spawn message with ANSI color codes.
-
-    Format:
-    🟢 explore:gemini-3-flash('Find auth...') ⏳
-    task_id=agent_abc123
-
-    With colors:
-    🟢 {CYAN}explore{RESET}:{YELLOW}gemini-3-flash{RESET}('{BOLD}Find auth...{RESET}') ⏳
-    task_id={BRIGHT_BLACK}agent_abc123{RESET}
-    """
     short_desc = (description or "")[:50].strip()
-
-    # Build colorized message
     colored_message = (
         f"{cost_emoji} "
         f"{Colors.CYAN}{agent_type}{Colors.RESET}:"
@@ -161,61 +245,63 @@ def colorize_agent_spawn_message(
     return colored_message
 
 
+def format_spawn_output(
+    agent_type: str,
+    display_model: str,
+    task_id: str,
+    mode: OutputMode = OutputMode.CLEAN,
+) -> str:
+    if mode == OutputMode.SILENT:
+        return ""
+
+    cost_emoji = get_agent_emoji(agent_type)
+    if mode == OutputMode.CLEAN:
+        return (
+            f"{Colors.GREEN}✓{Colors.RESET} "
+            f"{Colors.CYAN}{agent_type}{Colors.RESET}:"
+            f"{Colors.YELLOW}{display_model}{Colors.RESET} "
+            f"→ {Colors.CYAN}{task_id}{Colors.RESET}"
+        )
+    return ""
+
+
 @dataclass
 class AgentTask:
-    """Represents a background agent task with full tool access."""
-
     id: str
     prompt: str
-    agent_type: str  # explore, dewey, frontend, delphi, etc.
+    agent_type: str
     description: str
-    status: str  # pending, running, completed, failed, cancelled
+    status: str
     created_at: str
-    parent_session_id: Optional[str] = None
-    started_at: Optional[str] = None
-    completed_at: Optional[str] = None
-    result: Optional[str] = None
-    error: Optional[str] = None
-    pid: Optional[int] = None
-    timeout: int = 300  # Default 5 minutes
-    progress: Optional[Dict[str, Any]] = None  # tool calls, last update
-
-
-@dataclass
-class AgentProgress:
-    """Progress tracking for a running agent."""
-
-    tool_calls: int = 0
-    last_tool: Optional[str] = None
-    last_message: Optional[str] = None
-    last_update: Optional[str] = None
+    parent_session_id: str | None = None
+    terminal_session_id: str | None = None
+    started_at: str | None = None
+    completed_at: str | None = None
+    result: str | None = None
+    error: str | None = None
+    pid: int | None = None
+    timeout: int = 300
+    progress: dict[str, Any] | None = None
 
 
 class AgentManager:
-    """
-    Manages background agent execution using Claude Code CLI.
-
-    Key features:
-    - Spawns agents with full tool access via `claude -p`
-    - Tracks task status and progress
-    - Persists state to .stravinsky/agents.json
-    - Provides notification mechanism for task completion
-    """
-
-    # Dynamic CLI path - find claude in PATH, fallback to common locations
     CLAUDE_CLI = shutil.which("claude") or "/opt/homebrew/bin/claude"
 
-    def __init__(self, base_dir: Optional[str] = None):
-        # Initialize lock FIRST - used by _save_tasks and _load_tasks
+    def __init__(self, base_dir: str | None = None):
         self._lock = threading.RLock()
+        import uuid as uuid_module
 
+        self.session_id = os.environ.get(
+            "CLAUDE_CODE_SESSION_ID", f"pid_{os.getpid()}_{uuid_module.uuid4().hex[:8]}"
+        )
+        
         if base_dir:
             self.base_dir = Path(base_dir)
         else:
             self.base_dir = Path.cwd() / ".stravinsky"
 
         self.agents_dir = self.base_dir / "agents"
-        self.state_file = self.base_dir / "agents.json"
+        self.state_file = self.base_dir / f"agents_{self.session_id}.json"
 
         self.base_dir.mkdir(parents=True, exist_ok=True)
         self.agents_dir.mkdir(parents=True, exist_ok=True)
@@ -223,79 +309,148 @@ class AgentManager:
         if not self.state_file.exists():
             self._save_tasks({})
 
-        # In-memory tracking for running processes
-        self._processes: Dict[str, subprocess.Popen] = {}
-        self._notification_queue: Dict[str, List[Dict[str, Any]]] = {}
+        self._processes: dict[str, Any] = {} 
+        self._notification_queue: dict[str, list[dict[str, Any]]] = {}
+        self._tasks: dict[str, asyncio.Task] = {}
+        self._progress_monitors: dict[str, asyncio.Task] = {}
+        self._stop_monitors = asyncio.Event()
+        
+        # Orchestrator Integration
+        self.orchestrator = None # Type: Optional[OrchestratorState]
+
+        try:
+            self._sync_cleanup(max_age_minutes=30)
+        except Exception:
+            pass
+            
+        self._ensure_sidecar_running()
+
+    def _ensure_sidecar_running(self):
+        """Start the Go sidecar if not running."""
+        # Simple check: is socket present?
+        if os.path.exists("/tmp/stravinsky.sock"):
+            return
+
+        mux_path = Path.cwd() / "dist" / "stravinsky-mux"
+        if mux_path.exists():
+            try:
+                subprocess.Popen(
+                    [str(mux_path)],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    start_new_session=True
+                )
+                logger.info("Started stravinsky-mux sidecar")
+                # Wait briefly for socket
+                time.sleep(0.5)
+            except Exception as e:
+                logger.error(f"Failed to start sidecar: {e}")
+
+    def _sync_cleanup(self, max_age_minutes: int = 30):
+        tasks = self._load_tasks()
+        now = datetime.now()
+        removed_ids = []
+        for task_id, task in list(tasks.items()):
+            if task.get("status") in ["completed", "failed", "cancelled"]:
+                completed_at = task.get("completed_at")
+                if completed_at:
+                    try:
+                        completed_time = datetime.fromisoformat(completed_at)
+                        if (now - completed_time).total_seconds() / 60 > max_age_minutes:
+                            removed_ids.append(task_id)
+                            del tasks[task_id]
+                    except: continue
+        if removed_ids:
+            self._save_tasks(tasks)
 
-    def _load_tasks(self) -> Dict[str, Any]:
-        """Load tasks from persistent storage."""
+    def _load_tasks(self) -> dict[str, Any]:
         with self._lock:
             try:
                 if not self.state_file.exists():
                     return {}
-                with open(self.state_file, "r") as f:
+                with open(self.state_file) as f:
                     return json.load(f)
             except (json.JSONDecodeError, FileNotFoundError):
                 return {}
 
-    def _save_tasks(self, tasks: Dict[str, Any]):
-        """Save tasks to persistent storage."""
-        with self._lock:
-            with open(self.state_file, "w") as f:
-                json.dump(tasks, f, indent=2)
+    def _save_tasks(self, tasks: dict[str, Any]):
+        with self._lock, open(self.state_file, "w") as f:
+            json.dump(tasks, f, indent=2)
 
     def _update_task(self, task_id: str, **kwargs):
-        """Update a task's fields."""
         with self._lock:
             tasks = self._load_tasks()
             if task_id in tasks:
                 tasks[task_id].update(kwargs)
                 self._save_tasks(tasks)
 
-    def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
-        """Get a task by ID."""
+    def get_task(self, task_id: str) -> dict[str, Any] | None:
         tasks = self._load_tasks()
         return tasks.get(task_id)
 
-    def list_tasks(self, parent_session_id: Optional[str] = None) -> List[Dict[str, Any]]:
-        """List all tasks, optionally filtered by parent session."""
+    def list_tasks(
+        self,
+        parent_session_id: str | None = None,
+        show_all: bool = True,
+        current_session_only: bool = True,
+    ) -> list[dict[str, Any]]:
         tasks = self._load_tasks()
         task_list = list(tasks.values())
-
+        if current_session_only:
+            task_list = [t for t in task_list if t.get("terminal_session_id") == self.session_id]
         if parent_session_id:
             task_list = [t for t in task_list if t.get("parent_session_id") == parent_session_id]
-
+        if not show_all:
+            task_list = [t for t in task_list if t.get("status") in ["running", "pending"]]
         return task_list
 
-    def spawn(
+    async def spawn_async(
         self,
         token_store: Any,
         prompt: str,
         agent_type: str = "explore",
         description: str = "",
-        parent_session_id: Optional[str] = None,
-        system_prompt: Optional[str] = None,
+        parent_session_id: str | None = None,
+        system_prompt: str | None = None,
         model: str = "gemini-3-flash",
         thinking_budget: int = 0,
         timeout: int = 300,
+        semantic_first: bool = False,
     ) -> str:
-        """
-        Spawn a new background agent.
-
-        Args:
-            prompt: The task prompt for the agent
-            agent_type: Type of agent (explore, dewey, frontend, delphi)
-            description: Short description for status display
-            parent_session_id: Optional parent session for notifications
-            system_prompt: Optional custom system prompt
-            model: Model to use (gemini-3-flash, claude, etc.)
-            timeout: Maximum execution time in seconds
-
-        Returns:
-            Task ID for tracking
-        """
-        import uuid as uuid_module  # Local import for MCP context
+        # Orchestrator Logic
+        if self.orchestrator:
+            logger.info(f"Spawning agent {agent_type} in phase {self.orchestrator.current_phase}")
+            # Example: If in PLAN phase, inject wisdom automatically
+            from ..orchestrator.enums import OrchestrationPhase
+            if self.orchestrator.current_phase == OrchestrationPhase.PLAN:
+                from ..orchestrator.wisdom import WisdomLoader
+                wisdom = WisdomLoader().load_wisdom()
+                if wisdom:
+                    prompt = f"## PROJECT WISDOM\n{wisdom}\n\n---\n\n{prompt}"
+
+        # Semantic First Context Injection
+        if semantic_first and semantic_search:
+            try:
+                # Run search in thread to avoid blocking loop
+                results = await asyncio.to_thread(
+                    semantic_search.search, 
+                    query=prompt, 
+                    n_results=5, 
+                    project_path=str(self.base_dir.parent)
+                )
+                if results and "No results" not in results and "Error" not in results:
+                    prompt = (
+                        f"## 🧠 SEMANTIC CONTEXT (AUTO-INJECTED)\n"
+                        f"The following code snippets were found in the vector index based on your task:\n\n"
+                        f"{results}\n\n"
+                        f"---\n\n"
+                        f"## 📋 YOUR TASK\n"
+                        f"{prompt}"
+                    )
+            except Exception as e:
+                logger.error(f"Semantic context injection failed: {e}")
 
+        import uuid as uuid_module
         task_id = f"agent_{uuid_module.uuid4().hex[:8]}"
 
         task = AgentTask(
@@ -306,805 +461,400 @@ class AgentManager:
             status="pending",
             created_at=datetime.now().isoformat(),
             parent_session_id=parent_session_id,
+            terminal_session_id=self.session_id,
             timeout=timeout,
         )
 
-        # Persist task
         with self._lock:
             tasks = self._load_tasks()
             tasks[task_id] = asdict(task)
             self._save_tasks(tasks)
 
-        # Start background execution
-        self._execute_agent(
-            task_id, token_store, prompt, agent_type, system_prompt, model, thinking_budget, timeout
+        task_obj = asyncio.create_task(
+            self._execute_agent_async(
+                task_id, token_store, prompt, agent_type, system_prompt, model, thinking_budget, timeout
+            )
         )
+        self._tasks[task_id] = task_obj
 
         return task_id
 
-    def _execute_agent(
+    def spawn(self, *args, **kwargs) -> str:
+        try:
+            loop = asyncio.get_running_loop()
+            task_id_ref = [None]
+            async def wrap():
+                task_id_ref[0] = await self.spawn_async(*args, **kwargs)
+            
+            thread = threading.Thread(target=lambda: asyncio.run(wrap()))
+            thread.start()
+            thread.join()
+            return task_id_ref[0]
+        except RuntimeError:
+            return asyncio.run(self.spawn_async(*args, **kwargs))
+
+    async def _execute_agent_async(
         self,
         task_id: str,
         token_store: Any,
         prompt: str,
         agent_type: str,
-        system_prompt: Optional[str] = None,
+        system_prompt: str | None = None,
         model: str = "gemini-3-flash",
         thinking_budget: int = 0,
         timeout: int = 300,
     ):
-        """Execute agent using Claude CLI with full tool access.
-
-        Uses `claude -p` to spawn a background agent with complete tool access,
-        just like oh-my-opencode's Sisyphus implementation.
-        """
-
-        def run_agent():
-            log_file = self.agents_dir / f"{task_id}.log"
-            output_file = self.agents_dir / f"{task_id}.out"
-
-            self._update_task(task_id, status="running", started_at=datetime.now().isoformat())
+        self.agents_dir.mkdir(parents=True, exist_ok=True)
+        log_file = self.agents_dir / f"{task_id}.log"
+        output_file = self.agents_dir / f"{task_id}.out"
 
+        self._update_task(task_id, status="running", started_at=datetime.now().isoformat())
+
+        try:
+            full_prompt = prompt
+            if system_prompt:
+                full_prompt = f"{system_prompt}\n\n---\n\n{prompt}"
+
+            cmd = [
+                self.CLAUDE_CLI,
+                "-p",
+                full_prompt,
+                "--output-format",
+                "text",
+                "--dangerously-skip-permissions",
+            ]
+
+            cli_model = AGENT_MODEL_ROUTING.get(agent_type, AGENT_MODEL_ROUTING.get("_default", "sonnet"))
+            if cli_model:
+                cmd.extend(["--model", cli_model])
+
+            if thinking_budget and thinking_budget > 0:
+                cmd.extend(["--thinking-budget", str(thinking_budget)])
+
+            if system_prompt:
+                system_file = self.agents_dir / f"{task_id}.system"
+                system_file.write_text(system_prompt)
+                cmd.extend(["--system-prompt", str(system_file)])
+
+            logger.info(f"[AgentManager] Spawning {task_id}: {' '.join(cmd[:3])}...")
+
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=str(Path.cwd()),
+                env={**os.environ, "CLAUDE_CODE_ENTRYPOINT": "stravinsky-agent"},
+                start_new_session=True,
+            )
+
+            self._processes[task_id] = process
+            self._update_task(task_id, pid=process.pid)
+            
+            # Streaming read loop for Mux
+            stdout_buffer = []
+            stderr_buffer = []
+            mux = MuxClient(task_id)
+            mux.connect()
+            
+            async def read_stream(stream, buffer, stream_name):
+                while True:
+                    line = await stream.readline()
+                    if not line:
+                        break
+                    decoded = line.decode('utf-8', errors='replace')
+                    buffer.append(decoded)
+                    mux.log(decoded.strip(), stream_name)
+            
             try:
-                # Prepare full prompt with system prompt if provided
-                full_prompt = prompt
-                if system_prompt:
-                    full_prompt = f"{system_prompt}\n\n---\n\n{prompt}"
-
-                logger.info(f"[AgentManager] Spawning Claude CLI agent {task_id} ({agent_type})")
-
-                # Build Claude CLI command with full tool access
-                # Using `claude -p` for non-interactive mode with prompt
-                cmd = [
-                    self.CLAUDE_CLI,
-                    "-p",
-                    full_prompt,
-                    "--output-format",
-                    "text",
-                    "--dangerously-skip-permissions",  # Critical: bypass permission prompts
-                ]
-
-                # Model routing:
-                # - Specialized agents (explore/dewey/etc): None = use CLI default, they call invoke_*
-                # - Unknown agent types (coding tasks): Use Sonnet 4.5
-                if agent_type in AGENT_MODEL_ROUTING:
-                    cli_model = AGENT_MODEL_ROUTING[agent_type]  # None for specialized
-                else:
-                    cli_model = AGENT_MODEL_ROUTING.get("_default", "sonnet")
-
-                if cli_model:
-                    cmd.extend(["--model", cli_model])
-                    logger.info(f"[AgentManager] Using --model {cli_model} for {agent_type} agent")
-
-                # Add system prompt file if we have one
-                if system_prompt:
-                    system_file = self.agents_dir / f"{task_id}.system"
-                    system_file.write_text(system_prompt)
-                    cmd.extend(["--system-prompt", str(system_file)])
-
-                # Execute Claude CLI as subprocess with full tool access
-                logger.info(f"[AgentManager] Running: {' '.join(cmd[:3])}...")
-
-                # Use PIPE for stderr to capture it properly
-                # (Previously used file handle which was closed before process finished)
-                process = subprocess.Popen(
-                    cmd,
-                    stdin=subprocess.DEVNULL,  # Critical: prevent stdin blocking
-                    stdout=subprocess.PIPE,
-                    stderr=subprocess.PIPE,
-                    text=True,
-                    cwd=str(Path.cwd()),
-                    env={**os.environ, "CLAUDE_CODE_ENTRYPOINT": "stravinsky-agent"},
-                    start_new_session=True,  # Allow process group management
+                await asyncio.wait_for(
+                    asyncio.gather(
+                        read_stream(process.stdout, stdout_buffer, "stdout"),
+                        read_stream(process.stderr, stderr_buffer, "stderr"),
+                        process.wait()
+                    ),
+                    timeout=timeout
                 )
-
-                # Track the process
-                self._processes[task_id] = process
-                self._update_task(task_id, pid=process.pid)
-
-                # Wait for completion with timeout
+            except asyncio.TimeoutError:
                 try:
-                    stdout, stderr = process.communicate(timeout=timeout)
-                    result = stdout.strip() if stdout else ""
-
-                    # Write stderr to log file
-                    if stderr:
-                        log_file.write_text(stderr)
-
-                    if process.returncode == 0:
-                        output_file.write_text(result)
-                        self._update_task(
-                            task_id,
-                            status="completed",
-                            result=result,
-                            completed_at=datetime.now().isoformat(),
-                        )
-                        logger.info(f"[AgentManager] Agent {task_id} completed successfully")
-                    else:
-                        error_msg = f"Claude CLI exited with code {process.returncode}"
-                        if stderr:
-                            error_msg += f"\n{stderr}"
-                        self._update_task(
-                            task_id,
-                            status="failed",
-                            error=error_msg,
-                            completed_at=datetime.now().isoformat(),
-                        )
-                        logger.error(f"[AgentManager] Agent {task_id} failed: {error_msg}")
-
-                except subprocess.TimeoutExpired:
-                    process.kill()
-                    self._update_task(
-                        task_id,
-                        status="failed",
-                        error=f"Agent timed out after {timeout}s",
-                        completed_at=datetime.now().isoformat(),
-                    )
-                    logger.warning(f"[AgentManager] Agent {task_id} timed out")
-
-            except FileNotFoundError:
-                error_msg = f"Claude CLI not found at {self.CLAUDE_CLI}. Install with: npm install -g @anthropic-ai/claude-code"
-                log_file.write_text(error_msg)
+                    os.killpg(os.getpgid(process.pid), signal.SIGKILL)
+                except: pass
+                # Clean up streams
+                await process.wait()
+                error_msg = f"Timed out after {timeout}s"
+                output_file.write_text(f"❌ TIMEOUT: {error_msg}")
+                self._update_task(task_id, status="failed", error=error_msg, completed_at=datetime.now().isoformat())
+                return
+
+            stdout = "".join(stdout_buffer)
+            stderr = "".join(stderr_buffer)
+            
+            if stderr:
+                log_file.write_text(stderr)
+
+            if process.returncode == 0:
+                output_file.write_text(stdout)
                 self._update_task(
                     task_id,
-                    status="failed",
-                    error=error_msg,
+                    status="completed",
+                    result=stdout.strip(),
                     completed_at=datetime.now().isoformat(),
                 )
-                logger.error(f"[AgentManager] {error_msg}")
-
-            except Exception as e:
-                error_msg = str(e)
-                log_file.write_text(error_msg)
+            else:
+                error_msg = f"Exit code {process.returncode}\n{stderr}"
+                output_file.write_text(f"❌ ERROR: {error_msg}")
                 self._update_task(
                     task_id,
                     status="failed",
                     error=error_msg,
                     completed_at=datetime.now().isoformat(),
                 )
-                logger.exception(f"[AgentManager] Agent {task_id} exception")
 
-            finally:
-                self._processes.pop(task_id, None)
-                self._notify_completion(task_id)
+        except asyncio.CancelledError:
+            
+            
 
-        # Run in background thread
-        thread = threading.Thread(target=run_agent, daemon=True)
-        thread.start()
+            
+            try:
+                if task_id in self._processes:
+                    proc = self._processes[task_id]
+                    os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+                    await proc.wait()
+            except: pass
+            raise
+        except Exception as e:
+            error_msg = str(e)
+            output_file.write_text(f"❌ EXCEPTION: {error_msg}")
+            self._update_task(task_id, status="failed", error=error_msg, completed_at=datetime.now().isoformat())
+        finally:
+            self._processes.pop(task_id, None)
+            self._tasks.pop(task_id, None)
+            self._notify_completion(task_id)
 
     def _notify_completion(self, task_id: str):
-        """Queue notification for parent session."""
         task = self.get_task(task_id)
-        if not task:
-            return
-
-        parent_id = task.get("parent_session_id")
-        if parent_id:
+        if task and task.get("parent_session_id"):
+            parent_id = task["parent_session_id"]
             if parent_id not in self._notification_queue:
                 self._notification_queue[parent_id] = []
-
             self._notification_queue[parent_id].append(task)
-            logger.info(f"[AgentManager] Queued notification for {parent_id}: task {task_id}")
 
-    def get_pending_notifications(self, session_id: str) -> List[Dict[str, Any]]:
-        """Get and clear pending notifications for a session."""
-        notifications = self._notification_queue.pop(session_id, [])
-        return notifications
+    async def _monitor_progress_async(self, task_id: str, interval: int = 10):
+        task = self.get_task(task_id)
+        if not task: return
+        start_time = datetime.fromisoformat(task.get("started_at") or datetime.now().isoformat())
+
+        while not self._stop_monitors.is_set():
+            task = self.get_task(task_id)
+            if not task or task["status"] not in ["running", "pending"]:
+                # Final status reporting...
+                break
+            
+            elapsed = int((datetime.now() - start_time).total_seconds())
+            sys.stderr.write(f"{Colors.YELLOW}⏳{Colors.RESET} {Colors.CYAN}{task_id}{Colors.RESET} running ({elapsed}s)...\n")
+            sys.stderr.flush()
+            
+            try:
+                await asyncio.wait_for(self._stop_monitors.wait(), timeout=interval)
+                break
+            except asyncio.TimeoutError:
+                continue
 
     def cancel(self, task_id: str) -> bool:
-        """Cancel a running agent task."""
         task = self.get_task(task_id)
-        if not task:
-            return False
-
-        if task["status"] != "running":
+        if not task or task["status"] not in ["pending", "running"]:
             return False
 
         process = self._processes.get(task_id)
         if process:
             try:
-                os.killpg(os.getpgid(process.pid), signal.SIGTERM)
-                process.wait(timeout=5)
-            except Exception as e:
-                logger.warning(f"[AgentManager] Failed to kill process for {task_id}: {e}")
-                try:
-                    process.kill()
-                except:
-                    pass
-
+                if hasattr(process, 'pid'):
+                    os.killpg(os.getpgid(process.pid), signal.SIGTERM)
+            except: pass
+            
+        async_task = self._tasks.get(task_id)
+        if async_task:
+            async_task.cancel()
+            
         self._update_task(task_id, status="cancelled", completed_at=datetime.now().isoformat())
-
         return True
 
-    def stop_all(self, clear_history: bool = False) -> int:
-        """
-        Stop all running agents and optionally clear task history.
-
-        Args:
-            clear_history: If True, also remove completed/failed tasks from history
-
-        Returns:
-            Number of tasks stopped/cleared
-        """
+    async def stop_all_async(self, clear_history: bool = False) -> int:
         tasks = self._load_tasks()
         stopped_count = 0
-
-        # Stop running tasks
         for task_id, task in list(tasks.items()):
-            if task.get("status") == "running":
-                self.cancel(task_id)
-                stopped_count += 1
-
-        # Optionally clear history
+            status = task.get("status")
+            if status in ["pending", "running"]:
+                if self.cancel(task_id):
+                    stopped_count += 1
+        
+        self._stop_monitors.set()
+        
+        if self._tasks:
+            await asyncio.gather(*self._tasks.values(), return_exceptions=True)
+        if self._progress_monitors:
+            await asyncio.gather(*self._progress_monitors.values(), return_exceptions=True)
+            
         if clear_history:
             cleared = len(tasks)
             self._save_tasks({})
             self._processes.clear()
-            logger.info(f"[AgentManager] Cleared all {cleared} agent tasks")
+            self._tasks.clear()
+            self._progress_monitors.clear()
             return cleared
-
         return stopped_count
 
-    def get_output(self, task_id: str, block: bool = False, timeout: float = 30.0) -> str:
-        """
-        Get output from an agent task.
-
-        Args:
-            task_id: The task ID
-            block: If True, wait for completion
-            timeout: Max seconds to wait if blocking
-
-        Returns:
-            Formatted task output/status
-        """
+    def stop_all(self, clear_history: bool = False) -> int:
+        try:
+            return asyncio.run(self.stop_all_async(clear_history))
+        except RuntimeError:
+            # Loop already running, use a thread
+            res = [0]
+            def wrap(): res[0] = asyncio.run(self.stop_all_async(clear_history))
+            t = threading.Thread(target=wrap)
+            t.start()
+            t.join()
+            return res[0]
+
+    def cleanup(self, max_age_minutes: int = 30, statuses: list[str] | None = None) -> dict:
+        if statuses is None: statuses = ["completed", "failed", "cancelled"]
+        tasks = self._load_tasks()
+        now = datetime.now()
+        removed_ids = []
+        for task_id, task in list(tasks.items()):
+            if task.get("status") in statuses:
+                completed_at = task.get("completed_at")
+                if completed_at:
+                    try:
+                        completed_time = datetime.fromisoformat(completed_at)
+                        if (now - completed_time).total_seconds() / 60 > max_age_minutes:
+                            removed_ids.append(task_id)
+                            del tasks[task_id]
+                            for ext in [".log", ".out", ".system"]:
+                                (self.agents_dir / f"{task_id}{ext}").unlink(missing_ok=True)
+                    except: continue
+        if removed_ids: self._save_tasks(tasks)
+        return {"removed": len(removed_ids), "task_ids": removed_ids, "summary": f"Removed {len(removed_ids)} agents"}
+
+    async def get_output(self, task_id: str, block: bool = False, timeout: float = 30.0, auto_cleanup: bool = False) -> str:
         task = self.get_task(task_id)
-        if not task:
-            return f"Task {task_id} not found."
+        if not task: return f"Task {task_id} not found."
 
-        if block and task["status"] == "running":
-            # Poll for completion
-            start = datetime.now()
-            while (datetime.now() - start).total_seconds() < timeout:
+        if block and task["status"] in ["pending", "running"]:
+            start = time.time()
+            while (time.time() - start) < timeout:
                 task = self.get_task(task_id)
-                if not task or task["status"] != "running":
-                    break
-                time.sleep(0.5)
-
-        # Refresh task state after potential blocking wait
-        if not task:
-            return f"Task {task_id} not found."
+                if not task or task["status"] not in ["pending", "running"]: break
+                await asyncio.sleep(0.5)
 
+        task = self.get_task(task_id)
         status = task["status"]
-        description = task.get("description", "")
         agent_type = task.get("agent_type", "unknown")
-
-        # Get cost-tier emoji for visual differentiation
         cost_emoji = get_agent_emoji(agent_type)
         display_model = AGENT_DISPLAY_MODELS.get(agent_type, AGENT_DISPLAY_MODELS["_default"])
 
         if status == "completed":
-            result = task.get("result", "(no output)")
-            return f"""{cost_emoji} {Colors.BRIGHT_GREEN}✅ Agent Task Completed{Colors.RESET}
-
-**Task ID**: {Colors.BRIGHT_BLACK}{task_id}{Colors.RESET}
-**Agent**: {Colors.CYAN}{agent_type}{Colors.RESET}:{Colors.YELLOW}{display_model}{Colors.RESET}('{Colors.BOLD}{description}{Colors.RESET}')
-
-**Result**:
-{result}"""
-
+            res = task.get("result", "")
+            return f"{cost_emoji} {Colors.BRIGHT_GREEN}✅ Completed{Colors.RESET}\n\n**ID**: {task_id}\n**Result**:\n{res}"
         elif status == "failed":
-            error = task.get("error", "(no error details)")
-            return f"""{cost_emoji} {Colors.BRIGHT_RED}❌ Agent Task Failed{Colors.RESET}
-
-**Task ID**: {Colors.BRIGHT_BLACK}{task_id}{Colors.RESET}
-**Agent**: {Colors.CYAN}{agent_type}{Colors.RESET}:{Colors.YELLOW}{display_model}{Colors.RESET}('{Colors.BOLD}{description}{Colors.RESET}')
-
-**Error**:
-{error}"""
-
-        elif status == "cancelled":
-            return f"""{cost_emoji} {Colors.BRIGHT_YELLOW}⚠️ Agent Task Cancelled{Colors.RESET}
-
-**Task ID**: {Colors.BRIGHT_BLACK}{task_id}{Colors.RESET}
-**Agent**: {Colors.CYAN}{agent_type}{Colors.RESET}:{Colors.YELLOW}{display_model}{Colors.RESET}('{Colors.BOLD}{description}{Colors.RESET}')"""
-
-        else:  # pending or running
-            pid = task.get("pid", "N/A")
-            started = task.get("started_at", "N/A")
-            return f"""{cost_emoji} {Colors.BRIGHT_YELLOW}⏳ Agent Task Running{Colors.RESET}
-
-**Task ID**: {Colors.BRIGHT_BLACK}{task_id}{Colors.RESET}
-**Agent**: {Colors.CYAN}{agent_type}{Colors.RESET}:{Colors.YELLOW}{display_model}{Colors.RESET}('{Colors.BOLD}{description}{Colors.RESET}')
-**PID**: {Colors.DIM}{pid}{Colors.RESET}
-**Started**: {Colors.DIM}{started}{Colors.RESET}
-
-Use `agent_output` with block=true to wait for completion."""
+            err = task.get("error", "")
+            return f"{cost_emoji} {Colors.BRIGHT_RED}❌ Failed{Colors.RESET}\n\n**ID**: {task_id}\n**Error**:\n{err}"
+        else:
+            return f"{cost_emoji} {Colors.BRIGHT_YELLOW}⏳ Running{Colors.RESET}\n\n**ID**: {task_id}\nStatus: {status}"
 
     def get_progress(self, task_id: str, lines: int = 20) -> str:
-        """
-        Get real-time progress from a running agent's output.
-
-        Args:
-            task_id: The task ID
-            lines: Number of lines to show from the end
-
-        Returns:
-            Recent output lines and status
-        """
         task = self.get_task(task_id)
-        if not task:
-            return f"Task {task_id} not found."
-
+        if not task: return f"Task {task_id} not found."
         output_file = self.agents_dir / f"{task_id}.out"
-        log_file = self.agents_dir / f"{task_id}.log"
-
-        status = task["status"]
-        description = task.get("description", "")
-        agent_type = task.get("agent_type", "unknown")
-        pid = task.get("pid")
-
-        # Zombie Detection: If running but process is gone
-        if status == "running" and pid:
-            try:
-                import psutil
-
-                if not psutil.pid_exists(pid):
-                    status = "failed"
-                    self._update_task(
-                        task_id,
-                        status="failed",
-                        error="Agent process died unexpectedly (Zombie detected)",
-                        completed_at=datetime.now().isoformat(),
-                    )
-                    logger.warning(f"[AgentManager] Zombie agent detected: {task_id}")
-            except ImportError:
-                pass
-
-        # Read recent output
         output_content = ""
         if output_file.exists():
             try:
-                full_content = output_file.read_text()
-                if full_content:
-                    output_lines = full_content.strip().split("\n")
-                    recent = output_lines[-lines:] if len(output_lines) > lines else output_lines
-                    output_content = "\n".join(recent)
-            except Exception:
-                pass
-
-        # Check log for errors
-        log_content = ""
-        if log_file.exists():
-            try:
-                log_content = log_file.read_text().strip()
-            except Exception:
-                pass
-
-        # Status emoji
-        status_emoji = {
-            "pending": "⏳",
-            "running": "🔄",
-            "completed": "✅",
-            "failed": "❌",
-            "cancelled": "⚠️",
-        }.get(status, "❓")
-
-        # Get cost-tier emoji for visual differentiation
-        cost_emoji = get_agent_emoji(agent_type)
-        display_model = AGENT_DISPLAY_MODELS.get(agent_type, AGENT_DISPLAY_MODELS["_default"])
-
-        result = f"""{cost_emoji} {status_emoji} **Agent Progress**
-
-**Task ID**: {task_id}
-**Agent**: {agent_type}:{display_model}('{description}')
-**Status**: {status}
-"""
-
-        if output_content:
-            result += f"\n**Recent Output** (last {lines} lines):\n```\n{output_content}\n```"
-        elif status == "running":
-            result += "\n*Agent is working... no output yet.*"
-
-        if log_content and status == "failed":
-            # Truncate log if too long
-            if len(log_content) > 500:
-                log_content = log_content[:500] + "..."
-            result += f"\n\n**Error Log**:\n```\n{log_content}\n```"
+                text = output_file.read_text()
+                output_content = "\n".join(text.strip().split("\n")[-lines:])
+            except: pass
+        return f"**Agent Progress**\nID: {task_id}\nStatus: {task['status']}\n\nOutput:\n```\n{output_content}\n```"
 
-        return result
 
-
-# Global manager instance
-_manager: Optional[AgentManager] = None
+_manager: AgentManager | None = None
 _manager_lock = threading.Lock()
 
-
 def get_manager() -> AgentManager:
-    """Get or create the global AgentManager instance."""
     global _manager
     if _manager is None:
         with _manager_lock:
-            # Double-check pattern to avoid race condition
             if _manager is None:
                 _manager = AgentManager()
     return _manager
 
 
-# Tool interface functions
-
-
 async def agent_spawn(
     prompt: str,
     agent_type: str = "explore",
     description: str = "",
+    delegation_reason: str | None = None,
+    expected_outcome: str | None = None,
+    required_tools: list[str] | None = None,
     model: str = "gemini-3-flash",
     thinking_budget: int = 0,
     timeout: int = 300,
     blocking: bool = False,
+    spawning_agent: str | None = None,
+    semantic_first: bool = False,
 ) -> str:
-    """
-    Spawn a background agent.
-
-    Args:
-        prompt: The task for the agent to perform
-        agent_type: Type of agent (explore, dewey, frontend, delphi)
-        description: Short description shown in status
-        model: Model to use (gemini-3-flash, gemini-2.0-flash, claude)
-        thinking_budget: Reserved reasoning tokens
-        timeout: Execution timeout in seconds
-        blocking: If True, wait for completion and return result directly (use for delphi)
-
-    Returns:
-        Task ID and instructions, or full result if blocking=True
-    """
     manager = get_manager()
-
-    # Map agent types to system prompts
-    # ALL agents use invoke_gemini or invoke_openai - NOT Claude directly
-    # explore/dewey/document_writer/multimodal/frontend → gemini-3-flash
-    # delphi → openai gpt-5.2
-    system_prompts = {
-        "explore": """You are a codebase exploration specialist. Find files, patterns, and answer 'where is X?' questions.
-
-MODEL ROUTING (MANDATORY):
-You MUST use invoke_gemini with model="gemini-3-flash" for ALL analysis and reasoning.
-Use Claude's native tools (Read, Grep, Glob) ONLY for file access, then pass content to invoke_gemini.
-
-WORKFLOW:
-1. Use Read/Grep/Glob to get file contents
-2. Call invoke_gemini(prompt="Analyze this: <content>", model="gemini-3-flash", agent_context={"agent_type": "explore"}) for analysis
-3. Return the Gemini response""",
-        "dewey": """You are a documentation and research specialist. Find implementation examples and official docs.
-
-MODEL ROUTING (MANDATORY):
-You MUST use invoke_gemini with model="gemini-3-flash" for ALL analysis, summarization, and reasoning.
-
-WORKFLOW:
-1. Gather information using available tools
-2. Call invoke_gemini(prompt="<task>", model="gemini-3-flash", agent_context={"agent_type": "dewey"}) for processing
-3. Return the Gemini response""",
-        "frontend": """You are a Senior Frontend Architect & UI Designer.
-
-MODEL ROUTING (MANDATORY):
-You MUST use invoke_gemini with model="gemini-3-pro-high" for ALL code generation and design work.
-
-DESIGN PHILOSOPHY:
-- Anti-Generic: Reject standard layouts. Bespoke, asymmetric, distinctive.
-- Library Discipline: Use existing UI libraries (Shadcn, Radix, MUI) if detected.
-- Stack: React/Vue/Svelte, Tailwind/Custom CSS, semantic HTML5.
-
-WORKFLOW:
-1. Analyze requirements
-2. Call invoke_gemini(prompt="Generate frontend code for: <task>", model="gemini-3-pro-high", agent_context={"agent_type": "frontend"})
-3. Return the code""",
-        "delphi": """You are a strategic technical advisor for architecture and hard debugging.
-
-MODEL ROUTING (MANDATORY):
-You MUST use invoke_openai with model="gpt-5.2" for ALL strategic advice and analysis.
-
-WORKFLOW:
-1. Gather context about the problem
-2. Call invoke_openai(prompt="<problem description>", model="gpt-5.2", agent_context={"agent_type": "delphi"})
-3. Return the GPT response""",
-        "document_writer": """You are a Technical Documentation Specialist.
-
-MODEL ROUTING (MANDATORY):
-You MUST use invoke_gemini with model="gemini-3-flash" for ALL documentation generation.
-
-DOCUMENT TYPES: README, API docs, ADRs, user guides, inline docs.
-
-WORKFLOW:
-1. Gather context about what to document
-2. Call invoke_gemini(prompt="Write documentation for: <topic>", model="gemini-3-flash", agent_context={"agent_type": "document_writer"})
-3. Return the documentation""",
-        "multimodal": """You interpret media files (PDFs, images, diagrams, screenshots).
-
-MODEL ROUTING (MANDATORY):
-You MUST use invoke_gemini with model="gemini-3-flash" for ALL visual analysis.
-
-WORKFLOW:
-1. Receive file path and extraction goal
-2. Call invoke_gemini(prompt="Analyze this file: <path>. Extract: <goal>", model="gemini-3-flash", agent_context={"agent_type": "multimodal"})
-3. Return extracted information only""",
-        "planner": """You are a pre-implementation planning specialist. You analyze requests and produce structured implementation plans BEFORE any code changes begin.
-
-PURPOSE:
-- Analyze requests and produce actionable implementation plans
-- Identify dependencies and parallelization opportunities
-- Enable efficient parallel execution by the orchestrator
-- Prevent wasted effort through upfront planning
-
-METHODOLOGY:
-1. EXPLORE FIRST: Spawn explore agents IN PARALLEL to understand the codebase
-2. DECOMPOSE: Break request into atomic, single-purpose tasks
-3. ANALYZE DEPENDENCIES: What blocks what? What can run in parallel?
-4. ASSIGN AGENTS: Map each task to the right specialist (explore/dewey/frontend/delphi)
-5. OUTPUT STRUCTURED PLAN: Use the required format below
-
-REQUIRED OUTPUT FORMAT:
-```
-## PLAN: [Brief title]
-
-### ANALYSIS
-- **Request**: [One sentence summary]
-- **Scope**: [What's in/out of scope]
-- **Risk Level**: [Low/Medium/High]
-
-### EXECUTION PHASES
-
-#### Phase 1: [Name] (PARALLEL)
-| Task | Agent | Files | Est |
-|------|-------|-------|-----|
-| [description] | explore | file.py | S/M/L |
-
-#### Phase 2: [Name] (SEQUENTIAL after Phase 1)
-| Task | Agent | Files | Est |
-|------|-------|-------|-----|
-
-### AGENT SPAWN COMMANDS
-```python
-# Phase 1 - Fire all in parallel
-agent_spawn(prompt="...", agent_type="explore", description="...")
-```
-```
-
-CONSTRAINTS:
-- You ONLY plan. You NEVER execute code changes.
-- Every task must have a clear agent assignment
-- Parallel phases must be truly independent
-- Include ready-to-use agent_spawn commands""",
-        "research-lead": """You coordinate research tasks by spawning explore and dewey agents in parallel.
-
-## Your Role
-1. Receive research objective from Stravinsky
-2. Decompose into parallel search tasks
-3. Spawn explore/dewey agents for each task
-4. Collect and SYNTHESIZE results
-5. Return structured findings (not raw outputs)
-
-## Output Format
-Always return a Research Brief:
-```json
-{
-  "objective": "Original research goal",
-  "findings": [
-    {"source": "agent_id", "summary": "Key finding", "confidence": "high/medium/low"},
-    ...
-  ],
-  "synthesis": "Combined analysis of all findings",
-  "gaps": ["Information we couldn't find"],
-  "recommendations": ["Suggested next steps"]
-}
-```
-
-MODEL ROUTING:
-Use invoke_gemini with model="gemini-3-flash" for ALL synthesis work.
-""",
-        "implementation-lead": """You coordinate implementation based on research findings.
-
-## Your Role
-1. Receive Research Brief from Stravinsky
-2. Create implementation plan
-3. Delegate to specialists:
-   - frontend: UI/visual work
-   - debugger: Fix failures
-   - code-reviewer: Quality checks
-4. Verify with lsp_diagnostics
-5. Return Implementation Report
-
-## Output Format
-```json
-{
-  "objective": "What was implemented",
-  "files_changed": ["path/to/file.py"],
-  "tests_status": "pass/fail/skipped",
-  "diagnostics": "clean/warnings/errors",
-  "blockers": ["Issues preventing completion"]
-}
-```
-
-## Escalation Rules
-- After 2 failed attempts → spawn debugger
-- After debugger fails → escalate to Stravinsky with context
-- NEVER call delphi directly
-""",
-    }
-
-    system_prompt = system_prompts.get(agent_type, None)
-
-    # Model routing (MANDATORY - enforced in system prompts):
-    # - explore, dewey, document_writer, multimodal → invoke_gemini(gemini-3-flash)
-    # - frontend → invoke_gemini(gemini-3-pro-high)
-    # - delphi → invoke_openai(gpt-5.2)
-    # - Unknown agent types (coding tasks) → Claude CLI --model sonnet
-
-    # Get token store for authentication
+    if spawning_agent in ORCHESTRATOR_AGENTS:
+        if not delegation_reason or not expected_outcome or not required_tools:
+            raise ValueError("Orchestrators must provide delegation metadata")
+    if required_tools: validate_agent_tools(agent_type, required_tools)
+    if spawning_agent: validate_agent_hierarchy(spawning_agent, agent_type)
+    system_prompt = f"You are a {agent_type} specialist." 
     from ..auth.token_store import TokenStore
-
     token_store = TokenStore()
-
-    task_id = manager.spawn(
+    task_id = await manager.spawn_async(
         token_store=token_store,
         prompt=prompt,
         agent_type=agent_type,
-        description=description or prompt[:50],
+        description=description,
         system_prompt=system_prompt,
-        model=model,  # Not used for Claude CLI, kept for API compatibility
-        thinking_budget=thinking_budget,  # Not used for Claude CLI, kept for API compatibility
         timeout=timeout,
+        semantic_first=semantic_first,
     )
-
-    # Get display model and cost tier emoji for concise output
-    display_model = AGENT_DISPLAY_MODELS.get(agent_type, AGENT_DISPLAY_MODELS["_default"])
-    cost_emoji = get_agent_emoji(agent_type)
-    short_desc = (description or prompt[:50]).strip()
-
-    # If blocking mode (recommended for delphi), wait for completion
+    if not blocking:
+        monitor_task = asyncio.create_task(manager._monitor_progress_async(task_id))
+        manager._progress_monitors[task_id] = monitor_task
     if blocking:
-        result = manager.get_output(task_id, block=True, timeout=timeout)
-        blocking_msg = colorize_agent_spawn_message(
-            cost_emoji, agent_type, display_model, short_desc, task_id
-        )
-        return f"{blocking_msg} {Colors.BOLD}[BLOCKING]{Colors.RESET}\n\n{result}"
-
-    # Enhanced format with ANSI colors: cost_emoji agent:model('description') status_emoji
-    # 🟢 explore:gemini-3-flash('Find auth...') ⏳
-    # With colors: agent type in cyan, model in yellow, description bold
-    return colorize_agent_spawn_message(
-        cost_emoji, agent_type, display_model, short_desc, task_id
-    )
-
-
-async def agent_output(task_id: str, block: bool = False) -> str:
-    """
-    Get output from a background agent task.
+        return await manager.get_output(task_id, block=True, timeout=timeout)
+    display_model = AGENT_DISPLAY_MODELS.get(agent_type, AGENT_DISPLAY_MODELS["_default"])
+    return format_spawn_output(agent_type, display_model, task_id)
 
-    Args:
-        task_id: The task ID from agent_spawn
-        block: If True, wait for the task to complete (up to 30s)
 
-    Returns:
-        Task status and output
-    """
+async def agent_output(task_id: str, block: bool = False, auto_cleanup: bool = False) -> str:
     manager = get_manager()
-    return manager.get_output(task_id, block=block)
-
-
-async def agent_retry(
-    task_id: str,
-    new_prompt: Optional[str] = None,
-    new_timeout: Optional[int] = None,
-) -> str:
-    """
-    Retry a failed or timed-out background agent.
-
-    Args:
-        task_id: The ID of the task to retry
-        new_prompt: Optional refined prompt for the retry
-        new_timeout: Optional new timeout in seconds
+    return await manager.get_output(task_id, block=block, auto_cleanup=auto_cleanup)
 
-    Returns:
-        New Task ID and status
-    """
+async def agent_retry(task_id: str, new_prompt: str = None, new_timeout: int = None) -> str:
     manager = get_manager()
     task = manager.get_task(task_id)
-
-    if not task:
-        return f"❌ Task {task_id} not found."
-
-    if task["status"] in ["running", "pending"]:
-        return f"⚠️ Task {task_id} is still {task['status']}. Cancel it first if you want to retry."
-
-    prompt = new_prompt or task["prompt"]
-    timeout = new_timeout or task.get("timeout", 300)
-
-    return await agent_spawn(
-        prompt=prompt,
-        agent_type=task["agent_type"],
-        description=f"Retry of {task_id}: {task['description']}",
-        timeout=timeout,
-    )
-
+    if not task: return f"❌ Task {task_id} not found."
+    return await agent_spawn(prompt=new_prompt or task["prompt"], agent_type=task["agent_type"], timeout=new_timeout or task["timeout"])
 
 async def agent_cancel(task_id: str) -> str:
-    """
-    Cancel a running background agent.
-
-    Args:
-        task_id: The task ID to cancel
-
-    Returns:
-        Cancellation result
-    """
     manager = get_manager()
-    success = manager.cancel(task_id)
-
-    if success:
-        return f"✅ Agent task {task_id} has been cancelled."
-    else:
-        task = manager.get_task(task_id)
-        if not task:
-            return f"❌ Task {task_id} not found."
-        else:
-            return f"⚠️ Task {task_id} is not running (status: {task['status']}). Cannot cancel."
-
+    if not manager.get_task(task_id): return f"❌ Task {task_id} not found."
+    if manager.cancel(task_id): return f"✅ Cancelled {task_id}."
+    return f"❌ Could not cancel {task_id}."
 
-async def agent_list() -> str:
-    """
-    List all background agent tasks.
-
-    Returns:
-        Formatted list of tasks
-    """
+async def agent_cleanup(max_age_minutes: int = 30, statuses: list[str] = None) -> str:
     manager = get_manager()
-    tasks = manager.list_tasks()
-
-    if not tasks:
-        return "No background agent tasks found."
-
-    lines = []
-
-    for t in sorted(tasks, key=lambda x: x.get("created_at", ""), reverse=True):
-        status_emoji = {
-            "pending": "⏳",
-            "running": "🔄",
-            "completed": "✅",
-            "failed": "❌",
-            "cancelled": "⚠️",
-        }.get(t["status"], "❓")
-
-        agent_type = t.get("agent_type", "unknown")
-        display_model = AGENT_DISPLAY_MODELS.get(agent_type, AGENT_DISPLAY_MODELS["_default"])
-        cost_emoji = get_agent_emoji(agent_type)
-        desc = t.get("description", t.get("prompt", "")[:40])
-        task_id = t["id"]
-
-        # Concise format with colors: cost_emoji status agent:model('desc') id=xxx
-        # Agent type in cyan, model in yellow, task_id in dim
-        lines.append(
-            f"{cost_emoji} {status_emoji} "
-            f"{Colors.CYAN}{agent_type}{Colors.RESET}:"
-            f"{Colors.YELLOW}{display_model}{Colors.RESET}"
-            f"('{Colors.BOLD}{desc}{Colors.RESET}') "
-            f"id={Colors.BRIGHT_BLACK}{task_id}{Colors.RESET}"
-        )
-
-    return "\n".join(lines)
+    res = manager.cleanup(max_age_minutes, statuses)
+    return res["summary"]
 
+async def agent_list(show_all: bool = False, all_sessions: bool = False) -> str:
+    manager = get_manager()
+    tasks = manager.list_tasks(show_all=show_all, current_session_only=not all_sessions)
+    if not tasks: return "No tasks found."
+    return "\n".join([f"• {t['id']} ({t['status']}) - {t['agent_type']}" for t in tasks])
 
 async def agent_progress(task_id: str, lines: int = 20) -> str:
-    """
-    Get real-time progress from a running background agent.
-
-    Shows the most recent output lines from the agent, useful for
-    monitoring what the agent is currently doing.
-
-    Args:
-        task_id: The task ID from agent_spawn
-        lines: Number of recent output lines to show (default 20)
-
-    Returns:
-        Recent agent output and status
-    """
     manager = get_manager()
-    return manager.get_progress(task_id, lines=lines)
+    return manager.get_progress(task_id, lines)