SDK 会话生命周期 Hooks

onSessionStart 在新会话或恢复会话开始时运行；onSessionEnd 在会话结束时运行。它们适合管理应用自己的状态与资源，不应将代理一轮回答结束当成整个会话已经关闭。

启动与恢复

开始 Hook 的 input 包含 timestamp、cwd、source，以及可选 initialPrompt。source 的参考值有 startup、resume、new；initialPrompt 只在提供时存在。

返回 additionalContext 注入背景，或用 modifiedConfig 覆盖会话配置。官方表只将 modifiedConfig 定义为 object，没有在该页列出完整可修改子字段；使用前以当前 SDK 类型和支持范围为准，不把它当任意 runtime 配置的写入接口。

const session = await client.createSession({
  hooks: {
    onSessionStart: async (input, invocation) => {
      console.log("Session start", invocation.sessionId, input.source);
      if (input.source === "resume") {
        return { additionalContext: "Review prior context before continuing." };
      }
      return null;
    },
  },
});

加载用户偏好或应用保存的上次状态时，用 invocation.sessionId 关联；启动路径应尽量快，避免把大量无关历史重复加入上下文。

会话结束原因

结束 input 包含 timestamp、cwd、reason，以及可选 finalMessage、error。

结束回调的输出字段包括 suppressOutput（隐藏最终会话输出）、cleanupActions（清理动作字符串列表）和 sessionSummary（供日志或分析使用的摘要）。专门参考没有给出 cleanupActions 的完整动作词汇，本页不编造可传命令，也不把它当通用 shell 执行入口。

保存状态与清理资源

应用可在开始时建立按 sessionId 索引的轻量状态，在结束时保存业务摘要、记录 reason，并释放该会话分配的资源。需要恢复时，应用自己的状态存储与 SDK 的会话持久化是两层机制，应分别管理。

清理要能重复执行。官方提醒进程崩溃时 onSessionEnd 可能不会调用，因此不能把唯一的持久化时机或资源回收保证建立在该回调上。

时间类型与结束边界

生命周期专门表将 timestamp 写为 number / Unix timestamp，示例用差值计算时长；实用指南中另有 Date/getTime 写法。应按实际 SDK 类型处理，不将两种示例混用或假定所有版本单位相同。

顶层代理自然结束一轮但会话仍活动时，使用onAgentStop检查完成条件。它可以请求下一轮，onSessionEnd 则负责会话结束后的处理。