Allow configuring the maximum number of concurrent subagents
- Dominant language
- TypeScript
- Stars
- 193k
- Forks
- 42.4k
- PR merge metrics
- PR metrics pending
Description
### Problem
The number of concurrently running subagents is capped at **4**, and there is no way to change it.
Spawning a 5th concurrent agent fails with:
```
Maximum concurrent agent limit of 4 reached. Wait for existing agents to complete before spawning new ones.
```
The cap is **global across the entire agent tree**, which makes it much more restrictive than it first appears:
- A parent counts itself as running, so a parent plus 3 siblings already fills the budget.
- Child agents consume slots too, so nesting competes with top-level parallelism.
- With 5 parents live, **zero** nesting is possible — every child spawn is rejected until a parent finishes.
In practice this means a workflow that wants "5 parallel workers, each with a helper" cannot run at all, even though the machine and the model backend are perfectly capable of it. The failure is also not queued — the spawn is rejected outright, so the parent has to poll and retry.
### Proposed change
Expose a setting for the maximum number of concurrent subagents, for example:
```jsonc
// Default 4, matching today's behavior
"github.copilot.chat.subagents.maxConcurrent": 4
```
Considerations:
- A documented upper bound is fine; the point is that 4 should not be the only option.
- `chat.subagents.maxDepth` already exists as a precedent for a subagent tuning setting, so this would be consistent with the existing surface.
- If a hard ceiling is required for cost or capacity reasons, a clear error message naming the ceiling would help users understand why their value was clamped.
- Ideally the limit would be per-session or per-tree rather than process-wide, so unrelated sessions do not starve each other.
### Additional context
- The limiter is constructed locally in the SDK runtime from the Copilot auth/plan tier, so it is **not** affected by swapping the model provider (BYOK / custom gateway). Users on a custom model endpoint still get 4.
- The plumbing for a configurable limit appears to already exist: `TaskRegistry` exposes `setSubAgentLimiter()` and `updateSubAgentMaxConcurrent()`, and the session accepts an injectable `subAgentLimiter`. It just is not surfaced to users.
- Nested children are currently tool-stripped (no `task`, no `read_agent`), which caps nesting at depth 2 regardless of `chat.subagents.maxDepth`. Worth clarifying whether that is intentional — see #335257.
### Related
- #288048 — Live Subagents Panel (tree view of running subagents)
- #326533 — Improve visibility into long-running subagent activity
- #317392 — Support read-only sub-sessions for viewing sub-agent chats
- #289427 — Agent doesn't use enough subagents when research/tasks can be done parallel
Contributor guide
Assessment
This issue has not been assessed yet.