Support additionalContext in PreToolUse hooks or clarify Claude-style hook parity

[jeffhuen]

What variant of Codex are you using?

CLI

What version of Codex are you using?

codex-cli 0.124.0

What happened?

Codex hooks are now stable/default-enabled, and the code/release language describes them as "Claude-style lifecycle hooks" loaded from hooks.json / config layers. However, PreToolUse currently rejects hookSpecificOutput.additionalContext even though that is a common Claude-style context-injection pattern.

A minimal PreToolUse hook like this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"Before searching raw files, use the project knowledge graph.\"}}'"
          }
        ]
      }
    ]
  }
}

produces:

PreToolUse hook returned unsupported additionalContext

The official hooks docs also state that for PreToolUse, additionalContext is parsed but not supported yet.

Why this matters

This creates a sharp compatibility trap for tools that install Claude-style hooks and expect context injection before tool use. One concrete example is Graphify:

• Graphify issue: codex not support additionalContext on PreToolUse safishamsi/graphify#533
• Graphify compatibility PR: fix hook context output - Fixes #533  safishamsi/graphify#534

Graphify originally installed a PreToolUse hook that injected context reminding the agent to consult graphify-out/GRAPH_REPORT.md before raw file search. That pattern works in Claude-style hook environments, but Codex rejects it.

The current workaround is to emit top-level systemMessage from PreToolUse instead:

{"systemMessage":"graphify: Knowledge graph exists..."}

That avoids the hard error, but it is not equivalent:

• It surfaces as repeated warning-style UI noise before every intercepted tool call.
• It is not the same documented developer-context path as additionalContext.
• It still leaves third-party hook installers needing Codex-specific branching.

SessionStart.additionalContext and UserPromptSubmit.additionalContext are valid alternatives for some tools, but they are not equivalent to PreToolUse:

• SessionStart is cheap but too early and easy to stale/forget during long sessions.
• UserPromptSubmit runs on every prompt even when no tool/search is about to happen.
• PreToolUse is the natural low-token place to inject context specifically when a tool is about to run.

Expected behavior

Ideally, PreToolUse should support:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "..."
  }
}

and add that text as extra developer context for the next model continuation, matching the behavior already available on SessionStart, UserPromptSubmit, and PostToolUse.

If supporting this on PreToolUse is intentionally out of scope because the model has already decided to call a tool, then the docs and release wording should clarify the distinction:

• Codex supports Claude-style hook discovery/config shape.
• Codex does not provide full Claude Code output-field parity for every hook event.
• PreToolUse is currently a guardrail/blocking hook, not a context-injection hook.

Suggested acceptance criteria

One of:

1. Add PreToolUse.hookSpecificOutput.additionalContext support and inject it as extra developer context after the intercepted tool event, or
2. Update the hooks docs and relevant examples to explicitly warn that PreToolUse.additionalContext is unsupported despite Claude-style hook config compatibility, and recommend SessionStart, UserPromptSubmit, or PostToolUse depending on intent.

Related context

• Codex hooks docs: https://developers.openai.com/codex/hooks
• Codex PR marking hooks stable: Mark codex_hooks stable #19012
• Codex 0.124.0 release notes mention stable hooks and expanded hook support: https://github.com/openai/codex/releases/tag/rust-v0.124.0