feat(call-omo-agent): block sync subagent depth overflows

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,6 +3678,16 @@
             "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,6 +3,54 @@ 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,6 +4,8 @@ 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,6 +1637,25 @@ 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()
@@ -1831,6 +1850,98 @@ 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,6 +47,14 @@ 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"]
 
@@ -111,6 +119,7 @@ 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()
 
@@ -135,10 +144,42 @@ 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,
@@ -151,16 +192,28 @@ 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,
@@ -205,7 +258,7 @@ export class BackgroundManager {
     // Trigger processing (fire-and-forget)
     this.processKey(key)
 
-    return task
+    return { ...task }
   }
 
   private async processKey(key: string): Promise<void> {
@@ -875,6 +928,7 @@ export class BackgroundManager {
         }
       }
 
+      this.rootDescendantCounts.delete(sessionID)
       SessionCategoryRegistry.remove(sessionID)
     }
 
@@ -1609,6 +1663,7 @@ 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

@@ -0,0 +1,79 @@
+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,11 +19,13 @@ 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/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. Prompts MUST be in English. Use \`background_output\` for async results.`
+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.`

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

@@ -4,12 +4,14 @@ 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,
@@ -99,4 +101,25 @@ 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,6 +57,14 @@ 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,12 +23,19 @@ export async function executeSyncTask(
   fallbackChain?: import("../../shared/model-requirements").FallbackEntry[],
   deps: SyncTaskDeps = syncTaskDeps
 ): Promise<string> {
-  const { client, directory, onSyncSessionCreated, syncPollTimeoutMs } = executorCtx
+  const { manager, 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,
@@ -90,6 +97,7 @@ 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,
       },