fix(agent): make spoken narration strictly opt-in

Spoken narration defaulted on for all cloud runs via resolveSpokenNarration
falling back to isCloudRun(meta). That loaded the `speak` tool and its prompt
instructions — and prompted the agent to call it — on headless runs (Slack
threads, Signals scouts) where nothing can play audio, costing tokens with no
listener and regardless of the feature flag, user setting, or ElevenLabs key.

Make narration strictly opt-in: resolveSpokenNarration now returns true only
when a caller explicitly sets spokenNarration. The desktop is the only client
that can play audio and knows the flag/setting/key, so it computes that boolean
and passes it; everything else stays silent and never loads the tool. Also
require an ElevenLabs key alongside the setting on the desktop start/reconnect
paths, and refresh the now-stale comments.

Generated-By: PostHog Code
Task-Id: 7a65b8a4-b69d-472f-9753-67d59715e332

Author: andrewm4894

packages/agent/src/adapters/local-tools/tools/speak.ts

@@ -48,10 +48,11 @@ export const SPEAK_TOOL_DESCRIPTION =
  * speakers, so it just acknowledges. The desktop renderer observes the
  * surfaced `tool_call` (carrying `text`/`needsUser` in its rawInput) and routes
  * it to the speech queue, exactly like completion/permission notifications are
- * pure side effects off the event stream. Gated on `spokenNarration`: local
- * sessions pass the user's setting at session start, while cloud sessions
- * resolve it to true at the adapter (the sandbox can't know which clients are
- * listening, so cloud emits always and consumers gate playback).
+ * pure side effects off the event stream. Gated on `spokenNarration`, which is
+ * strictly opt-in (see `resolveSpokenNarration`): the desktop passes it true
+ * only when the feature flag, the user's setting, and an ElevenLabs key are all
+ * in place. Headless cloud runs (Slack threads, Signals scouts) never enable
+ * it, so the tool and its instructions never load and never cost tokens there.
  */
 export const speakTool = defineLocalTool({
   name: SPEAK_TOOL_NAME,

packages/agent/src/adapters/session-meta.test.ts

@@ -6,25 +6,18 @@ describe("resolveSpokenNarration", () => {
     vi.unstubAllEnvs();
   });
 
+  // Narration is strictly opt-in: only an explicit `spokenNarration: true`
+  // enables it. Cloud/sandbox runs no longer default on, so headless runs
+  // (Slack threads, Signals scouts) never load the tool or its instructions.
   it.each([
     {
-      name: "explicit true on local",
-      meta: { environment: "local" as const, spokenNarration: true },
+      name: "explicit true",
+      meta: { spokenNarration: true },
       expected: true,
     },
     {
-      name: "explicit false on cloud",
-      meta: { environment: "cloud" as const, spokenNarration: false },
-      expected: false,
-    },
-    {
-      name: "cloud default",
-      meta: { environment: "cloud" as const },
-      expected: true,
-    },
-    {
-      name: "local default",
-      meta: { environment: "local" as const },
+      name: "explicit false",
+      meta: { spokenNarration: false },
       expected: false,
     },
     { name: "no meta", meta: undefined, expected: false },
@@ -35,20 +28,20 @@ describe("resolveSpokenNarration", () => {
   });
 
   it.each([
-    { name: "no meta", meta: undefined, expected: true },
-    { name: "empty meta", meta: {}, expected: true },
+    { name: "no meta", meta: undefined, expected: false },
+    { name: "empty meta", meta: {}, expected: false },
     {
-      name: "explicit false",
-      meta: { spokenNarration: false },
-      expected: false,
+      name: "explicit true",
+      meta: { spokenNarration: true },
+      expected: true,
     },
     {
-      name: "explicit local environment",
-      meta: { environment: "local" as const },
+      name: "explicit false",
+      meta: { spokenNarration: false },
       expected: false,
     },
   ])(
-    "resolves $name to $expected in a sandbox without an environment tag",
+    "resolves $name to $expected in a sandbox (no default-on)",
     ({ meta, expected }) => {
       vi.stubEnv("IS_SANDBOX", "1");
       expect(resolveSpokenNarration(meta)).toBe(expected);

packages/agent/src/adapters/session-meta.ts

@@ -1,5 +1,3 @@
-import { isCloudRun } from "../utils/common";
-
 /** Minimal shape needed to resolve the effective task id from session meta. */
 interface TaskIdSource {
   taskId?: string;
@@ -19,18 +17,21 @@ export function resolveTaskId(
 
 /** Minimal shape needed to resolve spoken narration from session meta. */
 interface SpokenNarrationSource {
-  environment?: "local" | "cloud";
   spokenNarration?: boolean;
 }
 
 /**
- * An explicit setting wins; otherwise cloud runs (including sandbox runs
- * detected via `IS_SANDBOX`) default to on because the sandbox can't know
- * which clients are listening, so consumers gate playback. Local runs stay
- * silent. Shared by the Claude and Codex adapters.
+ * Spoken narration is strictly opt-in: it is on only when a caller explicitly
+ * sets `spokenNarration` true at session start. The desktop is the only client
+ * that can play audio and the only place that knows the feature flag, the
+ * user's setting, and whether an ElevenLabs key is configured — so it computes
+ * that boolean and passes it. Everything else (headless cloud runs like Slack
+ * threads and Signals scouts, sandboxes, local runs without the setting) stays
+ * silent, so the `speak` tool and its instructions never load and never cost
+ * tokens where nothing is listening. Shared by the Claude and Codex adapters.
  */
 export function resolveSpokenNarration(
   meta: SpokenNarrationSource | undefined,
 ): boolean {
-  return meta?.spokenNarration ?? isCloudRun(meta);
+  return meta?.spokenNarration === true;
 }

packages/core/src/sessions/sessionService.ts

@@ -336,6 +336,7 @@ export interface SessionServiceDeps {
     rtkEnabledLocal?: boolean;
     rtkEnabledCloud?: boolean;
     spokenNotifications?: boolean;
+    elevenLabsKeyConfigured?: boolean;
   };
   usageLimit: { show: (...args: any[]) => any };
   readonly addDirectoryDialog: { open: boolean };
@@ -1087,14 +1088,19 @@ export class SessionService {
           this.d.log.warn("Failed to verify workspace", { taskId, err });
         });
 
-      const { customInstructions, rtkEnabledLocal, spokenNotifications } =
-        this.d.settings;
+      const {
+        customInstructions,
+        rtkEnabledLocal,
+        spokenNotifications,
+        elevenLabsKeyConfigured,
+      } = this.d.settings;
       const result = await this.d.trpc.agent.reconnect.mutate({
         taskId,
         taskRunId,
         repoPath,
         rtkEnabled: rtkEnabledLocal,
-        spokenNarration: spokenNotifications === true,
+        spokenNarration:
+          spokenNotifications === true && elevenLabsKeyConfigured === true,
         apiHost: auth.apiHost,
         projectId: auth.projectId,
         logUrl,
@@ -1418,6 +1424,7 @@ export class SessionService {
       customInstructions: startCustomInstructions,
       rtkEnabledLocal,
       spokenNotifications,
+      elevenLabsKeyConfigured,
     } = this.d.settings;
     const preferredModel = model ?? this.d.DEFAULT_GATEWAY_MODEL;
     const result = await this.d.trpc.agent.start.mutate({
@@ -1430,7 +1437,8 @@ export class SessionService {
       adapter,
       customInstructions: startCustomInstructions || undefined,
       rtkEnabled: rtkEnabledLocal,
-      spokenNarration: spokenNotifications === true,
+      spokenNarration:
+        spokenNotifications === true && elevenLabsKeyConfigured === true,
       effort: effortLevelSchema.safeParse(reasoningLevel).success
         ? (reasoningLevel as EffortLevel)
         : undefined,

packages/workspace-server/src/services/agent/schemas.ts

@@ -93,8 +93,9 @@ export const startSessionInput = z.object({
   rtkEnabled: z.boolean().optional(),
   /**
    * The user's spoken-narration setting at session start. Gates the agent's
-   * speak tool and its prompt instructions; when absent the adapter defaults
-   * by environment (cloud on, local off).
+   * speak tool and its prompt instructions. Strictly opt-in: only the desktop
+   * sets it true (feature flag + setting + ElevenLabs key); when absent the
+   * adapter leaves narration off, so headless runs never load the tool.
    */
   spokenNarration: z.boolean().optional(),
 });