feat: Add Codex PreToolUse/PostToolUse hooks for graph context injection

[Maple0517]

Summary

Gortex currently implements rich hooks for Claude Code (PreToolUse, PostToolUse, PreCompact, Stop, SessionStart) but has no hooks for Codex CLI. The Codex adapter only writes MCP config and AGENTS.md communities block, missing the opportunity to proactively inject graph context during tool calls.

Problem

Codex CLI now supports lifecycle hooks (PreToolUse, PostToolUse, SessionStart) similar to Claude Code. Without hooks, Codex users experience:

1. Deferred tool discovery: Codex's tool_search may omit expected MCP tools on first query (tracked upstream as tool_search can miss exactly named deferred MCP tools, causing false unavailable conclusions openai/codex#21503)
2. No graph context injection: When Codex runs Grep, Glob, or Bash, it doesn't get enriched with graph context
3. No stale index detection: After git commit, Codex doesn't get notified to reindex
4. Inferior experience: Claude Code gets proactive graph integration; Codex gets passive MCP-only access

Current State

What Claude Code gets (from internal/agents/claudecode/hooks.go)

Hook	Behavior
PreToolUse	Enrich Read/Grep/Glob/Bash with graph context, deny mode available
PostToolUse	Augment tool output with graph context (enrich mode)
PreCompact	Inject orientation snapshot before context compaction
Stop	Post-task diagnostics (detect_changes, check_guards, dead_code)
SessionStart	Prime first turn with graph orientation

What Codex gets today (from internal/agents/codex/adapter.go)

Integration	Status
MCP config	✅ ~/.codex/config.toml
AGENTS.md	✅ Communities block
PreToolUse	❌ Missing
PostToolUse	❌ Missing
SessionStart	❌ Missing

Proposed Solution

Add Codex hooks support to the Codex adapter, following the same patterns as Claude Code hooks:

1. SessionStart hook (low-risk, high-value)

Inject a one-line reminder to use Gortex graph tools first:

# ~/.codex/config.toml
[[hooks.SessionStart]]
matcher = "startup|resume|clear|compact"

[[hooks.SessionStart.hooks]]
type = "command"
command = "echo 'Prefer gortex MCP tools (search_symbols, find_usages, analyze, get_callers) over Read/Grep/Glob for indexed source code.'"

Why SessionStart first?

• Lower risk than PreToolUse (no tool interception)
• Works across all lifecycle events (startup, resume, clear, compact)
• Directly addresses deferred tool discovery issue

2. PreToolUse hook (medium-risk, high-value)

Intercept Grep/Glob/Bash calls and inject graph context:

[[hooks.PreToolUse]]
matcher = "Grep|Glob|Bash"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "/path/to/gortex hook --mode=enrich"
timeout = 10

Implementation approach:

• Reuse existing gortex hook command (already implemented for Claude Code)
• Add --format=codex flag to output Codex-compatible JSON
• Follow same deny/enrich mode logic as Claude Code

3. PostToolUse hook (optional, for enrich mode)

Augment tool output with graph context:

[[hooks.PostToolUse]]
matcher = "Bash"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "/path/to/gortex hook --mode=post-enrich"
timeout = 10

Technical Notes

Codex hooks format

Codex uses TOML-based config (~/.codex/config.toml):

[[hooks.PreToolUse]]
matcher = "ToolName1|ToolName2"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "script-path"
timeout = 10

Differences from Claude Code

Aspect	Claude Code	Codex
Config format	JSON (settings.json)	TOML (config.toml)
Config location	~/.claude/settings.json	~/.codex/config.toml
Matcher syntax	Grep|Glob|Bash	Grep|Glob|Bash
Hook output	JSON to stdout	JSON to stdout
Timeout	seconds	seconds

Implementation location

• Add hooks logic to internal/agents/codex/hooks.go (new file)
• Reuse existing hook utilities from internal/agents/claudecode/hooks.go
• Add Codex-specific hook format conversion

Acceptance Criteria

1. gortex install detects Codex and installs SessionStart hook (user-level)
2. gortex init installs PreToolUse/PostToolUse hooks (project-level)
3. Hooks are idempotent (safe to run multiple times)
4. gortex init --no-hooks skips Codex hooks
5. gortex init --hooks-only refreshes Codex hooks
6. Tests cover fresh install, update, and removal
7. Documentation updated in docs/agents.md

References

• Codex CLI hooks documentation: https://developers.openai.com/codex/hooks
• Claude Code hooks implementation: internal/agents/claudecode/hooks.go
• Codex deferred tool discovery issue: tool_search can miss exactly named deferred MCP tools, causing false unavailable conclusions openai/codex#21503

Additional Context

• Codex CLI is gaining traction as a terminal-based coding agent
• Codex's hooks support is now stable
• This would make Gortex the first code intelligence engine with full Codex PreToolUse/PostToolUse support

---

Note: I'm willing to contribute a PR if maintainers agree with this direction.

[zzet]

Hey @Maple0517, thank you for raising this issue

Note: I'm willing to contribute a PR if maintainers agree with this direction.

Yes, I agree with this direction. @blankanswer has submitted 2 PRs to wire hooks integration, however the functionality is not fully covered the hooks integration yet. Contribution is welcome!