| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441 |
- """User skill locks, enforced on every agent write path.
- ``hermes curator lock <skill>`` (or the Desktop lock switch) records ``locked: true`` beside
- ``pinned`` in the profile's ``skills/.usage.json``. While a skill is locked the agent cannot change
- it: ``skill_manage`` refuses every mutating action, ``write_file``/``patch`` refuse any path inside
- the skill's directory, and ``terminal`` refuses commands that write there. The lock record itself
- is protected the same way, and the agent cannot run ``hermes curator unlock``. The user's own edits
- (Desktop editor, their own editor, the CLI) are not gated.
- The terminal check reads the command's write targets (redirections, tee, cp/mv/rm/sed -i and
- friends, git in the skill's tree, ``cd`` into it, inline interpreter code naming it). It is a
- policy check, not a sandbox: a script that writes there through its own logic is not seen.
- """
- from __future__ import annotations
- import glob
- import itertools
- import os
- import re
- import shlex
- from typing import Iterable
- # Verbs whose every path operand is written (or removed/renamed).
- _WRITES_EVERY_OPERAND = frozenset({
- "rm", "rmdir", "unlink", "truncate", "shred", "touch", "chmod", "chown", "chgrp", "chattr",
- "setfacl", "mkdir", "mv", "patch", "dos2unix", "unix2dos", "xattr", "ed", "ex", "vi", "vim",
- "nvim", "nano", "emacs"})
- # Verbs that write only to their LAST operand (the destination).
- _WRITES_LAST_OPERAND = frozenset({"cp", "install", "ln", "rsync", "scp"})
- # Verbs that reach INTO a directory operand recursively, so an ancestor of a locked skill counts.
- _RECURSIVE = frozenset({"rm", "mv", "chmod", "chown", "chgrp", "chattr", "setfacl", "rsync", "find"})
- _INPLACE_EDITORS = frozenset({"sed", "perl", "ruby"})
- _GIT_MUTATIONS = frozenset({
- "add", "am", "apply", "checkout", "clean", "commit", "merge", "mv", "pull", "rebase", "reset",
- "restore", "revert", "rm", "stash", "switch", "cherry-pick"})
- _INTERPRETERS = re.compile(
- r"^(?:python[0-9.]*|node|nodejs|deno|bun|ruby|perl|php|bash|sh|zsh|dash|ksh|pwsh|powershell)$")
- _WRAPPERS = frozenset({"sudo", "env", "command", "builtin", "exec", "nohup", "setsid", "time", "nice", "xargs"})
- # Inline code that writes: open() with a write/append/create mode, pathlib/fs write calls, deletes,
- # renames, copies, and shell write forms. A plain open(path) / read stays allowed.
- _WRITEISH_CODE = re.compile(
- r"open\s*\([^)]*['\"][rbt]*[wax+][^'\"]*['\"]|\.write(?:_text|_bytes|lines)?\s*\(|"
- r"\b(?:unlink|rmtree|removedirs|remove|rmdir|rename|truncate|chmod|chown|mkdir|makedirs|symlink|"
- r"copyfile|copytree|copy2?|move|touch)\s*\(|\bos\.replace\s*\(|\.replace\s*\(\s*(?:Path|['\"]/)|"
- r"(?:write|append)File(?:Sync)?|(?:rm|unlink|rename|mkdir|copyFile|cp)Sync|"
- r"(?:^|[\s;|&])>{1,2}|\bsed\s+-i|\b(?:mv|rm|cp|tee|touch)\s", re.IGNORECASE)
- _SEPARATORS = frozenset({";", "&", "&&", "|", "||", "(", ")", "|&", ";;"})
- def _skill_usage():
- from tools import skill_usage
- return skill_usage
- def locked_skill_dirs() -> list[tuple[str, str]]:
- """``(name, realpath)`` of every locked skill in the active profile, from ONE walk of the
- skills dirs (locks are keyed by directory name, so no frontmatter is read)."""
- names = set(_skill_usage().locked_skill_names())
- if not names:
- return []
- from agent.skill_utils import get_all_skills_dirs, is_excluded_skill_path
- found: dict[str, str] = {}
- for base in get_all_skills_dirs():
- if not base.is_dir():
- continue
- for skill_md in base.rglob("SKILL.md"):
- name = skill_md.parent.name
- if name in names and name not in found and not is_excluded_skill_path(skill_md, root=base):
- found[name] = os.path.realpath(skill_md.parent)
- return sorted(found.items())
- def is_locked_skill(name: str, locked_names: Iterable[str] | None = None) -> bool:
- """Whether *name* (directory, ``cat/name`` or frontmatter name) is locked. Locks are keyed by
- directory name, while curator rows and some callers carry the frontmatter name."""
- names = set(_skill_usage().locked_skill_names() if locked_names is None else locked_names)
- if not names:
- return False
- if name in names or os.path.basename(name) in names:
- return True
- from tools.skill_manager_tool import _find_skill
- found = _find_skill(name)
- return bool(found) and found["path"].name in names
- def _record_path() -> str:
- return os.path.realpath(_skill_usage()._usage_file())
- def _inside(path: str, root: str) -> bool:
- return path == root or path.startswith(root.rstrip(os.sep) + os.sep)
- def skill_refusal(name: str) -> str:
- return (f"Skill '{name}' is locked by the user, so the agent cannot change it: skill_manage, "
- f"write_file, patch and terminal all refuse. Don't retry or work around it (no copying it "
- f"under another name); tell the user what you would change. They can unlock it with "
- f"`hermes curator unlock {name}` or the lock switch in Desktop.")
- RECORD_REFUSAL = ("skills/.usage.json holds the user's skill locks, so the agent cannot change it "
- "while any skill is locked.")
- UNLOCK_REFUSAL = ("Only the user can unlock a skill. Ask them to run `hermes curator unlock <skill>` "
- "themselves or use the lock switch in Desktop.")
- def _skills_roots() -> list[str]:
- from agent.skill_utils import get_all_skills_dirs
- return [os.path.realpath(d) for d in get_all_skills_dirs()]
- def _hit(path: str, locked: list[tuple[str, str]], record: str, *, ancestor: str = "") -> str | None:
- """Refusal text when *path* is the lock record or inside a locked skill. ``ancestor="any"`` also
- counts a directory ABOVE a locked skill (recursive deletes/moves); ``ancestor="skills"`` counts it
- only inside a skills root (a recursive copy or extraction there can merge into the skill)."""
- real = os.path.realpath(path)
- if real == record or (ancestor == "any" and real != os.sep and _inside(record, real)):
- return RECORD_REFUSAL
- for name, root in locked:
- if _inside(real, root):
- return skill_refusal(name)
- if ancestor and real != os.sep and _inside(root, real) and (
- ancestor == "any" or any(_inside(real, r) for r in _skills_roots())):
- return skill_refusal(name)
- return None
- def path_refusal(paths: Iterable[str]) -> str | None:
- """write_file/patch guard: refusal text when any path lands in a locked skill or the lock record."""
- locked = locked_skill_dirs()
- if not locked:
- return None
- record = _record_path()
- for path in paths:
- if path and (reason := _hit(path, locked, record)):
- return reason
- return None
- # ── terminal ──────────────────────────────────────────────────────────────────────────────────
- _VAR = re.compile(r"\$\{(\w+)\}|\$(\w+)")
- def _shell_env(assigned: dict[str, str] | None = None) -> dict[str, str]:
- from hermes_constants import get_hermes_home
- return {**os.environ, "HOME": os.path.expanduser("~"), "HERMES_HOME": str(get_hermes_home()),
- **(assigned or {})}
- def _expand(word: str, cwd: str, env: dict[str, str] | None = None) -> list[str]:
- """Shell word -> absolute path(s): $VARS (environment + assignments earlier in the command), ~,
- relative to *cwd*; a glob expands against the filesystem the way the shell would (unmatched:
- its literal directory prefix)."""
- env = env if env is not None else _shell_env()
- word = _VAR.sub(lambda m: env.get(m.group(1) or m.group(2), m.group(0)), word)
- home = env["HOME"]
- if word == "~" or word.startswith("~/"):
- word = home + word[1:]
- path = os.path.normpath(os.path.join(cwd, word))
- if not any(ch in word for ch in "*?["):
- return [path]
- if matches := glob.glob(path):
- return matches
- return [path[: min(path.index(ch) for ch in "*?[" if ch in path)].rsplit(os.sep, 1)[0] or os.sep]
- def _unquoted_newlines_to_semicolons(command: str) -> str:
- """Newlines separate commands like ``;`` does; shlex would read them as plain whitespace."""
- out, quote = [], None
- for ch in command:
- if quote:
- quote = None if ch == quote else quote
- elif ch in "'\"":
- quote = ch
- elif ch == "\n":
- ch = ";"
- out.append(ch)
- return "".join(out)
- def _tokens(command: str) -> list[str]:
- lexer = shlex.shlex(_unquoted_newlines_to_semicolons(command), posix=True, punctuation_chars=";&|<>()")
- lexer.whitespace_split = True
- lexer.commenters = ""
- try:
- return list(lexer)
- except ValueError: # unbalanced quotes: fall back to whitespace words
- return command.split()
- def _segments(tokens: list[str]) -> Iterable[tuple[list[str], list[str], str]]:
- """Yield ``(argv, redirect_targets, separator_that_ended_it)`` per simple command."""
- argv: list[str] = []
- targets: list[str] = []
- it = iter(tokens)
- for tok in it:
- if ">" in tok and set(tok) <= set("&>|0123456789"):
- if not tok.endswith("&"):
- target = next(it, "")
- if target and not target.startswith("&") and target != "/dev/null":
- targets.append(target)
- continue
- if tok in ("<", "<<", "<<<", "<<-"):
- next(it, "") # input file / heredoc delimiter / here-string: read, never written
- continue
- if tok and set(tok) <= set(";&|()"):
- yield argv, targets, tok
- argv, targets = [], []
- continue
- argv.append(tok)
- yield argv, targets, ""
- _XARGS_OPTIONS_WITH_ARG = frozenset({"-n", "-I", "-L", "-P", "-d", "-E", "-s", "-a"})
- def _strip_wrappers(argv: list[str]) -> list[str]:
- from tools.self_repo_guard import _WRAPPER_OPTIONS_WITH_ARG
- while argv:
- if re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", argv[0]):
- argv = argv[1:]
- continue
- head = os.path.basename(argv[0])
- if head not in _WRAPPERS:
- break
- takes_value = _XARGS_OPTIONS_WITH_ARG if head == "xargs" else _WRAPPER_OPTIONS_WITH_ARG.get(head, frozenset())
- argv = argv[1:]
- while argv and argv[0].startswith("-"):
- argv = argv[2:] if argv[0] in takes_value else argv[1:]
- return argv
- def _operands(args: list[str]) -> list[str]:
- return [a for a in args if a and not a.startswith("-")]
- def _target_directory(args: list[str]) -> tuple[str | None, list[str]]:
- """``cp/mv/install/ln -t DIR`` / ``--target-directory[=]DIR``: (DIR, remaining args)."""
- rest = list(args)
- for i, arg in enumerate(rest):
- if arg.startswith("--target-directory="):
- return arg.split("=", 1)[1], rest[:i] + rest[i + 1:]
- if arg in ("-t", "--target-directory") and i + 1 < len(rest):
- return rest[i + 1], rest[:i] + rest[i + 2:]
- if arg.startswith("-t") and len(arg) > 2 and not arg.startswith("--"):
- return arg[2:], rest[:i] + rest[i + 1:]
- return None, rest
- class _Scope:
- """What a command is checked against: its working dir, the locked skills and the lock record."""
- def __init__(self, cwd: str, locked: list[tuple[str, str]], record: str, depth: int,
- env: dict[str, str] | None = None) -> None:
- self.cwd, self.locked, self.record, self.depth = cwd, locked, record, depth
- self.env = env if env is not None else _shell_env()
- def hit(self, word: str, ancestor: str = "") -> str | None:
- return next((r for path in _expand(word, self.cwd, self.env)
- if (r := _hit(path, self.locked, self.record, ancestor=ancestor))), None)
- def first_hit(self, words: Iterable[str], ancestor: str = "") -> str | None:
- return next((r for w in words if (r := self.hit(w, ancestor))), None)
- def _check_unlock(verb: str, args: list[str], scope: _Scope) -> str | None:
- if verb == "hermes" or (verb.startswith("python") and "hermes_cli.main" in args):
- if "curator" in args and "unlock" in args[args.index("curator"):]:
- return UNLOCK_REFUSAL
- return None
- _RECURSIVE_COPY_FLAGS = re.compile(r"^(?:-[A-Za-z]*[rRa][A-Za-z]*|--recursive|--archive)$")
- def _check_file_verbs(verb: str, args: list[str], scope: _Scope) -> str | None:
- if verb in _WRITES_EVERY_OPERAND or verb == "tee":
- return scope.first_hit(_operands(args), ancestor="any" if verb in _RECURSIVE else "")
- if verb not in _WRITES_LAST_OPERAND:
- return None
- target, rest = _target_directory(args)
- ops = _operands(rest)
- dest = target if target is not None else (ops[-1] if ops else None)
- if dest is None:
- return None
- # A recursive copy into a directory above the skill merges into it; rsync is recursive with -a/-r.
- merges = verb == "rsync" or any(_RECURSIVE_COPY_FLAGS.match(a) for a in rest)
- return scope.hit(dest, ancestor="skills" if merges else "")
- def _check_inplace(verb: str, args: list[str], scope: _Scope) -> str | None:
- if verb in _INPLACE_EDITORS and any(
- a.startswith("--in-place") or (a.startswith("-") and not a.startswith("--") and "i" in a) for a in args):
- return scope.first_hit(_operands(args))
- return None
- def _find_exec_commands(args: list[str]) -> Iterable[list[str]]:
- group: list[str] | None = None
- for arg in args:
- if arg in ("-exec", "-execdir", "-ok", "-okdir"):
- group = []
- elif group is not None and arg in (";", "+"):
- yield group
- group = None
- elif group is not None:
- group.append(arg)
- if group:
- yield group
- def _check_find(verb: str, args: list[str], scope: _Scope) -> str | None:
- """``find -delete``, or ``-exec`` of a command that writes, over a tree holding a locked skill."""
- if verb != "find":
- return None
- starts = list(itertools.takewhile(lambda a: not a.startswith("-"), args)) or ["."]
- writes = "-delete" in args
- for cmd in _find_exec_commands(args):
- # Judge the executed command as if `{}` were a file in the locked skill.
- probe = [w if w != "{}" else os.path.join(scope.locked[0][1], "SKILL.md") for w in cmd] if scope.locked else cmd
- writes = writes or (bool(probe) and _argv_refusal(
- probe, scope.cwd, scope.locked, scope.record, scope.depth, scope.env) is not None)
- return scope.first_hit(starts, ancestor="any") if writes else None
- def _check_git(verb: str, args: list[str], scope: _Scope) -> str | None:
- if verb != "git":
- return None
- where, rest = scope.cwd, list(args)
- while rest and rest[0].startswith("-"):
- flag = rest.pop(0)
- if flag == "-C" and rest:
- where = _expand(rest.pop(0), scope.cwd, scope.env)[0]
- elif flag in ("-c", "--git-dir", "--work-tree") and rest:
- rest.pop(0)
- if rest and rest[0] in _GIT_MUTATIONS:
- return _hit(where, scope.locked, scope.record, ancestor="any")
- return None
- def _check_extract(verb: str, args: list[str], scope: _Scope) -> str | None:
- if verb not in ("tar", "unzip", "bsdtar"):
- return None
- dest = scope.cwd
- for flag, value in itertools.pairwise(args):
- if flag in ("-C", "--directory", "-d"):
- dest = _expand(value, scope.cwd, scope.env)[0]
- bundled = bool(args) and not args[0].startswith("-") and "x" in args[0] # `tar xzf a.tgz`
- extracting = verb == "unzip" or bundled or any(
- a == "--extract" or (a.startswith("-") and not a.startswith("--") and "x" in a) for a in args)
- # The archive's paths are unknown: extracting into a directory above the skill can overwrite it.
- return _hit(dest, scope.locked, scope.record, ancestor="skills") if extracting else None
- def _check_interpreter(verb: str, args: list[str], scope: _Scope) -> str | None:
- if not _INTERPRETERS.match(verb):
- return None
- for flag, code in itertools.pairwise(args):
- if flag not in ("-c", "-e", "-E", "--eval", "-Command", "-r"):
- continue
- if verb in ("bash", "sh", "zsh", "dash", "ksh") and scope.depth < 3:
- reason = _command_refusal(code, scope.cwd, scope.locked, scope.record, scope.depth + 1)
- else:
- reason = _code_refusal(code, scope.locked, scope.record, scope.cwd)
- if reason:
- return reason
- return None
- _ARGV_CHECKS = (_check_unlock, _check_file_verbs, _check_inplace, _check_find, _check_git,
- _check_extract, _check_interpreter)
- def _argv_refusal(argv: list[str], cwd: str, locked, record, depth: int,
- env: dict[str, str] | None = None) -> str | None:
- scope = _Scope(cwd, locked, record, depth, env)
- verb = os.path.basename(argv[0])
- return next((r for check in _ARGV_CHECKS if (r := check(verb, argv[1:], scope))), None)
- def _code_refusal(code: str, locked, record, cwd: str = "") -> str | None:
- """Inline interpreter code that looks like it writes AND names a locked skill (or the record),
- or runs with its working directory inside one (relative paths)."""
- from hermes_constants import get_hermes_home
- if not _WRITEISH_CODE.search(code):
- return None
- if cwd and (reason := _hit(cwd, locked, record)):
- return reason
- home, hermes_home = os.path.expanduser("~"), str(get_hermes_home())
- text = code.replace("$HERMES_HOME", hermes_home).replace("~", home)
- skills_root = os.path.realpath(_skill_usage()._skills_dir())
- if ".usage.json" in text:
- return RECORD_REFUSAL
- for name, root in locked:
- rel = os.path.relpath(root, skills_root) if skills_root and _inside(root, skills_root) else ""
- if root in text or (rel and f"skills/{rel}" in text) or f"skills/{os.path.basename(root)}" in text:
- return skill_refusal(name)
- return None
- _ASSIGNMENT = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$", re.DOTALL)
- def _command_refusal(command: str, cwd: str, locked, record, depth: int = 0) -> str | None:
- if "<<" in command and (reason := _code_refusal(command, locked, record, cwd)):
- return reason # heredoc-fed interpreter body
- env = _shell_env()
- subshells: list[str] = [] # cwd to restore when each ( ... ) closes
- for argv, targets, separator in _segments(_tokens(command)):
- words = argv[1:] if argv[:1] == ["export"] else argv
- if words and all(_ASSIGNMENT.match(w) for w in words): # `p=...` / `export p=...` persist
- for w in words:
- name, value = _ASSIGNMENT.match(w).groups()
- env[name] = _VAR.sub(lambda m: env.get(m.group(1) or m.group(2), m.group(0)), value)
- argv = []
- for target in targets:
- if reason := next((r for path in _expand(target, cwd, env)
- if (r := _hit(path, locked, record))), None):
- return reason
- argv = _strip_wrappers(argv)
- if argv and argv[0] in ("cd", "pushd") and len(argv) > 1:
- cwd = _expand(argv[1], cwd, env)[0]
- elif argv and (reason := _argv_refusal(argv, cwd, locked, record, depth, env)):
- return reason
- for ch in separator:
- if ch == "(":
- subshells.append(cwd)
- elif ch == ")" and subshells:
- cwd = subshells.pop()
- return None
- def command_refusal(command: str, cwd: str) -> str | None:
- """terminal guard: refusal text when *command* writes into a locked skill, the lock record, or
- runs ``hermes curator unlock``. None when nothing is locked."""
- locked = locked_skill_dirs()
- if not locked:
- return None
- return _command_refusal(command, cwd or os.getcwd(), locked, _record_path())
|