diff --git a/CHANGELOG.md b/CHANGELOG.md
index eebde15..cb093f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **A waiting card says what the session is waiting for.** The `waiting` report
+  now carries a `reason`, so the bell says *why* rather than only *that*. Each
+  harness hands over something different to say it with: Claude Code's
+  `Notification` message, which is already a sentence written for a human
+  ("Claude needs your permission to use Bash") and covers the plain idle nudge
+  too; the tool Codex's `PermissionRequest` is asking about, qualified with the
+  same words a busy report puts on the card (`apply_patch:
+  internal/terminal/usage.go`); and, on opencode, the permission, the v2 action
+  or a question's own short header. Read by field rather than by event name, so
+  a prompt type nobody enumerated still rings the bell — the reason is optional
+  in the contract, and a missing one is never a reason to drop the report. omp
+  and Crush report no `waiting` at all, so neither gains anything here. No
+  minimum lich: the field is additive in both directions, so an older lich
+  ignores it and rings the bell exactly as before.
 - **An opencode session can rename a lich card.** `rename_session` is the eighth
   tool, beside the seven that were already there: with a session it renames that
   one, with only a name it renames the session the agent is running in — which is
diff --git a/CLAUDE.md b/CLAUDE.md
index 43ec691..a3e591c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,6 +13,7 @@ hooks/hooks.json                  # hook registration, Claude Code
 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)
+hooks/detail.jq                   # what a tool call acts on, shared by two of those scripts
 hooks/win-run.cmd                 # runs one of those scripts on Windows (Codex)
 opencode/lich.js                  # opencode client: a module, not a command
 omp/lich.js                       # omp client: a module, not a command
diff --git a/docs/providers.md b/docs/providers.md
index 5706924..7d7d28e 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -49,7 +49,7 @@ swallows its own errors and never awaits a report.
 | 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)            | —                           |
+| `waiting` + reason  | `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)  | —                           |
@@ -75,7 +75,13 @@ It asks the user in more than one way — `permission.asked` and `question.asked
 each with a `.v2.` spelling published beside it — and its catalogue is not
 exhaustive: a real run emits types (`server.heartbeat`) absent from its own
 schema. Enumerating names there is how a prompt goes unreported, so the module
-matches the suffix. See [session-state.md](session-state.md).
+matches the suffix, and reads what the prompt is about by field for the same
+reason. See [session-state.md](session-state.md).
+
+A `waiting` report says what the session is blocked on, and each harness hands
+over something different to say it with — a sentence, a tool name, a permission.
+The per-harness table is in [session-state.md](session-state.md#the-reason);
+omp and Crush have no cell there, because neither reports `waiting` at all.
 
 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
diff --git a/docs/session-state.md b/docs/session-state.md
index 2cd77a0..bb99e35 100644
--- a/docs/session-state.md
+++ b/docs/session-state.md
@@ -14,7 +14,7 @@ toast) when the agent is blocked on the user.
 | `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 waiting` | `waiting`+`reason`| `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
@@ -33,9 +33,10 @@ therefore shows a spinner, not a bell, while the agent waits on you — one stat
 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.
+The endpoint, the accepted states and the optional fields (`tool` / `detail`
+on the pre-tool report, `reason` on the waiting one) are spelled out once, in
+[lich's contract](https://github.com/omartelo/lich/blob/main/docs/hooks/session-state.md).
+What is below is only what each harness gives this plugin to fill them with.
 
 `Notification` fires when Claude needs a permission decision or has been idle
 waiting for input — both mean "your turn". A later `busy` or `done` clears it.
@@ -57,6 +58,46 @@ Answering (`question.replied` → `session.status busy`) and dismissing
 (`question.rejected` → `session.status idle`) both re-arm the card on their own,
 which is why neither is registered here.
 
+## The reason
+
+A `waiting` report carries what the agent is blocked on, so the bell on the card
+says *why* rather than only *that*. It rides `waiting` alone — lich drops it on
+every other state — and it is optional in both directions: the bell has to land
+whether or not a reason could be built, so no shape below is ever a reason to
+refuse the report.
+
+| harness     | where the reason comes from                                            |
+|-------------|------------------------------------------------------------------------|
+| Claude Code | the `Notification` payload's `message`                                  |
+| Codex       | `tool_name`, qualified with the same `detail` a busy report would carry |
+| opencode    | `permission`, the v2 `action`, or a question's `header`                 |
+| omp, Crush  | — neither reports `waiting` at all                                      |
+
+Claude Code is the only harness that hands over a sentence written for a human
+("Claude needs your permission to use Bash"), and it writes one for the plain
+idle-at-the-prompt nudge too — which is a reason as much as a permission is, so
+both go out unchanged and lich still decides which arrived. Codex's
+`PermissionRequest` has no message field at all: its payload is the `PreToolUse`
+envelope plus `model`, `permission_mode` and `turn_id`, so the report is the
+tool it is asking about with the words the busy report already puts on the card
+behind it — `apply_patch: internal/terminal/usage.go`. That second half is
+[`detail.jq`](../hooks/detail.jq), shared with `report-tool.sh` so the two
+readings of a tool call cannot drift.
+
+opencode's four `.asked` events spell it four ways, so `lich.js` reads it by
+field the way it reads a tool call's detail: `permission`, then the v2 `action`,
+then the first question's `header` — opencode's own ≤30-character label, built
+for exactly this kind of surface — with the full question behind it when a
+caller left the header out. A field rule covers the next prompt type too, and
+one that carries none of them still reports `waiting` with nothing attached,
+which is the documented degrade rather than a bug.
+
+Nothing here measures the reason's length: lich caps it, and a cap is not a
+refusal. Without `jq` (Windows, usually) the message stays home for the same
+reason the detail does — a hand-built body cannot escape arbitrary text — but
+Codex's tool name is an identifier and goes out alone, and Codex is the harness
+that needs the Windows wrapper.
+
 `SessionEnd → idle` clears the card's indicator (no spinner/check/bell). It
 fires when the session ends or is reset, so a stale state does not linger on a
 dead session, and a `/clear` starts the next session with a clean card. Codex
@@ -107,7 +148,9 @@ spell it `path` (read, write, edit, glob), `command` (bash) or `pattern`
 `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:
+Two shapes need more than the plain rule, and both live in
+[`detail.jq`](../hooks/detail.jq) — one copy, because the waiting report reads
+the same tool call for the second half of its reason:
 
 - **`apply_patch`** passes the *whole patch* as its command, so the plain rule
   would put `*** Begin Patch` on the card. The file its `*** Add/Update/Delete
diff --git a/hooks/detail.jq b/hooks/detail.jq
new file mode 100644
index 0000000..f2642d0
--- /dev/null
+++ b/hooks/detail.jq
@@ -0,0 +1,31 @@
+# The agent's own words for what a tool call acts on, read by field rather than
+# by tool name: one rule then covers every harness, because a Codex shell call
+# arrives as `Bash` carrying the same `command` string Claude Code sends.
+#
+# Shared, so the two readings of it cannot drift: `report-tool.sh` sends it as
+# the `detail` of a busy report, `report-state.sh` as half the `reason` of a
+# waiting one. Contract: ../docs/session-state.md.
+#
+# `apply_patch` is the exception. Codex passes the whole patch as the command,
+# so the plain rule would put "*** Begin Patch" on the card; the file the patch
+# names is the readable half of it. A patch touching several files shows the
+# first, which is the one the eye would land on anyway.
+#
+# A path is shortened against the session's own directory, because a card is
+# 240px wide and both harnesses report absolute ones: a full path fills the line
+# with the part every card shares. Outside that directory only the file name is
+# left, which at least names the file. Commands are never shortened — a leading
+# slash there belongs to a binary, not to a path worth cutting.
+.cwd as $cwd
+| def short: if ($cwd // "") != "" and startswith($cwd + "/") then ltrimstr($cwd + "/")
+             elif startswith("/") then sub(".*/"; "")
+             else . end;
+  (.tool_input // {})
+| if ((.command? // "") | tostring) != "" then
+    (.command | tostring
+     | if startswith("*** Begin Patch")
+       then ((capture("\\*\\*\\* (?:Add|Update|Delete) File: (?<p>[^\n]*)") // {}) | .p // "")
+       else . end)
+  else
+    ((.file_path? // .path? // .pattern? // .url? // .query? // "") | tostring | short)
+  end
diff --git a/hooks/report-state.sh b/hooks/report-state.sh
index 92f8b9f..205fdac 100755
--- a/hooks/report-state.sh
+++ b/hooks/report-state.sh
@@ -1,14 +1,59 @@
 #!/bin/sh
 # Reports session state to lich. Contract: docs/session-state.md
 # Usage: report-state.sh <busy|done|waiting|idle>
+# stdin: the hook payload — read for `waiting` alone, for the reason below.
 
 # Outside lich (vars absent) → no-op. Safe to install globally.
 [ -n "$LICH_PORT" ] && [ -n "$LICH_TOKEN" ] && [ -n "$LICH_SESSION_ID" ] || exit 0
 
+state=$1
+body="{\"session_id\":\"${LICH_SESSION_ID}\",\"state\":\"${state}\"}"
+
+# `reason` says what the agent is blocked on, and belongs to `waiting` alone —
+# lich drops it on every other state, so no other branch reads stdin. It is
+# optional in both directions: an absent one still rings the bell, and a value
+# lich finds too long is capped there rather than refused, so nothing here
+# measures it.
+if [ "$state" = waiting ]; then
+  payload=$(cat)
+  if command -v jq >/dev/null 2>&1; then
+    # Claude Code's Notification is the one payload carrying a sentence written
+    # for a human ("Claude needs your permission to use Bash"), and it writes one
+    # for the plain idle-at-the-prompt nudge too — which is a reason as well.
+    # `strings` guards against a harness that ever sends something else there,
+    # `\S` against whitespace, and `head` keeps it to the one line a card is.
+    reason=$(printf '%s' "$payload" | \
+      jq -r '.message | strings | select(test("\\S"))' 2>/dev/null | head -n 1)
+    if [ -z "$reason" ]; then
+      # Codex's PermissionRequest has no message field at all, so its report is
+      # the tool it is asking about, qualified with the words the busy report
+      # already puts on the card.
+      tool=$(printf '%s' "$payload" | jq -r '.tool_name // empty' 2>/dev/null | head -n 1)
+      detail=$(printf '%s' "$payload" | \
+        jq -r -f "$(dirname "$0")/detail.jq" 2>/dev/null | head -n 1)
+      if [ -n "$tool" ]; then
+        reason=$tool
+        [ -n "$detail" ] && reason="$tool: $detail"
+      fi
+    fi
+    [ -n "$reason" ] && body=$(jq -cn --arg sid "$LICH_SESSION_ID" --arg reason "$reason" \
+      '{session_id: $sid, state: "waiting", reason: $reason}')
+  else
+    # Without jq (Windows, usually) the message does not go out: it is arbitrary
+    # text, and a hand-built body cannot escape it. A tool name is an identifier
+    # and can, which is the whole of what Codex — the harness that needs the
+    # Windows wrapper — sends anyway.
+    tool=$(printf '%s' "$payload" | \
+      sed -n 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+    [ -n "$tool" ] && \
+      body="{\"session_id\":\"${LICH_SESSION_ID}\",\"state\":\"waiting\",\"reason\":\"${tool}\"}"
+  fi
+fi
+
 curl -s -o /dev/null --max-time 1 \
   -X POST "http://127.0.0.1:${LICH_PORT}/hook?token=${LICH_TOKEN}" \
   -H 'Content-Type: application/json' \
-  -d "{\"session_id\":\"${LICH_SESSION_ID}\",\"state\":\"$1\"}" \
+  -d "$body" \
   || true
 
 # Never blocks or fails the turn.
diff --git a/hooks/report-tool.sh b/hooks/report-tool.sh
index 2bf9e6e..6c9cf0a 100755
--- a/hooks/report-tool.sh
+++ b/hooks/report-tool.sh
@@ -10,6 +10,7 @@
 # Outside lich (vars absent) → no-op. Safe to install globally.
 [ -n "$LICH_PORT" ] && [ -n "$LICH_TOKEN" ] && [ -n "$LICH_SESSION_ID" ] || exit 0
 
+here=$(dirname "$0")
 payload=$(cat)
 command -v jq >/dev/null 2>&1 && has_jq=1 || has_jq=
 
@@ -25,36 +26,11 @@ fi
 [ -n "$tool" ] || exit 0
 
 # What the call is about, taken from whichever field the harness filled rather
-# than from the tool's name: one rule then covers both, because a Codex shell
-# call arrives as `Bash` with the same `command` field Claude Code uses. Only
-# with jq — the value is arbitrary text, and a hand-built body cannot escape it.
-#
-# `apply_patch` is the exception. Codex passes the whole patch as the command,
-# so the plain rule would put "*** Begin Patch" on the card; the file the patch
-# names is the readable half of it. A patch touching several files shows the
-# first, which is the one the eye would land on anyway.
-#
-# A path is shortened against the session's own directory, because a card is
-# 240px wide and both harnesses report absolute ones: a full path fills the line
-# with the part every card shares. Outside that directory only the file name is
-# left, which at least names the file. Commands are never shortened — a leading
-# slash there belongs to a binary, not to a path worth cutting.
+# than from the tool's name — detail.jq, shared with the waiting report. Only
+# with jq: the value is arbitrary text, and a hand-built body cannot escape it.
 detail=""
 if [ -n "$has_jq" ]; then
-  detail=$(printf '%s' "$payload" | jq -r '
-    .cwd as $cwd
-    | def short: if ($cwd // "") != "" and startswith($cwd + "/") then ltrimstr($cwd + "/")
-                 elif startswith("/") then sub(".*/"; "")
-                 else . end;
-      (.tool_input // {})
-    | if ((.command? // "") | tostring) != "" then
-        (.command | tostring
-         | if startswith("*** Begin Patch")
-           then ((capture("\\*\\*\\* (?:Add|Update|Delete) File: (?<p>[^\n]*)") // {}) | .p // "")
-           else . end)
-      else
-        ((.file_path? // .path? // .pattern? // .url? // .query? // "") | tostring | short)
-      end' 2>/dev/null | head -n 1)
+  detail=$(printf '%s' "$payload" | jq -r -f "$here/detail.jq" 2>/dev/null | head -n 1)
 fi
 
 # The detail is omitted rather than sent empty: the contract's optional field is
diff --git a/opencode/lich.js b/opencode/lich.js
index e7b7a9b..31ed183 100644
--- a/opencode/lich.js
+++ b/opencode/lich.js
@@ -36,6 +36,18 @@ function detailOf(args) {
   return undefined
 }
 
+// What an opencode prompt is blocking on. Read by field, the way detailOf
+// above reads a tool call: the four `.asked` events spell it four ways
+// (`permission`, the v2 `action`, and a question's own short `header` with its
+// full text behind it), and a field rule covers the next one too. A type that
+// carries none of them still reports `waiting` with no reason, which is the
+// documented degrade rather than a bug.
+function reasonOf(properties) {
+  const first = properties?.questions?.[0]
+  const reason = properties?.permission ?? properties?.action ?? first?.header ?? first?.question
+  return typeof reason === "string" && reason.trim() !== "" ? reason : undefined
+}
+
 // The lich command every tool below shells out to. lich exports it into each
 // PTY it spawns, and the contract says to call *that* one rather than whatever
 // `lich` resolves to on PATH: a machine running an installed lich beside a
@@ -345,7 +357,7 @@ export const LichPlugin = async ({ $ } = {}, helper) => {
           // next status report, which follows a reply within ~100ms; a missing
           // one costs the user the session.
           if (event?.type?.endsWith(".asked") && !subSessions.has(properties.sessionID)) {
-            report("hook", { state: "waiting" })
+            report("hook", { state: "waiting", reason: reasonOf(properties) })
           }
       }
     },
diff --git a/tests/fixtures/session-start.jsonl b/tests/fixtures/session-start.jsonl
index 21d2460..eadbb30 100644
--- a/tests/fixtures/session-start.jsonl
+++ b/tests/fixtures/session-start.jsonl
@@ -1,5 +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":"omp session id","body":{"session_id":"s1","provider_session_id":"019ffb38-ceab-7000-afae-20b8eae145d8","provider":"omp"},"accept":{"session_id":"s1","provider_session_id":"019ffb38-ceab-7000-afae-20b8eae145d8","provider":"omp"}}
 {"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"}}
diff --git a/tests/fixtures/session-state.jsonl b/tests/fixtures/session-state.jsonl
index dcba061..fa87adf 100644
--- a/tests/fixtures/session-state.jsonl
+++ b/tests/fixtures/session-state.jsonl
@@ -8,6 +8,10 @@
 {"name":"tool and detail are trimmed","body":{"session_id":"s1","state":"busy","tool":"  shell  ","detail":"  go test ./...  "},"accept":{"session_id":"s1","state":"busy","tool":"shell","detail":"go test ./..."}}
 {"name":"a detail with no tool names nothing","body":{"session_id":"s1","state":"busy","detail":"pnpm test"},"accept":{"session_id":"s1","state":"busy","tool":"","detail":""}}
 {"name":"whitespace is not a tool","body":{"session_id":"s1","state":"busy","tool":"   ","detail":"pnpm test"},"accept":{"session_id":"s1","state":"busy","tool":"","detail":""}}
+{"name":"waiting says what it is blocked on","body":{"session_id":"s1","state":"waiting","reason":"Claude needs your permission to use Bash"},"accept":{"session_id":"s1","state":"waiting","reason":"Claude needs your permission to use Bash"}}
+{"name":"a reason is trimmed","body":{"session_id":"s1","state":"waiting","reason":"  edit  "},"accept":{"session_id":"s1","state":"waiting","reason":"edit"}}
+{"name":"whitespace is not a reason","body":{"session_id":"s1","state":"waiting","reason":"   "},"accept":{"session_id":"s1","state":"waiting","reason":""}}
+{"name":"a reason outside waiting names nothing","body":{"session_id":"s1","state":"busy","reason":"Claude needs your permission to use Bash"},"accept":{"session_id":"s1","state":"busy","reason":""}}
 {"name":"missing session_id","body":{"state":"busy"},"reject":"session_id is required"}
 {"name":"empty session_id","body":{"session_id":"","state":"busy"},"reject":"session_id is required"}
 {"name":"unknown state","body":{"session_id":"s1","state":"cooking"},"reject":"state must be one of busy, done, waiting, idle"}
diff --git a/tests/hooks.test.mjs b/tests/hooks.test.mjs
index 525cdc9..ef1e716 100644
--- a/tests/hooks.test.mjs
+++ b/tests/hooks.test.mjs
@@ -213,6 +213,37 @@ const TOOL_CALL = {
   crush: { tool_name: 'write', tool_input: { file_path: 'probe.txt', content: 'ok\n' } },
 }
 
+/** The event each harness raises a `waiting` report from. */
+const WAITING_EVENT = { claude: 'Notification', codex: 'PermissionRequest' }
+
+/**
+ * The payload behind a `waiting` report, per harness. Claude Code's
+ * `Notification` is the only one carrying a sentence written for a human, and
+ * it fires for the plain idle nudge with the same fields; Codex's
+ * `PermissionRequest` has no message at all — its required fields (measured
+ * against the schema in the codex 0.149.0 binary) are the PreToolUse envelope
+ * plus `model`, `permission_mode` and `turn_id`.
+ */
+const WAITING = {
+  claude: {
+    message: 'Claude needs your permission to use Bash',
+    title: 'Claude Code',
+    notification_type: 'permission_prompt',
+  },
+  codex: {
+    ...TOOL_CALL.codex,
+    model: 'gpt-5.1-codex',
+    permission_mode: 'default',
+    turn_id: 'turn_01',
+  },
+}
+
+/** The reason each of those payloads must put on the card. */
+const WAITING_REASON = {
+  claude: WAITING.claude.message,
+  codex: 'Bash: go test ./...',
+}
+
 /**
  * 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
@@ -233,9 +264,11 @@ function stdinFor({ provider, event }) {
     cwd: ROOT,
     hook_event_name: event,
     ...(event === 'PreToolUse' ? TOOL_CALL[provider] : {}),
+    ...(WAITING_EVENT[provider] === event ? WAITING[provider] : {}),
   })
 }
 
+
 // ----------------------------------------------------------------- the suite --
 
 test('the vendored fixtures parse and carry exactly one body and one verdict', () => {
@@ -259,7 +292,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', 'crush', 'opencode'])
+  assert.deepEqual([...PROVIDERS].sort(), ['claude', 'codex', 'crush', 'omp', 'opencode'])
 })
 
 test('every rejected case is modelled by a client-side rule', () => {
@@ -361,7 +394,13 @@ for (const registration of REGISTRATIONS) {
 
       const { body } = assertContractHonoured(endpoint, stub.requests[0])
       assert.equal(body.session_id, LICH_SESSION_ID)
-      if (script === 'report-state.sh') assert.equal(body.state, argument)
+      if (script === 'report-state.sh') {
+        assert.equal(body.state, argument)
+        // Only `waiting` carries a reason — lich drops it on every other state,
+        // so sending one there would be noise the contract throws away.
+        if (argument === 'waiting') assert.equal(body.reason, WAITING_REASON[provider])
+        else assert.ok(!('reason' in body), `${argument} sent a reason: ${stub.requests[0].raw}`)
+      }
       if (script === 'report-tool.sh') {
         assert.equal(body.state, 'busy')
         assert.equal(body.tool, TOOL_CALL[provider].tool_name)
@@ -387,6 +426,79 @@ test('session-start falls back to claude when the registration passes no provide
   })
 })
 
+// The reason is what a bell on a card says the session is blocked on. It is
+// optional in the contract, and the bell has to land either way — so every
+// shape that cannot produce one still sends the plain `waiting`.
+const NO_REASON = [
+  ['a payload with neither a message nor a tool', { hook_event_name: 'Notification' }],
+  ['a message that is whitespace', { message: '   ' }],
+  ['a message that is not a string', { message: { text: 'permission' } }],
+]
+
+for (const [label, payload] of NO_REASON) {
+  test(`waiting still rings the bell for ${label}`, async () => {
+    await withStub(async (stub) => {
+      const result = await runHook(`"${ROOT}/hooks/report-state.sh" waiting`, {
+        env: lichEnv(stub.port),
+        stdin: JSON.stringify({ cwd: ROOT, ...payload }),
+      })
+      assertSilentSuccess(result)
+      assert.equal(stub.requests.length, 1, 'a reason it could not build cost the report')
+      const { body } = assertContractHonoured('/hook', stub.requests[0])
+      assert.equal(body.state, 'waiting')
+      assert.ok(!('reason' in body), `sent a reason it has no words for: ${stub.requests[0].raw}`)
+    })
+  })
+}
+
+// Windows ships sed (Git Bash) but rarely jq. A message is arbitrary text a
+// hand-built body cannot escape, so it stays home; Codex's tool name is an
+// identifier, and Codex is the harness that needs the Windows wrapper.
+test('waiting reports the tool name as its reason without jq', async () => {
+  await withStub(async (stub) => {
+    const result = await runHook(`"${ROOT}/hooks/report-state.sh" waiting`, {
+      env: { ...lichEnv(stub.port), PATH: binWithout('jq') },
+      stdin: stdinFor({ provider: 'codex', event: 'PermissionRequest' }),
+    })
+    assertSilentSuccess(result)
+    const { body } = assertContractHonoured('/hook', stub.requests[0])
+    assert.equal(body.reason, TOOL_CALL.codex.tool_name)
+  })
+})
+
+test('waiting sends no message-shaped reason without jq', async () => {
+  await withStub(async (stub) => {
+    const result = await runHook(`"${ROOT}/hooks/report-state.sh" waiting`, {
+      env: { ...lichEnv(stub.port), PATH: binWithout('jq') },
+      stdin: stdinFor({ provider: 'claude', event: 'Notification' }),
+    })
+    assertSilentSuccess(result)
+    const { body } = assertContractHonoured('/hook', stub.requests[0])
+    assert.equal(body.state, 'waiting')
+    assert.ok(!('reason' in body), `escaped nothing and sent it anyway: ${stub.requests[0].raw}`)
+  })
+})
+
+// Only `waiting` reads stdin. The other three states are reported from events
+// whose payload says nothing about a reason, and a script waiting on a pipe
+// nobody writes to would hold the turn it must never block.
+for (const state of ['busy', 'done', 'idle']) {
+  test(`${state} reports without reading stdin`, async () => {
+    await withStub(async (stub) => {
+      const child = spawn('/bin/sh', ['-c', `"${ROOT}/hooks/report-state.sh" ${state}`], {
+        env: { ...BASE_ENV, ...lichEnv(stub.port) },
+        stdio: ['pipe', 'ignore', 'ignore'],
+      })
+      child.stdin.on('error', () => {})
+      const code = await new Promise((resolve) => child.on('close', resolve))
+      child.stdin.destroy()
+      assert.equal(code, 0)
+      assert.equal(stub.requests.length, 1)
+      assert.equal(assertContractHonoured('/hook', stub.requests[0]).body.state, state)
+    })
+  })
+}
+
 test('session-start parses the payload without jq', async () => {
   // Windows ships sed (Git Bash) but rarely jq; the script falls back to sed.
   await withStub(async (stub) => {
diff --git a/tests/omp.test.mjs b/tests/omp.test.mjs
index c56bc45..a61eeec 100644
--- a/tests/omp.test.mjs
+++ b/tests/omp.test.mjs
@@ -18,13 +18,8 @@ import assert from 'node:assert/strict'
 
 import {
   LICH_SESSION_ID,
-  PROVIDERS,
-  REJECT_RULES,
-  TOKEN,
   assertContractHonoured,
-  isJsonObject,
   lichEnv,
-  matchingAcceptCase,
   startStub,
   withStub,
 } from './contract.mjs'
@@ -104,35 +99,12 @@ async function settle(stub, expected) {
 
 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 }
-}
+// lich has registered `omp` as a provider id, so this client answers to the
+// same assertion every other one does. It did not always: while the case was
+// missing from the vendored fixtures the contract's own "unregistered provider"
+// rule fired on an otherwise correct payload, and this skipped that one rule
+// rather than edit upstream truth to make a run green.
+const assertSessionStart = (request) => assertContractHonoured('/session-start', request)
 
 // ------------------------------------------------------------------ reports --
 
diff --git a/tests/opencode.test.mjs b/tests/opencode.test.mjs
index 44f4074..810d072 100644
--- a/tests/opencode.test.mjs
+++ b/tests/opencode.test.mjs
@@ -145,23 +145,50 @@ const ASKED_EVENTS = {
   },
 }
 
+// What each of those must put on the card: the permission itself, the v2
+// `action` under its own name, and a question's own short label — opencode
+// builds `header` for exactly this kind of surface, with the full question
+// behind it when a caller left it out.
+const ASKED_REASON = {
+  'permission.asked': 'edit',
+  'question.asked': 'Hot drink preference',
+  'permission.v2.asked': 'edit',
+  'question.v2.asked': 'coffee or tea?',
+}
+
 for (const [type, properties] of Object.entries(ASKED_EVENTS)) {
-  test(`${type} reports waiting`, async () => {
+  test(`${type} reports waiting and what it is blocked on`, async () => {
     const requests = await reportsFor(({ event }) => event(type, properties))
     assert.equal(requests.length, 1)
     const { body } = assertContractHonoured('/hook', requests[0])
     assert.equal(body.state, 'waiting')
+    assert.equal(body.reason, ASKED_REASON[type])
   })
 }
 
 // The point of the suffix rule: a prompt opencode adds later, under a name
 // nothing here knows, still reaches the card.
-test('an unknown .asked event reports waiting', async () => {
+test('an unknown .asked event reports waiting with no reason', async () => {
   const requests = await reportsFor(({ event }) =>
     event('elicitation.asked', { id: 'eli_1', sessionID: OPENCODE_SESSION_ID }),
   )
   assert.equal(requests.length, 1)
-  assert.equal(assertContractHonoured('/hook', requests[0]).body.state, 'waiting')
+  const { body } = assertContractHonoured('/hook', requests[0])
+  assert.equal(body.state, 'waiting')
+  // The documented degrade: a payload nothing here can destructure still rings
+  // the bell. A reason is optional; a missing bell costs the user the session.
+  assert.ok(!('reason' in body), `named a reason it cannot know: ${requests[0].raw}`)
+})
+
+// A field of the right name but the wrong shape is not a reason either.
+test('an .asked event whose reason is blank reports waiting alone', async () => {
+  const requests = await reportsFor(({ event }) =>
+    event('permission.asked', { id: 'per_1', sessionID: OPENCODE_SESSION_ID, permission: '   ' }),
+  )
+  assert.equal(requests.length, 1)
+  const { body } = assertContractHonoured('/hook', requests[0])
+  assert.equal(body.state, 'waiting')
+  assert.ok(!('reason' in body), `sent a blank reason: ${requests[0].raw}`)
 })
 
 // ...and its bound: the suffix is the whole rule, so an event merely mentioning