shotgun-sh 0.3.1.dev1__tar.gz → 0.3.3.dev2__tar.gz

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgun-sh
-Version: 0.3.1.dev1
+Version: 0.3.3.dev2
 Summary: AI-powered research, planning, and task management CLI tool
 Project-URL: Homepage, https://shotgun.sh/
 Project-URL: Repository, https://github.com/shotgun-sh/shotgun
@@ -32,7 +32,7 @@ Requires-Dist: logfire>=2.0.0
 Requires-Dist: openai>=1.0.0
 Requires-Dist: packaging>=23.0
 Requires-Dist: posthog>=3.0.0
-Requires-Dist: pydantic-ai>=0.0.14
+Requires-Dist: pydantic-ai>=1.26.0
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pyperclip>=1.10.0
 Requires-Dist: rich>=13.0.0

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shotgun-sh"
-version = "0.3.1.dev1"
+version = "0.3.3.dev2"
 description = "AI-powered research, planning, and task management CLI tool"
 readme = "README.md"
 license = { text = "MIT" }
@@ -24,7 +24,7 @@ classifiers = [
 dependencies = [
     "typer>=0.12.0",
     "rich>=13.0.0",
-    "pydantic-ai>=0.0.14",
+    "pydantic-ai>=1.26.0",
     "pydantic-settings>=2.0.0",
     "httpx>=0.27.0",
     "jinja2>=3.1.0",

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/agents/agent_manager.py

@@ -38,6 +38,7 @@ from pydantic_ai.messages import (
     PartDeltaEvent,
     PartStartEvent,
     SystemPromptPart,
+    TextPartDelta,
     ToolCallPart,
     ToolCallPartDelta,
     UserPromptPart,
@@ -174,6 +175,67 @@ class CompactionCompletedMessage(Message):
     """Event posted when conversation compaction completes."""
 
 
+class ToolExecutionStartedMessage(Message):
+    """Event posted when a tool starts executing.
+
+    This allows the UI to update the spinner text to provide feedback
+    during long-running tool executions.
+    """
+
+    def __init__(self, spinner_text: str = "Processing...") -> None:
+        """Initialize the tool execution started message.
+
+        Args:
+            spinner_text: The spinner message to display
+        """
+        super().__init__()
+        self.spinner_text = spinner_text
+
+
+class ToolStreamingProgressMessage(Message):
+    """Event posted during tool call streaming to show progress.
+
+    This provides visual feedback while tool arguments are streaming,
+    especially useful for long-running writes like file content.
+    """
+
+    def __init__(self, streamed_tokens: int, spinner_text: str) -> None:
+        """Initialize the tool streaming progress message.
+
+        Args:
+            streamed_tokens: Approximate number of tokens streamed so far
+            spinner_text: The current spinner message to preserve
+        """
+        super().__init__()
+        self.streamed_tokens = streamed_tokens
+        self.spinner_text = spinner_text
+
+
+# Fun spinner messages to show during tool execution
+SPINNER_MESSAGES = [
+    "Pontificating...",
+    "Ruminating...",
+    "Cogitating...",
+    "Deliberating...",
+    "Contemplating...",
+    "Reticulating splines...",
+    "Consulting the oracle...",
+    "Gathering thoughts...",
+    "Processing neurons...",
+    "Summoning wisdom...",
+    "Brewing ideas...",
+    "Polishing pixels...",
+    "Herding electrons...",
+    "Warming up the flux capacitor...",
+    "Consulting ancient tomes...",
+    "Channeling the muses...",
+    "Percolating possibilities...",
+    "Untangling complexity...",
+    "Shuffling priorities...",
+    "Aligning the stars...",
+]
+
+
 class AgentStreamingStarted(Message):
     """Event posted when agent starts streaming responses."""
 
@@ -210,6 +272,11 @@ class _PartialStreamState:
 
     messages: list[ModelRequest | ModelResponse] = field(default_factory=list)
     current_response: ModelResponse | None = None
+    # Token counting for tool call streaming progress
+    streamed_tokens: int = 0
+    current_spinner_text: str = "Processing..."
+    # Track last reported tokens to throttle UI updates
+    last_reported_tokens: int = 0
 
 
 class AgentManager(Widget):
@@ -992,6 +1059,44 @@ class AgentManager(Widget):
                         )
                         continue
 
+                    # Count tokens from the delta for progress indication
+                    delta_len = 0
+                    is_tool_call_delta = False
+                    if isinstance(event.delta, ToolCallPartDelta):
+                        is_tool_call_delta = True
+                        # args_delta can be str or dict depending on provider
+                        args_delta = event.delta.args_delta
+                        if isinstance(args_delta, str):
+                            delta_len = len(args_delta)
+                        elif isinstance(args_delta, dict):
+                            # For dict deltas, estimate from JSON representation
+                            delta_len = len(json.dumps(args_delta))
+                        # Pick a spinner message when tool streaming starts
+                        if state.current_spinner_text == "Processing...":
+                            import random
+
+                            state.current_spinner_text = random.choice(  # noqa: S311
+                                SPINNER_MESSAGES
+                            )
+                    elif isinstance(event.delta, TextPartDelta):
+                        delta_len = len(event.delta.content_delta)
+
+                    if delta_len > 0:
+                        # Approximate tokens: len / 4 is a rough estimate
+                        state.streamed_tokens += delta_len // 4 + 1
+                        # Send progress update for tool call streaming
+                        # Throttle updates to every ~75 tokens to avoid flooding UI
+                        if is_tool_call_delta and (
+                            state.streamed_tokens - state.last_reported_tokens >= 75
+                        ):
+                            state.last_reported_tokens = state.streamed_tokens
+                            self.post_message(
+                                ToolStreamingProgressMessage(
+                                    state.streamed_tokens,
+                                    state.current_spinner_text,
+                                )
+                            )
+
                     try:
                         updated_part = event.delta.apply(
                             cast(ModelResponsePart, partial_parts[index])
@@ -1087,6 +1192,17 @@ class AgentManager(Widget):
                     if partial_message is not None:
                         state.current_response = partial_message
                         self._post_partial_message(False)
+
+                    # Notify UI that a tool is about to execute
+                    # This updates the spinner with a fun message during tool execution
+                    # Pick a random spinner message and store it for progress updates
+                    import random
+
+                    spinner_text = random.choice(SPINNER_MESSAGES)  # noqa: S311
+                    state.current_spinner_text = spinner_text
+                    state.streamed_tokens = 0  # Reset token count for new tool
+                    self.post_message(ToolExecutionStartedMessage(spinner_text))
+
                 elif isinstance(event, FunctionToolResultEvent):
                     # Track tool completion event
 

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/agents/common.py

@@ -38,7 +38,6 @@ from .tools import (
     retrieve_code,
     write_file,
 )
-from .tools.file_management import AGENT_DIRECTORIES
 
 logger = get_logger(__name__)
 
@@ -352,86 +351,33 @@ async def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
 
 
 def get_agent_existing_files(agent_mode: AgentType | None = None) -> list[str]:
-    """Get list of existing files for the given agent mode.
+    """Get list of all existing files in .shotgun directory.
+
+    All agents can read any file in .shotgun/, so we list all files regardless
+    of agent mode. This includes user-added files that agents should be aware of.
 
     Args:
-        agent_mode: The agent mode to check files for. If None, lists all files.
+        agent_mode: Unused, kept for backwards compatibility.
 
     Returns:
         List of existing file paths relative to .shotgun directory
     """
     base_path = get_shotgun_base_path()
-    existing_files = []
-
-    # If no agent mode, list all files in base path and first level subdirectories
-    if agent_mode is None:
-        # List files in the root .shotgun directory
-        for item in base_path.iterdir():
-            if item.is_file():
-                existing_files.append(item.name)
-            elif item.is_dir():
-                # List files in first-level subdirectories
-                for subitem in item.iterdir():
-                    if subitem.is_file():
-                        relative_path = subitem.relative_to(base_path)
-                        existing_files.append(str(relative_path))
+    existing_files: list[str] = []
+
+    if not base_path.exists():
         return existing_files
 
-    # Handle specific agent modes
-    if agent_mode not in AGENT_DIRECTORIES:
-        return []
-
-    if agent_mode == AgentType.EXPORT:
-        # For export agent, list all files in exports directory
-        exports_dir = base_path / "exports"
-        if exports_dir.exists():
-            for file_path in exports_dir.rglob("*"):
-                if file_path.is_file():
-                    relative_path = file_path.relative_to(base_path)
+    # List all files in .shotgun directory and subdirectories
+    for item in base_path.iterdir():
+        if item.is_file():
+            existing_files.append(item.name)
+        elif item.is_dir():
+            # List files in subdirectories (one level deep to avoid too much noise)
+            for subitem in item.iterdir():
+                if subitem.is_file():
+                    relative_path = subitem.relative_to(base_path)
                     existing_files.append(str(relative_path))
-    else:
-        # For other agents, check files/directories they have access to
-        allowed_paths_raw = AGENT_DIRECTORIES[agent_mode]
-
-        # Convert single Path/string to list of Paths for uniform handling
-        if isinstance(allowed_paths_raw, str):
-            # Special case: "*" means export agent (shouldn't reach here but handle it)
-            allowed_paths = (
-                [Path(allowed_paths_raw)] if allowed_paths_raw != "*" else []
-            )
-        elif isinstance(allowed_paths_raw, Path):
-            allowed_paths = [allowed_paths_raw]
-        else:
-            # Already a list
-            allowed_paths = allowed_paths_raw
-
-        # Check each allowed path
-        for allowed_path in allowed_paths:
-            allowed_str = str(allowed_path)
-
-            # Check if it's a directory (no .md suffix)
-            if not allowed_path.suffix or not allowed_str.endswith(".md"):
-                # It's a directory - list all files within it
-                dir_path = base_path / allowed_str
-                if dir_path.exists() and dir_path.is_dir():
-                    for file_path in dir_path.rglob("*"):
-                        if file_path.is_file():
-                            relative_path = file_path.relative_to(base_path)
-                            existing_files.append(str(relative_path))
-            else:
-                # It's a file - check if it exists
-                file_path = base_path / allowed_str
-                if file_path.exists():
-                    existing_files.append(allowed_str)
-
-                # Also check for associated directory (e.g., research/ for research.md)
-                base_name = allowed_str.replace(".md", "")
-                dir_path = base_path / base_name
-                if dir_path.exists() and dir_path.is_dir():
-                    for file_path in dir_path.rglob("*"):
-                        if file_path.is_file():
-                            relative_path = file_path.relative_to(base_path)
-                            existing_files.append(str(relative_path))
 
     return existing_files
 

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/agents/config/models.py

@@ -25,16 +25,17 @@ class KeyProvider(StrEnum):
 class ModelName(StrEnum):
     """Available AI model names."""
 
-    GPT_5 = "gpt-5"
-    GPT_5_MINI = "gpt-5-mini"
     GPT_5_1 = "gpt-5.1"
     GPT_5_1_CODEX = "gpt-5.1-codex"
     GPT_5_1_CODEX_MINI = "gpt-5.1-codex-mini"
-    CLAUDE_OPUS_4_1 = "claude-opus-4-1"
+    CLAUDE_OPUS_4_5 = "claude-opus-4-5"
+    CLAUDE_SONNET_4 = "claude-sonnet-4"
     CLAUDE_SONNET_4_5 = "claude-sonnet-4-5"
     CLAUDE_HAIKU_4_5 = "claude-haiku-4-5"
     GEMINI_2_5_PRO = "gemini-2.5-pro"
     GEMINI_2_5_FLASH = "gemini-2.5-flash"
+    GEMINI_2_5_FLASH_LITE = "gemini-2.5-flash-lite"
+    GEMINI_3_PRO_PREVIEW = "gemini-3-pro-preview"
 
 
 class ModelSpec(BaseModel):
@@ -101,22 +102,6 @@ class ModelConfig(BaseModel):
 
 # Model specifications registry (static metadata)
 MODEL_SPECS: dict[ModelName, ModelSpec] = {
-    ModelName.GPT_5: ModelSpec(
-        name=ModelName.GPT_5,
-        provider=ProviderType.OPENAI,
-        max_input_tokens=400_000,
-        max_output_tokens=128_000,
-        litellm_proxy_model_name="openai/gpt-5",
-        short_name="GPT-5",
-    ),
-    ModelName.GPT_5_MINI: ModelSpec(
-        name=ModelName.GPT_5_MINI,
-        provider=ProviderType.OPENAI,
-        max_input_tokens=400_000,
-        max_output_tokens=128_000,
-        litellm_proxy_model_name="openai/gpt-5-mini",
-        short_name="GPT-5 Mini",
-    ),
     ModelName.GPT_5_1: ModelSpec(
         name=ModelName.GPT_5_1,
         provider=ProviderType.OPENAI,
@@ -141,14 +126,6 @@ MODEL_SPECS: dict[ModelName, ModelSpec] = {
         litellm_proxy_model_name="openai/gpt-5.1-codex-mini",
         short_name="GPT-5.1 Codex Mini",
     ),
-    ModelName.CLAUDE_OPUS_4_1: ModelSpec(
-        name=ModelName.CLAUDE_OPUS_4_1,
-        provider=ProviderType.ANTHROPIC,
-        max_input_tokens=200_000,
-        max_output_tokens=32_000,
-        litellm_proxy_model_name="anthropic/claude-opus-4-1",
-        short_name="Opus 4.1",
-    ),
     ModelName.CLAUDE_SONNET_4_5: ModelSpec(
         name=ModelName.CLAUDE_SONNET_4_5,
         provider=ProviderType.ANTHROPIC,
@@ -181,6 +158,38 @@ MODEL_SPECS: dict[ModelName, ModelSpec] = {
         litellm_proxy_model_name="gemini/gemini-2.5-flash",
         short_name="Gemini 2.5 Flash",
     ),
+    ModelName.CLAUDE_OPUS_4_5: ModelSpec(
+        name=ModelName.CLAUDE_OPUS_4_5,
+        provider=ProviderType.ANTHROPIC,
+        max_input_tokens=200_000,
+        max_output_tokens=64_000,
+        litellm_proxy_model_name="anthropic/claude-opus-4-5",
+        short_name="Opus 4.5",
+    ),
+    ModelName.CLAUDE_SONNET_4: ModelSpec(
+        name=ModelName.CLAUDE_SONNET_4,
+        provider=ProviderType.ANTHROPIC,
+        max_input_tokens=200_000,
+        max_output_tokens=64_000,
+        litellm_proxy_model_name="anthropic/claude-sonnet-4",
+        short_name="Sonnet 4",
+    ),
+    ModelName.GEMINI_2_5_FLASH_LITE: ModelSpec(
+        name=ModelName.GEMINI_2_5_FLASH_LITE,
+        provider=ProviderType.GOOGLE,
+        max_input_tokens=1_048_576,
+        max_output_tokens=65_536,
+        litellm_proxy_model_name="gemini/gemini-2.5-flash-lite",
+        short_name="Gemini 2.5 Flash Lite",
+    ),
+    ModelName.GEMINI_3_PRO_PREVIEW: ModelSpec(
+        name=ModelName.GEMINI_3_PRO_PREVIEW,
+        provider=ProviderType.GOOGLE,
+        max_input_tokens=1_048_576,
+        max_output_tokens=65_536,
+        litellm_proxy_model_name="gemini/gemini-3-pro-preview",
+        short_name="Gemini 3 Pro",
+    ),
 }
 
 

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/agents/config/provider.py

@@ -271,8 +271,6 @@ async def get_provider_model(
         # Check and test streaming capability for GPT-5 family models
         supports_streaming = True  # Default to True for all models
         if model_name in (
-            ModelName.GPT_5,
-            ModelName.GPT_5_MINI,
             ModelName.GPT_5_1,
             ModelName.GPT_5_1_CODEX,
             ModelName.GPT_5_1_CODEX_MINI,

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/agents/conversation/history/file_content_deduplication.py

@@ -5,8 +5,6 @@ tool returns before LLM-based compaction. Files are still accessible via
 `retrieve_code` (codebase) or `read_file` (.shotgun/ folder).
 """
 
-import copy
-import re
 from enum import StrEnum
 from typing import Any
 
@@ -43,40 +41,46 @@ SHOTGUN_PLACEHOLDER = (
     "**Content**: [Removed for compaction - file persisted in .shotgun/ folder]"
 )
 
-# Pattern for parsing file_read output (codebase files)
-# Format: **File**: `path`\n**Size**: N bytes\n[optional encoding]\n\n**Content**:\n```lang\ncontent```
-CODEBASE_FILE_PATTERN = re.compile(
-    r"\*\*File\*\*:\s*`([^`]+)`\s*\n"  # File path
-    r"\*\*Size\*\*:\s*(\d+)\s*bytes\s*\n"  # Size in bytes
-    r"(?:\*\*Encoding\*\*:.*?\n)?"  # Optional encoding line
-    r"\n\*\*Content\*\*:\s*\n"  # Blank line + Content header
-    r"```(\w*)\n"  # Language tag
-    r"(.*?)```",  # Actual content
-    re.DOTALL,
-)
+# Simple prefix for detecting file_read output format
+# Instead of using regex, we just check for the expected prefix and extract the file path
+CODEBASE_FILE_PREFIX = "**File**: `"
+
 
+def _extract_file_path(content: str) -> str | None:
+    """Extract file path from file_read tool return content.
 
-def _parse_codebase_file_content(
-    content: str,
-) -> tuple[str, int, str, str] | None:
-    """Parse file_read tool return content.
+    Uses simple string operations instead of regex for maximum performance.
+    The file_read tool output format is: **File**: `path`\\n...
 
     Args:
         content: The tool return content string
 
     Returns:
-        Tuple of (file_path, size_bytes, language, actual_content) or None if not parseable
+        The file path or None if format doesn't match
     """
-    match = CODEBASE_FILE_PATTERN.search(content)
-    if not match:
+    # Fast check: content must start with expected prefix
+    if not content.startswith(CODEBASE_FILE_PREFIX):
+        return None
+
+    # Find the closing backtick after the prefix
+    prefix_len = len(CODEBASE_FILE_PREFIX)
+    backtick_pos = content.find("`", prefix_len)
+
+    if backtick_pos == -1:
         return None
 
-    file_path = match.group(1)
-    size_bytes = int(match.group(2))
-    language = match.group(3) or ""
-    actual_content = match.group(4)
+    return content[prefix_len:backtick_pos]
+
+
+def _get_language_from_path(file_path: str) -> str:
+    """Infer programming language from file extension."""
+    from pathlib import Path
+
+    from shotgun.codebase.core.language_config import get_language_config
 
-    return file_path, size_bytes, language, actual_content
+    ext = Path(file_path).suffix
+    config = get_language_config(ext)
+    return config.name if config else "unknown"
 
 
 def _create_codebase_placeholder(file_path: str, size_bytes: int, language: str) -> str:
@@ -110,6 +114,11 @@ def deduplicate_file_content(
     This is a deterministic pre-compaction pass that reduces tokens without
     requiring an LLM. Files remain accessible via their respective tools.
 
+    This function uses copy-on-write semantics: only messages that need
+    modification are copied, while unmodified messages are reused by reference.
+    This significantly reduces memory allocation and processing time for large
+    conversations where only a subset of messages contain file content.
+
     Args:
         messages: Conversation history
         retention_window: Keep full content in last N messages (for recent context)
@@ -120,15 +129,17 @@ def deduplicate_file_content(
     if not messages:
         return messages, 0
 
-    # Deep copy to avoid modifying original
-    modified_messages = copy.deepcopy(messages)
     total_tokens_saved = 0
     files_deduplicated = 0
 
     # Calculate retention boundary (keep last N messages intact)
-    retention_start = max(0, len(modified_messages) - retention_window)
+    retention_start = max(0, len(messages) - retention_window)
+
+    # Track which message indices need replacement
+    # We use a dict to store index -> new_message mappings
+    replacements: dict[int, ModelMessage] = {}
 
-    for msg_idx, message in enumerate(modified_messages):
+    for msg_idx, message in enumerate(messages):
         # Skip messages in retention window
         if msg_idx >= retention_start:
             continue
@@ -159,18 +170,18 @@ def deduplicate_file_content(
 
             # Handle codebase file reads (file_read)
             if tool_name == FileReadTool.CODEBASE:
-                parsed = _parse_codebase_file_content(content)
-                if parsed:
-                    file_path, size_bytes, language, actual_content = parsed
-                    # Only replace if actual content is substantial
-                    if len(actual_content) >= MIN_CONTENT_LENGTH:
-                        replacement = _create_codebase_placeholder(
-                            file_path, size_bytes, language
-                        )
-                        logger.debug(
-                            f"Deduplicating codebase file: {file_path} "
-                            f"({size_bytes} bytes)"
-                        )
+                file_path = _extract_file_path(content)
+                if file_path:
+                    # Use content length as size estimate (includes formatting overhead
+                    # but close enough for deduplication purposes)
+                    size_bytes = len(content)
+                    language = _get_language_from_path(file_path)
+                    replacement = _create_codebase_placeholder(
+                        file_path, size_bytes, language
+                    )
+                    logger.debug(
+                        f"Deduplicating codebase file: {file_path} ({size_bytes} bytes)"
+                    )
 
             # Handle .shotgun/ file reads (read_file)
             elif tool_name == FileReadTool.SHOTGUN_FOLDER:
@@ -203,9 +214,21 @@ def deduplicate_file_content(
             else:
                 new_parts.append(part)
 
-        # Replace message with new parts if modified
+        # Only create a new message if parts were actually modified
         if message_modified:
-            modified_messages[msg_idx] = ModelRequest(parts=new_parts)
+            replacements[msg_idx] = ModelRequest(parts=new_parts)
+
+    # If no modifications were made, return original list (no allocation needed)
+    if not replacements:
+        return messages, 0
+
+    # Build result list with copy-on-write: reuse unmodified messages
+    modified_messages: list[ModelMessage] = []
+    for idx, msg in enumerate(messages):
+        if idx in replacements:
+            modified_messages.append(replacements[idx])
+        else:
+            modified_messages.append(msg)
 
     if files_deduplicated > 0:
         logger.info(

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/agents/tools/file_management.py

@@ -23,7 +23,10 @@ logger = get_logger(__name__)
 # - A list of Paths: multiple allowed files/directories (e.g., [Path("specification.md"), Path("contracts")])
 # - "*": any file except protected files (for export agent)
 AGENT_DIRECTORIES: dict[AgentType, str | Path | list[Path]] = {
-    AgentType.RESEARCH: Path("research.md"),
+    AgentType.RESEARCH: [
+        Path("research.md"),
+        Path("research"),
+    ],  # Research can write main file and research folder
     AgentType.SPECIFY: [
         Path("specification.md"),
         Path("contracts"),

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/agents/tools/web_search/gemini.py

@@ -1,7 +1,7 @@
 """Gemini web search tool implementation."""
 
 from opentelemetry import trace
-from pydantic_ai.messages import ModelMessage, ModelRequest
+from pydantic_ai.messages import ModelMessage, ModelRequest, TextPart
 from pydantic_ai.settings import ModelSettings
 
 from shotgun.agents.config import get_provider_model
@@ -82,8 +82,6 @@ async def gemini_web_search_tool(query: str) -> str:
         )
 
         # Extract text from response
-        from pydantic_ai.messages import TextPart
-
         result_text = "No content returned from search"
         if response.parts:
             for part in response.parts:

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/prompts/agents/partials/common_agent_system_prompt.j2

@@ -4,6 +4,31 @@ Your extensive expertise spans, among other things:
 * Software Architecture
 * Software Development
 
+## YOUR ROLE IN THE PIPELINE
+
+**CRITICAL**: You are a DOCUMENTATION and PLANNING agent, NOT a coding/implementation agent.
+
+- You produce DOCUMENTS (research, specifications, plans, tasks) that AI coding agents will consume
+- You do NOT write production code, implement features, or make code changes
+- NEVER offer to "move forward with implementation" or "start coding" - that's not your job
+- NEVER ask "would you like me to implement this?" - implementation is done by separate AI coding tools
+- Your deliverable is always a document file (.md), not code execution
+- When your work is complete, the user will take your documents to a coding agent (Claude Code, Cursor, etc.)
+
+## AGENT FILE PERMISSIONS
+
+There are four agents in the pipeline, and each agent can ONLY write to specific files. The user can switch between agents using **Shift+Tab**.
+
+The **Research agent** can only write to `research.md` and files inside the `.shotgun/research/` directory. If the user asks about specifications, plans, or tasks, tell them: "Use **Shift+Tab** to switch to the [appropriate] agent which can edit that file for you."
+
+The **Specification agent** can only write to `specification.md` and files inside the `.shotgun/contracts/` directory. If the user asks about research, plans, or tasks, tell them which agent handles that file.
+
+The **Plan agent** can only write to `plan.md`. If the user asks about research, specifications, or tasks, tell them which agent handles that file.
+
+The **Tasks agent** can only write to `tasks.md`. If the user asks about research, specifications, or plans, tell them which agent handles that file.
+
+When a user asks you to edit a file you cannot write to, you MUST tell them which agent can help and how to switch: "I can't edit [filename] - that's handled by the [agent name] agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
 ## KEY RULES
 
 {% if interactive_mode %}

{shotgun_sh-0.3.1.dev1 → shotgun_sh-0.3.3.dev2}/src/shotgun/prompts/agents/plan.j2

@@ -6,6 +6,22 @@ Your job is to help create comprehensive, actionable plans for software projects
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## YOUR SCOPE AND HANDOFFS
+
+You are the **Plan agent**. Your file is `plan.md` - this is the ONLY file you can write to.
+
+When your plan is complete, suggest the next step:
+"I've completed the plan. Use **Shift+Tab** to switch to the tasks agent to break this plan into actionable tasks."
+
+If the user asks you to edit other files, redirect them helpfully:
+- For research.md: "I can't edit research.md - that's handled by the research agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For specification.md or contracts: "I can't edit specification.md - that's handled by the specification agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For tasks.md: "I can't edit tasks.md - that's handled by the tasks agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
+NEVER offer to do work outside your scope:
+- Don't offer to write research, specifications, or tasks - redirect the user to the appropriate agent
+- Don't offer to implement code - you are not a coding agent
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `plan.md`