deepseek-harness/packages/hooks/hooks-codex/README.zh.md

@deepseek-ai/dsh-hooks-codex

English | 中文

一个 Cordis 插件，在 harness 的规范拦截 seam 上运行用户现有 Codex hook 配置的受支持子集。它是 hooks 子系统中采用 Codex 方言 的一侧。方言无关原语来自 @deepseek-ai/dsh-hook-protocol；该桥接负责处理 Codex 形状的 payload、matcher 模式和决策映射。

该桥接实现 Codex 当前 hook 协议的一个明确子集：

• 10 个 hook 点中的 5 个： PreToolUse、PostToolUse、SessionStart、UserPromptSubmit 和 Stop。
• 只使用正则 matcher（没有字面快速路径；matcher 始终是未锚定正则）。
• snake_case stdin payload，携带 turn_id／model 额外字段，写入时不带尾随换行符。
• 没有 Codex 插件 env 注入，也没有配置时 placeholder 替换（命令仍会接收执行器环境，并通过其 shell 运行）。
• 没有工具前审批或改写路径：hook 可以阻塞，但桥接不会预审批或替换工具输入。

原生 Cordis 插件可以完成此桥接的所有工作，并且功能更强；该桥接只是已映射 Codex 子集的兼容路径（见 拦截 seam Agent Note（agent 决策记录））。

配置

import type { Config } from '@deepseek-ai/dsh-hooks-codex'
const config: Config = {
  configPath: '/path/to/.codex/hooks.json', // required
  model: 'deepseek-v4',                      // optional: stamped on every payload (Codex includes `model`)
  defaultTimeoutMs: 600_000,                 // optional: per-hook timeout when a hook sets none
  stderrSummaryMaxChars: 500,                // optional: char cap on the hook/result event's persisted stderr summary
}

在 cordis.yml 中：

- dsh-hooks-codex:
    configPath: ./.codex/hooks.json
    model: deepseek-v4

配置只在加载时解析一次。configPath 是进程级配置：相对路径在加载时根据进程启动 cwd 解析，而非每会话解析（TODO(per-session-hook-config)）。读取／解析失败会被隔离处理（记录 + 不注册任何内容）。只运行同步 type: 'command' hook；非 command 或 async: true hook 会被解析并跳过，同时记录警告。hook 接受 timeout 或 timeoutSec alias；两者都未设置时，使用协议参考默认值 DEFAULT_HOOK_TIMEOUT_MS（来自 dsh-hook-protocol，10 分钟）。五个桥接支持点之外的事件会在解析时丢弃。

hook 本身会在 agent（智能体）的会话工作区中运行：对 agent scope 点，桥接会将会话 cwd 作为 hook 进程工作目录，因此 hook 作用于 用户项目树，而非服务器启动目录。

Hook 点 → seam Decision

Codex hook	Harness seam	映射
SessionStart	agent/session-start（emit）	纯 stdout hook 的输出 → additionalContext → agent.inject()
UserPromptSubmit	agent/prompt-submit（waterfall（瀑布式事件））	block（退出码 2）→ PromptDecision.block；仅 additionalContext → 通过 next() 委托，再将一个单独标记源的上下文前置到下游 additionalContexts
PreToolUse	tools/pre-execute（waterfall）	block → PreToolDecision.deny（没有 allow／ask）
PostToolUse	tools/post-execute（waterfall）	block → 带反馈的 block；仅 additionalContext → 通过 next() 委托，再将一个单独标记源的上下文前置到下游决策；Code Mode 将子调用上下文延迟到外层 run_code 结果
Stop	agent/turn-stopping（serial）	阻塞 Stop hook 通过 steer() 送入其原因，强制再执行一步

工具调用的 payload 携带真实 tool_name（matcher 测试的相同值）与 Codex tool_input: { command } 形状（存在 command arg 时使用该值，否则使用 ''）。matcher subject 是工具名称（PreToolUse／PostToolUse）或会话源（SessionStart）；UserPromptSubmit／Stop 忽略 matcher。

每个 agent scope stdin payload 都携带 session_id 和 transcript_path。可用时，桥接通过 ctx.sessionPersistence.locate(session.header) 解析后者，否则发送 null，保留 Codex string | null 形状。查找不会创建或 flush 产物，因此在第一个轮次结束检查点之前，路径可能尚不存在，或其指向的 transcript 可能尚未包含当前未结束的轮次。

SessionStart 是唯一的 emit 点，它会脱离运行。每条运行链都会被跟踪；对桥接执行 dispose（资源释放）会中止仍在运行的 hook 进程，再排空 continuation，之后 dispose 才会完成（createDetachedRuns，位于 dsh-hook-protocol）。

上下文源

注入上下文携带显式 { kind: 'plugin', plugin: 'hooks-codex' } 源（否则 agent.inject() 会将其默认为 { kind: 'user' }）。

模型体验

Hook 提供的上下文

模型看到的内容

SessionStart、已接受提示词和工具后 hook 可以添加带源归因的上下文消息；阻塞 Stop hook 将其原因添加为下一步 steering（中途引导）。

Token 影响

hook 不返回上下文时没有成本。Hook 文本取决于数据，会被记录，并重发直到压缩（compaction）。

KV Cache 影响

仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。

已阻塞提示词或工具结果

模型看到的内容

提供方提供的原因逐字传递。缺失原因时，已阻塞提示词精确使用 blocked by UserPromptSubmit hook，已拒绝工具变为 Error: blocked by PreToolUse hook，已阻塞工具后反馈精确为 blocked by PostToolUse hook，阻塞 stop 则精确添加 steering continue: blocked by Stop hook。Codex systemMessage 不会呈现。

Token 影响

阻塞提示词会移除其请求 token；拒绝或反馈会添加保留的回退或提供方文本；强制 continuation 需要另一个完整请求。

KV Cache 影响

已阻塞提示词不发送请求，不会导致失效。拒绝、反馈与强制 continuation 上下文会追加在可复用前缀之后，不改写前缀。

已知限制与暂缓事项

• 不支持的 hook 事件（Codex 当前 10 项中的 5 项）： PermissionRequest、PreCompact、PostCompact、SubagentStart 和 SubagentStop。这些事件的配置会在解析期间静默丢弃。比较基线是 Codex 官方 hook 参考。
• SessionStart 只支持部分功能： 支持纯 stdout 与 JSON additionalContext，但 hook 脱离运行，因此上下文可能错过第一个请求（TODO(session-start-gating)）。
• UserPromptSubmit 只支持部分功能： 支持阻塞加纯 stdout 或 JSON 上下文，但不会强制执行通用 systemMessage 和 {"continue": false} 控制。
• PreToolUse 只支持部分功能： 支持阻塞，但会忽略 additionalContext、permissionDecision: "allow" 和 updatedInput。每个工具都表示为 tool_input: { command }，因此非 shell 工具参数不会如实公开给 hook。
• PostToolUse 只支持部分功能： 支持阻塞反馈与 JSON additionalContext，但不会强制执行 {"continue": false}，非 shell 工具参数会缩减为 { command }，结构化工具输出会在 tool_response 中展平为文本。
• Stop 只支持部分功能： 阻塞会强制另一个模型轮次，但 stop_hook_active 始终为 false，last_assistant_message 始终为 null，且不会强制执行 {"continue": false}。因此，无条件阻塞 hook 会在每个步骤中强制 continuation，除非它自我限制（TODO(stop-loop-guard)）。
• 通用 payload 与输出字段只支持部分功能： 每个已映射事件都报告 transcript_path: null、静态配置的 model 与 permission_mode: "default"，而非当前 Codex 运行时值。systemMessage 会被记录并触发警告，但不呈现，{"continue": false} 会被记录但不会应用 Codex 事件特定停止行为（TODO(hook-continue-false)）。
• 配置加载与执行只支持部分功能： 一个进程级 configPath 会在加载时解析；尚未实现 Codex 的活动用户层、项目层、会话层、系统／托管层和插件层、信任控制与内联 config.toml hook 形式（TODO(per-session-hook-config)）。只运行同步 command handler，忽略 statusMessage 与 commandWindows 等当前元数据，匹配 handler 串行运行，而非使用 Codex 的并发启动语义。