@posthog/agent 2.3.259 → 2.3.263

package/src/server/agent-server.ts

@@ -1,4 +1,8 @@
-import type { ContentBlock } from "@agentclientprotocol/sdk";
+import type {
+  ContentBlock,
+  RequestPermissionRequest,
+  RequestPermissionResponse,
+} from "@agentclientprotocol/sdk";
 import {
   ClientSideConnection,
   ndJsonStream,
@@ -14,6 +18,7 @@ import {
   type InProcessAcpConnection,
 } from "../adapters/acp-connection";
 import { selectRecentTurns } from "../adapters/claude/session/jsonl-hydration";
+import type { CodeExecutionMode } from "../execution-mode";
 import { PostHogAPIClient } from "../posthog-api";
 import {
   type ConversationTurn,
@@ -157,6 +162,10 @@ interface ActiveSession {
   sseController: SseController | null;
   deviceInfo: DeviceInfo;
   logWriter: SessionLogWriter;
+  /** Current permission mode, tracked for relay decisions */
+  permissionMode: CodeExecutionMode;
+  /** Whether a desktop client has ever connected via SSE during this session */
+  hasDesktopConnected: boolean;
 }
 
 export class AgentServer {
@@ -176,6 +185,15 @@ export class AgentServer {
   // causing a second session to be created and duplicate Slack messages to be sent.
   private initializationPromise: Promise<void> | null = null;
   private pendingEvents: Record<string, unknown>[] = [];
+  private pendingPermissions = new Map<
+    string,
+    {
+      resolve: (response: {
+        outcome: { outcome: "selected"; optionId: string };
+        _meta?: Record<string, unknown>;
+      }) => void;
+    }
+  >();
 
   private detachSseController(controller: SseController): void {
     if (this.session?.sseController === controller) {
@@ -228,6 +246,10 @@ export class AgentServer {
     return payload.mode ?? this.config.mode;
   }
 
+  private getSessionPermissionMode(): CodeExecutionMode {
+    return this.session?.permissionMode ?? "default";
+  }
+
   private createApp(): Hono {
     const app = new Hono();
 
@@ -281,6 +303,7 @@ export class AgentServer {
             await this.initializeSession(payload, sseController);
           } else {
             this.session.sseController = sseController;
+            this.session.hasDesktopConnected = true;
             this.replayPendingEvents();
           }
 
@@ -511,13 +534,9 @@ export class AgentServer {
           prompt,
           ...(this.detectedPrUrl && {
             _meta: {
-              prContext:
-                `IMPORTANT — OVERRIDE PREVIOUS INSTRUCTIONS ABOUT CREATING BRANCHES/PRs.\n` +
-                `You already have an open pull request: ${this.detectedPrUrl}\n` +
-                `You MUST:\n` +
-                `1. Check out the existing PR branch with \`gh pr checkout ${this.detectedPrUrl}\`\n` +
-                `2. Make changes, commit, and push to that branch\n` +
-                `You MUST NOT create a new branch, close the existing PR, or create a new PR.`,
+              // Keep the live-session PR override aligned with the startup
+              // prompt policy so non-Slack runs remain review-first.
+              prContext: this.buildDetectedPrContext(this.detectedPrUrl),
             },
           }),
         });
@@ -579,6 +598,51 @@ export class AgentServer {
         return { closed: true };
       }
 
+      case "posthog/set_config_option":
+      case "set_config_option": {
+        const configId = params.configId as string;
+        const value = params.value as string;
+
+        this.logger.info("Set config option requested", { configId, value });
+
+        const result =
+          await this.session.clientConnection.setSessionConfigOption({
+            sessionId: this.session.acpSessionId,
+            configId,
+            value,
+          });
+
+        return {
+          configOptions: result.configOptions,
+        };
+      }
+
+      case POSTHOG_NOTIFICATIONS.PERMISSION_RESPONSE:
+      case "permission_response": {
+        const requestId = params.requestId as string;
+        const optionId = params.optionId as string;
+        const customInput = params.customInput as string | undefined;
+        const answers = params.answers as Record<string, string> | undefined;
+
+        this.logger.info("Permission response received", {
+          requestId,
+          optionId,
+        });
+
+        const resolved = this.resolvePermission(
+          requestId,
+          optionId,
+          customInput,
+          answers,
+        );
+        if (!resolved) {
+          throw new Error(
+            `No pending permission request found for id: ${requestId}`,
+          );
+        }
+        return { resolved: true };
+      }
+
       default:
         throw new Error(`Unknown method: ${method}`);
     }
@@ -740,6 +804,14 @@ export class AgentServer {
       this.detectedPrUrl = prUrl;
     }
 
+    const runState = preTaskRun?.state as Record<string, unknown> | undefined;
+    // Cloud runs default to bypassPermissions (auto-approve everything).
+    // Only PostHog Code sets initial_permission_mode explicitly (e.g., "plan").
+    const initialPermissionMode: CodeExecutionMode =
+      typeof runState?.initial_permission_mode === "string"
+        ? (runState.initial_permission_mode as CodeExecutionMode)
+        : "bypassPermissions";
+
     const sessionResponse = await clientConnection.newSession({
       cwd: this.config.repositoryPath ?? "/tmp/workspace",
       mcpServers: this.config.mcpServers ?? [],
@@ -749,6 +821,7 @@ export class AgentServer {
         systemPrompt: this.buildSessionSystemPrompt(prUrl),
         allowedDomains: this.config.allowedDomains,
         jsonSchema: preTask?.json_schema ?? null,
+        permissionMode: initialPermissionMode,
         ...(this.config.claudeCode?.plugins?.length && {
           claudeCode: {
             options: {
@@ -774,6 +847,8 @@ export class AgentServer {
       sseController,
       deviceInfo,
       logWriter,
+      permissionMode: initialPermissionMode,
+      hasDesktopConnected: sseController !== null,
     };
 
     this.logger = new Logger({
@@ -791,6 +866,7 @@ export class AgentServer {
     this.logger.info(
       `Agent version: ${this.config.version ?? packageJson.version}`,
     );
+    this.logger.info(`Initial permission mode: ${initialPermissionMode}`);
 
     // Signal in_progress so the UI can start polling for updates
     this.posthogAPI
@@ -1121,13 +1197,53 @@ export class AgentServer {
     return { append: cloudAppend };
   }
 
+  private getCloudInteractionOrigin(): string | undefined {
+    return (
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN ??
+      process.env.CODE_INTERACTION_ORIGIN ??
+      process.env.TWIG_INTERACTION_ORIGIN
+    );
+  }
+
+  /**
+   * Slack-origin cloud runs auto-publish by default. Every other origin is
+   * review-first unless the user explicitly asks, and createPr=false always
+   * disables publishing.
+   */
+  private shouldAutoPublishCloudChanges(): boolean {
+    return (
+      this.getCloudInteractionOrigin() === "slack" &&
+      this.config.createPr !== false
+    );
+  }
+
+  private buildDetectedPrContext(prUrl: string): string {
+    if (!this.shouldAutoPublishCloudChanges()) {
+      return (
+        `An open pull request already exists: ${prUrl}\n` +
+        `Use that PR as context if it is helpful, but stop with local changes ready for review.\n` +
+        `Do NOT create commits, push to the PR branch, update the pull request, create a new branch, or create a new pull request unless the user explicitly asks.`
+      );
+    }
+
+    return (
+      `IMPORTANT — OVERRIDE PREVIOUS INSTRUCTIONS ABOUT CREATING BRANCHES/PRs.\n` +
+      `You already have an open pull request: ${prUrl}\n` +
+      `You MUST:\n` +
+      `1. Check out the existing PR branch with \`gh pr checkout ${prUrl}\`\n` +
+      `2. Make changes, commit, and push to that branch\n` +
+      `You MUST NOT create a new branch, close the existing PR, or create a new PR.`
+    );
+  }
+
   private buildCloudSystemPrompt(prUrl?: string | null): string {
     const taskId = this.config.taskId;
+    const shouldAutoCreatePr = this.shouldAutoPublishCloudChanges();
     const attributionInstructions = `
 ## Attribution
 Do NOT use Claude Code's default attribution (no "Co-Authored-By" trailers, no "Generated with [Claude Code]" lines).
 
-Instead, add the following trailers to EVERY commit message (after a blank line at the end):
+If you create a commit, add the following trailers to the commit message (after a blank line at the end):
   Generated-By: PostHog Code
   Task-Id: ${taskId}
 
@@ -1143,6 +1259,21 @@ EOF
 \`\`\``;
 
     if (prUrl) {
+      if (!shouldAutoCreatePr) {
+        return `
+# Cloud Task Execution
+
+This task already has an open pull request: ${prUrl}
+
+Do the requested work, but stop with local changes ready for review.
+
+Important:
+- Do NOT create new commits, push to the branch, or update the pull request unless the user explicitly asks.
+- Do NOT create a new branch or a new pull request.
+${attributionInstructions}
+`;
+      }
+
       return `
 # Cloud Task Execution
 
@@ -1180,6 +1311,18 @@ Important:
 `;
     }
 
+    if (!shouldAutoCreatePr) {
+      return `
+# Cloud Task Execution
+
+Do the requested work, but stop with local changes ready for review.
+
+Important:
+- Do NOT create a branch, commit, push, or open a pull request unless the user explicitly asks.
+${attributionInstructions}
+`;
+    }
+
     return `
 # Cloud Task Execution
 
@@ -1304,25 +1447,68 @@ ${attributionInstructions}
     });
   }
 
+  private buildSlackQuestionRelayResponse(
+    payload: JwtPayload,
+    toolMeta: Record<string, unknown> | null | undefined,
+  ): RequestPermissionResponse {
+    this.relaySlackQuestion(payload, toolMeta);
+    return {
+      outcome: { outcome: "cancelled" as const },
+      _meta: {
+        message:
+          "This question has been relayed to the Slack thread where this task originated. " +
+          "The user will reply there. Do NOT re-ask the question or pick an answer yourself. " +
+          "Simply let the user know you are waiting for their reply.",
+      },
+    };
+  }
+
+  private shouldBlockPublishPermission(
+    params: RequestPermissionRequest,
+  ): boolean {
+    if (this.config.createPr !== false) {
+      return false;
+    }
+
+    const meta =
+      params.toolCall?._meta &&
+      typeof params.toolCall._meta === "object" &&
+      !Array.isArray(params.toolCall._meta)
+        ? (params.toolCall._meta as Record<string, unknown>)
+        : null;
+    const rawInput =
+      params.toolCall?.rawInput &&
+      typeof params.toolCall.rawInput === "object" &&
+      !Array.isArray(params.toolCall.rawInput)
+        ? (params.toolCall.rawInput as Record<string, unknown>)
+        : null;
+    const toolName = typeof meta?.toolName === "string" ? meta.toolName : null;
+    const command =
+      typeof rawInput?.command === "string" ? rawInput.command : null;
+
+    return Boolean(
+      toolName &&
+        (toolName === "Bash" || toolName.includes("bash")) &&
+        command &&
+        /\bgit\s+push\b|\bgh\s+pr\s+(create|edit|ready|merge)\b/.test(command),
+    );
+  }
+
   private createCloudClient(payload: JwtPayload) {
     const mode = this.getEffectiveMode(payload);
     const interactionOrigin =
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN ??
       process.env.CODE_INTERACTION_ORIGIN ??
       process.env.TWIG_INTERACTION_ORIGIN;
 
     return {
-      requestPermission: async (params: {
-        options: Array<{ kind: string; optionId: string; name?: string }>;
-        toolCall?: {
-          _meta?: Record<string, unknown> | null;
-        };
-      }) => {
-        // Background mode: always auto-approve permissions
-        // Interactive mode: also auto-approve for now (user can monitor via SSE)
-        // Future: interactive mode could pause and wait for user approval via SSE
+      requestPermission: async (
+        params: RequestPermissionRequest,
+      ): Promise<RequestPermissionResponse> => {
         this.logger.debug("Permission request", {
           mode,
           interactionOrigin,
+          kind: params.toolCall?.kind,
           options: params.options,
         });
 
@@ -1332,22 +1518,50 @@ ${attributionInstructions}
         const selectedOptionId =
           allowOption?.optionId ?? params.options[0].optionId;
 
+        const codeToolKind = params.toolCall?._meta?.codeToolKind;
+        const isPlanApproval = params.toolCall?.kind === "switch_mode";
+
+        // Relay questions to Slack when interaction originated there
         if (interactionOrigin === "slack") {
-          const codeToolKind = params.toolCall?._meta?.codeToolKind;
           if (codeToolKind === "question") {
-            this.relaySlackQuestion(payload, params.toolCall?._meta);
-            return {
-              outcome: { outcome: "cancelled" as const },
-              _meta: {
-                message:
-                  "This question has been relayed to the Slack thread where this task originated. " +
-                  "The user will reply there. Do NOT re-ask the question or pick an answer yourself. " +
-                  "Simply let the user know you are waiting for their reply.",
-              },
-            };
+            return this.buildSlackQuestionRelayResponse(
+              payload,
+              params.toolCall?._meta,
+            );
           }
         }
 
+        // Relay permission requests to the desktop app when:
+        // - Questions: always relay (need human answers regardless of mode)
+        // - Plan approvals: always relay
+        // - Edit/bash in "default" mode: relay for manual approval
+        // Other modes auto-approve. No client connected → auto-approve.
+        {
+          const isQuestion = codeToolKind === "question";
+          const sessionPermissionMode = this.getSessionPermissionMode();
+          const needsRelay =
+            isQuestion || isPlanApproval || sessionPermissionMode === "default";
+
+          if (needsRelay && this.session?.hasDesktopConnected) {
+            this.logger.info("Relaying permission to connected client", {
+              kind: params.toolCall?.kind,
+              isQuestion,
+              sessionPermissionMode,
+            });
+            return this.relayPermissionToClient(params);
+          }
+        }
+
+        if (this.shouldBlockPublishPermission(params)) {
+          return {
+            outcome: { outcome: "cancelled" },
+            _meta: {
+              message:
+                "This run is configured to stop before publishing. Do not push commits or create/update pull requests unless the user explicitly asks.",
+            },
+          };
+        }
+
         return {
           outcome: {
             outcome: "selected" as const,
@@ -1365,6 +1579,19 @@ ${attributionInstructions}
         sessionId: string;
         update?: Record<string, unknown>;
       }) => {
+        // Track permission mode changes for relay decisions
+        if (
+          params.update?.sessionUpdate === "current_mode_update" &&
+          typeof params.update?.currentModeId === "string" &&
+          this.session
+        ) {
+          this.session.permissionMode = params.update
+            .currentModeId as CodeExecutionMode;
+          this.logger.info("Permission mode updated", {
+            mode: params.update.currentModeId,
+          });
+        }
+
         // session/update notifications flow through the tapped stream (like local transport)
         // Only handle tree state capture for file changes here
         if (params.update?.sessionUpdate === "tool_call_update") {
@@ -1614,6 +1841,16 @@ ${attributionInstructions}
       this.logger.error("Failed to flush session logs", error);
     }
 
+    // Drain pending permissions before ACP cleanup to avoid deadlocks —
+    // cleanup may await operations that are blocked on a permission response.
+    for (const [, pending] of this.pendingPermissions) {
+      pending.resolve({
+        outcome: { outcome: "selected", optionId: "reject" },
+        _meta: { customInput: "Session is shutting down." },
+      });
+    }
+    this.pendingPermissions.clear();
+
     try {
       await this.session.acpConnection.cleanup();
     } catch (error) {
@@ -1707,4 +1944,55 @@ ${attributionInstructions}
       this.detachSseController(controller);
     }
   }
+
+  /**
+   * Relay a permission request (e.g., plan approval) to the connected desktop
+   * app via SSE and wait for a response via the `/command` endpoint.
+   *
+   * The promise waits indefinitely — if SSE is disconnected, the event is
+   * buffered by broadcastEvent and replayed when the client reconnects. Session
+   * cleanup force-resolves all pending permissions, so there is no leak.
+   */
+  private relayPermissionToClient(params: {
+    options: Array<{ kind: string; optionId: string; name?: string }>;
+    toolCall?: Record<string, unknown> | null;
+  }): Promise<{
+    outcome: { outcome: "selected"; optionId: string };
+    _meta?: Record<string, unknown>;
+  }> {
+    const requestId = crypto.randomUUID();
+
+    this.broadcastEvent({
+      type: "permission_request",
+      requestId,
+      options: params.options,
+      toolCall: params.toolCall,
+    });
+
+    return new Promise((resolve) => {
+      this.pendingPermissions.set(requestId, { resolve });
+    });
+  }
+
+  private resolvePermission(
+    requestId: string,
+    optionId: string,
+    customInput?: string,
+    answers?: Record<string, string>,
+  ): boolean {
+    const pending = this.pendingPermissions.get(requestId);
+    if (!pending) return false;
+
+    this.pendingPermissions.delete(requestId);
+
+    const meta: Record<string, unknown> = {};
+    if (customInput) meta.customInput = customInput;
+    if (answers) meta.answers = answers;
+
+    pending.resolve({
+      outcome: { outcome: "selected" as const, optionId },
+      ...(Object.keys(meta).length > 0 ? { _meta: meta } : {}),
+    });
+    return true;
+  }
 }

package/src/server/bin.ts

@@ -30,6 +30,16 @@ const envSchema = z.object({
 
 const program = new Command();
 
+function parseBooleanOption(
+  raw: string | undefined,
+  flag: string,
+): boolean | undefined {
+  if (raw === undefined) return undefined;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  program.error(`${flag} must be either "true" or "false"`);
+}
+
 function parseJsonOption<S extends z.ZodType>(
   raw: string | undefined,
   schema: S,
@@ -70,6 +80,7 @@ program
     "--mcpServers <json>",
     "MCP servers config as JSON array (ACP McpServer[] format)",
   )
+  .option("--createPr <boolean>", "Whether this run may publish changes")
   .option("--baseBranch <branch>", "Base branch for PR creation")
   .option(
     "--claudeCodeConfig <json>",
@@ -93,6 +104,7 @@ program
     const env = envResult.data;
 
     const mode = options.mode === "background" ? "background" : "interactive";
+    const createPr = parseBooleanOption(options.createPr, "--createPr");
 
     const mcpServers = parseJsonOption(
       options.mcpServers,
@@ -122,6 +134,7 @@ program
       mode,
       taskId: options.taskId,
       runId: options.runId,
+      createPr,
       mcpServers,
       baseBranch: options.baseBranch,
       claudeCode,

package/src/server/question-relay.test.ts

@@ -172,13 +172,13 @@ describe("Question relay", () => {
       { kind: "allow_once", optionId: "allow", name: "Allow" },
     ];
 
-    describe("with CODE_INTERACTION_ORIGIN=slack", () => {
+    describe("with POSTHOG_CODE_INTERACTION_ORIGIN=slack", () => {
       beforeEach(() => {
-        process.env.CODE_INTERACTION_ORIGIN = "slack";
+        process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
       });
 
       afterEach(() => {
-        delete process.env.CODE_INTERACTION_ORIGIN;
+        delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
       });
 
       it("returns cancelled with relay message for question tool", async () => {
@@ -220,9 +220,9 @@ describe("Question relay", () => {
       });
     });
 
-    describe("without CODE_INTERACTION_ORIGIN", () => {
+    describe("without POSTHOG_CODE_INTERACTION_ORIGIN", () => {
       beforeEach(() => {
-        delete process.env.CODE_INTERACTION_ORIGIN;
+        delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
       });
 
       it("auto-approves question tools (no Slack relay)", async () => {
@@ -301,6 +301,35 @@ describe("Question relay", () => {
         expect(appendRawLine).toHaveBeenCalledTimes(2);
       });
     });
+
+    describe("with createPr disabled", () => {
+      it("cancels publish commands", async () => {
+        server = new AgentServer({
+          port,
+          jwtPublicKey: "unused-in-unit-tests",
+          repositoryPath: repo.path,
+          apiUrl: "http://localhost:8000",
+          apiKey: "test-api-key",
+          projectId: 1,
+          mode: "interactive",
+          taskId: "test-task-id",
+          runId: "test-run-id",
+          createPr: false,
+        }) as unknown as TestableAgentServer;
+
+        const client = server.createCloudClient(TEST_PAYLOAD);
+        const result = await client.requestPermission({
+          options: ALLOW_OPTIONS,
+          toolCall: {
+            rawInput: { command: "git push origin my-branch" },
+            _meta: { toolName: "Bash" },
+          },
+        });
+
+        expect(result.outcome.outcome).toBe("cancelled");
+        expect(result._meta?.message).toContain("stop before publishing");
+      });
+    });
   });
 
   describe("relayAgentResponse duplicate suppression", () => {

package/src/server/schemas.test.ts

@@ -132,4 +132,56 @@ describe("validateCommandParams", () => {
 
     expect(result.success).toBe(false);
   });
+
+  it("accepts valid permission_response", () => {
+    const result = validateCommandParams("permission_response", {
+      requestId: "abc-123",
+      optionId: "acceptEdits",
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts permission_response with customInput", () => {
+    const result = validateCommandParams("permission_response", {
+      requestId: "abc-123",
+      optionId: "reject_with_feedback",
+      customInput: "Please change the approach",
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects permission_response without requestId", () => {
+    const result = validateCommandParams("permission_response", {
+      optionId: "acceptEdits",
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects permission_response without optionId", () => {
+    const result = validateCommandParams("permission_response", {
+      requestId: "abc-123",
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts valid set_config_option", () => {
+    const result = validateCommandParams("set_config_option", {
+      configId: "mode",
+      value: "plan",
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects set_config_option without configId", () => {
+    const result = validateCommandParams("set_config_option", {
+      value: "plan",
+    });
+
+    expect(result.success).toBe(false);
+  });
 });

package/src/server/schemas.ts

@@ -48,6 +48,18 @@ export const userMessageParamsSchema = z.object({
   ]),
 });
 
+export const permissionResponseParamsSchema = z.object({
+  requestId: z.string().min(1, "requestId is required"),
+  optionId: z.string().min(1, "optionId is required"),
+  customInput: z.string().optional(),
+  answers: z.record(z.string(), z.string()).optional(),
+});
+
+export const setConfigOptionParamsSchema = z.object({
+  configId: z.string().min(1, "configId is required"),
+  value: z.string().min(1, "value is required"),
+});
+
 export const commandParamsSchemas = {
   user_message: userMessageParamsSchema,
   "posthog/user_message": userMessageParamsSchema,
@@ -55,6 +67,10 @@ export const commandParamsSchemas = {
   "posthog/cancel": z.object({}).optional(),
   close: z.object({}).optional(),
   "posthog/close": z.object({}).optional(),
+  permission_response: permissionResponseParamsSchema,
+  "posthog/permission_response": permissionResponseParamsSchema,
+  set_config_option: setConfigOptionParamsSchema,
+  "posthog/set_config_option": setConfigOptionParamsSchema,
 } as const;
 
 export type CommandMethod = keyof typeof commandParamsSchemas;

package/src/server/types.ts

@@ -18,6 +18,7 @@ export interface AgentServerConfig {
   mode: AgentMode;
   taskId: string;
   runId: string;
+  createPr?: boolean;
   version?: string;
   mcpServers?: RemoteMcpServer[];
   baseBranch?: string;