Proposal: add PreToolUse/PostToolUse lifecycle hooks to Codex hooks engine

[pengjunfeng11]

Summary

I'd like to propose adding first-class tool lifecycle hooks to the new hooks engine, specifically:

• PreToolUse
• PostToolUse

This would extend the current lifecycle coverage beyond SessionStart and Stop and make it possible to observe, validate, or block tool execution before and after a tool call runs.

I reviewed the recent hooks work in PR #13276 and built a prototype locally using the same overall architecture.

Motivation

The current lifecycle hooks cover session boundaries, but not the most important execution boundary in Codex: tool calls.

Tool-use hooks would enable workflows like:

• validating tool arguments before execution
• blocking risky tool invocations with feedback to the model
• logging tool usage for project memory / learning workflows
• post-tool verification, auditing, and automatic warnings
• Claude-style PreToolUse / PostToolUse compatibility for users migrating workflows

Proposed design

Following the direction of the new hooks engine introduced in PR #13276, the proposal is:

• add new hook event names:
  • PreToolUse
  • PostToolUse
• support them in hooks.json
• define explicit input/output schemas for both events
• route them through the same hook engine / dispatcher / output parser path as the existing lifecycle hooks
• emit HookStarted / HookCompleted events for these hooks as well
• invoke them from the core tool dispatch path

Matching

Use the existing matcher-group pattern and match on tool_name, for example:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell_command|exec_command",
        "hooks": [
          {
            "type": "command",
            "command": "python my_pre_hook.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "shell_command",
        "hooks": [
          {
            "type": "command",
            "command": "python my_post_hook.py"
          }
        ]
      }
    ]
  }
}

Semantics

• PreToolUse
  • runs before the tool executes
  • can block execution and provide feedback
• PostToolUse
  • runs after the tool executes
  • receives execution metadata such as success, duration, and output preview

Example input fields

In the prototype, tool hook payloads include fields like:

• sessionId
• turnId
• cwd
• transcriptPath
• model
• permissionMode
• callId
• toolName
• toolKind
• toolInput

And for post-tool hooks additionally:

• executed
• success
• durationMs
• outputPreview

Local prototype status

I implemented this locally against the current hooks architecture and verified:

• cargo check -p codex-core
• cargo test -p codex-hooks
• a focused integration test that confirms both PreToolUse and PostToolUse are actually triggered around a real shell_command

The integration test verifies that:

• HookStarted / HookCompleted are emitted for both events
• the hook commands are executed
• the hook payloads contain the expected tool metadata
• the wrapped tool still executes normally

Question

Would the maintainers be open to this feature?

I saw the contribution policy in docs/contributing.md and understand that external PRs are only accepted when invited. If this direction makes sense, I'd be happy to open a PR from my prototype branch after maintainer guidance on:

• event naming / semantics
• expected schema shape
• whether PostToolUse should support blocking vs warning-only behavior
• whether this should coexist with legacy after_tool_use hooks or replace them over time

[pengjunfeng11]

Additional context: my main reason for wanting tool-use hooks is usage analysis.

I want to track which tools I use most, which tool sequences repeat in real work, and which tools tend to be used together. I am mainly using this as a foundation for lightweight workflow analysis and continuous learning.

A big reference for me is the everything-claude-code project. What is useful there is not just session memory, but observing tool behavior over time and learning from repeated patterns.

That is why PreToolUse / PostToolUse matter more than session-only hooks for my use case. If I want to understand real Codex workflows, the important signals are around tool boundaries:

• which tool was used
• with what input
• whether it succeeded
• how long it took
• what tool came next

So for me, this feature is mainly about tool statistics and workflow learning, not just blocking or policy enforcement.

[HeMuling]

This hook would be a very valuable addition, and a concrete use case is RTK: https://github.com/rtk-ai/rtk

Specifically:

• RTK rewrites common development commands to reduce LLM token consumption by roughly 60–90%.
• RTK already supports Claude Code and OpenCode, because Claude Code provides a PreToolUse hook and OpenCode provides tool.execute.before.
• Codex currently supports neither of these. Because of that, I previously added an experimental RTK integration that relies on Codex subprocess configuration to rewrite commands instead: feat(init): add experimental Codex adapter via subprocess-local PATH shims rtk-ai/rtk#642

Native support for a PreToolUse-style hook in Codex would be much cleaner.

If this is not something you plan to support, I would still appreciate guidance on whether it makes sense for me to continue maintaining the experimental RTK workaround.

[pengjunfeng11]

@etraut-openai I'm very excited to submit this PR!!! Could you consider opening permissions, or are there other options?

[who96]

I read the merged hooks work, the current codex-rs/hooks implementation, and the open proposals. I think the narrowest useful proposal to discuss here is smaller than a full PreToolUse + PostToolUse expansion plus a separate PermissionRequest hook.

What seems already true:

• the merged hooks engine already has the right shape for synchronous lifecycle hooks
• the current Stop and UserPromptSubmit hooks already show how blocking / feedback semantics are encoded at the hook layer
• #15211 shows that a shell-focused PreToolUse path is implementable with the current plumbing
• #13498 is useful context, but it is an open PR aimed at broader lifecycle coverage and is explicitly narrower than the broader Claude-compatible hooks line

If the goal is to land something practical first, the smallest cut that still looks useful to me is:

1. add blocking PreToolUse
2. keep the first version to shell-like tools only
3. make it deny-only for v1
4. defer PostToolUse, PermissionRequest, persistent allow rules, and non-shell tool coverage

I think that version is easier to review because it fits the current hooks engine, solves an obvious use case, and keeps the schema and test surface much smaller than a combined Pre/Post/PermissionRequest feature.

It would still cover a lot of real workflows, including the command-gating cases described in #14754, while leaving room for a later step toward #15311 if maintainers want a dedicated approval-oriented hook after PreToolUse exists.

If this direction sounds right, I’d expect the next step to be one of:

• evolve #15211 toward the agreed MVP shape
• open a new invited PR with this narrower scope
• or narrow it even further before code

I’m not posting code here because docs/contributing.md is explicit that external code contributions are by invitation only and unsolicited PRs will be closed. I wanted to sanity-check the scope here before going further.