Portable Options Reference

AgentOptions

AgentOptions is the portable interface that all provider-specific options extend. It defines the common surface that works identically across Claude, Codex, and Gemini.

public interface AgentOptions {
    String getModel();
    Duration getTimeout();
}

Each provider adds its own options beyond this interface — see the provider-specific reference pages for details.

Configuration Precedence

Agent behavior is determined by a layered precedence system. Higher layers override lower ones:

Explicit goal options      (highest — per-request)
Builder configuration      (per-client instance)
Spring properties          (application.yml / env vars)
Mode-derived defaults      (from AgentClientMode)
Hardcoded defaults         (lowest — in code)

Explicit always wins. If you set agent-client.codex.skip-git-check=true alongside agent-client.mode=strict, the explicit property wins. See Defaults Philosophy for the full rationale.

Example: Precedence in Action

agent-client:
  mode: strict
  codex:
    skip-git-check: true    # Explicit property overrides STRICT
    model: o3-mini           # Overrides hardcoded default (gpt-5-codex)

Result: Codex runs in STRICT mode except skipGitCheck is true because the explicit property takes precedence.

Mode System

AgentClientMode is a portable enum controlling default permissiveness:

Mode	Behavior	When to Use
`LOOSE` (default)	Minimize preconditions — works in any directory	Evaluation, development, tutorials
`STRICT`	Conservative — requires explicit opt-in	Production, CI, shared environments

agent-client:
  mode: loose    # or strict

See Defaults Philosophy for detailed mode-vs-property interaction examples.

Promotion Rubric

Provider-specific options graduate to the portable AgentOptions interface when all three conditions hold:

Two or more providers have a semantic equivalent
Absence causes failures on easy-tier benchmarks (evidence, not speculation)
The option can be expressed without leaking provider-specific concepts

Options that don’t meet the rubric remain in the provider-specific namespace indefinitely. This is intentional — not every option should be portable.

Current Portable Options

Option	Claude	Codex	Gemini	Status
`model`	`claude-sonnet-4-5`	`gpt-5-codex`	`gemini-2.5-flash`	Portable
`timeout`	5m	5m	5m	Portable
`effort`	`--effort`	`model_reasoning_effort`	ignored (no effort knob)	Portable (`low`/`medium`/`high`; native ranges are wider)

Provider-Specific (Not Promoted)

Option	Provider	Why Not Portable
`skipGitCheck`	Codex	Only Codex has a git directory gate
`maxThinkingTokens`	Claude	Claude-specific extended thinking
`yolo`	Claude, Gemini	Codex uses `fullAuto` — different semantics
`temperature`	Gemini	Not exposed by Claude/Codex CLIs

Provider Reference Pages

Claude

18 properties — agent-client.claude.*

Codex

6 properties — agent-client.codex.*

Gemini

6 properties — agent-client.gemini.*

​AgentOptions

​Configuration Precedence

​Example: Precedence in Action

​Mode System

​Promotion Rubric

​Current Portable Options

​Provider-Specific (Not Promoted)

​Provider Reference Pages

Claude

Codex

Gemini

AgentOptions

Configuration Precedence

Example: Precedence in Action

Mode System

Promotion Rubric

Current Portable Options

Provider-Specific (Not Promoted)

Provider Reference Pages