feat(task): add subagent-to-subagent delegation with persistent sessions

NamedIdentity · claude · NamedIdentity · commit ff5ab1f44370 · 2026-01-22T20:38:17.000-06:00
Adds support for subagents to delegate tasks to other subagents with
configurable call budgets and session persistence. This enables:

1. Subagent-to-subagent task delegation via Task tool
2. Session persistence across multiple task calls
3. Per-session budget tracking to prevent infinite loops
4. Permission-based delegation control

Key Changes:
- config.ts: Add task_budget field to agent schema
- agent.ts: Add task_budget to Agent.Info type and config mapping
- task.ts: Implement budget tracking, session ownership checks,
  and bypassAgentCheck fix for subagent-to-subagent delegation
- Add task-delegation.test.ts with 6 unit tests (all passing)

Configuration:
- Set task_budget &gt; 0 on agents that should delegate
- Use permission.task rules for granular delegation control
- Remove tools: { task: true } from agent frontmatter

Security:
- Default behavior unchanged (delegation disabled)
- Budget system provides hard stop for runaway delegation
- Permission checks always enforced for subagent-to-subagent calls

Tests: 6/6 passing
Typecheck: Clean

Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/packages/opencode/src/agent/agent.ts b/packages/opencode/src/agent/agent.ts
@@ -39,6 +39,7 @@ export namespace Agent {
       prompt: z.string().optional(),
       options: z.record(z.string(), z.any()),
       steps: z.number().int().positive().optional(),
+      task_budget: z.number().int().nonnegative().optional(),
     })
     .meta({
       ref: "Agent",
@@ -220,6 +221,7 @@ export namespace Agent {
       item.hidden = value.hidden ?? item.hidden
       item.name = value.name ?? item.name
       item.steps = value.steps ?? item.steps
+      item.task_budget = value.task_budget ?? item.task_budget
       item.options = mergeDeep(item.options, value.options ?? {})
       item.permission = PermissionNext.merge(item.permission, PermissionNext.fromConfig(value.permission ?? {}))
     }
diff --git a/packages/opencode/src/config/config.ts b/packages/opencode/src/config/config.ts
@@ -573,6 +573,14 @@ export namespace Config {
         .boolean()
         .optional()
         .describe("Hide this subagent from the @ autocomplete menu (default: false, only applies to mode: subagent)"),
+      task_budget: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe(
+          "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).",
+        ),
       options: z.record(z.string(), z.any()).optional(),
       color: z
         .string()
@@ -599,6 +607,7 @@ export namespace Config {
         "top_p",
         "mode",
         "hidden",
+        "task_budget",
         "color",
         "steps",
         "maxSteps",
diff --git a/packages/opencode/src/tool/task.ts b/packages/opencode/src/tool/task.ts
@@ -11,6 +11,24 @@ import { iife } from "@/util/iife"
 import { defer } from "@/util/defer"
 import { Config } from "../config/config"
 import { PermissionNext } from "@/permission/next"
+import { Instance } from "../project/instance"
+
+// Track task calls per session: Map<sessionID, count>
+// Budget is per-session (all calls within the delegated work count toward the limit)
+// Note: State grows with sessions but entries are small. Future optimization:
+// clean up completed sessions via Session lifecycle hooks if memory becomes a concern.
+const taskCallState = Instance.state(() => new Map<string, number>())
+
+function getCallCount(sessionID: string): number {
+  return taskCallState().get(sessionID) ?? 0
+}
+
+function incrementCallCount(sessionID: string): number {
+  const state = taskCallState()
+  const newCount = (state.get(sessionID) ?? 0) + 1
+  state.set(sessionID, newCount)
+  return newCount
+}
 
 const parameters = z.object({
   description: z.string().describe("A short (3-5 words) description of the task"),
@@ -41,8 +59,13 @@ export const TaskTool = Tool.define("task", async (ctx) => {
     async execute(params: z.infer<typeof parameters>, ctx) {
       const config = await Config.get()
 
+      // Get caller's session to check if this is a subagent calling
+      const callerSession = await Session.get(ctx.sessionID)
+      const isSubagent = callerSession.parentID !== undefined
+
       // Skip permission check when user explicitly invoked via @ or command subtask
-      if (!ctx.extra?.bypassAgentCheck) {
+      // BUT: always check permissions for subagent-to-subagent delegation
+      if (!ctx.extra?.bypassAgentCheck || isSubagent) {
         await ctx.ask({
           permission: "task",
           patterns: [params.subagent_type],
@@ -54,40 +77,79 @@ export const TaskTool = Tool.define("task", async (ctx) => {
         })
       }
 
-      const agent = await Agent.get(params.subagent_type)
-      if (!agent) throw new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`)
+      const targetAgent = await Agent.get(params.subagent_type)
+      if (!targetAgent) throw new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`)
+
+      // Get caller agent info for budget check (ctx.agent is just the name)
+      const callerAgentInfo = ctx.agent ? await Agent.get(ctx.agent) : undefined
+
+      // Get config values:
+      // - task_budget on CALLER: how many calls the caller can make per session
+      const callerTaskBudget = callerAgentInfo?.task_budget ?? 0
+
+      // Get target's task_budget once (used for session permissions and tool availability)
+      const targetTaskBudget = targetAgent.task_budget ?? 0
+
+      // Check session ownership BEFORE incrementing budget (if session_id provided)
+      // This prevents "wasting" budget on invalid session resume attempts
+      if (isSubagent && params.session_id) {
+        const existingSession = await Session.get(params.session_id).catch(() => undefined)
+        if (existingSession && existingSession.parentID !== ctx.sessionID) {
+          throw new Error(
+            `Cannot resume session: not a child of caller session. ` +
+            `Session "${params.session_id}" is not owned by this caller.`,
+          )
+        }
+      }
+
+      // Enforce nested delegation controls only for subagent-to-subagent calls
+      if (isSubagent) {
+        // Check 1: Caller must have task_budget configured
+        if (callerTaskBudget <= 0) {
+          throw new Error(
+            `Caller has no task budget configured. ` +
+            `Set task_budget > 0 on the calling agent to enable nested delegation.`,
+          )
+        }
 
-      const hasTaskPermission = agent.permission.some((rule) => rule.permission === "task")
+        // Check 2: Budget not exhausted for this session
+        const currentCount = getCallCount(ctx.sessionID)
+        if (currentCount >= callerTaskBudget) {
+          throw new Error(
+            `Task budget exhausted (${currentCount}/${callerTaskBudget} calls). ` +
+            `Return control to caller to continue.`,
+          )
+        }
+
+        // Increment count after passing all checks (including ownership above)
+        incrementCallCount(ctx.sessionID)
+      }
 
       const session = await iife(async () => {
         if (params.session_id) {
           const found = await Session.get(params.session_id).catch(() => {})
-          if (found) return found
+          if (found) {
+            // Ownership already verified above for subagents
+            return found
+          }
+        }
+
+        // Build session permissions
+        const sessionPermissions: PermissionNext.Rule[] = [
+          { permission: "todowrite", pattern: "*", action: "deny" },
+          { permission: "todoread", pattern: "*", action: "deny" },
+        ]
+
+        // Only deny task if target agent has no task_budget (cannot delegate further)
+        if (targetTaskBudget <= 0) {
+          sessionPermissions.push({ permission: "task", pattern: "*", action: "deny" })
         }
 
         return await Session.create({
           parentID: ctx.sessionID,
-          title: params.description + ` (@${agent.name} subagent)`,
+          title: params.description + ` (@${targetAgent.name} subagent)`,
           permission: [
-            {
-              permission: "todowrite",
-              pattern: "*",
-              action: "deny",
-            },
-            {
-              permission: "todoread",
-              pattern: "*",
-              action: "deny",
-            },
-            ...(hasTaskPermission
-              ? []
-              : [
-                  {
-                    permission: "task" as const,
-                    pattern: "*" as const,
-                    action: "deny" as const,
-                  },
-                ]),
+            ...sessionPermissions,
             ...(config.experimental?.primary_tools?.map((t) => ({
               pattern: "*",
               action: "allow" as const,
@@ -130,7 +192,7 @@ export const TaskTool = Tool.define("task", async (ctx) => {
         })
       })
 
-      const model = agent.model ?? {
+      const model = targetAgent.model ?? {
         modelID: msg.info.modelID,
         providerID: msg.info.providerID,
       }
@@ -149,11 +211,12 @@ export const TaskTool = Tool.define("task", async (ctx) => {
           modelID: model.modelID,
           providerID: model.providerID,
         },
-        agent: agent.name,
+        agent: targetAgent.name,
         tools: {
           todowrite: false,
           todoread: false,
-          ...(hasTaskPermission ? {} : { task: false }),
+          // Only disable task if target agent has no task_budget (cannot delegate further)
+          ...(targetTaskBudget <= 0 ? { task: false } : {}),
           ...Object.fromEntries((config.experimental?.primary_tools ?? []).map((t) => [t, false])),
         },
         parts: promptParts,
diff --git a/packages/opencode/test/task-delegation.test.ts b/packages/opencode/test/task-delegation.test.ts
@@ -0,0 +1,192 @@
+import { describe, test, expect } from "bun:test"
+import { Config } from "../src/config/config"
+import { Instance } from "../src/project/instance"
+import { Agent } from "../src/agent/agent"
+import { PermissionNext } from "../src/permission/next"
+import { tmpdir } from "./fixture/fixture"
+
+describe("task_budget configuration (caller)", () => {
+  test("task_budget is preserved from config", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+      config: {
+        agent: {
+          orchestrator: {
+            description: "Agent with high task budget",
+            mode: "subagent",
+            task_budget: 20,
+          },
+        },
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const config = await Config.get()
+        const agentConfig = config.agent?.["orchestrator"]
+        expect(agentConfig?.task_budget).toBe(20)
+      },
+    })
+  })
+
+  test("task_budget of 0 is preserved (disabled)", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+      config: {
+        agent: {
+          "disabled-agent": {
+            description: "Agent with explicitly disabled budget",
+            mode: "subagent",
+            task_budget: 0,
+          },
+        },
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const config = await Config.get()
+        const agentConfig = config.agent?.["disabled-agent"]
+        expect(agentConfig?.task_budget).toBe(0)
+      },
+    })
+  })
+
+  test("missing task_budget defaults to undefined (disabled)", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+      config: {
+        agent: {
+          "default-agent": {
+            description: "Agent without task_budget",
+            mode: "subagent",
+          },
+        },
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const config = await Config.get()
+        const agentConfig = config.agent?.["default-agent"]
+        expect(agentConfig?.task_budget).toBeUndefined()
+      },
+    })
+  })
+})
+
+describe("task_budget with permissions config", () => {
+  test("task_budget with permission rules for selective delegation", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+      config: {
+        agent: {
+          orchestrator: {
+            description: "Coordinates other subagents",
+            mode: "subagent",
+            task_budget: 20,
+            permission: {
+              task: {
+                "*": "deny",
+                "worker-a": "allow",
+                "worker-b": "allow",
+              },
+            },
+          },
+          "worker-a": {
+            description: "Worker with medium budget",
+            mode: "subagent",
+            task_budget: 3,
+            permission: {
+              task: {
+                "*": "deny",
+                "worker-b": "allow",
+              },
+            },
+          },
+          "worker-b": {
+            description: "Worker with minimal budget",
+            mode: "subagent",
+            task_budget: 1,
+            permission: {
+              task: {
+                "*": "deny",
+                "worker-a": "allow",
+              },
+            },
+          },
+        },
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const config = await Config.get()
+
+        // Orchestrator: high budget
+        const orchestratorConfig = config.agent?.["orchestrator"]
+        expect(orchestratorConfig?.task_budget).toBe(20)
+
+        // Verify permission rules
+        const orchestratorRuleset = PermissionNext.fromConfig(orchestratorConfig?.permission ?? {})
+        expect(PermissionNext.evaluate("task", "worker-a", orchestratorRuleset).action).toBe("allow")
+        expect(PermissionNext.evaluate("task", "worker-b", orchestratorRuleset).action).toBe("allow")
+        expect(PermissionNext.evaluate("task", "orchestrator", orchestratorRuleset).action).toBe("deny")
+
+        // Worker-A: medium budget
+        const workerAConfig = config.agent?.["worker-a"]
+        expect(workerAConfig?.task_budget).toBe(3)
+
+        // Worker-B: minimal budget
+        const workerBConfig = config.agent?.["worker-b"]
+        expect(workerBConfig?.task_budget).toBe(1)
+      },
+    })
+  })
+})
+
+describe("backwards compatibility", () => {
+  test("agent without delegation config has defaults (disabled)", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+      config: {
+        agent: {
+          "legacy-agent": {
+            description: "Agent without delegation config",
+            mode: "subagent",
+          },
+        },
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const config = await Config.get()
+        const agentConfig = config.agent?.["legacy-agent"]
+
+        // Should be undefined/falsy = delegation disabled
+        const taskBudget = (agentConfig?.task_budget as number) ?? 0
+
+        expect(taskBudget).toBe(0)
+      },
+    })
+  })
+
+  test("built-in agents should not have delegation config by default", async () => {
+    await using tmp = await tmpdir({
+      git: true,
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        // Get the built-in general agent
+        const generalAgent = await Agent.get("general")
+
+        // Built-in agents should not have delegation configured
+        const taskBudget = generalAgent?.task_budget ?? 0
+
+        expect(taskBudget).toBe(0)
+      },
+    })
+  })
+})
