Upload folder using huggingface_hub (part 3)

src/agentscope/model/_openai_response/_models/gpt-5.4.yaml

@@ -0,0 +1,22 @@
+name: gpt-5.4
+label: GPT-5.4 (Responses API)
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1050000
+output_size: 128000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 128000
+  reasoning_effort:
+    hidden: true

src/agentscope/model/_openai_response/_models/gpt-5.5.yaml

@@ -0,0 +1,26 @@
+name: gpt-5.5
+label: GPT-5.5
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+  - audio/mp3
+  - audio/wav
+
+output_types:
+  - text/plain
+
+context_size: 1050000
+output_size: 128000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 128000
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true

src/agentscope/model/_openai_response/_models/o3.yaml

@@ -0,0 +1,24 @@
+name: o3
+label: o3 (Responses API)
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 100000
+  temperature:
+    hidden: true

src/agentscope/model/_openai_response/_models/o4-mini.yaml

@@ -0,0 +1,24 @@
+name: o4-mini
+label: o4-mini (Responses API)
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 100000
+  temperature:
+    hidden: true

src/agentscope/model/_xai/__init__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The xAI LLM API modules."""
+
+from ._model import XAICredential, XAIChatModel
+
+__all__ = [
+    "XAICredential",
+    "XAIChatModel",
+]

src/agentscope/model/_xai/_model.py

@@ -0,0 +1,455 @@
+# -*- coding: utf-8 -*-
+"""The xAI chat model implementation using the official xai_sdk."""
+from datetime import datetime
+from typing import Any, AsyncGenerator, List, Literal, TYPE_CHECKING, Type
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import XAICredential
+from ...formatter import XAIChatFormatter
+from ...message import (
+    Msg,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+)
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from xai_sdk import AsyncClient
+    from xai_sdk.chat import Response
+else:
+    AsyncClient = Any
+    Response = Any
+
+
+class XAIChatModel(ChatModelBase):
+    """The xAI chat model using the official ``xai_sdk`` gRPC client.
+
+    This model provides native access to xAI-specific features such as
+    server-side agentic tools (web search, X search, code execution) and
+    reasoning effort control, which are not available through the
+    OpenAI-compatible REST endpoint.
+    """
+
+    class Parameters(BaseModel):
+        """The parameters for the xAI chat model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of tokens for the LLM output.",
+            gt=0,
+        )
+        """The maximum number of tokens to generate."""
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description=(
+                "Whether to enable reasoning for models that support "
+                "extended thinking (e.g. ``grok-3-mini``). Use "
+                "reasoning_effort to control the depth of reasoning."
+            ),
+        )
+
+        reasoning_effort: Literal["low", "medium", "high"] | None = Field(
+            default=None,
+            title="Reasoning Effort",
+            description=(
+                "Controls the depth of reasoning for models that support "
+                "extended thinking (e.g. ``grok-3-mini``). Set to "
+                "``'low'``, ``'medium'``, or ``'high'`` to enable reasoning "
+                "with the corresponding effort level. ``None`` disables "
+                "reasoning."
+            ),
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            le=2,
+        )
+        """The sampling temperature."""
+
+        top_p: float | None = Field(
+            default=None,
+            title="Top P",
+            description="The top-p nucleus sampling value.",
+            gt=0,
+            le=1,
+        )
+        """The top-p sampling parameter."""
+
+    type: Literal["xai_chat"] = "xai_chat"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: XAICredential,
+        model: str,
+        parameters: "XAIChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 131072,
+        formatter: XAIChatFormatter | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the xAI chat model.
+
+        Args:
+            credential (`XAICredential`):
+                The xAI credential used to authenticate API calls.
+            model (`str`):
+                The xAI model name, e.g. ``grok-3`` or ``grok-3-mini``.
+            parameters (`XAIChatModel.Parameters | None`, defaults to \
+            `None`):
+                The xAI API parameters. When ``None``, the default
+                parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the xAI API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `131072`):
+                The model context size used for context compression.
+            formatter (`XAIChatFormatter | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to xai_sdk
+                proto messages. When ``None``, an ``XAIChatFormatter``
+                instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``xai_sdk.AsyncClient``
+                (e.g. ``timeout``, ``metadata``, ``channel_options``). Keys
+                that overlap with credential-derived arguments (such as
+                ``api_key`` or ``api_host``) take precedence over the
+                credential values.
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or XAIChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import grpc
+
+        # xai_sdk uses grpc.aio under the hood; transport/API failures surface
+        # as grpc.aio.AioRpcError (subclass of grpc.RpcError). We retry the
+        # whole class because the retry mechanism here only filters by type,
+        # not by status code — so 4xx-equivalents (UNAUTHENTICATED, INVALID
+        # _ARGUMENT) will also be retried a few times before failing, which
+        # we accept. Note xai_sdk additionally retries UNAVAILABLE 5 times at
+        # the gRPC layer with exponential backoff before raising to us.
+        return (grpc.RpcError,)
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **generate_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the xAI API using the official ``xai_sdk`` gRPC client.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                A list of ``Msg`` objects representing the conversation.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Controls which (if any) tool is called by the model.
+            **generate_kwargs (`Any`):
+                Extra keyword arguments forwarded to the API.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+        from xai_sdk import AsyncClient
+
+        client = AsyncClient(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                "api_host": self.credential.api_host,
+                **self.client_kwargs,
+            },
+        )
+
+        xai_messages = await self.formatter.format(messages)
+
+        xai_tools, xai_tool_choice = self._format_tools(tools, tool_choice)
+
+        create_kwargs: dict[str, Any] = {"model": model_name}
+        if self.parameters.max_tokens is not None:
+            create_kwargs["max_tokens"] = self.parameters.max_tokens
+        if self.parameters.temperature is not None:
+            create_kwargs["temperature"] = self.parameters.temperature
+        if self.parameters.top_p is not None:
+            create_kwargs["top_p"] = self.parameters.top_p
+        if (
+            self.parameters.thinking_enable
+            and self.parameters.reasoning_effort
+        ):
+            create_kwargs[
+                "reasoning_effort"
+            ] = self.parameters.reasoning_effort
+        if xai_tools:
+            create_kwargs["tools"] = xai_tools
+        if xai_tool_choice is not None:
+            create_kwargs["tool_choice"] = xai_tool_choice
+
+        create_kwargs.update(generate_kwargs)
+
+        chat = client.chat.create(**create_kwargs)
+        for xai_msg in xai_messages:
+            chat.append(xai_msg)
+
+        start_datetime = datetime.now()
+
+        if self.stream:
+            return self._parse_stream_response(start_datetime, chat, client)
+
+        try:
+            response = await chat.sample()
+        finally:
+            await client.close()
+
+        return self._parse_completion_response(start_datetime, response)
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list | None, Any]:
+        """Validate, filter, and format tools and tool_choice for the xAI API.
+
+        When ``tool_choice.tools`` is specified the schemas list is filtered
+        to only those tools. When ``tool_choice.mode`` is a specific tool name
+        (str) the model is forced to call exactly that tool without needing to
+        filter the list, preserving prompt-cache efficiency.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list | None, Any]`:
+                A tuple of (xai_tools, xai_tool_choice) ready for the
+                ``xai_sdk`` client.
+        """
+        from xai_sdk.chat import required_tool, tool
+
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        xai_tools = None
+        if tools:
+            xai_tools = []
+            for t in tools:
+                if t.get("type") == "function" and "function" in t:
+                    fn = t["function"]
+                    xai_tools.append(
+                        tool(
+                            name=fn["name"],
+                            description=fn.get("description", ""),
+                            parameters=fn.get("parameters", {}),
+                        ),
+                    )
+
+        if not tool_choice:
+            return xai_tools, None
+
+        mode = tool_choice.mode
+
+        if mode in _TOOL_CHOICE_LITERAL_MODES:
+            return xai_tools, mode
+
+        return xai_tools, required_tool(mode)
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        chat: Any,
+        client: AsyncClient,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the xAI streaming response from ``xai_sdk``.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            chat (`Any`):
+                The ``xai_sdk`` chat session object.
+            client (`Any`):
+                The ``xai_sdk.AsyncClient`` instance; closed when the
+                generator is exhausted or abandoned.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``
+                followed by a final one with ``is_last=True``.
+        """
+        acc_text = TextBlock(text="")
+        acc_thinking = ThinkingBlock(thinking="")
+        last_response = None
+        response_id: str | None = None
+
+        try:
+            async for response, chunk in chat.stream():
+                if response_id is None:
+                    response_id = getattr(response, "id", None) or None
+
+                delta_text: str = chunk.content or ""
+                delta_thinking: str = chunk.reasoning_content or ""
+
+                delta_contents: List[TextBlock | ThinkingBlock] = []
+
+                if delta_thinking:
+                    acc_thinking.thinking += delta_thinking
+                    delta_contents.append(
+                        ThinkingBlock(
+                            id=acc_thinking.id,
+                            thinking=delta_thinking,
+                        ),
+                    )
+                if delta_text:
+                    acc_text.text += delta_text
+                    delta_contents.append(
+                        TextBlock(id=acc_text.id, text=delta_text),
+                    )
+
+                if delta_contents:
+                    _kwargs: dict[str, Any] = {
+                        "content": delta_contents,
+                        "is_last": False,
+                    }
+                    if response_id:
+                        _kwargs["id"] = response_id
+                    yield ChatResponse(**_kwargs)
+
+                last_response = response
+
+        finally:
+            await client.close()
+
+        final_contents: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+        if acc_thinking.thinking:
+            final_contents.append(acc_thinking)
+        if acc_text.text:
+            final_contents.append(acc_text)
+
+        if last_response is not None:
+            for tc in last_response.tool_calls or []:
+                final_contents.append(
+                    ToolCallBlock(
+                        id=tc.id,
+                        name=tc.function.name,
+                        input=tc.function.arguments,
+                    ),
+                )
+
+        usage = None
+        if last_response is not None and last_response.usage is not None:
+            u = last_response.usage
+            usage = ChatUsage(
+                input_tokens=u.prompt_tokens,
+                output_tokens=u.completion_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(
+                    u,
+                    "cached_prompt_text_tokens",
+                    0,
+                ),
+            )
+
+        final_kwargs: dict[str, Any] = {
+            "content": final_contents,
+            "usage": usage,
+            "is_last": True,
+        }
+        if response_id:
+            final_kwargs["id"] = response_id
+        yield ChatResponse(**final_kwargs)
+
+    def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: Response,
+    ) -> ChatResponse:
+        """Parse the xAI non-streaming response from ``xai_sdk``.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`Any`):
+                The ``xai_sdk`` ``Response`` object.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+        if response.reasoning_content:
+            content_blocks.append(
+                ThinkingBlock(thinking=response.reasoning_content),
+            )
+        if response.content:
+            content_blocks.append(TextBlock(text=response.content))
+
+        for tc in response.tool_calls or []:
+            content_blocks.append(
+                ToolCallBlock(
+                    id=tc.id,
+                    name=tc.function.name,
+                    input=tc.function.arguments,
+                ),
+            )
+
+        usage = None
+        if response.usage is not None:
+            u = response.usage
+            usage = ChatUsage(
+                input_tokens=u.prompt_tokens,
+                output_tokens=u.completion_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(
+                    u,
+                    "cached_prompt_text_tokens",
+                    0,
+                ),
+            )
+
+        resp_kwargs: dict[str, Any] = {
+            "content": content_blocks,
+            "is_last": True,
+            "usage": usage,
+        }
+        response_id = getattr(response, "id", None)
+        if response_id:
+            resp_kwargs["id"] = response_id
+
+        return ChatResponse(**resp_kwargs)

src/agentscope/model/_xai/_models/grok-3-fast.yaml

@@ -0,0 +1,19 @@
+name: grok-3-fast
+label: Grok 3 Fast
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 131072
+output_size: 16000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16000

src/agentscope/model/_xai/_models/grok-3-mini.yaml

@@ -0,0 +1,17 @@
+name: grok-3-mini
+label: Grok 3 Mini
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 131072
+output_size: 16000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16000

src/agentscope/model/_xai/_models/grok-3.yaml

@@ -0,0 +1,19 @@
+name: grok-3
+label: Grok 3
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 131072
+output_size: 16000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16000

src/agentscope/model/_xai/_models/grok-4.3.yaml

@@ -0,0 +1,19 @@
+name: grok-4.3
+label: Grok 4.3
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 30000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 30000

src/agentscope/permission/__init__.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""The tool permission related types and functions."""
+
+from ._context import PermissionContext, AdditionalWorkingDirectory
+from ._decision import PermissionDecision
+from ._engine import PermissionEngine
+from ._rule import PermissionRule
+from ._types import PermissionMode, PermissionBehavior
+
+__all__ = [
+    "PermissionContext",
+    "AdditionalWorkingDirectory",
+    "PermissionDecision",
+    "PermissionEngine",
+    "PermissionRule",
+    "PermissionMode",
+    "PermissionBehavior",
+]

src/agentscope/permission/_context.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""The permission context module."""
+from pydantic import BaseModel, Field
+
+from ._rule import PermissionRule
+from ._types import PermissionMode
+
+
+class AdditionalWorkingDirectory(BaseModel):
+    """An additional directory included in permission scope.
+
+    Working directories are used to determine which file paths should be
+    automatically allowed in ACCEPT_EDITS mode.
+    """
+
+    path: str
+    """Absolute path to the directory."""
+
+    source: str
+    """Where this directory permission originated from
+    (e.g., 'userSettings', 'session')."""
+
+
+class PermissionContext(BaseModel):
+    """Context for permission checking.
+
+    Contains the permission mode, working directories, and all configured
+    permission rules organized by behavior type (allow, deny, ask).
+    """
+
+    mode: PermissionMode = PermissionMode.DEFAULT
+    """The current permission mode."""
+
+    working_directories: dict[str, AdditionalWorkingDirectory] = Field(
+        default_factory=dict,
+    )
+    """Additional directories allowed for file operations, keyed by path."""
+
+    allow_rules: dict[str, list[PermissionRule]] = Field(default_factory=dict)
+    """Rules that allow tool execution, keyed by tool name."""
+
+    deny_rules: dict[str, list[PermissionRule]] = Field(default_factory=dict)
+    """Rules that deny tool execution, keyed by tool name."""
+
+    ask_rules: dict[str, list[PermissionRule]] = Field(default_factory=dict)
+    """Rules that require user confirmation, keyed by tool name."""

src/agentscope/permission/_decision.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+"""The permission decision result."""
+from dataclasses import dataclass
+from typing import Any
+
+from ._rule import PermissionRule
+from ._types import PermissionBehavior
+
+
+@dataclass
+class PermissionDecision:
+    """Decision result from permission checking.
+
+    Represents the outcome of a permission check, including whether
+    the action should be allowed, denied, or require user confirmation.
+    """
+
+    behavior: PermissionBehavior
+    """The permission behavior decision."""
+
+    message: str
+    """Human-readable message describing the decision."""
+
+    decision_reason: str | None = None
+    """Optional explanation for why this decision was made."""
+
+    updated_input: dict[str, Any] | None = None
+    """Optional modified input data (e.g., sanitized paths)."""
+
+    suggested_rules: list[PermissionRule] | None = None
+    """Optional list of suggested permission rules for user to apply."""
+
+    bypass_immune: bool = False
+    """Whether this decision is immune to being silenced by allow rules
+    ("bypass-immune").
+
+    Only meaningful when :attr:`behavior` is :attr:`PermissionBehavior.ASK`.
+    A tool sets this to ``True`` to signal that the operation is
+    dangerous enough that **no allow rule** may convert the ASK into an
+    ALLOW — the user must explicitly confirm in-the-moment. In
+    :attr:`PermissionMode.DONT_ASK` where no user is available, a
+    bypass-immune ASK is converted to DENY rather than silently allowed.
+
+    Per-mode handling of a ``bypass_immune=True`` ASK:
+
+    - ``DEFAULT`` / ``ACCEPT_EDITS``: honored — allow rules cannot
+      override.
+    - ``EXPLORE``: not applicable (the engine resolves EXPLORE via
+      :meth:`ToolBase.check_read_only` and does not invoke
+      :meth:`ToolBase.check_permissions`).
+    - ``BYPASS``: **intentionally ignored** — BYPASS's contract is
+      "the user has opted out of safety prompts; only deny / ask
+      rules remain as guardrails." Use deny rules in BYPASS to
+      enforce specific protections.
+    - ``DONT_ASK``: converted to DENY (no user available).
+
+    Default is ``False``: a regular ASK that may be overridden by an
+    allow rule in DEFAULT / ACCEPT_EDITS, and is silently allowed by
+    BYPASS's fallback. Tools should set this only for genuine safety
+    checks (e.g. writes to dangerous paths, ``rm -rf /``, command
+    injection patterns) — not for "I'd prefer user input" cases.
+
+    Note: this field is internal metadata for the permission engine.
+    Callers handling the decision (agent loop, HITL backend, UI) treat
+    a bypass-immune ASK the same as a regular ASK — both prompt the
+    user. The distinction only governs whether engine-level rules /
+    modes may override it before reaching the caller.
+    """

src/agentscope/permission/_engine.py

@@ -0,0 +1,729 @@
+# -*- coding: utf-8 -*-
+"""The permission engine for checking and enforcing permission rules."""
+from typing import Any, List, TYPE_CHECKING
+
+from ._context import PermissionContext
+from ._rule import PermissionRule
+from ._decision import PermissionDecision, PermissionBehavior
+from ._types import PermissionMode
+from .._utils._common import _execute_async_or_sync_func
+
+if TYPE_CHECKING:
+    from ..tool import ToolBase
+else:
+    ToolBase = "ToolBase"
+
+
+class PermissionEngine:
+    """Engine for checking and enforcing permission rules.
+
+    Evaluates tool execution requests against configured permission rules.
+    Matching strategy is delegated to each tool's :meth:`ToolBase.match_rule`:
+
+    - Bash tools: substring / prefix wildcard matching against the command
+    - Write/Read/Edit tools: glob matching against file paths
+    - Other tools: generic pattern matching (or tool-name-level only)
+
+    Each :class:`PermissionMode` has its own ``_check_<mode>`` method so
+    that mode policies are self-contained and readable in isolation. See
+    :meth:`check_permission` for the dispatcher and the individual methods
+    for per-mode evaluation order.
+    """
+
+    def __init__(
+        self,
+        context: PermissionContext,
+    ) -> None:
+        """Initialize the permission engine.
+
+        Args:
+            context (`PermissionContext`):
+                The permission context containing rules and mode
+
+        Example:
+            >>> context = PermissionContext(mode=PermissionMode.ACCEPT_EDITS)
+            >>> engine = PermissionEngine(context)
+        """
+        self.context = context
+
+    def add_rule(self, rule: PermissionRule) -> None:
+        """Add a permission rule to the context.
+
+        Args:
+            rule (`PermissionRule`):
+                The permission rule to add
+
+        Example:
+            >>> engine.add_rule(PermissionRule(
+            ...     tool_name="Bash",
+            ...     rule_content="git:*",
+            ...     behavior=PermissionBehavior.ALLOW,
+            ... ))
+        """
+
+        if rule.behavior == PermissionBehavior.ALLOW:
+            if rule.tool_name not in self.context.allow_rules:
+                self.context.allow_rules[rule.tool_name] = []
+            self.context.allow_rules[rule.tool_name].append(rule)
+        elif rule.behavior == PermissionBehavior.DENY:
+            if rule.tool_name not in self.context.deny_rules:
+                self.context.deny_rules[rule.tool_name] = []
+            self.context.deny_rules[rule.tool_name].append(rule)
+        elif rule.behavior == PermissionBehavior.ASK:
+            if rule.tool_name not in self.context.ask_rules:
+                self.context.ask_rules[rule.tool_name] = []
+            self.context.ask_rules[rule.tool_name].append(rule)
+
+    async def check_permission(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Check permission for a tool execution request.
+
+        Dispatches to a per-mode private method so each mode's policy
+        is self-contained and readable in isolation:
+
+        - DEFAULT      → :meth:`_check_default`
+        - EXPLORE      → :meth:`_check_explore`
+        - ACCEPT_EDITS → :meth:`_check_accept_edits`
+        - BYPASS       → :meth:`_check_bypass`
+        - DONT_ASK     → :meth:`_check_dont_ask`
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data, used for rule matching and
+                tool-specific checks.
+
+        Returns:
+            `PermissionDecision`:
+                Decision indicating whether to allow, deny, or ask.
+        """
+        mode = self.context.mode
+        if mode == PermissionMode.DEFAULT:
+            return await self._check_default(tool, tool_input)
+        if mode == PermissionMode.EXPLORE:
+            return await self._check_explore(tool, tool_input)
+        if mode == PermissionMode.ACCEPT_EDITS:
+            return await self._check_accept_edits(tool, tool_input)
+        if mode == PermissionMode.BYPASS:
+            return await self._check_bypass(tool, tool_input)
+        if mode == PermissionMode.DONT_ASK:
+            return await self._check_dont_ask(tool, tool_input)
+        raise ValueError(f"Unknown permission mode: {mode}")
+
+    async def _check_default(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.DEFAULT`.
+
+        Every operation requires explicit permission unless either an
+        allow rule matches or the tool's own ``check_permissions``
+        explicitly returns ALLOW (e.g. ``Bash`` auto-allows recognized
+        read-only commands like ``ls``/``git status``). Evaluation order:
+
+        1. Deny rules → DENY
+        2. Ask rules → ASK (with suggestions)
+        3. ``tool.check_permissions``:
+            - ALLOW / DENY → returned as-is
+            - Safety ASK (bypass-immune) → returned with suggestions; cannot
+              be overridden by allow rules
+            - Non-safety ASK / PASSTHROUGH → continue
+        4. Allow rules → ALLOW
+        5. Default → ASK (with suggestions)
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                The final decision.
+        """
+        # step 1: deny rules — highest priority
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return ask
+
+        # step 3: tool's own check_permissions
+        tool_decision = await tool.check_permissions(tool_input, self.context)
+        # step 3a: tool ALLOW / DENY returned as-is
+        if tool_decision.behavior in (
+            PermissionBehavior.ALLOW,
+            PermissionBehavior.DENY,
+        ):
+            return tool_decision
+        # step 3b: safety ASK is bypass-immune — allow rules can't override
+        if self._is_safety_ask(tool_decision):
+            tool_decision.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return tool_decision
+
+        # step 4: allow rules
+        allow = await self._check_allow_rules(tool, tool_input)
+        if allow:
+            return allow
+
+        # step 5: default — ASK the user
+        default = PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message=f"Permission required for {tool.name}",
+            decision_reason=f"Mode: {self.context.mode.value}",
+        )
+        default.suggested_rules = await self._generate_suggestions(
+            tool,
+            tool_input,
+        )
+        return default
+
+    async def _check_explore(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.EXPLORE`.
+
+        Read-only mode — modifications are categorically denied. Evaluation
+        order:
+
+        1. Deny rules → DENY
+        2. Ask rules → ASK (with suggestions)
+        3. :meth:`ToolBase.check_read_only` (input-aware):
+            - True  → ALLOW
+            - False → DENY
+
+        ``tool.check_permissions`` is not invoked: EXPLORE is fully
+        resolved by the read-only verdict, so safety ASK paths (e.g.
+        ``rm -rf /``) are subsumed into the broader DENY. Allow rules are
+        intentionally not consulted — EXPLORE's read-only guarantee
+        cannot be granted away by a user-configured rule.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                ALLOW for read-only invocations, DENY otherwise.
+        """
+        # step 1: deny rules
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return ask
+
+        # step 3: read-only verdict decides everything (ALLOW or DENY)
+        if await tool.check_read_only(tool_input):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message=(
+                    f"Permission granted for {tool.name} "
+                    f"(explore mode - read-only invocation)"
+                ),
+                decision_reason="Explore mode allows read-only operations",
+            )
+        return PermissionDecision(
+            behavior=PermissionBehavior.DENY,
+            message=(
+                f"Permission denied for {tool.name} "
+                f"(explore mode is read-only)"
+            ),
+            decision_reason="Explore mode does not allow modifications",
+        )
+
+    async def _check_accept_edits(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.ACCEPT_EDITS`.
+
+        Edits within working directories are auto-allowed by each tool's
+        own ``check_permissions``; other operations follow the normal
+        flow. Evaluation order:
+
+        1. Deny rules → DENY
+        2. Ask rules → ASK (with suggestions)
+        3. :meth:`ToolBase.check_read_only` → True → ALLOW (fast path)
+        4. ``tool.check_permissions``:
+            - ALLOW (e.g. ``Write`` to a file in the working directory) /
+              DENY → returned as-is
+            - Safety ASK (bypass-immune) → returned with suggestions
+            - Non-safety ASK / PASSTHROUGH → continue
+        5. Allow rules → ALLOW
+        6. Default → ASK (with suggestions)
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                The final decision.
+        """
+        # step 1: deny rules
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return ask
+
+        # step 3: read-only fast path — ALLOW without invoking the tool
+        if await tool.check_read_only(tool_input):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message=(
+                    f"Permission granted for {tool.name} "
+                    f"(accept edits mode - read-only invocation)"
+                ),
+                decision_reason="Accept edits mode allows read-only "
+                "operations",
+            )
+
+        # step 4: tool's own check_permissions (working-directory check
+        # for Write/Edit, path-checked auto-allow for Bash, ...)
+        tool_decision = await tool.check_permissions(tool_input, self.context)
+        # step 4a: tool ALLOW / DENY returned as-is
+        if tool_decision.behavior in (
+            PermissionBehavior.ALLOW,
+            PermissionBehavior.DENY,
+        ):
+            return tool_decision
+        # step 4b: safety ASK is bypass-immune
+        if self._is_safety_ask(tool_decision):
+            tool_decision.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return tool_decision
+
+        # step 5: allow rules
+        allow = await self._check_allow_rules(tool, tool_input)
+        if allow:
+            return allow
+
+        # step 6: default — ASK the user
+        default = PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message=f"Permission required for {tool.name}",
+            decision_reason=f"Mode: {self.context.mode.value}",
+        )
+        default.suggested_rules = await self._generate_suggestions(
+            tool,
+            tool_input,
+        )
+        return default
+
+    async def _check_bypass(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.BYPASS`.
+
+        BYPASS is the "fully trusted" mode: the user has explicitly
+        opted out of safety prompts. All tool-emitted safety ASKs
+        (``rm -rf /``, write to ``~/.bashrc``, command-injection
+        patterns, dangerous sed, etc.) are **skipped** — only
+        user-configured deny / ask rules and tool-emitted DENY remain
+        as guardrails. The :attr:`PermissionDecision.bypass_immune`
+        field has no effect in BYPASS by design.
+
+        Use BYPASS only for sandboxed / containerized environments or
+        when you fully trust the agent's behavior. For unattended
+        execution where safety still matters, use
+        :attr:`PermissionMode.DONT_ASK` instead — it converts safety
+        ASKs to DENY rather than skipping them.
+
+        Evaluation order:
+
+        1. Deny rules → DENY
+        2. Ask rules → ASK (with suggestions; honors explicit user intent)
+        3. ``tool.check_permissions``:
+            - ALLOW / DENY → returned as-is
+            - ASK (including bypass-immune safety ASKs) → falls through
+            - PASSTHROUGH → falls through
+        4. Allow rules → ALLOW
+        5. Fallback → ALLOW (BYPASS)
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                The final decision.
+        """
+        # step 1: deny rules
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules (honor explicit user intent to be prompted)
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return ask
+
+        # step 3: tool's own check_permissions — ALLOW / DENY returned;
+        # any ASK (including bypass-immune safety ASK) is intentionally
+        # NOT honored here, per BYPASS's "skip safety prompts" contract.
+        tool_decision = await tool.check_permissions(tool_input, self.context)
+        if tool_decision.behavior in (
+            PermissionBehavior.ALLOW,
+            PermissionBehavior.DENY,
+        ):
+            return tool_decision
+
+        # step 4: allow rules
+        allow = await self._check_allow_rules(tool, tool_input)
+        if allow:
+            return allow
+
+        # step 5: bypass fallback — ALLOW everything else
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"Permission granted for {tool.name} (bypass mode)",
+            decision_reason="Bypass mode allows all operations",
+        )
+
+    async def _check_dont_ask(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.DONT_ASK`.
+
+        Used when no user is available to answer prompts (scheduled
+        tasks, background runs). Invariant: this method must never
+        return :attr:`PermissionBehavior.ASK` — every code path that
+        would otherwise ASK is converted to DENY via
+        :meth:`_convert_ask_to_deny`. Evaluation order:
+
+        1. Deny rules → DENY
+        2. Ask rules → DENY (converted, with suggestions preserved)
+        3. ``tool.check_permissions``:
+            - ALLOW / DENY → returned as-is
+            - Safety ASK → DENY (converted, with suggestions preserved)
+            - Non-safety ASK / PASSTHROUGH → continue
+        4. Allow rules → ALLOW
+        5. Default → DENY (user not available to answer)
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                The final decision (never ASK).
+        """
+        # step 1: deny rules
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules — converted to DENY (no user available)
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return self._convert_ask_to_deny(tool, ask)
+
+        # step 3: tool's own check_permissions
+        tool_decision = await tool.check_permissions(tool_input, self.context)
+        # step 3a: tool ALLOW / DENY returned as-is
+        if tool_decision.behavior in (
+            PermissionBehavior.ALLOW,
+            PermissionBehavior.DENY,
+        ):
+            return tool_decision
+        # step 3b: safety ASK converted to DENY (no user available)
+        if self._is_safety_ask(tool_decision):
+            tool_decision.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return self._convert_ask_to_deny(tool, tool_decision)
+
+        # step 4: allow rules
+        allow = await self._check_allow_rules(tool, tool_input)
+        if allow:
+            return allow
+
+        # step 5: default — DENY (no user available to confirm)
+        return PermissionDecision(
+            behavior=PermissionBehavior.DENY,
+            message=(
+                f"Permission denied for {tool.name} "
+                f"(dont_ask mode - user not available)"
+            ),
+            decision_reason="User is not available to answer permission "
+            "prompts",
+        )
+
+    @staticmethod
+    def _convert_ask_to_deny(
+        tool: ToolBase,
+        ask_decision: PermissionDecision,
+    ) -> PermissionDecision:
+        """Convert an ASK decision into a DENY for DONT_ASK mode.
+
+        DONT_ASK's invariant is "never return ASK" — the user is not
+        available to answer prompts. This helper turns whatever produced
+        the ASK (an ASK rule, a safety check) into a DENY while
+        preserving traceability by carrying the original reason and
+        ``suggested_rules`` forward; callers (e.g. a UI surfacing the
+        scheduled-task failure) can still show the user what rule they
+        could add to unblock the operation in the future.
+
+        Args:
+            tool (`ToolBase`):
+                The tool whose invocation is being denied.
+            ask_decision (`PermissionDecision`):
+                The original ASK decision to convert.
+
+        Returns:
+            `PermissionDecision`:
+                A DENY decision with the original ASK's reason and
+                suggestions attached.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.DENY,
+            message=(
+                f"Permission denied for {tool.name} "
+                f"(dont_ask mode - ASK converted to DENY, "
+                f"user not available)"
+            ),
+            decision_reason=(
+                f"DONT_ASK mode converted ASK to DENY. "
+                f"Original reason: {ask_decision.decision_reason}"
+            ),
+            suggested_rules=ask_decision.suggested_rules,
+        )
+
+    @staticmethod
+    def _is_safety_ask(decision: PermissionDecision) -> bool:
+        """Whether a decision is a bypass-immune safety ASK.
+
+        A safety ASK is an ASK that a tool has explicitly marked with
+        :attr:`PermissionDecision.bypass_immune` ``= True``. Tools emit
+        these for dangerous operations (e.g. write to ``~/.bashrc``,
+        ``rm -rf /``, command-injection patterns) that must be surfaced
+        to the user regardless of allow rules in
+        ``DEFAULT``/``ACCEPT_EDITS``. ``BYPASS`` mode intentionally
+        skips this check (see :meth:`_check_bypass`); ``DONT_ASK``
+        converts the ASK to DENY (see :meth:`_check_dont_ask`).
+
+        Args:
+            decision (`PermissionDecision`):
+                The decision returned by a tool's ``check_permissions``.
+
+        Returns:
+            `bool`:
+                True iff ``behavior == ASK`` and ``bypass_immune`` is set.
+        """
+        return (
+            decision.behavior == PermissionBehavior.ASK
+            and decision.bypass_immune
+        )
+
+    async def _check_deny_rules(
+        self,
+        tool: ToolBase,
+        input_data: dict[str, Any],
+    ) -> PermissionDecision | None:
+        """Check if any deny rules match the request.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called
+            input_data (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `PermissionDecision | None`:
+                DENY decision if a rule matches, None otherwise
+        """
+        rules = self.context.deny_rules.get(tool.name, [])
+        for rule in rules:
+            if await self._rule_matches(tool, rule, input_data):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.DENY,
+                    message=f"Permission to use {tool.name} has been denied",
+                    decision_reason=f"Rule: {rule.rule_content}",
+                )
+        return None
+
+    async def _check_ask_rules(
+        self,
+        tool: ToolBase,
+        input_data: dict[str, Any],
+    ) -> PermissionDecision | None:
+        """Check if any ask rules match the request.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called (used for tool-specific checks)
+            input_data (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `PermissionDecision | None`:
+                ASK decision if a rule matches, None otherwise
+        """
+        rules = self.context.ask_rules.get(tool.name, [])
+        for rule in rules:
+            if await self._rule_matches(tool, rule, input_data):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.ASK,
+                    message=f"Permission required for {tool.name}",
+                    decision_reason=f"Rule: {rule.rule_content}",
+                )
+        return None
+
+    async def _check_allow_rules(
+        self,
+        tool: ToolBase,
+        input_data: dict[str, Any],
+    ) -> PermissionDecision | None:
+        """Check if any allow rules match the request.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called (used for tool-specific checks)
+            input_data (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `PermissionDecision | None`:
+                ALLOW decision if a rule matches, None otherwise
+        """
+        rules = self.context.allow_rules.get(tool.name, [])
+        for rule in rules:
+            if await self._rule_matches(tool, rule, input_data):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.ALLOW,
+                    message=f"Permission granted for {tool.name}",
+                    updated_input=input_data,
+                )
+        return None
+
+    async def _rule_matches(
+        self,
+        tool: ToolBase,
+        rule: PermissionRule,
+        input_data: dict[str, Any],
+    ) -> bool:
+        """Check if a rule matches the input data.
+
+        The matching strategy depends on the tool type:
+        - Bash: Substring matching against the command
+        - Write/Read: Glob pattern matching against file paths
+        - Other: Generic pattern matching
+
+        Args:
+            rule (`PermissionRule`):
+                The permission rule to check
+            input_data (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `bool`:
+                True if the rule matches, False otherwise
+        """
+        # Empty rule_content matches everything
+        if not rule.rule_content:
+            return True
+
+        # Try to use tool's match_rule method if available.
+        # ``_execute_async_or_sync_func`` keeps backward compatibility
+        # with third-party tools that still override match_rule with a
+        # sync ``def`` (the framework's signature is now ``async def``).
+        return await _execute_async_or_sync_func(
+            tool.match_rule,
+            rule.rule_content,
+            input_data,
+        )
+
+    async def _generate_suggestions(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules from a tool call.
+
+        This method analyzes the tool call and generates broader permission
+        suggestions that the user can apply to avoid future confirmations.
+
+        Strategy:
+        - For Bash: Extract command prefix (e.g., "npm run" -> "npm run:*")
+        - For File operations: Extract directory (e.g.,
+         "src/file.py" -> "src/**")
+        - For other tools: Generate exact match rule
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called (used for tool-specific
+                suggestions)
+            tool_input (`dict[str, Any]`):
+                The tool input data (used for generating suggestions)
+
+        Returns:
+            `List[PermissionRule]`:
+                List of suggested permission rules (usually 1, max 5 for
+                compound commands)
+        """
+
+        # Try to use tool's generate_suggestions method if available.
+        # ``_execute_async_or_sync_func`` keeps backward compatibility
+        # with third-party tools that still override this method with
+        # a sync ``def`` (the framework's signature is now ``async def``).
+        return await _execute_async_or_sync_func(
+            tool.generate_suggestions,
+            tool_input,
+        )

src/agentscope/permission/_rule.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""Permission rule model for tool usage."""
+from pydantic import BaseModel
+
+from ._types import PermissionBehavior
+
+
+class PermissionRule(BaseModel):
+    """Permission rule for tool usage.
+
+    A permission rule defines whether a specific tool or tool operation
+    should be allowed, denied, or require user confirmation. The
+    rule_content field has different semantics depending on the tool_name:
+
+    - For "Bash": rule_content is a substring pattern matched against the
+      command Example: rule_content="npm install" matches "npm install express"
+
+    - For "Write"/"Read": rule_content is a glob pattern matched against file
+      paths Example: rule_content="src/**" matches "src/main.py"
+
+    - For other tools: rule_content is a tool-specific filter pattern
+    """
+
+    tool_name: str
+    """The name of the tool this rule applies to (e.g., "Bash",
+    "Write", "Read")."""
+
+    rule_content: str | None
+    """Optional filter pattern - semantics depend on tool_name."""
+
+    behavior: PermissionBehavior
+    """The permission behavior ("allow", "deny", or "ask")."""
+
+    source: str
+    """Where this rule originated from (e.g., "userSettings",
+    "projectSettings")."""

src/agentscope/permission/_types.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=line-too-long
+"""Permission system types and engine for tool usage control.
+
+This module implements a permission system that controls tool execution based
+on configurable rules. The permission system supports different matching
+strategies depending on the tool type:
+
+- For Bash tools: rule_content is a substring pattern matched against commands
+- For Write/Read tools: rule_content is a glob pattern matched against file
+ paths
+- For other tools: rule_content uses generic matching logic
+"""
+
+from enum import Enum
+
+
+class PermissionMode(Enum):
+    """The mode of permission.
+
+    Permission modes control how the system handles tool execution requests.
+    Different modes are suitable for different scenarios:
+
+    +---------------+--------------------------------------------------+--------------------------------+
+    | Mode          | Behavior                                         | Use Case                       |
+    +===============+==================================================+================================+
+    | DEFAULT       | Every operation asks for permission unless:      | Default mode, most secure      |
+    |               | - an allow rule matches, OR                      |                                |
+    |               | - the tool's ``check_permissions`` explicitly    |                                |
+    |               |   returns ALLOW for the invocation (currently   |                                |
+    |               |   only ``Bash`` auto-allows recognized          |                                |
+    |               |   read-only commands such as ``ls``/``git       |                                |
+    |               |   status``). Read/Glob/Grep return PASSTHROUGH  |                                |
+    |               |   and fall through to the default ASK unless    |                                |
+    |               |   an allow rule matches.                        |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+    | ACCEPT_EDITS  | - Auto-allow file writes in working directories | User present, rapid iteration  |
+    |               | - Auto-allow file reads in working directories  | development                    |
+    |               | - Auto-allow filesystem commands (mkdir, rm,     |                                |
+    |               |   mv, cp, ...) **only when all target paths**   |                                |
+    |               |   **resolve inside a working directory**         |                                |
+    |               | - Other operations follow normal rules           |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+    | EXPLORE       | Read-only mode:                                  | Exploring codebase, planning   |
+    |               | - Allow: read-only tools (``Read``/``Grep``/    | implementation                 |
+    |               |   ``Glob``) and read-only bash commands         |                                |
+    |               |   (e.g. ``ls``, ``git status``)                  |                                |
+    |               | - Deny: any modification tool / command         |                                |
+    |               | - User-configured DENY or ASK rules take         |                                |
+    |               |   precedence over the read-only auto-allow      |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+    | BYPASS        | Skip all permission checks except explicit       | Sandboxed environments         |
+    |               | user-configured deny / ask rules and tool       | (container, VM), unattended    |
+    |               | DENY. **Safety ASKs from tools are NOT**         | runs where you fully trust     |
+    |               | **enforced** — including ``rm -rf /``, writes   | the agent                      |
+    |               | to ``~/.bashrc``, command-injection patterns,    |                                |
+    |               | etc. Use deny rules to protect specific paths.   |                                |
+    |               | For unattended runs that still need safety,      |                                |
+    |               | prefer DONT_ASK.                                 |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+    | DONT_ASK      | Convert every ASK (including safety ASKs and     | Scheduled tasks, background    |
+    |               | ASK-rule hits) to DENY. Safe-by-default for     | execution when user is away    |
+    |               | unattended execution.                            |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+
+    Attributes:
+        DEFAULT: Default mode - explicit permission per action. The
+            only auto-allow path is the tool's own ``check_permissions``
+            returning ALLOW (currently just ``Bash`` for recognized
+            read-only commands like ``ls``/``git status``).
+        ACCEPT_EDITS: Accept edits mode - automatically allows file
+            edits within working directories (including filesystem
+            bash commands whose every target is in a working dir).
+        EXPLORE: Explore mode - read-only; modifications are denied.
+        BYPASS: Bypass mode - skips safety checks; relies on user
+            deny / ask rules as the only guardrail.
+        DONT_ASK: Don't ask mode - converts all ASK decisions to DENY
+            (for unattended execution).
+    """  # noqa: E501
+
+    DEFAULT = "default"
+    ACCEPT_EDITS = "accept_edits"
+    EXPLORE = "explore"
+    BYPASS = "bypass"
+    DONT_ASK = "dont_ask"
+
+
+class PermissionBehavior(Enum):
+    """The behavior of permission.
+
+    Attributes:
+        ALLOW: Allow the operation
+        DENY: Deny the operation
+        ASK: Ask the user for permission
+        PASSTHROUGH: Let the permission engine continue with rule matching
+            (used by tools to defer decision to the engine)
+    """
+
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+    PASSTHROUGH = "passthrough"

src/agentscope/rag/__init__.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""The retrieval-augmented generation (RAG) module in AgentScope."""
+
+from ._chunker import ApproxTokenChunker, ChunkerBase
+from ._document import (
+    Section,
+    Chunk,
+)
+from ._parser import ImageParser, ParserBase, PDFParser, PPTParser, TextParser
+from ._vdb import (
+    DocumentSummary,
+    VectorStoreBase,
+    VectorRecord,
+    VectorSearchResult,
+    QdrantStore,
+)
+from ._knowledge import KnowledgeBase
+
+__all__ = [
+    "ApproxTokenChunker",
+    "ChunkerBase",
+    "Chunk",
+    "DocumentSummary",
+    "ImageParser",
+    "ParserBase",
+    "PDFParser",
+    "PPTParser",
+    "TextParser",
+    "Section",
+    "VectorStoreBase",
+    "VectorRecord",
+    "VectorSearchResult",
+    "QdrantStore",
+    "KnowledgeBase",
+]

src/agentscope/rag/_chunker/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""Chunker implementations for the RAG indexing pipeline."""
+
+from ._approx_token_chunker import ApproxTokenChunker
+from ._base import ChunkerBase
+
+__all__ = [
+    "ApproxTokenChunker",
+    "ChunkerBase",
+]

src/agentscope/rag/_chunker/_approx_token_chunker.py

@@ -0,0 +1,172 @@
+# -*- coding: utf-8 -*-
+"""A chunker that splits text by an approximate token count.
+
+The token count is approximated as ``len(text.encode("utf-8")) // 4``,
+which avoids a hard dependency on any tokenizer library while staying
+within the right order of magnitude for most LLM tokenizers.
+"""
+from bisect import bisect_right
+from itertools import accumulate
+
+from ._base import ChunkerBase
+from .._document import Chunk, Section
+from ...message import TextBlock, DataBlock
+
+
+class ApproxTokenChunker(ChunkerBase):
+    """A chunker based on an approximate token counting strategy.
+
+    Text sections are sliced into pieces of at most ``chunk_size``
+    approximate tokens, with ``overlap`` approximate tokens shared
+    between two consecutive pieces.  The token count of a string is
+    approximated as ``len(text.encode("utf-8")) // 4``, so no
+    tokenizer dependency is required.
+
+    Sections carrying a :class:`~agentscope.message.DataBlock`
+    (images, video, etc.) are passed through unchanged as a single
+    chunk.
+
+    .. note:: Chunks never span across two input Sections, as
+        required by :class:`ChunkerBase`.
+    """
+
+    def __init__(self, chunk_size: int = 512, overlap: int = 50) -> None:
+        """Initialize the approx token chunker.
+
+        Args:
+            chunk_size (`int`, defaults to `512`):
+                The maximum number of approximate tokens per chunk.
+                Must be a positive integer.
+            overlap (`int`, defaults to `50`):
+                The number of approximate tokens shared between two
+                consecutive chunks.  Must be non-negative and smaller
+                than ``chunk_size``.
+
+        Raises:
+            `ValueError`:
+                If ``chunk_size`` is not positive, or ``overlap`` is
+                negative or not smaller than ``chunk_size``.
+        """
+        if chunk_size <= 0:
+            raise ValueError(
+                f"chunk_size must be positive, got {chunk_size}.",
+            )
+        if overlap < 0 or overlap >= chunk_size:
+            raise ValueError(
+                "overlap must satisfy 0 <= overlap < chunk_size, "
+                f"got overlap={overlap}, chunk_size={chunk_size}.",
+            )
+
+        self.chunk_size = chunk_size
+        self.overlap = overlap
+
+    async def chunk(self, sections: list[Section]) -> list[Chunk]:
+        """Chunk the input sections into smaller chunks based on an approx
+        token counting strategy.
+
+        Args:
+            sections (`list[Section]`):
+                A list of sections to chunk.
+
+        Returns:
+            `list[Chunk]`:
+                A list of chunks, with ``chunk_index`` numbered
+                ``0..N-1`` and ``total_chunks`` set to ``N`` on every
+                chunk.
+        """
+        chunks: list[Chunk] = []
+        for section in sections:
+            contents: list[TextBlock | DataBlock]
+            if isinstance(section.content, TextBlock):
+                contents = [
+                    TextBlock(text=piece)
+                    for piece in self._split_text(section.content.text)
+                ]
+            else:
+                # DataBlock pass-through: never slice multimodal data
+                contents = [section.content]
+
+            chunks.extend(
+                Chunk(
+                    content=content,
+                    source=section.source,
+                    chunk_index=0,  # renumbered below
+                    total_chunks=0,  # renumbered below
+                    metadata=dict(section.metadata),
+                )
+                for content in contents
+            )
+
+        for index, chunk in enumerate(chunks):
+            chunk.chunk_index = index
+            chunk.total_chunks = len(chunks)
+
+        return chunks
+
+    def _split_text(self, text: str) -> list[str]:
+        """Split text into pieces of at most ``chunk_size`` approx tokens.
+
+        Consecutive pieces share approximately ``overlap`` tokens.
+
+        Args:
+            text (`str`):
+                The text to split.
+
+        Returns:
+            `list[str]`:
+                The text pieces, in document order.
+        """
+        if self._approx_count_tokens(text) <= self.chunk_size:
+            return [text]
+
+        # Cumulative UTF-8 byte length after each character, so that
+        # the byte length of text[i:j] == byte_offsets[j] - byte_offsets[i]
+        byte_offsets = [0, *accumulate(len(c.encode("utf-8")) for c in text)]
+
+        chunk_bytes = self.chunk_size * 4
+        overlap_bytes = self.overlap * 4
+
+        pieces: list[str] = []
+        start = 0
+        while start < len(text):
+            # The largest end such that the slice fits the byte budget
+            end = (
+                bisect_right(
+                    byte_offsets,
+                    byte_offsets[start] + chunk_bytes,
+                )
+                - 1
+            )
+            # Always make progress, even for characters whose UTF-8
+            # encoding exceeds the budget on their own
+            end = max(end, start + 1)
+            pieces.append(text[start:end])
+
+            if end >= len(text):
+                break
+
+            # Step back by the overlap budget, ensuring forward progress
+            next_start = (
+                bisect_right(
+                    byte_offsets,
+                    byte_offsets[end] - overlap_bytes,
+                )
+                - 1
+            )
+            start = max(next_start, start + 1)
+
+        return pieces
+
+    @staticmethod
+    def _approx_count_tokens(text: str) -> int:
+        """The approx count of tokens.
+
+        Args:
+            text (`str`):
+                The text to be counted.
+
+        Returns:
+            `int`:
+                The approx count of tokens.
+        """
+        return len(text.encode("utf-8")) // 4

src/agentscope/rag/_chunker/_base.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""Abstract base class for chunkers.
+
+A :class:`ChunkerBase` subclass takes the :class:`Section` list
+produced by a :class:`~agentscope.rag.ParserBase` and splits the
+content into final :class:`Chunk` objects suitable for embedding and
+storage in a vector database.
+
+Chunkers are **format-agnostic** — they operate on the unified
+``TextBlock | DataBlock`` content carried in each Section.  Long
+:class:`TextBlock` content is sliced according to a chunking strategy
+(by character count, by tokens, by semantic boundaries, etc.); short
+text and :class:`DataBlock` content are passed through unchanged.
+
+Chunkers **never combine content across Section boundaries**.  This
+guarantee preserves the structural metadata attached by the Parser
+(page numbers, slide indices, embedded-image isolation, etc.).
+"""
+from abc import ABC, abstractmethod
+
+from .._document import Chunk, Section
+
+
+class ChunkerBase(ABC):
+    """Abstract base class for chunkers.
+
+    Subclasses implement a specific chunking strategy (by character
+    count, by token count, by semantic boundary, etc.).  The
+    chunker is configured once at construction time and reused
+    across many ``chunk()`` calls within the same knowledge base.
+
+    Subclasses must guarantee:
+
+    - **No cross-Section merging**: every output :class:`Chunk` is
+      derived from exactly one input :class:`Section`.
+    - **DataBlock pass-through**: a Section whose content is a
+      :class:`~agentscope.message.DataBlock` becomes a single Chunk
+      with the same content; multimodal data is never sliced.
+    - **Continuous indexing**: ``chunk_index`` runs from ``0`` to
+      ``total_chunks - 1`` across the entire output list, even
+      when the input contains many Sections.
+    - **Consistent total_chunks**: every output Chunk carries the
+      same ``total_chunks`` value (the length of the output list).
+    - **Metadata inheritance**: each output Chunk's ``source`` and
+      ``metadata`` are copied from its parent Section.
+    """
+
+    @abstractmethod
+    async def chunk(self, sections: list[Section]) -> list[Chunk]:
+        """Split a list of Sections into Chunks.
+
+        Args:
+            sections (`list[Section]`):
+                The Sections produced by a :class:`ParserBase`, in
+                document order.
+
+        Returns:
+            `list[Chunk]`:
+                The final chunks, in document order, with
+                ``chunk_index`` numbered ``0..N-1`` and
+                ``total_chunks`` set to ``N`` on every chunk.
+        """

src/agentscope/rag/_document.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+"""Data structures used in the RAG indexing pipeline.
+
+The indexing pipeline has two stages, each producing its own
+structured output:
+
+1. :class:`Section` — produced by a :class:`ParserBase` from a raw
+   file.  Each ``Section`` represents one "natural boundary" of the
+   source (a PDF page, a PPTX slide, an embedded image, a Markdown
+   heading section, etc.).  A ``Chunker`` never combines content
+   across two ``Section`` instances, so ``Section`` is also a hard
+   boundary that prevents leakage of format-specific structure into
+   downstream chunks.
+
+2. :class:`Chunk` — produced by a :class:`ChunkerBase` from one or
+   more ``Section`` instances.  Each ``Chunk`` is the final unit
+   that gets embedded and inserted into the vector store.
+
+Neither structure is persisted on its own — they are transient
+in-memory carriers between pipeline stages.  Persistence happens at
+the :class:`~agentscope.rag.VectorRecord` and
+``KnowledgeDocumentRecord`` layers.
+"""
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ..message import TextBlock, DataBlock
+
+
+class Section(BaseModel):
+    """A single natural section produced by a :class:`ParserBase`.
+
+    A ``Section`` represents one logical region of the source file.
+    The :class:`ChunkerBase` guarantees that no resulting
+    :class:`Chunk` ever spans content from two different sections.
+
+    The granularity of a ``Section`` is format-specific:
+
+    - **PDF**: one section per page (plus separate sections for
+      embedded images).
+    - **PPTX**: one section per slide.
+    - **Markdown**: one section per top-level heading, or the entire
+      file if unstructured.
+    - **TXT / image / video**: one section for the whole file.
+    """
+
+    content: TextBlock | DataBlock
+    """The section content.  Text sections use :class:`TextBlock`;
+    multimodal sections (images, video, etc.) use :class:`DataBlock`."""
+
+    source: str
+    """The source filename (e.g. ``"report.pdf"``).  Carried through
+    to every downstream :class:`Chunk` and into the vector store
+    metadata for citation / display."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Format-specific metadata written by the parser.  Examples:
+
+    - PDFParser: ``{"page": 3}``
+    - PPTXParser: ``{"slide": 2}``
+    - ExcelParser: ``{"sheet": "Q3 Sales"}``
+
+    These keys are not part of any retrieval / pipeline contract —
+    they are passed through verbatim to the vector store metadata for
+    later citation.  Each Chunk inherits this dict from its parent
+    Section.
+    """
+
+
+class Chunk(BaseModel):
+    """A final indexable chunk produced by a :class:`ChunkerBase`.
+
+    Each ``Chunk`` corresponds to one record in the vector store.
+    The required structural fields (``source``, ``chunk_index``,
+    ``total_chunks``) enable downstream features such as "expand
+    context around a hit" during retrieval.
+    """
+
+    content: TextBlock | DataBlock
+    """The chunk content (sliced from a text :class:`Section`, or a
+    multimodal :class:`DataBlock` passed through unchanged)."""
+
+    source: str
+    """The source filename — inherited from the parent
+    :class:`Section`.  Used for display / citation."""
+
+    chunk_index: int
+    """The 0-based index of this chunk **within the document**.
+    Sequential across all sections of the same source file.  Used to
+    locate neighbouring chunks for "context expansion" at query time.
+    """
+
+    total_chunks: int
+    """The total number of chunks produced from the same source file.
+    Together with :attr:`chunk_index` lets callers know whether a hit
+    is near the start / end of the document, and bounds the
+    expansion range."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Format-specific metadata inherited from the parent
+    :class:`Section`.  See :attr:`Section.metadata`."""

src/agentscope/rag/_knowledge.py

@@ -0,0 +1,384 @@
+# -*- coding: utf-8 -*-
+"""Runtime handle for a single knowledge base.
+
+A :class:`KnowledgeBase` instance is the **single algorithmic source of
+truth** for talking to one knowledge base: it pairs an embedding model
+with a vector-store collection (optionally scoped by a payload
+``metadata_filter``) and exposes the four operations a caller ever
+needs — :meth:`search`, :meth:`insert_document`,
+:meth:`delete_document`, :meth:`list_documents`.
+
+The handle is *narrow on purpose* — it carries the resolved runtime
+state (embedding model + vector store + scope) and delegates every
+operation to the bound :class:`VectorStoreBase`.  Document parsing,
+chunking, credential resolution, dimension policy validation, and
+persistence of knowledge-base records all belong one layer up
+(service-side :class:`KnowledgeBaseManagerBase` for hosted
+deployments; the caller directly otherwise).
+
+The backing collection is created on first use — each operation
+transparently calls :meth:`ensure_collection`, which is itself
+idempotent and memoised after the first success, so the only cost is
+one extra round-trip on the very first call against a fresh
+deployment.
+
+``metadata_filter`` is the defense-in-depth scoping mechanism for
+co-locating multiple logical knowledge bases inside the same physical
+collection — typically multi-tenant deployments where every record
+carries a ``{"tenant_id": "..."}`` payload.  It is set once at
+construction time and **always** applied: search/list never escape
+it, and insert forces it onto every chunk's metadata so a malicious or
+buggy parser cannot rebind a record into another scope.
+"""
+
+import asyncio
+
+from ._document import Chunk
+from ._vdb import VectorRecord, VectorSearchResult, VectorStoreBase
+from .._utils._common import _generate_id
+from ..embedding import EmbeddingModelBase
+from ..message import DataBlock, TextBlock
+from ._vdb import DocumentSummary
+
+
+class KnowledgeBase:
+    """Runtime handle for one knowledge base.
+
+    Binds an embedding model and a vector-store collection together so
+    callers can retrieve / insert / delete / list documents without
+    repeating the wiring.  Cheap to construct (no I/O); the collection
+    itself is created lazily on the first operation, so a fresh
+    deployment "just works" without an explicit setup step.
+
+    .. code-block:: python
+
+        kb = KnowledgeBase(
+            name="company-handbook",
+            description="Internal HR and onboarding documents.",
+            embedding_model=embedding_model,
+            vector_store=vector_store,
+            collection="handbook",
+        )
+        await kb.insert_document(chunks)
+        results = await kb.search(["What is the PTO policy?"])
+    """
+
+    name: str
+    """Agent-oriented knowledge base name — used by tool descriptions
+    and frontend rendering."""
+
+    description: str
+    """Agent-oriented knowledge base description — what this knowledge
+    base contains and when to retrieve from it."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        embedding_model: EmbeddingModelBase,
+        vector_store: VectorStoreBase,
+        collection: str,
+        metadata_filter: dict | None = None,
+    ) -> None:
+        """Initialize the runtime handle.
+
+        Args:
+            name (`str`):
+                Agent-oriented knowledge base name.  Surfaced to the
+                LLM (via tool descriptions) and to the front-end.
+            description (`str`):
+                Agent-oriented description.  Should answer "what is in
+                this knowledge base and when should I search it?" — the
+                LLM uses it to decide whether to call the search tool
+                in agentic mode.
+            embedding_model (`EmbeddingModelBase`):
+                The embedding model used to embed both queries and
+                inserted chunks.  Must be the same model used at
+                indexing time and at retrieval time, otherwise vectors
+                will not be comparable.
+            vector_store (`VectorStoreBase`):
+                The shared vector-store connection.  The store must
+                already be entered (its own ``__aenter__`` already
+                called) before any operation on this handle runs.
+            collection (`str`):
+                The physical collection backing this knowledge base.
+                Created lazily on the first operation; see
+                :meth:`ensure_collection`.
+            metadata_filter (`dict | None`, optional):
+                Defense-in-depth payload filter.  When set:
+
+                - :meth:`search` and :meth:`list_documents` restrict
+                  results to records whose payload matches every
+                  ``key == value`` pair;
+                - :meth:`insert_document` forces these keys onto every
+                  inserted chunk's metadata, overriding caller-supplied
+                  values, so records cannot leak into another scope.
+
+                ``None`` disables filtering — the default for
+                deployments where every knowledge base owns its
+                collection outright.
+        """
+        self.name = name
+        self.description = description
+        self._embedding_model = embedding_model
+        self._vector_store = vector_store
+        self._collection = collection
+        self._metadata_filter = metadata_filter
+        # Memoise the "collection exists" check after the first
+        # successful ensure_collection so subsequent operations avoid
+        # the extra round-trip.
+        self._collection_ready = False
+
+    # ------------------------------------------------------------------
+    # Read-only accessors
+    # ------------------------------------------------------------------
+
+    @property
+    def embedding_model(self) -> EmbeddingModelBase:
+        """The bound embedding model."""
+        return self._embedding_model
+
+    @property
+    def vector_store(self) -> VectorStoreBase:
+        """The bound vector store."""
+        return self._vector_store
+
+    @property
+    def collection(self) -> str:
+        """The physical collection backing this knowledge base."""
+        return self._collection
+
+    @property
+    def metadata_filter(self) -> dict | None:
+        """The defense-in-depth payload filter, or ``None``."""
+        return self._metadata_filter
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def ensure_collection(self) -> None:
+        """Idempotently create the backing collection if missing.
+
+        Called transparently at the top of every public operation —
+        callers should not need to invoke it themselves.  Memoised on
+        the instance after the first success, so subsequent calls are
+        a single ``if`` check.
+
+        Looks up the collection via
+        :meth:`VectorStoreBase.has_collection` and creates it with the
+        embedding model's :attr:`~EmbeddingModelBase.dimensions` when
+        absent.
+
+        Raises whatever the backend raises if the collection exists at
+        an incompatible dimension (the backend is the authority on
+        that; we do not double-check here).
+        """
+        if self._collection_ready:
+            return
+        if not await self._vector_store.has_collection(self._collection):
+            await self._vector_store.create_collection(
+                self._collection,
+                dimensions=self._embedding_model.dimensions,
+            )
+        self._collection_ready = True
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        queries: list[str | TextBlock | DataBlock],
+        top_k: int = 5,
+        score_threshold: float | None = None,
+    ) -> list[VectorSearchResult]:
+        """Search the knowledge base with one or more queries.
+
+        All queries are embedded in a single batch, then searched
+        concurrently against the bound collection (with
+        :attr:`metadata_filter` applied).  Hits are deduplicated by
+        ``(document_id, chunk_index)`` keeping the best score,
+        optionally filtered by ``score_threshold``, sorted by
+        descending score, and truncated to ``top_k``.
+
+        Args:
+            queries (`list[str | TextBlock | DataBlock]`):
+                Query inputs.  Text may be either bare ``str`` or
+                :class:`TextBlock`; :class:`DataBlock` items are
+                **silently dropped** when the bound embedding model
+                does not declare ``supports_multimodal`` — text-only
+                models would otherwise reject them.  Callers can
+                therefore pass a mixed list without per-KB filtering.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results returned across all queries
+                (after dedup).
+            score_threshold (`float | None`, optional):
+                Minimum similarity score for a hit to be retained.
+                Only meaningful for similarity metrics where higher is
+                better (cosine / dot-product).  ``None`` disables
+                filtering.
+
+        Returns:
+            `list[VectorSearchResult]`:
+                At most ``top_k`` deduplicated hits ordered by
+                descending similarity score.  Empty when there are no
+                queries the bound embedding model can consume.
+        """
+        if not queries:
+            return []
+
+        if not self._embedding_model.supports_multimodal:
+            queries = [q for q in queries if not isinstance(q, DataBlock)]
+            if not queries:
+                return []
+
+        await self.ensure_collection()
+        response = await self._embedding_model(queries)
+
+        results_per_query = await asyncio.gather(
+            *(
+                self._vector_store.search(
+                    collection=self._collection,
+                    query_vector=vector,
+                    top_k=top_k,
+                    metadata_filter=self._metadata_filter,
+                )
+                for vector in response.embeddings
+            ),
+        )
+
+        best: dict[tuple[str, int], VectorSearchResult] = {}
+        for results in results_per_query:
+            for result in results:
+                if (
+                    score_threshold is not None
+                    and result.score < score_threshold
+                ):
+                    continue
+                # ``(document_id, chunk_index)`` is the stable identity
+                # of a chunk: it survives reindex (block UUIDs do not)
+                # and uniquely names "this slice of that document"
+                # regardless of which query surfaced it.
+                key = (result.document_id, result.chunk.chunk_index)
+                if key not in best or result.score > best[key].score:
+                    best[key] = result
+
+        merged = sorted(
+            best.values(),
+            key=lambda result: result.score,
+            reverse=True,
+        )
+        return merged[:top_k]
+
+    # ------------------------------------------------------------------
+    # Document management
+    # ------------------------------------------------------------------
+
+    async def insert_document(
+        self,
+        chunks: list[Chunk],
+        document_id: str | None = None,
+        document_metadata: dict | None = None,
+    ) -> str:
+        """Embed and insert a list of chunks as a single source document.
+
+        All chunks share the resolved ``document_id``;
+        :meth:`delete_document` later removes them as a unit.  Each
+        chunk's metadata is merged in this precedence (highest wins):
+
+        1. :attr:`metadata_filter` keys — defense-in-depth scoping, so
+           a chunk can never be inserted with a payload that escapes
+           the filter (any escape would silently disappear at retrieve
+           time anyway, but failing closed at insert is clearer).
+        2. The chunk's pre-existing ``metadata`` — parser-supplied.
+        3. ``document_metadata`` — document-level fields propagated
+           down (filename, media type, upload time, ...).
+
+        Args:
+            chunks (`list[Chunk]`):
+                The pre-chunked document content (already produced by
+                a parser + chunker pipeline).  An empty list is a
+                no-op.
+            document_id (`str | None`, optional):
+                The document identifier.  When ``None`` a fresh UUID
+                hex is generated and returned so the caller can record
+                it for future :meth:`delete_document` calls.
+            document_metadata (`dict | None`, optional):
+                Document-level metadata (filename, media type, size,
+                upload time, ...).  Merged into each chunk's
+                ``metadata``.
+
+        Returns:
+            `str`:
+                The (possibly generated) document id.
+
+        Raises:
+            `RuntimeError`:
+                If the embedding model returns a number of vectors
+                that does not match the number of chunks.
+        """
+        if not chunks:
+            return document_id or _generate_id()
+        document_id = document_id or _generate_id()
+
+        await self.ensure_collection()
+
+        # Precedence: metadata_filter wins (security boundary), then
+        # chunk metadata, then document_metadata.  See docstring.
+        for chunk in chunks:
+            chunk.metadata = {
+                **(document_metadata or {}),
+                **chunk.metadata,
+                **(self._metadata_filter or {}),
+            }
+
+        response = await self._embedding_model(
+            [chunk.content for chunk in chunks],
+        )
+
+        if len(response.embeddings) != len(chunks):
+            raise RuntimeError(
+                f"Embedding model returned {len(response.embeddings)} "
+                f"vectors for {len(chunks)} chunks.",
+            )
+
+        records = [
+            VectorRecord(
+                vector=vector,
+                document_id=document_id,
+                chunk=chunk,
+            )
+            for vector, chunk in zip(response.embeddings, chunks)
+        ]
+        await self._vector_store.insert(self._collection, records)
+        return document_id
+
+    async def delete_document(self, document_id: str) -> None:
+        """Remove every record for one source document.
+
+        Args:
+            document_id (`str`):
+                The source document id whose records should be removed.
+        """
+        await self.ensure_collection()
+        await self._vector_store.delete(
+            self._collection,
+            document_id,
+        )
+
+    async def list_documents(self) -> list["DocumentSummary"]:
+        """List all distinct source documents in this knowledge base.
+
+        Filtered by :attr:`metadata_filter` when set, so callers only
+        ever see documents within their own scope.
+
+        Returns:
+            `list[DocumentSummary]`:
+                One summary per indexed document, in unspecified order.
+        """
+        await self.ensure_collection()
+        return await self._vector_store.list_documents(
+            self._collection,
+            metadata_filter=self._metadata_filter,
+        )

src/agentscope/rag/_parser/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""File parser implementations for the RAG indexing pipeline."""
+
+from ._base import ParserBase
+from ._image import ImageParser
+from ._pdf import PDFParser
+from ._ppt import PPTParser
+from ._text import TextParser
+
+__all__ = [
+    "ParserBase",
+    "PDFParser",
+    "PPTParser",
+    "ImageParser",
+    "TextParser",
+]

src/agentscope/rag/_parser/_base.py

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""Abstract base class for file parsers.
+
+A :class:`ParserBase` subclass handles **one file format**.  Its job
+is to read a file's raw bytes and produce a list of
+:class:`~agentscope.rag.Section` objects, each representing a natural
+boundary of the source (e.g. one PDF page, one PPTX slide, one
+embedded image).
+
+Parsers **do not chunk text**.  Long text is left intact inside the
+Section; splitting happens later in a
+:class:`~agentscope.rag.ChunkerBase`.  Parsers also do not need to
+worry about output size — only about preserving the structural
+boundaries that downstream consumers must not cross.
+"""
+import mimetypes
+from abc import ABC, abstractmethod
+
+from .._document import Section
+
+
+class ParserBase(ABC):
+    """Abstract base class for file-format parsers.
+
+    Each subclass handles a single file format (or a related family,
+    e.g. all plain-text MIME types).  Subclasses are typically
+    instantiated once and reused across many ``parse()`` calls.
+
+    Subclasses should be stateless or thread-safe — a single
+    instance may be invoked concurrently from multiple agent runs.
+
+    Subclasses must declare :attr:`supported_media_types` so that the
+    KnowledgeBaseManager can route uploaded files to the right parser
+    based on standard IANA media types (RFC 6838).
+    """
+
+    supported_media_types: list[str]
+    """Standard IANA media types (RFC 6838) this parser handles,
+    e.g. ``["application/pdf"]`` or
+    ``["text/plain", "text/markdown"]``.  Used by the
+    KnowledgeBaseManager to select a parser for an uploaded file."""
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Filename extensions (including the leading ``.``) this parser
+        can produce uploads for.
+
+        The base implementation derives extensions from
+        :attr:`supported_media_types` via
+        :func:`mimetypes.guess_all_extensions` — good enough for clean
+        IANA types like ``application/pdf``.  Subclasses **should
+        override** this when the default reverse-lookup is noisy
+        (``text/plain`` resolves to ``.bat`` / ``.c`` / ``.pl`` and a
+        dozen other developer extensions no KB user wants in the file
+        picker) or when a media type has no registered extension at all
+        (``application/x-yaml`` returns the empty list).
+
+        The result is consumed by the front-end's ``<input accept>`` and
+        by the client-side filename guard; it is **not** consulted for
+        media-type routing — that always goes through
+        :attr:`supported_media_types`.
+
+        Returns:
+            `list[str]`:
+                Deduplicated, sorted extensions (each starting with
+                ``.``).  May be empty when no media type resolves.
+        """
+        out: set[str] = set()
+        for media_type in cls.supported_media_types:
+            out.update(mimetypes.guess_all_extensions(media_type))
+        return sorted(out)
+
+    @abstractmethod
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Parse a file into a list of :class:`Section` objects.
+
+        The ``file`` argument is a union covering the three call sites
+        a parser sees in practice:
+
+        - ``bytes`` — the raw payload, as handed in by HTTP uploads
+          and blob-store reads.
+        - ``str`` for binary parsers (PDF, PPT, image, …) — a
+          **filesystem path** to the file to read.  The parser opens
+          the path itself; callers do not need to read the bytes first.
+        - ``str`` for :class:`TextParser` — disambiguated at runtime:
+          if the string names an existing file on disk it is treated
+          as a path and the file is decoded with the configured
+          encoding; otherwise it is treated as pre-decoded text.
+
+        Args:
+            file (`bytes | str`):
+                The file content or a path to it (see above).
+            filename (`str`):
+                The original filename (e.g. ``"report.pdf"``).  Used
+                for error messages and copied into each Section's
+                :attr:`Section.source` field for downstream display
+                / citation.
+
+        Returns:
+            `list[Section]`:
+                One Section per natural boundary in the source file.
+                For unstructured formats (plain text, image, video),
+                a single Section may cover the whole file.  Sections
+                are returned in document order.
+
+        Raises:
+            `TypeError`: If the subclass does not accept the supplied
+                ``file`` form.
+            `FileNotFoundError`: If a binary parser is handed a
+                ``str`` that does not name an existing file.
+            `ValueError`: If the file cannot be parsed.
+        """

src/agentscope/rag/_parser/_image.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""Image file parser.
+
+A single :class:`Section` carrying the raw image bytes as a
+base64-encoded :class:`DataBlock`.  No OCR, no captioning — the
+section is the image, ready to flow through to a multimodal
+embedding model unchanged.
+"""
+import base64
+
+from ...message import Base64Source, DataBlock
+from .._document import Section
+from ._base import ParserBase
+from ._utils import _guess_image_media_type
+
+
+class ImageParser(ParserBase):
+    """Parser for image files.
+
+    Wraps the entire file as a single :class:`Section` holding a
+    :class:`DataBlock` with the image's base64-encoded bytes.  This is
+    the input shape a multimodal embedding model expects; the
+    surrounding pipeline (chunker, vector store) treats the section
+    opaquely.
+
+    The IANA media type is sniffed from the bytes' magic number so
+    callers do not need to pass it explicitly.
+    """
+
+    supported_media_types: list[str] = [
+        "image/png",
+        "image/jpeg",
+        "image/gif",
+        "image/bmp",
+        "image/webp",
+    ]
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return the canonical image extensions."""
+        return [
+            ".bmp",
+            ".gif",
+            ".jpeg",
+            ".jpg",
+            ".png",
+            ".webp",
+        ]
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Wrap the image bytes in a single :class:`Section`.
+
+        Args:
+            file (`bytes | str`):
+                Either the raw image bytes, or a filesystem path to
+                the image file.
+            filename (`str`):
+                The source filename, copied into
+                :attr:`Section.source`.
+
+        Returns:
+            `list[Section]`:
+                A one-element list whose section's ``content`` is a
+                :class:`DataBlock` with the base64-encoded image data.
+
+        Raises:
+            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
+                a path that does not exist.
+        """
+        if isinstance(file, str):
+            with open(file, "rb") as fp:
+                file = fp.read()
+
+        media_type = _guess_image_media_type(file)
+        data = base64.b64encode(file).decode("utf-8")
+        return [
+            Section(
+                content=DataBlock(
+                    source=Base64Source(
+                        media_type=media_type,
+                        data=data,
+                    ),
+                    name=filename,
+                ),
+                source=filename,
+                metadata={"media_type": media_type},
+            ),
+        ]

src/agentscope/rag/_parser/_pdf.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""PDF file parser.
+
+One :class:`Section` per page so a downstream
+:class:`~agentscope.rag.ChunkerBase` never combines text across page
+boundaries.  Each section's :attr:`Section.metadata` carries the
+page number (starting at 1) for later citation.
+"""
+import io
+
+from ...message import TextBlock
+from .._document import Section
+from ._base import ParserBase
+
+
+class PDFParser(ParserBase):
+    """Parser for PDF files.
+
+    Returns one :class:`Section` per page.  Empty / image-only pages
+    still produce a Section (with empty text) so the page → section
+    correspondence stays exact — downstream chunkers naturally drop
+    empty content.
+
+    Requires :mod:`pypdf`; install with ``pip install pypdf`` (or via
+    the ``agentscope[rag]`` extra).
+    """
+
+    supported_media_types: list[str] = ["application/pdf"]
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return the canonical ``.pdf`` extension."""
+        return [".pdf"]
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Read the PDF bytes and return one Section per page.
+
+        Args:
+            file (`bytes | str`):
+                Either the raw PDF bytes, or a filesystem path to
+                the PDF file.
+            filename (`str`):
+                The source filename, copied verbatim into each
+                Section's :attr:`Section.source` field.
+
+        Returns:
+            `list[Section]`:
+                One Section per page, in document order.  Each
+                section's metadata holds ``{"page": <starting at 1>}``.
+
+        Raises:
+            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
+                a path that does not exist.
+            `ImportError`: If :mod:`pypdf` is not installed.
+            `ValueError`: If the bytes cannot be parsed as PDF.
+        """
+        if isinstance(file, str):
+            with open(file, "rb") as fp:
+                file = fp.read()
+
+        try:
+            from pypdf import PdfReader
+            from pypdf.errors import PdfReadError
+        except ImportError as e:
+            raise ImportError(
+                "Please install pypdf to use the PDF parser. "
+                "You can install it by `pip install pypdf` (or "
+                "`pip install agentscope[rag]`).",
+            ) from e
+
+        try:
+            reader = PdfReader(io.BytesIO(file))
+        except PdfReadError as e:
+            raise ValueError(
+                f"Failed to parse {filename!r} as PDF: {e}",
+            ) from e
+
+        sections: list[Section] = []
+        for page_idx, page in enumerate(reader.pages, start=1):
+            text = page.extract_text() or ""
+            sections.append(
+                Section(
+                    content=TextBlock(text=text),
+                    source=filename,
+                    metadata={"page": page_idx},
+                ),
+            )
+        return sections

src/agentscope/rag/_parser/_ppt.py

@@ -0,0 +1,341 @@
+# -*- coding: utf-8 -*-
+"""PowerPoint (.pptx) file parser.
+
+Walks the deck slide-by-slide and emits one :class:`Section` per
+contiguous content block — adjacent text runs (and, by default,
+tables) are merged into a single text section; embedded images are
+emitted as their own :class:`DataBlock` sections.  Each section's
+metadata carries the slide index (starting at 1) for later citation.
+
+Mirrors the knob set of the v1 ``PowerPointReader``:
+``include_image``, ``separate_table``, ``table_format``,
+``slide_prefix``, ``slide_suffix``.  Chunking is **not** done here —
+long text stays intact inside a section and is split downstream by a
+:class:`~agentscope.rag.ChunkerBase`.
+"""
+import base64
+import io
+from typing import Any, Literal
+
+from ..._logging import logger
+from ...message import Base64Source, DataBlock, TextBlock
+from .._document import Section
+from ._base import ParserBase
+from ._utils import (
+    _guess_image_media_type,
+    _table_to_json,
+    _table_to_markdown,
+)
+
+
+def _extract_table_rows(table: Any) -> list[list[str]]:
+    """Read a python-pptx table into a 2-D ``list[list[str]]``.
+
+    Args:
+        table (`Any`):
+            The python-pptx ``Table`` object.
+
+    Returns:
+        `list[list[str]]`:
+            One inner list per row; per-cell line breaks are
+            normalised to ``\\n``.
+    """
+    rows: list[list[str]] = []
+    for row in table.rows:
+        cells: list[str] = []
+        for cell in row.cells:
+            text = cell.text.strip()
+            text = text.replace("\r\n", "\n").replace("\r", "\n")
+            cells.append(text)
+        rows.append(cells)
+    return rows
+
+
+def _extract_image_bytes(shape: Any) -> bytes | None:
+    """Return the embedded image bytes for a picture shape, or ``None``.
+
+    Args:
+        shape (`Any`):
+            A python-pptx shape.  Non-picture shapes return ``None``.
+
+    Returns:
+        `bytes | None`:
+            The raw image bytes, or ``None`` when ``shape`` is not a
+            picture / the bytes are unreadable.
+    """
+    try:
+        from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+        picture_type = MSO_SHAPE_TYPE.PICTURE
+    except ImportError:
+        # MSO_SHAPE_TYPE.PICTURE numeric value used as the fallback
+        # so the parser still works against pptx builds where the
+        # enum import path has moved.
+        picture_type = 13
+
+    if shape.shape_type != picture_type:
+        return None
+    try:
+        return shape.image.blob
+    except Exception as e:  # pylint: disable=broad-except
+        logger.warning("Failed to extract image from PPT shape: %s", e)
+        return None
+
+
+class PPTParser(ParserBase):
+    """Parser for PowerPoint ``.pptx`` files.
+
+    Slide order is preserved.  Within a slide, shapes are visited in
+    document order and grouped into a minimum number of sections:
+
+    - **Text** shapes and **table** shapes contribute to one running
+      text section.  When ``separate_table=True`` a table closes the
+      running section and starts a new one of its own.
+    - **Picture** shapes emit a standalone :class:`Section` whose
+      ``content`` is a :class:`DataBlock` holding the base64-encoded
+      image bytes.
+
+    ``slide_prefix`` / ``slide_suffix`` are wrapped around each
+    slide's text content (the prefix is prepended to the slide's
+    first text section, the suffix is appended to its last text
+    section).  Use ``None`` on either to disable wrapping.
+    """
+
+    supported_media_types: list[str] = [
+        "application/vnd.openxmlformats-officedocument.presentationml"
+        ".presentation",
+    ]
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return ``[".pptx"]`` — the only format ``python-pptx``
+        reads."""
+        return [".pptx"]
+
+    def __init__(
+        self,
+        include_image: bool = True,
+        separate_table: bool = False,
+        table_format: Literal["markdown", "json"] = "markdown",
+        slide_prefix: str | None = "<slide index={index}>",
+        slide_suffix: str | None = "</slide>",
+    ) -> None:
+        """Initialize the PowerPoint parser.
+
+        Args:
+            include_image (`bool`, defaults to ``True``):
+                When ``True``, picture shapes are emitted as
+                :class:`DataBlock` sections.  Set to ``False`` to keep
+                a text-only index.
+            separate_table (`bool`, defaults to ``False``):
+                When ``True``, each table becomes its own text
+                section, never merged with surrounding text.
+            table_format (`Literal["markdown", "json"]`, defaults to
+                ``"markdown"``):
+                How to render tables.  ``"markdown"`` uses pipe-table
+                syntax; ``"json"`` emits a JSON array prefixed with a
+                ``<system-info>`` marker — choose JSON when cells
+                contain newlines that would corrupt Markdown layout.
+            slide_prefix (`str | None`, defaults to
+                ``"<slide index={index}>"``):
+                Prepended to the first text section of each slide.
+                Supports the ``{index}`` placeholder (starting at 1).  Use
+                ``None`` to disable.
+            slide_suffix (`str | None`, defaults to ``"</slide>"``):
+                Appended to the last text section of each slide.  Use
+                ``None`` to disable.
+
+        Raises:
+            `ValueError`: If ``table_format`` is not one of
+                ``"markdown"`` / ``"json"``.
+        """
+        if table_format not in ("markdown", "json"):
+            raise ValueError(
+                "The table_format must be one of 'markdown' or 'json', "
+                f"got {table_format!r}.",
+            )
+        self.include_image = include_image
+        self.separate_table = separate_table
+        self.table_format = table_format
+        self.slide_prefix = slide_prefix
+        self.slide_suffix = slide_suffix
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Parse a PPTX file into a list of :class:`Section` objects.
+
+        Args:
+            file (`bytes | str`):
+                Either the raw PPTX bytes, or a filesystem path to
+                the PPTX file.
+            filename (`str`):
+                The source filename, copied into each Section's
+                :attr:`Section.source`.
+
+        Returns:
+            `list[Section]`:
+                Sections in deck order.  Text sections carry
+                ``{"slide": <starting at 1>}``; image sections add
+                ``{"media_type": "image/..."}``.
+
+        Raises:
+            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
+                a path that does not exist.
+            `ImportError`: If :mod:`python-pptx` is not installed.
+            `ValueError`: If the bytes cannot be parsed.
+        """
+        if isinstance(file, str):
+            with open(file, "rb") as fp:
+                file = fp.read()
+
+        try:
+            from pptx import Presentation
+        except ImportError as e:
+            raise ImportError(
+                "Please install python-pptx to use the PowerPoint "
+                "parser. You can install it by "
+                "`pip install python-pptx` (or "
+                "`pip install agentscope[rag]`).",
+            ) from e
+
+        try:
+            prs = Presentation(io.BytesIO(file))
+        except Exception as e:  # pylint: disable=broad-except
+            raise ValueError(
+                f"Failed to parse {filename!r} as PPTX: {e}",
+            ) from e
+
+        sections: list[Section] = []
+        for slide_idx, slide in enumerate(prs.slides):
+            sections.extend(
+                self._parse_slide(slide, slide_idx, filename),
+            )
+        return sections
+
+    # ------------------------------------------------------------------
+    # Slide-level parsing
+    # ------------------------------------------------------------------
+
+    def _parse_slide(
+        self,
+        slide: Any,
+        slide_idx: int,
+        filename: str,
+    ) -> list[Section]:
+        """Walk one slide and return its ordered sections."""
+        slide_no = slide_idx + 1
+        prefix = (
+            self.slide_prefix.format(index=slide_no)
+            if self.slide_prefix is not None
+            else ""
+        )
+
+        slide_sections: list[Section] = []
+        # ``text_buffer`` accumulates the running text section; it is
+        # flushed whenever an image arrives, the slide ends, or
+        # ``separate_table`` forces a break around a table shape.
+        text_buffer: list[str] = []
+
+        def flush_text() -> None:
+            if not text_buffer:
+                return
+            slide_sections.append(
+                Section(
+                    content=TextBlock(text="\n".join(text_buffer)),
+                    source=filename,
+                    metadata={"slide": slide_no},
+                ),
+            )
+            text_buffer.clear()
+
+        # Slide prefix lives at the very top of the first text section.
+        if prefix:
+            text_buffer.append(prefix)
+
+        for shape in slide.shapes:
+            # 1. Pictures — flush running text, emit a DataBlock section.
+            if self.include_image:
+                image_bytes = _extract_image_bytes(shape)
+                if image_bytes is not None:
+                    flush_text()
+                    media_type = _guess_image_media_type(image_bytes)
+                    data = base64.b64encode(image_bytes).decode("utf-8")
+                    slide_sections.append(
+                        Section(
+                            content=DataBlock(
+                                source=Base64Source(
+                                    media_type=media_type,
+                                    data=data,
+                                ),
+                                name=filename,
+                            ),
+                            source=filename,
+                            metadata={
+                                "slide": slide_no,
+                                "media_type": media_type,
+                            },
+                        ),
+                    )
+                    continue
+
+            # 2. Tables — render to text; optionally flush around them.
+            if getattr(shape, "has_table", False):
+                try:
+                    rows = _extract_table_rows(shape.table)
+                except Exception as e:  # pylint: disable=broad-except
+                    logger.warning(
+                        "Failed to extract table from slide %d: %s",
+                        slide_no,
+                        e,
+                    )
+                    continue
+                rendered = (
+                    _table_to_markdown(rows)
+                    if self.table_format == "markdown"
+                    else _table_to_json(rows)
+                )
+                if not rendered:
+                    continue
+                if self.separate_table:
+                    flush_text()
+                    slide_sections.append(
+                        Section(
+                            content=TextBlock(text=rendered),
+                            source=filename,
+                            metadata={"slide": slide_no},
+                        ),
+                    )
+                else:
+                    text_buffer.append(rendered)
+                continue
+
+            # 3. Text frames.
+            if getattr(shape, "has_text_frame", False):
+                try:
+                    parts = [
+                        para.text.strip()
+                        for para in shape.text_frame.paragraphs
+                        if para.text.strip()
+                    ]
+                except Exception as e:  # pylint: disable=broad-except
+                    logger.warning(
+                        "Failed to extract text from shape in slide %d: %s",
+                        slide_no,
+                        e,
+                    )
+                    continue
+                if parts:
+                    text_buffer.append("\n".join(parts))
+
+        # Suffix goes onto the last text section of this slide.  If the
+        # slide ends on an image (text_buffer empty, no prior text
+        # section in this slide), create a small text-only carrier so
+        # the suffix is preserved.
+        if self.slide_suffix is not None:
+            text_buffer.append(self.slide_suffix)
+
+        flush_text()
+        return slide_sections

src/agentscope/rag/_parser/_text.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+"""Plain-text file parser."""
+import os
+
+from ...message import TextBlock
+from .._document import Section
+from ._base import ParserBase
+
+
+class TextParser(ParserBase):
+    """Parser for plain-text file formats.
+
+    Reads the entire file as UTF-8 text and returns a single
+    :class:`Section`.  No internal boundaries are inferred — the file
+    is treated as one unstructured blob, leaving all splitting to a
+    downstream :class:`~agentscope.rag.ChunkerBase`.
+
+    Supports a fixed set of standard text-based IANA media types
+    (``text/plain``, ``text/markdown``, ``text/csv``, …).  Use
+    ``TextParser.supported_media_types`` to enumerate them.
+    """
+
+    supported_media_types: list[str] = [
+        "text/plain",
+        "text/markdown",
+        "text/csv",
+        "text/html",
+        "text/x-rst",
+        "application/json",
+        "application/xml",
+        "application/x-yaml",
+    ]
+    """Standard IANA media types this parser handles."""
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return the human-friendly text extensions.
+
+        Override the base reverse-lookup because
+        :func:`mimetypes.guess_all_extensions` returns a long tail of
+        developer-tool extensions for ``text/plain`` (``.bat`` /
+        ``.c`` / ``.pl`` / ``.ksh`` / …) that have no place in a KB
+        file picker, and returns the empty list for
+        ``application/x-yaml``.
+        """
+        return [
+            ".csv",
+            ".htm",
+            ".html",
+            ".json",
+            ".markdown",
+            ".md",
+            ".rst",
+            ".txt",
+            ".xml",
+            ".yaml",
+            ".yml",
+        ]
+
+    def __init__(self, encoding: str = "utf-8") -> None:
+        """Initialize the text parser.
+
+        Args:
+            encoding (`str`, defaults to ``"utf-8"``):
+                The text encoding used to decode the file bytes.
+        """
+        self.encoding = encoding
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Read the file as text and return a single :class:`Section`.
+
+        Args:
+            file (`bytes | str`):
+                The file content.  ``bytes`` is decoded with the
+                configured encoding.  ``str`` is disambiguated at
+                runtime: if it names an existing file on disk the
+                file is read and decoded; otherwise it is used
+                verbatim as pre-decoded text — letting local-mode
+                callers skip the encode → decode round trip.
+            filename (`str`):
+                The source filename, copied verbatim into
+                :attr:`Section.source`.
+
+        Returns:
+            `list[Section]`:
+                Always a one-element list containing the entire file
+                contents.
+
+        Raises:
+            `ValueError`: If the bytes cannot be decoded with the
+                configured encoding.
+        """
+        if isinstance(file, str):
+            if os.path.isfile(file):
+                with open(file, "rb") as fp:
+                    raw = fp.read()
+                try:
+                    text = raw.decode(self.encoding)
+                except UnicodeDecodeError as e:
+                    raise ValueError(
+                        f"Failed to decode {filename!r} as "
+                        f"{self.encoding!r}: {e}",
+                    ) from e
+            else:
+                text = file
+        else:
+            try:
+                text = file.decode(self.encoding)
+            except UnicodeDecodeError as e:
+                raise ValueError(
+                    f"Failed to decode {filename!r} as "
+                    f"{self.encoding!r}: {e}",
+                ) from e
+
+        return [
+            Section(
+                content=TextBlock(text=text),
+                source=filename,
+                metadata={},
+            ),
+        ]

src/agentscope/rag/_parser/_utils.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""Shared helpers for binary parsers.
+
+Three small utilities used by :class:`PDFParser`, :class:`ImageParser`,
+and :class:`PPTParser`:
+
+- :func:`_guess_image_media_type` — sniff the IANA media type from raw
+  image bytes by looking at the magic number.  Used to populate the
+  ``media_type`` field of :class:`Base64Source` for embedded images.
+- :func:`_table_to_markdown` — render a 2-D ``list[list[str]]`` as a
+  Markdown pipe-table; the default rendering for table content.
+- :func:`_table_to_json` — render the same shape as a JSON array
+  prefixed with a one-line ``<system-info>`` marker; used when the
+  caller picks ``table_format="json"`` to avoid Markdown's
+  multi-line-cell ambiguity.
+"""
+import json
+
+
+def _guess_image_media_type(data: bytes) -> str:
+    """Sniff the IANA media type of an image from its magic number.
+
+    Args:
+        data (`bytes`):
+            The raw image bytes.
+
+    Returns:
+        `str`:
+            The IANA media type (e.g. ``"image/png"``).  Falls back to
+            ``"image/jpeg"`` when no signature matches — JPEG is the
+            most permissive default and matches what every consumer can
+            decode.
+    """
+    signatures = {
+        b"\x89PNG\r\n\x1a\n": "image/png",
+        b"\xff\xd8": "image/jpeg",
+        b"GIF87a": "image/gif",
+        b"GIF89a": "image/gif",
+        b"BM": "image/bmp",
+    }
+    for signature, media_type in signatures.items():
+        if data.startswith(signature):
+            return media_type
+    # WebP: ``RIFF`` at offset 0 + ``WEBP`` at offset 8.
+    if len(data) > 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return "image/jpeg"
+
+
+def _table_to_markdown(table_data: list[list[str]]) -> str:
+    """Render a 2-D table as a Markdown pipe-table.
+
+    Args:
+        table_data (`list[list[str]]`):
+            The table data; ``table_data[0]`` is the header row.
+
+    Returns:
+        `str`:
+            The Markdown rendering, or the empty string when
+            ``table_data`` is empty / column-less.
+    """
+    if not table_data:
+        return ""
+
+    num_cols = len(table_data[0])
+    if num_cols == 0:
+        return ""
+
+    lines = [
+        "| " + " | ".join(table_data[0]) + " |",
+        "| " + " | ".join(["---"] * num_cols) + " |",
+    ]
+    for row in table_data[1:]:
+        # Pad short rows so column counts match the header.
+        padded = list(row) + [""] * max(0, num_cols - len(row))
+        lines.append("| " + " | ".join(padded[:num_cols]) + " |")
+    return "\n".join(lines) + "\n"
+
+
+def _table_to_json(table_data: list[list[str]]) -> str:
+    """Render a 2-D table as JSON prefixed by a one-line marker.
+
+    The ``<system-info>`` marker lets the LLM (and any
+    structure-aware downstream renderer) tell at a glance that this
+    block is tabular data, not free text — which is otherwise
+    indistinguishable from a raw JSON dump in the middle of a chunk.
+
+    Args:
+        table_data (`list[list[str]]`):
+            The table data.
+
+    Returns:
+        `str`:
+            ``"<system-info>...</system-info>\\n<json>"``.
+    """
+    return (
+        "<system-info>A table loaded as a JSON array:</system-info>\n"
+        + json.dumps(table_data, ensure_ascii=False)
+    )

src/agentscope/rag/_vdb/__init__.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""The vector store classes in AgentScope."""
+
+from ._vector_store import (
+    DocumentSummary,
+    VectorRecord,
+    VectorSearchResult,
+    VectorStoreBase,
+)
+from ._qdrant import QdrantStore
+
+__all__ = [
+    "DocumentSummary",
+    "VectorStoreBase",
+    "VectorRecord",
+    "VectorSearchResult",
+    "QdrantStore",
+]

src/agentscope/rag/_vdb/_qdrant.py

@@ -0,0 +1,392 @@
+# -*- coding: utf-8 -*-
+"""Qdrant implementation of the vector store backend.
+
+Built on the official ``qdrant-client`` SDK using its fully
+asynchronous client (:class:`~qdrant_client.AsyncQdrantClient`), so all
+operations are non-blocking and safe to call from the application's
+event loop.
+
+The same class supports all Qdrant deployment modes through the
+constructor arguments:
+
+- ``location=":memory:"`` — in-process, ephemeral (ideal for tests)
+- ``path="/path/to/db"`` — in-process, persisted to local disk
+- ``url="http://localhost:6333"`` — remote Qdrant server / cloud
+"""
+import uuid
+from typing import TYPE_CHECKING, Any, Literal
+
+from ._vector_store import (
+    DocumentSummary,
+    VectorRecord,
+    VectorSearchResult,
+    VectorStoreBase,
+)
+from .._document import Chunk
+
+if TYPE_CHECKING:
+    from qdrant_client import AsyncQdrantClient
+
+
+class QdrantStore(VectorStoreBase):
+    """Vector store backend backed by `Qdrant <https://qdrant.tech>`_.
+
+    Each knowledge base maps to one Qdrant collection.  Every point
+    payload stores the owning ``document_id`` plus the serialized
+    :class:`~agentscope.rag.Chunk`, which is reconstructed on
+    retrieval.
+
+    .. note:: The ``qdrant-client`` package is required. Install it
+        with ``pip install qdrant-client``.
+
+    .. code-block:: python
+
+        # In-memory (tests / prototyping)
+        store = QdrantStore(location=":memory:")
+
+        # Remote server
+        store = QdrantStore(
+            url="http://localhost:6333",
+            api_key="...",
+        )
+
+        async with store:
+            await store.create_collection("kb-1", dimensions=768)
+
+    """
+
+    def __init__(
+        self,
+        location: str | None = None,
+        url: str | None = None,
+        path: str | None = None,
+        api_key: str | None = None,
+        distance: Literal["Cosine", "Dot", "Euclid", "Manhattan"] = "Cosine",
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the Qdrant vector store.
+
+        Args:
+            location (`str | None`, optional):
+                Pass ``":memory:"`` for an ephemeral in-process
+                instance. Mutually exclusive with ``url`` and ``path``.
+            url (`str | None`, optional):
+                The URL of a remote Qdrant server, e.g.
+                ``"http://localhost:6333"``.
+            path (`str | None`, optional):
+                A local directory for an in-process, on-disk instance.
+            api_key (`str | None`, optional):
+                The API key for Qdrant Cloud or a secured server.
+            distance (`Literal["Cosine", "Dot", "Euclid", "Manhattan"]`, \
+             defaults to ``"Cosine"``):
+                The distance metric used when creating collections.
+            client_kwargs (`dict[str, Any] | None`, optional):
+                Extra keyword arguments forwarded to
+                :class:`~qdrant_client.AsyncQdrantClient`.
+        """
+        self._location = location
+        self._url = url
+        self._path = path
+        self._api_key = api_key
+        self._distance = distance
+        self._client_kwargs = client_kwargs or {}
+        self._client: "AsyncQdrantClient | None" = None
+
+    def get_client(self) -> "AsyncQdrantClient":
+        """Lazily create and cache the async Qdrant client.
+
+        Returns:
+            `AsyncQdrantClient`:
+                The shared async client instance.
+        """
+        if self._client is None:
+            from qdrant_client import AsyncQdrantClient
+
+            self._client = AsyncQdrantClient(
+                location=self._location,
+                url=self._url,
+                path=self._path,
+                api_key=self._api_key,
+                **self._client_kwargs,
+            )
+        return self._client
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit the async context — close the underlying client."""
+        if self._client is not None:
+            await self._client.close()
+            self._client = None
+
+    # ------------------------------------------------------------------
+    # Collection management
+    # ------------------------------------------------------------------
+
+    async def create_collection(
+        self,
+        name: str,
+        dimensions: int,
+    ) -> None:
+        """Create a new Qdrant collection.
+
+        No-op if the collection already exists.
+
+        Args:
+            name (`str`):
+                The collection name. Typically, the knowledge base ID.
+            dimensions (`int`):
+                The fixed vector dimensionality for this collection.
+        """
+        from qdrant_client import models
+
+        client = self.get_client()
+        if await client.collection_exists(name):
+            return
+        await client.create_collection(
+            collection_name=name,
+            vectors_config=models.VectorParams(
+                size=dimensions,
+                distance=models.Distance(self._distance),
+            ),
+        )
+
+    async def delete_collection(self, name: str) -> None:
+        """Delete a collection and all its data.
+
+        Args:
+            name (`str`):
+                The collection name to delete.
+        """
+        await self.get_client().delete_collection(name)
+
+    async def has_collection(self, name: str) -> bool:
+        """Check whether a collection exists.
+
+        Args:
+            name (`str`):
+                The collection name to check.
+
+        Returns:
+            `bool`: ``True`` if the collection exists.
+        """
+        return await self.get_client().collection_exists(name)
+
+    # ------------------------------------------------------------------
+    # Data operations
+    # ------------------------------------------------------------------
+
+    async def insert(
+        self,
+        collection: str,
+        records: list[VectorRecord],
+    ) -> None:
+        """Insert records into a collection.
+
+        Each point payload stores the :attr:`VectorRecord.document_id`
+        under the ``document_id`` key and the serialized
+        :class:`Chunk` under the ``chunk`` key, so that :meth:`delete`
+        can remove all records of one document.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            records (`list[VectorRecord]`):
+                The records to insert (each carrying a
+                :class:`Chunk` and its embedding vector).
+        """
+
+        from qdrant_client import models
+
+        if not records:
+            return
+        await self.get_client().upsert(
+            collection_name=collection,
+            points=[
+                models.PointStruct(
+                    id=str(uuid.uuid4()),
+                    vector=record.vector,
+                    payload={
+                        "document_id": record.document_id,
+                        "chunk": record.chunk.model_dump(mode="json"),
+                    },
+                )
+                for record in records
+            ],
+        )
+
+    async def delete(
+        self,
+        collection: str,
+        document_id: str,
+    ) -> None:
+        """Delete all records belonging to one source document.
+
+        Matches the ``document_id`` payload key written by
+        :meth:`insert` from :attr:`VectorRecord.document_id`.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            document_id (`str`):
+                The source document ID whose records should be
+                removed.
+        """
+        from qdrant_client import models
+
+        await self.get_client().delete(
+            collection_name=collection,
+            points_selector=models.FilterSelector(
+                filter=models.Filter(
+                    must=[
+                        models.FieldCondition(
+                            key="document_id",
+                            match=models.MatchValue(value=document_id),
+                        ),
+                    ],
+                ),
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        collection: str,
+        query_vector: list[float],
+        top_k: int = 5,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[VectorSearchResult]:
+        """Find the most similar records to a query vector.
+
+        Args:
+            collection (`str`):
+                The collection to search.
+            query_vector (`list[float]`):
+                The query embedding vector.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results to return.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict the search to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict (translated into a Qdrant ``must`` payload
+                filter against ``chunk.metadata.<key>``).
+
+        Returns:
+            `list[VectorSearchResult]`:
+                Results ordered by descending similarity score.
+        """
+        response = await self.get_client().query_points(
+            collection_name=collection,
+            query=query_vector,
+            limit=top_k,
+            with_payload=True,
+            query_filter=self._build_metadata_filter(metadata_filter),
+        )
+        return [
+            VectorSearchResult(
+                score=point.score,
+                document_id=point.payload["document_id"],
+                chunk=Chunk.model_validate(point.payload["chunk"]),
+            )
+            for point in response.points
+        ]
+
+    # ------------------------------------------------------------------
+    # Document listing
+    # ------------------------------------------------------------------
+
+    async def list_documents(
+        self,
+        collection: str,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[DocumentSummary]:
+        """List all distinct source documents indexed in a collection.
+
+        Scrolls the collection in payload-only mode (vectors disabled)
+        and aggregates by ``document_id``.  The first chunk encountered
+        for each document supplies the ``source`` filename and the
+        document-level ``metadata``.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict aggregation to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair.
+
+        Returns:
+            `list[DocumentSummary]`:
+                One summary per distinct ``document_id``.
+        """
+        client = self.get_client()
+        query_filter = self._build_metadata_filter(metadata_filter)
+        summaries: dict[str, DocumentSummary] = {}
+        offset: Any = None
+
+        while True:
+            points, next_offset = await client.scroll(
+                collection_name=collection,
+                scroll_filter=query_filter,
+                limit=256,
+                offset=offset,
+                with_payload=True,
+                with_vectors=False,
+            )
+            for point in points:
+                doc_id = point.payload["document_id"]
+                summary = summaries.get(doc_id)
+                if summary is None:
+                    chunk_payload = point.payload["chunk"]
+                    summaries[doc_id] = DocumentSummary(
+                        document_id=doc_id,
+                        source=chunk_payload.get("source", ""),
+                        chunk_count=1,
+                        metadata=dict(chunk_payload.get("metadata", {})),
+                    )
+                else:
+                    summary.chunk_count += 1
+            if next_offset is None:
+                break
+            offset = next_offset
+
+        return list(summaries.values())
+
+    @staticmethod
+    def _build_metadata_filter(
+        metadata_filter: dict[str, Any] | None,
+    ) -> Any:
+        """Translate a flat ``{key: value}`` filter into a Qdrant filter.
+
+        Each ``key`` is matched against the corresponding nested path
+        ``chunk.metadata.<key>`` written by :meth:`insert`.  Returns
+        ``None`` when ``metadata_filter`` is empty so that callers
+        skip the filter argument entirely.
+
+        Args:
+            metadata_filter (`dict[str, Any] | None`):
+                The flat filter, or ``None`` for no filter.
+
+        Returns:
+            `qdrant_client.models.Filter | None`:
+                A Qdrant ``Filter`` object, or ``None``.
+        """
+        if not metadata_filter:
+            return None
+
+        from qdrant_client import models
+
+        return models.Filter(
+            must=[
+                models.FieldCondition(
+                    key=f"chunk.metadata.{key}",
+                    match=models.MatchValue(value=value),
+                )
+                for key, value in metadata_filter.items()
+            ],
+        )

src/agentscope/rag/_vdb/_vector_store.py

@@ -0,0 +1,291 @@
+# -*- coding: utf-8 -*-
+"""Abstract base class for vector store backends.
+
+A :class:`VectorStoreBase` instance is the single connection point to
+one vector database deployment.  It is created once at application
+startup, passed into ``create_app(vector_store=...)``, and shared
+across all requests for the lifetime of the process — similar to
+:class:`~agentscope.app.storage.StorageBase` and
+:class:`~agentscope.app.message_bus.MessageBus`.
+
+Each **knowledge base** maps to one **collection** inside the vector
+store.  Collections are isolated: different knowledge bases never
+share a collection, so retrieval is always scoped to a single
+collection without cross-collection filtering.
+
+Lifecycle is managed via the async context manager protocol
+(``__aenter__`` / ``__aexit__``), which the app lifespan calls
+automatically.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Self
+
+from pydantic import BaseModel, Field
+
+from .._document import Chunk
+
+
+class VectorRecord(BaseModel):
+    """A single record to insert into a vector store collection.
+
+    Pairs a :class:`Chunk` (the business payload — content, source,
+    structural metadata) with its dense embedding vector.  ``Chunk``
+    is intentionally not extended with an ``embedding`` field so its
+    semantics stay stable across the indexing pipeline; instead the
+    vector lives in this wrapper whose only purpose is "I am about
+    to be inserted into a vector database."
+    """
+
+    vector: list[float]
+    """The dense embedding vector for :attr:`chunk`."""
+
+    document_id: str
+    """The ID of the source document this record belongs to.
+    Assigned by the knowledge base layer when the document is
+    registered.  Backends must persist it at insertion time so that
+    :meth:`VectorStoreBase.delete` can remove all records of one
+    document as a unit."""
+
+    chunk: Chunk
+    """The business payload — content, source, structural metadata."""
+
+
+class VectorSearchResult(BaseModel):
+    """A single result returned by a similarity search.
+
+    Pairs the matched :class:`Chunk` with its similarity score.
+    ``Chunk`` is intentionally not extended with a ``score`` field so
+    its semantics stay stable; instead the score lives in this
+    wrapper whose only purpose is "I am a query hit."
+    """
+
+    score: float
+    """Similarity score.  Higher = more similar for cosine /
+    dot-product; lower = more similar for L2 distance."""
+
+    document_id: str
+    """The ID of the source document the matched chunk belongs to —
+    the same value carried by :attr:`VectorRecord.document_id` at
+    insertion time.  Lets callers cite, group, or delete the source
+    document of a hit."""
+
+    chunk: Chunk
+    """The matched business payload."""
+
+
+class DocumentSummary(BaseModel):
+    """A lightweight description of one source document inside a collection.
+
+    Aggregated by :meth:`VectorStoreBase.list_documents` from the
+    records of each ``document_id`` — the vector store is the single
+    source of truth for "what documents exist in a knowledge base".
+    """
+
+    document_id: str
+    """The source document identifier — the same value carried by
+    :attr:`VectorRecord.document_id` at insertion time."""
+
+    source: str
+    """The original filename, taken from the first chunk encountered.
+    All chunks of the same document share the same filename so any
+    chunk yields the same value."""
+
+    chunk_count: int
+    """The total number of chunks indexed for this document."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Document-level metadata propagated from the parser / uploader
+    (media type, size, upload time, ...).  Taken from the first chunk
+    encountered."""
+
+
+class VectorStoreBase(ABC):
+    """Abstract base class for vector store backends.
+
+    Subclasses implement the concrete connection and query logic for a
+    specific vector database (Chroma, Milvus, Qdrant, FAISS, etc.).
+
+    A single instance is shared across the entire application.  The
+    underlying client SDK is expected to handle connection pooling and
+    thread safety internally.
+    """
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context — open connections if needed.
+
+        The default implementation is a no-op.  Subclasses that need
+        explicit connection setup should override this.
+
+        Returns:
+            `VectorStoreBase`: ``self``.
+        """
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit the async context — close connections if needed.
+
+        The default implementation is a no-op.
+        """
+
+    # ------------------------------------------------------------------
+    # Collection management
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def create_collection(
+        self,
+        name: str,
+        dimensions: int,
+    ) -> None:
+        """Create a new collection (vector index).
+
+        If the collection already exists, implementations should raise
+        or silently no-op depending on the backend's semantics.
+
+        Args:
+            name (`str`):
+                The collection name. Typically, the knowledge base ID.
+            dimensions (`int`):
+                The fixed vector dimensionality for this collection.
+                All vectors inserted later must have this many elements.
+        """
+
+    @abstractmethod
+    async def delete_collection(self, name: str) -> None:
+        """Delete a collection and all its data.
+
+        Args:
+            name (`str`):
+                The collection name to delete.
+        """
+
+    @abstractmethod
+    async def has_collection(self, name: str) -> bool:
+        """Check whether a collection exists.
+
+        Args:
+            name (`str`):
+                The collection name to check.
+
+        Returns:
+            `bool`: ``True`` if the collection exists.
+        """
+
+    # ------------------------------------------------------------------
+    # Data operations
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def insert(
+        self,
+        collection: str,
+        records: list[VectorRecord],
+    ) -> None:
+        """Insert records into a collection.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            records (`list[VectorRecord]`):
+                The records to insert (each carrying a
+                :class:`Chunk` and its embedding vector).
+        """
+
+    @abstractmethod
+    async def delete(
+        self,
+        collection: str,
+        document_id: str,
+    ) -> None:
+        """Delete all records belonging to one source document.
+
+        Identifies records by the :attr:`VectorRecord.document_id`
+        field that backends persist at insertion time.  This matches
+        the typical RAG workflow where a user uploads or removes a
+        file as a unit.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            document_id (`str`):
+                The source document ID whose records should be
+                removed.
+        """
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def search(
+        self,
+        collection: str,
+        query_vector: list[float],
+        top_k: int = 5,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[VectorSearchResult]:
+        """Find the most similar records to a query vector.
+
+        Args:
+            collection (`str`):
+                The collection to search.
+            query_vector (`list[float]`):
+                The query embedding vector.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results to return.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict the search to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict.  Backends translate this into a native
+                payload filter.  Used for defense-in-depth
+                cross-tenant scoping when an isolation strategy
+                co-locates multiple knowledge bases inside the same
+                collection.
+
+        Returns:
+            `list[VectorSearchResult]`:
+                Results ordered by descending similarity score.
+        """
+
+    # ------------------------------------------------------------------
+    # Document listing
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def list_documents(
+        self,
+        collection: str,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[DocumentSummary]:
+        """List all distinct source documents indexed in a collection.
+
+        Aggregates records by :attr:`VectorRecord.document_id` and
+        returns one :class:`DocumentSummary` per document.  Backends
+        are free to use whatever scrolling / aggregation primitive
+        they expose; this method is expected to be O(documents) not
+        O(chunks) on backends that support payload-only scans.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict aggregation to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict.  Used together with the search-time
+                filter when an isolation strategy co-locates multiple
+                knowledge bases inside the same collection.
+
+        Returns:
+            `list[DocumentSummary]`:
+                One summary per distinct ``document_id``, in
+                unspecified order.
+        """

src/agentscope/skill/__init__.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+"""The skill related classes and functions."""
+
+from ._base import SkillLoaderBase, Skill
+from ._local_loader import LocalSkillLoader
+
+__all__ = [
+    "Skill",
+    "SkillLoaderBase",
+    "LocalSkillLoader",
+]

src/agentscope/skill/_base.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""The skill loader base class."""
+from abc import abstractmethod, ABC
+from dataclasses import dataclass
+
+
+@dataclass
+class Skill:
+    """The agent skill class"""
+
+    name: str
+    """The name of the skill."""
+    description: str
+    """The description of the skill."""
+    dir: str
+    """The directory of the agent skill."""
+    markdown: str
+    """The markdown content of the agent skill."""
+    updated_at: float
+    """The last updated time of the skill."""
+
+
+class SkillLoaderBase(ABC):
+    """The base class for skill loader."""
+
+    @abstractmethod
+    async def list_skills(self) -> list[Skill]:
+        """List all the skills that can be loaded by this loader."""
+        raise NotImplementedError

src/agentscope/skill/_local_loader.py

@@ -0,0 +1,171 @@
+# -*- coding: utf-8 -*-
+"""The local skill loader class."""
+import asyncio
+import os
+
+import aiofiles
+import aiofiles.ospath
+import frontmatter
+
+from ._base import SkillLoaderBase
+from .._logging import logger
+from ..skill import Skill
+
+
+class LocalSkillLoader(SkillLoaderBase):
+    """The skill loader that loads skills from a local directory."""
+
+    def __init__(self, directory: str, scan_subdir: bool = False) -> None:
+        """Initialize the loader with the directory.
+
+        Args:
+            directory (`str`):
+                The directory to load skills from.
+            scan_subdir (`bool`, defaults to False):
+                Whether to scan subdirectories. Defaults to False (only
+                scan current directory).
+        """
+        self.directory = os.path.abspath(directory)
+        self.scan_subdir = scan_subdir
+        self._cache: dict[str, Skill] = {}
+
+    async def _load_single_skill(self, skill_root: str) -> Skill | None:
+        """Load a single skill from a skill root directory.
+
+        Args:
+            skill_root (`str`): The skill root directory containing SKILL.md.
+
+        Returns:
+            `Skill | None`: A Skill object or None if loading failed.
+        """
+        skill_md_path = os.path.join(skill_root, "SKILL.md")
+
+        try:
+            # Check if SKILL.md exists
+            if not await aiofiles.ospath.isfile(skill_md_path):
+                return None
+
+            # Get file modification time
+            updated_at = await aiofiles.ospath.getmtime(skill_md_path)
+
+            # Check cache: if cached skill exists and updated_at matches,
+            # return cached
+            if skill_root in self._cache:
+                cached_skill = self._cache[skill_root]
+                if cached_skill.updated_at == updated_at:
+                    return cached_skill
+
+            # Read and parse SKILL.md
+            async with aiofiles.open(
+                skill_md_path,
+                "r",
+                encoding="utf-8",
+            ) as f:
+                content_str = await f.read()
+                content = frontmatter.loads(content_str)
+
+            name = content.get("name")
+            description = content.get("description")
+
+            if not name or not description:
+                logger.warning(
+                    "SKILL.md in %s is missing required fields "
+                    "(name or description). Skipping.",
+                    skill_root,
+                )
+                return None
+
+            skill = Skill(
+                name=str(name),
+                description=str(description),
+                dir=skill_root,
+                markdown=content.content,
+                updated_at=updated_at,
+            )
+
+            # Update cache
+            self._cache[skill_root] = skill
+
+            return skill
+
+        except Exception as e:
+            logger.warning(
+                "Failed to load skill from %s: %s",
+                skill_root,
+                str(e),
+            )
+            return None
+
+    async def list_skills(self) -> list[Skill]:
+        """List all the available skills from the directory.
+
+        This method will:
+        1. Search for SKILL.md in the current directory
+        2. If scan_subdir is True, search for SKILL.md in all subdirectories
+        3. Load all SKILL.md files concurrently
+
+        Returns:
+            `list[Skill]`: A list of Skill objects.
+        """
+        try:
+            # Check if directory exists
+            if not await aiofiles.ospath.isdir(self.directory):
+                logger.warning(
+                    "Skill directory %s does not exist.",
+                    self.directory,
+                )
+                return []
+
+            # Find all directories containing SKILL.md
+            def _find_skill_dirs() -> list[str]:
+                """Find all directories containing SKILL.md file."""
+                dirs = []
+
+                if os.path.isfile(os.path.join(self.directory, "SKILL.md")):
+                    dirs.append(self.directory)
+
+                if self.scan_subdir:
+                    for root, _, filenames in os.walk(self.directory):
+                        if root == self.directory:
+                            continue
+                        if "SKILL.md" in filenames:
+                            dirs.append(root)
+
+                return dirs
+
+            skill_dirs = await asyncio.to_thread(_find_skill_dirs)
+
+            if not skill_dirs:
+                logger.info(
+                    "No SKILL.md files found in %s",
+                    self.directory,
+                )
+                return []
+
+            # Load all skills concurrently
+            tasks = [
+                self._load_single_skill(skill_dir) for skill_dir in skill_dirs
+            ]
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+
+            # Filter out None results and exceptions
+            skills: list = []
+            for i, result in enumerate(results):
+                if isinstance(result, Exception):
+                    logger.warning(
+                        "Failed to load skill from %s: %s",
+                        skill_dirs[i],
+                        str(result),
+                    )
+                elif result is not None:
+                    skills.append(result)
+
+            return skills
+
+        except Exception as e:
+            logger.warning(
+                "Failed to list skills from directory %s: %s",
+                self.directory,
+                str(e),
+            )
+            return []

src/agentscope/state/__init__.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+"""The agent state module in agentscope."""
+
+from ._state import AgentState, TaskContext
+from ._task import Task
+
+__all__ = [
+    "Task",
+    "TaskContext",
+    "AgentState",
+]

src/agentscope/state/_state.py

@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""The agent state class."""
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+import aiofiles.os
+
+from .._utils._common import _generate_id
+from ._task import Task
+from ..message import (
+    TextBlock,
+    DataBlock,
+    Msg,
+    ToolCallBlock,
+    ToolResultBlock,
+    HintBlock,
+)
+from ..permission import PermissionContext
+
+
+class ReadCacheEntry(BaseModel):
+    """The read file cache."""
+
+    lines: list[str]
+    updated_at: float
+    bytes: float
+    file_path: str
+
+
+class ToolContext(BaseModel):
+    """The tool context, e.g. tool cache"""
+
+    max_cache_files: int = Field(default=100, gt=1)
+    """The maximum number of cached files."""
+    max_cache_bytes: float = Field(default=25000, gt=10000)
+    """The maximum size of the accumulated read file cache."""
+    read_file_cache: list[ReadCacheEntry] = Field(default_factory=list)
+    """The cache for Read/Write/Edit file tools."""
+
+    activated_groups: list[str] = Field(default_factory=list)
+    """The names of the activated tool groups, each group contains a set of
+    tools."""
+
+    async def get_cache(self, file_path: str) -> ReadCacheEntry | None:
+        """Get cached file content if still valid.
+
+        Args:
+            file_path: The absolute path of the file.
+
+        Returns:
+            The cached entry if valid, otherwise None.
+        """
+
+        # Find the cache entry
+        for entry in self.read_file_cache:
+            if entry.file_path == file_path:
+                # Check if cache is still valid
+                try:
+                    updated_at = await aiofiles.os.path.getmtime(file_path)
+                    if updated_at == entry.updated_at:
+                        return entry
+                    else:
+                        # Cache is outdated, remove it
+                        self.read_file_cache.remove(entry)
+                        return None
+                except Exception:
+                    # File might not exist anymore
+                    self.read_file_cache.remove(entry)
+                    return None
+        return None
+
+    async def cache_file(self, file_path: str, lines: list[str]) -> None:
+        """Cache file content with LRU eviction.
+
+        Args:
+            file_path: The absolute path of the file.
+            lines: The lines of the file content.
+        """
+        try:
+            updated_at = await aiofiles.os.path.getmtime(file_path)
+        except Exception:
+            # Cannot get mtime, skip caching
+            return
+
+        # Calculate size in KB
+        new_entry_bytes = (
+            sum(len(line.encode("utf-8")) for line in lines) / 1024
+        )
+
+        # Remove existing cache for this file if present
+        self.read_file_cache = [
+            entry
+            for entry in self.read_file_cache
+            if entry.file_path != file_path
+        ]
+
+        # Evict the oldest entries if exceeding max_cache_files
+        while len(self.read_file_cache) >= self.max_cache_files:
+            self.read_file_cache.pop(0)
+
+        # Evict the oldest entries if exceeding max_cache_bytes
+        current_size = sum(entry.bytes for entry in self.read_file_cache)
+        while (
+            self.read_file_cache
+            and current_size + new_entry_bytes > self.max_cache_bytes
+        ):
+            removed = self.read_file_cache.pop(0)
+            current_size -= removed.bytes
+
+        # Add new entry to the end (most recent)
+        self.read_file_cache.append(
+            ReadCacheEntry(
+                lines=lines,
+                updated_at=updated_at,
+                bytes=new_entry_bytes,
+                file_path=file_path,
+            ),
+        )
+
+    async def clean_file_cache(
+        self,
+        reserved_file_paths: set[str] | None = None,
+    ) -> None:
+        """Drop read caches whose paths are not in ``reserved_file_paths``.
+
+        Args:
+            reserved_file_paths: File paths from Read calls that remain in the
+                context. Caches for these files are kept; all others are
+                evicted.
+        """
+        reserved_file_paths = reserved_file_paths or set()
+
+        self.read_file_cache = [
+            entry
+            for entry in self.read_file_cache
+            if entry.file_path in reserved_file_paths
+        ]
+
+
+class TaskContext(BaseModel):
+    """The task context."""
+
+    tasks: list[Task] = Field(default_factory=lambda: [])
+    """The task context."""
+
+
+class AgentState(BaseModel):
+    """The agent state that should be saved and loaded from storage."""
+
+    session_id: str = Field(default_factory=_generate_id)
+    """The session id of the agent. Normally, each session will maintain one
+    independent agent state for each agent."""
+
+    summary: str | list[TextBlock | DataBlock] = ""
+    """The compressed summary of the context, which will be prepended to the
+    context when feed into the LLM."""
+    context: list[Msg] = Field(default_factory=list)
+    """The uncompressed conversation context, that will be feed into the LLM"""
+    reply_id: str = Field(default_factory=_generate_id)
+    """The id of the current reply, which is also used as the id of the
+    final message of the reply."""
+    cur_iter: int = 0
+    """The current iteration of the agent's reasoning-acting loop."""
+
+    # =================================================================
+    # The permission context
+    # =================================================================
+    permission_context: PermissionContext = Field(
+        default_factory=PermissionContext,
+    )
+    """The permission context that will be passed to the toolkit to determine
+    the tool permissions."""
+
+    # =================================================================
+    # The tool context
+    # =================================================================
+    tool_context: ToolContext = Field(default_factory=ToolContext)
+
+    # =================================================================
+    # The tasks context
+    # =================================================================
+    tasks_context: TaskContext = Field(default_factory=TaskContext)
+    """The task context that records the agent tasks."""
+
+    # =================================================================
+    # The middleware context
+    # =================================================================
+    middle_context: dict[str, Any] = Field(default_factory=dict)
+    """The context that allow the middlewares to store/get data across
+    different replies."""
+
+    def append_context(
+        self,
+        name: str,
+        blocks: list[
+            TextBlock | DataBlock | HintBlock | ToolCallBlock | ToolResultBlock
+        ],
+    ) -> None:
+        """Append the given blocks to the agent's own message with the current
+        `reply_id`. If such message doesn't exist, a new assistant message
+        with agent's name and current reply ID will be created.
+        """
+        # If append to the latest message
+        if (
+            self.context
+            and self.context[-1].role == "assistant"
+            and self.context[-1].name == name
+            and self.context[-1].id == self.reply_id
+        ):
+            self.context[-1].content.extend(blocks)
+        else:
+            # Create a new assistant message with the current reply ID
+            self.context.append(
+                Msg(
+                    id=self.reply_id,
+                    role="assistant",
+                    name=name,
+                    content=blocks,
+                ),
+            )

src/agentscope/state/_task.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+"""The task class."""
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from .._utils._common import _generate_id
+
+
+class Task(BaseModel):
+    """The agent task."""
+
+    subject: str
+    """The subject of the task."""
+
+    description: str
+    """The task description."""
+
+    metadata: dict[str, Any]
+    """The additional metadata of the task."""
+
+    created_at: str = Field(default_factory=lambda: datetime.now().isoformat())
+    """The created timestamp."""
+
+    state: Literal["pending", "in_progress", "completed"] = "pending"
+    """The task state."""
+
+    id: str = Field(default_factory=_generate_id)
+    """The task identifier."""
+
+    owner: str | None = None
+    """The owner of the task."""
+
+    blocks: list[str] = Field(default_factory=lambda: [])
+    """The task ids blocked by this task."""
+
+    blocked_by: list[str] = Field(default_factory=lambda: [])
+    """The task ids blocking this task."""

src/agentscope/tool/__init__.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""The tool module in agentscope."""
+
+from ._types import ToolChoice, Function, RegisteredTool
+from ._response import ToolResponse, ToolChunk
+from ._toolkit import Toolkit
+from ._base import ToolBase, ParamsBase, ToolMiddlewareBase
+from ._adapters import MCPTool, FunctionTool
+from ._builtin import (
+    ResetTools,
+    Bash,
+    Edit,
+    Glob,
+    Grep,
+    Read,
+    Write,
+    BackendBase,
+    ExecResult,
+    LocalBackend,
+)
+from ._task import (
+    TaskUpdate,
+    TaskGet,
+    TaskList,
+    TaskCreate,
+)
+from ._tool_group import ToolGroup
+
+__all__ = [
+    # Basic tool related types and functions
+    "ToolChoice",
+    "Function",
+    "ToolBase",
+    "ParamsBase",
+    "ToolMiddlewareBase",
+    "MCPTool",
+    "FunctionTool",
+    "ToolGroup",
+    "Toolkit",
+    "ToolChunk",
+    "ToolResponse",
+    "RegisteredTool",
+    # Builtin tools
+    "BackendBase",
+    "LocalBackend",
+    "ExecResult",
+    "ResetTools",
+    "Bash",
+    "Edit",
+    "Glob",
+    "Grep",
+    "Read",
+    "Write",
+    "TaskUpdate",
+    "TaskGet",
+    "TaskList",
+    "TaskCreate",
+]

src/agentscope/tool/_adapters.py

@@ -0,0 +1,394 @@
+# -*- coding: utf-8 -*-
+"""Adapters to convert functions and MCP tools to ToolProtocol."""
+import inspect
+import json
+import re
+from contextlib import _AsyncGeneratorContextManager
+from datetime import timedelta
+from typing import Callable, Any, AsyncGenerator, Generator
+
+from mcp import ClientSession
+import mcp
+
+from ._types import Function
+from ._base import ToolBase, ToolMiddlewareBase
+from ..permission import (
+    PermissionBehavior,
+    PermissionDecision,
+)
+from ._response import ToolChunk
+from ._utils import _extract_func_description, _extract_input_schema
+from .._logging import logger
+from ..message import (
+    TextBlock,
+    DataBlock,
+    Base64Source,
+    URLSource,
+    ToolResultState,
+)
+
+
+class FunctionTool(ToolBase):
+    """Adapter to convert a Python function to ToolProtocol.
+
+    This class wraps a regular Python function and makes it compatible with
+    the ToolProtocol interface. It automatically extracts metadata from the
+    function's signature and docstring, and normalizes the return value to
+    ToolChunk or AsyncGenerator[ToolChunk, None].
+    """
+
+    is_external_tool: bool = False
+    """If this tool is an external tool, which doesn't need to implement the
+    __call__ method and the agent will yield the external tool call event."""
+    is_mcp: bool = False
+    """If this tool is an MCP tool, which will be used in the permission"""
+    mcp_name: str | None = None
+    """The name of the MCP server this tool belongs to, which is required if
+    this tool is an MCP tool."""
+
+    def __init__(
+        self,
+        func: Function,
+        name: str | None = None,
+        description: str | None = None,
+        is_concurrency_safe: bool = True,
+        is_read_only: bool = False,
+        is_state_injected: bool = False,
+        middlewares: list[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the FunctionTool.
+
+        Args:
+            func (`Callable`):
+                The Python function to wrap.
+            name (`str | None`, optional):
+                Custom tool name. If None, uses the function name.
+            description (`str | None`, optional):
+                Custom tool description. If None, extracts from docstring.
+            is_concurrency_safe (`bool`, optional):
+                Whether this tool is safe to call concurrently.
+            is_read_only (`bool`, optional):
+                Whether this tool only reads data without side effects.
+            is_state_injected (`bool`, optional):
+                Whether this tool requires agent state injection.
+            middlewares (`list[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+        """
+        super().__init__(middlewares=middlewares)
+        self.name = name or func.__name__
+        self.description = description or _extract_func_description(
+            func.__doc__ or "",
+        )
+        self.input_schema = _extract_input_schema(func)
+        self.is_concurrency_safe = is_concurrency_safe
+        self.is_read_only = is_read_only
+        self.is_state_injected = is_state_injected
+        self.is_external_tool = False
+        self.is_mcp = False
+        self._func = func
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage.
+
+        Default implementation allows all operations.
+
+        Returns:
+            `PermissionDecision`:
+                Permission decision (default: allowed).
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="Custom function tools must be explicitly allowed "
+            "by the user.",
+        )
+
+    async def call(
+        self,
+        **kwargs: Any,
+    ) -> ToolChunk | AsyncGenerator[ToolChunk, None]:
+        """Invoke the wrapped function in an async style.
+
+        Returns:
+            `ToolChunk` or `AsyncGenerator[ToolChunk, None]`:
+                The normalized result of the function execution.
+        """
+        if inspect.iscoroutinefunction(self._func):
+            result = await self._func(**kwargs)
+        else:
+            result = self._func(**kwargs)
+
+        if isinstance(result, AsyncGenerator):
+
+            async def _stream() -> AsyncGenerator[ToolChunk, None]:
+                async for chunk in result:
+                    if isinstance(chunk, ToolChunk):
+                        yield chunk
+                    else:
+                        yield self._convert_func_result_to_chunk(chunk)
+
+            return _stream()
+
+        if isinstance(result, Generator):
+
+            async def _stream() -> AsyncGenerator[ToolChunk, None]:
+                for chunk in result:
+                    if isinstance(chunk, ToolChunk):
+                        yield chunk
+                    else:
+                        yield self._convert_func_result_to_chunk(chunk)
+
+            return _stream()
+
+        return self._convert_func_result_to_chunk(result)
+
+    @staticmethod
+    def _convert_func_result_to_chunk(
+        result: Any,
+    ) -> ToolChunk:
+        if isinstance(result, ToolChunk):
+            return result
+        if isinstance(result, str):
+            text = result
+        else:
+            try:
+                text = json.dumps(result, ensure_ascii=False)
+            except (TypeError, ValueError):
+                text = str(result)
+        return ToolChunk(
+            content=[TextBlock(text=text)],
+            state=ToolResultState.RUNNING,
+        )
+
+
+class MCPTool(ToolBase):
+    """Adapter to convert an MCP tool to ToolProtocol.
+
+    This class wraps an MCP tool and makes it compatible with the ToolProtocol
+    interface. It handles the conversion between MCP's result format and
+    AgentScope's ToolChunk format.
+    """
+
+    is_mcp: bool = True
+    """Whether this tool is an MCP tool."""
+    is_state_injected: bool = False
+    """The mcp tools is prohibited state injection for safety reason."""
+
+    def __init__(
+        self,
+        mcp_name: str,
+        tool: mcp.types.Tool,
+        client_gen: Callable[..., _AsyncGeneratorContextManager[Any]]
+        | None = None,
+        session: Any | None = None,
+        timeout: float | None = None,
+        middlewares: list[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the MCPTool.
+
+        Args:
+            mcp_name (`str`):
+                The name of the MCP server instance.
+            tool (`mcp.types.Tool`):
+                The MCP tool definition.
+            client_gen (`Callable[..., _AsyncGeneratorContextManager[Any]] \
+            | None`, optional):
+                The MCP client generator function for stateless clients.
+                Either this or ``session`` must be provided.
+            session (`mcp.ClientSession | None`, optional):
+                The MCP client session for stateful clients.
+                Either this or ``client_gen`` must be provided.
+            timeout (`float | None`, optional):
+                The timeout in seconds for tool execution.
+            middlewares (`list[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+        """
+        super().__init__(middlewares=middlewares)
+        self.mcp_name = mcp_name
+
+        # LLM providers enforce ^[a-zA-Z0-9_-]+$ on tool names.
+        # mcp_name is validated in MCPClient.model_post_init;
+        # tool.name comes from the MCP server and may contain dots,
+        # colons, etc. — replace illegal chars with "x" (not "_")
+        # to avoid collisions with the "__" separator.
+        # self._tool.name retains the original for server-side calls.
+        sanitized_tool = re.sub(r"[^a-zA-Z0-9_-]", "x", tool.name)
+        self.name = f"mcp__{mcp_name}__{sanitized_tool}"
+        if sanitized_tool != tool.name:
+            logger.debug(
+                "MCP tool name sanitized: '%s' -> '%s'.",
+                tool.name,
+                self.name,
+            )
+
+        self.description = tool.description or ""
+
+        # Preserve the full inputSchema (including $defs, anyOf, oneOf, etc.)
+        # rather than only copying "properties" and "required", which would
+        # silently drop any nested type definitions that the LLM needs to
+        # resolve $ref pointers.
+        _schema = dict(tool.inputSchema) if tool.inputSchema else {}
+        _schema.setdefault("type", "object")
+        _schema.setdefault("properties", {})
+        _schema.setdefault("required", [])
+        self.input_schema = _schema
+
+        # By default
+        self.is_concurrency_safe = False
+        self.is_external_tool = False
+
+        # Extract is_read_only from MCP tool annotations
+        self.is_read_only = False
+        if tool.annotations and hasattr(tool.annotations, "readOnlyHint"):
+            self.is_read_only = tool.annotations.readOnlyHint or False
+
+        # Store MCP tool and connection info
+        self._tool = tool
+        self._client_gen = client_gen
+        self._session = session
+
+        if timeout:
+            self._timeout = timedelta(seconds=timeout)
+        else:
+            self._timeout = None
+
+        # Validate that either client_gen or session is provided
+        if (client_gen is None and session is None) or (
+            client_gen is not None and session is not None
+        ):
+            raise ValueError(
+                "Either client_gen or session must be provided, but not both.",
+            )
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the MCP tool usage.
+
+        Default implementation allows all operations.
+
+        Returns:
+            `PermissionDecision`:
+                Permission decision (default: ask for confirmation).
+        """
+        if self.is_read_only:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message="This is a read-only MCP tool. Allowing execution.",
+            )
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="MCP tools must be explicitly allowed by the user.",
+        )
+
+    async def call(
+        self,
+        **kwargs: Any,
+    ) -> ToolChunk:
+        """Invoke the MCP tool and convert the result to ToolChunk.
+
+        Args:
+            **kwargs: Arguments to pass to the MCP tool.
+
+        Returns:
+            `ToolChunk`: The converted tool execution result.
+        """
+
+        # Call the MCP tool
+        if self._client_gen:
+            # Stateless client: create temporary session
+            async with self._client_gen() as cli:
+                read_stream, write_stream = cli[0], cli[1]
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+                    result = await session.call_tool(
+                        self._tool.name,
+                        arguments=kwargs,
+                        read_timeout_seconds=self._timeout,
+                    )
+        else:
+            # Stateful client: use existing session
+            result = await self._session.call_tool(
+                self._tool.name,
+                arguments=kwargs,
+                read_timeout_seconds=self._timeout,
+            )
+
+        # Convert MCP result to AgentScope blocks
+        return ToolChunk(
+            content=self._convert_mcp_content_to_blocks(result.content),
+            state=ToolResultState.ERROR
+            if result.isError
+            else ToolResultState.RUNNING,
+        )
+
+    @staticmethod
+    def _convert_mcp_content_to_blocks(
+        mcp_content_blocks: list,
+    ) -> list[TextBlock | DataBlock]:
+        """Convert MCP content to AgentScope blocks.
+
+        Args:
+            mcp_content_blocks (`list`):
+                The MCP content blocks to convert.
+
+        Returns:
+            `list[TextBlock | DataBlock]`: Converted AgentScope blocks.
+        """
+
+        as_content = []
+        for content in mcp_content_blocks:
+            if isinstance(content, mcp.types.TextContent):
+                as_content.append(TextBlock(text=content.text))
+            elif isinstance(
+                content,
+                (mcp.types.ImageContent, mcp.types.AudioContent),
+            ):
+                as_content.append(
+                    DataBlock(
+                        source=Base64Source(
+                            type="base64",
+                            media_type=content.mimeType,
+                            data=content.data,
+                        ),
+                    ),
+                )
+
+            elif isinstance(content, mcp.types.EmbeddedResource):
+                if isinstance(
+                    content.resource,
+                    mcp.types.TextResourceContents,
+                ):
+                    as_content.append(
+                        TextBlock(
+                            text=content.resource.model_dump_json(indent=2),
+                        ),
+                    )
+                else:
+                    logger.error(
+                        "Unsupported EmbeddedResource content type: %s. "
+                        "Skipping this content.",
+                        type(content.resource),
+                    )
+
+            elif isinstance(content, mcp.types.ResourceContents):
+                as_content.append(
+                    DataBlock(
+                        source=URLSource(
+                            media_type=content.mimeType,
+                            url=content.uri,
+                        ),
+                    ),
+                )
+
+            else:
+                logger.warning(
+                    "Unsupported content type: %s. Skipping this content.",
+                    type(content),
+                )
+        return as_content

src/agentscope/tool/_base.py

@@ -0,0 +1,451 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-argument
+"""The tool protocol in agentscope."""
+import inspect
+import os
+from abc import abstractmethod, ABC
+from pathlib import Path
+from typing import AsyncGenerator, Any, Callable, List
+
+from pydantic import BaseModel
+
+from ._constants import DEFAULT_DANGEROUS_FILES, DEFAULT_DANGEROUS_DIRECTORIES
+from ..permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionRule,
+    PermissionBehavior,
+)
+from ._response import ToolChunk
+from ._utils import _remove_title_field
+
+
+class ParamsBase(BaseModel):
+    """A base class for tool parameters that remove the title field from the
+    exported JSON schema.
+    """
+
+    @classmethod
+    def model_json_schema(cls, *args: Any, **kwargs: Any) -> dict:
+        """An override implementation to remove the title field from the
+        exported schema.
+        """
+        return _remove_title_field(super().model_json_schema(*args, **kwargs))
+
+
+class ToolMiddlewareBase(ABC):
+    """Base class for tool middlewares.
+
+    A tool middleware wraps the execution of a tool in an onion fashion: the
+    first registered middleware is the outermost layer and runs its pre-logic
+    before any inner layer, then its post-logic after all inner layers have
+    completed. Subclass this and implement :meth:`on_tool_call` — the signature
+    is already spelled out, so second-party developers only need to fill in the
+    body without reasoning about the wrapping protocol.
+
+    Streaming and non-streaming tools are unified: ``next_handler`` always
+    returns an async generator, so a middleware never needs to know whether the
+    underlying tool yields a stream of chunks or returns a single chunk.
+
+    Example:
+        ```python
+        class LoggingMiddleware(ToolMiddlewareBase):
+            async def on_tool_call(self, tool, input_kwargs, next_handler):
+                print(f"Calling {tool.name} with {input_kwargs}")
+                async for chunk in next_handler(**input_kwargs):
+                    yield chunk
+                print(f"Finished {tool.name}")
+
+        tool = MyTool(middlewares=[LoggingMiddleware()])
+        ```
+    """
+
+    @abstractmethod
+    async def on_tool_call(
+        self,
+        tool: "ToolBase",
+        input_kwargs: dict[str, Any],
+        next_handler: Callable[..., AsyncGenerator[ToolChunk, None]],
+    ) -> AsyncGenerator[ToolChunk, None]:
+        """Intercept a single tool invocation.
+
+        Add pre-/post-logic around ``next_handler``, rewrite the tool inputs by
+        passing modified keyword arguments to ``next_handler``, or transform
+        the yielded chunks.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being invoked.
+            input_kwargs (`dict[str, Any]`):
+                The tool's input arguments for this invocation. Pass them on
+                via ``next_handler(**input_kwargs)``; mutate or replace them to
+                change what the inner layers and the tool itself receive.
+            next_handler (`Callable[..., AsyncGenerator[ToolChunk, None]]`):
+                Call it as ``next_handler(**input_kwargs)`` to run the next
+                layer. It always returns an async generator, regardless of
+                whether the underlying tool is streaming or not.
+
+        Yields:
+            `ToolChunk`:
+                The chunks produced by this tool invocation.
+        """
+
+
+class ToolBase(ABC):
+    """The tool protocol."""
+
+    name: str
+    """The name presented to the agent."""
+    description: str
+    """The agent-oriented tool description."""
+    input_schema: dict[str, Any]
+    """The input schema of the tool, following JSON schema format."""
+    is_concurrency_safe: bool
+    """If this tool is concurrency safe."""
+    is_read_only: bool
+    """If this tool is read-only, which will be used in the permission
+    checking."""
+    is_external_tool: bool = False
+    """If this tool is an external tool, which doesn't need to implement the
+    __call__ method and the agent will yield the external tool call event."""
+    is_state_injected: bool = False
+    """If this tool requires agent state to be injected when called. If `True`,
+    the state will be injected by an argument named `_agent_state`. Note your
+    tool should be able to accept such argument.
+    """
+    is_mcp: bool = False
+    """If this tool is an MCP tool, which will be used in the permission"""
+    mcp_name: str | None = None
+    """The name of the MCP server this tool belongs to, which is required if
+    this tool is an MCP tool."""
+
+    # Class attributes for dangerous path checking
+    dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES
+    """List of dangerous files that should be protected from auto-editing."""
+    dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES
+    """List of dangerous directories that should be protected from
+    auto-editing."""
+
+    def __init__(
+        self,
+        middlewares: List["ToolMiddlewareBase"] | None = None,
+    ) -> None:
+        """Initialize the tool with optional middlewares.
+
+        Args:
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                A list of :class:`ToolMiddlewareBase` instances wrapping the
+                tool execution in an onion fashion. Defaults to an empty list.
+        """
+        self._middlewares: List["ToolMiddlewareBase"] = (
+            middlewares if middlewares is not None else []
+        )
+
+    async def call(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> ToolChunk | AsyncGenerator[ToolChunk, None]:
+        """Execute the tool logic.
+
+        This is the new override point for tool implementations.
+        Subclasses should override this method instead of
+        :meth:`__call__`.  The base implementation raises
+        :exc:`NotImplementedError` for non-external tools and
+        :exc:`RuntimeError` for external tools.
+
+        Args:
+            **kwargs: Tool input arguments.
+
+        Returns:
+            `ToolChunk | AsyncGenerator[ToolChunk, None]`:
+                A single :class:`~agentscope.tool.ToolChunk` or an
+                async generator that yields them.
+        """
+        if not self.is_external_tool:
+            raise NotImplementedError(
+                f"{self.__class__.__name__} does not implement call",
+            )
+
+        raise RuntimeError(
+            f"{self.__class__.__name__} is an external tool and should not "
+            f"be called directly",
+        )
+
+    async def __call__(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> ToolChunk | AsyncGenerator[ToolChunk, None]:
+        """Invoke the tool, layering any registered middlewares around
+        :meth:`call`.
+
+        Tools are always invoked with keyword arguments only. ``*args`` is
+        accepted in the signature solely to stay Liskov-compatible with
+        subclasses that override ``__call__`` with their own positional
+        parameters; any positional argument actually passed here is rejected
+        (raising :exc:`TypeError`) so it fails loudly instead of being silently
+        dropped.
+
+        Middlewares are applied in an onion fashion: the first registered
+        middleware is the outermost layer and runs its pre-logic before
+        any inner layers, then its post-logic after all inner layers
+        have completed.
+        """
+        if args:
+            raise TypeError(
+                f"{type(self).__name__} must be called with keyword arguments "
+                f"only, but got {len(args)} positional argument(s).",
+            )
+        # ``getattr`` with a default so the no-middleware path keeps working
+        # even if a subclass overrides ``__init__`` without calling
+        # ``super().__init__()``.
+        middlewares = getattr(self, "_middlewares", [])
+        if not middlewares:
+            if inspect.isasyncgenfunction(self.call):
+                return self.call(**kwargs)
+            return await self.call(**kwargs)
+
+        async def execute_chain(
+            index: int = 0,
+            **chain_kwargs: Any,
+        ) -> AsyncGenerator[ToolChunk, None]:
+            """Execute the tool middleware chain."""
+            if index >= len(middlewares):
+                # Innermost layer: run the tool's own ``call``. ``call`` is
+                # always async but comes in two shapes — an async generator
+                # function (e.g. ``Bash``) or a coroutine returning a single
+                # ``ToolChunk`` / an async generator (e.g. ``FunctionTool``).
+                # Normalize both into a single stream so middlewares never have
+                # to distinguish them.
+                if inspect.isasyncgenfunction(self.call):
+                    async for chunk in self.call(**chain_kwargs):
+                        yield chunk
+                else:
+                    result = await self.call(**chain_kwargs)
+                    if isinstance(result, AsyncGenerator):
+                        async for chunk in result:
+                            yield chunk
+                    else:
+                        yield result
+            else:
+                mw = middlewares[index]
+                input_kwargs = dict(chain_kwargs)
+
+                async def next_handler(
+                    **kw: Any,
+                ) -> AsyncGenerator[ToolChunk, None]:
+                    async for chunk in execute_chain(index + 1, **kw):
+                        yield chunk
+
+                async for chunk in mw.on_tool_call(
+                    tool=self,
+                    input_kwargs=input_kwargs,
+                    next_handler=next_handler,
+                ):
+                    yield chunk
+
+        return execute_chain(**kwargs)
+
+    @abstractmethod
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+
+    async def check_read_only(
+        self,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Decide whether this specific invocation is read-only.
+
+        Returns the static :attr:`is_read_only` attribute by default.
+        Subclasses with input-dependent semantics (e.g. ``Bash``) should
+        override this to inspect ``tool_input`` — for example, ``Bash`` is
+        statically marked as not read-only but ``ls -a`` is in fact read-only.
+
+        Should be cheap — the permission engine may call this before the
+        full :meth:`check_permissions` flow.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data for this invocation.
+
+        Returns:
+            `bool`:
+                ``True`` if this invocation is read-only, ``False`` otherwise.
+        """
+        return self.is_read_only
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the tool input.
+
+        .. note:: This is an optional method. A rule with no content (``None``)
+        is a tool-name-level rule that matches every invocation; a rule
+        with content requires the tool to override this method with its
+        own matching logic, otherwise it returns ``False``.
+
+        This means:
+        - ``_FunctionTool`` and ``MCPTool`` (which do not override this)
+          can still be controlled at the tool-name level via rules like
+          ``{"tool_name": "my_tool", "rule_content": None}``.
+        - Specific tools (Bash, Read, Write, Edit, Glob, Grep) override
+          this method to support fine-grained pattern matching.
+
+        Args:
+            rule_content (`str | None`):
+                The rule pattern to match. ``None`` means "match all
+                invocations of this tool" (tool-name-level rule).
+            tool_input (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `bool`:
+                True if the rule matches, False otherwise
+        """
+        # None rule_content = tool-name-level rule, matches everything
+        return rule_content is None
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the tool input.
+
+        .. note:: Suggest a single tool-name-level rule (``rule_content=None``)
+        that allows all invocations of this tool. Tools can override this to
+        provide finer-grained suggestions.
+
+        For example:
+        - File tools (Read/Write/Edit): suggest a glob pattern covering the
+          parent directory (e.g., "src/main.py" -> "src/**")
+        - Bash: suggest command prefix patterns (e.g., "git commit -m 'xxx'"
+          -> "git commit:*")
+        - Grep/Glob: suggest patterns based on search paths
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `List[PermissionRule]`:
+                List of suggested permission rules (usually 1, max 5 for
+                compound operations)
+        """
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=None,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    def _path_in_allowed_working_path(
+        self,
+        file_path: str,
+        context: PermissionContext,
+    ) -> bool:
+        """Check if a file path is within any allowed working directory.
+
+        A "working directory" is the process's current directory plus any
+        entries in :attr:`PermissionContext.working_directories`. Paths
+        are compared via :func:`os.path.realpath` so that aliases like
+        macOS's ``/tmp`` → ``/private/tmp`` and symlinked working
+        directories compare equal on both sides.
+
+        Used by tools that conditionally auto-allow file operations in
+        :attr:`PermissionMode.ACCEPT_EDITS` (e.g. Write, Edit, and the
+        filesystem-command branch of Bash).
+
+        Args:
+            file_path (`str`):
+                The file path to check.
+            context (`PermissionContext`):
+                The permission context containing the working directories.
+
+        Returns:
+            `bool`:
+                True if ``file_path`` is within any allowed working
+                directory.
+        """
+        current_dir = os.getcwd()
+        additional_dirs = list(context.working_directories.keys())
+        all_working_dirs = [current_dir] + additional_dirs
+
+        abs_file_path = os.path.realpath(os.path.expanduser(file_path))
+
+        for working_dir in all_working_dirs:
+            abs_working_dir = os.path.realpath(
+                os.path.expanduser(working_dir),
+            )
+            try:
+                os.path.relpath(abs_file_path, abs_working_dir)
+                if (
+                    abs_file_path.startswith(abs_working_dir + os.sep)
+                    or abs_file_path == abs_working_dir
+                ):
+                    return True
+            except ValueError:
+                # On Windows, relpath raises ValueError if paths are on
+                # different drives.
+                continue
+
+        return False
+
+    def _is_dangerous_path(self, file_path: str) -> bool:
+        """Check if a file path is dangerous (sensitive file or directory).
+
+        A path is considered dangerous if:
+        1. The filename matches a dangerous file (e.g., .bashrc, .gitconfig)
+        2. Any path segment matches a dangerous directory (e.g., .git, .ssh)
+
+        Case-insensitive matching is used to prevent bypasses on
+        case-insensitive filesystems (macOS, Windows).
+
+        Args:
+            file_path (`str`):
+                The file path to check
+
+        Returns:
+            `bool`:
+                True if the path is dangerous and should require explicit
+                permission
+
+        Example:
+            >>> self._is_dangerous_path("/home/user/.bashrc")
+            True
+            >>> self._is_dangerous_path("/home/user/.git/config")
+            True
+            >>> self._is_dangerous_path("/home/user/project/main.py")
+            False
+        """
+
+        # Normalize path
+        abs_path = os.path.abspath(os.path.expanduser(file_path))
+
+        # Split path into segments
+        path_parts = Path(abs_path).parts
+        path_parts_lower = [p.lower() for p in path_parts]
+
+        # Check if filename matches dangerous files (case-insensitive)
+        filename = os.path.basename(abs_path)
+        filename_lower = filename.lower()
+        for dangerous_file in self.dangerous_files:
+            if filename_lower == dangerous_file.lower():
+                return True
+
+        # Check if any path segment matches dangerous directories
+        # (case-insensitive)
+        for dangerous_dir in self.dangerous_directories:
+            dangerous_dir_lower = dangerous_dir.lower()
+            if dangerous_dir_lower in path_parts_lower:
+                return True
+
+        return False

src/agentscope/tool/_builtin/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""The builtin tools in agentscope."""
+
+from ._backend import BackendBase, ExecResult, LocalBackend
+from ._bash import Bash
+from ._edit import Edit
+from ._glob import Glob
+from ._grep import Grep
+from ._meta import ResetTools
+from ._read import Read
+from ._skill import SkillViewer
+from ._write import Write
+
+__all__ = [
+    "ResetTools",
+    "SkillViewer",
+    "Bash",
+    "Edit",
+    "Glob",
+    "Grep",
+    "Read",
+    "Write",
+    "BackendBase",
+    "LocalBackend",
+    "ExecResult",
+]

src/agentscope/tool/_builtin/_backend.py

@@ -0,0 +1,733 @@
+# -*- coding: utf-8 -*-
+"""Backend abstraction for builtin tools.
+
+Provides a :class:`BackendBase` abstract base class that captures the
+core I/O primitives shared across all six builtin tools (Bash, Read,
+Write, Edit, Grep, Glob).
+
+Every backend implements exactly **three** abstract primitives whose
+mechanism genuinely differs per environment:
+
+* :meth:`BackendBase.exec_shell` — run a program from an argv list
+  (no shell; callers needing shell features wrap with ``sh -c``).
+* :meth:`BackendBase.read_file` — read raw bytes.
+* :meth:`BackendBase.write_file` — write raw bytes.
+
+All remaining filesystem operations (``file_exists``, ``is_dir``,
+``list_dir``, ``stat_mtime``, ``delete_path``) are derived on the base
+class from ``exec_shell`` and work out-of-the-box for any remote
+backend.  A backend that has a cheaper native path (e.g.
+:class:`LocalBackend` using ``os.*``) simply overrides them.
+
+Concrete implementations:
+
+* :class:`LocalBackend` — default; uses ``asyncio`` subprocesses,
+  ``aiofiles``, and ``os.*`` for host-local I/O.  Injected automatically
+  when no explicit backend is given.
+* ``DockerBackend`` — uses ``aiodocker`` exec / archive APIs.
+* ``E2BBackend`` — uses the E2B SDK ``commands`` / ``files`` APIs.
+
+By accepting a ``BackendBase`` parameter, each builtin tool can
+operate identically in local, Docker, and E2B workspaces without any
+workspace-specific branching inside the tool code itself.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import posixpath
+import shlex
+import shutil
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Any
+
+import aiofiles
+
+# ── data class ─────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class ExecResult:
+    """Result of running a shell command via a backend.
+
+    Attributes:
+        exit_code: Process exit code.  ``-1`` conventionally indicates
+            an internal failure (timeout, connection error, …).
+        stdout: Raw bytes captured from standard output.
+        stderr: Raw bytes captured from standard error.
+    """
+
+    exit_code: int
+    stdout: bytes
+    stderr: bytes
+
+    def ok(self) -> bool:
+        """Whether the command exited successfully.
+
+        Returns:
+            `bool`:
+                ``True`` iff the command exited with code ``0``.
+        """
+        return self.exit_code == 0
+
+
+# ── helpers ────────────────────────────────────────────────────────────
+
+
+def _normalize_newlines(text: str) -> str:
+    """Normalize Windows/old-Mac line endings to ``\\n``.
+
+    Converts ``\\r\\n`` (Windows) and lone ``\\r`` (classic Mac) to a
+    single ``\\n``.  Builtin tools read files as raw bytes (so binary
+    payloads survive intact); when the bytes are decoded as text for
+    line-based caching, editing, or matching, the line endings must be
+    normalized so that content written on Windows behaves identically to
+    content written on POSIX.
+
+    Args:
+        text (`str`):
+            Decoded file contents.
+
+    Returns:
+        `str`:
+            The text with all line endings collapsed to ``\\n``.
+    """
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+# ── base class ─────────────────────────────────────────────────────────
+
+
+class BackendBase(ABC):
+    """Filesystem + subprocess interface consumed by builtin tools.
+
+    Subclasses must implement three abstract primitives — ``exec_shell``,
+    ``read_file``, and ``write_file`` — which are the only operations
+    whose mechanism genuinely differs per environment.  The remaining
+    filesystem helpers are implemented here on top of ``exec_shell`` and
+    work for any backend whose shell is POSIX-like; a backend with a
+    cheaper native path may override them (see :class:`LocalBackend`).
+    """
+
+    #: Path-manipulation module whose semantics match the backend's
+    #: environment.  Used by :meth:`join_path`, :meth:`dirname`,
+    #: :meth:`isabs`, :meth:`normpath`, and :meth:`abspath` to ensure
+    #: correct behavior when the host OS and the backend OS differ
+    #: (e.g. a Windows host driving a Linux Docker container).
+    #:
+    #: Defaults to :mod:`posixpath`, which is correct for any backend
+    #: whose environment is Linux/macOS (Docker, E2B, …).  Subclasses
+    #: targeting a different environment override this attribute, e.g.
+    #: :class:`LocalBackend` sets it to :mod:`os.path`, and a future
+    #: Windows-container backend would set it to :mod:`ntpath`.
+    #:
+    #: .. important::
+    #:
+    #:     Only **pure string operations** on this module are safe to
+    #:     call (``join``, ``split``, ``dirname``, ``basename``,
+    #:     ``normpath``, ``isabs``, ``splitext``, ``splitdrive``, …).
+    #:
+    #:     Do **not** call functions that touch the filesystem or
+    #:     environment variables — ``exists``, ``isfile``, ``isdir``,
+    #:     ``getmtime``, ``realpath``, ``expanduser``, ``expandvars``,
+    #:     and parameterless ``abspath`` — because those read the
+    #:     **host** process's filesystem / ``$HOME`` / ``cwd``, which
+    #:     is meaningless (and a silent bug) for remote backends.  Use
+    #:     the async I/O methods on the backend instead
+    #:     (:meth:`file_exists`, :meth:`is_dir`, :meth:`stat_mtime`,
+    #:     …) or the :meth:`abspath` wrapper below, which requires an
+    #:     explicit ``cwd`` argument.
+    _path_module: ModuleType = posixpath
+
+    # ── path manipulation helpers (pure string ops) ────────────────
+
+    def join_path(self, path: str, *paths: str) -> str:
+        """Join one or more path components using the backend's separator.
+
+        Args:
+            path (`str`):
+                The first path component.
+            *paths (`str`):
+                Additional components to join onto ``path``.
+
+        Returns:
+            `str`:
+                The joined path, using the backend environment's path
+                separator.
+        """
+        return self._path_module.join(path, *paths)
+
+    def dirname(self, path: str) -> str:
+        """Return the directory component of ``path``.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+
+        Returns:
+            `str`:
+                Everything up to (but not including) the last path
+                separator. Empty string if ``path`` has no separator.
+        """
+        return self._path_module.dirname(path)
+
+    def isabs(self, path: str) -> bool:
+        """Return ``True`` if ``path`` is absolute in the backend.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+
+        Returns:
+            `bool`:
+                ``True`` iff ``path`` is absolute under the backend
+                environment's path semantics.
+        """
+        return self._path_module.isabs(path)
+
+    def normpath(self, path: str) -> str:
+        """Normalize ``path`` (collapse ``..``, ``.``, duplicate seps).
+
+        Pure string operation — does not touch the filesystem.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+
+        Returns:
+            `str`:
+                The normalized path.
+        """
+        return self._path_module.normpath(path)
+
+    def abspath(self, path: str, *, cwd: str) -> str:
+        """Return an absolute, normalized version of ``path``.
+
+        Unlike :func:`os.path.abspath`, this helper **never** reads
+        the host process's working directory: when ``path`` is
+        relative it is joined with the explicitly supplied ``cwd``,
+        which must itself be a path that is meaningful inside the
+        backend's environment.  This avoids the silent bug where the
+        host's ``os.getcwd()`` leaks into paths that will actually be
+        used on a remote backend.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+            cwd (`str`):
+                Directory to resolve a relative ``path`` against.
+                Ignored when ``path`` is already absolute.
+
+        Returns:
+            `str`:
+                An absolute, normalized path.
+        """
+        if self._path_module.isabs(path):
+            return self._path_module.normpath(path)
+        return self._path_module.normpath(
+            self._path_module.join(cwd, path),
+        )
+
+    # ── abstract primitives ────────────────────────────────────────
+
+    @abstractmethod
+    async def exec_shell(
+        self,
+        command: list[str],
+        *,
+        cwd: str | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a program directly from an argument vector.
+
+        *command* is an executable followed by its arguments — it is
+        **not** passed through a shell, so callers never have to quote
+        or escape arguments and there is no platform-specific quoting
+        bug. This makes the primitive portable to Windows, where POSIX
+        single-quote escaping (``shlex.quote``) is not understood by
+        ``cmd.exe``.
+
+        Callers that genuinely need shell features (pipes, redirects,
+        ``&&``) must wrap their command line explicitly, e.g.
+        ``["/bin/sh", "-c", command_line]``.
+
+        Args:
+            command (`list[str]`):
+                Executable path/name followed by its arguments.
+            cwd (`str | None`, optional):
+                Working directory to run the command in. When ``None``
+                the backend's default working directory is used.
+            timeout (`float | None`, optional):
+                Maximum number of seconds to wait. When ``None`` the
+                call waits indefinitely. On timeout the result carries
+                an ``exit_code`` of ``-1``.
+
+        Returns:
+            `ExecResult`:
+                The captured exit code, stdout, and stderr.
+        """
+
+    @abstractmethod
+    async def read_file(self, path: str) -> bytes:
+        """Read the full contents of ``path`` as raw bytes.
+
+        Args:
+            path (`str`):
+                Path to the file inside the backend's environment.
+
+        Returns:
+            `bytes`:
+                The raw file contents.
+        """
+
+    @abstractmethod
+    async def write_file(self, path: str, data: bytes) -> None:
+        """Write ``data`` to ``path``, creating parent directories.
+
+        Args:
+            path (`str`):
+                Destination path inside the backend's environment.
+            data (`bytes`):
+                The raw bytes to write.
+        """
+
+    # ── derived filesystem ops (shell-based defaults) ──────────────
+
+    async def getcwd(self) -> str:
+        """Return the backend environment's current working directory.
+
+        This is the directory that bare ``exec_shell`` invocations
+        (those with ``cwd=None``) execute in.  Tools should call this
+        — instead of :func:`os.getcwd` — whenever they need a default
+        path that is meaningful inside the backend, because the host
+        process's cwd is meaningless for remote backends
+        (Docker / E2B).
+
+        The default implementation runs ``pwd`` via :meth:`exec_shell`,
+        which works for any POSIX-like backend.  Backends with cheaper
+        native access (e.g. :class:`LocalBackend`, or remote backends
+        that already track their workdir) should override it.
+
+        Returns:
+            `str`:
+                The backend's current working directory.
+        """
+        result = await self.exec_shell(["pwd"])
+        return result.stdout.decode("utf-8", errors="replace").strip()
+
+    async def expanduser(self, path: str) -> str:
+        """Expand a leading ``~`` / ``~/`` to the backend's home directory.
+
+        Tools should call this — instead of :func:`os.path.expanduser`
+        — whenever they need to expand ``~`` in a path that lives
+        inside the backend's environment, because the host process's
+        ``$HOME`` is meaningless for remote backends.
+
+        The default implementation queries ``$HOME`` via
+        :meth:`exec_shell` (POSIX-only).  Only the leading ``~`` /
+        ``~/foo`` form is expanded; ``~user/...`` is not supported by
+        the default and is returned unchanged.  Backends with cheaper
+        native access should override (e.g. :class:`LocalBackend`).
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment, possibly
+                starting with ``~``.
+
+        Returns:
+            `str`:
+                ``path`` with a leading ``~`` / ``~/`` expanded.  If
+                ``path`` does not start with ``~``, or starts with
+                ``~user`` (unsupported), it is returned unchanged.
+        """
+        if not path or path[0] != "~":
+            return path
+        # ``~user/...`` form — not supported by the default impl.
+        if len(path) > 1 and path[1] not in ("/", self._path_module.sep):
+            return path
+        result = await self.exec_shell(["printenv", "HOME"])
+        home = result.stdout.decode("utf-8", errors="replace").strip()
+        if not home:
+            return path
+        return home + path[1:]
+
+    async def file_exists(self, path: str) -> bool:
+        """Return ``True`` if ``path`` exists (file or directory).
+
+        Args:
+            path (`str`):
+                Path to test inside the backend's environment.
+
+        Returns:
+            `bool`:
+                ``True`` if the path exists, ``False`` otherwise.
+        """
+        result = await self.exec_shell(["test", "-e", path])
+        return result.ok()
+
+    async def is_dir(self, path: str) -> bool:
+        """Return ``True`` if ``path`` is an existing directory.
+
+        Args:
+            path (`str`):
+                Path to test inside the backend's environment.
+
+        Returns:
+            `bool`:
+                ``True`` if the path is an existing directory.
+        """
+        result = await self.exec_shell(["test", "-d", path])
+        return result.ok()
+
+    async def list_dir(
+        self,
+        path: str,
+        *,
+        recursive: bool = False,
+    ) -> list[str]:
+        """List entries under ``path``.
+
+        Output is NUL-delimited (``find -print0`` / ``-printf '%f\\0'``)
+        and split on ``\\0`` so that file names containing spaces or
+        newlines are handled correctly.  ``find -printf`` is a GNU
+        extension; backends running on non-GNU userlands should override
+        this method.
+
+        Args:
+            path (`str`):
+                Directory to list inside the backend's environment.
+            recursive (`bool`, optional):
+                When ``True``, return all files underneath ``path`` as
+                paths (like ``find path -type f``). When ``False``
+                (default), return the immediate children's base names
+                (like ``os.listdir``).
+
+        Returns:
+            `list[str]`:
+                The matched entries, or an empty list if ``path`` does
+                not exist or cannot be listed.
+        """
+        if recursive:
+            command = ["find", path, "-type", "f", "-print0"]
+        else:
+            command = [
+                "find",
+                path,
+                "-mindepth",
+                "1",
+                "-maxdepth",
+                "1",
+                "-printf",
+                "%f\\0",
+            ]
+        result = await self.exec_shell(command)
+        if not result.ok():
+            return []
+        return [
+            part.decode("utf-8", errors="surrogateescape")
+            for part in result.stdout.split(b"\0")
+            if part
+        ]
+
+    async def stat_mtime(self, path: str) -> float | None:
+        """Return the modification time of ``path``, or ``None``.
+
+        Tries GNU ``stat -c %Y`` first and falls back to BSD
+        ``stat -f %m`` so the same call works across coreutils and
+        BSD/macOS userlands.  The two attempts are combined with ``||``,
+        so this default wraps a ``sh -c`` script; backends without a
+        POSIX shell (e.g. :class:`LocalBackend`) override it.
+
+        Args:
+            path (`str`):
+                Path to stat inside the backend's environment.
+
+        Returns:
+            `float | None`:
+                The modification time as a POSIX timestamp, or ``None``
+                if the path does not exist or cannot be stat'd.
+        """
+        quoted = shlex.quote(path)
+        script = (
+            f"stat -c %Y {quoted} 2>/dev/null || "
+            f"stat -f %m {quoted} 2>/dev/null"
+        )
+        result = await self.exec_shell(["sh", "-c", script])
+        if not result.ok():
+            return None
+        try:
+            return float(
+                result.stdout.decode("utf-8", errors="replace").strip(),
+            )
+        except ValueError:
+            return None
+
+    async def delete_path(self, path: str) -> None:
+        """Delete ``path`` (file or directory tree).
+
+        If ``path`` does not exist the call is a silent no-op (like
+        ``rm -rf``).  Handles both files and directories (recursively).
+
+        Args:
+            path (`str`):
+                Path to delete inside the backend's environment.
+        """
+        await self.exec_shell(["rm", "-rf", path])
+
+
+# ── local backend ──────────────────────────────────────────────────────
+
+
+def _subprocess_creation_kwargs() -> dict[str, Any]:
+    """Return platform-specific subprocess creation options.
+
+    Returns:
+        `dict[str, Any]`:
+            Extra keyword arguments for ``create_subprocess_shell``.
+            Empty on POSIX; on Windows it sets ``creationflags`` to
+            suppress a console window.
+    """
+    if os.name != "nt":
+        return {}
+
+    import subprocess
+
+    return {
+        "creationflags": getattr(
+            subprocess,
+            "CREATE_NO_WINDOW",
+            0x08000000,
+        ),
+    }
+
+
+class LocalBackend(BackendBase):
+    """Host-local :class:`BackendBase` implementation.
+
+    Uses ``asyncio.create_subprocess_exec``, ``aiofiles``, and the
+    ``os`` module.  This is the default backend injected when no
+    explicit one is given to a builtin tool.  Commands are spawned
+    directly from their argument vector (no shell), which avoids the
+    POSIX-vs-``cmd.exe`` quoting mismatch and makes the backend work on
+    Windows.  The derived filesystem helpers are overridden with native
+    ``os.*`` calls — faster and more robust than shelling out, and
+    portable to Windows where ``test`` / ``find`` / ``stat`` are
+    unavailable.
+    """
+
+    # Use the host OS's path semantics (Windows or POSIX) instead of
+    # the base class default (``posixpath``), so path helpers behave
+    # correctly when running on a Windows host.
+    _path_module = os.path
+
+    async def exec_shell(
+        self,
+        command: list[str],
+        *,
+        cwd: str | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a program via ``asyncio.create_subprocess_exec``.
+
+        The program is spawned directly from *command* without an
+        intervening shell, so no argument quoting is required and the
+        same code path works on POSIX and Windows.
+
+        Args:
+            command (`list[str]`):
+                Executable path/name followed by its arguments.
+            cwd (`str | None`, optional):
+                Working directory for the subprocess. When ``None`` the
+                current process working directory is used.
+            timeout (`float | None`, optional):
+                Maximum number of seconds to wait before the process is
+                killed and an ``exit_code`` of ``-1`` is returned.
+
+        Returns:
+            `ExecResult`:
+                The captured exit code, stdout, and stderr. If the
+                executable cannot be found or spawned, ``exit_code`` is
+                ``127`` (matching a shell's "command not found"), with
+                the OS error message on stderr.
+        """
+        kwargs = _subprocess_creation_kwargs()
+        if cwd is not None:
+            kwargs["cwd"] = cwd
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                **kwargs,
+            )
+        except (FileNotFoundError, NotADirectoryError, OSError) as exc:
+            # The executable could not be found or spawned. A shell would
+            # have returned 127 ("command not found"); mirror that so
+            # callers see a normal non-zero ExecResult instead of an
+            # exception.
+            return ExecResult(
+                exit_code=127,
+                stdout=b"",
+                stderr=str(exc).encode("utf-8"),
+            )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.communicate()
+            return ExecResult(exit_code=-1, stdout=b"", stderr=b"timed out")
+
+        return ExecResult(
+            exit_code=process.returncode or 0,
+            stdout=stdout,
+            stderr=stderr,
+        )
+
+    async def read_file(self, path: str) -> bytes:
+        """Read a local file as raw bytes.
+
+        Args:
+            path (`str`):
+                Path to the local file.
+
+        Returns:
+            `bytes`:
+                The raw file contents.
+        """
+        async with aiofiles.open(path, mode="rb") as f:
+            return await f.read()
+
+    async def write_file(self, path: str, data: bytes) -> None:
+        """Write *data* to a local file, creating parent dirs.
+
+        Args:
+            path (`str`):
+                Destination path on the local filesystem.
+            data (`bytes`):
+                The raw bytes to write.
+        """
+        parent = os.path.dirname(path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        async with aiofiles.open(path, mode="wb") as f:
+            await f.write(data)
+
+    async def getcwd(self) -> str:
+        """Return the host process's current working directory.
+
+        Returns:
+            `str`:
+                ``os.getcwd()`` — avoids spawning a ``pwd`` subprocess.
+        """
+        return os.getcwd()
+
+    async def expanduser(self, path: str) -> str:
+        """Expand ``~`` using the host process's ``$HOME``.
+
+        Args:
+            path (`str`):
+                A local path, possibly starting with ``~``.
+
+        Returns:
+            `str`:
+                ``os.path.expanduser(path)`` — avoids spawning a
+                subprocess.
+        """
+        return os.path.expanduser(path)
+
+    async def file_exists(self, path: str) -> bool:
+        """Check if a local path exists.
+
+        Args:
+            path (`str`):
+                Path to test.
+
+        Returns:
+            `bool`:
+                ``True`` if the path exists.
+        """
+        return os.path.exists(path)
+
+    async def is_dir(self, path: str) -> bool:
+        """Check if a local path is a directory.
+
+        Args:
+            path (`str`):
+                Path to test.
+
+        Returns:
+            `bool`:
+                ``True`` if the path is an existing directory.
+        """
+        return os.path.isdir(path)
+
+    async def list_dir(
+        self,
+        path: str,
+        *,
+        recursive: bool = False,
+    ) -> list[str]:
+        """List local directory entries.
+
+        Mirrors the base contract using native ``os`` calls.
+
+        Args:
+            path (`str`):
+                Directory to list.
+            recursive (`bool`, optional):
+                When ``True``, return file paths underneath ``path``
+                (``os.walk``). When ``False`` (default), return the
+                immediate children's base names (``os.listdir``).
+
+        Returns:
+            `list[str]`:
+                The matched entries.
+        """
+        if recursive:
+            results: list[str] = []
+            for root, _dirs, files in os.walk(path):
+                for f in files:
+                    results.append(os.path.join(root, f))
+            return results
+        return os.listdir(path)
+
+    async def stat_mtime(self, path: str) -> float | None:
+        """Return the modification time of a local file.
+
+        Args:
+            path (`str`):
+                Path to stat.
+
+        Returns:
+            `float | None`:
+                The modification time as a POSIX timestamp, or ``None``
+                if the path does not exist or cannot be stat'd.
+        """
+        try:
+            return os.stat(path).st_mtime
+        except (OSError, FileNotFoundError):
+            return None
+
+    async def delete_path(self, path: str) -> None:
+        """Delete a local file or directory tree.
+
+        No-op if *path* does not exist.
+
+        Args:
+            path (`str`):
+                Path to delete.
+        """
+        if not os.path.exists(path):
+            return
+        if os.path.isdir(path):
+            shutil.rmtree(path)
+        else:
+            os.remove(path)

src/agentscope/tool/_builtin/_bash.py

@@ -0,0 +1,778 @@
+# -*- coding: utf-8 -*-
+"""The bash tool in agentscope."""
+import os
+from typing import AsyncGenerator, Any, List
+import re
+
+from ._bash_parser import BashCommandParser
+from .._base import ToolBase, ToolMiddlewareBase
+from .._constants import (
+    DEFAULT_DANGEROUS_FILES,
+    DEFAULT_DANGEROUS_DIRECTORIES,
+)
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionMode,
+    PermissionRule,
+)
+from ...message import TextBlock, ToolResultState
+from .._response import ToolChunk
+from ._backend import BackendBase
+
+
+class Bash(ToolBase):
+    """The bash tool."""
+
+    name: str = "Bash"
+    """The tool name presented to the agent."""
+
+    description: str = """Executes a bash command and returns its output.
+
+The working directory persists between commands, but shell state does
+not. The shell environment is initialized from the user's profile
+(bash or zsh).
+
+IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`,
+`tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed
+or after you have verified that a dedicated tool cannot accomplish your
+task. Instead, use the appropriate dedicated tool as this will provide
+a much better experience for the user:
+
+ - File search: Use Glob (NOT find or ls)
+ - Content search: Use Grep (NOT grep or rg)
+ - Read files: Use Read (NOT cat/head/tail)
+ - Edit files: Use Edit (NOT sed/awk)
+ - Write files: Use Write (NOT echo >/cat <<EOF)
+ - Communication: Output text directly (NOT echo/printf)
+
+While the Bash tool can do similar things, it's better to use the
+built-in tools as they provide a better user experience and make it
+easier to review tool calls and give permission.
+
+# Instructions
+ - If your command will create new directories or files, first use
+   this tool to run `ls` to verify the parent directory exists and is
+   the correct location.
+ - Always quote file paths that contain spaces with double quotes in
+   your command (e.g., cd "path with spaces/file.txt")
+ - Try to maintain your current working directory throughout the
+   session by using absolute paths and avoiding usage of `cd`. You may
+   use `cd` if the User explicitly requests it.
+ - You may specify an optional timeout in milliseconds (up to 600000ms
+   / 10 minutes). By default, your command will timeout after 120000ms
+   (2 minutes).
+ - Write a clear, concise description of what your command does. For
+   simple commands, keep it brief (5-10 words). For complex commands
+   (piped commands, obscure flags, or anything hard to understand at a
+   glance), include enough context so that the user can understand what
+   your command will do.
+ - When issuing multiple commands:
+  - If the commands are independent and can run in parallel, make
+    multiple Bash tool calls in a single message. Example: if you need
+    to run "git status" and "git diff", send a single message with two
+    Bash tool calls in parallel.
+  - If the commands depend on each other and must run sequentially,
+    use a single Bash call with '&&' to chain them together.
+  - Use ';' only when you need to run commands sequentially but don't
+    care if earlier commands fail.
+  - DO NOT use newlines to separate commands (newlines are ok in
+    quoted strings).
+ - For git commands:
+  - Prefer to create a new commit rather than amending an existing
+    commit.
+  - Before running destructive operations (e.g., git reset --hard, git
+    push --force, git checkout --), consider whether there is a safer
+    alternative that achieves the same goal. Only use destructive
+    operations when they are truly the best approach.
+  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign,
+    -c commit.gpgsign=false) unless the user has explicitly asked for
+    it. If a hook fails, investigate and fix the underlying issue.
+ - Avoid unnecessary `sleep` commands:
+  - Do not sleep between commands that can run immediately — just run
+    them.
+  - Do not retry failing commands in a sleep loop — diagnose the root
+    cause or consider an alternative approach.
+  - If you must sleep, keep the duration short (1-5 seconds) to avoid
+    blocking the user."""
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The bash command to execute.",
+            },
+            "description": {
+                "type": "string",
+                "description": (
+                    "Clear, concise description of what this command "
+                    "does. For simple commands, keep it brief (5-10 "
+                    "words). For complex commands, include enough "
+                    "context."
+                ),
+            },
+            "timeout": {
+                "type": "integer",
+                "description": (
+                    "Optional timeout in milliseconds "
+                    "(default: 120000, max: 600000)"
+                ),
+                "default": 120000,
+                "maximum": 600000,
+                "minimum": 0,
+            },
+        },
+        "required": ["command"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = False
+    is_concurrency_safe: bool = False
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+
+    def __init__(  # pylint: disable=dangerous-default-value
+        self,
+        dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES,
+        dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES,
+        cwd: str | os.PathLike[str] | None = None,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize the bash tool.
+
+        Args:
+            dangerous_files (`list[str]`, optional):
+                Sensitive files that require explicit user confirmation,
+                even in BYPASS mode. Matched by basename
+                (case-insensitive). Defaults to `DEFAULT_DANGEROUS_FILES`.
+                Pass a custom list to fully replace the defaults, or `[]`
+                to disable the filename check.
+            dangerous_directories (`list[str]`, optional):
+                Sensitive directories that require explicit user
+                confirmation. Matched when any path segment equals an
+                entry (case-insensitive). Defaults to
+                `DEFAULT_DANGEROUS_DIRECTORIES`. Pass a custom list to
+                fully replace the defaults, or `[]` to disable the
+                directory check.
+            cwd (`str | os.PathLike[str] | None`, optional):
+                The working directory used when executing bash commands.
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use for shell execution. When
+                ``None``, a :class:`LocalBackend` is created.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self._bash_parser = BashCommandParser()
+
+        self.dangerous_files = list(dangerous_files)
+        self.dangerous_directories = list(dangerous_directories)
+        self._cwd = os.fspath(cwd) if cwd is not None else None
+        self._backend = backend or LocalBackend()
+
+    async def check_read_only(
+        self,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Decide whether this specific bash invocation is read-only.
+
+        Inspects the command and returns ``True`` for known-safe read-only
+        commands (e.g. ``ls``, ``cat``, ``grep``, ``git status``). The
+        static :attr:`is_read_only` class attribute is ``False`` because
+        Bash can execute arbitrary commands; this method overrides that
+        with a per-invocation answer.
+        """
+        command = tool_input.get("command", "")
+        if not command:
+            return self.is_read_only
+        return self._bash_parser.is_read_only_command(command)
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for bash command execution.
+
+        This method implements Bash-specific permission checks:
+
+        0. Injection risk check (bypass-immune safety ASK if command
+           contains dynamic expansion like ``$(...)`` or ``<(...)``)
+        1. Read-only command check — auto-ALLOW in **every mode**
+           (including DEFAULT) for known-safe read-only commands
+           (``ls``, ``pwd``, ``git status``, ``cat``, etc.). This is
+           the static counterpart to :meth:`check_read_only`.
+        2. Dangerous command pattern check (bypass-immune safety ASK)
+        3. Sed in-place constraint check (bypass-immune safety ASK)
+        4. Dangerous path check for config files (bypass-immune safety
+           ASK)
+        5. Dangerous removal path check for system dirs (bypass-immune
+           safety ASK)
+        6. ACCEPT_EDITS auto-allow for ``mkdir``/``touch``/``rm``/
+           ``rmdir``/``mv``/``cp``/``sed`` — only when **every**
+           target path resolves inside a working directory
+        7. PASSTHROUGH (engine continues with rule matching)
+
+        "Bypass-immune" decisions set
+        :attr:`PermissionDecision.bypass_immune` so they cannot be
+        silenced by allow rules in DEFAULT mode. In BYPASS mode all
+        bypass-immune ASKs are intentionally skipped — see
+        :attr:`PermissionMode.BYPASS`.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input containing "command" key
+            context (`PermissionContext`):
+                The permission context with mode and rules
+
+        Returns:
+            `PermissionDecision`:
+                ALLOW for safe operations, ASK for dangerous operations,
+                PASSTHROUGH to let Engine continue with rule matching
+        """
+
+        command = tool_input.get("command", "")
+        if not command:
+            return PermissionDecision(
+                behavior=PermissionBehavior.PASSTHROUGH,
+                message="Empty command",
+            )
+
+        # 0. Injection check: detect dynamic shell structures that cannot be
+        # statically analyzed (command substitution, process substitution,
+        # control flow, etc.). Must run before read-only check so that
+        # `$(rm -rf /)` inside an otherwise-safe command is caught.
+        injection_reason = self._bash_parser.check_injection_risk(command)
+        if injection_reason:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: {injection_reason}",
+                decision_reason="Safety check: command contains dynamic "
+                "expansion that cannot be statically analyzed",
+                bypass_immune=True,
+            )
+
+        # 1. Check if command is read-only (auto-allow)
+        if self._bash_parser.is_read_only_command(command):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message="Permission granted for read-only command",
+                decision_reason="Read-only command is allowed",
+            )
+
+        # 2. Check for dangerous commands (safety check, bypass-immune)
+        dangerous_pattern = self._bash_parser.check_dangerous_command(command)
+        if dangerous_pattern:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: Command contains dangerous "
+                f"pattern: {dangerous_pattern}",
+                decision_reason="Safety check: dangerous command pattern "
+                "detected",
+                bypass_immune=True,
+            )
+
+        # 3. Check for sed constraints (safety check, bypass-immune)
+        sed_error = self._bash_parser.check_sed_constraints(
+            command,
+            self.dangerous_files,
+        )
+        if sed_error:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: {sed_error}",
+                decision_reason="Safety check: sed in-place modification "
+                "of dangerous file",
+                bypass_immune=True,
+            )
+
+        # 4. Check for dangerous paths in sensitive config files/dirs
+        # (safety check, bypass-immune)
+        dangerous_paths = self._extract_dangerous_paths_from_bash(command)
+        if dangerous_paths:
+            paths_str = ", ".join(dangerous_paths)
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: Bash command operates on "
+                f"sensitive paths: {paths_str}",
+                decision_reason="Safety check: dangerous file or "
+                "directory in bash command",
+                bypass_immune=True,
+            )
+
+        # 5. Check for dangerous removal paths: rm/rmdir targeting system
+        # critical directories like /, /usr, /etc, ~ (bypass-immune).
+        # Checked separately from step 4 because these paths are not in the
+        # dangerous_files/directories lists — they are system-level paths
+        # that should never be removed regardless of user configuration.
+        removal_path = await self._check_dangerous_removal_path(command)
+        if removal_path:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Dangerous removal operation detected: "
+                f"'{removal_path}'\n\nThis command would remove a critical "
+                f"system directory. This requires explicit approval and "
+                f"cannot be auto-allowed by permission rules.",
+                decision_reason="Safety check: dangerous removal of "
+                "critical system path",
+                bypass_immune=True,
+            )
+
+        # 6. ACCEPT_EDITS auto-allow for filesystem commands whose targets
+        # all live inside a working directory. Mirrors Write/Edit's strict
+        # working-directory check — we never auto-allow a bash command that
+        # would touch a path outside the configured working set (e.g.
+        # ``cp /etc/hosts /tmp/x`` must not pass even though ``cp`` is in
+        # the auto-allow list).
+        if context.mode == PermissionMode.ACCEPT_EDITS:
+            filesystem_commands = {
+                "mkdir",
+                "touch",
+                "rm",
+                "rmdir",
+                "mv",
+                "cp",
+                "sed",
+            }
+            base_command = (
+                command.strip().split()[0] if command.strip() else ""
+            )
+
+            if base_command in filesystem_commands:
+                # Collect every target path: file arguments AND output
+                # redirections. ``extract_file_paths`` includes both.
+                target_paths = [
+                    path
+                    for _cmd, path in self._bash_parser.extract_file_paths(
+                        command,
+                    )
+                ]
+                # Conservative: only auto-allow when we extracted at least
+                # one target AND every target resolves inside a working
+                # directory. An empty list means the parser found nothing
+                # actionable (or the command has no args) — in that case
+                # we fall through to PASSTHROUGH rather than blindly
+                # allowing.
+                if target_paths and all(
+                    self._path_in_allowed_working_path(path, context)
+                    for path in target_paths
+                ):
+                    return PermissionDecision(
+                        behavior=PermissionBehavior.ALLOW,
+                        message=f"Permission granted for '{base_command}' "
+                        f"command (accept edits mode - filesystem command, "
+                        f"all targets in working directory)",
+                        decision_reason=(
+                            f"Filesystem command '{base_command}' is "
+                            f"auto-allowed in accept edits mode because "
+                            f"all target paths are within a working "
+                            f"directory"
+                        ),
+                    )
+
+        # 7. Passthrough to let Engine continue with rule matching
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message=f"Execute bash command: {command}",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        r"""Match Bash command using regex-based wildcard matching.
+
+        Implements wildcard matching with escape sequences:
+        - Supports \* for literal asterisk and \\ for literal backslash
+        - Special optimization: "git *" matches both "git" and "git add"
+        - Prefix pattern (e.g., "git:*"): matches commands starting with "git "
+        - Wildcard pattern: converts to regex with proper escape handling
+        - Substring pattern: exact substring matching
+        - If rule_content is None, matches all invocations
+         (tool-name-level rule)
+
+        Args:
+            rule_content: The command pattern to match, or None to match all
+            tool_input: Must contain a "command" key with the command string
+
+        Returns:
+            True if pattern matches the command
+        """
+        # None = tool-name-level rule, matches everything
+        if rule_content is None:
+            return True
+
+        command = tool_input.get("command", "")
+
+        # Check if pattern is a prefix pattern (ends with :*)
+        if rule_content.endswith(":*"):
+            prefix = rule_content[:-2].strip()
+            return command.startswith(prefix + " ") or command == prefix
+
+        # Check if pattern has unescaped wildcards
+        def has_wildcards(pattern: str) -> bool:
+            """Check if pattern contains unescaped * wildcards."""
+            i = 0
+            while i < len(pattern):
+                if pattern[i] == "\\":
+                    i += 2  # Skip escaped character
+                elif pattern[i] == "*":
+                    return True
+                else:
+                    i += 1
+            return False
+
+        if not has_wildcards(rule_content):
+            # No wildcards, but may have escape sequences
+            # Convert escape sequences for matching
+            pattern = rule_content
+            pattern = pattern.replace("\\\\", "\x00BACKSLASH\x00")
+            pattern = pattern.replace("\\*", "*")
+            pattern = pattern.replace("\x00BACKSLASH\x00", "\\")
+            # Use substring matching with converted pattern
+            return pattern in command
+
+        # Convert wildcard pattern to regex with escape handling
+        # Use placeholders for escaped sequences
+        ESCAPED_STAR = "\x00ESCAPED_STAR\x00"
+        ESCAPED_BACKSLASH = "\x00ESCAPED_BACKSLASH\x00"
+
+        pattern = rule_content
+        # Replace \\ with placeholder
+        pattern = pattern.replace("\\\\", ESCAPED_BACKSLASH)
+        # Replace \* with placeholder
+        pattern = pattern.replace("\\*", ESCAPED_STAR)
+
+        # Manually escape regex special characters (except *)
+        # Don't use re.escape() as it escapes spaces too
+        special_chars = r".^$+?{}[]|()"
+        for char in special_chars:
+            pattern = pattern.replace(char, "\\" + char)
+
+        # Convert * to regex .* (match any characters)
+        pattern = pattern.replace("*", ".*")
+
+        # Restore escaped sequences
+        pattern = pattern.replace(ESCAPED_STAR, r"\*")
+        pattern = pattern.replace(ESCAPED_BACKSLASH, r"\\")
+
+        # Special optimization: "git *" should match both "git" and "git add"
+        # Pattern: if ends with .*, make it optional
+        if pattern.endswith(".*"):
+            base_pattern = pattern[:-2]  # Remove .*
+            # Try exact match first (handles trailing space)
+            base_pattern = base_pattern.rstrip()
+            if re.fullmatch(base_pattern, command):
+                return True
+
+        # Full regex match
+        try:
+            return bool(re.fullmatch(pattern, command))
+        except re.error:
+            # Invalid regex, fall back to substring matching
+            return rule_content.replace("*", "") in command
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List["PermissionRule"]:
+        """Generate suggested permission rules for Bash commands.
+
+        Generates prefix rules based on command + subcommand (two words).
+        For example, "git commit -m 'xxx'" generates "git commit:*".
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "command" key
+
+        Returns:
+            `List[PermissionRule]`:
+                List of suggested permission rules based on command prefixes
+        """
+
+        command = tool_input.get("command", "")
+        if not command:
+            return []
+
+        # Use bash parser to extract command prefixes
+        prefixes = self._bash_parser.extract_command_prefixes(
+            command,
+            max_prefixes=5,
+        )
+
+        if not prefixes:
+            # Cannot extract any prefix, return empty
+            return []
+
+        # Generate rules for each prefix
+        rules = []
+        for prefix in prefixes:
+            rules.append(
+                PermissionRule(
+                    tool_name="Bash",
+                    rule_content=f"{prefix}:*",
+                    behavior=PermissionBehavior.ALLOW,
+                    source="suggested",
+                ),
+            )
+
+        return rules
+
+    def _extract_dangerous_paths_from_bash(
+        self,
+        command: str,
+    ) -> list[str]:
+        """Extract dangerous paths from a bash command using tree-sitter.
+
+        Checks for dangerous paths in:
+        - File-manipulating commands (rm, mv, cp, chmod, chown, sed, touch)
+        - Output redirections (>, >>)
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `list[str]`:
+                List of dangerous paths found in the command
+        """
+        dangerous_paths = []
+
+        # Use tree-sitter to extract file paths
+        file_paths = self._bash_parser.extract_file_paths(command)
+
+        for _cmd_name, path in file_paths:
+            if self._is_dangerous_path(path):
+                dangerous_paths.append(path)
+
+        return dangerous_paths
+
+    async def _check_dangerous_removal_path(self, command: str) -> str | None:
+        """Check if a rm/rmdir command targets a critical system path.
+
+        Detects commands like `rm -rf /`, `rm -rf /usr`, `rmdir ~` that
+        would destroy critical system directories. Unlike _is_dangerous_path
+        (which checks against a configurable list of sensitive config files),
+        this checks against a fixed set of system-level paths that must
+        never be removed regardless of user configuration.
+
+        Dangerous paths are:
+        - Root directory (/)
+        - Home directory (~)
+        - Wildcard alone (*) or as dir/* (removes everything)
+        - Direct children of root (/usr, /etc, /tmp, /var, etc.)
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `str | None`:
+                The dangerous path if found, None otherwise
+        """
+        tokens = command.strip().split()
+        if not tokens:
+            return None
+
+        # Find rm or rmdir subcommands (handle compound commands)
+        try:
+            tree = self._bash_parser.parser.parse(bytes(command, "utf8"))
+            subcommands = self._bash_parser.split_compound_command(
+                tree.root_node,
+                command,
+            )
+        except Exception:
+            subcommands = [command]
+
+        # Check each subcommand for rm/rmdir
+        for subcmd in subcommands:
+            subcmd_tokens = subcmd.strip().split()
+            if not subcmd_tokens:
+                continue
+            base = subcmd_tokens[0]
+            if base not in ("rm", "rmdir"):
+                continue
+
+            # Collect non-flag arguments as potential paths
+            i = 1
+            while i < len(subcmd_tokens):
+                tok = subcmd_tokens[i]
+                # Skip flags
+                if tok.startswith("-"):
+                    i += 1
+                    continue
+                path = tok.strip("'\"")
+                if await self._is_dangerous_removal_path(path):
+                    return path
+                i += 1
+
+        return None
+
+    async def _is_dangerous_removal_path(self, path: str) -> bool:
+        """Check if a path is a critical system directory that must not be
+        removed.
+
+        All path resolution is performed via the backend so that the
+        check operates on the **backend environment's** ``$HOME`` /
+        ``cwd`` / path semantics, not the host process's.
+
+        Args:
+            path (`str`):
+                The path to check (may be relative, absolute, or contain ~)
+
+        Returns:
+            `bool`:
+                True if removing this path would be catastrophic
+        """
+
+        # Bare wildcard
+        if path in ("*", "./*", "/"):
+            return True
+        # Ends with /* — removes everything in a directory
+        if path.endswith("/*") or path.endswith("\\*"):
+            return True
+
+        # Expand tilde and resolve to an absolute path inside the
+        # backend environment.  Don't resolve symlinks — ``/tmp`` is a
+        # symlink on macOS but is still a root-child and should be
+        # flagged.
+        expanded = await self._backend.expanduser(path)
+        backend_cwd = await self._backend.getcwd()
+        abs_path = self._backend.abspath(expanded, cwd=backend_cwd)
+
+        # Home directory
+        home = await self._backend.expanduser("~")
+        if abs_path == home:
+            return True
+
+        # Root itself: ``dirname(root) == root`` on both POSIX
+        # (``"/"``) and Windows (``"C:\\"``), so this check is
+        # path-flavor agnostic.
+        parent = self._backend.dirname(abs_path)
+        if abs_path == parent:
+            return True
+
+        # Direct children of root (e.g. ``/usr``, ``/etc``, ``/tmp``):
+        # the *parent* of these is the root, where
+        # ``dirname(parent) == parent``.
+        if self._backend.dirname(parent) == parent:
+            return True
+
+        return False
+
+    async def call(  # type: ignore[override] # pylint: disable=unused-argument
+        self,
+        command: str,
+        description: str = "",
+        timeout: int = 120000,
+    ) -> AsyncGenerator[ToolChunk, None]:
+        """Execute the bash and return the output.
+
+        Args:
+            command: The bash command to execute.
+            description: Optional description of what the command does.
+            timeout: Timeout in milliseconds (default: 120000, max: 600000).
+
+        Yields:
+            ToolChunk: The tool execution result with stdout/stderr content.
+        """
+
+        # Clamp timeout to max 600000ms and convert to seconds
+        timeout_ms = min(timeout, 600000)
+        timeout_sec = timeout_ms / 1000.0
+
+        try:
+            # ``command`` is a full shell command line (it may contain
+            # pipes, redirects, ``&&``, …), so wrap it in a shell — the
+            # backend primitive runs the argv directly without one. Pick
+            # the platform's native shell so the Windows experience that
+            # ``main`` had (commands interpreted by ``cmd.exe``) is
+            # preserved; POSIX hosts use ``/bin/sh``.
+            if os.name == "nt":
+                shell_command = ["cmd", "/c", command]
+            else:
+                shell_command = ["/bin/sh", "-c", command]
+            result = await self._backend.exec_shell(
+                shell_command,
+                cwd=self._cwd,
+                timeout=timeout_sec,
+            )
+
+            # Decode and normalize line endings
+            stdout = result.stdout.decode(
+                "utf-8",
+                errors="replace",
+            ).replace("\r\n", "\n")
+            stderr = result.stderr.decode(
+                "utf-8",
+                errors="replace",
+            ).replace("\r\n", "\n")
+
+            # Check for timeout (backend returns exit_code=-1,
+            # stderr=b"timed out")
+            if result.exit_code == -1 and result.stderr == b"timed out":
+                error_msg = (
+                    f"Command timed out after {timeout_ms}ms: {command}"
+                )
+                yield ToolChunk(
+                    content=[TextBlock(text=error_msg)],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+                return
+
+            # Combine output
+            output = stdout
+            if stderr:
+                if output:
+                    output += "\n"
+                output += stderr
+
+            # Truncate if exceeds 30000 characters
+            if len(output) > 30000:
+                output = output[:30000] + "\n... (output truncated)"
+
+            # Check exit code
+            if not result.ok():
+                # Command failed
+                error_result = f"Command failed: {command}\n"
+                if stdout:
+                    error_result += f"\nStdout:\n{stdout}"
+                if stderr:
+                    error_result += f"\nStderr:\n{stderr}"
+
+                # Truncate error message if needed
+                if len(error_result) > 30000:
+                    error_result = (
+                        error_result[:30000] + "\n... (output truncated)"
+                    )
+
+                yield ToolChunk(
+                    content=[TextBlock(text=error_result)],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+            else:
+                # Command succeeded - note: ToolChunk uses "running" state
+                # which will be converted to "finished" in ToolResponse
+                yield ToolChunk(
+                    content=[TextBlock(text=output)],
+                    state=ToolResultState.RUNNING,
+                    is_last=True,
+                )
+
+        except Exception as e:
+            # Other errors
+            error_msg = f"Command failed: {command}\nError: {str(e)}"
+            yield ToolChunk(
+                content=[TextBlock(text=error_msg)],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )

src/agentscope/tool/_builtin/_bash_parser.py

@@ -0,0 +1,884 @@
+# -*- coding: utf-8 -*-
+"""Bash command parser using tree-sitter for precise syntax analysis.
+
+This module provides utilities to parse Bash commands and extract meaningful
+information for permission rule generation, including:
+- Splitting compound commands (&&, ||, ;, |)
+- Extracting command prefixes (e.g., "npm run" from "npm run build")
+- Extracting file paths from commands for dangerous path detection
+- Extracting output redirections
+- Checking if commands are read-only
+"""
+
+from typing import List, Optional, Set, Tuple
+
+import re
+import shlex
+
+import tree_sitter_bash as tsbash
+from tree_sitter import Language, Parser, Node
+
+from .._constants import DANGEROUS_NODE_TYPES, DANGEROUS_COMMANDS
+
+
+# Commands that are considered safe and don't require permission rules
+SAFE_COMMANDS: Set[str] = {
+    "echo",
+    "cat",
+    "ls",
+    "pwd",
+    "cd",
+    "true",
+    "false",
+    "printf",
+    "grep",
+    "tee",
+}
+
+# Safe environment variables that can be skipped when extracting command prefix
+SAFE_ENV_VARS = {
+    "NODE_ENV",
+    "PYTHONUNBUFFERED",
+    "RUST_LOG",
+    "LANG",
+    "TERM",
+    "NO_COLOR",
+    "FORCE_COLOR",
+    "DEBUG",
+    "VERBOSE",
+    "CI",
+    "PATH",
+    "HOME",
+    "USER",
+    "SHELL",
+    "EDITOR",
+    "PAGER",
+    "TZ",
+    "LC_ALL",
+    "LC_CTYPE",
+    "COLUMNS",
+    "LINES",
+    "CLICOLOR",
+    "CLICOLOR_FORCE",
+}
+
+# Read-only git commands
+GIT_READ_ONLY_COMMANDS = {
+    "git status",
+    "git log",
+    "git diff",
+    "git show",
+    "git branch",
+    "git tag",
+    "git remote",
+    "git ls-files",
+    "git ls-tree",
+    "git cat-file",
+    "git rev-parse",
+    "git rev-list",
+    "git describe",
+    "git shortlog",
+    "git blame",
+    "git grep",
+    "git reflog",
+    "git config --get",
+    "git config --list",
+}
+
+# Read-only commands for various tools
+READ_ONLY_COMMANDS = {
+    # Basic file operations
+    "ls",
+    "cat",
+    "head",
+    "tail",
+    "less",
+    "more",
+    "file",
+    "stat",
+    "wc",
+    "grep",
+    "rg",
+    "ag",
+    "ack",
+    "find",
+    "tree",
+    "pwd",
+    "which",
+    "whereis",
+    "type",
+    # Git commands
+    *GIT_READ_ONLY_COMMANDS,
+    # Docker read-only
+    "docker ps",
+    "docker images",
+    "docker inspect",
+    "docker logs",
+    "docker version",
+    "docker info",
+    # GitHub CLI read-only
+    "gh repo view",
+    "gh issue list",
+    "gh pr list",
+    "gh status",
+    # Python/Node tools
+    "python --version",
+    "python -V",
+    "node --version",
+    "node -v",
+    "npm list",
+    "npm ls",
+    "pip list",
+    "pip show",
+}
+
+
+class BashCommandParser:
+    """Parse Bash commands using tree-sitter for accurate syntax analysis."""
+
+    def __init__(self) -> None:
+        """Initialize the parser with tree-sitter-bash language."""
+        self.parser = Parser(Language(tsbash.language()))
+
+    def is_read_only_command(self, command: str) -> bool:
+        """Check if a command is read-only (safe to auto-allow).
+
+        For compound commands (&&, ||, ;, |), ALL subcommands must be
+        read-only for the entire command to be considered read-only.
+
+        Commands with output redirections (>, >>) are NOT considered read-only.
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `bool`:
+                True if the command (and all subcommands) are read-only,
+                False otherwise
+        """
+        # Normalize command (strip leading/trailing whitespace)
+        cmd = command.strip()
+
+        # Check for output redirections - these are NOT read-only
+        if ">" in cmd:
+            return False
+
+        # Check if it's a compound command
+        if any(op in cmd for op in ["&&", "||", ";", "|"]):
+            # Split into subcommands and check each one
+            try:
+                tree = self.parser.parse(bytes(cmd, "utf8"))
+                root = tree.root_node
+                subcommands = self.split_compound_command(root, cmd)
+
+                # All subcommands must be read-only
+                for subcmd in subcommands:
+                    if not self._is_single_command_read_only(subcmd.strip()):
+                        return False
+                return True
+            except Exception:
+                # If parsing fails, be conservative
+                return False
+
+        # Single command - check directly
+        return self._is_single_command_read_only(cmd)
+
+    def _is_single_command_read_only(self, cmd: str) -> bool:
+        """Check if a single (non-compound) command is read-only.
+
+        Args:
+            cmd (`str`):
+                A single command string (no &&, ||, ;, |)
+
+        Returns:
+            `bool`:
+                True if the command is read-only, False otherwise
+        """
+        # Check exact match in read-only commands
+        if cmd in READ_ONLY_COMMANDS:
+            return True
+
+        # Check if it starts with a read-only prefix
+        for readonly_cmd in READ_ONLY_COMMANDS:
+            if cmd == readonly_cmd or cmd.startswith(readonly_cmd + " "):
+                return True
+
+        # Check base command for simple read-only operations
+        tokens = cmd.split()
+        if tokens:
+            base_cmd = tokens[0]
+            # Skip environment variables
+            i = 0
+            while i < len(tokens) and "=" in tokens[i]:
+                i += 1
+            if i < len(tokens):
+                base_cmd = tokens[i]
+
+            # Check if base command is in safe commands
+            if base_cmd in SAFE_COMMANDS:
+                return True
+
+        return False
+
+    def extract_file_paths(
+        self,
+        command: str,
+    ) -> List[Tuple[str, str]]:
+        """Extract file paths from a bash command using tree-sitter.
+
+        Returns paths that are arguments to file-manipulating commands
+        (rm, mv, cp, chmod, chown, etc.) and output redirection targets.
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `List[Tuple[str, str]]`:
+                List of tuples (command_name, file_path)
+        """
+        paths = []
+
+        try:
+            # Parse command to AST
+            tree = self.parser.parse(bytes(command, "utf8"))
+            root = tree.root_node
+
+            # Extract paths from commands
+            self._extract_paths_from_node(root, command, paths)
+
+        except Exception:
+            # Fallback to simple token-based extraction
+            paths = self._extract_paths_fallback(command)
+
+        return paths
+
+    def _extract_paths_from_node(
+        self,
+        node: Node,
+        command: str,
+        paths: List[Tuple[str, str]],
+    ) -> None:
+        """Recursively extract file paths from AST nodes.
+
+        Args:
+            node (`Node`):
+                The AST node to process
+            command (`str`):
+                The original command string
+            paths (`List[Tuple[str, str]]`):
+                List to append (command_name, path) tuples to
+        """
+        # Check for redirections
+        if node.type == "file_redirect":
+            # Extract the target file
+            for child in node.children:
+                if child.type == "word":
+                    path = command[child.start_byte : child.end_byte]
+                    paths.append(("redirect", path.strip("'\"")))
+        # Check for commands
+        if node.type == "command":
+            # Extract command name and arguments
+            cmd_name = None
+            args = []
+
+            for child in node.children:
+                if child.type == "command_name":
+                    cmd_name = command[child.start_byte : child.end_byte]
+                elif child.type == "word" and cmd_name:
+                    arg = command[child.start_byte : child.end_byte]
+                    args.append(arg.strip("'\""))
+
+            # Check if this is a file-manipulating command
+            if cmd_name in [
+                "rm",
+                "mv",
+                "cp",
+                "chmod",
+                "chown",
+                "chgrp",
+                "touch",
+                "ln",
+                "sed",
+                "mkdir",
+                "rmdir",
+            ]:
+                # Extract file arguments (skip flags)
+                for arg in args:
+                    if not arg.startswith("-"):
+                        paths.append((cmd_name, arg))
+
+        # Recursively process children
+        for child in node.children:
+            self._extract_paths_from_node(child, command, paths)
+
+    def _extract_paths_fallback(
+        self,
+        command: str,
+    ) -> List[Tuple[str, str]]:
+        """Fallback path extraction using simple token parsing.
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `List[Tuple[str, str]]`:
+                List of tuples (command_name, file_path)
+        """
+        paths = []
+        tokens = command.split()
+        i = 0
+
+        while i < len(tokens):
+            token = tokens[i]
+
+            # Check for output redirections
+            if token in [">", ">>", "2>", "&>"]:
+                if i + 1 < len(tokens):
+                    path = tokens[i + 1].strip("'\"")
+                    paths.append(("redirect", path))
+                i += 2
+                continue
+
+            # Check for file-manipulating commands
+            if token in [
+                "rm",
+                "mv",
+                "cp",
+                "chmod",
+                "chown",
+                "sed",
+                "touch",
+                "mkdir",
+                "rmdir",
+            ]:
+                cmd_name = token
+                # Look for file arguments after this command
+                j = i + 1
+                while j < len(tokens):
+                    arg = tokens[j].strip("'\"")
+                    # Skip flags
+                    if arg.startswith("-"):
+                        j += 1
+                        continue
+                    # This is a file argument
+                    paths.append((cmd_name, arg))
+                    j += 1
+                break
+
+            i += 1
+
+        return paths
+
+    def extract_redirections(self, command: str) -> List[str]:
+        """Extract output redirection targets from a bash command.
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `List[str]`:
+                List of file paths that are redirection targets
+        """
+        redirections = []
+
+        try:
+            # Parse command to AST
+            tree = self.parser.parse(bytes(command, "utf8"))
+            root = tree.root_node
+
+            # Extract redirections
+            self._extract_redirections_from_node(root, command, redirections)
+
+        except Exception:
+            # Fallback to simple extraction
+            tokens = command.split()
+            for i, token in enumerate(tokens):
+                if token in [">", ">>", "2>", "&>"] and i + 1 < len(tokens):
+                    path = tokens[i + 1].strip("'\"")
+                    redirections.append(path)
+
+        return redirections
+
+    def _extract_redirections_from_node(
+        self,
+        node: Node,
+        command: str,
+        redirections: List[str],
+    ) -> None:
+        """Recursively extract redirections from AST nodes.
+
+        Args:
+            node (`Node`):
+                The AST node to process
+            command (`str`):
+                The original command string
+            redirections (`List[str]`):
+                List to append redirection targets to
+        """
+        if node.type == "file_redirect":
+            # Extract the target file
+            for child in node.children:
+                if child.type == "word":
+                    path = command[child.start_byte : child.end_byte]
+                    redirections.append(path.strip("'\""))
+
+        # Recursively process children
+        for child in node.children:
+            self._extract_redirections_from_node(child, command, redirections)
+
+    def extract_command_prefixes(
+        self,
+        command: str,
+        max_prefixes: int = 5,
+    ) -> List[str]:
+        """Extract command prefixes from a bash command.
+
+        Automatically handles compound commands (&&, ||, ;, |) and extracts
+        prefixes from each subcommand. Returns deduplicated list of prefixes.
+
+        Args:
+            command (`str`):
+                The bash command string (may be compound)
+            max_prefixes (`int`):
+                Maximum number of prefixes to return (default: 5)
+
+        Returns:
+            `List[str]`:
+                List of command prefixes (deduplicated), e.g., ["npm run",
+                "git commit"]
+
+        Examples:
+            >>> parser.extract_command_prefixes("git add . && git commit")
+            ['git add', 'git commit']
+            >>> parser.extract_command_prefixes("npm run build")
+            ['npm run']
+            >>> parser.extract_command_prefixes("ls -la")
+            []
+        """
+        if not command or not command.strip():
+            return []
+
+        # Parse command to AST
+        tree = self.parser.parse(bytes(command, "utf8"))
+        root = tree.root_node
+
+        # Split compound commands
+        subcommands = self.split_compound_command(root, command)
+
+        # Extract prefixes from each subcommand
+        prefixes = []
+        seen = set()
+
+        for subcmd in subcommands[:max_prefixes]:
+            prefix = self._extract_command_prefix(subcmd)
+            if prefix and prefix not in seen:
+                prefixes.append(prefix)
+                seen.add(prefix)
+
+            if len(prefixes) >= max_prefixes:
+                break
+
+        return prefixes
+
+    def split_compound_command(self, root: Node, command: str) -> List[str]:
+        """Split compound commands using tree-sitter for precise parsing.
+
+        Recognizes: &&, ||, ;, |
+
+        Args:
+            root (`Node`):
+                The root AST node
+            command (`str`):
+                The original command string
+
+        Returns:
+            `List[str]`:
+                List of individual subcommands
+        """
+        subcommands = []
+
+        def extract_commands(node: Node) -> None:
+            """Recursively extract commands from AST."""
+            if node.type == "command":
+                # Extract command text
+                cmd_text = command[node.start_byte : node.end_byte]
+                subcommands.append(cmd_text)
+            elif node.type in ["list", "pipeline", "command_list"]:
+                # Recursively process compound structures
+                for child in node.children:
+                    if child.type not in ["&&", "||", ";", "|", "|&"]:
+                        extract_commands(child)
+            else:
+                # Continue traversing
+                for child in node.children:
+                    extract_commands(child)
+
+        extract_commands(root)
+        return subcommands if subcommands else [command]
+
+    def _extract_command_prefix(
+        self,
+        subcmd: str,
+    ) -> Optional[str]:
+        """Extract command prefix (first two words) from a subcommand.
+
+        Logic:
+        1. Skip safe environment variable assignments
+        2. Extract command name and first subcommand
+        3. Verify the second word looks like a subcommand (not a flag)
+
+        Args:
+            subcmd (`str`):
+                The subcommand string to extract prefix from
+
+        Returns:
+            `Optional[str]`:
+                Command prefix (e.g., "npm run") or None if cannot extract
+        """
+        # Parse the subcommand
+        tree = self.parser.parse(bytes(subcmd, "utf8"))
+        root = tree.root_node
+
+        # Find the first simple_command node
+        simple_cmd = self._find_first_simple_command(root)
+        if not simple_cmd:
+            return None
+
+        # Extract command parts
+        parts = []
+        env_vars = []
+
+        for child in simple_cmd.children:
+            if child.type == "variable_assignment":
+                # Environment variable assignment
+                var_name = subcmd[child.start_byte : child.end_byte].split(
+                    "=",
+                )[0]
+                env_vars.append(var_name)
+            elif child.type == "command_name":
+                # Command name
+                parts.append(subcmd[child.start_byte : child.end_byte])
+            elif child.type == "word" and len(parts) >= 1:
+                # Argument (might be a flag or subcommand)
+                word = subcmd[child.start_byte : child.end_byte]
+                parts.append(word)
+                # Stop after we have command + first argument
+                if len(parts) >= 2:
+                    break
+
+        # Check if environment variables are safe
+        if env_vars and not all(v in SAFE_ENV_VARS for v in env_vars):
+            return None
+
+        # Check if the command is a safe command that doesn't need permission
+        if parts and parts[0].lower() in SAFE_COMMANDS:
+            return None
+
+        # Return first two words
+        if len(parts) >= 2:
+            return " ".join(parts[:2])
+
+        return None
+
+    def _find_first_simple_command(self, node: Node) -> Optional[Node]:
+        """Recursively find the first command node in AST.
+
+        Args:
+            node (`Node`):
+                The AST node to search from
+
+        Returns:
+            `Optional[Node]`:
+                The first command node found, or None
+        """
+        if node.type == "command":
+            return node
+
+        for child in node.children:
+            result = self._find_first_simple_command(child)
+            if result:
+                return result
+
+        return None
+
+    def check_dangerous_command(self, command: str) -> Optional[str]:
+        """Check if command contains dangerous patterns.
+
+        Uses word-boundary aware matching to avoid false positives like
+        'git add' matching 'dd' pattern.
+
+        Args:
+            command (`str`):
+                The bash command to check
+
+        Returns:
+            `Optional[str]`:
+                The matched dangerous pattern if found, None otherwise
+        """
+
+        # Normalize command for matching
+        normalized = " ".join(command.split())
+
+        # Check each dangerous pattern
+        for pattern in DANGEROUS_COMMANDS:
+            # For single-word patterns like "dd", use word boundary matching
+            # to avoid false positives (e.g., "git add" shouldn't match "dd")
+            if " " not in pattern and len(pattern) <= 4:
+                # Single word pattern - use word boundaries
+                regex = r"\b" + re.escape(pattern) + r"\b"
+                if re.search(regex, normalized):
+                    return pattern
+            else:
+                # Multi-word pattern or longer pattern - use substring match
+                if pattern in normalized:
+                    return pattern
+
+        return None
+
+    # pylint: disable=too-many-return-statements, too-many-branches
+    def check_sed_constraints(
+        self,
+        command: str,
+        dangerous_files: List[str],
+    ) -> str | None:
+        """Check if sed command violates safety constraints.
+
+        Implements allowlist/denylist system:
+        - Allowlist: Line printing (sed -n 'Np') and substitution (sed 's///')
+        - Denylist: Dangerous operations (w/W/e/E), file writes, command
+         execution
+
+        Args:
+            command: The bash command to check
+            dangerous_files: List of dangerous file patterns
+
+        Returns:
+            Error message if dangerous sed operation found, None otherwise
+        """
+
+        if "sed" not in command:
+            return None
+
+        # Parse command using shlex
+        try:
+            tokens = shlex.split(command)
+        except ValueError:
+            return "sed command has invalid shell syntax"
+
+        # Find sed command position
+        sed_idx = None
+        for i, token in enumerate(tokens):
+            if token == "sed" or token.endswith("/sed"):
+                sed_idx = i
+                break
+
+        if sed_idx is None:
+            return None
+
+        # Extract flags and expressions
+        args = tokens[sed_idx + 1 :]
+        flags = []
+        expressions = []
+        file_args = []
+        i = 0
+        found_first_expr = False
+
+        while i < len(args):
+            arg = args[i]
+
+            # Handle flags
+            if arg.startswith("-") and not arg.startswith("--"):
+                # Combined flags like -nE
+                flag_chars = arg[1:]
+                for char in flag_chars:
+                    flags.append(char)
+                # -i flag may have optional backup extension argument
+                # But only skip if next arg doesn't look like an expression
+                if "i" in flag_chars and i + 1 < len(args):
+                    next_arg = args[i + 1]
+                    # Skip backup extension only if it's not an expression
+                    # or file
+                    if (
+                        not next_arg.startswith("-")
+                        and not next_arg.startswith("s")
+                        and "." not in next_arg
+                    ):
+                        i += 1  # Skip backup extension
+            elif arg == "--in-place":
+                flags.append("i")
+                if i + 1 < len(args):
+                    next_arg = args[i + 1]
+                    if (
+                        not next_arg.startswith("-")
+                        and not next_arg.startswith("s")
+                        and "." not in next_arg
+                    ):
+                        i += 1
+            elif arg in ["-e", "--expression"]:
+                if i + 1 < len(args):
+                    expressions.append(args[i + 1])
+                    i += 1
+            elif not arg.startswith("-"):
+                # First non-flag, non-option arg is expression (if no -e used)
+                if not found_first_expr:
+                    expressions.append(arg)
+                    found_first_expr = True
+                else:
+                    file_args.append(arg)
+
+            i += 1
+
+        # If no expressions found, command is invalid
+        if not expressions:
+            return "sed command missing expression"
+
+        # Validate flags - only allow specific flags
+        allowed_flags = {"n", "E", "e", "i"}
+        for flag in flags:
+            if flag not in allowed_flags:
+                return f"sed flag -{flag} not allowed"
+
+        # Check allowlist patterns
+        has_n_flag = "n" in flags
+        has_i_flag = "i" in flags
+
+        for expr in expressions:
+            # Denylist checks first - dangerous operations
+            # Check for write operations (w, W) - must be at end or followed
+            # by space/filename
+            if (
+                re.search(r"/[wW]\s+\S+", expr)
+                or expr.endswith("/w")
+                or expr.endswith("/W")
+            ):
+                return "sed write operation (w/W) not allowed"
+
+            # Check for execute operations (e, E) - must be at end or
+            # followed by space
+            if (
+                re.search(r"/[eE](?:\s|$)", expr)
+                or expr.endswith("/e")
+                or expr.endswith("/E")
+            ):
+                return "sed execute operation (e/E) not allowed"
+
+            # Check for dangerous patterns
+            if "{" in expr or "}" in expr:
+                return "sed curly braces not allowed"
+            if expr.startswith("!"):
+                return "sed negation (!) not allowed"
+            if "#" in expr and not expr.startswith("s#"):
+                return "sed comments not allowed"
+
+            # Pattern 1: Line printing with -n flag (sed -n 'Np' or 'N,Mp')
+            if has_n_flag:
+                # Match: number followed by 'p', or range 'N,Mp'
+                if re.match(
+                    r"^\d+p$",
+                    expr,
+                ) or re.match(
+                    r"^\d+,\d+p$",
+                    expr,
+                ):
+                    continue
+
+            # Pattern 2: Substitution command
+            # (sed 's/pattern/replacement/flags')
+            if (
+                expr.startswith("s/")
+                or expr.startswith("s|")
+                or expr.startswith("s#")
+            ):
+                delimiter = expr[1]
+                parts = expr[2:].split(delimiter)
+                if len(parts) >= 2:
+                    # Valid substitution
+                    # Check substitution flags (g, p, number, etc.)
+                    if len(parts) > 2:
+                        sub_flags = parts[2]
+                        # Allow common substitution flags
+                        if all(c in "gp0123456789" for c in sub_flags):
+                            continue
+                    else:
+                        continue
+
+            # If we reach here, expression doesn't match allowlist
+            return f"sed expression '{expr}' not in allowlist"
+
+        # Check -i flag with dangerous files
+        if has_i_flag and file_args:
+            for file_path in file_args:
+                for dangerous_file in dangerous_files:
+                    if dangerous_file in file_path or file_path.endswith(
+                        dangerous_file,
+                    ):
+                        return f"sed -i modifying dangerous file: {file_path}"
+
+        return None
+
+    def check_injection_risk(self, command: str) -> Optional[str]:
+        """Check if command contains structures that cannot be statically
+        analyzed.
+
+        This detects command substitution, process substitution, complex
+        expansions, control flow, and other dynamic shell features that
+        make it impossible to determine the command's behavior without
+        execution.
+
+        Args:
+            command (`str`):
+                The bash command to check
+
+        Returns:
+            `Optional[str]`:
+                Reason string if command is too complex, None if it can be
+                statically analyzed
+
+        Examples:
+            >>> parser.check_injection_risk("ls -la")
+            None
+            >>> parser.check_injection_risk("rm $(find . -name '*.tmp')")
+            "Command contains command_substitution which cannot be statically
+            analyzed"
+            >>> parser.check_injection_risk("for f in *.txt; do cat $f; done")
+            "Command contains for_statement which cannot be statically
+            analyzed"
+        """
+
+        try:
+            tree = self.parser.parse(bytes(command, "utf8"))
+            return self._walk_for_dangerous_nodes(tree.root_node)
+        except Exception:
+            # If parsing fails, be conservative and require review
+            return "Command parsing failed, cannot verify safety"
+
+    def _walk_for_dangerous_nodes(self, node: Node) -> Optional[str]:
+        """Recursively walk AST to find dangerous node types.
+
+        Args:
+            node (`Node`):
+                The AST node to check
+
+        Returns:
+            `Optional[str]`:
+                Reason string if dangerous node found, None otherwise
+        """
+
+        # Check if this node is a dangerous type
+        if node.type in DANGEROUS_NODE_TYPES:
+            return (
+                f"Command contains {node.type} which cannot be "
+                f"statically analyzed"
+            )
+
+        # Recursively check children
+        for child in node.children:
+            result = self._walk_for_dangerous_nodes(child)
+            if result:
+                return result
+
+        return None

src/agentscope/tool/_builtin/_edit.py

@@ -0,0 +1,416 @@
+# -*- coding: utf-8 -*-
+"""The edit tool in agentscope."""
+import difflib
+import fnmatch
+from typing import Any, List
+
+from .._base import ToolBase, ToolMiddlewareBase
+from .._constants import (
+    DEFAULT_DANGEROUS_FILES,
+    DEFAULT_DANGEROUS_DIRECTORIES,
+)
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionMode,
+    PermissionRule,
+)
+from .._response import ToolChunk
+from ...message import TextBlock, ToolResultState
+from ...state import AgentState
+from ._backend import BackendBase, _normalize_newlines
+
+
+class Edit(ToolBase):
+    """The edit tool for performing exact string replacements in files."""
+
+    name: str = "Edit"
+    """The tool name presented to the agent."""
+
+    description: str = """Performs exact string replacements in files.
+
+Usage:
+- You must use your `Read` tool at least once in the conversation
+  before editing. This tool will error if you attempt an edit without
+  reading the file.
+- When editing text from Read tool output, ensure you preserve the
+  exact indentation (tabs/spaces) as it appears AFTER the line number
+  prefix. The line number prefix format is: line number + tab.
+  Everything after that is the actual file content to match. Never
+  include any part of the line number prefix in the old_string or
+  new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write
+  new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding
+  emojis to files unless asked.
+- The edit will FAIL if `old_string` is not unique in the file."""  # noqa: E501
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "file_path": {
+                "type": "string",
+                "description": "The absolute path to the file to edit.",
+            },
+            "old_string": {
+                "type": "string",
+                "description": (
+                    "The exact string to replace. Must match exactly "
+                    "including whitespace and indentation."
+                ),
+            },
+            "new_string": {
+                "type": "string",
+                "description": "The string to replace old_string with.",
+            },
+            "replace_all": {
+                "type": "boolean",
+                "description": (
+                    "If true, replace all occurrences. If false "
+                    "(default), only replace if there is exactly one "
+                    "occurrence."
+                ),
+                "default": False,
+            },
+        },
+        "required": ["file_path", "old_string", "new_string"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = False
+    is_concurrency_safe: bool = False
+    is_external_tool: bool = False
+    is_state_injected: bool = True
+
+    def __init__(  # pylint: disable=dangerous-default-value
+        self,
+        dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES,
+        dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize the edit tool.
+
+        Args:
+            dangerous_files (`list[str]`, optional):
+                Sensitive files that require explicit user confirmation,
+                even in BYPASS mode. Matched by basename
+                (case-insensitive). Defaults to `DEFAULT_DANGEROUS_FILES`.
+                Pass a custom list to fully replace the defaults, or `[]`
+                to disable the filename check.
+            dangerous_directories (`list[str]`, optional):
+                Sensitive directories that require explicit user
+                confirmation. Matched when any path segment equals an
+                entry (case-insensitive). Defaults to
+                `DEFAULT_DANGEROUS_DIRECTORIES`. Pass a custom list to
+                fully replace the defaults, or `[]` to disable the
+                directory check.
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use for file I/O. When ``None``,
+                a :class:`LocalBackend` is created.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self.dangerous_files = list(dangerous_files)
+        self.dangerous_directories = list(dangerous_directories)
+        self._backend = backend or LocalBackend()
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for file editing.
+
+        This method implements Edit-specific permission checks:
+        1. Dangerous path check (safety check, bypass-immune)
+        2. ACCEPT_EDITS mode check for files in working directories
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input containing "file_path" key
+            context (`PermissionContext`):
+                The permission context with mode and rules
+
+        Returns:
+            `PermissionDecision`:
+                ASK for dangerous paths, ALLOW for safe operations in
+                ACCEPT_EDITS mode, PASSTHROUGH otherwise
+        """
+
+        file_path = tool_input.get("file_path")
+        if not file_path:
+            return PermissionDecision(
+                behavior=PermissionBehavior.PASSTHROUGH,
+                message="No file path provided",
+            )
+
+        # 1. Check for dangerous paths (safety check, bypass-immune)
+        if self._is_dangerous_path(file_path):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: Edit operation on "
+                f"sensitive file {file_path}",
+                decision_reason="Safety check: dangerous file or directory",
+                bypass_immune=True,
+            )
+
+        # 2. Check ACCEPT_EDITS mode for files in working directories
+        if context.mode == PermissionMode.ACCEPT_EDITS:
+            if self._path_in_allowed_working_path(file_path, context):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.ALLOW,
+                    message=f"Permission granted for editing {file_path} "
+                    f"(accept edits mode - in working directory)",
+                    decision_reason="File is in working directory and not "
+                    "a dangerous path",
+                )
+
+        # 3. Return PASSTHROUGH to let PermissionEngine check allow rules
+        # This ensures allow rules can grant Edit permissions
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message="",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the file path.
+
+        Matches rule_content as a glob pattern against the "file_path"
+        parameter using fnmatch. If rule_content is None, matches all
+        invocations (tool-name-level rule).
+
+        Args:
+            rule_content (`str | None`):
+                Glob pattern to match against the file path (e.g., "src/**"),
+                or None to match all invocations
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "file_path" key
+
+        Returns:
+            `bool`:
+                True if the glob pattern matches the file path, False otherwise
+        """
+        if rule_content is None:
+            return True
+
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            return False
+        return fnmatch.fnmatch(file_path, rule_content)
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the file path.
+
+        Suggests a glob pattern covering the parent directory of the file,
+        allowing the user to grant permission for the entire directory at once.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "file_path" key
+
+        Returns:
+            `List[PermissionRule]`:
+                A single suggested rule covering the parent directory
+                (e.g., file "/src/main.py" -> rule "src/**")
+        """
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            return []
+
+        parent = self._backend.dirname(file_path)
+        # Glob patterns are POSIX-style strings (matched by fnmatch),
+        # not real filesystem paths — do NOT use backend.join_path here.
+        pattern = (parent.rstrip("/\\") + "/**") if parent else "**"
+
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=pattern,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    async def call(  # type: ignore[override]
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+        _agent_state: AgentState | None = None,
+    ) -> ToolChunk:
+        """Execute the edit and return the result."""
+        # Validate file_path is absolute
+        if not self._backend.isabs(file_path):
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Error: file_path must be an absolute "
+                            f"path, got: {file_path}"
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Check file exists
+        if not await self._backend.file_exists(file_path):
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"Error: File not found: {file_path}"),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Check old_string != new_string
+        if old_string == new_string:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            "Error: old_string and new_string are "
+                            "identical. No changes to make."
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        content = None
+        if _agent_state is not None:
+            cache = await _agent_state.tool_context.get_cache(file_path)
+            if cache is None:
+                # Haven't read this file before
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text="Error: To edit a file, you must first read "
+                            "it using the Read tool.",
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+            content = "".join(cache.lines)
+        else:
+            # No state provided, read from backend
+            try:
+                raw = await self._backend.read_file(file_path)
+                # Normalize CRLF/CR to match the cached-content path and
+                # the LF-based old_string the caller supplies.
+                content = _normalize_newlines(
+                    raw.decode("utf-8", errors="replace"),
+                )
+            except Exception as e:
+                return ToolChunk(
+                    content=[TextBlock(text=f"Error reading file: {str(e)}")],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+
+        # Count occurrences
+        occurrences = content.count(old_string)
+
+        # If occurrences == 0, raise error
+        if occurrences == 0:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Error: old_string not found in {file_path}",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # If occurrences > 1 and not replace_all, raise error
+        if occurrences > 1 and not replace_all:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Error: old_string appears {occurrences} "
+                            f"times in {file_path}. Set replace_all=true "
+                            f"to replace all occurrences, or make "
+                            f"old_string more specific."
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Perform replacement
+        if replace_all:
+            updated_content = content.replace(old_string, new_string)
+        else:
+            updated_content = content.replace(
+                old_string,
+                new_string,
+                1,
+            )
+
+        # Write updated content back to file via backend
+        try:
+            await self._backend.write_file(
+                file_path,
+                updated_content.encode("utf-8"),
+            )
+        except Exception as e:
+            return ToolChunk(
+                content=[TextBlock(text=f"Error writing file: {str(e)}")],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Return success message
+        replacement_msg = (
+            f"all {occurrences} occurrences" if replace_all else "1 occurrence"
+        )
+
+        # Build a unified diff of the change with absolute line numbers so the
+        # web UI can render it with real line numbers and proper inter-hunk
+        # gaps. The diff is kept in ``metadata`` only (not in the textual
+        # output) so it does not bloat the LLM context.
+        diff_text = "".join(
+            difflib.unified_diff(
+                content.splitlines(keepends=True),
+                updated_content.splitlines(keepends=True),
+                fromfile=f"a/{file_path}",
+                tofile=f"b/{file_path}",
+                n=3,
+            ),
+        )
+
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=f"Successfully replaced {replacement_msg} "
+                    f"in {file_path}",
+                ),
+            ],
+            state=ToolResultState.RUNNING,
+            is_last=True,
+            metadata={
+                "diff": diff_text,
+                "file_path": file_path,
+                "occurrences": occurrences if replace_all else 1,
+            },
+        )

src/agentscope/tool/_builtin/_glob.py

@@ -0,0 +1,305 @@
+# -*- coding: utf-8 -*-
+"""The glob tool in agentscope."""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import sys
+from typing import TYPE_CHECKING, Any, List
+
+from ...message import TextBlock, ToolResultState
+from ...permission import (
+    PermissionBehavior,
+    PermissionContext,
+    PermissionDecision,
+    PermissionRule,
+)
+from .._base import ToolBase, ToolMiddlewareBase
+from .._response import ToolChunk
+
+if TYPE_CHECKING:
+    from ._backend import BackendBase
+
+
+def _default_glob_helper_path() -> str:
+    """Resolve the on-disk path of the bundled ``_glob_helper.py`` script.
+
+    Used by :class:`Glob` when no explicit ``glob_helper_path`` is
+    provided (i.e. the local-workspace case). The path is obtained via
+    :mod:`importlib.resources` so it works for both editable and
+    installed packages.
+    """
+    import importlib.resources as _res
+
+    ref = _res.files("agentscope.tool._builtin._scripts").joinpath(
+        "_glob_helper.py",
+    )
+    # as_posix() on a MultiplexedPath / PosixPath gives a str path
+    return str(ref)
+
+
+class Glob(ToolBase):
+    """The glob tool for fast file pattern matching."""
+
+    name: str = "Glob"
+    """The tool name presented to the agent."""
+
+    description: str = """Fast file pattern matching tool that works with
+any codebase size.
+
+Supports glob patterns like "**/*.js" or "src/**/*.ts" and returns
+matching file paths sorted by modification time (newest first).
+
+Use this tool when you need to find files by pattern across the
+codebase."""  # ignore: E501
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": "The glob pattern to match against "
+                "(e.g., '**/*.py', 'src/**/*.ts')",
+            },
+            "path": {
+                "type": "string",
+                "description": "The base directory to search from "
+                "(defaults to current working directory)",
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+
+    def __init__(
+        self,
+        backend: BackendBase | None = None,
+        glob_helper_path: str | None = None,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the glob tool.
+
+        Args:
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use. When ``None``, a
+                :class:`LocalBackend` is created automatically.
+            glob_helper_path (`str | None`, optional):
+                Filesystem path (inside the backend's environment) to
+                the ``_glob_helper.py`` script. When ``None``, the
+                path is resolved from the installed package resources
+                (suitable for :class:`LocalBackend`). Remote backends
+                (Docker, E2B) should pass the path where the script
+                was deployed during workspace initialization.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self._backend = backend or LocalBackend()
+        # When running against the host, invoke the helper with the
+        # current interpreter (``sys.executable``) rather than assuming
+        # ``python3`` is on PATH.
+        self._is_local = isinstance(self._backend, LocalBackend)
+        self._glob_helper_path = (
+            glob_helper_path
+            if glob_helper_path is not None
+            else _default_glob_helper_path()
+        )
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for glob pattern matching.
+
+        Glob is a read-only tool. Return PASSTHROUGH to let the engine
+        handle EXPLORE mode and rule matching.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message="Glob pattern matching is read-only.",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the glob pattern or path.
+
+        Matches rule_content as a glob pattern against the "pattern" or "path"
+        parameters. This allows rules to match either the search pattern itself
+        or the directory being searched. If rule_content is None, matches all
+        invocations (tool-name-level rule).
+
+        Args:
+            rule_content (`str | None`):
+                Glob pattern to match (e.g., "src/**" to match searches in
+                src), or None to match all invocations
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "pattern" and optional "path"
+
+        Returns:
+            `bool`:
+                True if the rule matches the pattern or path, False otherwise
+        """
+        # None = tool-name-level rule, matches everything
+        if rule_content is None:
+            return True
+
+        # Try matching against the search path first
+        path = tool_input.get("path", "")
+        if path and fnmatch.fnmatch(path, rule_content):
+            return True
+
+        # Fall back to matching against the pattern itself
+        pattern = tool_input.get("pattern", "")
+        if pattern and fnmatch.fnmatch(pattern, rule_content):
+            return True
+
+        return False
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the glob search.
+
+        Suggests a rule based on the search path. If no path is provided,
+        suggests a rule for the current directory.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing optional "path" key
+
+        Returns:
+            `List[PermissionRule]`:
+                A single suggested rule covering the search directory
+        """
+        backend_cwd = await self._backend.getcwd()
+        path = tool_input.get("path") or backend_cwd
+
+        # Normalize path and build a glob pattern. Glob patterns are
+        # POSIX-style strings (matched by fnmatch), not real filesystem
+        # paths — do NOT use backend.join_path here.
+        abs_path = self._backend.abspath(path, cwd=backend_cwd)
+        pattern = abs_path.rstrip("/\\") + "/**"
+
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=pattern,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    async def call(  # type: ignore[override]
+        self,
+        pattern: str,
+        path: str | None = None,
+    ) -> ToolChunk:
+        """Execute the glob pattern matching and return the results.
+
+        Invokes the standalone ``_glob_helper.py`` script via
+        ``exec_shell``. The script performs high-performance
+        ``os.walk`` + ``os.scandir`` matching and returns results
+        sorted by modification time (newest first) as JSON.
+
+        This unified path works identically across Local, Docker,
+        and E2B backends.
+
+        Args:
+            pattern (`str`):
+                The glob pattern to match against (e.g. ``**/*.py``).
+            path (`str | None`, optional):
+                Base directory to search from. Defaults to the current
+                working directory when ``None``.
+
+        Returns:
+            `ToolChunk`:
+                On success, the matched file paths joined by newlines
+                (or a "no files found" message). If the base directory
+                is missing or the helper fails, an error chunk with
+                ``ToolResultState.ERROR``.
+        """
+        base_dir = path if path else await self._backend.getcwd()
+
+        # The base must be an existing directory; a regular file would
+        # otherwise be accepted here and fail later with a confusing
+        # error from the helper.
+        if not await self._backend.is_dir(base_dir):
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"Directory not found: {base_dir}"),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Invoke the glob helper script via exec_shell as an argv list
+        # (run directly, without a shell, so no platform-specific
+        # quoting is needed). Use the current interpreter locally
+        # (``python3`` may be absent, e.g. on Windows or venvs exposing
+        # only ``python``); remote backends run inside Linux images
+        # where ``python3`` is the safe choice.
+        python = sys.executable if self._is_local else "python3"
+        command = [
+            python,
+            self._glob_helper_path,
+            "--pattern",
+            pattern,
+            "--base-dir",
+            base_dir,
+        ]
+        result = await self._backend.exec_shell(command, timeout=30.0)
+
+        # A non-zero exit means the helper itself failed (missing
+        # interpreter/script, permission error, …) — surface it rather
+        # than masking it as an empty match.
+        if not result.ok():
+            stderr = result.stderr.decode("utf-8", errors="replace").strip()
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Glob helper failed: {stderr}"
+                        if stderr
+                        else "Glob helper failed with no error output.",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        try:
+            matches = json.loads(
+                result.stdout.decode("utf-8", errors="replace"),
+            )
+        except (json.JSONDecodeError, ValueError):
+            matches = []
+
+        if len(matches) == 0:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"No files found matching pattern: {pattern}",
+                    ),
+                ],
+                state=ToolResultState.RUNNING,
+                is_last=True,
+            )
+
+        return ToolChunk(
+            content=[TextBlock(text="\n".join(matches))],
+            state=ToolResultState.RUNNING,
+            is_last=True,
+        )

src/agentscope/tool/_builtin/_grep.py

@@ -0,0 +1,488 @@
+# -*- coding: utf-8 -*-
+"""The grep tool in agentscope."""
+import fnmatch
+from typing import Any, List, Literal
+
+from .._base import ToolBase, ToolMiddlewareBase
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionRule,
+)
+from .._response import ToolChunk
+from ...message import TextBlock, ToolResultState
+from ._backend import BackendBase
+
+# Version control system directories to exclude from searches
+VCS_DIRECTORIES_TO_EXCLUDE = [
+    ".git",
+    ".svn",
+    ".hg",
+    ".bzr",
+    ".jj",
+    ".sl",
+]
+
+# Default cap on grep results when head_limit is unspecified
+DEFAULT_HEAD_LIMIT = 250
+
+
+class RipgrepTimeoutError(Exception):
+    """Custom error class for ripgrep timeouts."""
+
+    def __init__(self, message: str, partial_results: list[str]):
+        super().__init__(message)
+        self.partial_results = partial_results
+
+
+class Grep(ToolBase):
+    """The grep tool for searching file contents using ripgrep."""
+
+    name: str = "Grep"
+    """The tool name presented to the agent."""
+
+    description: str = """A powerful search tool built on ripgrep
+
+  Usage:
+- ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts per file
+- Context lines: use context parameter or -A/-B/-C for lines after/before/around matches
+- Case-insensitive search: set i to true
+- Multiline regex: set multiline to true for patterns spanning multiple lines
+- Limit results: use head_limit to cap the number of results returned"""  # noqa: E501
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": "The regular expression pattern to search "
+                "for in file contents.",
+            },
+            "path": {
+                "type": "string",
+                "description": "File or directory to search in. Defaults "
+                "to current working directory.",
+            },
+            "output_mode": {
+                "type": "string",
+                "enum": ["content", "files_with_matches", "count"],
+                "description": "Output mode: 'content' shows matching lines "
+                "(supports -A/-B/-C context, -n line numbers, "
+                "head_limit), 'files_with_matches' shows file "
+                "paths (supports head_limit), 'count' shows "
+                "match counts (supports head_limit). "
+                "Defaults to 'files_with_matches'.",
+                "default": "files_with_matches",
+            },
+            "glob": {
+                "type": "string",
+                "description": "Glob pattern to filter files (e.g., '*.js', "
+                "'*.{ts,tsx}').",
+            },
+            "type": {
+                "type": "string",
+                "description": "File type to search (rg --type). "
+                "Common types: js, py, rust, go, java, etc.",
+            },
+            "-A": {
+                "type": "integer",
+                "description": "Number of lines to show after each match. "
+                "Requires output_mode: 'content'.",
+            },
+            "-B": {
+                "type": "integer",
+                "description": "Number of lines to show before each match. "
+                "Requires output_mode: 'content'.",
+            },
+            "-C": {
+                "type": "integer",
+                "description": "Alias for context.",
+            },
+            "context": {
+                "type": "integer",
+                "description": "Number of context lines to show before and "
+                "after matches. Requires output_mode: "
+                "'content'.",
+            },
+            "n": {
+                "type": "boolean",
+                "description": "Show line numbers in output. Requires "
+                "output_mode: 'content'. Defaults to true.",
+                "default": True,
+            },
+            "i": {
+                "type": "boolean",
+                "description": "Case insensitive search.",
+                "default": False,
+            },
+            "case_insensitive": {
+                "type": "boolean",
+                "description": "Case insensitive search (alias for i).",
+                "default": False,
+            },
+            "multiline": {
+                "type": "boolean",
+                "description": "Enable multiline mode where . matches "
+                "newlines and patterns can span lines. "
+                "Default: false.",
+                "default": False,
+            },
+            "head_limit": {
+                "type": "integer",
+                "description": "Limit output to first N lines/entries. "
+                "Defaults to 250 when unspecified. "
+                "Pass 0 for unlimited.",
+                "minimum": 0,
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Skip first N lines/entries before applying "
+                "head_limit. Defaults to 0.",
+                "default": 0,
+                "minimum": 0,
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+
+    def __init__(
+        self,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize the grep tool.
+
+        Args:
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use for shell execution. When
+                ``None``, a :class:`LocalBackend` is created.
+                Ripgrep is always invoked via ``exec_shell`` so that
+                the same code path works for local, Docker, and E2B
+                backends.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self._backend = backend or LocalBackend()
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for grep search."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message="Grep search is read-only.",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the grep search path.
+
+        Matches rule_content as a glob pattern against the "path" parameter.
+        If no path is given, falls back to the current working directory.
+        If rule_content is None, matches all invocations (tool-name-level
+        rule).
+
+        Args:
+            rule_content (`str | None`):
+                Glob pattern to match against the search path (e.g., "src/**"),
+                or None to match all invocations
+            tool_input (`dict[str, Any]`):
+                The tool input data containing optional "path" key
+
+        Returns:
+            `bool`:
+                True if the glob pattern matches the search path, False
+                otherwise
+        """
+        # None = tool-name-level rule, matches everything
+        if rule_content is None:
+            return True
+
+        path = tool_input.get("path", "")
+        if not path:
+            path = await self._backend.getcwd()
+        return fnmatch.fnmatch(path, rule_content)
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the grep search path.
+
+        Suggests a rule based on the search path. If no path is provided,
+        suggests a rule for the current directory.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing optional "path" key
+
+        Returns:
+            `List[PermissionRule]`:
+                A single suggested rule covering the search directory
+        """
+        backend_cwd = await self._backend.getcwd()
+        path = tool_input.get("path") or backend_cwd
+
+        abs_path = self._backend.abspath(path, cwd=backend_cwd)
+        # Glob patterns are POSIX-style strings (matched by fnmatch),
+        # not real filesystem paths — do NOT use backend.join_path here.
+        pattern = abs_path.rstrip("/\\") + "/**"
+
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=pattern,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    def _apply_head_limit(
+        self,
+        items: list[str],
+        limit: int | None,
+        offset: int = 0,
+    ) -> tuple[list[str], int | None]:
+        """Apply head_limit and offset to a list of items.
+
+        Returns (sliced_items, applied_limit_if_truncated).
+        """
+        if limit == 0:
+            return items[offset:], None
+        effective_limit = limit if limit is not None else DEFAULT_HEAD_LIMIT
+        sliced = items[offset : offset + effective_limit]
+        was_truncated = len(items) - offset > effective_limit
+        return sliced, (effective_limit if was_truncated else None)
+
+    async def _run_ripgrep(
+        self,
+        args: list[str],
+        search_path: str,
+        timeout: int = 30,
+    ) -> list[str]:
+        """Run ripgrep and return output lines.
+
+        Builds an argument vector and dispatches it through
+        ``backend.exec_shell`` (which runs the program directly, without
+        a shell), so the same code path works for local, Docker, and E2B
+        backends and needs no platform-specific argument quoting.
+        """
+        command = ["rg", *args, search_path]
+
+        result = await self._backend.exec_shell(
+            command,
+            timeout=float(timeout),
+        )
+
+        if result.exit_code == -1 and result.stderr == b"timed out":
+            raise RipgrepTimeoutError(
+                f"Ripgrep search timed out after {timeout} seconds. "
+                "Try searching a more specific path or pattern.",
+                [],
+            )
+
+        # returncode 0 = matches found, 1 = no matches
+        if result.exit_code not in (0, 1):
+            error_msg = result.stderr.decode(
+                "utf-8",
+                errors="ignore",
+            ).strip()
+            raise RuntimeError(
+                f"ripgrep error (code {result.exit_code}): {error_msg}",
+            )
+
+        raw = result.stdout.decode("utf-8", errors="ignore")
+
+        lines = [
+            line.rstrip("\r") for line in raw.split("\n") if line.rstrip("\r")
+        ]
+        return lines
+
+    async def call(  # type: ignore[override]
+        self,
+        pattern: str,
+        path: str | None = None,
+        output_mode: Literal[
+            "content",
+            "files_with_matches",
+            "count",
+        ] = "files_with_matches",
+        glob: str | None = None,
+        type: str | None = None,  # pylint: disable=redefined-builtin
+        i: bool = False,
+        case_insensitive: bool = False,
+        context: int | None = None,
+        multiline: bool = False,
+        head_limit: int | None = None,
+        offset: int = 0,
+        n: bool = True,
+        **kwargs: Any,
+    ) -> ToolChunk:
+        """Execute the grep search using ripgrep.
+
+        Args:
+            pattern: The regex pattern to search for
+            path: The directory or file path to search in
+            output_mode: Output mode ('content', 'files_with_matches', 'count')
+            glob: Glob pattern to filter files
+            type: File type to filter by (rg --type)
+            i: Case-insensitive search (rg -i)
+            case_insensitive: Alias for i (backward compatibility)
+            context: Number of context lines around matches
+            multiline: Enable multiline regex matching
+            head_limit: Maximum number of results to return
+            (default 250, 0=unlimited)
+            offset: Skip first N results
+            n: Show line numbers (content mode only, default True)
+            **kwargs: Additional parameters (-A, -B, -C)
+        """
+        search_path = path or await self._backend.getcwd()
+
+        if head_limit is not None and head_limit < 0:
+            return ToolChunk(
+                content=[
+                    TextBlock(text="Error: head_limit must be non-negative."),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        if offset < 0:
+            return ToolChunk(
+                content=[
+                    TextBlock(text="Error: offset must be non-negative."),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        args: list[str] = ["--hidden"]
+
+        # Exclude VCS directories
+        for vcs_dir in VCS_DIRECTORIES_TO_EXCLUDE:
+            args.extend(["--glob", f"!{vcs_dir}"])
+
+        # Limit line length to prevent base64/minified content
+        args.extend(["--max-columns", "500"])
+
+        # Multiline mode
+        if multiline:
+            args.extend(["-U", "--multiline-dotall"])
+
+        # Case-insensitive (support both i and case_insensitive
+        # for compatibility)
+        if i or case_insensitive:
+            args.append("-i")
+
+        # Output mode flags
+        if output_mode == "files_with_matches":
+            args.append("-l")
+        elif output_mode == "count":
+            args.append("-c")
+
+        # Line numbers (content mode only)
+        if n and output_mode == "content":
+            args.append("-n")
+
+        # Context flags (content mode only)
+        if output_mode == "content":
+            A = kwargs.get("-A")
+            B = kwargs.get("-B")
+            C = kwargs.get("-C")
+
+            if context is not None:
+                args.extend(["-C", str(context)])
+            elif C is not None:
+                args.extend(["-C", str(C)])
+            else:
+                if B is not None:
+                    args.extend(["-B", str(B)])
+                if A is not None:
+                    args.extend(["-A", str(A)])
+
+        # Pattern — use -e if it starts with a dash
+        if pattern.startswith("-"):
+            args.extend(["-e", pattern])
+        else:
+            args.append(pattern)
+
+        # File type filter
+        if type is not None:
+            args.extend(["--type", type])
+
+        # Glob filter
+        if glob is not None:
+            raw_patterns = glob.split()
+            glob_patterns: list[str] = []
+            for raw in raw_patterns:
+                if "{" in raw and "}" in raw:
+                    glob_patterns.append(raw)
+                else:
+                    glob_patterns.extend(p for p in raw.split(",") if p)
+            for gp in glob_patterns:
+                args.extend(["--glob", gp])
+
+        try:
+            results = await self._run_ripgrep(args, search_path)
+        except RipgrepTimeoutError as e:
+            return ToolChunk(
+                content=[TextBlock(text=str(e))],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+        except RuntimeError as e:
+            return ToolChunk(
+                content=[TextBlock(text=str(e))],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        if not results:
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"No matches found for pattern: {pattern}"),
+                ],
+                state=ToolResultState.SUCCESS,
+                is_last=True,
+            )
+
+        limited, applied_limit = self._apply_head_limit(
+            results,
+            head_limit,
+            offset,
+        )
+
+        suffix = ""
+        if applied_limit is not None:
+            suffix = (
+                f"\n\n[Showing results with pagination = "
+                f"limit: {applied_limit}"
+            )
+            if offset:
+                suffix += f", offset: {offset}"
+            suffix += "]"
+
+        return ToolChunk(
+            content=[TextBlock(text="\n".join(limited) + suffix)],
+            state=ToolResultState.SUCCESS,
+            is_last=True,
+        )

src/agentscope/tool/_builtin/_meta.py

@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""The meta tool class."""
+from typing import Any, List
+
+from pydantic import Field, create_model
+from jinja2 import Template
+
+from .._tool_group import ToolGroup
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .._response import ToolChunk
+from .._base import ToolBase, ToolMiddlewareBase
+from ...exception import DeveloperOrientedException
+from ...message import TextBlock
+from ...state import AgentState
+
+
+class ResetTools(ToolBase):
+    """A meta tool allows agent to self-manage its equipped tools by
+    activating or deactivating tool groups dynamically."""
+
+    name: str = "reset_tools"
+    description: str = (
+        "This tool allows you to reset your equipped tools based on your "
+        "current task requirements. These tools are organized into different "
+        "groups, and you can activate/deactivate them by specifying the "
+        "boolean values for each group in the input.\n\n"
+        "**Important: The input booleans are the final state of their "
+        "corresponding tool groups, not incremental changes.** Any group not "
+        "explicitly set to True will be deactivated, regardless of its "
+        "previous state.\n\n"
+        "**Best practice**: Actively manage your tool groups——activate only "
+        "what you need for the current task, and promptly deactivate groups "
+        "as soon as they are no longer needed to conserve context space.\n\n"
+        "This tool will return the usage instructions for the activated tool "
+        "groups, which you **MUST pay attention to and follow**. You can "
+        "also reuse this tool to re-check the instructions."
+    )
+    is_mcp: bool = False
+    is_read_only: bool = False
+    is_concurrency_safe: bool = True
+    is_external_tool: bool = False
+    is_state_injected: bool = True
+
+    def __init__(
+        self,
+        groups: list[ToolGroup],
+        response_template: str,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the meta tool with the current tool groups."""
+        super().__init__(middlewares=middlewares)
+        self.groups = groups
+        self.response_template = response_template
+
+    @property
+    def input_schema(self) -> dict[str, Any]:  # type: ignore[override]
+        """Dynamically generate the input schema based on the current
+        available tool groups."""
+        fields = {}
+        for group in self.groups:
+            if group.name == "basic":
+                continue
+            fields[group.name] = (
+                bool,
+                Field(
+                    default=False,
+                    description=group.description,
+                ),
+            )
+
+        model = create_model("_DynamicModel", **fields)
+        schema = model.model_json_schema()
+        return schema
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """The meta tool is always allowed to be called."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="The meta tool is always allowed to be called.",
+        )
+
+    async def call(
+        self,
+        _agent_state: AgentState,
+        **kwargs: Any,
+    ) -> ToolChunk:
+        """Activate or deactivate tool groups based on the input arguments,
+        and return their usage instructions."""
+        if _agent_state is None:
+            raise DeveloperOrientedException(
+                "Error: ResetTools requires state to be provided.",
+            )
+
+        # Deactivate all tool groups first
+        _agent_state.tool_context.activated_groups.clear()
+
+        to_activate = []
+        for key, value in kwargs.items():
+            if not isinstance(value, bool):
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=f"Invalid arguments: the argument {key} "
+                            f"should be a bool value, but got {type(value)}.",
+                        ),
+                    ],
+                )
+
+            if value:
+                to_activate.append(key)
+
+        _agent_state.tool_context.activated_groups.extend(to_activate)
+
+        template = Template(self.response_template)
+        activated_groups = [_ for _ in self.groups if _.name in to_activate]
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=template.render(groups=activated_groups),
+                ),
+            ],
+        )