fix(tracing): keep raw errors behind content opt-in

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 2 people

CHANGELOG.md

@@ -15,6 +15,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   turn, chat, and tool spans end with `cubepi.run.outcome="suspended"`; observer
   failures cannot hide the terminal event, cancellation still propagates, and
   `respond()` opens a distinct correlated activation trace.
+- **Raw provider error details now follow the content-recording opt-in.** With
+  `record_content=False`, traces retain typed error classification and ERROR
+  status but use bounded generic descriptions and omit exception messages and
+  stack traces. `record_content=True` preserves the prior diagnostic detail.
 
 ## [0.13.3] - 2026-08-02
 

cubepi/tracing/recorder.py

@@ -844,7 +844,11 @@ def _on_turn_end(self, event: TurnEndEvent) -> None:
         # "error", mark turn ERROR. Abort path leaves UNSET + sets
         # cubepi.aborted on the invoke_agent root.
         if stop_reason == "error":
-            err_msg = getattr(msg, "error_message", None) or "model error"
+            err_msg = (
+                getattr(msg, "error_message", None) or "model error"
+                if self._record_content
+                else "model error"
+            )
             run.turn_span.set_status(Status(StatusCode.ERROR, err_msg[:256]))
             run.turn_span.set_attribute(ERROR_TYPE, "cubepi.error")
         elif stop_reason == "aborted":
@@ -1267,17 +1271,24 @@ def _on_provider_response(
                 span.set_attribute(CUBEPI_ABORTED, True)
                 span.set_attribute(ERROR_TYPE, "cubepi.aborted")
             else:
-                span.set_status(Status(StatusCode.ERROR, str(exc)[:256]))
+                description = (
+                    str(exc)[:256] if self._record_content else "provider error"
+                )
+                span.set_status(Status(StatusCode.ERROR, description))
                 span.set_attribute(ERROR_TYPE, cubepi_error_type_for(exc))
+                exception_attrs = {"exception.type": type(exc).__name__}
+                if self._record_content:
+                    exception_attrs.update(
+                        {
+                            "exception.message": str(exc),
+                            "exception.stacktrace": "".join(
+                                traceback.format_exception(exc)
+                            ),
+                        }
+                    )
                 span.add_event(
                     name=EVENT_GEN_AI_EXCEPTION,
-                    attributes={
-                        "exception.type": type(exc).__name__,
-                        "exception.message": str(exc),
-                        "exception.stacktrace": "".join(
-                            traceback.format_exception(exc)
-                        ),
-                    },
+                    attributes=exception_attrs,
                 )
         finally:
             span.end()

dev/plans/2026-08-04-tracing-hitl-suspension.md

@@ -50,6 +50,8 @@ OpenTelemetry SDK, pytest, Ruff, mypy, uv.
 - Move assistant output accumulation to `MessageEndEvent` so suspension before
   `TurnEndEvent` still records the partial output.
 - Do not change `_close_open_spans()` cancellation semantics.
+- When `record_content=False`, preserve typed ERROR classification while using
+  generic status descriptions and omitting exception messages/stack traces.
 
 ## Task 4: Document the lifecycle contract
 

dev/specs/2026-08-04-tracing-hitl-suspension.md

@@ -37,6 +37,8 @@ left the old `_RunState` retained in that task's context.
 - Remove tool-span and MCP-provider registrations during normal tracing detach.
 - Count the assistant tool-call message as partial activation output.
 - Keep tracing observational: recorder failures must not affect the agent.
+- Keep raw provider error messages and stack traces behind `record_content=True`;
+  privacy-default traces retain only typed error classification.
 
 ## Non-goals
 

tests/tracing/test_content_recording.py

@@ -102,6 +102,26 @@ async def test_no_content_attrs_when_record_content_false(self):
                     f"{span.name} should not carry {forbidden} with record_content=False"
                 )
 
+    async def test_error_details_are_private_when_record_content_false(self):
+        secret = "Authorization: Bearer TOPSECRET"
+        agent, provider, exporter, tracer = await _build(record_content=False)
+
+        def explode(*_args):
+            raise RuntimeError(secret)
+
+        provider.append_responses([explode])
+
+        await agent.prompt("private prompt")
+        await agent.wait_for_idle()
+        await tracer.shutdown()
+
+        assert any(span.status.status_code.name == "ERROR" for span in exporter.spans)
+        for span in exporter.spans:
+            assert secret not in (span.status.description or "")
+            assert secret not in repr(dict(span.attributes or {}))
+            for event in span.events:
+                assert secret not in repr(dict(event.attributes or {}))
+
 
 class TestRootContent:
     async def test_invoke_agent_records_input_output_system(self):

website/docs/guides/tracing/getting-started.md

@@ -147,6 +147,9 @@ The recorder treats cancellation as a control signal, not a failure:
 - A provider raising → chat/turn/root close with **status ERROR**, an
   `exception` event on the chat span, and `error.type` derived from the
   exception class (`timeout`, `connection_error`, fully-qualified class name, …).
+  With the default `record_content=False`, the status description is generic and
+  the event contains only `exception.type`; raw exception messages and stack
+  traces are included only when content recording is explicitly enabled.
 - An MCP `tools/call` returning `isError=true` → CLIENT span closes
   ERROR + `error.type=mcp.is_error`.
 
@@ -182,7 +185,8 @@ Optional, opt-in via `Tracer(record_content=True)`:
 `gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`,
 `gen_ai.tool.definitions`, `gen_ai.tool.call.arguments`,
 `gen_ai.tool.call.result`, `cubepi.llm.raw_request`,
-`cubepi.llm.raw_response`. See [Content & Redaction](./content-recording).
+`cubepi.llm.raw_response`, provider exception messages, and provider exception
+stack traces. See [Content & Redaction](./content-recording).
 
 ## Multiple agents, one process