# Events and Hooks API

## Event/Hook Operations

### `on`

Subscribe to an editor event
Handler must be a global function name (not a closure).
Multiple handlers can be registered for the same event.
Events: "buffer_save", "cursor_moved", "buffer_modified", etc.

```typescript
on(event_name: string, handler_name: string): boolean
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| `event_name` | `string` | Event to subscribe to |
| `handler_name` | `string` | Name of globalThis function to call with event data |

**Example:**

```typescript
globalThis.onSave = (data) => {
editor.setStatus(`Saved: ${data.path}`);
};
editor.on("buffer_save", "onSave");
```

#### `off`

Unregister an event handler

```typescript
off(event_name: string, handler_name: string): boolean
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| `event_name` | `string` | Name of the event |
| `handler_name` | `string` | Name of the handler to remove |

#### `getHandlers`

Get list of registered handlers for an event

```typescript
getHandlers(event_name: string): string[]
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| `event_name` | `string` | Name of the event |

## Window / Orchestrator events

These events fire as the editor's window set changes. (The
editor internally calls these "windows", modelled on VS Code
windows; Orchestrator's UX presents them as "sessions" — they're
the same thing.) See `docs/internal/orchestrator-sessions-design.md`
for the full window model.

| Event | Payload | When it fires |
|-------|---------|---------------|
| `window_created` | `{ id, label, root }` | A new session was created (via `editor.createWindow` or session restore on startup) |
| `window_closed` | `{ id }` | A session was closed |
| `active_window_changed` | `{ previous, current }` | The active session changed (warm-swap completed) |
| `terminal_output` | `{ terminal_id, data }` | A terminal produced output. Useful for plugins watching agent activity in background sessions. |
| `terminal_exit` | `{ terminal_id, exit_code }` | A terminal's child process exited. `exit_code` may be `null` on signal-terminated processes. |
| `path_changed` | `{ handle, path, kind }` | A path watched via `editor.watchPath(...)` changed. `kind` is `"create"`, `"modify"`, or `"remove"`. |
