fix(background-agent): cap recursive subagent spawning

[code-yeongyu]

Summary

• add configurable background_task.maxDepth and background_task.maxDescendants limits, plus the regenerated schema output
• track root session ancestry and enforce launch depth and descendant guards in BackgroundManager
• block sync task and call_omo_agent spawns once nested subagent depth exceeds the configured limit

Testing

• bun test
• bun run typecheck
• bun run build

---

Summary by cubic

Caps recursive subagent spawning by enforcing configurable max depth and per-root descendant limits in BackgroundManager. Addresses Linear #2330 by blocking runaway nested spawns and returning clear, user-facing errors.

• Bug Fixes
  • Added background_task.maxDepth and background_task.maxDescendants (defaults: 3 and 50) to config and schema.
  • Tracked rootSessionID and spawnDepth on tasks; counted descendants per root to enforce limits.
  • Introduced BackgroundManager.assertCanSpawn and used it in call_omo_agent and sync task paths to block over-limit sync and background spawns.
  • Improved tool copy to note depth limits; added tests covering valid/invalid config and spawn blocking.

^{Written for commit 7874669. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 11 files

Confidence score: 3/5

• There is a concrete medium-high risk in src/features/background-agent/subagent-spawn-limits.ts: session retrieval errors are not explicitly handled, which can allow spawn-limit checks to be bypassed during transient failures.
• The severity (7/10) with high confidence (9/10) suggests real user-facing impact under error conditions, so this is not just a cosmetic or housekeeping concern.
• Pay close attention to src/features/background-agent/subagent-spawn-limits.ts - ensure session-fetch failures fail closed so spawn limits are still enforced.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/features/background-agent/subagent-spawn-limits.ts">

<violation number="1" location="src/features/background-agent/subagent-spawn-limits.ts:41">
P1: Explicitly handle session retrieval errors to prevent bypassing spawn limits during transient failures.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: Explicitly handle session retrieval errors to prevent bypassing spawn limits during transient failures.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/features/background-agent/subagent-spawn-limits.ts, line 41:

<comment>Explicitly handle session retrieval errors to prevent bypassing spawn limits during transient failures.</comment>

<file context>
@@ -0,0 +1,79 @@
+      path: { id: currentSessionID },
+    }).catch(() => null)
+
+    const nextParentSessionID = session?.data?.parentID
+    if (!nextParentSessionID) {
+      rootSessionID = currentSessionID
</file context>