klaude-code 2.10.2__py3-none-any.whl → 2.10.4__py3-none-any.whl

klaude_code/core/task.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 
 from klaude_code.const import INITIAL_RETRY_DELAY_S, MAX_FAILED_TURN_RETRIES, MAX_RETRY_DELAY_S
 from klaude_code.core.agent_profile import AgentProfile, Reminder
+from klaude_code.core.backtrack import BacktrackManager
 from klaude_code.core.compaction import (
     CompactionReason,
     is_context_overflow,
@@ -178,6 +179,7 @@ class TaskExecutor:
         self._current_turn: TurnExecutor | None = None
         self._started_at: float = 0.0
         self._metadata_accumulator: MetadataAccumulator | None = None
+        self._backtrack_manager: BacktrackManager | None = None
 
     def get_partial_metadata(self) -> model.TaskMetadata | None:
         """Get the currently accumulated metadata without finalizing.
@@ -221,6 +223,11 @@ class TaskExecutor:
         session_ctx = ctx.session_ctx
         self._started_at = time.perf_counter()
 
+        if ctx.sub_agent_state is None:
+            self._backtrack_manager = BacktrackManager()
+            self._backtrack_manager.set_n_checkpoints(ctx.session.n_checkpoints)
+            self._backtrack_manager.sync_checkpoints(ctx.session.get_checkpoint_user_messages())
+
         yield events.TaskStartEvent(
             session_id=session_ctx.session_id,
             sub_agent_state=ctx.sub_agent_state,
@@ -262,6 +269,9 @@ class TaskExecutor:
                     log_debug("[Compact] result", str(result.to_entry()), debug_type=DebugType.RESPONSE)
 
                     session_ctx.append_history([result.to_entry()])
+                    if self._backtrack_manager is not None:
+                        self._backtrack_manager.set_n_checkpoints(ctx.session.n_checkpoints)
+                        self._backtrack_manager.sync_checkpoints(ctx.session.get_checkpoint_user_messages())
                     yield events.CompactionEndEvent(
                         session_id=session_ctx.session_id,
                         reason=CompactionReason.THRESHOLD.value,
@@ -298,6 +308,12 @@ class TaskExecutor:
                         will_retry=False,
                     )
 
+            if self._backtrack_manager is not None:
+                checkpoint_id = ctx.session.create_checkpoint()
+                self._backtrack_manager.set_n_checkpoints(ctx.session.n_checkpoints)
+                user_msg = ctx.session.get_user_message_before_checkpoint(checkpoint_id) or ""
+                self._backtrack_manager.register_checkpoint(checkpoint_id, user_msg)
+
             turn_context = TurnExecutionContext(
                 session_ctx=session_ctx,
                 llm_client=profile.llm_client,
@@ -305,6 +321,7 @@ class TaskExecutor:
                 tools=profile.tools,
                 tool_registry=ctx.tool_registry,
                 sub_agent_state=ctx.sub_agent_state,
+                backtrack_manager=self._backtrack_manager,
             )
 
             turn: TurnExecutor | None = None
@@ -354,6 +371,9 @@ class TaskExecutor:
                                 "[Compact:Overflow] result", str(result.to_entry()), debug_type=DebugType.RESPONSE
                             )
                             session_ctx.append_history([result.to_entry()])
+                            if self._backtrack_manager is not None:
+                                self._backtrack_manager.set_n_checkpoints(ctx.session.n_checkpoints)
+                                self._backtrack_manager.sync_checkpoints(ctx.session.get_checkpoint_user_messages())
                             yield events.CompactionEndEvent(
                                 session_id=session_ctx.session_id,
                                 reason=CompactionReason.OVERFLOW.value,
@@ -414,14 +434,40 @@ class TaskExecutor:
                 yield events.ErrorEvent(error_message=final_error, can_retry=False, session_id=session_ctx.session_id)
                 return
 
-            if turn is None or turn.task_finished:
-                # Empty result should retry instead of finishing
-                if turn is not None and not turn.task_result.strip():
-                    if ctx.sub_agent_state is not None:
-                        error_msg = "Sub-agent returned empty result, retrying…"
+            if self._backtrack_manager is not None:
+                pending = self._backtrack_manager.fetch_pending()
+                if pending is not None:
+                    try:
+                        entry = ctx.session.revert_to_checkpoint(pending.checkpoint_id, pending.note, pending.rationale)
+                    except ValueError as exc:
+                        yield events.ErrorEvent(
+                            error_message=str(exc),
+                            can_retry=False,
+                            session_id=session_ctx.session_id,
+                        )
                     else:
-                        error_msg = "Agent returned empty result, retrying…"
-                    yield events.ErrorEvent(error_message=error_msg, can_retry=True, session_id=session_ctx.session_id)
+                        messages_discarded = entry.reverted_from_index - len(ctx.session.conversation_history)
+                        session_ctx.append_history([entry])
+                        self._backtrack_manager.set_n_checkpoints(ctx.session.n_checkpoints)
+                        self._backtrack_manager.sync_checkpoints(ctx.session.get_checkpoint_user_messages())
+                        yield events.BacktrackEvent(
+                            session_id=session_ctx.session_id,
+                            checkpoint_id=pending.checkpoint_id,
+                            note=pending.note,
+                            rationale=pending.rationale,
+                            original_user_message=entry.original_user_message,
+                            messages_discarded=messages_discarded,
+                        )
+                        continue
+
+            if turn is None or turn.task_finished:
+                # Empty result should retry only for sub-agents
+                if turn is not None and not turn.task_result.strip() and ctx.sub_agent_state is not None:
+                    yield events.ErrorEvent(
+                        error_message="Sub-agent returned empty result, retrying…",
+                        can_retry=True,
+                        session_id=session_ctx.session_id,
+                    )
                     continue
                 break
 

klaude_code/core/tool/__init__.py

@@ -1,3 +1,4 @@
+from .backtrack.backtrack_tool import BacktrackTool
 from .context import FileTracker, RunSubtask, SubAgentResumeClaims, TodoContext, ToolContext, build_todo_context
 from .file.apply_patch import DiffError, process_patch
 from .file.apply_patch_tool import ApplyPatchTool
@@ -19,6 +20,7 @@ from .web.web_search_tool import WebSearchTool
 
 __all__ = [
     "ApplyPatchTool",
+    "BacktrackTool",
     "BashTool",
     "DiffError",
     "EditTool",

klaude_code/core/tool/backtrack/__init__.py

@@ -0,0 +1,3 @@
+from klaude_code.core.tool.backtrack.backtrack_tool import BacktrackTool
+
+__all__ = ["BacktrackTool"]

klaude_code/core/tool/backtrack/backtrack_tool.md

@@ -0,0 +1,17 @@
+Revert conversation history to a previous checkpoint, discarding everything after it.
+
+Use this tool when:
+- You spent many tokens on exploration that turned out unproductive
+- You read large files but only need to keep key information
+- A deep debugging session can be summarized before continuing
+- The current approach is stuck and you want to try a different path
+
+The note you provide will be shown to your future self at the checkpoint, so include:
+- Key findings from your exploration
+- What approaches did not work and why
+- Important context needed to continue
+
+IMPORTANT:
+- File system changes are NOT reverted - only conversation history is affected
+- Checkpoints are created automatically at the start of each turn
+- Available checkpoints appear as <system>Checkpoint N</system> in the conversation

klaude_code/core/tool/backtrack/backtrack_tool.py

@@ -0,0 +1,65 @@
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from klaude_code.core.tool.context import ToolContext
+from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_registry import register
+from klaude_code.protocol import llm_param, message, tools
+
+
+class BacktrackArguments(BaseModel):
+    checkpoint_id: int = Field(description="The checkpoint ID to revert to")
+    note: str = Field(description="A note to your future self with key findings/context to preserve")
+    rationale: str = Field(description="Why you are performing this backtrack")
+
+
+@register(tools.BACKTRACK)
+class BacktrackTool(ToolABC):
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        return llm_param.ToolSchema(
+            name=tools.BACKTRACK,
+            type="function",
+            description=load_desc(Path(__file__).parent / "backtrack_tool.md"),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "checkpoint_id": {
+                        "type": "integer",
+                        "description": "The checkpoint ID to revert to",
+                    },
+                    "note": {
+                        "type": "string",
+                        "description": "A note to your future self with key findings/context",
+                    },
+                    "rationale": {
+                        "type": "string",
+                        "description": "Why you are performing this backtrack",
+                    },
+                },
+                "required": ["checkpoint_id", "note", "rationale"],
+                "additionalProperties": False,
+            },
+        )
+
+    @classmethod
+    async def call(cls, arguments: str, context: ToolContext) -> message.ToolResultMessage:
+        try:
+            args = BacktrackArguments.model_validate_json(arguments)
+        except ValueError as exc:
+            return message.ToolResultMessage(status="error", output_text=f"Invalid arguments: {exc}")
+
+        backtrack_manager = context.backtrack_manager
+        if backtrack_manager is None:
+            return message.ToolResultMessage(
+                status="error",
+                output_text="Backtrack is not available in this context",
+            )
+
+        try:
+            result = backtrack_manager.send_backtrack(args.checkpoint_id, args.note, args.rationale)
+        except ValueError as exc:
+            return message.ToolResultMessage(status="error", output_text=str(exc))
+
+        return message.ToolResultMessage(status="success", output_text=result)

klaude_code/core/tool/context.py

@@ -4,6 +4,7 @@ import asyncio
 from collections.abc import Awaitable, Callable, MutableMapping
 from dataclasses import dataclass, replace
 
+from klaude_code.core.backtrack import BacktrackManager
 from klaude_code.protocol import model
 from klaude_code.protocol.sub_agent import SubAgentResult
 from klaude_code.session.session import Session
@@ -85,9 +86,13 @@ class ToolContext:
     sub_agent_resume_claims: SubAgentResumeClaims | None = None
     record_sub_agent_session_id: Callable[[str], None] | None = None
     register_sub_agent_metadata_getter: Callable[[GetMetadataFn], None] | None = None
+    backtrack_manager: BacktrackManager | None = None
 
     def with_record_sub_agent_session_id(self, callback: Callable[[str], None] | None) -> ToolContext:
         return replace(self, record_sub_agent_session_id=callback)
 
     def with_register_sub_agent_metadata_getter(self, callback: Callable[[GetMetadataFn], None] | None) -> ToolContext:
         return replace(self, register_sub_agent_metadata_getter=callback)
+
+    def with_backtrack_manager(self, manager: BacktrackManager | None) -> ToolContext:
+        return replace(self, backtrack_manager=manager)

klaude_code/core/turn.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
 from klaude_code.const import RETRY_PRESERVE_PARTIAL_MESSAGE, SUPPORTED_IMAGE_SIZES
+from klaude_code.core.backtrack import BacktrackManager
 from klaude_code.core.tool import ToolABC
 from klaude_code.core.tool.context import SubAgentResumeClaims, ToolContext
 
@@ -49,6 +50,7 @@ class TurnExecutionContext:
     tools: list[llm_param.ToolSchema]
     tool_registry: dict[str, type[ToolABC]]
     sub_agent_state: model.SubAgentState | None = None
+    backtrack_manager: BacktrackManager | None = None
 
 
 @dataclass
@@ -404,6 +406,7 @@ class TurnExecutor:
             session_id=session_ctx.session_id,
             run_subtask=session_ctx.run_subtask,
             sub_agent_resume_claims=SubAgentResumeClaims(),
+            backtrack_manager=ctx.backtrack_manager,
         )
 
         executor = ToolExecutor(

klaude_code/llm/anthropic/input.py

@@ -107,11 +107,20 @@ def _tool_blocks_to_message(blocks: list[BetaToolResultBlockParam]) -> BetaMessa
     }
 
 
+def _model_supports_unsigned_thinking(model_name: str | None) -> bool:
+    """Check if the model supports thinking blocks without signature (e.g., kimi, deepseek)."""
+    if not model_name:
+        return False
+    model_lower = model_name.lower()
+    return "kimi" in model_lower or "deepseek" in model_lower
+
+
 def _assistant_message_to_message(msg: message.AssistantMessage, model_name: str | None) -> BetaMessageParam:
     content: list[BetaContentBlockParam] = []
     current_thinking_content: str | None = None
     native_thinking_parts, _ = split_thinking_parts(msg, model_name)
     native_thinking_ids = {id(part) for part in native_thinking_parts}
+    supports_unsigned = _model_supports_unsigned_thinking(model_name)
 
     def _degraded_thinking_block(text: str) -> BetaTextBlockParam | None:
         stripped = text.strip()
@@ -125,11 +134,18 @@ def _assistant_message_to_message(msg: message.AssistantMessage, model_name: str
             },
         )
 
-    def _flush_thinking_as_text_block() -> None:
+    def _flush_thinking() -> None:
         nonlocal current_thinking_content
         if current_thinking_content is None:
             return
-        if block := _degraded_thinking_block(current_thinking_content):
+        if supports_unsigned:
+            content.append(
+                cast(
+                    BetaContentBlockParam,
+                    {"type": "thinking", "thinking": current_thinking_content},
+                )
+            )
+        elif block := _degraded_thinking_block(current_thinking_content):
             content.append(block)
         current_thinking_content = None
 
@@ -156,9 +172,17 @@ def _assistant_message_to_message(msg: message.AssistantMessage, model_name: str
                     )
                 )
                 current_thinking_content = None
+            elif supports_unsigned:
+                content.append(
+                    cast(
+                        BetaContentBlockParam,
+                        {"type": "thinking", "thinking": current_thinking_content or ""},
+                    )
+                )
+                current_thinking_content = None
             continue
 
-        _flush_thinking_as_text_block()
+        _flush_thinking()
         if isinstance(part, message.TextPart):
             content.append(cast(BetaTextBlockParam, {"type": "text", "text": part.text}))
         elif isinstance(part, message.ToolCallPart):
@@ -182,7 +206,7 @@ def _assistant_message_to_message(msg: message.AssistantMessage, model_name: str
                 )
             )
 
-    _flush_thinking_as_text_block()
+    _flush_thinking()
 
     return {"role": "assistant", "content": content}
 

klaude_code/llm/input_common.py

@@ -108,17 +108,86 @@ def build_tool_message(
     msg: message.ToolResultMessage,
     attachment: DeveloperAttachment,
 ) -> dict[str, object]:
+    """Build a tool message. Note: image_url in tool message is not supported by
+    OpenAI Chat Completions API. Use build_tool_message_for_chat_completions instead.
+    """
     merged_text = merge_reminder_text(
         msg.output_text or EMPTY_TOOL_OUTPUT_MESSAGE,
         attachment.text,
     )
+    content: list[dict[str, object]] = [{"type": "text", "text": merged_text}]
+    for part in msg.parts:
+        if isinstance(part, message.ImageFilePart):
+            content.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(part)}})
+        elif isinstance(part, message.ImageURLPart):
+            content.append({"type": "image_url", "image_url": {"url": part.url}})
+    for image in attachment.images:
+        if isinstance(image, message.ImageFilePart):
+            content.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(image)}})
+        else:
+            content.append({"type": "image_url", "image_url": {"url": image.url}})
     return {
         "role": "tool",
-        "content": [{"type": "text", "text": merged_text}],
+        "content": content,
         "tool_call_id": msg.call_id,
     }
 
 
+def build_tool_message_for_chat_completions(
+    msg: message.ToolResultMessage,
+    attachment: DeveloperAttachment,
+) -> tuple[dict[str, object], dict[str, object] | None]:
+    """Build tool message for OpenAI Chat Completions API.
+
+    OpenAI Chat Completions API does not support image_url in tool messages.
+    Images are extracted and returned as a separate user message to be appended after the tool message.
+
+    Returns:
+        A tuple of (tool_message, optional_user_message_with_images).
+        The user_message is None if there are no images.
+    """
+    merged_text = merge_reminder_text(
+        msg.output_text or EMPTY_TOOL_OUTPUT_MESSAGE,
+        attachment.text,
+    )
+
+    # Collect all images
+    image_urls: list[dict[str, object]] = []
+    for part in msg.parts:
+        if isinstance(part, message.ImageFilePart):
+            image_urls.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(part)}})
+        elif isinstance(part, message.ImageURLPart):
+            image_urls.append({"type": "image_url", "image_url": {"url": part.url}})
+    for image in attachment.images:
+        if isinstance(image, message.ImageFilePart):
+            image_urls.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(image)}})
+        else:
+            image_urls.append({"type": "image_url", "image_url": {"url": image.url}})
+
+    # If only images (no text), use placeholder
+    has_text = bool(merged_text.strip())
+    tool_content = merged_text if has_text else "(see attached image)"
+
+    tool_message: dict[str, object] = {
+        "role": "tool",
+        "content": tool_content,
+        "tool_call_id": msg.call_id,
+    }
+
+    # Build user message with images if any
+    user_message: dict[str, object] | None = None
+    if image_urls:
+        user_message = {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "Attached image(s) from tool result:"},
+                *image_urls,
+            ],
+        }
+
+    return tool_message, user_message
+
+
 def build_assistant_common_fields(
     msg: message.AssistantMessage,
     *,

klaude_code/llm/openai_compatible/input.py

@@ -12,7 +12,7 @@ from klaude_code.llm.input_common import (
     attach_developer_messages,
     build_assistant_common_fields,
     build_chat_content_parts,
-    build_tool_message,
+    build_tool_message_for_chat_completions,
     collect_text_content,
 )
 from klaude_code.protocol import llm_param, message
@@ -50,7 +50,10 @@ def convert_history_to_input(
                 parts = build_chat_content_parts(msg, attachment)
                 messages.append(cast(chat.ChatCompletionMessageParam, {"role": "user", "content": parts}))
             case message.ToolResultMessage():
-                messages.append(cast(chat.ChatCompletionMessageParam, build_tool_message(msg, attachment)))
+                tool_msg, user_msg = build_tool_message_for_chat_completions(msg, attachment)
+                messages.append(cast(chat.ChatCompletionMessageParam, tool_msg))
+                if user_msg is not None:
+                    messages.append(cast(chat.ChatCompletionMessageParam, user_msg))
             case message.AssistantMessage():
                 messages.append(_assistant_message_to_openai(msg))
             case _:

klaude_code/llm/openrouter/input.py

@@ -15,7 +15,7 @@ from klaude_code.llm.input_common import (
     attach_developer_messages,
     build_assistant_common_fields,
     build_chat_content_parts,
-    build_tool_message,
+    build_tool_message_for_chat_completions,
     collect_text_content,
     split_thinking_parts,
 )
@@ -153,7 +153,10 @@ def convert_history_to_input(
                 parts = build_chat_content_parts(msg, attachment)
                 messages.append(cast(chat.ChatCompletionMessageParam, {"role": "user", "content": parts}))
             case message.ToolResultMessage():
-                messages.append(cast(chat.ChatCompletionMessageParam, build_tool_message(msg, attachment)))
+                tool_msg, user_msg = build_tool_message_for_chat_completions(msg, attachment)
+                messages.append(cast(chat.ChatCompletionMessageParam, tool_msg))
+                if user_msg is not None:
+                    messages.append(cast(chat.ChatCompletionMessageParam, user_msg))
             case message.AssistantMessage():
                 messages.append(_assistant_message_to_openrouter(msg, model_name))
             case _:

klaude_code/llm/registry.py

@@ -21,7 +21,6 @@ _PROTOCOL_MODULES: dict[llm_param.LLMClientProtocol, str] = {
     llm_param.LLMClientProtocol.OPENROUTER: "klaude_code.llm.openrouter",
     llm_param.LLMClientProtocol.RESPONSES: "klaude_code.llm.openai_responses",
     llm_param.LLMClientProtocol.GOOGLE: "klaude_code.llm.google",
-    llm_param.LLMClientProtocol.ANTIGRAVITY: "klaude_code.llm.antigravity",
 }
 
 

klaude_code/protocol/events.py

@@ -14,6 +14,7 @@ __all__ = [
     "AssistantTextDeltaEvent",
     "AssistantTextEndEvent",
     "AssistantTextStartEvent",
+    "BacktrackEvent",
     "BashCommandEndEvent",
     "BashCommandOutputDeltaEvent",
     "BashCommandStartEvent",
@@ -116,6 +117,14 @@ class CompactionEndEvent(Event):
     kept_items_brief: list[message.KeptItemBrief] = Field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
 
 
+class BacktrackEvent(Event):
+    checkpoint_id: int
+    note: str
+    rationale: str
+    original_user_message: str
+    messages_discarded: int | None = None
+
+
 class TaskFinishEvent(Event):
     task_result: str
     has_structured_output: bool = False
@@ -220,6 +229,7 @@ type ReplayEventUnion = (
     | ErrorEvent
     | CompactionStartEvent
     | CompactionEndEvent
+    | BacktrackEvent
 )
 
 

klaude_code/protocol/llm_param.py

@@ -16,7 +16,6 @@ class LLMClientProtocol(Enum):
     BEDROCK = "bedrock"
     CODEX_OAUTH = "codex_oauth"
     GOOGLE = "google"
-    ANTIGRAVITY = "antigravity"
 
 
 class ToolSchema(BaseModel):

klaude_code/protocol/message.py

@@ -85,6 +85,15 @@ class CompactionEntry(BaseModel):
     created_at: datetime = Field(default_factory=datetime.now)
 
 
+class BacktrackEntry(BaseModel):
+    checkpoint_id: int
+    note: str
+    rationale: str
+    reverted_from_index: int
+    original_user_message: str
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
 # Part types
 
 
@@ -196,7 +205,7 @@ class ToolResultMessage(MessageBase):
 
 Message = SystemMessage | DeveloperMessage | UserMessage | AssistantMessage | ToolResultMessage
 
-HistoryEvent = Message | StreamErrorItem | TaskMetadataItem | CompactionEntry
+HistoryEvent = Message | StreamErrorItem | TaskMetadataItem | CompactionEntry | BacktrackEntry
 
 StreamItem = AssistantTextDelta | AssistantImageDelta | ThinkingTextDelta | ToolCallStartDelta
 

klaude_code/protocol/tools.py

@@ -12,6 +12,7 @@ WEB_SEARCH = "WebSearch"
 REPORT_BACK = "report_back"
 TASK = "Task"
 IMAGE_GEN = "ImageGen"
+BACKTRACK = "Backtrack"
 
 # SubAgentType is just a string alias now; agent types are defined via SubAgentProfile
 SubAgentType = str