/agent-notifications

name: agent-notifications
description: Send an Agent Notifications desktop notification when the user requests one, attention is needed, or a meaningful milestone warrants an alert during ongoing work.

Use the Agent Notifications plugin's `notify` tool. Installation and notification permissions must already be configured. When using MCP and `notification_status` is available, check that read-only tool for this chat before choosing navigation. Its navigation eligibility reflects configuration and caller context, not proof that the OS will display a banner or open the chat.

Leave routine task/turn completion to automatic lifecycle hooks. Do not call `notify` merely to say done or summarize the final result just before the final response, or relabel that same completion as `progress` or `attention`. A normal "notify me when done" request does not ask for an extra alert on top of the completion hook.

Send a completion alert only when completion hooks are known disabled or unavailable (for example, an explicit MCP-only installation), or the user explicitly requests an additional separate alert. Unknown hook state is not evidence of absence; `notification_status` does not report hook state.

In Codex Desktop, leave native questions (`request_user_input`, `request_user_input_async`) and approval/permission prompts to the app's notification flow. Do not call `notify` for the same event before opening the prompt, while waiting for the response, or after it closes. This also covers permission to call `notify` itself.

Do not relabel the same native prompt as a blocker, milestone, `progress`, or `info` to send an extra alert. A general instruction to notify when attention is needed does not request a duplicate; only an explicit request for an additional separate alert does.

Apply this rule without checking whether a banner appeared. Unknown native notification settings or delivery are not evidence that a fallback alert is needed; `notification_status` does not report them. Separate in-progress milestones and blockers without a native question/approval prompt may still use `notify`.

Notify during ongoing work when an actionable question, a blocker requiring the user's help, or a useful milestone warrants it, including an unresolved blocker when work pauses. If a known hook covers the same question or approval event, do not duplicate it. Continue the task after the MCP call when possible. Include the task name in a short title and make the body useful without exposing credentials or private source text on the lock screen. Do not send an alert for every internal step, poll, or notification result.

Choose `attention` for needed user input, `progress` for an intermediate milestone, and `info` for an informational result. Sending a notification does not mean the task is complete.

Send literal content and a stable, event-specific `request_id`. Reuse that ID and the same payload only when referring to the same notification request. A new event needs a new ID, even when its text is identical. Use a fresh high-entropy identifier such as a UUID for each new event; do not copy the example ID or use recurring labels like `review-choice-1`. When the client supplies no session ID (including informational Claude MCP calls), request IDs and the anonymous rate bucket are shared across those callers. A matching ID from another task can replay or conflict with its request; neither the process nor the working directory isolates it.

{
  "title": "Installer task: input needed",
  "body": "The Windows setup is ready for a test profile. Which profile should I use?",
  "category": "attention",
  "request_id": "492456bb-3be4-440d-9dcd-bb3324e06c48",
  "navigation": "required"
}

When `notification_status.navigation.capability` is `eligible`, prefer `navigation: "required"` for task-related alerts, including informational results. Their category does not disable click navigation. The example above uses this mode, which is also the tool default. Eligibility is checked again when sending; it is not a delivery or click guarantee.

Use `navigation: "none"` when an alert intentionally needs no return to the chat, or navigation is unavailable and an information-only alert still satisfies the request (for example, an MCP-only setup without a desktop route). `best_effort` permits a click target when possible without requiring one. Neither mode guarantees a return to this task. If returning to the chat is required, explain unavailable navigation instead of silently downgrading it, including after a failed `required` call. An older server omitting the navigation status field does not prove navigation is disabled.

The user must have configured the route and consent for `none`; default-on configure passes `--navigation none --allow-unknown-caller true --allow-caller-asserted false` explicitly. The parser does not imply that consent. Caller-asserted context requires separate consent. These flags grant no navigation target and never admit known remote/headless callers. Do not infer locality or session identity from Claude tool metadata. The client supplies the origin: do not put a chat ID, URL, executable, app path, or shell command in tool arguments, or infer a session from the working directory, active window, or MCP process environment.

Interpret the receipt rather than assuming that a successful tool call means delivery:

• `submitted`: the OS accepted the notification; display, click, and visible task selection are not confirmed.
• `suppressed`: respect the user's settings or rate policy. Do not loop or change IDs to bypass suppression.
• `rejected`: explain the actionable reason when relevant. Correcting a known no-effect request is different from retrying an uncertain delivery.
• `unknown`, a lost reply, or a write/connection failure: do not automatically resend, use another backend, or generate a new ID. The original notification may already exist. A new user-requested send may duplicate it; explain th