Use Gemini CLI in a repeatable pipeline

A headless Gemini CLI stage can receive an evidence packet and return review findings. Use explicit execution policy and validate the result before another stage consumes it.

These commands are documentation-checked as of 2026-09-08. Gemini CLI was not installed in the verification environment. The package tests its output parser with synthetic envelopes; live invocation and policy behavior remain unverified.

Start with the same review packet

In the reference package, the edge-cases stage receives the original retry contract, proposed configuration, and deterministic checks. It does not receive the other reviewer's conclusions.

After approving scope and reaching that stage in an import run:

node cli.mjs export ./my-run --stage edge-cases --file gemini-request.json

The reference argument builder describes this invocation:

gemini --admin-policy ABSOLUTE_POLICY_FILE --output-format json \
  --model YOUR_AVAILABLE_MODEL -p EXPORTED_PROMPT

Use an argument array so prompt text cannot become shell syntax. Supply only the approved packet. A policy filename is not evidence that the expected policy actually took effect.

Configure and test headless policy

As of the verification date, Gemini CLI documents workspace policy loading as disabled. Placing a file in .gemini/policies inside the repository is therefore insufficient. Configure supported user or administrator policy outside the agent's writable workspace.

The documented --admin-policy option has a further condition: existing standard administrator policy files can cause the supplied option to be ignored. Inspect the effective environment and verify a deliberately denied tool call before sending real material.

For an artifact-only task, a reviewed policy can deny tools entirely:

[[rule]]
toolName = "*"
decision = "deny"
priority = 100

This is a policy fragment, not proof of the effective combined policy. Higher priority or managed rules and the installed version affect the outcome. Keep the prepared execution environment free of unrelated private files and credentials.

Keep the human gate outside headless Plan Mode

Interactive Plan Mode is useful for reviewing a concrete plan. Its headless behavior differs: the current documentation describes automatic plan entry and exit, with a transition into YOLO execution.

Do not use that transition as an automated equivalent of a human design approval. The reference invocation does not select headless Plan Mode. The coordinator waits for an explicit decision bound to the plan artifact.

A headless ask_user policy decision is treated as denial under the documented policy engine. Return that outcome to the coordinator. It should request the needed decision or narrow the task, while retaining the existing restriction.

Parse the inner result

--output-format json supplies a transport envelope. Its response is a string; parse that string separately and validate the resulting object. Markdown fences, missing required fields, invented paths, and missing terminal output are failures.

For streaming integrations, distinguish intermediate events, recoverable warnings, and the terminal result. Preserve actual process exit status. Reported statistics do not establish that a task succeeded or identify every internal model choice.

The package now supports supervised CLI execution through an explicit launcher/model profile. Use that walkthrough to automate dispatch and observe process outcomes while retaining human decisions. Its local subprocess tests do not establish credentialed provider behavior.

What goes wrong

A valid outer JSON envelope can contain unusable inner text. A workspace policy file may never load. Headless Plan Mode can advance without the human decision you intended. Verify each boundary separately before automating a real task.

How to check

Run the package tests. Confirm that a response containing fenced JSON is rejected, an envelope error cannot become a successful review, and a fabricated evidence line prevents acceptance.

Before enabling a live adapter, record the installed version and a synthetic policy-denial trial. Verify the requested and observable model configuration. If the environment's permission behavior cannot be established, keep this stage as an explicit manual handoff.