Apply Patch System

Relevant source files

• codex-rs/core/src/message_history.rs
• codex-rs/core/src/tools/events.rs
• codex-rs/core/src/tools/handlers/apply_patch.rs
• codex-rs/core/src/tools/handlers/shell.rs
• codex-rs/core/src/tools/handlers/unified_exec.rs
• codex-rs/core/src/tools/network_approval.rs
• codex-rs/core/src/unified_exec/async_watcher.rs
• codex-rs/core/src/unified_exec/mod.rs
• codex-rs/core/src/unified_exec/process_manager.rs
• codex-rs/core/tests/suite/unified_exec.rs

Purpose and Scope

The Apply Patch System provides a specialized tool for file editing that uses a simplified, structured patch format designed to be easy for language models to generate and safe to parse. Unlike general shell execution, this system validates patches before applying them and emits granular events for tracking file changes.

For information about general command execution, see Shell Execution Tools. For unified exec process management, see Unified Exec Process Management. For tool approval and sandboxing orchestration, see Tool Orchestration and Approval.

---

Patch Format Grammar

The apply_patch tool accepts a stripped-down, file-oriented diff format with three fundamental operations:

*** Begin Patch
*** Add File: <path>
+<line1>
+<line2>
...
*** Update File: <path>
[*** Move to: <new_path>]
@@ [header]
 <context_line>
-<removed_line>
+<added_line>
...
*** Delete File: <path>
*** End Patch

Key Features:

• All file paths must be relative (absolute paths are rejected)
• Update operations support inline renaming via *** Move to:
• Hunks use @@ headers to specify context (class, function) when needed
• Context lines (prefixed with ) disambiguate code locations
• Models must include 3 lines of context before/after changes by default

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs305-378

---

Tool Registration and Variants

Freeform Tool (Lark Grammar)

Diagram: Freeform Tool Structure

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs278-288 codex-rs/core/src/tools/handlers/apply_patch.rs37

The freeform variant uses a Lark grammar definition that allows models to output patches directly without JSON wrapping:

ToolSpec::Freeform(FreeformTool {
    name: "apply_patch",
    format: FreeformToolFormat {
        type: "grammar",
        syntax: "lark",
        definition: APPLY_PATCH_LARK_GRAMMAR
    }
})

This is the preferred variant for GPT-5 class models that support custom tools.

JSON Function Tool

Diagram: JSON Tool Structure

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs291-378

For models that don't support freeform tools, the JSON variant wraps the patch content in a structured function call:

The input field contains the entire patch as a string.

---

Apply Patch Handler Flow

Diagram: Handler Execution Flow

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs80-188

Handler Entry Point

The ApplyPatchHandler implements the ToolHandler trait and processes both JSON and freeform payloads:

Payload Type	Extraction Method
ToolPayload::Function { arguments }	Parse JSON to ApplyPatchToolArgs, extract args.input
ToolPayload::Custom { input }	Use input directly

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs90-101

Parsing and Validation

The handler delegates to codex_apply_patch::maybe_parse_apply_patch_verified() which returns:

• MaybeApplyPatchVerified::Body(changes) - Valid patch, proceed to application
• MaybeApplyPatchVerified::CorrectnessError(err) - Patch format violations
• MaybeApplyPatchVerified::ShellParseError(err) - Failed to parse as shell command
• MaybeApplyPatchVerified::NotApplyPatch - Not an apply_patch command

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs107-187

Execution Paths

Direct Output Path

When apply_patch::apply_patch() returns InternalApplyPatchInvocation::Output(item), the patch can be applied without exec orchestration (e.g., simple validations or auto-approved changes).

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs109-116

Delegated Execution Path

For patches requiring approval or sandboxed execution:

1. Convert ApplyPatchAction to protocol FileChange map
2. Extract file paths for approval key generation
3. Create ApplyPatchRequest with:
   • action: The parsed patch action
   • file_paths: Absolute paths for approval tracking
   • changes: Protocol-format changes for events
   • exec_approval_requirement: Pre-computed approval requirement
   • timeout_ms: Optional timeout
   • codex_exe: Path to codex binary for sandbox execution

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs118-137

---

Interception System

Why Intercept?

Models sometimes generate shell commands like bash -c "apply_patch <<'EOF' ..." instead of using the dedicated tool. The interception system detects these patterns and routes them through the proper patch handler.

Diagram: Interception Flow

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs192-274 codex-rs/core/src/tools/handlers/shell.rs295-308 codex-rs/core/src/tools/handlers/unified_exec.rs171-185

Interception Points

Handler	Interception Location	Cleanup Required
ShellHandler	Before ToolOrchestrator::run()	None
ShellCommandHandler	Before ToolOrchestrator::run()	None
UnifiedExecHandler	After allocate_process_id(), before open_session_with_sandbox()	Must release_process_id()

Sources: codex-rs/core/src/tools/handlers/unified_exec.rs171-185

Intercept Function Signature

Returns Ok(Some(output)) when interception occurs, Ok(None) when the command is not apply_patch.

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs192-201

Model Warning

When interception occurs, the system records a warning to the model:

"apply_patch was requested via {tool_name}. Use the apply_patch tool instead of exec_command."

This feedback trains models to use the proper tool.

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs204-209

---

Approval and Sandbox Orchestration

Diagram: Orchestration Integration

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs130-156

ApplyPatchRequest Structure

The ApplyPatchRequest passed to the orchestrator contains:

Sources: codex-rs/core/src/tools/runtimes/apply_patch.rs (implied structure from usage)

File Path Extraction

The file_paths_for_action() function extracts all files involved in the patch, including move destinations:

This ensures approval requests cover both source and destination files.

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs39-56

Orchestrator Invocation

The orchestrator handles:

• Approval policy evaluation (bypass, prompt user, cache result)
• Sandbox selection (based on SandboxPolicy)
• Retry logic if sandbox denies execution

Sources: codex-rs/core/src/tools/handlers/apply_patch.rs139-156

---

Event Emission and Diff Tracking

Diagram: Event Lifecycle

Sources: codex-rs/core/src/tools/events.rs170-254 codex-rs/core/src/tools/events.rs491-525

PatchApplyBegin Event

Emitted before execution with:

File changes format:

Sources: codex-rs/core/src/tools/events.rs178-192

PatchApplyEnd Event

Emitted after execution with:

Sources: codex-rs/core/src/tools/events.rs491-512

Turn Diff Emission

If a SharedTurnDiffTracker is provided, the system:

1. Calls tracker.on_patch_begin(changes) at begin event
2. After end event, retrieves tracker.get_unified_diff()
3. Emits EventMsg::TurnDiff(TurnDiffEvent) with the complete unified diff

This enables UI clients to display cumulative file changes across all tools in a turn.

Sources: codex-rs/core/src/tools/events.rs514-524

---

Unified Exec Interception Test

The test suite verifies that exec_command via unified exec properly intercepts apply_patch:

The test confirms:

• PatchApplyBegin emitted with correct file changes
• PatchApplyEnd emitted with success status
• ExecCommandBegin never emitted (intercepted)
• Process ID released (no PTY spawned)
• File actually written with correct content

Sources: codex-rs/core/tests/suite/unified_exec.rs159-285

---

Summary

The Apply Patch System provides a structured, safe file editing mechanism with:

Component	Responsibility
Patch Format	Simplified diff syntax with Add/Update/Delete operations
Tool Variants	Freeform (Lark grammar) for advanced models, JSON for legacy
Handler	Parsing, validation, and delegation to orchestrator
Interception	Detects apply_patch in shell/exec commands, routes to handler
Orchestration	Approval prompting, sandbox selection, execution retry
Events	Granular begin/end events with file change details, diff tracking

This design ensures models can edit files reliably while maintaining full visibility and control through the approval and sandboxing systems.