# Agent notifications: when to interrupt the person and when to wait

> An AI agent should interrupt only for a pending decision, a blocker or a result ready to review. Which events to flag, how to rank them and how to cut noise.

*Tags: ai, agents, notifications, ux*

---


> [!info] Quick Definition
> **Agent notifications** are the alerts a system sends to a person while it works. They should interrupt only when there is a pending decision, a blocker or a result ready to review. Everything else belongs in a log the person checks when they want.


## Why is interrupting a design decision?

An [[background-agents|agent working in the background]] can produce dozens of events an hour. If each one becomes a notification, people learn to ignore them all, including the one that matters: the urgent permission request gets lost among a hundred "step completed" alerts.

Nielsen Norman Group distinguishes notifications, which report system events the person did not directly trigger, from indicators, which are passive, and from validations, which respond to what the person just typed. Its article warns that a notification sent regardless of the person's goal will likely be ignored and may even annoy them. It also separates action-required notifications, which are urgent and intrusive, from passive ones, which are less intrusive but easy to miss.

The right question is not "is there anything to report?" but "does the person need to do something now, or in the next few minutes?". If not, the alert is not a notification: it is a record.

## Which agent events deserve an alert?

Claude Code, a real agent tool, works as an example. Its notification event, which can be wired to a hook, distinguishes types by situation. Among them:

| Type | When it fires, according to the documentation |
|---|---|
| `permission_prompt` | Claude needs you to approve a tool use and the prompt has waited about six seconds |
| `idle_prompt` | Claude finished responding about 60 seconds ago and you have not typed since |
| `agent_needs_input` | A background session starts waiting on your input (while agent view is open in a terminal) |
| `agent_completed` | A background session finishes or fails (only while agent view is open) |

That list shows a useful idea for your own product: alerts are grouped by what the person has to do. Three classes cover almost everything:

| Class | Example message | When to interrupt |
|---|---|---|
| **Pending decision** | "I need approval to send the email" | Always, because the work is stopped |
| **Blocker** | "The connection to the payments system failed" | Always, with the cause and the next action |
| **Result ready** | "The migration finished; 118 of 120 tests passed" | Depends on urgency; sometimes a summary at the end is enough |

A normal step, such as "step 3 of 7 completed", belongs to none of these. It goes to the [[long-task-progress|long task progress]] log. Pending decisions are the class that matters most, and their screen is described in [[action-approval|action approval]].

## What should a good notification look like?

A useful notification answers three questions in one line: what happened, what the person needs to do and how long it can wait. An example message: "Waiting for your approval to edit the pricing configuration. The work has been paused for 4 minutes."

Those are three parts that can be designed: the fact, the action requested and the state of the work. A notification that only says "The agent needs your attention" forces people to open the tool to understand what is happening. In Claude Code, the notification arrives with a text (`message`), an optional title and the type, exactly the data needed to build an alert like that.

If it asks for a decision, the response control must be in the alert or one click away. Forcing someone to navigate to a panel to approve something simple is a way of losing the decision.

## How do you prioritize, and when do you alert?

A system needs at least two levels:

- **Urgent.** It blocks the work and needs an answer. It appears immediately, with sound or a visible alert.
- **Informative.** It happens, but the work continues. It accumulates in a summary or in the panel, with no alert. Since passive notices are easy to miss, nothing that requires action should live only there.

Three more decisions refine the system:

1. **Alert based on presence.** Claude Code fires the notification when the person appears to be away from the terminal, and waits a few seconds before alerting about a permission. If the person is looking at the screen, the alert is redundant.
2. **Pick the channel by type.** With a hook, a team can filter by type (a pattern such as `permission_prompt|idle_prompt`) and send only permissions to a desktop alert. By default, Claude Code sends a desktop notification in some terminals and a bell or nothing in others; hooks run alongside the built-in alert without replacing it. The documentation clarifies that notification hooks serve side effects and do not control any decision.
3. **Reduce the causes at the root.** Many interruptions come from permissions requested out of habit. Claude Code's permission modes show the alternative: in manual mode it asks before most edits, commands and network access; `acceptEdits` allows file edits without asking; and `auto` mode uses a classifier that reviews actions before they run and pauses if it blocks three times in a row or twenty in total. Ask less, but define where it must stop.

## What happens when the person does not respond?

A pending decision that nobody answers is a design problem. After a reasonable time, the system should remind, escalate or stop the task explicitly. It should not wait silently for hours while the person assumes the work is moving.

A reminder that says "Thirty minutes ago we were waiting for your answer on the refund; the work is stopped" is better than repeating the first alert. A visible waiting time lets the person decide whether to answer now or later. If the person is unavailable, the design must also define who else can decide; see [[human-in-the-loop|human-in-the-loop]].

## When should you NOT notify?

- When the task lasts seconds and the person is watching it on screen. An extra alert only adds noise.
- When the alert arrives after the action has already happened. That is reporting, not asking for a decision.
- When the text contains sensitive data and may be visible on a locked or shared screen. A neutral alert that leads to a safe place is better.

## Example

Illustrative example: an agent spends the afternoon migrating a billing module and emits 240 events. The first version sends a desktop notification for each one, and the team silences them by the second day.

After the redesign, only three types interrupt: pending permission, blocker and end of task, and only if the person has not looked at the screen for a few seconds. The other events go to a summary at the end. That afternoon the agent asks permission to change a tax value; the alert arrives with the question, the state of the work and an approve button. The decision takes a minute and the rest of the afternoon interrupts nobody.

## Common mistakes

- Notifying every step, until the person silences everything.
- Sending a generic alert without saying what is needed.
- Asking for a decision in a notification that does not allow a response.
- Leaving a pending decision silent for hours.
- Treating an urgent decision and an informative summary the same way.
- Alerting even though the person is looking at the screen.

## Sources

- [Hooks reference: Notification (Claude Code, documentation)](https://code.claude.com/docs/en/hooks)
- [Configure your terminal: terminal bell or notification (Claude Code, documentation)](https://code.claude.com/docs/en/terminal-config)
- [Choose a permission mode (Claude Code, documentation)](https://code.claude.com/docs/en/permission-modes)
- [Indicators, Validations, and Notifications, Nielsen Norman Group](https://www.nngroup.com/articles/indicators-validations-notifications/)


---

Source: https://www.fernandoux.com/en/wiki/ai/agent-notifications/