@posthog/agent 2.3.351 → 2.3.354

package/package.json

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

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

@@ -618,6 +618,32 @@ export type ResultMessageHandlerResult = {
   };
 };
 
+export type AgentErrorClassification =
+  | "upstream_stream_terminated"
+  | "upstream_connection_error"
+  | "agent_error";
+
+/**
+ * Classify an error string surfaced by the Claude CLI via `is_error: true`
+ * result messages. Transient upstream-stream terminations (e.g. the fetch body
+ * from the LLM gateway is torn down mid-stream) are retriable; most other
+ * errors are not.
+ */
+export function classifyAgentError(
+  result: string | undefined,
+): AgentErrorClassification {
+  if (!result) return "agent_error";
+  const text = result.trim();
+  // Anthropic SDK surfaces an undici fetch abort as "API Error: terminated".
+  if (/API Error:\s*terminated\b/i.test(text)) {
+    return "upstream_stream_terminated";
+  }
+  if (/API Error:\s*Connection error\b/i.test(text)) {
+    return "upstream_connection_error";
+  }
+  return "agent_error";
+}
+
 export function handleResultMessage(
   message: SDKResultMessage,
 ): ResultMessageHandlerResult {
@@ -636,9 +662,13 @@ export function handleResultMessage(
         return { shouldStop: true, stopReason: "max_tokens", usage };
       }
       if (message.is_error) {
+        const classification = classifyAgentError(message.result);
         return {
           shouldStop: true,
-          error: RequestError.internalError(undefined, message.result),
+          error: RequestError.internalError(
+            { classification, result: message.result },
+            message.result,
+          ),
           usage,
         };
       }

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

@@ -2,7 +2,10 @@ import type {
   AgentSideConnection,
   RequestPermissionResponse,
 } from "@agentclientprotocol/sdk";
-import type { PermissionUpdate } from "@anthropic-ai/claude-agent-sdk";
+import type {
+  PermissionRuleValue,
+  PermissionUpdate,
+} from "@anthropic-ai/claude-agent-sdk";
 import { text } from "../../../utils/acp-content";
 import type { Logger } from "../../../utils/logger";
 import { toolInfoFromToolUse } from "../conversion/tool-use-to-acp";
@@ -347,7 +350,7 @@ async function handleDefaultPermissionFlow(
   const options = buildPermissionOptions(
     toolName,
     toolInput as Record<string, unknown>,
-    session?.cwd,
+    session.settingsManager.getRepoRoot(),
     suggestions,
   );
 
@@ -374,17 +377,19 @@ async function handleDefaultPermissionFlow(
       response.outcome.optionId === "allow_always")
   ) {
     if (response.outcome.optionId === "allow_always") {
+      const rules = extractAllowRules(suggestions, toolName);
+      try {
+        await session.settingsManager.addAllowRules(rules);
+      } catch (error) {
+        context.logger.warn(
+          "[canUseTool] Failed to persist allow rules to repository settings",
+          { error: error instanceof Error ? error.message : String(error) },
+        );
+      }
       return {
         behavior: "allow",
         updatedInput: toolInput as Record<string, unknown>,
-        updatedPermissions: suggestions ?? [
-          {
-            type: "addRules",
-            rules: [{ toolName }],
-            behavior: "allow",
-            destination: "localSettings",
-          },
-        ],
+        updatedPermissions: buildSessionPermissions(suggestions, rules),
       };
     }
     return {
@@ -429,6 +434,44 @@ function handlePlanFileException(
   };
 }
 
+function extractAllowRules(
+  suggestions: PermissionUpdate[] | undefined,
+  toolName: string,
+): PermissionRuleValue[] {
+  if (!suggestions || suggestions.length === 0) {
+    return [{ toolName }];
+  }
+  return suggestions
+    .filter(
+      (update) => update.type === "addRules" && update.behavior === "allow",
+    )
+    .flatMap((update) => ("rules" in update ? update.rules : []));
+}
+
+/**
+ * Forwards any non-addRules suggestions from the SDK (e.g. addDirectories)
+ * with their destination remapped to `session`. Our own allow rules are
+ * persisted via `settingsManager.addAllowRules`, so the SDK must not write
+ * them to its default per-cwd location.
+ */
+function buildSessionPermissions(
+  suggestions: PermissionUpdate[] | undefined,
+  rules: PermissionRuleValue[],
+): PermissionUpdate[] {
+  const passthrough = (suggestions ?? [])
+    .filter(
+      (update) => !(update.type === "addRules" && update.behavior === "allow"),
+    )
+    .map((update) => ({ ...update, destination: "session" as const }));
+  if (rules.length === 0) {
+    return passthrough;
+  }
+  return [
+    { type: "addRules", rules, behavior: "allow", destination: "session" },
+    ...passthrough,
+  ];
+}
+
 function extractDomainFromUrl(url: string): string | null {
   try {
     return new URL(url).hostname;

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

@@ -25,7 +25,7 @@ function permissionOptions(allowAlwaysLabel: string): PermissionOption[] {
 export function buildPermissionOptions(
   toolName: string,
   toolInput: Record<string, unknown>,
-  cwd?: string,
+  repoRoot?: string,
   suggestions?: PermissionUpdate[],
 ): PermissionOption[] {
   if (BASH_TOOLS.has(toolName)) {
@@ -36,11 +36,11 @@ export function buildPermissionOptions(
 
     const command = toolInput?.command as string | undefined;
     const cmdName = command?.split(/\s+/)[0] ?? "this command";
-    const cwdLabel = cwd ? ` in ${cwd}` : "";
+    const scopeLabel = repoRoot ? ` in ${repoRoot}` : "";
     const label = ruleContent ?? `\`${cmdName}\` commands`;
 
     return permissionOptions(
-      `Yes, and don't ask again for ${label}${cwdLabel}`,
+      `Yes, and don't ask again for ${label}${scopeLabel}`,
     );
   }
 

package/src/adapters/claude/session/repo-path.ts

@@ -0,0 +1,22 @@
+import { listWorktrees } from "@posthog/git/queries";
+
+/**
+ * Resolves the primary worktree (main repository) path for a given cwd.
+ *
+ * Secondary git worktrees share a `.git` common directory with the primary
+ * worktree. Returning the primary worktree path lets us scope per-repo
+ * settings — such as "don't ask again" permission rules — to a single
+ * location that every worktree of the same repository can read from.
+ *
+ * `git worktree list --porcelain` always emits the primary worktree first.
+ * Returns `cwd` when the directory is not inside a git repository or when
+ * git is unavailable.
+ */
+export async function resolveMainRepoPath(cwd: string): Promise<string> {
+  try {
+    const worktrees = await listWorktrees(cwd);
+    return worktrees[0]?.path ?? cwd;
+  } catch {
+    return cwd;
+  }
+}

package/src/adapters/claude/session/settings.test.ts

@@ -0,0 +1,159 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { resolveMainRepoPath } from "./repo-path";
+import { SettingsManager } from "./settings";
+
+function runGit(cwd: string, args: string[]): void {
+  execFileSync("git", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+}
+
+describe("SettingsManager per-repo persistence", () => {
+  let mainRepo: string;
+  let worktree: string;
+  let tmpRoot: string;
+
+  beforeEach(async () => {
+    tmpRoot = await fs.promises.realpath(
+      await fs.promises.mkdtemp(path.join(os.tmpdir(), "settings-manager-")),
+    );
+    mainRepo = path.join(tmpRoot, "main");
+    worktree = path.join(tmpRoot, "wt");
+    await fs.promises.mkdir(mainRepo, { recursive: true });
+
+    runGit(mainRepo, ["init", "-b", "main"]);
+    runGit(mainRepo, ["config", "user.email", "test@example.com"]);
+    runGit(mainRepo, ["config", "user.name", "test"]);
+    runGit(mainRepo, ["commit", "--allow-empty", "-m", "init"]);
+    runGit(mainRepo, ["worktree", "add", "-b", "feat", worktree]);
+  });
+
+  afterEach(async () => {
+    await fs.promises.rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  it("persists allow rules to the primary worktree when invoked from a secondary worktree", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await manager.addAllowRules([
+      { toolName: "Bash", ruleContent: "pnpm test:*" },
+    ]);
+
+    const repoLocalPath = path.join(mainRepo, ".claude", "settings.local.json");
+    const contents = JSON.parse(
+      await fs.promises.readFile(repoLocalPath, "utf-8"),
+    );
+    expect(contents.permissions.allow).toContain("Bash(pnpm test:*)");
+
+    const worktreeLocalPath = path.join(
+      worktree,
+      ".claude",
+      "settings.local.json",
+    );
+    expect(fs.existsSync(worktreeLocalPath)).toBe(false);
+  });
+
+  it("sees rules persisted by a sibling worktree after re-initialization", async () => {
+    const writer = new SettingsManager(worktree);
+    await writer.initialize();
+    await writer.addAllowRules([{ toolName: "TodoWrite" }]);
+
+    const sibling = path.join(tmpRoot, "wt2");
+    runGit(mainRepo, ["worktree", "add", "-b", "other", sibling]);
+
+    const reader = new SettingsManager(sibling);
+    await reader.initialize();
+    const decision = reader.checkPermission("TodoWrite", {});
+    expect(decision.decision).toBe("allow");
+  });
+
+  it("widens name-based matching for argumentless rules", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await manager.addAllowRules([{ toolName: "TodoWrite" }]);
+
+    expect(manager.checkPermission("TodoWrite", {}).decision).toBe("allow");
+  });
+
+  it("does not widen name-based matching when the rule has an argument", async () => {
+    // A rule *with* an argument for a tool we don't have an accessor for must
+    // not match regardless of the actual input — otherwise a deny rule like
+    // `Bash(rm -rf)` applied to a non-ACP Bash invocation would match any
+    // command.
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await manager.addAllowRules([
+      { toolName: "UnknownTool", ruleContent: "something" },
+    ]);
+
+    expect(
+      manager.checkPermission("UnknownTool", { command: "anything" }).decision,
+    ).toBe("ask");
+  });
+
+  it("still allows ACP-prefixed Bash invocations when a Bash(...) rule is persisted", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await manager.addAllowRules([
+      { toolName: "Bash", ruleContent: "pnpm test:*" },
+    ]);
+
+    const decision = manager.checkPermission("mcp__acp__Bash", {
+      command: "pnpm test --filter agent",
+    });
+    expect(decision.decision).toBe("allow");
+  });
+
+  it("refuses to overwrite the file when existing contents cannot be parsed", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    const filePath = path.join(mainRepo, ".claude", "settings.local.json");
+    const original = "{ this is not valid json";
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.promises.writeFile(filePath, original);
+
+    await expect(
+      manager.addAllowRules([{ toolName: "TodoWrite" }]),
+    ).rejects.toThrow();
+
+    // File must be untouched — overwriting would wipe whatever the user had.
+    expect(await fs.promises.readFile(filePath, "utf-8")).toBe(original);
+  });
+
+  it("concurrent addAllowRules calls do not clobber each other", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await Promise.all([
+      manager.addAllowRules([{ toolName: "A" }]),
+      manager.addAllowRules([{ toolName: "B" }]),
+      manager.addAllowRules([{ toolName: "C" }]),
+    ]);
+
+    const filePath = path.join(mainRepo, ".claude", "settings.local.json");
+    const contents = JSON.parse(await fs.promises.readFile(filePath, "utf-8"));
+    expect(contents.permissions.allow).toEqual(
+      expect.arrayContaining(["A", "B", "C"]),
+    );
+  });
+});
+
+describe("resolveMainRepoPath", () => {
+  it("returns cwd when the directory is not inside a git repository", async () => {
+    const tmp = await fs.promises.realpath(
+      await fs.promises.mkdtemp(path.join(os.tmpdir(), "repo-path-")),
+    );
+    try {
+      expect(await resolveMainRepoPath(tmp)).toBe(tmp);
+    } finally {
+      await fs.promises.rm(tmp, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -1,7 +1,10 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { PermissionRuleValue } from "@anthropic-ai/claude-agent-sdk";
 import { minimatch } from "minimatch";
+import { AsyncMutex } from "../../../utils/async-mutex";
+import { resolveMainRepoPath } from "./repo-path";
 
 const ACP_TOOL_NAME_PREFIX = "mcp__acp__";
 
@@ -86,7 +89,8 @@ function matchesRule(
   const ruleAppliesToTool =
     (rule.toolName === "Bash" && toolName === acpToolNames.bash) ||
     (rule.toolName === "Edit" && FILE_EDITING_TOOLS.includes(toolName)) ||
-    (rule.toolName === "Read" && FILE_READING_TOOLS.includes(toolName));
+    (rule.toolName === "Read" && FILE_READING_TOOLS.includes(toolName)) ||
+    (rule.toolName === toolName && !rule.argument);
 
   if (!ruleAppliesToTool) {
     return false;
@@ -123,6 +127,23 @@ function matchesRule(
   return matchesGlob(rule.argument, actualArg, cwd);
 }
 
+function formatRule(rule: PermissionRuleValue): string {
+  return rule.ruleContent
+    ? `${rule.toolName}(${rule.ruleContent})`
+    : rule.toolName;
+}
+
+async function writeFileAtomic(filePath: string, data: string): Promise<void> {
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.promises.writeFile(tmpPath, data);
+  try {
+    await fs.promises.rename(tmpPath, filePath);
+  } catch (error) {
+    await fs.promises.rm(tmpPath, { force: true });
+    throw error;
+  }
+}
+
 async function loadSettingsFile(
   filePath: string | undefined,
 ): Promise<ClaudeCodeSettings> {
@@ -143,6 +164,26 @@ async function loadSettingsFile(
   }
 }
 
+/**
+ * Reads a settings file for a read-modify-write cycle. Unlike
+ * `loadSettingsFile`, this throws on any error other than ENOENT — we refuse
+ * to overwrite a file we couldn't parse, because doing so would wipe the
+ * user's existing settings (other allow/deny/ask rules, env, model, etc).
+ */
+async function readSettingsFileForUpdate(
+  filePath: string,
+): Promise<ClaudeCodeSettings> {
+  try {
+    const content = await fs.promises.readFile(filePath, "utf-8");
+    return JSON.parse(content) as ClaudeCodeSettings;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return {};
+    }
+    throw error;
+  }
+}
+
 export interface PermissionSettings {
   allow?: string[];
   deny?: string[];
@@ -177,8 +218,10 @@ export function getManagedSettingsPath(): string {
       return "/etc/claude-code/managed-settings.json";
   }
 }
+
 export class SettingsManager {
   private cwd: string;
+  private repoRoot: string;
   private userSettings: ClaudeCodeSettings = {};
   private projectSettings: ClaudeCodeSettings = {};
   private localSettings: ClaudeCodeSettings = {};
@@ -186,9 +229,11 @@ export class SettingsManager {
   private mergedSettings: ClaudeCodeSettings = {};
   private initialized = false;
   private initPromise: Promise<void> | null = null;
+  private writeMutex = new AsyncMutex();
 
   constructor(cwd: string) {
     this.cwd = cwd;
+    this.repoRoot = cwd;
   }
 
   async initialize(): Promise<void> {
@@ -211,11 +256,17 @@ export class SettingsManager {
     return path.join(this.cwd, ".claude", "settings.json");
   }
 
+  /**
+   * Local settings are anchored to the primary worktree so every worktree of
+   * the same repository shares a single `.claude/settings.local.json`. This
+   * avoids re-prompting for the same permission in every worktree.
+   */
   private getLocalSettingsPath(): string {
-    return path.join(this.cwd, ".claude", "settings.local.json");
+    return path.join(this.repoRoot, ".claude", "settings.local.json");
   }
 
   private async loadAllSettings(): Promise<void> {
+    this.repoRoot = await resolveMainRepoPath(this.cwd);
     const [userSettings, projectSettings, localSettings, enterpriseSettings] =
       await Promise.all([
         loadSettingsFile(this.getUserSettingsPath()),
@@ -278,10 +329,6 @@ export class SettingsManager {
   }
 
   checkPermission(toolName: string, toolInput: unknown): PermissionCheckResult {
-    if (!toolName.startsWith(ACP_TOOL_NAME_PREFIX)) {
-      return { decision: "ask" };
-    }
-
     const permissions = this.mergedSettings.permissions;
     if (!permissions) {
       return { decision: "ask" };
@@ -319,6 +366,45 @@ export class SettingsManager {
     return this.cwd;
   }
 
+  getRepoRoot(): string {
+    return this.repoRoot;
+  }
+
+  /**
+   * Persists allow rules to `<primary-worktree>/.claude/settings.local.json`.
+   * Because local settings are resolved against the primary worktree, every
+   * worktree of the same repository picks up the new rule on next load.
+   *
+   * Writes are serialised via `writeMutex` to prevent concurrent callers from
+   * clobbering each other, and use a temp-file + rename to keep the file
+   * consistent if the process dies mid-write.
+   */
+  async addAllowRules(rules: PermissionRuleValue[]): Promise<void> {
+    if (rules.length === 0) return;
+    if (!this.initialized) await this.initialize();
+    await this.writeMutex.acquire();
+    try {
+      const filePath = this.getLocalSettingsPath();
+      const existing = await readSettingsFileForUpdate(filePath);
+      const permissions: PermissionSettings = {
+        ...(existing.permissions ?? {}),
+      };
+      const current = new Set(permissions.allow ?? []);
+      for (const rule of rules) {
+        current.add(formatRule(rule));
+      }
+      permissions.allow = Array.from(current);
+      const next: ClaudeCodeSettings = { ...existing, permissions };
+      await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+      await writeFileAtomic(filePath, `${JSON.stringify(next, null, 2)}\n`);
+
+      this.localSettings = next;
+      this.mergeAllSettings();
+    } finally {
+      this.writeMutex.release();
+    }
+  }
+
   async setCwd(cwd: string): Promise<void> {
     if (this.cwd === cwd) return;
     if (this.initPromise) await this.initPromise;

package/src/server/agent-server.ts

@@ -14,12 +14,17 @@ import {
 import { type ServerType, serve } from "@hono/node-server";
 import { getCurrentBranch } from "@posthog/git/queries";
 import { Hono } from "hono";
+import { z } from "zod";
 import packageJson from "../../package.json" with { type: "json" };
 import { POSTHOG_METHODS, POSTHOG_NOTIFICATIONS } from "../acp-extensions";
 import {
   createAcpConnection,
   type InProcessAcpConnection,
 } from "../adapters/acp-connection";
+import {
+  type AgentErrorClassification,
+  classifyAgentError,
+} from "../adapters/claude/conversion/sdk-to-acp";
 import { selectRecentTurns } from "../adapters/claude/session/jsonl-hydration";
 import type { PermissionMode } from "../execution-mode";
 import { DEFAULT_CODEX_MODEL } from "../gateway-models";
@@ -51,6 +56,16 @@ import { type JwtPayload, JwtValidationError, validateJwt } from "./jwt";
 import { jsonRpcRequestSchema, validateCommandParams } from "./schemas";
 import type { AgentServerConfig } from "./types";
 
+const agentErrorClassificationSchema = z.enum([
+  "upstream_stream_terminated",
+  "upstream_connection_error",
+  "agent_error",
+]) satisfies z.ZodType<AgentErrorClassification>;
+
+const errorWithClassificationSchema = z.object({
+  data: z.object({ classification: agentErrorClassificationSchema }),
+});
+
 type MessageCallback = (message: unknown) => void;
 
 class NdJsonTap {
@@ -973,6 +988,41 @@ export class AgentServer {
     await this.sendInitialTaskMessage(payload, preTaskRun);
   }
 
+  private extractErrorClassification(error: unknown): {
+    classification: AgentErrorClassification;
+    message: string;
+  } {
+    const message =
+      error instanceof Error ? error.message : String(error ?? "");
+
+    // Prefer the structured `data` carried on RequestError if present.
+    const parsed = errorWithClassificationSchema.safeParse(error);
+    if (parsed.success) {
+      return { classification: parsed.data.data.classification, message };
+    }
+
+    return { classification: classifyAgentError(message), message };
+  }
+
+  private classifyAndSignalFailure(
+    payload: JwtPayload,
+    phase: "initial" | "resume",
+    error: unknown,
+  ): Promise<void> {
+    const { classification, message } = this.extractErrorClassification(error);
+    const errorMessage =
+      classification === "upstream_stream_terminated"
+        ? "Upstream LLM stream terminated"
+        : classification === "upstream_connection_error"
+          ? "Upstream LLM connection error"
+          : message || "Agent error";
+    this.logger.error(`send_${phase}_task_message_failed`, {
+      classification,
+      message,
+    });
+    return this.signalTaskComplete(payload, "error", errorMessage);
+  }
+
   private async sendInitialTaskMessage(
     payload: JwtPayload,
     prefetchedRun?: TaskRun | null,
@@ -1087,7 +1137,7 @@ export class AgentServer {
       if (this.session) {
         await this.session.logWriter.flushAll();
       }
-      await this.signalTaskComplete(payload, "error");
+      await this.classifyAndSignalFailure(payload, "initial", error);
     }
   }
 
@@ -1176,7 +1226,7 @@ export class AgentServer {
       if (this.session) {
         await this.session.logWriter.flushAll();
       }
-      await this.signalTaskComplete(payload, "error");
+      await this.classifyAndSignalFailure(payload, "resume", error);
     }
   }
 
@@ -1657,6 +1707,7 @@ ${attributionInstructions}
   private async signalTaskComplete(
     payload: JwtPayload,
     stopReason: string,
+    errorMessage?: string,
   ): Promise<void> {
     if (this.session?.payload.run_id === payload.run_id) {
       try {
@@ -1684,7 +1735,7 @@ ${attributionInstructions}
     try {
       await this.posthogAPI.updateTaskRun(payload.task_id, payload.run_id, {
         status,
-        error_message: stopReason === "error" ? "Agent error" : undefined,
+        error_message: errorMessage ?? "Agent error",
       });
       this.logger.info("Task completion signaled", { status, stopReason });
     } catch (error) {