deepseek-harness/packages/bash/tool-bash

@deepseek-ai/dsh-tool-bash

The model-facing bash tools — bash, bash_output, bash_kill — registered over the ctx.bash executor seam (@deepseek-ai/dsh-bash). Pure schema + text shaping; every process concern lives behind the seam, so sandboxed or remote executor implementations swap in without changing what the model sees.

Requires a loaded executor implementation (e.g. @deepseek-ai/dsh-bash-local); the plugin stays pending until ctx.bash exists (inject: ['tools', 'bash', 'systemPrompt']).

The plugin also contributes the tool:bash prompt section (order 105) — the cross-call habit the per-tool descriptions cannot carry: check the [exit code: N] marker on every result and investigate failures before moving on. Under a sandboxing executor it additionally contributes the per-agent env:bash-sandbox section (order 110) stating each session's EFFECTIVE mode, and the pre-step narrator — see Per-session mode.

Tools

bash

Arg	Type	Notes
command	string (required)	Run via bash -c. No state persists between calls — use workdir, not cd.
description	string (required)	One-line, active-voice summary of the command (5-10 words), for UI/log display only — no effect on execution.
timeoutMs	number	Timeout override in milliseconds. The executor applies its configured default and cap.
workdir	string	Working directory for this call. Defaults to the calling agent's session cwd (session.header.cwd) so each session runs in its own workspace; a relative workdir is resolved against that session cwd.
run_in_background	boolean	Return a task id immediately; no timeout applies.
sandbox_permissions	string enum	ADVERTISED ONLY when the mounted executor sandboxes (ctx.bash.sandboxMode reports a confining default): the wider mode a denied command needs, from the closed target vocabulary workspace-write/danger-full-access (never cut down to the executor's default — the effective mode is per-session; strict widening is checked at execution against it, and a non-widening request fails without prompting anyone).
justification	string	Required together with sandbox_permissions (each without the other is a validation error): one sentence for the user explaining why this exact command needs the wider access.

command, workdir, and timeoutMs are resolved against the executor's config defaults via ctx.bash.resolve() before execution, so the executor seam (BashExecSpec) receives explicit workdir/timeoutMs values. The workdir default is applied in the tool layer (from the calling agent's session.header.cwd) BEFORE resolve() — the per-session cwd must come from exec.agent, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / process.cwd().

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-home (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.

import type { Context } from 'cordis'
import type {} from '@deepseek-ai/dsh-tool-bash'

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.

Result text: stdout, then a [stderr] section, then status markers — [sandbox: file access denied under <mode> mode] when a sandboxing executor classified the failure as a policy denial (reported first so [exit code: N] stays the last line; the static description tells the model a denial is policy, not a command bug, and forbids retrying around it), [timed out after Nms] whenever the executor's timer fired (reported independently of how the process ended, so a command that traps SIGTERM and exits 0 still shows it), [killed by signal: …] for a signal death, [exit code: N] for a non-zero exit (reported, not isError: the model decides how to react), and [output truncated; full output: <path>] when the tail was kept and a safe spill file is available. If the executor knows output was dropped but cannot safely advertise a complete spill file, the path is reported as (unavailable). Only infrastructure failures (spawn errors, aborts) surface as isError results.

bash_output

task_id → output produced since the previous bash_output call plus a status line (running / completed, exit code: N / killed). A settled task classified as a sandbox denial carries the same [sandbox: file access denied under <mode> mode] marker on every read that sees it (denials are only classifiable once the whole stderr has been collected). Reads that lost data to buffer bounds say so and point at the full-output spill file when one is safely available, otherwise (unavailable).

bash_kill

task_id → ask the executor to kill the background task. The concrete executor decides how to signal or stop the process; killing an already-finished task is a reported no-op, and unknown ids are errors.

Task ownership (cross-session isolation)

The owning agent's session token (session.header.id) is stamped onto the task at spawn — passed to the executor via resolve({ …, owner }) and stored ON THE TASK inside the executor (the dsh-bash ownerOf(id) seam), not in a plugin-local map. bash_output/bash_kill compare ctx.bash.ownerOf(id) to the caller's token (session.header.id) with !== undefined semantics and reject a task owned by a different session with task <id> belongs to another session (a task started with no agent — a non-loop caller — has no owner token and is open to anyone; a call with no exec.agent cannot access an owned task). Task ids are global and predictable, so under multi-session ACP this token check is the fence that stops one session's agent from reading or killing another session's background task. Because ownership lives on the task in the executor (disposed with the dsh-bash fiber), it survives an independent tool-bash HMR reload — closing the old plugin-local-map gap where a reload orphaned pre-reload tasks. (The onTaskDone listener is still effect-scoped to this plugin's apply, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)

UI presentation

These tools own how their calls render in a UI (an editor's tool-call card) via the dsh-tools presentCall/presentResult seam, each returning a card-tagged render intent — a UI never special-cases tool names. A FOREGROUND bash run declares a terminal card: presentCall returns { card: 'terminal', title, description?, cwd? } — the title is the exact command ("ls -la src"), the model-written description rides along (rendered ABOVE the card), and cwd comes from the model workdir when given (absolute as-is, relative for the UI bridge to resolve against the session cwd; else left for the bridge to fill from the session cwd) — and presentResult returns { card: 'terminal', title?, output?, exitCode?, signal? } carrying the raw output plus the parsed exitCode/signal, so a capable client (Zed) renders a terminal card with an exit-status pill. The result carries the raw output; the bridge DERIVES the ```console fenced fallback for a no-terminal-capability UI (the tool no longer encodes the fences itself), so the model-facing result text stays unfenced. A run_in_background call is NOT a terminal (it returns a task id immediately and never streams a terminal — poll with bash_output) and instead returns a generic card ({ card: 'generic', title, kind: 'execute', rawInput: command, content: [description] }); an isError result (spawn failure / abort) likewise returns a generic result view with no exit pill (there is no real process exit). bash_output/bash_kill return a generic card with a task-scoped title ("Read output from background task bash-3" / "Kill background task bash-3") and the task id as rawInput. These methods are pure/display-only (they also run on session/load replay), and a malformed/older logged arg shape falls back to a generic presentation rather than throwing. See packages/core/tools ("Tool-owned UI presentation") and packages/ui/acp ("Terminal card" / "Tool-call presentation").

Background completion notices

When a background task finishes, a short notice is injected into the owning agent's session (agent.inject(), source {kind: 'plugin', plugin: 'tool-bash'}). The owning agent is found by its session token: the listener reads ctx.bash.ownerOf(task.id) and scans ctx.get('agents')?.list() for an agent whose session.header.id matches (read via ctx.get — onTaskDone runs on the bash fiber, a foreign fiber, so the ctx.agents proxy would throw). If no live agent carries that token — e.g. the owning session disconnected and its agent was disposed while the task ran on — the notice is dropped cleanly. Injection is durable context for the next model request, not a wake-up — an idle agent stays idle until something sends a message. That's why the tool descriptions tell the model to poll with bash_output.

The tool builds its request from named args only

The BashExecRequest seam carries optional stdin and ordinary env for in-process consumers plus the harness-owned dshEnv channel above. This tool does not expose any of them as model parameters: it builds the request from named schema fields, so model-supplied env/stdin keys are ignored and cannot replace the managed values. A model already has equivalent command-local power through shell syntax (FOO=bar cmd, a heredoc); ambient-secret protection comes from dsh-bash-local's credential scrub, while dshEnv ownership prevents stale or spoofed Harness context. See the bash-stdin-env RFC.

Permissions and escalation

Commands run with the executor's full authority unless a sandboxing executor (dsh-bash-sandbox) confines them — the deny-only sandbox reports denials as result facts, rendered here as the denial marker; per-call allow/deny/ask policy is the tools/pre-execute waterfall (see docs/architecture.md).

On top of a denial sits the escalation gate (the sandbox RFC § Escalation): an escalating call (sandbox_permissions + justification) resolves ctx.approval BEFORE anything executes — allowed-once stamps the granted mode onto the bash request as the seam-level sandboxMode override (that one call runs, classifies, and reports under the wider mode; its neighbors keep the session's effective mode), while rejected/cancelled/unavailable and the no-service / no-agent paths each fail closed with their own error text and execute nothing. The seam is consumed opportunistically (ctx.get('approval'), the dsh-tools ask-routing pattern); the grant is consumed by the very call that asked, and nothing is stored. The static description teaches — and a denied result itself prompts, via the escalation-available marker appended exactly when the fields are advertised — the SAME-TURN flow: on a denial a wider mode would cure, retry the exact command once with sandbox_permissions (the narrowest mode that suffices) + justification immediately, without detouring through chat (the approval prompt IS the user's consent); never speculatively — an escalation is grounded in a real denial (up-front only when the session already denied the same access), a prompt-stated approvals-disabled policy turns the exception off entirely, and a rejected escalation is final for that command.

Per-session mode switching

Under a sandboxing executor this plugin makes the session's standing mode override (the sandbox RFC § Per-session mode switching; the bash/sandbox-mode fold owned by dsh-bash) real at EXECUTION: every call is stamped escalation grant > session override > undefined onto BashExecRequest.sandboxMode; without either, the executor's resolve() applies its configured default. Nothing is stamped under a non-sandboxing executor (nothing would honor it) or for an agent-less caller (no session to fold). The prompt deliberately does NOT state the mode and a switch is not narrated: a standing declaration teaches the model to refuse preemptively, while the denial marker already names the mode the command ran under exactly when the boundary is hit — behavior, not belief, carries the state.