# `Pixir.Delegate.CLIContract`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/delegate/cli_contract.ex#L1)

Delegate CLI I/O Contract v1.

This module owns the machine-facing contract for `pixir delegate`. It is intentionally
small and testable: parse CLI flags, read a JSON spec, validate the contract, and emit
a stable dry-run result, attached runtime result, or structured error. Runtime
execution is delegated to `Pixir.Delegate.Runner` after the same parser accepts the
request.

The scaling rule is part of the contract: `delegate` should enter Pixir once and let
BEAM coordinate fanout. Caller-side polling loops and process-per-child shell fanout
are explicitly outside this surface.

Task object attachments are operator-supplied file paths that become ADR 0021
Session Resources in child Turns; the envelope records counts for dry-run planning
but never echoes attachment contents or paths.

## TODO(delegate-service-v1)

The `start`, `status`, `attach`, and `cancel` subcommands attempt daemon/IPC Delegate
service work when a manual workspace daemon is reachable. `start` requires that
resident owner so returned running work survives the short-lived CLI process; status,
attach, and cancel can fall back to durable Delegate snapshots. `attach` is
snapshot-first, and `attach --progress=stderr-jsonl --wait-horizon-ms N` requests a
daemon/owner follow stream rather than a caller-side polling loop. Keep the CLI shape
agent-useful:

  * `--json` responses should always expose `delegate_id`, parent `session_id`,
    diagnostics commands, and host-boundary metadata;
  * `attach --progress=stderr-jsonl` should emit bounded live/snapshot progress frames
    to stderr while stdout remains exactly one final JSON envelope;
  * long-running snapshots should distinguish accepted/running/incomplete from
    terminal success/failure;
  * `pixir delegate help` should become a supported alias for the delegate section of
    `pixir help`;
  * `command_ok` means the Delegate command itself was accepted and rendered a
    structured response; `work_complete` reports whether delegated work reached a
    clean terminal success, so consumers must not collapse them into one boolean;
  * service mode should still start exactly one Pixir entrypoint and let OTP own
    Subagent/Workflow fanout.

# `rendered`

```elixir
@type rendered() :: %{
  :exit_code => non_neg_integer(),
  :json? => boolean(),
  :payload => map(),
  :text => String.t(),
  optional(:after_render) => (-> :ok)
}
```

# `result`

```elixir
@type result() :: {:ok, rendered()} | {:error, rendered()}
```

# `contract_version`

```elixir
@spec contract_version() :: pos_integer()
```

Return the supported Delegate contract version.

# `run`

```elixir
@spec run(
  [String.t()],
  keyword()
) :: result()
```

Parse and execute Delegate CLI Contract v1 dry-run or attached runtime behavior.

---

*Consult [api-reference.md](api-reference.md) for complete listing*