RFI: Q0-3 Stop-reason state machine + max-tokens continuation

[gh-xj]

Summary

Track RFI for stop-reason/max-tokens continuation state machine (Q0-3).

Problem statement

Long responses can be truncated when provider stop reason is MaxTokens (or equivalent). The current loop does not consistently apply continuation behavior, causing silent truncation and degraded UX.

Scope

• Map stop reasons across active providers.
• Define continuation state machine and retry cap.
• Define behavior for partial tool-call JSON on truncation.
• Define observability/logging for continuation events.

Acceptance criteria

• Provider stop-reason mapping documented.
• Continuation policy and hard limits documented.
• Partial tool-call handling strategy documented.
• Proposed state machine approved for implementation.

References

• RFI doc: .docs/plans/rfi/partial/Q0-3-stop-reason-state-machine.md
• Linear: https://linear.app/zeroclawlabs/issue/RMN-257/rfi-q0-3-stop-reason-state-machine-max-tokens-continuation

[theonlyhennygod]

Implemented the Q0-3 RFI deliverable in PR #2316.\n\nWhat was added:\n- Unified stop-reason design () and extension proposal\n- Provider stop-reason mapping matrix (OpenAI/OpenRouter/compatible, Anthropic, Gemini, Bedrock)\n- Continuation state machine for truncation with bounded retry/budget limits\n- Partial tool-call JSON truncation policy (never execute partial payloads, controlled repair path)\n- Observability event/metric contract for continuation behavior\n- Verification strategy (mapping tests, FSM tests, integration and regression coverage)\n\nValidation run on changed docs:\n- \n- \n\nPR: #2316

[theonlyhennygod]

Correction update (previous comment had shell-escaping artifacts):

Implemented the Q0-3 RFI deliverable in PR #2316.

What was added:

• Unified stop-reason design (NormalizedStopReason) and ChatResponse extension proposal
• Provider stop-reason mapping matrix (OpenAI/OpenRouter/compatible, Anthropic, Gemini, Bedrock)
• Continuation state machine for MaxTokens truncation with bounded retry/budget limits
• Partial tool-call JSON truncation policy (never execute partial payloads, controlled repair path)
• Observability event and metric contract for continuation behavior
• Verification strategy (mapping tests, FSM tests, integration and regression coverage)

Validation run on changed docs:

• scripts/ci/docs_quality_gate.sh
• scripts/ci/docs_links_gate.sh

PR: #2316

[chumyin]

Functional follow-up has been implemented (not docs-only) and pushed to PR #2373 head: commit 255982e6.

Key hardening:

• Native truncated/malformed tool-call JSON is now fail-closed (no execution this turn).
• Mixed native-invalid + text-fallback payloads are blocked from fallback execution in the same turn.
• Controlled repair path preserved via parse-issue retry.
• Added targeted regression tests for truncated native JSON handling and fallback suppression.

PR details and validation evidence are posted in #2373 comments.