tracking: Codex 0.140.0 rejects codex-hooks.json due to unsupported root description field

[thedotmack]

Root Cause

The plugin/hooks/codex-hooks.json file includes a root-level description field that Codex CLI 0.140.0 rejects with an unknown-field error, preventing the entire Codex hook configuration from loading. The build validation checks event names under codexHooks.hooks but does not validate allowed root keys, so this incompatible field shipped undetected.

Tracked Items

Issues

• Closes Codex 0.140.0 rejects codex-hooks.json root description field #2947 — Codex 0.140.0 rejects codex-hooks.json root description field #2947

PRs

• Related PR Fix claude-mem codex-hooks.json for current Codex: drop description (0.140 parser) + filter SessionStart no-op #2953 — Fix claude-mem codex-hooks.json for current Codex: drop description (0.140 parser) + filter SessionStart no-op #2953
• Related PR fix(codex): remove unsupported hooks description #2948 — fix(codex): remove unsupported hooks description #2948

Resolution

This is the canonical tracking issue for this root cause. Individual issues and PRs listed above will be closed in favor of this one.

[WingsOfPanda]

Confirmed on a local Codex CLI v0.140.0 install with claude-mem 13.5.5.

Startup warning observed:

failed to parse plugin hooks config /home/liupan/.codex/plugins/cache/claude-mem-local/claude-mem/13.5.5/hooks/codex-hooks.json: unknown field `description`, expected `hooks` at line 2 column 15

Local minimal fix was to remove only the top-level description key from hooks/codex-hooks.json, leaving the existing hooks object unchanged. After that, codex plugin list no longer emitted the parse warning, and codex doctor --summary --ascii reached Configuration [ok] config loaded (it still reported unrelated network/MCP reachability issues in this sandbox).

I also had to patch the local marketplace source copy, not just the Codex cache, otherwise a reinstall/cache refresh can reintroduce the same root field.

[ychulin]

Still reproducing on codex-cli 0.141.0 with claude-mem 13.6.2 (macOS 26.5.1), installed via codex plugin marketplace add thedotmack/claude-mem + codex plugin add claude-mem@claude-mem-local.

Exact error from the Codex plugin config UI:

failed to parse plugin hooks config .../claude-mem/13.6.2/hooks/codex-hooks.json: unknown field description, expected hooks at line 2 column 15

So 13.6.2 still ships the root description key and PRs #2948/#2953 are not in a released build yet. Until then the entire Codex hook set silently fails to load — the toggles show as enabled in the UI but the hooks never actually run (no SessionStart context injection, no capture).

Workaround confirmed: removing the root description key from hooks/codex-hooks.json makes Codex load it cleanly — codex doctor is green and all 5 events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) parse. Note the Claude-side hooks/hooks.json carries the same key, but Claude Code's parser tolerates it; only Codex's strict parser rejects it.

[jeanmonet]

Confirmed on Codex CLI 0.142.0 with claude-mem 13.8.0: the plugin hook config fails to load when plugin/hooks/codex-hooks.json contains the root-level "description" field. Removing that field locally makes Codex load the plugin again. No environment-specific details needed.