@posthog/agent 2.3.326 → 2.3.346

package/src/adapters/claude/conversion/tool-use-to-acp.ts

@@ -31,6 +31,7 @@ function stripSystemReminders(value: string): string {
 }
 
 import { resourceLink, text, toolContent } from "../../../utils/acp-content";
+import type { EnrichedReadCache } from "../hooks";
 import { getMcpToolMetadata } from "../mcp/tool-metadata";
 
 type ToolInfo = Pick<ToolCall, "title" | "kind" | "content" | "locations">;
@@ -526,6 +527,7 @@ export function toolUpdateFromToolResult(
     supportsTerminalOutput?: boolean;
     toolUseId?: string;
     cachedFileContent?: Record<string, string>;
+    enrichedReadCache?: EnrichedReadCache;
   },
 ): Pick<ToolCallUpdate, "title" | "content" | "locations" | "_meta"> {
   if (
@@ -538,7 +540,21 @@ export function toolUpdateFromToolResult(
   }
 
   switch (toolUse?.name) {
-    case "Read":
+    case "Read": {
+      const cache = options?.enrichedReadCache;
+      const enriched =
+        cache && options?.toolUseId ? cache.get(options.toolUseId) : undefined;
+      if (enriched !== undefined && cache && options?.toolUseId) {
+        cache.delete(options.toolUseId);
+        return {
+          content: [
+            {
+              type: "content" as const,
+              content: text(markdownEscape(enriched)),
+            },
+          ],
+        };
+      }
       if (Array.isArray(toolResult.content) && toolResult.content.length > 0) {
         return {
           content: toolResult.content.map((item) => {
@@ -582,6 +598,7 @@ export function toolUpdateFromToolResult(
         };
       }
       return {};
+    }
 
     case "Bash": {
       const result = toolResult.content;

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

@@ -0,0 +1,189 @@
+import type { HookInput } from "@anthropic-ai/claude-agent-sdk";
+import { describe, expect, test, vi } from "vitest";
+import type { FileEnrichmentDeps } from "../../enrichment/file-enricher";
+
+const enrichFileMock = vi.hoisted(() => vi.fn());
+vi.mock("../../enrichment/file-enricher", () => ({
+  enrichFileForAgent: enrichFileMock,
+}));
+
+import { createReadEnrichmentHook, type EnrichedReadCache } from "./hooks";
+
+const stubDeps = {} as FileEnrichmentDeps;
+
+function buildReadHookInput(
+  overrides: Partial<HookInput> & {
+    file_path?: string;
+    tool_response?: unknown;
+  } = {},
+): HookInput {
+  return {
+    session_id: "test-session",
+    transcript_path: "/tmp/transcript",
+    cwd: "/tmp",
+    hook_event_name: "PostToolUse",
+    tool_name: "Read",
+    tool_use_id: "toolu_1",
+    tool_input: { file_path: overrides.file_path ?? "/tmp/code.ts" },
+    tool_response: overrides.tool_response ?? "raw-content",
+    ...overrides,
+  } as HookInput;
+}
+
+describe("createReadEnrichmentHook", () => {
+  test("returns { continue: true } for non-PostToolUse events", async () => {
+    enrichFileMock.mockReset();
+    const cache: EnrichedReadCache = new Map();
+    const hook = createReadEnrichmentHook(stubDeps, cache);
+    const result = await hook(
+      { hook_event_name: "PreToolUse" } as HookInput,
+      undefined,
+      { signal: new AbortController().signal },
+    );
+    expect(result).toEqual({ continue: true });
+    expect(enrichFileMock).not.toHaveBeenCalled();
+  });
+
+  test("returns { continue: true } for non-Read tools", async () => {
+    enrichFileMock.mockReset();
+    const cache: EnrichedReadCache = new Map();
+    const hook = createReadEnrichmentHook(stubDeps, cache);
+    const result = await hook(
+      buildReadHookInput({ tool_name: "Bash" }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+    expect(result).toEqual({ continue: true });
+    expect(enrichFileMock).not.toHaveBeenCalled();
+  });
+
+  test("passes stripped content and file_path into enricher", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce(null);
+
+    const cache: EnrichedReadCache = new Map();
+    const hook = createReadEnrichmentHook(stubDeps, cache);
+    await hook(
+      buildReadHookInput({
+        file_path: "/tmp/app.ts",
+        tool_response: "     1\tconst x = 1;\n     2\tposthog.capture('x');",
+      }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(enrichFileMock).toHaveBeenCalledTimes(1);
+    const [, filePath, content] = enrichFileMock.mock.calls[0];
+    expect(filePath).toBe("/tmp/app.ts");
+    expect(content).toBe("const x = 1;\nposthog.capture('x');");
+  });
+
+  test("returns additionalContext when enricher produces annotations", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce(
+      "posthog.capture('x'); // [PostHog] Event: \"x\"",
+    );
+
+    const cache: EnrichedReadCache = new Map();
+    const hook = createReadEnrichmentHook(stubDeps, cache);
+    const result = await hook(
+      buildReadHookInput({ file_path: "/tmp/app.ts" }),
+      undefined,
+      {
+        signal: new AbortController().signal,
+      },
+    );
+
+    expect(result).toEqual({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: expect.stringContaining(
+          "posthog.capture('x'); // [PostHog] Event: \"x\"",
+        ),
+      },
+    });
+    const context = (
+      result as {
+        hookSpecificOutput: { additionalContext: string };
+      }
+    ).hookSpecificOutput.additionalContext;
+    expect(context).toContain("/tmp/app.ts");
+  });
+
+  test("writes enriched content to cache keyed by tool_use_id", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce(
+      "posthog.capture('x'); // [PostHog] Event: \"x\"",
+    );
+
+    const cache: EnrichedReadCache = new Map();
+    const hook = createReadEnrichmentHook(stubDeps, cache);
+    await hook(buildReadHookInput({ file_path: "/tmp/app.ts" }), undefined, {
+      signal: new AbortController().signal,
+    });
+
+    expect(cache.get("toolu_1")).toContain('// [PostHog] Event: "x"');
+  });
+
+  test("does not write to cache when tool_use_id is missing", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce("enriched");
+
+    const cache: EnrichedReadCache = new Map();
+    const hook = createReadEnrichmentHook(stubDeps, cache);
+    await hook(
+      buildReadHookInput({ file_path: "/tmp/app.ts", tool_use_id: undefined }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(cache.size).toBe(0);
+  });
+
+  test("handles {type:'text', file:{content}} Read tool_response shape", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce("enriched");
+
+    const cache: EnrichedReadCache = new Map();
+    const hook = createReadEnrichmentHook(stubDeps, cache);
+    await hook(
+      buildReadHookInput({
+        file_path: "/tmp/app.ts",
+        tool_response: {
+          type: "text",
+          file: {
+            filePath: "/tmp/app.ts",
+            content: "posthog.capture('x');\n",
+            numLines: 1,
+            startLine: 1,
+            totalLines: 1,
+          },
+        },
+      }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    const [, , content] = enrichFileMock.mock.calls[0];
+    expect(content).toBe("posthog.capture('x');\n");
+  });
+
+  test("handles wrapped [{type:'text', text:'...'}] tool_response shape", async () => {
+    enrichFileMock.mockReset();
+    enrichFileMock.mockResolvedValueOnce("enriched");
+
+    const cache: EnrichedReadCache = new Map();
+    const hook = createReadEnrichmentHook(stubDeps, cache);
+    await hook(
+      buildReadHookInput({
+        tool_response: [{ type: "text", text: "     1\tfoo" }],
+      }),
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    const [, , content] = enrichFileMock.mock.calls[0];
+    expect(content).toBe("foo");
+  });
+});

package/src/adapters/claude/hooks.ts

@@ -1,8 +1,101 @@
 import type { HookCallback, HookInput } from "@anthropic-ai/claude-agent-sdk";
+import {
+  enrichFileForAgent,
+  type FileEnrichmentDeps,
+} from "../../enrichment/file-enricher";
 import type { Logger } from "../../utils/logger";
+import { stripCatLineNumbers } from "./conversion/sdk-to-acp";
 import type { SettingsManager } from "./session/settings";
 import type { CodeExecutionMode } from "./tools";
 
+function extractTextFromToolResponse(response: unknown): string | null {
+  if (typeof response === "string") return response;
+  if (!response) return null;
+  if (Array.isArray(response)) {
+    const parts: string[] = [];
+    for (const part of response) {
+      if (typeof part === "string") {
+        parts.push(part);
+      } else if (
+        part &&
+        typeof part === "object" &&
+        "text" in part &&
+        typeof (part as { text?: unknown }).text === "string"
+      ) {
+        parts.push((part as { text: string }).text);
+      }
+    }
+    return parts.length > 0 ? parts.join("") : null;
+  }
+  if (typeof response === "object" && response !== null) {
+    const maybe = response as {
+      content?: unknown;
+      text?: unknown;
+      file?: { content?: unknown };
+    };
+    if (
+      maybe.file &&
+      typeof maybe.file === "object" &&
+      typeof maybe.file.content === "string"
+    ) {
+      return maybe.file.content;
+    }
+    if (typeof maybe.text === "string") return maybe.text;
+    if (maybe.content) return extractTextFromToolResponse(maybe.content);
+  }
+  return null;
+}
+
+/**
+ * Per-toolUseId handoff from the PostToolUse hook to `toolUpdateFromToolResult`.
+ * Can't emit a standalone `tool_call_update` because the SDK emits its own
+ * when it processes the tool_result, and the renderer applies it via
+ * `Object.assign` — our earlier update would be overwritten.
+ */
+export type EnrichedReadCache = Map<string, string>;
+
+export const createReadEnrichmentHook =
+  (deps: FileEnrichmentDeps, cache: EnrichedReadCache): HookCallback =>
+  async (input: HookInput) => {
+    if (input.hook_event_name !== "PostToolUse") return { continue: true };
+    if (input.tool_name !== "Read") return { continue: true };
+
+    const toolInput = input.tool_input as { file_path?: string } | undefined;
+    const filePath = toolInput?.file_path;
+    if (!filePath) return { continue: true };
+
+    const raw = extractTextFromToolResponse(input.tool_response);
+    if (!raw) return { continue: true };
+
+    const enriched = await enrichFileForAgent(
+      deps,
+      filePath,
+      stripCatLineNumbers(raw),
+    );
+    if (!enriched) return { continue: true };
+
+    if (input.tool_use_id) {
+      cache.set(input.tool_use_id, enriched);
+    }
+
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse" as const,
+        additionalContext: [
+          `## PostHog metadata for ${filePath}`,
+          "",
+          "The file below is annotated with live data from the user's PostHog project:",
+          "flag type / rollout / staleness / linked experiment, and for events the verification status,",
+          "30-day volume, and unique-user count. Treat these as authoritative product context —",
+          "they describe what is actually running in production.",
+          "",
+          enriched,
+        ].join("\n"),
+      },
+    };
+  };
+
 const toolUseCallbacks: {
   [toolUseId: string]: {
     onPostToolUseHook?: (
@@ -61,9 +154,6 @@ export const createPostToolUseHook =
           );
           delete toolUseCallbacks[toolUseID];
         } else {
-          logger?.error(
-            `No onPostToolUseHook found for tool use ID: ${toolUseID}`,
-          );
           delete toolUseCallbacks[toolUseID];
         }
       }

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

@@ -164,7 +164,8 @@ async function applyPlanApproval(
 
   if (
     response.outcome?.outcome === "selected" &&
-    (response.outcome.optionId === "default" ||
+    (response.outcome.optionId === "auto" ||
+      response.outcome.optionId === "default" ||
       response.outcome.optionId === "acceptEdits" ||
       response.outcome.optionId === "bypassPermissions")
   ) {

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

@@ -106,6 +106,11 @@ export function buildExitPlanModePermissionOptions(): PermissionOption[] {
   }
 
   options.push(
+    {
+      kind: "allow_always",
+      name: 'Yes, and use "auto" mode',
+      optionId: "auto",
+    },
     {
       kind: "allow_always",
       name: "Yes, and auto-accept edits",

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

@@ -30,14 +30,17 @@ const MODELS_WITH_EFFORT = new Set([
   "claude-sonnet-4-6",
 ]);
 
-const MODELS_WITH_MAX_EFFORT = new Set(["claude-opus-4-6", "claude-opus-4-7"]);
+const MODELS_WITH_XHIGH_EFFORT = new Set([
+  "claude-opus-4-6",
+  "claude-opus-4-7",
+]);
 
 export function supportsEffort(modelId: string): boolean {
   return MODELS_WITH_EFFORT.has(modelId);
 }
 
-export function supportsMaxEffort(modelId: string): boolean {
-  return MODELS_WITH_MAX_EFFORT.has(modelId);
+export function supportsXhighEffort(modelId: string): boolean {
+  return MODELS_WITH_XHIGH_EFFORT.has(modelId);
 }
 
 const MODELS_TO_EXCLUDE_MCP_TOOLS = new Set(["claude-haiku-4-5"]);
@@ -60,8 +63,11 @@ export function getEffortOptions(modelId: string): EffortOption[] | null {
     { value: "high", name: "High" },
   ];
 
-  if (supportsMaxEffort(modelId)) {
-    options.push({ value: "max", name: "Max" });
+  if (supportsXhighEffort(modelId)) {
+    options.push(
+      { value: "xhigh", name: "Extra High" },
+      { value: "max", name: "Max" },
+    );
   }
 
   return options;

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

@@ -10,12 +10,15 @@ import type {
   SpawnedProcess,
   SpawnOptions,
 } from "@anthropic-ai/claude-agent-sdk";
+import type { FileEnrichmentDeps } from "../../../enrichment/file-enricher";
 import { IS_ROOT } from "../../../utils/common";
 import type { Logger } from "../../../utils/logger";
 import {
   createPostToolUseHook,
   createPreToolUseHook,
+  createReadEnrichmentHook,
   createSubagentRewriteHook,
+  type EnrichedReadCache,
   type OnModeChange,
 } from "../hooks";
 import type { CodeExecutionMode } from "../tools";
@@ -49,6 +52,8 @@ export interface BuildOptionsParams {
   onProcessSpawned?: (info: ProcessSpawnedInfo) => void;
   onProcessExited?: (pid: number) => void;
   effort?: EffortLevel;
+  enrichmentDeps?: FileEnrichmentDeps;
+  enrichedReadCache?: EnrichedReadCache;
 }
 
 export function buildSystemPrompt(
@@ -100,6 +105,8 @@ function buildEnvironment(): Record<string, string> {
     CLAUDE_CODE_ENABLE_ASK_USER_QUESTION_TOOL: "true",
     // Offload all MCP tools by default
     ENABLE_TOOL_SEARCH: "auto:0",
+    // Enable idle state as end-of-turn signal (required for SDK 0.2.114+)
+    CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
   };
 }
 
@@ -108,14 +115,21 @@ function buildHooks(
   onModeChange: OnModeChange | undefined,
   settingsManager: SettingsManager,
   logger: Logger,
+  enrichmentDeps: FileEnrichmentDeps | undefined,
+  enrichedReadCache: EnrichedReadCache | undefined,
 ): Options["hooks"] {
+  const postToolUseHooks = [createPostToolUseHook({ onModeChange, logger })];
+  if (enrichmentDeps && enrichedReadCache) {
+    postToolUseHooks.push(
+      createReadEnrichmentHook(enrichmentDeps, enrichedReadCache),
+    );
+  }
+
   return {
     ...userHooks,
     PostToolUse: [
       ...(userHooks?.PostToolUse || []),
-      {
-        hooks: [createPostToolUseHook({ onModeChange, logger })],
-      },
+      { hooks: postToolUseHooks },
     ],
     PreToolUse: [
       ...(userHooks?.PreToolUse || []),
@@ -269,6 +283,8 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
       params.onModeChange,
       params.settingsManager,
       params.logger,
+      params.enrichmentDeps,
+      params.enrichedReadCache,
     ),
     outputFormat: params.outputFormat,
     abortController: getAbortController(

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

@@ -132,7 +132,13 @@ async function loadSettingsFile(
   try {
     const content = await fs.promises.readFile(filePath, "utf-8");
     return JSON.parse(content) as ClaudeCodeSettings;
-  } catch {
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return {};
+    }
+    process.stderr.write(
+      `[SettingsManager] Failed to load settings from ${filePath}: ${error}\n`,
+    );
     return {};
   }
 }
@@ -179,17 +185,20 @@ export class SettingsManager {
   private enterpriseSettings: ClaudeCodeSettings = {};
   private mergedSettings: ClaudeCodeSettings = {};
   private initialized = false;
+  private initPromise: Promise<void> | null = null;
 
   constructor(cwd: string) {
     this.cwd = cwd;
   }
 
   async initialize(): Promise<void> {
-    if (this.initialized) {
-      return;
-    }
-    await this.loadAllSettings();
-    this.initialized = true;
+    if (this.initialized) return;
+    if (this.initPromise) return this.initPromise;
+    this.initPromise = this.loadAllSettings().then(() => {
+      this.initialized = true;
+      this.initPromise = null;
+    });
+    return this.initPromise;
   }
 
   private getUserSettingsPath(): string {
@@ -311,9 +320,8 @@ export class SettingsManager {
   }
 
   async setCwd(cwd: string): Promise<void> {
-    if (this.cwd === cwd) {
-      return;
-    }
+    if (this.cwd === cwd) return;
+    if (this.initPromise) await this.initPromise;
     this.dispose();
     this.cwd = cwd;
     this.initialized = false;

package/src/adapters/claude/tools.ts

@@ -41,10 +41,10 @@ const BASE_ALLOWED_TOOLS = [
 ];
 
 const AUTO_ALLOWED_TOOLS: Record<string, Set<string>> = {
+  auto: new Set(BASE_ALLOWED_TOOLS),
   default: new Set(BASE_ALLOWED_TOOLS),
   acceptEdits: new Set([...BASE_ALLOWED_TOOLS, ...WRITE_TOOLS]),
   plan: new Set(BASE_ALLOWED_TOOLS),
-  // dontAsk: new Set(BASE_ALLOWED_TOOLS),
 };
 
 export function isToolAllowedForMode(

package/src/adapters/claude/types.ts

@@ -13,7 +13,7 @@ import type { BaseSession } from "../base-acp-agent";
 import type { SettingsManager } from "./session/settings";
 import type { CodeExecutionMode } from "./tools";
 
-export type EffortLevel = "low" | "medium" | "high" | "max";
+export type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
 
 export type AccumulatedUsage = {
   inputTokens: number;
@@ -62,6 +62,7 @@ export type Session = BaseSession & {
   promptRunning: boolean;
   pendingMessages: Map<string, PendingMessage>;
   nextPendingOrder: number;
+  emitRawSDKMessages: boolean | SDKMessageFilter[];
 };
 
 export type ToolUseCache = {
@@ -99,6 +100,11 @@ export type ToolUpdateMeta = {
   terminal_exit?: TerminalExit;
 };
 
+export type SDKMessageFilter = {
+  type: string;
+  subtype?: string;
+};
+
 export type NewSessionMeta = {
   taskRunId?: string;
   disableBuiltInTools?: boolean;
@@ -113,5 +119,6 @@ export type NewSessionMeta = {
   jsonSchema?: Record<string, unknown> | null;
   claudeCode?: {
     options?: Options;
+    emitRawSDKMessages?: boolean | SDKMessageFilter[];
   };
 };

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

@@ -41,6 +41,10 @@ import {
   POSTHOG_METHODS,
   POSTHOG_NOTIFICATIONS,
 } from "../../acp-extensions";
+import {
+  createEnrichment,
+  type Enrichment,
+} from "../../enrichment/file-enricher";
 import {
   type CodeExecutionMode,
   type CodexNativeMode,
@@ -48,7 +52,7 @@ import {
   isCodexNativeMode,
   type PermissionMode,
 } from "../../execution-mode";
-import type { ProcessSpawnedCallback } from "../../types";
+import type { PostHogAPIConfig, ProcessSpawnedCallback } from "../../types";
 import { Logger } from "../../utils/logger";
 import {
   nodeReadableToWebReadable,
@@ -86,6 +90,7 @@ interface NewSessionMeta {
 export interface CodexAcpAgentOptions {
   codexProcessOptions: CodexProcessOptions;
   processCallbacks?: ProcessSpawnedCallback;
+  posthogApiConfig?: PostHogAPIConfig;
 }
 
 type CodexSession = BaseSession & {
@@ -119,6 +124,7 @@ function prependPrContext(params: PromptRequest): PromptRequest {
 }
 
 const CODEX_NATIVE_MODE: Record<CodeExecutionMode, CodexNativeMode> = {
+  auto: "auto",
   default: "auto",
   acceptEdits: "auto",
   plan: "read-only",
@@ -168,6 +174,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
   // Snapshot of the initialize() request so refreshSession can replay the
   // same handshake against a respawned codex-acp subprocess.
   private lastInitRequest?: InitializeRequest;
+  private enrichment?: Enrichment;
 
   constructor(client: AgentSideConnection, options: CodexAcpAgentOptions) {
     super(client);
@@ -205,12 +212,16 @@ export class CodexAcpAgent extends BaseAcpAgent {
 
     this.sessionState = createSessionState("", cwd);
 
+    this.enrichment = createEnrichment(options.posthogApiConfig, this.logger);
+
     // Create the ClientSideConnection to codex-acp.
     // The Client handler delegates all requests from codex-acp to the upstream
     // PostHog Code client via our AgentSideConnection.
     this.codexConnection = new ClientSideConnection(
       (_agent) =>
-        createCodexClient(this.client, this.logger, this.sessionState),
+        createCodexClient(this.client, this.logger, this.sessionState, {
+          enrichmentDeps: this.enrichment?.deps,
+        }),
       codexStream,
     );
   }
@@ -672,5 +683,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
     } catch (err) {
       this.logger.warn("Failed to kill codex-acp process", { error: err });
     }
+    this.enrichment?.dispose();
+    this.enrichment = undefined;
   }
 }