fix(agent): default Claude PostHog exec guard

Author: skoob13

packages/agent/README.md

@@ -76,11 +76,12 @@ In cloud background mode, permissions are always auto-approved. In interactive m
 
 Cloud provisioning can pass `--posthogExecPermissionRegex <regex>` to require
 one-time client approval for matching PostHog MCP `exec` sub-tools in every
-interactive Claude and Codex permission mode. Matching is case-insensitive
-against the delegated name in `call [--json] <sub-tool> ...`. These prompts do
-offer Claude users an always-allow choice remembered in local repository
-settings; Codex approvals remain one-time. Background runs keep their existing
-auto-approval behavior. The default is
+interactive cloud Claude and Codex permission mode. Local Claude `auto` and
+`bypassPermissions` modes remain hands-off. Matching is case-insensitive against
+the delegated name in `call [--json] <sub-tool> ...`. These prompts offer Claude
+users an always-allow choice remembered in local repository settings; Codex
+approvals remain one-time. Background runs keep their existing auto-approval
+behavior. The default is
 `(^|-)(partial-update|update|patch|delete|destroy)(-|$)`.
 
 ## ACP connection layer

packages/agent/src/adapters/claude/claude-agent.resume-model.test.ts

@@ -1,7 +1,8 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentSideConnection } from "@agentclientprotocol/sdk";
+import type { HookInput, Options } from "@anthropic-ai/claude-agent-sdk";
 import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { DEFAULT_GATEWAY_MODEL } from "../../gateway-models";
 
@@ -38,11 +39,13 @@ function makeQueryHandle(): SdkQueryHandle {
 }
 
 const createdQueries: SdkQueryHandle[] = [];
+const createdQueryOptions: Options[] = [];
 
 vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
-  query: vi.fn(() => {
+  query: vi.fn(({ options }: { options: Options }) => {
     const handle = makeQueryHandle();
     createdQueries.push(handle);
+    createdQueryOptions.push(options);
     return handle;
   }),
   getSessionMessages: vi.fn().mockResolvedValue([]),
@@ -87,6 +90,14 @@ const cwd = mkdtempSync(path.join(os.tmpdir(), "claude-agent-test-cwd-"));
 const configDir = mkdtempSync(
   path.join(os.tmpdir(), "claude-agent-test-config-"),
 );
+const permissionCwd = mkdtempSync(
+  path.join(os.tmpdir(), "claude-agent-permission-test-cwd-"),
+);
+mkdirSync(path.join(permissionCwd, ".claude"), { recursive: true });
+writeFileSync(
+  path.join(permissionCwd, ".claude", "settings.json"),
+  JSON.stringify({ permissions: { allow: ["mcp__posthog__exec"] } }),
+);
 const savedEnv = {
   ANTHROPIC_BASE_URL: process.env.ANTHROPIC_BASE_URL,
   CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
@@ -95,6 +106,7 @@ const savedEnv = {
 afterAll(() => {
   rmSync(cwd, { recursive: true, force: true });
   rmSync(configDir, { recursive: true, force: true });
+  rmSync(permissionCwd, { recursive: true, force: true });
   process.env.ANTHROPIC_BASE_URL = savedEnv.ANTHROPIC_BASE_URL;
   process.env.CLAUDE_CONFIG_DIR = savedEnv.CLAUDE_CONFIG_DIR;
   if (savedEnv.ANTHROPIC_BASE_URL === undefined) {
@@ -105,9 +117,10 @@ afterAll(() => {
   }
 });
 
-describe("ClaudeAcpAgent session model on resume", () => {
+describe("ClaudeAcpAgent session creation", () => {
   beforeEach(() => {
     createdQueries.length = 0;
+    createdQueryOptions.length = 0;
     nextInitPromise = Promise.resolve({
       result: "success",
       commands: [],
@@ -119,6 +132,119 @@ describe("ClaudeAcpAgent session model on resume", () => {
     process.env.CLAUDE_CONFIG_DIR = configDir;
   });
 
+  async function runPostHogExecPreToolUse(
+    options: Options,
+    subTool: string,
+  ): Promise<string | undefined> {
+    const input = {
+      session_id: "permission-session",
+      transcript_path: "/tmp/transcript",
+      cwd: permissionCwd,
+      hook_event_name: "PreToolUse",
+      tool_name: "mcp__posthog__exec",
+      tool_use_id: "toolu_permission",
+      tool_input: { command: `call ${subTool} {}` },
+    } as HookInput;
+
+    for (const hook of (options.hooks?.PreToolUse ?? []).flatMap(
+      (entry) => entry.hooks ?? [],
+    )) {
+      const result = await hook(input, undefined, {
+        signal: new AbortController().signal,
+      });
+      const decision = (
+        result as {
+          hookSpecificOutput?: { permissionDecision?: string };
+        }
+      ).hookSpecificOutput?.permissionDecision;
+      if (decision) return decision;
+    }
+
+    return undefined;
+  }
+
+  it.each(["new", "resume", "load"] as const)(
+    "uses the default PostHog exec permission regex for local %s sessions when metadata omits it",
+    async (sessionKind) => {
+      const agent = makeAgent();
+      const sessionIds = {
+        new: "0197a000-0000-7000-8000-000000000101",
+        resume: "0197a000-0000-7000-8000-000000000102",
+        load: "0197a000-0000-7000-8000-000000000103",
+      };
+      const params = {
+        sessionId: sessionIds[sessionKind],
+        cwd: permissionCwd,
+        mcpServers: [],
+        _meta: { taskRunId: `run-permission-${sessionKind}` },
+      };
+
+      if (sessionKind === "new") {
+        await agent.newSession(params);
+      } else if (sessionKind === "resume") {
+        await agent.resumeSession(params);
+      } else {
+        await agent.loadSession(params);
+      }
+
+      expect(createdQueryOptions).toHaveLength(1);
+      await expect(
+        runPostHogExecPreToolUse(
+          createdQueryOptions[0] as Options,
+          "dashboard-update",
+        ),
+      ).resolves.toBe("ask");
+    },
+  );
+
+  it("uses an explicit PostHog exec permission regex instead of the default", async () => {
+    const agent = makeAgent();
+
+    await agent.newSession({
+      cwd: permissionCwd,
+      mcpServers: [],
+      _meta: {
+        taskRunId: "run-permission-custom",
+        posthogExecPermissionRegex: "(^|-)archive(-|$)",
+      },
+    });
+
+    expect(createdQueryOptions).toHaveLength(1);
+    await expect(
+      runPostHogExecPreToolUse(
+        createdQueryOptions[0] as Options,
+        "dashboard-update",
+      ),
+    ).resolves.toBe("allow");
+    await expect(
+      runPostHogExecPreToolUse(
+        createdQueryOptions[0] as Options,
+        "dashboard-archive",
+      ),
+    ).resolves.toBe("ask");
+  });
+
+  it.each([
+    { environment: "local", expectedCloudMode: false },
+    { environment: "cloud", expectedCloudMode: true },
+  ] as const)(
+    "records $environment sessions as cloudMode=$expectedCloudMode",
+    async ({ environment, expectedCloudMode }) => {
+      const agent = makeAgent();
+
+      await agent.newSession({
+        cwd,
+        mcpServers: [],
+        _meta: { environment, taskRunId: `run-${environment}` },
+      });
+
+      expect(
+        (agent as unknown as { session: { cloudMode: boolean } }).session
+          .cloudMode,
+      ).toBe(expectedCloudMode);
+    },
+  );
+
   // The SDK does not carry the model across resume — without an explicit
   // setModel the resumed session silently runs the SDK default (opus).
   it.each([

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

@@ -57,7 +57,10 @@ import {
   type Enrichment,
   type FileEnrichmentDeps,
 } from "../../enrichment/file-enricher";
-import { compilePostHogExecPermissionRegex } from "../../posthog-exec-permission";
+import {
+  compilePostHogExecPermissionRegex,
+  DEFAULT_POSTHOG_EXEC_PERMISSION_REGEX_SOURCE,
+} from "../../posthog-exec-permission";
 import {
   classifyPostHogExecCall,
   isUnclassifiedPostHogSubTool,
@@ -1951,9 +1954,10 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       CODE_EXECUTION_MODES.includes(meta.permissionMode as CodeExecutionMode)
         ? (meta.permissionMode as CodeExecutionMode)
         : "default";
-    const posthogExecPermissionRegex = meta?.posthogExecPermissionRegex
-      ? compilePostHogExecPermissionRegex(meta.posthogExecPermissionRegex)
-      : undefined;
+    const posthogExecPermissionRegex = compilePostHogExecPermissionRegex(
+      meta?.posthogExecPermissionRegex ??
+        DEFAULT_POSTHOG_EXEC_PERMISSION_REGEX_SOURCE,
+    );
 
     const taskState: TaskState = new Map();
     const options = buildSessionOptions({
@@ -2015,6 +2019,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       cancelled: false,
       settingsManager,
       permissionMode,
+      cloudMode: cloudRun,
       posthogExecPermissionRegex,
       abortController,
       accumulatedUsage: {

packages/agent/src/adapters/claude/permissions/permission-handlers.test.ts

@@ -27,6 +27,7 @@ function createContext(
   return {
     session: {
       permissionMode: "default" as const,
+      cloudMode: false,
       settingsManager: {
         getRepoRoot: vi.fn().mockReturnValue("/repo"),
       },
@@ -215,14 +216,15 @@ describe("canUseTool MCP approval enforcement", () => {
     "auto",
     "bypassPermissions",
   ] as const)(
-    "prompts for a configured PostHog exec match in %s mode with a remembered choice",
+    "prompts for a configured PostHog exec match in cloud %s mode with a remembered choice",
     async (permissionMode) => {
       setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
 
       const context = createContext("mcp__posthog__exec", {
         toolInput: { command: "call notebooks-destroy {}" },
         session: {
           permissionMode,
+          cloudMode: true,
           posthogExecPermissionRegex,
           settingsManager: {
             getRepoRoot: vi.fn().mockReturnValue("/repo"),
@@ -250,6 +252,32 @@ describe("canUseTool MCP approval enforcement", () => {
     },
   );
 
+  it.each(["auto", "bypassPermissions"] as const)(
+    "keeps local %s mode hands-off for a configured PostHog exec match",
+    async (permissionMode) => {
+      setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
+
+      const context = createContext("mcp__posthog__exec", {
+        toolInput: { command: "call notebooks-destroy {}" },
+        session: {
+          permissionMode,
+          cloudMode: false,
+          posthogExecPermissionRegex,
+          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("skips the prompt for a remembered PostHog exec sub-tool", async () => {
     setMcpToolApprovalStates({ mcp__posthog__exec: "approved" });
 

packages/agent/src/adapters/claude/permissions/permission-handlers.ts

@@ -776,6 +776,20 @@ export async function canUseTool(
             updatedInput: toolInput as Record<string, unknown>,
           };
         }
+        // Local hands-off modes retain their normal no-prompt behavior. Cloud
+        // sessions must send the request to AgentServer, which uses the run's
+        // effective mode to relay interactive approvals and auto-approve
+        // background runs.
+        if (
+          !session.cloudMode &&
+          (session.permissionMode === "auto" ||
+            session.permissionMode === "bypassPermissions")
+        ) {
+          return {
+            behavior: "allow",
+            updatedInput: toolInput as Record<string, unknown>,
+          };
+        }
         return handlePostHogExecApprovalFlow(context, subTool);
       }
     }

packages/agent/src/adapters/claude/types.ts

@@ -67,6 +67,8 @@ export type Session = BaseSession & {
   input: Pushable<SDKUserMessage>;
   settingsManager: SettingsManager;
   permissionMode: CodeExecutionMode;
+  /** Whether permission decisions are delegated to the cloud AgentServer. */
+  cloudMode: boolean;
   posthogExecPermissionRegex?: RegExp;
   modeBeforePlan?: CodeExecutionMode;
   modelId?: string;

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

@@ -1575,26 +1575,43 @@ describe("AgentServer HTTP Mode", () => {
       });
     });
 
-    it("keeps background PostHog exec matches auto-approved", async () => {
-      const testServer = exposeCloudClient(
-        createServer({ posthogExecPermissionRegex: "delete|destroy" }),
-      );
-      const relaySpy = vi.spyOn(testServer, "relayPermissionToClient");
+    it.each([
+      {
+        modeSource: "JWT payload",
+        configMode: "interactive",
+        payloadMode: "background",
+      },
+      {
+        modeSource: "server config",
+        configMode: "background",
+        payloadMode: undefined,
+      },
+    ] as const)(
+      "keeps PostHog exec matches auto-approved in background mode from $modeSource",
+      async ({ configMode, payloadMode }) => {
+        const testServer = exposeCloudClient(
+          createServer({
+            mode: configMode,
+            posthogExecPermissionRegex: "delete|destroy",
+          }),
+        );
+        const relaySpy = vi.spyOn(testServer, "relayPermissionToClient");
 
-      const { requestPermission } = testServer.createCloudClient({
-        ...basePayload,
-        mode: "background",
-      });
-      const result = await requestPermission(
-        codexPosthogExecPermissionRequest("call experiment-delete {}"),
-      );
+        const { requestPermission } = testServer.createCloudClient({
+          ...basePayload,
+          ...(payloadMode ? { mode: payloadMode } : {}),
+        });
+        const result = await requestPermission(
+          codexPosthogExecPermissionRequest("call experiment-delete {}"),
+        );
 
-      expect(relaySpy).not.toHaveBeenCalled();
-      expect(result.outcome).toEqual({
-        outcome: "selected",
-        optionId: "allow_once",
-      });
-    });
+        expect(relaySpy).not.toHaveBeenCalled();
+        expect(result.outcome).toEqual({
+          outcome: "selected",
+          optionId: "allow_once",
+        });
+      },
+    );
 
     it("rejects permission responses for options that were not offered", async () => {
       const testServer = exposeCloudClient(createServer());