diff --git a/pkg/chat/display_name.go b/pkg/chat/display_name.go
new file mode 100644
index 0000000000..8ab25398ba
--- /dev/null
+++ b/pkg/chat/display_name.go
@@ -0,0 +1,72 @@
+package chat
+
+import (
+	"strings"
+	"unicode/utf8"
+)
+
+// MaxSanitizedFieldBytes is the canonical UTF-8-safe upper bound applied to
+// every sanitized display-name and MIME-type field (see
+// [SanitizeDisplayName] and the MIME sanitizer in pkg/runtime), independent
+// of the separate, larger bound applied to a fully formatted placeholder or
+// warning line. It exists so a single overlong provider-supplied field
+// cannot itself balloon persisted metadata, session history, or prompts.
+const MaxSanitizedFieldBytes = 128
+
+// TruncateUTF8Bytes returns the longest prefix of s that is at most max
+// bytes and still valid UTF-8 — it never splits a multi-byte rune, so the
+// result is always safe to display or re-encode. Used by every canonical
+// sanitizer (display name, MIME type, and formatted placeholder/warning
+// text) to enforce a byte bound without corrupting non-ASCII content.
+func TruncateUTF8Bytes(s string, maxBytes int) string {
+	if len(s) <= maxBytes {
+		return s
+	}
+	for maxBytes > 0 && !utf8.RuneStart(s[maxBytes]) {
+		maxBytes--
+	}
+	return s[:maxBytes]
+}
+
+// SanitizeDisplayName neutralizes a provider-supplied display name before
+// it is stored in a [Document] or any other session-visible metadata. The
+// name is untrusted input (e.g. Gemini's InlineData.DisplayName): it is
+// never used verbatim to build a filesystem path (path-bearing consumers
+// validate the requested name themselves), but it does end up in
+// UI, warnings, placeholder text, and interpolated harness/prompt text
+// (see pkg/runtime/harness.go's "<role>...</role>"-delimited blocks), so
+// it must not carry control characters, path separators, traversal-like
+// sequences, or angle brackets that could confuse a terminal, log line,
+// forge a fake XML/tag boundary, or trick a human copy-pasting it into a
+// shell.
+//
+// Control characters, path separators, and '<'/'>' are rewritten to '_';
+// any residual ".." sequence (which could still read as a traversal hint
+// even without separators, e.g. "..name") is rewritten too. The result is
+// capped at [MaxSanitizedFieldBytes] (UTF-8-safe) and trimmed of
+// surrounding whitespace. An empty or all-whitespace input returns "" —
+// callers are responsible for substituting their own fallback name.
+func SanitizeDisplayName(name string) string {
+	name = strings.TrimSpace(name)
+
+	var b strings.Builder
+	b.Grow(len(name))
+	for _, r := range name {
+		switch {
+		case r == '/' || r == '\\':
+			b.WriteRune('_')
+		case r == '<' || r == '>':
+			b.WriteRune('_')
+		case r < 0x20 || r == 0x7f:
+			b.WriteRune('_')
+		default:
+			b.WriteRune(r)
+		}
+	}
+	sanitized := b.String()
+	for strings.Contains(sanitized, "..") {
+		sanitized = strings.ReplaceAll(sanitized, "..", "_")
+	}
+	sanitized = TruncateUTF8Bytes(strings.TrimSpace(sanitized), MaxSanitizedFieldBytes)
+	return strings.TrimSpace(sanitized)
+}
diff --git a/pkg/chat/display_name_test.go b/pkg/chat/display_name_test.go
new file mode 100644
index 0000000000..c39cf828ec
--- /dev/null
+++ b/pkg/chat/display_name_test.go
@@ -0,0 +1,77 @@
+package chat
+
+import (
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSanitizeDisplayName(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{"unchanged for a plain name", "cat.png", "cat.png"},
+		{"path separators rewritten", "a/b\\c.png", "a_b_c.png"},
+		{"control chars rewritten", "cat\x00\x01name.png", "cat__name.png"},
+		{"DEL rewritten", "cat\x7fname.png", "cat_name.png"},
+		{"traversal sequence neutralized", "../../etc/passwd", "____etc_passwd"},
+		{"traversal without separators neutralized", "..name", "_name"},
+		{"leading/trailing whitespace trimmed", "  cat.png  ", "cat.png"},
+		{"empty input yields empty output", "", ""},
+		{"whitespace-only input yields empty output", "   \t\n  ", ""},
+		{"control chars only collapse to empty after trim", " \x00\x01 ", "__"},
+		{"unicode name preserved", "猫.png", "猫.png"},
+		{"angle brackets rewritten", "</system><script>.png", "__system__script_.png"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			got := SanitizeDisplayName(tc.input)
+			assert.Equal(t, tc.want, got)
+			assert.NotContains(t, got, "..", "sanitized name must never contain a traversal sequence")
+			assert.NotContains(t, got, "/", "sanitized name must never contain a path separator")
+			assert.NotContains(t, got, "\\", "sanitized name must never contain a path separator")
+			assert.NotContains(t, got, "<", "sanitized name must never contain an angle bracket")
+			assert.NotContains(t, got, ">", "sanitized name must never contain an angle bracket")
+		})
+	}
+}
+
+// TestSanitizeDisplayName_BoundsOverlongInput is the plan's "128-byte
+// UTF-8-safe field bound" regression: an overlong provider-supplied name
+// (well beyond any legitimate filename) must never reach persisted
+// metadata, placeholders, or warnings unbounded — a single hostile value
+// must not be able to balloon session history or context.
+func TestSanitizeDisplayName_BoundsOverlongInput(t *testing.T) {
+	t.Parallel()
+
+	got := SanitizeDisplayName(strings.Repeat("a", 10_000))
+	assert.LessOrEqual(t, len(got), MaxSanitizedFieldBytes)
+	assert.True(t, utf8.ValidString(got), "truncation must never split a multi-byte rune")
+
+	// A multi-byte-rune name must still be truncated at a valid rune
+	// boundary rather than corrupted mid-rune.
+	gotUnicode := SanitizeDisplayName(strings.Repeat("\u732b", 10_000))
+	assert.LessOrEqual(t, len(gotUnicode), MaxSanitizedFieldBytes)
+	assert.True(t, utf8.ValidString(gotUnicode), "truncation must never split a multi-byte rune")
+}
+
+func TestTruncateUTF8Bytes(t *testing.T) {
+	t.Parallel()
+
+	assert.Equal(t, "abc", TruncateUTF8Bytes("abc", 10), "input shorter than the bound is returned unchanged")
+	assert.Equal(t, "ab", TruncateUTF8Bytes("abc", 2))
+
+	// "\u732b" (猫) is 3 bytes in UTF-8; a 4-byte budget can fit exactly
+	// one full rune, and the cut must land before the second one starts.
+	got := TruncateUTF8Bytes(strings.Repeat("\u732b", 3), 4)
+	assert.True(t, utf8.ValidString(got))
+	assert.LessOrEqual(t, len(got), 4)
+}
diff --git a/pkg/model/provider/gemini/classify.go b/pkg/model/provider/gemini/classify.go
new file mode 100644
index 0000000000..8b5fafb0bd
--- /dev/null
+++ b/pkg/model/provider/gemini/classify.go
@@ -0,0 +1,81 @@
+package gemini
+
+import "strings"
+
+// RequestRejectionCategory buckets a Gemini request rejection into one of a
+// small, fixed set of causes so diagnostics and error messages can stay
+// specific without echoing the provider's raw message or response body.
+// Categories are derived only from Google's own public, documented API
+// field/parameter names appearing in [genai.APIError.Message] — never from
+// request content, tool schemas, prompts, or anything else local to this
+// process.
+type RequestRejectionCategory string
+
+const (
+	// RejectionMissingResponseModalities: the request didn't declare a
+	// response modality (e.g. IMAGE) that the model needed for this reply.
+	RejectionMissingResponseModalities RequestRejectionCategory = "missing_response_modalities"
+	// RejectionIncompatibleFunctionOrBuiltinTools: the combination of
+	// custom function tools and/or built-in tools (Search, Maps, Code
+	// Execution) enabled for the request isn't supported together.
+	RejectionIncompatibleFunctionOrBuiltinTools RequestRejectionCategory = "incompatible_function_or_builtin_tools"
+	// RejectionIncompatibleToolConfig: the ToolConfig/function-calling mode
+	// isn't supported for this request or model.
+	RejectionIncompatibleToolConfig RequestRejectionCategory = "incompatible_tool_config"
+	// RejectionStructuredOutputConflict: a structured-output option
+	// (response MIME type/schema) conflicts with another request option.
+	RejectionStructuredOutputConflict RequestRejectionCategory = "structured_output_conflict"
+	// RejectionModelOrAPICapabilityMismatch: the request used a feature
+	// (e.g. thinking configuration) the target model or API surface
+	// doesn't support at all.
+	RejectionModelOrAPICapabilityMismatch RequestRejectionCategory = "model_or_api_capability_mismatch"
+	// RejectionOther covers any other provider rejection, including ones
+	// with no message to classify against (Gemini sometimes returns a 400
+	// with an empty body).
+	RejectionOther RequestRejectionCategory = "other_provider_rejection"
+)
+
+// rejectionKeywords maps each category to lowercase substrings of Gemini's
+// own documented request field/parameter names that indicate it. Checked
+// top-to-bottom; the first match wins.
+var rejectionKeywords = []struct {
+	category RequestRejectionCategory
+	keywords []string
+}{
+	{RejectionMissingResponseModalities, []string{"response_modalities", "responsemodalities"}},
+	{RejectionStructuredOutputConflict, []string{
+		"response_schema", "response_json_schema", "response_mime_type",
+		"responseschema", "responsejsonschema", "responsemimetype",
+	}},
+	{RejectionIncompatibleToolConfig, []string{
+		"tool_config", "toolconfig", "function_calling_config", "functioncallingconfig",
+	}},
+	{RejectionIncompatibleFunctionOrBuiltinTools, []string{
+		"function_declarations", "functiondeclarations",
+		"google_search", "google_maps", "code_execution",
+		"built-in tool", "builtin tool",
+	}},
+	{RejectionModelOrAPICapabilityMismatch, []string{
+		"thinking_config", "thinkingconfig",
+		"not supported for", "not supported by", "does not support", "is not enabled for",
+	}},
+}
+
+// classifyByMessage returns the category matching a bounded set of known
+// Gemini field/parameter keywords found in message, and true when a match
+// was found. It returns (RejectionOther, false) when message is empty or
+// matches nothing — a common shape for Gemini 400s with no JSON body.
+func classifyByMessage(message string) (RequestRejectionCategory, bool) {
+	if message == "" {
+		return RejectionOther, false
+	}
+	lower := strings.ToLower(message)
+	for _, entry := range rejectionKeywords {
+		for _, kw := range entry.keywords {
+			if strings.Contains(lower, kw) {
+				return entry.category, true
+			}
+		}
+	}
+	return RejectionOther, false
+}
diff --git a/pkg/model/provider/gemini/client.go b/pkg/model/provider/gemini/client.go
index d51fb43d90..1a50f78000 100644
--- a/pkg/model/provider/gemini/client.go
+++ b/pkg/model/provider/gemini/client.go
@@ -34,6 +34,12 @@ type Client struct {
 	base.Config
 
 	clientFn func(context.Context) (*genai.Client, error)
+
+	// apiSurface classifies which backend/transport this client talks to
+	// (see the apiSurface* constants in diagnostics.go), for safe
+	// request-shape diagnostics. Never exposed to the model or logged
+	// alongside anything provider-supplied.
+	apiSurface string
 }
 
 // NewClient creates a new Gemini client from the provided configuration
@@ -49,6 +55,7 @@ func NewClient(ctx context.Context, cfg *latest.ModelConfig, env environment.Pro
 	globalOptions := options.Apply(opts...)
 
 	var clientFn func(context.Context) (*genai.Client, error)
+	var apiSurface string
 	if gateway := globalOptions.Gateway(); gateway == "" {
 		var (
 			httpClient *http.Client
@@ -111,6 +118,12 @@ func NewClient(ctx context.Context, cfg *latest.ModelConfig, env environment.Pro
 			httpClient = httpclient.NewHTTPClient(ctx)
 		}
 
+		if backend == genai.BackendVertexAI {
+			apiSurface = apiSurfaceVertexAI
+		} else {
+			apiSurface = apiSurfaceGeminiAPI
+		}
+
 		globalOptions.WrapTransport(ctx, httpClient)
 
 		client, err := genai.NewClient(ctx, &genai.ClientConfig{
@@ -131,6 +144,8 @@ func NewClient(ctx context.Context, cfg *latest.ModelConfig, env environment.Pro
 			return client, nil
 		}
 	} else {
+		apiSurface = apiSurfaceGateway
+
 		// When using a Gateway targeting a Docker domain, tokens are short-lived.
 		// Only require and inject the Docker JWT if the gateway is a .docker.com URL.
 		if err := base.VerifyDockerGatewayAuth(ctx, env, gateway); err != nil {
@@ -184,7 +199,8 @@ func NewClient(ctx context.Context, cfg *latest.ModelConfig, env environment.Pro
 			ModelOptions: globalOptions,
 			Env:          env,
 		},
-		clientFn: clientFn,
+		clientFn:   clientFn,
+		apiSurface: apiSurface,
 	}, nil
 }
 
@@ -749,16 +765,11 @@ func (c *Client) CreateChatCompletionStream(
 		if len(config.Tools) > len(allTools) {
 			config.ToolConfig.IncludeServerSideToolInvocations = new(true)
 		}
-
-		// Debug: Log the tools we're sending
-		slog.DebugContext(ctx, "Gemini tools config", "tools", config.Tools)
-		for _, tool := range config.Tools {
-			for _, fn := range tool.FunctionDeclarations {
-				slog.DebugContext(ctx, "Function", "name", fn.Name, "desc", fn.Description, "params", fn.Parameters)
-			}
-		}
 	}
 
+	shape := newRequestShape(c, config, len(requestTools))
+	slog.DebugContext(ctx, "Gemini request shape", shape.LogAttrs()...)
+
 	contents := convertMessagesToGemini(ctx, messages, c.ID(), c.ModelOptions.ModelsDevStore(), c.CapsOverride())
 
 	// Debug: Log the messages we're sending
diff --git a/pkg/model/provider/gemini/diagnostics.go b/pkg/model/provider/gemini/diagnostics.go
new file mode 100644
index 0000000000..01fda9283c
--- /dev/null
+++ b/pkg/model/provider/gemini/diagnostics.go
@@ -0,0 +1,155 @@
+package gemini
+
+import (
+	"strings"
+
+	"google.golang.org/genai"
+)
+
+// apiSurface* classifies which backend/transport a Client talks to. Used
+// only for diagnostics; never derived from or containing request content.
+const (
+	apiSurfaceGeminiAPI = "gemini_api"
+	apiSurfaceVertexAI  = "vertex_ai"
+	apiSurfaceGateway   = "gateway"
+)
+
+// RequestShape is a safe, allowlisted summary of a Gemini
+// GenerateContentConfig request. Every field is a boolean, count, or a value
+// drawn from a small fixed enum (e.g. a modality name or tool kind) — never
+// a prompt, tool description/schema, media payload, token, credential, or
+// any other provider- or user-supplied free text. It is safe to log at
+// Debug level and to include in diagnostics/bug reports.
+type RequestShape struct {
+	// ResponseModalitiesSet reports whether the request specified any
+	// response modalities at all. ResponseModalities holds the normalized
+	// (trimmed, upper-cased, de-duplicated) values, e.g. ["TEXT", "IMAGE"].
+	ResponseModalitiesSet bool
+	ResponseModalities    []string
+
+	// BuiltInToolKinds lists which fixed-kind built-in tools (google_search,
+	// google_maps, code_execution) were enabled. BuiltInToolCount is
+	// len(BuiltInToolKinds).
+	BuiltInToolKinds []string
+	BuiltInToolCount int
+
+	// FunctionToolCount is the number of caller-supplied (MCP/custom)
+	// function tools converted for this request. Never their names,
+	// descriptions, or parameter schemas.
+	FunctionToolCount int
+
+	// HasToolConfig, FunctionCallingMode, and ServerSideToolInvocation
+	// describe genai.ToolConfig without exposing AllowedFunctionNames.
+	HasToolConfig            bool
+	FunctionCallingMode      string
+	ServerSideToolInvocation bool
+
+	// StructuredOutputPresent reports whether a structured-output response
+	// (MIME type and/or schema) was requested, never the schema itself.
+	StructuredOutputPresent bool
+
+	// ThinkingConfigSet and NoThinkingRequested describe the thinking
+	// configuration shape without exposing budgets or levels (already safe
+	// enums/numbers, but kept out to keep this struct minimal).
+	ThinkingConfigSet   bool
+	NoThinkingRequested bool
+
+	// APISurface classifies the backend/transport: "gemini_api", "vertex_ai",
+	// or "gateway".
+	APISurface string
+
+	// OutputCapabilityKnown and OutputCapabilityEnabled report whether an
+	// authoritative source for the model's image/media *output* capability
+	// was consulted for this request. No such source exists yet — it is the
+	// subject of a later step — so both fields are always false today,
+	// deliberately reporting "unknown" rather than guessing from the model
+	// ID string.
+	OutputCapabilityKnown   bool
+	OutputCapabilityEnabled bool
+}
+
+// newRequestShape captures a [RequestShape] from a fully-built
+// genai.GenerateContentConfig (i.e. after tools/ToolConfig have been
+// attached) and the client that built it.
+func newRequestShape(c *Client, config *genai.GenerateContentConfig, functionToolCount int) RequestShape {
+	modalities := normalizeResponseModalities(config.ResponseModalities)
+	kinds := builtInToolKinds(config.Tools)
+
+	shape := RequestShape{
+		ResponseModalitiesSet:   len(modalities) > 0,
+		ResponseModalities:      modalities,
+		BuiltInToolKinds:        kinds,
+		BuiltInToolCount:        len(kinds),
+		FunctionToolCount:       functionToolCount,
+		HasToolConfig:           config.ToolConfig != nil,
+		StructuredOutputPresent: config.ResponseMIMEType != "" || config.ResponseSchema != nil || config.ResponseJsonSchema != nil,
+		ThinkingConfigSet:       config.ThinkingConfig != nil,
+		NoThinkingRequested:     c.ModelOptions.NoThinking(),
+		APISurface:              c.apiSurface,
+	}
+
+	if config.ToolConfig != nil {
+		if fc := config.ToolConfig.FunctionCallingConfig; fc != nil {
+			shape.FunctionCallingMode = string(fc.Mode)
+		}
+		shape.ServerSideToolInvocation = config.ToolConfig.IncludeServerSideToolInvocations != nil &&
+			*config.ToolConfig.IncludeServerSideToolInvocations
+	}
+
+	return shape
+}
+
+// normalizeResponseModalities trims, upper-cases, and de-duplicates raw
+// modality strings, dropping empty entries.
+func normalizeResponseModalities(raw []string) []string {
+	out := make([]string, 0, len(raw))
+	seen := make(map[string]bool, len(raw))
+	for _, m := range raw {
+		norm := strings.ToUpper(strings.TrimSpace(m))
+		if norm == "" || seen[norm] {
+			continue
+		}
+		seen[norm] = true
+		out = append(out, norm)
+	}
+	return out
+}
+
+// builtInToolKinds returns the fixed-kind names of built-in tools present in
+// toolsList (e.g. "google_search"). The caller-supplied function-declarations
+// tool (added separately by convertToolsToGemini) has none of these fields
+// set, so it is naturally excluded.
+func builtInToolKinds(toolsList []*genai.Tool) []string {
+	var kinds []string
+	for _, t := range toolsList {
+		switch {
+		case t.GoogleSearch != nil:
+			kinds = append(kinds, "google_search")
+		case t.GoogleMaps != nil:
+			kinds = append(kinds, "google_maps")
+		case t.CodeExecution != nil:
+			kinds = append(kinds, "code_execution")
+		}
+	}
+	return kinds
+}
+
+// LogAttrs renders the shape as a flat slog key/value list.
+func (s RequestShape) LogAttrs() []any {
+	return []any{
+		"response_modalities_set", s.ResponseModalitiesSet,
+		"response_modalities", s.ResponseModalities,
+		"built_in_tool_kinds", s.BuiltInToolKinds,
+		"built_in_tool_count", s.BuiltInToolCount,
+		"function_tool_count", s.FunctionToolCount,
+		"has_tool_config", s.HasToolConfig,
+		"function_calling_mode", s.FunctionCallingMode,
+		"server_side_tool_invocation", s.ServerSideToolInvocation,
+		"structured_output_present", s.StructuredOutputPresent,
+		"thinking_config_set", s.ThinkingConfigSet,
+		"no_thinking_requested", s.NoThinkingRequested,
+		"api_surface", s.APISurface,
+		"output_capability_known", s.OutputCapabilityKnown,
+		"output_capability_enabled", s.OutputCapabilityEnabled,
+	}
+}
diff --git a/pkg/model/provider/gemini/diagnostics_test.go b/pkg/model/provider/gemini/diagnostics_test.go
new file mode 100644
index 0000000000..b25bd56f93
--- /dev/null
+++ b/pkg/model/provider/gemini/diagnostics_test.go
@@ -0,0 +1,333 @@
+package gemini
+
+import (
+	"bytes"
+	"io/fs"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/genai"
+
+	"github.com/docker/docker-agent/pkg/chat"
+	"github.com/docker/docker-agent/pkg/config/latest"
+	"github.com/docker/docker-agent/pkg/environment"
+	"github.com/docker/docker-agent/pkg/model/provider/base"
+	"github.com/docker/docker-agent/pkg/model/provider/options"
+	"github.com/docker/docker-agent/pkg/tools"
+)
+
+// TestNewRequestShape_Minimal verifies that a request with no tools, no
+// thinking override, and no structured output produces an all-zero-value
+// shape (aside from the API surface), matching the actual gemini-2.5-flash-image
+// image-generation request captured in production diagnostics.
+func TestNewRequestShape_Minimal(t *testing.T) {
+	t.Parallel()
+
+	client := &Client{
+		Config: base.Config{
+			ModelConfig: latest.ModelConfig{Provider: "google", Model: "gemini-2.5-flash-image"},
+		},
+		apiSurface: apiSurfaceGeminiAPI,
+	}
+
+	config := client.buildConfig()
+	config.Tools = client.builtInTools()
+
+	shape := newRequestShape(client, config, 0)
+
+	assert.False(t, shape.ResponseModalitiesSet)
+	assert.Empty(t, shape.ResponseModalities)
+	assert.Equal(t, 0, shape.BuiltInToolCount)
+	assert.Empty(t, shape.BuiltInToolKinds)
+	assert.Equal(t, 0, shape.FunctionToolCount)
+	assert.False(t, shape.HasToolConfig)
+	assert.False(t, shape.StructuredOutputPresent)
+	assert.False(t, shape.ThinkingConfigSet)
+	assert.False(t, shape.NoThinkingRequested)
+	assert.Equal(t, apiSurfaceGeminiAPI, shape.APISurface)
+	// No authoritative output-capability source exists yet: diagnostics must
+	// report "unknown", never guess from the model ID.
+	assert.False(t, shape.OutputCapabilityKnown)
+	assert.False(t, shape.OutputCapabilityEnabled)
+}
+
+// TestNewRequestShape_ToolsAndBuiltIns mirrors the tool-attachment logic in
+// CreateChatCompletionStream to verify the shape captures built-in tool
+// kinds/count, custom function count, ToolConfig mode, and the server-side
+// tool invocation flag Gemini requires when mixing built-ins with functions.
+func TestNewRequestShape_ToolsAndBuiltIns(t *testing.T) {
+	t.Parallel()
+
+	client := &Client{
+		Config: base.Config{
+			ModelConfig: latest.ModelConfig{
+				Provider:     "google",
+				Model:        "gemini-2.5-flash",
+				ProviderOpts: map[string]any{"google_search": true, "google_maps": true},
+			},
+		},
+		apiSurface: apiSurfaceVertexAI,
+	}
+
+	config := client.buildConfig()
+	config.Tools = client.builtInTools()
+
+	requestTools := []tools.Tool{
+		{Name: "read_file", Description: "reads a file", Parameters: map[string]any{"type": "object"}},
+		{Name: "write_file", Description: "writes a file", Parameters: map[string]any{"type": "object"}},
+	}
+	allTools, err := convertToolsToGemini(requestTools)
+	require.NoError(t, err)
+	config.Tools = append(config.Tools, allTools...)
+	config.ToolConfig = &genai.ToolConfig{
+		FunctionCallingConfig: &genai.FunctionCallingConfig{Mode: genai.FunctionCallingConfigModeAuto},
+	}
+	if len(config.Tools) > len(allTools) {
+		config.ToolConfig.IncludeServerSideToolInvocations = new(true)
+	}
+
+	shape := newRequestShape(client, config, len(requestTools))
+
+	assert.Equal(t, 2, shape.BuiltInToolCount)
+	assert.ElementsMatch(t, []string{"google_search", "google_maps"}, shape.BuiltInToolKinds)
+	assert.Equal(t, 2, shape.FunctionToolCount)
+	assert.True(t, shape.HasToolConfig)
+	assert.Equal(t, string(genai.FunctionCallingConfigModeAuto), shape.FunctionCallingMode)
+	assert.True(t, shape.ServerSideToolInvocation, "mixing built-in and function tools must set the server-side invocation flag")
+	assert.Equal(t, apiSurfaceVertexAI, shape.APISurface)
+}
+
+// TestNewRequestShape_ResponseModalitiesNormalized verifies modality values
+// are trimmed, upper-cased, and de-duplicated, and that "set" reflects
+// presence independent of the normalized values.
+func TestNewRequestShape_ResponseModalitiesNormalized(t *testing.T) {
+	t.Parallel()
+
+	client := &Client{Config: base.Config{ModelConfig: latest.ModelConfig{Provider: "google", Model: "gemini-2.5-flash-image"}}}
+	config := client.buildConfig()
+	config.ResponseModalities = []string{" text ", "IMAGE", "text", ""}
+
+	shape := newRequestShape(client, config, 0)
+
+	assert.True(t, shape.ResponseModalitiesSet)
+	assert.Equal(t, []string{"TEXT", "IMAGE"}, shape.ResponseModalities)
+}
+
+// TestNewRequestShape_NoThinkingRequested verifies the title-generation path
+// (options.WithNoThinking) is captured: a non-Gemini-3 model gets an
+// explicit ThinkingConfig even though the model config itself set no
+// thinking budget.
+func TestNewRequestShape_NoThinkingRequested(t *testing.T) {
+	t.Parallel()
+
+	client := &Client{
+		Config: base.Config{
+			ModelConfig:  latest.ModelConfig{Provider: "google", Model: "gemini-2.5-flash-image"},
+			ModelOptions: options.Apply(options.WithNoThinking()),
+		},
+	}
+	config := client.buildConfig()
+
+	shape := newRequestShape(client, config, 0)
+
+	assert.True(t, shape.ThinkingConfigSet)
+	assert.True(t, shape.NoThinkingRequested)
+}
+
+// TestNewRequestShape_StructuredOutputPresent verifies structured-output
+// presence is captured as a boolean only — never the schema contents.
+func TestNewRequestShape_StructuredOutputPresent(t *testing.T) {
+	t.Parallel()
+
+	client := &Client{
+		Config: base.Config{
+			ModelConfig: latest.ModelConfig{Provider: "google", Model: "gemini-2.5-flash"},
+			ModelOptions: options.Apply(options.WithStructuredOutput(&latest.StructuredOutput{
+				Schema: map[string]any{"type": "object", "properties": map[string]any{"secret_field_name": map[string]any{"type": "string"}}},
+			})),
+		},
+	}
+	config := client.buildConfig()
+
+	shape := newRequestShape(client, config, 0)
+
+	require.True(t, shape.StructuredOutputPresent)
+
+	// The shape must never carry the schema itself.
+	for _, attr := range shape.LogAttrs() {
+		if s, ok := attr.(string); ok {
+			assert.NotContains(t, s, "secret_field_name")
+		}
+	}
+}
+
+// TestRequestShape_LogAttrsNeverLeaksToolSchemas is the core safety
+// regression for this diagnostic: it builds a request with a function tool
+// carrying a marker description and parameter schema, then verifies that
+// nothing serialized by LogAttrs (or logged through CreateChatCompletionStream)
+// contains that marker. This is exactly the kind of leak the previous
+// per-tool debug logging in CreateChatCompletionStream produced.
+func TestRequestShape_LogAttrsNeverLeaksToolSchemas(t *testing.T) {
+	t.Parallel()
+
+	const marker = "SECRET_TOOL_DESCRIPTION_MARKER"
+
+	client := &Client{Config: base.Config{ModelConfig: latest.ModelConfig{Provider: "google", Model: "gemini-2.5-flash"}}}
+	config := client.buildConfig()
+
+	requestTools := []tools.Tool{
+		{Name: "danger_tool", Description: marker, Parameters: map[string]any{"type": "object", "properties": map[string]any{marker: map[string]any{"type": "string"}}}},
+	}
+	allTools, err := convertToolsToGemini(requestTools)
+	require.NoError(t, err)
+	config.Tools = allTools
+
+	shape := newRequestShape(client, config, len(requestTools))
+
+	for _, attr := range flattenAttrs(shape.LogAttrs()) {
+		assert.NotContains(t, attr, marker, "RequestShape must never carry tool descriptions or schemas")
+	}
+}
+
+// flattenAttrs renders slog-style key/value pairs to strings for substring
+// assertions in tests.
+func flattenAttrs(attrs []any) []string {
+	out := make([]string, 0, len(attrs))
+	for _, a := range attrs {
+		switch v := a.(type) {
+		case string:
+			out = append(out, v)
+		case []string:
+			out = append(out, v...)
+		}
+	}
+	return out
+}
+
+// TestCreateChatCompletionStream_DebugLogNeverLeaksToolSchemas is an
+// end-to-end regression at the CreateChatCompletionStream boundary: it
+// swaps the default slog logger for a buffer-backed one, issues a real
+// request (against a local httptest server) with a marker-carrying tool,
+// and asserts the marker never reaches the debug log — the leak the old
+// per-tool "Function" debug log would have produced. Not parallel: it
+// swaps process-global slog state.
+func TestCreateChatCompletionStream_DebugLogNeverLeaksToolSchemas(t *testing.T) {
+	const marker = "SECRET_TOOL_DESCRIPTION_MARKER_E2E"
+
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug})))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		writeGeminiSSEResponse(w)
+	}))
+	defer server.Close()
+
+	cfg := &latest.ModelConfig{Provider: "google", Model: "gemini-2.5-flash", BaseURL: server.URL}
+	env := environment.NewMapEnvProvider(map[string]string{"GOOGLE_API_KEY": "test-key"})
+
+	client, err := NewClient(t.Context(), cfg, env)
+	require.NoError(t, err)
+
+	stream, err := client.CreateChatCompletionStream(t.Context(), []chat.Message{
+		{Role: chat.MessageRoleUser, Content: "hello"},
+	}, []tools.Tool{
+		{Name: marker, Description: marker, Parameters: map[string]any{"type": "object", "properties": map[string]any{marker: map[string]any{"type": "string"}}}},
+	})
+	require.NoError(t, err)
+	defer stream.Close()
+
+	for {
+		if _, err := stream.Recv(); err != nil {
+			break
+		}
+	}
+
+	assert.NotContains(t, buf.String(), marker, "debug logs must never contain a tool name, description, or schema value")
+}
+
+// splitDiffNeedles are case-insensitive substrings that would appear in Go
+// source if Split Diff View state ever leaked into a name, description, or
+// argument sent to a model provider.
+var splitDiffNeedles = []string{"splitdiff", "split-diff", "split_diff"}
+
+// splitDiffTraceRoots are the source directories a Split Diff reference
+// would have to pass through to ever reach a Gemini request: this package
+// (where the request is finally serialized) and the two layers upstream of
+// it that assemble what every provider call receives — pkg/tools (where the
+// []tools.Tool list handed to CreateChatCompletionStream is built) and
+// pkg/runtime (where messages and tools are gathered before any provider
+// call). Dynamic MCP/external tool registrations are out of reach of a
+// static scan; the local built-in tool definitions and the request-building
+// path itself are not.
+var splitDiffTraceRoots = []string{".", "../../../tools", "../../../runtime"}
+
+// TestSplitDiffView_NeverReferencedInToolOrRequestBuildingSource is a static
+// source-scan classification for the owner's screenshot, which showed
+// "Split Diff View" active in the sidebar alongside an observed Gemini 400.
+// It is a source scan, not a runtime trace: it proves that no non-test .go
+// file under [splitDiffTraceRoots] mentions Split Diff View in any form,
+// tracing the actual boundary a reference would have to cross — tool
+// registration (pkg/tools) and request assembly (pkg/runtime) — rather than
+// just this leaf package. It cannot see into MCP/other dynamically
+// registered tools, which no static scan can enumerate.
+//
+// That, combined with reading pkg/tui/service/sessionstate.go (SplitDiffView
+// is a plain bool getter/setter backed by session/userconfig persistence,
+// wired only into TUI rendering — pkg/tui/components/sidebar/sidebar.go,
+// pkg/tui/components/tool/editfile) and confirming pkg/tools and
+// pkg/runtime contain no reference to it either, is the evidence for
+// classifying Split Diff View as local-only TUI/session state with no path
+// into any provider request, Gemini included.
+//
+// If a future change ever wires it into a tool/config sent to a provider,
+// this test fails wherever that reference lands, and the classification
+// must move from "local-only" to "serialized-tool".
+func TestSplitDiffView_NeverReferencedInToolOrRequestBuildingSource(t *testing.T) {
+	t.Parallel()
+
+	for _, root := range splitDiffTraceRoots {
+		for _, path := range goSourceFiles(t, root) {
+			assertNoSplitDiffReference(t, path)
+		}
+	}
+}
+
+// goSourceFiles returns every non-test .go file under root, recursively.
+func goSourceFiles(t *testing.T, root string) []string {
+	t.Helper()
+
+	var files []string
+	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() || !strings.HasSuffix(d.Name(), ".go") || strings.HasSuffix(d.Name(), "_test.go") {
+			return nil
+		}
+		files = append(files, path)
+		return nil
+	})
+	require.NoError(t, err)
+	return files
+}
+
+func assertNoSplitDiffReference(t *testing.T, path string) {
+	t.Helper()
+
+	content, err := os.ReadFile(path)
+	require.NoError(t, err)
+	lower := strings.ToLower(string(content))
+	for _, needle := range splitDiffNeedles {
+		assert.NotContains(t, lower, needle,
+			"%s must never reference split-diff: it is local-only TUI state, never a tool/request field", path)
+	}
+}
diff --git a/pkg/model/provider/gemini/wrap.go b/pkg/model/provider/gemini/wrap.go
index ea23ee7963..cf77d83965 100644
--- a/pkg/model/provider/gemini/wrap.go
+++ b/pkg/model/provider/gemini/wrap.go
@@ -2,14 +2,26 @@ package gemini
 
 import (
 	"errors"
+	"fmt"
+	"net/http"
+	"strings"
 
+	"github.com/docker/portcullis"
 	"google.golang.org/genai"
 
+	"github.com/docker/docker-agent/pkg/chat"
 	"github.com/docker/docker-agent/pkg/modelerrors"
 )
 
 // wrapGeminiError wraps a Gemini SDK error in a *modelerrors.StatusError
-// to carry HTTP status code metadata for the retry loop.
+// to carry HTTP status code metadata for the retry loop, and — for HTTP 400
+// rejections — decorates it with a bounded [RequestRejectionCategory] and an
+// action-oriented [APIRejectionError] message that also preserves a bounded,
+// sanitized rendering of the SDK's own Message (see [sanitizeAPIErrorMessage]).
+// The category is derived only from keyword matching against that same
+// Message field; Details (the raw response body) is never inspected or
+// surfaced.
+//
 // Gemini's *genai.APIError does not expose *http.Response, so no Retry-After
 // header extraction is possible; the RetryAfter field will be zero.
 // Non-Gemini errors (e.g. io.EOF, network errors) pass through unchanged.
@@ -17,10 +29,118 @@ func wrapGeminiError(err error) error {
 	if err == nil {
 		return nil
 	}
-	apiErr, ok := errors.AsType[*genai.APIError](err)
+	// google.golang.org/genai's newAPIError returns APIError by value (see
+	// its `func (e APIError) Error() string`), never a pointer, so the type
+	// parameter here must match a value type. Asserting *genai.APIError
+	// would silently never match, letting every Gemini error through
+	// unclassified and unwrapped (no StatusCode, no category).
+	apiErr, ok := errors.AsType[genai.APIError](err)
 	if !ok {
 		return err
 	}
+
+	wrapped := err
+	if apiErr.Code == http.StatusBadRequest {
+		category, _ := classifyByMessage(apiErr.Message)
+		wrapped = &APIRejectionError{APIError: apiErr, Category: category}
+	}
+
 	// Pass nil for resp — Gemini doesn't expose *http.Response.
-	return modelerrors.WrapHTTPError(apiErr.Code, nil, err)
+	return modelerrors.WrapHTTPError(apiErr.Code, nil, wrapped)
+}
+
+// APIRejectionError decorates a Gemini HTTP 400 [genai.APIError] with a
+// bounded [RequestRejectionCategory] and an action-oriented hint, then
+// appends the SDK's own Message — bounded, single-line, JSON-envelope-
+// neutralized, and secret-redacted via [sanitizeAPIErrorMessage] — rather
+// than replacing it outright. Details (the raw response body, which can
+// carry field paths, schemas, or other request-shaped data) is never
+// inspected or surfaced. Preserving a safe rendering of Message matters
+// beyond this package: general model-error classification (pkg/modelerrors)
+// identifies context overflow and retryable transient rejections by
+// matching known phrases against err.Error() — replacing Message entirely
+// broke both for Gemini 400s (see wrap_test.go's classification-chain
+// tests). An auth-shaped 400 (e.g. "API key not valid") isn't affected by
+// either classifier: a *modelerrors.StatusError short-circuits before the
+// phrase-based fallback that would inspect it. Dropping Message there still
+// cost the user the provider's own informative text, leaving only a
+// generic "request shape" hint — a loss of visible context, not a
+// classifier failure.
+type APIRejectionError struct {
+	genai.APIError
+
+	Category RequestRejectionCategory
+}
+
+func (e *APIRejectionError) Unwrap() error { return e.APIError }
+
+func (e *APIRejectionError) Error() string {
+	msg := fmt.Sprintf("provider rejected the request (%s): %s", e.Category, categoryHint(e.Category))
+	if detail := sanitizeAPIErrorMessage(e.Message); detail != "" {
+		msg += " — provider message: " + detail
+	}
+	return msg
+}
+
+// maxSanitizedAPIErrorMessageBytes bounds the provider message preserved in
+// [APIRejectionError.Error], independent of the unrelated field-length bound
+// pkg/chat applies to display-name-shaped fields: this is free-form
+// provider text, and downstream substring classification (e.g.
+// modelerrors' "input token count" / "number of function response parts"
+// patterns) needs enough of it intact to keep matching, while still staying
+// well short of a provider's full, unbounded response body.
+const maxSanitizedAPIErrorMessageBytes = 300
+
+// sanitizeAPIErrorMessage returns a bounded, single-line, secret-redacted,
+// JSON-envelope-neutralized rendering of message — intended to be called
+// with a Gemini [genai.APIError]'s own Message field, never Details (the
+// raw response body). Control characters and newlines are collapsed to
+// single spaces, '{' and '}' are rewritten to '(' and ')' so a
+// JSON-object-shaped envelope embedded in Message (e.g. a proxy forwarding
+// an upstream body verbatim) can't later be re-parsed by
+// modelerrors.StatusError.Error (see parseProviderError in pkg/modelerrors)
+// and have its own fields substituted for this package's category/hint,
+// [portcullis.Redact] scrubs any recognizable credential/secret span, and
+// the result is truncated to [maxSanitizedAPIErrorMessageBytes] via
+// [chat.TruncateUTF8Bytes]. An empty message returns "".
+func sanitizeAPIErrorMessage(message string) string {
+	if message == "" {
+		return ""
+	}
+	var b strings.Builder
+	b.Grow(len(message))
+	for _, r := range message {
+		switch {
+		case r < 0x20 || r == 0x7f:
+			b.WriteRune(' ')
+		case r == '{':
+			b.WriteRune('(')
+		case r == '}':
+			b.WriteRune(')')
+		default:
+			b.WriteRune(r)
+		}
+	}
+	collapsed := strings.Join(strings.Fields(b.String()), " ")
+	redacted := portcullis.Redact(collapsed)
+	return chat.TruncateUTF8Bytes(redacted, maxSanitizedAPIErrorMessageBytes)
+}
+
+// categoryHint returns a short, safe, actionable explanation for a
+// [RequestRejectionCategory]. It never echoes provider-supplied text.
+func categoryHint(c RequestRejectionCategory) string {
+	switch c {
+	case RejectionMissingResponseModalities:
+		return "the response may need an explicit output modality (e.g. image) that this request didn't set"
+	case RejectionIncompatibleFunctionOrBuiltinTools:
+		return "the combination of tools enabled for this request may not be supported by this model"
+	case RejectionIncompatibleToolConfig:
+		return "the tool-invocation configuration may not be supported by this model"
+	case RejectionStructuredOutputConflict:
+		return "structured output may conflict with another option in this request"
+	case RejectionModelOrAPICapabilityMismatch:
+		return "this model may not support a feature enabled for this request (e.g. thinking/reasoning)"
+	default:
+		return "the request shape may be incompatible with this model or its current configuration"
+	}
 }
diff --git a/pkg/model/provider/gemini/wrap_test.go b/pkg/model/provider/gemini/wrap_test.go
new file mode 100644
index 0000000000..977b4086e9
--- /dev/null
+++ b/pkg/model/provider/gemini/wrap_test.go
@@ -0,0 +1,330 @@
+package gemini
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/docker/portcullis"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/genai"
+
+	"github.com/docker/docker-agent/pkg/internal/portcullistest"
+	"github.com/docker/docker-agent/pkg/modelerrors"
+)
+
+// TestWrapGeminiError_ValueTypeAPIError is the regression for the pointer-vs-
+// value bug: google.golang.org/genai returns APIError by value (its Error()
+// method has a value receiver), so a type assertion for *genai.APIError never
+// matches and every Gemini API error previously passed through unwrapped,
+// with no *modelerrors.StatusError and no category. This reproduces the
+// exact shape observed for a Gemini 400 with an empty body (empty Message,
+// empty Details) and verifies it is now correctly classified.
+func TestWrapGeminiError_ValueTypeAPIError(t *testing.T) {
+	t.Parallel()
+
+	apiErr := genai.APIError{Code: http.StatusBadRequest, Status: "400 Bad Request"}
+
+	wrapped := wrapGeminiError(apiErr)
+
+	var statusErr *modelerrors.StatusError
+	require.ErrorAs(t, wrapped, &statusErr, "a Gemini APIError must be classified as a *modelerrors.StatusError")
+	assert.Equal(t, http.StatusBadRequest, statusErr.StatusCode)
+	assert.Equal(t, 0, int(statusErr.RetryAfter), "Gemini exposes no *http.Response, so Retry-After must stay zero")
+
+	var rejErr *APIRejectionError
+	require.ErrorAs(t, wrapped, &rejErr, "a 400 must be decorated with *APIRejectionError")
+	assert.Equal(t, RejectionOther, rejErr.Category, "an empty message has no keyword to classify against")
+}
+
+// TestWrapGeminiError_NonBadRequestPassesThroughRawMessage verifies only 400s
+// get the action-oriented override; other status codes keep the SDK's own
+// Error() text so existing retry/rate-limit classification (which inspects
+// the message for patterns like "429") keeps working unchanged.
+func TestWrapGeminiError_NonBadRequestPassesThroughRawMessage(t *testing.T) {
+	t.Parallel()
+
+	apiErr := genai.APIError{Code: http.StatusTooManyRequests, Status: "429 Too Many Requests", Message: "rate limit exceeded"}
+
+	wrapped := wrapGeminiError(apiErr)
+
+	var statusErr *modelerrors.StatusError
+	require.ErrorAs(t, wrapped, &statusErr)
+	assert.Equal(t, http.StatusTooManyRequests, statusErr.StatusCode)
+
+	var rejErr *APIRejectionError
+	assert.NotErrorAs(t, wrapped, &rejErr, "only 400s are decorated with APIRejectionError")
+
+	_, rateLimited, _ := modelerrors.ClassifyModelError(wrapped)
+	assert.True(t, rateLimited, "429 classification must keep working after the fix")
+}
+
+// TestWrapGeminiError_NonGeminiErrorPassesThrough verifies errors unrelated
+// to the Gemini SDK (network errors, io.EOF, other providers) are returned
+// unchanged.
+func TestWrapGeminiError_NonGeminiErrorPassesThrough(t *testing.T) {
+	t.Parallel()
+
+	original := errors.New("boom")
+	assert.Same(t, original, wrapGeminiError(original))
+
+	assert.NoError(t, wrapGeminiError(nil))
+}
+
+// TestAPIRejectionError_RedactsSecretsAndNeverLeaksDetails is the core safety
+// regression for the preserved-message design: APIRejectionError.Error() now
+// deliberately echoes a bounded, sanitized rendering of the SDK's own
+// Message (see [sanitizeAPIErrorMessage]) so downstream classification keeps
+// working, but it must still redact any real credential/secret span
+// portcullis recognizes within that Message, and it must never surface
+// Details (the raw response body) at all, however sensitive-looking its
+// contents.
+func TestAPIRejectionError_RedactsSecretsAndNeverLeaksDetails(t *testing.T) {
+	t.Parallel()
+
+	secret := portcullistest.FakeGitHubPAT("1234567890abcdefghijklmnopqrst")
+
+	apiErr := genai.APIError{
+		Code:    http.StatusBadRequest,
+		Status:  "400 Bad Request",
+		Message: "invalid argument: token " + secret + " is not authorized",
+		Details: []map[string]any{{"reason": secret, "path": "/some/local/path"}},
+	}
+
+	wrapped := wrapGeminiError(apiErr)
+	visible := wrapped.Error()
+
+	assert.NotContains(t, visible, secret, "a real credential in Message must be redacted")
+	assert.Contains(t, visible, portcullis.Marker, "the redaction marker must take its place")
+	assert.Contains(t, visible, "invalid argument", "surrounding message text must be preserved for classification")
+	assert.NotContains(t, visible, "/some/local/path", "Details must never be surfaced")
+	assert.NotContains(t, visible, "Details:")
+}
+
+// TestWrapGeminiError_FormatErrorIsActionableAndSafe is the end-to-end
+// regression for the runtime/TUI-visible error seam: it drives a wrapped
+// 400 through the same modelerrors.FormatError call the runtime loop uses
+// to build ErrorEvent.Error (pkg/runtime/loop_steps.go), which the TUI
+// renders verbatim (pkg/tui/page/chat/runtime_events.go). Before this
+// classification, an empty-body Gemini 400 produced just "HTTP 400: " with
+// no actionable content; this proves the visible message now names a
+// bounded category and hint, keeps the sanitized provider message visible,
+// and still redacts a real credential found within it.
+func TestWrapGeminiError_FormatErrorIsActionableAndSafe(t *testing.T) {
+	t.Parallel()
+
+	secret := portcullistest.FakeGitHubPAT("abcdefghijklmnopqrstuvwxyz0123")
+
+	apiErr := genai.APIError{
+		Code:    http.StatusBadRequest,
+		Status:  "400 Bad Request",
+		Message: "response_modalities: token " + secret + " rejected",
+	}
+
+	visible := modelerrors.FormatError(wrapGeminiError(apiErr))
+
+	assert.Contains(t, visible, string(RejectionMissingResponseModalities))
+	assert.Contains(t, visible, "output modality")
+	assert.Contains(t, visible, "response_modalities", "the sanitized provider message must stay visible for classification/diagnosis")
+	assert.NotContains(t, visible, secret, "a real credential must be redacted even when the surrounding message is preserved")
+	assert.NotContains(t, visible, "\n", "the visible message must stay a single line")
+}
+
+// TestWrapGeminiError_ContextOverflowClassificationSurvivesWrapping is the
+// blocking regression for context-overflow classification: Gemini reports
+// token-window overflow as an HTTP 400 whose message contains "input token
+// count" (see modelerrors' tokenOverflowPatterns). Replacing that message
+// with fixed category text made every Gemini overflow invisible to
+// modelerrors.IsContextOverflowError; preserving a sanitized rendering of it
+// restores auto-compaction triggering.
+func TestWrapGeminiError_ContextOverflowClassificationSurvivesWrapping(t *testing.T) {
+	t.Parallel()
+
+	apiErr := genai.APIError{
+		Code:    http.StatusBadRequest,
+		Status:  "400 Bad Request",
+		Message: "The input token count (123456) exceeds the maximum number of tokens allowed (100000) for this model.",
+	}
+
+	wrapped := wrapGeminiError(apiErr)
+
+	require.True(t, modelerrors.IsContextOverflowError(wrapped),
+		"a preserved, sanitized provider message must still let modelerrors recognize a Gemini context overflow")
+	assert.Equal(t, modelerrors.OverflowKindTokens, modelerrors.OverflowKindOf(wrapped))
+}
+
+// TestWrapGeminiError_TransientFunctionResponseIsRetryable is the blocking
+// regression for issue #2683: Vertex/Gemini sometimes returns a transient
+// HTTP 400 whose message says the number of function response parts must
+// equal the number of function call parts, and modelerrors treats that
+// specific message as retryable (matchesTransientPattern) even though 400s
+// are otherwise non-retryable. Replacing the message broke this override for
+// Gemini; preserving it restores same-model retry instead of an immediate,
+// unnecessary fallback/failure.
+func TestWrapGeminiError_TransientFunctionResponseIsRetryable(t *testing.T) {
+	t.Parallel()
+
+	apiErr := genai.APIError{
+		Code:   http.StatusBadRequest,
+		Status: "400 Bad Request",
+		Message: "Please ensure that the number of function response parts is equal to the number of " +
+			"function call parts of the function call turn.",
+	}
+
+	wrapped := wrapGeminiError(apiErr)
+
+	retryable, rateLimited, _ := modelerrors.ClassifyModelError(wrapped)
+	assert.True(t, retryable, "issue #2683's transient function-response 400 must stay retryable after classification")
+	assert.False(t, rateLimited)
+}
+
+// TestWrapGeminiError_AuthMessageStaysInformative is the blocking regression
+// for auth-shaped 400s: Gemini reports an invalid/missing API key as an HTTP
+// 400 with an informative message rather than a 401. No documented request
+// field keyword matches it, so it classifies as [RejectionOther]. The
+// regression here is loss of visible context, not a broken classifier —
+// modelerrors never runs auth-phrase classification on this error at all,
+// since its *StatusError short-circuits that fallback — so the requirement
+// is simply that the visible error keeps surfacing the provider's own "API
+// key not valid" text instead of a generic, uninformative "request shape"
+// hint.
+func TestWrapGeminiError_AuthMessageStaysInformative(t *testing.T) {
+	t.Parallel()
+
+	apiErr := genai.APIError{
+		Code:    http.StatusBadRequest,
+		Status:  "400 Bad Request",
+		Message: "API key not valid. Please pass a valid API key.",
+	}
+
+	wrapped := wrapGeminiError(apiErr)
+	visible := modelerrors.FormatError(wrapped)
+
+	assert.Contains(t, visible, "API key not valid",
+		"an auth-shaped 400 must stay informative instead of being replaced by a generic request-shape hint")
+	assert.Contains(t, visible, string(RejectionOther), "no documented field keyword matches an auth message")
+}
+
+// TestSanitizeAPIErrorMessage covers the bounds this diagnostics feature
+// relies on for safety: control characters and newlines collapse to a single
+// line, recognizable secrets are redacted, and the output never exceeds
+// [maxSanitizedAPIErrorMessageBytes].
+func TestSanitizeAPIErrorMessage(t *testing.T) {
+	t.Parallel()
+
+	t.Run("empty", func(t *testing.T) {
+		t.Parallel()
+		assert.Empty(t, sanitizeAPIErrorMessage(""))
+	})
+
+	t.Run("collapses control characters and newlines to a single line", func(t *testing.T) {
+		t.Parallel()
+		got := sanitizeAPIErrorMessage("line one\r\nline\ttwo\x00\x1f")
+		assert.NotContains(t, got, "\n")
+		assert.NotContains(t, got, "\r")
+		assert.NotContains(t, got, "\t")
+		assert.Equal(t, "line one line two", got)
+	})
+
+	t.Run("redacts a recognizable secret", func(t *testing.T) {
+		t.Parallel()
+		secret := portcullistest.FakeGitHubPAT("zzzzzzzzzzzzzzzzzzzzzzzzzzzzzz")
+		got := sanitizeAPIErrorMessage("token " + secret + " rejected")
+		assert.NotContains(t, got, secret)
+		assert.Contains(t, got, portcullis.Marker)
+		assert.Contains(t, got, "rejected")
+	})
+
+	t.Run("bounds output length", func(t *testing.T) {
+		t.Parallel()
+		got := sanitizeAPIErrorMessage(strings.Repeat("a", maxSanitizedAPIErrorMessageBytes*2))
+		assert.LessOrEqual(t, len(got), maxSanitizedAPIErrorMessageBytes)
+	})
+
+	t.Run("neutralizes JSON-object braces so a downstream reparse can't hijack the message", func(t *testing.T) {
+		t.Parallel()
+		got := sanitizeAPIErrorMessage(`prefix {"error":{"message":"x","status":"UNAUTHENTICATED"}} suffix`)
+		assert.NotContains(t, got, "{")
+		assert.NotContains(t, got, "}")
+		assert.Contains(t, got, `("error":("message":"x","status":"UNAUTHENTICATED"))`)
+	})
+}
+
+// TestWrapGeminiError_JSONShapedMessageEnvelopeStaysInertAndSafe is the
+// regression for modelerrors.StatusError re-parsing a JSON-object-shaped
+// envelope embedded in the SDK's own Message (e.g. a proxy forwarding an
+// upstream body verbatim): parseProviderError
+// (pkg/modelerrors/modelerrors.go) scans an error's full Error() string for
+// the first "{...}" object and, if it looks like a provider error body,
+// replaces the ENTIRE message with just that body's fields — silently
+// dropping this package's category/hint. It drives both
+// [*APIRejectionError.Error] directly and the full
+// wrapGeminiError -> StatusError.Error -> modelerrors.FormatError seam, and
+// requires the category/hint survive, no literal brace reach the visible
+// text, a real credential embedded inside the envelope still be redacted,
+// and Details never surface — JSON-shaped or not.
+func TestWrapGeminiError_JSONShapedMessageEnvelopeStaysInertAndSafe(t *testing.T) {
+	t.Parallel()
+
+	secret := portcullistest.FakeGitHubPAT("0123456789abcdefghijklmnopqrst")
+	apiErr := genai.APIError{
+		Code:   http.StatusBadRequest,
+		Status: "400 Bad Request",
+		Message: `Upstream gateway returned {"error":{"message":"token ` + secret +
+			` rejected","status":"UNAUTHENTICATED"}} while forwarding the request`,
+		Details: []map[string]any{{"secret": secret, "path": "/etc/passwd"}},
+	}
+
+	wrapped := wrapGeminiError(apiErr)
+
+	for _, visible := range []string{wrapped.Error(), modelerrors.FormatError(wrapped)} {
+		assert.Contains(t, visible, string(RejectionOther),
+			"the category must survive an embedded JSON-shaped envelope in Message")
+		assert.Contains(t, visible, "request shape may be incompatible",
+			"the hint must survive, not be replaced by modelerrors reparsing the embedded JSON body")
+		assert.NotContains(t, visible, "{",
+			"a JSON-object brace from the provider message must be neutralized before modelerrors.StatusError can reparse it")
+		assert.NotContains(t, visible, "}")
+		assert.NotContains(t, visible, secret,
+			"a credential embedded inside the JSON-shaped envelope must still be redacted")
+		assert.Contains(t, visible, portcullis.Marker)
+		assert.NotContains(t, visible, "/etc/passwd", "Details must never be surfaced, JSON-shaped or not")
+		assert.NotContains(t, visible, "\n")
+	}
+}
+
+// TestClassifyByMessage covers the bounded keyword classification for each
+// category, plus the no-match and empty-message fallbacks. Keywords are
+// Google's own public, documented API field names — not derived from any
+// captured request.
+func TestClassifyByMessage(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name         string
+		message      string
+		wantCategory RequestRejectionCategory
+		wantMatched  bool
+	}{
+		{"empty message", "", RejectionOther, false},
+		{"no keyword match", "something went wrong", RejectionOther, false},
+		{"response_modalities", "Invalid value for response_modalities: must include IMAGE", RejectionMissingResponseModalities, true},
+		{"response_schema", "response_schema is not supported with response_mime_type text/plain", RejectionStructuredOutputConflict, true},
+		{"tool_config", "tool_config.function_calling_config.mode is invalid", RejectionIncompatibleToolConfig, true},
+		{"function_declarations", "function_declarations are not supported for this model", RejectionIncompatibleFunctionOrBuiltinTools, true},
+		{"google_search built-in", "google_search tool is not supported with function calling", RejectionIncompatibleFunctionOrBuiltinTools, true},
+		{"thinking_config", "thinking_config is not supported for this model", RejectionModelOrAPICapabilityMismatch, true},
+		{"generic not supported", "this feature is not supported by this model", RejectionModelOrAPICapabilityMismatch, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			category, matched := classifyByMessage(tt.message)
+			assert.Equal(t, tt.wantCategory, category)
+			assert.Equal(t, tt.wantMatched, matched)
+		})
+	}
+}