Merge remote-tracking branch 'origin/master' into codex/enforce-tool-cancellation

# Conflicts:
#	docs/cookbook/adding-a-tool.i18n.yaml
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	packages/bash/tool-bash/src/index.ts
#	packages/core/agent-loop/README.md
#	packages/core/tools/README.md
#	packages/core/tools/tests/scoped.spec.ts
#	packages/fs/tool-fs-search/tests/tools.spec.ts
#	website/zh-CN/api/harness/events.md
#	website/zh-CN/api/harness/tools.md

packages/fs/tool-fs/package.json

@@ -28,9 +28,12 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-fs": "^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-session": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-user-approval": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
@@ -42,9 +45,12 @@
     "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/fs/tool-fs/src/edit.ts

@@ -13,6 +13,7 @@ import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
+import type { FsSandboxSurface } from './sandbox.ts'
 
 /** Validated `edit` arguments after defaulting. */
 interface EditInput {
@@ -22,6 +23,20 @@ interface EditInput {
   replaceAll: boolean
 }
 
+/**
+ * The `edit` tool's validated argument shape: the base parameters plus the two
+ * escalation fields, advertised only under a confining `ctx.fs` (absent from
+ * the schema otherwise, so the validator rejects them before `execute`).
+ */
+interface EditToolArgs {
+  file_path: string
+  old_string: string
+  new_string: string
+  replace_all?: boolean
+  sandbox_permissions?: string
+  justification?: string
+}
+
 /**
  * Validate value constraints the schema DSL can't express: a non-blank
  * `file_path`, a non-empty `old_string`, and `old_string !== new_string`
@@ -56,8 +71,9 @@ export function formatEditOutput(displayPath: string, replaceAll: boolean): stri
 /**
  * Register the `edit` tool and its system-prompt guidance.
  * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ * @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
  */
-export function applyEditTool(ctx: Context): void {
+export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
   ctx.systemPrompt.section({
     name: 'tool:edit',
     order: 102,
@@ -72,20 +88,31 @@ export function applyEditTool(ctx: Context): void {
       old_string: { type: 'string', required: true, description: 'Literal text to replace. Must match exactly.' },
       new_string: { type: 'string', required: true, description: 'Literal replacement text. Use an empty string to delete the match.' },
       replace_all: { type: 'boolean', description: 'Replace all matches. Defaults to false; when false, old_string must appear exactly once.' },
+      ...sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {},
     },
-    async execute(args, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
+    async execute(args: EditToolArgs, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseEditArgs(args)
+      // Resolve the per-call sandbox mode (escalation grant > session override
+      // > backend default) BEFORE anything executes.
+      const sandboxMode = await sandbox.stampMode('edit', args, exec)
       const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
       // Single-slot decision: the policy plugin returns { version: vObserved } or
       // throws FS_NOT_OBSERVED; the bare default is undefined (unconditional edit).
       // No stat — the bare default never manufactures a version basis.
       const intent = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)
-      const outcome = await ctx.fs.editText(
-        target,
-        { oldString: input.oldString, newString: input.newString, replaceAll: input.replaceAll },
-        intent,
-        exec.signal,
-      )
+      let outcome
+      try {
+        outcome = await ctx.fs.editText(
+          target,
+          { oldString: input.oldString, newString: input.newString, replaceAll: input.replaceAll },
+          intent,
+          exec.signal,
+          sandboxMode,
+        )
+      } catch (error: unknown) {
+        // A sandbox denial becomes the shared [sandbox: …] marker; any other error passes through.
+        throw sandbox.mapError(error, sandboxMode)
+      }
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
       // An edit necessarily changes content, so result metadata carries at least one applied hunk.

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

@@ -7,10 +7,12 @@
 
 import type { Context } from 'cordis'
 import z from 'schemastery'
+import type {} from '@deepseek-ai/dsh-user-approval'
 import { applyReadTool, READ_LIMIT, STREAM_MIN_SIZE } from './read.ts'
 import { applyWriteTool } from './write.ts'
 import { applyEditTool } from './edit.ts'
 import { READ_MAX_BYTES, READ_MAX_LINE_LENGTH } from './read-render.ts'
+import { FsSandboxSurface } from './sandbox.ts'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'tool-fs'
@@ -61,6 +63,10 @@ export function apply(ctx: Context, config: Config): void {
     maxBytes: resolved.readMaxBytes,
     streamMinSize: resolved.readStreamMinSize,
   })
-  applyWriteTool(ctx)
-  applyEditTool(ctx)
+  // One escalation surface shared by both mutating tools: advertisement gating,
+  // per-call mode stamping, and denial-marker mapping, all keyed off whether
+  // the mounted ctx.fs confines (ctx.fs.sandboxMode).
+  const sandbox = new FsSandboxSurface(ctx)
+  applyWriteTool(ctx, sandbox)
+  applyEditTool(ctx, sandbox)
 }

packages/fs/tool-fs/src/sandbox.ts

@@ -0,0 +1,135 @@
+/**
+ * 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,
+        signal: exec.signal,
+      },
+    )
+  }
+
+  /**
+   * Map a thrown provider error for the model: a `FS_SANDBOX_DENIED` becomes a
+   * `FsError` whose text is the shared `[sandbox: …]` denial marker plus the
+   * same-turn escalation hint, so a policy denial reads identically to bash's
+   * WHILE keeping the structured `FS_SANDBOX_DENIED` code — `ToolRegistry`
+   * populates `result.error` only for `HarnessError` instances, so a plain
+   * `Error` would strip the code retry/observers key off. 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 `FsError` 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 FsError(`${sandboxDenialMarker(mode)}\n${escalationHintMarker('operation')}`, 'FS_SANDBOX_DENIED', { cause: error })
+  }
+}

packages/fs/tool-fs/src/write.ts

@@ -14,6 +14,7 @@ import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
+import type { FsSandboxSurface } from './sandbox.ts'
 
 /**
  * Validate value constraints the schema DSL can't express: only a non-blank
@@ -41,11 +42,24 @@ ${verb} file
 </content>`
 }
 
+/**
+ * The `write` tool's validated argument shape: the base parameters plus the
+ * two escalation fields, advertised only under a confining `ctx.fs` (absent
+ * from the schema otherwise, so the validator rejects them before `execute`).
+ */
+interface WriteToolArgs {
+  file_path: string
+  content: string
+  sandbox_permissions?: string
+  justification?: string
+}
+
 /**
  * Register the `write` tool and its system-prompt guidance.
  * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ * @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
  */
-export function applyWriteTool(ctx: Context): void {
+export function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void {
   ctx.systemPrompt.section({
     name: 'tool:write',
     order: 101,
@@ -58,14 +72,26 @@ export function applyWriteTool(ctx: Context): void {
     parameters: {
       file_path: { type: 'string', required: true, description: 'Path to write, resolved by the filesystem backend.' },
       content: { type: 'string', required: true, description: 'Full UTF-8 text content to write.' },
+      ...sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {},
     },
-    async execute(args, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
+    async execute(args: WriteToolArgs, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseWriteArgs(args)
+      // Resolve the per-call sandbox mode (escalation grant > session override
+      // > backend default) BEFORE anything executes; an escalating call
+      // resolves approval here and throws its distinct text on any non-grant.
+      const sandboxMode = await sandbox.stampMode('write', args, exec)
       const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
       // Single-slot decision: the policy plugin produces createIfAbsent/
       // replaceIfVersion; the bare default is undefined (unconditional). No stat.
       const intent = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)
-      const outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal)
+      let outcome: FsWriteOutcome
+      try {
+        outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal, sandboxMode)
+      } catch (error: unknown) {
+        // A sandbox denial becomes the shared [sandbox: …] marker (the model
+        // recognizes it from bash); any other error passes through.
+        throw sandbox.mapError(error, sandboxMode)
+      }
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
       // Overwrites carry applied hunks. Creates have no prior text, so result presentation uses

packages/fs/tool-fs/tests/tools.spec.ts

@@ -24,6 +24,8 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import { STREAM_MIN_SIZE } from '../src/read.ts'
 import { formatReadOutput } from '../src/read-render.ts'
 import type { FileReadOutcome } from '../src/read-render.ts'
+import ApprovalService from '@deepseek-ai/dsh-user-approval'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 
 const testToolSignal = new AbortController().signal
 
@@ -583,3 +585,163 @@ describe('read caps are plugin config', () => {
     expect('default' in ToolFs).toBe(false)
   })
 })
+
+describe('sandbox escalation surface (write/edit)', () => {
+  /** A confining fake `ctx.fs`: reports a default mode, records the per-call mode stamped, and can arm a sandbox denial. */
+  class SandboxingFakeFs extends FakeFs {
+    stamped: (SandboxMode | undefined)[] = []
+    override get sandboxMode(): SandboxMode {
+      return 'workspace-write'
+    }
+    override async writeText(
+      target: FsTarget,
+      content: string,
+      expected?: FsWriteIntent,
+      _signal?: AbortSignal,
+      sandboxMode?: SandboxMode,
+    ): Promise<FsWriteOutcome> {
+      this.stamped.push(sandboxMode)
+      return super.writeText(target, content, expected)
+    }
+    override async editText(
+      target: FsTarget,
+      edit: FsEditRequest,
+      expected?: { version: FsVersion },
+      _signal?: AbortSignal,
+      sandboxMode?: SandboxMode,
+    ): Promise<FsEditOutcome> {
+      this.stamped.push(sandboxMode)
+      return super.editText(target, edit, expected)
+    }
+  }
+
+  async function setupConfining(opts: { approval?: boolean } = {}) {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SandboxingFakeFs)
+    await ctx.plugin(FsPolicy)
+    if (opts.approval === true) await ctx.plugin(ApprovalService)
+    await ctx.plugin(ToolFs)
+    return { ctx, fs: ctx.fs as SandboxingFakeFs }
+  }
+
+  /** A fake agent whose session records appends (the approval audit surface), mid-turn, carrying the given events for the fold. */
+  function escalationAgent(events: Array<{ type: string; data?: Record<string, unknown> }> = []): object {
+    return {
+      id: 'agent-fs-esc',
+      session: {
+        header: { version: 0, id: 'sess-fs-esc', createdAt: 0 },
+        events: [{ type: 'turn/start' }, ...events],
+        append: (type: string, data: Record<string, unknown>) => { events.push({ type, data }) },
+      },
+    }
+  }
+
+  function fsSchema(ctx: Context, name: 'write' | 'edit') {
+    const schema = ctx.tools.schemas().find(s => s.name === name)
+    if (!schema) throw new Error(`${name} tool not registered`)
+    return schema as unknown as { parameters: { properties: Record<string, { enum?: string[] }> } }
+  }
+
+  it('advertises no escalation fields under a non-confining backend', async () => {
+    const { ctx } = await setup()
+    expect(ctx.fs.sandboxMode).toBeUndefined()
+    for (const name of ['write', 'edit'] as const) {
+      const props = fsSchema(ctx, name).parameters.properties
+      expect(props['sandbox_permissions']).toBeUndefined()
+      expect(props['justification']).toBeUndefined()
+    }
+  })
+
+  it('advertises the closed target vocabulary on write and edit under a confining backend', async () => {
+    const { ctx } = await setupConfining()
+    for (const name of ['write', 'edit'] as const) {
+      const props = fsSchema(ctx, name).parameters.properties
+      expect(props['sandbox_permissions']?.enum).toEqual(['workspace-write', 'danger-full-access'])
+      expect(props['justification']).toBeDefined()
+    }
+  })
+
+  it('a plain write stamps nothing (backend default) and no session override folds without one', async () => {
+    const { ctx, fs } = await setupConfining()
+    await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent())
+    expect(fs.stamped).toEqual([undefined])
+  })
+
+  it('a standing session override folds onto the stamp', async () => {
+    const { ctx, fs } = await setupConfining()
+    await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent([{ type: 'sandbox/mode', data: { mode: 'read-only' } }]))
+    expect(fs.stamped).toEqual(['read-only'])
+  })
+
+  it('a denied write maps to the shared marker plus the escalation hint (isError)', async () => {
+    const { ctx, fs } = await setupConfining()
+    fs.rejectWith = new FsError('denied', 'FS_SANDBOX_DENIED')
+    const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent())
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(text(result)).toContain('retry this exact operation once with sandbox_permissions')
+  })
+
+  it('a non-FS_SANDBOX_DENIED provider error passes through unchanged', async () => {
+    const { ctx, fs } = await setupConfining()
+    fs.rejectWith = new FsError('boom', 'FS_IO_ERROR')
+    const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent())
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('boom')
+    expect(text(result)).not.toContain('[sandbox:')
+  })
+
+  it('an approved escalation stamps the granted mode onto that write', async () => {
+    const { ctx, fs } = await setupConfining({ approval: true })
+    ctx.on('approval/request', () => Promise.resolve('allowed-once' as const))
+    // Pass a signal so the escalation ask forwards it to the approval request
+    // (the request rides the tool-execution abort signal).
+    await ctx.tools.execute({
+      callId: CallId('call-fs-esc-grant'),
+      name: 'write',
+      arguments: { file_path: 'a.txt', content: 'x', sandbox_permissions: 'danger-full-access', justification: 'the test needs it' },
+      agent: escalationAgent() as never,
+      signal: new AbortController().signal,
+    })
+    expect(fs.stamped).toEqual(['danger-full-access'])
+  })
+
+  it('a rejected escalation fails closed with its own text and never mutates', async () => {
+    const { ctx, fs } = await setupConfining({ approval: true })
+    ctx.on('approval/request', () => Promise.resolve('rejected' as const))
+    const result = await call(ctx, 'edit', { file_path: 'a.txt', old_string: 'x', new_string: 'y', sandbox_permissions: 'danger-full-access', justification: 'the test needs it' }, escalationAgent())
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('the user rejected escalating this operation to "danger-full-access"')
+    expect(fs.stamped).toEqual([])
+  })
+
+  it('escalation without an approval service fails closed', async () => {
+    const { ctx } = await setupConfining()
+    const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'x', sandbox_permissions: 'danger-full-access', justification: 'why' }, escalationAgent())
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('no approval service is composed')
+  })
+
+  it('escalation with an approval service but no agent fails closed', async () => {
+    const { ctx } = await setupConfining({ approval: true })
+    const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'x', sandbox_permissions: 'danger-full-access', justification: 'why' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('no agent to route it through')
+  })
+
+  it('rejects the escalation argument pairing (one field without the other)', async () => {
+    const { ctx } = await setupConfining()
+    const missing = await call(ctx, 'write', { file_path: 'a.txt', content: 'x', sandbox_permissions: 'workspace-write' }, escalationAgent())
+    expect(missing.isError).toBe(true)
+    expect(text(missing)).toContain('sandbox_permissions requires a justification')
+  })
+
+  it('sandbox_permissions under a non-confining backend fails closed (unadvertised field still reaches execute)', async () => {
+    const { ctx } = await setup()
+    const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'x', sandbox_permissions: 'workspace-write', justification: 'why' }, escalationAgent())
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('not available in this composition')
+  })
+})

packages/fs/tool-fs/tsconfig.json

@@ -13,6 +13,9 @@
     { "path": "../../core/tools" },
     { "path": "../../core/system-prompt" },
     { "path": "../fs" },
-    { "path": "../fs-policy" }
+    { "path": "../fs-policy" },
+    { "path": "../../sandbox/sandbox" },
+    { "path": "../../sandbox/sandbox-policy" },
+    { "path": "../../ui/user-approval" }
   ]
 }