tunacode-cli 0.0.75__tar.gz → 0.0.76.1__tar.gz

{tunacode_cli-0.0.75 → tunacode_cli-0.0.76.1}/.github/workflows/publish.yml

@@ -71,10 +71,3 @@ jobs:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
         run: python -m twine upload dist/*
-
-      # Fallback: username/password secrets
-      - name: Publish to PyPI (user/pass)
-        env:
-          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
-          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-        run: python -m twine upload dist/*

tunacode_cli-0.0.76.1/CLAUDE.md

@@ -0,0 +1,132 @@
+
+### Workflow
+Make this repository perfectly optimized for you and future instances of Claude working with it. Implement the following structure and instructions precisely:
+
+### Directory Structure
+
+```
+claude/
+├── metadata/
+│   ├── dependency_graphs/
+│   ├── file_classifications.json (implementation vs. interface)
+│   └── intent_classifications.json
+├── semantic_index/
+│   ├── function_call_graphs.json
+│   ├── intent_mappings.json
+│   └── type_relationships.json
+├── debug_history/
+│   ├── error_solution_logs.json (categorized by component and error type)
+│   └── context_and_versions.json
+├── patterns/
+│   ├── canonical_patterns/
+│   ├── empirical_interface_patterns/
+│   └── reliability_metrics.json
+├── cheatsheets/
+│   └── component_cheatsheets.md (quick-reference guides, known pitfalls, Claude-specific behaviors)
+├── qa/
+│   ├── solved_problems/
+│   ├── context_logs/
+│   └── reasoning_docs/
+├── debug_history/
+│   └── debug_sessions.json (error→solution pairs, context, code versions)
+├── docs_model_friendly/
+│   ├── component_purpose.md
+│   └── component_relationships.md
+├── delta_summaries/
+│   ├── api_change_logs.json
+│   ├── behavior_changes.json
+│   └── reasoning_logs/
+└── memory_anchors/
+    ├── anchors.json (UUID-based anchors with semantic structure)
+
+To perfectly optimize this repository for you and future instances of Claude working with it, implement the following explicit instructions:
+
+1. **Claude-specific Metadata Directory**
+   - Maintain normalized metadata about the codebase, including dependency graphs, file types (implementation/interface), and intent classifications.
+
+2. **Semantic Code Indexing**
+   - Create a semantic index with intent classification and pre-analyzed semantic relationships.
+   - Document detailed function-to-function call graphs and intent mappings.
+
+3. **Debug History Database**
+   - Log all debugging sessions explicitly, including error-solution pairs, context, code versions, and categorization by component/error type.
+
+4. **Pattern and Industry Database**
+   - Provide canonical implementation patterns and empirical interface examples.
+   - Include explicit reliability metrics for assessing robustness.
+
+4. **Component-specific Cheat Sheets**
+   - Create quick-reference guides documenting common operations, pitfalls, edge cases, and Claude-specific behaviors clearly.
+
+5. **Queries-and-Answers Database**
+   - Store solved queries explicitly indexed by component, file, error type, with context and detailed reasoning.
+
+6. **Claude-specific Model-Friendly Documentation**
+   - Include clear, explicit documentation on component purposes and relationships optimized for Claude.
+
+7. **Delta Summaries**
+   - Clearly document semantic change logs, highlighting API changes, behavior shifts, and reasoning behind these changes.
+
+7. **Explicit Memory Anchors**
+   - Embed special "memory anchor" comments with UUID-based identifiers and semantic structure for easy and precise future reference.
+
+Implementing these changes ensures an optimized, efficient, and highly actionable Claude-specific repository structure for current and future Claude interactions
+
+- **CRITICAL: WORKTREE REQUIREMENT** - When user requests a worktree, you MUST:
+  1. Create the worktree with `git worktree add -b branch-name ../dirname`
+  2. If access is blocked, immediately ask: "I cannot access the worktree directory. Should I: a) Work in a subdirectory instead, b) Use a branch in the main directory, or c) Another solution?"
+  3. NEVER proceed without a worktree if user specifically requested one
+
+- before any updates make a git commit rollback point, clearly labeled for future agents
+
+- the clear outline of the objective MUST be established before we begin ANY coding, do not under any circumstance begin any updates untill this is clearly understood, if you have any ambiuguity or quesiton, the user can be brought in or use best practises
+
+- pre-commit hooks can NOT be skipped, you will be punished for skipping the
+
+
+- grep documentation and .claude as needed BOTH of these have a README.md that ahs a direcoty map, you MUST read these before any bigger grep or context searches
+
+- in general gather as much context as needed, unless specified by the user
+
+- this is the most important part of this prompt: Synthesis context aggressively and heuristically AS NEEDED ONLY You can deploy the appropriate subagent for complex tasks agents list below
+
+### Documentation
+
+- update the documents @documentation and in .claude after any update.
+
+- use the subagent tech-docs-maintainer to update the documentation you MUST instruct the subagent to keep doc updates short you will be PUNISHED for not telling the documentation agent to keep it to only the most distilled information
+
+- always follow best practices with git commits naming and gh cli workflows
+
+- commit frequently
+
+- always be on the side of safety, if you have any question consult the user
+
+### Python Coding Standards
+
+- always use the .venv
+- Use type hints (PEP 484) for all function signatures
+- Prefer f-strings (PEP 498) over %-formatting or .format()
+- Use pathlib.Path instead of os.path for filesystem operations
+- Structure imports: stdlib → third-party → local (PEP 8)
+- Use dataclasses (PEP 557) for simple data containers
+- Prefer context managers (with) for resource handling
+- Use structural pattern matching (PEP 634) for complex
+- run ruff frequently for both linting and formatting
+
+### Testing
+
+- "hatch run test" command for testing suite
+
+- anytime a new feature or refactor is done, we MUST find or make the golden/character test FIRST as a baseline standaard BEFORE starting, under no circumstance are you to NOT follow this TDD pattern
+
+- if a test for a feature does not exist you MUST create one FIRST to capture current behavior
+
+
+
+
+## Available Agents:
+
+1. **bug-context-analyzer** - Investigates precise context around bugs without suggesting fixes
+2. **code-synthesis-analyzer** - Analyzes recent code changes to identify issues needing fixes
+3. **documentation-synthesis-qa** - Creates comprehensive docs via multi-agent orchestration

{tunacode_cli-0.0.75 → tunacode_cli-0.0.76.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunacode-cli
-Version: 0.0.75
+Version: 0.0.76.1
 Summary: Your agentic CLI developer.
 Project-URL: Homepage, https://tunacode.xyz/
 Project-URL: Repository, https://github.com/alchemiststudiosDOTai/tunacode
@@ -75,6 +75,27 @@ pip install tunacode-cli
 
 For detailed installation and configuration instructions, see the [**Getting Started Guide**](documentation/user/getting-started.md).
 
+## Quickstart
+
+```bash
+# 1) Install
+pip install tunacode-cli
+
+# 2) Launch the CLI
+tunacode --wizard   # guided setup (enter an API key, pick a model)
+
+# 3) Try common commands in the REPL
+/help        # see commands
+/model       # explore models and set a default
+/plan        # enter read-only Plan Mode
+```
+
+Tip: You can also skip the wizard and set everything via flags:
+
+```bash
+tunacode --model openai:gpt-4.1 --key sk-your-key
+```
+
 ## Development Installation
 
 For contributors and developers who want to work on TunaCode:
@@ -87,13 +108,13 @@ cd tunacode
 # Quick setup (recommended)
 ./scripts/setup_dev_env.sh
 
-# Or manual setup
-python3 -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-pip install -e ".[dev]"
+# Or manual setup with UV (recommended)
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
 
 # Verify installation
-python -m tunacode --version
+tunacode --version
 ```
 
 See the [Hatch Build System Guide](documentation/development/hatch-build-system.md) for detailed instructions on the development environment.
@@ -102,6 +123,42 @@ See the [Hatch Build System Guide](documentation/development/hatch-build-system.
 
 Choose your AI provider and set your API key. For more details, see the [Configuration Section](documentation/user/getting-started.md#2-configuration) in the Getting Started Guide. For local models (LM Studio, Ollama, etc.), see the [Local Models Setup Guide](documentation/configuration/local-models.md).
 
+### New: Enhanced Model Selection
+
+TunaCode now automatically saves your model selection for future sessions. When you choose a model using `/model <provider:name>`, it will be remembered across restarts.
+
+**If you encounter API key errors**, you can manually create a configuration file that matches the current schema:
+
+```bash
+# Create the config file
+cat > ~/.config/tunacode.json << 'EOF'
+{
+  "default_model": "openai:gpt-4.1",
+  "env": {
+    "OPENAI_API_KEY": "your-openai-api-key-here",
+    "ANTHROPIC_API_KEY": "",
+    "GEMINI_API_KEY": "",
+    "OPENROUTER_API_KEY": ""
+  },
+  "settings": {
+    "enable_streaming": true,
+    "max_iterations": 40,
+    "context_window_size": 200000
+  },
+  "mcpServers": {}
+}
+EOF
+```
+
+Replace the model and API key with your preferred provider and credentials. Examples:
+- `openai:gpt-4.1` (requires OPENAI_API_KEY)
+- `anthropic:claude-4-sonnet-20250522` (requires ANTHROPIC_API_KEY)
+- `google:gemini-2.5-pro` (requires GEMINI_API_KEY)
+
+### ⚠️ Important Notice
+
+I apologize for any recent issues with model selection and configuration. I'm actively working to fix these problems and improve the overall stability of TunaCode. Your patience and feedback are greatly appreciated as I work to make the tool more reliable.
+
 ### Recommended Models
 
 Based on extensive testing, these models provide the best performance:

{tunacode_cli-0.0.75 → tunacode_cli-0.0.76.1}/README.md

@@ -27,6 +27,27 @@ pip install tunacode-cli
 
 For detailed installation and configuration instructions, see the [**Getting Started Guide**](documentation/user/getting-started.md).
 
+## Quickstart
+
+```bash
+# 1) Install
+pip install tunacode-cli
+
+# 2) Launch the CLI
+tunacode --wizard   # guided setup (enter an API key, pick a model)
+
+# 3) Try common commands in the REPL
+/help        # see commands
+/model       # explore models and set a default
+/plan        # enter read-only Plan Mode
+```
+
+Tip: You can also skip the wizard and set everything via flags:
+
+```bash
+tunacode --model openai:gpt-4.1 --key sk-your-key
+```
+
 ## Development Installation
 
 For contributors and developers who want to work on TunaCode:
@@ -39,13 +60,13 @@ cd tunacode
 # Quick setup (recommended)
 ./scripts/setup_dev_env.sh
 
-# Or manual setup
-python3 -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-pip install -e ".[dev]"
+# Or manual setup with UV (recommended)
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
 
 # Verify installation
-python -m tunacode --version
+tunacode --version
 ```
 
 See the [Hatch Build System Guide](documentation/development/hatch-build-system.md) for detailed instructions on the development environment.
@@ -54,6 +75,42 @@ See the [Hatch Build System Guide](documentation/development/hatch-build-system.
 
 Choose your AI provider and set your API key. For more details, see the [Configuration Section](documentation/user/getting-started.md#2-configuration) in the Getting Started Guide. For local models (LM Studio, Ollama, etc.), see the [Local Models Setup Guide](documentation/configuration/local-models.md).
 
+### New: Enhanced Model Selection
+
+TunaCode now automatically saves your model selection for future sessions. When you choose a model using `/model <provider:name>`, it will be remembered across restarts.
+
+**If you encounter API key errors**, you can manually create a configuration file that matches the current schema:
+
+```bash
+# Create the config file
+cat > ~/.config/tunacode.json << 'EOF'
+{
+  "default_model": "openai:gpt-4.1",
+  "env": {
+    "OPENAI_API_KEY": "your-openai-api-key-here",
+    "ANTHROPIC_API_KEY": "",
+    "GEMINI_API_KEY": "",
+    "OPENROUTER_API_KEY": ""
+  },
+  "settings": {
+    "enable_streaming": true,
+    "max_iterations": 40,
+    "context_window_size": 200000
+  },
+  "mcpServers": {}
+}
+EOF
+```
+
+Replace the model and API key with your preferred provider and credentials. Examples:
+- `openai:gpt-4.1` (requires OPENAI_API_KEY)
+- `anthropic:claude-4-sonnet-20250522` (requires ANTHROPIC_API_KEY)
+- `google:gemini-2.5-pro` (requires GEMINI_API_KEY)
+
+### ⚠️ Important Notice
+
+I apologize for any recent issues with model selection and configuration. I'm actively working to fix these problems and improve the overall stability of TunaCode. Your patience and feedback are greatly appreciated as I work to make the tool more reliable.
+
 ### Recommended Models
 
 Based on extensive testing, these models provide the best performance:

{tunacode_cli-0.0.75 → tunacode_cli-0.0.76.1}/documentation/README.md

@@ -4,7 +4,7 @@ Project documentation for tunacode.
 
 ## Directory Structure
 
-```
+```text
 documentation/
 ├── agent/                  # Agent architecture and workflows
 │   ├── TOOLS_WORKFLOW.md
@@ -12,6 +12,8 @@ documentation/
 │   └── main-agent-architecture.md
 ├── configuration/         # System configuration docs
 │   ├── config-file-example.md
+│   ├── config-flow-diagram.md
+│   ├── config-touch-points.md
 │   ├── local-models.md
 │   └── logging-configuration.md
 ├── development/          # Development practices
@@ -19,8 +21,10 @@ documentation/
 │   ├── command-system-architecture.md
 │   ├── creating-custom-commands.md
 │   ├── hatch-build-system.md
-|   ├── performance-optimizations.md
-│   └── prompt-principles.md
+│   ├── performance-optimizations.md
+│   ├── publishing-workflow.md
+│   ├── prompt-principles.md
+│   └── streaming-text-prefix-fix.md
 │── user/                 # user guides
     │── getting-started.md
     │── commands.md
@@ -36,6 +40,8 @@ General project documentation for features, architecture, and best practices.
 - [Command System Architecture](development/command-system-architecture.md) - Technical overview of the command system design and components.
 - [Creating Custom Commands](development/creating-custom-commands.md) - Step-by-step guide for creating built-in and slash commands.
 - [Hatch Build System](development/hatch-build-system.md) - Complete guide to using Hatch for development and building.
+- [Publishing Workflow](development/publishing-workflow.md) - Automated PyPI publishing process and release management.
 - [Configuration File Example](configuration/config-file-example.md) - Complete example of `~/.config/tunacode.json` with all available settings.
 - [Local Models Setup](configuration/local-models.md) - Guide for using local models with LM Studio or any OpenAI-compatible API.
 - [Performance Optimizations](development/performance-optimizations.md) - Major performance improvements and optimization strategies.
+- [Streaming Text Prefix Fix](development/streaming-text-prefix-fix.md) - Technical documentation for the streaming text truncation fix.

tunacode_cli-0.0.76.1/documentation/agent/agent-flow.md

@@ -0,0 +1,85 @@
+Now I have a good understanding of how the agent system works. Let me create a flowchart to explain the agent creation and processing flow:
+
+## TunaCode Agent Creation and Processing Flow
+
+```mermaid
+graph TD
+    A[User Request] --> B[process_request function]
+    B --> C[get_or_create_agent]
+    C --> D{Agent in Cache?}
+    D -->|Yes - Valid| E[Use Cached Agent]
+    D -->|No/Invalid| F[Create New Agent]
+    F --> G[Load System Prompt]
+    G --> H[Load TUNACODE.md Context]
+    F --> I[Initialize Tools]
+    I --> J{Plan Mode?}
+    J -->|Yes| K[Plan Mode Tools Only]
+    J -->|No| L[All Tools Available]
+    K --> M[Create Agent with Read-only + present_plan tools]
+    L --> N[Create Agent with All tools]
+    M --> O[Cache Agent]
+    N --> O
+    O --> P[Agent Iteration Loop]
+    P --> Q[Process Each Node]
+    Q --> R{Model Request Node?}
+    R -->|Yes + Streaming| S[Stream Token-level Response]
+    R -->|No| T[Process Node Content]
+    T --> U{Task Completion Marker?}
+    U -->|Yes| V[Mark Task Complete]
+    U -->|No| W[Check for Tool Calls]
+    W --> X{Read-only Tool?}
+    X -->|Yes| Y[Buffer for Parallel Execution]
+    X -->|No| Z[Execute Sequentially]
+    Y --> AA[ToolBuffer Collection]
+    Z --> AB[Immediate Tool Execution]
+    AA --> AC[Execute Buffered Tools in Parallel]
+    P --> AD{Max Iterations Reached?}
+    AD -->|Yes| AE[Create Fallback Response]
+    AD -->|No| AF[Continue Loop]
+    V --> AG[Return AgentRun Result]
+    AE --> AG
+    AF --> P
+```
+
+## Detailed Flow Explanation
+
+### 1. **Agent Creation Process**
+- **`get_or_create_agent(model, state_manager)`** is called for each request
+- Uses dual caching system (session-level and module-level)
+- Cache invalidation based on configuration changes
+- Loads system prompt from `src/tunacode/prompts/system.md`
+- Appends TUNACODE.md project context if available
+- Dynamically configures tools based on mode (plan vs normal)
+
+### 2. **Plan Mode vs Normal Mode**
+- **Plan Mode**: Restricted to read-only tools + `present_plan` tool
+- **Normal Mode**: Full toolset including write/execute tools
+- System prompt is completely replaced in plan mode with plan-specific instructions
+
+### 3. **Request Processing Loop**
+- **`process_request()`** creates agent iteration context
+- Processes nodes one by one in async loop
+- Handles streaming responses at token level
+- Monitors for task completion markers (`TUNACODE DONE:`)
+- Implements productivity tracking (3 consecutive empty iterations triggers action)
+- Manages tool execution batching for performance
+
+### 4. **Tool Execution Strategy**
+- **Read-only tools** (read_file, grep, list_dir, glob) are buffered for parallel execution
+- **Write/execute tools** (bash, run_command, write_file, update_file) run sequentially
+- **ToolBuffer** collects multiple read-only tools and executes them in batches
+- Provides speedup metrics and visual feedback during batch execution
+
+### 5. **Completion Detection**
+- Looks for `TUNACODE DONE:` marker in response content
+- Validates that no tools are queued when completion is signaled
+- Prevents premature completion when tools are pending
+- Handles fallback responses when iterations are exhausted
+
+### 6. **State Management**
+- Uses **ResponseState** with enum-based state machine
+- Tracks: USER_INPUT → ASSISTANT → TOOL_EXECUTION → RESPONSE transitions
+- Maintains backward compatibility with boolean flags
+- Session state persists across requests with caching
+
+The system is designed for optimal performance through parallel tool execution while maintaining safety through sequential write operations and comprehensive state tracking.

tunacode_cli-0.0.76.1/documentation/agent-tools/tools-architecture.md

@@ -0,0 +1,222 @@
+---
+title: "Research – AI Agent and Tools Architecture"
+date: "2025-09-12"
+owner: "context-engineer"
+phase: "Research"
+last_updated: "2025-09-12"
+last_updated_by: "context-engineer"
+last_updated_note: "Initial comprehensive research on AI agent and tools relation to OpenAI tool call format and JSON tooling"
+tags: ["agents", "tools", "openai", "json-tooling", "architecture", "pydantic-ai"]
+git_commit: "320ee40"
+---
+
+# Research – AI Agent and Tools Architecture
+**Date:** 2025-09-12
+**Owner:** context-engineer
+**Phase:** Research
+
+## Goal
+Summarize all *existing knowledge* about how the AI agent and tools are used in relation to the OpenAI tool call format and JSON tooling in the tunacode system before any new work.
+
+## Additional Search
+- `grep -ri "tool.*call" src/tunacode/core/agents/`
+- `grep -ri "openai.*tool" src/tunacode/`
+- `grep -ri "json.*tool" src/tunacode/core/agents/`
+
+## Findings
+
+### Core Architecture Overview
+
+The tunacode system implements a sophisticated tool calling architecture that bridges OpenAI's function calling specification with custom JSON tooling. The system is built around `pydantic-ai` as the primary framework while providing robust fallback mechanisms for maximum compatibility across different LLM providers.
+
+### Key Files & Components
+
+#### Agent System (`src/tunacode/core/agents/`)
+- `main.py` → Primary agent orchestrator using pydantic-ai with OpenAI tool integration
+- `agent_config.py` → Tool registration and configuration with pydantic-ai Tool wrappers
+- `agent_components/` → Core components for tool processing and execution
+  - `node_processor.py` → Tool call processing from LLM responses
+  - `tool_executor.py` → Parallel tool execution orchestration
+  - `json_tool_parser.py` → Fallback JSON tool parsing for non-structured APIs
+  - `tool_buffer.py` → Tool buffering for batch execution
+  - `message_handler.py` → Tool message patching and state management
+
+#### Tool System (`src/tunacode/tools/`)
+- `base.py` → BaseTool class with OpenAI function schema generation
+- `schema_assembler.py` → Tool schema assembly for different model providers
+- Individual tools (bash.py, grep.py, read_file.py, etc.) → Tool implementations with JSON Schema compliance
+
+#### LLM Integration (`src/tunacode/core/llm/` and utils/)
+- Model configuration and registry for OpenAI-compatible providers
+- API key validation and response parsing
+- Token cost calculation for different models
+
+### OpenAI Tool Call Format Implementation
+
+#### 1. Schema Generation Pattern
+All tools generate OpenAI-compatible function schemas through the `get_tool_schema()` method:
+
+```python
+{
+  "name": "tool_name",
+  "description": "Tool description with usage instructions",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "param_name": {
+        "type": "string|number|boolean|array",
+        "description": "Parameter description"
+      }
+    },
+    "required": ["required_param"]
+  }
+}
+```
+
+#### 2. Tool Registration with pydantic-ai
+Tools are registered using pydantic-ai's `Tool` wrapper for OpenAI compatibility:
+
+```python
+tools_list = [
+    Tool(bash, max_retries=max_retries, strict=tool_strict_validation),
+    Tool(grep, max_retries=max_retries, strict=tool_strict_validation),
+    # ... more tools
+]
+
+agent = Agent(
+    model=model,
+    system_prompt=system_prompt,
+    tools=tools_list,
+    mcp_servers=get_mcp_servers(state_manager),
+)
+```
+
+#### 3. Tool Call Processing Flow
+The system processes tool calls through multiple layers:
+1. **Primary**: OpenAI structured tool calling via pydantic-ai
+2. **Secondary**: JSON object parsing for non-structured APIs
+3. **Tertiary**: Manual tool execution with error handling
+
+### JSON Tooling Patterns
+
+#### 1. Fallback JSON Parsing
+When structured tool calling fails, the system extracts JSON objects using pattern matching:
+
+```python
+# Pattern: {"tool": "tool_name", "args": {...}}
+async def parse_json_tool_calls(text: str, tool_callback: Optional[ToolCallback],
+                               state_manager: StateManager) -> int:
+    # Find JSON objects in text using brace counting
+    # Validate tool structure and create mock tool call objects
+```
+
+#### 2. Schema-Driven Design
+- All tools implement JSON Schema for parameter validation
+- Dynamic schema generation based on execution context
+- XML-based schema definitions with hardcoded fallbacks
+- Environment-specific schema adaptation
+
+#### 3. Tool Result Handling
+- Structured error responses with `ModelRetry` support
+- Tool call tracking and state management
+- Message patching for orphaned tool calls
+- UI integration for user feedback
+
+### Parallel Execution Architecture
+
+#### 1. Tool Categorization
+- **Read-Only Tools**: `read_file`, `list_dir`, `grep`, `glob` (3-4x parallel performance)
+- **Write Tools**: `write_file`, `update_file` (sequential execution)
+- **System Tools**: `bash`, `run_command` (safety checks required)
+
+#### 2. Batching Strategy
+```python
+async def execute_tools_parallel(tool_calls: List[Tuple[Any, Any]],
+                               callback: ToolCallback, return_exceptions: bool = True) -> List[Any]:
+    max_parallel = int(os.environ.get("TUNACODE_MAX_PARALLEL", os.cpu_count() or 4))
+    # Batch execution with configurable parallelism
+```
+
+### Safety and Permission Systems
+
+#### 1. Tool Confirmation
+- Write/execute tools require user confirmation
+- Path restrictions and sandboxing
+- Dangerous operation warnings
+
+#### 2. Input Validation
+- Schema-based parameter validation
+- Type checking and range validation
+- File path safety checks
+
+### Configuration and Extensibility
+
+#### 1. Model Support
+- OpenAI GPT models with full tool calling support
+- Anthropic Claude models with JSON fallback
+- Local models via OpenAI-compatible APIs
+
+#### 2. MCP Integration
+- Model Context Protocol server support
+- External tool provider integration
+- Dynamic tool discovery
+
+## Key Patterns / Solutions Found
+
+### **Bridge Pattern**: System bridges OpenAI function calling, custom JSON tooling, and pydantic-ai interface
+- Relevance: Enables compatibility across multiple LLM providers
+- Location: `src/tunacode/core/agents/agent_config.py:45-67`
+
+### **Fallback Pattern**: Multi-layer fallback system ensures tool execution across different APIs
+- Relevance: Provides robustness when structured tool calling fails
+- Location: `src/tunacode/core/agents/agent_components/json_tool_parser.py:12-89`
+
+### **Schema-Driven Design**: All tools define JSON Schema for consistent parameter validation
+- Relevance: Standardizes tool interface and enables dynamic tool discovery
+- Location: `src/tunacode/tools/base.py:23-41`
+
+### **Parallelization Strategy**: Read-only tools batched for 3-4x performance improvement
+- Relevance: Dramatically improves performance for file operations and searches
+- Location: `src/tunacode/core/agents/agent_components/tool_executor.py:34-78`
+
+### **Safety Architecture**: Tool categorization with confirmation system prevents dangerous operations
+- Relevance: Essential for production-safe AI agent tooling
+- Location: `src/tunacode/core/tool_handler.py:23-67`
+
+## Knowledge Gaps
+
+### Missing Context
+- Detailed MCP server implementation patterns
+- Performance benchmarks for different tool batching strategies
+- Error recovery mechanisms for specific tool failure scenarios
+- Advanced configuration options for tool parallelism limits
+
+### Areas for Further Investigation
+- Real-world usage patterns and common failure modes
+- Integration patterns with external tool providers
+- Security implications of different tool execution strategies
+- Optimization opportunities for tool schema generation
+
+## References
+
+### Core Documentation
+- [Main Agent Architecture](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/documentation/agent/main-agent-architecture.md)
+- [Tool System Technical Guide](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/documentation/agent/tunacode-tool-system.md)
+- [Tools Workflow Guide](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/documentation/agent/TOOLS_WORKFLOW.md)
+
+### Key Implementation Files
+- [Agent Configuration](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/core/agents/agent_config.py)
+- [Base Tool Implementation](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/tools/base.py)
+- [Schema Assembler](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/tools/schema_assembler.py)
+- [JSON Tool Parser](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/core/agents/agent_components/json_tool_parser.py)
+- [Tool Executor](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/core/agents/agent_components/tool_executor.py)
+
+### Configuration Files
+- [Model Configuration](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/configuration/models.py)
+- [Default Settings](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/configuration/defaults.py)
+- [Example Configuration](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/documentation/configuration/tunacode.json.example)
+
+### Testing Infrastructure
+- [Agent Initialization Tests](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/tests/test_agent_initialization.py)
+- [JSON Tool Parsing Tests](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/tests/characterization/agent/test_json_tool_parsing.py)
+- [Parallel Tool Execution Tests](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/tests/test_parallel_tool_execution.py)