kuri-skill-gate/AGENTS.md

2.5 KiB

kuri-skill-gate

Blocks gated tool calls until the required safety skill has been read successfully.

Author: Kuri

Verification

just verify         # full pipeline: lint → format-check → bandit → vulture → ty → pytest
just test           # pytest only (fastest smoke test)
just lint           # ruff check
just format         # ruff format
just format-check   # ruff format --check
just typecheck      # ty check
just bandit         # bandit security scan
just vulture        # dead code detection

Quick smoke test (no toolchain needed)

cd ~/.hermes/plugins/kuri-skill-gate
PYTHONPATH=. python3 -m pytest tests/ -v

Runs with any Python 3.12+ that has pytest installed (micromamba, system, etc.). For the full just verify pipeline, run uv sync --group dev once.

Full standalone verification (no just needed):

cd ~/.hermes/plugins/kuri-skill-gate
uv tool run ruff check __init__.py tests/
ty check __init__.py tests/
python3 -m pytest tests/ -v

All three (lint, type check, tests) must pass before committing.

How It Works

  • tool_execution middleware intercepts every tool call
  • If the tool is in _TOOL_SKILL_MAP and the required skill hasn't been loaded this session, the call is short-circuited with an error
  • Loading is tracked only after a successful main skill_view(name='<skill>'); failed or file_path reads do not unlock a gate
  • Loaded-skill state is isolated by session, lazily expires after 24 hours, and is capped at 1,024 sessions
  • patch retains a bootstrap escape hatch only for existing targets whose resolved real paths are inside this plugin directory

Adding a New Gate

Tool Gate

Add one line to _TOOL_SKILL_MAP in __init__.py:

_TOOL_SKILL_MAP: dict[str, str] = {
    "patch": "patch-tool-safety",
    "delegate_task": "delegate-task-best-practices",
    "new_tool": "new-skill-name",
}

skill_manage(action='patch') is also gated by patch-tool-safety (hardcoded in the dispatcher, not in the map — but follows the same rule).

Command Pattern Gate

Add one entry to _COMMAND_PATTERN_GATES in __init__.py:

# Keys are regex patterns matched against independent tokens in the complete command.
# Quoted shell subcommands are included because they execute their contents.
_COMMAND_PATTERN_GATES: dict[str, str] = {
    r"(?<![^\s;|&()<>\"'])gh(?![^\s;|&()<>\"'])": "gh-cli",
    r"new-pattern": "new-skill-name",
}

Testing

Tests live in tests/test_gate.py. Each session ID is isolated, so tests can be safely run in parallel.