Provider Guide

Prompt Runner delegates provider execution to agent_session_manager. This guide targets prompt_runner_sdk ~> 0.7.0.

Supported providers:

Prompt Runner always starts ASM sessions with lane: :core, so host applications do not need the provider SDK packages just to run Prompt Runner.

Default Profile Posture

mix prompt_runner init creates codex-default with:

• provider: codex
• model: gpt-5.4
• reasoning_effort: xhigh
• permission_mode: bypass
• cli_confirmation: require

Packets can use that profile directly or override any of those values locally.

mix prompt_runner init also creates simulated-default for zero-dependency recovery demos:

• provider: simulated
• model: simulated-demo
• permission_mode: bypass
• cli_confirmation: off
• recovery.resume_attempts: 2
• recovery.retry.base_delay_ms: 0
• recovery.retry.max_delay_ms: 0
• recovery.repair.enabled: true

Shared Provider Knobs

These packet or prompt keys are shared across providers:

• provider
• model
• allowed_tools
• permission_mode
• timeout
• system_prompt
• append_system_prompt
• max_turns

Provider support for system_prompt, append_system_prompt, and max_turns is validated before launch; unsupported controls fail configuration instead of being silently ignored.

Normalized shared permission modes:

• default
• auto
• bypass
• plan

Codex currently rejects shared permission_mode: auto, so use default, bypass, or plan for Codex packets.

Provider-Specific Option Maps

Prompt Runner also accepts provider-specific maps where the underlying ASM surface supports them:

• claude_opts
• codex_opts
• codex_thread_opts
• amp_opts
• cursor_opts
• antigravity_opts

Cursor and Antigravity accept only the option keys exposed by their current ASM core profiles. Unsupported keys fail during config validation instead of being forwarded as arbitrary CLI flags.

Gemini CLI support is retired. Use Antigravity for Google's coding-agent CLI. The gemini_ex package is a distinct model API SDK, not an alias for this provider surface.

Codex-only thread settings belong in codex_thread_opts, for example:

codex_thread_opts:
  reasoning_effort: "xhigh"
  additional_directories:
    - "./repos/beta"

Do not put raw unsupported CLI flags such as sandbox or ask_for_approval under codex_thread_opts.

Simulated Provider

The built-in simulated provider is for deterministic retry, repair, and resume demos. It does not use agent_session_manager or any external provider process.

It is package-local runtime support, not a service-mode simulation selector. Stack-level service-mode proofs should configure ASM and cli_subprocess_core runtime profiles so Prompt Runner still exercises the normal ASM core lane.

Codex CLI Confirmation

Codex packets can require runtime confirmation that the configured model and reasoning effort actually launched:

provider: "codex"
model: "gpt-5.4"
reasoning_effort: "xhigh"
cli_confirmation: "require"

Modes:

• off
• warn
• require

Prompt Runner accepts either hidden confirmation metadata or the actual launched command args as the proof source.

Working Directory Behavior

The provider cwd is the first targeted repo for the prompt. Additional repo paths are projected into Codex additional directories when they are part of the prompt target set.