code-puppy-core-plugins 0.0.40__tar.gz → 0.0.42__tar.gz

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.40
+Version: 0.0.42
 Summary: Official plugin bundle for Code Puppy
 Project-URL: Repository, https://github.com/mpfaffenberger/code_puppy_core_plugins
 Project-URL: Homepage, https://github.com/mpfaffenberger/code_puppy_core_plugins
@@ -55,6 +55,34 @@ The package deliberately does not depend on `code-puppy` in its own metadata.
 `code-puppy` depends on this bundle; adding the reverse edge would create a
 packaging dependency cycle. Plugin CI installs the core runtime separately.
 
+## Completion notifications
+
+The `completion_notification` plugin is disabled by default. Enable a native,
+best-effort desktop notification after a successful top-level response with:
+
+```text
+/set completion_notifications=true
+```
+
+Notifications use a sanitized, shortened copy of the latest user prompt as the
+title and a shortened response preview as the body, with Apple Terminal, iTerm2,
+or Warp labeled through `TERM_PROGRAM` when available. Unknown terminals omit
+the terminal label. Sub-agent completions are intentionally silent. Desktop
+notification centers may retain visible prompt and response previews.
+
+Optional sound configuration is platform-aware:
+
+```text
+/set completion_notification_sound=Frog
+```
+
+On macOS, a simple name selects a system sound (`Frog`, `Glass`, `Ping`, etc.).
+Preview one with `afplay /System/Library/Sounds/Frog.aiff`. On any platform, an
+absolute path to a local sound file is accepted when an available platform
+player can play it. Linux uses `notify-send` for desktop notifications when it
+is installed; Windows uses a best-effort PowerShell toast. No external Python
+dependencies are required.
+
 ## Releases
 
 Pushes to `main` run lint and tests, bump the patch version, build, publish to

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.42}/README.md

@@ -35,6 +35,34 @@ The package deliberately does not depend on `code-puppy` in its own metadata.
 `code-puppy` depends on this bundle; adding the reverse edge would create a
 packaging dependency cycle. Plugin CI installs the core runtime separately.
 
+## Completion notifications
+
+The `completion_notification` plugin is disabled by default. Enable a native,
+best-effort desktop notification after a successful top-level response with:
+
+```text
+/set completion_notifications=true
+```
+
+Notifications use a sanitized, shortened copy of the latest user prompt as the
+title and a shortened response preview as the body, with Apple Terminal, iTerm2,
+or Warp labeled through `TERM_PROGRAM` when available. Unknown terminals omit
+the terminal label. Sub-agent completions are intentionally silent. Desktop
+notification centers may retain visible prompt and response previews.
+
+Optional sound configuration is platform-aware:
+
+```text
+/set completion_notification_sound=Frog
+```
+
+On macOS, a simple name selects a system sound (`Frog`, `Glass`, `Ping`, etc.).
+Preview one with `afplay /System/Library/Sounds/Frog.aiff`. On any platform, an
+absolute path to a local sound file is accepted when an available platform
+player can play it. Linux uses `notify-send` for desktop notifications when it
+is installed; Windows uses a best-effort PowerShell toast. No external Python
+dependencies are required.
+
 ## Releases
 
 Pushes to `main` run lint and tests, bump the patch version, build, publish to

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.42}/code_puppy_core_plugins/chatgpt_oauth/config.py

@@ -28,8 +28,13 @@ CHATGPT_OAUTH_CONFIG: Dict[str, Any] = {
     # backend serves — never the raw number (openai/codex#31860, #32806).
     "default_context_length": 258400,
     "api_key_env_var": "CHATGPT_OAUTH_API_KEY",
-    # Codex CLI version info (for User-Agent header)
-    "client_version": "0.144.1",
+    # Codex CLI version info (for User-Agent header AND the /models
+    # ``client_version`` query param). The catalog gates models on it:
+    # gpt-6-astra has ``minimal_client_version: 0.153.0``, so an older value
+    # here silently hides newer models. Bump when a new generation lands.
+    "client_version": "0.153.3",
+    # Model selected right after a successful OAuth login.
+    "default_model": "codex-gpt-6-astra",
     "originator": "codex_cli_rs",
 }
 

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.42}/code_puppy_core_plugins/chatgpt_oauth/register_callbacks.py

@@ -129,7 +129,7 @@ def _handle_custom_command(command: str, name: str) -> Optional[bool]:
 
     if name in {"chatgpt-auth", "codex-auth"}:
         run_oauth_flow()
-        set_model_and_reload_agent("codex-gpt-5.6-sol")
+        set_model_and_reload_agent(CHATGPT_OAUTH_CONFIG["default_model"])
         # Auth just succeeded: re-discover the auth-gated codex-imagegen skill now
         # rather than waiting for the next process restart.
         refresh_skill_cache()
@@ -205,7 +205,7 @@ def _create_chatgpt_oauth_model(
 
     # Build headers for ChatGPT Codex API
     originator = CHATGPT_OAUTH_CONFIG.get("originator", "codex_cli_rs")
-    client_version = CHATGPT_OAUTH_CONFIG.get("client_version", "0.144.1")
+    client_version = CHATGPT_OAUTH_CONFIG.get("client_version", "0.153.3")
 
     headers = {
         "ChatGPT-Account-Id": account_id,

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.42}/code_puppy_core_plugins/chatgpt_oauth/test_plugin.py

@@ -314,10 +314,47 @@ def test_auth_command_refreshes_skill_cache():
         )
 
     oauth_flow.assert_called_once_with()
-    set_model.assert_called_once_with("codex-gpt-5.6-sol")
+    set_model.assert_called_once_with("codex-gpt-6-astra")
     refresh_skills.assert_called_once_with()
 
 
+def test_default_model_is_in_fallback_catalog():
+    """A default that isn't in the fallback list would 404 when /models is down."""
+    from code_puppy_core_plugins.chatgpt_oauth.config import CHATGPT_OAUTH_CONFIG
+
+    default = CHATGPT_OAUTH_CONFIG["default_model"]
+    prefix = CHATGPT_OAUTH_CONFIG["prefix"]
+    assert default.startswith(prefix)
+    assert default[len(prefix) :] in utils.DEFAULT_CODEX_MODELS
+
+
+def test_client_version_meets_gpt6_minimum():
+    """gpt-6-astra carries minimal_client_version 0.153.0 in the catalog."""
+    from code_puppy_core_plugins.chatgpt_oauth.config import CHATGPT_OAUTH_CONFIG
+
+    version = tuple(int(p) for p in CHATGPT_OAUTH_CONFIG["client_version"].split("."))
+    assert version >= (0, 153, 0)
+
+
+@pytest.mark.parametrize(
+    "name,xhigh,max_effort,responses_controls",
+    [
+        ("gpt-6-astra", True, True, True),
+        ("gpt-6-astra-pro", True, True, True),
+        ("gpt-5.6-sol", True, True, True),
+        ("gpt-5.5", True, False, False),
+        ("gpt-5.4-mini", True, False, False),
+        ("gpt-5.3-codex-spark", True, False, False),
+        ("codex-auto-review", True, False, False),
+        ("gpt-4o", False, False, False),
+    ],
+)
+def test_reasoning_gates_by_gpt_generation(name, xhigh, max_effort, responses_controls):
+    assert utils._supports_xhigh_reasoning(name) is xhigh
+    assert utils._supports_max_reasoning(name) is max_effort
+    assert utils._supports_responses_reasoning_controls(name) is responses_controls
+
+
 def test_codex_imagegen_agent_tool(tmp_path):
     registered = {}
 
@@ -679,5 +716,18 @@ def test_add_models_to_chatgpt_config(tmp_path):
         assert loaded["codex-gpt-4o"]["context_length"] == 258400
 
 
+def test_gpt6_astra_entry_gets_full_reasoning_surface(tmp_path):
+    with patch.object(
+        utils, "get_chatgpt_models_path", return_value=tmp_path / "chatgpt_models.json"
+    ):
+        assert utils.add_models_to_extra_config(["gpt-6-astra"])
+        entry = utils.load_chatgpt_models()["codex-gpt-6-astra"]
+
+    assert entry["supports_xhigh_reasoning"] is True
+    assert entry["supports_max_reasoning"] is True
+    assert "reasoning_context" in entry["supported_settings"]
+    assert "reasoning_mode" in entry["supported_settings"]
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.42}/code_puppy_core_plugins/chatgpt_oauth/utils.py

@@ -7,10 +7,11 @@ import datetime
 import hashlib
 import json
 import logging
+import re
 import secrets
 import time
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 from urllib.parse import parse_qs as urllib_parse_qs
 from urllib.parse import urlencode, urlparse
 
@@ -377,6 +378,7 @@ def exchange_code_for_tokens(
 # Models known to work with ChatGPT OAuth tokens (sourced from codex-rs CLI
 # and shell-scripts/codex-call.sh).
 DEFAULT_CODEX_MODELS = [
+    "gpt-6-astra",
     "gpt-5.6-sol",
     "gpt-5.6-terra",
     "gpt-5.6-luna",
@@ -399,17 +401,39 @@ CODEX_MODEL_CONTEXT_LENGTHS = {
 }
 
 
+_GPT_VERSION_RE = re.compile(r"^gpt-(\d+)(?:\.(\d+))?")
+
+
+def _gpt_version(model_name: str) -> Optional[Tuple[int, int]]:
+    """``(major, minor)`` for a ``gpt-X[.Y]...`` Codex slug, else ``None``.
+
+    Kept local (rather than importing ``code_puppy.model_utils``) so this
+    plugin doesn't hard-require a core release that ships the shared helper.
+    """
+    match = _GPT_VERSION_RE.match(model_name.lower())
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2) or 0)
+
+
+def _gpt_at_least(model_name: str, minimum: Tuple[int, int]) -> bool:
+    version = _gpt_version(model_name)
+    return version is not None and version >= minimum
+
+
 def _supports_xhigh_reasoning(model_name: str) -> bool:
     """Return whether a ChatGPT OAuth model supports xhigh reasoning."""
-    normalized_model_name = model_name.lower()
-    return "codex" in normalized_model_name or normalized_model_name.startswith(
-        ("gpt-5.4", "gpt-5.5", "gpt-5.6")
-    )
+    return "codex" in model_name.lower() or _gpt_at_least(model_name, (5, 4))
 
 
 def _supports_max_reasoning(model_name: str) -> bool:
     """Return whether a ChatGPT OAuth model supports max reasoning effort."""
-    return model_name.lower().startswith("gpt-5.6")
+    return _gpt_at_least(model_name, (5, 6))
+
+
+def _supports_responses_reasoning_controls(model_name: str) -> bool:
+    """GPT-5.6+ (incl. GPT-6) expose reasoning_context / reasoning_mode."""
+    return _gpt_at_least(model_name, (5, 6))
 
 
 def fetch_chatgpt_models(access_token: str, account_id: str) -> List[CodexModelInfo]:
@@ -431,7 +455,7 @@ def fetch_chatgpt_models(access_token: str, account_id: str) -> List[CodexModelI
     import platform
 
     # Build the models URL with client version
-    client_version = CHATGPT_OAUTH_CONFIG.get("client_version", "0.144.1")
+    client_version = CHATGPT_OAUTH_CONFIG.get("client_version", "0.153.3")
     base_url = CHATGPT_OAUTH_CONFIG["api_base_url"].rstrip("/")
     models_url = f"{base_url}/models"
 
@@ -525,7 +549,7 @@ def add_models_to_extra_config(models: List[Union[str, CodexModelInfo]]) -> bool
             # Responses-API models always support reasoning effort, summaries,
             # and text verbosity; per-model extras are added below.
             supported_settings = ["reasoning_effort", "summary", "verbosity"]
-            if model_name.lower().startswith("gpt-5.6"):
+            if _supports_responses_reasoning_controls(model_name):
                 supported_settings.extend(["reasoning_context", "reasoning_mode"])
 
             # xhigh: codex + GPT-5.4+; max: GPT-5.6+. Separate flags so a stronger

code_puppy_core_plugins-0.0.42/code_puppy_core_plugins/completion_notification/__init__.py

@@ -0,0 +1 @@
+"""Opt-in desktop notifications for completed top-level agent runs."""

code_puppy_core_plugins-0.0.42/code_puppy_core_plugins/completion_notification/config.py

@@ -0,0 +1,19 @@
+"""Configuration accessors for the completion-notification plugin."""
+
+from __future__ import annotations
+
+from code_puppy.config import get_value
+
+KEY_ENABLED = "completion_notifications"
+KEY_SOUND = "completion_notification_sound"
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def is_enabled() -> bool:
+    """Return whether completion notifications are explicitly enabled."""
+    return str(get_value(KEY_ENABLED) or "").strip().lower() in _TRUTHY
+
+
+def get_sound() -> str:
+    """Return an optional named macOS sound or absolute local sound-file path."""
+    return str(get_value(KEY_SOUND) or "").strip()

code_puppy_core_plugins-0.0.42/code_puppy_core_plugins/completion_notification/locales/en-US.json

@@ -0,0 +1,7 @@
+{
+  "completion_notification.title": "Code Puppy",
+  "completion_notification.title_with_context": "Code Puppy — {context}",
+  "completion_notification.response_complete": "Response complete.",
+  "completion_notification.response_complete_in_terminal": "Response complete in {terminal}.",
+  "completion_notification.response_preview_in_terminal": "{preview} · {terminal}"
+}

code_puppy_core_plugins-0.0.42/code_puppy_core_plugins/completion_notification/locales/es.json

@@ -0,0 +1,7 @@
+{
+  "completion_notification.title": "Code Puppy",
+  "completion_notification.title_with_context": "Code Puppy — {context}",
+  "completion_notification.response_complete": "Respuesta completada.",
+  "completion_notification.response_complete_in_terminal": "Respuesta completada en {terminal}.",
+  "completion_notification.response_preview_in_terminal": "{preview} · {terminal}"
+}

code_puppy_core_plugins-0.0.42/code_puppy_core_plugins/completion_notification/locales/fr-CA.json

@@ -0,0 +1,7 @@
+{
+  "completion_notification.title": "Code Puppy",
+  "completion_notification.title_with_context": "Code Puppy — {context}",
+  "completion_notification.response_complete": "Réponse terminée.",
+  "completion_notification.response_complete_in_terminal": "Réponse terminée dans {terminal}.",
+  "completion_notification.response_preview_in_terminal": "{preview} · {terminal}"
+}

code_puppy_core_plugins-0.0.42/code_puppy_core_plugins/completion_notification/notifier.py

@@ -0,0 +1,231 @@
+"""Best-effort, dependency-free desktop completion notifications."""
+
+from __future__ import annotations
+
+import logging
+import ntpath
+import os
+import platform
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from code_puppy.i18n import add_catalog_dir, t
+
+logger = logging.getLogger(__name__)
+
+_TIMEOUT_SECONDS = 3
+_CATALOG_DIR = Path(__file__).parent / "locales"
+add_catalog_dir(str(_CATALOG_DIR))
+_MACOS_SOUND_NAME = re.compile(r"^[A-Za-z0-9 _-]+$")
+# Control characters cannot survive intact inside AppleScript/PowerShell/XML
+# source and are never meaningful in a single-line notification, so drop them.
+_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")
+_WHITESPACE = re.compile(r"\s+")
+_TITLE_PREVIEW_CHARS = 88
+_BODY_PREVIEW_CHARS = 180
+_TERMINAL_NAMES = {
+    "apple_terminal": "Terminal",
+    "iterm.app": "iTerm2",
+    "warpterminal": "Warp",
+}
+
+
+def _title(prompt: str = "") -> str:
+    context = prompt_preview(prompt)
+    if context:
+        return t("completion_notification.title_with_context", context=context)
+    return t("completion_notification.title")
+
+
+def notify_completion(
+    sound: str = "", prompt: str = "", response_text: str = ""
+) -> None:
+    """Show a contextual platform-native completion notification."""
+    try:
+        system = platform.system()
+        title = _title(prompt)
+        message = _completion_message(response_text)
+        if system == "Darwin":
+            _notify_macos(title, message, sound)
+        elif system == "Linux":
+            _notify_linux(title, message, sound)
+        elif system == "Windows":
+            _notify_windows(title, message, sound)
+    except Exception:
+        logger.debug("completion notification failed", exc_info=True)
+
+
+def _completion_message(response_text: str = "") -> str:
+    terminal = _TERMINAL_NAMES.get(os.environ.get("TERM_PROGRAM", "").casefold())
+    preview = response_preview(response_text)
+    if preview:
+        return (
+            preview
+            if terminal is None
+            else t(
+                "completion_notification.response_preview_in_terminal",
+                preview=preview,
+                terminal=terminal,
+            )
+        )
+    return (
+        t("completion_notification.response_complete")
+        if terminal is None
+        else t(
+            "completion_notification.response_complete_in_terminal", terminal=terminal
+        )
+    )
+
+
+def response_preview(response_text: str) -> str:
+    """Return a safe, bounded body preview for an agent response."""
+    return _preview(response_text, _BODY_PREVIEW_CHARS)
+
+
+def prompt_preview(prompt: str) -> str:
+    """Return a safe, bounded title preview for a user prompt."""
+    return _preview(prompt, _TITLE_PREVIEW_CHARS)
+
+
+def _preview(text: str, limit: int) -> str:
+    """Collapse dynamic content into a readable, bounded notification line."""
+    compact = _WHITESPACE.sub(" ", _CONTROL_CHARS.sub(" ", text or "")).strip()
+    if len(compact) <= limit:
+        return compact
+    shortened = compact[: limit - 1].rsplit(" ", 1)[0].rstrip(".,;:!?")
+    return f"{shortened or compact[: limit - 1]}…"
+
+
+def _notify_macos(title: str, message: str, sound: str) -> None:
+    body = _escape_applescript(message)
+    title = _escape_applescript(title)
+    script = f'display notification "{body}" with title "{title}"'
+    if _is_macos_sound_name(sound):
+        script += f' sound name "{sound}"'
+    _run(["/usr/bin/osascript", "-e", script])
+    _play_file(sound, players=(("/usr/bin/afplay",),))
+
+
+def _notify_linux(title: str, message: str, sound: str) -> None:
+    notify_send = shutil.which("notify-send")
+    if notify_send:
+        # "--" stops option parsing so a title/message starting with "-" is
+        # never misread as a flag.
+        _run([notify_send, "--app-name", _title(), "--", title, message])
+    _play_file(sound, players=(("paplay",), ("aplay",)))
+
+
+def _notify_windows(title: str, message: str, sound: str) -> None:
+    # Windows Runtime toast APIs are available on current Windows releases. This
+    # remains best-effort: restricted hosts can reject the call without affecting
+    # the completed Code Puppy run.
+    toast_xml = (
+        '<toast><visual><binding template="ToastGeneric">'
+        f"<text>{_escape_xml(title)}</text><text>{_escape_xml(message)}</text>"
+        "</binding></visual></toast>"
+    )
+    # XML-escaping already removes single quotes, but escape the assembled
+    # literal defensively before it enters the single-quoted PowerShell string.
+    toast_literal = toast_xml.replace("'", "''")
+    notifier_title = _title().replace("'", "''")
+    script = (
+        "$xml = New-Object Windows.Data.Xml.Dom.XmlDocument; "
+        f"$xml.LoadXml('{toast_literal}'); "
+        "[Windows.UI.Notifications.ToastNotificationManager]::"
+        f"CreateToastNotifier('{notifier_title}').Show("
+        "[Windows.UI.Notifications.ToastNotification]::new($xml))"
+    )
+    powershell = _powershell_executable()
+    _run([powershell, "-NoProfile", "-NonInteractive", "-Command", script])
+    _play_file(
+        sound,
+        players=((powershell, "-NoProfile", "-NonInteractive", "-Command"),),
+    )
+
+
+def _powershell_executable() -> str:
+    """Return Windows PowerShell by trusted absolute path, never PATH lookup."""
+    system_root = os.environ.get("SystemRoot", r"C:\Windows")
+    return ntpath.join(
+        system_root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"
+    )
+
+
+def _is_macos_sound_name(sound: str) -> bool:
+    return bool(sound) and "/" not in sound and bool(_MACOS_SOUND_NAME.fullmatch(sound))
+
+
+def _escape_applescript(text: str) -> str:
+    """Escape text for a double-quoted AppleScript string literal.
+
+    i18n catalogs are an untrusted plugin/community seam, so translated text is
+    treated as hostile input. Escaping backslash and double-quote (after dropping
+    control characters) prevents breaking out of the literal into ``do shell
+    script`` and neutralizes the injection class entirely.
+    """
+    text = _CONTROL_CHARS.sub(" ", text)
+    return text.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _escape_xml(text: str) -> str:
+    """Escape text for a Windows toast XML text node (untrusted i18n input)."""
+    text = _CONTROL_CHARS.sub(" ", text)
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&apos;")
+    )
+
+
+def _play_file(sound: str, *, players: tuple[tuple[str, ...], ...]) -> None:
+    path = _sound_file(sound)
+    if path is None:
+        return
+    for player in players:
+        if Path(player[0]).is_absolute() or ntpath.isabs(player[0]):
+            executable = player[0]
+        else:
+            executable = shutil.which(player[0]) or (
+                player[0] if Path(player[0]).is_file() else None
+            )
+        if executable is None:
+            continue
+        if ntpath.basename(player[0]).casefold() == "powershell.exe":
+            escaped_path = str(path).replace("'", "''")
+            _run(
+                [
+                    *player,
+                    f"(New-Object System.Media.SoundPlayer '{escaped_path}').PlaySync()",
+                ]
+            )
+        else:
+            _run([executable, *player[1:], str(path)])
+        return
+
+
+def _sound_file(sound: str) -> Path | None:
+    if not sound or _is_macos_sound_name(sound):
+        return None
+    path = Path(sound).expanduser()
+    if not path.is_absolute() or not path.is_file():
+        return None
+    return path
+
+
+def _run(command: list[str]) -> None:
+    try:
+        subprocess.run(
+            command,
+            capture_output=True,
+            check=False,
+            timeout=_TIMEOUT_SECONDS,
+            text=True,
+        )
+    except (OSError, subprocess.SubprocessError):
+        logger.debug(
+            "completion notification command failed: %s", command[0], exc_info=True
+        )

code_puppy_core_plugins-0.0.42/code_puppy_core_plugins/completion_notification/register_callbacks.py

@@ -0,0 +1,135 @@
+"""Register opt-in desktop notifications for completed top-level agent runs."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+
+from code_puppy.callbacks import register_callback
+
+from .config import get_sound, is_enabled
+from .notifier import notify_completion, prompt_preview
+
+logger = logging.getLogger(__name__)
+_WORKER_JOIN_TIMEOUT_SECONDS = 3
+_lock = threading.Lock()
+_run_depth = 0
+_workers: set[threading.Thread] = set()
+_prompts: dict[str, str] = {}
+
+
+def _on_user_prompt_submit(prompt: str, session_id: str | None = None) -> None:
+    """Keep an opted-in prompt only until its run finishes."""
+    if not session_id or not is_enabled() or _is_subagent():
+        return
+    with _lock:
+        _prompts[session_id] = prompt_preview(prompt)
+
+
+def _is_subagent() -> bool:
+    try:
+        from code_puppy.tools.subagent_context import is_subagent
+
+        return is_subagent()
+    except Exception:
+        logger.debug(
+            "sub-agent status could not be determined; suppressing notification",
+            exc_info=True,
+        )
+        return True
+
+
+def _on_agent_run_start(*_args, **_kwargs) -> None:
+    """Track public lifecycle depth so internal nested runs never notify."""
+    global _run_depth
+    with _lock:
+        _run_depth += 1
+
+
+def _on_agent_run_end(
+    agent_name: str | None = None,
+    model_name: str | None = None,
+    session_id: str | None = None,
+    success: bool = True,
+    error: Exception | None = None,
+    response_text: str | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """Notify only when the outermost successful textual run completes."""
+    del agent_name, model_name, error, metadata
+    global _run_depth
+    with _lock:
+        _run_depth = max(0, _run_depth - 1)
+        is_outermost_run = _run_depth == 0
+        prompt = _prompts.pop(session_id, "") if session_id else ""
+
+    if (
+        not is_outermost_run
+        or not success
+        or not response_text
+        or not is_enabled()
+        or _is_subagent()
+    ):
+        return
+
+    try:
+        _start_notification_worker(get_sound(), prompt, response_text)
+    except Exception:
+        logger.debug("completion notification worker could not start", exc_info=True)
+
+
+def _start_notification_worker(
+    sound: str, prompt: str = "", response_text: str = ""
+) -> None:
+    worker: threading.Thread
+
+    def notify() -> None:
+        try:
+            notify_completion(sound, prompt, response_text)
+        finally:
+            with _lock:
+                _workers.discard(worker)
+
+    worker = threading.Thread(
+        target=notify,
+        daemon=True,
+        name="code-puppy-completion-notification",
+    )
+    with _lock:
+        _workers.add(worker)
+    worker.start()
+
+
+def _drain_workers(*_args, **_kwargs) -> None:
+    """Give notification workers a bounded chance to finish before exit.
+
+    Joins share a single deadline so total wall time stays within the timeout
+    regardless of how many workers are in flight, rather than N x timeout.
+    """
+    with _lock:
+        workers = tuple(_workers)
+        _workers.clear()
+    deadline = time.monotonic() + _WORKER_JOIN_TIMEOUT_SECONDS
+    for worker in workers:
+        remaining = max(0.0, deadline - time.monotonic())
+        try:
+            worker.join(timeout=remaining)
+        except RuntimeError:
+            logger.debug(
+                "completion notification worker could not be joined", exc_info=True
+            )
+
+
+register_callback("user_prompt_submit", _on_user_prompt_submit)
+register_callback("agent_run_start", _on_agent_run_start)
+register_callback("agent_run_end", _on_agent_run_end)
+register_callback("session_end", _drain_workers)
+register_callback("shutdown", _drain_workers)
+
+__all__ = [
+    "_drain_workers",
+    "_on_agent_run_end",
+    "_on_agent_run_start",
+    "_on_user_prompt_submit",
+]