patchpal 0.1.5__tar.gz → 0.1.7__tar.gz

{patchpal-0.1.5/patchpal.egg-info → patchpal-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchpal
-Version: 0.1.5
+Version: 0.1.7
 Summary: A lean Claude Code clone in pure  Python
 Author: PatchPal Contributors
 License-Expression: Apache-2.0
@@ -121,6 +121,10 @@ The agent has the following tools:
 
 ### File Operations
 - **read_file**: Read contents of files in the repository
+- **read_lines**: Read specific line ranges from a file without loading the entire file
+  - Example: `read_lines("app.py", 100, 150)` - read lines 100-150
+  - More efficient than read_file when you only need a few lines
+  - Useful for viewing code sections, error context, or specific regions of large files
 - **list_files**: List all files in the repository
 - **get_file_info**: Get detailed metadata for file(s) - size, modification time, type
   - Supports single files: `get_file_info("file.txt")`
@@ -143,6 +147,29 @@ The agent has the following tools:
 - **apply_patch**: Modify files by providing complete new content
 - **run_shell**: Execute shell commands (requires user permission; privilege escalation blocked)
 
+### Task Planning (TODO System)
+- **todo_add**: Add a new task to break down complex work into manageable subtasks
+  - Example: `todo_add("Implement authentication", details="Use JWT tokens")`
+  - Each task gets a unique ID for tracking
+- **todo_list**: Show all tasks with their status and progress
+  - Example: `todo_list()` - show pending tasks only
+  - Example: `todo_list(show_completed=True)` - show all tasks including completed
+- **todo_complete**: Mark a task as done
+  - Example: `todo_complete(1)` - mark task #1 as completed
+- **todo_update**: Update task description or details
+  - Example: `todo_update(1, description="Implement OAuth2 authentication")`
+- **todo_remove**: Remove a task from the list
+  - Example: `todo_remove(1)` - remove task #1
+- **todo_clear**: Clear completed tasks or start fresh
+  - Example: `todo_clear()` - clear completed tasks only
+  - Example: `todo_clear(completed_only=False)` - clear all tasks
+
+### User Interaction
+- **ask_user**: Ask the user a question during task execution
+  - Example: `ask_user("Which database should I use?", options=["PostgreSQL", "MySQL", "SQLite"])`
+  - Useful for clarifying requirements, getting decisions, or gathering additional information
+  - Supports multiple choice options or free-form answers
+
 ### Git Operations (No Permission Required)
 - **git_status**: Show modified, staged, and untracked files
 - **git_diff**: Show changes in working directory or staged area
@@ -513,6 +540,80 @@ When web tools are disabled:
 patchpal --help
 ```
 
+### Maximum Security Mode
+
+For maximum security and control, you can require permission for **all** operations including read operations:
+
+```bash
+patchpal --require-permission-for-all
+```
+
+When enabled, the agent will prompt for permission before:
+- **Read operations**: `read_file`, `list_files`, `get_file_info`, `find_files`, `tree`, `grep_code`, `git_status`, `git_diff`, `git_log`
+- **Write operations**: `edit_file`, `apply_patch` (always require permission)
+- **Shell commands**: `run_shell` (always requires permission)
+- **Web operations**: `web_search`, `web_fetch` (always require permission)
+
+**Granular session permissions:**
+When you grant permission for read operations, you can choose to grant it for:
+- **This specific operation only** (option 1)
+- **This specific file/pattern for the session** (option 2) - e.g., grant permission to read `config.py` for the session, but still prompt for other files
+- **Cancel the operation** (option 3)
+
+This provides fine-grained control over what the agent can access during the session.
+
+**Use cases:**
+- Working with highly sensitive codebases
+- Security audits where every operation must be reviewed
+- Training/demonstration purposes where you want to see exactly what the agent does
+- Untrusted environments where you want complete control
+
+**Example session:**
+```bash
+$ patchpal --require-permission-for-all
+================================================================================
+PatchPal - Claude Code–inspired coding and automation assistant
+================================================================================
+
+Using model: anthropic/claude-sonnet-4-5
+🔒 Permission required for ALL operations (including reads)
+
+You: Read config.py and database.py
+
+================================================================================
+Read File
+--------------------------------------------------------------------------------
+   Read: config.py
+--------------------------------------------------------------------------------
+
+Do you want to proceed?
+  1. Yes
+  2. Yes, and don't ask again this session for 'config.py'
+  3. No, and tell me what to do differently
+
+Choice [1-3]: 2
+
+# Agent reads config.py, then prompts for database.py
+
+================================================================================
+Read File
+--------------------------------------------------------------------------------
+   Read: database.py
+--------------------------------------------------------------------------------
+
+Do you want to proceed?
+  1. Yes
+  2. Yes, and don't ask again this session for 'database.py'
+  3. No, and tell me what to do differently
+
+Choice [1-3]: 1
+
+# Agent reads database.py, but will prompt again if it tries to read it later
+# Won't prompt again for config.py since you chose option 2
+```
+
+**Note:** This mode is separate from and overrides `PATCHPAL_REQUIRE_PERMISSION=false`. Even if you've disabled the standard permission system, `--require-permission-for-all` will still prompt for all operations.
+
 ## Usage
 
 Simply run the `patchpal` command and type your requests interactively:

{patchpal-0.1.5 → patchpal-0.1.7}/README.md

@@ -84,6 +84,10 @@ The agent has the following tools:
 
 ### File Operations
 - **read_file**: Read contents of files in the repository
+- **read_lines**: Read specific line ranges from a file without loading the entire file
+  - Example: `read_lines("app.py", 100, 150)` - read lines 100-150
+  - More efficient than read_file when you only need a few lines
+  - Useful for viewing code sections, error context, or specific regions of large files
 - **list_files**: List all files in the repository
 - **get_file_info**: Get detailed metadata for file(s) - size, modification time, type
   - Supports single files: `get_file_info("file.txt")`
@@ -106,6 +110,29 @@ The agent has the following tools:
 - **apply_patch**: Modify files by providing complete new content
 - **run_shell**: Execute shell commands (requires user permission; privilege escalation blocked)
 
+### Task Planning (TODO System)
+- **todo_add**: Add a new task to break down complex work into manageable subtasks
+  - Example: `todo_add("Implement authentication", details="Use JWT tokens")`
+  - Each task gets a unique ID for tracking
+- **todo_list**: Show all tasks with their status and progress
+  - Example: `todo_list()` - show pending tasks only
+  - Example: `todo_list(show_completed=True)` - show all tasks including completed
+- **todo_complete**: Mark a task as done
+  - Example: `todo_complete(1)` - mark task #1 as completed
+- **todo_update**: Update task description or details
+  - Example: `todo_update(1, description="Implement OAuth2 authentication")`
+- **todo_remove**: Remove a task from the list
+  - Example: `todo_remove(1)` - remove task #1
+- **todo_clear**: Clear completed tasks or start fresh
+  - Example: `todo_clear()` - clear completed tasks only
+  - Example: `todo_clear(completed_only=False)` - clear all tasks
+
+### User Interaction
+- **ask_user**: Ask the user a question during task execution
+  - Example: `ask_user("Which database should I use?", options=["PostgreSQL", "MySQL", "SQLite"])`
+  - Useful for clarifying requirements, getting decisions, or gathering additional information
+  - Supports multiple choice options or free-form answers
+
 ### Git Operations (No Permission Required)
 - **git_status**: Show modified, staged, and untracked files
 - **git_diff**: Show changes in working directory or staged area
@@ -476,6 +503,80 @@ When web tools are disabled:
 patchpal --help
 ```
 
+### Maximum Security Mode
+
+For maximum security and control, you can require permission for **all** operations including read operations:
+
+```bash
+patchpal --require-permission-for-all
+```
+
+When enabled, the agent will prompt for permission before:
+- **Read operations**: `read_file`, `list_files`, `get_file_info`, `find_files`, `tree`, `grep_code`, `git_status`, `git_diff`, `git_log`
+- **Write operations**: `edit_file`, `apply_patch` (always require permission)
+- **Shell commands**: `run_shell` (always requires permission)
+- **Web operations**: `web_search`, `web_fetch` (always require permission)
+
+**Granular session permissions:**
+When you grant permission for read operations, you can choose to grant it for:
+- **This specific operation only** (option 1)
+- **This specific file/pattern for the session** (option 2) - e.g., grant permission to read `config.py` for the session, but still prompt for other files
+- **Cancel the operation** (option 3)
+
+This provides fine-grained control over what the agent can access during the session.
+
+**Use cases:**
+- Working with highly sensitive codebases
+- Security audits where every operation must be reviewed
+- Training/demonstration purposes where you want to see exactly what the agent does
+- Untrusted environments where you want complete control
+
+**Example session:**
+```bash
+$ patchpal --require-permission-for-all
+================================================================================
+PatchPal - Claude Code–inspired coding and automation assistant
+================================================================================
+
+Using model: anthropic/claude-sonnet-4-5
+🔒 Permission required for ALL operations (including reads)
+
+You: Read config.py and database.py
+
+================================================================================
+Read File
+--------------------------------------------------------------------------------
+   Read: config.py
+--------------------------------------------------------------------------------
+
+Do you want to proceed?
+  1. Yes
+  2. Yes, and don't ask again this session for 'config.py'
+  3. No, and tell me what to do differently
+
+Choice [1-3]: 2
+
+# Agent reads config.py, then prompts for database.py
+
+================================================================================
+Read File
+--------------------------------------------------------------------------------
+   Read: database.py
+--------------------------------------------------------------------------------
+
+Do you want to proceed?
+  1. Yes
+  2. Yes, and don't ask again this session for 'database.py'
+  3. No, and tell me what to do differently
+
+Choice [1-3]: 1
+
+# Agent reads database.py, but will prompt again if it tries to read it later
+# Won't prompt again for config.py since you chose option 2
+```
+
+**Note:** This mode is separate from and overrides `PATCHPAL_REQUIRE_PERMISSION=false`. Even if you've disabled the standard permission system, `--require-permission-for-all` will still prompt for all operations.
+
 ## Usage
 
 Simply run the `patchpal` command and type your requests interactively:

{patchpal-0.1.5 → patchpal-0.1.7}/patchpal/__init__.py

@@ -1,6 +1,6 @@
 """PatchPal - An open-source Claude Code clone implemented purely in Python."""
 
-__version__ = "0.1.5"
+__version__ = "0.1.7"
 
 from patchpal.agent import create_agent
 from patchpal.tools import (

{patchpal-0.1.5 → patchpal-0.1.7}/patchpal/agent.py

@@ -14,6 +14,7 @@ from rich.markdown import Markdown
 from patchpal.context import ContextManager
 from patchpal.tools import (
     apply_patch,
+    ask_user,
     edit_file,
     find_files,
     get_file_info,
@@ -24,7 +25,14 @@ from patchpal.tools import (
     list_files,
     list_skills,
     read_file,
+    read_lines,
     run_shell,
+    todo_add,
+    todo_clear,
+    todo_complete,
+    todo_list,
+    todo_remove,
+    todo_update,
     tree,
     use_skill,
     web_fetch,
@@ -104,6 +112,31 @@ TOOLS = [
             },
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_lines",
+            "description": "Read specific lines from a file without loading the entire file. Useful for viewing code sections, error context, or specific regions of large files. More efficient than read_file when you only need a few lines.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path to the file - can be relative to repository root or an absolute path",
+                    },
+                    "start_line": {
+                        "type": "integer",
+                        "description": "Starting line number (1-indexed)",
+                    },
+                    "end_line": {
+                        "type": "integer",
+                        "description": "Ending line number (inclusive, 1-indexed). If omitted, reads only start_line",
+                    },
+                },
+                "required": ["path", "start_line"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
@@ -368,6 +401,142 @@ TOOLS = [
             },
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "todo_add",
+            "description": "Add a new task to the TODO list. Use this to break down complex tasks into manageable subtasks. Essential for planning multi-step work.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "description": {
+                        "type": "string",
+                        "description": "Brief task description (one line)",
+                    },
+                    "details": {
+                        "type": "string",
+                        "description": "Optional detailed notes about the task",
+                    },
+                },
+                "required": ["description"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "todo_list",
+            "description": "List all tasks in the TODO list with their status and progress.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "show_completed": {
+                        "type": "boolean",
+                        "description": "If true, show completed tasks; if false, show only pending tasks (default: false)",
+                    },
+                },
+                "required": [],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "todo_complete",
+            "description": "Mark a task as completed.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_id": {
+                        "type": "integer",
+                        "description": "The ID of the task to complete",
+                    },
+                },
+                "required": ["task_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "todo_update",
+            "description": "Update a task's description or details.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_id": {
+                        "type": "integer",
+                        "description": "The ID of the task to update",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "New description (optional)",
+                    },
+                    "details": {
+                        "type": "string",
+                        "description": "New details (optional)",
+                    },
+                },
+                "required": ["task_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "todo_remove",
+            "description": "Remove a task from the TODO list.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_id": {
+                        "type": "integer",
+                        "description": "The ID of the task to remove",
+                    },
+                },
+                "required": ["task_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "todo_clear",
+            "description": "Clear tasks from the TODO list (completed tasks only by default, or all tasks).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "completed_only": {
+                        "type": "boolean",
+                        "description": "If true, clear only completed tasks; if false, clear all tasks (default: true)",
+                    },
+                },
+                "required": [],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "ask_user",
+            "description": "Ask the user a question and wait for their response. Use this to clarify requirements, get decisions, or gather additional information during task execution.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "question": {
+                        "type": "string",
+                        "description": "The question to ask the user",
+                    },
+                    "options": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional list of predefined answer choices (e.g., ['yes', 'no', 'skip']). User can select from these or provide custom answer.",
+                    },
+                },
+                "required": ["question"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
@@ -387,6 +556,7 @@ TOOLS = [
 # Map tool names to functions
 TOOL_FUNCTIONS = {
     "read_file": read_file,
+    "read_lines": read_lines,
     "list_files": list_files,
     "get_file_info": get_file_info,
     "find_files": find_files,
@@ -401,6 +571,13 @@ TOOL_FUNCTIONS = {
     "web_fetch": web_fetch,
     "list_skills": list_skills,
     "use_skill": use_skill,
+    "todo_add": todo_add,
+    "todo_list": todo_list,
+    "todo_complete": todo_complete,
+    "todo_update": todo_update,
+    "todo_remove": todo_remove,
+    "todo_clear": todo_clear,
+    "ask_user": ask_user,
     "run_shell": run_shell,
 }
 
@@ -792,6 +969,13 @@ class PatchPalAgent:
                                     f"\033[2m📖 Reading: {tool_args.get('path', '')}\033[0m",
                                     flush=True,
                                 )
+                            elif tool_name == "read_lines":
+                                start = tool_args.get("start_line", "")
+                                end = tool_args.get("end_line", start)
+                                print(
+                                    f"\033[2m📖 Reading lines {start}-{end}: {tool_args.get('path', '')}\033[0m",
+                                    flush=True,
+                                )
                             elif tool_name == "list_files":
                                 print("\033[2m📁 Listing files...\033[0m", flush=True)
                             elif tool_name == "get_file_info":
@@ -855,6 +1039,41 @@ class PatchPalAgent:
                                     f"\033[2m⚡ Running: {tool_args.get('cmd', '')}\033[0m",
                                     flush=True,
                                 )
+                            elif tool_name == "todo_add":
+                                print(
+                                    f"\033[2m✅ Adding TODO: {tool_args.get('description', '')[:50]}\033[0m",
+                                    flush=True,
+                                )
+                            elif tool_name == "todo_list":
+                                print("\033[2m📋 Listing TODO tasks...\033[0m", flush=True)
+                            elif tool_name == "todo_complete":
+                                print(
+                                    f"\033[2m✓ Completing task #{tool_args.get('task_id', '')}\033[0m",
+                                    flush=True,
+                                )
+                            elif tool_name == "todo_update":
+                                print(
+                                    f"\033[2m📝 Updating task #{tool_args.get('task_id', '')}\033[0m",
+                                    flush=True,
+                                )
+                            elif tool_name == "todo_remove":
+                                print(
+                                    f"\033[2m🗑️  Removing task #{tool_args.get('task_id', '')}\033[0m",
+                                    flush=True,
+                                )
+                            elif tool_name == "todo_clear":
+                                clear_type = (
+                                    "completed" if tool_args.get("completed_only", True) else "all"
+                                )
+                                print(
+                                    f"\033[2m🧹 Clearing {clear_type} TODO tasks...\033[0m",
+                                    flush=True,
+                                )
+                            elif tool_name == "ask_user":
+                                print(
+                                    "\033[2m❓ Asking user a question...\033[0m",
+                                    flush=True,
+                                )
 
                             # Execute the tool (permission checks happen inside the tool)
                             try:

{patchpal-0.1.5 → patchpal-0.1.7}/patchpal/cli.py

@@ -194,8 +194,20 @@ Supported models: Any LiteLLM-supported model
         help="LiteLLM model identifier (e.g., openai/gpt-4o, anthropic/claude-opus-4, ollama_chat/llama3.1). "
         "Can also be set via PATCHPAL_MODEL environment variable.",
     )
+    parser.add_argument(
+        "--require-permission-for-all",
+        action="store_true",
+        help="Require permission for ALL operations including read operations (read_file, list_files, etc.). "
+        "Use this for maximum security when you want to review every operation the agent performs.",
+    )
     args = parser.parse_args()
 
+    # Set the require-permission-for-all flag if specified
+    if args.require_permission_for_all:
+        from patchpal.tools import set_require_permission_for_all
+
+        set_require_permission_for_all(True)
+
     # Determine model to use (priority: CLI arg > env var > default)
     model_id = args.model or os.getenv("PATCHPAL_MODEL") or "anthropic/claude-sonnet-4-5"
 
@@ -226,6 +238,10 @@ Supported models: Any LiteLLM-supported model
     print("=" * 80)
     print(f"\nUsing model: {model_id}")
 
+    # Show require-permission-for-all indicator if active
+    if args.require_permission_for_all:
+        print("\033[1;33m🔒 Permission required for ALL operations (including reads)\033[0m")
+
     # Show custom prompt indicator if set
     custom_prompt_path = os.getenv("PATCHPAL_SYSTEM_PROMPT")
     if custom_prompt_path:

{patchpal-0.1.5 → patchpal-0.1.7}/patchpal/system_prompt.md

@@ -8,6 +8,7 @@ Today is {current_date}. Current time is {current_time}.
 # Available Tools
 
 - **read_file**: Read any file on the system (repository files, /etc configs, logs, etc.) - sensitive files blocked for safety
+- **read_lines**: Read specific line ranges from a file without loading the entire file (efficient for large files or viewing code sections)
 - **list_files**: List all files in the repository (repository-only)
 - **get_file_info**: Get metadata for any file(s) - size, type, modified time (supports globs like '*.py', '/etc/*.conf')
 - **find_files**: Find files by name pattern using glob wildcards in repository (e.g., '*.py', 'test_*.txt')
@@ -30,7 +31,7 @@ You are a LOCAL CODE ASSISTANT with flexible file access. Security model (inspir
 
 Your tools are organized into:
 
-- **File navigation/reading**: read_file (system-wide), list_files (repo-only), find_files (repo-only), tree (system-wide), get_file_info (system-wide)
+- **File navigation/reading**: read_file (system-wide), read_lines (system-wide), list_files (repo-only), find_files (repo-only), tree (system-wide), get_file_info (system-wide)
 - **Code search**: grep_code (repo-only)
 - **File modification**: edit_file, apply_patch (repo files; outside requires permission)
 - **Git operations**: git_status, git_diff, git_log (read-only, no permission needed)
@@ -102,6 +103,7 @@ The user will primarily request software engineering tasks like solving bugs, ad
 - Use find_files to locate specific files by name pattern in repository (e.g., '*.py', 'test_*.txt')
 - Use get_file_info to check file metadata anywhere (supports globs like '/etc/*.conf')
 - Use read_file to examine any file on the system (repository, configs, logs, etc.)
+- Use read_lines to read specific line ranges from files (more efficient for large files)
 - Use grep_code to search for patterns in repository file contents
 - For system file exploration (outside repository):
   - Use tree for directory listing (e.g., tree("/etc") to list /etc)
@@ -111,6 +113,15 @@ The user will primarily request software engineering tasks like solving bugs, ad
   - Use edit_file for small, targeted changes (repository files; outside requires permission)
   - Use apply_patch for larger changes or rewriting significant portions
 - Use git_status, git_diff, git_log to understand repository state (no permission needed){web_usage}
+- For complex multi-step tasks:
+  - Use todo_add to break down work into manageable subtasks
+  - Use todo_list to check progress and see what's next
+  - Use todo_complete when finishing each task
+  - This helps track progress and ensures nothing is forgotten
+- Use ask_user to clarify requirements, get decisions, or gather information during execution
+  - Ask when user intent is ambiguous
+  - Get preferences on implementation choices
+  - Confirm before making significant architectural decisions
 - Use run_shell when no dedicated tool exists (requires permission)
 - Never use run_shell for repository file operations - dedicated tools are available