›_ Codex Issues
Codex Issues / #26112

Allow caller-defined display names for spawned subagents

Open 💬 6 comments Opened Jun 3, 2026 by schulle01
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Summary

Please allow callers to set a stable, user-visible display name when spawning a subagent.

Today, a parent agent can instruct a subagent in the prompt to act under a semantic role name such as Auditor or Librarius, but the platform still assigns an unrelated visible nickname such as Lagrange or Ampere. That makes structured multi-agent workflows harder to audit and explain.

Problem

In structured agent runtimes, subagents often have durable semantic roles, for example:

  • Auditor for review work
  • Librarius for low-effort context/log/research work
  • project-specific workbench agents for bounded browser or document checks

The current behavior separates the semantic role in the prompt from the platform-visible nickname. Users then see a name that does not match the role they asked for, and the parent agent has to explain that e.g. Lagrange is actually acting as Auditor.

This affects:

  • transparency for users supervising multiple agents
  • scanability of agent notifications and audit trails
  • role clarity in long-running or governed multi-agent workflows

Observed behavior

A subagent was spawned with an explicit prompt role Auditor.

The tool response returned a platform nickname Lagrange.

The subagent reported that it received the role name Auditor, but could not see the platform nickname and that the dedicated name was only prompt-instructed, not technically set.

Requested capability

Add a caller-controlled display-name field to subagent creation, for example:

{
  "agent_type": "explorer",
  "model": "gpt-5.4-mini",
  "display_name": "Auditor",
  "message": "Review the assigned runtime change..."
}

Returned metadata could include both the caller-defined display name and the platform nickname:

{
  "agent_id": "...",
  "display_name": "Auditor",
  "platform_nickname": "Lagrange"
}

If uniqueness is required, Codex could render a combined label such as Auditor (Lagrange).

Acceptance criteria

  • spawn_agent or the equivalent subagent API supports a caller-provided display_name field.
  • The chosen display name is visible in tool results, notifications, and agent status surfaces.
  • The spawned subagent can identify its assigned display name without relying only on prompt text.
  • Platform-generated nicknames may still exist internally, but they do not replace the caller-defined role name.
  • If the requested display name is invalid or unavailable, the API returns a clear validation error or deterministic fallback.

Why this matters

The missing capability does not block delegation, but it reduces transparency, auditability, and user trust in structured subagent workflows where names encode responsibilities.

View original on GitHub ↗

6 Comments

github-actions[bot] contributor · 1 month ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #24745
  • #24863

Powered by Codex Action

schulle01 · 1 month ago

Thanks for the duplicate suggestions.

I think this issue is related but not a duplicate of #24745 / #24863 / #23588.

Those issues appear to cover rendering bugs where the UI shows raw UUIDs/thread IDs instead of an already available generated nickname or readable label.

This issue asks for a different capability: allowing the caller of spawn_agent to provide a stable, semantic display_name, such as Auditor or Librarius, and having that name appear in tool results, notifications, and agent status surfaces.

So #23588 would improve display of existing nicknames, while this request is about caller-controlled naming as part of the subagent API/metadata contract.

iqdoctor · 1 month ago

Cross-linking with #23588 after checking current behavior there: I do not think #23588 fully closes this request.

#23588 is about a bug in metadata propagation/rendering: Codex already has some friendly nickname/role metadata for spawned subagents, but some live/replayed UI paths still fall back to the raw UUID/thread id. Fixing #23588 should make existing metadata consistently render as something like Ampere [architect] instead of 019e....

This issue asks for a different API capability: the caller should be able to provide a stable semantic display name such as Auditor or Librarius at spawn time, and have that caller-defined name become part of the subagent metadata contract.

So the relationship looks like:

  • #23588: bug fix — preserve and prefer existing generated nickname/role metadata over UUID fallback.
  • #26112: enhancement — let the caller define the user-visible display name in the first place.

A complete implementation of #26112 would likely depend on the same display surfaces being healthy, so #23588 is a useful prerequisite/foundation. But by itself, #23588 would still leave Codex choosing names like Ampere/Lagrange; it would not let the caller request Auditor as the canonical visible label.

iqdoctor · 1 month ago

Minimal $code-review report

Review version/scope:

  • Repository: openai/codex
  • Branch: main
  • Commit reviewed: fae270932065355b5d7f197b3f1c72912588369b (fae270932065)
  • Date checked: 2026-06-09
  • Diff reviewed: none / current implementation baseline; this is a pre-implementation risk review for the requested display_name capability.
  • Review method: repo-local $code-review using the code-review-* slices (breaking-changes, testing, context, change-size).

Consolidated findings:

  1. [MEDIUM] codex-rs/core/src/tools/handlers/multi_agents_spec.rs:557 — v1 and v2 spawn_agent tool schemas are separate, so adding display_name to only one surface would either miss acceptance or reject calls on the other surface.
  1. [MEDIUM] codex-rs/core/src/tools/handlers/multi_agents_spec.rs:600 — the v2 schema needs its own optional display_name property and docs; it is not automatically inherited from v1.
  1. [MEDIUM] codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs:190 — v2 SpawnAgentArgs uses #[serde(deny_unknown_fields)], so display_name will be rejected until explicitly parsed.
  1. [HIGH] codex-rs/core/src/tools/handlers/multi_agents_spec.rs:363 — existing tool results expose nickname; do not replace or overload it with display_name, because #26112 asks to preserve both caller-defined display name and platform nickname.
  1. [LOW] codex-rs/core/src/tools/handlers/multi_agents_spec.rs:381 — the hidden-metadata result shape currently omits nickname-like metadata. Decide whether caller-provided display_name is exempt from this privacy/config flag or whether the acceptance criteria need to mention the flag.
  1. [HIGH] codex-rs/protocol/src/protocol.rs:2583 — SubAgentSource::ThreadSpawn currently stores agent_nickname / agent_role only. A distinct optional display_name field is needed so caller display identity does not overwrite platform nickname.
  1. [MEDIUM] codex-rs/app-server-protocol/src/protocol/v2/thread_data.rs:137 — app-server Thread metadata likewise only carries nickname/role. Add additive displayName while preserving existing fields.
  1. [HIGH] codex-rs/core/src/agent/registry.rs:221 — preferred nickname reservation currently accepts arbitrary strings. Caller-provided display names need validation: trim, reject empty/control/newline values, enforce a small max length, and define duplicate/unavailable behavior.
  1. [HIGH] codex-rs/core/src/session_prefix.rs:21 — agent names are formatted into model-visible session context. A caller-controlled display_name must be bounded and safe before being injected.
  1. [HIGH] codex-rs/core/src/context/environment_context.rs:584 — subagent metadata reaches <environment_context>. Add tests/validation for newline, tag-like, and oversized display names to avoid context injection or unbounded context growth.
  1. [MEDIUM] codex-rs/core/src/tools/handlers/multi_agents_common.rs:137 — validation should live at the spawn parsing/control boundary, not only in UI rendering.
  1. [MEDIUM] codex-rs/state/src/model/thread_metadata.rs:74 — state DB metadata needs an optional/defaulted display-name field so old records deserialize and new records preserve the value.
  1. [MEDIUM] codex-rs/thread-store/src/types.rs:390 — persisted thread metadata stores nickname/role/path only; runtime-only display names would disappear on replay/resume.
  1. [MEDIUM] codex-rs/thread-store/src/types.rs:496 — thread metadata patch/update types need display-name support too, or updates will drop the field.
  1. [MEDIUM] codex-rs/core/src/agent/control/spawn.rs:645 — resume restores nickname/role only; add display-name restore logic and tests.
  1. [MEDIUM] codex-rs/protocol/src/protocol.rs:3838 — CollabAgentSpawnEndEvent lacks display-name metadata. Tool output alone is insufficient because notifications/status surfaces also need the caller-defined label.
  1. [MEDIUM] codex-rs/protocol/src/protocol.rs:3911 — subagent activity/status events also need display-name propagation or activity rendering will remain path/id-based.
  1. [MEDIUM] codex-rs/app-server-protocol/src/protocol/event_mapping.rs:104 — spawn-end event mapping currently builds app-server items without propagating name metadata. Extend the item/state and generated schemas.
  1. [MEDIUM] codex-rs/app-server-protocol/src/protocol/event_mapping.rs:115 — receiver state in collab spawn completion is status-focused; it should carry display metadata for canonical app-server consumers.
  1. [MEDIUM] codex-rs/app-server-protocol/src/protocol/v2/item.rs:340 — SubAgentActivity items carry IDs/path but no display metadata. Add display name or a reliable metadata lookup/hydration path.
  1. [MEDIUM] codex-rs/app-server-protocol/src/protocol/v2/item.rs:1052 — CollabAgentState only has status/message; add optional display metadata for live and replayed collab items.
  1. [MEDIUM] codex-rs/tui/src/multi_agents.rs:84 — TUI label formatting currently knows nickname/role/path, not caller display name. Define display priority, e.g. display_name first, optional platform nickname second, path/id fallback.
  1. [MEDIUM] codex-rs/tui/src/multi_agents.rs:502 — collab transcript rendering can fall back to raw IDs unless display metadata is available in the render path.
  1. [MEDIUM] codex-rs/tui/src/multi_agents.rs:319 — v2 activity rendering uses agent_path; it should prefer caller display name and keep path only as fallback/trace metadata.
  1. [MEDIUM] codex-rs/core/tests/suite/subagent_notifications.rs:1030 — add end-to-end agent logic coverage where the mocked model calls spawn_agent with "display_name": "Research Scout" and the child/output/persistence surfaces carry it.
  1. [MEDIUM] codex-rs/core/src/tools/handlers/multi_agents_tests.rs:1043 — add a direct handler regression proving SpawnAgentHandlerV2 accepts display_name and returns/persists the expected metadata.
  1. [MEDIUM] codex-rs/core/src/tools/handlers/multi_agents_spec_tests.rs:40 — extend tool-schema contract tests so display_name exists in properties, is optional, and has the intended description/output shape.
  1. [MEDIUM] codex-rs/core/src/agent/control_tests.rs:2174 — extend resume/persistence tests for display-name restoration alongside nickname/role.
  1. [MEDIUM] codex-rs/core/src/agent/registry.rs:35 — AgentMetadata currently has only agent_nickname and agent_role; add first-class display identity instead of overloading nickname.
  1. [MEDIUM] codex-rs/core/src/agent/control.rs:493 — generated nickname reservation should remain separate from caller display name, because the requested API wants both identities available.
  1. [MEDIUM] codex-rs/thread-store/src/thread_metadata_sync.rs:70 — thread metadata sync writes nickname/role/path today; include display name so it survives store updates.
  1. [MEDIUM] codex-rs/core/src/hook_runtime.rs:750 — hook context exposes agent id/type but not display name. If spawned agents must identify their assigned display name without relying only on prompt text, this needs a structured, bounded path.
  1. [MEDIUM] codex-rs/core/src/session_prefix.rs:17 — session prefix helper should be display-name-aware or replaced with a bounded context fragment for subagent identity.
  1. [MEDIUM] codex-rs/core/src/session/mod.rs:2924 — spawned-session environment context needs display-name propagation if self-identification is part of acceptance.

Suggested staging:

  1. Backend/API contract first: optional validated display_name, distinct from generated nickname, plus tool result shape and core tests.
  2. Persistence/resume next: protocol/state/thread-store metadata and old-rollout compatibility.
  3. Notifications/app-server: event mapping, thread history/replay, generated JSON/TS schemas.
  4. TUI/status surfaces last: label priority, snapshots, and activity/transcript rendering.
kennyalive · 18 days ago

This would be useful for role-based spawned subagents too.

Current behavior assigns opaque/fun names like Curie, Jason, Hilbert. For workflows with multiple active roles, it is much easier to scan the sidebar if callers can provide a display name, or at least a prefix/suffix, e.g. Comparator2 Epicurus, Fixer1 Banach, Verifier2 Darwin.

We can make this work manually by editing local Codex state (threads.agent_nickname) and restarting the app, but it would be much better as a supported spawn/display option.

Before:

<img width="358" height="406" alt="Image" src="https://github.com/user-attachments/assets/0648de0f-5996-43e6-b539-c882dafb6085" />

After:

<img width="386" height="380" alt="Image" src="https://github.com/user-attachments/assets/979e68b1-f83f-4e21-8cf8-d3e1d496aaf5" />

RichardMM · 5 days ago

is this coming any time soon. With 10 sub agents spawned each concerning different issues. Time is wasted in remembering context that a particular sub agent was working under