Use this for tasks that finish in a few minutes. For long/agentic work,
prefer `handoff_start` + `handoff_status` so you get progress and don't block.

Choosing a backend (see `handoff_guidance` for detail):
  - `codex` (OpenAI): code review, bug hunting, refactors, terminal-agentic
    work, second opinion on code/text. Text & images (not PDFs).
  - `antigravity` (Google Gemini 3): visual feedback (screenshots, diagrams,
    PDFs), very-long-context reads (whole repos / huge docs), cheap bulk.

Hand off aggressively when the Claude/Fable usage limit is close — each
backend bills to a separate subscription pool.

Args:
    prompt: What to do. The peer agent has NONE of this conversation's
        context — be explicit and self-contained.
    backend: "codex" or "antigravity".
    files: Absolute/~ paths to attach. codex: text + images. antigravity:
        text, images, and PDFs.
    model: Optional model id override; empty = the CLI's own default
        (e.g. "gpt-5.3-codex", "gemini-3.1-pro-preview").
    cwd: A project directory the agent may read for extra context. The
        process itself runs in a throwaway temp dir; originals are never
        modified unless you set `approve=True`.
    approve: Allow the agent to actually make edits (codex: workspace-write
        sandbox; antigravity: --dangerously-skip-permissions). Default False
        = read-only, right for reviews/opinions.
    timeout: Seconds before abort.

Returns:
    The peer agent's response, or a clear "[handoff error] …" string.

Use this for long or agentic handoffs (deep reviews, multi-file refactors,
reading a huge document). Then poll `handoff_status(job_id)` to watch
progress stream in and collect the result when it's `done`. This is the
async path — it lets you keep working / check in periodically instead of
blocking on one long call.

Args mirror `handoff`. Returns a short job id string (pass it to
`handoff_status`). The job's own timeout is generous (default 30 min).

Args:
    job_id: The id returned by `handoff_start`.
    tail: How many lines of streamed progress log to include.

Returns JSON with: `state` (running|done|error), `elapsed_s`, `backend`,
`log_tail` (the peer agent's streamed activity so far), and — once done —
`result` (or `error`). Call repeatedly until `state` != "running".

Call this first if a handoff returns an auth/not-found error. The output
includes a `staleness` banner reminding the maintainer to refresh the model
guidance when new models ship.

NOTE TO MAINTAINER: this reflects the model landscape as of
core.MODEL_INFO_UPDATED. Update core.ROUTING_GUIDE when new models/CLIs ship.