For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/reference/events.md.
agent-bundle
  • English

      • Event and hook matrix

      Generated page

      This page is rendered at documentation build time from the pinned host capability tables claude-2.1.250.json, codex-0.147.0.json, cursor-2026-08-28.json, portable-1.0.0.json. Those JSON files are the source of truth every target adapter compiles against; change them, not this page.

      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.

      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.

      Canonical eventclaude 2.1.250codex 0.147.0cursor 2026-08-28portable 1.0.0
      agent/idleTeammateIdleunavailableunavailableunavailable
      agent/startSubagentStartSubagentStartsubagentStart (cloud: supported; desktop: supported)unavailable
      agent/stopSubagentStopSubagentStopsubagentStop (cloud: supported; desktop: supported)unavailable
      compact/afterPostCompactPostCompactunavailableunavailable
      compact/beforePreCompactPreCompactpreCompact (cloud: supported; desktop: supported)unavailable
      config/changeConfigChangeunavailableunavailableunavailable
      file/changeFileChangedunavailableunavailableunavailable
      permission/deniedPermissionDeniedunavailableunavailableunavailable
      permission/requestPermissionRequestPermissionRequestunavailableunavailable
      prompt/submitUserPromptSubmitUserPromptSubmitbeforeSubmitPrompt (cloud: supported; desktop: supported)unavailable
      session/endSessionEndSessionEndsessionEnd (cloud: unavailable; desktop: supported)unavailable
      session/startSessionStartSessionStartsessionStart (cloud: unavailable; desktop: supported)unavailable
      stopStopStopstop (cloud: supported; desktop: supported)unavailable
      stop/failureStopFailureunavailableunavailableunavailable
      task/completeTaskCompletedunavailableunavailableunavailable
      task/createTaskCreatedunavailableunavailableunavailable
      tool/afterPostToolUsePostToolUsepostToolUse (cloud: supported; desktop: supported)unavailable
      tool/beforePreToolUsePreToolUsepreToolUse (cloud: supported; desktop: supported)unavailable
      tool/failurePostToolUseFailureunavailablepostToolUseFailure (cloud: supported; desktop: supported)unavailable
      workspace/openunavailableunavailableworkspaceOpen (cloud: unavailable; desktop: supported)unavailable

      Why a route is 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.

      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.

      Config keyclaude 2.1.250codex 0.147.0cursor 2026-08-28
      afterToolPostToolUsePostToolUsepostToolUse
      agentStartSubagentStartSubagentStartsubagentStart
      agentStopSubagentStopSubagentStopsubagentStop
      beforeToolPreToolUsePreToolUsepreToolUse
      sessionStartSessionStartSessionStartsessionStart
      stopStopStopstop

      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.

      Selectorclaude 2.1.250codex 0.147.0cursor 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$

      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.250

      Native eventStateReason
      ConfigChange-policy_settingsunavailableretrieved 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.
      CwdChangedunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: host environment callback outside the canonical application-event vocabulary (#258 defer list).
      DirectoryAddedunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: host workspace-registration callback outside the canonical application-event vocabulary (#258 defer list).
      Elicitationunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: MCP protocol callback outside the canonical application-event vocabulary (#258 defer list).
      ElicitationResultunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: MCP protocol callback outside the canonical application-event vocabulary (#258 defer list).
      InstructionsLoadedunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: host context-load callback outside the canonical application-event vocabulary (#258 defer list).
      MessageDisplayunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: UI display callback outside the canonical application-event vocabulary (#258 defer list).
      Notificationunavailableretrieved 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).
      PostModelSwitchunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: model-lifecycle callback outside the canonical application-event vocabulary (#258 defer list).
      PostToolBatchunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: batch-scheduling callback outside the canonical application-event vocabulary (#258 defer list).
      PreModelSwitchunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: model-lifecycle callback outside the canonical application-event vocabulary (#258 defer list).
      Setupunavailableretrieved 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).
      UserPromptExpansionunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: command-expansion callback outside the canonical application-event vocabulary (#258 defer list).
      WorktreeCreateunavailableretrieved 2026-09-02 from https://code.claude.com/docs/en/hooks: worktree-provisioning callback outside the canonical application-event vocabulary (#258 defer list).
      WorktreeRemoveunavailableretrieved 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

      Native eventStateReason
      Interruptunavailableretrieved 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

      Native eventStateReason
      afterAgentResponseunavailableretrieved 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.
      afterAgentThoughtunavailableretrieved 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.
      afterFileEditunavailableretrieved 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.
      afterMCPExecutionunavailableretrieved 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.
      afterShellExecutionunavailableretrieved 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.
      afterTabFileEditunavailableretrieved 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.
      beforeMCPExecutionunavailableretrieved 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.
      beforeReadFileunavailableretrieved 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.
      beforeShellExecutionunavailableretrieved 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.
      beforeTabFileReadunavailableretrieved 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.