dsh-subagent-claude-code-wrapper
English | 中文
Lets DeepSeek Harness (DSH) delegate subagent work to any Claude-compatible CLI binary — not just the SDK-bundled official one.
Forked from DSH's built-in dsh-subagent-claude-code with one added config field: executablePath.
What problem this solves
DSH's built-in subagent-claude-code provider hardcodes the SDK-bundled official Claude Code CLI. But some environments run a different Claude-compatible CLI — an enterprise fork, a self-built binary, a pinned version, or a wrapper script that injects extra flags. This plugin exposes the SDK's existing pathToClaudeCodeExecutable option as a config field, so you don't need to patch DSH source.
DSH doesn't accept external PRs (see its CONTRIBUTING.md); community plugins are the supported way to extend it. This package follows that path: a copy of the built-in provider's source plus one field, shipped as an independent bundle — DSH updates never touch it.
Config
| Field | Default | What it does |
|---|
providerName | claude-code-wrapper | Name registered on ctx.subagents. Distinct from the built-in claude-code so both can coexist. |
executablePath | (unset → SDK default) | Path to your CLI binary. Fill in where your CLI lives; the plugin spawns it at runtime. |
env | {} | Environment entries passed to the child process, layered over DSH's scrubbed parent environment. |
permissionMode | dontAsk | dontAsk / acceptEdits / auto / plan / bypassPermissions. |
disposeGraceMs | 3000 | Grace period in ms for process-tree termination. |
VS Code extension correspondence
This provider's config aligns with the official Claude Code VS Code extension's launch-contract settings:
| This plugin | VS Code setting | Notes |
|---|
executablePath | claudeCode.claudeProcessWrapper | Executable path used to launch the Claude process. |
env | claudeCode.environmentVariables | Child environment overlay (we use a map, VS Code uses an array). |
permissionMode | claudeCode.initialPermissionMode | Session permission mode. |
(permissionMode: bypassPermissions) | claudeCode.allowDangerouslySkipPermissions | Derived from permissionMode, not a separate field. |
The built-in provider already covers env and permissionMode. This fork adds the only missing piece: executablePath ↔ claudeProcessWrapper.
Quick start (3 steps)
Step 1 — Install the bundle
# Local directory:
dsh plugin --profile web add /path/to/dsh-subagent-claude-code-wrapper
# npm:
dsh plugin --profile web add @yaways/dsh-subagent-claude-code-wrapper
# GitHub:
dsh plugin --profile web add github:yaways/dsh-subagent-claude-code-wrapper
Verify with dsh --profile web --dump-default-config — look for id: subagent-claude-code-wrapper.
Step 2 — Point it at your CLI
Edit ~/.dsh/profiles/web/cordis.patch.yml and set executablePath to your CLI's actual path:
- id: subagent-claude-code-wrapper
config:
executablePath: /opt/your-tools/bin/your-claude-cli
Your CLI can be named anything and live anywhere — /usr/local/bin/claude, /home/me/bin/my-claude, or a wrapper script. As long as it speaks the Claude Code CLI protocol, it works. The plugin doesn't care what it's called, only where it is.
If the path differs per machine, use an environment variable so the config stays the same:
- id: subagent-claude-code-wrapper
config:
executablePath: !!js process.env.DSH_CLAUDE_CODE_EXECUTABLE
Then export DSH_CLAUDE_CODE_EXECUTABLE=/your/path/your-cli in your shell.
Verify with dsh --profile web --dump-config — the provider row should show your path.
Step 3 — Enable the delegation tool in a preset
Why this step is needed — see How it works below. Short version: DSH separates registering a provider (Host plane, Step 1) from giving an agent the delegation tool that uses it (agent plane, this step). The built-in claude-code provider requires the same step — this is not specific to this fork.
DSH ships tool-subagent-claude-code in every preset with disabled: true. The preset's own comment says:
Install the matching Bundle, then copy this preset and remove disabled from the matching tool row. Host availability alone grants no tool.
To enable it for your wrapper provider:
3a. Copy the shipped standard preset into user space with a new id (same-id copies are shadowed by the shipped original — DSH resolves preset duplicates first-root-wins).
Option 1: use the DSH Web GUI (recommended)
Open the DSH Web GUI settings, find the "Agent presets" section, select standard, click "Duplicate", and name the copy claude-code-wrapper. Under the hood this copies the entire standard preset directory (including agent.cordis.yml and preset.yml) to ~/.dsh/.agent-presets/claude-code-wrapper/ — no manual path-finding needed.
After duplicating, the copy lands at ~/.dsh/.agent-presets/claude-code-wrapper/agent.cordis.yml. Edit that file directly in step 3b.
Option 2: copy manually from the command line
If you're not using the Web GUI, or don't see the "Agent presets" entry, a manual cp works the same way. The shipped preset's location depends on how you installed dsh:
mkdir -p ~/.dsh/.agent-presets/claude-code-wrapper
# From a source checkout:
cp <dsh-checkout>/apps/cli/config/agent-presets/standard/agent.cordis.yml \
~/.dsh/.agent-presets/claude-code-wrapper/agent.cordis.yml
# From an npm global install (dsh's package name is @deepseek-ai/dsh):
cp "$(npm root -g)/@deepseek-ai/dsh/config/agent-presets/standard/agent.cordis.yml" \
~/.dsh/.agent-presets/claude-code-wrapper/agent.cordis.yml
# From an npx run — find it in the npx cache:
cp "$(find ~/.npm/_npx -path '*/@deepseek-ai/dsh/config/agent-presets/standard/agent.cordis.yml' 2>/dev/null | head -1)" \
~/.dsh/.agent-presets/claude-code-wrapper/agent.cordis.yml
3b. Edit the copy at ~/.dsh/.agent-presets/claude-code-wrapper/agent.cordis.yml. Find the tool-subagent-claude-code row and change two things:
- id: tool-subagent-claude-code
name: '@deepseek-ai/dsh-tool-subagent'
disabled: true # ← remove this line
config:
provider: claude-code-wrapper # ← was: claude-code
toolName: subagent_claude_code
backgroundMode: one-shot
maxDepth: provider-managed
3b-2. In the same directory, create (or edit) preset.yml to set the display name and description shown in the UI. A command-line cp won't have it; a Web GUI copy will (still showing "Standard mode") — change it to your own:
# ~/.dsh/.agent-presets/claude-code-wrapper/preset.yml
name: Claude Code Wrapper
description: Standard mode, but subagent delegation uses the claude-code-wrapper provider.
Without this file, the UI display name falls back to the directory name claude-code-wrapper.
3c. Switch the default preset to your copy.
⚠️ Note: DSH stores the default preset in ~/.dsh/settings.yaml (what the Web GUI's "Set as default" writes), and it takes priority over the profile's cordis.patch.yml. So setting agent-presets.default in cordis.patch.yml has no effect — you must change settings.
Option 1: use the DSH Web GUI
In "Agent presets", find your duplicated claude-code-wrapper and click "Set as default".
Option 2: command line
Edit ~/.dsh/settings.yaml and change agent-presets.default to claude-code-wrapper:
agent-presets:
default: claude-code-wrapper
3d. Restart dsh (settings changes need a restart to take effect). New sessions will automatically use the claude-code-wrapper preset and expose the subagent_claude_code delegation tool, backed by your wrapper provider.
If it doesn't take effect after restart, open "Agent presets" in the Web GUI and check whether claude-code-wrapper is selected as default — the settings value may have been overridden by a manual selection in the UI.
How it works
Two planes, two steps
DSH splits a subagent provider's lifecycle across two composition planes:
| Plane | What happens here | How it's configured |
|---|
| Host plane | Provider registers on ctx.subagents | Bundle cordis.patch.yml (Step 1) + profile cordis.patch.yml for config (Step 2) |
| Agent plane | An agent gets the subagent_claude_code delegation tool that calls the provider | Preset agent.cordis.yml (Step 3) |
A bundle's cordis.patch.yml can only inject Host-plane rows. The delegation tool lives in the preset's delegation group (an isolated agent-plane composition mounted per-session). The two data flows don't cross — this is why even DSH's own built-in claude-code provider ships with disabled: true and tells users to copy the preset.
What this fork changes
Three surgical edits over DSH's built-in dsh-subagent-claude-code source:
| File | Change |
|---|
src/index.ts | Config interface + schema add executablePath: z.string().min(1) (schemastery fields are optional unless .required()); DEFAULT_PROVIDER_NAME → 'claude-code-wrapper' (collision-safe); spec construction passes executablePath through. |
src/run.ts | ClaudeCodeRunSpec adds readonly executablePath?: string; claudeQueryOptions passes it as pathToClaudeCodeExecutable to the Agent SDK Options. |
src/index.ts | PACKAGE_NAME / error prefixes updated to the fork's package name. |
Everything else — unattended callbacks, diagnostics, process-tree disposal, permission handling — is unchanged from upstream.
Why an independent plugin (not a source patch)
| Source patch on a local branch | This independent plugin |
|---|
| DSH update impact | rebase + rebuild every time | zero — package lives outside the checkout |
| Maintenance surface | 3 lines of source, replayed on conflict | 3 lines of source, frozen in this repo |
| Shareable | manual patch file | dsh plugin add @yaways/... |
The executablePath value lives in ~/.dsh (your profile), not in source — change the binary or the path without touching the plugin.
About the build (regular users can skip)
lib/ (compiled output) is committed directly to the git repo — so whether you install from npm or GitHub, lib/ is there, no build, no extra steps.
Why commit build output to git? Because pnpm 11 has a security policy for git-hosted packages: any git-hosted package with a prepare/postinstall script is blocked behind an allowBuilds allowlist, and that allowlist key includes the full commit hash, which changes every push — impossible to pre-configure. Committing lib/ removes the need for a prepare script, sidestepping the gate entirely. lib/ is only 208K.
Only contributors who edit source need to build manually:
pnpm install --config.auto-install-peers=false # skips @deepseek-ai/* peers (provided by the host)
pnpm run build # tsc -b tsconfig.json → lib/*.js
git add lib/ && git commit # commit lib/ alongside source changes
tsc runs with type-checking off (noCheck: true) — the source is a verified copy of upstream, types are guaranteed there, and the build only transpiles, so it doesn't need @deepseek-ai/* type definitions to compile. If you have a DSH checkout nearby, tsconfig.json already references it for project types (../deepseek-harness/...); adjust the relative paths if your layout differs.
Or use link: install for live edits without rebuilding + committing each time.
Update impact
| Update source | What's affected |
|---|
| Your CLI binary updates | Nothing — executablePath points at a path (typically a symlink); the binary upgrades in place. |
| DSH updates | The plugin package (src/, lib/) is outside the checkout — untouched. Your executablePath config is in ~/.dsh — untouched. The only maintenance surface is Step 3's preset copy: if DSH changes the standard preset significantly, diff and merge new rows into your claude-code-wrapper copy. The only load-bearing line is tool-subagent-claude-code. |
Upstream executablePath accepted | If DSH adds executablePath to the built-in provider, delete this plugin, remove the Step 3 preset, and set executablePath on the built-in subagent-claude-code row — the field name matches, so your config carries over with zero migration. |
Upstream proposal
A feature request to add executablePath to the built-in dsh-subagent-claude-code is posted to DSH GitHub Discussions. This plugin is the "use it now" bridge until (or unless) that lands.
License
MIT
