cdx-manager 0.17.0 → 0.17.1

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.17.0-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.17.1-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.
 
@@ -349,8 +349,8 @@ 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
+✓ work1     logics-manager · needs your attention
+✓ codex-a   cdx-manager · turn complete
 ```
 
 Off until you ask for it, per session:
@@ -359,6 +359,7 @@ Off until you ask for it, per session:
 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
+cdx set work1 --notify-preview on  # include a short final-response preview
 ```
 
 Turning it on records the setting. The wiring happens at that session's **next
@@ -372,6 +373,16 @@ 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.
 
+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.
+
+`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-
+down session becomes usable.
+
 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
@@ -489,7 +500,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` | 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 notify` | Internal provider hook target for agent alerts; use `cdx set <name> --notify on` to enable it |
 | `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 |

package/changelogs/CHANGELOGS_0_17_1.md

@@ -0,0 +1,29 @@
+# CDX Manager 0.17.1
+
+## Fixes
+
+### Agent-alert setup now reports provider support accurately
+
+`cdx set <name> --notify on` now distinguishes sessions where cdx can install
+provider hooks (Claude and Codex) from providers that do not expose that
+integration yet. A mixed bulk selection reports both outcomes instead of
+promising a future hook installation that cannot happen.
+
+The setting remains storable for unsupported providers, so bulk configuration
+remains predictable and a future provider integration can honour the existing
+opt-in.
+
+### Permission-request notifications constrain tool names
+
+Tool names supplied by provider hook payloads now use the same printable,
+single-line normalization as response previews and are capped at 80 characters.
+This keeps permission notifications readable and prevents malformed payloads
+from expanding or controlling desktop notification text.
+
+## Validation
+
+- `npm run lint`
+- `npm test`
+- `npm run release:validate`
+- `logics-manager lint --require-status`
+- `logics-manager audit --legacy-cutoff-version 1.1.0 --group-by-doc`

package/checksums/release-archives.json

@@ -184,6 +184,10 @@
     "v0.16.0": {
       "github_tarball_sha256": "bdcd2808922410b20567ba86589d49166c5c2b9404325195b28457df80ca3dad",
       "github_zip_sha256": "e89cb8c964304f0805d06da9d355d543f8a590e0febbf07e585a692ccf73ef99"
+    },
+    "v0.17.0": {
+      "github_tarball_sha256": "6f321106aa426590ce809788fab4f26401b4cc499a6c518a56a4f24f8bfb6c2e",
+      "github_zip_sha256": "72665a0006df40bb27301140b0ed6600a0d91b456facbb5a2aad2a917357ae75"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "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.17.0"
+version = "0.17.1"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/agent_notify.py

@@ -19,13 +19,21 @@ 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"
+PREVIEW_ENV = "CDX_NOTIFY_PREVIEW"
 
 # 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"}
+_WAITING_EVENTS = {"notification", "permissionrequest"}
+_PREVIEW_LIMIT = 180
+_TOOL_NAME_LIMIT = 80
+
+
+def supports_agent_alerts(provider):
+    """Whether cdx can provision provider hooks for this session."""
+    return provider in {"claude", "codex"}
 
 
 def resolve_hook_command(env=None):
@@ -70,9 +78,29 @@ def compose_notification(payload, env=None, cwd=None):
         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"
+    event = event.replace("_", "").replace("-", "")
+    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
-    return f"✓ {session}", f"{where} · {state}"
+    preview = _notification_preview(payload, event, env)
+    return f"✓ {session}", f"{where} · {state}" + (f" — {preview}" if preview else "")
+
+
+def _notification_preview(payload, event, env):
+    if event != "stop" or env.get(PREVIEW_ENV) != "1":
+        return ""
+    return _notification_text(payload.get("last_assistant_message"), _PREVIEW_LIMIT)
+
+
+def _notification_text(value, limit):
+    if not isinstance(value, str):
+        return ""
+    value = " ".join("".join(char if char.isprintable() else " " for char in value).split())
+    if len(value) <= limit:
+        return value
+    return value[:limit - 1].rstrip() + "…"
 
 
 def handle_notify(rest, ctx):
@@ -82,9 +110,12 @@ def handle_notify(rest, ctx):
         stdin_text = None
         # "stdin" in ctx is the {"isTTY": ...} descriptor, not a stream.
         reader = ctx.get("prompt_stdin") or sys.stdin
+        env = os.environ if ctx.get("env") is None else ctx["env"]
+        if ctx.get("stdin_is_tty") and not env.get(SESSION_ENV):
+            ctx["out"]("cdx notify is called by provider hooks. Enable agent alerts with: cdx set <name> --notify on\n")
+            return 0
         if reader is not None and not ctx.get("stdin_is_tty"):
             stdin_text = reader.read()
-        env = os.environ if ctx.get("env") is None else ctx["env"]
         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)
@@ -98,6 +129,8 @@ def launch_notify_env(session, enabled, env=None):
     values = {SESSION_ENV: session["name"]}
     if not enabled:
         values[ENABLED_ENV] = "0"
+    elif (session.get("launch") or {}).get("notify_preview") is True:
+        values[PREVIEW_ENV] = "1"
     return values
 
 
@@ -130,6 +163,8 @@ def provision(auth_home, provider, enabled, env=None, spawn_sync=None, base_dir=
         # 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
+    if not supports_agent_alerts(provider):
+        return False
     command = resolve_hook_command(env)
     if provider == "claude":
         return _apply_hooks(hook_config_path(auth_home, provider), enabled, command)
@@ -224,7 +259,7 @@ def _write_codex_plugin(auth_home, command, base_dir=None):
         os.path.join(root, "hooks", "cdx-hooks.json"): {
             "hooks": {
                 event: [{"hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}]}]
-                for event in ("Stop", "Notification")
+                for event in ("Stop", "PermissionRequest")
             },
         },
     }

package/src/cli.py

@@ -231,8 +231,8 @@ def _print_help(use_color=False):
         f"  {_style('cdx config <name> [--json]', '36', use_color)}",
         f"  {_style('cdx configs [--json]', '36', use_color)}",
         f"  {_style('cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]', '36', use_color)}",
-        f"  {_style('cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--model MODEL] [--priority 0..100] [--json]', '36', use_color)}",
-        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--model|--priority|--all) [--json]', '36', use_color)}",
+        f"  {_style('cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--notify on|off] [--notify-preview on|off] [--model MODEL] [--priority 0..100] [--json]', '36', use_color)}",
+        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--notify|--notify-preview|--model|--priority|--all) [--json]', '36', use_color)}",
         f"  {_style('cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx last [--json]', '36', use_color)}",
@@ -259,7 +259,10 @@ 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', '36', use_color)}  # hook target, called by the provider",
+        "",
+        _style("Notifications:", "1", use_color),
+        f"  {_style('cdx set <name> --notify on', '36', use_color)}  # agent finishes or needs attention",
+        f"  {_style('cdx ready', '36', use_color)}  # next session to become ready",
         f"  {_style('cdx <name> [--json]', '36', use_color)}",
         f"  {_style('cdx --help', '36', use_color)}",
         f"  {_style('cdx --version', '36', use_color)}",

package/src/cli_args.py

@@ -249,6 +249,7 @@ def _parse_set_args(args):
         "--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},
+        "--notify-preview": {"key": "notify_preview", "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},
@@ -270,7 +271,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "model", "fallback_model", "budget", "extra_args", "priority")
+        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "model", "fallback_model", "budget", "extra_args", "priority")
         if parsed[key] is not None
     }
     if not settings:
@@ -293,6 +294,7 @@ def _parse_unset_args(args):
         "--rtk": {"key": "rtk", "type": "bool", "default": False},
         "--logics": {"key": "logics", "type": "bool", "default": False},
         "--notify": {"key": "notify", "type": "bool", "default": False},
+        "--notify-preview": {"key": "notify_preview", "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},
@@ -314,7 +316,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", "notify",
+        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify", "notify_preview",
         "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_helpers.py

@@ -486,7 +486,8 @@ def _format_launch_config(session, use_color=False):
         ("fast", "Fast"),
         ("rtk", "RTK"),
         ("logics", "Logics"),
-        ("notify", "Notify"),
+        ("notify", "Agent alerts"),
+        ("notify_preview", "Response preview"),
         ("model", "Model"),
         ("fallback_model", "Fallback"),
         ("budget", "Budget"),
@@ -509,18 +510,18 @@ 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 --notify on --model MODEL --priority 80"
+        "--fast on --rtk on --logics on --notify on --notify-preview on --model MODEL --priority 80"
     )
 
 def _format_launch_setting_value(launch, key, use_color=False):
-    if key in ("fast", "rtk", "logics", "notify"):
+    if key in ("fast", "rtk", "logics", "notify", "notify_preview"):
         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":
+        if key in ("notify", "notify_preview"):
             return _style("off", "2", use_color)
         return _dim("default", use_color)
     value = launch.get(key)

package/src/cli_render.py

@@ -175,6 +175,7 @@ def _format_sessions(service, use_color=False):
         f"  {_style('cdx configs', '36', use_color)}",
         f"  {_style('cdx stats', '36', use_color)}",
         f"  {_style('cdx ready', '36', use_color)}",
+        f"  {_style('cdx set <name> --notify on', '36', use_color)}",
         f"  {_style('cdx perm all default', '36', use_color)}",
         f"  {_style('cdx handoff <source> <target>', '36', use_color)}",
         f"  {_style('cdx history', '36', use_color)}",

package/src/commands/settings.py

@@ -3,6 +3,7 @@
 Split out of cli_commands.py. Moved verbatim; re-exported by cli_commands.
 """
 
+from ..agent_notify import supports_agent_alerts
 from ..cli_args import _parse_launch_setting_alias_args, _parse_set_args, _parse_unset_args
 from ..cli_helpers import _format_launch_config, _json_success, _write_json
 from ..cli_render import _success
@@ -40,6 +41,28 @@ def _format_bulk_launch_summary(sessions):
         return ", ".join(names)
     return ", ".join(names[:8]) + f", +{len(names) - 8} more"
 
+
+def _notification_setting_notice(settings, sessions, action):
+    if "notify" in settings:
+        supported = [session for session in sessions if supports_agent_alerts(session["provider"])]
+        unsupported = [session for session in sessions if not supports_agent_alerts(session["provider"])]
+        notices = []
+        if supported:
+            names = _format_bulk_launch_summary(supported)
+            if action == "set" and settings["notify"]:
+                notices.append(f"Agent alerts enabled for {names} — hooks install on the next interactive launch.")
+            else:
+                notices.append(f"Agent alerts disabled for {names} — cdx removes its hooks on the next interactive launch.")
+        if unsupported:
+            names = _format_bulk_launch_summary(unsupported)
+            notices.append(f"Agent alerts updated for {names} — this provider does not support notification hooks.")
+        return "\n".join(notices)
+    if "notify_preview" in settings:
+        if action == "set" and settings["notify_preview"]:
+            return f"Response previews enabled for {names} — completion text may be visible on the lock screen."
+        return f"Response previews disabled for {names}."
+    return None
+
 def _apply_launch_settings(parsed, ctx, action="set"):
     targets = _resolve_bulk_launch_targets(parsed, ctx["service"])
     sessions = [
@@ -63,6 +86,9 @@ def _apply_launch_settings(parsed, ctx, action="set"):
         _write_json(ctx, payload)
         return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    notice = _notification_setting_notice(parsed["settings"], sessions, action)
+    if notice:
+        ctx["out"](f"{notice}\n")
     if len(sessions) == 1:
         ctx["out"](f"{_format_launch_config(sessions[0], ctx['use_color'])}\n")
     return 0
@@ -90,6 +116,9 @@ def _clear_launch_settings(parsed, ctx, action="unset"):
         _write_json(ctx, payload)
         return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    notice = _notification_setting_notice({key: False for key in parsed["keys"]}, sessions, action)
+    if notice:
+        ctx["out"](f"{notice}\n")
     if len(sessions) == 1:
         ctx["out"](f"{_format_launch_config(sessions[0], ctx['use_color'])}\n")
     return 0

package/src/commands/status.py

@@ -126,7 +126,7 @@ def _format_launch_configs(sessions, use_color=False):
         for key in ("fallback_model", "budget")
     )
     has_extra = any((session.get("launch") or {}).get("extra_args") for session in sessions)
-    headers = ["SESSION", "PROVIDER", "POWER", "PERMISSION", "FAST", "RTK", "LOGICS", "MODEL"]
+    headers = ["SESSION", "PROVIDER", "POWER", "PERMISSION", "FAST", "RTK", "LOGICS", "ALERTS", "MODEL"]
     if has_headless:
         headers += ["FALLBACK", "BUDGET"]
     if has_extra:
@@ -143,6 +143,7 @@ def _format_launch_configs(sessions, use_color=False):
             _format_launch_setting_value(launch, "fast", use_color),
             _format_launch_setting_value(launch, "rtk", use_color),
             _format_launch_setting_value(launch, "logics", use_color),
+            _format_launch_setting_value(launch, "notify", use_color),
             _format_launch_setting_value(launch, "model", use_color),
         ]
         if has_headless:

package/src/session_service.py

@@ -223,6 +223,18 @@ def _normalize_launch_settings(settings, mark_fast_service_tier=True):
                 normalized["notify"] = False
             else:
                 raise CdxError(f"Unsupported notify value: {settings['notify']}")
+    if "notify_preview" in settings and settings["notify_preview"] is not None:
+        value = settings["notify_preview"]
+        if isinstance(value, bool):
+            normalized["notify_preview"] = value
+        else:
+            text = str(value).strip().lower()
+            if text in ("on", "true", "1", "yes"):
+                normalized["notify_preview"] = True
+            elif text in ("off", "false", "0", "no"):
+                normalized["notify_preview"] = False
+            else:
+                raise CdxError(f"Unsupported notify preview value: {settings['notify_preview']}")
     if "model" in settings and settings["model"] is not None:
         model = str(settings["model"]).strip()
         if not model:
@@ -361,7 +373,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", "notify",
+        "power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics", "notify", "notify_preview",
         "model", "fallback_model", "budget", "extra_args", "priority",
     }
     unknown = [key for key in keys if key not in allowed]