Gemini CLI Subagents: A Controlled Investigation Workflow for Coding Teams

Problem definition: long coding sessions blur evidence and decisions

A coding assistant can inspect code, search documentation, run tests, and propose edits in one conversation. That is convenient until the session starts treating its own intermediate notes as facts. The practical failure is not simply a long prompt. It is a mixed context where exploration, implementation, and review compete for the same attention.

This guide shows how to use Gemini CLI subagents as a control boundary for a repository task. It is for teams that need a repeatable way to investigate a codebase without handing a subagent broad authority. It is not a case for delegating every small edit or for treating an agent summary as proof.

Recommendation: isolate research first; keep the final decision and write access in the main session

Start with a subagent when the task has a clear question, a bounded output, and evidence that another person can reproduce. Good examples are mapping an authentication flow, locating callers of a deprecated API, or comparing two configuration paths.

Do not start with a subagent when the task is a one-file change, the question is still vague, or the subagent would need production credentials to answer it. In those cases, narrowing the task or reading the relevant file directly is safer and faster.

System breakdown: three boundaries that prevent a useful delegation from becoming noise

Main session: owns the acceptance criteria, chooses what evidence matters, and decides whether a change may be made. It should receive a short report, not an unfiltered transcript.

Subagent context: owns one investigation. Gemini CLI documents subagents as separate context loops with their own system prompt and persona. That separation protects the main conversation from tool output and speculative paths, but it does not make the result correct.

Repository and tool boundary: limits what the investigation can read or execute. Treat tool access as part of the task contract. A research subagent does not need deploy, secret, or destructive tools.

Why this design works better than a larger prompt

A longer prompt can describe roles, but it does not remove old assumptions or tool logs from the same context. A separate context makes the handoff explicit: the subagent returns claims, file paths, commands run, and uncertainties. The main session can then verify only the claims that would affect the decision.

The trade-off is coordination. Each handoff costs time and can omit useful detail. Use a subagent only when reducing context contamination or parallelizing evidence is worth that cost. For a narrow edit, a single well-scoped session is the better design.

Step-by-step: run a controlled repository investigation

1. Write a decision question. Use a question with a finish line: “Which modules create outbound payment requests, and what tests cover retries?” Avoid “Understand payments.”
2. Set an evidence contract. Require file paths, symbols, commands run, observed output, and open questions. State that the subagent must distinguish observations from inferences.
3. Set authority. For the first pass, allow read-only navigation and tests that do not change shared state. Do not include deployment, credential, or irreversible database actions.
4. Invoke the specialist. Gemini CLI documents automatic delegation and an explicit @agent_name form. For a codebase question, a prompt can begin: @codebase_investigator Map the retry path for outbound payment requests. Return files, symbols, tests, and unresolved assumptions. Do not edit files.
5. Verify the return. Open the cited files in the main session. Re-run the one or two commands that carry the decision. If a claim cannot be reproduced, mark it unverified instead of forwarding it into an implementation prompt.
6. Make a reversible change. Only after verification should the main session request an edit. Keep the change small, run the relevant test, and record how to revert it.

A usable handoff template

Goal: Identify every code path that can send an outbound payment request.
Scope: Read this repository only. Do not edit files or call external services.
Return: (1) file and symbol map, (2) exact commands run and results,
(3) tests that cover each path, (4) assumptions and gaps.
Done when: A reviewer can reproduce each claimed path from the returned evidence.

This template is deliberately restrictive. It makes a negative result useful: “No retry test found” is evidence for a follow-up task, not a reason for the subagent to invent one.

Alternatives and trade-offs

Approach	Use it when	Cost	Control risk
One main session	The task is narrow and the files are known.	Lowest coordination cost.	Logs and assumptions can accumulate.
Gemini CLI subagent	The question can be bounded and returned as evidence.	Handoff and review time.	Summary can hide omissions unless verified.
Human code review or paired investigation	The decision changes security, money movement, or production access.	Higher calendar cost.	Best option when accountability matters more than speed.

My recommendation is the middle option for exploration and the human option for high-consequence approval. Do not use a subagent to replace the accountable reviewer for a sensitive change.

Cost and operations: measure work units, not model mythology

Track the number of delegated investigations, verification commands repeated, tasks reopened because the handoff was incomplete, and elapsed time from question to accepted evidence. These measures reveal whether isolation is reducing rework. Do not claim a universal token or productivity saving; the result depends on repository size, task ambiguity, model choice, and tool permissions.

Set a stop condition before you delegate. For example, stop after the subagent returns a symbol map plus two reproducible paths. If the task keeps expanding, split it into a new question instead of allowing a generalist investigation to absorb the whole project.

Pitfalls and recovery

• Vague delegation. “Review the architecture” produces a broad narrative. Recover by restating one decision question and a required evidence format.
• Tool authority exceeds the question. An investigator can accidentally make a change or call an external system. Recover by starting read-only and granting one additional capability only when the evidence requires it.
• Summary accepted as proof. A plausible file list can still miss a feature flag or test fixture. Recover by opening cited files and rerunning decision-critical commands in the main session.
• Recursive delegation hides ownership. Multiple layers make it unclear who checked what. Recover by recording the owner of each claim and keeping one session responsible for the final acceptance decision.

Limits: context isolation is not a security sandbox

A separate context reduces conversational contamination. It does not independently enforce your repository policy, validate a result, or guarantee that a tool call is safe. Configuration and runtime permissions remain the control plane. Gemini CLI’s configuration reference documents agent overrides, including enabling, model configuration, and run configuration; teams should review those settings alongside their normal repository controls.

Further study

• Gemini CLI Subagents documentation — accessed 2026-08-28; confirms separate context loops, built-in roles, automatic delegation, and explicit invocation.
• Gemini CLI configuration reference — accessed 2026-08-28; review agents.overrides before standardizing a team workflow.
• Verification loops for coding agents — use this when turning an investigation into an implementation gate.
• Human approval queues for agent workflows — use this when a result triggers an external action.
• Version-matched instructions for coding agents — use this to keep the task contract close to the repository.

FAQ

Should every coding task use a subagent?

No. Use one when isolation creates a reviewable evidence boundary. A small, known edit normally does not justify the handoff.

Does a separate context make the result trustworthy?

No. It makes the source of a claim easier to inspect. Trust still comes from reproducible evidence and appropriate review.

Can a subagent edit code?

It can be configured for action, but begin with read-only investigation when the goal is understanding. Give write authority only after the main session has accepted the evidence and defined a rollback path.

Implementation checklist

• State one decision question with a concrete finish line.
• Choose an agent role that matches the question.
• Limit tools and external authority for the first pass.
• Require file paths, commands, results, and uncertainties in the handoff.
• Re-run decision-critical commands outside the subagent context.
• Make the first change reversible and test it.
• Record what was verified, what remains unknown, and who owns the next decision.

Definition of done: a reviewer can reproduce the evidence, understand the authority boundary, and reverse the accepted change without relying on the subagent’s hidden reasoning.