feat(go): add ContentCaptureMode for SDK-level content stripping (#21)

Callers now have a way to prevent text from leaving the process via the
export pipeline or OTel attributes. `MetadataOnly` mode strips all text
content at the SDK level while preserving message structure, tool names,
usage, and timing.

The existing `IncludeContent` bool on `ToolExecutionStart` only
controlled span attributes for individual tools. `ContentCapture`
supersedes it with a mode that applies to the entire generation and
propagates to child tool executions via context. `IncludeContent`
continues to work for backward compatibility under the default
`NoToolContent` mode.


### Modes

| Mode | Generations | Tool spans |
|------|------------|------------|
| `Full` | All content exported | Arguments and results in span
attributes |
| `NoToolContent` (SDK default, same as before this PR) | All content
exported | Excluded |
| `MetadataOnly` | Structure preserved, text stripped | Arguments and
results excluded |


### Example

```go
// Client-level default
client := sigil.NewClient(sigil.Config{
    ContentCapture: sigil.ContentCaptureModeMetadataOnly,
})

// Per-generation override
ctx, rec := client.StartGeneration(ctx, sigil.GenerationStart{
    ContentCapture: sigil.ContentCaptureModeFull,
})

// Tool executions inherit from parent generation
_, toolRec := client.StartToolExecution(ctx, sigil.ToolExecutionStart{
    ToolName: "search",
})
```

---

### Dynamic resolution via ContentCaptureResolver

A callback on `sigil.Config` that resolves the capture mode
per-recording at runtime. Useful for feature flags, per-tenant policies,
or context-dependent decisions.
    
```go
client := sigil.NewClient(sigil.Config{
    ContentCaptureResolver: func(ctx context.Context, metadata map[string]any) sigil.ContentCaptureMode {
        if shouldStripContent(ctx, metadata) {
            return sigil.ContentCaptureModeMetadataOnly
        }
        return sigil.ContentCaptureModeDefault // fall through to Config.ContentCapture
    },
})
```

Resolution precedence (highest -> lowest):
1. Per-recording `ContentCapture` field (on `GenerationStart` /
`ToolExecutionStart`)
2. `ContentCaptureResolver` return value
3. `Config.ContentCapture` (client default, resolves to `NoToolContent`
when unset to preserve old behaviour)
                                         
Panics in the resolver are recovered and treated as `MetadataOnly`.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes what generation payloads and tool span attributes can contain
(including new MetadataOnly stripping), which can affect downstream
ingestion/observability and validation behavior. Defaults aim to
preserve prior behavior, but misconfiguration could unintentionally drop
content or export more than intended.
> 
> **Overview**
> Introduces `ContentCaptureMode` with client defaults
(`Config.ContentCapture`), per-generation
(`GenerationStart.ContentCapture`) and per-tool
(`ToolExecutionStart.ContentCapture`) overrides, plus a
`Config.ContentCaptureResolver` callback (panic-safe, fail-closed) to
resolve capture policy per request.
> 
> When `MetadataOnly` is effective, generations are stamped with
`sigil.sdk.content_capture_mode` and have prompts/messages/tool
I/O/artifacts stripped before enqueue/export, while preserving structure
and operational fields; tool executions also inherit the parent
generation’s mode via context and only include arguments/results in span
attributes when allowed (keeping `IncludeContent` as deprecated
backward-compat opt-in under the default behavior).
> 
> Extends validation to accept stripped text/thinking parts, updates
rating submission to drop `Comment` under `MetadataOnly`, and
adds/updates docs, examples, and tests to cover mode resolution,
inheritance, and stripping behavior.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
ed684ca. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: alexander-akhmetov

go/sigil/client.go

@@ -26,6 +26,24 @@ type Config struct {
 	GenerationExport GenerationExportConfig
 	API              APIConfig
 	EmbeddingCapture EmbeddingCaptureConfig
+	// ContentCapture controls the default content capture mode for all
+	// generations and tool executions. Per-recording overrides take precedence.
+	ContentCapture ContentCaptureMode
+	// ContentCaptureResolver, when set, is called before each generation,
+	// tool execution, and rating submission to dynamically resolve the content
+	// capture mode. It receives the request context and the recording's
+	// metadata (nil when the recording type has no metadata, e.g. tool
+	// executions).
+	//
+	// Resolution precedence (highest → lowest):
+	//   1. Per-recording ContentCapture field (explicit override)
+	//   2. ContentCaptureResolver return value
+	//   3. Config.ContentCapture (static default)
+	//
+	// Returning ContentCaptureModeDefault defers to Config.ContentCapture.
+	// Panics are recovered and treated as ContentCaptureModeMetadataOnly
+	// (fail-closed).
+	ContentCaptureResolver func(ctx context.Context, metadata map[string]any) ContentCaptureMode
 	// Tracer is optional and mainly used for tests. If nil, the client uses the global OpenTelemetry tracer.
 	Tracer trace.Tracer
 	// Meter is optional and mainly used for tests. If nil, the client uses the global OpenTelemetry meter.
@@ -226,11 +244,12 @@ type Client struct {
 //
 // All methods are safe to call on a nil or no-op recorder.
 type GenerationRecorder struct {
-	client    *Client
-	ctx       context.Context
-	span      trace.Span
-	seed      GenerationStart
-	startedAt time.Time
+	client             *Client
+	ctx                context.Context
+	span               trace.Span
+	seed               GenerationStart
+	startedAt          time.Time
+	contentCaptureMode ContentCaptureMode
 
 	mu             sync.Mutex
 	ended          bool
@@ -455,12 +474,19 @@ func (c *Client) startGeneration(ctx context.Context, start GenerationStart, def
 		ThinkingEnabled:   cloneBoolPtr(seed.ThinkingEnabled),
 	})...)
 
+	// Resolve content capture mode: per-recording > resolver > client default.
+	resolverMode := callContentCaptureResolver(c.config.ContentCaptureResolver, ctx, seed.Metadata)
+	clientMode := resolveClientContentCaptureMode(resolveContentCaptureMode(resolverMode, c.config.ContentCapture))
+	ccMode := resolveContentCaptureMode(seed.ContentCapture, clientMode)
+	callCtx = withContentCaptureMode(callCtx, ccMode)
+
 	return callCtx, &GenerationRecorder{
-		client:    c,
-		ctx:       callCtx,
-		span:      span,
-		seed:      seed,
-		startedAt: startedAt,
+		client:             c,
+		ctx:                callCtx,
+		span:               span,
+		seed:               seed,
+		startedAt:          startedAt,
+		contentCaptureMode: ccMode,
 	}
 }
 
@@ -575,13 +601,19 @@ func (c *Client) StartToolExecution(ctx context.Context, start ToolExecutionStar
 	attrs := toolSpanAttributes(seed)
 	span.SetAttributes(attrs...)
 
+	// Resolve content capture: per-tool > context (parent generation) > resolver > client default.
+	resolverMode := callContentCaptureResolver(c.config.ContentCaptureResolver, ctx, nil)
+	effectiveClientDefault := resolveContentCaptureMode(resolverMode, c.config.ContentCapture)
+	ctxMode, ctxSet := contentCaptureModeFromContext(ctx)
+	includeContent := shouldIncludeToolContent(seed.ContentCapture, ctxMode, ctxSet, effectiveClientDefault, seed.IncludeContent)
+
 	return callCtx, &ToolExecutionRecorder{
 		client:         c,
 		ctx:            callCtx,
 		span:           span,
 		seed:           seed,
 		startedAt:      startedAt,
-		includeContent: seed.IncludeContent,
+		includeContent: includeContent,
 	}
 }
 
@@ -661,14 +693,19 @@ func (r *GenerationRecorder) End() {
 	normalized := r.normalizeGeneration(generation, completedAt, callErr)
 	applyTraceContextFromSpan(r.span, &normalized)
 
+	stampContentCaptureMetadata(&normalized, r.contentCaptureMode)
+	if r.contentCaptureMode == ContentCaptureModeMetadataOnly {
+		stripContent(&normalized, classifyErrorCategory(callErr, false))
+	}
+
 	r.span.SetName(generationSpanName(normalized))
 	r.span.SetAttributes(generationSpanAttributes(normalized)...)
 
 	r.mu.Lock()
 	r.lastGeneration = cloneGeneration(normalized)
 	r.mu.Unlock()
 
-	enqueueErr := r.client.persistGeneration(r.ctx, normalized)
+	enqueueErr := r.client.persistGeneration(normalized)
 
 	// Record errors on span.
 	if callErr != nil {
@@ -1078,11 +1115,10 @@ func combineAllErrors(errs ...error) error {
 	return errors.Join(filtered...)
 }
 
-func (c *Client) persistGeneration(_ context.Context, generation Generation) error {
-	if err := ValidateGeneration(generation); err != nil {
+func (c *Client) persistGeneration(generation Generation) error {
+	if err := validateGeneration(generation); err != nil {
 		return fmt.Errorf("%w: %v", errGenerationValidation, err)
 	}
-
 	if err := c.enqueueGeneration(generation); err != nil {
 		return fmt.Errorf("%w: %w", errGenerationEnqueue, err)
 	}

go/sigil/client_test.go

@@ -1086,59 +1086,57 @@ func TestStartToolExecutionSetsExecuteToolAttributes(t *testing.T) {
 }
 
 func TestToolExecutionRecorderContentCapture(t *testing.T) {
+	// Backward compat: Config{} with IncludeContent controls tool content.
 	client, recorder, _ := newTestClient(t, Config{})
 
-	_, withContent := client.StartToolExecution(context.Background(), ToolExecutionStart{
-		ToolName:       "weather",
-		IncludeContent: true,
-	})
-	withContent.SetResult(ToolExecutionEnd{
-		Arguments: map[string]any{"city": "Paris"},
-		Result:    map[string]any{"temp_c": 18},
-	})
-	withContent.End()
-	if err := withContent.Err(); err != nil {
-		t.Fatalf("end tool execution with content: %v", err)
-	}
-
-	_, withoutContent := client.StartToolExecution(context.Background(), ToolExecutionStart{
-		ToolName: "weather",
-	})
-	withoutContent.SetResult(ToolExecutionEnd{
-		Arguments: map[string]any{"city": "Paris"},
-		Result:    map[string]any{"temp_c": 18},
-	})
-	withoutContent.End()
-	if err := withoutContent.Err(); err != nil {
-		t.Fatalf("end tool execution without content: %v", err)
-	}
-
-	toolSpans := make([]sdktrace.ReadOnlySpan, 0, 2)
-	for _, span := range recorder.Ended() {
-		if isToolSpan(span) {
-			toolSpans = append(toolSpans, span)
+	execTool := func(t *testing.T, start ToolExecutionStart) sdktrace.ReadOnlySpan {
+		t.Helper()
+		start.ToolName = "weather"
+		_, rec := client.StartToolExecution(context.Background(), start)
+		rec.SetResult(ToolExecutionEnd{
+			Arguments: map[string]any{"city": "Paris"},
+			Result:    map[string]any{"temp_c": 18},
+		})
+		rec.End()
+		if err := rec.Err(); err != nil {
+			t.Fatalf("tool execution error: %v", err)
 		}
-	}
-	if len(toolSpans) != 2 {
-		t.Fatalf("expected 2 tool spans, got %d", len(toolSpans))
+		spans := recorder.Ended()
+		for i := len(spans) - 1; i >= 0; i-- {
+			if isToolSpan(spans[i]) {
+				return spans[i]
+			}
+		}
+		t.Fatal("tool span not found")
+		return nil
 	}
 
-	var sawWithContent, sawWithoutContent bool
-	for _, span := range toolSpans {
+	hasContent := func(span sdktrace.ReadOnlySpan) bool {
 		attrs := spanAttributeMap(span)
 		_, hasArgs := attrs[spanAttrToolCallArguments]
-		_, hasResult := attrs[spanAttrToolCallResult]
-		if hasArgs && hasResult {
-			sawWithContent = true
+		return hasArgs
+	}
+
+	t.Run("Config{} + bare ToolExecutionStart — no content", func(t *testing.T) {
+		span := execTool(t, ToolExecutionStart{})
+		if hasContent(span) {
+			t.Fatal("expected no tool content with default config and no IncludeContent")
 		}
-		if !hasArgs && !hasResult {
-			sawWithoutContent = true
+	})
+
+	t.Run("Config{} + IncludeContent:true — content included", func(t *testing.T) {
+		span := execTool(t, ToolExecutionStart{IncludeContent: true})
+		if !hasContent(span) {
+			t.Fatal("expected tool content with IncludeContent: true")
 		}
-	}
+	})
 
-	if !sawWithContent || !sawWithoutContent {
-		t.Fatalf("expected both content and non-content tool spans")
-	}
+	t.Run("Config{} + IncludeContent:false — no content", func(t *testing.T) {
+		span := execTool(t, ToolExecutionStart{IncludeContent: false})
+		if hasContent(span) {
+			t.Fatal("expected no tool content with IncludeContent: false")
+		}
+	})
 }
 
 func TestToolExecutionRecorderErrorSetsStatusAndType(t *testing.T) {