Merge branch 'codex/simp-agent-entry-state' into codex/simp-unify-agent-session-id

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/event-producer-consumer.md
#	docs/rfc/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
#	docs/rfc/implemented/architecture/2026-06-20-branded-ids.md
#	docs/rfc/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
#	docs/rfc/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md
#	docs/rfc/proposed/simplification/2026-06-20-unify-agent-and-session-id.md
#	packages/bash/tool-bash/README.md
#	packages/bash/tool-bash/src/index.ts
#	packages/bash/tool-bash/tests/tools.spec.ts
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/tests/properties.spec.ts
#	packages/core/agent/README.md
#	packages/core/agent/src/index.ts
#	packages/guard/repeat-tool-guard/src/index.ts
#	packages/hooks/hooks-claude/tests/bridge.spec.ts
#	packages/subagent/subagent-acp/tests/mock-acp-server.ts
#	packages/ui/acp/tests/dispose.spec.ts
#	packages/ui/stdio-agent/src/index.ts
#	packages/ui/stdio-agent/src/stdio-chat.ts
#	packages/ui/stdio-agent/tests/stdio-chat.spec.ts
#	packages/util/brand/src/index.ts

packages/bash/bash-local/README.md

@@ -22,7 +22,7 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
 - **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `XXX(stateful-shell)` in `src/run.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
 - **Process-group kills with escalation** — children are spawned `detached` (own process group); kills send SIGTERM to the group, then SIGKILL after the `graceMs` grace (default 3s — OpenCode's escalation; pipelines and subshells die with the parent). ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
 - **Tail-keep truncation + spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported when available. If the final spill close reports a delayed writeback failure, the executor still returns the tail but withholds the path rather than advertising a possibly incomplete file.
-- **Model-friendly env + credential scrub** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`), then `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results. This scrub is the security control that keeps the harness's *ambient* credentials out of a spawned command. A spec's `env` is merged LAST (after the scrub), so a caller's explicit entry — a value it already holds — wins even on a credential-shaped name. The spec's `stdin`, when supplied, is written to the child and closed; with none supplied, fd 0 is `/dev/null` — the exact pre-seam default, so a command that probes stdin's file type is unaffected. Both `env`/`stdin` are set by in-process plugins (the hooks bridges); the model-facing tool doesn't expose them. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+- **Model-friendly environment** — ambient credential-shaped variables are removed before noninteractive terminal defaults and explicit caller entries are applied. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. Trusted plugins use `env` and `stdin`, but the model-facing tool does not expose them. See the [bash stdin/env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
 - **Background tasks** — `start()` returns immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), `readOutput()` is incremental with whole-stream byte offsets, and disposal kills everything. The spec's opaque `owner` token is stored on the tracked task and returned by `ownerOf(id)` — the executor never interprets it (the consumer's access policy does), and because it lives with the task here it survives a `tool-bash` HMR reload.
 
 ## Model Experience
@@ -37,6 +37,5 @@ Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdou
 - **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
 - **Spill files are never deleted** — full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them.
 - **Finished background tasks are never evicted** — they stay in the task map, retaining their in-memory output tails, until executor disposal.
-- **`OutputCollector.snapshot()` / `totalBytes` are test-shaped residuals** — the live poll path uses `readFrom()` and a marked cleanup can inline the final snapshot and remove the unused public getter.
 
 The raw process handling lives in `src/run.ts`; `src/index.ts` is the service wiring.

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

@@ -1,16 +1,8 @@
 /**
- * `LocalBashExecutor`: the local-subprocess implementation of the
- * `@deepseek-ai/dsh-bash` executor seam. Spawns `bash -c` per call in its
- * own process group (see `./run.ts` for the plumbing and the agent-tool
- * survey notes), tracks background tasks, and kills everything on dispose.
- *
- * TODO(permissions/sandbox): execution policy does NOT belong here — use
- * the `tools/pre-execute` deny/ask gate (see docs/architecture.md
- * § Extending The Harness) or implement a sandboxing `BashExecutor`.
- * Reference points:
- * Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies
- * seatbelt/landlock plus an execpolicy prefix-rule engine.
- *
+ * Local-subprocess implementation of the bash seam. Each call runs in its own
+ * process group, background tasks are tracked, and disposal kills and awaits
+ * them. Execution policy belongs in `tools/pre-execute` or a sandboxing
+ * executor, not this local process layer.
  * @module @deepseek-ai/dsh-bash-local
  */
 
@@ -90,10 +82,9 @@ export class LocalBashExecutor extends BashExecutor {
     assertPositiveFinite('maxOutputBytes', this.config.maxOutputBytes)
     assertPositiveFinite('graceMs', this.config.graceMs)
     ctx.effect(() => async () => {
-      // Kill every live process group and WAIT for the processes to close so
-      // nothing outlives the fiber (HMR safety) — a TERM-trapping child is
-      // held until the SIGKILL escalation lands. The base class already
-      // silenced listeners, so these kills complete without notices.
+      // Kill every live process group and WAIT for the processes to close so nothing outlives
+      // the fiber (HMR safety) — a TERM-trapping child is held until the SIGKILL escalation
+      // lands.
       const pending: Promise<void>[] = []
       for (const task of this.tasks.values()) {
         if (task.status === 'running') {
@@ -154,23 +145,18 @@ export class LocalBashExecutor extends BashExecutor {
       stdin: spec.stdin,
       env: spec.env,
     }, this.internals).done
-    // Classify the FIRST abort reason: a BASH_TIMEOUT TimeoutReason means our
-    // timeout cut the command short; any other abort — an upstream cancel, or a
-    // foreign (outer) deadline's timeout under nesting — is aborted. Scoping to
-    // our own code keeps a nested outer deadline from reading as our timeout.
-    // Mutually exclusive by construction — the fused signal reports one cause.
+    // Classify the FIRST abort reason: a BASH_TIMEOUT TimeoutReason means our timeout cut the
+    // command short; any other abort — an upstream cancel, or a foreign (outer) deadline's
+    // timeout under nesting — is aborted.
     const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined
     const aborted = d.signal.aborted && !timedOut
     return { ...outcome, timedOut, aborted, timeoutMs: spec.timeoutMs }
   }
 
   start(spec: BashExecSpec): BashTask {
-    // No timeout for background tasks (matches Claude Code, which detaches
-    // the timeout when backgrounding); callers stop tasks via kill() — or
-    // via spec.signal, which the seam contract honors for background runs
-    // too (runBash wires it to the group kill). No deadline is created here,
-    // so spec.timeoutMs is ignored by design — background tasks stay
-    // timeout-free (see the timeout-library RFC).
+    // No timeout for background tasks (matches Claude Code, which detaches the timeout when
+    // backgrounding); callers stop tasks via kill() — or via spec.signal, which the seam
+    // contract honors for background runs too (runBash wires it to the group kill).
     const running = runBash({
       command: spec.command,
       cwd: spec.workdir,

packages/bash/bash-local/src/run.ts

@@ -1,23 +1,7 @@
 /**
- * Process plumbing for the local bash executor: spawn, output collection
- * with tail-keep + spill-to-disk truncation, and process-group kill with
- * SIGTERM→SIGKILL escalation.
- *
- * Everything here is deliberately free of Cordis concepts so it can be unit
- * tested in isolation; `LocalBashExecutor` owns lifecycle and configuration.
- *
- * runBash owns NO timing: it kills the process group when its `spec.signal`
- * fires and does not distinguish a timeout from a cancel. The executor fuses
- * timeout + upstream cancellation into that one signal via
- * `@deepseek-ai/dsh-timeout`'s `deadline`, and classifies the outcome from the
- * signal afterward — the timing/classification half is shared, the kill is not.
- *
- * Design notes (surveyed against Claude Code, OpenCode, Codex, and pi — see
- * the package README): spawn-per-call with `detached: true` so the child
- * leads its own process group; kills target the group (`kill(-pid)`) so
- * pipelines and subshells die with the parent. SIGTERM first, SIGKILL after a
- * grace period (OpenCode's escalation; Codex/pi jump straight to SIGKILL).
- *
+ * Process plumbing for the local bash executor: detached process-group spawn,
+ * tail-keep output with spill files, and SIGTERM→SIGKILL escalation. This layer
+ * reacts to an abort signal; the executor owns deadlines and classifies causes.
  * @module dsh-bash-local/run
  */
 
@@ -50,18 +34,9 @@ export const ENV_OVERRIDES = {
 export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
 
 /**
- * `process.env` minus credential-shaped vars, plus the model-friendly
- * overrides, plus any caller-supplied `extra` entries.
+ * Build a child environment by scrubbing credential-shaped ambient variables,
+ * applying model-friendly overrides, then merging trusted caller entries last.
  *
- * Layering matters: the scrub drops `process.env` credentials, then
- * `ENV_OVERRIDES` forces the model-friendly terminal vars, then `extra` is
- * merged LAST so an explicit caller entry wins even when its name matches the
- * scrub pattern (the scrub is the control that stops the HARNESS's ambient
- * credentials leaking into a spawned command; a caller that explicitly sets a
- * var named a value it already holds, not that ambient secret). `extra` is set
- * by in-process plugins (the hooks bridges), not the model — `dsh-tool-bash`
- * builds its request from named fields only and does not forward model input
- * here (see its README, § "The tool builds its request from named args only").
  * @param extra - caller-supplied entries merged last; an explicit entry wins even against the scrub and the overrides.
  * @returns the environment to hand to `spawn` for the child process.
  */
@@ -262,10 +237,8 @@ export class OutputCollector {
       try {
         closeSync(this.spillFd)
       } catch {
-        // close can surface delayed writeback failures (for example EIO/ENOSPC)
-        // after writeSync appeared to succeed. Keep finalize total so runBash's
-        // close handler still resolves, but stop advertising a spill file that
-        // may be missing its tail.
+        // A delayed writeback failure makes the spill unreliable; keep finalize
+        // total but stop advertising that file.
         this.spillFile = undefined
       }
       this.spillFd = undefined
@@ -275,13 +248,9 @@ export class OutputCollector {
 }
 
 /**
- * Send `sig` to the process GROUP led by `pid` (requires the child to have
- * been spawned with `detached: true`). NEVER throws: kills race process exit
- * by design (ESRCH), and the other failure modes (EPERM from setuid
- * children, …) fire inside timer callbacks where a throw would crash the
- * host process — a kill that cannot be delivered is reported by the process
- * NOT dying, which callers already handle via escalation/timeouts. No-op for
- * non-positive pids (spawn never started a process).
+ * Send `sig` to a detached process group. Never throws: delivery races process
+ * exit and may run in a timer callback, so failures are contained and a
+ * non-positive pid is a no-op.
  * @param pid - the group leader's pid; non-positive means the spawn failed and the call is a no-op.
  * @param sig - the signal to deliver to the whole group.
  */
@@ -311,24 +280,13 @@ export interface RunningBash {
 }
 
 /**
- * Spawn `bash -c <command>` in its own process group and collect output.
- *
- * Outcome semantics: the returned promise REJECTS only for spawn-level
- * failures (bad cwd → ENOENT, missing binary, pre-aborted signal); every
- * runtime outcome — nonzero exit, timeout kill, abort kill, signal death —
- * RESOLVES with a {@link SpawnOutcome} describing what happened, so callers
- * shape one consistent report for the model.
- *
- * XXX(stateful-shell): per the agent-tool survey there are two proven
- * stateful designs worth revisiting — Claude Code persists ONLY cwd between
- * calls (captures `pwd -P` after each command), and Codex keeps whole PTY
- * exec sessions addressable via session ids + stdin writes. We deliberately
- * spawn a fresh non-login `bash -c` per call for determinism (no rc files,
- * no inherited shell state); revisit when real workflows demand it.
- * @param spec - the fully-resolved run (command, cwd, limits); no defaulting happens here.
- * @param internals - test-only knobs; omitted fields fall back to the private per-process spill dir.
- * @returns the live handle: pid, the two live collectors, the outcome promise, and `kill()`.
+ * Spawn one isolated `bash -c` process group and collect its output.
+ * Runtime exits resolve as {@link SpawnOutcome}; only spawn failures reject.
+ * @param spec - fully resolved command, cwd, limits, and cancellation.
+ * @param internals - test-only process and spill-directory overrides.
+ * @returns live process handle and outcome promise.
  */
+// XXX(stateful-shell): evaluate persistent cwd or PTY sessions when workflows require shell state.
 export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningBash {
   const spillDir = internals.spillDir ?? privateSpillDir()
 
@@ -336,16 +294,7 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB
     throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
   }
 
-  // stdin is a pipe ONLY when the caller supplied bytes; with none it is `ignore`
-  // (fd 0 → /dev/null) — the exact pre-seam default. This matters: a spawn pipe
-  // and /dev/null are NOT observationally identical (node's pipe is an AF_UNIX
-  // socket, so a command that probes stdin's type — `test -c /dev/stdin`, `stat
-  // /proc/self/fd/0` — sees a char device vs a socket), so the no-stdin path
-  // (every model-driven call) must keep /dev/null rather than regress to a socket.
-  // Two LITERAL `stdio` tuples (not one variable tuple): only a literal lets the
-  // typed `spawn` overload infer non-null stdout/stderr, which the
-  // `ChildProcessByStdio` annotation captures (stdin `Writable | null`; stdout/
-  // stderr the non-null `Readable` the collectors attach to without a cast).
+  // Keep absent stdin as /dev/null; literal tuples preserve non-null output types.
   const env = childEnv(spec.env)
   const child: ChildProcessByStdio<Writable | null, Readable, Readable> = spec.stdin !== undefined
     ? spawn('bash', ['-c', spec.command], { cwd: spec.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true })
@@ -358,8 +307,7 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB
 
   let graceTimer: NodeJS.Timeout | undefined
 
-  // pid is undefined when the spawn itself fails (bad cwd, missing binary);
-  // the 'error' handler rejects `done` and kills become no-ops via pid -1.
+  // Failed spawns use pid -1 so kill remains a no-op.
   const pid = child.pid ?? -1
 
   const kill = (): void => {
@@ -368,27 +316,11 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB
     graceTimer = setTimeout(() => { killGroup(pid, 'SIGKILL') }, spec.graceMs)
   }
 
-  // runBash owns no timer: the executor's `run()` fuses timeout+cancel into one
-  // deadline signal (`@deepseek-ai/dsh-timeout`) and passes it here; we only
-  // listen and run the SIGTERM→grace→SIGKILL kill. Whether the abort was a
-  // timeout or an upstream cancel is classified by the executor from that
-  // signal, not tracked here.
+  // The executor owns timeout classification; this layer only reacts to abort.
   const onAbort = (): void => { kill() }
   spec.signal?.addEventListener('abort', onAbort, { once: true })
 
-  // Write stdin and close it, but ONLY when the caller supplied bytes — with no
-  // stdin, fd 0 is `ignore` (/dev/null) and `child.stdin` is null. The error
-  // handler must exist whenever we write: an unhandled 'error' on the stream
-  // would throw and crash the host. We swallow the error rather than reject
-  // `done`, and that is correct for ANY stdin-write error, not just the common
-  // one — the stdin write is BEST-EFFORT, while the command's authoritative
-  // outcome is its exit code + captured output, which the `close` handler reports
-  // regardless of whether the write landed. The expected case is EPIPE (the child
-  // exited without reading, so closing our end of a still-full pipe fails); a rare
-  // non-EPIPE pipe fault means the command ran with incomplete stdin, and it
-  // surfaces that itself through its own exit/output (e.g. a hook that gets
-  // truncated JSON errors out) — rejecting here would instead discard that real
-  // output and turn it into an opaque infrastructure error, which is worse.
+  // Stdin writes are best-effort; process exit and captured output remain authoritative.
   if (child.stdin !== null) {
     child.stdin.on('error', () => { /* stdin write is best-effort; outcome rides on exit/output. */ })
     child.stdin.end(spec.stdin)
@@ -396,8 +328,7 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB
 
   const done = new Promise<SpawnOutcome>((resolve, reject) => {
     child.on('error', (error) => {
-      // Spawn-level failure (ENOENT cwd, EACCES, …): no close event with
-      // meaningful output follows; clean up and reject.
+      // No meaningful close outcome follows a spawn failure.
       cleanup()
       reject(error)
     })

packages/bash/bash-local/tests/executor.spec.ts

@@ -337,7 +337,7 @@ describe('LocalBashExecutor background tasks', () => {
   })
 })
 
-describe('review fixes: lifecycle hardening', () => {
+describe('executor cancellation, callback, and disposal contracts', () => {
   it('start honors a pre-aborted or later-aborted AbortSignal', async () => {
     const { bash } = await setup()
     const controller = new AbortController()

packages/bash/bash-local/tests/run.spec.ts

@@ -189,12 +189,8 @@ describe('stdin and extra env (set by in-process plugins)', () => {
   })
 
   it('gives fd 0 the exact pre-seam type: /dev/null when no stdin, a pipe when supplied', async () => {
-    // The no-stdin path must stay observationally identical to the pre-seam
-    // `ignore` default: a command that probes stdin's file type sees a char
-    // device (/dev/null). Regressing to an always-open pipe would make fd 0 a
-    // socket (node's spawn pipe is an AF_UNIX socket, not a FIFO), flipping
-    // `test -c /dev/stdin` for every model-driven call. When bytes ARE supplied,
-    // fd 0 is that pipe (a socket), as it must be to carry them.
+    // With no bytes, fd 0 remains the pre-seam `ignore` default (/dev/null, a character device).
+    // Supplied bytes use Node's spawn pipe, which is an AF_UNIX socket rather than a FIFO.
     const none = await runBash(spec('test -c /dev/stdin && echo char || echo other')).done
     expect(none.stdout.text).toBe('char\n')
     const piped = await runBash(spec('test -S /dev/stdin && echo socket || echo other', { stdin: 'x' })).done
@@ -219,9 +215,8 @@ describe('stdin and extra env (set by in-process plugins)', () => {
   })
 
   it('does not crash or reject when the child ignores a large stdin (EPIPE)', async () => {
-    // The child exits immediately without reading; closing our end of a stdin
-    // pipe still holding ~1MiB triggers EPIPE on the write. The handler must
-    // swallow it: `done` resolves normally with the child's real exit.
+    // The child exits without reading, so closing a stdin pipe holding ~1 MiB triggers EPIPE.
+    // The handler swallows that write error and `done` reports the child's real exit.
     const big = 'x'.repeat(1024 * 1024)
     const result = await runBash(spec('exit 7', { stdin: big })).done
     expect(result.exitCode).toBe(7)
@@ -360,7 +355,7 @@ describe('abort edge cases', () => {
   })
 })
 
-describe('review fixes: env scrubbing and spill hardening', () => {
+describe('environment and spill-file hardening', () => {
   it('scrubs credential-shaped env vars from child processes', async () => {
     process.env.DSH_TEST_API_KEY = 'super-secret'
     process.env.DSH_TEST_TOKEN = 'also-secret'

packages/bash/bash-sandbox/README.md

@@ -14,7 +14,7 @@ Semantics:
 
 - **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
 - **Runner failures are sandbox failures, never task failures.** A failed run matching the wrap's `runnerFailureSignatures` (the runner's own error prefix — also what the shell prints for a missing runner) means the sandbox itself broke and the command NEVER RAN; the check outranks denial classification because a runner's error text can contain denial words. The foreground path re-throws it as the structured fail-closed `SANDBOX_UNAVAILABLE` error, with the runner's first stderr line as the cause; a settled background task stamps `task.sandbox.runnerFailed` instead (no error channel remains after settle), which `bash_output` renders as its own marker.
-- **Config-time default, per-call policy.** The DEFAULT mode is fixed by this entry's config for the executor's lifetime; `resolve()` stamps it onto every spec, and an explicit request-level `sandboxMode` override — set by the tool layer only for a call whose wider mode a human granted through `ctx.approval` ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)) — makes THAT call run, classify, and report under its own mode while every neighbor keeps the default (background facts are stamped per task at settle). The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted. The model learns of the sandbox only through result facts — the static bash tool description explains the denial marker; there is no current-mode statement in the system prompt.
+- **Config default, per-call override.** `resolve()` stamps the configured sandbox mode onto each spec unless an approved request supplies a wider mode. That override affects only its call or background task. `ctx.bash.sandboxMode` reports the default so the tool advertises escalation only when supported; results report the effective mode. The model learns standing mode only from tool/result facts, not a system-prompt announcement.
 - **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
 - Process mechanics (spawn, process-group kills, output collection/spill, background tasks, credential scrub) are inherited verbatim from [`dsh-bash-local`](../bash-local/); the runner ladder, probes, and the per-platform Landlock launcher packages live with [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
 
@@ -48,7 +48,7 @@ The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landloc
 
 ### Bash tool error, indirectly
 
-**What the model sees**: If no runner can enforce a confined mode, the foreground call fails with code `SANDBOX_UNAVAILABLE` and the exact message `sandbox mode "<mode>" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), ensure sandbox-exec is usable (macOS) — Windows has no confinement backend yet — or switch the consumer to danger-full-access.` An execution-time runner failure appends ` Runner failure: <first stderr line>`.
+**What the model sees**: If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). For an execution-time runner failure, this backend supplies the first stderr line as its detail.
 
 **Token effect**: Conditional error text is visible for that call and retained in history until compaction.
 

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

@@ -1,43 +1,9 @@
 /**
- * `SandboxBashExecutor`: the sandbox-consuming implementation of the
- * `@deepseek-ai/dsh-bash` executor seam. Every spawned command is wrapped by
- * the `ctx.sandbox` provider (`@deepseek-ai/dsh-sandbox`) according to the
- * configured {@link SandboxMode}: the executor hands the provider the exact
- * `['bash', '-c', command]` argv it is about to spawn and spawns the wrapped
- * argv instead. WHICH platform runner confines it — and whether one is
- * usable at all (the provider fails CLOSED with a structured
- * `SANDBOX_UNAVAILABLE` error rather than passing the argv through) — is the
- * provider's concern (`@deepseek-ai/dsh-sandbox-local` first).
- *
- * Extends `LocalBashExecutor` so all process mechanics — spawn, process-group
- * kills, timeout escalation, output collection and spill files, background
- * tasks, the credential scrub — are the local implementation's, verbatim.
- * This package adds only the seam consumption and the result facts, which is
- * exactly the split the capability seam was designed for (a sandboxing
- * executor replaces `dsh-bash-local` without touching `dsh-tool-bash`, and
- * swapping the confinement backend never touches this package).
- *
- * A failed run whose stderr carries the selected backend's own denial
- * dialect (the signatures the provider stamps on every wrap) is classified
- * as a sandbox denial on `BashRunResult.sandbox`, and every confined result
- * also carries how completely the selected runner enforces the mode
- * (`sandbox.enforcement`, from the provider's wrap). A failure carrying the
- * backend's RUNNER-FAILURE signature instead means the sandbox itself broke
- * and the command never ran: the foreground path re-throws it as the
- * structured fail-closed `SANDBOX_UNAVAILABLE` error (late twin of the
- * provider's confine-time throw), a settled background task stamps
- * `sandbox.runnerFailed` — either way a broken sandbox can never read as a
- * failing command, and the command never slips through unconfined.
- *
- * Deny-only at the seam, escalation at the tool: a denial is a reported FACT
- * here, and the one-shot user-approved escalated retry of a denied action
- * (docs/rfc/implemented/feature/2026-07-06-sandbox.md) is driven by
- * `dsh-tool-bash` through `ctx.approval` — this executor's contribution is the
- * per-call `sandboxMode` override it honors in {@link resolve}: an escalated
- * call runs (and classifies, and reports) under ITS granted mode while every
- * neighboring call keeps its session's standing mode (or the configured
- * default when that session has no override).
- *
+ * Sandbox-consuming bash executor. It wraps the exact local bash argv through
+ * `ctx.sandbox`, inherits local process mechanics, and reports the selected
+ * mode, enforcement, and denial facts. Runner failure means the command never
+ * ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while settled background
+ * tasks carry `runnerFailed`. The tool owns approval and passes per-call modes.
  * @module @deepseek-ai/dsh-bash-sandbox
  */
 
@@ -79,24 +45,11 @@ export function shellQuote(text: string): string {
 }
 
 /**
- * Conservative sandbox-denial classifier: a run counts as denied only when it
- * FAILED (nonzero exit — a signal kill is not a denial) and its stderr
- * carries one of the SELECTED BACKEND's own denial signatures — the dialect
- * the provider stamps on every wrap (`ConfinedArgv.denialSignatures`:
- * `Read-only file system` under bwrap's EROFS mounts, `Permission denied`
- * under Landlock's EACCES, `Operation not permitted` under Seatbelt's
- * EPERM). Matching the backend's dialect rather than a cross-backend union
- * keeps the classifier from claiming denials the active backend never
- * produces (bare EPERM text under a Linux runner names non-file boundaries —
- * mount, kill, ptrace — that fail the same way unsandboxed). Text inference
- * is the fallback signal until a runner provides a structured one (which
- * wins once it exists); it errs toward NOT claiming a denial, and its known
- * residual imprecision is non-sandbox text in the active dialect (an ssh
- * auth failure reads as a denial under Landlock, a refused `kill` under
- * Seatbelt).
+ * Conservatively classify a nonzero, non-signal run using only the selected
+ * backend's denial signatures. Text inference may miss a denial or match
+ * unrelated stderr in that dialect; it never uses another backend's terms.
  * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's denial dialect, case-insensitive
- *   stderr substrings.
+ * @param signatures - the active wrap's denial dialect, case-insensitive stderr substrings.
  * @returns whether the run's failure reads as a sandbox denial.
  */
 export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
@@ -104,17 +57,9 @@ export function classifyDenial(result: BashRunResult, signatures: readonly strin
 }
 
 /**
- * Runner-failure classifier: a failed run whose stderr carries the SELECTED
- * BACKEND's own runner-failure signature (`ConfinedArgv.
- * runnerFailureSignatures`: the runner's error prefix, which also matches
- * the shell's runner-not-found message) means the SANDBOX itself failed and
- * the command never ran. Checked BEFORE {@link classifyDenial} — a runner's
- * error text can contain denial words (an unopenable grant root reports
- * `Permission denied`) — and surfaced as the fail-closed
- * `SANDBOX_UNAVAILABLE` error on the foreground path, `sandbox.runnerFailed`
- * on a settled background task. Same conservative-text-inference stance and
- * residual imprecision as the denial classifier (a failing task that itself
- * prints the runner's prefix reads as a runner failure).
+ * Classify a nonzero run using the selected backend's runner-failure
+ * signatures. Callers check this before denial because runner diagnostics may
+ * contain denial words; the command did not run.
  * @param result - the settled foreground run to classify.
  * @param signatures - the active wrap's runner-failure signatures,
  *   case-insensitive stderr substrings.
@@ -137,15 +82,11 @@ function matchesSignature(exitCode: number | null, stderr: string, signatures: r
 }
 
 /**
- * Sandbox-consuming bash executor. Registers as `ctx.bash` (loading it
- * INSTEAD OF `dsh-bash-local`, together with a `ctx.sandbox` provider, is
- * the whole swap — the tool layer is untouched). Its configured mode is the
- * fallback exposed by {@link sandboxMode}; `dsh-tool-bash` folds a session's
- * durable `bash/sandbox-mode` override and stamps the effective mode onto each
- * request, while an approved escalation may stamp a strictly wider mode for
- * one call. The prompt deliberately does not state the mode; each run's
- * `result.sandbox` reports what actually executed plus enforcement
- * completeness, and the tool layer renders denial or runner-failure facts.
+ * Registers as `ctx.bash` in place of the local executor and requires a
+ * `ctx.sandbox` provider; the tool layer is unchanged. The configured mode is
+ * the fallback, while a session override or approved one-shot escalation may
+ * select each call's mode. The prompt does not state the standing mode;
+ * `result.sandbox` reports the mode and enforcement actually used.
  */
 export class SandboxBashExecutor extends LocalBashExecutor {
   static inject = ['sandbox']
@@ -163,15 +104,9 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   private readonly mode: SandboxMode
   private readonly workspaceRoot: string
   /**
-   * Per-task facts, keyed by task id from `start()` until the settle stamp
-   * consumes them: the mode the task runs under (per-call — an escalated task
-   * differs from its neighbors) plus its wrap facts. The seam returns facts
-   * PER WRAP — a provider may legally vary enforcement or dialect between
-   * calls — so overlapping background tasks must each classify against their
-   * OWN wrap; a single latest-wrap field would let a later `start()` clobber
-   * an earlier task's facts before it settles. A `danger-full-access` task
-   * has NO entry (nothing confined it), which is what the settle stamp keys
-   * off.
+   * Per-task mode and wrap facts retained until settlement. Overlapping tasks
+   * may use different modes or provider facts, so one latest-wrap field would
+   * misclassify earlier completions.
    */
   private readonly taskFacts = new Map<BashTaskId, {
     mode: ConfinedSandboxMode
@@ -215,11 +150,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     }
     const confined = this.confine(spec.command, mode)
     const result = await super.run({ ...spec, command: confined.command })
-    // Runner failure outranks denial: the sandbox itself failed and the
-    // command NEVER RAN — surface the same structured fail-closed error a
-    // confine-time discovery throws (late detection, same outcome), with
-    // the runner's own first stderr line as the cause. Returning it as a
-    // task result would let a broken sandbox read as a failing command.
+    // Runner failure outranks denial because the command did not run. Throw the
+    // same fail-closed error as confine-time discovery with the first stderr line.
     if (classifyRunnerFailure(result, confined.runnerFailureSignatures)) {
       throw new SandboxUnavailableError(mode, result.stderr.text.trim().split('\n')[0])
     }
@@ -230,11 +162,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     // Same stamped-by-resolve invariant as run().
     const mode = spec.sandboxMode as SandboxMode
     if (mode === 'danger-full-access') return super.start(spec)
-    // Sandbox facts are stamped at settle time by {@link notifyTaskDone}
-    // (denial classification runs against the settled task's collected
-    // stderr). The map entry lands synchronously after spawn, strictly
-    // before the earliest possible settle (a process exit reaches us no
-    // sooner than the next tick).
+    // Classification needs settled stderr. Store facts synchronously after
+    // spawn, before the earliest process completion can be observed.
     const confined = this.confine(spec.command, mode)
     const task = super.start({ ...spec, command: confined.command })
     const { enforcement, denialSignatures, runnerFailureSignatures } = confined
@@ -243,27 +172,16 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   }
 
   /**
-   * Stamp the sandbox facts BEFORE completion listeners run: the base
-   * executor notifies from inside the task's settle path, so overriding the
-   * notification point is what makes `task.sandbox` visible to `onTaskDone`
-   * consumers and `done` awaiters alike. Each task classifies against the
-   * facts of ITS OWN wrap and reports ITS OWN mode (consumed from the
-   * per-task map here — settle is the entry's end of life): with per-call
-   * escalation, tasks under different modes settle side by side, so keying
-   * anything off the configured default would misreport them. A
-   * `danger-full-access` task has no map entry and carries no facts (nothing
-   * confined it); a signal-killed task (null exit code) is never a denial,
-   * mirroring the foreground classifier.
+   * Stamp per-task sandbox facts before completion listeners and `done` settle.
+   * Full-access tasks have no facts; signal deaths are not denials.
    */
   protected override notifyTaskDone(task: BashTask): void {
     const facts = this.taskFacts.get(task.id)
     if (facts !== undefined) {
       this.taskFacts.delete(task.id)
       const stderr = this.collectedStderr(task.id)
-      // Runner failure outranks denial (the command never ran; the runner's
-      // own error text can contain denial words). A settled task has no
-      // error channel left, so the fact IS the surface here — the foreground
-      // path throws instead.
+      // Runner failure outranks denial. Background settlement has no throw
+      // channel, so this fact is its counterpart to the foreground exception.
       const runnerFailed = matchesSignature(task.exitCode, stderr, facts.runnerFailureSignatures)
       task.sandbox = {
         mode: facts.mode,

packages/bash/bash-sandbox/tests/bwrap.e2e.ts

@@ -9,20 +9,13 @@ import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 
 /**
- * KEYLESS consumer-integration proof under bwrap: the REAL
- * `LocalSandboxProvider` (nothing forced — bwrap is the ladder's first rung,
- * so a passing probe selects it) underneath the REAL `SandboxBashExecutor`,
- * driven through the executor's public run/start paths. Verifies the WORLD
- * (files exist or don't) plus the stamped result facts — in particular that
- * bwrap's EROFS denial text classifies as `denied: true` through the
- * wrap-carried dialect; the backend-only confinement proofs live with
- * `@deepseek-ai/dsh-sandbox-local`.
+ * Keyless integration of the real provider and executor through public run/start paths. With
+ * no rung forced, a passing bwrap probe selects the ladder's first rung. The tests check world
+ * effects and stamped facts, including EROFS classification through the wrap-carried dialect;
+ * backend-only confinement is covered by `@deepseek-ai/dsh-sandbox-local`.
  *
- * Self-skips wherever the functional probe fails — no `bwrap` on PATH, or a
- * host that denies unprivileged user namespaces.
- *
- * HOME-based dirs on purpose: bwrap's `/tmp` is an ephemeral mount, so only
- * paths outside it prove the workspace-root boundary.
+ * Skips when bwrap or unprivileged user namespaces are unavailable. HOME-based paths are
+ * intentional because bwrap replaces `/tmp`, which cannot prove the workspace-root boundary.
  */
 
 const probe = spawnSync('bwrap', [...bwrapProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' })

packages/bash/bash-sandbox/tests/sandbox.spec.ts

@@ -1,11 +1,8 @@
 /**
- * SandboxBashExecutor tests: the CONSUMER side of the sandbox seam. A fake
- * `ctx.sandbox` provider (injected as a real cordis service) makes wrapping,
- * policy hand-off, fail-closed propagation, classification, and fact
- * stamping all deterministic without any real runner; the real-provider
- * integration proof lives in `tests/landlock.e2e.ts`. Denials are produced
- * with plain unix permissions (a 0555 directory), which exercises the same
- * stderr signature the classifier keys on.
+ * Consumer-side `SandboxBashExecutor` tests. A fake Cordis sandbox service makes wrapping,
+ * policy hand-off, fail-closed propagation, classification, and fact stamping deterministic;
+ * real-provider integration lives in `tests/landlock.e2e.ts`. A mode-0555 directory supplies
+ * the Unix denial signature used by the classifier without requiring a real sandbox runner.
  */
 
 import { chmodSync, mkdirSync, mkdtempSync } from 'node:fs'
@@ -286,10 +283,9 @@ describe('background sandbox facts', () => {
   })
 
   it('overlapping background tasks keep their OWN wrap facts (per-task, not latest-wrap)', async () => {
-    // The seam returns facts PER WRAP — a legal provider may vary them
-    // between calls. The slow task settles AFTER the quick one started, so a
-    // latest-wrap field would classify its denial against the quick task's
-    // dialect (missing it) and stamp the wrong enforcement.
+    // Facts belong to each wrap and may vary between calls. The slow task settles after the
+    // quick task starts; a shared latest-wrap field would classify and stamp it with the wrong
+    // task's dialect and enforcement.
     const wraps: Array<Pick<ConfinedArgv, 'enforcement' | 'denialSignatures'>> = [
       { enforcement: 'partial', denialSignatures: ['permission denied'] },
       { enforcement: 'full', denialSignatures: ['read-only file system'] },

packages/bash/bash-sandbox/tests/seatbelt.e2e.ts

@@ -9,16 +9,11 @@ import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sand
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 
 /**
- * KEYLESS consumer-integration proof on macOS: the REAL `LocalSandboxProvider`
- * (Linux rungs forced off, so `sandbox-exec`/Seatbelt confines) underneath
- * the REAL `SandboxBashExecutor`, driven through the executor's public
- * run/start paths. Verifies the WORLD (files exist or don't) plus the
- * stamped result facts — in particular that Seatbelt's EPERM denial text
- * classifies as `denied: true` through the wrap-carried dialect; the
- * backend-only confinement proofs live with `@deepseek-ai/dsh-sandbox-local`.
- *
- * Self-skips wherever the functional probe fails — every non-macOS host, or
- * a macOS whose `sandbox-exec` refuses the profile.
+ * Keyless macOS integration of the real provider and executor through public run/start paths.
+ * Linux rungs are forced off so Seatbelt is selected. The tests check world effects and stamped
+ * facts, including EPERM classification through the wrap-carried dialect; backend-only
+ * confinement is covered by `@deepseek-ai/dsh-sandbox-local`. Skips off macOS or when
+ * `sandbox-exec` rejects the profile.
  */
 
 const probe = spawnSync('sandbox-exec', [...seatbeltProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' })

packages/bash/bash/README.md

@@ -32,7 +32,7 @@ Implementations subclass `BashExecutor`, implement the abstract methods, and cal
 
 `BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?, owner?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?, owner, sandboxMode) before execution; `owner` and `sandboxMode` are optional on the request and **required-but-nullable** on the resolved spec, so a forgotten one is a visible `undefined` rather than a silently-absent property. `sandboxMode` is the explicit per-call sandbox-policy input: an escalation grant a human just issued ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md), which outranks) or the session's standing override ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)); a sandboxing executor's `resolve()` stamps its configured default when the request carries none, and a non-sandboxing executor carries the field verbatim and confines nothing.
 
-The seam also owns the per-session mode override vocabulary (the sandbox RFC § Per-session mode switching): the log-only `'bash/sandbox-mode'` session event, the pure fold `effectiveSandboxMode(events)` (last event wins; `undefined` means "apply the executor default"), and THE write path `setSandboxMode(session, mode)` — the session log is the store, so an override survives restart by replay and two sessions can never see each other's mode. Writers must respect turn-enclosure: the ACP bridge anchors an idle switch at the next turn rather than appending between turns. The task id (`BashTaskId`) and the `owner` token (`OwnerToken`) are [branded](../../util/brand) — `OwnerToken` is a DISTINCT brand from `SessionId` (the seam never imports `dsh-session`; the `dsh-tool-bash` consumer is the single boundary that casts its `SessionId` into one). `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()`/`readOutput()` use `BashTask`/`BashTaskRead` for the background side. A sandboxing executor additionally stamps `sandbox` result facts on results and settled tasks (`BashSandboxInfo`: the mode it executed under, the conservative `denied` classification, and — for confined modes — the backend's `enforcement` completeness); the mode/enforcement vocabulary is owned by the [`dsh-sandbox`](../../sandbox/sandbox/) seam, and the facts are documented in [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md). See `src/types.ts` for the full contracts.
+The seam owns per-session sandbox overrides through the log-only `bash/sandbox-mode` event, `effectiveSandboxMode`, and `setSandboxMode`; writers preserve turn enclosure, and replay restores the last override. `BashTaskId` and `OwnerToken` are distinct brands. Foreground `run` returns exit, timeout, cancellation, output, and optional sandbox facts; background `start` and `readOutput` use task records. A sandboxing executor reports the executed mode, conservative denial classification, and enforcement completeness. See [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md) for full shapes.
 
 `stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so they would be redundant tool params. This is not a security boundary: the implementation's credential scrub (not these fields) is what keeps the harness's ambient secrets out of a spawned command. They are plain optionals on the resolved spec (unlike `owner`'s required-but-nullable): a missing one means "none", the safe default. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
 
@@ -43,5 +43,4 @@ Indirectly, through `dsh-tool-bash`, which turns executor output and sandbox fac
 ## Known Limitations and Deferred Work
 
 - **No interactive-input vocabulary** — `stdin` is written once at spawn and closed; the seam has no channel to feed a running task and no PTY session concept.
-- **Two overlapping surfaces flagged for pruning** — `BashTask.done` duplicates `onTaskDone` (shipped consumers use only the latter), and `get()`/`list()` have test-harness consumers only; both are marked in [the long-running-runtime RFC](../../../docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md).
 - **Foreground timeouts are always executor-owned** — a caller-owned-deadline mode on the seam is explicitly deferred by [the tool-call timeout-policy RFC](../../../docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).

packages/bash/bash/src/index.ts

@@ -1,16 +1,6 @@
 /**
- * The bash executor seam (`ctx.bash`): an abstract service defining WHAT a
- * bash backend does — run commands, manage background tasks — without saying
- * HOW. Implementations subclass {@link BashExecutor} and register themselves
- * as the `bash` service; `@deepseek-ai/dsh-bash-local` (local subprocesses)
- * is the first. Future implementations swap in sandboxes, containers, or
- * remote exec servers without touching the tool schemas that consume them
- * (`@deepseek-ai/dsh-tool-bash`).
- *
- * The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the
- * surveyed agents: pi hides execution behind a `BashOperations` interface
- * (local shell / SSH / VM backends), Codex behind an exec-server protocol.
- *
+ * The bash executor seam (`ctx.bash`): an abstract service defining what a bash backend does —
+ * run commands, manage background tasks — without saying how.
  * @module @deepseek-ai/dsh-bash
  */
 
@@ -39,25 +29,11 @@ declare module 'cordis' {
 }
 
 /**
- * Abstract bash execution service. Subclass, implement the abstract methods,
- * and load the subclass as a plugin — it registers as `ctx.bash` (one
- * implementation per context; loading a second throws, which is cordis'
- * standard duplicate-service behavior).
- *
- * Semantics every implementation must honor:
- * - {@link run} REJECTS only for infrastructure failures (unusable workdir,
- *   missing shell, pre-aborted signal). Nonzero exits, timeout kills, and
- *   abort kills RESOLVE with a descriptive {@link BashRunResult} — reporting
- *   a failed command is the tool layer's job, not an exception.
- * - {@link start} returns immediately; no timeout applies to background
- *   tasks (callers stop them via {@link kill} or the spec's AbortSignal).
- *   Completion must fire the {@link onTaskDone} listeners exactly once per
- *   task, and must NOT fire after the service is disposed.
- * - {@link readOutput} is incremental: consecutive reads never re-deliver
- *   output. Implementations bound their buffers; reads that lost data flag
- *   `lossy` and point at full-stream spill files when available.
- * - Disposal kills every running task and awaits their exit (no orphan
- *   processes survive `fiber.dispose()`).
+ * Registers one `ctx.bash` implementation. Runtime command failures resolve as
+ * {@link BashRunResult}; only infrastructure failures reject. Background starts
+ * return immediately without a timeout, report completion exactly once while
+ * live, and remain cancellable by signal or {@link kill}. Output reads are
+ * incremental and flag lost buffered data; disposal kills and awaits all tasks.
  */
 export abstract class BashExecutor extends Service {
   private listeners = new Set<BashTaskListener>()
@@ -74,14 +50,11 @@ export abstract class BashExecutor extends Service {
   }
 
   /**
-   * The sandbox mode this executor confines commands under BY DEFAULT, or
-   * `undefined` when it does not sandbox at all — the capability fact the
-   * tool and ACP layers read to advertise sandbox controls honestly. The
-   * getter proves a sandboxing executor is mounted and supplies its fallback
-   * mode; a session override may make the effective mode narrower or wider,
-   * so strict escalation widening is checked per call rather than encoded in
-   * this default-relative capability fact. The base class reports
-   * `undefined`; a sandboxing implementation overrides the getter.
+   * The sandbox mode this executor confines commands under BY DEFAULT, or `undefined` when it
+   * does not sandbox at all — the capability fact the tool and ACP layers read to advertise
+   * sandbox controls honestly.
+   * A session or call may override this default, so widening is evaluated per
+   * execution rather than encoded in this getter.
    * @returns the configured default mode of a sandboxing executor;
    *   `undefined` for an executor that never confines.
    */
@@ -90,12 +63,7 @@ export abstract class BashExecutor extends Service {
   }
 
   /**
-   * Resolve a caller's {@link BashExecRequest} into a fully-specified
-   * {@link BashExecSpec}, applying this implementation's config defaults and
-   * caps (working directory, default/max timeout). Consumers (tool layer)
-   * call this, then pass the result to {@link run}/{@link start} — keeping
-   * defaulting in the implementation that owns the config while the seam type
-   * stays explicit (no hidden `?? default` inside run/start).
+   * Apply implementation-owned defaults and caps to a request before execution.
    * @param request - the caller's request; omitted fields get this
    *   implementation's defaults, capped fields are clamped.
    * @returns the fully-specified spec to hand to {@link run}/{@link start}.
@@ -125,17 +93,10 @@ export abstract class BashExecutor extends Service {
   abstract get(id: BashTaskId): BashTask | undefined
 
   /**
-   * The opaque OWNER token recorded for a background task at {@link start}
-   * (from the {@link BashExecSpec}'s `owner`), or `undefined` for an unknown id
-   * OR a known-but-ownerless task. The executor stores and returns the token
-   * verbatim — it never interprets it; the access POLICY (who may read/kill a
-   * task) lives in the consumer (`@deepseek-ai/dsh-tool-bash`), which compares
-   * `ownerOf(id)` to the caller's token. Collapsing unknown-id and
-   * known-but-unowned into the same `undefined` is fine: the consumer's access
-   * gate treats `undefined` as "open", and a genuinely unknown id then fails
-   * loudly at the subsequent {@link readOutput}/{@link kill} ("unknown task").
-   * Storing ownership in the executor (disposed with ITS fiber) — not in the
-   * tool plugin — is what makes ownership survive a `tool-bash` HMR reload.
+   * The opaque OWNER token recorded for a background task at {@link start} (from the {@link
+   * BashExecSpec}'s `owner`), or `undefined` for an unknown id OR a known-but-ownerless task.
+   * The executor stores the token without interpreting policy; keeping it here
+   * lets ownership survive a consumer-plugin reload.
    * @param id - the background task id to look up ownership for.
    * @returns the token recorded at start, verbatim; undefined for an unknown
    *   id or a known-but-ownerless task.

packages/bash/bash/src/session-mode.ts

@@ -1,18 +1,9 @@
 /**
- * Per-session sandbox-mode override: the session log as the store. A runtime
- * switch (an ACP `session/set_config_option`, a test scenario) is recorded as
- * one `bash/sandbox-mode` event on the session it applies to;
- * `effective = fold(events) ?? the executor's configured default`, so an
- * override survives restart by replay, two sessions can never see each
- * other's state, and there is no external config store. The event is
- * log-only (the `approval/*` precedent): the model receives neither this event
- * nor a standing mode statement. `@deepseek-ai/dsh-tool-bash` names the mode
- * only when it renders a sandbox denial. EXECUTION honors the fold in the tool
- * layer — it stamps the effective mode onto each call's
- * `BashExecRequest.sandboxMode` (weakest-precedence: an escalation grant for
- * the call outranks it) — the executor itself stays a config-fixed default
- * plus per-call overrides.
- *
+ * Per-session sandbox-mode override stored as log-only events. Folding the log
+ * isolates sessions and survives replay; the tool stamps the override onto
+ * each call unless an approved one-shot escalation outranks it, and the
+ * executor default applies when neither exists. The model receives neither the
+ * event nor a standing-mode notice; denial results name the effective mode.
  * @module dsh-bash/session-mode
  */
 
@@ -22,11 +13,9 @@ import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
     /**
-     * The session's sandbox mode was switched — log-only (like `approval/*`;
-     * NOT a surface event, carries no `surfaceOp`): durable and replayable,
-     * never in the model transcript. The LAST such event is the session's
-     * override ({@link effectiveSandboxMode}); execution and ACP config-option
-     * reporting fold it without adding prompt text or a context notice.
+     * Durable log-only sandbox-mode override; never a surface event or model
+     * message. Execution and ACP option reporting fold the latest event through
+     * {@link effectiveSandboxMode} without adding a prompt notice.
      */
     'bash/sandbox-mode': { mode: SandboxMode }
   }
@@ -37,9 +26,8 @@ export const SANDBOX_MODES: readonly SandboxMode[] = ['read-only', 'workspace-wr
 
 /**
  * The session's sandbox-mode override: the last `bash/sandbox-mode` event in
- * the log, or undefined when the session never switched (callers apply the
- * executor's configured default). The pure fold — resume needs no catch-up
- * machinery because replaying the log IS the state.
+ * the log, or undefined when the session never switched and callers should use
+ * the executor default. Replay needs no separate catch-up state.
  * @param events - session events in log order (other event types are skipped).
  * @returns the mode of the last switch event, or undefined without one.
  */
@@ -52,10 +40,9 @@ export function effectiveSandboxMode(events: readonly SessionEvent[]): SandboxMo
 }
 
 /**
- * THE write path for a session's sandbox-mode override: appends exactly one
- * `bash/sandbox-mode` event — the switch IS its event; nothing mutates mode
- * state out of band. Subsequent execution and ACP config-option reporting fold
- * it on read; no prompt assembly consumes it.
+ * Append one `bash/sandbox-mode` event as the only override write path.
+ * Execution and ACP option reporting fold it on read; prompt assembly does not
+ * consume it.
  * @param session - the session the override belongs to.
  * @param mode - the mode every subsequent bash call in this session runs
  *   under (until the next switch).

packages/bash/bash/src/types.ts

@@ -71,14 +71,8 @@ export interface BashSandboxInfo {
    */
   enforcement?: SandboxEnforcement
   /**
-   * True when the executor classifies this failure as the SANDBOX RUNNER
-   * itself failing (missing binary, refused profile, fail-closed refusal
-   * before exec) — the command NEVER RAN; this is a sandbox failure, not a
-   * task failure, and it outranks `denied` (a runner's own error text can
-   * contain denial words). Only ever stamped on settled BACKGROUND tasks: a
-   * foreground run surfaces the same condition as the thrown
-   * `SANDBOX_UNAVAILABLE` error instead (the foreground path has an error
-   * channel; a settled task's facts are its only channel).
+   * The sandbox runner failed before executing the command. Set only on settled
+   * background tasks; foreground runs throw `SANDBOX_UNAVAILABLE` instead.
    */
   runnerFailed?: boolean
 }
@@ -125,17 +119,9 @@ export interface BashExecRequest {
    */
   owner?: OwnerToken | undefined
   /**
-   * Explicit per-call sandbox-policy input, overriding the executor's
-   * configured default mode for THIS call. Never a silent default: a
-   * consumer sets it only from an explicit policy source — an
-   * `'allowed-once'` grant a human just issued through `ctx.approval` (the
-   * escalation flow in the sandbox RFC § Escalation, which outranks), or the
-   * session's standing override folded from its own `bash/sandbox-mode`
-   * events (the sandbox RFC § Per-session mode switching — the user's recorded per-session
-   * choice). A sandboxing executor confines THIS call under the given mode;
-   * a non-sandboxing executor carries the field and confines nothing (the
-   * tool layer stamps neither escalation nor overrides without a sandboxing
-   * executor — see {@link BashExecutor.sandboxMode}).
+   * Explicit per-call sandbox policy. The tool stamps a session override or a
+   * one-shot approved escalation, with the grant taking precedence. Sandboxing
+   * executors honor it for this call; non-sandboxing executors do not confine.
    */
   sandboxMode?: SandboxMode | undefined
 }