Expose Codex subagent activity over ACP

Map subAgentActivity notifications to standard ACP tool calls with namespaced Codex metadata. Preserve collaboration model metadata and replay the same events when loading session history.

Author: nikita-ashihmin

README.md

@@ -12,6 +12,7 @@ Use [OpenAI Codex](https://github.com/openai/codex) from [Agent Client Protocol]
 - Model, reasoning effort, fast mode, approval, and sandbox mode configuration.
 - Text prompts, embedded context, images, resource links, and additional workspace directories.
 - Shell command, file change, permission request, MCP tool call, terminal output, reasoning, plan, web search, image generation, image view, token usage, and review events.
+- Subagent launches as standard ACP tool calls, with Codex thread identity and activity details in namespaced `_meta.codex.subagent` metadata.
 - Client-provided MCP servers over command-based stdio config and HTTP transport.
 - Slash commands: `/status`, `/mcp`, `/skills`, `/review`, `/review-branch`, `/review-commit`, `/compact`, and `/logout`, as well as configured skills.
 

src/CodexAcpServer.ts

@@ -60,6 +60,7 @@ import {
     createImageGenerationUpdate,
     createImageViewUpdate,
     createMcpToolCallUpdate,
+    createSubAgentActivityUpdate,
     formatWebSearchTitle,
 } from "./CodexToolCallMapper";
 import {
@@ -1179,9 +1180,10 @@ export class CodexAcpServer {
             case "userMessage":
                 return this.createUserMessageUpdates(item);
             case "hookPrompt":
-            case "subAgentActivity":
             case "sleep":
                 return [];
+            case "subAgentActivity":
+                return [createSubAgentActivityUpdate(item, "completed", "tool_call")];
             case "agentMessage": {
                 const meta = createCodexMessagePhaseMeta(item.phase);
                 return [{

src/CodexEventHandler.ts

@@ -51,6 +51,7 @@ import {
     createFuzzyFileSearchComplete,
     createFuzzyFileSearchStartOrUpdate,
     createMcpToolCallUpdate,
+    createSubAgentActivityUpdate,
     createWebSearchCompleteUpdate,
     createWebSearchStartUpdate,
     fuzzyFileSearchToolCallId,
@@ -79,6 +80,7 @@ export class CodexEventHandler {
     private readonly terminalCommandIds = new Set<string>();
     private readonly terminalCommandOutputIds = new Set<string>();
     private readonly agentMessagePhases = new Map<string, string | null>();
+    private readonly activeSubAgentActivities = new Set<string>();
 
     constructor(connection: AcpClientConnection, sessionState: SessionState) {
         this.connection = connection;
@@ -330,6 +332,8 @@ export class CodexEventHandler {
             case "contextCompaction":
                 return createContextCompactionStartUpdate(event.item);
             case "subAgentActivity":
+                this.activeSubAgentActivities.add(event.item.id);
+                return createSubAgentActivityUpdate(event.item, "in_progress", "tool_call");
             case "sleep":
             case "userMessage":
             case "hookPrompt":
@@ -387,7 +391,12 @@ export class CodexEventHandler {
             case "contextCompaction":
                 return createContextCompactionCompleteUpdate(event.item);
             //ignored types
-            case "subAgentActivity":
+            case "subAgentActivity": {
+                const sessionUpdate = this.activeSubAgentActivities.delete(event.item.id)
+                    ? "tool_call_update"
+                    : "tool_call";
+                return createSubAgentActivityUpdate(event.item, "completed", sessionUpdate);
+            }
             case "sleep":
             case "userMessage":
             case "hookPrompt":

src/CodexToolCallMapper.ts

@@ -40,6 +40,7 @@ type GuardianApprovalReviewNotification =
     | ItemGuardianApprovalReviewCompletedNotification;
 type WebSearchItem = ThreadItem & { type: "webSearch" };
 type CollabAgentToolCallItem = ThreadItem & { type: "collabAgentToolCall" };
+type SubAgentActivityItem = ThreadItem & { type: "subAgentActivity" };
 type CommandExecutionItem = ThreadItem & { type: "commandExecution" };
 type ContextCompactionItem = ThreadItem & { type: "contextCompaction" };
 type AcpToolCallEvent = Extract<UpdateSessionEvent, { sessionUpdate: "tool_call" }>;
@@ -412,6 +413,7 @@ export function createCollabAgentToolCallUpdate(
         title: item.tool,
         status: toAcpStatus(item.status),
         rawInput: createCollabAgentToolCallRawInput(item),
+        _meta: createCollabAgentToolCallMeta(item),
     };
 }
 
@@ -424,6 +426,7 @@ export function createCollabAgentToolCallCompleteUpdate(
         title: item.tool,
         status: toAcpStatus(item.status),
         rawInput: createCollabAgentToolCallRawInput(item),
+        _meta: createCollabAgentToolCallMeta(item),
     };
 }
 
@@ -433,10 +436,74 @@ function createCollabAgentToolCallRawInput(item: CollabAgentToolCallItem) {
         senderThreadId: item.senderThreadId,
         receiverThreadIds: item.receiverThreadIds,
         agentsStates: item.agentsStates,
+        model: item.model,
+        reasoningEffort: item.reasoningEffort,
         status: item.status,
     };
 }
 
+function createCollabAgentToolCallMeta(item: CollabAgentToolCallItem) {
+    return {
+        codex: {
+            collaboration: {
+                tool: item.tool,
+                senderThreadId: item.senderThreadId,
+                receiverThreadIds: item.receiverThreadIds,
+            },
+        },
+    };
+}
+
+export function createSubAgentActivityUpdate(
+    item: SubAgentActivityItem,
+    status: "in_progress" | "completed",
+    sessionUpdate: "tool_call" | "tool_call_update",
+): UpdateSessionEvent {
+    const name = item.agentPath.split("/").filter(Boolean).at(-1) ?? "subagent";
+    const title = formatSubAgentActivityTitle(item.kind, name);
+    const common = {
+        toolCallId: item.id,
+        status,
+        rawInput: {
+            agentThreadId: item.agentThreadId,
+            agentPath: item.agentPath,
+            activityKind: item.kind,
+        },
+        _meta: {
+            codex: {
+                subagent: {
+                    threadId: item.agentThreadId,
+                    path: item.agentPath,
+                    activity: item.kind,
+                },
+            },
+        },
+    };
+    if (sessionUpdate === "tool_call") {
+        return {
+            sessionUpdate,
+            title,
+            kind: "other",
+            ...common,
+        };
+    }
+    return {
+        sessionUpdate,
+        ...common,
+    };
+}
+
+function formatSubAgentActivityTitle(kind: SubAgentActivityItem["kind"], name: string): string {
+    switch (kind) {
+        case "started":
+            return `Start subagent ${name}`;
+        case "interacted":
+            return `Interact with subagent ${name}`;
+        case "interrupted":
+            return `Interrupt subagent ${name}`;
+    }
+}
+
 export function formatWebSearchTitle(item: WebSearchItem): string {
     const action = item.action;
     if (!action) {

src/__tests__/CodexACPAgent/collab-agent-events.test.ts

@@ -84,4 +84,30 @@ describe("CodexEventHandler - collab agent tool call events", () => {
             "data/collab-agent-tool-call-flow.json"
         );
     });
+
+    it("maps live subagent activity to an ACP tool call", async () => {
+        const notifications: ServerNotification[] = [
+            {
+                method: "item/completed",
+                params: {
+                    threadId: sessionId,
+                    turnId: "turn-1",
+                    completedAtMs: 0,
+                    item: {
+                        type: "subAgentActivity",
+                        id: "call-spawn-weather",
+                        kind: "started",
+                        agentThreadId: "thread-paris",
+                        agentPath: "/root/weather_research",
+                    },
+                },
+            },
+        ];
+
+        await setupPromptAndSendNotifications(mockFixture, sessionId, sessionState, notifications);
+
+        await expect(`${mockFixture.getAcpConnectionDump([])}\n`).toMatchFileSnapshot(
+            "data/subagent-activity-flow.json"
+        );
+    });
 });

src/__tests__/CodexACPAgent/data/collab-agent-tool-call-flow.json

@@ -21,7 +21,20 @@
               "message": "Checking weather"
             }
           },
+          "model": null,
+          "reasoningEffort": null,
           "status": "inProgress"
+        },
+        "_meta": {
+          "codex": {
+            "collaboration": {
+              "tool": "spawnAgent",
+              "senderThreadId": "thread-main",
+              "receiverThreadIds": [
+                "thread-paris"
+              ]
+            }
+          }
         }
       }
     }
@@ -49,7 +62,20 @@
               "message": null
             }
           },
+          "model": null,
+          "reasoningEffort": null,
           "status": "completed"
+        },
+        "_meta": {
+          "codex": {
+            "collaboration": {
+              "tool": "spawnAgent",
+              "senderThreadId": "thread-main",
+              "receiverThreadIds": [
+                "thread-paris"
+              ]
+            }
+          }
         }
       }
     }

src/__tests__/CodexACPAgent/data/load-session-history.json

@@ -400,4 +400,33 @@
       }
     }
   ]
+}
+{
+  "method": "sessionUpdate",
+  "args": [
+    {
+      "sessionId": "session-1",
+      "update": {
+        "sessionUpdate": "tool_call",
+        "title": "Start subagent test_audit",
+        "kind": "other",
+        "toolCallId": "item-subagent-1",
+        "status": "completed",
+        "rawInput": {
+          "agentThreadId": "thread-child-1",
+          "agentPath": "/root/test_audit",
+          "activityKind": "started"
+        },
+        "_meta": {
+          "codex": {
+            "subagent": {
+              "threadId": "thread-child-1",
+              "path": "/root/test_audit",
+              "activity": "started"
+            }
+          }
+        }
+      }
+    }
+  ]
 }

src/__tests__/CodexACPAgent/data/subagent-activity-flow.json

@@ -0,0 +1,29 @@
+{
+  "method": "sessionUpdate",
+  "args": [
+    {
+      "sessionId": "test-session-id",
+      "update": {
+        "sessionUpdate": "tool_call",
+        "title": "Start subagent weather_research",
+        "kind": "other",
+        "toolCallId": "call-spawn-weather",
+        "status": "completed",
+        "rawInput": {
+          "agentThreadId": "thread-paris",
+          "agentPath": "/root/weather_research",
+          "activityKind": "started"
+        },
+        "_meta": {
+          "codex": {
+            "subagent": {
+              "threadId": "thread-paris",
+              "path": "/root/weather_research",
+              "activity": "started"
+            }
+          }
+        }
+      }
+    }
+  ]
+}

src/__tests__/CodexACPAgent/load-session.test.ts

@@ -165,6 +165,13 @@ describe("CodexACPAgent - loadSession", () => {
                             type: "contextCompaction",
                             id: "item-context-compaction-1",
                         },
+                        {
+                            type: "subAgentActivity",
+                            id: "item-subagent-1",
+                            kind: "started",
+                            agentThreadId: "thread-child-1",
+                            agentPath: "/root/test_audit",
+                        },
                     ],
                 },
             ],