feat(settings): add rtk compression toggles for local and cloud runs

Two checkboxes in one settings row, both default on: Local (covers local and worktree sessions) and Cloud. Opting out sends POSTHOG_RTK=0 to local sessions via configureProcessEnv, which owns every per-session process env write, and rtk_enabled: false into cloud run creation and resume. Only false is ever sent so the enabled default stays a server-side decision. When Local is enabled but no rtk binary is installed, the row shows a binary-required hint backed by a new agent.rtkStatus query and detectRtkBinary, which reports installation independent of the toggle state a prior session left in the environment.

Author: tatoalo

packages/agent/src/adapters/claude/session/rtk.test.ts

@@ -6,6 +6,7 @@ import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import type { Logger } from "../../../utils/logger";
 import {
   createRtkRewriteHook,
+  detectRtkBinary,
   resolveRtkPrefix,
   rewriteBashForRtk,
 } from "./rtk";
@@ -133,6 +134,50 @@ describe("resolveRtkPrefix", () => {
   });
 });
 
+describe("detectRtkBinary", () => {
+  let dir: string;
+  let binary: string;
+
+  beforeAll(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "rtk-detect-"));
+    binary = path.join(dir, "rtk");
+    fs.writeFileSync(binary, "#!/bin/sh\n");
+  });
+
+  afterAll(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  // The per-session toggle must not hide an installed binary from the
+  // status probe — a prior session leaving POSTHOG_RTK=0 in the process
+  // env would otherwise flap the settings hint.
+  test.each([
+    ["unset", undefined],
+    ["0", "0"],
+    ["false", "false"],
+    ["1", "1"],
+    ["true", "true"],
+  ])("finds the PATH binary when POSTHOG_RTK is %s", (_label, value) => {
+    expect(detectRtkBinary({ POSTHOG_RTK: value, PATH: dir })).toBe(binary);
+  });
+
+  test("reports no binary when rtk is not on PATH", () => {
+    expect(detectRtkBinary({ PATH: "/nonexistent" })).toBeUndefined();
+  });
+
+  test("honors an explicit path override that exists", () => {
+    expect(detectRtkBinary({ POSTHOG_RTK: binary, PATH: "/nonexistent" })).toBe(
+      binary,
+    );
+  });
+
+  test("reports no binary for a broken explicit path, matching the resolver", () => {
+    expect(
+      detectRtkBinary({ POSTHOG_RTK: path.join(dir, "missing"), PATH: dir }),
+    ).toBeUndefined();
+  });
+});
+
 describe("createRtkRewriteHook", () => {
   const logger = {
     info() {},

packages/agent/src/adapters/claude/session/rtk.ts

@@ -129,6 +129,29 @@ export function resolveRtkPrefix(env: NodeJS.ProcessEnv): string | undefined {
   return findOnPath("rtk", env);
 }
 
+/**
+ * Detects the rtk binary a session on this host could use. The on/off flag
+ * values of POSTHOG_RTK ("0"/"false"/"1"/"true"/unset) all mean auto-detect
+ * here, so the answer reflects installation, not the per-session toggle a
+ * previous session may have left in the environment. An explicit binary-path
+ * override mirrors the resolver: honored when it exists, otherwise no binary.
+ */
+export function detectRtkBinary(env: NodeJS.ProcessEnv): string | undefined {
+  const raw = env.POSTHOG_RTK?.trim();
+  const lowered = raw?.toLowerCase();
+  const isFlagValue =
+    !raw || ["0", "false", "1", "true"].includes(lowered ?? "");
+  if (!isFlagValue && raw) {
+    try {
+      if (fs.statSync(raw).isFile()) return raw;
+    } catch {
+      // Explicit path doesn't exist — sessions would get no rtk either.
+    }
+    return undefined;
+  }
+  return findOnPath("rtk", env);
+}
+
 export const createRtkRewriteHook =
   (rtkPrefix: string, logger: Logger): HookCallback =>
   async (input: HookInput, _toolUseID: string | undefined) => {

packages/agent/src/index.ts

@@ -4,4 +4,5 @@ export {
   isMcpToolReadOnly,
   type McpToolMetadata,
 } from "./adapters/claude/mcp/tool-metadata";
+export { detectRtkBinary } from "./adapters/claude/session/rtk";
 export type { PostHogProductId } from "./posthog-products";

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

@@ -277,6 +277,41 @@ describe("PostHogAPIClient", () => {
     expect(body.initial_permission_mode).toBe("plan");
   });
 
+  it("serializes an rtk opt-out as rtk_enabled false on run creation", async () => {
+    const fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ id: "run-123", environment: "cloud" }),
+    });
+    const client = new PostHogAPIClient(
+      "http://localhost:8000",
+      async () => "token",
+      async () => "token",
+      123,
+    );
+
+    (
+      client as unknown as {
+        api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
+      }
+    ).api = {
+      baseUrl: "http://localhost:8000",
+      fetcher: { fetch },
+    };
+
+    await client.createTaskRun("task-123", {
+      environment: "cloud",
+      mode: "interactive",
+      rtkEnabled: false,
+    });
+
+    const request = fetch.mock.calls[0][0] as {
+      overrides: { body: string };
+    };
+    expect(JSON.parse(request.overrides.body)).toMatchObject({
+      rtk_enabled: false,
+    });
+  });
+
   it("omits the permission mode from created task runs without an adapter", async () => {
     const fetch = vi.fn().mockResolvedValue({
       ok: true,

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

@@ -497,6 +497,8 @@ interface CloudRunOptions {
   customImageId?: string;
   prAuthorshipMode?: PrAuthorshipMode;
   autoPublish?: boolean;
+  /** Only false is sent: opts the run out of rtk command-output compression. */
+  rtkEnabled?: boolean;
   runSource?: CloudRunSource;
   signalReportId?: string;
   initialPermissionMode?: ExecutionMode;
@@ -583,6 +585,9 @@ function buildCloudRunRequestBody(
   if (options?.autoPublish) {
     body.auto_publish = options.autoPublish;
   }
+  if (options?.rtkEnabled === false) {
+    body.rtk_enabled = false;
+  }
   if (options?.runSource) {
     body.run_source = options.runSource;
   }

packages/core/src/sessions/sessionService.ts

@@ -299,7 +299,11 @@ export interface SessionServiceDeps {
     setAdapter(taskRunId: string, adapter: Adapter): void;
     removeAdapter(taskRunId: string): void;
   };
-  readonly settings: { customInstructions?: string | null };
+  readonly settings: {
+    customInstructions?: string | null;
+    rtkEnabledLocal?: boolean;
+    rtkEnabledCloud?: boolean;
+  };
   usageLimit: { show: (...args: any[]) => any };
   readonly addDirectoryDialog: { open: boolean };
   taskViewedApi: { markActivity(taskId: string): void };
@@ -1027,11 +1031,12 @@ export class SessionService {
           this.d.log.warn("Failed to verify workspace", { taskId, err });
         });
 
-      const { customInstructions } = this.d.settings;
+      const { customInstructions, rtkEnabledLocal } = this.d.settings;
       const result = await this.d.trpc.agent.reconnect.mutate({
         taskId,
         taskRunId,
         repoPath,
+        rtkEnabled: rtkEnabledLocal,
         apiHost: auth.apiHost,
         projectId: auth.projectId,
         logUrl,
@@ -1362,6 +1367,7 @@ export class SessionService {
       permissionMode: executionMode,
       adapter,
       customInstructions: startCustomInstructions || undefined,
+      rtkEnabled: this.d.settings.rtkEnabledLocal,
       effort: effortLevelSchema.safeParse(reasoningLevel).success
         ? (reasoningLevel as EffortLevel)
         : undefined,
@@ -3087,6 +3093,7 @@ export class SessionService {
             artifactIds.length > 0 ? artifactIds : undefined,
           prAuthorshipMode,
           autoPublish: previousState.auto_publish === true || undefined,
+          rtkEnabled: this.d.settings.rtkEnabledCloud,
           runSource: getCloudRunSource(previousState),
           signalReportId:
             typeof previousState.signal_report_id === "string"

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

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

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

@@ -153,6 +153,7 @@ describe("TaskCreationSaga", () => {
       model: "gpt-5.4",
       reasoningLevel: "high",
       cloudAutoPublish: true,
+      cloudRtkEnabled: false,
     });
 
     expect(result.success).toBe(true);
@@ -170,6 +171,7 @@ describe("TaskCreationSaga", () => {
       sandboxEnvironmentId: undefined,
       prAuthorshipMode: "user",
       autoPublish: true,
+      rtkEnabled: false,
       runSource: "manual",
       signalReportId: undefined,
       initialPermissionMode: "auto",

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

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

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

@@ -29,6 +29,7 @@ export interface PrepareTaskInputOptions {
   channelId?: string;
   customInstructions?: string;
   autoPublishCloudRuns?: boolean;
+  rtkEnabledCloud?: boolean;
   allowNoRepo?: boolean;
 }
 
@@ -64,6 +65,7 @@ export function prepareTaskInput(
     cloudRunSource:
       options.signalReportId && isCloud ? "signal_report" : undefined,
     cloudAutoPublish: isCloud ? options.autoPublishCloudRuns : undefined,
+    cloudRtkEnabled: isCloud ? options.rtkEnabledCloud : undefined,
     signalReportId: options.signalReportId,
     additionalDirectories: isCloud ? undefined : options.additionalDirectories,
     channelContext: options.channelContext,