fix(notifications): mute backstop narration while viewing the task

Consecutive permission requests each spoke "needs your input" even while
the user was staring at the chat clicking Approve: needs_input bypassed
focus routing unconditionally.

Tag each speech request with its source — the agent's intentional speak
tool call vs the deterministic turn/permission backstop. Backstop lines
never play when focus routing says "suppress" (app focused, viewing that
task); agent lines keep current behavior, including the needs_input
focus bypass. A prompt on a task you're not viewing still speaks.

Also adds the enqueueSpeech fake missing from the cloud-notification
test harness since the speak feature landed.

Generated-By: PostHog Code
Task-Id: 6912b099-cb75-4f41-a337-1d2275c4be66

Author: jonmcwest

docs/superpowers/specs/2026-07-02-quiet-backstop-narration-design.md

@@ -0,0 +1,59 @@
+# Quiet backstop narration when viewing the task
+
+Date: 2026-07-02
+Status: approved
+
+## Problem
+
+Every permission request fires the deterministic speech backstop
+(`speakDeterministic(taskRunId, session, "needs_input")` in
+`packages/core/src/sessions/sessionService.ts`). `shouldSpeak` in
+`packages/ui/src/features/notifications/speechRouting.ts` lets every
+`needs_input` line bypass focus routing (`if (kind === "needs_input") return
+true`), and the queue treats them as priority lines that are never coalesced.
+Result: consecutive permission prompts each speak "needs your input" while the
+user is already looking at the chat approving them.
+
+## Design
+
+Distinguish the two speakers sharing the speech pipe and gate them
+differently:
+
+- `source: "agent"` — lines from the agent's `speak` tool call. Keep current
+  behavior: `needs_input` always plays; `done`/`progress` follow
+  `spokenFocusMode`.
+- `source: "backstop"` — deterministic lines ("finished", "needs your input")
+  fired by turn-complete and permission events. Never play when the focus
+  channel is `"suppress"` (app focused and the user is viewing that task).
+  Otherwise follow `spokenFocusMode` as today.
+
+`"suppress"` is per-task: a permission prompt on a task the user is *not*
+viewing (app focused, different tab) still speaks — that is the multi-agent
+case the voice exists for.
+
+## Changes
+
+1. `packages/ui/src/features/notifications/speechRouting.ts` — add
+   `SpeechSource = "agent" | "backstop"`; `shouldSpeak(kind, source, channel,
+   settings)`: backstop lines return `false` when `channel === "suppress"`;
+   agent `needs_input` keeps its unconditional pass.
+2. `packages/ui/src/features/notifications/speechNotifier.ts` — add `source`
+   to `SpeakRequest`, pass through to `shouldSpeak`.
+3. `packages/core/src/sessions/sessionService.ts` — add `source` to the
+   `enqueueSpeech` dep signature; `speakDeterministic` sends `"backstop"`,
+   the speak-tool handler sends `"agent"`.
+4. `packages/ui/src/features/sessions/sessionServiceHost.ts` — type flows
+   through unchanged (verify).
+5. `packages/ui/src/features/notifications/speechRouting.test.ts` — cover the
+   new matrix: backstop suppressed on `"suppress"`, backstop follows focus
+   mode on `"toast"`/`"native"`, agent `needs_input` unaffected.
+
+No settings UI change. No queue changes.
+
+## Rejected alternatives
+
+- Gate all `needs_input` by focus mode (no source flag): also mutes the
+  agent's intentional "Hey Jon" lines.
+- Debounce/dedupe backstop lines in the queue: treats the symptom; focus
+  suppression already kills repeats once the user is present, and serial
+  prompts while away should each speak.

packages/core/src/sessions/cloudTaskUpdateNotifications.test.ts

@@ -179,6 +179,7 @@ function createHarness() {
     sendUpdate: (update: CloudTaskUpdatePayload) => onUpdate?.(update),
     notifyPromptComplete,
     notifyPermissionRequest,
+    enqueueSpeech,
     markActivity,
   };
 }
@@ -255,6 +256,9 @@ describe("cloud task update notifications", () => {
       TASK_ID,
       45_000,
     );
+    expect(harness.enqueueSpeech).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: "done", source: "backstop" }),
+    );
     expect(harness.markActivity).toHaveBeenCalledTimes(1);
   });
 
@@ -271,6 +275,9 @@ describe("cloud task update notifications", () => {
 
     snapshot();
     expect(harness.notifyPermissionRequest).toHaveBeenCalledTimes(1);
+    expect(harness.enqueueSpeech).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: "needs_input", source: "backstop" }),
+    );
 
     snapshot();
     snapshot();

packages/core/src/sessions/sessionService.ts

@@ -40,7 +40,7 @@ import {
   isTerminalStatus,
   type Task,
 } from "@posthog/shared/domain-types";
-import type { SpeechKind } from "../speech/identifiers";
+import type { SpeechKind, SpeechSource } from "../speech/identifiers";
 import {
   isNotification,
   POSTHOG_NOTIFICATIONS,
@@ -288,6 +288,7 @@ export interface SessionServiceDeps {
     taskTitle: string;
     taskId?: string;
     kind: SpeechKind;
+    source: SpeechSource;
     addressByName?: boolean;
   }) => void;
   getIsOnline: () => boolean;
@@ -1960,6 +1961,7 @@ export class SessionService {
       taskTitle: session.taskTitle,
       taskId: session.taskId,
       kind,
+      source: "backstop",
       addressByName: false,
     });
   }
@@ -2116,6 +2118,7 @@ export class SessionService {
                 taskTitle: session.taskTitle,
                 taskId: session.taskId,
                 kind: pending.kind,
+                source: "agent",
                 // Agent-authored line: allowed to address the user by name.
                 addressByName: true,
               });

packages/core/src/speech/identifiers.ts

@@ -1,6 +1,13 @@
 /** Why the agent is speaking; drives priority, greeting, and per-kind gating. */
 export type SpeechKind = "needs_input" | "done" | "progress";
 
+/**
+ * Who authored the line: the agent's intentional `speak` tool call, or the
+ * deterministic backstop fired by turn-complete / permission events. Backstop
+ * lines are suppressed while the user is viewing the task; agent lines are not.
+ */
+export type SpeechSource = "agent" | "backstop";
+
 /** A narration request as it arrives from the agent's `speak` tool call. */
 export interface SpeechRequest {
   /** The message body the agent produced (no task prefix, no user name). */

packages/ui/src/features/notifications/speechNotifier.ts

@@ -11,11 +11,17 @@ import {
   SPEECH_NOTIFY_SETTINGS,
 } from "./identifiers";
 import { routeNotification } from "./routeNotification";
-import { type SpeechKind, shouldSpeak } from "./speechRouting";
+import {
+  type SpeechKind,
+  type SpeechSource,
+  shouldSpeak,
+} from "./speechRouting";
 
 export interface SpeakRequest {
   text: string;
   kind: SpeechKind;
+  /** Agent `speak` tool call, or the deterministic turn/permission backstop. */
+  source: SpeechSource;
   taskTitle: string;
   taskId?: string;
   /** Address the user by name ("Hey <name>,") — agent lines only, not backstop. */
@@ -49,7 +55,10 @@ export class SpeechNotifier {
       notificationTarget: target,
     });
 
-    if (!shouldSpeak(request.kind, channel, this.settings.get())) return;
+    if (
+      !shouldSpeak(request.kind, request.source, channel, this.settings.get())
+    )
+      return;
 
     this.queue.enqueue({
       text: request.text,

packages/ui/src/features/notifications/speechRouting.test.ts

@@ -3,6 +3,7 @@ import type { NotificationChannel } from "./routeNotification";
 import {
   type SpeechGateSettings,
   type SpeechKind,
+  type SpeechSource,
   shouldSpeak,
 } from "./speechRouting";
 
@@ -17,7 +18,10 @@ const base: SpeechGateSettings = {
 describe("shouldSpeak", () => {
   it("is silent when the feature is disabled", () => {
     expect(
-      shouldSpeak("needs_input", "native", { ...base, enabled: false }),
+      shouldSpeak("needs_input", "agent", "native", {
+        ...base,
+        enabled: false,
+      }),
     ).toBe(false);
   });
 
@@ -26,13 +30,15 @@ describe("shouldSpeak", () => {
     ["done", "completion"],
     ["progress", "progress"],
   ])("respects the per-kind toggle for %s", (kind, key) => {
-    expect(shouldSpeak(kind, "native", { ...base, [key]: false })).toBe(false);
+    expect(
+      shouldSpeak(kind, "agent", "native", { ...base, [key]: false }),
+    ).toBe(false);
   });
 
-  it("always speaks needs-input regardless of focus", () => {
+  it("always speaks agent needs-input regardless of focus", () => {
     for (const channel of ["suppress", "toast", "native"] as const) {
       expect(
-        shouldSpeak("needs_input", channel, {
+        shouldSpeak("needs_input", "agent", channel, {
           ...base,
           focusMode: "app_unfocused",
         }),
@@ -44,26 +50,63 @@ describe("shouldSpeak", () => {
     ["suppress", false],
     ["toast", true],
     ["native", true],
-  ])("unviewed_task: channel %s -> %s", (channel, expected) => {
+  ])(
+    "backstop needs-input is silent only over the viewed task: channel %s -> %s",
+    (channel, expected) => {
+      expect(
+        shouldSpeak("needs_input", "backstop", channel, {
+          ...base,
+          focusMode: "app_unfocused",
+        }),
+      ).toBe(expected);
+    },
+  );
+
+  it("backstop done never plays over the viewed task, even in always mode", () => {
     expect(
-      shouldSpeak("done", channel, { ...base, focusMode: "unviewed_task" }),
-    ).toBe(expected);
+      shouldSpeak("done", "backstop", "suppress", {
+        ...base,
+        focusMode: "always",
+      }),
+    ).toBe(false);
   });
 
+  it.each<[SpeechSource, NotificationChannel, boolean]>([
+    ["agent", "suppress", false],
+    ["agent", "toast", true],
+    ["agent", "native", true],
+    ["backstop", "suppress", false],
+    ["backstop", "toast", true],
+    ["backstop", "native", true],
+  ])(
+    "unviewed_task: %s done on channel %s -> %s",
+    (source, channel, expected) => {
+      expect(
+        shouldSpeak("done", source, channel, {
+          ...base,
+          focusMode: "unviewed_task",
+        }),
+      ).toBe(expected);
+    },
+  );
+
   it.each<[NotificationChannel, boolean]>([
     ["suppress", false],
     ["toast", false],
     ["native", true],
   ])("app_unfocused: channel %s -> %s", (channel, expected) => {
     expect(
-      shouldSpeak("done", channel, { ...base, focusMode: "app_unfocused" }),
+      shouldSpeak("done", "agent", channel, {
+        ...base,
+        focusMode: "app_unfocused",
+      }),
     ).toBe(expected);
   });
 
-  it("always mode speaks on every channel", () => {
+  it("always mode speaks agent lines on every channel", () => {
     for (const channel of ["suppress", "toast", "native"] as const) {
       expect(
-        shouldSpeak("done", channel, { ...base, focusMode: "always" }),
+        shouldSpeak("done", "agent", channel, { ...base, focusMode: "always" }),
       ).toBe(true);
     }
   });

packages/ui/src/features/notifications/speechRouting.ts

@@ -1,8 +1,11 @@
-import type { SpeechKind } from "@posthog/core/speech/identifiers";
+import type {
+  SpeechKind,
+  SpeechSource,
+} from "@posthog/core/speech/identifiers";
 import type { SpokenFocusMode } from "@posthog/ui/features/settings/settingsStore";
 import type { NotificationChannel } from "./routeNotification";
 
-export type { SpeechKind };
+export type { SpeechKind, SpeechSource };
 
 export interface SpeechGateSettings {
   enabled: boolean;
@@ -13,15 +16,19 @@ export interface SpeechGateSettings {
 }
 
 /**
- * Whether a spoken line should play, given the focus-routing channel (from
- * routeNotification) and the user's spoken-notification settings. Pure so the
- * policy is exhaustively unit-tested without the DI graph.
+ * Whether a spoken line should play, given who authored it, the focus-routing
+ * channel (from routeNotification) and the user's spoken-notification
+ * settings. Pure so the policy is exhaustively unit-tested without the DI
+ * graph.
  *
- * needs-input lines ignore focus mode entirely — a blocker is the whole point
- * of the feature, so it's never suppressed for being on screen.
+ * Agent needs-input lines ignore focus mode entirely — a blocker is the whole
+ * point of the feature. Backstop lines never play over the task the user is
+ * already viewing: the permission dialog (or finished turn) is on screen, and
+ * consecutive permission prompts would otherwise narrate every approval click.
  */
 export function shouldSpeak(
   kind: SpeechKind,
+  source: SpeechSource,
   channel: NotificationChannel,
   s: SpeechGateSettings,
 ): boolean {
@@ -35,6 +42,8 @@ export function shouldSpeak(
         : s.progress;
   if (!kindEnabled) return false;
 
+  if (source === "backstop" && channel === "suppress") return false;
+
   if (kind === "needs_input") return true;
 
   switch (s.focusMode) {