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

klaude_code/auth/AGENTS.md

@@ -1,6 +1,6 @@
 # Adding a New OAuth Provider
 
-This document describes all the files and changes required to add a new OAuth-based authentication provider (like `antigravity`, `codex`, or `claude`).
+This document describes all the files and changes required to add a new OAuth-based authentication provider (like `codex` or `claude`).
 
 ## Overview
 
@@ -25,7 +25,7 @@ Add the new protocol to the `LLMClientProtocol` enum:
 ```python
 class LLMClientProtocol(Enum):
     # ... existing protocols ...
-    ANTIGRAVITY = "antigravity"  # Add new protocol
+    NEW_PROVIDER = "new_provider"  # Add new protocol
 ```
 
 ---
@@ -171,26 +171,8 @@ def is_api_key_missing(self) -> bool:
         return state is None
 ```
 
-#### `Config.resolve_model_location_prefer_available()`
-
-Add the protocol to the "no API key required" set:
-
-```python
-if (
-    provider.protocol
-    not in {
-        llm_param.LLMClientProtocol.CODEX_OAUTH,
-        llm_param.LLMClientProtocol.CLAUDE_OAUTH,
-        llm_param.LLMClientProtocol.<PROVIDER>,  # Add here
-        llm_param.LLMClientProtocol.BEDROCK,
-    }
-    and not api_key
-):
-```
-
-#### `Config.get_model_config()`
-
-Same change as above - add protocol to the set.
+Note: `resolve_model_location_prefer_available()` and `get_model_config()` both use
+`is_api_key_missing()` internally, so no additional changes are needed in those methods.
 
 ---
 
@@ -317,8 +299,6 @@ When adding a new OAuth provider, ensure you've completed:
 - [ ] Create `llm/<provider>/` module (input, client, __init__)
 - [ ] Register protocol in `llm/registry.py`
 - [ ] Update `config.py` - `is_api_key_missing()` method
-- [ ] Update `config.py` - `resolve_model_location_prefer_available()` method
-- [ ] Update `config.py` - `get_model_config()` method
 - [ ] Update `auth_cmd.py` - provider selection, login, logout
 - [ ] Update `list_model.py` - status display function and panel
 - [ ] Add provider/models to `builtin_config.yaml`

klaude_code/auth/__init__.py

@@ -1,17 +1,8 @@
 """Authentication module.
 
-Includes Codex and Antigravity OAuth helpers.
+Includes OAuth helpers for various providers.
 """
 
-from klaude_code.auth.antigravity import (
-    AntigravityAuthError,
-    AntigravityAuthState,
-    AntigravityNotLoggedInError,
-    AntigravityOAuth,
-    AntigravityOAuthError,
-    AntigravityTokenExpiredError,
-    AntigravityTokenManager,
-)
 from klaude_code.auth.codex import (
     CodexAuthError,
     CodexAuthState,
@@ -29,13 +20,6 @@ from klaude_code.auth.env import (
 )
 
 __all__ = [
-    "AntigravityAuthError",
-    "AntigravityAuthState",
-    "AntigravityNotLoggedInError",
-    "AntigravityOAuth",
-    "AntigravityOAuthError",
-    "AntigravityTokenExpiredError",
-    "AntigravityTokenManager",
     "CodexAuthError",
     "CodexAuthState",
     "CodexNotLoggedInError",

klaude_code/cli/auth_cmd.py

@@ -24,11 +24,6 @@ def _select_provider() -> str | None:
             value="codex",
             search_text="codex",
         ),
-        SelectItem(
-            title=[("", "Google Antigravity "), ("ansibrightblack", "[OAuth]\n")],
-            value="antigravity",
-            search_text="antigravity",
-        ),
     ]
     # Add API key options
     for key_info in SUPPORTED_API_KEYS:
@@ -76,7 +71,7 @@ def _build_provider_help() -> str:
     from klaude_code.config.builtin_config import SUPPORTED_API_KEYS
 
     # Use first word of name for brevity (e.g., "google" instead of "google gemini")
-    names = ["codex", "claude", "antigravity"] + [k.name.split()[0].lower() for k in SUPPORTED_API_KEYS]
+    names = ["codex", "claude"] + [k.name.split()[0].lower() for k in SUPPORTED_API_KEYS]
     return f"Provider name ({', '.join(names)})"
 
 
@@ -154,39 +149,6 @@ def login_command(
             except Exception as e:
                 log((f"Login failed: {e}", "red"))
                 raise typer.Exit(1) from None
-        case "antigravity":
-            from klaude_code.auth.antigravity.oauth import AntigravityOAuth
-            from klaude_code.auth.antigravity.token_manager import AntigravityTokenManager
-
-            token_manager = AntigravityTokenManager()
-
-            if token_manager.is_logged_in():
-                state = token_manager.get_state()
-                if state and not state.is_expired():
-                    log(("You are already logged in to Antigravity.", "green"))
-                    if state.email:
-                        log(f"  Email: {state.email}")
-                    log(f"  Project ID: {state.project_id}")
-                    expires_dt = datetime.datetime.fromtimestamp(state.expires_at, tz=datetime.UTC)
-                    log(f"  Expires: {expires_dt.strftime('%Y-%m-%d %H:%M:%S UTC')}")
-                    if not typer.confirm("Do you want to re-login?"):
-                        return
-
-            log("Starting Antigravity OAuth login flow...")
-            log("A browser window will open for authentication.")
-
-            try:
-                oauth = AntigravityOAuth(token_manager)
-                state = oauth.login()
-                log(("Login successful!", "green"))
-                if state.email:
-                    log(f"  Email: {state.email}")
-                log(f"  Project ID: {state.project_id}")
-                expires_dt = datetime.datetime.fromtimestamp(state.expires_at, tz=datetime.UTC)
-                log(f"  Expires: {expires_dt.strftime('%Y-%m-%d %H:%M:%S UTC')}")
-            except Exception as e:
-                log((f"Login failed: {e}", "red"))
-                raise typer.Exit(1) from None
         case _:
             from klaude_code.config.builtin_config import SUPPORTED_API_KEYS
 
@@ -212,7 +174,7 @@ def login_command(
 
 
 def logout_command(
-    provider: str = typer.Argument("codex", help="Provider to logout (codex|claude|antigravity)"),
+    provider: str = typer.Argument("codex", help="Provider to logout (codex|claude)"),
 ) -> None:
     """Logout from a provider."""
     match provider.lower():
@@ -240,20 +202,8 @@ def logout_command(
             if typer.confirm("Are you sure you want to logout from Claude?"):
                 token_manager.delete()
                 log(("Logged out from Claude.", "green"))
-        case "antigravity":
-            from klaude_code.auth.antigravity.token_manager import AntigravityTokenManager
-
-            token_manager = AntigravityTokenManager()
-
-            if not token_manager.is_logged_in():
-                log("You are not logged in to Antigravity.")
-                return
-
-            if typer.confirm("Are you sure you want to logout from Antigravity?"):
-                token_manager.delete()
-                log(("Logged out from Antigravity.", "green"))
         case _:
-            log((f"Error: Unknown provider '{provider}'. Supported: codex, claude, antigravity", "red"))
+            log((f"Error: Unknown provider '{provider}'. Supported: codex, claude", "red"))
             raise typer.Exit(1)
 
 

klaude_code/cli/list_model.py

@@ -121,53 +121,6 @@ def _get_claude_status_rows() -> list[tuple[Text, Text]]:
     return rows
 
 
-def _get_antigravity_status_rows() -> list[tuple[Text, Text]]:
-    """Get Antigravity OAuth login status as (label, value) tuples for table display."""
-    from klaude_code.auth.antigravity.token_manager import AntigravityTokenManager
-
-    rows: list[tuple[Text, Text]] = []
-    token_manager = AntigravityTokenManager()
-    state = token_manager.get_state()
-
-    if state is None:
-        rows.append(
-            (
-                Text("Status", style=ThemeKey.CONFIG_PARAM_LABEL),
-                Text.assemble(
-                    ("Not logged in", ThemeKey.CONFIG_STATUS_ERROR),
-                    (" (run 'klaude login antigravity' to authenticate)", "dim"),
-                ),
-            )
-        )
-    elif state.is_expired():
-        rows.append(
-            (
-                Text("Status", style=ThemeKey.CONFIG_PARAM_LABEL),
-                Text.assemble(
-                    ("Token expired", ThemeKey.CONFIG_STATUS_ERROR),
-                    (" (will refresh automatically on use; run 'klaude login antigravity' if refresh fails)", "dim"),
-                ),
-            )
-        )
-    else:
-        expires_dt = datetime.datetime.fromtimestamp(state.expires_at, tz=datetime.UTC)
-        email_info = f", email: {state.email}" if state.email else ""
-        rows.append(
-            (
-                Text("Status", style=ThemeKey.CONFIG_PARAM_LABEL),
-                Text.assemble(
-                    ("Logged in", ThemeKey.CONFIG_STATUS_OK),
-                    (
-                        f" (project: {state.project_id}{email_info}, expires: {expires_dt.strftime('%Y-%m-%d %H:%M UTC')})",
-                        "dim",
-                    ),
-                ),
-            )
-        )
-
-    return rows
-
-
 def mask_api_key(api_key: str | None) -> str:
     """Mask API key to show only first 6 and last 6 characters with *** in between"""
     if not api_key:
@@ -286,9 +239,6 @@ def _build_provider_info_panel(provider: ProviderConfig, available: bool, *, dis
     if provider.protocol == LLMClientProtocol.CLAUDE_OAUTH:
         for label, value in _get_claude_status_rows():
             info_table.add_row(label, value)
-    if provider.protocol == LLMClientProtocol.ANTIGRAVITY:
-        for label, value in _get_antigravity_status_rows():
-            info_table.add_row(label, value)
 
     return Quote(
         Group(title, info_table),

klaude_code/config/assets/builtin_config.yaml

@@ -341,32 +341,4 @@ provider_list:
     cost: {input: 1.75, output: 14, cache_read: 0.17}
 
 
-- provider_name: antigravity
-  protocol: antigravity
-  model_list:
-  - model_name: opus
-    model_id: claude-opus-4-5-thinking
-    context_limit: 200000
-    max_tokens: 64000
-
-  - model_name: sonnet
-    model_id: claude-sonnet-4-5
-    context_limit: 200000
-    max_tokens: 64000
-
-  - model_name: gemini-pro-high
-    model_id: gemini-3-pro-high
-    context_limit: 1048576
-    max_tokens: 65535
-    thinking:
-      reasoning_effort: high
-
-  - model_name: gemini-flash
-    model_id: gemini-3-flash
-    context_limit: 1048576
-    max_tokens: 65535
-    thinking:
-      reasoning_effort: medium
-
-
 compact_model: gemini-flash

klaude_code/config/config.py

@@ -101,15 +101,6 @@ class ProviderConfig(llm_param.LLMConfigProviderParameter):
             # Consider available if logged in. Token refresh happens on-demand.
             return state is None
 
-        if self.protocol == LLMClientProtocol.ANTIGRAVITY:
-            # Antigravity uses OAuth authentication, not API key
-            from klaude_code.auth.antigravity.token_manager import AntigravityTokenManager
-
-            token_manager = AntigravityTokenManager()
-            state = token_manager.get_state()
-            # Consider available if logged in. Token refresh happens on-demand.
-            return state is None
-
         if self.protocol == LLMClientProtocol.BEDROCK:
             # Bedrock uses AWS credentials, not API key. Region is always required.
             _, resolved_profile = parse_env_var_syntax(self.aws_profile)
@@ -275,8 +266,7 @@ class Config(BaseModel):
     def resolve_model_location_prefer_available(self, model_selector: str) -> tuple[str, str] | None:
         """Resolve a selector to (model_name, provider_name), preferring usable providers.
 
-        This uses the same availability logic as :meth:`get_model_config` (API-key
-        presence for non-OAuth protocols).
+        This uses the same availability logic as :meth:`get_model_config`.
         """
 
         requested_model, requested_provider = self._split_model_selector(model_selector)
@@ -285,20 +275,7 @@ class Config(BaseModel):
             if requested_provider is not None and provider.provider_name.casefold() != requested_provider.casefold():
                 continue
 
-            if provider.disabled:
-                continue
-
-            api_key = provider.get_resolved_api_key()
-            if (
-                provider.protocol
-                not in {
-                    llm_param.LLMClientProtocol.CODEX_OAUTH,
-                    llm_param.LLMClientProtocol.CLAUDE_OAUTH,
-                    llm_param.LLMClientProtocol.ANTIGRAVITY,
-                    llm_param.LLMClientProtocol.BEDROCK,
-                }
-                and not api_key
-            ):
+            if provider.disabled or provider.is_api_key_missing():
                 continue
 
             for model in provider.model_list:
@@ -322,24 +299,10 @@ class Config(BaseModel):
                     raise ValueError(f"Provider '{provider.provider_name}' is disabled for: {model_name}")
                 continue
 
-            # Resolve ${ENV_VAR} syntax for api_key
-            api_key = provider.get_resolved_api_key()
-
-            # Some protocols do not use API keys for authentication.
-            if (
-                provider.protocol
-                not in {
-                    llm_param.LLMClientProtocol.CODEX_OAUTH,
-                    llm_param.LLMClientProtocol.CLAUDE_OAUTH,
-                    llm_param.LLMClientProtocol.ANTIGRAVITY,
-                    llm_param.LLMClientProtocol.BEDROCK,
-                }
-                and not api_key
-            ):
-                # When provider is explicitly requested, fail fast with a clearer error.
+            if provider.is_api_key_missing():
                 if requested_provider is not None:
                     raise ValueError(
-                        f"Provider '{provider.provider_name}' is not available (missing API key) for: {model_name}"
+                        f"Provider '{provider.provider_name}' is not available (missing credentials) for: {model_name}"
                     )
                 continue
 
@@ -355,7 +318,7 @@ class Config(BaseModel):
                     break
 
                 provider_dump = provider.model_dump(exclude={"model_list", "disabled"})
-                provider_dump["api_key"] = api_key
+                provider_dump["api_key"] = provider.get_resolved_api_key()
                 return llm_param.LLMConfigParameter(
                     **provider_dump,
                     **model.model_dump(exclude={"model_name"}),

klaude_code/const.py

@@ -141,7 +141,9 @@ MIN_HIDDEN_LINES_FOR_INDICATOR = 5  # Minimum hidden lines before showing trunca
 SUB_AGENT_RESULT_MAX_LINES = 10  # Maximum lines for sub-agent result display
 TRUNCATE_HEAD_MAX_LINES = 2  # Maximum lines for sub-agent error display
 BASH_OUTPUT_PANEL_THRESHOLD = 10  # Bash output line threshold for CodePanel display
-BASH_MULTILINE_STRING_TRUNCATE_MAX_LINES = 4  # Max lines shown for heredoc / multiline string tokens in bash tool calls
+BASH_MULTILINE_STRING_TRUNCATE_MAX_LINES = (
+    20  # Max lines shown for heredoc / multiline string tokens in bash tool calls
+)
 URL_TRUNCATE_MAX_LENGTH = 400  # Maximum length for URL truncation in display
 QUERY_DISPLAY_TRUNCATE_LENGTH = 80  # Maximum length for search query display
 NOTIFY_COMPACT_LIMIT = 160  # Maximum length for notification body text
@@ -169,7 +171,7 @@ STATUS_HINT_TEXT = " (esc to interrupt)"  # Status hint text shown after spinner
 # Spinner status texts
 STATUS_WAITING_TEXT = "Loading …"
 STATUS_THINKING_TEXT = "Thinking …"
-STATUS_COMPOSING_TEXT = "Composing"
+STATUS_COMPOSING_TEXT = "Typing"
 STATUS_COMPACTING_TEXT = "Compacting"
 STATUS_RUNNING_TEXT = "Running …"
 
@@ -177,6 +179,7 @@ STATUS_RUNNING_TEXT = "Running …"
 STATUS_DEFAULT_TEXT = STATUS_WAITING_TEXT
 SIGINT_DOUBLE_PRESS_EXIT_TEXT = "Press ctrl+c again to exit"  # Toast shown on first Ctrl+C during task waits
 SPINNER_BREATH_PERIOD_SECONDS: float = 2.0  # Spinner breathing animation period (seconds)
+STATUS_SHIMMER_ENABLED = True  # Enable shimmer effect on status text
 STATUS_SHIMMER_PADDING = 10  # Horizontal padding for shimmer band position
 STATUS_SHIMMER_BAND_HALF_WIDTH = 5.0  # Half-width of shimmer band in characters
 STATUS_SHIMMER_ALPHA_SCALE = 0.7  # Scale factor for shimmer intensity

klaude_code/core/agent_profile.py

@@ -52,10 +52,6 @@ COMMAND_DESCRIPTIONS: dict[str, str] = {
 }
 
 
-# Prompt for antigravity protocol - used exactly as-is without any additions.
-ANTIGRAVITY_PROMPT_PATH = "prompts/prompt-antigravity.md"
-
-
 STRUCTURED_OUTPUT_PROMPT_FOR_SUB_AGENT = """\
 
 # Structured Output
@@ -130,10 +126,6 @@ def load_system_prompt(
 ) -> str:
     """Get system prompt content for the given model and sub-agent type."""
 
-    # For antigravity protocol, use exact prompt without any additions.
-    if protocol == llm_param.LLMClientProtocol.ANTIGRAVITY:
-        return _load_prompt_by_path(ANTIGRAVITY_PROMPT_PATH)
-
     if sub_agent_type is not None:
         profile = get_sub_agent_profile(sub_agent_type)
         base_prompt = _load_prompt_by_path(profile.prompt_file)
@@ -169,9 +161,9 @@ def load_agent_tools(
 
     # Main agent tools
     if "gpt-5" in model_name:
-        tool_names: list[str] = [tools.BASH, tools.READ, tools.APPLY_PATCH, tools.UPDATE_PLAN]
+        tool_names: list[str] = [tools.BASH, tools.READ, tools.APPLY_PATCH, tools.UPDATE_PLAN, tools.BACKTRACK]
     else:
-        tool_names = [tools.BASH, tools.READ, tools.EDIT, tools.WRITE, tools.TODO_WRITE]
+        tool_names = [tools.BASH, tools.READ, tools.EDIT, tools.WRITE, tools.TODO_WRITE, tools.BACKTRACK]
 
     tool_names.append(tools.TASK)
     if config is not None:

klaude_code/core/backtrack/__init__.py

@@ -0,0 +1,3 @@
+from klaude_code.core.backtrack.manager import BacktrackManager, BacktrackRequest
+
+__all__ = ["BacktrackManager", "BacktrackRequest"]

klaude_code/core/backtrack/manager.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class BacktrackRequest:
+    checkpoint_id: int
+    note: str
+    rationale: str
+
+
+class BacktrackManager:
+    """Manage backtrack requests and checkpoint metadata for a task run."""
+
+    def __init__(self) -> None:
+        self._pending: BacktrackRequest | None = None
+        self._n_checkpoints: int = 0
+        self._checkpoint_user_messages: dict[int, str] = {}
+
+    def set_n_checkpoints(self, n: int) -> None:
+        self._n_checkpoints = n
+
+    @property
+    def n_checkpoints(self) -> int:
+        return self._n_checkpoints
+
+    def sync_checkpoints(self, checkpoints: dict[int, str]) -> None:
+        self._checkpoint_user_messages = dict(checkpoints)
+
+    def register_checkpoint(self, checkpoint_id: int, user_message: str) -> None:
+        self._checkpoint_user_messages[checkpoint_id] = user_message
+
+    def get_checkpoint_user_message(self, checkpoint_id: int) -> str | None:
+        return self._checkpoint_user_messages.get(checkpoint_id)
+
+    def send_backtrack(self, checkpoint_id: int, note: str, rationale: str) -> str:
+        if self._pending is not None:
+            raise ValueError("Only one backtrack can be pending at a time")
+        if checkpoint_id < 0 or checkpoint_id >= self._n_checkpoints:
+            raise ValueError(f"Invalid checkpoint {checkpoint_id}, available: 0-{self._n_checkpoints - 1}")
+        if checkpoint_id not in self._checkpoint_user_messages:
+            raise ValueError("Checkpoint is no longer available")
+        self._pending = BacktrackRequest(checkpoint_id=checkpoint_id, note=note, rationale=rationale)
+        return "Backtrack scheduled"
+
+    def fetch_pending(self) -> BacktrackRequest | None:
+        pending = self._pending
+        self._pending = None
+        return pending

klaude_code/core/memory.py

@@ -9,7 +9,7 @@ from pathlib import Path
 
 from pydantic import BaseModel
 
-MEMORY_FILE_NAMES = ["CLAUDE.md", "AGENTS.md", "AGENT.md"]
+MEMORY_FILE_NAMES = ["AGENTS.md", "CLAUDE.md", "AGENT.md"]
 
 
 class Memory(BaseModel):
@@ -36,12 +36,20 @@ def get_memory_paths(*, work_dir: Path) -> list[tuple[Path, str]]:
 
 
 def get_existing_memory_files(*, work_dir: Path) -> dict[str, list[str]]:
-    """Return existing memory file paths grouped by location (user/project)."""
+    """Return existing memory file paths grouped by location (user/project).
+
+    Only one memory file per directory is loaded, with priority: AGENTS.md > CLAUDE.md > AGENT.md
+    """
     result: dict[str, list[str]] = {"user": [], "project": []}
     work_dir = work_dir.resolve()
+    seen_dirs: set[Path] = set()
 
     for memory_path, _instruction in get_memory_paths(work_dir=work_dir):
+        parent = memory_path.parent.resolve()
+        if parent in seen_dirs:
+            continue
         if memory_path.exists() and memory_path.is_file():
+            seen_dirs.add(parent)
             path_str = str(memory_path)
             resolved = memory_path.resolve()
             try:
@@ -87,6 +95,8 @@ def discover_memory_files_near_paths(
 ) -> list[Memory]:
     """Discover and load CLAUDE.md/AGENTS.md from directories containing accessed files.
 
+    Only one memory file per directory is loaded, with priority: AGENTS.md > CLAUDE.md > AGENT.md
+
     Args:
         paths: List of file paths that have been accessed.
         is_memory_loaded: Callback to check if a memory file is already loaded.
@@ -97,7 +107,7 @@ def discover_memory_files_near_paths(
     """
     memories: list[Memory] = []
     work_dir = work_dir.resolve()
-    seen_memory_files: set[str] = set()
+    seen_dirs: set[Path] = set()
 
     for p_str in paths:
         p = Path(p_str)
@@ -117,24 +127,30 @@ def discover_memory_files_near_paths(
         current_dir = work_dir
         for part in rel_parts:
             current_dir = current_dir / part
+            if current_dir in seen_dirs:
+                continue
+            # Check if any memory file in this directory was already loaded
+            dir_already_loaded = any(is_memory_loaded(str(current_dir / fname)) for fname in MEMORY_FILE_NAMES)
+            if dir_already_loaded:
+                seen_dirs.add(current_dir)
+                continue
+            # Load first existing memory file in priority order
             for fname in MEMORY_FILE_NAMES:
                 mem_path = current_dir / fname
-                mem_path_str = str(mem_path)
-                if mem_path_str in seen_memory_files or is_memory_loaded(mem_path_str):
-                    continue
                 if mem_path.exists() and mem_path.is_file():
                     try:
                         text = mem_path.read_text(encoding="utf-8", errors="replace")
                     except (PermissionError, UnicodeDecodeError, OSError):
                         continue
-                    mark_memory_loaded(mem_path_str)
-                    seen_memory_files.add(mem_path_str)
+                    mark_memory_loaded(str(mem_path))
+                    seen_dirs.add(current_dir)
                     memories.append(
                         Memory(
-                            path=mem_path_str,
+                            path=str(mem_path),
                             instruction="project instructions, discovered near last accessed path",
                             content=text,
                         )
                     )
+                    break
 
     return memories

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