bug(codex): two hooks.json issues break Codex integration — unknown field description + async hooks skipped

[Jhonatand26]

Description

Running engram setup codex and then launching Codex produces two startup warnings that partially break the Codex integration on Windows.

---

Bug 1 — description field breaks the hooks parser

Error

⚠ failed to parse plugin hooks config ~/.codex/plugins/cache/engram/engram/0.1.1/hooks/hooks.json:
  unknown field `description`, expected `hooks` at line 2 column 15

Root Cause

The hooks.json ships with a top-level description field:

{
  "description": "Engram persistent memory hooks — ...",
  "hooks": { ... }
}

Codex CLI uses strict JSON deserialization (deny_unknown_fields). The Codex hooks schema only accepts a root-level hooks key — any other field is a fatal parse error.

Fix

Remove the description field from plugin/codex/hooks/hooks.json.

---

Bug 2 — async: true hooks are silently skipped

Error

⚠ skipping async hook in ~/.codex/plugins/cache/engram/engram/0.1.1/hooks/hooks.json: async hooks are not supported yet
⚠ skipping async hook in ~/.codex/plugins/cache/engram/engram/0.1.1/hooks/hooks.json: async hooks are not supported yet

Root Cause

Two hooks are marked "async": true:

"SubagentStop": [{ "hooks": [{ "command": "subagent-stop.sh", "timeout": 10, "async": true }] }],
"Stop":         [{ "hooks": [{ "command": "session-stop.sh",  "timeout": 5,  "async": true }] }]

Codex CLI does not yet implement async hook execution. Instead of running them synchronously as a fallback, it silently skips them. This means:

• subagent-stop.sh — passive memory capture after subagent completion never fires
• session-stop.sh — end-of-session logging never fires

Fix

Option A (recommended short-term): Remove "async": true from both hooks in plugin/codex/hooks/hooks.json so they run synchronously within their timeout window. The timeouts (10 s and 5 s) are acceptable for cleanup tasks.

Option B (long-term): Track Codex async hook support and re-add "async": true once Codex implements it.

---

Workaround (applied manually)

Both fields removed from the local plugin cache file. All four hook events now load and execute correctly.

Environment

OS	Windows 11
Shell	PowerShell 7.6.2
Codex CLI	0.140.0
Engram Codex plugin	0.1.1
Engram binary	v1.16.3 (latest)

Notes

Neither issue affects Claude Code users — Claude Code's parser tolerates unknown fields and has its own async hook implementation.