feat: Implement Lifecycle Hooks System - Phase 1 Complete

[mikeumus]

Summary

This PR implements a comprehensive lifecycle hooks system for Codex, enabling external scripts, webhooks, and integrations to be triggered at specific points in the Codex execution lifecycle.

What's Implemented

✅ Phase 1.1: Hook Type Definitions and Core Types

• Core Type System: Complete LifecycleEvent enum with 12 event types covering all major Codex lifecycle points
• Hook Types: Support for scripts, webhooks, MCP tools, and custom executables
• Hook Context: Environment variable injection, temporary file management, and template substitution
• Configuration System: TOML-based configuration with validation and schema checking
• Infrastructure: Hook registry, manager, and async executor framework

✅ Phase 1.2: Hook Registry System

• Priority Management: Automatic sorting and priority-based execution ordering
• Conditional Execution: Expression parser supporting equality, contains, and boolean conditions
• Advanced Features: Hook filtering by tags/priority, runtime registration, statistics
• Configuration Integration: Full integration with Codex's main configuration system

Key Features

Lifecycle Events

The system supports hooks for all major Codex lifecycle points:

• Session lifecycle (start, end)
• Task lifecycle (start, complete)
• Execution lifecycle (before/after command execution)
• Patch lifecycle (before/after patch application)
• MCP tool lifecycle (before/after tool calls)
• Agent interactions (messages, reasoning)
• Error handling

Hook Types

• Script Hooks: Execute shell scripts/commands with event context
• Webhook Hooks: Send HTTP requests to external APIs with event data
• MCP Tool Hooks: Call MCP tools as lifecycle hooks
• Custom Executable Hooks: Execute any binary with event data

Configuration Example

[hooks]
enabled = true
timeout_seconds = 30

# Session lifecycle hooks
[[hooks.session]]
event = "session_start"
type = "script"
command = ["./scripts/session-start.sh"]
environment = { CODEX_SESSION_ID = "{session_id}" }

# Task completion webhook
[[hooks.task]]
event = "task_complete"
type = "webhook"
url = "https://api.example.com/codex/task-complete"
method = "POST"
condition = "success == true"

# Error notification
[[hooks.agent]]
event = "agent_message"
type = "script"
command = ["./scripts/notify-error.sh"]
condition = "message.contains('ERROR')"
priority = 0  # High priority

Advanced Features

Conditional Execution

# Only run on successful commands
condition = "exit_code == 0"

# Only run on error messages
condition = "message.contains('ERROR')"

# Environment-based conditions
condition = "env.ENVIRONMENT == production"

Priority Management

HookPriority::HIGHEST  // 0 - Critical hooks
HookPriority::HIGH     // 25 - Important hooks
HookPriority::NORMAL   // 100 - Default priority
HookPriority::LOW      // 200 - Background hooks
HookPriority::LOWEST   // u32::MAX - Cleanup hooks

Template Substitution

# Hook scripts receive context via environment variables
echo "Task {task_id} completed with status {success}"
# Becomes: "Task task_123 completed with status true"

Architecture

The hooks system is built around these core components:

• Hook Manager: Central coordinator for all lifecycle hooks
• Hook Registry: Stores hook definitions and manages event routing
• Hook Executors: Execute different types of hooks (scripts, webhooks, MCP tools)
• Hook Context: Provides execution context and data to hooks

Integration

• Configuration: Seamlessly integrated with Codex's existing config system
• Events: Built on top of Codex's existing event architecture
• MCP: Reuses existing MCP infrastructure for tool-based hooks
• Security: Respects existing sandbox policies and permission systems

Testing

• 12 passing tests covering all major functionality
• Unit tests for core types, configuration, and registry
• Integration tests with the main configuration system
• Test coverage for priority sorting, condition evaluation, and hook execution

Files Added/Modified

New Files

• TODO.md - Comprehensive implementation roadmap
• codex-rs/core/src/hooks/mod.rs - Main hooks module
• codex-rs/core/src/hooks/types.rs - Core type definitions
• codex-rs/core/src/hooks/context.rs - Hook execution context
• codex-rs/core/src/hooks/config.rs - Configuration parsing
• codex-rs/core/src/hooks/registry.rs - Hook registry implementation
• codex-rs/core/src/hooks/manager.rs - Hook manager
• codex-rs/core/src/hooks/executor.rs - Hook execution framework

Modified Files

• codex-rs/core/Cargo.toml - Added dependencies (chrono, tempfile, async-trait)
• codex-rs/core/src/lib.rs - Added hooks module export
• codex-rs/core/src/config.rs - Integrated hooks configuration

Next Steps

This PR completes Phase 1 of the lifecycle hooks implementation. The next phases will include:

• Phase 2: Hook Execution Engine (manager coordination, timeout management)
• Phase 3: Event System Integration (protocol extensions, core integration)
• Phase 4: Client-Side Integration (CLI support, event processing)
• Phase 5: Configuration and Documentation (examples, comprehensive docs)
• Phase 6: Testing and Validation (e2e tests, performance testing)
• Phase 7: Advanced Features (monitoring, additional hook types)

Breaking Changes

None. This is a purely additive feature that doesn't affect existing functionality.

Performance Impact

Minimal. The hooks system is designed to be:

• Async-first: Non-blocking execution
• Opt-in: Disabled by default, zero overhead when not used
• Efficient: Event-driven architecture with minimal overhead

---

Ready for Review: This PR establishes a solid foundation for the lifecycle hooks system with comprehensive type safety, configuration management, and extensibility.

---

Pull Request opened by Augment Code with guidance from the PR author