事件与钩子矩阵

生成页面

本页在文档构建时由固定版本的宿主能力表 claude-2.1.250.json、codex-0.147.0.json、cursor-2026-08-28.json、portable-1.0.0.json 渲染而成。这些 JSON 文件是每个目标适配器编译时依赖的唯一事实来源；请修改它们而不是本页。表格内容保留英文原文。

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

规范事件路由

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

规范事件	claude 2.1.250	codex 0.147.0	cursor 2026-08-28	portable 1.0.0
`agent/idle`	`TeammateIdle`	unavailable	unavailable	unavailable
`agent/start`	`SubagentStart`	`SubagentStart`	`subagentStart` (cloud: supported; desktop: supported)	unavailable
`agent/stop`	`SubagentStop`	`SubagentStop`	`subagentStop` (cloud: supported; desktop: supported)	unavailable
`compact/after`	`PostCompact`	`PostCompact`	unavailable	unavailable
`compact/before`	`PreCompact`	`PreCompact`	`preCompact` (cloud: supported; desktop: supported)	unavailable
`config/change`	`ConfigChange`	unavailable	unavailable	unavailable
`file/change`	`FileChanged`	unavailable	unavailable	unavailable
`permission/denied`	`PermissionDenied`	unavailable	unavailable	unavailable
`permission/request`	`PermissionRequest`	`PermissionRequest`	unavailable	unavailable
`prompt/submit`	`UserPromptSubmit`	`UserPromptSubmit`	`beforeSubmitPrompt` (cloud: supported; desktop: supported)	unavailable
`session/end`	`SessionEnd`	`SessionEnd`	`sessionEnd` (cloud: unavailable; desktop: supported)	unavailable
`session/start`	`SessionStart`	`SessionStart`	`sessionStart` (cloud: unavailable; desktop: supported)	unavailable
`stop`	`Stop`	`Stop`	`stop` (cloud: supported; desktop: supported)	unavailable
`stop/failure`	`StopFailure`	unavailable	unavailable	unavailable
`task/complete`	`TaskCompleted`	unavailable	unavailable	unavailable
`task/create`	`TaskCreated`	unavailable	unavailable	unavailable
`tool/after`	`PostToolUse`	`PostToolUse`	`postToolUse` (cloud: supported; desktop: supported)	unavailable
`tool/before`	`PreToolUse`	`PreToolUse`	`preToolUse` (cloud: supported; desktop: supported)	unavailable
`tool/failure`	`PostToolUseFailure`	unavailable	`postToolUseFailure` (cloud: supported; desktop: supported)	unavailable
`workspace/open`	unavailable	unavailable	`workspaceOpen` (cloud: unavailable; desktop: supported)	unavailable

路由不可用的原因

claude 2.1.250

workspace/open — The pinned Claude Code 2.1.250 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.
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.
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/).
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.

配置声明的钩子事件

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

配置键	claude 2.1.250	codex 0.147.0	cursor 2026-08-28
`afterTool`	`PostToolUse`	`PostToolUse`	`postToolUse`
`agentStart`	`SubagentStart`	`SubagentStart`	`subagentStart`
`agentStop`	`SubagentStop`	`SubagentStop`	`subagentStop`
`beforeTool`	`PreToolUse`	`PreToolUse`	`preToolUse`
`sessionStart`	`SessionStart`	`SessionStart`	`sessionStart`
`stop`	`Stop`	`Stop`	`stop`

规范工具选择器

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

选择器	claude 2.1.250	codex 0.147.0	cursor 2026-08-28
`agent`	—	—	`^Task$`
`file.read`	`^Read$`	—	`^Read$`
`file.write`	`^(?:Write\|Edit)$`	`^(?:apply_patch\|Edit\|Write)$`	`^Write$`
`mcp`	`^mcp__`	`^mcp__`	`^MCP:`
`shell`	`^Bash$`	`^Bash$`	`^Shell$`

推迟的宿主原生事件

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

claude 2.1.250

宿主原生事件	状态	原因
`ConfigChange-policy_settings`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: ConfigChange block decisions cannot stop policy_settings changes; recorded so the config/change family's deny channel is not overstated.
`CwdChanged`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: host environment callback outside the canonical application-event vocabulary (#258 defer list).
`DirectoryAdded`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: host workspace-registration callback outside the canonical application-event vocabulary (#258 defer list).
`Elicitation`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: MCP protocol callback outside the canonical application-event vocabulary (#258 defer list).
`ElicitationResult`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: MCP protocol callback outside the canonical application-event vocabulary (#258 defer list).
`InstructionsLoaded`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: host context-load callback outside the canonical application-event vocabulary (#258 defer list).
`MessageDisplay`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: UI display callback outside the canonical application-event vocabulary (#258 defer list).
`Notification`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: delivery-channel surface tracked by #99 delivery evidence, not an application event route (#258 defer list).
`PostModelSwitch`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: model-lifecycle callback outside the canonical application-event vocabulary (#258 defer list).
`PostToolBatch`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: batch-scheduling callback outside the canonical application-event vocabulary (#258 defer list).
`PreModelSwitch`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: model-lifecycle callback outside the canonical application-event vocabulary (#258 defer list).
`Setup`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: one-time init/maintenance callback outside the canonical application-event vocabulary (#258 defer list).
`UserPromptExpansion`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: command-expansion callback outside the canonical application-event vocabulary (#258 defer list).
`WorktreeCreate`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: worktree-provisioning callback outside the canonical application-event vocabulary (#258 defer list).
`WorktreeRemove`	unavailable	retrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: worktree-provisioning callback outside the canonical application-event vocabulary (#258 defer list).

codex 0.147.0

宿主原生事件	状态	原因
`Interrupt`	unavailable	retrieved 2026-09-02: https://learn.chatgpt.com/docs/hooks now documents Interrupt (main-thread turn interruption; matcher ignored; one-second default and three-second maximum timeout; systemMessage-only output), but the pinned rust-v0.147.0 generated hook schema directory has no interrupt.command.{input,output}.schema.json (those files exist only on main), and Agent Bundle has no canonical interrupt event route (#97 owns route expansion). Deferred until the Codex pin moves to a release that ships the generated Interrupt schemas; authored native Interrupt hooks fail closed with codex.native-hooks.event.deferred.

cursor 2026-08-28

宿主原生事件	状态	原因
`afterAgentResponse`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: native/deferred until a canonical consumer is accepted (#258 defer list). Input is { text } with no output fields; matcher value AgentResponse; runs in cloud agents.
`afterAgentThought`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: native/deferred until a canonical consumer is accepted (#258 defer list). Input is { text, duration_ms? } with no output fields; matcher value AgentThought; runs in cloud agents.
`afterFileEdit`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: agent-edit variant overlapping canonical tool/after per the #258 selector rule (postToolUse with the ^Write$ matcher fires for the same edit); a dedicated family requires a canonical-vocabulary decision because the native input { file_path, edits[{ old_string, new_string }] } carries per-edit diffs the generic tool_output string does not, and no output fields are documented. Matcher is the tool type (TabWrite, Write); runs in cloud agents.
`afterMCPExecution`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: native variant of canonical tool/after with mcp selector per the #258 selector rule (postToolUse with the ^MCP: matcher). Native input adds mcp_server_name, mcp_server_url, result_json, and duration with no output fields; deferred while cloud agents cannot run it.
`afterShellExecution`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: native variant of canonical tool/after with shell selector per the #258 selector rule (postToolUse with the ^Shell$ matcher). Native input is { command, output, duration, sandbox } with raw terminal output rather than the JSON-stringified tool_output, and no output fields; matcher is the full command string; runs in cloud agents.
`afterTabFileEdit`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: Tab-surface callback, native/deferred until a canonical consumer is accepted (#258 defer list). Only Tab triggers it, edits carry range/old_line/new_line, no output fields, and Tab hooks do not run in cloud agents.
`beforeMCPExecution`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: native variant of canonical tool/before with mcp selector per the #258 selector rule (preToolUse with the ^MCP: matcher). Native input adds mcp_server_name plus url/mcp_server_url (HTTP) or command (stdio) and its output admits permission ask, which the canonical deny/continue vocabulary does not express; deferred while cloud agents cannot run it.
`beforeReadFile`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: native variant of canonical tool/before with file.read selector per the #258 selector rule (preToolUse with the ^Read$ matcher). Native input adds content and attachments and its output is { permission allow\|deny, user_message }; failClosed is documented for it; matcher is the tool type (TabRead, Read); runs in cloud agents.
`beforeShellExecution`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: native variant of canonical tool/before with shell selector per the #258 selector rule (preToolUse with the ^Shell$ matcher). Native input is { command, cwd, sandbox } and its output admits permission ask, which the canonical deny/continue vocabulary does not express; matcher is the full command string; runs in cloud agents.
`beforeTabFileRead`	unavailable	retrieved 2026-09-02 from https://cursor.com/docs/hooks: Tab-surface callback, native/deferred until a canonical consumer is accepted (#258 defer list). Only Tab triggers it, there is no attachments field, output is { permission allow\|deny }, and Tab hooks do not run in cloud agents.

#事件与钩子矩阵

#规范事件路由

#路由不可用的原因

#claude 2.1.250

#codex 0.147.0

#cursor 2026-08-28

#portable 1.0.0

#配置声明的钩子事件

#规范工具选择器

#推迟的宿主原生事件

#claude 2.1.250

#codex 0.147.0

#cursor 2026-08-28

事件与钩子矩阵

规范事件路由

路由不可用的原因

claude 2.1.250

codex 0.147.0

cursor 2026-08-28

portable 1.0.0

配置声明的钩子事件

规范工具选择器

推迟的宿主原生事件

claude 2.1.250

codex 0.147.0

cursor 2026-08-28