What variant of Codex are you using?

Codex Desktop App

What feature would you like to see?

Specific UX for #14923: attach an existing top-level session as a persistent subagent to an orchestrator thread

Summary

This is a narrower, concrete UX slice of #14923 — Desktop app: explicit cross-thread orchestration over existing thread/* and turn/* primitives.

Codex Desktop should let a user attach an existing top-level, folder-scoped session as a persistent subagent to an orchestrator thread.

In practical terms:

1. I create a normal top-level Codex session scoped to a project/folder, with its normal AGENTS.md guidance.
2. In the UI, I choose something like Attach as sub-agent to parent thread.
3. I pick an existing orchestrator/Operator thread.
4. The orchestrator can now send messages to that attached session and wait for replies.
5. The attached session remains visible and directly usable in the left sidebar.
6. Both the orchestrator and the attached role session remain targetable by Automations.

This is not a request for users to manually edit local state. It is a request to make this workflow a supported, first-class product surface.

Why this is different from current custom subagents

Current custom subagents are useful, but they are still fundamentally disposable child sessions created by a parent thread. They also require role governance to move into .toml agent definitions.

That creates two load-bearing problems.

1. TOML becomes a duplicate governance plane

Many serious Codex workflows already use folder-scoped AGENTS.md files as the primary governance mechanism:

• repository-level instructions
• role-specific instructions
• project-specific commands
• review/implementation/audit boundaries
• safety rules and local operating conventions

When custom subagents require a separate TOML role definition, the TOML becomes a second governance surface. That creates drift.

A TOML file that says “go read this AGENTS.md role brief” is also leaky indirection:

• the TOML can drift from the folder-scoped role brief
• the parent thread can contaminate the spawned child’s context
• continuity depends on the spawn prompt/injection behaving correctly
• role behavior is split between the Codex config plane and the project’s normal scoped-instructions plane

For durable role agents, the natural source of truth is the top-level session’s folder scope and loaded AGENTS.md hierarchy, not a parallel TOML copy of the same role.

2. Disposable subagent lifecycle is wrong for durable role desks

A spawned custom subagent is usually treated as temporary. The parent can wait on it and eventually close it.

That is appropriate for short-lived delegation.

It is not appropriate for standing role desks like:

• Operator / orchestrator
• Reviewer
• Implementor
• Auditor
• Designer
• Researcher

Those roles benefit from being long-lived, visible, directly promptable, automation-targetable sessions with stable local context.

The desired model is not “spawn a fresh reviewer every time.”

The desired model is “attach my existing Reviewer desk to my Operator desk.”

Proposed UX

Add a Desktop UI action on eligible top-level sessions:

Attach as sub-agent to parent thread

Flow:

1. User opens a top-level session, such as reviewer.
2. User clicks ... or a session action menu.
3. User selects Attach as sub-agent to parent thread.
4. Desktop shows a picker of available parent/orchestrator threads.
5. User selects the parent thread.
6. Codex creates a durable, visible attachment between the parent session and the child/role session.

The attached session should remain:

• visible in the normal left sidebar
• directly promptable by the user
• scoped to its original cwd/project/folder instructions
• available as a target for Automations
• addressable by the parent orchestrator through supported agent messaging/waiting tools

Required lifecycle semantics

Persistent attached sessions need different lifecycle semantics from disposable spawned subagents.

For disposable spawned subagents, a parent-facing close_agent operation can reasonably mean “close this child.”

For persistent attached sessions, that is dangerous.

An attached session is also a user-visible top-level thread with its own identity, history, Automations eligibility, project scope, and role state. Closing it through a parent subagent lifecycle tool could accidentally destroy or archive a durable role desk.

Desired lifecycle behavior

For persistent attached sessions:

• close_agent should be disabled, rejected, or mapped only to safe detach semantics.
• There should be an explicit Detach from parent thread action.
• Detaching should remove the parent-child orchestration relationship without archiving or destroying the target session.
• Archiving the child session should remove/detach the orchestration relationship.
• Archiving the parent session should detach or orphan the child safely, with clear UI state.
• The UI should distinguish:
  • disposable spawned subagent
  • persistent attached top-level session

The key safety rule: a parent orchestrator should not be able to accidentally destroy a durable top-level role session through a disposable-subagent lifecycle command.

Why Automations matter

This feature would pair extremely well with Codex Automations.

A top-level orchestrator thread can already be a durable operating surface. A top-level role thread can also be scheduled, resumed, or woken independently.

That enables workflows like:

• scheduled Operator wakeup checks current project state
• Operator sends a targeted review request to attached Reviewer
• Reviewer performs its pass in its own folder-scoped context
• Operator waits, receives the response, and updates the plan
• human can inspect or prompt either session directly

That is much more practical for real development workflows than a purely ephemeral spawn tree.

Example workflow

A project has these top-level Codex sessions:

• Operator at /repo/.agents/workspace-roles/operator
• Reviewer at /repo/.agents/workspace-roles/reviewer
• Implementor at /repo/.agents/workspace-roles/implementor

Each role folder has its own AGENTS.md.

The user attaches Reviewer and Implementor to Operator.

Now the Operator can do:

• ask Implementor to make a bounded change
• ask Reviewer to review the resulting diff
• wait for either role
• fold their output into the main operational thread

The human can still click into Reviewer or Implementor directly, inspect the full conversation, or prompt them manually.

Acceptance criteria

• A user can attach an existing top-level Desktop session to a parent/orchestrator thread through the UI.
• The attached session remains visible in the left sidebar.
• The attached session remains directly promptable by the human.
• The attached session keeps its original cwd and folder-scoped AGENTS.md instruction hierarchy.
• The parent/orchestrator can send a message to the attached session.
• The parent/orchestrator can wait for a response from the attached session.
• Both parent and attached child remain eligible for Automations.
• The UI clearly distinguishes persistent attached sessions from disposable spawned subagents.
• close_agent cannot accidentally close/archive/destroy a persistent attached top-level session.
• A first-class detach action removes the orchestration relationship without destroying either thread.
• Archiving either side handles the attachment safely and visibly.
• Cross-thread activity is auditable in both source and target sessions.

Non-goals

This issue is not asking for:

• hidden/manual local database or JSONL editing
• a workaround that depends on private state shape
• replacing current disposable subagents
• replacing .codex/agents/*.toml custom subagents
• full peer-to-peer arbitrary thread control
• a global shared memory system

This is a narrow Desktop UX and lifecycle feature: attach an existing folder-scoped top-level session as a persistent subagent to a chosen parent thread.

Relationship to existing issues

This is a concrete UX slice of:

• #14923 — Desktop app: explicit cross-thread orchestration over existing thread/* and turn/* primitives

It is also related to:

• #12047 — Multi-agent TUI overhaul: named agents, per-agent config, async orchestration & @mention messaging
• #21027 — Shared workspace/message bus for Codex subagents
• #15250 — Custom subagents in .codex/agents are not accessible from tool-backed Codex sessions as docs imply
• #18823 — Custom agent requests are easy to misrout to skills instead of .codex/agents/*.toml custom agents
• #19399 — Subagent-specific TOML config no longer works on Codex Windows; named agents spawn with default config
• #19482 — Support global/default model configuration for subagents in config.toml
• #20675 — Expose root/subagent metadata in hook payloads
• #16900 — Long-running healthy subagents can be prematurely treated as stalled
• #9607 — Main agent not receiving subagent completion signal

The difference from those issues is scope: this request is specifically for persistent attachment of an existing top-level, folder-scoped Desktop session to an orchestrator thread, with safe lifecycle semantics.

Additional information

No response