kuri-skill-gate/AGENTS.md

80 lines
2.5 KiB
Markdown

# kuri-skill-gate
Blocks gated tool calls until the required safety skill has been read successfully.
**Author:** Kuri
## Verification
```bash
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)
```bash
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):**
```bash
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`:
```python
_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`:
```python
# 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.