@deepseek-ai/dsh-tool-bash 0.1.6-alpha.1 → 0.1.7-alpha.1

package/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/shell/tool-bash/README.md
-README.md: 43c70d7ebc8eb13f28c4e4576dfde8cb2402b775
-README.zh.md: e38e7afa6b7a534fe29d1022fc2797f5a98651b0
+README.md: 3068e6d201758a2f66529155de12d1dbf912bae2
+README.zh.md: 032d59efa33b702c8d0b202ebd33e60ae63f6804

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-tool-bash` lets an agent run one-shot `bash` commands and receive stdout, stderr, and exit markers. Each call uses a fresh shell, so cwd, variables, and functions do not persist; `run_in_background` starts long-running work that the agent can inspect with `job_output` and stop with `job_kill`. Commands receive the managed `DSH_*` environment, and sandbox denials can be retried once with wider `sandbox_permissions`, a `justification`, and user approval. Non-zero exits are reported as results, so the agent decides how to respond; use an executor such as `dsh-bash-local` or `dsh-bash-sandbox` and load `dsh-shell-env`.
+`dsh-tool-bash` runs Bash commands and returns stdout, stderr, and exit markers. Each call uses a fresh shell; cwd, variables, and functions do not persist. With a job registry composed, every command is a job from its start: `run_in_background` returns the id at once, a foreground command that outlives its timeout returns the same id, and `job_output`/`job_kill` collect and stop it. Commands receive the managed `DSH_*` environment; sandbox denials can be retried once with wider `sandbox_permissions`, a `justification`, and user approval. Nonzero exits are results for the agent to interpret. Mount an executor such as `dsh-bash-local` or `dsh-bash-sandbox` with `dsh-shell-env`.
 
 ## Table of Contents
 
@@ -41,11 +41,12 @@ The common path is an executor provider, the environment registry, and this tool
 - name: '@deepseek-ai/dsh-tool-jobs'
 ```
 
-The single config field toggles background support.
+The config fields govern the background surface.
 
 | Field | Default | Meaning |
 |---|---|---|
-| `enableRunInBackground` | `true` | Expose `run_in_background`; when `false`, forced background calls are rejected |
+| `enableRunInBackground` | `true` | Expose `run_in_background` while a job registry is composed; when `false`, forced background calls are rejected |
+| `promoteOnTimeout` | `true` | Keep a foreground command that reaches its timeout running as its background job instead of killing it |
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-bash) is the exhaustive source for every accepted field and its JSDoc; the generated [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash) carries the full argument schema.
 
@@ -56,11 +57,15 @@ The tool executes `bash -c <command>` and returns the combined output. Commands
 <a id="running-long-commands-in-the-background"></a>
 ### Running long commands in the background
 
-Passing `run_in_background: true` admits a job and returns its id immediately; confinement preparation may still be pending, and no background execution timeout applies. Output is empty until the process is available. Job cancellation aborts preparation and stops any process that arrives afterward; startup failure settles the admitted job as failed. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted.
+Passing `run_in_background: true` admits a job and returns its id immediately; confinement preparation may still be pending, and no background execution timeout applies. Output is empty until the process is available. Job cancellation aborts preparation and stops any process that arrives afterward; startup failure settles the admitted job as failed. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted. The background job hands the run's non-consuming `observed` readers to the job registry as pull sources; the registry pumps them into the job's output ring at its own cadence (`pumpPollMs` on `dsh-jobs-local`), so the Web client streams live output and the model's `job_output` reads consume the same bytes through a separate cursor. A reader that throws is logged once and its stream stops; the job runs on to its own settlement. The ring is a best-effort live preview: stdout and stderr are copied per poll round, so writes the two streams made inside one poll window appear stdout first rather than in write order.
+
+### Foreground commands as jobs
+
+With a job registry composed, a foreground command is registered with `ctx.jobs` at its start and the call waits on that job: the command is listed, streams through `job.list` and `job.follow`, and can be stopped from the Web task list for as long as it runs. A command that finishes within the timeout returns the ordinary foreground result and its job record leaves the registry with it, so the model never sees an id. A command that outlives the timeout keeps running as the job it already was, and the call returns `[still running after <timeoutMs>ms; moved to background job <id>]` plus the job hand-off guidance, seeded with one consuming read of the output so far — `job_output` continues exactly after it. A kill from outside the call (the human stopping the job) settles the foreground result with `[stopped: <reason>]` ahead of the signal marker, so the model reads the reason instead of a command failure; cancelling the call itself kills the job. Registration is best-effort: `promoteOnTimeout: false`, a missing job registry, or a registry that refuses the job at its start (the owner's job limit, no controller) run the command under the executor's deadline kill instead, and the tool description advertises the hand-over only when it holds.
 
 ### Sandboxed execution and escalation
 
-When the mounted executor confines commands (for example `dsh-bash-sandbox`), a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a command failure. The model may then retry the exact same command once in the same turn with `sandbox_permissions` (the narrowest wider mode that suffices) and a one-sentence `justification`; the approval prompt raised by that retry is how the user consents. Escalation is never speculative: a request with no real prior denial, or one that is not strictly wider than the current mode, fails closed without running anything, and a rejected escalation is final for that command.
+When the mounted executor confines commands (for example `dsh-bash-sandbox`), a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a command failure. The model may then retry the exact same command once in the same turn with `sandbox_permissions` (the narrowest wider mode that suffices) and a one-sentence `justification`; the approval prompt raised by that retry is how the user consents. Request wider access only after a real denial; a rejected escalation is final for that command. Repeating the current mode runs without approval, while a narrower target fails before execution. Without `sandbox_permissions`, `justification` may be omitted, empty, or whitespace-only; a non-empty reason without a mode is rejected. Repeating the effective mode also permits an omitted or blank reason. A different requested mode requires a non-empty reason; widening still requires approval.
 
 ### What can go wrong
 
@@ -81,14 +86,14 @@ This section explains the design decisions behind the tool and points at the cod
 - **Model-facing consumer of the shell seam.** The tool is the Consumer role of the bash capability: it registers the `bash` schema, renders results, and resolves per-call policy, while the executor seam owns process mechanics.
 - **Request from named args only.** The tool never exposes `stdin`, `env`, or `stdoutMaxBytes`; it builds each request from command/workdir/timeout/signal fields plus the registry-collected `dshEnv`, so model-supplied keys cannot replace managed values.
 - **Non-zero exits are reported, not errored.** Only infrastructure failures (spawn errors, aborts) surface as tool errors; the model interprets exit codes and markers.
-- **Background work belongs to the job runtime.** A background call registers a process handle with `ctx.jobs`; ids, ownership, completion notices, and disposal are the runtime's, and this tool only maps bash exit and sandbox facts into job output.
+- **Every command belongs to the job runtime when one is composed.** A call registers its process handle with `ctx.jobs` as it starts, whether the model asked for the background or the tool waits on it; ids, ownership, completion notices, and disposal are the runtime's, and this tool only maps bash exit and sandbox facts into job output. Without a registry the tool is foreground-only, and it swaps between the two registrations as the registry comes and goes.
 
 ### Source map
 
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, prompt section, arg validation, escalation, request assembly |
-| [`src/background.ts`](src/background.ts) | Own asynchronous shell preparation and map process settlement onto job outcomes |
+| [`src/background.ts`](src/background.ts) | Own asynchronous shell preparation, map process settlement onto job outcomes, and render a ring read as a process read |
 | [`src/render.ts`](src/render.ts) | Model-facing result text: streams, markers, truncation notices |
 | — | No runtime invariant companion is published; the environment registry validates ownership and collected values at each mutation/read; it publishes no independent snapshot that a companion could cross-check. |
 
@@ -146,7 +151,7 @@ Prefix-stable while the registration scope and prompt text are unchanged. Plugin
 
 #### What the model sees
 
-The model sees the generated [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash). `run_in_background` appears only when this producer enables it; `sandbox_permissions` and `justification` appear only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definition for that agent.
+The model sees the generated [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash). `run_in_background` appears only when this producer enables it and a job registry is composed; `sandbox_permissions` and `justification` appear only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definition for that agent.
 
 #### Token effect
 
@@ -160,7 +165,7 @@ Prefix-stable while visibility, background support, and executor sandbox capabil
 
 #### What the model sees
 
-The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. With no output it emits exactly `(no output)`. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]`, `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]`; the sandbox escalation and runner-failure lines are quoted in [`dsh-bash-sandbox`](../bash-sandbox/README.md).
+The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. With no output it emits exactly `(no output)`. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]`, `[timed out after <timeoutMs>ms]`, `[stopped: <reason>]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]`; the sandbox escalation and runner-failure lines are quoted in [`dsh-bash-sandbox`](../bash-sandbox/README.md).
 
 #### Token effect
 
@@ -207,7 +212,8 @@ These limits define when the tool is a poor fit or needs special care. They are
 
 - **Replay exit pills parse from result text** — output whose final line happens to be exactly `[exit code: N]` / `[killed by signal: …]` shows a wrong pill on session replay and loses that line from the card body, because the parse treats it as the marker it consumes; a display-only known residual.
 - **The `bash` tool opts out of `timeout-policy` budgets** — it keeps the executor-owned `BASH_TIMEOUT` path, per [the tool-call timeout-policy Agent Note](../../../.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).
-- **Background processes have no executor timeout** — callers must use `job_kill`, or rely on owner/service disposal, when work no longer matters.
+- **Background processes have no executor timeout** — callers must use `job_kill`, or rely on owner/service disposal, when work no longer matters; a foreground command registered as a job has none either, since its timeout bounds only the wait.
+- **The job list shows every foreground command while it runs** — a settled one leaves with its result, but the Web task list does not yet mark which running rows a tool call is still waiting on.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-bash` 让 agent（智能体）运行一次性 `bash` 命令，并接收 stdout、stderr 与退出标记。每次调用都使用全新 shell，因此 cwd、变量和函数不会保留；`run_in_background` 可启动长时间运行的工作，agent 能用 `job_output` 检查、用 `job_kill` 停止。命令会收到受管 `DSH_*` 环境；沙箱拒绝后，可携带更宽的 `sandbox_permissions`、一句 `justification` 并经用户批准重试一次。非零退出会作为结果报告，因此由 agent 决定如何响应；请使用 `dsh-bash-local` 或 `dsh-bash-sandbox` 等执行器，并加载 `dsh-shell-env`。
+`dsh-tool-bash` 运行 Bash 命令并返回 stdout、stderr 与退出标记。每次调用使用全新 shell；cwd、变量和函数不会保留。组合中有 job 注册表时，每条命令从启动起就是一个 job：`run_in_background` 立即返回 id，超过超时仍在运行的前台命令返回同一个 id，`job_output`/`job_kill` 收集并停止它。命令获得受管 `DSH_*` 环境；沙箱拒绝可携带更宽的 `sandbox_permissions`、一句 `justification` 与用户批准重试一次。非零退出是供 agent（智能体）解读的结果。请将 `dsh-bash-local` 或 `dsh-bash-sandbox` 等执行器与 `dsh-shell-env` 一起挂载。
 
 ## 目录
 
@@ -41,11 +41,12 @@ kind: "package-reference"
 - name: '@deepseek-ai/dsh-tool-jobs'
 ```
 
-唯一的配置字段用于开关后台支持。
+配置字段决定后台能力面。
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
-| `enableRunInBackground` | `true` | 暴露 `run_in_background`；为 `false` 时拒绝强制后台调用 |
+| `enableRunInBackground` | `true` | 组合中有 job 注册表时暴露 `run_in_background`；为 `false` 时拒绝强制后台调用 |
+| `promoteOnTimeout` | `true` | 到达超时的前台命令继续作为它的后台任务运行，而不是杀掉它 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-bash)是每个受支持字段及其 JSDoc 的穷尽式真源；生成的[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-bash)携带完整参数 schema。
 
@@ -56,11 +57,15 @@ kind: "package-reference"
 <a id="running-long-commands-in-the-background"></a>
 ### 后台运行长时间命令
 
-传入 `run_in_background: true` 会准入任务并立即返回 job id；限制准备可能仍在进行，且不设后台执行超时。进程可用前输出为空。任务取消会中止准备并停止随后返回的进程；启动失败使已准入任务以失败状态结算。agent 用 `job_output` 读取输出（除非 `wait: true`，否则非阻塞）、用 `job_list` 列出任务、用 `job_kill` 停止任务；完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时（`dsh-jobs-local`）及其控制工具（`dsh-tool-jobs`）。
+传入 `run_in_background: true` 会准入任务并立即返回 job id；限制准备可能仍在进行，且不设后台执行超时。进程可用前输出为空。任务取消会中止准备并停止随后返回的进程；启动失败使已准入任务以失败状态结算。agent 用 `job_output` 读取输出（除非 `wait: true`，否则非阻塞）、用 `job_list` 列出任务、用 `job_kill` 停止任务；完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时（`dsh-jobs-local`）及其控制工具（`dsh-tool-jobs`）。后台 job 把运行的非消费 `observed` 读取器交给 job 注册表作为拉式源；注册表按自己的节奏（`dsh-jobs-local` 的 `pumpPollMs`）把它们泵入 job 的输出环，Web 客户端由此流式看到实时输出，模型的 `job_output` 读取则经另一个游标消费同一份字节。读取器抛错只记录一次，该流就此停止，job 继续跑到自己的结算。输出环是尽力而为的实时预览：stdout 与 stderr 按轮询轮次复制，同一个轮询窗口内两条流的写入会先 stdout 后 stderr 出现，而不是按写入顺序。
+
+### 前台命令即任务
+
+组合中有 job 注册表时，前台命令一启动就登记到 `ctx.jobs`，调用等待该任务：命令在运行期间始终被列出、经 `job.list` 与 `job.follow` 流式观看，并可从 Web 任务列表停止。在超时内完成的命令返回普通前台结果，其任务记录随结果一起离开注册表，模型从不看到 id。超过超时仍在运行的命令继续作为它本来就是的那个任务运行，调用返回 `[still running after <timeoutMs>ms; moved to background job <id>]` 加任务交接指引，并以一次消费式读取带上目前为止的输出——`job_output` 恰好从此处接续。来自调用之外的杀停（人在界面上停止任务）会让前台结果在信号标记之前带上 `[stopped: <reason>]`，模型读到的是原因而不是命令失败；取消调用本身则杀掉任务。登记是尽力而为的：`promoteOnTimeout: false`、缺少 job 注册表，或注册表在启动时拒绝该任务（持有者的任务上限、没有控制器）都会改为在执行器的 deadline 杀下运行命令，工具描述也只在交接语义成立时才宣传它。
 
 ### 沙箱执行与升权
 
-当已挂载的执行器约束命令（例如 `dsh-bash-sandbox`）时，被阻止的文件操作会报告为 `[sandbox: file access denied under <mode> mode]`——这是策略拒绝，不是命令失败。模型随后可以在同一轮次中用 `sandbox_permissions`（满足需要的最窄更宽模式）与一句 `justification` 重试完全相同的命令一次；该重试引发的审批提示就是用户同意的方式。升权绝不能预先推测：没有真实拒绝依据的请求，或没有严格宽于当前模式的请求，都会直接失败且不执行任何操作；被拒绝的升权对该命令即为最终结果。
+当已挂载的执行器约束命令（例如 `dsh-bash-sandbox`）时，被阻止的文件操作会报告为 `[sandbox: file access denied under <mode> mode]`——这是策略拒绝，不是命令失败。模型随后可以在同一轮次中用 `sandbox_permissions`（满足需要的最窄更宽模式）与一句 `justification` 重试完全相同的命令一次；该重试引发的审批提示就是用户同意的方式。只有发生真实拒绝后才请求更宽权限；被拒绝的升权对该命令即为最终结果。重复当前模式无需审批即可执行，更窄目标则在执行前失败。未提供 `sandbox_permissions` 时，`justification` 可以省略、为空字符串或仅含空白；未指定模式却提供非空理由会被拒绝。重复当前生效模式时也可省略理由或提供空白理由。请求不同模式时必须提供非空理由；升权仍需审批。
 
 ### 可能出什么问题
 
@@ -81,14 +86,14 @@ kind: "package-reference"
 - **shell seam 的模型侧消费方。** 本工具是 bash 能力的消费方角色：它注册 `bash` schema、渲染结果并解析每次调用的策略，进程机制归执行器 seam 所有。
 - **请求只来自命名参数。** 工具从不暴露 `stdin`、`env` 或 `stdoutMaxBytes`；它只用命令／workdir／超时／信号字段加上注册表收集的 `dshEnv` 构建每个请求，因此模型提供的键无法替换受管值。
 - **非零退出只报告、不失败。** 只有基础设施故障（spawn 错误、中止）才会作为工具错误暴露；模型解读退出码与标记。
-- **后台工作归任务运行时。** 后台调用把进程句柄注册到 `ctx.jobs`；job id、所有权、完成通知与释放都是运行时的职责，本工具只把 bash 退出与沙箱事实映射为任务输出。
+- **组合了任务运行时，每条命令都归它。** 调用一启动就把进程句柄注册到 `ctx.jobs`，无论是模型要求后台还是工具在等待它；job id、所有权、完成通知与释放都是运行时的职责，本工具只把 bash 退出与沙箱事实映射为任务输出。没有注册表时工具只做前台，并随注册表的出现与消失在两种注册之间切换。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：工具注册、提示词区段、参数校验、升权、请求组装 |
-| [`src/background.ts`](src/background.ts) | 管理异步 shell 准备，并将进程结算映射为任务结果 |
+| [`src/background.ts`](src/background.ts) | 管理异步 shell 准备、将进程结算映射为任务结果，并把输出环读取渲染为进程读取 |
 | [`src/render.ts`](src/render.ts) | 模型侧结果文本：流、标记、截断通知 |
 | — | 不发布运行时不变式伴生入口；环境注册表在每次变更和读取时校验所有权及收集值，且不发布可供伴生入口交叉核对的独立快照；执行关系由能力 seam 负责。 |
 
@@ -146,7 +151,7 @@ Check the [exit code: N] marker on every bash result; investigate failures befor
 
 #### 模型看到什么
 
-模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-bash)。仅当本生产方启用 `run_in_background` 时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。按 agent 作用域限制工具可以移除该 agent 的定义。
+模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-bash)。仅当本生产方启用 `run_in_background` 且组合中有 job 注册表时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。按 agent 作用域限制工具可以移除该 agent 的定义。
 
 #### Token 影响
 
@@ -160,7 +165,7 @@ Check the [exit code: N] marker on every bash result; investigate failures befor
 
 #### 模型看到什么
 
-renderer 输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]` 和 stderr 尾部。没有输出时，它精确输出 `(no output)`。条件行精确为 `[output truncated; full output: <path-or-(unavailable)>]`、`[sandbox: file access denied under <mode> mode]`、`[timed out after <timeoutMs>ms]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`；沙箱升权与 runner 故障行原文列于 [`dsh-bash-sandbox`](../bash-sandbox/README.zh.md)。
+renderer 输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]` 和 stderr 尾部。没有输出时，它精确输出 `(no output)`。条件行精确为 `[output truncated; full output: <path-or-(unavailable)>]`、`[sandbox: file access denied under <mode> mode]`、`[timed out after <timeoutMs>ms]`、`[stopped: <reason>]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`；沙箱升权与 runner 故障行原文列于 [`dsh-bash-sandbox`](../bash-sandbox/README.zh.md)。
 
 #### Token 影响
 
@@ -207,7 +212,8 @@ renderer 输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]`
 
 - **回放的退出 pill 从结果文本解析**——输出最后一行恰好是 `[exit code: N]` / `[killed by signal: …]` 时，会话回放会显示错误的 pill 并从卡片正文丢失该行，因为解析把它当作要消费的标记；这是仅影响显示的已知残留。
 - **`bash` 工具不参与 `timeout-policy` 预算**——它保留执行器自有的 `BASH_TIMEOUT` 路径，见[工具调用超时策略 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md)。
-- **后台进程没有执行器超时**——工作不再需要时，调用方必须使用 `job_kill`，或依赖持有者／服务的释放。
+- **后台进程没有执行器超时**——工作不再需要时，调用方必须使用 `job_kill`，或依赖持有者／服务的释放；登记为任务的前台命令同样没有，它的超时只限定等待时长。
+- **任务列表会显示每条运行中的前台命令**——完成的命令随结果离开，但 Web 任务列表尚未标出哪些运行中的行仍有工具调用在等待。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -6,35 +6,98 @@ import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDen
 import { DSH_ENV_PREFIX, parseExitStatus } from "@deepseek-ai/dsh-shell";
 //#region lib/types/background.js
 /**
-* Generic-task adaptation for background bash process handles.
+* Generic-job adaptation for bash process handles: the terminal outcome the
+* registry records, the pull sources it pumps, and the ring read a foreground
+* call renders when it stops waiting.
 *
 * @module @deepseek-ai/dsh-tool-bash/background
 */
 /**
-* Map a settled background process onto the generic task-outcome vocabulary:
+* Sandbox facts worth the terminal detail: a runner that never ran the
+* command, or a denial (with the escalation hint this composition offers).
+* @param sandbox - settled sandbox facts, when this was a confined process.
+* @param escalationModes - escalation targets advertised by this composition.
+* @returns the markers to append, oldest first.
+*/
+function sandboxNotes(sandbox, escalationModes) {
+	if (sandbox?.runnerFailed) return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`];
+	if (sandbox?.denied) {
+		const notes = [sandboxDenialMarker(sandbox.mode)];
+		if (escalationModes.length > 0) notes.push(escalationHintMarker("command"));
+		return notes;
+	}
+	return [];
+}
+/**
+* Map a settled background process onto the generic job-outcome vocabulary:
 * `killed` stays `killed` (detail: the signal when one is known), everything
 * else is `completed` with the exit code as detail. A nonzero command exit is
-* reported, not failed, exactly like the foreground rendering.
+* reported, not failed, exactly like the foreground rendering. Sandbox facts
+* join the detail, since a job's terminal reason is the one line every
+* reader — the model's status line, the roster row — shows.
 * @param proc - the settled process handle.
+* @param escalationModes - escalation targets advertised by this composition.
 * @returns the outcome for the `ctx.jobs` registration.
 */
-function processOutcome(proc) {
-	if (proc.status === "killed") return {
+function processOutcome(proc, escalationModes = []) {
+	const base = proc.status === "killed" ? {
 		status: "killed",
 		detail: proc.signal !== null ? `signal: ${proc.signal}` : "killed before exit"
-	};
-	return {
+	} : {
 		status: "completed",
 		detail: `exit code: ${proc.exitCode ?? 0}`
 	};
+	const notes = sandboxNotes(proc.sandbox, escalationModes);
+	return notes.length === 0 ? base : {
+		...base,
+		detail: `${base.detail}; ${notes.join(" ")}`
+	};
+}
+/**
+* The process's non-consuming stream readers as registry pull sources. They
+* bind lazily because the process is spawned inside the starter, after the
+* registry admitted the job; a read before the spawn yields nothing, and the
+* pump keeps the model's consuming cursor untouched. A rejected spawn's
+* stderr reader carries the provider's `subprocess failed before reporting an
+* outcome: …` note.
+* @param proc - the started process's observed streams, once the starter has spawned it.
+* @returns one source per stream, stdout first.
+*/
+function processSources(proc) {
+	const source = (channel) => ({
+		channel,
+		read: (fromByte) => {
+			const live = proc();
+			return live === void 0 ? {
+				text: "",
+				nextOffset: fromByte,
+				lossy: false
+			} : live.observed[channel].readFrom(fromByte);
+		}
+	});
+	return [source("stdout"), source("stderr")];
+}
+/**
+* The ring chunks of one consuming registry read as the shell tools render a
+* process read: stdout chunks in order, then every stderr chunk in one
+* `[stderr]` section, so the output a foreground call hands over when it
+* stops waiting reads exactly like the `job_output` reads that follow it.
+* @param chunks - the chunks since the model cursor, in offset order.
+* @returns the delta text, possibly empty.
+*/
+function ringDelta(chunks) {
+	const out = chunks.filter((chunk) => chunk.channel !== "stderr").map((chunk) => chunk.text).join("");
+	const err = chunks.filter((chunk) => chunk.channel === "stderr").map((chunk) => chunk.text).join("");
+	const separator = out.length > 0 && !out.endsWith("\n") ? "\n" : "";
+	return out + (err.length > 0 ? `${separator}[stderr]\n${err}` : "");
 }
 /**
 * Adapt asynchronous shell preparation after job admission without exposing a partial process.
 * @param start - starts the process with job-owned cancellation.
-* @param renderOutput - consumes output from a published process.
+* @param outcome - projects the settled process into the job outcome.
 * @returns synchronous job hooks whose completion includes preparation and process settlement.
 */
-function processJob(start, renderOutput) {
+function processJob(start, outcome) {
 	const controller = new AbortController();
 	let process;
 	return {
@@ -51,15 +114,14 @@ function processJob(start, renderOutput) {
 				} finally {
 					await process.done;
 				}
-				return processOutcome(process);
+				return outcome(process);
 			} catch (error) {
 				return {
 					status: controller.signal.aborted && process === void 0 ? "killed" : "failed",
 					detail: error instanceof Error ? error.message : String(error)
 				};
 			}
-		})(),
-		readOutput: () => process === void 0 ? "" : renderOutput(process)
+		})()
 	};
 }
 //#endregion
@@ -83,7 +145,7 @@ function streamText(output) {
 * @param escalationModes - the escalation targets this composition advertises;
 *   non-empty adds the same-turn escalation hint after a denial marker
 *   (default `[]`: no hint).
-* @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
+* @returns the model-facing text: output body (or `(no output)`), then any timeout/stopped/signal/exit markers, each on its own line.
 */
 function renderResult(result, escalationModes = []) {
 	const out = streamText(result.stdout);
@@ -100,6 +162,7 @@ function renderResult(result, escalationModes = []) {
 		if (escalationModes.length > 0) markers.push(escalationHintMarker("command"));
 	}
 	if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`);
+	if (result.stopped !== void 0) markers.push(`[stopped: ${result.stopped}]`);
 	if (result.signal !== null) markers.push(`[killed by signal: ${result.signal}]`);
 	else if (result.exitCode !== 0) markers.push(`[exit code: ${result.exitCode}]`);
 	if (markers.length === 0) return body;
@@ -107,35 +170,50 @@ function renderResult(result, escalationModes = []) {
 	return body + markers.join("\n");
 }
 /**
-* Shape one background-process read into the `job_output` delta the model
-* sees: the incremental delta, plus the lossy-read notice (with full-stream
-* spill paths) when in-memory truncation dropped unread bytes. Empty-delta
-* rendering (`(no new output)`) is the generic job controller's job.
-* @param read - one incremental read from the process handle.
+* Shape a foreground call that stopped waiting into the text the model sees:
+* the output captured so far (one consuming registry read taken at that
+* point, so `job_output` continues exactly after it), then the still-running
+* marker and the job hand-off guidance.
+* @param promoted - the promoted result value: the job id, the wait that
+*   expired, and the output so far.
+* @returns the model-facing text for a promoted call.
+*/
+function renderPromoted(promoted) {
+	return `${promoted.output.length > 0 ? promoted.output.endsWith("\n") ? promoted.output : `${promoted.output}\n` : ""}[still running after ${promoted.timeoutMs}ms; moved to background job ${promoted.jobId}]\nThe command keeps running in the background. You will be notified when it finishes; read newer output with job_output, stop it with job_kill.`;
+}
+/**
+* Shape the one consuming registry read a foreground call embeds in its
+* result when it stops waiting: the output produced so far, plus the
+* dropped-output notice (naming the job's spill files) when the model cursor
+* fell behind the ring, and the sandbox notices. Later `job_output` reads
+* render the same ring through the job tools.
+* @param delta - the read's chunks as rendered text.
+* @param lossy - whether bytes before the delta were evicted unread.
+* @param spillPaths - the complete-stream files the job currently advertises.
 * @param sandbox - settled sandbox facts, when this was a confined process.
 * @param escalationModes - escalation targets advertised by this composition.
 * @returns the delta text with any loss or sandbox notice appended.
 */
-function renderProcessRead(read, sandbox, escalationModes = []) {
+function renderJobRead(delta, lossy, spillPaths, sandbox, escalationModes = []) {
 	const notices = [];
-	if (read.lossy) {
-		const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path) => path !== void 0);
-		notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(", ") : "(unavailable)"}]`);
-	}
+	if (lossy) notices.push(`[some output was dropped from memory; full output: ${spillPaths.length > 0 ? spillPaths.join(", ") : "(unavailable)"}]`);
 	if (sandbox?.runnerFailed) notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`);
 	else if (sandbox?.denied) {
 		notices.push(sandboxDenialMarker(sandbox.mode));
 		if (escalationModes.length > 0) notices.push(escalationHintMarker("command"));
 	}
-	if (notices.length === 0) return read.delta;
-	return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
+	if (notices.length === 0) return delta;
+	return `${delta}${delta.length > 0 && !delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
 }
 //#endregion
 //#region lib/types/index.js
 /**
-* Model-facing Consumer of the `ctx.shell` capability seam. Background calls
-* register process handles with `ctx.jobs`; their work uses job cancellation
-* rather than the tool-call signal after an id is returned.
+* Model-facing Consumer of the `ctx.shell` capability seam. While a job
+* registry is composed, every call registers its process with `ctx.jobs` as
+* it starts: `run_in_background` returns the id at once, and a foreground call
+* waits on its job until the command finishes or the wait times out, at which
+* point it returns the same id. Without a registry the tool is foreground-only
+* and the executor's deadline kills the command.
 *
 * TODO(permissions): deployment policy belongs in `tools/pre-execute` and
 * sandboxing executors; see docs/architecture.md § Where new behavior goes.
@@ -149,15 +227,20 @@ const inject = [
 	"shellEnv"
 ];
 /** Runtime configuration schema for the bash tool plugin. */
-const Config = z.object({ enableRunInBackground: z.boolean().default(true) });
-function validateBashArgs(args) {
+const Config = z.object({
+	enableRunInBackground: z.boolean().default(true),
+	promoteOnTimeout: z.boolean().default(true)
+});
+function validateBashArgs(args, effectiveMode) {
 	if (args.command.trim().length === 0) throw new Error("invalid command: expected a non-empty string");
 	if (args.description.trim().length === 0) throw new Error("invalid description: expected a non-empty string");
 	if (args.timeoutMs !== void 0 && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`);
-	validateEscalationArgs(args.sandbox_permissions, args.justification);
+	if (args.sandbox_permissions !== void 0 && args.sandbox_permissions === effectiveMode) return;
+	const justification = args.sandbox_permissions === void 0 && args.justification?.trim() === "" ? void 0 : args.justification;
+	validateEscalationArgs(args.sandbox_permissions, justification);
 }
-function bashDescription(backgroundEnabled, escalationModes) {
-	const background = backgroundEnabled ? "Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`." : "Background execution is not available; long-running commands must finish within the timeout.";
+function bashDescription(backgroundEnabled, escalationModes, promoteOnTimeout) {
+	const background = backgroundEnabled ? "Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`." + (promoteOnTimeout ? " A foreground command that reaches its timeout is not killed: it moves to the background the same way, returning its job id and the output so far." : "") : "Background execution is not available; long-running commands must finish within the timeout.";
 	const base = `Execute a bash command (\`bash -c\`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass \`workdir\` instead of using \`cd\`. Non-zero exits are reported as \`[exit code: N]\`. Current harness environment facts are exposed through managed \`$${DSH_ENV_PREFIX}*\` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as \`[sandbox: file access denied under <mode> mode]\` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. ` + background;
 	if (escalationModes.length === 0) return base;
 	return base + " Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.";
@@ -188,7 +271,9 @@ function presentBashResult(args, result) {
 	const block = result.content.length === 1 ? result.content[0] : void 0;
 	if (block === void 0 || block.type !== "text") return void 0;
 	const raw = block.text;
-	if (typeof args === "object" && args !== null && args.run_in_background === true || result.isError) return {
+	const isBackground = typeof args === "object" && args !== null && args.run_in_background === true;
+	const isPromoted = result.value?.kind === "promoted";
+	if (isBackground || isPromoted || result.isError) return {
 		card: "generic",
 		content: [{
 			type: "text",
@@ -238,6 +323,12 @@ function canonicalBashResult(result) {
 		} } : {}
 	};
 }
+/** The structured abort the foreground paths throw when the caller cancels the call. */
+function toolAborted() {
+	const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+	error.name = "AbortError";
+	return error;
+}
 /** Canonical background-handle properties shared by the bash output union. */
 const BACKGROUND_OUTPUT_PROPERTIES = {
 	kind: {
@@ -252,6 +343,7 @@ const BACKGROUND_OUTPUT_PROPERTIES = {
 };
 function apply(ctx, config = {}) {
 	const backgroundEnabled = config.enableRunInBackground ?? true;
+	const promoteOnTimeout = (config.promoteOnTimeout ?? true) && backgroundEnabled;
 	const defaultMode = ctx.shell.sandboxMode;
 	const escalationModes = defaultMode === void 0 ? [] : ESCALATION_TARGETS;
 	const sandboxPolicy = defaultMode === void 0 ? void 0 : ctx.get("sandboxPolicy");
@@ -290,189 +382,335 @@ function apply(ctx, config = {}) {
 		order: ctx.systemPrompt.getSectionOrder("TOOL_BASH"),
 		text: "Check the [exit code: N] marker on every bash result; investigate failures before moving on."
 	});
-	ctx.tools.register(defineTool({
-		name: "bash",
-		description: bashDescription(backgroundEnabled, escalationModes),
-		parameters: {
-			command: {
-				type: "string",
-				required: true,
-				description: "The bash command to execute."
-			},
-			description: {
-				type: "string",
-				required: true,
-				description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
-			},
-			timeoutMs: {
-				type: "number",
-				description: "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
-			},
-			workdir: {
-				type: "string",
-				description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
-			},
-			...backgroundEnabled ? { run_in_background: {
-				type: "boolean",
-				description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
-			} } : {},
-			...escalationModes.length > 0 ? {
-				sandbox_permissions: {
+	/**
+	* One registration of the `bash` tool. With a registry, every call
+	* registers its process as a job at its start; without one the tool is
+	* foreground-only and the executor's deadline kills the command.
+	*/
+	const bashTool = (jobs) => {
+		const background = jobs !== void 0;
+		const promote = background && promoteOnTimeout;
+		/** Register the command as a job; the process spawns inside the starter, after admission. */
+		const startJob = (registry, args, exec, spec) => {
+			let proc;
+			let stopped;
+			return {
+				id: registry.start({
+					kind: "bash",
+					label: args.command,
+					...exec.agent ? { owner: exec.agent.id } : {},
+					output: processSources(() => proc),
+					run: () => {
+						const hooks = processJob(async (signal) => {
+							proc = await ctx.shell.execute({
+								...spec,
+								signal
+							});
+							return proc;
+						}, (started) => processOutcome(started, escalationModes));
+						return {
+							done: hooks.done,
+							cancel: (reason) => {
+								stopped = reason;
+								hooks.cancel(reason);
+							}
+						};
+					}
+				}),
+				process: () => proc,
+				stopped: () => stopped
+			};
+		};
+		/** Wait on a registered foreground command until it settles or the timeout passes. */
+		const waitOnJob = async (registry, attached, exec, spec) => {
+			const owner = exec.agent?.id;
+			const timeoutMs = spec.timeoutMs;
+			/**
+			* Stop the job on this call's own account and stay on it until it
+			* settles, so the settlement is `awaited` and no completion notice
+			* follows a result this call already carries; the record then leaves
+			* with the call, as the model never saw the id.
+			*/
+			const stop = async (reason) => {
+				registry.kill(attached.id, owner, reason);
+				const settled = await registry.wait(attached.id, timeoutMs, owner);
+				if (settled.status !== "running" && settled.status !== "stopping") registry.remove(attached.id, owner);
+				return settled;
+			};
+			let view;
+			try {
+				view = await registry.wait(attached.id, timeoutMs, owner, exec.signal);
+			} catch {
+				await stop("tool call aborted");
+				throw toolAborted();
+			}
+			if ((view.status === "running" || view.status === "stopping") && attached.process() === void 0) {
+				await stop("timed out during preparation");
+				return {
+					kind: "foreground",
+					exitCode: null,
+					signal: null,
+					timedOut: true,
+					aborted: false,
+					timeoutMs,
+					stdout: {
+						text: "",
+						truncated: false
+					},
+					stderr: {
+						text: "",
+						truncated: false
+					},
+					...spec.sandboxPolicy !== void 0 ? { sandbox: {
+						mode: spec.sandboxPolicy.mode,
+						denied: false
+					} } : {}
+				};
+			}
+			if (view.status === "running" || view.status === "stopping") {
+				const read = registry.read(attached.id, owner);
+				return {
+					kind: "promoted",
+					jobId: attached.id,
+					timeoutMs,
+					output: renderJobRead(ringDelta(read.chunks), read.lossy, read.job.output.spillPaths ?? [], attached.process()?.sandbox, escalationModes)
+				};
+			}
+			registry.remove(attached.id, owner);
+			const process = attached.process();
+			if (process === void 0) throw new Error(view.detail);
+			const result = await process.result();
+			const stopped = attached.stopped();
+			return {
+				kind: "foreground",
+				...canonicalBashResult(result),
+				...stopped !== void 0 ? { stopped } : {}
+			};
+		};
+		return defineTool({
+			name: "bash",
+			description: bashDescription(background, escalationModes, promote),
+			parameters: {
+				command: {
 					type: "string",
-					enum: [...escalationModes],
-					description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
+					required: true,
+					description: "The bash command to execute."
 				},
-				justification: {
+				description: {
 					type: "string",
-					description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
-				}
-			} : {}
-		},
-		output: {
-			schema: { oneOf: [{
-				type: "object",
-				additionalProperties: false,
-				properties: BACKGROUND_OUTPUT_PROPERTIES
-			}, {
-				type: "object",
-				additionalProperties: false,
-				properties: {
-					kind: {
+					required: true,
+					description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
+				},
+				timeoutMs: {
+					type: "number",
+					description: promote ? "Timeout in milliseconds. The executor applies its configured default and cap; on expiry the command moves to the background as a job instead of being killed." : "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+				},
+				workdir: {
+					type: "string",
+					description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+				},
+				...background ? { run_in_background: {
+					type: "boolean",
+					description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
+				} } : {},
+				...escalationModes.length > 0 ? {
+					sandbox_permissions: {
 						type: "string",
-						required: true,
-						const: "foreground"
-					},
-					exitCode: {
-						required: true,
-						oneOf: [{ type: "integer" }, { type: "null" }]
-					},
-					signal: {
-						required: true,
-						oneOf: [{ type: "string" }, { type: "null" }]
-					},
-					timedOut: {
-						type: "boolean",
-						required: true
+						enum: [...escalationModes],
+						description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
 					},
-					aborted: {
-						type: "boolean",
-						required: true
-					},
-					timeoutMs: {
-						type: "number",
-						required: true
+					justification: {
+						type: "string",
+						description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
+					}
+				} : {}
+			},
+			output: {
+				schema: { oneOf: [
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: BACKGROUND_OUTPUT_PROPERTIES
 					},
-					stdout: {
+					{
 						type: "object",
 						additionalProperties: false,
-						required: true,
 						properties: {
-							text: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "promoted"
+							},
+							jobId: {
 								type: "string",
 								required: true
 							},
-							truncated: {
-								type: "boolean",
+							timeoutMs: {
+								type: "number",
 								required: true
 							},
-							spillPath: { type: "string" }
+							output: {
+								type: "string",
+								required: true
+							}
 						}
 					},
-					stderr: {
+					{
 						type: "object",
 						additionalProperties: false,
-						required: true,
 						properties: {
-							text: {
+							kind: {
 								type: "string",
-								required: true
+								required: true,
+								const: "foreground"
+							},
+							exitCode: {
+								required: true,
+								oneOf: [{ type: "integer" }, { type: "null" }]
+							},
+							signal: {
+								required: true,
+								oneOf: [{ type: "string" }, { type: "null" }]
 							},
-							truncated: {
+							timedOut: {
 								type: "boolean",
 								required: true
 							},
-							spillPath: { type: "string" }
-						}
-					},
-					sandbox: {
-						type: "object",
-						additionalProperties: false,
-						properties: {
-							mode: {
-								type: "string",
+							aborted: {
+								type: "boolean",
 								required: true
 							},
-							denied: {
-								type: "boolean",
+							stopped: { type: "string" },
+							timeoutMs: {
+								type: "number",
 								required: true
 							},
-							enforcement: { type: "string" },
-							runnerFailed: { type: "boolean" }
+							stdout: {
+								type: "object",
+								additionalProperties: false,
+								required: true,
+								properties: {
+									text: {
+										type: "string",
+										required: true
+									},
+									truncated: {
+										type: "boolean",
+										required: true
+									},
+									spillPath: { type: "string" }
+								}
+							},
+							stderr: {
+								type: "object",
+								additionalProperties: false,
+								required: true,
+								properties: {
+									text: {
+										type: "string",
+										required: true
+									},
+									truncated: {
+										type: "boolean",
+										required: true
+									},
+									spillPath: { type: "string" }
+								}
+							},
+							sandbox: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									mode: {
+										type: "string",
+										required: true
+									},
+									denied: {
+										type: "boolean",
+										required: true
+									},
+									enforcement: { type: "string" },
+									runnerFailed: { type: "boolean" }
+								}
+							}
 						}
 					}
+				] },
+				render: (_args, value) => [{
+					type: "text",
+					text: value.kind === "background" ? `started background job ${value.jobId}` : value.kind === "promoted" ? renderPromoted(value) : renderResult(value, escalationModes)
+				}]
+			},
+			async execute(args, exec) {
+				const standingPolicy = resolveSandboxPolicy(exec);
+				validateBashArgs(args, standingPolicy?.mode);
+				const approvedMode = args.sandbox_permissions !== void 0 && args.justification !== void 0 ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy) : void 0;
+				const policy = approvedMode === void 0 ? standingPolicy : {
+					...standingPolicy,
+					mode: approvedMode
+				};
+				const workdir = resolveWorkdir(args.workdir, exec, standingPolicy?.workspaceRoot);
+				const dshEnv = ctx.shellEnv.collect(exec);
+				const request = {
+					command: args.command,
+					...workdir !== void 0 ? { workdir } : {},
+					...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
+					dshEnv,
+					...policy !== void 0 ? { sandboxPolicy: policy } : {}
+				};
+				if (args.run_in_background === true) {
+					if (!backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
+					if (jobs === void 0) throw new Error("background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
+					if (exec.signal.aborted) throw toolAborted();
+					return {
+						kind: "background",
+						jobId: startJob(jobs, args, exec, ctx.shell.resolve({
+							...request,
+							onExpiry: "none"
+						})).id
+					};
 				}
-			}] },
-			render: (_args, value) => [{
-				type: "text",
-				text: value.kind === "background" ? `started background job ${value.jobId}` : renderResult(value, escalationModes)
-			}]
-		},
-		async execute(args, exec) {
-			validateBashArgs(args);
-			const standingPolicy = resolveSandboxPolicy(exec);
-			const approvedMode = args.sandbox_permissions !== void 0 && args.justification !== void 0 ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy) : void 0;
-			const policy = approvedMode === void 0 ? standingPolicy : {
-				...standingPolicy,
-				mode: approvedMode
-			};
-			const workdir = resolveWorkdir(args.workdir, exec, standingPolicy?.workspaceRoot);
-			const dshEnv = ctx.shellEnv.collect(exec);
-			const request = {
-				command: args.command,
-				...workdir !== void 0 ? { workdir } : {},
-				...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
-				dshEnv,
-				...policy !== void 0 ? { sandboxPolicy: policy } : {}
-			};
-			if (args.run_in_background === true) {
-				if (!backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
-				const jobs = ctx.get("jobs");
-				if (jobs === void 0) throw new Error("background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
-				if (exec.signal.aborted) {
-					const error = new HarnessError("tool call aborted", TOOL_ABORTED);
-					error.name = "AbortError";
-					throw error;
+				if (jobs !== void 0 && promote) {
+					const spec = ctx.shell.resolve({
+						...request,
+						onExpiry: "none"
+					});
+					let attached;
+					try {
+						attached = startJob(jobs, args, exec, spec);
+					} catch (error) {
+						ctx.logger.warn(`bash: job registration refused, running in the foreground with the timeout kill instead: ${String(error)}`);
+					}
+					if (attached !== void 0) return waitOnJob(jobs, attached, exec, spec);
 				}
+				const result = await (await ctx.shell.execute(ctx.shell.resolve({
+					...request,
+					signal: exec.signal
+				}))).result();
+				if (result.aborted) throw toolAborted();
 				return {
-					kind: "background",
-					jobId: jobs.start({
-						kind: "bash",
-						label: args.command,
-						...exec.agent ? { owner: exec.agent } : {},
-						run: () => processJob((signal) => ctx.shell.start(ctx.shell.resolve({
-							...request,
-							signal
-						})), (proc) => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes))
-					})
+					kind: "foreground",
+					...canonicalBashResult(result)
 				};
-			}
-			const result = await ctx.shell.run(ctx.shell.resolve({
-				...request,
-				signal: exec.signal
-			}));
-			if (result.aborted) {
-				const error = new HarnessError("tool call aborted", TOOL_ABORTED);
-				error.name = "AbortError";
-				throw error;
-			}
-			return {
-				kind: "foreground",
-				...canonicalBashResult(result)
-			};
-		},
-		presentCall: presentBashCall,
-		presentResult: presentBashResult
-	}));
+			},
+			presentCall: presentBashCall,
+			presentResult: presentBashResult
+		});
+	};
+	if (!backgroundEnabled) {
+		ctx.tools.register(bashTool(void 0));
+		return;
+	}
+	let foregroundOnly = ctx.get("jobs") === void 0 ? ctx.tools.register(bashTool(void 0)) : void 0;
+	ctx.inject(["jobs"], (jobCtx) => {
+		foregroundOnly?.();
+		foregroundOnly = void 0;
+		const unregister = ctx.tools.register(bashTool(jobCtx.jobs));
+		jobCtx.effect(() => () => {
+			unregister();
+			if (ctx.fiber.state === 2) foregroundOnly = ctx.tools.register(bashTool(void 0));
+		});
+	});
 }
 //#endregion
 export { Config, apply, inject, name };

package/lib/types/background.d.ts

@@ -1,27 +1,50 @@
 /**
- * Generic-task adaptation for background bash process handles.
+ * Generic-job adaptation for bash process handles: the terminal outcome the
+ * registry records, the pull sources it pumps, and the ring read a foreground
+ * call renders when it stops waiting.
  *
  * @module @deepseek-ai/dsh-tool-bash/background
  */
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
 import type { ShellProcess } from '@deepseek-ai/dsh-shell';
-import type { JobHooks } from '@deepseek-ai/dsh-jobs';
+import type { JobChunk, JobHooks, JobOutcome, JobOutputSource } from '@deepseek-ai/dsh-jobs';
 /**
- * Map a settled background process onto the generic task-outcome vocabulary:
+ * Map a settled background process onto the generic job-outcome vocabulary:
  * `killed` stays `killed` (detail: the signal when one is known), everything
  * else is `completed` with the exit code as detail. A nonzero command exit is
- * reported, not failed, exactly like the foreground rendering.
+ * reported, not failed, exactly like the foreground rendering. Sandbox facts
+ * join the detail, since a job's terminal reason is the one line every
+ * reader — the model's status line, the roster row — shows.
  * @param proc - the settled process handle.
+ * @param escalationModes - escalation targets advertised by this composition.
  * @returns the outcome for the `ctx.jobs` registration.
  */
-export declare function processOutcome(proc: ShellProcess): {
-    status: 'completed' | 'killed';
-    detail: string;
-};
+export declare function processOutcome(proc: ShellProcess, escalationModes?: readonly SandboxMode[]): JobOutcome;
+/**
+ * The process's non-consuming stream readers as registry pull sources. They
+ * bind lazily because the process is spawned inside the starter, after the
+ * registry admitted the job; a read before the spawn yields nothing, and the
+ * pump keeps the model's consuming cursor untouched. A rejected spawn's
+ * stderr reader carries the provider's `subprocess failed before reporting an
+ * outcome: …` note.
+ * @param proc - the started process's observed streams, once the starter has spawned it.
+ * @returns one source per stream, stdout first.
+ */
+export declare function processSources(proc: () => Pick<ShellProcess, 'observed'> | undefined): JobOutputSource[];
+/**
+ * The ring chunks of one consuming registry read as the shell tools render a
+ * process read: stdout chunks in order, then every stderr chunk in one
+ * `[stderr]` section, so the output a foreground call hands over when it
+ * stops waiting reads exactly like the `job_output` reads that follow it.
+ * @param chunks - the chunks since the model cursor, in offset order.
+ * @returns the delta text, possibly empty.
+ */
+export declare function ringDelta(chunks: readonly JobChunk[]): string;
 /**
  * Adapt asynchronous shell preparation after job admission without exposing a partial process.
  * @param start - starts the process with job-owned cancellation.
- * @param renderOutput - consumes output from a published process.
+ * @param outcome - projects the settled process into the job outcome.
  * @returns synchronous job hooks whose completion includes preparation and process settlement.
  */
-export declare function processJob(start: (signal: AbortSignal) => Promise<ShellProcess>, renderOutput: (process: ShellProcess) => string): JobHooks;
+export declare function processJob(start: (signal: AbortSignal) => Promise<ShellProcess>, outcome: (process: ShellProcess) => JobOutcome): JobHooks;
 //# sourceMappingURL=background.d.ts.map

package/lib/types/index.d.ts

@@ -1,7 +1,10 @@
 /**
- * Model-facing Consumer of the `ctx.shell` capability seam. Background calls
- * register process handles with `ctx.jobs`; their work uses job cancellation
- * rather than the tool-call signal after an id is returned.
+ * Model-facing Consumer of the `ctx.shell` capability seam. While a job
+ * registry is composed, every call registers its process with `ctx.jobs` as
+ * it starts: `run_in_background` returns the id at once, and a foreground call
+ * waits on its job until the command finishes or the wait times out, at which
+ * point it returns the same id. Without a registry the tool is foreground-only
+ * and the executor's deadline kills the command.
  *
  * TODO(permissions): deployment policy belongs in `tools/pre-execute` and
  * sandboxing executors; see docs/architecture.md § Where new behavior goes.
@@ -13,8 +16,21 @@ export declare const name = "tool-bash";
 export declare const inject: string[];
 /** Configuration for the bash tool. */
 export interface Config {
-    /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+    /**
+     * Expose `run_in_background` while a job registry is composed (default
+     * true); disabled calls are also rejected. Without a registry the tool is
+     * foreground-only regardless.
+     */
     enableRunInBackground?: boolean;
+    /**
+     * Keep a foreground command that reaches its timeout running as a
+     * background job instead of killing it (default true). Applies only while
+     * background execution is available: with `enableRunInBackground` false or
+     * no job registry, the executor's deadline kills the command. A foreground
+     * command the registry refuses at its start (admission or a missing
+     * controller) also runs under the deadline kill.
+     */
+    promoteOnTimeout?: boolean;
 }
 /** Runtime configuration schema for the bash tool plugin. */
 export declare const Config: z<Config>;

package/lib/types/render.d.ts

@@ -3,7 +3,7 @@
  *
  * @module @deepseek-ai/dsh-tool-bash/render
  */
-import type { ShellProcessRead, ShellRunResult, ShellSandboxInfo } from '@deepseek-ai/dsh-shell';
+import type { ShellRunResult, ShellSandboxInfo } from '@deepseek-ai/dsh-shell';
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
 /**
  * Shape one finished run into the text the model sees: stdout, then a marked
@@ -14,20 +14,39 @@ import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
  * @param escalationModes - the escalation targets this composition advertises;
  *   non-empty adds the same-turn escalation hint after a denial marker
  *   (default `[]`: no hint).
- * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
+ * @returns the model-facing text: output body (or `(no output)`), then any timeout/stopped/signal/exit markers, each on its own line.
  */
-export declare function renderResult(result: ShellRunResult, escalationModes?: readonly SandboxMode[]): string;
+export declare function renderResult(result: ShellRunResult & {
+    stopped?: string;
+}, escalationModes?: readonly SandboxMode[]): string;
 /**
- * Shape one background-process read into the `job_output` delta the model
- * sees: the incremental delta, plus the lossy-read notice (with full-stream
- * spill paths) when in-memory truncation dropped unread bytes. Empty-delta
- * rendering (`(no new output)`) is the generic job controller's job.
- * @param read - one incremental read from the process handle.
+ * Shape a foreground call that stopped waiting into the text the model sees:
+ * the output captured so far (one consuming registry read taken at that
+ * point, so `job_output` continues exactly after it), then the still-running
+ * marker and the job hand-off guidance.
+ * @param promoted - the promoted result value: the job id, the wait that
+ *   expired, and the output so far.
+ * @returns the model-facing text for a promoted call.
+ */
+export declare function renderPromoted(promoted: {
+    jobId: string;
+    timeoutMs: number;
+    output: string;
+}): string;
+/**
+ * Shape the one consuming registry read a foreground call embeds in its
+ * result when it stops waiting: the output produced so far, plus the
+ * dropped-output notice (naming the job's spill files) when the model cursor
+ * fell behind the ring, and the sandbox notices. Later `job_output` reads
+ * render the same ring through the job tools.
+ * @param delta - the read's chunks as rendered text.
+ * @param lossy - whether bytes before the delta were evicted unread.
+ * @param spillPaths - the complete-stream files the job currently advertises.
  * @param sandbox - settled sandbox facts, when this was a confined process.
  * @param escalationModes - escalation targets advertised by this composition.
  * @returns the delta text with any loss or sandbox notice appended.
  */
-export declare function renderProcessRead(read: ShellProcessRead, sandbox?: ShellSandboxInfo, escalationModes?: readonly SandboxMode[]): string;
+export declare function renderJobRead(delta: string, lossy: boolean, spillPaths: readonly string[], sandbox?: ShellSandboxInfo, escalationModes?: readonly SandboxMode[]): string;
 /**
  * The exit-status parse is the shared marker-contract half of the shell-tool
  * rendering story, owned by `@deepseek-ai/dsh-shell` so `dsh-tool-pwsh` reuses

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-bash",
   "description": "Model-facing bash tool with optional generic background-job and sandbox-escalation support",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,41 +27,41 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-shell-env": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-jobs": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.6-alpha.1"
+    "@deepseek-ai/dsh-shell": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-agent": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-shell-env": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-user-approval": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-tools": "^0.1.7-alpha.1"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "^3.18.3"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-shell-env": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-bash-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-jobs-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-tool-jobs": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-user-approval": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-jobs": "^0.1.6-alpha.1"
+    "@deepseek-ai/dsh-agent": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-shell": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-shell-env": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-bash-local": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-jobs-local": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-tool-jobs": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-user-approval": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-session-projection": "^0.1.7-alpha.1"
   }
 }