fix: normalize LLM tool requests (#2142)

Author: yohamta0

internal/llm/provider.go

@@ -173,7 +173,11 @@ func NewProvider(providerType ProviderType, cfg Config) (Provider, error) {
 		cfg.BaseURL = DefaultBaseURL(providerType)
 	}
 
-	return factory(cfg)
+	provider, err := factory(cfg)
+	if err != nil {
+		return nil, err
+	}
+	return normalizedProvider{Provider: provider}, nil
 }
 
 // NewProviderWithAPIKey creates a new Provider with the given API key.

internal/llm/providers/anthropic/anthropic.go

@@ -17,10 +17,11 @@ import (
 )
 
 const (
-	providerName        = "anthropic"
-	defaultMessagesPath = "/v1/messages"
-	anthropicAPIVersion = "2023-06-01"
-	streamPrefix        = "data: "
+	providerName               = "anthropic"
+	defaultMessagesPath        = "/v1/messages"
+	anthropicAPIVersion        = "2023-06-01"
+	streamPrefix               = "data: "
+	anthropicWebSearchToolType = "web_search_20260209"
 
 	// Thinking budget token limits for different effort levels.
 	// Note: Anthropic recommends budgets <= 32K to avoid timeout issues.
@@ -160,8 +161,8 @@ func (p *Provider) buildRequestBody(req *llm.ChatRequest, stream bool) ([]byte,
 	// Append provider-native web search tool if enabled.
 	if req.WebSearch != nil && req.WebSearch.Enabled {
 		wsEntry := map[string]any{
-			"type": "web_search_20260209",
-			"name": "web_search",
+			"type": anthropicWebSearchToolType,
+			"name": llm.WebSearchToolName,
 		}
 		// Haiku 4.5 only supports allowed_callers=["direct"] for web_search.
 		// Other models accept any value, so "direct" is safe as a universal default.

internal/llm/request.go

@@ -0,0 +1,91 @@
+// Copyright (C) 2026 Yota Hamada
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package llm
+
+import "context"
+
+// WebSearchToolName is the canonical explicit tool name for web search.
+const WebSearchToolName = "web_search"
+
+// NormalizeChatRequest applies provider-independent request invariants before a
+// request reaches a concrete provider.
+func NormalizeChatRequest(req *ChatRequest) *ChatRequest {
+	if req == nil {
+		return nil
+	}
+
+	normalized := *req
+	normalized.Tools = dedupeTools(req.Tools)
+	normalized.WebSearch = cloneWebSearchRequest(req.WebSearch)
+
+	if normalized.WebSearch != nil && normalized.WebSearch.Enabled && hasToolNamed(normalized.Tools, WebSearchToolName) {
+		normalized.WebSearch.Enabled = false
+	}
+
+	return &normalized
+}
+
+// cloneWebSearchRequest returns an independent copy of provider-native web
+// search settings so normalization never mutates caller-owned request state.
+func cloneWebSearchRequest(req *WebSearchRequest) *WebSearchRequest {
+	if req == nil {
+		return nil
+	}
+
+	out := *req
+	out.AllowedDomains = append([]string(nil), req.AllowedDomains...)
+	out.BlockedDomains = append([]string(nil), req.BlockedDomains...)
+	if req.UserLocation != nil {
+		location := *req.UserLocation
+		out.UserLocation = &location
+	}
+	return &out
+}
+
+// dedupeTools preserves the first definition for each tool name and drops later
+// duplicates so providers never receive invalid same-name tool lists.
+func dedupeTools(tools []Tool) []Tool {
+	if len(tools) == 0 {
+		return nil
+	}
+
+	out := make([]Tool, 0, len(tools))
+	seen := make(map[string]struct{}, len(tools))
+	for _, tool := range tools {
+		name := tool.Function.Name
+		if _, ok := seen[name]; ok {
+			continue
+		}
+		seen[name] = struct{}{}
+		out = append(out, tool)
+	}
+	return out
+}
+
+// hasToolNamed reports whether tools contains a definition for name.
+func hasToolNamed(tools []Tool, name string) bool {
+	for _, tool := range tools {
+		if tool.Function.Name == name {
+			return true
+		}
+	}
+	return false
+}
+
+// normalizedProvider enforces shared request normalization around every
+// concrete provider implementation returned by the factory.
+type normalizedProvider struct {
+	Provider
+}
+
+// Chat normalizes each request before delegating to the concrete provider.
+func (p normalizedProvider) Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error) {
+	return p.Provider.Chat(ctx, NormalizeChatRequest(req))
+}
+
+// ChatStream normalizes each streaming request before delegating to the
+// concrete provider.
+func (p normalizedProvider) ChatStream(ctx context.Context, req *ChatRequest) (<-chan StreamEvent, error) {
+	return p.Provider.ChatStream(ctx, NormalizeChatRequest(req))
+}

internal/llm/request_test.go

@@ -0,0 +1,141 @@
+// Copyright (C) 2026 Yota Hamada
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package llm
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestNormalizeChatRequest verifies that request normalization preserves caller
+// state while enforcing provider-independent tool invariants.
+func TestNormalizeChatRequest(t *testing.T) {
+	t.Parallel()
+
+	t.Run("deduplicates tools by name and disables native web search on collision", func(t *testing.T) {
+		t.Parallel()
+
+		req := &ChatRequest{
+			Model: "test",
+			Tools: []Tool{
+				testTool(WebSearchToolName, "first"),
+				testTool(WebSearchToolName, "second"),
+				testTool("read", "read"),
+			},
+			WebSearch: &WebSearchRequest{Enabled: true},
+		}
+
+		normalized := NormalizeChatRequest(req)
+
+		require.NotSame(t, req, normalized)
+		require.Len(t, normalized.Tools, 2)
+		assert.Equal(t, "first", normalized.Tools[0].Function.Description)
+		assert.Equal(t, "read", normalized.Tools[1].Function.Name)
+		require.NotNil(t, normalized.WebSearch)
+		assert.False(t, normalized.WebSearch.Enabled)
+
+		require.Len(t, req.Tools, 3, "normalization must not mutate caller tools")
+		assert.True(t, req.WebSearch.Enabled, "normalization must not mutate caller web search config")
+	})
+
+	t.Run("keeps native web search when no explicit web_search tool exists", func(t *testing.T) {
+		t.Parallel()
+
+		req := &ChatRequest{
+			Model:     "test",
+			Tools:     []Tool{testTool("read", "read")},
+			WebSearch: &WebSearchRequest{Enabled: true},
+		}
+
+		normalized := NormalizeChatRequest(req)
+
+		require.NotNil(t, normalized.WebSearch)
+		assert.True(t, normalized.WebSearch.Enabled)
+	})
+}
+
+// TestNewProviderNormalizesRequests verifies that factory-created providers
+// normalize both synchronous and streaming chat requests.
+func TestNewProviderNormalizesRequests(t *testing.T) {
+	orig := registry
+	defer func() { registry = orig }()
+	registry = make(map[ProviderType]ProviderFactory)
+
+	capturedChat := make(chan *ChatRequest, 1)
+	capturedStream := make(chan *ChatRequest, 1)
+	RegisterProvider(ProviderType("normalize-test"), func(_ Config) (Provider, error) {
+		return &normalizingTestProvider{
+			chat:   capturedChat,
+			stream: capturedStream,
+		}, nil
+	})
+
+	provider, err := NewProvider(ProviderType("normalize-test"), Config{})
+	require.NoError(t, err)
+
+	req := &ChatRequest{
+		Model: "test",
+		Tools: []Tool{
+			testTool(WebSearchToolName, "first"),
+			testTool(WebSearchToolName, "second"),
+		},
+		WebSearch: &WebSearchRequest{Enabled: true},
+	}
+
+	_, err = provider.Chat(context.Background(), req)
+	require.NoError(t, err)
+	chatReq := <-capturedChat
+	require.Len(t, chatReq.Tools, 1)
+	assert.False(t, chatReq.WebSearch.Enabled)
+
+	events, err := provider.ChatStream(context.Background(), req)
+	require.NoError(t, err)
+	for range events {
+	}
+	streamReq := <-capturedStream
+	require.Len(t, streamReq.Tools, 1)
+	assert.False(t, streamReq.WebSearch.Enabled)
+}
+
+// testTool builds a minimal function tool definition for normalization tests.
+func testTool(name, description string) Tool {
+	return Tool{
+		Type: "function",
+		Function: ToolFunction{
+			Name:        name,
+			Description: description,
+			Parameters:  map[string]any{"type": "object"},
+		},
+	}
+}
+
+// normalizingTestProvider captures requests after the provider wrapper has
+// normalized them.
+type normalizingTestProvider struct {
+	chat   chan<- *ChatRequest
+	stream chan<- *ChatRequest
+}
+
+// Chat captures the normalized request received by the test provider.
+func (p *normalizingTestProvider) Chat(_ context.Context, req *ChatRequest) (*ChatResponse, error) {
+	p.chat <- req
+	return &ChatResponse{Content: "ok"}, nil
+}
+
+// ChatStream captures the normalized request received by the streaming path.
+func (p *normalizingTestProvider) ChatStream(_ context.Context, req *ChatRequest) (<-chan StreamEvent, error) {
+	p.stream <- req
+	ch := make(chan StreamEvent, 1)
+	ch <- StreamEvent{Done: true}
+	close(ch)
+	return ch, nil
+}
+
+// Name returns the test provider's registry name.
+func (p *normalizingTestProvider) Name() string {
+	return "normalize-test"
+}

internal/llm/retry.go

@@ -45,6 +45,7 @@ func DefaultLogicalRetryConfig() LogicalRetryConfig {
 // transient request failures.
 func ChatWithRetry(ctx context.Context, provider Provider, req *ChatRequest, cfg LogicalRetryConfig) (*ChatResponse, error) {
 	cfg = normalizeLogicalRetryConfig(cfg)
+	req = NormalizeChatRequest(req)
 
 	var lastErr error
 	for attempt := 1; attempt <= cfg.MaxAttempts; attempt++ {

internal/llm/retry_test.go

@@ -90,6 +90,33 @@ func TestChatWithRetry(t *testing.T) {
 		require.ErrorIs(t, err, context.Canceled)
 		assert.Equal(t, int32(1), calls.Load())
 	})
+
+	t.Run("normalizes request before provider call", func(t *testing.T) {
+		t.Parallel()
+
+		var captured *ChatRequest
+		provider := &retryTestProvider{
+			chatFunc: func(_ context.Context, req *ChatRequest) (*ChatResponse, error) {
+				captured = req
+				return &ChatResponse{Content: "ok", FinishReason: "stop"}, nil
+			},
+		}
+		req := &ChatRequest{
+			Model: "test",
+			Tools: []Tool{
+				testTool(WebSearchToolName, "first"),
+				testTool(WebSearchToolName, "second"),
+			},
+			WebSearch: &WebSearchRequest{Enabled: true},
+		}
+
+		_, err := ChatWithRetry(context.Background(), provider, req, DefaultLogicalRetryConfig())
+		require.NoError(t, err)
+		require.NotNil(t, captured)
+		require.Len(t, captured.Tools, 1)
+		assert.False(t, captured.WebSearch.Enabled)
+		assert.True(t, req.WebSearch.Enabled, "normalization must not mutate caller request")
+	})
 }
 
 func TestShouldRetryRequest(t *testing.T) {

internal/runtime/builtin/chat/executor.go

@@ -719,6 +719,7 @@ func (e *Executor) executeToolStep(
 
 func (e *Executor) runStreamForModel(ctx context.Context, provider llmpkg.Provider, req *llmpkg.ChatRequest) (string, *llmpkg.Usage, error) {
 	retryCfg := llmpkg.DefaultLogicalRetryConfig()
+	req = llmpkg.NormalizeChatRequest(req)
 
 	for attempt := 1; attempt <= retryCfg.MaxAttempts; attempt++ {
 		events, err := provider.ChatStream(ctx, req)