Return ToolSearch references

Author: SqlRush

docs/cc-100-roadmap.md

@@ -191,7 +191,7 @@ M8 补充：command registry 现在保存本地 skill prompt template，并提
 
 M8 补充：新增基础 `Skill` tool wrapper，已注册到默认内置工具集，可按官方 `skill`/`args` 输入调用项目目录发现到的本地 prompt skill，并兼容 `commandName`/`arguments` 别名；tool result 会返回 `Launching skill: ...`、structured command metadata 和 prompt expansion 生成的 meta user message，conversation runner 现在会把 `ToolResult.NewMessages` 追加进后续模型请求和 transcript。插件目录 skill 可通过工作目录发现和 display name 调用，structured content 会保留 source、loadedFrom、displayName、description、argument metadata、skillRoot、whenToUse、version、context、agent、effort、paths、contentLength 和 progressMessage，方便后续 UI/SDK/remote surface 使用。forked skill、remote/MCP/bundled skill 细节、skill prompt shell injection、slash/local command UI wiring 仍未完成。
 
-M8 补充：新增基础 `ToolSearch` tool 并注册到默认内置工具集，executor 会把当前 tool registry 放入工具 metadata，`ToolSearch` 可按 name、alias、description、prompt、search hint 和 input/output schema 字段搜索当前可用工具定义，返回 BM25-ranked structured results、read-only/concurrency/destructive、input/output schema 以及 `should_defer`/`always_load`/`requires_interaction`/`strict`/cache/eager 等请求提示元数据，并兼容 `query`/`q`/`search` 与 `topn`/`limit` 等输入别名。完整 deferred/lazy tool discovery 仍未完成。
+M8 补充：新增基础 `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`/`q`/`search` 与 `topn`/`limit` 等输入别名。完整 deferred/lazy tool discovery 仍未完成。
 
 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 仍未完成。
 

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

@@ -290,7 +290,7 @@ test/parity/                 # golden tests against TS/official behavior
 - 本轮补充：新增 `internal/commands` registry 基础层，按官方 command 来源顺序合并 bundled/builtin-plugin/project-skill/workflow/plugin/dynamic/builtin metadata，并提供 dynamic 去重、display-name/alias 查找、hidden 过滤、SkillTool/slash-skill 过滤和 bridge-safe 判定；实际 local/local-jsx 执行、`/help`/`/skills` UI、plugin/MCP/workflow 加载仍未宣称完成。
 - 本轮补充：command registry 现在保存本地 skill prompt template，并提供 prompt expansion 入口，覆盖 `$ARGUMENTS`、indexed/shorthand 参数、frontmatter named arguments、`${CLAUDE_SESSION_ID}` 替换、非 MCP skill 的 `${CLAUDE_SKILL_DIR}` 替换和 meta user message 输出；shell injection、SkillTool wrapper、local/local-jsx 执行和 REPL/UI wiring 仍未宣称完成。
 - 本轮补充：新增基础 `Skill` tool wrapper 并注册到默认内置工具集，可调用本地项目 prompt skill、兼容官方 `skill`/`args` 与相邻别名，并把 prompt expansion 产生的 meta user message 通过 `ToolResult.NewMessages` 交给 conversation runner；runner 现在会把这些新消息写入 transcript 并追加到下一轮模型请求。插件目录 skill 可通过工作目录发现和 display name 调用，Skill tool structured content 会保留 source、loadedFrom、displayName、description、argument metadata、skillRoot、whenToUse、version、context、agent、effort、paths、contentLength 和 progressMessage。forked/remote/MCP/bundled skills、plugin skill UI/SDK polish、shell injection、slash/local command UI wiring 仍未宣称完成。
-- 本轮补充：新增基础 `ToolSearch` tool 并注册到默认内置工具集，executor 会把当前 tool registry 注入工具 metadata；`ToolSearch` 可按 name、alias、description、prompt、search hint 搜索当前工具定义，返回 BM25-ranked structured results 和 read-only/concurrency/destructive 以及 `should_defer`/`always_load`/`requires_interaction`/`strict`/cache/eager 等请求提示元数据，并兼容 query/limit 相邻输入别名。deferred/lazy tool discovery 仍未宣称完成。
+- 本轮补充：新增基础 `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 仍未宣称完成。
 - 本轮补充：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 仍未宣称完成。
 - 本轮补充：新增基础 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 仍未宣称完成。
 - 本轮补充：本地 prompt skill slash command 和 `Skill` tool 现在都会生成 `command_permissions` attachment，解析 `allowed-tools` 的 comma/space 分隔形式并保留括号内 tool pattern；Runner 会在当前 turn 内把 attachment 转成 `PermissionSourceCommand` allow rules 合并进 engine permission decider，让 skill 授权的后续工具调用可在同一轮通过。完整权限 UI/SDK 展示、forked/MCP/plugin/bundled skill 权限继承仍未宣称完成。

docs/first-second-parity-audit.md

@@ -88,7 +88,7 @@ Anthropic API 和 conversation：
 - `/plugin <plugin-name>` now takes the no-query local plugin-detail path used by `/plugin show <plugin-name>` when the name matches a local plugin manifest, while unknown one-word subcommands still report unsupported.
 - `/model show`, `/model info`, and `/model current` now take the no-query current-model path instead of treating those words as custom model names and mutating the runner model.
 - A basic `Skill` tool wrapper is now registered with the default built-in tool set. It can invoke local project and plugin-directory prompt skills through the command registry, returns the official-style `Launching skill: ...` result plus structured command metadata, preserves command source/display/root/frontmatter metadata for plugin skills, and passes expanded meta user messages through `ToolResult.NewMessages`; the conversation runner now appends those new messages to transcripts and subsequent model requests.
-- 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, returning BM25-ranked structured results with read-only/concurrency/destructive plus input/output schema, deferred/loading/request-hint metadata, and query/limit aliases.
+- 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.
 - 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`.
 - 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.
 - Local prompt-skill slash commands and the `Skill` tool now emit `command_permissions` attachments, parse `allowed-tools` into command-scoped permission rules, and merge those rules into the engine permission decider for the current turn so authorized follow-up tool calls can pass without leaking into later turns.

internal/contracts/tool.go

@@ -46,6 +46,15 @@ type ToolResult struct {
 	Meta              map[string]any `json:"_meta,omitempty"`
 }
 
+type ToolReference struct {
+	Type     string `json:"type"`
+	ToolName string `json:"tool_name"`
+}
+
+func NewToolReference(name string) ToolReference {
+	return ToolReference{Type: "tool_reference", ToolName: name}
+}
+
 type ToolProgress struct {
 	ToolUseID ID             `json:"tool_use_id"`
 	Type      string         `json:"type"`

internal/conversation/run_test.go

@@ -234,6 +234,75 @@ func TestRunnerExecutesToolUseAndContinuesConversation(t *testing.T) {
 	}
 }
 
+func TestRunnerPreservesToolReferenceResultContent(t *testing.T) {
+	registry, err := tool.NewRegistry(tool.FuncTool{
+		DefinitionValue: contracts.ToolDefinition{
+			Name:        "ToolSearch",
+			Description: "selects tool references",
+			ReadOnly:    true,
+			InputSchema: contracts.JSONSchema{"type": "object"},
+		},
+		CallFunc: func(ctx tool.Context, raw json.RawMessage, sink tool.ProgressSink) (contracts.ToolResult, error) {
+			return contracts.ToolResult{
+				Content: []contracts.ToolReference{
+					contracts.NewToolReference("Read"),
+					contracts.NewToolReference("Edit"),
+				},
+				StructuredContent: map[string]any{
+					"matches": 2,
+				},
+			}, nil
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	client := &fakeClient{calls: []fakeCall{
+		{response: &anthropic.Response{
+			ID:         "msg_tool",
+			Type:       "message",
+			Role:       "assistant",
+			Model:      "sonnet",
+			StopReason: "tool_use",
+			Content: []contracts.ContentBlock{{
+				Type:  contracts.ContentToolUse,
+				ID:    "toolu_search",
+				Name:  "ToolSearch",
+				Input: json.RawMessage(`{"query":"select:Read,Edit"}`),
+			}},
+		}},
+		{response: &anthropic.Response{
+			ID:         "msg_done",
+			Type:       "message",
+			Role:       "assistant",
+			Model:      "sonnet",
+			StopReason: "end_turn",
+			Content:    []contracts.ContentBlock{contracts.NewTextBlock("done")},
+		}},
+	}}
+	runner := Runner{
+		Client:    client,
+		Tools:     tool.NewExecutor(registry),
+		Model:     "sonnet",
+		MaxTokens: 128,
+	}
+	if _, err := runner.RunTurn(context.Background(), nil, messages.UserText("find tools")); err != nil {
+		t.Fatal(err)
+	}
+	if len(client.requests) != 2 {
+		t.Fatalf("requests = %d, want 2", len(client.requests))
+	}
+	last := client.requests[1].Messages[len(client.requests[1].Messages)-1]
+	if last.Role != "user" || len(last.Content) != 1 || last.Content[0].Type != contracts.ContentToolResult {
+		t.Fatalf("last api message = %#v", last)
+	}
+	references, ok := last.Content[0].Content.([]contracts.ToolReference)
+	if !ok || len(references) != 2 || references[0].ToolName != "Read" || references[1].ToolName != "Edit" {
+		t.Fatalf("tool result content = %#v", last.Content[0].Content)
+	}
+}
+
 func TestRunnerExecutesSettingsCommandHookForToolUse(t *testing.T) {
 	registry, err := tool.NewRegistry(tool.FuncTool{
 		DefinitionValue: contracts.ToolDefinition{

internal/tools/searchtools/tools.go

@@ -35,14 +35,39 @@ func NewToolSearchTool() tool.Tool {
 				"properties": map[string]any{
 					"query": map[string]any{
 						"type":        "string",
-						"description": "Search query for available tools.",
+						"description": "Search query for available tools. Use select:ToolA,ToolB to fetch exact tool references.",
 					},
 					"topn": map[string]any{
 						"type":        "integer",
 						"description": "Maximum number of matching tools to return.",
 					},
 				},
 			},
+			OutputSchema: contracts.JSONSchema{
+				"type": "object",
+				"properties": map[string]any{
+					"query":      map[string]any{"type": "string"},
+					"limit":      map[string]any{"type": "integer"},
+					"matches":    map[string]any{"type": "integer"},
+					"ranking":    map[string]any{"type": "string"},
+					"query_type": map[string]any{"type": "string", "enum": []any{"keyword", "select"}},
+					"text":       map[string]any{"type": "string"},
+					"requested":  map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
+					"missing":    map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
+					"tool_references": map[string]any{
+						"type": "array",
+						"items": map[string]any{
+							"type":     "object",
+							"required": []any{"type", "tool_name"},
+							"properties": map[string]any{
+								"type":      map[string]any{"const": "tool_reference"},
+								"tool_name": map[string]any{"type": "string"},
+							},
+						},
+					},
+					"results": map[string]any{"type": "array"},
+				},
+			},
 		},
 		NormalizeFunc:   normalizeSearchInput,
 		ValidateFunc:    validateSearchInput,
@@ -114,13 +139,27 @@ func callToolSearch(ctx tool.Context, raw json.RawMessage, _ tool.ProgressSink)
 	if err != nil {
 		return contracts.ToolResult{}, err
 	}
-	results := matchToolDefinitions(definitions, input.Query, limit)
+	queryType := "keyword"
+	ranking := "bm25"
+	var requested []string
+	var missing []string
+	var results []scoredDefinition
+	if selectNames, ok := parseSelectQuery(input.Query); ok {
+		queryType = "select"
+		ranking = "select"
+		requested = selectNames
+		results, missing = selectToolDefinitions(definitions, selectNames)
+	} else {
+		results = matchToolDefinitions(definitions, input.Query, limit)
+	}
 	structuredResults := make([]map[string]any, 0, len(results))
 	lines := []string{
 		"Tool search: " + strings.TrimSpace(input.Query),
 		fmt.Sprintf("Matches: %d", len(results)),
 	}
+	toolReferences := make([]contracts.ToolReference, 0, len(results))
 	for _, result := range results {
+		toolReferences = append(toolReferences, contracts.NewToolReference(result.Definition.Name))
 		entry := map[string]any{
 			"name":                  result.Definition.Name,
 			"score":                 result.Score,
@@ -162,15 +201,31 @@ func callToolSearch(ctx tool.Context, raw json.RawMessage, _ tool.ProgressSink)
 	if len(results) == 0 {
 		lines = append(lines, "No tools matched.")
 	}
+	if len(missing) > 0 {
+		lines = append(lines, "Missing: "+strings.Join(missing, ", "))
+	}
+	text := strings.Join(lines, "\n")
+	content := any(text)
+	if len(toolReferences) > 0 {
+		content = toolReferences
+	}
+	structured := map[string]any{
+		"query":           strings.TrimSpace(input.Query),
+		"limit":           limit,
+		"matches":         len(results),
+		"ranking":         ranking,
+		"query_type":      queryType,
+		"text":            text,
+		"tool_references": toolReferences,
+		"results":         structuredResults,
+	}
+	if queryType == "select" {
+		structured["requested"] = requested
+		structured["missing"] = missing
+	}
 	return contracts.ToolResult{
-		Content: strings.Join(lines, "\n"),
-		StructuredContent: map[string]any{
-			"query":   strings.TrimSpace(input.Query),
-			"limit":   limit,
-			"matches": len(results),
-			"ranking": "bm25",
-			"results": structuredResults,
-		},
+		Content:           content,
+		StructuredContent: structured,
 	}, nil
 }
 
@@ -218,6 +273,55 @@ func matchToolDefinitions(definitions []contracts.ToolDefinition, query string,
 	return results
 }
 
+func parseSelectQuery(query string) ([]string, bool) {
+	trimmed := strings.TrimSpace(query)
+	if !strings.HasPrefix(strings.ToLower(trimmed), "select:") {
+		return nil, false
+	}
+	rawNames := strings.Split(trimmed[len("select:"):], ",")
+	names := make([]string, 0, len(rawNames))
+	for _, rawName := range rawNames {
+		name := strings.TrimSpace(rawName)
+		if name != "" {
+			names = append(names, name)
+		}
+	}
+	return names, true
+}
+
+func selectToolDefinitions(definitions []contracts.ToolDefinition, names []string) ([]scoredDefinition, []string) {
+	selected := make([]scoredDefinition, 0, len(names))
+	missing := make([]string, 0)
+	seen := map[string]struct{}{}
+	for _, name := range names {
+		definition, ok := findToolDefinition(definitions, name)
+		if !ok {
+			missing = append(missing, name)
+			continue
+		}
+		if _, ok := seen[definition.Name]; ok {
+			continue
+		}
+		seen[definition.Name] = struct{}{}
+		selected = append(selected, scoredDefinition{Definition: definition, Score: 1})
+	}
+	return selected, missing
+}
+
+func findToolDefinition(definitions []contracts.ToolDefinition, name string) (contracts.ToolDefinition, bool) {
+	for _, definition := range definitions {
+		if strings.EqualFold(definition.Name, name) {
+			return definition, true
+		}
+		for _, alias := range definition.Aliases {
+			if strings.EqualFold(alias, name) {
+				return definition, true
+			}
+		}
+	}
+	return contracts.ToolDefinition{}, false
+}
+
 func buildBM25Corpus(definitions []contracts.ToolDefinition) bm25Corpus {
 	documents := make([]bm25Document, 0, len(definitions))
 	documentCounts := map[string]int{}