DeepSeek Harness Hooks設定は、最初から複数の自動化を入れず、観測できる1つの阻止点から始めるのが安全です。失敗時に実行を続けるか不明な段階では、許可ではなく拒否を既定にし、動作確認後に対象範囲を広げます。
[ SECTION_01 ] 対象読者
Agent開発者は、ツール呼び出し前後の検査や実行結果の記録に使えます。プラットフォームエンジニアは、プロジェクト単位と環境単位の設定を分離できます。リモートMacの保守担当者は、切断、再起動、非対話実行でも証跡が残るかを確認できます。
DeepSeek Harnessは現在も開発者プレビューで、互換性を壊す変更があり得ます。設定キーやイベント名は、作業時点の公式リポジトリとREADMEを基準にしてください。
[ SECTION_02 ] 先に決めるのはHookの役割だけです
Hooksの目的は、最初に1つへ絞ります。権限の拒否、結果の記録、停止条件の門番、追加コンテキストの注入は似ていますが、検証方法が異なります。
- 権限の拒否：実行前に許可条件を確認します。
- 結果の記録：実行後の成功、失敗、出力要約を保存します。
- 停止条件の門番：セッションを終了させる条件を検査します。
- コンテキスト補充：ツール呼び出し前後に短い情報を追加します。
第一版では、PreToolUseを使った低リスクなツール呼び出しの記録、または限定的な拒否のどちらかにします。HooksはAgentの実行経路を検査できますが、OSの権限分離、秘密情報の保管、ネットワーク分離を代替するものではありません。
公式のREADMEでは、DeepSeek Harnessはプラグイン中心の構成として説明されています。したがって、HookをOS全体の防壁と考えず、Agentランタイム内の制御点として扱う必要があります。
[ SECTION_03 ] 準備段階では設定場所を推測しません
DeepSeek Harness Hooks設定ファイルの場所は、別のAgent製品の例からコピーしないでください。公式ソースの設定読込処理、サンプル、起動処理を確認し、どの階層が優先されるかを記録します。
確認する項目は次の通りです。
- 設定ファイルを読む処理の位置。
- プロジェクト固有設定とユーザー設定の優先順位。
- Hookスクリプトの相対パスが解決される作業ディレクトリ。
- 標準入力で渡されるイベント形式。
- 標準出力に返せる判定とエラー形式。
- Hookが読まれたことを示す起動ログ。
公式リポジトリは、標準的な起動方法としてNode.jsの導入後にnpx @deepseek-ai/dsh webを案内し、初期Web UIをhttp://127.0.0.1:3080で提供すると記載しています。現行READMEの起動手順と、package.jsonの実行定義を照合してから環境を作成します。
[ SECTION_04 ] 第一段階：低リスクの1ルールだけを発火させます
最初の対象は、読み取り系ツールや検査用の呼び出しにします。書き込み、シェル、外部サービス接続は後回しです。目的は防御性能ではなく、入力、判定、未発火の3点を再現できる状態にすることです。
実装前に、次の記録項目を決めます。
- セッション識別子。
- 発火したイベント名。
- ツール名。
- 作業ディレクトリ。
- 引数の要約。
- Hookの終了状態。
- Agent側で確認できた結果。
最初の成功信号は、同じ入力で同じHookが発火することです。対象外のツールまで停止するなら、マッチングが広すぎます。逆に、ツール名の表記揺れで発火しないなら、実際のイベント入力を確認してから条件を修正します。
Hook Protocolという名前だけで入力形式を決めることも危険です。DeepSeek Harnessの現在のイベント定義と、公式ソースのコミット履歴を確認し、別実装のtool_nameやtool_inputをそのまま流用しないでください。
[ SECTION_05 ] 第二段階：許可、拒否、異常、時間切れを分けて検証します
設定文を読んで「異常時は止まる」と判断してはいけません。実行時の証拠を取ります。安全なテスト用Hookを用意し、次の順番で確認します。
- 条件に一致した呼び出しを明示的に許可します。
- 危険条件に一致した呼び出しを明示的に拒否します。
- Hook内部で処理異常を発生させます。
- Hookの応答を遅らせ、時間切れを発生させます。
- それぞれの後に、Agentが実行したか、拒否したか、通常の許可処理へ戻ったかを確認します。
時間切れと異常終了は同じ扱いとは限りません。イベントログに判定が残らない場合は、許可を認めず、該当ツールの利用範囲を狭めたままにします。失敗時の既定値が公式ソースで確認できるまで、本番の自動承認へ進めません。
[ SECTION_06 ] 書き込みとコマンドへ広げるときの境界
Bash、ファイル変更、外部ツールへ対象を広げる場合は、一度に1種類だけ追加します。作業ディレクトリ、認証情報の可視範囲、引数の型、許可するサブコマンドを別々に制限します。
たとえばコマンド名だけで許可すると、同じツールに別の引数が渡された場合を見落とします。パスの前方一致だけに頼ると、シンボリックリンクや相対パスで想定外の場所へ到達する可能性があります。完全な安全性をHookだけで作るのではなく、OSのユーザー権限と秘密情報の分離を併用します。
設定方式の比較
| 方式 | 向いている用途 | 主な利点 | 主な弱点 | 初期評価 |
|---|---|---|---|---|
| 1つの実行前Hook | 危険な呼び出しの拒否 | 判定経路を追いやすい | 記録処理を別に設計する必要があります | 5点 |
| 実行前と実行後の分離 | 拒否と結果記録 | 責任範囲が明確です | イベントの対応付けが必要です | 4点 |
| 複数Hookの一括導入 | 大規模な自動化 | 機能を一度に増やせます | 失敗原因の切り分けが難しくなります | 2点 |
| Hookを隔離機構として利用 | 強い実行制限 | 入口で制御できます | OS権限や秘密情報を守れません | 1点 |
この表の評価は、初回導入時の切り分けやすさを基準にした運用上の目安です。性能測定値ではありません。
[ SECTION_07 ] リモートMacへ移す前に責任範囲を分けます
ローカルで通ったHookを、そのままリモートMacへコピーしてはいけません。次の順番で再構築します。
- Hookスクリプトを作業ディレクトリ内へ配置します。
- 実行ユーザーとファイル権限を確認します。
- 使用するランタイムが非対話シェルのPATHから見えるか確認します。
- 必要な環境変数を、秘密情報を表示せずに存在確認します。
- 作業ディレクトリを固定し、相対パスを検査します。
- セッションを切断して再接続します。
- Macを再起動し、同じ低リスク呼び出しを再実行します。
リモートMacでは、ログインシェルとAgentから起動される非対話シェルの環境が異なることがあります。再起動後にHookが発火しない場合は、設定ファイルだけでなく、ランタイムの場所、実行権限、作業ディレクトリを確認します。
DeepSeek Harnessの開発者プレビューは、公式README上で互換性破壊の可能性が明記されています。そのため、リモート環境では現在のコミットや導入方法を記録し、更新前に旧設定へ戻せる状態を残します。公式の開発者プレビューに関する記載も、運用記録に添付しておくと判断しやすくなります。
[ SECTION_08 ] FAQ：設定場所、拒否動作、再起動後の確認
DeepSeek HarnessのHooks設定ファイルはどこに置きますか？
固定のパスを他のAgent製品から流用してはいけません。DeepSeek Harnessは開発者プレビューで互換性を壊す変更があり得るため、作業時点の公式リポジトリにある設定読込処理、サンプル、起動手順を確認し、実際に読み込まれた設定をログで検証します。パス名だけを推測して配置する方法は避けてください。
Hookで危険なコマンドの実行を止めるにはどうしますか？
まずツール呼び出し前のPreToolUseに限定し、対象ツール、作業ディレクトリ、引数の許可条件を狭く定義します。条件に一致しない場合は拒否を返し、理由を記録します。正規表現だけでコマンド全体を許可する設計は、引数の変形や作業場所の変更を見落とすため、初期導入では採用しない方が安全です。
Hookスクリプトが失敗した場合、Agentは処理を続けますか？
DeepSeek Harnessの失敗時動作を設定文だけから推測してはいけません。明示的な拒否、異常終了、時間切れを個別に発生させ、セッションイベントまたは実行ログで確認します。結果が不明な間は拒否側に倒し、権限を広げないことが安全な運用条件です。公式ソースの現在の実装が優先されます。
リモートMacを再起動した後もHooksは有効ですか？
再起動前と同じ設定が残っているだけでは不十分です。Hook本体の配置、実行権限、ランタイムのPATH、環境変数、作業ディレクトリを再確認し、非対話起動で実際に発火させます。再起動後にログが増えない場合は、設定の問題だけでなく、起動方法やユーザー環境の違いも疑う必要があります。
[ SECTION_09 ] 公開前の証拠を4種類に分けます
公開判定では、許可タスクだけを実行してはいけません。許可、拒否、Hook異常、復旧後のタスクを別々に記録します。各記録には、導入方法、使用したコミット、作業ディレクトリ、イベント名、ツール名、判定、ログ保存先、復旧操作を含めます。
公開判定の比較
| 検証ケース | 確認する結果 | 合格条件 | 不合格時の対応 |
|---|---|---|---|
| 許可タスク | Hook発火後に通常実行されたか | 対象外の処理を止めません | マッチャーを狭めます |
| 拒否タスク | ツールが実行されなかったか | 拒否理由が記録されます | 権限を広げず原因を調査します |
| 異常Hook | Agentの次の動作 | 公式仕様どおりの結果を確認できます | 既定を拒否へ戻します |
| 復旧タスク | 再接続・再起動後の発火 | 新しいセッションでも証跡が残ります | 起動環境と依存関係を再構築します |
設定変更は、必ず直前の動作版と比較できる形で保存します。ログには秘密情報、APIキー、顧客名、完全な顧客パスを残さず、ツール名、判定、失敗分類など必要最小限の要約だけを記録します。
[ SECTION_10 ] 本番投入の判断基準
次の条件を満たさない場合は試行範囲を増やしません。
- 1つのマッチング条件で発火経路を再現できます。
- 許可と拒否を別々に確認できます。
- 異常終了と時間切れの結果を実行ログで説明できます。
- リモートMacの再接続と再起動後にも発火します。
- 旧設定へ戻す手順を実行できます。
- Hookが止められないOS権限や秘密情報の問題を別の仕組みで補っています。
ローカル環境だけでHooksを試す場合、端末の常時稼働、再起動復旧、監査ログの保管を開発者側で維持する必要があります。長時間のAgent処理では、端末のスリープ、ネットワーク切断、ユーザー環境の差が運用上の弱点になります。
一方、リモートMacを使う場合も、Hookが自動的に安全になるわけではありません。スクリプト依存関係の確認、再起動後の復旧、ログの保存期間、アクセス権限を別途管理する必要があります。Mac環境の候補や運用条件を確認する場合は、NOVAKVMのMac環境案内と、Mac miniの構成選びを照合すると、必要な実行環境を整理しやすくなります。
ローカルで4種類のテストを終えた後は、クラウドMacへの提供条件を確認します。特に、Hookの依存ランタイム、再起動後の自動復旧、ログの保管先が明文化されていない構成は、継続タスクへ移す前に見直すべきです。短期の検証や一時的な実行環境であれば、NOVAKVMのMacレンタルを候補に入れる価値があります。自前端末より常時稼働の責任を分けやすく、環境を作り直す手間も抑えやすい一方、長期の固定負荷や物理インターフェースが必要な処理には、自前のMacの方が適しています。