WSL2: notifications/notify hook often fails for approval prompts; add Windows-native toast backend

Summary

In WSL2, Codex CLI’s approval prompts (approval-requested) can fail to trigger a usable desktop
notification when using the current notify hook approach.

The usual Linux notification backend (notify-send via D-Bus) may error with:

• Could not connect: Operation not permitted

This makes it easy to miss approval prompts, leaving sessions blocked waiting for user input.

Environment

• Codex CLI: codex-cli 0.73.0
• OS: WSL2 (kernel string contains microsoft-standard-WSL2)
• Shell: zsh

Configuration used

# ~/.codex/config.toml
notify = [
  "python3",
  "-c",
  "import os,runpy; runpy.run_path(os.path.join(os.path.expanduser('~'), '.codex', 'scripts', 'notify-bell.py'), run_name='__main__')",
]

[tui]
notifications = ["agent-turn-complete", "approval-requested"]

Observed behavior

• Codex emits the approval-requested event (TUI shows the approval UI).
• The configured notify command runs, but the desktop notification frequently does not appear

because the underlying notification mechanism fails.

Common failures observed under WSL2:

• notify-send fails even when DISPLAY, WAYLAND_DISPLAY, and DBUS_SESSION_BUS_ADDRESS are set.
• Error: Could not connect: Operation not permitted
• Audio backends can also fail (e.g., PulseAudio/pipewire connection refused / operation not permitted).
• Attempting a Windows integration fallback from within this environment via powershell.exe

can fail with vsock-related errors:

• WSL ... ERROR: UtilBindVsockAnyPort: ... socket failed 1

Why this matters

Approval prompts are time-sensitive user interrupts; if the user misses them, Codex becomes blocked.
Notifications are critical for usability in long-running sessions.

Proposal

Add a built-in WSL notification provider that uses a Windows-native toast mechanism instead of
relying only on Linux D-Bus notifications.

Options (in order of preference):

1) Codex-native WSL toast notifications

• Detect WSL (e.g., /proc/version contains microsoft, or env vars like WSL_INTEROP).
• Use a Windows toast mechanism to show notifications for:
• approval-requested (highest priority)
• optionally agent-turn-complete
• Ensure this runs outside any restrictive sandbox so it can actually reach Windows.

2) Run the configured notify hook outside the sandbox by design

• If notify is executed inside a sandbox, it can be prevented from reaching D-Bus/WSLg/Windows.
• Provide a clear safety model since it’s user-configured.

3) Document a supported WSL notification path

• Recommend a known-good bridging tool or configuration.

Acceptance criteria

• With [tui].notifications containing approval-requested, a visible notification reliably appears

on Windows for WSL2 users.

• The solution does not require a functioning Linux D-Bus notification stack inside WSL.
• Failures (if any) are logged in a user-accessible place so the cause is diagnosable.