Merge remote-tracking branch 'origin/master' into codex/truncated-design

# Conflicts:
#	docs/capability-seams.md
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	docs/rfc/INDEX.md
#	docs/tool-catalog.md
#	examples/acp-agent/README.md
#	packages/README.md
#	packages/bash/bash/README.md
#	packages/core/tools/tests/gen-tool-catalog.spec.ts
#	packages/support/acp-snapshot/src/harness.ts
#	pnpm-lock.yaml
#	scripts/gen-doc-graphs.ts
#	scripts/gen-tool-catalog.ts
#	scripts/type-equiv.manifest.json

packages/bash/bash/README.md

@@ -2,15 +2,16 @@
 
 The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run commands, manage background tasks — without saying HOW.
 
-This package is one third of the bash capability, split so each concern can evolve (and be swapped) independently:
+This package is the interface quarter of the bash capability, split so each concern can evolve (and be swapped) independently:
 
 | Package | Role |
 |---|---|
 | `@deepseek-ai/dsh-bash` (this) | the interface: abstract service + vocabulary types |
 | `@deepseek-ai/dsh-bash-local` | an implementation: local subprocesses |
+| `@deepseek-ai/dsh-bash-sandbox` | an implementation: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
 | `@deepseek-ai/dsh-tool-bash` | the model-facing tool schemas over `ctx.bash` |
 
-The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. A future sandboxed, containerized, or remote executor implements this interface and the tool schemas don't change.
+The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same interface, tool schemas untouched; a containerized or remote executor slots in the same way.
 
 ## Service API (`ctx.bash`)
 
@@ -19,6 +20,7 @@ The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool su
 | `run(spec)` | Foreground execution. Resolves when the command finishes. **Rejects only for infrastructure failures** (unusable workdir, missing shell, pre-aborted signal); nonzero exits, timeout kills, and abort kills resolve with a descriptive `BashRunResult`. |
 | `start(spec)` | Background execution. Returns a `BashTask` handle immediately; **no timeout applies** (stop tasks via `kill`). |
 | `get(id)` / `list()` | Task lookup. |
+| `sandboxMode` | The capability fact for the tool layer: the default mode a SANDBOXING executor confines under (`undefined` in the base class — "this executor does not sandbox"). `dsh-tool-bash` reads it at registration to advertise the escalation fields only when the composition honors them. |
 | `ownerOf(id)` | The opaque OWNER token recorded for a background task at `start` (from the spec's `owner`), or `undefined` for an unknown id OR a known-but-ownerless task. The executor stores/returns it verbatim and NEVER interprets it — the access POLICY lives in the consumer (`dsh-tool-bash`), which compares `ownerOf(id)` to the caller's token. Storing ownership here (disposed with the executor's fiber) is what makes it survive a consumer HMR reload. |
 | `readOutput(id)` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. Throws for unknown ids. |
 | `kill(id)` | Kill a running task. Returns `false` when it already finished; throws for unknown ids. |
@@ -28,6 +30,8 @@ Implementations subclass `BashExecutor`, implement the abstract methods, and cal
 
 ## Vocabulary
 
-`BashExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, owner?) resolves to `BashExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, owner) before execution; `owner` is optional on the request and **required-but-nullable** (`OwnerToken | undefined`) on the resolved spec, so a forgotten owner is a visible `undefined` rather than a silently-absent property. 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). `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete stdout up to their own limit; the model-facing bash tool does not expose it. `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()`/`readOutput()` use `BashTask`/`BashTaskRead` for the background side. See `src/types.ts` for the full contracts.
+`BashExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, owner?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, 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. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete stdout up to their own limit; the model-facing bash tool does not expose it. `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.
 
 `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).

packages/bash/bash/package.json

@@ -23,10 +23,14 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
 }

packages/bash/bash/src/index.ts

@@ -15,13 +15,16 @@
  */
 
 import { Context, Service } from 'cordis'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId, BashTaskListener, BashTaskRead, OwnerToken } from './types.ts'
 
 export { BashTaskId, OwnerToken } from './types.ts'
+export { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from './session-mode.ts'
 export type {
   BashExecRequest,
   BashExecSpec,
   BashRunResult,
+  BashSandboxInfo,
   BashTask,
   BashTaskListener,
   BashTaskRead,
@@ -70,6 +73,22 @@ export abstract class BashExecutor extends Service {
     }, 'bash listener teardown')
   }
 
+  /**
+   * 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.
+   * @returns the configured default mode of a sandboxing executor;
+   *   `undefined` for an executor that never confines.
+   */
+  get sandboxMode(): SandboxMode | undefined {
+    return undefined
+  }
+
   /**
    * Resolve a caller's {@link BashExecRequest} into a fully-specified
    * {@link BashExecSpec}, applying this implementation's config defaults and

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

@@ -0,0 +1,65 @@
+/**
+ * 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 learns the mode from the
+ * prompt section and the boundary notices in `@deepseek-ai/dsh-tool-bash`,
+ * never from the event itself. 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.
+ *
+ * @module dsh-bash/session-mode
+ */
+
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+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}); who asked for it is derivable
+     * from position (an event after the log's last `request/header*` was a
+     * runtime switch by the user; see the tool layer's narrator).
+     */
+    'bash/sandbox-mode': { mode: SandboxMode }
+  }
+}
+
+/** Every {@link SandboxMode}, for option advertisement and runtime validation of untrusted mode strings. */
+export const SANDBOX_MODES: readonly SandboxMode[] = ['read-only', 'workspace-write', 'danger-full-access']
+
+/**
+ * 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.
+ * @param events - session events in log order (other event types are skipped).
+ * @returns the mode of the last switch event, or undefined without one.
+ */
+export function effectiveSandboxMode(events: readonly SessionEvent[]): SandboxMode | undefined {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index] as SessionEvent
+    if (event.type === 'bash/sandbox-mode') return event.data.mode
+  }
+  return undefined
+}
+
+/**
+ * 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. Takes effect on the session's next bash call and next
+ * prompt assembly (the consumers fold on every read).
+ * @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).
+ */
+export function setSandboxMode(session: Session, mode: SandboxMode): void {
+  session.append('bash/sandbox-mode', { mode })
+}

packages/bash/bash/src/types.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 
 /** Identifies one background task within an executor (generated `bash-N`). */
 export type BashTaskId = Branded<'BashTaskId'>
@@ -40,6 +41,48 @@ export function OwnerToken(id: string): OwnerToken {
   return id as OwnerToken
 }
 
+/**
+ * Sandbox facts for one foreground run — present on {@link BashRunResult} iff
+ * a sandboxing executor ran the command (an unsandboxed executor reports no
+ * `sandbox` field at all). Reported independently of `exitCode`/`signal`
+ * (orthogonal outcomes), so a caller can tell "the command failed on its own"
+ * from "the sandbox blocked a file operation". The mode/enforcement
+ * vocabulary lives on the `@deepseek-ai/dsh-sandbox` seam; this shape is the
+ * bash seam's result-fact carrier for it.
+ */
+export interface BashSandboxInfo {
+  /** The mode the command actually ran under. */
+  mode: SandboxMode
+  /**
+   * True when the executor classifies this run's failure as the sandbox
+   * denying a file operation. The classification is CONSERVATIVE (a failed
+   * exit whose stderr carries a filesystem-permission signature) and reads
+   * the COLLECTED stderr — the bounded in-memory tail per
+   * {@link CollectedOutput} semantics, so a signature that survives only in a
+   * spill file is missed toward `denied: false`. A plain command failure
+   * keeps `denied: false` even under a sandboxed mode.
+   */
+  denied: boolean
+  /**
+   * How completely the runner enforced `mode`'s file effects — see
+   * {@link SandboxEnforcement}. Absent exactly when `mode` is
+   * `danger-full-access`: nothing is confined, so there is no enforcement to
+   * report.
+   */
+  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).
+   */
+  runnerFailed?: boolean
+}
+
 /**
  * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
  * filled by {@link BashExecutor.resolve} from the implementation's config.
@@ -88,6 +131,20 @@ export interface BashExecRequest {
    * ownerless background start (a non-agent caller).
    */
   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}).
+   */
+  sandboxMode?: SandboxMode | undefined
 }
 
 /**
@@ -134,6 +191,16 @@ export interface BashExecSpec {
    * task. `start()` stores it; `run()` (foreground) ignores it.
    */
   owner: OwnerToken | undefined
+  /**
+   * The sandbox mode this call executes under, REQUIRED-but-nullable for the
+   * same visibility reason as `owner`. A sandboxing executor's `resolve()`
+   * stamps the effective mode (the request's explicit override, else its
+   * configured default) so `run()`/`start()` read the spec, never the config;
+   * a non-sandboxing executor carries the request value through verbatim and
+   * ignores it (`undefined` under such an executor means what its README says:
+   * unconfined execution).
+   */
+  sandboxMode: SandboxMode | undefined
 }
 
 /** One captured stream: the (possibly truncated) text plus recovery info. */
@@ -170,6 +237,12 @@ export interface BashRunResult {
   timeoutMs: number
   stdout: CollectedOutput
   stderr: CollectedOutput
+  /**
+   * Sandbox facts, present iff a sandboxing executor ran the command — an
+   * unsandboxed executor (e.g. `dsh-bash-local`) never sets it. See
+   * {@link BashSandboxInfo} for the `denied` classification semantics.
+   */
+  sandbox?: BashSandboxInfo
 }
 
 /** Lifecycle of a background task. */
@@ -186,6 +259,16 @@ export interface BashTask {
   signal: NodeJS.Signals | null
   /** Resolves when the underlying process closes (never rejects). */
   readonly done: Promise<void>
+  /**
+   * Sandbox facts for this task's execution, stamped by a sandboxing executor
+   * once the task settles and BEFORE completion listeners are notified — an
+   * `onTaskDone` consumer and a `done` awaiter both see it. Denial
+   * classification runs against the settled task's collected stderr, so the
+   * field cannot exist earlier: absent while the task is running and under an
+   * executor that does not sandbox. See {@link BashSandboxInfo} for the
+   * `denied` semantics.
+   */
+  sandbox?: BashSandboxInfo
 }
 
 /** One incremental {@link BashExecutor.readOutput} read. */

packages/bash/bash/tests/service.spec.ts

@@ -16,6 +16,7 @@ class StubExecutor extends BashExecutor {
       stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       ...request.signal ? { signal: request.signal } : {},
       owner: request.owner,
+      sandboxMode: request.sandboxMode,
     }
   }
 
@@ -97,6 +98,11 @@ describe('BashExecutor service seam', () => {
     expect(result.exitCode).toBe(0)
   })
 
+  it('reports no default sandbox mode (composition truth: the base never confines)', async () => {
+    const { bash } = await setup()
+    expect(bash.sandboxMode).toBeUndefined()
+  })
+
   it('onTaskDone delivers completions to registered listeners', async () => {
     const { bash } = await setup()
     const seen: string[] = []

packages/bash/bash/tsconfig.json

@@ -16,6 +16,12 @@
     },
     {
       "path": "../../util/brand"
+    },
+    {
+      "path": "../../sandbox/sandbox"
+    },
+    {
+      "path": "../../core/session"
     }
   ]
 }