Preface

When handling complex tasks in DeepSeek Harness (DSH), the common approaches are to have the main model directly call tools or manually write a layer of sub-agent orchestration. The former often wastes the session capabilities of external products like Codex and Claude Code; the latter requires handling process lifecycle, session recovery, and permission boundaries yourself.

dsh-plugin-product-subagents takes a different path: it registers installed and logged-in external Agent CLIs as DSH sub-agent providers, uses a declarative role library to describe “who does what, what they can do, and whether they can delegate further,” and exposes a set of unified tools within the Harness session. The main model remains a read-only relay, with write permissions and delegation limits delegated to the remote products.

Below, we explain what this plugin can do and what scenarios it’s suitable for, covering installation, tool usage, and the permission model.

What This Is

In one sentence: a role-based Codex / Claude Code / ACP sub-agent provider for DSH. It transforms external Agent CLIs into sub-agents that can be synchronized, continued, and have their sessions restored, while providing role-based product permissions and delegation capabilities with limits.

Core Features

Continuable Sub-agents

Subtasks can be executed synchronously all at once or asynchronously and continued. In continuation scenarios, the model controls sub-agents via send_message, list_agents, and interrupt_agent; when synchronous results are needed, it hooks up product_wait.

Session Persistence and Recovery

Remote product sessions associated with sub-agents can be recovered after idle reclamation or process restarts: the plugin uses a persistent registry and log markers to track sessions; Claude Code / Codex resume by ID, while ACP providers reconnect.

Declarative Role Library

Roles are defined in roles/*.json and include built-in ones:

  • general (default)
  • code-review
  • explore (no delegation)
  • debug

Delegation is enabled by default but can be disabled for individual roles. Unknown roles fall back to general.

Two-Layer Permissions and Delegation Limits

  • Relay Model: In any role, it only has a read-only pipeline and does not acquire write-capable tools.
  • Remote Products: Controlled by the role’s permissionMode, which can be readonly, default, or full, and maps to each product’s own CLI parameters.
  • Delegation Limits: Sub-agents cannot generate descendants with higher permissions than their own (readonly < default < full).

Any ACP Provider

In addition to the built-in claude-code, codex, and acp, you can declare ACP CLIs such as Cursor (agent acp), CodeBuddy (cbc --acp), and Gemini (gemini --acp) in config.providers without modifying the plugin code. Only commands detected on PATH will appear in the delegation enumeration.

Resources and Cross-Platform Support

Supports idle reclamation, configurable timeouts, and concurrency limits (maxConcurrentChildren). Windows provides .cmd shims and safe path escaping; CI covers macOS, Ubuntu, and Windows.

Environment Requirements

  • DSH deployed (web profile)
  • At least one authenticated product CLI on PATH: claude, codex, or an ACP CLI (e.g., opencode, agent, cbc)
  • Node ≥ 18

Installation and Enablement

It is recommended to install using dsh plugin add. This command installs the package and automatically writes the host-plane line via cordis.patch.yml declared in package.json, without manually modifying profile patches.

dsh plugin --profile web add dsh-plugin-product-subagents

After installation, restart Harness for the plugin to load.

To customize ACP providers or idle timeouts, override the product-subagents line in the profile’s cordis.patch.yml (e.g., ~/.dsh/profiles/web/cordis.patch.yml). Note: configuration overrides replace the entire config object, so keys to retain must be written together.

- id: product-subagents
  config:
    idleTimeoutMs: 600000
    providers:
      cursor:    { type: acp, command: agent, args: [acp] }
      codebuddy: { type: acp, command: cbc, args: [--acp] }

Advanced users can also manually install in the profile directory using pnpm and then insert the cordis.patch.yml line; the README recommends using pnpm over npm to avoid automatically installing peer dependencies.

Typical Usage

After installation and restart, six tools will appear in the session:

Tool Purpose
product_delegate Delegate tasks by role (synchronous or continuable)
product_roles List the role library
product_submit Send subsequent messages to a continuable sub-agent
subagent_progress View the status and internal traces of a single sub-agent
product_wait Block until a sub-agent ends and fetch the response
product_agents View provider availability and active sub-agents

Here is an example of delegation with waiting:

product_delegate role=general task="Refactor demo-project/calc.js and run its tests"
product_wait subagent_id=<childId>

Example role file (excerpt):

{
  "id": "code-review",
  "description": "Review code for bugs, security, maintainability (read-only).",
  "provider": "claude-code",
  "permissionMode": "readonly",
  "allowDelegation": true,
  "instructions": "You are a code reviewer. READ-ONLY: never modify files. …"
}

Correspondence between permissionMode and each product CLI (from README):

  • readonly: Claude --permission-mode plan; Codex --sandbox read-only
  • full: Claude --dangerously-skip-permissions; Codex --dangerously-bypass-approvals-and-sandbox

Configuration Options

config:
  providers: { cursor: { type: acp, command: agent, args: [acp] } }
  idleTimeoutMs: 600000       # How long to keep remote sessions after sub-agents settle (0 means no reclamation)
  maxConcurrentChildren: 8    # Limit on concurrent continuable sub-agents
  rolesDir: <path>            # Role library directory (default: roles/)
  registryPath: <path>        # Path to the remote session registry

Applicable Scenarios and Notes

Who Is It For

  • Those running workflows on DSH web profile who want to integrate CLIs like Claude Code, Codex, or Cursor into unified sub-agent orchestration.
  • Teams needing to switch roles based on task type (code review read-only, exploration no delegation, debugging writable).
  • Scenarios requiring long-running tasks where sub-agent sessions can continue after idle or restart.

Before Use, Please Confirm

  • The plugin launches the CLI you configured with the permissions of the current DSH process user; before installation, it is recommended to read the repository source code and SECURITY.md.
  • permissionMode: full passes each product’s own “skip permission check” parameters, which is a trust boundary by configuration; in production environments, roles and provider lists should be tightened.
  • The SkillHub directory (skillhub.cn/plugins/shaokeyibb/dsh-plugin-product-subagents) is a community index and has no official affiliation with DeepSeek / High-Flyer; refer to the GitHub README and release packages.

Conclusion

dsh-plugin-product-subagents consolidates “external Agent products + declarative roles + permission limits” into a set of reusable sub-agent tools in DSH, suitable for scenarios requiring unified orchestration across Codex, Claude Code, and ACP while keeping write permissions confined to the remote product side.