Files
codex/sdk/python
Ryan Taylor a1afa12273 Let required hooks block continuation on failure (#62831)
## Why

A required hook check can fail to run or return a usable result. Continuing
after that failure can let an action proceed without a completed check.

## What changed

Add per-handler `onFailure` for command and MCP tool hooks. The default
`continue` preserves existing behavior. On supported synchronous hooks,
`block` applies the event's blocking behavior and reports the reason while
preserving failure diagnostics. For example, a failed `PreToolUse` check
prevents the tool from running, while a failed `PostToolUse` check withholds
the result of a tool that already ran.

Expose the policy in the app-server's `configRequirements/read` response.

## Testing

Add tests for command and MCP failures under both policies, and scenario
coverage for blocked tool execution, withheld results, and completion after
a `Stop` hook recovers.

GitOrigin-RevId: 20d6ebda0094382fe052bbf34338edb994cc7bd3
2026-11-20 20:24:34 +00:00
..

OpenAI Codex Python SDK

Build Python applications that start Codex threads, run turns, stream progress, and control workspace access.

Install

Install the SDK:

pip install openai-codex

Quickstart

The SDK reuses your existing Codex authentication when one is already available:

from openai_codex import Codex

with Codex() as codex:
    thread = codex.thread_start()
    result = thread.run("Explain this repository in three bullets.")
    print(result.final_response)

thread.run(...) returns a TurnResult containing the final response, collected items, and token usage.

Authentication

Existing Codex authentication is reused automatically. To start ChatGPT browser login explicitly:

from openai_codex import Codex

with Codex() as codex:
    login = codex.login_chatgpt()
    print(login.auth_url)
    print(login.wait().success)

For device-code login:

with Codex() as codex:
    login = codex.login_chatgpt_device_code()
    print(login.verification_url, login.user_code)
    login.wait()

For API-key login:

with Codex() as codex:
    codex.login_api_key("sk-...")

Built-In Help

Use Python's standard help(openai_codex), help(Codex), or python -m pydoc openai_codex documentation tools.

Documentation

The package is licensed under the repository Apache License 2.0.