Skip to content

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

feat(agent): resolve_tool_call hook rewrites tool calls before the pipeline

xf gong98957b43ebcf
diff --git a/cubepi/agent/agent.py b/cubepi/agent/agent.py
index 8bc45a5..b57a5bf 100644
--- a/cubepi/agent/agent.py
+++ b/cubepi/agent/agent.py
@@ -178,6 +178,7 @@ class Agent(Generic[TMessage]):
transform_system_prompt: Callable | None = None,
after_model_response: Callable | None = None,
before_tool_call: Callable | None = None,
+ resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
should_stop_after_turn: Callable | None = None,
on_run_end: Callable | None = None,
@@ -246,6 +247,9 @@ class Agent(Generic[TMessage]):
"after_model_response"
)
self.before_tool_call = before_tool_call or _mw_hooks.get("before_tool_call")
+ self.resolve_tool_call = resolve_tool_call or _mw_hooks.get(
+ "resolve_tool_call"
+ )
self.after_tool_call = after_tool_call or _mw_hooks.get("after_tool_call")
self.should_stop_after_turn = should_stop_after_turn or _mw_hooks.get(
"should_stop_after_turn"
@@ -588,6 +592,10 @@ class Agent(Generic[TMessage]):
transform_system_prompt=self.transform_system_prompt,
after_model_response=self.after_model_response,
before_tool_call=self.before_tool_call,
+ # Without the resolver, dispatch-mode forks could never invoke
+ # loaded deferred tools (the dispatcher's execute is fork-denied
+ # and hidden tools are not in the payload).
+ resolve_tool_call=self.resolve_tool_call,
after_tool_call=self.after_tool_call,
should_stop_after_turn=self.should_stop_after_turn,
on_run_end=self.on_run_end,
@@ -721,6 +729,7 @@ class Agent(Generic[TMessage]):
transform_system_prompt=self.transform_system_prompt,
after_model_response=self.after_model_response,
before_tool_call=self.before_tool_call,
+ resolve_tool_call=self.resolve_tool_call,
after_tool_call=self.after_tool_call,
should_stop_after_turn=self.should_stop_after_turn,
on_run_end=self.on_run_end,
@@ -744,6 +753,7 @@ class Agent(Generic[TMessage]):
transform_system_prompt=self.transform_system_prompt,
after_model_response=self.after_model_response,
before_tool_call=self.before_tool_call,
+ resolve_tool_call=self.resolve_tool_call,
after_tool_call=self.after_tool_call,
should_stop_after_turn=self.should_stop_after_turn,
on_run_end=self.on_run_end,
@@ -1015,6 +1025,7 @@ class Agent(Generic[TMessage]):
transform_system_prompt=self.transform_system_prompt,
after_model_response=self.after_model_response,
before_tool_call=self.before_tool_call,
+ resolve_tool_call=self.resolve_tool_call,
after_tool_call=self.after_tool_call,
should_stop_after_turn=self.should_stop_after_turn,
on_run_end=self.on_run_end,
diff --git a/cubepi/agent/loop.py b/cubepi/agent/loop.py
index 1f8696c..b9f03b4 100644
--- a/cubepi/agent/loop.py
+++ b/cubepi/agent/loop.py
@@ -44,6 +44,7 @@ async def run_agent_loop(
transform_system_prompt: Callable | None = None,
after_model_response: Callable | None = None,
before_tool_call: Callable | None = None,
+ resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
should_stop_after_turn: Callable | None = None,
get_steering_messages: Callable | None = None,
@@ -79,6 +80,7 @@ async def run_agent_loop(
transform_system_prompt=transform_system_prompt,
after_model_response=after_model_response,
before_tool_call=before_tool_call,
+ resolve_tool_call=resolve_tool_call,
after_tool_call=after_tool_call,
should_stop_after_turn=should_stop_after_turn,
get_steering_messages=get_steering_messages,
@@ -102,6 +104,7 @@ async def run_agent_loop_continue(
transform_system_prompt: Callable | None = None,
after_model_response: Callable | None = None,
before_tool_call: Callable | None = None,
+ resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
should_stop_after_turn: Callable | None = None,
get_steering_messages: Callable | None = None,
@@ -137,6 +140,7 @@ async def run_agent_loop_continue(
transform_system_prompt=transform_system_prompt,
after_model_response=after_model_response,
before_tool_call=before_tool_call,
+ resolve_tool_call=resolve_tool_call,
after_tool_call=after_tool_call,
should_stop_after_turn=should_stop_after_turn,
get_steering_messages=get_steering_messages,
@@ -160,6 +164,7 @@ async def run_agent_loop_resume(
transform_system_prompt: Callable | None = None,
after_model_response: Callable | None = None,
before_tool_call: Callable | None = None,
+ resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
should_stop_after_turn: Callable | None = None,
get_steering_messages: Callable | None = None,
@@ -184,6 +189,7 @@ async def run_agent_loop_resume(
transform_system_prompt=transform_system_prompt,
after_model_response=after_model_response,
before_tool_call=before_tool_call,
+ resolve_tool_call=resolve_tool_call,
after_tool_call=after_tool_call,
should_stop_after_turn=should_stop_after_turn,
get_steering_messages=get_steering_messages,
@@ -223,6 +229,7 @@ async def _run_agent_loop_resume_body( # pragma: no cover — E2E tested
transform_system_prompt,
after_model_response,
before_tool_call,
+ resolve_tool_call,
after_tool_call,
should_stop_after_turn,
get_steering_messages,
@@ -308,6 +315,7 @@ async def _run_agent_loop_resume_body( # pragma: no cover — E2E tested
partial_msg,
tool_execution=tool_execution,
before_tool_call=before_tool_call,
+ resolve_tool_call=resolve_tool_call,
after_tool_call=after_tool_call,
signal=(stream_options or StreamOptions()).signal,
emit=emit,
@@ -375,6 +383,7 @@ async def _run_agent_loop_resume_body( # pragma: no cover — E2E tested
transform_system_prompt=transform_system_prompt,
after_model_response=after_model_response,
before_tool_call=before_tool_call,
+ resolve_tool_call=resolve_tool_call,
after_tool_call=after_tool_call,
should_stop_after_turn=should_stop_after_turn,
get_steering_messages=get_steering_messages,
@@ -398,6 +407,7 @@ async def _run_loop(
transform_system_prompt: Callable | None,
after_model_response: Callable | None,
before_tool_call: Callable | None,
+ resolve_tool_call: Callable | None,
after_tool_call: Callable | None,
should_stop_after_turn: Callable | None,
get_steering_messages: Callable | None,
@@ -418,6 +428,7 @@ async def _run_loop(
transform_system_prompt=transform_system_prompt,
after_model_response=after_model_response,
before_tool_call=before_tool_call,
+ resolve_tool_call=resolve_tool_call,
after_tool_call=after_tool_call,
should_stop_after_turn=should_stop_after_turn,
get_steering_messages=get_steering_messages,
@@ -454,6 +465,7 @@ async def _run_loop_inner(
transform_system_prompt: Callable | None,
after_model_response: Callable | None,
before_tool_call: Callable | None,
+ resolve_tool_call: Callable | None,
after_tool_call: Callable | None,
should_stop_after_turn: Callable | None,
get_steering_messages: Callable | None,
@@ -592,6 +604,7 @@ async def _run_loop_inner(
message,
tool_execution=tool_execution,
before_tool_call=before_tool_call,
+ resolve_tool_call=resolve_tool_call,
after_tool_call=after_tool_call,
signal=opts.signal,
emit=emit,
diff --git a/cubepi/agent/tools.py b/cubepi/agent/tools.py
index ab22ed2..bf1b542 100644
--- a/cubepi/agent/tools.py
+++ b/cubepi/agent/tools.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import asyncio
+import json
import time
from dataclasses import dataclass
from typing import Callable
@@ -139,12 +140,37 @@ def _make_tool_result_message(finalized: _FinalizedOutcome) -> ToolResultMessage
)
+async def _resolve_tool_call(
+ tool_call: ToolCall,
+ context: AgentContext,
+ resolve_tool_call: Callable | None,
+ signal: asyncio.Event | None,
+) -> tuple[ToolCall, bool] | _ImmediateOutcome:
+ """Give the resolve hook a chance to rewrite the call before anything
+ else sees it — events, validation, before/after hooks, and tracing all
+ operate on the rewritten call. Returns ``(call, was_resolved)``, or an
+ immediate error outcome if the resolver raised."""
+ if not resolve_tool_call:
+ return tool_call, False
+ try:
+ rewritten = await resolve_tool_call(tool_call, context=context, signal=signal)
+ except HitlControlException:
+ raise
+ except Exception as exc:
+ return _ImmediateOutcome(result=_error_result(str(exc)), is_error=True)
+ if rewritten is None:
+ return tool_call, False
+ return rewritten, True
+
+
async def _prepare_tool_call(
context: AgentContext,
assistant_message: AssistantMessage,
tool_call: ToolCall,
before_tool_call: Callable | None,
signal: asyncio.Event | None,
+ *,
+ resolved: bool = False,
) -> _PreparedToolCall | _ImmediateOutcome:
tool = None
if context.tools:
@@ -162,8 +188,19 @@ async def _prepare_tool_call(
try:
validated_args = tool.parameters.model_validate(tool_call.arguments)
except ValidationError as exc:
+ message = _format_validation_error(exc, tool.name)
+ if resolved:
+ # The model never saw a resolved tool's schema in the tools
+ # block — append it so a bad call self-corrects in one round
+ # trip instead of a blind retry.
+ schema = json.dumps(
+ tool.parameters.model_json_schema(),
+ sort_keys=True,
+ ensure_ascii=False,
+ )
+ message = f"{message}\n\nFull schema for '{tool.name}':\n{schema}"
return _ImmediateOutcome(
- result=_error_result(_format_validation_error(exc, tool.name)),
+ result=_error_result(message),
is_error=True,
)
except Exception as exc: # pragma: no cover — defensive
@@ -321,6 +358,7 @@ async def execute_tool_calls(
*,
tool_execution: str = "parallel",
before_tool_call: Callable | None = None,
+ resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
signal: asyncio.Event | None = None,
emit: Callable,
@@ -341,6 +379,7 @@ async def execute_tool_calls(
assistant_message,
tool_calls,
before_tool_call,
+ resolve_tool_call,
after_tool_call,
signal,
emit,
@@ -350,6 +389,7 @@ async def execute_tool_calls(
assistant_message,
tool_calls,
before_tool_call,
+ resolve_tool_call,
after_tool_call,
signal,
emit,
@@ -361,6 +401,7 @@ async def _execute_sequential(
assistant_message: AssistantMessage,
tool_calls: list[ToolCall],
before_tool_call: Callable | None,
+ resolve_tool_call: Callable | None,
after_tool_call: Callable | None,
signal: asyncio.Event | None,
emit_fn: Callable,
@@ -369,20 +410,36 @@ async def _execute_sequential(
messages: list[ToolResultMessage] = []
for tc in tool_calls:
+ resolution = await _resolve_tool_call(tc, context, resolve_tool_call, signal)
+ was_resolved = False
+ if isinstance(resolution, _ImmediateOutcome):
+ rtc = tc
+ else:
+ rtc, was_resolved = resolution
+
await emit_event(
emit_fn,
ToolExecutionStartEvent(
- tool_call_id=tc.id, tool_name=tc.name, args=tc.arguments
+ tool_call_id=rtc.id, tool_name=rtc.name, args=rtc.arguments
),
)
- preparation = await _prepare_tool_call(
- context, assistant_message, tc, before_tool_call, signal
- )
+ preparation: _PreparedToolCall | _ImmediateOutcome
+ if isinstance(resolution, _ImmediateOutcome):
+ preparation = resolution
+ else:
+ preparation = await _prepare_tool_call(
+ context,
+ assistant_message,
+ rtc,
+ before_tool_call,
+ signal,
+ resolved=was_resolved,
+ )
if isinstance(preparation, _ImmediateOutcome):
finalized = _FinalizedOutcome(
- tool_call=tc,
+ tool_call=rtc,
result=preparation.result,
is_error=preparation.is_error,
blocked_by_hook=preparation.blocked_by_hook,
@@ -404,8 +461,8 @@ async def _execute_sequential(
await emit_event(
emit_fn,
ToolExecutionEndEvent(
- tool_call_id=tc.id,
- tool_name=tc.name,
+ tool_call_id=rtc.id,
+ tool_name=rtc.name,
result=finalized.result,
is_error=finalized.is_error,
terminate=bool(finalized.result.terminate),
@@ -427,6 +484,7 @@ async def _execute_parallel(
assistant_message: AssistantMessage,
tool_calls: list[ToolCall],
before_tool_call: Callable | None,
+ resolve_tool_call: Callable | None,
after_tool_call: Callable | None,
signal: asyncio.Event | None,
emit_fn: Callable,
@@ -442,9 +500,21 @@ async def _execute_parallel(
# and trace spans permanently open.
entries: list[_FinalizedOutcome | _PreparedToolCall] = []
for tc in tool_calls:
- preparation = await _prepare_tool_call(
- context, assistant_message, tc, before_tool_call, signal
- )
+ resolution = await _resolve_tool_call(tc, context, resolve_tool_call, signal)
+ was_resolved = False
+ if isinstance(resolution, _ImmediateOutcome):
+ rtc = tc
+ preparation: _PreparedToolCall | _ImmediateOutcome = resolution
+ else:
+ rtc, was_resolved = resolution
+ preparation = await _prepare_tool_call(
+ context,
+ assistant_message,
+ rtc,
+ before_tool_call,
+ signal,
+ resolved=was_resolved,
+ )
if isinstance(preparation, _ImmediateOutcome):
# Immediate outcomes get a paired Start+End right here (the
@@ -454,11 +524,11 @@ async def _execute_parallel(
await emit_event(
emit_fn,
ToolExecutionStartEvent(
- tool_call_id=tc.id, tool_name=tc.name, args=tc.arguments
+ tool_call_id=rtc.id, tool_name=rtc.name, args=rtc.arguments
),
)
finalized = _FinalizedOutcome(
- tool_call=tc,
+ tool_call=rtc,
result=preparation.result,
is_error=preparation.is_error,
blocked_by_hook=preparation.blocked_by_hook,
@@ -468,8 +538,8 @@ async def _execute_parallel(
await emit_event(
emit_fn,
ToolExecutionEndEvent(
- tool_call_id=tc.id,
- tool_name=tc.name,
+ tool_call_id=rtc.id,
+ tool_name=rtc.name,
result=finalized.result,
is_error=finalized.is_error,
terminate=bool(finalized.result.terminate),
diff --git a/cubepi/middleware/base.py b/cubepi/middleware/base.py
index a1c8702..6828cce 100644
--- a/cubepi/middleware/base.py
+++ b/cubepi/middleware/base.py
@@ -13,7 +13,7 @@ from cubepi.agent.types import (
BeforeToolCallResult,
)
from cubepi.hitl.binding import HitlBinding
-from cubepi.providers.base import AssistantMessage, BoundModel, Message
+from cubepi.providers.base import AssistantMessage, BoundModel, Message, ToolCall
from cubepi.types import JsonObject, StructuredObject
@@ -64,6 +64,26 @@ class Middleware:
) -> AfterToolCallResult | None:
raise NotImplementedError
+ async def resolve_tool_call(
+ self,
+ tool_call: ToolCall,
+ *,
+ context: AgentContext,
+ signal: asyncio.Event | None = None,
+ ) -> ToolCall | None:
+ """Rewrite a tool call before validation/hooks. Return None to pass
+ through unchanged.
+
+ 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.
+ """
+ raise NotImplementedError
+
async def transform_system_prompt(
self,
system_prompt: str,
@@ -199,6 +219,20 @@ def compose_middleware(middlewares: list[Middleware]) -> dict[str, Callable]:
hooks["before_tool_call"] = composed_before
+ resolve_chain = [m for m in middlewares if _has_method(m, "resolve_tool_call")]
+ if resolve_chain:
+
+ async def composed_resolve(tool_call, *, context, signal=None):
+ for mw in resolve_chain:
+ result = await mw.resolve_tool_call(
+ tool_call, context=context, signal=signal
+ )
+ if result is not None:
+ return result
+ return None
+
+ hooks["resolve_tool_call"] = composed_resolve
+
after_chain = [m for m in middlewares if _has_method(m, "after_tool_call")]
if after_chain:
diff --git a/tests/agent/test_resolve_tool_call.py b/tests/agent/test_resolve_tool_call.py
new file mode 100644
index 0000000..b820d0a
--- /dev/null
+++ b/tests/agent/test_resolve_tool_call.py
@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from cubepi.agent.tools import execute_tool_calls
+from cubepi.agent.types import (
+ AgentContext,
+ AgentTool,
+ AgentToolResult,
+ ToolExecutionStartEvent,
+)
+from cubepi.providers.base import (
+ AssistantMessage,
+ TextContent,
+ ToolCall,
+)
+from cubepi.providers.faux import faux_assistant_message
+
+
+class _EchoArgs(BaseModel):
+ value: str = Field(description="echoed back")
+
+
+def _echo_tool(name: str, *, expose: bool = True) -> AgentTool:
+ async def _exec(tool_call_id, args, *, signal=None, on_update=None):
+ return AgentToolResult(content=[TextContent(text=f"echo:{args.value}")])
+
+ return AgentTool(
+ name=name,
+ description="echo",
+ parameters=_EchoArgs,
+ execute=_exec,
+ expose_to_model=expose,
+ )
+
+
+def _assistant_with(call: ToolCall) -> AssistantMessage:
+ # faux_assistant_message fills usage/timestamp with valid defaults.
+ return faux_assistant_message(call, stop_reason="tool_use")
+
+
+def _noop_emit(event) -> None:
+ return None
+
+
+async def test_resolver_rewrites_call_before_pipeline() -> None:
+ real = _echo_tool("real_tool", expose=False)
+ ctx = AgentContext(system_prompt="", messages=[], tools=[real])
+ call = ToolCall(
+ id="tc-1",
+ name="deferred_tool_call",
+ arguments={"tool_name": "real_tool", "arguments": {"value": "hi"}},
+ )
+ seen_before: list[str] = []
+
+ async def resolver(tool_call, *, context, signal=None):
+ if tool_call.name != "deferred_tool_call":
+ return None
+ return ToolCall(
+ id=tool_call.id,
+ name=tool_call.arguments["tool_name"],
+ arguments=tool_call.arguments["arguments"],
+ )
+
+ async def before(hook_ctx, *, signal=None):
+ seen_before.append(hook_ctx.tool_call.name)
+ return None
+
+ events: list = []
+ batch = await execute_tool_calls(
+ ctx,
+ _assistant_with(call),
+ before_tool_call=before,
+ resolve_tool_call=resolver,
+ emit=events.append,
+ )
+ # Hook saw the real name, not the dispatcher envelope.
+ assert seen_before == ["real_tool"]
+ # Emitted execution events carry the resolved name (tracing looks tools
+ # up by event.tool_name).
+ start_names = [
+ e.tool_name for e in events if isinstance(e, ToolExecutionStartEvent)
+ ]
+ assert start_names == ["real_tool"]
+ # Result keyed to the ORIGINAL tool_use id, carrying the real name.
+ msg = batch.messages[0]
+ assert msg.tool_call_id == "tc-1"
+ assert msg.tool_name == "real_tool"
+ assert msg.content[0].text == "echo:hi"
+
+
+async def test_resolver_none_is_passthrough() -> None:
+ tool = _echo_tool("plain")
+ ctx = AgentContext(system_prompt="", messages=[], tools=[tool])
+ call = ToolCall(id="tc-2", name="plain", arguments={"value": "x"})
+
+ async def resolver(tool_call, *, context, signal=None):
+ return None
+
+ batch = await execute_tool_calls(
+ ctx, _assistant_with(call), resolve_tool_call=resolver, emit=_noop_emit
+ )
+ assert batch.messages[0].content[0].text == "echo:x"
+
+
+async def test_resolver_exception_becomes_error_result() -> None:
+ tool = _echo_tool("plain")
+ ctx = AgentContext(system_prompt="", messages=[], tools=[tool])
+ call = ToolCall(id="tc-3", name="plain", arguments={"value": "x"})
+
+ async def resolver(tool_call, *, context, signal=None):
+ raise RuntimeError("resolver blew up")
+
+ batch = await execute_tool_calls(
+ ctx, _assistant_with(call), resolve_tool_call=resolver, emit=_noop_emit
+ )
+ msg = batch.messages[0]
+ assert msg.is_error is True
+ assert "resolver blew up" in msg.content[0].text
+
+
+async def test_resolved_call_validation_error_includes_schema() -> None:
+ real = _echo_tool("real_tool", expose=False)
+ ctx = AgentContext(system_prompt="", messages=[], tools=[real])
+ call = ToolCall(
+ id="tc-4",
+ name="deferred_tool_call",
+ arguments={"tool_name": "real_tool", "arguments": {"wrong_field": 1}},
+ )
+
+ async def resolver(tool_call, *, context, signal=None):
+ return ToolCall(
+ id=tool_call.id,
+ name="real_tool",
+ arguments=tool_call.arguments["arguments"],
+ )
+
+ batch = await execute_tool_calls(
+ ctx, _assistant_with(call), resolve_tool_call=resolver, emit=_noop_emit
+ )
+ msg = batch.messages[0]
+ assert msg.is_error is True
+ text = msg.content[0].text
+ assert "Invalid arguments for tool 'real_tool'" in text
+ # Full schema appended so the model can self-correct in one round trip.
+ assert '"value"' in text
+
+
+async def test_unresolved_call_validation_error_has_no_schema() -> None:
+ tool = _echo_tool("plain")
+ ctx = AgentContext(system_prompt="", messages=[], tools=[tool])
+ call = ToolCall(id="tc-5", name="plain", arguments={"wrong": 1})
+
+ batch = await execute_tool_calls(ctx, _assistant_with(call), emit=_noop_emit)
+ text = batch.messages[0].content[0].text
+ assert "Invalid arguments" in text
+ assert "Full schema" not in text