Align option pointer semantics with .NET

[Quim Muntal (qmuntal)]

Summary

• align existing Go config and option fields with nullable and default-sensitive .NET counterparts
• replace inverted true-by-default switches with positive, pointer-backed properties
• preserve the distinction between omitted values and explicit false, 0, or empty values
• update examples, documentation, and tests for the revised public API

Rationale

Go 1.26 allows new to initialize a pointer directly from an expression. Struct literals can now use new(false), new(0), or new("...") without helper functions or temporary variables. This makes pointer-backed options concise enough to model configuration intent directly: nil means "not specified," while the pointed value is an explicit choice.

That distinction lets the Go API follow the .NET option contracts more closely. In particular, true-by-default settings no longer need inverted Disable... names solely to accommodate Go's zero value.

Notable changes

• rename history-conflict switches to ThrowOnHistoryProviderConflict, WarnOnHistoryProviderConflict, and ClearOnHistoryProviderConflict
• use positive pointer booleans for workflow forwarding, role reassignment, automatic handler outputs, and turn-token forwarding
• model nullable or default-sensitive prompts, limits, search depth, Foundry memory, and shell options with pointers
• rename agent-mode Description to Instructions
• represent removed shell environment variables with nil map values

Compatibility

This intentionally changes exported struct fields and does not add compatibility aliases. Callers specify explicit pointer-backed values with Go 1.26 expressions such as new(false) and new(0).

Testing

• go test ./...

[Copilot]

Pull request overview

This PR aligns the Go SDK’s public option/config surfaces with .NET-style nullable and default-sensitive semantics by migrating many previously value-typed or inverted “Disable…” booleans to positive, pointer-backed fields. This preserves the distinction between omitted values and explicitly specified false/0/empty values, while keeping default behaviors consistent with the .NET counterparts.

Changes:

• Replaced several inverted Disable... switches with positive *bool options (and helper accessors) across workflow execution and agent hosting.
• Migrated multiple config fields to pointer-backed types (*bool, *int, *string, *time.Duration, etc.) to preserve “unset vs explicit” intent; updated merging/validation logic accordingly.
• Updated tests, examples, and docs to reflect the revised public API and pointer-based option patterns.

Show a summary per file

File	Description
workflow/protocol.go	Uses new Executor auto-send/auto-yield helpers when building protocol descriptors.
workflow/protocol_test.go	Updates protocol builder tests to use pointer-backed auto-send/auto-yield options.
workflow/internal/execution/protocol_test.go	Updates internal execution tests to use pointer-backed Executor auto-send/auto-yield options.
workflow/inproc/subworkflow.go	Updates subworkflow host executor defaults to explicit new(false) auto-send/auto-yield pointers.
workflow/inproc/subworkflow_test.go	Updates in-proc subworkflow tests for new Executor option fields.
workflow/inproc/external_request_test.go	Updates external request tests for new Executor option fields.
workflow/inproc/events_test.go	Updates event workflow test executors for new Executor option fields.
workflow/inproc/concurrent_test.go	Updates concurrent binding tests for new Executor option fields.
workflow/inproc/checkpoint_test.go	Updates checkpoint-related tests for new Executor option fields.
workflow/inproc/binding_test.go	Updates binding tests for new Executor option fields; updates auto send/yield parameterization.
workflow/executor.go	Replaces disable flags with pointer-backed auto-send/auto-yield fields and helper methods; updates Extend/Execute behavior.
workflow/executor_test.go	Updates Executor tests to use pointer-backed auto-send/auto-yield options.
workflow/builder_test.go	Updates builder validation test for new auto-send option field.
workflow/agentworkflow/workflow_test.go	Updates agentworkflow tests to pointer-backed EmitUpdateEvents/ForwardIncomingMessages and related options.
workflow/agentworkflow/sequential.go	Updates sequential workflow defaults to pointer-backed ForwardIncomingMessages; updates turn-token auto-send config usage.
workflow/agentworkflow/inprocess_execution_test.go	Updates in-process execution tests for pointer-backed EmitUpdateEvents.
workflow/agentworkflow/hosting.go	Migrates host Config booleans to pointer-backed fields; introduces helper to apply defaults.
workflow/agentworkflow/hosting_test.go	Updates hosting tests for pointer-backed config fields and new Executor options.
workflow/agentworkflow/groupchat.go	Updates group chat workflow to use pointer-backed ForwardIncomingMessages and turn-token auto-send option.
workflow/agentworkflow/groupchat_test.go	Updates group chat tests for new agentworkflow Config fields.
workflow/agentworkflow/concurrent.go	Updates concurrent workflow message executor to use pointer-backed turn-token auto-send option.
tool/shelltool/shelltool_test.go	Updates shelltool tests for pointer-backed config fields; adds new tests for snapshotting/timeout edge cases.
tool/shelltool/session.go	Updates persistent session to accept pointer timeout and pointer-based environment map semantics.
tool/shelltool/localshell.go	Migrates LocalConfig timeout/environment/confine flags to pointer-backed fields; updates validation and runtime behavior.
tool/shelltool/environment.go	Migrates EnvironmentProviderConfig override family and probe timeout to pointer-backed fields; snapshots resolved values.
provider/foundryprovider/memory.go	Migrates Foundry memory provider config prompt/max values to pointers; preserves explicit 0 and custom prompt intent.
provider/foundryprovider/memory_test.go	Updates memory provider tests to use pointer-backed config values.
message/messageworkflow/messageworkflow.go	Migrates DisableAutoSendTurnToken to pointer-backed AutoSendTurnToken with default-on helper; snapshots option pointer.
message/messageworkflow/messageworkflow_test.go	Updates messageworkflow tests for new AutoSendTurnToken option and snapshotting behavior.
message/messageworkflow/messageforwarding.go	Comment formatting updates (no behavioral change).
examples/03-workflows/subworkflows/request_interception/main.go	Updates example executors to explicit pointer-backed auto-send/auto-yield configuration.
examples/03-workflows/message-workflow/main.go	Updates example to use AutoSendTurnToken semantics and renamed parameter.
examples/03-workflows/human-in-the-loop/imperative_request/main.go	Updates example executor config for pointer-backed auto-send/auto-yield fields.
examples/03-workflows/01-start-here/06_mixed_workflow_agents_and_executors/main.go	Updates example agentworkflow Config to pointer-backed ForwardIncomingMessages.
examples/03-workflows/01-start-here/02_agents_in_workflows/main.go	Updates example agentworkflow Config to pointer-backed ForwardIncomingMessages.
examples/02-agents/agents/step23_planning_with_todos/main.go	Updates agentmode DefaultMode to pointer-backed string.
examples/02-agents/agents/step19_loop_reinvocation/main.go	Updates loop MaxIterations to pointer-backed int values.
docs/dotnet-go-sdk-feature-comparison.md	Updates documentation to reflect pointer-backed positive options matching .NET semantics.
agent/skills/skills_test.go	Updates skills tests for pointer-backed SearchDepth and prompt template config; adjusts invalid-depth behavior.
agent/skills/provider.go	Migrates SkillsInstructionPrompt to pointer-backed string and updates template selection logic.
agent/skills/provider_test.go	Updates provider tests for pointer-backed SkillsInstructionPrompt.
agent/skills/fsskills/source.go	Migrates SearchDepth to pointer-backed int; introduces validation/panic for invalid explicit values.
agent/skills/fsskills/source_test.go	Updates fsskills tests to use pointer-backed SearchDepth.
agent/skills/fsskills/source_script_test.go	Updates script discovery test to use pointer-backed SearchDepth.
agent/harness/toolautocall/autocall.go	Migrates MaximumConsecutiveErrorsPerRequest to pointer-backed int; updates defaulting and validation.
agent/harness/toolautocall/autocall_test.go	Updates toolautocall tests to use pointer-backed MaximumConsecutiveErrorsPerRequest semantics.
agent/harness/toolautocall/autocall_log_test.go	Updates autocall log tests for pointer-backed MaximumConsecutiveErrorsPerRequest.
agent/harness/toolapproval/toolapproval.go	Migrates MaxAutoApprovalIterations to pointer-backed int and tightens validation (>=1 when specified).
agent/harness/toolapproval/toolapproval_test.go	Updates toolapproval tests for pointer-backed MaxAutoApprovalIterations and new validation message.
agent/harness/todo/todo.go	Migrates todo provider Instructions override to pointer-backed string.
agent/harness/todo/todo_test.go	Updates todo tests for pointer-backed Instructions.
agent/harness/loop/loop.go	Migrates MaxIterations to pointer-backed int; updates defaulting and error messaging; clarifies mode metadata fields.
agent/harness/loop/loop_test.go	Updates loop tests for pointer-backed MaxIterations and completion marker template pointers.
agent/harness/loop/evaluators.go	Migrates completion marker feedback template override to pointer-backed string.
agent/harness/agentmode/agentmode.go	Renames Mode.Description to Mode.Instructions; migrates DefaultMode and Instructions overrides to pointer-backed strings; adds validation.
agent/harness/agentmode/agentmode_test.go	Updates agentmode tests for renamed fields and pointer-backed DefaultMode/Instructions.
agent/compaction/summarization.go	Migrates SummarizationPrompt to pointer-backed string and updates default selection.
agent/compaction/index_test.go	Updates compaction index test for pointer-backed SummarizationPrompt.
agent/compaction/compaction_test.go	Updates compaction strategy test for pointer-backed SummarizationPrompt.
agent/agent.go	Renames history-conflict controls and migrates them to pointer-backed booleans; updates conflict handling logic accordingly.
agent/agent_test.go	Updates agent tests for renamed history-conflict controls and pointer-backed values.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 61/61 changed files
• Comments generated: 1
• Review effort level: Lite

[github-actions]

Cross-Repo Parity Review

Scope: public API, user-visible behavior

Changed Go contract:

• agentmode.Mode.Description → Instructions
• agentmode.Config.DefaultMode / Config.Instructions: string → *string (nil = unset)
• agentworkflow.Config.ForwardIncomingMessages / ReassignOtherAgentsAsUsers: inverted Disable* bool → positive *bool (nil = default-true)
• agentworkflow.Config.EmitUpdateEvents: bool → *bool (nil = delegate to TurnToken)
• workflow.Executor.AutoSendMessageHandlerResultObject / AutoYieldOutputHandlerResultObject: inverted Disable* bool → positive *bool (nil = default-true)
• messageworkflow.Options.AutoSendTurnToken: inverted DisableAutoSendTurnToken → positive *bool

Upstream evidence reviewed:

• dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs — AgentMode.Instructions, DefaultMode string?, Instructions string? all match
• dotnet/src/Microsoft.Agents.AI.Workflows/AIAgentHostOptions.cs — ForwardIncomingMessages bool = true, ReassignOtherAgentsAsUsers bool = true, EmitAgentUpdateEvents bool? all match
• dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorOptions.cs — AutoSendMessageHandlerResultObject bool = true, AutoYieldOutputHandlerResultObject bool = true match

Result: ✅ aligned — all renamed and re-typed fields correspond to their upstream .NET counterparts in both naming and default semantics. No parity gaps found.

Generated by Go API Consistency Review Agent for #917 · sonnet46 · 35 AIC · ⌖ 5.04 AIC · ⊞ 6.4K · ◷