Extend intelligent routing to Claude Code

Generalize the Codex intelligent-routing engine into a shared core and add
Claude Code support. `ucode claude --enable-intelligent-routing` routes the
root session (via ANTHROPIC_MODEL) and subagents (via a PreToolUse hook that
rewrites the Agent tool's model) through the workspace task_v1 router.

- routing.py / hooks.py: harness-agnostic routes:select call, decision shape,
  canary/audit bookkeeping, and hook add/remove machinery. codex_routing /
  codex_hooks now delegate to these (behavior unchanged; 62 Codex tests green).
- claude_routing.py / claude_hooks.py: Claude cc-scenario arms
  (claude-opus-4-8, claude-sonnet-5, harness "claude"), both offered
  unconditionally per the frozen task_v1 menu; settings.json hook shape.
- claude agent + CLI: enable/disable flags, hidden claude-router-hook command,
  claude_intelligent_routing_enabled state key.

Co-authored-by: Isaac

Author: masonc08

src/ucode/agents/__init__.py

@@ -312,6 +312,7 @@ def configure_tool(
     provider: str | None = None,
     provider_models: dict[str, str] | None = None,
     relayed: bool = False,
+    route_root_model: str | None = None,
 ) -> dict:
     result: dict | tuple[dict, str]
     if tool == "codex":
@@ -322,7 +323,12 @@ def configure_tool(
         if not model and not provider:
             raise RuntimeError(f"A {tool} model must be selected before configuration.")
         result = claude.write_tool_config(
-            state, model, provider=provider, provider_models=provider_models, relayed=relayed
+            state,
+            model,
+            provider=provider,
+            provider_models=provider_models,
+            relayed=relayed,
+            route_root_model=route_root_model,
         )
     else:
         # provider routing is claude/codex-only; every other tool needs a model.

src/ucode/agents/claude.py

@@ -28,6 +28,10 @@
     build_tool_base_url,
     get_databricks_token,
 )
+from ucode.intelligent_routing.claude_hooks import (
+    remove_intelligent_routing_hooks,
+    sync_intelligent_routing_hooks,
+)
 from ucode.launcher import exec_or_spawn
 from ucode.state import mark_tool_managed, save_state
 from ucode.telemetry import agent_version, ucode_version
@@ -46,6 +50,12 @@
     "backup_path": CLAUDE_BACKUP_PATH,
 }
 
+# Per-workspace opt-in flag for Claude Code intelligent routing (state key).
+INTELLIGENT_ROUTING_STATE_KEY = "claude_intelligent_routing_enabled"
+# Claude Code settings.json hook events ucode manages when routing is enabled;
+# marked managed so they're tracked/reverted with the rest of ucode's config.
+CLAUDE_ROUTING_HOOK_EVENTS = ("PreToolUse", "SessionStart", "SubagentStart")
+
 
 def is_update_available() -> tuple[str, str] | None:
     return available_npm_package_update(SPEC["package"])
@@ -161,6 +171,7 @@ def render_overlay(
     fable_enabled: bool = False,
     relayed: bool = False,
     relayed_base_url: str | None = None,
+    route_root_model: str | None = None,
 ) -> tuple[dict, list[list[str]]]:
     """Return (overlay, managed_key_paths) for Claude settings.json.
 
@@ -212,13 +223,20 @@ def render_overlay(
         "ENABLE_TOOL_SEARCH": "1",
         "CLAUDE_CODE_USE_GATEWAY": "1",
     }
-    # Intentionally NOT setting ANTHROPIC_MODEL. Setting it produces a duplicate
-    # catalog row in Claude Code's /model picker (e.g. "Opus 4.8 (1M context) ✓")
-    # on top of the family-alias row from ANTHROPIC_DEFAULT_OPUS_MODEL. Without
-    # it, Default resolves through the pinned family alias and the picker shows
-    # only one row per model. `ucode claude -- --model X` still overrides for a
-    # single session via Claude Code's own --model flag.
+    # Intentionally NOT setting ANTHROPIC_MODEL by default. Setting it produces a
+    # duplicate catalog row in Claude Code's /model picker (e.g. "Opus 4.8 (1M
+    # context) ✓") on top of the family-alias row from ANTHROPIC_DEFAULT_OPUS_MODEL.
+    # Without it, Default resolves through the pinned family alias and the picker
+    # shows only one row per model. `ucode claude -- --model X` still overrides for
+    # a single session via Claude Code's own --model flag.
+    #
+    # The one exception is intelligent routing: `route_root_model` pins the
+    # router's per-launch pick for the root session as ANTHROPIC_MODEL. The
+    # duplicate-picker-row cost is acceptable because the whole point is to launch
+    # on the routed model rather than the family default.
     _ = model  # API stability; no longer pinned via env.
+    if route_root_model:
+        env["ANTHROPIC_MODEL"] = route_root_model
     # A Bedrock-backed provider needs its provider-side ids pinned verbatim
     # (Claude Code's canonical names aren't routable there). These come from the
     # service's targets, already de-duped to one id per family upstream.
@@ -336,12 +354,41 @@ def _unregister_web_search_mcp() -> None:
             pass
 
 
+def intelligent_routing_enabled(state: dict) -> bool:
+    """Return whether the current workspace opted into Claude Code routing."""
+    return state.get(INTELLIGENT_ROUTING_STATE_KEY) is True
+
+
+def enable_intelligent_routing(state: dict) -> dict:
+    """Persist the current workspace's Claude Code intelligent-routing opt-in."""
+    state[INTELLIGENT_ROUTING_STATE_KEY] = True
+    return state
+
+
+def disable_intelligent_routing(state: dict) -> bool:
+    """Disable routing and remove only ucode's Claude Code routing hooks."""
+    state.pop(INTELLIGENT_ROUTING_STATE_KEY, None)
+    if state.get("workspace"):
+        save_state(state)
+    changed = False
+    if CLAUDE_SETTINGS_PATH.exists():
+        doc = read_json_safe(CLAUDE_SETTINGS_PATH)
+        if remove_intelligent_routing_hooks(doc):
+            write_json_file(CLAUDE_SETTINGS_PATH, doc)
+            changed = True
+    from ucode.intelligent_routing.claude_routing import clear_routing_artifacts
+
+    clear_routing_artifacts()
+    return changed
+
+
 def write_tool_config(
     state: dict,
     model: str | None,
     provider: str | None = None,
     provider_models: dict[str, str] | None = None,
     relayed: bool = False,
+    route_root_model: str | None = None,
 ) -> dict:
     backup_existing_file(CLAUDE_SETTINGS_PATH, CLAUDE_BACKUP_PATH)
     web_search_model = _resolve_web_search_model(state)
@@ -360,6 +407,7 @@ def write_tool_config(
         fable_enabled=bool(state.get("fable_enabled")),
         relayed=relayed,
         relayed_base_url=relayed_base_url,
+        route_root_model=route_root_model,
     )
     tracing_env_vars = tracing_env(state, "claude")
     stop_hook_command = claude_tracing_stop_hook_command() if tracing_env_vars else None
@@ -404,6 +452,13 @@ def write_tool_config(
     if isinstance(merged_env, dict):
         for key in CLAUDE_REMOVED_ENV_KEYS:
             merged_env.pop(key, None)
+    # Intelligent-routing hooks: install ucode's PreToolUse/SessionStart/
+    # SubagentStart hooks when routing is enabled (and not under a provider,
+    # which pins no Databricks model), else surgically strip only ucode's own.
+    routing_enabled = intelligent_routing_enabled(state) and provider is None
+    sync_intelligent_routing_hooks(merged, state, enabled=routing_enabled)
+    if routing_enabled:
+        managed_keys = managed_keys + [["hooks", event] for event in CLAUDE_ROUTING_HOOK_EVENTS]
     write_json_file(CLAUDE_SETTINGS_PATH, merged)
 
     if web_search_model: