From c00d8a1b85548739d07d4e709798330b973c0aad Mon Sep 17 00:00:00 2001
From: omartelo <meopedevts@proton.me>
Date: Thu, 13 Aug 2026 10:59:53 -0300
Subject: [PATCH] feat: report omp (oh-my-pi) sessions to lich

omp is the fifth harness and the second that loads a module instead of
running commands: `--hook` and `--extension` are one list it `import()`s,
so even the files it calls hooks are modules, never scripts fed a payload
on stdin. `omp/lich.js` is the whole client, mirroring opencode/lich.js.

The mapping, measured against omp v17.3.0 driving a real run at a stub
listener:

- session id from `ctx.sessionManager.getSessionId()` at `session_start`
  (omp exports nothing about the session to its process env)
- `busy` on `input`, and on `turn_start` for the turns no input precedes
- the tool line on `tool_call`
- the git-status refresh on a `tool_result` from write/edit/bash/notebook
- `done` plus the generated title when a turn settles

`waiting` and `idle` are deliberately unreported: omp's approval event was
never observed on a real run, and a name taken off a type declaration is a
report that silently never fires; the process that would send `idle` is
the one exiting.

The outside-lich gate is in the module, not in a registration: omp
discovers `~/.claude` and `~/.omp` wholesale, so a global install loads on
every omp run on the machine.

Needs `omp` registered as a provider id in lich; until then the
session-start report is rejected and the other three land. The suite
asserts that payload against every contract rule except the one the
missing fixture case trips, and goes back to the shared assertion on its
own the day the case lands upstream.
---
 CHANGELOG.md            |  28 +++
 CLAUDE.md               |  23 +-
 README.md               |  21 +-
 docs/providers.md       |  93 +++++++--
 docs/session-start.md   |  26 ++-
 docs/session-state.md   |  52 +++--
 docs/session-title.md   |  14 +-
 docs/session-touched.md |  13 +-
 omp/lich.js             | 166 +++++++++++++++
 tests/omp.test.mjs      | 452 ++++++++++++++++++++++++++++++++++++++++
 10 files changed, 826 insertions(+), 62 deletions(-)
 create mode 100644 omp/lich.js
 create mode 100644 tests/omp.test.mjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c7dab69..b7cf12f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **omp (oh-my-pi) sessions report to lich.** A fifth harness, and the second
+  that loads a module rather than running commands: omp merges `--hook` and
+  `--extension` into one list and `import()`s every entry, so even the files it
+  calls hooks are modules. `omp/lich.js` is the whole client — the session id off
+  `ctx.sessionManager.getSessionId()` at `session_start`, `busy` on `input` and
+  `turn_start`, the tool line on `tool_call`, the git-status refresh on a
+  `tool_result` from `write`/`edit`/`bash`/`notebook`, and `done` plus the
+  generated title when a turn settles. Install is the file plus a line:
+  `~/.omp/agent/extensions/lich.js`, or any path named in `extensions:` in
+  `~/.omp/agent/config.yml`.
+
+  Two states are deliberately absent. Nothing reports `waiting`: omp has an
+  approval event, but it was never observed on a real run here, and a name taken
+  off a type declaration is a report that silently never fires — so an omp card
+  shows a spinner, not a bell, while the agent waits on you. Nothing reports
+  `idle` either, for the same reason no opencode session does: the process that
+  would send it is the one exiting.
+
+  The gate lives in the module rather than in a registration. omp discovers
+  `~/.claude` and `~/.omp` configuration wholesale, so a global install is loaded
+  by every omp run on the machine; with no lich environment the factory
+  subscribes to nothing at all.
+
+  Needs `omp` registered as a provider id in lich — until then the session-id
+  report is rejected and the card holds no id, while the other three land.
+
 ## [0.9.2] - 2026-08-12
 
 ### Fixed
diff --git a/CLAUDE.md b/CLAUDE.md
index 5da6912..5b92032 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # lich-plugin
 
-The agent side of the integration with **lich** — a harness that orchestrates agent CLI sessions. This companion plugin is how lich observes and acts inside a running session. It ships hooks — each following a contract documented in `docs/` — plus skills for work that targets lich itself. One plugin, packaged for **Claude Code**, **OpenAI Codex**, **opencode** and **Crush** from the same repository root.
+The agent side of the integration with **lich** — a harness that orchestrates agent CLI sessions. This companion plugin is how lich observes and acts inside a running session. It ships hooks — each following a contract documented in `docs/` — plus skills for work that targets lich itself. One plugin, packaged for **Claude Code**, **OpenAI Codex**, **opencode**, **omp** (oh-my-pi) and **Crush** from the same repository root.
 
 ## Structure
 
@@ -14,14 +14,17 @@ hooks/codex-hooks.json            # hook registration, Codex
 hooks/crush-hooks.json            # hook registration, Crush (hand-merged into crush.json)
 hooks/                            # hook scripts ($CLAUDE_PLUGIN_ROOT/hooks/<script>, all three)
 opencode/lich.js                  # opencode client: a module, not a command
+omp/lich.js                       # omp client: a module, not a command
 docs/                             # lich ⇄ plugin communication contracts
 skills/                           # skills (skills/<name>/SKILL.md, all)
 tests/                            # hook payloads asserted against lich's fixtures
 ```
 
-Two harnesses do not fit the script model, each its own way. **opencode** runs no
-commands: a plugin there is a JavaScript module its server imports, so all four
-reports live in `opencode/lich.js`. **Crush** runs the scripts unchanged — its
+Three harnesses do not fit the script model, each its own way. **opencode** runs
+no commands: a plugin there is a JavaScript module its server imports, so all
+four reports live in `opencode/lich.js`. **omp** has a `--hook` flag but merges
+it with `--extension` into one list it `import()`s, so its "hooks" are modules
+too, and its client is `omp/lich.js`. **Crush** runs the scripts unchanged — its
 hooks are Claude Code-compatible down to the stdin payload — but has exactly one
 event, `PreToolUse`, so only the session id and the touched refresh are
 registered for it.
@@ -34,6 +37,7 @@ Contracts are **canonical in the lich repository** (`docs/hooks/` there); this p
 - [docs/session-start.md](docs/session-start.md) — Claude session id via `SessionStart`
 - [docs/session-title.md](docs/session-title.md) — auto-generated `ai-title` via `Stop`
 - [docs/session-touched.md](docs/session-touched.md) — git-status refresh signal via `PostToolUse` (file-mutating tools only)
+- [docs/providers.md](docs/providers.md) — the per-harness map, including what installing on omp takes and what it cannot report
 
 Each doc carries the event mapping for **every** provider, one column each — a contract is implemented once and registered per harness. [docs/providers.md](docs/providers.md) is the map: which file each harness reads, where the event vocabularies differ, and what adding another provider takes. A harness that cannot close a state does not get that report registered: an unendable `busy` is worse on a card than a card with no indicator.
 
@@ -57,8 +61,12 @@ environment → no report, exit 0 on a 500 or a refused connection).
 opencode module, which is imported rather than spawned, and fed the event
 payloads a real opencode run emits — including the sub-session ones it must
 drop and the listener that never answers, which must not hold the turn.
+[tests/omp.test.mjs](tests/omp.test.mjs) does the same for the omp module,
+against the events and `ctx.sessionManager` methods measured on omp v17.3.0 —
+pinned in a comment there, because 17.x moves fast — plus the rule that outside
+lich it subscribes to nothing at all.
 [tests/contract.mjs](tests/contract.mjs) is the fixtures, the assertions and the
-stub, shared so both clients answer to the same lines. Node only, no
+stub, shared so every client answers to the same lines. Node only, no
 dependencies.
 
 The fixtures are vendored in `tests/fixtures/` from lich
@@ -75,8 +83,9 @@ the network; CI diffs the copies against upstream and fails on drift.
 - A hook must never block or fail the user's turn: short timeout, errors swallowed, always exit 0. On Codex the exit code is louder still — `2` on `PermissionRequest` denies the request, so silence and exit 0 are what keep a report an observation.
 - Outside lich (env vars absent) every hook is a no-op with exit 0 — the plugin must be safe to install globally.
 - A skill must be useful from any working directory: the user runs the agent CLI on their own project, not on the lich checkout.
-- One script per contract, shared by every provider that runs commands. Registration differs per harness, the report does not — extend a script to read a second transcript format before adding a second script. A harness that runs no commands at all is the one case for a client of its own, which is what `opencode/lich.js` is; it still sends the same payloads to the same endpoints.
-- opencode awaits its plugin hooks, so `lich.js` never awaits a report and never throws — that is its version of "always exit 0".
+- One script per contract, shared by every provider that runs commands. Registration differs per harness, the report does not — extend a script to read a second transcript format before adding a second script. A harness that runs no commands at all is the one case for a client of its own, which is what `opencode/lich.js` and `omp/lich.js` are; they still send the same payloads to the same endpoints.
+- opencode and omp both await their plugin handlers, so neither `lich.js` ever awaits a report or throws — that is their version of "always exit 0". The omp one also subscribes to nothing outside lich: omp loads it on every run on the machine, so the gate has to be in the module.
+- **A module client names only events it was measured emitting.** A name read off a type declaration is a report that silently never fires, which is worse than an absent feature — the omp `waiting` state is left unreported for exactly this reason.
 
 ## Local testing
 
diff --git a/README.md b/README.md
index 7b9f78f..f6ad3d8 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,13 @@
 # lich-plugin
 
-The agent side of the [lich](https://github.com/omartelo/lich) integration. lich is a harness that orchestrates agent CLI sessions; this companion plugin gives it eyes and hands inside each session. It installs on **Claude Code**, **OpenAI Codex**, **opencode** and **Crush** from this same repository. Every hook implements a contract that is canonical in the lich repository (`docs/hooks/` there); the docs in `docs/` here point at each contract and describe the client side:
+The agent side of the [lich](https://github.com/omartelo/lich) integration. lich is a harness that orchestrates agent CLI sessions; this companion plugin gives it eyes and hands inside each session. It installs on **Claude Code**, **OpenAI Codex**, **opencode**, **omp** (oh-my-pi) and **Crush** from this same repository. Every hook implements a contract that is canonical in the lich repository (`docs/hooks/` there); the docs in `docs/` here point at each contract and describe the client side:
 
 - **session state** — `busy`/`done` on the session card (`UserPromptSubmit`/`Stop`)
 - **session start** — persists the agent's session id on the lich session (`SessionStart`)
 - **session title** — names the card after the session's own title (`Stop`)
 - **session touched** — refreshes the card's git status right after file-mutating tools (`PostToolUse`)
 
-The four are what Claude Code, Codex and opencode report. **Crush reports two of them** — its session id and the git-status refresh — because `PreToolUse` is the only event it has, and a state nothing can end is worse on a card than no state. [docs/providers.md](docs/providers.md) has the event mapping per harness.
+The four are what Claude Code, Codex, opencode and omp report. **Crush reports two of them** — its session id and the git-status refresh — because `PreToolUse` is the only event it has, and a state nothing can end is worse on a card than no state. **omp reports all four minus the bell**: no event of its own for "your turn" has been measured yet, so its card shows a spinner while the agent waits on you. [docs/providers.md](docs/providers.md) has the event mapping per harness.
 
 On **opencode** it also carries the other direction: the seven operations lich
 offers a session for driving the sessions beside it — list, send, wait, reply,
@@ -37,12 +37,13 @@ hooks/report-session-start.sh     # session-start hook
 hooks/report-title.sh             # session-title hook
 hooks/report-touched.sh           # session-touched hook
 opencode/lich.js                  # opencode client: all four reports plus the seven tools, one module
+omp/lich.js                       # omp client: the reports, one module
 docs/                             # client-side docs, one per contract
 skills/theme/                     # theme skill: SKILL.md, template.json, validate.mjs
 tests/                            # hook payloads asserted against lich's fixtures
 ```
 
-One set of hook scripts serves Claude Code, Codex and Crush — they live in `hooks/` and are referenced via `$CLAUDE_PLUGIN_ROOT/hooks/<script>`, a variable Codex sets too. opencode runs no commands: a plugin there is a module its server imports, so its client is the single file `opencode/lich.js`, sending the same payloads to the same endpoints. [docs/providers.md](docs/providers.md) maps the layout and every harness's event names.
+One set of hook scripts serves Claude Code, Codex and Crush — they live in `hooks/` and are referenced via `$CLAUDE_PLUGIN_ROOT/hooks/<script>`, a variable Codex sets too. opencode and omp run no commands: in both, what gets loaded is a JavaScript module, so each has a single-file client — `opencode/lich.js` and `omp/lich.js` — sending the same payloads to the same endpoints. [docs/providers.md](docs/providers.md) maps the layout and every harness's event names.
 
 ## Installation
 
@@ -78,6 +79,18 @@ curl -fsSL -o ~/.config/opencode/plugin/lich.js \
 
 Per project instead of globally, use `.opencode/plugin/lich.js`. Updating means fetching the file again.
 
+### omp (oh-my-pi)
+
+omp has no marketplace of its own either, and its `--hook` and `--extension` flags are one list of modules. It scans `~/.omp/agent/extensions/` without being told, so dropping the file there is the install:
+
+```bash
+mkdir -p ~/.omp/agent/extensions
+curl -fsSL -o ~/.omp/agent/extensions/lich.js \
+  https://raw.githubusercontent.com/omartelo/lich-plugin/main/omp/lich.js
+```
+
+To keep it somewhere else, name the path instead — `omp config set extensions '["/path/to/lich.js"]'`, which writes `extensions:` in `~/.omp/agent/config.yml` — or pass `--hook /path/to/lich.js` for a single run. Per project, `.omp/extensions/lich.js` works the same way. Updating means fetching the file again.
+
 ### Crush
 
 Crush has no plugin system either: its hooks live in your own `crush.json`. Clone this repository, then merge [`hooks/crush-hooks.json`](hooks/crush-hooks.json) into `~/.config/crush/crush.json` (global) or the project's `crush.json`, replacing `<lich-plugin>` with the absolute path of the clone:
@@ -131,4 +144,4 @@ claude --plugin-dir .
 node --test tests/*.test.mjs
 ```
 
-Every hook script runs as a real subprocess, from the command line its registration spells, against a stub HTTP server — and the body it POSTs is asserted against [lich's contract fixtures](https://github.com/omartelo/lich/tree/main/docs/hooks/fixtures): an accepted shape, never a rejected one, the right endpoint and token, plus the client rules (no lich environment → no report; exit 0 when lich answers 500 or refuses the connection). The opencode module is imported instead of spawned and fed the events a real opencode run emits, against the same fixtures. Both share `tests/contract.mjs`. The fixtures are vendored in `tests/fixtures/` by `tests/refresh-fixtures.sh`; CI diffs them against upstream so a contract that moves in lich goes red here.
+Every hook script runs as a real subprocess, from the command line its registration spells, against a stub HTTP server — and the body it POSTs is asserted against [lich's contract fixtures](https://github.com/omartelo/lich/tree/main/docs/hooks/fixtures): an accepted shape, never a rejected one, the right endpoint and token, plus the client rules (no lich environment → no report; exit 0 when lich answers 500 or refuses the connection). The opencode and omp modules are imported instead of spawned and fed the events a real run of each emits, against the same fixtures. All three share `tests/contract.mjs`. The fixtures are vendored in `tests/fixtures/` by `tests/refresh-fixtures.sh`; CI diffs them against upstream so a contract that moves in lich goes red here.
diff --git a/docs/providers.md b/docs/providers.md
index 654a5e5..846c252 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -19,6 +19,7 @@ This repository is one plugin, packaged for each harness it supports:
 | `hooks/crush-hooks.json`        | Crush       | hook registration, merged by hand |
 | `hooks/*.sh`                    | the three   | the reports themselves        |
 | `opencode/lich.js`              | opencode    | the whole client, as a module |
+| `omp/lich.js`                   | omp         | the whole client, as a module |
 | `skills/`                       | all         | skills, same layout           |
 
 The repository root is the plugin root for Claude Code and Codex, so a single
@@ -29,26 +30,29 @@ on stdin with `session_id` and `transcript_path` (and `tool_name` /
 the installed plugin — Codex sets that same variable, so the command lines are
 identical.
 
-**opencode is the exception, and it is a packaging one.** It has no notion of a
-hook command: a plugin there is a JavaScript module the opencode server imports,
-which subscribes to an event bus instead of being spawned per event. So the four
-reports live in one file, `opencode/lich.js`, which posts the same payloads to
-the same endpoints. Nothing about the contracts changes; what changes is that
-there is no process to exit 0 from, so the module swallows its own errors and
-never awaits a report.
+**opencode and omp are the exceptions, and both are packaging ones.** Neither
+has a notion of a hook command. In opencode a plugin is a JavaScript module the
+server imports, which subscribes to an event bus instead of being spawned per
+event. omp arrives at the same place from the other side: it *has* a `--hook`
+flag, but `--hook` and `--extension` are one list and every entry is loaded with
+`import()` — even the files it calls hooks are modules, never scripts fed a
+payload on stdin. So each gets one file, `opencode/lich.js` and `omp/lich.js`,
+posting the same payloads to the same endpoints. Nothing about the contracts
+changes; what changes is that there is no process to exit 0 from, so the module
+swallows its own errors and never awaits a report.
 
 ## Event vocabulary
 
-| Report              | Claude Code                  | Codex                        | opencode                  | Crush                       |
-|---------------------|------------------------------|------------------------------|---------------------------|-----------------------------|
-| session id          | `SessionStart`               | `SessionStart`               | `session.created`         | `PreToolUse`                |
-| `busy`              | `UserPromptSubmit`, `PostToolUse` | `UserPromptSubmit`, `PostToolUse` | `session.status` (`busy`) | —              |
-| `busy` + tool       | `PreToolUse`                 | `PreToolUse`                 | `tool.execute.before`     | —                           |
-| `waiting`           | `Notification`               | `PermissionRequest`          | any `*.asked`             | —                           |
-| `done`              | `Stop`                       | `Stop`                       | `session.status` (`idle`) | —                           |
-| title               | `Stop`                       | `Stop`                       | `session.updated`         | —                           |
-| `idle`              | `SessionEnd`                 | — (registered, never fires)  | — (nothing outlives it)   | —                           |
-| touched             | `PostToolUse` (write tools)  | `PostToolUse` (write tools)  | `file.edited`             | `PreToolUse` (write tools)  |
+| Report              | Claude Code                  | Codex                        | opencode                  | omp                      | Crush                       |
+|---------------------|------------------------------|------------------------------|---------------------------|--------------------------|-----------------------------|
+| session id          | `SessionStart`               | `SessionStart`               | `session.created`         | `session_start`          | `PreToolUse`                |
+| `busy`              | `UserPromptSubmit`, `PostToolUse` | `UserPromptSubmit`, `PostToolUse` | `session.status` (`busy`) | `input`, `turn_start` | —              |
+| `busy` + tool       | `PreToolUse`                 | `PreToolUse`                 | `tool.execute.before`     | `tool_call`              | —                           |
+| `waiting`           | `Notification`               | `PermissionRequest`          | any `*.asked`             | — (see below)            | —                           |
+| `done`              | `Stop`                       | `Stop`                       | `session.status` (`idle`) | `session_stop`           | —                           |
+| title               | `Stop`                       | `Stop`                       | `session.updated`         | `session_stop`, `turn_start` | —                       |
+| `idle`              | `SessionEnd`                 | — (registered, never fires)  | — (nothing outlives it)   | — (nothing outlives it)  | —                           |
+| touched             | `PostToolUse` (write tools)  | `PostToolUse` (write tools)  | `file.edited`             | `tool_result` (write tools) | `PreToolUse` (write tools) |
 
 Every cell above was taken off a real run of that harness against a stub
 listener, not off its documentation.
@@ -129,6 +133,61 @@ waits.
   dropped, with a 1s timeout, and its failure is swallowed — the module's version
   of "always exit 0".
 
+## omp specifics
+
+Everything below was measured against omp v17.3.0
+(`@oh-my-pi/pi-coding-agent`), driving a real `omp --hook … -p …` run at a stub
+listener. 17.x moves fast — re-measure before trusting a name.
+
+- **`--hook` is `--extension`.** omp merges both flags into one list of
+  extension paths and imports every entry, so a "hook" there is a module
+  exporting a default factory, called with omp's API object. Its *other*
+  hooks — `hooks/pre/<tool>.sh` — are imported the same way rather than run, so
+  there is no script-and-stdin path anywhere in omp to reuse the `hooks/*.sh`
+  scripts from.
+- **It loads only `module.default`.** Unlike opencode, which calls every export
+  of a plugin file, omp reads one and warns if it is not a function.
+- **The session id is on the context, not in the environment.** omp exports
+  nothing about the running session to its own process env; every handler gets
+  `ctx.sessionManager`, whose `getSessionId()` is the id, and `getSessionFile()`
+  the transcript path. `omp -r <id>` resumes from that id.
+- **The gate is inside the module.** omp discovers configuration from `~/.omp`,
+  `~/.claude`, `~/.codex` and `~/.gemini` wholesale, and there is no per-harness
+  registration to key on, so a global install is loaded by every omp run on the
+  machine. Outside lich the factory subscribes to nothing at all.
+- **`input` is interactive-only.** It fires when the user submits a prompt,
+  which is what lich spawns — but a `-p` run has no `input` at all, so
+  `turn_start` carries `busy` there. It is also the recovery the script
+  harnesses get from `PostToolUse`: every turn passes through it.
+- **Nothing reports `waiting`.** omp raises `tool_approval_requested` when it
+  asks to run something, but that was not observed on a real run here (the
+  measured runs never reached an approval), and an unmeasured event name is a
+  report that silently never fires. Until it is measured, an omp card shows the
+  spinner while the agent waits on you.
+- **Nothing reports `idle` either.** The event that would say "the CLI has left"
+  is the process exiting with this module inside it. Like a Codex or an opencode
+  card, an omp card holds its last indicator until lich respawns its terminal.
+- **Never awaited.** omp awaits its extension handlers, so a report that blocked
+  would sit in front of the agent's next step. Every `fetch` is fired and
+  dropped, with a 1s timeout, and its failure is swallowed — the module's version
+  of "always exit 0". Handlers are synchronous and return nothing: `tool_call`
+  returning `{block: true}` would refuse the user's tool call.
+- **Install is a file plus a line.** Drop the module anywhere and name it in
+  `~/.omp/agent/config.yml` under `extensions:`, or drop it straight into
+  `~/.omp/agent/extensions/`, which omp scans without being told. Both were
+  measured; there is no manifest and no marketplace entry of omp's own.
+- **omp reads Claude Code plugins, but not their hooks.** It loads
+  `~/.claude/plugins/cache/` and takes skills, slash commands, custom tools and
+  MCP servers from them — honouring `.omp-plugin/plugin.json` before
+  `.claude-plugin/plugin.json`. `hooks/hooks.json` is read by nothing there, so
+  installing this repository as a Claude plugin gives an omp session the skills
+  and none of the reports.
+- **MCP has no command-line flag.** omp reads Claude-Desktop-shaped
+  `{"mcpServers": …}` from `~/.omp/agent/mcp.json` (and `.omp/mcp.json`,
+  `<cwd>/.mcp.json`), expanding `${VAR}` and `${VAR:-default}` from the process
+  environment — so a session token can ride in on the variables lich already
+  injects. The `--config` overlay does *not* take MCP servers.
+
 ## Crush specifics
 
 - **One event exists: `PreToolUse`.** Crush's hooks are Claude Code-compatible
diff --git a/docs/session-start.md b/docs/session-start.md
index e6aa843..606a986 100644
--- a/docs/session-start.md
+++ b/docs/session-start.md
@@ -8,9 +8,9 @@ Reports the agent CLI's own session id so lich can persist the link between its
 session (the card) and the agent session running inside it. lich stores it as
 the *provider* session id — the field is provider-agnostic.
 
-| script                             | action                          | Claude Code hook | Codex hook     | opencode event    | Crush hook   |
-|------------------------------------|---------------------------------|------------------|----------------|-------------------|--------------|
-| `report-session-start.sh <provider>` | send the CLI's `session_id`   | `SessionStart`   | `SessionStart` | `session.created` | `PreToolUse` |
+| script                             | action                          | Claude Code hook | Codex hook     | opencode event    | omp event       | Crush hook   |
+|------------------------------------|---------------------------------|------------------|----------------|-------------------|-----------------|--------------|
+| `report-session-start.sh <provider>` | send the CLI's `session_id`   | `SessionStart`   | `SessionStart` | `session.created` | `session_start` | `PreToolUse` |
 
 `POST /session-start` with `{"session_id": $LICH_SESSION_ID,
 "provider_session_id": <session_id from the hook payload on stdin>, "provider":
@@ -19,7 +19,8 @@ the *provider* session id — the field is provider-agnostic.
 The provider id comes from the registration, not from the payload: the scripts
 are shared, the hook files are not, so `hooks.json` passes `claude`,
 `codex-hooks.json` passes `codex` and `crush-hooks.json` passes `crush`.
-`opencode/lich.js` has no registration to read it from and spells its own.
+`opencode/lich.js` and `omp/lich.js` have no registration to read it from and
+spell their own.
 lich keys the card's icon on it — a hand-run `codex` inside a shell session
 marks that card as Codex, not as Claude. An omitted argument defaults to
 `claude`, which is also how lich reads a report from a plugin older than this
@@ -35,10 +36,19 @@ Crush included, whose hooks are Claude Code-compatible — so one script serves
 them. It uses `jq` to read the payload when present, and falls back to `sed`
 otherwise — so it also works on Windows, where `jq` is usually absent.
 
-The two newer harnesses report from the earliest place each offers. opencode
-raises `session.created` before the first turn, as early as `SessionStart`.
-**Crush only has `PreToolUse`**, so its id rides the first tool call and a
-conversation that answers without a tool never sends one — late, not wrong.
+The module harnesses report from the earliest place each offers. opencode raises
+`session.created` before the first turn, as early as `SessionStart`; omp's
+`session_start` fires at the same point, and the id itself is read off
+`ctx.sessionManager.getSessionId()` rather than off the event, which carries
+nothing but its type. **Crush only has `PreToolUse`**, so its id rides the first
+tool call and a conversation that answers without a tool never sends one — late,
+not wrong.
+
+**`omp` is not a registered provider id upstream yet.** This client sends it
+because it is the only correct value, and the day lich adds it to its provider
+list the card wears omp's icon and resumes with `omp -r <id>` — omp keeps a
+session per file, so that check has something to find, unlike opencode's and
+Crush's SQLite. Until then lich rejects the report and the card holds no id.
 
 The report doubles as proof that an agent runs in that PTY, so lich also marks
 the card as running that provider (its icon) until the mark is cleared — which
diff --git a/docs/session-state.md b/docs/session-state.md
index e6369a7..2cd77a0 100644
--- a/docs/session-state.md
+++ b/docs/session-state.md
@@ -8,21 +8,31 @@ Reports the session's processing state so the lich card shows a spinner while
 the agent works, a check when the turn ends, and a bell (plus an actionable
 toast) when the agent is blocked on the user.
 
-| script                    | state            | Claude Code hook   | Codex hook          | opencode event            |
-|---------------------------|------------------|--------------------|---------------------|---------------------------|
-| `report-state.sh busy`    | `busy`           | `UserPromptSubmit` | `UserPromptSubmit`  | `session.status` (`busy`) |
-| `report-tool.sh`          | `busy` + `tool`  | `PreToolUse`       | `PreToolUse`        | `tool.execute.before`     |
-| `report-state.sh busy`    | `busy`           | `PostToolUse`      | `PostToolUse`       | `session.status` (`busy`) |
-| `report-state.sh done`    | `done`           | `Stop`             | `Stop`              | `session.status` (`idle`) |
-| `report-state.sh waiting` | `waiting`        | `Notification`     | `PermissionRequest` | any `*.asked`             |
-| `report-state.sh idle`    | `idle`           | `SessionEnd`       | — (never fires)     | — (never fires)           |
-
-opencode runs no scripts: `opencode/lich.js` sends the same payloads off the
-event bus, and its `session.status` carries the state rather than implying it —
-`idle` there is the turn ending, which is this contract's `done`. **Crush is
+| script                    | state            | Claude Code hook   | Codex hook          | opencode event            | omp event       |
+|---------------------------|------------------|--------------------|---------------------|---------------------------|-----------------|
+| `report-state.sh busy`    | `busy`           | `UserPromptSubmit` | `UserPromptSubmit`  | `session.status` (`busy`) | `input`         |
+| `report-tool.sh`          | `busy` + `tool`  | `PreToolUse`       | `PreToolUse`        | `tool.execute.before`     | `tool_call`     |
+| `report-state.sh busy`    | `busy`           | `PostToolUse`      | `PostToolUse`       | `session.status` (`busy`) | `turn_start`    |
+| `report-state.sh done`    | `done`           | `Stop`             | `Stop`              | `session.status` (`idle`) | `session_stop`  |
+| `report-state.sh waiting` | `waiting`        | `Notification`     | `PermissionRequest` | any `*.asked`             | — (not measured)|
+| `report-state.sh idle`    | `idle`           | `SessionEnd`       | — (never fires)     | — (never fires)           | — (never fires) |
+
+opencode and omp run no scripts: `opencode/lich.js` and `omp/lich.js` send the
+same payloads off the events their harness hands a loaded module. opencode's
+`session.status` carries the state rather than implying it — `idle` there is the
+turn ending, which is this contract's `done`. omp implies it like the script
+harnesses do, and its `turn_start` is the `PostToolUse → busy` of that column:
+every turn passes through it, including the ones no `input` precedes. **Crush is
 absent from the table on purpose**: its only event is `PreToolUse`, and a `busy`
 nothing can end would pin a spinner to a card. See [providers.md](providers.md).
 
+**omp reports no `waiting`.** It raises `tool_approval_requested` when it asks to
+run something, but that event was never observed on a real run here, and a name
+taken off a type declaration is a report that silently never fires. An omp card
+therefore shows a spinner, not a bell, while the agent waits on you — one state
+late, never wrong. The event is the first thing to measure when someone can drive
+an approval prompt.
+
 `POST /hook` with `{"session_id": $LICH_SESSION_ID, "state":
 "busy"|"done"|"waiting"|"idle"}`, plus the optional `tool` / `detail` pair the
 pre-tool report adds.
@@ -79,19 +89,23 @@ always exit 0) stop being merely polite here.
 What the two harnesses actually send, taken off a real run of each against a
 stub listener rather than off their documentation:
 
-| Action        | Claude Code       | Codex                     | opencode         |
-|---------------|-------------------|---------------------------|------------------|
-| run a command | `Bash`            | `Bash`                    | `bash`           |
-| edit a file   | `Edit` / `Write`  | `apply_patch`             | `edit` / `write` |
-| read a file   | `Read`            | — (goes through `Bash`)   | `read`           |
-| search        | `Grep` / `Glob`   | — (goes through `Bash`)   | `grep` / `glob`  |
+| Action        | Claude Code       | Codex                     | opencode         | omp              |
+|---------------|-------------------|---------------------------|------------------|------------------|
+| run a command | `Bash`            | `Bash`                    | `bash`           | `bash`           |
+| edit a file   | `Edit` / `Write`  | `apply_patch`             | `edit` / `write` | `edit` / `write` |
+| read a file   | `Read`            | — (goes through `Bash`)   | `read`           | `read`           |
+| search        | `Grep` / `Glob`   | — (goes through `Bash`)   | `grep` / `glob`  | `grep` / `glob`  |
 
 The `detail` is read by field, never by tool name — `command`, then
 `file_path` / `path`, then `pattern` / `url` / `query` — which is what makes one
 rule cover both: a Codex shell call arrives as `Bash` carrying the same
 `command` string Claude Code sends. opencode spells the same fields in camel
 case (`filePath`) and hands over paths already relative to the session, so
-`lich.js` reads the same list and skips the shortening below.
+`lich.js` reads the same list and skips the shortening below. omp's built-ins
+spell it `path` (read, write, edit, glob), `command` (bash) or `pattern`
+(grep) — also already relative — and `omp/lich.js` keeps the camel-case and
+`query` / `url` spellings after them, for the tools omp does not define itself:
+an extension's or an MCP server's, named however their author named them.
 
 Two shapes need more than the plain rule:
 
diff --git a/docs/session-title.md b/docs/session-title.md
index d01f6cd..11529ad 100644
--- a/docs/session-title.md
+++ b/docs/session-title.md
@@ -8,9 +8,9 @@ Reports the title the agent CLI gives its own session, so lich can name the
 session card after it. lich only applies it while the card's label is still
 automatic, so re-sending on every `Stop` is idempotent.
 
-| script            | action                    | Claude Code hook | Codex hook | opencode event    | Crush hook |
-|-------------------|---------------------------|------------------|------------|-------------------|------------|
-| `report-title.sh` | send the session's title  | `Stop`           | `Stop`     | `session.updated` | —          |
+| script            | action                    | Claude Code hook | Codex hook | opencode event    | omp event                    | Crush hook |
+|-------------------|---------------------------|------------------|------------|-------------------|------------------------------|------------|
+| `report-title.sh` | send the session's title  | `Stop`           | `Stop`     | `session.updated` | `session_stop`, `turn_start` | —          |
 
 `POST /session-title` with `{"session_id": $LICH_SESSION_ID, "title": <title>}`.
 Both providers keep the title in the transcript file (`transcript_path` on
@@ -31,5 +31,13 @@ and the hook no-ops. Requires `jq`; absent → no-op.
   session is created with is a placeholder built from its timestamp, so the
   module keeps that first value and reports only a title that differs from it.
   It arrives more than once per turn, which the idempotence above covers.
+- **omp** — no transcript to read either: the title is on the session manager
+  every handler is handed, as `ctx.sessionManager.getSessionName()`. omp writes
+  it asynchronously after a turn, so the turn that produced it may well settle
+  before it exists — which is why `omp/lich.js` reads it at both ends, when a
+  turn settles and when the next one starts, and sends it only when it differs
+  from the last one sent. A session whose only turn is its last still reports
+  its title, one turn late; a session that never gets a second turn reports
+  none.
 - **Crush** — nothing to report. Its one event, `PreToolUse`, is about the tool;
   a Crush card keeps the name lich gave it.
diff --git a/docs/session-touched.md b/docs/session-touched.md
index 7e88af4..a40e719 100644
--- a/docs/session-touched.md
+++ b/docs/session-touched.md
@@ -9,9 +9,9 @@ session's git status immediately instead of waiting for its ~3s poll. Latency
 optimization only — without the plugin the poll catches the same changes, up
 to a poll interval later.
 
-| script              | Claude Code hook                                        | Codex hook                                              | Crush hook                                             | opencode event |
-|---------------------|---------------------------------------------------------|---------------------------------------------------------|--------------------------------------------------------|----------------|
-| `report-touched.sh` | `PostToolUse` matcher `Edit\|Write\|NotebookEdit\|Bash`  | `PostToolUse` matcher `apply_patch\|Edit\|Write\|Bash`  | `PreToolUse` matcher `^(edit\|write\|multiedit\|bash)$` | `file.edited`  |
+| script              | Claude Code hook                                        | Codex hook                                              | Crush hook                                             | opencode event | omp event                                        |
+|---------------------|---------------------------------------------------------|---------------------------------------------------------|--------------------------------------------------------|----------------|--------------------------------------------------|
+| `report-touched.sh` | `PostToolUse` matcher `Edit\|Write\|NotebookEdit\|Bash`  | `PostToolUse` matcher `apply_patch\|Edit\|Write\|Bash`  | `PreToolUse` matcher `^(edit\|write\|multiedit\|bash)$` | `file.edited`  | `tool_result` for `write`/`edit`/`bash`/`notebook` |
 
 `POST /session-touched` with `{"session_id": $LICH_SESSION_ID}`.
 
@@ -27,7 +27,12 @@ because its tool names are whole words (`ls` would otherwise be matched by a
 loose `s`).
 
 opencode needs no matcher at all: `file.edited` fires only when a file actually
-changed, which is what the matchers above approximate. Crush is the opposite —
+changed, which is what the matchers above approximate. omp has no such event and
+keeps the matcher, in its own lower-case spelling and on `tool_result` rather
+than `tool_call` — the same "after the write" position the `PostToolUse` column
+has, so the refresh sees the tree the tool has already changed. Its `python`
+tool can write too and is deliberately left out: it is a general evaluator, so
+including it would fire a refresh on every computation. Crush is the opposite —
 `PreToolUse` is its only event, so the refresh runs *before* the write and sees
 the tree the tool has not touched yet. What it front-runs there is the previous
 tool's write; the last write of a turn waits for the poll.
diff --git a/omp/lich.js b/omp/lich.js
new file mode 100644
index 0000000..760c079
--- /dev/null
+++ b/omp/lich.js
@@ -0,0 +1,166 @@
+// Reports an omp (oh-my-pi) session to lich. Contracts: ../docs/, canonical in
+// https://github.com/omartelo/lich/tree/main/docs/hooks
+//
+// omp runs no hook commands. `--hook` and `--extension` are the same list — it
+// merges both into one set of extension paths and loads every entry as a module
+// (`import()`), so even the files it calls "hooks" are modules, never scripts
+// fed a payload on stdin. So this one file plays the part the four hooks/*.sh
+// scripts play on the harnesses that do run commands, the way opencode/lich.js
+// does: same transport, same payloads, same rule — outside lich it is a no-op,
+// and it never blocks or fails the user's turn.
+//
+// Every event name and context method used here was measured against omp
+// v17.3.0 (@oh-my-pi/pi-coding-agent), against a stub listener, not read off
+// its documentation. 17.x moves fast: re-measure before trusting a name that is
+// not in this file.
+//
+// The transport below is a copy of opencode/lich.js's, not an import of it.
+// Each client is a single file dropped into its harness's own directory, with
+// no package around it to resolve a shared module from — so the duplication is
+// the packaging, not an oversight.
+
+// Fire and forget. Nothing here is awaited: omp awaits its extension handlers,
+// so a slow or dead listener would sit in front of the agent's next step. The
+// environment is read per report rather than at import, so a module loaded
+// outside lich stays a no-op instead of a cached decision.
+function report(path, body) {
+  const port = process.env.LICH_PORT
+  const token = process.env.LICH_TOKEN
+  const session = process.env.LICH_SESSION_ID
+  if (!port || !token || !session) return
+  try {
+    fetch(`http://127.0.0.1:${port}/${path}?token=${token}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ session_id: session, ...body }),
+      signal: AbortSignal.timeout(1000),
+    }).catch(() => {})
+  } catch {}
+}
+
+function inLich() {
+  return Boolean(process.env.LICH_PORT && process.env.LICH_TOKEN && process.env.LICH_SESSION_ID)
+}
+
+// The words for what a tool acts on. omp's built-ins name it `path` (read,
+// write, edit, glob), `command` (bash) or `pattern` (grep) — those three are
+// measured. `filePath` / `query` / `url` follow for the tools omp does not
+// define itself: an extension's or an MCP server's, which spell it however
+// their author did. A call carrying none of them sends no detail, which the
+// contract accepts.
+function detailOf(input) {
+  if (!input || typeof input !== "object") return undefined
+  for (const key of ["path", "command", "pattern", "filePath", "query", "url"]) {
+    const value = input[key]
+    if (typeof value === "string" && value !== "") return value
+  }
+  return undefined
+}
+
+// The tools that write to disk, so a git-status refresh is worth its cost.
+// Mirrors the `Edit|Write|NotebookEdit|Bash` matcher the script harnesses
+// register, in omp's own lower-case spelling. Read-only tools (`read`, `grep`,
+// `glob`) must stay out: a refresh per read would cost more than the ~3s poll
+// it front-runs.
+const WRITERS = new Set(["write", "edit", "bash", "notebook"])
+
+// omp catches what a handler throws, but a throwing extension is still a
+// visible startup warning and a line in its log. Nothing here is worth either.
+const safely = (fn) => (event, ctx) => {
+  try {
+    fn(event, ctx)
+  } catch {}
+}
+
+export default function lichPlugin(pi) {
+  // Outside lich, nothing is subscribed at all. omp discovers `~/.claude`
+  // wholesale, so an install meant for lich is loaded by every omp run on the
+  // machine; there is no per-harness registration to gate on. `report` guards
+  // itself too — this one just makes sure there is nothing to guard.
+  if (!pi || typeof pi.on !== "function" || !inLich()) return
+
+  // The last title sent, so a title that has not changed is not re-sent. lich
+  // applies a title only while the card's label is still automatic, so a repeat
+  // would be harmless — but it would also be a POST per turn saying nothing.
+  let reportedTitle = ""
+
+  // omp generates its session title asynchronously, after a turn: the manager
+  // holds it (`getSessionName`) once `setSessionName` has run. So it is read at
+  // the end of a turn and at the start of the next — a session whose only turn
+  // is its last still reports the title that turn produced, one turn later.
+  const reportTitle = (ctx) => {
+    const title = ctx?.sessionManager?.getSessionName?.()
+    const trimmed = typeof title === "string" ? title.trim() : ""
+    if (!trimmed || trimmed === reportedTitle) return
+    reportedTitle = trimmed
+    report("session-title", { title: trimmed })
+  }
+
+  // The session id lich resumes from. It is on the manager rather than in the
+  // environment: omp exports nothing about the running session to its own
+  // process env, so `ctx` is the only source.
+  pi.on(
+    "session_start",
+    safely((_event, ctx) => {
+      const id = ctx?.sessionManager?.getSessionId?.()
+      if (typeof id === "string" && id !== "") {
+        report("session-start", { provider_session_id: id, provider: "omp" })
+      }
+    }),
+  )
+
+  // The user has sent something: the turn starts here in an interactive
+  // session, which is the only kind lich spawns.
+  pi.on(
+    "input",
+    safely(() => report("hook", { state: "busy" })),
+  )
+
+  // Every turn passes through here, including the ones no `input` precedes — a
+  // continuation, a retry, a print-mode run. It is this contract's equivalent of
+  // the `PostToolUse → busy` the script harnesses register: the spinner comes
+  // back after anything that cleared it.
+  pi.on(
+    "turn_start",
+    safely((_event, ctx) => {
+      report("hook", { state: "busy" })
+      reportTitle(ctx)
+    }),
+  )
+
+  // The tool line on the card. This handler is on the agent's critical path:
+  // returning `{block: true}` from it would refuse the call, so it returns
+  // nothing, always.
+  pi.on(
+    "tool_call",
+    safely((event) => {
+      if (typeof event?.toolName !== "string" || event.toolName === "") return
+      report("hook", { state: "busy", tool: event.toolName, detail: detailOf(event.input) })
+    }),
+  )
+
+  // After the write, not before it: `tool_result` is where the tree has already
+  // changed, so the refresh lich runs sees it.
+  pi.on(
+    "tool_result",
+    safely((event) => {
+      if (WRITERS.has(event?.toolName)) report("session-touched", {})
+    }),
+  )
+
+  // The turn settling, which is this contract's `done`. It fires even when the
+  // turn ended in a provider error, so the spinner always comes off.
+  //
+  // Nothing reports `idle`: the event that would say "the CLI has left" is the
+  // process exiting with this module inside it. `session_shutdown` fires there,
+  // but a report fired and not awaited during shutdown is a report that may not
+  // leave — so an omp card holds its last indicator until lich respawns its
+  // terminal, like a Codex or an opencode one.
+  pi.on(
+    "session_stop",
+    safely((_event, ctx) => {
+      report("hook", { state: "done" })
+      reportTitle(ctx)
+    }),
+  )
+}
diff --git a/tests/omp.test.mjs b/tests/omp.test.mjs
new file mode 100644
index 0000000..c56bc45
--- /dev/null
+++ b/tests/omp.test.mjs
@@ -0,0 +1,452 @@
+// Pins the omp (oh-my-pi) client to lich's contract fixtures.
+//
+// omp runs no commands: `--hook` and `--extension` are one list and every entry
+// is imported as a module, so — like opencode — this suite imports
+// omp/lich.js, feeds it the events omp emits, and asserts the bodies it POSTs
+// against the same fixtures the hook scripts answer to (contract.mjs).
+//
+// The event names, the payload fields and the `ctx.sessionManager` methods
+// below were measured against omp v17.3.0 (@oh-my-pi/pi-coding-agent), driving
+// a real `omp --hook … -p …` run at a stub listener. 17.x moves fast: a name
+// that changes there fails here, which is the point of pinning the version in
+// this comment.
+//
+// Run: node --test tests/
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  LICH_SESSION_ID,
+  PROVIDERS,
+  REJECT_RULES,
+  TOKEN,
+  assertContractHonoured,
+  isJsonObject,
+  lichEnv,
+  matchingAcceptCase,
+  startStub,
+  withStub,
+} from './contract.mjs'
+import * as module from '../omp/lich.js'
+import lichPlugin from '../omp/lich.js'
+
+const OMP_SESSION_ID = '019ffb38-ceab-7000-afae-20b8eae145d8'
+const SESSION_FILE = `/home/u/.omp/agent/sessions/-w/2026-08-13T13-03-51-979Z_${OMP_SESSION_ID}.jsonl`
+
+/** What omp hands a handler as its second argument, of what this client reads. */
+const ctxWith = ({ id = OMP_SESSION_ID, title } = {}) => ({
+  sessionManager: {
+    getSessionId: () => id,
+    getSessionName: () => title,
+    getSessionFile: () => SESSION_FILE,
+  },
+})
+
+/** The `session_stop` payload omp sends, of what this client reads. */
+const stopEvent = () => ({
+  type: 'session_stop',
+  turn_id: 0,
+  session_id: OMP_SESSION_ID,
+  session_file: SESSION_FILE,
+  stop_hook_active: false,
+})
+
+/** Collects what the module subscribes to, and lets a test fire it. */
+function fakePi() {
+  const handlers = new Map()
+  return {
+    pi: {
+      on(event, handler) {
+        handlers.set(event, [...(handlers.get(event) ?? []), handler])
+      },
+    },
+    subscribed: () => [...handlers.keys()],
+    emit(event, payload, ctx) {
+      for (const handler of handlers.get(event) ?? []) handler(payload, ctx)
+    },
+  }
+}
+
+/**
+ * Loads the module against a stub, feeds it events, and returns what reached
+ * the listener. Reports are fired and never awaited by design, so the stub is
+ * polled for the expected count rather than assumed to have it already.
+ */
+async function reportsFor(drive, { expected = 1, status = 204 } = {}) {
+  return withStub(
+    async (stub) => {
+      const previous = { ...process.env }
+      Object.assign(process.env, lichEnv(stub.port))
+      try {
+        const host = fakePi()
+        lichPlugin(host.pi)
+        await drive(host)
+        await settle(stub, expected)
+      } finally {
+        for (const key of ['LICH_PORT', 'LICH_TOKEN', 'LICH_SESSION_ID']) delete process.env[key]
+        Object.assign(process.env, previous)
+      }
+      return stub.requests
+    },
+    { status },
+  )
+}
+
+/** Waits for `expected` requests, then a beat longer to catch an extra one. */
+async function settle(stub, expected) {
+  const deadline = Date.now() + 2000
+  while (stub.requests.length < expected && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 10))
+  }
+  await new Promise((r) => setTimeout(r, 60))
+}
+
+const only = (requests, endpoint) => requests.filter((r) => r.url.startsWith(endpoint + '?'))
+
+/**
+ * lich has not registered `omp` as a provider id yet: the vendored
+ * tests/fixtures/session-start.jsonl carries claude, codex, opencode and crush,
+ * so the contract's own "unregistered provider" rule fires on this client's
+ * otherwise correct payload. The fixture is upstream truth and is never edited
+ * here to make a run green — so until the case lands in lich (and
+ * refresh-fixtures.sh brings it down) this asserts every rule except that one,
+ * and goes back to the shared assertion on its own the day it does.
+ */
+function assertSessionStart(request) {
+  if (PROVIDERS.has('omp')) return assertContractHonoured('/session-start', request)
+
+  assert.equal(request.method, 'POST')
+  assert.equal(request.url, `/session-start?token=${TOKEN}`)
+  assert.match(request.headers['content-type'] ?? '', /application\/json/)
+  assert.ok(isJsonObject(request.raw), `body is not a JSON object: ${request.raw}`)
+
+  const body = JSON.parse(request.raw)
+  assert.ok(!('claude_session_id' in body), `body still sends claude_session_id: ${request.raw}`)
+  assert.ok(
+    matchingAcceptCase('/session-start', body),
+    `body matches no accepted shape for /session-start: ${request.raw}`,
+  )
+  for (const [name, violates] of Object.entries(REJECT_RULES['/session-start'])) {
+    if (name === 'unregistered provider') continue
+    assert.ok(!violates(body, request.raw), `body is the rejected shape "${name}": ${request.raw}`)
+  }
+  return { body }
+}
+
+// ------------------------------------------------------------------ reports --
+
+test('session_start reports the omp session id', async () => {
+  const requests = await reportsFor(({ emit }) => emit('session_start', { type: 'session_start' }, ctxWith()))
+  assert.equal(requests.length, 1)
+  const { body } = assertSessionStart(requests[0])
+  assert.equal(body.session_id, LICH_SESSION_ID)
+  assert.equal(body.provider, 'omp')
+  assert.equal(body.provider_session_id, OMP_SESSION_ID)
+})
+
+// The id is the whole point of the report: an empty one is rejected upstream.
+test('session_start with no id yet reports nothing', async () => {
+  const requests = await reportsFor(
+    ({ emit }) => {
+      emit('session_start', { type: 'session_start' }, ctxWith({ id: '' }))
+      emit('session_start', { type: 'session_start' }, { sessionManager: {} })
+      emit('session_start', { type: 'session_start' }, undefined)
+    },
+    { expected: 0 },
+  )
+  assert.equal(requests.length, 0, `posted an empty provider session id: ${requests[0]?.raw}`)
+})
+
+test('input reports busy', async () => {
+  const requests = await reportsFor(({ emit }) =>
+    emit('input', { type: 'input', text: 'ship it', source: 'interactive' }, ctxWith()),
+  )
+  assert.equal(requests.length, 1)
+  assert.equal(assertContractHonoured('/hook', requests[0]).body.state, 'busy')
+})
+
+// A turn omp starts on its own — a continuation, a retry, print mode — has no
+// `input` in front of it, so this is what brings the spinner back.
+test('turn_start reports busy', async () => {
+  const requests = await reportsFor(({ emit }) =>
+    emit('turn_start', { type: 'turn_start', timestamp: 0 }, ctxWith()),
+  )
+  assert.equal(requests.length, 1)
+  assert.equal(assertContractHonoured('/hook', requests[0]).body.state, 'busy')
+})
+
+test('session_stop reports done', async () => {
+  const requests = await reportsFor(({ emit }) => emit('session_stop', stopEvent(), ctxWith()))
+  assert.equal(requests.length, 1)
+  const { body } = assertContractHonoured('/hook', requests[0])
+  assert.equal(body.state, 'done')
+  assert.equal(body.session_id, LICH_SESSION_ID)
+})
+
+// --------------------------------------------------------------- tool line --
+
+test('tool_call names the tool and the file it acts on', async () => {
+  const requests = await reportsFor(({ emit }) =>
+    emit('tool_call', { type: 'tool_call', toolCallId: 'c', toolName: 'write', input: { path: 'omp/lich.js', content: 'ok\n' } }),
+  )
+  assert.equal(requests.length, 1)
+  const { body } = assertContractHonoured('/hook', requests[0])
+  assert.equal(body.state, 'busy')
+  assert.equal(body.tool, 'write')
+  assert.equal(body.detail, 'omp/lich.js')
+})
+
+const DETAILS = [
+  ['bash', { command: 'node --test tests/' }, 'node --test tests/'],
+  ['grep', { pattern: 'LICH_PORT' }, 'LICH_PORT'],
+  ['read', { path: 'docs/providers.md' }, 'docs/providers.md'],
+  // Not an omp built-in: an extension's or an MCP server's tool, spelled the
+  // way its author spelled it.
+  ['some_mcp_tool', { query: 'lich harness' }, 'lich harness'],
+]
+
+for (const [tool, input, detail] of DETAILS) {
+  test(`a ${tool} call names ${detail}`, async () => {
+    const requests = await reportsFor(({ emit }) =>
+      emit('tool_call', { type: 'tool_call', toolCallId: 'c', toolName: tool, input }),
+    )
+    const { body } = assertContractHonoured('/hook', requests[0])
+    assert.equal(body.tool, tool)
+    assert.equal(body.detail, detail)
+  })
+}
+
+// The detail is optional in the contract: absent, never blank.
+test('tool_call omits the detail when the call carries nothing to say', async () => {
+  const requests = await reportsFor(({ emit }) =>
+    emit('tool_call', { type: 'tool_call', toolCallId: 'c', toolName: 'todo', input: { todos: [] } }),
+  )
+  const { body, match } = assertContractHonoured('/hook', requests[0])
+  assert.equal(match, 'a tool with nothing to say about it')
+  assert.equal(body.tool, 'todo')
+  assert.ok(!('detail' in body), `sent a detail anyway: ${requests[0].raw}`)
+})
+
+// It is on the agent's critical path: a returned `{block: true}` would refuse
+// the call the user asked for.
+test('the tool_call handler never answers the agent', async () => {
+  const host = fakePi()
+  const previous = { ...process.env }
+  Object.assign(process.env, lichEnv(1))
+  try {
+    lichPlugin(host.pi)
+    for (const handler of host.subscribed()) {
+      assert.equal(
+        host.emit(handler, { type: handler, toolName: 'bash', input: { command: 'ls' } }, ctxWith()),
+        undefined,
+        `${handler} returned something omp reads as a decision`,
+      )
+    }
+  } finally {
+    for (const key of ['LICH_PORT', 'LICH_TOKEN', 'LICH_SESSION_ID']) delete process.env[key]
+    Object.assign(process.env, previous)
+  }
+})
+
+// ----------------------------------------------------------------- touched --
+
+const WRITERS = ['write', 'edit', 'bash', 'notebook']
+
+for (const tool of WRITERS) {
+  test(`a ${tool} result refreshes the git status`, async () => {
+    const requests = await reportsFor(({ emit }) =>
+      emit('tool_result', { type: 'tool_result', toolCallId: 'c', toolName: tool, input: {}, content: [], isError: false }),
+    )
+    assert.equal(requests.length, 1)
+    const { body } = assertContractHonoured('/session-touched', requests[0])
+    assert.equal(body.session_id, LICH_SESSION_ID)
+  })
+}
+
+// A refresh per read would cost more than the poll it front-runs.
+test('a read-only tool result refreshes nothing', async () => {
+  const requests = await reportsFor(
+    ({ emit }) => {
+      for (const toolName of ['read', 'grep', 'glob', 'web_search', 'todo']) {
+        emit('tool_result', { type: 'tool_result', toolCallId: 'c', toolName, input: {}, content: [], isError: false })
+      }
+    },
+    { expected: 0 },
+  )
+  assert.equal(requests.length, 0, `a read refreshed the git status: ${requests[0]?.raw}`)
+})
+
+// ------------------------------------------------------------------ titles --
+
+test('the title omp generates is reported when the turn settles', async () => {
+  const requests = await reportsFor(
+    ({ emit }) => emit('session_stop', stopEvent(), ctxWith({ title: '  Fix the replay ring overflow  ' })),
+    { expected: 2 },
+  )
+  const titles = only(requests, '/session-title')
+  assert.equal(titles.length, 1)
+  const { body } = assertContractHonoured('/session-title', titles[0])
+  assert.equal(body.title, 'Fix the replay ring overflow')
+})
+
+// omp writes the title asynchronously, so the turn that produced it may settle
+// before it exists. The next turn starting is the second chance.
+test('a title that only lands after the turn is reported on the next one', async () => {
+  const requests = await reportsFor(
+    ({ emit }) => {
+      emit('session_stop', stopEvent(), ctxWith())
+      emit('turn_start', { type: 'turn_start', timestamp: 0 }, ctxWith({ title: 'Add the omp client' }))
+    },
+    { expected: 3 },
+  )
+  const titles = only(requests, '/session-title')
+  assert.equal(titles.length, 1)
+  assert.equal(assertContractHonoured('/session-title', titles[0]).body.title, 'Add the omp client')
+})
+
+test('an unchanged title is not re-sent', async () => {
+  const requests = await reportsFor(
+    ({ emit }) => {
+      emit('session_stop', stopEvent(), ctxWith({ title: 'Add the omp client' }))
+      emit('session_stop', stopEvent(), ctxWith({ title: 'Add the omp client' }))
+      emit('session_stop', stopEvent(), ctxWith({ title: '  Add the omp client  ' }))
+    },
+    { expected: 4 },
+  )
+  assert.equal(only(requests, '/session-title').length, 1, 'sent the same title more than once')
+})
+
+test('a session with no title yet says nothing about it', async () => {
+  const requests = await reportsFor(
+    ({ emit }) => {
+      emit('session_stop', stopEvent(), ctxWith({ title: undefined }))
+      emit('session_stop', stopEvent(), ctxWith({ title: '   ' }))
+      emit('session_stop', stopEvent(), { sessionManager: {} })
+    },
+    { expected: 3 },
+  )
+  assert.equal(only(requests, '/session-title').length, 0, 'posted a blank title, which lich rejects')
+})
+
+// ------------------------------------------------------------ client rules --
+
+const PARTIAL_ENVS = {
+  'no lich variables at all': {},
+  'only LICH_PORT': ['LICH_PORT'],
+  'no LICH_TOKEN': ['LICH_PORT', 'LICH_SESSION_ID'],
+  'no LICH_SESSION_ID': ['LICH_PORT', 'LICH_TOKEN'],
+}
+
+// omp discovers `~/.claude` wholesale, so a global install is loaded by every
+// omp run on the machine. Outside lich it must subscribe to nothing at all —
+// no fetch, no timer, no line in omp's log.
+for (const [label, keep] of Object.entries(PARTIAL_ENVS)) {
+  test(`no report outside lich: ${label}`, async () => {
+    await withStub(async (stub) => {
+      const previous = { ...process.env }
+      const full = lichEnv(stub.port)
+      for (const key of ['LICH_PORT', 'LICH_TOKEN', 'LICH_SESSION_ID']) delete process.env[key]
+      // LICH_PORT points at the stub so a leak is caught, not refused.
+      for (const key of Array.isArray(keep) ? keep : []) process.env[key] = full[key]
+      try {
+        const host = fakePi()
+        lichPlugin(host.pi)
+        assert.deepEqual(host.subscribed(), [], 'subscribed to omp events outside lich')
+        await new Promise((r) => setTimeout(r, 80))
+        assert.equal(stub.requests.length, 0, 'reported without a full lich environment')
+      } finally {
+        for (const key of ['LICH_PORT', 'LICH_TOKEN', 'LICH_SESSION_ID']) delete process.env[key]
+        Object.assign(process.env, previous)
+      }
+    })
+  })
+}
+
+test('lich answering 500 changes nothing for the turn', async () => {
+  const requests = await reportsFor(
+    ({ emit }) => emit('input', { type: 'input', text: 'go', source: 'interactive' }, ctxWith()),
+    { status: 500 },
+  )
+  assert.equal(requests.length, 1)
+})
+
+test('a refused connection is swallowed', async () => {
+  const stub = await startStub()
+  const { port } = stub
+  await stub.close() // nothing listens there any more
+  const previous = { ...process.env }
+  Object.assign(process.env, lichEnv(port))
+  try {
+    const host = fakePi()
+    lichPlugin(host.pi)
+    host.emit('input', { type: 'input', text: 'go', source: 'interactive' }, ctxWith())
+    await new Promise((r) => setTimeout(r, 80))
+  } finally {
+    for (const key of ['LICH_PORT', 'LICH_TOKEN', 'LICH_SESSION_ID']) delete process.env[key]
+    Object.assign(process.env, previous)
+  }
+})
+
+// omp awaits its extension handlers, so a report that waited on the listener
+// would sit in front of the agent's next step.
+test('a handler returns before the listener answers', async () => {
+  const server = (await import('node:http')).createServer((req, res) => {
+    req.resume()
+    setTimeout(() => res.writeHead(204).end(), 3000)
+  })
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
+  const previous = { ...process.env }
+  Object.assign(process.env, lichEnv(server.address().port))
+  try {
+    const host = fakePi()
+    lichPlugin(host.pi)
+    const started = Date.now()
+    host.emit('input', { type: 'input', text: 'go', source: 'interactive' }, ctxWith())
+    const elapsed = Date.now() - started
+    assert.ok(elapsed < 500, `the handler waited ${elapsed}ms on the listener`)
+  } finally {
+    for (const key of ['LICH_PORT', 'LICH_TOKEN', 'LICH_SESSION_ID']) delete process.env[key]
+    Object.assign(process.env, previous)
+    await new Promise((resolve) => server.close(resolve))
+  }
+})
+
+// omp grows events between releases and hands this module all of them. A throw
+// here is a startup warning in the user's session, and a handler that answers
+// with garbage is worse than one that says nothing.
+test('a malformed event payload is survived', async () => {
+  const requests = await reportsFor(
+    ({ emit }) => {
+      emit('tool_call', undefined, undefined)
+      emit('tool_call', { type: 'tool_call' }, ctxWith())
+      emit('tool_call', { type: 'tool_call', toolName: '', input: null }, ctxWith())
+      emit('tool_result', {}, undefined)
+      emit('session_stop', undefined, undefined)
+      emit('session_start', undefined, undefined)
+    },
+    { expected: 1 },
+  )
+  // Only the `done` of that bare session_stop is legitimate.
+  assert.equal(requests.length, 1, `a malformed payload reached lich: ${requests[1]?.raw}`)
+  assert.equal(assertContractHonoured('/hook', requests[0]).body.state, 'done')
+})
+
+// omp loads exactly one thing from an extension file: `module.default`, called
+// with its API object. Anything else exported is dead weight, and a factory
+// that throws is a load error reported at startup.
+test('the module is the one factory omp loads, and survives being handed nothing', () => {
+  assert.deepEqual(Object.keys(module), ['default'], 'a second export omp will never call')
+  assert.equal(typeof module.default, 'function')
+
+  const previous = { ...process.env }
+  for (const key of Object.keys(process.env)) if (key.startsWith('LICH_')) delete process.env[key]
+  try {
+    assert.doesNotThrow(() => lichPlugin(undefined))
+    assert.doesNotThrow(() => lichPlugin({}))
+    assert.doesNotThrow(() => lichPlugin({ on: null }))
+  } finally {
+    for (const key of Object.keys(process.env)) if (key.startsWith('LICH_')) delete process.env[key]
+    Object.assign(process.env, previous)
+  }
+})