klaude-code 2.8.1__py3-none-any.whl → 2.9.1__py3-none-any.whl

klaude_code/protocol/model.py

@@ -217,12 +217,28 @@ class MermaidLinkUIExtra(BaseModel):
     line_count: int
 
 
+class ImageUIExtra(BaseModel):
+    type: Literal["image"] = "image"
+    file_path: str
+
+
 class MarkdownDocUIExtra(BaseModel):
     type: Literal["markdown_doc"] = "markdown_doc"
     file_path: str
     content: str
 
 
+class ReadPreviewLine(BaseModel):
+    line_no: int
+    content: str
+
+
+class ReadPreviewUIExtra(BaseModel):
+    type: Literal["read_preview"] = "read_preview"
+    lines: list[ReadPreviewLine]
+    remaining_lines: int  # lines not shown in preview
+
+
 class SessionStatusUIExtra(BaseModel):
     type: Literal["session_status"] = "session_status"
     usage: "Usage"
@@ -231,7 +247,14 @@ class SessionStatusUIExtra(BaseModel):
 
 
 MultiUIExtraItem = (
-    DiffUIExtra | TodoListUIExtra | SessionIdUIExtra | MermaidLinkUIExtra | MarkdownDocUIExtra | SessionStatusUIExtra
+    DiffUIExtra
+    | TodoListUIExtra
+    | SessionIdUIExtra
+    | MermaidLinkUIExtra
+    | ImageUIExtra
+    | MarkdownDocUIExtra
+    | SessionStatusUIExtra
+    | ReadPreviewUIExtra
 )
 
 
@@ -251,9 +274,11 @@ ToolResultUIExtra = Annotated[
     | TodoListUIExtra
     | SessionIdUIExtra
     | MermaidLinkUIExtra
+    | ImageUIExtra
     | MarkdownDocUIExtra
     | SessionStatusUIExtra
-    | MultiUIExtra,
+    | MultiUIExtra
+    | ReadPreviewUIExtra,
     Field(discriminator="type"),
 ]
 
@@ -292,6 +317,7 @@ class AtFileOpsUIItem(BaseModel):
 class UserImagesUIItem(BaseModel):
     type: Literal["user_images"] = "user_images"
     count: int
+    paths: list[str] = []
 
 
 class SkillActivatedUIItem(BaseModel):
@@ -299,6 +325,11 @@ class SkillActivatedUIItem(BaseModel):
     name: str
 
 
+class AtFileImagesUIItem(BaseModel):
+    type: Literal["at_file_images"] = "at_file_images"
+    paths: list[str]
+
+
 type DeveloperUIItem = (
     MemoryLoadedUIItem
     | ExternalFileChangesUIItem
@@ -306,6 +337,7 @@ type DeveloperUIItem = (
     | AtFileOpsUIItem
     | UserImagesUIItem
     | SkillActivatedUIItem
+    | AtFileImagesUIItem
 )
 
 

klaude_code/protocol/op.py

@@ -27,6 +27,7 @@ class OperationType(Enum):
     CONTINUE_AGENT = "continue_agent"
     COMPACT_SESSION = "compact_session"
     CHANGE_MODEL = "change_model"
+    CHANGE_COMPACT_MODEL = "change_compact_model"
     CHANGE_SUB_AGENT_MODEL = "change_sub_agent_model"
     CHANGE_THINKING = "change_thinking"
     CLEAR_SESSION = "clear_session"
@@ -108,6 +109,18 @@ class ChangeModelOperation(Operation):
         await handler.handle_change_model(self)
 
 
+class ChangeCompactModelOperation(Operation):
+    """Operation for changing the compact model (used for session compaction)."""
+
+    type: OperationType = OperationType.CHANGE_COMPACT_MODEL
+    session_id: str
+    model_name: str | None
+    save_as_default: bool = False
+
+    async def execute(self, handler: OperationHandler) -> None:
+        await handler.handle_change_compact_model(self)
+
+
 class ChangeThinkingOperation(Operation):
     """Operation for changing the thinking/reasoning configuration."""
 

klaude_code/protocol/op_handler.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Protocol
 
 if TYPE_CHECKING:
     from klaude_code.protocol.op import (
+        ChangeCompactModelOperation,
         ChangeModelOperation,
         ChangeSubAgentModelOperation,
         ChangeThinkingOperation,
@@ -43,6 +44,10 @@ class OperationHandler(Protocol):
         """Handle a change model operation."""
         ...
 
+    async def handle_change_compact_model(self, operation: ChangeCompactModelOperation) -> None:
+        """Handle a change compact model operation."""
+        ...
+
     async def handle_change_thinking(self, operation: ChangeThinkingOperation) -> None:
         """Handle a change thinking operation."""
         ...

klaude_code/protocol/sub_agent/AGENTS.md

@@ -1,6 +1,6 @@
 # Sub-Agent Protocol
 
-Sub-agents are specialized agents invoked by the main agent as tools. This module defines profiles and registration.
+Sub-agents are specialized agent types invoked by tools like Task and ImageGen. This module defines profiles and registration.
 
 ## Key Constraint
 
@@ -9,7 +9,7 @@ The `protocol` layer cannot import from `config` or `core` (enforced by import-l
 ## Core Files
 
 - `__init__.py` - `SubAgentProfile` dataclass and registration. Defines `AVAILABILITY_*` constants.
-- `image_gen.py`, `task.py`, `explore.py`, `web.py` - Individual sub-agent definitions.
+- `image_gen.py`, `task.py`, `explore.py`, `web.py` - Individual sub-agent type definitions.
 
 ## Availability Requirement Flow
 
@@ -23,6 +23,6 @@ Some sub-agents require specific model capabilities (e.g., ImageGen needs an ima
 ## Model Selection
 
 For sub-agents with `availability_requirement`, priority is:
-1. Explicit config in `sub_agent_models`
-2. Auto-resolve via requirement
-3. If neither found, sub-agent is unavailable (no fallback to main agent model)
+1. Explicit config in `sub_agent_models` for the specific type
+2. Fallback to the Task model config (if present)
+3. Otherwise inherit the main agent model

klaude_code/protocol/sub_agent/__init__.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
 from klaude_code.protocol import tools
@@ -38,32 +38,22 @@ class SubAgentProfile:
     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", "Explore", "WebAgent"
+    # Identity - single name used for type, config_key, and prompt_key
+    name: str  # e.g., "Task", "Explore", "Web", "ImageGen"
 
-    # 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
+    # Sub-agent run configuration
     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
 
+    # Entry-point metadata for Task tool (RunSubAgent)
+    invoker_type: str | None = None  # Tool-level type mapping (e.g., "general-purpose", "explore", "web")
+    invoker_summary: str = ""  # Short description shown under Task tool supported types
+    standalone_tool: bool = False  # True for sub-agents invoked by dedicated tools (e.g., ImageGen)
+
     # 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
-
-    # Structured output support: specifies which parameter in the tool schema contains the output schema
-    output_schema_arg: str | None = None
-
     # Config-based availability requirement (e.g., "image_model" means requires an image model)
     # The actual check is performed in the core layer to avoid circular imports.
     availability_requirement: str | None = None
@@ -85,25 +75,14 @@ def get_sub_agent_profile(sub_agent_type: tools.SubAgentType) -> SubAgentProfile
         raise KeyError(f"Unknown sub agent type: {sub_agent_type}") from exc
 
 
-def iter_sub_agent_profiles(enabled_only: bool = False) -> list[SubAgentProfile]:
-    profiles = list(_PROFILES.values())
-    if not enabled_only:
-        return profiles
-    return [p for p in profiles if p.enabled_by_default]
-
-
-def get_sub_agent_profile_by_tool(tool_name: str) -> SubAgentProfile | None:
-    return _PROFILES.get(tool_name)
+def iter_sub_agent_profiles() -> list[SubAgentProfile]:
+    return list(_PROFILES.values())
 
 
 def is_sub_agent_tool(tool_name: str) -> bool:
-    return tool_name in _PROFILES
-
+    from klaude_code.protocol import tools
 
-def sub_agent_tool_names(enabled_only: bool = False) -> list[str]:
-    return [
-        profile.name for profile in iter_sub_agent_profiles(enabled_only=enabled_only) if profile.show_in_main_agent
-    ]
+    return tool_name in {tools.TASK, tools.IMAGE_GEN}
 
 
 # Import sub-agent modules to trigger registration

klaude_code/protocol/sub_agent/explore.py

@@ -3,46 +3,19 @@ from __future__ import annotations
 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.
-"""
-
-EXPLORE_PARAMETERS = {
-    "type": "object",
-    "properties": {
-        "resume": {
-            "type": "string",
-            "description": "Optional agent ID to resume from. If provided, the agent will continue from the previous execution transcript.",
-        },
-        "description": {
-            "type": "string",
-            "description": "Short (3-5 words) label for the exploration goal",
-        },
-        "prompt": {
-            "type": "string",
-            "description": "The task for the agent to perform",
-        },
-        "output_format": {
-            "type": "object",
-            "description": "Optional JSON Schema for sub-agent structured output",
-        },
-    },
-    "required": ["description", "prompt"],
-    "additionalProperties": False,
-}
-
+EXPLORE_SUMMARY = (
+    "Fast codebase exploration: find files by patterns, search for keywords, and summarize how things work.\n"
+    "Always spawn multiple search agents in parallel to maximise speed. "
+    "(Tools: Bash, Read)"
+)
 
 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),
+        invoker_type="explore",
+        invoker_summary=EXPLORE_SUMMARY,
         active_form="Exploring",
-        output_schema_arg="output_format",
     )
 )

klaude_code/protocol/sub_agent/image_gen.py

@@ -4,76 +4,6 @@ from typing import Any, cast
 
 from klaude_code.protocol.sub_agent import AVAILABILITY_IMAGE_MODEL, SubAgentProfile, register_sub_agent
 
-IMAGE_GEN_DESCRIPTION = """\
-Generate one or more images from a text prompt.
-
-This tool invokes an Image Gen model to generate images. The generated image paths are automatically \
-returned in the response.
-
-Inputs:
-- `prompt`: The main instruction describing the desired image.
-- `image_paths` (optional): Local image file paths to use as references for editing or style guidance.
-- `generation` (optional): Per-call image generation settings (aspect ratio / size).
-
-Notes:
-- Provide a short textual description of the generated image(s).
-- Do NOT include base64 image data in text output.
-- When providing multiple input images, describe each image's characteristics and purpose in the prompt, \
-not just "image 1, image 2" - the image model cannot distinguish image order. \
-For example: "Edit the first image (a photo of a cat sitting on a windowsill) to match the style of \
-the second image (Van Gogh's Starry Night painting with swirling blue brushstrokes)."
-
-Multi-turn image editing:
-- Use `resume` to continue editing a previously generated image. The agent preserves its full context \
-including the generated image, so you don't need to pass `image_paths` again.
-- Example workflow:
-  1. Call ImageGen with prompt="Generate a watercolor painting of a mountain lake" -> returns agent_id
-  2. Call ImageGen with resume=agent_id, prompt="Add a wooden cabin on the shore" -> edits the previous image
-  3. Call ImageGen with resume=agent_id, prompt="Change to sunset lighting" -> continues editing
-"""
-
-
-IMAGE_GEN_PARAMETERS: dict[str, Any] = {
-    "type": "object",
-    "properties": {
-        "resume": {
-            "type": "string",
-            "description": "Optional agent ID to resume from. If provided, the agent will continue from the previous execution transcript.",
-        },
-        "description": {
-            "type": "string",
-            "description": "A short (3-5 word) description of the request.",
-        },
-        "prompt": {
-            "type": "string",
-            "description": "Text prompt for image generation.",
-        },
-        "image_paths": {
-            "type": "array",
-            "items": {"type": "string"},
-            "description": "Optional local image file paths used as references.",
-        },
-        "generation": {
-            "type": "object",
-            "description": "Optional per-call image generation settings.",
-            "properties": {
-                "aspect_ratio": {
-                    "type": "string",
-                    "description": "Aspect ratio, e.g. '16:9', '1:1', '9:16'.",
-                },
-                "image_size": {
-                    "type": "string",
-                    "enum": ["1K", "2K", "4K"],
-                    "description": "Output size for Nano Banana Pro (must use uppercase K).",
-                },
-            },
-            "additionalProperties": False,
-        },
-    },
-    "required": ["prompt"],
-    "additionalProperties": False,
-}
-
 
 def _quote_at_pattern_path(path: str) -> str:
     if any(ch.isspace() for ch in path) or '"' in path:
@@ -82,7 +12,7 @@ def _quote_at_pattern_path(path: str) -> str:
     return f"@{path}"
 
 
-def _build_image_gen_prompt(args: dict[str, Any]) -> str:
+def build_image_gen_prompt(args: dict[str, Any]) -> str:
     prompt = str(args.get("prompt") or "").strip()
     image_paths = args.get("image_paths")
 
@@ -98,12 +28,11 @@ def _build_image_gen_prompt(args: dict[str, Any]) -> str:
 register_sub_agent(
     SubAgentProfile(
         name="ImageGen",
-        description=IMAGE_GEN_DESCRIPTION,
-        parameters=IMAGE_GEN_PARAMETERS,
         prompt_file="prompts/prompt-sub-agent-image-gen.md",
         tool_set=(),
-        prompt_builder=_build_image_gen_prompt,
+        prompt_builder=build_image_gen_prompt,
         active_form="Generating Image",
         availability_requirement=AVAILABILITY_IMAGE_MODEL,
+        standalone_tool=True,
     )
 )

klaude_code/protocol/sub_agent/task.py

@@ -3,59 +3,15 @@ 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.
-"""
-
-TASK_PARAMETERS = {
-    "type": "object",
-    "properties": {
-        "resume": {
-            "type": "string",
-            "description": "Optional agent ID to resume from. If provided, the agent will continue from the previous execution transcript.",
-        },
-        "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,
-}
+TASK_SUMMARY = "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. (Tools: All Tools)"
 
 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),
+        invoker_type="general-purpose",
+        invoker_summary=TASK_SUMMARY,
         active_form="Tasking",
-        output_schema_arg="output_format",
     )
 )

klaude_code/protocol/sub_agent/web.py

@@ -3,63 +3,19 @@ from __future__ import annotations
 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
-- Fetch and parse web pages
-- Follow links across multiple pages
-- 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
-- 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.
-- Provide the url if you already know the target page
-
-What you receive:
-- The agent returns a text response summarizing its findings
-- The response is the agent's analysis, not raw web content
-- Web content is saved to local files (paths included in Sources) - read them directly if you need full content
-"""
-
-WEB_AGENT_PARAMETERS = {
-    "type": "object",
-    "properties": {
-        "resume": {
-            "type": "string",
-            "description": "Optional agent ID to resume from. If provided, the agent will continue from the previous execution transcript.",
-        },
-        "description": {
-            "type": "string",
-            "description": "A short (3-5 word) description of the task",
-        },
-        "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,
-}
-
+WEB_SUMMARY = (
+    "Web research: search, fetch, and analyze pages for up-to-date info; summarize findings with sources. "
+    "Include dates in queries when recency matters. "
+    "(Tools: WebSearch, WebFetch, Bash, Read, Write)"
+)
 
 register_sub_agent(
     SubAgentProfile(
-        name="WebAgent",
-        description=WEB_AGENT_DESCRIPTION,
-        parameters=WEB_AGENT_PARAMETERS,
+        name="Web",
         prompt_file="prompts/prompt-sub-agent-web.md",
         tool_set=(tools.BASH, tools.READ, tools.WEB_FETCH, tools.WEB_SEARCH, tools.WRITE),
+        invoker_type="web",
+        invoker_summary=WEB_SUMMARY,
         active_form="Surfing",
-        output_schema_arg="output_format",
     )
 )

klaude_code/protocol/tools.py

@@ -10,6 +10,8 @@ MERMAID = "Mermaid"
 WEB_FETCH = "WebFetch"
 WEB_SEARCH = "WebSearch"
 REPORT_BACK = "report_back"
+TASK = "Task"
+IMAGE_GEN = "ImageGen"
 
 # SubAgentType is just a string alias now; agent types are defined via SubAgentProfile
 SubAgentType = str