feat: surface codex app server hook governance

docs/architecture/codex_server_progress_card_cn.md

@@ -13,16 +13,16 @@ Codex App Server 是更适合 Boss 长期接入的协议层，因为它面向富
 - approvals
 - streamed agent events
 - Thread / Turn / Item
-- model/list、skills/list、skills/extraRoots/set、plugin/list、app/list
+- model/list、skills/list、skills/extraRoots/set、hooks/list、plugin/list、app/list
 - command execution、file change、tool input、MCP tool-call approvals
 
 Boss 不能直接把 App Server 原始 Thread / Turn / Item 字段写进业务层。当前第一批已经新增 `local-agent/codex-app-server-runner.mjs`，把 App Server 的 `thread/resume | thread/start -> turn/start -> item/agentMessage/delta -> turn/completed` 映射成 Boss 的普通任务完成回写。
 
 2026-05-31 已继续把 `turn/plan/updated`、`turn/diff/updated`、`item/started|completed`、`thread/started` 这类协议事件归一化为 Boss `execution_progress` 的步骤、分支变更、产物和后台智能体。同日第二批补齐 `item/*/requestApproval`、`item/autoApprovalReview/*`、`guardianWarning`、`serverRequest/resolved` 和 `item/fileChange/patchUpdated` 的安全摘要映射，APP 只展示审批状态、风险提醒和文件路径，不展示完整命令、diff、系统提示词或密钥。第三批已把 `thread/status/changed` 与 `thread/realtime/*` 归一成 `executionProgress.threadStatus / realtime`，APP 只展示活跃/等待审批/等待用户输入、realtime 文本摘要、音频片段计数和关闭/错误原因；第四批已把 `model/rerouted`、`thread/tokenUsage/updated`、`mcpServer/startupStatus/updated` 和 `remoteControl/status/changed` 归一成 `executionProgress.modelRoute / tokenUsage / mcpServers / remoteControl`，用于 APP “运行状态”区块。
 
-2026-06-01 第五批已把 `thread/goal/updated|cleared`、`thread/settings/updated` 和 `thread/compacted` 归一成 `executionProgress.threadGoal / threadSettings / compaction`，用于 APP “线程配置”区块；第六批已把 `account/updated`、`account/rateLimits/updated`、`model/verification`、`warning`、`configWarning`、`deprecationNotice` 归一成 `executionProgress.accountStatus / modelVerification / warnings`；第七批已把官方 `ThreadItem.collabToolCall` 归一成 `executionProgress.threadCollaboration`，并按官方建议把新版 `ThreadItem.contextCompaction` 映射回 `executionProgress.compaction`；第八批已把 `mcpToolCall`、`dynamicToolCall`、`webSearch`、`imageView`、`enteredReviewMode`、`exitedReviewMode` 和 `commandExecution` 归一成 `executionProgress.toolActivities`；第九批已把官方 `ThreadItem.plan` 的最终 `item/completed` 文本映射为 `executionProgress.steps`，并把 `ThreadItem.reasoning.summary` 映射为 `executionProgress.reasoningSummary`；第十批已把 `ThreadItem.imageGeneration` 安全映射为 `executionProgress.toolActivities` 的图像生成活动和 `executionProgress.artifacts` 的图片产物；第十一批已把 `hook/started|completed` 安全映射为 `executionProgress.toolActivities` 的钩子活动，供 APP 以“钩子”轻卡展示企业治理和插件生命周期状态；第十二批已把 `windowsSandbox/setupCompleted` 安全映射为 `executionProgress.windowsSandbox`，供 APP 在“运行状态”里展示 Windows 沙箱准备状态、setup mode 和脱敏错误摘要；第十三批已把 heartbeat discovery 扩展到 `experimentalFeature/list`、`collaborationMode/list`、`permissionProfile/list` 和 `mcpServerStatus/list`，供设备详情、APP 和 PC 后台看到实验特性、协作模式、权限 Profile 与 MCP 服务摘要；第十四批已把 `account/read`、`account/rateLimits/read`、`config/read`、`configRequirements/read` 和 `externalAgentConfig/detect` 纳入 heartbeat discovery，用于展示账号、套餐、额度、App 配置、托管要求和外部 Agent 迁移候选摘要；第十五批已把 `thread/list` 和 `thread/loaded/list` 纳入 heartbeat discovery，用于展示线程总数、已加载线程、活跃线程、归档线程和非归档可见线程轻量目录；第十六批已把 `thread/turns/list` 纳入 heartbeat discovery，用于展示总轮次、运行中轮次、完成轮次和每个非归档线程的最近 turn 状态摘要；第十七批已按 `codex-cli 0.136.0-alpha.2` 补齐 `skills/extraRoots/set`，支持把企业共享 Skill 根下发给 App Server 后再拉取 `skills/list`，并把新版 `ThreadItem.collabToolCall.receiverThreadIds / agentsStates` 安全映射成目标数量和 agent 状态集合。
+2026-06-01 第五批已把 `thread/goal/updated|cleared`、`thread/settings/updated` 和 `thread/compacted` 归一成 `executionProgress.threadGoal / threadSettings / compaction`，用于 APP “线程配置”区块；第六批已把 `account/updated`、`account/rateLimits/updated`、`model/verification`、`warning`、`configWarning`、`deprecationNotice` 归一成 `executionProgress.accountStatus / modelVerification / warnings`；第七批已把官方 `ThreadItem.collabToolCall` 归一成 `executionProgress.threadCollaboration`，并按官方建议把新版 `ThreadItem.contextCompaction` 映射回 `executionProgress.compaction`；第八批已把 `mcpToolCall`、`dynamicToolCall`、`webSearch`、`imageView`、`enteredReviewMode`、`exitedReviewMode` 和 `commandExecution` 归一成 `executionProgress.toolActivities`；第九批已把官方 `ThreadItem.plan` 的最终 `item/completed` 文本映射为 `executionProgress.steps`，并把 `ThreadItem.reasoning.summary` 映射为 `executionProgress.reasoningSummary`；第十批已把 `ThreadItem.imageGeneration` 安全映射为 `executionProgress.toolActivities` 的图像生成活动和 `executionProgress.artifacts` 的图片产物；第十一批已把 `hook/started|completed` 安全映射为 `executionProgress.toolActivities` 的钩子活动，供 APP 以“钩子”轻卡展示企业治理和插件生命周期状态；第十二批已把 `windowsSandbox/setupCompleted` 安全映射为 `executionProgress.windowsSandbox`，供 APP 在“运行状态”里展示 Windows 沙箱准备状态、setup mode 和脱敏错误摘要；第十三批已把 heartbeat discovery 扩展到 `experimentalFeature/list`、`collaborationMode/list`、`permissionProfile/list` 和 `mcpServerStatus/list`，供设备详情、APP 和 PC 后台看到实验特性、协作模式、权限 Profile 与 MCP 服务摘要；第十四批已把 `account/read`、`account/rateLimits/read`、`config/read`、`configRequirements/read` 和 `externalAgentConfig/detect` 纳入 heartbeat discovery，用于展示账号、套餐、额度、App 配置、托管要求和外部 Agent 迁移候选摘要；第十五批已把 `thread/list` 和 `thread/loaded/list` 纳入 heartbeat discovery，用于展示线程总数、已加载线程、活跃线程、归档线程和非归档可见线程轻量目录；第十六批已把 `thread/turns/list` 纳入 heartbeat discovery，用于展示总轮次、运行中轮次、完成轮次和每个非归档线程的最近 turn 状态摘要；第十七批已按 `codex-cli 0.136.0-alpha.2` 补齐 `skills/extraRoots/set`，支持把企业共享 Skill 根下发给 App Server 后再拉取 `skills/list`，并把新版 `ThreadItem.collabToolCall.receiverThreadIds / agentsStates` 安全映射成目标数量和 agent 状态集合；第十八批已把 `hooks/list` 纳入 heartbeat discovery，用于展示本机 Codex hook 数、启用数、信任状态和 warning/error 计数。
 
-`thread/realtime/sdp`、音频 base64、原始 realtime item、remote installationId、thread settings 的 `cwd`、compaction `turnId`、collaboration settings 内部 prompt、collabToolCall 源/目标线程 ID、`receiverThreadIds`、`agentsStates.message`、共享 Skill 根绝对路径、tool arguments/result/contentItems、web URL token、命令正文/输出、raw reasoning `content`、reasoning item id、imageGeneration 原始 result/revisedPrompt、hook id/sourcePath/statusMessage/entries、Windows sandbox sourcePath/samplePaths、本地绝对路径、permission profile 文件规则、MCP resource URI、账号邮箱、API key、完整 config、外部 Agent 迁移描述、turn id、turn items、turn 内容、用户正文、模型输出和未清洗的 MCP 错误不入账。
+`thread/realtime/sdp`、音频 base64、原始 realtime item、remote installationId、thread settings 的 `cwd`、compaction `turnId`、collaboration settings 内部 prompt、collabToolCall 源/目标线程 ID、`receiverThreadIds`、`agentsStates.message`、共享 Skill 根绝对路径、hook key/command/sourcePath/statusMessage/hash/error message、tool arguments/result/contentItems、web URL token、命令正文/输出、raw reasoning `content`、reasoning item id、imageGeneration 原始 result/revisedPrompt、hook id/sourcePath/statusMessage/entries、Windows sandbox sourcePath/samplePaths、本地绝对路径、permission profile 文件规则、MCP resource URI、账号邮箱、API key、完整 config、外部 Agent 迁移描述、turn id、turn items、turn 内容、用户正文、模型输出和未清洗的 MCP 错误不入账。
 
 官方文档入口：`https://developers.openai.com/codex/app-server`
 
@@ -41,10 +41,10 @@ Boss 不能直接把 App Server 原始 Thread / Turn / Item 字段写进业务
 - 本机 `codex --version`：`codex-cli 0.136.0-alpha.2`
 - 本机 `codex app-server --help` 已可用；本机 help 当前显示 `--listen` 支持 `stdio://`、`unix://`、`unix://PATH`、`ws://IP:PORT` 和 `off`
 - 本机 `codex app-server --help` 当前已经支持 `--ws-auth capability-token|signed-bearer-token`、`--ws-token-file`、`--ws-token-sha256`、`--ws-shared-secret-file`、issuer/audience/clock-skew 等 WebSocket 认证参数
-- 本机协议快照已生成到 `docs/protocol-snapshots/codex-app-server/0.136.0-alpha.2/`，共识别 138 个协议方法；确认支持 `thread/inject_items`、`thread/rollback`、`thread/goal/*`、`turn/steer`、`command/exec`、`thread/realtime/*`、`account/*`、`model/verification`、`configWarning`、`deprecationNotice`、`model/list` 和 `skills/extraRoots/set`
+- 本机协议快照已生成到 `docs/protocol-snapshots/codex-app-server/0.136.0-alpha.2/`，共识别 138 个协议方法；确认支持 `thread/inject_items`、`thread/rollback`、`thread/goal/*`、`turn/steer`、`command/exec`、`thread/realtime/*`、`account/*`、`model/verification`、`configWarning`、`deprecationNotice`、`model/list`、`skills/extraRoots/set` 和 `hooks/list`
 - Boss 当前默认仍以 `stdio` 作为本机 agent 接入方式；`ws://127.0.0.1:<port>` 和 `unix://PATH` 本地长驻 transport 已可灰度接入，WebSocket/Unix WebSocket handshake 支持 `Authorization: Bearer <token>`；非 loopback signed bearer/JWT、自动重连和健康探测仍保留为后续增强，不直接替换当前稳定链路
 - 官方文档提示 WebSocket ingress 满载时会返回 JSON-RPC `-32001 / Server overloaded; retry later.`；Boss runner 已对该错误做最多 3 次指数退避重试，避免长驻连接瞬时拥塞直接把用户任务打失败
-- Boss heartbeat 已新增 App Server 能力发现缓存：按 `codexAppServerDiscoveryTtlMs` 拉取 `model/list`、`modelProvider/capabilities/read`、`skills/list`、`plugin/list`、`app/list`、`experimentalFeature/list`、`collaborationMode/list`、`permissionProfile/list`、`mcpServerStatus/list`、`account/read`、`account/rateLimits/read`、`config/read`、`configRequirements/read`、`externalAgentConfig/detect`、`thread/list`、`thread/loaded/list` 和 `thread/turns/list`；配置了 `codexAppServerSkillExtraRoots` / `BOSS_CODEX_APP_SERVER_SKILL_EXTRA_ROOTS` 时，会先调用 `skills/extraRoots/set` 再拉取 `skills/list`，归一成设备 `capabilities.codexAppServer.metadata`；发现失败只记录 warn，不阻塞心跳。MCP discovery 使用 `detail=toolsAndAuthOnly`，turn discovery 固定 `itemsView=notLoaded`，账号、配置、线程和 Skill extra root discovery 只保留安全摘要，不保存邮箱、resource URI、工具参数、完整 config、本地路径、迁移描述、turn id、turn items、用户正文、模型输出或共享 Skill 根绝对路径。
+- Boss heartbeat 已新增 App Server 能力发现缓存：按 `codexAppServerDiscoveryTtlMs` 拉取 `model/list`、`modelProvider/capabilities/read`、`skills/list`、`hooks/list`、`plugin/list`、`app/list`、`experimentalFeature/list`、`collaborationMode/list`、`permissionProfile/list`、`mcpServerStatus/list`、`account/read`、`account/rateLimits/read`、`config/read`、`configRequirements/read`、`externalAgentConfig/detect`、`thread/list`、`thread/loaded/list` 和 `thread/turns/list`；配置了 `codexAppServerSkillExtraRoots` / `BOSS_CODEX_APP_SERVER_SKILL_EXTRA_ROOTS` 时，会先调用 `skills/extraRoots/set` 再拉取 `skills/list`，归一成设备 `capabilities.codexAppServer.metadata`；发现失败只记录 warn，不阻塞心跳。MCP discovery 使用 `detail=toolsAndAuthOnly`，turn discovery 固定 `itemsView=notLoaded`，账号、配置、线程、Hook 和 Skill extra root discovery 只保留安全摘要，不保存邮箱、resource URI、工具参数、完整 config、本地路径、迁移描述、turn id、turn items、用户正文、模型输出、hook 命令或共享 Skill 根绝对路径。
 - Boss 第一批只用 App Server 做任务级 provider，不直接复用 ChatGPT Mobile 到 Codex App 的官方 relay；官方移动控制链路仍属于 ChatGPT App 与 Codex App 同账号/工作区之间的产品能力，不是第三方 Boss 可以稳定依赖的私有通道
 
 下一轮再核对版本时，不要只看 npm 包版本号；必须同时读取 App Server schema / TypeScript 定义，并把 protocol snapshot 保存到 `docs/protocol-snapshots/codex-app-server/<version>/`。
@@ -150,6 +150,7 @@ UI 参考：
 - 新增 App Server 过载退避：单个 JSON-RPC 请求收到 `-32001` 或 `retry later` 文案时，会在同一个任务生命周期内重试，超出上限后才进入失败/CLI fallback 判定
 - 新增 App Server capability discovery：`local-agent` 会把可用模型、默认/快速/深度模型建议、provider 能力、Skill、Plugin、App 摘要写入设备 heartbeat；Web 设备详情已显示 App Server、模型和扩展数量，为后续 APP/后台模型配置页提供真实数据来源
 - 新增 App Server 共享 Skill 根下发：配置 `codexAppServerSkillExtraRoots` 或 `BOSS_CODEX_APP_SERVER_SKILL_EXTRA_ROOTS` 后，runner 会在 discovery 阶段调用 `skills/extraRoots/set`，再刷新 `skills/list`；设备详情页展示“共享 Skill 根：N 个 · 已下发/下发失败”，metadata 只保存数量、basename 和状态，不保存绝对路径
+- 新增 App Server Hook 治理 discovery：runner 会调用 `hooks/list` 并写入 `hookSummary`，设备详情页展示“Hook：N 个 · 启用 N 个 · 警告 N 个”；metadata 只保存计数、事件名和 handler 类型，不保存 hook key、command、sourcePath、statusMessage、hash、error message 或本地路径
 
 后续建议按两步继续：