crabcode 0.1.6__py3-none-win_amd64.whl

crabcode_core/query/loop.py

@@ -0,0 +1,2446 @@
+"""Query loop — the agentic turn loop, heart of the system.
+
+Ported from src/query.ts. Sends messages to the API, processes tool calls,
+and loops until the model stops using tools.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from dataclasses import dataclass, field, replace
+from typing import Any, AsyncGenerator, Callable, Coroutine
+
+import httpx
+
+from crabcode_core.api.base import APIAdapter, ModelConfig, usage_int_field
+from crabcode_core.usage import tracked_stream_message
+from crabcode_core.api.network import certificate_failure, network_error_message
+from crabcode_core.compact.compact import (
+    DEFAULT_COMPACT_BUFFER_TOKENS,
+    compact_conversation,
+    compact_summary_text,
+    compaction_input_limit,
+    conversation_turn_starts,
+    estimate_token_count,
+)
+from crabcode_core.compact.context_tokens import ContextTokenTracker, RequestSnapshot, TokenMeasurement
+from crabcode_core.logging_utils import get_logger
+from crabcode_core.prompts.blocks import SystemPrompt
+from crabcode_core.tools.loading import ToolCatalog, ToolLoadingState
+from crabcode_core.query.retry import ResponsesStreamRetryState, StreamRetry
+from crabcode_core.query.computer_use_history import project_computer_use_history
+from crabcode_core.types.config import ApiConfig, ToolLoadingSettings
+from crabcode_core.types.event import (
+    CompactEvent,
+    CoreEvent,
+    ErrorEvent,
+    PermissionRequestEvent,
+    PermissionResponseEvent,
+    StreamModeEvent,
+    StreamRetryEvent,
+    StreamTextEvent,
+    SteeringAppliedEvent,
+    ThinkingEvent,
+    ToolResultEvent,
+    ToolUseEvent,
+    TurnCompleteEvent,
+)
+from crabcode_core.types.message import (
+    AssistantMessage,
+    ContentBlock,
+    Message,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    create_assistant_message,
+    create_tool_result_message,
+    create_user_message,
+)
+from crabcode_core.permissions.ai_reviewer import AiPermissionReviewer, AiReviewRequest
+from crabcode_core.permissions.manager import PermissionMode
+from crabcode_core.tools._input_schema import (
+    ToolInputNormalization,
+    normalize_tool_input,
+)
+from crabcode_core.types.tool import PermissionBehavior, PermissionResult, Tool, ToolContext, ToolResult
+
+logger = get_logger(__name__)
+
+
+def _repair_unpaired_tool_calls(
+    messages: list[Message],
+) -> list[tuple[ToolUseBlock, Message]]:
+    """Normalize tool call/result ordering and close interrupted calls.
+
+    A provider requires every assistant ``tool_use`` to have a matching
+    ``tool_result`` before another user message.  Cancellation or a client
+    retry can leave results after an intervening user message, or leave the
+    assistant call without a result.  Move existing result messages next to
+    their call and insert a deterministic failure result for any missing ID.
+    """
+    result_messages: dict[str, Message] = {}
+    for message in messages:
+        content = message.content
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if isinstance(block, ToolResultBlock) and block.tool_use_id:
+                result_messages.setdefault(block.tool_use_id, message)
+
+    repairs_by_assistant: dict[str, list[ToolUseBlock]] = {}
+    known_call_ids: set[str] = set()
+    for message in messages:
+        if not isinstance(message, AssistantMessage):
+            continue
+        for block in message.tool_use_blocks:
+            if not block.id:
+                continue
+            known_call_ids.add(block.id)
+            if block.id not in result_messages:
+                repairs_by_assistant.setdefault(message.uuid, []).append(block)
+
+    if not known_call_ids:
+        return []
+
+    repaired: list[tuple[ToolUseBlock, Message]] = []
+    rebuilt: list[Message] = []
+    emitted_result_messages: set[str] = set()
+    for message in messages:
+        content = message.content
+        if isinstance(content, list) and any(
+            isinstance(block, ToolResultBlock)
+            and block.tool_use_id in known_call_ids
+            for block in content
+        ) and message.uuid in emitted_result_messages:
+            continue
+
+        rebuilt.append(message)
+        if isinstance(content, list) and any(
+            isinstance(block, ToolResultBlock)
+            and block.tool_use_id in known_call_ids
+            for block in content
+        ) and not isinstance(message, AssistantMessage):
+            # A result that appeared before its assistant call is already in
+            # the right relative position; mark it so the assistant pass does
+            # not emit a duplicate copy later.
+            emitted_result_messages.add(message.uuid)
+
+        if isinstance(message, AssistantMessage):
+            for block in message.tool_use_blocks:
+                existing = result_messages.get(block.id)
+                if existing is not None:
+                    if existing.uuid not in emitted_result_messages:
+                        rebuilt.append(existing)
+                        emitted_result_messages.add(existing.uuid)
+                    continue
+                if block.id not in {
+                    candidate.id
+                    for candidate in repairs_by_assistant.get(message.uuid, [])
+                }:
+                    continue
+                result = create_tool_result_message(
+                    tool_use_id=block.id,
+                    result="Tool call was interrupted before a result was produced.",
+                    is_error=True,
+                    source_tool_assistant_uuid=message.uuid,
+                )
+                rebuilt.append(result)
+                repaired.append((block, result))
+
+    messages[:] = rebuilt
+    return repaired
+
+
+def _append_missing_tool_results(
+    messages: list[Message],
+    tool_use_blocks: list[ToolUseBlock],
+    assistant_uuid: str,
+) -> list[tuple[ToolUseBlock, Message]]:
+    """Close tool calls that were cancelled before their execution returned."""
+    result_ids = {
+        block.tool_use_id
+        for message in messages
+        if isinstance(message.content, list)
+        for block in message.content
+        if isinstance(block, ToolResultBlock)
+    }
+    repaired: list[tuple[ToolUseBlock, Message]] = []
+    for block in tool_use_blocks:
+        if not block.id or block.id in result_ids:
+            continue
+        result = create_tool_result_message(
+            tool_use_id=block.id,
+            result="Tool call was interrupted before a result was produced.",
+            is_error=True,
+            source_tool_assistant_uuid=assistant_uuid,
+        )
+        messages.append(result)
+        result_ids.add(block.id)
+        repaired.append((block, result))
+    return repaired
+
+
+def _completed_tool_result(
+    messages: list[Message],
+    tool_use_id: str,
+) -> ToolResultBlock | None:
+    """Find a durable result so replayed call IDs never execute twice."""
+    if not tool_use_id:
+        return None
+    for message in reversed(messages):
+        if not isinstance(message.content, list):
+            continue
+        for block in message.content:
+            if (
+                isinstance(block, ToolResultBlock)
+                and block.tool_use_id == tool_use_id
+            ):
+                return block
+    return None
+
+
+def _format_exception_message(exc: Exception) -> str:
+    """Return an actionable message even when an exception has an empty str()."""
+    exception_name = type(exc).__name__
+    detail = str(exc).strip()
+    if detail:
+        return f"{exception_name}: {detail}"
+    return f"{exception_name}: no additional details"
+
+
+def _iter_exception_chain(exc: BaseException):
+    """Yield an exception and the causes/contexts it wraps."""
+    pending: list[BaseException] = [exc]
+    seen: set[int] = set()
+    while pending:
+        current = pending.pop()
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        yield current
+        for nested in (current.__cause__, current.__context__):
+            if nested is not None:
+                pending.append(nested)
+
+
+def _is_http_transport_error(exc: BaseException) -> bool:
+    """Match httpx transport failures, including the parallel httpx2 client.
+
+    The OpenAI SDK raises ``APIConnectionError`` from ``httpx2.RemoteProtocolError``.
+    That class mirrors ``httpx.TransportError`` but is not a subclass of it.
+    """
+    if isinstance(exc, httpx.TransportError):
+        return True
+    module = type(exc).__module__.split(".", 1)[0]
+    if module not in {"httpx", "httpx2"}:
+        return False
+    return any(base.__name__ == "TransportError" for base in type(exc).__mro__)
+
+
+def _is_http_connection_error(exc: BaseException) -> bool:
+    """Match connect failures from httpx and httpx2."""
+    if isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)):
+        return True
+    module = type(exc).__module__.split(".", 1)[0]
+    if module not in {"httpx", "httpx2"}:
+        return False
+    return type(exc).__name__ in {"ConnectError", "ConnectTimeout"}
+
+
+def _is_recoverable_api_exception(exc: Exception) -> bool:
+    """Identify transport/server failures that are safe for the caller to retry."""
+    if certificate_failure(exc):
+        return False
+    for current in _iter_exception_chain(exc):
+        if _is_http_transport_error(current) or isinstance(
+            current,
+            (asyncio.TimeoutError, json.JSONDecodeError, OSError),
+        ):
+            return True
+
+        status_code = getattr(current, "status_code", None)
+        if isinstance(status_code, int) and (
+            status_code in {408, 409, 429} or status_code >= 500
+        ):
+            return True
+
+    return False
+
+
+def _is_connection_api_exception(exc: Exception) -> bool:
+    """Return whether the unbounded connection retry path applies."""
+    return any(_is_http_connection_error(current) for current in _iter_exception_chain(exc))
+
+
+def _retry_after_seconds_from_message(message: str) -> float | None:
+    """Parse the server-advised delay used by Responses rate-limit errors."""
+    match = re.search(
+        r"(?:please\s+)?try\s+again\s+in\s+"
+        r"(\d+(?:\.\d+)?)\s*(ms|s|seconds?)\b",
+        message,
+        flags=re.IGNORECASE,
+    )
+    if not match:
+        return None
+    value = float(match.group(1))
+    unit = match.group(2).lower()
+    return value / 1000.0 if unit == "ms" else value
+
+
+def _retry_after_seconds_from_exception(exc: Exception) -> float | None:
+    pending: list[BaseException] = [exc]
+    seen: set[int] = set()
+    while pending:
+        current = pending.pop()
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        response = getattr(current, "response", None)
+        headers = getattr(response, "headers", None)
+        if headers is not None:
+            raw = headers.get("retry-after")
+            if raw is not None:
+                try:
+                    return max(0.0, float(raw))
+                except (TypeError, ValueError):
+                    pass
+        parsed = _retry_after_seconds_from_message(str(current))
+        if parsed is not None:
+            return parsed
+        for nested in (current.__cause__, current.__context__):
+            if nested is not None:
+                pending.append(nested)
+    return None
+
+
+def _is_recoverable_api_error_message(message: str) -> bool:
+    """Recognize transient failures delivered as successful stream events."""
+    text = message.lower().strip()
+    if not text:
+        return False
+
+    transient_phrases = (
+        "an error occurred while processing your request",
+        "you can retry your request",
+        "response failed",
+        "request timeout",
+        "too many requests",
+        "rate limit",
+        "internal server error",
+        "server error",
+        "bad gateway",
+        "service unavailable",
+        "gateway timeout",
+        "temporarily unavailable",
+        "server is overloaded",
+        "server overloaded",
+        "stream ended without a terminal event",
+        "invalid responses sse payload",
+    )
+    if any(phrase in text for phrase in transient_phrases):
+        return True
+
+    # Direct SSE adapters surface non-2xx responses as "HTTP <status>" text.
+    import re
+
+    match = re.search(r"\bhttp\s+(\d{3})\b", text)
+    if not match:
+        return False
+    status_code = int(match.group(1))
+    return status_code in {408, 409, 429} or status_code >= 500
+
+
+def _merge_permission_results(
+    rule_perm: PermissionResult,
+    tool_perm: PermissionResult,
+) -> PermissionResult:
+    updated_input = tool_perm.updated_input if tool_perm.updated_input is not None else rule_perm.updated_input
+    permission_key = tool_perm.permission_key or rule_perm.permission_key
+
+    if rule_perm.behavior == PermissionBehavior.DENY:
+        return PermissionResult(
+            behavior=PermissionBehavior.DENY,
+            reason=rule_perm.reason or tool_perm.reason,
+            updated_input=updated_input,
+            permission_key=permission_key,
+        )
+    if tool_perm.behavior == PermissionBehavior.DENY:
+        return PermissionResult(
+            behavior=PermissionBehavior.DENY,
+            reason=tool_perm.reason or rule_perm.reason,
+            updated_input=updated_input,
+            permission_key=permission_key,
+        )
+    if (
+        rule_perm.behavior == PermissionBehavior.ASK
+        or tool_perm.behavior == PermissionBehavior.ASK
+    ):
+        reason = tool_perm.reason or rule_perm.reason
+        return PermissionResult(
+            behavior=PermissionBehavior.ASK,
+            reason=reason,
+            updated_input=updated_input,
+            permission_key=permission_key,
+        )
+    return PermissionResult(
+        behavior=PermissionBehavior.ALLOW,
+        reason=tool_perm.reason or rule_perm.reason,
+        updated_input=updated_input,
+        permission_key=permission_key,
+    )
+
+
+@dataclass
+class QueryParams:
+    messages: list[Message]
+    system_prompt: list[str]
+    user_context: dict[str, str]
+    system_context: dict[str, str]
+    tools: list[Tool]
+    tool_context: ToolContext
+    api_adapter: APIAdapter
+    max_turns: int = 0
+    permission_manager: Any = None
+    permission_queue: asyncio.Queue | None = None
+    hook_manager: Any = None
+    agent_mode: str = "agent"  # "agent" | "plan"
+    api_config: ApiConfig | None = None  # passed from session for ModelConfig
+    context_window: int = 0  # resolved context window size
+    context_token_tracker: ContextTokenTracker | None = None
+    ai_reviewer: AiPermissionReviewer | None = None
+    tool_call_timeout: float | None = None  # seconds; None means no timeout
+    auto_compact_enabled: bool = True
+    compact_buffer_tokens: int = DEFAULT_COMPACT_BUFFER_TOKENS
+    compact_threshold: int | None = None
+    compact_prompt: str | None = None
+    reply_to_uuid: str | None = None
+    drain_peer_messages: Callable[[], list[str]] | None = None
+    # User guidance submitted while the foreground turn is running.  These
+    # messages are drained only at model-request boundaries, after a complete
+    # tool-result batch has been appended to the conversation.
+    drain_steering_messages: Callable[[], list[Message]] | None = None
+    tool_loading: ToolLoadingSettings | None = None
+    tool_loading_state: ToolLoadingState | None = None
+    on_tools_loaded: Callable[[list[str]], None] | None = None
+    pinned_tools: tuple[str, ...] = ()
+    # Checked user prompts. Applied only to the model request, not the transcript.
+    user_append_prompts: list[str] = field(default_factory=list)
+
+
+def _plan_mode_is_active(params: QueryParams) -> bool:
+    """Return whether this turn must enforce the read-only plan boundary.
+
+    ``agent_mode`` is the immutable mode captured when the turn starts.  The
+    live session check additionally closes the race where a client switches an
+    already-running agent turn into plan mode before its next tool call.
+    """
+    if params.agent_mode == "plan":
+        return True
+    session = params.tool_context.session
+    return getattr(session, "agent_mode", None) == "plan"
+
+
+def _append_system_context(
+    system_prompt: list[str],
+    context: dict[str, str],
+) -> list[str]:
+    """Append system context entries to the end of system prompt."""
+    if not context:
+        return system_prompt
+    extra = "\n".join(f"{k}: {v}" for k, v in context.items() if v)
+    if extra:
+        if isinstance(system_prompt, SystemPrompt):
+            return system_prompt.with_dynamic(extra)
+        return [*system_prompt, extra]
+    return system_prompt
+
+
+def _prepend_user_context(
+    messages: list[Message],
+    user_context: dict[str, str],
+) -> list[Message]:
+    """Prepare request-only history and prepend user context at the start."""
+    messages = project_computer_use_history(messages)
+    if not user_context:
+        return messages
+
+    ctx_parts = []
+    for key, value in user_context.items():
+        ctx_parts.append(f"# {key}\n{value}")
+    ctx_text = "\n".join(ctx_parts)
+
+    meta_msg = create_user_message(
+        content=(
+            f"<system-reminder>\n"
+            f"As you answer the user's questions, you can use the following context:\n"
+            f"{ctx_text}\n\n"
+            f"IMPORTANT: this context may or may not be relevant to your tasks. "
+            f"You should not respond to this context unless it is highly relevant "
+            f"to your task.\n</system-reminder>\n"
+        ),
+    )
+
+    return [meta_msg, *messages]
+
+
+def _user_rules_block(prompts: list[str]) -> str:
+    lines = [text.strip() for text in prompts if text and text.strip()]
+    if not lines:
+        return ""
+    return "<user-rules>\n" + "\n\n".join(lines) + "\n</user-rules>"
+
+
+def _is_conversational_user_message(message: Message) -> bool:
+    role = getattr(message.role, "value", message.role)
+    if role != "user" or message.is_compact_summary:
+        return False
+    if message.origin in {"peer-message", "task-notification"}:
+        return False
+    content = message.content
+    if isinstance(content, str):
+        return True
+    if not content:
+        return False
+    return any(not isinstance(block, ToolResultBlock) for block in content)
+
+
+def _append_user_prompts(messages: list[Message], prompts: list[str]) -> list[Message]:
+    """Append checked prompts to the latest user message in a request copy."""
+    block = _user_rules_block(prompts)
+    if not block:
+        return messages
+    index = next(
+        (
+            position
+            for position in range(len(messages) - 1, -1, -1)
+            if _is_conversational_user_message(messages[position])
+        ),
+        None,
+    )
+    if index is None:
+        return messages
+    cloned = messages[index].model_copy(deep=True)
+    suffix = f"\n\n{block}"
+    if isinstance(cloned.content, str):
+        cloned.content = f"{cloned.content}{suffix}" if cloned.content else block
+    else:
+        blocks = list(cloned.content)
+        text_indexes = [position for position, item in enumerate(blocks) if isinstance(item, TextBlock)]
+        if text_indexes:
+            text_index = text_indexes[-1]
+            current = blocks[text_index]
+            blocks[text_index] = current.model_copy(update={"text": f"{current.text}{suffix}"})
+        else:
+            blocks.append(TextBlock(text=block))
+        cloned.content = blocks
+    copied = list(messages)
+    copied[index] = cloned
+    return copied
+
+
+def _messages_for_model(messages: list[Message], params: QueryParams) -> list[Message]:
+    prepared = _prepend_user_context(messages, params.user_context)
+    return _append_user_prompts(prepared, params.user_append_prompts)
+
+
+def _find_tool(tools: list[Tool], name: str) -> Tool | None:
+    for tool in tools:
+        if tool.name == name:
+            return tool
+    return None
+
+
+def _normalize_and_record_tool_input(
+    tool: Tool,
+    block: ToolUseBlock,
+) -> ToolInputNormalization:
+    normalization = normalize_tool_input(block.input, tool.input_schema)
+    if normalization.corrections:
+        logger.warning(
+            "telemetry tool_input_schema_normalized tool=%s tool_use_id=%s corrections=%s",
+            tool.name,
+            block.id,
+            json.dumps(
+                [
+                    {
+                        "path": correction.path,
+                        "received": correction.received,
+                        "expected": correction.expected,
+                    }
+                    for correction in normalization.corrections
+                ],
+                separators=(",", ":"),
+                sort_keys=True,
+            ),
+        )
+    return normalization
+
+
+async def _run_tools(
+    tool_use_blocks: list[ToolUseBlock],
+    assistant_msg: AssistantMessage,
+    tools: list[Tool],
+    context: ToolContext,
+    hook_manager: Any = None,
+    tool_call_timeout: float | None = None,
+) -> AsyncGenerator[tuple[list[Message], ToolResultEvent] | CoreEvent, None]:
+    """Execute tool calls, yielding result events and mid-execution events.
+
+    Runs concurrency-safe tools in parallel, others sequentially.
+    Yields either (messages, ToolResultEvent) tuples or standalone
+    CoreEvents (e.g. ChoiceRequestEvent) emitted by tools during execution.
+
+    When a tool puts events into context.tool_event_queue (e.g. AskUserTool
+    emitting a ChoiceRequestEvent), this function monitors the queue concurrently
+    with the tool execution and yields those events immediately so the frontend
+    can respond (e.g. show a choice UI) while the tool is still awaiting input.
+    """
+    import asyncio
+
+    safe: list[ToolUseBlock] = []
+    unsafe: list[ToolUseBlock] = []
+    for block in tool_use_blocks:
+        tool = _find_tool(tools, block.name)
+        if tool and tool.is_concurrency_safe:
+            safe.append(block)
+        else:
+            unsafe.append(block)
+
+    def _hook_feedback_messages(tag: str, feedbacks: list[str] | None) -> list[Message]:
+        if not feedbacks:
+            return []
+        msgs: list[Message] = []
+        for text in feedbacks:
+            if not text:
+                continue
+            msgs.append(
+                create_user_message(
+                    content=f"<{tag}>\n{text}\n</{tag}>"
+                )
+            )
+        return msgs
+
+    async def execute_one(block: ToolUseBlock) -> tuple[list[Message], ToolResultEvent]:
+        tool = _find_tool(tools, block.name)
+        # Each invocation gets an isolated image sink.  This is the same
+        # per-tool boundary Codex uses for ``emitImage`` output and prevents
+        # concurrent tools from sharing attachments.
+        call_context = replace(context, tool_use_id=block.id, emitted_images=[])
+        if not tool:
+            msg = create_tool_result_message(
+                tool_use_id=block.id,
+                result=f"Error: unknown tool '{block.name}'",
+                is_error=True,
+                source_tool_assistant_uuid=assistant_msg.uuid,
+            )
+            event = ToolResultEvent(
+                tool_use_id=block.id,
+                tool_name=block.name,
+                result=f"Error: unknown tool '{block.name}'",
+                is_error=True,
+                tool_input=block.input,
+            )
+            return [msg], event
+
+        normalization = _normalize_and_record_tool_input(tool, block)
+        if normalization.error:
+            msg = create_tool_result_message(
+                tool_use_id=block.id,
+                result=f"Validation error: {normalization.error}",
+                is_error=True,
+                source_tool_assistant_uuid=assistant_msg.uuid,
+            )
+            event = ToolResultEvent(
+                tool_use_id=block.id,
+                tool_name=block.name,
+                result=f"Validation error: {normalization.error}",
+                is_error=True,
+                tool_input=block.input,
+            )
+            return [msg], event
+        if normalization.corrections:
+            block = block.model_copy(update={"input": normalization.value}, deep=True)
+
+        validation_error = await tool.validate_input(block.input)
+        if validation_error:
+            msg = create_tool_result_message(
+                tool_use_id=block.id,
+                result=f"Validation error: {validation_error}",
+                is_error=True,
+                source_tool_assistant_uuid=assistant_msg.uuid,
+            )
+            event = ToolResultEvent(
+                tool_use_id=block.id,
+                tool_name=block.name,
+                result=f"Validation error: {validation_error}",
+                is_error=True,
+                tool_input=block.input,
+            )
+            return [msg], event
+
+        extra_messages: list[Message] = []
+        if hook_manager:
+            pre_result = await hook_manager.run(
+                "pre_tool_call",
+                {
+                    "tool_name": block.name,
+                    "tool_input": block.input,
+                    "tool_use_id": block.id,
+                    "agent_id": context.agent_id,
+                },
+                cwd=context.cwd,
+                env=context.env,
+            )
+            extra_messages.extend(
+                _hook_feedback_messages(
+                    "pre-tool-call-hook",
+                    pre_result.feedback,
+                )
+            )
+            if pre_result.blocked:
+                reason = "; ".join(pre_result.details or []) or "blocked by pre_tool_call hook"
+                msg = create_tool_result_message(
+                    tool_use_id=block.id,
+                    result=f"Hook blocked tool call: {reason}",
+                    is_error=True,
+                    source_tool_assistant_uuid=assistant_msg.uuid,
+                )
+                event = ToolResultEvent(
+                    tool_use_id=block.id,
+                    tool_name=block.name,
+                    result=f"Hook blocked tool call: {reason}",
+                    is_error=True,
+                    tool_input=block.input,
+                )
+                return [*extra_messages, msg], event
+
+        timeout_enabled = tool_call_timeout is not None and tool_call_timeout > 0
+        try:
+            # Permissions/hooks may have awaited user input since dispatch.
+            # Recheck live availability, retaining the request's immutable exposure set.
+            catalog = call_context.tool_catalog
+            if catalog is not None and (
+                tool.name not in catalog.exposed_names or not tool.is_available(call_context)
+            ):
+                raise PermissionError("Tool is not exposed or is no longer available")
+            if getattr(call_context.session, "agent_mode", None) == "plan" and not tool.is_read_only:
+                raise PermissionError("Plan mode: write operations are not allowed")
+            if timeout_enabled:
+                result = await asyncio.wait_for(
+                    tool.call(block.input, call_context),
+                    timeout=tool_call_timeout,
+                )
+            else:
+                result = await tool.call(block.input, call_context)
+        except asyncio.TimeoutError as e:
+            if timeout_enabled:
+                result = ToolResult(
+                    result_for_model=f"Tool call timed out after {tool_call_timeout:g}s",
+                    is_error=True,
+                )
+            else:
+                logger.exception("Tool execution timed out: %s", block.name)
+                result = ToolResult(
+                    result_for_model=f"Error executing tool: {e}",
+                    is_error=True,
+                )
+        except Exception as e:
+            logger.exception("Tool execution failed: %s", block.name)
+            result = ToolResult(
+                result_for_model=f"Error executing tool: {e}",
+                is_error=True,
+            )
+
+        if call_context.emitted_images:
+            result.images = [
+                *result.images,
+                *[
+                    image
+                    for image in call_context.emitted_images
+                    if image not in result.images
+                ],
+            ]
+
+        if hook_manager:
+            post_result = await hook_manager.run(
+                "post_tool_call",
+                {
+                    "tool_name": block.name,
+                    "tool_input": block.input,
+                    "tool_use_id": block.id,
+                    "agent_id": context.agent_id,
+                    "tool_result": result.result_for_model,
+                    "tool_is_error": result.is_error,
+                },
+                cwd=context.cwd,
+                env=context.env,
+            )
+            extra_messages.extend(
+                _hook_feedback_messages(
+                    "post-tool-call-hook",
+                    post_result.feedback,
+                )
+            )
+            if post_result.blocked:
+                reason = "; ".join(post_result.details or []) or "post_tool_call hook failed"
+                result = ToolResult(
+                    result_for_model=f"{result.result_for_model}\n\nPost hook error: {reason}",
+                    result_for_display=result.result_for_display,
+                    is_error=True,
+                    images=result.images,
+                )
+
+        msg = create_tool_result_message(
+            tool_use_id=block.id,
+            result=result.result_for_model,
+            is_error=result.is_error,
+            source_tool_assistant_uuid=assistant_msg.uuid,
+            images=result.images,
+        )
+        event = ToolResultEvent(
+            tool_use_id=block.id,
+            tool_name=block.name,
+            result=result.result_for_model,
+            is_error=result.is_error,
+            result_for_display=result.result_for_display,
+            tool_input=block.input,
+            images=result.images,
+        )
+        return [*extra_messages, msg], event
+
+    async def _run_with_event_drain(
+        coro: Coroutine[Any, Any, tuple[list[Message], ToolResultEvent]],
+    ) -> AsyncGenerator[tuple[list[Message], ToolResultEvent] | CoreEvent, None]:
+        """Run a tool coroutine while draining mid-execution events from the queue.
+
+        This solves the deadlock: a tool like AskUserTool puts a ChoiceRequestEvent
+        into tool_event_queue, then blocks on choice_queue. Without draining, the
+        event would never reach the frontend and the tool would wait forever.
+        """
+        task: asyncio.Task[tuple[list[Message], ToolResultEvent]] = asyncio.create_task(coro)
+        queue = context.tool_event_queue
+        get_event: asyncio.Task[Any] | None = None
+
+        try:
+            if not queue:
+                result = await task
+                yield result
+                return
+
+            while not task.done():
+                # Wait for either the tool to finish or an event to arrive.
+                # Keep a reference so an outer cancellation can clean up the
+                # queue waiter as well as the tool task.
+                get_event = asyncio.create_task(queue.get())
+                done, _ = await asyncio.wait(
+                    {task, get_event},
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+
+                if get_event in done:
+                    yield get_event.result()
+                else:
+                    get_event.cancel()
+                    await asyncio.gather(get_event, return_exceptions=True)
+                get_event = None
+
+                # Drain any remaining events before checking task.
+                while True:
+                    try:
+                        yield queue.get_nowait()
+                    except asyncio.QueueEmpty:
+                        break
+
+            result = task.result()
+            # Final drain.
+            while True:
+                try:
+                    yield queue.get_nowait()
+                except asyncio.QueueEmpty:
+                    break
+
+            yield result
+        finally:
+            # Query/session cancellation must not leave a tool running against
+            # resources that are about to be closed, nor a queue waiter holding
+            # a reference to the session.  Await both tasks so their exceptions
+            # are consumed and no "Task exception was never retrieved" warning
+            # is emitted.
+            pending: list[asyncio.Task[Any]] = []
+            if get_event is not None and not get_event.done():
+                get_event.cancel()
+                pending.append(get_event)
+            if not task.done():
+                task.cancel()
+                pending.append(task)
+            if pending:
+                await asyncio.gather(*pending, return_exceptions=True)
+
+    # Safe tools run in parallel (they shouldn't emit mid-execution events)
+    if safe:
+        safe_results = await asyncio.gather(*(execute_one(b) for b in safe))
+        for item in safe_results:
+            yield item
+
+    # Unsafe tools run sequentially with event draining
+    for block in unsafe:
+        async for drained_item in _run_with_event_drain(execute_one(block)):
+            yield drained_item
+
+
+def _parse_context_limit_from_error(error_msg: str) -> int | None:
+    """Try to extract the model's actual context limit from an API error message.
+
+    Common patterns:
+      - "maximum context length is 202752 tokens"
+      - "context window of 128000"
+    """
+    import re
+    m = re.search(r"(?:maximum context length|context window)[^\d]*(\d[\d,_]*)", error_msg, re.IGNORECASE)
+    if m:
+        return int(m.group(1).replace(",", "").replace("_", ""))
+    return None
+
+
+def _is_request_size_error(error: str | Exception) -> bool:
+    """Recognize byte-size rejections independently of model context limits."""
+    import re
+
+    status = getattr(error, "status_code", None)
+    if status is None:
+        status = getattr(getattr(error, "response", None), "status_code", None)
+    if status == 413:
+        return True
+    text = str(error).lower()
+    return bool(re.search(
+        r"(?:^|\bhttp(?:/[\d.]+)?\s+|\bstatus(?:_code)?\s*[:=]?\s*|\berror code:\s*)413\b",
+        text,
+    )) or any(phrase in text for phrase in (
+        "request entity too large",
+        "request body too large",
+        "payload too large",
+        "content too large",
+        "request_too_large",
+        "content_length_exceeded",
+    ))
+
+
+def _request_size_error_event(detail: str) -> ErrorEvent:
+    return ErrorEvent(
+        message=(
+            "The provider rejected the request body as too large. "
+            "Reduce attachment file sizes or send fewer images in a new conversation. "
+            f"Provider error: {detail}"
+        ),
+        recoverable=True,
+        error_type="request_too_large",
+    )
+
+
+def _is_context_overflow_error(error_msg: str) -> bool:
+    """Recognize provider size-limit errors without matching arbitrary HTTP 400s."""
+    text = error_msg.lower()
+    phrases = (
+        "maximum context length",
+        "context length exceeded",
+        "context length limit exceeded",
+        "context window exceeded",
+        "exceeds the context window",
+        "context_length_exceeded",
+        "contextwindowexceeded",
+        "prompt is too long",
+        "input is too long",
+        "too many input tokens",
+        "input token count exceeds",
+        "exceeds the maximum number of tokens",
+        "request too large for model",
+    )
+    return any(phrase in text for phrase in phrases)
+
+
+def _truncate_to_fit_tokens(
+    messages: list[Message],
+    target_tokens: int,
+    system: list[str] | None = None,
+    tools: list[dict[str, Any]] | None = None,
+) -> list[Message]:
+    """Prune tool output, then drop only structurally complete old turns."""
+    if target_tokens <= 0:
+        return messages
+
+    if estimate_token_count(messages, system=system, tools=tools) <= target_tokens:
+        return messages
+    _trim_tool_results_to_fit(
+        messages,
+        target_tokens,
+        system=system,
+        tools=tools,
+    )
+    if estimate_token_count(messages, system=system, tools=tools) <= target_tokens:
+        return messages
+
+    # Preserve the compact summary (if any) and the newest real user turn.
+    starts = conversation_turn_starts(messages)
+    while (
+        estimate_token_count(messages, system=system, tools=tools) > target_tokens
+        and len(starts) > 1
+    ):
+        start, end = starts[0], starts[1]
+        del messages[start:end]
+        starts = conversation_turn_starts(messages)
+
+    return messages
+
+
+def _trim_tool_results_to_fit(
+    messages: list[Message],
+    target_tokens: int,
+    *,
+    system: list[str] | None = None,
+    tools: list[dict[str, Any]] | None = None,
+) -> bool:
+    """Prune oversized tool blocks before paying for a remote summary call."""
+    changed = False
+
+    def estimated() -> int:
+        return estimate_token_count(messages, system=system, tools=tools)
+
+    for max_chars in (2_000, 500):
+        for msg in messages:
+            if isinstance(msg.content, str):
+                continue
+            for block in msg.content:
+                if not isinstance(block, ToolResultBlock) or len(block.content) <= max_chars:
+                    continue
+                marker = "\n... [old tool output pruned to fit context] ...\n"
+                keep = max(0, max_chars - len(marker))
+                left = keep // 2
+                block.content = (
+                    block.content[:left]
+                    + marker
+                    + block.content[-(keep - left) :]
+                )
+                changed = True
+                if estimated() <= target_tokens:
+                    return changed
+    return changed
+
+
+_COMPACT_RESUME_PROMPT = (
+    "[Conversation was compacted to fit the context window. "
+    "Continue the current task from the summary and latest context "
+    "without asking the user to repeat anything.]"
+)
+
+_COMPACT_EMPTY_RESPONSE_RETRY_PROMPT = (
+    "[The previous attempt returned no content after compaction. "
+    "Resume immediately from the compacted summary and latest context. "
+    "Either continue the task or make the next tool call now.]"
+)
+
+
+def _compact_recovery_reasoning_effort(effort: str | None) -> str | None:
+    """Keep compact recovery calls from spending the whole response budget thinking."""
+    if effort in {None, "none", "minimal", "low"}:
+        return effort
+    return "low"
+
+
+def _append_compact_resume_prompt(messages: list[Message]) -> list[Message]:
+    """Append a lightweight resume prompt after emergency compaction."""
+    if not messages:
+        messages.append(create_user_message(content=_COMPACT_RESUME_PROMPT))
+        return messages
+
+    last = messages[-1]
+    if isinstance(last.content, str) and last.content == _COMPACT_RESUME_PROMPT:
+        return messages
+
+    messages.append(create_user_message(content=_COMPACT_RESUME_PROMPT))
+    return messages
+
+
+async def query_loop(
+    params: QueryParams,
+) -> AsyncGenerator[CoreEvent, None]:
+    """The main agentic turn loop.
+
+    Sends messages to the API, processes streaming response, executes
+    tool calls, and loops until no more tool calls are made.
+    """
+    # Work on a private deep copy so emergency pruning cannot mutate the durable
+    # pre-turn state before a successful checkpoint/turn is committed. Keep the
+    # caller-owned projection list itself as the single live container: tools
+    # such as Checkpoint/Revert receive that list through ToolContext and must be
+    # able to update the query loop immediately.
+    params.messages[:] = [
+        message.model_copy(deep=True) for message in params.messages
+    ]
+    messages = params.messages
+    params.tool_context.messages = messages
+    turn_count = 0
+    _context_retries = 0
+    _MAX_CONTEXT_RETRIES = 1
+    _compact_resume_retries = 0
+    _MAX_COMPACT_RESUME_RETRIES = 1
+    stream_retry_state = ResponsesStreamRetryState()
+    pending_stream_retry: StreamRetry | None = None
+    _awaiting_compact_resume = False
+    usage_keys = (
+        "input_tokens",
+        "output_tokens",
+        "total_input_tokens",
+        "cache_read_tokens",
+        "cache_write_tokens",
+    )
+    total_usage: dict[str, int] = {"input_tokens": 0, "output_tokens": 0}
+    last_request_usage: dict[str, int] = {key: 0 for key in usage_keys}
+    reported_usage_keys: set[str] = set()
+    reported_total_usage_keys: set[str] = set()
+
+    def _compact_total_usage() -> dict[str, int]:
+        return {
+            key: value
+            for key, value in total_usage.items()
+            if key in {"input_tokens", "output_tokens"}
+            or key in reported_total_usage_keys
+        }
+
+    # Frontends can answer a permission prompt after the turn has already
+    # been interrupted, or can answer several prompts out of order. Keep only
+    # responses for the current model response so a stale approval can never
+    # authorize a later tool call.
+    buffered_permission_responses: dict[str, PermissionResponseEvent] = {}
+
+    def _drain_steering_messages() -> list[Message]:
+        if params.drain_steering_messages is None:
+            return []
+        steering_messages = params.drain_steering_messages()
+        if not steering_messages:
+            return []
+        messages.extend(steering_messages)
+        params.messages[:] = messages
+        params.tool_context.messages = messages
+        return steering_messages
+
+    repaired_tool_calls = _repair_unpaired_tool_calls(messages)
+    if repaired_tool_calls:
+        params.messages[:] = messages
+        params.tool_context.messages = messages
+        logger.warning(
+            "Repaired %d unpaired tool call(s) before the next API request",
+            len(repaired_tool_calls),
+        )
+        yield ErrorEvent(
+            message=(
+                "检测到上一次任务有工具调用未返回结果，已标记为中断并恢复会话。"
+            ),
+            recoverable=True,
+            error_type="history_repaired",
+        )
+        for block, _result in repaired_tool_calls:
+            yield ToolResultEvent(
+                tool_use_id=block.id,
+                tool_name=block.name,
+                result="Tool call was interrupted before a result was produced.",
+                is_error=True,
+                tool_input=block.input,
+            )
+
+    cfg = params.api_config
+    adapter_config = getattr(params.api_adapter, "config", None)
+    effective_model = (
+        (cfg.model if cfg else None)
+        or (getattr(adapter_config, "model", None))
+        or "claude-sonnet-4-20250514"
+    )
+    effective_max_tokens = cfg.max_tokens if cfg else 16384
+    params.tool_context.api_adapter = params.api_adapter
+    params.tool_context.model = effective_model
+    effective_thinking = cfg.thinking_enabled if cfg else True
+    effective_thinking_budget = cfg.thinking_budget if cfg else 10000
+    effective_reasoning_effort = (
+        cfg.reasoning_effort
+        if cfg and cfg.reasoning_effort is not None
+        else getattr(adapter_config, "reasoning_effort", None)
+    )
+    effective_timeout = (
+        cfg.timeout if cfg
+        else getattr(adapter_config, "timeout", 300)
+    )
+    effective_max_retries = max(
+        0,
+        cfg.max_retries if cfg
+        else getattr(adapter_config, "max_retries", 5),
+    )
+    effective_unbounded_connection_retries = bool(
+        cfg.unbounded_connection_retries
+        if cfg
+        else getattr(adapter_config, "unbounded_connection_retries", False)
+    )
+    context_window = params.context_window
+    token_tracker = params.context_token_tracker or ContextTokenTracker()
+    count_available = True
+
+    def _request_config(max_tokens: int) -> ModelConfig:
+        request_thinking = effective_thinking
+        request_thinking_budget = effective_thinking_budget
+        request_reasoning_effort = effective_reasoning_effort
+        if _awaiting_compact_resume:
+            request_reasoning_effort = _compact_recovery_reasoning_effort(
+                request_reasoning_effort
+            )
+            if request_reasoning_effort is None:
+                request_reasoning_effort = "low"
+            if _compact_resume_retries > 0:
+                request_thinking = False
+                request_thinking_budget = 0
+            elif request_thinking:
+                request_thinking_budget = min(
+                    request_thinking_budget,
+                    max(1024, max_tokens // 4),
+                )
+
+        if request_thinking and request_thinking_budget >= max_tokens:
+            request_thinking_budget = max_tokens - 1024
+            if request_thinking_budget < 1024:
+                request_thinking = False
+                request_thinking_budget = 0
+
+        return ModelConfig(
+            model=effective_model,
+            max_tokens=max_tokens,
+            thinking_enabled=request_thinking,
+            thinking_budget=request_thinking_budget,
+            timeout=effective_timeout,
+            context_window=context_window,
+            reasoning_effort=request_reasoning_effort,
+        )
+
+    def _schedule_stream_retry(
+        error_message: str,
+        *,
+        connection_failed: bool = False,
+        retry_after: float | None = None,
+    ) -> StreamRetry | None:
+        # Unfinished thinking and text are discarded before the replay.
+        # Tool calls that already closed stay in the checkpoint and are not
+        # executed a second time, including adapters without response items.
+        if "CERTIFICATE_VERIFY_FAILED" in error_message:
+            return None
+        fallback = getattr(params.api_adapter, "try_switch_fallback_transport", None)
+        allow_unbounded = type(params.api_adapter).__name__ != "BedrockAdapter"
+        return stream_retry_state.schedule(
+            error=error_message,
+            max_retries=effective_max_retries,
+            connection_failed=connection_failed,
+            retry_after=retry_after,
+            unbounded_connection_retries=effective_unbounded_connection_retries,
+            allow_unbounded_connection_retries=allow_unbounded,
+            try_transport_fallback=fallback if callable(fallback) else None,
+        )
+
+    async def _perform_compaction(
+        *,
+        trigger: str,
+    ) -> CompactEvent | None:
+        nonlocal _awaiting_compact_resume, _compact_resume_retries
+
+        old_count = len(messages)
+        source_messages = list(messages)
+        if params.hook_manager:
+            pre = await params.hook_manager.run(
+                "pre_compact",
+                {
+                    "session_id": params.tool_context.session_id,
+                    "trigger": trigger,
+                    "custom_instructions": "",
+                },
+                cwd=params.tool_context.cwd,
+                env=params.tool_context.env,
+            )
+            if pre.blocked:
+                return None
+
+        result = await compact_conversation(
+            messages,
+            api_adapter=params.api_adapter,
+            compact_prompt=params.compact_prompt,
+            context_window=context_window,
+            cwd=params.tool_context.cwd,
+            session_id=params.tool_context.session_id,
+        )
+        if not result:
+            return None
+
+        _append_compact_resume_prompt(result)
+        if estimate_token_count(result) >= estimate_token_count(source_messages):
+            logger.warning(
+                "Compaction plus recovery prompt produced no token savings; "
+                "original context was preserved"
+            )
+            return None
+
+        messages[:] = result
+        token_tracker.reset()
+        _awaiting_compact_resume = True
+        _compact_resume_retries = 0
+        params.tool_context.messages = messages
+
+        if params.hook_manager:
+            await params.hook_manager.run(
+                "post_compact",
+                {
+                    "session_id": params.tool_context.session_id,
+                    "trigger": trigger,
+                    "compact_summary": compact_summary_text(messages[0]),
+                },
+                cwd=params.tool_context.cwd,
+                env=params.tool_context.env,
+            )
+        return CompactEvent(
+            summary=(
+                "Conversation auto-compacted: context approaching limit"
+                if trigger == "auto"
+                else "Emergency compact after provider context overflow"
+            ),
+            messages_before=old_count,
+            messages_after=len(messages),
+            trigger=trigger,
+            source_messages=source_messages,
+            checkpoint_messages=[message.model_copy(deep=True) for message in messages],
+        )
+
+    while True:
+        if pending_stream_retry is not None:
+            retry = pending_stream_retry
+            pending_stream_retry = None
+            logger.warning(
+                "Transient API failure; %s in %.3fs: %s",
+                retry.message,
+                retry.delay_seconds,
+                retry.error,
+            )
+            yield StreamRetryEvent(
+                message=retry.message,
+                error=retry.error,
+                retry_count=retry.retry_count,
+                max_retries=retry.max_retries,
+                delay_seconds=retry.delay_seconds,
+                unbounded=retry.unbounded,
+                transport_fallback=retry.transport_fallback,
+                discarded_text_chars=retry.discarded_text_chars,
+            )
+            if retry.delay_seconds > 0:
+                await asyncio.sleep(retry.delay_seconds)
+            reset_client = getattr(params.api_adapter, "reset_network_client", None)
+            if callable(reset_client) and not retry.transport_fallback:
+                try:
+                    await reset_client()
+                except Exception as exc:
+                    yield ErrorEvent(message=network_error_message(exc, adapter_config), recoverable=True, error_type="network")
+                    return
+
+        turn_count += 1
+        # Tools and permission reviewers must always observe the active
+        # projection, including this turn's results.
+        params.tool_context.messages = messages
+
+        # Follow-up guidance from the user is applied at the same safe
+        # boundary as tool results: immediately before the next model request.
+        # Keeping it out of _run_tools preserves provider requirements that a
+        # complete tool-result batch directly follows its assistant tool call.
+        steering_messages = _drain_steering_messages()
+        if steering_messages:
+            yield SteeringAppliedEvent(count=len(steering_messages))
+
+        # Peer text is injected only at an agent-loop boundary: never while a
+        # tool is executing, but before the next model request. This lets a
+        # session react after a completed tool batch without waiting for the
+        # entire foreground turn to finish.
+        if params.drain_peer_messages is not None:
+            peer_messages = params.drain_peer_messages()
+            for peer_text in peer_messages:
+                messages.append(
+                    create_user_message(content=peer_text, origin="peer-message")
+                )
+            if peer_messages:
+                params.messages[:] = messages
+                params.tool_context.messages = messages
+
+        full_system = _append_system_context(
+            params.system_prompt, params.system_context
+        )
+        messages_for_api = _messages_for_model(messages, params)
+
+        plan_mode_active = _plan_mode_is_active(params)
+        available_tools = [
+            t for t in params.tools
+            if t.is_available(params.tool_context) and (not plan_mode_active or t.is_read_only)
+        ]
+        directory = ""
+        loading_mode = "eager"
+        params.tool_context.tool_catalog = None
+        if params.tool_loading is not None:
+            if params.tool_loading_state is None:
+                params.tool_loading_state = ToolLoadingState()
+            catalog = ToolCatalog(
+                params.tools, params.tool_context, params.tool_loading, params.tool_loading_state,
+                plan_mode=plan_mode_active, on_change=params.on_tools_loaded, pinned=params.pinned_tools,
+            )
+            params.tool_context.tool_catalog = catalog
+            loading_mode = catalog.mode
+            available_tools = catalog.loaded
+            directory = catalog.directory()
+            full_system = _append_system_context(full_system, {
+                "capabilities": directory, "toolInstructions": catalog.instructions(),
+            })
+        tool_schemas = [
+            t.to_api_schema()
+            for t in available_tools
+        ]
+        exposed_names = frozenset(t.name for t in available_tools)
+        prompt_budget = {
+            "source": "estimated",
+            "mode": loading_mode,
+            "system_tokens": estimate_token_count([], system=full_system),
+            "tool_tokens": estimate_token_count([], tools=tool_schemas),
+            "directory_tokens": estimate_token_count([], system=[directory]) if directory else 0,
+            "loaded_tools": len(tool_schemas),
+            "loaded_names": [t.name for t in available_tools],
+            "available_tools": sum(t.is_available(params.tool_context) and (not plan_mode_active or t.is_read_only) for t in params.tools),
+        }
+
+        max_tokens = effective_max_tokens
+
+        compact_limit = compaction_input_limit(
+            context_window, max_tokens,
+            buffer_tokens=params.compact_buffer_tokens,
+            override=params.compact_threshold if params.auto_compact_enabled else None,
+        )
+
+        async def _measure_input(candidate: list[Message]) -> TokenMeasurement:
+            nonlocal count_available
+            count_config = _request_config(max_tokens)
+            snapshot = RequestSnapshot.capture(
+                params.api_adapter, count_config, candidate, full_system, tool_schemas,
+            )
+            measurement = token_tracker.measure(snapshot, candidate, full_system, tool_schemas)
+            # Establish a baseline if none exists, then verify only near the
+            # limit. Ordinary append-only turns reuse usage plus a small delta.
+            needs_count = measurement.source == "estimated" or measurement.tokens >= compact_limit * 0.9
+            counter = getattr(params.api_adapter, "count_input_tokens", None)
+            if measurement.source != "server" and needs_count and count_available and callable(counter):
+                try:
+                    count = await asyncio.wait_for(counter(
+                        candidate, full_system, tool_schemas, count_config,
+                    ), timeout=3.0)
+                    if token_tracker.calibrate(snapshot, count):
+                        return TokenMeasurement(token_tracker.input_tokens, "server")
+                    count_available = False
+                except Exception as exc:
+                    # Cancellation must propagate; counting failures must not.
+                    logger.debug("Input token counting unavailable (%s)", type(exc).__name__)
+                    count_available = False
+            return measurement
+
+        # --- Final-request preflight (system + messages + tool schemas) ---
+        if context_window > 0:
+            measurement = await _measure_input(messages_for_api)
+            estimated = measurement.tokens
+            needs_compaction = params.auto_compact_enabled and estimated > compact_limit
+            if needs_compaction:
+                source_messages = list(messages)
+                pruned_messages = [message.model_copy(deep=True) for message in messages]
+                if _trim_tool_results_to_fit(
+                    pruned_messages,
+                    compact_limit,
+                    system=full_system,
+                    tools=tool_schemas,
+                ):
+                    pruned_for_api = _messages_for_model(pruned_messages, params)
+                    pruned_measurement = await _measure_input(pruned_for_api)
+                    if pruned_measurement.tokens <= compact_limit:
+                        messages[:] = pruned_messages
+                        params.tool_context.messages = messages
+                        messages_for_api = pruned_for_api
+                        measurement = pruned_measurement
+                        estimated = measurement.tokens
+                        needs_compaction = False
+                        logger.warning(
+                            "Pruned oversized tool output; estimated final input is now %d",
+                            estimated,
+                        )
+                        yield CompactEvent(
+                            summary="Oversized historical tool output was pruned",
+                            messages_before=len(source_messages),
+                            messages_after=len(messages),
+                            trigger="auto",
+                            source_messages=source_messages,
+                            checkpoint_messages=[
+                                message.model_copy(deep=True) for message in messages
+                            ],
+                        )
+
+            if needs_compaction:
+                logger.warning(
+                    "Final input count (%d) exceeds compact threshold %d. "
+                    "Attempting auto compact.",
+                    estimated,
+                    compact_limit,
+                )
+                yield StreamModeEvent(mode="compacting")
+                compact_event = await _perform_compaction(
+                    trigger="auto",
+                )
+                if compact_event:
+                    messages_for_api = _messages_for_model(messages, params)
+                    measurement = await _measure_input(messages_for_api)
+                    estimated = measurement.tokens
+                    yield compact_event
+
+            # Always validate input + output. If compaction was disabled or failed,
+            # reduce output rather than knowingly sending an impossible request.
+            available_output = context_window - estimated - 512
+            if available_output < 256:
+                params.messages[:] = messages
+                yield ErrorEvent(
+                    message=(
+                        "The final request does not fit the model context window, and "
+                        "conversation compaction could not free enough space."
+                    ),
+                    recoverable=True,
+                    error_type="context_overflow",
+                )
+                yield TurnCompleteEvent(
+                    reason="context_overflow",
+                    turn_count=turn_count,
+                    usage=_compact_total_usage(),
+                    context_used_tokens=estimated,
+                    context_token_source=measurement.source,
+                    context_window_tokens=context_window,
+                    context_remaining_tokens=max(0, context_window - estimated),
+                    context_used_percent=round(estimated / context_window * 100, 1),
+                )
+                return
+            if max_tokens > available_output:
+                max_tokens = max(256, available_output)
+                logger.warning("Reducing max_tokens to %d to fit final request", max_tokens)
+
+        model_config = _request_config(max_tokens)
+        request_snapshot = RequestSnapshot.capture(
+            params.api_adapter, model_config, messages_for_api, full_system, tool_schemas,
+        )
+        logger.warning(
+            "Sending API request: model=%s, max_tokens=%d, msgs=%d, context_window=%d",
+            effective_model, max_tokens, len(messages_for_api), context_window,
+        )
+
+        last_request_usage = {key: 0 for key in usage_keys}
+        reported_usage_keys = set()
+
+        def _set_request_usage(usage: dict[str, Any]) -> None:
+            """Record this API request's latest usage snapshot.
+
+            Providers can stream usage as partial snapshots, and Anthropic may
+            repeat cumulative fields on message_delta. Keep total_usage in sync
+            by applying only monotonic differences from the prior snapshot.
+            """
+            for key in usage_keys:
+                if key not in usage:
+                    continue
+                value, valid = usage_int_field(usage, key)
+                if not valid:
+                    continue
+                previous = last_request_usage[key]
+                if key in reported_usage_keys and value < previous:
+                    continue
+                last_request_usage[key] = value
+                reported_usage_keys.add(key)
+                reported_total_usage_keys.add(key)
+                total_usage[key] = total_usage.get(key, 0) + value - previous
+            token_tracker.observe_usage(request_snapshot, {
+                key: last_request_usage[key] for key in reported_usage_keys
+            })
+
+        def _turn_complete_event(reason: str, snapshot: list[Message]) -> TurnCompleteEvent:
+            context_messages = _messages_for_model(snapshot, params)
+            context_snapshot = RequestSnapshot.capture(
+                params.api_adapter, model_config, context_messages, full_system, tool_schemas,
+            )
+            measurement = token_tracker.measure(context_snapshot, context_messages, full_system, tool_schemas)
+            context_used = measurement.tokens
+            context_window_tokens = max(0, context_window or 0)
+            context_remaining = (
+                max(context_window_tokens - context_used, 0)
+                if context_window_tokens
+                else 0
+            )
+            context_percent = (
+                round(context_used / context_window_tokens * 100, 1)
+                if context_window_tokens
+                else 0.0
+            )
+            assistant_uuid = next(
+                (
+                    str(message.uuid)
+                    for message in reversed(snapshot)
+                    if getattr(getattr(message, "role", None), "value", getattr(message, "role", None)) == "assistant"
+                ),
+                None,
+            )
+            logger.warning(
+                "Query turn completed: session=%s, model=%s, reason=%s, "
+                "context_tokens=%d, context_source=%s",
+                params.tool_context.session_id, effective_model, reason,
+                context_used, measurement.source,
+            )
+            return TurnCompleteEvent(
+                reason=reason,
+                turn_count=turn_count,
+                usage=_compact_total_usage(),
+                context_used_tokens=context_used,
+                context_token_source=measurement.source,
+                context_window_tokens=context_window_tokens,
+                context_remaining_tokens=context_remaining,
+                context_used_percent=context_percent,
+                assistant_message_uuid=assistant_uuid,
+                prompt_budget=prompt_budget,
+            )
+
+        assistant_content: list[ContentBlock] = []
+        tool_use_blocks: list[ToolUseBlock] = []
+        current_text = ""
+        current_thinking = ""
+        current_tool: dict[str, str] = {}
+        completed_content_count = 0
+        announced_tool_use_ids: set[str] = set()
+        item_aware_stream = bool(
+            getattr(params.api_adapter, "emits_response_item_events", False)
+        )
+        emitted_mode: str = ""
+        _retry_after_compact = False
+        _retry_after_api_error = False
+        _retry_after_completed_items = False
+        provider_stop_reason = ""
+        received_message_stop = False
+        response_outcome = "interrupted"
+
+        def _flush_thinking_block() -> None:
+            nonlocal current_thinking
+            if not current_thinking:
+                return
+            assistant_content.append(ThinkingBlock(thinking=current_thinking))
+            current_thinking = ""
+
+        def _has_response_evidence() -> bool:
+            return bool(
+                current_text
+                or current_thinking
+                or assistant_content
+                or tool_use_blocks
+                or current_tool
+            )
+
+        def _restore_completed_response_items() -> None:
+            """Discard only the unfinished item before replaying the request."""
+            nonlocal current_text, current_thinking, current_tool
+            del assistant_content[completed_content_count:]
+            tool_use_blocks[:] = [
+                block
+                for block in assistant_content
+                if isinstance(block, ToolUseBlock)
+            ]
+            current_text = ""
+            current_thinking = ""
+            current_tool = {}
+
+        def _discarded_response_text_chars() -> int:
+            suffix = sum(
+                len(block.text)
+                for block in assistant_content[completed_content_count:]
+                if isinstance(block, TextBlock)
+            )
+            return suffix + len(current_text)
+
+        yield StreamModeEvent(mode="requesting")
+
+        stream = None
+        try:
+            # Wrap stream with timeout to avoid hanging indefinitely
+            async def _stream_with_timeout():
+                source = tracked_stream_message(
+                    params.api_adapter,
+                    messages=messages_for_api,
+                    system=full_system,
+                    tools=tool_schemas,
+                    config=model_config,
+                    cwd=params.tool_context.cwd,
+                    session_id=params.tool_context.session_id,
+                )
+                try:
+                    async for chunk in source:
+                        yield chunk
+                finally:
+                    await source.aclose()
+
+            stream = _stream_with_timeout()
+            chunk = None
+            while True:
+                try:
+                    chunk = await asyncio.wait_for(
+                        stream.__anext__(),
+                        timeout=model_config.timeout,
+                    )
+                except StopAsyncIteration:
+                    response_outcome = "exhausted"
+                    break
+                except asyncio.TimeoutError:
+                    response_outcome = "timeout"
+                    error_message = (
+                        f"API request timed out after {model_config.timeout}s"
+                    )
+                    retry = _schedule_stream_retry(error_message)
+                    if retry is not None:
+                        retry = replace(
+                            retry,
+                            discarded_text_chars=_discarded_response_text_chars(),
+                        )
+                        pending_stream_retry = retry
+                        turn_count -= 1
+                        if completed_content_count > 0:
+                            _restore_completed_response_items()
+                            _retry_after_completed_items = True
+                        else:
+                            _retry_after_api_error = True
+                        break
+                    yield ErrorEvent(
+                        message=error_message,
+                        recoverable=True,
+                        error_type="network",
+                    )
+                    return
+                if chunk.stop_reason:
+                    provider_stop_reason = chunk.stop_reason
+                if chunk.type == "text":
+                    _flush_thinking_block()
+                    if emitted_mode != "responding":
+                        yield StreamModeEvent(mode="responding")
+                        emitted_mode = "responding"
+                    yield StreamTextEvent(text=chunk.text)
+                    current_text += chunk.text
+
+                elif chunk.type == "thinking":
+                    if emitted_mode != "thinking":
+                        yield StreamModeEvent(mode="thinking")
+                        emitted_mode = "thinking"
+                    yield ThinkingEvent(text=chunk.text)
+                    current_thinking += chunk.text
+
+                elif chunk.type == "tool_use_start":
+                    _flush_thinking_block()
+                    if current_text:
+                        assistant_content.append(TextBlock(text=current_text))
+                        current_text = ""
+                    if emitted_mode != "tool-input":
+                        yield StreamModeEvent(mode="tool-input")
+                        emitted_mode = "tool-input"
+                    current_tool = {
+                        "id": chunk.tool_use_id,
+                        "name": chunk.tool_name,
+                        "input_json": "",
+                    }
+
+                elif chunk.type == "tool_use_delta":
+                    current_tool["input_json"] = current_tool.get("input_json", "") + chunk.tool_input_json
+
+                elif chunk.type == "tool_use_end":
+                    input_json = chunk.tool_input_json or current_tool.get("input_json", "{}")
+                    try:
+                        tool_input = json.loads(input_json)
+                    except json.JSONDecodeError:
+                        tool_input = {}
+
+                    block = ToolUseBlock(
+                        id=chunk.tool_use_id or current_tool.get("id", ""),
+                        name=chunk.tool_name or current_tool.get("name", ""),
+                        input=tool_input,
+                    )
+                    assistant_content.append(block)
+                    tool_use_blocks.append(block)
+
+                    # Function arguments can finish just before their enclosing
+                    # output item. Do not persist or execute the call until the
+                    # item is complete, so a dropped stream cannot run it early.
+                    if (
+                        not item_aware_stream
+                        and _completed_tool_result(messages, block.id) is None
+                    ):
+                        completed_content_count = len(assistant_content)
+                        announced_tool_use_ids.add(block.id)
+                        yield ToolUseEvent(
+                            tool_name=block.name,
+                            tool_input=block.input,
+                            tool_use_id=block.id,
+                        )
+                    current_tool = {}
+
+                elif chunk.type == "response_item_done":
+                    _flush_thinking_block()
+                    if current_text:
+                        assistant_content.append(TextBlock(text=current_text))
+                        current_text = ""
+                    completed_content_count = len(assistant_content)
+                    for block in tool_use_blocks:
+                        if (
+                            block.id in announced_tool_use_ids
+                            or _completed_tool_result(messages, block.id) is not None
+                        ):
+                            continue
+                        announced_tool_use_ids.add(block.id)
+                        yield ToolUseEvent(
+                            tool_name=block.name,
+                            tool_input=block.input,
+                            tool_use_id=block.id,
+                        )
+
+                elif chunk.type == "message_start":
+                    if chunk.usage:
+                        _set_request_usage(chunk.usage)
+
+                elif chunk.type == "message_delta":
+                    if chunk.usage:
+                        _set_request_usage(chunk.usage)
+
+                elif chunk.type == "message_stop":
+                    received_message_stop = True
+                    if chunk.usage:
+                        _set_request_usage(chunk.usage)
+                    _flush_thinking_block()
+                    if current_text:
+                        assistant_content.append(TextBlock(text=current_text))
+                        current_text = ""
+                    completed_content_count = len(assistant_content)
+                    for block in tool_use_blocks:
+                        if (
+                            block.id in announced_tool_use_ids
+                            or _completed_tool_result(messages, block.id) is not None
+                        ):
+                            continue
+                        announced_tool_use_ids.add(block.id)
+                        yield ToolUseEvent(
+                            tool_name=block.name,
+                            tool_input=block.input,
+                            tool_use_id=block.id,
+                        )
+
+                elif chunk.type == "error":
+                    response_outcome = "error"
+                    if _is_request_size_error(chunk.error):
+                        yield _request_size_error_event(chunk.error)
+                        return
+                    has_response_evidence = _has_response_evidence()
+                    is_ctx_err = _is_context_overflow_error(chunk.error)
+                    if (
+                        is_ctx_err
+                        and not has_response_evidence
+                        and _context_retries < _MAX_CONTEXT_RETRIES
+                    ):
+                        _context_retries += 1
+                        parsed_limit = _parse_context_limit_from_error(chunk.error)
+                        if parsed_limit and parsed_limit > 0:
+                            context_window = parsed_limit
+                            logger.info("Parsed context window from error: %d", context_window)
+                        logger.warning(
+                            "Context overflow before output (retry %d/%d), preparing recovery",
+                            _context_retries, _MAX_CONTEXT_RETRIES,
+                        )
+                        yield StreamModeEvent(mode="compacting")
+                        compact_event = await _perform_compaction(trigger="overflow")
+                        if not compact_event:
+                            yield ErrorEvent(
+                                message=chunk.error,
+                                recoverable=True,
+                                error_type="context_overflow",
+                            )
+                            return
+                        yield compact_event
+                        messages_for_api = _messages_for_model(messages, params)
+                        turn_count -= 1
+                        _retry_after_compact = True
+                        break
+                    is_recoverable = (
+                        chunk.retryable
+                        if chunk.retryable is not None
+                        else _is_recoverable_api_error_message(chunk.error)
+                    )
+                    retry = (
+                        _schedule_stream_retry(
+                            chunk.error,
+                            connection_failed=chunk.connection_failed,
+                            retry_after=(
+                                chunk.retry_after
+                                if chunk.retry_after is not None
+                                else _retry_after_seconds_from_message(chunk.error)
+                            ),
+                        )
+                        if is_recoverable
+                        else None
+                    )
+                    if retry is not None:
+                        retry = replace(
+                            retry,
+                            discarded_text_chars=_discarded_response_text_chars(),
+                        )
+                        pending_stream_retry = retry
+                        turn_count -= 1
+                        if completed_content_count > 0:
+                            _restore_completed_response_items()
+                            _retry_after_completed_items = True
+                        else:
+                            _retry_after_api_error = True
+                        break
+                    yield ErrorEvent(
+                        message=chunk.error,
+                        recoverable=is_recoverable,
+                        error_type="network" if is_recoverable else "",
+                    )
+                    return
+
+        except Exception as e:
+            response_outcome = "exception"
+            error_str = _format_exception_message(e)
+            if (
+                _is_connection_api_exception(e)
+                or certificate_failure(e)
+                or any(_is_http_transport_error(item) for item in _iter_exception_chain(e))
+            ):
+                error_str = network_error_message(e, adapter_config)
+            if _is_request_size_error(e):
+                yield _request_size_error_event(error_str)
+                return
+            has_response_evidence = _has_response_evidence()
+            is_context_error = _is_context_overflow_error(error_str)
+            if (
+                is_context_error
+                and not has_response_evidence
+                and _context_retries < _MAX_CONTEXT_RETRIES
+            ):
+                _context_retries += 1
+                parsed_limit = _parse_context_limit_from_error(error_str)
+                if parsed_limit and parsed_limit > 0:
+                    context_window = parsed_limit
+                    logger.info("Parsed context window from error: %d", context_window)
+                logger.warning(
+                    "Context overflow before output (retry %d/%d), preparing recovery",
+                    _context_retries, _MAX_CONTEXT_RETRIES,
+                )
+                yield StreamModeEvent(mode="compacting")
+                compact_event = await _perform_compaction(trigger="overflow")
+                if not compact_event:
+                    yield ErrorEvent(
+                        message=error_str,
+                        recoverable=True,
+                        error_type="context_overflow",
+                    )
+                    return
+                yield compact_event
+                messages_for_api = _messages_for_model(messages, params)
+                turn_count -= 1
+                continue
+            is_network_error = _is_recoverable_api_exception(e)
+            retry = (
+                _schedule_stream_retry(
+                    error_str,
+                    connection_failed=_is_connection_api_exception(e),
+                    retry_after=_retry_after_seconds_from_exception(e),
+                )
+                if is_network_error
+                else None
+            )
+            if retry is not None:
+                retry = replace(
+                    retry,
+                    discarded_text_chars=_discarded_response_text_chars(),
+                )
+                pending_stream_retry = retry
+                turn_count -= 1
+                if completed_content_count > 0:
+                    _restore_completed_response_items()
+                    _retry_after_completed_items = True
+                else:
+                    continue
+            else:
+                if is_network_error or certificate_failure(e):
+                    logger.warning("Query network failure: %s", error_str)
+                else:
+                    logger.exception("Query loop failed")
+                yield ErrorEvent(
+                    message=error_str,
+                    recoverable=is_network_error,
+                    error_type="network" if is_network_error else "",
+                )
+                return
+        finally:
+            if stream is not None:
+                await stream.aclose()
+            # Metadata only: never log prompt text, tool arguments, images,
+            # endpoint credentials or response contents.
+            logger.warning(
+                "API response finished: session=%s, model=%s, outcome=%s, "
+                "stop_reason=%r, terminal_received=%s, completed_blocks=%d, "
+                "tool_calls=%d, retry=%s, input_tokens=%s",
+                params.tool_context.session_id, effective_model, response_outcome,
+                provider_stop_reason, received_message_stop, completed_content_count,
+                len(tool_use_blocks), pending_stream_retry is not None,
+                last_request_usage.get("total_input_tokens")
+                if "total_input_tokens" in reported_usage_keys
+                else last_request_usage.get("input_tokens"),
+            )
+
+        if _retry_after_api_error:
+            continue
+
+        # A completed stream gives the next agent turn a fresh reconnect budget.
+        if not _retry_after_completed_items:
+            stream_retry_state = ResponsesStreamRetryState()
+
+        if _retry_after_compact:
+            continue
+
+        _flush_thinking_block()
+        if current_text:
+            assistant_content.append(TextBlock(text=current_text))
+
+        has_visible_or_actionable_output = any(
+            isinstance(block, (TextBlock, ToolUseBlock))
+            for block in assistant_content
+        )
+        response_limit_error = None
+        if provider_stop_reason in {"max_tokens", "length", "model_context_window_exceeded"}:
+            response_limit_error = ErrorEvent(
+                message=(
+                    f"Model response was cut short ({provider_stop_reason}); it did not finish the task."
+                    if provider_stop_reason == "model_context_window_exceeded"
+                    else (
+                        f"Model response reached the output token limit (max_tokens={max_tokens}, "
+                        f"reason={provider_stop_reason}); the reply is incomplete. "
+                        "Ask the model to continue, or increase the maximum output tokens in model settings."
+                    )
+                ),
+                recoverable=True,
+                error_type=(
+                    "context_overflow" if provider_stop_reason == "model_context_window_exceeded"
+                    else "output_limit"
+                ),
+            )
+
+        if has_visible_or_actionable_output:
+            assistant_usage = {
+                key: last_request_usage[key]
+                for key in reported_usage_keys
+            }
+            assistant_msg = create_assistant_message(
+                content=assistant_content,
+                parent_uuid=messages[-1].uuid if messages else None,
+                reply_to_uuid=params.reply_to_uuid,
+                usage=assistant_usage,
+            )
+            messages.append(assistant_msg)
+            # Keep the caller-owned projection current at each completed model
+            # response. A cancellation during a later tool turn can then
+            # preserve this committed prefix without duplicating its text.
+            params.messages[:] = messages
+            _awaiting_compact_resume = False
+        else:
+            if _retry_after_completed_items:
+                continue
+            if _awaiting_compact_resume and _compact_resume_retries < _MAX_COMPACT_RESUME_RETRIES:
+                _compact_resume_retries += 1
+                logger.warning(
+                    "Empty response after compact, retrying (%d/%d)",
+                    _compact_resume_retries, _MAX_COMPACT_RESUME_RETRIES,
+                )
+                messages.append(
+                    create_user_message(content=_COMPACT_EMPTY_RESPONSE_RETRY_PROMPT)
+                )
+                params.messages[:] = messages
+                turn_count -= 1
+                continue
+            if response_limit_error is not None:
+                yield response_limit_error
+                yield _turn_complete_event(provider_stop_reason, messages)
+                params.messages[:] = messages
+                return
+            logger.warning("Empty response, ending turn (awaiting_resume=%s)", _awaiting_compact_resume)
+            if _awaiting_compact_resume:
+                yield ErrorEvent(
+                    message=(
+                        "Model returned no visible content after emergency compact; "
+                        "the compacted context was preserved."
+                    ),
+                    recoverable=True,
+                    error_type="empty_response",
+                )
+            yield _turn_complete_event("empty_response", messages)
+            params.messages[:] = messages
+            return
+
+        if not tool_use_blocks:
+            # A message can arrive while the model is streaming a text-only
+            # response. Continue this foreground operation instead of ending
+            # it and leaving that guidance stranded for a future prompt.
+            steering_messages = _drain_steering_messages()
+            if steering_messages:
+                yield SteeringAppliedEvent(count=len(steering_messages))
+                continue
+            if _retry_after_completed_items:
+                continue
+            if response_limit_error is not None:
+                yield response_limit_error
+                yield _turn_complete_event(provider_stop_reason, messages)
+                params.messages[:] = messages
+                return
+            yield _turn_complete_event("end_turn", messages)
+            params.messages[:] = messages
+            return
+
+        approved_blocks: list[ToolUseBlock] = []
+        seen_tool_use_ids: set[str] = set()
+
+        for block in tool_use_blocks:
+            if block.id in seen_tool_use_ids:
+                logger.warning(
+                    "Suppressing duplicate tool call in one response: %s",
+                    block.id,
+                )
+                continue
+            seen_tool_use_ids.add(block.id)
+
+            completed_result = _completed_tool_result(messages[:-1], block.id)
+            if completed_result is not None:
+                # A retried prompt includes already executed calls. Providers
+                # can still replay the same call ID; copy its result into the
+                # new protocol position without repeating
+                # the side effect or surfacing a second tool lifecycle in UI.
+                messages.append(
+                    create_tool_result_message(
+                        tool_use_id=block.id,
+                        result=completed_result.content,
+                        is_error=completed_result.is_error,
+                        source_tool_assistant_uuid=assistant_msg.uuid,
+                    )
+                )
+                params.messages[:] = messages
+                logger.warning(
+                    "Reused completed result for replayed tool call: %s",
+                    block.id,
+                )
+                continue
+
+            tool = _find_tool(params.tools, block.name)
+
+            if tool is not None:
+                normalization = _normalize_and_record_tool_input(tool, block)
+                if normalization.error:
+                    result = f"Validation error: {normalization.error}"
+                    msg = create_tool_result_message(
+                        tool_use_id=block.id,
+                        result=result,
+                        is_error=True,
+                        source_tool_assistant_uuid=assistant_msg.uuid,
+                    )
+                    messages.append(msg)
+                    params.messages[:] = messages
+                    yield ToolResultEvent(
+                        tool_use_id=block.id,
+                        tool_name=block.name,
+                        result=result,
+                        is_error=True,
+                        tool_input=block.input,
+                    )
+                    continue
+                if normalization.corrections:
+                    block = block.model_copy(
+                        update={"input": normalization.value},
+                        deep=True,
+                    )
+
+            # Tool-schema filtering is advisory: some providers can replay or
+            # synthesize calls to tools that were not included in this request.
+            # Enforce plan mode again at the final execution boundary, before
+            # permission plumbing or remembered allow rules can approve it.
+            if (
+                tool is not None
+                and _plan_mode_is_active(params)
+                and not tool.is_read_only
+            ):
+                reason = "Plan mode: write operations are not allowed"
+                msg = create_tool_result_message(
+                    tool_use_id=block.id,
+                    result=f"Permission denied: {reason}",
+                    is_error=True,
+                    source_tool_assistant_uuid=assistant_msg.uuid,
+                )
+                messages.append(msg)
+                params.messages[:] = messages
+                yield ToolResultEvent(
+                    tool_use_id=block.id,
+                    tool_name=block.name,
+                    result=f"Permission denied: {reason}",
+                    is_error=True,
+                    tool_input=block.input,
+                )
+                continue
+
+            # Semantic validation must happen before permission checks. Some
+            # tools derive permission targets by parsing their input; treating
+            # a parse failure as DENY makes malformed input look like a user or
+            # filesystem permission failure instead of a validation error.
+            if tool is not None and (block.name not in exposed_names or not tool.is_available(params.tool_context)):
+                result = "Tool is not loaded or is unavailable. Use ToolSearch and wait for the next response before calling it."
+                messages.append(create_tool_result_message(
+                    tool_use_id=block.id, result=result, is_error=True,
+                    source_tool_assistant_uuid=assistant_msg.uuid,
+                ))
+                params.messages[:] = messages
+                yield ToolResultEvent(tool_use_id=block.id, tool_name=block.name,
+                                      result=result, is_error=True, tool_input=block.input)
+                continue
+            if tool is not None:
+                validation_error = await tool.validate_input(block.input)
+                if validation_error:
+                    result = f"Validation error: {validation_error}"
+                    msg = create_tool_result_message(
+                        tool_use_id=block.id,
+                        result=result,
+                        is_error=True,
+                        source_tool_assistant_uuid=assistant_msg.uuid,
+                    )
+                    messages.append(msg)
+                    params.messages[:] = messages
+                    yield ToolResultEvent(
+                        tool_use_id=block.id,
+                        tool_name=block.name,
+                        result=result,
+                        is_error=True,
+                        tool_input=block.input,
+                    )
+                    continue
+
+            if not params.permission_manager or not params.permission_queue:
+                approved_blocks.append(block)
+                continue
+
+            if not tool:
+                approved_blocks.append(block)
+                continue
+
+            effective_block = block.model_copy(deep=True)
+            tool_perm = await tool.check_permissions(
+                effective_block.input,
+                params.tool_context,
+            )
+            if tool_perm.updated_input is not None:
+                effective_block.input = tool_perm.updated_input
+
+            # Tool-specific normalization may expose derived permission targets
+            # (for example, every path embedded in an ApplyPatch payload). Apply
+            # policy rules to that normalized input rather than the model's raw
+            # arguments so path-scoped rules cannot miss multi-file edits.
+            rule_perm = params.permission_manager.check(tool, effective_block.input)
+
+            permission_key = tool_perm.permission_key or tool.get_permission_key(effective_block.input)
+
+            bypass_active = (
+                hasattr(params.permission_manager, "mode")
+                and params.permission_manager.mode == PermissionMode.BYPASS
+            )
+            if bypass_active and tool_perm.behavior == PermissionBehavior.ASK:
+                tool_perm = PermissionResult(
+                    behavior=PermissionBehavior.ALLOW,
+                    updated_input=tool_perm.updated_input,
+                    permission_key=permission_key,
+                )
+
+            merged_perm = _merge_permission_results(
+                rule_perm,
+                PermissionResult(
+                    behavior=tool_perm.behavior,
+                    reason=tool_perm.reason,
+                    updated_input=tool_perm.updated_input,
+                    permission_key=permission_key,
+                ),
+            )
+
+            explicit_allow = params.permission_manager.has_explicit_allow(
+                tool,
+                effective_block.input,
+                permission_key=permission_key,
+            )
+            if (
+                explicit_allow
+                and merged_perm.behavior != PermissionBehavior.DENY
+            ):
+                approved_blocks.append(effective_block)
+                continue
+
+            ai_review_active = (
+                hasattr(params.permission_manager, "mode")
+                and params.permission_manager.mode == PermissionMode.AI_REVIEW
+            )
+            if (
+                ai_review_active
+                and params.ai_reviewer is not None
+                and merged_perm.behavior == PermissionBehavior.ASK
+                and rule_perm.reason is None
+                and tool_perm.behavior != PermissionBehavior.ASK
+            ):
+                merged_perm = await params.ai_reviewer.review(
+                    AiReviewRequest(
+                        tool=tool,
+                        tool_input=effective_block.input,
+                        context=params.tool_context,
+                        permission_key=permission_key,
+                        reason=merged_perm.reason,
+                    )
+                )
+
+            if merged_perm.behavior == PermissionBehavior.DENY:
+                reason = merged_perm.reason or "denied by policy"
+                msg = create_tool_result_message(
+                    tool_use_id=effective_block.id,
+                    result=f"Permission denied: {reason}",
+                    is_error=True,
+                    source_tool_assistant_uuid=assistant_msg.uuid,
+                )
+                messages.append(msg)
+                params.messages[:] = messages
+                yield ToolResultEvent(
+                    tool_use_id=effective_block.id,
+                    tool_name=effective_block.name,
+                    result=f"Permission denied: {reason}",
+                    is_error=True,
+                    tool_input=effective_block.input,
+                )
+            elif merged_perm.behavior == PermissionBehavior.ASK:
+                yield PermissionRequestEvent(
+                    tool_name=effective_block.name,
+                    tool_input=effective_block.input,
+                    tool_use_id=effective_block.id,
+                    reason=merged_perm.reason,
+                    permission_key=permission_key,
+                )
+                response = buffered_permission_responses.pop(effective_block.id, None)
+                if response is None:
+                    expected_ids = {candidate.id for candidate in tool_use_blocks}
+                    try:
+                        while True:
+                            candidate = await params.permission_queue.get()
+                            if not isinstance(candidate, PermissionResponseEvent):
+                                continue
+                            if candidate.agent_id is not None:
+                                continue
+                            if candidate.tool_use_id == effective_block.id:
+                                response = candidate
+                                break
+                            # Preserve an answer for another tool in this same
+                            # assistant response; discard IDs from an older turn.
+                            if candidate.tool_use_id in expected_ids:
+                                buffered_permission_responses[candidate.tool_use_id] = candidate
+                    except (asyncio.CancelledError, GeneratorExit):
+                        interrupted = _append_missing_tool_results(
+                            messages,
+                            tool_use_blocks,
+                            assistant_msg.uuid,
+                        )
+                        if interrupted:
+                            params.messages[:] = messages
+                        raise
+                assert response is not None
+                if response.allowed:
+                    if response.always_allow:
+                        params.permission_manager.add_allow_rule(permission_key)
+                    approved_blocks.append(effective_block)
+                else:
+                    if response.feedback:
+                        denial_msg = (
+                            f"Permission denied by user with feedback: {response.feedback}\n"
+                            "Adjust your approach based on this feedback."
+                        )
+                    else:
+                        denial_msg = (
+                            "Permission denied by user. Do not retry the same "
+                            "tool call. Explain what you wanted to do and ask "
+                            "for guidance."
+                        )
+                    msg = create_tool_result_message(
+                        tool_use_id=effective_block.id,
+                        result=denial_msg,
+                        is_error=True,
+                        source_tool_assistant_uuid=assistant_msg.uuid,
+                    )
+                    messages.append(msg)
+                    params.messages[:] = messages
+                    yield ToolResultEvent(
+                        tool_use_id=effective_block.id,
+                        tool_name=effective_block.name,
+                        result=denial_msg,
+                        is_error=True,
+                        tool_input=effective_block.input,
+                    )
+            else:
+                approved_blocks.append(effective_block)
+
+        if approved_blocks:
+            yield StreamModeEvent(mode="tool-running")
+            should_end_turn_after_tools = False
+            try:
+                async for item in _run_tools(
+                    approved_blocks,
+                    assistant_msg,
+                    params.tools,
+                    params.tool_context,
+                    params.hook_manager,
+                    params.tool_call_timeout,
+                ):
+                    if isinstance(item, tuple):
+                        msgs, event = item
+                        messages.extend(msgs)
+                        params.messages[:] = messages
+                        if event.tool_name == "SwitchMode" and not event.is_error:
+                            should_end_turn_after_tools = True
+                        yield event
+                    else:
+                        # Mid-execution event (e.g. ChoiceRequestEvent)
+                        yield item
+            except (asyncio.CancelledError, GeneratorExit):
+                # A user interrupt or session shutdown can cancel a tool task
+                # after the assistant call was committed but before its result
+                # reached the projection. Close every remaining call so a
+                # later Responses request cannot be rejected for an orphan.
+                interrupted = _append_missing_tool_results(
+                    messages,
+                    approved_blocks,
+                    assistant_msg.uuid,
+                )
+                if interrupted:
+                    params.messages[:] = messages
+                    logger.warning(
+                        "Closed %d tool call(s) after tool execution cancellation",
+                        len(interrupted),
+                    )
+                raise
+
+            if should_end_turn_after_tools:
+                yield _turn_complete_event("mode_switch_requested", messages)
+                params.messages[:] = messages
+                return
+
+        if params.max_turns and turn_count >= params.max_turns:
+            yield _turn_complete_event("max_turns_reached", messages)
+            params.messages[:] = messages
+            return