klaude-code 1.2.15__py3-none-any.whl → 1.2.17__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.py

@@ -0,0 +1,78 @@
+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_AGENT_DESCRIPTION = """\
+Launch a sub-agent to search the web, fetch pages, and analyze content. Use this for:
+- Accessing up-to-date information beyond your knowledge cutoff (current events, recent releases, latest docs)
+- Researching topics, news, APIs, or technical references
+- Fetching and analyzing specific URLs
+- Gathering comprehensive information from multiple web sources
+
+Capabilities:
+- Search the web to find relevant pages (no URL required)
+- Fetch and parse web pages (HTML-to-Markdown conversion)
+- Follow links across multiple pages autonomously
+- Aggregate findings from multiple sources
+
+How to use:
+- Write a clear prompt describing what information you need - the agent will search and fetch as needed
+- Optionally provide a `url` if you already know the target page
+- Use `output_format` (JSON Schema) to get structured data back from the agent
+- 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.
+
+What you receive:
+- The agent returns a text response summarizing its findings
+- With `output_format`, you receive structured JSON matching your schema
+- The response is the agent's analysis, not raw web content\
+"""
+
+WEB_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. If not provided, the agent will search the web first",
+        },
+        "prompt": {
+            "type": "string",
+            "description": "Instructions for searching, analyzing, or extracting content from the web page",
+        },
+        "output_format": {
+            "type": "object",
+            "description": "Optional JSON Schema for sub-agent structured output",
+        },
+    },
+    "required": ["description", "prompt"],
+    "additionalProperties": False,
+}
+
+
+def _web_agent_prompt_builder(args: dict[str, Any]) -> str:
+    """Build the WebAgent prompt from tool arguments."""
+    url = args.get("url", "")
+    prompt = args.get("prompt", "")
+    if url:
+        return f"URL to fetch: {url}\nTask: {prompt}"
+    return prompt
+
+
+register_sub_agent(
+    SubAgentProfile(
+        name="WebAgent",
+        description=WEB_AGENT_DESCRIPTION,
+        parameters=WEB_AGENT_PARAMETERS,
+        prompt_file="prompts/prompt-sub-agent-web.md",
+        tool_set=(tools.BASH, tools.READ, tools.WEB_FETCH, tools.WEB_SEARCH),
+        prompt_builder=_web_agent_prompt_builder,
+        active_form="Surfing",
+        output_schema_arg="output_format",
+    )
+)

klaude_code/protocol/tools.py

@@ -10,6 +10,8 @@ SKILL = "Skill"
 MERMAID = "Mermaid"
 MEMORY = "Memory"
 WEB_FETCH = "WebFetch"
+WEB_SEARCH = "WebSearch"
+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,18 +662,112 @@
         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;
       }
 
       /* Markdown Elements */
       .markdown-body {
         font-family: var(--font-markdown);
-        line-height: 1.5;
+        line-height: 1.6;
+        font-size: var(--font-size-base);
+      }
+      .markdown-body > *:first-child {
+        margin-top: 0 !important;
+      }
+      .markdown-body > *:last-child {
+        margin-bottom: 0 !important;
+      }
+      
+      .markdown-body h1,
+      .markdown-body h2,
+      .markdown-body h3,
+      .markdown-body h4,
+      .markdown-body h5,
+      .markdown-body h6 {
+        margin-top: 24px;
+        margin-bottom: 16px;
+        font-weight: var(--font-weight-bold);
+        line-height: 1.25;
+      }
+
+      .markdown-body a {
+        color: var(--accent);
+        text-decoration: none;
+        border-bottom: 1px solid rgba(8, 81, 178, 0.2);
+        transition: border-color 0.2s, background-color 0.2s;
+      }
+      .markdown-body a:hover {
+        border-bottom-color: var(--accent);
+        background-color: rgba(8, 81, 178, 0.05);
+        border-radius: 2px;
+      }
+
+      .markdown-body p {
+        margin-bottom: 8px; /* Tighter spacing */
+      }
+      
+      .markdown-body ul,
+      .markdown-body ol {
+        margin-bottom: 8px; /* Tighter spacing */
+        padding-left: 1.5rem;
+        list-style-position: outside;
+      }
+      
+      .markdown-body ul ul,
+      .markdown-body ol ul,
+      .markdown-body ul ol,
+      .markdown-body ol ol {
+        margin-top: 0;
+        margin-bottom: 0;
+      }
+      
+      .markdown-body li > p {
+        margin-bottom: 0;
+      }
+      .markdown-body li + li {
+        margin-top: 0.25em;
       }
+
+      .markdown-body blockquote {
+        margin: 0 0 16px;
+        padding: 0 1em;
+        color: var(--text-dim);
+        border-left: 0.25em solid var(--border);
+      }
+
+      .markdown-body table {
+        border-collapse: collapse;
+        width: 100%;
+        margin-top: 8px;
+        margin-bottom: 16px;
+        display: block;
+        overflow-x: auto;
+      }
+      
+      .markdown-body table tr {
+        background-color: var(--bg-card);
+        border-top: 1px solid var(--border);
+      }
+      
+      .markdown-body table tr:nth-child(2n) {
+        background-color: rgba(0, 0, 0, 0.02);
+      }
+      
+      .markdown-body table th,
+      .markdown-body table td {
+        padding: 6px 13px;
+        border: 1px solid var(--border);
+      }
+      
+      .markdown-body table th {
+        font-weight: var(--font-weight-bold);
+        background-color: rgba(0, 0, 0, 0.04);
+      }
+
       .markdown-body hr {
         height: 0;
         margin: 24px 0;
@@ -682,10 +776,10 @@
       }
       .markdown-body pre {
         background: var(--bg-code);
-        padding: 16px;
+        padding: 12px;
         border-radius: var(--radius-md);
         overflow-x: auto;
-        margin: 12px 0;
+        margin: 8px 0 16px 0;
         border: 1px solid var(--border);
       }
       .markdown-body code {
@@ -694,36 +788,17 @@
         font-size: var(--font-size-sm);
         padding: 2px 4px;
         border-radius: var(--radius-sm);
+        background-color: rgba(0, 0, 0, 0.05); /* Slight bg for inline code */
       }
       .markdown-body pre code {
         background: transparent;
         padding: 0;
         border-radius: 0;
+        color: inherit;
       }
       .markdown-body pre code.hljs {
         background: transparent;
       }
-      .markdown-body p {
-        margin-bottom: 12px;
-      }
-      .markdown-body > *:first-child {
-        margin-top: 0;
-      }
-      .markdown-body > *:last-child {
-        margin-bottom: 0;
-      }
-      .markdown-body ul,
-      .markdown-body ol {
-        margin-bottom: 12px;
-        padding-left: 1.5rem;
-        list-style-position: outside;
-      }
-      .markdown-body ul ul,
-      .markdown-body ol ul,
-      .markdown-body ul ol,
-      .markdown-body ol ol {
-        margin-left: 1rem;
-      }
 
       /* Diff View */
       .diff-view {
@@ -1297,17 +1372,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: