fix(claude): report usage limits on retried turns

[StiensWout]

What Changed

Claude turns retried while still limited now report "Claude usage limit reached" instead of "Claude gave up after repeated API errors", even when the CLI sends no new rate_limit_event.

Closes #10544. Alternative to #10546, with assistant-error evidence replaced when a later parent response arrives.

Why

The retry still carries structured assistant.error: "rate_limit". Record whether the latest top-level assistant message reports that error and use the existing result fallback. This fixes every client through the adapter without parsing the CLI's text or changing contracts.

Keep this evidence separate from rejectedRateLimitTypes: the assistant error supplies no window identity, while that set tracks individual windows and their recovery. Replace the assistant flag on each parent response rather than latching it for the entire turn, so a later normal response or different error cannot leave an obsolete usage-limit hint. Subagent messages neither set nor clear the parent flag. Both normal and synthetic turns start with fresh state.

The existing result handling still owns error precedence, including explicit errors, overloads, and interruption.

Verification

• Claude adapter suite: 126 tests pass, including nine new cases for assistant-only limits, repeated turns, later recovery/errors, subagent isolation, and error precedence. Result fixtures use the report's is_error: true.
• Running the six new classification/retry cases against the unfixed adapter fails the three expected positive cases.
• Server typecheck passes, with existing Effect suggestions only. Targeted lint, formatting, and git diff --check pass.

Implemented with GPT-6 in the Codex harness through T3 Code.

Note

Report usage-limit message on retried Claude turns with assistant rate-limit evidence

• Adds per-turn tracking of assistant rate-limit evidence in ClaudeTurnState so a terminal API failure can be classified as a usage-limit error when the current turn saw a rate-limit response.
• Resets the assistant-rate-limit flag at the start of each new Claude turn so evidence from a prior turn does not carry over.
• The result finalizer in makeClaudeAdapter now includes assistant rate-limit state alongside the existing rejected rate-limit event state when building the usage-limit fallback message.
• Adds parameterized tests covering consecutive usage-limit failures, terminal failures without new rate-limit evidence, and scenarios where more specific outcomes (overload, tool error, interrupt) take precedence.
• Risk: the result finalizer in apps/server/src/provider/Layers/ClaudeAdapter.ts changes which message a failed turn reports; turns that previously got a generic repeated-API-error message may now report a usage-limit message when assistant rate-limit evidence is present.

^{Macroscope summarized af3a725.}

Summary by CodeRabbit

• Bug Fixes
  • Improved Claude error messaging when assistant responses indicate rate limits.
  • Correctly distinguishes usage-limit messages from generic API errors across parent and subagent responses.
  • Prevented rate-limit details from incorrectly carrying over into later turns.
  • Improved handling of repeated rate limits and related terminal failures.

[macroscopeapp]

Approvability

Verdict: Approved at af3a725

Macroscope's review found this PR approvable — This is a focused Claude adapter bug fix that reports usage-limit failures correctly on retried turns while preserving existing error precedence and resetting evidence between turns. The production change is localized, has targeted test coverage, and introduces no schema, configuration, deployment, or sensitive-data impact.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 2b3f7391-fddc-4be1-ba9d-a1022da1b03c

📥 Commits

Reviewing files that changed from the base of the PR and between 1d1bf50 and af3a725.

📒 Files selected for processing (2)

• apps/server/src/provider/Layers/ClaudeAdapter.test.ts
• apps/server/src/provider/Layers/ClaudeAdapter.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The Claude adapter now records assistant rate-limit errors and uses them to classify terminal API failures. Tests cover single-turn, repeated-turn, subagent, overload, tool-error, and interrupt cases.

Changes

Claude rate-limit classification

Layer / File(s)	Summary
Track assistant rate-limit state apps/server/src/provider/Layers/ClaudeAdapter.ts	ClaudeTurnState stores whether the latest assistant message has error === "rate_limit". The state initializes for synthetic and regular turns and updates when assistant messages arrive.
Classify terminal failures apps/server/src/provider/Layers/ClaudeAdapter.ts, apps/server/src/provider/Layers/ClaudeAdapter.test.ts	Terminal results use assistant rate-limit state when selecting the Claude usage-limit message. Tests cover repeated turns, subagent responses, terminal errors, interrupts, and emitted assistant-rate-limit evidence.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to af3a7

Claude retries that retain a usage-limit error now report the usage-limit message rather than a generic repeated API failure, while normal recovery and higher-priority terminal errors retain their existing behavior. No current merge-blocking risk remains.

Suggested reviewers: juliusmarminge, t3dotgg

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the fix for usage-limit reporting on retried Claude turns.
Description check	✅ Passed	The description explains what changed, why it changed, verification results, and scope. The repository checklist section is omitted, but the description is otherwise complete and focused.
Linked Issues check	✅ Passed	The implementation directly addresses issue [#10544] by tracking assistant rate-limit evidence across retries, refreshing it per parent response, isolating subagent messages, and preserving error prec…
Out of Scope Changes check	✅ Passed	The changes are limited to Claude adapter state handling and related tests. They directly support the linked issue and stated objectives, with no unrelated code changes identified.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}