feat(codex): add hook conversion support for 5 Codex lifecycle events#354
Draft
feat(codex): add hook conversion support for 5 Codex lifecycle events#354
Conversation
Codex has been incrementally shipping hook support (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop), but the Codex converter silently dropped all hooks during conversion -- the only converter that didn't even warn. This adds partial hook conversion for the 5 compatible events and specific warnings for everything unconvertible. - Add CodexHookEventName union, CodexHookCommand, CodexHookMatcher, CodexHooks types and hooks field to CodexBundle - Add CODEX_EVENTS map with toolScoped flag, isBashCompatibleMatcher() helper, and convertHooksForCodex() to the converter - Write .codex/hooks.json with backup support in the writer - Auto-enable [features] codex_hooks = true in config.toml when hooks present - Refactor renderCodexConfig() to options object for extensibility - Update Codex spec with hooks documentation - 18 new tests (12 converter + 6 writer) PostToolUse conversion depends on openai/codex#15531 merging.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Codex converter has been silently dropping all hooks during Claude-to-Codex conversion since the converter was first written. Every other converter (Windsurf, Kiro, Copilot, Gemini) at minimum emits
console.warnwhen hooks are skipped -- the Codex converter had zero hook handling at all.Meanwhile, Codex has been incrementally shipping hook support across multiple PRs, creating a growing conversion gap:
This PR closes the gap by converting compatible hooks and emitting specific warnings for everything unconvertible.
Why this matters
Plugins with security-critical hooks (e.g., PreToolUse deny hooks that block dangerous commands) or workflow hooks (e.g., UserPromptSubmit context injection) lose that protection silently when converted to Codex. Users get no indication their hooks were dropped. This is especially concerning for PreToolUse hooks that enforce safety policies.
Changes
src/types/codex.ts): AddedCodexHookEventNamestring literal union for compile-time safety against invalid events (critical given Codex'sdeny_unknown_fields), plusCodexHookCommand,CodexHookMatcher,CodexHookstypes andhooksfield onCodexBundlesrc/converters/claude-to-codex.ts): AddedCODEX_EVENTSmap withtoolScopedflag,isBashCompatibleMatcher()helper, andconvertHooksForCodex()that filters to compatible hooks and emits specific warnings for everything skippedsrc/targets/codex.ts): Writes.codex/hooks.jsonwith backup support, auto-enables[features] codex_hooks = trueinconfig.toml, refactoredrenderCodexConfig()to options objectsrc/sync/codex.ts): UpdatedrenderCodexConfigcall site for new signature (backward compatible)docs/specs/codex.md): Added Hooks section with supported events, format, converter behavior, and constraintsdocs/solutions/integration-issues/codex-hook-converter-gap.md): Full gap analysis with upstream PR links and compatibility matrixdocs/plans/2026-03-23-001-feat-codex-hook-conversion-beta-plan.md): Implementation plan (completed)Key decisions
Bash|Writeare skipped entirely with warning[features] codex_hooks = true) written at top of config.toml to stay outside sync path's managed block markersTest plan
bun run release:validatepasses