nexo-brain 7.9.27 → 7.9.30

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.27",
+  "version": "7.9.30",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,13 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.9.27` is the current packaged-runtime line. Patch release over `7.9.26`: server startup no longer hangs the MCP `initialize` handshake when legacy followups/reminders still need owner backfill — the synchronous startup migration now runs `--rules-only` and skips the multi-minute `LocalZeroShotClassifier` load, keeping handshake under a few seconds.
+Version `7.9.30` is the current packaged-runtime line. Patch release over `7.9.29`: hotfix for a missing ``import sys`` in ``src/agent_runner.py`` that ruff F821 caught in CI and blocked the 7.9.29 publish workflow before any npm artifact shipped. ``nexo-brain@7.9.30`` is the first npm release that carries the 7.9.29 override-path hardening.
+
+Previously in `7.9.29`: hardening pass on the optional LLM endpoint and auth provider override path. The bearer is now passed to the Anthropic SDK via `auth_token` so it lands in the standard `Authorization: Bearer` header (7.9.28 sent it as `X-Api-Key` and any compatible proxy rejected every request with 401). The Brain config directory is resolved on each call instead of cached at import, so LaunchAgent crons that export `NEXO_HOME` via a wrapper now reach the right `~/.nexo/config/`. The `Idempotency-Key` header accepts a caller-provided value so application-level retries reuse the same dedup key. Override mode is strict about its bearer source: if `auth_provider.json` is missing or the helper fails, the call raises `ClassifierUnavailableError` instead of falling back to the operator's real `ANTHROPIC_API_KEY`, which would otherwise leak to the custom proxy as a second header. A new end-to-end test suite drives the real SDK against a local `http.server` and asserts on captured wire headers and body, complementing the SDK-mock unit tests.
+
+Previously in `7.9.28`: optional override files at `~/.nexo/config/llm_endpoint.json` and `~/.nexo/config/auth_provider.json` let third-party orchestrators redirect Brain's Anthropic SDK calls and delegate bearer token resolution to a local command (analogous to git's `credential.helper`). The same redirection is propagated to every CLI child Brain spawns (deep-sleep, evolution, followup-runner, morning-agent, email-monitor, `nexo chat`) by injecting `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` into the spawned environment, so headless crons reach the proxy too. An `Idempotency-Key` (UUID4 hex) is attached per request for proxy-side dedup of transparent retries within 24h. Brain libre standalone (no override files) hits `api.anthropic.com` directly with `ANTHROPIC_API_KEY` exactly as before.
+
+Previously in `7.9.27`: server startup no longer hangs the MCP `initialize` handshake when legacy followups/reminders still need owner backfill — the synchronous startup migration now runs `--rules-only` and skips the multi-minute `LocalZeroShotClassifier` load, keeping handshake under a few seconds.
 
 Previously in `7.9.26`: headless automation prompts now receive the operator-language contract centrally, so reports, diaries, syntheses, followups, escalations, and Deep Sleep-generated memory text follow calibration even when the underlying template is English.
 
@@ -1077,6 +1083,19 @@ Use a personal plugin only when you need a new MCP tool in the runtime surface.
 - **Auto-update is resilient.** NEXO checks for updates on startup. If an update fails, it continues with the current version and notifies you. Local migrations (database schema, configuration) always run. Network updates (git pull) can be disabled by setting `auto_update: false` in `NEXO_HOME/config/schedule.json`.
 - **Secret redaction.** API keys and tokens are stripped before they ever reach memory storage.
 
+## Custom LLM endpoint (advanced)
+
+NEXO Brain reads two optional override files at `~/.nexo/config/`:
+
+- `llm_endpoint.json` — set a custom Anthropic-compatible base URL.
+- `auth_provider.json` — delegate bearer token resolution to a local command (analogous to git's `credential.helper`).
+
+This lets third-party orchestrators — for example an Anthropic-compatible proxy that adds rate limiting, cost accounting, multi-provider failover, or per-team auth — route Brain's LLM calls without modifying its source.
+
+**If neither file exists, Brain operates exactly as before:** direct call to `https://api.anthropic.com` using `ANTHROPIC_API_KEY` from environment or filesystem. The override path is opt-in.
+
+When override mode is active, Brain attaches an opaque `Idempotency-Key` to every request so the proxy can dedup transparent retries (24h window) without double-billing. The same redirection applies to every CLI child Brain spawns (deep-sleep, evolution, followup-runner, morning-agent, email-monitor, `nexo chat`): `agent_runner.py` injects `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` into the spawned environment when override mode is on, so headless crons hit the proxy too — LaunchAgent crons do not inherit env from a UI process. See `docs/api/override-files.md` for the full schema, fallback rules, and an end-to-end example.
+
 ## The Psychology Behind NEXO Brain
 
 NEXO Brain isn't just engineering — it's applied cognitive psychology:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.27",
+  "version": "7.9.30",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/agent_runner.py

@@ -8,6 +8,7 @@ import paths
 import shlex
 import shutil
 import subprocess
+import sys
 import tempfile
 import time
 from functools import lru_cache
@@ -374,6 +375,68 @@ def _codex_config_path() -> Path:
     return Path.home() / ".codex" / "config.toml"
 
 
+def _apply_llm_endpoint_override(env: dict) -> dict:
+    """Redirect the child Anthropic-compatible CLI to the configured proxy
+    when Brain is in override mode (``~/.nexo/config/llm_endpoint.json``
+    present). Standalone runs leave ``env`` untouched, so Brain libre keeps
+    hitting ``api.anthropic.com`` directly with whatever ``ANTHROPIC_API_KEY``
+    the operator already had configured.
+
+    Security guarantee: if override mode is active but ``auth_provider.json``
+    is missing, malformed, or the helper command fails to produce a
+    bearer, the helper does NOT inject ``ANTHROPIC_BASE_URL`` either.
+    Otherwise the spawned CLI would inherit the operator's real
+    ``ANTHROPIC_API_KEY`` (a ``sk-ant-...`` key) from the parent process
+    and send it as the bearer to the custom proxy, leaking the real
+    Anthropic credential to a third party. Fail-closed: the override is
+    skipped completely, and the CLI either runs against
+    ``api.anthropic.com`` with the operator's real key (if also present
+    as standalone fallback) or fails locally.
+
+    The contract is symmetric with what ``call_model_raw.py`` does for SDK
+    direct calls: same files, same precedence, same alias system. The CLI
+    child reads ``ANTHROPIC_BASE_URL`` (Anthropic SDK convention) and
+    ``ANTHROPIC_API_KEY`` from the spawned environment.
+
+    No-op (and silent) when ``call_model_raw`` is unavailable for any
+    reason; the headless surface should never block on this helper.
+    """
+    try:
+        from call_model_raw import (
+            is_override_mode,
+            resolve_api_base_url,
+            resolve_auth_token,
+        )
+    except Exception:
+        return env
+    try:
+        if not is_override_mode():
+            return env
+        bearer = resolve_auth_token()
+        if not bearer:
+            # auth_provider.json missing or failed in override mode.
+            # Do NOT redirect to the proxy with a stale operator key — see
+            # the docstring above. Skip the override entirely and let the
+            # spawn either run standalone or fail explicitly elsewhere.
+            sys.stderr.write(
+                "[brain] llm_endpoint override active but auth_provider "
+                "produced no bearer; skipping CLI env injection to avoid "
+                "leaking a real ANTHROPIC_API_KEY to the proxy.\n"
+            )
+            return env
+        base_url = resolve_api_base_url()
+        if base_url:
+            env["ANTHROPIC_BASE_URL"] = base_url
+        env["ANTHROPIC_API_KEY"] = bearer
+    except Exception:
+        # Override is best-effort: a misconfigured override file must not
+        # crash an automation run that would otherwise have worked in
+        # standalone. The SDK direct path already surfaces config errors
+        # via ClassifierUnavailableError; the CLI path stays defensive.
+        pass
+    return env
+
+
 def _headless_env(env: dict | None = None) -> dict:
     merged = os.environ.copy()
     if env:
@@ -382,7 +445,7 @@ def _headless_env(env: dict | None = None) -> dict:
     merged["NEXO_AUTOMATION"] = "1"
     merged.pop("CLAUDECODE", None)
     merged.pop("CLAUDE_CODE", None)
-    return merged
+    return _apply_llm_endpoint_override(merged)
 
 
 def _load_client_bootstrap_prompt(client: str) -> str:
@@ -603,6 +666,7 @@ def run_automation_interactive(
     launch_env = os.environ.copy()
     if env:
         launch_env.update(env)
+    launch_env = _apply_llm_endpoint_override(launch_env)
     cwd_path = Path(_interactive_target_cwd(target))
 
     # Best-effort resonance lookup — interactive sessions do not swap the
@@ -1043,7 +1107,21 @@ def run_automation_prompt(
 
         bare_api_key = ""
         if resolved_bare:
-            bare_api_key = _resolve_anthropic_api_key()
+            # In override mode the bearer was already injected into
+            # run_env by _apply_llm_endpoint_override (proxy token, not
+            # the operator's raw Anthropic key). Reuse it instead of
+            # asking the keychain helper for a real Anthropic key — the
+            # proxy expects its own bearer and would reject the real one.
+            override_bearer = run_env.get("ANTHROPIC_API_KEY", "").strip() if run_env else ""
+            try:
+                from call_model_raw import is_override_mode as _is_override_mode
+                _override_active = _is_override_mode()
+            except Exception:
+                _override_active = False
+            if _override_active and override_bearer:
+                bare_api_key = override_bearer
+            else:
+                bare_api_key = _resolve_anthropic_api_key()
             if not bare_api_key:
                 # Silent fallback: we would rather take the slower path
                 # than force the caller to fail-closed on an env quirk.

package/src/call_model_raw.py

@@ -41,7 +41,11 @@ gap.
 from __future__ import annotations
 
 import json
+import logging
 import os
+import subprocess
+import sys
+import uuid
 from pathlib import Path
 
 
@@ -65,6 +69,246 @@ _OPENAI_KEY_PATHS = (
     Path.home() / ".codex" / "auth.json",
 )
 
+# ---------------------------------------------------------------------------
+# Optional override files (~/.nexo/config/)
+# ---------------------------------------------------------------------------
+# Two forward-compatible JSON files let third-party orchestrators (such as an
+# Anthropic-compatible proxy) redirect the LLM endpoint and delegate token
+# resolution to a local helper. Pattern is analogous to git's `core.editor`
+# and `credential.helper`.
+#
+#   ~/.nexo/config/llm_endpoint.json
+#       {
+#         "version": 1,
+#         "anthropic_base_url": "https://my-proxy.example.com/api/proxy"
+#       }
+#
+#   ~/.nexo/config/auth_provider.json
+#       {
+#         "version": 1,
+#         "command": "/path/to/auth-helper",
+#         "args": ["--for", "anthropic"],
+#         "timeout_sec": 5
+#       }
+#
+# If neither file exists the caller falls back to standalone behaviour:
+# direct call to api.anthropic.com using ANTHROPIC_API_KEY from environment
+# or filesystem. NEXO Brain's open-source distribution is unaffected.
+
+def _resolve_brain_config_dir() -> Path:
+    """Honour ``NEXO_HOME`` so tests, devcontainers and non-default
+    installs (Maria iMac, Codex sandboxes, etc.) hit the right
+    ``config/`` directory. Resolved at every call so a process that
+    sets ``NEXO_HOME`` after this module is imported still picks up
+    the right path on the next request — relevant for LaunchAgent
+    crons that rely on env exported by their wrapper script. Falls
+    back to ``~/.nexo/config/``."""
+    nexo_home = os.environ.get("NEXO_HOME", "").strip()
+    if nexo_home:
+        return Path(nexo_home).expanduser() / "config"
+    return Path.home() / ".nexo" / "config"
+
+
+# Tests monkeypatch this attribute to redirect overrides to a tmp dir.
+# Production code MUST NOT read this directly — use ``_brain_config_dir()``.
+# Default ``None`` lets ``_brain_config_dir()`` fall through to the live
+# ``_resolve_brain_config_dir()`` so call-time NEXO_HOME changes are honoured.
+_BRAIN_CONFIG_DIR: Path | None = None
+
+
+def _brain_config_dir() -> Path:
+    """Production-side resolver. Honours the test monkeypatch hook above
+    when set, otherwise resolves from the live environment on every call."""
+    if _BRAIN_CONFIG_DIR is not None:
+        return _BRAIN_CONFIG_DIR
+    return _resolve_brain_config_dir()
+
+
+_SUPPORTED_OVERRIDE_VERSION = 1
+_LLM_ENDPOINT_FILENAME = "llm_endpoint.json"
+_AUTH_PROVIDER_FILENAME = "auth_provider.json"
+_DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com"
+_DEFAULT_AUTH_PROVIDER_TIMEOUT = 5
+
+# Internal map: (concrete_model, effort) -> wire alias accepted by an
+# Anthropic-compatible proxy. ONLY consulted when override mode is active.
+# Standalone mode never reads this map and keeps using the concrete model.
+#
+# Add entries here in lockstep with new tiers added to resonance_tiers.json.
+# Failing fast on an unmapped (model, effort) is preferable to letting the
+# proxy reject the request with a 400 — the operator gets a clear local
+# error instead of a remote one.
+_CONCRETE_TO_ALIAS: dict[tuple[str, str], str] = {
+    ("claude-opus-4-7[1m]", "max"):    "nexo-max",
+    ("claude-opus-4-7[1m]", "xhigh"):  "nexo-high",
+    ("claude-opus-4-7[1m]", "high"):   "nexo-medium",
+    ("claude-opus-4-7[1m]", "medium"): "nexo-low",
+    ("claude-haiku-4-5-20251001", ""): "nexo-mini",
+}
+
+
+def _read_versioned_config(filename: str) -> dict | None:
+    """Load a versioned override file from the Brain config directory.
+
+    Calls ``_brain_config_dir()`` on every invocation so a process that
+    sets ``NEXO_HOME`` after importing the module picks up the new path
+    immediately. Tests can monkeypatch ``_BRAIN_CONFIG_DIR`` to redirect
+    to a tmp dir.
+
+    Returns the dict iff the file exists, parses as JSON and declares
+    ``version: 1``. Any other case (missing, malformed, unsupported version)
+    returns None and emits a stderr warning so operators can see why the
+    override was ignored. Never raises.
+    """
+    path = _brain_config_dir() / filename
+    try:
+        if not path.is_file():
+            return None
+        cfg = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        sys.stderr.write(
+            f"[brain] failed to read override {filename}: {exc}; ignoring\n"
+        )
+        return None
+    if not isinstance(cfg, dict):
+        sys.stderr.write(
+            f"[brain] override {filename} is not a JSON object; ignoring\n"
+        )
+        return None
+    version = cfg.get("version", 0)
+    if version != _SUPPORTED_OVERRIDE_VERSION:
+        sys.stderr.write(
+            f"[brain] override {filename} version {version!r} not supported "
+            f"(expected {_SUPPORTED_OVERRIDE_VERSION}); ignoring\n"
+        )
+        return None
+    return cfg
+
+
+def resolve_api_base_url() -> str:
+    """Return the Anthropic API base URL.
+
+    Resolution order:
+        1) ``~/.nexo/config/llm_endpoint.json`` with ``anthropic_base_url``.
+        2) ``NEXO_LLM_ENDPOINT`` env var.
+        3) Default ``https://api.anthropic.com`` (standalone).
+    """
+    cfg = _read_versioned_config(_LLM_ENDPOINT_FILENAME)
+    if cfg:
+        url = str(cfg.get("anthropic_base_url", "") or "").strip()
+        if url:
+            return url
+    env_url = os.environ.get("NEXO_LLM_ENDPOINT", "").strip()
+    if env_url:
+        return env_url
+    return _DEFAULT_ANTHROPIC_BASE_URL
+
+
+def _override_force_disabled() -> bool:
+    # Internal escape hatch used by the test suite and by maintainers when
+    # they need to validate a regression against the upstream Anthropic API
+    # without renaming the override files on disk. Intentionally undocumented
+    # outside the source so that the canonical override-mode contract stays
+    # purely file-driven for everybody else.
+    raw = os.environ.get("NEXO_RAW_ANTHROPIC", "").strip().lower()
+    return raw in ("1", "true", "yes", "on")
+
+
+def is_override_mode() -> bool:
+    """True iff a valid ``llm_endpoint.json`` is present and selects a custom
+    base URL. The override gate is the file (not an env var) so that
+    env-only configurations remain transparent to standalone callers."""
+    if _override_force_disabled():
+        return False
+    cfg = _read_versioned_config(_LLM_ENDPOINT_FILENAME)
+    if not cfg:
+        return False
+    url = str(cfg.get("anthropic_base_url", "") or "").strip()
+    return bool(url)
+
+
+def _resolve_auth_provider_token() -> str:
+    """Resolve the bearer token strictly from ``auth_provider.json``.
+
+    Returns the trimmed stdout of the configured command on success.
+    Returns ``""`` if the file is absent, malformed, or the command
+    times out / fails / exits non-zero / produces empty stdout. Never
+    falls back to environment or filesystem keys; that decision is
+    made by the caller based on whether override mode is active.
+    """
+    cfg = _read_versioned_config(_AUTH_PROVIDER_FILENAME)
+    if not cfg:
+        return ""
+    cmd = str(cfg.get("command", "") or "").strip()
+    if not cmd:
+        return ""
+    args_raw = cfg.get("args", []) or []
+    args = [str(a) for a in args_raw if isinstance(a, (str, int, float))]
+    try:
+        timeout_sec = int(cfg.get("timeout_sec", _DEFAULT_AUTH_PROVIDER_TIMEOUT))
+    except (TypeError, ValueError):
+        timeout_sec = _DEFAULT_AUTH_PROVIDER_TIMEOUT
+    try:
+        result = subprocess.run(
+            [cmd, *args],
+            capture_output=True,
+            text=True,
+            timeout=timeout_sec,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        # Learning #294: subprocess timeouts must be captured explicitly so
+        # the operator sees the helper hung instead of a generic
+        # "auth missing" downstream.
+        sys.stderr.write(
+            f"[brain] auth_provider command timed out after {timeout_sec}s: "
+            f"{exc}\n"
+        )
+        return ""
+    except (FileNotFoundError, PermissionError, OSError) as exc:
+        sys.stderr.write(f"[brain] auth_provider command failed: {exc}\n")
+        return ""
+    if result.returncode != 0:
+        stderr_excerpt = (result.stderr or "").strip()[:200]
+        sys.stderr.write(
+            f"[brain] auth_provider command exit={result.returncode}: "
+            f"{stderr_excerpt}\n"
+        )
+        return ""
+    return (result.stdout or "").strip()
+
+
+def resolve_auth_token() -> str:
+    """Return the bearer token to use against the resolved base URL.
+
+    The resolution depends on whether override mode is active:
+
+    * **Override mode** (``llm_endpoint.json`` valid): the token MUST
+      come from ``auth_provider.json``. Falling back to
+      ``ANTHROPIC_API_KEY`` (a real ``sk-ant-...`` key bound to the
+      operator's Anthropic account) and sending it as the bearer to a
+      third-party proxy would leak that credential. If the helper
+      command fails or is not configured, returns ``""`` so the caller
+      raises ``ClassifierUnavailableError``.
+    * **Standalone mode** (no override file): cascade
+      ``auth_provider.json`` → ``ANTHROPIC_API_KEY`` env →
+      ``~/.claude/anthropic-api-key.txt`` → ``~/.nexo/config/anthropic-api-key.txt``.
+      The legacy fallbacks exist so an operator that scripted bearer
+      resolution via the helper can still rely on the env var when
+      Brain is not redirected anywhere.
+    """
+    if is_override_mode():
+        # Strict: the bearer must come from the configured helper. If
+        # the helper is missing or fails, refuse to authenticate rather
+        # than leak a real Anthropic key to a custom proxy.
+        return _resolve_auth_provider_token()
+
+    # Standalone: helper first (if scripted), env/files otherwise.
+    helper_token = _resolve_auth_provider_token()
+    if helper_token:
+        return helper_token
+    return _resolve_anthropic_key()
+
 
 def _resolve_anthropic_key() -> str:
     env_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
@@ -138,28 +382,91 @@ def _extract_openai_text(response) -> str:
         return ""
 
 
+def _resolve_override_alias(model: str, effort: str) -> str:
+    """In override mode the proxy speaks aliases, not concrete model names.
+    Translate ``(model, effort)`` into the wire alias the proxy validates.
+    Unmapped pairs fail-closed: better to surface a local config error than
+    let the proxy reject the request remotely.
+    """
+    key = (model, effort)
+    alias = _CONCRETE_TO_ALIAS.get(key)
+    if not alias:
+        raise ClassifierUnavailableError(
+            f"override mode: no alias mapped for (model={model!r}, "
+            f"effort={effort!r}); update _CONCRETE_TO_ALIAS in call_model_raw.py"
+        )
+    return alias
+
+
 def _call_anthropic_raw(
     *,
     prompt: str,
     system: str | None,
     model: str,
+    effort: str,
     max_tokens: int,
     temperature: float,
     stop_sequences: list[str],
     timeout: float,
+    idempotency_key: str | None = None,
 ) -> str:
     try:
         import anthropic  # type: ignore
     except ImportError as exc:
         raise ClassifierUnavailableError(f"anthropic SDK missing: {exc}") from exc
 
-    api_key = _resolve_anthropic_key()
-    if not api_key:
-        raise ClassifierUnavailableError("anthropic: no ANTHROPIC_API_KEY found")
+    override = is_override_mode()
+    if override:
+        # Proxy mode. The Anthropic SDK distinguishes:
+        #   api_key=...    -> header "X-Api-Key: <value>"   (Anthropic-style)
+        #   auth_token=... -> header "Authorization: Bearer <value>" (OAuth-style)
+        # NEXO Desktop and any compatible proxy parse the standard
+        # "Authorization: Bearer" header, so we MUST pass the resolved
+        # bearer through ``auth_token`` — passing it as ``api_key`` would
+        # send "X-Api-Key" which the proxy would reject with 401.
+        wire_model = _resolve_override_alias(model, effort)
+        base_url = resolve_api_base_url()
+        bearer = resolve_auth_token()
+        if not bearer:
+            raise ClassifierUnavailableError(
+                "anthropic override: no bearer resolved from auth_provider.json; "
+                "override mode requires a configured auth helper to avoid leaking "
+                "a real ANTHROPIC_API_KEY to a custom proxy"
+            )
+        # The SDK ``__init__`` resolves ``api_key`` from
+        # ``ANTHROPIC_API_KEY`` whenever the kwarg is ``None`` (the
+        # parameter default). It then sends BOTH ``X-Api-Key`` (from the
+        # env-resolved api_key) and ``Authorization: Bearer`` (from
+        # auth_token) on every request. A custom proxy would see and
+        # potentially log the operator's real ``sk-ant-...`` key. Passing
+        # ``api_key=""`` does not fix it either: the SDK's auth_headers
+        # check is ``if api_key is None`` (strict ``is``, not falsy), so
+        # the empty string still produces an ``X-Api-Key:`` header.
+        # Solution: pop the env var around the constructor call so the
+        # SDK records ``api_key=None`` and skips the X-Api-Key header
+        # entirely. Then restore the original env so we don't break
+        # other code paths in the same Python process.
+        _saved_anthropic_env = os.environ.pop("ANTHROPIC_API_KEY", None)
+        try:
+            client = anthropic.Anthropic(
+                auth_token=bearer,
+                base_url=base_url,
+                timeout=timeout,
+            )
+        finally:
+            if _saved_anthropic_env is not None:
+                os.environ["ANTHROPIC_API_KEY"] = _saved_anthropic_env
+    else:
+        # Standalone: behaviour identical to pre-V11. No override, no alias
+        # translation, no extra headers — direct hit to api.anthropic.com.
+        wire_model = model
+        api_key = _resolve_anthropic_key()
+        if not api_key:
+            raise ClassifierUnavailableError("anthropic: no ANTHROPIC_API_KEY found")
+        client = anthropic.Anthropic(api_key=api_key, timeout=timeout)
 
-    client = anthropic.Anthropic(api_key=api_key, timeout=timeout)
     kwargs: dict = {
-        "model": model,
+        "model": wire_model,
         "max_tokens": max_tokens,
         "temperature": temperature,
         "stop_sequences": stop_sequences,
@@ -168,6 +475,21 @@ def _call_anthropic_raw(
     if system:
         kwargs["system"] = system
 
+    if override:
+        # Idempotency-Key: opaque per-request token. The proxy dedups on
+        # (token_id + idempotency_key) for 24h, so network-level retries
+        # do not double-bill the user. The caller is encouraged to pass
+        # an explicit ``idempotency_key`` and reuse it across application-
+        # level retries (e.g. enforcement_classifier retrying after a
+        # ClassifierUnavailableError) so the proxy treats the second
+        # attempt as a duplicate of the first instead of a brand-new
+        # billable request. If the caller omits it we generate a fresh
+        # UUID4, which still covers SDK-level transparent retries since
+        # the SDK reuses the same ``kwargs`` across them.
+        if idempotency_key is None:
+            idempotency_key = uuid.uuid4().hex
+        kwargs["extra_headers"] = {"Idempotency-Key": idempotency_key}
+
     try:
         response = client.messages.create(**kwargs)
     except anthropic.APITimeoutError as exc:
@@ -247,21 +569,32 @@ def call_model_raw(
     stop_sequences: list[str] | None = None,
     timeout: float = 10.0,
     system: str | None = None,
+    idempotency_key: str | None = None,
 ) -> str:
     """Run a single short LLM completion for enforcement-class classification.
 
     Parameters follow the Fase 2 plan doc 1 spec:
 
-        prompt         — the user-role text (English or the model's default).
-        tier           — resonance tier; default "muy_bajo" → Haiku / gpt-5.4-mini.
-        caller         — resonance caller label. Must be registered in
-                         resonance_map.SYSTEM_OWNED_CALLERS. Default
-                         "enforcer_classifier".
-        max_tokens     — hard cap on output tokens. Default 3 (yes/no only).
-        temperature    — sampling temperature. Default 0.0 (deterministic).
-        stop_sequences — early-stop strings. Default ["\\n", ".", " "].
-        timeout        — per-request timeout in seconds. Default 10.0.
-        system         — optional system prompt. Default None (provider default).
+        prompt          — the user-role text (English or the model's default).
+        tier            — resonance tier; default "muy_bajo" → Haiku / gpt-5.4-mini.
+        caller          — resonance caller label. Must be registered in
+                          resonance_map.SYSTEM_OWNED_CALLERS. Default
+                          "enforcer_classifier".
+        max_tokens      — hard cap on output tokens. Default 3 (yes/no only).
+        temperature     — sampling temperature. Default 0.0 (deterministic).
+        stop_sequences  — early-stop strings. Default ["\\n", ".", " "].
+        timeout         — per-request timeout in seconds. Default 10.0.
+        system          — optional system prompt. Default None (provider default).
+        idempotency_key — optional opaque token attached as
+                          ``Idempotency-Key`` header in override mode. Reuse
+                          the same value across application-level retries
+                          (e.g. when the caller catches
+                          ``ClassifierUnavailableError`` and tries again)
+                          so the proxy treats the retry as a duplicate of
+                          the first request and does not double-bill.
+                          Ignored in standalone mode. If omitted in
+                          override mode, a fresh UUID4 is generated which
+                          still covers transparent SDK-level retries.
 
     Returns the raw text response, trimmed. The CALLER is responsible for
     parsing yes/no — the "triple reinforcement" (prompt strict, max_tokens
@@ -301,7 +634,7 @@ def call_model_raw(
         raise ClassifierUnavailableError("automation_backend=none")
 
     try:
-        model, _effort = resolve_model_and_effort(
+        model, effort = resolve_model_and_effort(
             caller=caller,
             backend=backend,
             explicit_tier=tier,
@@ -320,10 +653,12 @@ def call_model_raw(
             prompt=prompt,
             system=system,
             model=model,
+            effort=effort,
             max_tokens=max_tokens,
             temperature=temperature,
             stop_sequences=stop_sequences,
             timeout=timeout,
+            idempotency_key=idempotency_key,
         )
     if backend == CLIENT_CODEX:
         return _call_openai_raw(
@@ -339,4 +674,10 @@ def call_model_raw(
     raise ClassifierUnavailableError(f"unsupported backend: {backend}")
 
 
-__all__ = ["call_model_raw", "ClassifierUnavailableError"]
+__all__ = [
+    "call_model_raw",
+    "ClassifierUnavailableError",
+    "is_override_mode",
+    "resolve_api_base_url",
+    "resolve_auth_token",
+]