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

klaude_code/core/tool/web/web_search_tool.py

@@ -0,0 +1,126 @@
+import asyncio
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_registry import register
+from klaude_code.protocol import llm_param, model, tools
+
+DEFAULT_MAX_RESULTS = 10
+MAX_RESULTS_LIMIT = 20
+
+
+@dataclass
+class SearchResult:
+    """A single search result from DuckDuckGo."""
+
+    title: str
+    url: str
+    snippet: str
+    position: int
+
+
+def _search_duckduckgo(query: str, max_results: int) -> list[SearchResult]:
+    """Perform a web search using ddgs library."""
+    from ddgs import DDGS  # type: ignore
+
+    results: list[SearchResult] = []
+
+    with DDGS() as ddgs:
+        for i, r in enumerate(ddgs.text(query, max_results=max_results)):
+            results.append(
+                SearchResult(
+                    title=r.get("title", ""),
+                    url=r.get("href", ""),
+                    snippet=r.get("body", ""),
+                    position=i + 1,
+                )
+            )
+
+    return results
+
+
+def _format_results(results: list[SearchResult]) -> str:
+    """Format search results for LLM consumption."""
+    if not results:
+        return (
+            "No results were found for your search query. "
+            "Please try rephrasing your search or using different keywords."
+        )
+
+    lines = [f"Found {len(results)} search results:\n"]
+
+    for result in results:
+        lines.append(f"{result.position}. {result.title}")
+        lines.append(f"   URL: {result.url}")
+        lines.append(f"   Summary: {result.snippet}\n")
+
+    return "\n".join(lines)
+
+
+@register(tools.WEB_SEARCH)
+class WebSearchTool(ToolABC):
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        return llm_param.ToolSchema(
+            name=tools.WEB_SEARCH,
+            type="function",
+            description=load_desc(Path(__file__).parent / "web_search_tool.md"),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "The search query to use",
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": f"Maximum number of results to return (default: {DEFAULT_MAX_RESULTS}, max: {MAX_RESULTS_LIMIT})",
+                    },
+                },
+                "required": ["query"],
+            },
+        )
+
+    class WebSearchArguments(BaseModel):
+        query: str
+        max_results: int = DEFAULT_MAX_RESULTS
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        try:
+            args = WebSearchTool.WebSearchArguments.model_validate_json(arguments)
+        except ValueError as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Invalid arguments: {e}",
+            )
+        return await cls.call_with_args(args)
+
+    @classmethod
+    async def call_with_args(cls, args: WebSearchArguments) -> model.ToolResultItem:
+        query = args.query.strip()
+        if not query:
+            return model.ToolResultItem(
+                status="error",
+                output="Query cannot be empty",
+            )
+
+        max_results = min(max(args.max_results, 1), MAX_RESULTS_LIMIT)
+
+        try:
+            results = await asyncio.to_thread(_search_duckduckgo, query, max_results)
+            formatted = _format_results(results)
+
+            return model.ToolResultItem(
+                status="success",
+                output=formatted,
+            )
+
+        except Exception as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Search failed: {e}",
+            )

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/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/commands.py

@@ -11,6 +11,7 @@ class CommandName(str, Enum):
     CLEAR = "clear"
     TERMINAL_SETUP = "terminal-setup"
     EXPORT = "export"
+    EXPORT_ONLINE = "export-online"
     STATUS = "status"
     RELEASE_NOTES = "release-notes"
     THINKING = "thinking"

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):
@@ -132,6 +133,13 @@ class TodoChangeEvent(BaseModel):
     todos: list[model.TodoItem]
 
 
+class ContextUsageEvent(BaseModel):
+    """Real-time context usage update during task execution."""
+
+    session_id: str
+    context_percent: float  # Context usage percentage (0-100)
+
+
 HistoryItemEvent = (
     ThinkingEvent
     | TaskStartEvent
@@ -177,4 +185,5 @@ Event = (
     | TurnStartEvent
     | TurnEndEvent
     | TurnToolCallStartEvent
+    | ContextUsageEvent
 )

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 as web  # 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"],
+    "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",
+    )
+)