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.
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.