Tool Orchestration and Approval

Relevant source files

• codex-rs/core/src/exec.rs
• codex-rs/core/src/guardian/mod.rs
• codex-rs/core/src/guardian/policy_template.md
• codex-rs/core/src/guardian/prompt.rs
• codex-rs/core/src/guardian/review.rs
• codex-rs/core/src/guardian/review_session.rs
• codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_followup_review_request_layout.snap
• codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_review_request_layout.snap
• codex-rs/core/src/guardian/tests.rs
• codex-rs/core/src/sandboxing/mod.rs
• codex-rs/core/src/tasks/user_shell.rs
• codex-rs/core/src/tools/network_approval.rs
• codex-rs/core/src/tools/network_approval_tests.rs
• codex-rs/core/src/tools/orchestrator.rs
• codex-rs/core/src/tools/runtimes/apply_patch.rs
• codex-rs/core/src/tools/runtimes/apply_patch_tests.rs
• codex-rs/core/src/tools/runtimes/mod.rs
• codex-rs/core/src/tools/runtimes/mod_tests.rs
• codex-rs/core/src/tools/runtimes/shell.rs
• codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs
• codex-rs/core/src/tools/runtimes/shell/unix_escalation_tests.rs
• codex-rs/core/src/tools/runtimes/unified_exec.rs
• codex-rs/core/src/tools/sandboxing.rs
• codex-rs/core/tests/common/zsh_fork.rs
• codex-rs/core/tests/suite/guardian_review.rs
• codex-rs/core/tests/suite/network_approval.rs
• codex-rs/core/tests/suite/skill_approval.rs

Purpose and Scope

This page documents the ToolOrchestrator codex-rs/core/src/tools/orchestrator.rs and the surrounding infrastructure that centralizes approval prompting, additional permissions handling, sandbox type selection, and retry-on-denial semantics for all executable tool runtimes. It covers the shared traits (Approvable, Sandboxable, ToolRuntime codex-rs/core/src/tools/sandboxing.rs1-5), the ExecApprovalRequirement codex-rs/core/src/tools/sandboxing.rs156-175 computation, permission validation, guardian sub-agent approval, and how those pieces coordinate across the concrete runtimes: ShellRuntime codex-rs/core/src/tools/runtimes/shell.rs90-92 UnifiedExecRuntime codex-rs/core/src/tools/runtimes/unified_exec.rs98-101 and ApplyPatchRuntime codex-rs/core/src/tools/runtimes/apply_patch.rs57-59

Key approval flows covered:

• Sandbox escalation approval: Commands requiring RequireEscalated sandbox permissions codex-rs/core/src/tools/sandboxing.rs23
• Additional permissions approval: Commands requesting granular filesystem/network permissions via AdditionalPermissionProfile codex-rs/core/src/tools/sandboxing.rs131-134
• Guardian auto-approval: AI-powered low-risk command pre-approval managed by GuardianReviewSession codex-rs/core/src/guardian/review_session.rs108-115
• Unix Escalation Protocol: Specialized handling for zsh-fork and codex-shell-escalation codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs104-109

Sources: codex-rs/core/src/tools/orchestrator.rs codex-rs/core/src/tools/sandboxing.rs1-175 codex-rs/core/src/tools/runtimes/shell.rs90-92 codex-rs/core/src/tools/runtimes/unified_exec.rs98-101 codex-rs/core/src/tools/runtimes/apply_patch.rs57-59

---

Architecture Overview

Every executable tool call is orchestrated through a common approval and sandbox management pipeline managed by ToolOrchestrator. This orchestrator:

1. Determines whether approval is required for a tool invocation using ExecApprovalRequirement codex-rs/core/src/tools/sandboxing.rs156-175
2. Reuses cached approvals via with_cached_approval, skipping user prompts for known safe commands codex-rs/core/src/tools/sandboxing.rs71-117
3. Invokes the Guardian sub-agent when enabled for low-risk AI-based auto-approval codex-rs/core/src/guardian/review_session.rs38-48
4. Falls back to interactive user approval if necessary, emitting events like AskForApproval codex-rs/core/src/tools/sandboxing.rs128
5. Selects an appropriate sandbox environment using select_process_exec_tool_sandbox_type codex-rs/core/src/exec.rs117-130
6. Retries execution with relaxed sandboxing on denial, based on escalate_on_failure() policy codex-rs/core/src/tools/sandboxing.rs151-153

Orchestration Pipeline:

Sources: codex-rs/core/src/tools/orchestrator.rs codex-rs/core/src/tools/sandboxing.rs71-153 codex-rs/core/src/exec.rs117-130 codex-rs/core/src/guardian/review_session.rs38-48

---

Key Types and Code Entities

This system uses several traits and structs to orchestrate tool execution from natural language intent down to code actions:

Type	File	Role
ToolOrchestrator	codex-rs/core/src/tools/orchestrator.rs	Central orchestrator coordinating approval → sandbox → run → retry lifecycle.
ExecApprovalRequirement	codex-rs/core/src/tools/sandboxing.rs156-175	Enum representing approval requirement computed from exec policy and permissions.
ToolRuntime	codex-rs/core/src/tools/sandboxing.rs35-38	Trait combining approval and sandbox interface for runtime implementations.
ShellRuntime	codex-rs/core/src/tools/runtimes/shell.rs90-92	Concrete runtime for shell command execution.
UnifiedExecRuntime	codex-rs/core/src/tools/runtimes/unified_exec.rs98-101	Concrete runtime for PTY-based unified exec command execution.
ApplyPatchRuntime	codex-rs/core/src/tools/runtimes/apply_patch.rs57-59	Concrete runtime for applying verified code patches.
ApprovalStore	codex-rs/core/src/tools/sandboxing.rs41-44	Cache for serialized approval decisions to skip redundant prompts.

Sources: codex-rs/core/src/tools/sandboxing.rs35-175 codex-rs/core/src/tools/runtimes/shell.rs90-92 codex-rs/core/src/tools/runtimes/unified_exec.rs98-101 codex-rs/core/src/tools/runtimes/apply_patch.rs57-59

---

ExecApprovalRequirement Computation

The execution approval requirement for a command is computed before runtime invocation. The ExecApprovalRequirement codex-rs/core/src/tools/sandboxing.rs156-175 drives the decision to require approval, skip it, or forbid execution.

Key aspects considered:

• AskForApproval Policy: Whether the global policy mandates prompting codex-rs/core/src/tools/sandboxing.rs198-208
• Sandbox Escalation: Interaction with requested sandbox permissions, especially when bypassing the sandbox codex-rs/core/src/tools/sandboxing.rs158-165
• Proposed Amendments: Optional ExecPolicyAmendment suggested to the user to avoid future prompts codex-rs/core/src/tools/sandboxing.rs178-191

Sources: codex-rs/core/src/tools/sandboxing.rs156-208

---

AskForApproval and Granular Policies

AskForApproval codex-rs/core/src/tools/sandboxing.rs21 controls when approval prompts may be emitted for tool runs.

Variant	Behavior
Never	Never emits approval prompts; commands run directly or error if conflicting.
OnRequest	Prompts when model requests elevated permissions explicitly codex-rs/core/src/tools/sandboxing.rs204
UnlessTrusted	Prompts for all non-trusted commands codex-rs/core/src/tools/sandboxing.rs207
Granular	Provides fine-grained control over rules and sandbox_approval prompts independently codex-rs/core/src/tools/sandboxing.rs204-206

Sources: codex-rs/core/src/tools/sandboxing.rs198-208

---

SandboxPermissions and Additional Permissions

Tool runtimes handle sandboxing and permission escalation via SandboxPermissions codex-rs/core/src/sandboxing/mod.rs23-24 and AdditionalPermissionProfile codex-rs/core/src/tools/runtimes/unified_exec.rs77

• RequireEscalated permission forces execution outside sandbox (full system access) codex-rs/core/src/tools/sandboxing.rs23
• WithAdditionalPermissions requests access to fine-grained filesystem paths or network codex-rs/core/src/tools/sandboxing.rs94-98
• Permission requests must be approved either automatically (Guardian) or interactively via start_approval_async codex-rs/core/src/tools/sandboxing.rs32

The function default_exec_approval_requirement codex-rs/core/src/tools/sandboxing.rs198-208 computes the baseline requirement based on whether the current sandbox policy is restrictive.

Sources: codex-rs/core/src/tools/sandboxing.rs23-208 codex-rs/core/src/sandboxing/mod.rs23-24

---

Guardian Approval Sub-Agent

The Guardian system serves as an AI-powered sub-agent that may automatically approve low-risk tool executions, reducing user burden.

Data Flow and Interaction

The Guardian first collects relevant conversation history via GuardianTranscriptCursor for context delta prompts codex-rs/core/src/guardian/review_session.rs60 It then receives the proposed tool call wrapped as a GuardianApprovalRequest codex-rs/core/src/guardian/review_session.rs82 Using the build_guardian_prompt_items_with_parent_turn builder codex-rs/core/src/guardian/review_session.rs61 the system synthesizes an AI prompt and runs an independent Codex thread dedicated to review via run_codex_thread_interactive codex-rs/core/src/guardian/review_session.rs38

On completion, the Guardian returns a GuardianReviewSessionOutcome indicating approval, rejection, or conditional action codex-rs/core/src/guardian/review_session.rs67-76

Risk Assessment Details

• Transcript Delta: If possible, the system sends only new history since last review via GuardianPromptMode::Delta, reducing prompt size codex-rs/core/src/guardian/review_session.rs124-126
• GuardianRejectionCircuitBreaker: Prevents infinite loops or flooding by interrupting turns after 3 consecutive Guardian denials or 10 recent denials codex-rs/core/src/guardian/mod.rs91-113
• Reuse Key: GuardianReviewSessionReuseKey tracks settings like model, permissions, and features to invalidate cached review sessions if the environment changes codex-rs/core/src/guardian/review_session.rs154-178

Sources: codex-rs/core/src/guardian/review_session.rs38-178 codex-rs/core/src/guardian/mod.rs91-113

---

Unix Escalation and Zsh Fork

On Unix systems, the ShellRuntime supports a specialized ZshFork backend codex-rs/core/src/tools/runtimes/shell.rs87 This uses codex-shell-escalation to manage permissions.

• Escalation Policy: Evaluated via EscalationPolicy to decide if a command can run with elevated privileges codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs56-58
• Approval Routing: If an escalation requires approval, it is routed to the Guardian if configured codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs173-195
• Sandbox Transformation: The orchestrator prepares an ExecRequest that includes the necessary sandbox types (e.g., Landlock or Seatbelt) codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs148-171

Sources: codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs56-195 codex-rs/core/src/tools/runtimes/shell.rs87

---

Summary

The tool orchestration and approval subsystem in Codex centralizes complex interactions spanning execution policy evaluation, sandboxing, approval prompting, and auxiliary AI-powered review via the Guardian sub-agent. This leads to consistent, policy-driven, and user-transparent tool execution, with the flexibility to retry on sandbox denials.

Sources: codex-rs/core/src/tools/orchestrator.rs codex-rs/core/src/tools/sandboxing.rs35-175 codex-rs/core/src/guardian/review_session.rs67-76 codex-rs/core/src/guardian/mod.rs91-113 codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs104-109