feat: Add user-configurable settings for reasoning and text verbosity #6

ben-vargas · 2025-10-03T08:16:22Z

Summary

This PR adds comprehensive user-configurable settings support to the plugin, allowing users to customize reasoning effort, reasoning summaries, text verbosity, and response fields for both gpt-5 and gpt-5-codex models through opencode's configuration system.

What's New

🎛️ User-Configurable Settings

Users can now customize model behavior via opencode.json configuration:

reasoningEffort: Control computational effort (minimal, low, medium, high)
reasoningSummary: Control summary verbosity (auto, detailed)
textVerbosity: Control output length (low, medium, high - codex only supports medium)
include: Additional response fields (default: ["reasoning.encrypted_content"] for stateless reasoning)

🎯 Flexible Configuration Patterns

The plugin supports three configuration patterns following Anthropic's configuration approach:

Global options: Apply same settings to all GPT-5 models
Per-model options: Different settings for gpt-5 vs gpt-5-codex
Mixed configuration: Global defaults with per-model overrides

Per-model options take precedence over global options when both are specified.

📊 Updated Plugin Defaults

The plugin defaults have been updated to match Codex CLI behavior and provide better out-of-the-box performance:

New defaults (v1.0.4):

{
  "reasoningEffort": "medium",
  "reasoningSummary": "auto",
  "textVerbosity": "medium",
  "include": ["reasoning.encrypted_content"]
}

Previous defaults (v1.0.3):

{
  "reasoningEffort": "high",
  "reasoningSummary": "detailed",
  "textVerbosity": "medium"
}

Changes:

reasoningEffort: Changed from high → medium (more balanced performance/cost)
reasoningSummary: Changed from detailed → auto (matches Codex CLI default)
include: Added ["reasoning.encrypted_content"] (critical for stateless multi-turn conversations)

The include: ["reasoning.encrypted_content"] default is critical for stateless operation (store: false), allowing reasoning context to persist across turns without server-side storage.

✅ Model-Specific Validation

The implementation includes model-specific restrictions based on comprehensive testing:

GPT-5 Model:

reasoningEffort: minimal, low, medium, high
reasoningSummary: auto, detailed
textVerbosity: low, medium, high

GPT-5-Codex Model:

reasoningEffort: minimal* (auto-normalized to low), low, medium, high
reasoningSummary: auto, detailed
textVerbosity: medium only

Both Models:

include: Array of strings (default: ["reasoning.encrypted_content"])

* The plugin automatically normalizes minimal → low for gpt-5-codex to match Codex CLI behavior.

Implementation Details

Configuration Loader (`index.mjs`)

Extracts user configuration from opencode's provider options
Supports both provider.openai.options (global) and provider.openai.models.{model}.options (per-model)
Passes configuration to request transformer

Request Transformer (`lib/request-transformer.mjs`)

New getModelConfig(): Merges global + per-model options (per-model overrides)
Enhanced getReasoningConfig(): Accepts user config, applies defaults, normalizes values
Enhanced transformRequestBody(): Applies user-configured text verbosity, reasoning settings, and include fields
Automatic normalization of minimal → low for gpt-5-codex
Configurable include field with default for encrypted reasoning content

Testing (`test-config.mjs`)

Comprehensive unit tests for configuration parsing
Tests global options, per-model options, and mixed configurations
Validates merging logic and default values
Run with: node test-config.mjs

Documentation

Updated README.md with:

Clear tables showing supported values for each model (including include setting)
Three configuration examples (global, per-model, mixed)
Plugin defaults section explaining the importance of reasoning.encrypted_content
Model-specific restrictions and warnings

Example Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-openai-codex-auth"],
  "model": "openai/gpt-5-codex",
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "medium",
        "reasoningSummary": "auto",
        "textVerbosity": "medium",
        "include": ["reasoning.encrypted_content"]
      },
      "models": {
        "gpt-5-codex": {
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "detailed"
          }
        }
      }
    }
  }
}

To restore v1.0.3 behavior:

{
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "high",
        "reasoningSummary": "detailed"
      }
    }
  }
}

Testing

All configuration patterns have been tested with:

Request logging verification (ENABLE_PLUGIN_REQUEST_LOGGING=1)
Systematic testing of all value combinations for reasoning and text verbosity
Validation against ChatGPT backend API responses
Unit tests for configuration parsing and merging logic

Commits

feat: Add user-configurable settings support - Core implementation
test: Add configuration parsing tests - Unit tests for config loader
docs: Update README with configuration documentation - Complete user documentation
fix: Normalize 'minimal' to 'low' for gpt-5-codex - Match Codex CLI behavior
chore: Bump version to 1.0.4 - Version update for new feature

Breaking Changes

Default behavior has changed:

Users upgrading from v1.0.3 to v1.0.4 will experience different default reasoning behavior:

Reasoning effort reduced from high → medium (more balanced dynamic behavior, recommended by OpenAI)
Reasoning summary changed from detailed → auto (adaptive verbosity)
Added encrypted reasoning content for better multi-turn conversations

Rationale: The new defaults match Codex CLI behavior and provide better out-of-the-box performance. The previous high effort setting is against default Codex CLI behavior and OpenAI's recommendation of medium which will dynamically think longer or shorter - also improved speed for users.

To restore v1.0.3 behavior: Add the configuration shown in the example above to explicitly set reasoningEffort: "high" and reasoningSummary: "detailed".

- Add getModelConfig() to merge global and per-model options - Update getReasoningConfig() to accept user configuration - Change defaults: effort from 'high' to 'medium', summary from 'detailed' to 'auto' - Matches Codex CLI defaults for ChatGPT backend API - Update transformRequestBody() to use user configuration - Support configurable textVerbosity (default: 'medium') - Add include parameter for encrypted reasoning content - Update index.mjs loader to extract provider configuration - Follows Anthropic pattern: uses 'openai' provider for both OAuth and API key - Supports both global options and per-model options - Enhanced logging to track textVerbosity and include in requests Configuration structure: - Global options: provider.openai.options - Per-model options: provider.openai.models['gpt-5-codex'].options - Supported settings: reasoningEffort, reasoningSummary, textVerbosity, include See SETTINGS.md for full implementation details and examples.

- Create test-config.json with example global and per-model options - Add test-config.mjs to verify configuration merging logic - All 5 tests pass: ✓ gpt-5-codex merges global + per-model options correctly ✓ gpt-5 merges global + per-model options correctly ✓ Reasoning config uses merged options ✓ Defaults work with empty config (medium/auto) ✓ Lightweight models get minimal effort by default

- Add Configuration section with all settings and examples - Update Usage section to reflect new defaults (medium/auto instead of high/detailed) - Add support for both gpt-5 and gpt-5-codex models - Show global, per-model, and mixed configuration examples - Update How It Works section with encrypted reasoning - Remove outdated limitation about hardcoded text verbosity - Link to SETTINGS.md for implementation details

Codex CLI does not provide a 'minimal' reasoning effort preset for gpt-5-codex (only low/medium/high - see model_presets.rs:20-40). When users configure reasoningEffort: 'minimal' for gpt-5-codex, normalize it to 'low' to prevent unsupported configuration. - Add validation in getReasoningConfig() to detect and normalize - Add test case to verify normalization works correctly - Prevents potential errors when backend receives unsupported effort level Addresses feedback from GPT-5 Codex code review.

Copilot

Pull Request Overview

This PR adds comprehensive user-configurable settings support to the OpenAI Codex authentication plugin, allowing users to customize reasoning effort, reasoning summaries, text verbosity, and response fields for both gpt-5 and gpt-5-codex models through opencode's configuration system.

Key changes:

Implementation of user-configurable settings with global and per-model options
Updated plugin defaults from high/detailed to medium/auto for better performance
Addition of encrypted reasoning content support for stateless multi-turn conversations

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test-config.mjs	Test suite for configuration parsing and merging logic
test-config.json	Example configuration file for testing
package.json	Version bump to 1.0.4
lib/request-transformer.mjs	Core implementation of configuration parsing and request transformation
index.mjs	Configuration loader integration with provider options
README.md	Comprehensive documentation of configuration options and examples

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-03T10:17:06Z

test-config.mjs

+	models: {
+		"gpt-5-codex": {
+			options: {
+				reasoningSummary: "concise", // Override global


The value 'concise' is not a valid reasoningSummary option. According to the README documentation, only 'auto' and 'detailed' are supported values.

Suggested change

reasoningSummary: "concise", // Override global

reasoningSummary: "detailed", // Override global

I'd probably leave this in for now, "concise" is returned by the error message as a valid value but not actually supported - so maybe they're going to add it, maybe not - doesn't hurt anything to be in the test while the API reports it as valid.

numman-ali · 2025-10-03T14:48:21Z

Thank you @ben-vargas !

Will review tonight

ben-vargas · 2025-10-03T14:49:56Z

Cool, thanks!

numman-ali · 2025-10-03T19:10:39Z

@ben-vargas this looks good ! I'm going to merge it in, and then follow up with some tweaks before publishing a new version

Should be only around half an hour

ben-vargas · 2025-10-03T19:11:38Z

Awesome, sounds good - thanks!

ben-vargas added 5 commits October 2, 2025 15:38

chore: Bump version to 1.0.4

6ce2713

numman-ali requested a review from Copilot October 3, 2025 10:16

Copilot AI reviewed Oct 3, 2025

View reviewed changes

numman-ali merged commit 1b57022 into numman-ali:main Oct 3, 2025

ben-vargas deleted the config-support branch October 4, 2025 06:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add user-configurable settings for reasoning and text verbosity #6

feat: Add user-configurable settings for reasoning and text verbosity #6

Uh oh!

ben-vargas commented Oct 3, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 3, 2025

Uh oh!

ben-vargas Oct 3, 2025

Uh oh!

numman-ali commented Oct 3, 2025

Uh oh!

ben-vargas commented Oct 3, 2025

Uh oh!

numman-ali commented Oct 3, 2025

Uh oh!

ben-vargas commented Oct 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	reasoningSummary: "concise", // Override global
	reasoningSummary: "detailed", // Override global

feat: Add user-configurable settings for reasoning and text verbosity #6

feat: Add user-configurable settings for reasoning and text verbosity #6

Uh oh!

Conversation

ben-vargas commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's New

🎛️ User-Configurable Settings

🎯 Flexible Configuration Patterns

📊 Updated Plugin Defaults

✅ Model-Specific Validation

Implementation Details

Configuration Loader (index.mjs)

Request Transformer (lib/request-transformer.mjs)

Testing (test-config.mjs)

Documentation

Example Configuration

Testing

Commits

Breaking Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

ben-vargas Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

numman-ali commented Oct 3, 2025

Uh oh!

ben-vargas commented Oct 3, 2025

Uh oh!

numman-ali commented Oct 3, 2025

Uh oh!

ben-vargas commented Oct 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ben-vargas commented Oct 3, 2025 •

edited

Loading

Configuration Loader (`index.mjs`)

Request Transformer (`lib/request-transformer.mjs`)

Testing (`test-config.mjs`)