feat(runtime): P6 command hook stdin/stdout JSON protocol

[Cai-Tang-www]

Summary

实现 kind=command hook 的完整 stdin/stdout JSON 协议（RFC #679 P6），使任意可执行脚本可作为 hook 接入 user/repo scope。

核心变更

新增 internal/runtime/hooks/command_handler.go：

• 协议类型：CommandHookPayload（stdin）、CommandHookResponse（stdout）、CommandHookSpec（执行参数）
• BuildCommandPayload：构造 stdin JSON，包含 payload_version、hook_id、point、metadata
• ParseCommandResponse：解析 stdout JSON，提取 status/message/update_input/annotations
• RunCommandHook：执行外部命令，处理 stdin 管道、stdout 解析、环境隔离、超时取消

执行模式：

模式	params.command 格式	行为
argv（默认）	["python3", "hook.py"]	直接 exec，不经 shell
shell	"python3 hook.py" + params.shell: true	通过 sh -c / powershell -Command 执行

单字符串 params.command 不设置 params.shell: true 触发配置校验错误，防止 shell 注入。

stdin 协议（单行 JSON）：

{
  "payload_version": "1",
  "hook_id": "my-hook",
  "point": "before_tool_call",
  "metadata": {"tool_name": "bash", "workdir": "/workspace"}
}

stdout 协议（单行 JSON）：

{
  "status": "pass",
  "message": "optional message",
  "update_input": {"text": "rewritten prompt"},
  "annotations": ["note1", "note2"]
}

stdout 退化模式： 非 JSON stdout 退化为 exit code 语义（0=pass, 1/2=block, other=failed），兼容简单脚本。

环境隔离： 命令进程仅注入 NEOCODE_HOOK_HOOK_ID、NEOCODE_HOOK_POINT、NEOCODE_HOOK_PAYLOAD_VERSION，不继承宿主环境。

update_input 接入： 仅 user_prompt_submit 点位（CanUpdateInput=true）允许，格式 {"text": "..."} 替换用户输入文本。

annotations 接入： stdout 中的 annotations 数组进入 runtime annotation buffer，与 message 一同被记录。

修改文件清单

文件	变更
internal/runtime/hooks/command_handler.go	新增：协议类型、payload 构造、response 解析、命令执行
internal/runtime/hooks/command_handler_test.go	新增：18 个测试用例，全平台覆盖
internal/runtime/hooks/result.go	HookResultMetadata 新增 Annotations、UpdateInput 字段
internal/runtime/user_hooks.go	重构 buildUserCommandHookHandler，新增 parseCommandHookParams，移除 buildCommandHookProcess
internal/runtime/repo_hooks.go	新增 validateRepoCommandParams，支持数组格式 params.command
internal/config/runtime_hooks.go	新增 validateRuntimeCommandItem，argv/shell 模式校验
internal/config/runtime_hooks_test.go	新增 3 个测试：shell 模式、字符串无 shell 拒绝、argv 模式
internal/runtime/hooks_integration.go	recordUserHookAnnotations 扩展收集 Metadata.Annotations；新增 applyCommandHookUpdateInput
internal/runtime/run.go	user_prompt_submit 点位接入 update_input 应用
internal/runtime/repo_hooks_test.go	更新 command hook 测试用例为数组格式
docs/runtime-hooks-design.md	新增 P6 章节：协议规范、执行模式、环境变量、示例

向后兼容

• 现有 params.command 为字符串的配置需添加 params.shell: true，否则校验失败（符合 issue 要求：argv 为新默认模式）
• exit code 语义（0=pass, 1/2=block, other=failed）在 stdout 非 JSON 时保留
• CombinedOutput() → Output()：stderr 不再混入 message

测试覆盖

• 正常 exit（exit 0 + JSON stdout）
• 超时（context timeout → failed）
• 非零 exit（exit 1 → block, exit 3 → failed）
• 非法 JSON stdout（退化为 exit code 模式）
• 环境隔离（仅 NEOCODE_HOOK_* 变量，无宿主环境泄漏）
• argv 模式直接 exec
• shell 模式 sh -c / powershell -Command
• update_input 解析与应用
• annotations 解析与收集
• payload_version 字段稳定（"1"）

Closes #683

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[codecov]

Codecov Report

❌ Patch coverage is 80.80000% with 48 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/runtime/hooks/command_handler.go	87.17%	16 Missing and 9 partials ⚠️
internal/runtime/user_hooks.go	0.00%	19 Missing ⚠️
internal/runtime/hooks_integration.go	87.09%	3 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[fennoai]

Review summary: found two command-hook protocol regressions to address before this lands. I also ran go test ./internal/runtime/hooks ./internal/runtime ./internal/config; internal/runtime/hooks currently fails on the env-isolation test.