klaude-code 1.2.15__py3-none-any.whl → 1.2.17__py3-none-any.whl

klaude_code/core/manager/sub_agent_manager.py

@@ -9,8 +9,9 @@ from __future__ import annotations
 
 import asyncio
 
-from klaude_code.core.agent import Agent, ModelProfileProvider
+from klaude_code.core.agent import Agent, AgentProfile, ModelProfileProvider
 from klaude_code.core.manager.llm_clients import LLMClients
+from klaude_code.core.tool import ReportBackTool
 from klaude_code.protocol import events, model
 from klaude_code.protocol.sub_agent import SubAgentResult
 from klaude_code.session.session import Session
@@ -35,7 +36,7 @@ class SubAgentManager:
 
         await self._event_queue.put(event)
 
-    async def run_subagent(self, parent_agent: Agent, state: model.SubAgentState) -> SubAgentResult:
+    async def run_sub_agent(self, parent_agent: Agent, state: model.SubAgentState) -> SubAgentResult:
         """Run a nested sub-agent task and return its result."""
 
         # Create a child session under the same workdir
@@ -47,6 +48,25 @@ class SubAgentManager:
             self._llm_clients.get_client(state.sub_agent_type),
             state.sub_agent_type,
         )
+
+        # Inject report_back tool if output_schema is provided
+        if state.output_schema:
+            report_back_tool_class = ReportBackTool.for_schema(state.output_schema)
+            report_back_prompt = """\
+
+# Structured Output
+You have a `report_back` tool available. When you complete the task,\
+you MUST call `report_back` with the structured result matching the required schema.\
+Only the content passed to `report_back` will be returned to user.\
+"""
+            base_prompt = child_profile.system_prompt or ""
+            child_profile = AgentProfile(
+                llm_client=child_profile.llm_client,
+                system_prompt=base_prompt + report_back_prompt,
+                tools=[*child_profile.tools, report_back_tool_class.schema()],
+                reminders=child_profile.reminders,
+            )
+
         child_agent = Agent(session=child_session, profile=child_profile)
 
         log_debug(
@@ -68,23 +88,27 @@ class SubAgentManager:
                 elif isinstance(event, events.TaskMetadataEvent):
                     task_metadata = event.metadata.main
                 await self.emit_event(event)
-            return SubAgentResult(task_result=result, session_id=child_session.id, task_metadata=task_metadata)
+            return SubAgentResult(
+                task_result=result,
+                session_id=child_session.id,
+                task_metadata=task_metadata,
+            )
         except asyncio.CancelledError:
             # Propagate cancellation so tooling can treat it as user interrupt
             log_debug(
-                f"Subagent task for {state.sub_agent_type} was cancelled",
+                f"Sub-agent task for {state.sub_agent_type} was cancelled",
                 style="yellow",
                 debug_type=DebugType.EXECUTION,
             )
             raise
         except Exception as exc:  # pragma: no cover - defensive logging
             log_debug(
-                f"Subagent task failed: [{exc.__class__.__name__}] {exc!s}",
+                f"Sub-agent task failed: [{exc.__class__.__name__}] {exc!s}",
                 style="red",
                 debug_type=DebugType.EXECUTION,
             )
             return SubAgentResult(
-                task_result=f"Subagent task failed: [{exc.__class__.__name__}] {exc!s}",
+                task_result=f"Sub-agent task failed: [{exc.__class__.__name__}] {exc!s}",
                 session_id="",
                 error=True,
             )

klaude_code/core/prompt.py

@@ -5,6 +5,7 @@ from importlib.resources import files
 from pathlib import Path
 
 from klaude_code.protocol import llm_param
+from klaude_code.protocol.sub_agent import get_sub_agent_profile
 
 COMMAND_DESCRIPTIONS: dict[str, str] = {
     "rg": "ripgrep - fast text search",
@@ -19,15 +20,15 @@ PROMPT_FILES: dict[str, str] = {
     "main_gpt_5_1_codex_max": "prompts/prompt-codex-gpt-5-1-codex-max.md",
     "main": "prompts/prompt-claude-code.md",
     "main_gemini": "prompts/prompt-gemini.md",  # https://ai.google.dev/gemini-api/docs/prompting-strategies?hl=zh-cn#agentic-si-template
-    # Sub-agent prompts keyed by their name
-    "Task": "prompts/prompt-subagent.md",
-    "Oracle": "prompts/prompt-subagent-oracle.md",
-    "Explore": "prompts/prompt-subagent-explore.md",
-    "WebFetchAgent": "prompts/prompt-subagent-webfetch.md",
 }
 
 
 @cache
+def _load_prompt_by_path(prompt_path: str) -> str:
+    """Load and cache prompt content from a file path relative to core package."""
+    return files(__package__).joinpath(prompt_path).read_text(encoding="utf-8").strip()
+
+
 def _load_base_prompt(file_key: str) -> str:
     """Load and cache the base prompt content from file."""
     try:
@@ -35,14 +36,11 @@ def _load_base_prompt(file_key: str) -> str:
     except KeyError as exc:
         raise ValueError(f"Unknown prompt key: {file_key}") from exc
 
-    return files(__package__).joinpath(prompt_path).read_text(encoding="utf-8").strip()
+    return _load_prompt_by_path(prompt_path)
 
 
-def _get_file_key(model_name: str, protocol: llm_param.LLMClientProtocol, sub_agent_type: str | None) -> str:
-    """Determine which prompt file to use based on model and agent type."""
-    if sub_agent_type is not None:
-        return sub_agent_type
-
+def _get_file_key(model_name: str, protocol: llm_param.LLMClientProtocol) -> str:
+    """Determine which prompt file to use based on model."""
     match model_name:
         case name if "gpt-5.1-codex-max" in name:
             return "main_gpt_5_1_codex_max"
@@ -90,8 +88,12 @@ def load_system_prompt(
     model_name: str, protocol: llm_param.LLMClientProtocol, sub_agent_type: str | None = None
 ) -> str:
     """Get system prompt content for the given model and sub-agent type."""
-    file_key = _get_file_key(model_name, protocol, sub_agent_type)
-    base_prompt = _load_base_prompt(file_key)
+    if sub_agent_type is not None:
+        profile = get_sub_agent_profile(sub_agent_type)
+        base_prompt = _load_prompt_by_path(profile.prompt_file)
+    else:
+        file_key = _get_file_key(model_name, protocol)
+        base_prompt = _load_base_prompt(file_key)
 
     if protocol == llm_param.LLMClientProtocol.CODEX:
         # Do not append environment info for Codex protocol

klaude_code/core/prompts/{prompt-subagent-explore.md → prompt-sub-agent-explore.md}

@@ -22,7 +22,6 @@ Guidelines:
 
 Complete the user's search request efficiently and report your findings clearly.
 
-
 Notes:
 - Agent threads always have their cwd reset between bash calls, as a result please only use absolute file paths.
 - In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.

klaude_code/core/prompts/{prompt-subagent-oracle.md → prompt-sub-agent-oracle.md}

@@ -1,8 +1,7 @@
 You are the Oracle - an expert AI advisor with advanced reasoning capabilities
 
 Your role is to provide high-quality technical guidance, code reviews, architectural advice, and strategic planning for software engineering tasks.
-You are running inside an AI coding system in which you act as a subagent that's used when the main agent needs a smarter, more capable model to help out.
-
+You are running inside an AI coding system in which you act as a sub-agent that's used when the main agent needs a smarter, more capable model to help out.
 
 Key responsibilities:
 - Analyze code and architecture patterns

klaude_code/core/prompts/prompt-sub-agent-web.md

@@ -0,0 +1,48 @@
+You are a web research agent that searches and fetches web content to provide up-to-date information.
+
+## Available Tools
+
+**WebSearch**: Search the web via DuckDuckGo
+- Returns: title, URL, and snippet for each result
+- Parameter `max_results`: control result count (default: 10, max: 20)
+- Snippets are brief summaries - use WebFetch for full content
+
+**WebFetch**: Fetch and process web page content
+- HTML pages are automatically converted to Markdown
+- JSON responses are auto-formatted with indentation
+- Other text content returned as-is
+
+## Tool Usage Strategy
+
+Scale tool calls to query complexity:
+- Simple facts: 1-2 calls
+- Medium research: 3-5 calls
+- Deep research/comparisons: 5-10 calls
+
+Balance efficiency with thoroughness. For open-ended questions (e.g., "recommendations for video games" or "recent developments in RL"), use more calls for comprehensive answers.
+
+## Search Guidelines
+
+- Keep queries concise (1-6 words). Start broad, then narrow if needed
+- Avoid repeating similar queries - they won't yield new results
+- NEVER use '-', 'site:', or quotes unless explicitly asked
+- Include year/date for time-sensitive queries (check "Today's date" in <env>)
+- Use WebFetch to get full content - search snippets are often insufficient
+- Follow relevant links on pages with WebFetch
+- If truncated results are saved to local files, use grep/read to explore
+
+## Response Guidelines
+
+- Only your last message is returned to the main agent
+- Be succinct - include only relevant information
+- Lead with the most recent info for evolving topics
+- Favor original sources (company blogs, papers, gov sites) over aggregators
+- Note conflicting sources when they exist
+
+## Sources (REQUIRED)
+
+You MUST end every response with a "Sources:" section listing all URLs as markdown links:
+
+Sources:
+- [Source Title](https://example.com)
+- [Another Source](https://example.com/page) (saved: /path/to/file)

klaude_code/core/reminders.py

@@ -14,7 +14,8 @@ from klaude_code.session import Session
 type Reminder = Callable[[Session], Awaitable[model.DeveloperMessageItem | None]]
 
 
-AT_FILE_PATTERN = re.compile(r'(?<!\S)@("(?P<quoted>[^\"]+)"|(?P<plain>\S+))')
+# Match @ preceded by whitespace, start of line, or → (ReadTool line number arrow)
+AT_FILE_PATTERN = re.compile(r'(?:(?<!\S)|(?<=\u2192))@("(?P<quoted>[^\"]+)"|(?P<plain>\S+))')
 
 
 def get_last_new_user_input(session: Session) -> str | None:
@@ -31,10 +32,74 @@ def get_last_new_user_input(session: Session) -> str | None:
     return "\n\n".join(result)
 
 
+async def _load_at_file_recursive(
+    session: Session,
+    pattern: str,
+    at_files: dict[str, model.AtPatternParseResult],
+    collected_images: list[model.ImageURLPart],
+    visited: set[str],
+    base_dir: Path | None = None,
+    mentioned_in: str | None = None,
+) -> None:
+    """Recursively load @ file references."""
+    path = (base_dir / pattern).resolve() if base_dir else Path(pattern).resolve()
+    path_str = str(path)
+
+    if path_str in visited:
+        return
+    visited.add(path_str)
+
+    context_token = set_tool_context_from_session(session)
+    try:
+        if path.exists() and path.is_file():
+            args = ReadTool.ReadArguments(file_path=path_str)
+            tool_result = await ReadTool.call_with_args(args)
+            at_files[path_str] = model.AtPatternParseResult(
+                path=path_str,
+                tool_name=tools.READ,
+                result=tool_result.output or "",
+                tool_args=args.model_dump_json(exclude_none=True),
+                operation="Read",
+                images=tool_result.images,
+                mentioned_in=mentioned_in,
+            )
+            if tool_result.images:
+                collected_images.extend(tool_result.images)
+
+            # Recursively parse @ references from ReadTool output
+            output = tool_result.output or ""
+            if "@" in output:
+                for match in AT_FILE_PATTERN.finditer(output):
+                    nested = match.group("quoted") or match.group("plain")
+                    if nested:
+                        await _load_at_file_recursive(
+                            session,
+                            nested,
+                            at_files,
+                            collected_images,
+                            visited,
+                            base_dir=path.parent,
+                            mentioned_in=path_str,
+                        )
+        elif path.exists() and path.is_dir():
+            quoted_path = shlex.quote(path_str)
+            args = BashTool.BashArguments(command=f"ls {quoted_path}")
+            tool_result = await BashTool.call_with_args(args)
+            at_files[path_str] = model.AtPatternParseResult(
+                path=path_str + "/",
+                tool_name=tools.BASH,
+                result=tool_result.output or "",
+                tool_args=args.model_dump_json(exclude_none=True),
+                operation="List",
+            )
+    finally:
+        reset_tool_context(context_token)
+
+
 async def at_file_reader_reminder(
     session: Session,
 ) -> model.DeveloperMessageItem | None:
-    """Parse @foo/bar to read"""
+    """Parse @foo/bar to read, with recursive loading of nested @ references"""
     last_user_input = get_last_new_user_input(session)
     if not last_user_input or "@" not in last_user_input:
         return None
@@ -53,38 +118,16 @@ async def at_file_reader_reminder(
 
     at_files: dict[str, model.AtPatternParseResult] = {}  # path -> content
     collected_images: list[model.ImageURLPart] = []
+    visited: set[str] = set()
 
     for pattern in at_patterns:
-        path = Path(pattern).resolve()
-        context_token = set_tool_context_from_session(session)
-        try:
-            if path.exists() and path.is_file():
-                args = ReadTool.ReadArguments(file_path=str(path))
-                tool_result = await ReadTool.call_with_args(args)
-                at_result = model.AtPatternParseResult(
-                    path=str(path),
-                    tool_name=tools.READ,
-                    result=tool_result.output or "",
-                    tool_args=args.model_dump_json(exclude_none=True),
-                    operation="Read",
-                    images=tool_result.images,
-                )
-                at_files[str(path)] = at_result
-                if tool_result.images:
-                    collected_images.extend(tool_result.images)
-            elif path.exists() and path.is_dir():
-                quoted_path = shlex.quote(str(path))
-                args = BashTool.BashArguments(command=f"ls {quoted_path}")
-                tool_result = await BashTool.call_with_args(args)
-                at_files[str(path)] = model.AtPatternParseResult(
-                    path=str(path) + "/",
-                    tool_name=tools.BASH,
-                    result=tool_result.output or "",
-                    tool_args=args.model_dump_json(exclude_none=True),
-                    operation="List",
-                )
-        finally:
-            reset_tool_context(context_token)
+        await _load_at_file_recursive(
+            session,
+            pattern,
+            at_files,
+            collected_images,
+            visited,
+        )
 
     if len(at_files) == 0:
         return None

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:
@@ -191,6 +182,14 @@ class TaskExecutor:
                                 yield am
                             case events.ResponseMetadataEvent() as e:
                                 metadata_accumulator.add(e.metadata)
+                                # Emit context usage event if available
+                                if e.metadata.usage is not None:
+                                    context_percent = e.metadata.usage.context_usage_percent
+                                    if context_percent is not None:
+                                        yield events.ContextUsageEvent(
+                                            session_id=session_ctx.session_id,
+                                            context_percent=context_percent,
+                                        )
                             case events.ToolResultEvent() as e:
                                 # Collect sub-agent task metadata from tool results
                                 if e.task_metadata is not None:
@@ -225,7 +224,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 +233,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
@@ -27,6 +28,7 @@ from .tool_runner import run_tool
 from .truncation import SimpleTruncationStrategy, TruncationStrategy, get_truncation_strategy, set_truncation_strategy
 from .web.mermaid_tool import MermaidTool
 from .web.web_fetch_tool import WebFetchTool
+from .web.web_search_tool import WebSearchTool
 
 __all__ = [
     "MEMORY_DIR_NAME",
@@ -38,6 +40,7 @@ __all__ = [
     "MermaidTool",
     "MultiEditTool",
     "ReadTool",
+    "ReportBackTool",
     "SafetyCheckResult",
     "SimpleTruncationStrategy",
     "Skill",
@@ -51,6 +54,7 @@ __all__ = [
     "TruncationStrategy",
     "UpdatePlanTool",
     "WebFetchTool",
+    "WebSearchTool",
     "WriteTool",
     "build_todo_context",
     "current_run_subtask_callback",

klaude_code/core/tool/report_back_tool.py

@@ -0,0 +1,84 @@
+"""ReportBackTool for sub-agents to return structured output."""
+
+from typing import Any, ClassVar, cast
+
+from klaude_code.protocol import llm_param, model, tools
+
+
+def _normalize_schema_types(schema: dict[str, Any]) -> dict[str, Any]:
+    """Recursively normalize JSON schema type values to lowercase.
+
+    Some LLMs (e.g., Gemini 3) generate type values in uppercase like "OBJECT", "STRING".
+    Standard JSON Schema requires lowercase type values.
+    """
+    result: dict[str, Any] = {}
+    for key, value in schema.items():
+        if key == "type" and isinstance(value, str):
+            result[key] = value.lower()
+        elif isinstance(value, dict):
+            result[key] = _normalize_schema_types(cast(dict[str, Any], value))
+        elif isinstance(value, list):
+            normalized_list: list[Any] = []
+            for item in cast(list[Any], value):
+                if isinstance(item, dict):
+                    normalized_list.append(_normalize_schema_types(cast(dict[str, Any], item)))
+                else:
+                    normalized_list.append(item)
+            result[key] = normalized_list
+        else:
+            result[key] = value
+    return result
+
+
+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.
+        """
+        normalized = _normalize_schema_types(schema)
+        return type("ReportBackTool", (ReportBackTool,), {"_schema": normalized})
+
+    @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/tool/web/web_search_tool.md

@@ -0,0 +1,23 @@
+- Search the web and use the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
+- Use this tool for accessing information beyond your knowledge cutoff
+- Searches are performed automatically within a single API call
+
+CRITICAL REQUIREMENT - You MUST follow this:
+- After answering the user's question, you MUST include a "Sources:" section at the end of your response
+- In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+- This is MANDATORY - never skip including sources in your response
+- Example format:
+
+[Your answer here]
+
+Sources:
+- [Source Title 1](https://example.com/1)
+- [Source Title 2](https://example.com/2)
+
+Usage notes:
+- Domain filtering is supported to include or block specific websites
+- Web search is only available in the US
+- Account for "Today's date" in <env>. For example, if <env> says "Today's date: 2025-07-01", and the user wants the latest docs, do not use 2024 in the search query. Use 2025.
+