沙箱（sandbox） 安全与工程
别名：
沙箱
把 Agent 的能力关进笼子的机制集合：工作目录路径约束（`resolveWithinRoot`）、命令白名单、无 shell 执行。与 ch18 权限层的分工是——权限层管意图（该不该做），沙箱管能力（能做多坏）；即使人类批准了危险参数，沙箱仍然拒绝。
它是什么
沙箱（sandbox）是把 Agent 的能力关进笼子的机制集合。ch18 的权限层管「该不该做」（意图），沙箱管「能做多坏」（能力）——人类批准了 delete_file(../../etc/passwd) 也没用，沙箱仍然拒绝。本教程的沙箱由三件套组成：工作目录路径约束（resolveWithinRoot，拦 .. 逃逸/绝对路径/前缀碰撞）、命令白名单（fail-closed，只放行只读命令）、无 shell 执行（execFile 参数数组，没有 shell 元字符注入通道）。
能力与意图分开约束
审批门拦不住「运行哪条命令」——人类批准的是「运行命令」这个意图，run_shell({command}) 的参数是模型在执行瞬间才决定的。所以沙箱在工具层兜底：每个碰文件系统的工具执行前最后一刻调校验，拒绝 = 抛错 → 走 error-as-data，模型能看到「为什么被拒」。注意 read_file 是 auto 档（不需要审批）也照样受路径约束——沙箱不看风险档位，auto 工具同样被约束。
诚实局限
白名单拦命令名、不拦参数：cat /etc/passwd 能过白名单。彻底隔离需要容器/虚拟机级——smolagents 官方对本地白名单解释器的态度就是「不是安全边界」（"this solution is not watertight"），生产级用 E2B/Docker 容器。我们做对的事是把「任意命令执行」降级为「有限只读命令」，把 RCE 面缩到最小；这也是「纵深防御」的意义：每一层都不完美，叠加后攻击者无处可绕。
在本教程的位置
第 19 章「手写实现：把沙箱装进产品」一节：lib/sandbox.mjs 三个纯函数族（零 import，浏览器判题可跑），工具层 createBaseTools({ rootDir }) 接入；loop 与协议一行没改——安全在工具层，这是设计而不是偷懒。相关词条：路径遍历、Shell 隔离、提示注入。