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

[Maple0517]

Summary

codebase-memory-mcp already implements Codex SessionStart hook (#330) and Claude Code PreToolUse hook, but has no PreToolUse/PostToolUse hooks for Codex CLI. Codex now supports the same lifecycle hooks as Claude Code, and deserves the same proactive graph integration.

Problem

Codex CLI now supports PreToolUse/PostToolUse hooks similar to Claude Code. Currently:

1. Claude Code gets PreToolUse hook: Intercepts Grep/Glob, injects graph context via hook-augment subcommand
2. Codex only gets SessionStart: A static reminder that doesn't provide dynamic graph context
3. Inferior experience: Codex users don't get proactive graph context injection during tool calls

Current State

What Claude Code gets (from cli.c)

Hook	Behavior
PreToolUse	Intercept Grep/Glob, inject graph context via hook-augment (non-blocking)
SessionStart	One-line reminder to use graph tools
SubagentStart	Inject context into Claude subagents

What Codex gets today (from #330 implementation)

Hook	Behavior
SessionStart	✅ One-line reminder (implemented)
PreToolUse	❌ Missing
PostToolUse	❌ Missing

Proposed Solution

Extend the Codex hooks to include PreToolUse/PostToolUse, following the Claude Code pattern:

1. PreToolUse hook (high-value)

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

# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "Grep|Glob|Bash"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "/path/to/codebase-memory-mcp hook-augment"
timeout = 10

Implementation approach:

• Reuse existing hook-augment subcommand (already implemented for Claude Code)
• Add Codex-specific hook format in cli.c
• Follow same non-blocking design as Claude Code hooks

2. PostToolUse hook (optional)

Augment tool output with graph context:

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

[[hooks.PostToolUse.hooks]]
type = "command"
command = "/path/to/codebase-memory-mcp hook-augment --post"
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
Hook output	JSON to stdout	JSON to stdout
Timeout	seconds	seconds

Existing infrastructure

The hook-augment subcommand already exists and is agent-agnostic:

• Takes a search token from stdin
• Calls search_graph to find matching symbols
• Returns structured context to stdout
• Non-blocking (exits 0 on all failure paths)

Implementation location

• Extend cbm_upsert_codex_hooks() in cli.c to add PreToolUse hook
• Add cbm_install_codex_hook_script() to install the hook script
• Reuse existing hook-augment subcommand

Hook script for Codex

Create a Codex-specific hook script that:

1. Reads the tool call from stdin (JSON format)
2. Extracts the search token (from Grep pattern, Glob pattern, or Bash command)
3. Calls codebase-memory-mcp hook-augment with the token
4. Returns the augmented context to stdout

Alternative: Reuse the existing cbm-code-discovery-gate shim script with Codex-specific path resolution.

Acceptance Criteria

1. codebase-memory-mcp install detects Codex and installs PreToolUse hook
2. PreToolUse hook intercepts Grep/Glob/Bash (same as Claude Code)
3. Hook is non-blocking (exits 0 on all failure paths)
4. Hook injects graph context via search_graph results
5. codebase-memory-mcp uninstall removes Codex PreToolUse hook
6. Tests cover fresh install, update, and removal
7. Documentation updated in README.md Multi-Agent Support table

References

• Codex CLI hooks documentation: https://developers.openai.com/codex/hooks
• Claude Code PreToolUse implementation: src/cli/hook_augment.c
• 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
• The existing hook-augment subcommand can be reused directly
• This would make codebase-memory-mcp the first code intelligence engine with full Codex PreToolUse support
• Related: feat: add Codex SessionStart reminder hook for codebase-memory tool discovery #330 (SessionStart hook) - this issue extends that work

Proposed Multi-Agent Support Table Update

The README table currently shows:

Agent	MCP Config	Instructions	Hooks
Claude Code	.claude/.mcp.json	4 Skills	PreToolUse (Grep/Glob graph augment, non-blocking)
Codex CLI	.codex/config.toml	.codex/AGENTS.md	SessionStart reminder

After this change:

Agent	MCP Config	Instructions	Hooks
Claude Code	.claude/.mcp.json	4 Skills	PreToolUse (Grep/Glob graph augment, non-blocking)
Codex CLI	.codex/config.toml	.codex/AGENTS.md	PreToolUse (Grep/Glob graph augment, non-blocking) + SessionStart reminder

---

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

[DeusData]

Thanks for the detailed proposal. Directionally this belongs in the editor/agent integration epic. We need to validate Codex hook semantics against the current config format before wiring anything into install/uninstall, but reusing hook-augment and keeping failures non-blocking is the right constraint. A focused PreToolUse-only first PR would be easier to review than doing PreToolUse and PostToolUse at once.

[rudi193-cmd]

Prior art — Willow Fylgja hooks (Cursor / Claude Code)

willow-2.0 already wires graph-adjacent context through PreToolUse / PostToolUse hooks (willow/fylgja/events/pre_tool.py, post_tool.py) — session boot, security scan, worktree cleanup, etc.

Lessons from running this in production that may inform a Codex hook PR:

Constraint	What we learned
Cold-start budget	Related to #858 — hook-augment must stay under client deadline or it silently never appears
Alias imports	scan_bash as _scan_bash breaks CBM caller attribution (#875) — hooks that trust graph alone mis-rank production usage
MCP vs native tools	We route shell to Kart queue, not raw Bash — hook surface differs by client
Non-blocking	Scan failures warn; they do not block the tool unless SEV_HIGH

A PreToolUse-only first PR (as maintainer suggested) aligns with how we ship: boot digest + cbm_search anchor before edits, security scan on Bash/Write.

Our audit addendum documents the CBM guardrails we layer on top: docs/audits/CODEBASE_MEMORY_MCP_TOOL_EVAL_ADDENDUM_2026-07-05.md