From 2c4d1f79e2a09299e7d56663cef0ea54e25926d0 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Sat, 19 Sep 2026 01:15:11 -0700
Subject: [PATCH] fix: document the reasoning-only stall failover under
 Fallback Model

Configured fallback_providers now also engage on a Codex reasoning-only stall
(incomplete_response) with one bounded grace call; the developer guide listed only the
429/5xx/401/403 triggers.
---
 website/docs/developer-guide/agent-loop.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/website/docs/developer-guide/agent-loop.md b/website/docs/developer-guide/agent-loop.md
index a381ea2b9d..17bc53ea47 100644
--- a/website/docs/developer-guide/agent-loop.md
+++ b/website/docs/developer-guide/agent-loop.md
@@ -193,6 +193,7 @@ When the primary model fails (429 rate limit, 5xx server error, 401/403 auth err
 2. Try each fallback in order
 3. On success, continue the conversation with the new provider
 4. On 401/403, attempt credential refresh before failing over
+5. A Codex Responses turn that stalls on reasoning-only output (three consecutive continuations with no visible text or tool call) also fails over to the next fallback with reason `incomplete_response`; if the stall consumed the iteration budget, the fallback gets exactly one bounded grace call
 
 The fallback system also covers auxiliary tasks independently — vision, compression, and web extraction each have their own fallback chain configurable via the `auxiliary.*` config section.