doc: add event topics reference

doc/event-topics.md

@@ -0,0 +1,73 @@
+# Event Topics Reference
+
+All events published to the `event` stream follow hierarchical topic naming.
+
+## Topic Format
+
+```
+session.{sessionId}.{type}
+session.{sessionId}.agent.{agentId}.{type}
+```
+
+## Session Events
+
+| Topic | Payload | Description |
+|-------|---------|-------------|
+| `session.{sid}.new` | `{name}` | Session created |
+| `session.{sid}.kill` | — | Session destroyed |
+| `session.{sid}.rename` | `{oldName} {newName}` | Session renamed |
+| `session.{sid}.pause` | — | Session paused |
+| `session.{sid}.resume` | — | Session resumed |
+| `session.{sid}.bypass.request` | `{id}\t{cmd}\t{cwd}` | Bypass approval requested |
+
+## Agent Events
+
+| Topic | Payload | Description |
+|-------|---------|-------------|
+| `session.{sid}.agent.{aid}.new` | — | Agent created |
+| `session.{sid}.agent.{aid}.kill` | — | Agent destroyed |
+| `session.{sid}.agent.{aid}.state` | `{state}` | State changed (idle, calling, thinking, paused) |
+
+## Filter Patterns
+
+Subscribe to specific events using the streaming rdwr pattern:
+
+```bash
+# All events
+ollie-9p read event
+
+# All session events
+echo "session.*" | ollie-9p rdwrs event
+
+# State changes for all agents
+echo "session.*.agent.*.state" | ollie-9p rdwrs event
+
+# All events for one session
+echo "session.abc123.>" | ollie-9p rdwrs event
+
+# Bypass requests only
+echo "session.*.bypass.>" | ollie-9p rdwrs event
+```
+
+## Filter Syntax
+
+| Pattern | Matches |
+|---------|---------|
+| `*` | Exactly one segment |
+| `>` | One or more segments (must be last) |
+| `literal` | Exact match |
+
+## Hierarchical Publishing
+
+Events are published to their topic and all parent wildcards:
+
+```
+session.abc.agent.xyz.state
+  → session.abc.agent.xyz.*
+  → session.abc.agent.*
+  → session.abc.*
+  → session.*
+  → *
+```
+
+This allows subscribing at any level of granularity.