Command API

CliSubprocessCore.Command is the provider-aware one-shot command lane.

It combines:

• provider profile resolution
• normalized command construction
• generic execution_surface placement
• wrapped lower-lane failures with provider context

Public Entry Points

• CliSubprocessCore.Command.run/1
• CliSubprocessCore.Command.run/2
• CliSubprocessCore.Command.new/3

Provider-Aware Execution

{:ok, result} =
  CliSubprocessCore.Command.run(
    provider: :claude,
    prompt: "Summarize this repository"
  )

The return value is CliSubprocessCore.Command.RunResult.

Prebuilt Invocation Execution

invocation =
  CliSubprocessCore.Command.new(
    "sh",
    ["-c", "printf alpha"]
  )

{:ok, result} = CliSubprocessCore.Command.run(invocation, timeout: 5_000)

Placement

Use execution_surface to move the command onto a different substrate without exposing adapter modules:

{:ok, result} =
  CliSubprocessCore.Command.run(
    provider: :codex,
    prompt: "Review this diff",
    execution_surface: [
      surface_kind: :ssh_exec,
      transport_options: [
        destination: "buildbox.example",
        ssh_user: "deploy"
      ]
    ]
  )

When that surface resolves to :local_subprocess, the covered minimal lane emits ProcessExecutionIntent.v1 and runs through ExecutionPlane.Process.run/2. Other surfaces resolve through ExecutionPlane.Process.Transport.run/2 using the same execution_surface contract.

Governed Launch

Use :governed_authority only after a higher authority materializer has selected the launch inputs for one effect. The authority must provide authority, lease, and target refs plus a materialized command. Optional cwd, env, config root, auth root, and base URL also belong in that authority value.

{:ok, result} =
  CliSubprocessCore.Command.run(
    provider: :codex,
    prompt: "Review this diff",
    governed_authority: [
      authority_ref: "authority://cli/run",
      credential_lease_ref: "lease://codex/run",
      connector_instance_ref: "connector-instance://codex/run",
      connector_binding_ref: "connector-binding://codex/run",
      provider_account_ref: "provider-account://codex/run",
      native_auth_assertion_ref: "native-auth-assertion://codex/run",
      target_ref: "target://local/run",
      operation_policy_ref: "operation-policy://codex/run",
      command: "/materialized/bin/codex",
      cwd: "/workspace",
      env: %{"CODEX_HOME" => "/materialized/codex-home"},
      clear_env?: true,
      config_root: "/materialized/config",
      auth_root: "/materialized/auth",
      base_url: "https://authority.example/v1"
    ]
  )

Governed launch fails closed when the caller also supplies command, cwd, env, config-root, auth-root, base-URL, or model env override fields outside the authority value. Standalone calls remain unchanged when :governed_authority is absent.

Result Shape

The returned core-owned result contains:

• stdout
• stderr
• output
• stderr_mode
• exit

exit is the core-owned ProcessExit facade.

Error Shape

Command-lane failures are wrapped as CliSubprocessCore.Command.Error.

That wrapper preserves core-facing context such as the invocation or provider while carrying the underlying lower-lane failure from execution_plane. Transport failures surface through the core-owned TransportError facade.