fix(agent): default final-answer directive for bare allowFinalResponse: true (DEV-658)

[LukasParke]

Fixes DEV-658

Problem

When stopWhen halted the loop mid-tool-call, the forced final turn stripped tools/toolChoice/parallelToolCalls and appended no signal that this was the model's last turn. Two defects:

1. Leak (DEV-658): models that emit tool-call syntax as text (GLM) attempt another tool call, which leaks into content as unparsed <tool_call>… text and gets treated as the final answer. Router PR #29461 worked around it by passing a directive string; every consumer using bare true was still exposed.
2. Cache bust (review feedback): stripping the tools block invalidated the prompt-cache prefix on the final request.

Additionally, the final turn was opt-in — the common failure mode (run ends on a half-finished tool call) was the default.

Change

• Final turn is on by default. allowFinalResponse: false opts out; omitted/true behave identically.
• Tools are kept; calling is forbidden via toolChoice: 'none' — preserves the prompt-cache prefix. Same on the empty-final retry path (retryCurrentRequest).
• Default directive: omitted/true appends DEFAULT_FINAL_RESPONSE_DIRECTIVE (exported) as the final user message; a non-empty string overrides the wording; '' appends nothing.

JSDoc, README, and changeset updated. Changeset bumped to minor: runs that previously ended on a halted tool-call turn now make one additional model request by default.

API example

import { callModel, stepCountIs, DEFAULT_FINAL_RESPONSE_DIRECTIVE } from '@openrouter/agent';

const result = callModel(client, {
  model: 'z-ai/glm-5.2',
  input: 'Research this step by step.',
  tools: [searchTool],
  stopWhen: stepCountIs(3),
  // was: no final turn unless allowFinalResponse was set; bare `true`
  //      stripped tools (cache-busting) and appended no directive, so
  //      GLM-style models could leak raw `<tool_call>…` as the answer
  // now: default-on final turn with toolChoice:'none' (tools kept, cache
  //      preserved) + DEFAULT_FINAL_RESPONSE_DIRECTIVE user message

  // custom wording still overrides the default:
  // allowFinalResponse: 'Summarize what you found.',
  // append no message (turn still happens):
  // allowFinalResponse: '',
  // restore the old opt-out (no final turn):
  // allowFinalResponse: false,
});

Tests

Unit (allow-final-response.test.ts, tool-terminal-empty-final.test.ts): final request keeps tools and forces toolChoice: 'none' (overriding the caller's 'required'); default-on path (option omitted) makes the final turn with the directive; string override, '', and false contracts pinned; retry path asserts tools kept + toolChoice: 'none'.

e2e regression (call-model.test.ts): DEV-658 repro shape — z-ai/glm-5.2, a web_search tool returning deliberately unhelpful results, stopWhen: stepCountIs(1), option omitted (default path under test). Asserts non-empty final text, no leaked tool-call syntax, zero structured function_call items.

Discrimination check (probed live before writing the test): legacy no-directive path leaked 3/3 runs; with the directive 0/3.

Verification

• Unit: 521/521, typecheck clean, biome clean
• e2e: full allowFinalResponse block passes against the live API (4/4, incl. GLM regression on the default path)
• CI e2e job verified actually running after provisioning the OPENROUTER_API_KEY repo secret (was previously skip-passing)

Maintenance

Adds .agents/skills/public-api-examples/SKILL.md: public-API-changing PRs must carry a consumer-perspective code example in the PR description and changeset.

Follow-up (not this PR)

• DEV-660: drop the router-level SERVER_TOOLS_FINAL_RESPONSE_DIRECTIVE workaround once this ships
• Python/Go ports carry the same deficiencies (model_result.py _build_final_request, model_result.go sendFinalResponseRequest) — same fix shape applies

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[mattapperson]

allowFinalResponse should not strip tools it should just set tool_choice: 'none',. removing the tools busts cache.

allowFinalResponse: true should be the default.

[LukasParke]

Added .agents/skills/public-api-examples/SKILL.md codifying this: any PR changing the public API must include a consumer-perspective code example in the PR description and in its changeset (so it lands in CHANGELOG.md for npm consumers). This PR now complies — see the "API example" section above and the updated changeset.

[LukasParke]

Both addressed in a1df1c6:

toolChoice: 'none' instead of stripping — the final turn (and the empty-final retry path) now keeps the full tools block and forces toolChoice: 'none', so the prompt-cache prefix stays intact. Unit tests assert tools are present and toolChoice === 'none' on both paths, including overriding a caller's toolChoice: 'required'.

Default-on — allowFinalResponse now defaults to on: omitted/true append DEFAULT_FINAL_RESPONSE_DIRECTIVE, a non-empty string overrides the wording, '' appends nothing, false opts out entirely. The e2e GLM regression test now exercises the default path (option omitted).

Changeset bumped to minor since runs that previously ended on a halted tool-call turn now make one extra request by default — allowFinalResponse: false restores the old behavior. Full suite: unit 521/521, e2e allowFinalResponse block 4/4 live.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

📝 Info: Default-on final turn adds an extra model request for existing stopWhen users

finalResponseEnabled = allowFinalResponse !== false (packages/agent/src/lib/model-result.ts:3211) makes the forced final turn happen by default whenever stopWhen halts mid-executable-tool-call. This is explicitly called out in the PR/changeset as an intentional minor bump, but it is worth confirming that no in-repo stateful/resume flows depend on the old behavior of ending on the halted tool-call turn. I checked the mcp package and found no stopWhen/allowFinalResponse usage, and the all-manual-tool-call path is still gated by hasExecutableToolCalls, so only executable-tool halts are affected.

---

Was this helpful? React with 👍 or 👎 to provide feedback.