@posthog/agent 2.3.507 → 2.3.510

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.507",
+  "version": "2.3.510",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {

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

@@ -103,6 +103,7 @@ import type {
   SDKMessageFilter,
   Session,
   ToolUseCache,
+  ToolUseStreamCache,
 } from "./types";
 
 const SESSION_VALIDATION_TIMEOUT_MS = 30_000;
@@ -145,6 +146,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
   readonly adapterName = "claude";
   declare session: Session;
   toolUseCache: ToolUseCache;
+  toolUseStreamCache: ToolUseStreamCache;
   backgroundTerminals: { [key: string]: BackgroundTerminal } = {};
   clientCapabilities?: ClientCapabilities;
   private options?: ClaudeAcpAgentOptions;
@@ -155,6 +157,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     super(client);
     this.options = options;
     this.toolUseCache = {};
+    this.toolUseStreamCache = new Map();
     this.logger = new Logger({ debug: true, prefix: "[ClaudeAcpAgent]" });
     this.enrichment = createEnrichment(options?.posthogApiConfig, this.logger);
   }
@@ -403,6 +406,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       sessionId: params.sessionId,
       client: this.client,
       toolUseCache: this.toolUseCache,
+      toolUseStreamCache: this.toolUseStreamCache,
       fileContentCache: this.fileContentCache,
       enrichedReadCache: this.enrichedReadCache,
       logger: this.logger,
@@ -768,6 +772,11 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       }
       throw error;
     } finally {
+      // Drop any leftover streaming-input buffers. Normally cleared per index
+      // on `content_block_stop`, but a cancelled or errored turn may leave
+      // entries behind; without this they'd carry over into the next turn
+      // and collide with new content-block indices.
+      this.toolUseStreamCache.clear();
       if (!handedOff) {
         this.session.promptRunning = false;
         // Resolve all remaining pending prompts so no callers get stuck.
@@ -1528,6 +1537,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
         sessionId,
         client: this.client,
         toolUseCache: this.toolUseCache,
+        toolUseStreamCache: this.toolUseStreamCache,
         fileContentCache: this.fileContentCache,
         enrichedReadCache: this.enrichedReadCache,
         logger: this.logger,

package/src/adapters/claude/conversion/sdk-to-acp.ts

@@ -21,8 +21,14 @@ import { POSTHOG_NOTIFICATIONS } from "@/acp-extensions";
 import { image, text } from "../../../utils/acp-content";
 import { unreachable } from "../../../utils/common";
 import type { Logger } from "../../../utils/logger";
+import { tryParsePartialJson } from "../../../utils/partial-json";
 import { type EnrichedReadCache, registerHookCallback } from "../hooks";
-import type { Session, ToolUpdateMeta, ToolUseCache } from "../types";
+import type {
+  Session,
+  ToolUpdateMeta,
+  ToolUseCache,
+  ToolUseStreamCache,
+} from "../types";
 import {
   type ClaudePlanEntry,
   planEntries,
@@ -67,6 +73,8 @@ export interface MessageHandlerContext {
   sessionId: string;
   client: AgentSideConnection;
   toolUseCache: ToolUseCache;
+  /** Buffers `input_json_delta` partial JSON per content-block index. */
+  toolUseStreamCache: ToolUseStreamCache;
   fileContentCache: { [key: string]: string };
   enrichedReadCache?: EnrichedReadCache;
   logger: Logger;
@@ -496,6 +504,7 @@ function streamEventToAcpNotifications(
   message: SDKPartialAssistantMessage,
   sessionId: string,
   toolUseCache: ToolUseCache,
+  toolUseStreamCache: ToolUseStreamCache,
   fileContentCache: { [key: string]: string },
   client: AgentSideConnection,
   logger: Logger,
@@ -507,9 +516,16 @@ function streamEventToAcpNotifications(
 ): SessionNotification[] {
   const event = message.event;
   switch (event.type) {
-    case "content_block_start":
+    case "content_block_start": {
+      const block = event.content_block;
+      if (block.type === "tool_use" || block.type === "mcp_tool_use") {
+        toolUseStreamCache.set(event.index, {
+          toolUseId: block.id,
+          partialJson: "",
+        });
+      }
       return toAcpNotifications(
-        [event.content_block],
+        [block],
         "assistant",
         sessionId,
         toolUseCache,
@@ -523,7 +539,16 @@ function streamEventToAcpNotifications(
         undefined,
         enrichedReadCache,
       );
-    case "content_block_delta":
+    }
+    case "content_block_delta": {
+      if (event.delta.type === "input_json_delta") {
+        return inputJsonDeltaToAcpNotifications(
+          event.index,
+          event.delta.partial_json,
+          sessionId,
+          toolUseStreamCache,
+        );
+      }
       return toAcpNotifications(
         [event.delta],
         "assistant",
@@ -539,10 +564,13 @@ function streamEventToAcpNotifications(
         undefined,
         enrichedReadCache,
       );
+    }
+    case "content_block_stop":
+      toolUseStreamCache.delete(event.index);
+      return [];
     case "message_start":
     case "message_delta":
     case "message_stop":
-    case "content_block_stop":
       return [];
 
     default:
@@ -551,6 +579,31 @@ function streamEventToAcpNotifications(
   }
 }
 
+function inputJsonDeltaToAcpNotifications(
+  index: number,
+  partialJson: string,
+  sessionId: string,
+  toolUseStreamCache: ToolUseStreamCache,
+): SessionNotification[] {
+  const entry = toolUseStreamCache.get(index);
+  if (!entry) return [];
+  entry.partialJson += partialJson;
+
+  const parsed = tryParsePartialJson(entry.partialJson);
+  if (!parsed || typeof parsed !== "object") return [];
+
+  return [
+    {
+      sessionId,
+      update: {
+        sessionUpdate: "tool_call_update" as const,
+        toolCallId: entry.toolUseId,
+        rawInput: parsed as Record<string, unknown>,
+      },
+    },
+  ];
+}
+
 export async function handleSystemMessage(
   message: Extract<SDKMessage, { type: "system" }>,
   context: MessageHandlerContext,
@@ -743,13 +796,21 @@ export async function handleStreamEvent(
   message: SDKPartialAssistantMessage,
   context: MessageHandlerContext,
 ): Promise<void> {
-  const { sessionId, client, toolUseCache, fileContentCache, logger } = context;
+  const {
+    sessionId,
+    client,
+    toolUseCache,
+    toolUseStreamCache,
+    fileContentCache,
+    logger,
+  } = context;
   const parentToolCallId = message.parent_tool_use_id ?? undefined;
 
   for (const notification of streamEventToAcpNotifications(
     message,
     sessionId,
     toolUseCache,
+    toolUseStreamCache,
     fileContentCache,
     client,
     logger,

package/src/adapters/claude/hooks.test.ts

@@ -7,7 +7,16 @@ vi.mock("../../enrichment/file-enricher", () => ({
   enrichFileForAgent: enrichFileMock,
 }));
 
-import { createReadEnrichmentHook, type EnrichedReadCache } from "./hooks";
+import { Logger } from "../../utils/logger";
+import {
+  createPreToolUseHook,
+  createReadEnrichmentHook,
+  type EnrichedReadCache,
+} from "./hooks";
+import type {
+  PermissionCheckResult,
+  SettingsManager,
+} from "./session/settings";
 
 const stubDeps = {} as FileEnrichmentDeps;
 
@@ -187,3 +196,118 @@ describe("createReadEnrichmentHook", () => {
     expect(content).toBe("foo");
   });
 });
+
+function buildPreToolUseHookInput(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+): HookInput {
+  return {
+    session_id: "test-session",
+    transcript_path: "/tmp/transcript",
+    cwd: "/tmp",
+    hook_event_name: "PreToolUse",
+    tool_name: toolName,
+    tool_use_id: "toolu_1",
+    tool_input: toolInput,
+  } as HookInput;
+}
+
+function buildSettingsManagerStub(
+  result: PermissionCheckResult,
+): SettingsManager {
+  return {
+    checkPermission: () => result,
+  } as unknown as SettingsManager;
+}
+
+describe("createPreToolUseHook", () => {
+  const logger = new Logger({ debug: false });
+
+  test("defers destructive PostHog exec sub-tool to canUseTool via ask", async () => {
+    const settingsManager = buildSettingsManagerStub({
+      decision: "allow",
+      rule: "mcp__posthog__exec",
+      source: "allow",
+    });
+    const hook = createPreToolUseHook(settingsManager, logger);
+    const result = await hook(
+      buildPreToolUseHookInput("mcp__posthog__exec", {
+        command: 'call dashboard-update {"id": 1, "name": "x"}',
+      }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(result).toMatchObject({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "ask",
+      },
+    });
+  });
+
+  test("allows non-destructive PostHog exec sub-tool via settings rule", async () => {
+    const settingsManager = buildSettingsManagerStub({
+      decision: "allow",
+      rule: "mcp__posthog__exec",
+      source: "allow",
+    });
+    const hook = createPreToolUseHook(settingsManager, logger);
+    const result = await hook(
+      buildPreToolUseHookInput("mcp__posthog__exec", {
+        command: 'call experiment-get {"id": 1}',
+      }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(result).toEqual({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "allow",
+        permissionDecisionReason:
+          "Allowed by settings rule: mcp__posthog__exec",
+      },
+    });
+  });
+
+  test("allows non-PostHog tool via settings rule unchanged", async () => {
+    const settingsManager = buildSettingsManagerStub({
+      decision: "allow",
+      rule: "Bash(ls:*)",
+      source: "allow",
+    });
+    const hook = createPreToolUseHook(settingsManager, logger);
+    const result = await hook(
+      buildPreToolUseHookInput("Bash", { command: "ls -la" }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(result).toMatchObject({
+      hookSpecificOutput: { permissionDecision: "allow" },
+    });
+  });
+
+  test("defers when destructive rule is partial-update", async () => {
+    const settingsManager = buildSettingsManagerStub({
+      decision: "allow",
+      rule: "mcp__posthog__exec",
+      source: "allow",
+    });
+    const hook = createPreToolUseHook(settingsManager, logger);
+    const result = await hook(
+      buildPreToolUseHookInput("mcp__posthog__exec", {
+        command: 'call cohorts-partial-update {"id": 1}',
+      }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(result).toMatchObject({
+      hookSpecificOutput: { permissionDecision: "ask" },
+    });
+  });
+});

package/src/adapters/claude/hooks.ts

@@ -5,6 +5,11 @@ import {
 } from "../../enrichment/file-enricher";
 import type { Logger } from "../../utils/logger";
 import { stripCatLineNumbers } from "./conversion/sdk-to-acp";
+import {
+  extractPostHogSubTool,
+  isPostHogDestructiveSubTool,
+  isPostHogExecTool,
+} from "./permissions/posthog-exec-gate";
 import type { SettingsManager } from "./session/settings";
 import type { CodeExecutionMode } from "./tools";
 
@@ -237,6 +242,25 @@ export const createPreToolUseHook =
       );
     }
 
+    // Defer destructive PostHog exec sub-tools to canUseTool so the
+    // sub-tool gate can re-prompt. Returning `{ continue: true }` is
+    // not enough — the SDK then falls back to its default permission
+    // flow which re-checks the same allow rule. We must force "ask"
+    // so the SDK invokes canUseTool.
+    if (permissionCheck.decision === "allow" && isPostHogExecTool(toolName)) {
+      const subTool = extractPostHogSubTool(toolInput);
+      if (subTool && isPostHogDestructiveSubTool(subTool)) {
+        return {
+          continue: true,
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse" as const,
+            permissionDecision: "ask" as const,
+            permissionDecisionReason: `Destructive PostHog sub-tool '${subTool}' requires explicit approval`,
+          },
+        };
+      }
+    }
+
     switch (permissionCheck.decision) {
       case "allow":
         return {

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

@@ -143,6 +143,158 @@ describe("canUseTool MCP approval enforcement", () => {
     expect(result.behavior).toBe("allow");
   });
 
+  it("bypasses the PostHog exec gate in auto mode", async () => {
+    setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
+    const hasApproval = vi.fn().mockReturnValue(false);
+    const addApproval = vi.fn().mockResolvedValue(undefined);
+
+    const context = createContext("mcp__posthog__exec", {
+      toolInput: { command: "call experiment-update {}" },
+      session: {
+        permissionMode: "auto",
+        settingsManager: {
+          getRepoRoot: vi.fn().mockReturnValue("/repo"),
+          hasPostHogExecApproval: hasApproval,
+          addPostHogExecApproval: addApproval,
+        },
+      },
+    });
+    const result = await canUseTool(context);
+
+    expect(result.behavior).toBe("allow");
+    expect(context.client.requestPermission).not.toHaveBeenCalled();
+    expect(hasApproval).not.toHaveBeenCalled();
+    expect(addApproval).not.toHaveBeenCalled();
+  });
+
+  it("bypasses the PostHog exec gate in bypassPermissions mode", async () => {
+    setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
+
+    const context = createContext("mcp__posthog__exec", {
+      toolInput: { command: "call feature-flag-delete {}" },
+      session: {
+        permissionMode: "bypassPermissions",
+        settingsManager: {
+          getRepoRoot: vi.fn().mockReturnValue("/repo"),
+          hasPostHogExecApproval: vi.fn().mockReturnValue(false),
+          addPostHogExecApproval: vi.fn(),
+        },
+      },
+    });
+    const result = await canUseTool(context);
+
+    expect(result.behavior).toBe("allow");
+    expect(context.client.requestPermission).not.toHaveBeenCalled();
+  });
+
+  it("short-circuits when a PostHog exec sub-tool was previously approved", async () => {
+    setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
+
+    const context = createContext("mcp__posthog__exec", {
+      toolInput: { command: "call experiment-update {}" },
+      session: {
+        permissionMode: "default",
+        settingsManager: {
+          getRepoRoot: vi.fn().mockReturnValue("/repo"),
+          hasPostHogExecApproval: vi
+            .fn()
+            .mockImplementation((s: string) => s === "experiment-update"),
+          addPostHogExecApproval: vi.fn(),
+        },
+      },
+    });
+    const result = await canUseTool(context);
+
+    expect(result.behavior).toBe("allow");
+    expect(context.client.requestPermission).not.toHaveBeenCalled();
+  });
+
+  it("prompts for an unapproved destructive PostHog sub-tool and persists on allow_always", async () => {
+    setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
+    const addApproval = vi.fn().mockResolvedValue(undefined);
+
+    const context = createContext("mcp__posthog__exec", {
+      toolInput: { command: "call notebooks-destroy {}" },
+      session: {
+        permissionMode: "default",
+        settingsManager: {
+          getRepoRoot: vi.fn().mockReturnValue("/repo"),
+          hasPostHogExecApproval: vi.fn().mockReturnValue(false),
+          addPostHogExecApproval: addApproval,
+        },
+      },
+      client: {
+        sessionUpdate: vi.fn().mockResolvedValue(undefined),
+        requestPermission: vi.fn().mockResolvedValue({
+          outcome: { outcome: "selected", optionId: "allow_always" },
+        }),
+      },
+    });
+    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 run `notebooks-destroy` on PostHog",
+        }),
+      }),
+    );
+    expect(addApproval).toHaveBeenCalledWith("notebooks-destroy");
+  });
+
+  it("prompts but does not persist on allow_once", async () => {
+    setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
+    const addApproval = vi.fn();
+
+    const context = createContext("mcp__posthog__exec", {
+      toolInput: { command: "call experiment-delete {}" },
+      session: {
+        permissionMode: "default",
+        settingsManager: {
+          getRepoRoot: vi.fn().mockReturnValue("/repo"),
+          hasPostHogExecApproval: vi.fn().mockReturnValue(false),
+          addPostHogExecApproval: addApproval,
+        },
+      },
+      client: {
+        sessionUpdate: vi.fn().mockResolvedValue(undefined),
+        requestPermission: vi.fn().mockResolvedValue({
+          outcome: { outcome: "selected", optionId: "allow" },
+        }),
+      },
+    });
+    const result = await canUseTool(context);
+
+    expect(result.behavior).toBe("allow");
+    expect(addApproval).not.toHaveBeenCalled();
+  });
+
+  it("does not gate non-destructive PostHog sub-tools", async () => {
+    setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
+    const addApproval = vi.fn();
+
+    const context = createContext("mcp__posthog__exec", {
+      toolInput: { command: "call experiment-get-all {}" },
+      session: {
+        permissionMode: "default",
+        settingsManager: {
+          getRepoRoot: vi.fn().mockReturnValue("/repo"),
+          hasPostHogExecApproval: vi.fn().mockReturnValue(false),
+          addPostHogExecApproval: addApproval,
+        },
+      },
+    });
+    const result = await canUseTool(context);
+
+    // Non-destructive sub-tool falls through the gate. With approved MCP state
+    // and non-read-only tool metadata, it hits the default permission flow,
+    // which auto-allows via our mocked requestPermission. The gate must not
+    // have prompted with a PostHog-specific title, and must not have persisted.
+    expect(result.behavior).toBe("allow");
+    expect(addApproval).not.toHaveBeenCalled();
+  });
+
   it("emits tool denial notification for do_not_use", async () => {
     setMcpToolApprovalStates({
       mcp__server__denied_tool: "do_not_use",

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

@@ -31,6 +31,11 @@ import {
   buildExitPlanModePermissionOptions,
   buildPermissionOptions,
 } from "./permission-options";
+import {
+  extractPostHogSubTool,
+  isPostHogDestructiveSubTool,
+  isPostHogExecTool,
+} from "./posthog-exec-gate";
 
 export type ToolPermissionResult =
   | {
@@ -78,6 +83,18 @@ async function emitToolDenial(
   });
 }
 
+async function buildDenialResult(
+  context: ToolHandlerContext,
+  response: RequestPermissionResponse,
+): Promise<ToolPermissionResult> {
+  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 getPlanFromFile(
   session: Session,
   fileContentCache: { [key: string]: string },
@@ -389,16 +406,9 @@ async function handleDefaultPermissionFlow(
       behavior: "allow",
       updatedInput: toolInput as Record<string, unknown>,
     };
-  } else {
-    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 };
   }
+
+  return buildDenialResult(context, response);
 }
 
 function parseMcpToolName(toolName: string): {
@@ -479,12 +489,74 @@ async function handleMcpApprovalFlow(
     };
   }
 
-  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 };
+  return buildDenialResult(context, response);
+}
+
+async function handlePostHogExecApprovalFlow(
+  context: ToolHandlerContext,
+  subTool: string,
+): Promise<ToolPermissionResult> {
+  const { toolName, toolInput, toolUseID, client, sessionId, session } =
+    context;
+
+  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 run \`${subTool}\` on PostHog`,
+      kind: "other",
+      content: [
+        {
+          type: "content" as const,
+          content: text(
+            "This will modify live PostHog data. Approve to run this sub-tool.",
+          ),
+        },
+      ],
+      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") {
+      try {
+        await session.settingsManager.addPostHogExecApproval(subTool);
+      } catch (error) {
+        context.logger.warn(
+          "[canUseTool] Failed to persist PostHog exec approval",
+          { error: error instanceof Error ? error.message : String(error) },
+        );
+      }
+    }
+    return {
+      behavior: "allow",
+      updatedInput: toolInput as Record<string, unknown>,
+    };
+  }
+
+  return buildDenialResult(context, response);
 }
 
 function handlePlanFileException(
@@ -602,6 +674,28 @@ export async function canUseTool(
     if (approvalState === "needs_approval") {
       return handleMcpApprovalFlow(context);
     }
+
+    if (isPostHogExecTool(toolName)) {
+      const subTool = extractPostHogSubTool(toolInput);
+      if (subTool && isPostHogDestructiveSubTool(subTool)) {
+        if (
+          session.permissionMode === "auto" ||
+          session.permissionMode === "bypassPermissions"
+        ) {
+          return {
+            behavior: "allow",
+            updatedInput: toolInput as Record<string, unknown>,
+          };
+        }
+        if (session.settingsManager.hasPostHogExecApproval(subTool)) {
+          return {
+            behavior: "allow",
+            updatedInput: toolInput as Record<string, unknown>,
+          };
+        }
+        return handlePostHogExecApprovalFlow(context, subTool);
+      }
+    }
   }
 
   if (isToolAllowedForMode(toolName, session.permissionMode)) {