Provider Guide

Prompt Runner delegates provider execution to agent_session_manager. This guide targets prompt_runner_sdk ~> 0.9.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.6-luna
• 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

Not every provider accepts every mode. Prompt Runner delegates the decision to ASM.Permission.normalize/2, so an unsupported pairing fails at config load with {:invalid_permission_mode, provider, mode} rather than at launch. On agent_session_manager ~> 0.12.1, Cursor and Antigravity reject auto, and Antigravity additionally rejects plan.

Normalized Common Options

ASM 0.11/0.12 promoted several formerly provider-local settings to normalized options that every provider schema accepts structurally and that are gated at runtime by the provider's common-feature manifest. Prompt Runner accepts them in any provider option map:

• allow_unknown_model — let a model newer than the shared registry through to the CLI instead of failing validation
• completion_only — a no-write, no-approval posture; supported by Claude and Codex, and rejected with a typed capability error by Amp, Antigravity, and Cursor
• output_schema — structured output, gated by the structured_output capability (Claude sends an inline JSON schema, Codex a schema file path)
• transport_headless_timeout_ms — the finite bound used to reap an orphaned transport, independent of stream idle timeout

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.

Claude accepts reasoning_effort as of agent_session_manager ~> 0.12.1; it resolves through the shared model registry the same way Codex's does. include_thinking remains the separate control for thinking output:

claude_opts:
  reasoning_effort: "high"
  include_thinking: true

Codex additionally exposes its app-server surface through codex_opts:

• app_server
• host_tools
• dynamic_tools
• reviewed_approval

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.6-luna"
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.