Strip inactive tool references from requests

Author: SqlRush

docs/cc-100-roadmap.md

@@ -199,6 +199,8 @@ M8/M6 补充：compact plan 现在会把 compact 前已发现的 `tool_reference
 
 M8/M2 补充：当 `ToolSearch` 可用且存在 deferred 工具时，conversation request 现在会按官方 dynamic tool loading 过滤请求工具：未发现 deferred 工具不发送 schema，已发现 deferred 工具作为 loaded tool 发送，`ToolSearch` 保持可调用，并在 API messages 前置 `<available-deferred-tools>` 名称列表；没有 deferred 工具时会从请求中移除 `ToolSearch`。
 
+M8/M2 补充：当本次 request 未启用 `ToolSearch` 时，conversation request 现在会从 API user `tool_result.content` 中剥离历史 `tool_reference` blocks；纯 reference 结果会替换为官方占位文本 `[Tool references removed - tool search not enabled]`，剥离发生在 discovered-tool 扫描之后，避免影响后续 loaded 工具恢复。
+
 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

@@ -294,6 +294,7 @@ test/parity/                 # golden tests against TS/official behavior
 - 本轮补充：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`。
+- 本轮补充：当本次 request 未启用 `ToolSearch` 时，API message normalization 会从历史 user `tool_result.content` 中剥离 `tool_reference` blocks；纯 reference 结果会替换成官方占位文本 `[Tool references removed - tool search not enabled]`，但剥离发生在 discovered-tool 扫描之后，不影响后续启用 ToolSearch 时恢复 loaded 工具。
 - 本轮补充：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

@@ -92,6 +92,7 @@ Anthropic API 和 conversation：
 - 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.
+- When ToolSearch is inactive for a request, API message normalization strips historical `tool_reference` blocks from user `tool_result` content and replaces pure-reference results with the official placeholder text, while preserving history scanning before stripping so discovered tools can still be loaded when ToolSearch is active.
 - 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

@@ -36,40 +36,47 @@ func (r Runner) buildRequest(history []contracts.Message, model string, relevant
 		}
 	}
 	history = memory.ExpandRelevantMemoryAttachments(history, time.Time{})
+	var definitions []contracts.ToolDefinition
+	var deferredToolNames []string
+	toolSearchActive := false
+	if r.Tools.Registry != nil {
+		defs, err := r.Tools.Registry.Definitions(toolPromptContext(r))
+		if err != nil {
+			return anthropic.Request{}, err
+		}
+		definitions, deferredToolNames, toolSearchActive = filterToolSearchDefinitions(defs, history)
+	}
+	apiMessages := msgs.NormalizeForAPI(history)
+	if !toolSearchActive {
+		apiMessages = stripToolReferenceBlocksFromAPIMessages(apiMessages)
+	}
+	if len(deferredToolNames) > 0 {
+		apiMessages = prependAvailableDeferredToolsMessage(apiMessages, deferredToolNames)
+	}
 	request := anthropic.Request{
 		Model:     model,
 		MaxTokens: r.maxTokens(),
-		Messages:  msgs.NormalizeForAPI(history),
+		Messages:  apiMessages,
 	}
 	if system := r.systemPromptWithOutputStyle(); system != "" {
 		request.System = system
 	}
-	if r.Tools.Registry != nil {
-		definitions, err := r.Tools.Registry.Definitions(toolPromptContext(r))
-		if err != nil {
-			return anthropic.Request{}, err
-		}
-		definitions, deferredToolNames := filterToolSearchDefinitions(definitions, history)
-		if len(deferredToolNames) > 0 {
-			request.Messages = prependAvailableDeferredToolsMessage(request.Messages, deferredToolNames)
-		}
-		if len(definitions) > 0 {
-			request.Tools = anthropic.ToolsFromContracts(definitions)
-		}
+	if len(definitions) > 0 {
+		request.Tools = anthropic.ToolsFromContracts(definitions)
 	}
 	return request, nil
 }
 
-func filterToolSearchDefinitions(definitions []contracts.ToolDefinition, history []contracts.Message) ([]contracts.ToolDefinition, []string) {
+func filterToolSearchDefinitions(definitions []contracts.ToolDefinition, history []contracts.Message) ([]contracts.ToolDefinition, []string, bool) {
 	if len(definitions) == 0 {
-		return definitions, nil
+		return definitions, nil, false
 	}
 	if !hasToolSearchDefinition(definitions) {
-		return applyDiscoveredToolReferences(definitions, history), nil
+		return applyDiscoveredToolReferences(definitions, history), nil, false
 	}
 	deferredNames := deferredToolNames(definitions)
 	if len(deferredNames) == 0 {
-		return withoutToolSearchDefinition(definitions), nil
+		return withoutToolSearchDefinition(definitions), nil, false
 	}
 	discovered := discoveredToolReferenceNames(history)
 	out := make([]contracts.ToolDefinition, 0, len(definitions))
@@ -84,7 +91,7 @@ func filterToolSearchDefinitions(definitions []contracts.ToolDefinition, history
 			out = append(out, definition)
 		}
 	}
-	return out, deferredNames
+	return out, deferredNames, true
 }
 
 func applyDiscoveredToolReferences(definitions []contracts.ToolDefinition, history []contracts.Message) []contracts.ToolDefinition {
@@ -114,6 +121,89 @@ func prependAvailableDeferredToolsMessage(messages []contracts.APIMessage, toolN
 	return out
 }
 
+func stripToolReferenceBlocksFromAPIMessages(messages []contracts.APIMessage) []contracts.APIMessage {
+	out := make([]contracts.APIMessage, len(messages))
+	for i, message := range messages {
+		out[i] = message
+		if message.Role != "user" {
+			continue
+		}
+		out[i].Content = stripToolReferenceBlocksFromContent(message.Content)
+	}
+	return out
+}
+
+func stripToolReferenceBlocksFromContent(content []contracts.ContentBlock) []contracts.ContentBlock {
+	out := make([]contracts.ContentBlock, len(content))
+	for i, block := range content {
+		out[i] = block
+		if block.Type != contracts.ContentToolResult {
+			continue
+		}
+		if stripped, ok := stripToolReferenceItems(block.Content); ok {
+			out[i].Content = stripped
+		}
+	}
+	return out
+}
+
+func stripToolReferenceItems(content any) (any, bool) {
+	items, ok := toolResultContentItems(content)
+	if !ok {
+		return content, false
+	}
+	filtered := make([]any, 0, len(items))
+	removed := false
+	for _, item := range items {
+		if toolReferenceItem(item) {
+			removed = true
+			continue
+		}
+		filtered = append(filtered, item)
+	}
+	if !removed {
+		return content, false
+	}
+	if len(filtered) == 0 {
+		return []contracts.ContentBlock{contracts.NewTextBlock("[Tool references removed - tool search not enabled]")}, true
+	}
+	return filtered, true
+}
+
+func toolResultContentItems(content any) ([]any, bool) {
+	switch typed := content.(type) {
+	case []any:
+		return typed, true
+	case []contracts.ToolReference:
+		out := make([]any, 0, len(typed))
+		for _, item := range typed {
+			out = append(out, item)
+		}
+		return out, true
+	case []contracts.ContentBlock:
+		out := make([]any, 0, len(typed))
+		for _, item := range typed {
+			out = append(out, item)
+		}
+		return out, true
+	default:
+		return nil, false
+	}
+}
+
+func toolReferenceItem(item any) bool {
+	switch typed := item.(type) {
+	case contracts.ToolReference:
+		return typed.Type == "tool_reference"
+	case map[string]any:
+		return toolReferenceType(typed)
+	case contracts.ContentBlock:
+		return typed.Type == "tool_reference"
+	default:
+		return false
+	}
+}
+
 func deferredToolNames(definitions []contracts.ToolDefinition) []string {
 	var names []string
 	for _, definition := range definitions {

internal/conversation/run_test.go

@@ -354,18 +354,26 @@ func TestRunnerPreservesToolReferenceResultContent(t *testing.T) {
 		Model:     "sonnet",
 		MaxTokens: 128,
 	}
-	if _, err := runner.RunTurn(context.Background(), nil, messages.UserText("find tools")); err != nil {
+	result, err := runner.RunTurn(context.Background(), nil, messages.UserText("find tools"))
+	if err != nil {
 		t.Fatal(err)
 	}
+	if len(result.ToolResults) != 1 {
+		t.Fatalf("tool results = %#v", result.ToolResults)
+	}
+	references, ok := result.ToolResults[0].Content.([]contracts.ToolReference)
+	if !ok || len(references) != 2 || references[0].ToolName != "Read" || references[1].ToolName != "Edit" {
+		t.Fatalf("runner tool result content = %#v", result.ToolResults[0].Content)
+	}
 	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" {
+	placeholder, ok := last.Content[0].Content.([]contracts.ContentBlock)
+	if !ok || len(placeholder) != 1 || placeholder[0].Text != "[Tool references removed - tool search not enabled]" {
 		t.Fatalf("tool result content = %#v", last.Content[0].Content)
 	}
 }
@@ -8084,6 +8092,104 @@ func TestBuildRequestWithToolSearchButNoDeferredToolsOmitsToolSearch(t *testing.
 	}
 }
 
+func TestBuildRequestStripsToolReferencesWhenToolSearchInactive(t *testing.T) {
+	registry, err := tool.NewRegistry(tasktools.NewTaskTool())
+	if err != nil {
+		t.Fatal(err)
+	}
+	runner := Runner{
+		Tools:     tool.NewExecutor(registry),
+		Model:     "sonnet",
+		MaxTokens: 100,
+	}
+	history := []contracts.Message{{
+		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 len(req.Messages) != 1 {
+		t.Fatalf("messages = %#v", req.Messages)
+	}
+	block := req.Messages[0].Content[0]
+	items, ok := block.Content.([]contracts.ContentBlock)
+	if !ok || len(items) != 1 || items[0].Text != "[Tool references removed - tool search not enabled]" {
+		t.Fatalf("tool result content = %#v", block.Content)
+	}
+	if !requestHasTool(req, "Task") || requestTool(req, "Task").DeferLoading {
+		t.Fatalf("tools = %#v", req.Tools)
+	}
+}
+
+func TestBuildRequestStripsOnlyToolReferencesFromMixedContentWhenInactive(t *testing.T) {
+	registry, err := tool.NewRegistry(tasktools.NewTaskTool())
+	if err != nil {
+		t.Fatal(err)
+	}
+	runner := Runner{
+		Tools:     tool.NewExecutor(registry),
+		Model:     "sonnet",
+		MaxTokens: 100,
+	}
+	history := []contracts.Message{{
+		Type: contracts.MessageUser,
+		Content: []contracts.ContentBlock{{
+			Type:      contracts.ContentToolResult,
+			ToolUseID: "toolu_search",
+			Content: []any{
+				map[string]any{"type": "text", "text": "kept"},
+				map[string]any{"type": "tool_reference", "tool_name": "Task"},
+			},
+		}},
+	}}
+	req, err := runner.BuildRequest(history, "sonnet")
+	if err != nil {
+		t.Fatal(err)
+	}
+	items, ok := req.Messages[0].Content[0].Content.([]any)
+	if !ok || len(items) != 1 {
+		t.Fatalf("tool result content = %#v", req.Messages[0].Content[0].Content)
+	}
+	item, ok := items[0].(map[string]any)
+	if !ok || item["type"] != "text" || item["text"] != "kept" {
+		t.Fatalf("kept item = %#v", items[0])
+	}
+}
+
+func TestBuildRequestKeepsToolReferencesWhenToolSearchActive(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{{
+		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)
+	}
+	items, ok := req.Messages[1].Content[0].Content.([]contracts.ToolReference)
+	if !ok || len(items) != 1 || items[0].ToolName != "Task" {
+		t.Fatalf("tool result content = %#v", req.Messages[1].Content[0].Content)
+	}
+}
+
 func TestBuildRequestLoadsDiscoveredToolReferences(t *testing.T) {
 	registry, err := tool.NewRegistry(tasktools.NewTaskTool())
 	if err != nil {