Surface the router rationale in the shown message, and log it

Both "Using Smart Routing" messages — the launch-time notice and the
subagent-routing hook's systemMessage — now include the router's rationale, so
the "why" is visible, not just the "what". Previously the launch notice never
showed it and the subagent hook put it only in permissionDecisionReason (a
field the harness doesn't surface in that line). Centralized in
RoutingDecision.display_message() so both paths format identically.

Also persist the rationale in the decisions.jsonl record, so an empty value
cleanly distinguishes "the gateway returned no rationale" from a display-side
placement bug.

Co-authored-by: Isaac

Author: masonc08

src/ucode/cli.py

@@ -1140,7 +1140,7 @@ def _launch_tool(
                     decision, routing_error = route_launch_model(state, ctx.args)
                 if decision is not None:
                     resolved_model = decision.model
-                    print_note(f"Using Smart Routing. Routing to {resolved_model}.")
+                    print_note(decision.display_message())
                 elif routing_error:
                     print_warning(
                         f"Smart routing was unavailable ({routing_error}); using {resolved_model}."

src/ucode/smart_routing/routing.py

@@ -33,6 +33,19 @@ class RoutingDecision:
     raw_model: str
     rationale: str = ""
 
+    def display_message(self, model_label: str | None = None) -> str:
+        """User-facing "Using Smart Routing" line, with the router's rationale.
+
+        Used by both the launch-time notice and the subagent-routing hook so the
+        "what" (model) and the "why" (rationale) are surfaced consistently.
+        ``model_label`` overrides the shown model id (e.g. a harness-translated
+        id); defaults to ``model``. The rationale is appended when present.
+        """
+        message = f"Using Smart Routing. Routing to {model_label or self.model}."
+        if self.rationale:
+            message += f" {self.rationale}"
+        return message
+
 
 def normalize_model(model: str) -> str:
     """Strip provider prefixes so router arms and workspace ids compare equal.
@@ -199,15 +212,16 @@ def route_spawn_tool(
     routed_model = model_id_mapper(decision.model)
     if record_decision is not None:
         record_decision(payload, task, decision, routed_model)
-    routing_message = f"Using Smart Routing. Routing to {routed_model}."
+    # Surface the router's rationale in BOTH the systemMessage (the line the
+    # harness shows the user) and permissionDecisionReason — the "why", not just
+    # the "what". The shown model is the harness-translated id (routed_model).
+    routing_message = decision.display_message(model_label=routed_model)
     output: dict[str, Any] = {
         "hookEventName": "PreToolUse",
         "permissionDecision": "allow",
         "updatedInput": {**tool_input, "model": routed_model},
         "permissionDecisionReason": routing_message,
     }
-    if decision.rationale:
-        output["permissionDecisionReason"] += f" {decision.rationale}"
     return {"systemMessage": routing_message, "hookSpecificOutput": output}
 
 
@@ -271,6 +285,9 @@ def write_decision_record(
             "task_name": task_name,
             "router_model": decision.raw_model,
             "requested_model": requested_model,
+            # Persisted for diagnosis: an empty value means the gateway returned
+            # no rationale (vs. a placement bug in how we surface it).
+            "rationale": decision.rationale,
             "at": time.time(),
         },
     )

tests/test_cli.py

@@ -11,6 +11,7 @@
 from typer.testing import CliRunner
 
 from ucode.cli import app
+from ucode.smart_routing.routing import RoutingDecision
 
 _ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
 
@@ -226,7 +227,11 @@ def test_enabled_codex_launch_uses_routed_root_model(self):
             "smart_routing_enabled": True,
             "codex_models": ["databricks-gpt-5", "databricks-gpt-5-5"],
         }
-        decision = MagicMock(model="databricks-gpt-5-5")
+        decision = RoutingDecision(
+            model="databricks-gpt-5-5",
+            raw_model="gpt-5-6-sol",
+            rationale="Cross-cutting refactor.",
+        )
         with (
             patch("ucode.cli.ensure_bootstrap_dependencies"),
             patch("ucode.cli.load_state", return_value=state),
@@ -244,7 +249,11 @@ def test_enabled_codex_launch_uses_routed_root_model(self):
 
         assert result.exit_code == 0, result.output
         assert mock_configure.call_args.args[2] == "databricks-gpt-5-5"
-        assert "Using Smart Routing. Routing to databricks-gpt-5-5." in _strip_ansi(result.output)
+        # The launch notice surfaces both the routed model and the rationale.
+        assert (
+            "Using Smart Routing. Routing to databricks-gpt-5-5. Cross-cutting refactor."
+            in _strip_ansi(result.output)
+        )
 
 
 class TestMcpSubcommands:

tests/test_codex_routing.py

@@ -143,7 +143,11 @@ def test_spawn_rewrite_preserves_original_input(monkeypatch):
     )
 
     hook = output["hookSpecificOutput"]
-    assert output["systemMessage"] == "Using Smart Routing. Routing to gpt-5.5."
+    # The rationale is surfaced in BOTH the systemMessage (shown to the user) and
+    # permissionDecisionReason, so the "why" is visible, not just the "what".
+    assert output["systemMessage"] == (
+        "Using Smart Routing. Routing to gpt-5.5. Review needs deeper reasoning."
+    )
     assert hook["permissionDecision"] == "allow"
     assert hook["updatedInput"] == {
         "task_name": "reviewer",
@@ -276,3 +280,37 @@ def test_decision_is_reconciled_with_actual_subagent_model(tmp_path, monkeypatch
     assert record["router_model"] == "gpt-5-6-luna"
     assert record["requested_model"] == "gpt-5.6-luna"
     assert record["matches_router_decision"] is True
+
+
+def test_decision_record_persists_rationale(tmp_path, monkeypatch):
+    decisions = tmp_path / "decisions.jsonl"
+    monkeypatch.setattr(codex_routing, "DECISIONS_PATH", decisions)
+    monkeypatch.setattr(
+        codex_routing,
+        "request_routing_decision",
+        lambda *args, **kwargs: (
+            codex_routing.RoutingDecision(
+                model="system.ai.gpt-5-6-sol",
+                raw_model="gpt-5-6-sol",
+                rationale="Cross-cutting refactor needs the strongest model.",
+            ),
+            None,
+        ),
+    )
+
+    codex_routing.route_pre_tool_use(
+        {
+            "session_id": "s1",
+            "tool_name": "collaborationspawn_agent",
+            "tool_input": {"task_name": "refactor", "message": "encrypted"},
+        },
+        workspace=WS,
+        token="token",
+        available_models=["system.ai.gpt-5-6-sol", "system.ai.gpt-5-6-luna"],
+        audit_decision=True,
+    )
+
+    # The rationale is persisted so an empty value distinguishes "gateway
+    # returned none" from a display-placement bug.
+    record = json.loads(decisions.read_text().strip())
+    assert record["rationale"] == "Cross-cutting refactor needs the strongest model."