Why audit trails matter for Claude agents
A fully auditable Claude coding agent leaves a record of every query it runs against BigQuery, and every data element it receives is masked according to policy. When a development team lets an LLM write and execute SQL, the risk is not only accidental data leakage but also the inability to prove who triggered a costly or destructive operation. An audit trail gives the team forensic visibility, satisfies compliance reviewers, and provides a deterrent against careless prompts.
Current practice and its blind spots
Most organizations drop a Claude‑driven client into their CI pipeline and hand it a service account key that has broad read‑write rights on a data warehouse. The key is stored in a secret manager, copied into build containers, and often shared across multiple projects. Engineers can invoke the agent from a notebook, a terminal, or an automated script, and the agent talks directly to BigQuery. No central point observes the traffic, no request is logged beyond the native BigQuery audit logs, and no response data is ever filtered. If the LLM hallucinates a table name or issues a DELETE without a WHERE clause, the damage is done before anyone notices.
This pattern satisfies the immediate need to get code generated quickly, but it leaves three critical gaps: the request bypasses any runtime guard, the response data is exposed in full to the calling process, and there is no immutable record that ties a specific prompt to a specific query result.
Turning the audit gap into a control surface
The missing piece is a Layer 7 gateway that sits between the Claude agent and BigQuery, inspects each protocol exchange, and applies policy before the request reaches the database. hoop.dev provides exactly that data‑path enforcement point. It proxies the connection, validates the caller’s OIDC token, and then records every command, every response, and the identity that issued it. Because the gateway is the only place the traffic flows, hoop.dev can also mask sensitive columns in the result set and block commands that do not meet pre‑approved criteria.
How hoop.dev captures a complete record
When a Claude‑driven process initiates a BigQuery query, hoop.dev receives the request, extracts the user’s identity from the OIDC token, and writes a session entry that includes the prompt, the generated SQL, the execution timestamp, and the final status. hoop.dev retains the audit trail for later review, ensuring that each Claude session is fully documented.
Masking and policy enforcement at the gateway
Before forwarding the query to BigQuery, hoop.dev can apply inline masking rules that replace or redact columns such as SSN, credit‑card numbers, or PII. The same engine can evaluate the SQL against a whitelist of allowed tables and operations; if the query attempts a destructive action without an explicit approval step, hoop.dev blocks it and raises a request for manual review. In this way, hoop.dev turns a blind‑spot into a controllable surface, delivering the audit trails the team needs while still allowing the Claude agent to operate.
Implementing the solution
Deploy the gateway close to your data warehouse using the Docker Compose quick‑start or a Kubernetes manifest. Register the BigQuery connection in the hoop.dev console, attach the service account credential that the gateway will use, and configure OIDC authentication against your identity provider. Once the gateway is running, point your Claude client at the hoop.dev endpoint instead of the raw BigQuery endpoint. All traffic will now be funneled through the gateway, and the audit trail will be generated automatically.
For step‑by‑step guidance, see the getting‑started guide. The feature overview explains how masking, approvals, and session replay work in detail. The full source code and contribution instructions are available on GitHub.
Explore the open‑source code on GitHub to get started.
FAQ
- Can I use hoop.dev with an existing Claude integration? Yes. The gateway is protocol‑aware, so you only need to change the endpoint address in the client configuration. No code changes are required in the Claude integration itself.
- Does hoop.dev store the raw query results? hoop.dev records the fact that a query was executed and the metadata around it. Result rows are masked according to policy before they leave the gateway, and only the masked view is persisted in the audit log.
- What happens if an agent tries to bypass the gateway? Because the service account credentials are only known to the gateway, any direct connection attempt without the gateway will be rejected by the database’s IAM policy. This forces all traffic through hoop.dev, guaranteeing that audit trails are always produced.
