codexapi 0.12.9__tar.gz → 0.12.11__tar.gz

{codexapi-0.12.9/src/codexapi.egg-info → codexapi-0.12.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.12.9
+Version: 0.12.11
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -80,6 +80,8 @@ Use `backend="cursor"` (or set `CODEXAPI_BACKEND=cursor`) to switch to the
 Cursor agent backend.
 Use `fast=True` in Codex API calls, or `--fast` in the CLI, to opt into Codex
 fast mode. Normal mode is the default.
+Use `model="..."` and `thinking="..."` in Codex API calls to override the
+backend model and reasoning effort for a run.
 
 ## CLI
 
@@ -155,7 +157,8 @@ Resume a session and print the thread/session id to stderr:
 codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
-Use `--no-yolo` to disable `--yolo` (Codex uses `--full-auto`).
+Use `--no-yolo` to keep unattended operation with Codex auto approvals, without
+forcing a sandbox policy.
 Use `--include-thinking` to return all agent messages joined together for `codexapi run` (Codex only).
 
 Lead mode periodically checks in on a long-running agent session with the
@@ -303,7 +306,8 @@ codexapi ralph --cancel --cwd /path/to/project
 ```
 
 Science mode wraps a short task in a science prompt and runs it through the
-Ralph loop. It defaults to `--yolo` and expects progress notes in `SCIENCE.md`.
+Ralph loop. It defaults to dangerous no-sandbox automation and expects progress
+notes in `SCIENCE.md`.
 Each iteration appends the agent output to `LOGBOOK.md` and the runner extracts
 any improved figures of merit for optional notifications. You can also set
 `--max-duration` to stop after the current iteration once a time limit is hit.
@@ -336,33 +340,41 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False, model=None, thinking=None) -> str`
 
 Runs a single agent turn and returns only the agent's message. Any reasoning
 items are filtered out.
 
 - `prompt` (str): prompt to send to the agent backend.
 - `cwd` (str | PathLike | None): working directory for the agent session.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override. Codex maps this to `-c model=...`; Cursor maps it to `--model ...`.
+- `thinking` (str | None): Codex reasoning effort override, mapped to `-c model_reasoning_effort=...`.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False, model=None, thinking=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
 
 - `__call__(prompt) -> str`: send a prompt to the agent backend and return the message.
 - `thread_id -> str | None`: expose the underlying session id once created.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override.
+- `thinking` (str | None): Codex reasoning effort override.
 For Cursor, `thread_id` corresponds to the `session_id` returned by the agent.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None, backend=None, fast=False) -> dict`
@@ -437,7 +449,9 @@ Runs a task file over a list of items, updating the list file in place.
 - `task_file` (str | PathLike): YAML task file (must include `prompt`).
 - `n` (int | None): limit parallelism to N (default: run all items in parallel).
 - `cwd` (str | PathLike | None): working directory for the agent session.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
@@ -459,7 +473,8 @@ Simple result object returned by `foreach()`.
   `fast=True` / `--fast` also passes `service_tier=fast` and `features.fast_mode=true`.
 - Cursor backend uses `cursor agent --print --output-format json --trust` and parses the JSON result.
 - `include_thinking=True` only affects Codex; Cursor returns a single result string.
-- Passes `--yolo` by default (Codex uses `--full-auto` when disabled).
+- Uses dangerous no-sandbox automation by default. For Codex, `yolo=False`
+  uses auto approvals without forcing a sandbox policy.
 - Raises `RuntimeError` if the backend exits non-zero or returns no agent message.
 
 ## Configuration

{codexapi-0.12.9 → codexapi-0.12.11}/README.md

@@ -65,6 +65,8 @@ Use `backend="cursor"` (or set `CODEXAPI_BACKEND=cursor`) to switch to the
 Cursor agent backend.
 Use `fast=True` in Codex API calls, or `--fast` in the CLI, to opt into Codex
 fast mode. Normal mode is the default.
+Use `model="..."` and `thinking="..."` in Codex API calls to override the
+backend model and reasoning effort for a run.
 
 ## CLI
 
@@ -140,7 +142,8 @@ Resume a session and print the thread/session id to stderr:
 codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
-Use `--no-yolo` to disable `--yolo` (Codex uses `--full-auto`).
+Use `--no-yolo` to keep unattended operation with Codex auto approvals, without
+forcing a sandbox policy.
 Use `--include-thinking` to return all agent messages joined together for `codexapi run` (Codex only).
 
 Lead mode periodically checks in on a long-running agent session with the
@@ -288,7 +291,8 @@ codexapi ralph --cancel --cwd /path/to/project
 ```
 
 Science mode wraps a short task in a science prompt and runs it through the
-Ralph loop. It defaults to `--yolo` and expects progress notes in `SCIENCE.md`.
+Ralph loop. It defaults to dangerous no-sandbox automation and expects progress
+notes in `SCIENCE.md`.
 Each iteration appends the agent output to `LOGBOOK.md` and the runner extracts
 any improved figures of merit for optional notifications. You can also set
 `--max-duration` to stop after the current iteration once a time limit is hit.
@@ -321,33 +325,41 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False, model=None, thinking=None) -> str`
 
 Runs a single agent turn and returns only the agent's message. Any reasoning
 items are filtered out.
 
 - `prompt` (str): prompt to send to the agent backend.
 - `cwd` (str | PathLike | None): working directory for the agent session.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override. Codex maps this to `-c model=...`; Cursor maps it to `--model ...`.
+- `thinking` (str | None): Codex reasoning effort override, mapped to `-c model_reasoning_effort=...`.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False, model=None, thinking=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
 
 - `__call__(prompt) -> str`: send a prompt to the agent backend and return the message.
 - `thread_id -> str | None`: expose the underlying session id once created.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override.
+- `thinking` (str | None): Codex reasoning effort override.
 For Cursor, `thread_id` corresponds to the `session_id` returned by the agent.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None, backend=None, fast=False) -> dict`
@@ -422,7 +434,9 @@ Runs a task file over a list of items, updating the list file in place.
 - `task_file` (str | PathLike): YAML task file (must include `prompt`).
 - `n` (int | None): limit parallelism to N (default: run all items in parallel).
 - `cwd` (str | PathLike | None): working directory for the agent session.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
@@ -444,7 +458,8 @@ Simple result object returned by `foreach()`.
   `fast=True` / `--fast` also passes `service_tier=fast` and `features.fast_mode=true`.
 - Cursor backend uses `cursor agent --print --output-format json --trust` and parses the JSON result.
 - `include_thinking=True` only affects Codex; Cursor returns a single result string.
-- Passes `--yolo` by default (Codex uses `--full-auto` when disabled).
+- Uses dangerous no-sandbox automation by default. For Codex, `yolo=False`
+  uses auto approvals without forcing a sandbox policy.
 - Raises `RuntimeError` if the backend exits non-zero or returns no agent message.
 
 ## Configuration

{codexapi-0.12.9 → codexapi-0.12.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.12.9"
+version = "0.12.11"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"

{codexapi-0.12.9 → codexapi-0.12.11}/src/codexapi/__init__.py

@@ -1,6 +1,6 @@
 """Minimal Python API for running agent CLIs."""
 
-from .agent import Agent, WelfareStop, agent
+from .agent import Agent, WelfareStop, agent, build_agent_flags
 from .async_agent import AsyncAgent
 from .foreach import ForeachResult, foreach
 from .pushover import Pushover
@@ -15,6 +15,7 @@ __all__ = [
     "AsyncAgent",
     "ForeachResult",
     "Pushover",
+    "build_agent_flags",
     "quota_line",
     "rate_limits",
     "Ralph",
@@ -29,4 +30,4 @@ __all__ = [
     "task_result",
     "lead",
 ]
-__version__ = "0.12.9"
+__version__ = "0.12.11"

{codexapi-0.12.9 → codexapi-0.12.11}/src/codexapi/agent.py

@@ -11,6 +11,7 @@ from . import welfare
 _CODEX_BIN = os.environ.get("CODEX_BIN", "codex")
 _CURSOR_BIN = os.environ.get("CURSOR_BIN", "cursor")
 _SUPPORTED_BACKENDS = {"codex", "cursor"}
+_CURSOR_AGENT_BIN = os.path.expanduser("~/.local/bin/cursor-agent")
 
 
 def _resolve_backend(backend):
@@ -33,12 +34,15 @@ def _ensure_backend_available(backend, env=None):
         env_var = "CODEX_BIN"
         label = "Codex CLI"
     else:
-        command = _CURSOR_BIN
+        command = _cursor_bin(env)
         env_var = "CURSOR_BIN"
         label = "Cursor agent CLI"
     merged = _merged_env(env)
     path_value = None if merged is None else merged.get("PATH")
-    resolved = shutil.which(command, path=path_value)
+    if os.path.isabs(command):
+        resolved = command if os.path.exists(command) else None
+    else:
+        resolved = shutil.which(command, path=path_value)
     if resolved:
         return resolved
     raise RuntimeError(
@@ -55,24 +59,38 @@ def agent(
     backend=None,
     env=None,
     fast=False,
+    model=None,
+    thinking=None,
 ):
     """Run a single agent turn and return only the agent's message.
 
     Args:
         prompt: The user prompt to send to the agent backend.
         cwd: Optional working directory for the agent session.
-        yolo: Whether to pass --yolo to the agent backend.
+        yolo: Whether to use the backend's most permissive unattended mode.
         flags: Additional raw CLI flags to pass to the agent backend.
         include_thinking: When true, return all agent messages joined together.
         backend: Agent backend to use ("codex" or "cursor").
         env: Optional environment variables for the backend subprocess.
         fast: Enable Codex fast mode. Defaults to normal mode.
+        model: Optional backend model override.
+        thinking: Optional backend reasoning/thinking effort override.
 
     Returns:
         The agent's visible response text with reasoning traces removed.
     """
     message, _thread_id, _usage = _run_agent(
-        prompt, cwd, None, yolo, flags, include_thinking, backend, env, fast
+        prompt,
+        cwd,
+        None,
+        yolo,
+        flags,
+        include_thinking,
+        backend,
+        env,
+        fast,
+        model,
+        thinking,
     )
     return message
 
@@ -106,12 +124,14 @@ class Agent:
         backend=None,
         env=None,
         fast=False,
+        model=None,
+        thinking=None,
     ):
         """Create a new session wrapper.
 
         Args:
             cwd: Optional working directory for the agent session.
-            yolo: Whether to pass --yolo to the agent backend.
+            yolo: Whether to use the backend's most permissive unattended mode.
             thread_id: Optional thread/session id to resume from the first call.
             flags: Additional raw CLI flags to pass to the agent backend.
             welfare: When true, append welfare stop instructions to each prompt
@@ -120,6 +140,8 @@ class Agent:
             backend: Agent backend to use ("codex" or "cursor").
             env: Optional environment variables for the backend subprocess.
             fast: Enable Codex fast mode. Defaults to normal mode.
+            model: Optional backend model override.
+            thinking: Optional backend reasoning/thinking effort override.
         """
         self.cwd = cwd
         self._yolo = yolo
@@ -130,6 +152,8 @@ class Agent:
         self._backend = backend
         self._env = env
         self._fast = fast
+        self._model = model
+        self._thinking = thinking
         self.last_usage = {}
 
     def __call__(self, prompt):
@@ -146,6 +170,8 @@ class Agent:
             self._backend,
             self._env,
             self._fast,
+            self._model,
+            self._thinking,
         )
         if thread_id:
             self.thread_id = thread_id
@@ -165,29 +191,59 @@ def _run_agent(
     backend,
     env,
     fast=False,
+    model=None,
+    thinking=None,
 ):
     backend = _resolve_backend(backend)
     _ensure_backend_available(backend, env)
     if backend == "codex":
-        return _run_codex(prompt, cwd, thread_id, yolo, flags, include_thinking, env, fast)
-    return _run_cursor(prompt, cwd, thread_id, yolo, flags, include_thinking, env)
+        return _run_codex(
+            prompt,
+            cwd,
+            thread_id,
+            yolo,
+            flags,
+            include_thinking,
+            env,
+            fast,
+            model,
+            thinking,
+        )
+    return _run_cursor(
+        prompt,
+        cwd,
+        thread_id,
+        yolo,
+        flags,
+        include_thinking,
+        env,
+        model,
+        thinking,
+    )
 
 
-def _run_codex(prompt, cwd, thread_id, yolo, flags, include_thinking, env, fast=False):
+def _run_codex(
+    prompt,
+    cwd,
+    thread_id,
+    yolo,
+    flags,
+    include_thinking,
+    env,
+    fast=False,
+    model=None,
+    thinking=None,
+):
     """Invoke the Codex CLI and return the message plus thread id (if any)."""
-    command = [
-        _CODEX_BIN,
+    command = [_CODEX_BIN] + _codex_automation_flags(yolo) + [
         "exec",
         "--json",
         "--color",
         "never",
         "--skip-git-repo-check",
     ]
-    if yolo:
-        command.append("--yolo")
-    else:
-        command.append("--full-auto")
     command.extend(_codex_fast_config(fast))
+    command.extend(_agent_config_flag_parts("codex", model, thinking))
     if flags:
         command.extend(shlex.split(flags))
     if cwd:
@@ -215,6 +271,13 @@ def _run_codex(prompt, cwd, thread_id, yolo, flags, include_thinking, env, fast=
     return _parse_jsonl(result.stdout, include_thinking)
 
 
+def _codex_automation_flags(yolo):
+    """Return current Codex CLI flags for unattended operation."""
+    if yolo:
+        return ["--dangerously-bypass-approvals-and-sandbox"]
+    return ["--ask-for-approval", "never"]
+
+
 def _codex_fast_config(fast):
     """Return Codex config flags for normal or fast mode."""
     if fast:
@@ -227,11 +290,82 @@ def _codex_fast_config(fast):
     return ["-c", "features.fast_mode=false"]
 
 
-def _run_cursor(prompt, cwd, thread_id, yolo, flags, include_thinking, env):
+def _cursor_bin(env=None):
+    merged = _merged_env(env)
+    env_source = merged or os.environ
+    override = env_source.get("CURSOR_BIN", "").strip()
+    if override:
+        return os.path.expanduser(override)
+
+    path_value = None if merged is None else merged.get("PATH")
+    direct = shutil.which("cursor-agent", path=path_value)
+    if direct:
+        return direct
+    if os.path.exists(_CURSOR_AGENT_BIN):
+        return _CURSOR_AGENT_BIN
+    return _CURSOR_BIN
+
+
+def _cursor_command_prefix(env=None):
+    command = _cursor_bin(env)
+    if os.path.basename(command) == "cursor-agent":
+        return [command]
+    return [command, "agent"]
+
+
+def build_agent_flags(*, backend=None, model=None, thinking=None, flags=None):
+    """Return raw backend flags for a model/thinking configuration.
+
+    The returned string is suitable for APIs that accept the existing ``flags``
+    parameter.
+    """
+    backend = _resolve_backend(backend)
+    parts = _agent_config_flag_parts(backend, model, thinking)
+    if flags:
+        parts.extend(shlex.split(flags))
+    return shlex.join(parts)
+
+
+def _agent_config_flag_parts(backend, model=None, thinking=None):
+    backend = _resolve_backend(backend)
+    parts = []
+    model = _clean_optional_text(model)
+    thinking = _clean_optional_text(thinking)
+
+    if backend == "codex":
+        if model:
+            parts.extend(["-c", f"model={model}"])
+        if thinking:
+            parts.extend(["-c", f"model_reasoning_effort={thinking}"])
+        return parts
+
+    if model:
+        parts.extend(["--model", model])
+    if thinking:
+        raise ValueError("thinking is only supported by the codex backend")
+    return parts
+
+
+def _clean_optional_text(value):
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _run_cursor(
+    prompt,
+    cwd,
+    thread_id,
+    yolo,
+    flags,
+    include_thinking,
+    env,
+    model=None,
+    thinking=None,
+):
     """Invoke the Cursor agent CLI and return the message plus session id (if any)."""
-    command = [
-        _CURSOR_BIN,
-        "agent",
+    command = _cursor_command_prefix(env) + [
         "--trust",
     ]
     if cwd:
@@ -240,6 +374,7 @@ def _run_cursor(prompt, cwd, thread_id, yolo, flags, include_thinking, env):
         command.extend(["--resume", thread_id])
     if yolo:
         command.append("--yolo")
+    command.extend(_agent_config_flag_parts("cursor", model, thinking))
     if flags:
         command.extend(shlex.split(flags))
     command.extend(["--print", "--output-format", "json"])

{codexapi-0.12.9 → codexapi-0.12.11}/src/codexapi/async_agent.py

@@ -12,8 +12,10 @@ import uuid
 
 from .agent import (
     _CODEX_BIN,
-    _CURSOR_BIN,
+    _agent_config_flag_parts,
+    _codex_automation_flags,
     _codex_fast_config,
+    _cursor_command_prefix,
     _ensure_backend_available,
     _event_usage,
     _merged_env,
@@ -88,6 +90,8 @@ class AsyncAgent:
         env=None,
         name=None,
         fast=False,
+        model=None,
+        thinking=None,
     ):
         """Start a backend subprocess and return an async handle immediately."""
         if not isinstance(prompt, str) or not prompt.strip():
@@ -95,7 +99,7 @@ class AsyncAgent:
 
         backend = _resolve_backend(backend)
         _ensure_backend_available(backend, env)
-        command = _build_command(backend, cwd, yolo, flags, fast)
+        command = _build_command(backend, cwd, yolo, flags, fast, model, thinking)
         process = subprocess.Popen(
             command,
             stdin=subprocess.PIPE,
@@ -376,26 +380,22 @@ class AsyncAgent:
         return self._rollout_final_output
 
 
-def _build_command(backend, cwd, yolo, flags, fast=False):
+def _build_command(backend, cwd, yolo, flags, fast=False, model=None, thinking=None):
     if backend == "codex":
-        return _build_codex_command(cwd, yolo, flags, fast)
-    return _build_cursor_command(cwd, yolo, flags)
+        return _build_codex_command(cwd, yolo, flags, fast, model, thinking)
+    return _build_cursor_command(cwd, yolo, flags, model, thinking)
 
 
-def _build_codex_command(cwd, yolo, flags, fast=False):
-    command = [
-        _CODEX_BIN,
+def _build_codex_command(cwd, yolo, flags, fast=False, model=None, thinking=None):
+    command = [_CODEX_BIN] + _codex_automation_flags(yolo) + [
         "exec",
         "--json",
         "--color",
         "never",
         "--skip-git-repo-check",
     ]
-    if yolo:
-        command.append("--yolo")
-    else:
-        command.append("--full-auto")
     command.extend(_codex_fast_config(fast))
+    command.extend(_agent_config_flag_parts("codex", model, thinking))
     if flags:
         command.extend(shlex.split(flags))
     if cwd:
@@ -404,16 +404,15 @@ def _build_codex_command(cwd, yolo, flags, fast=False):
     return command
 
 
-def _build_cursor_command(cwd, yolo, flags):
-    command = [
-        _CURSOR_BIN,
-        "agent",
+def _build_cursor_command(cwd, yolo, flags, model=None, thinking=None):
+    command = _cursor_command_prefix() + [
         "--trust",
     ]
     if cwd:
         command.extend(["--workspace", os.fspath(cwd)])
     if yolo:
         command.append("--yolo")
+    command.extend(_agent_config_flag_parts("cursor", model, thinking))
     if flags:
         command.extend(shlex.split(flags))
     command.extend(["--print", "--output-format", "json"])

{codexapi-0.12.9 → codexapi-0.12.11}/src/codexapi/cli.py

@@ -1439,7 +1439,8 @@ def main(argv=None):
     science_help = (
         "Science mode (science command):\n"
         "  Wraps your short task in a science prompt and runs it via the Ralph loop.\n"
-        "  Default uses --yolo. Use --no-yolo to disable it.\n"
+        "  Default uses dangerous no-sandbox automation. "
+        "Use --no-yolo for auto approvals without forcing sandbox policy.\n"
         "  Optional --max-duration stops before starting the next iteration once\n"
         "  the duration limit is reached (e.g. 90m, 2h, 45s; default unit is minutes).\n"
     )
@@ -1479,7 +1480,7 @@ def main(argv=None):
         "--no-yolo",
         action="store_false",
         dest="yolo",
-        help="Disable --yolo (Codex uses --full-auto).",
+        help="Use auto approvals instead of dangerous no-sandbox automation.",
     )
     run_parser.add_argument(
         "--flags",
@@ -1535,7 +1536,7 @@ def main(argv=None):
         "--no-yolo",
         action="store_false",
         dest="yolo",
-        help="Disable --yolo (Codex uses --full-auto).",
+        help="Use auto approvals instead of dangerous no-sandbox automation.",
     )
     lead_parser.add_argument(
         "--flags",
@@ -1604,7 +1605,7 @@ def main(argv=None):
         "--no-yolo",
         action="store_false",
         dest="yolo",
-        help="Disable --yolo (Codex uses --full-auto).",
+        help="Use auto approvals instead of dangerous no-sandbox automation.",
     )
     agent_start.add_argument(
         "--flags",
@@ -1837,7 +1838,7 @@ def main(argv=None):
         "--no-yolo",
         action="store_false",
         dest="yolo",
-        help="Disable --yolo (Codex uses --full-auto).",
+        help="Use auto approvals instead of dangerous no-sandbox automation.",
     )
     task_parser.add_argument(
         "--flags",
@@ -1911,7 +1912,7 @@ def main(argv=None):
         "--no-yolo",
         action="store_false",
         dest="yolo",
-        help="Disable --yolo (Codex uses --full-auto).",
+        help="Use auto approvals instead of dangerous no-sandbox automation.",
     )
     ralph_parser.add_argument(
         "--flags",
@@ -1982,7 +1983,7 @@ def main(argv=None):
         "--no-yolo",
         action="store_false",
         dest="yolo",
-        help="Disable --yolo (Codex uses --full-auto).",
+        help="Use auto approvals instead of dangerous no-sandbox automation.",
     )
     science_parser.add_argument(
         "--flags",
@@ -2033,7 +2034,7 @@ def main(argv=None):
         "--no-yolo",
         action="store_false",
         dest="yolo",
-        help="Disable --yolo (Codex uses --full-auto).",
+        help="Use auto approvals instead of dangerous no-sandbox automation.",
     )
     foreach_parser.add_argument(
         "--flags",

{codexapi-0.12.9 → codexapi-0.12.11}/src/codexapi/lead.py

@@ -91,7 +91,7 @@ def lead(
         minutes: Check-in interval in whole minutes (>= 0).
         prompt: The original instruction prompt.
         cwd: Optional working directory for the agent session.
-        yolo: Whether to pass --yolo to the agent backend.
+        yolo: Whether to use the backend's most permissive unattended mode.
         flags: Additional raw CLI flags to pass to the agent backend.
         leadbook: Optional path to the leadbook file. Set to False to disable.
         backend: Agent backend to use ("codex" or "cursor").

{codexapi-0.12.9 → codexapi-0.12.11}/src/codexapi/task.py

@@ -275,7 +275,7 @@ def task(
             a string check prompt. The string "None" skips verification.
         max_iterations: Maximum number of task iterations (0 means unlimited).
         cwd: Optional working directory for the agent session.
-        yolo: Whether to pass --yolo to the agent backend.
+        yolo: Whether to use the backend's most permissive unattended mode.
         flags: Additional raw CLI flags to pass to the agent backend.
         progress: Whether to show a tqdm progress bar with status updates.
         set_up: Optional setup prompt to run before the task.

{codexapi-0.12.9 → codexapi-0.12.11/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.12.9
+Version: 0.12.11
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -80,6 +80,8 @@ Use `backend="cursor"` (or set `CODEXAPI_BACKEND=cursor`) to switch to the
 Cursor agent backend.
 Use `fast=True` in Codex API calls, or `--fast` in the CLI, to opt into Codex
 fast mode. Normal mode is the default.
+Use `model="..."` and `thinking="..."` in Codex API calls to override the
+backend model and reasoning effort for a run.
 
 ## CLI
 
@@ -155,7 +157,8 @@ Resume a session and print the thread/session id to stderr:
 codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
-Use `--no-yolo` to disable `--yolo` (Codex uses `--full-auto`).
+Use `--no-yolo` to keep unattended operation with Codex auto approvals, without
+forcing a sandbox policy.
 Use `--include-thinking` to return all agent messages joined together for `codexapi run` (Codex only).
 
 Lead mode periodically checks in on a long-running agent session with the
@@ -303,7 +306,8 @@ codexapi ralph --cancel --cwd /path/to/project
 ```
 
 Science mode wraps a short task in a science prompt and runs it through the
-Ralph loop. It defaults to `--yolo` and expects progress notes in `SCIENCE.md`.
+Ralph loop. It defaults to dangerous no-sandbox automation and expects progress
+notes in `SCIENCE.md`.
 Each iteration appends the agent output to `LOGBOOK.md` and the runner extracts
 any improved figures of merit for optional notifications. You can also set
 `--max-duration` to stop after the current iteration once a time limit is hit.
@@ -336,33 +340,41 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False, model=None, thinking=None) -> str`
 
 Runs a single agent turn and returns only the agent's message. Any reasoning
 items are filtered out.
 
 - `prompt` (str): prompt to send to the agent backend.
 - `cwd` (str | PathLike | None): working directory for the agent session.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override. Codex maps this to `-c model=...`; Cursor maps it to `--model ...`.
+- `thinking` (str | None): Codex reasoning effort override, mapped to `-c model_reasoning_effort=...`.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False, model=None, thinking=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
 
 - `__call__(prompt) -> str`: send a prompt to the agent backend and return the message.
 - `thread_id -> str | None`: expose the underlying session id once created.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override.
+- `thinking` (str | None): Codex reasoning effort override.
 For Cursor, `thread_id` corresponds to the `session_id` returned by the agent.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None, backend=None, fast=False) -> dict`
@@ -437,7 +449,9 @@ Runs a task file over a list of items, updating the list file in place.
 - `task_file` (str | PathLike): YAML task file (must include `prompt`).
 - `n` (int | None): limit parallelism to N (default: run all items in parallel).
 - `cwd` (str | PathLike | None): working directory for the agent session.
-- `yolo` (bool): pass `--yolo` when true (defaults to true).
+- `yolo` (bool): use the backend's most permissive unattended mode when true
+  (defaults to true). For Codex, `False` uses auto approvals without forcing a
+  sandbox policy.
 - `flags` (str | None): extra CLI flags to pass to the agent backend.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
@@ -459,7 +473,8 @@ Simple result object returned by `foreach()`.
   `fast=True` / `--fast` also passes `service_tier=fast` and `features.fast_mode=true`.
 - Cursor backend uses `cursor agent --print --output-format json --trust` and parses the JSON result.
 - `include_thinking=True` only affects Codex; Cursor returns a single result string.
-- Passes `--yolo` by default (Codex uses `--full-auto` when disabled).
+- Uses dangerous no-sandbox automation by default. For Codex, `yolo=False`
+  uses auto approvals without forcing a sandbox policy.
 - Raises `RuntimeError` if the backend exits non-zero or returns no agent message.
 
 ## Configuration

{codexapi-0.12.9 → codexapi-0.12.11}/tests/test_agent_backend.py

@@ -2,11 +2,12 @@ import json
 import sys
 import unittest
 from pathlib import Path
+from unittest.mock import patch
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 
-from codexapi.agent import _codex_fast_config, _parse_jsonl
-from codexapi.async_agent import _build_codex_command
+from codexapi.agent import _codex_fast_config, _parse_jsonl, build_agent_flags
+from codexapi.async_agent import _build_codex_command, _build_cursor_command
 
 
 class AgentBackendTests(unittest.TestCase):
@@ -29,11 +30,59 @@ class AgentBackendTests(unittest.TestCase):
         self.assertIn("features.fast_mode=false", command)
         self.assertNotIn("service_tier=fast", command)
 
+    def test_async_codex_command_uses_documented_yolo_flags(self):
+        command = _build_codex_command(None, True, None)
+        exec_index = command.index("exec")
+        self.assertIn("--dangerously-bypass-approvals-and-sandbox", command)
+        self.assertLess(
+            command.index("--dangerously-bypass-approvals-and-sandbox"),
+            exec_index,
+        )
+        self.assertGreater(command.index("--json"), exec_index)
+        self.assertNotIn("--yolo", command)
+
+    def test_async_codex_command_no_yolo_uses_auto_approval_mode(self):
+        command = _build_codex_command(None, False, None)
+        exec_index = command.index("exec")
+        self.assertLess(command.index("--ask-for-approval"), exec_index)
+        self.assertIn("never", command)
+        self.assertNotIn("--sandbox", command)
+        self.assertNotIn("--full-auto", command)
+
     def test_async_codex_command_can_enable_fast_mode(self):
         command = _build_codex_command(None, True, None, fast=True)
         self.assertIn("service_tier=fast", command)
         self.assertIn("features.fast_mode=true", command)
 
+    def test_build_agent_flags_maps_codex_model_and_thinking_to_config(self):
+        self.assertEqual(
+            build_agent_flags(backend="codex", model="gpt-5.5", thinking="xhigh"),
+            "-c model=gpt-5.5 -c model_reasoning_effort=xhigh",
+        )
+
+    def test_build_agent_flags_maps_cursor_model_to_model_flag(self):
+        self.assertEqual(
+            build_agent_flags(backend="cursor", model="claude-4"),
+            "--model claude-4",
+        )
+
+    def test_build_agent_flags_rejects_cursor_thinking(self):
+        with self.assertRaises(ValueError):
+            build_agent_flags(backend="cursor", thinking="high")
+
+    def test_async_codex_command_can_set_model_and_thinking(self):
+        command = _build_codex_command(None, True, None, model="gpt-5.5", thinking="high")
+        self.assertIn("model=gpt-5.5", command)
+        self.assertIn("model_reasoning_effort=high", command)
+
+    def test_async_cursor_command_can_use_direct_cursor_agent(self):
+        with patch("codexapi.async_agent._cursor_command_prefix", return_value=["/tmp/cursor-agent"]):
+            command = _build_cursor_command("/tmp/work", True, None, model="composer-2")
+        self.assertEqual(command[0], "/tmp/cursor-agent")
+        self.assertNotEqual(command[1], "agent")
+        self.assertIn("--model", command)
+        self.assertIn("composer-2", command)
+
     def test_parse_jsonl_extracts_last_token_usage(self):
         output = "\n".join(
             [