fix: resolve post-rebase runtime fallback merge leftovers

fix(test): correct browserProvider assertion to match actual behavior
When browserProvider is not set, agent-browser skill should NOT resolve. Test assertions were inverted — expected 'Skills not found' but asserted the opposite.
2026-02-21 02:45:48 +09:00 · 2026-02-21 02:42:20 +09:00 · 2026-02-21 02:42:20 +09:00 · 2026-02-21 02:42:20 +09:00 · 2026-02-21 02:42:20 +09:00 · 2026-02-21 02:42:12 +09:00
45 changed files with 4720 additions and 683 deletions
--- a/assets/oh-my-opencode.schema.json
+++ b/assets/oh-my-opencode.schema.json
@@ -100,6 +100,7 @@
          "task-resume-info",
          "stop-continuation-guard",
          "tasks-todowrite-disabler",
+          "runtime-fallback",
          "write-existing-file-guard",
          "anthropic-effort",
          "hashline-read-enhancer",
@@ -140,6 +141,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -325,6 +339,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -510,6 +537,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -695,6 +735,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -880,6 +933,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -1065,6 +1131,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -1250,6 +1329,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -1435,6 +1527,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -1620,6 +1725,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -1805,6 +1923,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -1990,6 +2121,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -2175,6 +2319,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -2360,6 +2517,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -2545,6 +2715,19 @@
            "model": {
              "type": "string"
            },
+            "fallback_models": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
            "variant": {
              "type": "string"
            },
@@ -2738,6 +2921,19 @@
          "model": {
            "type": "string"
          },
+          "fallback_models": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            ]
+          },
          "variant": {
            "type": "string"
          },
@@ -3147,6 +3343,37 @@
      ],
      "additionalProperties": false
    },
+    "runtime_fallback": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "retry_on_errors": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          }
+        },
+        "max_fallback_attempts": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 20
+        },
+        "cooldown_seconds": {
+          "type": "number",
+          "minimum": 0
+        },
+        "timeout_seconds": {
+          "type": "number",
+          "minimum": 0
+        },
+        "notify_on_fallback": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
    "background_task": {
      "type": "object",
      "properties": {
--- a/docs/configurations.md
+++ b/docs/configurations.md
@@ -163,19 +163,20 @@ Override built-in agent settings:
 }
 ```

-Each agent supports: `model`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`, `category`, `variant`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `providerOptions`.
+Each agent supports: `model`, `fallback_models`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`, `category`, `variant`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `providerOptions`.

 ### Additional Agent Options

-| Option              | Type    | Description                                                                                     |
-| ------------------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `category`          | string  | Category name to inherit model and other settings from category defaults                             |
-| `variant`           | string  | Model variant (e.g., `max`, `high`, `medium`, `low`, `xhigh`)                                 |
-| `maxTokens`         | number  | Maximum tokens for response. Passed directly to OpenCode SDK.                                      |
-| `thinking`          | object  | Extended thinking configuration for Anthropic models. See [Thinking Options](#thinking-options) below. |
-| `reasoningEffort`   | string  | OpenAI reasoning effort level. Values: `low`, `medium`, `high`, `xhigh`.                         |
-| `textVerbosity`      | string  | Text verbosity level. Values: `low`, `medium`, `high`.                                        |
-| `providerOptions`    | object  | Provider-specific options passed directly to OpenCode SDK.                                      |
+| Option              | Type           | Description                                                                                     |
+| ------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
+| `fallback_models`   | string/array   | Fallback models for runtime switching on API errors. Single string or array of model strings.  |
+| `category`          | string         | Category name to inherit model and other settings from category defaults                        |
+| `variant`           | string         | Model variant (e.g., `max`, `high`, `medium`, `low`, `xhigh`)                                   |
+| `maxTokens`         | number         | Maximum tokens for response. Passed directly to OpenCode SDK.                                   |
+| `thinking`          | object         | Extended thinking configuration for Anthropic models. See [Thinking Options](#thinking-options) below. |
+| `reasoningEffort`   | string         | OpenAI reasoning effort level. Values: `low`, `medium`, `high`, `xhigh`.                        |
+| `textVerbosity`     | string         | Text verbosity level. Values: `low`, `medium`, `high`.                                          |
+| `providerOptions`   | object         | Provider-specific options passed directly to OpenCode SDK.                                      |

 #### Thinking Options (Anthropic)

@@ -714,6 +715,84 @@ Configure concurrency limits for background agent tasks. This controls how many
 - Allow more concurrent tasks for fast/cheap models (e.g., Gemini Flash)
 - Respect provider rate limits by setting provider-level caps

+## Runtime Fallback
+
+Automatically switch to backup models when the primary model encounters retryable API errors (rate limits, overload, etc.) or provider key misconfiguration errors (for example, missing API key). This keeps conversations running without manual intervention.
+
+```json
+{
+  "runtime_fallback": {
+    "enabled": true,
+    "retry_on_errors": [400, 429, 503, 529],
+    "max_fallback_attempts": 3,
+    "cooldown_seconds": 60,
+    "timeout_seconds": 30,
+    "notify_on_fallback": true
+  }
+}
+```
+
+| Option                  | Default                | Description                                                                 |
+| ----------------------- | ---------------------- | --------------------------------------------------------------------------- |
+| `enabled`               | `true`                 | Enable runtime fallback                                                     |
+| `retry_on_errors`       | `[400, 429, 503, 529]` | HTTP status codes that trigger fallback (rate limit, service unavailable). Also supports certain classified provider errors (for example, missing API key) that do not expose HTTP status codes.   |
+| `max_fallback_attempts` | `3`                    | Maximum fallback attempts per session (1-20)                                |
+| `cooldown_seconds`      | `60`                   | Cooldown in seconds before retrying a failed model                          |
+| `timeout_seconds`       | `30`                   | Timeout in seconds for an in-flight fallback request before forcing the next fallback model. **⚠️ Set to `0` to disable auto-retry signal detection** (see below). |
+| `notify_on_fallback`    | `true`                 | Show toast notification when switching to a fallback model                  |
+
+### timeout_seconds: Understanding the 0 Value
+
+**⚠️ IMPORTANT**: Setting `timeout_seconds: 0` **disables auto-retry signal detection**. This is a critical behavior change:
+
+| Setting | Behavior |
+|---------|----------|
+| `timeout_seconds: 30` (default) | ✅ **Full fallback coverage**: Error-based fallback (429, 503, etc.) + auto-retry signal detection (provider messages like "retrying in 8h") |
+| `timeout_seconds: 0` | ⚠️ **Limited fallback**: Only error-based fallback works. Provider retry messages are **completely ignored**. Timeout-based escalation is **disabled**. |
+
+**When `timeout_seconds: 0`:**
+- ✅ HTTP errors (429, 503, 529) still trigger fallback
+- ✅ Provider key errors (missing API key) still trigger fallback
+- ❌ Provider retry messages ("retrying in Xh") are **ignored**
+- ❌ Timeout-based escalation is **disabled**
+- ❌ Hanging requests do **not** advance to the next fallback model
+
+**Recommendation**: Use a non-zero value (e.g., `30` seconds) to enable full fallback coverage. Only set to `0` if you explicitly want to disable auto-retry signal detection.
+
+### How It Works
+
+1. When an API error matching `retry_on_errors` occurs (or a classified provider key error such as missing API key), the hook intercepts it
+2. The next request automatically uses the next available model from `fallback_models`
+3. Failed models enter a cooldown period before being retried
+4. If `timeout_seconds > 0` and a fallback provider hangs, timeout advances to the next fallback model
+5. Toast notification (optional) informs you of the model switch
+
+### Configuring Fallback Models
+
+Define `fallback_models` at the agent or category level:
+
+```json
+{
+  "agents": {
+    "sisyphus": {
+      "model": "anthropic/claude-opus-4-5",
+      "fallback_models": ["openai/gpt-5.2", "google/gemini-3-pro"]
+    }
+  },
+  "categories": {
+    "ultrabrain": {
+      "model": "openai/gpt-5.2-codex",
+      "fallback_models": ["anthropic/claude-opus-4-5", "google/gemini-3-pro"]
+    }
+  }
+}
+```
+
+When the primary model fails:
+1. First fallback: `openai/gpt-5.2`
+2. Second fallback: `google/gemini-3-pro`
+3. After `max_fallback_attempts`, returns to primary model
+
 ## Categories

 Categories enable domain-specific task delegation via the `task` tool. Each category applies runtime presets (model, temperature, prompt additions) when calling the `Sisyphus-Junior` agent.
@@ -830,15 +909,75 @@ Add your own categories or override built-in ones:
 }
 ```

-Each category supports: `model`, `temperature`, `top_p`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `tools`, `prompt_append`, `variant`, `description`, `is_unstable_agent`.
+Each category supports: `model`, `fallback_models`, `temperature`, `top_p`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `tools`, `prompt_append`, `variant`, `description`, `is_unstable_agent`.

 ### Additional Category Options

-| Option             | Type    | Default | Description                                                                                         |
-| ------------------ | ------- | ------- | --------------------------------------------------------------------------------------------------- |
-| `description`       | string  | -       | Human-readable description of the category's purpose. Shown in task prompt.                     |
-| `is_unstable_agent`| boolean | `false`  | Mark agent as unstable - forces background mode for monitoring. Auto-enabled for gemini models. |
+| Option              | Type         | Default | Description                                                                                         |
+| ------------------- | ------------ | ------- | --------------------------------------------------------------------------------------------------- |
+| `fallback_models`   | string/array | -       | Fallback models for runtime switching on API errors. Single string or array of model strings.      |
+| `description`       | string       | -       | Human-readable description of the category's purpose. Shown in delegate_task prompt.                |
+| `is_unstable_agent` | boolean      | `false` | Mark agent as unstable - forces background mode for monitoring. Auto-enabled for gemini models.    |

+## Runtime Fallback
+
+Automatically switch to backup models when the primary model encounters retryable API errors (rate limits, overload, etc.) or provider key misconfiguration errors (for example, missing API key). This keeps conversations running without manual intervention.
+
+```json
+{
+  "runtime_fallback": {
+    "enabled": true,
+    "retry_on_errors": [429, 503, 529],
+    "max_fallback_attempts": 3,
+    "cooldown_seconds": 60,
+    "timeout_seconds": 30,
+    "notify_on_fallback": true
+  }
+}
+```
+
+| Option                  | Default           | Description                                                                 |
+| ----------------------- | ----------------- | --------------------------------------------------------------------------- |
+| `enabled`               | `true`            | Enable runtime fallback                                                     |
+| `retry_on_errors`       | `[429, 503, 529]` | HTTP status codes that trigger fallback (rate limit, service unavailable). Also supports certain classified provider errors (for example, missing API key) that do not expose HTTP status codes.   |
+| `max_fallback_attempts` | `3`               | Maximum fallback attempts per session (1-10)                                |
+| `cooldown_seconds`      | `60`              | Cooldown in seconds before retrying a failed model                          |
+| `timeout_seconds`       | `30`              | Timeout in seconds for an in-flight fallback request before forcing the next fallback model. Set to `0` to disable timeout-based fallback and provider quota retry signal detection. |
+| `notify_on_fallback`    | `true`            | Show toast notification when switching to a fallback model                  |
+
+### How It Works
+
+1. When an API error matching `retry_on_errors` occurs (or a classified provider key error such as missing API key), the hook intercepts it
+2. The next request automatically uses the next available model from `fallback_models`
+3. Failed models enter a cooldown period before being retried
+4. If a fallback provider hangs, timeout advances to the next fallback model
+5. Toast notification (optional) informs you of the model switch
+
+### Configuring Fallback Models
+
+Define `fallback_models` at the agent or category level:
+
+```json
+{
+  "agents": {
+    "sisyphus": {
+      "model": "anthropic/claude-opus-4-5",
+      "fallback_models": ["openai/gpt-5.2", "google/gemini-3-pro"]
+    }
+  },
+  "categories": {
+    "ultrabrain": {
+      "model": "openai/gpt-5.2-codex",
+      "fallback_models": ["anthropic/claude-opus-4-5", "google/gemini-3-pro"]
+    }
+  }
+}
+```
+
+When the primary model fails:
+1. First fallback: `openai/gpt-5.2`
+2. Second fallback: `google/gemini-3-pro`
+3. After `max_fallback_attempts`, returns to primary model
 ## Model Resolution System

 At runtime, Oh My OpenCode uses a 3-step resolution process to determine which model to use for each agent and category. This happens dynamically based on your configuration and available models.
@@ -973,7 +1112,7 @@ Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-m
 }
 ```

-Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`, `auto-slash-command`, `sisyphus-junior-notepad`, `no-sisyphus-gpt`, `start-work`
+Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`, `auto-slash-command`, `sisyphus-junior-notepad`, `no-sisyphus-gpt`, `start-work`, `runtime-fallback`

 **Note on `directory-agents-injector`**: This hook is **automatically disabled** when running on OpenCode 1.1.37+ because OpenCode now has native support for dynamically resolving AGENTS.md files from subdirectories (PR #10678). This prevents duplicate AGENTS.md injection. For older OpenCode versions, the hook remains active to provide the same functionality.

--- a/docs/features.md
+++ b/docs/features.md
@@ -352,6 +352,7 @@ Hooks intercept and modify behavior at key points in the agent lifecycle.
 | **session-recovery** | Stop | Recovers from session errors - missing tool results, thinking block issues, empty messages. |
 | **anthropic-context-window-limit-recovery** | Stop | Handles Claude context window limits gracefully. |
 | **background-compaction** | Stop | Auto-compacts sessions hitting token limits. |
+| **runtime-fallback** | Event | Automatically switches to backup models on retryable API errors (e.g., 429, 503, 529), provider key misconfiguration errors (e.g., missing API key), and auto-retry signals (when `timeout_seconds > 0`). Configurable retry logic with per-model cooldown. See [Runtime Fallback Configuration](configurations.md#runtime-fallback) for details on `timeout_seconds` behavior. |

 #### Truncation & Context Management

--- a/issue-1501-analysis.md
+++ b/issue-1501-analysis.md
@@ -1,357 +0,0 @@
-# Issue #1501 분석 보고서: ULW Mode PLAN AGENT 무한루프
-
-## 📋 이슈 요약
-
-**증상:**
- ULW (ultrawork) mode에서 PLAN AGENT가 무한루프에 빠짐
- 분석/탐색 완료 후 plan만 계속 생성
- 1분마다 매우 작은 토큰으로 요청 발생
-
-**예상 동작:**
- 탐색 완료 후 solution document 생성
-
---
-
-## 🔍 근본 원인 분석
-
-### 파일: `src/tools/delegate-task/constants.ts`
-
-#### 문제의 핵심
-
-`PLAN_AGENT_SYSTEM_PREPEND` (constants.ts 234-269행)에 구조적 결함이 있었습니다:
-
-1. **Interactive Mode 가정**
-   ```
-   2. After gathering context, ALWAYS present:
-      - Uncertainties: List of unclear points
-      - Clarifying Questions: Specific questions to resolve uncertainties
-   
-   3. ITERATE until ALL requirements are crystal clear:
-      - Do NOT proceed to planning until you have 100% clarity
-      - Ask the user to confirm your understanding
-   ```
-
-2. **종료 조건 없음**
-   - "100% clarity" 요구는 객관적 측정 불가능
-   - 사용자 확인 요청은 ULW mode에서 불가능
-   - 무한루프로 이어짐
-
-3. **ULW Mode 미감지**
-   - Subagent로 실행되는 경우를 구분하지 않음
-   - 항상 interactive mode로 동작 시도
-
-### 왜 무한루프가 발생했는가?
-
-```
-ULW Mode 시작
-  → Sisyphus가 Plan Agent 호출 (subagent)
-    → Plan Agent: "100% clarity 필요"
-      → Clarifying questions 생성
-        → 사용자 없음 (subagent)
-          → 다시 plan 생성 시도
-            → "여전히 unclear"
-              → 무한루프 반복
-```
-
-**핵심:** Plan Agent는 사용자와 대화하도록 설계되었지만, ULW mode에서는 사용자가 없는 subagent로 실행됨.
-
---
-
-## ✅ 적용된 수정 방안
-
-### 수정 내용 (constants.ts)
-
-#### 1. SUBAGENT MODE DETECTION 섹션 추가
-
-```typescript
-SUBAGENT MODE DETECTION (CRITICAL):
-If you received a detailed prompt with gathered context from a parent orchestrator (e.g., Sisyphus):
- You are running as a SUBAGENT
- You CANNOT directly interact with the user
- DO NOT ask clarifying questions - proceed with available information
- Make reasonable assumptions for minor ambiguities
- Generate the plan based on the provided context
-```
-
-#### 2. Context Gathering Protocol 수정
-
-```diff
- 1. Launch background agents to gather context:
-+ 1. Launch background agents to gather context (ONLY if not already provided):
-```
-
-**효과:** 이미 Sisyphus가 context를 수집한 경우 중복 방지
-
-#### 3. Clarifying Questions → Assumptions
-
-```diff
- 2. After gathering context, ALWAYS present:
-    - Uncertainties: List of unclear points
-    - Clarifying Questions: Specific questions
-+ 2. After gathering context, assess clarity:
-+    - User Request Summary: Concise restatement
-+    - Assumptions Made: List any assumptions for unclear points
-```
-
-**효과:** 질문 대신 가정 사항 문서화
-
-#### 4. 무한루프 방지 - 명확한 종료 조건
-
-```diff
- 3. ITERATE until ALL requirements are crystal clear:
-    - Do NOT proceed to planning until you have 100% clarity
-    - Ask the user to confirm your understanding
-    - Resolve every ambiguity before generating the work plan
-+ 3. PROCEED TO PLAN GENERATION when:
-+    - Core objective is understood (even if some details are ambiguous)
-+    - You have gathered context via explore/librarian (or context was provided)
-+    - You can make reasonable assumptions for remaining ambiguities
-+    
-+    DO NOT loop indefinitely waiting for perfect clarity.
-+    DOCUMENT assumptions in the plan so they can be validated during execution.
-```
-
-**효과:**
- "100% clarity" 요구 제거
- 객관적인 진입 조건 제공
- 무한루프 명시적 금지
- Assumptions를 plan에 문서화하여 실행 중 검증 가능
-
-#### 5. 철학 변경
-
-```diff
- REMEMBER: Vague requirements lead to failed implementations.
-+ REMEMBER: A plan with documented assumptions is better than no plan.
-```
-
-**효과:** Perfectionism → Pragmatism
-
---
-
-## 🎯 해결 메커니즘
-
-### Before (무한루프)
-
-```
-Plan Agent 시작
-  ↓
-Context gathering
-  ↓
-Requirements 명확한가?
-  ↓ NO
-Clarifying questions 생성
-  ↓
-사용자 응답 대기 (없음)
-  ↓
-다시 plan 시도
-  ↓
-(무한 반복)
-```
-
-### After (정상 종료)
-
-```
-Plan Agent 시작
-  ↓
-Subagent mode 감지?
-  ↓ YES
-Context 이미 있음? → YES
-  ↓
-Core objective 이해? → YES
-  ↓
-Reasonable assumptions 가능? → YES
-  ↓
-Plan 생성 (assumptions 문서화)
-  ↓
-완료 ✓
-```
-
---
-
-## 📊 영향 분석
-
-### 해결되는 문제
-
-1. **ULW mode 무한루프** ✓
-2. **Sisyphus에서 Plan Agent 호출 시 블로킹** ✓
-3. **작은 토큰 반복 요청** ✓
-4. **1분마다 재시도** ✓
-
-### 부작용 없음
-
- Interactive mode (사용자와 직접 대화)는 여전히 작동
- Subagent mode일 때만 다르게 동작
- Backward compatibility 유지
-
-### 추가 개선사항
-
- Assumptions를 plan에 명시적으로 문서화
- Execution 중 validation 가능
- 더 pragmatic한 workflow
-
---
-
-## 🧪 검증 방법
-
-### 테스트 시나리오
-
-1. **ULW mode에서 Plan Agent 호출**
-   ```bash
-   oh-my-opencode run "Complex task requiring planning. ulw"
-   ```
-   - 예상: Plan 생성 후 정상 종료
-   - 확인: 무한루프 없음
-
-2. **Interactive mode (변경 없어야 함)**
-   ```bash
-   oh-my-opencode run --agent prometheus "Design X"
-   ```
-   - 예상: Clarifying questions 여전히 가능
-   - 확인: 사용자와 대화 가능
-
-3. **Subagent context 제공 케이스**
-   - 예상: Context gathering skip
-   - 확인: 중복 탐색 없음
-
---
-
-## 📝 수정된 파일
-
-```
-src/tools/delegate-task/constants.ts
-```
-
-### Diff Summary
-
-```diff
-@@ -234,22 +234,32 @@ export const PLAN_AGENT_SYSTEM_PREPEND = `<system>
-+SUBAGENT MODE DETECTION (CRITICAL):
-+[subagent 감지 및 처리 로직]
-+
- MANDATORY CONTEXT GATHERING PROTOCOL:
-1. Launch background agents to gather context:
-+1. Launch background agents (ONLY if not already provided):
-
-2. After gathering context, ALWAYS present:
-   - Uncertainties
-   - Clarifying Questions
-+2. After gathering context, assess clarity:
-+   - Assumptions Made
-
-3. ITERATE until ALL requirements are crystal clear:
-   - Do NOT proceed until 100% clarity
-   - Ask user to confirm
-+3. PROCEED TO PLAN GENERATION when:
-+   - Core objective understood
-+   - Context gathered
-+   - Reasonable assumptions possible
-+   
-+   DO NOT loop indefinitely.
-+   DOCUMENT assumptions.
-```
-
---
-
-## 🚀 권장 사항
-
-### Immediate Actions
-
-1. ✅ **수정 적용 완료** - constants.ts 업데이트됨
-2. ⏳ **테스트 수행** - ULW mode에서 동작 검증
-3. ⏳ **PR 생성** - code review 요청
-
-### Future Improvements
-
-1. **Subagent context 표준화**
-   - Subagent로 호출 시 명시적 플래그 전달
-   - `is_subagent: true` 파라미터 추가 고려
-
-2. **Assumptions validation workflow**
-   - Plan 실행 중 assumptions 검증 메커니즘
-   - Incorrect assumptions 감지 시 재계획
-
-3. **Timeout 메커니즘**
-   - Plan Agent가 X분 이상 걸리면 강제 종료
-   - Fallback plan 생성
-
-4. **Monitoring 추가**
-   - Plan Agent 실행 시간 측정
-   - Iteration 횟수 로깅
-   - 무한루프 조기 감지
-
---
-
-## 📖 관련 코드 구조
-
-### Call Stack
-
-```
-Sisyphus (ULW mode)
-  ↓
-task(category="deep", ...)
-  ↓
-executor.ts: executeBackgroundContinuation()
-  ↓
-prompt-builder.ts: buildSystemContent()
-  ↓
-constants.ts: PLAN_AGENT_SYSTEM_PREPEND (문제 위치)
-  ↓
-Plan Agent 실행
-```
-
-### Key Functions
-
-1. **executor.ts:587** - `isPlanAgent()` 체크
-2. **prompt-builder.ts:11** - Plan Agent prepend 주입
-3. **constants.ts:234** - PLAN_AGENT_SYSTEM_PREPEND 정의
-
---
-
-## 🎓 교훈
-
-### Design Lessons
-
-1. **Dual Mode Support**
-   - Interactive vs Autonomous mode 구분 필수
-   - Context 전달 방식 명확히
-
-2. **Avoid Perfectionism in Agents**
-   - "100% clarity" 같은 주관적 조건 지양
-   - 명확한 객관적 종료 조건 필요
-
-3. **Document Uncertainties**
-   - 불확실성을 숨기지 말고 문서화
-   - 실행 중 validation 가능하게
-
-4. **Infinite Loop Prevention**
-   - 모든 반복문에 명시적 종료 조건
-   - Timeout 또는 max iteration 설정
-
---
-
-## 🔗 참고 자료
-
- **Issue:** #1501 - [Bug]: ULW mode will 100% cause PLAN AGENT to get stuck
- **Files Modified:** `src/tools/delegate-task/constants.ts`
- **Related Concepts:** Ultrawork mode, Plan Agent, Subagent delegation
- **Agent Architecture:** Sisyphus → Prometheus → Atlas workflow
-
---
-
-## ✅ Conclusion
-
-**Root Cause:** Plan Agent가 interactive mode를 가정했으나 ULW mode에서는 subagent로 실행되어 사용자 상호작용 불가능. "100% clarity" 요구로 무한루프 발생.
-
-**Solution:** Subagent mode 감지 로직 추가, clarifying questions 제거, 명확한 종료 조건 제공, assumptions 문서화 방식 도입.
-
-**Result:** ULW mode에서 Plan Agent가 정상적으로 plan 생성 후 종료. 무한루프 해결.
-
---
-
-**Status:** ✅ Fixed  
-**Tested:** ⏳ Pending  
-**Deployed:** ⏳ Pending  
-
-**Analyst:** Sisyphus (oh-my-opencode ultrawork mode)  
-**Date:** 2026-02-05  
-**Session:** fast-ember
--- a/src/agents/types.ts
+++ b/src/agents/types.ts
@@ -100,6 +100,7 @@ export type AgentName = BuiltinAgentName
 export type AgentOverrideConfig = Partial<AgentConfig> & {
  prompt_append?: string
  variant?: string
+  fallback_models?: string | string[]
 }

 export type AgentOverrides = Partial<Record<OverridableAgentName, AgentOverrideConfig>>
--- a/src/agents/utils.test.ts
+++ b/src/agents/utils.test.ts
@@ -51,7 +51,7 @@ describe("createBuiltinAgents with model overrides", () => {
    expect(agents.sisyphus.thinking).toBeUndefined()
  })

-  test("Atlas uses uiSelectedModel when provided", async () => {
+  test("Atlas uses uiSelectedModel", async () => {
    // #given
    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
      new Set(["openai/gpt-5.2", "anthropic/claude-sonnet-4-6"])
--- a/src/config/index.ts
+++ b/src/config/index.ts
@@ -11,6 +11,8 @@ export {
  RalphLoopConfigSchema,
  TmuxConfigSchema,
  TmuxLayoutSchema,
+  RuntimeFallbackConfigSchema,
+  FallbackModelsSchema,
 } from "./schema"

 export type {
@@ -29,4 +31,6 @@ export type {
  TmuxLayout,
  SisyphusConfig,
  SisyphusTasksConfig,
+  RuntimeFallbackConfig,
+  FallbackModels,
 } from "./schema"
--- a/src/config/schema.ts
+++ b/src/config/schema.ts
@@ -9,11 +9,13 @@ export * from "./schema/comment-checker"
 export * from "./schema/commands"
 export * from "./schema/dynamic-context-pruning"
 export * from "./schema/experimental"
+export * from "./schema/fallback-models"
 export * from "./schema/git-master"
 export * from "./schema/hooks"
 export * from "./schema/notification"
 export * from "./schema/oh-my-opencode-config"
 export * from "./schema/ralph-loop"
+export * from "./schema/runtime-fallback"
 export * from "./schema/skills"
 export * from "./schema/sisyphus"
 export * from "./schema/sisyphus-agent"
--- a/src/config/schema/agent-overrides.ts
+++ b/src/config/schema/agent-overrides.ts
@@ -1,9 +1,11 @@
 import { z } from "zod"
+import { FallbackModelsSchema } from "./fallback-models"
 import { AgentPermissionSchema } from "./internal/permission"

 export const AgentOverrideConfigSchema = z.object({
  /** @deprecated Use `category` instead. Model is inherited from category defaults. */
  model: z.string().optional(),
+  fallback_models: FallbackModelsSchema.optional(),
  variant: z.string().optional(),
  /** Category name to inherit model and other settings from CategoryConfig */
  category: z.string().optional(),
--- a/src/config/schema/categories.ts
+++ b/src/config/schema/categories.ts
@@ -1,9 +1,11 @@
 import { z } from "zod"
+import { FallbackModelsSchema } from "./fallback-models"

 export const CategoryConfigSchema = z.object({
  /** Human-readable description of the category's purpose. Shown in task prompt. */
  description: z.string().optional(),
  model: z.string().optional(),
+  fallback_models: FallbackModelsSchema.optional(),
  variant: z.string().optional(),
  temperature: z.number().min(0).max(2).optional(),
  top_p: z.number().min(0).max(1).optional(),
--- a/src/config/schema/fallback-models.ts
+++ b/src/config/schema/fallback-models.ts
@@ -0,0 +1,5 @@
+import { z } from "zod"
+
+export const FallbackModelsSchema = z.union([z.string(), z.array(z.string())])
+
+export type FallbackModels = z.infer<typeof FallbackModelsSchema>
--- a/src/config/schema/hooks.ts
+++ b/src/config/schema/hooks.ts
@@ -46,6 +46,7 @@ export const HookNameSchema = z.enum([
  "task-resume-info",
  "stop-continuation-guard",
  "tasks-todowrite-disabler",
+  "runtime-fallback",
  "write-existing-file-guard",
  "anthropic-effort",
  "hashline-read-enhancer",
--- a/src/config/schema/oh-my-opencode-config.ts
+++ b/src/config/schema/oh-my-opencode-config.ts
@@ -14,6 +14,7 @@ import { GitMasterConfigSchema } from "./git-master"
 import { HookNameSchema } from "./hooks"
 import { NotificationConfigSchema } from "./notification"
 import { RalphLoopConfigSchema } from "./ralph-loop"
+import { RuntimeFallbackConfigSchema } from "./runtime-fallback"
 import { SkillsConfigSchema } from "./skills"
 import { SisyphusConfigSchema } from "./sisyphus"
 import { SisyphusAgentConfigSchema } from "./sisyphus-agent"
@@ -44,6 +45,7 @@ export const OhMyOpenCodeConfigSchema = z.object({
  auto_update: z.boolean().optional(),
  skills: SkillsConfigSchema.optional(),
  ralph_loop: RalphLoopConfigSchema.optional(),
+  runtime_fallback: RuntimeFallbackConfigSchema.optional(),
  background_task: BackgroundTaskConfigSchema.optional(),
  notification: NotificationConfigSchema.optional(),
  babysitting: BabysittingConfigSchema.optional(),
--- a/src/config/schema/runtime-fallback.ts
+++ b/src/config/schema/runtime-fallback.ts
@@ -0,0 +1,18 @@
+import { z } from "zod"
+
+export const RuntimeFallbackConfigSchema = z.object({
+  /** Enable runtime fallback (default: true) */
+  enabled: z.boolean().optional(),
+  /** HTTP status codes that trigger fallback (default: [400, 429, 503, 529]) */
+  retry_on_errors: z.array(z.number()).optional(),
+  /** Maximum fallback attempts per session (default: 3) */
+  max_fallback_attempts: z.number().min(1).max(20).optional(),
+  /** Cooldown in seconds before retrying a failed model (default: 60) */
+  cooldown_seconds: z.number().min(0).optional(),
+  /** Session-level timeout in seconds to advance fallback when provider hangs (default: 30). Set to 0 to disable auto-retry signal detection (only error-based fallback remains active). */
+  timeout_seconds: z.number().min(0).optional(),
+  /** Show toast notification when switching to fallback model (default: true) */
+  notify_on_fallback: z.boolean().optional(),
+})
+
+export type RuntimeFallbackConfig = z.infer<typeof RuntimeFallbackConfigSchema>
--- a/src/features/background-agent/manager.ts
+++ b/src/features/background-agent/manager.ts
@@ -16,6 +16,7 @@ import {
  createInternalAgentTextPart,
 } from "../../shared"
 import { setSessionTools } from "../../shared/session-tools-store"
+import { SessionCategoryRegistry } from "../../shared/session-category-registry"
 import { ConcurrencyManager } from "./concurrency"
 import type { BackgroundTaskConfig, TmuxConfig } from "../../config/schema"
 import { isInsideTmux } from "../../shared/tmux"
@@ -859,6 +860,7 @@ export class BackgroundManager {
          subagentSessions.delete(task.sessionID)
        }
      }
+      SessionCategoryRegistry.remove(sessionID)
    }
  }

@@ -1022,6 +1024,8 @@ export class BackgroundManager {
      this.client.session.abort({
        path: { id: task.sessionID },
      }).catch(() => {})
+
+      SessionCategoryRegistry.remove(task.sessionID)
    }

    if (options?.skipNotification) {
@@ -1169,6 +1173,8 @@ export class BackgroundManager {
      this.client.session.abort({
        path: { id: task.sessionID },
      }).catch(() => {})
+
+      SessionCategoryRegistry.remove(task.sessionID)
    }

    try {
@@ -1471,6 +1477,7 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
        this.tasks.delete(taskId)
        if (task.sessionID) {
          subagentSessions.delete(task.sessionID)
+          SessionCategoryRegistry.remove(task.sessionID)
        }
      }
    }
--- a/src/hooks/AGENTS.md
+++ b/src/hooks/AGENTS.md
@@ -9,6 +9,45 @@
 ## HOOK TIERS

 ### Tier 1: Session Hooks (22) — `create-session-hooks.ts`
+## STRUCTURE
+```
+hooks/
+├── atlas/                      # Main orchestration (757 lines)
+├── anthropic-context-window-limit-recovery/ # Auto-summarize
+├── todo-continuation-enforcer.ts # Force TODO completion
+├── ralph-loop/                 # Self-referential dev loop
+├── claude-code-hooks/          # settings.json compat layer - see AGENTS.md
+├── comment-checker/            # Prevents AI slop
+├── auto-slash-command/         # Detects /command patterns
+├── rules-injector/             # Conditional rules
+├── directory-agents-injector/  # Auto-injects AGENTS.md
+├── directory-readme-injector/  # Auto-injects README.md
+├── edit-error-recovery/        # Recovers from failures
+├── thinking-block-validator/   # Ensures valid <thinking>
+├── context-window-monitor.ts   # Reminds of headroom
+├── session-recovery/           # Auto-recovers from crashes
+├── think-mode/                 # Dynamic thinking budget
+├── keyword-detector/           # ultrawork/search/analyze modes
+├── background-notification/    # OS notification
+├── prometheus-md-only/         # Planner read-only mode
+├── agent-usage-reminder/       # Specialized agent hints
+├── auto-update-checker/        # Plugin update check
+├── tool-output-truncator.ts    # Prevents context bloat
+├── compaction-context-injector/ # Injects context on compaction
+├── delegate-task-retry/        # Retries failed delegations
+├── interactive-bash-session/   # Tmux session management
+├── non-interactive-env/        # Non-TTY environment handling
+├── start-work/                 # Sisyphus work session starter
+├── task-resume-info/           # Resume info for cancelled tasks
+├── question-label-truncator/   # Auto-truncates question labels
+├── category-skill-reminder/    # Reminds of category skills
+├── empty-task-response-detector.ts # Detects empty responses
+├── sisyphus-junior-notepad/    # Sisyphus Junior notepad
+├── stop-continuation-guard/    # Guards stop continuation
+├── subagent-question-blocker/  # Blocks subagent questions
+├── runtime-fallback/           # Auto-switch models on API errors
+└── index.ts                    # Hook aggregation + registration
+```

 | Hook | Event | Purpose |
 |------|-------|---------|
--- a/src/hooks/index.ts
+++ b/src/hooks/index.ts
@@ -45,7 +45,7 @@ export { createCompactionTodoPreserverHook } from "./compaction-todo-preserver";
 export { createUnstableAgentBabysitterHook } from "./unstable-agent-babysitter";
 export { createPreemptiveCompactionHook } from "./preemptive-compaction";
 export { createTasksTodowriteDisablerHook } from "./tasks-todowrite-disabler";
+export { createRuntimeFallbackHook, type RuntimeFallbackHook, type RuntimeFallbackOptions } from "./runtime-fallback";
 export { createWriteExistingFileGuardHook } from "./write-existing-file-guard";
 export { createHashlineReadEnhancerHook } from "./hashline-read-enhancer";
 export { createHashlineEditDiffEnhancerHook } from "./hashline-edit-diff-enhancer";
-
--- a/src/hooks/runtime-fallback/agent-resolver.ts
+++ b/src/hooks/runtime-fallback/agent-resolver.ts
@@ -0,0 +1,54 @@
+import { getSessionAgent } from "../../features/claude-code-session-state"
+
+export const AGENT_NAMES = [
+  "sisyphus",
+  "oracle",
+  "librarian",
+  "explore",
+  "prometheus",
+  "atlas",
+  "metis",
+  "momus",
+  "hephaestus",
+  "sisyphus-junior",
+  "build",
+  "plan",
+  "multimodal-looker",
+]
+
+export const agentPattern = new RegExp(
+  `\\b(${AGENT_NAMES
+    .sort((a, b) => b.length - a.length)
+    .map((a) => a.replace(/-/g, "\\-"))
+    .join("|")})\\b`,
+  "i",
+)
+
+export function detectAgentFromSession(sessionID: string): string | undefined {
+  const match = sessionID.match(agentPattern)
+  if (match) {
+    return match[1].toLowerCase()
+  }
+  return undefined
+}
+
+export function normalizeAgentName(agent: string | undefined): string | undefined {
+  if (!agent) return undefined
+  const normalized = agent.toLowerCase().trim()
+  if (AGENT_NAMES.includes(normalized)) {
+    return normalized
+  }
+  const match = normalized.match(agentPattern)
+  if (match) {
+    return match[1].toLowerCase()
+  }
+  return undefined
+}
+
+export function resolveAgentForSession(sessionID: string, eventAgent?: string): string | undefined {
+  return (
+    normalizeAgentName(eventAgent) ??
+    normalizeAgentName(getSessionAgent(sessionID)) ??
+    detectAgentFromSession(sessionID)
+  )
+}
--- a/src/hooks/runtime-fallback/auto-retry.ts
+++ b/src/hooks/runtime-fallback/auto-retry.ts
@@ -0,0 +1,213 @@
+import type { HookDeps } from "./types"
+import { HOOK_NAME } from "./constants"
+import { log } from "../../shared/logger"
+import { normalizeAgentName, resolveAgentForSession } from "./agent-resolver"
+import { getSessionAgent } from "../../features/claude-code-session-state"
+import { getFallbackModelsForSession } from "./fallback-models"
+import { prepareFallback } from "./fallback-state"
+import { SessionCategoryRegistry } from "../../shared/session-category-registry"
+
+const SESSION_TTL_MS = 30 * 60 * 1000
+
+export function createAutoRetryHelpers(deps: HookDeps) {
+  const { ctx, config, options, sessionStates, sessionLastAccess, sessionRetryInFlight, sessionAwaitingFallbackResult, sessionFallbackTimeouts, pluginConfig } = deps
+
+  const abortSessionRequest = async (sessionID: string, source: string): Promise<void> => {
+    try {
+      await ctx.client.session.abort({ path: { id: sessionID } })
+      log(`[${HOOK_NAME}] Aborted in-flight session request (${source})`, { sessionID })
+    } catch (error) {
+      log(`[${HOOK_NAME}] Failed to abort in-flight session request (${source})`, {
+        sessionID,
+        error: String(error),
+      })
+    }
+  }
+
+  const clearSessionFallbackTimeout = (sessionID: string) => {
+    const timer = sessionFallbackTimeouts.get(sessionID)
+    if (timer) {
+      clearTimeout(timer)
+      sessionFallbackTimeouts.delete(sessionID)
+    }
+  }
+
+  const scheduleSessionFallbackTimeout = (sessionID: string, resolvedAgent?: string) => {
+    clearSessionFallbackTimeout(sessionID)
+
+    const timeoutMs = options?.session_timeout_ms ?? config.timeout_seconds * 1000
+    if (timeoutMs <= 0) return
+
+    const timer = setTimeout(async () => {
+      sessionFallbackTimeouts.delete(sessionID)
+
+      const state = sessionStates.get(sessionID)
+      if (!state) return
+
+      if (sessionRetryInFlight.has(sessionID)) {
+        log(`[${HOOK_NAME}] Overriding in-flight retry due to session timeout`, { sessionID })
+      }
+
+      await abortSessionRequest(sessionID, "session.timeout")
+      sessionRetryInFlight.delete(sessionID)
+
+      if (state.pendingFallbackModel) {
+        state.pendingFallbackModel = undefined
+      }
+
+      const fallbackModels = getFallbackModelsForSession(sessionID, resolvedAgent, pluginConfig)
+      if (fallbackModels.length === 0) return
+
+      log(`[${HOOK_NAME}] Session fallback timeout reached`, {
+        sessionID,
+        timeoutSeconds: config.timeout_seconds,
+        currentModel: state.currentModel,
+      })
+
+      const result = prepareFallback(sessionID, state, fallbackModels, config)
+      if (result.success && result.newModel) {
+        await autoRetryWithFallback(sessionID, result.newModel, resolvedAgent, "session.timeout")
+      }
+    }, timeoutMs)
+
+    sessionFallbackTimeouts.set(sessionID, timer)
+  }
+
+  const autoRetryWithFallback = async (
+    sessionID: string,
+    newModel: string,
+    resolvedAgent: string | undefined,
+    source: string,
+  ): Promise<void> => {
+    if (sessionRetryInFlight.has(sessionID)) {
+      log(`[${HOOK_NAME}] Retry already in flight, skipping (${source})`, { sessionID })
+      return
+    }
+
+    const modelParts = newModel.split("/")
+    if (modelParts.length < 2) {
+      log(`[${HOOK_NAME}] Invalid model format (missing provider prefix): ${newModel}`)
+      return
+    }
+
+    const fallbackModelObj = {
+      providerID: modelParts[0],
+      modelID: modelParts.slice(1).join("/"),
+    }
+
+    sessionRetryInFlight.add(sessionID)
+    try {
+      const messagesResp = await ctx.client.session.messages({
+        path: { id: sessionID },
+        query: { directory: ctx.directory },
+      })
+      const msgs = (messagesResp as {
+        data?: Array<{
+          info?: Record<string, unknown>
+          parts?: Array<{ type?: string; text?: string }>
+        }>
+      }).data
+      const lastUserMsg = msgs?.filter((m) => m.info?.role === "user").pop()
+      const lastUserPartsRaw =
+        lastUserMsg?.parts ??
+        (lastUserMsg?.info?.parts as Array<{ type?: string; text?: string }> | undefined)
+
+      if (lastUserPartsRaw && lastUserPartsRaw.length > 0) {
+        log(`[${HOOK_NAME}] Auto-retrying with fallback model (${source})`, {
+          sessionID,
+          model: newModel,
+        })
+
+        const retryParts = lastUserPartsRaw
+          .filter((p) => p.type === "text" && typeof p.text === "string" && p.text.length > 0)
+          .map((p) => ({ type: "text" as const, text: p.text! }))
+
+        if (retryParts.length > 0) {
+          const retryAgent = resolvedAgent ?? getSessionAgent(sessionID)
+          sessionAwaitingFallbackResult.add(sessionID)
+          scheduleSessionFallbackTimeout(sessionID, retryAgent)
+
+          await ctx.client.session.promptAsync({
+            path: { id: sessionID },
+            body: {
+              ...(retryAgent ? { agent: retryAgent } : {}),
+              model: fallbackModelObj,
+              parts: retryParts,
+            },
+            query: { directory: ctx.directory },
+          })
+        }
+      } else {
+        log(`[${HOOK_NAME}] No user message found for auto-retry (${source})`, { sessionID })
+      }
+    } catch (retryError) {
+      log(`[${HOOK_NAME}] Auto-retry failed (${source})`, { sessionID, error: String(retryError) })
+    } finally {
+      const state = sessionStates.get(sessionID)
+      if (state?.pendingFallbackModel === newModel) {
+        state.pendingFallbackModel = undefined
+      }
+      sessionRetryInFlight.delete(sessionID)
+    }
+  }
+
+  const resolveAgentForSessionFromContext = async (
+    sessionID: string,
+    eventAgent?: string,
+  ): Promise<string | undefined> => {
+    const resolved = resolveAgentForSession(sessionID, eventAgent)
+    if (resolved) return resolved
+
+    try {
+      const messagesResp = await ctx.client.session.messages({
+        path: { id: sessionID },
+        query: { directory: ctx.directory },
+      })
+      const msgs = (messagesResp as { data?: Array<{ info?: Record<string, unknown> }> }).data
+      if (!msgs || msgs.length === 0) return undefined
+
+      for (let i = msgs.length - 1; i >= 0; i--) {
+        const info = msgs[i]?.info
+        const infoAgent = typeof info?.agent === "string" ? info.agent : undefined
+        const normalized = normalizeAgentName(infoAgent)
+        if (normalized) {
+          return normalized
+        }
+      }
+    } catch {
+      return undefined
+    }
+
+    return undefined
+  }
+
+  const cleanupStaleSessions = () => {
+    const now = Date.now()
+    let cleanedCount = 0
+    for (const [sessionID, lastAccess] of sessionLastAccess.entries()) {
+      if (now - lastAccess > SESSION_TTL_MS) {
+        sessionStates.delete(sessionID)
+        sessionLastAccess.delete(sessionID)
+        sessionRetryInFlight.delete(sessionID)
+        sessionAwaitingFallbackResult.delete(sessionID)
+        clearSessionFallbackTimeout(sessionID)
+        SessionCategoryRegistry.remove(sessionID)
+        cleanedCount++
+      }
+    }
+    if (cleanedCount > 0) {
+      log(`[${HOOK_NAME}] Cleaned up ${cleanedCount} stale session states`)
+    }
+  }
+
+  return {
+    abortSessionRequest,
+    clearSessionFallbackTimeout,
+    scheduleSessionFallbackTimeout,
+    autoRetryWithFallback,
+    resolveAgentForSessionFromContext,
+    cleanupStaleSessions,
+  }
+}
+
+export type AutoRetryHelpers = ReturnType<typeof createAutoRetryHelpers>
--- a/src/hooks/runtime-fallback/chat-message-handler.ts
+++ b/src/hooks/runtime-fallback/chat-message-handler.ts
@@ -0,0 +1,62 @@
+import type { HookDeps } from "./types"
+import { HOOK_NAME } from "./constants"
+import { log } from "../../shared/logger"
+import { createFallbackState } from "./fallback-state"
+
+export function createChatMessageHandler(deps: HookDeps) {
+  const { config, sessionStates, sessionLastAccess } = deps
+
+  return async (
+    input: { sessionID: string; agent?: string; model?: { providerID: string; modelID: string } },
+    output: { message: { model?: { providerID: string; modelID: string } }; parts?: Array<{ type: string; text?: string }> }
+  ) => {
+    if (!config.enabled) return
+
+    const { sessionID } = input
+    let state = sessionStates.get(sessionID)
+
+    if (!state) return
+
+    sessionLastAccess.set(sessionID, Date.now())
+
+    const requestedModel = input.model
+      ? `${input.model.providerID}/${input.model.modelID}`
+      : undefined
+
+    if (requestedModel && requestedModel !== state.currentModel) {
+      if (state.pendingFallbackModel && state.pendingFallbackModel === requestedModel) {
+        state.pendingFallbackModel = undefined
+        return
+      }
+
+      log(`[${HOOK_NAME}] Detected manual model change, resetting fallback state`, {
+        sessionID,
+        from: state.currentModel,
+        to: requestedModel,
+      })
+      state = createFallbackState(requestedModel)
+      sessionStates.set(sessionID, state)
+      return
+    }
+
+    if (state.currentModel === state.originalModel) return
+
+    const activeModel = state.currentModel
+
+    log(`[${HOOK_NAME}] Applying fallback model override`, {
+      sessionID,
+      from: input.model,
+      to: activeModel,
+    })
+
+    if (output.message && activeModel) {
+      const parts = activeModel.split("/")
+      if (parts.length >= 2) {
+        output.message.model = {
+          providerID: parts[0],
+          modelID: parts.slice(1).join("/"),
+        }
+      }
+    }
+  }
+}
--- a/src/hooks/runtime-fallback/constants.ts
+++ b/src/hooks/runtime-fallback/constants.ts
@@ -0,0 +1,44 @@
+/**
+ * Runtime Fallback Hook - Constants
+ *
+ * Default values and configuration constants for the runtime fallback feature.
+ */
+
+import type { RuntimeFallbackConfig } from "../../config"
+
+/**
+ * Default configuration values for runtime fallback
+ */
+export const DEFAULT_CONFIG: Required<RuntimeFallbackConfig> = {
+  enabled: true,
+  retry_on_errors: [400, 429, 503, 529],
+  max_fallback_attempts: 3,
+  cooldown_seconds: 60,
+  timeout_seconds: 30,
+  notify_on_fallback: true,
+}
+
+/**
+ * Error patterns that indicate rate limiting or temporary failures
+ * These are checked in addition to HTTP status codes
+ */
+export const RETRYABLE_ERROR_PATTERNS = [
+  /rate.?limit/i,
+  /too.?many.?requests/i,
+  /quota.?exceeded/i,
+  /usage\s+limit\s+has\s+been\s+reached/i,
+  /service.?unavailable/i,
+  /overloaded/i,
+  /temporarily.?unavailable/i,
+  /try.?again/i,
+  /credit.*balance.*too.*low/i,
+  /insufficient.?(?:credits?|funds?|balance)/i,
+  /(?:^|\s)429(?:\s|$)/,
+  /(?:^|\s)503(?:\s|$)/,
+  /(?:^|\s)529(?:\s|$)/,
+]
+
+/**
+ * Hook name for identification and logging
+ */
+export const HOOK_NAME = "runtime-fallback"
--- a/src/hooks/runtime-fallback/error-classifier.ts
+++ b/src/hooks/runtime-fallback/error-classifier.ts
@@ -0,0 +1,169 @@
+import { DEFAULT_CONFIG, RETRYABLE_ERROR_PATTERNS } from "./constants"
+
+export function getErrorMessage(error: unknown): string {
+  if (!error) return ""
+  if (typeof error === "string") return error.toLowerCase()
+
+  const errorObj = error as Record<string, unknown>
+  const paths = [
+    errorObj.data,
+    errorObj.error,
+    errorObj,
+    (errorObj.data as Record<string, unknown>)?.error,
+  ]
+
+  for (const obj of paths) {
+    if (obj && typeof obj === "object") {
+      const msg = (obj as Record<string, unknown>).message
+      if (typeof msg === "string" && msg.length > 0) {
+        return msg.toLowerCase()
+      }
+    }
+  }
+
+  try {
+    return JSON.stringify(error).toLowerCase()
+  } catch {
+    return ""
+  }
+}
+
+export function extractStatusCode(error: unknown, retryOnErrors?: number[]): number | undefined {
+  if (!error) return undefined
+
+  const errorObj = error as Record<string, unknown>
+
+  const statusCode = errorObj.statusCode ?? errorObj.status ?? (errorObj.data as Record<string, unknown>)?.statusCode
+  if (typeof statusCode === "number") {
+    return statusCode
+  }
+
+  const codes = retryOnErrors ?? DEFAULT_CONFIG.retry_on_errors
+  const pattern = new RegExp(`\\b(${codes.join("|")})\\b`)
+  const message = getErrorMessage(error)
+  const statusMatch = message.match(pattern)
+  if (statusMatch) {
+    return parseInt(statusMatch[1], 10)
+  }
+
+  return undefined
+}
+
+export function extractErrorName(error: unknown): string | undefined {
+  if (!error || typeof error !== "object") return undefined
+
+  const errorObj = error as Record<string, unknown>
+  const directName = errorObj.name
+  if (typeof directName === "string" && directName.length > 0) {
+    return directName
+  }
+
+  const nestedError = errorObj.error as Record<string, unknown> | undefined
+  const nestedName = nestedError?.name
+  if (typeof nestedName === "string" && nestedName.length > 0) {
+    return nestedName
+  }
+
+  const dataError = (errorObj.data as Record<string, unknown> | undefined)?.error as Record<string, unknown> | undefined
+  const dataErrorName = dataError?.name
+  if (typeof dataErrorName === "string" && dataErrorName.length > 0) {
+    return dataErrorName
+  }
+
+  return undefined
+}
+
+export function classifyErrorType(error: unknown): string | undefined {
+  const message = getErrorMessage(error)
+  const errorName = extractErrorName(error)?.toLowerCase()
+
+  if (
+    errorName?.includes("loadapi") ||
+    (/api.?key.?is.?missing/i.test(message) && /environment variable/i.test(message))
+  ) {
+    return "missing_api_key"
+  }
+
+  if (/api.?key/i.test(message) && /must be a string/i.test(message)) {
+    return "invalid_api_key"
+  }
+
+  if (errorName?.includes("unknownerror") && /model\s+not\s+found/i.test(message)) {
+    return "model_not_found"
+  }
+
+  return undefined
+}
+
+export interface AutoRetrySignal {
+  signal: string
+}
+
+export const AUTO_RETRY_PATTERNS: Array<(combined: string) => boolean> = [
+  (combined) => /retrying\s+in/i.test(combined),
+  (combined) =>
+    /(?:too\s+many\s+requests|quota\s*exceeded|usage\s+limit|rate\s+limit|limit\s+reached)/i.test(combined),
+]
+
+export function extractAutoRetrySignal(info: Record<string, unknown> | undefined): AutoRetrySignal | undefined {
+  if (!info) return undefined
+
+  const candidates: string[] = []
+
+  const directStatus = info.status
+  if (typeof directStatus === "string") candidates.push(directStatus)
+
+  const summary = info.summary
+  if (typeof summary === "string") candidates.push(summary)
+
+  const message = info.message
+  if (typeof message === "string") candidates.push(message)
+
+  const details = info.details
+  if (typeof details === "string") candidates.push(details)
+
+  const combined = candidates.join("\n")
+  if (!combined) return undefined
+
+  const isAutoRetry = AUTO_RETRY_PATTERNS.every((test) => test(combined))
+  if (isAutoRetry) {
+    return { signal: combined }
+  }
+
+  return undefined
+}
+
+export function containsErrorContent(
+  parts: Array<{ type?: string; text?: string }> | undefined
+): { hasError: boolean; errorMessage?: string } {
+  if (!parts || parts.length === 0) return { hasError: false }
+
+  const errorParts = parts.filter((p) => p.type === "error")
+  if (errorParts.length > 0) {
+    const errorMessages = errorParts.map((p) => p.text).filter((text): text is string => typeof text === "string")
+    const errorMessage = errorMessages.length > 0 ? errorMessages.join("\n") : undefined
+    return { hasError: true, errorMessage }
+  }
+
+  return { hasError: false }
+}
+
+export function isRetryableError(error: unknown, retryOnErrors: number[]): boolean {
+  const statusCode = extractStatusCode(error, retryOnErrors)
+  const message = getErrorMessage(error)
+  const errorType = classifyErrorType(error)
+
+  if (errorType === "missing_api_key") {
+    return true
+  }
+
+  if (errorType === "model_not_found") {
+    return true
+  }
+
+  if (statusCode && retryOnErrors.includes(statusCode)) {
+    return true
+  }
+
+  return RETRYABLE_ERROR_PATTERNS.some((pattern) => pattern.test(message))
+}
--- a/src/hooks/runtime-fallback/event-handler.ts
+++ b/src/hooks/runtime-fallback/event-handler.ts
@@ -0,0 +1,187 @@
+import type { HookDeps } from "./types"
+import type { AutoRetryHelpers } from "./auto-retry"
+import { HOOK_NAME } from "./constants"
+import { log } from "../../shared/logger"
+import { extractStatusCode, extractErrorName, classifyErrorType, isRetryableError } from "./error-classifier"
+import { createFallbackState, prepareFallback } from "./fallback-state"
+import { getFallbackModelsForSession } from "./fallback-models"
+import { SessionCategoryRegistry } from "../../shared/session-category-registry"
+
+export function createEventHandler(deps: HookDeps, helpers: AutoRetryHelpers) {
+  const { config, pluginConfig, sessionStates, sessionLastAccess, sessionRetryInFlight, sessionAwaitingFallbackResult, sessionFallbackTimeouts } = deps
+
+  const handleSessionCreated = (props: Record<string, unknown> | undefined) => {
+    const sessionInfo = props?.info as { id?: string; model?: string } | undefined
+    const sessionID = sessionInfo?.id
+    const model = sessionInfo?.model
+
+    if (sessionID && model) {
+      log(`[${HOOK_NAME}] Session created with model`, { sessionID, model })
+      sessionStates.set(sessionID, createFallbackState(model))
+      sessionLastAccess.set(sessionID, Date.now())
+    }
+  }
+
+  const handleSessionDeleted = (props: Record<string, unknown> | undefined) => {
+    const sessionInfo = props?.info as { id?: string } | undefined
+    const sessionID = sessionInfo?.id
+
+    if (sessionID) {
+      log(`[${HOOK_NAME}] Cleaning up session state`, { sessionID })
+      sessionStates.delete(sessionID)
+      sessionLastAccess.delete(sessionID)
+      sessionRetryInFlight.delete(sessionID)
+      sessionAwaitingFallbackResult.delete(sessionID)
+      helpers.clearSessionFallbackTimeout(sessionID)
+      SessionCategoryRegistry.remove(sessionID)
+    }
+  }
+
+  const handleSessionStop = async (props: Record<string, unknown> | undefined) => {
+    const sessionID = props?.sessionID as string | undefined
+    if (!sessionID) return
+
+    helpers.clearSessionFallbackTimeout(sessionID)
+
+    if (sessionRetryInFlight.has(sessionID)) {
+      await helpers.abortSessionRequest(sessionID, "session.stop")
+    }
+
+    sessionRetryInFlight.delete(sessionID)
+    sessionAwaitingFallbackResult.delete(sessionID)
+
+    const state = sessionStates.get(sessionID)
+    if (state?.pendingFallbackModel) {
+      state.pendingFallbackModel = undefined
+    }
+
+    log(`[${HOOK_NAME}] Cleared fallback retry state on session.stop`, { sessionID })
+  }
+
+  const handleSessionIdle = (props: Record<string, unknown> | undefined) => {
+    const sessionID = props?.sessionID as string | undefined
+    if (!sessionID) return
+
+    if (sessionAwaitingFallbackResult.has(sessionID)) {
+      log(`[${HOOK_NAME}] session.idle while awaiting fallback result; keeping timeout armed`, { sessionID })
+      return
+    }
+
+    const hadTimeout = sessionFallbackTimeouts.has(sessionID)
+    helpers.clearSessionFallbackTimeout(sessionID)
+    sessionRetryInFlight.delete(sessionID)
+
+    const state = sessionStates.get(sessionID)
+    if (state?.pendingFallbackModel) {
+      state.pendingFallbackModel = undefined
+    }
+
+    if (hadTimeout) {
+      log(`[${HOOK_NAME}] Cleared fallback timeout after session completion`, { sessionID })
+    }
+  }
+
+  const handleSessionError = async (props: Record<string, unknown> | undefined) => {
+    const sessionID = props?.sessionID as string | undefined
+    const error = props?.error
+    const agent = props?.agent as string | undefined
+
+    if (!sessionID) {
+      log(`[${HOOK_NAME}] session.error without sessionID, skipping`)
+      return
+    }
+
+    const resolvedAgent = await helpers.resolveAgentForSessionFromContext(sessionID, agent)
+    sessionAwaitingFallbackResult.delete(sessionID)
+    helpers.clearSessionFallbackTimeout(sessionID)
+
+    log(`[${HOOK_NAME}] session.error received`, {
+      sessionID,
+      agent,
+      resolvedAgent,
+      statusCode: extractStatusCode(error, config.retry_on_errors),
+      errorName: extractErrorName(error),
+      errorType: classifyErrorType(error),
+    })
+
+    if (!isRetryableError(error, config.retry_on_errors)) {
+      log(`[${HOOK_NAME}] Error not retryable, skipping fallback`, {
+        sessionID,
+        retryable: false,
+        statusCode: extractStatusCode(error, config.retry_on_errors),
+        errorName: extractErrorName(error),
+        errorType: classifyErrorType(error),
+      })
+      return
+    }
+
+    let state = sessionStates.get(sessionID)
+    const fallbackModels = getFallbackModelsForSession(sessionID, resolvedAgent, pluginConfig)
+
+    if (fallbackModels.length === 0) {
+      log(`[${HOOK_NAME}] No fallback models configured`, { sessionID, agent })
+      return
+    }
+
+    if (!state) {
+      const currentModel = props?.model as string | undefined
+      if (currentModel) {
+        state = createFallbackState(currentModel)
+        sessionStates.set(sessionID, state)
+        sessionLastAccess.set(sessionID, Date.now())
+      } else {
+        const detectedAgent = resolvedAgent
+        const agentConfig = detectedAgent
+          ? pluginConfig?.agents?.[detectedAgent as keyof typeof pluginConfig.agents]
+          : undefined
+        const agentModel = agentConfig?.model as string | undefined
+        if (agentModel) {
+          log(`[${HOOK_NAME}] Derived model from agent config`, { sessionID, agent: detectedAgent, model: agentModel })
+          state = createFallbackState(agentModel)
+          sessionStates.set(sessionID, state)
+          sessionLastAccess.set(sessionID, Date.now())
+        } else {
+          log(`[${HOOK_NAME}] No model info available, cannot fallback`, { sessionID })
+          return
+        }
+      }
+    } else {
+      sessionLastAccess.set(sessionID, Date.now())
+    }
+
+    const result = prepareFallback(sessionID, state, fallbackModels, config)
+
+    if (result.success && config.notify_on_fallback) {
+      await deps.ctx.client.tui
+        .showToast({
+          body: {
+            title: "Model Fallback",
+            message: `Switching to ${result.newModel?.split("/").pop() || result.newModel} for next request`,
+            variant: "warning",
+            duration: 5000,
+          },
+        })
+        .catch(() => {})
+    }
+
+    if (result.success && result.newModel) {
+      await helpers.autoRetryWithFallback(sessionID, result.newModel, resolvedAgent, "session.error")
+    }
+
+    if (!result.success) {
+      log(`[${HOOK_NAME}] Fallback preparation failed`, { sessionID, error: result.error })
+    }
+  }
+
+  return async ({ event }: { event: { type: string; properties?: unknown } }) => {
+    if (!config.enabled) return
+
+    const props = event.properties as Record<string, unknown> | undefined
+
+    if (event.type === "session.created") { handleSessionCreated(props); return }
+    if (event.type === "session.deleted") { handleSessionDeleted(props); return }
+    if (event.type === "session.stop") { await handleSessionStop(props); return }
+    if (event.type === "session.idle") { handleSessionIdle(props); return }
+    if (event.type === "session.error") { await handleSessionError(props); return }
+  }
+}
--- a/src/hooks/runtime-fallback/fallback-models.ts
+++ b/src/hooks/runtime-fallback/fallback-models.ts
@@ -0,0 +1,69 @@
+import type { OhMyOpenCodeConfig } from "../../config"
+import { AGENT_NAMES, agentPattern } from "./agent-resolver"
+import { HOOK_NAME } from "./constants"
+import { log } from "../../shared/logger"
+import { SessionCategoryRegistry } from "../../shared/session-category-registry"
+import { normalizeFallbackModels } from "../../shared/model-resolver"
+
+export function getFallbackModelsForSession(
+  sessionID: string,
+  agent: string | undefined,
+  pluginConfig: OhMyOpenCodeConfig | undefined
+): string[] {
+  if (!pluginConfig) return []
+
+  const sessionCategory = SessionCategoryRegistry.get(sessionID)
+  if (sessionCategory && pluginConfig.categories?.[sessionCategory]) {
+    const categoryConfig = pluginConfig.categories[sessionCategory]
+    if (categoryConfig?.fallback_models) {
+      return normalizeFallbackModels(categoryConfig.fallback_models) ?? []
+    }
+  }
+
+  const tryGetFallbackFromAgent = (agentName: string): string[] | undefined => {
+    const agentConfig = pluginConfig.agents?.[agentName as keyof typeof pluginConfig.agents]
+    if (!agentConfig) return undefined
+    
+    if (agentConfig?.fallback_models) {
+      return normalizeFallbackModels(agentConfig.fallback_models)
+    }
+    
+    const agentCategory = agentConfig?.category
+    if (agentCategory && pluginConfig.categories?.[agentCategory]) {
+      const categoryConfig = pluginConfig.categories[agentCategory]
+      if (categoryConfig?.fallback_models) {
+        return normalizeFallbackModels(categoryConfig.fallback_models)
+      }
+    }
+    
+    return undefined
+  }
+
+  if (agent) {
+    const result = tryGetFallbackFromAgent(agent)
+    if (result) return result
+  }
+
+  const sessionAgentMatch = sessionID.match(agentPattern)
+  if (sessionAgentMatch) {
+    const detectedAgent = sessionAgentMatch[1].toLowerCase()
+    const result = tryGetFallbackFromAgent(detectedAgent)
+    if (result) return result
+  }
+
+  const sisyphusFallback = tryGetFallbackFromAgent("sisyphus")
+  if (sisyphusFallback) {
+    log(`[${HOOK_NAME}] Using sisyphus fallback models (no agent detected)`, { sessionID })
+    return sisyphusFallback
+  }
+
+  for (const agentName of AGENT_NAMES) {
+    const result = tryGetFallbackFromAgent(agentName)
+    if (result) {
+      log(`[${HOOK_NAME}] Using ${agentName} fallback models (no agent detected)`, { sessionID })
+      return result
+    }
+  }
+
+  return []
+}
--- a/src/hooks/runtime-fallback/fallback-state.ts
+++ b/src/hooks/runtime-fallback/fallback-state.ts
@@ -0,0 +1,74 @@
+import type { FallbackState, FallbackResult } from "./types"
+import { HOOK_NAME } from "./constants"
+import { log } from "../../shared/logger"
+import type { RuntimeFallbackConfig } from "../../config"
+
+export function createFallbackState(originalModel: string): FallbackState {
+  return {
+    originalModel,
+    currentModel: originalModel,
+    fallbackIndex: -1,
+    failedModels: new Map<string, number>(),
+    attemptCount: 0,
+    pendingFallbackModel: undefined,
+  }
+}
+
+export function isModelInCooldown(model: string, state: FallbackState, cooldownSeconds: number): boolean {
+  const failedAt = state.failedModels.get(model)
+  if (failedAt === undefined) return false
+  const cooldownMs = cooldownSeconds * 1000
+  return Date.now() - failedAt < cooldownMs
+}
+
+export function findNextAvailableFallback(
+  state: FallbackState,
+  fallbackModels: string[],
+  cooldownSeconds: number
+): string | undefined {
+  for (let i = state.fallbackIndex + 1; i < fallbackModels.length; i++) {
+    const candidate = fallbackModels[i]
+    if (!isModelInCooldown(candidate, state, cooldownSeconds)) {
+      return candidate
+    }
+    log(`[${HOOK_NAME}] Skipping fallback model in cooldown`, { model: candidate, index: i })
+  }
+  return undefined
+}
+
+export function prepareFallback(
+  sessionID: string,
+  state: FallbackState,
+  fallbackModels: string[],
+  config: Required<RuntimeFallbackConfig>
+): FallbackResult {
+  if (state.attemptCount >= config.max_fallback_attempts) {
+    log(`[${HOOK_NAME}] Max fallback attempts reached`, { sessionID, attempts: state.attemptCount })
+    return { success: false, error: "Max fallback attempts reached", maxAttemptsReached: true }
+  }
+
+  const nextModel = findNextAvailableFallback(state, fallbackModels, config.cooldown_seconds)
+
+  if (!nextModel) {
+    log(`[${HOOK_NAME}] No available fallback models`, { sessionID })
+    return { success: false, error: "No available fallback models (all in cooldown or exhausted)" }
+  }
+
+  log(`[${HOOK_NAME}] Preparing fallback`, {
+    sessionID,
+    from: state.currentModel,
+    to: nextModel,
+    attempt: state.attemptCount + 1,
+  })
+
+  const failedModel = state.currentModel
+  const now = Date.now()
+
+  state.fallbackIndex = fallbackModels.indexOf(nextModel)
+  state.failedModels.set(failedModel, now)
+  state.attemptCount++
+  state.currentModel = nextModel
+  state.pendingFallbackModel = nextModel
+
+  return { success: true, newModel: nextModel }
+}
--- a/src/hooks/runtime-fallback/hook.ts
+++ b/src/hooks/runtime-fallback/hook.ts
@@ -0,0 +1,67 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import type { HookDeps, RuntimeFallbackHook, RuntimeFallbackOptions } from "./types"
+import { DEFAULT_CONFIG, HOOK_NAME } from "./constants"
+import { log } from "../../shared/logger"
+import { loadPluginConfig } from "../../plugin-config"
+import { createAutoRetryHelpers } from "./auto-retry"
+import { createEventHandler } from "./event-handler"
+import { createMessageUpdateHandler } from "./message-update-handler"
+import { createChatMessageHandler } from "./chat-message-handler"
+
+export function createRuntimeFallbackHook(
+  ctx: PluginInput,
+  options?: RuntimeFallbackOptions
+): RuntimeFallbackHook {
+  const config = {
+    enabled: options?.config?.enabled ?? DEFAULT_CONFIG.enabled,
+    retry_on_errors: options?.config?.retry_on_errors ?? DEFAULT_CONFIG.retry_on_errors,
+    max_fallback_attempts: options?.config?.max_fallback_attempts ?? DEFAULT_CONFIG.max_fallback_attempts,
+    cooldown_seconds: options?.config?.cooldown_seconds ?? DEFAULT_CONFIG.cooldown_seconds,
+    timeout_seconds: options?.config?.timeout_seconds ?? DEFAULT_CONFIG.timeout_seconds,
+    notify_on_fallback: options?.config?.notify_on_fallback ?? DEFAULT_CONFIG.notify_on_fallback,
+  }
+
+  let pluginConfig = options?.pluginConfig
+  if (!pluginConfig) {
+    try {
+      pluginConfig = loadPluginConfig(ctx.directory, ctx)
+    } catch {
+      log(`[${HOOK_NAME}] Plugin config not available`)
+    }
+  }
+
+  const deps: HookDeps = {
+    ctx,
+    config,
+    options,
+    pluginConfig,
+    sessionStates: new Map(),
+    sessionLastAccess: new Map(),
+    sessionRetryInFlight: new Set(),
+    sessionAwaitingFallbackResult: new Set(),
+    sessionFallbackTimeouts: new Map(),
+  }
+
+  const helpers = createAutoRetryHelpers(deps)
+  const baseEventHandler = createEventHandler(deps, helpers)
+  const messageUpdateHandler = createMessageUpdateHandler(deps, helpers)
+  const chatMessageHandler = createChatMessageHandler(deps)
+
+  const cleanupInterval = setInterval(helpers.cleanupStaleSessions, 5 * 60 * 1000)
+  cleanupInterval.unref()
+
+  const eventHandler = async ({ event }: { event: { type: string; properties?: unknown } }) => {
+    if (event.type === "message.updated") {
+      if (!config.enabled) return
+      const props = event.properties as Record<string, unknown> | undefined
+      await messageUpdateHandler(props)
+      return
+    }
+    await baseEventHandler({ event })
+  }
+
+  return {
+    event: eventHandler,
+    "chat.message": chatMessageHandler,
+  } as RuntimeFallbackHook
+}
--- a/src/hooks/runtime-fallback/index.test.ts
+++ b/src/hooks/runtime-fallback/index.test.ts
--- a/src/hooks/runtime-fallback/index.ts
+++ b/src/hooks/runtime-fallback/index.ts
@@ -0,0 +1,2 @@
+export { createRuntimeFallbackHook } from "./hook"
+export type { RuntimeFallbackHook, RuntimeFallbackOptions } from "./types"
--- a/src/hooks/runtime-fallback/message-update-handler.ts
+++ b/src/hooks/runtime-fallback/message-update-handler.ts
@@ -0,0 +1,216 @@
+import type { HookDeps } from "./types"
+import type { AutoRetryHelpers } from "./auto-retry"
+import { HOOK_NAME } from "./constants"
+import { log } from "../../shared/logger"
+import { extractStatusCode, extractErrorName, classifyErrorType, isRetryableError, extractAutoRetrySignal, containsErrorContent } from "./error-classifier"
+import { createFallbackState, prepareFallback } from "./fallback-state"
+import { getFallbackModelsForSession } from "./fallback-models"
+
+export function hasVisibleAssistantResponse(extractAutoRetrySignalFn: typeof extractAutoRetrySignal) {
+  return async (
+    ctx: HookDeps["ctx"],
+    sessionID: string,
+    _info: Record<string, unknown> | undefined,
+  ): Promise<boolean> => {
+    try {
+      const messagesResp = await ctx.client.session.messages({
+        path: { id: sessionID },
+        query: { directory: ctx.directory },
+      })
+
+      const msgs = (messagesResp as {
+        data?: Array<{
+          info?: Record<string, unknown>
+          parts?: Array<{ type?: string; text?: string }>
+        }>
+      }).data
+
+      if (!msgs || msgs.length === 0) return false
+
+      const lastAssistant = [...msgs].reverse().find((m) => m.info?.role === "assistant")
+      if (!lastAssistant) return false
+      if (lastAssistant.info?.error) return false
+
+      const parts = lastAssistant.parts ??
+        (lastAssistant.info?.parts as Array<{ type?: string; text?: string }> | undefined)
+
+      const textFromParts = (parts ?? [])
+        .filter((p) => p.type === "text" && typeof p.text === "string")
+        .map((p) => p.text!.trim())
+        .filter((text) => text.length > 0)
+        .join("\n")
+
+      if (!textFromParts) return false
+      if (extractAutoRetrySignalFn({ message: textFromParts })) return false
+
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+export function createMessageUpdateHandler(deps: HookDeps, helpers: AutoRetryHelpers) {
+  const { ctx, config, pluginConfig, sessionStates, sessionLastAccess, sessionRetryInFlight, sessionAwaitingFallbackResult } = deps
+  const checkVisibleResponse = hasVisibleAssistantResponse(extractAutoRetrySignal)
+
+  return async (props: Record<string, unknown> | undefined) => {
+    const info = props?.info as Record<string, unknown> | undefined
+    const sessionID = info?.sessionID as string | undefined
+    const retrySignalResult = extractAutoRetrySignal(info)
+    const retrySignal = retrySignalResult?.signal
+    const timeoutEnabled = config.timeout_seconds > 0
+    const parts = props?.parts as Array<{ type?: string; text?: string }> | undefined
+    const errorContentResult = containsErrorContent(parts)
+    const error = info?.error ?? 
+      (retrySignal && timeoutEnabled ? { name: "ProviderRateLimitError", message: retrySignal } : undefined) ??
+      (errorContentResult.hasError ? { name: "MessageContentError", message: errorContentResult.errorMessage || "Message contains error content" } : undefined)
+    const role = info?.role as string | undefined
+    const model = info?.model as string | undefined
+
+    if (sessionID && role === "assistant" && !error) {
+      if (!sessionAwaitingFallbackResult.has(sessionID)) {
+        return
+      }
+
+      const hasVisible = await checkVisibleResponse(ctx, sessionID, info)
+      if (!hasVisible) {
+        log(`[${HOOK_NAME}] Assistant update observed without visible final response; keeping fallback timeout`, {
+          sessionID,
+          model,
+        })
+        return
+      }
+
+      sessionAwaitingFallbackResult.delete(sessionID)
+      helpers.clearSessionFallbackTimeout(sessionID)
+      const state = sessionStates.get(sessionID)
+      if (state?.pendingFallbackModel) {
+        state.pendingFallbackModel = undefined
+      }
+      log(`[${HOOK_NAME}] Assistant response observed; cleared fallback timeout`, { sessionID, model })
+      return
+    }
+
+    if (sessionID && role === "assistant" && error) {
+      sessionAwaitingFallbackResult.delete(sessionID)
+      if (sessionRetryInFlight.has(sessionID) && !retrySignal) {
+        log(`[${HOOK_NAME}] message.updated fallback skipped (retry in flight)`, { sessionID })
+        return
+      }
+
+      if (retrySignal && sessionRetryInFlight.has(sessionID) && timeoutEnabled) {
+        log(`[${HOOK_NAME}] Overriding in-flight retry due to provider auto-retry signal`, {
+          sessionID,
+          model,
+        })
+        await helpers.abortSessionRequest(sessionID, "message.updated.retry-signal")
+        sessionRetryInFlight.delete(sessionID)
+      }
+
+      if (retrySignal && timeoutEnabled) {
+        log(`[${HOOK_NAME}] Detected provider auto-retry signal`, { sessionID, model })
+      }
+
+      if (!retrySignal) {
+        helpers.clearSessionFallbackTimeout(sessionID)
+      }
+
+      log(`[${HOOK_NAME}] message.updated with assistant error`, {
+        sessionID,
+        model,
+        statusCode: extractStatusCode(error, config.retry_on_errors),
+        errorName: extractErrorName(error),
+        errorType: classifyErrorType(error),
+      })
+
+      if (!isRetryableError(error, config.retry_on_errors)) {
+        log(`[${HOOK_NAME}] message.updated error not retryable, skipping fallback`, {
+          sessionID,
+          statusCode: extractStatusCode(error, config.retry_on_errors),
+          errorName: extractErrorName(error),
+          errorType: classifyErrorType(error),
+        })
+        return
+      }
+
+      let state = sessionStates.get(sessionID)
+      const agent = info?.agent as string | undefined
+      const resolvedAgent = await helpers.resolveAgentForSessionFromContext(sessionID, agent)
+      const fallbackModels = getFallbackModelsForSession(sessionID, resolvedAgent, pluginConfig)
+
+      if (fallbackModels.length === 0) {
+        return
+      }
+
+      if (!state) {
+        let initialModel = model
+        if (!initialModel) {
+          const detectedAgent = resolvedAgent
+          const agentConfig = detectedAgent
+            ? pluginConfig?.agents?.[detectedAgent as keyof typeof pluginConfig.agents]
+            : undefined
+          const agentModel = agentConfig?.model as string | undefined
+          if (agentModel) {
+            log(`[${HOOK_NAME}] Derived model from agent config for message.updated`, {
+              sessionID,
+              agent: detectedAgent,
+              model: agentModel,
+            })
+            initialModel = agentModel
+          }
+        }
+
+        if (!initialModel) {
+          log(`[${HOOK_NAME}] message.updated missing model info, cannot fallback`, {
+            sessionID,
+            errorName: extractErrorName(error),
+            errorType: classifyErrorType(error),
+          })
+          return
+        }
+
+        state = createFallbackState(initialModel)
+        sessionStates.set(sessionID, state)
+        sessionLastAccess.set(sessionID, Date.now())
+      } else {
+        sessionLastAccess.set(sessionID, Date.now())
+
+        if (state.pendingFallbackModel) {
+          if (retrySignal && timeoutEnabled) {
+            log(`[${HOOK_NAME}] Clearing pending fallback due to provider auto-retry signal`, {
+              sessionID,
+              pendingFallbackModel: state.pendingFallbackModel,
+            })
+            state.pendingFallbackModel = undefined
+          } else {
+          log(`[${HOOK_NAME}] message.updated fallback skipped (pending fallback in progress)`, {
+            sessionID,
+            pendingFallbackModel: state.pendingFallbackModel,
+          })
+          return
+          }
+        }
+      }
+
+      const result = prepareFallback(sessionID, state, fallbackModels, config)
+
+      if (result.success && config.notify_on_fallback) {
+        await deps.ctx.client.tui
+          .showToast({
+            body: {
+              title: "Model Fallback",
+              message: `Switching to ${result.newModel?.split("/").pop() || result.newModel} for next request`,
+              variant: "warning",
+              duration: 5000,
+            },
+          })
+          .catch(() => {})
+      }
+
+      if (result.success && result.newModel) {
+        await helpers.autoRetryWithFallback(sessionID, result.newModel, resolvedAgent, "message.updated")
+      }
+    }
+  }
+}
--- a/src/hooks/runtime-fallback/types.ts
+++ b/src/hooks/runtime-fallback/types.ts
@@ -0,0 +1,41 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import type { RuntimeFallbackConfig, OhMyOpenCodeConfig } from "../../config"
+
+export interface FallbackState {
+  originalModel: string
+  currentModel: string
+  fallbackIndex: number
+  failedModels: Map<string, number>
+  attemptCount: number
+  pendingFallbackModel?: string
+}
+
+export interface FallbackResult {
+  success: boolean
+  newModel?: string
+  error?: string
+  maxAttemptsReached?: boolean
+}
+
+export interface RuntimeFallbackOptions {
+  config?: RuntimeFallbackConfig
+  pluginConfig?: OhMyOpenCodeConfig
+  session_timeout_ms?: number
+}
+
+export interface RuntimeFallbackHook {
+  event: (input: { event: { type: string; properties?: unknown } }) => Promise<void>
+  "chat.message"?: (input: { sessionID: string; agent?: string; model?: { providerID: string; modelID: string } }, output: { message: { model?: { providerID: string; modelID: string } }; parts?: Array<{ type: string; text?: string }> }) => Promise<void>
+}
+
+export interface HookDeps {
+  ctx: PluginInput
+  config: Required<RuntimeFallbackConfig>
+  options: RuntimeFallbackOptions | undefined
+  pluginConfig: OhMyOpenCodeConfig | undefined
+  sessionStates: Map<string, FallbackState>
+  sessionLastAccess: Map<string, number>
+  sessionRetryInFlight: Set<string>
+  sessionAwaitingFallbackResult: Set<string>
+  sessionFallbackTimeouts: Map<string, ReturnType<typeof setTimeout>>
+}
--- a/src/hooks/write-existing-file-guard/hook.ts
+++ b/src/hooks/write-existing-file-guard/hook.ts
@@ -1,50 +1,262 @@
 import type { Hooks, PluginInput } from "@opencode-ai/plugin"

-import { existsSync } from "fs"
-import { resolve, isAbsolute, join, normalize, sep } from "path"
+import { existsSync, realpathSync } from "fs"
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "path"

 import { log } from "../../shared"

+type GuardArgs = {
+  filePath?: string
+  path?: string
+  file_path?: string
+  overwrite?: boolean | string
+}
+
+const MAX_TRACKED_SESSIONS = 256
+export const MAX_TRACKED_PATHS_PER_SESSION = 1024
+const OUTSIDE_SESSION_MESSAGE = "Path must be inside session directory."
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined
+  }
+
+  return value as Record<string, unknown>
+}
+
+function getPathFromArgs(args: GuardArgs | undefined): string | undefined {
+  return args?.filePath ?? args?.path ?? args?.file_path
+}
+
+function resolveInputPath(ctx: PluginInput, inputPath: string): string {
+  return normalize(isAbsolute(inputPath) ? inputPath : resolve(ctx.directory, inputPath))
+}
+
+function isPathInsideDirectory(pathToCheck: string, directory: string): boolean {
+  const relativePath = relative(directory, pathToCheck)
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+}
+
+function toCanonicalPath(absolutePath: string): string {
+  let canonicalPath = absolutePath
+
+  if (existsSync(absolutePath)) {
+    try {
+      canonicalPath = realpathSync.native(absolutePath)
+    } catch {
+      canonicalPath = absolutePath
+    }
+  } else {
+    const absoluteDir = dirname(absolutePath)
+    const resolvedDir = existsSync(absoluteDir) ? realpathSync.native(absoluteDir) : absoluteDir
+    canonicalPath = join(resolvedDir, basename(absolutePath))
+  }
+
+  // Preserve canonical casing from the filesystem to avoid collapsing distinct
+  // files on case-sensitive volumes (supported on all major OSes).
+  return normalize(canonicalPath)
+}
+
+function isOverwriteEnabled(value: boolean | string | undefined): boolean {
+  if (value === true) {
+    return true
+  }
+
+  if (typeof value === "string") {
+    return value.toLowerCase() === "true"
+  }
+
+  return false
+}
+
 export function createWriteExistingFileGuardHook(ctx: PluginInput): Hooks {
-  return {
-    "tool.execute.before": async (input, output) => {
-      const toolName = input.tool?.toLowerCase()
-      if (toolName !== "write") {
+  const readPermissionsBySession = new Map<string, Set<string>>()
+  const sessionLastAccess = new Map<string, number>()
+  const canonicalSessionRoot = toCanonicalPath(resolveInputPath(ctx, ctx.directory))
+  const sisyphusRoot = join(canonicalSessionRoot, ".sisyphus") + sep
+
+  const touchSession = (sessionID: string): void => {
+    sessionLastAccess.set(sessionID, Date.now())
+  }
+
+  const evictLeastRecentlyUsedSession = (): void => {
+    let oldestSessionID: string | undefined
+    let oldestSeen = Number.POSITIVE_INFINITY
+
+    for (const [sessionID, lastSeen] of sessionLastAccess.entries()) {
+      if (lastSeen < oldestSeen) {
+        oldestSeen = lastSeen
+        oldestSessionID = sessionID
+      }
+    }
+
+    if (!oldestSessionID) {
+      return
+    }
+
+    readPermissionsBySession.delete(oldestSessionID)
+    sessionLastAccess.delete(oldestSessionID)
+  }
+
+  const ensureSessionReadSet = (sessionID: string): Set<string> => {
+    let readSet = readPermissionsBySession.get(sessionID)
+    if (!readSet) {
+      if (readPermissionsBySession.size >= MAX_TRACKED_SESSIONS) {
+        evictLeastRecentlyUsedSession()
+      }
+
+      readSet = new Set<string>()
+      readPermissionsBySession.set(sessionID, readSet)
+    }
+
+    touchSession(sessionID)
+    return readSet
+  }
+
+  const trimSessionReadSet = (readSet: Set<string>): void => {
+    while (readSet.size > MAX_TRACKED_PATHS_PER_SESSION) {
+      const oldestPath = readSet.values().next().value
+      if (!oldestPath) {
        return
      }

-      const args = output.args as
-        | { filePath?: string; path?: string; file_path?: string }
-        | undefined
-      const filePath = args?.filePath ?? args?.path ?? args?.file_path
+      readSet.delete(oldestPath)
+    }
+  }
+
+  const registerReadPermission = (sessionID: string, canonicalPath: string): void => {
+    const readSet = ensureSessionReadSet(sessionID)
+    if (readSet.has(canonicalPath)) {
+      readSet.delete(canonicalPath)
+    }
+
+    readSet.add(canonicalPath)
+    trimSessionReadSet(readSet)
+  }
+
+  const consumeReadPermission = (sessionID: string, canonicalPath: string): boolean => {
+    const readSet = readPermissionsBySession.get(sessionID)
+    if (!readSet || !readSet.has(canonicalPath)) {
+      return false
+    }
+
+    readSet.delete(canonicalPath)
+    touchSession(sessionID)
+    return true
+  }
+
+  const invalidateOtherSessions = (canonicalPath: string, writingSessionID?: string): void => {
+    for (const [sessionID, readSet] of readPermissionsBySession.entries()) {
+      if (writingSessionID && sessionID === writingSessionID) {
+        continue
+      }
+
+      readSet.delete(canonicalPath)
+    }
+  }
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      const toolName = input.tool?.toLowerCase()
+      if (toolName !== "write" && toolName !== "read") {
+        return
+      }
+
+      const argsRecord = asRecord(output.args)
+      const args = argsRecord as GuardArgs | undefined
+      const filePath = getPathFromArgs(args)
      if (!filePath) {
        return
      }

-      const resolvedPath = normalize(
-        isAbsolute(filePath) ? filePath : resolve(ctx.directory, filePath)
-      )
+      const resolvedPath = resolveInputPath(ctx, filePath)
+      const canonicalPath = toCanonicalPath(resolvedPath)
+      const isInsideSessionDirectory = isPathInsideDirectory(canonicalPath, canonicalSessionRoot)

-      if (existsSync(resolvedPath)) {
-        const sisyphusRoot = join(ctx.directory, ".sisyphus") + sep
-        const isSisyphusMarkdown =
-          resolvedPath.startsWith(sisyphusRoot) && resolvedPath.endsWith(".md")
-        if (isSisyphusMarkdown) {
-          log("[write-existing-file-guard] Allowing .sisyphus/*.md overwrite", {
-            sessionID: input.sessionID,
-            filePath,
-          })
+      if (!isInsideSessionDirectory) {
+        if (toolName === "read") {
          return
        }

-        log("[write-existing-file-guard] Blocking write to existing file", {
+        log("[write-existing-file-guard] Blocking write outside session directory", {
          sessionID: input.sessionID,
          filePath,
          resolvedPath,
        })
-
-        throw new Error("File already exists. Use edit tool instead.")
+        throw new Error(OUTSIDE_SESSION_MESSAGE)
      }
+
+      if (toolName === "read") {
+        if (!existsSync(resolvedPath) || !input.sessionID) {
+          return
+        }
+
+        registerReadPermission(input.sessionID, canonicalPath)
+        return
+      }
+
+      const overwriteEnabled = isOverwriteEnabled(args?.overwrite)
+
+      if (argsRecord && "overwrite" in argsRecord) {
+        // Intentionally mutate output args so overwrite bypass remains hook-only.
+        delete argsRecord.overwrite
+      }
+
+      if (!existsSync(resolvedPath)) {
+        return
+      }
+
+      const isSisyphusPath = canonicalPath.startsWith(sisyphusRoot)
+      if (isSisyphusPath) {
+        log("[write-existing-file-guard] Allowing .sisyphus/** overwrite", {
+          sessionID: input.sessionID,
+          filePath,
+        })
+        invalidateOtherSessions(canonicalPath, input.sessionID)
+        return
+      }
+
+      if (overwriteEnabled) {
+        log("[write-existing-file-guard] Allowing overwrite flag bypass", {
+          sessionID: input.sessionID,
+          filePath,
+          resolvedPath,
+        })
+        invalidateOtherSessions(canonicalPath, input.sessionID)
+        return
+      }
+
+      if (input.sessionID && consumeReadPermission(input.sessionID, canonicalPath)) {
+        log("[write-existing-file-guard] Allowing overwrite after read", {
+          sessionID: input.sessionID,
+          filePath,
+          resolvedPath,
+        })
+        invalidateOtherSessions(canonicalPath, input.sessionID)
+        return
+      }
+
+      log("[write-existing-file-guard] Blocking write to existing file", {
+        sessionID: input.sessionID,
+        filePath,
+        resolvedPath,
+      })
+
+      throw new Error("File already exists. Use edit tool instead.")
+    },
+    event: async ({ event }: { event: { type: string; properties?: unknown } }) => {
+      if (event.type !== "session.deleted") {
+        return
+      }
+
+      const props = event.properties as { info?: { id?: string } } | undefined
+      const sessionID = props?.info?.id
+      if (!sessionID) {
+        return
+      }
+
+      readPermissionsBySession.delete(sessionID)
+      sessionLastAccess.delete(sessionID)
    },
  }
 }
--- a/src/hooks/write-existing-file-guard/index.test.ts
+++ b/src/hooks/write-existing-file-guard/index.test.ts
@@ -1,305 +1,551 @@
-import { describe, test, expect, beforeEach, afterEach } from "bun:test"
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+
+import { MAX_TRACKED_PATHS_PER_SESSION } from "./hook"
 import { createWriteExistingFileGuardHook } from "./index"
-import * as fs from "fs"
-import * as path from "path"
-import * as os from "os"
+
+const BLOCK_MESSAGE = "File already exists. Use edit tool instead."
+const OUTSIDE_SESSION_MESSAGE = "Path must be inside session directory."
+
+type Hook = ReturnType<typeof createWriteExistingFileGuardHook>
+
+function isCaseInsensitiveFilesystem(directory: string): boolean {
+  const probeName = `CaseProbe_${Date.now()}_A.txt`
+  const upperPath = join(directory, probeName)
+  const lowerPath = join(directory, probeName.toLowerCase())
+
+  writeFileSync(upperPath, "probe")
+  try {
+    return existsSync(lowerPath)
+  } finally {
+    rmSync(upperPath, { force: true })
+  }
+}

 describe("createWriteExistingFileGuardHook", () => {
-  let tempDir: string
-  let ctx: { directory: string }
-  let hook: ReturnType<typeof createWriteExistingFileGuardHook>
+  let tempDir = ""
+  let hook: Hook
+  let callCounter = 0
+
+  const createFile = (relativePath: string, content = "existing content"): string => {
+    const absolutePath = join(tempDir, relativePath)
+    mkdirSync(dirname(absolutePath), { recursive: true })
+    writeFileSync(absolutePath, content)
+    return absolutePath
+  }
+
+  const invoke = async (args: {
+    tool: string
+    sessionID?: string
+    outputArgs: Record<string, unknown>
+  }): Promise<{ args: Record<string, unknown> }> => {
+    callCounter += 1
+    const output = { args: args.outputArgs }
+
+    await hook["tool.execute.before"]?.(
+      {
+        tool: args.tool,
+        sessionID: args.sessionID ?? "ses_default",
+        callID: `call_${callCounter}`,
+      } as never,
+      output as never
+    )
+
+    return output
+  }
+
+  const emitSessionDeleted = async (sessionID: string): Promise<void> => {
+    await hook.event?.({ event: { type: "session.deleted", properties: { info: { id: sessionID } } } })
+  }

  beforeEach(() => {
-    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "write-guard-test-"))
-    ctx = { directory: tempDir }
-    hook = createWriteExistingFileGuardHook(ctx as any)
+    tempDir = mkdtempSync(join(tmpdir(), "write-existing-file-guard-"))
+    hook = createWriteExistingFileGuardHook({ directory: tempDir } as never)
+    callCounter = 0
  })

  afterEach(() => {
-    fs.rmSync(tempDir, { recursive: true, force: true })
+    rmSync(tempDir, { recursive: true, force: true })
  })

-  describe("tool.execute.before", () => {
-    test("allows write to non-existing file", async () => {
-      //#given
-      const nonExistingFile = path.join(tempDir, "new-file.txt")
-      const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-      const output = { args: { filePath: nonExistingFile, content: "hello" } }
+  test("#given non-existing file #when write executes #then allows", async () => {
+    await expect(
+      invoke({
+        tool: "write",
+        outputArgs: { filePath: join(tempDir, "new-file.txt"), content: "new content" },
+      })
+    ).resolves.toBeDefined()
+  })

-      //#when
-      const result = hook["tool.execute.before"]?.(input as any, output as any)
+  test("#given existing file without read or overwrite #when write executes #then blocks", async () => {
+    const existingFile = createFile("existing.txt")

-      //#then
-      await expect(result).resolves.toBeUndefined()
+    await expect(
+      invoke({
+        tool: "write",
+        outputArgs: { filePath: existingFile, content: "new content" },
+      })
+    ).rejects.toThrow(BLOCK_MESSAGE)
+  })
+
+  test("#given same-session read #when write executes #then allows once and consumes permission", async () => {
+    const existingFile = createFile("consume-once.txt")
+    const sessionID = "ses_consume"
+
+    await invoke({
+      tool: "read",
+      sessionID,
+      outputArgs: { filePath: existingFile },
    })

-    test("blocks write to existing file", async () => {
-      //#given
-      const existingFile = path.join(tempDir, "existing-file.txt")
-      fs.writeFileSync(existingFile, "existing content")
-      const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-      const output = { args: { filePath: existingFile, content: "new content" } }
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: existingFile, content: "first overwrite" },
+      })
+    ).resolves.toBeDefined()

-      //#when
-      const result = hook["tool.execute.before"]?.(input as any, output as any)
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: existingFile, content: "second overwrite" },
+      })
+    ).rejects.toThrow(BLOCK_MESSAGE)
+  })

-      //#then
-      await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
+  test("#given same-session concurrent writes #when only one read permission exists #then allows only one write", async () => {
+    const existingFile = createFile("concurrent-consume.txt")
+    const sessionID = "ses_concurrent"
+
+    await invoke({
+      tool: "read",
+      sessionID,
+      outputArgs: { filePath: existingFile },
    })

-    test("blocks write tool (lowercase) to existing file", async () => {
-      //#given
-      const existingFile = path.join(tempDir, "existing-file.txt")
-      fs.writeFileSync(existingFile, "existing content")
-      const input = { tool: "write", sessionID: "ses_1", callID: "call_1" }
-      const output = { args: { filePath: existingFile, content: "new content" } }
+    const results = await Promise.allSettled([
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: existingFile, content: "first attempt" },
+      }),
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: existingFile, content: "second attempt" },
+      }),
+    ])

-      //#when
-      const result = hook["tool.execute.before"]?.(input as any, output as any)
+    const successCount = results.filter((result) => result.status === "fulfilled").length
+    const failures = results.filter(
+      (result): result is PromiseRejectedResult => result.status === "rejected"
+    )

-      //#then
-      await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
+    expect(successCount).toBe(1)
+    expect(failures).toHaveLength(1)
+    expect(String(failures[0]?.reason)).toContain(BLOCK_MESSAGE)
+  })
+
+  test("#given read in another session #when write executes #then blocks", async () => {
+    const existingFile = createFile("cross-session.txt")
+
+    await invoke({
+      tool: "read",
+      sessionID: "ses_reader",
+      outputArgs: { filePath: existingFile },
    })

-    test("ignores non-write tools", async () => {
-      //#given
-      const existingFile = path.join(tempDir, "existing-file.txt")
-      fs.writeFileSync(existingFile, "existing content")
-      const input = { tool: "Edit", sessionID: "ses_1", callID: "call_1" }
-      const output = { args: { filePath: existingFile, content: "new content" } }
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID: "ses_writer",
+        outputArgs: { filePath: existingFile, content: "new content" },
+      })
+    ).rejects.toThrow(BLOCK_MESSAGE)
+  })

-      //#when
-      const result = hook["tool.execute.before"]?.(input as any, output as any)
+  test("#given overwrite true boolean #when write executes #then bypasses guard and strips overwrite", async () => {
+    const existingFile = createFile("overwrite-boolean.txt")

-      //#then
-      await expect(result).resolves.toBeUndefined()
+    const output = await invoke({
+      tool: "write",
+      outputArgs: {
+        filePath: existingFile,
+        content: "new content",
+        overwrite: true,
+      },
    })

-    test("ignores tools without any file path arg", async () => {
-      //#given
-      const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-      const output = { args: { command: "ls" } }
+    expect(output.args.overwrite).toBeUndefined()
+  })

-      //#when
-      const result = hook["tool.execute.before"]?.(input as any, output as any)
+  test("#given overwrite true string #when write executes #then bypasses guard and strips overwrite", async () => {
+    const existingFile = createFile("overwrite-string.txt")

-      //#then
-      await expect(result).resolves.toBeUndefined()
+    const output = await invoke({
+      tool: "write",
+      outputArgs: {
+        filePath: existingFile,
+        content: "new content",
+        overwrite: "true",
+      },
    })

-    describe("alternative arg names", () => {
-      test("blocks write using 'path' arg to existing file", async () => {
-        //#given
-        const existingFile = path.join(tempDir, "existing-file.txt")
-        fs.writeFileSync(existingFile, "existing content")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { path: existingFile, content: "new content" } }
+    expect(output.args.overwrite).toBeUndefined()
+  })

-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
+  test("#given overwrite falsy values #when write executes #then does not bypass guard", async () => {
+    const existingFile = createFile("overwrite-falsy.txt")

-        //#then
-        await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
-      })
+    for (const overwrite of [false, "false"] as const) {
+      await expect(
+        invoke({
+          tool: "write",
+          outputArgs: {
+            filePath: existingFile,
+            content: "new content",
+            overwrite,
+          },
+        })
+      ).rejects.toThrow(BLOCK_MESSAGE)
+    }
+  })

-      test("blocks write using 'file_path' arg to existing file", async () => {
-        //#given
-        const existingFile = path.join(tempDir, "existing-file.txt")
-        fs.writeFileSync(existingFile, "existing content")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { file_path: existingFile, content: "new content" } }
+  test("#given two sessions read same file #when one writes #then other session is invalidated", async () => {
+    const existingFile = createFile("invalidate.txt")

-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
-      })
-
-      test("allows write using 'path' arg to non-existing file", async () => {
-        //#given
-        const nonExistingFile = path.join(tempDir, "new-file.txt")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { path: nonExistingFile, content: "hello" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).resolves.toBeUndefined()
-      })
-
-      test("allows write using 'file_path' arg to non-existing file", async () => {
-        //#given
-        const nonExistingFile = path.join(tempDir, "new-file.txt")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { file_path: nonExistingFile, content: "hello" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).resolves.toBeUndefined()
-      })
+    await invoke({
+      tool: "read",
+      sessionID: "ses_a",
+      outputArgs: { filePath: existingFile },
+    })
+    await invoke({
+      tool: "read",
+      sessionID: "ses_b",
+      outputArgs: { filePath: existingFile },
    })

-    describe("relative path resolution using ctx.directory", () => {
-      test("blocks write to existing file using relative path", async () => {
-        //#given
-        const existingFile = path.join(tempDir, "existing-file.txt")
-        fs.writeFileSync(existingFile, "existing content")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: "existing-file.txt", content: "new content" } }
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID: "ses_b",
+        outputArgs: { filePath: existingFile, content: "updated by B" },
+      })
+    ).resolves.toBeDefined()

-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID: "ses_a",
+        outputArgs: { filePath: existingFile, content: "updated by A" },
+      })
+    ).rejects.toThrow(BLOCK_MESSAGE)
+  })

-        //#then
-        await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
+  test("#given existing file under .sisyphus #when write executes #then always allows", async () => {
+    const existingFile = createFile(".sisyphus/plans/plan.txt")
+
+    await expect(
+      invoke({
+        tool: "write",
+        outputArgs: { filePath: existingFile, content: "new plan" },
+      })
+    ).resolves.toBeDefined()
+  })
+
+  test("#given file arg variants #when read then write executes #then supports all variants", async () => {
+    const existingFile = createFile("variants.txt")
+    const variants: Array<"filePath" | "path" | "file_path"> = [
+      "filePath",
+      "path",
+      "file_path",
+    ]
+
+    for (const variant of variants) {
+      const sessionID = `ses_${variant}`
+      await invoke({
+        tool: "read",
+        sessionID,
+        outputArgs: { [variant]: existingFile },
      })

-      test("allows write to non-existing file using relative path", async () => {
-        //#given
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: "new-file.txt", content: "hello" } }
+      await expect(
+        invoke({
+          tool: "write",
+          sessionID,
+          outputArgs: { [variant]: existingFile, content: `overwrite via ${variant}` },
+        })
+      ).resolves.toBeDefined()
+    }
+  })

-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).resolves.toBeUndefined()
+  test("#given tools without file path arg #when write and read execute #then ignores safely", async () => {
+    await expect(
+      invoke({
+        tool: "write",
+        outputArgs: { content: "no path" },
      })
+    ).resolves.toBeDefined()

-      test("blocks write to nested relative path when file exists", async () => {
-        //#given
-        const subDir = path.join(tempDir, "subdir")
-        fs.mkdirSync(subDir)
-        const existingFile = path.join(subDir, "existing.txt")
-        fs.writeFileSync(existingFile, "existing content")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: "subdir/existing.txt", content: "new content" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
+    await expect(
+      invoke({
+        tool: "read",
+        outputArgs: {},
      })
+    ).resolves.toBeDefined()
+  })

-      test("uses ctx.directory not process.cwd for relative path resolution", async () => {
-        //#given
-        const existingFile = path.join(tempDir, "test-file.txt")
-        fs.writeFileSync(existingFile, "content")
-        const differentCtx = { directory: tempDir }
-        const differentHook = createWriteExistingFileGuardHook(differentCtx as any)
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: "test-file.txt", content: "new" } }
+  test("#given non-read-write tool #when it executes #then does not grant write permission", async () => {
+    const existingFile = createFile("ignored-tool.txt")
+    const sessionID = "ses_ignored_tool"

-        //#when
-        const result = differentHook["tool.execute.before"]?.(input as any, output as any)
-
-       //#then
-       await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
-     })
-
-    describe(".sisyphus/*.md exception", () => {
-      test("allows write to existing .sisyphus/plans/plan.md", async () => {
-        //#given
-        const sisyphusDir = path.join(tempDir, ".sisyphus", "plans")
-        fs.mkdirSync(sisyphusDir, { recursive: true })
-        const planFile = path.join(sisyphusDir, "plan.md")
-        fs.writeFileSync(planFile, "# Existing Plan")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: planFile, content: "# Updated Plan" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).resolves.toBeUndefined()
-      })
-
-      test("allows write to existing .sisyphus/notes.md", async () => {
-        //#given
-        const sisyphusDir = path.join(tempDir, ".sisyphus")
-        fs.mkdirSync(sisyphusDir, { recursive: true })
-        const notesFile = path.join(sisyphusDir, "notes.md")
-        fs.writeFileSync(notesFile, "# Notes")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: notesFile, content: "# Updated Notes" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).resolves.toBeUndefined()
-      })
-
-      test("allows write to existing .sisyphus/*.md using relative path", async () => {
-        //#given
-        const sisyphusDir = path.join(tempDir, ".sisyphus")
-        fs.mkdirSync(sisyphusDir, { recursive: true })
-        const planFile = path.join(sisyphusDir, "plan.md")
-        fs.writeFileSync(planFile, "# Plan")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: ".sisyphus/plan.md", content: "# Updated" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).resolves.toBeUndefined()
-      })
-
-      test("blocks write to existing .sisyphus/file.txt (non-markdown)", async () => {
-        //#given
-        const sisyphusDir = path.join(tempDir, ".sisyphus")
-        fs.mkdirSync(sisyphusDir, { recursive: true })
-        const textFile = path.join(sisyphusDir, "file.txt")
-        fs.writeFileSync(textFile, "content")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: textFile, content: "new content" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
-      })
-
-      test("blocks write when .sisyphus is in parent path but not under ctx.directory", async () => {
-        //#given
-        const fakeSisyphusParent = path.join(os.tmpdir(), ".sisyphus", "evil-project")
-        fs.mkdirSync(fakeSisyphusParent, { recursive: true })
-        const evilFile = path.join(fakeSisyphusParent, "plan.md")
-        fs.writeFileSync(evilFile, "# Evil Plan")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: evilFile, content: "# Hacked" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
-
-        // cleanup
-        fs.rmSync(path.join(os.tmpdir(), ".sisyphus"), { recursive: true, force: true })
-      })
-
-      test("blocks write to existing regular file (not in .sisyphus)", async () => {
-        //#given
-        const regularFile = path.join(tempDir, "regular.md")
-        fs.writeFileSync(regularFile, "# Regular")
-        const input = { tool: "Write", sessionID: "ses_1", callID: "call_1" }
-        const output = { args: { filePath: regularFile, content: "# Updated" } }
-
-        //#when
-        const result = hook["tool.execute.before"]?.(input as any, output as any)
-
-        //#then
-        await expect(result).rejects.toThrow("File already exists. Use edit tool instead.")
-      })
+    await invoke({
+      tool: "edit",
+      sessionID,
+      outputArgs: { filePath: existingFile, oldString: "old", newString: "new" },
    })
-   })
-})
+
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: existingFile, content: "should block" },
+      })
+    ).rejects.toThrow(BLOCK_MESSAGE)
+  })
+
+  test("#given relative read and absolute write #when same session writes #then allows", async () => {
+    createFile("relative-absolute.txt")
+    const sessionID = "ses_relative_absolute"
+    const relativePath = "relative-absolute.txt"
+    const absolutePath = resolve(tempDir, relativePath)
+
+    await invoke({
+      tool: "read",
+      sessionID,
+      outputArgs: { filePath: relativePath },
+    })
+
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: absolutePath, content: "updated" },
+      })
+    ).resolves.toBeDefined()
+  })
+
+  test("#given existing file outside session directory #when write executes #then blocks", async () => {
+    const outsideDir = mkdtempSync(join(tmpdir(), "write-existing-file-guard-outside-"))
+
+    try {
+      const outsideFile = join(outsideDir, "outside.txt")
+      writeFileSync(outsideFile, "outside")
+
+      await expect(
+        invoke({
+          tool: "write",
+          outputArgs: { filePath: outsideFile, content: "attempted overwrite" },
+        })
+      ).rejects.toThrow(OUTSIDE_SESSION_MESSAGE)
+    } finally {
+      rmSync(outsideDir, { recursive: true, force: true })
+    }
+  })
+
+  test("#given session read permission #when session deleted #then permission is cleaned up", async () => {
+    const existingFile = createFile("session-cleanup.txt")
+    const sessionID = "ses_cleanup"
+
+    await invoke({
+      tool: "read",
+      sessionID,
+      outputArgs: { filePath: existingFile },
+    })
+
+    await emitSessionDeleted(sessionID)
+
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: existingFile, content: "after cleanup" },
+      })
+    ).rejects.toThrow(BLOCK_MESSAGE)
+  })
+
+  test("#given case-different read path #when writing canonical path #then follows platform behavior", async () => {
+    const canonicalFile = createFile("CaseFile.txt")
+    const lowerCasePath = join(tempDir, "casefile.txt")
+    const sessionID = "ses_case"
+    const isCaseInsensitiveFs = isCaseInsensitiveFilesystem(tempDir)
+
+    await invoke({
+      tool: "read",
+      sessionID,
+      outputArgs: { filePath: lowerCasePath },
+    })
+
+    const writeAttempt = invoke({
+      tool: "write",
+      sessionID,
+      outputArgs: { filePath: canonicalFile, content: "updated" },
+    })
+
+    if (isCaseInsensitiveFs) {
+      await expect(writeAttempt).resolves.toBeDefined()
+      return
+    }
+
+    await expect(writeAttempt).rejects.toThrow(BLOCK_MESSAGE)
+  })
+
+  test("#given read via symlink #when write via real path #then allows overwrite", async () => {
+    const targetFile = createFile("real/target.txt")
+    const symlinkPath = join(tempDir, "linked-target.txt")
+    const sessionID = "ses_symlink"
+
+    try {
+      symlinkSync(targetFile, symlinkPath)
+    } catch (error) {
+      console.warn(
+        "Skipping symlink test: symlinks are not supported or cannot be created in this environment.",
+        error
+      )
+      return
+    }
+
+    await invoke({
+      tool: "read",
+      sessionID,
+      outputArgs: { filePath: symlinkPath },
+    })
+
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: targetFile, content: "updated via symlink read" },
+      })
+    ).resolves.toBeDefined()
+  })
+
+  test("#given session reads beyond path cap #when writing oldest and newest #then only newest is authorized", async () => {
+    const sessionID = "ses_path_cap"
+    const oldestFile = createFile("path-cap/0.txt")
+    let newestFile = oldestFile
+
+    await invoke({
+      tool: "read",
+      sessionID,
+      outputArgs: { filePath: oldestFile },
+    })
+
+    for (let index = 1; index <= MAX_TRACKED_PATHS_PER_SESSION; index += 1) {
+      newestFile = createFile(`path-cap/${index}.txt`)
+      await invoke({
+        tool: "read",
+        sessionID,
+        outputArgs: { filePath: newestFile },
+      })
+    }
+
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: oldestFile, content: "stale write" },
+      })
+    ).rejects.toThrow(BLOCK_MESSAGE)
+
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: newestFile, content: "fresh write" },
+      })
+    ).resolves.toBeDefined()
+  })
+
+  test("#given recently active session #when lru evicts #then keeps recent session permission", async () => {
+    const existingFile = createFile("lru.txt")
+    const hotSession = "ses_hot"
+
+    await invoke({
+      tool: "read",
+      sessionID: hotSession,
+      outputArgs: { filePath: existingFile },
+    })
+
+    for (let index = 0; index < 255; index += 1) {
+      await invoke({
+        tool: "read",
+        sessionID: `ses_${index}`,
+        outputArgs: { filePath: existingFile },
+      })
+    }
+
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, 2))
+
+    await invoke({
+      tool: "read",
+      sessionID: hotSession,
+      outputArgs: { filePath: existingFile },
+    })
+
+    await invoke({
+      tool: "read",
+      sessionID: "ses_overflow",
+      outputArgs: { filePath: existingFile },
+    })
+
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID: hotSession,
+        outputArgs: { filePath: existingFile, content: "hot session write" },
+      })
+    ).resolves.toBeDefined()
+  })
+
+  test("#given session permissions #when session deleted #then subsequent writes are blocked", async () => {
+    const existingFile = createFile("cleanup.txt")
+    const sessionID = "ses_cleanup"
+
+    // establish permission by reading the existing file
+    await invoke({
+      tool: "read",
+      sessionID,
+      outputArgs: { filePath: existingFile },
+    })
+
+    // sanity check: write should be allowed while the session is active
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: existingFile, content: "first write" },
+      })
+    ).resolves.toBeDefined()
+
+    // delete the session to trigger cleanup of any stored permissions/state
+    await invoke({
+      tool: "session.deleted",
+      sessionID,
+      outputArgs: {},
+    })
+
+    // after session deletion, the previous permissions must no longer apply
+    await expect(
+      invoke({
+        tool: "write",
+        sessionID,
+        outputArgs: { filePath: existingFile, content: "second write after delete" },
+      })
+    ).rejects.toThrow(BLOCK_MESSAGE)
+  })
 })
--- a/src/plugin/chat-message.ts
+++ b/src/plugin/chat-message.ts
@@ -54,6 +54,7 @@ export function createChatMessageHandler(args: {
    }

    await hooks.stopContinuationGuard?.["chat.message"]?.(input)
+    await hooks.runtimeFallback?.["chat.message"]?.(input, output)
    await hooks.keywordDetector?.["chat.message"]?.(input, output)
    await hooks.claudeCodeHooks?.["chat.message"]?.(input, output)
    await hooks.autoSlashCommand?.["chat.message"]?.(input, output)
--- a/src/plugin/event.test.ts
+++ b/src/plugin/event.test.ts
@@ -383,3 +383,55 @@ type EventInput = { event: { type: string; properties?: Record<string, unknown>
 		expect(dispatchCalls[1].event.type).toBe("session.idle")
 	})
 })
+
+describe("createEventHandler - event forwarding", () => {
+	it("forwards session.deleted to write-existing-file-guard hook", async () => {
+		//#given
+		const forwardedEvents: EventInput[] = []
+		const disconnectedSessions: string[] = []
+		const deletedSessions: string[] = []
+		const eventHandler = createEventHandler({
+			ctx: {} as never,
+			pluginConfig: {} as never,
+			firstMessageVariantGate: {
+				markSessionCreated: () => {},
+				clear: () => {},
+			},
+			managers: {
+				skillMcpManager: {
+					disconnectSession: async (sessionID: string) => {
+						disconnectedSessions.push(sessionID)
+					},
+				},
+				tmuxSessionManager: {
+					onSessionCreated: async () => {},
+					onSessionDeleted: async ({ sessionID }: { sessionID: string }) => {
+						deletedSessions.push(sessionID)
+					},
+				},
+			} as never,
+			hooks: {
+				writeExistingFileGuard: {
+					event: async (input: EventInput) => {
+						forwardedEvents.push(input)
+					},
+				},
+			} as never,
+		})
+		const sessionID = "ses_forward_delete_event"
+
+		//#when
+		await eventHandler({
+			event: {
+				type: "session.deleted",
+				properties: { info: { id: sessionID } },
+			},
+		})
+
+		//#then
+		expect(forwardedEvents.length).toBe(1)
+		expect(forwardedEvents[0]?.event.type).toBe("session.deleted")
+		expect(disconnectedSessions).toEqual([sessionID])
+		expect(deletedSessions).toEqual([sessionID])
+	})
+})
--- a/src/plugin/event.ts
+++ b/src/plugin/event.ts
@@ -20,16 +20,20 @@ type FirstMessageVariantGate = {
  clear: (sessionID: string) => void
 }

+type EventInput = Parameters<
+  NonNullable<NonNullable<CreatedHooks["writeExistingFileGuard"]>["event"]>
+>[0]
+
 export function createEventHandler(args: {
  ctx: PluginContext
  pluginConfig: OhMyOpenCodeConfig
  firstMessageVariantGate: FirstMessageVariantGate
  managers: Managers
  hooks: CreatedHooks
-}): (input: { event: { type: string; properties?: Record<string, unknown> } }) => Promise<void> {
+}): (input: EventInput) => Promise<void> {
  const { ctx, firstMessageVariantGate, managers, hooks } = args

-  const dispatchToHooks = async (input: { event: { type: string; properties?: Record<string, unknown> } }): Promise<void> => {
+  const dispatchToHooks = async (input: EventInput): Promise<void> => {
    await Promise.resolve(hooks.autoUpdateChecker?.event?.(input))
    await Promise.resolve(hooks.claudeCodeHooks?.event?.(input))
    await Promise.resolve(hooks.backgroundNotificationHook?.event?.(input))
@@ -42,12 +46,14 @@ export function createEventHandler(args: {
    await Promise.resolve(hooks.rulesInjector?.event?.(input))
    await Promise.resolve(hooks.thinkMode?.event?.(input))
    await Promise.resolve(hooks.anthropicContextWindowLimitRecovery?.event?.(input))
+    await Promise.resolve(hooks.runtimeFallback?.event?.(input))
    await Promise.resolve(hooks.agentUsageReminder?.event?.(input))
    await Promise.resolve(hooks.categorySkillReminder?.event?.(input))
-    await Promise.resolve(hooks.interactiveBashSession?.event?.(input))
+    await Promise.resolve(hooks.interactiveBashSession?.event?.(input as EventInput))
    await Promise.resolve(hooks.ralphLoop?.event?.(input))
    await Promise.resolve(hooks.stopContinuationGuard?.event?.(input))
    await Promise.resolve(hooks.compactionTodoPreserver?.event?.(input))
+    await Promise.resolve(hooks.writeExistingFileGuard?.event?.(input))
    await Promise.resolve(hooks.atlasHook?.handler?.(input))
  }

@@ -86,7 +92,7 @@ export function createEventHandler(args: {
        return
      }
      recentSyntheticIdles.set(sessionID, Date.now())
-      await dispatchToHooks(syntheticIdle)
+      await dispatchToHooks(syntheticIdle as EventInput)
    }

    const { event } = input
--- a/src/plugin/hooks/create-session-hooks.ts
+++ b/src/plugin/hooks/create-session-hooks.ts
@@ -24,6 +24,7 @@ import {
  createNoHephaestusNonGptHook,
  createQuestionLabelTruncatorHook,
  createPreemptiveCompactionHook,
+  createRuntimeFallbackHook,
 } from "../../hooks"
 import { createAnthropicEffortHook } from "../../hooks/anthropic-effort"
 import {
@@ -57,6 +58,7 @@ export type SessionHooks = {
  questionLabelTruncator: ReturnType<typeof createQuestionLabelTruncatorHook>
  taskResumeInfo: ReturnType<typeof createTaskResumeInfoHook>
  anthropicEffort: ReturnType<typeof createAnthropicEffortHook> | null
+  runtimeFallback: ReturnType<typeof createRuntimeFallbackHook> | null
 }

 export function createSessionHooks(args: {
@@ -175,6 +177,13 @@ export function createSessionHooks(args: {
    ? safeHook("anthropic-effort", () => createAnthropicEffortHook())
    : null

+  const runtimeFallback = isHookEnabled("runtime-fallback")
+    ? safeHook("runtime-fallback", () =>
+        createRuntimeFallbackHook(ctx, {
+          config: pluginConfig.runtime_fallback,
+          pluginConfig,
+        }))
+    : null
  return {
    contextWindowMonitor,
    preemptiveCompaction,
@@ -198,5 +207,6 @@ export function createSessionHooks(args: {
    questionLabelTruncator,
    taskResumeInfo,
    anthropicEffort,
+    runtimeFallback,
  }
 }
--- a/src/shared/index.ts
+++ b/src/shared/index.ts
@@ -34,6 +34,7 @@ export * from "./system-directive"
 export * from "./agent-tool-restrictions"
 export * from "./model-requirements"
 export * from "./model-resolver"
+export { normalizeFallbackModels } from "./model-resolver"
 export { resolveModelPipeline } from "./model-resolution-pipeline"
 export type {
  ModelResolutionRequest,
@@ -58,3 +59,4 @@ export * from "./normalize-sdk-response"
 export * from "./session-directory-resolver"
 export * from "./prompt-tools"
 export * from "./internal-initiator-marker"
+export { SessionCategoryRegistry } from "./session-category-registry"
--- a/src/shared/model-resolution-pipeline.ts
+++ b/src/shared/model-resolution-pipeline.ts
@@ -7,6 +7,7 @@ export type ModelResolutionRequest = {
  intent?: {
    uiSelectedModel?: string
    userModel?: string
+    userFallbackModels?: string[]
    categoryDefaultModel?: string
  }
  constraints: {
@@ -97,6 +98,42 @@ export function resolveModelPipeline(
    })
  }

+  //#when - user configured fallback_models, try them before hardcoded fallback chain
+  const userFallbackModels = intent?.userFallbackModels
+  if (userFallbackModels && userFallbackModels.length > 0) {
+    if (availableModels.size === 0) {
+      const connectedProviders = constraints.connectedProviders ?? connectedProvidersCache.readConnectedProvidersCache()
+      const connectedSet = connectedProviders ? new Set(connectedProviders) : null
+
+      if (connectedSet !== null) {
+        for (const model of userFallbackModels) {
+          attempted.push(model)
+          const parts = model.split("/")
+          if (parts.length >= 2) {
+            const provider = parts[0]
+            if (connectedSet.has(provider)) {
+              log("Model resolved via user fallback_models (connected provider)", { model })
+              return { model, provenance: "provider-fallback", attempted }
+            }
+          }
+        }
+        log("No connected provider found in user fallback_models, falling through to hardcoded chain")
+      }
+    } else {
+      for (const model of userFallbackModels) {
+        attempted.push(model)
+        const parts = model.split("/")
+        const providerHint = parts.length >= 2 ? [parts[0]] : undefined
+        const match = fuzzyMatchModel(model, availableModels, providerHint)
+        if (match) {
+          log("Model resolved via user fallback_models (availability confirmed)", { model: model, match })
+          return { model: match, provenance: "provider-fallback", attempted }
+        }
+      }
+      log("No available model found in user fallback_models, falling through to hardcoded chain")
+    }
+  }
+
  if (fallbackChain && fallbackChain.length > 0) {
    if (availableModels.size === 0) {
      const connectedProviders = constraints.connectedProviders ?? connectedProvidersCache.readConnectedProvidersCache()
--- a/src/shared/model-resolver.ts
+++ b/src/shared/model-resolver.ts
@@ -22,6 +22,7 @@ export type ModelResolutionResult = {
 export type ExtendedModelResolutionInput = {
 	uiSelectedModel?: string
 	userModel?: string
+	userFallbackModels?: string[]
 	categoryDefaultModel?: string
 	fallbackChain?: FallbackEntry[]
 	availableModels: Set<string>
@@ -44,9 +45,9 @@ export function resolveModel(input: ModelResolutionInput): string | undefined {
 export function resolveModelWithFallback(
 	input: ExtendedModelResolutionInput,
 ): ModelResolutionResult | undefined {
-	const { uiSelectedModel, userModel, categoryDefaultModel, fallbackChain, availableModels, systemDefaultModel } = input
+	const { uiSelectedModel, userModel, userFallbackModels, categoryDefaultModel, fallbackChain, availableModels, systemDefaultModel } = input
 	const resolved = resolveModelPipeline({
-		intent: { uiSelectedModel, userModel, categoryDefaultModel },
+		intent: { uiSelectedModel, userModel, userFallbackModels, categoryDefaultModel },
 		constraints: { availableModels },
 		policy: { fallbackChain, systemDefaultModel },
 	})
@@ -61,3 +62,13 @@ export function resolveModelWithFallback(
 		variant: resolved.variant,
 	}
 }
+
+/**
+ * Normalizes fallback_models config (which can be string or string[]) to string[]
+ * Centralized helper to avoid duplicated normalization logic
+ */
+export function normalizeFallbackModels(models: string | string[] | undefined): string[] | undefined {
+	if (!models) return undefined
+	if (typeof models === "string") return [models]
+	return models
+}
--- a/src/shared/session-category-registry.ts
+++ b/src/shared/session-category-registry.ts
@@ -0,0 +1,53 @@
+/**
+ * Session Category Registry
+ *
+ * Maintains a mapping of session IDs to their assigned categories.
+ * Used by runtime-fallback hook to lookup category-specific fallback_models.
+ */
+
+// Map of sessionID -> category name
+const sessionCategoryMap = new Map<string, string>()
+
+export const SessionCategoryRegistry = {
+  /**
+   * Register a session with its category
+   */
+  register: (sessionID: string, category: string): void => {
+    sessionCategoryMap.set(sessionID, category)
+  },
+
+  /**
+   * Get the category for a session
+   */
+  get: (sessionID: string): string | undefined => {
+    return sessionCategoryMap.get(sessionID)
+  },
+
+  /**
+   * Remove a session from the registry (cleanup)
+   */
+  remove: (sessionID: string): void => {
+    sessionCategoryMap.delete(sessionID)
+  },
+
+  /**
+   * Check if a session is registered
+   */
+  has: (sessionID: string): boolean => {
+    return sessionCategoryMap.has(sessionID)
+  },
+
+  /**
+   * Get the size of the registry (for debugging)
+   */
+  size: (): number => {
+    return sessionCategoryMap.size
+  },
+
+  /**
+   * Clear all entries (use with caution, mainly for testing)
+   */
+  clear: (): void => {
+    sessionCategoryMap.clear()
+  },
+}
--- a/src/tools/background-task/create-background-output.ts
+++ b/src/tools/background-task/create-background-output.ts
@@ -78,7 +78,7 @@ export function createBackgroundOutput(manager: BackgroundOutputManager, client:
        }

        const isActive = task.status === "pending" || task.status === "running"
-        const fullSession = args.full_session ?? isActive
+        const fullSession = args.full_session ?? false
        const includeThinking = isActive || (args.include_thinking ?? false)
        const includeToolResults = isActive || (args.include_tool_results ?? false)

--- a/src/tools/background-task/tools.test.ts
+++ b/src/tools/background-task/tools.test.ts
@@ -232,7 +232,7 @@ describe("background_output full_session", () => {
    expect(output).toContain("Has more: true")
  })

-  test("defaults to full_session when task is running", async () => {
+  test("defaults to compact status when task is running", async () => {
    // #given
    const task = createTask({ status: "running" })
    const manager = createMockManager(task)
@@ -242,6 +242,21 @@ describe("background_output full_session", () => {
    // #when
    const output = await tool.execute({ task_id: "task-1" }, mockContext)

+    // #then
+    expect(output).toContain("# Task Status")
+    expect(output).not.toContain("# Full Session Output")
+  })
+
+  test("returns full session when explicitly requested for running task", async () => {
+    // #given
+    const task = createTask({ status: "running" })
+    const manager = createMockManager(task)
+    const client = createMockClient({})
+    const tool = createBackgroundOutput(manager, client)
+
+    // #when
+    const output = await tool.execute({ task_id: "task-1", full_session: true }, mockContext)
+
    // #then
    expect(output).toContain("# Full Session Output")
  })
--- a/src/tools/delegate-task/background-task.ts
+++ b/src/tools/delegate-task/background-task.ts
@@ -4,6 +4,7 @@ import { getTimingConfig } from "./timing"
 import { storeToolMetadata } from "../../features/tool-metadata-store"
 import { formatDetailedError } from "./error-formatting"
 import { getSessionTools } from "../../shared/session-tools-store"
+import { SessionCategoryRegistry } from "../../shared/session-category-registry"

 export async function executeBackgroundTask(
  args: DelegateTaskArgs,
@@ -48,6 +49,10 @@ export async function executeBackgroundTask(
      sessionId = updated?.sessionID
    }

+    if (args.category && sessionId) {
+      SessionCategoryRegistry.register(sessionId, args.category)
+    }
+
    const unstableMeta = {
      title: args.description,
      metadata: {
--- a/src/tools/delegate-task/sync-task.ts
+++ b/src/tools/delegate-task/sync-task.ts
@@ -5,6 +5,7 @@ import { getTaskToastManager } from "../../features/task-toast-manager"
 import { storeToolMetadata } from "../../features/tool-metadata-store"
 import { subagentSessions } from "../../features/claude-code-session-state"
 import { log } from "../../shared/logger"
+import { SessionCategoryRegistry } from "../../shared/session-category-registry"
 import { formatDuration } from "./time-formatter"
 import { formatDetailedError } from "./error-formatting"
 import { syncTaskDeps, type SyncTaskDeps } from "./sync-task-deps"
@@ -41,6 +42,10 @@ export async function executeSyncTask(
    syncSessionID = sessionID
    subagentSessions.add(sessionID)

+    if (args.category) {
+      SessionCategoryRegistry.register(sessionID, args.category)
+    }
+
    if (onSyncSessionCreated) {
      log("[task] Invoking onSyncSessionCreated callback", { sessionID, parentID: parentContext.sessionID })
      await onSyncSessionCreated({
@@ -145,6 +150,7 @@ session_id: ${sessionID}
  } finally {
    if (syncSessionID) {
      subagentSessions.delete(syncSessionID)
+      SessionCategoryRegistry.remove(syncSessionID)
    }
  }
 }
--- a/src/tools/delegate-task/tools.test.ts
+++ b/src/tools/delegate-task/tools.test.ts
@@ -1044,7 +1044,7 @@ describe("sisyphus-task", () => {
        modelID: "claude-opus-4-6",
        variant: "max",
      })
-    })
+    }, { timeout: 20000 })

     test("DEFAULT_CATEGORIES variant passes to sync session.prompt WITHOUT userCategories", async () => {
       // given - NO userCategories, testing DEFAULT_CATEGORIES for sync mode
@@ -2624,31 +2624,35 @@ describe("sisyphus-task", () => {
        toolContext
      )

-      // then - agent-browser skill should be resolved (not in notFound)
+      // then - agent-browser skill should be resolved
      expect(promptBody).toBeDefined()
      expect(promptBody.system).toBeDefined()
-      expect(promptBody.system).toContain("agent-browser")
+      expect(promptBody.system).toContain("<Category_Context>")
+      expect(String(promptBody.system).startsWith("<Category_Context>")).toBe(false)
    }, { timeout: 20000 })

-    test("should NOT resolve agent-browser skill when browserProvider is not set", async () => {
-      // given - task without browserProvider (defaults to playwright)
+    test("should resolve agent-browser skill even when browserProvider is not set", async () => {
+      // given - delegate_task without browserProvider
      const { createDelegateTask } = require("./tools")
+      let promptBody: any

      const mockManager = { launch: async () => ({}) }
      const mockClient = {
        app: { agents: async () => ({ data: [] }) },
-         config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
-         session: {
-           get: async () => ({ data: { directory: "/project" } }),
-           create: async () => ({ data: { id: "ses_no_browser_provider" } }),
-           prompt: async () => ({ data: {} }),
-           promptAsync: async () => ({ data: {} }),
-           messages: async () => ({
-             data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "Done" }] }]
-           }),
-           status: async () => ({ data: {} }),
-         },
-       }
+        config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
+        session: {
+          get: async () => ({ data: { directory: "/project" } }),
+          create: async () => ({ data: { id: "ses_no_browser_provider" } }),
+          prompt: async (input: any) => {
+            promptBody = input.body
+            return { data: {} }
+          },
+          messages: async () => ({
+            data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "Done" }] }]
+          }),
+          status: async () => ({ data: {} }),
+        },
+      }

       // No browserProvider passed
       const tool = createDelegateTask({
@@ -2675,7 +2679,7 @@ describe("sisyphus-task", () => {
        toolContext
      )

-      // then - should return skill not found error
+      // then - agent-browser skill should NOT resolve without browserProvider
      expect(result).toContain("Skills not found")
      expect(result).toContain("agent-browser")
    })
Author	SHA1	Message	Date
YeonGyu-Kim	13196aedb7	fix: resolve post-rebase runtime fallback merge leftovers	2026-02-21 02:45:48 +09:00
IYODA Atsushi	a8e3e1ea01	fix(test): correct browserProvider assertion to match actual behavior When browserProvider is not set, agent-browser skill should NOT resolve. Test assertions were inverted — expected 'Skills not found' but asserted the opposite.	2026-02-21 02:42:20 +09:00
IYODA Atsushi	fcaaa11a06	fix(runtime-fallback): detect type:error message parts for fallback progression	2026-02-21 02:42:20 +09:00
IYODA Atsushi	f82e65fdd1	docs(runtime-fallback): clarify timeout_seconds=0 disables auto-retry detection	2026-02-21 02:42:20 +09:00
Youngbin Kim	eef80a4e23	chore: regenerate JSON schema after merge	2026-02-21 02:42:20 +09:00
Youngbin Kim	b6456faea8	refactor(runtime-fallback): decompose index.ts into focused modules Split 1021-line index.ts into 10 focused modules per project conventions. New structure: - error-classifier.ts: error analysis with dynamic status code extraction - agent-resolver.ts: agent detection utilities - fallback-state.ts: state management and cooldown logic - fallback-models.ts: model resolution from config - auto-retry.ts: retry helpers with mutual recursion support - event-handler.ts: session lifecycle events - message-update-handler.ts: message.updated event handling - chat-message-handler.ts: chat message interception - hook.ts: main factory with proper cleanup - types.ts: updated with HookDeps interface - index.ts: 2-line barrel re-export Embedded fixes: - Fix setInterval leak with .unref() - Replace require() with ESM import - Add log warning on invalid model format - Update sessionLastAccess on normal traffic - Make extractStatusCode dynamic from config - Remove unused SessionErrorInfo type All 61 tests pass without modification. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:42:12 +09:00
Youngbin Kim	22dda6178a	docs(config): fix runtime fallback documentation Remove duplicate Runtime Fallback section from configurations.md. Fix max_fallback_attempts range from (1-10) to (1-20) to match schema. Update retry_on_errors default to include 400 status code. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:42:12 +09:00
Youngbin Kim	c54da1e670	docs(config): correct retry_on_errors default in schema comment Update schema comment to match actual code default [400, 429, 503, 529]. Previously the comment omitted 400 which is included in the code default. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:41:43 +09:00
Youngbin Kim	1835458054	fix(test): revert atlas test to use uiSelectedModel Revert test name and assertion to original behavior per PR review feedback. The test now correctly expects Atlas to respect uiSelectedModel instead of using its own fallback chain. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:40:47 +09:00
Youngbin Kim	349e820473	fix(config): allow timeout_seconds to be 0 to disable fallback Previously, the Zod schema rejected timeout_seconds: 0 due to .min(1). Now it accepts 0-integer values to allow disabling timeout-based fallback. - Changed z.number().min(1) to z.number().min(0) - Updated comment to clarify 0 disables timeout checks - All tests pass (44 runtime-fallback + 46 schema tests) - Build successful	2026-02-21 02:40:47 +09:00
Youngbin Kim	68f5d982fc	feat(runtime-fallback): add timeout toggle for quota retry detection Make provider auto-retry signal detection respect timeout_seconds setting: - When timeout_seconds=0, disable quota-based fallback escalation - Only treat auto-retry signals as errors when timeout is enabled - Add test to verify behavior when timeout_seconds is disabled - Update documentation to explain timeout_seconds=0 behavior This allows users to disable timeout-based fallbacks while keeping error-based fallback functionality intact.	2026-02-21 02:40:47 +09:00
Youngbin Kim	8b2ae957e5	feat(runtime-fallback): generalize provider auto-retry signal detection Refactor retry signal detection to be provider-agnostic: - Replace hardcoded Copilot/OpenAI checks with generic pattern matching - Detect any provider message containing limit/quota keywords + [retrying in X] - Add OpenAI pattern: 'usage limit has been reached [retrying in X]' - Update logging to use generic 'provider' instead of specific names - Add 'usage limit has been reached' to RETRYABLE_ERROR_PATTERNS This enables fallback escalation for any provider that signals automatic retries due to quota/rate limits, not just Copilot and OpenAI. Closes PR discussion: generalize retry pattern detection	2026-02-21 02:40:47 +09:00
Youngbin Kim	31f61078b1	docs(runtime-fallback): document retry classes and timeout behavior	2026-02-21 02:40:47 +09:00
Youngbin Kim	6a97f00a22	feat(runtime-fallback): add configurable session timeout controls	2026-02-21 02:40:01 +09:00
Youngbin Kim	ff230df47c	fix(runtime-fallback): harden fallback progression and success detection	2026-02-21 02:40:01 +09:00
Youngbin Kim	5a406cab9e	refactor(runtime-fallback): extract auto-retry helper and fix provider constraint inconsistency - Extract duplicated auto-retry logic (~40 lines each) from session.error and message.updated handlers into shared autoRetryWithFallback() helper - Fix userFallbackModels path in model-resolution-pipeline to respect constraints.connectedProviders parameter instead of reading cache directly, matching the behavior of categoryDefaultModel and fallbackChain paths	2026-02-21 02:40:01 +09:00
Youngbin Kim	fbafb8cf67	fix(runtime-fallback): 9 critical bug fixes for auto-retry, agent preservation, and model override Bug fixes: 1. extractStatusCode: handle nested data.statusCode (Anthropic error structure) 2. Error regex: relax credit.balance.too.*low pattern for multi-char gaps 3. Zod schema: bump max_fallback_attempts from 10 to 20 (config rejected silently) 4. getFallbackModelsForSession: fallback to sisyphus/any agent when session.error lacks agent 5. Model detection: derive model from agent config when session.error lacks model info 6. Auto-retry: resend last user message with fallback model via promptAsync 7. Persistent fallback: override model on every chat.message (not just pendingFallbackModel) 8. Manual model change: detect UI model changes and reset fallback state 9. Agent preservation: include agent in promptAsync body to prevent defaulting to sisyphus Additional: - Add sessionRetryInFlight guard to prevent double-retries - Add resolveAgentForSession with 3-tier resolution (event → session memory → session ID) - Add normalizeAgentName for display names like "Prometheus (Planner)" → "prometheus" - Add resolveAgentForSessionFromContext to fetch agent from session messages - Move AGENT_NAMES and agentPattern to module scope for reuse - Register runtime-fallback hooks in event.ts and chat-message.ts - Remove diagnostic debug logging from isRetryableError - Add 400 to default retry_on_errors and credit/balance patterns to RETRYABLE_ERROR_PATTERNS	2026-02-21 02:39:41 +09:00
youming.tang	708b9ce9ff	fix(runtime-fallback): sort agent names by length to fix hyphenated agent detection The \b word boundary regex treats '-' as a boundary, causing 'sisyphus-junior-session-123' to incorrectly match 'sisyphus' instead of 'sisyphus-junior'. Sorting agent names by length (descending) ensures longer names are matched first, fixing the hyphenated agent detection issue. Fixes cubic-dev-ai review issue #8	2026-02-21 02:38:17 +09:00
um1ng	d9072b4a98	fix(runtime-fallback): address cubic AI review issues - Add normalizeFallbackModels helper to centralize string/array normalization (P3) - Export RuntimeFallbackConfig and FallbackModels types from config/index.ts - Fix agent detection regex to use word boundaries for sessionID matching - Improve tests to verify actual fallback switching logic (not just log paths) - Add SessionCategoryRegistry cleanup in executeSyncTask on completion/error (P2) - All 24 runtime-fallback tests pass, 115 delegate-task tests pass	2026-02-21 02:37:57 +09:00
um1ng	e9ec4f44e2	feat(runtime-fallback): automatic model switching on API errors Implements runtime model fallback that automatically switches to backup models when the primary model encounters transient errors (rate limits, overload, etc.). Features: - runtime_fallback configuration with customizable error codes, cooldown, notifications - Runtime fallback hook intercepts API errors (429, 503, 529) - Support for fallback_models from agent/category configuration - Session-state TTL and periodic cleanup to prevent memory leaks - Robust agent name detection with explicit AGENT_NAMES array - Session category registry for category-specific fallback lookup Schema changes: - Add RuntimeFallbackConfigSchema with enabled, retry_on_errors, max_fallback_attempts, cooldown_seconds, notify_on_fallback options - Add fallback_models to AgentOverrideConfigSchema and CategoryConfigSchema - Add runtime-fallback to HookNameSchema Files added: - src/hooks/runtime-fallback/index.ts - Main hook implementation - src/hooks/runtime-fallback/types.ts - Type definitions - src/hooks/runtime-fallback/constants.ts - Constants and defaults - src/hooks/runtime-fallback/index.test.ts - Comprehensive tests - src/config/schema/runtime-fallback.ts - Schema definition - src/shared/session-category-registry.ts - Session category tracking Files modified: - src/hooks/index.ts - Export runtime-fallback hook - src/plugin/hooks/create-session-hooks.ts - Register runtime-fallback hook - src/config/schema.ts - Export runtime-fallback schema - src/config/schema/oh-my-opencode-config.ts - Add runtime_fallback config - src/config/schema/agent-overrides.ts - Add fallback_models to agent config - src/config/schema/categories.ts - Add fallback_models to category config - src/config/schema/hooks.ts - Add runtime-fallback to hook names - src/shared/index.ts - Export session-category-registry - docs/configurations.md - Add Runtime Fallback documentation - docs/features.md - Add runtime-fallback to hooks list Supersedes #1237, #1408 Closes #1408	2026-02-21 02:36:56 +09:00
youming.tang	067c8010be	fix: resolve merge conflicts in PR #1408 - Fix bun.lock version conflicts (3.3.1 -> 3.3.2) - Remove Git conflict markers from docs/configurations.md - Remove duplicate normalizeFallbackModels, import from shared module	2026-02-21 02:35:03 +09:00
um1ng	17d43672ad	refactor(shared): add normalizeFallbackModels utility function Add shared utility to normalize fallback_models config values. Handles both single string and array inputs consistently. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:34:28 +09:00
um1ng	8873896432	fix(runtime-fallback): use precise regex patterns for status code matching Replace word-boundary regex with stricter patterns that match status codes only at start/end of string or surrounded by whitespace. Prevents false matches like '1429' or '4290'. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:33:49 +09:00
youming.tang	a206daa437	test(agents): update Atlas uiSelectedModel expectation	2026-02-21 02:33:49 +09:00
youming.tang	538a92ab12	test(delegate-task): stabilize browserProvider and default variant cases	2026-02-21 02:33:49 +09:00
youming.tang	cd3e0ca124	fix(session-category-registry): cleanup entries for task sessions	2026-02-21 02:31:42 +09:00
youming.tang	d947743932	fix(runtime-fallback): per-model cooldown and stricter retry patterns	2026-02-21 02:30:55 +09:00
youming.tang	0ef17aa6c9	docs: add runtime-fallback and fallback_models documentation	2026-02-21 02:30:45 +09:00
Ultrawork Bot	7aafa13b21	feat(fallback_models): complete init-time and runtime integration Implement full fallback_models support across all integration points: 1. Model Resolution Pipeline (src/shared/model-resolution-pipeline.ts) - Add userFallbackModels to ModelResolutionRequest - Process user fallback_models before hardcoded fallback chain - Support both connected provider and availability checking modes 2. Agent Utils (src/agents/utils.ts) - Update applyModelResolution to accept userFallbackModels - Inject fallback_models for all builtin agents (sisyphus, oracle, etc.) - Support both single string and array formats 3. Model Resolver (src/shared/model-resolver.ts) - Add userFallbackModels to ExtendedModelResolutionInput type - Pass through to resolveModelPipeline 4. Delegate Task Executor (src/tools/delegate-task/executor.ts) - Extract category fallback_models configuration - Pass to model resolution pipeline - Register session category for runtime-fallback hook 5. Session Category Registry (src/shared/session-category-registry.ts) - New module: maps sessionID -> category - Used by runtime-fallback to lookup category fallback_models - Auto-cleanup support 6. Runtime Fallback Hook (src/hooks/runtime-fallback/index.ts) - Check SessionCategoryRegistry first for category fallback_models - Fallback to agent-level configuration - Import and use SessionCategoryRegistry Test Results: - runtime-fallback: 24/24 tests passing - model-resolver: 46/46 tests passing Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:30:01 +09:00
Rebase Bot	6dc1aff698	fix(runtime-fallback): add Category support and expand test coverage - Add Category-level fallback_models support in getFallbackModelsForSession() - Try agent-level fallback_models first - Then try agent's category fallback_models - Support all builtin agents including hephaestus, sisyphus-junior, build, plan - Expand agent name recognition regex to include: - hephaestus, sisyphus-junior, build, plan, multimodal-looker - Add comprehensive test coverage (6 new tests, total 24): - Model switching via chat.message hook - Agent-level fallback_models configuration - SessionID agent pattern detection - Cooldown mechanism validation - Max attempts limit enforcement All 24 tests passing Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:28:27 +09:00
Rebase Bot	632570f7ec	feat(config): add runtime_fallback and fallback_models schema Add configuration schemas for runtime model fallback feature: - RuntimeFallbackConfigSchema with enabled, retry_on_errors, max_fallback_attempts, cooldown_seconds, notify_on_fallback - FallbackModelsSchema for init-time fallback model selection - Add fallback_models to AgentOverrideConfigSchema and CategoryConfigSchema - Export types and schemas from config/index.ts Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-21 02:28:27 +09:00
YeonGyu-Kim	86cfa06aef	Merge pull request #1983 from Pantoria/fix/background-output-full-session-default fix(background-output): stop defaulting full_session=true for running tasks	2026-02-21 02:24:17 +09:00
YeonGyu-Kim	3c2ccba62b	Merge pull request #1952 from gustavosmendes/codex/fix-write-existing-file-guard-1871 fix: make write-existing-file-guard read-gated with overwrite bypass	2026-02-21 02:17:11 +09:00
YeonGyu-Kim	e0f2952659	remove slops	2026-02-21 01:25:46 +09:00
Ze-Xuan Liu	d556937c8e	fix(background-output): stop defaulting full_session=true for running tasks background_output auto-enabled full_session when the task was still running, returning the entire session transcript on every poll. When the parent agent had no other work and polled in a tight loop, this caused massive token waste because each response dumped thousands of tokens into the conversation history. Default full_session to false so running-task checks return a compact status table (~200 tokens). Callers can still pass full_session=true explicitly when they need the full transcript.	2026-02-19 19:30:45 -06:00
gustavosmendes	73d9e1f847	fix(write-existing-file-guard): wire cleanup through event dispatcher Forward session.deleted events to write-existing-file-guard so per-session read permissions are actually cleared in runtime. Add plugin-level regression test to ensure event forwarding remains wired, alongside the expanded guard behavior and unit coverage.	2026-02-18 16:50:30 -03:00
gustavosmendes	6d5d250f8f	Update src/hooks/write-existing-file-guard/index.test.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2026-02-18 16:24:20 -03:00
gustavosmendes	b6c433dae0	fix: make write-existing-file-guard read-gated and test coverage	2026-02-18 16:18:59 -03:00