Skip to content

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

docs(deferred): fold code-review findings into spec + plan

xf gong309352e9f2dd
diff --git a/dev/plans/2026-06-10-deferred-dispatcher.md b/dev/plans/2026-06-10-deferred-dispatcher.md
index 9c2f20b..cc7334e 100644
--- a/dev/plans/2026-06-10-deferred-dispatcher.md
+++ b/dev/plans/2026-06-10-deferred-dispatcher.md
@@ -359,8 +359,33 @@ async def _prepare_tool_call(
...
```
-`resolved` is consumed in Task 3 (keep it assigned-but-unused for now, or fold Task 3's
-two-line change in immediately — see Task 3 Step 1).
+`resolved` is consumed in Task 3 — fold Task 3 Step 1's validation-branch change in
+immediately while editing this function (avoids an assigned-but-unused lint window); Task 3
+then only runs its tests.
+
+**Event naming (review finding).** `ToolExecutionStartEvent` / `ToolExecutionEndEvent` must
+carry the **resolved** name. Check where `_execute_sequential` / `_execute_parallel` emit
+them: if the start event is emitted from the raw `tool_call` before `_prepare_tool_call`
+runs, move the emission after preparation (or emit from `prepared.tool_call`) so tracing's
+`_find_tool(event.tool_name)` (cubepi/tracing/recorder.py ~:832) resolves the real tool.
+Extend `test_resolver_rewrites_call_before_pipeline` with an emit recorder:
+
+```python
+ events: list = []
+ batch = await execute_tool_calls(
+ ctx,
+ _assistant_with(call),
+ before_tool_call=before,
+ resolve_tool_call=resolver,
+ emit=events.append,
+ )
+ from cubepi.agent.types import ToolExecutionStartEvent
+
+ start_names = [e.tool_name for e in events if isinstance(e, ToolExecutionStartEvent)]
+ assert start_names == ["real_tool"]
+```
+
+(Replace the `emit=_noop_emit` in that one test with the recorder above.)
- [ ] **Step 4: Thread through `cubepi/agent/loop.py`**
@@ -386,6 +411,11 @@ In `cubepi/middleware/base.py`, add to the `Middleware` base class (next to
The returned ToolCall MUST keep the original ``id`` — the result
message is keyed by it on the wire.
+
+ Composition is FIRST-NON-NONE-WINS: the first middleware to return a
+ rewritten call short-circuits the chain. This differs from
+ ``before_tool_call``, which chains sequentially. A resolver never sees
+ another resolver's output.
"""
return None
```
@@ -418,6 +448,17 @@ Mirror `before_tool_call` exactly: add `resolve_tool_call: Callable | None = Non
:248), and pass `resolve_tool_call=self.resolve_tool_call` at the three loop invocation sites
(:590, :723, :746).
+**Fork wiring (review finding — regression otherwise).** The fork construction in
+`agent.py` (~:581-599) builds the child with `middleware=[]` but forwards hook callables
+explicitly (`before_tool_call` is already passed). Forward the resolver the same way:
+`resolve_tool_call=self.resolve_tool_call` in the fork's `Agent(...)` kwargs. Without this,
+dispatch-mode forks can never invoke loaded deferred tools (the dispatcher's execute is
+denied by `_deny_in_fork`, hidden tools are invisible, and no resolver exists) — a regression
+vs v1 where expanded tools remained usable in forks. Add a test in
+`tests/deferred/test_dispatch.py` that drives a fork the same way
+`tests/agent/test_agent_fork_once.py` does and asserts a `deferred_tool_call` to a
+pre-loaded tool succeeds inside the fork.
+
- [ ] **Step 7: Run tests**
Run: `uv run pytest tests/agent/test_resolve_tool_call.py -v`
@@ -537,11 +578,9 @@ def test_load_tools_output_carries_schemas() -> None:
tool_names=["t"],
remaining=0,
schemas=[{"name": "t", "description": "d", "parameters": {}}],
- usage="Call these via deferred_tool_call(tool_name=..., arguments=...).",
)
dumped = out.model_dump()
assert dumped["schemas"][0]["name"] == "t"
- assert "deferred_tool_call" in dumped["usage"]
```
- [ ] **Step 2: Run to verify failure**
@@ -602,10 +641,11 @@ class LoadToolsOutput(BaseModel):
tool_names: list[str]
remaining: int
error: str | None = None
- # Dispatch mode only: full schemas + calling hint, delivered in the tool
- # result so they live in message history (append-only, cache-safe).
+ # Dispatch mode only: full schemas, delivered in the tool result so they
+ # live in message history (append-only, cache-safe). The calling
+ # convention lives once in the static catalog header and the dispatcher
+ # description — not repeated per result.
schemas: list[dict[str, object]] | None = None
- usage: str | None = None
```
- [ ] **Step 4: Run tests**
@@ -698,16 +738,15 @@ class TestDispatchStrategy:
assert out.expanded is True
assert out.schemas is not None
assert out.schemas[0]["name"] == "t1"
- assert "deferred_tool_call" in (out.usage or "")
- # Deterministic parameters serialization.
- params = out.schemas[0]["parameters"]
- assert json.dumps(params, sort_keys=True) == json.dumps(params, sort_keys=True)
- async def test_load_tools_idempotent(self) -> None:
+ async def test_load_tools_idempotent_and_deterministic(self) -> None:
mw = _mw([_make_group("g", ["t1"])])
first = await mw._expand_callback("g", None)
second = await mw._expand_callback("g", None)
- assert first.schemas == second.schemas # compaction self-rescue
+ # Compaction self-rescue: repeat calls serialize byte-identically.
+ assert json.dumps(first.schemas, sort_keys=True) == json.dumps(
+ second.schemas, sort_keys=True
+ )
async def test_loaded_tools_enter_context_hidden(self) -> None:
mw = _mw([_make_group("g", ["t1"])])
@@ -848,7 +887,9 @@ def _make_deferred_tool_call(
TextContent(
text=(
f"Unknown deferred tool: {args.tool_name!r}. "
- f"Valid names: {', '.join(sorted(names))}"
+ f"Valid names: {', '.join(sorted(names))}. "
+ "Call load_tools(group_id=...) to list a group's "
+ "full schemas."
)
)
],
@@ -918,6 +959,17 @@ name→group index for the resolver:
known_tool_names=lambda: list(self._tool_to_group)
)
)
+
+ # Dispatch catalog is expansion-independent — render once, serve
+ # byte-identical every turn.
+ self._static_catalog: str = (
+ render_static_catalog(
+ groups=list(self._groups.values()),
+ header=self._catalog_header,
+ )
+ if strategy == "dispatch"
+ else ""
+ )
```
(Note: `resumed_schemas` and `self._expanded_schemas` are gone — Task 6/7 remove their
@@ -937,13 +989,9 @@ result carries schemas:
self._on_tools_expanded(staged)
schemas: list[dict[str, object]] | None = None
- usage: str | None = None
if self._strategy == "dispatch":
- requested_defs = [t.to_definition().model_dump() for t in requested]
- schemas = requested_defs # full set for the request — idempotent
- usage = (
- "Call these via deferred_tool_call(tool_name=..., arguments=...)."
- )
+ # Full set for the request — idempotent across repeat calls.
+ schemas = [t.to_definition().model_dump() for t in requested]
return LoadToolsOutput(
group_id=group_id,
@@ -951,7 +999,6 @@ result carries schemas:
tool_names=expanded_names,
remaining=max(remaining, 0),
schemas=schemas,
- usage=usage,
)
```
@@ -975,7 +1022,11 @@ so repeat calls return the same `schemas` even when `newly_expanded` is empty.)
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
- await self._ensure_loaded(self._tool_to_group[name], [name], context)
+ 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,
@@ -1009,10 +1060,7 @@ so repeat calls return the same `schemas` even when `newly_expanded` is empty.)
) -> str:
del signal
if self._strategy == "dispatch":
- catalog = render_static_catalog(
- groups=list(self._groups.values()),
- header=self._catalog_header,
- )
+ catalog = self._static_catalog
return f"{system_prompt}\n\n{catalog}" if catalog else system_prompt
extra = self._extra_ref()
@@ -1181,7 +1229,10 @@ tests call `DeferredToolsMiddleware.prepare_resumed_state`):
groups: list[DeferredToolGroup],
expanded: dict[str, list[str] | None],
*,
- strategy: DeferredStrategy = "dispatch",
+ strategy: DeferredStrategy, # REQUIRED — must match the middleware's
+ # strategy. A default would let an inject-mode host silently resume
+ # with hidden tools (invisible to the model, no dispatcher to reach
+ # them). Forcing the kwarg makes the mismatch impossible.
) -> ResumedState:
"""Replay expansion state from a previous run.
diff --git a/dev/specs/2026-06-10-deferred-dispatcher.md b/dev/specs/2026-06-10-deferred-dispatcher.md
index 5168abd..f27588a 100644
--- a/dev/specs/2026-06-10-deferred-dispatcher.md
+++ b/dev/specs/2026-06-10-deferred-dispatcher.md
@@ -155,8 +155,7 @@ carries the schemas instead of the middleware mutating prompt state:
"schemas": [
{"name": "create_issue", "description": "...", "parameters": {...}},
{"name": "list_issues", "description": "...", "parameters": {...}}
- ],
- "usage": "Call these via deferred_tool_call(tool_name=..., arguments=...)."
+ ]
}
```
@@ -164,6 +163,8 @@ carries the schemas instead of the middleware mutating prompt state:
cached prefix on subsequent turns).
- Idempotent: repeat calls return the same payload (compaction self-rescue). Loader still runs
exactly once per group per run (v1 loader cache + per-group `asyncio.Lock` reused).
+- The calling convention ("invoke via `deferred_tool_call`") lives once in the static catalog
+ header and the dispatcher's description — not repeated in every result.
**`deferred_tool_call(tool_name: str, arguments: dict)`** — the dispatcher. Its `execute` never
runs; calls are rewritten by the engine before the standard pipeline (next section).
@@ -213,6 +214,26 @@ The middleware's resolver:
with correct args in one round trip. (Mechanism: the resolver marks the rewritten call;
`_format_validation_error` gains an optional schema suffix. Exact plumbing settled in the plan.)
+### Forks
+
+Forked agents (`fork_once`-style) are built with `middleware=[]` but receive the parent's
+hook callables explicitly. The fork construction must forward `resolve_tool_call` the same
+way it already forwards `before_tool_call` — otherwise dispatch-mode forks cannot invoke any
+loaded deferred tool (the dispatcher's execute is fork-denied, hidden tools are not in the
+payload, and no resolver runs), a regression vs v1 where expanded tools stayed usable in
+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.
+
+`prepare_resumed_state` takes a **required** `strategy` kwarg (no default) so a host cannot
+resume with a strategy that mismatches its middleware construction.
+
### State persistence & resume
`extra["expanded_groups"]` keeps the v1 shape (`dict[group_id, list[str] | None]`) — durable