klaude-code 1.2.6__py3-none-any.whl

klaude_code/core/reminders.py

@@ -0,0 +1,445 @@
+import json
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from pydantic import BaseModel
+
+from klaude_code import const
+from klaude_code.core.tool import BashTool, ReadTool, reset_tool_context, set_tool_context_from_session
+from klaude_code.protocol import model, tools
+from klaude_code.session import Session
+
+type Reminder = Callable[[Session], Awaitable[model.DeveloperMessageItem | None]]
+
+
+def get_last_new_user_input(session: Session) -> str | None:
+    """Get last user input & developer message (CLAUDE.md) from conversation history. if there's a tool result after user input, return None"""
+    result: list[str] = []
+    for item in reversed(session.conversation_history):
+        if isinstance(item, model.ToolResultItem):
+            return None
+        if isinstance(item, model.UserMessageItem):
+            result.append(item.content or "")
+            break
+        if isinstance(item, model.DeveloperMessageItem):
+            result.append(item.content or "")
+    return "\n\n".join(result)
+
+
+async def at_file_reader_reminder(
+    session: Session,
+) -> model.DeveloperMessageItem | None:
+    """Parse @foo/bar to read"""
+    last_user_input = get_last_new_user_input(session)
+    if not last_user_input or "@" not in last_user_input.strip():
+        return None
+
+    at_patterns: list[str] = []
+
+    for item in last_user_input.strip().split():
+        if item.startswith("@") and len(item) > 1:
+            at_patterns.append(item.lower().strip("@"))
+
+    if len(at_patterns) == 0:
+        return None
+
+    at_files: dict[str, model.AtPatternParseResult] = {}  # path -> content
+    collected_images: list[model.ImageURLPart] = []
+
+    for pattern in at_patterns:
+        path = Path(pattern).resolve()
+        context_token = set_tool_context_from_session(session)
+        try:
+            if path.exists() and path.is_file():
+                args = ReadTool.ReadArguments(file_path=str(path))
+                tool_result = await ReadTool.call_with_args(args)
+                at_result = model.AtPatternParseResult(
+                    path=str(path),
+                    tool_name=tools.READ,
+                    result=tool_result.output or "",
+                    tool_args=args.model_dump_json(exclude_none=True),
+                    operation="Read",
+                    images=tool_result.images,
+                )
+                at_files[str(path)] = at_result
+                if tool_result.images:
+                    collected_images.extend(tool_result.images)
+            elif path.exists() and path.is_dir():
+                args = BashTool.BashArguments(command=f"ls {path}")
+                tool_result = await BashTool.call_with_args(args)
+                at_files[str(path)] = model.AtPatternParseResult(
+                    path=str(path) + "/",
+                    tool_name=tools.BASH,
+                    result=tool_result.output or "",
+                    tool_args=args.model_dump_json(exclude_none=True),
+                    operation="List",
+                )
+        finally:
+            reset_tool_context(context_token)
+
+    if len(at_files) == 0:
+        return None
+
+    at_files_str = "\n\n".join(
+        [
+            f"""Called the {result.tool_name} tool with the following input: {result.tool_args}
+Result of calling the {result.tool_name} tool:
+{result.result}
+"""
+            for result in at_files.values()
+        ]
+    )
+    return model.DeveloperMessageItem(
+        content=f"""<system-reminder>{at_files_str}\n</system-reminder>""",
+        at_files=list(at_files.values()),
+        images=collected_images or None,
+    )
+
+
+async def empty_todo_reminder(session: Session) -> model.DeveloperMessageItem | None:
+    """Remind agent to use TodoWrite tool when todos are empty/all completed.
+
+    Behavior:
+    - First time in empty state (counter == 0): trigger reminder and set cooldown (e.g., 3).
+    - While remaining in empty state with counter > 0: decrement each turn, no reminder.
+    - Do not decrement/reset while todos are non-empty (cooldown only counts during empty state).
+    """
+
+    empty_or_all_done = (not session.todos) or all(todo.status == "completed" for todo in session.todos)
+
+    # Only count down and possibly trigger when empty/all-done
+    if not empty_or_all_done:
+        return None
+
+    if session.need_todo_empty_cooldown_counter == 0:
+        session.need_todo_empty_cooldown_counter = 3
+        return model.DeveloperMessageItem(
+            content="""<system-reminder>This is a reminder that your todo list is currently empty. DO NOT mention this to the user explicitly because they are already aware. If you are working on tasks that would benefit from a todo list please use the TodoWrite tool to create one. If not, please feel free to ignore. Again do not mention this message to the user.</system-reminder>"""
+        )
+
+    if session.need_todo_empty_cooldown_counter > 0:
+        session.need_todo_empty_cooldown_counter -= 1
+    return None
+
+
+async def todo_not_used_recently_reminder(
+    session: Session,
+) -> model.DeveloperMessageItem | None:
+    """Remind agent to use TodoWrite tool if it hasn't been used recently (>=10 other tool calls), with cooldown.
+
+    Cooldown behavior:
+    - When condition becomes active (>=10 non-todo tool calls since last TodoWrite) and counter == 0: trigger reminder, set counter = 3.
+    - While condition remains active and counter > 0: decrement each turn, do not remind.
+    - When condition not active: do nothing to the counter (no decrement), and do not remind.
+    """
+
+    if not session.todos:
+        return None
+
+    # If all todos completed, skip reminder entirely
+    if all(todo.status == "completed" for todo in session.todos):
+        return None
+
+    # Count non-todo tool calls since the last TodoWrite
+    other_tool_call_count_befor_last_todo = 0
+    for item in reversed(session.conversation_history):
+        if isinstance(item, model.ToolCallItem):
+            if item.name in (tools.TODO_WRITE, tools.UPDATE_PLAN):
+                break
+            other_tool_call_count_befor_last_todo += 1
+            if other_tool_call_count_befor_last_todo >= const.TODO_REMINDER_TOOL_CALL_THRESHOLD:
+                break
+
+    not_used_recently = other_tool_call_count_befor_last_todo >= const.TODO_REMINDER_TOOL_CALL_THRESHOLD
+
+    if not not_used_recently:
+        return None
+
+    if session.need_todo_not_used_cooldown_counter == 0:
+        session.need_todo_not_used_cooldown_counter = 3
+        return model.DeveloperMessageItem(
+            content=f"""<system-reminder>
+The TodoWrite tool hasn't been used recently. If you're working on tasks that would benefit from tracking progress, consider using the TodoWrite tool to track progress. Also consider cleaning up the todo list if has become stale and no longer matches what you are working on. Only use it if it's relevant to the current work. This is just a gentle reminder - ignore if not applicable.
+
+
+Here are the existing contents of your todo list:
+
+{model.todo_list_str(session.todos)}</system-reminder>""",
+            todo_use=True,
+        )
+
+    if session.need_todo_not_used_cooldown_counter > 0:
+        session.need_todo_not_used_cooldown_counter -= 1
+    return None
+
+
+async def file_changed_externally_reminder(
+    session: Session,
+) -> model.DeveloperMessageItem | None:
+    """Remind agent about user/linter' changes to the files in FileTracker, provding the newest content of the file."""
+    changed_files: list[tuple[str, str, list[model.ImageURLPart] | None]] = []
+    collected_images: list[model.ImageURLPart] = []
+    if session.file_tracker and len(session.file_tracker) > 0:
+        for path, mtime in session.file_tracker.items():
+            try:
+                if Path(path).stat().st_mtime > mtime:
+                    context_token = set_tool_context_from_session(session)
+                    try:
+                        tool_result = await ReadTool.call_with_args(
+                            ReadTool.ReadArguments(file_path=path)
+                        )  # This tool will update file tracker
+                        if tool_result.status == "success":
+                            changed_files.append((path, tool_result.output or "", tool_result.images))
+                            if tool_result.images:
+                                collected_images.extend(tool_result.images)
+                    finally:
+                        reset_tool_context(context_token)
+            except (
+                FileNotFoundError,
+                IsADirectoryError,
+                OSError,
+                PermissionError,
+                UnicodeDecodeError,
+            ):
+                continue
+    if len(changed_files) > 0:
+        changed_files_str = "\n\n".join(
+            [
+                f"Note: {file_path} was modified, either by the user or by a linter. Don't tell the user this, since they are already aware. This change was intentional, so make sure to take it into account as you proceed (ie. don't revert it unless the user asks you to). So that you don't need to re-read the file, here's the result of running `cat -n` on a snippet of the edited file:\n\n{file_content}"
+                ""
+                for file_path, file_content, _ in changed_files
+            ]
+        )
+        return model.DeveloperMessageItem(
+            content=f"""<system-reminder>{changed_files_str}""",
+            external_file_changes=[file_path for file_path, _, _ in changed_files],
+            images=collected_images or None,
+        )
+
+    return None
+
+
+def get_memory_paths() -> list[tuple[Path, str]]:
+    return [
+        (
+            Path.home() / ".claude" / "CLAUDE.md",
+            "user's private global instructions for all projects",
+        ),
+        (
+            Path.home() / ".codex" / "AGENTS.md",
+            "user's private global instructions for all projects",
+        ),
+        (Path.cwd() / "AGENTS.md", "project instructions, checked into the codebase"),
+        (Path.cwd() / "AGENT.md", "project instructions, checked into the codebase"),
+        (Path.cwd() / "CLAUDE.md", "project instructions, checked into the codebase"),
+    ]
+
+
+class Memory(BaseModel):
+    path: str
+    instruction: str
+    content: str
+
+
+def get_last_user_message_image_count(session: Session) -> int:
+    """Get image count from the last user message in conversation history."""
+    for item in reversed(session.conversation_history):
+        if isinstance(item, model.ToolResultItem):
+            return 0
+        if isinstance(item, model.UserMessageItem):
+            return len(item.images) if item.images else 0
+    return 0
+
+
+async def image_reminder(session: Session) -> model.DeveloperMessageItem | None:
+    """Remind agent about images attached by user in the last message."""
+    image_count = get_last_user_message_image_count(session)
+    if image_count == 0:
+        return None
+
+    return model.DeveloperMessageItem(
+        content=f"<system-reminder>User attached {image_count} image{'s' if image_count > 1 else ''} in their message. Make sure to analyze and reference these images as needed.</system-reminder>",
+        user_image_count=image_count,
+    )
+
+
+async def memory_reminder(session: Session) -> model.DeveloperMessageItem | None:
+    """CLAUDE.md AGENTS.md"""
+    memory_paths = get_memory_paths()
+    memories: list[Memory] = []
+    for memory_path, instruction in memory_paths:
+        if memory_path.exists() and memory_path.is_file() and str(memory_path) not in session.loaded_memory:
+            try:
+                text = memory_path.read_text()
+                session.loaded_memory.append(str(memory_path))
+                memories.append(Memory(path=str(memory_path), instruction=instruction, content=text))
+            except (PermissionError, UnicodeDecodeError, OSError):
+                continue
+    if len(memories) > 0:
+        memories_str = "\n\n".join(
+            [f"Contents of {memory.path} ({memory.instruction}):\n\n{memory.content}" for memory in memories]
+        )
+        return model.DeveloperMessageItem(
+            content=f"""<system-reminder>As you answer the user's questions, you can use the following context:
+
+# claudeMd
+Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.
+{memories_str}
+
+#important-instruction-reminders
+Do what has been asked; nothing more, nothing less.
+NEVER create files unless they're absolutely necessary for achieving your goal.
+ALWAYS prefer editing an existing file to creating a new one.
+NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+
+IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
+</system-reminder>""",
+            memory_paths=[memory.path for memory in memories],
+        )
+    return None
+
+
+def get_last_turn_tool_call(session: Session) -> list[model.ToolCallItem]:
+    tool_calls: list[model.ToolCallItem] = []
+    for item in reversed(session.conversation_history):
+        if isinstance(item, model.ToolCallItem):
+            tool_calls.append(item)
+        if isinstance(
+            item,
+            (
+                model.ReasoningEncryptedItem,
+                model.ReasoningTextItem,
+                model.AssistantMessageItem,
+            ),
+        ):
+            break
+    return tool_calls
+
+
+MEMORY_FILE_NAMES = ["CLAUDE.md", "AGENTS.md", "AGENT.md"]
+
+
+async def last_path_memory_reminder(
+    session: Session,
+) -> model.DeveloperMessageItem | None:
+    """When last turn tool call entered a directory (or parent directory) with CLAUDE.md AGENTS.md"""
+    tool_calls = get_last_turn_tool_call(session)
+    if len(tool_calls) == 0:
+        return None
+    paths: list[str] = []
+    for tool_call in tool_calls:
+        if tool_call.name in (tools.READ, tools.EDIT, tools.MULTI_EDIT, tools.WRITE):
+            try:
+                json_dict = json.loads(tool_call.arguments)
+                if path := json_dict.get("file_path", ""):
+                    paths.append(path)
+            except json.JSONDecodeError:
+                continue
+        elif tool_call.name == tools.BASH:
+            # TODO: haiku check file path
+            pass
+    paths = list(set(paths))
+    memories: list[Memory] = []
+    if len(paths) == 0:
+        return None
+
+    cwd = Path.cwd().resolve()
+    loaded_set: set[str] = set(session.loaded_memory)
+    seen_memory_files: set[str] = set()
+
+    for p_str in paths:
+        p = Path(p_str)
+        full = (cwd / p).resolve() if not p.is_absolute() else p.resolve()
+        try:
+            _ = full.relative_to(cwd)
+        except ValueError:
+            # Not under cwd; skip
+            continue
+
+        # Determine the deepest directory to scan (file parent or directory itself)
+        deepest_dir = full if full.is_dir() else full.parent
+
+        # Iterate each directory level from cwd to deepest_dir
+        try:
+            rel_parts = deepest_dir.relative_to(cwd).parts
+        except ValueError:
+            # Shouldn't happen due to check above, but guard anyway
+            continue
+
+        current_dir = cwd
+        for part in rel_parts:
+            current_dir = current_dir / part
+            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 mem_path_str in loaded_set:
+                    continue
+                if mem_path.exists() and mem_path.is_file():
+                    try:
+                        text = mem_path.read_text()
+                    except (PermissionError, UnicodeDecodeError, OSError):
+                        continue
+                    session.loaded_memory.append(mem_path_str)
+                    loaded_set.add(mem_path_str)
+                    seen_memory_files.add(mem_path_str)
+                    memories.append(
+                        Memory(
+                            path=mem_path_str,
+                            instruction="project instructions, discovered near last accessed path",
+                            content=text,
+                        )
+                    )
+
+    if len(memories) > 0:
+        memories_str = "\n\n".join(
+            [f"Contents of {memory.path} ({memory.instruction}):\n\n{memory.content}" for memory in memories]
+        )
+        return model.DeveloperMessageItem(
+            content=f"""<system-reminder>{memories_str}
+</system-reminder>""",
+            memory_paths=[memory.path for memory in memories],
+        )
+
+
+ALL_REMINDERS = [
+    empty_todo_reminder,
+    todo_not_used_recently_reminder,
+    file_changed_externally_reminder,
+    memory_reminder,
+    last_path_memory_reminder,
+    at_file_reader_reminder,
+    image_reminder,
+]
+
+
+def load_agent_reminders(
+    model_name: str, sub_agent_type: str | None = None, *, vanilla: bool = False
+) -> list[Reminder]:
+    """Get reminders for an agent based on model and agent type.
+
+    Args:
+        model_name: The model name.
+        sub_agent_type: If None, returns main agent reminders. Otherwise returns sub-agent reminders.
+        vanilla: If True, returns minimal vanilla reminders (ignores sub_agent_type).
+    """
+    if vanilla:
+        return [at_file_reader_reminder]
+
+    reminders: list[Reminder] = []
+
+    # Only main agent (not sub-agent) gets todo reminders, and not for GPT-5
+    if sub_agent_type is None and "gpt-5" not in model_name:
+        reminders.append(empty_todo_reminder)
+        reminders.append(todo_not_used_recently_reminder)
+
+    reminders.extend(
+        [
+            memory_reminder,
+            last_path_memory_reminder,
+            at_file_reader_reminder,
+            file_changed_externally_reminder,
+            image_reminder,
+        ]
+    )
+
+    return reminders

klaude_code/core/task.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncGenerator, Callable, MutableMapping, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from klaude_code import const
+from klaude_code.core.reminders import Reminder
+from klaude_code.core.tool import TodoContext, ToolABC
+from klaude_code.core.turn import TurnError, TurnExecutionContext, TurnExecutor
+from klaude_code.protocol import events, model
+from klaude_code.trace import DebugType, log_debug
+
+if TYPE_CHECKING:
+    from klaude_code.core.agent import AgentProfile
+
+
+class MetadataAccumulator:
+    """Accumulates response metadata across multiple turns.
+
+    Tracks usage statistics including tokens, latency, and throughput,
+    merging them into a single aggregated result.
+    """
+
+    def __init__(self, model_name: str) -> None:
+        self._accumulated = model.ResponseMetadataItem(model_name=model_name)
+        self._throughput_weighted_sum: float = 0.0
+        self._throughput_tracked_tokens: int = 0
+
+    def add(self, turn_metadata: model.ResponseMetadataItem) -> None:
+        """Merge a turn's metadata into the accumulated state."""
+        accumulated = self._accumulated
+        usage = turn_metadata.usage
+
+        if usage is not None:
+            if accumulated.usage is None:
+                accumulated.usage = model.Usage()
+            acc_usage = accumulated.usage
+            acc_usage.input_tokens += usage.input_tokens
+            acc_usage.cached_tokens += usage.cached_tokens
+            acc_usage.reasoning_tokens += usage.reasoning_tokens
+            acc_usage.output_tokens += usage.output_tokens
+            acc_usage.total_tokens += usage.total_tokens
+
+            if usage.context_usage_percent is not None:
+                acc_usage.context_usage_percent = usage.context_usage_percent
+
+            if usage.first_token_latency_ms is not None:
+                if acc_usage.first_token_latency_ms is None:
+                    acc_usage.first_token_latency_ms = usage.first_token_latency_ms
+                else:
+                    acc_usage.first_token_latency_ms = min(
+                        acc_usage.first_token_latency_ms,
+                        usage.first_token_latency_ms,
+                    )
+
+            if usage.throughput_tps is not None:
+                current_output = usage.output_tokens
+                if current_output > 0:
+                    self._throughput_weighted_sum += usage.throughput_tps * current_output
+                    self._throughput_tracked_tokens += current_output
+
+            # Accumulate costs
+            if usage.input_cost is not None:
+                acc_usage.input_cost = (acc_usage.input_cost or 0.0) + usage.input_cost
+            if usage.output_cost is not None:
+                acc_usage.output_cost = (acc_usage.output_cost or 0.0) + usage.output_cost
+            if usage.cache_read_cost is not None:
+                acc_usage.cache_read_cost = (acc_usage.cache_read_cost or 0.0) + usage.cache_read_cost
+            if usage.total_cost is not None:
+                acc_usage.total_cost = (acc_usage.total_cost or 0.0) + usage.total_cost
+
+        if turn_metadata.provider is not None:
+            accumulated.provider = turn_metadata.provider
+        if turn_metadata.model_name:
+            accumulated.model_name = turn_metadata.model_name
+        if turn_metadata.response_id:
+            accumulated.response_id = turn_metadata.response_id
+        if turn_metadata.status is not None:
+            accumulated.status = turn_metadata.status
+        if turn_metadata.error_reason is not None:
+            accumulated.error_reason = turn_metadata.error_reason
+
+    def finalize(self, task_duration_s: float) -> model.ResponseMetadataItem:
+        """Return the final accumulated metadata with computed throughput and duration."""
+        accumulated = self._accumulated
+        if accumulated.usage is not None:
+            if self._throughput_tracked_tokens > 0:
+                accumulated.usage.throughput_tps = self._throughput_weighted_sum / self._throughput_tracked_tokens
+            else:
+                accumulated.usage.throughput_tps = None
+
+        accumulated.task_duration_s = task_duration_s
+        return accumulated
+
+
+@dataclass
+class TaskExecutionContext:
+    """Execution context required to run a task."""
+
+    session_id: str
+    profile: AgentProfile
+    get_conversation_history: Callable[[], list[model.ConversationItem]]
+    append_history: Callable[[Sequence[model.ConversationItem]], None]
+    tool_registry: dict[str, type[ToolABC]]
+    file_tracker: MutableMapping[str, float]
+    todo_context: TodoContext
+    # For reminder processing - needs access to session
+    process_reminder: Callable[[Reminder], AsyncGenerator[events.DeveloperMessageEvent, None]]
+    sub_agent_state: model.SubAgentState | None
+
+
+class TaskExecutor:
+    """Executes a complete task (multiple turns until no more tool calls).
+
+    Manages task-level state like metadata accumulation and retry logic.
+    """
+
+    def __init__(self, context: TaskExecutionContext) -> None:
+        self._context = context
+        self._current_turn: TurnExecutor | None = None
+        self._started_at: float = 0.0
+
+    @property
+    def current_turn(self) -> TurnExecutor | None:
+        return self._current_turn
+
+    def cancel(self) -> list[events.Event]:
+        """Cancel the current turn and return any resulting events."""
+        ui_events: list[events.Event] = []
+        if self._current_turn is not None:
+            ui_events.extend(self._current_turn.cancel())
+            self._current_turn = None
+        return ui_events
+
+    async def run(self, user_input: model.UserInputPayload) -> AsyncGenerator[events.Event, None]:
+        """Execute the task, yielding events as they occur."""
+        ctx = self._context
+        self._started_at = time.perf_counter()
+
+        yield events.TaskStartEvent(
+            session_id=ctx.session_id,
+            sub_agent_state=ctx.sub_agent_state,
+        )
+
+        ctx.append_history([model.UserMessageItem(content=user_input.text, images=user_input.images)])
+
+        profile = ctx.profile
+        metadata_accumulator = MetadataAccumulator(model_name=profile.llm_client.model_name)
+        last_assistant_message: events.AssistantMessageEvent | None = None
+
+        while True:
+            # Process reminders at the start of each turn
+            for reminder in profile.reminders:
+                async for event in ctx.process_reminder(reminder):
+                    yield event
+
+            turn_context = TurnExecutionContext(
+                session_id=ctx.session_id,
+                get_conversation_history=ctx.get_conversation_history,
+                append_history=ctx.append_history,
+                llm_client=profile.llm_client,
+                system_prompt=profile.system_prompt,
+                tools=profile.tools,
+                tool_registry=ctx.tool_registry,
+                file_tracker=ctx.file_tracker,
+                todo_context=ctx.todo_context,
+            )
+
+            turn: TurnExecutor | None = None
+            turn_succeeded = False
+            last_error_message: str | None = None
+
+            for attempt in range(const.MAX_FAILED_TURN_RETRIES + 1):
+                turn = TurnExecutor(turn_context)
+                self._current_turn = turn
+
+                try:
+                    async for turn_event in turn.run():
+                        match turn_event:
+                            case events.AssistantMessageEvent() as am:
+                                if am.content.strip() != "":
+                                    last_assistant_message = am
+                                yield am
+                            case events.ResponseMetadataEvent() as e:
+                                metadata_accumulator.add(e.metadata)
+                            case _:
+                                yield turn_event
+
+                    turn_succeeded = True
+                    break
+                except TurnError as e:
+                    last_error_message = str(e)
+                    if attempt < const.MAX_FAILED_TURN_RETRIES:
+                        delay = _retry_delay_seconds(attempt + 1)
+                        error_msg = f"Retrying {attempt + 1}/{const.MAX_FAILED_TURN_RETRIES} in {delay:.1f}s"
+                        if last_error_message:
+                            error_msg = f"{error_msg} - {last_error_message}"
+                        yield events.ErrorEvent(error_message=error_msg, can_retry=True)
+                        await asyncio.sleep(delay)
+                finally:
+                    self._current_turn = None
+
+            if not turn_succeeded:
+                log_debug(
+                    "Maximum consecutive failed turns reached, aborting task",
+                    style="red",
+                    debug_type=DebugType.EXECUTION,
+                )
+                final_error = f"Turn failed after {const.MAX_FAILED_TURN_RETRIES} retries."
+                if last_error_message:
+                    final_error = f"{last_error_message}\n{final_error}"
+                yield events.ErrorEvent(error_message=final_error, can_retry=False)
+                return
+
+            if turn is None or not turn.has_tool_call:
+                break
+
+        # Finalize metadata
+        task_duration_s = time.perf_counter() - self._started_at
+        accumulated = metadata_accumulator.finalize(task_duration_s)
+
+        yield events.ResponseMetadataEvent(metadata=accumulated, session_id=ctx.session_id)
+        ctx.append_history([accumulated])
+        yield events.TaskFinishEvent(
+            session_id=ctx.session_id,
+            task_result=last_assistant_message.content if last_assistant_message else "",
+        )
+
+
+def _retry_delay_seconds(attempt: int) -> float:
+    """Compute exponential backoff delay for the given attempt count."""
+    capped_attempt = max(1, attempt)
+    delay = const.INITIAL_RETRY_DELAY_S * (2 ** (capped_attempt - 1))
+    return min(delay, const.MAX_RETRY_DELAY_S)