Codex Effort Hooks: automatic reasoning effort switching

Keep routine work at medium. Switch to ultra after a failure. Return to medium when recovery is verified.

Codex Effort Hooks is an experimental Python controller for OpenAI Codex CLI. It demonstrates automatic reasoning effort changes inside one running turn, using trusted Codex hooks and the experimental turn/settings/update API.

Status: unofficial proof of concept. The demo starts its own Codex process with local, deterministic model responses. It does not attach to an existing Codex desktop task or run a real deployment.

Quick start · Test results · FAQ · Runtime guide

Why switch Codex reasoning effort?

A Git push can turn from a routine step into a debugging task with one rejected command. The policy should recognize that change, then wait for evidence of recovery before lowering effort again.

This repository lets you reproduce that transition in a single Codex turn. It is useful for developers exploring Codex hooks, coding-agent controllers and failure-aware workflows. Cost savings, faster execution and better debugging results have not been measured.

A failed push, from error to verified recovery

The local Git fixture deliberately rejects its first push. The controller reacts to the process exit code, then keeps ultra through repair and retry:

Fixture step	Observed result	Effort for the next step
Start a routine local push	Operation begins	medium
Push to the local bare repository	Rejected, exit 1	ultra
Remove the fixture's rejection hook	Repair succeeds	ultra
Retry the push	Push succeeds	ultra
Compare local HEAD with the remote ref	Verification passes	medium

A successful retry is not enough to lower effort. Verification must pass too. Unrelated failures and unknown outcomes do not trigger a change. The same test suite covers a failed commit, a simulated deploy and a terminated child process.

Quick start

You need Python 3.10+ and Git. The unit tests use only Python's standard library; no OpenAI API key or Codex installation is required for this first command.

git clone https://github.com/owgit/codex-effort-hooks.git
cd codex-effort-hooks
python3 -m unittest -v test_policy.py test_controller.py test_transport.py

To exercise native Codex hooks and runtime effort switching, install a compatible Codex CLI and run:

python3 verify.py

The verified native version is codex-cli 0.153.4 on macOS. Use python3 verify.py --codex /path/to/codex to select an executable. To also test a desktop app's bundled binary as a separate process:

python3 verify.py --desktop-codex /path/to/app/resources/codex

The runner creates disposable workspaces and a separate Codex profile. Its model responses come from a local fixture server. Read results in evidence/verification.json; generated evidence stays out of Git.

What the tests prove

The local verification on 2026-09-08 passed 34 unit, controller and transport tests, plus all five native runtime cases below. GitHub Actions runs the 34-test suite on Python 3.10 and 3.12. The native runtime cases remain local checks.

Runtime case	Verified behavior
Codex CLI with trusted hooks	18 fixture commands and 8 effort changes in one turn
Delayed commands	write_stdin polling preserves the expected effort sequence
Runtime switching disabled	Updates fail explicitly; effort stays medium
Hooks left untrusted	Hooks do not execute; no effort changes
Optional desktop binary	Same positive sequence in a separate app-server process

The tests assert actual exit codes, native setting acknowledgements and effort on every subsequent model request. They also verify that the model, thread and turn remain the same and that the user's normal Codex config and hooks files remain unchanged.

The commit and push use real local Git repositories. Deployment and model replies are simulated. This verifies the runtime mechanism, not real-model reasoning quality or production deployment behavior.

How Codex hooks change effort during a turn

1. Observe: native PreToolUse and PostToolUse Bash hooks send events to an authenticated loopback controller.
2. Check the outcome: the controller correlates hook IDs with app-server command-completion events and their structured exitCode.
3. Apply the policy: configured operations and verification steps determine whether effort stays the same or changes.
4. Confirm the change: the controller calls turn/settings/update and requires an applied acknowledgement before adopting its new state.

Hook output alone does not provide an effort override in the tested version. The experiment therefore owns the app-server connection and enables step_model_switching only in its disposable profile.

Read the runtime integration guide for hook trust, failure handling, cleanup, native API probes and upstream source references.

FAQ

Can Codex change reasoning effort during a running turn?

This experiment verifies it with Codex 0.153.4 through the gated turn/settings/update API. The update affects continuation requests within the same turn. It does not restart the task or change the model.

Does this work inside my existing Codex desktop task?

No. The controller starts and owns a separate app-server process. Testing the desktop's bundled binary does not connect it to an open desktop task. A supported desktop hook-to-active-turn bridge is still needed.

Does the provider receive ultra unchanged?

In the tested gpt-6-astra catalog, Codex acknowledges native ultra and normalizes its reasoning effort to xhigh in outgoing requests. Multi-agent behavior is disabled in the demo; it does not reproduce the full desktop preset.

Will this save tokens or improve debugging?

Those outcomes have not been measured. The tests use deterministic local model replies and verify settings changes, not cost, latency or answer quality.

Can I connect it to production deployments?

The repository currently provides an isolated fixture. A real integration needs an explicit command policy, provider-specific completion checks, handling for concurrent operations and user effort overrides. Effort changes must remain independent of command and deployment permissions.

What should I do if a runtime test fails?

Check codex --version and the logs in evidence/. Other Codex versions and native platforms have not been verified. Run python3 verify.py again after fixing the cause; each run starts fresh fixtures. An acknowledgement timeout means native state is unknown. See failure handling and cleanup before retrying.

Explore the code or contribute a reproduction

File	Responsibility
effort_policy.py	Pure failure, retry and verification policy
hook_client.py	Authenticated hook transport with loopback restrictions
runtime_lab.py	Native Codex app-server integration and local Responses fixture
fixture_ops.py	Local Git, simulated deployment and process-failure cases
verify.py	Canonical runner and evidence report

Maintained by owgit. Useful contributions include a reproducible failure case, another verified Codex version, or a supported desktop integration path. Open an issue with your platform, Codex version and a sanitized reproduction. Keep credentials and private conversation logs out of reports.

The upstream feature request contains the initial runtime findings. This project is independent of OpenAI.