gobby 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

gobby/mcp_proxy/tools/agents.py

@@ -2,7 +2,7 @@
 Internal MCP tools for Gobby Agent System.
 
 Exposes functionality for:
-- Starting agents (spawn subagents with prompts)
+- Spawning agents (via spawn_agent unified tool)
 - Getting agent results (retrieve completed run output)
 - Listing agents (view runs for a session)
 - Cancelling agents (stop running agents)
@@ -14,69 +14,62 @@ via the downstream proxy pattern (call_tool, list_tools, get_tool_schema).
 from __future__ import annotations
 
 import logging
-import socket
-from collections.abc import Callable
-from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from gobby.agents.context import (
-    ContextResolutionError,
-    ContextResolver,
-    format_injected_prompt,
-)
 from gobby.agents.registry import (
-    RunningAgent,
     RunningAgentRegistry,
     get_running_agent_registry,
 )
-from gobby.agents.spawn import (
-    EmbeddedSpawner,
-    HeadlessSpawner,
-    TerminalSpawner,
-)
 from gobby.mcp_proxy.tools.internal import InternalToolRegistry
-from gobby.utils.project_context import get_project_context
 
 if TYPE_CHECKING:
     from gobby.agents.runner import AgentRunner
-    from gobby.config.app import ContextInjectionConfig
-    from gobby.llm.executor import ToolResult
-    from gobby.mcp_proxy.services.tool_proxy import ToolProxyService
-    from gobby.storage.session_messages import LocalSessionMessageManager
-    from gobby.storage.sessions import LocalSessionManager
 
 logger = logging.getLogger(__name__)
 
 
 def create_agents_registry(
     runner: AgentRunner,
-    session_manager: LocalSessionManager | None = None,
-    message_manager: LocalSessionMessageManager | None = None,
-    context_config: ContextInjectionConfig | None = None,
-    get_session_context: Any | None = None,
     running_registry: RunningAgentRegistry | None = None,
-    tool_proxy_getter: Callable[[], ToolProxyService | None] | None = None,
     workflow_state_manager: Any | None = None,
+    session_manager: Any | None = None,
+    # spawn_agent dependencies
+    agent_loader: Any | None = None,
+    task_manager: Any | None = None,
+    worktree_storage: Any | None = None,
+    git_manager: Any | None = None,
+    clone_storage: Any | None = None,
+    clone_manager: Any | None = None,
 ) -> InternalToolRegistry:
     """
     Create an agent tool registry with all agent-related tools.
 
     Args:
         runner: AgentRunner instance for executing agents.
-        session_manager: Session manager for context resolution.
-        message_manager: Message manager for transcript resolution.
-        context_config: Context injection configuration.
-        get_session_context: Optional callable returning current session context.
         running_registry: Optional in-memory registry for running agents.
-        tool_proxy_getter: Optional callable that returns ToolProxyService for
-            routing tool calls in in-process agents. If not provided, tool calls
-            will fail with "tool not available".
         workflow_state_manager: Optional WorkflowStateManager for stopping workflows
             when agents are killed. If not provided, workflow stop will be skipped.
+        session_manager: Optional LocalSessionManager for resolving session references.
+        agent_loader: Agent definition loader for spawn_agent.
+        task_manager: Task manager for spawn_agent task resolution.
+        worktree_storage: Worktree storage for spawn_agent isolation.
+        git_manager: Git manager for spawn_agent isolation.
+        clone_storage: Clone storage for spawn_agent isolation.
+        clone_manager: Clone git manager for spawn_agent isolation.
 
     Returns:
         InternalToolRegistry with all agent tools registered.
     """
+    from gobby.utils.project_context import get_project_context
+
+    def _resolve_session_id(ref: str) -> str:
+        """Resolve session reference (#N, N, UUID, or prefix) to UUID."""
+        if session_manager is None:
+            return ref  # No resolution available, return as-is
+        project_ctx = get_project_context()
+        project_id = project_ctx.get("id") if project_ctx else None
+        return str(session_manager.resolve_session_reference(ref, project_id))
+
     registry = InternalToolRegistry(
         name="gobby-agents",
         description="Agent spawning - start, monitor, and manage subagents",
@@ -85,704 +78,6 @@ def create_agents_registry(
     # Use provided registry or global singleton
     agent_registry = running_registry or get_running_agent_registry()
 
-    # Create context resolver if managers are provided
-    context_resolver: ContextResolver | None = None
-    context_enabled = True  # Default enabled
-    context_template: str | None = None  # Custom template for injection
-    if session_manager and message_manager:
-        # Use config values if provided, otherwise use defaults
-        if context_config:
-            context_enabled = context_config.enabled
-            context_template = context_config.context_template
-            context_resolver = ContextResolver(
-                session_manager=session_manager,
-                message_manager=message_manager,
-                project_path=None,  # Will be set per-request
-                max_file_size=context_config.max_file_size,
-                max_content_size=context_config.max_content_size,
-                max_transcript_messages=context_config.max_transcript_messages,
-                truncation_suffix=context_config.truncation_suffix,
-            )
-        else:
-            context_resolver = ContextResolver(
-                session_manager=session_manager,
-                message_manager=message_manager,
-                project_path=None,  # Will be set per-request
-            )
-
-    @registry.tool(
-        name="start_agent",
-        description=(
-            "Spawn a subagent to execute a task. Can use a named agent definition "
-            "(e.g. 'validation-runner') or raw parameters. "
-            "Infers context from current project/session. "
-            "Use get_agent_result to poll for completion."
-        ),
-    )
-    async def start_agent(
-        prompt: str,
-        workflow: str | None = None,
-        task: str | None = None,
-        agent: str | None = None,
-        session_context: str = "summary_markdown",
-        mode: str = "terminal",
-        terminal: str = "auto",
-        provider: str | None = None,
-        model: str | None = None,
-        worktree_id: str | None = None,
-        timeout: float = 120.0,
-        max_turns: int = 10,
-        # Optional explicit context (usually inferred)
-        parent_session_id: str | None = None,
-        project_id: str | None = None,
-        machine_id: str | None = None,
-        source: str = "claude",
-    ) -> dict[str, Any]:
-        """
-        Start a new agent to execute a task.
-
-        Args:
-            prompt: The task/prompt for the agent.
-            workflow: Workflow name or path to execute.
-            task: Task ID or 'next' for auto-select.
-            agent: Named agent definition to use.
-            session_context: Context source (summary_markdown, compact_markdown,
-                           session_id:<id>, transcript:<n>, file:<path>).
-            mode: Execution mode (in_process, terminal, embedded, headless).
-            terminal: Terminal for terminal/embedded modes (auto, ghostty, iterm, etc.).
-            provider: LLM provider (claude, gemini, etc.). Defaults to claude.
-            model: Optional model override.
-            worktree_id: Existing worktree to use for terminal mode.
-            timeout: Execution timeout in seconds (default: 120).
-            max_turns: Maximum turns (default: 10).
-            parent_session_id: Explicit parent session ID (usually inferred).
-            project_id: Explicit project ID (usually inferred from context).
-            machine_id: Explicit machine ID (usually inferred from hostname).
-            source: CLI source (claude, gemini, codex).
-
-        Returns:
-            Dict with run_id, child_session_id, status.
-        """
-        from gobby.agents.runner import AgentConfig
-
-        # Validate mode
-        supported_modes = {"in_process", "terminal", "embedded", "headless"}
-        if mode not in supported_modes:
-            return {
-                "success": False,
-                "error": f"Invalid mode '{mode}'. Supported: {supported_modes}",
-            }
-
-        # Validate workflow (reject lifecycle workflows)
-        if workflow:
-            from gobby.workflows.loader import WorkflowLoader
-
-            workflow_loader = WorkflowLoader()
-            is_valid, error_msg = workflow_loader.validate_workflow_for_agent(workflow)
-            if not is_valid:
-                return {
-                    "success": False,
-                    "error": error_msg,
-                }
-
-        # Infer context from project if not provided
-        ctx = get_project_context()
-        if project_id is None:
-            if ctx:
-                project_id = ctx.get("id")
-                project_path = ctx.get("project_path")
-            else:
-                return {
-                    "success": False,
-                    "error": "No project context found. Run from a Gobby project directory.",
-                }
-        else:
-            # project_id was provided - try to get project_path from context if it matches
-            if ctx and ctx.get("id") == project_id:
-                project_path = ctx.get("project_path")
-            else:
-                project_path = None
-
-        # Infer machine_id from hostname if not provided
-        if machine_id is None:
-            machine_id = socket.gethostname()
-
-        # Parent session is required for depth checking
-        if parent_session_id is None:
-            # TODO: In future, could look up current active session for project
-            return {
-                "success": False,
-                "error": "parent_session_id is required (session context inference not yet implemented)",
-            }
-
-        # Check if spawning is allowed
-        can_spawn, reason, _parent_depth = runner.can_spawn(parent_session_id)
-        if not can_spawn:
-            return {
-                "success": False,
-                "error": reason,
-            }
-
-        # Resolve context and inject into prompt
-        effective_prompt = prompt
-        context_was_injected = False
-        if context_resolver and context_enabled and session_context:
-            try:
-                # Update resolver's project path for file resolution
-                context_resolver._project_path = Path(project_path) if project_path else None
-
-                resolved_context = await context_resolver.resolve(
-                    session_context, parent_session_id
-                )
-                if resolved_context:
-                    effective_prompt = format_injected_prompt(
-                        resolved_context, prompt, template=context_template
-                    )
-                    context_was_injected = True
-                    logger.info(
-                        f"Injected context from '{session_context}' into agent prompt "
-                        f"({len(resolved_context)} chars)"
-                    )
-            except ContextResolutionError as e:
-                logger.warning(f"Context resolution failed: {e}")
-                # Continue with original prompt - context injection is best-effort
-                pass
-
-        # Use provided provider or default
-        effective_provider = provider or "claude"
-
-        config = AgentConfig(
-            prompt=effective_prompt,
-            parent_session_id=parent_session_id,
-            project_id=project_id,
-            machine_id=machine_id,
-            source=source,
-            workflow=workflow,
-            task=task,
-            agent=agent,
-            session_context=session_context,
-            mode=mode,
-            terminal=terminal,
-            worktree_id=worktree_id,
-            provider=effective_provider,
-            model=model,
-            max_turns=max_turns,
-            timeout=timeout,
-            project_path=project_path,
-            context_injected=context_was_injected,
-        )
-
-        # Handle different execution modes
-        if mode == "in_process":
-            # In-process mode: run directly via runner
-            async def tool_handler(tool_name: str, arguments: dict[str, Any]) -> ToolResult:
-                from gobby.llm.executor import ToolResult
-
-                # Get tool proxy for routing calls
-                tool_proxy = tool_proxy_getter() if tool_proxy_getter else None
-                if tool_proxy is None:
-                    return ToolResult(
-                        tool_name=tool_name,
-                        success=False,
-                        error=f"Tool proxy not configured - cannot route tool {tool_name}",
-                    )
-
-                # Route the tool call through the MCP proxy
-                try:
-                    result = await tool_proxy.call_tool_by_name(tool_name, arguments)
-
-                    # Handle error response format from call_tool_by_name
-                    if isinstance(result, dict) and result.get("success") is False:
-                        return ToolResult(
-                            tool_name=tool_name,
-                            success=False,
-                            error=result.get("error", f"Tool {tool_name} failed"),
-                        )
-
-                    # Successful tool call
-                    return ToolResult(
-                        tool_name=tool_name,
-                        success=True,
-                        result=result,
-                    )
-                except Exception as e:
-                    logger.warning(f"Tool call failed for {tool_name}: {e}")
-                    return ToolResult(
-                        tool_name=tool_name,
-                        success=False,
-                        error=str(e),
-                    )
-
-            # Load available tools for the agent
-            from gobby.llm.executor import ToolSchema
-
-            tool_schemas: list[ToolSchema] = []
-            tool_proxy = tool_proxy_getter() if tool_proxy_getter else None
-            if tool_proxy:
-                # Get internal servers that have tools
-                internal_servers = ["gobby-tasks", "gobby-memory", "gobby-sessions"]
-                for srv in internal_servers:
-                    try:
-                        tools_result = await tool_proxy.list_tools(srv)
-                        if tools_result.get("success"):
-                            for tool_brief in tools_result.get("tools", []):
-                                # Get full schema for each tool
-                                schema_result = await tool_proxy.get_tool_schema(
-                                    srv, tool_brief["name"]
-                                )
-                                if schema_result.get("success"):
-                                    tool_data = schema_result.get("tool", {})
-                                    tool_schemas.append(
-                                        ToolSchema(
-                                            name=tool_brief["name"],
-                                            description=tool_brief.get("brief", ""),
-                                            input_schema=tool_data.get("inputSchema", {}),
-                                            server_name=srv,
-                                        )
-                                    )
-                    except Exception as e:
-                        logger.debug(f"Could not load tools from {srv}: {e}")
-
-            # Set tools on config
-            config.tools = tool_schemas
-            logger.info(f"Loaded {len(tool_schemas)} tools for in-process agent")
-
-            result = await runner.run(config, tool_handler=tool_handler)
-
-            return {
-                "success": result.status in ("success", "partial"),
-                "run_id": result.run_id,
-                "status": result.status,
-                "output": result.output,
-                "error": result.error,
-                "turns_used": result.turns_used,
-                "tool_calls_count": len(result.tool_calls),
-            }
-
-        # Special handling for Gemini terminal mode: requires preflight session capture
-        # Gemini CLI in interactive mode can't introspect its session_id, so we:
-        # 1. Launch preflight to capture session_id from stream-json output
-        # 2. Create Gobby session with external_id = gemini's session_id
-        # 3. Launch interactive with -r {session_id} to resume
-        if mode == "terminal" and effective_provider == "gemini":
-            from gobby.agents.spawn import (
-                build_gemini_command_with_resume,
-                prepare_gemini_spawn_with_preflight,
-            )
-
-            # Ensure project_id is non-None for spawning
-            if project_id is None:
-                return {
-                    "success": False,
-                    "error": "project_id is required for spawning Gemini agent",
-                }
-
-            # Determine working directory
-            cwd = project_path or "."
-
-            try:
-                # Preflight capture: gets Gemini's session_id and creates linked Gobby session
-                spawn_context = await prepare_gemini_spawn_with_preflight(
-                    session_manager=runner._child_session_manager,
-                    parent_session_id=parent_session_id,
-                    project_id=project_id,
-                    machine_id=socket.gethostname(),
-                    workflow_name=workflow,
-                    git_branch=None,  # Will be detected by hook
-                )
-            except FileNotFoundError as e:
-                return {
-                    "success": False,
-                    "error": str(e),
-                }
-            except Exception as e:
-                logger.error(f"Gemini preflight capture failed: {e}", exc_info=True)
-                return {
-                    "success": False,
-                    "error": f"Gemini preflight capture failed: {e}",
-                }
-
-            # Extract IDs from prepared spawn context
-            gobby_session_id = spawn_context.session_id
-            gemini_session_id = spawn_context.env_vars["GOBBY_GEMINI_EXTERNAL_ID"]
-
-            # Build command with session context injected into prompt
-            # build_gemini_command_with_resume handles the context prefix
-            cmd = build_gemini_command_with_resume(
-                gemini_external_id=gemini_session_id,
-                prompt=effective_prompt,
-                auto_approve=True,  # Subagents need to work autonomously
-                gobby_session_id=gobby_session_id,
-            )
-
-            # Spawn in terminal
-            terminal_spawner = TerminalSpawner()
-            terminal_result = terminal_spawner.spawn(
-                command=cmd,
-                cwd=cwd,
-                terminal=terminal,
-            )
-
-            if not terminal_result.success:
-                return {
-                    "success": False,
-                    "error": terminal_result.error or terminal_result.message,
-                    "child_session_id": gobby_session_id,
-                }
-
-            # Register in running agents registry
-            registry = get_running_agent_registry()
-            running_agent = RunningAgent(
-                run_id=f"gemini-{gemini_session_id[:8]}",
-                session_id=gobby_session_id,
-                parent_session_id=parent_session_id,
-                pid=terminal_result.pid,
-                mode="terminal",
-                provider="gemini",
-                workflow_name=workflow,
-            )
-            registry.add(running_agent)
-
-            return {
-                "success": True,
-                "run_id": running_agent.run_id,
-                "child_session_id": gobby_session_id,
-                "gemini_session_id": gemini_session_id,
-                "mode": "terminal",
-                "message": (f"Gemini agent spawned in terminal with session {gobby_session_id}"),
-                "pid": terminal_result.pid,
-            }
-
-        # Special handling for Codex terminal mode: requires preflight session capture
-        # Codex outputs session_id in startup banner, which we parse from `codex exec "exit"`
-        if mode == "terminal" and effective_provider == "codex":
-            from gobby.agents.spawn import (
-                build_codex_command_with_resume,
-                prepare_codex_spawn_with_preflight,
-            )
-
-            # Ensure project_id is non-None for spawning
-            if project_id is None:
-                return {
-                    "success": False,
-                    "error": "project_id is required for spawning Codex agent",
-                }
-
-            # Determine working directory
-            cwd = project_path or "."
-
-            try:
-                # Preflight capture: gets Codex's session_id and creates linked Gobby session
-                spawn_context = await prepare_codex_spawn_with_preflight(
-                    session_manager=runner._child_session_manager,
-                    parent_session_id=parent_session_id,
-                    project_id=project_id,
-                    machine_id=socket.gethostname(),
-                    workflow_name=workflow,
-                    git_branch=None,  # Will be detected by hook
-                )
-            except FileNotFoundError as e:
-                return {
-                    "success": False,
-                    "error": str(e),
-                }
-            except Exception as e:
-                logger.error(f"Codex preflight capture failed: {e}", exc_info=True)
-                return {
-                    "success": False,
-                    "error": f"Codex preflight capture failed: {e}",
-                }
-
-            # Extract IDs from prepared spawn context
-            gobby_session_id = spawn_context.session_id
-            codex_session_id = spawn_context.env_vars["GOBBY_CODEX_EXTERNAL_ID"]
-
-            # Build command with session context injected into prompt
-            # build_codex_command_with_resume handles the context prefix
-            cmd = build_codex_command_with_resume(
-                codex_external_id=codex_session_id,
-                prompt=effective_prompt,
-                auto_approve=True,  # --full-auto for sandboxed autonomy
-                gobby_session_id=gobby_session_id,
-                working_directory=cwd,
-            )
-
-            # Spawn in terminal
-            terminal_spawner = TerminalSpawner()
-            terminal_result = terminal_spawner.spawn(
-                command=cmd,
-                cwd=cwd,
-                terminal=terminal,
-            )
-
-            if not terminal_result.success:
-                return {
-                    "success": False,
-                    "error": terminal_result.error or terminal_result.message,
-                    "child_session_id": gobby_session_id,
-                }
-
-            # Register in running agents registry
-            registry = get_running_agent_registry()
-            running_agent = RunningAgent(
-                run_id=f"codex-{codex_session_id[:8]}",
-                session_id=gobby_session_id,
-                parent_session_id=parent_session_id,
-                pid=terminal_result.pid,
-                mode="terminal",
-                provider="codex",
-                workflow_name=workflow,
-            )
-            registry.add(running_agent)
-
-            return {
-                "success": True,
-                "run_id": running_agent.run_id,
-                "child_session_id": gobby_session_id,
-                "codex_session_id": codex_session_id,
-                "mode": "terminal",
-                "message": (f"Codex agent spawned in terminal with session {gobby_session_id}"),
-                "pid": terminal_result.pid,
-            }
-
-        # Terminal, embedded, or headless mode: prepare run then spawn
-        # Use prepare_run to create session and run records
-        from gobby.llm.executor import AgentResult
-
-        prepare_result = runner.prepare_run(config)
-        if isinstance(prepare_result, AgentResult):
-            # prepare_run returns AgentResult on error
-            return {
-                "success": False,
-                "error": prepare_result.error,
-            }
-
-        # Successfully prepared - we have context with session and run
-        context = prepare_result
-
-        # Validate context has required session and run (should always be set after prepare_run)
-        if context.session is None or context.run is None:
-            return {
-                "success": False,
-                "error": "Internal error: context missing session or run after prepare_run",
-            }
-
-        # Type narrowing: assign to non-optional variables
-        child_session = context.session
-        agent_run = context.run
-
-        # Determine working directory
-        cwd = project_path or "."
-
-        # Ensure project_id is non-None for spawn calls
-        if project_id is None:
-            return {
-                "success": False,
-                "error": "project_id is required for spawning",
-            }
-
-        if mode == "terminal":
-            # Spawn in external terminal
-            terminal_spawner = TerminalSpawner()
-            terminal_result = terminal_spawner.spawn_agent(
-                cli=effective_provider,  # claude, gemini, codex
-                cwd=cwd,
-                session_id=child_session.id,
-                parent_session_id=parent_session_id,
-                agent_run_id=agent_run.id,
-                project_id=project_id,
-                workflow_name=workflow,
-                agent_depth=child_session.agent_depth,
-                max_agent_depth=runner._child_session_manager.max_agent_depth,
-                terminal=terminal,
-                prompt=effective_prompt,
-            )
-
-            if not terminal_result.success:
-                return {
-                    "success": False,
-                    "error": terminal_result.error or terminal_result.message,
-                    "run_id": agent_run.id,
-                    "child_session_id": child_session.id,
-                }
-
-            # Register in running agents registry
-            running_agent = RunningAgent(
-                run_id=agent_run.id,
-                session_id=child_session.id,
-                parent_session_id=parent_session_id,
-                mode="terminal",
-                pid=terminal_result.pid,
-                terminal_type=terminal_result.terminal_type,
-                provider=effective_provider,
-                workflow_name=workflow,
-                worktree_id=worktree_id,
-            )
-            agent_registry.add(running_agent)
-
-            return {
-                "success": True,
-                "run_id": agent_run.id,
-                "child_session_id": child_session.id,
-                "status": "pending",
-                "message": f"Agent spawned in {terminal_result.terminal_type} (PID: {terminal_result.pid})",
-                "terminal_type": terminal_result.terminal_type,
-                "pid": terminal_result.pid,
-            }
-
-        elif mode == "embedded":
-            # Spawn with PTY for UI attachment
-            embedded_spawner = EmbeddedSpawner()
-            embedded_result = embedded_spawner.spawn_agent(
-                cli=effective_provider,
-                cwd=cwd,
-                session_id=child_session.id,
-                parent_session_id=parent_session_id,
-                agent_run_id=agent_run.id,
-                project_id=project_id,
-                workflow_name=workflow,
-                agent_depth=child_session.agent_depth,
-                max_agent_depth=runner._child_session_manager.max_agent_depth,
-                prompt=effective_prompt,
-            )
-
-            if not embedded_result.success:
-                return {
-                    "success": False,
-                    "error": embedded_result.error or embedded_result.message,
-                    "run_id": agent_run.id,
-                    "child_session_id": child_session.id,
-                }
-
-            # Register in running agents registry
-            running_agent = RunningAgent(
-                run_id=agent_run.id,
-                session_id=child_session.id,
-                parent_session_id=parent_session_id,
-                mode="embedded",
-                pid=embedded_result.pid,
-                master_fd=embedded_result.master_fd,
-                provider=effective_provider,
-                workflow_name=workflow,
-                worktree_id=worktree_id,
-            )
-            agent_registry.add(running_agent)
-
-            return {
-                "success": True,
-                "run_id": agent_run.id,
-                "child_session_id": child_session.id,
-                "status": "pending",
-                "message": f"Agent spawned with PTY (PID: {embedded_result.pid})",
-                "pid": embedded_result.pid,
-                "master_fd": embedded_result.master_fd,
-            }
-
-        else:  # headless mode
-            # Spawn headless with output capture
-            headless_spawner = HeadlessSpawner()
-            headless_result = headless_spawner.spawn_agent(
-                cli=effective_provider,
-                cwd=cwd,
-                session_id=child_session.id,
-                parent_session_id=parent_session_id,
-                agent_run_id=agent_run.id,
-                project_id=project_id,
-                workflow_name=workflow,
-                agent_depth=child_session.agent_depth,
-                max_agent_depth=runner._child_session_manager.max_agent_depth,
-                prompt=effective_prompt,
-            )
-
-            if not headless_result.success:
-                return {
-                    "success": False,
-                    "error": headless_result.error or headless_result.message,
-                    "run_id": agent_run.id,
-                    "child_session_id": child_session.id,
-                }
-
-            # IMPORTANT: For headless mode with -p flag, hooks are NOT called.
-            # Claude's print mode bypasses the hook system entirely.
-            # We must manually mark the agent run as started.
-            try:
-                runner._run_storage.start(agent_run.id)
-                logger.info(f"Manually started headless agent run {agent_run.id}")
-            except Exception as e:
-                logger.warning(f"Failed to manually start agent run: {e}")
-
-            # Register in running agents registry
-            running_agent = RunningAgent(
-                run_id=agent_run.id,
-                session_id=child_session.id,
-                parent_session_id=parent_session_id,
-                mode="headless",
-                pid=headless_result.pid,
-                provider=effective_provider,
-                workflow_name=workflow,
-                worktree_id=worktree_id,
-            )
-            agent_registry.add(running_agent)
-
-            # Start background task to monitor process completion
-            import asyncio
-
-            async def monitor_headless_process() -> None:
-                """Monitor headless process and update status on completion."""
-                try:
-                    process = headless_result.process
-                    if process is None:
-                        return
-
-                    # Wait for process to complete
-                    loop = asyncio.get_running_loop()
-                    return_code = await loop.run_in_executor(None, process.wait)
-
-                    # Capture output
-                    output = ""
-                    if process.stdout:
-                        output = process.stdout.read() or ""
-
-                    # Update agent run status
-                    if return_code == 0:
-                        runner._run_storage.complete(
-                            agent_run.id,
-                            result=output,
-                            tool_calls_count=0,
-                            turns_used=1,
-                        )
-                        logger.info(f"Headless agent {agent_run.id} completed successfully")
-                    else:
-                        runner._run_storage.fail(
-                            agent_run.id, error=f"Process exited with code {return_code}"
-                        )
-                        logger.warning(
-                            f"Headless agent {agent_run.id} failed with code {return_code}"
-                        )
-
-                    # Remove from running agents registry
-                    agent_registry.remove(agent_run.id)
-
-                except Exception as e:
-                    logger.error(f"Error monitoring headless process: {e}")
-                    try:
-                        runner._run_storage.fail(agent_run.id, error=str(e))
-                        agent_registry.remove(agent_run.id)
-                    except Exception:
-                        pass  # nosec B110 - best-effort cleanup during error handling
-
-            # Schedule monitoring task and store reference to prevent GC
-            running_agent.monitor_task = asyncio.create_task(monitor_headless_process())
-
-            return {
-                "success": True,
-                "run_id": agent_run.id,
-                "child_session_id": child_session.id,
-                "status": "running",  # Now "running" since we manually started it
-                "message": f"Agent spawned headless (PID: {headless_result.pid})",
-                "pid": headless_result.pid,
-            }
-
     @registry.tool(
         name="get_agent_result",
         description="Get the result of a completed agent run.",
@@ -822,7 +117,7 @@ def create_agents_registry(
 
     @registry.tool(
         name="list_agents",
-        description="List agent runs for a session.",
+        description="List agent runs for a session. Accepts #N, N, UUID, or prefix for session_id.",
     )
     async def list_agents(
         parent_session_id: str,
@@ -833,14 +128,20 @@ def create_agents_registry(
         List agent runs for a session.
 
         Args:
-            parent_session_id: The parent session ID.
+            parent_session_id: Session reference (accepts #N, N, UUID, or prefix) for the parent.
             status: Optional status filter (pending, running, success, error, timeout, cancelled).
             limit: Maximum results (default: 20).
 
         Returns:
             Dict with list of agent runs.
         """
-        runs = runner.list_runs(parent_session_id, status=status, limit=limit)
+        # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+        try:
+            resolved_parent_id = _resolve_session_id(parent_session_id)
+        except ValueError as e:
+            return {"success": False, "error": str(e)}
+
+        runs = runner.list_runs(resolved_parent_id, status=status, limit=limit)
 
         return {
             "success": True,
@@ -938,6 +239,12 @@ def create_agents_registry(
         agent = agent_registry.get(run_id)
         session_id = agent.session_id if agent else None
 
+        # Database fallback: if not in registry, look up from DB
+        if session_id is None:
+            db_run = runner.get_run(run_id)
+            if db_run and db_run.child_session_id:
+                session_id = db_run.child_session_id
+
         # Kill via registry (run in thread to avoid blocking event loop)
         import asyncio
 
@@ -962,7 +269,7 @@ def create_agents_registry(
 
     @registry.tool(
         name="can_spawn_agent",
-        description="Check if an agent can be spawned from the current session.",
+        description="Check if an agent can be spawned from the current session. Accepts #N, N, UUID, or prefix for session_id.",
     )
     async def can_spawn_agent(parent_session_id: str) -> dict[str, Any]:
         """
@@ -971,12 +278,18 @@ def create_agents_registry(
         This checks the agent depth limit to prevent infinite nesting.
 
         Args:
-            parent_session_id: The session that would spawn the agent.
+            parent_session_id: Session reference (accepts #N, N, UUID, or prefix) for the session that would spawn the agent.
 
         Returns:
             Dict with can_spawn boolean and reason.
         """
-        can_spawn, reason, _parent_depth = runner.can_spawn(parent_session_id)
+        # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+        try:
+            resolved_parent_id = _resolve_session_id(parent_session_id)
+        except ValueError as e:
+            return {"can_spawn": False, "reason": str(e)}
+
+        can_spawn, reason, _parent_depth = runner.can_spawn(resolved_parent_id)
         return {
             "can_spawn": can_spawn,
             "reason": reason,
@@ -984,7 +297,7 @@ def create_agents_registry(
 
     @registry.tool(
         name="list_running_agents",
-        description="List all currently running agents (in-memory process state).",
+        description="List all currently running agents (in-memory process state). Accepts #N, N, UUID, or prefix for session_id.",
     )
     async def list_running_agents(
         parent_session_id: str | None = None,
@@ -997,14 +310,19 @@ def create_agents_registry(
         including PIDs and process handles not stored in the database.
 
         Args:
-            parent_session_id: Optional filter by parent session.
+            parent_session_id: Optional session reference (accepts #N, N, UUID, or prefix) to filter by parent.
             mode: Optional filter by execution mode (terminal, embedded, headless).
 
         Returns:
             Dict with list of running agents.
         """
         if parent_session_id:
-            agents = agent_registry.list_by_parent(parent_session_id)
+            # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+            try:
+                resolved_parent_id = _resolve_session_id(parent_session_id)
+            except ValueError as e:
+                return {"success": False, "error": str(e)}
+            agents = agent_registry.list_by_parent(resolved_parent_id)
         elif mode:
             agents = agent_registry.list_by_mode(mode)
         else:
@@ -1100,4 +418,22 @@ def create_agents_registry(
             "by_parent_count": len(by_parent),
         }
 
+    # Register spawn_agent tool from spawn_agent module
+    from gobby.mcp_proxy.tools.spawn_agent import create_spawn_agent_registry
+
+    spawn_registry = create_spawn_agent_registry(
+        runner=runner,
+        agent_loader=agent_loader,
+        task_manager=task_manager,
+        worktree_storage=worktree_storage,
+        git_manager=git_manager,
+        clone_storage=clone_storage,
+        clone_manager=clone_manager,
+        session_manager=session_manager,
+    )
+
+    # Merge spawn_agent tools into agents registry
+    for tool_name, tool in spawn_registry._tools.items():
+        registry._tools[tool_name] = tool
+
     return registry