CLI contracts

What Leg knows about each coding-agent CLI, where every fact came from, and which facts were observed live on the build machine versus read from --help or docs. Two contracts per CLI: the headless argv a pipeline leg spawns (§ per CLI below), and the interactive tap leg <agent> reads (§ Interactive taps). Evidence: fixtures/help/<cli>.txt (raw --help), fixtures/live/<cli>/ (one real tiny task per CLI, run through src/runner.mjs launch on 2026-09-11 UTC, the evening of 2026-09-10 locally; paths under the local home directory are replaced with ~), and the interactive checks run on 2026-09-11.

Every fact line ends with (source: …). observed-live means the build machine did it; docs-only means the CLI's own --help or documentation says so and Leg has not seen it happen.

Probe task (identical for every CLI, scripts/probe.mjs): "Create a file named hello-.txt in the current directory containing exactly the word hi. Then create the directory .leg if it is missing and write the file .leg/DONE containing the single line: done. Do nothing else. Do not ask questions."

The auth-source check: the build shell carried ANTHROPIC_API_KEY and OPENAI_API_KEY (injected by the shell profile). Every adapter's env() deletes them (src/env.mjs). No fixture contains "another auth source" (grep -ril "another auth source" fixtures/live is empty), claude's and agy's stderr are 0 bytes, and codex's is the one stdin notice. observed-live.

claude

• Version 2.1.268 (source: claude --version, fixtures/help/claude.version.txt).

• Binary: ~/.local/bin/claude.exe (native exe, 211 MB); Leg resolves it there first, else claude on PATH; LEG_CLAUDE_BIN overrides (source: ls ~/.local/bin/claude.exe; src/adapters/claude.mjs resolve()).

• Headless argv (exact, from fixtures/live/claude/cmd.txt): claude.exe -p --output-format json --permission-mode acceptEdits with the prompt on stdin (stdin: pipe). Optional: --max-turns N, --resume <session-id>, --model <alias|name>, --allowedTools a,b (source: claude --help lines for each flag; observed-live for the base argv).

• Output: ONE JSON object on stdout, printed only when the session ends (test/lessons.test.mjs json-only-at-end; observed-live: 20 s of silence then the object). Top-level keys observed: type:"result", subtype:"success", is_error, stop_reason:"end_turn", terminal_reason:"completed", api_error_status, session_id, num_turns, result (final text), permission_denials (array), usage{input_tokens,output_tokens,cache_read_input_tokens,…}, modelUsage, total_cost_usd, duration_ms (source: fixtures/live/claude/out.log). Leg reads session_id, result, stop_reason, subtype, is_error, terminal_reason, api_error_status, permission_denials.length.

• Model: with no --model, the account's default model answered (modelUsage names claude-fable-5-1 and claude-haiku-4-5). A chain entry should name model to control spend; Leg passes it through as --model (source: fixtures/live/claude/out.log modelUsage; claude --help --model).

• Exit codes:

  exit	meaning	source
  0	completed, JSON printed	observed-live, fixtures/live/claude/run.json
  non-zero	launch or fatal error; JSON may be absent	docs-only (claude --help does not enumerate codes; phase 4 records the fixture cases)

• Permission modes (--permission-mode choices in 2.1.268): acceptEdits, auto, bypassPermissions, manual, dontAsk, plan (source: claude --help). Leg: default acceptEdits; allowed acceptEdits, auto, plan, manual, dontAsk; forbidden bypassPermissions, --dangerously-skip-permissions, --allow-dangerously-skip-permissions. acceptEdits allowed the file write headless (observed-live). The Agent tool is never disallowed (test/lessons.test.mjs agent-tool-never-disallowed). --permission-prompts none exists ("anything that would prompt is denied automatically") and is not passed; headless -p has no host to answer prompts anyway (source: claude --help).

• Resume: --resume <session-id> (docs-only until phase 5 exercises it); --fork-session creates a new id on resume (source: claude --help).

• Child-process rules: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, CLAUDECODE, CLAUDE_CODE_*, CLAUDE_EFFORT, CLAUDE_PLUGIN_DATA deleted; CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0 set (source: src/env.mjs; the "another auth source" check above, observed-live).

• Limit signals: see § Limit signals (phase 4).

codex

• Version codex-cli 0.153.4 (source: codex --version).

• Binary: npm package @openai/codex whose bin/codex.js only spawns the platform package's native exe. Leg spawns that exe directly: ~/AppData/Roaming/npm/node_modules/@openai/codex/node_modules/@openai/codex-win32-x64/vendor/x86_64-pc-windows-msvc/bin/codex.exe (one process to kill); falls back to node <bin/codex.js> via resolveNpmCliEntry, then codex on PATH; LEG_CODEX_BIN overrides (source: bin/codex.js read 2026-09-10; fixtures/live/codex/cmd.txt).

• Headless argv (exact, from cmd.txt): codex.exe exec --json -s workspace-write -C <worktree> -c sandbox_workspace_write.network_access=false -o <run>/last.md "<prompt>". Prompt is the last positional argument; stdin is ignore: codex exec reads stdin whenever it is not a TTY and hangs on an open pipe ("Reading additional input from stdin..."; plan-time probe hung 170 s with a pipe, finished in 20 s with stdin closed; observed-live). -o writes the final agent message to a file (observed-live: fixtures/live/codex/last.md).

• Output: JSONL events on stdout (source: fixtures/live/codex/out.log): thread.started{thread_id}, turn.started, item.started/item.completed{item{type: agent_message|command_execution|error, text|command|message}}, turn.completed{usage{input_tokens,cached_input_tokens,output_tokens,reasoning_output_tokens}}. An item.type:"error" is a non-fatal notice (observed: "Skill descriptions were shortened…"). Leg reads thread_id as the session id, the last agent_message text, turn.completed as the stop reason, and the error messages.

• Exit codes:

  exit	meaning	source
  0	turn completed	observed-live, fixtures/live/codex/run.json
  (none)	hangs with an open stdin pipe until it is killed	observed at plan time; no artifact kept, the behaviour is pinned by test/lessons.test.mjs codex-stdin-ignored
  non-zero	launch/auth/fatal	docs-only

• Sandbox modes (-s): read-only, workspace-write, danger-full-access (source: codex exec --help). Leg: default workspace-write; allowed read-only, workspace-write; forbidden danger-full-access, --dangerously-bypass-approvals-and-sandbox, --dangerously-bypass-hook-trust, --approve-for-me (routes approvals through automatic review), --full-auto (not present in 0.153.4 exec --help; kept on the forbidden list). Blast radius is -C <worktree>; network off unless the chain entry sets network: true (PROTOCOL sandbox ladder). workspace-write allowed the write headless (observed-live).

• Resume: codex exec resume [SESSION_ID] [PROMPT] with --last for the newest (source: codex exec resume --help). Leg's adapter emits exec … resume <thread_id> <prompt>; docs-only until phase 5 exercises it.

• Limit signals: see § Limit signals (phase 4).

agy

• Version 1.2.0 (source: agy --version).

• Binary: ~/AppData/Local/agy/bin/agy.exe (native); LEG_AGY_BIN overrides (source: where agy; src/adapters/agy.mjs).

• Headless argv (exact, from cmd.txt): agy.exe -p "<working-directory preamble + prompt>" --output-format json --mode accept-edits --add-dir <worktree> --print-timeout 90m; stdin ignore.

  • agy does not work in the process cwd. Attempt 1 (no --add-dir) exited 0 and wrote hello-agy.txt under ~/.gemini/antigravity-cli/scratch/ (observed-live, fixtures/live/agy/attempt-1-scratch-workspace.out.log). Attempt 2 adds --add-dir <worktree> and prefixes the prompt with "Working directory: "; it wrote both files in the repo (observed-live).
  • --print-timeout defaults to 5m0s; Leg sets it from the kill timer in Go duration syntax so the supervisor decides what a runaway is (source: agy --help).

• Output: one JSON object: conversation_id, status:"SUCCESS", response, duration_seconds, num_turns, usage{input_tokens,output_tokens,thinking_tokens,cache_read_tokens,total_tokens} (observed-live, fixtures/live/agy/out.log). Leg reads conversation_id as the session id, response, status.

• Exit codes:

  exit	meaning	source
  0	status: SUCCESS	observed-live (both attempts; attempt 1 was a success in the wrong directory)
  non-zero	fatal/auth	docs-only

• Modes (--mode): accept-edits, plan (source: agy --help). Leg: default accept-edits; forbidden --dangerously-skip-permissions. accept-edits allowed the write headless (observed-live).

• Resume: --conversation <id> (by id) or --continue (most recent) (source: agy --help; docs-only until phase 5).

• Limit signals: see § Limit signals (phase 4).

grok

• Version grok 0.2.51 (f4f85a649) [stable] (source: grok --version).

• Binary: ~/.grok/bin/grok.exe (native; also an npm shim on PATH); LEG_GROK_BIN overrides (source: where grok).

• Headless argv (from cmd.txt): grok.exe -p "<prompt>" --output-format json --permission-mode acceptEdits; stdin ignore. --prompt-file <path> also exists (source: grok --help).

• Output: one JSON object {text, stopReason, sessionId, requestId, thought} (observed-live, fixtures/live/grok/out.log).

• Exit codes:

  exit	meaning	source
  0	printed JSON with stopReason:"Cancelled" and did no work: the CLI was not logged in, printed a device-code prompt on stderr (https://accounts.x.ai/oauth2/device?user_code=…, "Waiting for authorization...") and gave up after ~58 s	observed-live, fixtures/live/grok/err.log

  A zero exit with no DONE marker and no diff is exactly the no_progress class the completion contract exists for.

• Permission modes: default, acceptEdits, auto, dontAsk, bypassPermissions, plan (source: grok --help). Leg: default acceptEdits; forbidden bypassPermissions, --always-approve.

• Login: grok login (source: grok --help Commands).

• Verdict: not verified, no adapter registered. src/adapters/grok.mjs is built from --help and unit-tested for shape and forbidden flags, but stays out of src/adapters/index.mjs until grok login has been completed on the machine and node scripts/probe.mjs --adapter grok --repo <toy> passes.

Interactive taps

What leg claude|codex|agy reads while the real interactive CLI runs. Same tagging rule: observed-live 2026-09-11 means the build machine did it; docs-only means the CLI's own source or documentation says so and Leg has not seen it happen. Machine: Claude Code 2.1.268, codex-cli 0.153.4, agy 1.2.0.

Shared: the agent is spawned with stdio inherited and the user's arguments passed through (src/attach.mjs spawnSpec); the child environment is sanitizeEnv(process.env, { interactive: true }) plus the account's config-dir variable and LEG_SESSION (source: src/attach.mjs, src/env.mjs).

claude tap

• Attach: claude <args> --settings <LEG_HOME>/sessions/<id>/claude-settings.json (source: src/attach.mjs spawnSpec; src/taps/claude.mjs writeSettings). Hooks in a --settings file merge with the user's rather than replacing them; statusLine is the one key that replaces, so Leg runs the user's own command first (source: code.claude.com/docs/en/settings; src/taps/claude.mjs userStatusLine). observed-live 2026-09-11: a Leg session ran with every user hook still firing.
• Hooks written (source: src/taps/claude.mjs settingsFor): SessionStart, UserPromptSubmit, PostToolUse with matcher Edit|Write|MultiEdit|NotebookEdit, Stop, StopFailure, SessionEnd, each node <src>/hook.mjs claude-hook --session <id> with a 20 s timeout. observed-live 2026-09-11 (hook.log in the session directory).
• autoContinueAtUsageLimit: false in the same file, because Leg owns the hand-off (source: src/taps/claude.mjs settingsFor).
• Usage: GET https://api.anthropic.com/api/oauth/usage (LEG_CLAUDE_USAGE_URL overrides) with Authorization: Bearer <accessToken> from <CLAUDE_CONFIG_DIR>/.credentials.json key claudeAiOauth, and header anthropic-beta: oauth-2025-04-20; response fields five_hour and seven_day, each { utilization, resets_at }; polled every LEG_USAGE_POLL_MS ms, default 60000 (source: src/taps/claude-usage.mjs). observed-live 2026-09-11: real windows came back and were written to <LEG_HOME>/usage/claude--default.json; a seven_day window at 93 % raised the amber warning.
• The wall: StopFailure hook with error: rate_limit (source: https://code.claude.com/docs/en/hooks#stopfailure). observed-live 2026-09-11 : a real StopFailure with error: rate_limit (a 429 rate_limit_error) arrived at 07:46:37Z and is kept, scrubbed, as fixtures/live/claude/limit-rate_limit.json (src/live-capture.mjs). The path can also be run live with leg sessions simulate-limit (the same payload through src/hook.mjs, marked leg_simulated, never kept as evidence).
• Status line, not usable on 2.1.268: a custom statusLine command passed through --settings, and again through a project .claude/settings.local.json, was not run at all when it was tried; an echo command at both levels left the built-in status line in place while hooks from the same --settings file fired (no artifact kept; note in the src/taps/claude-usage.mjs header, 2026-09-11). Leg still writes the statusLine entry, which records the same rate_limits.five_hour / seven_day fields (https://code.claude.com/docs/en/statusline), so the endpoint poll becomes a fallback if a later build honours it.

codex tap

• Attach: nothing injected. codex <args> runs as it always does, and Leg finds the session's rollout file afterwards (source: src/attach.mjs spawnSpec). Reason: injecting a hook makes codex show its hooks-review prompt on every Leg session.
• Which file: <CODEX_HOME>/sessions/YYYY/MM/DD/rollout-*.jsonl, matched on session_meta.payload.cwd equal to the session's cwd with a birth time or mtime at or after the spawn time, five seconds of slack (source: src/taps/codex.mjs findRollout). observed-live 2026-09-11: the right rollout was found for a real hand-off. The file's mtime is not a content clock on Windows, six rollouts from that day had mtimes 7 s to 9 min behind their last line, so nothing depends on the two matching.
• Usage: read-only app-server account/rateLimits/read, polled every 60 seconds by the board and active attach. Leg maps windows by duration, including 300 minutes to 5h and 10080 minutes to 7d, rather than assuming primary or secondary names. It sends no model turn and does not hardcode a quota; only explicit backend availability clears a previous wall (sources: src/taps/codex.mjs, src/attach.mjs, src/server.mjs, src/usage.mjs).
• The wall: event_msg.task_complete.error with codex_error_info: "usage_limit_exceeded" and message "You've hit your usage limit … try again at <date>" (source: github.com/openai/codex codex-rs/protocol/src/error.rs UsageLimitReachedError). The event shape was read from local rollouts; the error itself is observed-live 2026-09-15 . A task_complete.error with codex_error_info: usage_limit_exceeded walled a codex leg once, but no scrubbed payload was kept, so fixtures/live/codex/limit-usage_limit_exceeded.json is still the slot for the first one.
• Transcript: response_item.message with role: user and content[].type: input_text for prompts; output_text and task_complete.last_agent_message for assistant text (source: src/taps/codex.mjs; observed-live 2026-09-11).
• Edited files: the *** Add File: / *** Update File: / *** Delete File: lines of an apply_patch payload (source: src/taps/codex.mjs; observed-live 2026-09-11).

agy tap

• Attach: agy <args> --log-file <LEG_HOME>/sessions/<id>/agy.log (source: src/attach.mjs spawnSpec). agy 1.2.0 is a closed Go binary with no hook surface.
• Usage: none. No percentage is written to any file agy owns; its own status line fetches a quota summary from the backend and stores nothing (source: src/taps/agy.mjs header).
• The wall: RESOURCE_EXHAUSTED, "it resets in %s", "out of quota", and "quota exhausted/exceeded" in the log, plus a relative reset parsed out of "resets in <n><s|m|h|d>" (source: strings present in agy.exe; src/taps/agy.mjs scanLog). docs-only : RESOURCE_EXHAUSTED (code 429): Individual quota reached … Resets in 71h19m42s. appeared in a session's agy.log at 08:02:42Z, scanLog read the relative reset, and the agent was walled. No payload was kept, the capture call in src/attach.mjs was added while that session's runner was already running, so fixtures/live/agy/limit-agy-resource-exhausted.json is still the slot for the next one.
• Prompts and conversation id: ~/.gemini/antigravity-cli/history.jsonl, one { display, timestamp, workspace, conversationId } per prompt (source: src/taps/agy.mjs historyFile; shape observed on disk, last written 2026-09-09, the 2026-09-11 agy leg produced no history entry).
• One account only: agy 1.2.0 has no config-directory override, so LAYOUT.agy.env is null and accounts add agy is refused (source: src/accounts.mjs).

Usage store and the chooser

• <LEG_HOME>/usage/<agent>--<account>.json: { five_hour: {pct, resets_at}, seven_day: {…}, limited_until, limited_reason, source, updated_at } (source: src/usage.mjs).
• Warning threshold WARN_PCT, default 85, from LEG_WARN_PCT; the warning is an amber card, an event, and one terminal bell (source: src/usage.mjs, src/attach.mjs).
• markLimited() takes the reset the CLI reported; failing that the soonest known window reset; failing that now + 5 h (source: src/usage.mjs DEFAULT_LIMIT_S).
• candidates() yields the other accounts of the same agent first, then the remaining agents in the order claude, codex, agy, wrapping, so every option is tried once. chooseNext() skips any option still walled and returns the walled ones sorted by reset (source: src/usage.mjs).

Session store

<LEG_HOME>/sessions/<id>/ holds session.json, events.jsonl, hook.log, and, per agent, claude-settings.json or agy.log; control.json appears only once the board has asked for a hand-off or an end (source: src/sessions.mjs header, src/attach.mjs). Statuses and event types are listed in VOCABULARY.md. Board routes: GET /api/sessions, GET /api/sessions/:id, POST /api/sessions/:id/handoff, POST /api/sessions/:id/end, DELETE /api/sessions/:id, with the list pushed as the SSE sessions event (source: src/server.mjs, src/board/sessions.js).

Limit signals

Recorded in fixtures/limits/<group>/<id>.json and classified by src/limits.mjs (classify()); the runner writes the outcome into run.json.outcome with the matched signal. Every limit row below is still docs-only: its text comes from the CLI's own documentation or source, cited in "produced by". Real limits from all three agents were seen on 2026-09-11, but only the claude payload was kept as evidence (fixtures/live/claude/limit-rate_limit.json); the codex and agy ones went to the session ledger, not to fixtures/limits/. The observed-live rows are the non-limit cases the probes actually hit and the detector must never mistake for a limit.

Outcome precedence (src/limits.mjs): spawn error → launch_failed; stderr "another auth source is set" or an auth fixture → auth_failed (wins over any limit text, even with exit 0); killed from the board → killed; kill timer → stalled; exit 0 + .leg/DONE → completed; adapter-specific then generic limit fixture → limit; launch fixture → launch_failed; exit 0 + changes, no DONE → incomplete; exit 0, nothing changed → no_progress; non-zero exit → failed. Every outcome except completed, auth_failed and killed asks the chain to hand off.

Generated by node scripts/limits-table.mjs from 21 fixtures (4 observed-live, 17 docs-only). Classification limit hands the card to the next agent as a usage limit; auth is a failed launch (never a limit); launch is a failed launch that the next agent may still try; budget is a turn or spend cap set by Leg itself; info must never classify as a limit.

Runner facts that apply to every CLI (observed-live in phase 2/3 tests)

• The supervisor is detached (detached: true, windowsHide: true) and survives the launcher; run.json moves launching → running → exited|killed|failed.
• Kill is taskkill /PID <pid> /T /F on Windows with one verify-retry (LEG_TIMERS_MS=notify,kill,verify, default 30 min / 90 min / 30 s).
• No adapter ever sets shell: true; every spawn is spawn(bin, argv) with a native exe or node <entry.js> (test/lessons.test.mjs no-shell-spawn).
• A chain entry naming a forbidden mode or flag makes argv() throw forbidden flag: …; the supervisor records the refusal and exits 13 without spawning (test/adapters.test.mjs, test/runner.test.mjs).

Leg is commercial, source-available software by Wes Sander. The source you run ships in the npm package. Questions or a refund: legcli@practicalsystems.io.