Track Claude Code Guardrails with OpenTelemetry

Lachlan Reed

Picture this. You've got Claude Code running overnight in a pipeline, it stalls, and the only clue is a session transcript the size of a novel. Today's update is aimed squarely at that headache. This is The Claude Code Changelog, brought to you by Jellypod AI. I'm Lachlan.

James Turner

And I'm James. Version 2.1.307 shipped on October 21st, 2026, and it adds a new OpenTelemetry event called claude_code.safety_event. According to the release notes, it fires for each tool call that a permission rule, auto mode, a safety check, a hook, or the sandbox stopped, prompted, or sent back. So every time a guardrail gets involved, you get a data point.

Lachlan Reed

And what's in that data point? Because an event with no detail is just noise.

James Turner

A TurboAI breakdown of the release lists the attributes. The tool class and tool name, the tool use ID, a classifier category, a sandbox violation count, and whether sandboxing was enabled. That combination matters. The classifier category plus the sandbox count means you can tell a permission rule refusal apart from a sandbox block, and you can count either one without opening a single transcript.

Lachlan Reed

So the shift is from guardrails as something you dig for in logs, to guardrails as a metric. If you run Claude Code across a team, or in headless mode, you can finally ask how often calls get blocked, and which tools keep tripping it. Before this, that was a forensic exercise.

James Turner

Right. Now, how do you use it? This assumes you already export OpenTelemetry from Claude Code. If you do, there's nothing new to switch on that I can point to in the release notes, so check Anthropic's monitoring docs for the full setup. The usual exporter variables apply. OTEL_EXPORTER_OTLP_ENDPOINT pointing at your collector, so something like https colon slash slash your collector, port 4318 for HTTP. OTEL_EXPORTER_OTLP_PROTOCOL set to http/protobuf or grpc. And OTEL_EXPORTER_OTLP_HEADERS if your backend wants a bearer token.

Lachlan Reed

Then in your backend, whether that's Grafana, Datadog, Honeycomb, whatever you've got, you search for the event name claude_code.safety_event. Here's where I'd start. Filter for a sandbox violation count above zero. Those are commands that bumped into the sandbox's limits, and they're worth a look.

James Turner

And then group by classifier category and tool name. That's my suggestion, not something from the release notes, but it's a sensible read. If one tool keeps getting prompted for something harmless, that's probably a permission rule you should tune in your settings. If a category you never expected keeps showing up, that's the one to investigate.

Lachlan Reed

A few caveats. First, the event covers prompts, not just hard stops. If someone's in an interactive session and Claude asks permission to run a command, that counts. So a high number can just mean the agent's being careful, not that you're under attack.

James Turner

Second, this is observability, not enforcement. It tells you what a guardrail did after it evaluated the call. It doesn't replace your rules or managed settings. And third, there's a related fix in the same release. Telemetry from Claude Desktop sessions behind a Claude apps gateway was being rejected when OTEL_EXPORTER_OTLP_HEADERS was set. That's fixed now, so if your data went missing there, that may be why.

Lachlan Reed

Now some smaller bits worth a mention. HTTP MCP tool calls used to be sent twice if the connection closed mid call. Now Claude Code only retries tools that are read only or idempotent. That's a real win if your tool creates a record or charges a card.

James Turner

Also, unparseable tool calls now get retried up to twice before the turn ends with an error. For headless runs on macOS, MCP servers no longer get stuck showing needs authentication when the login keychain is locked. They now say why, and the next run after an unlock connects without a new sign in. Same idea for machines that go to sleep while MCP servers are connecting.

Lachlan Reed

Two more for people running infrastructure. On a self hosted runner, checkout hooks now stop after 30 minutes by default, and that fails the session's setup. If your hook legitimately needs longer, raise the checkout hook timeout minutes flag, or set it to zero. And for pull requests, you can now comment at claude review stop, or off, or pause, to end an at claude review always subscription without kicking off a new review.

James Turner

One last note. Version 2.1.308 landed shortly after, listed only as bug fixes and reliability improvements. So if you update, you'll get both. Go wire up that safety event, and run your first query on blocked calls this week.