DeepSeek Harness ツール実行パイプラインと権限ゲート
前の章で defineTool を使ってツールを登録する方法と、イベントシステムを使ってさまざまな拡張ポイントを監視する方法を学びました。
しかしここで疑問があります。モデルがツール呼び出しを1回発行したあと、ツールが実際に実行され、結果がモデルに戻るまで、間にどのような段階を経るのでしょうか?
この章では、dsh の「ツール実行パイプライン」と、フックプラグインを使って権限ゲートを実装する方法を明確に説明します。
一言でいうと、1回のツール呼び出しは固定の順序で複数の段階を経ます。各段階は1種類のポリシーを担当し、フックプラグインはその中で許可・拒否・問い合わせを行うことができます。
パイプラインの全体的な順序
ツール実行は「関数を1回呼び出す」ほど単純ではなく、固定の順序を持つパイプラインです。
公式ドキュメントでは順序を次のようにまとめています。tools/pre-execute → 単調ガード → tools/execute → tools/post-execute → finalizeContent → tools/result。
このうち最初の3つの waterfall は1回の呼び出しを書き換えることができ、定義自身が制御する finalizeContent と tools/result はその後で実行されます。
まず、混同しやすい2つの概念を見てみましょう。
waterfall(Waterfall イベント)はイベントディスパッチパターンの一つで、リスナーは next() を呼び出すことができますnext()決定権を委譲するか、直接決定を返してショートサーキットすることもできます。
単調ガード(monotonic guard)は、縮小のみを許可し、取り消しを許可しない最終防衛線です。
以下、各段階を順に詳しく説明します。
tools/pre-execute:再配置可能なポリシーレイヤー
tools/pre-executeこれはパイプラインの最初の waterfall であり、「フック・権限・サンドボックス」といった再配置可能なポリシーを担います。
「再配置可能」と呼ばれるのは、リスナーが next() を介してnext()決定権を次のリスナーに渡せるからです。複数のポリシープラグインの実行順序は設定で調整できます。
この waterfall は型付きの決定を返しますPreToolDecision値は3つあります。
| 決定 | 意味 | 後続の動作 |
|---|---|---|
{ kind: 'allow' } | この呼び出しを許可する | 単調ガードと後続の段階に進む |
{ kind: 'deny'; reason: string } | この呼び出しを拒否する | エラー結果として具体化され、ツール本体はスキップされる |
{ kind: 'ask'; reason?: string } | ユーザーに問い合わせる | 承認サービスが allow を返した場合のみallowed-once続行し、それ以外の場合は拒否する |
注意askask 分岐:ここではctx.approvalctx.ask() の一回限りの問い合わせがトリガーされます。この部分は次の記事で詳しく説明します。
パラメータは書き換えられません。履歴、監査、UI、実行の一貫性が保たれなければならないからです。
pre-execute はどのようなときに使うのか?
ポリシーが「許可・拒否・問い合わせ」のいずれかの動作を必要とし、かつポリシー間の順序を自由に並べ替えたい場合は、これを使います。
サンドボックス、権限、plan-mode などのプラグインはすべてこの拡張ポイントを使います。
単調ガード:取り消し不能な最終拒否
waterfall の欠点は、後から登録されたリスナーが前のリスナーの決定を覆せることです。
ある不変条件(invariant)が「最終拒否であり、誰にも取り消せない」ことを必要とする場合には、これを使います。ctx.tools.guard()。
ガードの型はToolGuardそれは意図的に allow 結果を持ちません。文字列を返すと拒否を表し、undefinedundefined を返すと現状維持を表します。
// ToolGuard:感知作用域的最终预分派策略 type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined
ガードには allow 結果がないため、リスナーの順序によって一度の拒否を許可に戻すことは決してできません。
これが「単調」の意味です。減るだけで増えず、権限を奪うだけで与えません。
実践原則再配置可能なポリシーはtools/pre-execute;「最終的に有効で取り消し不能」でなければならない不変条件はctx.tools.guard()。
tools/execute と tools/post-execute
tools/execute「アラウンドディスパッチ」を担当します。つまり、実際にツール本体を呼び出す処理を包み込みます。
タイムアウト、リトライ、メトリクス収集はすべてこの層で行います。ここが実際のディスパッチのライフサイクルをラップします。
ここで取得できるビューはToolDispatchExecutionこのビューだけが必須の signal を置き換えられますexec.signalデッドラインを設定するために使用します。
置き換えルールは次のとおりです。置き換えは可能ですが、削除はできません。レジストリはツール本体を呼び出す前に呼び出し元の signal を再マージします。
tools/post-executeツールが実行され、結果が正規化される前にチェックまたは書き換えを行います。これはPostToolDecision:
| 決定 | 意味 |
|---|---|
{ kind: 'accept'; content? } | 結果を受け入れ、表示内容を置き換えられる(正規値とメタデータは保持) |
{ kind: 'accept'; value } | 結果を受け入れ、正規値を置き換えられる(再検証と内容の再計算が行われる) |
{ kind: 'block'; feedback } | 結果をブロックし、修正フィードバックをエラー結果にする |
コンテンツの置き換えは表示のためのポリシーであり、秘匿のためのポリシーではありません。
プログラム上の値を隠すには、その値を置き換えるか、結果をブロックする必要があります。
finalizeContent と tools/result
finalizeContentこれらはツール定義(ToolDefinition)自身が持つコールバックで、レジストリはそれをちょうど1回だけ呼び出します。
これは「最後のコンテンツ専用不変条件」です。同期実行され、コンテンツレベルの最終修正のみが許可されます。
その後、レジストリは受け入れられた結果を具体化して凍結し、tools/result をトリガーします。tools/result。
tools/resultこれは同期通知であり、次のものを監視するために使います。凍結された不変の権威ある結果。
オブザーバーは結果を変換できません。また、オブザーバーの失敗は分離され、メインフローに影響しません。
「監査・メトリクス・最終結果の取得」が必要なときは tools/result を使います。「結果の変換やコンテキストの追加」が必要なときだけ tools/post-execute を使います。tools/post-execute。
使い分けの覚え方:pre-execute は「できるかどうか」を決定し、execute は「どうやるか」を決定し、post-execute は「結果をどう見せるか」を決定し、result は「最終結果をひと目見る」だけを担当します。
実践例:権限ゲートプラグインを書く
公式ドキュメントは「権限ゲート」を例に、フックプラグインがどのようにtools/pre-execute。
フックプラグインは通常の Cordis プラグインであり、外部プロトコルは必要ありません。
実装例
// tools/pre-execute に基づく権限ゲートプラグイン。
// 型付きの決定を返す:ブラックリストに一致したら deny、そうでなければ next() を呼び出して委譲する。
import type { Context } from '@deepseek-ai/cordis'
import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'
// ブラックリスト:サンプル プロジェクトでファイルシステムへの直接書き込みを禁止するツール。
// ここでは最も単純な集合でデモする。実際のプロジェクトではデータベースを参照したり承認サービスに問い合わせたりできる。
const DENY_TOOLS = new Set(['fs_write', 'fs_edit'])
// ポリシー判定関数:この呼び出しが許可されるかどうかを返す。
// exec は不変の呼び出し ID(callId、name、arguments、agent、token、signal)を持つ。
async function isAllowed(exec: ToolExecution): Promise<boolean> {
if (DENY_TOOLS.has(exec.name)) return false
// 追加例:サンプル デモでは .env ファイルの変更を禁止する(パラメータはポリシーに入る前に凍結されている)。
const raw = exec.arguments as { path?: string }
if (typeof raw.path === 'string' && raw.path.includes('.env')) return false
return true
}
export const name = 'permission-gate'
export function apply(ctx: Context) {
// tools/pre-execute は waterfall:リスナーは決定を返すか、next() を呼び出して委譲できる。
ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
if (!(await isAllowed(exec))) {
// deny を返すとこの呼び出しは即座に終了し、後続のリスナーは実行されない。
return { kind: 'deny', reason: 'Denied by policy: this tool is not allowed in the サンプル workspace.' }
}
// 許可:決定権をパイプライン内の後続リスナーに委ねる。
return next()
})
}
このプラグインを読み込むと、モデルがツールを呼び出すたびに必ず最初にこのプラグインを通ります。
ブラックリストに一致したツールは reason 付きのエラー結果を受け取り、ツール本体はスキップされます。
型付きの決定を返すため、他のポリシープラグインはその後も引き続き決定に参加できます。
実践例:tools/execute でタイムアウトを追加する
タイムアウトは「アラウンドディスパッチ」の関心事なので、tools/execute でtools/execute包むべきであり、ツール本体に書き込むべきではありません。
実装例
// tools/execute で実際のディスパッチライフサイクルをラップする: 各ツール呼び出しに30秒のタイムアウトを追加する。
import type { Context } from '@deepseek-ai/cordis'
export const name = 'tool-guard'
export function apply(ctx: Context) {
// tools/execute は waterfall です: 実際のツール本体を実行するには next() を呼び出す必要があります。
ctx.on('tools/execute', async (exec, next) => {
// 注意: tools/execute ビューのみが exec.signal を置き換えられます。
// ここでは呼び出し元のシグナルと30秒のデッドラインを融合し、元の signal を上書きします。
const originalSignal = exec.signal
const deadline = AbortSignal.timeout(30_000)
exec.signal = AbortSignal.any([originalSignal, deadline])
try {
// 実際のツール execute() に委任します; タイムアウトまたは呼び出し元のキャンセルで abort が発生します。
return await next()
} finally {
// 使用後は元のシグナルを復元し、後続の呼び出しを汚染しないようにします。
exec.signal = originalSignal
}
})
}
規則: exec.signal は置き換え可能ですが、削除はできません。
レジストリはツール関数本体を呼び出す前に呼び出し元の signal を再融合するため、ラッパー層が signal を置き換えても安全です。
実践例:ctx.tools.guard() で単調拒否を行う
不変条件が「最終拒否、取り消し不可」を必要とする場合に使いますctx.tools.guard()。
注意: ガードの戻り値の型はstring | undefined、allow ブランチはありません。
実装例
// 取り消し不可能な最終拒否: サンプル デモ環境での run_code の実行を禁止します。
import type { Context } from '@deepseek-ai/cordis'
export const name = 'invariant-guard'
export function apply(ctx: Context) {
// 単調ガードを登録します。文字列を返すと拒否; undefined を返すと現状維持を意味します。
const disposer = ctx.tools.guard((execution) => {
if (execution.name === 'run_code') {
return 'run_code is disabled in the サンプル demo profile.'
}
return undefined // 通過: pre-execute の決定をそのまま維持します
})
// guard() は正確なアンロード関数を返します; プラグインのアンロード時にフレームワークが自動的に呼び出します。
ctx.effect(() => disposer)
}
ガードには allow 結果がないため、後でリスナーが通過させようとしてもrun_code、この拒否を許可に戻すことはできません。
まとめと自己チェック
ツール実行パイプラインは「ポリシー」と「ツール本体」を分離し、フックが異なるツールファミリーにまたがって機能することを可能にします。ツールを特定のポリシーサービスに結合させる必要はありません。
セルフチェック問題:
| 問題 | 参考 |
|---|---|
| あるツールを「誰にも永久に通過させたくない」場合、pre-execute と guard のどちらを使うべきですか? | guard です。ガードには allow 結果がなく、取り消し不可だからです |
| すべてのツールに統一のタイムアウトを追加したい場合、どのイベントをリッスンすべきですか? | tools/execute、それはディスパッチを包み込み、signal を置き換えられます |
| 最終結果を監査用に記録するだけで、何も変更したくない場合、どの段階を使うべきですか? | tools/result、それは凍結された権威ある結果を観測します |