Gate ToolSearch by model and env

Author: SqlRush

cmd/claude/main_test.go

@@ -90,8 +90,8 @@ func TestRunPrintSendsPromptAndPrintsAssistantText(t *testing.T) {
 	if !ok || len(messages) < 1 {
 		t.Fatalf("messages = %#v", requestBody["messages"])
 	}
-	if !hasAvailableDeferredToolsMessage(messages) {
-		t.Fatalf("missing deferred tools message: %#v", messages)
+	if hasAvailableDeferredToolsMessage(messages) {
+		t.Fatalf("unexpected deferred tools message for haiku: %#v", messages)
 	}
 	if got := messageTextAt(t, messages, 0); got != "say hello" {
 		t.Fatalf("prompt = %q", got)
@@ -100,6 +100,9 @@ func TestRunPrintSendsPromptAndPrintsAssistantText(t *testing.T) {
 	if !ok || len(tools) == 0 {
 		t.Fatalf("missing builtin tools: %#v", requestBody["tools"])
 	}
+	if requestToolsContainName(tools, "ToolSearch") {
+		t.Fatalf("haiku request should not include ToolSearch: %#v", tools)
+	}
 }
 
 func TestRunChromeNativeHostRespondsToMessages(t *testing.T) {
@@ -3965,6 +3968,19 @@ func isAvailableDeferredToolsMessage(message any) bool {
 	return strings.HasPrefix(text, "<available-deferred-tools>\n")
 }
 
+func requestToolsContainName(tools []any, name string) bool {
+	for _, item := range tools {
+		tool, ok := item.(map[string]any)
+		if !ok {
+			continue
+		}
+		if tool["name"] == name {
+			return true
+		}
+	}
+	return false
+}
+
 func containsAnyString(values []any, want string) bool {
 	for _, value := range values {
 		if text, ok := value.(string); ok && text == want {

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 补充：conversation request 现在会在发送 beta `defer_loading` / `tool_reference` shape 前执行官方 ToolSearch enablement gate：Haiku 模型、`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`、falsy `ENABLE_TOOL_SEARCH`、`ENABLE_TOOL_SEARCH=auto:100`、以及未显式启用 ToolSearch 时的非一方 `ANTHROPIC_BASE_URL` 都会回落为标准 inline tool schema；显式 `ENABLE_TOOL_SEARCH=true` 仍可让支持 beta shape 的自定义网关 opt in。
+
 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 仍未完成。

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`。
+- 本轮补充：conversation request 现在会在发送 beta `defer_loading` / `tool_reference` shape 前执行官方 ToolSearch enablement gate：Haiku 模型、`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`、falsy `ENABLE_TOOL_SEARCH`、`ENABLE_TOOL_SEARCH=auto:100`、以及未显式启用 ToolSearch 时的非一方 `ANTHROPIC_BASE_URL` 都会回落为标准 inline tool schema；显式 `ENABLE_TOOL_SEARCH=true` 仍可让支持 beta shape 的自定义网关 opt in。
 - 本轮补充：当本次 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 的已发现工具快照。

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.
+- Request construction now also applies the official ToolSearch enablement gates before emitting beta `defer_loading` / `tool_reference` shapes: Haiku models, `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`, falsy `ENABLE_TOOL_SEARCH`, `ENABLE_TOOL_SEARCH=auto:100`, and unset ToolSearch behind non-first-party `ANTHROPIC_BASE_URL` all fall back to standard inline tool schemas; explicit `ENABLE_TOOL_SEARCH=true` can still opt a custom gateway back in.
 - 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.
@@ -113,7 +114,7 @@ The following items remain incomplete and must not be treated as done:
 - Auto mode / YOLO classifier: transcript construction, two-stage classifier, XML/tool-use parsing, prompt dump, denial circuit breaker, model gating, and fallback behavior.
 - Interactive permission prompt flow: REPL dialogs, bridge/channel/swarm permission relays, user feedback images, prompt race handling, cancellation.
 - Full filesystem permission parity gaps that remain: skill-scope allow suggestions, remaining local/local-jsx slash-command execution wiring beyond the currently covered no-query builtins, command permission UI/SDK surfacing, forked/remote/MCP/bundled SkillTool behavior and remaining plugin SkillTool UI/SDK polish beyond current metadata preservation, skill prompt shell injection, complete auto-memory override policy, and deeper platform-specific Windows/WSL bypass handling.
-- Full tool execution parity gaps that remain: complete hook runtime policy beyond the current settings command hook path, MCP elicitation, complete SDK control event surface beyond current progress NDJSON, full deferred/lazy tool discovery beyond current local registry BM25 search and API `defer_loading` hints, mid-call cancellation for concrete tools, background task behavior, telemetry, and concrete tool-specific semantics.
+- Full tool execution parity gaps that remain: complete hook runtime policy beyond the current settings command hook path, MCP elicitation, complete SDK control event surface beyond current progress NDJSON, full deferred/lazy tool discovery beyond current local registry BM25 search, API `defer_loading` hints, and model/env/proxy ToolSearch gates, including the official `ENABLE_TOOL_SEARCH=auto` token-threshold decision and remaining delta-attachment details, mid-call cancellation for concrete tools, background task behavior, telemetry, and concrete tool-specific semantics.
 - Complete Anthropic API parity gaps that remain: dynamic beta-header latching for any remaining provider-specific feature gates beyond prompt-cache/cache-editing/strict-output/1M-context requests, ant-only dump gating and remote `/issue` submission integration beyond the current local context summary, full official cost tracker/session restore lifecycle beyond current transcript usage restore, post-handshake streaming failure semantics, deeper gateway/proxy auth and routing behavior beyond static custom headers, first-party/Bedrock/Vertex/Foundry client setup, deeper OAuth account/profile lifecycle beyond request-time refresh retry, fast-mode retry/cooldown semantics, persistent unattended retry heartbeats, full prompt-cache editing lifecycle, and provider-specific cache behavior.
 - Full conversation/query loop: stop hooks, compact/auto-compact, token budget escalation, resume, SDK JSON/NDJSON control events, status updates, rate-limit handling, model switch breadcrumbs, side questions.
 - Full settings parity gaps that remain: complete Zod-equivalent validation messages, full remote managed-settings watcher/non-daemon background refresh lifecycle beyond current turn-start and daemon-heartbeat refresh, remaining forked agent/frontmatter execution and UI edge cases beyond current policy metadata filtering, complete marketplace TUI/UI/background lifecycle beyond current local/settings/directory/file/URL catalog/git/github/npm cache manifest load, URL catalog cache fallback, git/github fetch/pull cache refresh, npm pack cache refresh, and background watcher/continuous app-state sync beyond current turn-start local settings reload.

internal/conversation/request.go

@@ -1,7 +1,10 @@
 package conversation
 
 import (
+	"net/url"
+	"os"
 	"sort"
+	"strconv"
 	"strings"
 	"time"
 
@@ -44,7 +47,7 @@ func (r Runner) buildRequest(history []contracts.Message, model string, relevant
 		if err != nil {
 			return anthropic.Request{}, err
 		}
-		definitions, deferredToolNames, toolSearchActive = filterToolSearchDefinitions(defs, history)
+		definitions, deferredToolNames, toolSearchActive = filterToolSearchDefinitions(defs, history, model)
 	}
 	apiMessages := msgs.NormalizeForAPI(history)
 	if !toolSearchActive {
@@ -67,13 +70,16 @@ func (r Runner) buildRequest(history []contracts.Message, model string, relevant
 	return request, nil
 }
 
-func filterToolSearchDefinitions(definitions []contracts.ToolDefinition, history []contracts.Message) ([]contracts.ToolDefinition, []string, bool) {
+func filterToolSearchDefinitions(definitions []contracts.ToolDefinition, history []contracts.Message, model string) ([]contracts.ToolDefinition, []string, bool) {
 	if len(definitions) == 0 {
 		return definitions, nil, false
 	}
 	if !hasToolSearchDefinition(definitions) {
 		return applyDiscoveredToolReferences(definitions, history), nil, false
 	}
+	if !toolSearchEnabledForRequest(model) {
+		return loadAllDeferredTools(withoutToolSearchDefinition(definitions)), nil, false
+	}
 	deferredNames := deferredToolNames(definitions)
 	if len(deferredNames) == 0 {
 		return withoutToolSearchDefinition(definitions), nil, false
@@ -94,6 +100,118 @@ func filterToolSearchDefinitions(definitions []contracts.ToolDefinition, history
 	return out, deferredNames, true
 }
 
+type toolSearchMode string
+
+const (
+	toolSearchModeTST      toolSearchMode = "tst"
+	toolSearchModeTSTAuto  toolSearchMode = "tst-auto"
+	toolSearchModeStandard toolSearchMode = "standard"
+)
+
+func toolSearchEnabledForRequest(model string) bool {
+	if !modelSupportsToolReference(model) {
+		return false
+	}
+	mode := toolSearchModeFromEnv()
+	if mode == toolSearchModeStandard {
+		return false
+	}
+	if os.Getenv("ENABLE_TOOL_SEARCH") == "" && !isFirstPartyAnthropicBaseURL(os.Getenv("ANTHROPIC_BASE_URL")) {
+		return false
+	}
+	return true
+}
+
+func modelSupportsToolReference(model string) bool {
+	return !strings.Contains(strings.ToLower(strings.TrimSpace(model)), "haiku")
+}
+
+func toolSearchModeFromEnv() toolSearchMode {
+	if session.IsEnvTruthy(os.Getenv("CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS")) {
+		return toolSearchModeStandard
+	}
+	value := os.Getenv("ENABLE_TOOL_SEARCH")
+	if percent, ok := autoToolSearchPercent(value); ok {
+		if percent == 0 {
+			return toolSearchModeTST
+		}
+		if percent == 100 {
+			return toolSearchModeStandard
+		}
+	}
+	if isAutoToolSearchMode(value) {
+		return toolSearchModeTSTAuto
+	}
+	if session.IsEnvTruthy(value) {
+		return toolSearchModeTST
+	}
+	if isEnvDefinedFalsy(value) {
+		return toolSearchModeStandard
+	}
+	return toolSearchModeTST
+}
+
+func autoToolSearchPercent(value string) (int, bool) {
+	if !strings.HasPrefix(value, "auto:") {
+		return 0, false
+	}
+	percent, err := strconv.Atoi(value[len("auto:"):])
+	if err != nil {
+		return 0, false
+	}
+	if percent < 0 {
+		return 0, true
+	}
+	if percent > 100 {
+		return 100, true
+	}
+	return percent, true
+}
+
+func isAutoToolSearchMode(value string) bool {
+	return value == "auto" || strings.HasPrefix(value, "auto:")
+}
+
+func isEnvDefinedFalsy(value string) bool {
+	switch strings.ToLower(strings.TrimSpace(value)) {
+	case "0", "false", "no", "off":
+		return true
+	default:
+		return false
+	}
+}
+
+func isFirstPartyAnthropicBaseURL(raw string) bool {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return true
+	}
+	parsed, err := url.Parse(raw)
+	if err != nil {
+		return false
+	}
+	host := parsed.Host
+	if host == "" {
+		return false
+	}
+	if host == "api.anthropic.com" {
+		return true
+	}
+	return os.Getenv("USER_TYPE") == "ant" && host == "api-staging.anthropic.com"
+}
+
+func loadAllDeferredTools(definitions []contracts.ToolDefinition) []contracts.ToolDefinition {
+	out := make([]contracts.ToolDefinition, len(definitions))
+	copy(out, definitions)
+	for i := range out {
+		if toolDefinitionDeferred(out[i]) {
+			out[i].AlwaysLoad = true
+			out[i].ShouldDefer = false
+		}
+	}
+	return out
+}
+
 func applyDiscoveredToolReferences(definitions []contracts.ToolDefinition, history []contracts.Message) []contracts.ToolDefinition {
 	discovered := discoveredToolReferenceNames(history)
 	if len(discovered) == 0 || len(definitions) == 0 {