agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/native/tool_budget.py

@@ -0,0 +1,253 @@
+"""Project the remaining tool budget into model requests and tool batches."""
+
+from __future__ import annotations
+
+import json
+
+from .delivery_review import (
+    REVIEW_INSTRUCTIONS,
+    delivery_review_readers,
+    delivery_review_tool,
+    review_pending,
+)
+from .ports import RunConfiguration, ToolBudget, ToolDefinition
+from .state import CommitBatch, RunPhase, RunSnapshot, move
+from .task_policy import (
+    web_observation_due,
+    web_verification_only,
+)
+from .transitions import commit_transition
+from .turn_control import (
+    EXHAUSTED_INSTRUCTION as _EXHAUSTED_INSTRUCTION,
+)
+from .turn_control import (
+    FINALIZATION_INSTRUCTION as _FINALIZATION_INSTRUCTION,
+)
+from .turn_control import (
+    OBSERVATION_DUE_INSTRUCTION as _OBSERVATION_DUE_INSTRUCTION,
+)
+from .turn_control import (
+    VERIFICATION_INSTRUCTION as _VERIFICATION_INSTRUCTION,
+)
+from .turn_control import (
+    ModelTurnControl,
+)
+
+
+def dispatch_tool_budget(
+    snapshot: RunSnapshot, config: RunConfiguration, *, batch_size: int = 1, index: int = 0
+) -> ToolBudget:
+    """One authoritative net grant for dispatch and interrupted receipt admission."""
+    parallel = batch_size > 1
+    reserve = (max(config.limits.finalization_reserve_model_calls, 1) if parallel
+               else config.limits.finalization_reserve_model_calls)
+    model_slots = max(0, config.limits.max_model_calls - snapshot.model_budget_claimed - reserve)
+    tool_slots = max(0, config.limits.max_tool_calls - snapshot.tool_budget_claimed - batch_size)
+
+    def share(total):
+        return total // batch_size + int(index < total % batch_size)
+
+    return ToolBudget(
+        max_model_calls_remaining=share(model_slots),
+        max_tool_calls_remaining=share(tool_slots),
+        parent_finalization_reserved=parallel or bool(reserve),
+        depth=config.delegation_depth, max_depth=config.limits.max_subagent_depth,
+    )
+
+
+def tools_exhausted(snapshot: RunSnapshot, config: RunConfiguration) -> bool:
+    return snapshot.tool_budget_claimed >= config.limits.max_tool_calls
+
+
+def has_admitted_task_tools(config: RunConfiguration) -> bool:
+    allowed = config.contract.allowed_tool_names
+    return any(allowed is None or tool.name in allowed for tool in config.tools)
+
+
+def task_tool_budget_exhausted(snapshot: RunSnapshot, config: RunConfiguration) -> bool:
+    # A text-only role can deliberately have a zero tool allowance. It has
+    # not consumed a task tool budget and must not enter soft finalization.
+    # The numerical fence remains unconditional at the execution boundary.
+    return has_admitted_task_tools(config) and tools_exhausted(snapshot, config)
+
+
+def finalization_only(snapshot: RunSnapshot, config: RunConfiguration) -> bool:
+    reserve = config.limits.finalization_reserve_model_calls
+    return bool(
+        reserve
+        and config.limits.max_model_calls - snapshot.model_budget_claimed
+        <= reserve
+    )
+
+
+def model_turn_control(snapshot: RunSnapshot, config: RunConfiguration) -> ModelTurnControl | None:
+    if review_pending(snapshot):
+        return None
+    reason = (
+        "task_tools_exhausted"
+        if task_tool_budget_exhausted(snapshot, config)
+        else "model_budget_reserved"
+        if finalization_only(snapshot, config)
+        else "browser_observation_due"
+        if web_observation_due(snapshot, config)
+        else "browser_verification_reserved"
+        if web_verification_only(snapshot, config)
+        else None
+    )
+    return (
+        ModelTurnControl(
+            reason=reason,
+            final_submission_required=config.final_submission_schema is not None,
+            admitted_tool_names=(
+                tuple(tool.name for tool in model_tool_surface(snapshot, config))
+                if reason in {"browser_observation_due", "browser_verification_reserved"}
+                else None
+            ),
+        )
+        if reason
+        else None
+    )
+
+
+def model_tool_surface(
+    snapshot: RunSnapshot, config: RunConfiguration
+) -> tuple[ToolDefinition, ...]:
+    from .final_submission import final_submission_tool
+
+    if review_pending(snapshot):
+        return (*delivery_review_readers(snapshot, config), delivery_review_tool())
+    submission = final_submission_tool(config)
+    if tools_exhausted(snapshot, config) or finalization_only(snapshot, config):
+        task_tools = ()
+    elif web_observation_due(snapshot, config):
+        task_tools = tuple(tool for tool in config.tools if tool.observation_role == "browser")
+    elif web_verification_only(snapshot, config):
+        observed = snapshot.last_browser_observation
+        fresh = (
+            isinstance(observed, dict)
+            and type(observed.get("tool_call")) is int
+            and observed["tool_call"] >= (snapshot.last_web_mutation_tool_call or 0)
+            and snapshot.unresolved_interaction_observation is None
+        )
+        task_tools = tuple(
+            tool
+            for tool in config.tools
+            if tool.observation_role == "browser" or (fresh and tool.read_only)
+        )
+    else:
+        task_tools = config.tools
+    allowed = config.contract.allowed_tool_names
+    if allowed is not None:
+        task_tools = tuple(tool for tool in task_tools if tool.name in allowed)
+    return (*task_tools, submission) if submission is not None else task_tools
+
+
+def model_tool_catalog(
+    snapshot: RunSnapshot, config: RunConfiguration
+) -> tuple[ToolDefinition, ...]:
+    """Keep the task request prefix independent of current execution admission."""
+    if config.profile.tool_catalog_policy != "stable-task/v1" or review_pending(snapshot):
+        return model_tool_surface(snapshot, config)
+    from .final_submission import final_submission_tool
+
+    allowed = config.contract.allowed_tool_names
+    tools = tuple(tool for tool in config.tools if allowed is None or tool.name in allowed)
+    submission = final_submission_tool(config)
+    return (*tools, submission) if submission is not None else tools
+
+
+def model_instructions(snapshot: RunSnapshot, config: RunConfiguration) -> str:
+    if review_pending(snapshot):
+        return REVIEW_INSTRUCTIONS
+    submission_instruction = (
+        "For final delivery, call submit_final_output with arguments matching its schema. "
+        "A plain-text final response cannot satisfy this structured output contract."
+        if config.final_submission_schema is not None
+        else ""
+    )
+    if not task_tool_budget_exhausted(snapshot, config):
+        if not finalization_only(snapshot, config):
+            if web_observation_due(snapshot, config):
+                return "\n\n".join(
+                    part
+                    for part in (
+                        config.instructions,
+                        _OBSERVATION_DUE_INSTRUCTION,
+                        submission_instruction,
+                    )
+                    if part
+                )
+            if web_verification_only(snapshot, config):
+                return "\n\n".join(
+                    part
+                    for part in (
+                        config.instructions,
+                        _VERIFICATION_INSTRUCTION,
+                        submission_instruction,
+                    )
+                    if part
+                )
+            return "\n\n".join(
+                part for part in (config.instructions, submission_instruction) if part
+            )
+        return "\n\n".join(
+            part
+            for part in (config.instructions, _FINALIZATION_INSTRUCTION, submission_instruction)
+            if part
+        )
+    return "\n\n".join(
+        part
+        for part in (config.instructions, _EXHAUSTED_INSTRUCTION, submission_instruction)
+        if part
+    )
+
+
+def refused_pending_tools(
+    snapshot: RunSnapshot,
+    *,
+    reason: str = "tool_budget_exhausted",
+    available_tools: tuple[str, ...] | None = None,
+) -> tuple[dict, ...]:
+    """Pair unexecuted calls with host-authored errors; never debit the tool budget."""
+    return tuple(
+        {
+            "role": "tool",
+            "tool_call_id": call["call_id"],
+            "content": json.dumps(
+                {
+                    "status": "error",
+                    "content": {
+                        "reason": reason,
+                        "executed": False,
+                        **(
+                            {"available_tools": list(available_tools)}
+                            if available_tools is not None
+                            else {}
+                        ),
+                    },
+                },
+                ensure_ascii=False,
+            ),
+        }
+        for call in snapshot.pending_tools
+    )
+
+
+def refuse_pending_batch(snapshot: RunSnapshot) -> CommitBatch:
+    """Commit protocol-paired refusals before the next no-tool model request."""
+    refused = refused_pending_tools(snapshot)
+    updated = move(snapshot, RunPhase.PREPARING_CONTEXT).model_copy(
+        update={
+            "pending_tools": (),
+            "messages": (*snapshot.messages, *refused),
+        }
+    )
+    return commit_transition(
+        snapshot,
+        updated,
+        "budget.exhausted",
+        {
+            "reason": "tool_budget_exhausted",
+            "refused_call_ids": [call["call_id"] for call in snapshot.pending_tools],
+        },
+    )

ksadk/harness/native/tool_error_streak.py

@@ -0,0 +1,89 @@
+"""Host-owned, compaction-proof progress for repeated definite tool errors."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from .ports import ToolDefinition, ToolResult
+from .state import RunSnapshot
+
+REPEATED_ERROR_STOP_THRESHOLD = 6
+
+
+def advance_tool_error_streak(
+    snapshot: RunSnapshot,
+    result: ToolResult,
+    definition: ToolDefinition | None = None,
+) -> dict:
+    """Count model decisions with the same error until goal or workspace changes.
+
+    A successful read, plan update or unrelated tool receipt does not prove
+    that the failing action was repaired. Keep its fingerprint across those
+    receipts; a changed workspace observation resets the next comparison. A
+    single tool batch counts once: the model cannot correct its later calls
+    using results it has not received. Budgets still count every actual call.
+    Independent readonly queries can legitimately return the same generic
+    error. Their admitted inputs distinguish the failing query; this is not
+    successful progress or task acceptance. Writes and browser observations
+    retain their stronger, input-independent failure identity.
+    """
+    signature = snapshot.repeated_tool_error_signature
+    count = snapshot.repeated_tool_error_count
+    model_call = snapshot.repeated_tool_error_model_call
+    if result.status == "error":
+        tool_name = snapshot.pending_tools[0]["name"]
+        if (
+            definition is not None
+            and definition.name == tool_name
+            and definition.observation_role == "browser"
+            and result.progress_observation_digest
+        ):
+            # Only the matching host binding admits the Port's semantic page
+            # identity. Action IDs and artifact locations must not create a
+            # new error; arbitrary tool content cannot supply this authority.
+            payload = [tool_name, result.status, result.progress_observation_digest]
+        else:
+            payload = [
+                tool_name,
+                result.status,
+                result.content,
+                [block.model_dump(mode="json") for block in result.content_blocks],
+            ]
+            if (
+                definition is not None
+                and definition.name == tool_name
+                and definition.read_only
+                and definition.observation_role == "none"
+            ):
+                # Authority belongs to the matching locked host definition,
+                # never an argument or result that claims to be readonly.
+                payload.append(snapshot.pending_tools[0]["arguments"])
+        signature = hashlib.sha256(
+            json.dumps(payload, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode()
+        ).hexdigest()
+        same_observation = (
+            signature == snapshot.repeated_tool_error_signature
+            and snapshot.goal_revision == snapshot.repeated_tool_error_goal_revision
+            and snapshot.workspace_revision == snapshot.repeated_tool_error_workspace_revision
+        )
+        if same_observation:
+            count += int(model_call != snapshot.model_calls)
+        else:
+            count = 1
+        model_call = snapshot.model_calls
+    return {
+        "repeated_tool_error_signature": signature,
+        "repeated_tool_error_count": count,
+        "repeated_tool_error_model_call": model_call,
+        "repeated_tool_error_goal_revision": snapshot.goal_revision,
+        "repeated_tool_error_workspace_revision": snapshot.workspace_revision,
+    }
+
+
+def tool_error_streak_exhausted(snapshot: RunSnapshot) -> bool:
+    return (
+        snapshot.repeated_tool_error_count >= REPEATED_ERROR_STOP_THRESHOLD
+        and snapshot.goal_revision == snapshot.repeated_tool_error_goal_revision
+        and snapshot.workspace_revision == snapshot.repeated_tool_error_workspace_revision
+    )

ksadk/harness/native/tool_hook_runtime.py

@@ -0,0 +1,343 @@
+"""Pure durable tool Hook admission; callbacks never own tools or approval."""
+
+from __future__ import annotations
+
+import json
+
+from pydantic import Field, JsonValue
+
+from .hook_runtime_contract import (
+    HookInvocationRequest,
+    HookInvocationResult,
+    _json_bytes,
+    validate_hook_result,
+)
+from .model import ModelToolCall
+from .ports import RunConfiguration, ToolResult
+from .precompact_hook_runtime import precompact_hook_state
+from .state import Contract, RunPhase, RunSnapshot
+from .stop_hook_runtime import stop_hook_state
+from .tool_budget import refused_pending_tools, tools_exhausted
+from .tool_input_validation import ToolInputValidator
+from .tool_scheduling import scheduled_tool_calls
+from .transitions import finish, prepare_effect
+
+
+class ToolHookCall(Contract):
+    original: ModelToolCall
+    effective: ModelToolCall
+    next_pre_index: int = Field(default=0, strict=True, ge=0)
+    denied: bool = False
+
+
+class PostHookPending(Contract):
+    call: ModelToolCall
+    result: ToolResult
+    next_index: int = Field(default=0, strict=True, ge=0)
+
+
+class ToolHookState(Contract):
+    goal_revision: int = Field(strict=True, ge=0)
+    calls: tuple[ToolHookCall, ...] = ()
+    post: tuple[PostHookPending, ...] = ()
+    feedback: tuple[dict[str, JsonValue], ...] = ()
+
+
+def tool_hook_state(snapshot: RunSnapshot) -> ToolHookState:
+    if snapshot.tool_hook_state is not None:
+        state = ToolHookState.model_validate_json(_json_bytes(snapshot.tool_hook_state))
+        if state.goal_revision == snapshot.goal_revision:
+            return state
+    return ToolHookState(goal_revision=snapshot.goal_revision)
+
+
+def _call_state(state: ToolHookState, call: ModelToolCall) -> ToolHookCall:
+    record = next((item for item in state.calls if item.original.call_id == call.call_id), None)
+    if record is not None and _json_bytes(record.effective.model_dump(mode="json")) != _json_bytes(
+        call.model_dump(mode="json")
+    ):
+        raise ValueError("effective Hook call differs from pending tool")
+    return record or ToolHookCall(original=call, effective=call)
+
+
+def _valid_input(config: RunConfiguration, call: ModelToolCall) -> bool:
+    definition = next((tool for tool in config.tools if tool.name == call.name), None)
+    allowed = config.contract.allowed_tool_names
+    if (
+        definition is None
+        or call.wire_arguments_invalid
+        or (allowed is not None and call.name not in allowed)
+    ):
+        return False
+    try:
+        return ToolInputValidator(definition.parameters).rejection(call.arguments) is None
+    except ValueError:
+        return False
+
+
+def tool_hook_request(
+    snapshot: RunSnapshot, config: RunConfiguration, operation_key: str
+) -> HookInvocationRequest | None:
+    if snapshot.phase != RunPhase.EXECUTING_TOOLS:
+        return None
+    state = tool_hook_state(snapshot)
+    if state.post:
+        pending = state.post[0]
+        hooks = tuple(h for h in config.hooks if h.matches("PostToolUse", pending.call.name))
+        if pending.next_index >= len(hooks):
+            raise ValueError("invalid pending PostToolUse cursor")
+        call, result, event, hook = (
+            pending.call,
+            pending.result.model_dump(mode="json"),
+            "PostToolUse",
+            hooks[pending.next_index],
+        )
+    else:
+        if tools_exhausted(snapshot, config):
+            return None
+        selected = None
+        for raw in scheduled_tool_calls(snapshot, config):
+            current = ModelToolCall.model_validate(raw)
+            record = _call_state(state, current)
+            if record.denied or not _valid_input(config, current):
+                continue  # Invalid original/proposed input never invokes another Hook.
+            hooks = tuple(h for h in config.hooks if h.matches("PreToolUse", current.name))
+            if record.next_pre_index < len(hooks):
+                selected = (current, hooks[record.next_pre_index])
+                break
+        if selected is None:
+            return None
+        call, hook = selected
+        result, event = None, "PreToolUse"
+    return HookInvocationRequest(
+        scope=snapshot.scope,
+        run_id=snapshot.run_id,
+        session_id=snapshot.session_id,
+        turn_id=snapshot.turn_id,
+        operation_key=operation_key,
+        goal=snapshot.goal,
+        goal_revision=snapshot.goal_revision,
+        tool_call_count=snapshot.tool_calls,
+        stop_continuation_count=stop_hook_state(snapshot).continuation_count,
+        event=event,
+        definition=hook,
+        call=call,
+        tool_result=result,
+    )
+
+
+def prepare_tool_hook(snapshot: RunSnapshot, config: RunConfiguration):
+    if not any(event != "Stop" for hook in config.hooks for event in hook.events):
+        return None
+    request = tool_hook_request(
+        snapshot, config, f"{snapshot.run_id}:effect:{snapshot.revision + 1}"
+    )
+    return (
+        prepare_effect(snapshot, "hook", {"request": request.model_dump(mode="json")})
+        if request is not None
+        else None
+    )
+
+
+def close_tool_hook_run(snapshot: RunSnapshot, outcome: str, reason: str) -> RunSnapshot:
+    # These pending tool calls have not been dispatched. Unknown Hook effects
+    # are independent facts and do not authorize replay of either operation.
+    closed = snapshot.model_copy(
+        update={
+            "candidate": None,
+            "messages": (
+                *snapshot.messages,
+                *refused_pending_tools(snapshot, reason=reason),
+            ),
+        }
+    )
+    return finish(closed, outcome, reason)
+
+
+def reduce_tool_hook(
+    snapshot: RunSnapshot, config: RunConfiguration, operation_key: str, raw_result: dict
+) -> RunSnapshot:
+    request = tool_hook_request(snapshot, config, operation_key)
+    if request is None:
+        raise ValueError("tool Hook has no admitted subject")
+    result = validate_hook_result(request, HookInvocationResult.model_validate(raw_result))
+    state = tool_hook_state(snapshot)
+    updated = snapshot.model_copy(update={"pending_intent": None})
+    if result.status == "uncertain" or result.reason == "binding_unavailable":
+        return close_tool_hook_run(updated, "unverified", "effect_outcome_unknown")
+    if result.status == "failed":
+        optional = result.reason in {
+            "producer_failed",
+            "producer_invalid",
+            "producer_timeout",
+            "input_budget_exceeded",
+            "output_budget_exceeded",
+        }
+        if not optional or request.definition.failure_mode != "warn":
+            return close_tool_hook_run(updated, "blocked", "hook_" + result.reason)
+    output = result.output
+    if request.event == "PreToolUse":
+        record = _call_state(state, request.call)
+        record = record.model_copy(update={"next_pre_index": record.next_pre_index + 1})
+        if output is not None:
+            if output.action == "deny":
+                record = record.model_copy(update={"denied": True})
+            elif output.updated_arguments is not None:
+                call = ModelToolCall.model_validate(
+                    {
+                        **record.effective.model_dump(mode="json"),
+                        "arguments": output.updated_arguments,
+                    }
+                )
+                record = record.model_copy(update={"effective": call})
+                # Keep the provider's assistant call untouched. Effective
+                # arguments become the next actual tool request and approval.
+                updated = updated.model_copy(
+                    update={
+                        "pending_tools": tuple(
+                            call.model_dump(mode="json")
+                            if item["call_id"] == call.call_id
+                            else item
+                            for item in updated.pending_tools
+                        ),
+                        "interaction": None,
+                        "interaction_host_id": None,
+                    }
+                )
+        records = tuple(
+            item for item in state.calls if item.original.call_id != request.call.call_id
+        )
+        state = state.model_copy(update={"calls": (*records, record)})
+    else:
+        pending = state.post[0]
+        hooks = tuple(h for h in config.hooks if h.matches("PostToolUse", pending.call.name))
+        state = state.model_copy(
+            update={
+                "post": (
+                    (
+                        pending.model_copy(update={"next_index": pending.next_index + 1}),
+                        *state.post[1:],
+                    )
+                    if pending.next_index + 1 < len(hooks)
+                    else state.post[1:]
+                )
+            }
+        )
+    if output is not None:
+        if not request.definition.read_only:
+            updated = updated.model_copy(update={"workspace_observation_cursor": None})
+        if output.additional_context or output.updated_arguments is not None:
+            data = {
+                "event": request.event,
+                "hook_id": request.definition.hook_id,
+                "source_ref": request.definition.source_ref,
+                "binding_digest": request.definition.binding_digest,
+                "call_id": request.call.call_id,
+                "data": output.additional_context,
+            }
+            if output.updated_arguments is not None:
+                data["effective_arguments"] = output.updated_arguments
+            message = {
+                "role": "user",
+                "kind": "hook_context",
+                "hook_operation_key": operation_key,
+                "hook_goal_revision": snapshot.goal_revision,
+                "content": json.dumps(data, ensure_ascii=False, sort_keys=True),
+            }
+            state = state.model_copy(update={"feedback": (*state.feedback, message)})
+    updated = updated.model_copy(update={"tool_hook_state": state.model_dump(mode="json")})
+    if output is not None and output.action == "deny" and request.event == "PostToolUse":
+        return close_tool_hook_run(updated, "blocked", "post_tool_hook_denied")
+    return updated
+
+
+def tool_hook_denial(snapshot: RunSnapshot, call: ModelToolCall) -> ToolResult | None:
+    record = _call_state(tool_hook_state(snapshot), call)
+    return (
+        ToolResult(status="error", content={"code": "pre_tool_hook_denied", "executed": False})
+        if record.denied
+        else None
+    )
+
+
+def stage_post_hooks(
+    previous: RunSnapshot,
+    updated: RunSnapshot,
+    config: RunConfiguration,
+    calls: tuple[dict, ...],
+    results: tuple[ToolResult, ...],
+) -> RunSnapshot:
+    if (
+        not any("PostToolUse" in hook.events for hook in config.hooks)
+        or updated.phase != RunPhase.EXECUTING_TOOLS
+        or len(calls) != len(results)
+    ):
+        return updated
+    state, pending = tool_hook_state(updated), []
+    for raw, result in zip(calls, results, strict=True):
+        call = ModelToolCall.model_validate(raw)
+        record = _call_state(tool_hook_state(previous), call)
+        if result.status not in {"ok", "error"} or record.denied or not _valid_input(config, call):
+            continue
+        if any(h.matches("PostToolUse", call.name) for h in config.hooks):
+            pending.append(PostHookPending(call=call, result=result))
+    if not pending:
+        return updated
+    state = state.model_copy(update={"post": (*state.post, *pending)})
+    return updated.model_copy(update={"tool_hook_state": state.model_dump(mode="json")})
+
+
+def pending_hook_operation_keys(snapshot: RunSnapshot) -> tuple[str, ...]:
+    return tuple(
+        dict.fromkeys(
+            item["hook_operation_key"]
+            for item in (
+                *stop_hook_state(snapshot).feedback,
+                *tool_hook_state(snapshot).feedback,
+            )
+        )
+    )
+
+
+def consume_hook_feedback(snapshot: RunSnapshot) -> RunSnapshot:
+    """A sealed task response acknowledges input delivery, never task success."""
+    values = {}
+    if snapshot.tool_hook_state is not None:
+        values["tool_hook_state"] = (
+            tool_hook_state(snapshot).model_copy(update={"feedback": ()}).model_dump(mode="json")
+        )
+    if snapshot.stop_hook_state is not None:
+        values["stop_hook_state"] = (
+            stop_hook_state(snapshot).model_copy(update={"feedback": ()}).model_dump(mode="json")
+        )
+    compact = precompact_hook_state(snapshot)
+    if compact is not None and compact.feedback:
+        values["precompact_hook_state"] = (
+            compact.model_copy(update={"feedback": ()}).model_dump(mode="json")
+        )
+    return snapshot.model_copy(update=values)
+
+
+def hook_execution_metadata(snapshot: RunSnapshot) -> dict:
+    call = ModelToolCall.model_validate(snapshot.pending_tools[0])
+    record = _call_state(tool_hook_state(snapshot), call)
+    if _json_bytes(record.original.arguments) == _json_bytes(call.arguments):
+        return {}
+    return {"hook_effective_arguments": call.arguments}
+
+
+def tool_hook_feedback_messages(
+    snapshot: RunSnapshot, messages: tuple[dict, ...]
+) -> tuple[dict, ...]:
+    # Never insert a user frame between an assistant tool batch and its results.
+    if snapshot.pending_tools or tool_hook_state(snapshot).post:
+        return messages
+    seen = {message.get("hook_operation_key") for message in messages}
+    return (
+        *messages,
+        *(
+            item
+            for item in tool_hook_state(snapshot).feedback
+            if item["hook_operation_key"] not in seen
+        ),
+    )