Codex subagent notifications render as user prompts instead of structured agent state #291

Activity

1. Juliusolsson05

   added

   bugSomething isn't workingSomething isn't working

   provider:codexAffects Codex integrationAffects Codex integration

   on Jun 18, 2026
2. Juliusolsson05 commented on Jun 18, 2026

   

   Juliusolsson05

   on Jun 18, 2026

   OwnerAuthor

   More actions

   Research update: Codex subagent rendering and immediate ownership fix

   This is a read-only investigation from the latest debug bundle and current code. The bundle note is the right anchor:

   /Users/juliusolsson/.config/agent-code/debug-bundles/manual/2026-06-18T11-12-28-535-21c515e9/note.json
   note: "Not handling codex subagents at all."
   

   Confirmed bug

   Codex persists subagent completion notifications as response_item messages with role: "user" and an input_text block starting with <subagent_notification>. Agent Code maps any Codex message with role user|assistant into a normal feed Entry, so these model-visible session-state fragments render as human user prompts.

   Relevant mapper path:

   • src/renderer/src/workspace/codex/rollout.ts
     • codexConversationEntryFromMessageItem() maps payload.type === "message" and role user|assistant into conversation rows.
     • Existing synthetic filters only drop AGENTS.md and <environment_context> bootstrap blocks.
     • There is no <subagent_notification> filter.

   This must be fixed at the mapper/state layer, not hidden in React/CSS. Otherwise runtime entries, history replay, session preview, copy/debug surfaces, and counts remain polluted.

   Bundle/rollout evidence

   Parent rollout:

   /Users/juliusolsson/.codex/sessions/2026/06/17/rollout-2026-06-17T14-31-08-019ed590-5e7c-7a23-8e26-5fa45bca76c1.jsonl
   

   The latest bundle snapshot says:

   kind: codex
   runtime subAgents: 0
   totalEntries: 835
   runtime window entries: 160
   streamPhase: requesting
   semanticLog: 200
   

   But the parent rollout contains subagent activity. It has spawn_agent calls, wait_agent outputs, and persisted <subagent_notification> messages:

   line 949: response_item:message role=user, starts with <subagent_notification>, len 9572
   line 956: response_item:message role=user, starts with <subagent_notification>, len 5132
   line 963: response_item:message role=user, starts with <subagent_notification>, len 8435
   line 969: response_item:message role=user, starts with <subagent_notification>, len 8006
   line 994: response_item:message role=user, starts with <subagent_notification>, len 7092
   

   Example shape:

   {
     "type": "response_item",
     "payload": {
       "type": "message",
       "role": "user",
       "content": [
         {
           "type": "input_text",
           "text": "<subagent_notification>\n{\"agent_path\":\"019eda6c-...\",\"status\":{\"completed\":\"...\"}}\n</subagent_notification>"
         }
       ]
     }
   }

   Upstream Codex source confirms these are contextual fragments, not user intent:

   • vendor/codex-src/codex-rs/core/src/contextual_user_message.rs defines the subagent notification tags.
   • vendor/codex-src/codex-rs/core/src/session_prefix.rs formats { agent_path, status } and comments that these are model-visible session-state fragments, not human prompts.

   Existing Claude subagent system is not provider-neutral

   Claude flow today:

   • src/main/subagents/index.ts derives <providerSessionId>/subagents/ from a Claude parent .jsonl path.
   • SubAgentWatcher tails agent-*.jsonl and agent-*.meta.json.
   • The join key is meta.toolUseId === parent Agent tool_use.id.
   • SubAgentState is keyed by that parent toolUseId.
   • Renderer lookup is subAgents[block.id] inside TaskSubagentRow.
   • ConversationRow groups adjacent assistant blocks only when tool_use.name === "Agent".
   • Block.tsx currently routes Codex tool_use blocks to Codex rows before the Claude Agent special case, so even a synthetic Codex Agent tool_use would not automatically use TaskSubagentRow yet.

   Reusable parts:

   • runtime.subAgents
   • session:sub-agents full-map IPC shape, if generalized
   • SubAgentsContext
   • SubagentGroupHeader
   • TaskSubagentRow / SubagentMiniFeed as presentation primitives
   • capped tool-call timeline and droppedToolCalls

   Must be generalized:

   • toolUseId cannot remain the only join key.
   • Spawn detection cannot be hard-coded to Claude Agent tool_use blocks.
   • Data producers must split by provider: Claude watches subagents/; Codex indexes rollout files.

   Codex gives enough structure to build this properly

   Child rollouts under /Users/juliusolsson/.codex/sessions/2026/06/18/ contain structured subagent metadata in session_meta.payload.source.subagent.thread_spawn:

   {
     "subagent": {
       "thread_spawn": {
         "parent_thread_id": "019ed590-5e7c-7a23-8e26-5fa45bca76c1",
         "depth": 1,
         "agent_path": null,
         "agent_nickname": "Cicero",
         "agent_role": "explorer"
       }
     }
   }

   The same child id appears in multiple places:

   • parent spawn_agent output: output.agent_id
   • child session_meta.payload.id
   • child rollout filename suffix
   • parent <subagent_notification>.agent_path
   • parent wait_agent output status key

   Observed children for this parent:

   019eda6c-0573-7993-a01e-a1d839486a35 Cicero     explorer
   019eda6c-160d-79d0-a5e5-d2164e88dfc2 Planck     explorer
   019eda6c-280d-7c81-b10f-b40adc6d64ca Helmholtz  explorer
   019eda6c-38ef-7322-973b-ee92507f6d55 Curie      explorer
   019eda6c-496c-7723-b8c4-150940e4a5ee Confucius  explorer
   019eda6c-580c-71f3-917e-f82c060aa455 Ramanujan  explorer
   

   Child lifecycle/tool shapes:

   • event_msg.task_started gives turn_id, started_at, model/context metadata.
   • event_msg.agent_message carries commentary/final text and phase.
   • event_msg.task_complete carries last_agent_message, completed_at, duration_ms.
   • response_item.function_call plus function_call_output gives tool timeline.
   • custom_tool_call, custom_tool_call_output, web_search_call, and shell/event entries need the same capped timeline treatment as the main Codex feed.

   Recommended implementation stages

   1. Immediate correctness patch:

   Add isCodexSubagentNotificationText() beside existing bootstrap predicates in src/renderer/src/workspace/codex/rollout.ts.

   Drop role-user messages whose entire content consists of subagent notification blocks, exactly like the AGENTS/env bootstrap “every block is synthetic” rule.

   This stops <subagent_notification> from entering runtime.entries as a user prompt.

   2. Type/session-meta cleanup:

   packages/codex-headless/src/transcript/TranscriptTypes.ts currently types CodexSessionMeta.source as string, but real child rollouts use an object. Add a tolerant type/guard for:

   source: 'cli' | 'app_server' | {
     subagent?: { thread_spawn?: { parent_thread_id?: string; depth?: number; agent_path?: string | null; agent_nickname?: string; agent_role?: string } }
     subAgent?: { thread_spawn?: ... }
   }

   Handle both subagent and subAgent casing defensively.

   3. Structured committed event path:

   Teach codex-headless CommittedChannel to detect subagent notifications and emit a subagent_notification committed event instead of promoting them to turn_committed.

   The event should carry:

   agentId / agentPath
   status: completed | error | running | unknown
   completedText?: string
   raw item
   file
   ts

   4. Codex subagent indexer:

   Add a Codex-specific indexer over ~/.codex/sessions/**/rollout-*.jsonl that finds child rollouts where:

   child.session_meta.payload.source.subagent.thread_spawn.parent_thread_id === parent providerSessionId
   

   Build a SubAgentState-compatible record using:

   • agentId: child thread id
   • toolUseId: synthetic key for current renderer, probably child thread id until model is widened
   • agentType: agent_role
   • description: parent spawn_agent.arguments.message if available, otherwise first child user message / nickname
   • nickname: Codex-only extra if model is widened
   • status: parent notification or task_complete, else running
   • startedAt: child session_meta.timestamp or task_started.started_at
   • lastActivityAt: latest child event timestamp
   • turnCount: child assistant/message count
   • toolCalls: capped child function/custom/shell tool timeline
   • currentActivity: latest running tool or agent phase

   5. Renderer generalization:

   Do not force Codex through the Claude Agent block join. Either:

   • render a parent-level Codex subagent group keyed by child ids, or
   • generalize TaskSubagentRow into SubagentSpawnRow that accepts a provider-neutral subAgentKey and optional spawn block.

   Also move the Agent special-case before provider-specific Codex tool routing if we choose to synthesize spawn entries.

   6. Debug bundle improvements:

   Add subagent counts to manifest/state snapshot:

   subAgents.total
   subAgents.running
   subAgents.done
   subAgents.error
   provider-specific source: claude-subagents-dir | codex-child-rollouts
   

   The current bundle only showed subAgents: 0, which was useful but not explanatory.

   Tests to add

   Immediate mapper test:

   • src/renderer/src/workspace/codex/rollout.test.ts
   • mapCodexRolloutToFeedEntries() returns [] for a role-user message whose only text starts with <subagent_notification>.
   • Normal user prompts still map.
   • A user prompt quoting <subagent_notification> mid-text still maps.
   • AGENTS/env bootstrap filtering remains covered.

   Codex metadata tests:

   • src/renderer/src/workspace/codex/metadata.test.ts or package-level equivalent.
   • Parse session_meta.payload.source.subagent.thread_spawn and subAgent.thread_spawn.
   • Return parent provider id, child id, nickname, role, depth, path.
   • Do not throw on malformed or string source.

   Subagent state tests:

   • Keep/expand src/main/subagents/subagentState.test.ts for capped timeline behavior.
   • Add Codex child rollout builder tests for function/custom/shell calls and matching outputs.

   Renderer tests:

   • src/renderer/src/features/feed/ui/Feed.subagents.renderer.test.tsx
   • Verify multiple subagents render grouped, counts/statuses show, mini-feed expands, and dropped-call count is visible.
   • Include a Codex provider case so Block.tsx provider routing cannot bypass subagent rows.

   Debug bundle test:

   • src/renderer/src/features/debug/saveDebugBundle.renderer.test.ts
   • Assert manifest/state snapshot include subagent counts and provider-specific source metadata.

   Ordering recommendation

   Do the mapper filter first. It is small, clearly correct, and stops the worst user-visible corruption immediately.

   Then build the Codex indexer/state path behind tests. The full renderer can reuse much of the Claude presentation, but the join model should be provider-neutral rather than pretending Codex has Claude toolUseId semantics.
3. Juliusolsson05 commented on Jun 18, 2026

   

   Juliusolsson05

   on Jun 18, 2026

   OwnerAuthor

   More actions

   Implementation PR opened: #292

   What it covers:

   • maps Codex spawn_agent calls into the existing Claude-style subagent row/group UI
   • builds Codex SubAgentState from parent spawn outputs plus child rollout files
   • filters <subagent_notification> synthetic user messages at the Codex rollout mapper so they stop rendering as prompts
   • hides raw spawn_agent output JSON because it is join metadata, not user-visible agent work

   Verification so far:

   • targeted new tests pass
   • npx tsc --noEmit passes
   • full npm test / npm run build:app are blocked in the dedicated worktree by missing packages/claude-code-headless/src/... files, including src/proxy/mitmAddon.py, which is outside this patch
4. Juliusolsson05

   closed this as completedin #292on Jun 18, 2026