SDK Hooks

SDK Hooks 是应用在创建或恢复会话时注册的回调，用来补充上下文、检查工具调用、处理结果或记录运行情况。它们在宿主应用中执行；CLI 或云端代理的 JSON Hooks 配置属于其他接入方式，不能直接照搬回调字段与返回值。

按需要选择回调

回调可选，只注册实际需要的部分。返回 null 或语言对应的空结果通常表示沿用默认行为；具体能改变什么，应看该 Hook 的返回字段，不能把任意 Hook 都当作可拒绝操作的权限接口。

注册与关联会话

const session = await client.createSession({
  hooks: {
    onSessionStart: async (_input, invocation) => {
      console.log("Session started", invocation.sessionId);
      return { additionalContext: "Prefer concise explanations." };
    },
    onPostToolUse: async (input, invocation) => {
      console.log("Tool succeeded", invocation.sessionId, input.toolName);
      return null;
    },
  },
});

每个 handler 接收 input 和 invocation；后者含 sessionId，适合关联日志或按会话存储状态。恢复时也可传入 hooks 对象，不把内存回调假定为磁盘会话自动保存的一部分。

保持处理路径简短

Hooks 在处理流程中内联执行，异步函数本身不会消除等待时间。大型日志写入或 HTTP 上报可交给应用的后台队列；有决策作用的检查则要在返回前完成。跟踪多个会话时以 sessionId 分开状态，并在结束后清理。

日志应只记录业务需要的字段。完整工具参数、结果和输入可能含有敏感内容；官方示例中的直接 JSON 输出和正则脱敏都是示范，不能据此认定任意日志已经安全处理。

不统一套用字段类型

官方实用示例有把 timestamp 当作 Date 的写法，部分专门参考表则标为 number / Unix timestamp；Post-tool 写作 SDK timestamp type。目录字段也同时存在 cwd 与 workingDirectory。以下各页按各自参考说明，实际代码以所用 SDK 类型为准，不统一调用 getTime()，也不凭字段名推断所有语言和版本的时间单位。

同样，示例的 onPermissionRequest 自动批准是示例选择，不是所有应用应采用的授权默认值。只想观察工具的 Hook 不应额外引入全局自动批准。