Merge pull request #85 from vstorm-co/issue/84

Issue/84

Author: DEENUU1

CHANGELOG.md

@@ -5,6 +5,14 @@ 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.16] - 2026-04-22
+
+### Changed
+
+- **`instructions` now replaces `BASE_PROMPT` instead of appending to it** — previously, passing `instructions="..."` to `create_deep_agent()` produced a system prompt of `BASE_PROMPT + "\n\n" + instructions`. Now `instructions` is used verbatim as the full system prompt. `instructions=None` (the default) keeps the existing behaviour — `BASE_PROMPT` is used automatically. Users who want to extend the default rather than replace it can do so with an f-string: `instructions=f"{BASE_PROMPT}\n\nYour extra text"`. `BASE_PROMPT` is exported from the top-level package. ([#84](https://github.com/vstorm-co/pydantic-deepagents/issues/84), reported by [@rremilian](https://github.com/rremilian))
+- **Subagent and team-member factories always prepend `BASE_PROMPT`** — agents spawned automatically by the `task()` tool or `spawn_team()` continue to receive `BASE_PROMPT` followed by their task-specific `instructions`, so subagent behaviour is unchanged.
+- **`apps/deepresearch` double-prompt bug fixed** — `MAIN_INSTRUCTIONS` already contained `BASE_PROMPT`; it was previously duplicated in the final system prompt because the old append logic prepended it again. The new semantics resolve this without any change to the deepresearch app itself.
+
 ## [0.3.15] - 2026-04-17
 
 ### Fixed

README.md

@@ -36,6 +36,7 @@
 
 ## What's New
 
+- **2026-04-22**  **v0.3.16** — `instructions=` now replaces `BASE_PROMPT` directly. Use `f"{BASE_PROMPT}\n\n..."` to extend it. Subagents still get `BASE_PROMPT` automatically.
 - **2026-04-12**  **v0.3.8** — Stuck loop detection, context limit warnings for the model, expanded context file discovery (CLAUDE.md, .cursorrules, etc.), eviction & orphan repair migrated to capabilities hooks.
 - **2026-04-11**  **v0.3.6** — One-command installer + self-update: `curl -fsSL .../install.sh | bash` installs everything automatically. New `pydantic-deep update` command. Startup update notifications with 24-hour PyPI cache.
 - **2026-04-10**  **v0.3.5** — Headless runner (`pydantic-deep run`), Docker sandbox with named workspaces, browser automation via Playwright, Harbor adapter for Terminal Bench evaluation.

apps/cli/agent.py

@@ -8,7 +8,7 @@
 from pydantic_ai_backends import LocalBackend
 
 from apps.cli.prompts import build_cli_instructions
-from pydantic_deep.agent import create_deep_agent
+from pydantic_deep.agent import DEFAULT_INSTRUCTIONS, create_deep_agent
 from pydantic_deep.capabilities.hooks import Hook, HookEvent, HookInput, HookResult
 from pydantic_deep.deps import DeepAgentDeps
 
@@ -170,10 +170,13 @@ def create_cli_agent(  # noqa: C901
     if extra_middleware:
         middleware.extend(extra_middleware)
 
-    # Build dynamic system prompt (tool-specific guidance lives in tool descriptions)
-    instructions = build_cli_instructions(
-        non_interactive=non_interactive,
-        lean=lean,
+    instructions = (
+        DEFAULT_INSTRUCTIONS
+        + "\n\n"
+        + build_cli_instructions(
+            non_interactive=non_interactive,
+            lean=lean,
+        )
     )
 
     # Append working directory context

apps/cli/prompts.py

@@ -203,8 +203,6 @@ def build_cli_instructions(
     if non_interactive and lean:
         return _LEAN_NON_INTERACTIVE
 
-    # NOTE: BASE_PROMPT is prepended by create_deep_agent() — do NOT include it here.
-    # CLI prompt only adds CLI-specific sections on top of the framework base.
     parts: list[str] = [_CLI_CORE, _CODE_QUALITY_SECTION]
 
     if non_interactive:

docs/advanced/subagents.md

@@ -72,7 +72,7 @@ task(
 This:
 
 1. Creates a **deep agent** (`create_deep_agent()`) with:
-   - `BASE_PROMPT` + subagent's `instructions` as system prompt
+   - `BASE_PROMPT` prepended to the subagent's `instructions` as system prompt
    - Filesystem, web, todo, memory tools
    - Eviction and patch tool calls support
 2. Clones dependencies with:

docs/concepts/agents.md

@@ -33,6 +33,8 @@ agent = create_deep_agent(model=TestModel())
 
 ### Custom Instructions
 
+The `instructions` parameter sets the agent's system prompt. When provided, it **replaces** the built-in [`BASE_PROMPT`][pydantic_deep.prompts.BASE_PROMPT] entirely:
+
 ```python
 agent = create_deep_agent(
     instructions="""
@@ -46,6 +48,24 @@ agent = create_deep_agent(
 )
 ```
 
+To build on top of the default behavior instead of replacing it, import `BASE_PROMPT` and compose with an f-string:
+
+```python
+from pydantic_deep import BASE_PROMPT, create_deep_agent
+
+agent = create_deep_agent(
+    instructions=f"""{BASE_PROMPT}
+
+    ## Extra Guidelines
+
+    You are a Python expert. Always use type hints and docstrings.
+    """
+)
+```
+
+!!! note "Subagent instructions work differently"
+    The `instructions` field in [`SubAgentConfig`][pydantic_deep.types.SubAgentConfig] is always **appended** to `BASE_PROMPT` automatically — you only write the specialized part. This keeps subagent configs concise.
+
 ### Enabling/Disabling Features
 
 ```python
@@ -321,15 +341,15 @@ Pydantic Deep Agents uses a dynamic system prompt mechanism that automatically c
 ```python
 # The agent automatically includes relevant prompts based on enabled features
 agent = create_deep_agent(
-    instructions="You are a Python expert.",  # Your base instructions
+    instructions="You are a Python expert.",  # Replaces BASE_PROMPT
     include_todo=True,        # Adds todo prompt
     include_filesystem=True,  # Adds console prompt
     include_subagents=True,   # Adds subagent prompt
     include_skills=True,      # Adds skills prompt
 )
 
 # At runtime, the agent sees:
-# 1. Your instructions: "You are a Python expert."
+# 1. Static instructions: "You are a Python expert."  (or BASE_PROMPT if instructions=None)
 # 2. Uploaded files: "## Uploaded Files\n- /uploads/data.csv (1024 bytes, 50 lines)"
 # 3. Todo prompt: "## Current Todos\n- [ ] Analyze data..."
 # 4. Console prompt: "## File Operations\nYou can use ls, read_file, write_file..."

docs/examples/basic-usage.md

@@ -158,7 +158,7 @@ Usage Statistics:
 ```python
 agent = create_deep_agent(
     model="anthropic:claude-sonnet-4-6",  # LLM model
-    instructions="...",                           # System prompt
+    instructions="...",                   # System prompt (replaces built-in BASE_PROMPT)
 )
 ```
 

pydantic_deep/agent.py

@@ -70,6 +70,7 @@ def create_deep_agent(
     model: str | Model | None = None,
     model_settings: dict[str, Any] | None = None,
     summarization_model: str | None = None,
+    base_prompt: str | None = None,
     instructions: str | None = None,
     output_style: str | Any | None = None,
     styles_dir: str | list[str] | None = None,
@@ -137,6 +138,7 @@ def create_deep_agent(
     model: str | Model | None = None,
     model_settings: dict[str, Any] | None = None,
     summarization_model: str | None = None,
+    base_prompt: str | None = None,
     instructions: str | None = None,
     output_style: str | Any | None = None,
     styles_dir: str | list[str] | None = None,
@@ -204,6 +206,7 @@ def create_deep_agent(  # noqa: C901
     model: str | Model | None = None,
     model_settings: dict[str, Any] | None = None,
     summarization_model: str | None = None,
+    base_prompt: str | None = None,
     instructions: str | None = None,
     output_style: str | Any | None = None,
     styles_dir: str | list[str] | None = None,
@@ -277,7 +280,10 @@ def create_deep_agent(  # noqa: C901
 
     Args:
         model: Model to use (default: anthropic:claude-opus-4-6).
-        instructions: Custom instructions for the agent.
+        instructions: System prompt for the agent. When provided, replaces the
+            default ``BASE_PROMPT`` entirely. Use ``BASE_PROMPT`` from
+            ``pydantic_deep`` to build on top of it:
+            ``instructions=f"{BASE_PROMPT}\\n\\nYour extra instructions"``.
         output_style: Output style to apply to agent responses. Can be a
             string name of a built-in style ("concise", "explanatory",
             "formal", "conversational"), a custom OutputStyle instance,
@@ -564,9 +570,15 @@ def _set_toolset_retries(toolset: AbstractToolset[DeepAgentDeps], max_retries: i
 
         def _default_deep_agent_factory(cfg: dict[str, Any]) -> Any:
             """Create a deep agent for subagent execution."""
+            _sub_task_instructions = cfg.get("instructions") or ""
+            _sub_instructions = (
+                DEFAULT_INSTRUCTIONS + "\n\n" + _sub_task_instructions
+                if _sub_task_instructions
+                else DEFAULT_INSTRUCTIONS
+            )
             return create_deep_agent(
                 model=cfg.get("model", _sub_model),
-                instructions=cfg["instructions"],
+                instructions=_sub_instructions,
                 include_filesystem=True,
                 include_execute=True,
                 include_todo=True,
@@ -732,9 +744,15 @@ def _default_deep_agent_factory(cfg: dict[str, Any]) -> Any:
             _team_edit_fmt = edit_format
 
             def _deep_agent_factory(cfg: dict[str, Any]) -> Any:  # pragma: no cover
+                _team_task_instructions = cfg.get("instructions") or ""
+                _team_instructions = (
+                    DEFAULT_INSTRUCTIONS + "\n\n" + _team_task_instructions
+                    if _team_task_instructions
+                    else DEFAULT_INSTRUCTIONS
+                )
                 return create_deep_agent(
                     model=cfg.get("model", _team_model),
-                    instructions=cfg["instructions"],
+                    instructions=_team_instructions,
                     include_filesystem=True,
                     include_todo=True,
                     include_subagents=False,
@@ -751,10 +769,7 @@ def _deep_agent_factory(cfg: dict[str, Any]) -> Any:  # pragma: no cover
         team_toolset = create_team_toolset(**_team_kwargs)
         all_toolsets.append(team_toolset)
 
-    # Build base instructions — always include BASE_PROMPT, append user instructions
-    base_instructions = DEFAULT_INSTRUCTIONS
-    if instructions:
-        base_instructions = base_instructions + "\n\n" + instructions
+    base_instructions = instructions if instructions is not None else DEFAULT_INSTRUCTIONS
 
     # Improve toolset (self-improvement from session analysis)
     if include_improve:

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic-deep"
-version = "0.3.15"
+version = "0.3.16"
 description = "Batteries-included agent harness for Python — tool-calling, sandboxed execution, multi-agent teams, and unlimited context on Pydantic AI"
 readme = "README.md"
 keywords = [

tests/test_agent.py

@@ -99,6 +99,41 @@ def _sub_caps(parent_web_search: bool, parent_web_fetch: bool) -> list[type]:
         assert WebSearch in on_types
         assert WebFetch in on_types
 
+    def test_default_subagent_factory_prepends_base_prompt(self):
+        """Subagent factory always prepends BASE_PROMPT before task instructions."""
+        from pydantic_deep.prompts import BASE_PROMPT
+
+        subagents: list[SubAgentConfig] = [
+            SubAgentConfig(
+                name="researcher",
+                description="A research agent",
+                instructions="Research topics carefully.",
+            ),
+        ]
+        create_deep_agent(model=TEST_MODEL, subagents=subagents)
+        factory = subagents[0]["agent_factory"]
+        assert factory is not None
+        sub_agent = factory({"instructions": "Research topics carefully.", "model": TEST_MODEL})
+        assert any(BASE_PROMPT in str(i) for i in sub_agent._instructions)
+        assert any("Research topics carefully." in str(i) for i in sub_agent._instructions)
+
+    def test_default_subagent_factory_no_task_instructions(self):
+        """Subagent factory with empty instructions uses only BASE_PROMPT."""
+        from pydantic_deep.prompts import BASE_PROMPT
+
+        subagents: list[SubAgentConfig] = [
+            SubAgentConfig(
+                name="helper",
+                description="A helper agent",
+                instructions="",
+            ),
+        ]
+        create_deep_agent(model=TEST_MODEL, subagents=subagents)
+        factory = subagents[0]["agent_factory"]
+        assert factory is not None
+        sub_agent = factory({"instructions": "", "model": TEST_MODEL})
+        assert any(BASE_PROMPT in str(i) for i in sub_agent._instructions)
+
     def test_create_with_interrupt_on(self):
         """Test creating an agent with interrupt_on config."""
         agent = create_deep_agent(
@@ -133,14 +168,30 @@ def test_base_prompt_is_default(self):
         # pydantic-ai stores instructions as a normalized list
         assert any(BASE_PROMPT in str(i) for i in agent._instructions)
 
-    def test_custom_instructions_override_base_prompt(self):
+    def test_custom_instructions_replace_base_prompt(self):
         """Custom instructions replace BASE_PROMPT entirely."""
         from pydantic_deep.prompts import BASE_PROMPT
 
         custom = "You are a custom agent."
         agent = create_deep_agent(model=TEST_MODEL, instructions=custom, cost_tracking=False)
         assert any(custom in str(i) for i in agent._instructions)
-        assert not any(str(i) == BASE_PROMPT for i in agent._instructions)
+        assert not any(BASE_PROMPT in str(i) for i in agent._instructions)
+
+    def test_custom_instructions_with_base_prompt_fstring(self):
+        """User can combine BASE_PROMPT with their own instructions via f-string."""
+        from pydantic_deep import BASE_PROMPT
+
+        custom = f"{BASE_PROMPT}\n\nYou are a coding assistant."
+        agent = create_deep_agent(model=TEST_MODEL, instructions=custom, cost_tracking=False)
+        assert any(BASE_PROMPT in str(i) for i in agent._instructions)
+        assert any("coding assistant" in str(i) for i in agent._instructions)
+
+    def test_empty_instructions_uses_base_prompt(self):
+        """instructions=None (default) uses BASE_PROMPT."""
+        from pydantic_deep.prompts import BASE_PROMPT
+
+        agent = create_deep_agent(model=TEST_MODEL, instructions=None, cost_tracking=False)
+        assert any(BASE_PROMPT in str(i) for i in agent._instructions)
 
     def test_create_with_all_capabilities_disabled(self):
         """Agent can be created with all built-in capabilities disabled (all_capabilities empty)."""