Expose stable per-agent metadata on every tool/subprocess invocation

What variant of Codex are you using?

CLI, App, IDE Extension

What feature would you like to see?

Codex needs a stable way for tools and subprocesses to determine which agent they are running under, including whether that agent is the parent agent or a spawned subagent.

This is important for integrations that maintain per-agent local state or need isolation between agents.

Problem

In Codex, many tool executions happen in fresh subprocess shells. That creates two practical issues:

1. A tool cannot reliably tell which agent the current execution belongs to.
2. A tool cannot reliably associate repeated subprocess calls with the same agent over time.

This makes correct per-agent isolation difficult for:

• tools with local session state
• cached local resources
• subprocess-backed integrations
• anything that needs one local state bucket per agent

Flags like “is subagent” or “depth” are not sufficient by themselves, because multiple sibling agents can exist at the same depth.

Right now, integrations have to rely on prompt discipline, heuristics, or ad hoc conventions instead of a host-provided signal.

Requested feature

Expose stable per-agent metadata on every tool/subprocess invocation.

At minimum:

• CODEX_AGENT_ID: stable unique identifier for the current agent
• CODEX_PARENT_AGENT_ID: identifier for the parent agent, when applicable

Useful additional metadata:

• CODEX_AGENT_NAME
• CODEX_AGENT_DEPTH
• CODEX_IS_SUBAGENT=1

A structured metadata file path or another machine-readable channel would also work, but environment variables would be the simplest integration point.

Minimum useful behavior

• Every agent, including sibling subagents, gets its own stable CODEX_AGENT_ID
• Subagents can see CODEX_PARENT_AGENT_ID
• IDs remain stable across multiple tool/subprocess invocations from the same agent
• Optional metadata like name/depth/subagent flag can help with debugging and routing, but IDs are the essential part

Why this matters

This would let tools correctly implement:

• one isolated local state bucket per agent
• reliable reuse across multiple subprocess invocations from the same agent
• automatic parent vs subagent bootstrap behavior
• better traceability and debugging of multi-agent runs

Without something like this, multi-agent support exists at the model level but remains awkward for stateful local tooling.

Additional information

_No response_