microsoft / microsoft/vscode

Allow configuring the maximum number of concurrent subagents

Open
#336,440 0 comments 0 reactions 1 assignee Claimed by @roblourens View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.