Feature Request: Configurable Review Gates (Auto-review before critical actions)

Problem Statement

When using Plan Mode for complex features, there's a well-known cognitive bias problem: after deep codebase exploration and iterative design, the planning agent becomes "attached" to its solution and may miss flaws, edge cases, or simpler alternatives.

Current workaround (manual):

1. Open Session 1 → Enter Plan Mode → Iterate until plan looks good
2. Open Session 2 (clean context) → Pass the plan → Ask for cons/risks/alternatives
3. Return to Session 1 → Incorporate feedback → Execute

This works well but:

• Requires manual intervention
• Easy to forget
• Depends on user discipline

Proposed Solution: Review Gates

A configurable "gate" system that automatically spawns a fresh-context reviewer agent before critical actions.

# .claude/settings.json
gates:
  pre_exit_plan_mode:
    enabled: true
    reviewer_prompt: |
      Review this plan critically. You have fresh context - use it.
      Find: cons, risks, missing edge cases, simpler alternatives.
      Be adversarial but constructive.
    require_resolution: true  # Block until user acknowledges review

How it would work

┌─────────────────────────────────────────────────────────┐
│  Plan Mode (main session)                               │
│  1. Explore codebase                                    │
│  2. Design plan iteratively                             │
│  3. Write plan to file                                  │
│  4. Call ExitPlanMode                                   │
│        ↓                                                │
│  ┌─── GATE TRIGGERED ───┐                               │
│  │ Spawn reviewer agent │ ← Clean context               │
│  │ Agent reads plan     │                               │
│  │ Agent critiques      │                               │
│  │ Returns findings     │                               │
│  └──────────────────────┘                               │
│        ↓                                                │
│  5. User sees review + original plan                    │
│  6. User decides: proceed / revise / reject             │
└─────────────────────────────────────────────────────────┘

Generalizable Pattern

This pattern extends beyond plan review:

| Gate | Trigger | Use Case |
|------|---------|----------|
| pre_exit_plan_mode | Before ExitPlanMode | Validate architectural decisions |
| pre_commit | Before git commit | Catch issues before commit |
| pre_pr_create | Before gh pr create | Final review before PR |
| post_large_edit | After Edit >100 lines | Review significant changes |

Why this matters

1. Reduces cognitive bias - Fresh context catches what tired context misses
2. Catches design flaws early - Fixing a plan is cheap; fixing code is expensive
3. Automates best practices - Senior devs do this manually; juniors often skip it
4. Leverages LLM strength - Multiple perspectives on same problem at near-zero cost
5. Differentiator - No competing tool (Cursor, Copilot) has this workflow

Alternative Implementations

Option A: Built-in gate system (proposed above)

Option B: Hook enhancement - Allow hooks to spawn agents and block execution

hooks:
  pre-tool-call:
    - matcher: "ExitPlanMode"
      type: "agent-review"  # New hook type
      agent_prompt: "Review this plan..."
      blocking: true

Option C: ExitPlanMode parameter

ExitPlanMode(require_review=true)

Real-world workflow that motivated this

I've been using the manual 3-session workflow for weeks on a security scoring system. The "fresh eyes" review consistently catches:

• Over-engineering that seemed justified after deep exploration
• Missing edge cases that were "obvious" to a fresh reader
• Simpler alternatives that the original session dismissed too quickly

Automating this would save ~10 minutes per feature while improving quality.