Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

fix(session): harden lifecycle contracts

xfgong88405b678adf
diff --git a/cubeloop/agent/agent.py b/cubeloop/agent/agent.py
index 5408ed7..33f27b8 100644
--- a/cubeloop/agent/agent.py
+++ b/cubeloop/agent/agent.py
@@ -367,6 +367,7 @@ class Agent(Generic[TMessage]):
self._state.error_message = None
self._steering_queue.clear()
self._follow_up_queue.clear()
+ self._checkpoint_loaded = False
def _outcome_sink(self) -> Callable[[str], None]:
def _sink(value: str) -> None:
@@ -939,7 +940,11 @@ class Agent(Generic[TMessage]):
raise result.error.cause
async def _execute_respond(
- self, *, question_id: str | None = None, answer: StructuredValue
+ self,
+ *,
+ question_id: str | None = None,
+ answer: StructuredValue,
+ expected_run_id: str | None = None,
) -> None:
from cubeloop.hitl.exceptions import (
HitlNoPendingRequest,
@@ -976,6 +981,15 @@ class Agent(Generic[TMessage]):
if loaded is None:
raise HitlNoPendingRequest("no pending request on this thread")
pending, recovered_run_id = loaded
+ if (
+ recovered_run_id is not None
+ and expected_run_id is not None
+ and recovered_run_id != expected_run_id
+ ):
+ raise ValueError(
+ f"respond run_id={expected_run_id!r} does not match "
+ f"pending run_id={recovered_run_id!r}"
+ )
if question_id is None:
question_id = pending.question_id
if question_id != pending.question_id:
diff --git a/cubeloop/agent/tools.py b/cubeloop/agent/tools.py
index f945310..b1d1880 100644
--- a/cubeloop/agent/tools.py
+++ b/cubeloop/agent/tools.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import asyncio
+import inspect
import json
import time
from dataclasses import dataclass
@@ -184,7 +185,12 @@ async def _resolve_tool_call(
None,
)
if resolved_tool is not None:
- context.turn_execution_context = turn_context.extend(resolved_tool)
+ extended = turn_context.extend(resolved_tool)
+ context.turn_execution_context = extended
+ if context.on_turn_context is not None:
+ callback_result = context.on_turn_context(extended)
+ if inspect.isawaitable(callback_result):
+ await callback_result
return rewritten, True, None
diff --git a/cubeloop/session/session.py b/cubeloop/session/session.py
index 9bcf758..d354a10 100644
--- a/cubeloop/session/session.py
+++ b/cubeloop/session/session.py
@@ -7,7 +7,7 @@ from dataclasses import dataclass, replace
from typing import TYPE_CHECKING, Any
from cubeloop.agent._tool_cycle import ToolCycleViolation, check_tool_cycle
-from cubeloop.agent.types import MessageEndEvent
+from cubeloop.agent.types import AgentEndEvent, MessageEndEvent
from cubeloop.checkpointer.base import CheckpointData
from cubeloop.session.events import (
ExecutionEventEnvelope,
@@ -61,6 +61,10 @@ class _RequiredConsumerError(RuntimeError):
pass
+class _ConsumerClosedError(RuntimeError):
+ pass
+
+
_INPUT_DEDUP_CAPACITY = 4096
@@ -72,7 +76,10 @@ class ExecutionSession:
self._active_attempt_id: str | None = None
self._active_run_id: str | None = None
self._cancel_requested = False
+ self._accepting_input = False
self._seq = 0
+ self._publish_lock = asyncio.Lock()
+ self._required_delivery_failure: DeliveryError | None = None
self._consumers: list[_Consumer] = []
self._input_status: dict[str, InputStatus] = {}
self._delivery_errors: list[DeliveryError] = []
@@ -87,6 +94,15 @@ class ExecutionSession:
return tuple(self._turn_contexts)
def _capture_turn_context(self, context: TurnExecutionContext) -> None:
+ for index in range(len(self._turn_contexts) - 1, -1, -1):
+ existing = self._turn_contexts[index]
+ if (
+ existing.turn_id == context.turn_id
+ and existing.model.id == context.model.id
+ and existing.model.provider_id == context.model.provider_id
+ ):
+ self._turn_contexts[index] = context
+ return
self._turn_contexts.append(context)
@property
@@ -158,8 +174,17 @@ class ExecutionSession:
def submit_input(self, envelope: InputEnvelope) -> InputReceipt:
existing = self._input_status.get(envelope.input_id)
if existing is not None:
- return InputReceipt(input_id=envelope.input_id, status=existing)
- if self._active_attempt_id is None:
+ durability: InputDurability | None = None
+ if existing == "committed":
+ durability = (
+ "checkpoint" if self._has_durable_checkpoint() else "memory"
+ )
+ return InputReceipt(
+ input_id=envelope.input_id,
+ status=existing,
+ durability=durability,
+ )
+ if not self._accepting_input:
return InputReceipt(input_id=envelope.input_id, status="closed")
if len(self._input_status) >= _INPUT_DEDUP_CAPACITY:
return InputReceipt(input_id=envelope.input_id, status="closed")
@@ -167,7 +192,7 @@ class ExecutionSession:
metadata = dict(envelope.message.metadata)
metadata["input_id"] = envelope.input_id
metadata["input_mode"] = envelope.mode
- metadata.setdefault("steer_id", envelope.input_id)
+ metadata["steer_id"] = envelope.input_id
message = envelope.message.model_copy(update={"metadata": metadata})
if envelope.mode == "steer":
self._agent.steer(message)
@@ -207,8 +232,10 @@ class ExecutionSession:
self._active_attempt_id = request.attempt_id
self._active_run_id = request.run_id
self._cancel_requested = False
+ self._accepting_input = True
self._seq = 0
self._delivery_errors = []
+ self._required_delivery_failure = None
self._input_status.clear()
self._turn_contexts.clear()
caught: BaseException | None = None
@@ -221,6 +248,7 @@ class ExecutionSession:
await self._agent._execute_respond(
question_id=request.question_id,
answer=request.answer,
+ expected_run_id=request.run_id,
)
elif isinstance(request, ContinueExecutionRequest):
await self._agent._execute_continue(run_id=request.run_id)
@@ -230,9 +258,26 @@ class ExecutionSession:
caught = exc
except Exception as exc:
caught = exc
+ finally:
+ self._accepting_input = False
try:
- result = await self._settle(request, caught)
+ try:
+ result = await self._settle(request, caught)
+ except Exception as exc:
+ result = ExecutionResult(
+ run_id=request.run_id,
+ attempt_id=request.attempt_id,
+ outcome="failed",
+ error=ExecutionError(
+ kind="finalization",
+ message=str(exc),
+ cause=exc,
+ ),
+ checkpoint_committed=False,
+ history_consistent=False,
+ delivery_errors=tuple(self._delivery_errors),
+ )
final_errors = await self._publish(
ExecutionFinished(result=result), terminal=True
)
@@ -249,6 +294,8 @@ class ExecutionSession:
async def _publish_agent_event(self, event: SessionEvent) -> None:
if self._active_attempt_id is None:
return
+ if isinstance(event, AgentEndEvent):
+ self._accepting_input = False
await self._publish(event, terminal=False)
if not isinstance(event, MessageEndEvent):
return
@@ -273,6 +320,20 @@ class ExecutionSession:
*,
terminal: bool,
) -> list[DeliveryError]:
+ async with self._publish_lock:
+ return await self._publish_serialized(event, terminal=terminal)
+
+ async def _publish_serialized(
+ self,
+ event: SessionEvent,
+ *,
+ terminal: bool,
+ ) -> list[DeliveryError]:
+ if not terminal and self._required_delivery_failure is not None:
+ failure = self._required_delivery_failure
+ raise _RequiredConsumerError(
+ f"required consumer {failure.consumer} failed: {failure.message}"
+ )
self._seq += 1
envelope = ExecutionEventEnvelope(
run_id=self._active_run_id or "",
@@ -322,6 +383,7 @@ class ExecutionSession:
required_failure = diagnostic
self._delivery_errors.extend(errors)
if required_failure is not None:
+ self._required_delivery_failure = required_failure
raise _RequiredConsumerError(
f"required consumer {required_failure.consumer} failed: "
f"{required_failure.message}"
@@ -337,7 +399,9 @@ class ExecutionSession:
await value
except asyncio.CancelledError:
if not item.acknowledged.done():
- item.acknowledged.cancel()
+ item.acknowledged.set_exception(
+ _ConsumerClosedError("consumer task was cancelled")
+ )
raise
except BaseException as exc:
if not item.acknowledged.done():
@@ -417,7 +481,10 @@ class ExecutionSession:
)
error = ExecutionError(kind="execution", message=message)
- checkpoint_committed = outcome in {"completed", "suspended"}
+ checkpoint_committed = self._has_durable_checkpoint() and outcome in {
+ "completed",
+ "suspended",
+ }
return ExecutionResult(
run_id=request.run_id,
attempt_id=request.attempt_id,
diff --git a/cubeloop/session/turn_execution_context.py b/cubeloop/session/turn_execution_context.py
index 4020931..c6d0b3d 100644
--- a/cubeloop/session/turn_execution_context.py
+++ b/cubeloop/session/turn_execution_context.py
@@ -5,7 +5,7 @@ from types import MappingProxyType
from typing import Any, Mapping
from cubeloop.agent.types import AgentTool
-from cubeloop.providers.base import Message, Model, ReasoningControl, ToolDefinition
+from cubeloop.providers.base import Message, Model, ReasoningControl
def _freeze(value: Any) -> Any:
@@ -35,21 +35,35 @@ class MessageView:
content: tuple[FrozenObject, ...]
metadata: Mapping[str, Any]
run_id: str | None
+ _values: Mapping[str, Any]
+
+ def __getattr__(self, name: str) -> Any:
+ try:
+ return self._values[name]
+ except KeyError as exc:
+ raise AttributeError(name) from exc
@classmethod
def capture(cls, message: Message) -> MessageView:
+ values = MappingProxyType(
+ {
+ name: _freeze(getattr(message, name))
+ for name in type(message).model_fields
+ }
+ )
return cls(
- role=message.role,
- content=tuple(_freeze(item) for item in message.content),
- metadata=_freeze(message.metadata),
- run_id=message.run_id,
+ role=values["role"],
+ content=values["content"],
+ metadata=values["metadata"],
+ run_id=values["run_id"],
+ _values=values,
)
@dataclass(frozen=True)
class ToolExecutionBinding:
name: str
- definition: ToolDefinition
+ definition: FrozenObject
tool: AgentTool
@@ -58,8 +72,8 @@ class TurnExecutionContext:
turn_id: str
run_id: str
attempt_id: str
- model: Model
- reasoning: ReasoningControl
+ model: FrozenObject
+ reasoning: FrozenObject
system_prompt: str
messages: tuple[MessageView, ...]
tools: tuple[ToolExecutionBinding, ...]
@@ -83,14 +97,14 @@ class TurnExecutionContext:
turn_id=turn_id,
run_id=run_id,
attempt_id=attempt_id,
- model=model.model_copy(deep=True),
- reasoning=reasoning.model_copy(deep=True),
+ model=_freeze(model),
+ reasoning=_freeze(reasoning),
system_prompt=system_prompt,
messages=tuple(MessageView.capture(message) for message in messages),
tools=tuple(
ToolExecutionBinding(
name=tool.name,
- definition=tool.to_definition().model_copy(deep=True),
+ definition=_freeze(tool.to_definition()),
tool=tool,
)
for tool in tools or []
@@ -111,7 +125,7 @@ class TurnExecutionContext:
return self
binding = ToolExecutionBinding(
name=tool.name,
- definition=tool.to_definition().model_copy(deep=True),
+ definition=_freeze(tool.to_definition()),
tool=tool,
)
return replace(self, tools=(*self.tools, binding))
diff --git a/tests/agent/test_agent.py b/tests/agent/test_agent.py
index 4e407aa..2ca025e 100644
--- a/tests/agent/test_agent.py
+++ b/tests/agent/test_agent.py
@@ -42,6 +42,7 @@ class TestAgentInit:
assert agent.state.streaming_message is None
assert agent.state.pending_tool_calls == set()
assert agent.state.error_message is None
+ assert agent._checkpoint_loaded is False
def test_custom_initial_state(self):
provider = FauxProvider(provider_id="faux")
@@ -418,6 +419,7 @@ class TestAgentReset:
await agent.prompt("hello")
assert len(agent.state.messages) > 0
+ agent._checkpoint_loaded = True
agent.reset()
diff --git a/tests/agent/test_execution_session.py b/tests/agent/test_execution_session.py
index 0c66484..4a41069 100644
--- a/tests/agent/test_execution_session.py
+++ b/tests/agent/test_execution_session.py
@@ -7,11 +7,14 @@ import pytest
from cubeloop import Agent
from cubeloop.checkpointer.base import CheckpointData
from cubeloop.checkpointer.memory import MemoryCheckpointer
+from cubeloop.hitl.channel import CheckpointedChannel
+from cubeloop.hitl.types import ConfirmRequest, HitlRequest
from cubeloop.providers.base import AssistantMessage, TextContent, UserMessage
from cubeloop.providers.faux import FauxProvider
from cubeloop.session import (
ExecutionBusy,
PromptExecutionRequest,
+ RespondExecutionRequest,
)
@@ -41,6 +44,89 @@ async def test_execute_returns_explicit_completed_result() -> None:
assert result.outcome == "completed"
assert result.error is None
assert result.history_consistent is True
+ assert result.checkpoint_committed is False
+
+
+async def test_completed_checkpointed_attempt_reports_committed() -> None:
+ agent = Agent(
+ model=_provider(_answer()).model("faux-model"),
+ checkpointer=MemoryCheckpointer(),
+ thread_id="thread-1",
+ )
+
+ result = await agent.session.execute(
+ PromptExecutionRequest(run_id="run-1", attempt_id="attempt-1", message="hi")
+ )
+
+ assert result.outcome == "completed"
+ assert result.checkpoint_committed is True
+
+
+async def test_settlement_failure_returns_result_and_terminal_event() -> None:
+ class BrokenPendingCheckpointer(MemoryCheckpointer):
+ async def load_pending(self, thread_id: str):
+ del thread_id
+ raise RuntimeError("pending storage unavailable")
+
+ agent = Agent(
+ model=_provider(_answer()).model("faux-model"),
+ checkpointer=BrokenPendingCheckpointer(),
+ thread_id="thread-1",
+ )
+ events = []
+ agent.session.subscribe(lambda event: events.append(event))
+
+ result = await agent.session.execute(
+ PromptExecutionRequest(run_id="run-1", attempt_id="attempt-1", message="hi")
+ )
+
+ assert result.outcome == "failed"
+ assert result.error is not None
+ assert result.error.kind == "finalization"
+ assert "pending storage unavailable" in result.error.message
+ assert result.checkpoint_committed is False
+ finished = [event for event in events if event.event.type == "execution_finished"]
+ assert len(finished) == 1
+ assert finished[0].event.result == result
+
+
+async def test_respond_rejects_request_run_mismatch_before_resume() -> None:
+ checkpointer = MemoryCheckpointer()
+ pending = HitlRequest(
+ question_id="question-1",
+ thread_id="thread-1",
+ payload=ConfirmRequest(prompt="continue?"),
+ created_at=0,
+ )
+ await checkpointer.save_pending_request("thread-1", pending, run_id="run-real")
+ channel = CheckpointedChannel(
+ checkpointer=checkpointer,
+ thread_id="thread-1",
+ run_id="run-real",
+ )
+ agent = Agent(
+ model=_provider(_answer()).model("faux-model"),
+ checkpointer=checkpointer,
+ thread_id="thread-1",
+ channel=channel,
+ )
+
+ result = await agent.session.execute(
+ RespondExecutionRequest(
+ run_id="run-stale",
+ attempt_id="attempt-1",
+ question_id="question-1",
+ answer=True,
+ )
+ )
+
+ assert result.outcome == "failed"
+ assert result.error is not None
+ assert "does not match" in result.error.message
+ assert await checkpointer.load_pending("thread-1") == (pending, "run-real")
@pytest.mark.asyncio
diff --git a/tests/agent/test_session_events.py b/tests/agent/test_session_events.py
index a98569b..fe886a4 100644
--- a/tests/agent/test_session_events.py
+++ b/tests/agent/test_session_events.py
@@ -5,9 +5,11 @@ import asyncio
import pytest
from cubeloop import Agent
+from cubeloop.agent.types import AgentStartEvent
+from cubeloop.providers.base import UserMessage
from cubeloop.providers.base import AssistantMessage, TextContent
from cubeloop.providers.faux import FauxProvider
-from cubeloop.session import PromptExecutionRequest
+from cubeloop.session import InputEnvelope, PromptExecutionRequest
def _agent() -> Agent:
@@ -78,3 +80,81 @@ async def test_final_notification_timeout_preserves_settled_result() -> None:
assert len(result.delivery_errors) == 1
assert result.delivery_errors[0].consumer == "stalled-host"
assert result.delivery_errors[0].reason == "timeout"
+
+
+async def test_input_submitted_from_terminal_listener_is_closed() -> None:
+ agent = _agent()
+ receipts = []
+
+ def terminal_listener(envelope):
+ if envelope.event.type == "execution_finished":
+ receipts.append(
+ agent.session.submit_input(
+ InputEnvelope(
+ input_id="late",
+ message=UserMessage(content=[TextContent(text="too late")]),
+ mode="follow_up",
+ )
+ )
+ )
+
+ agent.session.subscribe(terminal_listener)
+
+ result = await agent.session.execute(
+ PromptExecutionRequest(run_id="run-1", attempt_id="attempt-1", message="hi")
+ )
+
+ assert result.outcome == "completed"
+ assert len(receipts) == 1
+ assert receipts[0].status == "closed"
+
+
+async def test_required_consumer_failure_stops_concurrent_publishers() -> None:
+ agent = _agent()
+
+ async def broken(envelope):
+ del envelope
+ raise RuntimeError("publisher closed")
+
+ agent.session.subscribe(broken, required=True, name="required")
+ first = asyncio.create_task(
+ agent.session._publish(AgentStartEvent(), terminal=False)
+ )
+ await asyncio.sleep(0)
+ second = asyncio.create_task(
+ agent.session._publish(AgentStartEvent(), terminal=False)
+ )
+
+ results = await asyncio.gather(first, second, return_exceptions=True)
+
+ assert all(isinstance(result, RuntimeError) for result in results)
+ assert all("required consumer" in str(result) for result in results)
+
+
+async def test_unsubscribing_running_observer_records_delivery_error() -> None:
+ agent = _agent()
+ entered = asyncio.Event()
+
+ async def waiting(envelope):
+ del envelope
+ entered.set()
+ await asyncio.Future()
+
+ unsubscribe = agent.session.subscribe(waiting, name="observer")
+ task = asyncio.create_task(
+ agent.session.execute(
+ PromptExecutionRequest(run_id="run-1", attempt_id="attempt-1", message="hi")
+ )
+ )
+ await asyncio.wait_for(entered.wait(), timeout=1)
+ unsubscribe()
+
+ result = await task
+
+ assert result.outcome == "completed"
+ assert len(result.delivery_errors) == 1
+ assert result.delivery_errors[0].consumer == "observer"
+ assert result.delivery_errors[0].reason == "error"
diff --git a/tests/agent/test_session_input.py b/tests/agent/test_session_input.py
index 04da686..d3dae19 100644
--- a/tests/agent/test_session_input.py
+++ b/tests/agent/test_session_input.py
@@ -179,3 +179,58 @@ async def test_follow_up_receipt_becomes_committed_in_memory() -> None:
committed = agent.session.cancel_input("follow-up-1")
assert committed.status == "committed"
assert committed.durability == "memory"
+ duplicate = agent.session.submit_input(
+ InputEnvelope(
+ input_id="follow-up-1",
+ message=UserMessage(content=[TextContent(text="duplicate")]),
+ mode="follow_up",
+ )
+ )
+ assert duplicate.status == "committed"
+ assert duplicate.durability == "memory"
+
+
+async def test_session_input_id_overrides_caller_steering_key() -> None:
+ entered = asyncio.Event()
+ release = asyncio.Event()
+
+ async def response(messages, model):
+ del messages, model
+ entered.set()
+ await release.wait()
+ return AssistantMessage(
+ content=[TextContent(text="done")], stop_reason="end_turn"
+ )
+
+ provider = FauxProvider(provider_id="faux")
+ provider.set_responses([response])
+ agent = Agent(model=provider.model("faux-model"))
+ task = asyncio.create_task(
+ agent.session.execute(
+ PromptExecutionRequest(
+ run_id="run-1", attempt_id="attempt-1", message="start"
+ )
+ )
+ )
+ await asyncio.wait_for(entered.wait(), timeout=1)
+
+ receipt = agent.session.submit_input(
+ InputEnvelope(
+ input_id="owned-id",
+ message=UserMessage(
+ content=[TextContent(text="cancel")],
+ metadata={"steer_id": "caller-id"},
+ ),
+ mode="steer",
+ )
+ )
+ assert receipt.status == "queued"
+ assert agent.session.cancel_input("owned-id").status == "cancelled"
+
+ release.set()
+ await task
+ assert not any(
+ message.metadata.get("input_id") == "owned-id"
+ for message in agent.state.messages
+ )
diff --git a/tests/agent/test_turn_execution_context.py b/tests/agent/test_turn_execution_context.py
index 96f31a2..7304dc4 100644
--- a/tests/agent/test_turn_execution_context.py
+++ b/tests/agent/test_turn_execution_context.py
@@ -4,12 +4,16 @@ import pytest
from pydantic import BaseModel
from cubeloop import Agent
-from cubeloop.agent.types import AgentTool, AgentToolResult
+from dataclasses import FrozenInstanceError
+
+from cubeloop.agent.tools import execute_tool_calls
+from cubeloop.agent.types import AgentContext, AgentTool, AgentToolResult
from cubeloop.providers.base import (
AssistantMessage,
ReasoningControl,
TextContent,
ToolCall,
+ ToolResultMessage,
UserMessage,
)
from cubeloop.providers.faux import FauxProvider
@@ -57,6 +61,10 @@ async def test_context_captures_transformed_request_as_immutable_view() -> None:
assert agent.state.messages[0].metadata == {}
with pytest.raises(AttributeError, match="missing"):
_ = transformed.content[0].missing
+ with pytest.raises(FrozenInstanceError):
+ context.model.id = "changed"
+ with pytest.raises(FrozenInstanceError):
+ context.reasoning.mode = "on"
@pytest.mark.asyncio
@@ -163,3 +171,79 @@ def test_turn_context_extension_is_immutable_and_rejects_rebinding() -> None:
assert extended.extend(first) is extended
with pytest.raises(ValueError, match="already binds"):
extended.extend(replacement)
+ with pytest.raises(FrozenInstanceError):
+ extended.tools[0].definition.description = "changed"
+
+
+def test_message_view_preserves_tool_result_request_fields() -> None:
+ provider = FauxProvider(provider_id="faux")
+ context = TurnExecutionContext.capture(
+ turn_id="turn-1",
+ run_id="run-1",
+ attempt_id="attempt-1",
+ model=provider.model("faux-model").spec,
+ reasoning=ReasoningControl(),
+ system_prompt="",
+ messages=[
+ ToolResultMessage(
+ tool_call_id="call-1",
+ tool_name="work",
+ content=[TextContent(text="failed")],
+ details={"code": "denied"},
+ is_error=True,
+ )
+ ],
+ tools=[],
+ )
+
+ message = context.messages[0]
+ assert message.tool_call_id == "call-1"
+ assert message.tool_name == "work"
+ assert message.is_error is True
+ assert message.details["code"] == "denied"
+
+
+async def test_resolved_tool_extension_updates_public_session_context() -> None:
+ async def execute(tool_call_id, args, *, signal=None, on_update=None):
+ del tool_call_id, args, signal, on_update
+ return AgentToolResult(content=[TextContent(text="done")])
+
+ tool = AgentTool(name="work", description="work", parameters=_Args, execute=execute)
+ provider = FauxProvider(provider_id="faux")
+ agent = Agent(model=provider.model("faux-model"))
+ captured = TurnExecutionContext.capture(
+ turn_id="turn-1",
+ run_id="run-1",
+ attempt_id="attempt-1",
+ model=provider.model("faux-model").spec,
+ reasoning=ReasoningControl(),
+ system_prompt="",
+ messages=[],
+ tools=[],
+ )
+ agent.session._capture_turn_context(captured)
+ context = AgentContext(
+ system_prompt="",
+ messages=[],
+ tools=[tool],
+ turn_execution_context=captured,
+ on_turn_context=agent.session._capture_turn_context,
+ )
+
+ async def resolve(call, *, context, signal=None):
+ del context, signal
+ return call.model_copy(update={"name": "work"})
+
+ await execute_tool_calls(
+ context,
+ AssistantMessage(
+ content=[ToolCall(id="call-1", name="alias", arguments={"value": "x"})],
+ stop_reason="tool_use",
+ ),
+ resolve_tool_call=resolve,
+ emit=lambda event: None,
+ )
+
+ assert len(agent.session.turn_contexts) == 1
+ assert agent.session.turn_contexts[0].binding_for("work") is not None
diff --git a/website/docs/guides/middleware/hooks.md b/website/docs/guides/middleware/hooks.md
index fd56a73..dc5c90a 100644
--- a/website/docs/guides/middleware/hooks.md
+++ b/website/docs/guides/middleware/hooks.md
@@ -99,6 +99,12 @@ a new capture under the same turn. Tool calls retain the binding from their
capture, while `before_tool_call` still performs current authorization and
policy checks at execution time.
+The concrete binding is retained in memory for the current execution process.
+CubeLoop does not checkpoint the full `TurnExecutionContext`; after durable
+HITL is resumed in a new process, tools are resolved from that Agent's restored
+catalog. Hosts that deploy tool implementations independently must pin or
+version that catalog across suspended runs.
+
## `resolve_tool_call`
```python
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md
index a8c1dbe..8399fbb 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md
@@ -90,6 +90,11 @@ CubeLoop 会捕获一个只读的 `TurnExecutionContext`。它记录生成本轮
fallback 模型时,会在同一个 turn 下创建一份新快照。工具调用会保留快照中的绑定,
而 `before_tool_call` 仍会在实际执行时按当前状态完成权限和策略检查。
+具体工具绑定只在当前执行进程的内存中保留。CubeLoop 不会把完整的
+`TurnExecutionContext` 写入 checkpoint;持久化 HITL 在新进程中恢复后,会从新
+Agent 恢复出的工具目录中重新解析工具。如果宿主会独立部署不同版本的工具实现,必须在
+挂起的 run 之间固定工具目录,或对它进行版本管理。
+
## `resolve_tool_call`
```python