feat(sandbox-policy): expose current file policy

packages/sandbox/sandbox-policy/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-policy/README.md
-README.md: dca54330bc888af9ecac21aa92019d8a2b0140bd
-README.zh.md: a201d48c81f563fc3d85495e964bb67432517a3c
+README.md: 3258492ba80102ec96d37baa5e4989b1c396cf15
+README.zh.md: 4bb7e3b1321620413b81414d60f7b2d02df588c6

packages/sandbox/sandbox-policy/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The single owner of sandbox-policy resolution: the deployment's default [`SandboxMode`](../sandbox/README.md) and fallback root, plus each session's durable mode override and immutable workspace root. Every enforcing capability family receives one resolved mode-and-root policy per call.
+The single owner of sandbox-policy resolution: the deployment's default [`SandboxMode`](../sandbox/README.md) and fallback root, plus each session's durable mode override and immutable workspace root. Every enforcing capability family receives one resolved mode-and-root policy per call, and the model receives that same effective policy before each request.
 
 ## Why a shared home
 
@@ -17,23 +17,50 @@ Two families enforce the same mode vocabulary: the sandboxed bash executor (`@de
 
 - `ctx.sandboxPolicy.resolve({ session?, mode? })` — resolves one complete per-call policy. An explicit approved mode outranks the session's last `sandbox/mode` event, which outranks `defaultMode`; the session's immutable `cwd` is canonicalized with filesystem semantics before becoming `workspaceRoot`, otherwise the configured fallback applies. Canonicalization precedes lexical normalization so `symlink/..` agrees with process working-directory resolution.
 - `ctx.sandboxPolicy.defaultMode` / `ctx.sandboxPolicy.workspaceRoot` — the deployment default and fallback root used by `resolve()`.
+- `sandbox:policy` — a request-time system-prompt section derived from `resolve({ session })`. It states the current file-effect mode, its consequences, and every canonical writable root under `workspace-write`; it does not claim host permissions, sandbox-backend readiness, or network/process restrictions.
 - `effectiveSandboxMode(events)` — the pure fold of a session's `sandbox/mode` events (the last switch wins, or `undefined`), used inside `resolve()`.
 - `setSandboxMode(session, mode)` — THE write path for a per-session override: appends exactly one `sandbox/mode` event. The switch IS its event; nothing mutates the mode out of band.
 - `SANDBOX_MODES` — every mode, for option advertisement and runtime validation.
 
-The optional `./invariant` companion rejects a forged durable `sandbox/mode` event whose value falls outside that closed vocabulary; Session and its companion own the surrounding storage and core execution-enclosure rules.
+The optional `./invariant` companion rejects a forged durable `sandbox/mode` event whose value falls outside that closed vocabulary; Session and its companion own the surrounding storage and core execution-enclosure rules. The rendered section is logged inside `request/header`, so the exact effective policy remains reconstructable without another event or an in-memory “last told” mirror.
 
 ## The per-session store
 
-A runtime switch is one log-only `sandbox/mode` event on the session it applies to. `effective = explicit grant ?? fold(events) ?? deployment default`, so an override survives restart by replay and two sessions never see each other's state. Workspace identity does not need another event: the immutable `SessionHeader.cwd` recorded at creation is the root for every call in that session. The event is log-only (the `approval/*` precedent): the model learns the mode from the enforcing tools' denial markers, never from the event.
+A runtime switch is one log-only `sandbox/mode` event on the session it applies to. `effective = explicit grant ?? fold(events) ?? deployment default`, so an override survives restart by replay and two sessions never see each other's state. Workspace identity does not need another event: the immutable `SessionHeader.cwd` recorded at creation is the root for every call in that session. The event stays log-only; the next request assembles the current section from the fold before any tool call.
 
 ## Model Experience
 
-Indirectly, through `dsh-tool-bash` and `dsh-tool-fs`, which render the effective mode this service holds in their `[sandbox: …]` denial markers and escalation prompts; the `sandbox/mode` event itself never reaches the model.
+### Current file sandbox policy
+
+#### What the model sees
+
+One `sandbox:policy` system section on every agent request. The section states only DSH file-effect policy; tool schemas remain their owners' surfaces, approval policy remains `dsh-user-approval`'s section, and plan guidance remains `dsh-plan-mode`'s section.
+
+##### Read-only
+
+```markdown
+Current DSH file sandbox policy: read-only. Ordinary file writes, edits, and file-mutating shell effects are denied; required sinks such as `/dev/null` may remain writable. Host OS permissions and sandbox-backend availability may restrict operations further. This policy does not govern network or process access.
+```
+
+##### Workspace-write
+
+```markdown
+Current DSH file sandbox policy: workspace-write. File writes, edits, and file-mutating shell effects are limited to these canonical writable roots: "<workspace root>", "<temporary root>". Host OS permissions and sandbox-backend availability may restrict operations further. This policy does not govern network or process access.
+```
+
+##### Danger-full-access
+
+```markdown
+Current DSH file sandbox policy: danger-full-access. The DSH file sandbox does not restrict file operations. Host OS permissions and other policies still apply. This policy does not govern network or process access.
+```
+
+#### Token effect
+
+One concise system section per request. `workspace-write` additionally lists the canonical session workspace root plus the canonical `/tmp` and platform temporary roots, deduplicated when they identify the same directory.
 
 #### KV Cache effect
 
-No direct invalidation; the named consumers own any request-prefix changes, and the mode is deliberately absent from the prompt.
+The request prefix is byte-stable while the session mode and immutable workspace root stay unchanged. A mode switch changes the section on the next request; the resulting `request/header` records the new prefix.
 
 ## Known Limitations and Deferred Work
 

packages/sandbox/sandbox-policy/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-沙箱策略解析的唯一归属位置：部署默认 [`SandboxMode`](../sandbox/README.md) 与回退根目录，加上每个会话的持久模式覆盖和不可变工作区根目录。每个强制执行策略的能力家族在每次调用时都会收到一项解析完成的模式与根目录策略。
+沙箱策略解析的唯一归属位置：部署默认 [`SandboxMode`](../sandbox/README.md) 与回退根目录，加上每个会话的持久模式覆盖和不可变工作区根目录。每个强制执行策略的能力家族在每次调用时都会收到一项解析完成的模式与根目录策略，模型也会在每次请求前收到同一项有效策略。
 
 ## 为何需要共享归属位置
 
@@ -17,23 +17,50 @@
 
 - `ctx.sandboxPolicy.resolve({ session?, mode? })`：解析一项完整的逐调用策略。显式批准的模式优先于会话最后一条 `sandbox/mode` 事件，后者又优先于 `defaultMode`；会话不可变的 `cwd` 会先按文件系统语义规范化，再成为 `workspaceRoot`，否则使用配置的回退值。规范化先于词法归一化，因此 `symlink/..` 与进程工作目录解析保持一致。
 - `ctx.sandboxPolicy.defaultMode`／`ctx.sandboxPolicy.workspaceRoot`：`resolve()` 使用的部署默认值与回退根目录。
+- `sandbox:policy`：由 `resolve({ session })` 派生的请求时系统提示词段落。它说明当前文件操作模式及其后果，并列出 `workspace-write` 下所有规范化的可写根目录；不会声称主机权限、沙箱后端就绪状态或网络／进程限制。
 - `effectiveSandboxMode(events)`：会话 `sandbox/mode` 事件的纯 fold（最后一次切换胜出，没有则为 `undefined`），在 `resolve()` 内使用。
 - `setSandboxMode(session, mode)`：逐会话覆盖的唯一写入路径：恰好追加一条 `sandbox/mode` 事件。切换本身就是事件；不会在带外修改模式。
 - `SANDBOX_MODES`：所有模式，用于选项展示与运行时验证。
 
-可选的 `./invariant` 配套组件会拒绝伪造的持久 `sandbox/mode` 事件，只要其值不在该封闭词汇中；Session 与其配套组件负责相关存储与核心执行封闭规则。
+可选的 `./invariant` 配套组件会拒绝伪造的持久 `sandbox/mode` 事件，只要其值不在该封闭词汇中；Session 与其配套组件负责相关存储与核心执行封闭规则。渲染后的段落记录在 `request/header` 中，因此无需另一条事件或内存中的「上次告知」镜像，也能重建确切的有效策略。
 
 ## 逐会话存储
 
-运行时切换是在对应会话日志中追加的一条 `sandbox/mode` 事件。`effective = explicit grant ?? fold(events) ?? deployment default`，因此覆盖会通过回放跨重启保留，两个会话也绝不会看到彼此状态。工作区标识无需另一条事件：创建时记录的不可变 `SessionHeader.cwd` 是该会话每次调用使用的根。该事件只进入日志（沿用 `approval/*` 先例）：模型通过强制执行工具的拒绝标记获知模式，绝不会从事件获知。
+运行时切换是在对应会话日志中追加的一条 `sandbox/mode` 事件。`effective = explicit grant ?? fold(events) ?? deployment default`，因此覆盖会通过回放跨重启保留，两个会话也绝不会看到彼此状态。工作区标识无需另一条事件：创建时记录的不可变 `SessionHeader.cwd` 是该会话每次调用使用的根。该事件仍只进入日志；下一次请求会在任何工具调用发生前，根据 fold 组装当前段落。
 
 ## 模型体验
 
-通过 `dsh-tool-bash` 和 `dsh-tool-fs` 间接影响；它们会在 `[sandbox: …]` 拒绝标记和升权提示词中渲染该服务持有的有效模式，`sandbox/mode` 事件本身绝不会到达模型。
+### 当前文件沙箱策略
+
+#### 模型看到的内容
+
+每次 agent 请求都有一个 `sandbox:policy` 系统段落。该段落只说明 DSH 文件操作策略；工具 schema 仍由各自归属方管理，批准策略仍由 `dsh-user-approval` 的段落管理，计划引导仍由 `dsh-plan-mode` 的段落管理。
+
+##### 只读
+
+```markdown
+Current DSH file sandbox policy: read-only. Ordinary file writes, edits, and file-mutating shell effects are denied; required sinks such as `/dev/null` may remain writable. Host OS permissions and sandbox-backend availability may restrict operations further. This policy does not govern network or process access.
+```
+
+##### 工作区写入
+
+```markdown
+Current DSH file sandbox policy: workspace-write. File writes, edits, and file-mutating shell effects are limited to these canonical writable roots: "<workspace root>", "<temporary root>". Host OS permissions and sandbox-backend availability may restrict operations further. This policy does not govern network or process access.
+```
+
+##### 完全访问
+
+```markdown
+Current DSH file sandbox policy: danger-full-access. The DSH file sandbox does not restrict file operations. Host OS permissions and other policies still apply. This policy does not govern network or process access.
+```
+
+#### Token 影响
+
+每个请求增加一个简洁的系统段落。`workspace-write` 还会列出规范化的会话工作区根目录，以及规范化的 `/tmp` 与平台临时根目录；如果它们指向同一目录则去重。
 
 #### KV Cache 影响
 
-不会直接使 KV Cache 失效；请求前缀变更由上述消费方负责，且提示词有意不包含模式。
+只要会话模式与不可变工作区根目录不变，请求前缀就在字节层面保持稳定。模式切换会在下一次请求中改变该段落；生成的 `request/header` 会记录新的前缀。
 
 ## 已知限制与暂缓事项
 

packages/sandbox/sandbox-policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-sandbox-policy",
-  "description": "Per-call sandbox policy resolver (ctx.sandboxPolicy): deployment fallbacks plus each session's mode and workspace root, shared by every enforcing capability family",
+  "description": "Per-call sandbox policy resolver and current model context: deployment fallbacks plus each session's mode and workspace root, shared by every enforcing capability family",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -27,18 +27,22 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-sandbox": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/sandbox/sandbox-policy/src/index.ts

@@ -3,6 +3,9 @@
  * deployment's sandbox fallbacks plus per-session resolution: the file-effect
  * {@link SandboxMode}, the `workspace-write` root, and the override kit (the
  * `sandbox/mode` event, its fold, and its write path, from `./session-mode.ts`).
+ * Before each agent request, the owner also renders the resolved policy as the
+ * `sandbox:policy` system section; request headers therefore reconstruct the
+ * same mode and roots the enforcing consumers resolve.
  *
  * Both enforcing capability families read the SAME policy here: the sandboxed
  * bash executor (`@deepseek-ai/dsh-bash-sandbox`) and the sandboxed filesystem
@@ -17,8 +20,10 @@
 import { resolve as resolvePath } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import { canonicalPath, type SandboxExecutionPolicy, type SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type {} from '@deepseek-ai/dsh-agent'
+import { canonicalPath, writableRoots, type SandboxExecutionPolicy, type SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import type { Session } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-system-prompt'
 import { effectiveSandboxMode } from './session-mode.ts'
 
 export { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from './session-mode.ts'
@@ -28,6 +33,23 @@ function resolveWorkspaceRoot(path: string): string {
   return resolvePath(canonicalPath(path))
 }
 
+/** Render the current file-effect policy without claiming host or backend capabilities. */
+function renderPolicyContext(policy: SandboxExecutionPolicy): string {
+  switch (policy.mode) {
+    case 'read-only':
+      return 'Current DSH file sandbox policy: read-only. Ordinary file writes, edits, and file-mutating shell effects are denied; required sinks such as `/dev/null` may remain writable. Host OS permissions and sandbox-backend availability may restrict operations further. This policy does not govern network or process access.'
+    case 'workspace-write':
+      return `Current DSH file sandbox policy: workspace-write. File writes, edits, and file-mutating shell effects are limited to these canonical writable roots: ${writableRoots(policy).map(root => JSON.stringify(root)).join(', ')}. Host OS permissions and sandbox-backend availability may restrict operations further. This policy does not govern network or process access.`
+    case 'danger-full-access':
+      return 'Current DSH file sandbox policy: danger-full-access. The DSH file sandbox does not restrict file operations. Host OS permissions and other policies still apply. This policy does not govern network or process access.'
+    /* v8 ignore next 4 -- SandboxMode is a typed same-process closed union; this branch is only the static exhaustiveness guard. */
+    default: {
+      const mode: never = policy.mode
+      throw new Error(`unreachable sandbox mode: ${String(mode)}`)
+    }
+  }
+}
+
 declare module 'cordis' {
   interface Context {
     sandboxPolicy: SandboxPolicyService
@@ -61,9 +83,9 @@ export interface SandboxPolicyRequest {
 
 /**
  * The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment
- * default mode and fallback workspace root. Tool layers call {@link resolve}
- * for each execution so a session's mode log and immutable cwd travel together
- * to every enforcing capability.
+ * default mode, fallback workspace root, and current request-time policy
+ * section. Tool layers call {@link resolve} for each execution so a session's
+ * mode log and immutable cwd travel together to every enforcing capability.
  */
 export class SandboxPolicyService extends Service {
   // Inline schema call: the config catalog walks `static Config` statically.
@@ -86,6 +108,17 @@ export class SandboxPolicyService extends Service {
     // the process cwd is real branching, resolved absolute either way.
     this.defaultMode = config.mode as SandboxMode
     this.workspaceRoot = resolveWorkspaceRoot(config.workspaceRoot ?? process.cwd())
+
+    ctx.inject(['systemPrompt'], (scope: Context) => {
+      scope.systemPrompt.section({
+        name: 'sandbox:policy',
+        order: 110,
+        text: (context) => {
+          const session = context.agent?.session
+          return session === undefined ? '' : renderPolicyContext(this.resolve({ session }))
+        },
+      })
+    })
   }
 
   /**

packages/sandbox/sandbox-policy/tests/policy.spec.ts

@@ -9,8 +9,11 @@ import { tmpdir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { canonicalPath, writableRoots } from '@deepseek-ai/dsh-sandbox'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import SandboxPolicyService, { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 
 async function mounted(config: { mode?: 'read-only' | 'workspace-write' | 'danger-full-access'; workspaceRoot?: string } = {}) {
   const ctx = new Context()
@@ -28,6 +31,15 @@ function session(id: string, cwd?: string): Session {
   })
 }
 
+function agentFor(activeSession: Session): Agent {
+  return { session: activeSession } as unknown as Agent
+}
+
+async function policySection(ctx: Context, activeSession: Session): Promise<string | undefined> {
+  return (await ctx.systemPrompt.assemble({ agent: agentFor(activeSession) }))
+    .sections.find(section => section.name === 'sandbox:policy')?.text
+}
+
 describe('SandboxPolicyService', () => {
   it('defaults to read-only under the process cwd', async () => {
     const ctx = await mounted()
@@ -116,10 +128,70 @@ describe('SandboxPolicyService', () => {
 
   it('unregisters cleanly from a child fiber (HMR safety)', async () => {
     const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
     const fiber = await ctx.plugin(SandboxPolicyService, {})
     expect(ctx.sandboxPolicy).toBeDefined()
+    expect(await policySection(ctx, session('sess-hmr'))).toContain('read-only')
     await fiber.dispose()
     expect(ctx.get('sandboxPolicy')).toBeUndefined()
+    expect((await ctx.systemPrompt.assemble()).sections.find(section => section.name === 'sandbox:policy')).toBeUndefined()
+  })
+})
+
+describe('sandbox:policy request context', () => {
+  async function promptMounted(config: { mode?: 'read-only' | 'workspace-write' | 'danger-full-access'; workspaceRoot?: string } = {}): Promise<Context> {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(SandboxPolicyService, config)
+    return ctx
+  }
+
+  it('states the fresh read-only consequences before a tool attempt', async () => {
+    const ctx = await promptMounted()
+    const text = await policySection(ctx, session('sess-read-only', '/projects/read-only'))
+    expect(text).toBe('Current DSH file sandbox policy: read-only. Ordinary file writes, edits, and file-mutating shell effects are denied; required sinks such as `/dev/null` may remain writable. Host OS permissions and sandbox-backend availability may restrict operations further. This policy does not govern network or process access.')
+  })
+
+  it('states canonical workspace and temporary roots under workspace-write', async () => {
+    const ctx = await promptMounted({ mode: 'workspace-write', workspaceRoot: '/fallback' })
+    const active = session('sess-workspace-write', '/projects/../projects/current')
+    const policy = ctx.sandboxPolicy.resolve({ session: active })
+    const roots = writableRoots(policy)
+    const text = await policySection(ctx, active)
+    expect(text).toBe(`Current DSH file sandbox policy: workspace-write. File writes, edits, and file-mutating shell effects are limited to these canonical writable roots: ${roots.map(root => JSON.stringify(root)).join(', ')}. Host OS permissions and sandbox-backend availability may restrict operations further. This policy does not govern network or process access.`)
+    expect(roots[0]).toBe(resolve('/projects/current'))
+    expect(roots).toContain(canonicalPath('/tmp'))
+  })
+
+  it('states that danger-full-access adds no DSH file restriction without claiming wider authority', async () => {
+    const ctx = await promptMounted({ mode: 'danger-full-access' })
+    const text = await policySection(ctx, session('sess-danger', '/projects/current'))
+    expect(text).toBe('Current DSH file sandbox policy: danger-full-access. The DSH file sandbox does not restrict file operations. Host OS permissions and other policies still apply. This policy does not govern network or process access.')
+  })
+
+  it('reflects the latest durable switch on the next assembly and stays byte-stable otherwise', async () => {
+    const ctx = await promptMounted()
+    const active = session('sess-switch', '/projects/current')
+    const first = await policySection(ctx, active)
+    expect(await policySection(ctx, active)).toBe(first)
+
+    setSandboxMode(active, 'danger-full-access')
+    const danger = await policySection(ctx, active)
+    expect(danger).toContain('does not restrict file operations')
+    expect(await policySection(ctx, active)).toBe(danger)
+
+    setSandboxMode(active, 'workspace-write')
+    expect(await policySection(ctx, active)).toContain(JSON.stringify(resolve('/projects/current')))
+  })
+
+  it('reconstructs resumed policy from the session log and omits diagnostics without an agent', async () => {
+    const active = session('sess-resume', '/projects/current')
+    setSandboxMode(active, 'workspace-write')
+    const resumed = new Session(active.id, active.events, active.header)
+    const ctx = await promptMounted({ mode: 'read-only' })
+
+    expect(await policySection(ctx, resumed)).toContain('workspace-write')
+    expect((await ctx.systemPrompt.assemble()).sections.find(section => section.name === 'sandbox:policy')?.text).toBe('')
   })
 })
 

packages/sandbox/sandbox-policy/tsconfig.json

@@ -17,12 +17,18 @@
     {
       "path": "../../../vendor/schemastery"
     },
+    {
+      "path": "../../core/agent"
+    },
     {
       "path": "../sandbox"
     },
     {
       "path": "../../core/session"
     },
+    {
+      "path": "../../core/system-prompt"
+    },
     {
       "path": "../../support/invariants"
     }