Follow up Codex CLI upstream updates: unauthorable [agents]/[[skills.config]]/project_doc_* keys, additionalContextLimit dropped, Codex plugin bundles

[dyoshikawa]

Summary

Three Codex CLI surfaces are unfollowed as of upstream 0.146.0: feature-adjacent top-level config.toml keys ([agents], [[skills.config]], project_doc_*, mcp_oauth_callback_*, allow_managed_hooks_only) have no authoring path, the per-handler hook field additionalContextLimit (0.145.0) is dropped by the converter, and the checked-in Codex plugin layout (.codex-plugin/plugin.json + marketplace discovery) has no rulesync surface.

Reviewed releases 0.129.0 → 0.146.0 (2026-05-07 → 2026-07-29). Docs note: developers.openai.com/codex/* now 308-redirects to learn.chatgpt.com/docs/*; both hosts still serve content, and appending .md yields Markdown.

Recent Releases

• 0.145.0 (2026-07-21) — SessionEnd hook event (PR #33895, already followed) and configurable hook context spill limits additionalContextLimit (PR #34393, gap 2).
• 0.143.0 — relaxed top-level hooks.json metadata validation (PR #30229); 0.140.0 warned on unsupported fields (PR #26426).
• 0.134.0 — plugin feature flag removed (PR #22552); mcp_oauth_callback_url (PR #24120).
• 0.131.0 (2026-05-18) — plugin hooks enabled by default (PR #22549), allow_managed_hooks_only (PR #20319), mcp_oauth_callback_port (PR #20237).

Gaps

1. No authoring path for feature-adjacent top-level config.toml keys

• Upstream (config reference):
  • agents.enabled, agents.max_concurrent_threads_per_session, agents.default_subagent_model, agents.default_subagent_reasoning_effort, agents.interrupt_message — also in the subagents doc "Global settings" table.
  • [[skills.config]] with path/enabled — skills doc, "Enable or disable local Codex skills".
  • project_doc_max_bytes, project_doc_fallback_filenames — AGENTS.md doc.
  • mcp_oauth_callback_port, mcp_oauth_callback_url — MCP doc OAuth section.
  • allow_managed_hooks_only — 0.131.0.
• rulesync (project + global): .codex/config.toml has exactly three owners in src/features/shared/shared-config-gateway.ts — features (hooks), mcp_servers (mcp), and permissions/default_permissions plus the five CODEXCLI_OVERRIDE_KEYS (permissions). Every other top-level key is unreachable: computeCodexcliOverridePatch (src/features/permissions/codexcli-permissions.ts) warns and skips anything outside the allowlist. This contradicts the schema doc comment at src/types/permissions.ts ("Kept looseObject (verbatim passthrough) so future top-level Codex config keys can be authored without Rulesync modeling each one") — the schema accepts such keys, then the patch builder silently drops them.

2. hooks — additionalContextLimit cannot be authored

• Upstream: the hooks doc documents additionalContextLimit as a per-handler field capping how much additionalContext a command hook returns before Codex spills the full text to disk (default 2500 tokens). Added in 0.145.0 (PR #34393).
• rulesync (project + global): CODEXCLI_CONVERTER_CONFIG (src/features/hooks/codexcli-hooks.ts) declares stringPassthroughFields for only commandWindows and statusMessage. additionalContextLimit is a number, and tool-hooks-converter.ts has no number-passthrough kind (only boolean, string, array), so buildToolHooks drops it on both generate and import. Related: the optional top-level description metadata of hooks.json is also dropped on import (toRulesyncHooks reads only parsed.hooks).

3. Codex plugins — authorable, repo-scoped surface with no rulesync target

• Upstream (plugins doc): a checked-in plugin layout — .codex-plugin/plugin.json manifest with skills, optional .mcp.json (bundled MCP server), .app.json (registered connection), and lifecycle hooks at hooks/hooks.json — plus repo-scoped discovery via $REPO_ROOT/.agents/plugins/marketplace.json (personal equivalent ~/.agents/plugins/marketplace.json). Plugin hooks default-on since 0.131.0; flag removed in 0.134.0.
• rulesync: unsupported — no codexcli plugin surface. Rulesync generates every piece a plugin would bundle (skills into .agents/skills, hooks into .codex/hooks.json, MCP into .codex/config.toml) but cannot emit a plugin manifest or marketplace entry, so a team cannot author a distributable Codex plugin with rulesync.

Proposed Follow-up

1. Give each feature its own codexcli config-key surface rather than widening the permissions override: declare subagents: { kind: "replace-owned-keys", ownedKeys: ["agents"] } in the shared-config gateway, and extend the skills, rules, and mcp ownership entries with skills, project_doc_max_bytes/project_doc_fallback_filenames, and mcp_oauth_callback_port/mcp_oauth_callback_url respectively, each fed from a codexcli section in the matching rulesync config. At minimum, correct the misleading passthrough comment in src/types/permissions.ts so it describes the allowlist that actually exists.
2. Add a numberPassthroughFields kind to ToolHooksConverterConfig (mirroring the boolean/string implementations) and register additionalContextLimit for codexcli; optionally carry the top-level description metadata of hooks.json through import.
3. Model the Codex plugin bundle as a new target, coordinating the design with the Claude Code plugin target (Follow up Claude Code plugin upstream updates: ${CLAUDE_PLUGIN_ROOT} hook commands, forbidden plugin-agent frontmatter, plugin.json path overrides #2495 covers its current divergences) — both are "skills + hooks + MCP behind a manifest", so a shared canonical model is likely worth it. Scope as its own follow-on issue when picked up.

Non-gaps (verified)

• Hooks carry all eleven upstream events with correct PascalCase names, including SessionEnd and UserPromptSubmit.
• The .rules generator emits the current prefix_rule(pattern=, decision=, justification=) Starlark form; permission profiles, extends, :workspace_roots, glob_scan_max_depth, and unmanaged-network-key preservation are modeled; the legacy sandbox_mode interaction warning matches upstream's note.
• MCP unknown keys pass through verbatim, so auth = "chatgpt", required, and default_tools_approval_mode need no change.
• Commands remain deprecated upstream and global-only in rulesync — correct.
• No ignore or checks surface exists upstream — unsupported is correct.
• Global dry-run writes .agents/skills/, .codex/AGENTS.md, .codex/hooks.json, .codex/config.toml, .codex/rules/rulesync.rules — all matching documented USER-scope locations.

References

• https://developers.openai.com/codex/config-reference — top-level config.toml keys with no authoring path (gap 1).
• https://developers.openai.com/codex/agents — [agents] global settings table (gap 1).
• https://developers.openai.com/codex/skills — [[skills.config]] enable/disable (gap 1).
• https://developers.openai.com/codex/guides/agents-md — project_doc_max_bytes / project_doc_fallback_filenames (gap 1).
• https://developers.openai.com/codex/mcp — OAuth callback keys (gap 1).
• https://developers.openai.com/codex/hooks — additionalContextLimit and plugin-bundled hooks (gaps 2, 3).
• https://developers.openai.com/plugins/build/plugins — the Codex plugin layout and marketplace discovery (gap 3).
• https://github.com/openai/codex/releases — release timeline 0.129.0 → 0.146.0 and the cited PRs.