The core philosophy of DSH is “everything is a plugin.” It adds a delegation boundary on top of the official ctx.subagents to address common issues in subagent invocation, such as uncontrolled depth, role overreach, and concurrency overflow.

What Is This

dsh-agent-delegate is a delegation broker plugin maintained by xingyingyuzhui. It does not provide a control-plane UI; instead, it governs delegation behavior through code logic. It solves the following specific problems:

  • Delegation depth: Counts based on the actual parent chain to prevent infinite nesting.
  • Role attenuation: Limits the role permissions of subagents to avoid permission sprawl.
  • Concurrency budget: Limits the number of unfinished subagents that can exist at the same time.
  • Write isolation: Assigns an independent Git worktree to write-capable subagents to avoid polluting the main workspace.
  • Result merging: Provides a patch mechanism, where the parent task decides whether to merge after acceptance.

Core Capabilities

Depth and Concurrency Control

The plugin counts based on the actual invocation depth of the parent chain. When a subagent is invoked, if the current depth exceeds policy.delegation.maxDepth, the call is rejected directly.

For concurrency, the plugin limits the number of unfinished subagents running parallel write tasks to at most 4 by default. If the number of unfinished child agents existing at the same time exceeds delegation.maxChildren, new delegation requests are also rejected.

Role Filtering and Limitation

A target role can be specified during delegation. The following forms are supported:
* role
* [research] tag
* role: reviewer prompt

The role policy formula for a subagent is child = parent ∩ role preset. If the target role is not present in the delegation.roles configuration, the delegation is rejected directly. For example, by default, the developer role can only delegate to research or reviewer.

Independent Worktree and Handoff

Only write-capable children (for example, configured with files.write: all) are assigned an independent Git worktree for background write tasks. The main session and foreground bash continue to work in the project root.

When creating the worktree, the plugin copies uncommitted changes and non-ignored untracked files from the parent workspace into it. After the subagent task ends, the diff relative to the seed commit is written to ~/.dsh/agent-delegate/handoffs/<id>.patch, and the status is marked as pending. It is not merged automatically.

After the parent task performs acceptance, the delegate_handoff command must be invoked:
* accept: runs git apply against the parent repository (using --3way when necessary). If the merge fails, the status is marked as conflicted, and the parent worktree remains unchanged.
* reject: discards the changes from that delegation.
* list: views all pending handoffs.

Sandbox Constraints

For the research, reviewer, and public roles, or in sandbox.requireEnforcement: full mode, when the sandbox reports partial (partially enforced), the plugin rejects any file actions and does not allow degraded pass-through.

Installation and Enablement

Add the plugin using the official installation command:

dsh plugin --profile web add github:xingyingyuzhui/dsh-agent-delegate

It is recommended to install dsh-session-permissions and dsh-agent-gate as well, and then restart dsh web after installation.

For local development and debugging, you can use a local path:

dsh plugin --profile web add link:/abs/path/to/dsh-agent-delegate

Uninstallation

After uninstallation, the plugin no longer creates worktrees, no longer enforces depth/attenuation interception, and the system falls back to DSH’s original subagent behavior (however, the installed dsh-agent-gate still remains effective).

dsh plugin --profile web remove dsh-agent-delegate

Technical Details

  • Version: 0.2.10
  • Engine requirement: Node.js >= 20
  • License: MIT
  • File size limit: handoffs are truncated to 64KiB by default

Use Cases

Suitable for scenarios that require strict control of subagent permissions in a DSH environment, prevention of infinite recursive calls, and merging of subagent modifications only after manual review in patch form.

For more details and source code, see the GitHub repository.