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.

packages/ui/acp/tests/config-options.spec.ts

@@ -99,12 +99,12 @@ describe('acp bridge — session config options', () => {
 
     // Idle: nothing in the log yet — turn-enclosure forbids a bare append.
     const session = h.ctx.agents.list()[0]?.session
-    expect(session?.events.some(e => e.type === 'permission/preset' || e.type === 'bash/sandbox-mode' || e.type === 'approval/policy')).toBe(false)
+    expect(session?.events.some(e => e.type === 'permission/preset' || e.type === 'sandbox/mode' || e.type === 'approval/policy')).toBe(false)
 
     await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'anchor' }] })
     const events = session?.events ?? []
     expect(events.filter(e => e.type === 'permission/preset').map(e => e.data)).toEqual([{ preset: 'danger-full-access' }])
-    expect(events.filter(e => e.type === 'bash/sandbox-mode').map(e => e.data)).toEqual([{ mode: 'danger-full-access' }])
+    expect(events.filter(e => e.type === 'sandbox/mode').map(e => e.data)).toEqual([{ mode: 'danger-full-access' }])
     expect(events.filter(e => e.type === 'approval/policy').map(e => e.data)).toEqual([{ policy: 'never' }])
     const turnStart = events.findIndex(e => e.type === 'turn/start')
     const anchored = events.findIndex(e => e.type === 'permission/preset')
@@ -135,7 +135,7 @@ describe('acp bridge — session config options', () => {
     expect(back.configOptions).toEqual([permissionOption('workspace-write')])
     await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'anchor' }] })
     const events = h.ctx.agents.list()[0]?.session.events ?? []
-    expect(events.some(e => e.type === 'permission/preset' || e.type === 'bash/sandbox-mode' || e.type === 'approval/policy')).toBe(false)
+    expect(events.some(e => e.type === 'permission/preset' || e.type === 'sandbox/mode' || e.type === 'approval/policy')).toBe(false)
   })
 
   it('a no-op switch (the value already shown) records nothing and keeps a live pending', async () => {
@@ -163,7 +163,7 @@ describe('acp bridge — session config options', () => {
     const anchored = events.findIndex(e => e.type === 'permission/preset')
     expect(turnStart).toBeGreaterThanOrEqual(0)
     expect(anchored).toBeGreaterThan(turnStart)
-    expect(events.some(e => e.type === 'bash/sandbox-mode')).toBe(true)
+    expect(events.some(e => e.type === 'sandbox/mode')).toBe(true)
     expect(events.some(e => e.type === 'approval/policy')).toBe(true)
     await h.client.cancel({ sessionId })
     await hung
@@ -213,7 +213,7 @@ describe('acp bridge — session config options', () => {
     const agent = h.ctx.agents.list()[0]
     if (agent === undefined) throw new Error('expected an agent')
     agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    agent.session.append('bash/sandbox-mode', { mode: 'read-only' })
+    agent.session.append('sandbox/mode', { mode: 'read-only' })
     agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     // The echo of the derived current is a no-op, not an unknown-value error…
     const echo = await h.client.setSessionConfigOption({ sessionId, configId: 'permission', value: 'custom' })

packages/ui/permission/package.json

@@ -24,6 +24,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-bash": "^0.0.1",
     "@deepseek-ai/dsh-sandbox": "^0.0.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-user-approval": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
@@ -34,6 +35,7 @@
   "devDependencies": {
     "@deepseek-ai/dsh-bash": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "cordis": "^4.0.0-rc.6"

packages/ui/permission/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * User-facing PERMISSION PRESETS: one product-level knob over the two
  * mechanism knobs. A preset names a bundle — its sandbox mode
- * (`bash/sandbox-mode`) and its approval policy (`approval/policy`) — so a
+ * (`sandbox/mode`) and its approval policy (`approval/policy`) — so a
  * user picks `workspace-write` or `danger-full-access` while the mechanism
  * tiers stay orthogonal capabilities. Switching a preset WRITES THROUGH: one `permission/preset` event
  * records the chosen bundle (the audit fact reverse-mapping cannot recover —
@@ -19,7 +19,10 @@ import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
-import { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from '@deepseek-ai/dsh-bash'
+import { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+// Side-effect type import: declaration-merges `ctx.bash` (the capability fact
+// `sandboxMode` this service reads), without a value dependency on the seam.
+import type {} from '@deepseek-ai/dsh-bash'
 import type { ApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
 import { APPROVAL_POLICIES, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
 
@@ -33,7 +36,7 @@ declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
     /**
      * The session's permission preset was switched — log-only (the
-     * `bash/sandbox-mode` precedent): durable and replayable, never in the
+     * `sandbox/mode` precedent): durable and replayable, never in the
      * model transcript. The LAST such event is the session's preset
      * ({@link effectivePermissionPreset}); the knob events the switch wrote
      * through follow it in the same turn, and they — not this record of the
@@ -48,7 +51,7 @@ declare module '@deepseek-ai/dsh-session' {
  * runs under while the preset is active — plus its presentation.
  */
 export interface PresetSpec {
-  /** The `bash/sandbox-mode` value the preset writes through. */
+  /** The `sandbox/mode` value the preset writes through. */
   sandbox: SandboxMode
   /** The `approval/policy` value the preset writes through. */
   approval: ApprovalPolicy

packages/ui/permission/tests/permission.spec.ts

@@ -53,7 +53,7 @@ describe('PermissionService', () => {
   it('a knob state matching no table entry derives custom — a state, not an error', async () => {
     const ctx = await mounted()
     const session = freshSession('sess-custom')
-    session.append('bash/sandbox-mode', { mode: 'read-only' })
+    session.append('sandbox/mode', { mode: 'read-only' })
     expect(ctx.permission.current(session.events)).toBe(CUSTOM_PRESET)
     // Switching FROM custom is an ordinary write-through; custom itself is
     // never a target.
@@ -80,7 +80,7 @@ describe('PermissionService', () => {
     expect(ctx.permission.current(session.events)).toBe('agentish')
     // A knob drifts: the fold's bundle no longer matches → reverse map wins.
     session.append('approval/policy', { policy: 'never' })
-    session.append('bash/sandbox-mode', { mode: 'danger-full-access' })
+    session.append('sandbox/mode', { mode: 'danger-full-access' })
     expect(ctx.permission.current(session.events)).toBe('danger-full-access')
   })
 
@@ -90,7 +90,7 @@ describe('PermissionService', () => {
     ctx.permission.set(session, 'danger-full-access')
     expect(session.events.map(e => [e.type, e.data])).toEqual([
       ['permission/preset', { preset: 'danger-full-access' }],
-      ['bash/sandbox-mode', { mode: 'danger-full-access' }],
+      ['sandbox/mode', { mode: 'danger-full-access' }],
       ['approval/policy', { policy: 'never' }],
     ])
   })
@@ -109,12 +109,12 @@ describe('PermissionService', () => {
     // A knob drifts out from under the preset (a direct setter call, a test
     // scenario): the session derives custom, and re-asserting the preset is
     // a real switch again — choice re-recorded, only the drifted knob moves.
-    session.append('bash/sandbox-mode', { mode: 'read-only' })
+    session.append('sandbox/mode', { mode: 'read-only' })
     ctx.permission.set(session, 'danger-full-access')
     const tail = session.events.slice(4)
     expect(tail.map(e => [e.type, e.data])).toEqual([
       ['permission/preset', { preset: 'danger-full-access' }],
-      ['bash/sandbox-mode', { mode: 'danger-full-access' }],
+      ['sandbox/mode', { mode: 'danger-full-access' }],
     ])
   })
 

packages/ui/permission/tsconfig.json

@@ -23,6 +23,9 @@
     {
       "path": "../../sandbox/sandbox"
     },
+    {
+      "path": "../../sandbox/sandbox-policy"
+    },
     {
       "path": "../../bash/bash"
     },