[FEATURE]: Cap how many subagents one session runs at once #63303

• I have verified this feature I'm about to request hasn't been suggested before.

Implemented in #63227 (feat(core): bound subagent concurrency), ready for review.

The gap today

subagent fan-out is unbounded. A model that emits five subagent calls in one step gets five child sessions running at the same time, each with its own prompt cache key and its own context, and nothing in config bounds that. On a metered key that is a visible cost jump for work one agent could have done, and on a small machine it is five competing processes plus the parent. The only related knob, experimental.subagent_depth, bounds nesting depth, not how many run at once.

What the enhancement adds

A cap on how many of one session's subagents run at once, settable from every config layer plus a startup switch, with a chosen over-limit behavior:

{
  "experimental": {
    "subagent_concurrency": 2,
    "subagent_over_limit": "wait",
  },
}

Why it is worth merging now

• It ships in feat(core): bound subagent concurrency #63227 with tests and docs, not as a sketch: 82 passing test cases across four files, including a new packages/core/test/session-subagent-job.test.ts for slot and queue semantics, plus the "Subagent concurrency" section in the config docs.
• Non-breaking by construction. The elected default reproduces today's behavior exactly, so nothing changes until a config sets a key, and the unlimited path carries no bookkeeping at all. No new feature flag is needed.
• Small surface. Two optional keys on the existing experimental block, one env var read ahead of config the way OPENCODE_FLAGS already works, and a per-parent slot registry inside the existing SubagentJob service rather than a new service.
• Correct at the edges. A slot is taken before the child session is created, so a rejected call leaves no orphan session; release is idempotent and owned either by the call fiber or by the backgrounded child's completion observer; a follow-up on a running child keeps its existing slot instead of budgeting a second one; at a cap of 0 the tool leaves the advertised list so the model is never offered a call that can only fail.
• The Windows check-test timeout from the first CI run is already fixed on the same branch (fix(core): use the in-memory watcher in the plugin test layer): the plugin fixture used the native watcher, whose only bound is an Effect.timeout that TestClock leaves inert. The full core suite shows an identical failure-name set before and after the change.

Same ask as the earlier reports, now with a working implementation attached: #27110 (max parallel subagents), #54935 (uncapped parallel subagents cost more than one agent) and #50563 (the sibling case, parallel tool calls inside one step).

Requested labels: enhancement, core. Will close with #63227.