Codex agent harness: support custom agents, MCP, plugins & instructions/rules from all multi-root workspace folders

[DonJayamanne]

API requirements

• API to either provide a custom list of Custom Agents, Plugins, Rules/Instructions
• Or API to have the SDK ensure the Custom Agents, Plugins, Rules/Instructions from additional folders are available in the session

[DonJayamanne]

Giuseppe’s suggestion for MCPs, plugins, and agents:

Skills: The experimental selectedCapabilityRoots can be passed to thread/start to use skills from other directories.
MCPs and plugins: These should also work with selectedCapabilityRoots.
Agents: Use a per-thread config override on thread/start or thread/resume. Example:

{
  "method": "thread/start",
  "params": {
    "cwd": "/workspace/A",
    "runtimeWorkspaceRoots": [
      "/workspace/A",
      "/workspace/B"
    ],
    "config": {
      "agents": {
        "reviewer": {
          "description": "Reviews code for correctness and maintainability.",
          "config_file": "/workspace/B/.codex/agents/reviewer.toml"
        },
        "researcher": {
          "description": "Researches the codebase before implementation.",
          "config_file": "/workspace/B/.codex/agents/researcher.toml"
        }
      }
    }
  }
}

Note: Codex custom agents use .toml (not .md). For reference, see the Copilot converter used in VS Code:

vscode/src/vs/platform/agentHost/node/copilot/copilotPluginConverters.ts

Line 127 in f551419

export async function toSdkCustomAgents(agents: readonly INamedPluginResource[], fileService: IFileService): Promise<CustomAgentConfig[]> {

[DonJayamanne]

Important clarification for Codex custom agents:

Custom-agent selection does not currently work even for a single-folder workspace. Before each message, the agent host passes the selected AgentSelection to agent.chats.changeAgent(...), but Codex implements changeAgent as an explicit no-op (Codex does not support selecting a custom agent). Consequently, the Codex session does not retain the selected agent URI, read or convert the agent Markdown, add it to thread/start.config, or apply its prompt as developer instructions. The picker can show the selection in VS Code state while the Codex backend continues with its default configuration.

This means multi-root support is not merely a matter of passing runtimeWorkspaceRoots or selectedCapabilityRoots. We first need complete single-folder custom-agent support: discovery/surfacing, Markdown-to-Codex TOML conversion, per-thread config.agents registration, selected-agent semantics, persistence/resume, and change handling. Multi-root then adds precedence, duplicate-name handling, per-root discovery/watchers, and path/lifetime concerns on top.

One semantic issue also needs an explicit decision: Codex config.agents defines roles available to spawned subagents; it does not by itself make the selected role the main thread agent. To preserve VS Code picker semantics, the selected agent likely also needs to be applied to the main thread (for example through developerInstructions), with unsupported agent properties clearly defined.