feat(sdk/python): model#variant reasoning-effort support across harness providers (#801)

* feat(sdk/python): split_model_variant + resolve_model_and_variant harness helpers

Parse the 'provider/model#variant' model-string syntax so a reasoning-effort
variant can travel through config surfaces that only hold a model string.
An explicit options['variant'] wins over the suffix.

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

* feat(sdk/python): opencode provider passes --variant reasoning effort

'model#variant' (or an explicit variant option) now maps to opencode run's
--variant flag; the -m flag and cost/metrics reporting use the base model id.

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

* feat(sdk/python): codex provider passes -m and model_reasoning_effort

codex exec previously received no model at all — options['model'] was only
used for cost estimation, so every run used the CLI's own default. Pass
-m <model>, and map a '#variant' suffix to -c model_reasoning_effort=<v>.

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

* fix(sdk/python): claude/gemini providers strip #variant model suffix

Neither runtime has a reasoning-effort control; strip the suffix so the
underlying CLI/SDK still receives a valid model id instead of 'model#variant'.

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

* docs: model selection and #variant reasoning-effort syntax for harness providers

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

* feat(sdk/go): model#variant reasoning-effort parity in harness providers

Mirrors the Python SDK: SplitModelVariant + Options.Variant (explicit field
wins over the suffix), opencode passes --variant, codex adds
-c model_reasoning_effort, claudecode/gemini strip the suffix. The
OpenRouter-attribution overlay and usage recording key off the base model
so a suffix neither defeats the prefix match nor pollutes attribution.

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

* feat(sdk/typescript): model#variant reasoning-effort parity in harness providers

Mirrors the Python SDK: splitModelVariant/resolveModelAndVariant helper,
variant?: string through HarnessConfig/HarnessOptions, opencode passes
--variant, codex now passes -m at all (it previously sent no model to the
CLI — same bug the Python provider had) plus -c model_reasoning_effort,
claude/gemini strip the suffix. Attribution overlay and usage metrics key
off the base model.

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: AbirAbbas

docs/harness-providers.md

@@ -23,6 +23,31 @@ The extras install Python wrappers. They do not replace the runtime preflight:
 Gemini is CLI-only, and Codex or OpenCode may still require a separately
 available executable depending on the wrapper and platform.
 
+## Model selection and reasoning-effort variants
+
+Every provider accepts a `model` option on `.harness()` calls. The model string
+may carry a reasoning-effort variant after a `#` separator:
+
+```python
+result = await app.harness(
+    task,
+    provider="opencode",
+    model="openrouter/z-ai/glm-5.2#high",
+)
+```
+
+An explicit `variant="high"` keyword wins over the suffix. Per provider:
+
+| Provider | Model flag | Variant handling |
+| --- | --- | --- |
+| OpenCode | `-m <model>` | `--variant <v>` (provider-specific effort, e.g. `high`, `max`, `minimal`) |
+| Codex | `-m <model>` | `-c model_reasoning_effort=<v>` |
+| Claude Code | SDK `model` option | No effort control — variant is dropped with a debug log |
+| Gemini | `-m <model>` | No effort control — variant is dropped |
+
+The `#` separator is safe in model ids: `:` belongs to OpenRouter suffixes like
+`:free`, and `@` to Vertex-style ids, but no provider uses `#`.
+
 ## Verify
 
 Check selected providers in a container or CI job before any paid run:

sdk/go/agent/cost_tracker_test.go

@@ -300,4 +300,21 @@ func TestRecordHarnessUsage(t *testing.T) {
 		assert.Equal(t, "openrouter/qwen/qwen3-coder", entries[0]["model"])
 		assert.Equal(t, "openrouter", entries[0]["provider"])
 	})
+
+	t.Run("model variant suffix is stripped for attribution", func(t *testing.T) {
+		a := newAgentForTest(t)
+		tracker := NewCostTracker()
+		ctx := contextWithCostTracker(context.Background(), tracker)
+
+		a.recordHarnessUsage(ctx, &harness.Result{InputTokens: 1}, harness.Options{
+			Provider: "opencode",
+			Model:    "openrouter/z-ai/glm-5.2#high",
+		})
+
+		entries := tracker.Serialize()["entries"].([]map[string]any)
+		require.Len(t, entries, 1)
+		assert.Equal(t, "openrouter/z-ai/glm-5.2", entries[0]["model"],
+			"usage must attribute to the BASE model, not the #variant-suffixed string")
+		assert.Equal(t, "openrouter", entries[0]["provider"])
+	})
 }

sdk/go/agent/harness.go

@@ -13,9 +13,16 @@ type HarnessConfig struct {
 	// Provider is the default provider: "claude-code", "codex", "gemini", or "opencode".
 	Provider string
 
-	// Model is the default model identifier.
+	// Model is the default model identifier. It may carry a
+	// reasoning-effort variant after a "#" separator (e.g.
+	// "openrouter/z-ai/glm-5.2#high").
 	Model string
 
+	// Variant is the default provider-specific reasoning-effort variant
+	// (e.g. "high", "minimal"). It wins over a "#variant" suffix on Model;
+	// providers without an effort control drop it.
+	Variant string
+
 	// MaxTurns is the default max agent iterations.
 	MaxTurns int
 
@@ -48,6 +55,7 @@ func (a *Agent) HarnessRunner() *harness.Runner {
 			hc := a.cfg.HarnessConfig
 			opts.Provider = hc.Provider
 			opts.Model = hc.Model
+			opts.Variant = hc.Variant
 			opts.MaxTurns = hc.MaxTurns
 			opts.PermissionMode = hc.PermissionMode
 			opts.Env = hc.Env

sdk/go/agent/usage.go

@@ -145,6 +145,10 @@ func (a *Agent) recordHarnessUsage(ctx context.Context, result *harness.Result,
 	if model == "" && a.cfg.HarnessConfig != nil {
 		model = a.cfg.HarnessConfig.Model
 	}
+	// Attribute usage to the BASE model: a "#variant" reasoning-effort
+	// suffix is a harness dispatch detail, not part of the model id (the
+	// Python SDK likewise records the provider-reported base model).
+	model, _ = harness.SplitModelVariant(model)
 	if model == "" {
 		model = provider
 	}

sdk/go/harness/claudecode.go

@@ -46,8 +46,13 @@ func (p *ClaudeCodeProvider) Execute(ctx context.Context, prompt string, options
 	// stream-json ("--output-format=stream-json requires --verbose").
 	cmd := []string{p.BinPath, "--print", "--output-format", "stream-json", "--verbose"}
 
-	if options.Model != "" {
-		cmd = append(cmd, "--model", options.Model)
+	// Strip any "#variant" reasoning-effort suffix so the CLI receives a
+	// valid model id. claude-code has no effort flag, so the variant is
+	// dropped (the Python provider logs this at debug level; this package
+	// has no provider-level logger).
+	modelValue, _ := options.resolveModelAndVariant()
+	if modelValue != "" {
+		cmd = append(cmd, "--model", modelValue)
 	}
 
 	if options.MaxTurns > 0 {

sdk/go/harness/claudecode_test.go

@@ -145,3 +145,35 @@ func TestClaudeCodeProvider_ParsesStreamJSONFixture(t *testing.T) {
 		assert.Equal(t, 1, raw.Metrics.NumTurns)
 	})
 }
+
+// TestClaudeCodeProvider_StripsModelVariantSuffix mirrors the Python
+// test_execute_strips_model_variant_suffix: claude-code has no reasoning-
+// effort control, so a "#variant" suffix is stripped from --model (the CLI
+// must receive a valid model id) and the variant is dropped.
+func TestClaudeCodeProvider_StripsModelVariantSuffix(t *testing.T) {
+	p := NewClaudeCodeProvider("claude")
+
+	var gotCmd []string
+	p.runCLI = func(_ context.Context, cmd []string, _ map[string]string, _ string, _ int, _ []byte) (*CLIResult, error) {
+		gotCmd = append([]string(nil), cmd...)
+		return &CLIResult{
+			Stdout:     `{"type":"result","result":"OK","session_id":"s1","num_turns":1}`,
+			ReturnCode: 0,
+		}, nil
+	}
+
+	raw, err := p.Execute(context.Background(), "hello", Options{Model: "sonnet#high"})
+	require.NoError(t, err)
+	require.False(t, raw.IsError, "unexpected error: %s", raw.ErrorMessage)
+
+	require.Contains(t, gotCmd, "--model")
+	for i, arg := range gotCmd {
+		if arg == "--model" {
+			require.Greater(t, len(gotCmd), i+1)
+			assert.Equal(t, "sonnet", gotCmd[i+1],
+				"--model must carry the base model, not the #variant-suffixed string")
+		}
+	}
+	assert.NotContains(t, gotCmd, "sonnet#high")
+	assert.NotContains(t, gotCmd, "--variant")
+}

sdk/go/harness/codex.go

@@ -65,9 +65,15 @@ func (p *CodexProvider) Execute(ctx context.Context, prompt string, options Opti
 
 	// Pass the model through with -m. SWE-AF resolves gpt-5.5 vs gpt-5.3-codex by
 	// auth mode and relies on the value reaching the CLI; the old provider
-	// ignored options.Model entirely.
-	if options.Model != "" {
-		cmd = append(cmd, "-m", options.Model)
+	// ignored options.Model entirely. Reasoning effort has no dedicated flag —
+	// it's the model_reasoning_effort config key, fed by a "#variant" suffix
+	// on the model (or an explicit Options.Variant), e.g. "gpt-5.3-codex#high".
+	modelValue, variantValue := options.resolveModelAndVariant()
+	if modelValue != "" {
+		cmd = append(cmd, "-m", modelValue)
+	}
+	if variantValue != "" {
+		cmd = append(cmd, "-c", "model_reasoning_effort="+variantValue)
 	}
 
 	// permission_mode → sandbox policy (port of codex_harness_patch.py:165-170).

sdk/go/harness/codex_test.go

@@ -306,3 +306,61 @@ func toStringSlice(v any) []string {
 		return nil
 	}
 }
+
+// TestCodexProvider_ModelVariantReasoningEffort pins the model#variant parity
+// matrix from the Python provider tests (test_harness_provider_codex.py):
+// -m always carries the BASE model, a "#variant" suffix (or an explicit
+// Options.Variant, which wins) becomes -c model_reasoning_effort=<v>, and a
+// bare model adds no -c at all.
+func TestCodexProvider_ModelVariantReasoningEffort(t *testing.T) {
+	run := func(t *testing.T, options Options) []string {
+		t.Helper()
+		var gotCmd []string
+		p := NewCodexProvider("codex")
+		p.runCLI = func(_ context.Context, cmd []string, _ map[string]string, _ string, _ int, _ []byte) (*CLIResult, error) {
+			gotCmd = append([]string(nil), cmd...)
+			return &CLIResult{Stdout: `{"type":"turn.completed","text":"ok"}`, ReturnCode: 0}, nil
+		}
+		raw, err := p.Execute(context.Background(), "hello", options)
+		require.NoError(t, err)
+		require.False(t, raw.IsError, "unexpected error: %s", raw.ErrorMessage)
+		return gotCmd
+	}
+
+	index := func(cmd []string, flag string) int {
+		for i, arg := range cmd {
+			if arg == flag {
+				return i
+			}
+		}
+		return -1
+	}
+
+	t.Run("suffix maps to model_reasoning_effort", func(t *testing.T) {
+		cmd := run(t, Options{Model: "gpt-5.3-codex#high"})
+		mIdx := index(cmd, "-m")
+		require.GreaterOrEqual(t, mIdx, 0)
+		assert.Equal(t, "gpt-5.3-codex", cmd[mIdx+1], "-m must carry the base model, never the suffixed string")
+		cIdx := index(cmd, "-c")
+		require.GreaterOrEqual(t, cIdx, 0)
+		assert.Equal(t, "model_reasoning_effort=high", cmd[cIdx+1])
+	})
+
+	t.Run("explicit variant wins over suffix", func(t *testing.T) {
+		cmd := run(t, Options{Model: "gpt-5.5#low", Variant: "max"})
+		mIdx := index(cmd, "-m")
+		require.GreaterOrEqual(t, mIdx, 0)
+		assert.Equal(t, "gpt-5.5", cmd[mIdx+1])
+		cIdx := index(cmd, "-c")
+		require.GreaterOrEqual(t, cIdx, 0)
+		assert.Equal(t, "model_reasoning_effort=max", cmd[cIdx+1])
+	})
+
+	t.Run("bare model has no effort config", func(t *testing.T) {
+		cmd := run(t, Options{Model: "gpt-5.5"})
+		mIdx := index(cmd, "-m")
+		require.GreaterOrEqual(t, mIdx, 0)
+		assert.Equal(t, "gpt-5.5", cmd[mIdx+1])
+		assert.NotContains(t, cmd, "-c")
+	})
+}

sdk/go/harness/gemini.go

@@ -35,8 +35,11 @@ func (p *GeminiProvider) Execute(ctx context.Context, prompt string, options Opt
 		cmd = append(cmd, "--sandbox")
 	}
 
-	if options.Model != "" {
-		cmd = append(cmd, "-m", options.Model)
+	// gemini has no reasoning-effort flag; strip any "#variant" suffix so
+	// the CLI still receives a valid model id, and drop the variant.
+	modelValue, _ := options.resolveModelAndVariant()
+	if modelValue != "" {
+		cmd = append(cmd, "-m", modelValue)
 	}
 
 	// Prompt passed via -p flag.

sdk/go/harness/model.go

@@ -0,0 +1,38 @@
+package harness
+
+import "strings"
+
+// ModelVariantSep separates the base model id from a reasoning-effort variant
+// in the "provider/model#variant" model-string syntax. "#" is safe because
+// provider model ids never contain it (":" is taken by OpenRouter suffixes
+// like ":free", "@" by Vertex-style ids).
+const ModelVariantSep = "#"
+
+// SplitModelVariant splits a "provider/model#variant" string into its base
+// model and variant parts.
+//
+// The "#variant" suffix carries a provider-specific reasoning-effort variant
+// (e.g. "high", "minimal") through config surfaces that only hold a model
+// string. The split happens on the FIRST separator and both parts are
+// whitespace-trimmed. A bare model string passes through as (model, "");
+// an empty or blank input yields ("", ""). Mirrors the Python SDK's
+// split_model_variant (harness/_cli.py).
+func SplitModelVariant(model string) (base, variant string) {
+	if strings.TrimSpace(model) == "" {
+		return "", ""
+	}
+	base, variant, _ = strings.Cut(model, ModelVariantSep)
+	return strings.TrimSpace(base), strings.TrimSpace(variant)
+}
+
+// resolveModelAndVariant resolves the (model, variant) pair for a harness
+// invocation. An explicit Options.Variant wins over a "#variant" suffix on
+// Options.Model; the returned model never carries the suffix. Mirrors the
+// Python SDK's resolve_model_and_variant (harness/_cli.py).
+func (o Options) resolveModelAndVariant() (model, variant string) {
+	model, variant = SplitModelVariant(o.Model)
+	if explicit := strings.TrimSpace(o.Variant); explicit != "" {
+		variant = explicit
+	}
+	return model, variant
+}