Generalize smart-routing engine (rename from intelligent routing)

Refactor the Codex smart-routing internals into a harness-agnostic core so a
second agent can reuse them, and rename the feature "intelligent routing" ->
"smart routing" throughout (package dir smart_routing/, symbols, CLI flags
--enable/--disable-smart-routing, hidden codex-router-hook, user-facing
strings) per naming guidance.

- smart_routing/routing.py + hooks.py: shared routes:select call, decision
  shape, canary/audit bookkeeping, and hook add/remove machinery.
- smart_routing/codex_routing.py + codex_hooks.py delegate to the shared core
  (behavior unchanged).
- State key is the agent-neutral "smart_routing_enabled" so a later agent can
  share one opt-in.

Co-authored-by: Isaac

Author: masonc08

src/ucode/agents/codex.py

@@ -20,11 +20,11 @@
     build_tool_base_url,
     get_databricks_token,
 )
-from ucode.intelligent_routing.codex_hooks import (
-    remove_intelligent_routing_hooks,
-    sync_intelligent_routing_hooks,
-)
 from ucode.launcher import exec_or_spawn
+from ucode.smart_routing.codex_hooks import (
+    remove_smart_routing_hooks,
+    sync_smart_routing_hooks,
+)
 from ucode.state import mark_tool_managed, save_state
 from ucode.telemetry import agent_version, ucode_version
 
@@ -39,7 +39,9 @@
 MINIMUM_CODEX_VERSION_TEXT = "0.134.0"
 MINIMUM_ROUTING_CODEX_VERSION = (0, 145, 0)
 MINIMUM_ROUTING_CODEX_VERSION_TEXT = "0.145.0"
-INTELLIGENT_ROUTING_STATE_KEY = "codex_intelligent_routing_enabled"
+# Shared across agents: one opt-in enables smart routing for every routing-capable
+# tool (codex, claude), so a workspace turns it on once.
+SMART_ROUTING_STATE_KEY = "smart_routing_enabled"
 
 
 SPEC: ToolSpec = {
@@ -325,10 +327,9 @@ def write_tool_config(state: dict, model: str | None = None, provider: str | Non
     databricks_profile = state.get("profile")
 
     if _use_legacy_layout():
-        if intelligent_routing_enabled(state) and provider is None:
+        if smart_routing_enabled(state) and provider is None:
             raise RuntimeError(
-                "Codex intelligent routing requires Codex "
-                f"{MINIMUM_ROUTING_CODEX_VERSION_TEXT} or newer."
+                f"Codex smart routing requires Codex {MINIMUM_ROUTING_CODEX_VERSION_TEXT} or newer."
             )
         # Codex < 0.134.0 only reads ~/.codex/config.toml. Write the shared
         # config with [profiles.ucode] + shared [model_providers.ucode-databricks]
@@ -370,10 +371,10 @@ def write_tool_config(state: dict, model: str | None = None, provider: str | Non
         # deep_merge can't drop keys, so clear a `model` pinned by an earlier
         # non-provider run that the provider overlay omits.
         doc.pop("model", None)
-    sync_intelligent_routing_hooks(
+    sync_smart_routing_hooks(
         doc,
         state,
-        enabled=intelligent_routing_enabled(state) and provider is None,
+        enabled=smart_routing_enabled(state) and provider is None,
     )
     write_toml_file(CODEX_CONFIG_PATH, doc)
     state = mark_tool_managed(state, "codex", MANAGED_KEYS)
@@ -416,38 +417,38 @@ def launch(state: dict, tool_args: list[str]) -> None:
     exec_or_spawn([binary, "--profile", CODEX_PROFILE_NAME, *tool_args])
 
 
-def intelligent_routing_enabled(state: dict) -> bool:
+def smart_routing_enabled(state: dict) -> bool:
     """Return whether the current workspace opted into Codex routing."""
-    return state.get(INTELLIGENT_ROUTING_STATE_KEY) is True
+    return state.get(SMART_ROUTING_STATE_KEY) is True
 
 
-def enable_intelligent_routing(state: dict) -> dict:
-    """Persist the current workspace's Codex intelligent-routing opt-in."""
+def enable_smart_routing(state: dict) -> dict:
+    """Persist the current workspace's Codex smart-routing opt-in."""
     parsed = _parse_version(agent_version(SPEC["binary"]))
     if parsed is not None and parsed < MINIMUM_ROUTING_CODEX_VERSION:
         raise RuntimeError(
-            "Codex intelligent routing requires Codex "
+            "Codex smart routing requires Codex "
             f"{MINIMUM_ROUTING_CODEX_VERSION_TEXT} or newer; found "
             f"{agent_version(SPEC['binary'])}."
         )
-    state[INTELLIGENT_ROUTING_STATE_KEY] = True
+    state[SMART_ROUTING_STATE_KEY] = True
     return state
 
 
-def disable_intelligent_routing(state: dict) -> bool:
+def disable_smart_routing(state: dict) -> bool:
     """Disable routing and remove only ucode's Codex routing hooks."""
-    state.pop(INTELLIGENT_ROUTING_STATE_KEY, None)
+    state.pop(SMART_ROUTING_STATE_KEY, None)
     if state.get("workspace"):
         save_state(state)
     changed = False
     for path in (CODEX_CONFIG_PATH, LEGACY_CODEX_CONFIG_PATH):
         if not path.exists():
             continue
         doc = read_toml_safe(path)
-        if remove_intelligent_routing_hooks(doc):
+        if remove_smart_routing_hooks(doc):
             write_toml_file(path, doc)
             changed = True
-    from ucode.intelligent_routing.codex_routing import clear_routing_artifacts
+    from ucode.smart_routing.codex_routing import clear_routing_artifacts
 
     clear_routing_artifacts()
     return changed

src/ucode/cli.py

@@ -30,10 +30,10 @@
     launch as launch_agent,
 )
 from ucode.agents.codex import (
-    disable_intelligent_routing,
-    enable_intelligent_routing,
-    intelligent_routing_enabled,
+    disable_smart_routing,
+    enable_smart_routing,
     revert_legacy_shared_config,
+    smart_routing_enabled,
 )
 from ucode.agents.pi import PI_SETTINGS_BACKUP_PATH, PI_SETTINGS_PATH
 from ucode.config_io import restore_file, set_dry_run
@@ -58,7 +58,6 @@
     resolve_pat_token,
     run_databricks_login,
 )
-from ucode.intelligent_routing.codex_routing import route_launch_model
 from ucode.mcp import (
     MCP_CLIENTS,
     SKILLS_MCP_KIND,
@@ -68,6 +67,7 @@
     revert_mcp_configs,
 )
 from ucode.skills_download import configure_skills_download_command
+from ucode.smart_routing.codex_routing import route_launch_model
 from ucode.state import (
     STATE_PATH,
     clear_state,
@@ -967,11 +967,11 @@ def codex_router_hook_cmd(
     use_pat: Annotated[bool, typer.Option("--use-pat")] = False,
     model: Annotated[list[str] | None, typer.Option("--model")] = None,
 ) -> None:
-    """Run a Codex intelligent-routing lifecycle hook."""
+    """Run a Codex smart-routing lifecycle hook."""
     import json
     import sys
 
-    from ucode.intelligent_routing.codex_routing import (
+    from ucode.smart_routing.codex_routing import (
         record_session_start,
         record_subagent_start,
         route_pre_tool_use,
@@ -993,7 +993,7 @@ def codex_router_hook_cmd(
             sys.stdout.write(
                 json.dumps(
                     {
-                        "systemMessage": "Intelligent Routing verified. "
+                        "systemMessage": "Smart Routing verified. "
                         f"Subagent is using {record.get('model')}."
                     }
                 )
@@ -1002,7 +1002,7 @@ def codex_router_hook_cmd(
             sys.stdout.write(
                 json.dumps(
                     {
-                        "systemMessage": "Intelligent Routing mismatch: router requested "
+                        "systemMessage": "Smart Routing mismatch: router requested "
                         f"{record.get('requested_model')}, but Codex started "
                         f"{record.get('model')}."
                     }
@@ -1073,7 +1073,7 @@ def _launch_tool(
     provider: str | None = None,
     skip_preflight: bool = False,
     workspace: str | None = None,
-    enable_codex_intelligent_routing: bool = False,
+    enable_codex_smart_routing: bool = False,
 ) -> None:
     try:
         tool = normalize_tool(tool_name)
@@ -1097,9 +1097,9 @@ def _launch_tool(
         # An explicit --provider overrides the persisted choice; otherwise fall
         # back to whatever `ucode configure` saved for this tool.
         provider = provider or get_provider_service(state, tool)
-        if tool == "codex" and enable_codex_intelligent_routing and provider:
+        if tool == "codex" and enable_codex_smart_routing and provider:
             raise RuntimeError(
-                "Codex intelligent routing cannot be enabled with --provider. "
+                "Codex smart routing cannot be enabled with --provider. "
                 "Launch without a Model Provider Service and try again."
             )
         # Validate the provider service before launching — it must exist, be a
@@ -1125,8 +1125,8 @@ def _launch_tool(
             skip_model_discovery=bool(provider),
             skip_preflight=skip_preflight,
         )
-        if tool == "codex" and enable_codex_intelligent_routing:
-            state = enable_intelligent_routing(state)
+        if tool == "codex" and enable_codex_smart_routing:
+            state = enable_smart_routing(state)
         if provider:
             # Routing through a Model Provider Service pins no Databricks model;
             # the agent uses its own canonical model names (header selects the
@@ -1135,16 +1135,15 @@ def _launch_tool(
             resolved_model = None
         else:
             state, resolved_model = resolve_launch_model(tool, state, None)
-            if tool == "codex" and intelligent_routing_enabled(state):
-                with spinner("Selecting a Codex model with intelligent routing..."):
+            if tool == "codex" and smart_routing_enabled(state):
+                with spinner("Selecting a Codex model with smart routing..."):
                     decision, routing_error = route_launch_model(state, ctx.args)
                 if decision is not None:
                     resolved_model = decision.model
-                    print_note(f"Using Intelligent Routing. Routing to {resolved_model}.")
+                    print_note(f"Using Smart Routing. Routing to {resolved_model}.")
                 elif routing_error:
                     print_warning(
-                        f"Intelligent routing was unavailable ({routing_error}); "
-                        f"using {resolved_model}."
+                        f"Smart routing was unavailable ({routing_error}); using {resolved_model}."
                     )
         state = configure_tool(
             tool,
@@ -1159,9 +1158,9 @@ def _launch_tool(
             print_kv("Provider", provider)
         elif resolved_model:
             print_kv("Model", resolved_model)
-        if tool == "codex" and intelligent_routing_enabled(state) and not provider:
-            print_kv("Intelligent routing", "enabled")
-            if enable_codex_intelligent_routing:
+        if tool == "codex" and smart_routing_enabled(state) and not provider:
+            print_kv("Smart routing", "enabled")
+            if enable_codex_smart_routing:
                 print_note(
                     "Codex requires one-time hook review. Open `/hooks` and trust the "
                     "ucode routing hooks if prompted."
@@ -1220,36 +1219,36 @@ def codex_cmd(
     ] = None,
     skip_preflight: SkipPreflightOption = False,
     workspace: WorkspaceOption = None,
-    enable_intelligent_routing_flag: Annotated[
+    enable_smart_routing_flag: Annotated[
         bool,
         typer.Option(
-            "--enable-intelligent-routing",
+            "--enable-smart-routing",
             help="Enable AI Gateway model routing for Codex sessions and subagents.",
         ),
     ] = False,
-    disable_intelligent_routing_flag: Annotated[
+    disable_smart_routing_flag: Annotated[
         bool,
         typer.Option(
-            "--disable-intelligent-routing",
-            help="Disable intelligent routing and remove ucode's Codex routing hooks.",
+            "--disable-smart-routing",
+            help="Disable smart routing and remove ucode's Codex routing hooks.",
         ),
     ] = False,
 ) -> None:
     """Launch Codex via Databricks."""
-    if enable_intelligent_routing_flag and disable_intelligent_routing_flag:
-        print_err("Use only one of --enable-intelligent-routing or --disable-intelligent-routing.")
+    if enable_smart_routing_flag and disable_smart_routing_flag:
+        print_err("Use only one of --enable-smart-routing or --disable-smart-routing.")
         raise typer.Exit(1)
-    if disable_intelligent_routing_flag:
-        disable_intelligent_routing(load_state())
-        print_success("Codex intelligent routing disabled; ucode routing hooks removed")
+    if disable_smart_routing_flag:
+        disable_smart_routing(load_state())
+        print_success("Codex smart routing disabled; ucode routing hooks removed")
         return
     _launch_tool(
         "codex",
         ctx,
         provider=provider,
         skip_preflight=skip_preflight,
         workspace=workspace,
-        enable_codex_intelligent_routing=enable_intelligent_routing_flag,
+        enable_codex_smart_routing=enable_smart_routing_flag,
     )