Preface¶

DeepSeek Harness (dsh) treats models, tools, sessions, sandboxes and UI as plugins. The official team also provides the dsh-subagent sub-agent contract: the parent session can hand over tasks to Codex, Claude Code, or any CLI that implements the Agent Client Protocol (ACP). In actual use, the common pain point is not “whether it can be started”, but “how to manage it after startup”: whether the subtask is one-off or resumable, whether the remote session remains alive after the process is recycled, whether different roles should be granted read-only or full permissions, and whether permissions will exceed the boundary when the sub-agent assigns tasks further down.

dsh-plugin-product-subagents is designed to solve these problems. It connects external product CLIs to dsh’s sub-agent channel, uses declarative roles to determine who performs the task and what they can do, and adds persistent session recovery for resumable subtasks. Below is a collation cross-checked against the community directory page, GitHub repository README / CHANGELOG / SECURITY, npm package description, and DeepSeek Harness’s official sub-agent documentation: what it is, what it can do after installation, and how to connect it to the current profile.

What is it¶

dsh-plugin-product-subagents is a session and message plugin for DeepSeek Harness, maintained by shaokeyibb. The repository is hosted at shaokeyibb/dsh-plugin-product-subagents, licensed under MIT, and mainly written in JavaScript. As of 2026-08-18, it has 16 stars on GitHub; the current npm version is 0.3.1 (released on 2026-08-17).

One-sentence positioning: A role-based provider for Codex / Claude Code / ACP sub-agents, turning external Agent CLIs into resumable and recoverable sub-agents, with product permissions and delegation ceilings based on roles.

It addresses the following needs:
- Hand over refactoring, code review, and troubleshooting tasks in dsh sessions to logged-in claude, codex, or ACP CLIs such as Cursor / CodeBuddy / Gemini / OpenCode
- Avoid starting a new session from scratch for each subtask, and resume the remote session by session ID after idle recycling or process restart
- Use read-only mode for reviews and exploration tasks, grant full permissions only for general tasks, and prevent sub-agents from spawning descendants with higher permissions than themselves

Two things need to be clarified first. DeepSeek Harness itself is an open-source Agent runtime developed by DeepSeek, whose core concept is “everything is a plugin”. The plugin directory deepseek-harness-plugin.com used in this article is a community site, which has no official affiliation with DeepSeek / HyperMind and cannot be regarded as an official app store. The official runtime also has providers such as dsh-subagent-claude-code and dsh-subagent-acp; this plugin is a community implementation that adds role libraries, permission ceilings, and persistent session registries on top of the official functions.

Core Features¶

The repository README summarizes the capabilities into the following items, which are also consistent with the roles/*.json and package.json in the source code.

Resumable Sub-Agents, Not One-and-Done Tasks¶

Delegation can be synchronous one-shot or asynchronous continuous. Continuous sub-agents can be controlled with send_message, list_agents, and interrupt_agent, and then use product_wait to block and wait for the result.

The model in the session will have access to six tools:

Remote Session Recovery¶

The remote product session corresponding to the sub-agent can be resumed after idle release or process restart. The implementation relies on a persistent registry and log markers: Claude / Codex resume by session ID, while ACP uses reconnection (session/load). The default registry path is ~/.dsh/product-subagents-registry.json as documented in SECURITY.md, which belongs to runtime state and should not be committed to Git.

The idle timeout is controlled by idleTimeoutMs, with the documentation example set to 600000 (10 minutes). Setting it to 0 disables the release mechanism. The upper limit of concurrent continuous sub-agents is maxConcurrentChildren, with the default example set to 8.

Declarative Role Library¶

Roles are stored in roles/*.json and are ready to use out of the box with four built-in roles:

Unknown roles will fall back to general. explore explicitly prohibits further task delegation, making it suitable for read-only code exploration; code-review allows delegating subtasks even though it uses read-only mode.

The structure of a role file is roughly as follows (taking the code-review role from the repository as an example):

{
  "id": "code-review",
  "description": "Code review: inspect defects, security issues and maintainability of changes. Runs the product in read-only mode.",
  "provider": "claude-code",
  "permissionMode": "readonly",
  "allowDelegation": true,
  "instructions": "You are a code reviewer. ..."
}

The custom role directory can be specified elsewhere using the rolesDir configuration item.

Two-Tier Permissions Plus Delegation Ceiling¶

Permissions are not “the model can make changes whenever it wants”:
1. The relay model is always a read-only messenger. The in-process bridge agent does not have write tools, regardless of the role.
2. permissionMode applies to the remote product, with values readonly / default / full, which map to respective CLI flags:
- readonly: Claude uses --permission-mode plan, Codex uses --sandbox read-only
- full: Claude uses --dangerously-skip-permissions, Codex uses --dangerously-bypass-approvals-and-sandbox
3. Delegation has a ceiling: readonly < default < full. A sub-agent cannot spawn descendants with higher permissions than itself.

full enables the product’s own “bypass all permission checks” switch. SECURITY.md states plainly that this level should only be granted to roles that are fully trusted for arbitrary file and command access.

Support Any ACP CLI, Add Providers with Zero Code¶

The built-in three providers are claude-code, codex, and acp. Other ACP-compliant CLIs can be configured via config.providers. The universal bridge handles persistent processes, session/load recovery, and dead process reconnection. The documentation provides the following example:

providers:
  cursor:    { type: acp, command: agent, args: [acp] }
  codebuddy: { type: acp, command: cbc, args: [--acp] }
  gemini:    { type: acp, command: gemini, args: [--acp] }
  opencode:  { type: acp, command: opencode, args: [acp] }

A provider will only appear in the delegation enumeration if its corresponding command is detected in the system PATH. The built-in three providers can be overwritten using the same key names.

Process startup considerations for Windows: .cmd shims and path escaping are handled. CHANGELOG 0.3.0 fixed a Windows quote issue where product_delegate would throw 'claude" -p ...' is not recognized for claude-code / codex. The CI matrix covers macOS / Ubuntu / Windows with Node 18 / 20 / 22.

Installation and Activation¶

The installation command provided by the community directory page can be executed in the DeepSeek Harness terminal:

dsh plugin add github:shaokeyibb/dsh-plugin-product-subagents

For reproducible installations, fix the commit hash as instructed on the directory page:

dsh plugin add github:shaokeyibb/dsh-plugin-product-subagents#commit

Replace #commit with the actual commit SHA from the repository. The plugin runs with the permissions of the current dsh process, and may execute code during installation. You should review the source code and license before installing.

Another recommended path from the author’s README (version 0.3.1) is to install it into the web profile using the npm package name instead of github:owner/repo. Version 0.3.1 declares dsh.bundle in package.json and includes cordis.patch.yml, so dsh plugin add will register it as a profile layer without manual wiring:

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

After installation, restart the harness for the plugin to load.

Environment requirements (from README):
- A deployed DeepSeek Harness instance using the web profile
- At least one logged-in product CLI in the system PATH: claude, codex, or an ACP CLI such as opencode / agent / cbc
- Node ≥ 18

If you want to manage dependencies manually, the README requires using pnpm in the profile directory, not npm: npm will automatically install peer dependencies, which may overwrite the @deepseek-ai/dsh-tools symlink in the host environment. CHANGELOG 0.3.0 fixed this issue (where tool calls would throw Cannot read properties of undefined (reading 'prepare')). The manual installation method is:

cd ~/.dsh/profiles/web
pnpm add dsh-plugin-product-subagents

Then insert the host layer into ~/.dsh/profiles/web/cordis.patch.yml (same structure as the patch included in the repository):

- insert:
    - id: product-subagents
      name: 'dsh-plugin-product-subagents'
      config:
        idleTimeoutMs: 600000

You can also let the current dsh Agent handle it automatically. The hint from the README is: run dsh plugin --profile web add dsh-plugin-product-subagents in the web profile, then restart the harness.

Typical Usage¶

First Check if Roles and Providers Are Ready¶

In the session, ask the model to call product_roles to list the role library, and call product_agents to see which providers are available in the PATH. If Cursor / Codex do not appear in the enumeration, first confirm that the corresponding CLI is installed, logged in, and that the command name matches the config.providers setting.

Delegate a One-Time Task by Role¶

The minimal example from the README:

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

general defaults to full permissions, suitable for actual code changes and test runs. Use code-review or explore for reviews and code exploration to avoid the remote product running with the “bypass permission checks” flag modifying files.

After delegating a continuous subtask, you do not need to block indefinitely: first obtain the childId, then call product_wait when you need the result; you can use subagent_progress to check the status and internal trace mid-task.

Add ACP Providers and Adjust Timeout¶

Custom configuration is written in the profile’s cordis.patch.yml, overwritten by the plugin ID product-subagents. Overwriting will replace the entire config object for that entry, so all required fields must be included together:

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

Full configuration items (from README):

config:
  providers: { cursor: { type: acp, command: agent, args: [acp] } }
  idleTimeoutMs: 600000
  maxConcurrentChildren: 8
  rolesDir: <path>
  registryPath: <path>

The default rolesDir is the packaged roles/ directory; registryPath points to the persistent remote session registry.

Applicable Scenarios and Notes¶

Suitable use cases:
- You are already using Claude Code / Codex / Cursor CLI and want to assign tasks by role in dsh web sessions, rather than relying solely on dsh’s built-in tool loops
- Long tasks require resumable sessions: conduct a code review, then follow up with questions, without rebuilding the remote product session each time
- You want to define roles like “read-only exploration”, “read-only code review”, “default debug permissions”, and “full deployment permissions” in role files, instead of verbally constraining the model each time

Before using, please review the following boundary conditions:
1. The plugin runs with the permissions of the current dsh process. Both the directory page and the security guide note: it may execute code during installation, and can perform any actions that the current process has permission to do. Read the repository source code and MIT license before installing; pin the version with #commit in production environments.
2. This is a “configuration-as-trust-boundary” tool. It will start any CLI you configure and pass process.env to child processes without cleaning secrets. full mode enables the product’s own dangerous flags. Do not add untrusted command entries to providers.
3. The persistent registry is runtime state. The default file ~/.dsh/product-subagents-registry.json maps sub-session IDs to remote product session IDs; do not commit it or distribute it as a configuration template.
4. The web profile and CLI login are prerequisites. Without claude / codex / ACP CLI, the tools will appear in the list but tasks cannot be delegated.
5. Use pnpm for manual package installation. npm will install a separate copy of @deepseek-ai/dsh-tools, overwriting the host singleton. The CHANGELOG also notes that pnpm 11’s default minimumReleaseAge may cause dsh plugin add to pull version 0.2.0; if you encounter tool call errors, explicitly install dsh-plugin-product-subagents@0.3.1.
6. The community directory is not an official store. The entries come from an independent site, and the maintainer and license shall prevail based on the GitHub repository.

Summary¶

dsh-plugin-product-subagents connects Codex, Claude Code, and any ACP CLI to DeepSeek Harness’s sub-agent channel, uses role files to manage permissions, and uses a registry to retain remote sessions. For users who have already logged into these product CLIs locally and want to divide work by review / exploration / troubleshooting / implementation in dsh, this plugin fits the session workflow better than “opening a new CLI window each time”.

Read the source code and license before installing, pin the commit hash as needed, and only grant full permissions to trusted roles. The directory page and repository addresses:
- Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-plugin-product-subagents/
- GitHub: https://github.com/shaokeyibb/dsh-plugin-product-subagents
- npm: https://www.npmjs.com/package/dsh-plugin-product-subagents
- DeepSeek Harness official repository: https://github.com/deepseek-ai/deepseek-harness