权限、沙箱与完成检查

写操作的调用顺序

修复文件时，先准入 Run 与能力快照，再对每个调用检查参数、权限及所需确认，执行 Hook、预算与沙箱约束，最后记录结果和变化。组件可以安排动作，权限执行器决定动作能否执行。

教程第四章给出默认拒绝、只读工具允许和确认管理器的接线。生产宿主应分别测试读取、写入、命令、网络和越界路径，不能只测“工具成功返回”。

权限与沙箱的职责

权限策略决定调用被允许、拒绝还是需要询问。工作区能力限定后端支持的操作。沙箱限制进程、文件和网络访问。允许一个工具名不会放宽另外两层。

Rust 宿主可通过 BashSandbox 注入进程隔离实现，使用 with_sandbox_handle 绑定，另有网络模式与 allow 范围。允许 host process sandbox 是显式宿主决定。不要把仅检查字符串的策略当成操作系统隔离，也不能用项目 ACL 启用原本未获准的主机执行。

租户、用户、工作区和路径身份都应由可信宿主提供。source_review、只读会话和固定快照审阅的更窄约束不能被提示、Hook 或后续工具注册解除。

Hook 的注册与撤销

会话公开 register_hook、register_hook_handler、register_hook_registration，各自对应配置、处理器和已绑定注册的接口。按选用类型的公开定义接入，保存精确 hook_id，并通过对应 unregister 方法撤销。

接入前先回答三个问题：在哪个事件触发，超时或处理器错误怎样返回，是否会影响模型和工具看到的内容。测试应该观察到实际触发和撤销后的不触发，而不只是 hook_count() 增加。不要依赖注册先后推断优先级，按 Hook 类型中的显式规则配置。

Hook 可以阻止或调整流程，但不能批准被权限拒绝的操作。Hook 要执行命令或 IO 时仍须有授权、期限和清理；在 Hook 里绕到主机直接写文件会破坏受控调用的边界。

预算与中止

set_budget_guard 接入宿主额度判断。模型 token、工具成本、时间、工具轮次和续跑上限分别计量。宿主需要决定失败是否可重试；预算不足不应显示成供应商故障，更不能切换一个无额度检查的入口继续运行。

重试需要继承原授权与已消耗预算。重试不应把重复写入当成新的成功动作。当前结果未知时，核实原操作再决定能否重试。

验证怎样阻止错误完成

verify_commands 执行已选验证命令并保留报告；verification_reports、verification_summary 读取结果。命令本身仍需要受控执行权限。进程退出码为零只证明这条检查按其规则成功，不自动证明用户需求全部满足。

宿主使用 CompletionAttestor 提交独立检查结果时，报告应绑定当前修改摘要和检查身份。修改后旧报告需要失效或重新检查。明确豁免应保留原因，不能把缺失检查改名为通过。

验证入口见 AgentSession::verify_commands L470 ↗；完成判定见 decide_with_contracts L1591 ↗，它先拒绝未解决事项，再检查当前 effect_digest 的豁免或 Passed 报告。

资源清理也要有结果

Turn 资源在单轮结束清理；跨轮使用的监听器、浏览器页面、文档模型引用和租约注册为 Run effect。CapabilityEffect::close 负责释放原资源并返回失败，不能只清空宿主字典。完整接口见验证与资源清理。

实现资源时从 CapabilityEffect L39 ↗ 的异步 close 合同开始核对。

验收至少覆盖：权限拒绝时未执行；确认过期时未执行；Hook 出错可定位；预算耗尽停止；取消后资源结算；清理失败不伪装成成功。

实现依据

• 权限实现
• Hook 接口
• 治理公开入口
• 验证与完成规则