Fix execute_tool span kind (#274)

* Emit execute_tool spans with INTERNAL span kind

execute_tool runs in-process, so its span must be INTERNAL, not CLIENT.
ToolInvocation was inheriting the CLIENT default from GenAIInvocation.

Also add a rego live-check rule (genai_span_kind_unexpected) that pins the
expected span kind per gen_ai.operation.name, which surfaces this class of bug.

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Rename changelog fragment to PR number and fix import order

Renames the changelog fragment to 274.fixed to satisfy the changelog CI
check, and sorts imports in test_toolcall.py to fix the ruff lint gate.

Assisted-by: Claude Opus 4.8

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: lmolkova

policies/genai_span_validation.rego

@@ -215,6 +215,43 @@ deny contains _span_finding(
 	not _has_attr(input.sample.span, attr_name)
 }
 
+# ─── Per-operation span kind (violation) ────────────────────────────────────
+#
+# Semconv pins the span kind for each operation. `_expected_kinds_for_op`
+# returns the set of kinds semconv allows; a span whose kind is outside that
+# set is flagged. Single-element sets are the unambiguous cases (inference and
+# embeddings are remote calls → CLIENT; tool execution runs in-process →
+# INTERNAL). `invoke_agent` / `create_agent` may be same-process or remote, so
+# both kinds are allowed. Undefined (→ no violation) for unmapped ops.
+_expected_kinds_for_op["chat"]             := {"client"}
+_expected_kinds_for_op["generate_content"] := {"client"}
+_expected_kinds_for_op["text_completion"]  := {"client"}
+_expected_kinds_for_op["embeddings"]       := {"client"}
+_expected_kinds_for_op["execute_tool"]     := {"internal"}
+_expected_kinds_for_op["invoke_workflow"]  := {"internal"}
+_expected_kinds_for_op["retrieval"]        := {"client"}
+_expected_kinds_for_op["invoke_agent"]     := {"internal", "client"}
+_expected_kinds_for_op["create_agent"]     := {"internal", "client"}
+
+deny contains _span_finding(
+	"genai_span_kind_unexpected",
+	"violation",
+	input.sample.span,
+	{
+		"operation": op,
+		"kind":      input.sample.span.kind,
+	},
+	sprintf(
+		"Span '%v' (operation '%v') has kind '%v'; semconv expects one of %v",
+		[input.sample.span.name, op, input.sample.span.kind, sort([k | expected_kinds[k]])],
+	),
+) if {
+	input.sample.span
+	op := _attr_value(input.sample.span, "gen_ai.operation.name")
+	expected_kinds := _expected_kinds_for_op[op]
+	not expected_kinds[input.sample.span.kind]
+}
+
 # ─── Unknown gen_ai.operation.name (violation) ──────────────────────────────
 #
 # Weaver's built-in `undefined_enum_variant` advice is `information`-level;

util/opentelemetry-util-genai/.changelog/274.fixed

@@ -0,0 +1 @@
+Emit ``execute_tool`` spans with ``INTERNAL`` span kind instead of ``CLIENT``.

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_tool_invocation.py

@@ -7,7 +7,7 @@
 from opentelemetry.semconv._incubating.attributes import (
     gen_ai_attributes as GenAI,
 )
-from opentelemetry.trace import Tracer
+from opentelemetry.trace import SpanKind, Tracer
 from opentelemetry.util.genai._invocation import Error, GenAIInvocation
 from opentelemetry.util.genai.completion_hook import CompletionHook
 from opentelemetry.util.genai.metrics import InvocationMetricsRecorder
@@ -71,6 +71,7 @@ def __init__(
             completion_hook,
             operation_name=_operation_name,
             span_name=f"{_operation_name} {name}" if name else _operation_name,
+            span_kind=SpanKind.INTERNAL,
         )
         self.should_capture_content_on_span = should_capture_content_on_spans()
         self.name = name

util/opentelemetry-util-genai/tests/test_toolcall.py

@@ -17,6 +17,7 @@
 from opentelemetry.semconv._incubating.attributes import (
     gen_ai_attributes as GenAI,
 )
+from opentelemetry.trace import SpanKind
 from opentelemetry.util.genai.environment_variables import (
     OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT,
 )
@@ -143,6 +144,14 @@ def test_server_tool_call_in_message():
     pytest.main([__file__, "-v"])
 
 
+def test_tool_span_is_internal_kind():
+    """execute_tool runs in-process, so its span must be INTERNAL, not CLIENT."""
+    span_exporter, handler = _make_span_exporter_and_handler()
+    handler.tool("get_weather").stop()
+
+    assert span_exporter.get_finished_spans()[0].kind == SpanKind.INTERNAL
+
+
 def test_start_tool_passes_sampling_attributes_at_span_creation():
     """Verify that sampling-relevant attributes are available at start_span() time for tools."""
     captured_attributes = {}