From 5aca384a1cda2a1b4b3e7a83a30cdb9b61235d0f Mon Sep 17 00:00:00 2001
From: omartelo <meopedevts@proton.me>
Date: Mon, 10 Aug 2026 23:06:12 -0300
Subject: [PATCH] feat: report from opencode and Crush sessions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two more harnesses, and neither fits the script model the other two
share — so each is met where it is rather than bent into the shape of
the others.

**opencode** runs no hook commands: a plugin there is a JavaScript
module its server imports. Its client is one file, opencode/lich.js,
posting the same four reports to the same endpoints off the event bus —
the session id from `session.created`, `busy`/`done` from
`session.status`, `waiting` from `permission.asked`, the tool line from
`tool.execute.before`, the label from `session.updated`, and the
git-status refresh from `file.edited`. Installing it is dropping the
file in ~/.config/opencode/plugin/; there is no marketplace.

Three things the module has to get right, all of them measured rather
than assumed:

- Sub-sessions are dropped by their `parentID`. The `task` tool runs a
  sub-agent as its own session, and its `idle` would otherwise end the
  turn on the card while the real one is still running.
- The title a session is created with is a placeholder built from its
  timestamp, so the module holds that first value and reports only a
  title that differs from it — no matching on its wording.
- opencode awaits its plugin hooks, so no report is ever awaited and
  nothing throws. That is this client's version of "always exit 0", and
  a test holds it: a listener that takes 3s must not hold the turn.

**Crush** runs the existing scripts unchanged — its hooks are Claude
Code-compatible down to the stdin payload — but `PreToolUse` is the only
event it has. Only the two reports that event can honour are registered:
the session id, and the git-status refresh on write tools. A `busy` with
no `Stop` behind it would pin a spinner to a card, so state and title
stay unregistered until Crush ships an end-of-turn event, at which point
report-state.sh and report-tool.sh are already here. Crush has no plugin
system either, so hooks/crush-hooks.json is a block to merge into the
user's own crush.json, with <lich-plugin> where the clone's path goes.

The suite splits so both clients answer to the same lines:
tests/contract.mjs holds lich's fixtures, the assertions and the stub;
tests/opencode.test.mjs drives the module through the payloads a real
opencode run emits, including the ones it must drop.
---
 CHANGELOG.md                       |  27 +++
 CLAUDE.md                          |  30 ++-
 README.md                          |  39 +++-
 docs/providers.md                  | 123 ++++++++--
 docs/session-start.md              |  35 ++-
 docs/session-state.md              |  38 +--
 docs/session-title.md              |  14 +-
 docs/session-touched.md            |  20 +-
 hooks/crush-hooks.json             |  17 ++
 opencode/lich.js                   | 108 +++++++++
 opencode/package.json              |   5 +
 tests/contract.mjs                 | 180 ++++++++++++++
 tests/fixtures/session-start.jsonl |   2 +
 tests/hooks.test.mjs               | 258 ++++++--------------
 tests/opencode.test.mjs            | 362 +++++++++++++++++++++++++++++
 15 files changed, 1005 insertions(+), 253 deletions(-)
 create mode 100644 hooks/crush-hooks.json
 create mode 100644 opencode/lich.js
 create mode 100644 opencode/package.json
 create mode 100644 tests/contract.mjs
 create mode 100644 tests/opencode.test.mjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c6afedf..f26afd8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **opencode sessions report to lich.** opencode runs no hook commands — a
+  plugin there is a module its server imports — so its client is one file,
+  `opencode/lich.js`, sending the same four reports to the same endpoints: the
+  session id off `session.created`, `busy`/`done` off `session.status`,
+  `waiting` off `permission.asked`, the tool line off `tool.execute.before`, the
+  card's label off `session.updated`, and the git-status refresh off
+  `file.edited`. Install it by dropping the file in `~/.config/opencode/plugin/`
+  — there is no marketplace to go through. Sub-sessions (the `task` tool) are
+  filtered out by their `parentID`, so a sub-agent finishing does not look like
+  the turn ending.
+- **Crush sessions report their id and refresh git status.** Crush's hooks are
+  Claude Code-compatible, so the existing scripts run unchanged — but
+  `PreToolUse` is its only event, so only the two reports it can honour are
+  registered. `hooks/crush-hooks.json` is the block to merge into your own
+  `crush.json`, with `<lich-plugin>` where the clone's path goes. A Crush card
+  shows no spinner and keeps the name lich gave it; both arrive the day Crush
+  ships an end-of-turn event.
+
+### Changed
+
+- The test suite is split: `tests/contract.mjs` holds lich's fixtures and the
+  assertions, and both clients — the hook scripts and the opencode module —
+  answer to the same lines. `tests/opencode.test.mjs` drives the module through
+  the events a real opencode run emits.
+
 ## [0.7.0] - 2026-08-10
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index 56dab0d..5da6912 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** and **OpenAI Codex** 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** and **Crush** from the same repository root.
 
 ## Structure
 
@@ -11,12 +11,21 @@ The agent side of the integration with **lich** — a harness that orchestrates
 .agents/plugins/marketplace.json  # marketplace, Codex
 hooks/hooks.json                  # hook registration, Claude Code
 hooks/codex-hooks.json            # hook registration, Codex
-hooks/                            # hook scripts ($CLAUDE_PLUGIN_ROOT/hooks/<script>, both)
+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
 docs/                             # lich ⇄ plugin communication contracts
-skills/                           # skills (skills/<name>/SKILL.md, both)
+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
+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.
+
 ## Contracts
 
 Contracts are **canonical in the lich repository** (`docs/hooks/` there); this plugin only implements the client side. Each hook has a doc in `docs/` here that points at its contract and describes the plugin-side behavior. Read it before creating or changing a hook:
@@ -26,7 +35,7 @@ Contracts are **canonical in the lich repository** (`docs/hooks/` there); this p
 - [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)
 
-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 two event vocabularies differ, and what adding a third provider takes.
+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.
 
 ## Skills
 
@@ -43,8 +52,14 @@ subprocess — the command line taken from the registration each harness reads 
 against a stub HTTP server, and asserts the body it POSTs against lich's
 contract fixtures: an accepted shape, no rejected one, the right endpoint and
 `?token=`, no deprecated `claude_session_id`, plus the client rules (no lich
-environment → no report, exit 0 on a 500 or a refused connection). Node only,
-no dependencies.
+environment → no report, exit 0 on a 500 or a refused connection).
+[tests/opencode.test.mjs](tests/opencode.test.mjs) does the same for the
+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/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
+dependencies.
 
 The fixtures are vendored in `tests/fixtures/` from lich
 (`docs/hooks/fixtures/*.jsonl` there) by
@@ -60,7 +75,8 @@ 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. Registration differs per harness, the report does not — extend a script to read a second transcript format before adding a second script.
+- 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".
 
 ## Local testing
 
diff --git a/README.md b/README.md
index 4359f2d..c695c71 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,14 @@
 # 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** and **OpenAI Codex** 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** 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.
+
 It also ships skills for the parts of lich you configure from inside a session:
 
 - **theme** (`/lich:theme` in Claude Code; on Codex the `theme` skill loads from its description) — write, port or fix a lich color theme: the app tokens, the xterm palette, where the file goes, and a validator for the rules that otherwise fail silently
@@ -20,17 +22,19 @@ It also ships skills for the parts of lich you configure from inside a session:
 .agents/plugins/marketplace.json  # marketplace, Codex
 hooks/hooks.json                  # hook registration, Claude Code
 hooks/codex-hooks.json            # hook registration, Codex
+hooks/crush-hooks.json            # hook registration, Crush (merged into crush.json by hand)
 hooks/report-state.sh             # session-state hook
 hooks/report-tool.sh              # session-state hook: the tool a turn is running
 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, 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 both harnesses — they live in `hooks/` and are referenced via `$CLAUDE_PLUGIN_ROOT/hooks/<script>`, a variable Codex sets too. [docs/providers.md](docs/providers.md) maps the layout and the two harnesses' 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 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.
 
 ## Installation
 
@@ -54,6 +58,35 @@ codex plugin add lich@lich-plugin
 
 Then start a new session and run `/hooks` to review and trust the plugin's hooks — Codex does not run a plugin's hooks until you do, so until then the plugin is installed but silent. Hooks themselves are stable and on by default in current Codex; on older versions set `[features] hooks = true` in `~/.codex/config.toml`.
 
+### opencode
+
+opencode has no marketplace: a plugin is a file in its plugin directory, so dropping it there is the install.
+
+```bash
+mkdir -p ~/.config/opencode/plugin
+curl -fsSL -o ~/.config/opencode/plugin/lich.js \
+  https://raw.githubusercontent.com/omartelo/lich-plugin/main/opencode/lich.js
+```
+
+Per project instead of globally, use `.opencode/plugin/lich.js`. 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:
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      { "name": "lich session id", "command": "/home/you/src/lich-plugin/hooks/report-session-start.sh crush", "timeout": 5 },
+      { "name": "lich git-status refresh", "matcher": "^(edit|write|multiedit|bash)$", "command": "/home/you/src/lich-plugin/hooks/report-touched.sh", "timeout": 5 }
+    ]
+  }
+}
+```
+
+`command` is resolved against the working directory, not the config file, so a global install needs the absolute path. Crush reports no session state and no title — see [docs/providers.md](docs/providers.md) for why.
+
 ### Manual (from a clone)
 
 ```bash
@@ -90,4 +123,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 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 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.
diff --git a/docs/providers.md b/docs/providers.md
index c6f5e4b..108c600 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -6,8 +6,7 @@ lich drives an agent CLI inside a PTY and injects the same three variables
 are therefore provider-agnostic: what changes per provider is only *how the
 harness registers hooks* and *what its lifecycle events are called*.
 
-This repository is one plugin with one set of hook scripts, packaged for each
-harness it supports:
+This repository is one plugin, packaged for each harness it supports:
 
 | File                            | Read by     | Purpose                       |
 |---------------------------------|-------------|-------------------------------|
@@ -17,27 +16,42 @@ harness it supports:
 | `.agents/plugins/marketplace.json` | Codex    | marketplace, points at `./`   |
 | `hooks/hooks.json`              | Claude Code | hook registration             |
 | `hooks/codex-hooks.json`        | Codex       | hook registration             |
-| `hooks/*.sh`                    | both        | the reports themselves        |
-| `skills/`                       | both        | skills, same layout           |
+| `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 |
+| `skills/`                       | all         | skills, same layout           |
 
-The repository root is the plugin root for both, so a single clone installs on
-either CLI. The scripts are shared because both harnesses expose the same
-things a report needs: the payload arrives as JSON on stdin with `session_id`
-and `transcript_path` (and `tool_name` / `tool_input` / `cwd` on a pre-tool
-event), and `$CLAUDE_PLUGIN_ROOT` points at the installed plugin — Codex sets
-that same variable, so the command lines are identical.
+The repository root is the plugin root for Claude Code and Codex, so a single
+clone installs on either CLI. The scripts are shared because those harnesses —
+and Crush — expose the same things a report needs: the payload arrives as JSON
+on stdin with `session_id` and `transcript_path` (and `tool_name` /
+`tool_input` / `cwd` on a pre-tool event), and `$CLAUDE_PLUGIN_ROOT` points at
+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.
 
 ## Event vocabulary
 
-| Report              | Claude Code                  | Codex                        |
-|---------------------|------------------------------|------------------------------|
-| session id          | `SessionStart`               | `SessionStart`               |
-| `busy`              | `UserPromptSubmit`, `PostToolUse` | `UserPromptSubmit`, `PostToolUse` |
-| `busy` + tool       | `PreToolUse`                 | `PreToolUse`                 |
-| `waiting`           | `Notification`               | `PermissionRequest`          |
-| `done` + title      | `Stop`                       | `Stop`                       |
-| `idle`              | `SessionEnd`                 | — (registered, never fires)  |
-| touched             | `PostToolUse` (write tools)  | `PostToolUse` (write tools)  |
+| 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`          | `permission.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)  |
+
+Every cell above was taken off a real run of that harness against a stub
+listener, not off its documentation.
 
 Two differences matter. Codex has no `Notification`, so "your turn" arrives as
 `PermissionRequest` — where a hook exiting `2` would *deny* the request, which
@@ -55,6 +69,9 @@ The session id carries the provider that reported it (`report-session-start.sh
 codex`), which is what puts Codex's icon rather than Claude's on the card, and
 what lets lich resume the conversation with `codex resume <id>`. Both need lich
 ≥ 0.28.0; an older lich ignores the field and treats the report as Claude's.
+opencode and Crush report the same field, so their cards wear their own icon
+too — but lich does not resume either yet, so for them the id is stored and
+waits.
 
 ## Codex specifics
 
@@ -78,13 +95,69 @@ what lets lich resume the conversation with `codex resume <id>`. Both need lich
   `./hooks/codex-hooks.json`, so the Claude Code registration sitting beside it
   is not also loaded — a session reports each event once, not twice.
 
+## opencode specifics
+
+- **It is a module, not a command.** `opencode/lich.js` goes in opencode's
+  plugin directory — `~/.config/opencode/plugin/` globally, `.opencode/plugin/`
+  per project (`plugins/` works too; opencode globs both). There is no
+  marketplace to install from and no manifest: the file being there is the
+  install.
+- **One module, one card.** The plugin is loaded by the opencode *server* and
+  reads `LICH_SESSION_ID` from the environment it was started in. A session lich
+  spawns gets its own server, so that is one card; a server shared between two
+  top-level sessions would report both onto the same one.
+- **Sub-sessions are filtered out.** The `task` tool runs a sub-agent as its own
+  session with its own `session.status`, and its `idle` is not the turn ending.
+  They are recognised by the `parentID` their session events carry and dropped.
+- **Nothing reports `idle`.** The event that would say "the CLI has left" is the
+  server exiting with this module inside it, so there is nobody left to send it.
+  Like a Codex card, an opencode card holds its last indicator until lich
+  respawns its terminal.
+- **The title is handed over, not read.** `session.updated` carries the whole
+  session including its title. The one at creation is a placeholder built from
+  the timestamp, so the module holds it and only reports a title that differs
+  from it — no matching on its wording.
+- **Never awaited.** opencode awaits its plugin hooks, so a report that blocked
+  would sit in front of the agent's next step. Every `fetch` here is fired and
+  dropped, with a 1s timeout, and its failure is swallowed — the module's version
+  of "always exit 0".
+
+## Crush specifics
+
+- **One event exists: `PreToolUse`.** Crush's hooks are Claude Code-compatible
+  down to the stdin payload and the exit codes, so the scripts run unchanged —
+  but with nothing that fires at the end of a turn, only two of the four reports
+  can be honest. Crush reports its session id and refreshes git status; it shows
+  no spinner, no check, no bell, and keeps the card's own name.
+- **`busy` is deliberately not registered.** A `busy` with no `Stop` behind it
+  would pin a spinner to the card until the next turn — wrong for longer than it
+  is right. The day Crush ships an end-of-turn event, `report-state.sh` and
+  `report-tool.sh` are already here.
+- **The session id arrives late.** It rides the first tool call, because that is
+  the first event there is. A conversation that answers without a tool never
+  reports one.
+- **The touched refresh runs one tool early**, for the same reason: `PreToolUse`
+  fires before the write, so the immediate git fetch sees the tree the tool has
+  not changed yet. What it front-runs in practice is the previous tool's write.
+- **Registration is a hand-merge.** Crush has no plugin system: its hooks live in
+  the user's own `crush.json`, and `command` is resolved against the working
+  directory, not the config file — so a global install needs an absolute path.
+  `hooks/crush-hooks.json` is that block with `<lich-plugin>` where the clone's
+  path goes.
+- **Tool names are lower case**: `bash`, `edit`, `write`, `multiedit`, `view`,
+  `ls`, `grep`, `glob`, `mcp_*`. `view` is the read tool — the matcher for the
+  touched report lists the writers only.
+
 ## Adding a provider
 
-1. Confirm the harness runs commands as hooks on a session's lifecycle, and
-   that it exposes the session id and the transcript path.
-2. Add its manifest and marketplace file, and a hook-registration file mapping
-   its events onto the existing scripts.
+1. Confirm the harness exposes the session lifecycle to something it will run or
+   load, and that it names the session id.
+2. Add its manifest and marketplace file if it has them, and a hook-registration
+   file mapping its events onto the existing scripts.
 3. Only write a new script if a report cannot be derived from what the existing
    ones read — extend one instead (`report-title.sh` reads two transcript
-   formats).
-4. Add the provider's column to each doc in this directory.
+   formats). A harness that takes no commands at all is the one case for a
+   client of its own, which is what `opencode/lich.js` is.
+4. Register only the reports the harness can actually close. A state nothing can
+   end is worse on a card than no state.
+5. Add the provider's column to each doc in this directory.
diff --git a/docs/session-start.md b/docs/session-start.md
index beae68d..e6aa843 100644
--- a/docs/session-start.md
+++ b/docs/session-start.md
@@ -8,29 +8,37 @@ 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     |
-|------------------------------------|---------------------------------|------------------|----------------|
-| `report-session-start.sh <provider>` | send the CLI's `session_id`   | `SessionStart`   | `SessionStart` |
+| 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` |
 
 `POST /session-start` with `{"session_id": $LICH_SESSION_ID,
 "provider_session_id": <session_id from the hook payload on stdin>, "provider":
 <$1>}`.
 
 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` and
-`codex-hooks.json` passes `codex`. 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 one.
+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.
+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
+one.
 
 Sent as `claude_session_id` up to v0.2.0; lich still accepts that alias for
 older plugins, but this plugin no longer sends it.
 
 `SessionStart` fires on startup, resume, `/clear` and compaction; each report
 overwrites the stored id, so lich always holds the session currently in the
-card. Both CLIs name the field `session_id` on the payload, so one script
-serves both. 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.
+card. All three script harnesses name the field `session_id` on the payload —
+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 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
@@ -40,4 +48,7 @@ contract. Nothing extra to send: both hooks already ship.
 The id is what a restored lich card resumes from — `claude --resume <id>` or
 `codex resume <id>`, chosen by the card's kind. lich only offers the prompt
 while the conversation is still on disk, so an id whose transcript the provider
-has pruned starts a fresh session instead of failing in the PTY.
+has pruned starts a fresh session instead of failing in the PTY. That check is
+also why opencode and Crush report an id lich stores and does not yet act on:
+both keep their conversations in SQLite, where there is no per-session file to
+find.
diff --git a/docs/session-state.md b/docs/session-state.md
index 9208def..05cc9b3 100644
--- a/docs/session-state.md
+++ b/docs/session-state.md
@@ -8,14 +8,20 @@ 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          |
-|---------------------------|------------------|--------------------|---------------------|
-| `report-state.sh busy`    | `busy`           | `UserPromptSubmit` | `UserPromptSubmit`  |
-| `report-tool.sh`          | `busy` + `tool`  | `PreToolUse`       | `PreToolUse`        |
-| `report-state.sh busy`    | `busy`           | `PostToolUse`      | `PostToolUse`       |
-| `report-state.sh done`    | `done`           | `Stop`             | `Stop`              |
-| `report-state.sh waiting` | `waiting`        | `Notification`     | `PermissionRequest` |
-| `report-state.sh idle`    | `idle`           | `SessionEnd`       | — (never fires)     |
+| 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` | `permission.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
+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).
 
 `POST /hook` with `{"session_id": $LICH_SESSION_ID, "state":
 "busy"|"done"|"waiting"|"idle"}`, plus the optional `tool` / `detail` pair the
@@ -61,17 +67,19 @@ 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                     |
-|---------------|-------------------|---------------------------|
-| run a command | `Bash`            | `Bash`                    |
-| edit a file   | `Edit` / `Write`  | `apply_patch`             |
-| read a file   | `Read`            | — (goes through `Bash`)   |
-| search        | `Grep` / `Glob`   | — (goes through `Bash`)   |
+| 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`  |
 
 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.
+`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.
 
 Two shapes need more than the plain rule:
 
diff --git a/docs/session-title.md b/docs/session-title.md
index 0b7d117..d01f6cd 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 |
-|-------------------|---------------------------|------------------|------------|
-| `report-title.sh` | send the session's title  | `Stop`           | `Stop`     |
+| script            | action                    | Claude Code hook | Codex hook | opencode event    | Crush hook |
+|-------------------|---------------------------|------------------|------------|-------------------|------------|
+| `report-title.sh` | send the session's title  | `Stop`           | `Stop`     | `session.updated` | —          |
 
 `POST /session-title` with `{"session_id": $LICH_SESSION_ID, "title": <title>}`.
 Both providers keep the title in the transcript file (`transcript_path` on
@@ -25,3 +25,11 @@ stdin), in their own shape — the script reads whichever is there:
 
 Both formats are internal and undocumented — extraction failures are swallowed
 and the hook no-ops. Requires `jq`; absent → no-op.
+
+- **opencode** — no transcript to read: `session.updated` carries the whole
+  session, title included, so `opencode/lich.js` forwards it. The title a
+  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.
+- **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 2127b9b..7e88af4 100644
--- a/docs/session-touched.md
+++ b/docs/session-touched.md
@@ -9,17 +9,25 @@ 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                                              |
-|---------------------|---------------------------------------------------------|---------------------------------------------------------|
-| `report-touched.sh` | `PostToolUse` matcher `Edit\|Write\|NotebookEdit\|Bash`  | `PostToolUse` matcher `apply_patch\|Edit\|Write\|Bash`  |
+| 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`  |
 
 `POST /session-touched` with `{"session_id": $LICH_SESSION_ID}`.
 
 The matcher is deliberate: only tools that write to disk. Read-only tools
-(`Read`, `Grep`, `Glob`) must not fire it — a git-status refresh per read
-would cost more than the poll it front-runs. No stdin parsing, no `jq`.
+(`Read`, `Grep`, `Glob`, Crush's `view`) must not fire it — a git-status refresh
+per read would cost more than the poll it front-runs. No stdin parsing, no `jq`.
 
 Codex writes files through `apply_patch` rather than `Edit`/`Write`, and runs
 commands as `Bash`; `Edit` and `Write` stay in its matcher because Codex
 accepts them as aliases for `apply_patch`, so the same intent holds if a tool
-is renamed.
+is renamed. Crush spells the same set in lower case and anchors the matcher,
+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 —
+`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/hooks/crush-hooks.json b/hooks/crush-hooks.json
new file mode 100644
index 0000000..82a409d
--- /dev/null
+++ b/hooks/crush-hooks.json
@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "name": "lich session id",
+        "command": "<lich-plugin>/hooks/report-session-start.sh crush",
+        "timeout": 5
+      },
+      {
+        "name": "lich git-status refresh",
+        "matcher": "^(edit|write|multiedit|bash)$",
+        "command": "<lich-plugin>/hooks/report-touched.sh",
+        "timeout": 5
+      }
+    ]
+  }
+}
diff --git a/opencode/lich.js b/opencode/lich.js
new file mode 100644
index 0000000..369f971
--- /dev/null
+++ b/opencode/lich.js
@@ -0,0 +1,108 @@
+// Reports an opencode session to lich. Contracts: ../docs/, canonical in
+// https://github.com/omartelo/lich/tree/main/docs/hooks
+//
+// opencode loads a module rather than running a script, so this one file plays
+// the part the four hooks/*.sh scripts play on the other harnesses. Same
+// transport, same payloads, same rule: outside lich it is a no-op, and it never
+// blocks or fails the user's turn.
+
+// Fire and forget. Nothing here is awaited: opencode awaits its hooks, 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 {}
+}
+
+// The name a card shows under a session's label, and the words for what it acts
+// on. opencode's args are per-tool; these are the keys that identify a call.
+function detailOf(args) {
+  if (!args || typeof args !== "object") return undefined
+  for (const key of ["filePath", "command", "pattern", "query", "url", "path"]) {
+    const value = args[key]
+    if (typeof value === "string" && value !== "") return value
+  }
+  return undefined
+}
+
+export const LichPlugin = async () => {
+  // A sub-session (the `task` tool) reports its own status and would answer for
+  // the card: its `idle` is a sub-agent finishing, not the turn ending. They are
+  // known by the parentID their session events carry.
+  const subSessions = new Set()
+  // The title opencode gives a session at creation is a placeholder built from
+  // the timestamp. Holding it is what tells a real title apart from it later,
+  // without matching on its wording.
+  const bornTitles = new Map()
+
+  const track = (properties) => {
+    const info = properties?.info
+    if (!info?.id) return
+    if (info.parentID) {
+      subSessions.add(info.id)
+      return
+    }
+    if (!bornTitles.has(info.id)) bornTitles.set(info.id, info.title ?? "")
+  }
+
+  return {
+    event: async ({ event }) => {
+      const properties = event?.properties ?? event?.data ?? {}
+
+      switch (event?.type) {
+        case "session.created": {
+          track(properties)
+          const id = properties.info?.id ?? properties.sessionID
+          if (id && !subSessions.has(id)) {
+            report("session-start", { provider_session_id: id, provider: "opencode" })
+          }
+          return
+        }
+        case "session.updated": {
+          track(properties)
+          const info = properties.info
+          if (!info?.id || subSessions.has(info.id)) return
+          const title = typeof info.title === "string" ? info.title.trim() : ""
+          if (title && title !== bornTitles.get(info.id)) report("session-title", { title })
+          return
+        }
+        case "session.status": {
+          if (subSessions.has(properties.sessionID)) return
+          // opencode's `idle` is the turn ending, which is lich's `done`.
+          // lich's own `idle` means the CLI has left, which nothing here can
+          // report — the plugin dies with the server that would say it.
+          const type = properties.status?.type
+          if (type === "idle") report("hook", { state: "done" })
+          else if (type === "busy" || type === "retry") report("hook", { state: "busy" })
+          return
+        }
+        case "permission.asked": {
+          if (subSessions.has(properties.sessionID)) return
+          report("hook", { state: "waiting" })
+          return
+        }
+        case "file.edited":
+          report("session-touched", {})
+          return
+      }
+    },
+
+    // The tool line on the card. `file.edited` above already covers the touched
+    // report, so this one only decorates the state.
+    "tool.execute.before": async (input, output) => {
+      if (!input?.tool || subSessions.has(input.sessionID)) return
+      report("hook", { state: "busy", tool: input.tool, detail: detailOf(output?.args) })
+    },
+  }
+}
diff --git a/opencode/package.json b/opencode/package.json
new file mode 100644
index 0000000..bb4e7d8
--- /dev/null
+++ b/opencode/package.json
@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "type": "module",
+  "comment": "lich.js is ESM. opencode imports it through Bun, which needs no help; this file is what lets Node — the test suite — read the same extension as a module."
+}
diff --git a/tests/contract.mjs b/tests/contract.mjs
new file mode 100644
index 0000000..7a75607
--- /dev/null
+++ b/tests/contract.mjs
@@ -0,0 +1,180 @@
+// lich's contract fixtures, and the assertions both clients answer to.
+//
+// lich owns the endpoints; this repository owns the two clients that build the
+// payloads — the hook scripts (Claude Code, Codex, Crush) and the opencode
+// module. The fixtures in tests/fixtures/ are lich's, vendored verbatim
+// (tests/refresh-fixtures.sh); they are upstream truth and are never edited to
+// make a run green.
+//
+// Everything here is shared by hooks.test.mjs and opencode.test.mjs so both
+// clients are held to the same lines.
+
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+
+export const ROOT = path.resolve(HERE, '..')
+export const TOKEN = 'test-token'
+export const LICH_SESSION_ID = 'lich-session-1'
+
+// ---------------------------------------------------------------- fixtures --
+
+/** endpoint → fixture file, per lich's docs/hooks/fixtures/README.md. */
+export const FIXTURE_OF = {
+  '/hook': 'session-state',
+  '/session-start': 'session-start',
+  '/session-title': 'session-title',
+  '/session-touched': 'session-touched',
+}
+
+const readFixture = (name) =>
+  readFileSync(path.join(HERE, 'fixtures', `${name}.jsonl`), 'utf8')
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => JSON.parse(line))
+
+export const CASES = Object.fromEntries(
+  Object.entries(FIXTURE_OF).map(([endpoint, file]) => [endpoint, readFixture(file)]),
+)
+
+export const accepted = (endpoint) => CASES[endpoint].filter((c) => c.accept)
+export const rejected = (endpoint) => CASES[endpoint].filter((c) => c.reject)
+
+// Enumerations come from the fixtures, not from a copy of them kept here: a
+// state or a provider that lich stops accepting stops being accepted below too.
+export const STATES = new Set(accepted('/hook').map((c) => c.accept.state))
+export const PROVIDERS = new Set(accepted('/session-start').map((c) => c.accept.provider))
+
+export const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+export const blank = (v) => typeof v !== 'string' || v.trim() === ''
+
+/**
+ * `reject` prose is documentation, not a matcher, so each rejected case is
+ * modelled here as a predicate: true means the body is the shape that case
+ * describes. A rejected case with no rule fails its own test, so a new one
+ * upstream cannot slip through unmodelled.
+ */
+export const REJECT_RULES = {
+  '/hook': {
+    'missing session_id': (b) => !('session_id' in b),
+    'empty session_id': (b) => b.session_id === '',
+    'missing state': (b) => !('state' in b),
+    'unknown state': (b) => 'state' in b && !STATES.has(b.state),
+    'state is case sensitive': (b) =>
+      typeof b.state === 'string' && !STATES.has(b.state) && STATES.has(b.state.toLowerCase()),
+    'malformed json': (b, raw) => !isJsonObject(raw),
+  },
+  '/session-start': {
+    'missing session_id': (b) => !('session_id' in b),
+    'missing provider_session_id': (b) => !('provider_session_id' in b) && !('claude_session_id' in b),
+    'empty provider_session_id': (b) => b.provider_session_id === '',
+    'unregistered provider': (b) => 'provider' in b && !PROVIDERS.has(b.provider),
+    'malformed json': (b, raw) => !isJsonObject(raw),
+  },
+  '/session-title': {
+    'missing session_id': (b) => !('session_id' in b),
+    'missing title': (b) => !('title' in b),
+    'empty title': (b) => b.title === '',
+    'blank title': (b) => 'title' in b && blank(b.title),
+    'malformed json': (b, raw) => !isJsonObject(raw),
+  },
+  '/session-touched': {
+    'missing session_id': (b) => !('session_id' in b),
+    'empty session_id': (b) => b.session_id === '',
+    'malformed json': (b, raw) => !isJsonObject(raw),
+  },
+}
+
+export function isJsonObject(raw) {
+  try {
+    return isObject(JSON.parse(raw))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Compares a sent body against every `accept` case's `body` for the endpoint:
+ * same key set, and each value of the same class (a non-blank string stays a
+ * non-blank string). Values themselves are dynamic — session ids and titles are
+ * whatever the session happens to hold — so only shape is asserted here;
+ * enumerated values are pinned by the reject rules.
+ *
+ * Returns the name of the case it matches, or null.
+ */
+export function matchingAcceptCase(endpoint, body) {
+  const shape = (o) =>
+    Object.keys(o)
+      .sort()
+      .map((k) => `${k}:${blank(o[k]) ? typeof o[k] + '(blank)' : typeof o[k]}`)
+      .join(',')
+  const sent = shape(body)
+  return accepted(endpoint).find((c) => c.body && shape(c.body) === sent)?.name ?? null
+}
+
+export function assertContractHonoured(endpoint, request) {
+  assert.equal(request.method, 'POST')
+  assert.equal(
+    request.url,
+    `${endpoint}?token=${TOKEN}`,
+    `posted to ${request.url}, expected ${endpoint}?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)
+
+  // claude_session_id is a deprecated alias lich still folds for plugins
+  // released before v0.3.0. Nothing shipping today emits it.
+  assert.ok(!('claude_session_id' in body), `body still sends claude_session_id: ${request.raw}`)
+
+  const match = matchingAcceptCase(endpoint, body)
+  assert.ok(match, `body matches no accepted shape for ${endpoint}: ${request.raw}`)
+
+  for (const [name, violates] of Object.entries(REJECT_RULES[endpoint])) {
+    assert.ok(!violates(body, request.raw), `body is the rejected shape "${name}": ${request.raw}`)
+  }
+  return { body, match }
+}
+
+// ------------------------------------------------------------------ harness --
+
+export async function startStub({ status = 204 } = {}) {
+  const requests = []
+  const server = createServer((req, res) => {
+    let raw = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      raw += chunk
+    })
+    req.on('end', () => {
+      requests.push({ method: req.method, url: req.url, headers: req.headers, raw })
+      res.writeHead(status).end()
+    })
+  })
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
+  return {
+    requests,
+    port: server.address().port,
+    close: () => new Promise((resolve) => server.close(resolve)),
+  }
+}
+
+export async function withStub(fn, options) {
+  const stub = await startStub(options)
+  try {
+    return await fn(stub)
+  } finally {
+    await stub.close()
+  }
+}
+
+export const lichEnv = (port) => ({
+  LICH_PORT: String(port),
+  LICH_TOKEN: TOKEN,
+  LICH_SESSION_ID,
+})
diff --git a/tests/fixtures/session-start.jsonl b/tests/fixtures/session-start.jsonl
index b0acea1..21d2460 100644
--- a/tests/fixtures/session-start.jsonl
+++ b/tests/fixtures/session-start.jsonl
@@ -1,4 +1,6 @@
 {"name":"reported provider","body":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"codex"},"accept":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"codex"}}
+{"name":"opencode session id","body":{"session_id":"s1","provider_session_id":"ses_011856954ffe5NEMhsYeTuWykR","provider":"opencode"},"accept":{"session_id":"s1","provider_session_id":"ses_011856954ffe5NEMhsYeTuWykR","provider":"opencode"}}
+{"name":"crush session id","body":{"session_id":"s1","provider_session_id":"db3492a0-4a6b-4335-8c0b-d4cc43fc4cb0","provider":"crush"},"accept":{"session_id":"s1","provider_session_id":"db3492a0-4a6b-4335-8c0b-d4cc43fc4cb0","provider":"crush"}}
 {"name":"absent provider defaults to claude","body":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01"},"accept":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"claude"}}
 {"name":"legacy claude_session_id is folded","body":{"session_id":"s1","claude_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c02"},"accept":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c02","provider":"claude"}}
 {"name":"provider_session_id wins over legacy","body":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","claude_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c02"},"accept":{"session_id":"s1","provider_session_id":"018f9c5a-0000-7000-9a3b-1c2d3e4f5c01","provider":"claude"}}
diff --git a/tests/hooks.test.mjs b/tests/hooks.test.mjs
index b50c160..4003629 100644
--- a/tests/hooks.test.mjs
+++ b/tests/hooks.test.mjs
@@ -1,173 +1,33 @@
 // Pins this plugin's hook scripts to lich's contract fixtures.
 //
-// lich owns the endpoints, this repository owns the scripts that build the
-// payloads. The fixtures in tests/fixtures/ are lich's, vendored verbatim
-// (tests/refresh-fixtures.sh); they are upstream truth and are never edited to
-// make a run green.
-//
 // Every case here drives a real script as a subprocess — the command line taken
 // from the hook registration a harness actually reads — against a stub HTTP
-// server, and asserts the body it POSTs.
+// server, and asserts the body it POSTs. The fixtures, the assertions and the
+// stub live in contract.mjs, shared with the opencode client's suite.
 //
 // Run: node --test tests/
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { createServer } from 'node:http'
 import { spawn, spawnSync } from 'node:child_process'
 import { readFileSync, writeFileSync, mkdtempSync, mkdirSync, symlinkSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const HERE = path.dirname(fileURLToPath(import.meta.url))
-const ROOT = path.resolve(HERE, '..')
-
-const TOKEN = 'test-token'
-const LICH_SESSION_ID = 'lich-session-1'
-
-// ---------------------------------------------------------------- fixtures --
-
-/** endpoint → fixture file, per lich's docs/hooks/fixtures/README.md. */
-const FIXTURE_OF = {
-  '/hook': 'session-state',
-  '/session-start': 'session-start',
-  '/session-title': 'session-title',
-  '/session-touched': 'session-touched',
-}
-
-const readFixture = (name) =>
-  readFileSync(path.join(HERE, 'fixtures', `${name}.jsonl`), 'utf8')
-    .split('\n')
-    .filter((line) => line.trim() !== '')
-    .map((line) => JSON.parse(line))
-
-const CASES = Object.fromEntries(
-  Object.entries(FIXTURE_OF).map(([endpoint, file]) => [endpoint, readFixture(file)]),
-)
-
-const accepted = (endpoint) => CASES[endpoint].filter((c) => c.accept)
-const rejected = (endpoint) => CASES[endpoint].filter((c) => c.reject)
-
-// Enumerations come from the fixtures, not from a copy of them kept here: a
-// state or a provider that lich stops accepting stops being accepted below too.
-const STATES = new Set(accepted('/hook').map((c) => c.accept.state))
-const PROVIDERS = new Set(accepted('/session-start').map((c) => c.accept.provider))
-
-const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
-const blank = (v) => typeof v !== 'string' || v.trim() === ''
-
-/**
- * `reject` prose is documentation, not a matcher, so each rejected case is
- * modelled here as a predicate: true means the body is the shape that case
- * describes. A rejected case with no rule fails its own test below, so a new
- * one upstream cannot slip through unmodelled.
- */
-const REJECT_RULES = {
-  '/hook': {
-    'missing session_id': (b) => !('session_id' in b),
-    'empty session_id': (b) => b.session_id === '',
-    'missing state': (b) => !('state' in b),
-    'unknown state': (b) => 'state' in b && !STATES.has(b.state),
-    'state is case sensitive': (b) =>
-      typeof b.state === 'string' && !STATES.has(b.state) && STATES.has(b.state.toLowerCase()),
-    'malformed json': (b, raw) => !isJsonObject(raw),
-  },
-  '/session-start': {
-    'missing session_id': (b) => !('session_id' in b),
-    'missing provider_session_id': (b) => !('provider_session_id' in b) && !('claude_session_id' in b),
-    'empty provider_session_id': (b) => b.provider_session_id === '',
-    'unregistered provider': (b) => 'provider' in b && !PROVIDERS.has(b.provider),
-    'malformed json': (b, raw) => !isJsonObject(raw),
-  },
-  '/session-title': {
-    'missing session_id': (b) => !('session_id' in b),
-    'missing title': (b) => !('title' in b),
-    'empty title': (b) => b.title === '',
-    'blank title': (b) => 'title' in b && blank(b.title),
-    'malformed json': (b, raw) => !isJsonObject(raw),
-  },
-  '/session-touched': {
-    'missing session_id': (b) => !('session_id' in b),
-    'empty session_id': (b) => b.session_id === '',
-    'malformed json': (b, raw) => !isJsonObject(raw),
-  },
-}
-
-function isJsonObject(raw) {
-  try {
-    return isObject(JSON.parse(raw))
-  } catch {
-    return false
-  }
-}
-
-/**
- * Compares a sent body against every `accept` case's `body` for the endpoint:
- * same key set, and each value of the same class (a non-blank string stays a
- * non-blank string). Values themselves are dynamic — session ids and titles are
- * whatever the session happens to hold — so only shape is asserted here;
- * enumerated values are pinned by the reject rules.
- *
- * Returns the name of the case it matches, or null.
- */
-function matchingAcceptCase(endpoint, body) {
-  const shape = (o) =>
-    Object.keys(o)
-      .sort()
-      .map((k) => `${k}:${blank(o[k]) ? typeof o[k] + '(blank)' : typeof o[k]}`)
-      .join(',')
-  const sent = shape(body)
-  return accepted(endpoint).find((c) => c.body && shape(c.body) === sent)?.name ?? null
-}
 
-function assertContractHonoured(endpoint, request) {
-  assert.equal(request.method, 'POST')
-  assert.equal(
-    request.url,
-    `${endpoint}?token=${TOKEN}`,
-    `posted to ${request.url}, expected ${endpoint}?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)
-
-  // 4. claude_session_id is a deprecated alias lich still folds for plugins
-  //    released before v0.3.0. Nothing shipping today emits it.
-  assert.ok(!('claude_session_id' in body), `body still sends claude_session_id: ${request.raw}`)
-
-  const match = matchingAcceptCase(endpoint, body)
-  assert.ok(match, `body matches no accepted shape for ${endpoint}: ${request.raw}`)
-
-  for (const [name, violates] of Object.entries(REJECT_RULES[endpoint])) {
-    assert.ok(!violates(body, request.raw), `body is the rejected shape "${name}": ${request.raw}`)
-  }
-  return { body, match }
-}
-
-// ------------------------------------------------------------------ harness --
-
-async function startStub({ status = 204 } = {}) {
-  const requests = []
-  const server = createServer((req, res) => {
-    let raw = ''
-    req.setEncoding('utf8')
-    req.on('data', (chunk) => {
-      raw += chunk
-    })
-    req.on('end', () => {
-      requests.push({ method: req.method, url: req.url, headers: req.headers, raw })
-      res.writeHead(status).end()
-    })
-  })
-  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
-  return {
-    requests,
-    port: server.address().port,
-    close: () => new Promise((resolve) => server.close(resolve)),
-  }
-}
+import {
+  CASES,
+  LICH_SESSION_ID,
+  PROVIDERS,
+  ROOT,
+  REJECT_RULES,
+  STATES,
+  TOKEN,
+  assertContractHonoured,
+  lichEnv,
+  rejected,
+  startStub,
+  withStub,
+} from './contract.mjs'
 
 /** The ambient environment minus anything lich would inject. */
 const BASE_ENV = Object.fromEntries(
@@ -198,21 +58,6 @@ function runHook(command, { env = {}, stdin = '' } = {}) {
   })
 }
 
-const lichEnv = (port) => ({
-  LICH_PORT: String(port),
-  LICH_TOKEN: TOKEN,
-  LICH_SESSION_ID,
-})
-
-async function withStub(fn, options) {
-  const stub = await startStub(options)
-  try {
-    return await fn(stub)
-  } finally {
-    await stub.close()
-  }
-}
-
 // A hook that reports never speaks on stdout: on Codex the session-state hook
 // rides PermissionRequest, where output and a non-zero exit are an answer to
 // the request rather than an observation.
@@ -226,8 +71,13 @@ function assertSilentSuccess(result) {
 const HOOK_FILES = [
   { provider: 'claude', file: 'hooks/hooks.json' },
   { provider: 'codex', file: 'hooks/codex-hooks.json' },
+  { provider: 'crush', file: 'hooks/crush-hooks.json' },
 ]
 
+// Crush has no plugin root to expand, so its registration ships the clone's
+// path as a placeholder the user replaces. Here it becomes this checkout.
+const PLUGIN_ROOT_PLACEHOLDER = '<lich-plugin>'
+
 const SCRIPTS = {
   'report-state.sh': '/hook',
   'report-tool.sh': '/hook',
@@ -236,24 +86,42 @@ const SCRIPTS = {
   'report-touched.sh': '/session-touched',
 }
 
+/**
+ * What each harness registers. Claude Code and Codex carry every report; Crush
+ * carries the two its single `PreToolUse` event can honour, because a `busy`
+ * nothing can end would pin a spinner to a card (docs/providers.md).
+ */
+const REGISTERED_SCRIPTS = {
+  claude: Object.keys(SCRIPTS),
+  codex: Object.keys(SCRIPTS),
+  crush: ['report-session-start.sh', 'report-touched.sh'],
+}
+
+/**
+ * A registration group is either Claude Code's shape (a matcher wrapping a
+ * `hooks` array) or Crush's (the hook itself, matcher included).
+ */
+const hooksIn = (group) => (Array.isArray(group.hooks) ? group.hooks : [group])
+
 function registrations() {
   const out = []
   for (const { provider, file } of HOOK_FILES) {
     const json = JSON.parse(readFileSync(path.join(ROOT, file), 'utf8'))
     for (const [event, groups] of Object.entries(json.hooks)) {
       for (const group of groups) {
-        for (const hook of group.hooks) {
+        for (const hook of hooksIn(group)) {
           const script = Object.keys(SCRIPTS).find((s) => hook.command.includes(s))
           assert.ok(script, `unknown script in ${file}: ${hook.command}`)
+          const command = hook.command.split(PLUGIN_ROOT_PLACEHOLDER).join(ROOT)
           out.push({
             provider,
             file,
             event,
             matcher: group.matcher,
-            command: hook.command,
+            command,
             script,
             endpoint: SCRIPTS[script],
-            argument: hook.command.trim().split(/\s+/).slice(1).join(' '),
+            argument: command.trim().split(/\s+/).slice(1).join(' '),
           })
         }
       }
@@ -322,8 +190,11 @@ function binWithout(missing) {
 const PROVIDER_SESSION_ID = {
   claude: '9f1c7c1e-8f2a-4c3b-9d5e-2a7b6c4d1e05',
   codex: '018f9c5a-0000-7000-9a3b-1c2d3e4f5c01',
+  crush: 'db3492a0-4a6b-4335-8c0b-d4cc43fc4cb0',
+  opencode: 'ses_011856954ffe5NEMhsYeTuWykR',
 }
 
+// Crush has no transcript to point a hook at: its payload is about the tool.
 const TRANSCRIPT = {
   claude: claudeTranscript('Fix the replay ring overflow'),
   codex: codexTranscript('Fix the replay ring overflow\nand its second line'),
@@ -339,10 +210,23 @@ const TRANSCRIPT = {
 const TOOL_CALL = {
   claude: { tool_name: 'Bash', tool_input: { command: 'pnpm test', description: 'run the suite' } },
   codex: { tool_name: 'Bash', tool_input: { command: 'go test ./...' } },
+  crush: { tool_name: 'write', tool_input: { file_path: 'probe.txt', content: 'ok\n' } },
 }
 
-/** What the harness puts on stdin for the event this registration rides. */
+/**
+ * What the harness puts on stdin for the event this registration rides. Crush's
+ * envelope is Claude Code's with two differences, both taken off a real run: it
+ * names the event `event`, and it carries no transcript.
+ */
 function stdinFor({ provider, event }) {
+  if (provider === 'crush') {
+    return JSON.stringify({
+      event,
+      session_id: PROVIDER_SESSION_ID.crush,
+      cwd: ROOT,
+      ...(event === 'PreToolUse' ? TOOL_CALL.crush : {}),
+    })
+  }
   return JSON.stringify({
     session_id: PROVIDER_SESSION_ID[provider],
     transcript_path: TRANSCRIPT[provider],
@@ -375,7 +259,7 @@ test('the vendored fixtures parse and carry exactly one body and one verdict', (
     }
   }
   assert.deepEqual([...STATES].sort(), ['busy', 'done', 'idle', 'waiting'])
-  assert.deepEqual([...PROVIDERS].sort(), ['claude', 'codex'])
+  assert.deepEqual([...PROVIDERS].sort(), ['claude', 'codex', 'crush', 'opencode'])
 })
 
 test('every rejected case is modelled by a client-side rule', () => {
@@ -390,20 +274,30 @@ test('every rejected case is modelled by a client-side rule', () => {
   }
 })
 
-test('every script is registered by both providers', () => {
-  for (const provider of ['claude', 'codex']) {
+test('each harness registers exactly the scripts it can honour', () => {
+  for (const [provider, expected] of Object.entries(REGISTERED_SCRIPTS)) {
     const scripts = new Set(REGISTRATIONS.filter((r) => r.provider === provider).map((r) => r.script))
-    assert.deepEqual([...scripts].sort(), Object.keys(SCRIPTS).sort(), `${provider} misses a script`)
+    assert.deepEqual([...scripts].sort(), [...expected].sort(), `${provider} registers the wrong set`)
   }
 })
 
+test("Crush's registration keeps the placeholder for the clone's path", () => {
+  const raw = readFileSync(path.join(ROOT, 'hooks/crush-hooks.json'), 'utf8')
+  assert.ok(
+    raw.includes(PLUGIN_ROOT_PLACEHOLDER),
+    'crush-hooks.json must ship the placeholder, not a path from somebody\'s machine',
+  )
+})
+
 test('every registered state argument is an accepted state', () => {
   const sent = REGISTRATIONS.filter((r) => r.script === 'report-state.sh').map((r) => r.argument)
   assert.ok(sent.length > 0)
   for (const state of sent) assert.ok(STATES.has(state), `registration reports unknown state "${state}"`)
-  // Both registrations wire up the whole vocabulary; Codex's SessionEnd never
-  // fires today, but the entry is deliberate (docs/providers.md).
-  for (const provider of ['claude', 'codex']) {
+  // A harness that reports state at all wires up the whole vocabulary; Codex's
+  // SessionEnd never fires today, but the entry is deliberate. Crush reports no
+  // state at all — see docs/providers.md for both.
+  for (const [provider, scripts] of Object.entries(REGISTERED_SCRIPTS)) {
+    if (!scripts.includes('report-state.sh')) continue
     const states = new Set(
       REGISTRATIONS.filter((r) => r.provider === provider && r.script === 'report-state.sh').map(
         (r) => r.argument,
diff --git a/tests/opencode.test.mjs b/tests/opencode.test.mjs
new file mode 100644
index 0000000..d232e0c
--- /dev/null
+++ b/tests/opencode.test.mjs
@@ -0,0 +1,362 @@
+// Pins the opencode client to lich's contract fixtures.
+//
+// opencode runs no commands: its client is a module its server imports, so
+// instead of spawning a script this suite imports opencode/lich.js, feeds it
+// the events opencode actually emits, and asserts the bodies it POSTs against
+// the same fixtures the hook scripts answer to (contract.mjs).
+//
+// The event payloads below were taken off a real opencode run against a stub
+// listener — an `opencode serve` driven through its own HTTP API — not off its
+// documentation.
+//
+// Run: node --test tests/
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { LICH_SESSION_ID, assertContractHonoured, lichEnv, startStub, withStub } from './contract.mjs'
+import { LichPlugin } from '../opencode/lich.js'
+
+const OPENCODE_SESSION_ID = 'ses_011856954ffe5NEMhsYeTuWykR'
+const SUB_SESSION_ID = 'ses_0118000000000000000000000000'
+const BORN_TITLE = 'New session - 2026-08-11T01:40:39.211Z'
+
+/** The shape `session.created` / `session.updated` carry. */
+const sessionInfo = (overrides = {}) => ({
+  sessionID: OPENCODE_SESSION_ID,
+  info: {
+    id: OPENCODE_SESSION_ID,
+    slug: 'swift-wizard',
+    version: '1.18.16',
+    projectID: 'global',
+    directory: '/w',
+    path: '',
+    title: BORN_TITLE,
+    cost: 0,
+    tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+    time: { created: 1786412439211, updated: 1786412439211 },
+    ...overrides,
+  },
+})
+
+/**
+ * Runs the module against a stub, feeding 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 hooks = await LichPlugin()
+        await drive({
+          event: (type, properties) => hooks.event({ event: { type, properties } }),
+          tool: (input, output) => hooks['tool.execute.before'](input, output),
+        })
+        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 + '?'))
+
+// ------------------------------------------------------------------- reports --
+
+test('session.created reports the opencode session id', async () => {
+  const requests = await reportsFor(({ event }) => event('session.created', sessionInfo()))
+  assert.equal(requests.length, 1)
+  const { body } = assertContractHonoured('/session-start', requests[0])
+  assert.equal(body.session_id, LICH_SESSION_ID)
+  assert.equal(body.provider, 'opencode')
+  assert.equal(body.provider_session_id, OPENCODE_SESSION_ID)
+})
+
+const STATUS_STATES = [
+  ['busy', 'busy'],
+  // opencode's idle is the turn ending, which is lich's done.
+  ['idle', 'done'],
+  // A retry is still working, so the spinner stays on.
+  ['retry', 'busy'],
+]
+
+for (const [type, state] of STATUS_STATES) {
+  test(`session.status ${type} reports ${state}`, async () => {
+    const requests = await reportsFor(({ event }) =>
+      event('session.status', { sessionID: OPENCODE_SESSION_ID, status: { type } }),
+    )
+    assert.equal(requests.length, 1)
+    const { body } = assertContractHonoured('/hook', requests[0])
+    assert.equal(body.state, state)
+  })
+}
+
+test('permission.asked reports waiting', async () => {
+  const requests = await reportsFor(({ event }) =>
+    event('permission.asked', {
+      id: 'per_fee7bb506001U0pyEOIdUduVvD',
+      sessionID: OPENCODE_SESSION_ID,
+      permission: 'edit',
+      patterns: ['oc-probe.txt'],
+      metadata: { filepath: '/w/oc-probe.txt' },
+    }),
+  )
+  assert.equal(requests.length, 1)
+  const { body } = assertContractHonoured('/hook', requests[0])
+  assert.equal(body.state, 'waiting')
+})
+
+test('file.edited refreshes the git status', async () => {
+  const requests = await reportsFor(({ event }) => event('file.edited', { file: '/w/oc-probe.txt' }))
+  assert.equal(requests.length, 1)
+  const { body } = assertContractHonoured('/session-touched', requests[0])
+  assert.equal(body.session_id, LICH_SESSION_ID)
+})
+
+test('tool.execute.before names the tool and what it acts on', async () => {
+  const requests = await reportsFor(({ tool }) =>
+    tool(
+      { tool: 'write', sessionID: OPENCODE_SESSION_ID, callID: 'call_1' },
+      { args: { filePath: 'oc-probe.txt', 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, 'oc-probe.txt')
+})
+
+// The detail is optional in the contract: absent, never blank.
+test('tool.execute.before omits the detail when the call carries nothing to say', async () => {
+  const requests = await reportsFor(({ tool }) =>
+    tool({ tool: 'todowrite', sessionID: OPENCODE_SESSION_ID, callID: 'c' }, { args: { todos: [] } }),
+  )
+  const { body, match } = assertContractHonoured('/hook', requests[0])
+  assert.equal(match, 'a tool with nothing to say about it')
+  assert.equal(body.tool, 'todowrite')
+  assert.ok(!('detail' in body), `sent a detail anyway: ${requests[0].raw}`)
+})
+
+test('a bash call names its command line', async () => {
+  const requests = await reportsFor(({ tool }) =>
+    tool({ tool: 'bash', sessionID: OPENCODE_SESSION_ID, callID: 'c' }, { args: { command: 'go test ./...' } }),
+  )
+  const { body } = assertContractHonoured('/hook', requests[0])
+  assert.equal(body.detail, 'go test ./...')
+})
+
+// ------------------------------------------------------------------- titles --
+
+test('the title a session is created with is not reported', async () => {
+  const requests = await reportsFor(
+    async ({ event }) => {
+      await event('session.created', sessionInfo())
+      await event('session.updated', sessionInfo())
+    },
+    { expected: 1 },
+  )
+  assert.equal(only(requests, '/session-title').length, 0, 'reported the placeholder title')
+})
+
+test('a title that replaces the placeholder is reported', async () => {
+  const requests = await reportsFor(
+    async ({ event }) => {
+      await event('session.created', sessionInfo())
+      await event('session.updated', sessionInfo({ 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')
+})
+
+test('an update with no title at all is silent', async () => {
+  const requests = await reportsFor(
+    async ({ event }) => {
+      await event('session.created', sessionInfo())
+      await event('session.updated', sessionInfo({ title: '   ' }))
+    },
+    { expected: 1 },
+  )
+  assert.equal(only(requests, '/session-title').length, 0, 'posted a blank title, which lich rejects')
+})
+
+// --------------------------------------------------------------- sub-sessions --
+
+// The task tool runs a sub-agent as its own session. Its idle is that sub-agent
+// finishing, not the turn ending, so nothing it says may reach the card.
+const sub = { ...sessionInfo().info, id: SUB_SESSION_ID, parentID: OPENCODE_SESSION_ID, title: 'sub' }
+
+test('a sub-session reports no session id of its own', async () => {
+  const requests = await reportsFor(
+    ({ event }) => event('session.created', { sessionID: SUB_SESSION_ID, info: sub }),
+    { expected: 0 },
+  )
+  assert.equal(requests.length, 0, `a sub-session answered for the card: ${requests[0]?.raw}`)
+})
+
+test('a sub-session finishing does not end the turn', async () => {
+  const requests = await reportsFor(
+    async ({ event }) => {
+      await event('session.created', { sessionID: SUB_SESSION_ID, info: sub })
+      await event('session.status', { sessionID: SUB_SESSION_ID, status: { type: 'idle' } })
+      await event('permission.asked', { sessionID: SUB_SESSION_ID, permission: 'edit' })
+    },
+    { expected: 0 },
+  )
+  assert.equal(requests.length, 0, `a sub-session answered for the card: ${requests[0]?.raw}`)
+})
+
+test('a sub-session title is not the card label', async () => {
+  const requests = await reportsFor(
+    async ({ event }) => {
+      await event('session.created', { sessionID: SUB_SESSION_ID, info: sub })
+      await event('session.updated', { sessionID: SUB_SESSION_ID, info: { ...sub, title: 'renamed' } })
+    },
+    { expected: 0 },
+  )
+  assert.equal(requests.length, 0, `a sub-session renamed the card: ${requests[0]?.raw}`)
+})
+
+test('a tool call inside a sub-session is not the card tool line', async () => {
+  const requests = await reportsFor(
+    async ({ event, tool }) => {
+      await event('session.created', { sessionID: SUB_SESSION_ID, info: sub })
+      await tool({ tool: 'bash', sessionID: SUB_SESSION_ID, callID: 'c' }, { args: { command: 'ls' } })
+    },
+    { expected: 0 },
+  )
+  assert.equal(requests.length, 0, `a sub-session put a tool on the card: ${requests[0]?.raw}`)
+})
+
+// ------------------------------------------------------------ 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'],
+}
+
+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 hooks = await LichPlugin()
+        await hooks.event({ event: { type: 'session.created', properties: sessionInfo() } })
+        await hooks.event({
+          event: { type: 'session.status', properties: { sessionID: OPENCODE_SESSION_ID, status: { type: 'busy' } } },
+        })
+        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(
+    ({ event }) => event('session.status', { sessionID: OPENCODE_SESSION_ID, status: { type: 'busy' } }),
+    { 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 hooks = await LichPlugin()
+    await hooks.event({
+      event: { type: 'session.status', properties: { sessionID: OPENCODE_SESSION_ID, status: { type: 'busy' } } },
+    })
+    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)
+  }
+})
+
+// opencode awaits its plugin hooks, so a report that waited on the listener
+// would sit in front of the agent's next step.
+test('a hook 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 hooks = await LichPlugin()
+    const started = Date.now()
+    await hooks.event({
+      event: { type: 'session.status', properties: { sessionID: OPENCODE_SESSION_ID, status: { type: 'busy' } } },
+    })
+    const elapsed = Date.now() - started
+    assert.ok(elapsed < 500, `the hook 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))
+  }
+})
+
+// An unknown event must not reach the card, and must not throw either: opencode
+// grows events between releases and this module sees all of them.
+test('an event the module knows nothing about is ignored', async () => {
+  const requests = await reportsFor(
+    async ({ event }) => {
+      await event('lsp.client.diagnostics', { serverID: 'gopls', path: '/w/main.go' })
+      await event('todo.updated', { sessionID: OPENCODE_SESSION_ID, todos: [] })
+      await event('installation.updated', { version: '1.18.17' })
+    },
+    { expected: 0 },
+  )
+  assert.equal(requests.length, 0, `an unhandled event reached lich: ${requests[0]?.raw}`)
+})
+
+test('a malformed event payload is survived', async () => {
+  const requests = await reportsFor(
+    async ({ event, tool }) => {
+      await event('session.created', {})
+      await event('session.created', undefined)
+      await event('session.status', { sessionID: OPENCODE_SESSION_ID })
+      await event('session.updated', { info: null })
+      await tool(undefined, undefined)
+    },
+    { expected: 0 },
+  )
+  assert.equal(requests.length, 0, `a malformed payload reached lich: ${requests[0]?.raw}`)
+})