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/fs/tool-fs/src/sandbox.ts

@@ -0,0 +1,132 @@
+/**
+ * The sandbox-escalation surface shared by the `write` and `edit` tools: the
+ * per-call mode stamp, the advertised escalation fields, and the denial-marker
+ * mapping — all delegating the vocabulary and the fail-closed approval
+ * sequence to `@deepseek-ai/dsh-sandbox` (the same pieces `@deepseek-ai/dsh-tool-bash`
+ * uses), so bash and fs escalate identically. Built ONCE per plugin from
+ * `ctx.fs.sandboxMode` (the capability fact — is a confining backend mounted?)
+ * and shared by both mutating tools.
+ *
+ * @module @deepseek-ai/dsh-tool-fs/sandbox
+ */
+
+import type { Context } from 'cordis'
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
+import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+import { FsError } from '@deepseek-ai/dsh-fs'
+
+/** The two escalation arguments a mutating tool may carry (advertised only under a confining backend). */
+export interface FsEscalationArgs {
+  sandbox_permissions?: string
+  justification?: string
+}
+
+/** The schema fields for the escalation arguments, spread into a tool's `parameters` when a confining backend is mounted. */
+export interface EscalationSchemaFields {
+  sandbox_permissions: { type: 'string'; enum: string[]; description: string }
+  justification: { type: 'string'; description: string }
+}
+
+/**
+ * The filesystem escalation surface: advertisement gating, per-call mode
+ * stamping (folding the session's `sandbox/mode` override), the one-approved
+ * wider retry, and denial-marker mapping. A pure product of `ctx` at plugin
+ * apply time.
+ */
+export class FsSandboxSurface {
+  /** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
+  readonly escalationModes: readonly SandboxMode[]
+  /** The backend's default mode, or `undefined` when `ctx.fs` does not confine. */
+  private readonly defaultMode: SandboxMode | undefined
+
+  constructor(private readonly ctx: Context) {
+    this.defaultMode = ctx.fs.sandboxMode
+    this.escalationModes = this.defaultMode === undefined ? [] : ESCALATION_TARGETS
+  }
+
+  /**
+   * The escalation schema fields for a mutating tool's `parameters`. Call it
+   * only under a confining backend (guard on {@link escalationModes}); the
+   * enum pins the closed target vocabulary, the strict-wider check happens per
+   * call at execution.
+   * @returns the two escalation parameter specs.
+   */
+  schemaFields(): EscalationSchemaFields {
+    return {
+      sandbox_permissions: {
+        type: 'string',
+        enum: [...this.escalationModes],
+        description: 'The wider sandbox mode this file operation needs. Only valid as a one-shot retry '
+          + 'of an operation the sandbox just denied; requires justification and user approval.',
+      },
+      justification: {
+        type: 'string',
+        description: 'Required with sandbox_permissions: one sentence for the user explaining '
+          + 'why this exact file operation needs the wider access.',
+      },
+    }
+  }
+
+  /**
+   * The session's standing mode override for an ordinary (non-escalating)
+   * call — the `sandbox/mode` fold of the calling agent's log. Undefined for a
+   * non-confining backend and for agent-less callers.
+   */
+  private sessionOverride(exec: ToolExecution): SandboxMode | undefined {
+    if (this.defaultMode === undefined || exec.agent === undefined) return undefined
+    return effectiveSandboxMode(exec.agent.session.events)
+  }
+
+  /**
+   * The mode to STAMP onto this mutation: an approved escalation grant (a
+   * strictly wider retry resolved through `ctx.approval` before anything
+   * executes), else the session's standing override, else `undefined` (the
+   * backend applies its own default). Validates the escalation argument
+   * pairing first.
+   * @param toolName - the mutating tool's name, for the approval audit trail.
+   * @param args - the call's escalation arguments.
+   * @param exec - the tool-execution context (agent, callId, signal).
+   * @returns the mode to pass to the mutation, or undefined for the backend default.
+   */
+  async stampMode(toolName: string, args: FsEscalationArgs, exec: ToolExecution): Promise<SandboxMode | undefined> {
+    validateEscalationArgs(args.sandbox_permissions, args.justification)
+    if (args.sandbox_permissions === undefined || args.justification === undefined) {
+      return this.sessionOverride(exec)
+    }
+    if (this.escalationModes.length === 0) {
+      throw new Error('sandbox_permissions is not available in this composition (no sandboxing filesystem to escalate)')
+    }
+    const effectiveMode = (this.sessionOverride(exec) ?? this.defaultMode) as SandboxMode
+    return approveEscalation(
+      { requestedMode: args.sandbox_permissions, justification: args.justification, effectiveMode, subject: 'operation' },
+      {
+        approver: this.ctx.get('approval'),
+        agent: exec.agent,
+        callId: exec.callId,
+        toolName,
+        ...exec.signal ? { signal: exec.signal } : {},
+      },
+    )
+  }
+
+  /**
+   * Map a thrown provider error for the model: a `FS_SANDBOX_DENIED` becomes an
+   * error whose text is the shared `[sandbox: …]` denial marker plus the
+   * same-turn escalation hint, so a policy denial reads identically to bash's;
+   * any other error passes through unchanged. A `FS_SANDBOX_DENIED` only arises
+   * under a confining backend, which always advertises the escalation fields,
+   * so the hint always applies here.
+   * @param error - the error thrown by the mutation.
+   * @param stampedMode - the mode stamped onto the call (names the mode in the marker).
+   * @returns the error to throw — the marker error for a sandbox denial, else the original.
+   */
+  mapError(error: unknown, stampedMode: SandboxMode | undefined): unknown {
+    if (!(error instanceof FsError) || error.code !== 'FS_SANDBOX_DENIED') return error
+    // A FS_SANDBOX_DENIED only arises under a confining backend, so defaultMode
+    // (hence the resolved mode) is defined here.
+    const mode = (stampedMode ?? this.defaultMode) as SandboxMode
+    return new Error(`${sandboxDenialMarker(mode)}\n${escalationHintMarker('operation')}`)
+  }
+}