@posthog/agent 2.3.678 → 2.3.696

package/package.json

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

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

@@ -68,6 +68,14 @@ import { Pushable } from "../../utils/streams";
 import { BaseAcpAgent } from "../base-acp-agent";
 import { LOCAL_TOOLS_MCP_NAME } from "../local-tools";
 import { resolveTaskId } from "../session-meta";
+import {
+  buildBreakdown,
+  emptyBaseline,
+  estimateMcpTokens,
+  estimateRulesTokens,
+  estimateSkillsTokens,
+  estimateSystemPrompt,
+} from "./context-breakdown";
 import { promptToClaude } from "./conversion/acp-to-sdk";
 import {
   handleResultMessage,
@@ -79,6 +87,7 @@ import type { EnrichedReadCache } from "./hooks";
 import { createLocalToolsMcpServer } from "./mcp/local-tools";
 import {
   fetchMcpToolMetadata,
+  getCachedMcpTools,
   getConnectedMcpServerNames,
   setMcpToolApprovalStates,
 } from "./mcp/tool-metadata";
@@ -118,6 +127,22 @@ const SESSION_VALIDATION_TIMEOUT_MS = 30_000;
 const MAX_TITLE_LENGTH = 256;
 const LOCAL_ONLY_COMMANDS = new Set(["/context", "/heapdump", "/extra-usage"]);
 
+// Best-effort: silent on ENOENT, logs other errors so permission failures
+// aren't masked.
+function readClaudeMdQuietly(cwd: string, logger: Logger): string | undefined {
+  try {
+    return fs.readFileSync(path.join(cwd, "CLAUDE.md"), "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
+      logger.warn("Failed to read CLAUDE.md for context breakdown", {
+        cwd,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+    return undefined;
+  }
+}
+
 function sanitizeTitle(text: string): string {
   const sanitized = text
     .replace(/[\r\n]+/g, " ")
@@ -556,6 +581,12 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
               });
             }
 
+            // `result.usage` is cumulative across the agentic loop; the
+            // outermost-model stream snapshot is what's actually resident.
+            const breakdownInputTokens =
+              lastStreamUsage.input_tokens +
+              lastStreamUsage.cache_read_input_tokens +
+              lastStreamUsage.cache_creation_input_tokens;
             await this.client.extNotification(
               POSTHOG_NOTIFICATIONS.USAGE_UPDATE,
               {
@@ -567,6 +598,10 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
                   cachedWriteTokens: message.usage.cache_creation_input_tokens,
                 },
                 cost: message.total_cost_usd,
+                breakdown: buildBreakdown(
+                  this.session.contextBreakdownBaseline ?? emptyBaseline(),
+                  breakdownInputTokens,
+                ),
               },
             );
 
@@ -1221,6 +1256,11 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       pendingMessages: new Map(),
       nextPendingOrder: 0,
       emitRawSDKMessages: meta?.claudeCode?.emitRawSDKMessages ?? false,
+      contextBreakdownBaseline: {
+        ...emptyBaseline(),
+        systemPrompt: estimateSystemPrompt(systemPrompt),
+        rules: estimateRulesTokens(readClaudeMdQuietly(cwd, this.logger)),
+      },
 
       // Custom properties
       cwd,
@@ -1547,13 +1587,30 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
 
   private async sendAvailableCommandsUpdate(): Promise<void> {
     const commands = await this.session.query.supportedCommands();
+    const available = getAvailableSlashCommands(commands);
     await this.client.sessionUpdate({
       sessionId: this.sessionId,
       update: {
         sessionUpdate: "available_commands_update",
-        availableCommands: getAvailableSlashCommands(commands),
+        availableCommands: available,
       },
     });
+    this.updateBreakdownCategory("skills", estimateSkillsTokens(available));
+  }
+
+  /** Update one category of the context-breakdown baseline so the next
+   *  `_posthog/usage_update` carries fresher numbers. No-op when the baseline
+   *  hasn't been initialized yet (e.g. in a unit-test session). */
+  private updateBreakdownCategory(
+    key: keyof NonNullable<Session["contextBreakdownBaseline"]>,
+    tokens: number,
+  ): void {
+    if (!this.session?.contextBreakdownBaseline) return;
+    if (this.session.contextBreakdownBaseline[key] === tokens) return;
+    this.session.contextBreakdownBaseline = {
+      ...this.session.contextBreakdownBaseline,
+      [key]: tokens,
+    };
   }
 
   private async replaySessionHistory(sessionId: string): Promise<void> {
@@ -1610,6 +1667,10 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
         this.sendAvailableCommandsUpdate(),
       ),
       fetchMcpToolMetadata(q, this.logger).then(() => {
+        this.updateBreakdownCategory(
+          "mcp",
+          estimateMcpTokens(getCachedMcpTools()),
+        );
         const serverNames = getConnectedMcpServerNames();
         if (serverNames.length > 0) {
           this.options?.onMcpServersReady?.(serverNames);

package/src/adapters/claude/context-breakdown.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildBreakdown,
+  emptyBaseline,
+  estimateJsonTokens,
+  estimateMcpTokens,
+  estimateRulesTokens,
+  estimateSkillsTokens,
+  estimateSystemPrompt,
+  estimateTokens,
+} from "./context-breakdown";
+
+describe("estimateTokens", () => {
+  it("returns 0 for empty input", () => {
+    expect(estimateTokens("")).toBe(0);
+    expect(estimateTokens(undefined)).toBe(0);
+    expect(estimateTokens(null)).toBe(0);
+  });
+
+  it("scales roughly with input length", () => {
+    expect(estimateTokens("a".repeat(40))).toBe(10);
+    expect(estimateTokens("a".repeat(400))).toBe(100);
+  });
+});
+
+describe("estimateJsonTokens", () => {
+  it("counts JSON representation of objects", () => {
+    const tokens = estimateJsonTokens({ name: "Read", schema: { foo: 1 } });
+    expect(tokens).toBeGreaterThan(0);
+  });
+
+  it("returns 0 for non-serializable values", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    expect(estimateJsonTokens(circular)).toBe(0);
+  });
+});
+
+describe("estimateSystemPrompt", () => {
+  it("includes the Claude preset budget when preset is used", () => {
+    const noAppend = estimateSystemPrompt({ type: "preset" });
+    expect(noAppend).toBeGreaterThan(0);
+  });
+
+  it("adds the append portion on top of the preset", () => {
+    const append = "a".repeat(400);
+    const result = estimateSystemPrompt({ type: "preset", append });
+    const presetOnly = estimateSystemPrompt({ type: "preset" });
+    expect(result - presetOnly).toBe(100);
+  });
+
+  it("counts a raw string verbatim with no preset overhead", () => {
+    expect(estimateSystemPrompt("a".repeat(400))).toBe(100);
+  });
+
+  it("treats undefined as the bare preset", () => {
+    expect(estimateSystemPrompt(undefined)).toBe(
+      estimateSystemPrompt({ type: "preset" }),
+    );
+  });
+});
+
+describe("estimateSkillsTokens", () => {
+  it("is 0 for an empty command list", () => {
+    expect(estimateSkillsTokens([])).toBe(0);
+  });
+
+  it("counts the JSON of name/description/hint", () => {
+    // [{"name":"review","description":"Review a PR","hint":"[pr]"}] ~ 55 chars
+    const result = estimateSkillsTokens([
+      { name: "review", description: "Review a PR", input: { hint: "[pr]" } },
+    ]);
+    expect(result).toBeGreaterThan(10);
+    expect(result).toBeLessThan(20);
+  });
+});
+
+describe("estimateMcpTokens", () => {
+  it("is 0 for no connected tools", () => {
+    expect(estimateMcpTokens([])).toBe(0);
+  });
+
+  it("scales with tool count", () => {
+    const one = estimateMcpTokens([{ name: "get_user", description: "x" }]);
+    const many = estimateMcpTokens(
+      Array.from({ length: 50 }, (_, i) => ({
+        name: `tool_${i}`,
+        description: "x",
+      })),
+    );
+    expect(many).toBeGreaterThan(one * 10);
+  });
+});
+
+describe("estimateRulesTokens", () => {
+  it("is 0 for missing rules", () => {
+    expect(estimateRulesTokens(undefined)).toBe(0);
+    expect(estimateRulesTokens("")).toBe(0);
+  });
+
+  it("counts the rules content", () => {
+    expect(estimateRulesTokens("a".repeat(400))).toBe(100);
+  });
+});
+
+describe("buildBreakdown", () => {
+  it("derives conversation from input - stable sum", () => {
+    const baseline = {
+      ...emptyBaseline(),
+      systemPrompt: 4000,
+      tools: 500,
+    };
+    const result = buildBreakdown(baseline, 10_000);
+    expect(result.systemPrompt).toBe(4000);
+    expect(result.tools).toBe(500);
+    expect(result.conversation).toBe(5500);
+  });
+
+  it("floors conversation at 0 when stable pieces exceed input", () => {
+    const baseline = { ...emptyBaseline(), systemPrompt: 5000 };
+    expect(buildBreakdown(baseline, 1000).conversation).toBe(0);
+  });
+
+  it("includes zero categories", () => {
+    const result = buildBreakdown(emptyBaseline(), 100);
+    expect(result.mcp).toBe(0);
+    expect(result.skills).toBe(0);
+    expect(result.subagents).toBe(0);
+  });
+});

package/src/adapters/claude/context-breakdown.ts

@@ -0,0 +1,127 @@
+// Anthropic doesn't break `input_tokens` down by source; we estimate the bits
+// we control via a chars-per-token heuristic. Indicative, not invoice-grade.
+
+export type ContextCategory =
+  | "systemPrompt"
+  | "tools"
+  | "rules"
+  | "skills"
+  | "mcp"
+  | "subagents"
+  | "conversation";
+
+export type ContextBreakdown = Record<ContextCategory, number>;
+
+// The `claude_code` preset prompt is opaque to us; without this constant its
+// tokens would bleed into the Conversation bucket and skew the chart.
+const CLAUDE_PRESET_ESTIMATE_TOKENS = 4000;
+
+const CHARS_PER_TOKEN = 4;
+
+export function estimateTokens(text: string | undefined | null): number {
+  if (!text) return 0;
+  return Math.max(0, Math.round(text.length / CHARS_PER_TOKEN));
+}
+
+export function estimateJsonTokens(value: unknown): number {
+  try {
+    return estimateTokens(JSON.stringify(value));
+  } catch {
+    return 0;
+  }
+}
+
+interface SlashCommandLike {
+  name?: string;
+  description?: string;
+  input?: { hint?: string } | null;
+}
+
+export function estimateSkillsTokens(commands: SlashCommandLike[]): number {
+  if (!commands.length) return 0;
+  return estimateJsonTokens(
+    commands.map((c) => ({
+      name: c.name,
+      description: c.description,
+      hint: c.input?.hint,
+    })),
+  );
+}
+
+interface McpToolLike {
+  name?: string;
+  description?: string;
+}
+
+// The SDK relies on tool search rather than inlining full MCP schemas in the
+// prompt, so name + description is a conservative estimate of what's resident.
+export function estimateMcpTokens(tools: McpToolLike[]): number {
+  if (!tools.length) return 0;
+  return estimateJsonTokens(
+    tools.map((t) => ({ name: t.name, description: t.description })),
+  );
+}
+
+export function estimateRulesTokens(rules: string | undefined): number {
+  return estimateTokens(rules);
+}
+
+export interface ContextBreakdownBaseline {
+  systemPrompt: number;
+  tools: number;
+  rules: number;
+  skills: number;
+  mcp: number;
+  subagents: number;
+}
+
+export function emptyBaseline(): ContextBreakdownBaseline {
+  return {
+    systemPrompt: 0,
+    tools: 0,
+    rules: 0,
+    skills: 0,
+    mcp: 0,
+    subagents: 0,
+  };
+}
+
+export function estimateSystemPrompt(systemPrompt: unknown): number {
+  if (!systemPrompt) return CLAUDE_PRESET_ESTIMATE_TOKENS;
+  if (typeof systemPrompt === "string") return estimateTokens(systemPrompt);
+  if (typeof systemPrompt === "object") {
+    const obj = systemPrompt as { type?: string; append?: unknown };
+    const appendTokens =
+      typeof obj.append === "string" ? estimateTokens(obj.append) : 0;
+    if (obj.type === "preset") {
+      return CLAUDE_PRESET_ESTIMATE_TOKENS + appendTokens;
+    }
+    return appendTokens;
+  }
+  return 0;
+}
+
+// Conversation is floored at 0 so estimation drift in the stable categories
+// can't surface a negative bucket.
+export function buildBreakdown(
+  baseline: ContextBreakdownBaseline,
+  currentInputTokens: number,
+): ContextBreakdown {
+  const stableSum =
+    baseline.systemPrompt +
+    baseline.tools +
+    baseline.rules +
+    baseline.skills +
+    baseline.mcp +
+    baseline.subagents;
+  const conversation = Math.max(0, currentInputTokens - stableSum);
+  return {
+    systemPrompt: baseline.systemPrompt,
+    tools: baseline.tools,
+    rules: baseline.rules,
+    skills: baseline.skills,
+    mcp: baseline.mcp,
+    subagents: baseline.subagents,
+    conversation,
+  };
+}

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

@@ -95,6 +95,45 @@ describe("promptToClaude", () => {
     expect(JSON.stringify(attachRes)).toContain("KEEP_ATTACH");
   });
 
+  it("forwards base64 image blocks with supported MIME types", () => {
+    const result = promptToClaude({
+      sessionId: "session-1",
+      prompt: [
+        {
+          type: "image",
+          data: "ZmFrZQ==",
+          mimeType: "image/png",
+        } as PromptRequest["prompt"][number],
+      ],
+    });
+
+    expect(result.message.content).toEqual([
+      {
+        type: "image",
+        source: { type: "base64", data: "ZmFrZQ==", media_type: "image/png" },
+      },
+    ]);
+  });
+
+  it("replaces unsupported base64 image MIME types with a text notice", () => {
+    const result = promptToClaude({
+      sessionId: "session-1",
+      prompt: [
+        {
+          type: "image",
+          data: "ZmFrZQ==",
+          mimeType: "image/heic",
+        } as PromptRequest["prompt"][number],
+      ],
+    });
+
+    expect(result.message.content).toHaveLength(1);
+    expect(result.message.content[0]).toMatchObject({
+      type: "text",
+      text: expect.stringContaining("image/heic"),
+    });
+  });
+
   it("maps file URI-only image blocks to workspace Read prompt text", () => {
     const req: PromptRequest = {
       sessionId: "session-1",

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

@@ -3,24 +3,12 @@ import { fileURLToPath } from "node:url";
 import type { PromptRequest } from "@agentclientprotocol/sdk";
 import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { ContentBlockParam } from "@anthropic-ai/sdk/resources";
-
-type ImageMimeType = "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+import { isClaudeImageMimeType, isImageFile } from "@posthog/shared";
 
 const PDF_EXTENSIONS = new Set(["pdf"]);
 
-const COMMON_IMAGE_EXTENSIONS = new Set([
-  "png",
-  "jpg",
-  "jpeg",
-  "gif",
-  "webp",
-  "bmp",
-  "svg",
-  "heic",
-  "tif",
-  "tiff",
-]);
-
+// Video-only on purpose: audio formats get the default "large text" hint.
+// Do not replace with AUDIO_VIDEO_EXTENSIONS from @posthog/shared.
 const VIDEO_EXTENSIONS = new Set([
   "mp4",
   "mov",
@@ -53,7 +41,7 @@ export function readToolGuidanceForPath(filePath: string): string {
   if (PDF_EXTENSIONS.has(ext)) {
     return 'Optional `pages` string (e.g. "1-5") per Read call instead of loading the entire PDF.';
   }
-  if (COMMON_IMAGE_EXTENSIONS.has(ext) || VIDEO_EXTENSIONS.has(ext)) {
+  if (isImageFile(filePath) || VIDEO_EXTENSIONS.has(ext)) {
     return "Binary file — use Read with `file_path`; prefer bounded reads where supported.";
   }
   return "Large text — use multiple Read calls with optional `offset` and `limit`.";
@@ -131,14 +119,22 @@ function processPromptChunk(
 
     case "image":
       if (chunk.data) {
-        content.push({
-          type: "image",
-          source: {
-            type: "base64",
-            data: chunk.data,
-            media_type: chunk.mimeType as ImageMimeType,
-          },
-        });
+        if (isClaudeImageMimeType(chunk.mimeType)) {
+          content.push({
+            type: "image",
+            source: {
+              type: "base64",
+              data: chunk.data,
+              media_type: chunk.mimeType,
+            },
+          });
+        } else {
+          content.push(
+            sdkText(
+              `[Unsupported image MIME type: ${chunk.mimeType}. Supported: image/jpeg, image/png, image/gif, image/webp.]`,
+            ),
+          );
+        }
       } else if (chunk.uri?.startsWith("http")) {
         content.push({
           type: "image",

package/src/adapters/claude/mcp/tool-metadata.ts

@@ -116,6 +116,12 @@ export function getConnectedMcpServerNames(): string[] {
   return [...names];
 }
 
+/** Snapshot of every tool currently in the metadata cache. Used by the
+ *  context-breakdown estimator to size the MCP category. */
+export function getCachedMcpTools(): McpToolMetadata[] {
+  return [...mcpToolMetadataCache.values()];
+}
+
 export function getMcpToolApprovalState(
   toolName: string,
 ): McpToolApprovalState | undefined {

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 { ContextBreakdownBaseline } from "./context-breakdown";
 import type { McpToolApprovals } from "./mcp/tool-metadata";
 import type { SettingsManager } from "./session/settings";
 import type { CodeExecutionMode } from "./tools";
@@ -65,6 +66,8 @@ export type Session = BaseSession & {
   pendingMessages: Map<string, PendingMessage>;
   nextPendingOrder: number;
   emitRawSDKMessages: boolean | SDKMessageFilter[];
+  /** Refreshed at session init and on MCP/skill changes. */
+  contextBreakdownBaseline?: ContextBreakdownBaseline;
 };
 
 export type ToolUseCache = {

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

@@ -64,6 +64,12 @@ import {
   nodeWritableToWebWritable,
 } from "../../utils/streams";
 import { BaseAcpAgent, type BaseSession } from "../base-acp-agent";
+import {
+  buildBreakdown,
+  type ContextBreakdownBaseline,
+  emptyBaseline,
+  estimateTokens,
+} from "../claude/context-breakdown";
 import { classifyAgentError } from "../error-classification";
 import {
   enabledLocalTools,
@@ -76,6 +82,7 @@ import { normalizeCodexConfigOptions } from "./models";
 import {
   type CodexSessionState,
   createSessionState,
+  resetSessionState,
   resetUsage,
 } from "./session-state";
 import { CodexSettingsManager } from "./settings";
@@ -161,6 +168,19 @@ function classifyPromptError(error: unknown): unknown {
   );
 }
 
+// codex-rs/protocol/src/protocol.rs BASELINE_TOKENS — the always-resident
+// floor (MCP schemas, skills, preset prompt) we can't attribute per-source.
+const CODEX_BASELINE_TOKENS = 12000;
+
+function buildCodexBaseline(
+  meta: NewSessionMeta | undefined,
+): ContextBreakdownBaseline {
+  const baseline = emptyBaseline();
+  baseline.systemPrompt =
+    CODEX_BASELINE_TOKENS + estimateTokens(meta?.systemPrompt);
+  return baseline;
+}
+
 const CODEX_NATIVE_MODE: Record<CodeExecutionMode, CodexNativeMode> = {
   auto: "auto",
   default: "auto",
@@ -392,8 +412,10 @@ export class CodexAcpAgent extends BaseAcpAgent {
       response.configOptions,
     );
 
-    // Initialize session state
-    this.sessionState = createSessionState(response.sessionId, params.cwd, {
+    // Initialize session state. Mutate in place — codex-client closure-
+    // captured this object in the constructor and writes contextUsed/
+    // accumulatedUsage to it on every upstream usage_update.
+    resetSessionState(this.sessionState, response.sessionId, params.cwd, {
       taskRunId: meta?.taskRunId,
       taskId: resolveTaskId(meta),
       modeId: response.modes?.currentModeId ?? "auto",
@@ -402,6 +424,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
     });
     this.sessionId = response.sessionId;
     this.sessionState.configOptions = response.configOptions ?? [];
+    this.sessionState.contextBreakdownBaseline = buildCodexBaseline(meta);
 
     await this.applyInitialPermissionMode(
       response.sessionId,
@@ -445,7 +468,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
     // notifications (TURN_COMPLETE, USAGE_UPDATE) after a reload. newSession
     // and unstable_resumeSession both do this; loadSession historically did
     // not, which silently broke task-completion tracking on re-attach.
-    this.sessionState = createSessionState(params.sessionId, params.cwd, {
+    resetSessionState(this.sessionState, params.sessionId, params.cwd, {
       taskRunId: meta?.taskRunId,
       taskId: resolveTaskId(meta),
       modeId: response.modes?.currentModeId ?? "auto",
@@ -453,6 +476,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
     });
     this.sessionId = params.sessionId;
     this.sessionState.configOptions = response.configOptions ?? [];
+    this.sessionState.contextBreakdownBaseline = buildCodexBaseline(meta);
 
     if (meta?.taskRunId) {
       await this.client.extNotification(POSTHOG_NOTIFICATIONS.SDK_SESSION, {
@@ -491,7 +515,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
       loadResponse.modes?.currentModeId,
       meta?.permissionMode,
     );
-    this.sessionState = createSessionState(params.sessionId, params.cwd, {
+    resetSessionState(this.sessionState, params.sessionId, params.cwd, {
       taskRunId: meta?.taskRunId,
       taskId: resolveTaskId(meta),
       modeId: loadResponse.modes?.currentModeId ?? "auto",
@@ -499,6 +523,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
     });
     this.sessionId = params.sessionId;
     this.sessionState.configOptions = loadResponse.configOptions ?? [];
+    this.sessionState.contextBreakdownBaseline = buildCodexBaseline(meta);
 
     if (meta?.taskRunId) {
       await this.client.extNotification(POSTHOG_NOTIFICATIONS.SDK_SESSION, {
@@ -538,7 +563,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
     );
 
     const requestedPermissionMode = toCodexPermissionMode(meta?.permissionMode);
-    this.sessionState = createSessionState(newResponse.sessionId, params.cwd, {
+    resetSessionState(this.sessionState, newResponse.sessionId, params.cwd, {
       taskRunId: meta?.taskRunId,
       taskId: resolveTaskId(meta),
       modeId: newResponse.modes?.currentModeId ?? "auto",
@@ -546,6 +571,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
     });
     this.sessionId = newResponse.sessionId;
     this.sessionState.configOptions = newResponse.configOptions ?? [];
+    this.sessionState.contextBreakdownBaseline = buildCodexBaseline(meta);
 
     await this.applyInitialPermissionMode(
       newResponse.sessionId,
@@ -730,6 +756,21 @@ export class CodexAcpAgent extends BaseAcpAgent {
       }
     }
 
+    // Emit the per-source breakdown so the renderer's ContextBreakdownPopover
+    // has data to show. This fires regardless of `taskRunId` (local sessions
+    // need it too) and regardless of `response.usage` (codex-acp doesn't
+    // populate it — context size comes from upstream usage_update events,
+    // tracked on sessionState.contextUsed).
+    if (this.sessionState.contextUsed !== undefined) {
+      await this.client.extNotification(POSTHOG_NOTIFICATIONS.USAGE_UPDATE, {
+        sessionId: params.sessionId,
+        breakdown: buildBreakdown(
+          this.sessionState.contextBreakdownBaseline ?? emptyBaseline(),
+          this.sessionState.contextUsed,
+        ),
+      });
+    }
+
     return response;
   }