No description
  • Python 99.5%
  • Just 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-08-09 21:21:11 +08:00
tests feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00
.gitignore kuri-tool-guard: consolidated pre_tool_call guards 2026-07-04 22:40:46 +08:00
.vulture_whitelist.py kuri-tool-guard: consolidated pre_tool_call guards 2026-07-04 22:40:46 +08:00
__init__.py feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00
_guards.py feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00
_parser.py refactor(kuri-tool-guard): modularise monolithic __init__.py and tests 2026-07-31 02:23:02 +08:00
_predicates.py refactor(kuri-tool-guard): modularise monolithic __init__.py and tests 2026-07-31 02:23:02 +08:00
_state.py feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00
AGENTS.md feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00
justfile feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00
plugin.yaml feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00
pyproject.toml feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00
README.md refactor: home-root guards with cross-account tests, injectable policy, bounded-output Guard 10 2026-07-30 22:46:35 +08:00
uv.lock feat(kuri-tool-guard): add skill directory lockdown guard (Guard 11) 2026-08-09 21:21:11 +08:00

kuri-tool-guard

A Hermes plugin that applies high-friction, good-faith policy checks before tool calls execute. It consolidates ten guard categories into one pre_tool_call hook. It is host-side policy, not a complete sandbox against every shell or tool route.

Guards

  1. Home root search — search_files / search targeting the effective user's Unix home root (via pwd.getpwuid(os.geteuid()), not hardcoded)
  2. Terminal file patterns — direct cat (stdout to terminal), echo >, printf >, heredoc, tee, bare redirect patterns, sed -i, and perl -pi. Pipeline uses of cat (e.g. cat file | head) are allowed.
  3. Write-file on existing file — write_file on a path that already exists
  4. Patch on memory files — patch targeting a path ending with memories/MEMORY.md or memories/USER.md. Plain MEMORY.md / USER.md in other directories is allowed.
  5. GitHub / raw.githubusercontent.com web access — web_extract / browser_navigate targeting github.com or raw.githubusercontent.com; use gh CLI or curl instead
  6. Consecutive process polling — process(action="poll") is blocked on the third consecutive poll with no intervening tool call; any non-poll tool resets the count
  7. cron/jobs.json lockdown — write_file / patch on cron/jobs.json blocked; use cronjob create/update instead. Read access allowed.
  8. Terminal home-root operand — blocks any shell command that uses a protected home root as an operand (e.g. find ~, rg pattern ~, grep -R ~, fd ~, tree ~, du -sh ~, glob ~/*). Also blocks locate/plocate/mlocate. Subpaths (e.g. ~/.hermes) are allowed.
  9. execute_code home-root — per-call AST analysis on each traversal function (os.walk, glob.glob, Path.rglob, subprocess, os.system). Only blocks when the call's own path argument is a protected home root. Dynamic arguments that can't be statically resolved pass as a known limitation.
  10. Bounded-output terminal — blocks commands likely to produce unbounded output: find <dir> -type f without -maxdepth or -print -quit; rg --files --hidden --no-ignore; fd --hidden --no-ignore. find | head is allowed (head limits output). find | sort | head is blocked (sort consumes full output first).

All guards return hard blocks — the tool never executes.

How it works

  • Single pre_tool_call hook dispatches by tool_name The terminal guard uses 9 predicates: 8 file-write predicates (Guard 2) + 1 bounded-output predicate (Guard 10).
  • /dev/null redirects excepted (discard, not a file write)
  • Quoted > inside echo/printf strings correctly ignored
  • Poll state is cleaned lazily after 24 hours and holds at most 1,024 sessions; the least-recently-seen entry is evicted when full

Installation

Clone to the Hermes user plugins directory:

git clone https://git.xlion.tw/xlionjuan/kuri-tool-guard.git \
    ~/.hermes/plugins/kuri-tool-guard

Enable

hermes plugins enable kuri-tool-guard

Takes effect after a gateway restart (/restart or restart the Hermes gateway service).

Using in other profiles

mkdir -p ~/.hermes/profiles/<profile>/plugins
ln -s ../../../plugins/kuri-tool-guard \
    ~/.hermes/profiles/<profile>/plugins/kuri-tool-guard
hermes plugins --profile <profile> enable kuri-tool-guard

Verification

cd ~/.hermes/plugins/kuri-tool-guard
just verify

just verify runs ruff lint and format checks, Bandit, Vulture, ty, and pytest. Run uv sync --group dev once before the first full verification.