Codex, OpenCode, and Pi Runner Protocols

These three engines are non-interactive only — no control channel, no permission prompts. They extend JsonlSubprocessRunner and use its run_impl (ClaudeRunner replaces it; OpenCodeRunner only wraps it with a pre-spawn version check, #970).

A failed resumed run keeps the chat's saved session unless the error names the resume itself (_RESUME_FAILURE_RE in runner_bridge.py: Codex no rollout found, OpenCode Session not found, Pi No session found, …) — none of the three reports num_turns, so the Claude-style 0-turn rule can't apply (#952). A new "session not found" wording must be added there.

Quick comparison

Codex

Key files

CLI invocation

codex [extra_args…] [--profile P] [--model MODEL] [-c model_reasoning_effort=LEVEL] \
  exec --json --skip-git-repo-check --color=never \
  [--sandbox read-only] [resume <thread_id> | resume --last] -

• Prompt on stdin (trailing - means read stdin)
• Resume: resume <thread_id> - (resume --last - for /continue)
• Safe mode is genuinely read-only: --sandbox read-only (exec-level, so it outranks a root-level sandbox flag), only in safe permission mode and before resume (codex exec resume has no --sandbox); no --ask-for-approval — codex exec forces approval never itself (#830)
• extra_args sit at the root (before exec) and are checked by runners/extra_args_guard.py: bypass/sandbox-escape flags (--yolo, --sandbox danger-full-access, -c …danger…, -C/--cd, …) disable the engine at load (#209)
• --skip-git-repo-check --color=never for clean output

JSONL events

Item types

Final answer selection

Multiple agent_message items may appear. Selection:

1. Prefer item with phase == "final_answer"
2. Fall back to last unnamed agent_message
3. Used in CompletedEvent.answer

Config keys

[codex]
profile = "Codex"        # Codex profile name
extra_args = []           # additional CLI flags

OpenCode

Key files

CLI invocation

opencode run --format json [--session SESSION_ID] [--model MODEL] -- <prompt>

• Prompt as positional arg after --
• Resume: --session ses_XXX
• Session IDs: ses_ prefix + 20+ chars
• Supported CLI: OpenCode 1.x (npm opencode-ai) only (#970). run_impl probes opencode --version off the event loop (cached per binary path + mtime; failed probes aren't cached) and refuses 2.x (@opencode/cli, which runs prompts on a shared background service outside Untether's process control) with one completed_error carrying PRESPAWN_BLOCKED_KEY, so nothing spawns and the saved session is kept. An unparsable version fails open (opencode.version.unknown). Tests stub the probe via an autouse fixture in tests/conftest.py
• run auto-rejects ask permissions (never auto-approves; only --dangerously-skip-permissions, which Untether doesn't pass) and denies question/plan_enter/plan_exit. OpenCode does auto-compact, but run --format json doesn't report it (#969)

JSONL events

Tool mapping

Usage

Each step_finish's cost and tokens accumulate into OpenCodeStreamState; _build_usage() puts them on CompletedEvent.usage (total_cost_usd + usage{input,output,reasoning,cache_*}_tokens). The bridge accumulates them per session for /usage and /export (#417).

Config keys

[opencode]
model = "anthropic/claude-sonnet-5-5"   # must be OpenCode's provider/model form; bare names fail

Pi

Key files

CLI invocation

pi --print --mode json [--session SESSION_PATH] \
  [--provider PROVIDER] [--model MODEL] <prompt>

• Prompt as positional arg (prefixed with space if starts with -)
• Resume: --session <token> (short ID or full path)
• Minimum version: 0.45.1
• Environment: NO_COLOR=1, CI=1 (set by runner)

JSONL events

Session ID promotion

Pi has a unique resume mechanism:

1. For new runs, Untether generates a session .jsonl file path
2. If a session header arrives with a UUID, the resume token is promoted to the 8-char short ID
3. allow_id_promotion flag ensures this only happens once
4. This gives a user-friendly resume token instead of a long path

Session path format: ~/.pi/agent/sessions/--<sanitized-cwd>--/<date>-<uuid>.jsonl

Tool mapping

Error detection

• stopReason in message_end: "error" or "aborted" -> ok=False
• No agent_end received -> CompletedEvent(ok=False, error="stream ended...")

Config keys

[pi]
provider = "anthropic"   # or "openai", "google", etc.
model = "claude-sonnet-4-5-20250929"
extra_args = []

Adding a new engine

To add a new engine runner:

1. Create src/untether/runners/myengine.py
2. Define schemas in src/untether/schemas/myengine.py
3. Implement MyEngineRunner(JsonlSubprocessRunner) with required template methods
4. Export BACKEND = EngineBackend(id="myengine", build_runner=..., cli_cmd="myengine")
5. Register in pyproject.toml entry points:

   myengine = "untether.runners.myengine:BACKEND"

6. Add reference docs in docs/reference/runners/myengine/
7. Add tests mirroring existing tests/test_*_runner.py patterns