From 0b1857904a3bad8e8e90ae832c755b936fe0cadf Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Wed, 22 Jul 2026 04:20:18 -0700
Subject: [PATCH] =?UTF-8?q?docs(i18n):=20add=20agent-scope=20and=20sandbox?=
 =?UTF-8?q?=20pairs=20=E2=80=94=20the=20batch=20is=20complete?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

最后两篇超长 RFC 经流式通道产出（代理会掐非流式长请求），v4 流水
线同一契约；至此 185 篇批次全部配对，pairing 194 对全绿。
---
 ...07-12-agent-scope-runtime-design.i18n.yaml |   6 +
 .../2026-07-12-agent-scope-runtime-design.md  |   2 +
 ...026-07-12-agent-scope-runtime-design.zh.md | 392 ++++++++++++++++++
 .../feature/2026-07-06-sandbox.i18n.yaml      |   6 +
 .../implemented/feature/2026-07-06-sandbox.md |   2 +
 .../feature/2026-07-06-sandbox.zh.md          | 212 ++++++++++
 scripts/translation-pairing.manifest.json     |   2 +
 7 files changed, 622 insertions(+)
 create mode 100644 docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
 create mode 100644 docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
 create mode 100644 docs/rfc/implemented/feature/2026-07-06-sandbox.i18n.yaml
 create mode 100644 docs/rfc/implemented/feature/2026-07-06-sandbox.zh.md

diff --git a/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
new file mode 100644
index 0000000000..5f2ed7f3bc
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+2026-07-12-agent-scope-runtime-design.md: 5fe44f2b0a79d91ce0e32a687ed183a5ffaef284
+2026-07-12-agent-scope-runtime-design.zh.md: 6e4f09e6780858c90b0cfbcf8709eca4c79ee414
diff --git a/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index 2c3126793f..5fe44f2b0a 100644
--- a/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
+++ b/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
@@ -1,5 +1,7 @@
 # RFC: Agent-scope runtime design and correctness
 
+English | [中文](2026-07-12-agent-scope-runtime-design.zh.md)
+
 Status: implemented
 
 ## Problem
diff --git a/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
new file mode 100644
index 0000000000..6e4f09e678
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -0,0 +1,392 @@
+# RFC：Agent 作用域运行时设计与正确性
+
+[English](2026-07-12-agent-scope-runtime-design.md) | 中文
+
+Status: implemented
+
+## 问题
+
+[agent 作用域契约](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份契约。
+
+主要的设计风险是为每个竞态条件引入第二套机制。独立的预留、就绪哨兵、取消中继、快照层和保护注册表可能镜像同一个事实，直到没有读者能分辨哪个才是权威的。这些机制还会诱使运行时把可信的类型化调用当作敌对的序列化边界来处理。
+
+实现需要足够的状态来维护真实的所有权和结算边界，但不能更多。正确性审查者必须能够从接受、发布到拆除，沿着一条事实链跟踪下去，而无需在并行的表示之间做调和。
+
+## 决策
+
+运行时对每个独立事实使用一种机制。作用域路由有一个不透明载体；每个活跃的注册表对象有一条入口记录；每个创建或恢复操作有一个事务；类型化的同进程调用借用 readonly 值；真实数据边界只物化一次；协作式 prompt 组装的结果即为权威；worker/进程代码仅在不同所有者确实可能竞争时才保留独立的终止态和静默态。
+
+该设计可概括为七项选择：
+
+| 问题 | 权威机制 |
+|---|---|
+| 选择全局加某个 agent 的注册 | 不透明作用域键与路由载体 |
+| 拥有一个活跃的 agent 或会话 | 由其 disposer 捕获的单条注册表入口 |
+| 协调创建/恢复 | 单个 `AgentCreationTransaction` |
+| 保护持久化、队列、模型或协议格式数据 | 在该边界处一次性物化 |
+| 在同一进程内传递类型化值 | Readonly 借用契约 |
+| 组合模型可见的 prompt 与工具表面 | 单个共享工具视图加权威的 assembly-waterfall 结果 |
+| 协调 subagent、worker 和进程关闭 | 单个取消信号加该边界独立的终止态/静默态事实 |
+
+本 RFC 余下部分按依赖顺序展开这些选择：Cordis 机制、作用域路由、创建与会话提交、工具与 prompt、subagent 与工作流，最后是可执行检查。
+
+[7 月 8 日 RFC](2026-07-08-agent-scope-contexts.md) 仍然是贡献者契约。独立的 [subagent 组合控制 RFC](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md) 拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
+
+## Cordis 模型：context、fiber、effect、receiver 与 waterfall
+
+理解实现需要五个 Cordis 概念。Context 选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；event receiver 选择监听器；waterfall（瀑布式事件）让监听器按顺序变换或否决一个操作。
+
+### Context 是贯穿单个服务图的所有权路径
+
+所有 agent 共享一个 Cordis 服务图。派生的 context 不会克隆 `ToolRegistry`、`SystemPrompt`、持久化或模型适配器；它改变的是：通过该 context 进行的注册如何被标记，以及哪些 effect 拥有其清理逻辑。
+
+`agent.ctx` 就是这样一个派生 context。服务调用仍然到达共享实例，而注册操作可以检查其调用 context 并将贡献存储在最近的作用域键下。普通的插件 context 不携带作用域键，因此注册到全局。
+
+### Fiber 与 effect 使清理成为结构性的
+
+Cordis fiber 是插件或子 context 被激活时创建的活跃实例。其状态记录该生命周期是 active、unloading、failed 还是 disposed。`ctx.effect()` 和 `ctx.on()` 返回 disposer，同时将这些 disposer 附加到注册所在的 fiber，因此卸载一个插件或 agent 作用域会移除通过该 context 注册的一切，无需单独的清单。
+
+vendor 中的 Cordis fiber 实现在任意 setup 或 `internal/plugin` 观察者运行之前就建立了所有权。可重入的卸载可以看到已启动的子 fiber 或 effect，拒绝卸载开始后添加的 effect，并通过一个公开的一次性 disposer 加入已启动的清理。拆除观察者被逐个隔离，因此一个回调无法阻止结构性清理。
+
+这些是框架生命周期保证，而非 agent 特有的策略。Agent 创建依赖它们，因为 setup 可以激活任意插件并同步重入所有者的 dispose。
+
+### Receiver 路由监听器；waterfall 组合决策
+
+Cordis 使用 dispatch receiver（`this`）过滤监听器，而 harness 的监听器需要一个显式的 agent、execution、request 或其他主体。`Scoped<T>` 标记作用域事件声明所期望的 receiver，但运行时载体刻意不暴露主体 API。
+
+因此，产品辅助函数构造载体并单独传递领域主体。这防止监听器路由变成另一套对象模型，并使事件签名在不了解载体内部的情况下也可理解。
+
+Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则否决或替换下游结果。Waterfall 驱动 prompt 组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
+
+## 作用域路由：一个不透明键选择一层
+
+scope 包实现了 Cordis 路由所需的最小对象。其载体仅持有一个组合的服务过滤器和作用域谓词，而包私有地记录不透明键，并单独暴露作用域 fiber 的静默 disposer。
+
+### 作用域标识使用对象标识
+
+`ScopeKey` 是一个按标识比较的不透明对象。Harness 使用活跃的 `Agent` 作为自身的键，但该原语与领域无关，支持其他作用域所有者。
+
+`createScope(parent, key)` 返回一个作用域，其 `ctx` 共享父级的服务，其 effect 被标记为该键。`scopeOf(ctx)` 读取最近的注册键。`scopeTarget(base, key)` 创建 event receiver，其过滤器保留 base receiver 的 Cordis 服务过滤器，然后接纳无作用域的监听器和具有该确切键的监听器。
+
+Receiver 是一个小型载体而非领域对象的透明代理。需要 agent 的代码接收显式的事件参数；需要注册所有权的代码接收 `agent.ctx`。
+
+### 注册表读取叠加一个精确映射
+
+作用域感知的注册表将全局贡献与按标识键索引的局部贡献分开存储。读取解析全局层和至多一个局部层；它从不遍历父级链。
+
+每个服务保留其领域规则。命名 prompt 值和工具使用局部遮蔽，工具限制在添加局部工具之前过滤全局，事件选择监听器受众而非注册数据。Scope 提供标识和所有权，而非通用的合并算法。
+
+### 融合 dispatch 辅助函数防止主体漂移
+
+`agentEvents(context, agent)` 构造 agent 的载体并注入同一个 agent 作为事件主体。Session、tool、approval、prompt 和 subagent 服务同样从它们已拥有的对象派生路由，而非接受一个无关的键。
+
+类型标记拒绝普通的裸 receiver 误用，开发环境不变式覆盖直接 JavaScript 或强制转换的 dispatch。主体保持显式，因为路由正确性和有用的事件数据是不同的关注点。
+
+## Agent 创建：一个事务拥有完整操作
+
+创建和恢复是一个具有多个阶段的异步生命周期，而非多个生命周期。`AgentCreationTransaction` 拥有调用方和工厂的活跃性、可选取消、私有资源、发布、回滚，以及每个所有者观察到的记忆化拆除。
+
+### 注册表入口是唯一的活跃标识记录
+
+AgentRegistry 和 SessionStore 各为每个活跃对象保留一条入口。入口持有稳定 ID、对象、作用域载体，以及属于该对象的少量发布或追加状态。
+
+detach 闭包捕获其确切入口。它仅在映射仍指向该入口时才删除，因此旧的 disposer 无法删除一个复用相同 ID 的后续对象。注册表不会重读可变的调用方对象来决定标识。
+
+没有预留 API。调用方提供的 ID 在最终入口时被接纳。并发的同 ID 操作可能都完成私有 setup；恰好一个最终 `enter()` 成功，每个失败者回滚其私有资源。前一个 disposer 达到静默后，顺序复用即为有效。
+
+### 事务在等待之前就拥有准备工作
+
+事务在持久化加载或 setup 可能挂起之前，就被安装到调用方的 Cordis context 和具体的 AgentLoop 工厂下。它还在公开操作结算之前观察可选的创建/恢复信号。
+
+创建准备一个新 Session。恢复加载并验证持久化的 Session，然后准备相同的活跃会话标识。两条路径随后构建作用域、agent 和 driver，并调用相同的 setup/发布算法。
+
+工厂存储具体的 trace 目标，但通过调用方绑定的 Cordis trace 调用它们。这保留了依赖来源和调用方所有权，而不堆叠 trace 代理。
+
+### Setup 是私有世界内的可信组合
+
+Setup 接收完整的子 context，可以等待插件激活。它可以注册工具、prompt 段、限制、监听器和其他 effect，但公开契约不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
+
+事务将异步加载和 setup 与停用进行竞争，而非无限等待外部代码拥有的 promise。如果取消或所有者卸载获胜，即使外部 promise 永不结算，公开创建也会在事务拥有的清理之后拒绝。
+
+### 发布有一条有序的提交路径
+
+发布按观察者所需的顺序接纳和宣告资源：
+
+1. 入口 session。
+2. 入口 agent。
+3. 宣告 `session/created`。
+4. 宣告 `agent/created`。
+5. 启用公开驱动。
+6. 发射 `agent/session-start`。
+7. 启动 driver。
+
+Agent 在两个注册表和创建通知都达成一致之前绝不驱动。同步监听器可以否决或 dispose 一个所有者；事务记录发布进行中，并等待该回调栈展开后再继续拆除。每个已开始的创建宣告在回滚期间都有匹配的销毁宣告。
+
+以下序列图隔离了非显而易见的竞态：同步创建监听器可以在发布调用栈仍拥有两个注册表入口时请求 dispose。拆除必须立即停用，但要等待该栈展开后才停止和分离任何东西。
+
+```mermaid
+sequenceDiagram
+  participant Tx as AgentCreationTransaction
+  participant Registries
+  participant Listener as Synchronous listener
+  participant Driver
+
+  Tx->>Tx: mark publication in progress
+  Tx->>Registries: announce agent/created
+  Registries->>Listener: invoke inside the same call stack
+  Listener->>Tx: dispose reentrantly
+  Tx->>Tx: deactivate, teardown waits for publication
+  Tx-->>Listener: disposal request accepted
+  Listener-->>Registries: return
+  Registries-->>Tx: announcement unwound
+  Tx->>Tx: resolve publication settlement
+  Tx->>Driver: stop and drain
+  Tx->>Registries: detach agent, then session
+  Tx->>Tx: dispose scope and resolve teardown
+```
+
+### 拆除在撤销注册之前保留工作
+
+每个拆除请求加入一条记忆化路径。顺序为：
+
+1. 停用创建或驱动，让同步发布完成。
+2. 停止并排空 driver，包括空闲注入刷新。
+3. 分离 agent。
+4. 分离 session。
+5. Dispose agent 作用域。
+6. 退役事务所有权追踪。
+
+此顺序让最终的 agent 和 session 事件能使用匹配的作用域监听器，并使持久化观察者在最终刷新完成前保持附加。作用域 dispose 放在最后，因为注册撤销是外部可见的生命期边界。
+
+## 会话追加：物化、验证、提交、通知
+
+会话事件跨越持久化边界，因此追加操作拥有其数据。算法的其余部分使用一条附加的入口和一个提交点。
+
+### 持久化数据一次性物化
+
+Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造函数或追加路径在存储前物化并验证它们，并暴露冻结的快照，因此后续调用方的修改无法改变持久化、回放或模型重建。
+
+这是一个真实的所有权边界：值离开调用方，可能被持久化，且必须在之后重建相同的请求。这比类型化的同进程回调或注册表定义有意更严格。
+
+### 提交前监听器可以否决；提交后观察者不能
+
+追加遵循一个序列：
+
+1. 物化持久化事件和表面意图。
+2. 声明 SessionEntry 并拒绝该入口上的重入追加。
+3. 解析作用域回调并运行内部不变式验证。
+4. 恰好推送一次；这是提交点。
+5. 逐个通知每个观察者，隔离同步和异步失败。
+6. 释放追加状态并兑现发布期间请求的 detach。
+
+没有观察者错误能让已提交的事件看起来未提交，一个坏的监听器也无法饿死后续监听器。Session 不变式在提交前暂存其转换，仅当同一事件到达被隔离的提交后观察者时才应用。
+
+`flush()` 启动每个持久化监听器并等待所有结果后再报告失败。这种有意的 all-settled 行为防止同步失败饿死另一个后端或最终刷新。
+
+## 信任边界：仅在所有权真正变更时复制
+
+运行时区分类型化的进程内契约与序列化及持久化边界。这是值和回调的主要简化规则。
+
+| 边界 | 所有权规则 |
+|---|---|
+| 同进程内的类型化服务/插件调用 | 借用 readonly 值和回调 |
+| 解析的插件配置或外部文件 | 验证语义和结构输入 |
+| 队列中的收件箱消息 | 在异步消费前物化 |
+| 模型/工具 JSON 输入或输出 | 在模型/工具边界处物化 |
+| 持久化会话或持久化数据 | 在提交前物化并验证 |
+| Worker、进程或协议格式消息 | 序列化、验证并拥有解码后的值 |
+
+测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产契约。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式（wire format）边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
+
+回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件契约隔离失败。
+
+## 工具与 prompt：单一视图、权威组装、已提交的结果
+
+工具展示和执行共享一个私有解析器。Prompt 组装仍然是可信的协作式组合：注册表提供有序输入，assembly waterfall 的返回值就是 agent loop（智能体循环）记录和发送的内容。执行仅在策略或结果结算必须单调时才使用独立的单向边界。
+
+### 一个解析器定义工具视图
+
+私有解析器应用当前展示模式、活跃的全局限制、精确的局部叠加和局部遮蔽。Schema、查找、执行、Code Mode SDK 生成和限制验证都使用该解析器或其限制前的全局名称视图。
+
+[subagent 组合控制 RFC](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md#tool-filtering-is-one-live-global-view-rule) 拥有用户可见的 allow/deny 语义。实现要求是一致性：被过滤掉的全局工具不能通过另一条查找路径仍可执行，局部遮蔽的定义就是被展示和执行的同一个定义。
+
+`ToolRestriction` 接受 readonly 的 allow/deny 名称并将其编译为内部集合。多个限制取交集。公开的 `visible()` 和 `knownNames()` 方法是不必要的，因为只有注册表需要中间视图。
+
+### 工具执行拥有标识和边界物化
+
+注册表为每次执行分配一个新的带品牌的 `Symbol` token。嵌套的 Code Mode 调用将外层 token 作为 `parent` 携带，因此结构化输出可以通过标识将内层捕获与其外层 `run_code` 结果关联。
+
+注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化契约，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
+
+参数在模型/工具 JSON 进入流水线时一次性物化。Pre-、around- 和 post-execute 监听器操作类型化的 execution 和决策。Call ID 关联、审批、单调守卫和 Code Mode 嵌套仍然是显式的关系检查。
+
+在最后一个 post-execute 监听器之后，注册表一次性物化并冻结被接受的最终结果。每个同步的 `tools/result` 观察者接收该确切的已提交对象，观察者失败被逐个隔离。外层流水线失败被规范化为已提交的错误结果，因此观察者可以丢弃针对同一权威边界的暂存工作。
+
+### Assembly waterfall 拥有最终的模型可见组合
+
+SystemPrompt 首先将全局加 agent 的段、变量和工具提供方解析为确定性的注册表贡献。作用域过滤的 `system-prompt/assemble` waterfall 随后可以重排、替换、添加或移除任何段、变量或 schema。其返回的组装结果即为权威；没有后续的恢复步骤，普通 prompt 段、工具定义或提供方结果上也没有终态元数据。
+
+这是一个可信的同进程扩展 seam，而非权限边界。修改 Code Mode 的 `run_code` schema 或 `tools:sdk` 指令，或结构化子级的捕获 schema 或指令的监听器，有责任在其返回的组装中保持协议的一致性。ToolRegistry 仍然保留 `run_code` 不受普通工具注册和限制影响，因为那些是注册表不变式，但 assembly 中间件仍然可以自由变换最终的模型可见表面。
+
+Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子级的精确作用域中，而 Code Mode 从同一个已解析的工具视图派生其传输和 SDK。第二套命名保护系统需要另一套所有权和碰撞规则来覆盖任意 schema 提供方（包括有意贡献重复名称的提供方），却不创建新的信任边界。
+
+### 结构化输出仅提交权威结果
+
+结构化输出将子作用域组合与两阶段执行提交相结合。子级在发布前注册其 `structured_output` 工具和指令；可信的 assembly 监听器可以变换这些普通贡献，并有责任在期望子级完成时保持协议。工具体验证候选值并按当前 `ToolExecution` 暂存，但成功捕获仅由不可变的 `tools/result` 观察决定。
+
+对于原生调用，观察者仅在该确切执行的最终结果成功时才删除暂存并提交其值。因此 post-execute 阻止或外层流水线失败不会留下已捕获的值。
+
+对于 Code Mode SDK 调用，内层成功结果记录 `{ parentToken, value }` 而非提交。观察者等待 token 匹配 `parentToken` 的 `run_code` 执行，仅在该外层最终结果也成功时才提交。程序失败、运行时中止或外层 post-policy 拒绝会丢弃待定值。
+
+一旦值处于待定或已提交状态，作用域单调守卫拒绝后续工具调用。提交后，普通串行的 `agent/turn-stop` 监听器在 continuation 和 steering（中途引导）已折叠之后返回停止决策。Schema 验证失败仍然是普通的 `INVALID_ARGS` 工具错误，子级可以在同一轮次内重试。
+
+纯 Code Mode 的注册表贡献从原生 wire schema 中省略 `structured_output`，并通过生成的 SDK 暴露它。Assembly waterfall 可以有意改变该展示；执行仍然针对子作用域定义进行验证，监听器拥有其创建的任何替代模型可见路由的一致性。
+
+### 三个执行边界有意设为单向
+
+Prompt 组装有意是协作式的，但三个执行事实在其可扩展阶段之后需要单向结算：
+
+| 边界 | 最终权力 | 为何普通监听器顺序不够 |
+|---|---|---|
+| 工具 pre-policy | 单调拒绝 | 后续监听器不得重新允许已被拒绝的调用 |
+| 工具结果 | 观察不可变的已提交结果 | 结构化输出必须仅提交实际逃出流水线的结果 |
+| 轮次 continuation | 在普通 continuation 折叠之后停止 | 已提交的终端输出必须结束轮次 |
+
+`ToolGuard` 是单调策略注册表。已提交的工具观察是上述被隔离的 `tools/result` 点。终端结构化输出监听普通串行的 `agent/turn-stop` 折叠，在正常 continuation 和 steering 决策之后；类型化的监听器契约不需要公开的 `strictSerial()` dispatcher。
+
+### Skill 和 approval 服务信任类型化调用方
+
+Skill 注册表定义和 approval 策略是 readonly 的同进程契约。它们的服务不克隆回调对象，也不防御交接后的回调替换。
+
+Skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用 agent 的工具视图路由目录，并精确 dispose 注册。Approval 仍然解析策略、观察取消、按 `request.agent` 路由 `approval/request`、记录持久化审计对，并隔离应答者和提交后观察者的失败。
+
+## Subagent：就绪即 start promise
+
+Subagent 启动有一次所有权转移。提供方拥有部分资源直到其 start promise 以一个就绪的已发布 run 兑现；调用方拥有返回的 run 并必须 dispose 它。
+
+### 服务契约有一个取消通道
+
+`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 仅在后端建立了它所承诺的子级之后才兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` 就绪 promise。
+
+`SubagentStartRequest.signal` 是必需的。中止它会在启动期间和就绪之后请求取消。`SubagentRun.dispose()` 也请求取消并等待静默。没有单独的公开 `run.cancel()` 通道。
+
+可选的 `sendMessage()` 支持能接受 steering 的活跃后端。可选的 `resume()` 返回 `Promise<SubagentRun>`，因为恢复的子级有相同的异步就绪边界。
+
+服务在调用提供方之前验证提供方能力和请求语义。提供方拒绝在拒绝逃出之前清理所有部分资源，且不发射 `subagent/start`/`subagent/end` 对。兑现之后，服务附加结果观察、发射作用域 start 并返回 run。提供方移除阻止后续 start，但不撤销提供方已接受的 run。
+
+### 进程内提供方复用核心事务
+
+Spawn 和 fork 共享一个进程内 driver。它通过 `parent.ctx` 创建子级，将必需的 signal 传入核心创建事务，并在未发布的 setup 期间安装 persona、工具限制和结构化输出贡献。
+
+提供方等待创建并仅返回已发布的 run。在交接时，核心创建分离其仅用于创建的 abort 监听器；提供方在安装活跃 run 监听器之前立即重新检查 signal，因此在那个窄窗口中的 abort 会 dispose 新句柄而非逃脱取消。父级拆除跟随子级，因为操作属于 `parent.ctx`；提供方卸载阻止新 start 但不成为已接受 run 的第二个撤销所有者。Run disposer 取消子级并等待 AgentHandle 的有序拆除。
+
+Spawn 使用空会话种子。Fork 使用经验证的已完成轮次前缀。对话种子仅改变历史，不导入作用域、工具、服务或权限。
+
+### ACP 提供方拥有进程直到就绪或清理
+
+ACP 提供方跨越真实的进程和协议格式边界，因此它保留验证、环境清洗、消息序列化、abort/进程竞争和 kill-to-exit 静默。
+
+Start 仅在 `initialize` 和 `newSession` 成功后才 resolve。Abort、spawn 失败、RPC 失败或无效启动响应在拒绝前回收进程。就绪后，result 映射 ACP prompt 结果和流式输出；dispose 请求取消、关闭连接并通过一条记忆化路径等待进程退出。
+
+## 工作流与 ACP UI：仅保留独立的异步事实
+
+Worker 和编辑器桥接比同进程注册表需要更多状态，因为消息、进程死亡和渲染可以独立结算。它们的状态围绕这些真实事实组织，而非重复的取消协议。
+
+### 工作流子级是待定 start 或已发布记录
+
+工作流宿主保持待定的提供方 start promise 和已发布的子级记录。子级仅在异步 `SubagentService.start()` 兑现时才从待定变为已发布；被拒绝的 start 清理其部分提供方工作且不产生子级生命周期对。
+
+一个宿主拥有的 AbortController 向待定和活跃子级提供必需的 signal。关闭工作流准入中止该 signal，因此没有重复的 `ChildCancel` worker RPC 或显式的宿主侧 `run.cancel()` 扇出。静默等待待定 start 和已发布子级 dispose 两者。
+
+Worker 边界仍然序列化请求和结果。宿主保留首个终端结果仲裁、精确的子级计数、worker 死亡处理、优雅终止、迟到/重复消息拒绝和有界清理，因为结果接收、worker 退出和子级静默是真正独立的事实。
+
+### 终端结果与物理清理保持分离
+
+工作流结果按公开优先级规则记录首个被接受的终端结果。该结果选定后清理可以继续：活跃子级仍需 dispose，worker 仍需终止，慢速外部后端可能超出配置的优雅期限。
+
+公开 dispose 在调用回调之前声明其记忆化 promise。Worker 死亡在处理任何排队的迟到子级请求之前关闭准入，合成缺失的生命周期结束，并启动子级/进程清理而不重写已声明的结果。
+
+### ACP prompt 结算不依赖渲染成功
+
+ACP UI 直接将 prompt 与其观察到的轮次关联。它不从 `logWatermark` 扫描，也不使用会话状态作为第二个调和预言机。
+
+Prompt 处理在 transcript（文本记录）渲染的 `finally` 中结算关联。渲染失败可以导致展示失败，但不能跳过 prompt 结算或让会话永久处于进行中状态。对同一持久化的调用方提供的会话 ID 的并发加载仍被排除，因为那是真实的持久化标识竞争，而非 UUID 碰撞问题。
+
+## 正确性强制
+
+该设计通过类型、运行时逃逸点、生成的契约和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
+
+### 类型使常规路径难以误用
+
+Readonly 契约描述借用的同进程值。`Scoped<T>` 标记 event receiver，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露就绪性。
+
+TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进程消息或持久化文件，因此运行时强制保留在这些逃逸点。
+
+### 运行时不变式覆盖跨服务事实
+
+不变式插件验证每个声明的作用域事件使用带标记的载体，以及暴露主体的事件族使用匹配的键。Session trace 验证在追加提交前暂存，并在同一事件提交后推进。
+
+该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的 prompt assembly 对象。这些检查会将组合契约变成推测性的运行时机制，却不保护真实的外部边界。
+
+### 生成的产物使公开契约保持对齐
+
+事件目录、服务目录、生产者/消费者矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 RFC](../process/2026-07-14-typescript-program-backed-semantic-gates.md) 拥有 Program 构造、语义事件发现和解析器生成规则。
+
+行为测试固定了作用域路由和 dispose、最终入口碰撞清理、发布回滚、有序静默、持久化前/后提交行为、跨展示和执行的活跃工具过滤、协作式 prompt 组装、原生和 Code Mode 中的结构化输出提交、异步 subagent 启动和信号取消、worker 终端仲裁、ACP 结算和进程拆除。
+
+## 曾考虑的替代方案
+
+[7 月 8 日 RFC](2026-07-08-agent-scope-contexts.md#alternatives-considered) 拥有公开扁平作用域契约的替代方案。此处的替代方案关注实现形态。
+
+### 使用透明代理作为作用域载体
+
+模拟主体的代理必须保持属性、可调用、可构造、私有字段、描述符和代理不变式行为，而监听器路由从不需要这些。一个小型不透明载体保持过滤器和键，而显式事件参数携带主体。
+
+### 在 setup 前预留 agent 和 session ID
+
+预留防止重复的私有 setup 工作，但需要跨服务能力、释放排序、废弃预留清理和已准备对象绑定。ID 由调用方提供，并发复用是调用方错误；最终入口可以选择赢家，而失败的事务干净地回滚。
+
+### 对每个类型化的同进程参数做快照
+
+通用复制防御有状态 getter 和违反 readonly 契约的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
+
+### 为就绪、取消和 dispose 提供独立控制器
+
+并行哨兵可能都镜像一个操作是否活跃。一个事务或 start promise 拥有操作；独立 promise 仅在发布展开、外部工作、终端结果和物理静默可以独立结算时才保留。
+
+### 保留同步 subagent start 加 `run.started`
+
+这将提供方接受与就绪分离，迫使每个消费方注册部分 run、附加结果观察、等待就绪并清理就绪失败。异步 start promise 使提供方到调用方的所有权转移本身成为就绪边界。
+
+### 在 assembly 之后恢复选定的 prompt 或工具贡献
+
+Waterfall 之后的恢复步骤会在文档化的协作式 seam 之后创建第二套组合规则。正确分配规范的存在或缺失还需要为任意工具 schema 提供方制定所有权和碰撞规则，而这些提供方的普通输出可能包含重复名称。作用域注册已经提供了所需的按 agent 隔离，可信的 assembly 监听器拥有其返回内容的协议一致性，因此命名恢复增加了机制却不建立独立边界。
+
+### 用同进程加固替代 worker/进程生命周期守卫
+
+Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化边界。首个结果仲裁、验证、环境清洗和静默进程清理即使在敌对的同进程回调机制不存在时仍然必要。
+
+## 后果
+
+实现更小，其证明与所有权图具有相同的形状。一个键选择一层，一条入口拥有一个活跃注册表对象，一个事务拥有创建，一个解析器拥有工具视图，一个异步 promise 转移 subagent 所有权。
+
+### 设计保证的内容
+
+- 作用域贡献仅在其精确的 agent 视图中可见，并随该作用域一起 dispose。
+- 创建和恢复不暴露部分配置的句柄；最终入口的失败者和发布失败清理每个已准备的资源。
+- Dispose 在 driver 排空和最终会话工作期间保留作用域监听器和持久化，然后撤销作用域。
+- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 契约。
+- ToolRegistry 的展示、查找和执行在专家 assembly 变换之前解析相同的活跃视图，已提交的结果有一个不可变的观察点。
+- 注册表贡献是确定性输入，而可信的 assembly waterfall 拥有最终的模型可见组合。
+- Subagent start 仅返回就绪的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的静默契约。
+- Worker/进程结果优先级和清理在死亡、迟到消息和有界拆除下保持正确。
+
+### 代价与局限
+
+作用域感知服务仍然维护全局和按标识键索引的映射，操作必须显式携带其真实 agent。异步创建/恢复和 subagent start 要求调用方等待所有权转移并 dispose 返回的句柄。
+
+可信的 `system-prompt/assemble` 监听器可以移除或替换 Code Mode 和结构化输出协议片段。这是有意为之：监听器拥有最终组合，必须保持部署期望仍可用的任何协议。
+
+该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 契约的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
+
+[安全与权限非目标](2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)仍然是根本性的。这些机制证明注册组合、发布和生命期所有权；它们不证明隔离或父到子的非升级。
diff --git a/docs/rfc/implemented/feature/2026-07-06-sandbox.i18n.yaml b/docs/rfc/implemented/feature/2026-07-06-sandbox.i18n.yaml
new file mode 100644
index 0000000000..8c97f0b5ee
--- /dev/null
+++ b/docs/rfc/implemented/feature/2026-07-06-sandbox.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+2026-07-06-sandbox.md: 29985b9336e7a190c90dc0e9c3b3aa78b6197e8e
+2026-07-06-sandbox.zh.md: 4285ae4ceb81ee57dc3ab3d51467f9267743e06e
diff --git a/docs/rfc/implemented/feature/2026-07-06-sandbox.md b/docs/rfc/implemented/feature/2026-07-06-sandbox.md
index 28f2066ee9..29985b9336 100644
--- a/docs/rfc/implemented/feature/2026-07-06-sandbox.md
+++ b/docs/rfc/implemented/feature/2026-07-06-sandbox.md
@@ -1,5 +1,7 @@
 # RFC: The subprocess sandbox — confinement seam, native runners, escalation, and per-session modes
 
+English | [中文](2026-07-06-sandbox.zh.md)
+
 Status: implemented
 
 ## Problem
diff --git a/docs/rfc/implemented/feature/2026-07-06-sandbox.zh.md b/docs/rfc/implemented/feature/2026-07-06-sandbox.zh.md
new file mode 100644
index 0000000000..4285ae4ceb
--- /dev/null
+++ b/docs/rfc/implemented/feature/2026-07-06-sandbox.zh.md
@@ -0,0 +1,212 @@
+# RFC：子进程沙箱——约束 seam、原生 runner、升级机制与按会话模式
+
+Status: implemented
+
+[English](2026-07-06-sandbox.md) | 中文
+
+## 问题
+
+一个编码 agent 需要如下产品路径：bash 子进程（以及依附其上的钩子命令）默认在受限的文件沙箱下执行；当且仅当沙箱实际拒绝了某个操作时，模型可以为同一操作请求一次用户批准，获批后以更宽的权限重试一次。本设计刻意不声称覆盖所有工具：fs/web/todo 在进程内执行，`execve` 包装对它们毫无意义（§ 进程内工具）；跨工具族的统一边界属于分阶段后续工作（§ 延迟阶段）。如果没有共享词汇，每个工具都会各自重新发明批准字段、拒绝解析、重试匹配和权限状态提示。
+
+harness 是一个 SDK，因此约束必须是开发者可**组合**的能力：是否启用沙箱、每个平台使用哪个后端，都应作为一等条目写在叶子 `cordis.yml` 中，而非藏在某个执行器的私有机制里。而首选 runner `bwrap` 恰恰在沙箱最重要的主机上不可用（精简容器、禁用了非特权 userns、LSM 拒绝 `mount`），因此备选 runner 必须随 SDK 一起交付，而不能假设主机已有。
+
+仅有约束还留下两个缺口。拒绝后没有升级路径就是死路：模型只能放弃，这会迫使运维人员全局配置 `workspace-write` 或 `danger-full-access`，从而使沙箱形同虚设。而模型可见的旋钮（沙箱模式、批准策略）在 agent 生命周期内会变化——ACP 用户切换按会话设置、运维人员在进程停止期间编辑 `cordis.yml`——模型绝不能基于过时的信念行动：每次请求时的实际状态是什么、agent 存活期间发生了什么变化、无人看管时又发生了什么变化，都需要有明确答案。
+
+## 决策
+
+一个 seam、一条按平台的本地后端链、一个消费方，加上两个上层杠杆：按调用的升级路径与按会话的运行时模式。以下所有内容均从叶子 `cordis.yml` 组合而来；不触及 `agent-loop`。范围有意限定：本 RFC 命名但不设计的阶段——按会话工作区根目录、跨工具族 fs 强制、`subagent-acp` 消费方、更多环境、Windows 链——列在 § 延迟阶段，各自是后续设计，而非配置旋钮。
+
+### 部署方式
+
+四条 `cordis.yml` 条目即可将一个无约束的编码 agent 转变为沙箱产品路径；[`examples/acp-agent`](../../../../examples/acp-agent/README.md) 默认使用此组合：
+
+```yaml
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'   # the per-platform runner provider (ctx.sandbox)
+- id: bash
+  name: '@deepseek-ai/dsh-bash-sandbox'    # the confined executor, replacing dsh-bash-local behind ctx.bash
+  config:
+    mode: workspace-write                  # the deployment default every session starts from
+    workspaceRoot: !!js process.cwd()      # the boundary workspace-write may write under
+- id: approval
+  name: '@deepseek-ai/dsh-user-approval'        # the escalation gate's channel (the approval RFC)
+  config:
+    policy: ask
+- id: permission
+  name: '@deepseek-ai/dsh-permission'      # one product-facing select over both mechanism knobs
+```
+
+这一替换对 `ctx.bash` 的所有消费方透明：bash 工具、钩子命令和后台任务照常运行，通过提供方返回的包装 argv spawn。删除 `sandbox` 和 `permission` 条目、将 `bash` 替换为 `@deepseek-ai/dsh-bash-local` 即为退出——执行恢复为无约束，升级字段从工具 schema 中消失，因为它们是基于已挂载执行器的能力门控，而非基于配置。仅省略 `approval` 则保留约束但以自身错误文本关闭每次升级；`permission` 还要求 approval seam 和约束执行器同时存在，因此部分组合的 preset 层在加载时即大声失败。
+
+配置错误大声失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段（命令 spawn 之前）抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner seam。
+
+被拒绝的文件操作返回 `[sandbox: file access denied under <mode> mode]` 标记，并附带不要绕过拒绝的指令。约束执行器添加配对的 `sandbox_permissions` 和 `justification` 字段，用于一次经批准的重试，该重试必须严格宽于会话的有效模式。授权仅放宽该次重试；拒绝则不执行任何内容，返回 `the user rejected escalating this command to "<mode>"`，且不允许再次请求。提示词不声明沙箱模式，以避免基于常驻标签的预防性拒绝。当 `dsh-permission` 被组合时，ACP 暴露一个 `Permissions` 选择器，其 preset 同时写入两个旋钮事件；不匹配的旋钮组合显示为仅可切换离开的 `custom`。只有切换到确定性的 `'never'` 批准策略才会在提示词中声明并叙述。
+
+### 设计细节
+
+#### 范围界定
+
+OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还将适用于 ACP subagent 子进程。文件系统、web 和其他工具在进程内执行，需要在各自的 seam 层面实施策略；argv 包装无法约束一个闭包了 `ctx` 的函数。既有的 bash request/spec 拆分承载按调用的覆盖，而 `tools/pre-execute` 和 approval seam 负责人的决策。
+
+#### seam：`ctx.sandbox`
+
+`dsh-sandbox` 拥有词汇和 `SandboxProvider` 契约：`confine(argv, policy)` 返回调用方应当 spawn 的替代 argv（经过包装，使进程及其所有子进程在约束下运行），加上所选后端达到的 `enforcement` 完整度、其拒绝方言（`denialSignatures`，该后端内核在拒绝文件操作时打印到 stderr 的子串）、以及其 runner 失败方言（`runnerFailureSignatures`，runner **本身**失败——因而命令从未运行——时的自我标识方式）；没有可用后端时抛出失败关闭的 `SANDBOX_UNAVAILABLE` 错误，绝不静默放行。词汇：`SandboxMode`（`read-only` / `workspace-write` / `danger-full-access`，仅限文件操作——不声称覆盖网络和进程可见性）、`SandboxEnforcement`（`full` / `partial`）、`SandboxPolicy`（mode + workspace root）。
+
+策略随每次**调用**而非提供方携带：两个消费方可以在同一时刻以不同策略约束（bash 在 `read-only` 下运行，而一个受约束的子 agent 保持其状态目录可写），且经批准的升级重试是一次带有更宽策略的新调用——在配置固定的提供方模式下无法表达。
+
+该 seam 仅约束**同世界**子进程：后端共享主机的文件系统和内核。容器、microVM 和远程执行器不是此 seam 的后端——它们以环境一致的组替换整个能力实现（`ctx.bash`、`ctx.fs`），因为一个 bash 在容器中运行而 fs 工具写主机的 agent 生活在两个割裂的世界中。
+
+留待需要时再决定：网络限制是作为独立的 `network_mode` 到来，还是在某个 runner 同时强制两者后合并进 `sandbox_mode`；以及 `SandboxPolicy` 是现在就增加额外的可写根授权（launcher 已支持 `--rw <path>`），还是等到升级机制需要时再加。
+
+#### 本地后端与随附 launcher
+
+`dsh-sandbox-local` 在提供方生命周期内选择一个平台 runner 并缓存结论。Linux 功能性探测 `bwrap` 然后 Landlock；macOS 使用 Seatbelt。不支持的平台和不可用的 runner 失败关闭。每次包装携带后端特定的拒绝签名和 runner 失败签名，以便 `dsh-bash-sandbox` 区分被拒绝的文件操作与损坏的沙箱。`runnerCommand` 作为运维人员对 bwrap 形状 runner 的断言跳过选择，但缺失或不可执行的命令仍被归类为沙箱失败，绝不无约束地运行负载。
+
+launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI——除静态链接的 musl 外无其他库，因此审计面仅为该文件加内核的稳定 syscall 契约）：`--ro <path>` / `--rw <path>` 授权，`--`，被包装的 argv；它在自身上安装规则集并 `exec`（规则集跨 `execve` 继承，且它在限制前设置 `no_new_privs`）；`--probe` 在一个短生命周期子进程中强制最大规则集，仅当内核确实强制时才以 0 退出；launcher 失败以 125 退出且不 exec。
+
+Landlock launcher 通过 [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) 交付，平台二进制由 npm 选择。该包（package）拥有路径解析、探测和 CLI flag；harness 将沙箱模式映射为授权。将入口点与其二进制一起版本化，使探测解析和启动语法保持对齐。
+
+FIXME: Revisit the separate-repository boundary and try to maintain the launcher source and its platform package family inside this monorepo, so the native release surface and harness contract evolve together.
+
+后端 profile 共享模式契约但在必要的主机授权上有所不同。Landlock 和 Seatbelt 在 read-only 模式下仅允许 `/dev/null`；workspace-write 还允许各自所需的主机临时目录根。每次包装携带后端特定的拒绝签名。Landlock 在较旧的 ABI 无法管控所有操作时报告 partial enforcement，而成功的 bwrap 和 Seatbelt profile 报告 full enforcement。
+
+#### bash 消费方
+
+`dsh-bash-sandbox` 复用本地进程执行，并请求 `ctx.sandbox` 包装确切的 bash argv。内核拒绝是独立于退出状态的结果事实，仅从所选包装的 stderr 方言推断。Runner 失败优先于拒绝，因为它意味着命令从未运行：前台调用抛出 `SANDBOX_UNAVAILABLE`，而已结算的后台任务为 `bash_output` 设置 `sandbox.runnerFailed`。这使损坏的约束与任务失败和强制拒绝保持区分。
+
+模型看到的仅是结果事实：静态工具描述解释拒绝标记（`[sandbox: file access denied under <mode> mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试；当升级字段被公布时，被拒绝的结果还额外携带升级提示本身，使被认可的同轮次重试在决策点被提示，而非依赖模型回忆描述（§ 升级机制）。没有提示词段落声明沙箱模式（§ 按会话模式）。
+
+#### 升级机制：拒绝后一次经批准的更宽重试
+
+`BashExecRequest.sandboxMode` 是可选的按调用输入；解析后的 spec 使该字段显式。`BashExecutor.sandboxMode` 公布已挂载的执行器能否兑现它，因此只有约束组合才暴露升级。seam 接受任何显式模式；工具拥有「仅更宽」的升级规则。非沙箱执行器诚实地保持无约束。
+
+`SandboxBashExecutor.resolve()` 盖章有效模式——升级授权 > 会话覆盖 > 配置默认——使 `run()`/`start()` 读取 spec 而非配置。`danger-full-access` 分支、confine 调用和结果事实都以 spec 的模式为键，且按任务的事实 map 携带每个任务的模式及其包装事实（`notifyTaskDone()` 从 map 条目盖章）：一次升级调用——前台或后台——报告它**实际**运行的模式，而每个邻居保持自己的。
+
+当约束执行器被挂载时，`bash` 公布配对的 `sandbox_permissions` 和 `justification` 字段。schema 暴露完整的封闭升级词汇，因为有效模式是按会话的；执行拒绝任何不严格宽于该调用有效模式的目标。批准在执行之前解析。`allowed-once` 仅将授权模式盖章到该请求上，而 `rejected`、`cancelled`、`unavailable`、缺失的 approval 服务或缺失的 agent 都以各自不同的结果文本失败关闭。授权不持久化。
+
+升级是对被拒绝命令的同轮次重试，使用最窄的足够 `sandbox_permissions` 和一个 `justification`；批准提示是同意步骤。它必须基于实际的拒绝，除非会话已观察到相同的被拒绝访问；禁用或被拒绝的批准终结该命令。重试、批准决策和结果使用既有的工具和批准事件。`dsh-tool-bash` 拥有请求动作，因为执行器 seam 既没有 agent 也没有用户交互所需的 call id。
+
+留待后续阶段处理：授权的范围标识超出沙箱模式之外是什么——确切的调用、路径、命令前缀、会话、时间窗口——这是 `allow_always` 授权存储在该选项可被公布之前必须回答的问题；以及如何为通过 `bash_output` 延迟到达的 `run_in_background` 拒绝定义升级。
+
+#### 按会话模式：会话日志即存储
+
+```
+effective(session) = findLast(the session's own knob events)?.value ?? the composition-config default
+```
+
+默认值是组合配置（`cordis.yml`）——运维人员拥有，进程范围。运行时切换是**会话范围**的覆盖，记录为该会话自身日志中的一条仅日志事件。重启免疫（恢复会话时回放其日志，覆盖自然恢复，无需追赶机制）和多会话隔离（一个编辑器标签页的 `workspace-write` 不会干扰另一个的 `read-only`）都是构造性的自然结果，且不存在任何外部配置存储。
+
+**每个旋钮一种事件，由其领域拥有**——这是每个既有事件族已遵循的可合并扩展 `SessionEventMap` 惯用法（`dsh-user-approval` 中的 `approval/*`、hooks 包中的 `hook/*`）：
+
+```ts
+interface SessionEventMap {
+  'bash/sandbox-mode': { mode: 'read-only' | 'workspace-write' | 'danger-full-access' }
+  'approval/policy': { policy: 'ask' | 'never' }
+}
+```
+
+每个拥有者导出相同的三件套：事件声明、纯 fold（`effectiveSandboxMode(events)` / `effectiveApprovalPolicy(events)`——一个 `findLast`，类型化到领域的封闭联合），以及**唯一的**写入路径（`setSandboxMode(session, mode)` / `setApprovalPolicy(session, policy)`——切换即其事件；没有任何东西在带外修改状态）。无共享拥有者服务、无通用 facts map、无注册表：第三个旋钮只需将约 40 行模式复制到自己的包中。执行在两侧都遵循 fold——bash 工具的按调用盖章将其作为 § 升级机制优先级链的中间层读取，approval seam 的 `'never'` 门控是[批准 RFC](2026-07-06-approval-seam.md) 同一模式的另一侧。
+
+沙箱模式不在提示词中叙述；拒绝结果在需要时报告模式，避免基于常驻标签的预防性拒绝。批准策略不同：只有 `'never'` 被声明，因为自动拒绝在行为上与用户的「不」无法区分。策略变更通知被合并，由下一个 pre-step 递送，重启后有基于日志的回退。通知来源从事件位置推断：最后一个 request header 之后的旋钮事件是用户驱动的；未记录的漂移是运维人员或配置驱动的。
+
+**编辑器界面**是协议原生的 [Session Config Options](https://agentclientprotocol.com/protocol/session-config-options)——该规范对 session modes 的替代（计划在 ACP v2 中移除），已有 SDK 类型。当 `ctx.permission` 被组合时，bridge 在 `session/new` 和 `session/load` 中公布一个 `permission` 选择器（category `mode`）；其选项是部署的 preset 表，其 `currentValue` 是 `PermissionService.current()` 对会话日志加组合默认值的结果。随附的 `workspace-write` 和 `danger-full-access` preset 各自捆绑一个沙箱模式与一个批准策略，并写入两个领域 setter；preset 表之外的旋钮组合报告为仅可切换离开的 `custom`。`session/set_config_option` 通过 permission 服务验证并切换，然后返回完整的刷新状态（规范契约）。
+
+**轮次封闭是提交边界。**开放轮次中的切换立即追加。空闲切换保持在 bridge 记录上待定，在下一次 prompt 提交时、assembly 或执行之前追加到开放轮次中；每个旋钮以最后写入为准。开放性来自日志边界而非 `agent.status`，setter 不从 `session/event` 监听器内追加，因为那会重排后续观察者。锚定之前，响应叠加待定值。崩溃丢弃它，重新加载返回持久 fold。
+
+#### 进程内工具
+
+fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层面的策略：fs 意图门控按共享模式词汇决策（§ 延迟阶段，跨工具族），使 `read-only` 成为真正的边界而非仅限 bash 的近似——在此之前契约诚实地如此声明。没有通用的按工具沙箱运行时：主机中介的工具仅通过返回主机验证的声明式效果来离开进程，那是一次重写而非包装。
+
+FIXME: Revisit this tool-local boundary. The follow-up design needs to determine whether sandboxing becomes a global harness capability that applies uniformly to every tool, instead of expressing in-process enforcement independently at each tool seam.
+
+### 测试
+
+- **单元测试：**固定平台选择和 profile、失败关闭的 runner 分类、按调用事实、升级验证和结果、permission preset fold 和写入透传、叙述器合并、ACP 公布和验证、轮次封闭的配置写入。
+- **Keyless 真实 runner：**在提供方和 bash 消费方层面对 bwrap、Landlock 和 Seatbelt 执行真实文件系统效果测试；packed-install 覆盖率证明注册表 launcher 保持可执行。真实 ACP 组合固定 permission 切换并拒绝未知 preset。CI 拒绝静默全跳过。
+- **With-key：**驱动真实模型、runner、bridge 应答器和磁盘效果通过授权和拒绝的升级；不可用的凭证或 runner 自动跳过。
+- **快照：**固定 permission config-option 协议格式（wire format）、preset 和旋钮事件、prompt delta 和通知、以及两个脚本化的 approval 分支。快照模式以无约束启动，使无关 fixture（测试前置数据）保持平台无关；策略场景显式切换。真实拒绝 stderr 留在平台测试中，因为其方言是 runner 特定的。
+
+## 延迟阶段
+
+每个阶段在被拾起时获得完整设计，对照当时的代码验证，并在其涉及的层级带上单元测试、真实 API e2e 和快照覆盖率落地。
+
+- **按会话工作区根目录**——执行器的写入边界在其生命周期内保持配置固定，而每个 ACP 会话有自己的 cwd；按会话根目录一旦设计完成即搭载同一个按调用策略载体。
+- **跨工具族边界**——fs 意图门控按共享模式决策，使 `read-only`/`workspace-write` 成为 bash 之外的真正边界。
+- **第二个消费方**——`subagent-acp` 可选地约束子 agent（按调用策略；默认无约束——子 agent 必须写入自己的持久化）。
+- **更多环境**——环境一致的能力组示例（如 bash+fs 对一个容器）。
+- **Windows 链**——`PLATFORM_CHAINS.win32` 保留为空（失败关闭）；填充它意味着来自 AppContainer/restricted-token 家族的约束 runner，从其自己的仓库按 `node-addon-landlock-run` 模板交付，加上其 profile 方言和拒绝/runner 失败签名。
+
+## 曾考虑的替代方案
+
+- **命令字符串启发式预检**：否决。无法理解展开/子进程/符号链接；严格尝试（运行它，让内核决定）是唯一可信的拒绝信号。
+- **即使平台仅有一个后端也功能性探测**：否决。探测用于在候选者之间仲裁；只有一个时无需决策，且探测开销对每个会话的首次约束命令征税（对未来重量级后端而言代价过高）。runner 自身执行时的失败关闭拒绝加 `runnerFailureSignatures` 分类承载了安全属性。
+- **提交构建好的 launcher 二进制**：否决。diff 中的二进制不可审查且膨胀历史；经审查的源码 + 原生 CI 构建 + launcher 仓库的字节固定发布演练使二进制远离所有代码树。
+- **安装时编译 launcher**：否决。将 C 工具链强加给每个消费方；仅在碰巧有编译器时才存在的备选不是备选。
+- **从一个构建器交叉编译两种架构**：否决。仅为重建两个约 70 KB 的二进制就需要携带一个固定的交叉工具链（rustup targets、zig 或容器镜像）；每架构的原生 runner 已存在，各自构建自己的平台包（`node-addon-require-builtin` 模式，launcher 仓库自己的流水线）。
+- **无备选（bwrap 或失败关闭）**：否决。将失败集中在沙箱最重要的主机上，最终因放弃而降级到 `danger-full-access`。
+- **将机制保留在 `dsh-bash-sandbox` 内部**：否决。阻塞既有的第二个消费方，使未来阶段从一个 bash 插件的配置中读取模式，且无法表达升级。
+- **提供方上的配置固定模式**：否决。每进程一个模式；无法服务具有不同策略的并发消费方，也无法表达一次性放宽重试。
+- **一个接口同时覆盖容器/VM**：否决。`confine(argv)` 预设共享文件系统；环境隔离是作为一致组部署的能力兄弟后端。
+- **通用 ToolRuntime 包装任何工具**：否决。对进程内工具（闭包了 `ctx`）机械上不成立；声明式效果重写对 fs/web/todo 而言不合理。
+- **在执行器内部（`dsh-bash-sandbox`）请求批准**：否决。没有可路由的 `agent`，没有可附加 prompt 的 `callId`；添加它们会让传输 seam 了解会话和 UI——工具层持有两者并拥有面向模型的词汇。
+- **同一工具调用内自动重试**：否决。日志无法重建的隐藏重入：一个 `tool/call` 会产生两次具有不同策略的执行——重试是一次**新的**带有自身参数和结果事实的已记录调用。
+- **无条件公布升级字段**：否决。在 `dsh-bash-local` 下它们是死杠杆——公布 harness 无法兑现的选项会制造注定失败的授权；能力门控仅需注册时一次读取。
+- **默认值相对的升级阶梯（仅公布比执行器注册时默认值更宽的模式）**：否决。按会话覆盖使默认值成为错误的基线——切换到比默认值更窄的会话恰恰失去它需要的杠杆，而在 `danger-full-access` 默认值下字段完全消失，同时一个被覆盖为 `read-only` 的会话仍处于约束中却没有升级路径。枚举固定封闭的目标词汇；严格放宽是针对会话有效模式的按调用执行检查。
+- **按会话动态工具 schema**：否决。schema 设计上是注册表全局的（一套 assembly 词汇、固定 header 快照契约），按会话重新注册只能买到执行时严格放宽检查已保证的东西，代价是按会话的 schema 表面和每次切换的 header 变动。
+- **将重试硬匹配到先前的拒绝**：否决。命令字符串同一性脆弱（引号、`workdir`、env 前缀、作为失败阶段重试的管道）——要么误拒诚实的重试，要么被轻易满足；真正的边界是人看到命令 + 理由。仅在 `allow_always` 授权存储需要机器可检查的范围时才重新考虑。
+- **通用 `env/state` facts map 加拥有者服务**：否决。approval 和 sandbox 独立组合，因此任何一方的状态都不应拖入第三个包；单键 fold 各自是一个 `findLast`，拥有者服务自然消解；没有跨旋钮的不变式，因此原子多键补丁无收益。
+- **通过 `agent/user-message` + 总线事件叙述**：否决。它预设了一个不存在的轮次入口 seam（真正的 seam 是 `agent/prompt-submit`），而 pre-step 的位置以一个监听器同时服务合并的轮次入口通知和轮中即时性约束。
+- **提示词中常驻声明沙箱模式（+ 切换叙述器）**：先交付后移除，基于实际证据：当每个请求中都有 `Bash commands run under the "read-only" file sandbox.` 时，模型拒绝**尝试**被拒绝后可升级的工作（首次手动会话中十二个轮次有五个以零工具调用结束），将沙箱变成了软锁定。拒绝标记在需要时命名模式，升级字段承载恢复路径；批准旋钮保留其声明，因为自动拒绝在行为上与人的「不」无法区分。
+- **用专门的簿记事件追踪「上次告知」**：否决。`request/header*` fold 已记录模型看到的确切 prompt；将封闭的候选句子解析回来替代了第二条簿记流——事件仅在它们**本身即为存储**时才需要。
+- **ACP session modes 而非 config options**：否决。preset 已经是一个部署定义的 config-option 选择器，且 modes 计划在 ACP v2 中移除。
+
+## 后果
+
+已交付并固定的内容——测试中的各层级分别保障：
+
+- 被拒绝的命令以 `sandbox_permissions` + `justification` 重试时，通过组合的应答器链提示用户；授权使**该次**调用在更宽模式下运行（结果事实如此报告），而其他所有调用保持各自的有效模式；每种非授权结果产生各自不同的错误文本且不执行任何内容。
+- 升级字段恰好在已挂载的执行器约束时存在；不严格宽于调用有效模式的请求以自身文本失败关闭且不提示任何人；没有 ApprovalService 的部署对升级调用失败关闭，对普通调用不影响。
+- 系统提示词从不声明沙箱模式（批准 `'never'` 策略是唯一被声明的旋钮），且整个交互——header、旋钮事件、通知、批准、结果——仅从会话日志即可重建，除两个旋钮事件外无额外事件类型。
+- N 次空闲切换每个旋钮最多产生一个锚定事件（净零序列不锚定任何事件——客户端回显当前选择的无操作推送不记录任何内容）；批准策略切换最多以一条合并通知叙述；轮中沙箱切换由下一次调用的盖章兑现。
+- 恢复的会话的覆盖生效并报告给编辑器，无需特殊处理；进程停止期间变更的默认值在会话的首个新请求前被叙述，归因于运维人员。
+- 两个并发会话永远看不到彼此的状态、通知或配置选项。
+- `agent-loop` 未被触及——一切搭载 `systemPrompt.section`、`SessionEventMap` 合并、`agent.inject()`、`agent/pre-step`、`agent/prompt-submit` 和 ACP handler 表面。
+
+代价与已接受的限制：
+
+- **单一包装的幻觉被有意放弃。**`tools/pre-execute` 包装加 prompt 约定无法解决沙箱批准——正确的设计需要结构化拒绝、原生 runner 探测、按调用策略承载和一致的跨工具族强制，本设计为此付出了代价。
+- **`read-only` 尚不是跨工具族边界。**在 fs 意图门控按共享模式决策之前，该声明仅对 bash 成立；契约诚实地如此声明（§ 进程内工具）。
+- **Windows 没有后端。**其链槽保留为空——失败关闭，绝不穿透；填充它是延迟阶段。
+- **Seatbelt 层级依赖 Apple 已弃用但仍交付的 `sandbox-exec` CLI。**作为 darwin 的唯一候选，它无需探测即被选中，因此未来移除会在执行时作为 runner 失败分类浮现——重新抛出 `SANDBOX_UNAVAILABLE`，命令从未运行；失败关闭，绝不开放。
+- **Landlock 约束的完整度取决于运行内核的 ABI。**报告为 `enforcement: 'partial'` 而非拒绝——这是有意的权衡，使备选在旧内核主机上仍可用。
+- **launcher 作为注册表依赖到达。**通过其自身仓库的发布流水线（经审查的 C 源码、原生 CI 构建器、字节固定的发布演练）加上本仓库的版本固定获得信任——真实内核 e2e 测试腿是通过安装字节为行为背书的。
+- **模型可能过度请求。**在没有拒绝依据的情况下升级，或在 `workspace-write` 足够时选择 `danger-full-access`：描述引导且枚举强制阶梯，但人的 prompt 是实际门控；`approval/asked` 原因使过度请求可审计，且 `prepend` 策略应答器可以自动拒绝部署永远不想要的模式。
+- **公布的目标集是静态的，而有效模式是按会话的**（schema 是注册表全局的）——已处于最宽模式的会话仍被提供这些字段。构造上无害：执行时的严格放宽检查（而非枚举）是安全边界——非放宽请求以自身文本失败且不提示任何人。
+- **授权的升级不等于可工作的沙箱。**不可用的后端即使对授权升级到约束模式也仍然失败关闭——在平台没有链或所有探测失败时于 `confine()` 阶段，在未探测的唯一 runner 拒绝时于执行阶段（归类为沙箱失败而非命令失败）——而授权的 `danger-full-access` 运行根本不触及提供方：此时授权（而非探测）是权威。
+- **空闲切换存在于 bridge 内存中，直到下一次 prompt 提交锚定它。**该窗口内的崩溃将其回退（在 `session/load` 时报告），且永不再提交 prompt 的会话永不持久化它——已接受，loop 拥有的空闲提交轮次留作未来工作（如果持久性成为需求）。
+- **批准叙述器的重启基线解析 prompt 文本。**封闭的候选句子由写入模块本身拥有，因此措辞变更是同一文件中写入器+解析器的协调编辑；header 早于该段落的会话静默采用当前策略而不发通知。
+- **批准段落仍是动态 prompt 表面**（`'never'` 切换会破坏该会话的提供方 prompt 前缀缓存）。已接受：策略切换罕见，且模型基于过时的 `'never'` 行动更糟。沙箱旋钮不再触及 prompt。
+- **模型可能持有关于沙箱模式的过时信念**（没有任何东西宣布切换）。有意接受：下一次尝试的标记或成功会纠正它，而宣布的观察到的失败模式——预防性拒绝——比一次浪费的重试更糟。
+
+## FAQ
+
+- **一个命令返回了 `[sandbox: file access denied under read-only mode]`——它失败了吗？**它**运行了**，内核拒绝了一个文件操作：拒绝是与退出码正交的结果事实。教学禁止绕过它重试；唯一被认可的动作是以升级请求重试同一命令一次。
+- **如何区分损坏的沙箱与失败的命令？**Runner 失败在分类中优先于拒绝：匹配包装的 `runnerFailureSignatures` 的失败运行意味着命令**从未运行**——前台重新抛出结构化的 `SANDBOX_UNAVAILABLE` 并附带 runner 的 stderr 行，后台任务盖章 `sandbox.runnerFailed` 并渲染自己的标记。损坏的沙箱永远不会被读作失败的命令，且命令永远不会无约束运行。
+- **在没有后端的平台上会发生什么——今天的 Windows？**`confine()` 抛出失败关闭的 `SANDBOX_UNAVAILABLE`，命令永不 spawn；`win32` 是保留的**空**链，由测试固定为同样失败关闭，直到 Windows runner 填充它（§ 延迟阶段）。
+- **`bwrap` 已安装在我的主机上但不可用（禁用了非特权 userns、LSM 拒绝 `mount`）——会发生什么？**链探测是功能性的——它构建并强制一个真实 profile 而非检查 `--version`——因此存在但不可用的 `bwrap` 探测失败，选择落到注册表安装的 Landlock launcher，结论在提供方生命周期内缓存。
+- **沙箱限制网络或进程可见性吗？**不——`SandboxMode` 仅声称文件操作；bwrap profile 刻意不 unshare pid，没有后端声称网络。网络限制是否成为自己的旋钮留在 § seam 中开放。
+- **哪些工具实际在约束下运行？**通过 `ctx.bash` 的 OS 子进程——bash 工具，以及传递性的钩子命令。fs/web/todo 在进程内执行，`execve` 包装对它们机械上毫无意义；它们的 `read-only` 语义随跨工具族延迟阶段到来，在此之前契约诚实地声明仅限 bash。
+- **授权的升级会持久化吗？或覆盖后台任务吗？**都不会：授权被请求它的那次调用（前台或后台）消耗，该次调用报告它实际运行的模式，而每个邻居保持自己的。如何为通过 `bash_output` 延迟浮现的后台拒绝**定义**升级，留在 § 升级机制中开放。
+- **编辑器的模式切换何时生效？**轮中：立即追加，由下一次调用的盖章兑现。空闲：保持在 bridge 的会话记录上，在下一次 `agent/prompt-submit` 时锚定到其开放轮次中，N 次切换合并为最多一个事件（净零则无）；锚定前崩溃回退它，`session/load` 报告真实状态。模型不被告知——其下一个命令直接在新模式下运行。
+- **重启后什么存活——如果运维人员在进程停止期间改了配置默认值呢？**覆盖从会话日志回放（`effective = fold ?? config`），因此恢复的会话以零追赶机制保持其模式；离线漂移的默认值以与切换相同的方式改变行为（批准策略因被声明，还额外以运维人员/配置归因叙述）。
+- **结果上的 `enforcement: 'partial'` 是什么意思？**所选后端强制其内核 ABI 管控的子集——例如 ABI v3 之前的 Landlock 不管控路径 truncate——并以结构化方式如此声明而非拒绝主机；探测的报告行区分各种情况。bwrap 和 Seatbelt profile 构造上管控所有承诺的文件操作，因此始终报告 `full`。
+
+## 先例
+
+本设计复制或对比的仓库内先例：
+
+- [能力 seam RFC](../architecture/2026-06-13-capability-seams.md)——接口/实现/消费方拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。
+- `dsh-bash` 的 request/spec 拆分及其 `owner` 字段（[bash 词汇目录](../../../core-data-structures/bash.md)）——`sandboxMode` 搭载的按调用载体模板，以及显式 `resolve()` 默认约定。
+- [批准 seam RFC](2026-07-06-approval-seam.md)——升级请求通过的通道；其应答器 waterfall（瀑布式事件）、审计对和单包理由记录在那里。
+- [事件溯源会话](../architecture/2026-06-11-event-sourced-sessions.md)与[轮次封闭不变式](../architecture/2026-06-15-turn-enclosure-invariant.md)——按会话模式 fold 所依赖的日志即存储基础，以及锚定设计遵守的提交边界。
+- [拦截 seam RFC](2026-06-30-interception-seams.md)——`tools/pre-execute` 词汇，升级门控刻意不复用它（升级调用没有自己的 pre-execute 时刻）。
diff --git a/scripts/translation-pairing.manifest.json b/scripts/translation-pairing.manifest.json
index c836ec18de..0459512d1e 100644
--- a/scripts/translation-pairing.manifest.json
+++ b/scripts/translation-pairing.manifest.json
@@ -73,6 +73,7 @@
     "docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md",
     "docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md",
     "docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md",
+    "docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md",
     "docs/rfc/implemented/feature/2026-06-14-acp-agent-client-protocol.md",
     "docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md",
     "docs/rfc/implemented/feature/2026-06-15-code-mode.md",
@@ -92,6 +93,7 @@
     "docs/rfc/implemented/feature/2026-07-05-skill-system.md",
     "docs/rfc/implemented/feature/2026-07-06-approval-seam.md",
     "docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md",
+    "docs/rfc/implemented/feature/2026-07-06-sandbox.md",
     "docs/rfc/implemented/feature/2026-07-07-mcp-client-plugin.md",
     "docs/rfc/implemented/feature/2026-07-07-session-prefix.md",
     "docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md",