Skip to main content
CLI-backed agent runtimes let Pioneer delegate a turn to a local CLI application that has its own native thread, model selection, approval flow, and event stream. The committed adapters cover Codex CLI and Claude Code through crates/cli-agent-runtime and crates/gateway/src/cli_runtime/*. This layer is intentionally separate from crates/provider. A provider adapter turns a normalized ChatRequest into a remote model API call. A CLI runtime is a process/session integration: Pioneer starts or resumes a native runtime thread, maps runtime events into Pioneer timeline items, handles approval and input requests, and persists enough binding state to recover after gateway restart.

​
Responsibilities

​
Why it is not a provider

Provider adapters are stateless request translators from Pioneer’s perspective. A CLI runtime is stateful and session-oriented. It may have:
  • a native thread id separate from the Pioneer thread id;
  • a native turn id separate from the Pioneer turn id;
  • an app-server process that must be started, cached, closed, or restarted;
  • login/account state independent from provider API keys;
  • pending approval or user-input requests that require client interaction;
  • runtime-native capabilities such as compact, fork, review start, and steering.
Putting that into pioneer-provider would leak process lifecycle and native-thread state into the model API layer. Instead, CLI runtime execution is selected through the turn execution backend and documented by CLI Runtime API.

​
Session keys and cache

CLIAgentRuntimeSessionKey is the gateway cache key: CLIAgentRuntimeManager owns session reuse. get_or_start_with_options first tries an existing session with the same key and start options. If options differ, the stale session is closed and a new one is started. Per-key start locks prevent concurrent starts from spawning duplicate app-server processes for the same thread. Idle sessions are closed by TTL. close_session and close_all support forced cleanup during turn shutdown or gateway shutdown. The manager owns session generations, launch-contract comparison, replacement barriers, and cache publication. Provider-specific behavior stays behind the CLIAgentRuntimeSession trait and the Codex or Claude session adapter.

​
Session trait

CLIAgentRuntimeSession is the runtime abstraction the gateway uses after a process is started. The contract is provider-neutral where the operation exists for more than one runtime:
  • take_event_receivers returns the shared runtime event channel;
  • take_codex_event_receivers remains as a Codex-specific compatibility channel;
  • start_thread, resume_thread, and start_turn open and run a native thread or turn;
  • prepare_mcp_turn, activate_mcp_turn, retarget_mcp_turn, and terminal_mcp_turn bind the selected MCP projection to a turn;
  • respond_to_request and fail_request resolve native server requests;
  • interrupt_turn, probe_turn_liveness, and load_turn_snapshot support control and recovery;
  • thread_compact, set_thread_name, fork_thread, and steer_turn expose optional native operations.
The default implementation returns “not supported” for operations a runtime does not implement. Capability reporting must match those implementations. Adding a new runtime kind must not make it claim Codex-only operations or native features it cannot execute.

​
Thread binding

A Pioneer thread can be bound to one native runtime thread or provider continuation. open_cli_runtime_thread_binding is the generic gateway path. For a runtime that exposes native thread operations, a new binding calls start_thread, records the returned native thread id, cwd, model, and resume cursor, and stores a cli_runtime_thread_binding row. A resumable binding validates workspace and runtime identity before calling resume_thread with the stored native thread id. Codex maps these operations to its app-server thread/start and thread/resume methods. Claude uses a durable provider session UUID and starts or resumes its CLI process from that identity. Claude’s provider session identity is prepared and persisted before process allocation. A reload reuses the stored UUID instead of minting a new conversation. For Codex, the native thread id is a continuation detail consumed when a process is started or resumed; changing that id alone does not require a new process generation. The invariant is strict: a Pioneer thread cannot silently move between runtime instances or workspace ids. If an existing binding says the thread belongs to runtime A, a request for runtime B fails instead of rewriting lineage.

​
Turn binding

Thread binding maps long-lived thread identity. Turn binding maps active execution. A CLI-backed turn persists:
  • Pioneer turn_id and thread_id;
  • runtime id and runtime kind;
  • native thread id;
  • native turn id when available;
  • request id;
  • runtime status such as starting, running, or terminal states;
  • model, cwd, sandbox, approval policy;
  • serialized input mapping.
This binding lets restart recovery reason about a turn that was in progress when the gateway stopped. It also lets client operations such as steering or request response route to the native turn rather than guessing from the active UI state.

​
Continuation across execution segments

One Pioneer turn may span several native CLI execution segments. A segment can pause for a goal transition, recovery, provider/runtime wait, or execution budget without completing the Pioneer turn. The gateway keeps the continuation owner attached to the same Pioneer turn and native thread, so a resumed segment remains part of the original work and timeline. Subagent execution is tracked separately from the parent turn. A child runtime segment must not accidentally complete or claim the parent’s terminal state; the parent remains open until its own execution contract reaches a terminal outcome.

​
Permission mapping

CLI runtime turns still start with Pioneer’s TurnPermissionProfileSelection. The gateway resolves that into a normal TurnPermissionProfileSnapshot, stores it on the Pioneer turn, writes the profile-selected audit event, and then maps the Pioneer permission mode into the native runtime’s approval policy. This mapping lives in crates/gateway/src/cli_runtime/permissions.rs. Runtime-specific pending requests are still exposed through the CLI runtime request surface and resolved with cli_runtime/request/respond. Native tool permission requests from Pioneer’s ordinary tools runtime use the turn permission surface described in Permission System.

​
Event projection

Codex app-server notifications and Claude CLI events are decoded in crates/cli-agent-runtime and projected by the gateway. Projection turns runtime-native events into Pioneer-visible timeline rows, system events, pending request snapshots, approval rows, and terminal turn state. The event receiver used depends on the runtime adapter: Codex retains its typed native channel, while the shared channel carries provider-neutral events. Clients consume Pioneer projections, not Codex JSON. Runtime-specific raw payloads may be preserved for diagnostics, but UI state should use protocol DTOs. Desktop, mobile, and custom clients then share one surface even if the native runtime changes its event format.

​
Pending requests

CLI runtimes can block on requests that need user action. Pioneer models those as pending runtime requests and exposes request-opened/request-resolved notifications. Clients respond through cli_runtime/request/respond. The gateway forwards responses to the active runtime session with the native request id. Request resolution should be idempotent from the client perspective: once a request is resolved, clients should stop showing it as actionable even if older timeline rows are still visible.

​
Startup and recovery

scan_cli_runtime_turn_recovery scans persisted CLI runtime turn bindings with starting or running status. It then compares each binding with the current runtime catalog. Recovery outcomes are: Blocked recovery includes TurnBlockedResumeMetadata with a reason class, human message, requirements, and a turn.resume:<turn_id> resume command. This is how a restarted gateway can present an actionable recovery state instead of failing a turn silently. Codex recovery can receive a JSONL-RPC response or notification larger than the normal in-memory frame budget. The runtime first admits the frame to a bounded disk spool, then decodes only the fields needed for recovery and omits unbounded payloads from the projected event. Recovery frames can also request exclude_turns so a history snapshot does not replay turns that Pioneer already owns. The spool and decoder remain bounded by the runtime’s native event budget; an invalid or exhausted budget fails closed instead of handing an unbounded frame to the gateway.

​
Settings and model selection

Gateway settings expose CLI runtime instances under cli_runtimes. Each instance has an id, kind, display name, enabled flag, binary path, home path, and optional shadow home path. The gateway migrates the legacy singleton Codex setting into the multi-runtime shape when needed, then supports Codex and Claude instances through the same settings contract. Runtime network routing is also gateway-owned. A workspace can assign a validated HTTP or SOCKS proxy to a runtime. The gateway uses it when starting the native process and when probing runtime account or MCP readiness, while keeping proxy credentials out of client payloads and diagnostics. The shared client core presents CLI runtimes alongside API providers in model selection, but the runtime remains a distinct execution backend. A selected runtime model must lead to a CLI-backed turn, not to pioneer-provider.

​
Supported operations

The protocol currently exposes:
  • runtime list, refresh, status, and model listing;
  • login start/cancel and account/app notifications;
  • pending request response;
  • thread binding lookup;
  • thread compact and fork;
  • turn steering;
  • review start.
Support is capability-driven. A runtime can be listed while a specific operation is unavailable because the binary is missing, authentication is required, the version is unsupported, or the runtime kind does not implement that operation.

​
Failure modes

Developers should handle these as first-class states:
  • binary missing or configured path invalid;
  • runtime needs authentication;
  • app-server spawn failed;
  • runtime version unsupported;
  • session starts but event receivers fail;
  • native thread resume returns a different native thread id;
  • pending request response targets a stale request;
  • gateway restarts with persisted running turns;
  • model selector displays a runtime whose status is degraded.
Do not collapse these into one generic provider error. They imply different user fixes and different recovery behavior.

​
Developer rules

  • Keep CLI process/session lifecycle out of crates/provider.
  • Persist thread and turn bindings before depending on in-memory session state.
  • Treat native ids as foreign ids. Never derive Pioneer ids from them or vice versa.
  • Add protocol fields only when clients need them; keep raw runtime payloads diagnostic.
  • When adding a runtime kind, implement capability reporting honestly and keep unsupported operations explicit.
  • When changing request/approval flows, update gateway projection, pioneer-client, desktop, mobile generated schemas, and CLI Runtime API together.
  • When changing permission mapping, update crates/gateway/src/cli_runtime/permissions.rs, client permission-mode display, and this page together.