docs(agents): document reasoningOptions effort + examples; note OpenRouter-style reasoning tokens

Explain Reasoning Options in Agent Reference and show usage in Customizing Agents, aligned with OpenRouter’s “max tokens for reasoning.” Mirrors base-lite usage.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

bun.lock

@@ -66,6 +66,36 @@ The model to use, which can be any model string from [Openrouter](https://openro
 "model": "anthropic/claude-4-sonnet-20250522"
 ```
 
+#### Reasoning Options (`reasoningOptions`, object, optional)
+
+Controls model reasoning behavior using OpenRouter-style settings.
+
+Fields:
+
+- `enabled` (boolean, default: false) — Turn reasoning mode on for supported models.
+- `exclude` (boolean, default: false) — If true, omit model-revealed reasoning content from responses (when available), returning only the final answer.
+- `effort` ("low" | "medium" | "high") — Increase or decrease how much the model "thinks" before answering. Higher effort typically improves quality for hard tasks at the cost of more reasoning tokens.
+
+Notes:
+
+- Patterned after OpenRouter's "max tokens for reasoning." Higher effort maps to a higher internal reasoning token budget. See OpenRouter docs for background.
+- Only supported by models that expose reasoning features. When unsupported, these options are ignored.
+
+Example:
+
+```ts
+// .agents/thinker.ts
+const definition = {
+  id: 'thinker',
+  // ... other fields ...
+  reasoningOptions: {
+    enabled: true,
+    exclude: false,
+    effort: 'high',
+  },
+}
+```
+
 ### Behavior Configuration
 
 #### `outputMode` (string, optional, default: "last_message")

web/src/content/agents/agent-reference.mdx

@@ -25,6 +25,25 @@ Keep in mind you'll get the most value from agents if you treat them as context
 
 **Tip:** Use specialty reviewers as spawnable subagents that your context-manager agent calls at the right time in the workflow.
 
+### Reasoning Options (optional)
+
+For models that support it, you can enable and tune reasoning directly on your agent:
+
+```ts
+const definition = {
+  id: 'reviewer',
+  // ... other fields ...
+  reasoningOptions: {
+    enabled: true,      // turn on reasoning if supported
+    exclude: false,     // include reasoning traces when available
+    effort: 'medium',   // low | medium | high
+  },
+}
+```
+
+- Effort roughly corresponds to a larger internal "max tokens for reasoning."
+- If the selected model doesn't support reasoning, these options are safely ignored.
+
 ## Example: Security Coordinator Agent
 
 Create a specialized agent for security-focused workflows: