hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/tools/registry.py

@@ -0,0 +1,318 @@
+"""
+The tool registry (tool standard S1) and its dispatcher.
+
+One entry per tool: name, description, args model (Pydantic, extra=forbid;
+the advertised schema is generated from it), effect, scope, tier,
+retry_budget and idempotent_on. The dispatcher is a dictionary lookup by
+name and knows nothing about individual tools. Every outcome — unknown
+tool, malformed or invalid arguments, a tool not offered on this surface,
+a handler exception, a timeout, or the tool's own result — comes back as a
+ToolResult envelope (S2); dispatch never raises.
+
+Broker mapping (hyper-nimbus-gtm agent-mode design, READ/PROPOSE/ACT):
+effect "read" is READ; every other effect is PROPOSE (in the approval wave an
+`ask` tool returns needs_approval with a proposal instead of running); ACT is
+never a tool here — execution after approval is a runtime transition. See
+docs/TOOL-STANDARD.md.
+"""
+from __future__ import annotations
+
+import contextvars
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
+
+from hyperclaw.chat_scope import OWNER, normalize as normalize_scope
+
+from . import args as targs
+from .classify import classify
+from .envelope import (REASON_SURFACE, REASON_UNKNOWN_TOOL, Status, ToolResult, make)
+from .surfaces import NEVER_FROM_CHAT, allowed_on_surface
+
+log = logging.getLogger("hyperclaw.tools")
+
+EFFECTS = ("read", "write", "send", "spend", "delete", "system")
+TIERS = ("auto", "ask", "never_from_chat", "never")
+PUBLIC = "public"  # tool scope a guest chat may use; anything else is owner-only
+
+
+# The turn guard of the tool call running right now (team_delegate reads the
+# lead's provenance and requester from it). Set only around a dispatch.
+_ACTIVE_GUARD: contextvars.ContextVar = contextvars.ContextVar("hyperclaw_active_guard",
+                                                              default=None)
+
+
+def active_guard():
+    return _ACTIVE_GUARD.get()
+
+
+class ToolTimeout(Exception):
+    """Raised by a `run` hook when a tool exceeded its time budget."""
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    description: str
+    args_model: type
+    effect: str
+    scope: str
+    tier: str
+    retry_budget: int
+    idempotent_on: Tuple[str, ...]
+    handler: Callable[[str, dict], Any] = field(compare=False, repr=False)
+    # Wave 2: the idempotent_on fields that name the TARGET (the rest are the
+    # payload). A single path field makes the target "file:<resolved path>".
+    target_on: Tuple[str, ...] = ()
+
+    def __post_init__(self):
+        if self.effect not in EFFECTS:
+            raise ValueError(f"{self.name}: bad effect {self.effect!r}")
+        if self.tier not in TIERS:
+            raise ValueError(f"{self.name}: bad tier {self.tier!r}")
+        if self.name in NEVER_FROM_CHAT and self.tier not in ("never_from_chat", "never"):
+            raise ValueError(f"{self.name} must be tier never_from_chat (or never)")
+
+    @property
+    def broker_class(self) -> str:
+        """READ / PROPOSE in the agent-mode broker's terms (ACT is a transition)."""
+        return "READ" if self.effect == "read" else "PROPOSE"
+
+    def input_schema(self) -> dict:
+        return targs.input_schema(self.args_model)
+
+    def anthropic(self) -> dict:
+        return {"name": self.name, "description": self.description,
+                "input_schema": self.input_schema()}
+
+    def openai(self) -> dict:
+        return {"type": "function", "function": {
+            "name": self.name, "description": self.description,
+            "parameters": self.input_schema()}}
+
+
+def surface_allows(spec: ToolSpec, surface: str, scope: str = OWNER) -> bool:
+    """May `spec` be offered/run on `surface` for a chat of `scope`?"""
+    if spec.tier == "never":  # refused everywhere: its effect cannot be shown up front
+        return False
+    if not allowed_on_surface(spec.name, surface):
+        return False
+    if spec.tier == "never_from_chat" and surface != "tui":
+        return False
+    if normalize_scope(scope) != OWNER and spec.scope != PUBLIC:
+        return False
+    return True
+
+
+class ToolRegistry:
+    def __init__(self, specs: Iterable[ToolSpec] = ()):
+        self._specs: Dict[str, ToolSpec] = {}
+        for s in specs:
+            self.register(s)
+
+    def register(self, spec: ToolSpec) -> None:
+        if spec.name in self._specs:
+            raise ValueError(f"duplicate tool {spec.name}")
+        self._specs[spec.name] = spec
+
+    def get(self, name: str) -> Optional[ToolSpec]:
+        return self._specs.get(name) if isinstance(name, str) else None
+
+    def names(self) -> List[str]:
+        return list(self._specs)
+
+    def __len__(self) -> int:
+        return len(self._specs)
+
+    def __contains__(self, name) -> bool:
+        return name in self._specs
+
+    def specs(self, surface: str = "tui", scope: str = OWNER) -> List[ToolSpec]:
+        return [s for s in self._specs.values() if surface_allows(s, surface, scope)]
+
+    def anthropic_tools(self, surface: str = "tui", scope: str = OWNER) -> List[dict]:
+        return [s.anthropic() for s in self.specs(surface, scope)]
+
+    def openai_tools(self, surface: str = "tui", scope: str = OWNER) -> List[dict]:
+        return [s.openai() for s in self.specs(surface, scope)]
+
+    def dispatch(self, name: str, raw_args: Any, *, surface: str = "tui",
+                 scope: str = OWNER,
+                 run: Optional[Callable[[ToolSpec, dict], Any]] = None,
+                 guard: Any = None, approved_hash: Optional[str] = None) -> ToolResult:
+        """Look `name` up and run it. Never raises; always an envelope.
+
+        raw_args: a dict, or the raw JSON string from an OpenAI-style call
+        (malformed JSON -> invalid_args, never {}).
+        run(spec, args): optional executor hook (e.g. a timeout wrapper);
+        raise ToolTimeout from it on a timeout.
+        guard: the turn's tools.guard.TurnGuard (wave 2: effect ledger,
+        retry budgets, turn cap). Every tool loop passes one; None only in
+        direct calls (tests, internal use).
+        approved_hash: set only by tools.approval.send() when the owner pressed
+        Send; the call runs only if its payload hash is exactly that one.
+        Never reachable from a model's tool call.
+
+        Taint guard (hyperclaw.taint): the call runs as part of the guard's
+        conversation, so connector reads are recorded in its ledger; a
+        memory/learning tool whose arguments carry connector content (or, for
+        learning, whose conversation is tainted) is refused before any
+        approval card, with the reason.
+
+        Wave 3 (approval layer): after validation, tools.approval.evaluate()
+        decides whether the call runs now, is queued for the owner (Send /
+        Edit / Cancel; returns needs_approval and runs nothing), or is
+        refused. Every tool that is not read-only is gated, on every surface
+        including the local terminal (bash, code, desktop control too). Model
+        tool loops always pass a guard; a call without one has no approval
+        channel, so a gated call is refused (nothing runs), on every surface.
+        """
+        from hyperclaw import taint
+        token = _ACTIVE_GUARD.set(guard)
+        try:
+            with taint.conversation(getattr(guard, "conversation", None)), \
+                    taint.message(getattr(guard, "turn_id", None)):
+                return self._dispatch(name, raw_args, surface=surface, scope=scope, run=run,
+                                      guard=guard, approved_hash=approved_hash)
+        finally:
+            _ACTIVE_GUARD.reset(token)
+
+    def _dispatch(self, name: str, raw_args: Any, *, surface: str, scope: str,
+                  run: Optional[Callable[[ToolSpec, dict], Any]], guard: Any,
+                  approved_hash: Optional[str]) -> ToolResult:
+        spec = self.get(name)
+        if spec is None:
+            return make(Status.NOT_FOUND, f"Tool '{name}' does not exist.",
+                        reason=REASON_UNKNOWN_TOOL)
+        if not surface_allows(spec, surface, scope):
+            return make(Status.PERMISSION_DENIED,
+                        f"Tool '{name}' is not available in this conversation; it was NOT run.",
+                        reason=REASON_SURFACE)
+        if guard is not None:
+            refused = guard.precheck(spec)
+            if refused is not None:
+                return refused
+        try:
+            args = targs.validate(spec.args_model, raw_args)
+        except targs.ArgsError as e:
+            if guard is not None:
+                guard.on_invalid(spec)
+            return make(Status.INVALID_ARGS, f"{name}: {e}")
+        from hyperclaw import taint
+        tainted = taint.check_tool_call(name, args, getattr(guard, "conversation", None))
+        if tainted is not None:
+            return make(Status.PERMISSION_DENIED, f"{name} was NOT run. {tainted.user_message}")
+        budgets = getattr(guard, "check_budgets", None) if approved_hash is None else None
+        if budgets is not None:
+            try:
+                refused = budgets(spec, args)
+            except Exception as e:  # fail closed
+                log.warning("guard budget check failed for %s", name, exc_info=True)
+                return make(Status.FAILED, f"{name} was NOT run: runtime guard error "
+                                           f"({type(e).__name__}).")
+            if refused is not None:
+                return refused
+        gated = self._approval_gate(spec, args, raw_args, surface, scope, guard, approved_hash)
+        if gated is not None:
+            return gated
+        ctx = None
+        if guard is not None:
+            try:
+                refused, ctx = guard.before(spec, args)
+            except Exception as e:  # fail closed: a guard bug never runs the tool unchecked
+                log.warning("guard failed for %s", name, exc_info=True)
+                return make(Status.FAILED, f"{name} was NOT run: runtime guard error "
+                                           f"({type(e).__name__}).")
+            if refused is not None:
+                return refused
+        env = self._execute(spec, args, run)
+        if guard is not None:
+            try:
+                env = guard.after(spec, args, env, ctx)
+            except Exception:
+                log.warning("guard.after failed for %s", name, exc_info=True)
+        return env
+
+    @staticmethod
+    def _approval_gate(spec: ToolSpec, args: dict, raw_args: Any, surface: str, scope: str,
+                       guard: Any, approved_hash: Optional[str]) -> Optional[ToolResult]:
+        from . import approval
+        name = spec.name
+        if approved_hash is not None:
+            if not isinstance(raw_args, dict) or \
+                    approval.payload_hash(name, raw_args) != approved_hash or \
+                    approval.payload_hash(name, args) != approved_hash:
+                return make(Status.PERMISSION_DENIED,
+                            f"{name} was NOT run: its arguments differ from the approved payload.")
+            return None
+        try:
+            gate = approval.evaluate(spec, args, surface=surface, guard=guard)
+        except Exception as e:  # fail closed
+            log.warning("approval gate failed for %s", name, exc_info=True)
+            return make(Status.FAILED, f"{name} was NOT run: approval check error "
+                                       f"({type(e).__name__}).")
+        if gate is None:
+            return None
+        if gate.action == "deny":
+            env = make(Status.PERMISSION_DENIED, f"{name} was NOT run: {gate.reason}.")
+            _log_gate(guard, spec, args, env)
+            return env
+        if guard is None:  # no approval channel: refused on every surface, terminal included
+            return make(Status.PERMISSION_DENIED,
+                        f"{name} was NOT run: it needs the owner's approval ({gate.reason}) and "
+                        f"this call has no approval channel.")
+        try:
+            item = approval.get_queue().propose(
+                tool=name, args=args, conversation=guard.conversation, surface=surface,
+                scope=normalize_scope(scope), requester=getattr(guard, "requester", "owner"),
+                kind=gate.kind, reason=gate.reason,
+                untrusted=bool(getattr(guard, "untrusted_seen", False)))
+        except Exception as e:
+            log.warning("approval queue unavailable for %s", name, exc_info=True)
+            return make(Status.FAILED, f"{name} was NOT run: the approval queue is unavailable "
+                                       f"({type(e).__name__}).")
+        env = approval.needs_approval_envelope(item)
+        guard.queued.append(item.id)
+        _log_gate(guard, spec, args, env)
+        return env
+
+    @staticmethod
+    def _execute(spec: ToolSpec, args: dict, run) -> ToolResult:
+        name = spec.name
+        try:
+            raw = run(spec, args) if run else spec.handler(name, args)
+        except ToolTimeout as e:
+            if spec.effect != "read":
+                return make(Status.UNCERTAIN,
+                            f"{name} timed out ({e}); it may still have completed.")
+            return make(Status.FAILED, f"{name} timed out ({e}).", retryable=True)
+        except Exception as e:  # a tool bug: report it, never retry the model call
+            from hyperclaw.taint import TaintedInput
+            if isinstance(e, TaintedInput):   # a sink refused connector content: say why
+                return make(Status.PERMISSION_DENIED, f"{name} was NOT run. {e.user_message}")
+            log.warning("tool %s raised %s", name, type(e).__name__, exc_info=True)
+            return make(Status.FAILED, f"Error: tool {name} failed: {type(e).__name__}: {e}")
+        env = classify(spec, raw, args)
+        # Restricted-client guard, connector-result boundary: under an outside
+        # model, what involves a restricted client is withheld before the
+        # result can enter any model request (hyperclaw.client_guard).
+        from hyperclaw import client_guard
+        try:
+            return client_guard.filter_tool_result(name, env)
+        except Exception as e:  # fail closed: nothing unchecked reaches the model
+            log.warning("client guard failed for %s", name, exc_info=True)
+            if name in client_guard.CONNECTOR_TOOL_SOURCES:
+                return make(Status.FAILED, f"{name}: the restricted-client check could not run "
+                                           f"({type(e).__name__}), so nothing it read is shown.")
+            return env
+
+
+def _log_gate(guard, spec: ToolSpec, args: dict, env: ToolResult) -> None:
+    """Queued or refused calls go in the activity log too."""
+    if guard is None:
+        return
+    try:
+        from . import effects as fx
+        guard._log_refusal(spec, fx.call_effect(spec, args), args, env)
+    except Exception:
+        log.warning("could not log the approval decision for %s", spec.name, exc_info=True)

hyperclaw/tools/service_guard.py

@@ -0,0 +1,151 @@
+"""
+Service-control guard (benchmark 17.4 / 17.5).
+
+Recovery and restart actions may only touch HyperClaw's own services, and
+only with the owner's approval:
+
+- A command that stops, starts, restarts, loads, unloads or kills a service or
+  process is a *service action*.
+- Every label it names must match the allowlist (config-driven,
+  HYPERCLAW_SERVICE_ALLOWLIST, comma-separated globs; default
+  ``com.hyperclaw.*``). Anything else — another app's messaging service, a
+  bare pid, ``pkill``/``killall`` patterns — is refused outright.
+- An allowlisted action still goes to the approval queue (never auto).
+- Text the model read from email, the web or a document is data: a service
+  action asked for after such a read is refused unless the user named that
+  service in their own words (tools/approval.py applies this rule).
+
+This is a guard for the model's tool calls (bash, python_exec, applescript),
+not a sandbox.
+"""
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+import shlex
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+DEFAULT_ALLOWLIST = ("com.hyperclaw.*",)
+
+# Tools whose text argument can carry a service command.
+COMMAND_ARGS = {"bash": "command", "python_exec": "code", "applescript": "script"}
+
+_LAUNCHCTL_VERBS = {"kickstart", "bootout", "bootstrap", "load", "unload", "stop", "start",
+                    "kill", "enable", "disable", "remove", "submit", "restart"}
+_SYSTEMCTL_VERBS = {"restart", "stop", "start", "kill", "reload", "disable", "enable", "mask",
+                    "unmask", "try-restart", "reload-or-restart"}
+_KILLERS = {"kill", "pkill", "killall", "skill", "xkill"}
+_SPLIT = re.compile(r"\|\||&&|[;|&\n]|\$\(|`")
+
+
+def allowlist() -> tuple:
+    raw = os.environ.get("HYPERCLAW_SERVICE_ALLOWLIST", "")
+    items = tuple(x.strip() for x in raw.split(",") if x.strip())
+    return items or DEFAULT_ALLOWLIST
+
+
+def label_allowed(label: str) -> bool:
+    return any(fnmatch.fnmatchcase(label, pat) for pat in allowlist())
+
+
+@dataclass
+class ServiceAction:
+    verdict: str                    # "deny" | "approve"
+    labels: List[str] = field(default_factory=list)
+    reason: str = ""
+
+
+def _label_from_target(tok: str) -> str:
+    """gui/501/com.x.y -> com.x.y; ~/Library/LaunchAgents/com.x.y.plist -> com.x.y."""
+    t = tok.rstrip("/")
+    t = t.rsplit("/", 1)[-1]
+    if t.endswith(".plist"):
+        t = t[:-6]
+    if t.endswith(".service"):
+        t = t[:-8]
+    return t
+
+
+def _segment_action(words: List[str]) -> Optional[ServiceAction]:
+    # drop leading sudo / env assignments
+    while words and (words[0] in ("sudo", "doas", "exec", "command", "nohup")
+                     or re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*=.*", words[0])):
+        words = words[1:]
+    if not words:
+        return None
+    prog = words[0].rsplit("/", 1)[-1]
+    if prog in _KILLERS:
+        return ServiceAction("deny", [], f"'{prog}' targets processes by pid or name, which "
+                                         f"cannot be limited to HyperClaw's own services")
+    if prog == "launchctl" and len(words) > 1 and words[1] in _LAUNCHCTL_VERBS:
+        targets = [w for w in words[2:] if not w.startswith("-") and not w.isdigit()]
+        labels = [_label_from_target(t) for t in targets if t not in ("system", "gui", "user")]
+        labels = [x for x in labels if x and not re.fullmatch(r"(gui|user|system)", x)]
+        return _decide(labels, f"launchctl {words[1]}")
+    if prog == "systemctl" and len(words) > 1:
+        rest = [w for w in words[1:] if not w.startswith("-")]
+        if rest and rest[0] in _SYSTEMCTL_VERBS:
+            return _decide([_label_from_target(w) for w in rest[1:]], f"systemctl {rest[0]}")
+    if prog == "service" and len(words) > 2:
+        return _decide([words[1]], f"service {words[2]}")
+    if prog == "brew" and len(words) > 2 and words[1] == "services" and words[2] in (
+            "start", "stop", "restart", "kill", "run", "cleanup"):
+        return _decide(words[3:4] or ["(all)"], f"brew services {words[2]}")
+    return None
+
+
+def _decide(labels: List[str], what: str) -> ServiceAction:
+    if not labels:
+        return ServiceAction("deny", [], f"{what} names no service label")
+    bad = [x for x in labels if not label_allowed(x)]
+    if bad:
+        return ServiceAction("deny", labels, f"{what} on {', '.join(bad)}: only HyperClaw's own "
+                                             f"services ({', '.join(allowlist())}) may be touched")
+    return ServiceAction("approve", labels, f"{what} on {', '.join(labels)}")
+
+
+def check_command(text: str, shell: bool = True) -> Optional[ServiceAction]:
+    """None when `text` contains no service action; else the verdict (any
+    denied segment denies the whole command)."""
+    if not isinstance(text, str) or not text.strip():
+        return None
+    found: List[ServiceAction] = []
+    for seg in _SPLIT.split(text):
+        seg = seg.strip()
+        if not seg:
+            continue
+        try:
+            words = shlex.split(seg, comments=True)
+        except ValueError:
+            words = seg.split()
+        act = _segment_action(words)
+        if act:
+            found.append(act)
+    # Code in other languages (python_exec subprocess lists, AppleScript
+    # "do shell script"): look for the programs as plain words too.
+    words_re = r"\b(launchctl|systemctl)\b" if shell else r"\b(launchctl|systemctl|pkill|killall|kill)\b"
+    if not found and re.search(words_re, text):
+        m = re.search(r"\b(launchctl|systemctl)\b[\s'\",\[]+(\w[\w-]*)", text)
+        labels = re.findall(r"(?:gui|user|system)/\d*/?([\w.\-]+)|([\w\-]+(?:\.[\w\-]+){2,})", text)
+        names = [a or b for a, b in labels]
+        if m and m.group(2) in (_LAUNCHCTL_VERBS | _SYSTEMCTL_VERBS) and names:
+            found.append(_decide(names, f"{m.group(1)} {m.group(2)}"))
+        else:
+            found.append(ServiceAction("deny", [], "process/service control from code cannot be "
+                                                   "limited to HyperClaw's own services"))
+    if not found:
+        return None
+    denied = [a for a in found if a.verdict == "deny"]
+    if denied:
+        return denied[0]
+    labels = [x for a in found for x in a.labels]
+    return ServiceAction("approve", labels, "; ".join(a.reason for a in found))
+
+
+def check_tool(name: str, args: dict) -> Optional[ServiceAction]:
+    field_name = COMMAND_ARGS.get(name)
+    if not field_name or not isinstance(args, dict):
+        return None
+    return check_command(args.get(field_name, ""), shell=(name == "bash"))

hyperclaw/tools/surfaces.py

@@ -0,0 +1,54 @@
+"""
+Which tools a surface may offer.
+
+Spec cross-cutting rule 4 / §6: "shell and code execution from remote
+channels, and desktop/app control" are tier never_from_chat. They are
+REMOVED from every chat/remote surface (absent from the tool list and
+refused if called anyway), not gated behind a confirmation.
+
+Only the local terminal (surface "tui") keeps them, and there every call
+that is not read-only goes through the approval layer (tools/approval.py):
+the owner sees the exact command line, script, keystrokes, click, app, file
+or address and answers Send / Edit / Cancel before anything runs.
+"""
+from __future__ import annotations
+
+# Shell / code execution and desktop or device control.
+NEVER_FROM_CHAT = frozenset({
+    "bash",          # shell
+    "python_exec",   # bare exec() of model-written code
+    "applescript",   # arbitrary macOS automation
+    "type_text",     # keyboard
+    "key_press",     # keyboard
+    "mouse_click",   # mouse
+    "open_app",      # app control
+    "open_file",     # opens files/apps on the owner's desktop
+    "open_url",      # drives the owner's browser
+    "screenshot",    # captures the owner's screen
+    "record_audio",  # records the owner's microphone
+})
+
+# Tools only the lead (the person's own agent) has: never offered to or run by
+# a specialist (surface "swarm"). Specialists can't start specialists.
+LEAD_ONLY = frozenset({"team_delegate", "agent_start", "agent_stop", "agent_watch"})
+SPECIALIST_SURFACE = "swarm"
+
+LOCAL_SURFACES = frozenset({"tui"})
+# Known remote surfaces. Any surface name not in LOCAL_SURFACES is treated as
+# remote, including unknown ones (fail closed).
+REMOTE_SURFACES = frozenset({"telegram", "imessage", "bridge", "server", "scheduler", "swarm"})
+
+
+def is_local(surface: str) -> bool:
+    return surface in LOCAL_SURFACES
+
+
+def allowed_on_surface(name: str, surface: str) -> bool:
+    if surface == SPECIALIST_SURFACE and name in LEAD_ONLY:
+        return False
+    return is_local(surface) or name not in NEVER_FROM_CHAT
+
+
+def tools_for_surface(tools: list, surface: str) -> list:
+    """Filter an Anthropic-format tool list for a surface."""
+    return [t for t in tools if allowed_on_surface(t.get("name", ""), surface)]

hyperclaw/tools/workspace.py

@@ -0,0 +1,87 @@
+"""
+Writes only to the workspace (benchmark 12.5, rc3).
+
+Every tool that writes a file (write_file, edit_file, download, qr_code,
+image_generate, sql_query) resolves the real target path first, following
+symlinks and '..', and refuses anything outside the workspace,
+``$HYPERCLAW_ROOT/workspace`` (default ``~/.hyperclaw/workspace``). A
+relative path is taken relative to the workspace, not the process cwd.
+
+Refusals start with ``Permission denied:`` so the registry returns a
+``permission_denied`` envelope and the model is told not to work around it.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+# tool name -> the argument(s) naming a file the tool writes
+WRITE_PATH_ARGS = {
+    "write_file": ("path",),
+    "edit_file": ("path",),
+    "download": ("path",),
+    "qr_code": ("save_path",),
+    "image_generate": ("save_path",),
+    "sql_query": ("database",),
+    "document_create": ("path",),
+}
+
+DENIED_PREFIX = "Permission denied:"
+
+
+def workspace_root() -> Path:
+    """The real (symlink-resolved) workspace directory for this install."""
+    from hyperclaw.userconfig import root
+    ws = root() / "workspace"
+    return Path(os.path.realpath(ws))
+
+
+def resolve(path, base: Optional[Path] = None) -> Path:
+    """The real path a write to `path` would land on: '~' expanded,
+    relative to the workspace, every symlink and '..' resolved (including a
+    symlinked final component)."""
+    base = base or workspace_root()
+    p = Path(os.path.expanduser(str(path)))
+    if not p.is_absolute():
+        p = base / p
+    return Path(os.path.realpath(p))
+
+
+def inside_workspace(path, base: Optional[Path] = None) -> bool:
+    base = base or workspace_root()
+    real = resolve(path, base)
+    try:
+        real.relative_to(base)
+        return True
+    except ValueError:
+        return False
+
+
+def check_write(tool: str, args: dict) -> Optional[str]:
+    """None if every path `tool` would write is inside the workspace;
+    otherwise the refusal text (nothing is written)."""
+    names = WRITE_PATH_ARGS.get(tool)
+    if not names or not isinstance(args, dict):
+        return None
+    base = workspace_root()
+    for key in names:
+        val = args.get(key)
+        if val in (None, ""):
+            continue
+        try:
+            ok = inside_workspace(val, base)
+        except (OSError, ValueError, RuntimeError):
+            ok = False
+        if not ok:
+            return (f"{DENIED_PREFIX} {tool} may only write inside the HyperClaw workspace "
+                    f"({base}); {val!r} resolves outside it. Nothing was written.")
+    return None
+
+
+def workspace_path(path) -> Path:
+    """Resolve `path` for writing, or raise PermissionError if outside."""
+    base = workspace_root()
+    if not inside_workspace(path, base):
+        raise PermissionError(f"{path!r} is outside the HyperClaw workspace ({base})")
+    return resolve(path, base)