CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
fix(session): harden lifecycle contracts
xfgong88405b678adf
diff --git a/cubeloop/agent/agent.py b/cubeloop/agent/agent.pyindex 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 = Noneself._steering_queue.clear()self._follow_up_queue.clear()+ self._checkpoint_loaded = Falsedef _outcome_sink(self) -> Callable[[str], None]:def _sink(value: str) -> None:@@ -939,7 +940,11 @@ class Agent(Generic[TMessage]):raise result.error.causeasync 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_idif question_id != pending.question_id:diff --git a/cubeloop/agent/tools.py b/cubeloop/agent/tools.pyindex f945310..b1d1880 100644--- a/cubeloop/agent/tools.py+++ b/cubeloop/agent/tools.py@@ -1,6 +1,7 @@from __future__ import annotationsimport asyncio+import inspectimport jsonimport timefrom 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_resultreturn rewritten, True, Nonediff --git a/cubeloop/session/session.py b/cubeloop/session/session.pyindex 9bcf758..d354a10 100644--- a/cubeloop/session/session.py+++ b/cubeloop/session/session.py@@ -7,7 +7,7 @@ from dataclasses import dataclass, replacefrom typing import TYPE_CHECKING, Anyfrom cubeloop.agent._tool_cycle import ToolCycleViolation, check_tool_cycle-from cubeloop.agent.types import MessageEndEvent+from cubeloop.agent.types import AgentEndEvent, MessageEndEventfrom cubeloop.checkpointer.base import CheckpointDatafrom 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 = Noneself._active_run_id: str | None = Noneself._cancel_requested = False+ self._accepting_input = Falseself._seq = 0+ self._publish_lock = asyncio.Lock()+ self._required_delivery_failure: DeliveryError | None = Noneself._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+ returnself._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_idmetadata["input_mode"] = envelope.mode- metadata.setdefault("steer_id", envelope.input_id)+ metadata["steer_id"] = envelope.input_idmessage = 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_idself._active_run_id = request.run_idself._cancel_requested = False+ self._accepting_input = Trueself._seq = 0self._delivery_errors = []+ self._required_delivery_failure = Noneself._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 = excexcept Exception as exc:caught = exc+ finally:+ self._accepting_input = Falsetry:- 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 = Falseawait 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 += 1envelope = ExecutionEventEnvelope(run_id=self._active_run_id or "",@@ -322,6 +383,7 @@ class ExecutionSession:required_failure = diagnosticself._delivery_errors.extend(errors)if required_failure is not None:+ self._required_delivery_failure = required_failureraise _RequiredConsumerError(f"required consumer {required_failure.consumer} failed: "f"{required_failure.message}"@@ -337,7 +399,9 @@ class ExecutionSession:await valueexcept asyncio.CancelledError:if not item.acknowledged.done():- item.acknowledged.cancel()+ item.acknowledged.set_exception(+ _ConsumerClosedError("consumer task was cancelled")+ )raiseexcept 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.pyindex 4020931..c6d0b3d 100644--- a/cubeloop/session/turn_execution_context.py+++ b/cubeloop/session/turn_execution_context.py@@ -5,7 +5,7 @@ from types import MappingProxyTypefrom typing import Any, Mappingfrom cubeloop.agent.types import AgentTool-from cubeloop.providers.base import Message, Model, ReasoningControl, ToolDefinition+from cubeloop.providers.base import Message, Model, ReasoningControldef _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@classmethoddef 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: FrozenObjecttool: AgentTool@@ -58,8 +72,8 @@ class TurnExecutionContext:turn_id: strrun_id: strattempt_id: str- model: Model- reasoning: ReasoningControl+ model: FrozenObject+ reasoning: FrozenObjectsystem_prompt: strmessages: 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 selfbinding = 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.pyindex 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 Noneassert agent.state.pending_tool_calls == set()assert agent.state.error_message is None+ assert agent._checkpoint_loaded is Falsedef 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 = Trueagent.reset()diff --git a/tests/agent/test_execution_session.py b/tests/agent/test_execution_session.pyindex 0c66484..4a41069 100644--- a/tests/agent/test_execution_session.py+++ b/tests/agent/test_execution_session.py@@ -7,11 +7,14 @@ import pytestfrom cubeloop import Agentfrom cubeloop.checkpointer.base import CheckpointDatafrom cubeloop.checkpointer.memory import MemoryCheckpointer+from cubeloop.hitl.channel import CheckpointedChannel+from cubeloop.hitl.types import ConfirmRequest, HitlRequestfrom cubeloop.providers.base import AssistantMessage, TextContent, UserMessagefrom cubeloop.providers.faux import FauxProviderfrom 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 Noneassert 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.asynciodiff --git a/tests/agent/test_session_events.py b/tests/agent/test_session_events.pyindex a98569b..fe886a4 100644--- a/tests/agent/test_session_events.py+++ b/tests/agent/test_session_events.py@@ -5,9 +5,11 @@ import asyncioimport pytestfrom cubeloop import Agent+from cubeloop.agent.types import AgentStartEvent+from cubeloop.providers.base import UserMessagefrom cubeloop.providers.base import AssistantMessage, TextContentfrom cubeloop.providers.faux import FauxProvider-from cubeloop.session import PromptExecutionRequest+from cubeloop.session import InputEnvelope, PromptExecutionRequestdef _agent() -> Agent:@@ -78,3 +80,81 @@ async def test_final_notification_timeout_preserves_settled_result() -> None:assert len(result.delivery_errors) == 1assert 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.pyindex 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.pyindex 96f31a2..7304dc4 100644--- a/tests/agent/test_turn_execution_context.py+++ b/tests/agent/test_turn_execution_context.py@@ -4,12 +4,16 @@ import pytestfrom pydantic import BaseModelfrom 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, AgentToolResultfrom 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 extendedwith 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 Nonediff --git a/website/docs/guides/middleware/hooks.md b/website/docs/guides/middleware/hooks.mdindex 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 theircapture, while `before_tool_call` still performs current authorization andpolicy 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````pythondiff --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.mdindex 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