notify-voice

# Notify Voice Use `chatgpt-voice` as a best-effort side channel. Continue to provide normal commentary and final responses in the originating task. ## Decide whether to notify Notify for: - `input-required`: Notify immediately before asking a blocking question. - `permission-required`: Notify immediately before triggering or requesting approval. - `blocker`: Notify when progress cannot continue without an external change. - `failed`: Notify when an important operation fails and needs attention. - `milestone`: Notify at a meaningful phase boundary in long-running or background work. - `insight`: Notify only for a verified finding that materially changes the conclusion, recommended action, risk, or expected outcome. - `completed`: Notify after meaningful background or long-running work completes. Do not notify for routine tool calls, minor progress, self-recovered errors, unchanged monitoring results, or facts already sent in another notification. ## Check the fast environment gate Before invoking `chatgpt-voice notify`, inspect `CHATGPT_VOICE_NOTIFICATIONS`. If it is explicitly disabled, do not invoke the notification command: ```bash case "${CHATGPT_VOICE_NOTIFICATIONS:-}" in 0|[fF][aA][lL][sS][eE]|[nN][oO]|[oO][fF][fF]|[dD][iI][sS][aA][bB][lL][eE][dD]) exit 0 ;; esac chatgpt-voice notify --kind milestone "The build passed." ``` An unset variable is not a denial. Continue to the CLI, which enforces its persistent notification setting. Values such as `on`, `true`, and `1` explicitly enable notifications and override persistent config. ## Send the notification Use one concise sentence and include the requested action when applicable: ```bash chatgpt-voice notify --kind input-required \ "I need you to choose staging or production before I can continue." ``` Choose priority as follows: - Use `urgent` for input, permission, blockers, and important failures. These kinds already default to urgent and activate Voice. - Use `normal` for milestones and completion when timely interruption is useful. - Use `quiet` for nonurgent insights or updates. Quiet notifications are delivered without activating Voice. Examples: ```bash chatgpt-voice notify --kind milestone \ "The failure is reproduced and isolated to token refresh; I am testing the fix." chatgpt-voice notify --kind insight --priority quiet \ "The latency regression comes from one missing index, not the model upgrade." chatgpt-voice notify --kind permission-required \ "The release is ready; approve the deployment in this task if you want me to proceed." chatgpt-voice notify --kind completed \ "The production health sweep completed with no critical findings." ``` The CLI automatically validates and attaches `CODEX_THREAD_ID` as the source task ID when available. Do not copy, infer, or invent a task ID. Use `--source-thread <id>` only when deliberately relaying for another known task. ## Preserve safety and signal - Send at most one notification per event or state change. - Keep details in the originating task; send only the summary and next action. - Notify before a predictable approval prompt because execution may pause at the prompt. - Do not treat a cross-task or Voice relay as authorization for destructive, external, or permission-gated actions. Require approval in the source task. - Do not notify from the Voice task itself. The CLI also suppresses a notification when its source and target task IDs match. - Treat delivery as best effort. If `chatgpt-voice` is unavailable or fails, continue the main task and do not retry more than once. - Rely on Voxport's default stale-notification expiry. Use `--no-expiry` only when the user explicitly wants an update retained indefinitely. - Let the Voice agent close a transient session after ten seconds without a response. Use `--keep-open` only when the user explicitly wants the session to remain active without that delegated instruction. - Respect the user's configured wake microphone mode. Do not add `--wake-microphone` unless the user explicitly requests a one-delivery override. - Avoid shell-sensitive substitutions in notification text. Pass literal, concise text and use `--` before text that starts with `--`.