Overview#

The Codex extension system exposes contributor traits that allow features and external integrations to hook into the session, thread, turn, and tool execution lifecycle. The Goals system is a first-class built-in extension that uses these same hooks to implement persistent, resumable agent objectives with token-budget tracking.

As of v0.133.0, Goals are enabled by default — the feature is registered as Stage::Stable with default_enabled: true 1, no longer behind an experimental flag.

Key entry points:

• Extension API — codex-rs/ext/extension-api/src/contributors.rs 2: all contributor trait definitions
• Tool lifecycle metadata — codex-rs/ext/extension-api/src/contributors/tool_lifecycle.rs 3
• Goals runtime — codex-rs/core/src/goals.rs 4
• Goals storage — codex-rs/state/src/runtime/goals.rs 5
• Goals extension — codex-rs/ext/goal/src/extension.rs 6

Extension Contributor Lifecycle Hooks#

All hooks are defined as async traits in contributors.rs. Each callback receives scoped ExtensionData stores (session_store, thread_store, turn_store) for managing extension-private state without touching core runtime objects.

Thread scope — ThreadLifecycleContributor 7#

Turn scope — TurnLifecycleContributor 8#

Tool scope — ToolLifecycleContributor 9#

ToolLifecycleContributor is observer-only — it cannot inspect or rewrite tool input/output 10.

Additional contributor traits#

• ContextContributor — injects prompt fragments during prompt assembly
• ConfigContributor — receives before/after snapshots on config changes
• TokenUsageContributor — called each time token usage is recorded from a model response
• ToolContributor — exposes native tools owned by a feature
• ApprovalReviewContributor — can claim and respond to approval-review prompts
• TurnItemContributor — post-processes parsed turn items before emission

Tool Execution Metadata for Extensions#

The ToolLifecycleContributor callbacks receive typed structs defined in tool_lifecycle.rs.

ToolStartInput — supplied when the host starts a tool call:

• session_store, thread_store, turn_store — scoped extension data
• turn_id, call_id — stable identifiers for correlation
• tool_name: &ToolName
• source: ToolCallSource

ToolFinishInput — all of the above plus:

• outcome: ToolCallOutcome

ToolCallSource distinguishes how the call originated:

• Direct — the model invoked the tool directly
• CodeMode { cell_id, runtime_tool_call_id } — a code-mode runtime cell issued the nested call

ToolCallOutcome captures the host-observed result:

• Completed { success: bool } — normal output; success is the tool's own success marker
• Blocked — blocked by host policy before the handler ran
• Failed { handler_executed: bool } — did not produce normal output
• Aborted — host cancelled before normal completion; a matching on_tool_start may not exist

Subagent Lifecycle Events#

When a subagent's status changes, the runtime injects a SubagentNotification into the model context as a hidden user-turn fragment. The struct carries two fields: agent_reference: String (the agent path) and status: AgentStatus.

The notification implements ContextualUserFragment — it is wrapped in <subagent_notification> / </subagent_notification> XML tags and serialized as JSON with agent_path and status keys. This makes subagent state visible to the model's next turn without appearing as a user-visible message.

AgentStatus variants 11:

Goals System#

Goals let an agent track a persistent objective with a token budget across multiple turns, stored in a dedicated database table that survives thread suspension and resumption.

Feature flag#

Feature::Goals is declared Stage::Stable with default_enabled: true 1. It can still be overridden in ~/.codex/config.toml via [features] goals = false. The Goals extension checks self.enabled(Feature::Goals) before every operation 12.

Goal states#

A goal's ThreadGoalStatus follows this state machine 13:

Active → Paused | Blocked | UsageLimited | BudgetLimited | Complete

Runtime event dispatch#

GoalRuntimeEvent drives all state transitions. The session reports events; goals.rs owns the policy:

GoalRuntimeState 14 manages concurrency with a semaphore-based accounting_lock and a separate continuation_lock.

Extension integration#

GoalExtension implements all six contributor traits, wiring goals into every relevant lifecycle gate:

Goal persistence is delegated to GoalStore in the state layer, which handles creation, status updates, and accounting-mode-gated writes (ActiveStatusOnly, ActiveOnly, ActiveOrComplete, ActiveOrStopped) 21.