Document per-run session and reasoning overrides

types.go

@@ -98,7 +98,8 @@ type RunRequest struct {
 	// opaque consumer metadata, not a credential, and may be exposed in
 	// prepared values, results, collaborator requests, provider requests, and
 	// provider observability. Callers should use stable, non-sensitive
-	// identifiers.
+	// identifiers. An overlong direct value makes Prepare or Run return an
+	// error matching ErrInvalidRequest.
 	SessionID string
 	// APIKey is a request-scoped direct credential. It takes precedence over
 	// APIKeyEnv, is passed to the selected LLMClient, and is never included in
@@ -300,7 +301,8 @@ type ExecutionTarget struct {
 	TimeoutSeconds int `json:"timeout_seconds"`
 	// ServiceTier is an optional provider-specific request tier.
 	ServiceTier string `json:"service_tier"`
-	// ReasoningEffort is an optional provider-specific reasoning setting.
+	// ReasoningEffort is the effective opaque provider-specific reasoning
+	// setting. An empty value instructs model clients to omit reasoning.
 	ReasoningEffort string `json:"reasoning_effort"`
 	// APIKeyEnv is an environment-variable name, not its credential value.
 	APIKeyEnv string `json:"api_key_env"`
@@ -337,7 +339,8 @@ type ExecutionTargetOverride struct {
 	// ReasoningEffort controls the per-run reasoning setting. Nil inherits the
 	// profile value. A pointer to a non-blank string trims and replaces the
 	// profile value. A pointer to an empty or whitespace-only string clears the
-	// inherited value and disables reasoning for this run.
+	// inherited value and disables reasoning for this run. Non-blank values
+	// are opaque and are not validated against a fixed vocabulary.
 	ReasoningEffort *string
 	// APIKeyEnv replaces the profile or backend environment-variable name when
 	// non-blank. A direct RunRequest.APIKey still takes precedence over