fix(runtime): prevent a step-capped turn from completing past a finish-hook veto #6221

What happened

When a turn has a finite maxSteps and the model's last step returns text, AiSdkTurn skips beforeTurnFinish and emits complete(end_turn). The run is recorded as completed, even if a finish hook (Bot Inbox/Sleep, proactive-matters settlement, plugin hooks) would have vetoed it.

Expected: a turn that a finish hook rejects never ends as a success. If no budget is left, it ends as step_limit.

Two latent defects have the same cause. No production caller triggers them today, because nothing passes mode: 'after_step':

• An after_step stop with maxSteps set ends as step_limit (failed / tool_step_cap_reached) after only 1 of 100 steps.
• An after_step stop that arrives during the veto handoffBoundary or the provider retry sleep still sends another provider request.

Why now: #6004 introduced the finish-hook bypass one week ago by copying the gating of neighboring branches, and open PRs #4138 and #5594 add more exits to the same section.

Root cause

After each step, the loop must answer three separate questions: is work left (demand), did a tool end the turn (yield), and may the turn continue (constraint). The code does not represent this decision as a value:

step settled
  │
  ├─ mayTakeAnotherStep = budget left && !stop        ← constraint computed first
  │
  ├─ tool calls  && may ─► handoff ─► recheck stop ─► continue
  ├─ prereq miss        ─► !may ? throw : handoff ─► recheck ─► continue
  ├─ steering    && may ─► handoff ─► recheck stop ─► continue
  ├─ text        && may ─► beforeTurnFinish ─veto─► handoff ─► continue    ✗ no recheck
  │      (!may ⇒ hook never runs)                                          ✗
  └─ break agentLoop        (carries no reason)
        │
        ▼
  stopReason = loopStopReason
            ?? (maxSteps !== undefined && finishReason === 'tool-calls')   ✗ "configured" ≠ "spent"
                 ? 'step_limit'
                 : mapFinishReason(finishReason)                           ✗ veto + text ⇒ end_turn

1. The constraint check decides whether the demand is evaluated at all (ai-sdk-turn.ts:2455). This causes the hook skip.
2. The terminal reason is inferred afterwards from proxies (ai-sdk-turn.ts:2608). External stops and tool yields share loopStopRequested/loopStopReason, and an after_step stop sets the flag without a reason (:667).
3. "Send no request after a stop" is copied onto four continue branches (:2369, :2401, :2442, :2469). It is not enforced at the single request seam, startStream (:1680). The retry sleep (:2156) and overflow recovery have no check.

Adding more rechecks or proxy conditions keeps this structure. Each new branch or await reopens the same class of defect.

Proposed direction

Replace only the step-boundary decision (:2336–2482) and the terminal derivation (:2608):

step settled ─► facts { yield?, demand?, constraint? }
                  (a finish candidate always consults beforeTurnFinish, whatever the budget)
                    │
                    ▼
             decideStep(facts)   ← pure, finite domain
          ┌─────────┼──────────────┐
  terminate(reason) continue      fail
                    │
            crossStepBoundary()   ← one copy, handles pause only
                    │
     startStream guard: stop latched? ─► terminate(user_stop)

• Separate StopRequest {mode, reason} from TurnYield {reason}.
• Emit complete with the decided reason. Delete the proxy inference.
• Leave out of scope: provider streaming, tool settlement, T1/T2, and the Host Run/Turn/Session layering.

Open questions: whether a missing loadTurnRuntimeEvents should count as a constraint instead of a reason to skip the hook, and whether the Bot beforeFinish writes stay correct when the hook also runs at the step cap.

How to reproduce

Use AiSdkBackend with a controlled model:

1. Set maxSteps: 1.
2. Make beforeTurnFinish always return { allow: false, feedback }.
3. Make the model return text with finishReason: 'stop'.

Result: 1 request, 0 hook calls, complete(end_turn), mapped to status=completed. With maxSteps 2 or 3, the hook runs only 1 or 2 times, and the turn still ends as end_turn.

This path is reachable through turn.start maxSteps, the CLI --max-steps flag, and continuation after a handoff. A full assistant-workflow E2E run was not done.

Environment

• Commit: dc4515cd6
• OS: macOS 26.3.1
• Surface: Runtime (packages/runtime)
• Node.js: v24.21.0

Additional context

Verification plan: a table test over all decideStep inputs, plus three AiSdkBackend wiring regressions (one per defect above) and the verify step-limit / stop / steering journeys.

Related: #3802 (provider finish-reason semantics, one layer below), #5594 (proactive-matters finish hook).

step settled
  │
  ├─ mayTakeAnotherStep = budget left && !stop        ← 先算约束
  │
  ├─ tool calls  && may ─► handoff ─► recheck stop ─► continue
  ├─ prereq miss        ─► !may ? throw : handoff ─► recheck ─► continue
  ├─ steering    && may ─► handoff ─► recheck stop ─► continue
  ├─ text        && may ─► beforeTurnFinish ─veto─► handoff ─► continue    ✗ 未重验
  │      (!may ⇒ 检查不运行)                                               ✗
  └─ break agentLoop        (不携带原因)
        │
        ▼
  stopReason = loopStopReason
            ?? (maxSteps !== undefined && finishReason === 'tool-calls')   ✗ 配置了 ≠ 用完了
                 ? 'step_limit'
                 : mapFinishReason(finishReason)                           ✗ 拒绝 + 文本 ⇒ end_turn

step settled ─► facts { yield?, demand?, constraint? }
                  (出现结束候选时总是调用 beforeTurnFinish，与预算无关)
                    │
                    ▼
             decideStep(facts)   ← 纯函数，有限域
          ┌─────────┼──────────────┐
  terminate(reason) continue      fail
                    │
            crossStepBoundary()   ← 只保留一份，只处理 pause
                    │
     startStream guard: stop latched? ─► terminate(user_stop)