[FEATURE] Allow agents and integrations to enrich native OTEL spans with delivery context

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code's beta OpenTelemetry tracing emits native spans for interactions, model requests, tools, hooks, and subagents. It also supports static resource attributes and repository identity.

However, an agent, hook, or approved integration cannot add governed, dynamic delivery context to the native span currently being created. Static OTEL_RESOURCE_ATTRIBUTES cannot represent per-interaction or per-feature values discovered during a session, such as a ticket ID, merge request, commit SHA, artifact, release, deployment, or runtime environment.

This prevents reliable end-to-end correlation from AI-assisted work through source control, CI/CD, deployment, and production outcomes.

Proposed Solution

Provide a governed runtime API or hook that can add allow-listed attributes to relevant native Claude Code spans before export.

Illustrative API:

on_span_created(span, context)
span.set_attribute(key, value)

Requirements:

• Mutations happen in the Claude Code runtime before export, not through prompting alone.
• Support dynamic, per-interaction and per-span context.
• Allow-list keys and constrain types, value sizes, and cardinality.
• Support privacy, redaction, and managed organization policy.
• Record provenance: runtime, agent, hook, plugin, or integration.
• Apply configured context consistently to interaction, model, tool, hook, and subagent spans.
• Preserve OpenTelemetry semantic conventions, especially vcs.* and gen_ai.*.

Example attributes:

workitem.id
vcs.repository.url.full
vcs.repository.ref.name
vcs.repository.ref.revision
gitlab.merge_request.id
artifact.id
deployment.id
deployment.environment
service.version

The primary correlation key would normally be repository identity plus commit SHA, with work-item, artifact, release, deployment, and session identifiers supplying the remaining lineage.

Alternative Solutions

OTEL_RESOURCE_ATTRIBUTES can add process-wide static context, and an OpenTelemetry Collector can enrich spans after export. Neither option gives an agent-aware integration controlled access to dynamic context on the native span where Claude Code knows the interaction, model, tool, hook, and subagent relationship.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

1. Claude Code starts work for ticket PROJ-123.
2. It creates or discovers a branch, commit, and merge request.
3. CI builds an artifact and deploys it to an environment.
4. Native Claude Code spans carry the approved correlation keys available at each stage.
5. An observability backend can trace the feature from requirement through AI activity, commit, pipeline, artifact, deployment, and runtime outcomes.

Additional Context

Related request for GitHub Copilot CLI: https://github.com/github/copilot-cli/issues/4967

Observed with Claude Code v2.1.283.