Repository navigation
feat(hooks): async 后台观测钩子——8 并发上限、永不阻断、结果仅审计 - #570
Merged
Merged
Conversation
Add async: true to hook declarations for observation taps. Only record and script actions may run asynchronously, both require the continue failure policy, and the engine runs them outside the boundary on a detached context: the boundary never waits, the result is discarded, and only the audit ledger records the outcome. Background scripts receive the same stdin payload as synchronous ones. An engine-wide eight-slot semaphore skips an overloaded fire with a failed_continue audit row written on its own detached context, so saturation and hook timeouts can never suppress it, and declared timeouts still kill background children. Unfinished background hooks are lost at process exit; this is documented rather than persisted. The plugin diagnostics projection exposes the async flag, the OpenAPI snapshot and the generated TypeScript schema are regenerated, and the web hook diagnostics parser and declared-rules view learn the new field.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
改动背景
继续对齐 Claude Code 与 Codex 的 hooks 能力:两者的 hook 都支持
async: true后台观测(Claude Code 异步 hooks;Codex 后台 hooks 每会话 8 并发上限、不能阻断),用于遥测、webhook 通知、指标打点——慢速 tap 不再拖累每个工具调用。本项目的 hook 全部同步(声明式 2 秒、脚本 10 秒上限),操作者的半秒 webhook 脚本要在其订阅的每个边界付一次延迟。关键设计
record与script动作可声明async: true;deny/annotate/narrow 必须同步——边界从不等待的 hook 不可能阻断调用,也不可能 annotate 调用方已经拿到的结果。后台脚本自行输出的denied仅记录审计、从不生效。failed_continue审计行跳过,而不是阻塞或排队——结果词表不变,web 诊断解析零漂移。completed/failed_continue(rejected=false);进程退出时未完成的后台 hook 丢失——已文档化,不做持久化。async参与 registry generation 指纹;后台脚本子进程仍受声明超时击杀;诊断投影暴露async标志。与竞品的显式取舍:Claude Code 对异步 hooks"超时不强制",本项目仍强制声明超时(其 fail-closed 文化);Codex 的上限是每会话,本项目的自然作用域是引擎(每 app/desktop 宿主一个),审计行保留了 Run 归属。
验证方式
go vet、gofmt、go test -race -count=1 ./internal/hooks/通过。internal/hooks:异步校验(deny/annotate/narrow 拒绝、record/script 任意事件接受)、边界结果零污染(Executed/Annotations 空、无 deny)、完成与失败审计行、8 并发上限 + 跳过审计行 + 释放后全部完成、失败记录——全部在 race detector 下运行(测试 sink 已加锁)。internal/httpapiHook/Extension 子集通过;投影链:docs/openapi.json再生成 →schema.d.ts→ 前端 exact-keys + async 校验(drift 用例 4 个)→ 声明面板"后台观测"标记;typecheck通过、vitest 34/34。docs/extensions.md双语 async 契约;新增 ADR 0200。