Skip to content

Guides

Connect Claude Code

Ingest Claude Code sessions from OpenTelemetry gen_ai telemetry and govern its tool-calls at a deny-closed enforcement point, with governance data kept on-prem

Claude Code is the canonical cooperative source for Olivares AI. The platform does two distinct things with it, on two surfaces with opposite postures: keep them straight, because one is read-first and the other deliberately sits in the path.

For the general source model see Connect a source; for the enforcement workflow see Govern and approve.

What is observed vs. what is enforced

  • Observation (read-first). Claude Code exports OpenTelemetry; the connector runs an OTLP receiver that turns that telemetry into access-map edges, cost samples and identity. This path never sits in the agent’s request path — it ingests out of band. See the access map.
  • Enforcement (deny-closed). Claude Code’s native PreToolUse / PostToolUse hooks can call a policy enforcement point (PEP) that returns allow / deny / ask before the tool runs. This is the deliberately-interposed path you turn on when the control plane must govern the agent, not just watch it.

You can run observation alone. Enforcement is opt-in and additive.

Observation: OTel telemetry ingest

The connector exposes a standard OTLP receiver (gRPC and HTTP, on the conventional OpenTelemetry ports). It maps two vocabularies into the same pipeline:

  • Claude Code’s own claude_code.* telemetry — tool calls, sessions, per-request model usage, and (under the tracing beta) the subagent hierarchy.
  • The vendor-neutral OpenTelemetry GenAI semantic conventions (gen_ai.*), so any OTel-instrumented agent feeds the same access map and FinOps, not just Claude Code.

From that telemetry the connector derives session-attributed access edges (which session touched which resource, read or write), a topology edge for each MCP server a session connects to, and a per-request cost sample. MCP servers expose readOnlyHint / destructiveHint introspection; those are an R/RW signal the MCP spec marks untrusted, so the connector treats them as corroborating evidence and never upgrades an edge on a hint alone.

OLIVARES_SOURCES_CONFIG is a JSON document (read before the engine starts); kind: "claude" selects this connector. http_addr binds loopback by default — see the warning below.

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

The GenAI profile is opt-in

The gen_ai.* semantic conventions are still Development-status, so mapping them to cost and edges is an explicit opt-in. Set the connector’s semconv_opt_in to the spec’s own token (mirroring OTEL_SEMCONV_STABILITY_OPT_IN); with it off, a gen_ai.* record still feeds the liveness watchdog but is not costed. The profile reads both the current and the deprecated attribute names that real frameworks still emit, accepts the data on traces or logs, and de-duplicates an operation that arrives on both so FinOps is not double-billed. Message content is never read — content keys are used only to detect which dialect an emitter speaks.

Minimal data by default

The connector retains only structural telemetry — sessions, identities, tool names, R/RW mode, timing — even if the client is configured to emit prompt text or tool bodies. A raw tool input is reduced to a redacted resource reference before it becomes an observation. Retaining any content category is a separate, audited opt-in. See permitted vs. observed and fidelity for how coverage and attribution are tiered.

:::caution The cooperative receiver is unauthenticated and binds loopback by default. Anyone who can reach the socket can forge telemetry, so do not expose it on a shared network. Off-host agents belong on the non-cooperative kernel backstop, not on a public OTLP port. :::

Enforcement: the hook PEP

To govern — not just observe — wire Claude Code’s hooks to the PEP. The agent’s PreToolUse hook pipes each tool-call to a managed hook command, which forwards it to the PEP and relays the verdict back. The connector owns only the hook wire protocol and the deny-closed defaults; the actual decision is delegated through a seam the control plane implements against a live PDP (Cedar/ABAC), the firm-identity plane, human-in-the-loop approvals and the tamper-evident ledger.

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

What the PEP can return, verified against Claude Code’s hook contract:

  • PreToolUse — allow, deny, or ask, with an optional governed updatedInput rewrite (narrow a path, add --dry-run, redirect a fetch). Precedence is deny over ask over allow.
  • PostToolUse — Claude Code has no output-rewrite field, so a PostToolUse hook can only block further processing on a policy-flagged result. The connector does not pretend to rewrite a result the model already saw; what it redacts is what it retains and audits.

Deny-closed is total

Interposing in the data path is asymmetric risk, so every failure mode fails closed, never open: a missing decider, a decision error (PDP unreachable, identity unresolved, an approval that could not open), or a malformed hook payload all return a clean deny. The verdict’s zero value is itself a deny. An ask routes to a governed approval; the approval is bound to a plan hash of the exact tool-call, so it cannot be reused to authorize a different call (anti-TOCTOU).

In production the hook ships in Claude Code’s enterprise managed-settings tier with managed-hooks-only enabled, so a developer cannot disable or replace it from a lower-precedence settings file. Identity hints stamped on the request refine attribution; the authoritative principal is the bearer the decider resolves, and a policy that requires firm identity denies anything it can only attribute approximately.

A lighter, local mode

The connector also supports a local, in-process enforcement policy evaluated on the hook’s hot path with no engine round-trip — so a slow or unreachable control plane never wedges a developer’s tool call. It is opt-in: with no rules configured, hooks are observed and never gated. This is the cooperative-by-default posture; the governed PEP above is the opposite posture you switch to when the control plane must be the decision-maker.

Anti-evasion

Because the observation path is cooperative, the connector watches for a session that stops emitting OTel while its hooks are still firing — the signature of an agent that disabled its exporter mid-session while continuing to act. Note what it does not do: a finished agent goes quiet, and quiet alone is never flagged. Ground truth for genuinely non-cooperative activity is the kernel/eBPF backstop, not this heuristic.

Air-gap: what stays home and what does not

The control plane runs inside your own infrastructure and can run air-gapped — the governance and observation data (access edges, decisions, audit, cost samples) never leaves your perimeter. The OTLP receiver and the hook PEP are local sockets; the engine does not phone home.

One honest caveat: Claude inference is never air-gapped. Claude Code still sends its prompts to Anthropic’s API (directly or via Bedrock, Vertex or Foundry) to get a response. Air-gapping the control plane keeps your estate’s governance data home; it does not move the model on-prem. Only genuinely self-hostable models (for example via vLLM/Ollama) run fully offline. See what is Olivares AI and honesty and limits.

Next steps