merge: preserve hybrid execution with stable tool bridge

DragonnZhang · Sep 14, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 18, 2026 · Sep 18, 2026
commit 4a3863233c43e5220d634d2599a02242fe83b9d9
diff --git a/docs/design/code-mode.md b/docs/design/code-mode.md
@@ -44,23 +44,29 @@ force `direct`. Container execution exposes direct tools only: selecting
 
 ## Exposure policy
 
-| Surface              | `direct`                 | `code_mode`                     | `code_mode_only` |
-| -------------------- | ------------------------ | ------------------------------- | ---------------- |
-| Ordinary eager tools | Direct                   | Direct and nested               | Nested only      |
-| Deferred tools       | `tool_search`            | `tool_search` and nested        | Nested only      |
-| Direct-control tools | Direct                   | Direct only                     | Direct only      |
-| `exec`               | Not registered           | Direct                          | Direct           |
-| Hidden bridge tools  | Existing direct behavior | Direct where already applicable | Hidden           |
+| Surface              | `direct`                    | `code_mode`                     | `code_mode_only` |
+| -------------------- | --------------------------- | ------------------------------- | ---------------- |
+| Ordinary eager tools | Direct                      | Direct and nested               | Nested only      |
+| Deferred tools       | `tool_search` + `tool_call` | Bridge and nested               | Nested only      |
+| Direct-control tools | Direct                      | Direct only                     | Direct only      |
+| `exec`               | Not registered              | Direct                          | Direct           |
+| Hidden bridge tools  | Existing direct behavior    | Direct where already applicable | Hidden           |
 
 In `code_mode`, ordinary visible tool descriptions gain an `exec` declaration
 for that tool. The `exec` description keeps the complete `ALL_TOOLS` metadata
-but does not duplicate every schema. Deferred tools gain their declaration when
-their normal top-level declaration is revealed. In `code_mode_only`, the
-existing behavior remains: all nested declarations live in the `exec`
-description because no later top-level reveal is possible. `tools.eager` and
-`tools.visible` do not reduce those nested schemas in CodeModeOnly: `tool_search`
-is hidden, deferred reminders and the no-ToolSearch warning are skipped, and
-surviving callable tools remain available through `exec`.
+without duplicating every schema. With both bridge tools available, `tool_search`
+returns deferred parameter schemas without changing the top-level declarations.
+Match each returned schema name exactly to `ALL_TOOLS.name`, then invoke
+`tools[entry.jsName]` with arguments shaped by that schema. If there is no entry,
+do not normalize or guess a binding; use `tool_call` outside `exec`, or an
+available direct tool, subject to normal validation and approval.
+
+When either bridge half is absent or the agent surface is filtered, `exec`
+includes signatures for nested tools whose schemas are otherwise unavailable.
+In `code_mode_only`, all nested declarations live in the `exec` description.
+Both bridge tools are hidden, deferred reminders and the incomplete-bridge
+warning are skipped, and `tools.eager` / `tools.visible` do not reduce those
+nested schemas. Callable tools remain available through `exec`.
 
 Nested bindings prefer an exact canonical JavaScript name over names rewritten
 to that property. Other collisions retain canonical-name ordering; omitted

diff --git a/docs/design/code-mode.zh-CN.md b/docs/design/code-mode.zh-CN.md
@@ -42,20 +42,26 @@ CodeModeOnly。
 
 ## 暴露策略
 
-| 调用面       | `direct`             | `code_mode`              | `code_mode_only` |
-| ------------ | -------------------- | ------------------------ | ---------------- |
-| 普通即时工具 | 直接调用             | 直接调用和嵌套调用       | 仅嵌套调用       |
-| 延迟工具     | `tool_search`        | `tool_search` 和嵌套调用 | 仅嵌套调用       |
-| 直接控制工具 | 直接调用             | 仅直接调用               | 仅直接调用       |
-| `exec`       | 未注册               | 直接调用                 | 直接调用         |
-| 隐藏桥接工具 | 保持现有直接模式行为 | 在原本适用时直接调用     | 隐藏             |
+| 调用面       | `direct`                    | `code_mode`          | `code_mode_only` |
+| ------------ | --------------------------- | -------------------- | ---------------- |
+| 普通即时工具 | 直接调用                    | 直接调用和嵌套调用   | 仅嵌套调用       |
+| 延迟工具     | `tool_search` + `tool_call` | 桥接和嵌套调用       | 仅嵌套调用       |
+| 直接控制工具 | 直接调用                    | 仅直接调用           | 仅直接调用       |
+| `exec`       | 未注册                      | 直接调用             | 直接调用         |
+| 隐藏桥接工具 | 保持现有直接模式行为        | 在原本适用时直接调用 | 隐藏             |
 
 在 `code_mode` 中，普通可见工具的描述会附加该工具的 `exec` 调用声明。
-`exec` 描述保留完整的 `ALL_TOOLS` 元数据，但不重复所有 schema。延迟工具在
-按正常流程暴露顶层声明时获得对应声明。在 `code_mode_only` 中保持现有行为：
-由于后续无法暴露顶层声明，所有嵌套声明都集中在 `exec` 描述中。CodeModeOnly 中
-`tools.eager` 和 `tools.visible` 不会减少这些嵌套 schema：`tool_search` 被隐藏，
-延迟提醒和缺少 ToolSearch 的警告被跳过，仍可调用的工具继续通过 `exec` 使用。
+`exec` 描述保留完整的 `ALL_TOOLS` 元数据，但不重复所有 schema。两个桥接工具
+都可用时，`tool_search` 返回延迟工具的参数 schema，不改变顶层声明列表。
+用返回的 schema 名称精确匹配 `ALL_TOOLS.name`，再按该 schema 构造参数调用
+`tools[entry.jsName]`。没有匹配项时不能自行规范化或猜测绑定名称；应在 `exec`
+外使用 `tool_call`，或调用可用的直接工具，沿用正常的参数校验和审批。
+
+任一桥接工具缺失或智能体调用面经过过滤时，`exec` 会为无法从其他途径取得
+schema 的嵌套工具附上签名。在 `code_mode_only` 中，所有嵌套声明集中在 `exec`
+描述中；两个桥接工具都被隐藏，延迟提醒和桥接不完整的警告被跳过。
+`tools.eager` 和 `tools.visible` 不会减少这些嵌套 schema，仍可调用的工具继续
+通过 `exec` 使用。
 
 嵌套绑定优先保留与 JavaScript 属性精确一致的规范名称，再考虑改写为该属性的
 名称。其他碰撞沿用规范名称字典序；被省略的绑定不出现在嵌套签名中，