Skip to content

feat(hooks): async 后台观测钩子——8 并发上限、永不阻断、结果仅审计 - #570

Merged
Qiyuanqiii merged 4 commits into
mainfrom
feat/async-hooks
Nov 12, 2026
Merged

Qiyuanqiii merged 4 commits into
mainfrom
feat/async-hooks

Conversation

@Qiyuanqiii

Copy link
Copy Markdown
Member

改动背景

继续对齐 Claude Code 与 Codex 的 hooks 能力:两者的 hook 都支持 async: true 后台观测(Claude Code 异步 hooks;Codex 后台 hooks 每会话 8 并发上限、不能阻断),用于遥测、webhook 通知、指标打点——慢速 tap 不再拖累每个工具调用。本项目的 hook 全部同步(声明式 2 秒、脚本 10 秒上限),操作者的半秒 webhook 脚本要在其订阅的每个边界付一次延迟。

本 PR 堆叠在 #565(其又堆叠在 #564、#563)之上,base 为 feat/hook-tool-matchers;请按 #563 → #564 → #565 → 本 PR 顺序合并,base 会随前序合并自动重定向到 main。

关键设计

  • 后台即纯观测:只有 record 与 script 动作可声明 async: true;deny/annotate/narrow 必须同步——边界从不等待的 hook 不可能阻断调用,也不可能 annotate 调用方已经拿到的结果。后台脚本自行输出的 denied 仅记录审计、从不生效。
  • 有界并发、不排队:引擎级 8 槽信号量(与 Codex 文档化的每会话上限一致);过载的触发以 failed_continue 审计行跳过,而不是阻塞或排队——结果词表不变,web 诊断解析零漂移。
  • 边界永不等待:后台执行在分离上下文(保留 value、按声明自身超时重置 deadline)中运行;结果全部丢弃,仅 metadata-only 审计记录 completed / failed_continue(rejected=false);进程退出时未完成的后台 hook 丢失——已文档化,不做持久化。
  • 同信任同边界:声明校验完全复用(script 规格、工具过滤器、身份);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/httpapi Hook/Extension 子集通过;投影链:docs/openapi.json 再生成 → schema.d.ts → 前端 exact-keys + async 校验(drift 用例 4 个)→ 声明面板"后台观测"标记;typecheck 通过、vitest 34/34。
  • 文档:docs/extensions.md 双语 async 契约;新增 ADR 0200。

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.
@coderabbitai

coderabbitai Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

Explain Change →

Caution

Review failed

The pull request is closed.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@Qiyuanqiii
Qiyuanqiii changed the base branch from feat/hook-tool-matchers to main November 12, 2026 03:15
@Qiyuanqiii
Qiyuanqiii merged commit 41d042d into main Nov 12, 2026
19 of 32 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants