Hooks 公共输入与输出

理解 JSON 字段、事件特定输出、超时、上下文限制和不稳定 transcript 格式。

This page has not been translated into English yet. The original Chinese version is shown below.

command Hook 从 stdin 接收一个 JSON 对象。处理器应解析 JSON 并检查事件名，不要用文本搜索代替结构化解析。

公共输入

字段	类型与作用
`session_id`	当前会话 ID；subagent Hook 使用父会话 ID
`transcript_path`	字符串或 null，记录文件路径
`cwd`	会话工作目录
`hook_event_name`	事件名
`model`	当前模型 slug，属于 Codex 扩展字段

回合相关事件还可带 turn_id。SessionStart、工具事件、UserPromptSubmit、subagent 事件、Stop、Interrupt 带 permission_mode，其值为 default、acceptEdits、plan、dontAsk 或 bypassPermissions。这些是载荷中的模式名，不应据此改写 approval_policy 配置。

transcript 路径方便诊断，但文件格式不是稳定 Hook 接口。实现应优先依赖已定义的输入字段。

输出必须对应事件

常见控制字段包括 continue、stopReason 和显示警告的 systemMessage。并非所有事件都支持相同字段：

SessionStart、PreCompact、PostCompact、UserPromptSubmit、SubagentStop、Stop 支持公共输出形状。
SubagentStart 可以注入上下文，但 continue: false 不能阻止 subagent 启动。
PreToolUse 和 PermissionRequest 不支持公共的 continue/stopReason/suppressOutput 控制，应使用各自的专用输出。
suppressOutput 不能作为当前版本已实现的输出隐藏功能使用。

例如 SessionStart 注入上下文：

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Load the workspace conventions before editing."
  }
}

普通成功路径可 exit 0 且无输出。Stop、SubagentStop 和 Interrupt 的非空 stdout 必须按对应事件要求返回 JSON，不能随意打印日志；工具事件的普通 stdout 文本则被忽略。

超时和执行位置

timeout 单位是秒，多数 Hook 默认 600 秒；SessionEnd 和 Interrupt 默认 1 秒、最多 3 秒。命令以会话 cwd 运行，因此仓库脚本应从 Git 根或稳定绝对路径定位。Windows 可用 commandWindows 覆盖命令，TOML 也支持 command_windows。

大输出

默认每条提供给模型的 Hook 输出大约限制为 2,500 tokens。超出时，完整内容可保存到临时目录 hook_outputs/<session_id>/<uuid>.txt，模型收到头尾预览和路径；保存失败时仍只得到截断预览。

command handler 的 additionalContextLimit 调整 additionalContext 的近似 token 阈值，省略为 2500，正整数设新上限，0 表示完整送入。该设置不改变工具反馈或继续提示词的默认限制，也不能让不支持上下文的事件获得该能力。多份上下文会累加，应保持简短，避免输出秘密。