工具执行前检查

onPreToolUse 在每次工具执行前调用，适合检查具体工具名称、参数和应用政策。它返回的决定只描述这一调用，不等于文件系统沙箱，也不能代替应用对自定义工具输入的校验。

输入与返回字段

input 包含 toolName、toolArgs、cwd 和 timestamp；专门参考将 timestamp 标为 number / Unix timestamp。invocation.sessionId 提供会话关联信息。

返回 null 或 undefined 表示此 Hook 不修改或拦截调用，继续正常处理；不能将它当作取消会话其他权限机制的开关。allow 表示正常执行，deny 阻止执行；ask 的用户批准语义由官方限定在交互模式。SDK 应用是否真的向人显示询问，还取决于权限请求处理方式，不能配上自动批准后仍声称一定有人确认。

阻止指定工具，其余保持原流程

const blocked = new Set(["shell", "bash", "exec"]);
const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (blocked.has(input.toolName)) {
        return {
          permissionDecision: "deny",
          permissionDecisionReason: "Shell execution is disabled in this application.",
        };
      }
      return null;
    },
  },
});

名称必须和实际注册工具一致。此例只表达所列工具的拒绝规则，不宣称已经覆盖所有可执行命令或写入文件的路径。

修改参数时保留工具 Schema

modifiedArgs 可以添加默认值或调整参数，但返回对象仍须满足该工具参数要求。官方 shell 示例补充 30000 毫秒 timeout，只是应用自己的示例策略，不是 SDK 全局默认超时，也不是任意名为 shell 的工具都必然接受同样字段。

官方还展示按路径字符串前缀限制目录的简例。这类写法不等同于规范化后的目录边界检查或符号链接隔离，因此本页不将其包装成完整文件访问控制。需要强隔离时，应结合实际工具实现和运行环境约束。

可信自定义工具可跳过提示

工具定义支持 skipPermission: true，用于应用控制、输入已受约束且适合无需提示运行的自定义工具。它设置在工具定义上；按次策略检查或参数校验则放在 onPreToolUse。

不要为减少提示给任意外部工具统一开启此选项。官方天气示例仅返回模拟结果，不能据此认为执行外部操作的工具都具有同样风险范围。

输出与性能

suppressOutput 会减少模型能看到的信息，使用前需确认后续步骤不依赖完整结果。能用 additionalContext 解释约束时，不必改变参数或隐藏结果。每次工具调用都等待该 Hook，保持判断短且明确，失败原因应让应用或用户理解下一步该怎么做。