ID: ADR-004 タイトル: ツール保持の共有状態は、デーモン所有のアイデンティティとハンドル所有権に従う 日付: 2026-03-22 ステータス: 承認済み 関連:

• https://github.com/zeroclaw-labs/zeroclaw/issues/4057
• crates/zeroclaw-runtime/src/tools/mod.rs
• crates/zeroclaw-tools/src/canvas.rs
• crates/zeroclaw-tools/src/reaction.rs
• crates/zeroclaw-api/src/tool.rs

ADR-004: ツールが保持する共有状態はデーモンが所有するアイデンティティとハンドルの所有権に従う

これは遡及的に復元された記録です。元のADRは docs/architecture/adr-004-tool-shared-state-ownership.md の下に追加されましたが、mdBookの移行中に削除されました。元の記録以降、コードパスはワークスペースクレートに移動しています。この復元版では、有用な箇所でパス参照を更新しつつ、承認された決定内容をそのまま維持しています。

コンテキスト

ZeroClaw ツールは、単一のデーモンプロセスが複数の接続クライアントとエージェントセッションにサービスを提供できるマルチクライアント環境で実行されます。一部のツールは、長期間維持される共有状態を必要とします。

• 委譲ツールは親ツールへのハンドルを保持します。
• チャネル向けツールはチャネルマップへのハンドルを保持します。
• canvasツールは共有された表示状態を保持します。
• 将来のツールでは、レートリミッター、コネクションプール、認証情報ハンドル、セッションスコープのキャッシュが保持される可能性があります。

これらの状態をすべて同じ方法で扱うことはできません。一部は正当な共有ディスプレイやレジストリの状態です。一部はセキュリティに関わるものであり、クライアントまたはセッションごとに分離する必要があります。

共有された契約がなければ、新しいツールは状態の重複、クライアント間のデータ漏洩、リロード後の古い状態、または誤ったライフサイクルフェーズでの起動時検証のブロックを引き起こすリスクがあります。

決定

ツールは、ハンドルパターンに従い、デーモンが所有する識別子、分離、ライフサイクル、リロードのルールを尊重する場合、長期間存続する共有状態を所有できます。

1. 所有権

ツールが共有状態を正当に所有する場合、構築時に渡されるクローン可能なハンドルを使用します。これは通常、Arc<RwLock<T>> またはその周辺の薄いラッパーです。

現在のワークスペース内の例には次のものがあります:

共有状態を必要とするツールは、次の条件を満たす必要があります。

• 名前付きハンドル型またはラッパーを定義する。
• 構築時にハンドルを受け入れる。
• 並行性と所有権の契約を文書化する
• リクエストごとまたはクライアントごとのデータにグローバルなミュータブル状態を使用しないでください。

2. アイデンティティ

デーモンはクライアントとセッションのアイデンティティを保持します。ツールは、IPアドレス、ヘッダー、ユーザー名、チャネル固有の送信者文字列などのトランスポートの詳細から、独自の永続的なクライアントアイデンティティキーを構築してはなりません。

クライアントごとの名前空間を必要とするツールは、デーモンによって割り当てられたアイデンティティを利用するか、すでにスコープが設定されたハンドルを受け取ります。クライアントごとの分離を必要としないツールはアイデンティティ面を無視してもかまいませんが、並行するものを独自に作り出してはなりません。

3. ライフサイクル

ツールのライフサイクルには4つのフェーズがあります。

1. 構築: ハンドルと設定から導出された入力でインスタンス化します。ブロッキングなネットワークまたはファイルシステムの検証は行わないでください。
2. 登録: ツールレジストリに登録します。使用前に検証が必要な場合、ツールは起動時に検証を実行することがあります。
3. 実行: 単一のリクエストを処理する。このパスではブロッキング検証やレジストリの再構築を避ける。
4. シャットダウン: 所有者が明示的なシャットダウンメソッドを提供している場合はそれを使用し、そうでない場合は Drop を通じて、所有するリソースをクリーンアップします。

設定、認証情報、ポリシー、または外部リソースから導出された検証状態は、ソースが変更された場合に無効化する必要があります。セキュリティに関係のない表示状態は、リロードによってその有効性が影響を受けない場合に限り、リロード後も保持されることがあります。

4. 分離

クレデンシャル、ポリシー、クォータ、ユーザーデータ、またはセッションデータを漏洩させる可能性のあるステートは、所有するサーフェスに応じて、クライアント、エージェント、またはセッションごとに分離する必要があります。共有ハンドルは、キー空間がデーモン所有のアイデンティティによってスコープされていない限り、クライアントごとのシークレットを保存してはなりません。

ブロードキャスト表示状態、読み取り専用のレジストリデータ、チャネルハンドルなど、自然に共有される状態は、クライアント間で共有される場合があります。文字列キーを使用する場合は、名前空間のプレフィックスやトレースメタデータをサポートし、オペレーターがクライアント、エージェント、チャネル、またはセッションでフィルタリングできるようにする必要があります。

5. リロードセマンティクス

設定由来の検証とキャッシュは、関連する設定、認証情報、ポリシー、ワークスペース、またはプロバイダーのソースが変更された後は無効です。ツールは、使用時に信頼できる情報源から再解決するか、所有者から新しいハンドル/設定由来の値を受け取る必要があります。

リロードルールはレジストリの変更ではなく、有効性に関するものです。ツールは、リロードがその状態の有効性に影響しない場合に限り、セキュリティに関係しない表示状態をリロード間で保持できます。

結果

肯定的な結果:

• ツールが所有する状態が検出可能かつ監査可能になります。
• セキュリティ上機密性の高いデータには、名前付きの分離要件があります。
• ランタイムのリロード動作には、明確な無効化ルールがあります。
• 新しいツールは、グローバル状態を発明することなくハンドルパターンを再利用できます。
• レビュー担当者は、新しいツールフィールドやキャッシュを受け入れる前に、信頼できる情報源を要求できます。

否定的な結果:

• 単純なシングルトンのように見えるツールであっても、クライアント、エージェント、セッションのアイデンティティについて考慮する必要があります。
• デーモンのアイデンティティ面またはリロードモデルが変更された場合、一部の古いハンドルは移行が必要です。
• ハンドルパターンだけでは不十分です。所有権と正規の状態は、レビューにおいて依然として明示される必要があります。

参照

• 組み込みツール一覧
• Issue #4057
• AGENTS.md
• crates/zeroclaw-runtime/src/tools/mod.rs
• crates/zeroclaw-tools/src/ask_user.rs
• crates/zeroclaw-tools/src/poll.rs
• crates/zeroclaw-tools/src/reaction.rs
• crates/zeroclaw-tools/src/canvas.rs
• crates/zeroclaw-api/src/tool.rs
• crates/zeroclaw-gateway/src/lib.rs