Conectar Claude Code — Olivares AI

Ingesta las sesiones de Claude Code a partir de la telemetría gen_ai de OpenTelemetry y gobierna sus llamadas a herramientas en un punto de aplicación deny-closed, manteniendo los datos de gobierno on-prem

Claude Code es la fuente cooperativa canónica de Olivares AI. La plataforma hace dos cosas distintas con ella, sobre dos superficies con posturas opuestas: no las confundas, porque una es read-first y la otra se sitúa deliberadamente en la ruta.

Para el modelo de fuente general, consulta Conectar una fuente; para el flujo de aplicación, consulta Gobernar y aprobar.

Qué se observa frente a qué se aplica

Observación (read-first). Claude Code exporta OpenTelemetry; el conector ejecuta un receptor OTLP que convierte esa telemetría en aristas del mapa de accesos, muestras de coste e identidad. Esta ruta nunca se sitúa en la ruta de petición del agente: ingesta fuera de banda. Consulta el mapa de accesos.
Aplicación (deny-closed). Los hooks nativos PreToolUse / PostToolUse de Claude Code pueden llamar a un punto de aplicación de políticas (PEP) que devuelve allow / deny / ask antes de que la herramienta se ejecute. Esta es la ruta deliberadamente interpuesta que activas cuando el control plane debe gobernar al agente, no solo observarlo.

Puedes ejecutar la observación por sí sola. La aplicación es opt-in y aditiva.

Observación: ingesta de telemetría OTel

El conector expone un receptor OTLP estándar (gRPC y HTTP, en los puertos convencionales de OpenTelemetry). Mapea dos vocabularios al mismo pipeline:

La telemetría propia de Claude Code claude_code.* — llamadas a herramientas, sesiones, uso de modelo por petición y (bajo la beta de tracing) la jerarquía de subagentes.
Las convenciones semánticas GenAI de OpenTelemetry, neutrales respecto al proveedor (gen_ai.*), de modo que cualquier agente instrumentado con OTel alimenta el mismo mapa de accesos y FinOps, no solo Claude Code.

A partir de esa telemetría, el conector deriva aristas de acceso atribuidas a la sesión (qué sesión tocó qué recurso, en lectura o escritura), una arista de topología por cada servidor MCP al que se conecta una sesión, y una muestra de coste por petición. Los servidores MCP exponen introspección readOnlyHint / destructiveHint; esas son una señal R/RW que la especificación MCP marca como no fiable, así que el conector las trata como evidencia corroborante y nunca promociona una arista basándose en una hint por sí sola.

OLIVARES_SOURCES_CONFIG es un documento JSON (leído antes de que arranque el motor); kind: "claude" selecciona este conector. http_addr enlaza loopback por defecto — consulta la advertencia más abajo.

{
  "sources": [
    {
      "name": "claude",
      "kind": "claude",
      "tenant": "<tenant-ref>",
      "config": {
        "enable_http": "true",
        "http_addr": "127.0.0.1:4318"
      }
    }
  ]
}

El perfil GenAI es opt-in

Las convenciones semánticas gen_ai.* siguen estando en estado Development, así que mapearlas a coste y aristas es un opt-in explícito. Ajusta el semconv_opt_in del conector al propio token de la especificación (reflejando OTEL_SEMCONV_STABILITY_OPT_IN); con él desactivado, un registro gen_ai.* sigue alimentando el watchdog de liveness pero no se contabiliza su coste. El perfil lee tanto los nombres de atributo actuales como los deprecados que los frameworks reales todavía emiten, acepta los datos en trazas o logs, y deduplica una operación que llega por ambos para que FinOps no la facture por duplicado. El contenido de los mensajes nunca se lee — las claves de contenido se usan solo para detectar qué dialecto habla un emisor.

Datos mínimos por defecto

El conector retiene únicamente telemetría estructural — sesiones, identidades, nombres de herramientas, modo R/RW, timing — incluso si el cliente está configurado para emitir el texto del prompt o los cuerpos de las herramientas. Una entrada de herramienta en bruto se reduce a una referencia de recurso redactada antes de convertirse en una observación. Retener cualquier categoría de contenido es un opt-in aparte y auditado. Consulta permitido frente a observado y fidelidad para ver cómo se escalonan la cobertura y la atribución.

:::caution El receptor cooperativo está sin autenticar y enlaza loopback por defecto. Cualquiera que pueda alcanzar el socket puede falsificar telemetría, así que no lo expongas en una red compartida. Los agentes fuera del host pertenecen al backstop no cooperativo del kernel, no a un puerto OTLP público. :::

Aplicación: el PEP de hooks

Para gobernar — no solo observar — conecta los hooks de Claude Code al PEP. El hook PreToolUse del agente canaliza cada llamada a herramienta a un comando de hook gestionado, que la reenvía al PEP y devuelve el veredicto. El conector posee únicamente el protocolo de cable de los hooks y los valores por defecto deny-closed; la decisión real se delega a través de una costura que el control plane implementa contra un PDP vivo (Cedar/ABAC), el plano de identidad firme, las aprobaciones human-in-the-loop y el ledger a prueba de manipulaciones.

Claude Code ──PreToolUse hook──▶ managed hook command ──HTTP──▶ governed PEP
   (agent)        (stdin JSON)                                  (loopback)
                                                                    │
              allow │ deny │ ask  ◀──── governed decision ──────────┘
            (+ updatedInput rewrite)   deny-closed on any failure

Lo que el PEP puede devolver, verificado contra el contrato de hooks de Claude Code:

PreToolUse — allow, deny o ask, con una reescritura gobernada opcional updatedInput (estrechar una ruta, añadir --dry-run, redirigir un fetch). La precedencia es deny sobre ask sobre allow.
PostToolUse — Claude Code no tiene campo de reescritura de salida, así que un hook PostToolUse solo puede bloquear el procesamiento posterior sobre un resultado marcado por política. El conector no pretende reescribir un resultado que el modelo ya vio; lo que redacta es lo que él retiene y audita.

Deny-closed es total

Interponerse en la ruta de datos es un riesgo asimétrico, así que todo modo de fallo falla cerrado, nunca abierto: un decisor ausente, un error de decisión (PDP inalcanzable, identidad no resuelta, una aprobación que no pudo abrirse) o un payload de hook malformado devuelven todos un deny limpio. El valor cero del veredicto es en sí mismo un deny. Un ask se enruta a una aprobación gobernada; la aprobación está ligada a un hash de plan de la llamada a herramienta exacta, de modo que no puede reutilizarse para autorizar una llamada distinta (anti-TOCTOU).

En producción, el hook se distribuye en el tier de managed-settings enterprise de Claude Code con managed-hooks-only activado, de modo que un desarrollador no puede desactivarlo ni reemplazarlo desde un fichero de settings de menor precedencia. Las hints de identidad estampadas en la petición refinan la atribución; el principal autoritativo es el bearer que resuelve el decisor, y una política que exige identidad firme deniega cualquier cosa que solo pueda atribuir de forma aproximada.

Un modo más ligero y local

El conector también admite una política de aplicación local, in-process, evaluada en la ruta caliente del hook sin ida y vuelta al motor — de modo que un control plane lento o inalcanzable nunca atasque la llamada a herramienta de un desarrollador. Es opt-in: sin reglas configuradas, los hooks se observan y nunca se gatean. Esta es la postura cooperativa-por-defecto; el PEP gobernado de arriba es la postura opuesta a la que cambias cuando el control plane debe ser quien tome las decisiones.

Anti-evasión

Como la ruta de observación es cooperativa, el conector vigila si una sesión deja de emitir OTel mientras sus hooks siguen disparándose — la firma de un agente que desactivó su exporter a mitad de sesión mientras seguía actuando. Fíjate en lo que no hace: un agente que ha terminado se queda en silencio, y el silencio por sí solo nunca se marca. La ground truth de la actividad genuinamente no cooperativa es el backstop de kernel/eBPF, no esta heurística.

Air-gap: qué se queda en casa y qué no

El control plane se ejecuta dentro de tu propia infraestructura y puede ejecutarse air-gapped — los datos de gobierno y observación (aristas de acceso, decisiones, auditoría, muestras de coste) nunca salen de tu perímetro. El receptor OTLP y el PEP de hooks son sockets locales; el motor no llama a casa.

Una salvedad honesta: la inferencia de Claude nunca está air-gapped. Claude Code sigue enviando sus prompts a la API de Anthropic (directamente o vía Bedrock, Vertex o Foundry) para obtener una respuesta. Hacer air-gap del control plane mantiene en casa los datos de gobierno de tu estate; no traslada el modelo on-prem. Solo los modelos genuinamente autoalojables (por ejemplo vía vLLM/Ollama) se ejecutan totalmente offline. Consulta qué es Olivares AI y honestidad y límites.

Próximos pasos

Gobernar y aprobar — redacta la política y el bucle ask → aprobación humana que el PEP aplica.
El mapa de accesos — qué alimentan las aristas observadas.
Gobierno de Claude Code — la visión general de producto de esta ruta.