@@ -84,6 +84,9 @@ export const Info = Schema.Struct({
   subagent_depth: Schema.optional(NonNegativeInt).annotate({
     description: "Maximum subagent nesting depth. Defaults to 1, which prevents subagents from launching subagents.",
   }),
+  subagent_concurrency: Schema.optional(PositiveInt).annotate({
+    description: "Maximum number of subagents that may execute concurrently. Unset allows unlimited concurrency.",
+  }),
   username: Schema.optional(Schema.String).annotate({
     description: "Custom username to display in conversations instead of system username",
   }),
 
@@ -10,7 +10,7 @@ import { Agent } from "../agent/agent"
 import { deriveSubagentSessionPermission } from "../agent/subagent-permissions"
 import type { SessionPrompt } from "../session/prompt"
 import { Config } from "@/config/config"
-import { Effect, Exit, Schema, Scope } from "effect"
+import { Effect, Exit, Schema, Scope, Semaphore } from "effect"
 import { EffectBridge } from "@/effect/bridge"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import { Database } from "@opencode-ai/core/database/database"
@@ -21,6 +21,19 @@ export interface TaskPromptOps {
   prompt(input: SessionPrompt.PromptInput): Effect.Effect<SessionV1.WithParts>
 }
 
+function isTaskPromptOps(value: unknown): value is TaskPromptOps {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "cancel" in value &&
+    typeof value.cancel === "function" &&
+    "resolvePromptParts" in value &&
+    typeof value.resolvePromptParts === "function" &&
+    "prompt" in value &&
+    typeof value.prompt === "function"
+  )
+}
+
 const id = "task"
 const BACKGROUND_DESCRIPTION = [
   "Background mode: background=true launches the subagent asynchronously and returns immediately.",
@@ -88,6 +101,16 @@ export const TaskTool = Tool.define(
     const scope = yield* Scope.Scope
     const flags = yield* RuntimeFlags.Service
     const database = yield* Database.Service
+    const limits = new Map<number, Semaphore.Semaphore>()
+
+    function limit(concurrency: number | undefined) {
+      if (concurrency === undefined) return undefined
+      const current = limits.get(concurrency)
+      if (current) return current
+      const created = Semaphore.makeUnsafe(concurrency)
+      limits.set(concurrency, created)
+      return created
+    }
 
     const run = Effect.fn("TaskTool.execute")(function* (
       params: Schema.Schema.Type<typeof Parameters>,
@@ -194,12 +217,14 @@ export const TaskTool = Tool.define(
         metadata,
       })
 
-      const ops = ctx.extra?.promptOps as TaskPromptOps
-      if (!ops) return yield* Effect.fail(new Error("TaskTool requires promptOps in ctx.extra"))
+      const promptOps = ctx.extra?.promptOps
+      if (!isTaskPromptOps(promptOps)) {
+        return yield* Effect.fail(new Error("TaskTool requires valid promptOps in ctx.extra"))
+      }
 
-      const runTask = Effect.fn("TaskTool.runTask")(function* () {
-        const parts = yield* ops.resolvePromptParts(params.prompt)
-        const result = yield* ops.prompt({
+      const executeTask = Effect.fn("TaskTool.runTask")(function* () {
+        const parts = yield* promptOps.resolvePromptParts(params.prompt)
+        const result = yield* promptOps.prompt({
           messageID: MessageID.ascending(),
           sessionID: nextSession.id,
           model: {
@@ -223,13 +248,15 @@ export const TaskTool = Tool.define(
         }
         return result.parts.findLast((item) => item.type === "text")?.text ?? ""
       })
+      const semaphore = limit(cfg.subagent_concurrency)
+      const runTask = () => (semaphore ? semaphore.withPermit(executeTask()) : executeTask())
 
       const inject = Effect.fn("TaskTool.injectBackgroundResult")(function* (
         state: "completed" | "error",
         text: string,
       ) {
         const currentParent = yield* sessions.get(ctx.sessionID)
-        yield* ops
+        yield* promptOps
           .prompt({
             sessionID: ctx.sessionID,
             agent: currentParent.agent ?? ctx.agent,
@@ -286,14 +313,14 @@ export const TaskTool = Tool.define(
         type: id,
         title: params.description,
         metadata,
-        onPromote: Effect.all([
-          ctx.metadata({
+        onPromote: Effect.gen(function* () {
+          yield* ctx.metadata({
             title: params.description,
             metadata: { ...metadata, background: true, jobId: nextSession.id },
-          }),
-          notify(nextSession.id),
-        ]),
-        run: runTask().pipe(Effect.onInterrupt(() => ops.cancel(nextSession.id))),
+          })
+          yield* notify(nextSession.id)
+        }),
+        run: runTask().pipe(Effect.onInterrupt(() => promptOps.cancel(nextSession.id))),
       })
 
       function backgroundResult() {
@@ -319,7 +346,7 @@ export const TaskTool = Tool.define(
       }
 
       const runCancel = yield* EffectBridge.make()
-      const cancel = ops.cancel(nextSession.id)
+      const cancel = promptOps.cancel(nextSession.id)
 
       function onAbort() {
         runCancel.fork(cancel)
 
@@ -3,7 +3,7 @@ import { SessionV1 } from "@opencode-ai/core/v1/session"
 import { Database } from "@opencode-ai/core/database/database"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { SessionProjector } from "@opencode-ai/core/session/projector"
-import { Cause, Deferred, Effect, Exit, Fiber, Layer } from "effect"
+import { Cause, Deferred, Effect, Exit, Fiber } from "effect"
 import { Agent } from "../../src/agent/agent"
 import { BackgroundJob } from "@/background/job"
 import { EventV2Bridge } from "@/event-v2-bridge"
@@ -545,6 +545,70 @@ describe("tool.task", () => {
     }),
   )
 
+  it.instance(
+    "limits concurrent subagent execution when configured",
+    () =>
+      Effect.gen(function* () {
+        const { chat, assistant } = yield* seed()
+        const tool = yield* TaskTool
+        const def = yield* tool.init()
+        const firstStarted = yield* Deferred.make<void>()
+        const release = yield* Deferred.make<void>()
+        let calls = 0
+        let active = 0
+        let peak = 0
+        const promptOps: TaskPromptOps = {
+          cancel: () => Effect.void,
+          resolvePromptParts: (template) => Effect.succeed([{ type: "text" as const, text: template }]),
+          prompt: (input) =>
+            Effect.gen(function* () {
+              calls++
+              active++
+              peak = Math.max(peak, active)
+              if (calls === 1) yield* Deferred.succeed(firstStarted, undefined)
+              yield* Deferred.await(release)
+              active--
+              return reply(input, "done")
+            }),
+        }
+        const execute = () =>
+          def.execute(
+            {
+              description: "inspect bug",
+              prompt: "look into the cache key path",
+              subagent_type: "general",
+            },
+            {
+              sessionID: chat.id,
+              messageID: assistant.id,
+              agent: "build",
+              abort: new AbortController().signal,
+              extra: { promptOps },
+              messages: [],
+              metadata: () => Effect.void,
+              ask: () => Effect.void,
+            },
+          )
+
+        const first = yield* execute().pipe(Effect.forkChild)
+        yield* Deferred.await(firstStarted)
+        const second = yield* execute().pipe(Effect.forkChild)
+        yield* Effect.yieldNow
+        yield* Effect.yieldNow
+
+        expect(calls).toBe(1)
+        expect(peak).toBe(1)
+
+        yield* Deferred.succeed(release, undefined)
+        yield* Fiber.join(first)
+        yield* Fiber.join(second)
+
+        expect(calls).toBe(2)
+        expect(peak).toBe(1)
+      }),
+    { config: { subagent_concurrency: 1 } },
+  )
+
   it.instance(
     "allows nested subagents up to the configured depth",
     () =>
 
@@ -1936,6 +1936,7 @@ export type Config = {
   small_model?: string
   default_agent?: string
   subagent_depth?: number
+  subagent_concurrency?: number
   username?: string
   mode?: {
     build?: AgentConfig
 
@@ -21290,6 +21290,10 @@
             "type": "integer",
             "minimum": 0
           },
+          "subagent_concurrency": {
+            "type": "integer",
+            "minimum": 1
+          },
           "username": {
             "type": "string"
           },