Render Codex subagent tool calls (#210)

* feat: render Codex subagent tool calls

* chore: format Codex subagent rendering tests

Author: 0xSolarPunk

common/chat-types.ts

@@ -212,6 +212,56 @@ export class TaskToolUseMessage {
   ) {}
 }
 
+export const CODEX_SUBAGENT_ACTIONS = [
+  'spawn_agent',
+  'send_input',
+  'send_message',
+  'followup_task',
+  'wait_agent',
+  'interrupt_agent',
+  'list_agents',
+  'close_agent',
+  'resume_agent',
+] as const;
+
+export type CodexSubagentAction = (typeof CODEX_SUBAGENT_ACTIONS)[number];
+
+export interface CodexSubagentInputItem {
+  type?: string;
+  text?: string;
+  imageUrl?: string;
+  path?: string;
+  name?: string;
+}
+
+export interface CodexSubagentDetails {
+  target?: string;
+  targets?: string[];
+  message?: string;
+  taskName?: string;
+  agentType?: string;
+  model?: string;
+  reasoningEffort?: string;
+  serviceTier?: string;
+  forkContext?: boolean;
+  forkTurns?: string;
+  timeoutMs?: number;
+  pathPrefix?: string;
+  interrupt?: boolean;
+  items?: CodexSubagentInputItem[];
+}
+
+export class CodexSubagentToolUseMessage {
+  readonly type = 'codex-subagent-tool-use' as const;
+
+  constructor(
+    public timestamp: string,
+    public toolId: string,
+    public action: CodexSubagentAction,
+    public details: CodexSubagentDetails = {},
+  ) {}
+}
+
 export class UpdatePlanToolUseMessage {
   readonly type = 'update-plan-tool-use' as const;
 
@@ -514,6 +564,7 @@ export type ToolUseChatMessage =
   | TodoWriteToolUseMessage
   | TodoReadToolUseMessage
   | TaskToolUseMessage
+  | CodexSubagentToolUseMessage
   | UpdatePlanToolUseMessage
   | WriteStdinToolUseMessage
   | EnterPlanModeToolUseMessage
@@ -701,6 +752,53 @@ function asOptionalChanges(v: unknown): Array<{ path?: string; kind?: string }>
   return undefined;
 }
 
+const CODEX_SUBAGENT_ACTION_SET = new Set<string>(CODEX_SUBAGENT_ACTIONS);
+
+function asCodexSubagentAction(v: unknown): CodexSubagentAction | undefined {
+  return typeof v === 'string' && CODEX_SUBAGENT_ACTION_SET.has(v)
+    ? v as CodexSubagentAction
+    : undefined;
+}
+
+function asCodexSubagentInputItems(v: unknown): CodexSubagentInputItem[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const items: CodexSubagentInputItem[] = [];
+  for (const entry of v) {
+    const raw = asRecord(entry);
+    const item: CodexSubagentInputItem = {};
+    if (typeof raw.type === 'string') item.type = raw.type;
+    if (typeof raw.text === 'string') item.text = raw.text;
+    if (typeof raw.imageUrl === 'string') item.imageUrl = raw.imageUrl;
+    if (typeof raw.path === 'string') item.path = raw.path;
+    if (typeof raw.name === 'string') item.name = raw.name;
+    if (Object.keys(item).length > 0) items.push(item);
+  }
+  return items.length > 0 || v.length === 0 ? items : undefined;
+}
+
+function asCodexSubagentDetails(v: unknown): CodexSubagentDetails {
+  const raw = asRecord(v);
+  const details: CodexSubagentDetails = {};
+  if (typeof raw.target === 'string') details.target = raw.target;
+  const targets = asStringArray(raw.targets);
+  if (targets !== undefined) details.targets = targets;
+  if (typeof raw.message === 'string') details.message = raw.message;
+  if (typeof raw.taskName === 'string') details.taskName = raw.taskName;
+  if (typeof raw.agentType === 'string') details.agentType = raw.agentType;
+  if (typeof raw.model === 'string') details.model = raw.model;
+  if (typeof raw.reasoningEffort === 'string') details.reasoningEffort = raw.reasoningEffort;
+  if (typeof raw.serviceTier === 'string') details.serviceTier = raw.serviceTier;
+  if (typeof raw.forkContext === 'boolean') details.forkContext = raw.forkContext;
+  if (typeof raw.forkTurns === 'string') details.forkTurns = raw.forkTurns;
+  const timeoutMs = asOptionalNumber(raw.timeoutMs);
+  if (timeoutMs !== undefined) details.timeoutMs = timeoutMs;
+  if (typeof raw.pathPrefix === 'string') details.pathPrefix = raw.pathPrefix;
+  if (typeof raw.interrupt === 'boolean') details.interrupt = raw.interrupt;
+  const items = asCodexSubagentInputItems(raw.items);
+  if (items !== undefined) details.items = items;
+  return details;
+}
+
 type ToolUseMessageType = ToolUseChatMessage['type'];
 type ToolUseMessageParser = (data: Record<string, unknown>) => ToolUseChatMessage | null;
 
@@ -794,6 +892,15 @@ const TOOL_USE_MESSAGE_PARSERS = {
       asOptionalString(data.model),
       asOptionalString(data.resume)),
 
+  'codex-subagent-tool-use': (data) => {
+    const action = asCodexSubagentAction(data.action);
+    if (action === undefined) return null;
+    return new CodexSubagentToolUseMessage(
+      str(data.timestamp), str(data.toolId),
+      action,
+      asCodexSubagentDetails(data.details));
+  },
+
   'update-plan-tool-use': (data) =>
     new UpdatePlanToolUseMessage(
       str(data.timestamp), str(data.toolId),

screenshots/codex-subagent-tool-desktop.png

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'bun:test';
 import { convertCodexFunctionCall, convertCodexCustomToolCall } from '../jsonl-tool-use-converter.js';
 import {
   BashToolUseMessage,
+  CodexSubagentToolUseMessage,
   EditToolUseMessage,
   WriteStdinToolUseMessage,
   UpdatePlanToolUseMessage,
@@ -92,6 +93,37 @@ describe('convertCodexFunctionCall', () => {
     ]);
   });
 
+  it('maps spawn_agent to CodexSubagentToolUseMessage', () => {
+    const msg = convertCodexFunctionCall(TS, {
+      name: 'spawn_agent',
+      arguments: '{"task_name":"review-auth","message":"Review auth boundaries","model":"gpt-5.5","fork_turns":"all"}',
+      call_id: 'call-subagent',
+    });
+    expect(msg).toBeInstanceOf(CodexSubagentToolUseMessage);
+    expect(msg.type).toBe('codex-subagent-tool-use');
+    expect(msg.action).toBe('spawn_agent');
+    expect(msg.details).toEqual({
+      message: 'Review auth boundaries',
+      taskName: 'review-auth',
+      model: 'gpt-5.5',
+      forkTurns: 'all',
+    });
+  });
+
+  it('maps namespaced v1 subagent tools to CodexSubagentToolUseMessage', () => {
+    const msg = convertCodexFunctionCall(TS, {
+      name: 'multi_agent_v1.wait_agent',
+      arguments: '{"target":"/root/review-auth","timeout_ms":5000}',
+      call_id: 'call-subagent-v1',
+    });
+    expect(msg).toBeInstanceOf(CodexSubagentToolUseMessage);
+    expect(msg.action).toBe('wait_agent');
+    expect(msg.details).toEqual({
+      target: '/root/review-auth',
+      timeoutMs: 5000,
+    });
+  });
+
   it('passes through unmapped function names as Unknown', () => {
     const msg = convertCodexFunctionCall(TS, {
       name: 'some_new_tool',

screenshots/codex-subagent-tool-mobile.png

@@ -3,7 +3,7 @@ import { EventEmitter } from 'events';
 import { promises as fs } from 'fs';
 import os from 'os';
 import path from 'path';
-import { PermissionRequestMessage, PermissionResolvedMessage } from '../../../../../common/chat-types.js';
+import { CodexSubagentToolUseMessage, PermissionRequestMessage, PermissionResolvedMessage } from '../../../../../common/chat-types.js';
 import { buildApprovalResponse, createPendingApproval } from '../approvals.ts';
 import { CodexAppServerClient } from '../client.ts';
 import { convertCodexAppServerItem, convertCodexAppServerLiveItem } from '../converter.ts';
@@ -462,6 +462,35 @@ describe('Codex app-server converter', () => {
       'tool-result',
     ]);
   });
+
+  it('maps Codex subagent dynamic tool calls to explicit tool-use messages', () => {
+    const items = [
+      { type: 'dynamicToolCall', id: 'd-sub-1', namespace: null, tool: 'spawn_agent', arguments: { task_name: 'review-auth', message: 'Review auth boundaries', model: 'gpt-5.5' }, status: 'completed', contentItems: [{ type: 'text', text: 'spawned /root/review-auth' }], success: true, durationMs: 10 },
+      { type: 'dynamicToolCall', id: 'd-sub-2', namespace: null, tool: 'multi_agent_v1.send_input', arguments: { target: '/root/review-auth', items: [{ type: 'text', text: 'Please inspect converter.ts' }] }, status: 'completed', contentItems: [], success: true, durationMs: 10 },
+    ];
+
+    const messages = items.flatMap((item) => convertCodexAppServerItem(item, '2026-02-21T10:00:00.000Z'));
+
+    expect(messages.map((message) => message.type)).toEqual([
+      'codex-subagent-tool-use',
+      'tool-result',
+      'codex-subagent-tool-use',
+      'tool-result',
+    ]);
+    expect(messages[0]).toBeInstanceOf(CodexSubagentToolUseMessage);
+    expect(messages[0].action).toBe('spawn_agent');
+    expect(messages[0].details).toEqual({
+      message: 'Review auth boundaries',
+      taskName: 'review-auth',
+      model: 'gpt-5.5',
+    });
+    expect(messages[2]).toBeInstanceOf(CodexSubagentToolUseMessage);
+    expect(messages[2].action).toBe('send_input');
+    expect(messages[2].details).toEqual({
+      target: '/root/review-auth',
+      items: [{ type: 'text', text: 'Please inspect converter.ts' }],
+    });
+  });
 });
 
 describe('Codex app-server approvals', () => {

server/agents/codex/__tests__/jsonl-tool-use-converter.test.js

@@ -24,6 +24,7 @@ import {
 } from "../../../../common/chat-types.js";
 import { stripResolvedFileMentionContext } from "../../shared/file-mention-context.js";
 import { normalizeTodoItems, normalizeToolInput, normalizeToolResultContent } from "../../shared/normalize-util.js";
+import { convertCodexSubagentToolUse } from '../subagent-tool-use.js';
 import type { CodexThreadItem, CodexUserInput, CodexWebSearchAction } from './protocol.js';
 
 export interface ConvertCodexAppServerItemOptions {
@@ -186,6 +187,9 @@ function convertKnownDynamicTool(
   tool: string,
   input: Record<string, unknown>,
 ): ChatMessage | null {
+  const subagentToolUse = convertCodexSubagentToolUse(timestamp, id, tool, input);
+  if (subagentToolUse) return subagentToolUse;
+
   switch (tool) {
     case 'shell_command':
     case 'exec_command':

server/agents/codex/app-server/__tests__/app-server.test.js

@@ -11,6 +11,7 @@ import {
   type ToolUseChatMessage,
 } from '../../../common/chat-types.js';
 import { normalizeToolInput, normalizeTodoItems } from '../shared/normalize-util.js';
+import { convertCodexSubagentToolUse } from './subagent-tool-use.js';
 
 interface ApplyPatchPayload {
   file_path: string;
@@ -37,6 +38,10 @@ export function convertCodexFunctionCall(ts: string, payload: unknown): ToolUseC
   const rawName = typeof rawPayload.name === 'string' ? rawPayload.name : 'unknown';
   const callId = typeof rawPayload.call_id === 'string' ? rawPayload.call_id : '';
   const rawArgs = rawPayload.arguments;
+  const input = asObject(normalizeToolInput(rawArgs));
+
+  const subagentToolUse = convertCodexSubagentToolUse(ts, callId, rawName, input);
+  if (subagentToolUse) return subagentToolUse;
 
   if (rawName === 'shell_command' || rawName === 'exec_command') {
     let command: string | undefined;
@@ -58,15 +63,14 @@ export function convertCodexFunctionCall(ts: string, payload: unknown): ToolUseC
   }
 
   if (rawName === 'write_stdin') {
-    return new WriteStdinToolUseMessage(ts, callId, asObject(normalizeToolInput(rawArgs)));
+    return new WriteStdinToolUseMessage(ts, callId, input);
   }
 
   if (rawName === 'update_plan') {
-    const input = asObject(normalizeToolInput(rawArgs));
     return new UpdatePlanToolUseMessage(ts, callId, normalizeTodoItems(input.items ?? input.todos ?? input.plan));
   }
 
-  return new UnknownToolUseMessage(ts, callId, rawName, asObject(normalizeToolInput(rawArgs)));
+  return new UnknownToolUseMessage(ts, callId, rawName, input);
 }
 
 /**