feat(tool): add built-in ask_user tool for LLM-driven user input

Add AskUserTool as a framework-built-in tool that is automatically
registered for every agent, allowing the LLM to ask structured
questions when it needs user clarification, decisions, or approval.

- AskUserTool: ITool implementation with structured question schema
- IUserInputHandler: callback protocol for host apps (CLI, web, etc.)
- CLIUserInputHandler: default stdin/stdout implementation
- Builder auto-registers ask_user; no manual add_tools() needed
- with_user_input_handler() on builder for custom handler injection

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bouillipx

dare_framework/agent/_internal/builder.py

@@ -55,6 +55,7 @@
     IValidatorManager,
 )
 from dare_framework.tool._internal.managers.tool_manager import ToolManager
+from dare_framework.tool._internal.tools.ask_user import AskUserTool, IUserInputHandler
 from dare_framework.tool.interfaces import ITool, IToolProvider, RunContext
 from dare_framework.tool.kernel import IExecutionControl, IToolGateway, IToolManager
 
@@ -102,6 +103,9 @@ def __init__(self, name: str) -> None:
         # Initial skill path (None = not set; single path for one skill).
         self._initial_skill_path: str | None = None
 
+        # User input handler for the built-in ask_user tool.
+        self._user_input_handler: IUserInputHandler | None = None
+
     def _manager_config(self) -> Config | None:
         """Return the Config passed to managers."""
 
@@ -209,6 +213,15 @@ def with_skill(self: TBuilder, path: str | Path) -> TBuilder:
         self._initial_skill_path = str(path)
         return self
 
+    def with_user_input_handler(self: TBuilder, handler: IUserInputHandler) -> TBuilder:
+        """Inject a custom user-input handler for the built-in ``ask_user`` tool.
+
+        If not called, the default ``CLIUserInputHandler`` (stdin/stdout) is
+        used.  Pass a custom implementation for web UIs, Slack bots, etc.
+        """
+        self._user_input_handler = handler
+        return self
+
     async def build(self) -> Any:
         """Build the agent. When with_config() was used and config.mcp_paths is set, loads MCP inside build()."""
         if self._config is not None and getattr(self._config, "mcp_paths", None):
@@ -300,6 +313,8 @@ def _ensure_tool_provider(
             # Include knowledge tool names so they are always listed when knowledge is set.
             if self._resolved_knowledge() is not None:
                 explicit_names = explicit_names | {"knowledge_get", "knowledge_add"}
+            # Built-in ask_user is always available.
+            explicit_names = explicit_names | {"ask_user"}
             return _ConfiguredToolProvider(
                 manager=manager,
                 config=self._config,
@@ -329,6 +344,9 @@ def _register_tools_with_manager(self, manager: IToolManager | None, tools: list
         if knowledge is not None:
             manager.register_tool(KnowledgeGetTool(knowledge))
             manager.register_tool(KnowledgeAddTool(knowledge))
+        # Built-in ask_user tool — always available so the LLM can request user input.
+        ask_user_tool = AskUserTool(handler=self._user_input_handler)
+        manager.register_tool(ask_user_tool)
 
     def _resolved_model(self) -> IModelAdapter:
         if self._model is not None:

dare_framework/tool/__init__.py

@@ -37,6 +37,9 @@
 
 # Built-in v4 tool runtime helpers and file tools
 from dare_framework.tool._internal import (
+    AskUserTool,
+    CLIUserInputHandler,
+    IUserInputHandler,
     EditLineTool,
     FileExecutionControl,
     NoOpMCPClient,
@@ -87,6 +90,9 @@
     "NoOpTool",
     "ToolManager",
     # v4 tool runtime helpers and file tools
+    "AskUserTool",
+    "CLIUserInputHandler",
+    "IUserInputHandler",
     "NoOpMCPClient",
     "NoOpSkill",
     "RunCommandTool",

dare_framework/tool/_internal/__init__.py

@@ -13,6 +13,11 @@
 from dare_framework.tool._internal.adapters.noop_mcp_client import NoOpMCPClient
 from dare_framework.tool._internal.toolkits.mcp_toolkit import MCPToolkit
 from dare_framework.tool._internal.managers.tool_manager import ToolManager
+from dare_framework.tool._internal.tools.ask_user import (
+    AskUserTool,
+    CLIUserInputHandler,
+    IUserInputHandler,
+)
 from dare_framework.tool._internal.tools.echo_tool import EchoTool
 from dare_framework.tool._internal.tools.noop_tool import NoopTool
 from dare_framework.tool._internal.tools.noop_skill import NoOpSkill
@@ -24,6 +29,9 @@
 from dare_framework.tool._internal.utils.run_context_state import RunContextState
 
 __all__ = [
+    "AskUserTool",
+    "CLIUserInputHandler",
+    "IUserInputHandler",
     "Checkpoint",
     "DefaultExecutionControl",
     "FileExecutionControl",

dare_framework/tool/_internal/tools/__init__.py

@@ -1,5 +1,10 @@
 """Built-in tool implementations for the tool domain."""
 
+from dare_framework.tool._internal.tools.ask_user import (
+    AskUserTool,
+    CLIUserInputHandler,
+    IUserInputHandler,
+)
 from dare_framework.tool._internal.tools.echo_tool import EchoTool
 from dare_framework.tool._internal.tools.noop_skill import NoOpSkill
 from dare_framework.tool._internal.tools.noop_tool import NoopTool
@@ -10,6 +15,9 @@
 from dare_framework.tool._internal.tools.edit_line import EditLineTool
 
 __all__ = [
+    "AskUserTool",
+    "CLIUserInputHandler",
+    "IUserInputHandler",
     "EchoTool",
     "NoOpSkill",
     "NoopTool",