From a2b32e211b1388c9d2a6e0a760aeba86da3ed9ef Mon Sep 17 00:00:00 2001
From: omartelo <meopedevts@proton.me>
Date: Sat, 22 Aug 2026 20:49:12 -0300
Subject: [PATCH 1/2] feat: say what a waiting session is waiting for
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `waiting` report now carries a `reason`, so the bell on a lich card says
why the session is blocked rather than only that it is. Client side of the
contract change that landed in lich; the field is optional there, trimmed and
capped, and belongs to `waiting` alone.

Each harness hands over something different to say it with, and none of them
was taken off documentation:

  - Claude Code's `Notification` message is already 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 — both go out unchanged, and lich
    still decides which arrived.
  - Codex's `PermissionRequest` has no message field at all, so the report is
    the tool it is asking about with the same words a busy report puts on the
    card behind it: `apply_patch: internal/terminal/usage.go`. That second half
    moves into hooks/detail.jq, shared with report-tool.sh so the two readings
    of one tool call cannot drift.
  - opencode's four `.asked` events spell it four ways, so lich.js reads it by
    field the way it already reads a tool call: `permission`, the v2 `action`,
    then a question's own short `header` with its full text behind it. The
    generic suffix rule stays — a prompt type nobody enumerated still reports
    `waiting` with no reason, which is the documented degrade.

omp and Crush report no `waiting` at all, so neither gains anything here.

A reason it cannot build is never a reason to drop the report: an absent one,
a blank one and a payload with nothing to read all still ring the bell. Without
jq the message stays home, as the detail already did, but Codex's tool name is
an identifier and goes out alone.
---
 CHANGELOG.md                       |  14 ++++
 CLAUDE.md                          |   1 +
 docs/providers.md                  |  10 ++-
 docs/session-state.md              |  53 ++++++++++++--
 hooks/detail.jq                    |  31 ++++++++
 hooks/report-state.sh              |  47 +++++++++++-
 hooks/report-tool.sh               |  32 +-------
 opencode/lich.js                   |  14 +++-
 tests/fixtures/session-state.jsonl |   4 +
 tests/hooks.test.mjs               | 114 ++++++++++++++++++++++++++++-
 tests/opencode.test.mjs            |  33 ++++++++-
 11 files changed, 312 insertions(+), 41 deletions(-)
 create mode 100644 hooks/detail.jq

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-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..8e81c7c 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', () => {
@@ -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/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

From 5a983845839da1bc46364b9d165ca89e16be1067 Mon Sep 17 00:00:00 2001
From: omartelo <meopedevts@proton.me>
Date: Sat, 22 Aug 2026 21:35:07 -0300
Subject: [PATCH 2/2] test: register omp as a provider, as lich now does
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The vendored session-start fixtures were a case behind lich, which has since
registered `omp` as a provider id. Refreshed, so `fixtures-drift` stops failing
on a copy nobody refetched.

That retires the workaround it forced: omp's session-start assertion skipped the
contract's own "unregistered provider" rule, because the rule fired on an
otherwise correct payload. It was written to fold back into the shared assertion
the day the case landed, and this is that day — so it does, and the imports it
needed go with it.
---
 tests/fixtures/session-start.jsonl |  1 +
 tests/hooks.test.mjs               |  2 +-
 tests/omp.test.mjs                 | 40 +++++-------------------------
 3 files changed, 8 insertions(+), 35 deletions(-)

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/hooks.test.mjs b/tests/hooks.test.mjs
index 8e81c7c..ef1e716 100644
--- a/tests/hooks.test.mjs
+++ b/tests/hooks.test.mjs
@@ -292,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', () => {
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 --