@posthog/agent 2.3.388 → 2.3.401

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.388",
+  "version": "2.3.401",
   "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"
@@ -103,8 +107,8 @@
     "typescript": "^5.5.0",
     "vitest": "^2.1.8",
     "@posthog/git": "1.0.0",
-    "@posthog/shared": "1.0.0",
-    "@posthog/enricher": "1.0.0"
+    "@posthog/enricher": "1.0.0",
+    "@posthog/shared": "1.0.0"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.19.0",

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.test.ts

@@ -179,5 +179,6 @@ describe("HandoffCheckpointTracker", () => {
     expect(status).toContain("M  tracked.txt");
     expect(status).toContain(" M unstaged.txt");
     expect(status).toContain("?? untracked.txt");
+    expect(localRepo.exists(".posthog/tmp")).toBe(false);
   });
 });

package/src/handoff-checkpoint.ts

@@ -1,4 +1,11 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rm,
+  rmdir,
+  writeFile,
+} from "node:fs/promises";
 import { join } from "node:path";
 import {
   type GitHandoffBranchDivergence,
@@ -161,6 +168,7 @@ export class HandoffCheckpointTracker {
     } finally {
       await this.removeIfPresent(packPath);
       await this.removeIfPresent(indexPath);
+      await this.removeTmpDirIfEmpty(tmpDir);
     }
   }
 
@@ -364,4 +372,12 @@ export class HandoffCheckpointTracker {
     }
     await rm(filePath, { force: true }).catch(() => {});
   }
+
+  private async removeTmpDirIfEmpty(tmpDir: string): Promise<void> {
+    const entries = await readdir(tmpDir).catch(() => null);
+    if (!entries || entries.length > 0) {
+      return;
+    }
+    await rmdir(tmpDir).catch(() => {});
+  }
 }

package/src/sagas/apply-snapshot-saga.test.ts

@@ -328,6 +328,7 @@ describe("ApplySnapshotSaga", () => {
       });
 
       expect(repo.exists(".posthog/tmp/test-tree-hash.tar.gz")).toBe(false);
+      expect(repo.exists(".posthog/tmp")).toBe(false);
     });
 
     it("cleans up downloaded archive on checkout failure (rollback verification)", async () => {