fix(agent): preserve narration opt-in for cloud runs

Generated-By: PostHog Code
Task-Id: ac30fada-8c29-4973-a253-08d70be31be6

Author: pauldambra

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

@@ -1,5 +1,8 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { resolveSpokenNarration } from "./session-meta";
+import {
+  resolveCloudSpokenNarration,
+  resolveSpokenNarration,
+} from "./session-meta";
 
 describe("resolveSpokenNarration", () => {
   afterEach(() => {
@@ -48,3 +51,17 @@ describe("resolveSpokenNarration", () => {
     },
   );
 });
+
+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

@@ -20,6 +20,10 @@ interface SpokenNarrationSource {
   spokenNarration?: boolean;
 }
 
+interface SpokenNarrationRunState {
+  spoken_narration?: unknown;
+}
+
 /**
  * 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
@@ -35,3 +39,9 @@ export function resolveSpokenNarration(
 ): boolean {
   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

@@ -1088,19 +1088,14 @@ export class SessionService {
           this.d.log.warn("Failed to verify workspace", { taskId, err });
         });
 
-      const {
-        customInstructions,
-        rtkEnabledLocal,
-        spokenNotifications,
-        spokenNarrationEnabled,
-      } = this.d.settings;
+      const { customInstructions, rtkEnabledLocal, spokenNarrationEnabled } =
+        this.d.settings;
       const result = await this.d.trpc.agent.reconnect.mutate({
         taskId,
         taskRunId,
         repoPath,
         rtkEnabled: rtkEnabledLocal,
-        spokenNarration:
-          spokenNotifications === true && spokenNarrationEnabled === true,
+        spokenNarration: spokenNarrationEnabled === true,
         apiHost: auth.apiHost,
         projectId: auth.projectId,
         logUrl,
@@ -1423,7 +1418,6 @@ export class SessionService {
     const {
       customInstructions: startCustomInstructions,
       rtkEnabledLocal,
-      spokenNotifications,
       spokenNarrationEnabled,
     } = this.d.settings;
     const preferredModel = model ?? this.d.DEFAULT_GATEWAY_MODEL;
@@ -1437,8 +1431,7 @@ export class SessionService {
       adapter,
       customInstructions: startCustomInstructions || undefined,
       rtkEnabled: rtkEnabledLocal,
-      spokenNarration:
-        spokenNotifications === true && spokenNarrationEnabled === true,
+      spokenNarration: spokenNarrationEnabled === true,
       effort: effortLevelSchema.safeParse(reasoningLevel).success
         ? (reasoningLevel as EffortLevel)
         : undefined,
@@ -3415,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);
+    },
+  );
 });