cdx-manager 0.18.3 → 0.18.5

package/README.md

@@ -1,6 +1,10 @@
+<img src="docs/assets/icon.png" alt="CDX Manager icon" width="64" align="left" />
+
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.18.3-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+<br clear="left"/>
+
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.18.5-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Stop guessing which AI account still has quota.** `cdx` tracks the rate-limit window of every Codex and Claude account you own, tells you which one is usable right now, and launches it with isolated auth — in one command.
 
@@ -374,10 +378,33 @@ configuration and, on Codex, puts an approval prompt in front of you. That is
 not something to do to sessions you already own without being asked.
 
 Response previews are separately off by default. When enabled, a completion
-notification includes at most 180 characters of the agent's final response.
-That text can be visible on a lock screen, so enable it only for sessions whose
-output is safe to expose. Previews never read transcripts and are not shown for
-permission requests.
+notification includes at most 180 characters of the agent's final response, and
+a permission request may quote the provider's own one-line description of what
+it wants to do. That text can be visible on a lock screen, so enable it only for
+sessions whose output is safe to expose. Previews never read transcripts, and
+the command a permission request is about is never included.
+
+Both providers are subscribed to the same two hooks: `Stop` when a turn ends and
+`PermissionRequest` when one blocks on your approval. Claude Code is also
+subscribed to `Notification`, for the "still waiting for you" states that no
+other hook reports; the permission notifications it also sends are dropped,
+because `PermissionRequest` already reported the same call immediately and by
+name.
+
+Claude Code additionally reports a turn that ended on a provider error rather
+than on an answer — a rate limit, an overload, an authentication or billing
+problem. Those alerts are marked apart from completions, name the error class,
+and say whether the failure is one that usually clears on its own or one that
+needs you. Codex documents no equivalent hook, so a Codex turn killed by its
+provider stays silent; that is a gap in what the provider publishes, not a
+setting.
+
+A running tray companion receives each alert as fields rather than as a
+sentence, so its menu can name the session, the project and the tool, and
+clicking a recent alert opens the session it came from. The tool's arguments,
+the transcript path and the provider's own session identifiers are never part of
+that — only what cdx already knew and what the providers document as safe
+metadata.
 
 `cdx notify` is the internal hook target, called by the provider; it is not the
 setup command. `cdx ready` is separate: it notifies you when the next cooling-
@@ -515,12 +542,15 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx status <name> [--json] [--refresh\|--cached] [--timeout SECONDS]` | Show detailed usage breakdown for one session; `--cached` avoids live provider refreshes |
 | `cdx tray status [--json] [--refresh]` | Emit the tray snapshot: one icon state, one line per enabled session, and how fresh each figure is. Reads stored status by default; `--refresh` is the only path that probes a provider |
 | `cdx tray launch [--json]` | Start the installed tray companion, detached. Reports `tray_companion_not_installed` when nothing is recorded, or `tray_companion_missing` when the recorded companion is gone. `CDX_TRAY_BIN` points it at a locally built one |
-| `cdx tray install [--json]` | Download the companion for this OS and architecture, verify its published checksum before unpacking, and record what was written. Refuses when no checksum is published for the asset |
+| `cdx tray install [--json] [--yes] [--autostart\|--no-autostart] [--alerts\|--no-alerts]` | Download the companion for this OS and architecture, verify its published checksum before unpacking, record what was written, and start it. Asks two separate questions: whether to launch it at login, and whether to notify you when an agent finishes a turn or waits for you. `--yes` answers both, each pair of flags answers one deterministically, and a non-interactive or `--json` run declines rather than acquiring a login item or writing provider hooks by accident. Accepting alerts turns them on for every supported session and for sessions created later. Refuses when no checksum is published for the asset |
 | `cdx tray uninstall [--json]` | Remove exactly what `install` recorded, and nothing else |
+| — | `cdx update` also moves an installed companion to the new release, and says so. A companion already running keeps executing the build it started with, so it reports that too rather than leaving you to wonder why the menu looks unchanged |
 | `cdx tray autostart [on\|off\|status] [--json]` | Start the companion at login, or stop doing so. Off until asked, idempotent, and the state is read back from the platform rather than from what CDX last intended |
 | `cdx tray events [--json]` | List agent alerts a running companion has not shown yet. The companion reads these instead of the spool file, so a Windows tray can collect events from CDX in WSL over the same interop it already uses |
 | `cdx tray ack <id>... [--json]` | Mark events as shown, idempotently |
 | `cdx tray heartbeat [--json]` | Record that a companion is alive. `cdx notify` publishes to the tray only while this is fresh, and delivers directly otherwise |
+| `cdx tray terminal [status\|set <app>\|clear] [--json]` | Choose which terminal a tray session row opens — `cdx tray terminal set iTerm`, `cdx tray terminal clear` to go back to the platform default. The value is an application name, never a command: anything that could be read as one is refused rather than sanitized. macOS opens it with `open -a`, Linux prefers it ahead of the emulators it already tries, and Windows honours `wt` because Windows Terminal is the one that documents how to be handed a command. A named terminal that is not installed falls back to the default rather than leaving the click doing nothing |
+| `cdx tray plugin [status\|enable <name>\|disable <name>\|run <action>] [--json]` | Turn a tray integration on or off, and list what is enabled. Opt-in in both directions and reversible; nothing enables one implicitly. `logics` is the only one that exists, and `status` says once when it is installed but not enabled. `run` is what the tray calls back with a card's action id and is not meant to be typed |
 | `cdx tray alerts [on\|off\|status] [--json]` | Silence agent alerts, or let them through again — the tray menu has the same switch. Muting stops the banner, not the record: events still reach a running companion, so the menu shows what you missed. It applies to the direct notification path too, so quitting the tray does not silently un-mute you. Distinct from the per-session `--notify` opt-in, which says which sessions may alert at all |
 | `cdx tray doctor [--json]` | Report companion, executable, version, running instance, autostart, and the two capabilities that fail silently — whether this desktop can draw a tray icon at all, and on Windows whether the Start Menu shortcut toasts depend on exists. Reads only; it never repairs |
 | `cdx --help` | Show usage |
@@ -563,6 +593,12 @@ The companion is a native binary distributed as a release asset, not part of the
 
 - **Where the checksum comes from.** Releases older than the one you are running are vouched for by `checksums/release-archives.json`, committed to the repository before those assets existed. Your own release is a special case: its tray assets are built after the tag, so no package built at tag time can carry their checksums. For that one version CDX reads the ledger the release publishes beside the assets — the publisher's own assertion over the same channel, which catches a truncated download or a wrong-architecture asset but does not defend against someone who can rewrite the release itself.
 - **The checksum is the vouching, not Apple or Microsoft.** The macOS bundle is signed with a *self-signed* certificate. That signature exists because Apple Silicon refuses to execute unsigned arm64 code at all — it is not a claim that Apple reviewed anything. What actually vouches for the asset is the SHA-256 published in `checksums/release-archives.json`, verified before a single byte is unpacked. An asset with no published checksum is refused rather than installed hopefully.
+- **Tray integrations are cards, not plugins.** `cdx tray plugin enable logics` adds one section to the menu: a blocked/ready summary and at most two rows — the first blocked document, because it is what stops work, and the highest-priority task in progress, because it is what to do instead. Clicking a row opens the Logics viewer focused on it.
+
+  There is deliberately no marketplace, no discovery, no installation from a URL, and no plugin auto-update. An adapter is a function in this repository, named in a registry CDX owns, so nothing unknown can run. Adapters produce data and never behaviour: a card is a summary, rows, and action ids from a fixed vocabulary, and the tray hands an id back to CDX rather than running anything itself. Adding a capability is a change to CDX, reviewed like any other.
+
+  A card is built from `logics-manager status --format json` and from nothing else, so nothing about your documents is read or stored. It is refreshed at most once a minute, or on demand from the menu — an integration never pays the tray's polling rate. If `logics-manager` is absent, slow, failing or in a directory that is not a Logics repository, the card is simply not there: an integration cannot degrade the session rows the tray exists to show.
+
 - **Install through `cdx tray install`, and no download link is offered.** This is a security property, not a convenience. A file fetched by CDX carries no macOS quarantine attribute and no Windows Mark-of-the-Web, so nothing puts Gatekeeper or SmartScreen between you and a companion you asked for. The same file fetched through a browser would carry both. That is why no direct download URL is published: it would be a worse path wearing the same clothes.
 - **Nothing is silently replaced.** An update downloads, verifies, and *proves the replacement starts* before the working companion is touched. A corrupt asset or one built for the wrong architecture costs an error message, not a tray you can no longer launch. An interrupted update is a named, recoverable state that `cdx tray doctor` reports.
 - **Uninstall removes only what install recorded**, from a record CDX wrote itself. A damaged record reads as absent rather than being guessed at, because that record drives deletion.

package/VERSION

@@ -0,0 +1 @@
+0.18.5

package/changelogs/CHANGELOGS_0_18_4.md

@@ -0,0 +1,78 @@
+# CDX Manager 0.18.4
+
+## Fixes
+
+### Agent alerts arrive when they happen
+
+An alert reached the tray on the next poll, so up to thirty seconds passed
+between a turn finishing and the banner appearing — where the direct path had
+been instant. The poll period is a cost budget, not a latency target, and it was
+the wrong one for the single event a user actively waits for.
+
+The companion now notices the spool changing between polls. No file watcher was
+needed: the event loop already wakes five times a second, so a `stat` costs
+microseconds at that rate. Measured at 0.57s from hook to consumption, including
+the polling in the measurement itself.
+
+Unchanged across the Windows-to-WSL boundary, and deliberately: a Windows
+process cannot watch a path inside the Linux filesystem, so the poll period
+remains the latency there.
+
+### The menu bar icon stays visible after the first poll
+
+`tray-icon`'s macOS `set_icon` clears the template flag unconditionally, so every
+refresh dropped the setting that lets macOS invert the glyph for the current
+theme. The icon started white and turned black about thirty seconds later, which
+on a dark menu bar means invisible.
+
+### `cdx update` brings the tray companion with it
+
+The companion is a separate artifact on a separate release, so it drifted and
+had to be reinstalled by hand. `cdx update` now moves it too, through the staged
+path that verifies the asset and proves the replacement starts before the
+working one is touched — and never fails the update if it cannot: the previous
+companion stays installed and the reason is reported.
+
+`cdx tray doctor` names the state now, rather than printing two version numbers
+and leaving the comparison to you: `aligned` or `drifted`.
+
+## Features
+
+### The menu is readable at a dozen accounts
+
+Rows are selectable rather than informational — macOS renders disabled items
+grey, so a dozen arrived as a wall of grey text — and clicking one opens a
+terminal on that session. The list is sorted by urgency, most constrained first;
+it previously arrived in storage order, so an account at 1% could sit tenth
+while the icon showed critical.
+
+Sessions are grouped under their provider instead of repeating it on every row,
+and each carries a gauge. On macOS the rows are drawn: name, a gauge coloured by
+severity, and the figure aligned on a fixed column — a native menu font is
+proportional, so text alone cannot align. Windows and Linux keep the text rows,
+which say everything the drawing does.
+
+Times are distances, not stamps: `↻ in 6d 23h` rather than `↻ Aug 18 03:23`, and
+a stale row says how stale. The wording is `cdx status`'s own.
+
+### A switch to silence agent alerts
+
+In the tray menu and as `cdx tray alerts on|off|status`. Muting stops the
+banner, not the record — events keep reaching a running companion, so the menu
+shows what you missed — and it applies to the direct path too, so quitting the
+tray does not silently un-mute you.
+
+### `cdx tray install` starts what it installed
+
+And asks whether to launch it at login. `--yes` answers without a prompt,
+`--no-autostart` declines, and a non-interactive run declines too: a script must
+not acquire a startup entry by running an install.
+
+## Validation
+
+- `npm run lint`, `npm test` — 790 Python tests
+- `cargo test` — 52 Rust tests; `cargo clippy` clean with zero warnings on three
+  targets
+- 143 Python tests on native Windows, plus the Windows and Linux companions
+  exercised on a managed host: grouped menu, gauges, alert switch, spool path,
+  and the unsupported-desktop path still refusing to draw

package/changelogs/CHANGELOGS_0_18_5.md

@@ -0,0 +1,147 @@
+# CDX Manager 0.18.5
+
+## Fixes
+
+### An npm install knew which version it was
+
+`cdx --version` reported `0.0.0` for every install done through npm, and the
+update banner never went away: nothing is newer than a release that believes it
+is version zero, so `cdx update` ran, succeeded, and changed nothing that could
+be seen.
+
+The version is resolved from the `VERSION` file, then from Python distribution
+metadata. An npm install has neither — the file was not in the published package
+and npm creates no Python metadata — so both lookups missed. `VERSION` ships
+now, and `package.json` becomes the last resort below it, because an npm tarball
+carries that file by construction and cannot lose it the way a file list can.
+
+Installs through `install.sh` were never affected: they unpack the git archive,
+which always contained `VERSION`.
+
+### The tray badge cleared when you read it
+
+The count beside the icon could be raised and never lowered. `tray-icon`'s macOS
+`set_title` ignores a `None` — it sets a title when given one and does nothing
+otherwise — so every attempt to clear the marker was silently dropped. This
+predates the unread work: the 45-second expiry it replaced cleared the same way,
+so it never cleared either. Nobody noticed, because a marker that outstays its
+welcome looks exactly like one that is still true.
+
+### The tray says which CDX it actually reached
+
+A WSL user could see `cdx --version` report the current release in their
+terminal while the companion insisted CDX was too old to have `cdx tray`. Both
+were right: the companion runs `wsl.exe -- cdx`, which is not a login shell, so
+it resolves the system PATH and can find an older CDX that the user's own shell
+never sees. The message names the command that answered now, and points at
+`CDX_TRAY_CDX`, which is the setting that fixes it.
+
+### The gauge is legible on Windows and Linux
+
+The empty part of the capacity bar was a dither pattern, which on a dark Windows
+menu reads as corrupted text rather than as an empty gauge. It is a thin rule
+now, in the same Unicode block as the filled part so the column still aligns in
+the proportional font a native menu uses.
+
+## Features
+
+### The tray menu is ordered by remaining capacity, and by nothing else
+
+Sessions were grouped under a provider heading, which reordered the list it was
+meant to organise: a group took the rank of its most constrained session, so a
+healthy account could sit above the one that made the icon turn. The headings
+are gone and each row names its provider.
+
+That also removed an older defect underneath. A click carried a position into
+the snapshot, which only worked while the order was stable — and ordering by
+capacity makes it change under you. A row now carries the session's name, so a
+poll landing between the draw and the click can no longer open the wrong one.
+
+### Both limit windows are visible at once
+
+Both providers meter a five-hour window and a weekly one, and the tray showed
+whichever was worse. A week almost spent was invisible behind a five-hour window
+that had just reset, and the figure silently changed meaning between two polls.
+
+Each window now has its own line, its own bar and its own name. On macOS the row
+also says how old its figure is and when the limit resets — the two facts you
+need before trusting a percentage, which the text rows had all along and the
+drawn one had never been given.
+
+### Every session row opens into its own actions
+
+A row that launched on click had space for exactly one meaning. Each is a
+submenu now: **Open session**, which is the launch it always did, and **Launch
+settings (next launch)**, a view of `cdx config <name>`. The wording is the
+promise — CDX stores those settings for the next start, and no provider accepts
+them for an assistant already running, so the tray never implies otherwise.
+
+### Agent alerts say what happened, and open the session that sent them
+
+Both providers are now subscribed to the same two hooks, `Stop` and
+`PermissionRequest`, so a permission request is reported immediately and by
+tool name rather than through a delayed generic notification. The duplicate that
+combination used to produce is filtered where the duplication is.
+
+Alerts reach the tray as fields rather than as a sentence, so the menu can name
+the session, the project and the tool — and clicking one opens the session it
+came from. The tool's arguments, the transcript path and provider session
+identifiers are never part of that.
+
+A turn that dies on a provider error also raises an alert now, where it used to
+be silent: a rate limit, an overload, an authentication or billing problem. They
+are marked apart from completions and say whether the failure usually clears on
+its own or needs you. Claude publishes this; Codex documents no equivalent, so a
+Codex turn killed by its provider stays silent.
+
+### The alert badge and the alert list are the same thing
+
+The marker beside the icon expired on a timer while the menu kept a list that
+never cleared, so the two could not agree and neither meant anything precise.
+There is one unread list now: the badge counts it, the menu shows it, and
+opening the menu is what marks it read. An alert that arrives while the menu is
+open stays unread, because nobody has seen it.
+
+### `cdx update` replaces a running companion
+
+It used to move the files and tell you to quit the tray from its menu and start
+it again. It now asks the running companion to stop, replaces it, and starts the
+replacement — verifying that it actually came up rather than trusting that it
+was launched. If the replacement will not start, the companion that was working
+is put back and restarted.
+
+A companion that does not stop within ten seconds is left alone and reported,
+never killed: an open menu blocks it on Windows, and a tray you are reading is
+not a process to terminate over a version number.
+
+### Installing the tray asks about alerts, and means it for later sessions
+
+`cdx tray install` asks two separate questions — start at login, and notify you
+when an agent finishes or waits for you. Each has its own flags, an explicit
+flag never triggers a prompt, and a piped or `--json` run declines rather than
+deciding for you. Accepting alerts turns them on for every supported session and
+for sessions created afterwards; on Codex, the approval it will ask for at the
+next launch is stated at install time.
+
+### A Logics card in the tray, off unless you ask
+
+`cdx tray plugin enable logics` adds one section to the menu: how much is
+blocked and in progress, the first blocked document, and the highest-priority
+task in progress. Clicking a row opens the Logics viewer focused on it.
+
+There is deliberately no marketplace, no discovery and no plugin auto-update. An
+adapter is a function in this repository, named in a registry CDX owns, so
+nothing unknown can run. It produces data and never behaviour: a card is a
+summary, rows, and action ids from a fixed vocabulary. The card is built from
+`logics-manager status --format json` and nothing else, refreshed at most once a
+minute, and simply absent when Logics is unavailable.
+
+### Choose the terminal a session row opens
+
+`cdx tray terminal set iTerm` — or Ghostty, WezTerm, kitty, `wt`. What is stored
+is an application name, never a command: anything that could be read as one is
+refused rather than sanitized, and the rule is applied when the value is read as
+well as when it is written. macOS opens it with `open -a`, Linux prefers it
+ahead of the emulators it already tries, and Windows honours `wt`, which is the
+one that documents how to be handed a command. A terminal that is not installed
+falls back to the platform default rather than leaving the click doing nothing.

package/checksums/release-archives.json

@@ -224,6 +224,28 @@
         "x86_64-pc-windows-msvc": "7a40ffc6a1908e0cda5e484b50ab7c11b6cb01f4c370905eefe23e40a8afb7bd",
         "x86_64-unknown-linux-musl": "2f4b95c661cdb65bf58c2aa0d2c7a45e03bb5a8ec3d20404c688887dba33afe4"
       }
+    },
+    "v0.18.3": {
+      "github_tarball_sha256": "0099b87967b2a2f4f026c97888d2017473c0b58aa974b56dd35320231e67e248",
+      "github_zip_sha256": "f6f15a9f91a85696d4f865cf192bfb4b076be92937105df57329fbfc73147631",
+      "tray_assets": {
+        "aarch64-apple-darwin": "5bbd0d9764c0feae3fc60c24951fc8202f56c8cd69574440277a4b372ae93da5",
+        "aarch64-unknown-linux-musl": "c937af7a08701fbc102ff3d7e0458e488a57001e65f20acab7809221a0395310",
+        "x86_64-apple-darwin": "036dde97929ed4c3a5e0b29b4e8332caede15c124e907c573557d888439af748",
+        "x86_64-pc-windows-msvc": "e50250d21d11e6986a310a00d4f3ab5b1a13d2960684750c569926d5bda923f9",
+        "x86_64-unknown-linux-musl": "edbdb02b7e9df5709b5b9512233e2b25b51f7652bd1b78c68edb85dbfa65d708"
+      }
+    },
+    "v0.18.4": {
+      "github_tarball_sha256": "9709de784596783587a8fd5fcc75da32c43a0a19dd84dd2633e958bf38bd134d",
+      "github_zip_sha256": "a01abf6eac2627427eab2c1d3c3363b24ac93c6aadf049bdc6fd60987a6086ce",
+      "tray_assets": {
+        "aarch64-apple-darwin": "d8d11e6365f14cc72e7e433da75c6d577bdf0a98eac38747ff9bba98788e1e98",
+        "aarch64-unknown-linux-musl": "ff1c007f06262f510346a90458c9e26b4972e741b4b483da5bbebac83e6083b0",
+        "x86_64-apple-darwin": "cb46a11a1a0ffa0426f1afeb2a91cfd67c837a37b0afcc6b222473c02f20a817",
+        "x86_64-pc-windows-msvc": "cc33c0f5a53472c6c1c72f458f33052abc09b6fe4ff5dfb5edae497c234bb2d0",
+        "x86_64-unknown-linux-musl": "d8fb9958112329487bd91be7f7505f18f886676f4309e30aa3877340e42c6c15"
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",
@@ -24,6 +24,7 @@
     "node": ">=18"
   },
   "files": [
+    "VERSION",
     "bin",
     "!bin/__pycache__",
     "!bin/**/*.pyc",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.18.3"
+version = "0.18.5"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/agent_notify.py

@@ -30,6 +30,29 @@ PREVIEW_ENV = "CDX_NOTIFY_PREVIEW"
 HOOK_ARG = "notify"
 
 _WAITING_EVENTS = {"notification", "permissionrequest"}
+# The Notification states that mean the agent is waiting for its user.
+#
+# Claude's Notification hook is a broad one: `permission_prompt` fires for the
+# same tool call `PermissionRequest` already reports, exactly and immediately,
+# so subscribing to both once produced two alerts for one request. Filtering
+# here rather than unsubscribing keeps the idle states, which nothing else
+# reports at all — an agent waiting on an answer would otherwise go silent.
+_WAITING_NOTIFICATIONS = {"idle_prompt", "agent_needs_input"}
+# Hook events that decide something. Anything this process writes to stdout on
+# one of these is read by Claude Code as an allow or a deny for the tool call,
+# so `cdx notify` has to stay silent on them whatever happens.
+_DECIDING_EVENTS = {"permissionrequest"}
+# A turn that ended on a provider error rather than on an answer.
+#
+# Claude Code publishes this; Codex documents no equivalent, so this is a
+# Claude-only alert and the documentation says so rather than implying parity.
+_FAILURE_EVENTS = {"stopfailure"}
+# Error classes that usually clear on their own. The distinction is the whole
+# point of the alert: an overloaded model and a billing error both stop the
+# turn, and reacting to them the same way is what trains someone to ignore
+# both. Anything unrecognised is treated as needing attention — a failure this
+# build has never seen is not one to reassure the user about.
+_TRANSIENT_ERRORS = {"rate_limit", "overloaded", "server_error", "max_output_tokens"}
 _PREVIEW_LIMIT = 180
 _TOOL_NAME_LIMIT = 80
 
@@ -69,6 +92,38 @@ def read_hook_payload(args, stdin_text=None):
     return {}
 
 
+def hook_event(payload):
+    """The provider's event name, in one spelling.
+
+    Both providers publish the same names now, but they have each spelled them
+    differently over time and Codex's older `notify` used `type`. Normalising in
+    one place keeps every caller reading the same value.
+    """
+    raw = payload.get("hook_event_name") or payload.get("eventName") or payload.get("type") or ""
+    return str(raw).lower().replace("_", "").replace("-", "")
+
+
+def is_deciding_event(payload):
+    """Whether this hook's output would be read as a permission decision."""
+    return hook_event(payload) in _DECIDING_EVENTS
+
+
+def _is_reportable(payload, event):
+    """Whether this event is one the user should hear about at all.
+
+    A Notification that is not a waiting state is either something another hook
+    reports exactly — `permission_prompt` duplicates PermissionRequest — or an
+    internal state the user has no action to take on.
+    """
+    if event != "notification":
+        return True
+    kind = str(payload.get("notification_type") or "").lower()
+    # An older Claude sent no type at all. Reporting it is the safer default: a
+    # duplicate is a nuisance, a missed "the agent is waiting for you" is the
+    # failure this feature exists to prevent.
+    return not kind or kind in _WAITING_NOTIFICATIONS
+
+
 def compose_notification(payload, env=None, cwd=None):
     """Title and message for this event, or None if we should stay quiet."""
     env = os.environ if env is None else env
@@ -79,18 +134,124 @@ def compose_notification(payload, env=None, cwd=None):
     session = env.get(SESSION_ENV)
     if not session:
         return None
+    event = hook_event(payload)
+    if not _is_reportable(payload, event):
+        return None
     directory = payload.get("cwd") or payload.get("workspace") or cwd or os.getcwd()
-    event = str(payload.get("hook_event_name") or payload.get("eventName") or payload.get("type") or "").lower()
-    event = event.replace("_", "").replace("-", "")
+    where = os.path.basename(str(directory).rstrip("/\\")) or directory
+    if event in _FAILURE_EVENTS:
+        # A different mark, because the word alone is not enough: a glance at a
+        # notification centre reads the symbol first, and a failed turn that
+        # carries the completion tick is a turn the user believes finished.
+        state = _failure_state(payload)
+        detail = _failure_detail(payload, env)
+        return f"✕ {session}", f"{where} · {state}" + (f" — {detail}" if detail else "")
     state = "needs your attention" if event in _WAITING_EVENTS else "turn complete"
     tool_name = _notification_text(payload.get("tool_name"), _TOOL_NAME_LIMIT)
     if event == "permissionrequest" and tool_name:
         state += f" ({tool_name})"
-    where = os.path.basename(str(directory).rstrip("/\\")) or directory
     preview = _notification_preview(payload, event, env)
     return f"✓ {session}", f"{where} · {state}" + (f" — {preview}" if preview else "")
 
 
+def error_class(payload):
+    """The provider's error class, normalised. Empty when it sent none."""
+    return _notification_text(payload.get("error_type"), _TOOL_NAME_LIMIT).lower().replace(" ", "_")
+
+
+def _failure_state(payload):
+    """What a failed turn says it is, in words that suggest what to do.
+
+    The class itself is included rather than translated: `rate_limit` and
+    `billing_error` mean different things to whoever reads them, and inventing
+    friendlier wording for a closed vocabulary loses the part that identifies
+    the problem.
+    """
+    kind = error_class(payload)
+    if not kind:
+        return "turn failed"
+    if kind in _TRANSIENT_ERRORS:
+        return f"turn interrupted ({kind})"
+    return f"turn failed ({kind}) — needs you"
+
+
+def _failure_detail(payload, env):
+    """The provider's own message, under the same opt-in as any other free text."""
+    if env.get(PREVIEW_ENV) != "1":
+        return ""
+    return _notification_text(payload.get("error_message"), _PREVIEW_LIMIT)
+
+
+def structured_details(payload, env=None, cwd=None):
+    """The event as fields, for a tray that should not parse a sentence.
+
+    What is deliberately absent is the point of this function. `tool_input`
+    carries command lines, paths and patch bodies; `transcript_path` points at
+    the whole conversation; `session_id` and `turn_id` identify a provider
+    session rather than a cdx one. None of them reach the spool. What crosses is
+    what cdx already knew (its own session name, the project directory) plus the
+    closed-vocabulary metadata the providers document: the event, the tool name,
+    the model, the permission category and the stop reason.
+    """
+    env = os.environ if env is None else env
+    event = hook_event(payload)
+    directory = payload.get("cwd") or payload.get("workspace") or cwd or os.getcwd()
+    details = {
+        "session": env.get(SESSION_ENV) or "",
+        "project": os.path.basename(str(directory).rstrip("/\\")) or str(directory),
+        "event": event,
+    }
+    for key, source, limit in (
+        ("tool", "tool_name", _TOOL_NAME_LIMIT),
+        ("error_type", "error_type", _TOOL_NAME_LIMIT),
+        ("model", "model", _TOOL_NAME_LIMIT),
+        ("category", "permission_category", _TOOL_NAME_LIMIT),
+        ("stop_reason", "stop_reason", _TOOL_NAME_LIMIT),
+    ):
+        value = _notification_text(payload.get(source), limit)
+        if value:
+            details[key] = value
+    preview = _notification_preview(payload, event, env)
+    if preview:
+        details["preview"] = preview
+    reason = _permission_reason(payload, event, env)
+    if reason:
+        details["reason"] = reason
+    failure = _failure_detail(payload, env) if event in _FAILURE_EVENTS else ""
+    if failure:
+        details["preview"] = failure
+    return details
+
+
+def alert_kind(payload):
+    """Which of the three shapes this event is, for the tray's marker.
+
+    A failure is its own kind rather than borrowing `attention`: they call for
+    different reactions, and a companion that predates this shows the neutral
+    marker with a message that still says the turn failed.
+    """
+    event = hook_event(payload)
+    if event in _FAILURE_EVENTS:
+        return "failed"
+    return "attention" if event in _WAITING_EVENTS else "complete"
+
+
+def _permission_reason(payload, event, env):
+    """The provider's own words for what it is asking permission to do.
+
+    The one field taken out of `tool_input`, and only this one: it is prose the
+    provider wrote for a human, where everything else in there is the command
+    itself. It follows the response-preview preference like any other free text,
+    because prose a provider composed can quote whatever it was asked to do.
+    """
+    if event != "permissionrequest" or env.get(PREVIEW_ENV) != "1":
+        return ""
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return ""
+    return _notification_text(tool_input.get("description"), _PREVIEW_LIMIT)
+
+
 def _notification_preview(payload, event, env):
     if event != "stop" or env.get(PREVIEW_ENV) != "1":
         return ""
@@ -120,6 +281,11 @@ def handle_notify(rest, ctx):
         if reader is not None and not ctx.get("stdin_is_tty"):
             stdin_text = reader.read()
         payload = read_hook_payload(rest, stdin_text)
+        # From here on nothing may be written to stdout. On a PermissionRequest
+        # Claude Code reads this process's stdout as the decision for the tool
+        # call being asked about, so a stray line would allow or deny it. The
+        # notification paths below print nothing; this is the statement of why
+        # they must not start.
         composed = compose_notification(payload, env, ctx.get("cwd"))
         if composed:
             # Muted stops the banner, not the record: the event still reaches a
@@ -128,14 +294,14 @@ def handle_notify(rest, ctx):
             base_dir = (ctx.get("service") or {}).get("base_dir")
             muted = bool(base_dir) and not alerts_enabled(base_dir)
             if muted:
-                _published_to_tray(ctx, composed, payload)
+                _published_to_tray(ctx, composed, payload, env, ctx.get("cwd"))
                 return 0
             # A live tray becomes the sole owner of this alert, so the user sees
             # one notification rather than two. Publication happens below the
             # composition boundary on purpose: the tray receives the same
             # already-sanitized title and message the direct path would send,
             # and cannot be handed anything the privacy rules removed.
-            if not _published_to_tray(ctx, composed, payload):
+            if not _published_to_tray(ctx, composed, payload, env, ctx.get("cwd")):
                 send_desktop_notification(*composed, spawn_sync=ctx.get("spawn_sync"), env=env)
     except Exception:  # noqa: BLE001 - deliberate: the caller is an agent turn
         pass
@@ -330,7 +496,15 @@ def _apply_hooks(path, enabled, command):
     hooks = document.get("hooks")
     hooks = hooks if isinstance(hooks, dict) else {}
     before = json.dumps(hooks, sort_keys=True)
-    for event in ("Stop", "Notification"):
+    # PermissionRequest is what Codex has always used and Claude Code now
+    # publishes too: it fires immediately and names the tool, where Notification
+    # is delayed and does not. Notification stays subscribed for the waiting
+    # states nothing else reports; the duplicate it used to cause is filtered in
+    # `cdx notify` rather than avoided by unsubscribing.
+    # StopFailure is Claude-only: Codex documents no equivalent, so a turn its
+    # provider kills stays silent there and the documentation says so rather
+    # than implying a parity that does not exist.
+    for event in ("Stop", "StopFailure", "Notification", "PermissionRequest"):
         # Rebuilt from whatever is there minus our own entry, so user-authored
         # hooks on the same event survive both installing and removing.
         entries = [entry for entry in hooks.get(event, []) if not _is_ours(entry)]
@@ -387,22 +561,28 @@ def _write_json(path, document):
     return True
 
 
-def _published_to_tray(ctx, composed, payload):
+def _published_to_tray(ctx, composed, payload, env=None, cwd=None):
     """Hand the alert to a live tray, or say we did not.
 
     False is the safe answer to everything: no base directory, no heartbeat, a
     stale one, a schema mismatch, or an unwritable spool all mean the direct
     path still runs. The only way to lose a notification here would be to
     return True without having written it.
+
+    The rendered title and message go too, unchanged. A companion older than the
+    structured fields reads exactly what it read before, and a newer one that is
+    handed a malformed event still has a sentence to show.
     """
     try:
         base_dir = (ctx.get("service") or {}).get("base_dir")
         if not base_dir:
             return False
-        event = str(
-            payload.get("hook_event_name") or payload.get("eventName") or payload.get("type") or ""
-        ).lower().replace("_", "").replace("-", "")
-        kind = "attention" if event in _WAITING_EVENTS else "complete"
-        return publish(base_dir, composed[0], composed[1], kind=kind)
+        return publish(
+            base_dir,
+            composed[0],
+            composed[1],
+            kind=alert_kind(payload),
+            details=structured_details(payload, env, cwd),
+        )
     except Exception:  # noqa: BLE001 - the caller is an agent turn
         return False