Clawの解剖学：オーケストレーション層としての84のHook

最初のHookは4分で書けました。Anthropic専用のワークフローで、モデルがOpenAI製品を提案するのをブロックするためのものです。2ヶ月後、その1つのHookは84になっていました。84のHookは43のSkill、19の特化型エージェント、30のライブラリモジュールとつながっていました。ある時点で、この寄せ集めはスクリプトの集まりであることをやめ、オーケストレーション層になったのです。

「Claw」とは、AIエージェントCLIの上に構築され、スケジューリング、コンテキスト管理、ツールルーティング、品質保証を担うオーケストレーション層のことです。 トップダウンの設計からではなく、個々の失敗を解決するなかで有機的に育ちます。そのアーキテクチャはKarpathyが特定した5つの機能に対応し、計画と実行の分離がHookベースのシステムの自然な性質として立ち上がってきます。

そうなるように設計したわけではありません。「15,000行のエージェントインフラを構築しよう」と腰を据えて決める人はいません。1つの問題を解決します。次にもう1つ。そして、問題同士が干渉し合うという問題を解決します。アーキテクチャに気づいた頃には、それはすでに存在しています。

Andrej Karpathyも同じことに気づいていました。2026年2月、彼は「Claws」を新しい計算レイヤーとして説明しています。LLMエージェントの上に構築されるオーケストレーション、スケジューリング、コンテキスト管理、ツールルーティングの層であり、エージェントがLLMの上に構築されるのと同じ関係です。¹ この枠組みは、実践者たちが名前をつけないまま構築してきたものを、はっきりした形に結晶させました。本記事は、そうしたシステムの1つを解剖したものです。何を含み、どのように育ち、どこで機能し、どこで失敗するのかを見ていきます。

TL;DR

Karpathyの「Claws」層は、エージェントCLIの上に構築されたオーケストレーションシステムを指します。私はClaude Code上で2ヶ月かけて自然発生的にこのシステムを構築しました。15のイベントタイプにまたがる84のHook、43のSkill、19のエージェント、30以上のライブラリモジュールで構成されています。このシステムはClawsの5つの機能（オーケストレーション、スケジューリング、コンテキスト管理、ツールルーティング、品質保証）にきれいに対応し、1つの注目すべきギャップ（宣言的ワークフロー定義）があります。主要な発見として、計画と実行の分離が、設計目標としてではなくHookベースのオーケストレーションの自然な性質として浮上しました。「判断と抽象化がコアであり続け、AIが実装を自動化する」というLattnerの観察は、Hookアーキテクチャに直接対応します。ガバナンスHookが判断を行使し、自動化Hookが実装を実行するのです。

Clawsの分類体系

Karpathyの説明では、Claws層が果たす5つの機能を特定しています。各機能には、過去2ヶ月間にClaude Code上で構築したHookシステムに直接対応するものがあります。¹

この分類体系が有用なのは、実践者が絡み合った形で構築しがちな関心事を分離してくれるからです。初期のHookはコンテキスト管理と品質保証を混在させていました。コスト追跡Hookは、予算コンテキストの注入（コンテキスト管理）と高額な操作のブロック（品質保証）の両方を行っていたのです。これらを別々のHookに分離したことで、各Hookが他方の機能を壊すことなく独立して失敗できるようになり、信頼性が向上しました。

システムの全体像

2026年2月時点の数値です。

イベントタイプごとのHook分布は、オーケストレーションの複雑さがどこに集中しているかを示しています。

UserPromptSubmitが最も負荷が大きいのは、すべてのユーザーメッセージで発火するためです。ディスパッチャー（prompt-dispatcher.sh）は、すべてのプロンプトに対して9つのHookを順次実行します。セキュリティフィルタリング、アナリティクス、使用状況追跡、システム監視、目標注入、時間見積もりのブロック、コンテキスト注入、メモリトピック注入、コンテキスト圧力の監視です。²

各Hookはレイテンシを追加します。9つの逐次Hookで、プロンプトあたり合計200msの実測値が加わります。ディスパッチャーがこれらを（並列ではなく）逐次実行するのは、初期のテストで共有JSON状態ファイルへの同時書き込みがデータ破損を引き起こしたためです。2つのHookがjiro.state.jsonに同時に書き込むと、切り詰められたJSONが生成され、下流のHookがすべて壊れました。逐次実行は遅いですが安全です。200msのオーバーヘッドはユーザーには見えません。ボトルネックは人間のタイピング速度であって、Hookのレイテンシではないからです。

成長の過程

成長は線形ではありませんでした。問題、解決、統合というサイクルのパターンをたどりました。

フェーズ1：単一目的のHook（1〜2週目）。 各Hookが1つの問題を解決しました。enforce-opus-model.shはOpus以外のモデルリクエストをブロックしました。no-time-estimates.shはレスポンスから工数見積もりを除去しました。filter-sensitive.shはツールコール内の認証情報を検出しました。これらのHookは独立して動作していました。どのHookも他のHookの存在を知りませんでした。

フェーズ2：調整の問題（3〜4週目）。 Hookが互いに干渉し始めました。認証情報フィルターが正当なAPI呼び出しをブロックしました。モデルエンフォーサーがサブエージェントのスポーンと競合しました。解決策はディスパッチャーです。単一のエントリーポイント（prompt-dispatcher.sh）が7つの個別UserPromptSubmit Hookを置き換え、実行順序を制御し、キャッシュされたstdinパイプを通じて状態を共有するようになりました。

フェーズ3：複合的な能力（5〜8週目）。 個別のHookが組み合わさってシステムになりました。品質ループは、pre-tool Hook（問題が起きる前に検出）とpost-tool Hook（起きた後に結果を検証）を、共有状態ファイル（jiro.state.json）を介して接続しました。審議システムは、再帰ガード、スポーン予算、合意プロトコルを使って、無限ループなしに複数のエージェントを調整しました。Ralph（自律開発ループ）は、PRDファイルの読み取りからClaudeのスポーン、テスト検証、コードレビューまでを1つのオーケストレーションされたパイプラインでつなぎました。

フェーズ4：自己認識（9週目以降）。 システムは、自分自身を理解するためのツールが必要なほど大きくなりました。Hookシステム全体のセマンティック検索（/find Skill）により、エージェントはファイル名ではなく目的でHookを発見できるようになりました。パフォーマンス監視（/perf Skill）は、システム自体のオーバーヘッドがマシンを劣化させていないかを追跡しました。コンテキスト圧力モニターは、オーケストレーション層が注入するコンテキストがモデルのコンテキストウィンドウを過剰に消費しているときに警告を出しました。

単一目的のHookから自己監視インフラへという進み方は、Chris LattnerがClaude C Compilerプロジェクトのレビューで指摘したパターンと重なります。「優れたソフトウェアは判断力、コミュニケーション、明確な抽象化に依存します。AIはこれを増幅させました。」³ Hookシステムのアーキテクチャは同じ真実を映し出しています。価値のあるHookは、タスクを自動化するものではありません。価値のあるHookは、タスクをいつ、どのように自動化すべきかについての判断をエンコードするものです。

判断Hook vs. 自動化Hook

LattnerによるClaude C Compilerのレビューは、AIがうまく自動化するもの（実装）と、根本的に人間に残るもの（判断と抽象化）を区別しました。³ この区別はHookシステムに直接対応します。

判断Hookは、何かが起こるべきかどうかを決めます。手順ではなく、ポリシーをエンコードします。

自動化Hookは、あらかじめ決められたアクションを実行します。ポリシーではなく、手順をエンコードします。

判断Hookは書くのが難しく、テストも難しく、そしてより価値があります。quality-gate.shには、7つの名前付き失敗モード、6つのエビデンス基準、そして曖昧表現の検出器が必要でした。inject-context.shは5行のbashで済みました。しかし両方とも必要です。自動化Hookは、判断Hookが評価するデータを供給します。sysmon-snapshot.sh（自動化）がパフォーマンスモニターにデータを送り、そのモニターがエージェント数のスロットリングを推奨するかどうかを決めます（判断）。

比率が重要です。健全なオーケストレーション層では、判断Hookが自動化Hookを上回るべきです。ほとんどのHookがデータ注入やメトリクス記録だけであれば、システムはうまく自動化しますが、ガバナンスは不十分になります。現在のシステムの検証済みの数は、判断Hookが35、自動化Hookが44、おおよそ4対5です。まだ自動化がリードしています。この比率は約1対6（ほぼすべてが注入とロギングのHook）から始まり、純粋な自動化では防げなかった障害に遭遇するたびにガバナンス制約が追加され、2ヶ月かけて判断側にシフトしました。比率はまだ均衡に達していませんが、それ自体が有用なシグナルです。このシステムは、自動化する量ほどにはまだガバナンスできていないのです。

計画と実行の分離

Boris Taneの「How I use Claude Code」という記事は、計画と実行を分離するというワークフローパターンを説明して、Hacker Newsで936ポイントを集めました。⁴ 1つのClaudeセッションで計画し（調査、アウトライン作成、設計）、計画を構造化された入力として受け取る新しいセッションで実行します。このパターンが共感を呼んだのは、現実の問題を解いているからです。計画と実行はコンテキストウィンドウのスペースを奪い合います。

Hookシステムは別の経路で同じ分離に到達しました。審議システムは、アプローチを調査し議論するために特化型エージェントをスポーンします。出力は、ストーリー、受け入れ基準、検証タイプを含む構造化されたPRD（プロダクト要件定義書）です。RalphループはPRDを読み取り、各ストーリーを実装するために新しいClaudeインスタンスをスポーンします。計画エージェントは決して実装しません。実装エージェントは決して計画しません。

この分離は設計目標ではありませんでした。2つの独立した制約から生まれたものです。

1. コンテキストウィンドウの圧力。 計画には多くのファイルを読み、選択肢を探索する必要があります。実装には現在のタスクに集中したコンテキストが必要です。両方を同じコンテキストウィンドウに入れると、どちらも十分なスペースを得られません。セッションを分ければ、各フェーズがフルのコンテキストを使えます。

2. 品質検証の独立性。 同じエージェントが計画と実装を行うと、計画に照らして自分の実装を客観的に検証できません。計画とコードだけを持つ新しいエージェントが、独立した検証を提供します。Ralphループはこれを強制しています。実装エージェントがテストを実行しますが、3つの別々のレビューエージェント（正確性、セキュリティ、規約）が結果を検証します。

Taneの手動ワークフローと自動化されたHookシステムの収束は、計画と実行の分離が単なる実践者の好みではなく、エージェント的なシステムの自然な性質であることを示唆しています。コンテキストウィンドウを管理し、出力を検証するシステムは、いずれ計画と実行を分離します。両方を1つのコンテキストで行うという代替案は、どちらのフェーズでもより悪い結果を生むからです。

Hookシステムが失敗するところ

このアーキテクチャには、専用に設計されたオーケストレーションフレームワークであれば解決できる重大な弱点が3つあります。

宣言的なワークフロー定義がありません。 すべてのワークフローがbashスクリプトに命令的にエンコードされています。Ralphループは1,320行のbashで、特定のシーケンスをエンコードしています。PRDの読み取り、ストーリーの選択、コンテキストの収集、Claudeのスポーン、テストの実行、レビューの実行、失敗の処理、状態の更新です。ワークフローを変えるにはbashを編集しなければなりません。宣言的なシステムであれば、ワークフローをインタープリターが実行するデータ（YAML、JSON）として定義できます。宣言的ワークフローは変更、合成、可視化が容易です。命令的スクリプトは最初こそ書きやすいものの、成長するにつれて保守が難しくなります。

Hookの順序が脆弱です。 プロンプトディスパッチャーはHookをハードコードされた順序で実行します。memory-capsule-inject.shをinject-context.shの前に動かすと、カプセルの注入が壊れます。inject-context.shが解決するセッションIDに依存しているからです。これらの依存関係は暗黙的（ディスパッチャーの順序としてエンコード）であり、明示的（Hook間の依存として宣言）ではありません。専用に設計されたシステムであれば、Hookの依存関係をDAGとして表現し、実行順序をトポロジカルソートで決められます。

ワークフローの可視化がありません。 84のHookがある状態で、あるユーザー操作の完全な実行パスを理解するには、ディスパッチャーのコードを読み、Hookチェーンを手でたどる必要があります。「ユーザーがメッセージを入力すると、これら9つのHookがこの順序で発火し、Hook 3がライブラリ関数Xを呼び出し、状態ファイルYに書き込む」と示してくれるツールはありません。このシステムはログを通じては観測できますが、構造を通じては観測できません。専用に設計されたオーケストレーションフレームワークであれば、Hookの依存関係、データフロー、実行パスを視覚的なグラフとして提供するでしょう。

これらの弱点には共通の原因があります。このシステムは、一貫したオーケストレーション層として設計されたのではなく、個別の問題を解決することから有機的に成長した、ということです。有機的な成長は、動くシステム（84のHookはすべてプロダクションで正しく機能しています）を生みますが、全体として推論するのは困難です。トレードオフは現実のものです。オーケストレーション層を事前に設計していれば、より良い構造は得られたでしょうが、機能はより貧しくなっていたはずです。多くの機能（メモリカプセル、出力ホワイトリスト、スポーン予算）は、起きる前には予測できなかった障害への対応として発明されたものだからです。

Harnessが主流になる

Karpathyがこの層に名前を与えてから3週間で、この概念は2つ目の名前と、成長するコミュニティを手に入れました。

Geoffrey Huntleyは形式的な定義を提案しました。「Agent Harnessとは、言語モデルを取り巻くオーケストレーション層であり、モデルをツールからチームメイトへと変えるものです。」⁵ この言い方は正確です。harnessはモデルではありません。モデルが呼び出すツールでもありません。どのツールを、いつ呼び出し、その呼び出しが成功したかをどう評価するかを決めるシステムのことです。あらゆる本番のエージェントシステムがこの層を構築しています。多くは暗黙のうちに、オーケストレーションのロジックとビジネスロジックが混ざったアプリケーションコードの中に構築しています。名前を与えることで、アーキテクチャが見えるようになるのです。

コミュニティのシグナルは、このパターンが広がっていることを裏づけています。Pieter Levelsは、Claude Codeをサーバー上で動かす運用に恒久的に切り替え、ローカルのツールではなくインフラとして扱っていると報告しました。⁶ AnthropicはRemote Controlを出荷し、ターミナルでタスクを開始してClaude.aiで引き継げるようにしました。⁷ Ben Cherny は/simplifyと/batchをファーストパーティのSkillとして発表しました。⁸ いずれもharnessの機能です。永続的な実行、リモートのオーケストレーション、組み込みの能力モジュールです。CLIがharnessへと育っています。

その一方で、実践者たちは自分のharnessコンポーネントを作っています。ある開発者は、個人用オペレーティングシステムのためにObsidian + Claude Codeのカスタムコマンド22個を公開しました。⁹ 別の開発者は、補完的なスラッシュコマンドを備えた「Visual Explainer」エージェントSkillを作りました。¹⁰ パターンは一致します。ディスパッチャー、Skill、共有状態、イベント駆動のHookです。こうしたシステムを作る前にフレームワークのガイドを読む人はいません。1つの問題を解き、次にもう1つ、そして問題同士が干渉し合う問題を解くのです。

最近の2つのプロジェクトは、コミュニティ製のharnessコンポーネントがどれほど洗練されてきたかを示しています。nahは、PreToolUse Hookとして登録されるコンテキスト認識型のパーミッションガードです。¹⁴ 20種類の異なるアクションタイプ（ファイル書き込み、ネットワークリクエスト、プロセス生成など）を分類し、タイプごとのポリシーを適用します。このツールは、エージェントが無害なコマンドを連鎖させてブロック対象の操作を達成しようとするパイプ分解攻撃も検出します。そのアーキテクチャは、本記事のfilter-sensitive.shやrecursion-guard.shと重なります。同じガバナンスの問題を解こうとした別の実践者が、独立にたどり着いたのです。

Rudelは、Claude CodeのセッションデータをClickHouseに取り込むことでセッション分析を提供します。¹⁵ 1,573セッションの分析から、Skillを呼び出すユーザーはわずか4%で、26%のセッションが60秒以内に放棄されていることが分かりました。この数値は、harnessのアーキテクチャが示唆することを裏づけています。ほとんどのユーザーはエージェントCLIを表層のレベルで使っているのです。本記事で述べたオーケストレーション層は、大多数が浅い側から出ることのない利用分布の、深い側の端にあたります。ツールにできることと、ほとんどのユーザーが実際に頼むことの間にある隔たりこそ、harnessインフラが埋める空間です。

Autoresearch：研究ループとしてのharness

Karpathy自身のautoresearchプロジェクトは、別の領域でharnessのパターンを実演しています。¹¹ このシステムは、言語モデルを学習スクリプト（train.py）に向け、5分間の実験を実行し、結果を固定の指標（検証bits per byte）で評価して、改善なら残し、劣化なら破棄します。2日間でおよそ700回の実験を走らせ、およそ20件の本物の改善を見つけ、GPT-2の学習時間を11%短縮しました。

そのアーキテクチャは、ここまで述べてきたHookシステムと同一です。固定の評価ハーネス（prepare.py）は判断Hookに相当します。実験が成功したかどうかを決めるからです。学習スクリプト（train.py）は自動化Hookに相当します。エージェントの変更を実行するからです。gitブランチの管理（改善なら維持、劣化ならリセット）は、Ralphループの状態管理に相当します。results.tsvのログは、セッションのテレメトリに相当します。

このパターンが移植できるのは、harnessが領域に依存しない問題を解いているからです。エージェントがコードを書くにせよ、学習ループを最適化するにせよ、コンテンツパイプラインを管理するにせよ、必要なものは同じです。結果を基準に照らして評価する手段、変更を残すか破棄するかを決める手段、反復をまたいで状態を維持する手段、そして人間の介入なしに自律実行する手段です。この4つの要件が、エージェントが実際に何をしているかに関わらず同じアーキテクチャを生み出します。

Shopify CEOのTobi Lütkeは、autoresearchを社内向けに応用しました。エージェントが最適化した小さいモデルが、人手で構成した大きいモデルを上回り、自律的なharness駆動の反復が人間の思いつかない構成を発見するという主張を裏づけました。¹²

Harnessに空いたセキュリティの穴

harnessはオーケストレーションを解きます。安全性を自動的に解いてくれるわけではありません。

LLM駆動の反復的なコード改良に関する研究では、10ラウンドのエージェント修正を経た反復チェーンの43.7%が、出発点となったベースラインのコードよりも多くの脆弱性を含むようになったことが分かりました。¹³ 根本原因は仕様のドリフトでした。エージェントが機能的な正しさを最適化するにつれて、防御的なロジックを段階的に削り、例外処理を弱めていったのです。さらに悪いことに、静的解析のセキュリティツール（SASTゲート）を反復ループに追加すると、潜在的な劣化はむしろ12.5%から20.8%へ増えました。スキャナーが偽りの安心感を生み、エージェントをより慎重にではなく、より不注意にしてしまったのです。

この劣化の発見は、harnessの設計に直接関わります。本記事で述べた判断Hook（quality-gate.sh、filter-sensitive.sh、recursion-guard.sh）は、自動化だけでは劣化してしまう品質と安全性の次元を扱っています。この劣化問題に取り組んだSCAFFOLD-CEGISフレームワークは、4層のゲート付き検証を用い、潜在的劣化率2.1%と安全性の単調性100%を達成しました。¹³ そのアーキテクチャはHookシステムと並行しています。評価の層を分け、それぞれが異なる性質をチェックし、フェーズの間に明示的なゲートを置くのです。

別の取り組みが、この脅威モデルを本番側から裏づけています。AIエージェントのセキュリティに関するPerplexityのNIST回答は、大規模に稼働するエージェント的システムの攻撃面をマッピングしました。¹⁶ 主要なベクターは、データチャネル（Webページ、メール、ツール出力）を通じた間接プロンプトインジェクション、エージェント特有のCIAトライアド違反（ツールコール経由のデータ流出、コンテキスト汚染による行動操作、再帰的スポーンによるリソース枯渇）、そしてエージェント周辺システムの実在するCVEです。彼らが推奨する防御アーキテクチャ（入力レベルのフィルタリング、モデルレベルのアラインメント、サンドボックスと許可リストによる決定論的な強制）は、ここで述べたHookシステムに有機的に現れた3層のパターンと重なります。自動化Hookが入力をフィルタし、モデルが判断を行い、ガバナンスHookがモデルには覆せない決定論的な制約を強制するのです。

実践者への教訓はこうです。harnessが統治せずに自動化とオーケストレーションだけを行うなら、反復的なエージェント実行は、標準的なツールでは検出できないセキュリティの後退を持ち込みます。判断Hookはオーバーヘッドではありません。システムが劣化しない理由そのものです。

更新、9月3日：現実世界に現れた失敗モード

本記事が「Harnessに空いたセキュリティの穴」で述べたギャップに、記録された犠牲者が現れました。2026年7月19日、Claude Code v2.1.204が、Mythic SocietyのBengaluru Inscriptions 3D Digital Conservation Projectの名誉ディレクターであるUdaya Kumar P L氏のコンピューターでキャッシュを消去していたとき、本人の説明によれば「AIが生成したコマンドのクォートの誤りが、その指示を『すべて削除せよ』に変えてしまいました」。harnessの設計にとって重要なのは、その次に起きたことです。「それが状況を理解してプロセスを終了させようとしたとき、その安全システムが終了をブロックしました。二度もです […] 安全層は破壊のほうを許したのです。」氏は4分後にマシンをシャットダウンしました。失われたのは、4つか5つのプログラムと、10年かけて集めた碑文、英雄石、寺院、貨幣のオリジナル写真であり、プロジェクトの記録の約15%にあたります。そこには、Hebbalという名の初期形を刻んだ石（西暦750年）も含まれていました。NASのコピーは残り、ドライブは残りませんでした。Societyは2台目のNASとオフサイトのテープに15ラークルピーを支出し、ボランティアが約120か所の遺跡を再スキャンする予定です。1ヶ月以上経っても、Anthropicの誰からも連絡はありませんでした。¹⁷

この説明のうち3点が、これまでの議論と一致します。破壊的なステップはモデルの判断ではなく、生成されたコマンドにおけるシェルのクォート処理の失敗でした。まさにPreToolUseの判断Hookが捕まえるために存在するクラスのものです。記事はパーミッションモードを明記しておらず、そのコマンドをレビューしたファーストパーティの記録は残っていません。auto modeであっても、分類器はデフォルトでは任意コード実行のパターンに一致するシェルコマンドしかレビューしません。氏はエージェントがサンドボックスを突破したとも述べていますが、記事はその種類について詳細を示していません。Anthropicは隣接するケースに対するガードをすでに出荷していました。7月8日にリリースされたv2.1.205で、コンテキストから解決できない変数に対してrm -rfを実行する前に確認するよう、auto modeが変更されたのです。当該マシンはv2.1.204でした。¹⁹ そして安全層は、逆方向に仕事をしました。エージェント自身の是正措置のほうを危険な操作として扱ったのです。そして残ったものが残ったのは、harnessの完全に外側にある唯一のコントロール、すなわちバックアップのおかげでした。残りは手作業で再スキャンされます。この種の出来事について、少なくとも非公式の記録簿は今や存在します。公式のものは存在しないと氏は指摘していました。I Have Been Clawedは、エージェントとチャットボットのインシデントをソースへのリンク付きで集め、それぞれに教訓を添えたアーカイブで、執筆時点で58件、うち7件がClaude Codeです。トップページには正直な注意書きがあり、エントリーは自己申告であり拡散度に偏るため、ツールごとの件数は安全性ではなく報告文化を測るものだと述べています。今回の件より前にも、同じ形のClaude Codeのエントリーがすでに3件ありました。WSLのホームディレクトリからユーザー所有のファイルを削除した再帰的コマンド（2025年10月21日）、ホームディレクトリを削除にさらしたリテラルのチルダディレクトリ（2025年11月28日）、そしてホームパスで終わるクリーンアップコマンドがMacを消去した件（2025年12月7日）です。現実の世界では、これは1つの物語ではなくパターンなのです。¹⁸

実践者が持ち帰るべきこと

エージェントCLIの上にオーケストレーション層を構築しているなら（Claude Codeガイドから始めるにせよ、ゼロから始めるにせよ）、このシステムから3つのパターンが直接移植できます。

個別のHookではなく、ディスパッチャーから始めてください。 最大のアーキテクチャ上の改善は、7つの個別UserPromptSubmit Hookを、それらを順次実行する単一のディスパッチャーに置き換えたことでした。いずれかのイベントタイプでHookが3つを超えると見込まれるなら、先にディスパッチャーを作ってください。ディスパッチャーの作成に費やす30分が、後のHook相互作用バグのデバッグに費やす数時間を節約します。最小限のパターンは次のとおりです。

#!/bin/bash
# dispatcher.sh — sequential hook execution with shared stdin
HANDLERS=("inject-context.sh" "track-usage.sh" "quality-gate.sh")
HOOK_DIR="$(dirname "$0")/handlers"
INPUT=$(cat)  # Cache stdin once (each handler gets the same input)

for handler in "${HANDLERS[@]}"; do
    [ -x "$HOOK_DIR/$handler" ] && echo "$INPUT" | "$HOOK_DIR/$handler"
done

この単一のディスパッチャーをHookのエントリーポイントとして登録します。ハンドラーは作るたびに配列へ追加していきます。各ハンドラーは同じキャッシュされたstdin（Hookイベントのペイロード）を読み取り、独立してstdoutに書き込みます。

判断と自動化を早い段階で分離してください。 新しいHookを書くときは、「このHookは何かが起こるべきかどうかを決めるのか、それともあらかじめ決められたアクションを実行するのか」と問いかけてください。判断Hookには、より多くのテスト、より多くのエッジケース処理、より多くの反復が必要です。自動化Hookに必要なのは信頼性とパフォーマンスです。両者を同じように扱うと、テストの足りない判断Hookと、過剰に作り込まれた自動化Hookが生まれます。

計画と実行の分離は、自然に立ち上がるのを待ってください。 初日から分離を強制しないでください。動く最もシンプルなものを作ってください。エージェントのコンテキストウィンドウが計画と実装の両方には一杯すぎると気づいたら、分割してください。エージェントが自分の仕事を客観的に検証できないと気づいたら、独立したレビューエージェントを追加してください。制約がそれを要求するとき、分離は自明に感じられるはずです。

harnessが主流になりつつあるのは、このパターンが不可避だからです。この層をClawsと呼ぶか、Agent Harnessと呼ぶか、単に「自分のhooksフォルダ」と呼ぶかにかかわらず、エージェントを目標に向けて調整するシステムはすべて同じアーキテクチャに収束します。順序づけのためのディスパッチャー、ガバナンスのための判断Hook、実行のための自動化Hook、そして継続性のための状態ファイルです。Claude Codeのソースリークは、Anthropic自身の内部アーキテクチャもこれと同じパターンに従っていることを裏づけました。コーディネーターモードは、コードレベルのオーケストレーションではなく、完全にシステムプロンプトの指示として実装されていたのです。Hookベースのアプローチには、専用に設計されたオーケストレーションフレームワークに対する利点が1つあります。コミットメントがゼロであることです。すべてのHookは独立しています。1つのHook、10のHook、あるいは84のHookを採用できます。（ディスパッチャーを維持している限り）どのHookも他を壊さずに削除できます。学ぶべきフレームワークも、管理すべき依存関係も、運用すべきランタイムもありません。オーケストレーション層は、ただのファイルなのです。

よくある質問

agent harness、あるいは「Claws」層とは何ですか？

Claws層（2026年2月にAndrej Karpathyが命名）とは、エージェントCLIの上に構築され、それをツールからチームメイトへと変えるオーケストレーションシステムのことです。¹ 5つの機能を果たします。オーケストレーション（複数エージェントの調整）、スケジューリング（タスクの実行タイミングの決定）、コンテキスト管理（ターンをまたぐ関連情報の維持）、ツールルーティング（ツールコールを適切なハンドラーへ振り分けること）、そして品質保証（出力が基準を満たしているかの検証）です。Geoffrey Huntleyはこの定義を「言語モデルを取り巻くオーケストレーション層」として形式化しました。⁵

Claude CodeのPreToolUse Hookはどのように動きますか？

PreToolUse Hookは、すべてのツールコール（Bashコマンド、ファイル書き込み、ファイル編集、サブエージェントのスポーン）の前に発火し、ツールコールのペイロードをJSONとしてstdinで受け取ります。Hookスクリプトはペイロードを評価し、許可、拒否、変更のいずれかの決定を返します。モデルはHookをスキップすることも、上書きすることも、交渉することもできません。Hookはプロンプトのレベルではなく、インフラのレベルで実行されるからです。² ディスパッチャーのパターンでは、各イベントで複数のHookを順次実行し、stdinをキャッシュしたパイプによってすべてのハンドラーが同じ入力を受け取ります。

判断Hookと自動化Hookの違いは何ですか？

判断Hookは何かが起こるべきかどうかを決め（ポリシー）、自動化Hookはあらかじめ決められたアクションを実行します（手順）。判断Hookには品質ゲート、認証情報フィルター、再帰ガード、コストゲートなどがあります。自動化Hookにはコンテキスト注入、使用状況追跡、システム監視、ハートビートなどがあります。³ 比率が重要です。自動化Hookばかりのシステムは、うまく自動化しますがガバナンスは不十分です。現在のシステムは判断Hook 35に対して自動化Hook 44で、純粋な自動化では防げないものを障害が明らかにするたびにガバナンス側へシフトしています。

なぜエージェントシステムでは計画と実行の分離が自然に生まれるのですか？

2つの独立した制約が分離を強います。第一に、計画には多くのファイルを読み選択肢を探索することが必要で、実装には現在のタスクに集中したコンテキストが必要であり、両方を同じコンテキストウィンドウに入れるとどちらも十分なスペースを得られません。第二に、同じエージェントが計画と実装を行うと、計画に照らして自分の仕事を客観的に検証できません。⁴ コンテキストウィンドウを管理し、出力を検証するシステムは、いずれ計画と実行を分離します。代替案はどちらのフェーズでもより悪い結果を生むからです。

自分のHookシステムを作り始めるにはどうすればよいですか？

個別のHookではなく、ディスパッチャーから始めてください。いずれかのイベントタイプでHookが3つを超えると見込まれるなら、配列からハンドラーを順次実行する単一のディスパッチャーを作ってください。ディスパッチャーの作成に費やす30分が、後のHook相互作用バグのデバッグに費やす数時間を節約します。「このHookは何かが起こるべきかどうかを決めるのか、それともあらかじめ決められたアクションを実行するのか」と問うことで、判断と自動化を早い段階で分離してください。まずはClaude Code Hookチュートリアルから始め、システム全体を最初から設計するのではなく、実際の失敗が要求するのに応じてHookを追加していきましょう。

出典