Connecter Claude Code — Olivares AI

Ingérer les sessions Claude Code depuis la télémétrie OpenTelemetry gen_ai et gouverner ses appels d'outils à un point d'application fermé par défaut.

Claude Code est la source coopérative canonique pour Olivares AI. La plateforme fait deux choses distinctes avec lui, sur deux surfaces aux postures opposées : gardez-les distinctes, car l’une est lecture d’abord et l’autre se place délibérément dans le chemin.

Pour le modèle de source général, voir Connecter une source ; pour le workflow d’application, voir Gouverner et approuver.

Ce qui est observé vs. ce qui est appliqué

Observation (lecture d’abord). Claude Code exporte OpenTelemetry ; le connecteur exécute un récepteur OTLP qui transforme cette télémétrie en arêtes de carte d’accès, échantillons de coûts et identité. Ce chemin ne se place jamais dans le chemin de requête de l’agent — il ingère hors bande. Voir la carte d’accès.
Application (fermée par défaut). Les hooks natifs PreToolUse / PostToolUse de Claude Code peuvent appeler un point d’application de politique (PEP) qui retourne allow / deny / ask avant l’exécution de l’outil. C’est le chemin délibérément interposé que vous activez quand le plan de contrôle doit gouverner l’agent, pas seulement l’observer.

Vous pouvez exécuter l’observation seule. L’application est opt-in et additive.

Observation : ingestion de télémétrie OTel

Le connecteur expose un récepteur OTLP standard (gRPC et HTTP, sur les ports conventionnels OpenTelemetry). Il mappe deux vocabulaires dans le même pipeline :

La propre télémétrie claude_code.* de Claude Code — appels d’outils, sessions, utilisation de modèle par requête, et (sous la beta de tracing) la hiérarchie de sous-agents.
Les conventions sémantiques GenAI d’OpenTelemetry (gen_ai.*), neutres vis-à-vis du fournisseur, de sorte que tout agent instrumenté OTel alimente la même carte d’accès et les mêmes FinOps, pas seulement Claude Code.

À partir de cette télémétrie, le connecteur dérive des arêtes d’accès attribuées par session (quelle session a touché quelle ressource, lecture ou écriture), une arête de topologie pour chaque serveur MCP auquel une session se connecte, et un échantillon de coût par requête. Les serveurs MCP exposent readOnlyHint / destructiveHint en introspection ; ce sont un signal R/RW que la spécification MCP marque comme non fiable, donc le connecteur les traite comme preuve corroborante et n’élève jamais une arête sur un hint seul.

OLIVARES_SOURCES_CONFIG est un document JSON (lu avant le démarrage du moteur) ; kind: "claude" sélectionne ce connecteur. http_addr se lie au loopback par défaut — voir l’avertissement ci-dessous.

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

Le profil GenAI est opt-in

Les conventions sémantiques gen_ai.* sont encore en statut Development, donc leur mappage vers les coûts et arêtes est un opt-in explicite. Définissez le semconv_opt_in du connecteur au propre token de la spécification (miroir de OTEL_SEMCONV_STABILITY_OPT_IN) ; sans cela, un enregistrement gen_ai.* alimente toujours le watchdog de vivacité mais n’est pas chiffré. Le profil lit à la fois les noms d’attributs actuels et dépréciés que les vrais frameworks émettent encore, accepte les données sur les traces ou les logs, et déduplique une opération qui arrive sur les deux pour que le FinOps ne soit pas double-facturé. Le contenu des messages n’est jamais lu — les clés de contenu servent uniquement à détecter quel dialecte un émetteur parle.

Données minimales par défaut

Le connecteur ne retient que la télémétrie structurelle — sessions, identités, noms d’outils, mode R/RW, timing — même si le client est configuré pour émettre du texte de prompt ou des corps d’outils. Une entrée d’outil brute est réduite à une référence de ressource expurgée avant de devenir une observation. Retenir toute catégorie de contenu est un opt-in séparé et audité. Voir permis vs. observé et fidélité pour comment la couverture et l’attribution sont graduées.

:::caution Le récepteur coopératif est non authentifié et se lie au loopback par défaut. Quiconque peut atteindre le socket peut falsifier la télémétrie, ne l’exposez donc pas sur un réseau partagé. Les agents hors-hôte appartiennent au backstop noyau non coopératif, pas à un port OTLP public. :::

Application : le PEP via hook

Pour gouverner — pas seulement observer — câblez les hooks de Claude Code au PEP. Le hook PreToolUse de l’agent fait transiter chaque appel d’outil vers une commande de hook gérée, qui le transfère au PEP et relaie le verdict. Le connecteur ne détient que le protocole filaire du hook et les défauts fermés par défaut ; la décision réelle est déléguée à travers un point d’accès que le plan de contrôle implémente contre un PDP en direct (Cedar/ABAC), le plan d’identité ferme, les approbations humain-dans-la-boucle et le registre inviolable.

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

Ce que le PEP peut retourner, vérifié contre le contrat de hook de Claude Code :

PreToolUse — allow, deny, ou ask, avec une updatedInput gouvernée optionnelle (réduire un chemin, ajouter --dry-run, rediriger un fetch). La précédence est deny sur ask sur allow.
PostToolUse — Claude Code n’a pas de champ de réécriture de sortie, donc un hook PostToolUse ne peut que bloquer le traitement ultérieur sur un résultat signalé par la politique. Le connecteur ne prétend pas réécrire un résultat que le modèle a déjà vu ; ce qu’il expurge est ce que lui retient et audite.

Le fermé par défaut est total

S’interposer dans le chemin de données est un risque asymétrique, donc chaque mode d’échec échoue fermé, jamais ouvert : un décideur manquant, une erreur de décision (PDP inaccessible, identité non résolue, une approbation qui n’a pas pu s’ouvrir), ou une charge utile de hook malformée retournent tous un deny propre. La valeur zéro du verdict est elle-même un deny. Un ask route vers une approbation gouvernée ; l’approbation est liée à un hash de plan de l’appel d’outil exact, donc elle ne peut pas être réutilisée pour autoriser un appel différent (anti-TOCTOU).

En production, le hook est livré dans le tier entreprise managed-settings de Claude Code avec managed-hooks-only activé, de sorte qu’un développeur ne peut pas le désactiver ou le remplacer depuis un fichier de settings de moindre précédence. Les hints d’identité estampés sur la requête affinent l’attribution ; le principal faisant autorité est le porteur que le décideur résout, et une politique qui exige une identité ferme refuse tout ce qu’elle ne peut attribuer qu’approximativement.

Un mode local plus léger

Le connecteur supporte aussi une politique d’application locale in-process évaluée sur le chemin chaud du hook sans aller-retour vers le moteur — de sorte qu’un plan de contrôle lent ou inaccessible ne bloque jamais l’appel d’outil d’un développeur. C’est opt-in : sans règles configurées, les hooks sont observés et jamais contrôlés. C’est la posture coopérative par défaut ; le PEP gouverné ci-dessus est la posture opposée que vous activez quand le plan de contrôle doit être le décideur.

Anti-évasion

Parce que le chemin d’observation est coopératif, le connecteur surveille une session qui arrête d’émettre OTel alors que ses hooks continuent de tirer — la signature d’un agent qui a désactivé son exporteur en cours de session tout en continuant d’agir. Notez ce qu’il ne fait pas : un agent terminé devient silencieux, et le silence seul n’est jamais signalé. La vérité terrain pour l’activité véritablement non coopérative est le backstop noyau/eBPF, pas cette heuristique.

Air-gap : ce qui reste chez vous et ce qui ne reste pas

Le plan de contrôle fonctionne dans votre propre infrastructure et peut fonctionner air-gappé — les données de gouvernance et d’observation (arêtes d’accès, décisions, audit, échantillons de coûts) ne quittent jamais votre périmètre. Le récepteur OTLP et le PEP du hook sont des sockets locaux ; le moteur ne phone pas à la maison.

Une réserve honnête : l’inférence Claude n’est jamais air-gappée. Claude Code envoie toujours ses prompts à l’API d’Anthropic (directement ou via Bedrock, Vertex ou Foundry) pour obtenir une réponse. Air-gapper le plan de contrôle garde les données de gouvernance de votre environnement chez vous ; cela ne déplace pas le modèle sur site. Seuls les modèles véritablement auto-hébergeables (par exemple via vLLM/Ollama) fonctionnent entièrement hors ligne. Voir qu’est-ce qu’Olivares AI et transparence et limites.

Étapes suivantes

Gouverner et approuver — rédiger la politique et la boucle ask → approbation humaine que le PEP applique.
La carte d’accès — ce qu’alimentent les arêtes observées.
Gouvernance Claude Code — l’aperçu produit de ce chemin.