Add first-class Codex support for Caveat retrieval and recording

[quolu]

Goal

Make Caveat fully usable from Codex, not only Claude Code.

Today Caveat already has a CLI, MCP server, markdown-in-git knowledge repo, and SQLite/FTS index, so Codex can read caveats through an external adapter. Full parity requires Caveat itself to understand Codex lifecycle/events and offer Codex-native retrieval and recording flows.

Desired Outcome

Codex should become a first-class Caveat client alongside Claude Code. Caveat should be able to surface relevant entries automatically during Codex work and suggest recording/updating caveats when Codex encounters objective struggle signals.

Scope

• Define a Codex integration mode that does not depend on Claude Code hooks.
• Support Codex App Server event/turn inputs or a documented JSON event adapter.
• Add Codex prompt-submit equivalent retrieval for user prompts.
• Add Codex tool/error equivalent retrieval for failing command/tool results.
• Add Codex session-end or turn-end signal mining for caveat record/update suggestions.
• Preserve existing caveat search, caveat show, and MCP server behavior.
• Expose enough metadata for Codex/codex-sidecar to preserve source boundaries: visibility, confidence, source, id, path, and relevant sections.
• Design safe Codex flows for caveat_record and caveat_update, especially around visibility: private and public-output leakage.

Non-goals

• Do not make Caveat depend on codex-sidecar internals unless there is a stable adapter contract.
• Do not silently treat Codex events as Claude transcript JSONL. Codex is a distinct source format.
• Do not auto-record private/repo-specific caveats into shared repos.
• Do not auto-surface private entries into public/external output without explicit visibility handling.

Acceptance Criteria

• Caveat can ingest or evaluate at least one documented Codex event format.
• Codex prompt/error retrieval can return relevant caveats without Claude hooks.
• A Codex-origin struggle signal can produce a structured record/update suggestion.
• Existing Claude Code hook and MCP tests remain passing.
• Failure modes are explicit; no hidden fallback to Claude-only behavior.

Related

• codex-sidecar can initially read Caveat via CLI/MCP as SidecarContextBlock kind: caveat_entry.
• Full automatic retrieval/recording should live in this Caveat repository.