Preserve Claude SDK child environment

packages/subprocess/subprocess-local/src/spawn.ts

@@ -26,12 +26,12 @@ import type {
 
 /**
  * Build a child environment: explicit caller entries merge after the scrubbed
- * parent base, so a deliberately supplied credential or current `DSH_*` fact
- * wins over the scrub that dropped its ambient namesake.
- * @param extra - explicit caller entries, merged verbatim after the scrub.
+ * parent base. A string deliberately restores or overrides an entry; an
+ * explicit `undefined` tombstone removes an ordinary ambient entry.
+ * @param extra - explicit caller entries and tombstones, merged after the scrub.
  * @returns the environment to hand to `spawn` for the child process.
  */
-export function childEnv(extra?: Readonly<Record<string, string>>): NodeJS.ProcessEnv {
+export function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv {
   return { ...scrubbedParentEnv(), ...extra }
 }
 

packages/subprocess/subprocess-local/tests/spawn.spec.ts

@@ -343,6 +343,19 @@ describe('stdin and extra env (set by in-process plugins)', () => {
     expect(result.stdout.text).toBe('alpha/beta\n')
   })
 
+  it('lets an explicit tombstone remove an ordinary ambient env entry', async () => {
+    process.env.SUBPROCESS_TOMBSTONE_PROBE = 'ambient-value'
+    try {
+      const result = await finish(spawnSubprocess(spec(
+        'echo "${SUBPROCESS_TOMBSTONE_PROBE:-absent}"',
+        { env: { SUBPROCESS_TOMBSTONE_PROBE: undefined } },
+      )))
+      expect(result.stdout.text).toBe('absent\n')
+    } finally {
+      delete process.env.SUBPROCESS_TOMBSTONE_PROBE
+    }
+  })
+
   it('an explicit extra env entry overrides the credential scrub', async () => {
     // EXPLICIT_OVERRIDE_PASSWORD matches the credential scrub pattern, yet an explicit
     // entry is still honored — the scrub only drops AMBIENT process.env creds.

packages/subprocess/subprocess/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subprocess/subprocess/README.md
-README.md: c360437bf2b2b95734f55f6aec46b0cecffb9260
-README.zh.md: dac459a6ed1b92c2354bf0a2cc4e0c23e824154f
+README.md: 13c634429bfae9408dc732aea69df673e5da87aa
+README.zh.md: fe7b28d3a8f256e0eb9b4cbb98093bac33816fdf

packages/subprocess/subprocess/README.md

@@ -10,7 +10,7 @@ The subprocess seam (`ctx.subprocess`). The abstract `SubprocessService` exposes
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and the spec's explicit `env` merges after the scrub with no namespace validation — a deliberately forwarded credential or a current `DSH_*` fact survives precisely because it is an explicit caller opt-in, while the stale ambient namesake never reaches the child. Spawners that cannot route through the service (node-pty backends, SDK-managed transports) import the scrub.
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and the spec's explicit `env` merges after the scrub with no namespace validation — a string deliberately forwards or overrides a value, while an `undefined` tombstone removes an ordinary ambient entry. Spawners that cannot route through the service (node-pty backends, SDK-managed transports) import the scrub.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
 See the [subprocess data-structure catalog](../../../docs/core-data-structures/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).

packages/subprocess/subprocess/README.zh.md

@@ -10,7 +10,7 @@
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，spec 的显式 `env` 在清除之后合并且不做命名空间校验——有意转发的凭据或当前 `DSH_*` 事实之所以能保留下来，正因为它是调用方的显式选择，而陈旧的同名环境值永远到不了子进程。无法把 spawn 路由到该服务的进程启动方（node-pty 后端、由 SDK 管理的传输层）改为导入环境清理函数。
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，spec 的显式 `env` 在清理后合并且不做命名空间校验——字符串会有意转发或覆盖某个值，而 `undefined` tombstone 则会删除普通的环境条目。无法把 spawn 路由到该服务的进程启动方（node-pty 后端、由 SDK 管理的传输层）会导入该环境清理定义。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
 参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。

packages/subprocess/subprocess/src/types.ts

@@ -94,13 +94,12 @@ export interface SubprocessSpawnSpec {
   signal?: AbortSignal | undefined
   /**
    * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation:
-   * every entry is a deliberate caller opt-in, so a forwarded
-   * credential-shaped entry or a current `DSH_*` fact survives precisely
-   * because this layer merges after the scrub that drops its ambient
-   * namesake.
+   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
+   * string is a deliberate caller opt-in, so a forwarded credential-shaped
+   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
+   * tombstone that removes an ordinary ambient entry from the child.
    */
-  env?: Record<string, string> | undefined
+  env?: NodeJS.ProcessEnv | undefined
 }
 
 /**