claude-smart 0.2.49 → 0.2.50

package/plugin/scripts/dashboard-service.sh

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# Auto-start the claude-smart Next.js dashboard (port 3001) if it's not
-# already running. Mirrors how claude-mem boots its worker on SessionStart:
+# Auto-start the claude-smart Next.js dashboard if it's not already running.
+# Mirrors how claude-mem boots its worker on SessionStart:
 # detached, returns immediately so the hook doesn't block the session.
 #
 # Subcommands:
-#   start         probe the port; spawn `npm run start` if our dashboard
-#                 isn't already answering. Never builds in foreground — if
+#   start         probe the port; spawn local `next start` if no claude-smart
+#                 dashboard is already answering. Never builds in foreground — if
 #                 .next is missing, logs and bails (Setup is responsible for
 #                 the build; rerun it or restart Claude Code to retry).
 #   stop          kill the recorded process group, and (if our dashboard
@@ -28,7 +28,10 @@ fi
 claude_smart_prepend_node_bins
 claude_smart_source_reflexio_env
 
-PORT=3001
+BACKEND_PORT="${BACKEND_PORT:-8071}"
+PORT="${DASHBOARD_PORT:-${PORT:-3001}}"
+export BACKEND_PORT
+claude_smart_derive_reflexio_url_from_backend_port
 
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "dashboard-service.sh" "$@"
@@ -48,116 +51,46 @@ kill_group() {
   claude_smart_kill_tree "$1"
 }
 
+dashboard_pid_command_matches() {
+  pid="$1"
+  cmdline="$(claude_smart_pid_command "$pid" | tr '\n' ' ' || true)"
+  [ -n "$cmdline" ] || return 1
+  case "$cmdline" in
+    *"$DASHBOARD_DIR"*|*next-server*|*next*start*|*node*next*|*claude-smart*dashboard*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+kill_recorded_dashboard() {
+  if [ -f "$PID_FILE" ]; then
+    pid="$(cat "$PID_FILE" 2>/dev/null || true)"
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null && dashboard_pid_command_matches "$pid"; then
+      kill_group "$pid"
+    fi
+    rm -f "$PID_FILE"
+  fi
+}
+
 # True if the marker header served by app/api/health is present on the
 # port. Requires curl — absence is reported as false. This deliberately
 # accepts any claude-smart dashboard, including stale cache versions, so
 # stop/uninstall can safely reap them without touching foreign listeners.
 marker_responds() {
   command -v curl >/dev/null 2>&1 || return 1
-  curl -sfI "http://127.0.0.1:$PORT/api/health" 2>/dev/null \
+  curl -sfI --connect-timeout 1 --max-time 2 "http://127.0.0.1:$PORT/api/health" 2>/dev/null \
     | grep -qi '^x-claude-smart-dashboard:'
 }
 
-dashboard_health_headers() {
-  command -v curl >/dev/null 2>&1 || return 1
-  curl -sfI --connect-timeout 2 --max-time 5 "http://127.0.0.1:$PORT/api/health" 2>/dev/null
-}
-
-header_value_from() {
-  header_name="$1"
-  awk -v wanted="$header_name" '
-    BEGIN { wanted = tolower(wanted) ":" }
-    {
-      line = $0
-      sub(/\r$/, "", line)
-      lower = tolower(line)
-      if (index(lower, wanted) == 1) {
-        sub(/^[^:]*:[[:space:]]*/, "", line)
-        print line
-        exit
-      }
-    }
-  '
-}
-
-canonical_dir() {
-  dir="$1"
-  (cd "$dir" 2>/dev/null && pwd -P) || printf '%s\n' "$dir"
-}
-
-normalize_identity_path() {
-  path="$1"
-  if claude_smart_is_windows; then
-    if command -v cygpath >/dev/null 2>&1; then
-      path="$(cygpath -u "$path" 2>/dev/null || printf '%s\n' "$path")"
-    else
-      path="$(
-        printf '%s\n' "$path" | awk '{
-          gsub(/\\/, "/")
-          if ($0 ~ /^[A-Za-z]:/) {
-            drive = tolower(substr($0, 1, 1))
-            sub(/^[A-Za-z]:/, "/" drive)
-          }
-          print
-        }'
-      )"
-    fi
-  fi
-  while [ "${path%/}" != "$path" ] && [ "$path" != "/" ]; do
-    path="${path%/}"
-  done
-  printf '%s\n' "$path"
-}
-
-# True only if *this plugin root's* dashboard is on the port. The generic
-# x-claude-smart-dashboard marker is intentionally not enough: after an
-# install/update, an older cache can keep serving port 3001 until restarted.
-dashboard_matches_current_root() {
-  expected_root="$(normalize_identity_path "$(canonical_dir "$PLUGIN_ROOT")")"
-  headers="$(dashboard_health_headers)" || return 1
-  printf '%s\n' "$headers" | grep -qi '^x-claude-smart-dashboard:' || return 1
-  actual_root="$(printf '%s\n' "$headers" | header_value_from "x-claude-smart-plugin-root")"
-  [ -n "$actual_root" ] || return 1
-  actual_root="$(normalize_identity_path "$actual_root")"
-  [ "$actual_root" = "$expected_root" ]
-}
-
 # Kill a claude-smart dashboard listener currently holding the port. Gated by
-# marker_responds so a foreign app on 3001 is never killed.
+# marker_responds so a foreign listener on the dashboard port is never killed.
 stop_dashboard_listener() {
   marker_responds || return 0
-  command -v lsof >/dev/null 2>&1 || return 0
-  port_pid=$(lsof -t -i ":$PORT" -sTCP:LISTEN 2>/dev/null | head -n1)
-  [ -n "$port_pid" ] || return 0
-  kill -TERM "$port_pid" 2>/dev/null || true
-  for _ in 1 2 3 4 5; do
-    kill -0 "$port_pid" 2>/dev/null || return 0
-    sleep 0.2
-  done
-  kill -KILL "$port_pid" 2>/dev/null || true
-}
-
-# True only if *our* dashboard is on the port. Uses plugin-root identity so a
-# stale claude-smart listener doesn't cause us to silently skip starting.
-is_our_dashboard_running() {
-  if [ -f "$PID_FILE" ]; then
-    pid=$(cat "$PID_FILE" 2>/dev/null || echo "")
-    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
-      # PID alive — still verify the port responds with our marker so we
-      # don't claim "running" when the server crashed but the group leader
-      # lingered.
-      if command -v curl >/dev/null 2>&1; then
-        dashboard_matches_current_root && return 0
-      else
-        # No curl — fall back to PID liveness alone.
-        return 0
-      fi
-    fi
-  fi
-  # No PID or dead PID — probe the port for our marker (recovers after a
-  # stale PID file from a crash).
-  dashboard_matches_current_root && return 0
-  return 1
+  kill_recorded_dashboard
+  claude_smart_reap_port_listeners_matching "$PORT" \
+    '*next-server*' \
+    '*next*start*' \
+    '*node*next*' \
+    '*claude-smart*dashboard*' || true
 }
 
 # True if *something* is listening on the port, regardless of marker.
@@ -170,6 +103,46 @@ port_occupied() {
   (echo >"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null
 }
 
+resolve_next_bin() {
+  if claude_smart_is_windows; then
+    for candidate in "$DASHBOARD_DIR/node_modules/.bin/next.cmd" "$DASHBOARD_DIR/node_modules/.bin/next"; do
+      [ -f "$candidate" ] && { printf '%s\n' "$candidate"; return 0; }
+    done
+  else
+    for candidate in "$DASHBOARD_DIR/node_modules/.bin/next" "$DASHBOARD_DIR/node_modules/.bin/next.cmd"; do
+      [ -f "$candidate" ] && { printf '%s\n' "$candidate"; return 0; }
+    done
+  fi
+  return 1
+}
+
+spawn_dashboard() {
+  NEXT_BIN="$(resolve_next_bin || true)"
+  if [ -z "$NEXT_BIN" ]; then
+    reason="local Next.js binary is missing; run claude-smart install/update to restore dashboard dependencies"
+    echo "[claude-smart] dashboard: $reason" >>"$LOG_FILE"
+    claude_smart_write_dashboard_unavailable "$reason"
+    return 1
+  fi
+  cd "$DASHBOARD_DIR"
+  export CLAUDE_SMART_DASHBOARD_WORKSPACE="$WORKSPACE_CWD"
+  # Invoke Next directly so custom DASHBOARD_PORT/PORT values are honored
+  # without relying on package.json's fixed start script.
+  CLAUDE_SMART_SPAWN_KEEP_OUTPUT=1 claude_smart_spawn_detached "$NEXT_BIN" start -p "$PORT" -H 127.0.0.1 >>"$LOG_FILE" 2>&1
+  dash_pid=$!
+  echo "$dash_pid" > "$PID_FILE"
+}
+
+wait_for_dashboard_marker() {
+  attempts="$1"
+  while [ "$attempts" -gt 0 ]; do
+    marker_responds && return 0
+    attempts=$((attempts - 1))
+    sleep 1
+  done
+  marker_responds
+}
+
 case "$CMD" in
   start)
     if claude_smart_is_internal_invocation_env; then
@@ -181,11 +154,19 @@ case "$CMD" in
       emit_ok; exit 0
     fi
     if [ ! -d "$DASHBOARD_DIR" ]; then emit_ok; exit 0; fi
-    if is_our_dashboard_running; then claude_smart_clear_dashboard_unavailable; emit_ok; exit 0; fi
-    if marker_responds; then
-      echo "[claude-smart] dashboard: stale claude-smart dashboard on port $PORT; restarting from $PLUGIN_ROOT" >>"$LOG_FILE"
-      stop_dashboard_listener
+    if marker_responds; then claude_smart_clear_dashboard_unavailable; emit_ok; exit 0; fi
+    if ! claude_smart_service_lock "dashboard"; then
+      for _ in 1 2 3 4 5; do
+        if marker_responds; then
+          claude_smart_clear_dashboard_unavailable
+          emit_ok; exit 0
+        fi
+        sleep 0.2
+      done
+      emit_ok; exit 0
     fi
+    trap 'claude_smart_service_unlock "dashboard"' EXIT
+    if marker_responds; then claude_smart_clear_dashboard_unavailable; emit_ok; exit 0; fi
     if port_occupied; then
       echo "[claude-smart] dashboard: port $PORT held by another process; skipping" >>"$LOG_FILE"
       emit_ok; exit 0
@@ -221,8 +202,6 @@ case "$CMD" in
       emit_ok; exit 0
     fi
 
-    cd "$DASHBOARD_DIR"
-
     # Detach so the hook returns immediately. claude_smart_spawn_detached
     # picks the strongest primitive available:
     #   - Linux: setsid (puts child in its own session/group, pid==pgid).
@@ -230,36 +209,41 @@ case "$CMD" in
     #   - Windows: nohup alone (no process groups; tree-kill via taskkill).
     # Caller-side `>>file 2>&1` redirection is honoured before the child
     # detaches, so per-OS log paths stay identical.
-    export CLAUDE_SMART_DASHBOARD_WORKSPACE="$WORKSPACE_CWD"
-    CLAUDE_SMART_SPAWN_KEEP_OUTPUT=1 claude_smart_spawn_detached "$NPM_BIN" run start >>"$LOG_FILE" 2>&1
-    dash_pid=$!
-    # Record the spawned pid, not a pgid sampled with ps. On POSIX,
-    # setsid/python os.setsid make this pid the new process group leader;
-    # sampling immediately can race and capture the caller's pgid instead.
-    # On Windows, claude_smart_kill_tree translates the MSYS pid to WINPID.
-    echo "$dash_pid" > "$PID_FILE"
-    dashboard_ready=0
-    for _ in 1 2 3 4 5; do
-      if dashboard_matches_current_root; then
-        dashboard_ready=1
-        claude_smart_clear_dashboard_unavailable
-        break
+    if ! spawn_dashboard; then
+      emit_ok; exit 0
+    fi
+    if wait_for_dashboard_marker 5; then
+      claude_smart_clear_dashboard_unavailable
+      emit_ok; exit 0
+    fi
+    if ! kill -0 "$dash_pid" 2>/dev/null; then
+      sleep 2
+      if port_occupied; then
+        if marker_responds; then
+          claude_smart_clear_dashboard_unavailable
+        else
+          claude_smart_write_dashboard_unavailable "dashboard process exited and port $PORT is now held by a non-claude-smart listener; see $LOG_FILE"
+        fi
+      else
+        echo "[claude-smart] dashboard: first start exited before readiness; retrying once" >>"$LOG_FILE"
+        if spawn_dashboard; then
+          if wait_for_dashboard_marker 5; then
+            claude_smart_clear_dashboard_unavailable
+          else
+            claude_smart_write_dashboard_unavailable "dashboard process spawned but did not respond on http://127.0.0.1:$PORT within 5s; see $LOG_FILE"
+          fi
+        fi
       fi
-      sleep 1
-    done
-    if [ "$dashboard_ready" != "1" ]; then
+    else
       claude_smart_write_dashboard_unavailable "dashboard process spawned but did not respond on http://127.0.0.1:$PORT within 5s; see $LOG_FILE"
     fi
     emit_ok
     ;;
   stop)
-    if [ -f "$PID_FILE" ]; then
-      kill_group "$(cat "$PID_FILE" 2>/dev/null)"
-      rm -f "$PID_FILE"
-    fi
+    kill_recorded_dashboard
     # Fallback: if a claude-smart dashboard is still responding on the port (e.g.,
     # was started outside this script, or the PGID kill missed because
-    # the process wasn't the group leader) kill whoever owns the port.
+    # the process wasn't the group leader) reap only dashboard-shaped listeners.
     # Gated on the marker header so we never touch a foreign listener.
     stop_dashboard_listener
     emit_ok
@@ -269,15 +253,12 @@ case "$CMD" in
     # interactions/playbooks between sessions. Opt in to teardown by setting
     # CLAUDE_SMART_DASHBOARD_STOP_ON_END=1 in the environment.
     if [ "${CLAUDE_SMART_DASHBOARD_STOP_ON_END:-0}" = "1" ]; then
-      if [ -f "$PID_FILE" ]; then
-        kill_group "$(cat "$PID_FILE" 2>/dev/null)"
-        rm -f "$PID_FILE"
-      fi
+      kill_recorded_dashboard
     fi
     emit_ok
     ;;
   status)
-    if is_our_dashboard_running; then echo "running on http://localhost:$PORT"; else echo "not running"; fi
+    if marker_responds; then echo "running on http://localhost:$PORT"; else echo "not running"; fi
     ;;
   *)
     emit_ok

package/plugin/scripts/hook_entry.sh

@@ -44,10 +44,13 @@ claude_smart_source_login_path
 # Explicit fallback for the astral.sh installer's default paths, in case
 # the user's login-shell rc hasn't yet been re-sourced to pick them up.
 claude_smart_prepend_astral_bins
+BACKEND_PORT="${BACKEND_PORT:-8071}"
+export BACKEND_PORT
 claude_smart_source_reflexio_env
 
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "hook_entry.sh" "$@"
+claude_smart_derive_reflexio_url_from_backend_port
 
 FAILURE_MARKER="$HOME/.claude-smart/install-failed"
 STATE_DIR="$HOME/.claude-smart"

package/plugin/scripts/smart-install.sh

@@ -149,7 +149,21 @@ install_vendored_reflexio() {
   local VENDORED_REFLEXIO PLUGIN_PYTHON
 
   VENDORED_REFLEXIO="$PLUGIN_ROOT/vendor/reflexio"
-  [ -f "$VENDORED_REFLEXIO/pyproject.toml" ] || return 0
+  if [ ! -f "$VENDORED_REFLEXIO/pyproject.toml" ]; then
+    # A host plugin cache (~/.claude/plugins/cache/..., ~/.codex/plugins/cache/...)
+    # is only ever populated from the npm package, which always carries the
+    # vendored runtime. Missing it there means the plugin was installed straight
+    # from the GitHub marketplace, where the bundle is gitignored — the backend
+    # could never start. Fail here, at Setup, rather than at first session.
+    case "$PLUGIN_ROOT" in
+      */plugins/cache/*)
+        write_failure "bundled Reflexio runtime is missing from $VENDORED_REFLEXIO. This happens when claude-smart is installed from the GitHub marketplace, which does not carry the generated runtime. Install with: npx claude-smart install"
+        ;;
+    esac
+    # A source checkout legitimately has no vendor bundle (it is generated at
+    # pack time); reflexio comes from the plugin venv instead.
+    return 0
+  fi
 
   if claude_smart_is_windows; then
     PLUGIN_PYTHON="$PLUGIN_ROOT/.venv/Scripts/python.exe"

package/plugin/src/claude_smart/cli.py

@@ -2185,6 +2185,20 @@ def cmd_restart(args: argparse.Namespace) -> int:
         return 0
 
     if do_backend:
+        # Preparing the replacement can reinstall the vendored Reflexio if its
+        # version drifted, so this both validates and repairs. It must succeed
+        # before we stop anything: a backend we cannot replace is better left
+        # running.
+        sys.stdout.write("Preparing reflexio backend replacement…\n")
+        preflight_rc = _run_service(_BACKEND_SCRIPT, "preflight")
+        if preflight_rc != 0:
+            sys.stderr.write(
+                "error: reflexio backend replacement failed preflight; "
+                "existing services were not changed.\n"
+                "Repair the bundled runtime with: npx claude-smart update\n"
+            )
+            return preflight_rc
+
         sys.stdout.write("Stopping reflexio backend…\n")
         _run_service(_BACKEND_SCRIPT, "stop")
     if do_dashboard:

package/plugin/src/claude_smart/context_inject.py

@@ -59,6 +59,9 @@ def emit_context(
         project_id=project_id,
         query=query,
         top_k=top_k,
+        # Scopes server-side dedup: rules already injected into this session
+        # are not returned again; next-best matches backfill instead.
+        session_id=session_id or None,
     )
     renderer = (
         context_format.render_inline_compact_with_registry

package/plugin/src/claude_smart/env_config.py

@@ -29,7 +29,10 @@ DEFAULT_CLAUDE_SMART_HOST = runtime.HOST_CLAUDE_CODE
 
 _LOCAL_DEFAULT_ENTRIES = (
     (
-        "# Route reflexio generation through the configured local host CLI",
+        "# Set to 1 to route reflexio generation through the active host CLI "
+        "(claude for Claude Code, the host compatibility bridge for OpenCode/Codex). "
+        "Set to 0 to disable that provider so reflexio auto-detects a cloud LLM "
+        "key (anthropic, minimax, openai, etc.) from ~/.claude-smart/.env instead.",
         CLAUDE_SMART_USE_LOCAL_CLI_ENV,
         "1",
     ),

package/plugin/src/claude_smart/events/post_tool.py

@@ -6,7 +6,7 @@ import re
 import time
 from typing import Any
 
-from claude_smart import state
+from claude_smart import runtime, state
 
 # Tool inputs are persisted locally and later published to reflexio, so we
 # apply a conservative redaction pass at ingestion time. Chosen to avoid
@@ -144,5 +144,6 @@ def handle(payload: dict[str, Any]) -> None:
         "tool_input": _redact(payload.get("tool_input") or {}),
         "tool_output": _redact_string(output_text) if output_text else "",
         "status": _derive_status(tool_response),
+        "host": runtime.attribution_host(),
     }
     state.append(session_id, record)

package/plugin/src/claude_smart/events/session_end.py

@@ -21,7 +21,7 @@ import time
 from pathlib import Path
 from typing import Any
 
-from claude_smart import env_config, ids, publish, state
+from claude_smart import env_config, ids, publish, runtime, state
 from claude_smart.events.stop import (
     _read_transcript_entries,
     _scan_transcript_for_assistant_text,
@@ -119,6 +119,7 @@ def _maybe_synthesize_assistant_anchor(
             "content": assistant_text,
             "user_id": project_id,
             "synthesised_by": "session_end_anchor",
+            "host": runtime.attribution_host(),
         },
     )
     _LOGGER.info(

package/plugin/src/claude_smart/events/stop.py

@@ -408,6 +408,7 @@ def handle(payload: dict[str, Any]) -> tuple[publish.PublishStatus, int] | None:
                     "role": "User",
                     "content": decision_text,
                     "user_id": project_id,
+                    "host": runtime.attribution_host(),
                 },
             )
     elif prompt and not _has_unpublished_user_turn(session_id):
@@ -418,6 +419,7 @@ def handle(payload: dict[str, Any]) -> tuple[publish.PublishStatus, int] | None:
                 "role": "User",
                 "content": prompt,
                 "user_id": project_id,
+                "host": runtime.attribution_host(),
             },
         )
 
@@ -426,6 +428,7 @@ def handle(payload: dict[str, Any]) -> tuple[publish.PublishStatus, int] | None:
         "role": "Assistant",
         "content": assistant_text,
         "user_id": project_id,
+        "host": runtime.attribution_host(),
     }
     if cited_items:
         record["cited_items"] = cited_items

package/plugin/src/claude_smart/events/user_prompt.py

@@ -28,7 +28,7 @@ import logging
 import time
 from typing import Any
 
-from claude_smart import context_inject, ids, state
+from claude_smart import context_inject, ids, runtime, state
 
 _LOGGER = logging.getLogger(__name__)
 _TOP_K = 3
@@ -58,6 +58,7 @@ def handle(payload: dict[str, Any]) -> None:
             "role": "User",
             "content": prompt,
             "user_id": project_id,
+            "host": runtime.attribution_host(),
         },
     )
 

package/plugin/src/claude_smart/internal_call.py

@@ -20,7 +20,8 @@ Two distinct sources of unwanted hook fires:
 
 Detection signals, OR'd:
   - ``CLAUDE_CODE_ENTRYPOINT`` is anything other than an interactive entrypoint
-    (``"cli"`` or Claude Desktop's ``"claude-desktop"``). Headless
+    (``"cli"``, Claude Desktop's ``"claude-desktop"``, or Claude Code IDE
+    entrypoints such as ``"claude-vscode"``/``"claude-jetbrains"``). Headless
     ``claude -p`` sets ``sdk-cli`` (and the SDKs may set other values). This
     catches case (2) for any third-party tool, not just claude-mem.
   - Env var ``CLAUDE_SMART_INTERNAL=1``, set by reflexio's provider
@@ -46,7 +47,9 @@ from typing import Any
 from claude_smart import runtime
 
 _ENTRYPOINT_VAR = "CLAUDE_CODE_ENTRYPOINT"
-_INTERACTIVE_ENTRYPOINTS = frozenset({"cli", "claude-desktop"})
+_INTERACTIVE_ENTRYPOINTS = frozenset(
+    {"cli", "claude-desktop", "claude-vscode", "claude-jetbrains"}
+)
 _CODEX_TITLE_PROMPT_PREFIX = (
     "You are a helpful assistant. You will be presented with a user prompt, "
     "and your job is to provide a short title for a task"

package/plugin/src/claude_smart/optimizer_assistant.py

@@ -4,6 +4,13 @@ Reflexio's ``LocalScriptAssistant`` sends one JSON payload on stdin and expects
 one JSON object on stdout. This module bridges that protocol to a guarded
 local CLI subprocess so candidate playbooks can be evaluated against the active
 host without re-entering claude-smart/reflexio hooks.
+
+Host CLI resolution: when ``CLAUDE_SMART_CLI_PATH`` is set in the environment
+(``backend-service.sh`` writes it for ``opencode`` and ``codex`` hosts so
+generation routes through the host-specific compatibility bridge instead of
+the real Claude CLI), this script honours that override. Falling back to
+``shutil.which("claude")`` preserves the legacy Claude Code host behaviour
+where no override is configured.
 """
 
 from __future__ import annotations
@@ -22,6 +29,20 @@ from claude_smart import internal_call, runtime
 _CLI_TIMEOUT_SECONDS = 300
 _READ_ONLY_TOOLS = "Read,Grep,Glob,LS"
 _MUTATING_TOOLS = "Bash,Edit,Write,MultiEdit,NotebookEdit"
+# Mirrors ``reflexio.server.llm.providers.claude_code_provider._ENV_CLI_PATH``
+# so backend-service.sh can route both the reflexio Claude CLI provider and
+# this assistant script through the same host-specific bridge.
+_ENV_CLI_PATH = "CLAUDE_SMART_CLI_PATH"
+_CLAUDE_SMART_COMPAT_BRIDGE_NAMES = frozenset(
+    {
+        "codex-claude-compat",
+        "codex-claude-compat.cmd",
+        "codex-claude-compat.js",
+        "opencode-claude-compat",
+        "opencode-claude-compat.cmd",
+        "opencode-claude-compat.js",
+    }
+)
 
 
 class OptimizerAssistantError(Exception):
@@ -142,26 +163,51 @@ def _run_local_cli(*, prompt: str, system_prompt: str) -> str:
     return _run_claude(prompt=prompt, system_prompt=system_prompt)
 
 
+def _resolve_claude_cli_path() -> str:
+    """Return the host CLI to invoke for evaluation rollouts.
+
+    When ``CLAUDE_SMART_CLI_PATH`` is set, prefer it so backend-service.sh can
+    route the assistant through the same bridge it uses for the reflexio
+    ``claude-code`` provider (e.g. ``opencode-claude-compat`` for the OpenCode
+    host). Falls back to ``shutil.which("claude")`` so Claude Code hosts — and
+    any environment that never set the override — continue to use the real
+    ``claude`` CLI.
+    """
+    override = os.environ.get(_ENV_CLI_PATH)
+    if override:
+        return override
+    return shutil.which("claude") or "claude"
+
+
+def _is_claude_smart_compat_bridge(cli_path: str) -> bool:
+    return Path(cli_path).name.lower() in _CLAUDE_SMART_COMPAT_BRIDGE_NAMES
+
+
 def _run_claude(*, prompt: str, system_prompt: str) -> str:
-    cli_path = shutil.which("claude") or "claude"
-    # This is an evaluation rollout, not a real user session: allow local
-    # inspection, but prevent filesystem, shell, MCP, and session mutations.
+    cli_path = _resolve_claude_cli_path()
     cmd = [
         cli_path,
         "-p",
         "--output-format",
         "json",
-        "--permission-mode",
-        "plan",
-        "--tools",
-        _READ_ONLY_TOOLS,
-        "--disallowedTools",
-        _MUTATING_TOOLS,
-        "--no-session-persistence",
-        "--mcp-config",
-        '{"mcpServers": {}}',
-        "--strict-mcp-config",
     ]
+    if not _is_claude_smart_compat_bridge(cli_path):
+        # This is an evaluation rollout, not a real user session: allow local
+        # inspection, but prevent filesystem, shell, MCP, and session mutations.
+        cmd.extend(
+            [
+                "--permission-mode",
+                "plan",
+                "--tools",
+                _READ_ONLY_TOOLS,
+                "--disallowedTools",
+                _MUTATING_TOOLS,
+                "--no-session-persistence",
+                "--mcp-config",
+                '{"mcpServers": {}}',
+                "--strict-mcp-config",
+            ]
+        )
     if system_prompt:
         cmd.extend(["--append-system-prompt", system_prompt])