Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts:
#	examples/acp-agent/tests/snapshots/cancel-tool-calls/session.jsonl

packages/bash/tool-bash/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/bash/tool-bash/README.md
-README.md: 29b9fba369e1fc6a4b8bb7bdd6543b7678df627d
-README.zh.md: 31f691f7bfb8d2cb905751663151c3f6a6bc6c57
+README.md: 35a5647365dab6daa903c14cba8b83702b50305d
+README.zh.md: eb7901f3445117988d77e6d39b73681480b7a754

packages/bash/tool-bash/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The model-facing `bash` tool registered over the `ctx.bash` executor seam. Foreground execution stays behind that seam; a background process handle is registered with the generic `ctx.tasks` runtime and controlled through `task_output`, `task_list`, and `task_kill` from `@deepseek-ai/dsh-tool-tasks`.
 
-Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash', 'systemPrompt']`).
+Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`) and the [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) registry; the plugin stays pending until every injected service exists (`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`). The tool contract is bash-dialect — mount a bash-parsing executor.
 
 The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering and background-process adaptation remain implementation details covered by same-package tests.
 
@@ -28,26 +28,7 @@ The plugin also contributes the `tool:bash` prompt section (order 105): check th
 
 ### Managed shell environment
 
-Every foreground and background model bash call receives a newly collected trusted `DSH_*` environment. `DSH_HOME` is the absolute Harness home resolved by [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) (`dshHome` config, then ambient `$DSH_HOME`, then `~/.dsh`) and `DSH_SHELL=1` identifies the managed child. Agent calls additionally receive `DSH_SESSION_ID=agent.session.header.id`; when the active persistence seam locates a JSONL artifact they also receive `DSH_SESSION_JSONL=<absolute target path>`. The JSONL path is a location hint: it may not exist before the first flush or contain the current buffered turn, and it is not an authorization credential.
-
-`ctx.bashEnv` owns collection. Other plugins can register an effect-scoped contributor with a stable name, declared keys/descriptions, and `resolve(execution: ToolExecution)`; duplicate ownership and undeclared runtime keys fail loudly, while `list()` enumerates declarations without executing providers. Harness built-ins reserve `DSH_HOME`, `DSH_SHELL`, and `DSH_SESSION_ID`; tool-bash's persistence translator owns `DSH_SESSION_JSONL` by reading the backend-neutral `sessionPersistence.locate()` seam.
-
-```ts
-import type { Context } from 'cordis'
-import type {} from '@deepseek-ai/dsh-tool-bash'
-
-export const inject = ['bashEnv']
-
-export function apply(ctx: Context): void {
-  ctx.bashEnv.register({
-    name: 'deployment-region',
-    variables: { DSH_DEPLOYMENT_REGION: { description: 'Current deployment region.' } },
-    resolve: execution => execution.agent === undefined ? {} : { DSH_DEPLOYMENT_REGION: 'cn-north' },
-  })
-}
-```
-
-The overlay is computed from the current `ToolExecution` and passed through the dedicated `BashExecRequest.dshEnv` channel. The local executor removes all inherited `DSH_*` before merging that snapshot, so nested harnesses and concurrent parent/child agents cannot leak stale identities. `process.env` is never modified. The tool description teaches the generic `$DSH_*` convention rather than naming persistence-specific variables or adding a permanent system-prompt section.
+Every foreground and background model bash call receives a freshly collected trusted `DSH_*` environment through the shared [`dsh-bash-env`](../bash-env/README.md) registry: `DSH_HOME` (the absolute Harness home), `DSH_SHELL=1`, the agent's `DSH_SESSION_ID`, and `DSH_SESSION_JSONL` when the active persistence backend locates one. The registry contract — contributor registration, loud duplicate/undeclared-key failure, the built-in reservations, and the contributor example — lives in that package's README. The snapshot passes through the dedicated `BashExecRequest.dshEnv` channel; the local executor removes all inherited `DSH_*` before merging it, so nested harnesses and concurrent parent/child agents cannot leak stale identities, and `process.env` is never modified. The tool description teaches the generic `$DSH_*` convention rather than naming persistence-specific variables or adding a permanent system-prompt section.
 
 Result text contains stdout, an optional `[stderr]` section, then applicable sandbox-denial, timeout, signal, exit-code, and truncation markers. Timeout is reported independently of final exit status; nonzero exit remains a model-interpreted result rather than `isError`. Truncation links a safe complete spill file or reports it unavailable. Only infrastructure failures such as spawn errors and aborts produce `isError`.
 
@@ -141,7 +122,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-Validation and policy failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `background execution is disabled for this bash tool`, `background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`.
+Validation and policy failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `background execution is disabled for this bash tool`, `background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`, the approval-availability/rejection/cancellation variants, and `tool call aborted`.
 
 #### Token effect
 

packages/bash/tool-bash/README.zh.md

@@ -4,7 +4,7 @@
 
 模型侧 `bash` 工具，注册在 `ctx.bash` 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 `ctx.tasks` 运行时，并通过 `task_output`、`task_list` 和 `task_kill` 控制；这些工具由 `@deepseek-ai/dsh-tool-tasks` 提供。
 
-需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）；在 `ctx.bash` 可用之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt']`）。
+需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具契约是 bash 方言——请挂载能解析 bash 的执行器。
 
 包（package）根只公开 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍是实现细节，由同包测试覆盖。
 
@@ -28,26 +28,7 @@
 
 ### 托管 shell 环境
 
-每次模型发起的前台或后台 bash 调用都会收到新收集的一组可信 `DSH_*` 环境变量。`DSH_HOME` 是由 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 解析出的 Harness home 绝对路径（依次采用 `dshHome` 配置、环境中的 `$DSH_HOME`、`~/.dsh`），`DSH_SHELL=1` 则标识受托管的子进程。Agent 调用还会收到 `DSH_SESSION_ID=agent.session.header.id`；当活跃的持久化 seam 找到 JSONL 产物时，也会收到 `DSH_SESSION_JSONL=<absolute target path>`。JSONL 路径只是位置提示：首次 flush 前它可能尚不存在，也可能不包含当前缓冲的轮次，并且它不是授权凭据。
-
-`ctx.bashEnv` 持有收集过程。其他插件可以注册具有 effect 作用域的贡献方，提供稳定名称、已声明的键／说明以及 `resolve(execution: ToolExecution)`；重复持有或运行时返回未声明的键会快速失败，而 `list()` 无需执行提供方即可列举声明。Harness 内置项保留 `DSH_HOME`、`DSH_SHELL` 和 `DSH_SESSION_ID`；tool-bash 的持久化转换器持有 `DSH_SESSION_JSONL`，其值来自后端无关的 `sessionPersistence.locate()` seam。
-
-```ts
-import type { Context } from 'cordis'
-import type {} from '@deepseek-ai/dsh-tool-bash'
-
-export const inject = ['bashEnv']
-
-export function apply(ctx: Context): void {
-  ctx.bashEnv.register({
-    name: 'deployment-region',
-    variables: { DSH_DEPLOYMENT_REGION: { description: 'Current deployment region.' } },
-    resolve: execution => execution.agent === undefined ? {} : { DSH_DEPLOYMENT_REGION: 'cn-north' },
-  })
-}
-```
-
-overlay 根据当前 `ToolExecution` 计算，并通过专用的 `BashExecRequest.dshEnv` 通道传递。本地执行器会先删除继承的所有 `DSH_*`，再合并该快照，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份。它绝不会修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
+每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表契约——贡献方注册、重复／未声明键的响亮失败、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
 
 结果文本依次包含 stdout、可选的 `[stderr]` 段落和适用的沙箱拒绝、超时、信号、退出代码及截断标记。超时与最终退出状态分别报告；非零退出仍是由模型解释的结果，不会成为 `isError`。截断结果会链接安全的完整 spill 文件，或报告文件不可用。只有 spawn 错误和中止等基础设施故障才会产生 `isError`。
 
@@ -141,7 +122,7 @@ renderer 先输出依数据而定的 stdout 尾部，再输出可选的 `[stderr
 
 #### 模型看到的内容
 
-验证和策略失败统一为 `Error: <message>`。此包的稳定消息包括 `invalid command: expected a non-empty string`、`invalid description: expected a non-empty string`、`invalid timeoutMs: expected a positive number, got <value>`、`invalid escalation: sandbox_permissions requires a justification`、`invalid escalation: justification is only valid together with sandbox_permissions`、`invalid justification: expected a non-empty sentence`、`background execution is disabled for this bash tool`、`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`、`sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`、`sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`、审批不可用／拒绝／取消变体，以及 `command aborted`。
+验证和策略失败统一为 `Error: <message>`。此包的稳定消息包括 `invalid command: expected a non-empty string`、`invalid description: expected a non-empty string`、`invalid timeoutMs: expected a positive number, got <value>`、`invalid escalation: sandbox_permissions requires a justification`、`invalid escalation: justification is only valid together with sandbox_permissions`、`invalid justification: expected a non-empty sentence`、`background execution is disabled for this bash tool`、`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`、`sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`、`sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`、审批不可用／拒绝／取消变体，以及 `tool call aborted`。
 
 #### Token 影响
 

packages/bash/tool-bash/package.json

@@ -29,12 +29,11 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-bash": "^0.0.1",
+    "@deepseek-ai/dsh-bash-env": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
-    "@deepseek-ai/dsh-paths": "^0.0.1",
     "@deepseek-ai/dsh-sandbox": "^0.0.1",
     "@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
@@ -49,15 +48,14 @@
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
     "@deepseek-ai/dsh-bash": "workspace:^",
+    "@deepseek-ai/dsh-bash-env": "workspace:^",
     "@deepseek-ai/dsh-bash-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-subprocess-local": "workspace:^",
-    "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",

packages/bash/tool-bash/src/index.ts

@@ -8,205 +8,39 @@
  * @module @deepseek-ai/dsh-tool-bash
  */
 
-import { Service, type Context } from 'cordis'
+import type { Context } from 'cordis'
 import z from 'schemastery'
 import { isAbsolute, resolve as resolvePath } from 'node:path'
 import { defineTool, TOOL_ABORTED } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, TerminalCallView, ToolExecution, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools'
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type {} from '@deepseek-ai/dsh-session-persistence'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tasks'
 import type {} from '@deepseek-ai/dsh-user-approval'
+import type {} from '@deepseek-ai/dsh-bash-env'
 import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { ESCALATION_TARGETS, approveEscalation, canonicalPath, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-bash'
-import type { BashRunResult, DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-bash'
-import { DSH_HOME_ENV, resolveDshHome } from '@deepseek-ai/dsh-paths'
+import type { BashRunResult } from '@deepseek-ai/dsh-bash'
 import { processOutcome } from './background.ts'
 import { parseExitStatus, renderProcessRead, renderResult } from './render.ts'
 
-declare module 'cordis' {
-  interface Context {
-    bashEnv: BashEnvRegistry
-  }
-}
-
 export const name = 'tool-bash'
-export const inject = ['tools', 'bash', 'systemPrompt']
+export const inject = ['tools', 'bash', 'systemPrompt', 'bashEnv']
 
-/** Configuration for the bash tool and its managed child environment. */
+/** Configuration for the bash tool. */
 export interface Config {
   /** Expose `run_in_background` (default true); disabled calls are also rejected. */
   enableRunInBackground?: boolean
-  /** DeepSeek Harness home directory exposed as `DSH_HOME`; defaults to `$DSH_HOME` or `~/.dsh`. */
-  dshHome?: string
 }
 
 /** Runtime configuration schema for the bash tool plugin. */
 export const Config: z<Config> = z.object({
   enableRunInBackground: z.boolean().default(true),
-  dshHome: z.string(),
 })
 
-/** Model-visible metadata for one managed `DSH_*` environment variable. */
-export interface BashEnvVariable {
-  /** Concise description of the environment fact represented by the variable. */
-  description: string
-}
-
-/**
- * A plugin contribution to the managed environment of each model bash call.
- * Declared keys make ownership conflicts detectable before the first command;
- * `resolve` computes only the values available for the current execution.
- */
-export interface BashEnvContributor {
-  /** Stable contributor name used in diagnostics and duplicate detection. */
-  name: string
-  /** Complete set of `DSH_*` keys this contributor may return. */
-  variables: Readonly<Record<DshEnvironmentKey, BashEnvVariable>>
-  /**
-   * Resolve this contributor's available values for one tool execution.
-   * @param execution - the bash tool execution and its optional calling agent.
-   * @returns a partial map containing only keys declared in {@link variables}.
-   */
-  resolve(execution: ToolExecution): Readonly<Partial<Record<DshEnvironmentKey, string>>>
-}
-
-/** An enumerable declaration returned by {@link BashEnvRegistry.list}. */
-export interface BashEnvVariableInfo extends BashEnvVariable {
-  /** Contributor that owns the variable. */
-  contributor: string
-  /** Declared `DSH_*` environment variable name. */
-  key: DshEnvironmentKey
-}
-
-const DSH_SHELL_KEY = `${DSH_ENV_PREFIX}SHELL` as const
-const DSH_SESSION_ID_KEY = `${DSH_ENV_PREFIX}SESSION_ID` as const
-const DSH_SESSION_JSONL_KEY = `${DSH_ENV_PREFIX}SESSION_JSONL` as const
-const RESERVED_BASH_ENV_KEYS = new Set<DshEnvironmentKey>([
-  DSH_HOME_ENV,
-  DSH_SHELL_KEY,
-  DSH_SESSION_ID_KEY,
-])
-const BASH_ENV_KEY_SUFFIX = /^[A-Z][A-Z0-9_]*$/
-
-/**
- * Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables.
- * The namespace is rebuilt for every model bash call: ambient `DSH_*` values
- * are discarded by the executor, then the registry's current snapshot is
- * injected. Built-in shell facts remain owned by the registry itself while
- * plugins can register additional, enumerable facts with effect-scoped
- * disposal.
- */
-export class BashEnvRegistry extends Service {
-  private readonly contributors = new Map<string, BashEnvContributor>()
-  private readonly keyOwners = new Map<DshEnvironmentKey, string>()
-  private readonly dshHome: string
-
-  /**
-   * Create and install the `ctx.bashEnv` service.
-   * @param ctx - Cordis context that owns the service and registrations.
-   * @param config - home-directory configuration for the built-in variables.
-   */
-  constructor(ctx: Context, config: Config = {}) {
-    super(ctx, 'bashEnv')
-    this.dshHome = resolveDshHome(config.dshHome)
-  }
-
-  /**
-   * Register one environment contributor. Names and keys are unique; built-in
-   * keys are reserved. Registration is disposed with the calling plugin fiber.
-   * @param contributor - declared key ownership and per-execution resolver.
-   * @returns the disposer that unregisters the contribution.
-   */
-  register(contributor: BashEnvContributor): () => void {
-    const dispose = this.ctx.effect(function* (this: BashEnvRegistry) {
-      if (contributor.name.trim().length === 0) {
-        throw new Error('bash env contributor name must be non-empty')
-      }
-      if (this.contributors.has(contributor.name)) {
-        throw new Error(`bash env contributor "${contributor.name}" is already registered`)
-      }
-
-      const variables = Object.entries(contributor.variables) as [DshEnvironmentKey, BashEnvVariable][]
-      for (const [key, variable] of variables) {
-        if (!key.startsWith(DSH_ENV_PREFIX)
-          || !BASH_ENV_KEY_SUFFIX.test(key.slice(DSH_ENV_PREFIX.length))) {
-          throw new Error(`bash env contributor "${contributor.name}" declared invalid key "${key}"`)
-        }
-        if (RESERVED_BASH_ENV_KEYS.has(key)) {
-          throw new Error(`bash env contributor "${contributor.name}" cannot own reserved key "${key}"`)
-        }
-        if (variable.description.trim().length === 0) {
-          throw new Error(`bash env contributor "${contributor.name}" must describe "${key}"`)
-        }
-        const owner = this.keyOwners.get(key)
-        if (owner !== undefined) {
-          throw new Error(`bash env key "${key}" is already owned by contributor "${owner}"; contributor "${contributor.name}" cannot also own it`)
-        }
-      }
-
-      this.contributors.set(contributor.name, contributor)
-      for (const [key] of variables) this.keyOwners.set(key, contributor.name)
-      yield () => {
-        this.contributors.delete(contributor.name)
-        for (const [key] of variables) this.keyOwners.delete(key)
-      }
-    }.bind(this), 'bashEnv.register()')
-    return () => void dispose()
-  }
-
-  /**
-   * Build the trusted `DSH_*` snapshot for one bash tool execution.
-   * @param execution - the current tool execution.
-   * @returns an immutable environment overlay containing built-ins and current contributions.
-   */
-  collect(execution: ToolExecution): DshEnvironment {
-    const values: Record<DshEnvironmentKey, string> = {
-      [DSH_HOME_ENV]: this.dshHome,
-      [DSH_SHELL_KEY]: '1',
-    }
-    if (execution.agent !== undefined) {
-      values[DSH_SESSION_ID_KEY] = execution.agent.session.header.id
-    }
-
-    for (const contributor of [...this.contributors.values()].sort((left, right) => left.name.localeCompare(right.name))) {
-      const resolved = contributor.resolve(execution)
-      for (const [rawKey, value] of Object.entries(resolved)) {
-        const key = rawKey as DshEnvironmentKey
-        if (!Object.hasOwn(contributor.variables, key)) {
-          throw new Error(`bash env contributor "${contributor.name}" returned undeclared key "${key}"`)
-        }
-        if (typeof value !== 'string') {
-          throw new Error(`bash env contributor "${contributor.name}" returned a non-string value for "${key}"`)
-        }
-        values[key] = value
-      }
-    }
-
-    return Object.freeze(Object.fromEntries(Object.entries(values).sort(([left], [right]) => left.localeCompare(right))))
-  }
-
-  // TODO(bash-env-list-builtins): Include registry-owned built-ins before diagnostics,
-  // prompt, or UI code treats list() as an exhaustive environment catalog.
-  /**
-   * Enumerate plugin-contributed variables without executing their resolvers.
-   * @returns declarations sorted by environment variable name.
-   */
-  list(): BashEnvVariableInfo[] {
-    return [...this.contributors.values()]
-      .flatMap(contributor => Object.entries(contributor.variables).map(([key, variable]) => ({
-        contributor: contributor.name,
-        description: variable.description,
-        key: key as DshEnvironmentKey,
-      })))
-      .sort((left, right) => left.key.localeCompare(right.key))
-  }
-}
-
 /** Parsed tool args; execute validates value constraints absent from ParameterSchemaSpec. */
 interface BashToolArgs {
   command: string
@@ -354,24 +188,6 @@ const BACKGROUND_OUTPUT_PROPERTIES = {
 } as const
 
 export function apply(ctx: Context, config: Config = {}): void {
-  // FIXME(bash-env-ownership): Move ctx.bashEnv to a tool-independent shell
-  // environment plugin; replacing this tool with persistent Bash must not
-  // remove the managed DSH_* contributor seam.
-  const bashEnv = new BashEnvRegistry(ctx, config)
-  bashEnv.register({
-    name: 'session-persistence',
-    variables: {
-      [DSH_SESSION_JSONL_KEY]: {
-        description: 'Absolute target path of the current session JSONL when the active persistence backend provides one.',
-      },
-    },
-    resolve(execution) {
-      const agent = execution.agent
-      if (agent === undefined) return {}
-      const location = ctx.get('sessionPersistence')?.locate(agent.session.header)
-      return location?.kind === 'jsonl' ? { [DSH_SESSION_JSONL_KEY]: location.path } : {}
-    },
-  })
   const backgroundEnabled = config.enableRunInBackground ?? true
   const defaultMode = ctx.bash.sandboxMode
   const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS
@@ -522,7 +338,7 @@ export function apply(ctx: Context, config: Config = {}): void {
         ? standingPolicy
         : { ...(standingPolicy as SandboxExecutionPolicy), mode: approvedMode }
       const workdir = resolveWorkdir(args.workdir, exec, standingPolicy?.workspaceRoot)
-      const dshEnv = bashEnv.collect(exec)
+      const dshEnv = ctx.bashEnv.collect(exec)
       const request = {
         command: args.command,
         ...workdir !== undefined ? { workdir } : {},
@@ -565,7 +381,11 @@ export function apply(ctx: Context, config: Config = {}): void {
         ...request,
         signal: exec.signal,
       }))
-      if (result.aborted) throw new Error('command aborted')
+      if (result.aborted) {
+        const error = new HarnessError('tool call aborted', TOOL_ABORTED)
+        error.name = 'AbortError'
+        throw error
+      }
       return { kind: 'foreground' as const, ...canonicalBashResult(result) }
     },
     presentCall: presentBashCall,

packages/bash/tool-bash/tests/bash-env.spec.ts

@@ -1,193 +0,0 @@
-import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
-import { CallId } from '@deepseek-ai/dsh-llm'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { ToolExecution } from '@deepseek-ai/dsh-tools'
-import { BashEnvRegistry } from '@deepseek-ai/dsh-tool-bash'
-
-const testToolSignal = new AbortController().signal
-
-afterEach(() => vi.unstubAllEnvs())
-
-function execution(sessionId?: string): ToolExecution {
-  return {
-    signal: testToolSignal,
-    token: Symbol('bash-env-test') as ToolExecution['token'],
-    callId: CallId('bash-env-call'),
-    name: 'bash',
-    arguments: { command: 'true' },
-    ...(sessionId === undefined
-      ? {}
-      : { agent: { session: { header: { version: 0, id: sessionId, createdAt: 0 } } } as Agent }),
-  }
-}
-
-describe('BashEnvRegistry', () => {
-  it('collects unconditional shell facts and the current agent session id', () => {
-    const ctx = new Context()
-    const registry = new BashEnvRegistry(ctx, { dshHome: './test-dsh-home' })
-
-    expect(registry.collect(execution())).toEqual({
-      DSH_HOME: resolve('./test-dsh-home'),
-      DSH_SHELL: '1',
-    })
-    expect(registry.collect(execution('session-a'))).toEqual({
-      DSH_HOME: resolve('./test-dsh-home'),
-      DSH_SESSION_ID: 'session-a',
-      DSH_SHELL: '1',
-    })
-  })
-
-  it('resolves DSH_HOME from the ambient override or the user-home default', () => {
-    vi.stubEnv('DSH_HOME', './ambient-dsh-home')
-    const fromEnvironment = new BashEnvRegistry(new Context())
-    expect(fromEnvironment.collect(execution()).DSH_HOME).toBe(resolve('./ambient-dsh-home'))
-
-    vi.stubEnv('DSH_HOME', undefined)
-    const fromDefault = new BashEnvRegistry(new Context())
-    expect(fromDefault.collect(execution()).DSH_HOME).toBe(join(homedir(), '.dsh'))
-  })
-
-  it('collects declared contributor variables and omits unavailable values', () => {
-    const ctx = new Context()
-    const registry = new BashEnvRegistry(ctx, { dshHome: './test-dsh-home' })
-    registry.register({
-      name: 'optional-session-fact',
-      variables: {
-        DSH_SESSION_OPTIONAL: { description: 'Optional session-scoped test fact.' },
-      },
-      resolve: exec => exec.agent === undefined ? {} : { DSH_SESSION_OPTIONAL: exec.agent.session.header.id },
-    })
-    registry.register({
-      name: 'always-available-fact',
-      variables: {
-        DSH_ALWAYS_AVAILABLE: { description: 'Always-available test fact.' },
-      },
-      resolve: () => ({ DSH_ALWAYS_AVAILABLE: 'yes' }),
-    })
-
-    expect(registry.collect(execution())).not.toHaveProperty('DSH_SESSION_OPTIONAL')
-    expect(registry.collect(execution()).DSH_ALWAYS_AVAILABLE).toBe('yes')
-    expect(registry.collect(execution('session-b')).DSH_SESSION_OPTIONAL).toBe('session-b')
-    expect(registry.list()).toEqual([
-      {
-        contributor: 'always-available-fact',
-        description: 'Always-available test fact.',
-        key: 'DSH_ALWAYS_AVAILABLE',
-      },
-      {
-        contributor: 'optional-session-fact',
-        description: 'Optional session-scoped test fact.',
-        key: 'DSH_SESSION_OPTIONAL',
-      },
-    ])
-  })
-
-  it('rejects duplicate variable ownership at registration time', () => {
-    const ctx = new Context()
-    const registry = new BashEnvRegistry(ctx, { dshHome: './test-dsh-home' })
-    registry.register({
-      name: 'first',
-      variables: { DSH_SHARED: { description: 'First owner.' } },
-      resolve: () => ({ DSH_SHARED: 'first' }),
-    })
-
-    expect(() => registry.register({
-      name: 'second',
-      variables: { DSH_SHARED: { description: 'Second owner.' } },
-      resolve: () => ({ DSH_SHARED: 'second' }),
-    })).toThrow(/DSH_SHARED.*first.*second|DSH_SHARED.*second.*first/)
-  })
-
-  it('rejects duplicate contributor names and malformed declarations', () => {
-    const registry = new BashEnvRegistry(new Context(), { dshHome: './test-dsh-home' })
-    registry.register({
-      name: 'declared',
-      variables: { DSH_DECLARED: { description: 'Declared fact.' } },
-      resolve: () => ({}),
-    })
-
-    expect(() => registry.register({
-      name: 'declared',
-      variables: { DSH_ANOTHER: { description: 'Another fact.' } },
-      resolve: () => ({}),
-    })).toThrow(/already registered/)
-    expect(() => registry.register({
-      name: ' ',
-      variables: { DSH_BLANK_NAME: { description: 'Blank owner.' } },
-      resolve: () => ({}),
-    })).toThrow(/name must be non-empty/)
-    expect(() => registry.register({
-      name: 'invalid-key',
-      variables: { dsh_invalid: { description: 'Invalid key.' } } as unknown as Record<'DSH_INVALID', { description: string }>,
-      resolve: () => ({}),
-    })).toThrow(/invalid key/)
-    expect(() => registry.register({
-      name: 'reserved-key',
-      variables: { DSH_HOME: { description: 'Reserved key.' } },
-      resolve: () => ({}),
-    })).toThrow(/reserved key/)
-    expect(() => registry.register({
-      name: 'blank-description',
-      variables: { DSH_BLANK_DESCRIPTION: { description: ' ' } },
-      resolve: () => ({}),
-    })).toThrow(/must describe/)
-  })
-
-  it('rejects undeclared variables returned by a contributor', () => {
-    const ctx = new Context()
-    const registry = new BashEnvRegistry(ctx, { dshHome: './test-dsh-home' })
-    registry.register({
-      name: 'drifted-provider',
-      variables: { DSH_DECLARED: { description: 'Declared fact.' } },
-      resolve: () => ({ DSH_UNDECLARED: 'bad' }),
-    })
-
-    expect(() => registry.collect(execution())).toThrow(/drifted-provider.*DSH_UNDECLARED/)
-  })
-
-  it('rejects non-string values returned by a contributor', () => {
-    const registry = new BashEnvRegistry(new Context(), { dshHome: './test-dsh-home' })
-    registry.register({
-      name: 'wrong-value-type',
-      variables: { DSH_STRING: { description: 'String fact.' } },
-      resolve: () => ({ DSH_STRING: 42 }) as unknown as Record<'DSH_STRING', string>,
-    })
-
-    expect(() => registry.collect(execution())).toThrow(/wrong-value-type.*non-string.*DSH_STRING/)
-  })
-
-  it('removes an effect-scoped contributor when its plugin is disposed', async () => {
-    const ctx = new Context()
-    const registry = new BashEnvRegistry(ctx, { dshHome: './test-dsh-home' })
-    const fiber = await ctx.plugin({
-      inject: ['bashEnv'],
-      apply(inner: Context) {
-        inner.bashEnv.register({
-          name: 'temporary',
-          variables: { DSH_TEMPORARY: { description: 'Temporary fact.' } },
-          resolve: () => ({ DSH_TEMPORARY: 'present' }),
-        })
-      },
-    })
-
-    expect(registry.collect(execution()).DSH_TEMPORARY).toBe('present')
-    await fiber.dispose()
-    expect(registry.collect(execution())).not.toHaveProperty('DSH_TEMPORARY')
-  })
-
-  it('returns an explicit contributor disposer', () => {
-    const registry = new BashEnvRegistry(new Context(), { dshHome: './test-dsh-home' })
-    const dispose = registry.register({
-      name: 'explicit-disposal',
-      variables: { DSH_EXPLICIT_DISPOSAL: { description: 'Explicitly disposed fact.' } },
-      resolve: () => ({ DSH_EXPLICIT_DISPOSAL: 'present' }),
-    })
-
-    expect(registry.collect(execution()).DSH_EXPLICIT_DISPOSAL).toBe('present')
-    dispose()
-    expect(registry.collect(execution())).not.toHaveProperty('DSH_EXPLICIT_DISPOSAL')
-  })
-})

packages/bash/tool-bash/tests/integration.spec.ts

@@ -14,6 +14,7 @@ import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
+import * as BashEnvPlugin from '@deepseek-ai/dsh-bash-env'
 import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 
 /**
@@ -32,8 +33,9 @@ async function harness(adapter: MockAdapter, sessionRoot?: string, dshHome?: str
   await ctx.plugin(LocalTaskService)
   await ctx.plugin(ToolTasks)
   await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(BashEnvPlugin, dshHome === undefined ? {} : { dshHome })
   await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
-  await ctx.plugin(ToolBash, dshHome === undefined ? {} : { dshHome })
+  await ctx.plugin(ToolBash)
   ctx.llm.registerAdapter(['mock'], adapter)
   return ctx
 }

packages/bash/tool-bash/tests/tools.spec.ts

@@ -20,6 +20,7 @@ import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
+import * as BashEnvPlugin from '@deepseek-ai/dsh-bash-env'
 import { processOutcome } from '../src/background.ts'
 import { renderProcessRead, renderResult } from '../src/render.ts'
 
@@ -35,6 +36,7 @@ async function setup() {
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(LocalSubprocessService)
   ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
+  await ctx.plugin(BashEnvPlugin)
   await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
   await ctx.plugin(ToolBash)
   return ctx
@@ -50,6 +52,7 @@ async function setupWithTasks() {
   await ctx.plugin(ToolTasks)
   await ctx.plugin(LocalSubprocessService)
   ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
+  await ctx.plugin(BashEnvPlugin)
   await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
   await ctx.plugin(ToolBash)
   return ctx
@@ -188,6 +191,7 @@ async function setupSandboxed(withApproval = false) {
   await ctx.plugin(SandboxPolicyService, {})
   await ctx.plugin(RecordingSandboxExecutor)
   if (withApproval) await ctx.plugin(ApprovalService)
+  await ctx.plugin(BashEnvPlugin)
   await ctx.plugin(ToolBash)
   return { ctx, bash: ctx.bash as RecordingSandboxExecutor }
 }
@@ -281,6 +285,7 @@ describe('bash tool', () => {
     await ctx.plugin(LocalSubprocessService)
     ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
     await ctx.plugin(LocalBashExecutor, { maxOutputBytes: 100, graceMs: 200 })
+    await ctx.plugin(BashEnvPlugin)
     await ctx.plugin(ToolBash)
     const result = await call(ctx, 'bash', { command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i; done', description: 'test command' })
     expect(text(result)).toContain('[output truncated; full output: ')
@@ -300,7 +305,7 @@ describe('bash tool', () => {
     expect(text(result)).toMatch(/ENOENT/)
   })
 
-  it('surfaces foreground aborts as isError', async () => {
+  it('surfaces foreground aborts as the structured TOOL_ABORTED error', async () => {
     const ctx = await setup()
     const controller = new AbortController()
     const pending = ctx.tools.execute({
@@ -312,7 +317,10 @@ describe('bash tool', () => {
     setTimeout(() => { controller.abort() }, 50)
     const result = await pending
     expect(result.isError).toBe(true)
-    expect(text(result)).toMatch(/aborted/)
+    expect(result.error).toMatchObject({
+      message: 'tool call aborted',
+      info: { name: 'AbortError', code: TOOL_ABORTED },
+    })
   })
 
   // Type and required-key violations are rejected by the harness
@@ -389,6 +397,7 @@ describe('bash tool', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(LocalSubprocessService)
     await ctx.plugin(LocalBashExecutor, {})
+    await ctx.plugin(BashEnvPlugin)
     const fiber = await ctx.plugin(ToolBash)
     expect(ctx.tools.schemas()).toHaveLength(1)
     expect((await ctx.systemPrompt.assemble()).sections.map(s => s.name)).toEqual(['harness:identity', 'deployment:persona', 'tool:bash'])
@@ -403,6 +412,7 @@ describe('bash tool', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     // inject: ['tools', 'bash'] keeps the plugin pending until bash exists.
+    await ctx.plugin(BashEnvPlugin)
     await ctx.plugin(ToolBash)
     expect(ctx.tools.schemas()).toHaveLength(0)
     await ctx.plugin(LocalSubprocessService)
@@ -493,6 +503,7 @@ describe('background execution through the task runtime', () => {
     await ctx.plugin(LocalTaskService)
     await ctx.plugin(ToolTasks)
     await ctx.plugin(CountingStartExecutor)
+    await ctx.plugin(BashEnvPlugin)
     await ctx.plugin(ToolBash)
 
     const controller = new AbortController()
@@ -520,6 +531,7 @@ describe('background execution through the task runtime', () => {
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(LocalTaskService)
     await ctx.plugin(CountingStartExecutor)
+    await ctx.plugin(BashEnvPlugin)
     await ctx.plugin(ToolBash)
 
     const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
@@ -534,6 +546,7 @@ describe('background execution through the task runtime', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(BashEnvPlugin)
     await ctx.plugin(LocalBashExecutor, {})
     await ctx.plugin(ToolBash, { enableRunInBackground: false })
 
@@ -568,6 +581,7 @@ describe('sandbox escalation through the generic task producer', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(RecordingSandboxExecutor)
+    await ctx.plugin(BashEnvPlugin)
     await expect(ctx.plugin(ToolBash)).rejects.toThrow('tool-bash: the mounted bash executor confines but ctx.sandboxPolicy is missing')
   })
 
@@ -1003,9 +1017,9 @@ describe('tool-owned UI presentation (presentCall / presentResult)', () => {
     // not renderResult output, so a generic fenced card, no terminal output/exit.
     const out = ctx.tools.get('bash')!.presentResult!(
       { command: 'x', description: 'x' },
-      { content: [{ type: 'text', text: 'command aborted' }], isError: true },
+      { content: [{ type: 'text', text: 'tool call aborted' }], isError: true },
     )
-    expect(out).toEqual({ card: 'generic', content: [{ type: 'text', text: '```console\ncommand aborted\n```' }] })
+    expect(out).toEqual({ card: 'generic', content: [{ type: 'text', text: '```console\ntool call aborted\n```' }] })
   })
 
   it('bash presentResult: leaves a non-text (unexpected) result untouched → undefined (UI keeps raw content)', async () => {
@@ -1097,8 +1111,9 @@ describe('the model-facing bash tool builds its request from named args only (no
     }
     await ctx.plugin(LocalTaskService)
     await ctx.plugin(ToolTasks)
+    await ctx.plugin(BashEnvPlugin, { dshHome: recordingDshHome })
     await ctx.plugin(RecordingBashExecutor)
-    await ctx.plugin(ToolBash, { dshHome: recordingDshHome })
+    await ctx.plugin(ToolBash)
     return { ctx, bash: ctx.bash as RecordingBashExecutor }
   }
 

packages/bash/tool-bash/tsconfig.json

@@ -26,21 +26,18 @@
     {
       "path": "../../core/agent"
     },
-    {
-      "path": "../../session-persistence/session-persistence"
-    },
     {
       "path": "../../bash/bash"
     },
-    {
-      "path": "../../util/paths"
-    },
     {
       "path": "../../tasks/tasks"
     },
     {
       "path": "../../core/system-prompt"
     },
+    {
+      "path": "../../bash/bash-env"
+    },
     {
       "path": "../../ui/user-approval"
     },