Ask user tool

README.md

@@ -59,6 +59,12 @@ Allows the model to browse Wikipedia using its API.
 *   **Workflow**: Use `mode='summary'` (default) to get an overview and a Table of Contents. Use `mode='section'` with a linear index from the ToC to dive into specific details.
 *   **Features**: Returns raw Wikitext to save tokens, handles redirects, and automatically falls back to a search result list if a page is not found.
 
+### 🗣️ `ask_user`
+Asks the human operator a question and waits for their answer.
+*   **Best for**: Circuit-breaking when the model is missing critical context or needs guidance. Use this to interject when the model gets stuck.
+*   **Workflow**: The model calls `ask_user` with a `question` string. The question is printed to the MCP server's terminal, and the server blocks until you type an answer and press Enter.
+*   **Behavior**: Blocks indefinitely — there is no timeout. The answer is returned to the model as the tool result.
+
 ---
 
 ## Installation & Requirements

tools/__init__.py

@@ -26,6 +26,7 @@ from .browse_wikipedia import handle as wikipedia_handler
 from .get_model_info import handle as get_model_info_handler
 from .generate_image import handle as generate_image_handler
 from .search_tags import handle as search_tags_handler
+from .ask_user import handle as ask_user_handler
 
 # Central registry of all available tools
 TOOL_REGISTRY = [
@@ -167,4 +168,16 @@ TOOL_REGISTRY = [
         },
         handler=search_tags_handler
     ),
+    Tool(
+        name="ask_user",
+        description="Asks the human operator a question and waits for their answer. Use this when the model is missing critical information or needs guidance. This blocks the server until the user responds.",
+        schema={
+            "type": "object",
+            "properties": {
+                "question": {"type": "string", "description": "The question to ask the human operator."}
+            },
+            "required": ["question"],
+        },
+        handler=ask_user_handler
+    ),
 ]

tools/ask_user.py

@@ -0,0 +1,31 @@
+import asyncio
+from typing import Any, Dict
+from tools.utils import ToolError
+
+logger = None  # logging not wired up in this module; keep it simple
+
+async def handle(args: Dict[str, Any]):
+    """
+    Asks the human operator a question and blocks until they type an answer.
+    Intended as a circuit-breaker when the model is missing critical context
+    or needs guidance. Prints the question to the MCP server's terminal and
+    reads the answer from stdin.
+    """
+    question = args.get("question")
+    if not question:
+        raise ToolError("Missing 'question' argument")
+
+    # Print the question to the server terminal so the human sees it.
+    print(f">>> {question}")
+
+    try:
+        answer = await asyncio.to_thread(input, ">>> ")
+    except (EOFError, KeyboardInterrupt):
+        print("\n>>> Input interrupted.")
+        raise ToolError("ask_user was interrupted")
+
+    answer = (answer or "").strip()
+    if not answer:
+        raise ToolError("ask_user received an empty answer")
+
+    return [{"type": "text", "text": answer}]