feat(#3996): reject incompatible image-output Google requests

Reject tools, built-in tools, and structured output before dispatch whenever image output resolves enabled on Google gateway, direct Gemini API, or Vertex AI. The guard uses the same binding capability policy as request construction: explicit false, then explicit true, then exact models.dev Modalities.Output=image for an omitted image flag; unknown or unavailable metadata stays off. It never guesses from model names.

Return fixed safe incompatibility classes, enrich custom-tool errors from models.dev tool_call metadata when available, and keep provider text, prompts, names, and schemas out of user-visible guard errors.

Author: aheritier

docs/providers/google/index.md

@@ -60,6 +60,34 @@ models:
 | `gemini-2.5-flash`        | Fast inference, cost-effective  |
 | `gemini-2.5-pro`          | Strong reasoning, large context |
 
+## Generated Images
+
+Some Gemini models (e.g. `gemini-2.5-flash-image`) are designed to generate
+an image directly as part of their reply, not just describe one. Docker
+Agent's Gemini request path doesn't yet ask for that image output — that
+support is still being completed — so today a request like this gets a
+text-only reply. See
+[Generated Media](../../features/tui/index.md#generated-media) for the
+current, verified state.
+
+```yaml
+agents:
+  root:
+    model: google/gemini-2.5-flash-image
+```
+
+When the model is accessed through a Docker AI Gateway and explicitly
+declared image-output-capable with
+[`output_capabilities.image: true`](../../configuration/models/index.md#output-capabilities),
+Docker Agent has verified that request combined with custom function tools,
+a built-in tool (e.g. `google_search`), or structured output gets rejected
+by the gateway with an opaque, empty-body HTTP 400. To avoid that, Docker
+Agent rejects such a combination itself, before any request is sent, with a
+clear error naming which feature is incompatible. Plain text requests to
+that model (no tools, no structured output) are unaffected, as is every
+other route: direct Gemini API/Vertex AI calls, and gateway calls to a model
+without the declaration.
+
 ## Thinking Budget
 
 Gemini supports two approaches depending on the model version:

pkg/model/provider/base/base.go

@@ -79,6 +79,11 @@ func (c *Config) CapsOverride() *modelinfo.CapsOverride {
 	return &modelinfo.CapsOverride{Image: caps.Image, PDF: caps.PDF, Audio: caps.Audio, Video: caps.Video}
 }
 
+// ToolCallSupport resolves the model's tool-call capability from models.dev.
+func (c *Config) ToolCallSupport(ctx context.Context) modelinfo.ToolCallSupport {
+	return modelinfo.ResolveToolCallSupport(ctx, c.ModelOptions.ModelsDevStore(), c.ID())
+}
+
 // ImageOutputEnabled resolves the model's image-output capability from its
 // explicit tri-state configuration and, when unset, the models.dev catalogue.
 func (c *Config) ImageOutputEnabled(ctx context.Context) bool {

pkg/model/provider/base/base_test.go

@@ -59,6 +59,22 @@ func TestConfigCapsOverride(t *testing.T) {
 	})
 }
 
+func TestConfigToolCallSupport(t *testing.T) {
+	t.Parallel()
+
+	store := modelsdev.NewDatabaseStore(&modelsdev.Database{Providers: map[string]modelsdev.Provider{
+		"google": {Models: map[string]modelsdev.Model{
+			"tool-model": {ToolCall: true},
+		}},
+	}})
+	cfg := Config{
+		ModelConfig:  latest.ModelConfig{Provider: "google", Model: "tool-model"},
+		ModelOptions: options.Apply(options.WithModelsDevStore(store)),
+	}
+
+	assert.Equal(t, modelinfo.ToolCallSupported, cfg.ToolCallSupport(t.Context()))
+}
+
 func TestConfigImageOutputEnabled(t *testing.T) {
 	t.Parallel()
 

pkg/model/provider/gemini/client.go

@@ -729,6 +729,17 @@ func stringifyEnumValues(values []any) []string {
 	return out
 }
 
+// wantsImageResponseModalities reports whether this ordinary chat request
+// should ask Gemini for TEXT+IMAGE output.
+func (c *Client) wantsImageResponseModalities(imageOutputEnabled bool) bool {
+	switch c.apiSurface {
+	case apiSurfaceGateway, apiSurfaceGeminiAPI, apiSurfaceVertexAI:
+	default:
+		return false
+	}
+	return imageOutputEnabled && !c.ModelOptions.GeneratingTitle() && !c.ModelOptions.Compacting()
+}
+
 // CreateChatCompletionStream creates a streaming chat completion request
 func (c *Client) CreateChatCompletionStream(
 	ctx context.Context,
@@ -740,9 +751,15 @@ func (c *Client) CreateChatCompletionStream(
 	}
 
 	config := c.buildConfig()
+	imageOutputEnabled := c.ImageOutputEnabled(ctx)
+
+	if c.wantsImageResponseModalities(imageOutputEnabled) {
+		config.ResponseModalities = []string{string(genai.ModalityText), string(genai.ModalityImage)}
+	}
 
 	// Start with Google built-in tools (search, maps, code execution) from provider_opts
-	config.Tools = c.builtInTools()
+	builtInTools := c.builtInTools()
+	config.Tools = builtInTools
 
 	// Add tools to config if provided
 	if len(requestTools) > 0 {
@@ -767,7 +784,11 @@ func (c *Client) CreateChatCompletionStream(
 		}
 	}
 
-	shape := newRequestShape(c, config, len(requestTools))
+	if err := c.checkImageOutputRequestCompatibility(ctx, imageOutputEnabled, config, builtInTools, len(requestTools)); err != nil {
+		return nil, err
+	}
+
+	shape := newRequestShape(c, config, len(requestTools), imageOutputEnabled)
 	slog.DebugContext(ctx, "Gemini request shape", shape.LogAttrs()...)
 
 	contents := convertMessagesToGemini(ctx, messages, c.ID(), c.ModelOptions.ModelsDevStore(), c.CapsOverride())

pkg/model/provider/gemini/diagnostics.go

@@ -58,20 +58,16 @@ type RequestShape struct {
 	// 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 records whether the capability was resolved from an
+	// explicit configuration override instead of the catalogue.
 	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 {
+func newRequestShape(c *Client, config *genai.GenerateContentConfig, functionToolCount int, imageOutputEnabled bool) RequestShape {
 	modalities := normalizeResponseModalities(config.ResponseModalities)
 	kinds := builtInToolKinds(config.Tools)
 
@@ -86,6 +82,8 @@ func newRequestShape(c *Client, config *genai.GenerateContentConfig, functionToo
 		ThinkingConfigSet:       config.ThinkingConfig != nil,
 		NoThinkingRequested:     c.ModelOptions.NoThinking(),
 		APISurface:              c.apiSurface,
+		OutputCapabilityKnown:   c.ModelConfig.OutputCapabilities != nil && c.ModelConfig.OutputCapabilities.Image != nil,
+		OutputCapabilityEnabled: imageOutputEnabled,
 	}
 
 	if config.ToolConfig != nil {

pkg/model/provider/gemini/diagnostics_test.go

@@ -40,7 +40,7 @@ func TestNewRequestShape_Minimal(t *testing.T) {
 	config := client.buildConfig()
 	config.Tools = client.builtInTools()
 
-	shape := newRequestShape(client, config, 0)
+	shape := newRequestShape(client, config, 0, false)
 
 	assert.False(t, shape.ResponseModalitiesSet)
 	assert.Empty(t, shape.ResponseModalities)
@@ -52,9 +52,8 @@ func TestNewRequestShape_Minimal(t *testing.T) {
 	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)
+	// No output_capabilities declaration on this ModelConfig: diagnostics
+	// must report "unknown", never guess from the model ID.
 	assert.False(t, shape.OutputCapabilityEnabled)
 }
 
@@ -93,7 +92,7 @@ func TestNewRequestShape_ToolsAndBuiltIns(t *testing.T) {
 		config.ToolConfig.IncludeServerSideToolInvocations = new(true)
 	}
 
-	shape := newRequestShape(client, config, len(requestTools))
+	shape := newRequestShape(client, config, len(requestTools), false)
 
 	assert.Equal(t, 2, shape.BuiltInToolCount)
 	assert.ElementsMatch(t, []string{"google_search", "google_maps"}, shape.BuiltInToolKinds)
@@ -114,7 +113,7 @@ func TestNewRequestShape_ResponseModalitiesNormalized(t *testing.T) {
 	config := client.buildConfig()
 	config.ResponseModalities = []string{" text ", "IMAGE", "text", ""}
 
-	shape := newRequestShape(client, config, 0)
+	shape := newRequestShape(client, config, 0, false)
 
 	assert.True(t, shape.ResponseModalitiesSet)
 	assert.Equal(t, []string{"TEXT", "IMAGE"}, shape.ResponseModalities)
@@ -135,7 +134,7 @@ func TestNewRequestShape_NoThinkingRequested(t *testing.T) {
 	}
 	config := client.buildConfig()
 
-	shape := newRequestShape(client, config, 0)
+	shape := newRequestShape(client, config, 0, false)
 
 	assert.True(t, shape.ThinkingConfigSet)
 	assert.True(t, shape.NoThinkingRequested)
@@ -156,7 +155,7 @@ func TestNewRequestShape_StructuredOutputPresent(t *testing.T) {
 	}
 	config := client.buildConfig()
 
-	shape := newRequestShape(client, config, 0)
+	shape := newRequestShape(client, config, 0, false)
 
 	require.True(t, shape.StructuredOutputPresent)
 
@@ -168,6 +167,46 @@ func TestNewRequestShape_StructuredOutputPresent(t *testing.T) {
 	}
 }
 
+// TestNewRequestShape_OutputCapabilityUsesResolvedValue pins that diagnostics
+// distinguish an explicit override while reporting the resolved capability.
+func TestNewRequestShape_OutputCapabilityUsesResolvedValue(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name               string
+		outputCapabilities *latest.OutputCapabilitiesConfig
+		resolvedEnabled    bool
+		wantKnown          bool
+		wantEnabled        bool
+	}{
+		{name: "catalogue enabled", outputCapabilities: nil, resolvedEnabled: true, wantKnown: false, wantEnabled: true},
+		{name: "declared false", outputCapabilities: &latest.OutputCapabilitiesConfig{Image: new(false)}, wantKnown: true, wantEnabled: false},
+		{name: "declared true", outputCapabilities: &latest.OutputCapabilitiesConfig{Image: new(true)}, resolvedEnabled: true, wantKnown: true, wantEnabled: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			client := &Client{
+				Config: base.Config{
+					ModelConfig: latest.ModelConfig{
+						Provider:           "google",
+						Model:              "gemini-2.5-flash-image",
+						OutputCapabilities: tt.outputCapabilities,
+					},
+				},
+				apiSurface: apiSurfaceGeminiAPI,
+			}
+			config := client.buildConfig()
+
+			shape := newRequestShape(client, config, 0, tt.resolvedEnabled)
+			assert.Equal(t, tt.wantKnown, shape.OutputCapabilityKnown)
+			assert.Equal(t, tt.wantEnabled, shape.OutputCapabilityEnabled)
+		})
+	}
+}
+
 // 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
@@ -189,7 +228,7 @@ func TestRequestShape_LogAttrsNeverLeaksToolSchemas(t *testing.T) {
 	require.NoError(t, err)
 	config.Tools = allTools
 
-	shape := newRequestShape(client, config, len(requestTools))
+	shape := newRequestShape(client, config, len(requestTools), false)
 
 	for _, attr := range flattenAttrs(shape.LogAttrs()) {
 		assert.NotContains(t, attr, marker, "RequestShape must never carry tool descriptions or schemas")

pkg/model/provider/gemini/image_output_guard.go

@@ -0,0 +1,86 @@
+package gemini
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"google.golang.org/genai"
+
+	"github.com/docker/docker-agent/pkg/modelinfo"
+)
+
+// imageOutputIncompatibility names a fixed, safe request-feature class
+// rejected by the image-output request guard. Values are display-safe:
+// never provider text, tool names, schema contents, or prompts.
+type imageOutputIncompatibility string
+
+const (
+	imageOutputIncompatibleTools            imageOutputIncompatibility = "tools"
+	imageOutputIncompatibleBuiltInTools     imageOutputIncompatibility = "built-in tools"
+	imageOutputIncompatibleStructuredOutput imageOutputIncompatibility = "structured output"
+)
+
+// ImageOutputRequestIncompatibleError is returned before any provider
+// dispatch when a request to an image-output-capable model
+// (output_capabilities.image: true) combines custom function tools (with
+// their required ToolConfig), a built-in tool, or structured output. The
+// request shape is intentionally unsupported until live direct Gemini API and
+// Vertex AI verification proves it is accepted there; gateway probing has
+// already shown opaque, empty-body HTTP 400 responses. Rejecting locally keeps
+// the verified minimal request byte-for-byte and gives the caller a specific,
+// actionable error instead.
+type ImageOutputRequestIncompatibleError struct {
+	// Incompatibilities is always non-empty. Its values are the fixed enum
+	// above — never provider text, tool names/schemas, or prompt content.
+	Incompatibilities []imageOutputIncompatibility
+	ToolCallSupport   modelinfo.ToolCallSupport
+}
+
+func (e *ImageOutputRequestIncompatibleError) Error() string {
+	if len(e.Incompatibilities) == 1 && e.Incompatibilities[0] == imageOutputIncompatibleTools {
+		switch e.ToolCallSupport {
+		case modelinfo.ToolCallUnsupported:
+			return "this model does not support tool calls; use a tool-capable model or remove tools from the request"
+		case modelinfo.ToolCallSupported:
+			return "this model supports tool calls, but not while image output is enabled; use a separate model or request for that combination"
+		}
+	}
+
+	names := make([]string, len(e.Incompatibilities))
+	for i, c := range e.Incompatibilities {
+		names[i] = string(c)
+	}
+	return fmt.Sprintf(
+		"this model is configured for image output (output_capabilities.image) and does not support %s in the same request; use a separate model or request for that combination",
+		strings.Join(names, ", "),
+	)
+}
+
+// checkImageOutputRequestCompatibility rejects, before any provider dispatch,
+// an incompatible request when image output is enabled by configuration or the
+// models.dev catalogue.
+func (c *Client) checkImageOutputRequestCompatibility(ctx context.Context, imageOutputEnabled bool, config *genai.GenerateContentConfig, builtInTools []*genai.Tool, requestTools int) error {
+	if !imageOutputEnabled {
+		return nil
+	}
+
+	var incompatibilities []imageOutputIncompatibility
+	if requestTools > 0 {
+		incompatibilities = append(incompatibilities, imageOutputIncompatibleTools)
+	}
+	if len(builtInTools) > 0 {
+		incompatibilities = append(incompatibilities, imageOutputIncompatibleBuiltInTools)
+	}
+	if config.ResponseMIMEType != "" || config.ResponseJsonSchema != nil {
+		incompatibilities = append(incompatibilities, imageOutputIncompatibleStructuredOutput)
+	}
+	if len(incompatibilities) == 0 {
+		return nil
+	}
+	incompatible := &ImageOutputRequestIncompatibleError{Incompatibilities: incompatibilities}
+	if len(incompatibilities) == 1 && incompatibilities[0] == imageOutputIncompatibleTools {
+		incompatible.ToolCallSupport = c.ToolCallSupport(ctx)
+	}
+	return incompatible
+}