#事件与钩子矩阵

src/events/** 下的事件路由与配置声明的 hooks 都基于同一组按宿主固定的表编译。规范事件会降级为此处列出的宿主原生事件。不具备该事件的宿主没有可降级的目标，因此仍然选中该宿主的路由或 hook 会让构建失败（<target>.hook.event.*，显式配置 hook 目标则为 AB4204）：请通过路由的 config.targets 或 hook 的 targets 排除该宿主。未显式声明 targets 的配置 hook 只继承所选宿主中支持 hook 的那些，因此不受支持的宿主会在那里被跳过且不产生诊断。每个不可用单元格都记录其原因，而非推断。Amp 事件单元格来自固定版本 PluginAPI 的契约核对；现场派发仍为 runtime-unverified。

#规范事件路由

行是 src/events/<family>/*.tsx 路由可以声明的规范事件族；列是固定宿主。单元格给出该路由降级到的原生事件。

#路由不可用的原因

#amp 0.0.1788739286-gf348fe

• agent/idle — PluginEventMap declares no idle event.
• agent/start — Amp agent.start is a user turn, not a subagent-start event.
• agent/stop — PluginEventMap declares no subagent-stop event.
• compact/after — PluginEventMap declares no compaction event.
• compact/before — PluginEventMap declares no compaction event.
• config/change — PluginEventMap declares no configuration-change event.
• file/change — PluginEventMap declares no file-change event.
• model-switch/after — PluginEventMap declares no model-switch event.
• model-switch/before — PluginEventMap declares no model-switch event.
• permission/denied — PluginEventMap declares no separate permission-denied event.
• permission/request — Permission control is part of tool.call; no separate permission event is declared.
• session/end — Amp explicitly documents that no session.end event exists.
• stop/failure — PluginEventMap declares no separate failed-stop event.
• task/complete — PluginEventMap declares no task lifecycle event.
• task/create — PluginEventMap declares no task lifecycle event.
• tool/failure — Failures are a tool.result status, not a separate PluginEventMap event.
• workspace/open — PluginEventMap declares no workspace-open event.

#claude 2.1.260

• workspace/open — The pinned Claude Code 2.1.260 hooks contract has no workspace-open event.

#codex 0.147.0

• agent/idle — retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no teammate-idle event.
• config/change — retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no config-change event.
• file/change — retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no file-changed event.
• model-switch/after — 2026-09-03: the complete rust-v0.147.0 generated hook schema directory contains no post-model-switch event, and https://learn.chatgpt.com/docs/hooks (retrieved 2026-09-02) documents no model-switch hook.
• model-switch/before — 2026-09-03: the complete rust-v0.147.0 generated hook schema directory contains no pre-model-switch event, and https://learn.chatgpt.com/docs/hooks (retrieved 2026-09-02) documents no model-switch hook.
• permission/denied — retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no permission-denied event.
• stop/failure — retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no stop-failure event.
• task/complete — retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no task-completed event.
• task/create — retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory contains no task-created event.
• tool/failure — retrieved 2026-09-02: the complete rust-v0.147.0 generated hook schema directory and native event inventory contain no tool-failure event.
• workspace/open — The pinned Codex 0.147.0 hooks contract has no workspace-open event.

#cursor 2026-08-28

• agent/idle — retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no teammate-idle event.
• compact/after — retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no postCompact event.
• config/change — retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no configChange event.
• file/change — retrieved 2026-09-02: Cursor documents afterFileEdit as an agent-edit tool variant that overlaps canonical tool/after per the #258 selector rule, not a disk-watch FileChanged equivalent; no dedicated family is inferred without fixture evidence of loss.
• model-switch/after — 2026-09-03: https://cursor.com/docs/hooks (retrieved 2026-09-02) documents no hook that runs after the session model changes; the model reaches Cursor hooks only as the model input field of session-scoped events.
• model-switch/before — 2026-09-03: https://cursor.com/docs/hooks (retrieved 2026-09-02) documents no hook that runs before a model switch and no output that could block one.
• permission/denied — retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no permission-denied event.
• permission/request — retrieved 2026-09-02: https://cursor.com/docs/hooks documents no standalone permission-request event; pre-tool permission control is beforeShellExecution/beforeMCPExecution and is not inferred as this family per #258.
• stop/failure — retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no stop-failure event.
• task/complete — retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no taskCompleted event.
• task/create — retrieved 2026-09-02: the complete https://cursor.com/docs/hooks event inventory documents no taskCreated event.
• session/end (cloud) — retrieved 2026-09-02: https://cursor.com/docs/hooks states cloud agents have no editor-lifetime session boundary, so sessionEnd is unavailable there.
• session/start (cloud) — retrieved 2026-09-02: https://cursor.com/docs/hooks defers cloud sessionStart while cloud agents can begin in a read-only environment where hooks do not load, so it would fire too late; Self-Hosted Machines workers fire it when a session claims the worker.
• workspace/open (cloud) — retrieved 2026-09-02: https://cursor.com/docs/hooks states workspaceOpen is an IDE lifecycle hook that does not apply to cloud agents.

#portable 1.0.0

• agent/idle — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native TeammateIdle equivalent (https://agent-plugins.org/).
• agent/start — Agent Plugins 1.0.0 does not define hooks.
• agent/stop — Agent Plugins 1.0.0 does not define hooks.
• compact/after — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native PostCompact equivalent (https://agent-plugins.org/).
• compact/before — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native PreCompact/preCompact equivalent (https://agent-plugins.org/).
• config/change — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native ConfigChange equivalent (https://agent-plugins.org/).
• file/change — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native FileChanged equivalent (https://agent-plugins.org/).
• model-switch/after — 2026-09-03: Agent Plugins 1.0.0 defines no hooks and therefore no native PostModelSwitch equivalent (https://agent-plugins.org/).
• model-switch/before — 2026-09-03: Agent Plugins 1.0.0 defines no hooks and therefore no native PreModelSwitch equivalent (https://agent-plugins.org/).
• permission/denied — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native PermissionDenied equivalent (https://agent-plugins.org/).
• permission/request — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native PermissionRequest equivalent (https://agent-plugins.org/).
• prompt/submit — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native UserPromptSubmit/beforeSubmitPrompt equivalent (https://agent-plugins.org/).
• session/end — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native SessionEnd/sessionEnd equivalent (https://agent-plugins.org/).
• session/start — Agent Plugins 1.0.0 does not define hooks.
• stop — Agent Plugins 1.0.0 does not define hooks.
• stop/failure — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native StopFailure equivalent (https://agent-plugins.org/).
• task/complete — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native TaskCompleted equivalent (https://agent-plugins.org/).
• task/create — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native TaskCreated equivalent (https://agent-plugins.org/).
• tool/after — Agent Plugins 1.0.0 does not define hooks.
• tool/before — Agent Plugins 1.0.0 does not define hooks.
• tool/failure — 2026-09-02: Agent Plugins 1.0.0 defines no hooks and therefore no native PostToolUseFailure/postToolUseFailure equivalent (https://agent-plugins.org/).
• workspace/open — Agent Plugins 1.0.0 does not define hooks.

#规范载荷字段

事件路由收到的 canonical.payload（AgentEventRouteProps<E>）：每个事件族一张表，每个规范字段一行，每个支持该事件族的宿主一列。单元格给出该字段读取自的宿主键——字段以 { value, nativeKey } 的形式到达，nativeKey 恰为该键——— 表示宿主从不发送该字段，因此它在那里是 undefined，而非被伪造。标有 → json-string 的键是框架会解析的 JSON 编码字符串（不是合法 JSON 时保留为字符串）；→ positive-count 表示把计数读作布尔值。没有任何两个宿主共有的字段留在 native 上。

#agent/idle

#agent/start

#agent/stop

#compact/after

#compact/before

#config/change

#file/change

#model-switch/after

#model-switch/before

#permission/denied

#permission/request

#prompt/submit

#session/end

#session/start

#stop

#stop/failure

#task/complete

#task/create

#tool/after

#tool/before

#tool/failure

#workspace/open

#配置声明的钩子事件

agent-bundle.config.ts 的 hooks 块以这些规范名称为键；每个键映射到目标注册的原生事件。

#规范工具选择器

限定 tools 的钩子或事件路由使用这些规范选择器；每个适配器发出下表中的原生匹配器。目标无法映射的选择器会产生针对该目标的诊断，而不是空匹配器。

#推迟的宿主原生事件

各宿主公布但尚无规范路由族的原生事件，以及推迟它们的记录原因。

#claude 2.1.260

#codex 0.147.0

#cursor 2026-08-28