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

ksadk/conversations/runtime_preparation.py

@@ -49,7 +49,6 @@ from ksadk.conversations.runtime_metadata import (
 )
 from ksadk.conversations.runtime_observability import _latest_deferred_tool_names
 from ksadk.conversations.runtime_payloads import PreparedConversationTurn
-from ksadk.session_context import split_session_context
 from ksadk.conversations.runtime_persistence import (
     append_conversation_event,
     append_run_resume_event,
@@ -57,20 +56,24 @@ from ksadk.conversations.runtime_persistence import (
     ensure_conversation_session,
 )
 from ksadk.conversations.runtime_resume import (
+    ToolReceiptUncertainError,
     _agentengine_resume_metadata,
     _approval_decision_from_resume,
     _approval_resume_run_mode,
+    _claim_approved_builtin_tool_resume,
     _consecutive_approval_denials_from_events,
     _execute_approved_builtin_tool_resume,
     _find_tool_receipt_event_by_key,
     _format_resume_response_text,
-    _has_pending_approval,
     _is_approval_resume_input,
     _is_checkpoint_resume_input,
     _normalize_approval_resume_input,
     _normalize_checkpoint_resume_input,
+    _raise_if_legacy_tool_receipt_checkpoint_ambiguous,
     _tool_receipt_idempotency_key_for_resume,
+    _validate_tool_receipt_event,
 )
+from ksadk.conversations.tool_receipt_resume import _has_pending_approval_for_resume
 from ksadk.ids import new_run_id
 from ksadk.model_policy import model_policy_options_for_model
 from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY, PlatformIdentityContext
@@ -245,13 +248,41 @@ async def build_run_input(
 
         existing_events = await service.get_events(resolved_session_id)
         is_approval_resume = _is_approval_resume_input(normalized_resume_input)
-        existing_tool_receipt_event = None
-        if is_approval_resume and not _has_pending_approval(existing_events):
+        has_pending_approval = _has_pending_approval_for_resume(
+            existing_events, normalized_resume_input
+        )
+        preclaimed_receipt = None
+        replay_candidate = normalized_resume_input
+        if is_approval_resume:
             replay_candidate = _normalize_approval_resume_input(
                 normalized_resume_input,
                 existing_events,
-                include_resolved=True,
+                include_resolved=not has_pending_approval,
             )
+            decision = replay_candidate.get("approval")
+            if not isinstance(decision, Mapping):
+                decision = _approval_decision_from_resume(replay_candidate)
+            if bool(decision.get("approved") or decision.get("approve")):
+                # Do this before persisting approval_response. An unscoped
+                # legacy receipt cannot safely be attributed to an explicit
+                # checkpoint and must never reach replay or builtin execution.
+                receipt_key = _tool_receipt_idempotency_key_for_resume(
+                    session_id=resolved_session_id,
+                    resume_input=replay_candidate,
+                )
+                scoped_receipt_event = (
+                    _find_tool_receipt_event_by_key(existing_events, receipt_key)
+                    if receipt_key
+                    else None
+                )
+                if scoped_receipt_event is None:
+                    _raise_if_legacy_tool_receipt_checkpoint_ambiguous(
+                        session_id=resolved_session_id,
+                        resume_input=replay_candidate,
+                        events=existing_events,
+                    )
+        existing_tool_receipt_event = None
+        if is_approval_resume and not has_pending_approval:
             receipt_key = _tool_receipt_idempotency_key_for_resume(
                 session_id=resolved_session_id,
                 resume_input=replay_candidate,
@@ -261,10 +292,27 @@ async def build_run_input(
                     existing_events,
                     receipt_key,
                 )
+            replay_decision = replay_candidate.get("approval")
+            if not isinstance(replay_decision, Mapping):
+                replay_decision = _approval_decision_from_resume(replay_candidate)
+            replay_is_approved = bool(
+                replay_decision.get("approved") or replay_decision.get("approve")
+            )
             if existing_tool_receipt_event is not None:
+                if replay_is_approved:
+                    # Validate before appending the approval response.  A
+                    # malformed newest receipt must fail closed and must not
+                    # create another approval/tool-result pair.
+                    _validate_tool_receipt_event(existing_tool_receipt_event)
                 normalized_resume_input = replay_candidate
-            else:
+            elif not replay_is_approved:
                 raise ValueError("Responses resume input requires a pending approval_request")
+            else:
+                # A prior request may have consumed approval_response before a
+                # crash left only the durable unknown claim. Discover that
+                # claim before appending another response; unknown never runs
+                # the builtin again and remains available for reconciliation.
+                normalized_resume_input = replay_candidate
         if is_approval_resume:
             normalized_resume_input = _normalize_approval_resume_input(
                 normalized_resume_input,
@@ -280,6 +328,36 @@ async def build_run_input(
                     _consecutive_approval_denials_from_events(existing_events)
                 )
 
+            # A pending approval can still race with a persisted receipt (for
+            # example, after a retry that restored the approval request but
+            # retained its tool-result ledger entry).  Resolve and validate
+            # the newest matching receipt before appending approval_response.
+            # Rejections remain a harmless no-op even if an unrelated old
+            # receipt is malformed, so only approved decisions are replayed.
+            approval_decision = normalized_resume_input.get("approval")
+            if not isinstance(approval_decision, Mapping):
+                approval_decision = _approval_decision_from_resume(normalized_resume_input)
+            approval_is_approved = bool(
+                approval_decision.get("approved") or approval_decision.get("approve")
+            )
+            if approval_is_approved and existing_tool_receipt_event is None:
+                _preclaimed_receipt, preclaimed_claim = (
+                    await _claim_approved_builtin_tool_resume(
+                        session_id=resolved_session_id,
+                        invocation_id=resolved_invocation_id,
+                        resume_input=normalized_resume_input,
+                        session_service_provider=provider,
+                        existing_events=existing_events,
+                        require_existing=not has_pending_approval,
+                    )
+                )
+                if not has_pending_approval and preclaimed_claim is None:
+                    raise ValueError("Responses resume input requires a pending approval_request")
+                if preclaimed_claim is not None and _preclaimed_receipt is not None:
+                    if not preclaimed_claim.acquired and preclaimed_claim.state == "unknown":
+                        raise ToolReceiptUncertainError(preclaimed_claim.idempotency_key)
+                    preclaimed_receipt = (_preclaimed_receipt, preclaimed_claim)
+
         resume_text = _format_resume_response_text(normalized_resume_input)
         resume_event_metadata: dict[str, Any] = {"resume_input": normalized_resume_input}
         if normalized_resume_input.get("call_id"):
@@ -309,6 +387,7 @@ async def build_run_input(
                 resume_input=normalized_resume_input,
                 session_service_provider=provider,
                 existing_events=existing_events,
+                preclaimed_receipt=preclaimed_receipt,
             )
         effective_resume_input = tool_resume_input or normalized_resume_input
         if tool_resume_input is not None:

ksadk/conversations/runtime_projection.py

@@ -0,0 +1,217 @@
+"""Run-local presentation derived exclusively from canonical runtime facts."""
+
+from __future__ import annotations
+
+import json
+from typing import Literal
+
+from ksadk.a2a.presentation import ExecutionScopeDescriptor
+from ksadk.conversations.contracts import ConversationItem
+from ksadk.conversations.projector import project_conversation_item
+from ksadk.events.canonical import (
+    InteractionRequested,
+    InteractionResolved,
+    RunCompleted,
+    RuntimeEvent,
+)
+from ksadk.events.content import DataContent, TextContent, ToolResultContent
+from ksadk.events.reducer import StreamReducer
+
+
+def conversation_identity(run: str, scope: str, item: str) -> str:
+    return json.dumps([run, scope, item], ensure_ascii=False, separators=(",", ":"))
+
+
+class RuntimeConversationProjection:
+    """Replay the prefix before projecting a cursor suffix; never guess child text.
+
+    Instances belong to one run and one negotiated profile. They contain only
+    a derived view, and must be rebuilt from the authoritative event store after
+    a process restart or reconnect.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        profile: Literal["flat-v1", "agent-block-v1"],
+        kernel_interactions: bool = False,
+    ):
+        if profile not in {"flat-v1", "agent-block-v1"}:
+            raise ValueError("unsupported presentation profile")
+        self.session_id, self.profile = session_id, profile
+        self.runtime = StreamReducer()
+        self._parents: dict[str, str] = {}
+        self._descriptors: dict[str, str] = {}
+        self._kernel_interactions = kernel_interactions
+        self._interactions: dict[tuple[str, str], str] = {}
+
+    def _identity(self, event: RuntimeEvent, scope: str, item: str) -> str:
+        if self.profile == "agent-block-v1" or scope in self._parents:
+            return conversation_identity(event.run_id, scope, item)
+        return item
+
+    def apply(self, event: RuntimeEvent) -> ConversationItem | None:
+        if not self.runtime.apply(event).applied:
+            return None
+        if event.parent_scope_id:
+            self._parents[event.scope_id] = event.parent_scope_id
+        if (
+            isinstance(event, (InteractionRequested, InteractionResolved))
+            and event.scope_id in self._parents
+        ):
+            key = (event.run_id, event.interaction_id)
+            previous = self._interactions.get(key)
+            if previous is not None and previous != event.scope_id:
+                raise ValueError("interaction scope changed")
+            self._interactions[key] = event.scope_id
+            if self._kernel_interactions:
+                # The native fact establishes scope, but only the ledger's
+                # revision can authorize a user submission.
+                return None
+        projected = project_conversation_item(event, session_id=self.session_id)
+        view = self.runtime.snapshot()
+        native_item = getattr(event, "item_id", None)
+        item = next(
+            (i for i in view.items if (i.scope_id, i.item_id) == (event.scope_id, native_item)),
+            None,
+        )
+        if (
+            item
+            and event.scope_id in self._parents
+            and item.item_kind == "status"
+            and item.status == "open"
+            and not item.parts
+        ):
+            return None
+        fields = projected.model_dump()
+        if item and event.scope_id in self._parents:
+            if item.item_kind in {"artifact", "tool_call", "tool_result"} and not item.parts:
+                # Native A2A declares identity before the first typed part. Do
+                # not expose an empty artifact/tool with an invented payload.
+                return None
+            if item.item_kind == "artifact" and all(isinstance(p, TextContent) for p in item.parts):
+                # A2A transports ordinary response text as an Artifact. The
+                # canonical kind stays artifact; the presentation renders its
+                # typed text parts instead of dropping them as an unknown file.
+                fields.update(
+                    kind="assistant_text",
+                    payload_schema_ref="conversation.item.assistant_text/v1",
+                    payload={"text": "".join(p.text for p in item.parts)},
+                    operation="completed" if item.status == "completed" else "replace",
+                    lifecycle="completed" if item.status == "completed" else "streaming",
+                )
+        fields["item_id"] = self._identity(event, event.scope_id, projected.item_id)
+        fields["native_ref"].update(scopeId=event.scope_id, runtimeItemId=native_item)
+        if event.scope_id in self._parents:
+            fields["native_ref"]["parentScopeId"] = self._parents[event.scope_id]
+            parent = self._descriptors.get(event.scope_id)
+            if parent:
+                fields["parent_item_id"] = self._identity(event, event.scope_id, parent)
+            if self.profile == "flat-v1" or projected.kind == "reasoning":
+                fields["visibility"] = "hidden"
+        descriptor_data = (
+            next(
+                (
+                    p.data
+                    for p in item.parts
+                    if isinstance(p, DataContent)
+                    and isinstance(p.data, dict)
+                    and p.data.get("schema") == "execution.scope/v1"
+                ),
+                None,
+            )
+            if item
+            else None
+        )
+        if descriptor_data is not None:
+            descriptor = ExecutionScopeDescriptor.model_validate(descriptor_data)
+            self._descriptors[event.scope_id] = item.item_id
+            self._parents[event.scope_id] = descriptor.parent_scope_id
+            if self.profile == "agent-block-v1":
+                terminal = descriptor.status in {"completed", "failed", "cancelled"}
+                fields.update(
+                    kind="agent",
+                    payload_schema_ref="conversation.item.agent/v1",
+                    capability_ref="agent.block",
+                    payload=descriptor.model_dump(mode="json", by_alias=True),
+                    parent_item_id=self._identity(
+                        event, descriptor.trigger_ref.scope_id, descriptor.trigger_ref.item_id
+                    ),
+                    lifecycle="failed"
+                    if descriptor.status == "failed"
+                    else "completed"
+                    if terminal
+                    else "streaming",
+                    operation="completed" if terminal else "replace",
+                )
+            else:
+                fields["visibility"] = "hidden"
+        if item and item.item_kind in {"tool_call", "tool_result"}:
+            result = next((p for p in item.parts if isinstance(p, ToolResultContent)), None)
+            status = (
+                "failed"
+                if item.status == "failed" or (result and result.is_error)
+                else ("completed" if result and item.status == "completed" else "running")
+            )
+            fields["payload"].update(executionStatus=status, sourceKind=item.item_kind)
+        if isinstance(event, RunCompleted) and self.profile == "flat-v1":
+            # Pure delegation must provide explicit root output refs. Preserve
+            # an existing root answer; never aggregate arbitrary child output.
+            root_answer = any(
+                i.scope_id not in self._parents
+                and i.phase == "final_answer"
+                and i.status == "completed"
+                for i in view.items
+            )
+            if (
+                not root_answer
+                and event.output_refs
+                and all(ref.scope_id in self._parents for ref in event.output_refs)
+            ):
+                texts = []
+                for ref in event.output_refs:
+                    target = next(
+                        i
+                        for i in view.items
+                        if (i.scope_id, i.item_id) == (ref.scope_id, ref.item_id)
+                    )
+                    texts.extend(
+                        p.text
+                        for p in target.parts
+                        if isinstance(p, TextContent)
+                        and (ref.part_id is None or p.part_id == ref.part_id)
+                    )
+                fields.update(
+                    item_id=conversation_identity(event.run_id, event.scope_id, "delegated-final"),
+                    kind="assistant_text",
+                    payload_schema_ref="conversation.item.assistant_text/v1",
+                    operation="completed",
+                    lifecycle="completed",
+                    payload={"text": "".join(texts)},
+                )
+        return ConversationItem.model_validate(fields)
+
+    def scope_ledger_item(self, item: ConversationItem) -> ConversationItem:
+        """Attach native child identity to the one actionable ledger projection."""
+        if item.native_ref.get("protocol") != "agent-kernel/interaction-v1":
+            return item
+        interaction_id = item.payload.get("interactionId")
+        scope = self._interactions.get((item.run_id, interaction_id))
+        if scope is None:
+            return item
+        parent = self._descriptors.get(scope)
+        return item.model_copy(
+            update={
+                "item_id": conversation_identity(item.run_id, scope, interaction_id),
+                "parent_item_id": conversation_identity(item.run_id, scope, parent)
+                if parent and self.profile == "agent-block-v1"
+                else None,
+                "native_ref": {
+                    **item.native_ref,
+                    "scopeId": scope,
+                    "parentScopeId": self._parents[scope],
+                    "runtimeItemId": interaction_id,
+                },
+            }
+        )

ksadk/conversations/runtime_resume.py

@@ -6,22 +6,36 @@ import time
 import uuid
 from typing import Any, Callable, Mapping, Sequence
 
-from ksadk.conversations.context import (
-    canonical_event_type,
-)
+from ksadk.conversations.context import canonical_event_type
 from ksadk.conversations.model_options import normalize_model_options
 from ksadk.conversations.run_kinds import (
     RUN_MODE_UNKNOWN,
     validate_run_mode,
 )
 from ksadk.conversations.runtime_persistence import append_conversation_event
+from ksadk.conversations.tool_receipt_resume import (
+    ToolReceiptUncertainError,  # noqa: F401
+    _claim_approved_builtin_tool_resume,  # noqa: F401
+    _pending_approval_events,
+    claim_or_replay_tool_receipt,
+    replay_existing_tool_receipt_event,
+    settle_claimed_tool_receipt,
+)
+from ksadk.conversations.tool_receipts import _validate_tool_receipt_event  # noqa: F401
 from ksadk.events.v1_compat import EventTypeV1 as EventType
-from ksadk.sessions import SessionEvent
-from ksadk.tools.gateway import (
-    build_tool_receipt_idempotency_key,
+from ksadk.sessions import SessionEvent, ToolReceiptClaim
+from ksadk.tools.gateway import build_tool_receipt_idempotency_key
+
+LEGACY_TOOL_RECEIPT_CHECKPOINT_AMBIGUITY_MESSAGE = (
+    "legacy tool receipt checkpoint identity is ambiguous; reconciliation required"
 )
 
 
+class LegacyToolReceiptCheckpointAmbiguityError(ValueError):
+    def __init__(self) -> None:
+        super().__init__(LEGACY_TOOL_RECEIPT_CHECKPOINT_AMBIGUITY_MESSAGE)
+
+
 def _has_pending_approval(events: Sequence[SessionEvent]) -> bool:
     pending = 0
     for event in events:
@@ -41,33 +55,6 @@ def _approval_request_id_from_event(event: SessionEvent) -> str:
     return str(event.id or "")
 
 
-def _pending_approval_events(events: Sequence[SessionEvent]) -> list[SessionEvent]:
-    pending: list[SessionEvent] = []
-    for event in events:
-        event_type = _approval_lifecycle_event_type(event)
-        if event_type == "approval_request":
-            pending.append(event)
-            continue
-        if event_type != "approval_response" or not pending:
-            continue
-        resume_input = (event.metadata or {}).get("resume_input")
-        response_id = ""
-        if isinstance(resume_input, Mapping):
-            response_id = str(
-                resume_input.get("approval_request_id")
-                or resume_input.get("interrupt_id")
-                or resume_input.get("id")
-                or ""
-            )
-        if response_id:
-            pending = [
-                item for item in pending if _approval_request_id_from_event(item) != response_id
-            ]
-        else:
-            pending.pop()
-    return pending
-
-
 def _approval_request_events(events: Sequence[SessionEvent]) -> list[SessionEvent]:
     return [
         event for event in events if _approval_lifecycle_event_type(event) == "approval_request"
@@ -114,10 +101,10 @@ def _approval_interrupt_info_from_event(event: SessionEvent) -> dict[str, Any]:
         if isinstance(request, Mapping):
             raw_detail = request.get("detail")
             detail = dict(raw_detail) if isinstance(raw_detail, Mapping) else {}
-            approval_id = request.get("call_id") or canonical_payload.get("interaction_id")
+            approval_id = canonical_payload.get("interaction_id") or request.get("call_id")
             if approval_id:
-                detail.setdefault("approval_request_id", approval_id)
-                detail.setdefault("id", approval_id)
+                detail["approval_request_id"] = approval_id
+                detail["id"] = approval_id
             if request.get("call_id"):
                 detail.setdefault("run_id", request.get("call_id"))
             return detail
@@ -410,9 +397,11 @@ def _tool_receipt_idempotency_key_for_resume(
     run_id = _tool_resume_run_id(resume_input)
     if not run_id:
         return None
+    checkpoint_id = str(resume_input.get("checkpoint_id") or "").strip() or None
     idempotency_key = build_tool_receipt_idempotency_key(
         session_id=session_id,
         run_id=run_id,
+        checkpoint_id=checkpoint_id,
         tool_call_id=run_id,
         tool_name=tool_name,
         tool_args=dict(tool_args),
@@ -423,6 +412,9 @@ def _tool_receipt_idempotency_key_for_resume(
 def _find_tool_receipt_event_by_key(
     events: Sequence[SessionEvent],
     idempotency_key: str,
+    *,
+    expected_receipt: Mapping[str, Any] | None = None,
+    expected_tool_args: Mapping[str, Any] | None = None,
 ) -> SessionEvent | None:
     for event in reversed(events):
         if event.event_type != "tool_result":
@@ -432,10 +424,68 @@ def _find_tool_receipt_event_by_key(
         if not isinstance(receipt, Mapping):
             continue
         if str(receipt.get("idempotency_key") or "") == idempotency_key:
+            if expected_receipt is not None:
+                for field in ("tool_name", "tool_call_id", "run_id", "checkpoint_id"):
+                    expected = str(expected_receipt.get(field) or "")
+                    actual = str(receipt.get(field) or "")
+                    if expected != actual:
+                        raise ValueError(
+                            f"tool receipt idempotency collision: {field} does not match"
+                        )
+                if expected_tool_args is not None:
+                    actual_args = metadata.get("tool_args")
+                    if not isinstance(actual_args, Mapping) or dict(actual_args) != dict(
+                        expected_tool_args
+                    ):
+                        raise ValueError(
+                            "tool receipt idempotency collision: tool_args do not match"
+                        )
             return event
     return None
 
 
+def _find_legacy_tool_receipt_event_for_resume(
+    *,
+    session_id: str,
+    resume_input: Mapping[str, Any],
+    events: Sequence[SessionEvent],
+) -> SessionEvent | None:
+    tool_name = str(resume_input.get("tool_name") or "").strip()
+    tool_args = resume_input.get("tool_args")
+    run_id = _tool_resume_run_id(resume_input)
+    if not tool_name or not isinstance(tool_args, Mapping) or not run_id:
+        return None
+    legacy_receipt = _tool_receipt_metadata(
+        session_id=session_id,
+        run_id=run_id,
+        tool_name=tool_name,
+        tool_args=dict(tool_args),
+        tool_call_id=run_id,
+    )
+    return _find_tool_receipt_event_by_key(
+        events,
+        legacy_receipt["idempotency_key"],
+        expected_receipt=legacy_receipt,
+        expected_tool_args=tool_args,
+    )
+
+
+def _raise_if_legacy_tool_receipt_checkpoint_ambiguous(
+    *,
+    session_id: str,
+    resume_input: Mapping[str, Any],
+    events: Sequence[SessionEvent],
+) -> None:
+    if not str(resume_input.get("checkpoint_id") or "").strip():
+        return
+    if _find_legacy_tool_receipt_event_for_resume(
+        session_id=session_id,
+        resume_input=resume_input,
+        events=events,
+    ) is not None:
+        raise LegacyToolReceiptCheckpointAmbiguityError()
+
+
 def _latest_checkpoint_metadata_for_run(
     events: Sequence[SessionEvent],
     run_id: str,
@@ -468,15 +518,12 @@ async def _execute_approved_builtin_tool_resume(
     resume_input: Mapping[str, Any],
     session_service_provider: Callable[[], Any],
     existing_events: Sequence[SessionEvent] | None = None,
+    preclaimed_receipt: tuple[dict[str, Any], ToolReceiptClaim] | None = None,
 ) -> dict[str, Any] | None:
     approval = resume_input.get("approval")
     if not isinstance(approval, Mapping) or not bool(approval.get("approved")):
         return None
     tool_name = str(resume_input.get("tool_name") or "").strip()
-    tool_func = _builtin_tool_callable(tool_name)
-    if tool_func is None:
-        return None
-
     tool_args = resume_input.get("tool_args")
     if not isinstance(tool_args, Mapping):
         return None
@@ -486,6 +533,12 @@ async def _execute_approved_builtin_tool_resume(
     if existing_events is None:
         existing_events = await service.get_events(session_id)
     checkpoint_metadata = _latest_checkpoint_metadata_for_run(existing_events, run_id)
+    requested_checkpoint_id = str(resume_input.get("checkpoint_id") or "").strip()
+    if requested_checkpoint_id:
+        checkpoint_metadata = {
+            **checkpoint_metadata,
+            "checkpoint_id": requested_checkpoint_id,
+        }
     receipt = _tool_receipt_metadata(
         session_id=session_id,
         run_id=run_id,
@@ -499,41 +552,51 @@ async def _execute_approved_builtin_tool_resume(
     existing_event = _find_tool_receipt_event_by_key(
         existing_events,
         receipt["idempotency_key"],
+        expected_receipt=receipt,
+        expected_tool_args=call_args,
     )
+    if existing_event is None and requested_checkpoint_id:
+        # Receipts written before checkpoint-scoped keys used an empty
+        # checkpoint field. They cannot be attributed safely to this explicit
+        # checkpoint, so require reconciliation before any replay or tool call.
+        legacy_event = _find_legacy_tool_receipt_event_for_resume(
+            session_id=session_id,
+            resume_input=resume_input,
+            events=existing_events,
+        )
+        if legacy_event is not None:
+            raise LegacyToolReceiptCheckpointAmbiguityError()
     if existing_event is not None:
-        existing_metadata = existing_event.metadata or {}
-        output = existing_metadata.get("tool_output", "")
-        if isinstance(output, Mapping):
-            output = {**dict(output), "replayed": True}
-        replayed_receipt = {
-            **dict((existing_metadata.get("tool_receipt") or receipt)),
-            "replayed": True,
-            "replayed_from_event_id": existing_event.id,
-        }
-        await append_conversation_event(
+        return await replay_existing_tool_receipt_event(
+            existing_event=existing_event,
+            receipt=receipt,
             session_id=session_id,
-            author="tool",
-            role="user",
-            text=str(output),
             invocation_id=invocation_id,
-            event_type="tool_result",
+            run_id=run_id,
+            tool_name=tool_name,
+            call_args=call_args,
+            resume_input=resume_input,
             session_service_provider=session_service_provider,
-            metadata={
-                "tool_name": tool_name,
-                "tool_args": call_args,
-                "tool_output": output,
-                "run_id": run_id,
-                "approval_request_id": resume_input.get("approval_request_id")
-                or resume_input.get("interrupt_id"),
-                "tool_receipt": replayed_receipt,
-                "replayed": True,
-            },
         )
-        return {
-            "type": "function_call_output",
-            "call_id": run_id,
-            "output": output,
-        }
+
+    tool_func = _builtin_tool_callable(tool_name)
+    if tool_func is None:
+        return None
+
+    claim, replayed = await claim_or_replay_tool_receipt(
+        service=service,
+        session_id=session_id,
+        receipt=receipt,
+        tool_name=tool_name,
+        call_args=call_args,
+        invocation_id=invocation_id,
+        preclaimed_receipt=preclaimed_receipt,
+        run_id=run_id,
+        resume_input=resume_input,
+        session_service_provider=session_service_provider,
+    )
+    if replayed is not None:
+        return replayed
 
     try:
         if tool_name in {"run_command", "run_code"}:
@@ -543,7 +606,15 @@ async def _execute_approved_builtin_tool_resume(
     except Exception as exc:
         output = {"ok": False, "error_type": type(exc).__name__, "error_message": str(exc)}
 
-    receipt["status"] = _tool_receipt_status_from_output(output)
+    await settle_claimed_tool_receipt(
+        service=service,
+        claim=claim,
+        receipt=receipt,
+        session_id=session_id,
+        tool_name=tool_name,
+        call_args=call_args,
+        output=output,
+    )
     await append_conversation_event(
         session_id=session_id,
         author="tool",