Build a Codex job's string-keyed, JSON-safe Oban args.

new/1 accepts atom-keyed native Elixir options, validates them, and returns the map Oban stores:

ObanCodex.Args.new(
  prompt: "review the repository",
  working_dir: "/repo",
  sandbox: :read_only,
  approval_policy: :never
)

#=> %{
#     "prompt" => "review the repository",
#     "working_dir" => "/repo",
#     "sandbox" => "read_only",
#     "approval_policy" => "never"
#   }

defaults/1 has the same schema with :prompt optional, making it suitable for worker-level defaults:

use ObanCodex.Worker,
  queue: :codex,
  args: ObanCodex.Args.defaults(
    working_dir: "/repo",
    sandbox: :read_only,
    approval_policy: :never
  )

:meta carries application values such as an issue number or correlation id. It is flattened into the map because Oban jobs already expose their args to callbacks and telemetry. Meta keys may not collide with a Codex option and every value must be JSON-encodable.

Options

• :prompt (String.t/0) - Required. The Codex prompt. The only required option for new/1.

• :model (String.t/0) - Model name understood by the installed Codex CLI.

• :profile (String.t/0) - Named Codex config profile for the initial turn.

• :working_dir (String.t/0) - Working directory for the Codex subprocess.

• :binary (String.t/0) - Path to the codex binary. Pin this in worker defaults when a PATH upgrade during a batch would be unsafe.

• :timeout (pos_integer/0) - Whole command timeout in milliseconds.

• :verbose (boolean/0) - Enable verbose Codex CLI output.

• :sandbox - Codex sandbox mode.

• :approval_policy - Codex approval policy.

• :full_auto (boolean/0) - Compatibility shorthand for sandbox: :workspace_write; an explicit :sandbox wins.

• :dangerously_bypass_approvals_and_sandbox (boolean/0) - Bypass approvals and sandboxing. Only use inside a separately secured execution environment.

• :dangerously_bypass_hook_trust (boolean/0) - Run repository hooks without persisted trust. Only use when hook sources are already vetted.

• :skip_git_repo_check (boolean/0) - Allow Codex to run outside a git repository.

• :add_dir - Additional readable directory or directories for an initial turn.

• :search - Web-search mode.

• :ephemeral (boolean/0) - Do not persist the session. This is suitable for one-shot jobs and is incompatible with :session_id/:resume.

• :output_schema (String.t/0) - Path to a JSON Schema file for the final message. Unlike Claude's inline json_schema, Codex expects a file path. It is reapplied on resumed turns.

• :output_last_message (String.t/0) - Path where Codex writes the final agent message.

• :images (list of String.t/0) - Image paths attached to the prompt.

• :config_overrides (list of String.t/0) - Repeatable Codex key=value config overrides.

• :enabled_features (list of String.t/0) - Feature names enabled for this invocation.

• :disabled_features (list of String.t/0) - Feature names disabled for this invocation.

• :strict_config (boolean/0) - Fail when config contains fields the installed Codex doesn't recognize.

• :ignore_user_config (boolean/0) - Do not load the user's config.toml (authentication still resolves normally).

• :ignore_rules (boolean/0) - Do not load user or project execpolicy .rules files.

• :color - Color mode for the initial turn.

• :oss (boolean/0) - Use an open-source provider for the initial turn.

• :local_provider (String.t/0) - Local provider name, typically "ollama" or "lmstudio".

• :session_id (String.t/0) - Explicit Codex thread id to resume. Obtain it with ObanCodex.session_id/1 from a prior result.

• :resume (String.t/0) - Alias for :session_id, retained to keep lifecycle code and migration patterns aligned with oban_claude. Do not set both.

• :meta - Application metadata merged flat into the stored args (keys stringified). It is not forwarded to Codex.