klaude-code 2.0.1__py3-none-any.whl → 2.1.0__py3-none-any.whl

klaude_code/protocol/events/lifecycle.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from klaude_code.protocol import model
+
+from .base import Event
+
+
+class TaskStartEvent(Event):
+    sub_agent_state: model.SubAgentState | None = None
+
+
+class TaskFinishEvent(Event):
+    task_result: str
+    has_structured_output: bool = False
+
+
+class TurnStartEvent(Event):
+    pass
+
+
+class TurnEndEvent(Event):
+    pass

klaude_code/protocol/events/metadata.py

@@ -0,0 +1,15 @@
+"""Metadata-related protocol events."""
+
+from __future__ import annotations
+
+from klaude_code.protocol import model
+
+from .base import Event, ResponseEvent
+
+
+class UsageEvent(ResponseEvent):
+    usage: model.Usage
+
+
+class TaskMetadataEvent(Event):
+    metadata: model.TaskMetadataItem

klaude_code/protocol/events/streaming.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from .base import ResponseEvent
+
+
+class ThinkingStartEvent(ResponseEvent):
+    pass
+
+
+class ThinkingDeltaEvent(ResponseEvent):
+    content: str
+
+
+class ThinkingEndEvent(ResponseEvent):
+    pass
+
+
+class AssistantTextStartEvent(ResponseEvent):
+    pass
+
+
+class AssistantTextDeltaEvent(ResponseEvent):
+    content: str
+
+
+class AssistantTextEndEvent(ResponseEvent):
+    pass
+
+
+class AssistantImageDeltaEvent(ResponseEvent):
+    file_path: str
+
+
+class ToolCallStartEvent(ResponseEvent):
+    tool_call_id: str
+    tool_name: str
+
+
+class ResponseCompleteEvent(ResponseEvent):
+    """Final snapshot of the model response."""
+
+    content: str
+    thinking_text: str | None = None

klaude_code/protocol/events/system.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from klaude_code.protocol import llm_param
+from klaude_code.protocol.events.chat import DeveloperMessageEvent, UserMessageEvent
+from klaude_code.protocol.events.lifecycle import TaskFinishEvent, TaskStartEvent, TurnStartEvent
+from klaude_code.protocol.events.metadata import TaskMetadataEvent
+from klaude_code.protocol.events.streaming import AssistantImageDeltaEvent, ResponseCompleteEvent
+from klaude_code.protocol.events.tools import ToolCallEvent, ToolResultEvent
+
+from .base import Event
+
+
+class WelcomeEvent(Event):
+    work_dir: str
+    llm_config: llm_param.LLMConfigParameter
+    show_klaude_code_info: bool = True
+
+
+class ErrorEvent(Event):
+    error_message: str
+    can_retry: bool = False
+
+
+class InterruptEvent(Event):
+    pass
+
+
+class EndEvent(Event):
+    """Global display shutdown."""
+
+    session_id: str = "__app__"
+
+
+type ReplayEventUnion = (
+    TaskStartEvent
+    | TaskFinishEvent
+    | TurnStartEvent
+    | AssistantImageDeltaEvent
+    | ResponseCompleteEvent
+    | ToolCallEvent
+    | ToolResultEvent
+    | UserMessageEvent
+    | TaskMetadataEvent
+    | InterruptEvent
+    | DeveloperMessageEvent
+    | ErrorEvent
+)
+
+
+class ReplayHistoryEvent(Event):
+    events: list[ReplayEventUnion]
+    updated_at: float
+    is_load: bool = True

klaude_code/protocol/events/tools.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from klaude_code.protocol import model
+
+from .base import ResponseEvent
+
+
+class ToolCallEvent(ResponseEvent):
+    tool_call_id: str
+    tool_name: str
+    arguments: str
+
+
+class ToolResultEvent(ResponseEvent):
+    tool_call_id: str
+    tool_name: str
+    result: str
+    ui_extra: model.ToolResultUIExtra | None = None
+    status: Literal["success", "error"]
+    task_metadata: model.TaskMetadata | None = None
+    is_last_in_turn: bool = True

klaude_code/protocol/message.py

@@ -12,8 +12,7 @@ from typing import Annotated, Literal
 from pydantic import BaseModel, Field, field_validator
 
 from klaude_code.protocol.model import (
-    AtPatternParseResult,
-    CommandOutput,
+    DeveloperUIExtra,
     StopReason,
     TaskMetadata,
     TaskMetadataItem,
@@ -137,15 +136,8 @@ class DeveloperMessage(MessageBase):
     role: Literal["developer"] = "developer"
     parts: list[Part]
 
-    # Special fields for reminders UI
-    memory_paths: list[str] | None = None
-    memory_mentioned: dict[str, list[str]] | None = None  # memory_path -> list of @ patterns mentioned in it
-    external_file_changes: list[str] | None = None
-    todo_use: bool | None = None
-    at_files: list[AtPatternParseResult] | None = None
-    command_output: CommandOutput | None = None
-    user_image_count: int | None = None
-    skill_name: str | None = None  # Skill name activated via $skill syntax
+    # Structured UI-only metadata (never sent to the LLM).
+    ui_extra: DeveloperUIExtra | None = None
 
 
 class UserMessage(MessageBase):

klaude_code/protocol/model.py

@@ -272,21 +272,90 @@ ToolResultUIExtra = Annotated[
 ]
 
 
-class AtPatternParseResult(BaseModel):
-    path: str
-    tool_name: str
-    result: str
-    tool_args: str
-    operation: Literal["Read", "List"]
-    mentioned_in: str | None = None  # Parent file that referenced this file
-
-
 class CommandOutput(BaseModel):
     command_name: CommandName
     ui_extra: ToolResultUIExtra | None = None
     is_error: bool = False
 
 
+class MemoryFileLoaded(BaseModel):
+    path: str
+    mentioned_patterns: list[str] = Field(default_factory=list)
+
+
+class MemoryLoadedUIItem(BaseModel):
+    type: Literal["memory_loaded"] = "memory_loaded"
+    files: list[MemoryFileLoaded]
+
+
+class ExternalFileChangesUIItem(BaseModel):
+    type: Literal["external_file_changes"] = "external_file_changes"
+    paths: list[str]
+
+
+class TodoReminderUIItem(BaseModel):
+    type: Literal["todo_reminder"] = "todo_reminder"
+    reason: Literal["empty", "not_used_recently"]
+
+
+class AtFileOp(BaseModel):
+    operation: Literal["Read", "List"]
+    path: str
+    mentioned_in: str | None = None
+
+
+class AtFileOpsUIItem(BaseModel):
+    type: Literal["at_file_ops"] = "at_file_ops"
+    ops: list[AtFileOp]
+
+
+class UserImagesUIItem(BaseModel):
+    type: Literal["user_images"] = "user_images"
+    count: int
+
+
+class SkillActivatedUIItem(BaseModel):
+    type: Literal["skill_activated"] = "skill_activated"
+    name: str
+
+
+class CommandOutputUIItem(BaseModel):
+    type: Literal["command_output"] = "command_output"
+    output: CommandOutput
+
+
+type DeveloperUIItem = (
+    MemoryLoadedUIItem
+    | ExternalFileChangesUIItem
+    | TodoReminderUIItem
+    | AtFileOpsUIItem
+    | UserImagesUIItem
+    | SkillActivatedUIItem
+    | CommandOutputUIItem
+)
+
+
+def _empty_developer_ui_items() -> list[DeveloperUIItem]:
+    return []
+
+
+class DeveloperUIExtra(BaseModel):
+    items: list[DeveloperUIItem] = Field(default_factory=_empty_developer_ui_items)
+
+
+def build_command_output_extra(
+    command_name: CommandName,
+    *,
+    ui_extra: ToolResultUIExtra | None = None,
+    is_error: bool = False,
+) -> DeveloperUIExtra:
+    return DeveloperUIExtra(
+        items=[
+            CommandOutputUIItem(output=CommandOutput(command_name=command_name, ui_extra=ui_extra, is_error=is_error))
+        ]
+    )
+
+
 class SubAgentState(BaseModel):
     sub_agent_type: SubAgentType
     sub_agent_desc: str

klaude_code/protocol/op.py

@@ -51,6 +51,11 @@ class RunAgentOperation(Operation):
     type: OperationType = OperationType.RUN_AGENT
     session_id: str
     input: UserInputPayload
+    # Frontends may choose to render the user message themselves (e.g. TUI) to support
+    # event-only commands; in that case the core should skip emitting the UserMessageEvent.
+    emit_user_message_event: bool = True
+    # Frontends may choose to run without persisting input (e.g. some interactive commands).
+    persist_user_input: bool = True
 
     async def execute(self, handler: OperationHandler) -> None:
         await handler.handle_run_agent(self)

klaude_code/protocol/sub_agent/explore.py

@@ -1,7 +1,5 @@
 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
 
@@ -37,11 +35,6 @@ EXPLORE_PARAMETERS = {
             "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",
@@ -52,13 +45,6 @@ EXPLORE_PARAMETERS = {
 }
 
 
-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",
@@ -66,7 +52,6 @@ register_sub_agent(
         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",
     )

klaude_code/protocol/sub_agent/task.py

@@ -64,7 +64,7 @@ register_sub_agent(
         description=TASK_DESCRIPTION,
         parameters=TASK_PARAMETERS,
         prompt_file="prompts/prompt-sub-agent.md",
-        tool_set=(tools.BASH, tools.READ, tools.EDIT, tools.WRITE, tools.MOVE),
+        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

@@ -1,7 +1,5 @@
 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
 
@@ -21,7 +19,7 @@ Capabilities:
 How to use:
 - Write a clear prompt describing what information you need - the agent will search and fetch as needed
 - 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.
-- Optionally provide a `url` if you already know the target page
+- Provide the url if you already know the target page
 - Use `output_format` (JSON Schema) to get structured data back from the agent
 
 What you receive:
@@ -48,10 +46,6 @@ WEB_AGENT_PARAMETERS = {
             "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",
@@ -66,15 +60,6 @@ WEB_AGENT_PARAMETERS = {
 }
 
 
-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",
@@ -82,7 +67,6 @@ register_sub_agent(
         parameters=WEB_AGENT_PARAMETERS,
         prompt_file="prompts/prompt-sub-agent-web.md",
         tool_set=(tools.BASH, tools.READ, tools.WEB_FETCH, tools.WEB_SEARCH, tools.WRITE),
-        prompt_builder=_web_agent_prompt_builder,
         active_form="Surfing",
         output_schema_arg="output_format",
     )

klaude_code/protocol/tools.py

@@ -1,6 +1,5 @@
 BASH = "Bash"
 APPLY_PATCH = "apply_patch"
-MOVE = "Move"
 EDIT = "Edit"
 
 READ = "Read"

klaude_code/session/session.py

@@ -289,7 +289,7 @@ class Session(BaseModel):
             return True
         return isinstance(prev_item, (message.UserMessage, message.ToolResultMessage, message.DeveloperMessage))
 
-    def get_history_item(self) -> Iterable[events.HistoryItemEvent]:
+    def get_history_item(self) -> Iterable[events.ReplayEventUnion]:
         seen_sub_agent_sessions: set[str] = set()
         prev_item: message.HistoryEvent | None = None
         last_assistant_content: str = ""
@@ -314,8 +314,8 @@ class Session(BaseModel):
                             response_id=am.response_id,
                             session_id=self.id,
                         )
-                    yield events.AssistantMessageEvent(
-                        thinking_text=thinking_text,
+                    yield events.ResponseCompleteEvent(
+                        thinking_text=thinking_text or None,
                         content=content,
                         response_id=am.response_id,
                         session_id=self.id,
@@ -360,7 +360,8 @@ class Session(BaseModel):
                         images=images or None,
                     )
                 case model.TaskMetadataItem() as mt:
-                    yield events.TaskMetadataEvent(session_id=self.id, metadata=mt)
+                    if self.sub_agent_state is None:
+                        yield events.TaskMetadataEvent(session_id=self.id, metadata=mt)
                 case message.DeveloperMessage() as dm:
                     yield events.DeveloperMessageEvent(session_id=self.id, item=dm)
                 case message.StreamErrorItem() as se:
@@ -377,7 +378,7 @@ class Session(BaseModel):
 
     def _iter_sub_agent_history(
         self, tool_result: message.ToolResultMessage, seen_sub_agent_sessions: set[str]
-    ) -> Iterable[events.HistoryItemEvent]:
+    ) -> Iterable[events.ReplayEventUnion]:
         ui_extra = tool_result.ui_extra
         if not isinstance(ui_extra, model.SessionIdUIExtra):
             return

klaude_code/skill/assets/create-plan/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: create-plan
+description: Create a concise plan. Use when a user explicitly asks for a plan related to a coding task.
+metadata:
+  short-description: Create a plan
+---
+
+# Create Plan
+
+## Goal
+
+Turn a user prompt into a **single, actionable plan** delivered in the final assistant message.
+
+## Minimal workflow
+
+1. **Scan context quickly**
+   - Read `README.md` and any obvious docs (`docs/`, `CONTRIBUTING.md`, `ARCHITECTURE.md`).
+   - Skim relevant files (the ones most likely touched).
+   - Identify constraints (language, frameworks, CI/test commands, deployment shape).
+
+2. **Ask follow-ups only if blocking**
+   - Ask **at most 1–2 questions**.
+   - Only ask if you cannot responsibly plan without the answer; prefer multiple-choice.
+   - If unsure but not blocked, make a reasonable assumption and proceed.
+
+3. **Create a plan using the template below**
+   - Start with **1 short paragraph** describing the intent and approach.
+   - Clearly call out what is **in scope** and what is **not in scope** in short.
+   - Then provide a **small checklist** of action items (default 6–10 items).
+      - Each checklist item should be a concrete action and, when helpful, mention files/commands.
+      - **Make items atomic and ordered**: discovery → changes → tests → rollout.
+      - **Verb-first**: “Add…”, “Refactor…”, “Verify…”, “Ship…”.
+   - Include at least one item for **tests/validation** and one for **edge cases/risk** when applicable.
+   - If there are unknowns, include a tiny **Open questions** section (max 3).
+
+4. **Write the plan to `plan.md` in the current working directory**
+   - Use the Write tool to save the plan to `./plan.md`
+   - If `plan.md` already exists, overwrite it with the new plan
+
+5. **Do not preface the plan with meta explanations; output only the plan as per template**
+
+## Plan template (follow exactly)
+
+```markdown
+# Plan
+
+<1–3 sentences: what we’re doing, why, and the high-level approach.>
+
+## Scope
+- In:
+- Out:
+
+## Action items
+[ ] <Step 1>
+[ ] <Step 2>
+[ ] <Step 3>
+[ ] <Step 4>
+[ ] <Step 5>
+[ ] <Step 6>
+
+## Open questions
+- <Question 1>
+- <Question 2>
+- <Question 3>
+```
+
+## Checklist item guidance
+Good checklist items:
+- Point to likely files/modules: src/..., app/..., services/...
+- Name concrete validation: “Run npm test”, “Add unit tests for X”
+- Include safe rollout when relevant: feature flag, migration plan, rollback note
+
+Avoid:
+- Vague steps (“handle backend”, “do auth”)
+- Too many micro-steps
+- Writing code snippets (keep the plan implementation-agnostic)

klaude_code/skill/loader.py

@@ -5,7 +5,7 @@ from typing import ClassVar
 
 import yaml
 
-from klaude_code.trace import log_debug
+from klaude_code.log import log_debug
 
 
 @dataclass

klaude_code/skill/system_skills.py

@@ -11,7 +11,7 @@ from contextlib import contextmanager
 from importlib import resources
 from pathlib import Path
 
-from klaude_code.trace import log_debug
+from klaude_code.log import log_debug
 
 # Marker file name for tracking installed skills version
 SYSTEM_SKILLS_MARKER_FILENAME = ".klaude-system-skills.marker"

klaude_code/tui/__init__.py

@@ -0,0 +1,8 @@
+"""Terminal (TUI) frontend for klaude-code.
+
+This package contains all terminal-specific UI code (Rich rendering,
+prompt-toolkit input, and terminal integrations).
+
+The tui layer may depend on `klaude_code.ui`, but `klaude_code.ui` must not
+depend on `klaude_code.tui`.
+"""

klaude_code/{command → tui/command}/clear_cmd.py

@@ -1,6 +1,7 @@
-from klaude_code.command.command_abc import Agent, CommandABC, CommandResult
 from klaude_code.protocol import commands, message, op
 
+from .command_abc import Agent, CommandABC, CommandResult
+
 
 class ClearCommand(CommandABC):
     """Clear current session and start a new conversation"""

klaude_code/{command → tui/command}/debug_cmd.py

@@ -1,6 +1,7 @@
-from klaude_code.command.command_abc import Agent, CommandABC, CommandResult
+from klaude_code.log import DebugType, get_current_log_file, is_debug_enabled, set_debug_logging
 from klaude_code.protocol import commands, events, message, model
-from klaude_code.trace import DebugType, get_current_log_file, is_debug_enabled, set_debug_logging
+
+from .command_abc import Agent, CommandABC, CommandResult
 
 
 def _format_status() -> str:
@@ -72,7 +73,7 @@ class DebugCommand(CommandABC):
                     session_id=agent.session.id,
                     item=message.DeveloperMessage(
                         parts=message.text_parts_from_str(content),
-                        command_output=model.CommandOutput(command_name=self.name),
+                        ui_extra=model.build_command_output_extra(self.name),
                     ),
                 )
             ]

klaude_code/{command → tui/command}/export_cmd.py

@@ -2,9 +2,10 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from klaude_code.command.command_abc import Agent, CommandABC, CommandResult
 from klaude_code.protocol import commands, message, op
 
+from .command_abc import Agent, CommandABC, CommandResult
+
 
 class ExportCommand(CommandABC):
     """Export the current session into a standalone HTML transcript."""

klaude_code/{command → tui/command}/export_online_cmd.py

@@ -9,10 +9,11 @@ from pathlib import Path
 from rich.console import Console
 from rich.text import Text
 
-from klaude_code.command.command_abc import Agent, CommandABC, CommandResult
 from klaude_code.protocol import commands, events, message, model
 from klaude_code.session.export import build_export_html
 
+from .command_abc import Agent, CommandABC, CommandResult
+
 
 class ExportOnlineCommand(CommandABC):
     """Export and deploy the current session to surge.sh as a static webpage."""
@@ -42,7 +43,7 @@ class ExportOnlineCommand(CommandABC):
                 session_id=agent.session.id,
                 item=message.DeveloperMessage(
                     parts=message.text_parts_from_str("surge.sh CLI not found. Install with: npm install -g surge"),
-                    command_output=model.CommandOutput(command_name=self.name, is_error=True),
+                    ui_extra=model.build_command_output_extra(self.name, is_error=True),
                 ),
             )
             return CommandResult(events=[event])
@@ -59,7 +60,7 @@ class ExportOnlineCommand(CommandABC):
                     session_id=agent.session.id,
                     item=message.DeveloperMessage(
                         parts=message.text_parts_from_str(f"Not logged in to surge.sh. Please run: {login_cmd}"),
-                        command_output=model.CommandOutput(command_name=self.name, is_error=True),
+                        ui_extra=model.build_command_output_extra(self.name, is_error=True),
                     ),
                 )
                 return CommandResult(events=[event])
@@ -73,7 +74,7 @@ class ExportOnlineCommand(CommandABC):
                 session_id=agent.session.id,
                 item=message.DeveloperMessage(
                     parts=message.text_parts_from_str(f"Session deployed to: {url}"),
-                    command_output=model.CommandOutput(command_name=self.name),
+                    ui_extra=model.build_command_output_extra(self.name),
                 ),
             )
             return CommandResult(events=[event])
@@ -84,7 +85,7 @@ class ExportOnlineCommand(CommandABC):
                 session_id=agent.session.id,
                 item=message.DeveloperMessage(
                     parts=message.text_parts_from_str(f"Failed to deploy session: {exc}\n{traceback.format_exc()}"),
-                    command_output=model.CommandOutput(command_name=self.name, is_error=True),
+                    ui_extra=model.build_command_output_extra(self.name, is_error=True),
                 ),
             )
             return CommandResult(events=[event])