| name | agenterminal-plan-review |
| description | Use when you want to submit an implementation plan for review or approval through AgenTerminal. For full reviews, use type plan_review (spawns Codex analysis). For simple plan approval (replacing ExitPlanMode), use type plan_approval — shows the plan content directly to the user. |
Agenterminal Plan Review (Requester)
Use this workflow when you have written an implementation plan and want it reviewed before proceeding.
1. Write the plan
Write your plan to a file. This can be any path readable from the working directory (e.g. plan.md, or the Claude Code plan file).
2. Submit for review
Call the agenterminal.request MCP tool:
agenterminal.request
type: plan_review
description: <brief summary of the plan's goal>
plan_path: <path to the plan file>
auto_dispatch: true
The tool blocks until the user accepts or auto-dispatches (up to 5 minutes).
- If accepted, returns
{ accepted: true, conversation_id: "<id>" }. This means the review process started — it does NOT mean the plan passed review.
- If declined, returns
{ accepted: false, feedback: "<user's feedback>" }. Revise the plan and resubmit.
- If timed out, returns
{ accepted: false, reason: "timeout" }.
3. Wait for reviewer feedback
A fresh Codex reviewer will be spawned to analyze your plan. Wait for the [Conversation notification] or [Review completed] message.
When notified, read the conversation:
agenterminal.conversation.read
conversation_id: <id>
since_id: <last_seen_id or omit on first read>
Check for PLAN_APPROVED in a turn from the reviewer (mode: codex) — this means the plan passed with no blocking concerns. Proceed to implementation.
4. Handle reviewer feedback (re-review cycle)
If the reviewer has MUST-FIX items (no PLAN_APPROVED):
- Revise your plan file to address the blocking concerns
- Post an update to the conversation summarizing your revisions:
agenterminal.conversation
event: turn
conversation_id: <id>
role: agent
text: <summary of revisions made>
mode: claude
- Submit a NEW
agenterminal.request to spawn a fresh reviewer for re-review:
agenterminal.request
type: plan_review
description: Re-review after addressing feedback for <original description>
plan_path: <path to the plan file>
conversation_id: <same conversation_id>
auto_dispatch: true
IMPORTANT: Do NOT poll or wait for the original reviewer to respond. The reviewer has already exited. You MUST submit a new agenterminal.request to get a fresh reviewer.
- Wait for the new
[Conversation notification] and repeat from step 3.
The conversation ID persists across all review rounds so each fresh reviewer reads the full history.
5. Proceed
Once you see PLAN_APPROVED from the reviewer, proceed with implementation.
Plan Approval (ExitPlanMode replacement)
When you are in plan mode and want user approval to proceed (replacing the built-in ExitPlanMode), use plan_approval instead of plan_review:
agenterminal.request
type: plan_approval
description: <brief summary of the plan's goal>
plan_path: <path to the plan file>
This shows the rendered plan content directly to the user for accept/decline. No Codex reviewer is spawned. Use this for lightweight plan approval where you just need a go/no-go from the user.
- If accepted, returns
{ accepted: true }. Proceed with implementation.
- If declined, returns
{ accepted: false, feedback: "<user's feedback>" }. Revise and resubmit.
Auto-Dispatch (Synchronous)
When using auto_dispatch: true, the agenterminal.request tool blocks until the reviewer completes and returns the result inline:
{ "review_approved": true, "feedback": "..." }
- If
review_approved is true: proceed to implementation.
- If
review_approved is false: read the feedback, revise the plan, then submit a NEW agenterminal.request with the same conversation_id for re-review.
- Max 3 review rounds.
- Do NOT use
agenterminal.conversation tools for auto-dispatch reviews — results are inline.
Tips
- Keep the plan description concise — the reviewer reads the full plan file.
- If you revise the plan after feedback, update the plan file in place so the path stays the same.
- Use
plan_review when you want Codex analysis alongside user acceptance. Use plan_approval when you just need user sign-off (e.g., replacing ExitPlanMode).
- For manual reviews (no auto_dispatch): use conversation tools as described in the main flow.
- For auto-dispatch reviews: the tool blocks and returns results inline — no conversation needed.