feat(sandbox): cross-family file sandbox — one policy home, sandboxed fs provider, fs escalation parity

Extend SandboxMode enforcement from bash to the filesystem tools, the sandbox RFC's deferred cross-family phase. - dsh-sandbox-policy (new, ctx.sandboxPolicy): the single home for the deployment default mode + workspaceRoot and the per-session override event, renamed bash/sandbox-mode -> sandbox/mode and moved here with its fold/setter. Decouples the bash seam from dsh-session. - dsh-fs-sandbox (new): SandboxedFileSystem extends LocalFileSystem and fences write/edit by the per-call mode (read-only denies, workspace-write contains to the workspace + temp roots via the shared writableRoots, danger passes through); reads pass through. Structured FS_SANDBOX_DENIED; in-lock parent re-canonicalization. A policy fence in trusted code, not a kernel boundary. - dsh-sandbox: the shared escalation kit (writableRoots, the strictly-wider ladder, denial/hint markers, approveEscalation) both tool families use; approveEscalation takes a structural approver so dsh-sandbox gains no approval/agent dependency, and both tools stay duplication-free. - tool-fs: write/edit advertise sandbox_permissions/justification under a confining ctx.fs, map FS_SANDBOX_DENIED to the shared [sandbox: ...] marker, and resolve the same one-approved-wider retry. - examples/acp-agent: composes sandbox-policy + fs-sandbox, drops the gating that disabled the fs stack under confined modes. RFC docs/rfc/implemented/feature/2026-07-14-cross-family-fs-sandbox.md; the old sandbox RFC's In-process/deferred/FAQ sections updated to shipped fact.
2026-07-14 20:05:57 +08:00
parent c3137b5474
commit 2dc62497ce
100 changed files with 2238 additions and 385 deletions
--- a/packages/bash/bash-sandbox/package.json
+++ b/packages/bash/bash-sandbox/package.json
@@ -25,16 +25,15 @@
    "@deepseek-ai/dsh-bash": "^0.0.1",
    "@deepseek-ai/dsh-bash-local": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
    "cordis": "^4.0.0-rc.6"
  },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
  "devDependencies": {
    "@deepseek-ai/dsh-bash": "workspace:^",
    "@deepseek-ai/dsh-bash-local": "workspace:^",
    "@deepseek-ai/dsh-sandbox": "workspace:^",
    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
    "node-addon-landlock-run": "0.0.0-test.0",
    "cordis": "^4.0.0-rc.6"
  }
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -41,31 +41,23 @@
 * @module @deepseek-ai/dsh-bash-sandbox
 */

-import { resolve } from 'node:path'
 import { Context } from 'cordis'
-import z from 'schemastery'
 import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId } from '@deepseek-ai/dsh-bash'
 import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedSandboxMode, SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type {} from '@deepseek-ai/dsh-sandbox-policy'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'

 /**
- * Plugin config: the local executor's knobs plus the sandbox policy. All
- * optional — `static Config` supplies the defaults (`mode: 'read-only'` is the
- * fail-safe default; an example that wants a workspace-writable agent opts in
- * explicitly). The runner choice is NOT configured here: which platform
- * backend confines the command is the `ctx.sandbox` provider's config.
+ * Plugin config: the local executor's knobs, verbatim. The sandbox policy —
+ * the default mode and the `workspace-write` boundary root — is NOT here: it
+ * lives on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), the one
+ * home both enforcing families read, so bash and fs can never confine to
+ * different roots. The runner choice is likewise the `ctx.sandbox` provider's
+ * config, not this executor's.
 */
-export interface Config extends LocalConfig {
-  /** File-sandbox mode commands run under (default: `read-only`). */
-  mode?: SandboxMode
-  /**
-   * Root directory `workspace-write` mode may write under (default: the
-   * executor's default working directory — `cwd`, else `process.cwd()`).
-   */
-  workspaceRoot?: string
-}
+export type Config = LocalConfig

 /**
 * Quote one string as a single-quoted POSIX shell word (embedded single
@@ -141,24 +133,18 @@ function matchesSignature(exitCode: number | null, stderr: string, signatures: r
 * 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
+ * durable `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 tool's per-agent prompt section states that same effective
 * mode, and each run's `result.sandbox` reports what actually executed plus
 * enforcement completeness.
 */
 export class SandboxBashExecutor extends LocalBashExecutor {
-  static inject = ['sandbox']
+  static inject = ['sandbox', 'sandboxPolicy']

-  // The sandbox-specific fields intersect the local executor's Config as an
-  // inline schema call: the config catalog walks `static Config` statically.
-  static override Config: z<Config> = z.intersect([
-    LocalBashExecutor.Config,
-    z.object({
-      mode: z.union(['read-only', 'workspace-write', 'danger-full-access'] as const).default('read-only'),
-      workspaceRoot: z.string(),
-    }),
-  ])
+  // No own Config: the sandbox default (mode + workspaceRoot) moved to
+  // ctx.sandboxPolicy, so this executor inherits LocalBashExecutor's Config
+  // verbatim (the config catalog walks the inherited static).

  private readonly mode: SandboxMode
  private readonly workspaceRoot: string
@@ -182,12 +168,11 @@ export class SandboxBashExecutor extends LocalBashExecutor {

  constructor(ctx: Context, config: Config) {
    super(ctx, config)
-    // schemastery (static Config) already filled the defaulted fields — the
-    // cast records that runtime fact (mirrors LocalBashExecutor's config
-    // cast). `workspaceRoot` and `cwd` have NO schema default, so their
-    // fallback chain is real branching.
-    this.mode = config.mode as SandboxMode
-    this.workspaceRoot = resolve(config.workspaceRoot ?? config.cwd ?? process.cwd())
+    // The sandbox default (mode + workspaceRoot) is the one shared policy home
+    // both enforcing families read; injecting sandboxPolicy guarantees it is
+    // constructed first. workspaceRoot arrives already resolved absolute.
+    this.mode = ctx.sandboxPolicy.defaultMode
+    this.workspaceRoot = ctx.sandboxPolicy.workspaceRoot
  }

  /** The configured default mode — the capability fact the tool layer reads. */
--- a/packages/bash/bash-sandbox/tests/bwrap.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/bwrap.e2e.ts
@@ -6,6 +6,7 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'

 /**
@@ -46,7 +47,8 @@ async function tempDir(base: string): Promise<string> {
 async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-write'): Promise<SandboxBashExecutor> {
  ctx = new Context()
  await ctx.plugin(LocalSandboxProvider, {})
-  await ctx.plugin(SandboxBashExecutor, { mode, cwd: workspace, workspaceRoot: workspace, timeoutMs: 30_000 })
+  await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: workspace })
+  await ctx.plugin(SandboxBashExecutor, { cwd: workspace, timeoutMs: 30_000 })
  return ctx.bash as SandboxBashExecutor
 }

--- a/packages/bash/bash-sandbox/tests/landlock.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/landlock.e2e.ts
@@ -7,6 +7,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { launcherPath } from 'node-addon-landlock-run'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'

 /**
@@ -45,7 +46,8 @@ async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-w
  ctx = new Context()
  await ctx.plugin(LocalSandboxProvider, {})
  ;(ctx.sandbox as LocalSandboxProvider).internals = { probeBwrap: () => false }
-  await ctx.plugin(SandboxBashExecutor, { mode, cwd: workspace, workspaceRoot: workspace, timeoutMs: 30_000 })
+  await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: workspace })
+  await ctx.plugin(SandboxBashExecutor, { cwd: workspace, timeoutMs: 30_000 })
  return ctx.bash as SandboxBashExecutor
 }

--- a/packages/bash/bash-sandbox/tests/sandbox.spec.ts
+++ b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
@@ -15,7 +15,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
 import { SANDBOX_UNAVAILABLE, SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
-import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import type { ConfinedArgv, SandboxMode, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { classifyDenial, classifyRunnerFailure, SandboxBashExecutor, shellQuote } from '@deepseek-ai/dsh-bash-sandbox'
 import type { Config } from '@deepseek-ai/dsh-bash-sandbox'

@@ -39,9 +40,15 @@ const passthrough = (argv: readonly string[]): ConfinedArgv =>

 /**
 * Boot a context with a recording fake `ctx.sandbox` (behavior injectable
- * per test) and the executor under test on top of it.
+ * per test), the shared `ctx.sandboxPolicy` (mode + workspaceRoot), and the
+ * executor under test on top of them. `mode`/`workspaceRoot` route to the
+ * policy service; the rest (cwd, graceMs, timeoutMs) to the executor.
 */
-async function setup(config: Config = {}, behavior: (argv: readonly string[], policy: SandboxPolicy) => ConfinedArgv = passthrough) {
+async function setup(
+  config: { mode?: SandboxMode; workspaceRoot?: string } & Config = {},
+  behavior: (argv: readonly string[], policy: SandboxPolicy) => ConfinedArgv = passthrough,
+) {
+  const { mode, workspaceRoot, ...execConfig } = config
  const calls: ConfineCall[] = []
  class FakeSandboxProvider extends SandboxProvider {
    confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
@@ -51,7 +58,11 @@ async function setup(config: Config = {}, behavior: (argv: readonly string[], po
  }
  const ctx = new Context()
  await ctx.plugin(FakeSandboxProvider)
-  await ctx.plugin(SandboxBashExecutor, { graceMs: 200, ...config })
+  await ctx.plugin(SandboxPolicyService, {
+    ...mode !== undefined ? { mode } : {},
+    ...workspaceRoot !== undefined ? { workspaceRoot } : {},
+  })
+  await ctx.plugin(SandboxBashExecutor, { graceMs: 200, ...execConfig })
  const bash = ctx.bash as SandboxBashExecutor
  bash.internals = { spillDir }
  return { ctx, bash, calls }
@@ -86,14 +97,14 @@ describe('the provider hand-off', () => {
    expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
  })

-  it('workspace-write rides the policy, workspaceRoot falling back to cwd when not configured', async () => {
-    const { bash, calls } = await setup({ mode: 'workspace-write', cwd: tmpdir() })
+  it('workspace-write rides the policy, workspaceRoot falling back to process.cwd() when not configured', async () => {
+    const { bash, calls } = await setup({ mode: 'workspace-write' })
    const result = await bash.run(bash.resolve({ command: 'true' }))
    expect(result.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' })
-    expect(calls[0]?.policy).toEqual({ mode: 'workspace-write', workspaceRoot: resolve(tmpdir()) })
+    expect(calls[0]?.policy).toEqual({ mode: 'workspace-write', workspaceRoot: resolve(process.cwd()) })
  })

-  it('an explicit workspaceRoot wins over cwd', async () => {
+  it('an explicit workspaceRoot on the policy wins', async () => {
    const { calls, bash } = await setup({ mode: 'workspace-write', workspaceRoot: '/ws', cwd: tmpdir() })
    await bash.run(bash.resolve({ command: 'true' }))
    expect(calls[0]?.policy.workspaceRoot).toBe(resolve('/ws'))
--- a/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
@@ -6,6 +6,7 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local'
+import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'

 /**
@@ -43,7 +44,8 @@ async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-w
  ctx = new Context()
  await ctx.plugin(LocalSandboxProvider, {})
  ;(ctx.sandbox as LocalSandboxProvider).internals = { probeBwrap: () => false, probeLandlock: () => 'unusable' }
-  await ctx.plugin(SandboxBashExecutor, { mode, cwd: workspace, workspaceRoot: workspace, timeoutMs: 30_000 })
+  await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: workspace })
+  await ctx.plugin(SandboxBashExecutor, { cwd: workspace, timeoutMs: 30_000 })
  return ctx.bash as SandboxBashExecutor
 }

--- a/packages/bash/bash-sandbox/tsconfig.json
+++ b/packages/bash/bash-sandbox/tsconfig.json
@@ -14,9 +14,6 @@
    {
      "path": "../../../vendor/cordis"
    },
-    {
-      "path": "../../../vendor/schemastery"
-    },
    {
      "path": "../../util/brand"
    },
@@ -26,6 +23,9 @@
    {
      "path": "../../sandbox/sandbox"
    },
+    {
+      "path": "../../sandbox/sandbox-policy"
+    },
    {
      "path": "../../bash/bash"
    },
--- a/packages/bash/bash/package.json
+++ b/packages/bash/bash/package.json
@@ -24,13 +24,11 @@
  "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"
  }
 }
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -19,7 +19,6 @@ 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,
--- a/packages/bash/bash/src/session-mode.ts
+++ b/packages/bash/bash/src/session-mode.ts
@@ -1,65 +0,0 @@
-/**
- * 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 })
-}
--- a/packages/bash/bash/src/types.ts
+++ b/packages/bash/bash/src/types.ts
@@ -130,7 +130,7 @@ export interface BashExecRequest {
   * 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`
+   * session's standing override folded from its own `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
--- a/packages/bash/bash/tsconfig.json
+++ b/packages/bash/bash/tsconfig.json
@@ -19,9 +19,6 @@
    },
    {
      "path": "../../sandbox/sandbox"
-    },
-    {
-      "path": "../../core/session"
    }
  ]
 }
--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -25,8 +25,8 @@
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-user-approval": "^0.0.1",
    "@deepseek-ai/dsh-bash": "^0.0.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "cordis": "^4.0.0-rc.6"
@@ -41,6 +41,7 @@
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-sandbox": "workspace:^",
    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -44,7 +44,7 @@
 * that the composition cannot honor.
 *
 * Per-session mode switching (the sandbox RFC § Per-session mode switching): a session may carry a
- * standing sandbox-mode override — the `bash/sandbox-mode` event fold from
+ * standing sandbox-mode override — the `sandbox/mode` event fold from
 * `@deepseek-ai/dsh-bash` — which this plugin makes real at EXECUTION: each
 * call is stamped `escalation grant > session override > executor default`.
 * The prompt deliberately does NOT state the mode and no switch is narrated:
@@ -60,14 +60,21 @@ import { isAbsolute, resolve as resolvePath } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, TerminalCallView, ToolExecution, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { assertNever } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 // Side-effect type import: declaration-merges `ctx.approval`, consumed
 // opportunistically by the escalation gate (`ctx.get('approval')` — the seam
 // stays optional at runtime, same pattern as dsh-tools' ask routing).
 import type {} from '@deepseek-ai/dsh-user-approval'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
-import { BashTaskId, OwnerToken, effectiveSandboxMode } from '@deepseek-ai/dsh-bash'
+import {
+  ESCALATION_TARGETS,
+  approveEscalation,
+  escalationHintMarker,
+  sandboxDenialMarker,
+  validateEscalationArgs,
+} from '@deepseek-ai/dsh-sandbox'
+import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+import { BashTaskId, OwnerToken } from '@deepseek-ai/dsh-bash'
 import type { BashRunResult, BashTask, CollectedOutput } from '@deepseek-ai/dsh-bash'

 export const name = 'tool-bash'
@@ -93,15 +100,9 @@ function validateBashArgs(args: BashToolArgs): void {
  if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
    throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`)
  }
-  if (args.sandbox_permissions !== undefined && args.justification === undefined) {
-    throw new Error('invalid escalation: sandbox_permissions requires a justification')
-  }
-  if (args.justification !== undefined && args.sandbox_permissions === undefined) {
-    throw new Error('invalid escalation: justification is only valid together with sandbox_permissions')
-  }
-  if (args.justification !== undefined && args.justification.trim().length === 0) {
-    throw new Error('invalid justification: expected a non-empty sentence')
-  }
+  // The escalation pairing (sandbox_permissions ⇔ justification, non-empty) is
+  // the shared rule both enforcing families validate identically.
+  validateEscalationArgs(args.sandbox_permissions, args.justification)
 }

 /**
@@ -132,27 +133,6 @@ interface BashToolArgs {
  justification?: string
 }

-/**
- * The strictly-wider table: what a call whose effective mode is the key may
- * escalate TO. Checked at EXECUTION, never baked into the schema — the
- * schema's enum is {@link ESCALATION_TARGETS}, because schemas are
- * registry-global while the effective mode is per-call truth.
- */
-const WIDER_MODES: Record<string, readonly SandboxMode[]> = {
-  'read-only': ['workspace-write', 'danger-full-access'],
-  'workspace-write': ['danger-full-access'],
-}
-
-/**
- * The closed escalation-target vocabulary — every mode a call could ever
- * escalate TO (`read-only` is the floor; nothing escalates to it). Advertised
- * whenever the mounted executor confines: cutting the enum down to the modes
- * wider than the executor's DEFAULT would strand a session whose effective
- * mode sits below it (a `danger-full-access` default would advertise nothing
- * while a narrower-switched session stays confined with no lever).
- */
-const ESCALATION_TARGETS: readonly SandboxMode[] = ['workspace-write', 'danger-full-access']
-
 /**
 * The bash tool's static description. The base text is byte-stable regardless
 * of composition (it is part of the pinned snapshot header); the escalation
@@ -222,13 +202,13 @@ export function renderResult(
  // stays the LAST line (exitStatus() anchors its parse there). Denial is a
  // reported fact like timeout: the model decides how to react.
  if (result.sandbox?.denied) {
-    markers.push(`[sandbox: file access denied under ${result.sandbox.mode} mode]`)
+    markers.push(sandboxDenialMarker(result.sandbox.mode))
    // The same-turn nudge lives at the decision point: only when this
    // composition advertises the fields (a lever is never hinted that the
    // schema does not offer), and inside the sandbox marker family so the
    // exit-code marker stays the last line.
    if (escalationModes.length > 0) {
-      markers.push('[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]')
+      markers.push(escalationHintMarker('command'))
    }
  }
  // Timeout is reported independently of how the process actually ended: a
@@ -482,7 +462,7 @@ export function apply(ctx: Context): void {

  /**
   * The session's standing mode override for an ordinary (non-escalating)
-   * call: the `bash/sandbox-mode` fold of the calling agent's log, stamped
+   * call: the `sandbox/mode` fold of the calling agent's log, stamped
   * onto the request so EXECUTION follows the same effective mode the prompt
   * section states. Weakest precedence — an escalation grant (freshly
   * approved for exactly this call) outranks it, and without either the
@@ -495,58 +475,30 @@ export function apply(ctx: Context): void {

  /**
   * Resolve a sandbox-escalation request through `ctx.approval` BEFORE
-   * anything executes. Returns the granted mode to stamp onto the bash
-   * request; throws the distinct fail-closed text for every other path (no
-   * service composed, an agent-less execution, a rejection, a cancellation,
-   * an unanswerable ask) — the registry turns the throw into this call's
-   * isError result, and nothing has run. The seam is consumed
-   * opportunistically (`ctx.get`, the dsh-tools ask-routing pattern), so a
-   * deployment without it degrades per call, never at registration.
+   * anything executes, delegating the shared fail-closed sequence (strict
+   * widening, channel resolution, outcome mapping) to
+   * {@link approveEscalation}. This tool contributes only the composition
+   * guard (the fields are unadvertised without a sandboxing executor, yet
+   * schema validation checks advertised keys only, so an unadvertised
+   * `sandbox_permissions` still reaches execute) and the channel closure over
+   * `ctx.approval` — consumed opportunistically (`ctx.get`, the dsh-tools
+   * ask-routing pattern) so a deployment without it degrades per call.
   */
-  const approveEscalation = async (mode: string, justification: string, exec: ToolExecution): Promise<SandboxMode> => {
-    // Schema validation only checks ADVERTISED keys, so an unadvertised
-    // `sandbox_permissions` (no sandboxing executor) still reaches execute — reject it here so a
-    // human is never prompted to "escalate" a sandbox that is not there. When
-    // the fields ARE advertised, the registry's SchemaSpec enum has already
-    // pinned `mode` to this ladder for every caller.
+  const approveBashEscalation = (mode: string, justification: string, exec: ToolExecution): Promise<SandboxMode> => {
    if (escalationModes.length === 0) {
      throw new Error('sandbox_permissions is not available in this composition (no sandboxing executor to escalate)')
    }
-    // Strict widening is an EXECUTION check against the call's effective
-    // mode — session override ?? executor default, the same fold ordinary
-    // calls are stamped with — deliberately not a schema constraint (the
-    // enum is the closed target vocabulary; the effective mode is per-call
-    // truth). A non-widening request fails closed here and never prompts a
-    // human.
    const effectiveMode = (sessionOverride(exec) ?? defaultMode) as SandboxMode
-    if (!(WIDER_MODES[effectiveMode] ?? []).includes(mode as SandboxMode)) {
-      throw new Error(`sandbox escalation to "${mode}" is not strictly wider than this call's current "${effectiveMode}" mode`)
-    }
-    const approval = ctx.get('approval')
-    if (approval === undefined) {
-      throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval service is composed`)
-    }
-    if (exec.agent === undefined) {
-      throw new Error(`sandbox escalation to "${mode}" requires approval, but the call has no agent to route it through`)
-    }
-    const outcome = await approval.request({
-      agent: exec.agent,
-      toolName: 'bash',
-      callId: exec.callId,
-      // Self-contained for the audit trail: approval/asked stores this
-      // reason, and the target mode is part of the grant's identity.
-      reason: `escalate sandbox to ${mode}: ${justification}`,
-      ...exec.signal ? { signal: exec.signal } : {},
-    })
-    switch (outcome) {
-      // The SchemaSpec enum already pinned `mode` to the closed target
-      // vocabulary; the per-call check above proved it is strictly wider.
-      case 'allowed-once': return mode as SandboxMode
-      case 'rejected': throw new Error(`the user rejected escalating this command to "${mode}"`)
-      case 'cancelled': throw new Error(`approval for escalating to "${mode}" was cancelled`)
-      case 'unavailable': throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval channel is available`)
-      default: return assertNever(outcome, 'ApprovalOutcome')
-    }
+    return approveEscalation(
+      { requestedMode: mode, justification, effectiveMode, subject: 'command' },
+      {
+        approver: ctx.get('approval'),
+        agent: exec.agent,
+        callId: exec.callId,
+        toolName: 'bash',
+        ...exec.signal ? { signal: exec.signal } : {},
+      },
+    )
  }

  ctx.tools.register(defineTool({
@@ -589,7 +541,7 @@ export function apply(ctx: Context): void {
      // An ordinary call carries the session's standing override instead —
      // grant > session override > executor default (see sessionOverride).
      const sandboxMode = args.sandbox_permissions !== undefined && args.justification !== undefined
-        ? await approveEscalation(args.sandbox_permissions, args.justification, exec)
+        ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec)
        : sessionOverride(exec)
      // Default the workdir to the calling agent's session cwd so each ACP
      // session runs in its own workspace (see resolveWorkdir); an explicit
@@ -649,9 +601,9 @@ export function apply(ctx: Context): void {
        // hint). Background denials are only classifiable once the task
        // settles (the classifier needs the whole stderr), so the marker
        // rides every read that sees the settled task.
-        text += `\n[sandbox: file access denied under ${read.task.sandbox.mode} mode]`
+        text += `\n${sandboxDenialMarker(read.task.sandbox.mode)}`
        if (escalationModes.length > 0) {
-          text += '\n[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]'
+          text += `\n${escalationHintMarker('command')}`
        }
      }
      return Promise.resolve([{ type: 'text', text }])
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
-import { BashExecutor, BashTaskId, setSandboxMode } from '@deepseek-ai/dsh-bash'
+import { BashExecutor, BashTaskId } from '@deepseek-ai/dsh-bash'
 import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
@@ -15,6 +15,7 @@ import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 import { SandboxProvider } from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv } from '@deepseek-ai/dsh-sandbox'
+import { SandboxPolicyService, setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import ApprovalService from '@deepseek-ai/dsh-user-approval'
 import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
@@ -1040,6 +1041,7 @@ describe('sandbox rendering', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
+    await ctx.plugin(SandboxPolicyService, {})
    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
    const bash = ctx.bash as SandboxBashExecutor
    bash.internals = { spillDir }
@@ -1106,6 +1108,7 @@ describe('sandbox rendering', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(FakeProvider)
+    await ctx.plugin(SandboxPolicyService, {})
    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
    const bash = ctx.bash as SandboxBashExecutor
    bash.internals = { spillDir }
@@ -1126,6 +1129,7 @@ describe('sandbox rendering', () => {
      runnerCommand: ['bash', '-c', `printf '${signature}\\n' >&2; exit 125`, 'custom-runner'],
      runnerFailureSignatures: [signature],
    })
+    await ctx.plugin(SandboxPolicyService, {})
    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
    const bash = ctx.bash as SandboxBashExecutor
    bash.internals = { spillDir }
@@ -1144,6 +1148,7 @@ describe('sandbox rendering', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
+    await ctx.plugin(SandboxPolicyService, {})
    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
    const bash = ctx.bash as SandboxBashExecutor
    bash.internals = { spillDir }
@@ -1167,7 +1172,8 @@ describe('sandbox escalation (sandbox_permissions / justification)', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
-    await ctx.plugin(SandboxBashExecutor, { graceMs: 200, ...mode !== undefined ? { mode } : {} })
+    await ctx.plugin(SandboxPolicyService, mode !== undefined ? { mode } : {})
+    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
    const bash = ctx.bash as SandboxBashExecutor
    bash.internals = { spillDir }
    if (opts.approval === true) await ctx.plugin(ApprovalService, opts.policy !== undefined ? { policy: opts.policy } : {})
@@ -1381,7 +1387,7 @@ describe('sandbox escalation (sandbox_permissions / justification)', () => {
  })
 })

-describe('per-session sandbox mode (the bash/sandbox-mode fold)', () => {
+describe('per-session sandbox mode (the sandbox/mode fold)', () => {
  /** Compose the real sandbox stack (passthrough runner) at a given default mode. */
  async function setupModal(mode: 'read-only' | 'workspace-write' | 'danger-full-access' = 'read-only', opts: { approval?: boolean } = {}) {
    const ctx = new Context()
@@ -1389,7 +1395,8 @@ describe('per-session sandbox mode (the bash/sandbox-mode fold)', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
-    await ctx.plugin(SandboxBashExecutor, { graceMs: 200, mode })
+    await ctx.plugin(SandboxPolicyService, { mode })
+    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
    ;(ctx.bash as SandboxBashExecutor).internals = { spillDir }
    if (opts.approval === true) await ctx.plugin(ApprovalService)
    await ctx.plugin(ToolBash)
--- a/packages/bash/tool-bash/tsconfig.json
+++ b/packages/bash/tool-bash/tsconfig.json
@@ -14,9 +14,6 @@
    {
      "path": "../../../vendor/cordis"
    },
-    {
-      "path": "../../llm/llm"
-    },
    {
      "path": "../../core/tools"
    },
@@ -34,6 +31,9 @@
    },
    {
      "path": "../../sandbox/sandbox"
+    },
+    {
+      "path": "../../sandbox/sandbox-policy"
    }
  ]
 }