feat: avoid forced tool choice for structured output when unsupported - #28621

Issue for this PR

None

What does this PR do?

This fixes SDK structured response support for DeepSeek v4 reasoning models. Those models do not support forcing tool calls with tool_choice: "required".

Previously, OpenCode always used forced tool calling for JSON schema output. That worked for many models, but DeepSeek reasoning models reject this parameter with an error like:

deepseek-reasoner does not support this tool_choice

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

Open Question

Since we changed the semantics from required to auto, should we detect and return an error when a structured response wasn't generated?

UPDATE: We already do

Naming tool_choice_required might be a bit confusing, however, if you read it as "capability" like tool_call, it could be fine.

What Changed

• Added a new model capability: tool_choice_required.
• Kept tool_call separate from forced tool choice support.
• Updated structured output logic:
  • Use toolChoice: "required" when the model supports forced tool choice.
  • Use toolChoice: "auto" when tool_choice_required: false.
  • Added config support so users can override model metadata.
  • Added models.dev schema support for tool_choice_required.
  • Added SDK types for tool_choice_required.
  • Added tests proving tools are still sent while forced tool choice is avoided.

Why

Some models have this capability shape:

{
  "tool_call": true,
  "tool_choice_required": false
}

That means:

• The model supports tools.
• The model can choose to call a tool.
• The model does not support being forced to call a tool.

Structured output uses a StructuredOutput tool. For these models, we now send the tool but use tool_choice: "auto" instead of tool_choice: "required".

Example

This SDK script proves the fix by using DeepSeek V4 Flash Free / Pro with JSON schema output:

import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode({
  port: 14096,
  config: {
    model: "opencode/deepseek-v4-flash-free",
    provider: {
      opencode: {
        models: {
          "deepseek-v4-flash-free": {
            tool_call: true,
            tool_choice_required: false, // Toggle to make it fail
          },
        },
      },
    },
  },
})
const session = await client.session.create({
  body: { title: "Test 1" },
})
const result = await client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Say hello in one sentence." }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          answer: { type: "string" },
        },
        required: ["answer"],
      },
    },
  },
})
console.log(JSON.stringify(result.data, null, 2))

Before this fix, the request could fail because OpenCode forced:
tool_choice: "required"

After this fix, the request uses:
tool_choice: "auto"

while still sending the StructuredOutput tool.

Before release

The models.dev metadata must be updated for affected DeepSeek reasoning models:

{
  "tool_call": true,
  "tool_choice_required": false
}

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

If you do not follow this template your PR will be automatically rejected.