feat(mcp): add scoped bounded diagnostics with explicit probe permission

docs/cli-reference.md

@@ -907,6 +907,24 @@ executable and bounded home/state DB candidates, unsupported DB schemas, and
 permission or unknown failures as distinct codes. It does not connect to an
 inbox, write a queue, scan arbitrary directories, or alter agent/SSH settings.
 
+Unreleased v1.4.0 candidate (#358): `doctor --agent NAME` restricts checks and declared agent capabilities to the selected registered agent, including execution over SSH. It also skips the shared installed-skill inventory. `doctor --agent codex --selected-home-only --codex-home /absolute/home` checks only the selected Codex home and skips the inventory of other homes. These options do not enable reverse-route checks. Without them, existing all-agent and bounded multi-home diagnostics keep their behavior.
+
+The candidate MCP wrapper supports only the following checks and effects:
+
+| Mode / agent | Checked facts | Process / connection effects |
+| --- | --- | --- |
+| Metadata | Policy and adapter declarations | None |
+| Active Claude | Registry records, process identity metadata and filesystem inbox presence | No inbox connection |
+| Active Codex | Executable presence, selected-home read-only SQLite queries and bounded writer scan | No native Codex execution or version query |
+| Active Antigravity | Registered bridge metadata | No bridge or native RPC |
+| Active SSH | Configured forward route, only after explicit probe permission | SSH configuration may execute commands; no reverse probe or automatic connection back to a return host |
+
+Representative allowlisted codes include `sessions_dir_missing`, `inbox_present`, `codex_executable_missing`, `state_db_readable`, `unsaved_writer_check_unavailable` and `adapter_failed`. Results are limited to permitted agents and at most 32 checks per agent; these codes describe only the bounded scope above.
+
+`ok` describes collection and format completeness, not availability. A complete `missing_home` result can have `ok=true`; read each agent's status separately. `diagnosticEvidence` is `point_in_time_only` for active results and `not_collected` in metadata mode. `readiness` remains `not_checked` because no per-target readiness is tested. A passing `state_db_readable` check means only that the read-only database query succeeded; it is not an effective-storage attestation or a return-route guarantee.
+
+The stages `tcpAccept`, `tls` and `peerAuthentication` remain `not_checked`. Here `peerAuthentication` refers to paired-device authentication, separate from forward SSH authentication. `sshFailure` reports only a sanitized forward SSH failure category, such as `authentication_failed` or `host_key_failed`. No TCP, TLS, paired-device or return-host probe is added.
+
 Reverse SSH is checked only with `--check-return-route`. The destination runs a
 fixed `ssh ... true` probe with prompts, password authentication, host-key
 enrollment, and config mutation disabled. Forward SSH success is never reused as

docs/i18n-manifest.json

@@ -15,13 +15,13 @@
     "docs/ai-assistant-guide.md": "9624ec96b92fb688fae3be3c94cb3564c77985091be451fbf1f056a1af9b9d9c",
     "docs/antigravity.md": "f2b5122a0ce6e6fb5bd4d8ed50ce2c8bd2dc9c98ec8ce328405cf7c2cd24229d",
     "docs/architecture/agent-transports.md": "01a4e3942e87acb476595859f2e37f9653ea1e3bc19ebc68dced1adf20a6966f",
-    "docs/cli-reference.md": "1d7b7108923e2360df73a9a081b92e19c63e2318c8df3dff5b317a55748434ea",
+    "docs/cli-reference.md": "c63c044b4f52300394427782c5aecc47b533ca3ef6998d4303c5d057dbbf94c8",
     "docs/compatibility-v1.md": "7e551aad37a369faff7e370728376763efb54c2c9e9cfd8556a0c19aabc3d103",
     "docs/contracts/handoff-v1.md": "46a953010c49214bd8f969412f26713384fbe09a0ba78ebf0fef75da40d0d889",
     "docs/diagnostics.md": "0949e53612eeab2cd7c7bbda498e14d71e9cb1b1189aa7722030cb8702cd8481",
     "docs/download-metrics.md": "a537300d3fe2b60273b6f4bd84e0ae0944364fda3881d7fb7e32ce665dc2c724",
     "docs/handoff-runtime.md": "a236e48392c91eca0f7c3734a6008a991955ae66d16fd71f97691aac5bf0091f",
-    "docs/mcp.md": "8ecbdd8eeda984f5e039b5b22c56782b3c7927b2bdfc47faa9df95e5314094b5",
+    "docs/mcp.md": "af00a34033ac0e953c2e0b328567ca98f20c91541fe4c4f15c426d08142f477f",
     "docs/multi-home-list.md": "f8d8e3adf727e4842ea7c4d45e8f6523b11d0513bf2509d4d1204645875e6489",
     "docs/paired-devices.md": "1c6cf45187fdbac5a21e43968bc0cc39aee05af19904b4d176f1dd2a70065303",
     "docs/relay-auth.md": "e6da5291ce6a9da31e79e66ceeff7e9fef7e95046359acbf04d708c96ffab62f",

docs/ja/cli-reference.md

@@ -852,6 +852,24 @@ Codex メッセージは、測定された Codex サーバーの制限ではな
 不明な障害を個別のコードとして報告します。受信トレイへの接続、キューへの書き込み、
 任意のディレクトリのスキャン、エージェント/SSH 設定の変更は行いません。
 
+未リリースの v1.4.0 候補 (#358): `doctor --agent NAME` は SSH 経由も含め、チェックと宣言されたエージェント機能を選択した登録済みエージェントに限定し、共通のインストール済みスキル一覧の検査も省略します。`doctor --agent codex --selected-home-only --codex-home /absolute/home` は選択した Codex ホームのみを検査し、他のホームの一覧確認を省略します。これらのオプションは逆方向経路のチェックを有効にしません。省略すると、既存の全エージェントおよび制限付き複数ホーム診断の動作を維持します。
+
+候補版 MCP ラッパーが対応する検査と実行上の影響は、次の範囲に限られます。
+
+| モード / エージェント | 確認する事実 | プロセス / 接続への影響 |
+| --- | --- | --- |
+| メタデータ | ポリシーとアダプターの宣言 | なし |
+| 能動 Claude | 登録記録、プロセス識別メタデータ、ファイルシステム上の受信箱の存在 | 受信箱には接続しない |
+| 能動 Codex | 実行ファイルの存在、選択したホームの読み取り専用 SQLite クエリ、制限付き writer 走査 | ネイティブ Codex の実行やバージョン照会はしない |
+| 能動 Antigravity | 登録されたブリッジのメタデータ | ブリッジやネイティブへの RPC はしない |
+| 能動 SSH | 明示的なプローブ権限を得た後、設定済みの順方向経路のみ | SSH 設定がコマンドを実行する場合がある。逆方向プローブや返信先ホストへの自動接続はしない |
+
+許可されたコードの例は `sessions_dir_missing`、`inbox_present`、`codex_executable_missing`、`state_db_readable`、`unsaved_writer_check_unavailable`、`adapter_failed` です。結果は許可されたエージェントと、エージェントごとに最大 32 件のチェックに限られ、これらのコードが示すのは上記の限定範囲のみです。
+
+`ok` は可用性ではなく、収集と形式の完全性を示します。完全な `missing_home` 結果でも `ok=true` になり得るため、各エージェントの状態は別途確認してください。`diagnosticEvidence` は能動結果では `point_in_time_only`、メタデータモードでは `not_collected` です。個別の対象の準備状態は検査しないため、`readiness` は `not_checked` のままです。`state_db_readable` の合格は読み取り専用 DB クエリの成功だけを意味し、有効なストレージの証明や返信経路の保証ではありません。
+
+`tcpAccept`、`tls`、`peerAuthentication` の段階は `not_checked` のままです。ここでの `peerAuthentication` はペアリングされたデバイスの認証を指し、順方向 SSH 認証とは別です。`sshFailure` は `authentication_failed` や `host_key_failed` など、サニタイズされた順方向 SSH 失敗の分類だけを報告します。TCP、TLS、ペアリングされたデバイス、返信先ホストへのプローブは追加しません。
+
 リバース SSH は `--check-return-route` を指定した場合にのみチェックされます。送信先は、
 プロンプト、パスワード認証、ホストキー登録、および設定変更を無効にした状態で、
 固定の `ssh ... true` プローブを実行します。フォワード SSH の成功が、リバースパスが機能する

docs/ja/mcp.md

@@ -43,6 +43,32 @@ Python 3.10 以降でインストールします: `pipx install 'session-peer[mc
 
 既存の dry-run 検査はローカル・バージョン確認のプロセスや SSH 接続を開始する場合があり、SSH 設定自体がコマンドを実行する場合もあります。このため、このツールは `readOnlyHint=false` と `openWorldHint=true` を使用します。ホストの承認はポリシーの権限とは別です。合格は検査時点の結果であり、経路の予約、有効なストレージの証明、承認、後の送信の保証、消費、ACK を意味しません。
 
+## 未リリースの v1.4.0 候補: 制限付き診断 (#358)
+
+`diagnose_destination(destination="local", agent=null, active_probe=false)` には、`schemaVersion` 2 ポリシーで明示的な `diagnostics` 権限が必要です。既定モードはポリシーのメタデータと宣言されたエージェント機能のみを返し、CLI や検出プロセスの起動、ネットワーク要求は行いません。送信先 ID には送信先検出と同じ、表示可能文字と UTF-8 128 バイトの制限が適用されます。バージョン 1 と既定ポリシーは診断権限を付与しません。 既定モードの `declaredCapabilities` はアダプターの宣言に基づくブール値であり、実際の配信や準備状態を証明しません。
+
+`active_probe=true` には、さらに `diagnostics_probe` が必要です。メタデータモードは全プラットフォームで利用できます。能動モードは現在 macOS と Linux のみをサポートし、Windows では CLI プロセスの起動やネットワーク要求を行わず、固定理由 `diagnostics_platform_unsupported` を返します。チェックは設定された送信先、固定された Codex ホームと許可されたエージェントのみを使用します。エージェントごとの doctor 呼び出しは最大 3 エージェントを検査し、20 秒の実行予算を共有した後にプロセスを終了処理します。厳密な経過時間の上限やリモートプロセス終了の保証ではありません。子プロセスの stdout と stderr はそれぞれ 64 KiB に制限されます。Codex のチェックは選択したホームのみを調べます。逆方向経路のプローブ、メッセージ送信、ネイティブモデルの起動、自動再試行は行いません。能動チェックは CLI プロセスや SSH 接続を開始でき、運用者の SSH 設定自体がコマンドを実行する場合もあります。ホストの承認はポリシー権限とは別です。選択的な能動チェックが運用者の SSH 設定を実行できるため、統合ツールは `readOnlyHint=false` と `idempotentHint=false` を使用します。
+
+応答は許可された状態値と診断コードを公開し、生のエラー、ホスト名、ホームパス、認証情報、セッション内容、不明な応答フィールドを除外します。メタデータモードは準備状態を検証しません。能動結果も検査時点の状態であり、消費や ACK の証拠、または送信権限ではありません。テキストと構造化ツール結果の合計は 64 KiB に制限されます。
+
+状態・チェックのフィールドが欠落または不正な場合、一部のチェックが不完全な場合、チェック一覧が切り詰められた場合は、正常とはせず不明・不完全（`diagnostic_incomplete`）として報告します。通信段階 `tcpAccept`、`tls`、`peerAuthentication` はすべて `not_checked` のままで、診断では個別に検証しません。
+
+候補版 MCP ラッパーが対応する検査と実行上の影響は、次の範囲に限られます。
+
+| モード / エージェント | 確認する事実 | プロセス / 接続への影響 |
+| --- | --- | --- |
+| メタデータ | ポリシーとアダプターの宣言 | なし |
+| 能動 Claude | 登録記録、プロセス識別メタデータ、ファイルシステム上の受信箱の存在 | 受信箱には接続しない |
+| 能動 Codex | 実行ファイルの存在、選択したホームの読み取り専用 SQLite クエリ、制限付き writer 走査 | ネイティブ Codex の実行やバージョン照会はしない |
+| 能動 Antigravity | 登録されたブリッジのメタデータ | ブリッジやネイティブへの RPC はしない |
+| 能動 SSH | 明示的なプローブ権限を得た後、設定済みの順方向経路のみ | SSH 設定がコマンドを実行する場合がある。逆方向プローブや返信先ホストへの自動接続はしない |
+
+許可されたコードの例は `sessions_dir_missing`、`inbox_present`、`codex_executable_missing`、`state_db_readable`、`unsaved_writer_check_unavailable`、`adapter_failed` です。結果は許可されたエージェントと、エージェントごとに最大 32 件のチェックに限られ、これらのコードが示すのは上記の限定範囲のみです。
+
+`ok` は可用性ではなく、収集と形式の完全性を示します。完全な `missing_home` 結果でも `ok=true` になり得るため、各エージェントの状態は別途確認してください。`diagnosticEvidence` は能動結果では `point_in_time_only`、メタデータモードでは `not_collected` です。個別の対象の準備状態は検査しないため、`readiness` は `not_checked` のままです。`state_db_readable` の合格は読み取り専用 DB クエリの成功だけを意味し、有効なストレージの証明や返信経路の保証ではありません。
+
+`tcpAccept`、`tls`、`peerAuthentication` の段階は `not_checked` のままです。ここでの `peerAuthentication` はペアリングされたデバイスの認証を指し、順方向 SSH 認証とは別です。`sshFailure` は `authentication_failed` や `host_key_failed` など、サニタイズされた順方向 SSH 失敗の分類だけを報告します。TCP、TLS、ペアリングされたデバイス、返信先ホストへのプローブは追加しません。
+
 ## ツールとパーミッション
 
 - `list_sessions(destination="local", agent=null, include_inactive=false)` は CLI の構造化された一覧を返します。Agent は `claude` または `codex` です。省略した場合は許可されたエージェントを一覧表示します。

docs/ko/cli-reference.md

@@ -849,6 +849,24 @@ SSH 실패나 시간 초과가 발생해도 성공·거부 및 네이티브 제
 연결하거나, 큐에 쓰거나, 임의의 디렉터리를 검색하거나, 에이전트/SSH 설정을 변경하지
 않습니다.
 
+미출시 v1.4.0 후보 (#358): `doctor --agent NAME`은 SSH 경유 실행에서도 검사와 선언된 에이전트 기능을 선택한 등록 에이전트로 제한하며, 공통 설치 스킬 목록 검사도 건너뜁니다. `doctor --agent codex --selected-home-only --codex-home /absolute/home`은 선택한 Codex 홈만 검사하고 다른 홈 목록은 확인하지 않습니다. 이 옵션은 역방향 경로 검사를 활성화하지 않습니다. 옵션을 생략하면 기존의 전체 에이전트 및 제한된 다중 홈 진단 동작이 유지됩니다.
+
+후보 MCP 래퍼가 지원하는 검사와 실행 효과는 다음으로 제한됩니다.
+
+| 모드 / 에이전트 | 확인하는 사실 | 프로세스 / 연결 효과 |
+| --- | --- | --- |
+| 메타데이터 | 정책과 어댑터 선언 | 없음 |
+| 능동 Claude | 등록 기록, 프로세스 식별 메타데이터와 파일시스템의 수신함 존재 여부 | 수신함에 연결하지 않음 |
+| 능동 Codex | 실행 파일 존재 여부, 선택한 홈의 읽기 전용 SQLite 조회와 제한된 writer 검색 | 네이티브 Codex 실행이나 버전 조회 없음 |
+| 능동 Antigravity | 등록된 브리지 메타데이터 | 브리지 또는 네이티브 RPC 없음 |
+| 능동 SSH | 명시적인 검사 권한을 받은 뒤 설정된 정방향 경로만 확인 | SSH 설정이 명령을 실행할 수 있음. 역방향 검사나 회신 호스트로의 자동 연결 없음 |
+
+허용된 코드의 예로는 `sessions_dir_missing`, `inbox_present`, `codex_executable_missing`, `state_db_readable`, `unsaved_writer_check_unavailable`, `adapter_failed`가 있습니다. 결과는 허용된 에이전트와 에이전트별 최대 32개 검사로 제한되며, 이 코드는 위의 제한된 범위만 설명합니다.
+
+`ok`는 가용성이 아니라 수집과 형식의 완전성을 나타냅니다. 완전한 `missing_home` 결과도 `ok=true`일 수 있으므로 에이전트별 상태를 따로 확인하십시오. `diagnosticEvidence`는 능동 결과에서 `point_in_time_only`, 메타데이터 모드에서 `not_collected`입니다. 특정 대상의 준비 상태를 검사하지 않으므로 `readiness`는 `not_checked`로 유지됩니다. `state_db_readable` 검사의 통과는 읽기 전용 DB 조회가 성공했다는 뜻일 뿐, 유효 저장소의 증명이나 회신 경로의 보장이 아닙니다.
+
+`tcpAccept`, `tls`, `peerAuthentication` 단계는 `not_checked`로 유지됩니다. 여기서 `peerAuthentication`은 페어링된 기기의 인증을 뜻하며 정방향 SSH 인증과 별개입니다. `sshFailure`는 `authentication_failed` 또는 `host_key_failed`처럼 정제된 정방향 SSH 실패 범주만 보고합니다. TCP, TLS, 페어링된 기기 또는 회신 호스트 검사는 추가하지 않습니다.
+
 역방향 SSH는 `--check-return-route`를 지정한 경우에만 검사됩니다. 대상 시스템은
 프롬프트, 비밀번호 인증, 호스트 키 등록 및 구성 변조가 비활성화된 고정 `ssh ... true`
 프로브를 실행합니다. 정방향 SSH의 성공이 역방향 경로가 작동한다는 증거로 절대