| name | provider-codex |
| description | Track and maintain the upstream OpenAI Codex CLI contract. Use when OpenAI ships a Codex release, when a `codex exec` flag/sandbox/approval/resume/subcommand behaviour changes, or when an upstream scan flags drift. Process guidance only; `src/upstream-contracts.ts` is the mechanical source of truth. |
| metadata | {"author":"verivus-oss","version":"1.2"} |
Provider: OpenAI Codex CLI
Process guidance for keeping the gateway's Codex (codex) integration aligned
with the upstream CLI. This skill does not define argv/env behaviour; the
single mechanical source of truth is UPSTREAM_CLI_CONTRACTS.codex in
src/upstream-contracts.ts, enforced by validateUpstreamCliArgs /
validateUpstreamCliEnv. Never re-encode flags, sandbox/approval modes, or
resume rules here or in TOML.
Identity
These values mirror UPSTREAM_CLI_CONTRACTS.codex.upstreamMetadata and
docs/upstream/provider-sources.dag.toml ([providers.codex]). The TypeScript
metadata is authoritative; the TOML is scanner input only.
When to use
- An OpenAI Codex CLI release lands and you need to check for contract drift.
- A
codex request fails the upstream contract check before spawn.
npm run upstream:scan -- --live reports a change on the Codex release notes
or changelog.
How LLM agents should use Codex through the gateway
- Discover the live gateway/provider surface before relying on Codex-specific
controls:
provider_tool_capabilities({cli:"codex"})
For a cached read-only resource, use provider-tools://codex.
- Use
codex_request for normal implementation/review turns,
codex_request_async for long-running work, and codex_fork_session when a
real Codex session needs to branch.
- Omit
model unless the caller explicitly asked for a specific variant; the
gateway resolves the configured Codex default/profile.
- Prefer
sandboxMode:"workspace-write" when Codex needs a writable
workspace. fullAuto:true is the deprecated compatibility shorthand. Use
approvalStrategy:"legacy": Codex rejects mcp_managed before launch
because its ambient MCP configuration cannot be isolated, and
approvalPolicy has no effect for Codex.
- Do not pass Claude-style
allowedTools or disallowedTools; Codex does not
expose those request fields through the gateway. Codex owns its MCP
configuration, and a gateway mcpServers list is descriptive metadata, not
an enforceable allowlist.
- Use
sandboxMode, profile, configOverrides, oss, images,
outputFormat, and outputSchema only as reported by
provider_tool_capabilities. askForApproval and
useLegacyFullAutoFlag are deprecated compatibility inputs: current Codex
emits no corresponding argv and the gateway returns a warning. fullAuto:true
remains a compatibility shorthand for sandboxMode:"workspace-write".
These are provider-native legacy controls, not inputs to the Claude-only
gateway approval boundary.
- Codex continuity is real through
codex exec resume: pass a real Codex UUID
from ~/.codex/sessions/, or resumeLatest:true. Gateway gw-* IDs are not
Codex sessions. Resumed Codex sessions retain their provider-native posture;
sandboxMode and its deprecated fullAuto:true shorthand are dropped on
resume. resumeLatest selects Codex's globally latest session, inherits that
session's original cwd, and is not scoped by workingDir.
The provider-native workingDir and addDir flags scope new sessions only;
the gateway accepts but omits those fields on resume. A verified workspace
or gateway worktree can still select the child process launch cwd and bind
gateway tracking, but it does not retarget the resumed Codex session. Every
resume form, including a direct UUID resume, inherits the original native
session cwd.
- Codex new and resume requests send the exact prompt through stdin with the
native
- marker. They do not consume the platform's single-argv prompt
allowance and are never truncated. codex_fork_session uses the distinct
codex fork contract, remains argv-bound, and rejects oversized UTF-8 prompts
as non-retryable input_too_large. An otherwise unscoped child still runs in
a fresh neutral temporary cwd, not the gateway repository. All other
caller-controlled argv values are admitted in their final encoded form
before spawn. Embedded NUL bytes return non-retryable invalid_input
without exposing the rejected value. New and resumed stdin requests complete
only after the full payload write callback succeeds; a clean child exit with
closed or pending delivery is a fixed non-sensitive failure.
Full-access review handoff
For a user-authorized exhaustive review that needs full provider permissions and
native MCP access, do not infer the launch controls from this maintenance guide.
Follow multi-llm-review's full-access protocol, inspect the current request
schema and live capability response, and use a fresh target-checkout
node dist/index.js --transport=stdio gateway rather than a global process.
Reapply the grant on every new job, preserve native MCP configuration without a
pretend gateway allowlist, send the corrective-program report and exact
diff/file identity, set no caller caps, and honor a user-required 90-second
progress cadence. The reviewer must independently inspect code, docs, tests,
and commands before it can approve.
Scan for upstream change
npm run upstream:scan -- --provider codex
npm run upstream:scan -- --live --provider codex --fail-on-critical
npm run upstream:scan -- --live --provider codex --write-snapshot --write-report
A failed fetch is advisory (exit 0) unless --fail-on-critical is passed.
Update procedure when the upstream CLI changes
- Edit the contract in
src/upstream-contracts.ts (UPSTREAM_CLI_CONTRACTS.codex):
the exec / exec resume command shape, flag arities/enums, and the
resumeOnlyFlags / resumeForbiddenFlags lists all live here.
- Add a conformance fixture proving the new accept/reject behaviour
(mirror the existing
codex-* fixtures, including resume cases).
- If a source URL or watch category changed, update
upstreamMetadata and
mirror it into docs/upstream/provider-sources.dag.toml.
- Verify:
npm run build && npm run upstream:contracts and npm test.
Codex-specific notes (see the contract for exact rules)
