test(plugin): cover session.status dedupe and runtime fallback gating

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

assets/oh-my-opencode.schema.json

@@ -3678,16 +3678,6 @@
             "minimum": 0
           }
         },
-        "maxDepth": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 9007199254740991
-        },
-        "maxDescendants": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 9007199254740991
-        },
         "staleTimeoutMs": {
           "type": "number",
           "minimum": 60000

src/config/schema/background-task.test.ts

@@ -3,54 +3,6 @@ import { ZodError } from "zod/v4"
 import { BackgroundTaskConfigSchema } from "./background-task"
 
 describe("BackgroundTaskConfigSchema", () => {
-  describe("maxDepth", () => {
-    describe("#given valid maxDepth (3)", () => {
-      test("#when parsed #then returns correct value", () => {
-        const result = BackgroundTaskConfigSchema.parse({ maxDepth: 3 })
-
-        expect(result.maxDepth).toBe(3)
-      })
-    })
-
-    describe("#given maxDepth below minimum (0)", () => {
-      test("#when parsed #then throws ZodError", () => {
-        let thrownError: unknown
-
-        try {
-          BackgroundTaskConfigSchema.parse({ maxDepth: 0 })
-        } catch (error) {
-          thrownError = error
-        }
-
-        expect(thrownError).toBeInstanceOf(ZodError)
-      })
-    })
-  })
-
-  describe("maxDescendants", () => {
-    describe("#given valid maxDescendants (50)", () => {
-      test("#when parsed #then returns correct value", () => {
-        const result = BackgroundTaskConfigSchema.parse({ maxDescendants: 50 })
-
-        expect(result.maxDescendants).toBe(50)
-      })
-    })
-
-    describe("#given maxDescendants below minimum (0)", () => {
-      test("#when parsed #then throws ZodError", () => {
-        let thrownError: unknown
-
-        try {
-          BackgroundTaskConfigSchema.parse({ maxDescendants: 0 })
-        } catch (error) {
-          thrownError = error
-        }
-
-        expect(thrownError).toBeInstanceOf(ZodError)
-      })
-    })
-  })
-
   describe("syncPollTimeoutMs", () => {
     describe("#given valid syncPollTimeoutMs (120000)", () => {
       test("#when parsed #then returns correct value", () => {

src/config/schema/background-task.ts

@@ -4,8 +4,6 @@ export const BackgroundTaskConfigSchema = z.object({
   defaultConcurrency: z.number().min(1).optional(),
   providerConcurrency: z.record(z.string(), z.number().min(0)).optional(),
   modelConcurrency: z.record(z.string(), z.number().min(0)).optional(),
-  maxDepth: z.number().int().min(1).optional(),
-  maxDescendants: z.number().int().min(1).optional(),
   /** Stale timeout in milliseconds - interrupt tasks with no activity for this duration (default: 180000 = 3 minutes, minimum: 60000 = 1 minute) */
   staleTimeoutMs: z.number().min(60000).optional(),
   /** Timeout for tasks that never received any progress update, falling back to startedAt (default: 600000 = 10 minutes, minimum: 60000 = 1 minute) */

src/features/background-agent/manager.test.ts

@@ -1637,25 +1637,6 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
      }
    }
 
-    function createMockClientWithSessionChain(
-      sessions: Record<string, { directory: string; parentID?: string }>
-    ) {
-      return {
-        session: {
-          create: async (_args?: any) => ({ data: { id: `ses_${crypto.randomUUID()}` } }),
-          get: async ({ path }: { path: { id: string } }) => ({
-            data: sessions[path.id] ?? { directory: "/test/dir" },
-          }),
-          prompt: async () => ({}),
-          promptAsync: async () => ({}),
-          messages: async () => ({ data: [] }),
-          todo: async () => ({ data: [] }),
-          status: async () => ({ data: {} }),
-          abort: async () => ({}),
-        },
-      }
-    }
-
   beforeEach(() => {
     // given
     mockClient = createMockClient()
@@ -1850,98 +1831,6 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
         expect(updatedTask.startedAt.getTime()).toBeGreaterThanOrEqual(queuedAt.getTime())
       }
     })
-
-    test("should track rootSessionID and spawnDepth from the parent chain", async () => {
-      // given
-      manager.shutdown()
-      manager = new BackgroundManager(
-        {
-          client: createMockClientWithSessionChain({
-            "session-depth-2": { directory: "/test/dir", parentID: "session-depth-1" },
-            "session-depth-1": { directory: "/test/dir", parentID: "session-root" },
-            "session-root": { directory: "/test/dir" },
-          }),
-          directory: tmpdir(),
-        } as unknown as PluginInput,
-        { maxDepth: 3 },
-      )
-
-      const input = {
-        description: "Test task",
-        prompt: "Do something",
-        agent: "test-agent",
-        parentSessionID: "session-depth-2",
-        parentMessageID: "parent-message",
-      }
-
-      // when
-      const task = await manager.launch(input)
-
-      // then
-      expect(task.rootSessionID).toBe("session-root")
-      expect(task.spawnDepth).toBe(3)
-    })
-
-    test("should block launches that exceed maxDepth", async () => {
-      // given
-      manager.shutdown()
-      manager = new BackgroundManager(
-        {
-          client: createMockClientWithSessionChain({
-            "session-depth-3": { directory: "/test/dir", parentID: "session-depth-2" },
-            "session-depth-2": { directory: "/test/dir", parentID: "session-depth-1" },
-            "session-depth-1": { directory: "/test/dir", parentID: "session-root" },
-            "session-root": { directory: "/test/dir" },
-          }),
-          directory: tmpdir(),
-        } as unknown as PluginInput,
-        { maxDepth: 3 },
-      )
-
-      const input = {
-        description: "Test task",
-        prompt: "Do something",
-        agent: "test-agent",
-        parentSessionID: "session-depth-3",
-        parentMessageID: "parent-message",
-      }
-
-      // when
-      const result = manager.launch(input)
-
-      // then
-      await expect(result).rejects.toThrow("background_task.maxDepth=3")
-    })
-
-    test("should block launches when maxDescendants is reached", async () => {
-      // given
-      manager.shutdown()
-      manager = new BackgroundManager(
-        {
-          client: createMockClientWithSessionChain({
-            "session-root": { directory: "/test/dir" },
-          }),
-          directory: tmpdir(),
-        } as unknown as PluginInput,
-        { maxDescendants: 1 },
-      )
-
-      const input = {
-        description: "Test task",
-        prompt: "Do something",
-        agent: "test-agent",
-        parentSessionID: "session-root",
-        parentMessageID: "parent-message",
-      }
-
-      await manager.launch(input)
-
-      // when
-      const result = manager.launch(input)
-
-      // then
-      await expect(result).rejects.toThrow("background_task.maxDescendants=1")
-    })
   })
 
   describe("pending task can be cancelled", () => {

src/features/background-agent/manager.ts

@@ -47,14 +47,6 @@ import { MESSAGE_STORAGE } from "../hook-message-injector"
 import { join } from "node:path"
 import { pruneStaleTasksAndNotifications } from "./task-poller"
 import { checkAndInterruptStaleTasks } from "./task-poller"
-import {
-  createSubagentDepthLimitError,
-  createSubagentDescendantLimitError,
-  getMaxRootDescendants,
-  getMaxSubagentDepth,
-  resolveSubagentSpawnContext,
-  type SubagentSpawnContext,
-} from "./subagent-spawn-limits"
 
 type OpencodeClient = PluginInput["client"]
 
@@ -119,7 +111,6 @@ export class BackgroundManager {
   private completionTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
   private idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
   private notificationQueueByParent: Map<string, Promise<void>> = new Map()
-  private rootDescendantCounts: Map<string, number>
   private enableParentSessionNotifications: boolean
   readonly taskHistory = new TaskHistory()
 
@@ -144,42 +135,10 @@ export class BackgroundManager {
     this.tmuxEnabled = options?.tmuxConfig?.enabled ?? false
     this.onSubagentSessionCreated = options?.onSubagentSessionCreated
     this.onShutdown = options?.onShutdown
-    this.rootDescendantCounts = new Map()
     this.enableParentSessionNotifications = options?.enableParentSessionNotifications ?? true
     this.registerProcessCleanup()
   }
 
-  async assertCanSpawn(parentSessionID: string): Promise<SubagentSpawnContext> {
-    const spawnContext = await resolveSubagentSpawnContext(this.client, parentSessionID)
-    const maxDepth = getMaxSubagentDepth(this.config)
-    if (spawnContext.childDepth > maxDepth) {
-      throw createSubagentDepthLimitError({
-        childDepth: spawnContext.childDepth,
-        maxDepth,
-        parentSessionID,
-        rootSessionID: spawnContext.rootSessionID,
-      })
-    }
-
-    const maxDescendants = getMaxRootDescendants(this.config)
-    const descendantCount = this.rootDescendantCounts.get(spawnContext.rootSessionID) ?? 0
-    if (descendantCount >= maxDescendants) {
-      throw createSubagentDescendantLimitError({
-        rootSessionID: spawnContext.rootSessionID,
-        descendantCount,
-        maxDescendants,
-      })
-    }
-
-    return spawnContext
-  }
-
-  private registerRootDescendant(rootSessionID: string): number {
-    const nextCount = (this.rootDescendantCounts.get(rootSessionID) ?? 0) + 1
-    this.rootDescendantCounts.set(rootSessionID, nextCount)
-    return nextCount
-  }
-
   async launch(input: LaunchInput): Promise<BackgroundTask> {
     log("[background-agent] launch() called with:", {
       agent: input.agent,
@@ -192,28 +151,16 @@ export class BackgroundManager {
       throw new Error("Agent parameter is required")
     }
 
-    const spawnContext = await this.assertCanSpawn(input.parentSessionID)
-    const descendantCount = this.registerRootDescendant(spawnContext.rootSessionID)
-
-    log("[background-agent] spawn guard passed", {
-      parentSessionID: input.parentSessionID,
-      rootSessionID: spawnContext.rootSessionID,
-      childDepth: spawnContext.childDepth,
-      descendantCount,
-    })
-
     // Create task immediately with status="pending"
     const task: BackgroundTask = {
       id: `bg_${crypto.randomUUID().slice(0, 8)}`,
       status: "pending",
       queuedAt: new Date(),
-      rootSessionID: spawnContext.rootSessionID,
       // Do NOT set startedAt - will be set when running
       // Do NOT set sessionID - will be set when running
       description: input.description,
       prompt: input.prompt,
       agent: input.agent,
-      spawnDepth: spawnContext.childDepth,
       parentSessionID: input.parentSessionID,
       parentMessageID: input.parentMessageID,
       parentModel: input.parentModel,
@@ -258,7 +205,7 @@ export class BackgroundManager {
     // Trigger processing (fire-and-forget)
     this.processKey(key)
 
-    return { ...task }
+    return task
   }
 
   private async processKey(key: string): Promise<void> {
@@ -928,7 +875,6 @@ export class BackgroundManager {
         }
       }
 
-      this.rootDescendantCounts.delete(sessionID)
       SessionCategoryRegistry.remove(sessionID)
     }
 
@@ -1663,7 +1609,6 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
     this.pendingNotifications.clear()
     this.pendingByParent.clear()
     this.notificationQueueByParent.clear()
-    this.rootDescendantCounts.clear()
     this.queuesByKey.clear()
     this.processingKeys.clear()
     this.unregisterProcessCleanup()

src/features/background-agent/subagent-spawn-limits.ts

@@ -1,79 +0,0 @@
-import type { BackgroundTaskConfig } from "../../config/schema"
-import type { OpencodeClient } from "./constants"
-
-export const DEFAULT_MAX_SUBAGENT_DEPTH = 3
-export const DEFAULT_MAX_ROOT_DESCENDANTS = 50
-
-export interface SubagentSpawnContext {
-  rootSessionID: string
-  parentDepth: number
-  childDepth: number
-}
-
-export function getMaxSubagentDepth(config?: BackgroundTaskConfig): number {
-  return config?.maxDepth ?? DEFAULT_MAX_SUBAGENT_DEPTH
-}
-
-export function getMaxRootDescendants(config?: BackgroundTaskConfig): number {
-  return config?.maxDescendants ?? DEFAULT_MAX_ROOT_DESCENDANTS
-}
-
-export async function resolveSubagentSpawnContext(
-  client: OpencodeClient,
-  parentSessionID: string
-): Promise<SubagentSpawnContext> {
-  const visitedSessionIDs = new Set<string>()
-  let rootSessionID = parentSessionID
-  let currentSessionID = parentSessionID
-  let parentDepth = 0
-
-  while (true) {
-    if (visitedSessionIDs.has(currentSessionID)) {
-      throw new Error(`Detected a session parent cycle while resolving ${parentSessionID}`)
-    }
-
-    visitedSessionIDs.add(currentSessionID)
-
-    const session = await client.session.get({
-      path: { id: currentSessionID },
-    }).catch(() => null)
-
-    const nextParentSessionID = session?.data?.parentID
-    if (!nextParentSessionID) {
-      rootSessionID = currentSessionID
-      break
-    }
-
-    currentSessionID = nextParentSessionID
-    parentDepth += 1
-  }
-
-  return {
-    rootSessionID,
-    parentDepth,
-    childDepth: parentDepth + 1,
-  }
-}
-
-export function createSubagentDepthLimitError(input: {
-  childDepth: number
-  maxDepth: number
-  parentSessionID: string
-  rootSessionID: string
-}): Error {
-  const { childDepth, maxDepth, parentSessionID, rootSessionID } = input
-  return new Error(
-    `Subagent spawn blocked: child depth ${childDepth} exceeds background_task.maxDepth=${maxDepth}. Parent session: ${parentSessionID}. Root session: ${rootSessionID}. Continue in an existing subagent session instead of spawning another.`
-  )
-}
-
-export function createSubagentDescendantLimitError(input: {
-  rootSessionID: string
-  descendantCount: number
-  maxDescendants: number
-}): Error {
-  const { rootSessionID, descendantCount, maxDescendants } = input
-  return new Error(
-    `Subagent spawn blocked: root session ${rootSessionID} already has ${descendantCount} descendants, which meets background_task.maxDescendants=${maxDescendants}. Reuse an existing session instead of spawning another.`
-  )
-}

src/features/background-agent/types.ts

@@ -19,13 +19,11 @@ export interface TaskProgress {
 export interface BackgroundTask {
   id: string
   sessionID?: string
-  rootSessionID?: string
   parentSessionID: string
   parentMessageID: string
   description: string
   prompt: string
   agent: string
-  spawnDepth?: number
   status: BackgroundTaskStatus
   queuedAt?: Date
   startedAt?: Date

src/hooks/runtime-fallback/constants.ts

@@ -26,6 +26,11 @@ export const RETRYABLE_ERROR_PATTERNS = [
   /rate.?limit/i,
   /too.?many.?requests/i,
   /quota.?exceeded/i,
+  /quota\s+will\s+reset\s+after/i,
+  /all\s+credentials\s+for\s+model/i,
+  /cool(?:ing)?\s+down/i,
+  /cooldown/i,
+  /exhausted\s+your\s+capacity/i,
   /usage\s+limit\s+has\s+been\s+reached/i,
   /service.?unavailable/i,
   /overloaded/i,

src/hooks/runtime-fallback/event-handler.ts

@@ -6,9 +6,11 @@ import { extractStatusCode, extractErrorName, classifyErrorType, isRetryableErro
 import { createFallbackState, prepareFallback } from "./fallback-state"
 import { getFallbackModelsForSession } from "./fallback-models"
 import { SessionCategoryRegistry } from "../../shared/session-category-registry"
+import { createSessionStatusHandler } from "./session-status-handler"
 
 export function createEventHandler(deps: HookDeps, helpers: AutoRetryHelpers) {
   const { config, pluginConfig, sessionStates, sessionLastAccess, sessionRetryInFlight, sessionAwaitingFallbackResult, sessionFallbackTimeouts } = deps
+  const sessionStatusHandler = createSessionStatusHandler(deps, helpers)
 
   const handleSessionCreated = (props: Record<string, unknown> | undefined) => {
     const sessionInfo = props?.info as { id?: string; model?: string } | undefined
@@ -33,6 +35,7 @@ export function createEventHandler(deps: HookDeps, helpers: AutoRetryHelpers) {
       sessionRetryInFlight.delete(sessionID)
       sessionAwaitingFallbackResult.delete(sessionID)
       helpers.clearSessionFallbackTimeout(sessionID)
+      sessionStatusHandler.clearRetryKey(sessionID)
       SessionCategoryRegistry.remove(sessionID)
     }
   }
@@ -191,6 +194,7 @@ export function createEventHandler(deps: HookDeps, helpers: AutoRetryHelpers) {
     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.status") { await sessionStatusHandler.handleSessionStatus(props); return }
     if (event.type === "session.error") { await handleSessionError(props); return }
   }
 }

src/hooks/runtime-fallback/index.test.ts

@@ -387,6 +387,133 @@ describe("runtime-fallback", () => {
       expect(fallbackLog?.data).toMatchObject({ from: "openai/gpt-5.3-codex", to: "anthropic/claude-opus-4-6" })
     })
 
+    test("should trigger fallback on session.status auto-retry signal", async () => {
+      const promptCalls: unknown[] = []
+      const hook = createRuntimeFallbackHook(
+        createMockPluginInput({
+          session: {
+            messages: async () => ({
+              data: [
+                {
+                  info: { role: "user" },
+                  parts: [{ type: "text", text: "continue" }],
+                },
+              ],
+            }),
+            promptAsync: async (args: unknown) => {
+              promptCalls.push(args)
+              return {}
+            },
+          },
+        }),
+        {
+          config: createMockConfig({ notify_on_fallback: false }),
+          pluginConfig: createMockPluginConfigWithCategoryFallback(["openai/gpt-5.4"]),
+        }
+      )
+
+      const sessionID = "test-session-status-auto-retry"
+      SessionCategoryRegistry.register(sessionID, "test")
+
+      await hook.event({
+        event: {
+          type: "session.created",
+          properties: { info: { id: sessionID, model: "quotio/claude-opus-4-6" } },
+        },
+      })
+
+      await hook.event({
+        event: {
+          type: "session.status",
+          properties: {
+            sessionID,
+            status: {
+              type: "retry",
+              attempt: 1,
+              next: 476,
+              message: "All credentials for model claude-opus-4-6 are cooling down [retrying in 7m 56s attempt #1]",
+            },
+          },
+        },
+      })
+
+      const signalLog = logCalls.find((c) => c.msg.includes("Detected provider auto-retry signal in session.status"))
+      expect(signalLog).toBeDefined()
+
+      const fallbackLog = logCalls.find((c) => c.msg.includes("Preparing fallback"))
+      expect(fallbackLog).toBeDefined()
+      expect(fallbackLog?.data).toMatchObject({ from: "quotio/claude-opus-4-6", to: "openai/gpt-5.4" })
+      expect(promptCalls).toHaveLength(1)
+    })
+
+    test("should deduplicate session.status countdown updates for the same retry attempt", async () => {
+      const promptCalls: unknown[] = []
+      const hook = createRuntimeFallbackHook(
+        createMockPluginInput({
+          session: {
+            messages: async () => ({
+              data: [
+                {
+                  info: { role: "user" },
+                  parts: [{ type: "text", text: "continue" }],
+                },
+              ],
+            }),
+            promptAsync: async (args: unknown) => {
+              promptCalls.push(args)
+              return {}
+            },
+          },
+        }),
+        {
+          config: createMockConfig({ notify_on_fallback: false }),
+          pluginConfig: createMockPluginConfigWithCategoryFallback(["openai/gpt-5.4"]),
+        }
+      )
+
+      const sessionID = "test-session-status-countdown-dedup"
+      SessionCategoryRegistry.register(sessionID, "test")
+
+      await hook.event({
+        event: {
+          type: "session.created",
+          properties: { info: { id: sessionID, model: "quotio/claude-opus-4-6" } },
+        },
+      })
+
+      await hook.event({
+        event: {
+          type: "session.status",
+          properties: {
+            sessionID,
+            status: {
+              type: "retry",
+              attempt: 1,
+              next: 476,
+              message: "All credentials for model claude-opus-4-6 are cooling down [retrying in 7m 56s attempt #1]",
+            },
+          },
+        },
+      })
+
+      await hook.event({
+        event: {
+          type: "session.status",
+          properties: {
+            sessionID,
+            status: {
+              type: "retry",
+              attempt: 1,
+              next: 475,
+              message: "All credentials for model claude-opus-4-6 are cooling down [retrying in 7m 55s attempt #1]",
+            },
+          },
+        },
+      })
+
+      expect(promptCalls).toHaveLength(1)
+    })
+
     test("should NOT trigger fallback on auto-retry signal when timeout_seconds is 0", async () => {
       const hook = createRuntimeFallbackHook(createMockPluginInput(), {
         config: createMockConfig({ notify_on_fallback: false, timeout_seconds: 0 }),

src/hooks/runtime-fallback/session-status-handler.ts

@@ -0,0 +1,160 @@
+import type { HookDeps } from "./types"
+import type { AutoRetryHelpers } from "./auto-retry"
+import { HOOK_NAME } from "./constants"
+import { log } from "../../shared/logger"
+import { isRetryableError } from "./error-classifier"
+import { createFallbackState, prepareFallback } from "./fallback-state"
+import { getFallbackModelsForSession } from "./fallback-models"
+import { extractRetryAttempt, extractRetryStatusModel, normalizeRetryStatusMessage } from "../../shared/retry-status-utils"
+
+type SessionStatus = {
+  type?: string
+  message?: string
+  attempt?: number
+}
+
+function resolveInitialModel(
+  props: Record<string, unknown> | undefined,
+  retryMessage: string,
+  resolvedAgent: string | undefined,
+  pluginConfig: HookDeps["pluginConfig"],
+): string | undefined {
+  const eventModel = typeof props?.model === "string" ? props.model : undefined
+  if (eventModel) {
+    return eventModel
+  }
+
+  const retryModel = extractRetryStatusModel(retryMessage)
+  if (retryModel) {
+    return retryModel
+  }
+
+  const agentConfig = resolvedAgent
+    ? pluginConfig?.agents?.[resolvedAgent as keyof typeof pluginConfig.agents]
+    : undefined
+
+  return typeof agentConfig?.model === "string" ? agentConfig.model : undefined
+}
+
+export function createSessionStatusHandler(deps: HookDeps, helpers: AutoRetryHelpers): {
+  clearRetryKey: (sessionID: string) => void
+  handleSessionStatus: (props: Record<string, unknown> | undefined) => Promise<void>
+} {
+  const {
+    config,
+    pluginConfig,
+    sessionStates,
+    sessionLastAccess,
+    sessionRetryInFlight,
+    sessionAwaitingFallbackResult,
+  } = deps
+  const sessionStatusRetryKeys = new Map<string, string>()
+
+  const clearRetryKey = (sessionID: string): void => {
+    sessionStatusRetryKeys.delete(sessionID)
+  }
+
+  const handleSessionStatus = async (props: Record<string, unknown> | undefined): Promise<void> => {
+    const sessionID = props?.sessionID as string | undefined
+    const status = props?.status as SessionStatus | undefined
+    const agent = props?.agent as string | undefined
+    const timeoutEnabled = config.timeout_seconds > 0
+
+    if (!sessionID || status?.type !== "retry" || !timeoutEnabled) {
+      return
+    }
+
+    const retryMessage = typeof status.message === "string" ? status.message : ""
+    if (!retryMessage || !isRetryableError({ message: retryMessage }, config.retry_on_errors)) {
+      return
+    }
+
+    const currentState = sessionStates.get(sessionID)
+    const retryAttempt = extractRetryAttempt(status.attempt, retryMessage)
+    const retryModel =
+      (typeof props?.model === "string" ? props.model : undefined) ??
+      extractRetryStatusModel(retryMessage) ??
+      currentState?.currentModel ??
+      "unknown-model"
+    const retryKey = `${retryAttempt}:${retryModel}:${normalizeRetryStatusMessage(retryMessage)}`
+
+    if (sessionStatusRetryKeys.get(sessionID) === retryKey) {
+      return
+    }
+    sessionStatusRetryKeys.set(sessionID, retryKey)
+
+    if (sessionRetryInFlight.has(sessionID)) {
+      log(`[${HOOK_NAME}] Overriding in-flight retry due to provider session.status retry signal`, {
+        sessionID,
+        retryModel,
+      })
+      await helpers.abortSessionRequest(sessionID, "session.status.retry-signal")
+      sessionRetryInFlight.delete(sessionID)
+    }
+
+    sessionAwaitingFallbackResult.delete(sessionID)
+
+    const resolvedAgent = await helpers.resolveAgentForSessionFromContext(sessionID, agent)
+    const fallbackModels = getFallbackModelsForSession(sessionID, resolvedAgent, pluginConfig)
+
+    if (fallbackModels.length === 0) {
+      log(`[${HOOK_NAME}] No fallback models configured`, { sessionID, agent: resolvedAgent ?? agent })
+      return
+    }
+
+    let state = currentState
+    if (!state) {
+      const initialModel = resolveInitialModel(props, retryMessage, resolvedAgent, pluginConfig)
+      if (!initialModel) {
+        log(`[${HOOK_NAME}] session.status retry missing model info, cannot fallback`, { sessionID })
+        return
+      }
+
+      state = createFallbackState(initialModel)
+      sessionStates.set(sessionID, state)
+    }
+
+    sessionLastAccess.set(sessionID, Date.now())
+
+    if (state.pendingFallbackModel) {
+      log(`[${HOOK_NAME}] Clearing pending fallback due to provider session.status retry signal`, {
+        sessionID,
+        pendingFallbackModel: state.pendingFallbackModel,
+      })
+      state.pendingFallbackModel = undefined
+    }
+
+    log(`[${HOOK_NAME}] Detected provider auto-retry signal in session.status`, {
+      sessionID,
+      model: state.currentModel,
+      retryAttempt,
+    })
+
+    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.status")
+      return
+    }
+
+    log(`[${HOOK_NAME}] Fallback preparation failed`, { sessionID, error: result.error })
+  }
+
+  return {
+    clearRetryKey,
+    handleSessionStatus,
+  }
+}

src/plugin/event.model-fallback.test.ts

@@ -6,7 +6,7 @@ import { _resetForTesting, setMainSession } from "../features/claude-code-sessio
 import { createModelFallbackHook, clearPendingModelFallback } from "../hooks/model-fallback/hook"
 
 describe("createEventHandler - model fallback", () => {
-  const createHandler = (args?: { hooks?: any }) => {
+  const createHandler = (args?: { hooks?: any; pluginConfig?: any }) => {
     const abortCalls: string[] = []
     const promptCalls: string[] = []
 
@@ -26,7 +26,7 @@ describe("createEventHandler - model fallback", () => {
           },
         },
       } as any,
-      pluginConfig: {} as any,
+      pluginConfig: (args?.pluginConfig ?? {}) as any,
       firstMessageVariantGate: {
         markSessionCreated: () => {},
         clear: () => {},
@@ -213,6 +213,121 @@ describe("createEventHandler - model fallback", () => {
     expect(output.message["variant"]).toBe("max")
   })
 
+  test("deduplicates session.status countdown updates for the same retry attempt", async () => {
+    //#given
+    const sessionID = "ses_status_retry_dedup"
+    setMainSession(sessionID)
+    clearPendingModelFallback(sessionID)
+    const modelFallback = createModelFallbackHook()
+    const { handler, abortCalls, promptCalls } = createHandler({ hooks: { modelFallback } })
+
+    await handler({
+      event: {
+        type: "message.updated",
+        properties: {
+          info: {
+            id: "msg_user_status_dedup",
+            sessionID,
+            role: "user",
+            modelID: "claude-opus-4-6-thinking",
+            providerID: "anthropic",
+            agent: "Sisyphus (Ultraworker)",
+          },
+        },
+      },
+    })
+
+    //#when
+    await handler({
+      event: {
+        type: "session.status",
+        properties: {
+          sessionID,
+          status: {
+            type: "retry",
+            attempt: 1,
+            message:
+              "Bad Gateway: {\"error\":{\"message\":\"unknown provider for model claude-opus-4-6-thinking\"}} [retrying in 27s attempt #1]",
+            next: 27,
+          },
+        },
+      },
+    })
+
+    await handler({
+      event: {
+        type: "session.status",
+        properties: {
+          sessionID,
+          status: {
+            type: "retry",
+            attempt: 1,
+            message:
+              "Bad Gateway: {\"error\":{\"message\":\"unknown provider for model claude-opus-4-6-thinking\"}} [retrying in 26s attempt #1]",
+            next: 26,
+          },
+        },
+      },
+    })
+
+    //#then
+    expect(abortCalls).toEqual([sessionID])
+    expect(promptCalls).toEqual([sessionID])
+  })
+
+  test("does not trigger model fallback from session.status when runtime fallback is enabled", async () => {
+    //#given
+    const sessionID = "ses_status_retry_runtime_enabled"
+    setMainSession(sessionID)
+    clearPendingModelFallback(sessionID)
+    const modelFallback = createModelFallbackHook()
+    const runtimeFallback = {
+      event: async () => {},
+      "chat.message": async () => {},
+    }
+    const { handler, abortCalls, promptCalls } = createHandler({
+      hooks: { modelFallback, runtimeFallback },
+      pluginConfig: { runtime_fallback: { enabled: true } },
+    })
+
+    await handler({
+      event: {
+        type: "message.updated",
+        properties: {
+          info: {
+            id: "msg_user_status_runtime_enabled",
+            sessionID,
+            role: "user",
+            modelID: "claude-opus-4-6-thinking",
+            providerID: "anthropic",
+            agent: "Sisyphus (Ultraworker)",
+          },
+        },
+      },
+    })
+
+    //#when
+    await handler({
+      event: {
+        type: "session.status",
+        properties: {
+          sessionID,
+          status: {
+            type: "retry",
+            attempt: 1,
+            message:
+              "Bad Gateway: {\"error\":{\"message\":\"unknown provider for model claude-opus-4-6-thinking\"}} [retrying in 27s attempt #1]",
+            next: 27,
+          },
+        },
+      },
+    })
+
+    //#then
+    expect(abortCalls).toEqual([])
+    expect(promptCalls).toEqual([])
+  })
+
   test("advances main-session fallback chain across repeated session.error retries end-to-end", async () => {
     //#given
     const abortCalls: string[] = []

src/plugin/event.ts

@@ -18,6 +18,7 @@ import {
 import { resetMessageCursor } from "../shared";
 import { log } from "../shared/logger";
 import { shouldRetryError } from "../shared/model-error-classifier";
+import { extractRetryAttempt, extractRetryStatusModel, normalizeRetryStatusMessage } from "../shared/retry-status-utils";
 import { clearSessionModel, setSessionModel } from "../shared/session-model-state";
 import { deleteSessionTools } from "../shared/session-tools-store";
 import { lspManager } from "../tools";
@@ -342,10 +343,15 @@ export function createEventHandler(args: {
       const sessionID = props?.sessionID as string | undefined;
       const status = props?.status as { type?: string; attempt?: number; message?: string; next?: number } | undefined;
 
-      if (sessionID && status?.type === "retry" && isModelFallbackEnabled) {
+      if (sessionID && status?.type === "retry" && !isRuntimeFallbackEnabled && isModelFallbackEnabled) {
         try {
           const retryMessage = typeof status.message === "string" ? status.message : "";
-          const retryKey = `${status.attempt ?? "?"}:${status.next ?? "?"}:${retryMessage}`;
+          const retryAttempt = extractRetryAttempt(status.attempt, retryMessage);
+          const retryModel =
+            extractRetryStatusModel(retryMessage) ??
+            lastKnownModelBySession.get(sessionID)?.modelID ??
+            "unknown-model";
+          const retryKey = `${retryAttempt}:${retryModel}:${normalizeRetryStatusMessage(retryMessage)}`;
           if (lastHandledRetryStatusKey.get(sessionID) === retryKey) {
             return;
           }

src/shared/retry-status-utils.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test"
+
+import { extractRetryAttempt, extractRetryStatusModel, normalizeRetryStatusMessage } from "./retry-status-utils"
+
+describe("retry-status-utils", () => {
+  test("extracts retry attempt from explicit status attempt", () => {
+    //#given
+    const attempt = 6
+
+    //#when
+    const result = extractRetryAttempt(attempt, "The usage limit has been reached [retrying in 27s attempt #6]")
+
+    //#then
+    expect(result).toBe(6)
+  })
+
+  test("extracts retry model from cooldown status text", () => {
+    //#given
+    const message = "All credentials for model claude-opus-4-6 are cooling down [retrying in 7m 56s attempt #1]"
+
+    //#when
+    const result = extractRetryStatusModel(message)
+
+    //#then
+    expect(result).toBe("claude-opus-4-6")
+  })
+
+  test("normalizes countdown jitter to a stable cooldown class", () => {
+    //#given
+    const firstMessage = "All credentials for model claude-opus-4-6 are cooling down [retrying in 7m 56s attempt #1]"
+    const secondMessage = "All credentials for model claude-opus-4-6 are cooling down [retrying in 7m 55s attempt #1]"
+
+    //#when
+    const firstResult = normalizeRetryStatusMessage(firstMessage)
+    const secondResult = normalizeRetryStatusMessage(secondMessage)
+
+    //#then
+    expect(firstResult).toBe("cooldown")
+    expect(secondResult).toBe("cooldown")
+  })
+})

src/shared/retry-status-utils.ts

@@ -0,0 +1,51 @@
+const RETRY_COUNTDOWN_PATTERN = /\[\s*retrying\s+in[^\]]*\]/gi
+
+function collapseWhitespace(value: string): string {
+  return value.toLowerCase().replace(/\s+/g, " ").trim()
+}
+
+export function extractRetryAttempt(attempt: number | undefined, message: string): number | "?" {
+  if (typeof attempt === "number" && Number.isFinite(attempt)) {
+    return attempt
+  }
+
+  const parsedAttempt = message.match(/attempt\s*#\s*(\d+)/i)?.[1]
+  return parsedAttempt ? Number.parseInt(parsedAttempt, 10) : "?"
+}
+
+export function extractRetryStatusModel(message: string): string | undefined {
+  return message.match(/model\s+([a-z0-9._/-]+)(?=\s+(?:are|is)\b)/i)?.[1]?.toLowerCase()
+}
+
+export function normalizeRetryStatusMessage(message: string): string {
+  const normalizedMessage = collapseWhitespace(message.replace(RETRY_COUNTDOWN_PATTERN, " "))
+  if (!normalizedMessage) {
+    return "retry"
+  }
+
+  if (/all\s+credentials\s+for\s+model|cool(?:ing)?\s+down|cooldown|exhausted\s+your\s+capacity/.test(normalizedMessage)) {
+    return "cooldown"
+  }
+
+  if (/too\s+many\s+requests/.test(normalizedMessage)) {
+    return "too-many-requests"
+  }
+
+  if (/quota\s+will\s+reset\s+after|quota\s*exceeded/.test(normalizedMessage)) {
+    return "quota"
+  }
+
+  if (/usage\s+limit\s+has\s+been\s+reached|limit\s+reached/.test(normalizedMessage)) {
+    return "usage-limit"
+  }
+
+  if (/rate\s+limit/.test(normalizedMessage)) {
+    return "rate-limit"
+  }
+
+  if (/service.?unavailable|temporarily.?unavailable|overloaded/.test(normalizedMessage)) {
+    return "service-unavailable"
+  }
+
+  return normalizedMessage
+}

src/tools/call-omo-agent/constants.ts

@@ -12,4 +12,4 @@ export const CALL_OMO_AGENT_DESCRIPTION = `Spawn explore/librarian agent. run_in
 
 Available: {agents}
 
-Pass \`session_id=<id>\` to continue previous agent with full context. Nested subagent depth is tracked automatically and blocked past the configured limit. Prompts MUST be in English. Use \`background_output\` for async results.`
+Pass \`session_id=<id>\` to continue previous agent with full context. Prompts MUST be in English. Use \`background_output\` for async results.`

src/tools/call-omo-agent/tools.test.ts

@@ -4,14 +4,12 @@ import type { BackgroundManager } from "../../features/background-agent"
 import { createCallOmoAgent } from "./tools"
 
 describe("createCallOmoAgent", () => {
-  const assertCanSpawnMock = mock(() => Promise.resolve(undefined))
   const mockCtx = {
     client: {},
     directory: "/test",
   } as unknown as PluginInput
 
   const mockBackgroundManager = {
-    assertCanSpawn: assertCanSpawnMock,
     launch: mock(() => Promise.resolve({
       id: "test-task-id",
       sessionID: null,
@@ -101,25 +99,4 @@ describe("createCallOmoAgent", () => {
     //#then
     expect(result).not.toContain("disabled via disabled_agents")
   })
-
-  test("should return a tool error when sync spawn depth validation fails", async () => {
-    //#given
-    assertCanSpawnMock.mockRejectedValueOnce(new Error("Subagent spawn blocked: child depth 4 exceeds background_task.maxDepth=3."))
-    const toolDef = createCallOmoAgent(mockCtx, mockBackgroundManager, [])
-    const executeFunc = toolDef.execute as Function
-
-    //#when
-    const result = await executeFunc(
-      {
-        description: "Test",
-        prompt: "Test prompt",
-        subagent_type: "explore",
-        run_in_background: false,
-      },
-      { sessionID: "test", messageID: "msg", agent: "test", abort: new AbortController().signal },
-    )
-
-    //#then
-    expect(result).toContain("background_task.maxDepth=3")
-  })
 })

src/tools/call-omo-agent/tools.ts

@@ -57,14 +57,6 @@ export function createCallOmoAgent(
         return await executeBackground(args, toolCtx, backgroundManager, ctx.client)
       }
 
-      if (!args.session_id) {
-        try {
-          await backgroundManager.assertCanSpawn(toolCtx.sessionID)
-        } catch (error) {
-          return `Error: ${error instanceof Error ? error.message : String(error)}`
-        }
-      }
-
       return await executeSync(args, toolCtx, ctx)
     },
   })

src/tools/delegate-task/sync-task.ts

@@ -23,19 +23,12 @@ export async function executeSyncTask(
   fallbackChain?: import("../../shared/model-requirements").FallbackEntry[],
   deps: SyncTaskDeps = syncTaskDeps
 ): Promise<string> {
-  const { manager, client, directory, onSyncSessionCreated, syncPollTimeoutMs } = executorCtx
+  const { client, directory, onSyncSessionCreated, syncPollTimeoutMs } = executorCtx
   const toastManager = getTaskToastManager()
   let taskId: string | undefined
   let syncSessionID: string | undefined
 
   try {
-    const spawnContext = typeof manager?.assertCanSpawn === "function"
-      ? await manager.assertCanSpawn(parentContext.sessionID)
-      : {
-          rootSessionID: parentContext.sessionID,
-          parentDepth: 0,
-          childDepth: 1,
-        }
     const createSessionResult = await deps.createSyncSession(client, {
       parentSessionID: parentContext.sessionID,
       agentToUse,
@@ -97,7 +90,6 @@ export async function executeSyncTask(
         run_in_background: args.run_in_background,
         sessionId: sessionID,
         sync: true,
-        spawnDepth: spawnContext.childDepth,
         command: args.command,
         model: categoryModel ? { providerID: categoryModel.providerID, modelID: categoryModel.modelID } : undefined,
       },