feat: add experimental Codex extension and tool

[seratch]

This pull request adds an experimental Codex extension with tool/exec/thread APIs, payload/event/item schemas, and options wiring under src/agents/ extensions/experimental/codex, plus a usage example and tests for Codex exec thread and tool behavior. It introduces new runtime surface area under src/agents/ (experimental), so please review compatibility expectations and ensure opt‑in behavior remains clear. It also adds examples/tools/codex.py and tests in tests/extensions/experiemental/codex/ to cover the new functionality.

import asyncio
from agents import Agent, Runner
from agents.extensions.experimental.codex import (
    ThreadOptions,
    TurnOptions,
    codex_tool,
)

async def main() -> None:
    agent = Agent(
        name="Codex Agent",
        instructions=(
            "Use the codex tool to inspect the workspace and answer the question. "
            "When skill names, which usually starts with `$`, are mentioned, "
            "you must rely on the codex tool to use the skill and answer the question.\n\n"
            "When you send the final answer, you must include the following info at the end:\n\n"
            "Run `codex resume <thread_id>` to continue the codex session."
        ),
        tools=[
            # Run local Codex CLI as a sub process
            codex_tool(
                sandbox_mode="workspace-write",
                default_thread_options=ThreadOptions(
                    # You can pass a Codex instance to customize CLI details
                    # codex=Codex(executable_path="/path/to/codex", base_url="..."),
                    model="gpt-5.2-codex",
                    model_reasoning_effort="low",
                    network_access_enabled=True,
                    web_search_enabled=False,
                    approval_policy="never",  # We'll update this example once the HITL is implemented
                ),
                default_turn_options=TurnOptions(
                    # Abort Codex CLI if no events arrive within this many seconds.
                    idle_timeout_seconds=60,
                ),
                # Subscribe the events from codex CLI
                on_stream=lambda payload: print(payload),
            )
        ],
    )
    result = await Runner.run(
        agent, "You must use `$openai-knowledge` skill to fetch the latest realtime model name."
    )
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Output:

➜  openai-agents-python git:(feat/experimental-codex-extension) ✗ uv run -m test
The latest realtime model name, as fetched using the $openai-knowledge skill, is gpt-realtime. This model name is specified in the documentation as model: "gpt-realtime" for realtime API usage.

Run codex resume 019bc5ac-3af5-76b3-a1aa-fe8488c19ec0 to continue the codex session.

Trace:

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4bb47e2431

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f5bc2460b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 49cbfb251b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".