dsh-plugin-product-subagents

English | 简体中文

Role-based Codex / Claude Code / ACP subagent providers for the DeepSeek
Harness. Turns external agent CLIs into durable, continuable subagents with a
declarative role library, per-role product permissions, delegation with a
permission ceiling, and cross-platform process launching.

Features

• Continuable children — one-shot sync or async continuable (control with
  send_message, list_agents, interrupt_agent; attach synchronously with
  product_wait).
• Session continuity — a child's remote product session survives idle
  disposal and process restarts (durable registry + log markers; claude/codex
  resume by id, ACP reconnects).
• Declarative roles (roles/*.json) — general (default), code-review,
  explore (never delegates), debug. Delegation defaults ON; a role can ban
  it. Unknown roles fall back to general.
• Two-layer permission model — the relay model is always a read-only
  pipe; permissionMode (readonly / default / full) applies to the
  remote product and is mapped to each product's own CLI flags.
• Permission ceiling — a child can never spawn a descendant with more
  permission than it has.
• Any ACP agent — add Cursor (agent acp), CodeBuddy (cbc --acp),
  Gemini (gemini --acp) and more via config.providers; no code needed.
• Resource management — idle disposal, configurable timeouts, concurrency
  cap.
• Cross-platform — Windows .cmd shims, Windows-safe path escaping;
  CI runs macOS / Ubuntu / Windows.

Requirements

• A DeepSeek Harness deployment (web profile).
• At least one product CLI on PATH and authenticated: claude, codex, or
  an ACP CLI (opencode, agent, cbc, …).
• Node ≥ 18.

Install

Install via your agent (one line)

Paste this to your DeepSeek Harness agent (or any coding agent with shell and
file access to the harness home) — it performs every step itself:

Install the dsh-plugin-product-subagents plugin into my DeepSeek Harness
web profile: run npm i dsh-plugin-product-subagents in
~/.dsh/profiles/web, then append this row to
~/.dsh/profiles/web/cordis.patch.yml —
- insert: [{id: product-subagents, name: 'dsh-plugin-product-subagents', config: {idleTimeoutMs: 600000}}] —
then tell me to restart the harness so the plugin loads.

That one prompt covers: installing the package into the profile, wiring the
host-plane row, and flagging the required restart. (Before the package is
published, use the local variant: point the row's name at this repo's
lib/index.js instead of the package name.)

Manual

npm i dsh-plugin-product-subagents

Then add a host-plane row to your profile's cordis.patch.yml:

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

Quick start

In a session, the model has six tools:

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

Configuration

config:
  providers: { cursor: { type: acp, command: agent, args: [acp] } }
  idleTimeoutMs: 600000       # settled children release their remote session
                              # after this idle period (0 disables)
  maxConcurrentChildren: 8    # cap on simultaneous continuable children
  rolesDir: <path>            # declarative role library (default: roles/)
  registryPath: <path>        # durable remote-session registry

Roles and permissions

Each role file:

{
  "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. …"
}

• permissionMode maps to product flags: readonly (claude
  --permission-mode plan / codex --sandbox read-only), full (claude
  --dangerously-skip-permissions / codex
  --dangerously-bypass-approvals-and-sandbox).
• The relay model never gets write-capable tools, in every role.
• Delegation is capped: readonly < default < full; a child cannot spawn
  a descendant with a higher mode.

Custom ACP providers

config.providers accepts any ACP-capable CLI — the generic bridge handles a
persistent process, session/load resume, and dead-process reconnect:

providers:
  cursor:    { type: acp, command: agent, args: [acp] }    # Cursor CLI
  codebuddy: { type: acp, command: cbc, args: [--acp] }    # CodeBuddy
  gemini:    { type: acp, command: gemini, args: [--acp] } # Gemini CLI
  opencode:  { type: acp, command: opencode, args: [acp] } # opencode

Providers appear in the delegation enum only when their command is detected
on PATH. Built-ins (claude-code, codex, acp) can be overridden with
the same keys.

Development

npm install
npm test        # node:test — pure logic + fake bridge, no CLIs or keys
npm run lint    # syntax-check every module

See docs/ARCHITECTURE.md for the bridge contract, the
permission model, and how to add products. CI runs the suite on macOS /
Ubuntu / Windows × Node 18/20/22.

Security

This is a configuration-as-trust-boundary tool: it spawns whatever CLIs
you configure, and full passes the products' own "bypass all permission
checks" flags. See SECURITY.md.

License

MIT