Reject mistyped ucode launch flags instead of forwarding them

The launch commands set `ignore_unknown_options=True` so an agent's own flags
pass straight through. That also meant a *mistyped* ucode flag — e.g.
`--skip-preflight-checks` instead of `--skip-preflight` — was silently handed
to the agent, where it does nothing, so `--skip-preflight` appeared not to work.

Add a guard that runs before launch and rejects any passthrough arg whose bare
name is a near-miss of a known ucode launch flag (a superstring like
`--skip-preflight-checks`, or a near-complete truncation), with an error naming
the intended flag. Unrelated agent flags (`--model`, `-r`,
`--dangerously-skip-permissions`, …) are left untouched and still pass through.

Co-authored-by: Isaac

Author: max-rozen-oss-db

src/ucode/cli.py

@@ -1359,6 +1359,51 @@ def _print_budget_panel(recommendation: dict, tool: str, managed: dict | None =
         console.print(panel)
 
 
+# ucode's own launch flags. The launch commands set `ignore_unknown_options`
+# so the agent's own flags pass straight through, which also means a *mistyped*
+# ucode flag (e.g. `--skip-preflight-checks`) is silently forwarded to the agent
+# instead of taking effect. We catch near-misses of these up front so a typo
+# fails loudly rather than quietly running with the flag ignored.
+_UCODE_LAUNCH_FLAGS = frozenset(
+    {
+        "--skip-preflight",
+        "--workspace",
+        "--provider",
+        "--enable-smart-routing",
+        "--disable-smart-routing",
+    }
+)
+
+
+def _reject_mistyped_ucode_flag(ctx: typer.Context) -> None:
+    """Error on a passthrough arg that looks like a misspelled ucode launch flag.
+
+    Only flags whose bare name (before any `=`) is a near-miss of a known ucode
+    flag are rejected — an unrelated agent flag like `--model` is left alone. This
+    keeps `--skip-preflight-checks` from being silently handed to the agent (where
+    it does nothing) instead of enabling the ucode behavior the user intended.
+    """
+    for raw in ctx.args:
+        if not raw.startswith("--"):
+            continue
+        name = raw.split("=", 1)[0]
+        if name in _UCODE_LAUNCH_FLAGS:
+            continue
+        for known in _UCODE_LAUNCH_FLAGS:
+            # A superstring is the reported bug: `--skip-preflight-checks` starts
+            # with `--skip-preflight`. A near-complete truncation (`--skip-prefligh`,
+            # one char short) is caught too — but a short generic prefix like
+            # `--enable` is left alone so a real agent flag isn't hijacked.
+            superstring = name.startswith(known)
+            truncation = known.startswith(name) and len(known) - len(name) <= 3
+            if superstring or truncation:
+                raise RuntimeError(
+                    f"Unknown ucode option '{name}'. Did you mean '{known}'? "
+                    "(ucode flags must be spelled exactly; anything else is passed "
+                    "through to the agent.)"
+                )
+
+
 def _launch_tool(
     tool_name: str,
     ctx: typer.Context,
@@ -1370,6 +1415,7 @@ def _launch_tool(
     recommendation: dict | None = None,
 ) -> None:
     try:
+        _reject_mistyped_ucode_flag(ctx)
         tool = normalize_tool(tool_name)
         # An explicit --workspace targets that workspace for this launch (and
         # auto-configures it if unseen), so `ucode claude --provider ... --workspace ...`

tests/test_cli.py

@@ -820,6 +820,70 @@ def test_skip_preflight_bypasses_cli_version_check(self):
         )
 
 
+class TestMistypedUcodeFlag:
+    """A launch command sets `ignore_unknown_options`, so a mistyped ucode flag
+    would otherwise be forwarded to the agent and silently do nothing. The guard
+    turns near-misses of ucode's own flags into a loud error."""
+
+    def test_superstring_typo_is_rejected(self):
+        # The reported bug: `--skip-preflight-checks` never enabled the behavior.
+        with patch("ucode.cli.ensure_bootstrap_dependencies") as mock_bootstrap:
+            result = runner.invoke(app, ["claude", "--skip-preflight-checks"])
+        assert result.exit_code == 1
+        out = _strip_ansi(result.output)
+        assert "--skip-preflight-checks" in out
+        assert "--skip-preflight" in out
+        # Fails before any bootstrap/install work runs.
+        mock_bootstrap.assert_not_called()
+
+    def test_plural_workspace_typo_is_rejected(self):
+        result = runner.invoke(app, ["codex", "--workspaces", "https://ws"])
+        assert result.exit_code == 1
+        assert "--workspace" in _strip_ansi(result.output)
+
+    def test_correct_flag_is_not_rejected(self):
+        with (
+            patch("ucode.cli.ensure_bootstrap_dependencies"),
+            patch("ucode.cli.load_state", return_value=MINIMAL_STATE),
+            patch("ucode.cli._auto_configure_tool"),
+            patch("ucode.cli.configure_shared_state", return_value=MINIMAL_STATE),
+            patch("ucode.cli.ensure_provider_state", return_value=MINIMAL_STATE),
+            patch(
+                "ucode.cli.resolve_launch_model",
+                return_value=(MINIMAL_STATE, "databricks-claude-sonnet-4"),
+            ),
+            patch("ucode.cli.configure_tool", return_value=MINIMAL_STATE),
+            patch("ucode.cli._fetch_managed_config", return_value=None),
+            patch("ucode.cli.launch_agent"),
+        ):
+            result = runner.invoke(app, ["claude", "--skip-preflight"])
+        assert result.exit_code == 0, result.output
+
+    def test_unrelated_agent_flag_passes_through(self):
+        # A real agent flag that isn't a near-miss of any ucode flag reaches the agent.
+        captured = {}
+        with (
+            patch("ucode.cli.ensure_bootstrap_dependencies"),
+            patch("ucode.cli.load_state", return_value=MINIMAL_STATE),
+            patch("ucode.cli._auto_configure_tool"),
+            patch("ucode.cli.configure_shared_state", return_value=MINIMAL_STATE),
+            patch("ucode.cli.ensure_provider_state", return_value=MINIMAL_STATE),
+            patch(
+                "ucode.cli.resolve_launch_model",
+                return_value=(MINIMAL_STATE, "databricks-claude-sonnet-4"),
+            ),
+            patch("ucode.cli.configure_tool", return_value=MINIMAL_STATE),
+            patch("ucode.cli._fetch_managed_config", return_value=None),
+            patch(
+                "ucode.cli.launch_agent",
+                side_effect=lambda tool, state, args: captured.setdefault("args", args),
+            ),
+        ):
+            result = runner.invoke(app, ["claude", "--model", "opus"])
+        assert result.exit_code == 0, result.output
+        assert "--model" in captured.get("args", [])
+
+
 class TestPassthroughArgs:
     @pytest.mark.parametrize(
         "tool,extra_args",