Merge pull request #59 from vstorm-co/feat/0.3.3

feat: add ACP protocol, framework improvements and bug fixes

Author: DEENUU1

AGENT.md

@@ -206,7 +206,7 @@ from pydantic_ai_backends import create_console_toolset
 from pydantic_ai_todo import create_todo_toolset
 
 agent = create_deep_agent(
-    model="openai:gpt-4.1",
+    model="anthropic:claude-sonnet-4-6",
     toolsets=[create_todo_toolset(), create_console_toolset()],
 )
 ```
@@ -218,7 +218,7 @@ from pydantic_ai_shields import CostTracking
 from pydantic_deep.capabilities.hooks import HooksCapability, Hook, HookEvent
 
 agent = create_deep_agent(
-    model="openai:gpt-4.1",
+    model="anthropic:claude-sonnet-4-6",
     capabilities=[
         CostTracking(cost_budget_usd=5.0),
         HooksCapability(hooks=[

CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.3] - 2026-04-02
+
+### Changed
+
+- Default models changed: main agent `anthropic:claude-opus-4-6`, subagents `anthropic:claude-sonnet-4-6`, summarization `anthropic:claude-haiku-4-5-20251001`
+- Replaced `include_general_purpose_subagent` with `include_builtin_subagents` — adds a built-in "research" deep agent (filesystem + web + memory) instead of a plain pydantic-ai Agent
+- **Subagents are now deep agents by default** — all subagents (built-in and custom) are created via `create_deep_agent()` with filesystem, web, memory, eviction, and patch support. Custom subagents that don't specify `agent` or `agent_factory` automatically get the deep agent factory
+- Removed `skills` parameter from `create_deep_agent()` — pass pre-loaded skills via `SkillsToolset(skills=[...])` in the `toolsets` parameter instead
+- Removed `image_support` parameter from `create_deep_agent()` — image support is now always enabled (multimodal `read_file` for `.png`, `.jpg`, `.gif`, `.webp`)
+- Changed `include_memory` default from `False` to `True` — persistent agent memory is now enabled by default
+- Changed `max_nesting_depth` default from `0` to `1` — subagents can now spawn their own subagents by default
+- Simplified context file discovery to `AGENTS.md` and `SOUL.md` only (removed DEEP.md, AGENT.md, CLAUDE.md). Subagents see only `AGENTS.md`; `SOUL.md` is main-agent-only
+- Replaced `include_web` with separate `web_search` and `web_fetch` parameters (both default `True`) — allows independent control of WebSearch and WebFetch capabilities
+- Added `thinking` parameter (default `"high"`) — enables model thinking/reasoning via pydantic-ai `Thinking` capability. Supports `True`/`False`/`"minimal"`/`"low"`/`"medium"`/`"high"`/`"xhigh"`
+- Changed `eviction_token_limit` default from `None` to `20_000` — large tool outputs automatically saved to files
+- Changed `patch_tool_calls` default from `False` to `True` — orphaned tool calls fixed automatically
+- `BASE_PROMPT` is now always included in system prompt — `instructions` parameter appends to it instead of replacing it
+- Moved `model_settings` parameter next to `model` in `create_deep_agent()` signature
+
+### Added
+
+- 5 new hook events: `BEFORE_RUN`, `AFTER_RUN`, `RUN_ERROR`, `BEFORE_MODEL_REQUEST`, `AFTER_MODEL_REQUEST` — maps to pydantic-ai lifecycle hooks for session tracking, LLM call logging, and error alerts
+- `compact_conversation` tool — agent can manually trigger context compression with optional focus topic (uses `ContextManagerCapability.request_compact()`)
+- Anthropic prompt caching enabled by default (`anthropic_cache_instructions`, `anthropic_cache_tool_definitions`, `anthropic_cache_messages`) — silently ignored by non-Anthropic models
+- Built-in "research" subagent (`pydantic_deep/subagents.py`) — full deep agent for codebase exploration and web research
+- `upload_files()` batch method on `DeepAgentDeps` for uploading multiple files at once
+- `approve_tools` config in CLI — configure which tools require user approval (default: `["execute"]`). Set via `/config set approve_tools "execute,write_file,edit_file"` or in `config.toml`
+- Skills as slash commands in CLI — type `/code-review` to activate a skill directly from the picker
+- 3-tier skill discovery: built-in (`apps/cli/skills/`) → user (`~/.pydantic-deep/skills/`) → project (`.pydantic-deep/skills/`), with later sources overriding earlier by name
+- Provider setup wizard in CLI — first-run auto-detects missing API keys and guides through provider selection (Anthropic, OpenAI, Google, OpenRouter) with key input. Keys saved to `.pydantic-deep/.env`
+- `/provider` slash command — switch AI provider and model mid-session
+- `/config` slash command in CLI — view and change settings interactively (e.g., `/config set include_teams true`)
+- `web_search`, `web_fetch`, `thinking_effort`, and `include_teams` as configurable options in `config.toml`
+- ACP (Agent Client Protocol) adapter in `apps/acp/` — enables pydantic-deep agents to run inside editors like Zed. Streaming text deltas, tool call visibility with arguments and results, model switching, session management, auto-detect provider from API keys
+- Enhanced `BASE_PROMPT` with Claude Code-inspired sections: code quality, executing actions with care, tone and formatting
+- MCP documentation (`docs/advanced/mcp.md`) — shows how to use pydantic-ai's `MCP` capability with deep agents
+- Documentation for `BackendSkillsDirectory` in `docs/concepts/skills.md` — covers usage with `StateBackend`, `LocalBackend`, `DockerSandbox`, and mixed configurations
+- Cross-reference to backend-aware skills in `docs/concepts/backends.md`
+
+### Fixed
+
+- CLI bundled skills fallback path — was resolving to non-existent `apps/pydantic_deep/bundled_skills`, now correctly points to `apps/cli/skills/`
+
 ## [0.3.2] - 2026-03-31
 
 ### Added
@@ -103,7 +146,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - **`deps.todos` not synchronized with todo tools** — `create_todo_toolset()` was called without `storage=` parameter, creating an isolated `TodoStorage` disconnected from `deps.todos`. Todo tools wrote to their own internal list while `deps.todos`, `get_todo_prompt()`, and `share_todos` remained empty. Fixed with `_DepsTodoProxy` pattern that delegates reads/writes to `deps.todos` at runtime. Subagent todo toolsets use the same proxy pattern for consistency. ([#35](https://github.com/vstorm-co/pydantic-deepagents/issues/35))
-- **`Model` objects discarded for subagents** — `isinstance(model, str)` guard silently replaced `Model` objects (e.g. `TestModel()`, `AnthropicModel()`) with `DEFAULT_MODEL`. Subagents always used `openai:gpt-4.1` regardless of the model passed to `create_deep_agent()`. Changed to `model or DEFAULT_MODEL`. ([#34](https://github.com/vstorm-co/pydantic-deepagents/pull/34), by [@ret2libc](https://github.com/ret2libc))
+- **`Model` objects discarded for subagents** — `isinstance(model, str)` guard silently replaced `Model` objects (e.g. `TestModel()`, `AnthropicModel()`) with `DEFAULT_MODEL`. Subagents always used `anthropic:claude-sonnet-4-6` regardless of the model passed to `create_deep_agent()`. Changed to `model or DEFAULT_MODEL`. ([#34](https://github.com/vstorm-co/pydantic-deepagents/pull/34), by [@ret2libc](https://github.com/ret2libc))
 - **Binary file upload tests flaky on Linux** — `chardet` detected encoding for small byte sequences on Linux but not macOS, causing `line_count` assertions to fail in CI. Tests now mock `chardet.detect` for deterministic behavior.
 
 ### Changed
@@ -250,7 +293,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed `CLAUDE.md` - corrected `CompositeBackend` API signature (uses `default` and `routes`, not `backends`)
 - Fixed `README.md` - corrected import path `pydantic_deep.processors` to `pydantic_deep`
 - Fixed `docs/api/agent.md` - added missing `include_execute` parameter to signature and parameters table
-- Fixed `pydantic_deep/agent.py` - corrected docstring model default from "Claude Sonnet 4" to "openai:gpt-4.1"
+- Fixed `pydantic_deep/agent.py` - corrected docstring model default from "Claude Sonnet 4" to "anthropic:claude-sonnet-4-6"
 
 ## [0.2.13] - 2025-01-17
 

CLAUDE.md

@@ -206,7 +206,7 @@ from pydantic_ai_backends import create_console_toolset
 from pydantic_ai_todo import create_todo_toolset
 
 agent = create_deep_agent(
-    model="openai:gpt-4.1",
+    model="anthropic:claude-sonnet-4-6",
     toolsets=[create_todo_toolset(), create_console_toolset()],
 )
 ```
@@ -218,7 +218,7 @@ from pydantic_ai_shields import CostTracking
 from pydantic_deep.capabilities.hooks import HooksCapability, Hook, HookEvent
 
 agent = create_deep_agent(
-    model="openai:gpt-4.1",
+    model="anthropic:claude-sonnet-4-6",
     capabilities=[
         CostTracking(cost_budget_usd=5.0),
         HooksCapability(hooks=[

README.md

@@ -53,11 +53,12 @@ pydantic-deep implements the **deep agent pattern** -- the same architecture pow
 
 ---
 
-**pydantic-deep** is three things:
+**pydantic-deep** is four things:
 
 1. **A Python framework** for building Claude Code-style agents with planning, filesystem access, subagents, memory, and unlimited context
 2. **A CLI** that gives you a terminal AI assistant out of the box
-3. **DeepResearch** -- a full-featured research agent with web UI, web search, diagrams, and sandboxed code execution
+3. **An ACP adapter** that runs deep agents inside editors like Zed
+4. **DeepResearch** -- a full-featured research agent with web UI, web search, diagrams, and sandboxed code execution
 
 ---
 
@@ -96,7 +97,7 @@ pydantic-deep run "Build a web scraper" --sandbox
 pydantic-deep chat --model anthropic:claude-sonnet-4-20250514
 
 # Manage config
-pydantic-deep config set model openai:gpt-4.1
+pydantic-deep config set model anthropic:claude-sonnet-4-6
 ```
 
 > See [CLI docs](docs/cli/index.md) for the full reference.
@@ -125,15 +126,17 @@ One function call gives you an agent with planning, filesystem tools, subagents,
 
 ```python
 agent = create_deep_agent(
-    model="openai:gpt-4.1",
+    model="anthropic:claude-sonnet-4-6",
     include_todo=True,          # Task planning
     include_filesystem=True,    # File read/write/edit/execute
     include_subagents=True,     # Delegate to subagents
     include_skills=True,        # Domain-specific skills from SKILL.md files
     include_memory=True,        # Persistent MEMORY.md across sessions
     include_plan=True,          # Structured planning before execution
     include_teams=True,         # Multi-agent teams with shared TODOs
-    include_web=True,           # Built-in WebSearch() and WebFetch() capabilities
+    web_search=True,            # WebSearch capability
+    web_fetch=True,             # WebFetch capability
+    thinking="high",            # Thinking/reasoning effort
     context_manager=True,       # Auto-summarization for unlimited context
     cost_tracking=True,         # Token/USD budget enforcement
     include_checkpoints=True,   # Save, rewind, and fork conversations
@@ -192,25 +195,98 @@ agent = create_deep_agent(
 )
 ```
 
-### Custom Subagents
+### MCP Servers
+
+Connect to any [MCP](https://modelcontextprotocol.io/) server via pydantic-ai's `MCP` capability:
+
+```python
+from pydantic_ai.capabilities import MCP
+
+agent = create_deep_agent(
+    capabilities=[
+        MCP(url="https://mcp.example.com/api"),
+    ],
+)
+```
+
+### Subagents
+
+A built-in **research** subagent is included by default. Add your own:
 
 ```python
 agent = create_deep_agent(
     subagents=[
         {
             "name": "code-reviewer",
             "description": "Reviews code for quality issues",
-            "instructions": "You are a senior code reviewer...",
-            "preferred_mode": "sync",
+            "instructions": "Check for security, performance, error handling...",
         },
     ],
 )
+# The main agent delegates: task(description="Review auth.py", subagent_type="code-reviewer")
+```
+
+All subagents are full deep agents with filesystem, web, and memory tools. You only provide the specialized `instructions` — the framework adds `BASE_PROMPT` automatically.
+
+### Project Files
+
+pydantic-deep recognizes three special markdown files:
+
+| File | Purpose | Who Sees It |
+|------|---------|-------------|
+| `AGENTS.md` | Project instructions, conventions, architecture | Main agent + subagents |
+| `SOUL.md` | Agent personality, style, user preferences | Main agent only |
+| `MEMORY.md` | Persistent memory across sessions (read/write/update tools) | Per-agent (isolated) |
+
+```python
+agent = create_deep_agent(
+    context_discovery=True,  # Auto-discover AGENTS.md and SOUL.md at backend root
+    include_memory=True,     # MEMORY.md with read/write/update tools (on by default)
+)
 ```
 
+`AGENTS.md` follows the [agents.md spec](https://agents.md/) — compatible with other agent frameworks.
+
 > See the full [API reference](https://vstorm-co.github.io/pydantic-deepagents/api/toolsets/) for all options.
 
 ---
 
+## ACP -- Editor Integration (Zed)
+![zed.png](assets/zed.png)
+
+Run pydantic-deep agents inside [Zed](https://zed.dev) via the [Agent Client Protocol](https://agentclientprotocol.com):
+
+```bash
+pip install pydantic-deep[acp]
+python -m apps.acp
+```
+
+Add to Zed settings (`Cmd+,`):
+
+```json
+{
+  "agent_servers": {
+    "pydantic-deep": {
+      "type": "custom",
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "apps.acp"],
+      "cwd": "/path/to/pydantic-deep"
+    }
+  }
+}
+```
+
+API keys are loaded from `~/.pydantic-deep/.env` (global) or `.pydantic-deep/.env` (per-project):
+
+```bash
+mkdir -p ~/.pydantic-deep
+echo 'OPENROUTER_API_KEY=sk-or-your-key' > ~/.pydantic-deep/.env
+```
+
+> See [ACP README](apps/acp/README.md) for full configuration.
+
+---
+
 ## DeepResearch -- Reference App
 
 A full-featured research agent with web UI, built entirely on pydantic-deep.

apps/acp/README.md

@@ -0,0 +1,130 @@
+# ACP Adapter for pydantic-deep
+
+[Agent Client Protocol (ACP)](https://agentclientprotocol.com) adapter that enables pydantic-deep agents to run inside editors like [Zed](https://zed.dev).
+
+## Installation
+
+```bash
+pip install pydantic-deep[acp]
+```
+
+## Quick Start
+
+```bash
+python -m apps.acp
+```
+
+The server auto-detects your API key from environment variables or `.env` files and picks the right provider.
+
+## API Key Setup
+
+The ACP server looks for API keys in this order:
+
+1. **Environment variables** (e.g., `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`)
+2. **`~/.pydantic-deep/.env`** — global, all projects
+3. **`.pydantic-deep/.env`** — per-project
+4. **`.env`** — current directory
+
+Create one:
+
+```bash
+# Global (recommended)
+mkdir -p ~/.pydantic-deep
+echo 'OPENROUTER_API_KEY=sk-or-your-key' > ~/.pydantic-deep/.env
+
+# Or per-project
+echo 'ANTHROPIC_API_KEY=sk-ant-your-key' > .pydantic-deep/.env
+```
+
+The server auto-detects the provider from available keys:
+- `ANTHROPIC_API_KEY` → `anthropic:claude-sonnet-4-6`
+- `OPENROUTER_API_KEY` → `openrouter:anthropic/claude-sonnet-4`
+- `OPENAI_API_KEY` → `openai:gpt-4.1`
+- `GOOGLE_API_KEY` → `google:gemini-2.5-pro`
+
+## Zed Configuration
+
+Add to your Zed settings (`Cmd+,` → edit JSON):
+
+```json
+{
+  "agent_servers": {
+    "pydantic-deep": {
+      "type": "custom",
+      "command": "/path/to/your/venv/bin/python",
+      "args": ["-m", "apps.acp"],
+      "cwd": "/path/to/pydantic-deep"
+    }
+  }
+}
+```
+
+Find your Python path:
+
+```bash
+# From the pydantic-deep directory
+echo "$(pwd)/.venv/bin/python"
+```
+
+After saving, "pydantic-deep" appears in Zed's agent panel.
+
+## Features
+
+- Streaming text responses with real-time deltas
+- Tool call visibility with arguments (`read_file: /src/main.py`, `grep: TODO`)
+- Tool results displayed inline (file contents, search results, command output)
+- Model switching mid-session via Zed's model picker
+- Auto-detect provider from API keys
+- Session management with conversation history
+- Context file discovery (AGENTS.md, SOUL.md)
+- Full pydantic-deep toolset (filesystem, web, memory, skills, subagents)
+
+## CLI Options
+
+```bash
+python -m apps.acp                                    # Auto-detect model
+python -m apps.acp --model anthropic:claude-opus-4-6  # Specific model
+python -m apps.acp --cwd /path/to/project             # Working directory
+```
+
+## Custom Agent Factory
+
+```python
+from apps.acp.server import DeepAgentACP, AgentSessionContext
+from pydantic_deep import create_deep_agent
+
+def build_agent(ctx: AgentSessionContext):
+    return create_deep_agent(
+        model=ctx.model,
+        include_memory=True,
+        context_discovery=True,
+        thinking="high",
+    )
+
+server = DeepAgentACP(
+    agent=build_agent,
+    models=[
+        {"value": "anthropic:claude-opus-4-6", "name": "Claude Opus 4.6"},
+        {"value": "anthropic:claude-sonnet-4-6", "name": "Claude Sonnet 4.6"},
+    ],
+)
+```
+
+## Architecture
+
+```
+Editor (Zed)
+    |
+    |  ACP protocol (stdio)
+    |  - text deltas
+    |  - tool call start/complete with content
+    |  - model switching
+    |
+    v
+DeepAgentACP (apps/acp/server.py)
+    |
+    |  pydantic-ai Agent.iter() + node.stream()
+    |
+    v
+create_deep_agent() -- full deep agent with all tools
+```

apps/acp/__init__.py

@@ -0,0 +1,5 @@
+"""ACP (Agent Client Protocol) adapter for pydantic-deep.
+
+Bridges pydantic-deep agents with the Agent Client Protocol,
+enabling integration with editors like Zed.
+"""