joogy06/agent-foundry/codex-orchestration

Cross-Model Orchestration — Claude + Codex + Antigravity (agy)

Delegate tasks to Codex CLI (GPT-5.6-sol) and the Antigravity CLI (`agy`) from Claude Code for second opinions, parallel research, challenger reviews, and idea generation. Each model runs as an independent agent with its own context, tools, and reasoning — different models catch different things.

<HARD-RULE> Pin reasoning effort PER CALL on every codex exec delegation: -c model_reasoning_effort=<tier> (see "Reasoning-Effort Tiers" below). Never rely on the config default — ~/.codex/config.toml holds whatever the interactive TUI last persisted, so an unpinned headless call can silently run anywhere from none to max. </HARD-RULE>

<HARD-RULE> Always check Codex availability before delegating. Read tools.codex.installed from ~/.claude/state/inventory.json (written by env-adoption skill). If the inventory is missing, run bash ~/.claude/skills/env-adoption/scripts/probe.sh check --inventory-only --silent first. If tools.codex.installed is false, fall back to Claude Code agents. </HARD-RULE>

<HARD-RULE> Never pass secrets, API keys, or credentials in Codex prompts. Prompts may be logged in ~/.codex/sessions/ and ~/.codex/history.jsonl. Use environment variables or file references instead. </HARD-RULE>

<HARD-RULE> Always use --ephemeral for orchestration tasks to avoid polluting Codex session history. Orchestration calls are fire-and-forget — they don't need persistent sessions. </HARD-RULE>

<HARD-RULE> </HARD-RULE>

Codex Plugin Commands (Primary Interface)

The Codex plugin (codex@openai-codex) provides first-class slash commands for structured Codex interaction. Prefer plugin commands over raw `codex exec` for reviews, task delegation, and managed workflows.

When to Use Plugin vs Raw codex exec

Plugin commands handle job lifecycle (tracking, resume, cancel). Raw `codex exec` is better for parallel orchestration and custom prompt engineering.

Antigravity CLI (agy) — Primary Interface

The Antigravity CLI (agy) is this host's second-opinion / challenger / research delegate. It authenticates itself via the Antigravity account — no API key or env prefix needed. There is no MCP server: call agy directly via Bash. See the antigravity-cli skill for the full reference.

Headless single-prompt mode:

timeout 600 agy --sandbox -p "<prompt>" < /dev/null

• STDIN RULE (mandatory, #135): < /dev/null on every headless agy call — agy reads

non-TTY stdin until EOF before the model call; background/harness shells never EOF → infinite hang at 0 bytes (--print-timeout does not protect; it guards only the print phase). Piped input (cat file | agy -p) is safe (the pipe EOFs). Always wrap in shell timeout. Same behavior class as codex exec's stdin-block.

• FLAG ORDER RULE (mandatory, root-caused 2026-07-02): every flag BEFORE -p, prompt LAST.

-p is a string flag and consumes the next token — agy -p --sandbox "X" runs UN-sandboxed with the literal prompt --sandbox and discards "X", after which agy improvises from its implicit memory (the "does work instead of consulting" failure mode) and can fork-bomb re-testing the broken command. Correct: agy --sandbox [--add-dir D] [--print-timeout 15m] -p "…".

• SANDBOX RULE (mandatory for analyst/read-only delegation, #157): --sandbox on every agy

call that should only READ — agy has write/shell/git tools by default, and an un-sandboxed "analyst" can author and git-commit code (S052 rogue auto-commit incident). Scope caveat (verified 2026-07-02, 1.0.15): --sandbox constrains shell/git commands only, NOT agy's native file writes — do not --add-dir a writable live repo for consultancy (pipe content instead), open the prompt with "Advisory only — do not modify any files; answer on stdout", and run git status --short afterwards if a repo was exposed. Omit --sandbox only when the task explicitly requires writes, and say so in the prompt.

• Output is plain text on stdout — there are no structured response fields. Callers must parse text, not JSON.
• agy uses the Antigravity-account default model by convention — as of 1.0.5+ (current 1.1.6) a --model flag and an agy models subcommand DO exist (there is no short -m alias), but omit --model unless a call explicitly needs a specific model. The account default is `gemini-3.6-flash` (verified 2026-07-24), so omitting the flag rides the current line automatically. FLASH-ONLY HARD-RULE (user directive 2026-07-24): agy runs gemini flash models ONLY. ✅ gemini-3.6-flash-{high,medium,low} (current) / gemini-3.5-flash-* (legacy). ❌ FORBIDDEN with no carve-out: claude-sonnet-4-6, claude-opus-4-6-thinking, gpt-oss-120b-medium, and `gemini-3.1-pro-{high,low}`. Reasons: (1) provider diversity — agy holds the third-model slot because it is neither Anthropic nor OpenAI; repointing it at claude-sonnet-4-6 (the tempting "fix" for an agy no-show) collapses the cross-check into an echo, and gpt-oss-* collapses into the Codex arm; (2) flash-tier discipline — agy is advisory-tier, so don't reach for pro. On a no-show: retry under the STDIN/FLAG-ORDER/Pattern-2 rules, then record the provider gap honestly — there is no gemini fallback (retired 2026-07-25). Escalate to another arm rather than repointing agy.
• For long-running prompts raise the wait timeout: agy --print-timeout 15m -p "<prompt>" < /dev/null (default 5m0s). Keep < /dev/null even here — --print-timeout only guards the print phase, NOT the stdin read, so omitting it still hangs to the shell timeout (#135).
• Append a served_by probe line to the prompt if you need provenance — self-reported model identity is unreliable, so capture it at the call layer.

Use cases (all via a single agy -p call): research, analysis, code review, large-file analysis, and brainstorming (frame the methodology — SCAMPER, Design Thinking, Divergent, Convergent, Lateral — directly inside the prompt text, since there is no dedicated brainstorm tool).

agy -p invocation patterns

# Basic headless mode (plain-text stdout — no JSON output mode)
agy --sandbox -p "Review this code for security issues" < /dev/null
 
# With piped context
cat src/main.py | agy --sandbox -p "Find N+1 query problems"
 
# Reference a workspace directory instead of piping (repeatable)
# CAUTION: --sandbox does NOT gate native file writes into --add-dir trees — prefer piping;
# if you must --add-dir a writable repo, run `git status --short` afterwards and revert strays.
agy --sandbox --add-dir "$PROJECT_DIR" -p "Advisory only — do not modify any files; answer on stdout. Review for security issues in this project" < /dev/null
 
# Structured brainstorming — frame the methodology inside the prompt
agy --sandbox -p "Use SCAMPER to generate ideas for reducing checkout abandonment. List each lens separately." < /dev/null
 
# Parallel with Codex (triple-model validation)
CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)
AGY_WORK=$(mktemp -d /tmp/agy-XXXXXXXXXX)
 
timeout 600 codex exec --ephemeral -C "$PROJECT_DIR" -s read-only \
  -o "$CODEX_WORK/review.md" "Review for security issues" < /dev/null &
timeout 600 agy --sandbox --add-dir "$PROJECT_DIR" -p "Review for security issues in this project" \
  > "$AGY_WORK/review.txt" < /dev/null &
wait

agy Availability Check

AGY_AVAILABLE=$(agy --version 2>/dev/null && echo "yes" || echo "no")

Cache for the session like the Codex check. Both can be checked in parallel at session start.

Reasoning-Effort Tiers (benchmarked 2026-07-11)

Measured on gpt-5.6-sol / codex-cli 0.144.1 with planted-bug review fixtures (14 scored runs, easy + hard rounds + a delta-seeking challenger round). Every tier found all planted bugs with zero false positives; the only quality separations were (a) one subtle unplanted defect caught only at xhigh/max under a plain review prompt, and (b) finding ALTITUDE under a delta-seeking prompt — medium returned concrete-bug deltas, xhigh added state-consistency reasoning, max alone produced a design-level finding. high never beat medium in any run — skip it. ultra matched max's findings at 2.3x the time on bounded tasks; it exists for orchestrated deep dives, not verdicts.

# Challenger call — xhigh floor, effort pinned per call
timeout 600 codex exec --ephemeral -s read-only \
  -c model_reasoning_effort=xhigh \
  -o "$CODEX_WORK/challenge.md" "$(cat "$CODEX_WORK/brief.md")" < /dev/null

Delta-seeking challenger prompt (the honest-loop contract). Prompt shape matters as much as tier: telling codex "the basics are done" reallocates attention to the tail — at medium this recovered a subtle bug that a plain review prompt missed even at high. Template to embed in challenger briefs:

A prior review already found: <findings list>. Your ONLY job: find genuine defects the

prior review MISSED. Do not repeat, rephrase, or elaborate on listed findings. Inventing

a finding to have something to say is a failure mode; if you find nothing genuinely new,

output exactly: NONE_FOUND

Operational notes:

• Retry ONCE on Selected model is at capacity (transient; fails within ~2s, so the retry is cheap).
• Keep -s read-only on every consultancy call: at max, codex has run unrequested

read-only shell detours (reading its own skill files) despite an explicit "do not browse the filesystem" instruction — the sandbox contained it.

• max/ultra workflow stages need raised timeouts (1200s/1800s), not the default 600s.

Three-Model Validation Pattern

For COMPLEX tasks, run all three models for maximum coverage: