hermes-subagent-output-guide/AGENTS.md

2.8 KiB

subagent-output-guide

A Hermes user plugin that automatically injects text-report delivery guidance into subagent prompts. Concise reports stay in the response; long reports use a specified location or /tmp/.

How it works

Three hooks working together:

  1. subagent_start — records child_session_id as belonging to a child agent
  2. pre_llm_call — checks if the current session_id is a known child session. If so, and it's the first turn, injects a context block into the user message that keeps concise reports in the response and saves long text reports under /tmp/ when no report location is specified.
  3. on_session_end — cleans up the tracked child session when it ends, keeping the plugin's process memory free from stale entries.

Verification

  • pytest (all tests under tests/)
  • ruff (linting + formatting)
  • ty (static type checking)
  • bandit (security scan)
  • vulture (dead code detection)

Run before every commit:

uv run ruff check .          # Lint
uv run ruff format --check . # Format check
uv run bandit -r __init__.py tests/ -c pyproject.toml  # Security scan
uv run vulture . .vulture_whitelist.py --exclude '.venv,dist,.git,__pycache__'  # Dead code
uv run ty check . --exclude .vulture_whitelist.py  # Type check
uv run pytest                # Unit tests

Or via just:

just verify     # Full suite
just clean      # Remove __pycache__ and .pyc files

Structure

~/.hermes/plugins/hermes-subagent-output-guide/
├── plugin.yaml          # Plugin manifest (name, version, hooks)
├── __init__.py          # Plugin entry — register() + hook callbacks
├── AGENTS.md            # This file
├── tests/
│   ├── __init__.py
│   ├── test_tracker.py
│   ├── test_guidance.py
│   └── test_registration.py
├── .gitignore
├── .vulture_whitelist.py
├── .github/
│   └── workflows/
├── pyproject.toml       # Project metadata, dependencies, tool config
├── justfile             # Task runner (verify, test, lint)

Python toolchain

  • Python 3.11 (>=3.11, <3.12)
  • uv for package management (not pip)
  • ruff for linting and formatting
  • ty for static type checking
  • bandit for security scanning
  • vulture for dead code detection
  • pytest for testing

Workflow

All code changes must pass:

uv run ruff check .          # Lint
uv run ruff format --check . # Format check
uv run bandit -r __init__.py tests/ -c pyproject.toml  # Security scan
uv run vulture . .vulture_whitelist.py --exclude '.venv,dist,.git,__pycache__'  # Dead code
uv run ty check . --exclude .vulture_whitelist.py  # Type check
uv run pytest                # Unit tests

Git conventions

  • Branch name: fix/, feat/, chore/ prefix
  • Commit message format: <type>: <short description>