Skip to content

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

docs: count resolve_tool_call everywhere hooks are enumerated (8 -> 9)

xf gongecfb98a1a71f
diff --git a/README.md b/README.md
index d19079b..0e14cdb 100644
--- a/README.md
+++ b/README.md
@@ -182,6 +182,7 @@ hooks = compose_middleware([LoggingMiddleware(), SafetyMiddleware()])
|------|------|
| `transform_context` | Chained — each receives previous result |
| `convert_to_llm` | Last implementation wins |
+| `resolve_tool_call` | First non-`None` rewrite wins (short-circuits) |
| `before_tool_call` | Any block stops execution |
| `after_tool_call` | Later overrides earlier |
| `transform_system_prompt` | Chained — each receives previous result |
diff --git a/website/docs/getting-started/core-concepts.md b/website/docs/getting-started/core-concepts.md
index 0ef986e..dfb8083 100644
--- a/website/docs/getting-started/core-concepts.md
+++ b/website/docs/getting-started/core-concepts.md
@@ -121,13 +121,14 @@ Subscribe to agent events for UI; for low-level token routing dig into
## Middleware
-`Middleware` is a class with up to eight typed hooks:
+`Middleware` is a class with up to nine typed hooks:
| Hook | When it runs | Composition rule |
|---|---|---|
| `transform_context` | Before each model call, on the message list | Chained — each receives previous result |
| `convert_to_llm` | Right before serialisation to the provider | Last implementation wins |
| `transform_system_prompt` | Before each model call, on the system prompt | Chained |
+| `resolve_tool_call` | Per tool call, before validation — may rewrite the call | First non-`None` wins |
| `before_tool_call` | Per tool call, after arg validation | First `block=True` short-circuits |
| `after_tool_call` | Per tool call, after `execute` | Later override earlier |
| `after_model_response` | After the assistant message lands | Returns a `TurnAction` controlling flow |
diff --git a/website/docs/guides/middleware/composition.md b/website/docs/guides/middleware/composition.md
index d9ed7d0..1246611 100644
--- a/website/docs/guides/middleware/composition.md
+++ b/website/docs/guides/middleware/composition.md
@@ -18,6 +18,7 @@ to remember "before" or "after" precedence guesses.
| `transform_context` | **Chain** — each sees previous output | Yes |
| `convert_to_llm` | **Last wins** | Only the last one runs |
| `transform_system_prompt` | **Chain** | Yes |
+| `resolve_tool_call` | **First non-`None` wins** — rewrites the call before validation | First match short-circuits |
| `before_tool_call` | **First block stops**; non-block accumulates | Block wins; `edited_args` last-writer-wins; `hitl_trace` merges |
| `after_tool_call` | **Later overrides earlier** | Last write wins |
| `should_stop_after_turn` | **Any `True` stops** (OR) | No |
@@ -53,6 +54,18 @@ If you find yourself needing two `convert_to_llm` middlewares,
collapse them into one (call site composition: write one that calls
both).
+## `resolve_tool_call`
+
+**First non-`None` wins.** The first middleware to return a rewritten
+`ToolCall` short-circuits the chain — later resolvers never see the
+original call, and no resolver ever sees another resolver's output. If
+every middleware returns `None`, the call proceeds unchanged.
+
+This deliberately differs from `before_tool_call`'s chaining: a
+resolution is a single rewrite (e.g. unwrapping the
+[deferred-tools](./deferred-tools) dispatcher to the real tool), not an
+accumulation.
+
## `before_tool_call`
First `block=True` short-circuits the rest. **Non-block returns
diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx
index d092a68..11829a9 100644
--- a/website/docs/intro.mdx
+++ b/website/docs/intro.mdx
@@ -35,10 +35,10 @@ working tool-using agent in under five minutes.
conversation length — SQLite for laptops, Postgres for production.
- **Native multi-provider.** Anthropic and OpenAI ship in the box,
through a `Provider` Protocol. Add a new provider in one class.
-- **Eight-hook middleware.** `transform_context`, `convert_to_llm`,
- `transform_system_prompt`, `before_tool_call`, `after_tool_call`,
- `should_stop_after_turn`, `after_model_response`, `on_run_end` — each
- with explicit composition rules. No mystery node ordering.
+- **Nine-hook middleware.** `transform_context`, `convert_to_llm`,
+ `transform_system_prompt`, `resolve_tool_call`, `before_tool_call`,
+ `after_tool_call`, `should_stop_after_turn`, `after_model_response`,
+ `on_run_end` — each with explicit composition rules. No mystery node ordering.
- **MCP loaders.** Point at any
[Model Context Protocol](https://modelcontextprotocol.io) server
(HTTP or stdio) and get back a list of `AgentTool`s.
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/core-concepts.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/core-concepts.md
index 3906943..cbaadb5 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/core-concepts.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/core-concepts.md
@@ -97,13 +97,14 @@ class Provider(Protocol):
## Middleware
-`Middleware` 是有最多八个类型化 hook 的类:
+`Middleware` 是有最多九个类型化 hook 的类:
| Hook | 何时触发 | 组合规则 |
|---|---|---|
| `transform_context` | 每次调模型之前,处理消息列表 | 链式 —— 每个收到上一个的输出 |
| `convert_to_llm` | provider 序列化之前 | 最后一个实现生效 |
| `transform_system_prompt` | 每次调模型之前,处理 system prompt | 链式 |
+| `resolve_tool_call` | 每个工具调用之前(参数校验之前,可改写调用) | 第一个非 `None` 胜出 |
| `before_tool_call` | 每个工具调用之前(在参数校验后) | 第一个 `block=True` 短路 |
| `after_tool_call` | 每个工具调用之后(在 `execute` 之后) | 后写覆盖先写 |
| `after_model_response` | assistant 消息落定之后 | 返回 `TurnAction` 控制流向 |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/composition.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/composition.md
index 8e746a4..5aa2653 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/composition.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/composition.md
@@ -16,6 +16,7 @@ description: "了解 CubePi 如何通过 per-hook 规则组合多个中间件。
| `transform_context` | **链式**——每个看到上一个的输出 | 是 |
| `convert_to_llm` | **最后一个胜出** | 只有一个运行 |
| `transform_system_prompt` | **链式** | 是 |
+| `resolve_tool_call` | **第一个非 `None` 胜出**——在校验前改写调用 | 第一个命中即短路 |
| `before_tool_call` | **第一个 block 停止**;非 block 累积 | block 胜出;`edited_args` 最后写入者胜出;`hitl_trace` 合并 |
| `after_tool_call` | **后面覆盖前面** | 最后写入胜出 |
| `should_stop_after_turn` | **任一 True 即停止**(OR) | 否 |
@@ -46,6 +47,16 @@ CubePi 强制**列表中的最后一个**实现了 `convert_to_llm` 的中间件
如果你发现自己需要两个 `convert_to_llm` 中间件,将它们合并为一个
(调用点组合:写一个调用两者的中间件)。
+## `resolve_tool_call`
+
+**第一个非 `None` 返回值胜出。** 第一个返回改写后 `ToolCall` 的中间件
+会短路整个链——后面的 resolver 看不到原始调用,任何 resolver 也看不到
+其他 resolver 的输出。全部返回 `None` 时调用原样继续。
+
+这与 `before_tool_call` 的链式组合是刻意不同的:一次 resolution 是
+单一改写(例如把[延迟工具](./deferred-tools)的 dispatcher 解包成
+真实工具),不是累积。
+
## `before_tool_call`
第一个 `block=True` 短路其余中间件。**非 block 返回累积:**
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx
index 9695b49..d92e3a2 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx
@@ -35,10 +35,10 @@ pip install cubepi
生产环境。
- **原生多 provider。** Anthropic 和 OpenAI 开箱即用,通过 `Provider`
Protocol 接入。要新增一个 provider 只需要写一个类。
-- **八个 Hook 的中间件。** `transform_context`、`convert_to_llm`、
- `transform_system_prompt`、`before_tool_call`、`after_tool_call`、
- `should_stop_after_turn`、`after_model_response`、`on_run_end`——
- 每一个都有明确的组合规则。没有"节点执行顺序之谜"。
+- **九个 Hook 的中间件。** `transform_context`、`convert_to_llm`、
+ `transform_system_prompt`、`resolve_tool_call`、`before_tool_call`、
+ `after_tool_call`、`should_stop_after_turn`、`after_model_response`、
+ `on_run_end`——每一个都有明确的组合规则。没有"节点执行顺序之谜"。
- **MCP 加载器。** 指向任意
[Model Context Protocol](https://modelcontextprotocol.io) 服务器
(HTTP 或 stdio),就能拿回一组 `AgentTool`。