Skip to content

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

fix(deferred): address PR codex review findings

xf gong4b433d07dce7
diff --git a/cubepi/agent/tools.py b/cubepi/agent/tools.py
index e6efb5a..b5c0ca2 100644
--- a/cubepi/agent/tools.py
+++ b/cubepi/agent/tools.py
@@ -372,21 +372,30 @@ async def execute_tool_calls(
) -> ToolCallBatch:
tool_calls = [c for c in assistant_message.content if isinstance(c, ToolCall)]
+ # Resolve up front (in order) so the execution-mode decision below sees
+ # the REAL tool names — a dispatcher call targeting a sequential tool
+ # must route through the sequential executor. Resolution is idempotent,
+ # so hoisting it ahead of execution is safe.
+ resolutions: list[tuple[ToolCall, bool, _ImmediateOutcome | None]] = []
+ for tc in tool_calls:
+ resolutions.append(
+ await _resolve_tool_call(tc, context, resolve_tool_call, signal)
+ )
+
has_sequential = any(
t.execution_mode == "sequential"
- for tc in tool_calls
+ for (rtc, _, _) in resolutions
if context.tools
for t in context.tools
- if t.name == tc.name
+ if t.name == rtc.name
)
if tool_execution == "sequential" or has_sequential:
return await _execute_sequential(
context,
assistant_message,
- tool_calls,
+ resolutions,
before_tool_call,
- resolve_tool_call,
after_tool_call,
signal,
emit,
@@ -394,9 +403,8 @@ async def execute_tool_calls(
return await _execute_parallel(
context,
assistant_message,
- tool_calls,
+ resolutions,
before_tool_call,
- resolve_tool_call,
after_tool_call,
signal,
emit,
@@ -406,9 +414,8 @@ async def execute_tool_calls(
async def _execute_sequential(
context: AgentContext,
assistant_message: AssistantMessage,
- tool_calls: list[ToolCall],
+ resolutions: list[tuple[ToolCall, bool, _ImmediateOutcome | None]],
before_tool_call: Callable | None,
- resolve_tool_call: Callable | None,
after_tool_call: Callable | None,
signal: asyncio.Event | None,
emit_fn: Callable,
@@ -416,11 +423,7 @@ async def _execute_sequential(
finalized_list: list[_FinalizedOutcome] = []
messages: list[ToolResultMessage] = []
- for tc in tool_calls:
- rtc, was_resolved, resolver_error = await _resolve_tool_call(
- tc, context, resolve_tool_call, signal
- )
-
+ for rtc, was_resolved, resolver_error in resolutions:
await emit_event(
emit_fn,
ToolExecutionStartEvent(
@@ -482,9 +485,8 @@ async def _execute_sequential(
async def _execute_parallel(
context: AgentContext,
assistant_message: AssistantMessage,
- tool_calls: list[ToolCall],
+ resolutions: list[tuple[ToolCall, bool, _ImmediateOutcome | None]],
before_tool_call: Callable | None,
- resolve_tool_call: Callable | None,
after_tool_call: Callable | None,
signal: asyncio.Event | None,
emit_fn: Callable,
@@ -499,10 +501,7 @@ async def _execute_parallel(
# End event when prepare later raised, leaving state.pending_tool_calls
# and trace spans permanently open.
entries: list[_FinalizedOutcome | _PreparedToolCall] = []
- for tc in tool_calls:
- rtc, was_resolved, resolver_error = await _resolve_tool_call(
- tc, context, resolve_tool_call, signal
- )
+ for rtc, was_resolved, resolver_error in resolutions:
preparation = resolver_error or await _prepare_tool_call(
context,
assistant_message,
diff --git a/cubepi/deferred/middleware.py b/cubepi/deferred/middleware.py
index f54bb0d..9ed702d 100644
--- a/cubepi/deferred/middleware.py
+++ b/cubepi/deferred/middleware.py
@@ -304,30 +304,60 @@ class DeferredToolsMiddleware(Middleware):
name = args.get("tool_name") if isinstance(args, dict) else None
if not isinstance(name, str) or name not in self._tool_to_group:
return None # falls through to the dispatcher's error fallback
+ inner = args.get("arguments")
+ if inner is None:
+ inner = {}
+ if not isinstance(inner, dict):
+ # Let the dispatcher's own schema validation reject the call —
+ # coercing to {} would silently run no-arg tools on garbage
+ # input.
+ return None
already_loaded = context.tools is not None and any(
t.name == name for t in context.tools
)
if not already_loaded:
- await self._ensure_loaded(self._tool_to_group[name], [name], context)
- inner = args.get("arguments")
- return ToolCall(
- id=tool_call.id,
- name=name,
- arguments=inner if isinstance(inner, dict) else {},
- )
+ error = await self._ensure_loaded(
+ self._tool_to_group[name], [name], context
+ )
+ if error is not None:
+ # The engine converts resolver exceptions into the call's
+ # error result — the model sees WHY the load failed instead
+ # of a misleading "tool not found".
+ raise RuntimeError(error)
+ return ToolCall(id=tool_call.id, name=name, arguments=inner)
async def _ensure_loaded(
self,
group_id: str,
tool_names: list[str],
context: AgentContext,
- ) -> None:
- """Implicit load for dispatched calls: reuse the load path, then drain
- staged tools into the live context immediately (no after_tool_call
- fires on the dispatcher's behalf for a rewritten call)."""
- await self._expand_callback(group_id, tool_names)
+ ) -> str | None:
+ """Ephemeral load for dispatched calls.
+
+ Shares the loader cache and per-group locks (the loader still runs
+ at most once per group per run) but records NO expansion state and
+ never calls ``on_tools_expanded`` — a fork-forwarded resolver must
+ not mutate the parent agent's ``extra`` or tool list. Recording
+ state stays the job of an explicit ``load_tools`` call.
+
+ Returns an error string when the loader failed, ``None`` on
+ success.
+ """
+ group = self._groups[group_id]
+ lock = self._loader_locks.setdefault(group_id, asyncio.Lock())
+ async with lock:
+ try:
+ if group_id not in self._loader_cache:
+ self._loader_cache[group_id] = await group.loader()
+ except Exception as exc:
+ return f"Loading deferred tool group '{group_id}' failed: {exc}"
+ wanted = set(tool_names)
if context.tools is not None:
- self._drain_pending(context.tools)
+ existing = {t.name for t in context.tools}
+ for t in self._loader_cache[group_id]:
+ if t.name in wanted and t.name not in existing:
+ context.tools.append(replace(t, expose_to_model=False))
+ return None
# ------------------------------------------------------------------
# System prompt: catalog (static in dispatch mode)
diff --git a/dev/specs/2026-06-10-deferred-dispatcher.md b/dev/specs/2026-06-10-deferred-dispatcher.md
index f27588a..15c7b18 100644
--- a/dev/specs/2026-06-10-deferred-dispatcher.md
+++ b/dev/specs/2026-06-10-deferred-dispatcher.md
@@ -204,10 +204,14 @@ The middleware's resolver:
1. `tool_call.name != "deferred_tool_call"` → return `None` (no-op for everything else).
2. Parse `{tool_name, arguments}`. Unknown `tool_name` (not in any group) → leave the call
unresolved with a structured error result listing valid names.
-3. **Implicit load**: if `tool_name`'s group isn't loaded, run the loader (cache + lock), append
- the group's tools to `context.tools` (`expose_to_model=False`), record load state in
- `extra["expanded_groups"]`.
-4. Return `ToolCall(id=同, name=tool_name, arguments=arguments)`.
+3. **Implicit load** (ephemeral, state-free): if `tool_name` isn't already in
+ `context.tools`, run the loader (shared cache + per-group lock), append the requested
+ tool to `context.tools` (`expose_to_model=False`). No `extra["expanded_groups"]` write,
+ no `on_tools_expanded` — state recording belongs to explicit `load_tools` only
+ (fork-safety; see §Forks). A loader failure raises, which the engine converts into the
+ call's error result.
+4. Non-dict `arguments` → return `None` (the dispatcher's own schema validation rejects the
+ call). Otherwise return `ToolCall(id=同, name=tool_name, arguments=arguments)`.
**Validation failure includes the schema.** When a dispatch-resolved call fails
`model_validate`, the error result appends the tool's full schema JSON, so the model retries
@@ -224,12 +228,14 @@ payload, and no resolver runs), a regression vs v1 where expanded tools stayed u
forks. `load_tools` remains fork-denied as in v1 (its *execute* is wrapped); the forwarded
resolver, however, does not go through that execute — so dispatched calls work in forks for
already-loaded tools, and dispatching an unloaded tool triggers an **implicit load from the
-fork**. This is deliberate: the loader cache and per-group locks live on the shared
-middleware instance, so the loader still runs at most once across parent + forks, loaded
-tools are appended hidden (no cache impact anywhere), and the recorded
-`extra["expanded_groups"]` state simply pre-warms the parent. Deferred loading is
-process-level resource acquisition, not conversation state — sharing it across forks is
-coherent where v1's model-visible injection was not.
+fork**. Implicit loads are **ephemeral and state-free** (revised per PR codex review): they
+share only the loader cache and per-group locks (the loader still runs at most once across
+parent + forks — process-level resource acquisition), append the hidden tool to the *local*
+context only, and never write `extra["expanded_groups"]` or call `on_tools_expanded` — a
+fork-forwarded resolver therefore cannot mutate the parent agent's state or tool list.
+Recording expansion state stays the job of an explicit `load_tools` call. An implicit load
+whose loader fails surfaces the loader error as the dispatched call's error result (not a
+misleading "tool not found").
`prepare_resumed_state` takes a **required** `strategy` kwarg (no default) so a host cannot
resume with a strategy that mismatches its middleware construction.
diff --git a/tests/deferred/test_dispatch.py b/tests/deferred/test_dispatch.py
index b054d09..f8333fa 100644
--- a/tests/deferred/test_dispatch.py
+++ b/tests/deferred/test_dispatch.py
@@ -7,7 +7,7 @@ from pydantic import BaseModel
from cubepi.agent.types import AgentContext, AgentTool, AgentToolResult
from cubepi.providers.base import TextContent, ToolCall
-from cubepi.deferred import DeferredToolsMiddleware
+from cubepi.deferred import DeferredToolGroup, DeferredToolsMiddleware
from tests.deferred._helpers import _dummy_tool, _echo_tool, _mw
from tests.deferred._helpers import _make_group as _make_group_base
@@ -325,3 +325,147 @@ class TestDispatchFork:
if getattr(m, "tool_call_id", None) == "tc-2"
]
assert echo_results == ["echo:fork"]
+
+
+class TestCodexReviewFindings:
+ async def test_dispatched_sequential_tool_runs_in_sequential_mode(self) -> None:
+ """The execution-mode decision must see the RESOLVED tool name —
+ a dispatcher call targeting a sequential tool may not run in the
+ parallel executor."""
+ import asyncio as aio
+
+ from cubepi.agent.tools import execute_tool_calls
+ from cubepi.providers.faux import faux_assistant_message
+
+ order: list[str] = []
+
+ class _NoArgs(BaseModel):
+ pass
+
+ async def _slow_exec(tool_call_id, args, *, signal=None, on_update=None):
+ await aio.sleep(0.05)
+ order.append("seq")
+ return AgentToolResult(content=[TextContent(text="seq")])
+
+ async def _fast_exec(tool_call_id, args, *, signal=None, on_update=None):
+ order.append("fast")
+ return AgentToolResult(content=[TextContent(text="fast")])
+
+ seq_tool = AgentTool(
+ name="seq_tool",
+ description="d",
+ parameters=_NoArgs,
+ execute=_slow_exec,
+ execution_mode="sequential",
+ )
+ fast_tool = AgentTool(
+ name="fast_tool", description="d", parameters=_NoArgs, execute=_fast_exec
+ )
+ group = _make_group_base("g", ["seq_tool"], loader_tools=[seq_tool])
+ extra: dict = {}
+ mw = DeferredToolsMiddleware(
+ groups=[group], extra_ref=lambda: extra, strategy="dispatch"
+ )
+ ctx = AgentContext(
+ system_prompt="", messages=[], tools=[*mw.tools, fast_tool], extra=extra
+ )
+ calls = [
+ ToolCall(
+ id="tc-a",
+ name="deferred_tool_call",
+ arguments={"tool_name": "seq_tool", "arguments": {}},
+ ),
+ ToolCall(id="tc-b", name="fast_tool", arguments={}),
+ ]
+ await execute_tool_calls(
+ ctx,
+ faux_assistant_message(calls, stop_reason="tool_use"),
+ resolve_tool_call=mw.resolve_tool_call,
+ emit=lambda e: None,
+ )
+ assert order == ["seq", "fast"]
+
+ async def test_implicit_load_records_no_state(self) -> None:
+ """Implicit loads are ephemeral: no expanded_groups entry, no
+ on_tools_expanded callback — a fork-forwarded resolver cannot
+ mutate the parent agent."""
+ extra: dict = {}
+ seen: list = []
+ group = _make_group("g", ["t1"])
+ mw = DeferredToolsMiddleware(
+ groups=[group],
+ extra_ref=lambda: extra,
+ strategy="dispatch",
+ on_tools_expanded=seen.append,
+ )
+ ctx = AgentContext(system_prompt="", messages=[], tools=list(mw.tools))
+ call = ToolCall(
+ id="tc-1",
+ name="deferred_tool_call",
+ arguments={"tool_name": "t1", "arguments": {"value": "hi"}},
+ )
+ rewritten = await mw.resolve_tool_call(call, context=ctx)
+ assert rewritten is not None and rewritten.name == "t1"
+ assert any(t.name == "t1" and not t.expose_to_model for t in ctx.tools)
+ assert "expanded_groups" not in extra
+ assert seen == []
+
+ async def test_implicit_load_failure_surfaces_loader_error(self) -> None:
+ from cubepi.agent.tools import execute_tool_calls
+ from cubepi.providers.faux import faux_assistant_message
+
+ async def _failing_loader():
+ raise RuntimeError("connection refused")
+
+ group = DeferredToolGroup(
+ group_id="g",
+ display_name="G",
+ description="d",
+ tool_names=["t1"],
+ loader=_failing_loader,
+ )
+ extra: dict = {}
+ mw = DeferredToolsMiddleware(
+ groups=[group], extra_ref=lambda: extra, strategy="dispatch"
+ )
+ ctx = AgentContext(system_prompt="", messages=[], tools=list(mw.tools))
+ call = ToolCall(
+ id="tc-f",
+ name="deferred_tool_call",
+ arguments={"tool_name": "t1", "arguments": {}},
+ )
+ batch = await execute_tool_calls(
+ ctx,
+ faux_assistant_message(call, stop_reason="tool_use"),
+ resolve_tool_call=mw.resolve_tool_call,
+ emit=lambda e: None,
+ )
+ msg = batch.messages[0]
+ assert msg.is_error is True
+ assert "connection refused" in msg.content[0].text
+ assert "not found" not in msg.content[0].text
+
+ async def test_dispatcher_rejects_non_dict_arguments(self) -> None:
+ """Garbage inner arguments must hit the dispatcher's own schema
+ validation, not be coerced to {} and silently run the tool."""
+ from cubepi.agent.tools import execute_tool_calls
+ from cubepi.providers.faux import faux_assistant_message
+
+ mw = _mw([_make_group("g", ["t1"])])
+ ctx = AgentContext(system_prompt="", messages=[], tools=list(mw.tools))
+ call = ToolCall(
+ id="tc-bad",
+ name="deferred_tool_call",
+ arguments={"tool_name": "t1", "arguments": "oops"},
+ )
+ batch = await execute_tool_calls(
+ ctx,
+ faux_assistant_message(call, stop_reason="tool_use"),
+ resolve_tool_call=mw.resolve_tool_call,
+ emit=lambda e: None,
+ )
+ msg = batch.messages[0]
+ assert msg.is_error is True
+ text = msg.content[0].text
+ assert "Invalid arguments for tool 'deferred_tool_call'" in text
+ assert "dictionary" in text