Release v2.3.6

- Add planning_tools and planning_reasoning parameters to PraisonAIAgents
- Add RESEARCH_TOOLS list for safe planning research tools (web_search, read_file, etc.)
- Add tools, reasoning, and max_reasoning_steps parameters to PlanningAgent
- Add _get_agent() method to PlanningAgent for tool-enabled planning with Agent.chat()
- Update plan creation to use Agent with tools when available, fallback to bare LLM
- Add Planning

README.md

@@ -60,6 +60,9 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 - 💾 **Prompt Caching** (Reduce costs & latency - OpenAI, Anthropic, Bedrock, Deepseek)
 - 🧠 **Claude Memory Tool** (Persistent cross-conversation memory - Anthropic Beta)
 - 💾 **File-Based Memory** (Zero-dependency persistent memory for all agents)
+- 📋 **Planning Mode** (Plan before execution - Agent & Multi-Agent)
+- 🔧 **Planning Tools** (Research with tools during planning)
+- 🧠 **Planning Reasoning** (Chain-of-thought planning)
 
 ## Using Python Code
 
@@ -103,7 +106,34 @@ Run:
 python app.py
 ```
 
-### 3. Deep Research Agent
+### 3. Agent with Planning Mode
+
+Enable planning for any agent - the agent creates a plan, then executes step by step:
+
+```python
+from praisonaiagents import Agent
+
+def search_web(query: str) -> str:
+    return f"Search results for: {query}"
+
+agent = Agent(
+    name="AI Assistant",
+    instructions="Research and write about topics",
+    planning=True,              # Enable planning mode
+    planning_tools=[search_web], # Tools for planning research
+    planning_reasoning=True      # Chain-of-thought reasoning
+)
+
+result = agent.start("Research AI trends in 2025 and write a summary")
+```
+
+**What happens:**
+1. 📋 Agent creates a multi-step plan
+2. 🚀 Executes each step sequentially
+3. 📊 Shows progress with context passing
+4. ✅ Returns final result
+
+### 4. Deep Research Agent
 
 Automated research with real-time streaming, web search, and citations using OpenAI or Gemini Deep Research APIs.
 
@@ -141,7 +171,7 @@ print(result.report)
 - 🛠️ Built-in tools: web search, code interpreter, MCP, file search
 - 🔄 Automatic provider detection from model name
 
-### 4. Query Rewriter Agent
+### 5. Query Rewriter Agent
 
 Transform user queries to improve RAG retrieval quality using multiple strategies.
 
@@ -176,9 +206,9 @@ result = agent.rewrite("What about cost?", chat_history=[...])
 - **CONTEXTUAL**: Resolve references using conversation history
 - **AUTO**: Automatically detect best strategy
 
-### 5. Agent Memory (Zero Dependencies)
+### 6. Agent Memory (Zero Dependencies)
 
-Enable persistent memory for agents - works out of the box without any extra packages. Features inspired by Claude, Gemini CLI, Codex CLI, Cursor, and Windsurf.
+Enable persistent memory for agents - works out of the box without any extra packages.
 
 ```python
 from praisonaiagents import Agent
@@ -203,7 +233,7 @@ result = agent.start("My name is John and I prefer Python")
 - **Entity**: People, places, organizations with attributes
 - **Episodic**: Date-based interaction history
 
-**Advanced Features (like Gemini CLI):**
+**Advanced Features:**
 ```python
 from praisonaiagents.memory import FileMemory
 
@@ -233,7 +263,7 @@ memory.handle_command("/memory save my_session")
 | `memory="sqlite"` | Built-in | SQLite with indexing |
 | `memory="chromadb"` | chromadb | Vector/semantic search |
 
-### 6. Rules & Instructions (like Cursor/Windsurf)
+### 6. Rules & Instructions
 
 PraisonAI auto-discovers instruction files from your project root and git root:
 
@@ -261,7 +291,7 @@ agent = Agent(name="Assistant", instructions="You are helpful.")
 # Rules are injected into system prompt automatically
 ```
 
-**@Import Syntax (like Claude Code):**
+**@Import Syntax:**
 ```markdown
 # CLAUDE.md
 See @README for project overview
@@ -282,7 +312,7 @@ activation: always  # always, glob, manual, ai_decision
 - Follow PEP 8
 ```
 
-### 7. Auto-Generated Memories (like Windsurf Cascade)
+### 7. Auto-Generated Memories
 
 ```python
 from praisonaiagents.memory import FileMemory, AutoMemory
@@ -297,7 +327,7 @@ memories = auto.process_interaction(
 # Extracts: name="John", preference="Python for backend"
 ```
 
-### 8. Workflows (like Windsurf)
+### 8. Workflows
 
 Create reusable multi-step workflows in `.praison/workflows/`:
 
@@ -314,7 +344,7 @@ result = manager.execute(
 )
 ```
 
-### 9. Hooks (like Windsurf Cascade Hooks)
+### 9. Hooks
 
 Configure in `.praison/hooks.json`:
 

docker/Dockerfile

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     flask \
-    "praisonai>=2.3.4" \
+    "praisonai>=2.3.6" \
     "praisonai[api]" \
     gunicorn \
     markdown

docker/Dockerfile.chat

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.3.4" \
+    "praisonai>=2.3.6" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.3.4" \
+    "praisonai>=2.3.6" \
     "praisonai[ui]" \
     "praisonai[chat]" \
     "praisonai[realtime]" \

docker/Dockerfile.ui

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.3.4" \
+    "praisonai>=2.3.6" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

src/praisonai-agents/README.md

@@ -84,6 +84,64 @@ agents = PraisonAIAgents(agents=[researcher, writer], tasks=[research_task, writ
 result = agents.start()
 ```
 
+### Planning Mode 🆕
+
+#### Single Agent Planning (Simplest)
+
+Enable planning for any single agent:
+
+```python
+from praisonaiagents import Agent
+
+def search_web(query: str) -> str:
+    return f"Search results for: {query}"
+
+agent = Agent(
+    name="AI Assistant",
+    instructions="Research and write about topics",
+    planning=True,              # Enable planning mode
+    planning_tools=[search_web], # Tools for planning research
+    planning_reasoning=True      # Chain-of-thought reasoning
+)
+
+result = agent.start("Research AI trends in 2025 and write a summary")
+```
+
+#### Multi-Agent Planning
+
+Plan before execution with multiple agents:
+
+```python
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+researcher = Agent(name="Researcher", role="Research Analyst")
+writer = Agent(name="Writer", role="Content Writer")
+
+research_task = Task(description="Research AI benefits", agent=researcher)
+write_task = Task(description="Write summary", agent=writer)
+
+agents = PraisonAIAgents(
+    agents=[researcher, writer],
+    tasks=[research_task, write_task],
+    planning=True,              # Enable planning
+    planning_tools=[search_web], # Tools for planning research
+    planning_reasoning=True,     # Chain-of-thought reasoning
+    auto_approve_plan=True       # Auto-approve plans
+)
+
+result = agents.start()
+```
+
+**Features:**
+- **Single Agent Planning**: `Agent(planning=True)` - simplest API
+- **Multi-Agent Planning**: `PraisonAIAgents(planning=True)` - orchestrated
+- **Planning Tools**: Research with tools before creating plans
+- **Reasoning Mode**: Chain-of-thought planning with tool use
+- **Todo Lists**: Auto-generated from plans with progress tracking
+- **Read-Only Mode**: `plan_mode=True` restricts agents to safe tools
+- **Approval Flow**: Review and approve plans before execution
+- **Persistence**: Plans saved to `.praison/plans/` as markdown
+
 ---
 
 ## Agent Types
@@ -216,7 +274,7 @@ router = RouterAgent(
 
 ## Memory
 
-PraisonAI provides a comprehensive memory system with features inspired by Claude, Gemini CLI, Codex CLI, Cursor, and Windsurf.
+PraisonAI provides a comprehensive memory system.
 
 ### Quick Start (Zero Dependencies)
 
@@ -261,7 +319,7 @@ agent = Agent(name="Memory Agent", memory=memory)
 | **Episodic** | Date-based interaction memories | JSON files |
 | **Graph** | Relationship-based memory | Mem0/Neo4j |
 
-### Session Save/Resume (like Gemini CLI)
+### Session Save/Resume
 
 ```python
 from praisonaiagents.memory import FileMemory
@@ -282,7 +340,7 @@ session_data = memory.resume_session("ml_project")
 sessions = memory.list_sessions()
 ```
 
-### Context Compression (like Gemini CLI)
+### Context Compression
 
 ```python
 # Auto-compress when memory gets full
@@ -295,7 +353,7 @@ def llm_summarize(prompt):
 summary = memory.compress(llm_func=llm_summarize, max_items=10)
 ```
 
-### Checkpointing (like Gemini CLI)
+### Checkpointing
 
 ```python
 # Create checkpoint before risky operations
@@ -337,9 +395,9 @@ result = memory.handle_command("/memory help")
 
 ---
 
-## Rules & Instructions (like Cursor/Windsurf)
+## Rules & Instructions
 
-PraisonAI automatically discovers and applies rules from multiple sources, similar to Cursor, Windsurf, Claude Code, and Codex CLI.
+PraisonAI automatically discovers and applies rules from multiple sources.
 
 ### Supported Instruction Files
 
@@ -462,7 +520,7 @@ project/
         └── global.md
 ```
 
-### @Import Syntax (like Claude Code)
+### @Import Syntax
 
 Include other files in your rules:
 
@@ -473,7 +531,7 @@ See @docs/architecture.md for system design
 @~/.praison/my-preferences.md
 ```
 
-### Auto-Generated Memories (like Windsurf Cascade)
+### Auto-Generated Memories
 
 ```python
 from praisonaiagents.memory import FileMemory, AutoMemory
@@ -488,7 +546,7 @@ memories = auto.process_interaction(
 # Extracts: name="John", preference="Python for backend"
 ```
 
-### Workflows (like Windsurf)
+### Workflows
 
 Create reusable multi-step workflows:
 
@@ -505,7 +563,7 @@ result = manager.execute(
 )
 ```
 
-### Hooks (like Windsurf Cascade Hooks)
+### Hooks
 
 ```python
 from praisonaiagents.memory import HooksManager

src/praisonai-agents/planning_example.py

@@ -0,0 +1,34 @@
+"""Simple Planning Mode Example: Plan first, then execute todo items."""
+
+from praisonaiagents import Agent
+from praisonaiagents.planning import PlanningAgent, TodoList
+
+# Step 1: Create agents
+researcher = Agent(name="Researcher", role="Research Analyst", verbose=True)
+writer = Agent(name="Writer", role="Content Writer", verbose=True)
+
+# Step 2: Create a plan using PlanningAgent
+planner = PlanningAgent(llm="gpt-4o-mini", verbose=1)
+plan = planner.create_plan_sync(
+    request="Write a short article about the top 3 benefits of meditation",
+    agents=[researcher, writer],
+    context="Keep it concise"
+)
+
+# Step 3: Create todo list from the plan
+todo = TodoList.from_plan(plan)
+
+# Step 4: Execute each todo item one by one
+for item in todo.items:
+    todo.start(item.id)
+    
+    # Pick the right agent based on the item's assigned agent
+    if item.agent == "Researcher":
+        agent = researcher
+    else:
+        agent = writer
+    
+    # Execute the task
+    result = agent.chat(item.description)
+    
+    todo.complete(item.id)

src/praisonai-agents/planning_simple.py

@@ -0,0 +1,21 @@
+"""Simplest Planning Mode Example - Just enable planning=True"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+# Create agents
+researcher = Agent(name="Researcher", role="Research Analyst")
+writer = Agent(name="Writer", role="Content Writer")
+
+# Create tasks
+task1 = Task(description="Research the benefits of meditation", agent=researcher)
+task2 = Task(description="Write a short article about meditation benefits", agent=writer)
+
+# Run with planning enabled - that's it!
+agents = PraisonAIAgents(
+    agents=[researcher, writer],
+    tasks=[task1, task2],
+    planning=True,
+    auto_approve_plan=True  # Auto-approve the generated plan
+)
+
+agents.start()

src/praisonai-agents/praisonaiagents/__init__.py

@@ -55,6 +55,32 @@ except ImportError:
 from .session import Session
 from .memory.memory import Memory
 from .guardrails import GuardrailResult, LLMGuardrail
+
+# Planning mode support
+try:
+    from .planning import (
+        Plan,
+        PlanStep,
+        TodoList,
+        TodoItem,
+        PlanStorage,
+        PlanningAgent,
+        ApprovalCallback,
+        READ_ONLY_TOOLS,
+        RESTRICTED_TOOLS,
+    )
+    _planning_available = True
+except ImportError:
+    _planning_available = False
+    Plan = None
+    PlanStep = None
+    TodoList = None
+    TodoItem = None
+    PlanStorage = None
+    PlanningAgent = None
+    ApprovalCallback = None
+    READ_ONLY_TOOLS = []
+    RESTRICTED_TOOLS = []
 from .agent.handoff import Handoff, handoff, handoff_filters, RECOMMENDED_PROMPT_PREFIX, prompt_with_handoff_instructions
 # Flow display
 try:

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -238,7 +238,11 @@ class Agent:
         web_search: Optional[Union[bool, Dict[str, Any]]] = None,
         web_fetch: Optional[Union[bool, Dict[str, Any]]] = None,
         prompt_caching: Optional[bool] = None,
-        claude_memory: Optional[Union[bool, Any]] = None
+        claude_memory: Optional[Union[bool, Any]] = None,
+        plan_mode: bool = False,
+        planning: bool = False,
+        planning_tools: Optional[List[Any]] = None,
+        planning_reasoning: bool = False
     ):
         """Initialize an Agent instance.
 
@@ -524,6 +528,11 @@ Your Goal: {self.goal}
         # Store user_id
         self.user_id = user_id or "praison"
         self.reasoning_steps = reasoning_steps
+        self.plan_mode = plan_mode  # Read-only mode for planning
+        self.planning = planning  # Enable planning mode
+        self.planning_tools = planning_tools  # Tools for planning phase
+        self.planning_reasoning = planning_reasoning  # Enable reasoning during planning
+        self._planning_agent = None  # Lazy loaded PlanningAgent
         self.web_search = web_search
         self.web_fetch = web_fetch
         self.prompt_caching = prompt_caching
@@ -610,6 +619,37 @@ Your Goal: {self.goal}
             self._agent_id = str(uuid.uuid4())
         return self._agent_id
     
+    def get_available_tools(self) -> List[Any]:
+        """
+        Get tools available to this agent, filtered by plan_mode if enabled.
+        
+        In plan_mode, only read-only tools are available to prevent
+        modifications during the planning phase.
+        
+        Returns:
+            List of available tools
+        """
+        if not self.plan_mode:
+            return self.tools
+            
+        # Filter to read-only tools only
+        from ..planning import READ_ONLY_TOOLS, RESTRICTED_TOOLS
+        
+        filtered_tools = []
+        for tool in self.tools:
+            tool_name = getattr(tool, '__name__', str(tool)).lower()
+            
+            # Check if tool is in restricted list
+            is_restricted = any(
+                restricted.lower() in tool_name 
+                for restricted in RESTRICTED_TOOLS
+            )
+            
+            if not is_restricted:
+                filtered_tools.append(tool)
+                
+        return filtered_tools
+    
     def _model_supports_web_search(self) -> bool:
         """
         Check if the agent's model supports native web search via LiteLLM.
@@ -2459,10 +2499,88 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
 
     def run(self, prompt: str, **kwargs):
         """Alias for start() method"""
-        return self.start(prompt, **kwargs) 
+        return self.start(prompt, **kwargs)
+    
+    def _get_planning_agent(self):
+        """Lazy load PlanningAgent for planning mode."""
+        if self._planning_agent is None and self.planning:
+            from ..planning import PlanningAgent
+            self._planning_agent = PlanningAgent(
+                llm=self.llm if hasattr(self, 'llm') else (self.llm_instance.model if hasattr(self, 'llm_instance') else "gpt-4o-mini"),
+                tools=self.planning_tools,
+                reasoning=self.planning_reasoning,
+                verbose=1 if self.verbose else 0
+            )
+        return self._planning_agent
+    
+    def _start_with_planning(self, prompt: str, **kwargs):
+        """Execute with planning mode - creates plan then executes each step."""
+        from rich.console import Console
+        from rich.panel import Panel
+        from rich.markdown import Markdown
+        
+        console = Console()
+        
+        # Step 1: Create the plan
+        console.print("\n[bold blue]📋 PLANNING PHASE[/bold blue]")
+        console.print("[dim]Creating implementation plan...[/dim]\n")
+        
+        planner = self._get_planning_agent()
+        plan = planner.create_plan_sync(request=prompt, agents=[self])
+        
+        if not plan or not plan.steps:
+            console.print("[yellow]⚠️ Planning failed, falling back to direct execution[/yellow]")
+            return self.chat(prompt, **kwargs)
+        
+        # Display the plan
+        console.print(Panel(
+            Markdown(plan.to_markdown()),
+            title="[bold green]Generated Plan[/bold green]",
+            border_style="green"
+        ))
+        
+        # Step 2: Execute each step
+        console.print("\n[bold blue]🚀 EXECUTION PHASE[/bold blue]\n")
+        
+        results = []
+        context = ""
+        
+        for i, step in enumerate(plan.steps):
+            progress = (i + 1) / len(plan.steps)
+            bar_length = 30
+            filled = int(bar_length * progress)
+            bar = "█" * filled + "░" * (bar_length - filled)
+            
+            console.print(f"[dim]Progress: [{bar}] {progress * 100:.0f}%[/dim]")
+            console.print(f"\n[bold]📌 Step {i + 1}/{len(plan.steps)}:[/bold] {step.description[:60]}...")
+            
+            # Build prompt with context from previous steps
+            step_prompt = step.description
+            if context:
+                step_prompt = f"{step.description}\n\nContext from previous steps:\n{context}"
+            
+            # Execute the step
+            result = self.chat(step_prompt, **kwargs)
+            results.append(result)
+            
+            # Update context for next step
+            context += f"\n\nStep {i + 1} result: {result[:500] if result else 'No result'}"
+            
+            console.print(f"   [green]✅ Completed[/green]")
+        
+        console.print(f"\n[bold green]🎉 EXECUTION COMPLETE[/bold green]")
+        console.print(f"[dim]Progress: [{'█' * bar_length}] 100%[/dim]")
+        console.print(f"Completed {len(plan.steps)}/{len(plan.steps)} steps!\n")
+        
+        # Return the final result
+        return results[-1] if results else None
 
     def start(self, prompt: str, **kwargs):
         """Start the agent with a prompt. This is a convenience method that wraps chat()."""
+        # Check if planning mode is enabled
+        if self.planning:
+            return self._start_with_planning(prompt, **kwargs)
+        
         # Check if streaming is enabled (either from kwargs or agent's stream attribute)
         stream_enabled = kwargs.get('stream', getattr(self, 'stream', False))
         

src/praisonai-agents/praisonaiagents/agents/agents.py

@@ -127,7 +127,7 @@ def process_task_context(context_item, verbose=0, user_id=None):
         return str(context_item)  # Fallback for unknown types
 
 class PraisonAIAgents:
-    def __init__(self, agents, tasks=None, verbose=0, completion_checker=None, max_retries=5, process="sequential", manager_llm=None, memory=False, memory_config=None, embedder=None, user_id=None, max_iter=10, stream=True, name: Optional[str] = None):
+    def __init__(self, agents, tasks=None, verbose=0, completion_checker=None, max_retries=5, process="sequential", manager_llm=None, memory=False, memory_config=None, embedder=None, user_id=None, max_iter=10, stream=True, name: Optional[str] = None, planning: bool = False, planning_llm: Optional[str] = None, auto_approve_plan: bool = False, planning_tools: Optional[List] = None, planning_reasoning: bool = False):
         # Add check at the start if memory is requested
         if memory:
             try:
@@ -213,6 +213,16 @@ class PraisonAIAgents:
         
         self._state = {}  # Add state storage at PraisonAIAgents level
         
+        # Initialize planning mode
+        self.planning = planning
+        self.planning_llm = planning_llm or "gpt-4o-mini"
+        self.auto_approve_plan = auto_approve_plan
+        self.planning_tools = planning_tools
+        self.planning_reasoning = planning_reasoning
+        self._current_plan = None
+        self._todo_list = None
+        self._planning_agent = None
+        
         # Initialize memory system
         self.shared_memory = None
         if memory:
@@ -929,9 +939,13 @@ Context:
                         task.context = []
                     # Add content to context
                     task.context.append(content)
-                
-        # Run tasks as before
-        self.run_all_tasks()
+        
+        # Planning Mode: Create plan and todo list before execution
+        if self.planning:
+            self._run_with_planning()
+        else:
+            # Run tasks as before
+            self.run_all_tasks()
         
         # Auto-display token metrics if any agent has metrics=True
         metrics_enabled = any(getattr(agent, 'metrics', False) for agent in self.agents)
@@ -1532,3 +1546,354 @@ Context:
         else:
             display_error(f"Invalid protocol: {protocol}. Choose 'http' or 'mcp'.")
             return None
+
+    # =========================================================================
+    # Planning Mode Properties and Methods
+    # =========================================================================
+    
+    @property
+    def current_plan(self):
+        """Get the current plan."""
+        return self._current_plan
+    
+    @property
+    def todo_list(self):
+        """Get the current todo list."""
+        return self._todo_list
+    
+    def _get_planning_agent(self):
+        """Lazy load PlanningAgent."""
+        if self._planning_agent is None and self.planning:
+            from ..planning import PlanningAgent
+            self._planning_agent = PlanningAgent(
+                llm=self.planning_llm,
+                read_only=True,
+                verbose=self.verbose,
+                tools=self.planning_tools,
+                reasoning=self.planning_reasoning
+            )
+        return self._planning_agent
+    
+    async def _create_plan(self, request: str = None, context: str = None):
+        """
+        Create an implementation plan.
+        
+        Args:
+            request: The request/goal to plan for
+            context: Optional additional context
+            
+        Returns:
+            Plan instance
+        """
+        planner = self._get_planning_agent()
+        if planner is None:
+            return None
+            
+        # Use first task description as request if not provided
+        if request is None and self.tasks:
+            first_task = list(self.tasks.values())[0]
+            request = first_task.description
+            
+        plan = await planner.create_plan(
+            request=request,
+            agents=self.agents,
+            tasks=list(self.tasks.values()),
+            context=context
+        )
+        
+        self._current_plan = plan
+        
+        # Create todo list from plan
+        from ..planning import TodoList
+        self._todo_list = TodoList.from_plan(plan)
+        
+        return plan
+    
+    def _create_plan_sync(self, request: str = None, context: str = None):
+        """
+        Synchronous version of _create_plan.
+        
+        Args:
+            request: The request/goal to plan for
+            context: Optional additional context
+            
+        Returns:
+            Plan instance
+        """
+        planner = self._get_planning_agent()
+        if planner is None:
+            return None
+            
+        # Use first task description as request if not provided
+        if request is None and self.tasks:
+            first_task = list(self.tasks.values())[0]
+            request = first_task.description
+            
+        plan = planner.create_plan_sync(
+            request=request,
+            agents=self.agents,
+            tasks=list(self.tasks.values()),
+            context=context
+        )
+        
+        self._current_plan = plan
+        
+        # Create todo list from plan
+        from ..planning import TodoList
+        self._todo_list = TodoList.from_plan(plan)
+        
+        return plan
+    
+    async def _request_approval(self, plan):
+        """
+        Request approval for a plan.
+        
+        Args:
+            plan: Plan to approve
+            
+        Returns:
+            True if approved, False if rejected
+        """
+        if self.auto_approve_plan:
+            plan.approve()
+            return True
+            
+        from ..planning import ApprovalCallback
+        callback = ApprovalCallback(auto_approve=self.auto_approve_plan)
+        return await callback.async_call(plan)
+    
+    def _request_approval_sync(self, plan):
+        """
+        Synchronous version of _request_approval.
+        
+        Args:
+            plan: Plan to approve
+            
+        Returns:
+            True if approved, False if rejected
+        """
+        if self.auto_approve_plan:
+            plan.approve()
+            return True
+            
+        from ..planning import ApprovalCallback
+        callback = ApprovalCallback(auto_approve=self.auto_approve_plan)
+        return callback(plan)
+    
+    def get_plan_markdown(self) -> str:
+        """
+        Get the current plan as markdown.
+        
+        Returns:
+            Markdown string or empty string if no plan
+        """
+        if self._current_plan:
+            return self._current_plan.to_markdown()
+        return ""
+    
+    def get_todo_markdown(self) -> str:
+        """
+        Get the current todo list as markdown.
+        
+        Returns:
+            Markdown string or empty string if no todo list
+        """
+        if self._todo_list:
+            return self._todo_list.to_markdown()
+        return ""
+    
+    def update_plan_step_status(self, step_id: str, status: str) -> bool:
+        """
+        Update the status of a plan step.
+        
+        Args:
+            step_id: ID of the step to update
+            status: New status
+            
+        Returns:
+            True if updated, False if not found
+        """
+        if self._current_plan:
+            result = self._current_plan.update_step_status(step_id, status)
+            # Sync todo list
+            if self._todo_list:
+                self._todo_list.sync_with_plan(self._current_plan)
+            return result
+        return False
+    
+    def _run_with_planning(self):
+        """
+        Run tasks with planning mode enabled.
+        
+        This method:
+        1. Creates a plan using PlanningAgent
+        2. Generates a todo list from the plan
+        3. Creates proper Task objects from plan steps
+        4. Executes each task using the full Task execution system
+           (with memory, callbacks, guardrails, structured output, etc.)
+        5. Tracks progress as items are completed
+        """
+        from rich.console import Console
+        from rich.panel import Panel
+        from rich.markdown import Markdown
+        from ..task import Task
+        
+        console = Console()
+        
+        # Step 1: Create the plan
+        console.print("\n[bold blue]📋 PLANNING PHASE[/bold blue]")
+        console.print("[dim]Creating implementation plan...[/dim]\n")
+        
+        # Build request from tasks
+        task_descriptions = [task.description for task in self.tasks.values()]
+        request = " AND ".join(task_descriptions)
+        
+        plan = self._create_plan_sync(request=request)
+        
+        if not plan:
+            console.print("[yellow]⚠️ Planning failed, falling back to normal execution[/yellow]")
+            self.run_all_tasks()
+            return
+        
+        # Display the plan
+        console.print(Panel(
+            Markdown(plan.to_markdown()),
+            title="[bold green]Generated Plan[/bold green]",
+            border_style="green"
+        ))
+        
+        # Step 2: Request approval if not auto-approve
+        if not self.auto_approve_plan:
+            approved = self._request_approval_sync(plan)
+            if not approved:
+                console.print("[red]❌ Plan rejected. Aborting execution.[/red]")
+                return
+        else:
+            plan.approve()
+            console.print("[green]✅ Plan auto-approved[/green]")
+        
+        # Step 3: Create todo list for tracking
+        from ..planning import TodoList
+        self._todo_list = TodoList.from_plan(plan)
+        
+        console.print("\n[bold blue]📝 TODO LIST[/bold blue]")
+        console.print(Panel(
+            Markdown(self._todo_list.to_markdown()),
+            title="[bold cyan]Tasks to Complete[/bold cyan]",
+            border_style="cyan"
+        ))
+        
+        # Step 4: Create proper Task objects from plan steps
+        console.print("\n[bold blue]🚀 EXECUTION PHASE[/bold blue]\n")
+        
+        # Map agent names to agent instances
+        agent_map = {agent.name: agent for agent in self.agents}
+        
+        # Store original tasks and create new tasks from plan
+        original_tasks = self.tasks.copy()
+        self.tasks = {}
+        self.task_id_counter = 0
+        
+        # Create Task objects from plan steps
+        plan_tasks = []
+        step_to_task = {}  # Map step_id to task for context chaining
+        
+        for i, step in enumerate(plan.steps):
+            # Get the appropriate agent
+            agent = agent_map.get(step.agent, self.agents[0] if self.agents else None)
+            
+            if not agent:
+                console.print(f"[yellow]⚠️ No agent found for '{step.agent}', using first available[/yellow]")
+                agent = self.agents[0] if self.agents else None
+            
+            if not agent:
+                console.print(f"[red]❌ No agents available for step: {step.description}[/red]")
+                continue
+            
+            # Build context from dependencies (previous task results)
+            context = []
+            for dep_id in step.dependencies:
+                # Convert step_X format to actual step index
+                if dep_id.startswith("step_"):
+                    try:
+                        dep_index = int(dep_id.split("_")[1])
+                        if dep_index < len(plan_tasks):
+                            context.append(plan_tasks[dep_index])
+                    except (ValueError, IndexError):
+                        pass
+                elif dep_id in step_to_task:
+                    context.append(step_to_task[dep_id])
+            
+            # Find matching original task for additional config (memory, callbacks, etc.)
+            original_task = None
+            for orig_task in original_tasks.values():
+                if orig_task.agent and orig_task.agent.name == agent.name:
+                    original_task = orig_task
+                    break
+            
+            # Create Task with full features from original task if available
+            task = Task(
+                description=step.description,
+                expected_output=f"Complete: {step.description}",
+                agent=agent,
+                name=f"Plan Step {i + 1}",
+                tools=agent.tools if agent.tools else [],
+                context=context if context else None,
+                # Inherit from original task if available
+                memory=original_task.memory if original_task else None,
+                callback=original_task.callback if original_task else None,
+                guardrail=original_task.guardrail if original_task else None,
+                max_retries=original_task.max_retries if original_task else 3,
+                output_json=original_task.output_json if original_task else None,
+                output_pydantic=original_task.output_pydantic if original_task else None,
+                config=original_task.config if original_task else {}
+            )
+            
+            # Add task to our task list
+            task_id = self.add_task(task)
+            plan_tasks.append(task)
+            step_to_task[step.id] = task
+        
+        # Step 5: Execute tasks using the proper Task execution system
+        for i, (task_id, task) in enumerate(self.tasks.items()):
+            # Update todo list progress
+            if i < len(self._todo_list.items):
+                item = self._todo_list.items[i]
+                
+                # Display progress bar
+                progress = self._todo_list.progress
+                bar_length = 30
+                filled = int(bar_length * progress)
+                bar = "█" * filled + "░" * (bar_length - filled)
+                console.print(f"[dim]Progress: [{bar}] {progress * 100:.0f}%[/dim]")
+                
+                console.print(f"\n[bold]📌 Step {i + 1}/{len(self.tasks)}:[/bold] {task.description[:60]}...")
+                console.print(f"[dim]   Agent: {task.agent.name if task.agent else 'Unknown'}[/dim]")
+                
+                # Mark as in progress
+                self._todo_list.start(item.id)
+            
+            # Execute using the full Task execution system
+            # This includes: memory, callbacks, guardrails, structured output, retry logic
+            try:
+                self.run_task(task_id)
+                
+                if task.status == "completed":
+                    if i < len(self._todo_list.items):
+                        self._todo_list.complete(self._todo_list.items[i].id)
+                    console.print("[green]   ✅ Completed[/green]")
+                else:
+                    console.print(f"[yellow]   ⚠️ Task status: {task.status}[/yellow]")
+            except Exception as e:
+                console.print(f"[red]   ❌ Error: {e}[/red]")
+                logger.error(f"Error executing plan task {task_id}: {e}")
+        
+        # Final progress
+        completed_count = len([t for t in self.tasks.values() if t.status == "completed"])
+        console.print(f"\n[bold green]🎉 EXECUTION COMPLETE[/bold green]")
+        console.print(f"[dim]Progress: [{'█' * 30}] 100%[/dim]")
+        console.print(f"[green]Completed {completed_count}/{len(self.tasks)} tasks![/green]\n")
+        
+        # Restore original tasks reference for result retrieval
+        self._plan_tasks = self.tasks.copy()
+        # Keep plan tasks for results but note original tasks are preserved in _plan_tasks

src/praisonai-agents/praisonaiagents/planning/__init__.py

@@ -0,0 +1,104 @@
+"""
+Planning Module for PraisonAI Agents.
+
+Provides Planning Mode functionality similar to:
+- Cursor Plan Mode
+- Windsurf Planning Mode  
+- Claude Code Plan Mode
+- Gemini CLI Plan Mode
+- Codex CLI /plan command
+
+Features:
+- PlanningAgent for creating implementation plans
+- Plan and PlanStep dataclasses for plan structure
+- TodoList for tracking progress
+- PlanStorage for persistence
+- ApprovalCallback for plan approval flow
+- Read-only mode for safe research
+
+Usage:
+    from praisonaiagents import Agent, Task, PraisonAIAgents
+    
+    agents = PraisonAIAgents(
+        agents=[agent1, agent2],
+        tasks=[task1, task2],
+        planning=True,           # Enable planning mode
+        planning_llm="gpt-4o-mini"  # Optional: custom LLM
+    )
+    
+    result = agents.start()
+"""
+
+from .plan import Plan, PlanStep
+from .todo import TodoList, TodoItem
+from .storage import PlanStorage
+from .planner import PlanningAgent
+from .approval import ApprovalCallback
+
+# Read-only tools that are allowed in plan mode
+READ_ONLY_TOOLS = [
+    "read_file",
+    "list_directory",
+    "search_codebase",
+    "search_files",
+    "grep_search",
+    "find_files",
+    "web_search",
+    "get_file_content",
+    "list_files",
+    "read_document",
+    "search_web",
+    "fetch_url",
+    "get_context",
+]
+
+# Restricted tools that are blocked in plan mode
+RESTRICTED_TOOLS = [
+    "write_file",
+    "create_file",
+    "delete_file",
+    "execute_command",
+    "run_command",
+    "shell_command",
+    "modify_file",
+    "edit_file",
+    "remove_file",
+    "move_file",
+    "copy_file",
+    "mkdir",
+    "rmdir",
+    "git_commit",
+    "git_push",
+    "npm_install",
+    "pip_install",
+]
+
+# Research tools that are safe for planning research
+RESEARCH_TOOLS = [
+    "web_search",
+    "search_web",
+    "duckduckgo_search",
+    "tavily_search",
+    "brave_search",
+    "google_search",
+    "read_url",
+    "fetch_url",
+    "read_file",
+    "list_directory",
+    "search_codebase",
+    "grep_search",
+    "find_files",
+]
+
+__all__ = [
+    "Plan",
+    "PlanStep",
+    "TodoList",
+    "TodoItem",
+    "PlanStorage",
+    "PlanningAgent",
+    "ApprovalCallback",
+    "READ_ONLY_TOOLS",
+    "RESTRICTED_TOOLS",
+    "RESEARCH_TOOLS",
+]

src/praisonai-agents/praisonaiagents/planning/approval.py

@@ -0,0 +1,274 @@
+"""
+ApprovalCallback for plan approval flow.
+
+Provides approval functionality similar to:
+- Cursor Plan Mode approval
+- Claude Code plan approval
+- Codex CLI /approvals
+
+Features:
+- Auto-approve option
+- Custom approval functions
+- Async support
+- Plan modification during approval
+"""
+
+import asyncio
+import inspect
+import logging
+from typing import Callable, Optional, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .plan import Plan
+
+logger = logging.getLogger(__name__)
+
+
+class ApprovalCallback:
+    """
+    Callback for plan approval flow.
+    
+    Handles the approval process for plans before execution.
+    Can be configured for auto-approval or custom approval logic.
+    
+    Attributes:
+        auto_approve: Whether to automatically approve all plans
+        approve_fn: Custom approval function
+        on_reject: Callback when plan is rejected
+    """
+    
+    def __init__(
+        self,
+        auto_approve: bool = False,
+        approve_fn: Optional[Callable[['Plan'], Union[bool, 'asyncio.Future']]] = None,
+        on_reject: Optional[Callable[['Plan'], None]] = None
+    ):
+        """
+        Initialize ApprovalCallback.
+        
+        Args:
+            auto_approve: If True, automatically approve all plans
+            approve_fn: Custom function to determine approval
+                       Should return True to approve, False to reject
+                       Can be sync or async
+            on_reject: Optional callback when plan is rejected
+        """
+        self.auto_approve = auto_approve
+        self.approve_fn = approve_fn
+        self.on_reject = on_reject
+        
+    def __call__(self, plan: 'Plan') -> bool:
+        """
+        Synchronously check if plan is approved.
+        
+        Args:
+            plan: Plan to check for approval
+            
+        Returns:
+            True if approved, False if rejected
+        """
+        if self.auto_approve:
+            logger.debug(f"Auto-approving plan: {plan.name}")
+            plan.approve()
+            return True
+            
+        if self.approve_fn is not None:
+            # Check if function is async
+            if inspect.iscoroutinefunction(self.approve_fn):
+                # Run async function synchronously
+                loop = asyncio.new_event_loop()
+                try:
+                    result = loop.run_until_complete(self.approve_fn(plan))
+                finally:
+                    loop.close()
+            else:
+                result = self.approve_fn(plan)
+                
+            if result:
+                plan.approve()
+                return True
+            else:
+                if self.on_reject:
+                    self.on_reject(plan)
+                return False
+                
+        # Default: require explicit approval (return False)
+        logger.debug(f"Plan requires explicit approval: {plan.name}")
+        return False
+    
+    async def async_call(self, plan: 'Plan') -> bool:
+        """
+        Asynchronously check if plan is approved.
+        
+        Args:
+            plan: Plan to check for approval
+            
+        Returns:
+            True if approved, False if rejected
+        """
+        if self.auto_approve:
+            logger.debug(f"Auto-approving plan: {plan.name}")
+            plan.approve()
+            return True
+            
+        if self.approve_fn is not None:
+            # Check if function is async
+            if inspect.iscoroutinefunction(self.approve_fn):
+                result = await self.approve_fn(plan)
+            else:
+                result = self.approve_fn(plan)
+                
+            if result:
+                plan.approve()
+                return True
+            else:
+                if self.on_reject:
+                    self.on_reject(plan)
+                return False
+                
+        # Default: require explicit approval (return False)
+        logger.debug(f"Plan requires explicit approval: {plan.name}")
+        return False
+    
+    @staticmethod
+    def console_approval(plan: 'Plan') -> bool:
+        """
+        Interactive console approval.
+        
+        Displays the plan and prompts for approval.
+        
+        Args:
+            plan: Plan to approve
+            
+        Returns:
+            True if user approves, False otherwise
+        """
+        print("\n" + "=" * 60)
+        print("PLAN APPROVAL REQUIRED")
+        print("=" * 60)
+        print(plan.to_markdown())
+        print("=" * 60)
+        
+        while True:
+            response = input("\nApprove this plan? [y/n/e(dit)]: ").strip().lower()
+            
+            if response in ['y', 'yes']:
+                return True
+            elif response in ['n', 'no']:
+                return False
+            elif response in ['e', 'edit']:
+                print("\nPlan editing not implemented in console mode.")
+                print("Please modify the plan programmatically and re-submit.")
+                continue
+            else:
+                print("Please enter 'y' for yes, 'n' for no, or 'e' to edit.")
+                
+    @staticmethod
+    def always_approve(plan: 'Plan') -> bool:
+        """Always approve plans."""
+        return True
+    
+    @staticmethod
+    def always_reject(plan: 'Plan') -> bool:
+        """Always reject plans."""
+        return False
+    
+    @staticmethod
+    def approve_if_small(plan: 'Plan', max_steps: int = 5) -> bool:
+        """
+        Approve plans with few steps automatically.
+        
+        Args:
+            plan: Plan to check
+            max_steps: Maximum number of steps to auto-approve
+            
+        Returns:
+            True if plan has <= max_steps
+        """
+        return len(plan.steps) <= max_steps
+    
+    @staticmethod
+    def approve_if_no_dangerous_tools(plan: 'Plan') -> bool:
+        """
+        Approve plans that don't use dangerous tools.
+        
+        Args:
+            plan: Plan to check
+            
+        Returns:
+            True if no dangerous tools are used
+        """
+        from . import RESTRICTED_TOOLS
+        
+        for step in plan.steps:
+            for tool in step.tools:
+                if tool in RESTRICTED_TOOLS:
+                    logger.warning(f"Plan uses restricted tool: {tool}")
+                    return False
+                    
+        return True
+
+
+class InteractiveApproval:
+    """
+    Interactive approval handler with rich UI support.
+    
+    Provides a more sophisticated approval interface
+    with plan editing capabilities.
+    """
+    
+    def __init__(self, use_rich: bool = True):
+        """
+        Initialize InteractiveApproval.
+        
+        Args:
+            use_rich: Whether to use Rich library for display
+        """
+        self.use_rich = use_rich
+        self._rich_available = False
+        
+        if use_rich:
+            try:
+                from rich.console import Console
+                from rich.panel import Panel
+                from rich.prompt import Confirm
+                self._rich_available = True
+                self._console = Console()
+            except ImportError:
+                self._rich_available = False
+                
+    def __call__(self, plan: 'Plan') -> bool:
+        """
+        Display plan and get approval.
+        
+        Args:
+            plan: Plan to approve
+            
+        Returns:
+            True if approved
+        """
+        if self._rich_available:
+            return self._rich_approval(plan)
+        else:
+            return ApprovalCallback.console_approval(plan)
+            
+    def _rich_approval(self, plan: 'Plan') -> bool:
+        """Rich library approval display."""
+        from rich.panel import Panel
+        from rich.prompt import Confirm
+        from rich.markdown import Markdown
+        
+        # Display plan
+        md = Markdown(plan.to_markdown())
+        self._console.print(Panel(md, title="[bold blue]Plan Approval Required[/bold blue]"))
+        
+        # Get approval
+        approved = Confirm.ask("Approve this plan?")
+        
+        return approved
+    
+    async def async_call(self, plan: 'Plan') -> bool:
+        """Async version of approval."""
+        # For now, just call sync version
+        # Could be extended for async UI frameworks
+        return self(plan)

src/praisonai-agents/praisonaiagents/planning/plan.py

@@ -0,0 +1,364 @@
+"""
+Plan and PlanStep dataclasses for Planning Mode.
+
+Provides structured representation of implementation plans
+with support for:
+- Step dependencies
+- Status tracking
+- Markdown serialization
+- Progress calculation
+"""
+
+import uuid
+import re
+import yaml
+import logging
+from datetime import datetime
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any, Literal
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PlanStep:
+    """
+    A single step in an implementation plan.
+    
+    Attributes:
+        id: Unique identifier for the step
+        description: What this step does
+        agent: Name of the agent to execute this step
+        tools: List of tools needed for this step
+        dependencies: List of step IDs that must complete first
+        status: Current status (pending, in_progress, completed, skipped)
+        estimated_tokens: Estimated token usage for this step
+    """
+    description: str
+    id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    agent: Optional[str] = None
+    tools: List[str] = field(default_factory=list)
+    dependencies: List[str] = field(default_factory=list)
+    status: Literal["pending", "in_progress", "completed", "skipped"] = "pending"
+    estimated_tokens: int = 0
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert PlanStep to dictionary."""
+        return {
+            "id": self.id,
+            "description": self.description,
+            "agent": self.agent,
+            "tools": self.tools,
+            "dependencies": self.dependencies,
+            "status": self.status,
+            "estimated_tokens": self.estimated_tokens
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'PlanStep':
+        """Create PlanStep from dictionary."""
+        return cls(
+            id=data.get("id", str(uuid.uuid4())[:8]),
+            description=data.get("description", ""),
+            agent=data.get("agent"),
+            tools=data.get("tools", []),
+            dependencies=data.get("dependencies", []),
+            status=data.get("status", "pending"),
+            estimated_tokens=data.get("estimated_tokens", 0)
+        )
+    
+    def mark_complete(self) -> None:
+        """Mark this step as completed."""
+        self.status = "completed"
+        
+    def mark_in_progress(self) -> None:
+        """Mark this step as in progress."""
+        self.status = "in_progress"
+        
+    def mark_skipped(self) -> None:
+        """Mark this step as skipped."""
+        self.status = "skipped"
+        
+    def is_ready(self, completed_steps: List[str]) -> bool:
+        """
+        Check if this step is ready to execute.
+        
+        Args:
+            completed_steps: List of completed step IDs
+            
+        Returns:
+            True if all dependencies are satisfied
+        """
+        if self.status != "pending":
+            return False
+        return all(dep in completed_steps for dep in self.dependencies)
+
+
+@dataclass
+class Plan:
+    """
+    An implementation plan with multiple steps.
+    
+    Attributes:
+        id: Unique identifier for the plan
+        name: Human-readable name
+        description: Detailed description of what the plan accomplishes
+        steps: List of PlanStep objects
+        status: Current status (draft, approved, executing, completed)
+        created_at: When the plan was created
+        approved_at: When the plan was approved (if applicable)
+        file_path: Path where the plan is stored (if saved)
+    """
+    name: str
+    id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    description: str = ""
+    steps: List[PlanStep] = field(default_factory=list)
+    status: Literal["draft", "approved", "executing", "completed", "cancelled"] = "draft"
+    created_at: datetime = field(default_factory=datetime.now)
+    approved_at: Optional[datetime] = None
+    file_path: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert Plan to dictionary."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "steps": [step.to_dict() for step in self.steps],
+            "status": self.status,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "approved_at": self.approved_at.isoformat() if self.approved_at else None,
+            "file_path": self.file_path
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Plan':
+        """Create Plan from dictionary."""
+        steps = [
+            PlanStep.from_dict(s) if isinstance(s, dict) else s
+            for s in data.get("steps", [])
+        ]
+        
+        created_at = data.get("created_at")
+        if isinstance(created_at, str):
+            created_at = datetime.fromisoformat(created_at)
+        elif created_at is None:
+            created_at = datetime.now()
+            
+        approved_at = data.get("approved_at")
+        if isinstance(approved_at, str):
+            approved_at = datetime.fromisoformat(approved_at)
+            
+        return cls(
+            id=data.get("id", str(uuid.uuid4())[:8]),
+            name=data.get("name", "Untitled Plan"),
+            description=data.get("description", ""),
+            steps=steps,
+            status=data.get("status", "draft"),
+            created_at=created_at,
+            approved_at=approved_at,
+            file_path=data.get("file_path")
+        )
+    
+    def to_markdown(self) -> str:
+        """
+        Convert Plan to markdown format.
+        
+        Returns:
+            Markdown string representation of the plan
+        """
+        # YAML frontmatter
+        frontmatter = {
+            "id": self.id,
+            "name": self.name,
+            "status": self.status,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "approved_at": self.approved_at.isoformat() if self.approved_at else None
+        }
+        
+        lines = [
+            "---",
+            yaml.dump(frontmatter, default_flow_style=False).strip(),
+            "---",
+            "",
+            f"# {self.name}",
+            "",
+        ]
+        
+        if self.description:
+            lines.extend([self.description, ""])
+            
+        lines.extend(["## Steps", ""])
+        
+        status_icons = {
+            "pending": "⬜",
+            "in_progress": "🔄",
+            "completed": "✅",
+            "skipped": "⏭️"
+        }
+        
+        for i, step in enumerate(self.steps, 1):
+            icon = status_icons.get(step.status, "⬜")
+            lines.append(f"{i}. {icon} {step.description}")
+            
+            if step.agent:
+                lines.append(f"   - Agent: {step.agent}")
+            if step.tools:
+                lines.append(f"   - Tools: {', '.join(step.tools)}")
+            if step.dependencies:
+                lines.append(f"   - Depends on: {', '.join(step.dependencies)}")
+            lines.append("")
+            
+        return "\n".join(lines)
+    
+    @classmethod
+    def from_markdown(cls, markdown: str) -> 'Plan':
+        """
+        Create Plan from markdown format.
+        
+        Args:
+            markdown: Markdown string with YAML frontmatter
+            
+        Returns:
+            Plan instance
+        """
+        # Extract YAML frontmatter
+        frontmatter_match = re.match(r'^---\n(.*?)\n---', markdown, re.DOTALL)
+        
+        data = {}
+        if frontmatter_match:
+            try:
+                data = yaml.safe_load(frontmatter_match.group(1))
+            except yaml.YAMLError:
+                logger.warning("Failed to parse YAML frontmatter")
+                
+        # Extract steps from markdown
+        steps = []
+        # Pattern to capture status icon and description
+        step_pattern = r'^\d+\.\s*([⬜🔄✅⏭️]?)\s*(.+?)$'
+        
+        # Map icons to status
+        icon_to_status = {
+            "⬜": "pending",
+            "🔄": "in_progress",
+            "✅": "completed",
+            "⏭️": "skipped",
+            "": "pending"
+        }
+        
+        for match in re.finditer(step_pattern, markdown, re.MULTILINE):
+            icon = match.group(1).strip()
+            description = match.group(2).strip()
+            status = icon_to_status.get(icon, "pending")
+            steps.append(PlanStep(description=description, status=status))
+            
+        return cls(
+            id=data.get("id", str(uuid.uuid4())[:8]),
+            name=data.get("name", "Untitled Plan"),
+            description=data.get("description", ""),
+            steps=steps,
+            status=data.get("status", "draft")
+        )
+    
+    def add_step(self, step: PlanStep) -> None:
+        """Add a step to the plan."""
+        self.steps.append(step)
+        
+    def remove_step(self, step_id: str) -> bool:
+        """
+        Remove a step from the plan.
+        
+        Args:
+            step_id: ID of the step to remove
+            
+        Returns:
+            True if step was removed, False if not found
+        """
+        for i, step in enumerate(self.steps):
+            if step.id == step_id:
+                self.steps.pop(i)
+                return True
+        return False
+    
+    def get_step(self, step_id: str) -> Optional[PlanStep]:
+        """
+        Get a step by ID.
+        
+        Args:
+            step_id: ID of the step to find
+            
+        Returns:
+            PlanStep if found, None otherwise
+        """
+        for step in self.steps:
+            if step.id == step_id:
+                return step
+        return None
+    
+    def approve(self) -> None:
+        """Approve the plan for execution."""
+        self.status = "approved"
+        self.approved_at = datetime.now()
+        
+    def start_execution(self) -> None:
+        """Mark the plan as executing."""
+        self.status = "executing"
+        
+    def complete(self) -> None:
+        """Mark the plan as completed."""
+        self.status = "completed"
+        
+    def cancel(self) -> None:
+        """Cancel the plan."""
+        self.status = "cancelled"
+    
+    @property
+    def progress(self) -> float:
+        """
+        Calculate plan progress.
+        
+        Returns:
+            Float between 0.0 and 1.0 representing completion percentage
+        """
+        if not self.steps:
+            return 1.0
+            
+        completed = sum(1 for s in self.steps if s.status == "completed")
+        return completed / len(self.steps)
+    
+    @property
+    def is_complete(self) -> bool:
+        """Check if all steps are completed."""
+        return all(s.status == "completed" for s in self.steps)
+    
+    @property
+    def completed_step_ids(self) -> List[str]:
+        """Get list of completed step IDs."""
+        return [s.id for s in self.steps if s.status == "completed"]
+    
+    def get_next_steps(self) -> List[PlanStep]:
+        """
+        Get steps that are ready to execute.
+        
+        Returns:
+            List of steps with satisfied dependencies
+        """
+        completed = self.completed_step_ids
+        return [s for s in self.steps if s.is_ready(completed)]
+    
+    def update_step_status(self, step_id: str, status: str) -> bool:
+        """
+        Update the status of a step.
+        
+        Args:
+            step_id: ID of the step to update
+            status: New status
+            
+        Returns:
+            True if step was updated, False if not found
+        """
+        step = self.get_step(step_id)
+        if step:
+            step.status = status
+            return True
+        return False

src/praisonai-agents/praisonaiagents/planning/planner.py

@@ -0,0 +1,525 @@
+"""
+PlanningAgent for creating implementation plans.
+
+Provides planning functionality similar to:
+- CrewAI AgentPlanner
+- Cursor Plan Mode
+- Claude Code Plan Mode
+
+Features:
+- Analyze requests and create detailed plans
+- Read-only mode for safe research
+- Plan refinement based on feedback
+- Context analysis
+"""
+
+import json
+import logging
+from typing import List, Optional, Dict, Any, TYPE_CHECKING
+
+from .plan import Plan, PlanStep
+
+# Define READ_ONLY_TOOLS locally to avoid circular import
+READ_ONLY_TOOLS = [
+    "read_file",
+    "list_directory",
+    "search_codebase",
+    "search_files",
+    "grep_search",
+    "find_files",
+    "web_search",
+    "get_file_content",
+    "list_files",
+    "read_document",
+    "search_web",
+    "fetch_url",
+    "get_context",
+]
+
+if TYPE_CHECKING:
+    from ..agent.agent import Agent
+    from ..task.task import Task
+
+logger = logging.getLogger(__name__)
+
+
+class PlanningAgent:
+    """
+    Agent specialized in creating implementation plans.
+    
+    The PlanningAgent analyzes requests, researches the codebase,
+    and creates detailed step-by-step plans before execution.
+    
+    Attributes:
+        llm_model: LLM model to use for planning
+        read_only: Whether to restrict to read-only tools
+        allowed_tools: List of tools available in planning mode
+        verbose: Verbosity level
+    """
+    
+    PLANNING_PROMPT = '''You are an expert planning specialist. Your task is to analyze the request and create a detailed, actionable implementation plan.
+
+## Request
+{request}
+
+## Available Agents
+{agents_info}
+
+## Available Tasks (if any)
+{tasks_info}
+
+## Context
+{context}
+
+## Instructions
+1. Analyze the request thoroughly
+2. Break it down into clear, actionable steps
+3. Assign appropriate agents to each step
+4. Identify dependencies between steps
+5. Consider potential risks and edge cases
+
+## Output Format
+Respond with a JSON object in this exact format:
+{{
+    "name": "Brief plan name",
+    "description": "Detailed description of what this plan accomplishes",
+    "steps": [
+        {{
+            "description": "Clear description of what this step does",
+            "agent": "Name of the agent to execute this step (or null)",
+            "tools": ["list", "of", "tools", "needed"],
+            "dependencies": ["list of step IDs this depends on"]
+        }}
+    ]
+}}
+
+Important:
+- Each step should be atomic and clearly defined
+- Dependencies should reference step indices (e.g., "step_0", "step_1")
+- Be specific about what each step accomplishes
+- Consider the order of operations carefully'''
+
+    REFINEMENT_PROMPT = '''You are refining an existing implementation plan based on feedback.
+
+## Original Plan
+{original_plan}
+
+## Feedback
+{feedback}
+
+## Instructions
+1. Review the original plan
+2. Apply the feedback to improve the plan
+3. Maintain the same JSON format
+4. Keep steps that are still valid
+5. Add, modify, or remove steps as needed
+
+## Output Format
+Respond with a JSON object in the same format as the original plan:
+{{
+    "name": "Updated plan name",
+    "description": "Updated description",
+    "steps": [...]
+}}'''
+
+    ANALYSIS_PROMPT = '''Analyze the following context and provide insights for planning:
+
+## Context
+{context}
+
+## Instructions
+1. Identify the key components and their relationships
+2. Note any patterns or conventions
+3. Highlight potential challenges
+4. Suggest best practices to follow
+
+Provide a concise analysis that will help in creating an implementation plan.'''
+
+    def __init__(
+        self,
+        llm: str = "gpt-4o-mini",
+        read_only: bool = True,
+        verbose: int = 0,
+        tools: Optional[List] = None,
+        reasoning: bool = False,
+        max_reasoning_steps: int = 5
+    ):
+        """
+        Initialize PlanningAgent.
+        
+        Args:
+            llm: LLM model to use for planning
+            read_only: Whether to restrict to read-only tools
+            verbose: Verbosity level
+            tools: Optional list of tools for research during planning
+            reasoning: Whether to enable reasoning mode with chain-of-thought
+            max_reasoning_steps: Maximum reasoning iterations (default 5)
+        """
+        self.llm_model = llm
+        self.read_only = read_only
+        self.verbose = verbose
+        self.tools = tools or []
+        self.reasoning = reasoning
+        self.max_reasoning_steps = max_reasoning_steps
+        self.allowed_tools = READ_ONLY_TOOLS.copy() if read_only else []
+        self._llm = None
+        self._agent = None
+        
+    def _get_llm(self):
+        """Lazy load LLM instance."""
+        if self._llm is None:
+            from ..llm import LLM
+            self._llm = LLM(model=self.llm_model)
+        return self._llm
+    
+    def _get_agent(self):
+        """
+        Lazy load Agent instance for tool-enabled planning.
+        
+        Returns:
+            Agent instance if tools are provided, None otherwise
+        """
+        if not self.tools:
+            return None
+            
+        if self._agent is None:
+            from ..agent.agent import Agent
+            self._agent = Agent(
+                name="Planning Research Agent",
+                role="Research and Planning Specialist",
+                goal="Research information and create detailed implementation plans",
+                llm=self.llm_model,
+                tools=self.tools,
+                verbose=self.verbose > 0
+            )
+        return self._agent
+    
+    def _format_agents_info(self, agents: List['Agent']) -> str:
+        """
+        Format agent information for the prompt.
+        
+        Args:
+            agents: List of Agent instances
+            
+        Returns:
+            Formatted string describing agents
+        """
+        if not agents:
+            return "No agents specified"
+            
+        lines = []
+        for agent in agents:
+            name = getattr(agent, 'name', 'Unnamed')
+            role = getattr(agent, 'role', 'General')
+            goal = getattr(agent, 'goal', '')
+            
+            line = f"- **{name}** ({role})"
+            if goal:
+                line += f": {goal}"
+            lines.append(line)
+            
+        return "\n".join(lines)
+    
+    def _format_tasks_info(self, tasks: Optional[List['Task']]) -> str:
+        """
+        Format task information for the prompt.
+        
+        Args:
+            tasks: List of Task instances
+            
+        Returns:
+            Formatted string describing tasks
+        """
+        if not tasks:
+            return "No predefined tasks"
+            
+        lines = []
+        for task in tasks:
+            name = getattr(task, 'name', None) or getattr(task, 'description', 'Unnamed')[:50]
+            desc = getattr(task, 'description', '')[:100]
+            
+            lines.append(f"- {name}: {desc}")
+            
+        return "\n".join(lines)
+    
+    def _parse_plan_response(self, response: str) -> Plan:
+        """
+        Parse LLM response into a Plan object.
+        
+        Args:
+            response: JSON string from LLM
+            
+        Returns:
+            Plan instance
+        """
+        try:
+            # Try to extract JSON from response
+            # Handle cases where LLM includes extra text
+            json_start = response.find('{')
+            json_end = response.rfind('}') + 1
+            
+            if json_start >= 0 and json_end > json_start:
+                json_str = response[json_start:json_end]
+                data = json.loads(json_str)
+            else:
+                raise ValueError("No JSON found in response")
+                
+            # Create steps
+            steps = []
+            for i, step_data in enumerate(data.get("steps", [])):
+                step = PlanStep(
+                    id=f"step_{i}",
+                    description=step_data.get("description", ""),
+                    agent=step_data.get("agent"),
+                    tools=step_data.get("tools", []),
+                    dependencies=step_data.get("dependencies", [])
+                )
+                steps.append(step)
+                
+            return Plan(
+                name=data.get("name", "Implementation Plan"),
+                description=data.get("description", ""),
+                steps=steps
+            )
+            
+        except (json.JSONDecodeError, ValueError) as e:
+            logger.warning(f"Failed to parse plan response: {e}")
+            # Return a simple plan with the response as a single step
+            return Plan(
+                name="Implementation Plan",
+                description="Auto-generated plan",
+                steps=[PlanStep(description=response[:500])]
+            )
+    
+    async def create_plan(
+        self,
+        request: str,
+        agents: List['Agent'],
+        tasks: Optional[List['Task']] = None,
+        context: Optional[str] = None
+    ) -> Plan:
+        """
+        Create an implementation plan for the given request.
+        
+        Args:
+            request: The user's request or goal
+            agents: List of available agents
+            tasks: Optional list of predefined tasks
+            context: Optional additional context
+            
+        Returns:
+            Plan instance with steps
+        """
+        llm = self._get_llm()
+        
+        # Format the prompt
+        prompt = self.PLANNING_PROMPT.format(
+            request=request,
+            agents_info=self._format_agents_info(agents),
+            tasks_info=self._format_tasks_info(tasks),
+            context=context or "No additional context provided"
+        )
+        
+        if self.verbose >= 2:
+            logger.info(f"Creating plan for: {request[:100]}...")
+            
+        # Get LLM response
+        response = await llm.get_response_async(prompt)
+        
+        # Parse response into Plan
+        plan = self._parse_plan_response(response)
+        
+        if self.verbose >= 1:
+            logger.info(f"Created plan '{plan.name}' with {len(plan.steps)} steps")
+            
+        return plan
+    
+    def create_plan_sync(
+        self,
+        request: str,
+        agents: List['Agent'],
+        tasks: Optional[List['Task']] = None,
+        context: Optional[str] = None
+    ) -> Plan:
+        """
+        Synchronous version of create_plan.
+        
+        Args:
+            request: The user's request or goal
+            agents: List of available agents
+            tasks: Optional list of predefined tasks
+            context: Optional additional context
+            
+        Returns:
+            Plan instance with steps
+        """
+        # Format the prompt
+        prompt = self.PLANNING_PROMPT.format(
+            request=request,
+            agents_info=self._format_agents_info(agents),
+            tasks_info=self._format_tasks_info(tasks),
+            context=context or "No additional context provided"
+        )
+        
+        if self.verbose >= 2:
+            logger.info(f"Creating plan for: {request[:100]}...")
+        
+        # Use Agent with tools if available, otherwise use bare LLM
+        agent = self._get_agent()
+        if agent is not None:
+            # Use Agent.chat() for tool-enabled planning
+            response = agent.chat(prompt)
+        else:
+            # Use bare LLM for simple planning
+            llm = self._get_llm()
+            response = llm.get_response(prompt)
+        
+        # Parse response into Plan
+        plan = self._parse_plan_response(response)
+        
+        if self.verbose >= 1:
+            logger.info(f"Created plan '{plan.name}' with {len(plan.steps)} steps")
+            
+        return plan
+    
+    async def refine_plan(
+        self,
+        plan: Plan,
+        feedback: str
+    ) -> Plan:
+        """
+        Refine an existing plan based on feedback.
+        
+        Args:
+            plan: Original plan to refine
+            feedback: User feedback for refinement
+            
+        Returns:
+            Refined Plan instance
+        """
+        llm = self._get_llm()
+        
+        # Format the prompt
+        prompt = self.REFINEMENT_PROMPT.format(
+            original_plan=json.dumps(plan.to_dict(), indent=2),
+            feedback=feedback
+        )
+        
+        if self.verbose >= 2:
+            logger.info(f"Refining plan based on feedback: {feedback[:100]}...")
+            
+        # Get LLM response
+        response = await llm.get_response_async(prompt)
+        
+        # Parse response into Plan
+        refined = self._parse_plan_response(response)
+        
+        # Preserve original ID
+        refined.id = plan.id
+        
+        if self.verbose >= 1:
+            logger.info(f"Refined plan '{refined.name}' with {len(refined.steps)} steps")
+            
+        return refined
+    
+    def refine_plan_sync(
+        self,
+        plan: Plan,
+        feedback: str
+    ) -> Plan:
+        """
+        Synchronous version of refine_plan.
+        
+        Args:
+            plan: Original plan to refine
+            feedback: User feedback for refinement
+            
+        Returns:
+            Refined Plan instance
+        """
+        llm = self._get_llm()
+        
+        # Format the prompt
+        prompt = self.REFINEMENT_PROMPT.format(
+            original_plan=json.dumps(plan.to_dict(), indent=2),
+            feedback=feedback
+        )
+        
+        if self.verbose >= 2:
+            logger.info(f"Refining plan based on feedback: {feedback[:100]}...")
+            
+        # Get LLM response
+        response = llm.get_response(prompt)
+        
+        # Parse response into Plan
+        refined = self._parse_plan_response(response)
+        
+        # Preserve original ID
+        refined.id = plan.id
+        
+        if self.verbose >= 1:
+            logger.info(f"Refined plan '{refined.name}' with {len(refined.steps)} steps")
+            
+        return refined
+    
+    async def analyze_context(
+        self,
+        context: str
+    ) -> str:
+        """
+        Analyze context and provide insights for planning.
+        
+        Args:
+            context: Context to analyze (e.g., codebase summary)
+            
+        Returns:
+            Analysis string
+        """
+        llm = self._get_llm()
+        
+        prompt = self.ANALYSIS_PROMPT.format(context=context)
+        
+        if self.verbose >= 2:
+            logger.info("Analyzing context...")
+            
+        response = await llm.get_response_async(prompt)
+        
+        return response
+    
+    def analyze_context_sync(
+        self,
+        context: str
+    ) -> str:
+        """
+        Synchronous version of analyze_context.
+        
+        Args:
+            context: Context to analyze
+            
+        Returns:
+            Analysis string
+        """
+        llm = self._get_llm()
+        
+        prompt = self.ANALYSIS_PROMPT.format(context=context)
+        
+        if self.verbose >= 2:
+            logger.info("Analyzing context...")
+            
+        response = llm.get_response(prompt)
+        
+        return response
+    
+    def is_tool_allowed(self, tool_name: str) -> bool:
+        """
+        Check if a tool is allowed in planning mode.
+        
+        Args:
+            tool_name: Name of the tool to check
+            
+        Returns:
+            True if tool is allowed
+        """
+        if not self.read_only:
+            return True
+        return tool_name in self.allowed_tools

src/praisonai-agents/praisonaiagents/planning/storage.py

@@ -0,0 +1,325 @@
+"""
+PlanStorage for persisting plans and todo lists.
+
+Provides storage functionality similar to:
+- Cursor .cursor/plans/
+- Windsurf ~/.codeium/windsurf/brain/
+- Codex ~/.codex/sessions/
+
+Features:
+- Save/load plans as markdown files
+- Save/load todo lists as JSON
+- Auto-discovery of existing plans
+- Plan versioning
+"""
+
+import os
+import json
+import logging
+from pathlib import Path
+from datetime import datetime
+from typing import List, Optional, Dict, Any
+
+from .plan import Plan
+from .todo import TodoList
+
+logger = logging.getLogger(__name__)
+
+
+class PlanStorage:
+    """
+    Storage manager for plans and todo lists.
+    
+    Attributes:
+        base_path: Base directory for storage
+        plans_dir: Directory for plan files
+        todos_dir: Directory for todo files
+    """
+    
+    DEFAULT_BASE_PATH = ".praison"
+    
+    def __init__(self, base_path: Optional[str] = None):
+        """
+        Initialize PlanStorage.
+        
+        Args:
+            base_path: Base directory for storage. Defaults to .praison/
+        """
+        self.base_path = base_path or self.DEFAULT_BASE_PATH
+        self.plans_dir = os.path.join(self.base_path, "plans")
+        self.todos_dir = os.path.join(self.base_path, "todos")
+        
+        # Create directories if they don't exist
+        self._ensure_directories()
+        
+    def _ensure_directories(self) -> None:
+        """Create storage directories if they don't exist."""
+        os.makedirs(self.plans_dir, exist_ok=True)
+        os.makedirs(self.todos_dir, exist_ok=True)
+        
+    def _get_plan_filename(self, plan: Plan) -> str:
+        """
+        Generate filename for a plan.
+        
+        Args:
+            plan: Plan to generate filename for
+            
+        Returns:
+            Filename string
+        """
+        date_str = plan.created_at.strftime("%Y-%m-%d") if plan.created_at else datetime.now().strftime("%Y-%m-%d")
+        safe_name = "".join(c if c.isalnum() or c in "-_" else "_" for c in plan.name[:30])
+        return f"plan_{date_str}_{plan.id}_{safe_name}.md"
+    
+    def _get_plan_path(self, plan_id: str) -> Optional[str]:
+        """
+        Find the path for a plan by ID.
+        
+        Args:
+            plan_id: ID of the plan to find
+            
+        Returns:
+            Path to the plan file, or None if not found
+        """
+        for filename in os.listdir(self.plans_dir):
+            if plan_id in filename and filename.endswith(".md"):
+                return os.path.join(self.plans_dir, filename)
+        return None
+    
+    def save_plan(self, plan: Plan, filename: Optional[str] = None) -> str:
+        """
+        Save a plan to storage.
+        
+        Args:
+            plan: Plan to save
+            filename: Optional custom filename
+            
+        Returns:
+            Path to the saved file
+        """
+        if filename is None:
+            filename = self._get_plan_filename(plan)
+            
+        path = os.path.join(self.plans_dir, filename)
+        
+        # Convert plan to markdown
+        markdown = plan.to_markdown()
+        
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(markdown)
+            
+        plan.file_path = path
+        logger.debug(f"Saved plan to {path}")
+        
+        return path
+    
+    def load_plan(self, plan_id: str) -> Optional[Plan]:
+        """
+        Load a plan from storage.
+        
+        Args:
+            plan_id: ID of the plan to load
+            
+        Returns:
+            Plan instance, or None if not found
+        """
+        path = self._get_plan_path(plan_id)
+        
+        if path is None or not os.path.exists(path):
+            logger.debug(f"Plan {plan_id} not found")
+            return None
+            
+        with open(path, "r", encoding="utf-8") as f:
+            markdown = f.read()
+            
+        plan = Plan.from_markdown(markdown)
+        plan.file_path = path
+        
+        logger.debug(f"Loaded plan from {path}")
+        return plan
+    
+    def load_plan_from_file(self, path: str) -> Optional[Plan]:
+        """
+        Load a plan from a specific file path.
+        
+        Args:
+            path: Path to the plan file
+            
+        Returns:
+            Plan instance, or None if file doesn't exist
+        """
+        if not os.path.exists(path):
+            return None
+            
+        with open(path, "r", encoding="utf-8") as f:
+            markdown = f.read()
+            
+        plan = Plan.from_markdown(markdown)
+        plan.file_path = path
+        
+        return plan
+    
+    def list_plans(self) -> List[Dict[str, Any]]:
+        """
+        List all saved plans.
+        
+        Returns:
+            List of plan metadata dictionaries
+        """
+        plans = []
+        
+        for filename in os.listdir(self.plans_dir):
+            if filename.endswith(".md"):
+                path = os.path.join(self.plans_dir, filename)
+                
+                # Try to load and get metadata
+                try:
+                    plan = self.load_plan_from_file(path)
+                    if plan:
+                        plans.append({
+                            "id": plan.id,
+                            "name": plan.name,
+                            "status": plan.status,
+                            "created_at": plan.created_at.isoformat() if plan.created_at else None,
+                            "file_path": path
+                        })
+                except Exception as e:
+                    logger.warning(f"Failed to load plan from {path}: {e}")
+                    
+        # Sort by creation date (newest first)
+        plans.sort(key=lambda p: p.get("created_at", ""), reverse=True)
+        
+        return plans
+    
+    def delete_plan(self, plan_id: str) -> bool:
+        """
+        Delete a plan from storage.
+        
+        Args:
+            plan_id: ID of the plan to delete
+            
+        Returns:
+            True if deleted, False if not found
+        """
+        path = self._get_plan_path(plan_id)
+        
+        if path and os.path.exists(path):
+            os.remove(path)
+            logger.debug(f"Deleted plan {plan_id}")
+            return True
+            
+        return False
+    
+    def save_todo(self, todo: TodoList, name: str = "current") -> str:
+        """
+        Save a todo list to storage.
+        
+        Args:
+            todo: TodoList to save
+            name: Name for the todo file (without extension)
+            
+        Returns:
+            Path to the saved file
+        """
+        filename = f"{name}.json"
+        path = os.path.join(self.todos_dir, filename)
+        
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(todo.to_json())
+            
+        logger.debug(f"Saved todo list to {path}")
+        return path
+    
+    def load_todo(self, name: str = "current") -> Optional[TodoList]:
+        """
+        Load a todo list from storage.
+        
+        Args:
+            name: Name of the todo file (without extension)
+            
+        Returns:
+            TodoList instance, or None if not found
+        """
+        filename = f"{name}.json"
+        path = os.path.join(self.todos_dir, filename)
+        
+        if not os.path.exists(path):
+            return None
+            
+        with open(path, "r", encoding="utf-8") as f:
+            json_str = f.read()
+            
+        logger.debug(f"Loaded todo list from {path}")
+        return TodoList.from_json(json_str)
+    
+    def list_todos(self) -> List[str]:
+        """
+        List all saved todo lists.
+        
+        Returns:
+            List of todo list names
+        """
+        todos = []
+        
+        for filename in os.listdir(self.todos_dir):
+            if filename.endswith(".json"):
+                name = filename[:-5]  # Remove .json extension
+                todos.append(name)
+                
+        return todos
+    
+    def delete_todo(self, name: str) -> bool:
+        """
+        Delete a todo list from storage.
+        
+        Args:
+            name: Name of the todo file (without extension)
+            
+        Returns:
+            True if deleted, False if not found
+        """
+        filename = f"{name}.json"
+        path = os.path.join(self.todos_dir, filename)
+        
+        if os.path.exists(path):
+            os.remove(path)
+            logger.debug(f"Deleted todo list {name}")
+            return True
+            
+        return False
+    
+    def get_latest_plan(self) -> Optional[Plan]:
+        """
+        Get the most recently created plan.
+        
+        Returns:
+            Most recent Plan, or None if no plans exist
+        """
+        plans = self.list_plans()
+        
+        if not plans:
+            return None
+            
+        return self.load_plan(plans[0]["id"])
+    
+    def cleanup_old_plans(self, keep_count: int = 10) -> int:
+        """
+        Remove old plans, keeping only the most recent ones.
+        
+        Args:
+            keep_count: Number of plans to keep
+            
+        Returns:
+            Number of plans deleted
+        """
+        plans = self.list_plans()
+        
+        if len(plans) <= keep_count:
+            return 0
+            
+        deleted = 0
+        for plan in plans[keep_count:]:
+            if self.delete_plan(plan["id"]):
+                deleted += 1
+                
+        return deleted

src/praisonai-agents/praisonaiagents/planning/todo.py

@@ -0,0 +1,415 @@
+"""
+TodoList and TodoItem classes for Planning Mode.
+
+Provides task tracking functionality similar to:
+- Cursor Agent To-Dos
+- Windsurf Todo Lists
+- Claude Code TodoRead/TodoWrite
+
+Features:
+- Create todo lists from plans
+- Track item completion
+- Dependencies between items
+- Markdown and JSON serialization
+"""
+
+import uuid
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any, Literal, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .plan import Plan
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TodoItem:
+    """
+    A single todo item.
+    
+    Attributes:
+        id: Unique identifier
+        description: What needs to be done
+        status: Current status (pending, in_progress, completed)
+        dependencies: List of item IDs that must complete first
+        agent: Name of the agent responsible
+        priority: Priority level (low, medium, high)
+        notes: Additional notes
+    """
+    description: str
+    id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    status: Literal["pending", "in_progress", "completed"] = "pending"
+    dependencies: List[str] = field(default_factory=list)
+    agent: Optional[str] = None
+    priority: Literal["low", "medium", "high"] = "medium"
+    notes: str = ""
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert TodoItem to dictionary."""
+        return {
+            "id": self.id,
+            "description": self.description,
+            "status": self.status,
+            "dependencies": self.dependencies,
+            "agent": self.agent,
+            "priority": self.priority,
+            "notes": self.notes
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'TodoItem':
+        """Create TodoItem from dictionary."""
+        return cls(
+            id=data.get("id", str(uuid.uuid4())[:8]),
+            description=data.get("description", ""),
+            status=data.get("status", "pending"),
+            dependencies=data.get("dependencies", []),
+            agent=data.get("agent"),
+            priority=data.get("priority", "medium"),
+            notes=data.get("notes", "")
+        )
+    
+    def complete(self) -> None:
+        """Mark this item as completed."""
+        self.status = "completed"
+        
+    def start(self) -> None:
+        """Mark this item as in progress."""
+        self.status = "in_progress"
+        
+    def reset(self) -> None:
+        """Reset this item to pending."""
+        self.status = "pending"
+        
+    def is_ready(self, completed_ids: List[str]) -> bool:
+        """
+        Check if this item is ready to start.
+        
+        Args:
+            completed_ids: List of completed item IDs
+            
+        Returns:
+            True if all dependencies are satisfied
+        """
+        if self.status != "pending":
+            return False
+        return all(dep in completed_ids for dep in self.dependencies)
+
+
+@dataclass
+class TodoList:
+    """
+    A list of todo items with tracking capabilities.
+    
+    Attributes:
+        items: List of TodoItem objects
+        auto_update: Whether to auto-update from plan changes
+        name: Optional name for the todo list
+    """
+    items: List[TodoItem] = field(default_factory=list)
+    auto_update: bool = True
+    name: str = "Todo List"
+    
+    def add(self, item: Union[TodoItem, str]) -> TodoItem:
+        """
+        Add an item to the list.
+        
+        Args:
+            item: TodoItem or description string
+            
+        Returns:
+            The added TodoItem
+        """
+        if isinstance(item, str):
+            item = TodoItem(description=item)
+        self.items.append(item)
+        return item
+    
+    def remove(self, item_id: str) -> bool:
+        """
+        Remove an item from the list.
+        
+        Args:
+            item_id: ID of the item to remove
+            
+        Returns:
+            True if item was removed, False if not found
+        """
+        for i, item in enumerate(self.items):
+            if item.id == item_id:
+                self.items.pop(i)
+                return True
+        return False
+    
+    def get(self, item_id: str) -> Optional[TodoItem]:
+        """
+        Get an item by ID.
+        
+        Args:
+            item_id: ID of the item to find
+            
+        Returns:
+            TodoItem if found, None otherwise
+        """
+        for item in self.items:
+            if item.id == item_id:
+                return item
+        return None
+    
+    def complete(self, item_id: str) -> bool:
+        """
+        Mark an item as completed.
+        
+        Args:
+            item_id: ID of the item to complete
+            
+        Returns:
+            True if item was completed, False if not found
+        """
+        item = self.get(item_id)
+        if item:
+            item.complete()
+            return True
+        return False
+    
+    def start(self, item_id: str) -> bool:
+        """
+        Mark an item as in progress.
+        
+        Args:
+            item_id: ID of the item to start
+            
+        Returns:
+            True if item was started, False if not found
+        """
+        item = self.get(item_id)
+        if item:
+            item.start()
+            return True
+        return False
+    
+    @property
+    def pending(self) -> List[TodoItem]:
+        """Get all pending items."""
+        return [item for item in self.items if item.status == "pending"]
+    
+    @property
+    def in_progress(self) -> List[TodoItem]:
+        """Get all in-progress items."""
+        return [item for item in self.items if item.status == "in_progress"]
+    
+    @property
+    def completed(self) -> List[TodoItem]:
+        """Get all completed items."""
+        return [item for item in self.items if item.status == "completed"]
+    
+    @property
+    def progress(self) -> float:
+        """
+        Calculate completion progress.
+        
+        Returns:
+            Float between 0.0 and 1.0
+        """
+        if not self.items:
+            return 1.0
+        return len(self.completed) / len(self.items)
+    
+    @property
+    def is_complete(self) -> bool:
+        """Check if all items are completed."""
+        return all(item.status == "completed" for item in self.items)
+    
+    @property
+    def completed_ids(self) -> List[str]:
+        """Get list of completed item IDs."""
+        return [item.id for item in self.completed]
+    
+    def get_ready_items(self) -> List[TodoItem]:
+        """
+        Get items that are ready to start.
+        
+        Returns:
+            List of items with satisfied dependencies
+        """
+        completed = self.completed_ids
+        return [item for item in self.items if item.is_ready(completed)]
+    
+    def to_markdown(self) -> str:
+        """
+        Convert TodoList to markdown format.
+        
+        Returns:
+            Markdown string with checkbox format
+        """
+        lines = [f"# {self.name}", ""]
+        
+        for item in self.items:
+            checkbox = "[x]" if item.status == "completed" else "[ ]"
+            lines.append(f"- {checkbox} {item.description}")
+            
+            if item.agent:
+                lines.append(f"  - Agent: {item.agent}")
+            if item.dependencies:
+                lines.append(f"  - Depends on: {', '.join(item.dependencies)}")
+            if item.notes:
+                lines.append(f"  - Notes: {item.notes}")
+                
+        return "\n".join(lines)
+    
+    @classmethod
+    def from_markdown(cls, markdown: str) -> 'TodoList':
+        """
+        Create TodoList from markdown format.
+        
+        Args:
+            markdown: Markdown string with checkbox format
+            
+        Returns:
+            TodoList instance
+        """
+        import re
+        
+        items = []
+        # Match checkbox items: - [ ] or - [x]
+        pattern = r'^-\s*\[([ x])\]\s*(.+?)$'
+        
+        for match in re.finditer(pattern, markdown, re.MULTILINE):
+            checked = match.group(1) == 'x'
+            description = match.group(2).strip()
+            
+            item = TodoItem(
+                description=description,
+                status="completed" if checked else "pending"
+            )
+            items.append(item)
+            
+        return cls(items=items)
+    
+    def to_json(self) -> str:
+        """
+        Serialize TodoList to JSON.
+        
+        Returns:
+            JSON string
+        """
+        data = {
+            "name": self.name,
+            "auto_update": self.auto_update,
+            "items": [item.to_dict() for item in self.items]
+        }
+        return json.dumps(data, indent=2)
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> 'TodoList':
+        """
+        Create TodoList from JSON.
+        
+        Args:
+            json_str: JSON string
+            
+        Returns:
+            TodoList instance
+        """
+        data = json.loads(json_str)
+        items = [TodoItem.from_dict(item) for item in data.get("items", [])]
+        
+        return cls(
+            items=items,
+            auto_update=data.get("auto_update", True),
+            name=data.get("name", "Todo List")
+        )
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert TodoList to dictionary."""
+        return {
+            "name": self.name,
+            "auto_update": self.auto_update,
+            "items": [item.to_dict() for item in self.items]
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'TodoList':
+        """Create TodoList from dictionary."""
+        items = [TodoItem.from_dict(item) for item in data.get("items", [])]
+        return cls(
+            items=items,
+            auto_update=data.get("auto_update", True),
+            name=data.get("name", "Todo List")
+        )
+    
+    @classmethod
+    def from_plan(cls, plan: 'Plan') -> 'TodoList':
+        """
+        Create TodoList from a Plan.
+        
+        Args:
+            plan: Plan instance
+            
+        Returns:
+            TodoList with items matching plan steps
+        """
+        items = []
+        for step in plan.steps:
+            item = TodoItem(
+                id=step.id,
+                description=step.description,
+                status=step.status if step.status in ["pending", "in_progress", "completed"] else "pending",
+                dependencies=step.dependencies,
+                agent=step.agent
+            )
+            items.append(item)
+            
+        return cls(
+            items=items,
+            name=f"Todo: {plan.name}"
+        )
+    
+    def sync_with_plan(self, plan: 'Plan') -> None:
+        """
+        Synchronize TodoList with a Plan.
+        
+        Updates item statuses to match plan step statuses.
+        
+        Args:
+            plan: Plan to sync with
+        """
+        step_statuses = {step.id: step.status for step in plan.steps}
+        
+        for item in self.items:
+            if item.id in step_statuses:
+                status = step_statuses[item.id]
+                if status in ["pending", "in_progress", "completed"]:
+                    item.status = status
+                    
+    def update_from_plan(self, plan: 'Plan') -> None:
+        """
+        Update TodoList to match Plan structure.
+        
+        Adds new items for new steps, removes items for removed steps.
+        
+        Args:
+            plan: Plan to update from
+        """
+        # Get current step IDs
+        step_ids = {step.id for step in plan.steps}
+        item_ids = {item.id for item in self.items}
+        
+        # Remove items for deleted steps
+        self.items = [item for item in self.items if item.id in step_ids]
+        
+        # Add items for new steps
+        for step in plan.steps:
+            if step.id not in item_ids:
+                self.add(TodoItem(
+                    id=step.id,
+                    description=step.description,
+                    dependencies=step.dependencies,
+                    agent=step.agent
+                ))
+                
+        # Sync statuses
+        self.sync_with_plan(plan)

src/praisonai-agents/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "0.0.180"
+version = "0.0.184"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
 requires-python = ">=3.10"
 authors = [

src/praisonai-agents/test_agent_planning.py

@@ -0,0 +1,16 @@
+from praisonaiagents import Agent
+
+def search_web(query: str) -> str:
+    return "AI trends: LLMs, multimodal AI, autonomous agents"
+
+agent = Agent(
+    name="AI Assistant",
+    role="Research and Writing Specialist",
+    llm="gpt-4o-mini",
+    planning=True,
+    planning_tools=[search_web],
+    planning_reasoning=True
+)
+
+result = agent.start("Research AI trends in 2025 and write a 2 sentence summary")
+print(result)

src/praisonai-agents/test_planning_execution.py

@@ -0,0 +1,183 @@
+"""
+Complete Planning Mode Demo: Plan First, Then Execute Todo Items One by One.
+
+This demonstrates the full workflow:
+1. Create a plan with the PlanningAgent
+2. Generate todo list from the plan
+3. Execute each todo item sequentially with the appropriate agent
+4. Update progress as items are completed
+
+Run with: python test_planning_execution.py
+"""
+
+from praisonaiagents import Agent, Task
+from praisonaiagents.planning import PlanningAgent, TodoList
+
+
+def print_separator(title: str):
+    print("\n" + "=" * 70)
+    print(f"  {title}")
+    print("=" * 70 + "\n")
+
+
+def print_progress(todo_list: TodoList):
+    """Print current progress."""
+    completed = len(todo_list.completed)
+    total = len(todo_list.items)
+    progress = todo_list.progress * 100
+    bar_length = 30
+    filled = int(bar_length * todo_list.progress)
+    bar = "█" * filled + "░" * (bar_length - filled)
+    print(f"\n📊 Progress: [{bar}] {progress:.0f}% ({completed}/{total} completed)\n")
+
+
+def main():
+    print_separator("🎯 PLANNING MODE: PLAN FIRST, EXECUTE TODO ITEMS")
+    
+    # ==========================================================================
+    # STEP 1: Create Agents
+    # ==========================================================================
+    print("📦 Creating agents...")
+    
+    researcher = Agent(
+        name="Researcher",
+        role="Research Analyst",
+        goal="Research topics thoroughly and provide accurate information",
+        backstory="Expert researcher with access to vast knowledge bases",
+        verbose=True
+    )
+    
+    writer = Agent(
+        name="Writer",
+        role="Content Writer", 
+        goal="Write clear, engaging, and well-structured content",
+        backstory="Professional writer skilled in creating compelling narratives",
+        verbose=True
+    )
+    
+    print("✅ Agents created: Researcher, Writer\n")
+    
+    # ==========================================================================
+    # STEP 2: Create Plan using PlanningAgent
+    # ==========================================================================
+    print_separator("📋 PHASE 1: CREATING PLAN")
+    
+    planner = PlanningAgent(
+        llm="gpt-4o-mini",
+        read_only=True,
+        verbose=1
+    )
+    
+    request = "Write a short article about the top 3 benefits of meditation for mental health"
+    
+    print(f"📝 Request: {request}\n")
+    print("🤔 Planning agent is analyzing and creating a plan...\n")
+    
+    plan = planner.create_plan_sync(
+        request=request,
+        agents=[researcher, writer],
+        context="Keep it concise - each section should be 2-3 sentences max"
+    )
+    
+    print("\n✅ Plan created successfully!")
+    print(f"   Plan Name: {plan.name}")
+    print(f"   Total Steps: {len(plan.steps)}")
+    
+    # ==========================================================================
+    # STEP 3: Display the Plan
+    # ==========================================================================
+    print_separator("📄 GENERATED PLAN")
+    print(plan.to_markdown())
+    
+    # ==========================================================================
+    # STEP 4: Create Todo List from Plan
+    # ==========================================================================
+    print_separator("📝 PHASE 2: TODO LIST CREATED")
+    
+    todo_list = TodoList.from_plan(plan)
+    print(todo_list.to_markdown())
+    print_progress(todo_list)
+    
+    # ==========================================================================
+    # STEP 5: Execute Each Todo Item One by One
+    # ==========================================================================
+    print_separator("🚀 PHASE 3: EXECUTING TODO ITEMS")
+    
+    # Map agent names to agent instances
+    agent_map = {
+        "Researcher": researcher,
+        "Writer": writer
+    }
+    
+    results = {}
+    
+    for i, item in enumerate(todo_list.items):
+        print(f"\n{'─' * 70}")
+        print(f"📌 TODO ITEM {i + 1}/{len(todo_list.items)}")
+        print(f"{'─' * 70}")
+        print(f"   Description: {item.description}")
+        print(f"   Agent: {item.agent or 'Auto-assign'}")
+        print(f"   Status: {item.status}")
+        
+        if item.dependencies:
+            print(f"   Dependencies: {', '.join(item.dependencies)}")
+        
+        # Mark as in progress
+        todo_list.start(item.id)
+        print(f"\n   ⏳ Starting execution...")
+        
+        # Get the appropriate agent
+        agent_name = item.agent or "Researcher"
+        agent = agent_map.get(agent_name, researcher)
+        
+        # Build context from previous results
+        context = ""
+        for dep_id in item.dependencies:
+            if dep_id in results:
+                context += f"\nPrevious result ({dep_id}):\n{results[dep_id]}\n"
+        
+        # Create task description
+        task_description = item.description
+        if context:
+            task_description += f"\n\nContext from previous steps:{context}"
+        
+        # Execute with the agent
+        try:
+            result = agent.chat(task_description)
+            results[item.id] = result
+            
+            # Mark as completed
+            todo_list.complete(item.id)
+            
+            print(f"\n   ✅ Completed!")
+            print(f"\n   📄 Result Preview:")
+            print("   " + "-" * 50)
+            preview = str(result)[:500] + "..." if len(str(result)) > 500 else str(result)
+            for line in preview.split('\n'):
+                print(f"   {line}")
+            
+        except Exception as e:
+            print(f"\n   ❌ Error: {e}")
+            results[item.id] = f"Error: {e}"
+        
+        print_progress(todo_list)
+    
+    # ==========================================================================
+    # STEP 6: Final Summary
+    # ==========================================================================
+    print_separator("🎉 EXECUTION COMPLETE")
+    
+    print("📋 Final Todo List Status:")
+    print(todo_list.to_markdown())
+    
+    print("\n📊 Final Results Summary:")
+    print("-" * 50)
+    for item in todo_list.items:
+        status_icon = "✅" if item.status == "completed" else "❌"
+        print(f"{status_icon} {item.description[:60]}...")
+    
+    print(f"\n🏆 All {len(todo_list.completed)} tasks completed successfully!")
+
+
+if __name__ == "__main__":
+    main()

src/praisonai-agents/test_planning_modes_clean.py

@@ -0,0 +1,22 @@
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+def search_web(query: str) -> str:
+    return f"Results: AI trends include LLMs, multimodal AI, autonomous agents"
+
+researcher = Agent(name="Researcher", role="Research Analyst", llm="gpt-4o-mini")
+writer = Agent(name="Writer", role="Content Writer", llm="gpt-4o-mini")
+
+task1 = Task(description="Research AI trends in 2025", agent=researcher)
+task2 = Task(description="Write a 2 sentence summary", agent=writer)
+
+agents = PraisonAIAgents(
+    agents=[researcher, writer],
+    tasks=[task1, task2],
+    planning=True,
+    planning_tools=[search_web],
+    planning_reasoning=True,
+    auto_approve_plan=True
+)
+
+result = agents.start()
+print(result)

src/praisonai-agents/test_planning_simple.py

@@ -0,0 +1,28 @@
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+def search_web(query: str) -> str:
+    return "AI trends: LLMs, multimodal AI, autonomous agents"
+
+agent = Agent(
+    name="AI Assistant",
+    role="Research and Writing Specialist",
+    llm="gpt-4o-mini",
+    instructions="Research AI trends in 2025 and write a 2 sentence summary"
+)
+
+task = Task(
+    description="Research AI trends in 2025 and write a 2 sentence summary",
+    agent=agent
+)
+
+agents = PraisonAIAgents(
+    agents=[agent],
+    tasks=[task],
+    planning=True,
+    planning_tools=[search_web],
+    planning_reasoning=True,
+    auto_approve_plan=True
+)
+
+result = agents.start()
+print(result)

src/praisonai-agents/test_planning_tools_example.py

@@ -0,0 +1,34 @@
+from praisonaiagents import Agent
+from praisonaiagents.planning import PlanningAgent
+
+def search_web(query: str) -> str:
+    return f"Results for '{query}': LLMs, multimodal AI, autonomous agents"
+
+researcher = Agent(name="Researcher", role="Research Analyst", llm="gpt-4o-mini")
+writer = Agent(name="Writer", role="Content Writer", llm="gpt-4o-mini")
+
+print("\n=== TEST 1: Basic Planning (NO tools) ===")
+planner1 = PlanningAgent(llm="gpt-4o-mini")
+plan1 = planner1.create_plan_sync(
+    request="Write about AI trends 2025",
+    agents=[researcher, writer]
+)
+print(f"Plan: {plan1.name}, Steps: {len(plan1.steps)}")
+
+print("\n=== TEST 2: Planning WITH tools ===")
+planner2 = PlanningAgent(llm="gpt-4o-mini", tools=[search_web])
+plan2 = planner2.create_plan_sync(
+    request="Write about AI trends 2025",
+    agents=[researcher, writer]
+)
+print(f"Plan: {plan2.name}, Steps: {len(plan2.steps)}")
+
+print("\n=== TEST 3: Planning WITH tools + reasoning ===")
+planner3 = PlanningAgent(llm="gpt-4o-mini", tools=[search_web], reasoning=True)
+plan3 = planner3.create_plan_sync(
+    request="Write about AI trends 2025",
+    agents=[researcher, writer]
+)
+print(f"Plan: {plan3.name}, Steps: {len(plan3.steps)}")
+
+print("\n✅ Done!")

src/praisonai-agents/tests/test_planning_tools.py

@@ -0,0 +1,407 @@
+"""
+Test-Driven Development tests for Planning Mode with Tools Support.
+
+This module contains tests for:
+- PlanningAgent with tools parameter
+- PlanningAgent with reasoning mode
+- PraisonAIAgents with planning_tools parameter
+- Research-enabled planning
+"""
+
+import pytest
+import json
+from unittest.mock import Mock, MagicMock, patch, AsyncMock
+
+
+# =============================================================================
+# SECTION 1: PlanningAgent Tools Parameter Tests
+# =============================================================================
+
+class TestPlanningAgentToolsParameter:
+    """Tests for PlanningAgent tools parameter."""
+    
+    def test_planning_agent_accepts_tools_parameter(self):
+        """Test that PlanningAgent accepts tools parameter."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        def search_tool(query: str) -> str:
+            """Search the web."""
+            return f"Results for {query}"
+        
+        planner = PlanningAgent(tools=[search_tool])
+        
+        assert planner.tools is not None
+        assert len(planner.tools) == 1
+        
+    def test_planning_agent_tools_default_empty(self):
+        """Test that tools defaults to empty list."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        planner = PlanningAgent()
+        
+        assert planner.tools == []
+        
+    def test_planning_agent_with_multiple_tools(self):
+        """Test PlanningAgent with multiple tools."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        def tool1(x: str) -> str:
+            return x
+        def tool2(x: str) -> str:
+            return x
+        def tool3(x: str) -> str:
+            return x
+        
+        planner = PlanningAgent(tools=[tool1, tool2, tool3])
+        
+        assert len(planner.tools) == 3
+
+
+# =============================================================================
+# SECTION 2: PlanningAgent Internal Agent Tests
+# =============================================================================
+
+class TestPlanningAgentInternalAgent:
+    """Tests for PlanningAgent internal Agent creation."""
+    
+    def test_planning_agent_creates_internal_agent_when_tools_provided(self):
+        """Test that internal Agent is created when tools are provided."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        def search_tool(query: str) -> str:
+            """Search the web."""
+            return f"Results for {query}"
+        
+        planner = PlanningAgent(tools=[search_tool])
+        
+        # Internal agent should be created lazily
+        agent = planner._get_agent()
+        
+        assert agent is not None
+        assert agent.tools is not None
+        
+    def test_planning_agent_no_internal_agent_without_tools(self):
+        """Test that no internal Agent is created without tools."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        planner = PlanningAgent()
+        
+        agent = planner._get_agent()
+        
+        assert agent is None
+        
+    def test_planning_agent_internal_agent_uses_planning_llm(self):
+        """Test that internal Agent uses the planning LLM."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        def search_tool(query: str) -> str:
+            return "results"
+        
+        planner = PlanningAgent(llm="gpt-4o", tools=[search_tool])
+        agent = planner._get_agent()
+        
+        assert agent is not None
+        # The agent should use the same LLM model
+        assert agent.llm == "gpt-4o"
+
+
+# =============================================================================
+# SECTION 3: PlanningAgent Create Plan with Tools Tests
+# =============================================================================
+
+class TestPlanningAgentCreatePlanWithTools:
+    """Tests for create_plan_sync with tools."""
+    
+    def test_create_plan_sync_uses_agent_when_tools_provided(self):
+        """Test that create_plan_sync uses Agent.chat when tools provided."""
+        from praisonaiagents.planning import PlanningAgent
+        from praisonaiagents import Agent
+        
+        def search_tool(query: str) -> str:
+            """Search the web for information."""
+            return f"Search results for: {query}"
+        
+        planner = PlanningAgent(tools=[search_tool])
+        
+        # Mock the internal agent's chat method
+        mock_agent = MagicMock()
+        mock_agent.chat = MagicMock(return_value=json.dumps({
+            "name": "Research Plan",
+            "description": "Plan created with research",
+            "steps": [
+                {"description": "Research topic", "agent": "Researcher"},
+                {"description": "Write content", "agent": "Writer"}
+            ]
+        }))
+        mock_agent.tools = [search_tool]
+        mock_agent.llm = "gpt-4o-mini"
+        
+        planner._agent = mock_agent
+        
+        agents = [Agent(name="Researcher", role="Researcher")]
+        plan = planner.create_plan_sync(
+            request="Research AI trends",
+            agents=agents
+        )
+        
+        # Verify agent.chat was called (not LLM.get_response)
+        mock_agent.chat.assert_called_once()
+        assert plan.name == "Research Plan"
+        
+    def test_create_plan_sync_uses_llm_when_no_tools(self):
+        """Test that create_plan_sync uses LLM when no tools provided."""
+        from praisonaiagents.planning import PlanningAgent
+        from praisonaiagents import Agent
+        
+        planner = PlanningAgent()
+        
+        # Mock the LLM
+        mock_llm = MagicMock()
+        mock_llm.get_response = MagicMock(return_value=json.dumps({
+            "name": "Simple Plan",
+            "description": "Plan without research",
+            "steps": [{"description": "Step 1"}]
+        }))
+        
+        planner._llm = mock_llm
+        
+        agents = [Agent(name="Worker", role="Worker")]
+        plan = planner.create_plan_sync(
+            request="Simple task",
+            agents=agents
+        )
+        
+        # Verify LLM.get_response was called
+        mock_llm.get_response.assert_called_once()
+        assert plan.name == "Simple Plan"
+
+
+# =============================================================================
+# SECTION 4: PraisonAIAgents planning_tools Parameter Tests
+# =============================================================================
+
+class TestPraisonAIAgentsPlanningTools:
+    """Tests for PraisonAIAgents planning_tools parameter."""
+    
+    def test_praisonaiagents_accepts_planning_tools(self):
+        """Test that PraisonAIAgents accepts planning_tools parameter."""
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        
+        def search_tool(query: str) -> str:
+            return "results"
+        
+        agent = Agent(name="Test", role="Tester")
+        task = Task(description="Test task", agent=agent)
+        
+        agents = PraisonAIAgents(
+            agents=[agent],
+            tasks=[task],
+            planning=True,
+            planning_tools=[search_tool]
+        )
+        
+        assert agents.planning_tools is not None
+        assert len(agents.planning_tools) == 1
+        
+    def test_praisonaiagents_planning_tools_default_none(self):
+        """Test that planning_tools defaults to None."""
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        
+        agent = Agent(name="Test", role="Tester")
+        task = Task(description="Test task", agent=agent)
+        
+        agents = PraisonAIAgents(
+            agents=[agent],
+            tasks=[task],
+            planning=True
+        )
+        
+        assert agents.planning_tools is None
+        
+    def test_praisonaiagents_passes_tools_to_planning_agent(self):
+        """Test that planning_tools are passed to PlanningAgent."""
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        
+        def search_tool(query: str) -> str:
+            return "results"
+        
+        agent = Agent(name="Test", role="Tester")
+        task = Task(description="Test task", agent=agent)
+        
+        agents = PraisonAIAgents(
+            agents=[agent],
+            tasks=[task],
+            planning=True,
+            planning_tools=[search_tool]
+        )
+        
+        # Get the planning agent
+        planning_agent = agents._get_planning_agent()
+        
+        assert planning_agent is not None
+        assert planning_agent.tools is not None
+        assert len(planning_agent.tools) == 1
+
+
+# =============================================================================
+# SECTION 5: PlanningAgent Reasoning Mode Tests
+# =============================================================================
+
+class TestPlanningAgentReasoningMode:
+    """Tests for PlanningAgent reasoning mode."""
+    
+    def test_planning_agent_accepts_reasoning_parameter(self):
+        """Test that PlanningAgent accepts reasoning parameter."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        planner = PlanningAgent(reasoning=True)
+        
+        assert planner.reasoning is True
+        
+    def test_planning_agent_reasoning_default_false(self):
+        """Test that reasoning defaults to False."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        planner = PlanningAgent()
+        
+        assert planner.reasoning is False
+        
+    def test_planning_agent_accepts_max_reasoning_steps(self):
+        """Test that PlanningAgent accepts max_reasoning_steps parameter."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        planner = PlanningAgent(reasoning=True, max_reasoning_steps=10)
+        
+        assert planner.max_reasoning_steps == 10
+        
+    def test_planning_agent_max_reasoning_steps_default(self):
+        """Test that max_reasoning_steps defaults to 5."""
+        from praisonaiagents.planning import PlanningAgent
+        
+        planner = PlanningAgent(reasoning=True)
+        
+        assert planner.max_reasoning_steps == 5
+
+
+# =============================================================================
+# SECTION 6: PraisonAIAgents planning_reasoning Parameter Tests
+# =============================================================================
+
+class TestPraisonAIAgentsPlanningReasoning:
+    """Tests for PraisonAIAgents planning_reasoning parameter."""
+    
+    def test_praisonaiagents_accepts_planning_reasoning(self):
+        """Test that PraisonAIAgents accepts planning_reasoning parameter."""
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        
+        agent = Agent(name="Test", role="Tester")
+        task = Task(description="Test task", agent=agent)
+        
+        agents = PraisonAIAgents(
+            agents=[agent],
+            tasks=[task],
+            planning=True,
+            planning_reasoning=True
+        )
+        
+        assert agents.planning_reasoning is True
+        
+    def test_praisonaiagents_planning_reasoning_default_false(self):
+        """Test that planning_reasoning defaults to False."""
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        
+        agent = Agent(name="Test", role="Tester")
+        task = Task(description="Test task", agent=agent)
+        
+        agents = PraisonAIAgents(
+            agents=[agent],
+            tasks=[task],
+            planning=True
+        )
+        
+        assert agents.planning_reasoning is False
+        
+    def test_praisonaiagents_passes_reasoning_to_planning_agent(self):
+        """Test that planning_reasoning is passed to PlanningAgent."""
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        
+        agent = Agent(name="Test", role="Tester")
+        task = Task(description="Test task", agent=agent)
+        
+        agents = PraisonAIAgents(
+            agents=[agent],
+            tasks=[task],
+            planning=True,
+            planning_reasoning=True
+        )
+        
+        planning_agent = agents._get_planning_agent()
+        
+        assert planning_agent.reasoning is True
+
+
+# =============================================================================
+# SECTION 7: Integration Tests
+# =============================================================================
+
+class TestPlanningToolsIntegration:
+    """Integration tests for planning with tools."""
+    
+    def test_planning_with_tools_and_reasoning(self):
+        """Test planning with both tools and reasoning enabled."""
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        
+        def search_tool(query: str) -> str:
+            return "search results"
+        
+        agent = Agent(name="Researcher", role="Research Analyst")
+        task = Task(description="Research AI trends", agent=agent)
+        
+        agents = PraisonAIAgents(
+            agents=[agent],
+            tasks=[task],
+            planning=True,
+            planning_tools=[search_tool],
+            planning_reasoning=True,
+            auto_approve_plan=True
+        )
+        
+        assert agents.planning is True
+        assert agents.planning_tools is not None
+        assert agents.planning_reasoning is True
+        
+        planning_agent = agents._get_planning_agent()
+        assert planning_agent.tools is not None
+        assert planning_agent.reasoning is True
+
+
+# =============================================================================
+# SECTION 8: RESEARCH_TOOLS List Tests
+# =============================================================================
+
+class TestResearchToolsList:
+    """Tests for RESEARCH_TOOLS list in planning module."""
+    
+    def test_research_tools_list_exists(self):
+        """Test that RESEARCH_TOOLS list exists."""
+        from praisonaiagents.planning import RESEARCH_TOOLS
+        
+        assert RESEARCH_TOOLS is not None
+        assert isinstance(RESEARCH_TOOLS, list)
+        
+    def test_research_tools_contains_search_tools(self):
+        """Test that RESEARCH_TOOLS contains common search tools."""
+        from praisonaiagents.planning import RESEARCH_TOOLS
+        
+        expected_tools = [
+            "web_search",
+            "search_web",
+            "duckduckgo_search",
+        ]
+        
+        for tool in expected_tools:
+            assert tool in RESEARCH_TOOLS, f"{tool} should be in RESEARCH_TOOLS"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

src/praisonai-agents/uv.lock

@@ -2422,7 +2422,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "0.0.180"
+version = "0.0.184"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

src/praisonai/README.md

@@ -60,6 +60,9 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 - 💾 **Prompt Caching** (Reduce costs & latency - OpenAI, Anthropic, Bedrock, Deepseek)
 - 🧠 **Claude Memory Tool** (Persistent cross-conversation memory - Anthropic Beta)
 - 💾 **File-Based Memory** (Zero-dependency persistent memory for all agents)
+- 📋 **Planning Mode** (Plan before execution - Agent & Multi-Agent)
+- 🔧 **Planning Tools** (Research with tools during planning)
+- 🧠 **Planning Reasoning** (Chain-of-thought planning)
 
 ## Using Python Code
 
@@ -103,7 +106,34 @@ Run:
 python app.py
 ```
 
-### 3. Deep Research Agent
+### 3. Agent with Planning Mode
+
+Enable planning for any agent - the agent creates a plan, then executes step by step:
+
+```python
+from praisonaiagents import Agent
+
+def search_web(query: str) -> str:
+    return f"Search results for: {query}"
+
+agent = Agent(
+    name="AI Assistant",
+    instructions="Research and write about topics",
+    planning=True,              # Enable planning mode
+    planning_tools=[search_web], # Tools for planning research
+    planning_reasoning=True      # Chain-of-thought reasoning
+)
+
+result = agent.start("Research AI trends in 2025 and write a summary")
+```
+
+**What happens:**
+1. 📋 Agent creates a multi-step plan
+2. 🚀 Executes each step sequentially
+3. 📊 Shows progress with context passing
+4. ✅ Returns final result
+
+### 4. Deep Research Agent
 
 Automated research with real-time streaming, web search, and citations using OpenAI or Gemini Deep Research APIs.
 
@@ -141,7 +171,7 @@ print(result.report)
 - 🛠️ Built-in tools: web search, code interpreter, MCP, file search
 - 🔄 Automatic provider detection from model name
 
-### 4. Query Rewriter Agent
+### 5. Query Rewriter Agent
 
 Transform user queries to improve RAG retrieval quality using multiple strategies.
 
@@ -176,9 +206,9 @@ result = agent.rewrite("What about cost?", chat_history=[...])
 - **CONTEXTUAL**: Resolve references using conversation history
 - **AUTO**: Automatically detect best strategy
 
-### 5. Agent Memory (Zero Dependencies)
+### 6. Agent Memory (Zero Dependencies)
 
-Enable persistent memory for agents - works out of the box without any extra packages. Features inspired by Claude, Gemini CLI, Codex CLI, Cursor, and Windsurf.
+Enable persistent memory for agents - works out of the box without any extra packages.
 
 ```python
 from praisonaiagents import Agent
@@ -203,7 +233,7 @@ result = agent.start("My name is John and I prefer Python")
 - **Entity**: People, places, organizations with attributes
 - **Episodic**: Date-based interaction history
 
-**Advanced Features (like Gemini CLI):**
+**Advanced Features:**
 ```python
 from praisonaiagents.memory import FileMemory
 
@@ -233,7 +263,7 @@ memory.handle_command("/memory save my_session")
 | `memory="sqlite"` | Built-in | SQLite with indexing |
 | `memory="chromadb"` | chromadb | Vector/semantic search |
 
-### 6. Rules & Instructions (like Cursor/Windsurf)
+### 6. Rules & Instructions
 
 PraisonAI auto-discovers instruction files from your project root and git root:
 
@@ -261,7 +291,7 @@ agent = Agent(name="Assistant", instructions="You are helpful.")
 # Rules are injected into system prompt automatically
 ```
 
-**@Import Syntax (like Claude Code):**
+**@Import Syntax:**
 ```markdown
 # CLAUDE.md
 See @README for project overview
@@ -282,7 +312,7 @@ activation: always  # always, glob, manual, ai_decision
 - Follow PEP 8
 ```
 
-### 7. Auto-Generated Memories (like Windsurf Cascade)
+### 7. Auto-Generated Memories
 
 ```python
 from praisonaiagents.memory import FileMemory, AutoMemory
@@ -297,7 +327,7 @@ memories = auto.process_interaction(
 # Extracts: name="John", preference="Python for backend"
 ```
 
-### 8. Workflows (like Windsurf)
+### 8. Workflows
 
 Create reusable multi-step workflows in `.praison/workflows/`:
 
@@ -314,7 +344,7 @@ result = manager.execute(
 )
 ```
 
-### 9. Hooks (like Windsurf Cascade Hooks)
+### 9. Hooks
 
 Configure in `.praison/hooks.json`:
 

src/praisonai/praisonai.rb

@@ -3,8 +3,8 @@ class Praisonai < Formula
   
     desc "AI tools for various AI applications"
     homepage "https://github.com/MervinPraison/PraisonAI"
-    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.4.tar.gz"
-    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.4.tar.gz | shasum -a 256`.split.first
+    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.6.tar.gz"
+    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.6.tar.gz | shasum -a 256`.split.first
     license "MIT"
   
     depends_on "[email protected]"

src/praisonai/praisonai/deploy.py

@@ -57,7 +57,7 @@ class CloudDeployer:
             file.write("FROM python:3.11-slim\n")
             file.write("WORKDIR /app\n")
             file.write("COPY . .\n")
-            file.write("RUN pip install flask praisonai==2.3.4 gunicorn markdown\n")
+            file.write("RUN pip install flask praisonai==2.3.6 gunicorn markdown\n")
             file.write("EXPOSE 8080\n")
             file.write('CMD ["gunicorn", "-b", "0.0.0.0:8080", "api:app"]\n')
             

src/praisonai/praisonai/version.py

@@ -1 +1 @@
-__version__ = "2.3.4"
+__version__ = "2.3.6"

src/praisonai/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
     "rich>=13.7",
     "markdown>=3.5",
     "pyparsing>=3.0.0",
-    "praisonaiagents>=0.0.180",
+    "praisonaiagents>=0.0.184",
     "python-dotenv>=0.19.0",
     "instructor>=1.3.3",
     "PyYAML>=6.0",

src/praisonai/uv.lock

@@ -4197,7 +4197,7 @@ requires-dist = [
     { name = "praisonai-tools", marker = "extra == 'autogen'", specifier = ">=0.0.22" },
     { name = "praisonai-tools", marker = "extra == 'autogen-v4'", specifier = ">=0.0.22" },
     { name = "praisonai-tools", marker = "extra == 'crewai'", specifier = ">=0.0.22" },
-    { name = "praisonaiagents", specifier = ">=0.0.180" },
+    { name = "praisonaiagents", specifier = ">=0.0.184" },
     { name = "pyautogen", marker = "extra == 'autogen'", specifier = "==0.2.29" },
     { name = "pydantic", marker = "extra == 'chat'", specifier = "<=2.10.1" },
     { name = "pydantic", marker = "extra == 'code'", specifier = "<=2.10.1" },
@@ -4252,7 +4252,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "0.0.180"
+version = "0.0.184"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
@@ -4261,9 +4261,9 @@ dependencies = [
     { name = "pydantic" },
     { name = "rich" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a6/7e/8404716bff5d51dccada132bf2c9fb3986f858622f1f7651ff379d56a8fa/praisonaiagents-0.0.180.tar.gz", hash = "sha256:e668ac705e15b13478cd2b895c32cf603fbf49c380b8cfdb4949adefc8505014", size = 387604, upload-time = "2025-12-15T16:37:52.512Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/98/56/219e1f1eca6f0d521822f83fda970b44decba97dd49346c75cba00684bce/praisonaiagents-0.0.184.tar.gz", hash = "sha256:c09d036a35c5e34a3a40ffee01b94fa50ca6f6cc07f4a67a52ea1cbba42c139e", size = 412203, upload-time = "2025-12-15T22:13:47.78Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a0/ec/8e954809280beb9eee32c130fd32ee7f6c6e73f9d806228cb31b8bbc0752/praisonaiagents-0.0.180-py3-none-any.whl", hash = "sha256:c0d8dcde4deb4dd3029f1f1fe4b263a4e08783c803ad8253be1d11470a807157", size = 378348, upload-time = "2025-12-15T16:37:51.033Z" },
+    { url = "https://files.pythonhosted.org/packages/93/a5/ffa998f4b99b763f9ff1d2ecc0a96b9669747b36563d9e453be3d4f9df3a/praisonaiagents-0.0.184-py3-none-any.whl", hash = "sha256:6aaa099cf181a9b7ac2ff446a6658ae8e2b687d55dc68a89a8eaa3f8ff1a0705", size = 398575, upload-time = "2025-12-15T22:13:46.253Z" },
 ]
 
 [[package]]