feat(tool-bash): sandbox escalation — one approved wider retry after a denial

The tool gate advertises sandbox_permissions (an enum of exactly the modes
STRICTLY WIDER than the mounted executor default — the schema makes a
non-widening request inexpressible) plus a required justification, exactly
when ctx.bash.sandboxMode reports a confining mode at registration:
composition truth, never a dead lever. An escalating call resolves
ctx.approval BEFORE anything executes with the audit-self-contained reason
"escalate sandbox to <mode>: <justification>"; allowed-once stamps the
granted mode onto that one bash request (the seam-level per-call override),
while rejected / cancelled / unavailable and the no-service / no-agent
paths each fail closed with their own error text and execute nothing. The
description teaches the flow only when the fields exist: retry the SAME
command once after a real denial, never preemptively; a rejected
escalation is final. No new session events: the attempt is an ordinary
tool/call, the decision is the approval audit pair, the outcome an
ordinary tool/result whose facts name the mode it ran under.

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

@@ -33,12 +33,16 @@
  * Commands run with the executor's full authority unless a sandboxing
  * executor (`@deepseek-ai/dsh-bash-sandbox`) confines them; per-call
  * allow/deny/ask policy is the `tools/pre-execute` waterfall — see
- * docs/architecture.md § Extension And Composition. A sandbox denial is a
- * RESULT FACT this layer renders as its own marker (the command RAN and the
- * kernel refused a file effect), and a sandbox RUNNER failure renders as a
- * sandbox problem, never a command failure. The escalation surface and the
- * per-session mode switching are staged follow-ups of the sandbox RFC
- * (docs/rfc/proposed/feature/2026-07-06-sandbox.md).
+ * docs/architecture.md § Extension And Composition. Under a sandboxing
+ * executor this plugin also advertises the ESCALATION surface
+ * (`sandbox_permissions`/`justification` — the sandbox RFC § Escalation,
+ * docs/rfc/proposed/feature/2026-07-06-sandbox.md): a command the
+ * sandbox denied may be retried once under a strictly wider mode, resolved
+ * through `ctx.approval` BEFORE anything executes and failing closed on every
+ * unanswerable path. The fields exist only when the mounted executor reports
+ * a confining default (`ctx.bash.sandboxMode`) — a lever is never advertised
+ * that the composition cannot honor. Per-session mode switching is the
+ * sandbox RFC's staged follow-up.
  *
  * @module @deepseek-ai/dsh-tool-bash
  */
@@ -46,9 +50,15 @@
 import type { Context } from 'cordis'
 import { isAbsolute, resolve as resolvePath } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { GenericCallView, TerminalCallView, ToolResult, ToolResultView } 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-approval'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { BashTaskId, OwnerToken } from '@deepseek-ai/dsh-bash'
 import type { BashRunResult, BashTask, CollectedOutput } from '@deepseek-ai/dsh-bash'
 
@@ -60,16 +70,12 @@ export const inject = ['tools', 'bash', 'systemPrompt']
  * validates parsed args against the SchemaSpec before `execute` runs (the
  * arg-validation RFC), so type/required/enum checks are already done and `args`
  * is the validated `InferArgs` shape here. What remains are value constraints
- * the DSL has no vocabulary for: non-empty strings and a positive, finite
- * timeout.
+ * the DSL has no vocabulary for: non-empty strings, a positive finite timeout,
+ * and the escalation pairing (`sandbox_permissions` and `justification` travel
+ * together — an approval prompt without a reason, or a reason driving nothing,
+ * is a malformed ask).
  */
-function validateBashArgs(args: {
-  command: string
-  description: string
-  timeoutMs?: number
-  workdir?: string
-  run_in_background?: boolean
-}): void {
+function validateBashArgs(args: BashToolArgs): void {
   if (args.command.trim().length === 0) {
     throw new Error('invalid command: expected a non-empty string')
   }
@@ -79,6 +85,15 @@ function validateBashArgs(args: {
   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')
+  }
 }
 
 /**
@@ -93,6 +108,75 @@ function validateTaskId(value: string): BashTaskId {
   return BashTaskId(value)
 }
 
+/**
+ * The bash tool's validated argument shape — the base parameters plus the two
+ * escalation fields, which are ADVERTISED only when the mounted executor
+ * reports a confining default mode (absent from the schema otherwise, so the
+ * SchemaSpec validator rejects them before `execute` ever sees one).
+ */
+interface BashToolArgs {
+  command: string
+  description: string
+  timeoutMs?: number
+  workdir?: string
+  run_in_background?: boolean
+  sandbox_permissions?: string
+  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
+ * teaching rides only when the mounted executor actually honors the fields —
+ * it names the ONE sanctioned exception to the base text's "do not retry
+ * another way" rule. Its deference clause ("If the session states approval
+ * prompts are disabled…") points at the approval plugin's never-policy prompt
+ * sentence by meaning, not by parsed wording — a rendezvous kept working by
+ * that sentence continuing to open with the approvals-disabled claim.
+ */
+function bashDescription(escalationModes: readonly SandboxMode[]): string {
+  const base = 'Execute a bash command (`bash -c`) and return its stdout/stderr. '
+    + 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — '
+    + 'pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. '
+    + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). '
+    + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
+    + 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; '
+    + 'poll it with `bash_output` and stop it with `bash_kill`.'
+  if (escalationModes.length === 0) return base
+  return base + ' Attempting a command the sandbox may deny is safe and expected: run it and read the '
+    + 'marker rather than assuming the denial. When a command IS denied and a wider mode would let it '
+    + 'succeed, escalate immediately in the SAME turn — the ONE sanctioned exception to a denial: retry '
+    + 'the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) '
+    + 'plus a one-sentence `justification`. Do not detour through chat to ask permission first — the '
+    + 'approval prompt raised by that retry IS how the user consents. If the session states approval '
+    + 'prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. '
+    + 'Never escalate speculatively: ground the request in a real denial — normally the one THIS command '
+    + 'just hit; escalating up front is fine only when this session already denied the same access. '
+    + 'A rejected escalation is final for THAT command — stop and explain, never work around '
+    + 'it — but it does not forbid attempting or escalating other commands later.'
+}
+
 /** Append the truncation notice (with the full-output spill path) to a stream's text. */
 function streamText(output: CollectedOutput): string {
   if (!output.truncated) return output.text
@@ -105,9 +189,15 @@ function streamText(output: CollectedOutput): string {
  * errored — the model decides how to react; only infrastructure failures
  * (spawn errors, aborts) surface as isError results.
  * @param result - the completed foreground run from the executor.
+ * @param escalationModes - the escalation targets this composition advertises;
+ *   non-empty adds the same-turn escalation hint after a denial marker
+ *   (default `[]`: no hint).
  * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
  */
-export function renderResult(result: BashRunResult): string {
+export function renderResult(
+  result: BashRunResult,
+  escalationModes: readonly SandboxMode[] = [],
+): string {
   const out = streamText(result.stdout)
   const err = streamText(result.stderr)
 
@@ -125,6 +215,13 @@ export function renderResult(result: BashRunResult): string {
   // 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]`)
+    // 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]')
+    }
   }
   // Timeout is reported independently of how the process actually ended: a
   // command can trap SIGTERM and exit 0 after our timer fired (e.g.
@@ -366,15 +463,73 @@ export function apply(ctx: Context): void {
     }
   })
 
+  // The escalation surface exists exactly when the mounted executor confines
+  // under a default that has a strictly wider mode to escalate to — a lever
+  // is never advertised that the composition cannot honor. Registration time
+  // is the right read: the executor's default is config-fixed for its
+  // lifetime, and an executor swap restarts this fiber (static inject) and
+  // re-registers the schema.
+  const defaultMode = ctx.bash.sandboxMode
+  const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS
+
+  /**
+   * 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.
+   */
+  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, or a `danger-full-access`
+    // default with nothing wider) 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.
+    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, 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 = 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 this executor's wider
+      // ladder; the cast records that validated fact.
+      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')
+    }
+  }
+
   ctx.tools.register(defineTool({
     name: 'bash',
-    description: 'Execute a bash command (`bash -c`) and return its stdout/stderr. '
-      + 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — '
-      + 'pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. '
-      + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). '
-      + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
-      + 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; '
-      + 'poll it with `bash_output` and stop it with `bash_kill`.',
+    description: bashDescription(escalationModes),
     parameters: {
       command: { type: 'string', required: true, description: 'The bash command to execute.' },
       description: {
@@ -387,12 +542,31 @@ export function apply(ctx: Context): void {
       timeoutMs: { type: 'number', description: 'Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry.' },
       workdir: { type: 'string', description: 'Working directory for this command. Defaults to the session workspace; a relative path is resolved against it.' },
       run_in_background: { type: 'boolean', description: 'Run in the background and return a task id immediately. No timeout applies.' },
+      ...escalationModes.length > 0 ? {
+        sandbox_permissions: {
+          type: 'string' as const,
+          enum: [...escalationModes],
+          description: 'The wider sandbox mode this command needs. Only valid as a one-shot retry '
+            + 'of a command the sandbox just denied; requires justification and user approval.',
+        },
+        justification: {
+          type: 'string' as const,
+          description: 'Required with sandbox_permissions: one sentence for the user explaining '
+            + 'why this exact command needs the wider access.',
+        },
+      } : {},
     },
-    async execute(args, exec) {
+    async execute(args: BashToolArgs, exec) {
       validateBashArgs(args)
       // `description` is display/logging metadata only (surfaced to UIs via
       // the tool/call session event); it is intentionally NOT forwarded to
       // ctx.bash and has no effect on execution.
+      // An escalating call resolves approval BEFORE anything executes; every
+      // non-grant outcome throws its distinct error text and runs nothing.
+      // (validateBashArgs pinned the pairing, so the double narrow is exact.)
+      const sandboxMode = args.sandbox_permissions !== undefined && args.justification !== undefined
+        ? await approveEscalation(args.sandbox_permissions, args.justification, exec)
+        : undefined
       // Default the workdir to the calling agent's session cwd so each ACP
       // session runs in its own workspace (see resolveWorkdir); an explicit
       // model workdir still wins.
@@ -402,6 +576,7 @@ export function apply(ctx: Context): void {
         ...workdir !== undefined ? { workdir } : {},
         ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
         ...exec.signal ? { signal: exec.signal } : {},
+        ...sandboxMode !== undefined ? { sandboxMode } : {},
       }
       if (args.run_in_background === true) {
         // Stamp the owner token (the agent's session id) onto the spec so the
@@ -413,7 +588,7 @@ export function apply(ctx: Context): void {
       }
       const result = await ctx.bash.run(ctx.bash.resolve(request))
       if (result.aborted) throw new Error('command aborted')
-      return [{ type: 'text', text: renderResult(result) }]
+      return [{ type: 'text', text: renderResult(result, escalationModes) }]
     },
     presentCall: presentBashCall,
     presentResult: presentBashResult,
@@ -446,10 +621,14 @@ export function apply(ctx: Context): void {
         // error; a settled task's read carries the marker instead.
         text += `\n[sandbox: the sandbox runner itself failed under ${read.task.sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`
       } else if (read.task.sandbox?.denied) {
-        // Mirrors the foreground result marker. 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.
+        // Mirrors the foreground result marker (and its same-turn escalation
+        // 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]`
+        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]'
+        }
       }
       return Promise.resolve([{ type: 'text', text }])
     },