UserPromptSubmit：输入提交前的最后修饰

UserPromptSubmit 钩子在用户按下回车提交 Prompt 之后、系统将其正式发送给模型（或执行 Slash Command）之前触发。它提供了一个对用户输入进行实时审计或自动增强的机会。

核心概念

UserPromptSubmit 本质上是 输入流的预处理网关（Input Pre-processor）。

它允许开发者在不改变用户原始输入习惯的前提下，通过后台逻辑对输入进行“修饰”。常见的场景包括：自动将特定的缩写展开、在提交前进行敏感词过滤、或者根据当前上下文自动为输入添加特定的人物设定（Persona）或项目约束。

它不是对模型回复的拦截（那是 PostToolUse 或 Stop 钩子的职责），它专门服务于用户发送的那一瞬间。

其运行时逻辑深度嵌入在 claude-code-opensource/src/main.tsx 的输入循环中：

捕获原始输入：用户在终端确认输入后，系统捕获 raw_prompt。
触发拦截：系统派发 UserPromptSubmit 事件，并将 raw_prompt 作为输入传递给 Hook。
结果回填与改写：钩子可以返回一个特殊的 HookJSONOutput，其中包含：
- 改写后的 Prompt：直接替换用户的原始输入。模型将看到这个版本，而用户在终端看到的可能依然是其原始输入。
- 状态拒绝（Decision: block）：如果判定输入违反安全准则，返回错误信息。系统会中断发送流程，并向用户展示报错。
Slash Command 优先级：值得注意的是，UserPromptSubmit 运行在 Slash Command（如 /compact）解析之前。这意味着你可以通过钩子动态地将普通的自然语言指令转化为特定格式的斜杠命令。

UI 同步性瓶颈：该钩子是同步执行的。在钩子返回前，终端的光标会处于等待状态。为了保证流畅，钩子逻辑应尽可能保持在毫秒级响应。
不影响历史记录：通常情况下，钩子改写的是发送给模型的 Prompt，用户本地的历史搜索（Up Arrow）记录的依然是其原始输入的文字。
Prompt 注入风险：这是一个强大的注入点。如果钩子逻辑存在缺陷，可能会导致模型接收到被恶意篡改的指令（Internal Prompt Injection）。
与 InstructionsLoaded 的区别：InstructionsLoaded 注入的是 System Prompt，而 UserPromptSubmit 注入的是 User Prompt。

claude-code-opensource/src/utils/processUserInput/processUserInput.ts — 处理用户输入并触发 UserPromptSubmit 的核心逻辑（第 153 行 Slash Command 解析，第 182 行 Hook 触发）。

📄 src/utils/processUserInput/processUserInput.ts — 处理用户输入并触发 `UserPromptSubmit` 的核心逻辑（第 153 行 Slash Command 解析，第 182 行 Hook 触发）。L42-45 of 606

typescript

  executeUserPromptSubmitHooks,
  getUserPromptSubmitHookBlockingMessage,
} from '../hooks.js'
import {

📄 src/types/hooks.ts — `UserPromptSubmitHookInput` 结构定义。L22-24 of 291

typescript

export function isHookEvent(value: string): value is HookEvent {
  return HOOK_EVENTS.includes(value as HookEvent)
}

aude-code-opensource/src/main.tsx— 处理用户输入并触发UserPromptSubmit` 的主循环。