kuri-tool-guard/AGENTS.md

6.3 KiB

kuri-tool-guard

Consolidated pre_tool_call plugin with high-friction, good-faith policy guards. It is host-side policy rather than a complete hostile-model sandbox.

Author: Kuri

Verification

just verify         # full pipeline: lint → format-check → bandit → vulture → ty → pytest
just test           # pytest only (fastest smoke test)

Quick smoke test (minimal Python environment)

cd ~/.hermes/plugins/kuri-tool-guard
PYTHONPATH=. python3 -m pytest tests/ -v

For the full just verify pipeline, run uv sync --group dev once.

Completion gate

just verify is the mandatory completion gate for every code, test, fixture, or documentation change in this repository, whether or not a commit is requested.

A task is not complete unless just verify exits with status 0.

  • Running individual verification commands does not replace just verify.
  • Passing tests alone does not count as completion.
  • Failures believed to be pre-existing still make the gate fail.
  • Do not silently accept, suppress, baseline, or reclassify failures.
  • If the gate fails, fix the failure within the authorized scope or report the exact blocker and leave the task marked incomplete.
  • Changing lint configuration, adding broad ignores, adding noqa, or changing verification policy only to make the gate pass requires explicit owner approval.
  • The final report must include the exact just verify exit status.

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 any operand (e.g. echo /home/alice, stat /home/alice, find /home/alice). Subpaths (e.g. ~/.hermes) are allowed. Also blocks locate/plocate/mlocate.
  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).
  11. Skill directory lockdown — patch / write_file targeting any Hermes skill root ($HERMES_HOME/skills or <home>/.hermes/skills, including profiles/*/skills); use skill_manage instead. Terminal writes are not blocked.

All guards return hard blocks — the tool never executes.

How it works

  • Single pre_tool_call hook dispatches by tool_name
  • Terminal guard (Guard 2) uses 8 predicate functions in a registry (_TERMINAL_PREDICATES)
  • Terminal home-root guard (Guard 8) uses operand-based token checking (no command-name denylist)
  • execute_code guard (Guard 9) uses per-call AST analysis — each traversal call's own argument is evaluated in isolation
  • Bounded-output guard (Guard 10) runs as a terminal predicate, independent of home-root policy
  • /dev/null redirects excepted (discard, not a file write)
  • Poll state is cleaned lazily after 24 hours and holds at most 1,024 sessions
  • Protected home roots determined via pwd.getpwuid(os.geteuid()) — no hardcoded usernames

Adding a New Guard

  1. Add a _guard_* function returning Optional[dict[str, str]]
  2. Wire it in _on_pre_tool_call dispatcher
  3. Add tests in tests/ under the corresponding test file (e.g. test_home_policy.py, test_terminal_guards.py)
  4. Run just verify before finalising

Testing

Tests are organised by guard category across multiple files:

Test class Guard(s) File
TestHomeRootGuard Guard 1 — home root (search tools) tests/test_home_policy.py
TestTerminalGuardPredicates Guard 2 — each terminal predicate in isolation tests/test_terminal_predicates.py
TestTerminalGuardCombined Guard 2 — _match_terminal_predicate orchestration tests/test_terminal_guards.py
TestTerminalGuardMiddleware Guard 2 — _on_pre_tool_call hook interface for terminal tests/test_terminal_guards.py
TestWriteFileGuard Guard 3 — write_file on existing files tests/test_write_file.py
TestPatchMemoryGuard Guard 4 — patch on memory files tests/test_patch_memory.py
TestGitHubWebGuard Guard 5 — GitHub.com web access tests/test_github_web.py
TestProcessPollGuard Guard 6 — consecutive poll state, TTL, and capacity tests/test_process_poll.py
TestCronJobsJsonGuard Guard 7 — cron/jobs.json lockdown tests/test_cron_jobs.py
TestTerminalHomeRootGuard Guard 8 — terminal home-root operand + locate tests/test_terminal_home_root.py
TestExecuteCodeGuard Guard 9 — execute_code per-call protection tests/test_execute_code.py
TestBoundedOutputPredicate Guard 10 — bounded-output terminal filter tests/test_bounded_output.py
TestPolicyFixtures All — policy fixture integration tests/test_policy_integration.py
TestManifestMetadata All — manifest and version consistency tests/test_dispatcher.py
TestDispatcher All — multi-guard orchestration tests/test_dispatcher.py