Ligar Claude Code

O Claude Code e a fonte cooperativa canonica para o Olivares AI. A plataforma faz duas coisas distintas com ele, em duas superficies com posturas opostas: mantenha-as claras, porque uma e leitura-primeiro e a outra deliberadamente coloca-se no caminho.

Para o modelo geral de fontes veja Ligar uma fonte; para o fluxo de aplicação veja Governar e aprovar.

O que é observado vs. o que é aplicado

• Observação (leitura-primeiro). O Claude Code exporta OpenTelemetry; o conector executa um recetor OTLP que transforma essa telemetria em arestas de mapa de acesso, amostras de custo e identidade. Este caminho nunca se coloca no caminho do pedido do agente — ingere fora de banda. Veja o mapa de acesso.
• Aplicação (deny-closed). Os hooks nativos PreToolUse / PostToolUse do Claude Code podem chamar um ponto de aplicação de políticas (PEP) que retorna allow / deny / ask antes da ferramenta executar. Este e o caminho deliberadamente interposto que ativa quando o plano de controlo deve governar o agente, não apenas observa-lo.

Pode executar observação sozinha. A aplicação e opt-in e aditiva.

Observação: ingestão de telemetria OTel

O conector expoe um recetor OTLP padrão (gRPC e HTTP, nas portas convencionais OpenTelemetry). Mapeia dois vocabularios no mesmo pipeline:

• A telemetria própria do Claude Code claude_code.* — chamadas de ferramenta, sessões, uso de modelo por pedido, e (sob o beta de tracing) a hierarquia de subagentes.
• As convencoes semanticas GenAI do OpenTelemetry neutras em relação a fornecedor (gen_ai.*), para que qualquer agente instrumentado com OTel alimente o mesmo mapa de acesso e FinOps, não apenas Claude Code.

A partir dessa telemetria o conector deriva arestas de acesso atribuidas a sessão (qual sessão tocou em qual recurso, leitura ou escrita), uma aresta de topologia para cada servidor MCP a que uma sessão se liga, e uma amostra de custo por pedido. Os servidores MCP expoem introspeção readOnlyHint / destructiveHint; esses são um sinal R/RW que a especificação MCP marca como não confiável, portanto o conector trata-os como evidência corroborante e nunca eleva uma aresta apenas com base numa dica.

OLIVARES_SOURCES_CONFIG e um documento JSON (lido antes do motor arrancar); kind: "claude" seleciona este conector. http_addr vincula loopback por defeito — veja o aviso abaixo.

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

O perfil GenAI e opt-in

As convencoes semanticas gen_ai.* ainda estão em estado Development, portanto mapea-las para custo e arestas e um opt-in explicito. Defina semconv_opt_in do conector para o token da própria especificação (espelhando OTEL_SEMCONV_STABILITY_OPT_IN); com ele desligado, um registo gen_ai.* ainda alimenta o watchdog de liveness mas não é contabilizado. O perfil le tanto os nomes de atributos atuais como os depreciados que frameworks reais ainda emitem, aceita os dados em traces ou logs, e de-duplica uma operação que chega em ambos para que FinOps não seja duplamente faturado. O conteúdo de mensagens nunca e lido — as chaves de conteúdo são usadas apenas para detetar que dialeto um emissor fala.

Dados mínimos por defeito

O conector retém apenas telemetria estrutural — sessões, identidades, nomes de ferramentas, modo R/RW, timing — mesmo que o cliente esteja configurado para emitir texto de prompt ou corpos de ferramentas. Um input bruto de ferramenta e reduzido a uma referência de recurso redigida antes de se tornar uma observação. Reter qualquer categoria de conteúdo e um opt-in separado e auditado. Veja permitido vs. observado e fidelidade para como cobertura e atribuição são escalonadas.

:::caution O recetor cooperativo e não autenticado e vincula loopback por defeito. Qualquer pessoa que alcance o socket pode forjar telemetria, portanto não o exponha numa rede partilhada. Agentes fora do host pertencem ao backstop não cooperativo de kernel, não a uma porta OTLP pública. :::

Aplicação: o PEP de hooks

Para governar — não apenas observar — ligue os hooks do Claude Code ao PEP. O hook PreToolUse do agente encaminha cada chamada de ferramenta para um comando de hook gerido, que a envia ao PEP e retransmite o veredicto. O conector possui apenas o protocolo de comunicação do hook e os valores predefinidos deny-closed; a decisão real e delegada através de um ponto que o plano de controlo implementa contra um PDP ativo (Cedar/ABAC), o plano de identidade firme, aprovações human-in-the-loop e o registo a prova de adulteracao.

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

O que o PEP pode retornar, verificado contra o contrato de hooks do Claude Code:

• PreToolUse — allow, deny ou ask, com uma reescrita governada opcional de updatedInput (restringir um caminho, adicionar --dry-run, redirecionar um fetch). A precedência e deny sobre ask sobre allow.
• PostToolUse — O Claude Code não tem campo de reescrita de saída, portanto um hook PostToolUse só pode bloquear processamento posterior num resultado sinalizado por política. O conector não finge reescrever um resultado que o modelo já viu; o que redige e o que ele retém e audita.

Deny-closed e total

Interpor-se no caminho de dados e risco assimetrico, portanto cada modo de falha falha fechado, nunca aberto: um decisor em falta, um erro de decisão (PDP inalcançável, identidade não resolvida, uma aprovação que não conseguiu abrir), ou um payload de hook malformado todos retornam uma negação limpa. O valor zero do veredicto e em si uma negação. Um ask encaminha para uma aprovação governada; a aprovação e vinculada a um hash de plano da chamada de ferramenta exata, portanto não pode ser reutilizada para autorizar uma chamada diferente (anti-TOCTOU).

Em produção o hook e distribuído no nível de managed-settings empresarial do Claude Code com managed-hooks-only ativado, portanto um programador não pode desativa-lo ou substitui-lo de um ficheiro de definições de menor precedência. As dicas de identidade carimbadas no pedido refinam a atribuição; o principal autoritativo e o bearer que o decisor resolve, e uma política que requer identidade firme nega qualquer coisa que só possa atribuir aproximadamente.

Um modo local mais leve

O conector também suporta uma política de aplicação local, em processo, avaliada no caminho quente do hook com nenhuma viagem de ida e volta ao motor — portanto um plano de controlo lento ou inalcançável nunca bloqueia a chamada de ferramenta de um programador. E opt-in: sem regras configuradas, os hooks são observados e nunca bloqueados. Esta e a postura cooperativa-por-defeito; o PEP governado acima e a postura oposta para a qual muda quando o plano de controlo deve ser o decisor.

Anti-evasao

Como o caminho de observação e cooperativo, o conector vigia uma sessão que para de emitir OTel enquanto os seus hooks ainda estão a disparar — a assinatura de um agente que desativou o seu exportador a meio da sessão enquanto continua a agir. Note o que não faz: um agente terminado fica silencioso, e silencio sozinho nunca e sinalizado. A verdade fundamental para atividade genuinamente não cooperativa e o backstop de kernel/eBPF, não esta heurística.

Air-gap: o que fica em casa e o que não fica

O plano de controlo funciona dentro da sua própria infraestrutura e pode funcionar air-gapped — os dados de governança e observação (arestas de acesso, decisões, auditoria, amostras de custo) nunca saem do seu perímetro. O recetor OTLP e o PEP de hooks são sockets locais; o motor não telefona para casa.

Uma ressalva honesta: a inferência Claude nunca e air-gapped. O Claude Code ainda envia os seus prompts para a API da Anthropic (diretamente ou via Bedrock, Vertex ou Foundry) para obter uma resposta. Air-gap do plano de controlo mantém os dados de governança do seu ambiente em casa; não move o modelo para on-prem. Apenas modelos genuinamente auto-hospedaveis (por exemplo via vLLM/Ollama) funcionam totalmente offline. Veja o que é o Olivares AI e honestidade e limites.

Proximos passos

• Governar e aprovar — escrever a política e o ciclo ask → aprovação humana que o PEP aplica.
• O mapa de acesso — o que as arestas observadas alimentam.
• Governança de Claude Code — a vista geral de produto deste caminho.