shield-kya

@shield-agent/kya

AI エージェントの監査証跡とトレーサビリティ。 すべてのコーディングエージェントが何をしたかを確認し、リスクのある呼び出しをブロックし、人間に承認を求め、署名付きの信頼チェックでそれを証明できます。すべてのツール呼び出しは、リアルタイムのローカルダッシュボードに記録され、Agent Trust Baseline と照合できます。ローカルの KYA はブロックではなく警告を出し、フェイルオープンで動作します（エラーが発生すると呼び出しを許可します）。例外は、小規模な拒否リスト（常に拒否される危険な呼び出しの短いリスト）です。実際の強制適用は、MCP ゲートの経路とホスト型プレーン（Shield Agent クラウドサービス）で実行されます。コマンドは 1 つ。MIT ライセンスのもと、永久に無料です。

npm i -g @shield-agent/kya@latest && kya start

Node.js 22+ が必要です（24 を推奨）。MCP を読み込むため、Cursor / Claude Code / Codex を一度再起動してください。ホスト型デスクトップアプリ：shield-agent.com。

Shield の Know Your Agent パス用 CLI およびローカル MCP ゲートです。

まず Shield に問い合わせるエージェントは、Allow、Review、または Deny を受け取ります。エージェントを登録し、ツールをラップする（または MCP ゲートやホスト型プレーン経由でルーティングする）と、Review の場合は人間の応答を待ちます。ローカルフックは記録と拒否リストのブロックのみを行います（フックのインターセプトを参照）。強制適用はホスト型環境で行われます。このパッケージはネットワークをスキャンしません。evaluate を一度も呼び出さないエージェントは、意図的に可視化されません。

ウォークスルー：使い方。

npx @shield-agent/kya@latest --help

Node.js 22+ が必要です（engines.node: >=22）。24 が推奨バージョンです。Node 20 と 21 はサポート対象外ですが、動作します。CLI は 1 行の警告を表示します。Node 18 以前はサポート対象外で、一部の機能（HTTP serve-mcp、ゲートウェイの OTLP レシーバー）が動作しません。22 未満の場合、CLI は Node 24 のインストール（volta / fnm / nvm / brew 経由）、自身の再インストール、コマンドの完了を提案します。拒否した場合は、警告を表示して続行します。kya hook は警告も確認も表示しません。

MCP または OpenAPI を扱えるホストであれば、どれでも利用できます。垂直パックは任意です。ポリシーの決定ポイント（Allow または Deny を決める場所）は Shield のみです。このゲートは、取り消せない副作用（元に戻せない変更）を自動承認することはありません。

認証済みプレーンに対して KYA_API_KEY が空の場合、ネットワークコマンドはゼロ以外の終了コードを返します。eval-tool、wrap、invoke は、ALLOW の場合は 0、REQUIRE_APPROVE の場合は 4、DENY または不明の場合は 1 を返すため、eval-tool && write のような行でゲートを迂回することはできません。

--offline を指定すると、有料クラウドを使わずにサンプルの evaluate を実行できます（DENY や REQUIRE_APPROVE のデモに便利です）。エージェントの作成自体もツールです。オフラインでは、kya.agent.register は REQUIRE_APPROVE を返します。承認を作成する Allow、break-glass、approve の各 mint モードは、コントロールプレーン上で利用できます。

ワンライナー

npm i -g @shield-agent/kya@latest && kya start

プロジェクトディレクトリで実行してください。（このリポジトリをクローンした場合は、./scripts/install-local.sh を実行すると npm によるインストールの代わりになります。）

同じパッケージをインストールする別の方法（npm が引き続き推奨の方法です）：

# Homebrew. Homebrew 7 may ask you to trust a third-party tap: run `brew tap The-Pixel-Boys/tap` first.
# The formula installs about 270MB because of the optional semantic-search runtime.
brew install The-Pixel-Boys/tap/shield-kya

# Scoop (not yet verified on Windows)
scoop bucket add The-Pixel-Boys https://github.com/The-Pixel-Boys/scoop-bucket.git
scoop install shield-kya

Claude Code ユーザーはプラグインもインストールできます。GitHub Copilot CLI ユーザーはCopilot CLI プラグインをインストールできます（インストール前に最初の段落をお読みください）。Codex CLI ユーザーはCodex プラグイン、Gemini CLI ユーザーはGemini CLI 拡張機能をインストールできます。Cline ユーザーは、npm install -g @shield-agent/kya@latest を実行してから、llms-install.md に従ってください。Cline が手順に従えるように記述されていますが、このファイルだけを使った Cline の実行はまだテストされていません。

このコマンドは .kya/ を初期化し、ローカル MCP（.mcp.json、mcp.json、.cursor/mcp.json → kya serve-mcp --stdio）を設定します。また、検出したインストール済みホストすべてのユーザーレベル設定（~/.claude.json、~/.kimi-code/、~/.grok/、~/.cursor/、…）も設定し、ライブアクティビティレポートを開きます。レポートはバックグラウンドで動作するため、ターミナルをそのまま使えます。kya stop で停止し、kya receipt --open で再度開けます。Cursor、Kiro、Qwen、Amp、Droid、Cline、Grok は再起動せずにサーバーをすぐに認識します（Kimi の場合は、新しいセッションを開始してください）。Claude Code、Codex、OpenCode、Gemini、Copilot CLI、Kilo CLI は次回の起動時に読み込みます。claude --resume を使えば会話を継続できます。

kya start --no-open   # wire only
kya start --force     # rewrite MCP blocks
# Receipt change previews (clipped + redacted): on by default for writes
# KYA_DIFF_PREVIEW=0 to disable

ホストごとに 1 つのコマンド

kya start は Claude Code、Cursor、および .mcp.json を読み込むすべてのホストに対応しています。また、検出したインストール済みホストすべてのユーザーレベル設定も自動で構成します。それ以外のホストについては、kya connect を実行すると、ホスト固有の設定形式で直接書き込みます。

kya connect claude              # ~/.claude.json (merges mcpServers only)
kya connect grok                # ~/.grok/config.toml (appends [mcp_servers.shield-kya])
kya connect opencode            # ~/.config/opencode/opencode.json
kya connect qwen                # ~/.qwen/settings.json
kya connect amp                 # ~/.config/amp/settings.json
kya connect qwen --project      # project scope instead of global
kya connect kiro --force        # overwrite an existing shield-kya entry

接続時には既存の設定が統合されます。解析できないホスト設定を書き換えることはなく、ほかのサーバーやキーも保持されます。対応ホスト：claude、grok、opencode、kilo、kiro、qwen、kimi、mastracode、amp、copilot、cursor。各ホストでは serve-mcp --stdio を KYA_OFFLINE=1 で設定し、ゲートを API キーなしで起動します。認証が必要なプレーンを指定する場合は、ホストの環境変数に KYA_API_KEY を設定してください。

connect の接続先がないホストでも使用できます。kya wrap --offline -- <agent command> を実行すると、同じ評価ゲートを任意の CLI の前段に配置できます。検証手順とトラブルシューティングを含むホストごとの手順は、docs/hosts/ にあります。

フックによるインターセプト

kya start は、検出したフック対応ホストすべてに PreToolUse フックも設定します。対象は Claude Code（~/.claude/settings.json、既存設定へのマージのみ）、Grok（~/.grok/hooks/shield-kya.json、kya 管理ファイル）、Kimi Code（~/.kimi-code/config.toml、[[hooks]] への追記）です。エージェントが実行するすべてのツール呼び出しは、まず kya hook を通過します。ローカルで評価され（オフライン、1秒未満、ネットワーク接続なし）、グローバルレコード（trail）に書き込まれます。（匿名の利用状況統計にオプトインしている場合、フックは1日に最大1回、デタッチされたヘルパーも起動します。詳細は匿名の利用状況統計（オプトイン、デフォルトでは無効）をご覧ください。）

判定の対応関係：ローカルの禁止リストによる DENY はツール呼び出しをブロックします（終了コード 2 と、permissionDecision: "deny" を含む hookSpecificOutput の拒否 JSON）。ALLOW と REQUIRE_APPROVE は助言としてレコードに記録され、呼び出しは続行されます。手動で設定する場合は、フックコマンドに --strict を指定すると、REQUIRE_APPROVE もブロックできます。

フックはフェイルオープンです。フックのエラーまたはタイムアウトが発生した場合、呼び出しは許可されます。フックはアラートとローカルの禁止リスト適用のためのものであり、唯一の防御策ではありません。プレーンの強制は引き続き MCP の kya.policy_evaluate 経由で行われます。フックは新しいセッションから有効になります。3つのホストはいずれもセッション開始時にフックを読み込みます。

kya connect claude --hooks   # wire the PreToolUse hook by hand
kya connect grok --hooks
kya connect kimi --hooks

Claude Code プラグイン

このリポジトリは、shield-kya という Claude Code プラグインマーケットプレイスでもあり、kya というプラグインが1つ含まれています。

/plugin marketplace add The-Pixel-Boys/shield-kya
/plugin install kya@shield-kya

このプラグインは助言のみを行い、フェイルオープンで動作します。すべてのツール呼び出しをローカルレコード（~/.kya/trail.jsonl）に記録し、小規模な禁止リストに該当する場合のみブロックします。kya が見つからない場合、クラッシュした場合、またはタイムアウトした場合、ツール呼び出しは続行され、何も記録されません。オフラインで評価するため、Hold も承認機能もありません。ホスト型の強制適用は MCP ゲート経由で行います。

チームへの展開：extraKnownMarketplaces（shield-kya の GitHub ソース）と enabledPlugins（"kya@shield-kya": true）をリポジトリの .claude/settings.json にコミットするか、管理設定で組織全体に強制適用してください。詳細と制限については、docs/hosts/claude-plugin.mdをご覧ください。

GitHub Copilot CLI プラグイン

まず確認してください。 公開リポジトリにまだ plugins/kya-copilot フォルダーがない場合（これを含むリリース以前のすべてのリリース）、Copilot CLI にプラグインをインストールしないでください。インストールすると、Copilot は Claude Code プラグインを使用し、Copilot CLI 1.0.98 はすべてのツール呼び出しを拒否します（「Denied by preToolUse hook ... (hook errored)」）。すでにインストールしている場合は、copilot plugin uninstall kya@shield-kya を実行し、フォルダーを含むリリースが公開されるまでは kya connect copilot を使用してください（MCP サーバーのみ。詳細はその他のホストをご覧ください）。

このリリース以降は、次の手順で使用できます。

copilot plugin marketplace add The-Pixel-Boys/shield-kya
copilot plugin install kya@shield-kya

Copilot は .claude-plugin/marketplace.json より先に .plugin/marketplace.json を読み込むため、kya@shield-kya は Agent Plugins v1 マニフェスト（plugin.json）、com.github.copilot/hooks/hooks.json のフック、mcp.json の MCP サーバーを含む plugins/kya-copilot に解決されます。Claude Code と Codex は引き続き plugins/kya を読み込み、このフォルダーは参照しません。動作は同じで、助言のみを行い、フェイルオープンです。Copilot は、ツール実行前のフックがゼロ以外の値で終了するとツール呼び出しを拒否します。そのため、フックは Copilot の PATH に node がない場合は何もしない bash コマンドです。それ以外の場合は scripts/copilot-hook.mjs を実行します。このスクリプトは kya の禁止リストによる拒否のみを転送し、終了コードが 2 以外なら 0 に変換します。記録には、その PATH に Node.js 22 以降が必要です。Copilot は MCP ツール名を <server>-<tool>（例：postgres-drop_table）としますが、禁止リストはまだこの形式を認識しないため、MCP 呼び出しは記録されますがブロックされません。レコードの行では、製品名は other と表示されます。macOS 上の Copilot CLI 1.0.98 でテスト済みです。現時点では Windows にインストールしないでください。ツール実行前のフックは bash 形式のみで、Windows 上では実行されていません。Windows では kya connect copilot を使用してください。詳細はdocs/hosts/copilot.mdをご覧ください。

Codex プラグイン

同じリポジトリは、同じ kya プラグインを含む Codex プラグインマーケットプレイス（.agents/plugins/marketplace.json）でもあります。

codex plugin marketplace add The-Pixel-Boys/shield-kya
codex plugin add kya@shield-kya

次に、Codex CLI で /hooks を開き、Shield KYA の 2 つのフックを信頼してください。信頼するまでは、Codex はプラグインフックを実行しません。Codex が信頼するのはフックスクリプトではなくフックコマンドです。SessionStart コマンドには kya のバージョンが含まれているため、kya のリリースごとに再度確認が求められます。また、Codex は起動時に Git マーケットプレイスを自動アップグレードするため、このリポジトリにプッシュできる人なら誰でも、次回実行される内容を変更できます。チームではリリースの参照を固定できます（ガイドを参照）。動作は Claude Code プラグインと同じです。アドバイザリーモードでフェイルオープンし、Codex がフック経由で送信するすべてのツール呼び出し（シェル、apply_patch、MCP、その他のローカルツール。ウェブ検索などのホスト型ツールは除く）を記録し、禁止リストにあるものだけをブロックします。MCP サーバーはバンドルされていません。kya connect codex で追加してください。詳細：docs/hosts/codex.md。

Gemini CLI 拡張機能

リポジトリのルートは Gemini CLI 拡張機能（gemini-extension.json + hooks/hooks.json）でもあります。

gemini extensions install https://github.com/The-Pixel-Boys/shield-kya

動作は他のプラグインと同じです。アドバイザリーモードでフェイルオープンし、Gemini が BeforeTool フック経由で送信するすべてのツール呼び出しを記録し、禁止リストにあるものだけをブロックします。Gemini は個別の信頼手順なしで拡張機能のフックを実行します。この拡張機能は、リリース時の kya のバージョンを固定します。MCP サーバーはバンドルされていません。MCP の例を参照してください。詳細：docs/hosts/gemini.md。

Gate（ローカル MCP ゲートウェイ）

kya gate は、すでに使用している MCP サーバーの前段に、ループバック専用リスナー（127.0.0.1、デフォルトポート 3930）を 1 つ配置します。ホストはゲートウェイと通信し、ゲートウェイは実際のサーバーに呼び出しを振り分けます。ツールごとのポリシーは、上位 20 サーバーの分類に基づきます。破壊的な名前（drop／truncate／purge／transfer）と、各サーバーの ADMIN ティアのツールは無条件に拒否され、tools/list から除外されます。それ以外はすべて監視モードで実行され、許可されて記録されます。すべての呼び出しはローカル記録とライブレポートに書き込まれ、OTLP としてホスト型インテークに転送することもできます。

ゼロタッチ： kya start を実行すると、すでにこの処理が行われます。検出されたホスト設定からサードパーティ製 MCP サーバーをスキャンし、.kya/gateways.json にインポートします（各サーバーの取得元を示す importedFrom フィールドを付けて記録します）。その後、ゲートウェイバイナリをインストールしてリスナーを起動し、インポートしたサーバーをゲートウェイ経由でルーティングするよう、各ソースホストの設定を書き換えます。削除を行う前に、元のホスト設定を .kya/backups/ に保存します。対象が見つからなければ、ダウンロードもリスナーの起動も行いません。kya start --no-gate または KYA_GATE=off で無効にできます。バイナリのダウンロードに失敗した場合（オフライン、ネットワークなし）、kya start は一度だけ警告し、ゲートウェイなしで続行します。ホスト設定には手を加えません。完全に制御したい場合は、以下の手動手順も引き続き利用できます。

kya gate init     # scaffold .kya/gateways.json with ready-to-move recipes
# edit gateways.json: move a recipe into "servers", fill its placeholders
kya gate setup    # download the pinned gateway binary into .kya/bin
kya gate run      # generate the gateway config, start the listener detached
kya connect claude --gate   # point the host at the gateway (server key shield-kya-gate)
kya gate doctor   # binary, config, listener health, loopback-only posture

kya gate stop は、スーパーバイザーとその配下のバイナリを停止します。正直なところ、kya gate setup（および、管理対象のサーバーが見つかった場合に限る kya start の自動セットアップ）では、固定されたゲートウェイバイナリを当社のリリースからダウンロードします。それ以外に何かをダウンロードすることはありません。ほかにネットワークを使用するのは、docs/telemetry.md にあるオプトイン方式の匿名利用統計だけです。これは同意しない限り無効です。run がダウンロードを行うことはありません。監視モードでは、許可された呼び出しがブロックされず記録されます。唯一の強制的な停止措置は上記の拒否セットであり、プレーンの強制は kya.policy_evaluate が引き続き担います。kya connect <host> --gate で対象となるホストは、通常の connect と同じです。Grok の設定では、config.toml に [mcp_servers.shield-kya-gate] の URL テーブルが追加されます（Grok は HTTP 経由のリモート MCP サーバーに対応しています）。サーバーごとのティアと設定例：docs/mcp-servers.md。

さらに詳しい手順（任意）

# Offline sample evaluate
kya eval-tool --offline --tool-id org.sample.never.event --irreversible
kya wrap --offline --tool-id Write --irreversible --args '{"path":"src/x.ts","content":"hi"}'
kya receipt --open
# Org Hold: KYA_HOLD=1 kya wrap …
kya dash --once --offline

インストールハブ：https://shield-agent.com/install

アクティビティ記録（グローバル）

すべてのプロジェクトで共有される単一の記録（トレイル）です：~/.kya/trail.jsonl（KYA_HOME を設定すると ~ の代わりに使用されます）。どのディレクトリからでも kya receipt --open を実行すると、すべてのプロジェクトのアクティビティが表示されます。各イベントにはプロジェクトのフォルダー名が含まれます。2 つ以上のプロジェクトが登場すると、レポートにプロジェクト別の集計が追加され、フィードの各項目にもプロジェクトが表示されます。以前のプロジェクト別ファイル <project>/.kya/trail.jsonl も引き続き読み込まれて統合されるため、移行は不要です。記録の上限は 1 MB です（末尾から読み込むため、古いイベントから順に消えていきます）。すべてのプロジェクトで共有されます。

レポート自体はダッシュボードです。最上部のヒーロー行には、ライブの Certify 結果、判定の内訳、アクティビティのスパークライン、ショーバック（エージェントあたりのコスト）が表示されます。その下にはタブ付きセクションがあります：Overview（分析、セッション、理由）、Certify（ライブの要件をすべて記載した表。ドメインごとに要件をグループ化し、ステータス、証拠、証明を表示）、Activity（フィルター可能なイベントフィード）、System（接続済みホスト、サンドボックス、ORR）。すべてが、単一のオフライン HTML ページとして提供されます。ライブビューに追加される外部リンクは「Star on GitHub」の 1 つだけです。kya start で起動したライブデーモンは、イベントごとにレポートを再描画します。

レポートの共有

kya receipt --share は、現在の期間の編集済みサマリー（判定数の集計、製品と理由コードの内訳、Certify のステータス。パス、ツールの引数、セッション ID は含まれません）を shield-agent.com に公開し、有効期限（7 日間）付きの公開 URL（/r/<id>）を出力します。この URL は誰でも開けます。また、セキュリティ責任者への送信を提案する行も 1 行表示されます。共有ページにはすべて、読者が自分のエージェントを監査できるよう、1 行のインストール手順と、チーム用のホスト型ワークスペースを開始するボタンが表示されます。ページ上の Certify ステータスには、Shield Agent による検証ではなく、CLI による自己申告であることが明記されます。--json を指定すると、コマンドは {"url", "expiresAt"} のみを出力します。--share-url <base> または KYA_SHARE_URL を使うと、別のコレクターを指定できます。

共有は設計上、1 回のみ試行されます（大量発生への対策として、コレクターへの無言の再試行は行いません）。--share-retries <n>（最大 3）を指定すると、429／5xx／ネットワークエラー時に指数バックオフとジッターを使った回数制限付きの再試行が有効になり、サーバーの Retry-After に従います。

自然言語検索

Activity の検索ボックスでは、自然な英語で検索できます。ツール ID、要約、理由コード、判定、プロジェクト、MCP サーバーのラベルを対象とした BM25 検索と、ローカルの MiniLM による意味的な再ランキングを組み合わせています（オプションの依存関係として同梱されており、モデルのランタイムが利用できない場合はレポートが語彙一致のみにフォールバックします）。組み込みの概念用語集が日常的な単語をイベントで実際に使われる語彙に対応付けるため、dangerous で rm／kill／delete／sudo の呼び出しが、blocked で拒否が、held で承認リクエストが見つかります。failed stripe transfers、files written by grok、approval required production のような語句も入力できます。ストップワードの処理とステミングは自動で行われ、グローバル記録全体を対象に同じ検索を利用できます。

• オフライン時または KYA_OFFLINE=1 の場合、検索は語彙一致のみで行われます（モデルはダウンロードされません）。
• デフォルトでは、ライブサーバーが BAAI/bge-small-en-v1.5 を ~/.kya/models に 1 度だけダウンロードし、イベントのベクトルを ~/.kya/search-index.json にキャッシュします。
• KYA_SEARCH_SEMANTIC=off を指定すると、BM25 は維持したままモデルを無効にできます。

ホスト型コンソールでは、同じハイブリッド検索をサーバー側で使用します（Postgres 全文検索と、オプションの OpenAI 互換埋め込み）。そのため、どちらで入力しても同じように検索できます。

デュアルプレーン

 host=ide (authoring)          host=runtime (production)
        │                              │
        └────────── same agent ────────┘
                    identity
                    policy evaluate  → ALLOW | DENY | REQUIRE_APPROVE
                    approval + trail

KYA_HOST=ide または KYA_HOST=runtime を指定してセッションにタグを付けます。どちらの場合も同じポリシーパスが使われます。

環境

変数	必須	意味
KYA_BASE_URL	はい（ネットワークコマンド）	コントロールプレーンのオリジン
KYA_API_KEY	認証が有効な場合	API キー（または decide 動詞用の Bearer JWT）
KYA_HOST	いいえ（デフォルトは ide）	ide | runtime
KYA_AGENT_ID	登録後	エージェントのプリンシパル ID
KYA_MCP_PORT	いいえ（デフォルトは 3920）	HTTP MCP リッスンポート
KYA_OFFLINE	いいえ	サンプル評価では 1／true
KYA_HOLD	いいえ	組織の Hold パスでは 1／true（REQUIRE_APPROVE により人間のチケットが作成されます）
KYA_DASH_PLAN	いいえ	enterprise にすると、ライセンス対象の TUI ペインが有効になります
KYA_DIFF_PREVIEW	いいえ	0 にすると、レシート上の変更プレビューが省略されます
KYA_RECEIPT_AUTO	いいえ	0 にすると、wrap 後のレシート自動表示が無効になります。1 にすると強制されます
KYA_SEARCH_SEMANTIC	いいえ	off にすると MiniLM のセマンティック再ランキングが無効になります（BM25 は引き続き動作します）
KYA_SHARE_URL	いいえ	kya receipt --share の収集先ベース URL（デフォルトは https://shield-agent.com）
KYA_TELEMETRY	いいえ	0／off にすると、匿名利用統計が強制的に無効になります（ドキュメント）。オプトインしない限り無効です
DO_NOT_TRACK	いいえ	1 にすると、KYA_TELEMETRY=0 と同様に匿名利用統計が強制的に無効になります

ゲートモードは、プロジェクトの .kya/config.json でも設定できます。 {"gateMode": "hold"} または {"gateMode": "offline"}（指定できる値はこの2つのみです。 それ以外は無視されます）。ゲート自体（wrap／hook／eval）は、 優先順位 flags > env > config > observe に従います。また、kya certify は 同じリゾルバーを使ってレポートするため、ゲートモードでの certify の結果は常に ゲートの実際の動作を反映します。

MCP ツール

ツール	役割
kya.policy_evaluate	ALLOW | DENY | REQUIRE_APPROVE
kya.session_ingest	リスクの監視／引き上げのみ
kya.request_approval	人間による Hold を作成します。副作用は実行しません

MCP Registry のエントリ：server.json と、パッケージの mcpName io.github.The-Pixel-Boys/shield-kya。

{
  "mcpServers": {
    "shield-kya": {
      "command": "npx",
      "args": ["--no-install", "@shield-agent/[email protected]", "serve-mcp", "--stdio"],
      "env": {
        "KYA_BASE_URL": "http://127.0.0.1:8090",
        "KYA_API_KEY": "${KYA_API_KEY}",
        "KYA_HOST": "ide"
      }
    }
  }
}

Wrap と decide

npx @shield-agent/kya wrap --offline --tool-id org.sample.data.write --irreversible
npx @shield-agent/kya approve --id <approval-id>
npx @shield-agent/kya reject --id <approval-id>

ホストされた高リスクのリクエスト（現在または以前に HIGH 優先度だったもの、または取り消し不能のヒント付きで作成されたもの）は、CLI または TUI から承認できません。ホストされたプレーンは 403 kya.approval_console_mfa_required を返します。ホストされたコンソールで二要素認証コードを使って承認してください。reject は常に使用できます。

wrap は評価を行い、保留中のチケットを作成することがあります。副作用は実行しません。invoke は Allow または APPROVED の後、ライブプレーンに認可を要求します。このマシン上で書き込みを実行することはありません。TUI（dash）では、JWT（sk_* は拒否されます）を使って y で確認した後にのみ、a／x で判断できます。

プロセス内 SDK シム

LangGraph.js、Vercel AI SDK、Mastra、OpenAI Agents TS、または Claude Agent SDK を基盤に構築されたエージェントは、ゲートウェイなしで、ツール呼び出しを同じ評価パス経由にできます。

import { governed, governLangGraphTool, KyaDeniedError } from "@shield-agent/kya/sdk";

const run = governed({ toolId: "write_file", server: "filesystem", fn: myWrite });
await run({ path: "out.txt", content: "hi" }); // throws KyaDeniedError on DENY

デフォルトではオフラインで評価します（ネットワークもホストされたプレーンも使用しません）。明示的に設定すると、ライブプレーンを使用します。governA2aSend は、プロセス内のエージェント間送信をゲートします。LangChain ミドルウェアを備えたフェイルオープンの Python シムは開発中で、まだリリースされていません。サポートマトリックスとレシピは docs/sdk-integrations.md、実行可能なスクリプトは examples/sdk/ をご覧ください。

Claude コネクター

デスクトップ／Claude Code（ローカル stdio）：

# Prefer a preinstalled package (no registry auto-install):
npx --no-install @shield-agent/[email protected] serve-mcp --stdio
# Or after npm i -g / local install:
kya serve-mcp --stdio

claude/claude_desktop_config.example.json を Claude Desktop の MCP 設定にコピーするか、Claude Code では .mcp.json を使用してください。npx @anthropic-ai/mcpb pack で Desktop 拡張機能をパッケージ化できます（manifest.json を参照）。そのパッケージは npx -y ではなく、パッケージ化された dist/cli.js を実行します。

Claude.ai／Cowork（ホスト型）： リクエストヘッダー Authorization: Bearer <KYA_API_KEY>（または X-API-Key）を指定して、https://shield-agent.com/mcp にカスタムコネクターを追加してください。まだ Directory には掲載されていません（API キー認証で、OAuth DCR はありません）。

OpenAI (Codex / Responses)

Codex CLI プラグイン（フック）： Codex plugin を参照してください。Codex CLI / IDE（MCP）： openai/codex.config.example.toml を ~/.codex/config.toml にコピーしてください。ローカルの stdio では npx --no-install @shield-agent/[email protected] serve-mcp --stdio を使用します。ホスト型 Codex では、bearer_token_env_var = "KYA_API_KEY" とともに url = "https://shield-agent.com/mcp" を使用します。

Responses API： openai/responses-mcp.example.json（server_url と Authorization: Bearer <KYA_API_KEY>）を参照してください。

ChatGPT Apps（chatgpt.com）： 現時点では未対応です。Developer Mode では OAuth が必要です。それまでは Codex を使用してください。

Gemini CLI

gemini/settings.example.json（stdio）または gemini/settings.hosted.example.json（httpUrl と Bearer）を ~/.gemini/settings.json または .gemini/settings.json にマージしてください。両方を同時に有効にしないでください。

Grok

Grok CLI（ローカル）： kya connect grok は、~/.grok/config.toml に [mcp_servers.shield-kya] テーブルを追加します（serve-mcp --stdio、キー不要のオフラインサンプル評価）。実行中のセッションでは、/mcps 内で r を押して更新してください。

grok.com（ホスト型）： https://shield-agent.com/mcp のカスタムコネクター（grok/README.md を参照）を使用してください。Grok は localhost を拒否します。UI でリクエストヘッダーを設定できる場合は、Bearer マシンキーの使用を推奨します。

その他のホスト

各ホストのディレクトリには、それぞれコピーして貼り付けられる設定例が含まれています。対応するホストでは、kya connect <host> を実行すると同じ内容が書き込まれます。詳しい手順（検証、アンインストール、トラブルシューティング）については、docs/hosts/ を参照してください。

ホスト	セットアップ	設定例
Claude Code	kya connect claude（または kya start）	-（~/.claude.json / .mcp.json をマージ）
Grok CLI	kya connect grok	-（~/.grok/config.toml に [mcp_servers.shield-kya] を追加）
OpenCode	kya connect opencode	opencode/opencode.example.json
Kilo Code	kya connect kilo	kilo/kilo.example.json
Kiro	kya connect kiro	kiro/mcp.example.json
Qwen Code	kya connect qwen	qwen/settings.example.json（および settings.hosted.example.json）
Kimi Code	kya connect kimi	kimi/mcp.example.json
MastraCode	kya connect mastracode	mastracode/mcp.example.json
Amp	kya connect amp	amp/settings.example.json
GitHub Copilot CLI	kya connect copilot	copilot/mcp-config.example.json
Cline	npm install -g @shield-agent/kya@latest を実行し、llms-install.md の手順に従う	cline/cline_mcp_settings.example.json
Droid	droid mcp add（スキーマ未検証）	droid/mcp.example.json
Pi · OMP · Devin · Hermes · Qoder · Maki · Muse · Antigravity	kya wrap --offline -- <cmd>	docs/hosts/

Cursor プラグイン

このパッケージには .cursor-plugin/plugin.json、mcp.json、および wrap スキルが含まれています。公開リポジトリの掲載先：https://github.com/The-Pixel-Boys/shield-kya

ORR（レポート専用）

npx @shield-agent/kya orr run --path . --out ./orr-report --skip-optional-producers
npx @shield-agent/kya orr run --path . --out ./orr-report --scorecard ./scorecard.json --producer openssf.scorecard
npx @shield-agent/kya orr run --path . --out ./orr-report --producer harness.agentshield --agentshield-json ./agentshield-report.json

ORR は、エージェントのセットアップが安全に実行できるかどうかを確認します。レポート用のボードにすぎません。スキャナー、--scorecard、harness.agentshield は根拠となる情報です。これらが重大な副作用を ALLOW することはないため、2つ目のポリシーゲートではありません。AgentShield は任意で、読み取り専用です。--fix、MiniClaw、ランタイムフックはありません。このパッケージは ecc-agentshield に依存しません。--producer harness.agentshield を渡し、--agentshield-json も agentshield バイナリもない場合、ORR はカバレッジの不足を記録し、終了コード 0 で終了します。明示的な --producer は常に実行を試みます。--skip-optional-producers は、指定されていないプロデューサーのみをスキップします。

Certify（継続的な信頼性チェック）

kya certify は、オープンな Agent Trust Baseline カタログ（catalog/agent-trust-baseline-v0.json：データとプライバシー、セキュリティ、安全性、信頼性、説明責任、社会に関する31の要件）を、ローカルの証拠（グローバルレコード、ORRの出力、接続済みのホスト、サンドボックスのインベントリ、レシート、ショーバック、記録済みのアテステーション）と照合して評価します。ギャップレポートを .kya/certify/ に出力します（JSON＋Markdown＋HTML）。ギャップの一覧が作業計画になります。レシートレポートには同じ状態がリアルタイムで表示されます。Certify パネルは描画のたびに再計算されるため（イベントの受信に応じて kya start のライブレポートが更新されます）、さらに、要件の一覧をすべて表示する専用の Certify タブもあります。ギャップレポート一式と署名済みの証拠バンドルを作成するには、kya certify を実行してください。

npx @shield-agent/kya certify                  # gap report; exit 1 when gaps exist (CI-friendly)
npx @shield-agent/kya certify --open           # open the HTML report
npx @shield-agent/kya certify --fail-on never  # report only, always exit 0
npx @shield-agent/kya certify --attest SOC-01 --text "Acceptable-use policy: https://example.com/aup"
npx @shield-agent/kya certify --sign           # also emit a signed evidence-bundle.json

Certify は証拠の評価のみを行います。何かを ALLOW、DENY したり、ブロックしたりすることはありません。唯一の PEP（ポリシー実施ポイント：呼び出しをブロックできるコンポーネント）は、引き続き Shield KYA です。レコードに基づく機械的なチェックは、空のレコードでは決して合格しません（insufficient_evidence を報告します）。機械で確認できない項目は、.kya/attestations.json に記録される明示的なローカルアテステーション（--attest）で補います。これらは未検証のオペレーターによる申告であり、その旨が明示されます。

--sign は evidence-bundle.json を出力します。これは正規化されたJSONで、ローカルで生成されたキー（~/.kya/keys/evidence-ed25519.json、モード0600、初回使用時に自動作成）によって ed25519 署名（公開鍵署名）されます。--sign を実行するたびに、署名鍵のフィンガープリントが表示されます。鍵が新たに作成された場合、鍵の継続性はここから始まることが CLI によって通知されます（以前のバンドルは旧公開鍵でのみ検証可能です）。自己署名の開発者鍵が証明するのは、バンドルの完全性と鍵の継続性であり、身元ではありません。--sign で作成したバンドルはオフラインで検証できます。公開検証エンドポイント（POST /api/v1/kya/evidence/verify）とバッジでは、グレーの self-signed バッジが表示されます。アクティブなホスト型ワークスペースの鍵で署名されたバンドルのみが、緑色の Shield Verified バッジを取得します。これにより、バッジがホスト型アカウントに紐づきます。ただし、会社やエージェントの法的な身元を証明するものではありません。バンドル形式はオープンで、docs/certify.md に記載されています。埋め込みの公開鍵を使えば、誰でもオフラインでバンドルを検証できます。

kya certify はローカルで無料で実行でき、オフラインで動作します。アカウントは不要で、ネットワーク呼び出しもライセンスチェックもありません（使用状況の統計を送信することはありません）。カタログは MIT ライセンスで、プルリクエストを歓迎します。EU AI Act との対応表（ベースライン要件と第9～15条、第26条、第72条の対応）は、docs/certify-eu-ai-act.md と src/certify/eu-ai-act-map.json に含まれています。

トレースのインポート（LangSmith、Langfuse、Phoenix、OTel、AGT、ADR Sensor、OpenShell）

既存のモニタリングデータをレコードに取り込み、レシートと Certify で参照できるようにします。

kya import --from langsmith ./runs.json
kya import --from langfuse ./observations.jsonl
kya import --from otel ./otraces.json
kya import --from agt   # Microsoft Agent Governance Toolkit audit log
kya import --from adr-sensor ./adr-sensor-events.jsonl
kya import --from openshell ./openshell-events.jsonl

AGT インポーターは AGT のハッシュチェーン（ログ行間のチェックサムリンク）を検証し、改ざんされたログには chainVerified=false のフラグを付け、再インポート時に行が重複することはありません。詳しくは docs/import-agt.md をご覧ください。ADR Sensor のイベントは、1つの AgentEvent から1つ以上の KYA イベントにマッピングされ、再インポート時には安定した uuid によって重複が除去されます。詳しくは docs/import-adr-sensor.md をご覧ください。OpenShell OCSF ログは、1行のログから1つの KYA イベントにマッピングされ、再インポート時には安定した uid によって重複が除去されます。詳しくは docs/import-openshell.md をご覧ください。AGT のハッシュチェーンは鍵なし（秘密鍵を持たない）のため、「検証済み」とは内部的に整合していることを意味し、真正性を意味するものではありません。ホスト型コンソールでも同じ形式を受け付けます（docs/import-agt-hosted.md）。

インポートされたデータは監視モードのイベントとして取り込まれます（host: import、reasonCode: IMPORTED、エラーになった実行は DENY/IMPORTED_ERROR）。ソースに含まれる場合は、レイテンシーとトークン数もマッピングされます。50MBを超えるファイルは拒否されます。破損したレコードはスキップされますが、インポートが中断されることはありません。インポートが行われると、レポート（kya start / kya receipt）に、形式ごとの件数、エラー件数、直近でインポートされたイベントを示す Import カードが表示されます。

調査（検出結果と修正概要）

kya investigate は、LLM を呼び出さずに、記録に対して固定のローカル検出器を実行します。要約内の PII 漏えい、DENY の急増、承認の再試行ループ、繰り返される重大インシデントにつながる試行、保留中の未知のツール、処理の遅いツールを検出します。検出結果はインシデントごとにまとめられます。各インシデントでは、Claude Code、Cursor、Codex に貼り付けて使える形式の Markdown 修正概要が生成されます。実行のたびに簡潔な概要が ~/.kya/investigate-last.json にも保存され、レポートには重大度別の検出結果（検出器 ID を含む）と、最上位の修正概要を示す 調査 カードとして表示されます。

kya investigate           # summary: counts by severity + top incidents
kya investigate --json    # findings + incidents + briefs, machine-readable

エンドポイントの検出

kya discover は、現在のワークステーション上にある AI エージェント、IDE 拡張機能、デスクトップアプリ、モデルランタイム、MCP サーバーを一覧表示します。スキャナーはパスと設定ファイルのみを検査し、検出したバイナリを実行することも、ランタイムのポートに接続することもありません。スナップショットは ~/.kya/discovery/<iso-ts>.json に保存され、latest.json にもコピーされます。ライブレポートには、合計数、承認済み／確認が必要な数、上位カテゴリを示す 検出 カードが表示されます。

kya discover                              # scan, save snapshot, print summary
kya discover --json                       # print snapshot JSON to stdout
kya discover --diff ~/.kya/discovery/latest.json  # compare current scan to saved snapshot
kya discover --push                       # scan and push to hosted console

プッシュには KYA_BASE_URL と KYA_API_KEY が必要です。

export KYA_BASE_URL=https://shield-agent.com
export KYA_API_KEY=your-token
kya discover --push

ホームディレクトリのプレフィックスは、証拠パスから削除され（~ に置換され）ます。スナップショットには、OS から導出した安定した endpointUid、ホスト名のハッシュ、ユーザー名のハッシュが含まれます。生のホスト名やユーザー名がマシンの外部に送信されることはありません。スキャン対象の一覧とプライバシーに関する注意事項は、docs/discovery.md を参照してください。

アラート Webhook（判断のルーティング）

DENY／REQUIRE_APPROVE イベントを Slack、Microsoft Teams、Linear、Jira、または任意の Webhook にルーティングできます。設定は .kya/config.json（プロジェクト）または ~/.kya/config.json（グローバル）に保存されます。

{
  "notify": {
    "webhooks": [
      { "url": "https://hooks.slack.com/services/...", "template": "slack", "events": ["DENY", "REQUIRE_APPROVE"] },
      { "url": "https://<env>.environment.api.powerplatform.com:443/powerautomate/...", "template": "teams", "events": ["DENY"] },
      { "url": "https://example.invalid/jira", "template": "jira", "events": ["DENY"] }
    ]
  }
}

すべての Slack メッセージの末尾には、Slack のリアクションや返信は承認ではないことを示す行が付きます。ホステッドプレーンから新しい承認リクエストを Slack に投稿することもできます（コンソールの Approvals > Slack notify）。このメッセージにはコンソールへのリンクのみが含まれ、承認ボタンはありません。

teams テンプレートは、Teams Workflows の Webhook に Adaptive Card を 1 つ送信します（Teams で、チャネル、Workflows、「Send webhook alerts to a channel」の順に選択し、Webhook リンクをコピーします）。カードにはボタンがなく、Teams のリアクションや返信は承認ではないことを示す行で終わります。イベントテキストからは、Teams がリンク、メンション、Markdown に使用する文字が取り除かれます。ワークフロー URL には署名が含まれているため、秘密にしてください。通知ログに保存されるのはホスト名のみです。ホステッドプレーンから新しい承認リクエストを Teams に投稿することもできます（コンソールの Approvals > Teams notify）。

KYA_NOTIFY_WEBHOOK=<url> は、設定不要で使える方法です（汎用ペイロード）。配信は指数バックオフ（250ms／1s／4s ＋ ジッター）、試行ごとのタイムアウト、URL ごとのサーキットブレーカー（失敗が続く宛先への送信を停止）、送信レート制限を適用して再試行されます。ペイロードは、マスキング済みの記録フィールドのみから作成され、シークレットスキャンで何かが検出された場合は、自動的に最小化された内容に切り替わります。短命な hook／wrap の子プロセスからは、デタッチされたヘルパー（kya notify-flush）が Webhook を送信するため、ゲート処理がネットワークの応答を待つことはありません。配信試行はすべて ~/.kya/notify-log.jsonl に追記されます（宛先ホストのみを記録し、完全な URL は記録しません。直近 500 件まで保持します）。レポートの System タブには、宛先ごとの配信成功数／失敗数と直近の試行を示す アラート パネルが表示されます。

任意のサンドボックスラッパー（Firecracker、OpenShell）

ゲートの横に配置し、MCP の内部には組み込みません。オプトインのみです：

KYA_SANDBOX=mock kya sandbox spawn
KYA_SANDBOX=mock kya sandbox exec --sandbox-id <id> --cmd "true"
KYA_SANDBOX=mock kya sandbox kill --sandbox-id <id>

org.sample.sandbox.exec に --sandbox-id を指定しない場合は、MISSING_SANDBOX_ID で DENY になります。実際の Firecracker を使用するには、PATH 上に firecracker と jailer が必要で、カーネルと rootfs の環境変数（KYA_SANDBOX_KERNEL、KYA_SANDBOX_ROOTFS）も必要です。これらのバイナリは同梱していません。KYA_SANDBOX=openshell を設定すると、openshell CLI を通じて NVIDIA OpenShell を実行します。PATH 上に openshell と docker または podman が必要です。KYA は起動ごとに OpenShell ポリシーを生成し、CLI の最低バージョンを固定し、常に OPENSHELL_TELEMETRY_ENABLED=false を設定します。バックエンドの詳細はdocs/sandbox.mdを参照してください。serve-mcp が引き続き公開するのは evaluate／ingest／request_approval のみです。

コストのショーバック（観測のみ）

kya orr run --usage ./usage.json（または .kya/usage.json）を実行すると、エージェントおよび実行ごとのトークン数と推定 USD を示すショーバックセクションが追加されます。サブエージェントは parentRunId の下にネストされます。このセクションは請求用メーターでも、ポリシーゲートでもありません。セッションとともに使用状況を取り込むと、ホスト型メトリクスにも同じ集計結果が表示されます。ホスト報告のトークン数を含むレコード内のイベント（usage オブジェクトを含むフックペイロード、インポートされたトレース）は、イベントごとの静的な推定値より優先して使用されます。また、レポートには実際の使用状況があったウィンドウ内イベント数が記載されます。

エンタープライズ（別ティア）

上記の初日から利用できる npx の手順では、ピン留め、プライベートレジストリ、マルチテナント密度、ORR ボードの運用、サポートは必要ありません。

開発

pnpm install
pnpm test
pnpm build

ドキュメント

• インストールハブ
• KYA の仕組み
• ホストごとのレシピ（23 ホスト）
• 主要 20 種の MCP サーバー対応マトリックス（分類体系＋ゲートのレシピ）
• OTLP メトリクス（OSS＋ホスト型）
• 匿名の使用状況統計（オプトイン）：送信内容、制御方法、保持期間
• OWASP MCP ガバナンスマップ
• Claude Code プラグイン · Copilot CLI プラグイン · Codex プラグイン · Gemini CLI 拡張機能
• AGT 監査ログのインポート（CLI） · ホスト型
• kya certify - Agent Trust Baseline のギャップレポート
• Agent Trust Baseline の EU AI Act 対応表
• サンドボックスのバックエンド（mock／firecracker／openshell）
• お使いのオブザーバビリティスタックと連携
• SDK とフレームワークの統合（プロセス内シム）
• ホスト型オペレーターの SSO／SCIM（OSS CLI には含まれません）
• オープンソース版とホスト型の違い
• このリポジトリの LIMITATIONS.md も参照してください

匿名の使用状況統計（オプトイン、デフォルトではオフ）

ターミナルで初めて kya start、kya init、または kya connect を実行すると、KYA は匿名の使用状況統計の共有について一度だけ確認します（[y/N]、デフォルトは No）。明示的に y または yes を選択した場合にのみ有効になります。CI、非対話型実行、--json の指定時、または DO_NOT_TRACK=1／KYA_TELEMETRY=0 の設定時には、何も送信されません。kya hook 自体はネットワークにアクセスしません。オプトインした場合は、1 日に最大 1 回、デタッチされたヘルパーを起動して ping を 1 回送信するため、フックのみのインストールもアクティブとしてカウントされます。

kya telemetry show        # the exact payload, field by field
kya telemetry status      # on / off / not asked, and what overrides it
kya telemetry off --purge # turn off and erase what the server holds for this install

詳細、ペイロード、保持期間、エンドポイントのセルフホスト方法については、docs/telemetry.mdを参照してください。

OTLP（任意）

オプトイン方式です。デフォルトでは無効です。

OSS CLI： KYA_OTLP_ENDPOINT（または OTEL_EXPORTER_OTLP_ENDPOINT）を設定すると、タグ verdict と host のみを付与して、評価のレイテンシー（kya.client.evaluate.latency）を簡易的にエクスポートします。ツールの引数や API キーは含まれません。

Decision span export： KYA_OTLP_EXPORT_ENDPOINT（または .kya/config.json の "otlpExport": { "endpoint": ... }）を設定すると、すべての判定を OTLP/JSON GenAI スパン（gen_ai.tool.name、kya.verdict、kya.reason_code、既知の場合はトークン属性）として、任意の OTLP/HTTP バックエンドに出力します。長時間稼働するプロセス（MCP ゲート、ゲートウェイ）は、すべての判定をエクスポートします。Hook/wrap の起動プロセスでは、切り離された notify-flush ヘルパーを介して DENY / REQUIRE_APPROVE をエクスポートします。平文 HTTP は "insecure": true の場合を除き、ループバック接続でのみ使用できます。フラッシュ結果は ~/.kya/otel-stats.json（エンドポイントホストのラベル、送信／失敗したスパン数、最終エクスポート時刻）に収集され、レポートの System タブに OTel export パネルとして表示されます。

ホステッドプレーン： KYA_OTLP_ENABLED=true の場合、より詳細な Micrometer のゲージとタイマーを使用できます。

環境変数の全一覧、Grafana/Datadog に関する注意事項、禁止リスト、Collector のサンプルについては、docs/otlp.md をご覧ください。