fix(agent): relax forced toolChoice to auto on follow-up turns (DEV-785)

.changeset/warm-lions-drum.md

@@ -0,0 +1,19 @@
+---
+'@openrouter/agent': patch
+---
+
+Relax an unchanged forced `toolChoice` (`required`, a specific tool, or `allowed_tools` with `mode: 'required'`) to `auto` after it produces a tool call, including follow-ups resumed after approval, HITL, client-tool, or async-tool pauses. Dynamically resolved choices re-arm when their semantic value changes. This lets the model synthesize a final text answer instead of being forced to call tools until the step budget runs out (DEV-785).
+
+```ts
+const result = callModel(client, {
+  model: 'openai/gpt-4o',
+  input: 'Plan, research, then submit.',
+  tools: [planTool, searchTool, submitTool] as const,
+  toolChoice: ({ numberOfTurns }) =>
+    numberOfTurns === 0
+      ? { type: 'function', name: 'plan' }
+      : numberOfTurns === 3
+        ? { type: 'function', name: 'submit' }
+        : 'auto',
+});
+```

packages/agent/README.md

@@ -157,6 +157,26 @@ const confirmTool = tool({
 });
 ```
 
+**Forced tool choices** are one-shot for each resolved semantic value. After a
+forced choice produces a tool call, unchanged follow-up choices are relaxed to
+`auto` so the model can either call another tool or answer in text. A dynamic
+choice re-arms when it resolves to a different value (or after an unforced
+turn):
+
+```typescript
+callModel(client, {
+  model: 'openai/gpt-4o',
+  input: 'Plan, research, then submit.',
+  tools: [planTool, searchTool, submitTool] as const,
+  toolChoice: ({ numberOfTurns }) =>
+    numberOfTurns === 0
+      ? { type: 'function', name: 'plan' }
+      : numberOfTurns === 3
+        ? { type: 'function', name: 'submit' }
+        : 'auto',
+});
+```
+
 ### Stop Conditions
 
 Control when the agent loop stops executing tools: