tools.py

"""Claude Code style tools, every one scoped to a workspace (see workspaces.py).

Docstrings are the tool descriptions the model sees (Gradio builds the MCP schema from
them), so they are written for the model. Errors are returned as "error: ..." text.
"""

import fnmatch
import glob as _glob
import ipaddress
import inspect
import json
import os
import re
import secrets
import shlex
import shutil
import signal
import socket
import subprocess
import threading
import time
from pathlib import Path
from urllib.parse import urljoin, urlsplit

import workspaces as W
import runtime_client as R

MAX_OUTPUT = 30_000
SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", ".cache"}
_SECRET_HINTS = ("TOKEN", "SECRET", "KEY", "PASSWORD", "CREDENTIAL")


def _clip(text: str, limit: int = MAX_OUTPUT) -> str:
    if len(text) <= limit:
        return text
    half = limit // 2
    return f"{text[:half]}\n... [{len(text) - limit} characters truncated] ...\n{text[-half:]}"


def _ws(workspace: str) -> W.Workspace:
    return W.get(workspace, touch=False, restore=False, allow_paused=True)


def _atomic_write_text(path: Path, content: str) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    temp = path.with_name(f".{path.name}.{secrets.token_hex(4)}.tmp")
    try:
        temp.write_text(content, encoding="utf-8")
        if path.exists():
            os.chmod(temp, path.stat().st_mode & 0o7777)
        os.replace(temp, path)
    except Exception:
        temp.unlink(missing_ok=True)
        raise


def _autosave(ws: W.Workspace) -> str:
    try:
        R.get_client().request("dirty", workspace=ws.id)
        return "\nChanges recorded; checkpoint work is scheduled independently."
    except Exception as exc:  # file changes already succeeded; report checkpoint separately
        return f"\nWarning: workspace edit succeeded, but checkpoint failed: {type(exc).__name__}: {exc}"


def _numbered(lines: list[str], start: int = 1) -> str:
    return "\n".join(f"{i:>6}\t{ln[:2000]}" for i, ln in enumerate(lines, start))


def _guard(fn):
    """Turn workspace/IO errors into 'error: ...' text instead of tracebacks."""
    import functools

    @functools.wraps(fn)
    def wrapper(*args, **kwargs):
        lease = None
        file_tools = {"Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "LS", "TodoWrite", "WorkflowNew"}
        try:
            bound = inspect.signature(fn).bind_partial(*args, **kwargs)
            workspace_id = bound.arguments.get("workspace")
            if workspace_id and fn.__name__ in file_tools:
                changing = fn.__name__ in {"Write", "Edit", "MultiEdit", "TodoWrite", "WorkflowNew"}
                requested = len(str(bound.arguments.get("content", "")).encode())
                if fn.__name__ == "Edit":
                    requested = len(str(bound.arguments.get("new_string", "")).encode())
                elif fn.__name__ == "MultiEdit":
                    requested = sum(len(str(edit.get("new_string", "")).encode()) for edit in bound.arguments.get("edits", []))
                lease = R.get_client().request("begin", workspace=str(workspace_id), write=changing,
                                               bytes_needed=requested,
                                               pid=os.getpid() if os.environ.get("CCMCP_TOOL_WORKER") else None)
            result = fn(*args, **kwargs)
        except W.WorkspaceError as exc:
            result = f"error: {exc}"
        except Exception as exc:  # noqa: BLE001 - surface any failure to the model
            result = f"error: {type(exc).__name__}: {exc}"
        finally:
            if lease:
                try:
                    R.get_client().request("end", lease=lease)
                except Exception:
                    pass
        try:
            bound = inspect.signature(fn).bind_partial(*args, **kwargs)
            workspace_id = bound.arguments.get("workspace")
            if workspace_id:
                notices = _drain_background_notices(str(workspace_id))
                if notices:
                    result = f"{result}\n\nBackground job updates:\n" + "\n".join(notices)
        except Exception:
            # A notification must never turn an otherwise successful tool call into
            # an error; the job metadata remains available through BackgroundJobs.
            pass
        return result

    return wrapper


# --------------------------------------------------------------------------- workspaces


@_guard
def workspace_new(title: str = "") -> str:
    """Create a workspace on the remote computer. Call this once at the start of a conversation. Then pass the returned id as `workspace` in every tool call of this conversation. Use WorkflowNew for independent tasks.

    Args:
        title: Short label for the workspace, e.g. the task being worked on.

    Returns:
        The workspace id and its working directory.
    """
    ws = W.create(title)
    R.get_client().request("register", workspace=ws.id, meta=ws.meta())
    return (
        f"Workspace created: {ws.id}\n"
        f"Working directory: {ws.work}\n"
        f"Rules: pass workspace=\"{ws.id}\" in every tool call of this conversation, and mention "
        f"`workspace: {ws.id}` in your replies. Prefer absolute paths."
    )


@_guard
def workspace_list() -> str:
    """List existing workspaces, most recently used first. Use it to recover the id of a workspace when this conversation has lost it, or to resume older work.

    Returns:
        One line per workspace: id, title, last used time.
    """
    rows = []
    for m in R.get_client().request("overview")["workspaces"][:50]:
        last = time.strftime("%Y-%m-%d %H:%M", time.localtime(m.get("last_used", 0)))
        rows.append(
            f"{m['id']}  kind={m.get('kind', 'workspace')}  status={m.get('status', 'idle')} "
            f"last_used={last}  checkpoint={m.get('latest_checkpoint') or 'none'} "
            f"title={m.get('title') or '-'}"
        )
    return "\n".join(rows) or "(no workspaces)"


@_guard
def workspace_delete(workspace: str) -> str:
    """Permanently delete a workspace and all its files. Only do this when the user asks.

    Args:
        workspace: Workspace id to delete.

    Returns:
        Confirmation.
    """
    ws = W.Workspace(W.normalize(workspace))
    descendants = {ws.id}
    changed = True
    while changed:
        changed = False
        for candidate in W.list_all():
            if candidate.id not in descendants and candidate.meta().get("parent_id") in descendants:
                descendants.add(candidate.id)
                changed = True
    for ws_id in descendants:
        _kill_all_shells(ws_id)
    deadline = time.monotonic() + 4
    while True:
        busy = [row for row in R.get_client().request("overview")["workspaces"] if row["id"] in descendants and
                (row["running_jobs"] or row["queued_jobs"] or row["file_operations"] or row["status"] in {"saving", "restoring", "hibernating"})]
        if not busy:
            break
        if time.monotonic() >= deadline:
            return "error: process/maintenance cancellation is pending; inspect JobStatus and retry deletion after it finishes"
        time.sleep(.05)
    W.delete(ws.id)
    R.get_client().request("forget", workspace=ws.id)
    return f"deleted {ws.id}"


@_guard
def WorkspaceCheckpoint(workspace: str) -> str:
    """Schedule a compressed checkpoint without blocking the MCP response.

    Call before pausing a long project or before a risky batch of changes. Known secret files
    and dependency caches are excluded; attach an HF Storage Bucket at /data for persistence
    across Space restarts.

    Args:
        workspace: Workspace or workflow id.

    Returns:
        Maintenance job id. Inspect it with JobStatus.
    """
    job = R.get_client().request("maintenance", workspace=W.normalize(workspace), operation="checkpoint")
    return f"checkpoint queued: {job['id']}; inspect it with JobStatus"


@_guard
def WorkflowNew(workspace: str, title: str) -> str:
    """Create an isolated workflow workspace under the current conversation workspace.

    Args:
        workspace: Parent workspace id from workspace_new.
        title: Short name for this independent workflow.

    Returns:
        A new workspace id. Pass that id as `workspace` to every tool used by this workflow.
    """
    parent = _ws(workspace)
    workflow = W.create(title, parent_id=parent.id, kind="workflow")
    R.get_client().request("register", workspace=workflow.id, meta=workflow.meta())
    return (
        f"Workflow created: {workflow.id}\n"
        f"Title: {title.strip()[:120] or '(untitled)'}\n"
        f"Working directory: {workflow.work}\n"
        f"Use workspace=\"{workflow.id}\" in all tools for this workflow."
    )


@_guard
def WorkflowList(workspace: str) -> str:
    """List workflows created from this parent workspace, including status and checkpoint.

    Args:
        workspace: Parent workspace id returned by workspace_new.

    Returns:
        One workflow per line with id, status and latest checkpoint.
    """
    rows = []
    for meta in R.get_client().request("overview")["workspaces"]:
        if meta.get("parent_id") != W.normalize(workspace):
            continue
        if meta.get("kind") != "workflow":
            continue
        checkpoint = meta.get("latest_checkpoint") or "none"
        rows.append(
            f"{meta['id']} status={meta.get('status', 'idle')} "
            f"checkpoint={checkpoint} title={meta.get('title') or '-'}"
        )
    return "\n".join(rows) or "(no workflows)"


@_guard
def WorkflowPause(workspace: str) -> str:
    """Hibernate and manually pause an idle workflow. Inspect the returned maintenance id with JobStatus.

    Args:
        workspace: Workflow id returned by WorkflowNew.
    """
    row = next((row for row in R.get_client().request("overview")["workspaces"] if row["id"] == W.normalize(workspace)), None)
    if not row or row.get("kind") != "workflow":
        return "error: WorkflowPause expects a workflow id returned by WorkflowNew"
    return WorkspaceHibernate.__wrapped__(workspace, manual=True)


@_guard
def WorkflowResume(workspace: str) -> str:
    """Restore a manually paused workflow asynchronously; inspect the maintenance id with JobStatus.

    Args:
        workspace: Workflow id returned by WorkflowNew.
    """
    return WorkspaceResume.__wrapped__(workspace)


# --------------------------------------------------------------------------- supervised commands


def _drain_background_notices(ws_id: str) -> list[str]:
    return R.get_client().request("notices", workspace=W.normalize(ws_id))


def _kill_all_shells(ws_id: str) -> None:
    R.get_client().request("stop", workspace=W.normalize(ws_id), recursive=False)


def _load_job(ws: W.Workspace, bash_id: str) -> dict | None:
    try:
        return R.get_client().request("job", workspace=ws.id, job_id=bash_id)
    except RuntimeError:
        return None


def _refresh_background_jobs(ws: W.Workspace) -> None:
    # Process exits are continuously observed by the independent supervisor.
    return None


@_guard
def Bash(workspace: str, command: str, timeout: int = 60, run_in_background: bool = False,
         memory_gb: float = 2, execution_timeout: int = 3600, request_id: str = "") -> str:
    """Run a tracked command on the remote Linux computer. Every command has a job id and bounded logs.

    The Space has one shared execution pool. A workspace and its child workflows
    share at least 1 vCPU when admitted; other workspaces queue. Short calls wait
    at most five seconds and then return the same running job in the background.
    Use JobStatus/BackgroundJobs for status, BashOutput for logs and JobCancel or
    KillShell to cancel any command. Output/status calls do not prevent hibernation.
    File changes persist on the mounted Bucket; checkpoints run independently.

    Args:
        workspace: Workspace or workflow id.
        command: Non-interactive bash command. cd persists; exported environment variables do not.
        timeout: Maximum foreground wait, capped at five seconds; it does not kill the job.
        run_in_background: Return the job id immediately without waiting.
        memory_gb: RAM reservation for this command, 0.256 to 12 GB, shared within the global 12 GB pool.
        execution_timeout: Execution deadline in seconds, 1 to 86400, independent of the MCP wait.
        request_id: Optional unique retry key; reusing it with the same command returns the original job.
    """
    client = R.get_client()
    workspace = W.normalize(workspace)
    job = client.request("submit", workspace=workspace, command=command, memory_gb=memory_gb,
                         execution_timeout=execution_timeout, request_id=request_id)
    if not run_in_background:
        job = client.wait(workspace, job["id"], max(0, min(5, int(timeout))))
    if job["status"] in {"queued", "preparing", "running", "cancelling"}:
        prefix = "started background shell" if job["status"] == "running" else "accepted background shell"
        return f"{prefix} {job['id']} (status={job['status']} pid={job.get('pid') or '-'}). " +                (f"Queue: {job.get('queue_reason')}. " if job.get('queue_reason') else "") +                "Use JobStatus, BashOutput and JobCancel; the command is not killed when this tool returns."
    log = client.request("logs", workspace=workspace, job_id=job["id"], offset=0, max_bytes=MAX_LOG_READ_BYTES)
    return _clip(log["content"] + f"\n[job={job['id']} status={job['status']} exit code: {job.get('exit_code')} next_offset={log['next_offset']}]" +
                 (f"\n{job['reason']}" if job.get('reason') else ""))


MAX_LOG_READ_BYTES = 20_000


@_guard
def BashOutput(workspace: str, bash_id: str, filter: str = "", offset: int = -1, max_bytes: int = MAX_LOG_READ_BYTES) -> str:
    """Read bounded, cursor-based logs for any command. This does not wake a hibernated workspace.

    Args:
        workspace: Workspace or workflow id.
        bash_id: Job id returned by Bash.
        filter: Optional regular expression to filter this bounded log chunk.
        offset: Absolute byte cursor; -1 continues from the saved cursor.
        max_bytes: Maximum bytes, capped at 20000.
    """
    log = R.get_client().request("logs", workspace=W.normalize(workspace), job_id=bash_id,
                                 offset=offset, max_bytes=max_bytes)
    text = log["content"]
    if filter:
        rx = re.compile(filter)
        text = "\n".join(line for line in text.splitlines() if rx.search(line))
    return _clip(text + f"\n[status={log['status']} exit_code={log.get('exit_code')} next_offset={log['next_offset']} " +
                 f"unread_bytes={log['unread_bytes']} dropped_log_bytes={log['dropped_log_bytes']}]" )


@_guard
def KillShell(workspace: str, shell_id: str) -> str:
    """Cancel a queued, foreground or background command and its process group.

    Args:
        workspace: Workspace or workflow id.
        shell_id: Job id returned by Bash.
    """
    job = R.get_client().request("cancel", workspace=W.normalize(workspace), job_id=shell_id)
    return f"{job['id']} status={job['status']}; cancellation does not require a checkpoint; logs remain available"


@_guard
def JobCancel(workspace: str, job_id: str) -> str:
    """Cancel any tracked command without waiting for filesystem operations.

    Args:
        workspace: Workspace or workflow id.
        job_id: Command id returned by Bash.
    """
    return KillShell.__wrapped__(workspace, job_id)


@_guard
def JobStatus(workspace: str, job_id: str) -> str:
    """Inspect a command or checkpoint/hibernation/restoration operation without waking its workspace.

    Args:
        workspace: Workspace or workflow id.
        job_id: Command or maintenance id.
    """
    return json.dumps(R.get_client().request("job", workspace=W.normalize(workspace), job_id=job_id), ensure_ascii=False)


@_guard
def BackgroundJobs(workspace: str) -> str:
    """List all queued, running and completed commands, including former foreground commands.

    Args:
        workspace: Workspace or workflow id.
    """
    row = next((row for row in R.get_client().request("overview")["workspaces"] if row["id"] == W.normalize(workspace)), None)
    if row is None:
        return "error: unknown workspace"
    return "\n".join(f"{job['id']} status={job['status']} exit_code={job.get('exit_code')} " +
                      (f"queue={job.get('queue_reason')} " if job.get('queue_reason') else "") +
                      "command=" + " ".join(job["command"].split())[:180] for job in row["jobs"]) or "(no jobs)"


@_guard
def BackgroundWait(workspace: str, bash_id: str, wait_seconds: int = 20) -> str:
    """Wait for up to 20 seconds for a tracked command; it continues when the wait expires.

    Args:
        workspace: Workspace or workflow id.
        bash_id: Command id returned by Bash.
        wait_seconds: Maximum wait, 0 to 20 seconds.
    """
    job = R.get_client().wait(W.normalize(workspace), bash_id, max(0, min(20, int(wait_seconds))))
    return f"{job['id']}: status={job['status']} exit_code={job.get('exit_code')}; call BashOutput for logs"


@_guard
def WorkspaceHibernate(workspace: str, manual: bool = False) -> str:
    """Save a complete verified checkpoint and hibernate an idle workspace/workflow asynchronously.

    Running commands/file operations must finish or be cancelled first. Full hibernation
    archives include project secrets and dependencies, so the Bucket must be private.
    Automatic hibernation restores on demand; manual pauses require WorkspaceResume.

    Args:
        workspace: Workspace or workflow id.
        manual: Require an explicit resume instead of waking on the next command.
    """
    job = R.get_client().request("maintenance", workspace=W.normalize(workspace), operation="hibernate", manual=manual)
    return f"hibernation status={job['status']} operation={job['id'] or 'already-hibernated'}; inspect JobStatus"


@_guard
def WorkspaceResume(workspace: str) -> str:
    """Restore a hibernated/manually paused workspace without blocking the MCP response.

    Args:
        workspace: Workspace or workflow id.
    """
    job = R.get_client().request("maintenance", workspace=W.normalize(workspace), operation="restore")
    return f"resume status={job['status']} operation={job['id'] or 'already-ready'}; inspect JobStatus before file operations"


@_guard
def WorkspaceStop(workspace: str, include_workflows: bool = False) -> str:
    """Cancel commands in a workspace, optionally including child workflows; retain project files.

    Args:
        workspace: Workspace or workflow id.
        include_workflows: Also cancel commands belonging to child workflows.
    """
    jobs = R.get_client().request("stop", workspace=W.normalize(workspace), recursive=include_workflows)
    return f"stop requested for {len(jobs)} commands; files and logs are retained"


@_guard
def ResourceStatus(workspace: str = "") -> str:
    """Report the global CPU/RAM/50 GB budgets and actual per-workspace allocations.

    Args:
        workspace: Optional workspace/workflow id; empty returns the shared pool.
    """
    data = R.get_client().request("overview")
    result = {"scheduler": data["scheduler"], "storage": data["storage"]}
    if workspace:
        row = next((row for row in data["workspaces"] if row["id"] == W.normalize(workspace)), None)
        if row is None:
            return "error: unknown workspace"
        result["workspace"] = {key: row.get(key) for key in ("id", "status", "resources", "maintenance_error")}
    return json.dumps(result, ensure_ascii=False)


@_guard
def ProcessList(workspace: str) -> str:
    """List tracked commands with PID, state and resource estimates without running Bash.

    Args:
        workspace: Workspace or workflow id.
    """
    row = next((row for row in R.get_client().request("overview")["workspaces"] if row["id"] == W.normalize(workspace)), None)
    return json.dumps(row["jobs"] if row else [], ensure_ascii=False)


# --------------------------------------------------------------------------- files


@_guard
def Read(workspace: str, file_path: str, offset: int = 1, limit: int = 2000) -> str:
    """Read a text file. Returns lines prefixed with line numbers (cat -n style). Always Read a file before you Edit it.

    Args:
        workspace: Workspace id of this conversation.
        file_path: Absolute path (relative paths resolve from the current directory).
        offset: 1-based line number to start from.
        limit: Maximum number of lines to return.

    Returns:
        The numbered lines.
    """
    ws = _ws(workspace)
    p = ws.path(file_path)
    if p.is_dir():
        return f"error: {p} is a directory; use LS"
    if not p.is_file():
        return f"error: file not found: {p}"
    count = max(1, min(int(limit), 2000))
    start = max(1, int(offset))
    chunk = []
    with p.open("rb") as source:
        if b"\0" in source.read(8192):
            return "error: file looks binary"
        source.seek(0)
        # Bounded readline also protects against a single multi-gigabyte line.
        line_number = 1
        while line_number < start:
            piece = source.readline(64 * 1024)
            if not piece:
                return f"error: offset {start} is past the end of the file"
            if piece.endswith(b"\n"):
                line_number += 1
        for _ in range(count):
            first = source.readline(64 * 1024)
            if not first:
                break
            truncated = len(first) == 64 * 1024 and not first.endswith(b"\n")
            if truncated:
                while True:
                    piece = source.readline(64 * 1024)
                    if not piece or piece.endswith(b"\n"):
                        break
            chunk.append(first[:2000].decode(errors="replace").rstrip("\r\n") + (" [long line truncated]" if truncated else ""))
        more = bool(source.read(1))
    if not chunk:
        return "(file is empty)"
    note = f"\n[showing lines {start}-{start + len(chunk)-1}; more lines available]" if more else ""
    return _clip(_numbered(chunk, start) + note)


@_guard
def Write(workspace: str, file_path: str, content: str) -> str:
    """Create a file or completely overwrite an existing one (parent folders are created). To change part of an existing file use Edit instead.

    Args:
        workspace: Workspace id of this conversation.
        file_path: Absolute path (relative paths resolve from the current directory).
        content: The full file content.

    Returns:
        Confirmation.
    """
    ws = _ws(workspace)
    p = ws.path(file_path)
    if p.is_dir():
        return f"error: {p} is a directory"
    existed = p.exists()
    _atomic_write_text(p, content)
    return f"{'Overwrote' if existed else 'Created'} {p} ({content.count(chr(10)) + 1} lines, {len(content.encode())} bytes)" + _autosave(ws)


def _apply_edit(text: str, old: str, new: str, replace_all: bool) -> str:
    if old == new:
        raise ValueError("old_string and new_string are identical")
    if not old:
        raise ValueError("old_string is empty (use Write to create a file)")
    count = text.count(old)
    if count == 0:
        raise ValueError("old_string not found. It must match exactly, including whitespace and indentation")
    if count > 1 and not replace_all:
        raise ValueError(
            f"old_string appears {count} times. Add surrounding context to make it unique, or set replace_all=true"
        )
    return text.replace(old, new) if replace_all else text.replace(old, new, 1)


@_guard
def Edit(workspace: str, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> str:
    """Replace an exact string in an existing file. old_string must match the file exactly (whitespace included) and be unique unless replace_all is true. Read the file first.

    Args:
        workspace: Workspace id of this conversation.
        file_path: Absolute path of the file to modify.
        old_string: The exact text to replace.
        new_string: The replacement text.
        replace_all: Replace every occurrence instead of requiring a unique match.

    Returns:
        Confirmation with a numbered snippet around the change.
    """
    ws = _ws(workspace)
    p = ws.path(file_path)
    if not p.is_file():
        return f"error: file not found: {p}"
    if p.stat().st_size > 8 * 1024 * 1024:
        return "error: atomic edits are limited to 8 MiB; use a streaming Bash job for larger files"
    text = p.read_text(encoding="utf-8", errors="replace")
    try:
        updated = _apply_edit(text, old_string, new_string, replace_all)
    except ValueError as exc:
        return f"error: {exc}"
    _atomic_write_text(p, updated)
    first = updated.find(new_string) if new_string else 0
    line_no = updated.count("\n", 0, max(first, 0)) + 1
    lines = updated.splitlines()
    lo = max(0, line_no - 4)
    return f"Edited {p}. Snippet:\n{_numbered(lines[lo : line_no + 3 + new_string.count(chr(10))], lo + 1)}" + _autosave(ws)


@_guard
def MultiEdit(workspace: str, file_path: str, edits: list[dict]) -> str:
    """Apply several Edit operations to ONE file in order, atomically (if any edit fails nothing is written). Each edit sees the result of the previous one.

    Args:
        workspace: Workspace id of this conversation.
        file_path: Absolute path of the file to modify.
        edits: List of objects {"old_string": str, "new_string": str, "replace_all": bool (optional)}.

    Returns:
        Confirmation.
    """
    ws = _ws(workspace)
    p = ws.path(file_path)
    if not p.is_file():
        return f"error: file not found: {p}"
    if p.stat().st_size > 8 * 1024 * 1024:
        return "error: atomic edits are limited to 8 MiB; use a streaming Bash job for larger files"
    text = p.read_text(encoding="utf-8", errors="replace")
    for i, e in enumerate(edits or [], 1):
        try:
            text = _apply_edit(text, e["old_string"], e["new_string"], bool(e.get("replace_all", False)))
        except (ValueError, KeyError) as exc:
            return f"error: edit #{i} failed ({exc}). Nothing was written."
    _atomic_write_text(p, text)
    return f"Applied {len(edits)} edits to {p}" + _autosave(ws)


@_guard
def Glob(workspace: str, pattern: str, path: str = "") -> str:
    """Find files by glob pattern (e.g. "**/*.py", "src/**/*.ts"), newest first. Skips .git, node_modules and caches.

    Args:
        workspace: Workspace id of this conversation.
        pattern: Glob pattern; ** matches any depth.
        path: Directory to search in. Empty means the current directory.

    Returns:
        Absolute file paths, one per line.
    """
    ws = _ws(workspace)
    base = ws.path(path) if path else ws.cwd()
    if not base.is_dir():
        return f"error: not a directory: {base}"
    hits = []
    for rel in _glob.iglob(pattern, root_dir=base, recursive=True, include_hidden=True):
        full = base / rel
        if full.is_file() and not (set(Path(rel).parts) & SKIP_DIRS):
            hits.append(full)
            if len(hits) >= 1000:
                break
    hits.sort(key=lambda f: f.stat().st_mtime, reverse=True)
    out = "\n".join(str(h) for h in hits[:250])
    return (out + (f"\n[{len(hits) - 250} more not shown]" if len(hits) > 250 else "")) or "(no matches)"


def _py_grep(base: Path, pattern, glob_pat, flags, mode, ctx_b, ctx_a, line_numbers, multiline) -> list[str]:
    rx = re.compile(pattern, flags | (re.DOTALL | re.MULTILINE if multiline else 0))
    files: list[Path] = [base] if base.is_file() else []
    if base.is_dir():
        for root, dirs, names in os.walk(base):
            dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
            files.extend(Path(root) / n for n in sorted(names))
    out: list[str] = []
    for f in files:
        if glob_pat and not fnmatch.fnmatch(f.name, glob_pat) and not fnmatch.fnmatch(str(f), glob_pat):
            continue
        try:
            if f.is_symlink() or f.stat().st_size > 8 * 1024 * 1024:
                continue
            raw = f.read_bytes()
        except OSError:
            continue
        if b"\0" in raw[:8192]:
            continue
        text = raw.decode(errors="replace")
        if multiline:
            n = len(rx.findall(text))
            if n:
                out.append(f"{f}:{n}" if mode == "count" else str(f))
            continue
        lines = text.splitlines()
        hit = [i for i, ln in enumerate(lines) if rx.search(ln)]
        if not hit:
            continue
        if mode == "files_with_matches":
            out.append(str(f))
        elif mode == "count":
            out.append(f"{f}:{len(hit)}")
        else:
            shown: set[int] = set()
            for i in hit:
                shown.update(range(max(0, i - ctx_b), min(len(lines), i + ctx_a + 1)))
            for i in sorted(shown):
                sep = ":" if i in hit else "-"
                out.append(f"{f}{sep}{i + 1}{sep}{lines[i][:500]}" if line_numbers else f"{f}{sep}{lines[i][:500]}")
    return out


@_guard
def Grep(
    workspace: str,
    pattern: str,
    path: str = "",
    glob: str = "",
    output_mode: str = "files_with_matches",
    case_insensitive: bool = False,
    line_numbers: bool = True,
    context_before: int = 0,
    context_after: int = 0,
    multiline: bool = False,
    head_limit: int = 250,
) -> str:
    """Search file contents with a regular expression (ripgrep). Respects .gitignore, skips binary files.

    Args:
        workspace: Workspace id of this conversation.
        pattern: Regular expression to search for.
        path: File or directory to search. Empty means the current directory.
        glob: Only search files matching this glob, e.g. "*.py".
        output_mode: "files_with_matches" (paths only), "content" (matching lines) or "count".
        case_insensitive: Ignore case.
        line_numbers: Include line numbers in content mode.
        context_before: Lines of context before each match (content mode).
        context_after: Lines of context after each match (content mode).
        multiline: Let the pattern span lines (. matches newline).
        head_limit: Maximum number of output lines.

    Returns:
        Matches, one per line.
    """
    ws = _ws(workspace)
    if output_mode not in ("files_with_matches", "content", "count"):
        return "error: output_mode must be files_with_matches, content or count"
    base = ws.path(path) if path else ws.cwd()
    if not base.exists():
        return f"error: path not found: {base}"
    if shutil.which("rg"):
        cmd = ["rg", "--no-heading", "--with-filename", "--color=never", "--max-columns=500"]
        cmd += {"files_with_matches": ["-l"], "count": ["-c"], "content": []}[output_mode]
        if output_mode == "content":
            if line_numbers:
                cmd.append("-n")
            if context_before:
                cmd += ["-B", str(int(context_before))]
            if context_after:
                cmd += ["-A", str(int(context_after))]
        if case_insensitive:
            cmd.append("-i")
        if multiline:
            cmd += ["-U", "--multiline-dotall"]
        if glob:
            cmd += ["--glob", glob]
        cmd += ["-e", pattern, "--", str(base)]
        cap = max(1, min(1000, int(head_limit)))
        lines, total, truncated = [], 0, False
        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, cwd=ws.cwd())
        try:
            while True:
                line = proc.stdout.readline(8192)
                if not line:
                    break
                lines.append(line.decode(errors="replace").rstrip("\n"))
                total += len(line)
                if len(lines) >= cap or total >= MAX_OUTPUT:
                    truncated = True
                    proc.kill()
                    break
            proc.wait(timeout=2)
            if proc.returncode == 2:
                return "error: " + _clip("\n".join(lines))
        finally:
            if proc.poll() is None:
                proc.kill()
            proc.stdout.close()
        if truncated:
            lines.append("[search output limit reached; narrow the query for more matches]")
    else:
        lines = _py_grep(base, pattern, glob, re.I if case_insensitive else 0, output_mode,
                         int(context_before), int(context_after), line_numbers, multiline)
    if not lines:
        return "(no matches)"
    cap = max(1, int(head_limit))
    return _clip("\n".join(lines[:cap]) + (f"\n[{len(lines) - cap} more lines not shown]" if len(lines) > cap else ""))


@_guard
def LS(workspace: str, path: str = "", depth: int = 2, ignore: str = "") -> str:
    """List files and folders as a tree. Prefer Glob/Grep when you know what you are looking for.

    Args:
        workspace: Workspace id of this conversation.
        path: Directory to list. Empty means the current directory.
        depth: How many levels to descend (1-5).
        ignore: Optional glob of names to hide, e.g. "*.pyc".

    Returns:
        An indented tree; folders end with "/".
    """
    ws = _ws(workspace)
    base = ws.path(path) if path else ws.cwd()
    if not base.is_dir():
        return f"error: not a directory: {base}"
    depth = max(1, min(int(depth), 5))
    out, budget = [f"{base}/"], [400]

    def walk(d: Path, level: int) -> None:
        try:
            entries = sorted(d.iterdir(), key=lambda e: (not e.is_dir(), e.name.lower()))
        except OSError:
            return
        for e in entries:
            if budget[0] <= 0:
                return
            if e.name in SKIP_DIRS or (ignore and fnmatch.fnmatch(e.name, ignore)):
                continue
            budget[0] -= 1
            out.append(f"{'  ' * level}- {e.name}{'/' if e.is_dir() else ''}")
            if e.is_dir() and not e.is_symlink() and level < depth:
                walk(e, level + 1)

    walk(base, 1)
    if budget[0] <= 0:
        out.append("[truncated at 400 entries]")
    return "\n".join(out)


# --------------------------------------------------------------------------- web


def _validate_public_web_url(candidate: str) -> str:
    parsed = urlsplit(candidate)
    if parsed.scheme.lower() not in {"http", "https"} or not parsed.hostname:
        raise ValueError("url must be an absolute http(s) URL")
    if parsed.username is not None or parsed.password is not None:
        raise ValueError("URL credentials are not allowed")
    host = parsed.hostname.rstrip(".").lower()
    if host.endswith((".localhost", ".local", ".internal", ".test", ".invalid", ".onion")) or host == "localhost":
        raise ValueError("private or local hosts are not allowed")
    try:
        addresses = {str(ipaddress.ip_address(host))}
    except ValueError:
        if "." not in host:
            raise ValueError("single-label hostnames are not allowed")
        try:
            addresses = {
                result[4][0].split("%", 1)[0]
                for result in socket.getaddrinfo(
                    host,
                    parsed.port or (443 if parsed.scheme == "https" else 80),
                    type=socket.SOCK_STREAM,
                )
            }
        except OSError as exc:
            raise ValueError(f"host could not be resolved: {host}") from exc
    if not addresses or any(not ipaddress.ip_address(address).is_global for address in addresses):
        raise ValueError("private, loopback, link-local, and reserved IP addresses are not allowed")
    return candidate


@_guard
def WebFetch(url: str, max_chars: int = 20000, offset: int = 0) -> str:
    """Download a public web page and return markdown text (HTML is converted; other text is returned as is).

    Args:
        url: The public http(s) URL to fetch. Private, local and reserved targets are blocked.
        max_chars: Maximum characters to return.
        offset: Character offset to start from.

    Returns:
        The page content.
    """
    _validate_public_web_url(url)
    import httpx

    max_bytes = 4 * 1024 * 1024
    current_url = url
    headers = {"User-Agent": "Mozilla/5.0 (claude-code-space)"}
    with httpx.Client(follow_redirects=False, timeout=25, headers=headers, trust_env=False) as client:
        for redirect_count in range(6):
            _validate_public_web_url(current_url)
            with client.stream("GET", current_url) as response:
                if response.is_redirect:
                    location = response.headers.get("location")
                    if not location or redirect_count >= 5:
                        return "error: too many redirects or redirect without a Location header"
                    current_url = urljoin(str(response.url), location)
                    continue
                content_type = response.headers.get("content-type", "")
                declared_size = response.headers.get("content-length")
                if declared_size and int(declared_size) > max_bytes:
                    return f"error: response exceeds the {max_bytes} byte WebFetch limit"
                chunks = []
                size = 0
                for chunk in response.iter_bytes():
                    size += len(chunk)
                    if size > max_bytes:
                        return f"error: response exceeds the {max_bytes} byte WebFetch limit"
                    chunks.append(chunk)
                page_status = response.status_code
                final_url = str(response.url)
                encoding = response.encoding or "utf-8"
                raw_body = b"".join(chunks)
                break
        else:
            return "error: too many redirects"

    body = raw_body.decode(encoding, errors="replace")
    if "html" in content_type:
        import html2text

        conv = html2text.HTML2Text()
        conv.ignore_images, conv.body_width = True, 0
        body = conv.handle(body)
    body = body[max(0, int(offset)) :]
    cap = max(1, min(int(max_chars), MAX_OUTPUT))
    more = f"\n[truncated: call again with offset={int(offset) + cap}]" if len(body) > cap else ""
    return f"[{page_status}] {final_url}\n\n{body[:cap]}{more}"


@_guard
def WebSearch(query: str, max_results: int = 8) -> str:
    """Search the web (DuckDuckGo) and return titles, URLs and snippets. Follow up with WebFetch to read a result.

    Args:
        query: The search query.
        max_results: Number of results (1-20).

    Returns:
        Numbered results.
    """
    from ddgs import DDGS

    rows = DDGS().text(query, max_results=max(1, min(int(max_results), 20)))
    return "\n\n".join(
        f"{i}. {r.get('title')}\n   {r.get('href')}\n   {r.get('body', '')}" for i, r in enumerate(rows, 1)
    ) or "(no results)"


# --------------------------------------------------------------------------- todos


@_guard
def TodoWrite(workspace: str, todos: list[dict]) -> str:
    """Create and update the task list for the current work. Send the COMPLETE list every time. Use it for tasks with 3+ steps; keep exactly one item in_progress.

    Args:
        workspace: Workspace id of this conversation.
        todos: List of {"content": str, "status": "pending" | "in_progress" | "completed"}.

    Returns:
        The rendered list.
    """
    ws = _ws(workspace)
    marks = {"pending": "[ ]", "in_progress": "[~]", "completed": "[x]"}
    for t in todos or []:
        if t.get("status") not in marks or not t.get("content"):
            return "error: each todo needs 'content' and a 'status' of pending, in_progress or completed"
    _atomic_write_text(ws.todos_file, json.dumps(todos, ensure_ascii=False))
    return "Todos updated:\n" + "\n".join(f"{marks[t['status']]} {t['content']}" for t in todos) + _autosave(ws)


ALL_TOOLS = [
    workspace_new, workspace_list, workspace_delete,
    WorkspaceCheckpoint, WorkflowNew, WorkflowList, WorkflowPause, WorkflowResume,
    Bash, BashOutput, BackgroundJobs, BackgroundWait, KillShell,
    JobStatus, JobCancel, ProcessList, ResourceStatus, WorkspaceHibernate, WorkspaceResume, WorkspaceStop,
    Read, Write, Edit, MultiEdit, Glob, Grep, LS,
    WebFetch, WebSearch, TodoWrite,
]