coderouter-cli 2.14.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

coderouter/routing/fallback_trace.py

@@ -0,0 +1,501 @@
+"""v2.15.0: request-scoped fallback trace — *why* did the chain move?
+
+Before v2.15.0 the engine could tell an operator (via ``try-provider`` /
+``provider-failed`` log lines) that a fallback happened, but nothing tied
+the two together into a single "we left A for B because of R" record, and
+nothing at all reached the *client*. This module is that missing record.
+
+Vocabulary
+==========
+
+``reason`` already existed in the codebase as a keyword argument on
+:func:`coderouter.routing.capability.log_capability_degraded`
+(``provider-does-not-support`` / ``translation-lossy`` /
+``unsupported-backend``) and on the drift verdict. Those are **degrade**
+reasons: the request stays on the same provider, something is stripped.
+v2.15.0 keeps those strings verbatim (they are re-exported here as
+``REASON_PROVIDER_DOES_NOT_SUPPORT`` etc. so there is one place to read
+the whole vocabulary) and adds the **fallback** reasons — the ones that
+actually move the request to a different provider.
+
+Only fallback reasons ever produce a :class:`FallbackHop`. Degrade
+reasons never do, by construction: nothing moved.
+
+Fallback reasons split in two families:
+
+*Pre-attempt* (the provider was filtered out of the chain during
+:meth:`FallbackEngine._resolve_chain`, so it was never called):
+``paid-gate`` / ``budget-exceeded`` / ``memory-pressure`` /
+``backend-unhealthy`` / ``self-healing-excluded`` / ``unknown-provider``.
+
+*Attempt-failure* (the provider was called and did not deliver):
+``timeout`` / ``rate-limit`` / ``auth`` / ``upstream-5xx`` /
+``upstream-4xx`` / ``connection`` / ``upstream-error`` /
+``empty-response`` / ``empty-stream``.
+
+Request scoping
+===============
+
+The trace lives in a :class:`~contextvars.ContextVar`, the same isolation
+mechanism the drift verdict (``_drift_verdict_ctx``) and the M11 prepared
+dispatch (``_prepared_dispatch_ctx``) already use in
+:mod:`coderouter.routing.fallback`. Starlette runs each request handler in
+its own asyncio task, so one request never sees another's hops, and the
+value cannot go stale across requests (the ContextVar defaults to
+``None``).
+
+Two entry points, deliberately different:
+
+* :func:`begin_fallback_trace` — installs a *fresh* trace. Called by the
+  engine's dispatch entry points. ``keep_existing=True`` preserves a trace
+  the ingress's ``apply_context_budget`` pre-pass already started for the
+  same request (chain-resolve skips are recorded there, before dispatch).
+* :func:`current_fallback_trace` — read-only lookup. The ingress uses it
+  after dispatch to build the ``X-CodeRouter-Fallback-*`` headers and the
+  ``coderouter_fallback`` SSE metadata event.
+
+Ordering / shape contract (what a client can rely on)
+=====================================================
+
+For a request that fell back twice::
+
+    X-CodeRouter-Fallback-From:   local
+    X-CodeRouter-Fallback-To:     openrouter
+    X-CodeRouter-Fallback-Reason: timeout,upstream-5xx
+    X-CodeRouter-Fallback-Chain:  local>ollama>openrouter
+
+``Chain`` is the providers in try-order; ``Reason`` is the reason for each
+*departure*, in the same order. ``len(Chain) == len(Reason) + 1`` when the
+chain finally produced an answer, and ``len(Chain) == len(Reason)`` when
+the whole chain was exhausted (there was no provider to hand off to, so
+``X-CodeRouter-Fallback-To`` is omitted). ``From`` is the first provider
+that was abandoned, ``To`` the one that ultimately served.
+
+None of these headers are emitted when no fallback happened — the
+zero-fallback path is byte-for-byte unchanged from v2.14.0.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Final
+
+if TYPE_CHECKING:
+    from coderouter.adapters.base import AdapterError
+
+# ---------------------------------------------------------------------------
+# Canonical reason vocabulary
+# ---------------------------------------------------------------------------
+
+# -- pre-attempt (chain-resolve filters; provider was never called) ---------
+REASON_PAID_GATE: Final = "paid-gate"
+REASON_BUDGET_EXCEEDED: Final = "budget-exceeded"
+REASON_MEMORY_PRESSURE: Final = "memory-pressure"
+REASON_BACKEND_UNHEALTHY: Final = "backend-unhealthy"
+REASON_SELF_HEALING_EXCLUDED: Final = "self-healing-excluded"
+REASON_UNKNOWN_PROVIDER: Final = "unknown-provider"
+
+# -- attempt failures (provider was called) --------------------------------
+REASON_TIMEOUT: Final = "timeout"
+REASON_RATE_LIMIT: Final = "rate-limit"
+REASON_AUTH: Final = "auth"
+REASON_UPSTREAM_5XX: Final = "upstream-5xx"
+REASON_UPSTREAM_4XX: Final = "upstream-4xx"
+REASON_CONNECTION: Final = "connection"
+REASON_UPSTREAM_ERROR: Final = "upstream-error"
+REASON_EMPTY_RESPONSE: Final = "empty-response"
+REASON_EMPTY_STREAM: Final = "empty-stream"
+# v2.15.0: the upstream SSE stream ended without its protocol terminator —
+# distinct from ``empty-stream`` (nothing at all arrived) and from
+# ``connection`` (the transport itself broke). Produced only when the profile
+# sets ``stream_truncation_action: error``.
+REASON_STREAM_TRUNCATED: Final = "stream-truncated"
+
+# -- degrade reasons (pre-existing strings; never produce a hop) -----------
+# Kept here so the whole ``reason`` vocabulary is readable in one place.
+REASON_PROVIDER_DOES_NOT_SUPPORT: Final = "provider-does-not-support"
+REASON_TRANSLATION_LOSSY: Final = "translation-lossy"
+REASON_UNSUPPORTED_BACKEND: Final = "unsupported-backend"
+
+PRE_ATTEMPT_REASONS: Final[frozenset[str]] = frozenset(
+    {
+        REASON_PAID_GATE,
+        REASON_BUDGET_EXCEEDED,
+        REASON_MEMORY_PRESSURE,
+        REASON_BACKEND_UNHEALTHY,
+        REASON_SELF_HEALING_EXCLUDED,
+        REASON_UNKNOWN_PROVIDER,
+    }
+)
+
+ATTEMPT_FAILURE_REASONS: Final[frozenset[str]] = frozenset(
+    {
+        REASON_TIMEOUT,
+        REASON_RATE_LIMIT,
+        REASON_AUTH,
+        REASON_UPSTREAM_5XX,
+        REASON_UPSTREAM_4XX,
+        REASON_CONNECTION,
+        REASON_UPSTREAM_ERROR,
+        REASON_EMPTY_RESPONSE,
+        REASON_EMPTY_STREAM,
+        REASON_STREAM_TRUNCATED,
+    }
+)
+
+FALLBACK_REASONS: Final[frozenset[str]] = PRE_ATTEMPT_REASONS | ATTEMPT_FAILURE_REASONS
+
+DEGRADE_REASONS: Final[frozenset[str]] = frozenset(
+    {
+        REASON_PROVIDER_DOES_NOT_SUPPORT,
+        REASON_TRANSLATION_LOSSY,
+        REASON_UNSUPPORTED_BACKEND,
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Header names — follow the v2.0-F / v2.0-G convention already in
+# ``ingress/anthropic_routes.py`` (``X-CodeRouter-Context-Budget`` /
+# ``X-CodeRouter-Drift``): ``X-CodeRouter-`` prefix, Train-Case suffix,
+# short scalar value.
+# ---------------------------------------------------------------------------
+
+HEADER_FALLBACK_FROM: Final = "X-CodeRouter-Fallback-From"
+HEADER_FALLBACK_TO: Final = "X-CodeRouter-Fallback-To"
+HEADER_FALLBACK_REASON: Final = "X-CodeRouter-Fallback-Reason"
+HEADER_FALLBACK_CHAIN: Final = "X-CodeRouter-Fallback-Chain"
+
+# SSE metadata event name for the streaming path. Mirrors the existing
+# ``coderouter_partial`` extension event (v2.0-H) — a client-optional
+# trailing frame, emitted after ``message_stop``, that spec-compliant
+# Anthropic SDKs ignore.
+SSE_FALLBACK_EVENT: Final = "coderouter_fallback"
+
+# Provider names and reasons are config identifiers, but a header value has
+# to stay in the printable-ASCII token range no matter what a user typed in
+# their YAML. Anything outside the allowlist collapses to ``_``.
+_SAFE_CHARS: Final[frozenset[str]] = frozenset(
+    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-"
+)
+
+
+def _sanitize(value: str) -> str:
+    """Reduce ``value`` to a header-safe token.
+
+    Keeps ``[A-Za-z0-9._-]`` and replaces everything else with ``_`` so a
+    provider named ``my provider`` or one carrying non-ASCII can never
+    produce a malformed (or header-injecting) response header.
+    """
+    return "".join(ch if ch in _SAFE_CHARS else "_" for ch in value) or "_"
+
+
+def describe_adapter_error(exc: AdapterError) -> str:
+    """Build the short, non-leaking ``detail`` string for a failed attempt.
+
+    Deliberately structural: the upstream's error *text* stays in the
+    existing ``provider-failed`` warn line (which passes through the
+    secret-redaction filter) and never reaches a response header or an SSE
+    event. Here we only report the HTTP status, or the transport shape
+    when there was no response at all.
+    """
+    if exc.status_code is not None:
+        return f"status={exc.status_code}"
+    reason = classify_adapter_error(exc)
+    if reason == REASON_STREAM_TRUNCATED:
+        # Not a transport fault — the HTTP body ended cleanly; it was the
+        # LLM protocol inside it that never closed.
+        return "no-terminator"
+    return f"transport={reason}"
+
+
+def classify_adapter_error(exc: AdapterError) -> str:
+    """Map an :class:`AdapterError` onto a canonical fallback reason.
+
+    Status codes are the primary signal. Adapters raise with
+    ``status_code=None`` for pre-response failures (httpx timeout,
+    transport error, JSON decode), so those are disambiguated by the
+    message text the adapters already write — ``timeout ...`` and
+    ``transport error: ...`` are stable prefixes in both
+    ``adapters/openai_compat.py`` and ``adapters/anthropic_native.py``.
+
+    v2.15.0: ``StreamTruncatedError`` is checked first and by type, not by
+    message text. It carries ``status_code=None`` and would otherwise land in
+    the generic ``upstream-error`` bucket, hiding the one failure mode this
+    reason exists to name. The import is function-local because
+    ``adapters.base`` is a TYPE_CHECKING-only import at module scope here
+    (the runtime import order would otherwise cycle through the registry).
+    """
+    from coderouter.adapters.base import StreamTruncatedError
+
+    if isinstance(exc, StreamTruncatedError):
+        return REASON_STREAM_TRUNCATED
+    status = exc.status_code
+    if status is None:
+        message = str(exc).lower()
+        if "timeout" in message or "timed out" in message:
+            return REASON_TIMEOUT
+        if "transport error" in message or "connect" in message:
+            return REASON_CONNECTION
+        return REASON_UPSTREAM_ERROR
+    if status == 408:
+        return REASON_TIMEOUT
+    if status == 429:
+        return REASON_RATE_LIMIT
+    if status in {401, 403}:
+        return REASON_AUTH
+    if status >= 500:
+        return REASON_UPSTREAM_5XX
+    if status >= 400:
+        return REASON_UPSTREAM_4XX
+    return REASON_UPSTREAM_ERROR
+
+
+@dataclass(frozen=True)
+class FallbackHop:
+    """One provider→provider transition and the reason behind it.
+
+    ``to_provider`` is ``None`` until the *next* provider is actually
+    attempted (see :meth:`FallbackTrace.record_attempt`); it stays ``None``
+    forever when the chain was exhausted without a successor.
+    """
+
+    from_provider: str
+    reason: str
+    to_provider: str | None = None
+    detail: str | None = None
+    stream: bool = False
+    pre_attempt: bool = False
+
+    def as_dict(self) -> dict[str, Any]:
+        """Serializable view, used by the SSE metadata event."""
+        return {
+            "from": self.from_provider,
+            "to": self.to_provider,
+            "reason": self.reason,
+            "detail": self.detail,
+            "stream": self.stream,
+            "pre_attempt": self.pre_attempt,
+        }
+
+
+@dataclass
+class FallbackTrace:
+    """Ordered record of every fallback that happened while serving one request.
+
+    Mutated in place by the engine. The ingress only ever reads it, so the
+    object can be shared safely between the request-handler context and the
+    SSE-iterator context (which inherits a copy of the same ContextVar
+    mapping, and therefore the same object).
+    """
+
+    hops: list[FallbackHop] = field(default_factory=list)
+    attempts: list[str] = field(default_factory=list)
+    profile: str | None = None
+    #: Set once the engine has emitted the ``fallback-occurred`` log lines
+    #: for this request, so a dispatch path with several terminal returns
+    #: cannot log the same hop trail twice.
+    logged: bool = False
+
+    # -- recording ---------------------------------------------------------
+
+    def record_skip(
+        self, provider: str, reason: str, *, detail: str | None = None
+    ) -> None:
+        """Record a provider filtered out of the chain before it was called."""
+        self.hops.append(
+            FallbackHop(
+                from_provider=provider,
+                reason=reason,
+                detail=detail,
+                pre_attempt=True,
+            )
+        )
+
+    def record_failure(
+        self,
+        provider: str,
+        reason: str,
+        *,
+        detail: str | None = None,
+        stream: bool = False,
+    ) -> None:
+        """Record a provider that was called and did not deliver."""
+        self.hops.append(
+            FallbackHop(
+                from_provider=provider,
+                reason=reason,
+                detail=detail,
+                stream=stream,
+                pre_attempt=False,
+            )
+        )
+
+    def record_attempt(self, provider: str) -> None:
+        """Record that ``provider`` is being tried, resolving pending hops.
+
+        Every hop still waiting for a successor (``to_provider is None``)
+        gets ``provider`` filled in. Consecutive skips therefore all point
+        at the same provider that finally ran, which is exactly the
+        narrative an operator wants: "budget blocked local and health
+        blocked ollama, so openrouter served it".
+        """
+        self.attempts.append(provider)
+        self.resolve_pending(provider)
+
+    def resolve_pending(self, provider: str) -> None:
+        """Point every still-unresolved hop at ``provider``.
+
+        Split out of :meth:`record_attempt` because the *streaming* ingress
+        needs the answer earlier than the first attempt: an SSE response
+        commits its HTTP headers before the engine's generator runs a
+        single line, so ``X-CodeRouter-Fallback-To`` would always be
+        missing if only ``record_attempt`` could fill it. The engine calls
+        this from ``apply_context_budget`` — the one place where the chain
+        is fully ordered (adaptive reorder, drift demotion and capability
+        bucketing have all been applied) and its head is therefore
+        genuinely the provider that will be tried first.
+
+        Idempotent and monotonic: only hops holding ``None`` are touched,
+        so a later ``record_attempt`` can never rewrite an answer this
+        already gave, and the two mechanisms compose instead of fighting.
+        """
+        for index, hop in enumerate(self.hops):
+            if hop.to_provider is None:
+                self.hops[index] = FallbackHop(
+                    from_provider=hop.from_provider,
+                    reason=hop.reason,
+                    to_provider=provider,
+                    detail=hop.detail,
+                    stream=hop.stream,
+                    pre_attempt=hop.pre_attempt,
+                )
+
+    # -- reading -----------------------------------------------------------
+
+    @property
+    def occurred(self) -> bool:
+        """True iff at least one fallback hop was recorded."""
+        return bool(self.hops)
+
+    @property
+    def chain(self) -> list[str]:
+        """Providers in try-order, including the one that finally served."""
+        if not self.hops:
+            return list(self.attempts)
+        names = [hop.from_provider for hop in self.hops]
+        final = self.hops[-1].to_provider
+        if final is not None:
+            names.append(final)
+        return names
+
+    @property
+    def reasons(self) -> list[str]:
+        """Departure reason for each hop, in order."""
+        return [hop.reason for hop in self.hops]
+
+    @property
+    def from_provider(self) -> str | None:
+        """The first provider that was abandoned."""
+        return self.hops[0].from_provider if self.hops else None
+
+    @property
+    def to_provider(self) -> str | None:
+        """The provider that ultimately served, or ``None`` if none did."""
+        return self.hops[-1].to_provider if self.hops else None
+
+    def header_values(self) -> dict[str, str]:
+        """Build the ``X-CodeRouter-Fallback-*`` response headers.
+
+        Returns an empty dict when no fallback occurred, so the caller can
+        merge unconditionally and the zero-fallback response keeps exactly
+        the headers it had before v2.15.0.
+        """
+        if not self.hops:
+            return {}
+        headers: dict[str, str] = {
+            HEADER_FALLBACK_FROM: _sanitize(self.hops[0].from_provider),
+            HEADER_FALLBACK_REASON: ",".join(_sanitize(r) for r in self.reasons),
+            HEADER_FALLBACK_CHAIN: ">".join(_sanitize(p) for p in self.chain),
+        }
+        final = self.hops[-1].to_provider
+        if final is not None:
+            headers[HEADER_FALLBACK_TO] = _sanitize(final)
+        return headers
+
+    def as_event_payload(self) -> dict[str, Any]:
+        """Build the ``coderouter_fallback`` SSE metadata event body."""
+        return {
+            "type": SSE_FALLBACK_EVENT,
+            "from": self.from_provider,
+            "to": self.to_provider,
+            "reason": self.reasons,
+            "chain": self.chain,
+            "hops": [hop.as_dict() for hop in self.hops],
+        }
+
+
+# ---------------------------------------------------------------------------
+# Request-scoped storage
+# ---------------------------------------------------------------------------
+
+_fallback_trace_ctx: ContextVar[FallbackTrace | None] = ContextVar(
+    "coderouter_fallback_trace", default=None
+)
+
+
+def begin_fallback_trace(
+    *, keep_existing: bool = False, profile: str | None = None
+) -> FallbackTrace:
+    """Install (or reuse) the trace for the request being dispatched.
+
+    ``keep_existing=True`` is used by the engine entry points when the M11
+    prepared dispatch was consumed: that proves the ingress already called
+    ``apply_context_budget`` for *this* request, so the trace it started
+    (holding the chain-resolve skips) must be kept rather than replaced.
+
+    In every other case a fresh trace is installed, which is what makes
+    successive direct engine calls in one context (unit tests, scripts)
+    independent instead of accumulating hops forever.
+    """
+    existing = _fallback_trace_ctx.get()
+    if keep_existing and existing is not None:
+        if profile is not None:
+            existing.profile = profile
+        return existing
+    trace = FallbackTrace(profile=profile)
+    _fallback_trace_ctx.set(trace)
+    return trace
+
+
+def ensure_fallback_trace(*, profile: str | None = None) -> FallbackTrace:
+    """Return the current trace, creating one only if none exists.
+
+    Used by chain resolution, which runs both inside dispatch (a trace
+    already exists) and from the ingress's ``apply_context_budget``
+    pre-pass (it does not yet).
+    """
+    existing = _fallback_trace_ctx.get()
+    if existing is not None:
+        if profile is not None and existing.profile is None:
+            existing.profile = profile
+        return existing
+    trace = FallbackTrace(profile=profile)
+    _fallback_trace_ctx.set(trace)
+    return trace
+
+
+def current_fallback_trace() -> FallbackTrace | None:
+    """Return the trace for the current request, or ``None``.
+
+    Read-only accessor for the ingress. ``None`` means "nothing recorded"
+    — either no fallback machinery ran (a stubbed engine in a test) or the
+    engine never started a trace. Callers must treat it as "no fallback".
+    """
+    return _fallback_trace_ctx.get()
+
+
+def reset_fallback_trace() -> None:
+    """Clear the current trace. Test helper; not used in the request path."""
+    _fallback_trace_ctx.set(None)

coderouter/state/audit_log.py

@@ -78,6 +78,10 @@ _AUDIT_EVENTS: frozenset[str] = frozenset(
         "chain-paid-gate-blocked",
         "chain-memory-pressure-blocked",
         "chain-uniform-auth-failure",
+        # Fallback reason trail (v2.15.0) — one line per chain transition.
+        # Low volume by construction: nothing is emitted when the first
+        # provider serves the request.
+        "fallback-occurred",
         # Memory pressure
         "memory-pressure-detected",
         # Drift (v2.0-G)

coderouter/vscode_init.py

@@ -24,9 +24,16 @@ The design contract:
   until a human debugged it.
 * Nothing an operator wrote is destroyed without a copy: before any
   existing file is rewritten, its previous bytes (and mode) land in
-  ``<name>.bak``. ``--force`` on ``.envrc`` is a whole-file replace,
-  not a merge, so this is the only thing standing between the user and
-  a lost ``source_env_if_exists .envrc.local`` line.
+  ``<name>.bak``, which ``coderouter rollback`` can swap back.
+* Since v2.14.0, ``.envrc`` is edited through a marker-delimited block
+  (``# BEGIN coderouter-managed`` … ``# END coderouter-managed``): only
+  that block is rewritten and every other line survives byte-for-byte.
+  A re-run over an already-fenced file therefore needs no ``--force``;
+  ``--force`` now means "adopt a file I did not write". Before v2.14.0
+  this was a whole-file replace, which is how the lost
+  ``source_env_if_exists .envrc.local`` line (H-11) happened — see the
+  "marker-delimited managed block in .envrc" section below for the full
+  rationale and the conflict rules.
 * A freshly generated ``.envrc`` is created 0600 — it carries
   ``ANTHROPIC_AUTH_TOKEN`` and sits next to the operator's real
   secrets. An existing file's mode is preserved across rewrites

{coderouter_cli-2.14.0.dist-info → coderouter_cli-2.15.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: coderouter-cli
-Version: 2.14.0
+Version: 2.15.1
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter
@@ -66,7 +66,7 @@ Description-Content-Type: text/markdown
 ## 何ができるか — 30 秒で
 
 ```
-あなたのエージェント (Claude Code / codex / agy)
+あなたのエージェント (Claude Code / agy ほか ※)
         │
         ▼
   ┌─ CodeRouter ─┐
@@ -76,6 +76,8 @@ Description-Content-Type: text/markdown
   └──────────────┘
 ```
 
+※ 現行の codex CLI は Responses API（`/v1/responses`）専用になったため、CodeRouter 経由ではまだ使えません（対応予定）。直結の代替手順 → [quickstart Pattern B](./docs/start/quickstart.md#pattern-b-codex-cli-で使う)
+
 **やってくれること:**
 
 - ローカルモデルが壊した tool calling を Claude Code に届く前に修復する
@@ -118,6 +120,8 @@ uvx --from coderouter-cli coderouter serve --port 8088
 
 恒久インストールしたい場合: `uv tool install coderouter-cli`
 
+> **パッケージ名に注意**: PyPI のパッケージ名は **`coderouter-cli`** です。PyPI の `coderouter`（名前だけ同じ）は別の製品なので、`pip install coderouter` と打たないでください。
+
 ---
 
 ## Claude Code で使う
@@ -143,7 +147,7 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 | Claude Code + ローカル Ollama で tool calling が壊れる | **必須** — tool 修復 (+ 必要なら wire 変換) |
 | Claude Code + ローカルで長時間回すと止まる | **必須級** — 6 系統ガード + self-healing |
 | Ollama v0.14+ / LM Studio にネイティブ直結で動いてる | **便利** — 直結に無い fallback / ガード / 診断を追加 (passthrough で翻訳ゼロ) |
-| codex / agy + Ollama 直繋ぎで動いてる | オプション — フォールバックが欲しいなら |
+| codex / agy + Ollama 直繋ぎで動いてる | オプション — フォールバックが欲しいなら(codex は `/v1/responses` 対応後) |
 | Claude API を直接叩いてて問題ない | 不要 |
 
 詳細は → [要否判定ガイド](./docs/start/when-do-i-need-coderouter.md)
@@ -156,7 +160,7 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 
 | 機能 | 何をしてくれるか |
 |---|---|
-| **Tool-call 修復** | ローカルモデルがテキストで吐いた JSON を正しい tool_use ブロックに復元 |
+| **Tool-call 修復** | ローカルモデルがテキストで吐いた JSON を正しい tool_use ブロックに復元。実測は [修復ベンチ](./benchmarks/tool-repair/README.md)（壊れた tool call を出す 4 モデルで成功率 0% → 80〜100%、回帰コーパスで誤修復 0 件。CI でゲート） |
 | **3 層フォールバック** | ローカル → 無料クラウド → 有料の順に自動切替 |
 | **出力フィルタ** | `<think>` タグ漏れ、stop marker 漏れ、byte-fallback (`<0xNN>`) を自動除去/修復 |
 | **Wire 翻訳** | Anthropic 形式 ↔ OpenAI 形式を自動変換 (ネイティブ `/v1/messages` 対応 backend は passthrough で翻訳ゼロ) |
@@ -333,6 +337,14 @@ CodeRouter は backend ルーター層として独立して動きます。`OPENA
 
 シークレットは環境変数に置きます。[`docs/security.md`](./docs/guides/security.md) に完全な方針と報告手順があります。
 
+リリースは多層で守っています。どれか 1 つを根拠に「安全」とは言いません(正規のパイプラインでビルドされた汚染版が出た例があります)。
+
+- PyPI へは Trusted Publishing(OIDC)で公開し、長期の API トークンを置かない
+- PyPI 側の公開許可は `release.yml` の `pypi` 環境に限定している
+- タグは事前検査スクリプトを通してから打つ(version・CHANGELOG・main の一致を機械的に確認)
+- 実行時の依存は 5 個に絞っている
+- 各リリースに SBOM(CycloneDX)を添付する
+
 ## License
 
 MIT