Skip to main content

deepseek-harness-studio/packages/subagent/subagent-claude-code

403Stars43Forks2Issues2Watchers

Allow DSH to launch the official Claude Code sub-agent in a one-time, unattended manner within a delegation session: submit a plain text task via `dsh-subagent` to the Claude Agent SDK for execution and return the final answer based on strict success criteria.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the fufankeji/deepseek-harness-studio monorepo — stars and activity count the whole repository.

Language
TypeScript
License
MIT
Branch
main
ai-agentdeepseekdeepseek-harnessdeepseek-harness-studiodesktop-appdeveloper-toolsdshdsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add github:fufankeji/deepseek-harness-studio#path:packages/subagent/subagent-claude-code

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin fufankeji/deepseek-harness-studio/packages/subagent/subagent-claude-code for me: review the repository at https://github.com/fufankeji/deepseek-harness-studio first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Sentence Positioning

subagent-claude-code enables DSH sessions to temporarily spawn an independent Claude Code subprocess for pure text tasks when needed: each time it starts a fresh CLI, requires no human key press approval, and passes the final answer or failure diagnosis upstream; it doesn't rewrite your Claude account or settings, just connects the official SDK to DSH's subagent service.

Core Capabilities

  • Spawns the official Claude Agent SDK's real CLI subprocess in the委托 Session's working directory, with the process managed by dsh-subprocess's process tree (src/run.ts:362-368 / src/process.ts:46-94)
  • One-shot text task: accepts only non-empty plain text blocks; only compliant results (subtype: "success" and non-error and non-blank) are considered successful; any deviations are mapped to fixed failure classifications (src/run.ts:182-224, 234-260)
  • No popups or user interaction: disables AskUserQuestion, rejects all permission requests, rejects all MCP elicitation, cancels blocking conversations (src/run.ts:323-360)
  • Failures include diagnostics: composes a failure summary of up to 4096 bytes from lifecycle stages (query-start / query-run / process / teardown), SDK error classification, subprocess exit code/signal, written to SubagentResult.diagnostic (README.md:19 / src/run.ts:82-97)
  • Runs only once: does not hold session state, does not resume, does not persist; each time is a new SDK query + new CLI process + one-shot product session (README.md:141 / README.md:115-117)
  • Install/uninstall via Profile Bundle: upon installation, a dormant provider is added to the host; upon uninstall, it withdraws along with its private runtime on next startup (README.md:44 / cordis.patch.yml:1-6)

Technical Implementation

  • Language: TypeScript (ESM, published artifacts lib/index.js and lib/types/*.d.ts, see package.json:13-27).
  • Key Dependencies: @anthropic-ai/[email protected] (official SDK, includes eight platform subpackages with Claude Code 2.1.220), @deepseek-ai/dsh-subagent (shared task seam and result settlement), @deepseek-ai/dsh-subprocess (responsible for real CLI process tree hosting), @deepseek-ai/dsh-timeout (MAX_TIMER_DELAY_MS upper limit validation) (package.json:40-54 / src/run.ts:9-37 / src/process.ts:9-18).
  • Architecture Pattern: Function plugin + Profile Bundle——src/index.ts named exports name/inject/Config/apply; apply(ctx, config) registers a ClaudeCodeProvider to ctx.subagents, injected by cordis.patch.yml on top of dsh-base. At runtime, via SDK's spawnClaudeCodeProcess custom hook, the process generation path is handed over to the shared handle held by dsh-subprocess, then ManagedClaudeCodeProcess feeds the event stream back to the SDK protocol layer (src/index.ts:30-32, 129-151 / cordis.patch.yml:1-6 / src/run.ts:362-368 / src/process.ts:67-159).
  • Entry Files: src/index.ts (Cordis registration entry), src/run.ts (one-shot task lifecycle and SDK options), src/process.ts (SDK to subprocess handle projection).

Use Cases

Delegating an independent task where "I don't want to do it myself, just let Claude handle it" to a sub Agent; common practice is to let the model in DSH's main conversation trigger subagent_claude_code from its tool whitelist when needed, such as generating long documents in one go, batch modifying files, or having Claude pull a current state summary back to the main conversation. This package is unsuitable for scenarios requiring continuous dialogue, needing to see intermediate steps, or requiring Claude tools to pop up interactive confirmations all the way—these needs inherently conflict with the "one-shot, no human, final answer only" positioning.

Prerequisites & Compatibility

DependencyMin VersionDescription
DSH (launcher)0.1.0-rc.8This package and other packages in the same repository share the same version (package.json:4), injected as a Profile Bundle on top of dsh-base (cordis.patch.yml:1-6).
Node.js^22.19.0 || >=24.0.0Repository root engines.node constraint; subagent-claude-code itself does not declare an independent range (repository root package.json:8-10).
PlatformCross-platform (macOS / Windows / Linux)The actual executable CLI comes from @anthropic-ai/claude-agent-sdk's eight platform subpackages, self-contained per system/CPU/Linux libc; omitting optional dependencies, unsupported systems, or missing payload files will allow provider registration to succeed but the first delegation will fail at the SDK startup boundary (README.md:101, 103).
Claude Code CLI2.1.220 (bundled with SDK)Locked by SDK 0.3.220, does not depend on host claude; this package also doesn't check PATH, doesn't do platform selection, and doesn't fall back to host binary (README.md:42, 103).
Native Modulesclaude / claude.exe (from @anthropic-ai/claude-agent-sdk)Carried by SDK platform packages after installation; DSH side doesn't introduce new native modules (README.md:101).
disposeGraceMs Upper Limit≤ MAX_TIMER_DELAY_MS (2,147,483,647)Validated at apply() startup; must be a positive finite value not exceeding the repository's dsh-timeout shared upper limit (src/index.ts:136-145 / packages/util/timeout/src/index.ts:25).

Installation

dsh plugin --profile web add github:fufankeji/deepseek-harness-studio/packages/subagent/subagent-claude-code

Configuration Options

ConfigTypeDescriptionDefault
providerNamestring (non-empty)Registration name on ctx.subagents, also referenced by dsh-tool-subagent tool行的 provider field; when multiple instances are attached under the same Profile, they must be mutually unique (src/index.ts:58 / README.md:29).claude-code
envobject (Record<string, string>)Explicitly passed through to Claude Code subprocess environment variables, layered on top of the subset of parent environment after credentials have been cleared by the sharing mechanism; to have the subprocess receive ANTHROPIC_API_KEY, it must be explicitly declared here (src/index.ts:60 / src/run.ts:321 / README.md:42).{}
permissionModeenum: dontAsk / acceptEdits / auto / plan / bypassPermissionsNon-interactive permission strategy for this provider instance's subprocess; selecting plan also puts ExitPlanMode into disallowedTools, forcing the model to treat the plan as the final answer (src/run.ts:43-55, 323-342 / README.md:34-40).dontAsk
disposeGraceMsnumber (ms, positive finite)Wait duration between termination tiers for the shared process tree owner; after which it waits for the entire process tree to exit before cleanup is complete (src/index.ts:62, 136-145 / src/process.ts:46-61).3000

FAQ

Q: What's the difference from the previous Claude toolchain? Is this an easier integration?

A: It's different. This package serves as a "subagent provider" role for dsh, handling one-shot requests from dsh-tool-subagent; each time it starts a fresh Claude Code process and exits when done; it doesn't pick models for Claude, doesn't persist sessions, and doesn't replicate Claude settings. The default deepseek entry in dsh-base is the main conversation model, which is completely independent from this provider at the process level (README.md:42, 115-117).

Q: Is env only for ANTHROPIC_API_KEY? How to pass other variables?

A: Not limited to keys only, but please put keys here; any environment variables in the parent process that are judged to be credential-shaped will be stripped by dsh-subprocess before passing to the subprocess. Non-credential variables like PATH, HOME, ANTHROPIC_BASE_URL are naturally inherited, and can also be explicitly overridden in env. DSH side doesn't create accounts, doesn't log into Claude, and doesn't modify settings files; login state and valid keys must be ensured to exist by Claude's side itself (README.md:42 / src/run.ts:321 / src/process.ts:30-38).

Q: After installation, how does the model know about the subagent_claude_code tool?

A: It doesn't—it depends on your Agent Preset. The full Preset has the corresponding tool line set to disabled: true by default; you need to first copy the Preset then remove this field; when starting a new Session based on the copy, the model will see that static tool name. Each dsh-tool-subagent line needs an independent toolName exposed to the model, so when multiple providers are attached under the same Profile, each tool must have a different name (README.md:52).

Q: How do Claude settings files work in the subprocess?

A: It uses the relative path of native Claude settings; this package neither specifies settingSources nor copies/filters those files. So in the parent session's working directory, it looks for configurations and login states following Claude's own user / project / local three-layer approach. This means you can place a .claude/settings.json in your project to affect this provider, and uninstalling this package won't touch these files (README.md:17 / README.md:144).

Q: How to tell from failures whether it's an SDK error or the subprocess didn't start?

A: Look at the stage segment in SubagentResult.diagnostic: query-start is mostly SDK/platform package not found, query-run is an error during execution (e.g., SDK's four error sub-types are explicitly preserved as original names), process is CLI ran but didn't produce correct results, teardown is subprocess exit failure during cleanup. Co-occurring exit code / signal lines are the actual process-level exit reasons. Original product layer or Host errors are always in the Error's cause chain and don't directly enter this diagnostic (README.md:19 / src/run.ts:82-97, 540-568).

Q: Can one tool instance support both foreground and background execution?

A: Yes, but needs two tool lines. When dsh-tool-subagent's backgroundMode is set to one-shot, omitting run_in_background or passing false runs in foreground (synchronous blocking); passing true immediately returns a Job id owned by the parent Agent, which can be used with dsh-tool-jobs' job_output / job_kill to pull results later.前提是你的 Profile 已经装好本地作业服务(@deepseek-ai/dsh-jobs-local / dsh-tool-jobs)(README.md:52).

Learning Curve

Advanced — requires first understanding DSH's Profile Bundle model, cordis patch injection order, the seam between dsh-tool-subagent and jobs, and being able to configure Claude's settings and keys yourself to make the subprocess run; if you expect "plug in and it just works," the entire chain may feel too lengthy.

Known Issues & Limitations

  • Each run creates a new SDK query and new CLI process: no support for resume, pooling, progress streaming, or product session persistence (README.md:141)
  • Instance selection is static: Profile lines have fixed provider name and tool binding; the model cannot choose a provider at call time; each exposed tool must have a unique toolName (README.md:142)
  • Host Claude settings are always authoritative: this package doesn't provide a "filtered or isolated from host environment" production mode; project and user layer settings can modify models and tools (README.md:143)
  • Authentication and account state are managed by Claude's native side: this package doesn't create accounts, doesn't log in, doesn't modify settings; configuration or authentication failures are reported with lifecycle stage + unknown fallback (README.md:144)
  • SDK platform payload must exist at delegation time: skipped optional dependencies, unsupported platforms, or missing/corrupted platform payloads will cause first query failure; there is no "host CLI fallback" path (README.md:145)
  • No human interaction channel exists: AskUserQuestion is disabled, permission prompts are rejected, MCP elicitation is rejected, undeclared conversations fail quickly without hanging (README.md:146 / src/run.ts:323-360)
  • Assistant payload only contains final text: reasoning/intermediate messages/tool calls/usage/process stderr/workspace diffs all stay on Claude's side; when failures occur, an independent safety diagnostic is carried as needed (README.md:147)
  • Optional sharing capabilities not supported: shared subagent service rejects this provider's output schema, sub-roles, tool filtering, and harness depth enforcement (README.md:148)
  • No time-based triggering for timeouts or side-effect rollback: caller must actively abort to stop; any state the subprocess has written/modified/called to external interfaces before stopping won't be automatically restored (README.md:149)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/fufankeji/deepseek-harness-studio/packages/subagent/subagent-claude-code)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory