Collegare Claude Code

Claude Code e la sorgente cooperativa canonica per Olivares AI. La piattaforma fa due cose distinte con esso, su due superfici con posture opposte: tienile chiare, perché una e lettura prima di tutto e l’altra si interpone deliberatamente nel percorso.

Per il modello sorgente generale vedi Collegare una sorgente; per il workflow di enforcement vedi Governare e approvare.

Cosa viene osservato vs cosa viene applicato

• Osservazione (lettura prima di tutto). Claude Code esporta OpenTelemetry; il connettore esegue un ricevitore OTLP che trasforma quella telemetria in archi della mappa degli accessi, campioni di costo e identità. Questo percorso non si interpone mai nel percorso delle richieste dell’agente — acquisisce fuori banda. Vedi la mappa degli accessi.
• Enforcement (deny-closed). Gli hook nativi PreToolUse / PostToolUse di Claude Code possono chiamare un punto di enforcement delle policy (PEP) che restituisce allow / deny / ask prima che il tool venga eseguito. Questo è il percorso deliberatamente interposto che attivi quando il piano di controllo deve governare l’agente, non solo osservarlo.

Puoi eseguire l’osservazione da sola. L’enforcement e opt-in e additivo.

Osservazione: ingestione telemetria OTel

Il connettore espone un ricevitore OTLP standard (gRPC e HTTP, sulle porte convenzionali OpenTelemetry). Mappa due vocabolari nella stessa pipeline:

• La telemetria propria claude_code.* di Claude Code — chiamate tool, sessioni, utilizzo del modello per richiesta, e (sotto la beta del tracing) la gerarchia dei subagent.
• Le convenzioni semantiche OpenTelemetry GenAI vendor-neutral (gen_ai.*), cosi qualsiasi agente strumentato con OTel alimenta la stessa mappa degli accessi e FinOps, non solo Claude Code.

Da quella telemetria il connettore deriva archi di accesso attribuiti alla sessione (quale sessione ha toccato quale risorsa, in lettura o scrittura), un arco di topologia per ogni server MCP a cui una sessione si connette, e un campione di costo per richiesta. I server MCP espongono l’introspezione readOnlyHint / destructiveHint; queste sono un segnale R/RW che la specifica MCP marca come non attendibile, quindi il connettore le tratta come evidenza corroborante e non promuove mai un arco solo sulla base di un hint.

OLIVARES_SOURCES_CONFIG e un documento JSON (letto prima dell’avvio del motore); kind: "claude" seleziona questo connettore. http_addr si collega al loopback di default — vedi l’avviso sotto.

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

Il profilo GenAI e opt-in

Le convenzioni semantiche gen_ai.* sono ancora in stato Development, quindi mapparle a costi e archi e un opt-in esplicito. Imposta il semconv_opt_in del connettore al token proprio della specifica (rispecchiando OTEL_SEMCONV_STABILITY_OPT_IN); con esso disattivato, un record gen_ai.* alimenta comunque il watchdog di liveness ma non viene contabilizzato. Il profilo legge sia i nomi di attributo correnti che quelli deprecati che i framework reali ancora emettono, accetta i dati su trace o log, e de-duplica un’operazione che arriva su entrambi cosi il FinOps non viene fatturato doppio. Il contenuto dei messaggi non viene mai letto — le chiavi di contenuto vengono usate solo per rilevare quale dialetto usa un emettitore.

Dati minimi per default

Il connettore conserva solo telemetria strutturale — sessioni, identità, nomi dei tool, modalità R/RW, timing — anche se il client è configurato per emettere testo dei prompt o corpi dei tool. Un input raw del tool viene ridotto a un riferimento risorsa redatto prima di diventare un’osservazione. Conservare qualsiasi categoria di contenuto e un opt-in separato è registrato. Vedi permesso vs osservato e fedeltà per come copertura e attribuzione sono a livelli.

:::caution Il ricevitore cooperativo e non autenticato e si collega al loopback di default. Chiunque possa raggiungere il socket può falsificare la telemetria, quindi non esporlo su una rete condivisa. Gli agenti fuori host appartengono al backstop kernel non cooperativo, non a una porta OTLP pubblica. :::

Enforcement: il PEP via hook

Per governare — non solo osservare — collega gli hook di Claude Code al PEP. L’hook PreToolUse dell’agente invia ogni tool-call a un comando hook gestito, che lo inoltra al PEP e ritrasmette il verdetto. Il connettore possiede solo il protocollo wire dell’hook e i default deny-closed; la decisione effettiva viene delegata attraverso un seam che il piano di controllo implementa contro un PDP live (Cedar/ABAC), il piano di identità firm, le approvazioni human-in-the-loop e il registro a prova di manomissione.

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

Ciò che il PEP può restituire, verificato rispetto al contratto hook di Claude Code:

• PreToolUse — allow, deny o ask, con un opzionale updatedInput rewrite governato (restringere un percorso, aggiungere --dry-run, reindirizzare un fetch). La precedenza e deny su ask su allow.
• PostToolUse — Claude Code non ha un campo di riscrittura dell’output, quindi un hook PostToolUse può solo bloccare ulteriore elaborazione su un risultato segnalato dalla policy. Il connettore non finge di riscrivere un risultato che il modello ha già visto; ciò che redige e ciò che esso conserva e registra.

Deny-closed e totale

Interporsi nel percorso dei dati e un rischio asimmetrico, quindi ogni modalità di errore fallisce chiusa, mai aperta: un decisore mancante, un errore di decisione (PDP irraggiungibile, identità non risolta, un’approvazione che non ha potuto aprirsi), o un payload hook malformato restituiscono tutti una negazione pulita. Il valore zero del verdetto è esso stesso una negazione. Un ask viene instradato a un’approvazione governata; l’approvazione è vincolata a un hash del piano dell’esatta tool-call, quindi non può essere riusata per autorizzare una chiamata diversa (anti-TOCTOU).

In produzione l’hook viene distribuito nel livello enterprise managed-settings di Claude Code con managed-hooks-only abilitato, cosi uno sviluppatore non può disabilitarlo o sostituirlo da un file di impostazioni a precedenza inferiore. Gli hint di identità stampati sulla richiesta raffinano l’attribuzione; il principal autorevole e il bearer che il decisore risolve, e una policy che richiede identità firm nega qualsiasi cosa possa attribuire solo in modo approssimativo.

Una modalità più leggera, locale

Il connettore supporta anche una policy di enforcement locale, in-process, valutata nel percorso caldo dell’hook senza round-trip al motore — cosi un piano di controllo lento o irraggiungibile non blocca mai la tool-call di uno sviluppatore. E opt-in: senza regole configurate, gli hook vengono osservati e mai bloccati. Questa è la postura cooperativa per default; il PEP governato sopra e la postura opposta a cui passi quando il piano di controllo deve essere il decisore.

Anti-evasione

Poiché il percorso di osservazione è cooperativo, il connettore sorveglia una sessione che smette di emettere OTel mentre i suoi hook continuano a scattare — la firma di un agente che ha disabilitato il suo esportatore a meta sessione continuando ad agire. Nota cosa non fa: un agente terminato va in silenzio, e il silenzio da solo non viene mai segnalato. La ground truth per attività genuinamente non cooperativa e il backstop kernel/eBPF, non questa euristica.

Air-gap: cosa resta a casa e cosa no

Il piano di controllo gira all’interno della tua infrastruttura e può funzionare air-gapped — i dati di governance e osservazione (archi di accesso, decisioni, audit, campioni di costo) non lasciano mai il tuo perimetro. Il ricevitore OTLP e il PEP dell’hook sono socket locali; il motore non chiama casa.

Un avvertimento onesto: l’inferenza di Claude non è mai air-gapped. Claude Code invia comunque i suoi prompt all’API di Anthropic (direttamente o tramite Bedrock, Vertex o Foundry) per ottenere una risposta. L’air-gapping del piano di controllo tiene i dati di governance del tuo estate a casa; non sposta il modello on-prem. Solo i modelli genuinamente self-hostabili (ad esempio tramite vLLM/Ollama) funzionano completamente offline. Vedi cos’è Olivares AI e trasparenza e limiti.

Prossimi passi

• Governare e approvare — scrivere la policy e il ciclo ask -> approvazione umana che il PEP applica.
• La mappa degli accessi — ciò che alimentano gli archi osservati.
• Governance Claude Code — la panoramica prodotto di questo percorso.