0.3.12

[0.3.12] - 2026-04-13

Added

• Bandit security scanner — Bandit is now part of the development toolchain and CI pipeline. It runs on every commit via the new security job in GitHub Actions and is also available locally via make security. The scanner checks production code (pydantic_deep/) for common Python security vulnerabilities (CWE-listed issues). No medium- or high-severity findings block a merge.
• GitHub Issue Templates — structured forms for bug reports and feature requests guide contributors to provide the right information. Blank issues are disabled; the config redirects security reports to security@vstorm.co.
• Pull Request Template — a checklist-based PR template ensures contributors verify tests, linting, type checking, and the security scan before requesting review.

Fixed

• MD5 usedforsecurity flag (StuckLoopDetection) — hashlib.md5() calls used for tool-call fingerprinting in stuck_loop.py now pass usedforsecurity=False, correctly signalling that the hash is used for deduplication (not cryptographic security). This resolves a Bandit B324 High-severity finding.

Changed

• CONTRIBUTING.md — expanded with an explicit test policy (new functionality requires tests; 100 % coverage is enforced mechanically), a coding-standards reference table (Ruff, Pyright, MyPy, Bandit with pyproject.toml links), English-language requirement, API docs pointer, and a static-analysis section documenting all quality gates.
• make all — now includes make security (Bandit scan) in addition to the existing format → lint → typecheck → testcov sequence.
• Docs site — homepage (docs/index.md) rewritten with a plain-language problem/solution description and explicit "Next Steps" links to Installation, Getting Help, and Contributing. New docs/contributing.md page added to the nav, covering setup, PR requirements, and test policy. docs/index.md subtitle updated to remove jargon.
• OpenSSF Best Practices badge — badge embedded in README and docs homepage; badge targets project ID 12495 at bestpractices.dev.

0.3.11

[0.3.11] - 2026-04-13

Fixed

• Browser opens on every message (BrowserCapability) — async_playwright() was entered eagerly
  at the start of wrap_run, spawning the Playwright Node.js driver process (which in turn opened a
  browser window) on every agent run — even when no browser tool was ever called. The Playwright context
  manager is now entered lazily inside the first-tool-call launcher, so runs that never use the browser
  incur zero Playwright overhead and no browser process is started.
• Browser window always visible (browser_headless default) — the CLI config defaulted
  browser_headless = false, meaning any browser launch produced a visible Chrome window. Changed to
  browser_headless = true.

0.3.10

[0.3.10] - 2026-04-12

Changed

• Version re-release of 0.3.9 — 0.3.9 was published to PyPI and this release carries
  the same changes forward under a new version number. No functional differences from 0.3.9.

0.3.9

[0.3.9] - 2026-04-12

Added

• Chromium auto-install (BrowserCapability.auto_install) — when the Chromium binary is missing,
  BrowserCapability now automatically runs playwright install chromium via the current Python
  interpreter before the first agent run. On success the launch is retried immediately; on failure the
  browser degrades gracefully (tools hidden, no instructions injected) without crashing the agent.
  Controlled via auto_install: bool = True on BrowserCapability.

Changed

• install.sh now ships browser support out of the box — the one-line installer now installs
  pydantic-deep[cli,browser] (was [cli]) and runs playwright install chromium automatically.
  New users get a fully working browser without any manual steps.
• Browser tool usage guidance — BROWSER_INSTRUCTIONS now includes an explicit "when to use
  browser vs web_search / web_fetch" section. The model is instructed to prefer the lighter
  web_search / web_fetch tools for information lookup and static pages, and to reserve the
  Playwright browser for interactive workflows (login, forms, JS-heavy SPAs, screenshots).

0.3.8

[0.3.8] - 2026-04-12

Added

• Automatic context limit warnings (LimitWarnerCapability) — the agent now receives URGENT/CRITICAL
  warnings injected as user messages when approaching the context window limit. Warnings start at 70% usage
  (well before auto-compression at 90%), giving the model time to wrap up or use /compact. Previously only
  the TUI status bar showed context usage — the model itself had no awareness of approaching limits.
  Enabled automatically when context_manager=True (the default)
• Stuck loop detection (StuckLoopDetection) — new capability that detects repetitive agent behavior
  and intervenes before the agent wastes tokens. Detects three patterns: repeated identical tool calls,
  A-B-A-B alternating calls, and no-op calls (same result). Configurable threshold (max_repeated, default 3)
  and action (warn via ModelRetry or error via StuckLoopError). Per-run state isolation via for_run().
  Enabled by default via stuck_loop_detection=True in create_deep_agent()
• BM25-ranked history search — search_conversation_history now uses BM25 ranking instead of naive
  substring matching. Multi-word queries are tokenized — each word is scored independently, rare terms
  (high IDF) rank higher than common ones, and results are sorted by relevance score. Zero dependencies
  (pure Python implementation using the standard Elasticsearch/Lucene BM25 formula)
• Expanded context file discovery — DEFAULT_CONTEXT_FILENAMES now discovers 7 convention file types
  instead of 2: added CLAUDE.md, .cursorrules, .github/copilot-instructions.md, CONVENTIONS.md,
  and CODING_GUIDELINES.md alongside the existing AGENTS.md and SOUL.md. Subagent allowlist updated
  to include CLAUDE.md (project instructions relevant to subagents)

Changed

• Eviction uses after_tool_execute hook instead of history processor — large tool outputs are now
  intercepted before they enter message history via the new EvictionCapability, rather than after
  the fact via EvictionProcessor (history processor). This means the full output never bloats the message
  list in memory. The old EvictionProcessor is preserved for backward compatibility but
  create_deep_agent() now uses EvictionCapability by default
• Orphan repair uses before_model_request hook instead of history processor — PatchToolCallsCapability
  replaces patch_tool_calls_processor as the default in create_deep_agent(). Integrates with the
  pydantic-ai capabilities system instead of raw history processors. The old processor function is preserved
  for backward compatibility and standalone use

Fixed

• Browser tools never require approval — BrowserCapability now uses prepare_tools to force
  kind='function' on all browser tools (navigate, click, execute_js, etc.), ensuring they never
  trigger approval dialogs even if a user adds browser tool names to approve_tools
• Checkpoint per-run state isolation — CheckpointMiddleware now implements for_run() to return a
  fresh instance per agent run with isolated _turn_counter and _latest_messages. Previously, concurrent
  agent.run() calls on the same agent would share and corrupt checkpoint state

0.3.7

[0.3.7] - 2026-04-11

Fixed

• web_search not working for non-Anthropic and OpenRouter models — duckduckgo local fallback was not
  included in cli / tui extras, so WebSearch silently fell back to native-only mode. Models accessed
  through OpenRouter (or any provider without native web-search support) would report no web_search tool.
  pydantic-ai-slim[duckduckgo] is now bundled in both cli and tui extras

0.3.6

[0.3.6] - 2026-04-11

Added

• One-command installer (install.sh) — macOS and Linux users can now install pydantic-deep without knowing
  Python or pip. A single curl command installs uv (if missing) and then the CLI:

  curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deep/main/install.sh | bash

  The script auto-detects uv, falls back to installing it via astral.sh/uv, then runs
  uv tool install "pydantic-deep[cli]". Verifies the installation and prints PATH instructions
  if the binary is not immediately discoverable
• pydantic-deep update command — self-update command that upgrades to the latest PyPI release.
  Uses uv tool upgrade pydantic-deep when uv is available; falls back to
  pip install --upgrade "pydantic-deep[cli]" otherwise
• Startup update notifications — on every CLI invocation the tool silently checks PyPI for a newer
  version and prints a one-line notice when one is found:

  Update available: v0.3.6 → v0.3.7  Run: pydantic-deep update
  

  The check is backed by a 24-hour file cache (~/.pydantic-deep/update_check.json) so the network
  is only hit once per day. A 2-second timeout ensures the check never blocks startup

Fixed

• ModuleNotFoundError: No module named 'textual' on fresh install — textual was listed under the
  tui optional extra but missing from cli, so uv tool install "pydantic-deep[cli]" produced a broken
  installation that crashed immediately on launch. textual>=3.0.0 is now included in both cli and tui

0.3.5

[0.3.5] - 2026-04-10

Added

• Headless runner (pydantic-deep run) — new CLI command for non-interactive task execution. Designed for
  benchmarks (Terminal Bench), CI/CD pipelines, and scripted automation. All feature flags mirror the TUI and default
  from .pydantic-deep/config.toml. Supports --task-file, --json, --max-turns, --timeout, --model,
  --working-dir, --web-search/--no-web-search, --web-fetch/--no-web-fetch, --thinking, --todo/--no-todo,
  --subagents/--no-subagents, --skills/--no-skills, --plan/--no-plan, --memory/--no-memory,
  --teams/--no-teams, --context/--no-context, --temperature
• Harbor adapter (apps/harbor/) — BaseInstalledAgent implementation for Terminal Bench evaluation via Harbor.
  Installs pydantic-deep in the container via uv, runs tasks with pydantic-deep run --json, parses JSON output for
  usage stats. Supports model name conversion (provider/model to provider:model), API key forwarding, custom git ref
  via PYDANTIC_DEEP_GIT_REF env var. All headless feature flags configurable via Harbor --ak kwargs (e.g.
  --ak web_search=false)
• DEFAULT_USAGE_LIMITS — framework-wide UsageLimits(request_limit=None) exported from pydantic_deep.deps.
  Removes pydantic-ai's default 50-request limit which caused UsageLimitExceeded crashes on complex benchmark tasks.
  Applied in both headless runner and TUI
• Docker sandbox for CLI (--sandbox docker) — run the agent inside a Docker container for isolated code execution.
  The TUI and headless runner stay in the terminal but all file operations and shell commands execute inside the
  container. The working directory is mounted at /workspace (read-write) so project files are shared. Container is
  automatically stopped on exit. Supports both pydantic-deep tui --sandbox docker and
  pydantic-deep run "task" --sandbox docker. Configurable via sandbox and sandbox_image in
  .pydantic-deep/config.toml. Requires pydantic-ai-backend[docker]
• Named workspaces (--workspace <name>) — shared Docker environment that persists across threads. Installed
  packages and any state outside the mounted volume survive between sessions. Multiple conversation threads can share
  the same workspace — each thread keeps its own history (.pydantic-deep/sessions/{thread_id}/messages.json) while the
  Docker container and its state are shared. Usage: pydantic-deep tui --workspace ml-env or
  pydantic-deep run "task" --workspace dev. Implies --sandbox docker automatically
• Workspace management (pydantic-deep sandbox) — new subcommands: sandbox list shows Docker workspaces for the
  current project with status/image/creation date; sandbox stop <name> stops a specific workspace;
  sandbox stop all --rm stops and removes all project workspaces
• Browser automation (BrowserCapability) — Playwright-based browser control via pydantic-deep[browser].
  Gives agents 9 tools: navigate, click, type_text, get_text, screenshot, scroll, go_back, go_forward,
  execute_js. Single-tab design with automatic popup interception. Domain allowlist, content truncation, and optional
  auto-screenshot on navigate. Browser lifecycle managed by wrap_run — Chromium starts before agent runs, closes
  after (on success, exception, or cancellation). Requires playwright>=1.40.0 and playwright install chromium.
  Optional html2text>=2020.1 for better content extraction
• --browser/--no-browser CLI flag — opt-in browser automation for pydantic-deep tui and pydantic-deep run.
  Disabled by default (include_browser = false). Enable with --browser flag or include_browser = true in
  config.toml
• --browser-headless/--browser-headed CLI flag — control browser window visibility. Default is headed (window
  visible, browser_headless = false). Use --browser-headless for CI/scripted use, --browser-headed for
  interactive sessions
• BrowseResult type — structured result from browser operations: url, title, content, screenshot,
  error fields. Exported from pydantic_deep.types
• browser extras — pip install 'pydantic-deep[browser]' installs playwright>=1.40.0 and html2text>=2020.1.
  Added to all extras

Changed

• create_cli_agent() feature flags now read from config.toml — include_skills, include_plan, include_memory,
  include_subagents, include_todo, context_discovery, web_search, web_fetch, thinking, include_teams, and
  temperature all default to None (= read from config). Previously hardcoded to True, ignoring config.toml values.
  Explicit parameters still override config
• Headless runner uses same defaults as TUI — pydantic-deep run no longer hardcodes include_plan=False and
  include_memory=False. All features inherit from config.toml, overridable via CLI flags
• Headless runner auto-initializes .pydantic-deep/ — pydantic-deep run now calls ensure_initialized() before
  creating the agent, ensuring config, skills, and memory scaffolding exist in the working directory
• Default model changed to anthropic:claude-opus-4-6 — updated in CliConfig, init.py template, and model
  picker
• Model picker updated — 25 OpenRouter models (Anthropic, OpenAI, Google, Z-AI, X-AI), refreshed
  Anthropic/OpenAI/Google direct models
• Prompt stack deduplicated — BASE_PROMPT was included twice (framework + CLI layer). CLI prompt now only adds
  CLI-specific sections (Path Handling, Exactness, Provided Data). Removed redundant "Bias Towards Action", "Avoid
  Over-Engineering", "Parallel Tool Calls" from CLI layer (already in BASE_PROMPT)
• Prompt streamlined — removed "Executing Actions with Care" section (approve_tools handles this mechanically),
  merged "Tone and Formatting" + "Progress Updates" into 3-line "Output" section, added 5-step workflow (Research →
  Understand → Implement → Verify → Retry), strengthened error handling with "NEVER declare done if last test failed"
• Directory tree excludes .pydantic-deep/ — sessions, logs, and config internals no longer leak into the system
  prompt tree
• TUI: all tool calls now visible — todo tools (read_todos, write_todos, add_todo, update_todo_status,
  remove_todo) are no longer hidden from the UI
• TUI: side panel visible by default — shows on startup when terminal >= 100 chars wide, responsive to resize
• TUI: default subagents shown on startup — side panel lists available subagents (planner, research) with idle
  status before any delegation occurs
• TUI: thinking content displayed — model thinking/reasoning streamed live as dimmed text, collapsed to summary
  after completion
• TUI: per-turn token usage — each assistant response shows in:X · out:Y · total:Z · reqs:N below the text
• TUI: header shows cumulative tokens and cost — in:45K out:3K · $0.12 in the top bar after responses
• TUI: all notifications logged — DeepApp.notify() override and notify_error/warning/success helpers write to
  per-session log file
• TUI: session saved on error — _save_session() moved to finally block so messages.json is persisted even
  after agent crashes or cancellation
• TUI: subagent output fully logged — tool_log.jsonl stores up to 20K chars for subagent task results (was 2K),
  debug log includes full output for task tool calls

Fixed

• ensure_initialized() now always populates missing scaffolding — previously only ran init_project when
  .pydantic-deep/ didn't exist at all. Now always runs idempotent init, so missing built-in skills, config, or memory
  templates are added to existing directories
• contextlib scope error in chat.py — import contextlib was inside except block but used in finally. Moved
  to top-level import
• CostUpdated message routing — _on_cost_update callback now posts to app.screen (not app), fixing Textual
  message routing so ChatScreen.on_cost_updated actually receives cost/token updates

0.3.4

[0.3.4] - 2026-04-09

Changed

• Merged TUI into apps/cli/ — removed old interactive/non-interactive CLI, TUI is now the default interface. Running pydantic-deep without a subcommand launches the TUI
• Redesigned /improve pipeline — added UserFactInsight and AgentLearningInsight extraction categories; relaxed synthesis rules so user facts from a single session are accepted; MEMORY.md is now the primary target for personal facts and agent learnings
• Configurable context file paths in /improve — ImprovementAnalyzer accepts context_files mapping for backend-agnostic path resolution (supports LocalBackend, Docker, etc.)
• Structured tool call logging — sessions now save tool_log.jsonl alongside messages.json for richer execution traces (inspired by Meta-Harness)
• Raw tool traces in synthesis — synthesis agent receives both extracted insights and raw tool call sequences, following Meta-Harness finding that raw traces >> summaries
• Debug logging — per-session logs in .pydantic-deep/logs/ with latest.log symlink
• Added /config command to TUI for viewing and updating config.toml

Fixed

• /improve crash — unescaped {} in prompt templates caused str.format() errors
• /improve silent failures — extraction errors were swallowed; now reports failed_sessions count and last_error
• /improve API key missing — improve pipeline now loads keys from keystore before creating agents
• /improve wrong model — used hardcoded OpenRouter fallback; now uses current agent's model
• /improve MEMORY.md path mismatch — wrote to project root instead of .pydantic-deep/main/MEMORY.md

Removed

• Old interactive CLI (apps/cli/interactive.py, non_interactive.py, display.py, etc.)
• run and chat CLI commands (replaced by TUI)
• Dead agent_worker.py code

0.3.3

[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/