Add caller-facing invocation instructions to custom agent TOML files

What variant of Codex are you using?

App

What feature would you like to see?

Custom agent definitions should support caller-facing invocation instructions that tell the calling or orchestrating agent what information it should provide when invoking that specific agent.

Using the reviewer role from the official custom-agent documentation as a neutral example:

name = "reviewer"
description = "Reviews pull requests for correctness, security, and missing tests."

invocation_instructions = """
When invoking this agent, provide:
- the change or review target,
- the intended behavior,
- the relevant scope,
- known constraints,
- applicable review criteria.
"""

developer_instructions = """
Review the supplied change and report concrete, actionable findings.
"""

The fields would have separate responsibilities:

• description explains when the agent should be selected.
• invocation_instructions tells the caller how to construct a sufficiently specified task for the selected agent.
• developer_instructions defines how the invoked agent should behave.

Suggested behavior:

1. Codex selects a custom agent using its description.
2. Before constructing the delegated task, the caller receives that agent’s invocation_instructions.
3. The caller provides the requested information when it is available.
4. The caller identifies material missing information instead of silently inventing it.
5. invocation_instructions are not automatically appended to the child agent’s developer_instructions.
6. The field is optional, so existing custom agents continue to work unchanged.

The exact field name is open to discussion. caller_instructions or a structured [invocation] table could provide the same separation.

Additional information

Problem

A custom agent currently has no agent-specific way to tell its caller what information is needed for an effective invocation.

The documented fields do not cover this responsibility:

• description describes when Codex should use the agent.
• developer_instructions define the behavior of the invoked agent.

By the time developer_instructions apply, the caller has already selected the agent and constructed the delegated task. They therefore cannot reliably guide task construction.

This can lead to underspecified delegation. The invoked agent must then:

• infer missing objectives, criteria, or scope;
• ask an avoidable clarification question;
• proceed using arbitrary assumptions; or
• return a weaker result because relevant context was not supplied.

Why AGENTS.md is not an adequate substitute

Invocation requirements can currently be placed in AGENTS.md, but that has several disadvantages:

• They are separated from the agent definition they describe.
• They apply broadly rather than to one particular agent.
• Requirements must be duplicated in central orchestration instructions.
• Adding or changing an agent requires maintaining another file.
• Project or global instructions may be inherited by agents for which they were not intended.
• Shared custom agents are not self-describing.

The information belongs with the custom agent because it constitutes that agent’s invocation contract.

Why a skill is not an adequate substitute

A skill could describe how to invoke an agent, but the skill would need to be discovered and selected independently.

This creates two separately maintained definitions:

1. the custom agent;
2. the skill explaining how to invoke it.

First-class caller-facing metadata would keep role selection, invocation requirements, and child behavior together while preserving their distinct purposes.

Possible structured alternative

[invocation]
required = [
  "Concrete objective",
  "Input material or search scope"
]

recommended = [
  "Relevant context",
  "Expected output format",
  "Evaluation criteria"
]

question_policy = "Ask only when missing information could materially change the result"

A free-form invocation_instructions field would be simpler and more flexible initially. A structured table could later support validation, tooling, and user interfaces.

Expected behavior

• The caller can access the invocation contract before composing the delegated task.
• The field does not influence agent selection unless explicitly designed to do so.
• description remains focused on routing.
• developer_instructions remain child-facing.
• The field works for both personal and project-scoped custom agents.
• Nested subagents can use the same metadata when invoking another agent.
• Existing custom agents remain backward-compatible.
• Invalid values produce a clear validation error instead of being silently ignored.

Related but distinct issues

• #26806 concerns scoping instructions to the parent or preventing their inheritance by subagents. This request concerns instructions associated with one specific agent and exposed to its caller.
• #22639 concerns reusable worker instructions and custom roles for spawn_agents_on_csv. This request defines the invocation contract of any custom agent, independently of batch execution.
• #18550 concerns declarative fork_context configuration. It similarly stores invocation-related behavior with the agent, but addresses context inheritance rather than task construction.

I searched the existing Codex issues and discussions and did not find a request for this specific caller-facing invocation contract.