feat(task): add level_limit to prevent infinite delegation depth

Adds global level_limit configuration to cap subagent session tree depth.
Complements existing task_budget (horizontal limit) with vertical depth
limit for complete loop prevention.

- Add level_limit to experimental config schema (default: 5)
- Add getSessionDepth() helper to calculate session tree depth
- Add depth check before task delegation (Check 3)
- Add 3 unit tests for level_limit configuration
- Regenerate SDK types with level_limit field

Related to PR #7756 (subagent delegation)

Author: NamedIdentity

packages/opencode/src/config/config.ts

@@ -1164,6 +1164,15 @@ export namespace Config {
             .positive()
             .optional()
             .describe("Timeout in milliseconds for model context protocol (MCP) requests"),
+          level_limit: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe(
+              "Maximum depth for subagent session trees. Prevents infinite delegation loops. " +
+              "Default: 5. Set to 0 to disable (not recommended)."
+            ),
         })
         .optional(),
     })

packages/opencode/src/tool/task.ts

@@ -30,6 +30,23 @@ function incrementCallCount(sessionID: string): number {
   return newCount
 }
 
+/**
+ * Calculate session depth by walking up the parentID chain.
+ * Root session = depth 0, first child = depth 1, etc.
+ */
+async function getSessionDepth(sessionID: string): Promise<number> {
+  let depth = 0
+  let currentID: string | undefined = sessionID
+  while (currentID) {
+    const session: Awaited<ReturnType<typeof Session.get>> | undefined = 
+      await Session.get(currentID).catch(() => undefined)
+    if (!session?.parentID) break
+    currentID = session.parentID
+    depth++
+  }
+  return depth
+}
+
 const parameters = z.object({
   description: z.string().describe("A short (3-5 words) description of the task"),
   prompt: z.string().describe("The task for the agent to perform"),
@@ -126,6 +143,18 @@ export const TaskTool = Tool.define("task", async (ctx) => {
           )
         }
 
+        // Check 3: Level limit not exceeded
+        const levelLimit = config.experimental?.level_limit ?? 5  // Default: 5
+        if (levelLimit > 0) {
+          const currentDepth = await getSessionDepth(ctx.sessionID)
+          if (currentDepth >= levelLimit) {
+            throw new Error(
+              `Level limit reached (depth ${currentDepth}/${levelLimit}). ` +
+              `Cannot create deeper subagent sessions. Return control to caller.`
+            )
+          }
+        }
+
         // Increment count after passing all checks (including ownership above)
         incrementCallCount(ctx.sessionID)
       }

packages/opencode/test/task-delegation.test.ts

@@ -190,3 +190,55 @@ describe("backwards compatibility", () => {
     })
   })
 })
+
+describe("level_limit configuration", () => {
+  test("level_limit is preserved from config", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+      config: {
+        experimental: {
+          level_limit: 8,
+        },
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const config = await Config.get()
+        expect(config.experimental?.level_limit).toBe(8)
+      },
+    })
+  })
+
+  test("level_limit defaults to undefined when not set (implementation defaults to 5)", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+      config: {},
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const config = await Config.get()
+        expect(config.experimental?.level_limit).toBeUndefined()
+      },
+    })
+  })
+
+  test("level_limit of 0 is preserved (disabled)", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+      config: {
+        experimental: {
+          level_limit: 0,
+        },
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const config = await Config.get()
+        expect(config.experimental?.level_limit).toBe(0)
+      },
+    })
+  })
+})

packages/sdk/js/src/v2/gen/types.gen.ts

@@ -47,13 +47,6 @@ export type EventProjectUpdated = {
   properties: Project
 }
 
-export type EventServerInstanceDisposed = {
-  type: "server.instance.disposed"
-  properties: {
-    directory: string
-  }
-}
-
 export type EventServerConnected = {
   type: "server.connected"
   properties: {
@@ -68,6 +61,13 @@ export type EventGlobalDisposed = {
   }
 }
 
+export type EventServerInstanceDisposed = {
+  type: "server.instance.disposed"
+  properties: {
+    directory: string
+  }
+}
+
 export type EventLspClientDiagnostics = {
   type: "lsp.client.diagnostics"
   properties: {
@@ -888,9 +888,9 @@ export type Event =
   | EventInstallationUpdated
   | EventInstallationUpdateAvailable
   | EventProjectUpdated
-  | EventServerInstanceDisposed
   | EventServerConnected
   | EventGlobalDisposed
+  | EventServerInstanceDisposed
   | EventLspClientDiagnostics
   | EventLspUpdated
   | EventFileEdited
@@ -993,22 +993,6 @@ export type KeybindsConfig = {
    * Rename session
    */
   session_rename?: string
-  /**
-   * Delete session
-   */
-  session_delete?: string
-  /**
-   * Delete stash entry
-   */
-  stash_delete?: string
-  /**
-   * Open provider list from model dialog
-   */
-  model_provider_list?: string
-  /**
-   * Toggle model favorite status
-   */
-  model_favorite_toggle?: string
   /**
    * Share current session
    */
@@ -1033,14 +1017,6 @@ export type KeybindsConfig = {
    * Scroll messages down by one page
    */
   messages_page_down?: string
-  /**
-   * Scroll messages up by one line
-   */
-  messages_line_up?: string
-  /**
-   * Scroll messages down by one line
-   */
-  messages_line_down?: string
   /**
    * Scroll messages up by half page
    */
@@ -1286,11 +1262,11 @@ export type KeybindsConfig = {
    */
   history_next?: string
   /**
-   * Next child session
+   * Next sibling session
    */
   session_child_cycle?: string
   /**
-   * Previous child session
+   * Previous sibling session
    */
   session_child_cycle_reverse?: string
   /**
@@ -1305,6 +1281,10 @@ export type KeybindsConfig = {
    * Go to root session
    */
   session_root?: string
+  /**
+   * Open session tree dialog
+   */
+  session_child_list?: string
   /**
    * Suspend terminal
    */
@@ -1411,6 +1391,10 @@ export type AgentConfig = {
    * Hide this subagent from the @ autocomplete menu (default: false, only applies to mode: subagent)
    */
   hidden?: boolean
+  /**
+   * Maximum task calls this agent can make per session when delegating to other subagents. Set to 0 to explicitly disable, omit to use default (disabled).
+   */
+  task_budget?: number
   options?: {
     [key: string]: unknown
   }
@@ -1438,6 +1422,7 @@ export type AgentConfig = {
     | "subagent"
     | "primary"
     | "all"
+    | number
     | {
         [key: string]: unknown
       }
@@ -1562,7 +1547,7 @@ export type McpLocalConfig = {
    */
   enabled?: boolean
   /**
-   * Timeout in ms for MCP server requests. Defaults to 5000 (5 seconds) if not specified.
+   * Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds) if not specified.
    */
   timeout?: number
 }
@@ -1606,7 +1591,7 @@ export type McpRemoteConfig = {
    */
   oauth?: McpOAuthConfig | false
   /**
-   * Timeout in ms for MCP server requests. Defaults to 5000 (5 seconds) if not specified.
+   * Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds) if not specified.
    */
   timeout?: number
 }
@@ -1721,7 +1706,7 @@ export type Config = {
     [key: string]: AgentConfig | undefined
   }
   /**
-   * Agent configuration, see https://opencode.ai/docs/agents
+   * Agent configuration, see https://opencode.ai/docs/agent
    */
   agent?: {
     plan?: AgentConfig
@@ -1828,6 +1813,10 @@ export type Config = {
      * Timeout in milliseconds for model context protocol (MCP) requests
      */
     mcp_timeout?: number
+    /**
+     * Maximum depth for subagent session trees. Prevents infinite delegation loops. Default: 5. Set to 0 to disable (not recommended).
+     */
+    level_limit?: number
   }
 }
 
@@ -2170,6 +2159,7 @@ export type Agent = {
     [key: string]: unknown
   }
   steps?: number
+  task_budget?: number
 }
 
 export type LspStatus = {