Package com.tnsai.planning.llm

Class PlanApprovalGate

java.lang.Object

com.tnsai.planning.llm.PlanApprovalGate

public final class PlanApprovalGate
extends Object

Plan-level human-in-the-loop approval gate.

Sits between plan generation and execution, presenting the plan to the user for review. Users can approve, reject, modify, or reorder steps before execution proceeds.

Approval Flow

1. Planner generates plan
2. Gate presents plan to user via PlanApprovalGate.PlanReviewCallback
3. User returns an PlanApprovalGate.ApprovalDecision
4. Gate applies modifications and returns the final plan (or empty on reject)

Usage

 PlanApprovalGate gate = PlanApprovalGate.builder()
     .reviewCallback(plan -> {
         System.out.println(plan.toDisplayString());
         System.out.print("Approve? (y/n/modify): ");
         String input = scanner.nextLine();
         if ("y".equals(input)) return ApprovalDecision.approve();
         if ("n".equals(input)) return ApprovalDecision.reject("User rejected");
         return ApprovalDecision.approve(); // simplified
     })
     .build();

 Optional<LLMPlan> approved = gate.review(generatedPlan);
 approved.ifPresent(plan -> engine.executePlan(plan));
 

Integration with ToolCallFilter

For step-level approval during execution, combine with the agent's ToolCallFilter. The gate handles plan-level approval; the filter handles individual tool call approval.

Since:

0.3.0

See Also:

• LLMDynamicPlanner
• AdaptiveReplanEngine

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	PlanApprovalGate.ApprovalDecision	Represents the user's decision after reviewing a plan.
static enum	PlanApprovalGate.ApprovalType	Type of plan approval decision.
static final class	PlanApprovalGate.Builder	Builder for PlanApprovalGate.
static interface	PlanApprovalGate.PlanReviewCallback	Callback for presenting a plan to the user for review.

Method Summary

Modifier and Type	Method	Description
static PlanApprovalGate	autoApprove()	Creates a gate that auto-approves all plans (useful for testing/automation).
static PlanApprovalGate.Builder	builder()	Creates a new builder.
Optional<LLMPlan>	generateAndReview(LLMDynamicPlanner planner, String goal)	Generates a plan and reviews it in one step.
Optional<LLMPlan>	generateAndReview(LLMDynamicPlanner planner, String goal, Map<String,Object> state)	Generates a plan with state context and reviews it.
Optional<LLMPlan>	review(LLMPlan plan)	Reviews a plan through the approval gate.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

builder

public static PlanApprovalGate.Builder builder()

Creates a new builder.

autoApprove

public static PlanApprovalGate autoApprove()

Creates a gate that auto-approves all plans (useful for testing/automation).

review

public Optional<LLMPlan> review(LLMPlan plan)

Reviews a plan through the approval gate.

Parameters:

plan - the plan to review

Returns:

the approved (possibly modified) plan, or empty if rejected

generateAndReview

public Optional<LLMPlan> generateAndReview(LLMDynamicPlanner planner,
 String goal)

Generates a plan and reviews it in one step.

Parameters:

planner - the planner to use

goal - the goal

Returns:

approved plan, or empty if rejected

generateAndReview

public Optional<LLMPlan> generateAndReview(LLMDynamicPlanner planner,
 String goal,
 Map<String,Object> state)

Generates a plan with state context and reviews it.

Parameters:

planner - the planner to use

goal - the goal

state - current state

Returns:

approved plan, or empty if rejected