@posthog/agent 2.3.387 → 2.3.398

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.387",
+  "version": "2.3.398",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -52,6 +52,10 @@
       "types": "./dist/adapters/reasoning-effort.d.ts",
       "import": "./dist/adapters/reasoning-effort.js"
     },
+    "./adapters/claude/mcp/tool-metadata": {
+      "types": "./dist/adapters/claude/mcp/tool-metadata.d.ts",
+      "import": "./dist/adapters/claude/mcp/tool-metadata.js"
+    },
     "./execution-mode": {
       "types": "./dist/execution-mode.d.ts",
       "import": "./dist/execution-mode.js"

package/src/adapters/claude/claude-agent.ts

@@ -72,6 +72,7 @@ import type { EnrichedReadCache } from "./hooks";
 import {
   fetchMcpToolMetadata,
   getConnectedMcpServerNames,
+  setMcpToolApprovalStates,
 } from "./mcp/tool-metadata";
 import { canUseTool } from "./permissions/permission-handlers";
 import { getAvailableSlashCommands } from "./session/commands";
@@ -1091,6 +1092,10 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       : {};
     const systemPrompt = buildSystemPrompt(meta?.systemPrompt);
 
+    if (meta?.mcpToolApprovals) {
+      setMcpToolApprovalStates(meta.mcpToolApprovals);
+    }
+
     // Configure structured output via SDK's native outputFormat
     const outputFormat =
       meta?.jsonSchema && this.options?.onStructuredOutput

package/src/adapters/claude/mcp/tool-metadata.test.ts

@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  clearMcpToolMetadataCache,
+  getMcpToolApprovalState,
+  getMcpToolMetadata,
+  isMcpToolReadOnly,
+  sanitizeMcpServerName,
+  setMcpToolApprovalStates,
+} from "./tool-metadata";
+
+describe("tool-metadata approval states", () => {
+  beforeEach(() => {
+    clearMcpToolMetadataCache();
+  });
+
+  describe("setMcpToolApprovalStates", () => {
+    it("creates entries for unknown tools", () => {
+      setMcpToolApprovalStates({
+        mcp__server__tool1: "approved",
+        mcp__server__tool2: "do_not_use",
+      });
+
+      expect(getMcpToolApprovalState("mcp__server__tool1")).toBe("approved");
+      expect(getMcpToolApprovalState("mcp__server__tool2")).toBe("do_not_use");
+
+      const meta = getMcpToolMetadata("mcp__server__tool1");
+      expect(meta).toBeDefined();
+      expect(meta?.readOnly).toBe(false);
+    });
+
+    it("merges with existing entries preserving readOnly", () => {
+      setMcpToolApprovalStates({
+        mcp__server__ro_tool: "needs_approval",
+      });
+
+      const before = getMcpToolMetadata("mcp__server__ro_tool");
+      expect(before?.readOnly).toBe(false);
+      expect(before?.approvalState).toBe("needs_approval");
+    });
+
+    it("updates approval state on existing entries without overwriting other fields", () => {
+      setMcpToolApprovalStates({
+        mcp__server__tool: "approved",
+      });
+
+      setMcpToolApprovalStates({
+        mcp__server__tool: "do_not_use",
+      });
+
+      expect(getMcpToolApprovalState("mcp__server__tool")).toBe("do_not_use");
+    });
+  });
+
+  describe("getMcpToolApprovalState", () => {
+    it("returns undefined for unknown tools", () => {
+      expect(getMcpToolApprovalState("mcp__server__unknown")).toBeUndefined();
+    });
+
+    it("returns the correct state", () => {
+      setMcpToolApprovalStates({
+        mcp__s__t: "needs_approval",
+      });
+      expect(getMcpToolApprovalState("mcp__s__t")).toBe("needs_approval");
+    });
+  });
+
+  describe("isMcpToolReadOnly with approval states", () => {
+    it("returns false for tools that only have approval state", () => {
+      setMcpToolApprovalStates({
+        mcp__server__tool: "approved",
+      });
+      expect(isMcpToolReadOnly("mcp__server__tool")).toBe(false);
+    });
+  });
+
+  describe("sanitizeMcpServerName", () => {
+    it("passes through simple alphanumeric names", () => {
+      expect(sanitizeMcpServerName("HubSpot")).toBe("HubSpot");
+    });
+
+    it("replaces spaces with underscores", () => {
+      expect(sanitizeMcpServerName("My Server")).toBe("My_Server");
+    });
+
+    it("replaces special characters with underscores", () => {
+      expect(sanitizeMcpServerName("server@v2.0!")).toBe("server_v2_0_");
+    });
+
+    it("preserves hyphens and underscores", () => {
+      expect(sanitizeMcpServerName("my-server_v2")).toBe("my-server_v2");
+    });
+  });
+});

package/src/adapters/claude/mcp/tool-metadata.ts

@@ -1,10 +1,16 @@
 import type { McpServerStatus, Query } from "@anthropic-ai/claude-agent-sdk";
 import { Logger } from "../../../utils/logger";
 
+export type McpToolApprovalState = "approved" | "needs_approval" | "do_not_use";
+
+/** Maps MCP tool keys (e.g. `mcp__server__tool`) to their backend approval state. */
+export type McpToolApprovals = Record<string, McpToolApprovalState>;
+
 export interface McpToolMetadata {
   readOnly: boolean;
   name: string;
   description?: string;
+  approvalState?: McpToolApprovalState;
 }
 
 const mcpToolMetadataCache: Map<string, McpToolMetadata> = new Map();
@@ -12,6 +18,10 @@ const mcpToolMetadataCache: Map<string, McpToolMetadata> = new Map();
 const PENDING_RETRY_INTERVAL_MS = 1_000;
 const PENDING_MAX_RETRIES = 10;
 
+export function sanitizeMcpServerName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
 function buildToolKey(serverName: string, toolName: string): string {
   return `mcp__${serverName}__${toolName}`;
 }
@@ -49,10 +59,12 @@ export async function fetchMcpToolMetadata(
         const toolKey = buildToolKey(server.name, tool.name);
         const readOnly = tool.annotations?.readOnly === true;
 
+        const existing = mcpToolMetadataCache.get(toolKey);
         mcpToolMetadataCache.set(toolKey, {
           readOnly,
           name: tool.name,
           description: tool.description,
+          approvalState: existing?.approvalState,
         });
         if (readOnly) readOnlyCount++;
       }
@@ -104,6 +116,27 @@ export function getConnectedMcpServerNames(): string[] {
   return [...names];
 }
 
+export function getMcpToolApprovalState(
+  toolName: string,
+): McpToolApprovalState | undefined {
+  return mcpToolMetadataCache.get(toolName)?.approvalState;
+}
+
+export function setMcpToolApprovalStates(approvals: McpToolApprovals): void {
+  for (const [toolKey, approvalState] of Object.entries(approvals)) {
+    const existing = mcpToolMetadataCache.get(toolKey);
+    if (existing) {
+      existing.approvalState = approvalState;
+    } else {
+      mcpToolMetadataCache.set(toolKey, {
+        readOnly: false,
+        name: toolKey,
+        approvalState,
+      });
+    }
+  }
+}
+
 export function clearMcpToolMetadataCache(): void {
   mcpToolMetadataCache.clear();
 }

package/src/adapters/claude/permissions/permission-handlers.test.ts

@@ -0,0 +1,165 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  clearMcpToolMetadataCache,
+  setMcpToolApprovalStates,
+} from "../mcp/tool-metadata";
+import { canUseTool } from "./permission-handlers";
+
+function createContext(
+  toolName: string,
+  overrides: Record<string, unknown> = {},
+) {
+  return {
+    session: {
+      permissionMode: "default" as const,
+      settingsManager: {
+        getRepoRoot: vi.fn().mockReturnValue("/repo"),
+      },
+      ...((overrides.session as Record<string, unknown>) ?? {}),
+    },
+    toolName,
+    toolInput: {},
+    toolUseID: "test-tool-use-id",
+    suggestions: undefined,
+    signal: undefined,
+    client: {
+      sessionUpdate: vi.fn().mockResolvedValue(undefined),
+      requestPermission: vi.fn().mockResolvedValue({
+        outcome: { outcome: "selected", optionId: "allow" },
+      }),
+    },
+    sessionId: "test-session",
+    fileContentCache: {},
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+    updateConfigOption: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  } as unknown as Parameters<typeof canUseTool>[0];
+}
+
+describe("canUseTool MCP approval enforcement", () => {
+  beforeEach(() => {
+    clearMcpToolMetadataCache();
+  });
+
+  it("denies do_not_use MCP tools with correct message", async () => {
+    setMcpToolApprovalStates({
+      mcp__server__blocked_tool: "do_not_use",
+    });
+
+    const result = await canUseTool(createContext("mcp__server__blocked_tool"));
+
+    expect(result.behavior).toBe("deny");
+    if (result.behavior === "deny") {
+      expect(result.message).toContain("Settings > MCP Servers");
+      expect(result.message).toContain("PostHog Code");
+      expect(result.interrupt).toBe(false);
+    }
+  });
+
+  it("routes needs_approval MCP tools to permission dialog with descriptive title", async () => {
+    setMcpToolApprovalStates({
+      mcp__HubSpot__search_crm_objects: "needs_approval",
+    });
+
+    const context = createContext("mcp__HubSpot__search_crm_objects");
+    const result = await canUseTool(context);
+
+    expect(result.behavior).toBe("allow");
+    expect(context.client.requestPermission).toHaveBeenCalledWith(
+      expect.objectContaining({
+        toolCall: expect.objectContaining({
+          title: "The agent wants to call search_crm_objects (HubSpot)",
+        }),
+      }),
+    );
+  });
+
+  it("allows approved MCP tools through normal flow", async () => {
+    setMcpToolApprovalStates({
+      mcp__server__approved_tool: "approved",
+    });
+
+    const result = await canUseTool(
+      createContext("mcp__server__approved_tool"),
+    );
+
+    // Approved falls through to isToolAllowedForMode; MCP tools without
+    // readOnly annotation are not auto-allowed, so they go to the default
+    // permission flow which calls requestPermission
+    expect(result.behavior).toBe("allow");
+  });
+
+  it("falls through for MCP tools with no approval state", async () => {
+    const context = createContext("mcp__server__unknown_tool");
+    const result = await canUseTool(context);
+
+    // No approval state → falls through to isToolAllowedForMode → not allowed
+    // in default mode → goes to default permission flow
+    expect(result.behavior).toBe("allow");
+    expect(context.client.requestPermission).toHaveBeenCalled();
+  });
+
+  it("blocks do_not_use even on read-only MCP tools", async () => {
+    setMcpToolApprovalStates({
+      mcp__server__readonly_blocked: "do_not_use",
+    });
+
+    const result = await canUseTool(
+      createContext("mcp__server__readonly_blocked"),
+    );
+
+    expect(result.behavior).toBe("deny");
+    if (result.behavior === "deny") {
+      expect(result.message).toContain("blocked");
+    }
+  });
+
+  it("blocks do_not_use even in bypassPermissions mode", async () => {
+    setMcpToolApprovalStates({
+      mcp__server__blocked_bypass: "do_not_use",
+    });
+
+    const result = await canUseTool(
+      createContext("mcp__server__blocked_bypass", {
+        session: { permissionMode: "bypassPermissions" },
+      }),
+    );
+
+    expect(result.behavior).toBe("deny");
+    if (result.behavior === "deny") {
+      expect(result.message).toContain("blocked");
+    }
+  });
+
+  it("does not affect non-MCP tools", async () => {
+    const result = await canUseTool(createContext("Read"));
+
+    // Read is in the auto-allowed set for default mode
+    expect(result.behavior).toBe("allow");
+  });
+
+  it("emits tool denial notification for do_not_use", async () => {
+    setMcpToolApprovalStates({
+      mcp__server__denied_tool: "do_not_use",
+    });
+
+    const context = createContext("mcp__server__denied_tool");
+    await canUseTool(context);
+
+    expect(context.client.sessionUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: "test-session",
+        update: expect.objectContaining({
+          sessionUpdate: "tool_call_update",
+          toolCallId: "test-tool-use-id",
+          status: "failed",
+        }),
+      }),
+    );
+  });
+});

package/src/adapters/claude/permissions/permission-handlers.ts

@@ -9,6 +9,10 @@ import type {
 import { text } from "../../../utils/acp-content";
 import type { Logger } from "../../../utils/logger";
 import { toolInfoFromToolUse } from "../conversion/tool-use-to-acp";
+import {
+  getMcpToolApprovalState,
+  getMcpToolMetadata,
+} from "../mcp/tool-metadata";
 import {
   getClaudePlansDir,
   getLatestAssistantText,
@@ -408,6 +412,92 @@ async function handleDefaultPermissionFlow(
   }
 }
 
+function parseMcpToolName(toolName: string): {
+  serverName: string;
+  tool: string;
+} {
+  const parts = toolName.split("__");
+  return {
+    serverName: parts[1] ?? toolName,
+    tool: parts.slice(2).join("__") || toolName,
+  };
+}
+
+async function handleMcpApprovalFlow(
+  context: ToolHandlerContext,
+): Promise<ToolPermissionResult> {
+  const { toolName, toolInput, toolUseID, client, sessionId } = context;
+
+  const { serverName, tool: displayTool } = parseMcpToolName(toolName);
+  const metadata = getMcpToolMetadata(toolName);
+  const description = metadata?.description
+    ? `\n\n${metadata.description}`
+    : "";
+
+  const response = await client.requestPermission({
+    options: [
+      { kind: "allow_once", name: "Yes", optionId: "allow" },
+      {
+        kind: "allow_always",
+        name: "Yes, always allow",
+        optionId: "allow_always",
+      },
+      {
+        kind: "reject_once",
+        name: "Type here to tell the agent what to do differently",
+        optionId: "reject",
+        _meta: { customInput: true },
+      },
+    ],
+    sessionId,
+    toolCall: {
+      toolCallId: toolUseID,
+      title: `The agent wants to call ${displayTool} (${serverName})`,
+      kind: "other",
+      content: description
+        ? [{ type: "content" as const, content: text(description) }]
+        : [],
+      rawInput: { ...(toolInput as Record<string, unknown>), toolName },
+    },
+  });
+
+  if (context.signal?.aborted || response.outcome?.outcome === "cancelled") {
+    throw new Error("Tool use aborted");
+  }
+
+  if (
+    response.outcome?.outcome === "selected" &&
+    (response.outcome.optionId === "allow" ||
+      response.outcome.optionId === "allow_always")
+  ) {
+    if (response.outcome.optionId === "allow_always") {
+      return {
+        behavior: "allow",
+        updatedInput: toolInput as Record<string, unknown>,
+        updatedPermissions: [
+          {
+            type: "addRules",
+            rules: [{ toolName }],
+            behavior: "allow",
+            destination: "localSettings",
+          },
+        ],
+      };
+    }
+    return {
+      behavior: "allow",
+      updatedInput: toolInput as Record<string, unknown>,
+    };
+  }
+
+  const feedback = (response._meta?.customInput as string | undefined)?.trim();
+  const message = feedback
+    ? `User refused permission to run tool with feedback: ${feedback}`
+    : "User refused permission to run tool";
+  await emitToolDenial(context, message);
+  return { behavior: "deny", message, interrupt: !feedback };
+}
+
 function handlePlanFileException(
   context: ToolHandlerContext,
 ): ToolPermissionResult | null {
@@ -510,6 +600,21 @@ export async function canUseTool(
     }
   }
 
+  if (toolName.startsWith("mcp__")) {
+    const approvalState = getMcpToolApprovalState(toolName);
+
+    if (approvalState === "do_not_use") {
+      const message =
+        "This tool has been blocked. To re-enable it, go to Settings > MCP Servers in PostHog Code.";
+      await emitToolDenial(context, message);
+      return { behavior: "deny", message, interrupt: false };
+    }
+
+    if (approvalState === "needs_approval") {
+      return handleMcpApprovalFlow(context);
+    }
+  }
+
   if (isToolAllowedForMode(toolName, session.permissionMode)) {
     return {
       behavior: "allow",

package/src/adapters/claude/session/instructions.ts

@@ -16,4 +16,12 @@ Only enter plan mode (EnterPlanMode) when the user is requesting a significant c
 When in doubt, continue executing and incorporate the feedback inline.
 `;
 
-export const APPENDED_INSTRUCTIONS = BRANCH_NAMING + PLAN_MODE;
+const MCP_TOOLS = `
+# MCP Tool Access
+
+If an MCP tool call is explicitly denied with a message, relay that denial message to the user exactly as given. Do NOT suggest checking "Claude Code settings."
+
+If an MCP tool call returns an error, treat it as a normal tool error — troubleshoot, retry, or inform the user about the specific error. Do NOT assume it is a permissions issue and do NOT direct the user to any settings page.
+`;
+
+export const APPENDED_INSTRUCTIONS = BRANCH_NAMING + PLAN_MODE + MCP_TOOLS;

package/src/adapters/claude/types.ts

@@ -10,6 +10,7 @@ import type {
 } from "@anthropic-ai/claude-agent-sdk";
 import type { Pushable } from "../../utils/streams";
 import type { BaseSession } from "../base-acp-agent";
+import type { McpToolApprovals } from "./mcp/tool-metadata";
 import type { SettingsManager } from "./session/settings";
 import type { CodeExecutionMode } from "./tools";
 
@@ -117,6 +118,7 @@ export type NewSessionMeta = {
   /** Model ID to use for this session (e.g. "claude-sonnet-4-6") */
   model?: string;
   jsonSchema?: Record<string, unknown> | null;
+  mcpToolApprovals?: McpToolApprovals;
   claudeCode?: {
     options?: Options;
     emitRawSDKMessages?: boolean | SDKMessageFilter[];

package/src/handoff-checkpoint.ts

@@ -113,7 +113,7 @@ export class HandoffCheckpointTracker {
         divergence: GitHandoffBranchDivergence,
       ) => Promise<boolean>;
     },
-  ): Promise<void> {
+  ): Promise<{ packBytes: number; indexBytes: number; totalBytes: number }> {
     if (!this.apiClient) {
       throw new Error(
         "Cannot apply handoff checkpoint: API client not configured",
@@ -152,6 +152,12 @@ export class HandoffCheckpointTracker {
       });
 
       this.logApplyMetrics(checkpoint, downloads, applyResult.totalBytes);
+
+      return {
+        packBytes: downloads.pack?.rawBytes ?? 0,
+        indexBytes: downloads.index?.rawBytes ?? 0,
+        totalBytes: applyResult.totalBytes,
+      };
     } finally {
       await this.removeIfPresent(packPath);
       await this.removeIfPresent(indexPath);
@@ -207,23 +213,24 @@ export class HandoffCheckpointTracker {
   }
 
   private async uploadArtifacts(specs: UploadArtifactSpec[]): Promise<Uploads> {
-    const uploads = await Promise.all(
-      specs.map(async (spec) => {
-        if (!spec.filePath) {
-          return [spec.key, undefined] as const;
-        }
-        return [
-          spec.key,
-          await this.uploadArtifactFile(
-            spec.filePath,
-            spec.name,
-            spec.contentType,
-          ),
-        ] as const;
-      }),
-    );
+    const results: Array<readonly [ArtifactKey, UploadedArtifact | undefined]> =
+      [];
+    for (const spec of specs) {
+      if (!spec.filePath) {
+        results.push([spec.key, undefined] as const);
+        continue;
+      }
+      results.push([
+        spec.key,
+        await this.uploadArtifactFile(
+          spec.filePath,
+          spec.name,
+          spec.contentType,
+        ),
+      ] as const);
+    }
 
-    return Object.fromEntries(uploads) as Uploads;
+    return Object.fromEntries(results) as Uploads;
   }
 
   private async downloadArtifactToFile(
@@ -241,9 +248,8 @@ export class HandoffCheckpointTracker {
       artifactPath,
     );
     if (!arrayBuffer) {
-      throw new Error(`Failed to download ${label}`);
+      throw new Error(`Failed to download ${label} from ${artifactPath}`);
     }
-
     const base64Content = Buffer.from(arrayBuffer).toString("utf-8");
     const binaryContent = Buffer.from(base64Content, "base64");
     await writeFile(filePath, binaryContent);

package/src/posthog-api.ts

@@ -153,6 +153,14 @@ export class PostHogAPIClient {
     );
   }
 
+  async resumeRunInCloud(taskId: string, runId: string): Promise<TaskRun> {
+    const teamId = this.getTeamId();
+    return this.apiRequest<TaskRun>(
+      `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/resume_in_cloud/`,
+      { method: "POST" },
+    );
+  }
+
   async updateTaskRun(
     taskId: string,
     runId: string,

package/src/resume.ts

@@ -30,8 +30,6 @@ export interface ResumeState {
   conversation: ConversationTurn[];
   latestSnapshot: TreeSnapshotEvent | null;
   latestGitCheckpoint: GitCheckpointEvent | null;
-  /** Whether the tree snapshot was successfully applied (files restored) */
-  snapshotApplied: boolean;
   interrupted: boolean;
   lastDevice?: DeviceInfo;
   logEntryCount: number;
@@ -61,11 +59,7 @@ export interface ResumeConfig {
 /**
  * Resume a task from its persisted log.
  * Returns the rebuilt state for the agent to continue from.
- *
- * Uses Saga pattern internally for atomic operations.
- * Note: snapshotApplied field indicates if files were actually restored -
- * even if latestSnapshot is non-null, files may not have been restored if
- * the snapshot had no archive URL or download/extraction failed.
+ * Snapshot and checkpoint application happens in the agent server after SSE connects.
  */
 export async function resumeFromLog(
   config: ResumeConfig,
@@ -102,7 +96,6 @@ export async function resumeFromLog(
     conversation: result.data.conversation as ConversationTurn[],
     latestSnapshot: result.data.latestSnapshot,
     latestGitCheckpoint: result.data.latestGitCheckpoint,
-    snapshotApplied: result.data.snapshotApplied,
     interrupted: result.data.interrupted,
     lastDevice: result.data.lastDevice,
     logEntryCount: result.data.logEntryCount,
@@ -124,15 +117,31 @@ export function conversationToPromptHistory(
 const RESUME_HISTORY_TOKEN_BUDGET = 50_000;
 const TOOL_RESULT_MAX_CHARS = 2000;
 
+const RESUME_CONTEXT_MARKERS = [
+  "You are resuming a previous conversation",
+  "Here is the conversation history from the",
+  "Continue from where you left off",
+];
+
+function isResumeContextTurn(turn: ConversationTurn): boolean {
+  if (turn.role !== "user") return false;
+  const text = turn.content
+    .filter((b) => b.type === "text")
+    .map((b) => (b as { type: "text"; text: string }).text)
+    .join("");
+  return RESUME_CONTEXT_MARKERS.some((marker) => text.includes(marker));
+}
+
 export function formatConversationForResume(
   conversation: ConversationTurn[],
 ): string {
-  const selected = selectRecentTurns(conversation, RESUME_HISTORY_TOKEN_BUDGET);
+  const filtered = conversation.filter((turn) => !isResumeContextTurn(turn));
+  const selected = selectRecentTurns(filtered, RESUME_HISTORY_TOKEN_BUDGET);
   const parts: string[] = [];
 
-  if (selected.length < conversation.length) {
+  if (selected.length < filtered.length) {
     parts.push(
-      `*(${conversation.length - selected.length} earlier turns omitted)*`,
+      `*(${filtered.length - selected.length} earlier turns omitted)*`,
     );
   }