fix(agent): show Codex subagent activity

Generated-By: PostHog Code
Task-Id: d8f51f0f-0f93-47ef-9c93-4b70efc02672

Author: MattPua

packages/agent/src/adapters/codex-app-server/codex-app-server-agent.test.ts

@@ -143,7 +143,7 @@ describe("CodexAppServerAgent", () => {
     });
   });
 
-  it("isolates subagent output, usage, compaction, and completion", async () => {
+  it("surfaces subagent activity while isolating its lifecycle state", async () => {
     const stub = makeStubRpc({
       initialize: {},
       "thread/start": { thread: { id: "thr_1" } },
@@ -191,7 +191,6 @@ describe("CodexAppServerAgent", () => {
         prompt: "Review the implementation",
       },
     });
-    const sessionUpdateCount = sessionUpdates.length;
     const extNotificationCount = extNotifications.length;
 
     stub.emit("item/agentMessage/delta", {
@@ -215,6 +214,16 @@ describe("CodexAppServerAgent", () => {
         text: '{"source":"child"}',
       },
     });
+    stub.emit("item/started", {
+      threadId: "subagent_1",
+      turnId: "subagent_turn_1",
+      item: {
+        type: "commandExecution",
+        id: "shared_command_id",
+        command: "echo child",
+        status: "inProgress",
+      },
+    });
     stub.emit("item/commandExecution/outputDelta", {
       threadId: "subagent_1",
       turnId: "subagent_turn_1",
@@ -251,11 +260,9 @@ describe("CodexAppServerAgent", () => {
     expect({
       extNotifications: extNotifications.length,
       promptSettled,
-      sessionUpdates: sessionUpdates.length,
     }).toEqual({
       extNotifications: extNotificationCount,
       promptSettled: false,
-      sessionUpdates: sessionUpdateCount,
     });
 
     stub.emit("item/agentMessage/delta", {
@@ -292,10 +299,14 @@ describe("CodexAppServerAgent", () => {
     await expect(promptDone).resolves.toMatchObject({ stopReason: "end_turn" });
     const serializedUpdates = JSON.stringify(sessionUpdates);
     expect(serializedUpdates).toContain("spawn_agent");
+    expect(serializedUpdates).toContain("subagent prose");
+    expect(serializedUpdates).toContain("subagent reasoning");
+    expect(serializedUpdates).toContain("child command output");
+    expect(serializedUpdates).toContain(
+      "subagent:subagent_1:shared_command_id",
+    );
+    expect(serializedUpdates).toContain('"parentToolCallId":"spawn_1"');
     expect(serializedUpdates).toContain("parent response");
-    expect(serializedUpdates).not.toContain("subagent prose");
-    expect(serializedUpdates).not.toContain("subagent reasoning");
-    expect(serializedUpdates).not.toContain("child command output");
     expect(structuredOutputs).toEqual([{ source: "parent" }]);
     expect(
       extNotifications.filter(

packages/agent/src/adapters/codex-app-server/codex-app-server-agent.ts

@@ -15,6 +15,7 @@ import type {
   RequestPermissionResponse,
   ResumeSessionRequest,
   ResumeSessionResponse,
+  SessionNotification,
   SetSessionConfigOptionRequest,
   SetSessionConfigOptionResponse,
   StopReason,
@@ -236,6 +237,7 @@ export class CodexAppServerAgent extends BaseAcpAgent {
   /** Deployment environment; on "cloud" a non-danger sandbox would panic, so we skip the override. */
   private environment?: "local" | "cloud";
   private readonly commandOutputs = new Map<string, string>();
+  private readonly subagentParents = new Map<string, string>();
   /** Extra writable roots for this session, folded into workspaceWrite sandbox turns. */
   private additionalDirectories?: string[];
   /** The session workspace stays writable when extra roots are applied per turn. */
@@ -460,6 +462,7 @@ export class CodexAppServerAgent extends BaseAcpAgent {
   ): Promise<{ threadId: string; thread: AppServerThread | undefined }> {
     this.cancelNextGoalTurn = false;
     this.nativeGoalTurnId = undefined;
+    this.subagentParents.clear();
     this.jsonSchema = params.meta?.jsonSchema ?? undefined;
     this.taskRunId = params.meta?.taskRunId;
     this.environment = params.meta?.environment;
@@ -1159,6 +1162,7 @@ export class CodexAppServerAgent extends BaseAcpAgent {
 
   async closeSession(): Promise<void> {
     this.commandOutputs.clear();
+    this.subagentParents.clear();
     this.nativeGoalTurnId = undefined;
     this.session.abortController.abort();
     this.session.cancelled = true;
@@ -1178,23 +1182,25 @@ export class CodexAppServerAgent extends BaseAcpAgent {
     const notificationThreadId = readNotificationThreadId(params);
     const isMainThread =
       !notificationThreadId || notificationThreadId === this.threadId;
+    this.captureSubagentRelationship(method, params, notificationThreadId);
     const mappedParams = isMainThread
       ? this.withBufferedCommandOutput(method, params)
       : params;
 
     if (this.sessionId && !this.session.cancelled) {
-      if (isMainThread) {
-        const notification = mapAppServerNotification(
-          this.sessionId,
-          method,
-          mappedParams,
-        );
-        if (notification) {
-          void this.client
-            .sessionUpdate(notification)
-            .catch((err) => this.logger.warn("sessionUpdate failed", err));
-          this.appendNotification(this.sessionId, notification);
-        }
+      const notification = mapAppServerNotification(
+        this.sessionId,
+        method,
+        mappedParams,
+      );
+      const visibleNotification = isMainThread
+        ? notification
+        : this.mapSubagentNotification(notification, notificationThreadId);
+      if (visibleNotification) {
+        void this.client
+          .sessionUpdate(visibleNotification)
+          .catch((err) => this.logger.warn("sessionUpdate failed", err));
+        this.appendNotification(this.sessionId, visibleNotification);
       }
     }
 
@@ -1307,6 +1313,87 @@ export class CodexAppServerAgent extends BaseAcpAgent {
     }
   }
 
+  private captureSubagentRelationship(
+    method: string,
+    params: unknown,
+    senderThreadId: string | undefined,
+  ): void {
+    if (
+      method !== APP_SERVER_NOTIFICATIONS.ITEM_STARTED &&
+      method !== APP_SERVER_NOTIFICATIONS.ITEM_COMPLETED
+    ) {
+      return;
+    }
+    const item = (params as { item?: AppServerItem })?.item;
+    if (
+      item?.type !== "collabAgentToolCall" ||
+      item.tool !== "spawnAgent" ||
+      !item.id ||
+      !item.receiverThreadIds?.length
+    ) {
+      return;
+    }
+    const parentToolCallId =
+      senderThreadId && senderThreadId !== this.threadId
+        ? subagentToolCallId(senderThreadId, item.id)
+        : item.id;
+    for (const receiverThreadId of item.receiverThreadIds) {
+      this.subagentParents.set(receiverThreadId, parentToolCallId);
+    }
+  }
+
+  private mapSubagentNotification(
+    notification: SessionNotification | null,
+    threadId: string | undefined,
+  ): SessionNotification | null {
+    if (!notification || !threadId) return null;
+    const parentToolCallId = this.subagentParents.get(threadId);
+    if (!parentToolCallId) return null;
+    const update = notification.update as SessionNotification["update"] & {
+      _meta?: Record<string, unknown>;
+      toolCallId?: string;
+    };
+    if (
+      update.sessionUpdate !== "agent_message_chunk" &&
+      update.sessionUpdate !== "agent_thought_chunk" &&
+      update.sessionUpdate !== "tool_call" &&
+      update.sessionUpdate !== "tool_call_update"
+    ) {
+      return null;
+    }
+    const toolCallId = update.toolCallId
+      ? subagentToolCallId(threadId, update.toolCallId)
+      : undefined;
+    if (update.sessionUpdate === "tool_call_update") {
+      return {
+        ...notification,
+        update: { ...update, ...(toolCallId ? { toolCallId } : {}) },
+      } as SessionNotification;
+    }
+    const existingPosthog = (update._meta?.posthog ?? {}) as Record<
+      string,
+      unknown
+    >;
+    return {
+      ...notification,
+      update: {
+        ...update,
+        ...(toolCallId ? { toolCallId } : {}),
+        _meta: {
+          ...update._meta,
+          posthog: {
+            toolName:
+              typeof existingPosthog.toolName === "string"
+                ? existingPosthog.toolName
+                : "subagent_activity",
+            ...existingPosthog,
+            parentToolCallId,
+          },
+        },
+      },
+    } as SessionNotification;
+  }
+
   private withBufferedCommandOutput(method: string, params: unknown): unknown {
     if (!params || typeof params !== "object") {
       return params;
@@ -1718,6 +1805,10 @@ function readNotificationThreadId(params: unknown): string | undefined {
   return typeof threadId === "string" ? threadId : undefined;
 }
 
+function subagentToolCallId(threadId: string, toolCallId: string): string {
+  return `subagent:${threadId}:${toolCallId}`;
+}
+
 /** The codex thread config override map: folds in MCP servers + makes extra workspace roots writable. Undefined when empty. */
 function buildThreadConfig(
   mcpServers: ReturnType<typeof toCodexMcpServers>,

packages/shared/src/index.ts

@@ -275,6 +275,7 @@ export {
   readAgentToolName,
   readMcpToolDescriptor,
   readMcpToolName,
+  readParentToolCallId,
 } from "./tool-meta";
 export { TypedEventEmitter } from "./typed-event-emitter";
 export { isSafeExternalUrl } from "./url";

packages/shared/src/tool-meta.test.ts

@@ -4,6 +4,7 @@ import {
   readAgentToolName,
   readMcpToolDescriptor,
   readMcpToolName,
+  readParentToolCallId,
 } from "./tool-meta";
 
 describe("parseMcpToolName", () => {
@@ -49,6 +50,25 @@ describe("readAgentToolName", () => {
   });
 });
 
+describe("readParentToolCallId", () => {
+  it("prefers the posthog channel over the legacy claudeCode fallback", () => {
+    expect(
+      readParentToolCallId({
+        posthog: { toolName: "Bash", parentToolCallId: "parent-1" },
+        claudeCode: { parentToolCallId: "stale" },
+      }),
+    ).toBe("parent-1");
+  });
+
+  it("falls back to claudeCode when posthog is absent", () => {
+    expect(
+      readParentToolCallId({
+        claudeCode: { parentToolCallId: "parent-2" },
+      }),
+    ).toBe("parent-2");
+  });
+});
+
 describe("readMcpToolDescriptor / readMcpToolName", () => {
   it("uses the structured mcp descriptor when present (no name parsing)", () => {
     const meta = {

packages/shared/src/tool-meta.ts

@@ -12,6 +12,8 @@ export interface PosthogToolMeta {
   toolName: string;
   /** Set only for MCP tool calls — the originating server + tool. */
   mcp?: { server: string; tool: string };
+  /** Parent subagent tool call for nested activity. */
+  parentToolCallId?: string;
 }
 
 /** `_meta` fragment for adapters to spread onto a tool_call update. */
@@ -45,7 +47,7 @@ export function parseMcpToolName(
 interface ToolCallMeta {
   posthog?: PosthogToolMeta;
   /** Legacy Claude-adapter channel, read only as a fallback. */
-  claudeCode?: { toolName?: string };
+  claudeCode?: { toolName?: string; parentToolCallId?: string };
 }
 
 function asToolCallMeta(meta: unknown): ToolCallMeta | undefined {
@@ -58,6 +60,12 @@ export function readAgentToolName(meta: unknown): string | undefined {
   return m?.posthog?.toolName ?? m?.claudeCode?.toolName;
 }
 
+/** Parent subagent tool call: neutral channel first, legacy fallback. */
+export function readParentToolCallId(meta: unknown): string | undefined {
+  const m = asToolCallMeta(meta);
+  return m?.posthog?.parentToolCallId ?? m?.claudeCode?.parentToolCallId;
+}
+
 /**
  * The MCP `{ server, tool }` descriptor for a tool call, or undefined for a
  * non-MCP call. Prefers the structured channel, else parses the legacy

packages/ui/src/features/sessions/components/buildConversationItems.ts

@@ -12,6 +12,7 @@ import {
   isJsonRpcNotification,
   isJsonRpcRequest,
   isJsonRpcResponse,
+  readParentToolCallId,
   type UserShellExecuteParams,
 } from "@posthog/shared";
 import {
@@ -747,10 +748,7 @@ function extractUserPrompt(params: unknown): {
 }
 
 function getParentToolCallId(update: SessionUpdate): string | undefined {
-  const meta = (update as Record<string, unknown>)?._meta as
-    | { claudeCode?: { parentToolCallId?: string } }
-    | undefined;
-  return meta?.claudeCode?.parentToolCallId;
+  return readParentToolCallId((update as Record<string, unknown>)._meta);
 }
 
 function pushChildItem(b: ItemBuilder, parentId: string, update: RenderItem) {

packages/ui/src/features/sessions/components/incrementalConversationItems.test.ts

@@ -475,4 +475,34 @@ describe("createIncrementalConversationBuilder", () => {
     expect(row2.turnContext.childItems).not.toBe(row1.turnContext.childItems);
     expect(row2.turnContext.childItems.get("agent1")?.length).toBe(1);
   });
+
+  it("groups canonical PostHog child metadata under its subagent", () => {
+    const inc = createIncrementalConversationBuilder();
+    const messages = [
+      userPromptMsg(1, 1, "go"),
+      toolCallMsg(2, "agent1", {
+        _meta: { posthog: { toolName: "spawn_agent" } },
+      }),
+      updateMsg(3, {
+        sessionUpdate: "tool_call",
+        toolCallId: "child1",
+        kind: "read",
+        status: "pending",
+        title: "child1",
+        _meta: {
+          posthog: {
+            toolName: "subagent_activity",
+            parentToolCallId: "agent1",
+          },
+        },
+      }),
+    ];
+
+    const result = inc.update(messages, true);
+    const row = result.items.find((item) => item.type === "session_update");
+    if (row?.type !== "session_update") {
+      throw new Error("expected agent session_update row");
+    }
+    expect(row.turnContext.childItems.get("agent1")?.length).toBe(1);
+  });
 });