deep-review: define plugin-local reviewer agents instead of defaulting to general-purpose

Goal

Give deep-review's four Step 2 subagents dedicated, read-only agent definitions under plugins/deep-review/agents/, so a reviewer cannot write to the working tree and each concern's prompt lives in a file rather than inline in the command markdown.

Background

Step 2 of plugins/deep-review/commands/deep-review.md launches four parallel agents — Correctness & Security, Test Coverage, Design & Simplification, and Assumptions & Contracts. None of them passes subagent_type, so all four silently default to general-purpose, whose toolset is * — including Edit and Write.

Nothing but the wording of each prompt prevents a review agent from mutating the tree it is supposed to be reading. That is the concrete defect; the reviews themselves are correct today, so this is hardening rather than a bug fix.

The built-in agent types do not close the gap. Explore is read-only but its system prompt is scoped to locating code via excerpts and explicitly not reviewing or auditing it, so it would work against the reviewer prompt being passed in. Plan is a worse fit. There is no built-in read-only reviewer.

No plugin in this repo currently defines custom agents, so this would be the first agents/ directory here.

Why this is worth doing

Beyond preventing writes, in rough order of weight:

• The reviewer identity moves into the system prompt. Today the four concern prompts are passed as the agent's user turn, alongside the diff. An agent definition's body becomes its system prompt instead. This matters because the input these agents ingest is untrusted: a diff can contain comments, strings, or test fixtures whose text reads like instructions. A reviewer whose mandate sits at the system level is materially harder to talk out of its job than one whose mandate is merely earlier text in the same user turn as the attacker-controlled content. For an agent whose whole purpose is reading hostile-shaped input, this is the strongest argument in the issue.
• It closes off recursive agent spawning. general-purpose's toolset is *, which includes the Agent tool — so any of the four reviewers can spawn its own subagents. Step 2 already launches four opus agents in parallel; each fanning out further is unbounded token spend with nothing supervising it. Restricting tools to Read, Grep, Glob, Bash eliminates this as a side effect of the same change that removes Edit/Write.
• It removes a system-prompt conflict. general-purpose is framed as a research-and-search agent for multi-step tasks. That is not hostile to reviewing, but it is not reviewing either — the current prompt fights it rather than replacing it. A custom definition simply is the reviewer, with nothing to override.
• Smaller wins: the four prompts become diffable, greppable, version-controlled artifacts instead of paragraphs buried mid-file; other commands could reuse the agents later (real, but speculative — nothing else needs them today); each agent loads a smaller tool schema set, though deferred tool loading already mostly covers this.

Explicitly not a benefit: per-agent model selection. model can already be passed in the Agent call, and Step 2 does exactly that.

Proposed change

• Add plugins/deep-review/agents/ with one definition per concern area, each declaring tools: Read, Grep, Glob, Bash (no Edit, no Write, no Agent) and model: opus.
• Move each agent's system prompt out of Step 2 inline markdown and into its agent definition — consistent with the "prefer scripts over inline markdown" reasoning in CLAUDE.md.
• Update Step 2 to name each subagent_type explicitly, collapsing four embedded prompt paragraphs into four Agent calls.
• Keep the existing structured output contract (SEVERITY|file:line|description, GAP|file:line|description) unchanged so Step 2's reconciliation logic and the Step 12 self-check still apply as written.
• Write each description to state the agent is invoked by /deep-review and is not for general use.
• Preserve the existing fallback: if the Agent tool is unavailable or denied, Step 2 is skipped and Steps 3-10 still provide full coverage.

Acceptance criteria

• The four reviewer agents have no write tools available.
• The four reviewer agents cannot spawn further subagents.
• /deep-review produces the same five-section output format as before, with no regression in finding coverage.
• Step 2 of the command markdown no longer carries the four inline prompts.
• The plugin remains self-contained — the agent definitions reference nothing outside plugins/deep-review/.

Tradeoff to weigh during implementation

Plugin-defined agents register into the installing user's global agent list for every session, not only during /deep-review. This adds four entries that anyone installing the plugin sees permanently, and the main model may select them for unrelated work if the description fields are loose. Tight, purpose-scoped descriptions mitigate this but do not eliminate it.

The cheaper alternative — keeping general-purpose and adding an explicit "do not use Edit or Write" line to each prompt — costs nothing and pollutes no namespace. But note it buys strictly less: it is an instruction rather than an enforced constraint, it leaves the mandate in the same user turn as the untrusted diff, and it does nothing about recursive spawning. Weigh it against the namespace cost with that in mind.

Related

• #179 — whether the Correctness & Security agent should compose the built-in security-review skill (prompt sourcing; independent of this)

Start with Step 2 of plugins/deep-review/commands/deep-review.md and trace its four Agent calls, inline prompts, structured output, and fallback behavior. Add the four scoped definitions under plugins/deep-review/agents/, then update Step 2 to reference them while preserving the existing output contract and five-section result. Run /deep-review and verify the agents have only the stated read-only tools, cannot spawn subagents, and the fallback still works.