Codex hook config fails to parse when top-level description is present

[pitimon]

Summary

Codex reports a hook config parse failure for the claude-mem-local Codex hook because the hook JSON includes a top-level description field next to hooks.

This machine's claude-mem-local marketplace/cache is local, but the upstream/source-of-truth for reporting this issue is this repo: pitimon/exp-myCodex.

Error

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

Affected File

hooks/codex-hooks.json

Current shape includes:

{
  "description": "claude-mem Codex CLI hook integration",
  "hooks": {
    "SessionStart": [],
    "UserPromptSubmit": [],
    "PreToolUse": [],
    "PostToolUse": [],
    "Stop": []
  }
}

Codex currently appears to accept only a top-level hooks object:

{
  "hooks": {
    "SessionStart": [],
    "UserPromptSubmit": [],
    "PreToolUse": [],
    "PostToolUse": [],
    "Stop": []
  }
}

Local Workaround Confirmed

Removing only the top-level description field from the cached plugin hook JSON resolves the parse warning locally. jq empty still passes after the change.

Suggested Fix

Update the Codex hook config emitted by this plugin to omit unsupported top-level metadata, or document the minimum Codex CLI/parser version if top-level description is intended to be supported.

Related Note

A separate local MCP startup warning was handled by adding this to ~/.codex/config.toml:

[mcp_servers.codex_apps]
startup_timeout_sec = 120

That looks like a separate startup-timeout concern, not the JSON schema parse failure described here.

[pitimon]

Runtime follow-up: duplicate Codex hook surface + worker drift on 13.6.2

Additional local validation on 2026-06-18 found that the original schema issue is only one part of the Codex availability problem. After the description parse issue was no longer the active blocker, Codex still showed startup-hook instability in ~/ISMS-SIT:

SessionStart hook (failed)
error: hook timed out after 5s

What was found

• Active Codex plugin path was claude-mem@claude-mem-local version 13.6.2 at:

/Users/itarun/.codex/local-marketplaces/claude-mem-local/plugin

• The worker health endpoint was still reporting an older live worker initially:

version: 13.6.1
workerPath: /Users/itarun/.claude/plugins/cache/thedotmack/claude-mem/13.6.1/scripts/worker-service.cjs

• Codex had two claude-mem hook surfaces active at the same time:
  • plugin-owned claude-mem@claude-mem-local:hooks/codex-hooks.json
  • user-level fallback ~/.codex/hooks.json

That produced 6 SessionStart hooks in one startup lifecycle, increasing timeout/race risk. A real lifecycle smoke showed the duplication clearly before cleanup.

Local mitigation applied

• Trimmed ~/.codex/hooks.json back to only the Obsidian Stop capture hook.
• Removed stale user-level claude-mem hook trust entries from ~/.codex/config.toml.
• Restarted the worker through the active 13.6.2 runtime.
• Changed active Codex PreToolUse to a fail-open no-op:

{
  "type": "command",
  "command": "printf '{\"continue\":true}\\n'",
  "timeout": 5
}

Reason: during worker restart/warm handoff, PreToolUse began blocking normal commands with claude-mem worker unreachable for N consecutive hooks. For availability, PreToolUse should not synchronously depend on worker health. PostToolUse can still capture observations.

Validation after mitigation

• node /Users/itarun/src-repo/exp-myCodex/scripts/claude-mem-codex-compat.cjs verify --json returned ok: true.
• Health endpoint reported worker 13.6.2.
• Real lifecycle smoke passed:

codex exec --skip-git-repo-check --cd /Users/itarun/ISMS-SIT 'Reply exactly: Ready.'

Observed lifecycle after cleanup:

hook: SessionStart
hook: SessionStart
hook: SessionStart
hook: SessionStart Completed
hook: SessionStart Completed
hook: SessionStart Completed
hook: UserPromptSubmit
hook: UserPromptSubmit Completed
codex
Ready.
hook: Stop
hook: Stop
hook: Stop Completed
hook: Stop Completed

No Failed lines remained, and the startup surface dropped from 6 SessionStart hooks to the 3 plugin-owned hooks.

Suggested follow-up for this repo

The compatibility helper/runbook should treat these as first-class checks for Codex readiness:

1. Detect duplicate claude-mem hook surfaces between plugin-owned hooks and ~/.codex/hooks.json.
2. Verify worker health version/path matches the active plugin version/path, not just that the endpoint is alive.
3. Keep Codex PreToolUse fail-open and non-blocking; do not let worker unreachability block ordinary tool execution.
4. Require a real codex exec ... 'Reply exactly: Ready.' lifecycle smoke before declaring startup-hook fixes complete.