SDK 权限处理

官方兼容性参考明确：SDK 的权限请求默认拒绝，应用需提供 onPermissionRequest 处理器来批准请求。写文件、shell、URL 等能力不能仅凭注册工具或发送 prompt 就假定已授权。

区分三层控制

机制	控制什么
availableTools / excludedTools	会话中哪些工具可见或被排除
onPreToolUse	当前工具调用的允许、拒绝、询问，以及参数调整
onPermissionRequest	runtime 发出的权限请求如何由应用决策

工具清单不是用户批准记录，返回 ask 也不自动保证应用真的询问了人。如果权限 handler 总是批准，ask 最终仍可能直接获准。自定义工具的业务权限和输入约束还要由宿主实施。

不把 CLI 开关当作 SDK 策略

CLI 的 --yolo、--allow-all、--allow-all-paths、--allow-all-urls，以及细粒度 allow/deny 参数，在 SDK 中使用权限处理器和 Hooks 的对应机制。交互式 /reset-allowed-tools 也不是发给模型的一条文本指令。

官方展示 onPermissionRequest: approveAll 作为全部批准示例。它是明确放开权限的应用选择，不是为修复任何工具故障都应添加的默认补丁。需要逐次判断时，根据请求内容返回当前 SDK 支持的决定类型，事件接入见工具交互事件。

额外目录与会话恢复

会话 workingDirectory 指定工作目录，additionalDirectories 可授予工作目录以外的目录访问；官方要求恢复时重新提供 additionalDirectories。不要把磁盘恢复的历史记录当作自动重建全部运行权限。

配置工具访问、额外路径或批准策略也不创建 OS 隔离。共享宿主仍需核对实际进程权限、文件可访问范围和会话身份，相关部署见多租户配置。

排查工具没有执行

先确认工具已注册且未被会话筛选排除，再检查 pre-tool 决定和 permission handler。观察拒绝或失败事件，比把所有权限改成批准更能定位问题。仅为记录工具调用而返回空 Hook 结果时，仍沿用其他权限机制，不是全局批准。

可信应用自定义工具可用 skipPermission，但应按执行前 Hook的范围使用；它不能替代不可信参数的校验。