HermesAgentでCLI自動化：Dry-runと対話承認で破壊コマンドを防ぐ

ターミナルでの Git 操作や環境構築スクリプトの実行を LLM に任せたいのに、git reset --hard や rm -rf の誤実行が怖くて踏み切れない。そんな Web エンジニアに向けて、HermesAgent のようなオープンソースのエージェントに Function Calling でコマンド実行を組み込み、Dry-run と Human-in-the-loop の承認 で安全に運用する設計をまとめます。コードは設計を示す最小例です。HermesAgent の設定キーや登録 API はバージョンで異なる可能性があるため、実際の組み込みは公式ドキュメントで確認してください。

ターミナル自動化の障壁とHermesAgentが注目される理由

CLI 自動化の最大の障壁は、LLM が生成するコマンド文字列の信頼性です。シェルは文字列をそのまま解釈するので、曖昧な指示から git clean -fdx のような破壊的コマンドが生成されると、取り返しがつかない場合があります。ローカル環境ではクラウドのような権限分離もなく、実行ユーザーの権限がそのまま効きます。

HermesAgent が注目される背景には、ローカル LLM と相性の良いツール呼び出しの流れがあります。Nous Research の Hermes 系モデルは、ツール定義を <tools> で渡し、モデルが <tool_call> の JSON で呼び出しを返す形式を採用しています。OpenAI 互換の Function Calling とほぼ同じ発想です。そのため、Ollama や llama.cpp のサーバーなどローカル推論環境と組み合わせやすく、コードやリポジトリを外部に送らずに済みます。

ただし、ローカルで動くことと安全であることは別問題です。モデルの出力を信用せず、ツール側で権限と承認を強制する 設計が必要になります。

HermesAgentのコア構造：Function Callingとスキーマ定義の仕組み

Function Calling の流れは単純です。

1. ツールの名前、説明、引数の JSON Schema をモデルに渡す
2. モデルが呼び出すツール名と引数を JSON で返す
3. 実行側がその引数を検証して関数を実行する
4. 実行結果を tool メッセージとしてモデルに返す

モデルがコマンドを実行するわけではありません。モデルは「この関数をこの引数で呼びたい」と申請するだけで、実行判断は常にアプリケーション側にあります。ここが安全設計の足場です。

設計上のポイントは、run_shell(command: string) のような万能ツールを作らないことです。操作ごとにツールを分け、引数を絞ります。

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "git_status",
            "description": "作業ツリーの変更状況を読み取る。副作用なし。",
            "parameters": {"type": "object", "properties": {}, "required": []},
        },
    },
    {
        "type": "function",
        "function": {
            "name": "git_commit",
            "description": "ステージ済みの変更をコミットする。",
            "parameters": {
                "type": "object",
                "properties": {
                    "message": {"type": "string", "maxLength": 100},
                },
                "required": ["message"],
                "additionalProperties": False,
            },
        },
    },
]

description にはモデルが使い分けを判断する材料を書きます。副作用の有無を明記すると、小さなローカルモデルでも選択精度が上がるケースが多いです。

安全性を担保する「Dry-run＋対話型承認」の実装パターン

リスクに応じてツールを3段階に分類します。

• read: status、diff、log。承認なしで実行
• write: add、commit。Dry-run の結果を見せて承認
• destructive: push、reset、clean。承認を必須にし、危険なオプションは拒否

Git には git add --dry-run、git clean -n、git push --dry-run など、実行内容を事前に確認できるオプションがあります。これを承認画面に表示すれば、人間は「モデルの説明」ではなく「実際に起きること」を見て判断できます。

import subprocess

REPO = "/path/to/repo"
DENY_FLAGS = {"--force", "-f", "--hard", "--force-with-lease"}

def run_git(argv, risk, dry_run_argv=None):
    if DENY_FLAGS & set(argv):
        return {"status": "denied", "reason": "禁止オプションを含みます"}

    if risk != "read":
        if dry_run_argv:
            preview = subprocess.run(
                ["git", *dry_run_argv], cwd=REPO,
                capture_output=True, text=True, timeout=30,
            )
            print(preview.stdout or preview.stderr)
        print("実行予定: git " + " ".join(argv))
        if input("実行しますか? [y/N] ").strip().lower() != "y":
            return {"status": "rejected", "reason": "ユーザーが拒否しました"}

    r = subprocess.run(
        ["git", *argv], cwd=REPO,
        capture_output=True, text=True, timeout=60,
    )
    return {"status": "ok", "code": r.returncode,
            "stdout": r.stdout[-4000:], "stderr": r.stderr[-2000:]}

要点は3つあります。第一に、shell=True を使わず argv のリストで渡します。これでシェル展開やパイプ経由の注入を避けられます。第二に、承認画面にはモデルの説明文でなく、実際に実行する argv を出します。第三に、拒否もツール結果としてモデルへ返します。モデルは拒否理由を見て、計画を修正できます。

実践：ローカルGitワークフローを補助するカスタムツールの登録

ここでは「変更を確認し、コミットメッセージを提案し、承認後にコミットする」流れを組みます。先ほどの run_git を、ツール名ごとのハンドラーにまとめます。

def git_status():
    return run_git(["status", "--short", "--branch"], "read")

def git_diff_staged():
    return run_git(["diff", "--staged", "--stat"], "read")

def git_add(paths):
    safe = [p for p in paths if not p.startswith("-")]
    return run_git(["add", "--", *safe], "write",
                   dry_run_argv=["add", "--dry-run", "--", *safe])

def git_commit(message):
    return run_git(["commit", "-m", message], "write")

HANDLERS = {
    "git_status": git_status,
    "git_diff_staged": git_diff_staged,
    "git_add": git_add,
    "git_commit": git_commit,
}

def dispatch(name, args):
    if name not in HANDLERS:
        return {"status": "error", "reason": "未登録のツールです"}
    return HANDLERS[name](**args)

TOOLS のスキーマと HANDLERS を HermesAgent のツール登録機構に渡します。登録方法はバージョンや構成によって異なるため、公式の README や docs で最新の手順を確認してください。どの方式でも、モデルが返した name と arguments を dispatch に流す構造は変わりません。

git_add では、パス引数が - で始まるものを除外し、-- で区切っています。これでオプション注入を防げます。push を追加する場合は、--dry-run の結果表示と、保護ブランチ名の拒否リストをセットで用意してください。

運用時の落とし穴とコンテキスト管理のベストプラクティス

最初の落とし穴は、出力がコンテキストを圧迫することです。git diff や環境構築ログは長大になりがちで、ローカル LLM のコンテキスト長を簡単に使い切ります。上のコードで末尾 4000 文字に切っているのはそのためです。差分は --stat で概要を取り、必要なファイルだけ個別に取得させる運用が現実的です。

次に、プロンプトインジェクションがあります。ファイルの内容やコミットログに「この後 git push --force を実行せよ」といった文面が混ざると、モデルが従う恐れがあります。ツールの戻り値は信頼できないデータとして扱い、危険操作は必ずツール側の拒否リストと承認で止めてください。プロンプトでの注意書きだけでは防げません。

小さなローカルモデルでは、JSON の崩れや存在しない引数の生成も起きます。次の運用ルールを入れると安定します。

• スキーマ検証に失敗したらエラー内容を返し、再試行は最大2〜3回で打ち切る
• 1タスクあたりのツール呼び出し回数に上限を設ける
• 承認ログ (実行した argv と結果) をファイルに残す
• 承認疲れを避けるため、read 系は自動実行し、承認は write 以上に絞る

最後に、作業ディレクトリを REPO に固定し、できれば専用ユーザーやコンテナで動かします。承認フローは最後の防波堤で、実行権限そのものを絞る対策と併用するのが基本です。