ripperdoc 0.2.9__py3-none-any.whl → 0.3.0__py3-none-any.whl

ripperdoc/tools/task_tool.py

@@ -2,8 +2,13 @@
 
 from __future__ import annotations
 
+import asyncio
+import os
+import threading
 import time
-from typing import Any, AsyncGenerator, Callable, Dict, Iterable, List, Optional
+from dataclasses import dataclass
+from typing import Any, AsyncGenerator, Callable, Dict, Iterable, List, Optional, Sequence, Union
+from uuid import uuid4
 
 from pydantic import BaseModel, Field
 
@@ -20,29 +25,173 @@ from ripperdoc.core.agents import (
 )
 from ripperdoc.core.query import QueryContext, query
 from ripperdoc.core.system_prompt import build_environment_prompt
-from ripperdoc.core.tool import Tool, ToolOutput, ToolProgress, ToolResult, ToolUseContext
-from ripperdoc.utils.messages import AssistantMessage, create_user_message
+from ripperdoc.core.tool import (
+    Tool,
+    ToolOutput,
+    ToolProgress,
+    ToolResult,
+    ToolUseContext,
+    ValidationResult,
+)
+from ripperdoc.utils.messages import AssistantMessage, UserMessage, create_user_message
 from ripperdoc.utils.log import get_logger
 
 logger = get_logger()
 
 
+MessageType = Union[UserMessage, AssistantMessage]
+
+
+@dataclass
+class AgentRunRecord:
+    """In-memory record for a subagent run (foreground or background)."""
+
+    agent_id: str
+    agent_type: str
+    tools: List[Tool[Any, Any]]
+    system_prompt: str
+    history: List[MessageType]
+    missing_tools: List[str]
+    model_used: Optional[str]
+    start_time: float
+    duration_ms: float = 0.0
+    tool_use_count: int = 0
+    status: str = "running"
+    result_text: Optional[str] = None
+    error: Optional[str] = None
+    task: Optional[asyncio.Task] = None
+    is_background: bool = False
+
+
+_AGENT_RUNS: Dict[str, AgentRunRecord] = {}
+_AGENT_RUNS_LOCK = threading.Lock()
+DEFAULT_AGENT_RUN_TTL_SEC = float(os.getenv("RIPPERDOC_AGENT_RUN_TTL_SEC", "3600"))
+
+
+def _new_agent_id() -> str:
+    return f"agent_{uuid4().hex[:8]}"
+
+
+def _register_agent_run(record: AgentRunRecord) -> None:
+    with _AGENT_RUNS_LOCK:
+        _AGENT_RUNS[record.agent_id] = record
+    prune_agent_runs()
+
+
+def _get_agent_run(agent_id: str) -> Optional[AgentRunRecord]:
+    with _AGENT_RUNS_LOCK:
+        return _AGENT_RUNS.get(agent_id)
+
+
+def _snapshot_agent_run(record: AgentRunRecord) -> dict:
+    duration_ms = (
+        record.duration_ms
+        if record.duration_ms
+        else max((time.time() - record.start_time) * 1000.0, 0.0)
+    )
+    return {
+        "id": record.agent_id,
+        "agent_type": record.agent_type,
+        "status": record.status,
+        "duration_ms": duration_ms,
+        "tool_use_count": record.tool_use_count,
+        "missing_tools": list(record.missing_tools),
+        "model_used": record.model_used,
+        "result_text": record.result_text,
+        "error": record.error,
+        "is_background": record.is_background,
+    }
+
+
+def list_agent_runs() -> List[str]:
+    """Return known subagent run ids."""
+    prune_agent_runs()
+    with _AGENT_RUNS_LOCK:
+        return list(_AGENT_RUNS.keys())
+
+
+def get_agent_run_snapshot(agent_id: str) -> Optional[dict]:
+    """Return a snapshot of a subagent run by id."""
+    record = _get_agent_run(agent_id)
+    if not record:
+        return None
+    return _snapshot_agent_run(record)
+
+
+def prune_agent_runs(max_age_seconds: Optional[float] = None) -> int:
+    """Remove finished subagent runs older than the TTL."""
+    ttl = DEFAULT_AGENT_RUN_TTL_SEC if max_age_seconds is None else max_age_seconds
+    if ttl is None or ttl <= 0:
+        return 0
+    now = time.time()
+    removed = 0
+    with _AGENT_RUNS_LOCK:
+        for agent_id, record in list(_AGENT_RUNS.items()):
+            if record.status == "running" or record.task:
+                continue
+            age = now - record.start_time
+            if age > ttl:
+                _AGENT_RUNS.pop(agent_id, None)
+                removed += 1
+    return removed
+
+
+async def cancel_agent_run(agent_id: str) -> bool:
+    """Cancel a running subagent, if possible."""
+    record = _get_agent_run(agent_id)
+    if not record or not record.task or record.task.done():
+        return False
+    record.task.cancel()
+    try:
+        await record.task
+    except asyncio.CancelledError:
+        pass
+    record.status = "cancelled"
+    record.error = record.error or "Cancelled by user."
+    record.duration_ms = (time.time() - record.start_time) * 1000
+    record.task = None
+    return True
+
+
 class TaskToolInput(BaseModel):
     """Input schema for delegating to a subagent."""
 
-    prompt: str = Field(description="Detailed task description for the subagent to perform")
-    subagent_type: str = Field(description="Agent type to run (matches agent frontmatter name)")
+    prompt: Optional[str] = Field(
+        default=None,
+        description="Detailed task description for the subagent to perform.",
+    )
+    subagent_type: Optional[str] = Field(
+        default=None,
+        description="Agent type to run (matches agent frontmatter name). Required for new runs.",
+    )
+    run_in_background: bool = Field(
+        default=False,
+        description="If true, start the agent in the background and return immediately.",
+    )
+    resume: Optional[str] = Field(
+        default=None,
+        description="Agent id to resume or fetch results for a background run.",
+    )
+    wait: bool = Field(
+        default=True,
+        description="When resuming a background agent, wait for completion before returning.",
+    )
 
 
 class TaskToolOutput(BaseModel):
     """Summary of a completed subagent run."""
 
+    agent_id: Optional[str] = None
     agent_type: str
     result_text: str
     duration_ms: float
     tool_use_count: int
     missing_tools: List[str] = Field(default_factory=list)
     model_used: Optional[str] = None
+    status: str = "completed"
+    is_background: bool = False
+    is_resumed: bool = False
+    error: Optional[str] = None
 
 
 class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
@@ -101,7 +250,7 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
             f"The {task_tool_name} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.\n\n"
             f"Available agent types and the tools they have access to:\n"
             f"{agent_block}\n\n"
-            f"When using the {task_tool_name} tool, you must specify a subagent_type parameter to select which agent type to use.\n\n"
+            f"When starting a new agent with the {task_tool_name} tool, you must specify a subagent_type parameter to select which agent type to use.\n\n"
             f"When NOT to use the {task_tool_name} tool:\n"
             f"- If you want to read a specific file path, use the {file_read_tool_name} or {search_tool_name} tool instead of the {task_tool_name} tool, to find the match more quickly\n"
             f'- If you are searching for a specific class definition like "class Foo", use the {search_tool_name} tool instead, to find the match more quickly\n'
@@ -112,11 +261,11 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
             "Usage notes:\n"
             "- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses\n"
             "- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.\n"
-            f"- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will need to use {background_fetch_tool_name} to retrieve its results once it's done. You can continue to work while background agents run - When you need their results to continue you can use {background_fetch_tool_name} in blocking mode to pause and wait for their results.\n"
-            "- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.\n"
-            "- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.\n"
+            f"- Use run_in_background=true to launch an agent asynchronously. The tool will return an agent_id immediately for later retrieval.\n"
+            f"- Fetch background results by calling {background_fetch_tool_name} with resume=<agent_id>. If the agent is still running, set wait=true to block or wait=false to get status only.\n"
+            "- To continue a completed agent, call Task with resume=<agent_id> and a new prompt.\n"
             "- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.\n"
-            '- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.\n'
+            "- Agents can opt into parent context by setting fork_context: true in their frontmatter. When enabled, they receive the full conversation history before the tool call.\n"
             "- The agent's outputs should generally be trusted\n"
             "- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent\n"
             "- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.\n"
@@ -125,7 +274,7 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
             "Example usage:\n"
             "\n"
             "<example_agent_descriptions>\n"
-            '"code-reviewer": use this agent after you are done writing a signficant piece of code\n'
+            '"code-reviewer": use this agent after you are done writing a significant piece of code\n'
             '"greeting-responder": use this agent when to respond to user greetings with a friendly joke\n'
             "</example_agent_description>\n"
             "\n"
@@ -144,7 +293,7 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
             "}\n"
             "</code>\n"
             "<commentary>\n"
-            "Since a signficant piece of code was written and the task was completed, now use the code-reviewer agent to review the code\n"
+            "Since a significant piece of code was written and the task was completed, now use the code-reviewer agent to review the code\n"
             "</commentary>\n"
             "assistant: Now let me use the code-reviewer agent to review the code\n"
             f"assistant: Uses the {task_tool_name} tool to launch the code-reviewer agent \n"
@@ -165,20 +314,60 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
     def is_concurrency_safe(self) -> bool:
         return True
 
+    async def validate_input(
+        self, input_data: TaskToolInput, context: Optional[ToolUseContext] = None
+    ) -> ValidationResult:
+        del context
+        if input_data.resume and input_data.run_in_background:
+            return ValidationResult(
+                result=False,
+                message="run_in_background cannot be used when resuming an agent.",
+            )
+        if input_data.resume:
+            if input_data.prompt is not None and not input_data.prompt.strip():
+                return ValidationResult(
+                    result=False,
+                    message="prompt cannot be empty when resuming with new work.",
+                )
+            return ValidationResult(result=True)
+
+        if not input_data.subagent_type:
+            return ValidationResult(
+                result=False,
+                message="subagent_type is required when starting a new agent.",
+            )
+        if not input_data.prompt or not input_data.prompt.strip():
+            return ValidationResult(
+                result=False,
+                message="prompt is required when starting a new agent.",
+            )
+        return ValidationResult(result=True)
+
     def render_result_for_assistant(self, output: TaskToolOutput) -> str:
         details: List[str] = []
+        if output.agent_id:
+            details.append(f"id={output.agent_id}")
+        if output.status and output.status != "completed":
+            details.append(output.status)
         if output.tool_use_count:
             details.append(f"{output.tool_use_count} tool uses")
         details.append(f"{output.duration_ms / 1000:.1f}s")
         if output.missing_tools:
             details.append(f"missing tools: {', '.join(output.missing_tools)}")
+        if output.error:
+            details.append(f"error: {output.error}")
 
         suffix = f" ({'; '.join(details)})" if details else ""
         return f"[subagent:{output.agent_type}] {output.result_text}{suffix}"
 
     def render_tool_use_message(self, input_data: TaskToolInput, verbose: bool = False) -> str:
         del verbose
-        return f"Task via {input_data.subagent_type}: {input_data.prompt}"
+        if input_data.resume:
+            return f"Resume subagent {input_data.resume}"
+        label = f"Task via {input_data.subagent_type}: {input_data.prompt}"
+        if input_data.run_in_background:
+            label += " (background)"
+        return label
 
     async def call(
         self,
@@ -187,6 +376,123 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
     ) -> AsyncGenerator[ToolOutput, None]:
         clear_agent_cache()
         agents = load_agent_definitions()
+
+        if input_data.resume:
+            record = _get_agent_run(input_data.resume)
+            if not record:
+                raise ValueError(
+                    f"Agent id '{input_data.resume}' not found. "
+                    "Start a new agent to obtain a valid agent_id."
+                )
+
+            if record.task and not record.task.done():
+                if not input_data.wait:
+                    output = self._output_from_record(
+                        record,
+                        status_override="running",
+                        result_text_override="Agent is still running in the background.",
+                        is_background=True,
+                        is_resumed=True,
+                    )
+                    yield ToolResult(
+                        data=output, result_for_assistant=self.render_result_for_assistant(output)
+                    )
+                    return
+
+                yield ToolProgress(
+                    content=f"Waiting for subagent '{record.agent_type}' ({record.agent_id})"
+                )
+                try:
+                    await record.task
+                except asyncio.CancelledError:
+                    raise
+                except Exception as exc:
+                    record.status = "failed"
+                    record.error = str(exc)
+
+            if not input_data.prompt:
+                output = self._output_from_record(
+                    record,
+                    is_background=bool(record.task),
+                    is_resumed=True,
+                )
+                yield ToolResult(
+                    data=output, result_for_assistant=self.render_result_for_assistant(output)
+                )
+                return
+
+            record.history.append(create_user_message(input_data.prompt))
+            record.start_time = time.time()
+            record.duration_ms = 0.0
+            record.tool_use_count = 0
+            record.status = "running"
+            record.result_text = None
+            record.error = None
+            record.task = None
+
+            subagent_context = QueryContext(
+                tools=record.tools,
+                yolo_mode=context.yolo_mode,
+                verbose=context.verbose,
+                model=record.model_used or "main",
+                stop_hook="subagent",
+            )
+
+            yield ToolProgress(content=f"Resuming subagent '{record.agent_type}'")
+
+            # Get the Task tool's tool_use_id to set as parent_tool_use_id for subagent messages
+            parent_tool_use_id = context.message_id
+
+            assistant_messages: List[AssistantMessage] = []
+            tool_use_count = 0
+            async for message in query(
+                record.history,  # type: ignore[arg-type]
+                record.system_prompt,
+                {},
+                subagent_context,
+                context.permission_checker,
+            ):
+                msg_type = getattr(message, "type", "")
+                if msg_type == "progress":
+                    continue
+
+                # Track the message for internal state
+                tool_use_count, updates = self._track_subagent_message(
+                    message,
+                    record.history,
+                    assistant_messages,
+                    tool_use_count,
+                )
+                for update in updates:
+                    yield ToolProgress(content=update)
+
+                # CRITICAL: Also yield subagent messages to SDK for compatibility
+                if msg_type in ("assistant", "user"):
+                    # Set parent_tool_use_id to link subagent messages to the Task tool call
+                    message_with_parent = message.model_copy(update={"parent_tool_use_id": parent_tool_use_id})
+                    yield ToolProgress(content=message_with_parent, is_subagent_message=True)
+
+            duration_ms = (time.time() - record.start_time) * 1000
+            result_text = (
+                self._extract_text(assistant_messages[-1])
+                if assistant_messages
+                else "Agent returned no response."
+            )
+            record.duration_ms = duration_ms
+            record.tool_use_count = tool_use_count
+            record.result_text = result_text.strip()
+            record.status = "completed"
+
+            output = self._output_from_record(
+                record,
+                result_text_override=result_text.strip(),
+                is_resumed=True,
+            )
+            yield ToolResult(
+                data=output, result_for_assistant=self.render_result_for_assistant(output)
+            )
+            return
+
         target_agent = next(
             (
                 agent
@@ -217,83 +523,251 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
         ]
 
         agent_system_prompt = self._build_agent_prompt(target_agent, typed_agent_tools)
-        subagent_messages = [create_user_message(input_data.prompt)]
+        parent_history = (
+            self._coerce_parent_history(getattr(context, "conversation_messages", None))
+            if target_agent.fork_context
+            else []
+        )
+        subagent_messages = [
+            *parent_history,
+            create_user_message(input_data.prompt or ""),
+        ]
+
+        agent_id = _new_agent_id()
+        record = AgentRunRecord(
+            agent_id=agent_id,
+            agent_type=target_agent.agent_type,
+            tools=typed_agent_tools,
+            system_prompt=agent_system_prompt,
+            history=subagent_messages,
+            missing_tools=missing_tools,
+            model_used=target_agent.model or "main",
+            start_time=time.time(),
+            is_background=bool(input_data.run_in_background),
+        )
+        _register_agent_run(record)
 
         subagent_context = QueryContext(
             tools=typed_agent_tools,
             yolo_mode=context.yolo_mode,
             verbose=context.verbose,
-            model=target_agent.model or "task",
+            model=target_agent.model or "main",
+            stop_hook="subagent",
         )
 
-        start = time.time()
-        assistant_messages: List[AssistantMessage] = []
-        tool_use_count = 0
+        if input_data.run_in_background:
+            record.task = asyncio.create_task(
+                self._run_subagent_background(
+                    record,
+                    subagent_context,
+                    context.permission_checker,
+                )
+            )
+            output = self._output_from_record(
+                record,
+                status_override="running",
+                result_text_override="Agent started in the background.",
+                is_background=True,
+            )
+            yield ToolResult(
+                data=output, result_for_assistant=self.render_result_for_assistant(output)
+            )
+            return
 
         yield ToolProgress(content=f"Launching subagent '{target_agent.agent_type}'")
 
+        # Get the Task tool's tool_use_id to set as parent_tool_use_id for subagent messages
+        parent_tool_use_id = context.message_id
+
+        assistant_messages = []
+        tool_use_count = 0
         async for message in query(
-            subagent_messages,  # type: ignore[arg-type]
+            record.history,  # type: ignore[arg-type]
             agent_system_prompt,
             {},
             subagent_context,
             context.permission_checker,
         ):
-            if getattr(message, "type", "") == "assistant":
-                # Surface subagent tool requests as progress so the user sees activity.
-                msg_content = getattr(message, "message", None)
-                blocks = getattr(msg_content, "content", []) if msg_content else []
-                if isinstance(blocks, list):
-                    for block in blocks:
-                        block_type = getattr(block, "type", None) or (
-                            block.get("type") if isinstance(block, Dict) else None
-                        )
-                        if block_type == "tool_use":
-                            tool_name = getattr(block, "name", None) or (
-                                block.get("name") if isinstance(block, Dict) else "unknown tool"
-                            )
-                            block_input = (
-                                getattr(block, "input", None)
-                                if hasattr(block, "input")
-                                else (block.get("input") if isinstance(block, Dict) else None)
-                            )
-                            summary = self._summarize_tool_input(block_input)
-                            label = f"Subagent requesting {tool_name}"
-                            if summary:
-                                label += f" — {summary}"
-                            yield ToolProgress(content=label)
-                        if block_type == "text":
-                            text_val = getattr(block, "text", None) or (
-                                block.get("text") if isinstance(block, Dict) else ""
-                            )
-                            if text_val:
-                                snippet = str(text_val).strip()
-                                if snippet:
-                                    short = (
-                                        snippet if len(snippet) <= 200 else snippet[:197] + "..."
-                                    )
-                                    yield ToolProgress(content=f"Subagent: {short}")
-                assistant_messages.append(message)  # type: ignore[arg-type]
-                if isinstance(message, AssistantMessage):
-                    tool_use_count += self._count_tool_uses(message)
-
-        duration_ms = (time.time() - start) * 1000
+            msg_type = getattr(message, "type", "")
+            if msg_type == "progress":
+                continue
+
+            # Track the message for internal state
+            tool_use_count, updates = self._track_subagent_message(
+                message,
+                record.history,
+                assistant_messages,
+                tool_use_count,
+            )
+            for update in updates:
+                yield ToolProgress(content=update)
+
+            # CRITICAL: Also yield subagent messages to SDK for compatibility
+            # This allows SDK clients to see the full subagent conversation
+            if msg_type in ("assistant", "user"):
+                # Set parent_tool_use_id to link subagent messages to the Task tool call
+                # Use model_copy() to create a new message with the parent_tool_use_id set
+                message_with_parent = message.model_copy(update={"parent_tool_use_id": parent_tool_use_id})
+                yield ToolProgress(content=message_with_parent, is_subagent_message=True)
+
+        duration_ms = (time.time() - record.start_time) * 1000
         result_text = (
             self._extract_text(assistant_messages[-1])
             if assistant_messages
             else "Agent returned no response."
         )
 
-        output = TaskToolOutput(
-            agent_type=target_agent.agent_type,
-            result_text=result_text.strip(),
+        record.duration_ms = duration_ms
+        record.tool_use_count = tool_use_count
+        record.result_text = result_text.strip()
+        record.status = "completed"
+
+        output = self._output_from_record(record, result_text_override=result_text.strip())
+
+        yield ToolResult(data=output, result_for_assistant=self.render_result_for_assistant(output))
+
+    def _output_from_record(
+        self,
+        record: AgentRunRecord,
+        *,
+        status_override: Optional[str] = None,
+        result_text_override: Optional[str] = None,
+        is_background: bool = False,
+        is_resumed: bool = False,
+        error_override: Optional[str] = None,
+    ) -> TaskToolOutput:
+        status = status_override or record.status
+        duration_ms = (
+            record.duration_ms
+            if record.duration_ms
+            else max((time.time() - record.start_time) * 1000, 0.0)
+        )
+        result_text = (
+            result_text_override
+            or record.result_text
+            or ("Agent is still running." if status == "running" else "Agent returned no response.")
+        )
+        return TaskToolOutput(
+            agent_id=record.agent_id,
+            agent_type=record.agent_type,
+            result_text=result_text,
             duration_ms=duration_ms,
-            tool_use_count=tool_use_count,
-            missing_tools=missing_tools,
-            model_used=target_agent.model or "task",
+            tool_use_count=record.tool_use_count,
+            missing_tools=record.missing_tools,
+            model_used=record.model_used,
+            status=status,
+            is_background=is_background,
+            is_resumed=is_resumed,
+            error=error_override or record.error,
         )
 
-        yield ToolResult(data=output, result_for_assistant=self.render_result_for_assistant(output))
+    def _coerce_parent_history(self, messages: Optional[Sequence[object]]) -> List[MessageType]:
+        if not messages:
+            return []
+        history: List[MessageType] = []
+        for msg in messages:
+            msg_type = getattr(msg, "type", None)
+            if msg_type in ("user", "assistant"):
+                history.append(msg)  # type: ignore[arg-type]
+        return history
+
+    def _track_subagent_message(
+        self,
+        message: object,
+        history: List[MessageType],
+        assistant_messages: List[AssistantMessage],
+        tool_use_count: int,
+    ) -> tuple[int, List[str]]:
+        updates: List[str] = []
+        msg_type = getattr(message, "type", "")
+        if msg_type in ("assistant", "user"):
+            history.append(message)  # type: ignore[arg-type]
+
+        if msg_type == "assistant":
+            if isinstance(message, AssistantMessage):
+                tool_use_count += self._count_tool_uses(message)
+            updates = self._extract_progress_updates(message)
+            assistant_messages.append(message)  # type: ignore[arg-type]
+
+        return tool_use_count, updates
+
+    def _extract_progress_updates(self, message: object) -> List[str]:
+        msg_content = getattr(message, "message", None)
+        blocks = getattr(msg_content, "content", []) if msg_content else []
+        if not isinstance(blocks, list):
+            return []
+
+        updates: List[str] = []
+        for block in blocks:
+            block_type = getattr(block, "type", None) or (
+                block.get("type") if isinstance(block, Dict) else None
+            )
+            if block_type == "tool_use":
+                tool_name = getattr(block, "name", None) or (
+                    block.get("name") if isinstance(block, Dict) else "unknown tool"
+                )
+                block_input = (
+                    getattr(block, "input", None)
+                    if hasattr(block, "input")
+                    else (block.get("input") if isinstance(block, Dict) else None)
+                )
+                summary = self._summarize_tool_input(block_input)
+                label = f"Subagent requesting {tool_name}"
+                if summary:
+                    label += f" — {summary}"
+                updates.append(label)
+            if block_type == "text":
+                text_val = getattr(block, "text", None) or (
+                    block.get("text") if isinstance(block, Dict) else ""
+                )
+                if text_val:
+                    snippet = str(text_val).strip()
+                    if snippet:
+                        short = snippet if len(snippet) <= 200 else snippet[:197] + "..."
+                        updates.append(f"Subagent: {short}")
+        return updates
+
+    async def _run_subagent_background(
+        self,
+        record: AgentRunRecord,
+        subagent_context: QueryContext,
+        permission_checker: Any,
+    ) -> None:
+        assistant_messages: List[AssistantMessage] = []
+        tool_use_count = 0
+        try:
+            async for message in query(
+                record.history,  # type: ignore[arg-type]
+                record.system_prompt,
+                {},
+                subagent_context,
+                permission_checker,
+            ):
+                if getattr(message, "type", "") == "progress":
+                    continue
+                tool_use_count, _ = self._track_subagent_message(
+                    message,
+                    record.history,
+                    assistant_messages,
+                    tool_use_count,
+                )
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            record.status = "failed"
+            record.error = str(exc)
+        finally:
+            record.duration_ms = (time.time() - record.start_time) * 1000
+            record.tool_use_count = tool_use_count
+            if record.status != "failed":
+                result_text = (
+                    self._extract_text(assistant_messages[-1])
+                    if assistant_messages
+                    else "Agent returned no response."
+                )
+                record.result_text = result_text.strip()
+                record.status = "completed"
+            record.task = None
 
     def _build_agent_prompt(self, agent: AgentDefinition, tools: List[Tool[Any, Any]]) -> str:
         tool_names = ", ".join(tool.name for tool in tools if getattr(tool, "name", None))