Let the agent send a push notification on purpose: a notify_user MCP tool

[iamtoled]

Area

apps/server (MCP toolkits), infra/relay (push delivery), apps/mobile

Problem

Today a phone notification only fires when a thread changes phase: waiting for approval, waiting for input, completed, failed (alertAllowedForPhase). The text is fixed too: thread title, then status: project (notificationForActivity).

So the agent has no way to tell me something that matters while it keeps working, and when it does stop, the notification can't say why. Cases we hit every day:

• A long run (migration, backfill, test suite, deploy) reaches a milestone or breaks halfway: "Backfill done, 12,408 rows, starting the check", "Prod deploy failed on step 3, rolling back".
• A watcher thread (PR babysitting, funnel monitoring after a push, a scheduled report) finds something worth a look, but there's nothing to answer, so it shouldn't turn into a question.
• A scheduled report is ready. Today the only signal is a generic "Done" that looks like every other finished turn.

The workarounds are bad: end the turn early to trigger a "completed" push, or ask a fake question to get "waiting for input". Both stop the work and still don't carry the message.

Proposal

An MCP tool in the T3 toolkit, next to html_render, schedule_task and the others:

notify_user({
  title?: string,       // defaults to the thread title
  body: string,         // what happened, short (sanitized/truncated like today's payloads)
  priority?: "normal" | "high",  // high = time-sensitive / breaks through Focus where the OS allows
})

• Sends through the existing relay (APNs/FCM) and desktop/web notifications, with the deep link to the thread, like phase alerts.
• Doesn't change the thread's phase or end the turn: the agent keeps working.
• Shows up in the thread timeline as a small passive card ("Notified you: …"), so the history shows what was sent (close to what [Feature]: Render the pi Notify tool as inline cards #18046 proposes for pi's Notify).
• Respects the user's settings: a new "Notify on agent request" toggle next to notifyOnApproval / notifyOnCompletion, plus per-thread mute (Mute notifications for a single thread #16798) if it lands.
• Rate limit per thread (e.g. a few per hour, deduplicating identical bodies) so a looping agent can't spam the phone.

Why it matters

Phase alerts tell me that a thread stopped. This would tell me what happened, at the moment the agent decides it's worth my attention, which is something only the agent knows. For long-running and scheduled work (where T3 Code is strongest), that's what lets me leave the desk and trust that I'll get pinged when something actually needs me.

Related: #13834 (message preview in agent-activity notifications) improves the existing alerts; this one is about alerts the agent sends itself.

Version or commit

Source inspected at 7ac952c6 (main, 2026-10-14). Used daily on a self-hosted T3 Code server (Linux) with the mobile app.

[nibarAhmed]

this is something that's really needed. Right now it makes the t3 code phone app unusable compared to claude's phone app. The entire point of the phone app is to be able to monitor select threads and be able to get notifications about those threads that you explicitly want them for.

[murtazox04]

+1 on the tool. Some notes from reading the relay at main, since a few details decide where the limits and dedup have to live:

1. It's an event, and the relay only knows how to diff state.
Every alert today comes from comparing the previous and next aggregate per (environmentId, threadId) (attentionTransitionRows, newlyTerminalRows), and a missing baseline is deliberately treated as a replay. A notify_user call doesn't change any of that state, so it can't ride the diff. It needs its own path: an event with a server-generated id that the relay dedupes on (the server will resend after a reconnect), plus a freshness rule like TERMINAL_NOTIFICATION_FRESHNESS_MS. Without that, a milestone queued while the link was down buzzes the phone an hour later, when it's already wrong.

2. Dedup on identical bodies won't catch the cases in the proposal.
Progress messages differ every time ("12,408 rows", "40%", "step 3"). An optional key argument works better: send it as apns-collapse-id on iOS and the notification tag on Android, so "Backfill 60%" replaces "Backfill 40%" on the lock screen instead of stacking. The alert path sets thread-id today, which only groups. Exact repeats of (thread, key, body) can still be dropped.

3. A per-thread limit doesn't bound what the phone gets.
With five watcher threads, "a few per hour per thread" is fifteen-plus pushes an hour. The relay is the only place that sees every environment and thread for a user, and it already has the preferences and devices, so I'd put a per-user budget there across all threads. When the budget is used up, collapse what's left into one summary the same way alertForActivityRows already merges several rows ("3 updates from 2 threads"), rather than dropping them. A per-thread cap on the server is still useful as the first line against a looping agent.

4. priority: "high" needs a user-side cap.
Breaking through Focus means interruption-level: time-sensitive in the aps payload plus the time-sensitive entitlement on the app. The relay doesn't set an interruption level today. If the agent decides this on its own, one bad prompt or loop can break through Focus all night. I'd put it behind its own preference ("Let agents send time-sensitive alerts"), give it a much smaller budget than normal notifies, and quietly downgrade to normal when the budget is spent.

5. Notify + phase change on the same thread = two buzzes for one piece of news.
"Prod deploy failed on step 3, rolling back", then the turn fails 20 seconds later and the failed alert fires too. If the thread sent a notify in the last minute or two, the terminal alert could update it (same collapse id) or go out without sound instead of buzzing again.

The timeline card ("Notified you: …") is a good call, and so is recording when one was suppressed or collapsed. Otherwise "why didn't I get pinged" is impossible to answer.

Disclosure: I maintain Cue (https://github.com/murtazox04/Cue), a self-hosted service that does per-person budgets, collapsing and quiet hours for agent notifications. Mentioning it only for context; everything above is about doing it inside the relay.