@deepseek-ai/dsh-subagent-claude-code 0.1.1-rc.2 → 0.1.2-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.i18n.yaml CHANGED
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
3
  # after editing either side, bring the other along and re-record with:
4
4
  # pnpm run verify-translation-pairing --write packages/subagent/subagent-claude-code/README.md
5
- README.md: 0260d9c82dee82541e5b60ff7fe2c323cf9b7331
6
- README.zh.md: 484241f1ca23f2b8ee843b6f412d0f779832d400
5
+ README.md: 9fcce15b45a77a7a3b7dd4e6299609f8ef5ee484
6
+ README.zh.md: 5066c2553f7bd7f71fd87c7ee5acb800b7398b59
package/README.md CHANGED
@@ -1,47 +1,35 @@
1
+ ---
2
+ description: "The one-shot Claude Code subagent provider for users and maintainers choosing a product backend, installing a Profile bundle, or configuring an unattended Claude Code delegation."
3
+ kind: "package-bundle"
4
+ ---
5
+
1
6
  # @deepseek-ai/dsh-subagent-claude-code
2
7
 
3
8
  English | [中文](README.zh.md)
4
9
 
5
- This package registers a Profile-named Claude Code subagent provider whose default name is `claude-code`. Each accepted run invokes the official Claude Agent SDK in the delegating Session's workspace, lets the pinned SDK select its installed platform CLI, submits one self-contained text task, and returns either the strict final answer or a separate safe failure diagnostic through the shared [`dsh-subagent`](../subagent/README.md) result contract.
6
-
7
- ## Start and ownership
10
+ ## Summary
8
11
 
9
- `start(request)` accepts only a non-empty sequence of text blocks and derives the child cwd from the parent Session. It creates one private `AbortController`, calls the official SDK `query()`, and publishes the run only after the SDK's `spawnClaudeCodeProcess` hook has supplied a live CLI handle owned by [`dsh-subprocess`](../../subprocess/subprocess/README.md). A failure or cancellation before publication closes the query, terminates any acquired process tree, waits for it to exit, and rejects `start()`.
12
+ `dsh-subagent-claude-code` registers a Profile-named Claude Code subagent provider (default `claude-code`) that runs a real Claude Code CLI child in the delegating session's workspace through the official Agent SDK. Each accepted run submits one self-contained text task and returns the strict final answer — or a separate safe failure diagnostic — through the shared subagent result contract. The provider ships as an optional Profile Bundle: installing it brings the pinned Agent SDK and one compatible platform CLI payload, while the registered provider stays dormant until a bound tool calls it. Native Claude settings and authentication remain authoritative, and the Profile-selected `permissionMode` decides how the unattended query handles permission checks. Choose it when the child should be a genuine Claude Code product session, fully isolated from the parent harness.
10
13
 
11
- The SDK receives the exact concatenated text task. The provider iterates the complete SDK message stream and accepts only a `result` message with `subtype: "success"`, `is_error: false`, and a nonblank `result`, followed by normal iterator completion. Every failure still maps to `error`: the four error subtypes in Agent SDK 0.3.220 retain their exact category, an error-marked or blank success becomes `invalid-success`, a missing result becomes `missing-result`, an unclassified query failure becomes `unknown`, and an early CLI exit becomes `process-exit`. The diagnostic also names the current `query-start`, `query-run`, `process`, or `teardown` stage and independently includes an observed exit code and signal. The provider produces neither `max-tokens` nor `refusal`.
14
+ ## Table of Contents
12
15
 
13
- Local cancellation wins the result race and maps to `aborted` without a failure diagnostic. `dispose()` is idempotent: it aborts the run, asks the SDK query to close, invokes the shared process-tree termination escalation, and waits for whole-tree exit. SDK graceful close expresses protocol intent; the subprocess handle remains the authority for process quiescence. Startup and teardown rejections expose the same fixed safe stage and process facts through their Error message, while the original product or Host error remains on the internal cause chain and in the Provider's Host log. Result failure and independent teardown failure remain separate.
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
14
22
 
15
- ## Native settings and interaction
23
+ -----
16
24
 
17
- The provider deliberately omits the SDK `settingSources` option. The official SDK therefore reads the host's normal user, project, and local Claude settings relative to the parent Session cwd, including native account state and product configuration. The provider neither copies nor filters those files and does not create or modify login state. The Profile-selected `permissionMode` is the one query-level override: Claude Code still owns its settings and sandbox, while the selected native mode decides how this unattended query handles permission checks.
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
18
27
 
19
- Each query sets `persistSession: false` and disables `AskUserQuestion`. Except in bypass mode, `canUseTool` immediately denies requests that still require human approval. Plan mode also places `ExitPlanMode` in the SDK's `disallowedTools`, so native settings cannot pre-approve a transition back to execution and the model must return the completed plan as its final answer. MCP elicitation is declined, the known refusal fallback dialog is cancelled, and undeclared dialog kinds use the SDK's no-dialog failure behavior. These decisions never wait for a user interface. When both facts contribute to a failed run, `SubagentResult.diagnostic` contains the structured failure line first and the latest safe permission decision second; the shared result boundary limits the complete text to 4096 UTF-8 bytes. Successful and locally cancelled runs expose neither captured fact.
28
+ Mount this provider when a delegation should run as a real Claude Code session in the parent's workspace. The common path is explicit: install the Bundle into a Profile, optionally configure the provider row, and expose it to the model through a delegation tool row.
20
29
 
21
- ## Capabilities and context
30
+ ### Installing the Bundle
22
31
 
23
- The provider advertises no optional start-time capabilities and reports `inheritsParentContext: false`. Claude Code receives the standalone text task and the parent Session cwd, but not the parent conversation, persona, tool filter, depth policy, or structured-output contract. Every run has an independent SDK query, cancellation controller, CLI process, and non-persisted product session.
24
-
25
- ## Configuration
26
-
27
- | Key | Default | Meaning |
28
- |---|---|---|
29
- | `providerName` | `claude-code` | Non-empty registry name on `ctx.subagents`; each mounted instance needs a unique value. |
30
- | `env` | `{}` | Explicit SDK/CLI environment layered over the shared credential-scrubbed parent environment. |
31
- | `permissionMode` | `dontAsk` | Native non-interactive permission policy fixed for every run from this Provider instance. |
32
- | `disposeGraceMs` | `3000` | Positive finite grace in milliseconds, no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), between the shared process-tree owner's termination tiers; disposal then waits for whole-tree exit. |
33
-
34
- | `permissionMode` value | Native behavior |
35
- |---|---|
36
- | `dontAsk` | Deny operations that are not already authorized instead of prompting. |
37
- | `acceptEdits` | Accept file edits; any remaining permission prompt is denied by the unattended callback. |
38
- | `auto` | Let Claude Code's native classifier allow or deny permission requests. |
39
- | `plan` | Run in native planning mode, deny execution approval, and return the completed plan as the final answer. |
40
- | `bypassPermissions` | Explicitly set the SDK's dangerous confirmation and bypass permission checks. |
41
-
42
- Production omits `pathToClaudeCodeExecutable`, so Agent SDK 0.3.220 selects the matching native `claude` or `claude.exe` from its own platform package and passes that absolute command through the custom-spawn hook to `dsh-subprocess`. The provider does not inspect `PATH`, implement platform selection, or fall back to a host `claude`. Native settings and authentication remain authoritative, while `permissionMode` is the only query-level policy override. The plugin does not select a model, create a product home, log in, or probe an account. Credential-shaped ambient variables are removed before the explicit `env` overlay is applied, so an API key or token intended for the child must be supplied there. Non-credential endpoint variables such as `ANTHROPIC_BASE_URL`, along with ordinary ambient values such as `PATH` and `HOME`, remain inherited unless overridden; `PATH` does not choose the Claude executable.
43
-
44
- This package is an optional Profile Bundle. Install it into the target Profile, then restart that Profile; installation brings the pinned Agent SDK and one compatible platform CLI payload into that Profile, while the declared `cordis.patch.yml` layer registers only the dormant `claude-code` Host provider and starts no Claude process. Removing the package withdraws that provider and its private runtime closure on the next Profile start.
32
+ Install the package into the target Profile, then restart that Profile. The installation brings the pinned Agent SDK and one compatible platform CLI payload into the Profile; the declared patch layer registers only the dormant provider and starts no Claude process.
45
33
 
46
34
  ```sh
47
35
  dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-claude-code
@@ -49,70 +37,110 @@ dsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-claude-code
49
37
  dsh --profile <name>
50
38
  ```
51
39
 
52
- Installation controls Host availability, not model permission. The Bundle supplies the dormant default `claude-code` row; the Profile may replace that row's complete config or mount additional rows with distinct `providerName`, `permissionMode`, and `env` values. Loading an instance starts no Claude process until a bound tool calls it. Each `dsh-tool-subagent` row names one provider and needs its own `toolName`, so the model sees static tools rather than a dynamic provider selector. Full Agent Presets carry a matching default product tool row with `disabled: true`; copy a preset and remove that field to expose `subagent_claude_code` only to agents composed from the copy. Its `one-shot` policy keeps omitted or `false` `run_in_background` calls in the foreground, while explicit `true` returns a parent-owned Job id for `job_output` or `job_kill`. The base host and full presets already provide the generic Job registry and controls.
40
+ Removing the package withdraws the provider and its private runtime closure on the next Profile start. Installation controls Host availability, not model permission: the model can only reach the provider through a delegation tool row you compose.
53
41
 
54
- The standalone composition below shows the complete explicit capability. A Profile based on `@deepseek-ai/dsh-base` keeps its existing Job rows, adds the product provider and tool rows, and does not mount duplicate Job services.
42
+ ### Configuration
55
43
 
56
- ```yaml
57
- - id: subagent-claude-safe
58
- name: '@deepseek-ai/dsh-subagent-claude-code'
59
- config:
60
- providerName: claude-safe
61
- permissionMode: dontAsk
62
- env:
63
- ANTHROPIC_API_KEY: !!js process.env.ANTHROPIC_API_KEY
44
+ | Field | Default | Meaning |
45
+ |---|---|---|
46
+ | `providerName` | `claude-code` | Non-empty registry name on `ctx.subagents`; each mounted instance needs a unique value |
47
+ | `model` | native Claude settings | Optional non-empty model name fixed for every run from this provider instance; omission sends no SDK override |
48
+ | `env` | `{}` | Explicit SDK/CLI environment layered over the credential-scrubbed parent environment |
49
+ | `permissionMode` | `dontAsk` | Native non-interactive permission policy fixed for every run from this provider instance |
50
+ | `disposeGraceMs` | `3000` | Grace between the shared process-tree owner's termination tiers |
64
51
 
65
- - id: subagent-claude-bypass
66
- name: '@deepseek-ai/dsh-subagent-claude-code'
67
- config:
68
- providerName: claude-bypass
69
- permissionMode: bypassPermissions
70
- env:
71
- ANTHROPIC_API_KEY: !!js process.env.ANTHROPIC_API_KEY
72
- ```
52
+ | `permissionMode` value | Native behavior |
53
+ |---|---|
54
+ | `dontAsk` | Deny operations that are not already authorized instead of prompting |
55
+ | `acceptEdits` | Accept file edits; any remaining permission prompt is denied by the unattended callback |
56
+ | `auto` | Let Claude Code's native classifier allow or deny permission requests |
57
+ | `plan` | Run in native planning mode, deny execution approval, and return the completed plan as the final answer |
58
+ | `bypassPermissions` | Explicitly set the SDK's dangerous confirmation and bypass permission checks |
59
+
60
+ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-subagent-claude-code) is the exhaustive source for every accepted field and its JSDoc. A configured `model` passes unchanged to every query from that provider instance; omission leaves native model selection in force. Credential-shaped ambient variables are removed before the explicit `env` overlay, so an API key intended for the child must be supplied there. The provider omits the SDK `settingSources` option, so Claude Code reads the host's normal user, project, and local settings relative to the parent Session cwd. It does not copy or filter those files, create or modify login state, inspect `PATH`, or fall back to a host `claude` executable.
61
+
62
+ ### Exposing the tool
63
+
64
+ Each delegation tool row names one provider and needs its own `toolName`, so the model sees static tools rather than a dynamic provider selector. Full Agent Presets carry a matching default tool row with `disabled: true`; copy a preset and remove that field to expose `subagent_claude_code` only to agents composed from the copy.
73
65
 
74
66
  ```yaml
75
67
  - id: jobs
76
68
  name: '@deepseek-ai/dsh-jobs-local'
77
-
78
69
  - id: tool-jobs
79
70
  name: '@deepseek-ai/dsh-tool-jobs'
80
-
81
- - id: tool-subagent-claude-safe
82
- name: '@deepseek-ai/dsh-tool-subagent'
83
- disabled: true
84
- config:
85
- provider: claude-safe
86
- toolName: subagent_claude_safe
87
- backgroundMode: one-shot
88
- maxDepth: provider-managed
89
-
90
- - id: tool-subagent-claude-bypass
71
+ - id: tool-subagent-claude
91
72
  name: '@deepseek-ai/dsh-tool-subagent'
92
73
  config:
93
- provider: claude-bypass
94
- toolName: subagent_claude_bypass
74
+ provider: claude-code
75
+ toolName: subagent_claude_code
95
76
  backgroundMode: one-shot
96
77
  maxDepth: provider-managed
97
78
  ```
98
79
 
99
- ## Product compatibility and evidence
80
+ The `one-shot` policy keeps omitted or `false` `run_in_background` calls in the foreground, while explicit `true` returns a parent-owned Job id for `job_output` or `job_kill`; the base host and full presets already provide the generic Job registry and controls.
81
+
82
+ ### What you get
83
+
84
+ A foreground call gives the model the strict final Claude Code answer, or an error with the stop reason and optional safe diagnostic for a failed run. A background call first returns a Job id; the generic job controls later deliver a completion notice and expose the same final answer or failed status through `job_output`. Claude Code reasoning, tool activity, intermediate messages, stderr, and workspace diffs never enter the parent session.
85
+
86
+ ### Failure and recovery
87
+
88
+ An install that omits optional dependencies, uses an unsupported platform, or loses the selected payload leaves the provider dormant and fails the first delegation at the SDK startup boundary with a safe `query-start` / `unknown` failure fact; there is no host-CLI fallback. The original product error stays on the internal cause chain and in the provider's Host log. A cancelled run settles as `aborted`.
89
+
90
+ -----
91
+
92
+ <a id="understand-the-implementation"></a>
93
+ ## Understand the implementation
94
+
95
+ <details>
96
+ <summary>Implementation internals — click to expand</summary>
97
+
98
+ This section explains how the provider drives a real Claude Code CLI and where the observable behavior comes from; the full contract lives in [Use this package](#use-this-package).
99
+
100
+ ### Design concept
101
+
102
+ - **One fresh query per run.** Every run has an independent SDK query, cancellation controller, CLI process, and non-persisted product session; there is no continuation, resume, or pooling.
103
+ - **Native settings are authoritative.** The provider deliberately omits the SDK `settingSources` option, so Claude Code reads the host's normal user, project, and local settings; an optional `model` and the required `permissionMode` are the only query-level overrides.
104
+ - **Unattended by design.** `AskUserQuestion` is disabled and permission prompts are denied except in bypass mode, so the query never waits for a user interface.
105
+
106
+ ### Source map
107
+
108
+ | File | Role |
109
+ |---|---|
110
+ | [`src/index.ts`](src/index.ts) | Plugin entry: config schema, provider registration |
111
+ | [`src/run.ts`](src/run.ts) | The SDK query lifecycle, result acceptance, and permission handling |
112
+ | [`src/process.ts`](src/process.ts) | Process-tree termination escalation on disposal |
113
+ | [`cordis.patch.yml`](cordis.patch.yml) | The Profile patch layer that registers the dormant provider |
114
+
115
+ ### Run flow
116
+
117
+ A start accepts only a non-empty sequence of text blocks and derives the child cwd from the parent session. It creates a private `AbortController`, calls the official SDK `query()` with the exact concatenated task, and publishes the run only after the SDK's custom-spawn hook has supplied a live CLI handle owned by the subprocess seam. The provider iterates the complete message stream and accepts only a `result` message with `subtype: "success"`, `is_error: false`, and a nonblank `result`, followed by normal iterator completion. Every other outcome maps to a fixed-category `error` diagnostic naming the lifecycle stage and observed process outcome — the category set lives in [`src/run.ts`](src/run.ts). Local cancellation wins the result race and maps to `aborted` without a failure diagnostic.
118
+
119
+ </details>
100
120
 
101
- The runtime dependency is pinned to `@anthropic-ai/claude-agent-sdk@0.3.220`, whose eight platform packages carry Claude Code 2.1.220. A normal install selects one payload for the current OS, CPU, and Linux libc. For the current darwin-arm64 payload, `npm pack --dry-run --json` reports 74,858,812 packed bytes and 256,908,856 unpacked bytes; other platforms may differ, and these values are disclosure rather than an installation threshold. The keyless real-product test runs the SDK-selected CLI against a loopback Messages fixture and asserts that the shared subprocess argv begins with that platform package's native executable. Loader composition proves that installing the Bundle registers only the dormant Claude Code provider and starts no product process.
121
+ -----
102
122
 
103
- Installing with optional dependencies omitted, using an unsupported platform, or losing the selected payload leaves provider registration dormant but makes the first delegation fail at the SDK startup boundary. The caller receives the safe `query-start` / `unknown` failure fact; the native payload error remains only on the internal cause chain and in the Provider's Host log. The provider neither probes a host CLI nor retries with one.
123
+ <a id="further-exploration"></a>
124
+ ## Further Exploration
104
125
 
105
- Loader composition proves that the Bundle default, two additional named Claude instances, and the existing Codex package coexist without starting either product.
126
+ Read these pages when the package-level contract is not enough. They move from this provider to the seam it plugs into and the sibling product provider.
106
127
 
107
- The project owner's identity-scoped distribution authorization covers the official SDK and the official CLI/platform payloads declared by each SDK version. [`THIRD_PARTY_NOTICES.md`](../../../THIRD_PARTY_NOTICES.md) discloses the current optional payload closure without classifying its declared terms as permissive; unrelated non-permissive runtime dependencies continue to fail the notices gate.
128
+ - [Subagent subsystem](../../../docs/subsystems/subagent.md) — the service contract, provider contract, and terminal result semantics.
129
+ - [dsh-subagent seam](../subagent/README.md) — the registry and start API this provider registers on.
130
+ - [Codex subagent provider](../subagent-codex/README.md) — the sibling product backend over the official app-server protocol.
131
+ - [Claude Code and Codex backends](../../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md) — the design record for the product providers.
132
+ - [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-subagent-claude-code) — every accepted config field and its source declaration.
108
133
 
134
+ -----
135
+
136
+ <a id="model-experience"></a>
109
137
  ## Model Experience
110
138
 
111
139
  ### Child request
112
140
 
113
141
  #### What the model sees
114
142
 
115
- The Claude Code child receives the standalone text task as one fresh SDK query. Its workspace is the parent Session cwd; its model, system instructions, tools, sandbox, and authentication come from native Claude settings, the selected Provider instance's Profile configuration fixes the query's environment and non-interactive permission mode, and the executable version comes from the Bundle's pinned SDK platform payload.
143
+ The Claude Code child receives the standalone text task as one fresh SDK query. Its workspace is the parent Session cwd; the selected Provider instance fixes the query's configured model, environment, and non-interactive permission mode, while an omitted model and every other product setting come from native Claude configuration. The executable version comes from the Bundle's pinned SDK platform payload.
116
144
 
117
145
  #### Token effect
118
146
 
@@ -126,7 +154,7 @@ Independent of the parent request cache. Reuse depends only on Claude Code's own
126
154
 
127
155
  #### What the model sees
128
156
 
129
- Through `dsh-tool-subagent`, a foreground call gives the parent the strict final Claude Code answer or an error containing the stop reason and optional safe diagnostic for a non-completed result. That diagnostic can distinguish the fixed SDK error category, lifecycle stage, and observed process outcome without copying raw product text. A background call first returns a Job id; the generic job controls later deliver a completion notice, expose the same final answer or failed status detail through `job_output`, and let `job_kill` request cancellation. Claude Code reasoning, tool activity, intermediate messages, stderr, workspace diffs, usage, product ids, tool inputs, and raw protocol payloads are not copied into the parent Session.
157
+ Through `dsh-tool-subagent`, a foreground call gives the parent the strict final Claude Code answer or an error containing the stop reason and optional safe diagnostic for a non-completed result. That diagnostic can distinguish a coarse action category, lifecycle stage, and observed process outcome without copying raw product text or version-specific subtype names. A background call first returns a Job id; the generic job controls later deliver a completion notice, expose the same final answer or failed status detail through `job_output`, and let `job_kill` request cancellation. Claude Code reasoning, tool activity, intermediate messages, stderr, workspace diffs, usage, product ids, tool inputs, and raw protocol payloads are not copied into the parent Session.
130
158
 
131
159
  #### Token effect
132
160
 
@@ -138,12 +166,30 @@ Append-only: foreground adds one result after the reusable parent prefix, while
138
166
 
139
167
  ## Known Limitations and Deferred Work
140
168
 
169
+ <a id="known-limitations-and-deferred-work"></a>
170
+
171
+
172
+ These limits define when this provider is a poor fit or needs special operational care. They are current package constraints, not a general Claude Code comparison or a task backlog.
173
+
141
174
  - **One fresh query and process per run** — there is no continuation, resume, pooling, progress stream, or product-session persistence.
142
- - **Static instance selection** — Profile rows fix provider names and tool bindings; calls cannot choose a provider dynamically, and every exposed tool needs a unique `toolName`.
143
- - **Host settings are intentionally authoritative** — project and user settings can change model, tools, and behavior; the provider does not provide a filtered or hermetic production mode.
175
+ - **Static instance selection** — Profile rows fix provider names, optional models, and tool bindings; calls cannot choose or change either a provider or model dynamically, and every exposed tool needs a unique `toolName`.
176
+ - **Host settings are intentionally authoritative** — when `model` is omitted, project and user settings choose it; native settings always retain the remaining tools and behavior, and the provider does not provide a filtered or hermetic production mode.
144
177
  - **Authentication and account state remain native** — the Bundle supplies the CLI but does not create an account, log in, or rewrite Claude settings; configuration and authentication failures surface with their lifecycle stage and the safe `unknown` fallback rather than a separate public classification.
145
178
  - **The SDK platform payload is required at delegation time** — installs that omit optional dependencies, unsupported platforms, and missing or damaged payloads fail at the first query; there is no host-CLI fallback.
146
179
  - **No human interaction path** — `AskUserQuestion` is disabled, permission prompts are denied, MCP elicitation is declined, and blocking dialogs fail closed instead of suspending.
147
- - **Assistant payload is final text only** — a failed run may additionally expose the separate safe diagnostic; reasoning, intermediate messages, tool traffic, usage, stderr, and workspace diffs remain product-local, while generic Job ids, notices, and status come from the shared job runtime.
148
- - **No optional shared capabilities** — output schemas, child personas, tool filtering, and harness depth enforcement are rejected by the shared service for this provider.
180
+ - **Assistant payload is final text only** — reasoning, intermediate messages, tool traffic, usage, stderr, and workspace diffs remain product-local.
181
+ - **No optional shared capabilities** — `agentOptions`, output schemas, child personas, tool filtering, and harness depth enforcement are rejected by the shared service for this provider.
149
182
  - **No wall-clock timeout or side-effect rollback** — the caller cancels long work, and files or external systems changed before cancellation are not restored.
183
+
184
+ <a id="dev-note"></a>
185
+ ### Dev Note
186
+
187
+ <details>
188
+ <summary>Working context for maintainers — click to expand</summary>
189
+
190
+ This Dev Note is working context for maintainers: open questions and undecided directions. It is explicitly non-authoritative — shipped behavior and limits live in the sections above and in the package code.
191
+
192
+ - **Payload size disclosure** — the current darwin-arm64 platform payload packs to about 92 MB and unpacks to about 325 MB; these are disclosure numbers, not installation thresholds.
193
+ - **Version-pinned protocol** — the runtime dependency is pinned to Agent SDK 0.3.241; upgrading pins a new SDK version and requires re-running the keyless real-product and loader-composition evidence.
194
+
195
+ </details>
package/README.zh.md CHANGED
@@ -1,47 +1,35 @@
1
+ ---
2
+ description: "面向用户与维护者的一次性 Claude Code subagent 提供方,用于选择产品后端、安装 Profile bundle 或配置无人值守的 Claude Code 委派。"
3
+ kind: "package-bundle"
4
+ ---
5
+
1
6
  # @deepseek-ai/dsh-subagent-claude-code
2
7
 
3
8
  [English](README.md) | 中文
4
9
 
5
- 本包(package)注册由 Profile 命名、默认名称为 `claude-code` 的 Claude Code subagent 提供方。每次接受运行请求后,它都会在发起委托的会话工作区中调用官方 Claude Agent SDK,让锁定版本的 SDK 选择随包安装的平台 CLI,提交一个自包含的文本任务,并通过共享的 [`dsh-subagent`](../subagent/README.zh.md) 结果约定返回严格的最终答案或独立的安全失败诊断。
6
-
7
- ## 启动与所有权
8
-
9
- `start(request)` 只接受非空的文本块序列,并根据父会话确定子级 cwd。它会创建一个私有 `AbortController`,调用官方 SDK 的 `query()`,并仅在 SDK 的 `spawnClaudeCodeProcess` 钩子已经提供由 [`dsh-subprocess`](../../subprocess/subprocess/README.zh.md) 管理的活动 CLI 句柄后发布此次运行。若在发布前发生失败或取消,它会关闭 query、终止所有已取得的进程树并等待其退出,然后拒绝 `start()` 调用。
10
-
11
- SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 消息流,而且只接受满足以下条件的 `result` 消息:其 `subtype: "success"`、`is_error: false` 且 `result` 非空白,之后迭代器还须正常结束。所有失败仍映射为 `error`:Agent SDK 0.3.220 的四种错误子类型保留准确类别;标记为错误或内容空白的成功消息成为 `invalid-success`;缺失结果成为 `missing-result`;未分类的 query 失败成为 `unknown`;CLI 提前退出成为 `process-exit`。诊断还会注明当前 `query-start`、`query-run`、`process` 或 `teardown` 阶段,并分别保留已观测到的退出码与信号。该提供方不会产生 `max-tokens` 或 `refusal`。
12
-
13
- 本地取消会在结果竞态中胜出并映射为 `aborted`,且不附带失败诊断。`dispose()`(资源释放)具有幂等性:它会中止此次运行、请求 SDK query 关闭、调用共享的进程树逐级终止机制,并等待整棵进程树退出。SDK 的优雅关闭只表达协议意图;进程是否完全停稳仍以子进程句柄为准。启动与清理拒绝会在 Error 消息中公开同样固定的安全阶段和进程事实,而原始产品或 Host 错误只保留在内部 cause 链与提供方的 Host 日志中。结果失败与独立的清理失败仍彼此分离。
14
-
15
- ## 原生设置与交互
16
-
17
- 提供方故意省略 SDK 的 `settingSources` 选项。因此,官方 SDK 会相对于父会话 cwd 读取宿主机常规的用户、项目和本地 Claude 设置,包括原生账户状态与产品配置。提供方既不复制也不过滤这些文件,也不会创建或修改登录状态。Profile 选择的 `permissionMode` 是唯一的 query 级覆盖:Claude Code 仍拥有其设置与沙箱,而所选原生模式决定这个无人值守 query 如何处理权限检查。
10
+ ## 概述
18
11
 
19
- 每次 query 都设置 `persistSession: false` 并禁用 `AskUserQuestion`。除 bypass 模式外,`canUseTool` 会立即拒绝仍需人工审批的请求。Plan 模式还会把 `ExitPlanMode` 放入 SDK 的 `disallowedTools`,因此原生 settings 无法预先放行回到执行模式的转换,模型必须把完整计划作为最终答案返回。MCP elicitation 会被拒绝,已知的拒绝回退对话会被取消,未声明的对话类型则使用 SDK 的无对话失败行为。这些决定都不会等待用户界面。当两类事实共同参与一次失败运行时,`SubagentResult.diagnostic` 会先写入结构化失败行,再写入最新的安全权限决定;共享结果边界会把完整文本限制在 4096 个 UTF-8 字节以内。成功运行与本地取消都不会公开已捕获的事实。
12
+ `dsh-subagent-claude-code` 注册由 Profile 命名、默认名称为 `claude-code` 的 Claude Code subagent 提供方,它在发起委派的会话工作区中通过官方 Agent SDK 运行真实的 Claude Code CLI 子 agent(智能体)。每次接受的运行提交一个自包含文本任务,并通过共享的 subagent 结果约定返回严格的最终答案——或独立的安全失败诊断。该提供方作为可选的 Profile Bundle 发布:安装会带入锁定的 Agent SDK 与一个兼容的平台 CLI 载荷,而注册的提供方在绑定工具调用前保持休眠。原生 Claude 设置与身份验证继续是权威来源,Profile 选择的 `permissionMode` 决定这个无人值守 query 如何处理权限检查。当子 agent 应该是与父 harness 完全隔离的真实 Claude Code 产品会话时,选择它。
20
13
 
21
- ## 能力与上下文
14
+ ## 目录
22
15
 
23
- 本提供方不声明任何可选的启动时能力,并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd,但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
16
+ - [使用本包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [进一步探索](#further-exploration)
19
+ - [模型体验](#model-experience)
20
+ - [已知限制与延期工作](#known-limitations-and-deferred-work)
21
+ - [开发备注](#dev-note)
24
22
 
25
- ## 配置
23
+ -----
26
24
 
27
- | 配置键 | 默认值 | 含义 |
28
- |---|---|---|
29
- | `providerName` | `claude-code` | `ctx.subagents` 中的非空注册名称;每个已挂载实例都需要唯一值。 |
30
- | `env` | `{}` | 显式指定的 SDK/CLI 环境,叠加在由共享机制清除凭证后的父环境之上。 |
31
- | `permissionMode` | `dontAsk` | 为该提供方实例的每次运行固定原生非交互权限策略。 |
32
- | `disposeGraceMs` | `3000` | 共享进程树责任方各终止层级之间的宽限期,单位为毫秒且须为正有限值,并不得大于仓库共享的 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.zh.md);随后资源释放会等待整棵进程树退出。 |
25
+ <a id="use-this-package"></a>
26
+ ## 使用本包
33
27
 
34
- | `permissionMode` 值 | 原生行为 |
35
- |---|---|
36
- | `dontAsk` | 不弹出提示,直接拒绝尚未获授权的操作。 |
37
- | `acceptEdits` | 接受文件编辑;其余权限提示由无人值守回调拒绝。 |
38
- | `auto` | 由 Claude Code 原生分类器允许或拒绝权限请求。 |
39
- | `plan` | 使用原生规划模式,拒绝执行审批,并把完整计划作为最终答案返回。 |
40
- | `bypassPermissions` | 显式设置 SDK 的危险确认并跳过权限检查。 |
28
+ 当委派应以父级工作区中的真实 Claude Code 会话运行时,挂载本提供方。常用路径是显式的:把 Bundle 安装进 Profile,可选地配置提供方行,并通过委派工具行把它暴露给模型。
41
29
 
42
- 生产环境会省略 `pathToClaudeCodeExecutable`,因此 Agent SDK 0.3.220 会从自己的平台包中选择匹配的原生 `claude` 或 `claude.exe`,再通过 custom-spawn 钩子把该绝对命令交给 `dsh-subprocess`。提供方不会检查 `PATH`、重复实现平台选择,也不会回退到宿主 `claude`。原生设置与身份验证继续是权威来源,而 `permissionMode` 是唯一的 query 级策略覆盖。本插件不选择模型、不创建产品主目录、不执行登录,也不探测账户。具有凭证特征的环境变量会在显式 `env` 覆盖生效前被清除,因此供子进程使用的 API 密钥或 token 必须在该配置中显式提供。除非被覆盖,`ANTHROPIC_BASE_URL` 等非凭证端点变量以及 `PATH` 和 `HOME` 等普通环境变量仍会被继承;`PATH` 不参与选择 Claude 可执行文件。
30
+ ### 安装 Bundle
43
31
 
44
- 本包是可选的 Profile Bundle。将它安装进目标 Profile 后重启该 Profile;安装会把锁定的 Agent SDK 与一个兼容的平台 CLI 载荷带入该 Profile,而包所声明的 `cordis.patch.yml` 层只注册休眠的 `claude-code` Host provider,不会启动 Claude 进程。移除该包后,下一次 Profile 启动会撤回这一 provider 及其私有运行时闭包。
32
+ 把包安装进目标 Profile,然后重启该 Profile。安装会把锁定的 Agent SDK 与一个兼容的平台 CLI 载荷带入 Profile;声明的 patch 层只注册休眠的提供方,不启动任何 Claude 进程。
45
33
 
46
34
  ```sh
47
35
  dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-claude-code
@@ -49,101 +37,159 @@ dsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-claude-code
49
37
  dsh --profile <name>
50
38
  ```
51
39
 
52
- 安装决定 Host 可用性,而不是模型权限。Bundle 会提供休眠的默认 `claude-code` 配置项;Profile 可以替换该配置项的完整 config,也可以挂载更多具有不同 `providerName`、`permissionMode` 与 `env` 的配置项。加载实例本身不会在绑定工具调用前启动 Claude 进程。每个 `dsh-tool-subagent` 配置项指定一个提供方,并需要独立的 `toolName`,因此模型看到的是静态工具,而不是动态提供方选择器。完整 Agent Preset 携带对应的默认产品工具行并设置 `disabled: true`;复制一个 preset 后删除该字段,即可只向由该副本组装的 agent 暴露 `subagent_claude_code`。其 `one-shot` 策略会让省略 `run_in_background` 或传入 `false` 的调用继续在前台等待,而显式传入 `true` 会返回由父 agent 拥有的 Job ID,供 `job_output` 或 `job_kill` 使用。base host(基础宿主)与完整 preset 已提供通用作业注册表和控制工具。
40
+ 移除包后,下一次 Profile 启动会撤回提供方及其私有运行时闭包。安装决定 Host 可用性,而不是模型权限:模型只能通过你组合的委派工具行触达提供方。
53
41
 
54
- 下列独立组装展示完整的显式能力。基于 `@deepseek-ai/dsh-base` 的 Profile 保留已有 Job 配置项,新增产品提供方与工具配置项,而且不重复挂载 Job 服务。
42
+ ### 配置
55
43
 
56
- ```yaml
57
- - id: subagent-claude-safe
58
- name: '@deepseek-ai/dsh-subagent-claude-code'
59
- config:
60
- providerName: claude-safe
61
- permissionMode: dontAsk
62
- env:
63
- ANTHROPIC_API_KEY: !!js process.env.ANTHROPIC_API_KEY
44
+ | 字段 | 默认值 | 含义 |
45
+ |---|---|---|
46
+ | `providerName` | `claude-code` | `ctx.subagents` 上的非空注册名称;每个已挂载实例都需要唯一值 |
47
+ | `model` | Claude 原生设置 | 为本提供方实例的每次运行固定的可选非空模型名称;省略时不发送 SDK 覆盖 |
48
+ | `env` | `{}` | 叠加在已清理凭据的父环境之上的显式 SDK/CLI 环境 |
49
+ | `permissionMode` | `dontAsk` | 为本提供方实例的每次运行固定的原生非交互权限策略 |
50
+ | `disposeGraceMs` | `3000` | 共享进程树责任方各终止层级之间的宽限 |
64
51
 
65
- - id: subagent-claude-bypass
66
- name: '@deepseek-ai/dsh-subagent-claude-code'
67
- config:
68
- providerName: claude-bypass
69
- permissionMode: bypassPermissions
70
- env:
71
- ANTHROPIC_API_KEY: !!js process.env.ANTHROPIC_API_KEY
72
- ```
52
+ | `permissionMode` 值 | 原生行为 |
53
+ |---|---|
54
+ | `dontAsk` | 不弹出提示,直接拒绝尚未获授权的操作 |
55
+ | `acceptEdits` | 接受文件编辑;其余权限提示由无人值守回调拒绝 |
56
+ | `auto` | 由 Claude Code 原生分类器允许或拒绝权限请求 |
57
+ | `plan` | 使用原生规划模式,拒绝执行审批,并把完整计划作为最终答案返回 |
58
+ | `bypassPermissions` | 显式设置 SDK 的危险确认并跳过权限检查 |
59
+
60
+ 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-subagent-claude-code)是每个受支持字段及其 JSDoc 的穷尽式真源。已配置的 `model` 会原样传给该提供方实例的每次 query;省略时保留原生模型选择。具有凭证特征的环境变量会在显式 `env` 覆盖生效前被移除,因此供子进程使用的 API 密钥必须在该配置中显式提供。提供方省略 SDK 的 `settingSources` 选项,因此 Claude Code 会相对于父会话 cwd 读取宿主机常规的用户、项目与本地设置。它不会复制或过滤这些文件、创建或修改登录状态、检查 `PATH`,也不会回退到宿主 `claude` 可执行文件。
61
+
62
+ ### 暴露工具
63
+
64
+ 每个委派工具行指名一个提供方,并需要独立的 `toolName`,因此模型看到的是静态工具,而不是动态提供方选择器。完整 Agent Preset 携带对应的默认工具行并设置 `disabled: true`;复制一个 preset 后删除该字段,即可只向由该副本组装的 agent 暴露 `subagent_claude_code`。
73
65
 
74
66
  ```yaml
75
67
  - id: jobs
76
68
  name: '@deepseek-ai/dsh-jobs-local'
77
-
78
69
  - id: tool-jobs
79
70
  name: '@deepseek-ai/dsh-tool-jobs'
80
-
81
- - id: tool-subagent-claude-safe
82
- name: '@deepseek-ai/dsh-tool-subagent'
83
- disabled: true
84
- config:
85
- provider: claude-safe
86
- toolName: subagent_claude_safe
87
- backgroundMode: one-shot
88
- maxDepth: provider-managed
89
-
90
- - id: tool-subagent-claude-bypass
71
+ - id: tool-subagent-claude
91
72
  name: '@deepseek-ai/dsh-tool-subagent'
92
73
  config:
93
- provider: claude-bypass
94
- toolName: subagent_claude_bypass
74
+ provider: claude-code
75
+ toolName: subagent_claude_code
95
76
  backgroundMode: one-shot
96
77
  maxDepth: provider-managed
97
78
  ```
98
79
 
99
- ## 产品兼容性与证据
80
+ `one-shot` 策略会让省略 `run_in_background` 或传入 `false` 的调用继续在前台等待,而显式传入 `true` 会返回由父 agent 拥有的 Job id,供 `job_output` 或 `job_kill` 使用;base host(基础宿主)与完整 preset 已提供通用作业注册表和控制工具。
100
81
 
101
- 运行时依赖精确锁定为 `@anthropic-ai/claude-agent-sdk@0.3.220`,其八个平台包都携带 Claude Code 2.1.220。普通安装会按当前操作系统、CPU 及 Linux libc 选择一个载荷。对于当前 darwin-arm64 载荷,`npm pack --dry-run --json` 报告压缩包为 74,858,812 字节、解包后为 256,908,856 字节;其他平台可能不同,这些数值只用于披露而不是安装阈值。无密钥真实产品测试会让 SDK 选择 CLI,通过回环 Messages fixture 运行它,并断言共享子进程 argv 的首项就是该平台包的原生可执行文件。Loader 组合证明安装该 Bundle 只会注册休眠的 Claude Code provider,不会启动产品进程。
82
+ ### 你会得到什么
102
83
 
103
- 如果安装时省略 optional dependencies、当前平台不受支持,或所选载荷缺失,提供方注册仍保持休眠,但第一次委派会在 SDK 启动边界失败。调用方只会收到安全的 `query-start` / `unknown` 失败事实;原生载荷错误只保留在内部 cause 链和提供方 Host 日志中。提供方既不会探测宿主 CLI,也不会用它重试。
84
+ 前台调用会把严格的最终 Claude Code 答案交给模型;运行失败时则返回带停止原因与可选安全诊断的错误。后台调用先返回 Job id;随后通用作业控制面会送达完成通知,并通过 `job_output` 公开同一最终答案或失败状态。Claude Code 的推理、工具活动、中间消息、stderr 与工作区差异绝不会进入父级会话。
104
85
 
105
- Loader 组合证明 Bundle 默认实例、两个额外命名 Claude 实例与现有 Codex 包可以共存,而且不会启动任一产品。
86
+ ### 失败与恢复
106
87
 
107
- 限定于项目所有者身份的分发授权涵盖官方 SDK 及每个 SDK 版本声明的官方 CLI/平台载荷。[`THIRD_PARTY_NOTICES.md`](../../../THIRD_PARTY_NOTICES.md) 会披露当前可选载荷闭包,但不会认定其中声明的条款属于宽松许可;其他无关的非宽松运行时依赖仍会使第三方声明门禁失败。
88
+ 省略 optional dependencies、当前平台不受支持或所选载荷缺失的安装会让提供方保持休眠,并在第一次委派时于 SDK 启动边界以安全的 `query-start` / `unknown` 失败事实失败;不存在宿主 CLI 回退。原始产品错误只保留在内部 cause 链与提供方 Host 日志中。被取消的运行以 `aborted` 结算。
108
89
 
90
+ -----
91
+
92
+ <a id="understand-the-implementation"></a>
93
+ ## 理解实现
94
+
95
+ <details>
96
+ <summary>实现细节——点击展开</summary>
97
+
98
+ 本节解释提供方如何驱动真实 Claude Code CLI,以及可观察行为从何而来;完整约定见[使用本包](#use-this-package)。
99
+
100
+ ### 设计理念
101
+
102
+ - **每次运行一个全新 query。** 每次运行都拥有独立的 SDK query、取消控制器、CLI 进程与不持久化的产品会话;没有续接、恢复或池化。
103
+ - **原生设置是权威。** 提供方故意省略 SDK 的 `settingSources` 选项,因此 Claude Code 读取宿主机常规的用户、项目与本地设置;可选 `model` 与必需的 `permissionMode` 是仅有的 query 级覆盖。
104
+ - **刻意无人值守。** `AskUserQuestion` 被禁用,除 bypass 模式外权限提示都会被拒绝,因此 query 绝不会等待用户界面。
105
+
106
+ ### 源码地图
107
+
108
+ | 文件 | 职责 |
109
+ |---|---|
110
+ | [`src/index.ts`](src/index.ts) | 插件入口:config schema、提供方注册 |
111
+ | [`src/run.ts`](src/run.ts) | SDK query 生命周期、结果接受与权限处理 |
112
+ | [`src/process.ts`](src/process.ts) | dispose 时的进程树逐级终止 |
113
+ | [`cordis.patch.yml`](cordis.patch.yml) | 注册休眠提供方的 Profile patch 层 |
114
+
115
+ ### 运行流程
116
+
117
+ 一次启动只接受非空的文本块序列,并根据父会话确定子级 cwd。它创建私有 `AbortController`,用精确拼接的任务调用官方 SDK `query()`,并仅在 SDK 的 custom-spawn 钩子已经提供由子进程 seam 管理的活动 CLI 句柄后发布运行。提供方完整迭代消息流,只接受满足 `subtype: "success"`、`is_error: false` 且 `result` 非空白、随后迭代器正常结束的 `result` 消息。其余一切结果都映射为带固定类别的 `error` 诊断,命名生命周期阶段与已观测进程结果——类别集合见 [`src/run.ts`](src/run.ts)。本地取消会在结果竞态中胜出并映射为 `aborted`,且不附带失败诊断。
118
+
119
+ </details>
120
+
121
+ -----
122
+
123
+ <a id="further-exploration"></a>
124
+ ## 进一步探索
125
+
126
+ 当包级约定不够用时阅读以下页面。它们从本提供方逐步进入它接入的 seam 与兄弟产品提供方。
127
+
128
+ - [Subagent 子系统](../../../docs/subsystems/subagent.zh.md)——服务约定、提供方约定与终态结果语义。
129
+ - [dsh-subagent seam](../subagent/README.zh.md)——本提供方注册于其上的注册表与启动 API。
130
+ - [Codex subagent 提供方](../subagent-codex/README.zh.md)——经官方 app-server 协议的兄弟产品后端。
131
+ - [Claude Code 与 Codex 后端](../../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md)——产品提供方的设计记录。
132
+ - [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-subagent-claude-code)——每个受支持配置字段及其源声明。
133
+
134
+ -----
135
+
136
+ <a id="model-experience"></a>
109
137
  ## 模型体验
110
138
 
111
139
  ### 子级请求
112
140
 
113
- #### 模型看到的内容
141
+ #### 模型看到什么
114
142
 
115
- Claude Code 子级会在一个全新的 SDK query 中接收独立文本任务。它的工作区是父会话 cwd;其模型、系统指令、工具、沙箱和身份验证来自原生 Claude 设置,所选提供方实例的 Profile 配置会固定该 query 的环境与非交互权限模式,而可执行版本来自 Bundle 锁定的 SDK 平台载荷。
143
+ Claude Code 子级会在一个全新的 SDK query 中接收独立文本任务。它的工作区是父会话 cwd;所选提供方实例会固定已配置的模型、环境与非交互权限模式,而省略的模型及其余产品设置来自 Claude 原生配置。可执行版本来自 Bundle 锁定的 SDK 平台载荷。
116
144
 
117
- #### 对 token 的影响
145
+ #### Token 影响
118
146
 
119
- 子级需为独立的 Claude Code 上下文和 query 承担 token 开销。子级 token 不会进入父级上下文。
147
+ 子级需为独立的 Claude Code 上下文和 query 承担 token 成本。子级 token 不会进入父级上下文。
120
148
 
121
- #### 对 KV Cache 的影响
149
+ #### KV Cache 影响
122
150
 
123
- 这与父请求缓存相互独立。能否复用只取决于 Claude Code 自身的模型、指令、工具、原生设置和全新 query。
151
+ 与父级请求缓存相互独立。能否复用只取决于 Claude Code 自身的模型、指令、工具、原生设置和全新 query。
124
152
 
125
153
  ### 父级调度与结果(间接)
126
154
 
127
- #### 模型看到的内容
155
+ #### 模型看到什么
128
156
 
129
- 通过 `dsh-tool-subagent`,前台调用会让父级模型看到符合严格成功条件的 Claude Code 最终答案;若结果未完成,错误中会包含终止原因和可选的安全诊断。该诊断可以区分固定 SDK 错误类别、生命周期阶段和已观测的进程结果,而不复制原始产品文本。后台调用会先返回 Job id;随后通用作业控制面会送达完成通知,通过 `job_output` 公开同一最终答案或失败状态 detail,并允许 `job_kill` 请求取消。Claude Code 的推理、工具活动、中间消息、stderr、工作区差异、用量信息、产品标识符、工具输入和原始协议载荷均不会复制到父会话。
157
+ 通过 `dsh-tool-subagent`,前台调用会让父级模型看到符合严格成功条件的 Claude Code 最终答案;若结果未完成,错误中会包含终止原因和可选的安全诊断。该诊断可以区分粗粒度行动类别、生命周期阶段和已观测的进程结果,而不复制原始产品文本或版本专属 subtype 名称。后台调用会先返回 Job id;随后通用作业控制面会送达完成通知,通过 `job_output` 公开同一最终答案或失败状态 detail,并允许 `job_kill` 请求取消。Claude Code 的推理、工具活动、中间消息、stderr、工作区差异、用量信息、产品标识符、工具输入和原始协议载荷均不会复制到父会话。
130
158
 
131
- #### 对 token 的影响
159
+ #### Token 影响
132
160
 
133
161
  前台输入会增加工具结果中保留的最终答案或错误内容。后台输入还会包含启动确认、完成通知,以及 `job_output`、`job_kill` 或后续状态结果;子任务 token 仍不会进入父级上下文。本提供方自身不添加父级工具 schema。
134
162
 
135
- #### 对 KV Cache 的影响
163
+ #### KV Cache 影响
136
164
 
137
165
  仅追加:前台会在可复用的父请求前缀后增加一个结果,后台则会继续追加 Job 启动确认、通知以及后续控制或收集结果。后台调度可能增加一个由通知唤醒的轮次,但这些消息都不会改写更早的前缀。
138
166
 
139
- ## 已知限制与后续工作
140
-
141
- - **每次运行均新建一个 query 和一个进程**:不支持续接、恢复、池化、进度流或产品会话持久化。
142
- - **静态选择实例**:Profile 配置项固定提供方名称与工具绑定;调用无法动态选择提供方,而且每个公开工具都需要唯一的 `toolName`。
143
- - **宿主设置有意保持权威**:项目和用户设置可以改变模型、工具与行为;本提供方不提供经过筛选或与宿主环境隔离的生产模式。
144
- - **身份验证与账户状态仍由原生机制管理**:Bundle 会提供 CLI,但不会创建账户、登录或改写 Claude 设置;配置与身份验证失败会公开其生命周期阶段与安全的 `unknown` 回退,而不会增加单独的公开分类。
145
- - **委派时必须存在 SDK 平台载荷**:省略 optional dependencies 的安装、不受支持的平台以及缺失或损坏的载荷都会在第一次 query 时失败;不会回退到宿主 CLI。
146
- - **没有人工交互路径**:`AskUserQuestion` 被禁用,权限提示会被拒绝,MCP elicitation 会被拒绝,阻塞对话会快速失败而不会挂起。
147
- - **assistant 载荷仅包含最终文本**:失败运行可以额外公开独立的安全诊断;推理、中间消息、工具通信、用量信息、stderr 和工作区差异仍只保留在产品内部,通用 Job id、通知与状态来自共享作业运行时。
148
- - **没有可选的共享能力**:对于本提供方,共享服务会拒绝输出 schema、子任务角色设定、工具筛选和 harness 深度强制约束。
149
- - **没有按实际经过时间触发的超时或副作用回滚**:长时间运行的工作由调用方取消,且取消前已更改的文件或外部系统不会恢复原状。
167
+ ## 已知限制与延期工作
168
+
169
+ <a id="known-limitations-and-deferred-work"></a>
170
+
171
+
172
+ 这些限制说明本提供方何时不合适,或何时需要特别的运维注意。它们是当前包约束,不是通用 Claude Code 对比或任务积压。
173
+
174
+ - **每次运行均新建一个 query 和一个进程**——不支持续接、恢复、池化、进度流或产品会话持久化。
175
+ - **静态选择实例**——Profile 配置项固定提供方名称、可选模型与工具绑定;调用无法动态选择或修改提供方与模型,而且每个公开工具都需要唯一的 `toolName`。
176
+ - **宿主设置有意保持权威**——省略 `model` 时由项目与用户设置选择模型;原生设置始终保留其余工具和行为,本提供方不提供经过筛选或与宿主环境隔离的生产模式。
177
+ - **身份验证与账户状态仍由原生机制管理**——Bundle 会提供 CLI,但不会创建账户、登录或改写 Claude 设置;配置与身份验证失败会公开其生命周期阶段与安全的 `unknown` 回退,而不会增加单独的公开分类。
178
+ - **委派时必须存在 SDK 平台载荷**——省略 optional dependencies 的安装、不受支持的平台以及缺失或损坏的载荷都会在第一次 query 时失败;不会回退到宿主 CLI。
179
+ - **没有人工交互路径**——`AskUserQuestion` 被禁用,权限提示会被拒绝,MCP elicitation 会被拒绝,阻塞对话会快速失败而不会挂起。
180
+ - **assistant 载荷仅包含最终文本**——失败运行可以额外公开独立的安全诊断;推理、中间消息、工具通信、用量信息、stderr 和工作区差异仍只保留在产品内部,通用 Job id、通知与状态来自共享作业运行时。
181
+ - **没有可选的共享能力**——对于本提供方,共享服务会拒绝 `agentOptions`、输出 schema、子任务角色设定、工具筛选和 harness 深度强制约束。
182
+ - **没有按实际经过时间触发的超时或副作用回滚**——长时间运行的工作由调用方取消,且取消前已更改的文件或外部系统不会恢复原状。
183
+
184
+ <a id="dev-note"></a>
185
+ ### 开发备注
186
+
187
+ <details>
188
+ <summary>维护者的工作上下文——点击展开</summary>
189
+
190
+ 本开发备注是维护者的工作上下文:开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为与限制以上文和包代码为准。
191
+
192
+ - **载荷体积披露**——当前 darwin-arm64 平台载荷压缩后约 92 MB、解包后约 325 MB;这些是披露数字,不是安装阈值。
193
+ - **版本锁定的协议**——运行时依赖锁定为 Agent SDK 0.3.241;升级会锁定新的 SDK 版本,并需要重新运行无密钥真实产品与 loader 组合证据。
194
+
195
+ </details>
package/lib/index.js CHANGED
@@ -3,7 +3,7 @@ import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
3
3
  import { NO_START_CAPABILITIES, assertPositiveFinite, resolveChildCwd, settleRunResult, subprocessRunHandle } from "@deepseek-ai/dsh-subagent";
4
4
  import { randomUUID } from "node:crypto";
5
5
  import { query } from "@anthropic-ai/claude-agent-sdk";
6
- import { SessionId } from "@deepseek-ai/dsh-session";
6
+ import { brandString } from "@deepseek-ai/dsh-brand";
7
7
  import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
8
8
  import { EventEmitter } from "node:events";
9
9
  //#region lib/types/process.js
@@ -159,10 +159,10 @@ var ClaudeCodeFailure = class extends Error {
159
159
  };
160
160
  function sdkFailureCategory(subtype) {
161
161
  switch (subtype) {
162
- case "error_during_execution":
163
162
  case "error_max_turns":
164
163
  case "error_max_budget_usd":
165
- case "error_max_structured_output_retries": return subtype;
164
+ case "error_max_structured_output_retries": return "limit";
165
+ case "error_during_execution": return "product-error";
166
166
  default: return "unknown";
167
167
  }
168
168
  }
@@ -219,7 +219,7 @@ function successfulResult(message) {
219
219
  }
220
220
  if (message.is_error || message.result.trim().length === 0) throw new ClaudeCodeFailure({
221
221
  stage: "query-run",
222
- category: "invalid-success"
222
+ category: "invalid-result"
223
223
  });
224
224
  return message.result;
225
225
  }
@@ -244,7 +244,7 @@ async function consumeClaudeQuery(query, onPermissionDenied, onResult) {
244
244
  }
245
245
  if (answer === void 0) throw new ClaudeCodeFailure({
246
246
  stage: "query-run",
247
- category: "missing-result"
247
+ category: "invalid-result"
248
248
  });
249
249
  return {
250
250
  output: [{
@@ -294,6 +294,7 @@ function claudeQueryOptions(spec, controller, capture, captureDiagnostic) {
294
294
  return {
295
295
  abortController: controller,
296
296
  cwd: spec.cwd,
297
+ ...spec.model === void 0 ? {} : { model: spec.model },
297
298
  env: {
298
299
  ...scrubbedParentEnv(),
299
300
  ...spec.env
@@ -454,7 +455,7 @@ async function startClaudeCodeRun(request, spec) {
454
455
  };
455
456
  else if (processOutcome !== void 0 && !receivedResult) facts = {
456
457
  stage: "process",
457
- category: "process-exit",
458
+ category: "process",
458
459
  outcome: processOutcome
459
460
  };
460
461
  else facts = {
@@ -474,7 +475,7 @@ async function startClaudeCodeRun(request, spec) {
474
475
  onAbort
475
476
  });
476
477
  return subprocessRunHandle({
477
- id: SessionId(randomUUID()),
478
+ id: brandString(randomUUID()),
478
479
  result,
479
480
  signal: request.signal,
480
481
  onAbort,
@@ -504,6 +505,7 @@ const inject = ["subagents", "subprocess"];
504
505
  const DEFAULT_PROVIDER_NAME = "claude-code";
505
506
  const Config = z.object({
506
507
  providerName: z.string().min(1).default(DEFAULT_PROVIDER_NAME),
508
+ model: z.string().min(1),
507
509
  env: z.dict(z.string()).default({}),
508
510
  permissionMode: z.union([...CLAUDE_CODE_PERMISSION_MODES]).default(DEFAULT_CLAUDE_CODE_PERMISSION_MODE),
509
511
  disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS)
@@ -533,6 +535,7 @@ var ClaudeCodeProvider = class {
533
535
  }
534
536
  return startClaudeCodeRun(request, {
535
537
  cwd,
538
+ ...this.config.model === void 0 ? {} : { model: this.config.model },
536
539
  permissionMode: this.config.permissionMode,
537
540
  env: this.config.env,
538
541
  disposeGraceMs: this.config.disposeGraceMs,
@@ -546,11 +549,12 @@ var ClaudeCodeProvider = class {
546
549
  /**
547
550
  * Register one Profile-named Claude Code provider.
548
551
  * @param ctx - context carrying shared subagent and subprocess services.
549
- * @param config - registry name, permission mode, child environment, and disposal grace.
552
+ * @param config - registry name, optional model, permission mode, child environment, and disposal grace.
550
553
  */
551
554
  function apply(ctx, config) {
552
555
  const resolved = {
553
556
  providerName: config.providerName ?? DEFAULT_PROVIDER_NAME,
557
+ ...config.model === void 0 ? {} : { model: config.model },
554
558
  env: config.env,
555
559
  permissionMode: config.permissionMode ?? "dontAsk",
556
560
  disposeGraceMs: config.disposeGraceMs
@@ -10,10 +10,12 @@ import z from '@deepseek-ai/schemastery';
10
10
  import { type ClaudeCodePermissionMode } from './run.ts';
11
11
  export declare const name = "subagent-claude-code";
12
12
  export declare const inject: string[];
13
- /** Deployment-owned permission, environment, and process-release settings. */
13
+ /** Deployment-owned model, permission, environment, and process-release settings. */
14
14
  export interface Config {
15
15
  /** Provider name on `ctx.subagents` (default `claude-code`). */
16
16
  providerName?: string;
17
+ /** Native Claude model fixed for this instance; omitted to inherit Claude settings. */
18
+ model?: string;
17
19
  /**
18
20
  * Explicit environment entries layered over the subprocess seam's
19
21
  * credential-scrubbed parent environment.
@@ -33,7 +35,7 @@ export declare const Config: z<Config>;
33
35
  /**
34
36
  * Register one Profile-named Claude Code provider.
35
37
  * @param ctx - context carrying shared subagent and subprocess services.
36
- * @param config - registry name, permission mode, child environment, and disposal grace.
38
+ * @param config - registry name, optional model, permission mode, child environment, and disposal grace.
37
39
  */
38
40
  export declare function apply(ctx: Context, config: Config): void;
39
41
  //# sourceMappingURL=index.d.ts.map
@@ -28,6 +28,8 @@ export declare function claudeCodeStartupFailure(cause: unknown): Error;
28
28
  export interface ClaudeCodeRunSpec {
29
29
  /** Parent Session workspace supplied to the SDK and real CLI. */
30
30
  readonly cwd: string;
31
+ /** Profile-selected native model; omitted to preserve Claude settings. */
32
+ readonly model?: string;
31
33
  /** Profile-selected native non-interactive permission mode. */
32
34
  readonly permissionMode: ClaudeCodePermissionMode;
33
35
  /** Explicit deployment/test environment layered after shared scrubbing. */
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@deepseek-ai/dsh-subagent-claude-code",
3
3
  "description": "One-shot Claude Code subagent provider over the official Agent SDK",
4
- "version": "0.1.1-rc.2",
4
+ "version": "0.1.2-alpha.3",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -38,31 +38,40 @@
38
38
  }
39
39
  },
40
40
  "peerDependencies": {
41
- "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
42
- "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
43
- "@deepseek-ai/dsh-subagent": "^0.1.1-rc.2",
44
- "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
45
- "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
46
- "@deepseek-ai/cordis": "^4.0.1",
47
- "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
41
+ "@deepseek-ai/cordis": "^4.0.2",
42
+ "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
43
+ "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
44
+ "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
45
+ "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.3",
46
+ "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.3",
47
+ "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.3"
48
48
  },
49
49
  "dependencies": {
50
+ "@anthropic-ai/claude-agent-sdk": "0.3.241",
50
51
  "@anthropic-ai/sdk": "0.93.0",
51
- "@anthropic-ai/claude-agent-sdk": "0.3.220",
52
52
  "@modelcontextprotocol/sdk": "^1.29.0",
53
53
  "zod": "^4.4.3",
54
- "@deepseek-ai/schemastery": "^3.18.1"
54
+ "@deepseek-ai/dsh-brand": "^0.1.2-alpha.3",
55
+ "@deepseek-ai/schemastery": "^3.18.2"
55
56
  },
56
57
  "devDependencies": {
57
- "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
58
- "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
59
- "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
60
- "@deepseek-ai/dsh-loader-smoke": "^0.1.1-rc.2",
61
- "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
62
- "@deepseek-ai/dsh-subagent": "^0.1.1-rc.2",
63
- "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
64
- "@deepseek-ai/dsh-subprocess-local": "^0.1.1-rc.2",
65
- "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
66
- "@deepseek-ai/cordis": "^4.0.1"
58
+ "@deepseek-ai/cordis": "^4.0.2",
59
+ "@deepseek-ai/dsh-agent": "^0.1.2-alpha.3",
60
+ "@deepseek-ai/dsh-app-boot": "^0.1.2-alpha.3",
61
+ "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
62
+ "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
63
+ "@deepseek-ai/dsh-loader-smoke": "^0.1.2-alpha.3",
64
+ "@deepseek-ai/dsh-session-checkpoint-policy": "^0.1.2-alpha.3",
65
+ "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.2-alpha.3",
66
+ "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3",
67
+ "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
68
+ "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.3",
69
+ "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.3",
70
+ "@deepseek-ai/dsh-subagent-codex": "^0.1.2-alpha.3",
71
+ "@deepseek-ai/dsh-subprocess-local": "^0.1.2-alpha.3",
72
+ "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.3",
73
+ "@deepseek-ai/dsh-tool-jobs": "^0.1.2-alpha.3",
74
+ "@deepseek-ai/dsh-tools": "^0.1.2-alpha.3",
75
+ "@deepseek-ai/dsh-tool-subagent": "^0.1.2-alpha.3"
67
76
  }
68
77
  }