Hook failure messages should identify the failing hook and expose diagnostics

What problem are you seeing?

When a hook fails, Codex currently surfaces a very terse message such as:

SessionStart hook (failed)
error: hook returned invalid session start JSON output

or:

PostToolUse hook (failed)
error: hook exited with code 1

This tells the user that a hook failed, but not enough to debug it when multiple hooks are configured. In practice, the user still has to manually inspect config files and scripts to answer basic questions:

• Which configured hook failed?
• Where was it configured?
• What command/script was executed?
• What was the exit code?
• Did stdout contain invalid JSON, mixed logs, or no output?
• Did stderr contain a useful error message?

I hit this on Codex CLI 0.136.0 with both SessionStart and PostToolUse failures in a hooks-heavy setup. The task itself could continue, but the hook failure surface was too opaque to quickly diagnose.

Requested improvement

Please make hook failure diagnostics identify the failing hook and expose a small, safe diagnostic block.

Useful fields would be:

hook_event: PostToolUse
hook_name_or_id: <configured name/id if available>
config_source: <path or profile source, secrets redacted>
command: <script/command path, secrets redacted>
exit_code: 1
stderr_tail: <last N lines>
stdout_tail: <last N lines, if safe>
stdout_parse_error: expected JSON object, got non-JSON output / empty output / mixed log output

For JSON-producing hooks, it would be especially helpful to distinguish:

• stdout was empty
• stdout was invalid JSON
• stdout contained valid JSON plus extra non-JSON logs
• stdout had unsupported fields
• hook exited non-zero before producing output

UI / workflow ideas

A failure message could show a compact summary with expandable details:

PostToolUse hook "my-hook-name" failed
source: ~/.codex/hooks.json
command: /path/to/script
exit_code: 1
stderr_tail: ...
stdout_parse_error: expected JSON object, received non-JSON log output

Actions that would reduce debugging friction:

• Copy diagnostics
• Open hook config
• Temporarily disable this hook for this session
• Show docs link for expected JSON schema for that hook event

Why this matters

Hooks are an advanced-user feature, but the current failure display is opaque even for advanced users. The result is that a 30-second script/config bug becomes a 10-minute hunt through hook sources.

This is also important for trust: if hooks can affect session startup or tool lifecycle behavior, users should be able to see exactly which hook failed and why.

Related issues I found before filing

This is adjacent to, but broader than:

• #18887: Stop hook invalid JSON error is too opaque for unsupported fields
• #22847: unable to trust hooks, error in CLI
• #23645: Computer Use get_app_state hang and relative hook path failure are hard to diagnose
• #26675: Plugin PostToolUse hook relative command resolves from workspace cwd

Those cover specific hook problems. This issue is about the general diagnostic surface for hook failures across hook event types.

Environment

• Codex CLI: 0.136.0
• Platform: macOS
• Account/profile used to file: Fearvox