Delegate a well-scoped subtask to Antigravity (agy/Gemini) under cost discipline, then verify.

Args:
    prompt: The task prompt to send to Antigravity.
    tier: Model tier (flash, flash-med, flash-lo, pro, pro-lo, sonnet, opus, gpt-oss). Default is flash.
    dirs: Workspaces to attach so agy reads real files.
    yolo: Auto-approve all tool permissions (DANGEROUS). Required for web search.
    sandbox: Run agent with terminal sandbox restrictions.
    continue_session: Resume the most recent agy conversation (stateful).
    conversation_id: Resume a specific agy conversation by ID (stateful).
    timeout: Print-mode timeout, e.g., '10m'. Default is '5m'.

Start a long-running Antigravity (agy/Gemini) task in the background.
Returns a job_id that can be used to check status.

Args:
    prompt: The task prompt to send to Antigravity.
    tier: Model tier (flash, flash-med, flash-lo, pro, pro-lo, sonnet, opus, gpt-oss). Default is flash.
    dirs: Workspaces to attach so agy reads real files.
    yolo: Auto-approve all tool permissions (DANGEROUS). Required for web search.
    sandbox: Run agent with terminal sandbox restrictions.
    continue_session: Resume the most recent agy conversation (stateful).
    conversation_id: Resume a specific agy conversation by ID (stateful).
    timeout: Print-mode timeout, e.g., '10m'. Default is '5m'.

Check the status and retrieve the output of a background job.

Args:
    job_id: The ID of the job to check.

Launch parallel grounded-research workers, one detached Antigravity (agy) job per sub-question.

This is the fan-out half of a deep-research pipeline. Each worker web-searches its
sub-question, writes a full markdown report to a file, and prints a short digest to
stdout. Reports stay on disk so Claude's context stays lean — poll with
research_status(batch_id) and gather with collect_digests(batch_id).

Args:
    topic: The overarching research topic (gives each worker shared context).
    subquestions: One focused sub-question per worker. Each launches a parallel job.
    tier: Model tier for every worker (default 'pro' = Gemini 3.1 Pro High).
    timeout: Per-worker print-mode timeout, e.g., '10m'.

Report aggregate status of every worker in a research batch.

Args:
    batch_id: The batch ID returned by research_fanout.

Gather the stdout digests from a finished research batch (NOT the full reports).

Keeps Claude's context lean: returns each worker's short digest plus the on-disk path
to its full report. Read individual subreport.md files only when a claim needs deeper
verification.

Args:
    batch_id: The batch ID returned by research_fanout.
    include_stderr: If True, also include each worker's stderr (for debugging failures).

Draft clarifying questions and candidate sub-questions to sharpen a research brief.

Run this BEFORE research_fanout. It offloads brainstorming the interview to a cheap
agy model: it returns clarifying questions (each with suggested answer options) that the
orchestrator should put to the user, plus a draft set of sub-questions. The orchestrator
then asks the user, refines the brief, and only then spends quota on research_fanout.

Returns JSON: {"clarifying_questions": [{"question", "why", "options": [...]}],
"draft_subquestions": [...]}. Falls back to raw text if the model returns non-JSON.

Args:
    topic: The research topic to interrogate.
    context: Optional extra context (audience, deadline, what's already known).
    tier: Model tier for the brainstorm (default 'flash' — this is a cheap task).

Draft clarifying questions and candidate requirements to sharpen a build/improvement brief.

The first step of the Architect pipeline (the *grill*). Mirrors propose_research_questions
but for software projects: offloads brainstorming the requirements interview to a cheap
agy model. Returns clarifying questions (each with answer options) the orchestrator should
put to the user, plus a draft set of requirements. The orchestrator asks the user, refines,
and writes requirements.md before spending quota on a code review or design doc.

Returns JSON: {"clarifying_questions": [{"question", "why", "options": [...]}],
"draft_requirements": [...]}. Falls back to raw text if the model returns non-JSON.

Args:
    goal: The project goal — what to build or improve.
    repo_path: Optional path to an existing codebase being improved (gives the model context).
    context: Optional extra context (users, constraints, deadline, what already exists).
    tier: Model tier for the brainstorm (default 'flash' — this is a cheap task).

Launch parallel codebase-review workers, one detached Antigravity (agy) job per aspect.

The code analog of research_fanout. Each worker reads the repo (via --add-dir) and reviews
ONE aspect (architecture, security, performance, tests, etc.), writes a full markdown report
to disk, and prints a short digest to stdout. Reports stay on disk so Claude's context stays
lean — poll with research_status(batch_id) and gather with collect_digests(batch_id), exactly
as for a research batch (the collectors are batch-generic).

Args:
    repo_path: Absolute path to the codebase to review.
    aspects: One review aspect per worker. Defaults to a 7-aspect standard sweep.
    goal: Optional improvement goal to focus the review (e.g. 'prepare for multi-tenant SaaS').
    tier: Model tier for every worker (default 'pro' = Gemini 3.1 Pro High).
    timeout: Per-worker print-mode timeout, e.g., '10m'.

Have Antigravity draft a structured design document (with work packages) from on-disk batches.

The synthesis step of the Architect pipeline. agy reads the digests/subreports from the given
review + research batch dirs PLUS the orchestrator's verified `brief`, and drafts a full design
doc to `out_path`. Returns only a short digest — the orchestrator (Claude) then reads the file,
verifies claims, and edits it in place. This is the 'agy drafts, Opus refines' gate.

Args:
    goal: The project goal the design serves.
    brief: Claude's verified findings / requirements (the trustworthy synthesis so far).
    batch_ids: review_fanout / research_fanout batch IDs whose reports agy should read.
    out_path: Absolute path to write the design doc (e.g. <repo>/design.md).
    tier: Model tier for the draft (default 'pro').

Get an independent cross-model review of a code diff using Antigravity.

Tip: set tier='gpt-oss' or 'sonnet' for a genuinely different model family than the
author, which surfaces blind spots a same-family reviewer would share.

Args:
    diff: The git diff or code changes to review.
    adversarial: If True, challenges design decisions and trade-offs rather than just finding line-level bugs.
    tier: Model tier. Default is 'pro' for deeper reasoning.

Automatically stage, generate a commit message using Antigravity, commit, and optionally push.
Use this to offload boring token-wasting git operations from the frontier model.

Args:
    repo_path: The absolute path to the git repository.
    push: Whether to 'git push' after committing.
    stage_all: Whether to 'git add .' before generating the commit. If False, only uses currently staged changes.

Reads specific directories or files using Antigravity's massive context window and returns a distilled architectural index.
Use this to quickly understand a subset of a codebase (or a whole repo) without pulling all the raw files into the frontier model's context window.

Args:
    paths: A list of absolute paths to directories or files to index.
    focus: What to focus the index on (e.g., 'general architecture', 'database schemas', 'API routes'). Default is 'general architecture'.
    out_path: Optional absolute path to also persist the index to (e.g. '<repo>/docs/ARCHITECTURE.md') so it survives for incremental reuse instead of living only in the caller's context.