ripperdoc 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

ripperdoc/core/query_utils.py

@@ -4,10 +4,10 @@ from __future__ import annotations
 
 import json
 import re
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Mapping, Optional, Union
 from uuid import uuid4
 
-from json_repair import repair_json
+from json_repair import repair_json  # type: ignore[import-not-found]
 from pydantic import ValidationError
 
 from ripperdoc.core.config import ModelProfile, ProviderType, get_global_config
@@ -26,17 +26,25 @@ from ripperdoc.utils.messages import (
 logger = get_logger()
 
 
-def _safe_int(value: Any) -> int:
+def _safe_int(value: object) -> int:
     """Best-effort int conversion for usage counters."""
     try:
         if value is None:
             return 0
-        return int(value)
+        if isinstance(value, bool):
+            return int(value)
+        if isinstance(value, (int, float)):
+            return int(value)
+        if isinstance(value, str):
+            return int(value)
+        if hasattr(value, "__int__"):
+            return int(value)  # type: ignore[arg-type]
+        return 0
     except (TypeError, ValueError):
         return 0
 
 
-def _get_usage_field(usage: Any, field: str) -> int:
+def _get_usage_field(usage: Optional[Mapping[str, Any] | object], field: str) -> int:
     """Fetch a usage field from either a dict or object."""
     if usage is None:
         return 0
@@ -45,7 +53,7 @@ def _get_usage_field(usage: Any, field: str) -> int:
     return _safe_int(getattr(usage, field, 0))
 
 
-def anthropic_usage_tokens(usage: Any) -> Dict[str, int]:
+def anthropic_usage_tokens(usage: Optional[Mapping[str, Any] | object]) -> Dict[str, int]:
     """Extract token counts from an Anthropic response usage payload."""
     return {
         "input_tokens": _get_usage_field(usage, "input_tokens"),
@@ -55,7 +63,7 @@ def anthropic_usage_tokens(usage: Any) -> Dict[str, int]:
     }
 
 
-def openai_usage_tokens(usage: Any) -> Dict[str, int]:
+def openai_usage_tokens(usage: Optional[Mapping[str, Any] | object]) -> Dict[str, int]:
     """Extract token counts from an OpenAI-compatible response usage payload."""
     prompt_details = None
     if isinstance(usage, dict):
@@ -73,8 +81,24 @@ def openai_usage_tokens(usage: Any) -> Dict[str, int]:
     }
 
 
+def estimate_cost_usd(model_profile: ModelProfile, usage_tokens: Dict[str, int]) -> float:
+    """Compute USD cost using per-1M token pricing from the model profile."""
+    input_price = getattr(model_profile, "input_cost_per_million_tokens", 0.0) or 0.0
+    output_price = getattr(model_profile, "output_cost_per_million_tokens", 0.0) or 0.0
+
+    total_input_tokens = (
+        _safe_int(usage_tokens.get("input_tokens"))
+        + _safe_int(usage_tokens.get("cache_read_input_tokens"))
+        + _safe_int(usage_tokens.get("cache_creation_input_tokens"))
+    )
+    output_tokens = _safe_int(usage_tokens.get("output_tokens"))
+
+    cost = (total_input_tokens * input_price + output_tokens * output_price) / 1_000_000
+    return float(cost)
+
+
 def resolve_model_profile(model: str) -> ModelProfile:
-    """Resolve a model pointer to a concrete profile or raise if missing."""
+    """Resolve a model pointer to a concrete profile, falling back to a safe default."""
     config = get_global_config()
     profile_name = getattr(config.model_pointers, model, None) or model
     model_profile = config.model_profiles.get(profile_name)
@@ -82,7 +106,11 @@ def resolve_model_profile(model: str) -> ModelProfile:
         fallback_profile = getattr(config.model_pointers, "main", "default")
         model_profile = config.model_profiles.get(fallback_profile)
     if not model_profile:
-        raise ValueError(f"No model profile found for pointer: {model}")
+        logger.warning(
+            "[config] No model profile found; using built-in default profile",
+            extra={"model_pointer": model},
+        )
+        return ModelProfile(provider=ProviderType.OPENAI_COMPATIBLE, model="gpt-4o-mini")
     return model_profile
 
 
@@ -103,12 +131,10 @@ def _parse_text_mode_json_blocks(text: str) -> Optional[List[Dict[str, Any]]]:
     if not text or not isinstance(text, str):
         return None
 
-    code_blocks = re.findall(
-        r"```(?:\s*json)?\s*([\s\S]*?)\s*```", text, flags=re.IGNORECASE
-    )
+    code_blocks = re.findall(r"```(?:\s*json)?\s*([\s\S]*?)\s*```", text, flags=re.IGNORECASE)
     candidates = [blk.strip() for blk in code_blocks if blk.strip()]
 
-    def _normalize_blocks(parsed: Any) -> Optional[List[Dict[str, Any]]]:
+    def _normalize_blocks(parsed: object) -> Optional[List[Dict[str, Any]]]:
         raw_blocks = parsed if isinstance(parsed, list) else [parsed]
         normalized: List[Dict[str, Any]] = []
         for raw in raw_blocks:
@@ -204,7 +230,9 @@ def _tool_prompt_for_text_mode(tools: List[Tool[Any, Any]]) -> str:
 
         schema_json = ""
         try:
-            schema_json = json.dumps(tool.input_schema.model_json_schema(), ensure_ascii=False, indent=2)
+            schema_json = json.dumps(
+                tool.input_schema.model_json_schema(), ensure_ascii=False, indent=2
+            )
         except (AttributeError, TypeError, ValueError) as exc:
             logger.debug(
                 "[tool_prompt] Failed to render input_schema",
@@ -218,7 +246,12 @@ def _tool_prompt_for_text_mode(tools: List[Tool[Any, Any]]) -> str:
 
     example_blocks = [
         {"type": "text", "text": "好的，我来帮你查看一下README.md文件"},
-        {"type": "tool_use", "tool_use_id": "tool_id_000001", "tool": "View", "input": {"file_path": "README.md"}},
+        {
+            "type": "tool_use",
+            "tool_use_id": "tool_id_000001",
+            "tool": "View",
+            "input": {"file_path": "README.md"},
+        },
     ]
     lines.append("Example:")
     lines.append("```json")
@@ -228,7 +261,9 @@ def _tool_prompt_for_text_mode(tools: List[Tool[Any, Any]]) -> str:
     return "\n".join(lines)
 
 
-def text_mode_history(messages: List[Union[UserMessage, AssistantMessage, ProgressMessage]]) -> List[Union[UserMessage, AssistantMessage]]:
+def text_mode_history(
+    messages: List[Union[UserMessage, AssistantMessage, ProgressMessage]],
+) -> List[Union[UserMessage, AssistantMessage]]:
     """Convert a message history into text-only form for text mode."""
 
     def _normalize_block(block: Any) -> Optional[Dict[str, Any]]:
@@ -269,9 +304,13 @@ def text_mode_history(messages: List[Union[UserMessage, AssistantMessage, Progre
         if isinstance(content, list):
             normalized_blocks = []
             for block in content:
-                block_type = getattr(block, "type", None) or (block.get("type") if isinstance(block, dict) else None)
-                block_text = getattr(block, "text", None) if hasattr(block, "text") else (
-                    block.get("text") if isinstance(block, dict) else None
+                block_type = getattr(block, "type", None) or (
+                    block.get("type") if isinstance(block, dict) else None
+                )
+                block_text = (
+                    getattr(block, "text", None)
+                    if hasattr(block, "text")
+                    else (block.get("text") if isinstance(block, dict) else None)
                 )
                 if block_type == "text" and isinstance(block_text, str):
                     parsed_nested = _parse_text_mode_json_blocks(block_text)
@@ -287,7 +326,9 @@ def text_mode_history(messages: List[Union[UserMessage, AssistantMessage, Progre
         elif isinstance(content, str):
             parsed_blocks = _parse_text_mode_json_blocks(content)
             if parsed_blocks:
-                text_content = f"```json\n{json.dumps(parsed_blocks, ensure_ascii=False, indent=2)}\n```"
+                text_content = (
+                    f"```json\n{json.dumps(parsed_blocks, ensure_ascii=False, indent=2)}\n```"
+                )
             else:
                 text_content = content
         else:
@@ -301,7 +342,9 @@ def text_mode_history(messages: List[Union[UserMessage, AssistantMessage, Progre
     return converted
 
 
-def _maybe_convert_json_block_to_tool_use(content_blocks: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+def _maybe_convert_json_block_to_tool_use(
+    content_blocks: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
     """Convert any text blocks containing JSON content to structured content blocks."""
     if not content_blocks:
         return content_blocks
@@ -437,9 +480,7 @@ async def build_openai_tool_schemas(tools: List[Tool[Any, Any]]) -> List[Dict[st
     return openai_tools
 
 
-def content_blocks_from_anthropic_response(
-    response: Any, tool_mode: str
-) -> List[Dict[str, Any]]:
+def content_blocks_from_anthropic_response(response: Any, tool_mode: str) -> List[Dict[str, Any]]:
     """Normalize Anthropic response content to our internal block format."""
     blocks: List[Dict[str, Any]] = []
     for block in getattr(response, "content", []) or []:

ripperdoc/core/system_prompt.py

@@ -8,7 +8,19 @@ from pathlib import Path
 from textwrap import dedent
 from typing import Any, Dict, Iterable, List, Optional
 
-from ripperdoc.core.agents import clear_agent_cache, load_agent_definitions, summarize_agent
+from ripperdoc.core.agents import (
+    ASK_USER_QUESTION_TOOL_NAME,
+    BASH_TOOL_NAME,
+    FILE_EDIT_TOOL_NAME,
+    FILE_WRITE_TOOL_NAME,
+    TASK_TOOL_NAME,
+    TODO_WRITE_TOOL_NAME,
+    TOOL_SEARCH_TOOL_NAME,
+    VIEW_TOOL_NAME,
+    clear_agent_cache,
+    load_agent_definitions,
+    summarize_agent,
+)
 from ripperdoc.core.tool import Tool
 from ripperdoc.utils.log import get_logger
 
@@ -174,10 +186,18 @@ def build_system_prompt(
 ) -> str:
     _ = user_prompt, context
     tool_names = {tool.name for tool in tools}
-    todo_tool_name = "TodoWrite"
+    todo_tool_name = TODO_WRITE_TOOL_NAME
     todo_available = todo_tool_name in tool_names
-    task_available = "Task" in tool_names
-    shell_tool_name = next((tool.name for tool in tools if tool.name.lower() == "bash"), "Bash")
+    task_available = TASK_TOOL_NAME in tool_names
+    ask_tool_name = ASK_USER_QUESTION_TOOL_NAME
+    ask_available = ask_tool_name in tool_names
+    view_tool_name = VIEW_TOOL_NAME
+    file_edit_tool_name = FILE_EDIT_TOOL_NAME
+    file_write_tool_name = FILE_WRITE_TOOL_NAME
+    shell_tool_name = next(
+        (tool.name for tool in tools if tool.name.lower() == BASH_TOOL_NAME.lower()),
+        BASH_TOOL_NAME,
+    )
 
     main_prompt = dedent(
         f"""\
@@ -190,61 +210,25 @@ def build_system_prompt(
         - /help: Get help with using {APP_NAME}
         - To give feedback, users should report the issue at {FEEDBACK_URL}
 
-        # Tone and style
-        You should be concise, direct, and to the point.
-        You MUST answer concisely with fewer than 4 lines (not including tool use or code generation), unless user asks for detail.
-        IMPORTANT: You should minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy. Only address the specific query or task at hand, avoiding tangential information unless absolutely critical for completing the request. If you can answer in 1-3 sentences or a short paragraph, please do.
-        IMPORTANT: You should NOT answer with unnecessary preamble or postamble (such as explaining your code or summarizing your action), unless the user asks you to.
-        Do not add additional code explanation summary unless requested by the user. After working on a file, just stop, rather than providing an explanation of what you did.
-        Answer the user's question directly, without elaboration, explanation, or details. One word answers are best. Avoid introductions, conclusions, and explanations. You MUST avoid text before/after your response, such as "The answer is <answer>.", "Here is the content of the file..." or "Based on the information provided, the answer is..." or "Here is what I will do next...". Here are some examples to demonstrate appropriate verbosity:
-        <example>
-        user: 2 + 2
-        assistant: 4
-        </example>
-
-        <example>
-        user: what is 2+2?
-        assistant: 4
-        </example>
-
-        <example>
-        user: is 11 a prime number?
-        assistant: Yes
-        </example>
-
-        <example>
-        user: what command should I run to list files in the current directory?
-        assistant: ls
-        </example>
+        # Looking up your own documentation
+        When the user asks what {APP_NAME} can do, how to use it (hooks, slash commands, MCP, SDKs), or requests SDK code samples, use the {TASK_TOOL_NAME} tool with a documentation-focused subagent (for example, subagent_type="docs") if available to consult official docs before answering.
 
-        <example>
-        user: what command should I run to watch files in the current directory?
-        assistant: [use the ls tool to list the files in the current directory, then read docs/commands in the relevant file to find out how to watch files]
-        npm run dev
-        </example>
-
-        <example>
-        user: How many golf balls fit inside a jetta?
-        assistant: 150000
-        </example>
-
-        <example>
-        user: what files are in the directory src/?
-        assistant: [runs ls and sees foo.c, bar.c, baz.c]
-        user: which file contains the implementation of foo?
-        assistant: src/foo.c
-        </example>
-
-        <example>
-        user: write tests for new feature
-        assistant: [uses grep and glob search tools to find where similar tests are defined, uses concurrent read file tool use blocks in one tool call to read relevant files at the same time, uses edit file tool to write new tests]
-        </example>
+        # Tone and style
+        - Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
+        - Your output will be displayed on a command line interface. Your responses should be short and concise. You can use Github-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+        - Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like {BASH_TOOL_NAME} or code comments as means to communicate with the user during the session.
+        - NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.
+
+        # Professional objectivity
+        Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation. It is best for the user if Claude honestly applies the same rigorous standards to all ideas and disagrees when necessary, even if it may not be what the user wants to hear. Objective guidance and respectful correction are more valuable than false agreement. Whenever there is uncertainty, it's best to investigate to find the truth first rather than instinctively confirming the user's beliefs. Avoid using over-the-top validation or excessive praise when responding to users such as "You're absolutely right" or similar phrases.
+
+        # Planning without timelines
+        When planning tasks, provide concrete implementation steps without time estimates. Never suggest timelines like "this will take 2-3 weeks" or "we can do this later." Focus on what needs to be done, not when. Break work into actionable steps and let users decide scheduling.
+      
+        # Explain Your Code: Bash Command Transparency
         When you run a non-trivial bash command, you should explain what the command does and why you are running it, to make sure the user understands what you are doing (this is especially important when you are running a command that will make changes to the user's system).
         Remember that your output will be displayed on a command line interface. Your responses can use Github-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
-        Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like {shell_tool_name} or code comments as means to communicate with the user during the session.
         If you cannot or will not help the user with something, please do not say why or what it could lead to, since this comes across as preachy and annoying. Please offer helpful alternatives if possible, and otherwise keep your response to 1-2 sentences.
-        Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
-        IMPORTANT: Keep your responses short, since they will be displayed on a command line interface.  
 
         # Proactiveness
         You are allowed to be proactive, but only when the user asks you to do something. You should strive to strike a balance between:
@@ -260,7 +244,7 @@ def build_system_prompt(
         - Always follow security best practices. Never introduce code that exposes or logs secrets and keys. Never commit secrets or keys to the repository.
 
         # Code style
-        - IMPORTANT: DO NOT ADD ***ANY*** COMMENTS unless asked"""
+        - Only add comments when the logic is not self-evident and within code you changed. Do not add docstrings, comments, or type annotations to code you did not modify."""
     ).strip()
 
     if mcp_instructions:
@@ -318,6 +302,15 @@ def build_system_prompt(
             </example>"""
         ).strip()
 
+    ask_questions_section = ""
+    if ask_available:
+        ask_questions_section = dedent(
+            f"""\
+            # Asking questions as you work
+
+            You have access to the {ask_tool_name} tool to ask the user questions when you need clarification, want to validate assumptions, or need to make a decision you're unsure about. When presenting options or plans, do not include time estimates—focus on what each option involves."""
+        ).strip()
+
     hooks_section = dedent(
         """\
         Users may configure 'hooks', shell commands that execute in response to events like tool calls, in settings. Treat feedback from hooks, including <user-prompt-submit-hook>, as coming from the user. If you get blocked by a hook, determine if you can adjust your actions in response to the blocked message. If not, ask the user to check their hooks configuration."""
@@ -329,15 +322,26 @@ def build_system_prompt(
     ]
     if todo_available:
         doing_tasks_lines.append(f"- Use the {todo_tool_name} tool to plan the task if required")
+    if ask_available:
+        doing_tasks_lines.append(
+            f"- Use the {ask_tool_name} tool to ask questions, clarify, and gather information as needed."
+        )
     doing_tasks_lines.extend(
         [
+            "- NEVER propose changes to code you haven't read. If a user asks about or wants you to modify a file, read it first.",
             "- Use the available search tools to understand the codebase and the user's query. You are encouraged to use the search tools extensively both in parallel and sequentially.",
-            "- Implement the solution using all tools available to you",
+            "- When exploring the codebase beyond a needle query, prefer using the Task tool with an exploration subagent if available instead of running raw search commands directly.",
+            "- Implement the solution using all tools available to you.",
+            "- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities. If you notice that you wrote insecure code, immediately fix it.",
+            "- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.",
+            "  - Don't add features, refactor code, or make improvements beyond what was asked. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.",
+            "  - Don't add error handling, fallbacks, or validation for scenarios that can't happen. Validate only at system boundaries (user input, external APIs).",
+            "  - Don't create helpers, utilities, or abstractions for one-time operations. Avoid feature flags or backwards-compatibility shims when a direct change is sufficient. If something is unused, delete it completely.",
             "- Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the README or search codebase to determine the testing approach.",
             f"- VERY IMPORTANT: When you have completed a task, you MUST run the lint and typecheck commands (eg. npm run lint, npm run typecheck, ruff, etc.) with {shell_tool_name} if they were provided to you to ensure your code is correct. If you are unable to find the correct command, ask the user for the command to run and if they supply it, proactively suggest writing it to AGENTS.md so that you will know to run it next time.",
             "NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.",
-            "",
             "- Tool results and user messages may include <system-reminder> tags. <system-reminder> tags contain useful information and reminders. They are NOT part of the user's provided input or the tool result.",
+            "- The conversation has unlimited context through automatic summarization. Complete tasks fully; do not stop mid-task or claim context limits.",
         ]
     )
     doing_tasks_section = "\n".join(doing_tasks_lines)
@@ -345,7 +349,8 @@ def build_system_prompt(
     tool_usage_lines = [
         "# Tool usage policy",
         '- You have the capability to call multiple tools in a single response. When multiple independent pieces of information are requested, batch your tool calls together for optimal performance. When making multiple bash tool calls, you MUST send a single message with multiple tools calls to run the calls in parallel. For example, if you need to run "git status" and "git diff", send a single message with two tool calls to run the calls in parallel.',
-        "",
+        "- If the user asks to run tools in parallel and there are no dependencies, include multiple tool calls in a single message; sequence dependent calls instead of guessing values.",
+        f"- Use specialized tools instead of bash when possible: use {view_tool_name} for reading files, {file_edit_tool_name} for editing, and {file_write_tool_name} for creating files. Do not use bash echo or other command-line tools to communicate with the user; reply in text.",
         "You MUST answer concisely with fewer than 4 lines of text (not including tool use or code generation), unless user asks for detail.",
     ]
     if task_available:
@@ -353,7 +358,7 @@ def build_system_prompt(
             1,
             "- Use the Task tool with configured subagents when the task matches an agent's description. Always set subagent_type.",
         )
-    if "ToolSearch" in tool_names:
+    if TOOL_SEARCH_TOOL_NAME in tool_names:
         tool_usage_lines.insert(
             1,
             "- Use the ToolSearch tool to discover and activate deferred or MCP tools. Keep searches focused and load only 3-5 relevant tools.",
@@ -402,6 +407,7 @@ def build_system_prompt(
     sections: List[str] = [
         main_prompt,
         task_management_section,
+        ask_questions_section,
         hooks_section,
         doing_tasks_section,
         tool_usage_section,
@@ -409,7 +415,7 @@ def build_system_prompt(
         build_environment_prompt(),
         DEFENSIVE_SECURITY_GUIDELINE,
         always_use_todo,
-        build_commit_workflow_prompt(shell_tool_name, todo_tool_name, "Task"),
+        build_commit_workflow_prompt(shell_tool_name, todo_tool_name, TASK_TOOL_NAME),
         code_references,
     ]
 

ripperdoc/core/tool.py

@@ -8,6 +8,7 @@ import json
 from abc import ABC, abstractmethod
 from typing import Any, AsyncGenerator, Dict, List, Optional, TypeVar, Generic, Union
 from pydantic import BaseModel, ConfigDict, Field
+from ripperdoc.utils.file_watch import FileSnapshot
 from ripperdoc.utils.log import get_logger
 
 
@@ -39,9 +40,17 @@ class ToolUseContext(BaseModel):
     safe_mode: bool = False
     verbose: bool = False
     permission_checker: Optional[Any] = None
-    read_file_timestamps: Dict[str, float] = {}
+    read_file_timestamps: Dict[str, float] = Field(default_factory=dict)
+    file_state_cache: Dict[str, "FileSnapshot"] = Field(default_factory=dict)
     tool_registry: Optional[Any] = None
     abort_signal: Optional[Any] = None
+    # UI control callbacks for tools that need user interaction
+    pause_ui: Optional[Any] = Field(default=None, description="Callback to pause UI spinner")
+    resume_ui: Optional[Any] = Field(default=None, description="Callback to resume UI spinner")
+    # Plan mode control callback
+    on_exit_plan_mode: Optional[Any] = Field(
+        default=None, description="Callback invoked when exiting plan mode"
+    )
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
 
@@ -202,7 +211,7 @@ async def build_tool_description(
     except Exception:
         logger.exception(
             "[tool] Failed to build input example section",
-            extra={"tool": getattr(tool, 'name', None)},
+            extra={"tool": getattr(tool, "name", None)},
         )
         return description_text
 
@@ -221,7 +230,7 @@ def tool_input_examples(tool: Tool[Any, Any], limit: int = 5) -> List[Dict[str,
         except Exception:
             logger.exception(
                 "[tool] Failed to format tool input example",
-                extra={"tool": getattr(tool, 'name', None)},
+                extra={"tool": getattr(tool, "name", None)},
             )
             continue
     return results

ripperdoc/sdk/client.py

@@ -19,11 +19,13 @@ from typing import (
     List,
     Optional,
     Sequence,
+    Tuple,
     Union,
 )
 
 from ripperdoc.core.default_tools import get_default_tools
 from ripperdoc.core.query import QueryContext, query as _core_query
+from ripperdoc.core.permissions import PermissionResult
 from ripperdoc.core.system_prompt import build_system_prompt
 from ripperdoc.core.tool import Tool
 from ripperdoc.tools.task_tool import TaskTool
@@ -42,7 +44,16 @@ from ripperdoc.utils.mcp import (
 )
 
 MessageType = Union[UserMessage, AssistantMessage, ProgressMessage]
-PermissionChecker = Callable[[Tool[Any, Any], Any], Union[Awaitable[Any], Any]]
+PermissionChecker = Callable[
+    [Tool[Any, Any], Any],
+    Union[
+        PermissionResult,
+        Dict[str, Any],
+        Tuple[bool, Optional[str]],
+        bool,
+        Awaitable[Union[PermissionResult, Dict[str, Any], Tuple[bool, Optional[str]], bool]],
+    ],
+]
 QueryRunner = Callable[
     [
         List[MessageType],