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
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.pyindex 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.pyindex 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 testedtransform_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 testedpartial_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 testedtransform_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.pyindex ab22ed2..bf1b542 100644--- a/cubepi/agent/tools.py+++ b/cubepi/agent/tools.py@@ -1,6 +1,7 @@from __future__ import annotationsimport asyncio+import jsonimport timefrom dataclasses import dataclassfrom 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 = Noneif 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.pyindex 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, ToolCallfrom 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.pynew file mode 100644index 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