docs: add Permission Mode feature documentation (#239)

* docs: add Permission Mode feature documentation

- Add Permission Mode section to CLAUDE.md explaining UI-driven implementation
- Update README.md with Permission Mode in feature comparison and Key Features
- Document PlanPermissionInputPanel approach that works around SDK limitations

Closes #138

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* fix: remove inaccurate CLI limitation from README comparison

---------

Co-authored-by: Claude <[email protected]>

Author: sugyan

CLAUDE.md

@@ -524,6 +524,8 @@ cd frontend && npm run dev      # Configures proxy to localhost:9000
 
 21. **Enter Key Behavior**: Configurable Enter key behavior with persistent user preferences, supporting both traditional (Enter=Send) and modern (Enter=Newline) interaction patterns.
 
+22. **Permission Mode Switching**: UI-driven plan mode functionality that allows users to toggle between normal execution and plan mode. When plan mode is selected, users can review and approve Claude's planned actions before execution through an intuitive interface.
+
 ## Claude Code SDK Types Reference
 
 **SDK Types**: `frontend/node_modules/@anthropic-ai/claude-code/sdk.d.ts`
@@ -590,6 +592,48 @@ The modular frontend architecture provides several key benefits:
 - **Code Splitting**: Easier to implement lazy loading for large features
 - **Memory Efficiency**: Reduced memory footprint with focused hooks
 
+## Permission Mode Switching
+
+This project implements a permission mode switching feature that allows users to toggle between normal execution and plan mode before sending messages to Claude.
+
+### Features
+
+- **Normal Mode**: Direct execution (default behavior)
+- **Plan Mode**: Claude presents a plan for user review and approval before execution
+- **UI Toggle**: Permission mode selector integrated into the chat input interface
+- **Session Persistence**: Permission mode choice is maintained during the browser session
+
+### Implementation Approach
+
+The implementation uses a **UI-driven approach** with the `PlanPermissionInputPanel` component, providing:
+
+- **Three-Option Interface**: "Accept with Edits", "Accept Default", or "Keep Planning"
+- **Seamless Integration**: Built into the existing chat input component
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **State Management**: Uses the `usePermissionMode` hook for state tracking
+
+### Technical Architecture
+
+- **Frontend**: Permission mode state management via `usePermissionMode` hook
+- **Backend**: `permissionMode` parameter passed to Claude Code SDK via the chat API
+- **Types**: Shared type definitions in `shared/types.ts` with frontend extensions
+- **UI Components**: `PlanPermissionInputPanel` for plan approval workflow
+
+### Usage
+
+1. Toggle permission mode using the cycle button in the chat input area
+2. Send message in plan mode to activate plan review workflow
+3. Review plan options in the permission input panel
+4. Choose your preferred action: Accept with Edits, Accept Default, or Keep Planning
+
+### Files Involved
+
+- **Shared Types**: `shared/types.ts` - `ChatRequest.permissionMode` field
+- **Backend API**: `backend/handlers/chat.ts` - Permission mode parameter handling
+- **Frontend State**: `frontend/src/hooks/chat/usePermissionMode.ts` - State management
+- **UI Components**: `frontend/src/components/chat/PlanPermissionInputPanel.tsx` - Plan approval interface
+- **Integration**: `frontend/src/components/chat/ChatInput.tsx` - Mode toggle and panel integration
+
 ## Testing
 
 The project includes comprehensive test suites for both frontend and backend components:

README.md

@@ -14,10 +14,10 @@
 
 <div align="center">
 
-| Desktop Interface                                                                             | Mobile Experience                                                                           |
-| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Desktop Interface                                                                                                                                  | Mobile Experience                                                                                                                                |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
 | <img src="https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-desktop-basic-dark.png" alt="Desktop Interface" width="600"> | <img src="https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-mobile-basic-dark.png" alt="Mobile Interface" width="250"> |
-| _Chat-based coding interface with instant responses and ready input field_                    | _Mobile-optimized chat experience with touch-friendly design_                               |
+| _Chat-based coding interface with instant responses and ready input field_                                                                         | _Mobile-optimized chat experience with touch-friendly design_                                                                                    |
 
 </div>
 
@@ -26,10 +26,10 @@
 
 <div align="center">
 
-| Desktop (Light)                                                                            | Mobile (Light)                                                                           |
-| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| Desktop (Light)                                                                                                                                 | Mobile (Light)                                                                                                                                |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | <img src="https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-desktop-basic.png" alt="Desktop Light Theme" width="600"> | <img src="https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-mobile-basic.png" alt="Mobile Light Theme" width="250"> |
-| _Clean light interface for daytime coding sessions_                                        | _iPhone SE optimized light theme interface_                                              |
+| _Clean light interface for daytime coding sessions_                                                                                             | _iPhone SE optimized light theme interface_                                                                                                   |
 
 </div>
 
@@ -40,10 +40,10 @@
 
 <div align="center">
 
-| Desktop Permission Dialog                                                                              | Mobile Permission Dialog                                                                              |
-| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| Desktop Permission Dialog                                                                                                                                   | Mobile Permission Dialog                                                                                                                                   |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | <img src="https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-desktop-fileOperations-dark.png" alt="Permission Dialog" width="600"> | <img src="https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-mobile-fileOperations-dark.png" alt="Mobile Permission" width="250"> |
-| _Secure tool access with granular permission controls and clear approval workflow_                     | _Touch-optimized permission interface for mobile devices_                                             |
+| _Secure tool access with granular permission controls and clear approval workflow_                                                                          | _Touch-optimized permission interface for mobile devices_                                                                                                  |
 
 </div>
 
@@ -79,6 +79,16 @@ Instead of being limited to command-line interactions, Claude Code Web UI brings
 | 📝 Plain text output          | 🎨 Rich formatted responses  |
 | 🗂️ Manual directory switching | 📁 Visual project selection  |
 
+### 🎯 Key Features
+
+- **📋 Permission Mode Switching** - Toggle between normal and plan mode execution
+- **🔄 Real-time streaming responses** - Live Claude Code output in chat interface
+- **📁 Project directory selection** - Visual project picker for context-aware sessions
+- **💬 Conversation history** - Browse and restore previous chat sessions
+- **🛠️ Tool permission management** - Granular control over Claude's tool access
+- **🎨 Dark/light theme support** - Automatic system preference detection
+- **📱 Mobile-responsive design** - Touch-optimized interface for any device
+
 ---
 
 ## 🚀 Quick Start
@@ -179,16 +189,19 @@ PORT=9000 DEBUG=true claude-code-webui
 If you encounter "Claude Code process exited with code 1" or similar errors, this typically indicates Claude CLI path detection failure.
 
 **Quick Solution:**
+
 ```bash
 claude-code-webui --claude-path "$(which claude)"
 ```
 
 **Common scenarios requiring explicit path specification:**
+
 - **Node.js environment managers** (Volta, asdf, nvm, etc.)
 - **Custom installation locations**
 - **Shell aliases or wrapper scripts**
 
 **Environment-specific commands:**
+
 ```bash
 # For Volta users
 claude-code-webui --claude-path "$(volta which claude)"
@@ -199,12 +212,14 @@ claude-code-webui --claude-path "$(asdf which claude)"
 
 **Native Binary Installation:**
 Currently **not supported** due to TypeScript SDK limitations. Please use npm/yarn installation:
+
 ```bash
 npm install -g @anthropic-ai/claude-code
 ```
 
 **Debug Mode:**
 Use `--debug` flag for detailed error information:
+
 ```bash
 claude-code-webui --debug
 ```