@posthog/agent 2.3.259 → 2.3.261

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.259",
+  "version": "2.3.261",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -82,8 +82,8 @@
     "tsx": "^4.20.6",
     "typescript": "^5.5.0",
     "vitest": "^2.1.8",
-    "@posthog/shared": "1.0.0",
-    "@posthog/git": "1.0.0"
+    "@posthog/git": "1.0.0",
+    "@posthog/shared": "1.0.0"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.16.1",

package/src/server/agent-server.test.ts

@@ -20,6 +20,7 @@ interface TestableServer {
   detectAndAttachPrUrl(payload: unknown, update: unknown): void;
   detectedPrUrl: string | null;
   buildCloudSystemPrompt(prUrl?: string | null): string;
+  buildDetectedPrContext(prUrl: string): string;
 }
 
 // The Claude Agent SDK has an internal readMessages() loop that rejects with
@@ -380,14 +381,17 @@ describe("AgentServer HTTP Mode", () => {
   });
 
   describe("buildCloudSystemPrompt", () => {
-    it("returns PR-aware prompt when prUrl is provided", () => {
+    it("returns review-first prompt for existing PRs on non-Slack runs", () => {
       const s = createServer();
       const prompt = (s as unknown as TestableServer).buildCloudSystemPrompt(
         "https://github.com/org/repo/pull/1",
       );
-      expect(prompt).toContain("Do NOT create a new branch");
+      expect(prompt).toContain("stop with local changes ready for review");
       expect(prompt).toContain("https://github.com/org/repo/pull/1");
-      expect(prompt).toContain("gh pr checkout");
+      expect(prompt).toContain(
+        "Do NOT create new commits, push to the branch, or update the pull request unless the user explicitly asks.",
+      );
+      expect(prompt).not.toContain("gh pr checkout");
       expect(prompt).not.toContain("Create a draft pull request");
       expect(prompt).toContain("Generated-By: PostHog Code");
       expect(prompt).toContain("Task-Id: test-task-id");
@@ -396,12 +400,13 @@ describe("AgentServer HTTP Mode", () => {
     it("returns default prompt when no prUrl", () => {
       const s = createServer();
       const prompt = (s as unknown as TestableServer).buildCloudSystemPrompt();
-      expect(prompt).toContain("posthog-code/");
-      expect(prompt).toContain("Create a draft pull request");
-      expect(prompt).toContain("gh pr create --draft");
+      expect(prompt).toContain("stop with local changes ready for review");
+      expect(prompt).toContain(
+        "Do NOT create a branch, commit, push, or open a pull request unless the user explicitly asks.",
+      );
       expect(prompt).toContain("Generated-By: PostHog Code");
       expect(prompt).toContain("Task-Id: test-task-id");
-      expect(prompt).toContain("Created with [PostHog Code]");
+      expect(prompt).not.toContain("gh pr create --draft");
     });
 
     it("returns default prompt when prUrl is null", () => {
@@ -409,12 +414,41 @@ describe("AgentServer HTTP Mode", () => {
       const prompt = (s as unknown as TestableServer).buildCloudSystemPrompt(
         null,
       );
+      expect(prompt).toContain("stop with local changes ready for review");
+    });
+
+    it("returns auto-PR prompt for Slack-origin runs", () => {
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
+      const s = createServer();
+      const prompt = (s as unknown as TestableServer).buildCloudSystemPrompt();
       expect(prompt).toContain("posthog-code/");
       expect(prompt).toContain("Create a draft pull request");
       expect(prompt).toContain("gh pr create --draft");
+      expect(prompt).toContain("Generated-By: PostHog Code");
+      expect(prompt).toContain("Task-Id: test-task-id");
+      expect(prompt).toContain("Created with [PostHog Code]");
+      delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
+    });
+
+    it("returns PR-update prompt for existing PRs on Slack-origin runs", () => {
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
+      const s = createServer();
+      const prompt = (s as unknown as TestableServer).buildCloudSystemPrompt(
+        "https://github.com/org/repo/pull/1",
+      );
+      expect(prompt).toContain(
+        "gh pr checkout https://github.com/org/repo/pull/1",
+      );
+      expect(prompt).toContain(
+        "Stage and commit all changes with a clear commit message",
+      );
+      expect(prompt).toContain("Push to the existing PR branch");
+      expect(prompt).not.toContain("Create a draft pull request");
+      delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
     });
 
     it("includes --base flag when baseBranch is configured", () => {
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
       server = new AgentServer({
         port,
         jwtPublicKey: TEST_PUBLIC_KEY,
@@ -433,13 +467,112 @@ describe("AgentServer HTTP Mode", () => {
       expect(prompt).toContain(
         "gh pr create --draft --base add-yolo-to-readme",
       );
+      delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
     });
 
     it("omits --base flag when baseBranch is not configured", () => {
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
       const s = createServer();
       const prompt = (s as unknown as TestableServer).buildCloudSystemPrompt();
       expect(prompt).toContain("gh pr create --draft`");
       expect(prompt).not.toContain("--base");
+      delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
+    });
+
+    it("disables auto-publish for Slack-origin runs when createPr is false", () => {
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
+      server = new AgentServer({
+        port,
+        jwtPublicKey: TEST_PUBLIC_KEY,
+        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,
+      });
+      const prompt = (
+        server as unknown as TestableServer
+      ).buildCloudSystemPrompt();
+      expect(prompt).toContain("stop with local changes ready for review");
+      expect(prompt).not.toContain("gh pr create --draft");
+      delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
+    });
+
+    it("disables auto-publish for existing PRs when createPr is false", () => {
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
+      server = new AgentServer({
+        port,
+        jwtPublicKey: TEST_PUBLIC_KEY,
+        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,
+      });
+      const prompt = (
+        server as unknown as TestableServer
+      ).buildCloudSystemPrompt("https://github.com/org/repo/pull/1");
+      expect(prompt).toContain("stop with local changes ready for review");
+      expect(prompt).not.toContain("gh pr checkout");
+      expect(prompt).not.toContain("Push to the existing PR branch");
+      delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
+    });
+  });
+
+  describe("buildDetectedPrContext", () => {
+    const prUrl = "https://github.com/org/repo/pull/1";
+
+    it("returns review-first PR context for non-Slack runs", () => {
+      const s = createServer();
+      const context = (s as unknown as TestableServer).buildDetectedPrContext(
+        prUrl,
+      );
+      expect(context).toContain("stop with local changes ready for review");
+      expect(context).toContain(
+        "Do NOT create commits, push to the PR branch, update the pull request",
+      );
+      expect(context).not.toContain("gh pr checkout");
+    });
+
+    it("returns auto-update PR context for Slack-origin runs", () => {
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
+      const s = createServer();
+      const context = (s as unknown as TestableServer).buildDetectedPrContext(
+        prUrl,
+      );
+      expect(context).toContain(`gh pr checkout ${prUrl}`);
+      expect(context).toContain(
+        "Make changes, commit, and push to that branch",
+      );
+      delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
+    });
+
+    it("returns review-first PR context when createPr is false", () => {
+      process.env.POSTHOG_CODE_INTERACTION_ORIGIN = "slack";
+      server = new AgentServer({
+        port,
+        jwtPublicKey: TEST_PUBLIC_KEY,
+        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,
+      });
+      const context = (
+        server as unknown as TestableServer
+      ).buildDetectedPrContext(prUrl);
+      expect(context).toContain("stop with local changes ready for review");
+      expect(context).not.toContain("gh pr checkout");
+      delete process.env.POSTHOG_CODE_INTERACTION_ORIGIN;
     });
   });
 });

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,
@@ -511,13 +515,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),
             },
           }),
         });
@@ -1121,13 +1121,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 +1183,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 +1235,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,19 +1371,64 @@ ${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;
-        };
-      }) => {
+      requestPermission: async (
+        params: RequestPermissionRequest,
+      ): Promise<RequestPermissionResponse> => {
         // 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
@@ -1335,19 +1447,23 @@ ${attributionInstructions}
         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,
+            );
           }
         }
 
+        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,

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/types.ts

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