#Event and hook matrix

Event routes under src/events/** and config-declared hooks both compile against the same per-host tables. A canonical event lowers to the host-native event named here. A host without that event has nothing to lower to, so a route or hook that still selects that host fails the build (<target>.hook.event.*, or AB4204 for an explicit config-hook target): exclude the host through the route's config.targets or the hook's targets. A config hook with no explicit targets inherits only the selected hosts that support hooks, so unsupported hosts are skipped there without a diagnostic. Every unavailable cell records its reason rather than inferring one. Amp event cells are contract-verified from the pinned PluginAPI; live dispatch remains runtime-unverified.

#Canonical event routes

Rows are the canonical event families a src/events/<family>/*.tsx route may declare; columns are the pinned hosts. A cell names the native event the route lowers to.

#Why a route is unavailable

#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 fields

The canonical.payload an event route receives (AgentEventRouteProps<E>): one table per family, one row per canonical field, one column per host that supports the family. A cell names the host key the field is read from — the field arrives as { value, nativeKey } with exactly that key as its provenance — and — means the host never sends it, so the field is undefined there rather than fabricated. A key marked → json-string is a JSON-encoded string the framework parses (kept as the string when it is not valid JSON); → positive-count is a counter read as a boolean. Fields no host shares stay on 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

#Config-declared hook events

The hooks block of agent-bundle.config.ts is keyed by these canonical names; each maps to the native event a target registers.

#Canonical tool selectors

A hook or event route that scopes tools uses these canonical selectors; each adapter emits the native matcher below. A selector a target cannot map is a per-target diagnostic, never an empty matcher.

#Deferred host-native events

Native events each host publishes that have no canonical route family yet, with the recorded reason for deferring them.

#claude 2.1.260

#codex 0.147.0

#cursor 2026-08-28