codex - 💡(How to fix) Fix Feature Request: Add TaskCompleted Hook Event [2 comments, 3 participants]

Description

Currently, Codex provides several hook events such as PreToolUse, PostToolUse, UserPromptSubmit, and Stop. However, there is no explicit hook that represents the completion of a full task (i.e., when the agent has finished executing a user request end-to-end).

I would like to propose introducing a new hook event: TaskCompleted.

Motivation

While existing hooks cover turn-level and tool-level lifecycle events, they are still somewhat fragmented when building higher-level integrations.

A TaskCompleted hook would provide a clear and reliable signal that:

The agent has finished executing the entire task

No further actions or tool calls are expected

The final output is ready for downstream processing

This is especially useful for:

Logging and analytics pipelines

Triggering post-task automation (e.g., notifications, CI steps)

Persisting results or summaries

Integrating with external orchestration systems

Measuring task-level performance and success rates

Proposed Behavior

The TaskCompleted hook should fire exactly once per task

It should run after the final response is generated

It should include structured metadata, such as:

Final response content

Task duration

Tools used (if applicable)

Status (success / failure / interrupted)

Example (conceptual):

{ "event": "TaskCompleted", "data": { "final_output": "...", "duration_ms": 12345, "tools_used": ["local_shell", "file_write"], "status": "success" } }

Why Existing Hooks Are Not Enough

Stop operates at turn scope, not full task scope

PostToolUse is too granular and tool-specific

There is no single event that reliably signals task-level completion

This makes it harder to build robust integrations without additional inference or custom patching.