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.