ツール実行のライフサイクル

ZeroClaw のツールは、モデルがターン中に呼び出せる機能です。ツールカタログは何を呼び出せるかを定義し、実行ライフサイクルは呼び出しがどのように安全で、観測可能で、キャンセル可能で、プロバイダーから可視になるかを定義します。

組み込みツール、MCPツールの有効化、エージェントループ、承認ポリシー、ツール呼び出しのストリーミングイベント、レシート、オブザーバーイベント、ツール結果の履歴、キャンセル、またはチャネル入力とエージェント側アクションの境界に変更が及ぶ場合は、このページを参照してください。

実行パス

ステップ	所有者	契約を確認する
ツール定義	`zeroclaw-api::tool::Tool`	ツールは、安定した名前、説明、JSON スキーマ、非同期の `execute`、およびアトリビューションを持ちます。
ツールアセンブリ	ランタイムツールファクトリとスコープ付きレジストリ	エージェントは、バンドル、MCP設定、リスクプロファイル、および実行ごとの絞り込みによって許可されたツールのみを受け取ります。
ターンコンテキストの解決	`ResolvedAgentExecution`	ターンは1つの解決済みバンドルで始まります。モデルアクセス、レジストリ、承認マネージャー、オブザーバー、ランタイムノブ、MCP アクティベーションハンドル、レシートジェネレーターです。
プロバイダーリクエスト	`agent::turn::tool_specs` とプロバイダー呼び出し	ネイティブツールプロバイダーは構造化された仕様を受け取り、テキストプロトコルプロバイダーは厳密なパースによって隠されない限りプロンプト指示を受け取ります。
ツール呼び出しの解析	`agent::turn::parse_response` とパーサーヘルパー	ネイティブおよびテキストのツール呼び出しは、利用可能な場合はプロバイダー ID 付きの解析済み呼び出しに正規化されます。
準備	`agent::turn::call_prep`	フック、配信デフォルト、承認、プロンプト必須の重複ガード、および通常の重複呼び出しガードは、ディスパッチ前に実行されます。
実行	`agent::tool_execution`	呼び出しは、ポリシー、キャンセル、およびアクティベーションの制約に従って、順次または並列に実行されます。
結果の記録	`post_exec`、`results_collect`、`history_append`	結果は順序付けされ、ログに記録され、監視され、必要に応じて受領確認され、境界付けされ、プロバイダー履歴に追記されます。
ループ制御	`run_tool_call_loop`	モデルはツールの結果を確認し、最終的なテキストを返すか、キャンセルされるか、反復回数の上限に達するまで処理を続行する場合があります。

ランタイムはこれらのステップを分離することで、レビューでどの境界が変更されたのかを問えるようにしています。ツールの追加は、承認ポリシーの拡大、プロバイダーのツール仕様の変更、オブザーバーのペイロードの改変、結果の永続化とは同じではありません。

ツール定義と登録

すべてのツールは Tool トレイトを実装します:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync + Attributable {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
}
}

ToolResult は小さく、success、output、error で構成されます。各ツールの実装が独自のロギングや承認パスを考案すべきではありません。ディスパッチャーが共通の開始/結果イベント、レシート、オブザーバーレコード、進捗メッセージ、履歴変換を管理します。

ツールの仕様はプロバイダーへのリクエスト用に再構築されます。現在の ToolSpec は大きなスキーマを Arc を通じて共有するため、ワイヤーフォーマットは同じままで、反復ごとの深いクローンを回避します。

エントリポイントは、ポリシーをインラインで再導出してターンを組み立てるべきではありません。ターンエンジンは、エージェントごとの安定した依存関係のために ResolvedAgentExecution バンドルを受け取ります: モデルバインディング、有効なツールレジストリ、オブザーバーと承認ハンドル、解決済みランタイムノブ、遅延MCPアクティベーションセット、モデル切り替えコールバック、およびオプションのレシートジェネレーター。

メッセージごとの状態はそのバンドルの外部に保持されます。履歴、ストリーミングシンク、イベントチャネル、ステアリングメッセージ、キャンセルトークン、メモリ注入状態、およびイングレスエンベロープです。

PRが新しい実行入力を追加する場合、この解決済みコンテキストまたはターンごとの明示的な ToolLoop 状態を通して受け渡すことを推奨します。隠れたグローバル変数や、単一のツールパス内での設定の再取得は避けてください。

可用性と MCP の有効化

モデルは現在のターンで有効なツールのみを呼び出せます。

静的ツールはスコープ付きレジストリから取得されます。
excluded_tools は、プロンプト/スペックへの公開前および実行前に名前を削除します。
native-tool プロバイダーは、effective ツール用の構造化された仕様を受け取ります。
text-protocol プロバイダーは、text ツール呼び出しが許可されている場合にのみツール命令を受け取ります。
strict parsing はテキストツールプロトコルを完全に隠蔽できます。
tool_filter_groups は、現在のターンでどの MCP ツールスキーマを表示するかを決定します。mode = "always" のグループは、対象となる遅延 MCP ラッパーを事前に有効化できます。一方、dynamic のグループは、現在のユーザーメッセージがそのキーワードと一致した場合にのみツールを公開します。
遅延 MCP は、すべての MCP ラッパーの代わりに tool_search スタブを公開できます。

遅延MCP有効化はターン内でステートフルです。tool_search は一致するMCPスタブを共有の ActivatedToolSet に解決し、後続の呼び出しはそれらの有効化されたラッパーを実行できます。フィルターグループ自体はケイパビリティを付与しません。スコープ付きレジストリ、MCPポリシー、および拒否リストが、どのラッパーが存在できるかを引き続き決定します。

tool_search を、それが有効化するツールと並行して実行しないでください。ディスパッチャーは、tool_search を含むバッチを強制的に順次実行させ、ルックアップが有効化と競合しないようにします。デリゲート/サブエージェントのパスは、付与された有効化済みセットを引き継がなければなりません。そうしないと、デリゲートされたターンが、そのエグゼキューターが解決できないツールを広告したり試行したりする可能性があります。

承認と準備

準備はエグゼキューターがツールを実行する前に行われます:

before_tool_call フックは、名前や引数をキャンセルまたは書き換えることができます。
チャネル対応ツールには、チャネル配信のデフォルトが注入される場合があります。
ランタイムは、引数内の「承認済み」マーカーをすべてクリアします。
承認ゲートは、ApprovalManager に対してツールを評価します。
承認済みの呼び出しには、ランタイム承認済みマーカーが復元されます。
重複呼び出しガードは、ツールが免除されていない限り、繰り返される同一の呼び出しを削除します。

承認には異なるフロントドアがあります：

CLI マネージャーはオペレーターにプロンプトを表示し、yes、no、always をサポートします。
非対話型チャネルマネージャーは、チャネルがインライン承認バックチャネルを提供しない限り、プロンプトが必要なツールを自動拒否します。
ACP/web バックチャネルは、ターン自体が非対話的であっても、承認リクエストを実際のオペレーターに届けることができます。
DenyWithEdit / 置換応答はサニタイズされ、合成ツール結果になります。元のツールは実行されません。

承認は実行前の制御です。レシートではなく、ツールが実行されたことの証明でもありません。監査エントリは決定と、決定したチャネルまたはバックチャネルを記録します。

プロンプトが必要なシェル呼び出しには追加のループガードがあります。エージェントが承認前に同じプロンプト必須のシェル呼び出しを繰り返した場合、何度も確認を求める代わりにループを中断します。

ディスパッチ、キャンセル、および順序付け

エグゼキューターは、ストリーミングクライアントが実行中のカードをライブ表示できるよう、ツールを実行する直前に保留中の TurnEvent::ToolCall を発行します。ツールが完了すると、同じ相関 ID を使用して対応する TurnEvent::ToolResult を発行します。

並列実行は次の場合にのみ許可されます:

ランタイムノブが並列ツールを有効化します。
バッチに複数の実行可能な呼び出しが含まれています。
バッチ内のいずれの呼び出しも承認を必要としません。
バッチに tool_search が含まれていません。

それ以外の場合、呼び出しは順次実行されます。順次ディスパッチは各呼び出しの前にキャンセルを確認し、キャンセルされた場合は残りのディスパッチを停止します。並列ディスパッチでは一部の兄弟が完了する一方で他が中断されることがあり、完了した呼び出しは実際の終端結果を保持し、未完了の呼び出しのみが中断結果を受け取ります。

順序付けされた結果ベクターは、元のモデル呼び出しごとに1つのスロットを保持します。準備段階では、キャンセル、拒否、置換、または重複排除された呼び出しのスロットを埋め、実行段階では残りのスロットを埋めます。これにより、一部の呼び出しが実行されない場合や、並列呼び出しが順不同で完了した場合でも、プロバイダー履歴の順序が保持されます。

結果、レシート、履歴

ツール実行が成功すると、空の出力は (no output) に正規化されます。[agent.tool_receipts] enabled = true の場合、実行が成功すると、結果が履歴に追加される前に、アクティブなレシートスコープからレシートを受け取ることができます。チャネルランタイムのパスと直接ターンのパスではスコープの有効期間が異なります。正確な HMAC 形式とキーの有効期間の詳細については、ツールレシートのページを参照してください。

レシートは結果の証拠です。承認の決定でも、永続的な監査記録でも、チェーンでもなく、拒否・置換・ブロック・失敗・中断された呼び出しに対しては生成されません。

実行後:

observer の ToolCallStart イベントには、ツール名、利用可能な場合はプロバイダーのツール呼び出し ID、引数、チャンネル、エージェントエイリアス、ターン ID が含まれます。
スパン指向のバックエンドが必要とする相関フィールドを繰り返しつつ、ターミナルオブザーバーの ToolCall イベントには継続時間、成功フラグ、およびスクラブ済みの結果が追加されます。
進捗ストリームには、機密情報が除去された失敗テキストとともに開始/完了行が表示されます。
after_tool_call フックは実行された呼び出しに対して実行されます。
結果は、モデルが参照可能な履歴に追加される前に max_tool_result_chars によって制限されます。
ループ検出は、設定で無視するツールを除き、結果コンテンツを使用します
次のプロバイダーリクエストでは、アシスタントのツール呼び出しターンと順序付けされたツール結果が表示されます。

ツールの結果は、メモリへの書き込みが発生しない限り長期メモリではありません。それらは、現在のターンのコンテキスト、永続化されたセッション履歴、ストリーミングされた UI イベント、オブザーバー/ログレコード、またはレシートを伴う結果である可能性があります。PR やレビューでは、その領域を正確に名指ししてください。

このページが所有していないもの

チャネルアダプターとゲートウェイは、インバウンドトランスポート、認証、ペアリング、Webhook のデコード、および返信の配信を担当します。ツール実行は、ターンがエージェントループに到達し、モデルがツール呼び出しを発行した後に開始されます。

設定ライフサイクルは、ツール関連の設定がどのように読み込まれ、保存され、上書きされ、再読み込みされるかを管理します。このページでは、それらがターンに入った後の解決済みの値のみを扱います。

セキュリティおよび自律性のドキュメントがポリシー用語を定義しています。このページでは、そのポリシーが具体的なツール呼び出しにどのように適用されるかを示します。

メモリとペイロードのライフサイクルは、履歴、ファイル、メディア、メモリの耐久性とプライバシー境界を管理します。このページでは、それらのサーフェスに供給するツール結果のパスについて説明します。

バックグラウンド作業のライフサイクルは、ツールが委任された作業またはサブエージェント作業を開始する場合に、より長期的なコントラクトを担います。ツールがタスク ID を返すだけでは、その実行が再起動後に再開可能になるわけではありません。

レビュー担当者向けチェックリスト

ツール実行の変更については、レビュアーのサインオフ前にこれらに回答してください:

どの境界が変更されましたか: ツール定義、レジストリの組み立て、承認、実行、レシート、オブザーバーイベント、履歴、または UI ストリーミングのうちどれですか?
ツールは通常のファクトリパスを通じて帰属可能かつ登録されたままですか？
モデルはこのエージェント/ラン/イテレーションに許可されたツールのみを参照しますか？
excluded_tools、実行ごとの絞り込み、tool_filter_groups、および遅延 MCP アクティベーションは、まだ一致していますか？
プロンプト必須の呼び出しは順次実行され、正しい承認サーフェスを尋ねますか？
非対話型実行は、サイレントに承認するのではなく、拒否するか実際のバックチャネルを使用しますか？
duplicate-call および repeated-prompt ガードは保持されますか？
キャンセルは未完了のツールカード/結果のみを閉じますか？
オブザーバ/ログ/プログレスのサーフェスは、ユーザーまたはシークレットのペイロードが出現し得る箇所でスクラブされ、バウンドされていますか？
レシートは成功した実行の証拠として記述されており、承認、永続性、またはゼロ知識証明ではないですか？
PR は、変更するユーザー可視のサーフェス（CLI、channel、ACP/WS、gateway、cron、または delegate/subagent）に対する境界レベルの検証を含んでいますか？

ソースポインタ

正規ドキュメント:

主要なコードエントリポイント:

ツールトレイトと結果の形状: crates/zeroclaw-api/src/tool.rs
オブザーバーツールイベント: crates/zeroclaw-api/src/observability_traits.rs
ターン実行コンテキスト: crates/zeroclaw-runtime/src/agent/turn/execution.rs
ターンエンジンの実行シートとループ: crates/zeroclaw-runtime/src/agent/turn/mod.rs
ツール呼び出しの準備と承認: crates/zeroclaw-runtime/src/agent/turn/call_prep.rs と crates/zeroclaw-runtime/src/agent/turn/approval_gate.rs
ツールディスパッチ: crates/zeroclaw-runtime/src/agent/tool_execution.rs
ツールレシート: crates/zeroclaw-runtime/src/agent/tool_receipts.rs
結果の収集と履歴への追加: crates/zeroclaw-runtime/src/agent/turn/results_collect.rs と crates/zeroclaw-runtime/src/agent/turn/history_append.rs
承認マネージャー: crates/zeroclaw-runtime/src/approval/mod.rs
スコープ付きツールアセンブリと遅延MCPアクティベーション: crates/zeroclaw-runtime/src/tools/scoped.rs

ZeroClaw Docs