cdx-manager 0.15.1 → 0.16.0

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.15.1-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.16.0-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.
 
@@ -70,7 +70,8 @@ The reason `cdx` exists: knowing, across every account you own, which one you ca
 
 - **Usage at a glance.** `cdx status` shows token usage, 5-hour window quota, weekly quota, last-updated timestamps, priority guidance, and the last launched session in one aligned table.
 - **Pick for me.** `cdx next` selects the best available assistant from your pinned priorities and the live quota picture, shows the reason, and prints the exact command to run.
-- **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately. `cdx notify` covers reset times and scheduled wake-ups.
+- **Agent notifications.** When a session finishes a turn or blocks waiting for you, cdx raises a desktop notification naming the session and the repository — so you can run several in parallel without watching any of them. Opt in per session with `cdx set <name> --notify on`.
+- **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately.
 - **Passive status resolution.** Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
 - **Banked reset visibility.** Eligible Codex accounts show the number of manually redeemable bonus resets in `cdx status` and expose reset details in JSON output.
 
@@ -342,7 +343,43 @@ cdx disk profiles --candidates
 
 ### Next-Ready Notifications
 
-Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. It is shorthand for `cdx notify --schedule --next-ready`: cdx picks the next known reset, registers a native OS notification, and exits immediately. If no future reset is known, it exits successfully and explains that no notification was scheduled.
+### Agent notifications
+
+When a session's agent finishes a turn, or stops to wait for you, cdx raises a
+desktop notification naming the session and the repository:
+
+```text
+✓ work1     logics-manager · waiting for you
+✓ codex-a   cdx-manager · finished
+```
+
+Off until you ask for it, per session:
+
+```bash
+cdx set work1 --notify on      # turn it on for one session
+cdx set --all --notify on      # turn it on everywhere
+cdx set work1 --notify off     # and back off; cdx removes what it installed
+```
+
+Turning it on records the setting. The wiring happens at that session's **next
+launch**: cdx writes the hook into the session's own home and says so once.
+Claude Code honours it straight away. Codex only runs hooks that come from an
+installed plugin, so cdx generates one per session and installs it — and Codex
+asks you to approve it once, which cdx leaves to you rather than writing that
+trust on your behalf.
+
+It is off by default because turning it on writes into the provider's own
+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.
+
+Per platform: macOS uses `osascript`, Linux `notify-send`, Windows a toast, and
+WSL reaches the Windows notification centre through interop. On a host with no
+way to deliver one — a headless or SSH Linux session, or WSL with interop
+disabled — cdx installs no hooks at all rather than asking you to approve
+something that could show you nothing. Headless `cdx run` never notifies: its
+caller already learns of completion from the return value.
+
+Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. cdx picks the next known reset, registers a native OS notification, and exits immediately. If no future reset is known, it exits successfully and explains that no notification was scheduled.
 
 ```bash
 cdx ready
@@ -446,8 +483,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx update all [--yes] [--json]` | Check installed providers, RTK, and Ponytail across Codex profiles; show the plan and ask once before applying safe native/Homebrew updates and missing RTK/Ponytail setup |
 | `cdx ready [--refresh] [--json]` | Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately |
-| `cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait for a session reset time or schedule an OS wake-up notification when due |
-| `cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait until the recommended session is usable, or schedule the next known reset notification |
+| `cdx notify` | Hook target: raises the desktop notification when a session's agent finishes a turn or waits for you. Called by the provider, not by you |
 | `cdx next [--json] [--refresh]` | Select the best next assistant using the same priority logic as `cdx status` |
 | `cdx select --provider PROVIDER [--min-reasoning-effort minimal\|low\|medium\|high\|xhigh] [--min-power minimal\|low\|medium\|high\|xhigh] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
 | `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit, `--prompt-file -` reads the prompt from stdin |
@@ -499,7 +535,6 @@ Commands with machine-readable output:
 - `cdx view --json`
 - `cdx update --json`
 - `cdx ready --json`
-- `cdx notify ... --json`
 - `cdx select ... --json`
 - `cdx run ... --json`
 

package/changelogs/CHANGELOGS_0_16_0.md

@@ -0,0 +1,97 @@
+# CDX Manager 0.16.0
+
+> cdx now tells you when one of its sessions finishes or needs you, which is
+> the one thing it could not do in the situation it was built for: several
+> assistants running in parallel across different repositories. Getting there
+> meant retiring the old `cdx notify` and reserving the name for this.
+
+## Breaking
+
+### `cdx notify` means something else
+
+`cdx notify <name> --at-reset` and `cdx notify --next-ready` are gone. Those
+answered "when does my quota come back", which `cdx status` already answers,
+and in practice the only form anyone typed was `cdx ready`.
+
+`cdx ready` is unchanged — same behaviour, same output, same flags. If you
+scripted the retired flags, `cdx ready --json` is the replacement; there is no
+equivalent for waiting on one named session's reset.
+
+`cdx notify` is now the target a provider hook calls. You do not run it
+yourself.
+
+## Features
+
+### Notifications when a session finishes or waits for you
+
+```text
+✓ work1     logics-manager · waiting for you
+✓ codex-a   cdx-manager · finished
+```
+
+The notification names the session and the repository, because the case this
+exists for is several of them at once — a notification that cannot tell you
+which one is not worth raising. Only cdx knows the session name, which is why
+this lives here rather than in a hook you write by hand.
+
+Off until you ask for it:
+
+```bash
+cdx set work1 --notify on      # one session
+cdx set --all --notify on      # all of them
+```
+
+The setting is recorded straight away; the wiring happens at that session's
+next launch, into the home directory cdx already owns, and cdx says so once.
+Turning it back off removes what cdx installed and leaves any hooks you wrote
+yourself alone.
+
+It is opt-in rather than on by default because enabling it writes into the
+provider's own configuration and, on Codex, puts an approval prompt in front of
+you — not something to do unrequested to sessions you already own.
+
+### Codex goes through a generated plugin
+
+Codex does not read hooks from a file. Not at its home root, not under a
+`hooks/` directory, not from a project `.codex/` — all three were tried and
+none is ever loaded. It runs only hooks that come from an installed plugin, so
+cdx generates one per session and installs it with `codex plugin marketplace
+add`.
+
+The generated plugin lives outside `CODEX_HOME` on purpose. Rooted inside it,
+the marketplace installs without an error and reports `installed, enabled`, and
+then never runs a thing: Codex registers it pointing at the source directory
+rather than the cache copy it executes from. Everything looks right and nothing
+happens.
+
+Codex also refuses to run a hook it has not been told to trust, so it asks you
+once per session. cdx does not answer that for you.
+
+### Delivery on every platform, and silence where there is none
+
+macOS uses `osascript`, Linux `notify-send`, native Windows a toast, and WSL
+reaches the Windows notification centre through interop rather than being
+treated as plain Linux — which is what it was before, and why it delivered
+nothing at all there.
+
+On a host with no way to show a notification — a headless or SSH Linux
+session, or WSL with interop disabled — cdx installs no hooks. Approving a
+hook that could never show you anything is a cost with no return. A host that
+gains a channel later is provisioned on its next launch.
+
+Headless `cdx run` never notifies, so a script issuing fifty runs stays quiet.
+Its caller already learns of completion from the return value.
+
+## Fixes
+
+### The Windows notification no longer blocks
+
+Windows notifications were a `MessageBox` spawned with no timeout. As an
+occasional quota alert that was survivable. As a hook firing on every agent
+turn it would have held the turn open until someone dismissed the dialog, and
+a window stealing focus every turn is worse than no notification at all. It is
+now a toast, which needs no dismissing.
+
+Claude Code honours the hooks it finds immediately. Codex is the one that
+gates them behind trust, so only Codex asks — cdx passes no bypass flag, the
+guard is there on purpose.

package/checksums/release-archives.json

@@ -176,6 +176,10 @@
     "v0.15.0": {
       "github_tarball_sha256": "93d0a7305a5235f20e89a3e2a404029546926437952ee61d43a1f69c3ae98e4e",
       "github_zip_sha256": "23e4e42fb746f4af5fa407f853e979ffce91e147dbb623c250e276fdcaa9638a"
+    },
+    "v0.15.1": {
+      "github_tarball_sha256": "1dc7ea87600844e4853ab12c9f123dc67548ae904f511fea9a58ddf7b3eacfef",
+      "github_zip_sha256": "7ad41c63adffdd1ef12d02a72c86fb1b6a64cbcddd9970b0741ba5516f241707"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

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

package/src/agent_notify.py

@@ -0,0 +1,324 @@
+"""Agent-event notifications: the hook target, and the per-session provisioning.
+
+`cdx notify` is what a provider hook calls when an agent turn ends or blocks
+waiting for input. It exists because the notification has to name *which* cdx
+session, in *which* repository — the case the feature is for is several sessions
+running in parallel — and only cdx knows the session name.
+
+Provisioning writes the hook into the session's own home, which cdx already
+owns because it sets HOME/CODEX_HOME per session at launch.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+
+from .notify import notification_channel, send_desktop_notification
+
+# Set on the provider process at launch; the hook runs as its child and inherits both.
+SESSION_ENV = "CDX_SESSION_NAME"
+ENABLED_ENV = "CDX_NOTIFY"
+
+# Our entries are recognised by the command they run, not by a marker key of our
+# own: both providers validate this file against their own schema, and an extra
+# key they do not know is a rejection risk for no gain.
+HOOK_ARG = "notify"
+
+_WAITING_EVENTS = {"notification", "permissionrequest", "userpromptsubmit"}
+
+
+def resolve_hook_command(env=None):
+    """Absolute path to cdx, not the bare name.
+
+    Codex spawns the hook without a shell, and a Windows npm install ships a
+    `.cmd` shim rather than an executable called `cdx`, so the bare name does
+    not resolve there. pipx and uv installs can likewise leave cdx off the PATH
+    the provider inherits.
+    """
+    env = env or os.environ
+    return env.get("CDX_BIN") or shutil.which("cdx", path=env.get("PATH")) or "cdx"
+
+
+def read_hook_payload(args, stdin_text=None):
+    """Accept the payload however the provider hands it over.
+
+    Claude Code and current Codex hooks write JSON to stdin. Codex's older
+    `notify` key — which it now calls `legacy_notify` — passes it as an argv.
+    Anything unparseable is an empty payload, never an error: a hook that fails
+    loudly turns a missing notification into a broken agent turn.
+    """
+    for candidate in ([stdin_text] if stdin_text else []) + list(args or []):
+        try:
+            payload = json.loads(candidate)
+        except (TypeError, ValueError):
+            continue
+        if isinstance(payload, dict):
+            return payload
+    return {}
+
+
+def compose_notification(payload, env=None, cwd=None):
+    """Title and message for this event, or None if we should stay quiet."""
+    env = env or os.environ
+    if env.get(ENABLED_ENV) == "0":
+        # Headless runs share the session's home, so they read the same hooks.
+        # Their caller already learns of completion from the return value.
+        return None
+    session = env.get(SESSION_ENV)
+    if not session:
+        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()
+    state = "waiting for you" if event.replace("_", "") in _WAITING_EVENTS else "finished"
+    where = os.path.basename(str(directory).rstrip("/\\")) or directory
+    return f"✓ {session}", f"{where} · {state}"
+
+
+def handle_notify(rest, ctx):
+    """Hook target. Never fails: a broken notification is not a broken turn."""
+    try:
+        import sys
+        stdin_text = None
+        # "stdin" in ctx is the {"isTTY": ...} descriptor, not a stream.
+        reader = ctx.get("prompt_stdin") or sys.stdin
+        if reader is not None and not ctx.get("stdin_is_tty"):
+            stdin_text = reader.read()
+        env = ctx.get("env") or os.environ
+        composed = compose_notification(read_hook_payload(rest, stdin_text), env, ctx.get("cwd"))
+        if composed:
+            send_desktop_notification(*composed, spawn_sync=ctx.get("spawn_sync"), env=env)
+    except Exception:  # noqa: BLE001 - deliberate: the caller is an agent turn
+        pass
+    return 0
+
+
+def launch_notify_env(session, enabled, env=None):
+    """Env the provider is launched with, carrying who we are and whether to notify."""
+    values = {SESSION_ENV: session["name"]}
+    if not enabled:
+        values[ENABLED_ENV] = "0"
+    return values
+
+
+def notifications_enabled(session):
+    """Off unless this session explicitly turned it on.
+
+    Opt-in rather than on-by-default: provisioning writes into the provider's
+    own configuration and, on Codex, asks the user to approve a hook. Doing
+    that to every session someone already owns, without being asked, is not a
+    default worth having.
+    """
+    launch = session.get("launch") or {}
+    return launch.get("notify") is True
+
+
+def provision(auth_home, provider, enabled, env=None, spawn_sync=None, base_dir=None):
+    """Install or remove cdx's notification hooks in this session's own home.
+
+    Idempotent, so an existing session picks the hooks up on its next launch and
+    repeated launches change nothing. Returns True when they were newly
+    installed, so the caller can say so once.
+
+    The two providers need different mechanisms, which is not a stylistic
+    choice: Claude Code reads hooks straight out of `settings.json`, while Codex
+    reads them only from an installed plugin — a free-standing hooks file
+    anywhere under `CODEX_HOME` is never looked at.
+    """
+    env = env or os.environ
+    if enabled and not notification_channel(env):
+        # Nothing could be delivered on this host, so installing a hook would only
+        # buy the user an approval prompt for a feature that shows nothing.
+        enabled = False
+    command = resolve_hook_command(env)
+    if provider == "claude":
+        return _apply_hooks(hook_config_path(auth_home, provider), enabled, command)
+    if provider == "codex":
+        return _provision_codex_plugin(auth_home, enabled, command, env, spawn_sync, base_dir)
+    return False
+
+
+def hook_config_path(auth_home, provider, base_dir=None):
+    if provider == "claude":
+        return os.path.join(auth_home, ".claude", "settings.json")
+    if provider == "codex":
+        return os.path.join(codex_plugin_root(auth_home, base_dir), "hooks", "cdx-hooks.json")
+    return None
+
+
+def codex_plugin_root(auth_home, base_dir=None):
+    """Where the generated Codex plugin lives — deliberately outside CODEX_HOME.
+
+    A marketplace rooted inside Codex's own home installs without complaint and
+    then never runs: Codex registers it pointing straight at the source
+    directory instead of taking the cache copy it executes from. Moving the same
+    plugin one directory out is the whole difference between working and
+    silently doing nothing.
+    """
+    if base_dir:
+        return os.path.join(base_dir, "state", "codex-plugins", os.path.basename(auth_home))
+    # Without a base directory, sit beside the home rather than guessing at cdx's
+    # layout by walking up from it: two levels above a home is `/` for anything
+    # not laid out as `<base>/profiles/<name>`, and writing there fails.
+    return os.path.join(os.path.dirname(auth_home), ".cdx-codex-plugins", os.path.basename(auth_home))
+
+
+# Codex only runs hooks that come from an installed plugin, identified as
+# `<plugin>@<marketplace>`. Generating one per session keeps the resolved cdx
+# path baked into it.
+CODEX_PLUGIN = "cdx-notify"
+CODEX_MARKETPLACE = "cdx"
+CODEX_PLUGIN_REF = f"{CODEX_PLUGIN}@{CODEX_MARKETPLACE}"
+
+
+def _provision_codex_plugin(auth_home, enabled, command, env, spawn_sync=None, base_dir=None):
+    installed = _codex_plugin_installed(auth_home)
+    if enabled == installed:
+        return False
+    if not enabled:
+        _run_codex(["plugin", "remove", CODEX_PLUGIN_REF], auth_home, env, spawn_sync)
+        _run_codex(["plugin", "marketplace", "remove", CODEX_MARKETPLACE], auth_home, env, spawn_sync)
+        return False
+    root = _write_codex_plugin(auth_home, command, base_dir)
+    if not root:
+        return False
+    if not _run_codex(["plugin", "marketplace", "add", root], auth_home, env, spawn_sync):
+        return False
+    return _run_codex(["plugin", "add", CODEX_PLUGIN_REF], auth_home, env, spawn_sync)
+
+
+def _codex_plugin_installed(auth_home):
+    """Whether Codex's own config already lists our plugin.
+
+    Read rather than remembered, so a plugin the user removed by hand is
+    reinstalled on the next launch instead of being assumed present.
+    """
+    try:
+        with open(os.path.join(auth_home, "config.toml"), encoding="utf-8") as handle:
+            return f'[plugins."{CODEX_PLUGIN_REF}"]' in handle.read()
+    except OSError:
+        return False
+
+
+def _write_codex_plugin(auth_home, command, base_dir=None):
+    root = codex_plugin_root(auth_home, base_dir)
+    files = {
+        os.path.join(root, ".claude-plugin", "marketplace.json"): {
+            "name": CODEX_MARKETPLACE,
+            "description": "cdx agent notifications",
+            "owner": {"name": "cdx"},
+            "plugins": [{
+                "name": CODEX_PLUGIN,
+                "description": "Notify when this cdx session finishes a turn or waits for you",
+                "source": "./",
+            }],
+        },
+        # The "hooks" key is what makes Codex load the file at all; without it
+        # the plugin installs cleanly and never runs anything.
+        os.path.join(root, ".claude-plugin", "plugin.json"): {
+            "name": CODEX_PLUGIN,
+            "version": "1.0.0",
+            "description": "Notify when this cdx session finishes a turn or waits for you",
+            "hooks": "./hooks/cdx-hooks.json",
+        },
+        os.path.join(root, "hooks", "cdx-hooks.json"): {
+            "hooks": {
+                event: [{"hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}]}]
+                for event in ("Stop", "Notification")
+            },
+        },
+    }
+    for path, document in files.items():
+        if not _write_json(path, document):
+            return None
+    return root
+
+
+def _run_codex(args, auth_home, env, spawn_sync):
+    """Run one `codex` command, following the repo's (command, args, options)
+    spawn_sync contract rather than subprocess.run's, so the same injected
+    double serves here as everywhere else."""
+    options = {"env": {**env, "CODEX_HOME": auth_home}, "cwd": auth_home}
+    try:
+        result = (spawn_sync or _subprocess_spawn_sync)("codex", list(args), options)
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+        # No codex on PATH, or it hung: a skipped provisioning step, never a
+        # failed launch.
+        return False
+    if isinstance(result, dict):
+        return not result.get("error") and result.get("status", 0) == 0
+    return getattr(result, "returncode", 0) == 0
+
+
+def _subprocess_spawn_sync(command, args, options):
+    return subprocess.run(
+        [command, *args],
+        env=options.get("env"),
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+
+
+def _apply_hooks(path, enabled, command):
+    document = _read_json(path)
+    if document is None:
+        return False
+    hooks = document.get("hooks")
+    hooks = hooks if isinstance(hooks, dict) else {}
+    before = json.dumps(hooks, sort_keys=True)
+    for event in ("Stop", "Notification"):
+        # 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)]
+        if enabled:
+            entries.append({
+                "hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}],
+            })
+        if entries:
+            hooks[event] = entries
+        else:
+            hooks.pop(event, None)
+    if json.dumps(hooks, sort_keys=True) == before:
+        return False
+    document["hooks"] = hooks
+    return _write_json(path, document) and enabled
+
+
+def _is_ours(entry):
+    """Ours if any of its commands is a cdx notify invocation."""
+    if not isinstance(entry, dict):
+        return False
+    for hook in entry.get("hooks") or []:
+        command = str((hook or {}).get("command") or "")
+        if command.endswith(f" {HOOK_ARG}") and "cdx" in command:
+            return True
+    return False
+
+
+def _read_json(path):
+    """Existing content, {} when absent, or None when we must not touch it.
+
+    An unparseable file is someone else's, so we leave it exactly as it is
+    rather than replacing settings the user cares about.
+    """
+    try:
+        with open(path, encoding="utf-8") as handle:
+            document = json.load(handle)
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError):
+        return None
+    return document if isinstance(document, dict) else None
+
+
+def _write_json(path, document):
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as handle:
+            json.dump(document, handle, indent=2)
+            handle.write("\n")
+    except OSError:
+        # An unwritable home is a skipped provisioning step, not a failed launch.
+        return False
+    return True

package/src/cli.py

@@ -5,6 +5,7 @@ import os
 import sys
 from datetime import datetime, timezone
 
+from .agent_notify import handle_notify
 from .cli_commands import (
     API_SCHEMA_VERSION,
     STATUS_USAGE,
@@ -34,7 +35,7 @@ from .cli_commands import (
     handle_logout,
     handle_memory,
     handle_next,
-    handle_notify,
+    handle_ready,
     handle_remove,
     handle_rename,
     handle_repair,
@@ -258,8 +259,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx view [--json]', '36', use_color)}",
         f"  {_style('cdx update [all] [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",
         f"  {_style('cdx ready [--refresh] [--json]', '36', use_color)}",
-        f"  {_style('cdx notify <name> --at-reset [--schedule] [--refresh] [--json]', '36', use_color)}",
-        f"  {_style('cdx notify --next-ready [--schedule] [--refresh] [--json]', '36', use_color)}",
+        f"  {_style('cdx notify', '36', use_color)}  # hook target, called by the provider",
         f"  {_style('cdx <name> [--json]', '36', use_color)}",
         f"  {_style('cdx --help', '36', use_color)}",
         f"  {_style('cdx --version', '36', use_color)}",
@@ -576,9 +576,7 @@ def main(argv, options=None):
     }
 
     if resolved_command == "ready":
-        if any(arg not in ("--refresh", "--json") for arg in rest):
-            raise CdxError("Usage: cdx ready [--refresh] [--json]")
-        return handle_notify(["--next-ready", "--schedule", *rest], ctx)
+        return handle_ready(rest, ctx)
 
     if resolved_command in ("power", "perm", "fast", "model"):
         return handle_launch_setting_alias(resolved_command, rest, ctx)

package/src/cli_args.py

@@ -248,6 +248,7 @@ def _parse_set_args(args):
         "--fast": {"key": "fast", "type": "str", "default": None, "transform": _parse_fast_value},
         "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _parse_fast_value},
         "--logics": {"key": "logics", "type": "str", "default": None, "transform": _parse_fast_value},
+        "--notify": {"key": "notify", "type": "str", "default": None, "transform": _parse_fast_value},
         "--model": {"key": "model", "type": "str", "default": None},
         "--fallback-model": {"key": "fallback_model", "type": "str", "default": None},
         "--budget": {"key": "budget", "type": "str", "default": None, "transform": _parse_budget_value},
@@ -269,7 +270,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "model", "fallback_model", "budget", "extra_args", "priority")
+        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "model", "fallback_model", "budget", "extra_args", "priority")
         if parsed[key] is not None
     }
     if not settings:
@@ -291,6 +292,7 @@ def _parse_unset_args(args):
         "--fast": {"key": "fast", "type": "bool", "default": False},
         "--rtk": {"key": "rtk", "type": "bool", "default": False},
         "--logics": {"key": "logics", "type": "bool", "default": False},
+        "--notify": {"key": "notify", "type": "bool", "default": False},
         "--model": {"key": "model", "type": "bool", "default": False},
         "--fallback-model": {"key": "fallback_model", "type": "bool", "default": False},
         "--budget": {"key": "budget", "type": "bool", "default": False},
@@ -312,7 +314,7 @@ def _parse_unset_args(args):
     if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
         raise CdxError(UNSET_USAGE)
     _UNSET_KEYS = (
-        "power", "reasoning_effort", "permission", "fast", "rtk", "logics",
+        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify",
         "model", "fallback_model", "budget", "extra_args", "priority",
     )
     keys = list(_UNSET_KEYS) if parsed["all"] else [key for key in _UNSET_KEYS if parsed[key]]

package/src/cli_commands.py

@@ -48,7 +48,7 @@ from .commands.auth import (
     handle_logout as handle_logout,
 )
 from .commands.auth import (
-    handle_notify as handle_notify,
+    handle_ready as handle_ready,
 )
 from .commands.auth import (
     handle_reset as handle_reset,

package/src/cli_helpers.py

@@ -486,6 +486,7 @@ def _format_launch_config(session, use_color=False):
         ("fast", "Fast"),
         ("rtk", "RTK"),
         ("logics", "Logics"),
+        ("notify", "Notify"),
         ("model", "Model"),
         ("fallback_model", "Fallback"),
         ("budget", "Budget"),
@@ -508,17 +509,19 @@ def _format_launch_config(session, use_color=False):
 def _format_launch_settings_hint(name="<name>"):
     return (
         f"Set a value: cdx set {name} --power medium --permission auto "
-        "--fast on --rtk on --logics on --model MODEL --priority 80"
+        "--fast on --rtk on --logics on --notify on --model MODEL --priority 80"
     )
 
 def _format_launch_setting_value(launch, key, use_color=False):
-    if key in ("fast", "rtk", "logics"):
+    if key in ("fast", "rtk", "logics", "notify"):
         if launch.get(key) is True:
             return _style("on", "32", use_color)
         if launch.get(key) is False:
             return _style("off", "2", use_color)
         if key == "logics":
             return _dim("auto", use_color)
+        if key == "notify":
+            return _style("off", "2", use_color)
         return _dim("default", use_color)
     value = launch.get(key)
     if value is None or value == "":

package/src/commands/auth.py

@@ -1,4 +1,4 @@
-"""Authentication domain commands: login, logout, reset, notify.
+"""Authentication domain commands: login, logout, reset, ready.
 
 Split out of cli_commands.py. Moved verbatim; re-exported by cli_commands.
 """
@@ -20,13 +20,11 @@ from ..codex_usage import consume_codex_rate_limit_reset_credit
 from ..config import PROVIDER_ANTIGRAVITY, PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_OLLAMA
 from ..errors import CdxError
 from ..notify import (
-    format_notify_event,
     format_scheduled_notification,
-    parse_notify_args,
+    parse_ready_args,
     resolve_notify_event,
     schedule_notification_event,
     send_desktop_notification,
-    wait_for_notification_event,
 )
 from ..provider_runtime import _ensure_session_authentication, _run_interactive_provider_command
 
@@ -35,61 +33,46 @@ def _confirm_reset(name):
     answer = input(f"Consume one banked Codex reset for {name}? [y/N] ")
     return answer.strip().lower() in ("y", "yes")
 
-def handle_notify(rest, ctx):
-    parsed = parse_notify_args(rest)
+def handle_ready(rest, ctx):
+    """`cdx ready`: schedule an OS notification for the next session to come back.
 
-    def notifier(title, message):
+    This is all that remains of the quota-reset flow: `cdx notify` now means
+    agent notifications, and the wait-and-poll surface that used to sit here was
+    unreachable once `cdx ready` became the only entry point.
+    """
+    parsed = parse_ready_args(rest)
+    event = resolve_notify_event(
+        ctx["service"]["get_status_rows"](
+            progress_callback=None if parsed["json"] else _make_notify_progress(ctx),
+            force_refresh=parsed["refresh"],
+        ),
+        parsed,
+        (ctx["options"].get("now") or time.time)(),
+    )
+    if event["ready"]:
         send_desktop_notification(
-            title,
-            message,
-            spawn_sync=ctx.get("spawn_sync"),
-            env=ctx.get("env"),
+            event["title"], event["message"],
+            spawn_sync=ctx.get("spawn_sync"), env=ctx.get("env"),
         )
-
-    if parsed["schedule"]:
-        event = resolve_notify_event(
-            ctx["service"]["get_status_rows"](
-                progress_callback=None if parsed["json"] else _make_notify_progress(ctx),
-                force_refresh=parsed.get("refresh", False),
-            ),
+        schedule = {
+            "scheduled": False,
+            "backend": "immediate",
+            "message": event["message"],
+            "target_timestamp": event.get("target_timestamp"),
+        }
+    else:
+        schedule = schedule_notification_event(
+            ctx["service"]["base_dir"],
             parsed,
-            (ctx["options"].get("now") or time.time)(),
+            event,
+            spawn_sync=ctx.get("spawn_sync"),
+            env=ctx.get("env"),
+            now_fn=ctx["options"].get("now"),
         )
-        if event["ready"]:
-            notifier(event["title"], event["message"])
-            schedule = {
-                "scheduled": False,
-                "backend": "immediate",
-                "message": event["message"],
-                "target_timestamp": event.get("target_timestamp"),
-            }
-        else:
-            schedule = schedule_notification_event(
-                ctx["service"]["base_dir"],
-                parsed,
-                event,
-                spawn_sync=ctx.get("spawn_sync"),
-                env=ctx.get("env"),
-                now_fn=ctx["options"].get("now"),
-            )
-        if parsed["json"]:
-            _write_json(ctx, _json_success("notify", "Scheduled notification event", event=event, schedule=schedule))
-        else:
-            ctx["out"](f"{format_scheduled_notification(schedule)}\n")
-        return 0
-
-    event = wait_for_notification_event(
-        ctx["service"],
-        parsed,
-        notifier=notifier,
-        sleep_fn=ctx["options"].get("sleep"),
-        now_fn=ctx["options"].get("now"),
-        progress_callback=None if parsed["json"] else _make_notify_progress(ctx),
-    )
     if parsed["json"]:
-        _write_json(ctx, _json_success("notify", "Resolved notification event", event=event))
+        _write_json(ctx, _json_success("notify", "Scheduled notification event", event=event, schedule=schedule))
     else:
-        ctx["out"](f"{format_notify_event(event)}\n")
+        ctx["out"](f"{format_scheduled_notification(schedule)}\n")
     return 0
 
 def handle_reset(rest, ctx):

package/src/commands/launch.py

@@ -6,6 +6,7 @@ Split out of cli_commands.py. Moved verbatim; re-exported by cli_commands.
 import os
 import shlex
 
+from ..agent_notify import notifications_enabled, provision
 from ..cli_args import CAN_RESUME_USAGE, HANDOFF_USAGE, RESUME_USAGE, _parse_json_flag
 from ..cli_helpers import (
     API_SCHEMA_VERSION,
@@ -21,9 +22,10 @@ from ..cli_helpers import (
     _write_update_notice,
 )
 from ..cli_render import _dim, _info, _success, _warn
+from ..config import PROVIDER_CODEX
 from ..context_store import install_context_for_session, write_context
 from ..errors import CdxError
-from ..provider_runtime import _ensure_session_authentication, _run_interactive_provider_command
+from ..provider_runtime import _ensure_session_authentication, _get_auth_home, _run_interactive_provider_command
 
 
 def _format_resume_capability(capability, use_color=False):
@@ -108,6 +110,23 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
     if not json_flag:
         ctx["out"](f"{_info(message, ctx['use_color'])}\n")
         _write_update_notice(ctx)
+    installed = provision(
+        _get_auth_home(session),
+        session["provider"],
+        notifications_enabled(session),
+        ctx.get("env"),
+        spawn_sync=ctx.get("spawn_sync"),
+        base_dir=ctx["service"]["base_dir"],
+    )
+    if installed and not json_flag:
+        notice = f"Notification hooks installed for {session['name']}"
+        if session["provider"] == PROVIDER_CODEX:
+            # Codex refuses to run a hook it has not been told to trust, so
+            # silence here would leave the user with a feature that quietly does
+            # nothing. Claude Code honours them straight away — verified against
+            # a real turn — so it gets no instruction it does not need.
+            notice += " — approve them once in Codex to enable"
+        ctx["out"](f"{_info(notice, ctx['use_color'])}\n")
     cwd = ctx.get("cwd") or os.getcwd()
     runtime_run_id = None
 

package/src/notify.py

@@ -10,126 +10,51 @@ from .errors import CdxError
 from .session_ranking import rank_sessions
 from .status_view import (
     PRIORITY_EMPTY_AVAILABLE_THRESHOLD,
-    _parse_reset_timestamp,
     _priority_reset_timestamp,
 )
 
-NOTIFY_USAGE = "Usage: cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] | cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh]"
-
-
-def parse_notify_args(args):
-    json_flag = "--json" in args
-    once = "--once" in args
-    at_reset = "--at-reset" in args
-    next_ready = "--next-ready" in args
-    refresh = "--refresh" in args
-    schedule = "--schedule" in args
-    poll = 60
-    cleaned = []
-    i = 0
-    while i < len(args):
-        arg = args[i]
-        if arg in ("--json", "--once", "--at-reset", "--next-ready", "--refresh", "--schedule"):
-            i += 1
-            continue
-        if arg == "--poll":
-            if i + 1 >= len(args):
-                raise CdxError(NOTIFY_USAGE)
-            try:
-                poll = max(1, int(args[i + 1]))
-            except ValueError as error:
-                raise CdxError("--poll must be a number of seconds") from error
-            i += 2
-            continue
-        if arg.startswith("--poll="):
-            try:
-                poll = max(1, int(arg.split("=", 1)[1]))
-            except ValueError as error:
-                raise CdxError("--poll must be a number of seconds") from error
-            i += 1
-            continue
-        if arg.startswith("-"):
-            raise CdxError(NOTIFY_USAGE)
-        cleaned.append(arg)
-        i += 1
-    if at_reset == next_ready:
-        raise CdxError(NOTIFY_USAGE)
-    if at_reset and len(cleaned) != 1:
-        raise CdxError("Usage: cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh]")
-    if next_ready and cleaned:
-        raise CdxError("Usage: cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh]")
-    return {
-        "name": cleaned[0] if cleaned else None,
-        "mode": "at-reset" if at_reset else "next-ready",
-        "poll": poll,
-        "once": once,
-        "json": json_flag,
-        "refresh": refresh,
-        "schedule": schedule,
-    }
+READY_USAGE = "Usage: cdx ready [--refresh] [--json]"
 
 
-def wait_for_notification_event(service, parsed, notifier=None, sleep_fn=None, now_fn=None, progress_callback=None):
-    notifier = notifier or send_desktop_notification
-    sleep_fn = sleep_fn or time.sleep
-    now_fn = now_fn or time.time
-    while True:
-        if progress_callback:
-            progress_callback({"event": "notify_check_started", "mode": parsed["mode"], "session_name": parsed["name"]})
-        event = resolve_notify_event(
-            service["get_status_rows"](
-                progress_callback=progress_callback,
-                force_refresh=parsed.get("refresh", False),
-            ),
-            parsed,
-            now_fn(),
-        )
-        if event["ready"] or parsed["once"]:
-            if event["ready"]:
-                notifier(event["title"], event["message"])
-            return event
-        if progress_callback:
-            progress_callback({
-                "event": "notify_waiting",
-                "message": event["message"],
-                "poll": parsed["poll"],
-                "session_name": event.get("session"),
-                "target_timestamp": event.get("target_timestamp"),
-            })
-        sleep_fn(parsed["poll"])
+def parse_ready_args(args):
+    """`cdx ready [--refresh] [--json]`.
+
+    This used to parse a much wider surface — --at-reset, --once, --poll and a
+    blocking wait loop — reachable through a `cdx notify` that no longer exists.
+    `cdx ready` always schedules the next-ready event, so none of it could run.
+    """
+    unknown = [arg for arg in args if arg not in ("--refresh", "--json")]
+    if unknown:
+        raise CdxError(READY_USAGE)
+    return {
+        "name": None,
+        "mode": "next-ready",
+        "json": "--json" in args,
+        "refresh": "--refresh" in args,
+        "schedule": True,
+    }
 
 
 def resolve_notify_event(rows, parsed, now_ts=None):
     now_ts = time.time() if now_ts is None else now_ts
-    if parsed["mode"] == "next-ready":
-        active_rows = [row for row in rows if row.get("enabled", True) is not False]
-        # Same ranking every other selector uses; the pre-filter is what makes
-        # this "next to come back" rather than "best right now".
-        priority, _decision = rank_sessions(
-            [
-                row for row in active_rows
-                if not _is_usable_now(row) and _priority_reset_timestamp(row) is not None
-            ],
-            now_ts,
-            _priority_reset_timestamp,
-        )
-        if not priority:
-            return _event(False, "cdx", "No upcoming session reset available", None)
-        first = priority[0]
-        timestamp = _priority_reset_timestamp(first)
-        if _needs_refresh(first, timestamp, now_ts):
-            return _event(True, "cdx", f"{first['session_name']} reset is due; refresh status", first["session_name"])
-        return _event(False, "cdx", f"Waiting for {first['session_name']}", first["session_name"], timestamp)
-
-    row = next((item for item in rows if item["session_name"] == parsed["name"]), None)
-    if not row:
-        raise CdxError(f"Unknown session: {parsed['name']}")
-    timestamp = _next_reset_timestamp(row)
-    if timestamp is None:
-        return _event(False, "cdx", f"No reset time known for {row['session_name']}", row["session_name"])
-    if timestamp <= now_ts:
-        return _event(True, "cdx", f"{row['session_name']} reset is due", row["session_name"], timestamp)
-    return _event(False, "cdx", f"Waiting for {row['session_name']} reset", row["session_name"], timestamp)
+    active_rows = [row for row in rows if row.get("enabled", True) is not False]
+    # Same ranking every other selector uses; the pre-filter is what makes
+    # this "next to come back" rather than "best right now".
+    priority, _decision = rank_sessions(
+        [
+            row for row in active_rows
+            if not _is_usable_now(row) and _priority_reset_timestamp(row) is not None
+        ],
+        now_ts,
+        _priority_reset_timestamp,
+    )
+    if not priority:
+        return _event(False, "cdx", "No upcoming session reset available", None)
+    first = priority[0]
+    timestamp = _priority_reset_timestamp(first)
+    if _needs_refresh(first, timestamp, now_ts):
+        return _event(True, "cdx", f"{first['session_name']} reset is due; refresh status", first["session_name"])
+    return _event(False, "cdx", f"Waiting for {first['session_name']}", first["session_name"], timestamp)
 
 
 def _is_usable_now(row):
@@ -144,18 +69,6 @@ def _needs_refresh(row, reset_timestamp, now_ts):
     return reset_timestamp is not None and reset_timestamp < now_ts
 
 
-def _next_reset_timestamp(row):
-    values = [row.get("reset_5h_at"), row.get("reset_week_at"), row.get("reset_at")]
-    timestamps = [
-        timestamp
-        for timestamp in (_parse_reset_timestamp(value) for value in values)
-        if timestamp is not None
-    ]
-    if not timestamps:
-        return None
-    return min(timestamps)
-
-
 def _event(ready, title, message, session_name, target_timestamp=None):
     return {
         "ready": ready,
@@ -166,22 +79,70 @@ def _event(ready, title, message, session_name, target_timestamp=None):
     }
 
 
-def send_desktop_notification(title, message, spawn_sync=None, env=None):
+def notification_channel(env=None):
+    """Name the delivery mechanism usable on this host, or None if there is none.
+
+    Two callers depend on this answer: `cdx notify` decides whether to bother
+    delivering, and launch provisioning decides whether to install hooks at all.
+    A host with no channel gets no hooks, so the user is never asked to approve
+    a hook that could not have shown them anything.
+    """
     import sys
-    spawn_sync = spawn_sync or subprocess.run
     env = env or os.environ
+    path = env.get("PATH")
     if sys.platform == "win32":
-        _send_windows_notification(title, message, spawn_sync, env)
-    elif shutil.which("osascript", path=env.get("PATH")):
+        return "powershell" if shutil.which("powershell", path=path) else None
+    if _is_wsl(env):
+        # WSL has no notification daemon of its own; delivery crosses to Windows
+        # through interop, which /etc/wsl.conf can disable.
+        return "wsl" if shutil.which("powershell.exe", path=path) else None
+    if shutil.which("osascript", path=path):
+        return "osascript" if _has_desktop_session(env) else None
+    if shutil.which("notify-send", path=path):
+        return "notify-send" if _has_desktop_session(env) else None
+    return None
+
+
+def _is_wsl(env):
+    if env.get("WSL_DISTRO_NAME") or env.get("WSL_INTEROP"):
+        return True
+    try:
+        with open("/proc/version", encoding="utf-8") as handle:
+            return "microsoft" in handle.read().lower()
+    except OSError:
+        return False
+
+
+def _has_desktop_session(env):
+    """Whether anything is around to render a notification.
+
+    Over SSH or in a container there is no session bus and no display, so
+    notify-send is delivered nowhere and osascript has no session to talk to.
+    """
+    import sys
+    if sys.platform == "darwin":
+        return not env.get("SSH_CONNECTION")
+    return bool(env.get("DISPLAY") or env.get("WAYLAND_DISPLAY") or env.get("DBUS_SESSION_BUS_ADDRESS"))
+
+
+def send_desktop_notification(title, message, spawn_sync=None, env=None):
+    spawn_sync = spawn_sync or subprocess.run
+    env = env or os.environ
+    channel = notification_channel(env)
+    if channel == "powershell":
+        _send_windows_notification(title, message, spawn_sync, env, ["powershell"])
+    elif channel == "wsl":
+        _send_windows_notification(title, message, spawn_sync, env, ["powershell.exe"])
+    elif channel == "osascript":
         script = f'display notification "{_escape_applescript(message)}" with title "{_escape_applescript(title)}"'
         _run_notification_command(
             ["osascript", "-e", script],
             spawn_sync,
             env,
         )
-    elif shutil.which("notify-send", path=env.get("PATH")):
+    elif channel == "notify-send":
         _run_notification_command(
-            ["notify-send", str(title), str(message)],
+            ["notify-send", "-a", "cdx", str(title), str(message)],
             spawn_sync,
             env,
         )
@@ -190,26 +151,45 @@ def send_desktop_notification(title, message, spawn_sync=None, env=None):
 def _run_notification_command(argv, spawn_sync, env):
     try:
         spawn_sync(argv, env=env, capture_output=True, text=True, timeout=5)
-    except (FileNotFoundError, OSError):
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
         pass
 
 
-def _send_windows_notification(title, message, spawn_sync, env):
-    title_escaped = _escape_powershell(title)
-    message_escaped = _escape_powershell(message)
-    script = (
-        "Add-Type -AssemblyName System.Windows.Forms; "
-        f"[System.Windows.Forms.MessageBox]::Show('{message_escaped}', '{title_escaped}')"
+# Windows only shows a toast on behalf of an application it knows. Registering our
+# own identifier would mean installing a Start Menu shortcut, so we borrow the one
+# PowerShell already ships with; an unknown identifier is dropped in silence.
+_POWERSHELL_AUMID = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe"
+
+_TOAST_SCRIPT = """
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] > $null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType=WindowsRuntime] > $null
+$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$nodes = $template.GetElementsByTagName('text')
+$nodes.Item(0).AppendChild($template.CreateTextNode('{title}')) > $null
+$nodes.Item(1).AppendChild($template.CreateTextNode('{message}')) > $null
+$toast = [Windows.UI.Notifications.ToastNotification]::new($template)
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('{aumid}').Show($toast)
+"""
+
+
+def _send_windows_notification(title, message, spawn_sync, env, launcher):
+    """Raise a toast rather than a dialog.
+
+    The dialog this replaced blocked with no timeout, which was survivable for a
+    once-a-day quota alert and not for a hook that fires on every agent turn: an
+    undismissed window holds the turn open, and one that steals focus every turn
+    is worse than no notification at all.
+    """
+    script = _TOAST_SCRIPT.format(
+        title=_escape_powershell(title),
+        message=_escape_powershell(message),
+        aumid=_POWERSHELL_AUMID,
+    )
+    _run_notification_command(
+        [*launcher, "-NoProfile", "-NonInteractive", "-Command", script],
+        spawn_sync,
+        env,
     )
-    try:
-        spawn_sync(
-            ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
-            env=env,
-            capture_output=True,
-            text=True,
-        )
-    except (FileNotFoundError, OSError):
-        pass
 
 
 def _escape_powershell(value):
@@ -437,10 +417,6 @@ def _escape_xml(value):
     return str(value).replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")
 
 
-def format_notify_event(event):
-    return event["message"]
-
-
 def format_scheduled_notification(schedule):
     if schedule.get("scheduled"):
         return f"Scheduled notification via {schedule['backend']} for {schedule['target_iso']}"

package/src/provider_runtime.py

@@ -10,6 +10,7 @@ import sys
 import uuid
 from datetime import datetime, timezone
 
+from .agent_notify import launch_notify_env, notifications_enabled
 from .claude_usage import _clean_oauth_token, _decode_jwt_claims
 from .codex_usage import codex_auth_lock
 from .config import (
@@ -517,6 +518,7 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
     cwd = cwd or os.getcwd()
     env_override = env_override or {}
     env = {**os.environ, **env_override}
+    env.update(launch_notify_env(session, notifications_enabled(session)))
     initial_prompt = _with_launch_preferences(session, initial_prompt, env=env)
     _validate_initial_prompt(initial_prompt)
     if session["provider"] == PROVIDER_CLAUDE:
@@ -724,6 +726,9 @@ def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_pr
     _validate_initial_prompt(initial_prompt)
     cwd = cwd or os.getcwd()
     env = {**os.environ, **(env_override or {})}
+    # Headless runs read the same home, and so the same hooks, as an interactive
+    # launch. Their caller already learns of completion from the return value.
+    env.update(launch_notify_env(session, enabled=False))
     initial_prompt = _with_launch_preferences(session, initial_prompt, env=env)
     _validate_initial_prompt(initial_prompt)
     launch = session.get("launch") or {}

package/src/session_service.py

@@ -211,6 +211,18 @@ def _normalize_launch_settings(settings, mark_fast_service_tier=True):
                 normalized["logics"] = False
             else:
                 raise CdxError(f"Unsupported logics value: {settings['logics']}")
+    if "notify" in settings and settings["notify"] is not None:
+        value = settings["notify"]
+        if isinstance(value, bool):
+            normalized["notify"] = value
+        else:
+            text = str(value).strip().lower()
+            if text in ("on", "true", "1", "yes"):
+                normalized["notify"] = True
+            elif text in ("off", "false", "0", "no"):
+                normalized["notify"] = False
+            else:
+                raise CdxError(f"Unsupported notify value: {settings['notify']}")
     if "model" in settings and settings["model"] is not None:
         model = str(settings["model"]).strip()
         if not model:
@@ -349,7 +361,7 @@ def unset_launch_settings(store, name, keys):
     if not keys:
         raise CdxError("At least one launch setting is required.")
     allowed = {
-        "power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics",
+        "power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics", "notify",
         "model", "fallback_model", "budget", "extra_args", "priority",
     }
     unknown = [key for key in keys if key not in allowed]