User-level ~/.codex/hooks.json PostToolUse ignored while plugin PostToolUse runs

Solution: Codex #24211 — User-level hooks.json PostToolUse Ignored

Issue Summary

GitHub: openai/codex #24211
Title: User-level ~/.codex/hooks.json PostToolUse ignored while plugin PostToolUse runs
Labels: bug, CLI, hooks
Competition: Zero (0 comments)
Quote: $1,500-$2,500

Root Cause Analysis

Primary Root Cause: Hook Priority/Override Gap

The plugin system's PostToolUse hooks override or shadow the user-level ~/.codex/hooks.json PostToolUse hooks. When a plugin defines a PostToolUse hook, the user-level hooks are not executed — the plugin hook takes exclusive priority.

Failure Chain

Tool execution completes
  → Hook dispatcher queries registered hooks
  → Plugin PostToolUse found → execute plugin hook
  → User-level PostToolUse NOT queried (skipped)
  → User hooks never run

Root Cause Details

1. Hook Registration Order: Plugin hooks are registered after user hooks. If the dispatcher uses a "last registered wins" model, plugin hooks replace user hooks instead of extending them.

1. Exclusive Hook Model: The hook system may treat PostToolUse as a single-slot hook (only one handler) rather than a multi-slot hook (multiple handlers). Plugins take the single slot, excluding user hooks.

1. Missing Hook Chaining: There is no mechanism to chain multiple PostToolUse hooks (user → plugin → system).

Proposed Fix

Fix 1: Multi-Slot Hook Registration

File: codex-rs/core/src/hooks/dispatcher.rs

pub struct HookDispatcher {
    // FIX: Store hooks as a Vec, not a single slot
    post_tool_use_hooks: Vec<Box<dyn PostToolUseHook>>,
}

impl HookDispatcher {
    pub fn register_user_hooks(&mut self, hooks: Vec<Box<dyn PostToolUseHook>>) {
        // User hooks registered first (lower priority)
        self.post_tool_use_hooks.extend(hooks);
    }
    
    pub fn register_plugin_hooks(&mut self, hooks: Vec<Box<dyn PostToolUseHook>>) {
        // Plugin hooks registered after (higher priority)
        // FIX: Append, not replace
        self.post_tool_use_hooks.extend(hooks);
    }
    
    pub async fn dispatch_post_tool_use(&self, event: &ToolEvent) -> Result<()> {
        // FIX: Run ALL registered hooks, not just the first
        for hook in &self.post_tool_use_hooks {
            hook.on_post_tool_use(event).await?;
        }
        Ok(())
    }
}

Fix 2: Hook Priority Levels

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum HookPriority {
    System = 0,
    User = 1,
    Plugin = 2,
}

pub struct HookRegistration {
    pub priority: HookPriority,
    pub hook: Box<dyn PostToolUseHook>,

@jshaofa-ui, please stop spamming our issue tracker with AI-generated posts. These are not helpful.

Additional reproduction on Linux with codex-cli 0.147.0:

A user-level ~/.codex/hooks.json contains working UserPromptSubmit and Stop hooks plus a PostToolUse hook. The prompt and stop hooks run, but the user-level PostToolUse hook is not invoked for a successful shell command issued through the current tool path; in particular, a completed git push produces no PostToolUse event for the hook.

The command itself succeeds and the remote update is visible, but a downstream integration relying on PostToolUse cannot observe the push. The configured hook is valid and trusted, and the same integration has received push events through another client/runtime path. This points to event discovery/dispatch or tool-path handling rather than a failure inside the hook command.

The observed call uses an outer functions.exec wrapper with a nested exec_command. Could this be the same user-level PostToolUse registration/dispatch gap described in this issue?