docs: distinguish extension events from hooks

README.md

@@ -44,7 +44,8 @@ Spec Kit combines ready-to-use processes with composable mechanisms:
 | Connect to or switch between coding agents | [Integration](https://github.github.io/spec-kit/reference/integrations.html) |
 | Add a command, quality gate, or complete process | [Extension](https://github.github.io/spec-kit/reference/extensions.html) |
 | Connect a process to an external tool or service | [Extension](https://github.github.io/spec-kit/reference/extensions.html) |
-| React to coding-agent lifecycle events | [Extension event hook](https://github.github.io/spec-kit/reference/extensions.html#project-extension-and-hook-configuration) |
+| React to coding-agent lifecycle events | [Extension runtime event](https://github.github.io/spec-kit/reference/extensions.html#extension-runtime-events) |
+| Run extension commands before or after Spec Kit commands | [Extension hook](https://github.github.io/spec-kit/reference/extensions.html#project-extension-and-hook-configuration) |
 | Adapt templates, commands, terminology, or methodology | [Preset](https://github.github.io/spec-kit/reference/presets.html) |
 | Enforce organizational or regulatory standards | [Preset](https://github.github.io/spec-kit/reference/presets.html) |
 | Override a template for one project | [Project-local override](https://github.github.io/spec-kit/guides/customization.html#project-local-overrides-and-resolution) |

docs/reference/extensions.md

@@ -294,6 +294,33 @@ cp .specify/extensions/<ext>/<ext>-config.template.yml \
    .specify/extensions/<ext>/<ext>-config.yml
 ```
 
+## Extension Runtime Events
+
+Extensions can react to coding-agent lifecycle events by declaring a top-level
+`events` mapping in `extension.yml`:
+
+```yaml
+events:
+  session_start:
+    command: speckit.my-extension.initialize
+  pre_tool_use:
+    command: speckit.my-extension.validate
+```
+
+Event declarations are integration-agnostic. Spec Kit refreshes every installed
+event-capable integration, and each integration translates the canonical event
+names into its coding agent's native event configuration. Supported canonical
+events are `session_start`, `pre_tool_use`, `post_tool_use`,
+`user_prompt_submit`, `stop`, and `session_end`; each integration may support
+only a subset.
+
+Runtime events are distinct from extension hooks. Events react to the coding
+agent's lifecycle and execute the referenced command template's `scripts`
+entry directly. The referenced command must therefore provide a runnable
+script; its Markdown instructions are not sent to the coding agent. Hooks
+instead surface extension commands before or after Spec Kit commands such as
+`plan`, `tasks`, and `implement`.
+
 ## Project Extension and Hook Configuration
 
 Spec Kit stores project-level extension registration and hook configuration in: