Claude Agent SDK 的权限求值与会话隔离设计

Claude Agent SDK 的权限求值与会话隔离设计

把 Read、Glob、Grep 写进 allowed_tools，并不等于 Agent 只看得见这三个工具；恢复旧 Session，也不只是恢复聊天文本，而是把之前读取的文件和分析历史带进新一轮任务。权限和会话如果分开设计，旧上下文可能越过新的项目或用户边界。本文先解释 deny、allow、permission mode、审批回调和 Hook 的关系，再说明如何让一个任务、一组授权和一个 Session 保持一致。

allowed_tools 不是工具白名单

Claude Agent SDK 权限文档明确说明：allowed_tools 向 allow 规则中增加条目，匹配的工具会被预先批准；没有列出的工具仍可存在，并继续进入 permission mode 和后续审批流程。

这意味着下面的理解是错误的：

allowed_tools = [Read, Glob, Grep]
因此其他工具一定不可用

正确设计要分别回答：

• 哪些调用可自动批准。
• 哪些工具或具体操作必须禁止。
• 哪些调用要交给人或业务审批器。
• 哪些规则必须在每次工具调用前执行。

如果目标是删除某个工具能力，应使用当前文档中的 deny 规则。例如官方文档说明，裸工具名形式的 disallowed_tools=["Bash"] 会从请求中移除 Bash 工具定义；带模式的规则则可拒绝匹配操作。具体规则语法和路径锚点必须按当前版本核对。

按求值顺序设计规则

权限不是一张简单矩阵，而是一条求值链。当前官方文档给出的顺序如下：

1. Hooks：首先运行 Hook。Hook 可以拒绝调用或让调用继续；即使 Hook 返回 allow，后面的 deny 和 ask 规则仍会求值。
2. Deny rules：检查 disallowed_tools 与 settings.json 中的 deny 规则。匹配时阻止调用，即使当前模式是 bypassPermissions。
3. Ask rules：检查 settings.json 中的 ask 规则。匹配时将调用交给 canUseTool，即使 allow 规则也匹配或当前模式是 bypassPermissions；在 dontAsk 模式中则直接拒绝。
4. Permission mode：应用当前模式。bypassPermissions 批准尚未处理的调用，acceptEdits 批准文件操作，plan 则不考虑 allow 规则，把文件编辑与 shell 写操作交给 canUseTool。
5. Allow rules：检查 allowed_tools 与 settings.json 中的 allow 规则，匹配时批准调用。
6. canUseTool callback：只有此前仍未处理的调用才进入回调；dontAsk 会跳过回调并拒绝调用。

这组顺序直接影响策略设计。不可逾越的边界应放进 deny；必须逐次审批的操作应使用 ask，因为 ask 在模式与 allow 之前求值。不能假设宽泛 allow 命中后仍会进入回调，也不能把 Hook 返回 allow 当作绕过 deny 或 ask 的通道。选择 permission mode 时，还要单独验证它会自动批准或强制送审哪些剩余调用。

用拒绝测试验证配置

权限配置不能只测试“允许的动作能运行”，还要测试：

被禁止的工具是否从 Agent 视野中移除
匹配 deny 的具体操作是否始终被拒绝
需要审批的编辑是否实际进入回调
拒绝后 Agent 是否停止，而不是改用另一工具
Hook 抛错或超时时是否采用安全失败策略
路径规则在当前工作目录下实际匹配哪里

在测试仓库中覆盖允许、拒绝、修改参数、取消和异常路径。尤其要检查日志，确认预期回调或 Hook 确实被触发，而不是调用在更早阶段已经获批。

Session 会保存什么边界

官方 Session 文档说明，会话持久化 Agent 的对话历史，可以通过 continue、resume 和 fork 返回之前的运行。它还会保留已经读取文件和完成分析形成的上下文。

这带来两个直接风险：

• 新任务可能继承旧任务中的源码、日志和敏感信息。
• 当前授权已经收窄，但会话历史仍包含较宽权限阶段取得的内容。

因此，“能恢复”不等于“应该恢复”。继续使用会话前，需要同时验证任务、用户、项目、工作目录和数据权限都没有跨界。

一任务一会话的默认策略

作为工程设计建议，可以把 Session 绑定到以下元数据：

内部任务 ID
发起主体
目标项目与确认后的工作目录
数据分类
权限策略版本
模型与 SDK 版本
创建、最后使用与结束状态

同一任务的连续澄清可以 resume；要探索另一种方案且希望保留共同背景时可以 fork，但 fork 后应获得新的内部任务分支标识。以下情况默认新建会话：

• 切换仓库、客户或业务环境。
• 发起人或可见数据范围变化。
• 从只读分析升级为生产写入。
• 旧会话包含不应进入新任务的敏感信息。
• 无法证明 Session ID 与当前任务的归属关系。

不要只使用“最近会话”作为无人值守服务的恢复依据。多用户或并发任务中，应显式保存并校验 Session ID 与内部任务的映射。

权限升级不要复用隐式授权

从只读定位进入编辑阶段时，建议建立新的执行阶段和权限快照。即使继续同一 Session，也应：

1. 固定已批准的输入与候选文件。
2. 重新构造 SDK options，不沿用进程内可变配置。
3. 记录本阶段的 deny、allow、mode、回调和 Hook 版本。
4. 在执行前向人展示将要获得的新增能力。
5. 在阶段结束后撤销凭据和运行环境。

更高风险的生产或外部提交操作不应仅靠恢复会话获得授权。授权对象应是当前动作和具体变更，而不是历史对话中的一句同意。

审计记录与会话内容分开

审计日志需要证明发生了什么，但不应无条件复制完整会话。可以分别保存：

任务与 Session 映射
权限策略摘要和版本
工具名称、脱敏目标、审批结果
阶段状态、错误和取消原因
代码或数据变更的外部证据位置
最终人工决定

源码、用户数据、凭据和模型上下文按数据分类控制访问与保留周期。Session 存储不是通用审计仓库，审计摘要也不能替代必要的业务系统日志。

常见配置误区

只看 allowed_tools

结果是未列工具仍可能进入其他权限路径。应同时设计 deny 与审批流程。

在 acceptEdits 下等待编辑回调

文件操作可能被模式提前批准而绕过回调。需要逐次审批时，应选择与当前文档一致的模式并做拒绝测试。

使用宽泛 allow 后靠 Hook 补救所有问题

Hook 能在早期执行，但规则重叠会增加复杂度。能用清晰 deny 和最小 allow 表达的边界，不应全部堆进自定义代码。

跨项目恢复最近会话

历史上下文和工作目录可能属于另一任务。必须显式校验 Session 归属并在边界变化时新建。

日志保存所有消息

这会扩大敏感数据暴露。日志只保留排错和问责所需信息，并采用相应访问控制。

结论与限制

Claude Agent SDK 的权限设计要按照 Hooks、deny、ask、permission mode、allow 和 canUseTool 的实际求值顺序完成；会话设计则要保证 Session 的历史上下文不越过当前任务和授权范围。两者共同决定 Agent 能看什么、能做什么以及哪些旧信息能继续使用。

权限模式、规则语法和 Session API 都会随 SDK 更新。本文给出设计原则，接入时必须以锁定版本的官方文档为准，并用允许与拒绝两类集成测试证明配置行为。