machinemode.io
For builders of agent systems · Updated 2026-10-23

For agents

An agent‑operable CLI gives an AI agent guarantees it can check before it acts, in place of behavior it has to infer after the fact.

The A in AOI is the part everything else is for. Tool authors get a contract that makes a CLI readable by agents, and the spec and the conformance badge are written for them.

This page is about what that contract changes for the agent on the other side, the one audience that can’t compensate for a bad interface by reading between the lines. When the interface isn’t legible, the agent ends up scraping output and retrying blind while it burns context.

Below are thirty‑two concrete things that change when the tool on the other end implements AOI‑CLI and its recommended profile, grouped by what they buy the agent.

§ 01

Comprehension and predictability

Stops being a parsing problem

  1. One vocabulary across every conforming tool.
    The agent learns the framework events once: aoi:meta, aoi:summary, aoi:error, aoi:warning, aoi:check, aoi:plan and aoi:heartbeat, plus recommended domain shapes such as hit and match. Every conforming tool uses the same framework events, so the agent needs far less per‑tool prompting.
  2. Discovery before invocation.
    tool schema and tool capabilities tell the agent what the tool can do, which events it emits and which standard options each command supports, all without credentials, network access or a real call. The agent doesn’t have to run --help and parse an ASCII table.
  3. Typed events with a discriminator.
    The agent dispatches on event.type, never on a regex against prose. Whether a line is a result, a warning or a status update is a typed answer rather than a guess.
  4. Versioned schemas.
    schema_version in aoi:meta tells the agent which event shape to expect. When a tool updates, the agent knows whether its parser still applies or whether it has to opt into a new major version explicitly, so nothing breaks silently.
§ 02

Context‑window economics

Specific to language models

  1. Bounded results with cursors.
    --limit 50 returns at most 50 results, so an accidental list that would have dumped a hundred thousand rows can’t blow the agent’s context budget.
  2. Compact, line‑delimited JSON.
    Machine mode forbids banners, ASCII art, color codes and progress bars, so none of them eat tokens. The agent’s context goes to data.
  3. Streaming arrival.
    The agent can start reasoning over the first result while the rest are still arriving. It reaches a useful token sooner, and long operations stay observable.
  4. Selective consumption.
    The agent can run jq -c 'select(.type=="hit")' over the stream before reading it and pay tokens only for the event types it cares about.
§ 03

Verification

Stops being forensic work

  1. A terminal aoi:summary with ok:true is the success signal.
    The agent stops trusting exit code 0 alone, which can mislead after a buffered write or a partial run. “The process exited” and “the work finished” become two facts the agent can tell apart.
  2. EOF without a summary means the tool crashed.
    A consumer can detect a crashed tool even when its language runtime swallowed the exit code, and the check works the same in any language on any platform. With aoi.seq and event_count, the agent can also tell when a harness dropped lines from the middle of the stream.
  3. Structured errors with category and retryable.
    The agent’s retry policy works across tools. category:"rate_limited" with retryable:true means the same thing in every conforming tool, and retry_after_ms says how long to wait. The agent branches on retryable to decide whether to retry and on category to route the error, with no per‑tool exception parsing and no scraping messages for hints.
  4. Audit records on every mutation.
    Mutating commands report stable IDs, paths or URLs for what they created, updated or deleted. The agent confirms the action took effect and hands the IDs to memory or a downstream audit instead of assuming.
  5. doctor for pre‑flight readiness.
    Before real work, the agent can ask whether its credentials are valid and the endpoint is reachable, and get structured aoi:check events back. It doesn’t need a destructive call to find out.
§ 04

Safety the agent can steer

More than prompt engineering

  1. Read‑only by default.
    An agent working under uncertainty gets non‑destructive behavior unless it asks for more, because mutation requires explicit intent.
  2. --dry-run returns typed aoi:plan events.
    The agent, or whoever supervises it, can preview what an action would do in machine‑readable form before committing. The model reasons over a plan instead of trusting itself blindly.
  3. --confirm and --confirm-count N.
    Destructive operations refuse to run without explicit confirmation, and bulk ones can require the count the agent expected. A wrong invocation produces a refusal instead of a disaster.
  4. --idempotency-key.
    Writes become safe to retry. The agent can re‑issue a failed create without doubling the effect, because the tool recognizes the key and returns the earlier result.
  5. Secret redaction in meta.
    A conforming tool shouldn’t echo raw arguments by default and must redact secrets when it does. args_redacted:true confirms the agent’s API key didn’t land in the output stream, so the agent doesn’t have to scrub logs before keeping them.
§ 05

Composition

Sources, transformers, sinks

  1. Three roles, one contract.
    Every conforming tool plays one of three pipeline roles. A source emits JSONL; a transformer reads JSONL and emits JSONL; a sink reads JSONL, performs side effects and reports what it did. The agent composes them with ordinary shell pipes, and the envelope is the same in all three.
  2. JSONL in, JSONL out, by construction.
    Nobody regexes column 3 of tool A’s table to feed tool B, because the interface holds across the chain. Shell tools that already handle structured streams, like jq and tee, work unchanged.
  3. Pipefail‑safe chains.
    With set -o pipefail and a check on the final summary, the agent can compose five tools and trust the result. An upstream failure shows up in the exit status and in the last tool’s summary, whose caused_by field carries the upstream error’s retry details.
  4. Domain and control events stay apart.
    A downstream tool reads upstream aoi:meta and aoi:summary for the outcome but never forwards them, and it treats hit and match as data. The aoi: prefix makes the split visible on the wire, so nobody has to configure it.
  5. Heartbeats tell quiet from dead.
    On unbounded streams a tool can emit aoi:heartbeat, which lets the agent’s supervisor decide whether to keep waiting or to kill and retry. Liveness becomes part of the contract rather than a TCP keepalive hack.
§ 06

Planning and reasoning

At agent altitude

  1. A queryable capabilities manifest.
    The agent asks which commands are destructive, which are bounded, and which support cursors, dry runs or idempotency keys, and it gets a typed answer. Reasoning happens at plan time instead of by trial and error.
  2. Cost visible at plan time.
    Whether a command is read‑only or mutating, bounded or not, idempotent or not is declared and inspectable before any call. The model can pick the lowest‑risk path that meets the goal.
  3. Fewer hallucinated flags.
    The agent doesn’t have to guess whether a command supports --dry-run; it reads capabilities and gets the truth. A wrong flag fails loudly with category:"usage" instead of silently doing the wrong thing.
  4. Reproducibility.
    The same arguments, tool_version and schema_version produce the same event shape, so the agent can cache, replay and diff runs to detect drift.
§ 07

Operational control

The unglamorous primitives

  1. Structured cancellation.
    When a long operation is aborted, the tool emits an aoi:summary with ok:false and reason:"cancelled" if it’s safe to. The counts on that summary tell the agent how much got done before it stopped, not just that it stopped.
  2. One pagination model.
    Tools that page share the same --cursor pattern. The agent learns it once and applies it everywhere instead of memorizing each tool’s pagination.
  3. Explicit truncation.
    aoi:summary.truncated:true with aoi:summary.next_cursor tells the agent there’s more, so it never has to parse a trailing “...” or “and 47 more results.”
§ 08

Environment and auth

The agent doesn’t manage OAuth

  1. Auth happens beneath the call.
    The agent invokes a tool and the user’s existing credentials, such as the keychain, the AWS credential chain, kubeconfig, the ssh agent or a corporate SSO session, are already wired in. The agent never runs an OAuth flow or refreshes a token. When auth does fail, the tool says so with the authn or authz category, and doctor can check it ahead of time. Why auth is deliberately out of scope
  2. A clean environment per invocation.
    Each batch‑mode call is a fresh process, so state doesn’t leak between operations. Session mode, which is still in design (see Direction), would give the agent the opposite when it wants it: state that persists across requests.
§ Closing

From inference to contract

Every item above is something an agent can rely on at plan time instead of discovering it at run time, and that shift is what makes autonomous tool use tractable.

The work for tool authors is small. The required core is Part I of the AOI‑CLI specification, which a maintainer should be able to implement in an afternoon, and § 18 defines the aoi-lint checks for it. Adopt has minimal implementations in Python, TypeScript, Go, Rust and shell.

For wire‑level demonstrations, see Examples. Direction covers session mode and profiles for other surfaces.

Adopt in an afternoonRead the spec →