klaude-code 2.2.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

klaude_code/llm/responses/input.py

@@ -2,7 +2,7 @@
 # pyright: reportArgumentType=false
 # pyright: reportAssignmentType=false
 
-from typing import Any
+from typing import Any, cast
 
 from openai.types import responses
 
@@ -23,15 +23,25 @@ def _build_user_content_parts(
     parts: list[responses.ResponseInputContentParam] = []
     for part in user.parts:
         if isinstance(part, message.TextPart):
-            parts.append({"type": "input_text", "text": part.text})
+            parts.append(cast(responses.ResponseInputContentParam, {"type": "input_text", "text": part.text}))
         elif isinstance(part, message.ImageURLPart):
-            parts.append({"type": "input_image", "detail": "auto", "image_url": part.url})
+            parts.append(
+                cast(
+                    responses.ResponseInputContentParam,
+                    {"type": "input_image", "detail": "auto", "image_url": part.url},
+                )
+            )
     if attachment.text:
-        parts.append({"type": "input_text", "text": attachment.text})
+        parts.append(cast(responses.ResponseInputContentParam, {"type": "input_text", "text": attachment.text}))
     for image in attachment.images:
-        parts.append({"type": "input_image", "detail": "auto", "image_url": image.url})
+        parts.append(
+            cast(
+                responses.ResponseInputContentParam,
+                {"type": "input_image", "detail": "auto", "image_url": image.url},
+            )
+        )
     if not parts:
-        parts.append({"type": "input_text", "text": ""})
+        parts.append(cast(responses.ResponseInputContentParam, {"type": "input_text", "text": ""}))
     return parts
 
 
@@ -45,17 +55,22 @@ def _build_tool_result_item(
         attachment.text,
     )
     if text_output:
-        content_parts.append({"type": "input_text", "text": text_output})
+        content_parts.append(cast(responses.ResponseInputContentParam, {"type": "input_text", "text": text_output}))
     images = [part for part in tool.parts if isinstance(part, message.ImageURLPart)] + attachment.images
     for image in images:
-        content_parts.append({"type": "input_image", "detail": "auto", "image_url": image.url})
+        content_parts.append(
+            cast(
+                responses.ResponseInputContentParam,
+                {"type": "input_image", "detail": "auto", "image_url": image.url},
+            )
+        )
 
     item: dict[str, Any] = {
         "type": "function_call_output",
         "call_id": tool.call_id,
         "output": content_parts,
     }
-    return item
+    return cast(responses.ResponseInputItemParam, item)
 
 
 def convert_history_to_input(
@@ -73,25 +88,30 @@ def convert_history_to_input(
                 system_text = "\n".join(part.text for part in msg.parts)
                 if system_text:
                     items.append(
-                        {
-                            "type": "message",
-                            "role": "system",
-                            "content": [
-                                {
-                                    "type": "input_text",
-                                    "text": system_text,
-                                }
-                            ],
-                        }
+                        cast(
+                            responses.ResponseInputItemParam,
+                            {
+                                "type": "message",
+                                "role": "system",
+                                "content": [
+                                    cast(
+                                        responses.ResponseInputContentParam,
+                                        {"type": "input_text", "text": system_text},
+                                    )
+                                ],
+                            },
+                        )
                     )
             case message.UserMessage():
                 items.append(
-                    {
-                        "type": "message",
-                        "role": "user",
-                        "id": msg.id,
-                        "content": _build_user_content_parts(msg, attachment),
-                    }
+                    cast(
+                        responses.ResponseInputItemParam,
+                        {
+                            "type": "message",
+                            "role": "user",
+                            "content": _build_user_content_parts(msg, attachment),
+                        },
+                    )
                 )
             case message.ToolResultMessage():
                 items.append(_build_tool_result_item(msg, attachment))
@@ -103,17 +123,19 @@ def convert_history_to_input(
                 native_thinking_ids = {id(part) for part in native_thinking_parts}
                 degraded_thinking_texts.extend(degraded_for_message)
 
-                def flush_text(*, _message_id: str = msg.id) -> None:
+                def flush_text() -> None:
                     nonlocal assistant_text_parts
                     if not assistant_text_parts:
                         return
                     items.append(
-                        {
-                            "type": "message",
-                            "role": "assistant",
-                            "id": _message_id,
-                            "content": assistant_text_parts,
-                        }
+                        cast(
+                            responses.ResponseInputItemParam,
+                            {
+                                "type": "message",
+                                "role": "assistant",
+                                "content": assistant_text_parts,
+                            },
+                        )
                     )
                     assistant_text_parts = []
 
@@ -140,17 +162,25 @@ def convert_history_to_input(
 
                     emit_reasoning()
                     if isinstance(part, message.TextPart):
-                        assistant_text_parts.append({"type": "output_text", "text": part.text})
+                        assistant_text_parts.append(
+                            cast(
+                                responses.ResponseInputContentParam,
+                                {"type": "input_text", "text": part.text},
+                            )
+                        )
                     elif isinstance(part, message.ToolCallPart):
                         flush_text()
                         items.append(
-                            {
-                                "type": "function_call",
-                                "name": part.tool_name,
-                                "arguments": part.arguments_json,
-                                "call_id": part.call_id,
-                                "id": part.id,
-                            }
+                            cast(
+                                responses.ResponseInputItemParam,
+                                {
+                                    "type": "function_call",
+                                    "name": part.tool_name,
+                                    "arguments": part.arguments_json,
+                                    "call_id": part.call_id,
+                                    "id": part.id,
+                                },
+                            )
                         )
 
                 emit_reasoning()
@@ -159,16 +189,22 @@ def convert_history_to_input(
                 continue
 
     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>",
-                }
-            ],
-        }
+        degraded_item = cast(
+            responses.ResponseInputItemParam,
+            {
+                "type": "message",
+                "role": "assistant",
+                "content": [
+                    cast(
+                        responses.ResponseInputContentParam,
+                        {
+                            "type": "input_text",
+                            "text": "<thinking>\n" + "\n".join(degraded_thinking_texts) + "\n</thinking>",
+                        },
+                    )
+                ],
+            },
+        )
         items.insert(0, degraded_item)
 
     return items
@@ -184,7 +220,7 @@ def convert_reasoning_inputs(text_content: str | None, signature: str | None) ->
     ]
     if signature:
         result["encrypted_content"] = signature
-    return result
+    return cast(responses.ResponseInputItemParam, result)
 
 
 def convert_tool_schema(
@@ -193,11 +229,14 @@ def convert_tool_schema(
     if tools is None:
         return []
     return [
-        {
-            "type": "function",
-            "name": tool.name,
-            "description": tool.description,
-            "parameters": tool.parameters,
-        }
+        cast(
+            responses.ToolParam,
+            {
+                "type": "function",
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": tool.parameters,
+            },
+        )
         for tool in tools
     ]

klaude_code/protocol/commands.py

@@ -15,8 +15,8 @@ class CommandInfo:
 class CommandName(str, Enum):
     INIT = "init"
     DEBUG = "debug"
-    HELP = "help"
     MODEL = "model"
+    SUB_AGENT_MODEL = "sub-agent-model"
     COMPACT = "compact"
     REFRESH_TERMINAL = "refresh-terminal"
     CLEAR = "clear"
@@ -24,7 +24,6 @@ class CommandName(str, Enum):
     EXPORT = "export"
     EXPORT_ONLINE = "export-online"
     STATUS = "status"
-    RELEASE_NOTES = "release-notes"
     THINKING = "thinking"
     FORK_SESSION = "fork-session"
     RESUME = "resume"

klaude_code/protocol/events/__init__.py

@@ -1,7 +1,12 @@
 from __future__ import annotations
 
 from klaude_code.protocol.events.base import Event, ResponseEvent
-from klaude_code.protocol.events.chat import DeveloperMessageEvent, TodoChangeEvent, UserMessageEvent
+from klaude_code.protocol.events.chat import (
+    CommandOutputEvent,
+    DeveloperMessageEvent,
+    TodoChangeEvent,
+    UserMessageEvent,
+)
 from klaude_code.protocol.events.lifecycle import TaskFinishEvent, TaskStartEvent, TurnEndEvent, TurnStartEvent
 from klaude_code.protocol.events.metadata import TaskMetadataEvent, UsageEvent
 from klaude_code.protocol.events.streaming import (
@@ -30,6 +35,7 @@ __all__ = [
     "AssistantTextDeltaEvent",
     "AssistantTextEndEvent",
     "AssistantTextStartEvent",
+    "CommandOutputEvent",
     "DeveloperMessageEvent",
     "EndEvent",
     "ErrorEvent",

klaude_code/protocol/events/chat.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from klaude_code.protocol import message, model
+from klaude_code.protocol.commands import CommandName
 
 from .base import Event
 
@@ -18,3 +19,12 @@ class DeveloperMessageEvent(Event):
 
 class TodoChangeEvent(Event):
     todos: list[model.TodoItem]
+
+
+class CommandOutputEvent(Event):
+    """Event for command output display. Not persisted to session history."""
+
+    command_name: CommandName | str
+    content: str = ""
+    ui_extra: model.ToolResultUIExtra | None = None
+    is_error: bool = False

klaude_code/protocol/events/system.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from pydantic import Field
+
 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
@@ -14,6 +16,8 @@ class WelcomeEvent(Event):
     work_dir: str
     llm_config: llm_param.LLMConfigParameter
     show_klaude_code_info: bool = True
+    show_sub_agent_models: bool = True
+    sub_agent_models: dict[str, llm_param.LLMConfigParameter] = Field(default_factory=dict)
 
 
 class ErrorEvent(Event):

klaude_code/protocol/llm_param.py

@@ -119,7 +119,7 @@ class LLMConfigProviderParameter(BaseModel):
 
 
 class LLMConfigModelParameter(BaseModel):
-    model: str | None = None
+    model_id: str | None = None
     temperature: float | None = None
     max_tokens: int | None = None
     context_limit: int | None = None

klaude_code/protocol/model.py

@@ -5,7 +5,6 @@ from typing import Annotated, Any, Literal
 from pydantic import BaseModel, Field, computed_field
 
 from klaude_code.const import DEFAULT_MAX_TOKENS
-from klaude_code.protocol.commands import CommandName
 from klaude_code.protocol.tools import SubAgentType
 
 RoleType = Literal["system", "developer", "user", "assistant", "tool"]
@@ -272,12 +271,6 @@ ToolResultUIExtra = Annotated[
 ]
 
 
-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)
@@ -319,11 +312,6 @@ class SkillActivatedUIItem(BaseModel):
     name: str
 
 
-class CommandOutputUIItem(BaseModel):
-    type: Literal["command_output"] = "command_output"
-    output: CommandOutput
-
-
 type DeveloperUIItem = (
     MemoryLoadedUIItem
     | ExternalFileChangesUIItem
@@ -331,7 +319,6 @@ type DeveloperUIItem = (
     | AtFileOpsUIItem
     | UserImagesUIItem
     | SkillActivatedUIItem
-    | CommandOutputUIItem
 )
 
 
@@ -343,19 +330,6 @@ 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

@@ -25,6 +25,7 @@ class OperationType(Enum):
 
     RUN_AGENT = "run_agent"
     CHANGE_MODEL = "change_model"
+    CHANGE_SUB_AGENT_MODEL = "change_sub_agent_model"
     CHANGE_THINKING = "change_thinking"
     CLEAR_SESSION = "clear_session"
     RESUME_SESSION = "resume_session"
@@ -51,11 +52,6 @@ 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)
@@ -97,6 +93,22 @@ class ChangeThinkingOperation(Operation):
         await handler.handle_change_thinking(self)
 
 
+class ChangeSubAgentModelOperation(Operation):
+    """Operation for changing the model used by a specific sub-agent."""
+
+    type: OperationType = OperationType.CHANGE_SUB_AGENT_MODEL
+    session_id: str
+    sub_agent_type: str
+    # When None, clear explicit override and fall back to the sub-agent's default
+    # behavior (usually inherit from main agent; some sub-agents auto-resolve a
+    # suitable model, e.g. ImageGen).
+    model_name: str | None
+    save_as_default: bool = False
+
+    async def execute(self, handler: OperationHandler) -> None:
+        await handler.handle_change_sub_agent_model(self)
+
+
 class ClearSessionOperation(Operation):
     """Operation for clearing the active session and starting a new one."""
 

klaude_code/protocol/op_handler.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING, Protocol
 if TYPE_CHECKING:
     from klaude_code.protocol.op import (
         ChangeModelOperation,
+        ChangeSubAgentModelOperation,
         ChangeThinkingOperation,
         ClearSessionOperation,
         ExportSessionOperation,
@@ -36,6 +37,10 @@ class OperationHandler(Protocol):
         """Handle a change thinking operation."""
         ...
 
+    async def handle_change_sub_agent_model(self, operation: ChangeSubAgentModelOperation) -> None:
+        """Handle a change sub-agent model operation."""
+        ...
+
     async def handle_clear_session(self, operation: ClearSessionOperation) -> None:
         """Handle a clear session operation."""
         ...

klaude_code/protocol/sub_agent/AGENTS.md

@@ -0,0 +1,28 @@
+# Sub-Agent Protocol
+
+Sub-agents are specialized agents invoked by the main agent as tools. This module defines profiles and registration.
+
+## Key Constraint
+
+The `protocol` layer cannot import from `config` or `core` (enforced by import-linter). Availability checks are delegated to upper layers via string constants.
+
+## Core Files
+
+- `__init__.py` - `SubAgentProfile` dataclass and registration. Defines `AVAILABILITY_*` constants.
+- `image_gen.py`, `task.py`, `explore.py`, `web.py` - Individual sub-agent definitions.
+
+## Availability Requirement Flow
+
+Some sub-agents require specific model capabilities (e.g., ImageGen needs an image model). The flow:
+
+1. `SubAgentProfile.availability_requirement` stores a constant (e.g., `AVAILABILITY_IMAGE_MODEL`)
+2. `config/sub_agent_model_helper.py` checks if the requirement is met based on `config/config.py`
+3. `config/sub_agent_model_helper.py` resolves the default model when unset (e.g., first available image model)
+4. Core builders/UI call into the helper to avoid dealing with requirement constants directly
+
+## 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)

klaude_code/protocol/sub_agent/__init__.py

@@ -9,9 +9,11 @@ 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]
 
+# Availability requirement constants
+AVAILABILITY_IMAGE_MODEL = "image_model"
+
 
 @dataclass
 class SubAgentResult:
@@ -58,17 +60,13 @@ class SubAgentProfile:
     # 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)
+    # 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
 
 
 _PROFILES: dict[str, SubAgentProfile] = {}
@@ -87,11 +85,11 @@ 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, model_name: str | None = None) -> list[SubAgentProfile]:
+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_for_model(model_name)]
+    return [p for p in profiles if p.enabled_by_default]
 
 
 def get_sub_agent_profile_by_tool(tool_name: str) -> SubAgentProfile | None:
@@ -102,11 +100,9 @@ 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]:
+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, model_name=model_name)
-        if profile.show_in_main_agent
+        profile.name for profile in iter_sub_agent_profiles(enabled_only=enabled_only) if profile.show_in_main_agent
     ]
 
 

klaude_code/protocol/sub_agent/image_gen.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Any, cast
 
-from klaude_code.protocol.sub_agent import SubAgentProfile, register_sub_agent
+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.
@@ -115,5 +115,6 @@ register_sub_agent(
         tool_set=(),
         prompt_builder=_build_image_gen_prompt,
         active_form="Generating Image",
+        availability_requirement=AVAILABILITY_IMAGE_MODEL,
     )
 )

klaude_code/session/codec.py

@@ -1,17 +1,13 @@
 from __future__ import annotations
 
 import json
-from typing import Any, TypeGuard, cast, get_args
+from typing import Any, cast, get_args
 
 from pydantic import BaseModel
 
 from klaude_code.protocol import message
 
 
-def _is_basemodel_subclass(tp: object) -> TypeGuard[type[BaseModel]]:
-    return isinstance(tp, type) and issubclass(tp, BaseModel)
-
-
 def _flatten_union(tp: object) -> list[object]:
     args = list(get_args(tp))
     if not args:
@@ -25,7 +21,7 @@ def _flatten_union(tp: object) -> list[object]:
 def _build_type_registry() -> dict[str, type[BaseModel]]:
     registry: dict[str, type[BaseModel]] = {}
     for tp in _flatten_union(message.HistoryEvent):
-        if not _is_basemodel_subclass(tp):
+        if not isinstance(tp, type) or not issubclass(tp, BaseModel):
             continue
         registry[tp.__name__] = tp
     return registry

klaude_code/session/session.py

@@ -237,7 +237,7 @@ class Session(BaseModel):
         Args:
             new_id: Optional ID for the forked session.
             until_index: If provided, only copy conversation history up to (but not including) this index.
-                         If None, copy all history.
+                         If -1, copy all history.
         """
 
         forked = Session.create(id=new_id, work_dir=self.work_dir)
@@ -250,7 +250,9 @@ class Session(BaseModel):
         forked.todos = [todo.model_copy(deep=True) for todo in self.todos]
 
         history_to_copy = (
-            self.conversation_history[:until_index] if until_index is not None else self.conversation_history
+            self.conversation_history[:until_index]
+            if (until_index is not None and until_index >= 0)
+            else self.conversation_history
         )
         items = [it.model_copy(deep=True) for it in history_to_copy]
         if items:
@@ -370,8 +372,16 @@ class Session(BaseModel):
 
         has_structured_output = report_back_result is not None
         task_result = report_back_result if has_structured_output else last_assistant_content
+
+        if self.sub_agent_state is not None:
+            trimmed = (task_result or "").rstrip()
+            lines = trimmed.splitlines()
+            if not (lines and lines[-1].startswith("agentId:")):
+                footer = f"agentId: {self.id} (for resuming to continue this agent's work if needed)"
+                task_result = f"{trimmed}\n\n{footer}" if trimmed.strip() else footer
+
         yield events.TaskFinishEvent(
-            session_id=self.id, task_result=task_result, has_structured_output=has_structured_output
+            session_id=self.id, task_result=task_result or "", has_structured_output=has_structured_output
         )
 
     def _iter_sub_agent_history(

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

@@ -13,6 +13,8 @@ Turn a user prompt into a **single, actionable plan** delivered in the final ass
 
 ## Minimal workflow
 
+Throughout the entire workflow, operate in read-only mode. Do not write or update files.
+
 1. **Scan context quickly**
    - Read `README.md` and any obvious docs (`docs/`, `CONTRIBUTING.md`, `ARCHITECTURE.md`).
    - Skim relevant files (the ones most likely touched).
@@ -33,11 +35,7 @@ Turn a user prompt into a **single, actionable plan** delivered in the final ass
    - 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**
+4. **Do not preface the plan with meta explanations; output only the plan as per template**
 
 ## Plan template (follow exactly)