shotgun-sh 0.2.6.dev1__py3-none-any.whl → 0.2.6.dev3__py3-none-any.whl

shotgun/agents/agent_manager.py

@@ -10,8 +10,6 @@ if TYPE_CHECKING:
 
 from pydantic_ai import (
     Agent,
-    DeferredToolRequests,
-    DeferredToolResults,
     RunContext,
     UsageLimits,
 )
@@ -37,7 +35,7 @@ from textual.widget import Widget
 
 from shotgun.agents.common import add_system_prompt_message, add_system_status_message
 from shotgun.agents.config.models import KeyProvider
-from shotgun.agents.models import AgentType, FileOperation
+from shotgun.agents.models import AgentResponse, AgentType, FileOperation
 from shotgun.posthog_telemetry import track_event
 from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 from shotgun.utils.source_detection import detect_source
@@ -45,7 +43,7 @@ from shotgun.utils.source_detection import detect_source
 from .export import create_export_agent
 from .history.compaction import apply_persistent_compaction
 from .messages import AgentSystemPrompt
-from .models import AgentDeps, AgentRuntimeOptions, UserAnswer
+from .models import AgentDeps, AgentRuntimeOptions
 from .plan import create_plan_agent
 from .research import create_research_agent
 from .specify import create_specify_agent
@@ -92,6 +90,25 @@ class PartialResponseMessage(Message):
         self.is_last = is_last
 
 
+class ClarifyingQuestionsMessage(Message):
+    """Event posted when agent returns clarifying questions."""
+
+    def __init__(
+        self,
+        questions: list[str],
+        response_text: str,
+    ) -> None:
+        """Initialize the clarifying questions message.
+
+        Args:
+            questions: List of clarifying questions from the agent
+            response_text: The agent's response text before asking questions
+        """
+        super().__init__()
+        self.questions = questions
+        self.response_text = response_text
+
+
 @dataclass(slots=True)
 class _PartialStreamState:
     """Tracks streamed messages while handling a single agent run."""
@@ -158,8 +175,12 @@ class AgentManager(Widget):
         self.recently_change_files: list[FileOperation] = []
         self._stream_state: _PartialStreamState | None = None
 
+        # Q&A mode state for structured output questions
+        self._qa_questions: list[str] | None = None
+        self._qa_mode_active: bool = False
+
     @property
-    def current_agent(self) -> Agent[AgentDeps, str | DeferredToolRequests]:
+    def current_agent(self) -> Agent[AgentDeps, AgentResponse]:
         """Get the currently active agent.
 
         Returns:
@@ -167,9 +188,7 @@ class AgentManager(Widget):
         """
         return self._get_agent(self._current_agent_type)
 
-    def _get_agent(
-        self, agent_type: AgentType
-    ) -> Agent[AgentDeps, str | DeferredToolRequests]:
+    def _get_agent(self, agent_type: AgentType) -> Agent[AgentDeps, AgentResponse]:
         """Get agent by type.
 
         Args:
@@ -252,9 +271,8 @@ class AgentManager(Widget):
         *,
         deps: AgentDeps | None = None,
         usage_limits: UsageLimits | None = None,
-        deferred_tool_results: DeferredToolResults | None = None,
         **kwargs: Any,
-    ) -> AgentRunResult[str | DeferredToolRequests]:
+    ) -> AgentRunResult[AgentResponse]:
         """Run the current agent with automatic message history management.
 
         This method wraps the agent's run method, automatically injecting the
@@ -264,7 +282,6 @@ class AgentManager(Widget):
             prompt: Optional prompt to send to the agent.
             deps: Optional dependencies override (defaults to manager's deps).
             usage_limits: Optional usage limits for the agent run.
-            deferred_tool_results: Optional deferred tool results for continuing a conversation.
             **kwargs: Additional keyword arguments to pass to the agent.
 
         Returns:
@@ -274,15 +291,6 @@ class AgentManager(Widget):
         # Use merged deps (shared state + agent-specific system prompt) if not provided
         if deps is None:
             deps = self._create_merged_deps(self._current_agent_type)
-        ask_user_part = self.get_unanswered_ask_user_part()
-        if ask_user_part and prompt:
-            if not deferred_tool_results:
-                deferred_tool_results = DeferredToolResults()
-            deferred_tool_results.calls[ask_user_part.tool_call_id] = UserAnswer(
-                answer=prompt,
-                tool_call_id=ask_user_part.tool_call_id,
-            )
-            prompt = None
 
         # Ensure deps is not None
         if deps is None:
@@ -378,20 +386,16 @@ class AgentManager(Widget):
             event_name,
             {
                 "has_prompt": prompt is not None,
-                "has_deferred_results": deferred_tool_results is not None,
                 "model_name": model_name,
             },
         )
 
         try:
-            result: AgentRunResult[
-                str | DeferredToolRequests
-            ] = await self.current_agent.run(
+            result: AgentRunResult[AgentResponse] = await self.current_agent.run(
                 prompt,
                 deps=deps,
                 usage_limits=usage_limits,
                 message_history=message_history,
-                deferred_tool_results=deferred_tool_results,
                 event_stream_handler=self._handle_event_stream
                 if not is_gpt5_byok
                 else None,
@@ -400,10 +404,68 @@ class AgentManager(Widget):
         finally:
             self._stream_state = None
 
+        # Agent ALWAYS returns AgentResponse with structured output
+        agent_response = result.output
+        logger.debug("Agent returned structured AgentResponse")
+
+        # Always add the agent's response messages to maintain conversation history
         self.ui_message_history = original_messages + cast(
             list[ModelRequest | ModelResponse | HintMessage], result.new_messages()
         )
 
+        # Check if there are clarifying questions
+        if agent_response.clarifying_questions:
+            logger.info(
+                f"Agent has {len(agent_response.clarifying_questions)} clarifying questions"
+            )
+
+            # Add agent's response first if present
+            if agent_response.response:
+                self.ui_message_history.append(
+                    HintMessage(message=agent_response.response)
+                )
+
+            if len(agent_response.clarifying_questions) == 1:
+                # Single question - treat as non-blocking suggestion, DON'T enter Q&A mode
+                self.ui_message_history.append(
+                    HintMessage(message=f"💡 {agent_response.clarifying_questions[0]}")
+                )
+            else:
+                # Multiple questions (2+) - enter Q&A mode
+                self._qa_questions = agent_response.clarifying_questions
+                self._qa_mode_active = True
+
+                # Show intro with list, then first question
+                questions_list_with_intro = (
+                    f"I have {len(agent_response.clarifying_questions)} questions:\n\n"
+                    + "\n".join(
+                        f"{i + 1}. {q}"
+                        for i, q in enumerate(agent_response.clarifying_questions)
+                    )
+                )
+                self.ui_message_history.append(
+                    HintMessage(message=questions_list_with_intro)
+                )
+                self.ui_message_history.append(
+                    HintMessage(
+                        message=f"**Q1:** {agent_response.clarifying_questions[0]}"
+                    )
+                )
+
+                # Post event to TUI to update Q&A mode state (only for multiple questions)
+                self.post_message(
+                    ClarifyingQuestionsMessage(
+                        questions=agent_response.clarifying_questions,
+                        response_text=agent_response.response,
+                    )
+                )
+        else:
+            # No clarifying questions - just show the response if present
+            if agent_response.response and agent_response.response.strip():
+                self.ui_message_history.append(
+                    HintMessage(message=agent_response.response)
+                )
+
         # Apply compaction to persistent message history to prevent cascading growth
         all_messages = result.all_messages()
         self.message_history = await apply_persistent_compaction(all_messages, deps)
@@ -416,6 +478,7 @@ class AgentManager(Widget):
         file_operations = deps.file_tracker.operations.copy()
         self.recently_change_files = file_operations
 
+        # Post message history update (hints are now added synchronously above)
         self._post_messages_updated(file_operations)
 
         return result
@@ -702,22 +765,6 @@ class AgentManager(Widget):
         self.ui_message_history.append(message)
         self._post_messages_updated()
 
-    def get_unanswered_ask_user_part(self) -> ToolCallPart | None:
-        if not self.message_history:
-            return None
-        self.last_response = self.message_history[-1]
-        ## we're searching for unanswered ask_user parts
-        found_tool = next(
-            (
-                part
-                for part in self.message_history[-1].parts
-                if isinstance(part, ToolCallPart) and part.tool_name == "ask_user"
-            ),
-            None,
-        )
-
-        return found_tool
-
 
 # Re-export AgentType for backward compatibility
 __all__ = [
@@ -725,4 +772,5 @@ __all__ = [
     "AgentType",
     "MessageHistoryUpdated",
     "PartialResponseMessage",
+    "ClarifyingQuestionsMessage",
 ]

shotgun/agents/common.py

@@ -1,14 +1,11 @@
 """Common utilities for agent creation and management."""
 
-import asyncio
 from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
 from pydantic_ai import (
     Agent,
-    DeferredToolRequests,
-    DeferredToolResults,
     RunContext,
     UsageLimits,
 )
@@ -19,7 +16,7 @@ from pydantic_ai.messages import (
 )
 
 from shotgun.agents.config import ProviderType, get_provider_model
-from shotgun.agents.models import AgentType
+from shotgun.agents.models import AgentResponse, AgentType
 from shotgun.logging_config import get_logger
 from shotgun.prompts import PromptLoader
 from shotgun.sdk.services import get_codebase_service
@@ -28,12 +25,10 @@ from shotgun.utils.datetime_utils import get_datetime_context
 from shotgun.utils.file_system_utils import get_shotgun_base_path
 
 from .history import token_limit_compactor
-from .history.compaction import apply_persistent_compaction
 from .messages import AgentSystemPrompt, SystemStatusPrompt
 from .models import AgentDeps, AgentRuntimeOptions, PipelineConfigEntry
 from .tools import (
     append_file,
-    ask_user,
     codebase_shell,
     directory_lister,
     file_read,
@@ -106,7 +101,7 @@ def create_base_agent(
     additional_tools: list[Any] | None = None,
     provider: ProviderType | None = None,
     agent_mode: AgentType | None = None,
-) -> tuple[Agent[AgentDeps, str | DeferredToolRequests], AgentDeps]:
+) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create a base agent with common configuration.
 
     Args:
@@ -164,7 +159,7 @@ def create_base_agent(
 
     agent = Agent(
         model,
-        output_type=[str, DeferredToolRequests],
+        output_type=AgentResponse,
         deps_type=AgentDeps,
         instrument=True,
         history_processors=[history_processor],
@@ -179,11 +174,6 @@ def create_base_agent(
     for tool in additional_tools or []:
         agent.tool_plain(tool)
 
-    # Register interactive tool conditionally based on deps
-    if deps.interactive_mode:
-        agent.tool(ask_user)
-        logger.debug("📞 Interactive mode enabled - ask_user tool registered")
-
     # Register common file management tools (always available)
     agent.tool(write_file)
     agent.tool(append_file)
@@ -323,7 +313,9 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
         if prior_toc:
             # Add section with XML tags
             toc_sections.append(
-                f'<TABLE_OF_CONTENTS file_name="{prior_file}">\n{prior_toc}\n</TABLE_OF_CONTENTS>'
+                f'<TABLE_OF_CONTENTS file_name="{prior_file}">\n'
+                f"{prior_toc}\n"
+                f"</TABLE_OF_CONTENTS>"
             )
 
     # Extract TOC from own file (full detail)
@@ -334,7 +326,9 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
             # Put own file TOC at the beginning with XML tags
             toc_sections.insert(
                 0,
-                f'<TABLE_OF_CONTENTS file_name="{config.own_file}">\n{own_toc}\n</TABLE_OF_CONTENTS>',
+                f'<TABLE_OF_CONTENTS file_name="{config.own_file}">\n'
+                f"{own_toc}\n"
+                f"</TABLE_OF_CONTENTS>",
             )
 
     # Combine all sections
@@ -476,7 +470,8 @@ async def add_system_prompt_message(
     message_history = message_history or []
 
     # Create a minimal RunContext to call the system prompt function
-    # We'll pass None for model and usage since they're not used by our system prompt functions
+    # We'll pass None for model and usage since they're not used
+    # by our system prompt functions
     context = type(
         "RunContext", (), {"deps": deps, "retry": 0, "model": None, "usage": None}
     )()
@@ -500,12 +495,12 @@ async def add_system_prompt_message(
 
 
 async def run_agent(
-    agent: Agent[AgentDeps, str | DeferredToolRequests],
+    agent: Agent[AgentDeps, AgentResponse],
     prompt: str,
     deps: AgentDeps,
     message_history: list[ModelMessage] | None = None,
     usage_limits: UsageLimits | None = None,
-) -> AgentRunResult[str | DeferredToolRequests]:
+) -> AgentRunResult[AgentResponse]:
     # Clear file tracker for new run
     deps.file_tracker.clear()
     logger.debug("🔧 Cleared file tracker for new agent run")
@@ -520,33 +515,6 @@ async def run_agent(
         message_history=message_history,
     )
 
-    # Apply persistent compaction to prevent cascading token growth across CLI commands
-    messages = await apply_persistent_compaction(result.all_messages(), deps)
-    while isinstance(result.output, DeferredToolRequests):
-        logger.info("got deferred tool requests")
-        await deps.queue.join()
-        requests = result.output
-        done, _ = await asyncio.wait(deps.tasks)
-
-        task_results = [task.result() for task in done]
-        task_results_by_tool_call_id = {
-            result.tool_call_id: result.answer for result in task_results
-        }
-        logger.info("got task results", task_results_by_tool_call_id)
-        results = DeferredToolResults()
-        for call in requests.calls:
-            results.calls[call.tool_call_id] = task_results_by_tool_call_id[
-                call.tool_call_id
-            ]
-        result = await agent.run(
-            deps=deps,
-            usage_limits=usage_limits,
-            message_history=messages,
-            deferred_tool_results=results,
-        )
-        # Apply persistent compaction to prevent cascading token growth in multi-turn loops
-        messages = await apply_persistent_compaction(result.all_messages(), deps)
-
     # Log file operations summary if any files were modified
     if deps.file_tracker.operations:
         summary = deps.file_tracker.format_summary()

shotgun/agents/export.py

@@ -4,7 +4,6 @@ from functools import partial
 
 from pydantic_ai import (
     Agent,
-    DeferredToolRequests,
 )
 from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import ModelMessage
@@ -19,14 +18,14 @@ from .common import (
     create_usage_limits,
     run_agent,
 )
-from .models import AgentDeps, AgentRuntimeOptions, AgentType
+from .models import AgentDeps, AgentResponse, AgentRuntimeOptions, AgentType
 
 logger = get_logger(__name__)
 
 
 def create_export_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
-) -> tuple[Agent[AgentDeps, str | DeferredToolRequests], AgentDeps]:
+) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create an export agent with file management capabilities.
 
     Args:
@@ -50,11 +49,11 @@ def create_export_agent(
 
 
 async def run_export_agent(
-    agent: Agent[AgentDeps, str | DeferredToolRequests],
+    agent: Agent[AgentDeps, AgentResponse],
     instruction: str,
     deps: AgentDeps,
     message_history: list[ModelMessage] | None = None,
-) -> AgentRunResult[str | DeferredToolRequests]:
+) -> AgentRunResult[AgentResponse]:
     """Export artifacts based on the given instruction.
 
     Args:

shotgun/agents/history/token_counting/anthropic.py

@@ -1,5 +1,6 @@
 """Anthropic token counting using official client."""
 
+import logfire
 from pydantic_ai.messages import ModelMessage
 
 from shotgun.agents.config.models import KeyProvider
@@ -49,7 +50,15 @@ class AnthropicTokenCounter(TokenCounter):
                     f"Initialized async Anthropic token counter for {model_name} via direct API"
                 )
         except Exception as e:
-            raise RuntimeError("Failed to initialize Anthropic async client") from e
+            logfire.exception(
+                f"Failed to initialize Anthropic token counter for {model_name}",
+                model_name=model_name,
+                key_provider=key_provider.value,
+                exception_type=type(e).__name__,
+            )
+            raise RuntimeError(
+                f"Failed to initialize Anthropic async client for {model_name}: {type(e).__name__}: {str(e)}"
+            ) from e
 
     async def count_tokens(self, text: str) -> int:
         """Count tokens using Anthropic's official API (async).
@@ -71,8 +80,19 @@ class AnthropicTokenCounter(TokenCounter):
             )
             return result.input_tokens
         except Exception as e:
+            # Create a preview of the text for logging (truncated to avoid huge logs)
+            text_preview = text[:100] + "..." if len(text) > 100 else text
+
+            logfire.exception(
+                f"Anthropic token counting failed for {self.model_name}",
+                model_name=self.model_name,
+                text_length=len(text),
+                text_preview=text_preview,
+                exception_type=type(e).__name__,
+                exception_message=str(e),
+            )
             raise RuntimeError(
-                f"Anthropic token counting API failed for {self.model_name}"
+                f"Anthropic token counting API failed for {self.model_name}: {type(e).__name__}: {str(e)}"
             ) from e
 
     async def count_message_tokens(self, messages: list[ModelMessage]) -> int:

shotgun/agents/models.py

@@ -19,6 +19,30 @@ if TYPE_CHECKING:
     from shotgun.codebase.service import CodebaseService
 
 
+class AgentResponse(BaseModel):
+    """Structured response from an agent with optional clarifying questions.
+
+    This model provides a consistent response format for all agents:
+    - response: The main response text (can be empty if only asking questions)
+    - clarifying_questions: Optional list of questions to ask the user
+
+    When clarifying_questions is provided, the agent expects to receive
+    answers before continuing its work. This replaces the ask_questions tool.
+    """
+
+    response: str = Field(
+        description="The agent's response text. Always respond with some text summarizing what happened, whats next, etc.",
+    )
+    clarifying_questions: list[str] | None = Field(
+        default=None,
+        description="""
+Optional list of clarifying questions to ask the user.
+- Single question: Shown as a non-blocking suggestion (user can answer or continue with other prompts)
+- Multiple questions (2+): Asked sequentially in Q&A mode (blocks input until all answered or cancelled)
+""",
+    )
+
+
 class AgentType(StrEnum):
     """Enumeration for available agent types."""
 
@@ -73,6 +97,30 @@ class UserQuestion(BaseModel):
     )
 
 
+class MultipleUserQuestions(BaseModel):
+    """Multiple questions to ask the user sequentially."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    questions: list[str] = Field(
+        description="List of questions to ask the user",
+    )
+    current_index: int = Field(
+        default=0,
+        description="Current question index being asked",
+    )
+    answers: list[str] = Field(
+        default_factory=list,
+        description="Accumulated answers from the user",
+    )
+    tool_call_id: str = Field(
+        description="Tool call id",
+    )
+    result: Future[UserAnswer] = Field(
+        description="Future that will contain all answers formatted as Q&A pairs"
+    )
+
+
 class AgentRuntimeOptions(BaseModel):
     """User interface options for agents."""
 
@@ -100,9 +148,9 @@ class AgentRuntimeOptions(BaseModel):
         description="Maximum number of iterations for agent loops",
     )
 
-    queue: Queue[UserQuestion] = Field(
+    queue: Queue[UserQuestion | MultipleUserQuestions] = Field(
         default_factory=Queue,
-        description="Queue for storing user responses",
+        description="Queue for storing user questions (single or multiple)",
     )
 
     tasks: list[Future[UserAnswer]] = Field(

shotgun/agents/plan.py

@@ -4,7 +4,6 @@ from functools import partial
 
 from pydantic_ai import (
     Agent,
-    DeferredToolRequests,
 )
 from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import ModelMessage
@@ -19,14 +18,14 @@ from .common import (
     create_usage_limits,
     run_agent,
 )
-from .models import AgentDeps, AgentRuntimeOptions, AgentType
+from .models import AgentDeps, AgentResponse, AgentRuntimeOptions, AgentType
 
 logger = get_logger(__name__)
 
 
 def create_plan_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
-) -> tuple[Agent[AgentDeps, str | DeferredToolRequests], AgentDeps]:
+) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create a plan agent with artifact management capabilities.
 
     Args:
@@ -52,11 +51,11 @@ def create_plan_agent(
 
 
 async def run_plan_agent(
-    agent: Agent[AgentDeps, str | DeferredToolRequests],
+    agent: Agent[AgentDeps, AgentResponse],
     goal: str,
     deps: AgentDeps,
     message_history: list[ModelMessage] | None = None,
-) -> AgentRunResult[str | DeferredToolRequests]:
+) -> AgentRunResult[AgentResponse]:
     """Create or update a plan based on the given goal using artifacts.
 
     Args:

shotgun/agents/research.py

@@ -4,7 +4,6 @@ from functools import partial
 
 from pydantic_ai import (
     Agent,
-    DeferredToolRequests,
 )
 from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import (
@@ -21,7 +20,7 @@ from .common import (
     create_usage_limits,
     run_agent,
 )
-from .models import AgentDeps, AgentRuntimeOptions, AgentType
+from .models import AgentDeps, AgentResponse, AgentRuntimeOptions, AgentType
 from .tools import get_available_web_search_tools
 
 logger = get_logger(__name__)
@@ -29,7 +28,7 @@ logger = get_logger(__name__)
 
 def create_research_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
-) -> tuple[Agent[AgentDeps, str | DeferredToolRequests], AgentDeps]:
+) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create a research agent with web search and artifact management capabilities.
 
     Args:
@@ -66,11 +65,11 @@ def create_research_agent(
 
 
 async def run_research_agent(
-    agent: Agent[AgentDeps, str | DeferredToolRequests],
+    agent: Agent[AgentDeps, AgentResponse],
     query: str,
     deps: AgentDeps,
     message_history: list[ModelMessage] | None = None,
-) -> AgentRunResult[str | DeferredToolRequests]:
+) -> AgentRunResult[AgentResponse]:
     """Perform research on the given query and update research artifacts.
 
     Args:

shotgun/agents/specify.py

@@ -4,7 +4,6 @@ from functools import partial
 
 from pydantic_ai import (
     Agent,
-    DeferredToolRequests,
 )
 from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import ModelMessage
@@ -19,14 +18,14 @@ from .common import (
     create_usage_limits,
     run_agent,
 )
-from .models import AgentDeps, AgentRuntimeOptions, AgentType
+from .models import AgentDeps, AgentResponse, AgentRuntimeOptions, AgentType
 
 logger = get_logger(__name__)
 
 
 def create_specify_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
-) -> tuple[Agent[AgentDeps, str | DeferredToolRequests], AgentDeps]:
+) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create a specify agent with artifact management capabilities.
 
     Args:
@@ -52,11 +51,11 @@ def create_specify_agent(
 
 
 async def run_specify_agent(
-    agent: Agent[AgentDeps, str | DeferredToolRequests],
+    agent: Agent[AgentDeps, AgentResponse],
     requirement: str,
     deps: AgentDeps,
     message_history: list[ModelMessage] | None = None,
-) -> AgentRunResult[str | DeferredToolRequests]:
+) -> AgentRunResult[AgentResponse]:
     """Create or update specifications based on the given requirement.
 
     Args: