codex/ucode: exec real binary for non-interactive subcommands, skip init

ucode's launch runs full session init on every invocation — auth validation,
per-launch model discovery, config write — before exec'ing the agent. For
non-interactive invocations that need none of it, this only adds latency and
can corrupt output:

  - `codex app-server` is a server subcommand the *caller* configures (e.g.
    omnigent supplies a private CODEX_HOME + its own provider config); ucode's
    init adds several seconds and delays the socket bind past the caller's
    readiness budget, so the app-server times out. It also rejects the global
    `--profile` ucode injects.
  - `<agent> --version` / `--help` are info commands; init delays them, and
    ucode's own banner/version can be parsed by a caller instead of the agent's.

Add a passthrough: for a universal info flag (--version/-V/--help/-h) or a
tool-declared non-interactive subcommand (an agent module's
PASSTHROUGH_SUBCOMMANDS; codex -> app-server), exec the real binary directly
with no ucode flags or init. Extensible: add a flag to _PASSTHROUGH_GLOBAL_FLAGS,
or a PASSTHROUGH_SUBCOMMANDS set + subcommand() to an agent module.

This supersedes the earlier codex --profile-skip for app-server — the
passthrough runs before launch(), so ucode never adds --profile there — so
launch() goes back to always attaching --profile for the runtime subcommands
that accept it.

Co-authored-by: Isaac

Author: Edwinhe03

src/ucode/agents/__init__.py

@@ -24,6 +24,7 @@
     map_bedrock_claude_models,
     resolve_provider_service,
 )
+from ucode.launcher import exec_or_spawn
 from ucode.state import get_provider_service, load_state, save_state
 from ucode.telemetry import agent_version
 from ucode.ui import (
@@ -65,6 +66,13 @@
 DEFAULT_TOOL = "codex"
 BUNDLE_VERSION = 1
 
+# Global flags that only print info and launch no session — for ANY tool, exec
+# the real binary directly, skipping ucode init. A ``codex --version`` probe
+# must be both fast (init runs network validation + model discovery) and clean
+# (ucode's own banner/version can otherwise be parsed by a caller instead of the
+# agent's). Extend by adding a flag here.
+_PASSTHROUGH_GLOBAL_FLAGS = frozenset({"--version", "-V", "--help", "-h"})
+
 
 def normalize_tool(tool: str) -> str:
     normalized = TOOL_ALIASES.get(tool.strip().lower())
@@ -321,6 +329,42 @@ def launch(tool: str, state: dict, tool_args: list[str]) -> None:
     _MODULES[tool].launch(state, tool_args)
 
 
+def is_passthrough_invocation(tool: str, tool_args: list[str]) -> bool:
+    """Whether *tool_args* is a non-interactive invocation that needs no ucode
+    init and should exec the real binary directly (see :func:`passthrough`).
+
+    Two extensible cases:
+      * a universal info flag (``--version``/``--help``, see
+        :data:`_PASSTHROUGH_GLOBAL_FLAGS`), or
+      * a tool-declared non-interactive subcommand — the agent module's
+        ``PASSTHROUGH_SUBCOMMANDS``, located via its ``subcommand()`` parser —
+        e.g. codex ``app-server``, which the caller configures itself.
+
+    Extend by adding a flag above, or a ``PASSTHROUGH_SUBCOMMANDS`` set +
+    ``subcommand()`` to an agent module.
+    """
+    if any(arg in _PASSTHROUGH_GLOBAL_FLAGS for arg in tool_args):
+        return True
+    module = _MODULES[tool]
+    subcommands = getattr(module, "PASSTHROUGH_SUBCOMMANDS", frozenset())
+    if not subcommands:
+        return False
+    resolve = getattr(module, "subcommand", None)
+    return resolve is not None and resolve(tool_args) in subcommands
+
+
+def passthrough(tool: str, tool_args: list[str]) -> None:
+    """Exec the real tool binary directly, skipping all ucode init/config.
+
+    For the non-interactive invocations :func:`is_passthrough_invocation`
+    matches: an info flag needs nothing, and a passthrough subcommand is
+    configured by its caller (auth/gateway/model/policies). No ucode flags are
+    injected. Relies on the self-healing wrapper's recursion sentinel to reach
+    the real binary, exactly like :func:`launch`.
+    """
+    exec_or_spawn([TOOL_SPECS[tool]["binary"], *tool_args])
+
+
 def check_gateway_endpoint(state: dict, tool: str) -> bool:
     """V2-only: a tool is available iff we discovered models for it."""
     if tool == "claude":

src/ucode/agents/codex.py

@@ -391,6 +391,71 @@ def _gpt_version_key(entry: tuple[str, tuple[int, int | None, int | None, str]])
     return max(parsed, key=_gpt_version_key)[0]
 
 
+# Non-interactive subcommands that launch no interactive session and are
+# configured by the CALLER, not ucode — e.g. omnigent runs ``codex app-server``
+# with a private CODEX_HOME + its own provider config. ucode's launch init
+# (auth validation, per-launch model discovery, config write) is redundant for
+# these, and its latency overruns the caller's app-server readiness budget — so
+# ucode execs the real binary directly, skipping init (see
+# ``agents.is_passthrough_invocation``). This also sidesteps ``--profile``
+# entirely: ``codex app-server`` rejects the global ``--profile`` ("--profile
+# only applies to runtime commands and codex mcp"), and the passthrough — which
+# runs before ``launch`` — never adds it.
+PASSTHROUGH_SUBCOMMANDS = frozenset({"app-server"})
+
+# codex global options that consume the following token as their value. Used to
+# skip past a leading global (e.g. ``--model X``) when locating the subcommand,
+# so it isn't mistaken for the subcommand itself. Boolean flags take no value;
+# ``--flag=value`` forms are self-contained and handled inline.
+_CODEX_GLOBAL_VALUE_FLAGS = frozenset(
+    {
+        "-c",
+        "--config",
+        "-i",
+        "--image",
+        "-m",
+        "--model",
+        "-p",
+        "--profile",
+        "-s",
+        "--sandbox",
+        "-C",
+        "--cd",
+        "-a",
+        "--ask-for-approval",
+        "--enable",
+        "--disable",
+        "--remote",
+        "--remote-auth-token-env",
+        "--local-provider",
+        "--add-dir",
+    }
+)
+
+
+def _codex_subcommand(tool_args: list[str]) -> str | None:
+    """Return the codex subcommand in *tool_args*, skipping global options.
+
+    ``None`` when there is no subcommand (the interactive TUI).
+    """
+    i = 0
+    while i < len(tool_args):
+        arg = tool_args[i]
+        if not arg.startswith("-"):
+            return arg
+        # A bare value flag (``--model X``) consumes the next token too; a
+        # ``--flag=value`` form or a boolean flag consumes only itself.
+        if "=" not in arg and arg in _CODEX_GLOBAL_VALUE_FLAGS:
+            i += 1
+        i += 1
+    return None
+
+
+# Public alias so cross-agent dispatch (agents.is_passthrough_invocation) can
+# resolve the codex subcommand without reaching into a private helper.
+subcommand = _codex_subcommand
+
+
 def launch(state: dict, tool_args: list[str]) -> None:
     binary = SPEC["binary"]
     workspace = state.get("workspace")

src/ucode/cli.py

@@ -17,7 +17,9 @@
     ensure_bootstrap_dependencies,
     ensure_provider_state,
     install_tool_binary,
+    is_passthrough_invocation,
     normalize_tool,
+    passthrough,
     provider_permission_error,
     resolve_launch_model,
     resolve_provider_models,
@@ -825,6 +827,16 @@ def _auto_configure_tool(tool: str) -> None:
 def _launch_tool(tool_name: str, ctx: typer.Context, provider: str | None = None) -> None:
     try:
         tool = normalize_tool(tool_name)
+        # Non-interactive invocations — a universal info flag (--version/--help)
+        # or a tool-declared non-interactive subcommand (e.g. codex app-server,
+        # which the caller configures itself) — need none of ucode's session
+        # init (auth validation, per-launch model discovery, config write). That
+        # init only delays the output and can even corrupt a caller's
+        # `--version` probe (ucode's banner/version parsed instead of the
+        # agent's). Exec the real binary directly.
+        if is_passthrough_invocation(tool, ctx.args):
+            passthrough(tool, ctx.args)
+            return
         existing = load_state()
         # Workspaces configured with --use-pat export the profile's PAT as
         # DATABRICKS_BEARER up front so every auth check below (and the

tests/test_agent_codex.py

@@ -4,6 +4,7 @@
 
 import os
 
+from ucode import agents
 from ucode.agents import codex
 from ucode.config_io import read_toml_safe
 
@@ -436,3 +437,69 @@ def fake_execvp(binary: str, args: list[str]) -> None:
 
         assert os.environ["OAUTH_TOKEN"] == "fresh-token"
         assert exec_calls == [("codex", ["codex", "--profile", "ucode", "--search"])]
+
+    def test_keeps_profile_for_exec_subcommand(self, monkeypatch):
+        exec_calls: list[tuple[str, list[str]]] = []
+
+        def fake_execvp(binary: str, args: list[str]) -> None:
+            exec_calls.append((binary, args))
+            raise RuntimeError("stop")
+
+        monkeypatch.setattr(codex, "get_databricks_token", lambda workspace, profile=None: "tok")
+        monkeypatch.setattr(os, "execvp", fake_execvp)
+
+        try:
+            codex.launch({"workspace": WS}, ["exec", "say hi"])
+        except RuntimeError:
+            pass
+
+        assert exec_calls == [("codex", ["codex", "--profile", "ucode", "exec", "say hi"])]
+
+
+class TestCodexSubcommand:
+    def test_none_for_interactive(self):
+        assert codex._codex_subcommand([]) is None
+        assert codex._codex_subcommand(["--search"]) is None
+
+    def test_finds_bare_subcommand(self):
+        assert codex._codex_subcommand(["exec", "hi"]) == "exec"
+        assert codex._codex_subcommand(["app-server"]) == "app-server"
+
+    def test_skips_leading_value_flags(self):
+        assert codex._codex_subcommand(["--model", "gpt-5", "app-server"]) == "app-server"
+        assert codex._codex_subcommand(["-c", "k=v", "exec"]) == "exec"
+
+
+class TestPassthroughInvocation:
+    def test_app_server_is_passthrough(self):
+        # codex app-server is caller-configured (omnigent) and rejects --profile;
+        # ucode execs it directly, skipping init — even behind a leading global.
+        assert agents.is_passthrough_invocation("codex", ["app-server", "--listen", "u"])
+        assert agents.is_passthrough_invocation("codex", ["--model", "gpt-5", "app-server"])
+
+    def test_info_flags_passthrough_for_any_tool(self):
+        for tool in ("codex", "claude"):
+            assert agents.is_passthrough_invocation(tool, ["--version"])
+            assert agents.is_passthrough_invocation(tool, ["-V"])
+            assert agents.is_passthrough_invocation(tool, ["--help"])
+            assert agents.is_passthrough_invocation(tool, ["-h"])
+
+    def test_interactive_and_exec_are_not_passthrough(self):
+        assert not agents.is_passthrough_invocation("codex", [])
+        assert not agents.is_passthrough_invocation("codex", ["exec", "say hi"])
+        # a prompt that merely mentions app-server is not the subcommand
+        assert not agents.is_passthrough_invocation("codex", ["exec", "run the app-server"])
+        assert not agents.is_passthrough_invocation("claude", [])
+
+    def test_claude_has_no_passthrough_subcommands(self):
+        # claude has no non-interactive server subcommand; only info flags apply.
+        assert not agents.is_passthrough_invocation("claude", ["mcp", "list"])
+
+    def test_passthrough_execs_real_binary_without_ucode_flags(self, monkeypatch):
+        calls: list[list[str]] = []
+        monkeypatch.setattr(agents, "exec_or_spawn", lambda argv: calls.append(argv))
+        agents.passthrough("codex", ["app-server", "--listen", "u"])
+        assert calls == [["codex", "app-server", "--listen", "u"]]
+
+    def test_handles_equals_form(self):
+        assert codex._codex_subcommand(["--model=gpt-5", "app-server"]) == "app-server"