seedcode-cli 6.1.5__py3-none-any.whl

seedcode/tools/git.py

@@ -0,0 +1,72 @@
+"""Git integration tool: a safe subset of git run inside the workspace.
+
+Read subcommands (status, log, diff, ...) work in every permission mode;
+mutating ones (add, commit, checkout, ...) pass the execute gate AND the
+user's Y/A/N confirmation, and remote ones (push, pull, fetch) get their own
+confirmation category — Seed Code never commits or pushes silently. Anything
+outside the allow-list is refused so the model cannot smuggle arbitrary
+commands through the git tool (it must use run_command, which is gated too).
+"""
+
+from __future__ import annotations
+
+import shlex
+from typing import TYPE_CHECKING, Any
+
+from .base import ToolResult, register
+from .permissions import CATEGORY_GIT_MUTATE, CATEGORY_GIT_REMOTE
+from .terminal import run_command
+
+if TYPE_CHECKING:
+    from .permissions import PermissionManager
+
+_READ_SUBCOMMANDS = {"status", "log", "diff", "show", "branch", "remote", "blame", "shortlog"}
+_WRITE_SUBCOMMANDS = {
+    "add", "commit", "checkout", "switch", "restore", "stash",
+    "merge", "rebase", "reset", "revert", "init", "tag", "rm", "mv",
+}
+_REMOTE_SUBCOMMANDS = {"push", "pull", "fetch"}
+_GIT_TIMEOUT_S = 60
+
+
+@register(
+    "git",
+    "Run a git subcommand in the workspace (status, log, diff, add, commit, push, pull, ...).",
+    {"args": "git arguments, e.g. 'status' or 'commit -m \"message\"'"},
+    mutates=True,
+)
+def _git(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    raw = str(args["args"]).strip()
+    if raw.startswith("git "):
+        raw = raw[4:]  # tolerate "git status" as well as "status"
+    if not raw:
+        return ToolResult(False, "No git subcommand given.")
+
+    try:
+        parts = shlex.split(raw)
+    except ValueError as exc:
+        return ToolResult(False, f"Could not parse git arguments: {exc}")
+    sub = parts[0].lower() if parts else ""
+
+    if sub in _WRITE_SUBCOMMANDS:
+        perm.check_execute(f"git {sub}")
+        perm.confirm_action(CATEGORY_GIT_MUTATE, f"git {raw}")
+    elif sub in _REMOTE_SUBCOMMANDS:
+        perm.check_execute(f"git {sub}")
+        perm.confirm_action(CATEGORY_GIT_REMOTE, f"git {raw}")
+    elif sub not in _READ_SUBCOMMANDS:
+        allowed = ", ".join(
+            sorted(_READ_SUBCOMMANDS | _WRITE_SUBCOMMANDS | _REMOTE_SUBCOMMANDS)
+        )
+        return ToolResult(False, f"git subcommand '{sub}' is not allowed. Allowed: {allowed}.")
+
+    # shlex.split validated the quoting; re-quote for the real shell.
+    quoted = " ".join(_quote(p) for p in parts)
+    return run_command(perm, f"git {quoted}", _GIT_TIMEOUT_S)
+
+
+def _quote(part: str) -> str:
+    """Minimal cross-platform quoting (shlex.quote is POSIX-only)."""
+    if part and all(c.isalnum() or c in "-_=./:@^~+%," for c in part):
+        return part
+    return '"' + part.replace('"', '\\"') + '"'

seedcode/tools/patch.py

@@ -0,0 +1,170 @@
+"""Patch tools: precise in-place edits by exact text matching.
+
+``edit_file`` is the agent's scalpel — replace one exact occurrence of a
+string — and ``insert_in_file`` adds a block before/after an exact anchor;
+``write_file`` (filesystem) is the sledgehammer. Multi-file editing is
+several edit/write calls in one turn; each passes the same permission gate
+independently.
+
+Matching happens on ``\\n``-normalized text (see :mod:`seedcode.tools.textio`)
+and the original encoding/line endings are preserved on write, so editing a
+CRLF or latin-1 file never silently converts it.
+
+There is deliberately NO unified-diff applier here: model-generated diffs
+malform often (line-number drift), which converts into retry loops that burn
+the agent's step budget, while exact-match editing gives precise failure
+messages the model can act on. edit_file + insert_in_file + write_file cover
+every edit shape the loop needs.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import ToolResult, register
+from .textio import read_text_file, write_text_file
+
+if TYPE_CHECKING:
+    from .permissions import PermissionManager
+
+
+@register(
+    "edit_file",
+    "Replace an exact text snippet in a file (must match exactly once).",
+    {
+        "path": "file path",
+        "old_text": "exact text currently in the file",
+        "new_text": "replacement text",
+    },
+    mutates=True,
+)
+def _edit_file(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    perm.check_write(path)
+    if not path.is_file():
+        return ToolResult(False, f"File not found: {path}")
+
+    old = str(args["old_text"]).replace("\r\n", "\n")
+    new = str(args["new_text"]).replace("\r\n", "\n")
+    if not old:
+        return ToolResult(False, "old_text is empty — use write_file to create content.")
+    if old == new:
+        return ToolResult(False, "old_text and new_text are identical; nothing to do.")
+
+    try:
+        tf = read_text_file(path)
+    except OSError as exc:
+        return ToolResult(False, f"Could not read {path}: {exc}")
+
+    count = tf.text.count(old)
+    if count == 0:
+        return ToolResult(
+            False,
+            f"old_text was not found in {path}. Read the file again and copy the "
+            "text exactly (whitespace matters).",
+        )
+    if count > 1:
+        return ToolResult(
+            False,
+            f"old_text appears {count} times in {path}. Include more surrounding "
+            "lines so it matches exactly once.",
+        )
+
+    tf.text = tf.text.replace(old, new, 1)
+    expected = tf.text
+    try:
+        write_text_file(path, tf)
+    except OSError as exc:
+        return ToolResult(False, f"Could not write {path}: {exc}")
+
+    # VERIFICATION: the file must read back as exactly what we wrote
+    # (comparing full text — substring checks false-positive when new_text
+    # contains old_text, e.g. "b = 2" -> "b = 20").
+    try:
+        updated = read_text_file(path).text
+        if updated != expected:
+            return ToolResult(
+                False,
+                f"Edit operation completed but verification failed: {path} does "
+                "not match the edited content. The file may have been modified "
+                "by another process."
+            )
+    except OSError as exc:
+        return ToolResult(
+            False,
+            f"Edit completed but verification failed: could not read back {path}: {exc}"
+        )
+
+    return ToolResult(True, f"Edited {path} (1 replacement, verified).")
+
+
+@register(
+    "insert_in_file",
+    "Insert a block of text before or after an exact anchor snippet "
+    "(anchor must match exactly once).",
+    {
+        "path": "file path",
+        "anchor": "exact existing text to anchor on",
+        "position": "'before' or 'after'",
+        "text": "block to insert",
+    },
+    mutates=True,
+)
+def _insert_in_file(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    perm.check_write(path)
+    if not path.is_file():
+        return ToolResult(False, f"File not found: {path}")
+
+    anchor = str(args["anchor"]).replace("\r\n", "\n")
+    block = str(args["text"]).replace("\r\n", "\n")
+    position = str(args["position"]).strip().lower()
+    if position not in ("before", "after"):
+        return ToolResult(False, "position must be 'before' or 'after'.")
+    if not anchor:
+        return ToolResult(False, "anchor is empty — copy an exact snippet from the file.")
+    if not block:
+        return ToolResult(False, "text is empty; nothing to insert.")
+
+    try:
+        tf = read_text_file(path)
+    except OSError as exc:
+        return ToolResult(False, f"Could not read {path}: {exc}")
+
+    count = tf.text.count(anchor)
+    if count == 0:
+        return ToolResult(
+            False,
+            f"anchor was not found in {path}. Read the file again and copy the "
+            "text exactly (whitespace matters).",
+        )
+    if count > 1:
+        return ToolResult(
+            False,
+            f"anchor appears {count} times in {path}. Include more surrounding "
+            "lines so it matches exactly once.",
+        )
+
+    replacement = block + anchor if position == "before" else anchor + block
+    tf.text = tf.text.replace(anchor, replacement, 1)
+    try:
+        write_text_file(path, tf)
+    except OSError as exc:
+        return ToolResult(False, f"Could not write {path}: {exc}")
+
+    # VERIFICATION: Read back to confirm the block landed where intended
+    try:
+        updated = read_text_file(path).text
+        if replacement not in updated:
+            return ToolResult(
+                False,
+                f"Insert completed but verification failed: the inserted block was "
+                f"not found next to the anchor in {path}.",
+            )
+    except OSError as exc:
+        return ToolResult(
+            False,
+            f"Insert completed but verification failed: could not read back {path}: {exc}"
+        )
+
+    return ToolResult(True, f"Inserted {len(block)} chars {position} the anchor in {path} (verified).")

seedcode/tools/permissions.py

@@ -0,0 +1,288 @@
+"""Unified permission system for Seed Code.
+
+A single hierarchical :class:`PermissionLevel` is the one source of truth for
+what the session may do, checked before every privileged operation:
+
+* ``read_only``    — inspect only: no writes, no commands, no git mutations,
+                     no desktop control.
+* ``workspace``    — read anywhere, mutate only inside the workspace directory
+                     (the directory Seed Code was started in); still no desktop.
+* ``desktop``      — everything ``workspace`` allows, plus control of the local
+                     computer through the Computer Engine (mouse, keyboard,
+                     windows, apps, browser, non-sensitive registry reads).
+* ``full_system``  — no path restriction on mutations and sensitive desktop
+                     actions (registry writes, secrets, system power, deletes,
+                     purchases) become available (still confirmed per action).
+
+Levels are ordered (``READ_ONLY < WORKSPACE < DESKTOP < FULL_SYSTEM``) so a
+capability check is a single comparison: ``level >= required``. Desktop
+automation is a *capability of a level*, not a separate mode — the old
+``desktop_mode`` flag is gone.
+
+On top of the levels, *dangerous* actions (shell commands, file deletes, git
+mutations, writes outside the workspace, and every sensitive desktop action)
+ask the user first — the Y/A/N prompt is [Y] once / [A] always for this
+session / [N] cancel. "Always"/"Deny" answers are remembered per category for
+the session only, never persisted; sensitive categories never remember.
+
+The manager is the single gate: tools never check paths or levels themselves,
+they ask :meth:`PermissionManager.require` / :meth:`check_read` /
+:meth:`check_write` / :meth:`check_execute` / :meth:`confirm_action` and let
+the raised error flow back to the model.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, IntEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from ..computer.permissions import DesktopSession
+
+
+class PermissionError_(Exception):
+    """An action was blocked by the current permission level.
+
+    Named with a trailing underscore to avoid shadowing the builtin
+    ``PermissionError`` (raised by the OS for filesystem denials).
+    """
+
+
+class PermissionLevel(IntEnum):
+    """Hierarchical capability level; higher includes everything lower."""
+
+    READ_ONLY = 0
+    WORKSPACE = 1
+    DESKTOP = 2
+    FULL_SYSTEM = 3
+    # Legacy alias: pre-vNext configs used "full_access" for the top level.
+    FULL_ACCESS = 3
+
+    @classmethod
+    def parse(cls, value: "str | PermissionLevel") -> "PermissionLevel":
+        if isinstance(value, PermissionLevel):
+            return value
+        raw = (str(value) or "").strip().lower().replace("-", "_").replace(" ", "_")
+        aliases = {
+            "read": cls.READ_ONLY,
+            "readonly": cls.READ_ONLY,
+            "read_only": cls.READ_ONLY,
+            "ws": cls.WORKSPACE,
+            "workspace": cls.WORKSPACE,
+            "desktop": cls.DESKTOP,
+            "computer": cls.DESKTOP,
+            "full": cls.FULL_SYSTEM,
+            "full_access": cls.FULL_SYSTEM,
+            "fullaccess": cls.FULL_SYSTEM,
+            "full_system": cls.FULL_SYSTEM,
+            "fullsystem": cls.FULL_SYSTEM,
+            "system": cls.FULL_SYSTEM,
+        }
+        level = aliases.get(raw)
+        if level is None:
+            raise ValueError(
+                f"Unknown permission level '{value}'. "
+                "Choose read_only, workspace, desktop, or full_system."
+            )
+        return level
+
+    @property
+    def value_str(self) -> str:
+        """Canonical serialised name for this level."""
+        return {
+            PermissionLevel.READ_ONLY: "read_only",
+            PermissionLevel.WORKSPACE: "workspace",
+            PermissionLevel.DESKTOP: "desktop",
+            PermissionLevel.FULL_SYSTEM: "full_system",
+        }[PermissionLevel(int(self))]
+
+    @property
+    def label(self) -> str:
+        return {
+            PermissionLevel.READ_ONLY: "Read Only",
+            PermissionLevel.WORKSPACE: "Workspace",
+            PermissionLevel.DESKTOP: "Desktop",
+            PermissionLevel.FULL_SYSTEM: "Full System",
+        }[PermissionLevel(int(self))]
+
+    @property
+    def allows_desktop(self) -> bool:
+        """Whether this level may drive the Computer Engine at all."""
+        return int(self) >= int(PermissionLevel.DESKTOP)
+
+
+# Backward-compatible name: older modules import ``PermissionMode`` and
+# reference ``PermissionMode.FULL_ACCESS``. Both resolve through the unified
+# enum now, so a single class serves every caller.
+PermissionMode = PermissionLevel
+
+
+class ActionGrant(str, Enum):
+    """The user's answer to a dangerous-action prompt."""
+
+    ONCE = "once"
+    ALWAYS = "always"
+    DENY = "deny"
+
+
+# Dangerous-action categories. Grants are remembered per category for the
+# session; the descriptions shown to the user always include the concrete
+# action (the exact command / path / git args).
+CATEGORY_SHELL = "shell"                  # run a terminal command
+CATEGORY_GIT_MUTATE = "git_mutate"        # commit / merge / reset / ...
+CATEGORY_GIT_REMOTE = "git_remote"        # push / pull / fetch
+CATEGORY_DELETE = "delete"                # delete a file
+CATEGORY_OUTSIDE_WRITE = "outside_write"  # write outside the workspace
+
+ACTION_LABELS = {
+    CATEGORY_SHELL: "Run a shell command",
+    CATEGORY_GIT_MUTATE: "Change git state",
+    CATEGORY_GIT_REMOTE: "Talk to a git remote",
+    CATEGORY_DELETE: "Delete a file",
+    CATEGORY_OUTSIDE_WRITE: "Write outside the workspace",
+}
+
+# (category, description) -> the user's grant.
+ConfirmAction = Callable[[str, str], "ActionGrant"]
+
+
+@dataclass
+class ActionGate:
+    """Session-scoped Y/A/N confirmation for dangerous core-tool actions.
+
+    The app layer supplies ``confirm`` (wired to the UI prompt); "Always" and
+    "Deny" answers stick for the rest of the session, "Once" asks again next
+    time. Nothing is ever persisted.
+    """
+
+    confirm: ConfirmAction
+    grants: dict[str, "ActionGrant"] = field(default_factory=dict)
+
+    def check(self, category: str, description: str) -> None:
+        granted = self.grants.get(category)
+        if granted is ActionGrant.ALWAYS:
+            return
+        if granted is ActionGrant.DENY:
+            label = ACTION_LABELS.get(category, category)
+            raise PermissionError_(
+                f"Blocked: the user denied '{label}' for this session."
+            )
+        choice = self.confirm(category, description)
+        if choice in (ActionGrant.ALWAYS, ActionGrant.DENY):
+            self.grants[category] = choice
+        if choice is ActionGrant.DENY:
+            raise PermissionError_(
+                f"Blocked: the user denied this action ({description})."
+            )
+
+    def reset(self) -> None:
+        """Forget all session grants."""
+        self.grants.clear()
+
+
+class PermissionManager:
+    """Gatekeeper consulted by every tool before acting."""
+
+    def __init__(
+        self,
+        workspace: Path | None = None,
+        mode: "PermissionLevel | str" = PermissionLevel.WORKSPACE,
+        level: "PermissionLevel | str | None" = None,
+    ) -> None:
+        self.workspace = (workspace or Path.cwd()).resolve()
+        # ``level`` is the canonical field; ``mode`` is accepted as the legacy
+        # keyword and both stay in sync through the ``mode`` property below.
+        self.level = PermissionLevel.parse(level if level is not None else mode)
+        # Desktop Control gate (the Computer Engine); attached by the app layer
+        # when the level allows desktop. None means desktop tools refuse.
+        self.desktop: "DesktopSession | None" = None
+        # Dangerous-action confirmation gate; attached by the app layer. None
+        # means no prompting (headless/tests) — the level checks alone decide.
+        self.gate: ActionGate | None = None
+        # Live command output sink (attached by the app layer): each line a
+        # running terminal command prints is echoed here as it arrives.
+        self.on_output: Callable[[str], None] | None = None
+
+    # --- level (with legacy ``mode`` alias) ----------------------------------
+    @property
+    def mode(self) -> PermissionLevel:
+        """Legacy alias for :attr:`level` (same object)."""
+        return self.level
+
+    @mode.setter
+    def mode(self, value: "PermissionLevel | str") -> None:
+        self.level = PermissionLevel.parse(value)
+
+    def require(self, required: "PermissionLevel | str", description: str = "") -> None:
+        """Raise unless the current level meets ``required``.
+
+        The single capability gate the Computer Engine and every privileged
+        tool consults. Elevation prompting is handled by the app layer (which
+        may raise the level in response); this method only enforces the
+        current level.
+        """
+        needed = PermissionLevel.parse(required)
+        if self.level >= needed:
+            return
+        what = f" ({description})" if description else ""
+        raise PermissionError_(
+            f"Blocked: this needs {needed.label} permission{what}, but the "
+            f"current level is {self.level.label}. The user can raise it with "
+            "/permission."
+        )
+
+    # --- path helpers --------------------------------------------------------
+    def resolve(self, raw: str) -> Path:
+        """Resolve a tool-supplied path (relative paths anchor at the workspace)."""
+        path = Path(str(raw)).expanduser()
+        if not path.is_absolute():
+            path = self.workspace / path
+        return path.resolve()
+
+    def in_workspace(self, path: Path) -> bool:
+        try:
+            path.resolve().relative_to(self.workspace)
+            return True
+        except ValueError:
+            return False
+
+    # --- checks (raise PermissionError_ when blocked) -------------------------
+    def check_read(self, path: Path) -> None:
+        """Reading is allowed at every level."""
+
+    def check_write(self, path: Path) -> None:
+        if self.level < PermissionLevel.WORKSPACE:
+            raise PermissionError_(
+                "Blocked: permission level is Read Only — no file changes allowed. "
+                "The user can raise it with /permission."
+            )
+        if self.level < PermissionLevel.FULL_SYSTEM and not self.in_workspace(path):
+            raise PermissionError_(
+                f"Blocked: '{path}' is outside the workspace ({self.workspace}). "
+                "Only Full System allows changes outside it — "
+                "the user can raise it with /permission full_system."
+            )
+        if self.level >= PermissionLevel.FULL_SYSTEM and not self.in_workspace(path):
+            # Full System allows it, but writing outside the workspace is
+            # dangerous enough to confirm with the user first.
+            self.confirm_action(CATEGORY_OUTSIDE_WRITE, str(path))
+
+    def check_execute(self, description: str = "") -> None:
+        """Commands and git mutations need more than Read Only."""
+        if self.level < PermissionLevel.WORKSPACE:
+            what = f" ({description})" if description else ""
+            raise PermissionError_(
+                f"Blocked: permission level is Read Only — cannot execute{what}. "
+                "The user can raise it with /permission."
+            )
+
+    def confirm_action(self, category: str, description: str) -> None:
+        """Ask the user to confirm a dangerous action (no-op without a gate).
+
+        Raises :class:`PermissionError_` when the user denies; the message
+        flows back to the model like any other permission refusal.
+        """
+        if self.gate is not None:
+            self.gate.check(category, description)

seedcode/tools/search.py

@@ -0,0 +1,137 @@
+"""Search tools: filename glob and text search across the workspace.
+
+Pure-Python (pathlib + a linear scan) so search works identically on Windows,
+Linux, and macOS with no external binaries.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .base import ToolResult, register
+from .filesystem import _INDEX_SKIP
+
+if TYPE_CHECKING:
+    from .permissions import PermissionManager
+
+_MAX_MATCHES = 100
+_MAX_FILE_BYTES = 1024 * 1024  # skip anything bigger — likely binary/asset
+
+
+def _iter_files(root: Path):
+    """Workspace files, skipping caches/VCS dirs and hidden entries."""
+    stack = [root]
+    while stack:
+        current = stack.pop()
+        try:
+            entries = sorted(current.iterdir(), key=lambda p: p.name.lower())
+        except OSError:
+            continue
+        for entry in entries:
+            if entry.name in _INDEX_SKIP or entry.name.startswith("."):
+                continue
+            if entry.is_dir():
+                stack.append(entry)
+            elif entry.is_file():
+                yield entry
+
+
+def _glob_to_regex(pattern: str) -> "re.Pattern[str]":
+    """Compile a path glob ('src/**/*.py') to a regex over posix paths.
+
+    ``**/`` matches any directory depth (including none), ``**`` any run of
+    characters, ``*`` within one segment, ``?`` one character.
+    (``PurePath.full_match`` needs Python 3.13; this supports 3.10+.)
+    """
+    out: list[str] = []
+    i = 0
+    while i < len(pattern):
+        ch = pattern[i]
+        if pattern.startswith("**/", i):
+            out.append(r"(?:[^/]+/)*")
+            i += 3
+        elif pattern.startswith("**", i):
+            out.append(r".*")
+            i += 2
+        elif ch == "*":
+            out.append(r"[^/]*")
+            i += 1
+        elif ch == "?":
+            out.append(r"[^/]")
+            i += 1
+        else:
+            out.append(re.escape(ch))
+            i += 1
+    return re.compile("".join(out) + r"\Z")
+
+
+@register(
+    "find_files",
+    "Find files by glob: a name pattern ('*.py') or a path pattern "
+    "('src/**/*.py', relative to the workspace).",
+    {"pattern": "glob matched against file names, or paths when it contains '/'"},
+    mutates=False,
+)
+def _find_files(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    pattern = str(args["pattern"]).replace("\\", "/")
+    path_mode = "/" in pattern
+    path_regex = _glob_to_regex(pattern) if path_mode else None
+
+    matches = []
+    for path in _iter_files(perm.workspace):
+        if path_mode:
+            rel = path.relative_to(perm.workspace).as_posix()
+            matched = path_regex.match(rel) is not None
+        else:
+            matched = fnmatch.fnmatch(path.name, pattern)
+        if matched:
+            matches.append(str(path.relative_to(perm.workspace)))
+            if len(matches) >= _MAX_MATCHES:
+                matches.append(f"... (capped at {_MAX_MATCHES})")
+                break
+    if not matches:
+        return ToolResult(True, f"No files matching '{pattern}'.")
+    return ToolResult(True, "\n".join(matches))
+
+
+@register(
+    "search_text",
+    "Search file contents for a regex; returns file:line matches.",
+    {
+        "pattern": "regular expression",
+        "glob": "(optional) only search files whose name matches this glob",
+    },
+    mutates=False,
+)
+def _search_text(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    try:
+        regex = re.compile(str(args["pattern"]))
+    except re.error as exc:
+        return ToolResult(False, f"Invalid regex: {exc}")
+    name_glob = str(args.get("glob") or "*")
+
+    hits: list[str] = []
+    for path in _iter_files(perm.workspace):
+        if not fnmatch.fnmatch(path.name, name_glob):
+            continue
+        try:
+            if path.stat().st_size > _MAX_FILE_BYTES:
+                continue
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if "\x00" in text[:1024]:  # binary sniff
+            continue
+        rel = path.relative_to(perm.workspace)
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            if regex.search(line):
+                hits.append(f"{rel}:{lineno}: {line.strip()[:200]}")
+                if len(hits) >= _MAX_MATCHES:
+                    hits.append(f"... (capped at {_MAX_MATCHES})")
+                    return ToolResult(True, "\n".join(hits))
+    if not hits:
+        return ToolResult(True, f"No matches for '{args['pattern']}'.")
+    return ToolResult(True, "\n".join(hits))