caudate-cli 0.1.0__py3-none-any.whl

api/anthropic_compat.py

@@ -0,0 +1,1518 @@
+"""Anthropic Messages API compatibility layer.
+
+Lets Claude Code (or any other Anthropic-format client) point at Cognos
+and get answers back as if Cognos were Anthropic. Internally:
+
+    incoming  /v1/messages  (Anthropic schema)
+        │
+        ▼
+    translate to Cognos's internal message format
+        │
+        ▼
+    route through CognosAgent.llm  (DualLLMProvider — Caudate + dual-brain
+    routing + fallback chain + prompt caching all engaged)
+        │
+        ▼
+    translate response back to Anthropic schema (regular or SSE stream)
+        │
+        ▼
+    Claude Code consumes it the same way it consumes a real Anthropic call
+
+This is a pure LLM proxy — Claude Code keeps doing its own tool
+execution. Cognos does NOT run its agentic loop here. The benefit is
+that Claude Code's well-engineered REPL + tool stack is preserved, and
+Cognos contributes its routing brain, memory, and (eventually) Caudate
+predictions to every call.
+
+Set Claude Code's env to use Cognos:
+
+    export ANTHROPIC_BASE_URL=http://127.0.0.1:8000
+    export ANTHROPIC_AUTH_TOKEN=cognos
+    export ANTHROPIC_API_KEY=""
+    claude   # now talks to Cognos instead of Anthropic
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import time
+import uuid
+from typing import Any, AsyncIterator
+
+import httpx
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from api.caudate_middleware import CaudateMiddleware
+from core.schemas import StreamEvent, ToolUseBlock
+from llm.provider import LLMProvider
+
+
+# ---- Anthropic passthrough -------------------------------------------
+# When system1 (or the requested model) is an Anthropic Claude id,
+# Cognos forwards the request to api.anthropic.com using the caller's
+# original Authorization header (the user's Claude Code subscription
+# token) instead of routing through LiteLLM/Ollama. Caudate still
+# observes — she sees Opus's behaviour and learns from it.
+
+ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages"
+_ANTHROPIC_VERSION_DEFAULT = "2023-06-01"
+
+# Force-enable extended thinking on the upstream request so Caudate
+# always observes Opus's reasoning channel. Disabled with
+# COGNOS_FORCE_THINKING=0 if it ever causes issues.
+_FORCE_THINKING_DEFAULT_BUDGET = 4096
+_FORCE_THINKING_MIN_MAX_TOKENS = 1024  # don't force on tiny requests
+
+# Headers we forward verbatim from the incoming request to Anthropic.
+# Anything else (host, content-length, accept-encoding, x-forwarded-*)
+# is dropped so httpx can compute its own.
+_FORWARD_REQUEST_HEADERS = {
+    "authorization", "anthropic-version", "anthropic-beta",
+    "x-api-key", "anthropic-dangerous-direct-browser-access",
+}
+
+
+def _resolve_anthropic_model(requested_model: str | None) -> str | None:
+    """Return the Anthropic model id to send upstream, or None if this
+    request should NOT use the Anthropic passthrough.
+
+    Decision order:
+      1. requested_model is a Cognos-internal id (has a `[...]` suffix
+         like "claude-opus-4-7[1m]" that Claude Code self-reports) → None,
+         route locally via the dual-brain path (these ids 404 upstream)
+      2. requested_model is already a real claude id → use as-is
+      3. requested_model has the "anthropic/" prefix → strip it
+      4. settings.system1 starts with "anthropic/" → use that resolved id
+         (catches the case where the client picked a "cognos-*" alias)
+      5. otherwise → None (fall through to local LiteLLM path)
+    """
+    if requested_model:
+        m = requested_model.strip()
+        # Claude Code identifies itself with a bracketed context-window
+        # suffix (e.g. "claude-opus-4-7[1m]"). That id is not in the
+        # Anthropic public catalog and forwarding it 404s — drop to
+        # local dual-brain routing instead.
+        if "[" in m and m.endswith("]"):
+            return None
+        if m.startswith("claude-"):
+            return m
+        if m.startswith("anthropic/"):
+            return m.split("/", 1)[1]
+    # Settings-driven fallback: if system1 is configured for Anthropic,
+    # any client request lands on Opus regardless of which "cognos-*"
+    # alias they picked.
+    try:
+        from core.settings import Settings
+        s1 = (Settings.load().get("system1") or "")
+        if s1.startswith("anthropic/"):
+            return s1.split("/", 1)[1]
+    except Exception:
+        pass
+    return None
+
+
+# Capability matrix per model family. Claude Code sends a fistful of
+# request fields that only the newer/larger models accept (extended
+# thinking, the effort knob, etc). When the resolved upstream model
+# doesn't support a given field, we strip it before forwarding — else
+# Anthropic returns 400s like `adaptive thinking is not supported on
+# this model` or `does not support the effort parameter`.
+_THINKING_CAPABLE_PREFIXES = (
+    "claude-opus-",
+    "claude-sonnet-",
+)
+_EFFORT_CAPABLE_PREFIXES = (
+    "claude-opus-",
+    "claude-sonnet-",
+)
+
+
+def _model_supports_thinking(model_id: str) -> bool:
+    if not model_id:
+        return False
+    return any(model_id.startswith(p) for p in _THINKING_CAPABLE_PREFIXES)
+
+
+def _model_supports_effort(model_id: str) -> bool:
+    if not model_id:
+        return False
+    return any(model_id.startswith(p) for p in _EFFORT_CAPABLE_PREFIXES)
+
+
+def _strip_thinking_dependent_context_management(
+    upstream_body: dict[str, Any],
+) -> dict[str, Any]:
+    """Remove `context_management.edits` entries whose `type` mentions
+    'thinking' — they require thinking to be enabled and Anthropic
+    rejects with 400 when it's been stripped (e.g. Haiku path).
+
+    If the resulting edits list is empty, drop the whole
+    `context_management` field; otherwise keep it with the surviving
+    edits."""
+    cm = upstream_body.get("context_management")
+    if not isinstance(cm, dict):
+        return upstream_body
+    edits = cm.get("edits")
+    if not isinstance(edits, list):
+        return upstream_body
+    surviving = [
+        e for e in edits
+        if not (isinstance(e, dict)
+                and isinstance(e.get("type"), str)
+                and "thinking" in e["type"])
+    ]
+    if not surviving:
+        upstream_body.pop("context_management", None)
+    else:
+        upstream_body["context_management"] = {**cm, "edits": surviving}
+    return upstream_body
+
+
+def _strip_unsupported_thinking(
+    upstream_body: dict[str, Any], model_id: str,
+) -> dict[str, Any]:
+    """If the upstream model doesn't support thinking, drop the field
+    *and* any context_management strategies that depend on it."""
+    if not _model_supports_thinking(model_id):
+        upstream_body.pop("thinking", None)
+        upstream_body = _strip_thinking_dependent_context_management(upstream_body)
+    return upstream_body
+
+
+def _strip_unsupported_fields(
+    upstream_body: dict[str, Any], model_id: str,
+) -> dict[str, Any]:
+    """Strip every Claude-Code-extended field that the resolved
+    upstream model doesn't accept. Centralises the per-field capability
+    checks so adding a new one is one line.
+
+    Effort lives both at the top level AND nested inside `output_config`
+    on newer Claude Code clients — handle both."""
+    upstream_body = _strip_unsupported_thinking(upstream_body, model_id)
+    if not _model_supports_effort(model_id):
+        upstream_body.pop("effort", None)
+        oc = upstream_body.get("output_config")
+        if isinstance(oc, dict) and "effort" in oc:
+            oc = {k: v for k, v in oc.items() if k != "effort"}
+            if oc:
+                upstream_body["output_config"] = oc
+            else:
+                upstream_body.pop("output_config", None)
+    return upstream_body
+
+
+def _maybe_force_thinking(upstream_body: dict[str, Any]) -> dict[str, Any]:
+    """Inject `thinking: {type: enabled}` if the caller didn't ask for it.
+
+    Caudate's training depends on observing Opus's reasoning channel —
+    not just the visible answer. Without this, Claude Code's default
+    request shape leaves thinking off and Caudate sees only the surface
+    output.
+
+    Skips when:
+      - caller already set `thinking` (respect explicit choice)
+      - max_tokens is very small (thinking budget would starve the answer)
+      - COGNOS_FORCE_THINKING=0 in env (escape hatch)
+    """
+    # Default OFF: Claude Code already requests thinking when it wants
+    # it (and Anthropic rejects requests where forced budget brushes
+    # against max_tokens, which produces 400s on title-gen / tab-
+    # completion calls). Opt in via COGNOS_FORCE_THINKING=1.
+    if os.environ.get("COGNOS_FORCE_THINKING", "0") != "1":
+        return upstream_body
+    if "thinking" in upstream_body:
+        return upstream_body
+    max_tokens = int(upstream_body.get("max_tokens") or 0)
+    # Need enough headroom: thinking + answer must both fit in max_tokens.
+    # Skip unless we can guarantee a budget *and* leave 1024 tokens free.
+    if not max_tokens or max_tokens < (_FORCE_THINKING_MIN_MAX_TOKENS + 1024):
+        return upstream_body
+    budget = min(_FORCE_THINKING_DEFAULT_BUDGET, max_tokens - 1024)
+    if budget < 1024:
+        return upstream_body
+    upstream_body["thinking"] = {"type": "enabled", "budget_tokens": budget}
+    if "temperature" in upstream_body and upstream_body["temperature"] != 1:
+        upstream_body["temperature"] = 1
+    upstream_body.pop("top_p", None)
+    upstream_body.pop("top_k", None)
+    return upstream_body
+
+
+def _filter_forward_headers(request: Request) -> dict[str, str]:
+    """Pick only the headers we want to forward upstream."""
+    out: dict[str, str] = {}
+    for k, v in request.headers.items():
+        if k.lower() in _FORWARD_REQUEST_HEADERS:
+            out[k] = v
+    out.setdefault("anthropic-version", _ANTHROPIC_VERSION_DEFAULT)
+    out["content-type"] = "application/json"
+    return out
+
+
+def _parse_sse_event(raw_event: str) -> tuple[str | None, dict[str, Any] | None]:
+    """Parse one SSE event block ('event: X\\ndata: {...}') into (type, data)."""
+    event_type: str | None = None
+    data_lines: list[str] = []
+    for line in raw_event.splitlines():
+        if line.startswith("event:"):
+            event_type = line[6:].strip()
+        elif line.startswith("data:"):
+            data_lines.append(line[5:].strip())
+    if not data_lines:
+        return event_type, None
+    try:
+        data = json.loads("\n".join(data_lines))
+    except Exception:
+        return event_type, None
+    return event_type, data
+
+
+async def _passthrough_anthropic_stream(
+    *,
+    upstream_body: dict[str, Any],
+    headers: dict[str, str],
+    middleware: CaudateMiddleware | None,
+    turn_ctx: Any,
+) -> AsyncIterator[bytes]:
+    """Forward streaming /v1/messages to api.anthropic.com.
+
+    Bytes are forwarded to the client unchanged so SSE event ordering
+    and field shape are preserved exactly. Each event is *also* parsed
+    in-flight so Caudate observes text/thinking/tool deltas as they
+    happen.
+    """
+    error_occurred = False
+    block_types: dict[int, str] = {}  # index -> block type ("text"/"thinking"/"tool_use")
+    block_tool_names: dict[int, str] = {}    # index -> tool name (for stop-event lookup)
+    block_tool_inputs: dict[int, str] = {}   # index -> accumulated input_json string
+    pending_chunk = ""
+
+    try:
+        async with httpx.AsyncClient(timeout=httpx.Timeout(300.0, connect=15.0)) as client:
+            async with client.stream(
+                "POST", ANTHROPIC_API_URL,
+                headers=headers,
+                json=upstream_body,
+            ) as resp:
+                if resp.status_code >= 400:
+                    error_occurred = True
+                    body_bytes = await resp.aread()
+                    yield (
+                        f"event: error\ndata: "
+                        f"{json.dumps({'type':'error','error':{'type':'api_error','message':body_bytes.decode('utf-8', errors='replace')}})}"
+                        f"\n\n"
+                    ).encode()
+                    return
+
+                async for chunk in resp.aiter_bytes():
+                    if not chunk:
+                        continue
+                    yield chunk
+                    # Tee into Caudate. Accumulate until we see a blank
+                    # line which terminates one SSE event.
+                    pending_chunk += chunk.decode("utf-8", errors="replace")
+                    while "\n\n" in pending_chunk:
+                        raw_event, pending_chunk = pending_chunk.split("\n\n", 1)
+                        if not raw_event.strip():
+                            continue
+                        evt_type, data = _parse_sse_event(raw_event)
+                        if data is None or middleware is None or turn_ctx is None:
+                            continue
+                        try:
+                            if evt_type == "content_block_start":
+                                idx = int(data.get("index", -1))
+                                cb = data.get("content_block") or {}
+                                block_types[idx] = cb.get("type", "")
+                                if cb.get("type") == "tool_use":
+                                    name = cb.get("name", "")
+                                    block_tool_names[idx] = name
+                                    block_tool_inputs[idx] = ""
+                                    middleware.observe_tool_use(turn_ctx, name)
+                            elif evt_type == "content_block_delta":
+                                idx = int(data.get("index", -1))
+                                delta = data.get("delta") or {}
+                                dtype = delta.get("type")
+                                if dtype == "text_delta":
+                                    middleware.observe_response_text(turn_ctx, delta.get("text", ""))
+                                elif dtype == "thinking_delta":
+                                    middleware.observe_thinking(turn_ctx, delta.get("thinking", ""))
+                                elif dtype == "input_json_delta":
+                                    # Accumulate the streamed JSON of a
+                                    # tool_use block so we can capture
+                                    # questions/inputs (e.g.
+                                    # AskUserQuestion's question + options)
+                                    # for Caudate's training context.
+                                    block_tool_inputs[idx] = (
+                                        block_tool_inputs.get(idx, "")
+                                        + (delta.get("partial_json") or "")
+                                    )
+                            elif evt_type == "content_block_stop":
+                                idx = int(data.get("index", -1))
+                                if block_types.get(idx) == "tool_use":
+                                    name = block_tool_names.get(idx, "")
+                                    raw = block_tool_inputs.get(idx, "")
+                                    if raw:
+                                        # Surface the structured input as
+                                        # part of the response text so
+                                        # Caudate's text-encoder sees it.
+                                        middleware.observe_response_text(
+                                            turn_ctx,
+                                            f"\n[tool_use {name}({raw[:1000]})]\n",
+                                        )
+                        except Exception as e:
+                            logger.debug(f"caudate observe (passthrough stream) failed: {e}")
+    except Exception as e:
+        logger.exception("Anthropic passthrough stream failed")
+        error_occurred = True
+        yield (
+            f"event: error\ndata: "
+            f"{json.dumps({'type':'error','error':{'type':'api_error','message':str(e)}})}"
+            f"\n\n"
+        ).encode()
+    finally:
+        if middleware is not None and turn_ctx is not None:
+            middleware.end_turn(turn_ctx, error=error_occurred)
+
+
+async def _passthrough_anthropic_nonstream(
+    *,
+    upstream_body: dict[str, Any],
+    headers: dict[str, str],
+    middleware: CaudateMiddleware | None,
+    turn_ctx: Any,
+) -> JSONResponse:
+    """Forward non-streaming /v1/messages and observe the response."""
+    try:
+        async with httpx.AsyncClient(timeout=httpx.Timeout(300.0, connect=15.0)) as client:
+            resp = await client.post(
+                ANTHROPIC_API_URL, headers=headers, json=upstream_body,
+            )
+        if resp.status_code >= 400:
+            if middleware is not None and turn_ctx is not None:
+                middleware.end_turn(turn_ctx, error=True)
+            return JSONResponse(
+                status_code=resp.status_code,
+                content={"type": "error", "error": {
+                    "type": "api_error",
+                    "message": resp.text,
+                }},
+            )
+        data = resp.json()
+        if middleware is not None and turn_ctx is not None:
+            try:
+                for block in data.get("content") or []:
+                    btype = block.get("type")
+                    if btype == "text":
+                        middleware.observe_response_text(turn_ctx, block.get("text", ""))
+                    elif btype == "thinking":
+                        middleware.observe_thinking(turn_ctx, block.get("thinking", ""))
+                    elif btype == "tool_use":
+                        name = block.get("name", "")
+                        middleware.observe_tool_use(turn_ctx, name)
+                        # Surface the tool's structured input (the
+                        # question + options for AskUserQuestion, etc.)
+                        # so Caudate sees the intent, not just the name.
+                        try:
+                            inp = json.dumps(block.get("input") or {}, ensure_ascii=False)[:1000]
+                        except Exception:
+                            inp = str(block.get("input"))[:1000]
+                        if inp:
+                            middleware.observe_response_text(
+                                turn_ctx, f"\n[tool_use {name}({inp})]\n",
+                            )
+            except Exception as e:
+                logger.debug(f"caudate observe (passthrough nonstream) failed: {e}")
+            middleware.end_turn(turn_ctx, error=False)
+        return JSONResponse(content=data, status_code=resp.status_code)
+    except Exception as e:
+        logger.exception("Anthropic passthrough nonstream failed")
+        if middleware is not None and turn_ctx is not None:
+            middleware.end_turn(turn_ctx, error=True)
+        raise HTTPException(502, f"Anthropic upstream error: {e}")
+
+logger = logging.getLogger(__name__)
+
+
+# ---- Translation helpers ---------------------------------------------
+
+
+def _translate_anthropic_to_internal(
+    body: dict[str, Any],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]] | None]:
+    """Anthropic /v1/messages body → Cognos messages list + tools list.
+
+    Returns (messages, tools_or_None). Messages are in OpenAI/LiteLLM
+    shape since that's what `LLMProvider.chat()` expects underneath.
+    """
+    raw_messages = body.get("messages") or []
+    raw_system = body.get("system")
+    raw_tools = body.get("tools") or []
+
+    out: list[dict[str, Any]] = []
+
+    # System prompt — can be a string or a list of text blocks
+    if isinstance(raw_system, str) and raw_system:
+        out.append({"role": "system", "content": raw_system})
+    elif isinstance(raw_system, list):
+        text = "".join(
+            b.get("text", "") for b in raw_system
+            if isinstance(b, dict) and b.get("type") == "text"
+        )
+        if text:
+            out.append({"role": "system", "content": text})
+
+    # Convert each message
+    for msg in raw_messages:
+        role = msg.get("role")
+        content = msg.get("content")
+        if isinstance(content, str):
+            out.append({"role": role, "content": content})
+            continue
+
+        if not isinstance(content, list):
+            continue
+
+        # Multi-block content — translate each block
+        text_parts: list[dict[str, Any]] = []
+        tool_uses: list[dict[str, Any]] = []
+        tool_results: list[dict[str, Any]] = []
+
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            btype = block.get("type")
+            if btype == "text":
+                text_parts.append({"type": "text", "text": block.get("text", "")})
+            elif btype == "image":
+                src = block.get("source") or {}
+                if src.get("type") == "base64":
+                    media_type = src.get("media_type", "image/png")
+                    data = src.get("data", "")
+                    text_parts.append({
+                        "type": "image_url",
+                        "image_url": {"url": f"data:{media_type};base64,{data}"},
+                    })
+                elif src.get("type") == "url":
+                    text_parts.append({
+                        "type": "image_url",
+                        "image_url": {"url": src.get("url", "")},
+                    })
+            elif btype == "tool_use":
+                tool_uses.append({
+                    "id": block.get("id", ""),
+                    "type": "function",
+                    "function": {
+                        "name": block.get("name", ""),
+                        "arguments": json.dumps(block.get("input") or {}),
+                    },
+                })
+            elif btype == "tool_result":
+                # Anthropic puts tool results in user messages; OpenAI
+                # uses a separate "tool" role.
+                rc = block.get("content")
+                if isinstance(rc, list):
+                    rc = "\n".join(
+                        b.get("text", "") for b in rc
+                        if isinstance(b, dict) and b.get("type") == "text"
+                    )
+                tool_results.append({
+                    "role": "tool",
+                    "tool_call_id": block.get("tool_use_id", ""),
+                    "content": str(rc or ""),
+                })
+
+        # Emit assistant message with tool_calls (OpenAI shape)
+        if role == "assistant":
+            entry: dict[str, Any] = {"role": "assistant"}
+            if text_parts:
+                entry["content"] = (
+                    text_parts[0]["text"] if len(text_parts) == 1
+                    and text_parts[0]["type"] == "text"
+                    else text_parts
+                )
+            else:
+                entry["content"] = ""
+            if tool_uses:
+                entry["tool_calls"] = tool_uses
+            out.append(entry)
+        else:
+            # User message — text + images stay together; tool_results
+            # become separate "tool" role messages right after.
+            if text_parts:
+                payload: Any = (
+                    text_parts[0]["text"] if len(text_parts) == 1
+                    and text_parts[0]["type"] == "text"
+                    else text_parts
+                )
+                out.append({"role": "user", "content": payload})
+            for tr in tool_results:
+                out.append(tr)
+
+    tools_translated: list[dict[str, Any]] | None = None
+    if raw_tools:
+        tools_translated = [
+            {
+                "type": "function",
+                "function": {
+                    "name": t.get("name", ""),
+                    "description": t.get("description", ""),
+                    "parameters": t.get("input_schema") or {
+                        "type": "object", "properties": {}, "required": [],
+                    },
+                },
+            }
+            for t in raw_tools if isinstance(t, dict)
+        ]
+
+    return out, tools_translated
+
+
+def _build_anthropic_response(
+    *,
+    thinking: str = "",
+    text: str,
+    tool_calls: list[ToolUseBlock],
+    model: str,
+    usage: dict[str, int],
+    stop_reason: str | None,
+) -> dict[str, Any]:
+    """Build the non-streaming /v1/messages response."""
+    blocks: list[dict[str, Any]] = []
+    # Thinking block first — Anthropic's spec puts thinking before text
+    # so clients (Claude Code) render the reasoning above the answer.
+    if thinking:
+        blocks.append({"type": "thinking", "thinking": thinking})
+    if text:
+        blocks.append({"type": "text", "text": text})
+    for tc in tool_calls:
+        blocks.append({
+            "type": "tool_use",
+            "id": tc.id or f"toolu_{uuid.uuid4().hex[:12]}",
+            "name": tc.name,
+            "input": tc.input or {},
+        })
+
+    # Translate stop reason
+    stop_map = {
+        "stop": "end_turn", "length": "max_tokens",
+        "tool_calls": "tool_use", "tool_use": "tool_use",
+    }
+    anthropic_stop = stop_map.get(stop_reason or "stop", "end_turn")
+    if tool_calls and anthropic_stop == "end_turn":
+        anthropic_stop = "tool_use"
+
+    return {
+        "id": f"msg_{uuid.uuid4().hex[:24]}",
+        "type": "message",
+        "role": "assistant",
+        "model": model,
+        "content": blocks or [{"type": "text", "text": ""}],
+        "stop_reason": anthropic_stop,
+        "stop_sequence": None,
+        "usage": {
+            "input_tokens": usage.get("prompt_tokens", 0),
+            "output_tokens": usage.get("completion_tokens", 0),
+        },
+    }
+
+
+# ---- Streaming SSE generator -----------------------------------------
+
+
+async def _stream_anthropic_events(
+    llm: LLMProvider,
+    messages: list[dict[str, Any]],
+    tools: list[dict[str, Any]] | None,
+    max_tokens: int,
+    temperature: float | None,
+    requested_model: str,
+    middleware: CaudateMiddleware | None = None,
+    turn_ctx: Any = None,
+) -> AsyncIterator[bytes]:
+    """Cognos stream → Anthropic SSE format.
+
+    Anthropic emits a strict sequence of events:
+      message_start, content_block_start (text), [content_block_delta]+
+      content_block_stop, [tool blocks], message_delta, message_stop
+    """
+    msg_id = f"msg_{uuid.uuid4().hex[:24]}"
+
+    def _sse(event: str, data: dict[str, Any]) -> bytes:
+        return f"event: {event}\ndata: {json.dumps(data)}\n\n".encode()
+
+    # message_start
+    yield _sse("message_start", {
+        "type": "message_start",
+        "message": {
+            "id": msg_id, "type": "message", "role": "assistant",
+            "model": requested_model, "content": [],
+            "stop_reason": None, "stop_sequence": None,
+            "usage": {"input_tokens": 0, "output_tokens": 1},
+        },
+    })
+
+    # We track which content blocks we've opened.
+    # Block layout follows Anthropic's spec: thinking (if any) at index 0,
+    # then text at the next index, then tool_use blocks after that.
+    thinking_open = False
+    thinking_index = 0
+    text_open = False
+    text_index = 0
+    tool_blocks: list[tuple[int, ToolUseBlock]] = []
+    next_index = 0
+    output_text = ""
+    stop_reason: str | None = None
+
+    def _close_thinking() -> bytes | None:
+        nonlocal thinking_open
+        if thinking_open:
+            thinking_open = False
+            return _sse("content_block_stop", {
+                "type": "content_block_stop", "index": thinking_index,
+            })
+        return None
+
+    error_occurred = False
+    try:
+        async for event in llm.stream(
+            messages=messages, tools=tools,
+            max_tokens=max_tokens, temperature=temperature,
+        ):
+            if event.type == "thinking_delta" and event.delta:
+                # Feed thinking into the middleware too — it's signal
+                # for tool-intent inference even though it's not visible.
+                if middleware is not None and turn_ctx is not None:
+                    middleware.observe_thinking(turn_ctx, event.delta)
+                # First thinking chunk: open the thinking block
+                if not thinking_open:
+                    yield _sse("content_block_start", {
+                        "type": "content_block_start",
+                        "index": thinking_index,
+                        "content_block": {"type": "thinking", "thinking": ""},
+                    })
+                    thinking_open = True
+                    text_index = thinking_index + 1
+                    next_index = max(next_index, thinking_index + 1)
+                yield _sse("content_block_delta", {
+                    "type": "content_block_delta",
+                    "index": thinking_index,
+                    "delta": {"type": "thinking_delta", "thinking": event.delta},
+                })
+            elif event.type == "text_delta" and event.delta:
+                # If thinking was open and we're switching to text, close it
+                close_evt = _close_thinking()
+                if close_evt:
+                    yield close_evt
+                if not text_open:
+                    yield _sse("content_block_start", {
+                        "type": "content_block_start",
+                        "index": text_index,
+                        "content_block": {"type": "text", "text": ""},
+                    })
+                    text_open = True
+                    next_index = max(next_index, text_index + 1)
+                output_text += event.delta
+                if middleware is not None and turn_ctx is not None:
+                    middleware.observe_response_text(turn_ctx, event.delta)
+                yield _sse("content_block_delta", {
+                    "type": "content_block_delta",
+                    "index": text_index,
+                    "delta": {"type": "text_delta", "text": event.delta},
+                })
+            elif event.type == "tool_use_end":
+                # Close any open thinking block before emitting tool blocks
+                close_evt = _close_thinking()
+                if close_evt:
+                    yield close_evt
+                # Cognos emits the whole tool call at once. Anthropic
+                # wants a content_block_start + input_json_delta + stop.
+                idx = next_index
+                next_index += 1
+                tc = ToolUseBlock(
+                    id=event.tool_use_id or f"toolu_{uuid.uuid4().hex[:12]}",
+                    name=event.tool_name or "",
+                    input=event.tool_input or {},
+                )
+                tool_blocks.append((idx, tc))
+                if middleware is not None and turn_ctx is not None:
+                    middleware.observe_tool_use(turn_ctx, tc.name)
+                yield _sse("content_block_start", {
+                    "type": "content_block_start",
+                    "index": idx,
+                    "content_block": {
+                        "type": "tool_use",
+                        "id": tc.id,
+                        "name": tc.name,
+                        "input": {},
+                    },
+                })
+                yield _sse("content_block_delta", {
+                    "type": "content_block_delta",
+                    "index": idx,
+                    "delta": {
+                        "type": "input_json_delta",
+                        "partial_json": json.dumps(tc.input),
+                    },
+                })
+                yield _sse("content_block_stop", {
+                    "type": "content_block_stop", "index": idx,
+                })
+            elif event.type == "message_stop":
+                stop_reason = event.stop_reason
+    except Exception as e:
+        logger.exception("Stream upstream failed")
+        error_occurred = True
+        # Emit an error event so the client knows
+        yield _sse("error", {
+            "type": "error",
+            "error": {"type": "api_error", "message": str(e)},
+        })
+        if middleware is not None and turn_ctx is not None:
+            middleware.end_turn(turn_ctx, error=True)
+        return
+
+    if thinking_open:
+        yield _sse("content_block_stop", {
+            "type": "content_block_stop", "index": thinking_index,
+        })
+        thinking_open = False
+    if text_open:
+        yield _sse("content_block_stop", {
+            "type": "content_block_stop", "index": text_index,
+        })
+
+    # Translate stop reason
+    stop_map = {
+        "stop": "end_turn", "length": "max_tokens",
+        "tool_calls": "tool_use", "tool_use": "tool_use",
+    }
+    anthropic_stop = stop_map.get(stop_reason or "stop", "end_turn")
+    if tool_blocks and anthropic_stop == "end_turn":
+        anthropic_stop = "tool_use"
+
+    # Approximate output token count — we don't have it exact for streaming
+    output_tokens = max(1, len(output_text.split()))
+
+    yield _sse("message_delta", {
+        "type": "message_delta",
+        "delta": {"stop_reason": anthropic_stop, "stop_sequence": None},
+        "usage": {"output_tokens": output_tokens},
+    })
+    yield _sse("message_stop", {"type": "message_stop"})
+
+    # Close the Caudate turn — derive reward, push samples, write episode,
+    # potentially trigger auto-train.
+    if middleware is not None and turn_ctx is not None and not error_occurred:
+        middleware.end_turn(turn_ctx, error=False)
+
+
+# ---- Dual-brain arbitration on /v1/messages -------------------------
+# Mirror of the Open-WebUI arbitration in api/openai_compat.py, but the
+# response/stream shape is Anthropic, not OpenAI. Both brains are run
+# in parallel and a heuristic scorer picks the winner; both drafts are
+# captured for Caudate's preference-learning corpus
+# (data/nn/arbitrations.jsonl). This is the substrate for Phase 4 of
+# CAUDATE_EVOLUTION.md (the conductor) — same data shape regardless of
+# which client speaks to Cognos.
+
+
+def _anthropic_response_from_llm_response(
+    *,
+    resp: Any,                          # LLMResponse
+    requested_model: str,
+) -> dict[str, Any]:
+    """Translate an internal `LLMResponse` into Anthropic /v1/messages body."""
+    # Surface thinking when content is empty (mirror the openai-compat
+    # fallback so the user always sees something).
+    text = resp.content or ""
+    thinking = getattr(resp, "thinking", "") or ""
+    if not text and thinking:
+        text = (
+            f"[thinking — model didn't finish before max_tokens]\n\n{thinking}"
+        )
+    return _build_anthropic_response(
+        thinking=thinking if text != f"[thinking — model didn't finish before max_tokens]\n\n{thinking}" else "",
+        text=text,
+        tool_calls=resp.tool_calls or [],
+        model=requested_model,
+        usage=resp.usage or {},
+        stop_reason=resp.stop_reason,
+    )
+
+
+async def _anthropic_arbitrate_nonstream(
+    *,
+    body: dict[str, Any],
+    internal_msgs: list[dict[str, Any]],
+    internal_tools: list[dict[str, Any]] | None,
+    max_tokens: int,
+    temperature: float | None,
+    requested_model: str,
+    agent: Any,
+    middleware: CaudateMiddleware,
+    turn_ctx: Any,
+) -> JSONResponse:
+    """Run system1 + system2 in parallel via DualLLMProvider, score
+    both, return the winner as an Anthropic /v1/messages JSON body.
+    Subscription auth scope is needed so the Anthropic-side brain can
+    use the user's OAuth token (it'd 401 with x-api-key otherwise)."""
+    from api.openai_compat import _dual_brain_arbitrate
+    from core.anthropic_auth import subscription_auth_scope
+    from llm.router import DualLLMProvider
+
+    if not isinstance(agent.llm, DualLLMProvider):
+        # No dual-brain wired — fall back to a single chat call.
+        with subscription_auth_scope():
+            resp = await agent.llm.chat(
+                messages=internal_msgs, tools=internal_tools,
+                max_tokens=max_tokens, temperature=temperature,
+            )
+    else:
+        with subscription_auth_scope():
+            resp = await _dual_brain_arbitrate(
+                llm=agent.llm,
+                messages=internal_msgs, tools=internal_tools,
+                max_tokens=max_tokens, temperature=temperature,
+                middleware=middleware, turn_ctx=turn_ctx,
+            )
+
+    # Feed observer (ones not already covered by _dual_brain_arbitrate's
+    # observe_arbitration call — that records BOTH drafts; we still
+    # need to record the chosen text for the normal observation path).
+    middleware.observe_response_text(turn_ctx, resp.content or "")
+    if getattr(resp, "thinking", None):
+        middleware.observe_thinking(turn_ctx, resp.thinking)
+    for tc in resp.tool_calls or []:
+        middleware.observe_tool_use(turn_ctx, tc.name)
+    middleware.end_turn(turn_ctx, error=False)
+
+    return JSONResponse(_anthropic_response_from_llm_response(
+        resp=resp, requested_model=requested_model,
+    ))
+
+
+async def _anthropic_arbitrate_stream(
+    *,
+    body: dict[str, Any],
+    internal_msgs: list[dict[str, Any]],
+    internal_tools: list[dict[str, Any]] | None,
+    max_tokens: int,
+    temperature: float | None,
+    requested_model: str,
+    agent: Any,
+    middleware: CaudateMiddleware,
+    turn_ctx: Any,
+) -> AsyncIterator[bytes]:
+    """Streaming arbitration: stream system1 LIVE so the user sees
+    text flow within seconds, run system2 in parallel as a buffered
+    background draft for the preference corpus. Avoids the 20+ second
+    blackout that comes from buffering both before any data flows
+    (Claude Code times out on that)."""
+    import asyncio
+    from api.openai_compat import _score_draft
+    from core.anthropic_auth import subscription_auth_scope
+    from llm.router import DualLLMProvider
+
+    msg_id = f"msg_{uuid.uuid4().hex[:24]}"
+
+    def _sse(event_name: str, data: dict[str, Any]) -> bytes:
+        return f"event: {event_name}\ndata: {json.dumps(data)}\n\n".encode()
+
+    # No dual-brain — fall back to a single-brain stream.
+    if not isinstance(agent.llm, DualLLMProvider):
+        try:
+            with subscription_auth_scope():
+                resp = await agent.llm.chat(
+                    messages=internal_msgs, tools=internal_tools,
+                    max_tokens=max_tokens, temperature=temperature,
+                )
+        except Exception as e:
+            logger.exception("anthropic-arbitrate single fallback failed")
+            middleware.end_turn(turn_ctx, error=True)
+            yield _sse("error", {
+                "type": "error",
+                "error": {"type": "api_error", "message": str(e)},
+            })
+            return
+        text = resp.content or ""
+        thinking = getattr(resp, "thinking", "") or ""
+        if not text and thinking:
+            text = f"[thinking — model didn't finish before max_tokens]\n\n{thinking}"
+        middleware.observe_response_text(turn_ctx, text)
+        for tc in resp.tool_calls or []:
+            middleware.observe_tool_use(turn_ctx, tc.name)
+        middleware.end_turn(turn_ctx, error=False)
+        # Single-shot fake stream for the fallback case.
+        yield _sse("message_start", {
+            "type": "message_start",
+            "message": {
+                "id": msg_id, "type": "message", "role": "assistant",
+                "model": requested_model, "content": [],
+                "stop_reason": None, "stop_sequence": None,
+                "usage": {"input_tokens": 0, "output_tokens": 1},
+            },
+        })
+        if text:
+            yield _sse("content_block_start", {
+                "type": "content_block_start", "index": 0,
+                "content_block": {"type": "text", "text": ""},
+            })
+            step = 80
+            for i in range(0, len(text), step):
+                yield _sse("content_block_delta", {
+                    "type": "content_block_delta", "index": 0,
+                    "delta": {"type": "text_delta", "text": text[i:i+step]},
+                })
+            yield _sse("content_block_stop", {
+                "type": "content_block_stop", "index": 0,
+            })
+        yield _sse("message_delta", {
+            "type": "message_delta",
+            "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+            "usage": {"output_tokens": 1},
+        })
+        yield _sse("message_stop", {"type": "message_stop"})
+        return
+
+    # Dual-brain path: stream the FAST-RESPONDING brain live, run the
+    # other in parallel as a buffered background draft. Streaming a
+    # thinking model (Kimi) blocks visible content for tens of seconds
+    # while it reasons — so we route the *visible* stream to the
+    # non-thinking brain when one is available. Both are still
+    # engaged for arbitration.
+    s1, s2 = agent.llm.router.fast, agent.llm.router.slow
+    s1_thinks = any(h in (s1.model or "").lower()
+                    for h in ("kimi", "deepseek", "qwen3", "o1", "o3"))
+    s2_thinks = any(h in (s2.model or "").lower()
+                    for h in ("kimi", "deepseek", "qwen3", "o1", "o3"))
+    if s1_thinks and not s2_thinks:
+        stream_provider, bg_provider = s2, s1
+        stream_label = "slow"
+    else:
+        stream_provider, bg_provider = s1, s2
+        stream_label = "fast"
+
+    # Kick off the background draft.
+    bg_task = asyncio.create_task(
+        _slow_with_subscription_scope(
+            bg_provider, internal_msgs, internal_tools,
+            max_tokens, temperature,
+        )
+    )
+
+    # message_start event — arrives immediately.
+    yield _sse("message_start", {
+        "type": "message_start",
+        "message": {
+            "id": msg_id, "type": "message", "role": "assistant",
+            "model": requested_model, "content": [],
+            "stop_reason": None, "stop_sequence": None,
+            "usage": {"input_tokens": 0, "output_tokens": 1},
+        },
+    })
+
+    stream_text_buf: list[str] = []
+    stream_tool_calls: list[ToolUseBlock] = []
+    text_open = False
+    text_index = 0
+    next_index = 0
+    thinking_open = False
+    thinking_index = 0
+    stop_reason: str | None = None
+
+    try:
+        with subscription_auth_scope():
+            async for event in stream_provider.stream(
+                messages=internal_msgs, tools=internal_tools,
+                max_tokens=max_tokens, temperature=temperature,
+            ):
+                if event.type == "thinking_delta" and event.delta:
+                    middleware.observe_thinking(turn_ctx, event.delta)
+                    if not thinking_open:
+                        yield _sse("content_block_start", {
+                            "type": "content_block_start",
+                            "index": thinking_index,
+                            "content_block": {"type": "thinking", "thinking": ""},
+                        })
+                        thinking_open = True
+                        text_index = thinking_index + 1
+                        next_index = max(next_index, thinking_index + 1)
+                    yield _sse("content_block_delta", {
+                        "type": "content_block_delta",
+                        "index": thinking_index,
+                        "delta": {"type": "thinking_delta", "thinking": event.delta},
+                    })
+                elif event.type == "text_delta" and event.delta:
+                    if thinking_open:
+                        yield _sse("content_block_stop", {
+                            "type": "content_block_stop", "index": thinking_index,
+                        })
+                        thinking_open = False
+                    if not text_open:
+                        yield _sse("content_block_start", {
+                            "type": "content_block_start",
+                            "index": text_index,
+                            "content_block": {"type": "text", "text": ""},
+                        })
+                        text_open = True
+                        next_index = max(next_index, text_index + 1)
+                    stream_text_buf.append(event.delta)
+                    middleware.observe_response_text(turn_ctx, event.delta)
+                    yield _sse("content_block_delta", {
+                        "type": "content_block_delta",
+                        "index": text_index,
+                        "delta": {"type": "text_delta", "text": event.delta},
+                    })
+                elif event.type == "tool_use_end":
+                    if thinking_open:
+                        yield _sse("content_block_stop", {
+                            "type": "content_block_stop", "index": thinking_index,
+                        })
+                        thinking_open = False
+                    idx = next_index
+                    next_index += 1
+                    tc = ToolUseBlock(
+                        id=event.tool_use_id or f"toolu_{uuid.uuid4().hex[:12]}",
+                        name=event.tool_name or "",
+                        input=event.tool_input or {},
+                    )
+                    stream_tool_calls.append(tc)
+                    middleware.observe_tool_use(turn_ctx, tc.name)
+                    yield _sse("content_block_start", {
+                        "type": "content_block_start",
+                        "index": idx,
+                        "content_block": {
+                            "type": "tool_use", "id": tc.id,
+                            "name": tc.name, "input": {},
+                        },
+                    })
+                    yield _sse("content_block_delta", {
+                        "type": "content_block_delta",
+                        "index": idx,
+                        "delta": {
+                            "type": "input_json_delta",
+                            "partial_json": json.dumps(tc.input),
+                        },
+                    })
+                    yield _sse("content_block_stop", {
+                        "type": "content_block_stop", "index": idx,
+                    })
+                elif event.type == "message_stop":
+                    stop_reason = event.stop_reason
+    except Exception as e:
+        logger.exception("stream-leg failed in arbitrate")
+        middleware.end_turn(turn_ctx, error=True)
+        yield _sse("error", {
+            "type": "error",
+            "error": {"type": "api_error", "message": str(e)},
+        })
+        bg_task.cancel()
+        return
+
+    if thinking_open:
+        yield _sse("content_block_stop", {
+            "type": "content_block_stop", "index": thinking_index,
+        })
+    if text_open:
+        yield _sse("content_block_stop", {
+            "type": "content_block_stop", "index": text_index,
+        })
+
+    stop_map = {
+        "stop": "end_turn", "length": "max_tokens",
+        "tool_calls": "tool_use", "tool_use": "tool_use",
+    }
+    anthropic_stop = stop_map.get(stop_reason or "stop", "end_turn")
+    if stream_tool_calls and anthropic_stop == "end_turn":
+        anthropic_stop = "tool_use"
+
+    output_tokens = max(1, len("".join(stream_text_buf).split()))
+    yield _sse("message_delta", {
+        "type": "message_delta",
+        "delta": {"stop_reason": anthropic_stop, "stop_sequence": None},
+        "usage": {"output_tokens": output_tokens},
+    })
+    yield _sse("message_stop", {"type": "message_stop"})
+
+    # Background: wait for bg brain to finish, score both, log
+    # arbitration. User has already seen the streamed brain; this is
+    # purely for the preference corpus.
+    try:
+        bg_resp = await bg_task
+    except Exception as e:
+        logger.warning(f"bg-draft failed: {e}")
+        bg_resp = None
+
+    try:
+        streamed_text = "".join(stream_text_buf)
+        class _FakeResp:
+            content = streamed_text
+            thinking = ""
+            tool_calls = stream_tool_calls
+        streamed_score = _score_draft(_FakeResp())  # type: ignore[arg-type]
+        bg_score = _score_draft(bg_resp) if bg_resp else 0.0
+        if stream_label == "fast":
+            fast_text, fast_score = streamed_text, streamed_score
+            slow_text = bg_resp.content if bg_resp else ""
+            slow_score = bg_score
+        else:
+            slow_text, slow_score = streamed_text, streamed_score
+            fast_text = bg_resp.content if bg_resp else ""
+            fast_score = bg_score
+        winner = ("fast" if fast_score >= slow_score
+                  or abs(fast_score - slow_score) < 0.02
+                  else "slow")
+        middleware.observe_arbitration(
+            turn_ctx,
+            fast_text=fast_text,
+            slow_text=slow_text,
+            fast_score=fast_score,
+            slow_score=slow_score,
+            winner=winner,
+            fast_model=s1.model,
+            slow_model=s2.model,
+        )
+    except Exception as e:
+        logger.debug(f"arbitration log failed: {e}")
+    middleware.end_turn(turn_ctx, error=False)
+
+
+async def _slow_with_subscription_scope(
+    provider, messages, tools, max_tokens, temperature,
+):
+    """Helper: invoke a provider's chat() inside the subscription
+    auth scope (so anthropic/* models work via OAuth) — used by the
+    streaming arbitration path's background slow-draft."""
+    from core.anthropic_auth import subscription_auth_scope
+    with subscription_auth_scope():
+        return await provider.chat(
+            messages=messages, tools=tools,
+            max_tokens=max_tokens, temperature=temperature,
+        )
+
+
+# ---- FastAPI router --------------------------------------------------
+
+
+def build_router() -> APIRouter:
+    """Build the /v1/messages router. Uses a process-wide CognosAgent so
+    state (memory, Caudate, mood) carries across requests."""
+    router = APIRouter()
+
+    # Lazy singleton — first request builds it, subsequent reuse.
+    _agent_box: dict[str, Any] = {"agent": None, "middleware": None}
+
+    def _get_agent():
+        if _agent_box["agent"] is None:
+            from core.agent import CognosAgent
+            agent = CognosAgent(
+                mode="agentic",
+                permission_mode="bypass",  # Claude Code handles permissions
+                personality=True,          # keep mood signal alive for Caudate
+            )
+            _agent_box["agent"] = agent
+            _agent_box["middleware"] = CaudateMiddleware(agent)
+            cau = getattr(agent, "caudate", None)
+            cau_status = (cau.policy.level.label
+                          if cau and cau.policy else "unavailable")
+            logger.info(
+                f"Anthropic-compat singleton agent ready, "
+                f"llm={agent.llm.model}, caudate={cau_status}"
+            )
+        return _agent_box["agent"], _agent_box["middleware"]
+
+    @router.post("/v1/messages")
+    async def messages_endpoint(request: Request):
+        try:
+            body = await request.json()
+        except Exception:
+            raise HTTPException(400, "Invalid JSON body")
+
+        if not isinstance(body, dict):
+            raise HTTPException(400, "Body must be a JSON object")
+
+        try:
+            internal_msgs, internal_tools = _translate_anthropic_to_internal(body)
+        except Exception as e:
+            logger.exception("Anthropic→internal translation failed")
+            raise HTTPException(400, f"Bad message format: {e}")
+
+        # Inject sandbox-awareness hint so the LLM scaffolds new files
+        # into cognos/sandbox/ by default. Idempotent across multi-turn.
+        from core.sandbox_prompt import inject_sandbox_hint
+        internal_msgs = inject_sandbox_hint(internal_msgs)
+
+        max_tokens = int(body.get("max_tokens") or 4096)
+        temperature = body.get("temperature")
+        if temperature is not None:
+            temperature = float(temperature)
+        requested_model = body.get("model") or "cognos"
+        stream = bool(body.get("stream", False))
+
+        agent, middleware = _get_agent()
+        llm = agent.llm
+
+        # ---- Dual-brain arbitration branch (Phase 4 substrate) --------
+        # `cognos-dual-brain` (and the `cognos-collab` alias) trigger
+        # parallel arbitration through both system1 and system2. The
+        # winner is returned in Anthropic format; both drafts are
+        # captured for Caudate's preference-learning corpus. This path
+        # has its own non-passthrough flow because we need to dispatch
+        # both providers in parallel, not just forward upstream.
+        rm_lower = (requested_model or "").lower()
+        if rm_lower in ("cognos-dual-brain", "cognos-collab"):
+            turn_ctx = middleware.begin_turn(
+                internal_msgs, internal_tools,
+                model_source=f"dual[fast={getattr(getattr(llm,'router',None),'fast',type('x',(),{'model':'?'})).model},"
+                             f"slow={getattr(getattr(llm,'router',None),'slow',type('x',(),{'model':'?'})).model}]"
+                if hasattr(llm, "router") else "unknown",
+            )
+            internal_msgs = middleware.maybe_inject_hint(internal_msgs, turn_ctx)
+            if stream:
+                return StreamingResponse(
+                    _anthropic_arbitrate_stream(
+                        body=body,
+                        internal_msgs=internal_msgs,
+                        internal_tools=internal_tools,
+                        max_tokens=max_tokens,
+                        temperature=temperature,
+                        requested_model=requested_model,
+                        agent=agent,
+                        middleware=middleware,
+                        turn_ctx=turn_ctx,
+                    ),
+                    media_type="text/event-stream",
+                )
+            return await _anthropic_arbitrate_nonstream(
+                body=body,
+                internal_msgs=internal_msgs,
+                internal_tools=internal_tools,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                requested_model=requested_model,
+                agent=agent,
+                middleware=middleware,
+                turn_ctx=turn_ctx,
+            )
+
+        # ---- Anthropic passthrough branch -----------------------------
+        # If the resolved primary brain is an Anthropic Claude id, forward
+        # the request to api.anthropic.com using the caller's own auth
+        # header. Caudate observes the response so she still learns from
+        # every turn — just from a stronger teacher.
+        passthrough_model = _resolve_anthropic_model(requested_model)
+        if passthrough_model is not None:
+            turn_ctx = middleware.begin_turn(
+                internal_msgs, internal_tools,
+                model_source=f"anthropic/{passthrough_model}",
+            )
+            internal_msgs_with_hint = middleware.maybe_inject_hint(internal_msgs, turn_ctx)
+            # Build an Anthropic-shape body to forward. We start from the
+            # caller's body so any client-set fields (system, tools,
+            # tool_choice, metadata, top_p, top_k...) survive — we only
+            # override the model id.
+            upstream_body = dict(body)
+            upstream_body["model"] = passthrough_model
+            # DIAG: log the keys + any 'effort' references before strip
+            logger.warning(
+                f"[passthrough pre-strip] model={passthrough_model} "
+                f"top_keys={sorted(upstream_body.keys())} "
+                f"has_effort={'effort' in upstream_body} "
+                f"has_thinking={'thinking' in upstream_body}"
+            )
+            upstream_body = _strip_unsupported_fields(upstream_body, passthrough_model)
+            upstream_body = _maybe_force_thinking(upstream_body)
+            logger.warning(
+                f"[passthrough post-strip] top_keys={sorted(upstream_body.keys())} "
+                f"has_effort={'effort' in upstream_body} "
+                f"has_thinking={'thinking' in upstream_body}"
+            )
+            # If Caudate injected a hint, also inject it into the system
+            # prompt of the upstream body. Not just the internal_msgs.
+            if internal_msgs_with_hint is not internal_msgs:
+                # Find the system content in the hinted internal messages.
+                injected_system = ""
+                for m in internal_msgs_with_hint:
+                    if m.get("role") == "system":
+                        c = m.get("content")
+                        injected_system = c if isinstance(c, str) else (
+                            " ".join(b.get("text", "") for b in c
+                                     if isinstance(b, dict) and b.get("type") == "text")
+                            if isinstance(c, list) else ""
+                        )
+                        break
+                if injected_system:
+                    raw_sys = body.get("system")
+                    if isinstance(raw_sys, str) and raw_sys:
+                        upstream_body["system"] = injected_system
+                    elif isinstance(raw_sys, list):
+                        upstream_body["system"] = [
+                            {"type": "text", "text": injected_system}
+                        ]
+                    else:
+                        upstream_body["system"] = injected_system
+
+            headers = _filter_forward_headers(request)
+            if "authorization" not in {k.lower() for k in headers}:
+                # Fall back to ANTHROPIC_API_KEY env var if the client
+                # didn't send a Bearer token. Common when the caller is
+                # something other than Claude Code.
+                env_key = os.environ.get("ANTHROPIC_API_KEY")
+                if env_key:
+                    headers["x-api-key"] = env_key
+
+            if stream:
+                return StreamingResponse(
+                    _passthrough_anthropic_stream(
+                        upstream_body=upstream_body,
+                        headers=headers,
+                        middleware=middleware,
+                        turn_ctx=turn_ctx,
+                    ),
+                    media_type="text/event-stream",
+                )
+            return await _passthrough_anthropic_nonstream(
+                upstream_body=upstream_body,
+                headers=headers,
+                middleware=middleware,
+                turn_ctx=turn_ctx,
+            )
+
+        # ---- Local LiteLLM path (Ollama / OpenAI / etc.) --------------
+        # Open Caudate's turn — capture state, predict, log, register
+        # tool vocab, extract images, etc.
+        turn_ctx = middleware.begin_turn(
+            internal_msgs, internal_tools,
+            model_source=getattr(llm, "model", "unknown"),
+        )
+
+        # WHISPER+ : prepend Caudate's hint to the system message
+        internal_msgs = middleware.maybe_inject_hint(internal_msgs, turn_ctx)
+
+        if stream:
+            return StreamingResponse(
+                _stream_anthropic_events(
+                    llm=llm,
+                    messages=internal_msgs,
+                    tools=internal_tools,
+                    max_tokens=max_tokens,
+                    temperature=temperature,
+                    requested_model=requested_model,
+                    middleware=middleware,
+                    turn_ctx=turn_ctx,
+                ),
+                media_type="text/event-stream",
+            )
+
+        # Non-streaming
+        try:
+            resp = await llm.chat(
+                messages=internal_msgs,
+                tools=internal_tools,
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+        except Exception as e:
+            logger.exception("LLM call failed")
+            middleware.end_turn(turn_ctx, error=True)
+            raise HTTPException(500, f"LLM error: {e}")
+
+        # Feed the response back into Caudate's observer
+        middleware.observe_response_text(turn_ctx, resp.content or "")
+        if getattr(resp, "thinking", None):
+            middleware.observe_thinking(turn_ctx, resp.thinking)
+        for tc in resp.tool_calls:
+            middleware.observe_tool_use(turn_ctx, tc.name)
+        middleware.end_turn(turn_ctx, error=False)
+
+        return JSONResponse(_build_anthropic_response(
+            thinking=getattr(resp, "thinking", "") or "",
+            text=resp.content,
+            tool_calls=resp.tool_calls,
+            model=requested_model,
+            usage=resp.usage,
+            stop_reason=resp.stop_reason,
+        ))
+
+    @router.get("/v1/models")
+    async def models_endpoint():
+        """Anthropic-compat model list.
+
+        Exposes friendly cognos-* aliases so Claude Code's header shows
+        something honest (e.g. "cognos-dual-brain") rather than the
+        misleading "Sonnet 4.6". Each cognos-* id routes through the
+        normal Cognos LLM stack regardless of which one Claude Code
+        picks — the name is purely cosmetic.
+        """
+        from config import LLM_MODEL
+        from core.settings import Settings
+        s = Settings.load()
+        s1 = s.get("system1") or "(unset)"
+        s2 = s.get("system2") or "(unset)"
+        primary = s.get("model") or LLM_MODEL
+
+        # Friendly cognos-* aliases — what Claude Code will display.
+        # User-facing: ONE model. Caudate decides per-turn whether to
+        # use one brain or both, whether to engage constitutional
+        # critique, which tier, and whether to think — driven by her
+        # tool/tier/think/value head predictions. The other cognos-*
+        # aliases below are *functional* but unlisted — power users can
+        # still hit them directly to force a specific behaviour, but
+        # the default catalog stays clean.
+        cognos_aliases = [
+            ("cognos", f"Cognos · Caudate-driven smart routing · S1={s1} + S2={s2}"),
+        ]
+
+        # Real model ids the user has — for transparency / picker support.
+        real_ids: set[str] = set()
+        for v in (s.get("system1"), s.get("system2"), s.get("model"), LLM_MODEL):
+            if v: real_ids.add(v)
+
+        # Claude id stubs so anyone with a Claude default in their
+        # ~/.claude/settings.json still works.
+        claude_stubs = [
+            "claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5",
+        ]
+
+        # Each model carries BOTH Anthropic-shape and OpenAI-shape
+        # fields so Claude Code AND Open WebUI can both parse this list.
+        # Anthropic clients read `type` + `display_name` + `created_at`;
+        # OpenAI clients read `object` + `created` (Unix int) + `owned_by`.
+        # Carrying both is harmless to either side.
+        ts_iso = "2026-01-01T00:00:00Z"
+        ts_unix = 1735689600  # 2025-01-01T00:00:00Z, intentionally older
+                              # than session ids so picker sorts stable
+        owner = "cognos"
+        def _entry(model_id: str, display: str) -> dict[str, Any]:
+            return {
+                "id": model_id,
+                "type": "model",          # Anthropic shape
+                "object": "model",        # OpenAI shape
+                "display_name": display,
+                "created_at": ts_iso,
+                "created": ts_unix,
+                "owned_by": owner,
+            }
+
+        models: list[dict[str, Any]] = []
+        for name, display in cognos_aliases:
+            models.append(_entry(name, display))
+        for name in sorted(real_ids):
+            models.append(_entry(name, name))
+        for name in claude_stubs:
+            models.append(_entry(name, f"{name} (alias → Cognos)"))
+
+        return {
+            "object": "list",   # OpenAI clients require this
+            "data": models,
+            "first_id": models[0]["id"] if models else None,
+            "last_id":  models[-1]["id"] if models else None,
+            "has_more": False,
+        }
+
+    return router