Missing documentation related agent tools

What is the type of issue?

_No response_

What is the issue?

The subagent agent_tool.rs defines multi-agent tooling, however there is no documentation on that. This might lead to bad implementation of SKILL.md.

wait_agent is mentioned here https://developers.openai.com/codex/config-reference#configtoml but there is no explicit documentation about them.

I can see the implementation in the source code here
https://github.com/openai/codex/blob/a4d5112b37c1b012b761df66286e73b858205482/codex-rs/tools/src/agent_tool.rs#L202-L224

Where did you find it?

Found it when asking Codex to review compatibility of a SKILL.md that was not behaving well. Reported the problem to tool developer in here https://github.com/safishamsi/graphify/issues/273

Codex output when asked about documentation on wait_agent was:

Primary official doc:

- `Subagents – Codex`: https://developers.openai.com/codex/subagents  
  This is the main OpenAI doc for Codex multi-agent workflows. It describes spawning subagents in parallel, waiting for results, and closing agent threads.

Useful supporting docs:

- `Subagent concepts – Codex`: https://developers.openai.com/codex/concepts/subagents  
  This explains why subagent workflows exist and the tradeoffs around multi-agent orchestration.

- `Codex web`: https://developers.openai.com/codex/cloud  
  This mentions Codex working on tasks in the background, including in parallel.

I did not find a public official OpenAI doc page that exposes the literal internal tool name `wait_agent` as text. The public docs describe the behavior instead of listing that exact tool symbol.

And when asked the decision making in fixing SKILL.md with wait to wait_agent was:

From the live Codex tool schema in this session, not from a public doc page.

The basis was:

- This session exposes `spawn_agent`, `wait_agent`, and `close_agent` as actual callable tools.
- There is no `wait` tool in the available tool definitions.
- `graphify` had a Codex-specific section that said:
  - `Uses spawn_agent + wait + close_agent`
  - and later showed `result = wait(handle); close_agent(handle)`
- That mismatched the real tool contract available here, so I changed it to `wait_agent`.

So the fix was grounded in the runtime/tooling contract of this Codex environment, plus the mismatch in [graphify/SKILL.md](.codex/skills/graphify/SKILL.md), not in an external published doc.