klaude-code 1.2.14__py3-none-any.whl → 1.2.16__py3-none-any.whl

klaude_code/core/task.py

@@ -41,10 +41,8 @@ class MetadataAccumulator:
             if main.usage is None:
                 main.usage = model.Usage()
             acc_usage = main.usage
-            acc_usage.input_tokens += usage.input_tokens
-            acc_usage.cached_tokens += usage.cached_tokens
-            acc_usage.reasoning_tokens += usage.reasoning_tokens
-            acc_usage.output_tokens += usage.output_tokens
+
+            model.TaskMetadata.merge_usage(acc_usage, usage)
             acc_usage.currency = usage.currency
 
             if usage.context_size is not None:
@@ -67,13 +65,6 @@ class MetadataAccumulator:
                     self._throughput_weighted_sum += usage.throughput_tps * current_output
                     self._throughput_tracked_tokens += current_output
 
-            if usage.input_cost is not None:
-                acc_usage.input_cost = (acc_usage.input_cost or 0.0) + usage.input_cost
-            if usage.output_cost is not None:
-                acc_usage.output_cost = (acc_usage.output_cost or 0.0) + usage.output_cost
-            if usage.cache_read_cost is not None:
-                acc_usage.cache_read_cost = (acc_usage.cache_read_cost or 0.0) + usage.cache_read_cost
-
         if turn_metadata.provider is not None:
             main.provider = turn_metadata.provider
         if turn_metadata.model_name:
@@ -225,7 +216,7 @@ class TaskExecutor:
                 yield events.ErrorEvent(error_message=final_error, can_retry=False)
                 return
 
-            if turn is None or not turn.has_tool_call:
+            if turn is None or turn.task_finished:
                 break
 
         # Finalize metadata
@@ -234,21 +225,18 @@ class TaskExecutor:
 
         yield events.TaskMetadataEvent(metadata=accumulated, session_id=session_ctx.session_id)
         session_ctx.append_history([accumulated])
+
+        # Get task result from turn
+        task_result = turn.task_result if turn is not None else ""
+        has_structured_output = turn.has_structured_output if turn is not None else False
+
         yield events.TaskFinishEvent(
             session_id=session_ctx.session_id,
-            task_result=_get_last_assistant_message(session_ctx.get_conversation_history()) or "",
+            task_result=task_result,
+            has_structured_output=has_structured_output,
         )
 
 
-def _get_last_assistant_message(history: list[model.ConversationItem]) -> str | None:
-    """Return the content of the most recent assistant message in history."""
-
-    for item in reversed(history):
-        if isinstance(item, model.AssistantMessageItem):
-            return item.content or ""
-    return None
-
-
 def _retry_delay_seconds(attempt: int) -> float:
     """Compute exponential backoff delay for the given attempt count."""
     capped_attempt = max(1, attempt)

klaude_code/core/tool/__init__.py

@@ -7,6 +7,7 @@ from .file.write_tool import WriteTool
 from .memory.memory_tool import MEMORY_DIR_NAME, MemoryTool
 from .memory.skill_loader import Skill, SkillLoader
 from .memory.skill_tool import SkillTool
+from .report_back_tool import ReportBackTool
 from .shell.bash_tool import BashTool
 from .shell.command_safety import SafetyCheckResult, is_safe_command
 from .sub_agent_tool import SubAgentTool
@@ -38,6 +39,7 @@ __all__ = [
     "MermaidTool",
     "MultiEditTool",
     "ReadTool",
+    "ReportBackTool",
     "SafetyCheckResult",
     "SimpleTruncationStrategy",
     "Skill",

klaude_code/core/tool/report_back_tool.py

@@ -0,0 +1,58 @@
+"""ReportBackTool for sub-agents to return structured output."""
+
+from typing import Any, ClassVar
+
+from klaude_code.protocol import llm_param, model, tools
+
+
+class ReportBackTool:
+    """Special tool for sub-agents to return structured output and end the task.
+
+    This tool is dynamically injected when a parent agent calls a sub-agent with
+    an output_schema. The schema for this tool's parameters is defined by the
+    parent agent, allowing structured data to be returned.
+
+    Note: This class does not inherit from ToolABC because it's not registered
+    in the global tool registry. Instead, it's handled specially by the
+    TurnExecutor and SubAgentManager.
+    """
+
+    _schema: ClassVar[dict[str, Any]] = {}
+
+    @classmethod
+    def for_schema(cls, schema: dict[str, Any]) -> type["ReportBackTool"]:
+        """Create a tool class with the specified output schema.
+
+        Args:
+            schema: JSON Schema defining the expected structure of the report_back arguments.
+
+        Returns:
+            A new class with the schema set as a class variable.
+        """
+        return type("ReportBackTool", (ReportBackTool,), {"_schema": schema})
+
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        """Generate the tool schema for this report_back tool."""
+        return llm_param.ToolSchema(
+            name=tools.REPORT_BACK,
+            type="function",
+            description=(
+                "Report the final structured result back to the parent agent. "
+                "Call this when you have completed the task and want to return structured data. "
+                "The task will end after this tool is called."
+            ),
+            parameters=cls._schema,
+        )
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        """Execute the report_back tool.
+
+        The actual handling of report_back results is done by TurnExecutor.
+        This method just returns a success status to maintain the tool call flow.
+        """
+        return model.ToolResultItem(
+            status="success",
+            output="Result reported successfully. Task will end.",
+        )

klaude_code/core/tool/sub_agent_tool.py

@@ -63,12 +63,18 @@ class SubAgentTool(ToolABC):
         prompt = profile.prompt_builder(args)
         description = args.get("description", "")
 
+        # Extract output_schema if configured
+        output_schema = None
+        if profile.output_schema_arg:
+            output_schema = args.get(profile.output_schema_arg)
+
         try:
             result = await runner(
                 model.SubAgentState(
                     sub_agent_type=profile.name,
                     sub_agent_desc=description,
                     sub_agent_prompt=prompt,
+                    output_schema=output_schema,
                 )
             )
         except asyncio.CancelledError:

klaude_code/core/tool/tool_runner.py

@@ -3,9 +3,10 @@ from collections.abc import AsyncGenerator, Callable, Iterable, Sequence
 from dataclasses import dataclass
 
 from klaude_code import const
+from klaude_code.core.tool.report_back_tool import ReportBackTool
 from klaude_code.core.tool.tool_abc import ToolABC
 from klaude_code.core.tool.truncation import truncate_tool_output
-from klaude_code.protocol import model
+from klaude_code.protocol import model, tools
 from klaude_code.protocol.sub_agent import is_sub_agent_tool
 
 
@@ -19,6 +20,13 @@ async def run_tool(tool_call: model.ToolCallItem, registry: dict[str, type[ToolA
     Returns:
         The result of the tool execution.
     """
+    # Special handling for report_back tool (not registered in global registry)
+    if tool_call.name == tools.REPORT_BACK:
+        tool_result = await ReportBackTool.call(tool_call.arguments)
+        tool_result.call_id = tool_call.call_id
+        tool_result.tool_name = tool_call.name
+        return tool_result
+
     if tool_call.name not in registry:
         return model.ToolResultItem(
             call_id=tool_call.call_id,

klaude_code/core/turn.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import AsyncGenerator
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
 from klaude_code.core.tool import ToolABC, tool_context
@@ -17,7 +17,7 @@ from klaude_code.core.tool.tool_runner import (
     ToolExecutorEvent,
 )
 from klaude_code.llm import LLMClientABC
-from klaude_code.protocol import events, llm_param, model
+from klaude_code.protocol import events, llm_param, model, tools
 from klaude_code.trace import DebugType, log_debug
 
 
@@ -46,6 +46,7 @@ class TurnResult:
     assistant_message: model.AssistantMessageItem | None
     tool_calls: list[model.ToolCallItem]
     stream_error: model.StreamErrorItem | None
+    report_back_result: str | None = field(default=None)
 
 
 def build_events_from_tool_executor_event(session_id: str, event: ToolExecutorEvent) -> list[events.Event]:
@@ -101,8 +102,38 @@ class TurnExecutor:
         self._turn_result: TurnResult | None = None
 
     @property
-    def has_tool_call(self) -> bool:
-        return bool(self._turn_result and self._turn_result.tool_calls)
+    def report_back_result(self) -> str | None:
+        return self._turn_result.report_back_result if self._turn_result else None
+
+    @property
+    def task_finished(self) -> bool:
+        """Check if this turn indicates the task should end.
+
+        Task ends when there are no tool calls or report_back was called.
+        """
+        if self._turn_result is None:
+            return True
+        if not self._turn_result.tool_calls:
+            return True
+        return self._turn_result.report_back_result is not None
+
+    @property
+    def task_result(self) -> str:
+        """Get the task result from this turn.
+
+        Returns report_back result if available, otherwise returns
+        the assistant message content.
+        """
+        if self._turn_result is not None and self._turn_result.report_back_result is not None:
+            return self._turn_result.report_back_result
+        if self._turn_result is not None and self._turn_result.assistant_message is not None:
+            return self._turn_result.assistant_message.content or ""
+        return ""
+
+    @property
+    def has_structured_output(self) -> bool:
+        """Check if the task result is structured output from report_back."""
+        return bool(self._turn_result and self._turn_result.report_back_result)
 
     def cancel(self) -> list[events.Event]:
         """Cancel running tools and return any resulting events."""
@@ -143,11 +174,21 @@ class TurnExecutor:
         self._append_success_history(self._turn_result)
 
         if self._turn_result.tool_calls:
+            # Check for report_back before running tools
+            self._detect_report_back(self._turn_result)
+
             async for ui_event in self._run_tool_executor(self._turn_result.tool_calls):
                 yield ui_event
 
         yield events.TurnEndEvent(session_id=session_ctx.session_id)
 
+    def _detect_report_back(self, turn_result: TurnResult) -> None:
+        """Detect report_back tool call and store its arguments as JSON string."""
+        for tool_call in turn_result.tool_calls:
+            if tool_call.name == tools.REPORT_BACK:
+                turn_result.report_back_result = tool_call.arguments
+                break
+
     async def _consume_llm_stream(self, turn_result: TurnResult) -> AsyncGenerator[events.Event]:
         """Stream events from LLM and update turn_result in place."""
 

klaude_code/llm/anthropic/input.py

@@ -104,18 +104,22 @@ def _tool_groups_to_message(groups: list[ToolGroup]) -> BetaMessageParam:
 def _assistant_group_to_message(group: AssistantGroup, model_name: str | None) -> BetaMessageParam:
     content: list[dict[str, object]] = []
     current_reasoning_content: str | None = None
+    degraded_thinking_texts: list[str] = []
 
     # Process reasoning items in original order so that text and
     # encrypted parts are paired correctly for the given model.
+    # For cross-model scenarios, degrade thinking to plain text.
     for item in group.reasoning_items:
         if isinstance(item, model.ReasoningTextItem):
             if model_name != item.model:
-                continue
-            current_reasoning_content = item.content
+                # Cross-model: collect thinking text for degradation
+                if item.content:
+                    degraded_thinking_texts.append(item.content)
+            else:
+                current_reasoning_content = item.content
         else:
-            if model_name != item.model:
-                continue
-            if item.encrypted_content and len(item.encrypted_content) > 0:
+            # Same model: preserve signature
+            if model_name == item.model and item.encrypted_content and len(item.encrypted_content) > 0:
                 content.append(
                     {
                         "type": "thinking",
@@ -131,6 +135,11 @@ def _assistant_group_to_message(group: AssistantGroup, model_name: str | None) -
     if len(current_reasoning_content or "") > 0:
         content.insert(0, {"type": "thinking", "thinking": current_reasoning_content})
 
+    # Cross-model: degrade thinking to plain text with <thinking> tags
+    if degraded_thinking_texts:
+        degraded_text = "<thinking>\n" + "\n".join(degraded_thinking_texts) + "\n</thinking>"
+        content.insert(0, {"type": "text", "text": degraded_text})
+
     if group.text_content:
         content.append({"type": "text", "text": group.text_content})
 

klaude_code/llm/input_common.py

@@ -149,7 +149,7 @@ def parse_message_groups(history: list[model.ConversationItem]) -> list[MessageG
                 for item in items:
                     if isinstance(item, (model.UserMessageItem, model.DeveloperMessageItem)):
                         if item.content:
-                            group.text_parts.append(item.content)
+                            group.text_parts.append(item.content + "\n")
                         if item.images:
                             group.images.extend(item.images)
                 groups.append(group)

klaude_code/llm/openrouter/input.py

@@ -28,9 +28,6 @@ def is_gemini_model(model_name: str | None) -> bool:
 def _assistant_group_to_message(group: AssistantGroup, model_name: str | None) -> chat.ChatCompletionMessageParam:
     assistant_message: dict[str, object] = {"role": "assistant"}
 
-    if group.text_content:
-        assistant_message["content"] = group.text_content
-
     if group.tool_calls:
         assistant_message["tool_calls"] = [
             {
@@ -48,9 +45,14 @@ def _assistant_group_to_message(group: AssistantGroup, model_name: str | None) -
     # The order of items in reasoning_details must match the original
     # stream order from the provider, so we iterate reasoning_items
     # instead of the separated reasoning_text / reasoning_encrypted lists.
+    # For cross-model scenarios, degrade thinking to plain text.
     reasoning_details: list[dict[str, object]] = []
+    degraded_thinking_texts: list[str] = []
     for item in group.reasoning_items:
         if model_name != item.model:
+            # Cross-model: collect thinking text for degradation
+            if isinstance(item, model.ReasoningTextItem) and item.content:
+                degraded_thinking_texts.append(item.content)
             continue
         if isinstance(item, model.ReasoningEncryptedItem):
             if item.encrypted_content and len(item.encrypted_content) > 0:
@@ -75,6 +77,15 @@ def _assistant_group_to_message(group: AssistantGroup, model_name: str | None) -
     if reasoning_details:
         assistant_message["reasoning_details"] = reasoning_details
 
+    # Build content with optional degraded thinking prefix
+    content_parts: list[str] = []
+    if degraded_thinking_texts:
+        content_parts.append("<thinking>\n" + "\n".join(degraded_thinking_texts) + "\n</thinking>")
+    if group.text_content:
+        content_parts.append(group.text_content)
+    if content_parts:
+        assistant_message["content"] = "\n".join(content_parts)
+
     return assistant_message
 
 

klaude_code/llm/responses/input.py

@@ -1,5 +1,6 @@
 # pyright: reportReturnType=false
 # pyright: reportArgumentType=false
+# pyright: reportAssignmentType=false
 
 from typing import Any
 
@@ -51,6 +52,7 @@ def convert_history_to_input(
     items: list[responses.ResponseInputItemParam] = []
 
     pending_reasoning_text: str | None = None
+    degraded_thinking_texts: list[str] = []
 
     for item in history:
         match item:
@@ -60,6 +62,9 @@ def convert_history_to_input(
                 # or we can choose to output it if the next item is NOT reasoning?
                 # For now, based on instructions, we pair them.
                 if model_name != item.model:
+                    # Cross-model: collect thinking text for degradation
+                    if item.content:
+                        degraded_thinking_texts.append(item.content)
                     continue
                 pending_reasoning_text = item.content
 
@@ -130,6 +135,20 @@ def convert_history_to_input(
                 # Other items may be Metadata
                 continue
 
+    # Cross-model: degrade thinking to plain text with <thinking> tags
+    if degraded_thinking_texts:
+        degraded_item: responses.ResponseInputItemParam = {
+            "type": "message",
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "output_text",
+                    "text": "<thinking>\n" + "\n".join(degraded_thinking_texts) + "\n</thinking>",
+                }
+            ],
+        }
+        items.insert(0, degraded_item)
+
     return items
 
 

klaude_code/protocol/events.py

@@ -26,6 +26,7 @@ class TaskStartEvent(BaseModel):
 class TaskFinishEvent(BaseModel):
     session_id: str
     task_result: str
+    has_structured_output: bool = False
 
 
 class TurnStartEvent(BaseModel):

klaude_code/protocol/model.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 from enum import Enum
-from typing import Annotated, Literal
+from typing import Annotated, Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, computed_field
 
@@ -132,6 +132,7 @@ class AtPatternParseResult(BaseModel):
     tool_args: str
     operation: Literal["Read", "List"]
     images: list["ImageURLPart"] | None = None
+    mentioned_in: str | None = None  # Parent file that referenced this file
 
 
 class CommandOutput(BaseModel):
@@ -144,6 +145,7 @@ class SubAgentState(BaseModel):
     sub_agent_type: SubAgentType
     sub_agent_desc: str
     sub_agent_prompt: str
+    output_schema: dict[str, Any] | None = None
 
 
 """
@@ -327,6 +329,26 @@ class TaskMetadata(BaseModel):
     task_duration_s: float | None = None
     turn_count: int = 0
 
+    @staticmethod
+    def merge_usage(dst: Usage, src: Usage) -> None:
+        """Merge src usage into dst usage (in-place).
+
+        Accumulates token counts and cost components. Does not handle
+        special fields like throughput_tps, first_token_latency_ms,
+        context_size, or context_limit - those require custom logic.
+        """
+        dst.input_tokens += src.input_tokens
+        dst.cached_tokens += src.cached_tokens
+        dst.reasoning_tokens += src.reasoning_tokens
+        dst.output_tokens += src.output_tokens
+
+        if src.input_cost is not None:
+            dst.input_cost = (dst.input_cost or 0.0) + src.input_cost
+        if src.output_cost is not None:
+            dst.output_cost = (dst.output_cost or 0.0) + src.output_cost
+        if src.cache_read_cost is not None:
+            dst.cache_read_cost = (dst.cache_read_cost or 0.0) + src.cache_read_cost
+
     @staticmethod
     def aggregate_by_model(metadata_list: list["TaskMetadata"]) -> list["TaskMetadata"]:
         """Aggregate multiple TaskMetadata by (model_name, provider).
@@ -356,19 +378,7 @@ class TaskMetadata(BaseModel):
             if agg.usage is None:
                 continue
 
-            # Accumulate primary token fields (total_tokens is computed)
-            agg.usage.input_tokens += usage.input_tokens
-            agg.usage.cached_tokens += usage.cached_tokens
-            agg.usage.reasoning_tokens += usage.reasoning_tokens
-            agg.usage.output_tokens += usage.output_tokens
-
-            # Accumulate cost components (total_cost is computed)
-            if usage.input_cost is not None:
-                agg.usage.input_cost = (agg.usage.input_cost or 0.0) + usage.input_cost
-            if usage.output_cost is not None:
-                agg.usage.output_cost = (agg.usage.output_cost or 0.0) + usage.output_cost
-            if usage.cache_read_cost is not None:
-                agg.usage.cache_read_cost = (agg.usage.cache_read_cost or 0.0) + usage.cache_read_cost
+            TaskMetadata.merge_usage(agg.usage, usage)
 
         # Sort by total_cost descending
         return sorted(

klaude_code/protocol/sub_agent/__init__.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from klaude_code.protocol import tools
+
+if TYPE_CHECKING:
+    from klaude_code.protocol import model
+
+AvailabilityPredicate = Callable[[str], bool]
+PromptBuilder = Callable[[dict[str, Any]], str]
+
+
+@dataclass
+class SubAgentResult:
+    task_result: str
+    session_id: str
+    error: bool = False
+    task_metadata: model.TaskMetadata | None = None
+
+
+def _default_prompt_builder(args: dict[str, Any]) -> str:
+    """Default prompt builder that just returns the 'prompt' field."""
+    return args.get("prompt", "")
+
+
+@dataclass(frozen=True)
+class SubAgentProfile:
+    """Metadata describing a sub agent and how it integrates with the system.
+
+    This dataclass contains all the information needed to:
+    1. Register the sub agent with the system
+    2. Generate the tool schema for the main agent
+    3. Build the prompt for the sub agent
+    """
+
+    # Identity - single name used for type, tool_name, config_key, and prompt_key
+    name: str  # e.g., "Task", "Oracle", "Explore"
+
+    # Tool schema
+    description: str  # Tool description shown to the main agent
+    parameters: dict[str, Any] = field(
+        default_factory=lambda: dict[str, Any](), hash=False
+    )  # JSON Schema for tool parameters
+
+    # System prompt
+    prompt_file: str = ""  # Resource file path relative to core package (e.g., "prompts/prompt-sub-agent.md")
+
+    # Sub agent configuration
+    tool_set: tuple[str, ...] = ()  # Tools available to this sub agent
+    prompt_builder: PromptBuilder = _default_prompt_builder  # Builds the sub agent prompt from tool arguments
+
+    # UI display
+    active_form: str = ""  # Active form for spinner status (e.g., "Tasking", "Exploring")
+
+    # Availability
+    enabled_by_default: bool = True
+    show_in_main_agent: bool = True
+    target_model_filter: AvailabilityPredicate | None = None
+
+    # Structured output support: specifies which parameter in the tool schema contains the output schema
+    output_schema_arg: str | None = None
+
+    def enabled_for_model(self, model_name: str | None) -> bool:
+        if not self.enabled_by_default:
+            return False
+        if model_name is None or self.target_model_filter is None:
+            return True
+        return self.target_model_filter(model_name)
+
+
+_PROFILES: dict[str, SubAgentProfile] = {}
+
+
+def register_sub_agent(profile: SubAgentProfile) -> None:
+    if profile.name in _PROFILES:
+        raise ValueError(f"Duplicate sub agent profile: {profile.name}")
+    _PROFILES[profile.name] = profile
+
+
+def get_sub_agent_profile(sub_agent_type: tools.SubAgentType) -> SubAgentProfile:
+    try:
+        return _PROFILES[sub_agent_type]
+    except KeyError as exc:
+        raise KeyError(f"Unknown sub agent type: {sub_agent_type}") from exc
+
+
+def iter_sub_agent_profiles(enabled_only: bool = False, model_name: str | None = None) -> list[SubAgentProfile]:
+    profiles = list(_PROFILES.values())
+    if not enabled_only:
+        return profiles
+    return [p for p in profiles if p.enabled_for_model(model_name)]
+
+
+def get_sub_agent_profile_by_tool(tool_name: str) -> SubAgentProfile | None:
+    return _PROFILES.get(tool_name)
+
+
+def is_sub_agent_tool(tool_name: str) -> bool:
+    return tool_name in _PROFILES
+
+
+def sub_agent_tool_names(enabled_only: bool = False, model_name: str | None = None) -> list[str]:
+    return [
+        profile.name
+        for profile in iter_sub_agent_profiles(enabled_only=enabled_only, model_name=model_name)
+        if profile.show_in_main_agent
+    ]
+
+
+# Import sub-agent modules to trigger registration
+from klaude_code.protocol.sub_agent import explore as explore  # noqa: E402
+from klaude_code.protocol.sub_agent import oracle as oracle  # noqa: E402
+from klaude_code.protocol.sub_agent import task as task  # noqa: E402
+from klaude_code.protocol.sub_agent import web_fetch as web_fetch  # noqa: E402

klaude_code/protocol/sub_agent/explore.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any
+
+from klaude_code.protocol import tools
+from klaude_code.protocol.sub_agent import SubAgentProfile, register_sub_agent
+
+EXPLORE_DESCRIPTION = """\
+Spin up a fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), \
+search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?")\
+When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.
+Always spawn multiple search agents in parallel to maximise speed.
+
+Structured output:
+- Provide an `output_format` (JSON Schema) parameter for structured data back from the sub-agent
+- Example: `output_format={"type": "object", "properties": {"files": {"type": "array", "items": {"type": "string"}, "description": "List of file paths that match the search criteria, e.g. ['src/main.py', 'src/utils/helper.py']"}}, "required": ["files"]}`\
+"""
+
+EXPLORE_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "description": {
+            "type": "string",
+            "description": "Short (3-5 words) label for the exploration goal",
+        },
+        "prompt": {
+            "type": "string",
+            "description": "The task for the agent to perform",
+        },
+        "thoroughness": {
+            "type": "string",
+            "enum": ["quick", "medium", "very thorough"],
+            "description": "Controls how deep the sub-agent should search the repo",
+        },
+        "output_format": {
+            "type": "object",
+            "description": "Optional JSON Schema for sub-agent structured output",
+        },
+    },
+    "required": ["description", "prompt", "output_format"],
+    "additionalProperties": False,
+}
+
+
+def _explore_prompt_builder(args: dict[str, Any]) -> str:
+    """Build the Explore prompt from tool arguments."""
+    prompt = args.get("prompt", "").strip()
+    thoroughness = args.get("thoroughness", "medium")
+    return f"{prompt}\nthoroughness: {thoroughness}"
+
+
+register_sub_agent(
+    SubAgentProfile(
+        name="Explore",
+        description=EXPLORE_DESCRIPTION,
+        parameters=EXPLORE_PARAMETERS,
+        prompt_file="prompts/prompt-sub-agent-explore.md",
+        tool_set=(tools.BASH, tools.READ),
+        prompt_builder=_explore_prompt_builder,
+        active_form="Exploring",
+        output_schema_arg="output_format",
+    )
+)