[Feature]: Add mandatory plan-before-execute step for agent tasks

[louisdevzz]

Summary

Implement a mandatory plan-before-execute step for all agent tasks that modify state, ensuring users can see and approve the agent's intended approach before execution begins.

Problem statement

Currently, the agent executes tasks immediately without presenting a clear plan first:

• User says "build a coffee cat website"
• Agent immediately runs tools (sandbox_create, npx create-next-app, etc.)
• User doesn't know what will happen until tools are already running
• No opportunity to review or adjust the approach

This creates:

1. Lack of transparency - users are surprised by what the agent does
2. No course correction - can't adjust plan before execution
3. Difficult debugging - don't know what agent intended vs what actually happened

Proposed solution

Add a mandatory plan step that works like this:

1. User makes request: "build a coffee cat landing page"
2. Agent thinks and creates plan: Uses LLM to analyze request and generate plan

   📋 Plan:
   • Create Next.js project with TypeScript and Tailwind
   • Build landing page with: Hero section, Features, Contact form
   • Style with cat/coffee theme
   • Deploy to sandbox for preview
   

3. Show plan to user: Display clearly in conversation
4. User responds:
   • "yes" / "ok" / "build it" → Execute the plan
   • "add pricing section" → Update plan
   • "use Vue instead" → Update plan
   • "cancel" → Stop and do nothing

Implementation approach:

• On first tool iteration with write operations, intercept and generate plan
• Call LLM with system prompt + user request to get plan text
• Return plan as assistant message (not execute tools yet)
• On next user message, check if user approved
• If approved → Continue with tool execution
• If modified → Regenerate plan with changes
• If rejected → Stop gracefully

Non-goals / out of scope

• Complex interactive plan editing with multi-turn refinement (v1 should be simple)
• Automatic plan optimization based on past user feedback
• Plan templates or reusable plan fragments
• Plan persistence across sessions
• Plan comparison/diff between versions

Alternatives considered

1. Show tools only (current approach): Just list tools that will run

   • Rejected: Too technical, doesn't explain "why"

2. Post-execution summary: Show what was done after completion

   • Rejected: Too late to prevent unwanted changes

3. Always require explicit yes: Block every tool call

   • Rejected: Too tedious for simple tasks

4. Size-based planning: Only plan for "large" tasks

   • Rejected: Hard to determine size, all modifications should be transparent

Acceptance criteria

• When user requests build/modify operation, agent displays plan BEFORE executing tools
• Plan is generated by LLM (not hardcoded) based on user request
• Plan explains what will be done in user-friendly language
• User can approve plan with "yes", "ok", "build it", etc.
• User can modify plan by requesting changes
• User can cancel with "stop", "cancel", "no"
• Works across all channels (CLI, Signal, WhatsApp, etc.)
• Read-only operations (explain code, read files) skip plan step
• Plan is added to conversation history for reference
• Tests cover: approval, rejection, modification, read-only exemption

Architecture impact

• src/agent/agent.rs: Modify turn() to detect first write iteration and generate plan
• src/agent/prompt.rs: May need plan generation prompt template
• src/channels/: No changes, plan displayed as normal assistant message
• AGENTS.md: Update documentation for plan behavior

Risk and rollback

Main risk: User experience friction from additional step
Rollback: Remove plan check from agent loop or add config to disable
Quick disable: Set env var ZEROBUILD_SKIP_PLAN=1

Breaking change?

No - adds new behavior, doesn't change existing API

Data hygiene checks

• No personal data in examples
• Uses neutral "user" and "agent" terminology