# AIOps Claw — Full Documentation

> Control plane for self-built AI agents. Add governance, policy validation, constitutional constraints, snapshots, and full auditability through MCP.

## 日本語

### ヒーロー
- 製品名: AIOps Claw
- 見出し: 自分で作る AI エージェントに、運用ガバナンスを。
- 説明: AIOps Claw は、自分で立ち上げた AI エージェントにポリシー、監査ログ、Constitutional Constraints、スナップショット復元を組み込むための制御プレーンです。Rail が既成エージェントの安全利用を支えるのに対し、Claw は開発者自身のエージェント基盤へガバナンスを持ち込みます。

### Claw の MCP ツール
Claw では、Rail 共通の 6 ツールに加えて、ポリシー登録・実行前評価・ポリシー棚卸し・監査証跡取得の 4 ツールを提供します。以下では、`/tools/list` の形式に合わせて全 10 ツールを 6 要素で詳細化します。

> 補足: Claw では Constitutional Constraints が常に最優先です。`define_policy` や `validate_action` で許可されるように見える操作でも、恒久ブロック対象であれば `check_scope` または `validate_action` で最終的に拒否されます。

#### Rail 共通ツール

##### `declare_task`
**Purpose**
- このツールは、Claw のガバナンス対象セッションに task manifest を作成し、後続の scope check・snapshot・policy 監査の基準を固定します。
- エージェントが「このセッションでどこまで触れてよいか」を先に宣言することで、曖昧な自律実行を抑制します。

**Guidelines**
- 推奨: ガバナンス付きワークフローを開始するとき、最初に呼び出して `session_id` と `allowed_paths` を明示する。
- 推奨: リリース作業、法務文面更新、設定変更など、対象ディレクトリが事前に分かる仕事で使う。
- 非推奨: `/` やリポジトリ全体のような広すぎる `allowed_paths` を安易に指定する。
- 非推奨: 無関係な複数作業を同じ `session_id` に詰め込むこと。監査が読みにくくなります。

**Limitations**
- `session_id` は呼び出し側が一意に生成して渡す必要があり、サーバー側では採番しません。
- このツール自体は実操作を実行せず、後続判定の前提を作るだけです。
- 新しい manifest を同じ `session_id` で上書きすると、以後の判定は新しい scope を基準に行われます。

**Parameters**
- `session_id` — string / 必須 / 呼び出し側が生成するガバナンス対象セッション識別子。
- `description` — string / 必須 / これから行う作業の人間向け要約。
- `allowed_paths` — string[] / 必須 / このセッションで許可するファイルまたはディレクトリのパス接頭辞一覧。

**Response**
- 正常時は `ok` (boolean), `manifest` (object), `trial_remaining` (number) を返します。
- `manifest` には `session_id`, `description`, `allowed_paths`, `created_at`, `created_by`, `type` (`claw-manifest`) が含まれます。
- 異常時は JSON-RPC エラーで返り、代表例は `session_id, description, and allowed_paths are required` です。
- 正常時の例:
  - `{"ok":true,"manifest":{"session_id":"release-123","description":"governed docs release","allowed_paths":["/repo/docs","/repo/legal"],"created_at":"2026-03-31T10:00:00.000Z","created_by":"owner@example.com","type":"claw-manifest"},"trial_remaining":47}`
- 異常時の例:
  - `{"error":{"code":-32602,"message":"session_id, description, and allowed_paths are required"}}`

**Examples**
1. 推奨シナリオ: FAQ と legal copy の更新前に、`/repo/docs` と `/repo/legal` だけを許可してセッションを開始する。
   - 例: `{"session_id":"release-123","description":"governed docs release","allowed_paths":["/repo/docs","/repo/legal"]}`
   - 想定レスポンス: `{"ok":true,"manifest":{...},"trial_remaining":47}`
2. 非推奨シナリオ: `/` を許可して雑にセッションを開始する。
   - 例: `{"session_id":"catch-all","description":"do everything","allowed_paths":["/"]}`
   - 想定レスポンス: 登録自体は成功し得るが、後続の `check_scope` / `validate_action` が安全側に制限し、監査上も不適切な運用として残ります。

##### `check_scope`
**Purpose**
- このツールは、これから行うファイル操作が `allowed_paths` の範囲内か、そして Constitutional Constraints に違反していないかを判定します。
- Claw における最初の実行前ガードとして、許可・拒否・恒久拒否を返します。

**Guidelines**
- 推奨: read / write / delete の前に毎回呼び出すこと。
- 推奨: secrets、production、設定ファイル、法務文書など影響が大きい対象に触る前は必須にする。
- 非推奨: 似たパスが前回 ALLOWED だったことを理由に呼び出しを省略する。
- 非推奨: policy validation のみで十分と判断すること。Claw では scope と constitutional rule の確認も必要です。

**Limitations**
- 判定専用であり、ファイル操作そのものは行いません。
- 先に `declare_task` が呼ばれていないと使えません。
- 返る結果は `ALLOWED`, `BLOCKED`, `CONSTITUTIONAL BLOCK` の 3 種で、Rail のような delete 確認状態は返しません。

**Parameters**
- `session_id` — string / 必須 / 判定対象 manifest が属するセッション識別子。
- `path` — string / 必須 / 検証したい対象パス。
- `action` — string / 必須 / `read`・`write`・`delete` のいずれか。

**Response**
- 正常時は `result`, `reason`, `path`, `action` を含む JSON テキストを返します。
- `result` は `ALLOWED`, `BLOCKED`, `CONSTITUTIONAL BLOCK` のいずれかです。
- 異常時は JSON-RPC エラーで返り、manifest 未作成時は `declare_task must be called first` になります。
- 正常時の例:
  - `{"result":"ALLOWED","reason":"Path is inside allowed_paths.","path":"/repo/docs/faq.md","action":"write"}`
- 範囲外の例:
  - `{"result":"BLOCKED","reason":"Path is outside declared allowed_paths.","path":"/repo/infra/secrets.tfvars","action":"write"}`
- 恒久ブロックの例:
  - `{"result":"CONSTITUTIONAL BLOCK","reason":"Environment files are permanently blocked.","path":"/repo/.env","action":"write"}`

**Examples**
1. 推奨シナリオ: FAQ を更新する前に write 可否を確認する。
   - 例: `{"session_id":"release-123","path":"/repo/docs/faq.md","action":"write"}`
   - 想定レスポンス: `{"result":"ALLOWED","reason":"Path is inside allowed_paths.","path":"/repo/docs/faq.md","action":"write"}`
2. Constitutional Block シナリオ: `.env` を更新しようとする。
   - 例: `{"session_id":"release-123","path":"/repo/.env","action":"write"}`
   - 想定レスポンス: `{"result":"CONSTITUTIONAL BLOCK","reason":"Environment files are permanently blocked.","path":"/repo/.env","action":"write"}`

##### `take_snapshot`
**Purpose**
- このツールは、変更前のファイル内容を R2 に保存し、ロールバック用の復元点を作成します。
- ポリシーで「変更前 snapshot 必須」としている運用を支える基盤ツールです。

**Guidelines**
- 推奨: write 系操作、公開文面更新、設定変更などの直前に使う。
- 推奨: policy 上で snapshot 必須にしている場合は、対象変更ごとに取得する。
- 非推奨: 現在内容を読まずに空文字や不完全な内容で保存する。
- 非推奨: 単なる read-only 確認だけで無差別に snapshot を増やす。

**Limitations**
- 保存されるのは渡された `content` だけであり、サーバーが元ファイルを読みには行きません。
- 1 回の呼び出しで扱える対象は 1 パスです。
- snapshot を取っても、Constitutional Block や policy block を回避する権限にはなりません。

**Parameters**
- `session_id` — string / 必須 / snapshot を所有する active session。
- `path` — string / 必須 / 保護対象のファイルパス。
- `content` — string / 必須 / 変更前に保存したい現在のファイル内容。

**Response**
- 正常時は `ok` (boolean) と snapshot metadata を返します。
- metadata には `snapshot_id`, `session_id`, `path`, `object_key`, `created_at`, `created_by` が含まれます。
- 異常時は JSON-RPC エラーで返り、代表例は `declare_task must be called first` と `path is required` です。
- 正常時の例:
  - `{"ok":true,"snapshot_id":"snap_123","session_id":"release-123","path":"/repo/docs/faq.md","object_key":"claw/release-123/1711879200-repo_docs_faq_md.txt","created_at":"2026-03-31T10:01:00.000Z","created_by":"owner@example.com"}`
- 異常時の例:
  - `{"error":{"code":-32602,"message":"path is required"}}`

**Examples**
1. 推奨シナリオ: FAQ 更新前に現在の内容を保存する。
   - 例: `{"session_id":"release-123","path":"/repo/docs/faq.md","content":"Current FAQ text..."}`
   - 想定レスポンス: `{"ok":true,"snapshot_id":"snap_123",...}`
2. Block ワークフロー: snapshot を取得した後でも `.env` の write は `check_scope` で拒否され得る。
   - 例: `{"session_id":"release-123","path":"/repo/.env","content":"KEY=old"}`
   - 想定レスポンス: snapshot 自体は作成できても、その後の `check_scope` / `validate_action` は恒久制約を優先します。

##### `list_snapshots`
**Purpose**
- このツールは、セッションに紐づいて保存された snapshot metadata を一覧化します。
- どの復元点があるか、どのファイルをいつ保護したかを把握するための API です。

**Guidelines**
- 推奨: `restore_snapshot` の前に、対象 `snapshot_id` を確認したいとき。
- 推奨: 複数ファイルを触ったセッションで、どこまで保護できているか監査したいとき。
- 非推奨: snapshot の本文そのものを読みたい用途で使うこと。内容取得は `restore_snapshot` を使う。
- 非推奨: `session_id` を指定せずに使うこと。

**Limitations**
- 返るのは metadata のみで、ファイル本文は含まれません。
- 指定セッションに属する snapshot だけを列挙します。
- 危険な変更が `check_scope` や `validate_action` で止められた場合、期待した snapshot が存在しないことがあります。

**Parameters**
- `session_id` — string / 必須 / 一覧化したい snapshot 群が属するセッション識別子。

**Response**
- 正常時は `ok` (boolean) と `snapshots` (array) を返します。
- `snapshots[]` の各要素は通常 `snapshot_id`, `session_id`, `path`, `object_key`, `created_at`, `created_by` を含みます。
- 異常時の代表例は `session_id is required` です。
- 正常時の例:
  - `{"ok":true,"snapshots":[{"snapshot_id":"snap_123","session_id":"release-123","path":"/repo/docs/faq.md","object_key":"claw/release-123/...","created_at":"2026-03-31T10:01:00.000Z","created_by":"owner@example.com"}]}`
- 異常時の例:
  - `{"error":{"code":-32602,"message":"session_id is required"}}`

**Examples**
1. 推奨シナリオ: セッション終了前に、保存済み snapshot を棚卸しする。
   - 例: `{"session_id":"release-123"}`
   - 想定レスポンス: `{"ok":true,"snapshots":[...]}`
2. 監査シナリオ: 本番変更の前に required snapshot が揃っているか確認する。
   - 例: `{"session_id":"prod-rollout-7"}`
   - 想定レスポンス: `{"ok":true,"snapshots":[...]}`

##### `restore_snapshot`
**Purpose**
- このツールは、保存済み snapshot metadata と本文を取得し、クライアントがロールバックを実行できるようにします。
- 変更失敗後に「どの内容へ戻すか」を確定する読み出し側 API です。

**Guidelines**
- 推奨: `take_snapshot` 済みのファイルで不具合が起きたときに使う。
- 推奨: `list_snapshots` で対象 `snapshot_id` を確認した後に呼び出す。
- 非推奨: snapshot を取っていない対象に対して推測で `snapshot_id` を入れること。
- 非推奨: このツールだけで自動復旧が完了すると考えること。返るのは復元用 payload です。

**Limitations**
- 元ファイルへ書き戻す処理は行いません。呼び出し側が `content` を使って復元を実行する必要があります。
- snapshot record または R2 オブジェクトが存在しない場合は失敗します。
- policy block や constitutional block を解除する機能はありません。

**Parameters**
- `session_id` — string / 必須 / snapshot が属するセッション識別子。
- `snapshot_id` — string / 必須 / 取得したい snapshot の識別子。

**Response**
- 正常時は `ok` (boolean), `snapshot` (object), `content` (string) を返します。
- `snapshot` には通常 `snapshot_id`, `session_id`, `path`, `object_key`, `created_at`, `created_by` が含まれます。
- 異常時の代表例は `session_id and snapshot_id are required`, `Snapshot not found`, `Snapshot data missing from R2` です。
- 正常時の例:
  - `{"ok":true,"snapshot":{"snapshot_id":"snap_123","session_id":"release-123","path":"/repo/docs/faq.md","object_key":"claw/release-123/...","created_at":"2026-03-31T10:01:00.000Z","created_by":"owner@example.com"},"content":"Current FAQ text..."}`
- 異常時の例:
  - `{"error":{"code":-32602,"message":"Snapshot not found"}}`

**Examples**
1. 推奨シナリオ: 壊れた FAQ を差し戻すため、保存済み snapshot を読む。
   - 例: `{"session_id":"release-123","snapshot_id":"snap_123"}`
   - 想定レスポンス: `{"ok":true,"snapshot":{...},"content":"Current FAQ text..."}`
2. 失敗シナリオ: 存在しない snapshot を復元しようとする。
   - 例: `{"session_id":"release-123","snapshot_id":"snap_missing"}`
   - 想定レスポンス: `{"error":{"code":-32602,"message":"Snapshot not found"}}`

##### `close_session`
**Purpose**
- このツールは、ガバナンス対象セッションを終了し、その session scope での作業を明示的に閉じます。
- 監査ログ上で「いつこの作業を終えたか」を明確にする締め処理です。

**Guidelines**
- 推奨: scope check・policy validation・snapshot・復元判断がすべて終わった時点で呼ぶ。
- 推奨: 人間レビューが終わり、同じ session でこれ以上変更しないと決まったときに使う。
- 非推奨: まだ後続の guarded action が残っている段階で早閉じすること。
- 非推奨: 監査取得や rollback の途中で session を閉じること。

**Limitations**
- manifest を削除してセッションを終了しますが、snapshot・policy・audit history は削除しません。
- `session_id` が無い場合は失敗します。
- session を閉じても、過去の block 判定や監査結果は残ります。

**Parameters**
- `session_id` — string / 必須 / 終了したい manifest session の識別子。

**Response**
- 正常時は `ok` (boolean), `session_id` (string), `closed_at` (string) を返します。
- 異常時の代表例は `session_id is required` です。
- 正常時の例:
  - `{"ok":true,"session_id":"release-123","closed_at":"2026-03-31T10:05:00.000Z"}`
- 異常時の例:
  - `{"error":{"code":-32602,"message":"session_id is required"}}`

**Examples**
1. 推奨シナリオ: ドキュメント更新と監査確認が完了したので、セッションを閉じる。
   - 例: `{"session_id":"release-123"}`
   - 想定レスポンス: `{"ok":true,"session_id":"release-123","closed_at":"2026-03-31T10:05:00.000Z"}`
2. 推奨シナリオ: `validate_action` が BLOCKED を返したため、作業を継続せずに安全に終了する。
   - 例: `{"session_id":"prod-rollout-7"}`
   - 想定レスポンス: `{"ok":true,"session_id":"prod-rollout-7","closed_at":"2026-03-31T10:05:00.000Z"}`

#### Claw 専用ツール

##### `define_policy`
**Purpose**
- このツールは、JSON または YAML のポリシードキュメントを解析・正規化し、後続アクション判定に使う governance policy として登録します。
- エージェントのふるまいを「実行前に明文化されたルール」に変換する入口です。

**Guidelines**
- 推奨: エージェント初回起動時にポリシーを登録し、そのセッションで従うルールを明確にする。
- 推奨: 新しい運用フローや新しい agent_id ごとに、安定した `policy_id` を決めて管理する。
- 非推奨: セッション途中でポリシーを頻繁に再定義すること。監査追跡と判定の一貫性が崩れます。
- 非推奨: 実行中に一時しのぎで曖昧なポリシー文書を投入すること。

**Limitations**
- 先に `declare_task` が必要です。
- `policy` は妥当な JSON または YAML である必要があります。
- 登録後も Constitutional Constraints が優先されるため、危険な領域を許可する policy は実効を持ちません。

**Parameters**
- `session_id` — string / 必須 / 監査対象となる active session。
- `policy_id` — string / 任意 / 保存時に使う安定したポリシー識別子。
- `format` — string / 任意 / `json` または `yaml` のヒント。
- `policy` — string / 必須 / 解析・正規化したい生のポリシードキュメント。

**Response**
- 正常時は `ok` (boolean) と `policy` (object) を返します。
- `policy` には通常 `policy_id`, `name`, `description`, `agent_id`, `session_id`, `created_at`, `created_by` と rule fields が含まれます。
- 異常時の代表例は `declare_task must be called first` と、パース失敗時の 500 系エラーです。
- 正常時の例:
  - `{"ok":true,"policy":{"policy_id":"finance-v1","name":"Finance policy","description":"Require snapshots before writes","agent_id":"finance-agent","session_id":"release-123","created_at":"2026-03-31T10:02:00.000Z","created_by":"owner@example.com"}}`
- 異常時の例:
  - `{"error":{"code":-32602,"message":"declare_task must be called first"}}`

**Examples**
1. 推奨シナリオ: エージェント初回起動時に finance 用 policy を登録する。
   - 例: `{"session_id":"release-123","policy_id":"finance-v1","format":"yaml","policy":"name: Finance policy
agent_id: finance-agent
require_snapshot_for_write: true"}`
   - 想定レスポンス: `{"ok":true,"policy":{...}}`
2. 非推奨シナリオ: セッション途中で別の意図の policy を何度も再定義する。
   - 例: `{"session_id":"release-123","policy":"{bad json"}`
   - 想定レスポンス: パース失敗でエラーとなり、監査にも失敗イベントが残ります。

##### `validate_action`
**Purpose**
- このツールは、提案された action object を登録済み policy に照らして評価し、実行前に `ALLOWED` / `BLOCKED` / `CONSTITUTIONAL BLOCK` を返します。
- Claw の policy governance を実運用に接続する中核ツールです。

**Guidelines**
- 推奨: 全ての state-changing アクションの実行前に呼び出す。ファイル write/delete、外部 API 呼び出し、危険操作の前に必須です。
- 推奨: `risk_level`, `snapshot_taken`, `path`, `reason` など、判定に必要な action 情報を十分に含める。
- 非推奨: 読み取り専用操作に対して乱用すること。policy で明示的に必要な場合を除き、read-only は `check_scope` で十分です。
- 非推奨: 実行後に事後的に呼ぶこと。validate_action は pre-flight 用です。

**Limitations**
- 先に `declare_task` と `define_policy` が必要です。
- このツール自体は action を実行しません。
- policy が許可しても Constitutional Constraints は別レイヤーで優先されます。

**Parameters**
- `session_id` — string / 必須 / 監査ログおよび scope context に使う active session。
- `policy_id` — string / 必須 / 評価対象の登録済み policy 識別子。
- `action` — object / 必須 / `action`, `path`, `target`, `resource`, `risk_level`, `snapshot_taken`, `reason` などを含む提案 action payload。

**Response**
- 正常時は `ok` (boolean), `policy_id` (string), `evaluation` (object) を返します。
- `evaluation` には通常 `result` と `reason` が入り、`result` は `ALLOWED`, `BLOCKED`, `CONSTITUTIONAL BLOCK` のいずれかです。
- 異常時の代表例は `declare_task must be called first`, `Policy not found` です。
- 正常時の例:
  - `{"ok":true,"policy_id":"finance-v1","evaluation":{"result":"ALLOWED","reason":"Action satisfies the active policy."}}`
- ブロック例:
  - `{"ok":true,"policy_id":"finance-v1","evaluation":{"result":"BLOCKED","reason":"This policy requires a snapshot before any write-like action."}}`

**Examples**
1. 推奨シナリオ: write 前に snapshot 済みであることを含めて評価する。
   - 例: `{"session_id":"release-123","policy_id":"finance-v1","action":{"action":"write","path":"/repo/docs/faq.md","risk_level":"medium","snapshot_taken":true,"reason":"Update FAQ"}}`
   - 想定レスポンス: `{"ok":true,"policy_id":"finance-v1","evaluation":{"result":"ALLOWED","reason":"Action satisfies the active policy."}}`
2. 非推奨シナリオ: read-only チェック代わりに乱用する、または snapshot なし write を通そうとする。
   - 例: `{"session_id":"release-123","policy_id":"finance-v1","action":{"action":"write","path":"/repo/docs/faq.md","risk_level":"medium","snapshot_taken":false}}`
   - 想定レスポンス: `{"ok":true,"policy_id":"finance-v1","evaluation":{"result":"BLOCKED","reason":"This policy requires a snapshot before any write-like action."}}`

##### `list_policies`
**Purpose**
- このツールは、登録済み policy の要約一覧を返し、どの governance rule が利用可能かを確認できるようにします。
- policy_id の選択、デバッグ、運用棚卸しに使う discovery API です。

**Guidelines**
- 推奨: ポリシー適用状況の確認・デバッグ時に使う。
- 推奨: 実行前にどの `policy_id` が存在するか確認したいときに使う。
- 非推奨: ポリシー本文全体を取得する用途で使うこと。返るのは summary です。
- 非推奨: 大量取得を前提に過大な `limit` を期待すること。1〜100 に丸められます。

**Limitations**
- 返すのは summary であり、生のポリシードキュメントではありません。
- 結果件数は `limit` の範囲に制限されます。
- セッション不要で使えますが、どのセッションで登録した policy かは summary 情報から解釈する必要があります。

**Parameters**
- `limit` — number / 任意 / 返す件数の上限。既定値 100、実際には 1〜100 に clamp されます。

**Response**
- 正常時は `ok` (boolean) と `policies` (array) を返します。
- `policies[]` の各要素は通常 `policy_id`, `name`, `description`, `agent_id`, `created_at`, `created_by` を含みます。
- 空配列も正常応答です。
- 正常時の例:
  - `{"ok":true,"policies":[{"policy_id":"finance-v1","name":"Finance policy","description":"Require snapshots before writes","agent_id":"finance-agent","created_at":"2026-03-31T10:02:00.000Z","created_by":"owner@example.com"}]}`
- 空の例:
  - `{"ok":true,"policies":[]}`

**Examples**
1. 推奨シナリオ: どの policy_id を使うべきかデバッグ前に確認する。
   - 例: `{"limit":20}`
   - 想定レスポンス: `{"ok":true,"policies":[...]}`
2. 推奨シナリオ: 新規環境でポリシー未登録を確認する。
   - 例: `{"limit":5}`
   - 想定レスポンス: `{"ok":true,"policies":[]}`

##### `audit_log`
**Purpose**
- このツールは、policy check・scope check・snapshot・close など、Claw が記録した監査イベントを新しい順で取得します。
- コンプライアンス証跡、事後検証、障害調査のための監査 API です。

**Guidelines**
- 推奨: セッション終了後の振り返り・コンプライアンス証跡の取得に使う。
- 推奨: どの tool がどの判定を返したか時系列で確認したいときに使う。
- 非推奨: リアルタイム監視の代替として扱うこと。継続監視ダッシュボードではありません。
- 非推奨: 外部システムで記録されなかった操作まで再構成できると期待すること。

**Limitations**
- 返るのは Claw が保存した監査イベントのみです。
- 外部で実行された未記録操作や、Claw を経由しなかった操作は再現できません。
- `session_id` は任意ですが、全体監査では件数が増えるため `limit` の設計が必要です。

**Parameters**
- `session_id` — string / 任意 / 特定セッションに絞り込む場合の識別子。
- `limit` — number / 任意 / 返す監査イベント件数の上限。

**Response**
- 正常時は `ok` (boolean) と `entries` (array) を返します。
- `entries[]` の各要素には通常 `timestamp`, `tool`, `status`, `policy_id`, `detail`, `session_id` などが含まれます。
- 空配列も正常応答です。
- 正常時の例:
  - `{"ok":true,"entries":[{"tool":"validate_action","status":"ALLOWED","session_id":"release-123","detail":{"action":{"action":"write"}}}]}`
- 空の例:
  - `{"ok":true,"entries":[]}`

**Examples**
1. 推奨シナリオ: セッション終了後に、その run で何が起きたかを振り返る。
   - 例: `{"session_id":"release-123","limit":50}`
   - 想定レスポンス: `{"ok":true,"entries":[...]}`
2. 推奨シナリオ: アカウント全体のコンプライアンス証跡を確認する。
   - 例: `{"limit":100}`
   - 想定レスポンス: `{"ok":true,"entries":[...]}`

### Constitutional Constraints
Claw はユーザーの許可があっても解除できない恒久制約を持ちます。ポリシーよりも先に評価され、秘密情報・危険領域・本番破壊操作を常にブロックします。

Always-on guardrails:
- `/etc/passwd`, `/etc/shadow`, `/.ssh`, `/root` などの危険領域を恒久ブロック
- `.env` / secrets / payment 系の自律変更を恒久ブロック
- 本番への破壊的 delete を恒久ブロック
- ポリシー validation と snapshot 要件を重ねて適用

### 導入手順
Rail と同じ認証基盤を使い、メール登録 → API キー取得 → MCP 設定追加の 3 ステップで開始できます。

1. **メール登録**: 下部フォームからメールアドレスを送信します。
2. **API キー取得**: Rail / Claw 共通の API キーを発行します。
3. **MCP 設定に追加**: エージェントの MCP 設定に `claw.aiops.services/mcp` を追加します。

```json
{
  "mcpServers": {
    "aiops-claw": {
      "url": "https://claw.aiops.services/mcp",
      "transport": "http",
      "headers": {
        "X-Rail-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

### 料金
Rail と同じ料金体系です。Free は 50 回まで、AIOps Live の有償プランでは無制限です。

**Free**
- 50 MCP tool calls
- Policy registration
- Snapshots and audit logs

**AIOps Live Paid**
- 無制限の Rail / Claw 利用
- Shared API key
- Production agent governance

### API キー登録
メールアドレスを登録すると、Rail / Claw 共通 API キーを即時発行します。

## English

### Hero
- Product: AIOps Claw
- Headline: Govern your AI agents.
- Description: AIOps Claw is the control plane for self-built AI agents. Add policies, audit logs, Constitutional Constraints, and recoverable snapshots to the agents you develop yourself. Rail protects the use of prebuilt agents; Claw governs the agents you own.

### Claw MCP tools
Claw exposes the 6 shared Rail tools plus 4 governance-specific tools for policy registration, preflight validation, policy discovery, and audit review. The details below follow the same 6-part format already used in `/tools/list`.

> Note: Constitutional Constraints always run before policy logic. Even if a policy appears to allow an action, a permanently blocked path or action is still denied by `check_scope` or `validate_action`.

#### Shared Rail tools

##### `declare_task`
**Purpose**
- This tool creates the task manifest for a governed Claw session and establishes the scope baseline used by later checks, snapshots, and audits.
- It makes the agent declare what it plans to touch before autonomous work begins.

**Guidelines**
- Recommended: Call at the start of every governed workflow with a unique `session_id` and narrowly defined `allowed_paths`.
- Recommended: Use for releases, legal edits, configuration work, and other tasks where target directories are known in advance.
- Not recommended: Declaring overly broad scopes such as `/` or an entire repository without a strong reason.
- Not recommended: Reusing one `session_id` for multiple unrelated jobs because it weakens audit clarity.

**Limitations**
- `session_id` must be generated by the caller; the service does not mint it for you.
- The tool does not execute any file operation. It only creates the scope baseline.
- Re-declaring the same session can overwrite the manifest used by later evaluations.

**Parameters**
- `session_id` — string / required / Caller-generated unique identifier for the governed session.
- `description` — string / required / Human-readable summary of the work the agent is about to do.
- `allowed_paths` — string[] / required / File or directory path prefixes permitted in this session.

**Response**
- On success it returns `ok` (boolean), `manifest` (object), and `trial_remaining` (number).
- `manifest` includes `session_id`, `description`, `allowed_paths`, `created_at`, `created_by`, and `type` (`claw-manifest`).
- On failure it returns a JSON-RPC error, most commonly `session_id, description, and allowed_paths are required`.
- Success example:
  - `{"ok":true,"manifest":{"session_id":"release-123","description":"governed docs release","allowed_paths":["/repo/docs","/repo/legal"],"created_at":"2026-03-31T10:00:00.000Z","created_by":"owner@example.com","type":"claw-manifest"},"trial_remaining":47}`
- Error example:
  - `{"error":{"code":-32602,"message":"session_id, description, and allowed_paths are required"}}`

**Examples**
1. Recommended scenario: Start a governed documentation release limited to `/repo/docs` and `/repo/legal`.
   - Example: `{"session_id":"release-123","description":"governed docs release","allowed_paths":["/repo/docs","/repo/legal"]}`
   - Expected response: `{"ok":true,"manifest":{...},"trial_remaining":47}`
2. Not recommended scenario: Create a catch-all session with `/` as the only allowed path.
   - Example: `{"session_id":"catch-all","description":"do everything","allowed_paths":["/"]}`
   - Expected response: the manifest may register, but later checks and audits will still constrain dangerous work and the scope declaration is operationally poor.

##### `check_scope`
**Purpose**
- This tool decides whether an intended file action is inside the declared scope and outside the constitutional deny list.
- It is the first pre-execution gate for governed file-like actions in Claw.

**Guidelines**
- Recommended: Call before every read, write, or delete action.
- Recommended: Make it mandatory for secrets, production assets, configs, and legal content.
- Not recommended: Skipping it because a similar path was allowed earlier.
- Not recommended: Relying on policy validation alone. Claw still needs scope and constitutional checks.

**Limitations**
- It only returns a decision and never executes the action itself.
- It requires a manifest created by `declare_task`.
- Its result set is `ALLOWED`, `BLOCKED`, or `CONSTITUTIONAL BLOCK`; unlike Rail, this implementation does not return a separate delete-confirmation state.

**Parameters**
- `session_id` — string / required / Session whose manifest should be checked.
- `path` — string / required / Exact target path to validate.
- `action` — string / required / One of `read`, `write`, or `delete`.

**Response**
- On success it returns JSON text containing `result`, `reason`, `path`, and `action`.
- `result` is one of `ALLOWED`, `BLOCKED`, or `CONSTITUTIONAL BLOCK`.
- On failure it returns a JSON-RPC error; if no manifest exists, the error is `declare_task must be called first`.
- Allowed example:
  - `{"result":"ALLOWED","reason":"Path is inside allowed_paths.","path":"/repo/docs/faq.md","action":"write"}`
- Out-of-scope example:
  - `{"result":"BLOCKED","reason":"Path is outside declared allowed_paths.","path":"/repo/infra/secrets.tfvars","action":"write"}`
- Constitutional block example:
  - `{"result":"CONSTITUTIONAL BLOCK","reason":"Environment files are permanently blocked.","path":"/repo/.env","action":"write"}`

**Examples**
1. Recommended scenario: Validate a docs write before editing the FAQ.
   - Example: `{"session_id":"release-123","path":"/repo/docs/faq.md","action":"write"}`
   - Expected response: `{"result":"ALLOWED","reason":"Path is inside allowed_paths.","path":"/repo/docs/faq.md","action":"write"}`
2. Constitutional Block scenario: Attempt to write `.env`.
   - Example: `{"session_id":"release-123","path":"/repo/.env","action":"write"}`
   - Expected response: `{"result":"CONSTITUTIONAL BLOCK","reason":"Environment files are permanently blocked.","path":"/repo/.env","action":"write"}`

##### `take_snapshot`
**Purpose**
- This tool stores the current file contents in R2 before a mutation, creating a rollback point.
- It supports governance rules that require snapshots before risky writes.

**Guidelines**
- Recommended: Use immediately before write-like actions, public content changes, or configuration updates.
- Recommended: Take one snapshot per protected target when policy requires it.
- Not recommended: Sending empty or partial content because the caller failed to read the current file first.
- Not recommended: Creating snapshots for every trivial read-only inspection.

**Limitations**
- It stores only the supplied `content`; it does not fetch the file for you.
- Each call protects one path only.
- A snapshot does not bypass constitutional or policy blocks.

**Parameters**
- `session_id` — string / required / Active session that owns the snapshot.
- `path` — string / required / Path of the file being protected.
- `content` — string / required / Current file contents to preserve before mutation.

**Response**
- On success it returns `ok` (boolean) plus snapshot metadata.
- The metadata includes `snapshot_id`, `session_id`, `path`, `object_key`, `created_at`, and `created_by`.
- Typical failures are `declare_task must be called first` and `path is required`.
- Success example:
  - `{"ok":true,"snapshot_id":"snap_123","session_id":"release-123","path":"/repo/docs/faq.md","object_key":"claw/release-123/1711879200-repo_docs_faq_md.txt","created_at":"2026-03-31T10:01:00.000Z","created_by":"owner@example.com"}`
- Error example:
  - `{"error":{"code":-32602,"message":"path is required"}}`

**Examples**
1. Recommended scenario: Save the current FAQ before editing it.
   - Example: `{"session_id":"release-123","path":"/repo/docs/faq.md","content":"Current FAQ text..."}`
   - Expected response: `{"ok":true,"snapshot_id":"snap_123",...}`
2. Block workflow: Even after snapshotting, a later `.env` write can still be rejected.
   - Example: `{"session_id":"release-123","path":"/repo/.env","content":"KEY=old"}`
   - Expected response: the snapshot may exist, but `check_scope` and `validate_action` still enforce the permanent block.

##### `list_snapshots`
**Purpose**
- This tool lists the snapshot metadata captured for a session.
- It is the discovery step before choosing a rollback point.

**Guidelines**
- Recommended: Use before `restore_snapshot` to confirm the right `snapshot_id`.
- Recommended: Use when several files were touched and you need an inventory of protected states.
- Not recommended: Using it when you need the actual file contents. Use `restore_snapshot` instead.
- Not recommended: Calling it without `session_id`.

**Limitations**
- It returns metadata only, not snapshot body content.
- It only enumerates snapshots belonging to the specified session.
- If a dangerous action was blocked earlier, there may be no corresponding snapshot to list.

**Parameters**
- `session_id` — string / required / Session whose snapshots should be enumerated.

**Response**
- On success it returns `ok` (boolean) and `snapshots` (array).
- Each item usually contains `snapshot_id`, `session_id`, `path`, `object_key`, `created_at`, and `created_by`.
- Typical failure: `session_id is required`.
- Success example:
  - `{"ok":true,"snapshots":[{"snapshot_id":"snap_123","session_id":"release-123","path":"/repo/docs/faq.md","object_key":"claw/release-123/...","created_at":"2026-03-31T10:01:00.000Z","created_by":"owner@example.com"}]}`
- Error example:
  - `{"error":{"code":-32602,"message":"session_id is required"}}`

**Examples**
1. Recommended scenario: Inspect available rollback points before restoring.
   - Example: `{"session_id":"release-123"}`
   - Expected response: `{"ok":true,"snapshots":[...]}`
2. Audit scenario: Confirm all required production snapshots exist for a governed rollout.
   - Example: `{"session_id":"prod-rollout-7"}`
   - Expected response: `{"ok":true,"snapshots":[...]}`

##### `restore_snapshot`
**Purpose**
- This tool retrieves the stored snapshot metadata and file content so a client can perform rollback.
- It is the read side of the recovery workflow.

**Guidelines**
- Recommended: Use after a bad edit when you need the prior version of a protected file.
- Recommended: Use after `list_snapshots` confirms the target `snapshot_id`.
- Not recommended: Guessing snapshot identifiers for files that were never backed up.
- Not recommended: Assuming this tool writes anything back automatically. It only returns the saved payload.

**Limitations**
- It does not restore the original file by itself; the client must write back `content` explicitly.
- It fails if the snapshot record is missing or the R2 object no longer exists.
- It does not override policy or constitutional blocks.

**Parameters**
- `session_id` — string / required / Session that owns the target snapshot.
- `snapshot_id` — string / required / Snapshot identifier to retrieve.

**Response**
- On success it returns `ok` (boolean), `snapshot` (object), and `content` (string).
- `snapshot` usually includes `snapshot_id`, `session_id`, `path`, `object_key`, `created_at`, and `created_by`.
- Typical errors are `session_id and snapshot_id are required`, `Snapshot not found`, and `Snapshot data missing from R2`.
- Success example:
  - `{"ok":true,"snapshot":{"snapshot_id":"snap_123","session_id":"release-123","path":"/repo/docs/faq.md","object_key":"claw/release-123/...","created_at":"2026-03-31T10:01:00.000Z","created_by":"owner@example.com"},"content":"Current FAQ text..."}`
- Error example:
  - `{"error":{"code":-32602,"message":"Snapshot not found"}}`

**Examples**
1. Recommended scenario: Retrieve the saved FAQ content after a broken change.
   - Example: `{"session_id":"release-123","snapshot_id":"snap_123"}`
   - Expected response: `{"ok":true,"snapshot":{...},"content":"Current FAQ text..."}`
2. Failure scenario: Ask for a snapshot that does not exist.
   - Example: `{"session_id":"release-123","snapshot_id":"snap_missing"}`
   - Expected response: `{"error":{"code":-32602,"message":"Snapshot not found"}}`

##### `close_session`
**Purpose**
- This tool closes the governed manifest session when the work is finished.
- It gives the audit trail a clean completion boundary.

**Guidelines**
- Recommended: Call after all scope checks, policy validations, snapshots, and recovery decisions are complete.
- Recommended: Use when a human review is done and the agent should stop operating under that session.
- Not recommended: Closing early while more guarded actions are still pending.
- Not recommended: Closing in the middle of rollback or audit collection.

**Limitations**
- It removes the manifest for that session, but it does not delete snapshots, policies, or audit history.
- It fails when `session_id` is missing.
- Closing a session does not erase or override prior block decisions.

**Parameters**
- `session_id` — string / required / Manifest session identifier to close.

**Response**
- On success it returns `ok` (boolean), `session_id` (string), and `closed_at` (string).
- Typical failure: `session_id is required`.
- Success example:
  - `{"ok":true,"session_id":"release-123","closed_at":"2026-03-31T10:05:00.000Z"}`
- Error example:
  - `{"error":{"code":-32602,"message":"session_id is required"}}`

**Examples**
1. Recommended scenario: Finish the governed docs release and close the session.
   - Example: `{"session_id":"release-123"}`
   - Expected response: `{"ok":true,"session_id":"release-123","closed_at":"2026-03-31T10:05:00.000Z"}`
2. Recommended scenario: Stop after a blocked validation instead of forcing the workflow forward.
   - Example: `{"session_id":"prod-rollout-7"}`
   - Expected response: `{"ok":true,"session_id":"prod-rollout-7","closed_at":"2026-03-31T10:05:00.000Z"}`

#### Claw-specific tools

##### `define_policy`
**Purpose**
- This tool parses and registers a JSON or YAML policy document for future governance decisions.
- It is the entry point that turns informal agent behavior expectations into an explicit, reusable policy.

**Guidelines**
- Recommended: Register a policy when the agent starts for the first time so its operating rules are explicit from the beginning.
- Recommended: Use stable `policy_id` values for durable workflows or agent families.
- Not recommended: Frequently redefining the policy mid-session. That weakens audit clarity and evaluation consistency.
- Not recommended: Injecting vague or temporary policy text just to get past a single blocked action.

**Limitations**
- It requires an active session from `declare_task`.
- The `policy` payload must be valid JSON or YAML.
- Constitutional Constraints still override any policy that attempts to permit dangerous targets.

**Parameters**
- `session_id` — string / required / Active session under which the policy registration should be audited.
- `policy_id` — string / optional / Stable identifier to assign to the stored policy.
- `format` — string / optional / Format hint, either `json` or `yaml`.
- `policy` — string / required / Raw JSON or YAML policy document to parse and normalize.

**Response**
- On success it returns `ok` (boolean) and `policy` (object).
- `policy` usually includes `policy_id`, `name`, `description`, `agent_id`, `session_id`, `created_at`, `created_by`, and normalized rule fields.
- Common failures are `declare_task must be called first` and parse-related server errors for invalid documents.
- Success example:
  - `{"ok":true,"policy":{"policy_id":"finance-v1","name":"Finance policy","description":"Require snapshots before writes","agent_id":"finance-agent","session_id":"release-123","created_at":"2026-03-31T10:02:00.000Z","created_by":"owner@example.com"}}`
- Error example:
  - `{"error":{"code":-32602,"message":"declare_task must be called first"}}`

**Examples**
1. Recommended scenario: Register the governance policy when the finance agent boots for the first time.
   - Example: `{"session_id":"release-123","policy_id":"finance-v1","format":"yaml","policy":"name: Finance policy
agent_id: finance-agent
require_snapshot_for_write: true"}`
   - Expected response: `{"ok":true,"policy":{...}}`
2. Not recommended scenario: Redefine the policy repeatedly in the middle of the same session.
   - Example: `{"session_id":"release-123","policy":"{bad json"}`
   - Expected response: parsing fails and the error is recorded in the audit trail.

##### `validate_action`
**Purpose**
- This tool evaluates a proposed action object against a stored policy before execution.
- It is the core governance gate that converts policy text into an allow-or-block decision.

**Guidelines**
- Recommended: Call it before every state-changing action such as file writes, deletions, external API calls, or other risky autonomous operations.
- Recommended: Include enough action detail to make the policy decision meaningful, such as `path`, `risk_level`, `snapshot_taken`, and `reason`.
- Not recommended: Using it for read-only operations unless policy explicitly requires that extra review.
- Not recommended: Calling it after the action has already happened. It is a pre-flight check.

**Limitations**
- It requires both an active session and a previously stored `policy_id`.
- It never executes the proposed action itself.
- Constitutional Constraints still win even when the stored policy would otherwise allow the action.

**Parameters**
- `session_id` — string / required / Active session used for audit logging and scope context.
- `policy_id` — string / required / Identifier of the stored policy to evaluate against.
- `action` — object / required / Structured proposal such as `action`, `path`, `target`, `resource`, `risk_level`, `snapshot_taken`, and `reason`.

**Response**
- On success it returns `ok` (boolean), `policy_id` (string), and `evaluation` (object).
- `evaluation` usually contains `result` and `reason`, where `result` is `ALLOWED`, `BLOCKED`, or `CONSTITUTIONAL BLOCK`.
- Common failures are `declare_task must be called first` and `Policy not found`.
- Allowed example:
  - `{"ok":true,"policy_id":"finance-v1","evaluation":{"result":"ALLOWED","reason":"Action satisfies the active policy."}}`
- Blocked example:
  - `{"ok":true,"policy_id":"finance-v1","evaluation":{"result":"BLOCKED","reason":"This policy requires a snapshot before any write-like action."}}`

**Examples**
1. Recommended scenario: Validate a write after a snapshot has already been taken.
   - Example: `{"session_id":"release-123","policy_id":"finance-v1","action":{"action":"write","path":"/repo/docs/faq.md","risk_level":"medium","snapshot_taken":true,"reason":"Update FAQ"}}`
   - Expected response: `{"ok":true,"policy_id":"finance-v1","evaluation":{"result":"ALLOWED","reason":"Action satisfies the active policy."}}`
2. Not recommended scenario: Use it as a read-only shortcut or try to push a write without a snapshot.
   - Example: `{"session_id":"release-123","policy_id":"finance-v1","action":{"action":"write","path":"/repo/docs/faq.md","risk_level":"medium","snapshot_taken":false}}`
   - Expected response: `{"ok":true,"policy_id":"finance-v1","evaluation":{"result":"BLOCKED","reason":"This policy requires a snapshot before any write-like action."}}`

##### `list_policies`
**Purpose**
- This tool lists registered policy summaries so the client can discover what governance rules are available.
- It is the discovery and debugging endpoint for policy inventory.

**Guidelines**
- Recommended: Use to confirm policy coverage or debug governance setup.
- Recommended: Use before execution when you need to choose the correct `policy_id`.
- Not recommended: Treating it as a full policy document export. It returns summaries only.
- Not recommended: Expecting unbounded output. `limit` is clamped to 1-100.

**Limitations**
- It returns summaries, not the raw source policy text.
- The response size is limited by `limit`.
- It does not require a session, so session context must be inferred from the returned metadata.

**Parameters**
- `limit` — number / optional / Maximum number of policy summaries to return. Defaults to 100 and is clamped to 1-100.

**Response**
- On success it returns `ok` (boolean) and `policies` (array).
- Each policy summary usually includes `policy_id`, `name`, `description`, `agent_id`, `created_at`, and `created_by`.
- An empty array is still a valid success response.
- Success example:
  - `{"ok":true,"policies":[{"policy_id":"finance-v1","name":"Finance policy","description":"Require snapshots before writes","agent_id":"finance-agent","created_at":"2026-03-31T10:02:00.000Z","created_by":"owner@example.com"}]}`
- Empty example:
  - `{"ok":true,"policies":[]}`

**Examples**
1. Recommended scenario: Check which policies exist before selecting a `policy_id`.
   - Example: `{"limit":20}`
   - Expected response: `{"ok":true,"policies":[...]}`
2. Recommended scenario: Confirm that a fresh environment has no policies yet.
   - Example: `{"limit":5}`
   - Expected response: `{"ok":true,"policies":[]}`

##### `audit_log`
**Purpose**
- This tool retrieves the stored audit trail for scope checks, policy validations, snapshots, and related governance events.
- It is the primary evidence endpoint for compliance review, postmortems, and debugging.

**Guidelines**
- Recommended: Use after a session ends to review what happened and preserve compliance evidence.
- Recommended: Use when you need a time-ordered explanation of which tools returned which decisions.
- Not recommended: Treating it as a replacement for real-time monitoring or alerting.
- Not recommended: Assuming it can reconstruct external actions that were never logged by Claw.

**Limitations**
- It returns only events that Claw actually stored.
- Unlogged or out-of-band actions cannot be reconstructed.
- `session_id` is optional, but account-wide reviews can become large and should be paired with a deliberate `limit`.

**Parameters**
- `session_id` — string / optional / Session identifier used to filter to one governed run.
- `limit` — number / optional / Maximum number of audit entries to return.

**Response**
- On success it returns `ok` (boolean) and `entries` (array).
- Each entry can include `timestamp`, `tool`, `status`, `policy_id`, `detail`, and `session_id`.
- An empty array is still a valid success response.
- Success example:
  - `{"ok":true,"entries":[{"tool":"validate_action","status":"ALLOWED","session_id":"release-123","detail":{"action":{"action":"write"}}}]}`
- Empty example:
  - `{"ok":true,"entries":[]}`

**Examples**
1. Recommended scenario: Review one governed run after the session is over.
   - Example: `{"session_id":"release-123","limit":50}`
   - Expected response: `{"ok":true,"entries":[...]}`
2. Recommended scenario: Gather account-wide compliance evidence.
   - Example: `{"limit":100}`
   - Expected response: `{"ok":true,"entries":[...]}`

### Constitutional Constraints
Claw enforces permanent restrictions that cannot be overridden, even by explicit user approval. These checks run before session scope and before policy evaluation.

Always-on guardrails:
- Permanently block dangerous paths such as `/etc/passwd`, `/etc/shadow`, `/.ssh`, and `/root`
- Permanently block autonomous changes to `.env`, secrets, and payment-related assets
- Permanently block destructive deletes in production
- Layer policy validation and snapshot requirements together

### Getting started
Use the shared Rail auth flow: register your email, receive an API key, and add Claw to your MCP configuration.

1. **Register email**: Submit your email using the form below.
2. **Receive API key**: Receive the shared API key used by both Rail and Claw.
3. **Add MCP config**: Add `claw.aiops.services/mcp` to your agent MCP config.

```json
{
  "mcpServers": {
    "aiops-claw": {
      "url": "https://claw.aiops.services/mcp",
      "transport": "http",
      "headers": {
        "X-Rail-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

### Pricing
The pricing model is shared with Rail: 50 free calls, then unlimited access through paid AIOps Live plans.

**Free**
- 50 MCP tool calls
- Policy registration
- Snapshots and audit logs

**AIOps Live Paid**
- Unlimited MCP calls
- Shared API key
- Production agent governance

### Register for an API key
Register your email address to issue a shared Rail / Claw API key instantly.