Limit recursive subagent spawning

2026-03-11 17:46:04 +09:00
parent 4ded281ee0
commit 4a39c83eb5
11 changed files with 358 additions and 5 deletions
@@ -1731,6 +1731,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()
@@ -1925,6 +1944,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", () => {
@@ -51,6 +51,14 @@ import { join } from "node:path"
 import { pruneStaleTasksAndNotifications } from "./task-poller"
 import { checkAndInterruptStaleTasks } from "./task-poller"
 import { removeTaskToastTracking } from "./remove-task-toast-tracking"
+import {
+  createSubagentDepthLimitError,
+  createSubagentDescendantLimitError,
+  getMaxRootDescendants,
+  getMaxSubagentDepth,
+  resolveSubagentSpawnContext,
+  type SubagentSpawnContext,
+} from "./subagent-spawn-limits"

 type OpencodeClient = PluginInput["client"]

@@ -115,6 +123,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()

@@ -139,10 +148,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,
@@ -155,16 +196,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,
@@ -209,7 +262,7 @@ export class BackgroundManager {
    // Trigger processing (fire-and-forget)
    this.processKey(key)

-    return task
+    return { ...task }
  }

  private async processKey(key: string): Promise<void> {
@@ -885,6 +938,7 @@ export class BackgroundManager {
        }
      }

+      this.rootDescendantCounts.delete(sessionID)
      SessionCategoryRegistry.remove(sessionID)
    }

@@ -1625,6 +1679,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()
@@ -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.`
+  )
+}
@@ -20,11 +20,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