Filter deferred tools during ToolSearch

Author: SqlRush

cmd/claude/main_test.go

@@ -87,20 +87,14 @@ func TestRunPrintSendsPromptAndPrintsAssistantText(t *testing.T) {
 		t.Fatalf("max_tokens = %#v", requestBody["max_tokens"])
 	}
 	messages, ok := requestBody["messages"].([]any)
-	if !ok || len(messages) != 1 {
+	if !ok || len(messages) < 1 {
 		t.Fatalf("messages = %#v", requestBody["messages"])
 	}
-	message, ok := messages[0].(map[string]any)
-	if !ok || message["role"] != "user" {
-		t.Fatalf("message = %#v", messages[0])
+	if !hasAvailableDeferredToolsMessage(messages) {
+		t.Fatalf("missing deferred tools message: %#v", messages)
 	}
-	content, ok := message["content"].([]any)
-	if !ok || len(content) != 1 {
-		t.Fatalf("content = %#v", message["content"])
-	}
-	block, ok := content[0].(map[string]any)
-	if !ok || block["type"] != "text" || block["text"] != "say hello" {
-		t.Fatalf("block = %#v", content[0])
+	if got := messageTextAt(t, messages, 0); got != "say hello" {
+		t.Fatalf("prompt = %q", got)
 	}
 	tools, ok := requestBody["tools"].([]any)
 	if !ok || len(tools) == 0 {
@@ -1049,8 +1043,7 @@ func TestRunPrintReadsPromptFromStdinAndSettingsModel(t *testing.T) {
 		t.Fatalf("model = %#v", requestBody["model"])
 	}
 	messages := requestBody["messages"].([]any)
-	content := messages[0].(map[string]any)["content"].([]any)
-	if got := content[0].(map[string]any)["text"]; got != "from stdin" {
+	if got := messageTextAt(t, messages, 0); got != "from stdin" {
 		t.Fatalf("prompt = %#v", got)
 	}
 }
@@ -2889,22 +2882,10 @@ func TestRunPrintStreamJSONIncludesToolProgress(t *testing.T) {
 		t.Fatalf("exit = %d stderr=%s stdout=%s", code, stderr.String(), stdout.String())
 	}
 	messages, ok := requestBody["messages"].([]any)
-	if !ok || len(messages) != 1 {
+	if !ok || len(messages) < 1 {
 		t.Fatalf("messages = %#v", requestBody["messages"])
 	}
-	message, ok := messages[0].(map[string]any)
-	if !ok {
-		t.Fatalf("message = %#v", messages[0])
-	}
-	content, ok := message["content"].([]any)
-	if !ok || len(content) != 1 {
-		t.Fatalf("content = %#v", message["content"])
-	}
-	block, ok := content[0].(map[string]any)
-	if !ok {
-		t.Fatalf("block = %#v", content[0])
-	}
-	prompt, _ := block["text"].(string)
+	prompt := messageTextAt(t, messages, 0)
 	if !strings.Contains(prompt, "stream prompt") || !strings.Contains(prompt, "stream hook context") {
 		t.Fatalf("prompt = %q", prompt)
 	}
@@ -3937,15 +3918,53 @@ func writeTestTranscript(t *testing.T, path string, sessionID contracts.ID, user
 
 func messageTextAt(t *testing.T, requestMessages []any, index int) string {
 	t.Helper()
-	if index >= len(requestMessages) {
+	filtered := nonDeferredToolMessages(requestMessages)
+	if index >= len(filtered) {
 		t.Fatalf("messages = %#v", requestMessages)
 	}
-	message := requestMessages[index].(map[string]any)
+	message := filtered[index].(map[string]any)
 	content := message["content"].([]any)
 	block := content[0].(map[string]any)
 	return block["text"].(string)
 }
 
+func nonDeferredToolMessages(requestMessages []any) []any {
+	filtered := make([]any, 0, len(requestMessages))
+	for _, message := range requestMessages {
+		if isAvailableDeferredToolsMessage(message) {
+			continue
+		}
+		filtered = append(filtered, message)
+	}
+	return filtered
+}
+
+func hasAvailableDeferredToolsMessage(requestMessages []any) bool {
+	for _, message := range requestMessages {
+		if isAvailableDeferredToolsMessage(message) {
+			return true
+		}
+	}
+	return false
+}
+
+func isAvailableDeferredToolsMessage(message any) bool {
+	item, ok := message.(map[string]any)
+	if !ok || item["role"] != "user" {
+		return false
+	}
+	content, ok := item["content"].([]any)
+	if !ok || len(content) == 0 {
+		return false
+	}
+	block, ok := content[0].(map[string]any)
+	if !ok {
+		return false
+	}
+	text, _ := block["text"].(string)
+	return strings.HasPrefix(text, "<available-deferred-tools>\n")
+}
+
 func containsAnyString(values []any, want string) bool {
 	for _, value := range values {
 		if text, ok := value.(string); ok && text == want {

docs/cc-100-roadmap.md

@@ -197,6 +197,8 @@ M8/M2 补充：conversation `BuildRequest` 现在会扫描历史 `tool_result.co
 
 M8/M6 补充：compact plan 现在会把 compact 前已发现的 `tool_reference` 名称快照进 `compactMetadata.preCompactDiscoveredTools`，session transcript alias/resume 转换会保留该 metadata，conversation `BuildRequest` 可在 tool-result 消息被 summary 替换后继续从 compact boundary 恢复已发现工具并取消 `defer_loading`。完整官方 compact/snipping 边界策略仍未完成。
 
+M8/M2 补充：当 `ToolSearch` 可用且存在 deferred 工具时，conversation request 现在会按官方 dynamic tool loading 过滤请求工具：未发现 deferred 工具不发送 schema，已发现 deferred 工具作为 loaded tool 发送，`ToolSearch` 保持可调用，并在 API messages 前置 `<available-deferred-tools>` 名称列表；没有 deferred 工具时会从请求中移除 `ToolSearch`。
+
 M8/M2 补充：Anthropic request tool 转换现在会保留 contract 的 `strict`、`eager_input_streaming`、`cache_control` 与 `should_defer`，将 deferred 工具序列化为 API `defer_loading`，并用 `always_load` 覆盖 deferred hint；API tool description 会按 description、prompt、searchHint 顺序 fallback，conversation runner 构造请求时会把 `Task` 等 deferred tool 的 strict/defer_loading 元数据带到最终请求。完整 deferred/lazy tool discovery 仍未完成。
 
 M8/M5 补充：tool executor 现在会在未通过 `ToolSearch` 发现的 deferred 工具输入 schema 校验失败时追加 schema-not-sent 恢复提示，指导模型先调用 `ToolSearch` 的 `select:<tool>` 再重试；conversation runner 会把当前 turn messages 放进工具 metadata，提示判断兼容普通 `tool_reference` 结果和 compact boundary 已发现工具快照。

docs/claude-code-go-rewrite-plan.md

@@ -293,6 +293,7 @@ test/parity/                 # golden tests against TS/official behavior
 - 本轮补充：新增基础 `ToolSearch` tool 并注册到默认内置工具集，executor 会把当前 tool registry 注入工具 metadata；`ToolSearch` 可按 name、alias、description、prompt、search hint 和 input/output schema 字段搜索当前工具定义，支持 `select:ToolA,ToolB` 直接选择并返回 `tool_reference` content，返回 BM25/select structured results 和 read-only/concurrency/destructive、input/output schema 以及 `should_defer`/`always_load`/`requires_interaction`/`strict`/cache/eager 等请求提示元数据，并兼容 query/limit 相邻输入别名。deferred/lazy tool discovery 仍未宣称完成。
 - 本轮补充：conversation `BuildRequest` 会扫描历史 `tool_result.content` 中的 `tool_reference`，并把已发现工具在后续 API request 中作为 loaded tool 发送，不再携带 `defer_loading`；扫描兼容运行时 `ToolReference` 值和 transcript/JSON 解码后的 map 形态。完整官方 tool-reference expansion/filtering 仍未宣称完成。
 - 本轮补充：compact plan 会把 compact 前已发现的 `tool_reference` 名称快照进 `compactMetadata.preCompactDiscoveredTools`，session transcript alias/resume 转换会保留该 metadata，conversation `BuildRequest` 可在 tool-result 消息被 summary 替换后继续从 compact boundary 恢复已发现工具并取消 `defer_loading`。完整官方 compact/snipping 边界策略仍未宣称完成。
+- 本轮补充：当 request registry 同时存在 `ToolSearch` 和 deferred 工具时，conversation request 会按官方 dynamic tool loading 过滤工具列表：未发现 deferred 工具不再发送 schema，已发现 deferred 工具作为 loaded tool 发送，`ToolSearch` 保持可调用，并在首条 API user message 前注入 `<available-deferred-tools>` 名称列表；没有 deferred 工具时会从请求中移除 `ToolSearch`。
 - 本轮补充：Anthropic request tool 转换会保留 contract 的 `strict`、`eager_input_streaming`、`cache_control` 与 `should_defer`，把 deferred 工具序列化为 API `defer_loading`，并让 `always_load` 覆盖 deferred hint；API tool description 会按 description、prompt、searchHint 顺序 fallback，conversation runner 构造请求时会保留 `Task` 等 deferred tool 的 strict/defer_loading 元数据。完整 deferred/lazy tool discovery 仍未宣称完成。
 - 本轮补充：tool executor 会在未通过 `ToolSearch` 发现的 deferred 工具发生输入 schema 校验失败时追加 schema-not-sent 恢复提示，引导模型先调用 `ToolSearch` 的 `select:<tool>` 再重试；runner 会把当前 turn messages 传入工具 metadata，提示判断兼容 `tool_reference` 结果和 compact boundary 的已发现工具快照。
 - 本轮补充：新增基础 slash command parser/executor，支持官方 `/command args` 和 `/mcp:tool (MCP) args` 解析；conversation runner 现在会在请求模型前展开本地项目 prompt skill slash command，生成 command metadata user message 和 meta prompt message，保留 transcript parent chain，并支持 skill `model` 覆盖本轮请求。local/local-jsx 目前只返回未实现输出且不会误发模型，command permissions attachment、forked/MCP/plugin/bundled slash command 和 UI wiring 仍未宣称完成。

docs/first-second-parity-audit.md

@@ -91,6 +91,7 @@ Anthropic API 和 conversation：
 - A basic `ToolSearch` tool is now registered with the default built-in tool set. The executor exposes the current registry through tool metadata, and `ToolSearch` can search available definitions by name, alias, description, prompt, search hint, and input/output schema fields, supports `select:ToolA,ToolB` direct selection, and returns tool-reference content plus BM25/select structured results with read-only/concurrency/destructive, input/output schema, deferred/loading/request-hint metadata, and query/limit aliases.
 - Conversation request construction now scans previous `tool_result` blocks for `tool_reference` content from `ToolSearch`; referenced tools are copied into the next API request without `defer_loading`, including both in-memory `ToolReference` values and decoded transcript map forms.
 - Compact planning now snapshots discovered `tool_reference` names into `compactMetadata.preCompactDiscoveredTools`; resume/transcript conversion preserves that metadata and request construction reloads those tools after compacted `tool_result` messages have been summarized away.
+- When `ToolSearch` is available and deferred tools exist, request construction now follows dynamic tool loading: undiscovered deferred schemas are omitted from `tools`, discovered deferred tools are loaded, `ToolSearch` stays callable, and an `<available-deferred-tools>` user meta message advertises the deferred tool names; if no deferred tools exist, `ToolSearch` is omitted from the request.
 - Anthropic request tool conversion now preserves contract-level `strict`, `eager_input_streaming`, `cache_control`, and API-level `defer_loading` hints from deferred tool definitions, with `always_load` overriding `should_defer`; it also falls back from `description` to `prompt` to `searchHint` when building API tool descriptions. Runner request construction preserves these fields for tools such as `Task`.
 - Tool validation now appends an official-style schema-not-sent recovery hint when an undiscovered deferred tool is invoked with invalid typed input and `ToolSearch` is available, including compact-boundary discovered-tool metadata so already loaded tools do not get a false hint.
 - Basic slash prompt command invocation is now wired for local project prompt skills: `/skill args` is parsed before the model request, converted into official-shaped command metadata plus expanded meta prompt messages, appended to transcript parent chains, and can override the turn model from skill frontmatter.

internal/conversation/request.go

@@ -1,6 +1,7 @@
 package conversation
 
 import (
+	"sort"
 	"strings"
 	"time"
 
@@ -48,14 +49,44 @@ func (r Runner) buildRequest(history []contracts.Message, model string, relevant
 		if err != nil {
 			return anthropic.Request{}, err
 		}
-		definitions = applyDiscoveredToolReferences(definitions, history)
+		definitions, deferredToolNames := filterToolSearchDefinitions(definitions, history)
+		if len(deferredToolNames) > 0 {
+			request.Messages = prependAvailableDeferredToolsMessage(request.Messages, deferredToolNames)
+		}
 		if len(definitions) > 0 {
 			request.Tools = anthropic.ToolsFromContracts(definitions)
 		}
 	}
 	return request, nil
 }
 
+func filterToolSearchDefinitions(definitions []contracts.ToolDefinition, history []contracts.Message) ([]contracts.ToolDefinition, []string) {
+	if len(definitions) == 0 {
+		return definitions, nil
+	}
+	if !hasToolSearchDefinition(definitions) {
+		return applyDiscoveredToolReferences(definitions, history), nil
+	}
+	deferredNames := deferredToolNames(definitions)
+	if len(deferredNames) == 0 {
+		return withoutToolSearchDefinition(definitions), nil
+	}
+	discovered := discoveredToolReferenceNames(history)
+	out := make([]contracts.ToolDefinition, 0, len(definitions))
+	for _, definition := range definitions {
+		if isToolSearchDefinition(definition) || !toolDefinitionDeferred(definition) {
+			out = append(out, definition)
+			continue
+		}
+		if toolDefinitionDiscovered(definition, discovered) {
+			definition.AlwaysLoad = true
+			definition.ShouldDefer = false
+			out = append(out, definition)
+		}
+	}
+	return out, deferredNames
+}
+
 func applyDiscoveredToolReferences(definitions []contracts.ToolDefinition, history []contracts.Message) []contracts.ToolDefinition {
 	discovered := discoveredToolReferenceNames(history)
 	if len(discovered) == 0 || len(definitions) == 0 {
@@ -72,6 +103,63 @@ func applyDiscoveredToolReferences(definitions []contracts.ToolDefinition, histo
 	return out
 }
 
+func prependAvailableDeferredToolsMessage(messages []contracts.APIMessage, toolNames []string) []contracts.APIMessage {
+	if len(toolNames) == 0 {
+		return messages
+	}
+	content := "<available-deferred-tools>\n" + strings.Join(toolNames, "\n") + "\n</available-deferred-tools>"
+	out := make([]contracts.APIMessage, 0, len(messages)+1)
+	out = append(out, contracts.APIMessage{Role: "user", Content: []contracts.ContentBlock{contracts.NewTextBlock(content)}})
+	out = append(out, messages...)
+	return out
+}
+
+func deferredToolNames(definitions []contracts.ToolDefinition) []string {
+	var names []string
+	for _, definition := range definitions {
+		if toolDefinitionDeferred(definition) {
+			names = append(names, definition.Name)
+		}
+	}
+	sort.Strings(names)
+	return names
+}
+
+func toolDefinitionDeferred(definition contracts.ToolDefinition) bool {
+	return definition.ShouldDefer && !definition.AlwaysLoad && !isToolSearchDefinition(definition)
+}
+
+func hasToolSearchDefinition(definitions []contracts.ToolDefinition) bool {
+	for _, definition := range definitions {
+		if isToolSearchDefinition(definition) {
+			return true
+		}
+	}
+	return false
+}
+
+func withoutToolSearchDefinition(definitions []contracts.ToolDefinition) []contracts.ToolDefinition {
+	out := make([]contracts.ToolDefinition, 0, len(definitions))
+	for _, definition := range definitions {
+		if !isToolSearchDefinition(definition) {
+			out = append(out, definition)
+		}
+	}
+	return out
+}
+
+func isToolSearchDefinition(definition contracts.ToolDefinition) bool {
+	if strings.EqualFold(strings.TrimSpace(definition.Name), "ToolSearch") {
+		return true
+	}
+	for _, alias := range definition.Aliases {
+		if strings.EqualFold(strings.TrimSpace(alias), "ToolSearch") {
+			return true
+		}
+	}
+	return false
+}
+
 func toolDefinitionDiscovered(definition contracts.ToolDefinition, discovered map[string]struct{}) bool {
 	if _, ok := discovered[strings.ToLower(definition.Name)]; ok {
 		return true

internal/conversation/run_test.go

@@ -36,6 +36,7 @@ import (
 	telemetrypkg "ccgo/internal/telemetry"
 	"ccgo/internal/tool"
 	filetools "ccgo/internal/tools/file"
+	searchtools "ccgo/internal/tools/searchtools"
 	skilltools "ccgo/internal/tools/skill"
 	tasktools "ccgo/internal/tools/task"
 )
@@ -7864,6 +7865,15 @@ func requestHasTool(request anthropic.Request, name string) bool {
 	return false
 }
 
+func requestTool(request anthropic.Request, name string) anthropic.ToolDefinition {
+	for _, definition := range request.Tools {
+		if definition.Name == name {
+			return definition
+		}
+	}
+	return anthropic.ToolDefinition{}
+}
+
 func bridgeManifestHasCommand(manifest bridgepkg.Manifest, name string) bool {
 	for _, command := range manifest.Commands {
 		if command.Name == name {
@@ -7978,6 +7988,102 @@ func TestBuildRequestPreservesDeferredToolMetadata(t *testing.T) {
 	}
 }
 
+func TestBuildRequestWithToolSearchOmitsUndiscoveredDeferredTools(t *testing.T) {
+	registry, err := tool.NewRegistry(tasktools.NewTaskTool(), searchtools.NewToolSearchTool())
+	if err != nil {
+		t.Fatal(err)
+	}
+	runner := Runner{
+		Tools:     tool.NewExecutor(registry),
+		Model:     "sonnet",
+		MaxTokens: 100,
+	}
+	req, err := runner.BuildRequest([]contracts.Message{messages.UserText("hi")}, "sonnet")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(req.Tools) != 1 || req.Tools[0].Name != "ToolSearch" {
+		t.Fatalf("tools = %#v", req.Tools)
+	}
+	if len(req.Messages) != 2 {
+		t.Fatalf("messages = %#v", req.Messages)
+	}
+	deferred := req.Messages[0]
+	if deferred.Role != "user" || !strings.Contains(deferred.Content[0].Text, "<available-deferred-tools>\nTask\n</available-deferred-tools>") {
+		t.Fatalf("deferred tools message = %#v", deferred)
+	}
+	if got := req.Messages[1].Content[0].Text; got != "hi" {
+		t.Fatalf("original user message = %q", got)
+	}
+}
+
+func TestBuildRequestWithToolSearchLoadsDiscoveredDeferredTools(t *testing.T) {
+	registry, err := tool.NewRegistry(tasktools.NewTaskTool(), searchtools.NewToolSearchTool())
+	if err != nil {
+		t.Fatal(err)
+	}
+	runner := Runner{
+		Tools:     tool.NewExecutor(registry),
+		Model:     "sonnet",
+		MaxTokens: 100,
+	}
+	history := []contracts.Message{
+		messages.UserText("find task"),
+		{
+			Type: contracts.MessageUser,
+			Content: []contracts.ContentBlock{{
+				Type:      contracts.ContentToolResult,
+				ToolUseID: "toolu_search",
+				Content:   []contracts.ToolReference{contracts.NewToolReference("Task")},
+			}},
+		},
+	}
+	req, err := runner.BuildRequest(history, "sonnet")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !requestHasTool(req, "ToolSearch") || !requestHasTool(req, "Task") || len(req.Tools) != 2 {
+		t.Fatalf("tools = %#v", req.Tools)
+	}
+	taskTool := requestTool(req, "Task")
+	if taskTool.DeferLoading {
+		t.Fatalf("discovered task defer_loading = true")
+	}
+	if len(req.Messages) < 1 || !strings.Contains(req.Messages[0].Content[0].Text, "<available-deferred-tools>\nTask\n</available-deferred-tools>") {
+		t.Fatalf("messages = %#v", req.Messages)
+	}
+}
+
+func TestBuildRequestWithToolSearchButNoDeferredToolsOmitsToolSearch(t *testing.T) {
+	registry, err := tool.NewRegistry(
+		tool.FuncTool{DefinitionValue: contracts.ToolDefinition{
+			Name:        "Read",
+			Description: "read a file",
+			ReadOnly:    true,
+			InputSchema: contracts.JSONSchema{"type": "object"},
+		}},
+		searchtools.NewToolSearchTool(),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	runner := Runner{
+		Tools:     tool.NewExecutor(registry),
+		Model:     "sonnet",
+		MaxTokens: 100,
+	}
+	req, err := runner.BuildRequest([]contracts.Message{messages.UserText("hi")}, "sonnet")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(req.Tools) != 1 || req.Tools[0].Name != "Read" {
+		t.Fatalf("tools = %#v", req.Tools)
+	}
+	if len(req.Messages) != 1 || req.Messages[0].Content[0].Text != "hi" {
+		t.Fatalf("messages = %#v", req.Messages)
+	}
+}
+
 func TestBuildRequestLoadsDiscoveredToolReferences(t *testing.T) {
 	registry, err := tool.NewRegistry(tasktools.NewTaskTool())
 	if err != nil {