Fix issue #2393: auto-enable model_fallback and expand retry patterns

[code-yeongyu]

Summary

• expand retryable model error detection to catch FreeUsageLimitError and broader free-tier or daily-limit messages
• auto-enable model_fallback when fallback_models are configured, while keeping explicit model_fallback: false as an override
• extract focused model-fallback hook helpers and add regression coverage for the new config behavior

Testing

• bun run typecheck
• bun run build
• bun test src/shared/model-error-classifier.test.ts src/plugin/hooks/model-fallback-config.test.ts src/plugin/event.model-fallback.test.ts
• bun test (currently fails on pre-existing expectations in src/plugin-config.test.ts about disabled_hooks; unrelated to this change)

---

Summary by cubic

Auto-enables model_fallback when fallback_models are configured and expands retryable error detection (including free-tier limits) to make provider fallback more reliable.

• Bug Fixes

  • Treat FreeUsageLimitError and free-tier/daily-limit messages as retryable; error name matching is now case-insensitive.
  • Automatically enable model_fallback when any agent/category defines fallback_models; explicit model_fallback: false still disables it.

• Refactors

  • Extracted config and session hook into model-fallback-config and create-model-fallback-session-hook, added focused tests, and simplified create-session-hooks.

^{Written for commit fd7faff. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 6 files

Confidence score: 3/5

• Potential mismatch with actual SDK behavior: src/shared/model-error-classifier.test.ts assumes error.name === "FreeUsageLimitError", but the SDK wraps limit errors as MessageV2.APIError, so the classifier/tests may be validating the wrong condition and could mis-handle real limit errors.
• Severity is high (8/10) and confidence is high, suggesting a concrete behavioral mismatch rather than a minor test tweak; this introduces some user-impacting risk if error classification is relied on.
• Pay close attention to src/shared/model-error-classifier.test.ts - ensure error name/type checks align with how the SDK surfaces limit errors.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/shared/model-error-classifier.test.ts">

<violation number="1" location="src/shared/model-error-classifier.test.ts:43">
P1: Custom agent: **Opencode Compatibility**

Opencode SDK never throws an error with `name: "FreeUsageLimitError"`. Backend limit errors are wrapped by the SDK into `MessageV2.APIError` instances (meaning `error.name` is always `"APIError"`), and the `FreeUsageLimitError` identifier is only present in the `responseBody` or `message`. Testing for `name: "FreeUsageLimitError"` indicates an invalid approach to catching Opencode limit errors, as it won't match the actual errors emitted by the SDK.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: Custom agent: Opencode Compatibility

Opencode SDK never throws an error with name: "FreeUsageLimitError". Backend limit errors are wrapped by the SDK into MessageV2.APIError instances (meaning error.name is always "APIError"), and the FreeUsageLimitError identifier is only present in the responseBody or message. Testing for name: "FreeUsageLimitError" indicates an invalid approach to catching Opencode limit errors, as it won't match the actual errors emitted by the SDK.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/shared/model-error-classifier.test.ts, line 43:

<comment>Opencode SDK never throws an error with `name: "FreeUsageLimitError"`. Backend limit errors are wrapped by the SDK into `MessageV2.APIError` instances (meaning `error.name` is always `"APIError"`), and the `FreeUsageLimitError` identifier is only present in the `responseBody` or `message`. Testing for `name: "FreeUsageLimitError"` indicates an invalid approach to catching Opencode limit errors, as it won't match the actual errors emitted by the SDK.</comment>

<file context>
@@ -40,6 +40,28 @@ describe("model-error-classifier", () => {
     expect(result).toBe(true)
   })
 
+  test("treats FreeUsageLimitError names as retryable", () => {
+    //#given
+    const error = { name: "FreeUsageLimitError" }
</file context>

[code-yeongyu]

Duplicate of #2422 which already passes CI