用户提交输入 Hook

onUserPromptSubmitted 在用户提交消息时运行。它可以改写 prompt 或追加上下文，适合输入模板、项目背景和偏好；官方明确说明它不能拒绝 prompt 或执行硬性政策限制。

输入和输出

input 提供 prompt、cwd、timestamp；专门参考把 timestamp 标为 number / Unix timestamp，invocation.sessionId 用于会话关联。

返回 null 或 undefined 原样使用输入。只需要添加信息时，优先 additionalContext，避免无意改变用户目标。

添加应用背景

const session = await client.createSession({
  hooks: {
    onUserPromptSubmitted: async () => ({
      additionalContext: "This project uses TypeScript. Explain changes concisely.",
    }),
  },
});

这里的背景是示例应用已知事实。实际应用应传递当前项目的真实信息；不要因某个示例这样写，就向所有会话注入相同技术栈。

用模板展开约定输入

const session = await client.createSession({
  hooks: {
    onUserPromptSubmitted: async (input) => {
      if (!input.prompt.startsWith("bug:")) return null;
      const description = input.prompt.slice("bug:".length).trim();
      return {
        modifiedPrompt: `Investigate this bug and explain the cause: ${description}`,
      };
    },
  },
});

此例把应用约定的 bug 前缀转换为明确任务，不是 SDK 内置命令。较大改写应在产品中让用户能理解最终发送的内容；直接裁剪长 prompt 可能删掉约束，不能只按长度判断内容无关紧要。

这里不是拒绝请求的边界

官方示例包含敏感内容替换和短期请求数提示，但专门说明 additionalContext 只提供建议，不能强制限流。硬上限应在调用 session.send() 之前由应用检查。

suppressOutput 隐藏响应，不等于请求未发送或未处理；把 prompt 换成警告文本也不是拒绝接口。需要验证、禁止或要求用户补充输入时，应在应用接收消息的流程中处理，不能仅靠模型遵守提醒。

与转换后 Hook 配合

提交 Hook 之后，runtime 还可能补充日期等上下文。要检查最终写入历史和交给模型的文本，使用模型输入转换 Hook。两者字段不同：本页修改 modifiedPrompt，后者修改 modifiedTransformedPrompt。