Plan Review

When to useCopy Anchor Link

• Before multi-step work the agent will carry out itself: a launch, a data clean-up, a migration.
• The user should shape the steps (order, scope, what to skip) before anything runs.
• Some steps write to shared systems or are hard to undo, and the user should see them first.

When not to useCopy Anchor Link

• The steps are for the user to do. Use a Checklist.
• It's one or two quick, reversible actions. Just do them, or confirm in text.
• The agent is proposing specific field values. Use a Change Preview.

How the agent should use itCopy Anchor Link

• Write each step as an action the agent will take, in run order, with the tools it uses (only tools it actually has).
• Mark where it will stop. requiresApproval shows "Pauses for approval"; risk: "medium" or "high" shows a warning for bulk, shared or irreversible writes.
• Fill dependsOn for real dependencies only. The user is warned when a reorder, removal or skip breaks one, and can't approve until it's fixed.
• Give estimates as minutes or hours ("~2 min", "1 h") so the header can sum them. If any step can't be summed ("~1 day"), the header shows totalEstimate instead.
• List assumptions that would change the plan if wrong, five at most. "These are wrong" opens the feedback box for them.
• Run nothing until approve arrives, then run exactly the returned steps, in order, skipping enabled: false. For steps with addedByUser, ask how to do them if it isn't clear.
• Lifecycle: supersede, don't stack. When the agent proposes a revised plan after revise, mark the old card superseded (markSuperseded(calls, { names: ["propose_plan"] })). A plan needs no expiresAt; set fetchedAt and staleAfterMs only when it was built on live data that may change before the user approves.

Editing the planCopy Anchor Link

Nothing runs while the user edits. Every change is marked on its step ("Moved", "Edited", "Added by you"), and the approve button becomes Approve edited plan. The footer keeps Request changes and Approve as buttons; Dismiss (✕) and Reset (↺) are icon buttons with labels. The header shows only the total time; the step count, goal, each step's tools and estimate are read to screen readers but not shown, to keep the card short.

Dependency guard. If a step would run before a step it needs, or that step is removed or skipped, the step shows a warning ("Step 1 needs “Find duplicates”, which now runs later.") and approve is disabled. Move it back, undo the removal, or remove the dependent step.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/plan-review.json

UsageCopy Anchor Link

import { tool } from "ai"
import { planReviewTool } from "@/components/genui/plan-review.schema"

const tools = {
  // No execute(): the call is completed by the user's decision in the UI.
  [planReviewTool.name]: tool({
    description: planReviewTool.description,
    inputSchema: planReviewTool.inputSchema,
  }),
}

<PlanReview
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : undefined}
  result={part.state === "output-available" ? part.output : undefined}
  onResult={(result) =>
    addToolResult({ tool: "propose_plan", toolCallId: part.toolCallId, output: result })
  }
/>

The agent receives one of:

{
  action: "approve",
  steps: [
    { id: "export", title: "Export contacts", enabled: true },
    { id: "find", title: "Find duplicates", description: "Match on email first", enabled: true },
    { id: "merge", title: "Merge duplicates", enabled: true },
    { id: "notify", title: "Notify record owners", enabled: false },
    { id: "added-1", title: "Tell the sales team", enabled: true, addedByUser: true },
  ],
  edited: true,
  changes: { moved: [], removed: ["report"], edited: [], added: ["added-1"], disabled: ["notify"] },
}
{ action: "revise", feedback: "About the assumptions: leave Enterprise records out" }
{ action: "dismiss" }

steps is the final order; removed steps are left out. moved is the smallest set of steps whose relocation explains the new order, so moving one step counts once and moving it back counts zero. On revise or dismiss, run nothing.

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "propose_plan", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

Pass the stored result back as result. An approved plan restores read-only in its final order, with skipped steps struck through and "Approved · running" in the footer; a revise shows the request. It never calls onResult again.

<PlanReview {...part.input} result={part.state === "output-available" ? part.output : undefined} />

SchemaCopy Anchor Link

PlanStep

Host props: status (streaming, ready, submitting, approved, revised, dismissed), onResult, result and className.

SourceCopy Anchor Link