Introduction

In DeepSeek Harness (DSH), the workflow engine’s maxConcurrentAgents and maxTotalAgents only apply to agent() calls within workflows. For direct calls at the root level outside workflows, or for background/resumable tasks, DSH lacks process-level concurrency limits. maxParallelToolCalls limits the concurrency pool for tool dispatch, not the number of actively running tasks.

The dsh-subagent-concurrency-limit plugin aims to fill this gap. It limits the concurrency of root-level delegation admission and local subagent turns within the same process.

Plugin Overview

Name: dsh-subagent-concurrency-limit
Author: blauerberg
Positioning: DeepSeek Harness workflow plugin
Core functionality: Limits concurrent subagent runs and local subagent turns within the same process. The root agent is not counted toward the limit.

Core Features

  • Process-level limits: Applies concurrency control to delegation tools with delegationDepthOf(agent) > 0 and local subagent turns within the same process.
  • FIFO queue: Delegation calls from the root agent wait in first-in, first-out (FIFO) order.
  • Custom tool names: Supports specifying non-standard delegation tool names via the subagentToolNames configuration.
  • Cordis Patch integration: Integrates into DSH using the Cordis Patch mechanism.
  • Nested and remote support: Applies to nested subagents and remote process providers (such as Codex).

Installation and Activation

Installing the plugin requires specifying a profile (the example uses web) and a specific commit hash:

dsh plugin --profile web add github:blauerberg/dsh-subagent-concurrency-limit#01182275695067510a187cb05b46df49e5fe812c

After installation, add the configuration to the profile’s Cordis Patch file:

- id: subagent-concurrency-limit
  name: dsh-subagent-concurrency-limit
  config:
    maxConcurrentSubagents: 2
    subagentToolNames:
      - subagent

Start the profile:

dsh --profile web

Usage Notes

  • Concurrency pool: All eligible agents in the process (delegation depth > 0) share the same concurrency pool.
  • FIFO waiting: When the concurrency pool is full, root-agent delegation calls enter the waiting queue.
  • Nested behavior: Nested subagent calls also consume the concurrency pool. If the pool is full, subagent calls fail immediately without waiting, which prevents blocking ancestor agents that are already waiting.
  • Workflow calls: agent() calls in workflows and resumed local subagent turns use this concurrency pool when they start.
  • Resource release: A permit is released when a subagent turn becomes idle, a run ends, or an agent is destroyed.

Important Notes

  • Default limit: The default concurrency limit is 2.
  • Configuration constraints: maxConcurrentSubagents must be a positive integer; subagentToolNames must contain at least one non-empty tool name.
  • Root agent not counted: The root agent itself does not consume concurrency quota.
  • Remote process limits: For remote process providers (such as Codex, Claude Code, and ACP), only configured root-level delegation admission and observable subagent/start and subagent/end boundaries can be counted. Nested execution and restarts inside remote processes cannot be counted.
  • Independent limit: The maxParallelToolCalls limit is independent. It limits tool calls, not actively running tasks.

Conclusion

By controlling process-internal concurrency resources, this plugin helps developers prevent subagents from exhausting system resources. Developers can view more details on the plugin directory page or inspect the source code in the GitHub repository.

Directory page: dsh-subagent-concurrency-limit - SkillHub
Source code: github.com/blauerberg/dsh-subagent-concurrency-limit