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(deep-scan): preserve caller tool settings across scan turns (#2012)

Michael D'Angelo49b498122049
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/permission-profile-preflight.ts b/plugins/codex-security/mcp-app/src/deep-scan/permission-profile-preflight.ts
index af19bb370..a221f17c8 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/permission-profile-preflight.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/permission-profile-preflight.ts
@@ -47,26 +47,80 @@ type PendingRequest = {
type RuntimeConfigReadOptions = Pick<
DeepScanPermissionProfilePreflightOptions,
- "codexPath" | "cwd" | "configOverrides" | "env" | "signal" | "context"
+ "codexPath" | "cwd" | "configOverrides" | "env" | "signal"
> & {
+ readonly context?: PreflightContext;
readonly commandArgs?: readonly string[];
+ readonly configCwd?: string;
/** Full app-server invocation for callers that already constructed its arguments. */
readonly appServerArgs?: readonly string[];
readonly providerConfigOverrides?: readonly string[];
};
+type PreflightContext = "helper" | "parent-config";
+
/** Read native effective settings, including managed provider requirements, without a turn. */
export async function readDeepScanRuntimeConfig(
- options: RuntimeConfigReadOptions,
-): Promise<JsonRecord> {
+ options: RuntimeConfigReadOptions & {
+ readonly plugin?: { marketplacePath: string; pluginName: string };
+ },
+ inspect?: (
+ config: JsonRecord,
+ hasEmptyCatalog: (server: string) => Promise<boolean>,
+ ) => Promise<JsonRecord>,
+): Promise<JsonRecord | undefined> {
return withPreflightClient(options, async (client) => {
const response = await client.request("config/read", {
- cwd: options.cwd,
+ cwd: options.configCwd ?? options.cwd,
includeLayers: false,
});
- const config = record(response.config);
+ let config = record(response.config);
if (!config) throw malformedPreflightError(options.context);
- return config;
+ // Portable plugins expose their admitted server names through native discovery.
+ // Preserve native routing if the selected Codex cannot provide that metadata.
+ if (options.plugin) {
+ const detail = await client
+ .request("plugin/read", options.plugin)
+ .catch(() => undefined);
+ options.signal.throwIfAborted();
+ const plugin = record(detail?.plugin);
+ const summary = record(plugin?.summary);
+ const servers = plugin?.mcpServers;
+ if (
+ summary?.installed !== true ||
+ summary.enabled !== true ||
+ !Array.isArray(servers) ||
+ !servers.every((name) => typeof name === "string")
+ )
+ return undefined;
+ config = {
+ ...config,
+ mcp_servers: {
+ ...Object.fromEntries(servers.map((name) => [name, {}])),
+ ...record(config.mcp_servers),
+ },
+ };
+ }
+ if (!inspect) return config;
+ return inspect(config, async (serverName) => {
+ const result = await client
+ .request("mcpServerStatus/list", {
+ serverName,
+ detail: "toolsAndAuthOnly",
+ })
+ .catch(() => undefined);
+ options.signal.throwIfAborted();
+ const match = Array.isArray(result?.data)
+ ? result.data.map(record).find((entry) => entry?.name === serverName)
+ : undefined;
+ const tools = record(match?.tools);
+ // Native status applies tool filters before it returns the catalog.
+ return (
+ match?.toolsError === null &&
+ tools !== undefined &&
+ Object.keys(tools).length === 0
+ );
+ });
});
}
@@ -266,7 +320,8 @@ async function withPreflightClient<T>(
options: RuntimeConfigReadOptions,
operation: (client: AppServerPreflightClient) => Promise<T>,
): Promise<T> {
- if (options.signal.aborted) throw abortError(options.signal.reason);
+ if (options.signal.aborted)
+ throw abortError(options.signal.reason, options.context);
const client = new AppServerPreflightClient(options);
try {
await client.initialize();
@@ -320,6 +375,7 @@ class AppServerPreflightClient {
args.push("--config", override);
}
args.push("app-server", "--stdio");
+ if (options.configCwd !== undefined) args.push("--cd", options.configCwd);
}
this.child = spawn(executablePathForSpawn(options.codexPath), args, {
@@ -361,7 +417,7 @@ class AppServerPreflightClient {
});
const onAbort = () => {
- this.fail(abortError(options.signal.reason));
+ this.fail(abortError(options.signal.reason, options.context));
this.stopChild();
};
options.signal.addEventListener("abort", onAbort, { once: true });
@@ -667,21 +723,28 @@ function profileCollisionError(context?: "helper"): DeepScanNonRetryableError {
);
}
-function malformedPreflightError(context?: "helper"): Error {
+function failedOperation(context?: PreflightContext): string {
+ return context === "parent-config"
+ ? "Could not read the Deep Scan parent configuration"
+ : `${subject(context)} cannot safely verify its read-only worker permission profile`;
+}
+
+function malformedPreflightError(context?: PreflightContext): Error {
return new Error(
- `${subject(context)} cannot safely verify its read-only worker permission profile with this Codex configuration. ${subject(context)} did not run.`,
+ context === "parent-config"
+ ? `${failedOperation(context)}. Codex returned an invalid app-server response.`
+ : `${failedOperation(context)} with this Codex configuration. ${subject(context)} did not run.`,
);
}
function unsupportedCodexApiError(
codexPath: string,
api: string,
- context?: "helper",
+ context?: PreflightContext,
): DeepScanNonRetryableError {
return new DeepScanNonRetryableError(
- subject(context) +
- " cannot safely verify its read-only worker permission profile because " +
- "the selected Codex executable " +
+ failedOperation(context) +
+ " because the selected Codex executable " +
JSON.stringify(codexPath) +
" does not support the required " +
JSON.stringify(api) +
@@ -698,7 +761,7 @@ function jsonRpcPreflightError(
codexPath: string,
method: string,
value: unknown,
- context?: "helper",
+ context?: PreflightContext,
): Error {
const error = record(value);
const code =
@@ -712,9 +775,8 @@ function jsonRpcPreflightError(
return failure;
}
return new Error(
- subject(context) +
- " cannot safely verify its read-only worker permission profile because " +
- "the selected Codex executable " +
+ failedOperation(context) +
+ " because the selected Codex executable " +
JSON.stringify(codexPath) +
" returned an error for " +
JSON.stringify(method) +
@@ -730,7 +792,7 @@ function jsonRpcPreflightError(
function codexExecutableStartError(
codexPath: string,
error: Error,
- context?: "helper",
+ context?: PreflightContext,
): Error {
const value = "code" in error ? error.code : undefined;
const code =
@@ -754,22 +816,24 @@ function codexExecutableExitError(
codexPath: string,
code: number | null,
signal: NodeJS.Signals | null,
- context?: "helper",
+ context?: PreflightContext,
): Error {
+ const operation =
+ context === "parent-config"
+ ? "the configuration read"
+ : "permission-profile verification";
const detail =
code !== null
- ? "exited before permission-profile verification completed with code " +
- code
+ ? `exited before ${operation} completed with code ${code}`
: signal !== null
- ? "was terminated before permission-profile verification completed by signal " +
- signal
- : "exited before permission-profile verification completed";
+ ? `was terminated before ${operation} completed by signal ${signal}`
+ : `exited before ${operation} completed`;
return new Error(codexExecutableFailureMessage(codexPath, detail, context));
}
function codexExecutableStdioError(
codexPath: string,
- context?: "helper",
+ context?: PreflightContext,
): Error {
return new Error(
codexExecutableFailureMessage(
@@ -783,8 +847,10 @@ function codexExecutableStdioError(
function codexExecutableFailureMessage(
codexPath: string,
detail: string,
- context?: "helper",
+ context?: PreflightContext,
): string {
+ if (context === "parent-config")
+ return `${failedOperation(context)}. Codex executable ${JSON.stringify(codexPath)} ${detail}.`;
return (
subject(context) +
" cannot safely verify its read-only worker permission profile because " +
@@ -822,7 +888,7 @@ export function deepScanPermissionProfileFallbackError(
);
}
-function subject(context?: "helper"): string {
+function subject(context?: PreflightContext): string {
return context === "helper" ? "Read-only Codex helper" : "Deep Scan";
}
@@ -830,10 +896,12 @@ function isAbortError(error: unknown): boolean {
return error instanceof Error && error.name === "AbortError";
}
-function abortError(reason: unknown): Error {
+function abortError(reason: unknown, context?: PreflightContext): Error {
if (reason instanceof Error) return reason;
return new DOMException(
- "Deep Scan worker permission profile preflight aborted.",
+ context === "parent-config"
+ ? "Deep Scan parent configuration read aborted."
+ : "Deep Scan worker permission profile preflight aborted.",
"AbortError",
);
}
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 1c086f3e1..d4716eb6c 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -30,6 +30,7 @@ import {
dirname,
isAbsolute,
join,
+ parse as parsePath,
posix,
relative,
resolve,
@@ -108,7 +109,12 @@ import {
import type { ScanTokenUsage } from "./cost-model.js";
import { ScanProgressTracker, type DeepScanProgress } from "./scan-progress.js";
import { findScanSession } from "./scan-logs.js";
-import { DIRECT_DEEP_SCAN_CONTROL_USAGE, runDeepScan } from "./deep-scan.js";
+import {
+ DIRECT_DEEP_SCAN_CONTROL_USAGE,
+ deepScanParentToolOverrides,
+ readDeepScanParentConfig,
+ runDeepScan,
+} from "./deep-scan.js";
import {
getDefaultSeverityRubric,
readSeverityRubricFile,
@@ -133,7 +139,7 @@ import {
type ScanSettings,
type ScanPromptSettings,
} from "./scan-settings.js";
-import { resolveScanPrompts } from "./prompt-files.js";
+import { readRegularInputFile, resolveScanPrompts } from "./prompt-files.js";
import {
readScanTimeBudgetPolicy,
renderScanTimeBudgetPolicy,
@@ -698,6 +704,7 @@ interface ClientDependencies {
runWorkbench?: typeof runWorkbench;
matchFindings?: typeof matchScanFindingsInternal;
runDeepScan?: typeof runDeepScan;
+ readDeepScanParentConfig?: typeof readDeepScanParentConfig;
canRunDirectDeepScan?: () => boolean;
}
@@ -3070,9 +3077,6 @@ export class CodexSecurity {
runtimePaths,
options.auth,
git,
- mode === "deep" && !directDeepScan
- ? deepScanParentConfig(session.sessionConfig)
- : undefined,
);
const threadOptions: ThreadOptions = {
threadSource: CODEX_SECURITY_THREAD_SOURCES.scan,
@@ -3080,40 +3084,113 @@ export class CodexSecurity {
skipGitRepoCheck: true,
approvalPolicy,
};
- let thread: CodexThreadLike;
- if (typeof resumeThreadId === "string") {
- if (codex.resumeThread === undefined) {
+ const turnOptions: TurnOptions = {
+ signal,
+ cyberAccessProgram: options.cyberAccessProgram,
+ };
+ const postScanPrompt = options.postScanPrompt;
+ const openThread = (client: CodexClientLike, id: unknown) => {
+ if (typeof id !== "string") return client.startThread(threadOptions);
+ if (!client.resumeThread)
throw new CodexSecurityError(
"The configured Codex client does not support resuming sessions.",
);
- }
- thread = codex.resumeThread(resumeThreadId, threadOptions);
+ return client.resumeThread(id, threadOptions);
+ };
+ if (typeof resumeThreadId === "string") {
tracker.start(resumeThreadId);
if (budgetRecovery !== null) budgetRecovery.threadId = resumeThreadId;
await tracker.refresh().catch(reportTrackingError);
- checkOpen();
- } else {
- thread = codex.startThread(threadOptions);
}
- const serializedPaths =
- normalized.kind === "paths" ? jsonForPrompt(normalized.paths) : null;
checkOpen();
- if (serializedPaths !== null && targetPathsFile !== null) {
- await writeFile(targetPathsFile, `${serializedPaths}\n`, {
- flag: "wx",
- mode: 0o400,
+ if (normalized.kind === "paths" && targetPathsFile !== null) {
+ await writeFile(
+ targetPathsFile,
+ `${jsonForPrompt(normalized.paths)}\n`,
+ {
+ flag: "wx",
+ mode: 0o400,
+ signal,
+ },
+ );
+ await chmod(targetPathsFile, 0o400);
+ checkOpen();
+ }
+ let parentCodex = codex;
+ const pluginServers =
+ mode === "deep" && !directDeepScan && !this.#dependencies.hostedScan
+ ? await readInstalledDeepScanPluginServers(
+ runtime.plugin.installedRoot,
+ )
+ : undefined;
+ if (pluginServers !== undefined) {
+ // The scan is already registered when native routing is inspected.
+ if (postScanPrompt?.trim()) {
+ runPostScan = () =>
+ openThread(codex, resumeThreadId).runStreamed(
+ postScanPrompt,
+ turnOptions,
+ );
+ }
+ const parentConfig = await (
+ this.#dependencies.readDeepScanParentConfig ??
+ readDeepScanParentConfig
+ )({
+ codexOptions,
+ preflightCommand:
+ await this.#providerPreflightCommand(effectiveConfig),
+ scanDir,
signal,
+ ...(pluginServers !== "native" && { pluginServers }),
+ ...(pluginServers === "native" && {
+ plugin: {
+ marketplacePath: join(
+ runtime.plugin.marketplaceRoot,
+ ".agents",
+ "plugins",
+ "marketplace.json",
+ ),
+ pluginName: runtime.plugin.name,
+ },
+ }),
});
- await chmod(targetPathsFile, 0o400);
+ const overrides =
+ parentConfig === undefined
+ ? []
+ : deepScanParentToolOverrides(
+ parentConfig,
+ pluginServers === "native" ? {} : pluginServers,
+ );
+ if (overrides.length > 0) {
+ // Only the coordinator turn needs to keep its MCP call outside a yielding cell.
+ parentCodex = await this.#dependencies.createCodex({
+ ...codexOptions,
+ configOverrides: [
+ ...(codexOptions.configOverrides ?? []),
+ ...overrides,
+ ],
+ });
+ }
+ runPostScan = null;
}
checkOpen();
- const turnOptions: TurnOptions = {
- signal,
- cyberAccessProgram: options.cyberAccessProgram,
- };
- const postScanPrompt = options.postScanPrompt;
+ const thread = openThread(parentCodex, resumeThreadId);
+ let scanThreadId = thread.id;
if (postScanPrompt?.trim()) {
- runPostScan = () => thread.runStreamed(postScanPrompt, turnOptions);
+ runPostScan = () => {
+ if (
+ (parentCodex !== codex || directDeepScan) &&
+ scanThreadId !== null
+ ) {
+ return openThread(codex, scanThreadId).runStreamed(
+ postScanPrompt,
+ turnOptions,
+ );
+ }
+ const followUp =
+ parentCodex === codex ? thread : codex.startThread(threadOptions);
+ return followUp.runStreamed(postScanPrompt, turnOptions);
+ };
}
if (mode === "standard" && options.maxTimeMinutes !== undefined) {
const timePolicy = await readScanTimeBudgetPolicy(
@@ -3168,17 +3245,7 @@ export class CodexSecurity {
"Codex did not resume the original scan session.",
);
}
- if (directDeepScan && postScanPrompt?.trim()) {
- runPostScan = () => {
- if (codex.resumeThread === undefined)
- throw new CodexSecurityError(
- "The configured Codex client does not support resuming sessions.",
- );
- return codex
- .resumeThread(threadId, threadOptions)
- .runStreamed(postScanPrompt, turnOptions);
- };
- }
+ scanThreadId = threadId;
if (resumeThreadId !== undefined) {
return;
}
@@ -6136,32 +6203,6 @@ export function classifyConnectionFailure(
return "unknown";
}
-function deepScanParentConfig(config: JsonObject): JsonObject {
- const resolved = resolveCodexProfile(config);
- const features = resolved["features"] ?? {};
- if (!isRecord(features)) return resolved;
- const mode = features["code_mode"];
- const settings = typeof mode === "boolean" ? { enabled: mode } : (mode ?? {});
- // Leave malformed user settings for the native config parser to reject.
- if (!isRecord(settings)) return resolved;
- const direct = settings["direct_only_tool_namespaces"] ?? [];
- if (!Array.isArray(direct)) return resolved;
- // The native parent waits for direct tool calls before it can end its turn.
- // A code-mode cell can yield the still-running coordinator to the model.
- return {
- ...resolved,
- features: {
- ...features,
- code_mode: {
- ...settings,
- direct_only_tool_namespaces: [
- ...new Set([...direct, "mcp__codex_security", "codex_security"]),
- ],
- },
- },
- };
-}
-
export function scanRuntimeCodexConfig(
config: JsonObject,
protectedCredentialHome?: string,
@@ -6578,23 +6619,68 @@ function selectedWorkerRuntimeConfig(
};
}
-async function pluginSupportsIsolatedDeepScanConfig(
+/** Read the declaration selected by the installed Codex plugin manifest. */
+async function readInstalledDeepScanPluginServers(
+ installedRoot: string,
+): Promise<Record<string, unknown> | "native" | undefined> {
+ const read = async (path: string): Promise<unknown> =>
+ JSON.parse(
+ await readRegularInputFile(join(installedRoot, path), installedRoot),
+ );
+ try {
+ const portable = await read("plugin.json").catch(() => undefined);
+ // A portable manifest owns MCP. Its legacy overlay only forwards environment variables.
+ if (
+ isRecord(portable) &&
+ typeof portable["$schema"] === "string" &&
+ portable["$schema"].startsWith("https://agent-plugins.org/schemas/")
+ )
+ return "native";
+ const manifest = await read(".codex-plugin/plugin.json");
+ if (!isRecord(manifest)) return;
+ let source = manifest["mcpServers"];
+ if (!isRecord(source)) {
+ const path =
+ typeof source === "string" && source.startsWith("./")
+ ? source.slice(2)
+ : "";
+ // Native Codex ignores invalid selectors and uses the installed default.
+ const valid =
+ path &&
+ !parsePath(path).root &&
+ !path.split(sep === "\\" ? /[/\\]/u : "/").includes("..");
+ source = await read(valid ? path : ".mcp.json");
+ }
+ if (!isRecord(source)) return;
+ return isRecord(source["mcpServers"]) ? source["mcpServers"] : source;
+ } catch {
+ return undefined;
+ }
+}
+
+async function readDeepScanPluginServers(
pluginRoot: string,
-): Promise<boolean> {
- let configuration: unknown;
+): Promise<Record<string, unknown> | undefined> {
try {
- configuration = JSON.parse(
+ const configuration: unknown = JSON.parse(
await readFile(join(pluginRoot, ".mcp.json"), "utf8"),
);
+ const servers = isRecord(configuration)
+ ? configuration["mcpServers"]
+ : undefined;
+ return isRecord(servers) ? servers : undefined;
} catch {
- return false;
+ return undefined;
}
- if (!isRecord(configuration)) return false;
- const servers = configuration["mcpServers"];
- if (!isRecord(servers)) return false;
- const server = servers["codex-security"];
- if (!isRecord(server)) return false;
- const environment = server["env_vars"];
+}
+
+async function pluginSupportsIsolatedDeepScanConfig(
+ pluginRoot: string,
+): Promise<boolean> {
+ const server = (await readDeepScanPluginServers(pluginRoot))?.[
+ "codex-security"
+ ];
+ const environment = isRecord(server) ? server["env_vars"] : undefined;
return (
Array.isArray(environment) &&
environment.includes(DEEP_SCAN_CONFIG_PATH_ENVIRONMENT)
diff --git a/sdk/typescript/src/config.ts b/sdk/typescript/src/config.ts
index 7d18370bc..7870c25d8 100644
--- a/sdk/typescript/src/config.ts
+++ b/sdk/typescript/src/config.ts
@@ -197,6 +197,8 @@ export function inlineToml(value: JsonValue): string {
throw new ConfigurationError(
"Codex TOML overrides cannot contain null values.",
);
+ // Match the Codex SDK's numeric spelling, including integers above 2**53 - 1.
+ if (typeof value === "number" && Number.isFinite(value)) return String(value);
if (Array.isArray(value)) return `[${value.map(inlineToml).join(",")}]`;
if (isObject(value)) {
return `{${Object.entries(value)
diff --git a/sdk/typescript/src/deep-scan.ts b/sdk/typescript/src/deep-scan.ts
index e81f1079a..840be4b86 100644
--- a/sdk/typescript/src/deep-scan.ts
+++ b/sdk/typescript/src/deep-scan.ts
@@ -1,12 +1,33 @@
import { spawn } from "node:child_process";
-import { join } from "node:path";
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
import { pathToFileURL } from "node:url";
import type { CodexOptions } from "@openai/codex-sdk";
-import { bundledCodexSdkEnvironment } from "./codex-sdk-environment.js";
+import { parse } from "smol-toml";
+import {
+ bundledCodexSdkEnvironment,
+ resolveBundledCodexExecutable,
+} from "./codex-sdk-environment.js";
import { CodexSecurityError } from "./errors.js";
-import { executablePathForSpawn, type CodexCommand } from "./runtime.js";
+import {
+ deepMerge,
+ inlineToml,
+ type JsonObject,
+ type JsonValue,
+} from "./config.js";
+import { isRecord } from "./record.js";
+import {
+ executablePathForSpawn,
+ PLUGIN_NAME,
+ runCodexCommand,
+ type CodexCommand,
+} from "./runtime.js";
import { resolveTrustedExecutable } from "./trusted-executable.js";
-import { withCodexPreflightLock } from "./provider-profile.js";
+import {
+ nativePermissionPreflight,
+ nativeProfileClient,
+ withCodexPreflightLock,
+} from "./provider-profile.js";
export interface DirectDeepScanOptions {
codexOptions: CodexOptions & { nativeProfile?: string };
@@ -19,6 +40,305 @@ export interface DirectDeepScanOptions {
signal: AbortSignal;
}
+// The stock SDK emits one flag per leaf, including literal dotted keys in order.
+function sdkConfigFlags(config: JsonObject, prefix = ""): string[] {
+ return Object.entries(config).flatMap(([key, value]) => {
+ const path = prefix ? `${prefix}.${key}` : key;
+ return isRecord(value) && Object.keys(value).length
+ ? sdkConfigFlags(value, path)
+ : [`${path}=${inlineToml(value)}`];
+ });
+}
+
+// An older custom launcher must start in the caller's directory. Only use
+// supplied routing when its app-server cannot read the scan at startup.
+function suppliedParentRouting(
+ overrides: readonly string[],
+): JsonObject | undefined {
+ try {
+ const config: JsonObject = Object.create(null);
+ for (const override of overrides) {
+ const equals = override.indexOf("=");
+ const key = override.slice(0, equals).trim();
+ if (!/^(?:features|mcp_servers)(?:\.|$)/u.test(key)) continue;
+ const path = key.split(".");
+ const leaf = path.pop()!;
+ let table = config;
+ for (const part of path) {
+ const next = Object.hasOwn(table, part) ? table[part] : undefined;
+ const child =
+ table === config["features"] && part === "code_mode"
+ ? codeModeTable(next)
+ : next;
+ table = table[part] = Object.assign(
+ Object.create(null),
+ isRecord(child) ? child : {},
+ );
+ }
+ const value = parse(`value=${override.slice(equals + 1)}`)[
+ "value"
+ ] as JsonValue;
+ const priorMode =
+ key === "features.code_mode" ? codeModeTable(table[leaf]) : undefined;
+ const newMode = priorMode && codeModeTable(value);
+ table[leaf] =
+ priorMode && newMode ? deepMerge({ ...priorMode }, newMode) : value;
+ }
+ const servers = config["mcp_servers"];
+ const owner = isRecord(servers) ? servers[PLUGIN_NAME] : undefined;
+ // Even a supplied transport can inherit a machine-level direct opt-out.
+ if (isRecord(owner) && !Array.isArray(owner["omit_tools_from"])) return;
+ return config;
+ } catch {
+ // Leave malformed settings for exec's own parser.
+ return undefined;
+ }
+}
+
+// Codex merges a structured Code Mode setting with its boolean shorthand.
+function codeModeTable(value: JsonValue | undefined): JsonObject | undefined {
+ if (typeof value === "boolean") return { enabled: value };
+ return isRecord(value) ? value : undefined;
+}
+
+/** Read the same native layers and CLI overrides as the parent before adding its tool. */
+export async function readDeepScanParentConfig(
+ options: Pick<
+ DirectDeepScanOptions,
+ "codexOptions" | "preflightCommand" | "scanDir" | "signal"
+ > & {
+ plugin?: { marketplacePath: string; pluginName: string };
+ pluginServers?: Record<string, unknown>;
+ },
+): Promise<JsonObject | undefined> {
+ const { codexOptions, preflightCommand: command } = options;
+ const config = codexOptions.config ?? {};
+ // The provider-profile launcher emits whole top-level tables instead.
+ const overrides =
+ codexOptions.nativeProfile === undefined
+ ? sdkConfigFlags(config)
+ : (await nativeProfileClient()).profileConfigOverrides(config);
+ const environment = bundledCodexSdkEnvironment(command.command, {
+ ...codexOptions.env,
+ ...(codexOptions.apiKey === undefined
+ ? {}
+ : { CODEX_API_KEY: codexOptions.apiKey }),
+ });
+ const configOverrides = [
+ ...overrides,
+ ...(codexOptions.configOverrides ?? []),
+ ];
+ // Subcommand help does not load a project. A global --cd is ignored by
+ // older app-servers, so require support on the subcommand itself.
+ const help = await runCodexCommand(
+ command,
+ ["app-server", "--cd", options.scanDir, "--help"],
+ environment,
+ undefined,
+ options.signal,
+ );
+ const supportsCd =
+ help.success && /^\s*(?:-C,\s*)?--cd\s+<[^>\n]+>/mu.test(help.stdout);
+ if (!supportsCd) {
+ // The bundled command is the native executable itself. A custom launcher
+ // can use its own working directory to resolve scripts and other inputs.
+ if (
+ resolve(options.scanDir) !== process.cwd() &&
+ !isBundledExecutable(command.command)
+ )
+ return options.plugin
+ ? undefined
+ : suppliedParentRouting(configOverrides);
+ if (environment["CODEX_HOME"])
+ environment["CODEX_HOME"] = resolve(environment["CODEX_HOME"]);
+ }
+
+ const native = await nativePermissionPreflight();
+ return withCodexPreflightLock(environment, options.signal, () =>
+ native.readDeepScanRuntimeConfig(
+ {
+ codexPath: command.command,
+ commandArgs: command.args,
+ cwd: supportsCd ? process.cwd() : options.scanDir,
+ ...(supportsCd && { configCwd: options.scanDir }),
+ configOverrides,
+ env: environment,
+ signal: options.signal,
+ context: "parent-config",
+ plugin: options.plugin,
+ },
+ (
+ config: JsonObject,
+ hasEmptyCatalog: (server: string) => Promise<boolean>,
+ ) => inspectFilteredPeers(config, options.pluginServers, hasEmptyCatalog),
+ ),
+ );
+}
+
+function isBundledExecutable(command: string): boolean {
+ try {
+ return (
+ realpathSync.native(command) ===
+ realpathSync.native(resolveBundledCodexExecutable())
+ );
+ } catch {
+ return false; // An installation may supply only an external launcher.
+ }
+}
+
+async function inspectFilteredPeers(
+ config: JsonObject,
+ pluginServers: Record<string, unknown> | undefined,
+ hasEmptyCatalog: (server: string) => Promise<boolean>,
+): Promise<JsonObject> {
+ const configured = isRecord(config["mcp_servers"])
+ ? config["mcp_servers"]
+ : {};
+ const owner = configured[PLUGIN_NAME];
+ if (
+ isRecord(owner) &&
+ (owner["command"] ||
+ owner["url"] ||
+ Array.isArray(owner["omit_tools_from"]))
+ )
+ return config;
+ const servers = { ...pluginServers, ...configured };
+ const registration = servers[PLUGIN_NAME];
+ if (!isRecord(registration) || registration["enabled"] === false)
+ return config;
+ const routing = { ...configured };
+ for (const [name, settings] of Object.entries(servers)) {
+ if (
+ name === PLUGIN_NAME ||
+ !isRecord(settings) ||
+ settings["enabled"] === false ||
+ !["codex_security", "mcp__codex_security"].includes(
+ normalizedServerName(name),
+ )
+ )
+ continue;
+ if (
+ ![settings["enabled_tools"], settings["disabled_tools"]].some(
+ (tools) => Array.isArray(tools) && tools.length > 0,
+ )
+ )
+ continue;
+ if (await hasEmptyCatalog(name)) {
+ // This view is used only to select a namespace. Never change the peer's config.
+ routing[name] = { enabled_tools: [] };
+ }
+ }
+ return { ...config, mcp_servers: routing };
+}
+
+function normalizedServerName(server: string): string {
+ return server.replace(/[-.:@/]/gu, "_");
+}
+
+/** Keep direct dispatch scoped to the original SDK coordinator turn and MCP server. */
+export function deepScanParentToolOverrides(
+ config: JsonObject,
+ pluginServers: Record<string, unknown>,
+): string[] {
+ const features = config["features"] ?? {};
+ if (!isRecord(features)) return [];
+ const mode = features["code_mode"];
+ if (mode !== undefined && typeof mode !== "boolean" && !isRecord(mode))
+ return [];
+ const direct =
+ (isRecord(mode) ? mode["direct_only_tool_namespaces"] : undefined) ?? [];
+ if (!Array.isArray(direct)) return [];
+
+ const owner = PLUGIN_NAME;
+ const bare = "codex_security";
+ const prefixed = "mcp__codex_security";
+ let required = [prefixed, bare];
+ const overrides: string[] = [];
+ const configured = config["mcp_servers"];
+ // Native registrations take precedence over the selected plugin's entries.
+ const servers: Record<string, unknown> = {
+ ...pluginServers,
+ ...(isRecord(configured) ? configured : {}),
+ };
+ const ownerConfig = servers[owner];
+ if (!isRecord(ownerConfig) || ownerConfig["enabled"] === false) return [];
+ const omitted = ownerConfig["omit_tools_from"];
+ if (Array.isArray(omitted) && omitted.includes("direct")) return [];
+ // A raw transport or an existing omission leaf can be updated in place.
+ // Adding a new registration would shadow a plugin's transport and policy.
+ if (
+ isRecord(configured) &&
+ Object.hasOwn(configured, owner) &&
+ (Array.isArray(omitted) ||
+ typeof ownerConfig["command"] === "string" ||
+ typeof ownerConfig["url"] === "string")
+ ) {
+ if (omitted != null && !Array.isArray(omitted)) return [];
+ const surfaces = omitted ?? [];
+ if (surfaces.includes("code_mode") && surfaces.includes("deferred"))
+ return [];
+ return [
+ `mcp_servers.${owner}.omit_tools_from=${inlineToml([...new Set([...surfaces, "code_mode", "deferred"])])}`,
+ ];
+ }
+ const option = features["non_prefixed_mcp_tool_names"];
+ const enabled =
+ option === true || (isRecord(option) && option["enabled"] === true);
+ const selected = isRecord(option) ? option["server_names"] : undefined;
+ function namespace(server: string): string {
+ const name = normalizedServerName(server);
+ const omitPrefix =
+ enabled && (!Array.isArray(selected) || selected.includes(server));
+ return omitPrefix || name.startsWith("mcp__") ? name : `mcp__${name}`;
+ }
+ const occupied = new Set(
+ Object.entries(servers)
+ .filter(
+ ([server, settings]) =>
+ server !== owner &&
+ isRecord(settings) &&
+ settings["enabled"] !== false &&
+ (!Array.isArray(settings["enabled_tools"]) ||
+ settings["enabled_tools"].length > 0),
+ )
+ .map(([server]) => namespace(server)),
+ );
+ const current = namespace(owner);
+ if (occupied.has(current)) {
+ const excluded = isRecord(mode) ? mode["excluded_tool_namespaces"] : null;
+ const routed = Array.isArray(excluded) ? [...direct, ...excluded] : direct;
+ // Moving the owner also renames its peers. Keep names that the caller
+ // explicitly routed or excluded from Code Mode.
+ if (
+ current === bare ||
+ occupied.has(bare) ||
+ routed.some(
+ (name) =>
+ name === current ||
+ (typeof name === "string" &&
+ /^mcp__codex_security_[0-9a-f]{12}$/u.test(name)),
+ ) ||
+ (option != null && !enabled)
+ )
+ return [];
+ overrides.push(
+ `features.non_prefixed_mcp_tool_names=${inlineToml({
+ enabled: true,
+ server_names: [...(Array.isArray(selected) ? selected : []), owner],
+ })}`,
+ );
+ required = [bare];
+ } else if (occupied.has(prefixed) || occupied.has(bare)) {
+ required = [current];
+ }
+ if (!required.every((name) => direct.includes(name))) {
+ overrides.push(
+ `features.code_mode.direct_only_tool_namespaces=${inlineToml([...new Set([...direct, ...required])])}`,
+ );
+ }
+ return overrides;
+}
+
// The direct coordinator records context but never calls a model itself.
export const DIRECT_DEEP_SCAN_CONTROL_USAGE = {
input_tokens: 0,
diff --git a/sdk/typescript/src/provider-profile.ts b/sdk/typescript/src/provider-profile.ts
index 41ace6c25..bd357db67 100644
--- a/sdk/typescript/src/provider-profile.ts
+++ b/sdk/typescript/src/provider-profile.ts
@@ -272,7 +272,7 @@ export async function withCodexPreflightLock<T>(
}
}
-async function nativePermissionPreflight() {
+export async function nativePermissionPreflight() {
return await import(
pathToFileURL(
join(
@@ -284,7 +284,7 @@ async function nativePermissionPreflight() {
);
}
-async function nativeProfileClient() {
+export async function nativeProfileClient() {
return await import(
pathToFileURL(
join(await bundledPluginRoot(), "scripts", "codex_profile.mjs"),
diff --git a/sdk/typescript/tests-ts/api-deep-scan-runtime-routing.test.ts b/sdk/typescript/tests-ts/api-deep-scan-runtime-routing.test.ts
index fb95d691b..47844ac70 100644
--- a/sdk/typescript/tests-ts/api-deep-scan-runtime-routing.test.ts
+++ b/sdk/typescript/tests-ts/api-deep-scan-runtime-routing.test.ts
@@ -1,8 +1,16 @@
-import { mkdir } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, readFile, symlink, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
import { afterEach, expect, mock, test } from "bun:test";
import type { CodexOptions } from "@openai/codex-sdk";
-import type { DirectDeepScanOptions } from "../src/deep-scan.js";
+import { parse } from "smol-toml";
+import type { JsonObject, JsonValue } from "../src/config.js";
+import {
+ deepScanParentToolOverrides,
+ readDeepScanParentConfig,
+ type DirectDeepScanOptions,
+} from "../src/deep-scan.js";
+import { resolveCodexCommand } from "../src/runtime.js";
+import { PLUGIN_ROOT } from "./plugin-root.js";
import { TestClient } from "./support/api-client.js";
import {
preparedRuntime,
@@ -13,6 +21,165 @@ import { createApiTestFixtures } from "./support/temporary-directories.js";
const { temporaryDirectory, cleanup } = createApiTestFixtures();
afterEach(cleanup);
+test("a colliding MCP server leaves only the original coordinator's namespace direct", () => {
+ const owner = "codex-security";
+ const alias = "codex.security";
+ const bare = "codex_security";
+ const prefixed = "mcp__codex_security";
+ const servers = { [owner]: { enabled: true }, [alias]: { enabled: true } };
+ const selected = (...names: string[]) => ({
+ enabled: true,
+ server_names: names,
+ });
+ const direct = (...names: string[]) => ({
+ direct_only_tool_namespaces: names,
+ });
+ const overrides = (
+ prefix?: JsonValue,
+ existing: string[] = ["audit"],
+ registrations: JsonObject = servers,
+ ) => {
+ const config = {
+ mcp_servers: registrations,
+ features: {
+ ...(prefix === undefined
+ ? {}
+ : { non_prefixed_mcp_tool_names: prefix }),
+ code_mode: direct(...existing),
+ },
+ };
+ return parse(deepScanParentToolOverrides(config, {}).join("\n"))[
+ "features"
+ ];
+ };
+
+ expect(overrides()).toEqual({
+ non_prefixed_mcp_tool_names: selected(owner),
+ code_mode: direct("audit", bare),
+ });
+ expect(overrides(selected("retained-tools"))).toEqual({
+ non_prefixed_mcp_tool_names: selected("retained-tools", owner),
+ code_mode: direct("audit", bare),
+ });
+ expect(overrides(selected(alias))).toEqual({
+ code_mode: direct("audit", prefixed),
+ });
+ expect(overrides(selected(owner))).toEqual({
+ code_mode: direct("audit", bare),
+ });
+ expect(
+ overrides(undefined, ["audit"], {
+ ...servers,
+ [alias]: { enabled: false },
+ }),
+ ).toEqual({
+ code_mode: direct("audit", prefixed, bare),
+ });
+
+ expect(
+ overrides(false, ["audit"], { ...servers, [alias]: { enabled_tools: [] } }),
+ ).toEqual({ code_mode: direct("audit", prefixed, bare) });
+ expect(
+ overrides(false, ["audit"], {
+ ...servers,
+ [alias]: { enabled_tools: ["peer_ping"] },
+ }),
+ ).toBeUndefined();
+ expect(overrides(false)).toBeUndefined();
+ expect(overrides(true)).toBeUndefined();
+ expect(overrides(undefined, [prefixed])).toBeUndefined();
+ const guardedPeer = `${prefixed}_9721dc6aa9d2`;
+ expect(overrides(undefined, [guardedPeer])).toBeUndefined();
+ expect(
+ deepScanParentToolOverrides(
+ { features: { code_mode: { excluded_tool_namespaces: [guardedPeer] } } },
+ servers,
+ ),
+ ).toEqual([]);
+ expect(
+ overrides(undefined, [], { ...servers, [owner]: { enabled: false } }),
+ ).toBeUndefined();
+ expect(
+ overrides(selected(bare), [], { ...servers, [bare]: { enabled: true } }),
+ ).toBeUndefined();
+});
+
+test("a configured owner stays direct across native tool filtering without changing a sibling's routing", () => {
+ const owner = "codex-security";
+ const peer = "codex_security";
+ const guarded = "mcp__codex_security_9721dc6aa9d2";
+ const overrides = (transport: JsonObject, selected: string[]) =>
+ parse(
+ deepScanParentToolOverrides(
+ {
+ mcp_servers: {
+ [owner]: transport,
+ [peer]: { command: "peer", enabled_tools: selected },
+ },
+ features: {
+ non_prefixed_mcp_tool_names: false,
+ code_mode: { direct_only_tool_namespaces: [guarded] },
+ },
+ },
+ {},
+ ).join("\n"),
+ );
+ const transports: JsonObject[] = [
+ { command: "coordinator", omit_tools_from: ["code_mode"] },
+ { url: "https://coordinator.example/mcp" },
+ ];
+ for (const transport of transports) {
+ for (const selected of [["peer_ping"], ["absent"]]) {
+ expect(overrides(transport, selected)).toEqual({
+ mcp_servers: {
+ [owner]: { omit_tools_from: ["code_mode", "deferred"] },
+ },
+ });
+ }
+ }
+ expect(
+ overrides({ command: "coordinator", omit_tools_from: ["direct"] }, [
+ "absent",
+ ]),
+ ).toEqual({});
+});
+
+test("native MCP registrations take precedence over the selected plugin's names and opt-outs", () => {
+ const owner = "codex-security";
+ const alias = "codex.security";
+ const plugin = { [owner]: {}, [alias]: {} };
+ const noDirect = { omit_tools_from: ["direct"] };
+ const overrides = (servers: JsonObject, selected: JsonObject) =>
+ parse(
+ deepScanParentToolOverrides({ mcp_servers: servers }, selected).join(
+ "\n",
+ ),
+ )["features"];
+ const isolated = {
+ non_prefixed_mcp_tool_names: { enabled: true, server_names: [owner] },
+ code_mode: { direct_only_tool_namespaces: ["codex_security"] },
+ };
+
+ expect(overrides({}, plugin)).toEqual(isolated);
+ expect(overrides({ [alias]: { enabled: false } }, plugin)).toEqual({
+ code_mode: {
+ direct_only_tool_namespaces: ["mcp__codex_security", "codex_security"],
+ },
+ });
+ expect(overrides({}, { [alias]: {} })).toBeUndefined();
+ expect(overrides({}, { ...plugin, [owner]: noDirect })).toBeUndefined();
+ expect(overrides({ [owner]: noDirect }, plugin)).toBeUndefined();
+ expect(overrides({ [owner]: {} }, { ...plugin, [owner]: noDirect })).toEqual(
+ isolated,
+ );
+});
+
+const parentWithNode = {
+ dependencyNode: null,
+ runtimeNode: "selected runtime",
+ route: "parent",
+} as const;
+
test.each([
{
name: "inherited Node override",
@@ -44,6 +211,69 @@ test.each([
runtimeNode: null,
route: "direct",
},
+ {
+ name: "installed plugin excludes the direct surface",
+ dependencyNode: null,
+ runtimeNode: "selected runtime",
+ route: "parent",
+ pluginOmit: ["direct"],
+ directOmitted: true,
+ },
+ {
+ name: "configured server permits direct use despite the installed plugin exclusion",
+ dependencyNode: null,
+ runtimeNode: "selected runtime",
+ route: "parent",
+ pluginOmit: ["direct"],
+ configuredOmit: [],
+ },
+ {
+ name: "configured server excludes the direct surface",
+ dependencyNode: null,
+ runtimeNode: "selected runtime",
+ route: "parent",
+ configuredOmit: ["direct"],
+ directOmitted: true,
+ },
+ {
+ ...parentWithNode,
+ name: "inline MCP declaration allowing direct calls",
+ declaration: "inline",
+ pluginOmit: [],
+ },
+ {
+ ...parentWithNode,
+ name: "inline MCP declaration excluding direct calls",
+ declaration: "inline",
+ pluginOmit: ["direct"],
+ directOmitted: true,
+ },
+ {
+ ...parentWithNode,
+ name: "alternate MCP declaration allowing direct calls",
+ declaration: "alternate",
+ pluginOmit: [],
+ },
+ {
+ ...parentWithNode,
+ name: "alternate MCP declaration excluding direct calls",
+ declaration: "alternate",
+ pluginOmit: ["direct"],
+ directOmitted: true,
+ },
+ {
+ ...parentWithNode,
+ name: "the installed default when an alternate MCP selector contains a parent component",
+ declaration: "invalid",
+ pluginOmit: ["direct"],
+ },
+ {
+ ...parentWithNode,
+ name: "an alternate MCP file reached through a link outside the installed plugin",
+ declaration: "outside",
+ pluginOmit: [],
+ directOmitted: true,
+ },
{
name: "invalid code mode supplied by the caller",
dependencyNode: null,
@@ -59,6 +289,57 @@ test.each([
await mkdir(repository);
await mkdir(codexHome);
await mkdir(scanDir, { mode: 0o700 });
+ const runtime = preparedRuntime(codexHome);
+ if (scenario.pluginOmit) {
+ const installed = join(root, "installed-plugin");
+ await mkdir(join(installed, ".codex-plugin"), { recursive: true });
+ const manifest = JSON.parse(
+ await readFile(join(PLUGIN_ROOT, ".codex-plugin", "plugin.json"), "utf8"),
+ );
+ const servers = (omit: readonly string[]) => ({
+ "codex-security": { command: "fixture", omit_tools_from: omit },
+ });
+ const declared = servers(scenario.pluginOmit);
+ let defaults = declared;
+ if ("declaration" in scenario) {
+ // Only the installed manifest selects this declaration.
+ defaults = servers(scenario.directOmitted ? [] : ["direct"]);
+ if (scenario.declaration === "inline") {
+ manifest.mcpServers = declared;
+ } else {
+ manifest.mcpServers = "./routing/servers.json";
+ const routing = join(installed, "routing");
+ const linked = scenario.declaration === "outside";
+ const directory = linked ? join(root, "outside-plugin") : routing;
+ await mkdir(directory);
+ if (scenario.declaration === "invalid") {
+ await mkdir(join(directory, "nested"));
+ manifest.mcpServers = "./routing/nested/../servers.json";
+ defaults = servers([]);
+ }
+ if (linked) {
+ await symlink(
+ directory,
+ routing,
+ process.platform === "win32" ? "junction" : "dir",
+ );
+ }
+ await writeFile(
+ join(directory, "servers.json"),
+ JSON.stringify({ mcpServers: declared }),
+ );
+ }
+ }
+ await writeFile(
+ join(installed, ".mcp.json"),
+ JSON.stringify({ mcpServers: defaults }),
+ );
+ await writeFile(
+ join(installed, ".codex-plugin", "plugin.json"),
+ JSON.stringify(manifest),
+ );
+ runtime.plugin.installedRoot = installed;
+ }
const selectedNode =
scenario.runtimeNode === null
? undefined
@@ -78,6 +359,7 @@ test.each([
);
throw new Error("direct route reached");
});
+ const started: CodexOptions[] = [];
const createCodex = mock((options: CodexOptions) => {
expect(options.apiKey).toBe("synthetic-routing-key");
expect(options.env?.["CODEX_MCP_NODE_PATH"]).toBe(selectedNode);
@@ -87,25 +369,29 @@ test.each([
model_reasoning_effort: "high",
features: {
shell_tool: false,
- code_mode:
- typeof codeMode === "string" || scenario.route === "direct"
- ? codeMode
- : {
- direct_only_tool_namespaces: [
- "existing_tools",
- "mcp__codex_security",
- "codex_security",
- ],
- },
+ code_mode: codeMode,
},
});
return {
- startThread: () => ({ id: null, runStreamed: parentTurn }),
+ startThread: () => {
+ started.push(options);
+ return { id: null, runStreamed: parentTurn };
+ },
};
});
const client = new TestClient(
{
codexOverrides: {
+ ...(scenario.configuredOmit === undefined
+ ? {}
+ : {
+ mcp_servers: {
+ "codex-security": {
+ command: "test-server",
+ omit_tools_from: [...scenario.configuredOmit],
+ },
+ },
+ }),
model: "gpt-6.1-sol",
model_reasoning_effort: "high",
features: {
@@ -126,7 +412,7 @@ test.each([
}),
},
prepareRuntime: async () => ({
- ...preparedRuntime(codexHome),
+ ...runtime,
environment: runtimeEnvironment,
}),
// Keep the host's Bun fallback and account advisory out of this check.
@@ -139,7 +425,25 @@ test.each([
await expect(client.run(repository, { mode: "deep" })).rejects.toThrow(
`${scenario.route} route reached`,
);
- expect(createCodex).toHaveBeenCalledTimes(1);
+ expect(started).toHaveLength(1);
+ const rawRule =
+ 'mcp_servers.codex-security.omit_tools_from=["code_mode","deferred"]';
+ const overrides = started[0]!.configOverrides?.filter(
+ (value) =>
+ value === rawRule ||
+ value.startsWith("features.code_mode.direct_only_tool_namespaces="),
+ );
+ expect(overrides).toEqual(
+ scenario.route === "parent" &&
+ typeof codeMode !== "string" &&
+ !scenario.directOmitted
+ ? [
+ scenario.configuredOmit !== undefined
+ ? rawRule
+ : 'features.code_mode.direct_only_tool_namespaces=["existing_tools","mcp__codex_security","codex_security"]',
+ ]
+ : [],
+ );
expect(parentTurn).toHaveBeenCalledTimes(
scenario.route === "parent" ? 1 : 0,
);
@@ -151,3 +455,262 @@ test.each([
await client.close();
}
});
+
+test("stock Codex resolves ordered profile overrides and inherited transport policy in the scan", async () => {
+ const home = await temporaryDirectory();
+ const scanDir = await temporaryDirectory();
+ await writeFile(
+ join(scanDir, "instructions.md"),
+ "Synthetic scan instructions.",
+ );
+ const owner = "codex-security";
+ const read = () =>
+ readDeepScanParentConfig({
+ codexOptions: {
+ nativeProfile: "fixture",
+ env: { CODEX_HOME: relative(process.cwd(), home) },
+ config: {
+ "features.code_mode.enabled": true,
+ features: {
+ code_mode: {
+ enabled: true,
+ direct_only_tool_namespaces: ["audit"],
+ },
+ },
+ model_instructions_file: "instructions.md",
+ mcp_servers: { [owner]: { command: "fixture" } },
+ },
+ },
+ preflightCommand: resolveCodexCommand({}),
+ scanDir,
+ signal: new AbortController().signal,
+ });
+ const overrides = async () => {
+ const config = await read();
+ expect(config?.["features"]).toMatchObject({
+ code_mode: { enabled: true, direct_only_tool_namespaces: ["audit"] },
+ });
+ return deepScanParentToolOverrides(config!, {});
+ };
+ expect(await overrides()).toEqual([
+ 'mcp_servers.codex-security.omit_tools_from=["code_mode","deferred"]',
+ ]);
+ await writeFile(
+ join(home, "config.toml"),
+ '[mcp_servers.codex-security]\ncommand="fixture"\nomit_tools_from=["direct"]\n',
+ );
+ expect(await overrides()).toEqual([]);
+});
+
+test("stock Codex counts only admitted tools from a colliding MCP server", async () => {
+ const home = await temporaryDirectory();
+ const scanDir = await temporaryDirectory();
+ const script = join(home, "peer.mjs");
+ await writeFile(
+ script,
+ `import { createInterface } from "node:readline";
+for await (const line of createInterface({ input: process.stdin })) {
+ const { id, method, params } = JSON.parse(line);
+ if (id === undefined) continue;
+ const result = method === "initialize" ? {
+ protocolVersion: params.protocolVersion, capabilities: { tools: {} }, serverInfo: { name: "fixture", version: "1" },
+ } : method === "tools/list" ? { tools: [{ name: "peer_ping", inputSchema: { type: "object" } }] } : {};
+ console.log(JSON.stringify({ jsonrpc: "2.0", id, result }));
+}`,
+ );
+ const pluginServers = { "codex-security": {} };
+ const routes = async (allowed: string) => {
+ const config = await readDeepScanParentConfig({
+ codexOptions: {
+ env: { CODEX_HOME: home },
+ config: {
+ features: {
+ code_mode: {
+ enabled: true,
+ direct_only_tool_namespaces: ["audit"],
+ },
+ non_prefixed_mcp_tool_names: false,
+ },
+ mcp_servers: {
+ codex_security: {
+ command: process.execPath,
+ args: [script],
+ enabled_tools: [allowed],
+ },
+ },
+ },
+ },
+ preflightCommand: resolveCodexCommand({}),
+ pluginServers,
+ scanDir,
+ signal: new AbortController().signal,
+ });
+ return deepScanParentToolOverrides(config!, pluginServers);
+ };
+ expect(await routes("absent")).toEqual([
+ 'features.code_mode.direct_only_tool_namespaces=["audit","mcp__codex_security","codex_security"]',
+ ]);
+ expect(await routes("peer_ping")).toEqual([]);
+});
+
+test("an older custom launcher retains supplied routing without starting in the caller project", async () => {
+ const home = await temporaryDirectory();
+ const scanDir = await temporaryDirectory();
+ await writeFile(
+ join(home, "config.toml"),
+ '[features.code_mode]\ndirect_only_tool_namespaces = ["inherited_tools"]\n',
+ );
+ const read = (
+ config: CodexOptions["config"],
+ configOverrides: string[] = [],
+ ) =>
+ readDeepScanParentConfig({
+ codexOptions: { config, configOverrides, env: { CODEX_HOME: home } },
+ preflightCommand: {
+ command: process.execPath,
+ args: [
+ "-e",
+ "process.exit(process.argv.includes('--help') ? 0 : 1)",
+ "--",
+ ],
+ },
+ scanDir,
+ signal: new AbortController().signal,
+ });
+ const expected = (name: string) => ({
+ features: { code_mode: { direct_only_tool_namespaces: [name] } },
+ });
+ expect(
+ await read({ model_instructions_file: "missing-in-caller.md" }),
+ ).toEqual({});
+ expect(
+ await read({
+ features: { "code_mode.direct_only_tool_namespaces": ["first"] },
+ "features.code_mode.direct_only_tool_namespaces": ["last"],
+ model_auto_compact_token_limit: 2 ** 53,
+ }),
+ ).toEqual(expected("last"));
+ expect(await read({ "features.code_mode": "invalid" })).toEqual({
+ features: { code_mode: "invalid" },
+ });
+ expect(
+ await read({}, [
+ "features.code_mode=false",
+ 'features.code_mode.direct_only_tool_namespaces=["audit"]',
+ "features.code_mode=true",
+ ]),
+ ).toEqual({
+ features: {
+ code_mode: { enabled: true, direct_only_tool_namespaces: ["audit"] },
+ },
+ });
+ expect(
+ await read({}, [
+ "features.code_mode.enabled=false",
+ 'features={code_mode={enabled=true,direct_only_tool_namespaces=["audit"]}}',
+ ]),
+ ).toEqual({
+ features: {
+ code_mode: { enabled: true, direct_only_tool_namespaces: ["audit"] },
+ },
+ });
+ const owner = { command: "fixture" };
+ const explicit = { mcp_servers: { "codex-security": owner } };
+ expect(await read(explicit)).toBeUndefined();
+ expect(
+ await read(explicit, [
+ 'mcp_servers.codex-security.omit_tools_from=["direct"]',
+ "mcp_servers.codex-security.omit_tools_from=[]",
+ ]),
+ ).toEqual({
+ mcp_servers: { "codex-security": { ...owner, omit_tools_from: [] } },
+ });
+ const leaf = await read({}, [
+ "mcp_servers.codex-security.omit_tools_from=[]",
+ ]);
+ expect(deepScanParentToolOverrides(leaf!, {})).toEqual([
+ 'mcp_servers.codex-security.omit_tools_from=["code_mode","deferred"]',
+ ]);
+});
+
+test("a capable app-server launches from the caller and reads the scan settings and selected plugin", async () => {
+ const home = await temporaryDirectory();
+ const scanDir = await temporaryDirectory();
+ const script = join(home, "config-reader.mjs");
+ const log = join(home, "requests.json");
+ await writeFile(
+ script,
+ `import { writeFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+if (process.argv.includes("--help")) { console.log(" -C, --cd <DIR>"); process.exit(0); }
+const startupCwd = process.argv[process.argv.indexOf("--cd") + 1];
+const [log, replies] = process.argv.slice(2);
+const responses = JSON.parse(replies);
+const calls = [];
+for await (const line of createInterface({ input: process.stdin })) {
+ const { id, method, params } = JSON.parse(line);
+ if (id === undefined) continue;
+ if (method !== "initialize") {
+ calls.push({ method, params });
+ writeFileSync(log, JSON.stringify({ cwd: process.cwd(), startupCwd, calls }));
+ }
+ console.log(JSON.stringify({ id, ...(responses[method] ?? { result: {} }) }));
+}`,
+ );
+ const plugin = {
+ marketplacePath: join(home, "marketplace.json"),
+ pluginName: "selected-security",
+ };
+ const owner = "codex-security";
+ const alias = "codex.security";
+ const noDirect = { omit_tools_from: ["direct"] };
+ const config = { mcp_servers: { [owner]: noDirect } };
+ const read = (
+ detail: JsonObject,
+ settings: JsonObject = { result: { config } },
+ ) =>
+ readDeepScanParentConfig({
+ codexOptions: { env: { CODEX_HOME: home } },
+ preflightCommand: {
+ command: process.execPath,
+ args: [
+ script,
+ log,
+ JSON.stringify({ "config/read": settings, "plugin/read": detail }),
+ ],
+ },
+ scanDir,
+ signal: new AbortController().signal,
+ plugin,
+ });
+ const requests = async () => JSON.parse(await readFile(log, "utf8"));
+ const configRead = {
+ method: "config/read",
+ params: { cwd: scanDir, includeLayers: false },
+ };
+ const detail = {
+ result: {
+ plugin: {
+ summary: { installed: true, enabled: true },
+ mcpServers: [owner, alias],
+ },
+ },
+ };
+ expect(await read(detail)).toEqual({
+ mcp_servers: { [owner]: noDirect, [alias]: {} },
+ });
+ expect(await requests()).toEqual({
+ cwd: process.cwd(),
+ startupCwd: scanDir,
+ calls: [configRead, { method: "plugin/read", params: plugin }],
+ });
+ expect(
+ await read({ error: { code: -32601, message: "Method not found" } }),
+ ).toBeUndefined();
+ await expect(
+ read(detail, { error: { code: -32602, message: "invalid configuration" } }),
+ ).rejects.toThrow(
+ /Could not read the Deep Scan parent configuration[\s\S]*invalid configuration/u,
+ );
+ expect((await requests()).calls).toEqual([configRead]);
+});
diff --git a/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts b/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
index 5076368d2..9da22ea6e 100644
--- a/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
+++ b/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
@@ -207,15 +207,26 @@ test.each(["configured", "managed"] as const)(
...runtimeEnvironment,
CODEX_API_KEY: "synthetic-bun-scan-key",
};
+ const postScanPrompt = "Read the completed scan in a code-mode cell.";
+ const followUp = mock(async (prompt: string) => {
+ expect(prompt).toBe(postScanPrompt);
+ return { events: completedEvents("owner") };
+ });
+ const codeMode = { direct_only_tool_namespaces: ["caller_tools"] };
const parentTurn = mock(async (prompt: string) => {
expect(prompt).toContain("start_codex_security_deep_scan");
- throw new Error("parent route reached");
+ async function* events() {
+ yield { type: "thread.started", thread_id: "owner" };
+ throw new Error("parent route reached");
+ }
+ return { events: events() };
});
const client = new TestClient(
{
codexOverrides: {
model: "gpt-6.1-sol",
model_reasoning_effort: "high",
+ features: { code_mode: codeMode },
},
},
{
@@ -238,10 +249,21 @@ test.each(["configured", "managed"] as const)(
model_reasoning_effort: "high",
});
return {
- startThread: (options) => {
- expect(options.workingDirectory).toBe(scanDir);
+ startThread: (threadOptions) => {
+ expect(threadOptions.workingDirectory).toBe(scanDir);
return { id: null, runStreamed: parentTurn };
},
+ resumeThread: (id, threadOptions) => {
+ expect(id).toBe("owner");
+ expect(threadOptions.workingDirectory).toBe(scanDir);
+ expect(options.config?.["features"]).toMatchObject({
+ code_mode: codeMode,
+ });
+ expect(options.configOverrides?.join("\n")).not.toContain(
+ "direct_only_tool_namespaces",
+ );
+ return { id, runStreamed: followUp };
+ },
};
},
runDeepScan: async function* () {
@@ -253,9 +275,11 @@ test.each(["configured", "managed"] as const)(
await expect(
client.run(repository, {
mode: "deep",
+ postScanPrompt,
}),
).rejects.toThrow("parent route reached");
expect(parentTurn).toHaveBeenCalledTimes(1);
+ expect(followUp).toHaveBeenCalledTimes(1);
} finally {
await client.close();
}
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index 0d769c920..42a242587 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -15249,6 +15249,108 @@ if __name__ == "__main__":
},
);
+ test.each([undefined, "Record the failed scan."])(
+ "preserves the requested post-scan turn when Deep Scan routing fails with %p",
+ async (postScanPrompt) => {
+ const { repository, codexHome, scanDir } = await scanDirectories();
+ const target = ["api", "notes.md"];
+ await mkdir(join(repository, "api"));
+ await writeFile(join(repository, "notes.md"), "fixture");
+ const turns: Array<{ prompt: string; paths: string[] }> = [];
+ const warnings: string[] = [];
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ canRunDirectDeepScan: () => false,
+ readDeepScanParentConfig: async () =>
+ fail("native configuration failed"),
+ createCodex: async ({ env }) =>
+ codexFactory(async (prompt: string) => {
+ const pathsFile = env?.["CODEX_SECURITY_TARGET_PATHS_FILE"];
+ if (!pathsFile) throw new Error("Missing scope file location");
+ turns.push({
+ prompt,
+ paths: JSON.parse(await readFile(pathsFile, "utf8")),
+ });
+ return { events: completedEvents() };
+ })(),
+ });
+ try {
+ await expect(
+ client.run(repository, {
+ mode: "deep",
+ target,
+ postScanPrompt,
+ onWarning: (warning) => warnings.push(warning),
+ }),
+ ).rejects.toThrow("native configuration failed");
+ expect(warnings).toEqual([]);
+ expect(turns).toEqual(
+ postScanPrompt ? [{ prompt: postScanPrompt, paths: target }] : [],
+ );
+ } finally {
+ await client.close();
+ }
+ },
+ );
+
+ test("checks the resumed budget before routing a Deep Scan failure follow-up", async () => {
+ const { repository, codexHome, scanDir } = await scanDirectories();
+ const scanId = "scan_example_001";
+ const threadId = "thread-1";
+ await writeUsageSession(
+ codexHome,
+ threadId,
+ {
+ input_tokens: 2_000,
+ output_tokens: 0,
+ total_tokens: 2_000,
+ },
+ { cwd: scanDir },
+ );
+ const readConfig = mock(rejecting("native configuration failed"));
+ const runStreamed = mock(async () => ({
+ events: completedEvents(threadId),
+ }));
+ const thread = { id: threadId, runStreamed };
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ canRunDirectDeepScan: () => false,
+ readDeepScanParentConfig: readConfig,
+ createCodex: () => ({
+ startThread: () => thread,
+ resumeThread: () => thread,
+ }),
+ runWorkbench: async (_options, args, input): Promise<JsonObject> => {
+ if (args[0] === "get-cli-scan-resume")
+ return {
+ scanId,
+ scanDir,
+ threadId,
+ targetId: "target_sha256_example",
+ targetRevision: "deadbeef",
+ recipe: { repository, target: { kind: "repository", paths: [] } },
+ contract: { target: { allowedKinds: ["git_revision"] } },
+ };
+ return mockWorkbench(args, input);
+ },
+ });
+ try {
+ await expect(
+ client.run(repository, {
+ mode: "deep",
+ resumeScanId: scanId,
+ outputDir: scanDir,
+ maxCostUsd: 0.004,
+ postScanPrompt: "Summarize the failed scan.",
+ }),
+ ).rejects.toBeInstanceOf(ScanCostLimitExceededError);
+ expect(readConfig).not.toHaveBeenCalled();
+ expect(runStreamed).not.toHaveBeenCalled();
+ } finally {
+ await client.close();
+ }
+ });
+
test.each([
["a completed scan with scope notes", "completed", false, false],
["legacy coverage metadata", "legacy", false, false],
@@ -18434,6 +18536,7 @@ if ([basename(process.argv[1]), ...process.argv.slice(2)].join(" ") !== "login s
createCodex: (options: CodexOptions) => {
const codex = new Codex(options);
return {
+ resumeThread: codex.resumeThread.bind(codex),
startThread: (threadOptions: ThreadOptions) => {
const thread = codex.startThread(threadOptions);
return {
diff --git a/sdk/typescript/tests-ts/component-scan.test.ts b/sdk/typescript/tests-ts/component-scan.test.ts
index 932357ed6..81773289e 100644
--- a/sdk/typescript/tests-ts/component-scan.test.ts
+++ b/sdk/typescript/tests-ts/component-scan.test.ts
@@ -34,6 +34,7 @@ import {
type ComponentScanEvent,
type ComponentScanOptions,
} from "../src/component-scan.js";
+import * as deepScan from "../src/deep-scan.js";
import type { Finding, SeverityLevel } from "../src/models.js";
import { ScanResult } from "../src/result.js";
import * as runtime from "../src/runtime.js";
@@ -1870,6 +1871,10 @@ test.each([
return preparedRuntime("unused").plugin;
}),
spyOn(runtime, "probeCodexSandbox").mockImplementation(async () => {}),
+ // The Node child below implements only `codex exec`.
+ spyOn(deepScan, "readDeepScanParentConfig").mockImplementation(
+ async ({ codexOptions }) => codexOptions.config ?? {},
+ ),
spyOn(runtime, "resolvePluginPython").mockResolvedValue(
"/managed/python",
),
diff --git a/sdk/typescript/tests-ts/scan-recipe.test.ts b/sdk/typescript/tests-ts/scan-recipe.test.ts
index 8f994c008..082fef353 100644
--- a/sdk/typescript/tests-ts/scan-recipe.test.ts
+++ b/sdk/typescript/tests-ts/scan-recipe.test.ts
@@ -595,7 +595,7 @@ test.each(
args,
input,
);
- let launches = 0;
+ let modelTurns = 0;
const runtimeDependencies = {
environment,
prepareRuntime: async () => ({
@@ -613,15 +613,15 @@ test.each(
return command(args, input);
},
createCodex: ({ config }: { config?: JsonObject }) => {
- launches++;
- if (cleared) {
- expect(config).not.toHaveProperty(key);
- expect(config).not.toHaveProperty("analytics");
- expect(config).not.toHaveProperty("agents.reviewer.config_file");
- }
const thread = (id: string, cwd?: string) => ({
id,
async runStreamed() {
+ modelTurns++;
+ if (cleared) {
+ expect(config).not.toHaveProperty(key);
+ expect(config).not.toHaveProperty("analytics");
+ expect(config).not.toHaveProperty("agents.reviewer.config_file");
+ }
await writeSession(home, id, {}, { cwd });
return {
events: (async function* () {
@@ -637,7 +637,7 @@ test.each(
return {
startThread: (options?: { workingDirectory?: string }) =>
thread(
- `synthetic-model-file-thread-${launches}`,
+ `synthetic-model-file-thread-${modelTurns + 1}`,
options?.workingDirectory,
),
resumeThread: (id: string, options?: { workingDirectory?: string }) =>
@@ -694,7 +694,7 @@ test.each(
agents: { reviewer: { description: "updated reviewer" } },
});
}
- expect(launches).toBe(mode === "deep" ? 3 : 2);
+ expect(modelTurns).toBe(mode === "deep" ? 3 : 2);
expect(replay).not.toHaveProperty(key);
expect(replay).not.toHaveProperty("analytics");
expect(replay).not.toHaveProperty("agents.reviewer.config_file");
diff --git a/sdk/typescript/tests-ts/support/api-client.ts b/sdk/typescript/tests-ts/support/api-client.ts
index 1d78e1d4d..5bd30fcbc 100644
--- a/sdk/typescript/tests-ts/support/api-client.ts
+++ b/sdk/typescript/tests-ts/support/api-client.ts
@@ -54,6 +54,9 @@ export function withSyntheticScanEvents<T extends Partial<Dependencies>>(
};
},
runDeepScan: dependencies.runDeepScan ?? runDeepScan,
+ readDeepScanParentConfig:
+ dependencies.readDeepScanParentConfig ??
+ (async ({ codexOptions }) => codexOptions.config ?? {}),
};
}