Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix: pass reasoning effort through to Codex (#1237)

mldangelo-oai6e9adf21b156
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
index cb7388445..92ab8abf2 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
@@ -1102,7 +1102,9 @@ async function testWorkerRuntimeSettings() {
await mkdir(codexHome);
await writeFile(
path.join(codexHome, "config.toml"),
- `model_provider = "synthetic"
+ `model = "fixture-inherited-model"
+model_reasoning_effort = "medium"
+model_provider = "synthetic"
[model_providers.synthetic]
name = "Synthetic gateway"
base_url = "https://gateway.example.test/v1"
@@ -1154,12 +1156,13 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
{ model: "gpt-6-astra", reasoningEffort: "ultra" },
{ model: "gpt-6.1-sol", reasoningEffort: "max" },
{ model: "gpt-6-sol", reasoningEffort: "high" },
+ { model: "fixture-future-model", reasoningEffort: "future-effort" },
+ // Omitted settings preserve the model and effort in the Codex home.
+ {},
];
- const providerKeys = [
- "synthetic-gateway-key-0",
- "synthetic-gateway-key-1",
- undefined,
- ];
+ const providerKeys = settings.map((_, index) =>
+ index < 2 ? `synthetic-gateway-key-${index}` : undefined,
+ );
const executors = settings.map(
(modelSettings) =>
new CodexSdkWorkerExecutor({
@@ -1168,7 +1171,7 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
artifactContext: {
pluginRoot: fixture.root,
repoRoot: fixture.root,
- scanId: `fixture-scan-${modelSettings.model}`,
+ scanId: `fixture-scan-${modelSettings.model ?? "inherited"}`,
pythonCommand: helperPython,
},
}),
@@ -1215,8 +1218,10 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
index,
{ model, reasoningEffort },
] of settings.entries()) {
- const workerLaunch = workerLaunches.find(
- ({ args }) => args[args.indexOf("--model") + 1] === model,
+ const workerLaunch = workerLaunches.find(({ args }) =>
+ model === undefined
+ ? !args.includes("--model")
+ : args[args.indexOf("--model") + 1] === model,
);
assert.ok(workerLaunch, `missing worker launch for ${model}`);
assert.equal(
@@ -1254,9 +1259,20 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
);
assertConfigOverrides(invocation.argv, {
model_reasoning_summary: expected,
- model_reasoning_effort: reasoningEffort,
});
- assertFlagPair(invocation.argv, "--model", model);
+ assert.deepEqual(
+ invocation.argv.filter((arg: string) =>
+ arg.startsWith("model_reasoning_effort="),
+ ),
+ reasoningEffort === undefined
+ ? []
+ : [`model_reasoning_effort=${JSON.stringify(reasoningEffort)}`],
+ );
+ if (model === undefined) {
+ assert.equal(invocation.argv.includes("--model"), false);
+ } else {
+ assertFlagPair(invocation.argv, "--model", model);
+ }
assert.equal(
invocation.argv.includes("resume"),
resumeThreadId !== undefined,
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 4ef0de962..6e9d8a635 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -969,15 +969,16 @@ max_concurrent_threads_per_session = 9
sandbox = "unelevated"
```
-Use `--model` to choose a model and `--effort minimal|low|medium|high|xhigh|max`
+Use `--model MODEL` to choose a model and `--effort EFFORT`
for reasoning effort. Both flags work with `scan`, `bulk-scan`, `scan-components`,
`policy`, `validate`, `patch`, `verify-fix`, `suggest-owners`, `classify-severity`,
`scans match`, and `scans compare`.
-Model IDs are passed through to Codex, including `gpt-6-astra`, `gpt-6.1-sol`,
-and `gpt-6-luna`; availability depends on your credentials and inference provider.
-For Astra and GPT-6.1 Sol, use `low`, `medium`, `high`, `xhigh`, or `max`, as
-documented in the [OpenAI model guide](https://developers.openai.com/api/docs/guides/latest-model).
+Model IDs and reasoning effort values are passed through to Codex unchanged.
+The wrapper accepts values such as `minimal`, `none`, and `high`, as
+well as future values, without requiring a wrapper update. Supported combinations
+depend on the model, inference provider, installed Codex version, and credentials.
+Codex and provider errors are reported without substituting another model or effort.
Omitting these flags preserves each command's defaults: scans, policy generation,
validation, patching, verification, and owner suggestions use `gpt-5.6-sol`/`xhigh`;
matching and severity classification use Codex's configured model and `medium` effort.
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 99225d46d..011faaa6c 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -307,14 +307,6 @@ type Writable = Pick<NodeJS.WriteStream, "write"> & {
};
type SignalName = "SIGINT" | "SIGTERM";
-const MODEL_REASONING_EFFORTS = [
- "minimal",
- "low",
- "medium",
- "high",
- "xhigh",
- "max",
-] as const;
const DEFAULT_SCAN_MODEL_CONFIGURATION =
scanModelConfiguration(DEFAULT_CODEX_CONFIG);
const MODEL_OPTIONS = modelOptions();
@@ -985,12 +977,11 @@ function modelOptions(
) {
return z.object({
model: optionValue("--model").optional().describe(modelDescription),
- effort: z
- .enum(MODEL_REASONING_EFFORTS, {
- error: "--effort must be minimal, low, medium, high, xhigh, or max.",
- })
+ effort: optionValue("--effort")
.optional()
- .describe(effortDescription),
+ .describe(
+ `${effortDescription} Passed through to Codex; supported values depend on the model, provider, and Codex version.`,
+ ),
});
}
diff --git a/sdk/typescript/src/scan-comparison.ts b/sdk/typescript/src/scan-comparison.ts
index 42d4cb2c2..c7f74916d 100644
--- a/sdk/typescript/src/scan-comparison.ts
+++ b/sdk/typescript/src/scan-comparison.ts
@@ -145,8 +145,8 @@ export interface ReadOnlyCodexOptions {
codex?: ReadOnlyCodex;
environment?: NodeJS.ProcessEnv;
model?: string;
- reasoningEffort?:
- "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+ /** Passed through to Codex; support depends on the runtime, model, and provider. */
+ reasoningEffort?: string;
signal?: AbortSignal;
workingDirectory?: string;
}
@@ -522,9 +522,7 @@ async function startReadOnlyCodexThread(
config === undefined ? undefined : scanModelConfiguration(config);
const model = options.model ?? configuredModel?.model;
const reasoningEffort =
- options.reasoningEffort ??
- (configuredModel?.reasoningEffort as ModelReasoningEffort | undefined) ??
- "medium";
+ options.reasoningEffort ?? configuredModel?.reasoningEffort ?? "medium";
const source = options.environment ?? process.env;
const providerConfig =
options.codex === undefined
@@ -617,6 +615,7 @@ async function startReadOnlyCodexThread(
return codex.startThread({
threadSource: runtimeOptions.threadSource,
...(model === undefined ? {} : { model }),
+ // Native Codex accepts strings before the pinned SDK widens its effort type.
modelReasoningEffort: reasoningEffort as ModelReasoningEffort,
sandboxMode: "read-only",
approvalPolicy: "never",
diff --git a/sdk/typescript/src/suggest-owners.ts b/sdk/typescript/src/suggest-owners.ts
index e807a82ba..d686f5783 100644
--- a/sdk/typescript/src/suggest-owners.ts
+++ b/sdk/typescript/src/suggest-owners.ts
@@ -98,10 +98,7 @@ export async function suggestOwnersInternal(
await mergedCodexConfig(options.config ?? {}),
);
const model = options.model ?? configured.model;
- const reasoningEffort = (options.reasoningEffort ??
- configured.reasoningEffort) as NonNullable<
- SuggestOwnersOptions["reasoningEffort"]
- >;
+ const reasoningEffort = options.reasoningEffort ?? configured.reasoningEffort;
const report: OwnerSuggestions = {
schemaVersion: 1,
revision: git.revision,
diff --git a/sdk/typescript/tests-ts/classify-severity.test.ts b/sdk/typescript/tests-ts/classify-severity.test.ts
index 4fbbada64..3111de2cd 100644
--- a/sdk/typescript/tests-ts/classify-severity.test.ts
+++ b/sdk/typescript/tests-ts/classify-severity.test.ts
@@ -100,7 +100,7 @@ test("supplies complete evidence and separate policy/context to a restricted str
codex,
signal,
model: "synthetic-model",
- reasoningEffort: "high",
+ reasoningEffort: "future-effort",
});
expect(result.assessments[0]).toMatchObject({
...assessed,
@@ -114,7 +114,7 @@ test("supplies complete evidence and separate policy/context to a restricted str
expect(calls[0]!.thread).toMatchObject({
threadSource: "security_severity_classification",
model: "synthetic-model",
- modelReasoningEffort: "high",
+ modelReasoningEffort: "future-effort",
sandboxMode: "read-only",
approvalPolicy: "never",
networkAccessEnabled: false,
diff --git a/sdk/typescript/tests-ts/cli-skills.test.ts b/sdk/typescript/tests-ts/cli-skills.test.ts
index 38930d3bb..3b7664cff 100644
--- a/sdk/typescript/tests-ts/cli-skills.test.ts
+++ b/sdk/typescript/tests-ts/cli-skills.test.ts
@@ -955,7 +955,11 @@ describe("CLI skill commands", () => {
test.each(["validate", "patch", "verify-fix"] as const)(
"selects the model and reasoning effort directly for %s",
async (command) => {
- for (const model of ["gpt-6-astra", "gpt-6.1-sol"]) {
+ for (const [model, effort] of [
+ ["gpt-6-astra", "max"],
+ ["gpt-6.1-sol", "max"],
+ ["synthetic-future-model", "synthetic-future-effort"],
+ ] as const) {
let invocation: readonly string[] = [];
const stderr = captureCli(main, "stderr");
expect(
@@ -967,7 +971,7 @@ describe("CLI skill commands", () => {
? ["--model", model]
: [`--model=${model}`]),
"--effort",
- "max",
+ effort,
],
dependencies({
onCodex: (args, output) => {
@@ -992,14 +996,11 @@ describe("CLI skill commands", () => {
stderr.text(),
).toBe(0);
expect(invocation).toContain(`model="${model}"`);
- expect(invocation).toContain('model_reasoning_effort="max"');
+ expect(invocation).toContain(`model_reasoning_effort="${effort}"`);
}
for (const [options, message] of [
- [
- ["--effort", "ultra"],
- "--effort must be minimal, low, medium, high, xhigh, or max",
- ],
+ [["--effort="], "--effort must not be empty"],
[
["--effort", "high", "--codex", 'model_reasoning_effort="medium"'],
"--effort conflicts with --codex model_reasoning_effort",
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index bedd10381..200d07c7d 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -170,7 +170,8 @@ describe("CLI", () => {
verbose: { type: "boolean" },
showCost: { type: "boolean", default: false },
effort: {
- enum: ["minimal", "low", "medium", "high", "xhigh", "max"],
+ type: "string",
+ minLength: 1,
},
provider: {
enum: ["openai", "openrouter", "fireworks", "amazon-bedrock"],
@@ -865,6 +866,43 @@ describe("CLI", () => {
}
});
+ test("surfaces unsupported effort errors without substituting settings or retrying", async () => {
+ const model = "synthetic-future-model";
+ const effort = "synthetic-future-effort";
+ const message = `Provider does not support reasoning effort '${effort}' for model '${model}'.`;
+ const stdout = capture();
+ const stderr = capture();
+ const deps = dependencies();
+ const run = mock(async () => {
+ throw new CodexSecurityError(message);
+ });
+ const createSecurity = mock((_config: CodexSecurityConfig) =>
+ fakeSecurity(run),
+ );
+ deps.createSecurity = createSecurity;
+
+ expect(
+ await main(
+ ["scan", ".", "--model", model, "--effort", effort, "--json"],
+ stdout.stream,
+ stderr.stream,
+ deps,
+ ),
+ ).toBe(2);
+ expect(createSecurity).toHaveBeenCalledTimes(1);
+ expect(createSecurity.mock.lastCall?.[0].codexOverrides).toEqual({
+ model,
+ model_reasoning_effort: effort,
+ });
+ expect(run).toHaveBeenCalledTimes(1);
+ expect(JSON.parse(stdout.text())).toEqual({
+ status: "failed",
+ code: "SCAN_FAILED",
+ message,
+ });
+ expect(stderr.text()).toContain(message);
+ });
+
test.each([
[
"OpenRouter",
@@ -2315,8 +2353,22 @@ describe("CLI", () => {
],
[["--model=gpt-5.6-sol"], { model: "gpt-5.6-sol" }],
[["--effort", "minimal"], { model_reasoning_effort: "minimal" }],
+ [["--effort", "none"], { model_reasoning_effort: "none" }],
+ [["--effort", "ultra"], { model_reasoning_effort: "ultra" }],
[["--effort=xhigh"], { model_reasoning_effort: "xhigh" }],
[["--effort", "max"], { model_reasoning_effort: "max" }],
+ [
+ [
+ "--model",
+ "synthetic-future-model",
+ "--effort",
+ "synthetic-future-effort",
+ ],
+ {
+ model: "synthetic-future-model",
+ model_reasoning_effort: "synthetic-future-effort",
+ },
+ ],
[
["--model", "gpt-5.6-terra", "--effort", "high"],
{ model: "gpt-5.6-terra", model_reasoning_effort: "high" },
@@ -2705,10 +2757,7 @@ describe("CLI", () => {
["scan", ".", "--provider", "fireworks"],
"--model is required when using --provider fireworks",
],
- [
- ["scan", ".", "--effort", "ultra"],
- "--effort must be minimal, low, medium, high, xhigh, or max",
- ],
+ [["scan", ".", "--effort="], "--effort must not be empty"],
[["scan", ".", "--mode", "bogus"], "Invalid option"],
[["scan", ".", "--unknown"], "Unknown flag: --unknown"],
[["scan", ".", "--path", "--dry-run"], "Missing value for flag"],
diff --git a/sdk/typescript/tests-ts/effort-forwarding.test.ts b/sdk/typescript/tests-ts/effort-forwarding.test.ts
new file mode 100644
index 000000000..e11220686
--- /dev/null
+++ b/sdk/typescript/tests-ts/effort-forwarding.test.ts
@@ -0,0 +1,114 @@
+import { Codex } from "@openai/codex-sdk";
+import { afterEach, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DEFAULT_CODEX_CONFIG, scanModelConfiguration } from "../src/config.js";
+import {
+ runReadOnlyCodex,
+ type ReadOnlyCodexOptions,
+} from "../src/scan-comparison.js";
+import { nodeCommand } from "./support/shell.js";
+import { createTemporaryDirectories } from "./support/temporary-directories.js";
+
+const directories = createTemporaryDirectories();
+afterEach(directories.cleanup);
+
+test("forwards resolved efforts through the SDK independently for concurrent threads", async () => {
+ const root = await directories.create("codex-security-effort-");
+ const repository = join(root, "repository");
+ const preload = join(root, "capture-codex.mjs");
+ await mkdir(repository);
+ await writeFile(
+ preload,
+ [
+ "for await (const _chunk of process.stdin) {}",
+ "const send = (event) => console.log(JSON.stringify(event));",
+ 'send({ type: "thread.started", thread_id: "fixture-thread" });',
+ 'send({ type: "item.completed", item: { id: "reply", type: "agent_message", text: JSON.stringify(process.argv.slice(2)) } });',
+ 'send({ type: "turn.completed", usage: { input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 } });',
+ "process.exit(0);",
+ ].join("\n"),
+ );
+ const codex = new Codex({
+ codexPathOverride: nodeCommand().command,
+ env: {
+ NODE_OPTIONS: `--import=${pathToFileURL(preload).href}`,
+ ...(process.env["SystemRoot"] === undefined
+ ? {}
+ : { SystemRoot: process.env["SystemRoot"] }),
+ },
+ });
+ const configuredProfile = {
+ codexOverrides: {
+ model: "fixture-global-model",
+ model_reasoning_effort: "high",
+ profile: "selected",
+ profiles: {
+ selected: {
+ model: "fixture-future-model",
+ model_reasoning_effort: "future-effort",
+ },
+ },
+ },
+ };
+ const defaults = scanModelConfiguration(DEFAULT_CODEX_CONFIG);
+ const cases: {
+ options: ReadOnlyCodexOptions;
+ model?: string;
+ effort: string;
+ }[] = [
+ { options: {}, effort: "medium" },
+ {
+ options: { config: {} },
+ model: defaults.model,
+ effort: defaults.reasoningEffort,
+ },
+ {
+ options: {
+ config: {
+ codexOverrides: {
+ model: "fixture-legacy-model",
+ model_reasoning_effort: "minimal",
+ },
+ },
+ },
+ model: "fixture-legacy-model",
+ effort: "minimal",
+ },
+ {
+ options: { config: configuredProfile },
+ model: "fixture-future-model",
+ effort: "future-effort",
+ },
+ {
+ options: {
+ config: configuredProfile,
+ model: "fixture-explicit-model",
+ reasoningEffort: "none",
+ },
+ model: "fixture-explicit-model",
+ effort: "none",
+ },
+ ];
+
+ await Promise.all(
+ cases.map(async ({ options, model, effort }) => {
+ const response = await runReadOnlyCodex(
+ "Capture the invocation.",
+ {},
+ { ...options, codex, workingDirectory: repository },
+ { surface: "sdk", threadSource: "security_scan_comparison" },
+ );
+ const args: string[] = JSON.parse(response);
+ expect(
+ args.filter((arg) => arg.startsWith("model_reasoning_effort=")),
+ ).toEqual([`model_reasoning_effort=${JSON.stringify(effort)}`]);
+ if (model === undefined) {
+ expect(args).not.toContain("--model");
+ } else {
+ expect(args[args.indexOf("--model") + 1]).toBe(model);
+ }
+ }),
+ );
+});
diff --git a/sdk/typescript/tests-ts/scan-comparison.test.ts b/sdk/typescript/tests-ts/scan-comparison.test.ts
index 36bec6e48..8b34c998f 100644
--- a/sdk/typescript/tests-ts/scan-comparison.test.ts
+++ b/sdk/typescript/tests-ts/scan-comparison.test.ts
@@ -856,11 +856,11 @@ describe("semantic scan comparison", () => {
config,
codex,
model: "explicit-model",
- reasoningEffort: "max",
+ reasoningEffort: "future-effort",
});
expect(calls.threadOptions).toMatchObject({
model: "explicit-model",
- modelReasoningEffort: "max",
+ modelReasoningEffort: "future-effort",
});
});
diff --git a/sdk/typescript/tests-ts/suggest-owners.test.ts b/sdk/typescript/tests-ts/suggest-owners.test.ts
index 2a61f8299..700772a2f 100644
--- a/sdk/typescript/tests-ts/suggest-owners.test.ts
+++ b/sdk/typescript/tests-ts/suggest-owners.test.ts
@@ -269,12 +269,12 @@ test("combines source, affected-line authorship, and history through the restric
codex,
signal,
model: "synthetic-model",
- reasoningEffort: "high",
+ reasoningEffort: "future-effort",
});
expect(report).toMatchObject({
revision: repo.revision,
model: "synthetic-model",
- reasoningEffort: "high",
+ reasoningEffort: "future-effort",
results: [
{
findingId: finding.findingId,
@@ -298,7 +298,7 @@ test("combines source, affected-line authorship, and history through the restric
expect(calls[0]!.thread).toMatchObject({
threadSource: "security_suggest_owners",
model: "synthetic-model",
- modelReasoningEffort: "high",
+ modelReasoningEffort: "future-effort",
sandboxMode: "read-only",
approvalPolicy: "never",
networkAccessEnabled: false,