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

klaude_code/protocol/sub_agent/oracle.py

@@ -0,0 +1,91 @@
+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
+
+ORACLE_DESCRIPTION = """\
+Consult the Oracle - an AI advisor powered by OpenAI's premium reasoning model that can plan, review, and provide expert guidance.
+
+The Oracle has access to the following tools: Read, Bash.
+
+The Oracle acts as your senior engineering advisor and can help with:
+
+WHEN TO USE THE ORACLE:
+- Code reviews and architecture feedback
+- Finding a bug in multiple files
+- Planning complex implementations or refactoring
+- Analyzing code quality and suggesting improvements
+- Answering complex technical questions that require deep reasoning
+
+WHEN NOT TO USE THE ORACLE:
+- Simple file reading or searching tasks (use Read or Grep directly)
+- Codebase searches (use Task)
+- Basic code modifications and when you need to execute code changes (do it yourself or use Task)
+
+USAGE GUIDELINES:
+1. Be specific about what you want the Oracle to review, plan, or debug
+2. Provide relevant context about what you're trying to achieve. If you know that any files are involved, list them and they will be attached.
+
+
+EXAMPLES:
+- "Review the authentication system architecture and suggest improvements"
+- "Plan the implementation of real-time collaboration features"
+- "Analyze the performance bottlenecks in the data processing pipeline"
+- "Review this API design and suggest better patterns"\
+"""
+
+ORACLE_PARAMETERS = {
+    "properties": {
+        "context": {
+            "description": "Optional context about the current situation, what you've tried, or background information that would help the Oracle provide better guidance.",
+            "type": "string",
+        },
+        "files": {
+            "description": "Optional list of specific file paths (text files, images) that the Oracle should examine as part of its analysis. These files will be attached to the Oracle input.",
+            "items": {"type": "string"},
+            "type": "array",
+        },
+        "task": {
+            "description": "The task or question you want the Oracle to help with. Be specific about what kind of guidance, review, or planning you need.",
+            "type": "string",
+        },
+        "description": {
+            "description": "A short (3-5 word) description of the task",
+            "type": "string",
+        },
+    },
+    "required": ["task", "description"],
+    "type": "object",
+}
+
+
+def _oracle_prompt_builder(args: dict[str, Any]) -> str:
+    """Build the Oracle prompt from tool arguments."""
+    context = args.get("context", "")
+    task = args.get("task", "")
+    files = args.get("files", [])
+
+    prompt = f"""\
+Context: {context}
+Task: {task}\
+"""
+    if files:
+        files_str = "\n".join(f"@{file}" for file in files)
+        prompt += f"\nRelated files to review:\n{files_str}"
+    return prompt
+
+
+register_sub_agent(
+    SubAgentProfile(
+        name="Oracle",
+        description=ORACLE_DESCRIPTION,
+        parameters=ORACLE_PARAMETERS,
+        prompt_file="prompts/prompt-sub-agent-oracle.md",
+        tool_set=(tools.READ, tools.BASH),
+        prompt_builder=_oracle_prompt_builder,
+        active_form="Consulting Oracle",
+        target_model_filter=lambda model: ("gpt-5" not in model) and ("gemini-3" not in model),
+    )
+)

klaude_code/protocol/sub_agent/task.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from klaude_code.protocol import tools
+from klaude_code.protocol.sub_agent import SubAgentProfile, register_sub_agent
+
+TASK_DESCRIPTION = """\
+Launch a new agent to handle complex, multi-step tasks autonomously. \
+
+When NOT to use the Task tool:
+- If you want to read a specific file path, use the Read or Bash tool for `rg` instead of the Task tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Bash tool for `rg` instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly
+- Other tasks that are not related to the agent descriptions above
+
+Usage notes:
+- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+- 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.
+- Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+- The agent's outputs should generally be trusted
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent
+- 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.
+- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Task tool use content blocks. For example, if you need to launch both a code-reviewer agent and a test-runner agent in parallel, send a single message with both tool calls.
+
+Structured output:
+- Provide an `output_format` (JSON Schema) parameter for structured data back from the 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"]}`\
+"""
+
+TASK_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "description": {
+            "type": "string",
+            "description": "A short (3-5 word) description of the task",
+        },
+        "prompt": {
+            "type": "string",
+            "description": "The task for the agent to perform",
+        },
+        "output_format": {
+            "type": "object",
+            "description": (
+                "Optional JSON Schema for structured output, better with examples in argument descriptions."
+            ),
+        },
+    },
+    "required": ["description", "prompt"],
+    "additionalProperties": False,
+}
+
+register_sub_agent(
+    SubAgentProfile(
+        name="Task",
+        description=TASK_DESCRIPTION,
+        parameters=TASK_PARAMETERS,
+        prompt_file="prompts/prompt-sub-agent.md",
+        tool_set=(tools.BASH, tools.READ, tools.EDIT, tools.WRITE),
+        active_form="Tasking",
+        output_schema_arg="output_format",
+    )
+)

klaude_code/protocol/sub_agent/web_fetch.py

@@ -0,0 +1,74 @@
+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
+
+WEB_FETCH_AGENT_DESCRIPTION = """\
+Launch a sub-agent to fetch and analyze web content. Use this when you need to:
+- Retrieve and extract information from a webpage
+- Analyze web page content based on specific instructions
+- Get structured data from URLs
+
+This is an autonomous agent with its own reasoning capabilities. It can:
+- Follow links and navigate across multiple pages to gather comprehensive information
+- Decide which related pages to visit based on the initial content
+- Aggregate information from multiple sources into a coherent response
+
+The agent will fetch the URL content, handle HTML-to-Markdown conversion automatically, \
+and can use tools like rg to search through large responses that were truncated and saved to files.
+
+Usage notes:
+- Provide a clear prompt describing what information to extract or analyze
+- Provide an `output_format` (JSON Schema) parameter for structured data back from the sub-agent
+  - Example: `output_format={"type": "object", "properties": {"main_content": {"type": "string", "description": "The main content extracted from the page, e.g. 'This article discusses...'"}, "key_insights": {"type": "array", "items": {"type": "string"}, "description": "Key takeaways from the content, e.g. ['Insight 1', 'Insight 2']"}}, "required": ["main_content", "key_insights"]}`
+- The agent will return a summary of the findings
+- For large web pages, the content may be truncated and saved to a file; the agent can search through it
+- The agent can autonomously follow links to related pages if needed to complete the task\
+"""
+
+WEB_FETCH_AGENT_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "description": {
+            "type": "string",
+            "description": "A short (3-5 word) description of the task",
+        },
+        "url": {
+            "type": "string",
+            "description": "The URL to fetch and analyze",
+        },
+        "prompt": {
+            "type": "string",
+            "description": "Instructions for analyzing or extracting content from the web page",
+        },
+        "output_format": {
+            "type": "object",
+            "description": "Optional JSON Schema for sub-agent structured output",
+        },
+    },
+    "required": ["description", "url", "prompt", "output_format"],
+    "additionalProperties": False,
+}
+
+
+def _web_fetch_prompt_builder(args: dict[str, Any]) -> str:
+    """Build the WebFetchAgent prompt from tool arguments."""
+    url = args.get("url", "")
+    prompt = args.get("prompt", "")
+    return f"URL to fetch: {url}\nTask: {prompt}"
+
+
+register_sub_agent(
+    SubAgentProfile(
+        name="WebFetchAgent",
+        description=WEB_FETCH_AGENT_DESCRIPTION,
+        parameters=WEB_FETCH_AGENT_PARAMETERS,
+        prompt_file="prompts/prompt-sub-agent-webfetch.md",
+        tool_set=(tools.BASH, tools.READ, tools.WEB_FETCH),
+        prompt_builder=_web_fetch_prompt_builder,
+        active_form="Fetching Web",
+        output_schema_arg="output_format",
+    )
+)

klaude_code/protocol/tools.py

@@ -10,6 +10,7 @@ SKILL = "Skill"
 MERMAID = "Mermaid"
 MEMORY = "Memory"
 WEB_FETCH = "WebFetch"
+REPORT_BACK = "report_back"
 
 # SubAgentType is just a string alias now; agent types are defined via SubAgentProfile
 SubAgentType = str

klaude_code/session/export.py

@@ -299,18 +299,24 @@ def _try_render_todo_args(arguments: str) -> str | None:
 
 
 def _render_sub_agent_result(content: str) -> str:
-    encoded = _escape_html(content)
+    # Try to format as JSON for better readability
+    try:
+        parsed = json.loads(content)
+        formatted = "```json\n" + json.dumps(parsed, ensure_ascii=False, indent=2) + "\n```"
+    except (json.JSONDecodeError, TypeError):
+        formatted = content
+    encoded = _escape_html(formatted)
     return (
-        f'<div class="subagent-result-container">'
-        f'<div class="subagent-toolbar">'
+        f'<div class="sub-agent-result-container">'
+        f'<div class="sub-agent-toolbar">'
         f'<button type="button" class="raw-toggle" aria-pressed="false" title="Toggle raw text view">Raw</button>'
         f'<button type="button" class="copy-raw-btn" title="Copy raw content">Copy</button>'
         f"</div>"
-        f'<div class="subagent-content">'
-        f'<div class="subagent-rendered markdown-content markdown-body" data-raw="{encoded}">'
+        f'<div class="sub-agent-content">'
+        f'<div class="sub-agent-rendered markdown-content markdown-body" data-raw="{encoded}">'
         f'<noscript><pre style="white-space: pre-wrap;">{encoded}</pre></noscript>'
         f"</div>"
-        f'<pre class="subagent-raw">{encoded}</pre>'
+        f'<pre class="sub-agent-raw">{encoded}</pre>'
         f"</div>"
         f"</div>"
     )

klaude_code/session/session.py

@@ -7,7 +7,7 @@ from typing import ClassVar
 
 from pydantic import BaseModel, Field, PrivateAttr
 
-from klaude_code.protocol import events, model
+from klaude_code.protocol import events, model, tools
 
 
 class Session(BaseModel):
@@ -270,6 +270,7 @@ class Session(BaseModel):
         seen_sub_agent_sessions: set[str] = set()
         prev_item: model.ConversationItem | None = None
         last_assistant_content: str = ""
+        report_back_result: str | None = None
         yield events.TaskStartEvent(session_id=self.id, sub_agent_state=self.sub_agent_state)
         for it in self.conversation_history:
             if self.need_turn_start(prev_item, it):
@@ -286,6 +287,8 @@ class Session(BaseModel):
                         session_id=self.id,
                     )
                 case model.ToolCallItem() as tc:
+                    if tc.name == tools.REPORT_BACK:
+                        report_back_result = tc.arguments
                     yield events.ToolCallEvent(
                         tool_call_id=tc.call_id,
                         tool_name=tc.name,
@@ -336,7 +339,14 @@ class Session(BaseModel):
                 case _:
                     continue
             prev_item = it
-        yield events.TaskFinishEvent(session_id=self.id, task_result=last_assistant_content)
+
+        has_structured_output = report_back_result is not None
+        task_result = report_back_result if has_structured_output else last_assistant_content
+        yield events.TaskFinishEvent(
+            session_id=self.id,
+            task_result=task_result,
+            has_structured_output=has_structured_output,
+        )
 
     def _iter_sub_agent_history(
         self, tool_result: model.ToolResultItem, seen_sub_agent_sessions: set[str]

klaude_code/session/templates/export_session.html

@@ -632,26 +632,26 @@
         color: var(--text-dim);
       }
 
-      /* Sub Agent Result */
-      .subagent-result-container {
+      /* Sub-Agent Result */
+      .sub-agent-result-container {
         display: flex;
         flex-direction: column;
         gap: 8px;
         margin-top: 8px;
       }
 
-      .subagent-toolbar {
+      .sub-agent-toolbar {
         display: flex;
         justify-content: flex-end;
         align-items: center;
         margin-bottom: 4px;
       }
 
-      .subagent-content {
+      .sub-agent-content {
         width: 100%;
       }
 
-      .subagent-raw {
+      .sub-agent-raw {
         display: none;
         font-family: var(--font-mono);
         font-size: var(--font-size-base);
@@ -662,10 +662,10 @@
         padding: 20px;
       }
 
-      .subagent-content.show-raw .subagent-rendered {
+      .sub-agent-content.show-raw .sub-agent-rendered {
         display: none;
       }
-      .subagent-content.show-raw .subagent-raw {
+      .sub-agent-content.show-raw .sub-agent-raw {
         display: block;
       }
 
@@ -1297,17 +1297,17 @@
         });
       });
 
-      // Subagent raw toggle
+      // Sub-agent raw toggle
       document
-        .querySelectorAll(".subagent-result-container")
+        .querySelectorAll(".sub-agent-result-container")
         .forEach((group) => {
           const toggle = group.querySelector(".raw-toggle");
           const copyBtn = group.querySelector(".copy-raw-btn");
-          const block = group.querySelector(".subagent-content");
+          const block = group.querySelector(".sub-agent-content");
           const rendered = block
-            ? block.querySelector(".subagent-rendered")
+            ? block.querySelector(".sub-agent-rendered")
             : null;
-          const raw = block ? block.querySelector(".subagent-raw") : null;
+          const raw = block ? block.querySelector(".sub-agent-raw") : null;
 
           // Copy button logic
           if (copyBtn && rendered) {

klaude_code/ui/modes/repl/completers.py

@@ -85,7 +85,7 @@ class _SlashCommandCompleter(Completer):
         matched: list[tuple[str, object, str]] = []
         for cmd_name, cmd_obj in commands.items():
             if cmd_name.startswith(frag):
-                hint = " [args]" if cmd_obj.support_addition_params else ""
+                hint = " [instructions]" if cmd_obj.support_addition_params else ""
                 matched.append((cmd_name, cmd_obj, hint))
 
         if not matched:

klaude_code/ui/modes/repl/event_handler.py

@@ -121,7 +121,7 @@ class ActivityState:
             for name, count in self._tool_calls.items():
                 if not first:
                     activity_text.append(", ")
-                activity_text.append(name, style="bold")
+                activity_text.append(name)
                 if count > 1:
                     activity_text.append(f" x {count}")
                 first = False
@@ -175,6 +175,10 @@ class SpinnerStatusState:
         """Clear activity state for a new turn."""
         self._activity.reset()
 
+    def get_activity_text(self) -> Text | None:
+        """Get current activity text. Returns None if idle."""
+        return self._activity.get_activity_text()
+
     def get_status(self) -> Text:
         """Get current spinner status as rich Text."""
         activity_text = self._activity.get_activity_text()
@@ -377,6 +381,7 @@ class DisplayEventHandler:
         self.spinner_status.set_composing(False)
         self._update_spinner()
         await self.stage_manager.transition_to(Stage.WAITING)
+        self.renderer.print()
         self.renderer.spinner_start()
 
     def _on_tool_call_start(self, event: events.TurnToolCallStartEvent) -> None:
@@ -476,6 +481,7 @@ class DisplayEventHandler:
             mdstream.update(self.thinking_stream.buffer, final=True)
             self.thinking_stream.finish()
             self.renderer.console.pop_theme()
+            self.renderer.print()
             self.renderer.spinner_start()
 
     def _maybe_notify_task_finish(self, event: events.TaskFinishEvent) -> None:
@@ -512,7 +518,31 @@ class DisplayEventHandler:
                 if len(todo.content) > 0:
                     status_text = todo.content
         status_text = status_text.replace("\n", "")
-        return self._truncate_status_text(status_text, max_length=50)
+        max_length = self._calculate_base_status_max_length()
+        return self._truncate_status_text(status_text, max_length=max_length)
+
+    def _calculate_base_status_max_length(self) -> int:
+        """Calculate max length for base_status based on terminal width.
+
+        Reserve space for:
+        - Spinner glyph + space: 2 chars
+        - " | " separator: 3 chars (only if activity text present)
+        - Activity text: actual length (only if present)
+        - Status hint text (esc to interrupt)
+        """
+        terminal_width = self.renderer.console.size.width
+
+        # Base reserved space: spinner + status hint
+        reserved_space = 2 + len(const.STATUS_HINT_TEXT)
+
+        # Add space for activity text if present
+        activity_text = self.spinner_status.get_activity_text()
+        if activity_text:
+            # " | " separator + actual activity text length
+            reserved_space += 3 + len(activity_text.plain)
+
+        max_length = max(10, terminal_width - reserved_space)
+        return max_length
 
     def _truncate_status_text(self, text: str, max_length: int) -> str:
         if len(text) <= max_length:

klaude_code/ui/modes/repl/renderer.py

@@ -50,7 +50,7 @@ class REPLRenderer:
 
         self.session_map: dict[str, SessionStatus] = {}
         self.current_sub_agent_color: Style | None = None
-        self.subagent_color_index = 0
+        self.sub_agent_color_index = 0
 
     def register_session(self, session_id: str, sub_agent_state: model.SubAgentState | None = None) -> None:
         session_status = SessionStatus(
@@ -66,16 +66,16 @@ class REPLRenderer:
     def _advance_sub_agent_color_index(self) -> None:
         palette_size = len(self.themes.sub_agent_colors)
         if palette_size == 0:
-            self.subagent_color_index = 0
+            self.sub_agent_color_index = 0
             return
-        self.subagent_color_index = (self.subagent_color_index + 1) % palette_size
+        self.sub_agent_color_index = (self.sub_agent_color_index + 1) % palette_size
 
     def pick_sub_agent_color(self) -> Style:
         self._advance_sub_agent_color_index()
         palette = self.themes.sub_agent_colors
         if not palette:
             return Style()
-        return palette[self.subagent_color_index]
+        return palette[self.sub_agent_color_index]
 
     def get_session_sub_agent_color(self, session_id: str) -> Style:
         status = self.session_map.get(session_id)
@@ -100,9 +100,9 @@ class REPLRenderer:
         if self.current_sub_agent_color:
             if objects:
                 content = objects[0] if len(objects) == 1 else objects
-                self.console.print(Quote(content, style=self.current_sub_agent_color))
+                self.console.print(Quote(content, style=self.current_sub_agent_color), overflow="ellipsis")
             return
-        self.console.print(*objects, style=style, end=end)
+        self.console.print(*objects, style=style, end=end, overflow="ellipsis")
 
     def display_tool_call(self, e: events.ToolCallEvent) -> None:
         if r_tools.is_sub_agent_tool(e.tool_name):
@@ -152,6 +152,7 @@ class REPLRenderer:
                     case events.ThinkingEvent() as e:
                         if is_sub_agent:
                             continue
+                        self.display_thinking_prefix()
                         self.display_thinking(e.content)
                     case events.DeveloperMessageEvent() as e:
                         self.display_developer_message(e)
@@ -233,6 +234,7 @@ class REPLRenderer:
                     r_sub_agent.render_sub_agent_result(
                         event.task_result,
                         code_theme=self.themes.code_theme,
+                        has_structured_output=event.has_structured_output,
                     )
                 )
 

klaude_code/ui/renderers/developer.py

@@ -67,13 +67,24 @@ def render_developer_message(e: events.DeveloperMessageEvent) -> RenderableType:
     if e.item.at_files:
         grid = create_grid()
         for at_file in e.item.at_files:
-            grid.add_row(
-                Text("  +", style=ThemeKey.REMINDER),
-                Text.assemble(
-                    (f"{at_file.operation} ", ThemeKey.REMINDER),
-                    render_path(at_file.path, ThemeKey.REMINDER_BOLD),
-                ),
-            )
+            if at_file.mentioned_in:
+                grid.add_row(
+                    Text("  +", style=ThemeKey.REMINDER),
+                    Text.assemble(
+                        (f"{at_file.operation} ", ThemeKey.REMINDER),
+                        render_path(at_file.path, ThemeKey.REMINDER_BOLD),
+                        (" mentioned in ", ThemeKey.REMINDER),
+                        render_path(at_file.mentioned_in, ThemeKey.REMINDER_BOLD),
+                    ),
+                )
+            else:
+                grid.add_row(
+                    Text("  +", style=ThemeKey.REMINDER),
+                    Text.assemble(
+                        (f"{at_file.operation} ", ThemeKey.REMINDER),
+                        render_path(at_file.path, ThemeKey.REMINDER_BOLD),
+                    ),
+                )
         parts.append(grid)
 
     if uic := e.item.user_image_count:

klaude_code/ui/renderers/metadata.py

@@ -59,20 +59,32 @@ def _render_task_metadata_block(
     parts: list[Text] = []
 
     if metadata.usage is not None:
-        # Tokens: ↑37k c5k ↓907 r45k
-        token_parts: list[tuple[str, str]] = [
-            ("↑", ThemeKey.METADATA_DIM),
-            (format_number(metadata.usage.input_tokens), ThemeKey.METADATA),
+        # Tokens: ↑ 37k cache 5k ↓ 907 think 45k
+        token_parts: list[Text] = [
+            Text.assemble(
+                ("↑ ", ThemeKey.METADATA_DIM), (format_number(metadata.usage.input_tokens), ThemeKey.METADATA)
+            )
         ]
         if metadata.usage.cached_tokens > 0:
-            token_parts.append((" c", ThemeKey.METADATA_DIM))
-            token_parts.append((format_number(metadata.usage.cached_tokens), ThemeKey.METADATA))
-        token_parts.append((" ↓", ThemeKey.METADATA_DIM))
-        token_parts.append((format_number(metadata.usage.output_tokens), ThemeKey.METADATA))
+            token_parts.append(
+                Text.assemble(
+                    Text("cache ", style=ThemeKey.METADATA_DIM),
+                    Text(format_number(metadata.usage.cached_tokens), style=ThemeKey.METADATA),
+                )
+            )
+        token_parts.append(
+            Text.assemble(
+                ("↓ ", ThemeKey.METADATA_DIM), (format_number(metadata.usage.output_tokens), ThemeKey.METADATA)
+            )
+        )
         if metadata.usage.reasoning_tokens > 0:
-            token_parts.append((" r", ThemeKey.METADATA_DIM))
-            token_parts.append((format_number(metadata.usage.reasoning_tokens), ThemeKey.METADATA))
-        parts.append(Text.assemble(*token_parts))
+            token_parts.append(
+                Text.assemble(
+                    ("think ", ThemeKey.METADATA_DIM),
+                    (format_number(metadata.usage.reasoning_tokens), ThemeKey.METADATA),
+                )
+            )
+        parts.append(Text(" · ").join(token_parts))
 
     # Cost
     if metadata.usage is not None and metadata.usage.total_cost is not None:
@@ -141,7 +153,7 @@ def render_task_metadata(e: events.TaskMetadataEvent) -> RenderableType:
     for meta in sorted_items:
         renderables.append(_render_task_metadata_block(meta, is_sub_agent=True, show_context_and_time=False))
 
-    return Padding(Group(*renderables), (0, 0, 0, 1))
+    return Group(*renderables)
 
 
 def render_welcome(e: events.WelcomeEvent, *, box_style: Box | None = None) -> RenderableType: