dsh-subagent-concurrency-limit
Limit how many DeepSeek Harness subagent runs and local child-agent turns run at
the same time in one process. The root Agent is not counted.
Why it is needed
In DeepSeek Harness dsh-v0.1.1-rc.2 (commit
b150a551b8d465e31e418e1b2eaf5e79bbb7d28e), the workflow
engine's maxConcurrentAgents and maxTotalAgents apply to
agent() calls inside each workflow run. The standard
subagent tool has no process-wide limit for root-level direct
runs outside a workflow. maxParallelToolCalls limits the
dispatch pool for parallel-safe tool calls in one Agent step, not the number of
background or continuable runs.
This plugin fills that gap by limiting concurrent root delegation admissions and
local descendant Agent turns in one process.
Scope
The plugin limits the delegation tools listed in subagentToolNames and local
Agent turns in the same process where delegationDepthOf(agent) > 0. They share
one process-local pool. The default limit is 2.
- A root Agent's delegation call waits in FIFO order before creating a child.
- Add nonstandard delegation tool names to
subagentToolNames.
- Nested children that call the same delegation tool also consume the pool. If a
permit is available, they take it immediately; when the pool is full, they
fail without waiting so a child cannot block the ancestor that is waiting for
it.
- Workflow
agent() calls and resumed local child turns use the same pool when
their Agent turn starts.
- A permit is released when the child turn becomes idle, the run ends, or the
Agent is disposed.
- Pool waits are bounded: a root delegation call or a resumed local child turn
that has been queued for
queueTimeoutMs (default 300000, five minutes) fails
with a clear error instead of waiting forever.
- A locally published child whose reservation was lost (for example a
background job that published outside the delegating call's async context)
never queues: it takes a permit immediately when one is free and fails loudly
when the pool is full, so it cannot block the ancestor that is waiting for
it.
- For remote-process providers such as Codex, Claude Code, and ACP, only the
configured root delegation admission and the observable
subagent/start and
subagent/end boundaries are visible. Nested execution and restarts inside
the remote process cannot be counted.
maxParallelToolCalls is independent because it limits tool calls, not live
runs.
Install
These examples use the web profile. Replace web with your profile name in
each command and path.
Install the plugin:
dsh plugin --profile web add dsh-subagent-concurrency-limit
Add the plugin configuration to
$DSH_HOME/profiles/web/cordis.patch.yml:
- id: subagent-concurrency-limit
name: dsh-subagent-concurrency-limit
config:
maxConcurrentSubagents: 2
queueTimeoutMs: 300000
subagentToolNames:
- subagent
maxConcurrentSubagents must be a positive safe integer.
queueTimeoutMs must be a positive safe integer; the default is 300000 (five
minutes), which bounds every pool wait.
subagentToolNames must contain at least one nonempty delegation tool name.
The bundle patch applies the defaults above; edit the same keys to override
them.
Start the profile:
dsh --profile web
Update
To update the installed plugin to the latest npm release, run:
dsh plugin --profile web add dsh-subagent-concurrency-limit@latest
Restart the profile after updating.
Development
pnpm install
pnpm run check
To inspect the package before publishing:
npm pack --dry-run
prepare builds lib/ when packing or publishing. npm publish runs the
checks through prepublishOnly before publishing to npm.
License
The project is licensed under MIT.
Harness compatibility
This version targets DeepSeek Harness 0.2.0-rc.2.
