Skip to content

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

fix(agent): preserve live tool result run ids

Cue2d7b4751d0cf
diff --git a/cubepi/agent/agent.py b/cubepi/agent/agent.py
index b8ac744..99a803b 100644
--- a/cubepi/agent/agent.py
+++ b/cubepi/agent/agent.py
@@ -1196,8 +1196,14 @@ class Agent(Generic[TMessage]):
active = self._state.active_run_id
if active is not None:
if msg.run_id is None:
- msg = msg.model_copy(update={"run_id": active})
- event = event.model_copy(update={"message": msg})
+ if isinstance(msg, AssistantMessage):
+ # The loop retains this provider-owned object for tool
+ # execution and the next model call. Stamp it in place
+ # so tool results can inherit the owning turn's run ID.
+ msg.run_id = active
+ else:
+ msg = msg.model_copy(update={"run_id": active})
+ event = event.model_copy(update={"message": msg})
elif msg.run_id != active:
raise ValueError(
f"message.run_id={msg.run_id!r} does not match "
diff --git a/cubepi/agent/tools.py b/cubepi/agent/tools.py
index 9d7ff1b..cf53662 100644
--- a/cubepi/agent/tools.py
+++ b/cubepi/agent/tools.py
@@ -128,7 +128,9 @@ def _merge_hitl_details(
return {"_non_dict_details": base, "hitl": hitl}
-def _make_tool_result_message(finalized: _FinalizedOutcome) -> ToolResultMessage:
+def _make_tool_result_message(
+ finalized: _FinalizedOutcome, *, run_id: str | None
+) -> ToolResultMessage:
details = _merge_hitl_details(finalized.result.details, finalized.hitl_trace)
return ToolResultMessage(
tool_call_id=finalized.tool_call.id,
@@ -137,6 +139,7 @@ def _make_tool_result_message(finalized: _FinalizedOutcome) -> ToolResultMessage
details=details,
is_error=finalized.is_error,
timestamp=time.time(),
+ run_id=run_id,
)
@@ -534,7 +537,9 @@ async def _execute_sequential(
block_reason=finalized.block_reason,
),
)
- tool_msg = _make_tool_result_message(finalized)
+ tool_msg = _make_tool_result_message(
+ finalized, run_id=assistant_message.run_id
+ )
await emit_event(emit_fn, MessageStartEvent(message=tool_msg))
await emit_event(emit_fn, MessageEndEvent(message=tool_msg))
finalized_list.append(finalized)
@@ -684,7 +689,9 @@ async def _execute_parallel(
if isinstance(s, _FinalizedOutcome)
or (s.done() and not s.cancelled() and s.exception() is None)
]
- await _emit_tool_result_messages(salvaged, emit_fn)
+ await _emit_tool_result_messages(
+ salvaged, emit_fn, run_id=assistant_message.run_id
+ )
except asyncio.CancelledError:
raise
except Exception:
@@ -769,7 +776,9 @@ async def _execute_parallel(
# resume would re-run tools whose side effects already happened.
# A persistence failure propagates instead (consistent with every
# other MessageEndEvent site): the run fails rather than suspends.
- emitted = await _emit_tool_result_messages(finalized_list, emit_fn)
+ emitted = await _emit_tool_result_messages(
+ finalized_list, emit_fn, run_id=assistant_message.run_id
+ )
if isinstance(control_exc, HitlControlException):
# Stateless loop entry points append these to the message
# lists they return, so callers persisting the return value
@@ -777,16 +786,21 @@ async def _execute_parallel(
control_exc.partial_tool_results = tuple(emitted)
raise control_exc
- messages = await _emit_tool_result_messages(finalized_list, emit_fn)
+ messages = await _emit_tool_result_messages(
+ finalized_list, emit_fn, run_id=assistant_message.run_id
+ )
return ToolCallBatch(messages=messages, terminate=_should_terminate(finalized_list))
async def _emit_tool_result_messages(
- finalized_list: list[_FinalizedOutcome], emit_fn: Callable
+ finalized_list: list[_FinalizedOutcome],
+ emit_fn: Callable,
+ *,
+ run_id: str | None,
) -> list[ToolResultMessage]:
messages: list[ToolResultMessage] = []
for finalized in finalized_list:
- tool_msg = _make_tool_result_message(finalized)
+ tool_msg = _make_tool_result_message(finalized, run_id=run_id)
await emit_event(emit_fn, MessageStartEvent(message=tool_msg))
await emit_event(emit_fn, MessageEndEvent(message=tool_msg))
messages.append(tool_msg)
diff --git a/dev/plans/2026-07-31-live-tool-result-run-id.md b/dev/plans/2026-07-31-live-tool-result-run-id.md
new file mode 100644
index 0000000..911452e
--- /dev/null
+++ b/dev/plans/2026-07-31-live-tool-result-run-id.md
@@ -0,0 +1,133 @@
+# Live ToolResult `run_id` Hotfix Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ensure every live `ToolResultMessage` created for a run-aware Agent tool turn carries the owning assistant turn's `run_id` before emission, hooks, live-context append, checkpointing, and the next provider call.
+
+**Architecture:** Keep `execute_tool_calls` public behavior and signatures compatible. Make the current assistant message's `run_id` visible on the live assistant object at the existing Agent message-end stamping seam, then pass that value explicitly through the private tool-result construction/emission boundary. Direct calls with an unstamped assistant continue to produce `run_id=None`; no run ID is inferred from call IDs or other global state during tool-result construction.
+
+**Tech Stack:** Python 3.13, asyncio, Pydantic models, `FauxProvider`, `MemoryCheckpointer`, pytest, Ruff, mypy, uv.
+
+---
+
+### Task 1: Pin the Regression at the Real Agent Boundary
+
+**Files:**
+- Modify: `tests/agent/test_agent_run_id.py`
+
+- [ ] **Step 1: Add a production-shaped Agent/FauxProvider tool-cycle test**
+
+Create an `Agent` with a real `AgentTool`, `MemoryCheckpointer`, and `run_id="R1"`. Queue a tool-call assistant response followed by a Faux response factory. In the second response factory, assert the just-appended `ToolResultMessage.run_id == "R1"`. Capture `should_stop_after_turn` inputs and tool-result message events so the test also verifies the live context, `new_messages`, hook input, emitted message, `Agent.state.messages`, and checkpointed message all carry exactly `"R1"`.
+
+- [ ] **Step 2: Run the production-shaped test and record RED**
+
+Run:
+
+```bash
+uv run pytest tests/agent/test_agent_run_id.py::test_live_tool_results_carry_owning_run_id -vv
+```
+
+Expected on base `94d0ca7380502506042390ce73a02de1060387b0`: FAIL in the second Faux response factory because the live `ToolResultMessage.run_id` is `None`, while the `MemoryCheckpointer` copy is stamped `"R1"`.
+
+### Task 2: Pin Executor Outcome and Compatibility Contracts
+
+**Files:**
+- Modify: `tests/agent/test_tools.py`
+
+- [ ] **Step 1: Add stamped-assistant executor coverage**
+
+Add focused tests that pass an `AssistantMessage(run_id="R-tools")` into `execute_tool_calls` and assert both emitted `MessageStartEvent`/`MessageEndEvent` messages and returned `ToolCallBatch.messages` retain `"R-tools"` for:
+
+- a mixed parallel batch containing success, validation failure, tool-not-found, tool-body error, and `before_tool_call` blocked outcomes;
+- a sequential batch with multiple results.
+
+Also assert message ordering, content/error classification, and tool-call IDs remain unchanged.
+
+- [ ] **Step 2: Add the unstamped legacy control**
+
+Call `execute_tool_calls` directly with an assistant whose `run_id` is `None` and assert every returned and emitted `ToolResultMessage.run_id` remains `None`.
+
+- [ ] **Step 3: Run the focused executor tests and record RED**
+
+Run the new test node IDs with `uv run pytest ... -vv`.
+
+Expected on the pinned base: stamped-assistant assertions FAIL because `_make_tool_result_message` omits `run_id`; the unstamped control PASSes.
+
+### Task 3: Implement the Smallest Construction-Boundary Fix
+
+**Files:**
+- Modify: `cubepi/agent/agent.py`
+- Modify: `cubepi/agent/tools.py`
+
+- [ ] **Step 1: Preserve the owning ID on the live assistant turn**
+
+At `Agent._process_event`'s existing `MessageEndEvent` stamping seam, ensure an unstamped `AssistantMessage` that belongs to the active run is stamped on the same live object before the loop proceeds to `execute_tool_calls`. Preserve the existing mismatch rejection and persistence behavior. Avoid mutating caller-supplied user messages or adding a run ID to stateless/legacy flows.
+
+- [ ] **Step 2: Pass the assistant ID into tool-result construction**
+
+Change the private `_make_tool_result_message` helper to accept `run_id: str | None` and set `ToolResultMessage.run_id`. Pass `assistant_message.run_id` from sequential construction and through `_emit_tool_result_messages` for every parallel, salvage, cancellation, HITL-sibling, immediate, success, and error outcome.
+
+- [ ] **Step 3: Run the new tests GREEN**
+
+Run:
+
+```bash
+uv run pytest tests/agent/test_agent_run_id.py tests/agent/test_tools.py -vv
+```
+
+Expected: all tests PASS, including live provider context, emitted event, hook, multiple-result, outcome-matrix, and unstamped-assistant controls.
+
+### Task 4: Verify Regressions and Quality Gates
+
+**Files:**
+- Verify only; no new production scope.
+
+- [ ] **Step 1: Run focused Agent/tool/run-ID/checkpointer suites**
+
+```bash
+uv run pytest tests/agent/test_agent_run_id.py tests/agent/test_tools.py tests/agent/test_loop.py tests/agent/test_checkpointer_integration.py -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run the full test suite**
+
+```bash
+uv run pytest tests/
+```
+
+Expected: PASS; record exact passed/skipped counts.
+
+- [ ] **Step 3: Run static and formatting checks**
+
+```bash
+uv run ruff check cubepi/ tests/
+uv run ruff format --check cubepi/ tests/
+uv run mypy cubepi
+```
+
+Expected: all PASS; record exact output/counts.
+
+### Task 5: Produce One Local Hotfix Commit and Applicability Report
+
+**Files:**
+- Commit only the plan, focused tests, and minimal source fix.
+
+- [ ] **Step 1: Inspect the final diff**
+
+Verify there are no unrelated refactors, public API changes, Cubemanus changes, release/tag changes, or external publishing actions.
+
+- [ ] **Step 2: Commit once locally**
+
+```bash
+git add dev/plans/2026-07-31-live-tool-result-run-id.md cubepi/agent/agent.py cubepi/agent/tools.py tests/agent/test_agent_run_id.py tests/agent/test_tools.py
+git commit -m "fix(agent): preserve tool result run ids
+
+Co-Authored-By: Claude <[email protected]>"
+```
+
+- [ ] **Step 3: Verify clean worktree and main applicability**
+
+Record the exact commit SHA and changed files. Fetch no remote state unless already available; compare against current `origin/main` and use a temporary, non-publishing applicability check (`git apply --check` against the patch or an isolated temporary worktree) without mutating `main`.
+
+Expected: clean worktree and an explicit clean/conflicting applicability result.
diff --git a/tests/agent/test_agent_run_id.py b/tests/agent/test_agent_run_id.py
index 06ab0e4..e70a2f9 100644
--- a/tests/agent/test_agent_run_id.py
+++ b/tests/agent/test_agent_run_id.py
@@ -70,6 +70,110 @@ async def test_appended_messages_carry_run_id():
assert m.run_id == "R1"
+async def test_live_tool_results_carry_owning_run_id():
+ from pydantic import BaseModel
+
+ from cubepi.agent.types import AgentTool, AgentToolResult
+ from cubepi.checkpointer.memory import MemoryCheckpointer
+ from cubepi.providers.base import ToolResultMessage
+ from cubepi.providers.faux import faux_assistant_message, faux_tool_call
+
+ class EchoParams(BaseModel):
+ value: str
+
+ async def execute(tool_call_id, params, *, signal=None, on_update=None):
+ return AgentToolResult(content=[TextContent(text=params.value)])
+
+ live_provider_run_ids = []
+ hook_snapshots = []
+
+ def finish(messages, model):
+ assistant = next(
+ m
+ for m in reversed(messages)
+ if isinstance(m, AssistantMessage) and m.stop_reason == "tool_use"
+ )
+ tool_result = next(
+ m for m in reversed(messages) if isinstance(m, ToolResultMessage)
+ )
+ live_provider_run_ids.append((assistant.run_id, tool_result.run_id))
+ return faux_assistant_message("done")
+
+ async def should_stop_after_turn(ctx):
+ if ctx.tool_results:
+ hook_snapshots.append(
+ (
+ [m.run_id for m in ctx.tool_results],
+ [
+ m.run_id
+ for m in ctx.context.messages
+ if isinstance(m, ToolResultMessage)
+ ],
+ [
+ m.run_id
+ for m in ctx.new_messages
+ if isinstance(m, ToolResultMessage)
+ ],
+ )
+ )
+ return False
+
+ provider = FauxProvider()
+ provider.set_responses(
+ [
+ faux_assistant_message(
+ faux_tool_call("echo", {"value": "ok"}, id="call-1"),
+ stop_reason="tool_use",
+ ),
+ finish,
+ ]
+ )
+ checkpointer = MemoryCheckpointer()
+ agent = Agent(
+ model=provider.model("faux-model"),
+ tools=[
+ AgentTool(
+ name="echo",
+ description="Echo a value",
+ parameters=EchoParams,
+ execute=execute,
+ )
+ ],
+ checkpointer=checkpointer,
+ thread_id="run-id-tool-cycle",
+ should_stop_after_turn=should_stop_after_turn,
+ )
+ events = []
+ agent.subscribe(lambda event, signal=None: events.append(event))
+
+ await agent.prompt("use the tool", run_id="R1")
+
+ state_tool_result = next(
+ message
+ for message in agent.state.messages
+ if isinstance(message, ToolResultMessage)
+ )
+ checkpoint = await checkpointer.load("run-id-tool-cycle")
+ checkpoint_tool_result = next(
+ message
+ for message in checkpoint.messages
+ if isinstance(message, ToolResultMessage)
+ )
+ assert state_tool_result.run_id == checkpoint_tool_result.run_id == "R1"
+
+ assert live_provider_run_ids == [("R1", "R1")]
+ assert hook_snapshots == [(["R1"], ["R1"], ["R1"])]
+
+ tool_message_events = [
+ event.message
+ for event in events
+ if event.type in ("message_start", "message_end")
+ and isinstance(event.message, ToolResultMessage)
+ ]
+ assert [message.run_id for message in tool_message_events] == ["R1", "R1"]
+
+
@pytest.mark.asyncio
async def test_prompt_rejects_mismatched_run_id_before_claim():
"""Caller pre-stamps a Message with a different run_id than the
diff --git a/tests/agent/test_tools.py b/tests/agent/test_tools.py
index 1bf18f2..052d6f5 100644
--- a/tests/agent/test_tools.py
+++ b/tests/agent/test_tools.py
@@ -36,8 +36,14 @@ def make_echo_tool(
)
-def make_assistant_msg(tool_calls: list[ToolCall]) -> AssistantMessage:
- return AssistantMessage(content=tool_calls, stop_reason="tool_use")
+def make_assistant_msg(
+ tool_calls: list[ToolCall], *, run_id: str | None = None
+) -> AssistantMessage:
+ return AssistantMessage(
+ content=tool_calls,
+ stop_reason="tool_use",
+ run_id=run_id,
+ )
def make_context(tools: list[AgentTool]) -> AgentContext:
@@ -623,6 +629,141 @@ class TestToolEvents:
assert start_idx < end_idx
+class TestToolResultRunId:
+ async def test_parallel_outcomes_inherit_assistant_run_id_before_emission(self):
+ async def fail_execute(tool_call_id, params, *, signal=None, on_update=None):
+ raise RuntimeError("tool failed")
+
+ async def before(before_ctx, *, signal=None):
+ if before_ctx.tool_call.id == "t5":
+ return BeforeToolCallResult(
+ block=True,
+ reason="blocked by policy",
+ hitl_trace={"request_id": "approval-1"},
+ )
+ if before_ctx.tool_call.id == "t6":
+ raise RuntimeError("hook failed")
+ return None
+
+ ctx = make_context(
+ [
+ make_echo_tool(),
+ make_echo_tool(name="fail", execute_fn=fail_execute),
+ ]
+ )
+ msg = make_assistant_msg(
+ [
+ ToolCall(id="t1", name="echo", arguments={"value": "ok"}),
+ ToolCall(id="t2", name="echo", arguments={}),
+ ToolCall(id="t3", name="missing", arguments={}),
+ ToolCall(id="t4", name="fail", arguments={"value": "boom"}),
+ ToolCall(id="t5", name="echo", arguments={"value": "blocked"}),
+ ToolCall(id="t6", name="echo", arguments={"value": "hook"}),
+ ],
+ run_id="R-tools",
+ )
+ events = []
+
+ batch = await execute_tool_calls(
+ ctx,
+ msg,
+ tool_execution="parallel",
+ before_tool_call=before,
+ emit=lambda event: events.append(event),
+ )
+
+ assert [message.tool_call_id for message in batch.messages] == [
+ "t1",
+ "t2",
+ "t3",
+ "t4",
+ "t5",
+ "t6",
+ ]
+ assert [message.run_id for message in batch.messages] == ["R-tools"] * 6
+ assert [message.is_error for message in batch.messages] == [
+ False,
+ True,
+ True,
+ True,
+ True,
+ True,
+ ]
+ by_id = {message.tool_call_id: message for message in batch.messages}
+ assert by_id["t1"].content[0].text == "echoed: ok"
+ assert "field required" in by_id["t2"].content[0].text
+ assert "not found" in by_id["t3"].content[0].text
+ assert "tool failed" in by_id["t4"].content[0].text
+ assert by_id["t5"].content[0].text == "blocked by policy"
+ assert by_id["t5"].details == {"hitl": {"request_id": "approval-1"}}
+ assert by_id["t6"].content[0].text == "hook failed"
+
+ message_events = [
+ event for event in events if event.type in ("message_start", "message_end")
+ ]
+ assert [
+ (event.type, event.message.tool_call_id, event.message.run_id)
+ for event in message_events
+ ] == [
+ (event_type, tool_call_id, "R-tools")
+ for tool_call_id in ("t1", "t2", "t3", "t4", "t5", "t6")
+ for event_type in ("message_start", "message_end")
+ ]
+
+ async def test_sequential_multiple_results_inherit_assistant_run_id(self):
+ ctx = make_context([make_echo_tool()])
+ msg = make_assistant_msg(
+ [
+ ToolCall(id="t1", name="echo", arguments={"value": "first"}),
+ ToolCall(id="t2", name="echo", arguments={"value": "second"}),
+ ],
+ run_id="R-sequential",
+ )
+ events = []
+
+ batch = await execute_tool_calls(
+ ctx,
+ msg,
+ tool_execution="sequential",
+ emit=lambda event: events.append(event),
+ )
+
+ assert [message.run_id for message in batch.messages] == [
+ "R-sequential",
+ "R-sequential",
+ ]
+ message_events = [
+ event for event in events if event.type in ("message_start", "message_end")
+ ]
+ assert [event.message.run_id for event in message_events] == [
+ "R-sequential"
+ ] * 4
+
+ @pytest.mark.parametrize("tool_execution", ["parallel", "sequential"])
+ async def test_unstamped_assistant_does_not_fabricate_run_id(self, tool_execution):
+ ctx = make_context([make_echo_tool()])
+ msg = make_assistant_msg(
+ [
+ ToolCall(id="t1", name="echo", arguments={"value": "first"}),
+ ToolCall(id="t2", name="echo", arguments={"value": "second"}),
+ ]
+ )
+ events = []
+
+ batch = await execute_tool_calls(
+ ctx,
+ msg,
+ tool_execution=tool_execution,
+ emit=lambda event: events.append(event),
+ )
+
+ assert [message.run_id for message in batch.messages] == [None, None]
+ message_events = [
+ event for event in events if event.type in ("message_start", "message_end")
+ ]
+ assert all(event.message.run_id is None for event in message_events)
+
+
class TestToolResultDetails:
async def test_details_propagated_to_tool_result_message(self):
async def execute_with_details(