Cross-agent CLI for other agents to use; currently supports claude, codex, cursor agent, copilot, and grok.

agent_cli

#!/usr/bin/env bash
#
# agent_cli — one front door for cross-agent work: read-only review/research
# OR write-capable edit/refactor.
#
# Generalizes agent_review (read-only only) by adding an optional trailing
# `mode` arg. `review` (default) keeps every agent read-only — identical to
# agent_review. `edit` flips each CLI into its write-capable mode so a worker
# can apply targeted refactors/edits. Append `edit` to allow writes.
#
# Session continuity is explicit: the first arg is either `new` (fresh
# session) or a session ID from a previous run (resume with full context).
# There is no implicit "continue last session" — you always say which.
#
# Wraps the five CLI agents (copilot, codex, claude, cursor, grok) behind a single
# signature so one doc describes one wrapper instead of five. This script owns the
# per-CLI transport quirks (read-only vs write mode, stdin redirect, effort
# flag mapping, default models). When a CLI's API changes, fix it HERE.
#
# Usage:
#   Tools/agent_cli <session ID | new> <agent> <model|default> <effort|default> "<prompt>" [mode]
#
#   <session> `new` starts a fresh session; a session ID resumes that session.
#             Every run prints `session: <id>` on stderr for later resumption.
#             IDs are per-agent (claude/copilot/grok UUIDs, codex thread ids,
#             cursor chat ids) — resume with the same agent that minted the id.
#   <agent>   copilot | codex | claude | cursor | grok
#   <model>   a model id for that agent, or `default` (see DEFAULT_MODEL_* below)
#   <effort>  low | medium | high | none | default   (mapped per agent)
#   <prompt>  the prompt; pass `-` to read it from stdin
#   [mode]    review (default, read-only) | edit (write-capable)
#
# Examples:
#   Tools/agent_cli new copilot default high "Review the uncommitted diff."
#   Tools/agent_cli new codex gpt-5.6-sol high "Review Scripts/TreeRegion.gd for perf."
#   Tools/agent_cli new claude default default "Refactor Scripts/Foo.gd: extract helper." edit
#   Tools/agent_cli 0198c2… claude default default "Now run the tests you suggested." edit
#   git diff main...HEAD | Tools/agent_cli new claude default high -
#
# review mode runs READ-ONLY (no edits); edit mode allows writes within the
# repo. The repo is the current git toplevel (override with REPO=/path).
# List models with: Tools/agent_cli <agent> --list-models

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# shellcheck source=/dev/null
source "$SCRIPT_DIR/colors.sh"

REPO="${REPO:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"

# Per-agent defaults. Selection rationale lives in AI_MODEL_COMPARISON.md.
DEFAULT_MODEL_copilot="auto"             # Auto grants more token usage than pinning a model. Free tokens.
DEFAULT_MODEL_codex="gpt-5.6-terra"
DEFAULT_MODEL_claude="claude-opus-4-8"
DEFAULT_MODEL_cursor="composer-2.5"
DEFAULT_MODEL_grok="grok-4.5"

DEFAULT_EFFORT_copilot="low"     # Informational for auto, which rejects explicit effort.
DEFAULT_EFFORT_codex="high"      # Benchmark-backed routine review/final-edit setting.
DEFAULT_EFFORT_claude="medium"   # Normal work; use claude-fable-5 low for very hard tasks.
DEFAULT_EFFORT_cursor="low"      # Informational; Cursor effort is encoded in model ids.
DEFAULT_EFFORT_grok="high"       # Unbenchmarked secondary perspective; use high effort.

usage() {
  cat <<'EOF'

Usage: Tools/agent_cli <session ID | new> <agent> <model|default> <effort|default> "<prompt>" [mode]

  session  `new` for a fresh session, or a session ID to resume (printed as
           `session: <id>` on stderr by every run; IDs are per-agent)
  agent    copilot | codex | claude | cursor | grok
  model    a model id, or `default`
  effort   low | medium | high | none | default
  prompt   the prompt; `-` reads from stdin
  mode     review (default, read-only) | edit (write-capable)

review mode runs read-only; edit mode allows writes within the repo.

Auth/health checks:
  Tools/agent_cli <agent> --check-auth    # Test auth for one agent
  Tools/agent_cli --doctor                # Test all five agents

List models: Tools/agent_cli <agent> --list-models

EOF
}

die() { echo -e "${RED}agent_cli: $*${NC}" >&2; exit 1; }
note() { echo -e "${DKGRAY}» $*${NC}" >&2; }

REVIEW_COMPLETION_CONTRACT='Review completion contract:
- After all tool use, always return a final answer on stdout. Do not stop after a preamble, progress update, or tool result.
- State the findings with severity and file/line references. If there are no findings, state PASS explicitly.
- Do not use /tmp or another file as the only report channel; the caller only receives your final stdout.
- End with exactly one of these lines:
REVIEW_COMPLETE: PASS
REVIEW_COMPLETE: FINDINGS'

finish_result() {
  local result="$1" status="$2"
  printf '%s\n' "$result"
  [ "$status" -eq 0 ] || exit "$status"
  if [ "$MODE" = "review" ] && [ "${AGENT_CLI_SKIP_REVIEW_COMPLETION:-0}" != "1" ]; then
    local last_line
    last_line="$(awk 'NF { line = $0 } END { print line }' <<<"$result")"
    case "$last_line" in
      "REVIEW_COMPLETE: PASS"|"REVIEW_COMPLETE: FINDINGS") ;;
      *)
        echo "agent_cli: reviewer exited 0 without the required final verdict; review is incomplete, not PASS" >&2
        exit 2
        ;;
    esac
  fi
}

[ $# -ge 1 ] || { usage >&2; exit 1; }

# Flag forms keep their original shapes (<agent> --list-models,
# <agent> --check-auth, --doctor); the run form is session-first.
if [ "${2:-}" = "--list-models" ] || [ "${2:-}" = "models" ] || [ "${2:-}" = "--check-auth" ] \
   || [ "$1" = "--doctor" ] || [ "$1" = "doctor" ]; then
  AGENT="$1"; shift
else
  SESSION="$1"; shift
  case "$SESSION" in
    copilot|codex|claude|cursor|grok)
      die "first arg is now <session ID | new> (got agent '$SESSION'); use \`new\` for a fresh session" ;;
    "") die "empty session arg (expected a session ID or \`new\`)" ;;
  esac
  [ $# -ge 1 ] || { usage >&2; die "need <agent>"; }
  AGENT="$1"; shift
fi

# --list-models shortcut
if [ "${1:-}" = "--list-models" ] || [ "${1:-}" = "models" ]; then
  case "$AGENT" in
    cursor) exec cursor-agent --list-models ;;
    codex)  exec codex --help ;;  # codex enumerates via -m; no list subcommand
    copilot) die "copilot has no headless model list; run \`copilot\` then /model. Known good: gpt-5.4, claude-sonnet-4-6, auto" ;;
    claude) die "claude model ids: claude-fable-5, claude-opus-4-8, claude-sonnet-5, claude-haiku-4-5-20251001" ;;
    grok)   exec grok models ;;
    *) die "unknown agent '$AGENT'" ;;
  esac
fi

# Auth check functions
check_agent_auth() {
  local agent="$1"
  local model; v="DEFAULT_MODEL_$agent"; model="${!v:-}"
  [ -z "$model" ] && die "unknown agent '$agent'"

  note "checking $agent auth (model: $model)..."
  local out exit_code=0
  out="$(AGENT_CLI_SKIP_REVIEW_COMPLETION=1 "$0" new "$agent" "$model" none "Reply with exactly: OK" review 2>&1)" || exit_code=$?

  if grep -qi "OK" <<<"$out"; then
    echo "${GREEN}✓${NC} $agent: authenticated" >&2
    return 0
  elif grep -qi "exceeded your monthly quota\|quota exceeded\|rate limit" <<<"$out"; then
    echo "${RED}✗${NC} $agent: authenticated but out of quota / rate limited" >&2
    echo "  Wait for the quota window to reset or use another agent" >&2
    return 1
  else
    echo "${RED}✗${NC} $agent: authentication failed or no response" >&2
    echo "  Run the $agent CLI interactively to re-authenticate" >&2
    [ "$exit_code" -ne 0 ] && echo "  Exit code: $exit_code" >&2
    return 1
  fi
}

# --check-auth shortcut
if [ "${1:-}" = "--check-auth" ]; then
  check_agent_auth "$AGENT" || exit 1
  exit 0
fi

# --doctor checks all agents
if [ "$AGENT" = "--doctor" ] || [ "$AGENT" = "doctor" ]; then
  failures=0
  for ag in copilot codex claude cursor grok; do
    check_agent_auth "$ag" || failures=$((failures + 1))
  done
  [ $failures -eq 0 ] && { echo "${GREEN}All agents authenticated${NC}" >&2; exit 0; }
  echo "${RED}$failures agent(s) failed authentication${NC}" >&2
  exit 1
fi

[ $# -ge 3 ] || { usage >&2; die "need <model> <effort> <prompt>"; }
MODEL="$1"; EFFORT="$2"; PROMPT="$3"; MODE="${4:-review}"

[ "$MODEL" = "default" ] && { v="DEFAULT_MODEL_$AGENT"; MODEL="${!v:-}"; [ -n "$MODEL" ] || die "unknown agent '$AGENT'"; }
[ "$EFFORT" = "default" ] && { v="DEFAULT_EFFORT_$AGENT"; EFFORT="${!v:-}"; [ -n "$EFFORT" ] || die "no default effort for '$AGENT'"; }
[ "$PROMPT" = "-" ] && PROMPT="$(cat)"
[ -n "$PROMPT" ] || die "empty prompt"

case "$MODE" in
  review|edit) ;;
  *) die "unknown mode '$MODE' (expected review | edit)" ;;
esac

if [ "$MODE" = "review" ] && [ "${AGENT_CLI_SKIP_REVIEW_COMPLETION:-0}" != "1" ]; then
  PROMPT="$(printf '%s\n\n%s' "$PROMPT" "$REVIEW_COMPLETION_CONTRACT")"
fi

case "$AGENT" in
  copilot)
    command -v copilot >/dev/null 2>&1 || die "copilot CLI not found"
    # review: --plan = read-only/planning (no edits). edit: drop --plan so
    # the agent can write. --allow-all-tools suppresses permission prompts on
    # tools (required non-interactive). Some models (auto, *-4.5) reject
    # --effort, so retry without it on error.
    eff=()
    [ "$EFFORT" != "none" ] && [ "$MODEL" != "auto" ] && eff=(--effort "$EFFORT")
    plan=(--plan)
    [ "$MODE" = "edit" ] && plan=()
    # --session-id both names a new session and resumes an existing one.
    sess_id="$SESSION"
    [ "$sess_id" = "new" ] && sess_id="$(uuidgen | tr '[:upper:]' '[:lower:]')"
    note "copilot --model $MODEL ${eff[*]:-} ${plan[*]:-} ($MODE)"
    note "session: $sess_id"
    status=0
    out="$(copilot -p "$PROMPT" --model "$MODEL" --session-id "$sess_id" ${eff[@]+"${eff[@]}"} ${plan[@]+"${plan[@]}"} --allow-all-tools --no-color -C "$REPO" </dev/null 2>&1)" || status=$?
    if grep -q "does not support reasoning effort" <<<"$out"; then
      note "model rejects --effort; retrying without it"
      status=0
      out="$(copilot -p "$PROMPT" --model "$MODEL" --session-id "$sess_id" ${plan[@]+"${plan[@]}"} --allow-all-tools --no-color -C "$REPO" </dev/null 2>&1)" || status=$?
    fi
    finish_result "$out" "$status"
    ;;

  codex)
    command -v codex >/dev/null 2>&1 || die "codex CLI not found"
    sandbox="read-only"
    [ "$MODE" = "edit" ] && sandbox="workspace-write"
    status=0
    if [ "$SESSION" = "new" ]; then
      note "codex exec -m $MODEL model_reasoning_effort=$EFFORT -s $sandbox ($MODE)"
      raw="$(codex exec --strict-config --json -m "$MODEL" -c model_reasoning_effort="$EFFORT" \
        -s "$sandbox" -C "$REPO" "$PROMPT" </dev/null)" || status=$?
    else
      # `codex exec resume` has no -s/-C flags; sandbox goes through config
      # and the working directory through a subshell cd.
      note "codex exec resume $SESSION -m $MODEL model_reasoning_effort=$EFFORT sandbox_mode=$sandbox ($MODE)"
      raw="$( (cd "$REPO" && codex exec resume --strict-config --json -m "$MODEL" \
        -c model_reasoning_effort="$EFFORT" -c sandbox_mode="$sandbox" \
        "$SESSION" "$PROMPT") </dev/null)" || status=$?
    fi
    result="$(printf '%s\n' "$raw" | python3 -c '
import sys, json
message = ""
thread_id = ""
for line in sys.stdin:
    line = line.strip()
    if not line: continue
    try: obj = json.loads(line)
    except Exception: continue
    if obj.get("type") == "thread.started" and obj.get("thread_id"):
        thread_id = obj["thread_id"]
    item = obj.get("item", {})
    if obj.get("type") == "item.completed" and item.get("type") == "agent_message" and item.get("text"):
        message = item["text"]
if thread_id:
    print(f"session: {thread_id}", file=sys.stderr)
print(message if message else "(codex returned no result text)")')"
    finish_result "$result" "$status"
    ;;

  claude)
    command -v claude >/dev/null 2>&1 || die "claude CLI not found"
    # Headless Claude can silently stall when permission prompts cannot be
    # displayed. Use full-access mode in this trusted repo; review-only behavior
    # is enforced by the prompt contract, not by Claude's plan-mode permissions.
    # Sessions persist so they can be resumed by ID; the explicit --session-id
    # still prevents the desktop-managed binary from silently resuming an
    # unrelated prior task.
    if [ "$SESSION" = "new" ]; then
      claude_session_id="$(uuidgen | tr '[:upper:]' '[:lower:]')"
      sess=(--session-id "$claude_session_id")
    else
      claude_session_id="$SESSION"
      sess=(--resume "$SESSION")
    fi
    cprompt="$PROMPT"
    [ "$MODE" = "review" ] && cprompt="$(printf 'Review-only: do not edit files.\n\n%s' "$PROMPT")"
    note "claude -p --model $MODEL --effort $EFFORT --permission-mode bypassPermissions ($MODE)"
    note "session: $claude_session_id"
    status=0
    raw="$(cd "$REPO" && printf '%s' "$cprompt" | claude -p \
        --model "$MODEL" --effort "$EFFORT" \
        "${sess[@]}" \
        --permission-mode bypassPermissions --output-format json)" || status=$?
    result="$(printf '%s\n' "$raw" | python3 -c '
import json, sys
raw = sys.stdin.read()
try:
    obj = json.loads(raw)
    print(obj.get("result") or "(claude returned no result text)")
except Exception:
    print(raw.strip() or "(claude returned no result text)")')"
    finish_result "$result" "$status"
    ;;

  cursor)
    command -v cursor-agent >/dev/null 2>&1 || die "cursor-agent CLI not found"
    # Cursor bakes effort into model ids (e.g. gpt-5.5-high); EFFORT is
    # informational only. review: --mode plan blocks edits. edit: cursor's
    # write/agent mode is the default, so we OMIT --mode (its only --mode
    # choices are plan|ask; there is no `agent` value). Headless -p cannot
    # show tool-permission prompts, so --force --trust are required or it
    # hangs and exits empty. stream-json reliably emits the final result text
    # (text format drops it for agentic runs), so we stream the final result.
    cursor_review_mode="${AGENT_CLI_CURSOR_REVIEW_MODE:-plan}"
    case "$cursor_review_mode" in plan|ask) ;; *) die "AGENT_CLI_CURSOR_REVIEW_MODE must be plan or ask" ;; esac
    cmode=(--mode "$cursor_review_mode"); cprompt="Review-only: do not edit any files. $PROMPT"
    [ "$MODE" = "edit" ] && { cmode=(); cprompt="$PROMPT"; }
    # A new run pre-mints a chat id via create-chat so the id is known before
    # dispatch; both branches then attach with --resume. Re-prefixing
    # `Review-only:` on a resumed session makes Composer flake (empty result
    # or degenerate repetition), so the prefix is first-message-only; --mode
    # plan remains the hard read-only gate on every review call.
    cursor_chat_id="$SESSION"
    if [ "$cursor_chat_id" = "new" ]; then
      cursor_chat_id="$(cursor-agent create-chat)" || die "cursor-agent create-chat failed"
      [ -n "$cursor_chat_id" ] || die "cursor-agent create-chat returned no chat id"
    else
      cprompt="$PROMPT"
    fi
    note "cursor-agent -p --output-format stream-json ${cmode[*]:-} --force --trust --model $MODEL ($MODE; effort '$EFFORT' n/a)"
    note "session: $cursor_chat_id"
    status=0
    raw="$(cursor-agent -p --output-format stream-json ${cmode[@]+"${cmode[@]}"} --force --trust \
      --workspace "$REPO" --model "$MODEL" --resume "$cursor_chat_id" \
      "$cprompt")" || status=$?
    result="$(printf '%s\n' "$raw" | python3 -c '
import sys, json
assistant = ""
result = ""
for line in sys.stdin:
    line = line.strip()
    if not line: continue
    try: obj = json.loads(line)
    except Exception: continue
    if obj.get("type") == "assistant":
        content = obj.get("message", {}).get("content", [])
        text = "".join(item.get("text", "") for item in content if item.get("type") == "text")
        if text.strip(): assistant = text
    elif obj.get("type") == "result" and obj.get("result"):
        result = obj["result"]
print(assistant if assistant else result if result else "(cursor returned no result text)")')"
    finish_result "$result" "$status"
    ;;

  grok)
    command -v grok >/dev/null 2>&1 || die "grok CLI not found"
    # Both modes run --permission-mode bypassPermissions: headless grok
    # cancels the session (stopReason "Cancelled", answer lost) when plan or
    # dontAsk mode hits a tool approval, and --sandbox read-only does not
    # actually block writes on this host. Review read-only is therefore
    # prompt-level (Review-only prefix) like claude, plus --disallowed-tools
    # to strip the direct edit tools; Bash remains available for searching.
    # Effort maps to --reasoning-effort (high|medium|low); omit for `none`.
    eff=()
    [ "$EFFORT" != "none" ] && eff=(--reasoning-effort "$EFFORT")
    gate=(); gprompt="$PROMPT"
    if [ "$MODE" = "review" ]; then
      gate=(--disallowed-tools "Write,Edit,MultiEdit,NotebookEdit")
      gprompt="Review-only: do not edit any files. $PROMPT"
    fi
    if [ "$SESSION" = "new" ]; then
      grok_session_id="$(uuidgen | tr '[:upper:]' '[:lower:]')"
      sess=(--session-id "$grok_session_id")
    else
      grok_session_id="$SESSION"
      sess=(--resume "$SESSION")
    fi
    note "grok -p -m $MODEL ${eff[*]:-} --permission-mode bypassPermissions ${gate[*]:-} ($MODE)"
    note "session: $grok_session_id"
    status=0
    raw="$(grok -p "$gprompt" -m "$MODEL" ${eff[@]+"${eff[@]}"} \
      --permission-mode bypassPermissions ${gate[@]+"${gate[@]}"} \
      "${sess[@]}" --cwd "$REPO" --output-format json </dev/null)" || status=$?
    result="$(printf '%s\n' "$raw" | python3 -c '
import json, sys
raw = sys.stdin.read()
try:
    obj = json.loads(raw)
    print(obj.get("text") or "(grok returned no result text)")
except Exception:
    print(raw.strip() or "(grok returned no result text)")')"
    finish_result "$result" "$status"
    ;;

  *)
    die "unknown agent '$AGENT' (expected copilot | codex | claude | cursor | grok)"
    ;;
esac