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

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 and the user's setting are both enabled. 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

@@ -1,30 +1,26 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { resolveSpokenNarration } from "./session-meta";
+import {
+  resolveCloudSpokenNarration,
+  resolveSpokenNarration,
+} from "./session-meta";
 
 describe("resolveSpokenNarration", () => {
   afterEach(() => {
     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,23 +31,37 @@ 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);
     },
   );
 });
+
+describe("resolveCloudSpokenNarration", () => {
+  it.each([
+    { state: { spoken_narration: true }, expected: true },
+    { state: { spoken_narration: false }, expected: false },
+    { state: {}, expected: false },
+    { state: undefined, expected: false },
+  ])(
+    "resolves explicit cloud run opt-in to $expected",
+    ({ state, expected }) => {
+      expect(resolveCloudSpokenNarration(state)).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,31 @@ export function resolveTaskId(
 
 /** Minimal shape needed to resolve spoken narration from session meta. */
 interface SpokenNarrationSource {
-  environment?: "local" | "cloud";
   spokenNarration?: boolean;
 }
 
+interface SpokenNarrationRunState {
+  spoken_narration?: unknown;
+}
+
 /**
- * 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 and the
+ * user's setting, 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;
+}
+
+export function resolveCloudSpokenNarration(
+  state: SpokenNarrationRunState | undefined,
+): boolean {
+  return state?.spoken_narration === true;
 }

packages/agent/src/server/agent-server.ts

@@ -45,6 +45,7 @@ import {
   classifyAgentError,
   isPromptTooLongError,
 } from "../adapters/error-classification";
+import { resolveCloudSpokenNarration } from "../adapters/session-meta";
 import {
   SIGNED_COMMIT_QUALIFIED_TOOL_NAME,
   SIGNED_MERGE_QUALIFIED_TOOL_NAME,
@@ -1497,6 +1498,7 @@ export class AgentServer {
       allowedDomains: this.config.allowedDomains,
       jsonSchema: preTask?.json_schema ?? null,
       permissionMode: initialPermissionMode,
+      spokenNarration: resolveCloudSpokenNarration(runState),
       ...(this.config.baseBranch && { baseBranch: this.config.baseBranch }),
       ...this.buildClaudeCodeSessionMeta(runtimeAdapter),
     };

packages/api-client/src/posthog-client.test.ts

@@ -25,6 +25,7 @@ describe("PostHogAPIClient", () => {
       adapter: "codex",
       model: "gpt-5.4",
       reasoningLevel: "high",
+      spokenNarration: true,
     });
 
     expect(post).toHaveBeenCalledWith(
@@ -37,6 +38,7 @@ describe("PostHogAPIClient", () => {
           runtime_adapter: "codex",
           model: "gpt-5.4",
           reasoning_effort: "high",
+          spoken_narration: true,
         }),
       }),
     );

packages/api-client/src/posthog-client.ts

@@ -613,6 +613,8 @@ interface CloudRunOptions {
   autoPublish?: boolean;
   /** Only false is sent: opts the run out of rtk command-output compression. */
   rtkEnabled?: boolean;
+  /** Explicit desktop opt-in; omitted for headless/background callers. */
+  spokenNarration?: boolean;
   runSource?: CloudRunSource;
   signalReportId?: string;
   initialPermissionMode?: ExecutionMode;
@@ -708,6 +710,9 @@ function buildCloudRunRequestBody(
   if (options?.rtkEnabled === false) {
     body.rtk_enabled = false;
   }
+  if (options?.spokenNarration !== undefined) {
+    body.spoken_narration = options.spokenNarration;
+  }
   if (options?.runSource) {
     body.run_source = options.runSource;
   }

packages/core/src/sessions/sessionService.ts

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

packages/core/src/task-detail/taskCreationApiClient.ts

@@ -19,6 +19,7 @@ export interface CreateTaskRunClientOptions {
   prAuthorshipMode?: PrAuthorshipMode;
   autoPublish?: boolean;
   rtkEnabled?: boolean;
+  spokenNarration?: boolean;
   runSource?: CloudRunSource;
   signalReportId?: string;
   initialPermissionMode?: string;

packages/core/src/task-detail/taskCreationSaga.test.ts

@@ -154,6 +154,7 @@ describe("TaskCreationSaga", () => {
       reasoningLevel: "high",
       cloudAutoPublish: true,
       cloudRtkEnabled: false,
+      spokenNarration: true,
     });
 
     expect(result.success).toBe(true);
@@ -172,6 +173,7 @@ describe("TaskCreationSaga", () => {
       prAuthorshipMode: "user",
       autoPublish: true,
       rtkEnabled: false,
+      spokenNarration: true,
       runSource: "manual",
       signalReportId: undefined,
       initialPermissionMode: "auto",

packages/core/src/task-detail/taskCreationSaga.ts

@@ -404,6 +404,7 @@ export class TaskCreationSaga extends Saga<
             prAuthorshipMode,
             autoPublish: input.cloudAutoPublish,
             rtkEnabled: input.cloudRtkEnabled,
+            spokenNarration: input.spokenNarration,
             runSource: input.cloudRunSource ?? "manual",
             signalReportId: input.signalReportId,
             homeQuickAction: input.homeQuickActionLabel,

packages/core/src/task-detail/taskInput.test.ts

@@ -27,4 +27,19 @@ describe("prepareTaskInput", () => {
     });
     expect(input.customInstructions).toBeUndefined();
   });
+
+  it.each([
+    { workspaceMode: "cloud" as const, expected: true },
+    { workspaceMode: "local" as const, expected: undefined },
+    { workspaceMode: "worktree" as const, expected: undefined },
+  ])(
+    "passes spoken narration through only for cloud (%s)",
+    ({ workspaceMode, expected }) => {
+      const input = prepareTaskInput("do the thing", [], {
+        workspaceMode,
+        spokenNarration: true,
+      });
+      expect(input.spokenNarration).toBe(expected);
+    },
+  );
 });

packages/core/src/task-detail/taskInput.ts

@@ -32,6 +32,7 @@ export interface PrepareTaskInputOptions {
   customInstructions?: string;
   autoPublishCloudRuns?: boolean;
   rtkEnabledCloud?: boolean;
+  spokenNarration?: boolean;
   allowNoRepo?: boolean;
   importedMcpServers?: CloudMcpServerImport[];
   relayedMcpServers?: CloudMcpServerRelayDesignation[];
@@ -70,6 +71,7 @@ export function prepareTaskInput(
       options.signalReportId && isCloud ? "signal_report" : undefined,
     cloudAutoPublish: isCloud ? options.autoPublishCloudRuns : undefined,
     cloudRtkEnabled: isCloud ? options.rtkEnabledCloud : undefined,
+    spokenNarration: isCloud ? options.spokenNarration : undefined,
     signalReportId: options.signalReportId,
     additionalDirectories: isCloud ? undefined : options.additionalDirectories,
     channelContext: options.channelContext,

packages/shared/src/task-creation-domain.ts

@@ -52,6 +52,8 @@ export interface TaskCreationInput {
    * meaningful: it opts the run out of the server-side default (enabled).
    */
   cloudRtkEnabled?: boolean;
+  /** Explicit desktop opt-in for spoken narration in interactive cloud runs. */
+  spokenNarration?: boolean;
   signalReportId?: string;
   additionalDirectories?: string[];
   /**