pass through additional agent options to the provider

3 files changed, 42 insertions, 7 deletions

diff --git a/packages/opencode/src/agent/agent.ts b/packages/opencode/src/agent/agent.ts
index ede8fbf7e..b363e0e9b 100644
--- a/packages/opencode/src/agent/agent.ts
+++ b/packages/opencode/src/agent/agent.ts
@@ -14,7 +14,6 @@ export namespace Agent {
       mode: z.union([z.literal("subagent"), z.literal("primary"), z.literal("all")]),
       topP: z.number().optional(),
       temperature: z.number().optional(),
-      options: z.record(z.any()),
       model: z
         .object({
           modelID: z.string(),
@@ -23,6 +22,7 @@ export namespace Agent {
         .optional(),
       prompt: z.string().optional(),
       tools: z.record(z.boolean()),
+      options: z.record(z.string(), z.any()),
     })
     .openapi({
       ref: "Agent",
@@ -73,6 +73,11 @@ export namespace Agent {
           options: {},
           tools: {},
         }
+      const { model, prompt, tools, description, temperature, top_p, mode, ...extra } = value
+      item.options = {
+        ...item.options,
+        ...extra,
+      }
       if (value.model) item.model = Provider.parseModel(value.model)
       if (value.prompt) item.prompt = value.prompt
       if (value.tools)
@@ -84,11 +89,6 @@ export namespace Agent {
       if (value.temperature != undefined) item.temperature = value.temperature
       if (value.top_p != undefined) item.topP = value.top_p
       if (value.mode) item.mode = value.mode
-      if (value.options)
-        item.options = {
-          ...item.options,
-          ...value.options,
-        }
     }
     return result
   })
diff --git a/packages/opencode/src/config/config.ts b/packages/opencode/src/config/config.ts
index 96a662b29..62f425cb5 100644
--- a/packages/opencode/src/config/config.ts
+++ b/packages/opencode/src/config/config.ts
@@ -173,9 +173,9 @@ export namespace Config {
       tools: z.record(z.string(), z.boolean()).optional(),
       disable: z.boolean().optional(),
       description: z.string().optional().describe("Description of when to use the agent"),
-      options: z.record(z.string(), z.any()).optional().describe("Additional model options passed through to provider"),
       mode: z.union([z.literal("subagent"), z.literal("primary"), z.literal("all")]).optional(),
     })
+    .catchall(z.any())
     .openapi({
       ref: "AgentConfig",
     })
diff --git a/packages/web/src/content/docs/docs/agents.mdx b/packages/web/src/content/docs/docs/agents.mdx
index 659c8ee5f..52bb8ed14 100644
--- a/packages/web/src/content/docs/docs/agents.mdx
+++ b/packages/web/src/content/docs/docs/agents.mdx
@@ -360,6 +360,41 @@ The `mode` option can be set to `primary`, `subagent`, or `all`. If no `mode` is
 
 ---
 
+### Additional options
+
+Any other options you specify in your agent configuration will be passed through directly to the provider as model options. This allows you to use provider-specific features and parameters.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "reasoning": {
+      "model": "openai/gpt-5-turbo",
+      "reasoningEffort": "high",
+      "textVerbosity": "medium"
+    }
+  }
+}
+```
+
+For example, with OpenAI's reasoning models, you can control the reasoning effort:
+
+```json title="opencode.json"
+{
+  "agent": {
+    "deep-thinker": {
+      "description": "Agent that uses high reasoning effort for complex problems",
+      "model": "openai/gpt-5-turbo", 
+      "reasoningEffort": "high",
+      "textVerbosity": "low"
+    }
+  }
+}
+```
+
+These additional options are model and provider-specific. Check your provider's documentation for available parameters.
+
+---
+
 ## Create agents
 
 You can create new agents using the following command: