Gemini CLI Runtime Contract

This skill defines how polycli:polycli-provider-agent (the subagent) interacts with the polycli companion script for Gemini. Only invoked from within polycli:polycli-provider-agent.

Primary helper

node "${CLAUDE_PLUGIN_ROOT}/scripts/polycli-companion.bundle.mjs" rescue --provider gemini "<prompt>" --json

Commands available to the agent

The provider-agent forwards whatever subcommand the caller supplied. Use rescue for multi-step agent work and ask for one-shot questions; the rest are slash-command-driven user flows.

Resumable thread state is exposed via the --resume-last flag, not a separate subcommand.

Latency expectations

Only deep-reasoning Gemini variants (Pro / Thinking series) routinely spend 30s–several minutes silently reasoning before emitting visible text. Flash and other non-reasoning variants typically stream within seconds. This is upstream behavior, not a polycli stall.

To absorb the reasoning latency without inflating other models' budgets, the companion applies a model-scoped multiplier:

PROVIDER_TIMEOUT_MULTIPLIERS = {
  gemini: { "gemini-3.1-pro-preview": 2 },
  opencode: { "kimi-for-coding/k2p6": 2 },  // also a code-reasoning model
}

(The opencode entry was added 2026-05-02 after a HumanEval/130 Tribonacci probe hit the 120s ask ceiling; the same pattern can be extended to any other reasoning model id.)

Resolution rules (per resolveTimeoutMs in polycli-companion.mjs):

• --model gemini-3.1-pro-preview → ×2 budget (the explicit reasoning case)
• No --model, cached upstream-default model is gemini-3.1-pro-preview → ×2 budget (the common case today)
• --model <some-flash-or-other> → ×1 (caller explicitly chose a non-reasoning model)
• Unknown / cache empty / non-gemini provider → ×1

Effective ceilings when the multiplier applies:

health keeps the universal 60s budget regardless of model — gemini's health prompt is sentinel-only and does not exercise reasoning.

If you cannot estimate how long a gemini prompt will take (e.g. open-ended diagnosis on a large diff), prefer --background and poll with /polycli:status / /polycli:result instead of relying on the foreground timeout. The background worker reuses the same execution.timeout (so gemini still gets the model-resolved budget), but the calling shell is freed immediately and the user can decide how long to wait.

When upstream releases a new reasoning-capable Gemini model id, add it to PROVIDER_TIMEOUT_MULTIPLIERS.gemini. Do not blanket-multiply the whole provider — that would over-budget Flash users.

Routing controls

These are CLI flags, not prompt text:

• --background — run async, return job ID immediately
• --write — allow Gemini to modify files (maps to --approval-mode auto_edit)
• --resume-last — continue previous Gemini thread
• --fresh — start new thread (ignore previous)
• --model <model> — override the default model
• --effort <low|medium|high> — reasoning effort level
• --prompt-file <path> — read prompt from file instead of positional args
• --json — always use this for machine-readable output

Safety rules

• Preserve prompt text as-is. Only reshape via gemini-prompting skill.
• Never inspect the repo from the agent. Claude does that.
• Return stdout exactly. No independent analysis.
• Return nothing if invocation fails (let Claude handle the error).

Source: bbingz/polycli — distributed by TomeVault.