SDK 工具权限与沙箱

本地 SDK 默认不询问人工批准，local.sandboxOptions.enabled 和 local.autoReview 默认都为 false。脚本可直接执行 shell、编辑文件与联网，不能把“在后台运行”理解为只读模式。

限制提供给模型的工具

tools 只提供列出的内建工具；disallowedTools 排除指定工具，其他工具及未来新增工具仍可用。两者一起设置时 deny 优先。当前只支持本地，且不会持久化，resume 时必须再传。

const reader = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2.5" },
  tools: ["read", "grep", "glob", "ls"],
  local: { cwd: process.cwd() },
});

tools 未设置时使用模型标准工具集，空数组不提供内建工具。字段接受公开工具名、shell/mcp 能力组或原始 proto 名，未知名在 create/resume 时抛 ConfigurationError。排除 mcp 也移除 custom tools；排除 task 阻止 subagents，否则 subagents 保留自身工具集，不能假设父工具清单自动变成所有子 Agent 的清单。

Shell 沙箱

local: {
  cwd: process.cwd(),
  sandboxOptions: { enabled: true },
}

启用后限制每次 shell 调用及其子进程：写入限定 cwd、临时目录和 sandbox.json 允许路径；读取不限定 workspace；默认禁止出站网络，可通过 .cursor/sandbox.json 或 ~/.cursor/sandbox.json 允许主机。

SDK 专题当前描述 Linux 使用 bubblewrap、macOS 使用 seatbelt，与编辑器 Run Modes 文档中的平台实现描述不同，应按所用 SDK 的实际 helper 和错误诊断，不混用成一个固定后端。缺少支持或 helper 时抛 ConfigurationError，不保证自动退回受限模式。云端 VM 不使用 local.sandboxOptions。

Auto-review

local.autoReview: true 使用分类器判断 Shell、MCP 和 Fetch 是否符合任务意图与安全条件。被阻止的调用直接拒绝，并把原因给 Agent；headless 没有人工升级审批。可用 workspace permissions.json 的 autoRun 配置影响判断。

分类器需要后端启用，不可用时回到默认行为，因此 Auto-review 是尽力提供的便利控制，不是严格隔离边界。需要强约束时同时配置沙箱或工具允许范围。

自定义工具和 Hooks

custom tools 跳过交互审批，包括开启 sandbox/Auto-review 的运行，虽然 deny 规则与适用沙箱限制仍存在，其 execute 本身在应用进程执行。对外部系统的授权必须由工具实现控制，不能靠只读 annotations。

Hooks 可在 beforeShellExecution/preToolUse 等时点限制动作，但只支持文件配置。将可执行环境限制、工具授权与模型意图判断分别检查，具体字段见SDK 扩展。