HarnessScope

HarnessScope

エージェントハーネスのターン単位のガバナンス可観測性。 HarnessScope は、エージェントハーネスがすでに書き出しているトランスクリプトを読み取り、各ターンをワークスペース独自の運用ルール（コードを書く前の計画、完了前の検証、コンテキスト予算、パス境界など）に照らして評価します。また、各セッションがガバナンス構造をどのようにたどったかを、違反だけでなく合格も含めて示すローカルビューアーを提供します。

上記のすべての画面は hscope demo によるものです。ローカルで生成された合成コーパスを使用しています。実際のトランスクリプトにはプロンプト全文が含まれるため、デモ素材として使用されることはありません。

---

判明したこと

セッションとは、1つのモデルが自分自身と対話するものではありません。サブエージェントを起動し、親エージェントが使っていないモデル上でサブエージェントが動作し、ストリーミング応答では同じリクエストが複数回書き込まれます。この構造を単純に読み取ると、数値が誤ります。以下は、このプロジェクト独自のトランスクリプトを使ってそれぞれ計測した修正点です。

単純に読み取った場合	実際のところ	理由
再読み込みによる無駄	その42%は誤りでした	親エージェントが読んだファイルをサブエージェントが読んでも、再読み込みではありません。サブエージェントはそのトークンをそもそも持っていなかったからです。無駄はセッション単位ではなく、コンテキストウィンドウ（agent_id）単位で計上されます。
出力トークン数 90,957,147	32,348,242（2.8倍の過大計上）	ストリーミング応答では、1つのrequestIdにつき複数の使用記録が書き込まれます。最後の記録を数えます。先に記録されたものは途中経過です（2に対し、完了した応答では31,979）。
3,121ターン	2,438（28%の水増し）	1ターンとは1つのユーザープロンプト（promptId）です。中断通知、<command-name>のエコー、<bash-input>ブロックもユーザー記録として扱われます。
安定した形式	1か月で29種類のハーネスバージョン	トランスクリプト形式は文書化されておらず、変化します。そのため、hscope doctorは誤った数値をひそかに出力するのではなく、はっきりと失敗し、問題を起こしたバージョンを示します。
それでも残っていた再読み込みによる無駄	その81%も誤りでした	(context, path)をキーにすると、大きなファイルのページング（offset=501）と二度読みは区別できません。しかも、新しいチャンクごとに、そのコンテキストがすでに保持しているトークンが再度課金されていました。854,334トークンのうち692,292トークンです。現在はキーに範囲も含まれます。

最も重要なのは最後の行です。これは最も新しく見つかった問題でもあります。v0.1.3のリリース後に、このツールを自分自身のワークスペースに向けて実行し、その回答を読んだことで発見しました。最初の行と同じ種類の誤りが、もう1段深いところで、独自のテストをすでに通過していたコードに潜んでいました。ガバナンスの失敗を検知すると謳うツールは、自分自身に対しても機能しなければなりません。そこで、これを現在の標準的な使い方にしました。そして次に判明したことは、さらに深刻でした。

この問題により、3つのルールがデフォルトで無効になりました。R1（インデックス優先）、R2（インライン優先）、R6（承認ゲート）は、意味上の問い、つまり「これはドメインに関する質問か」「このファンアウトは妥当だったか」「このコードはその計画の対象か」を尋ねるルールですが、構文上のテストで答えていました。プロンプトに特定のキーワードがあるか、プロンプトの文字数、プロジェクトフォルダーなどです。実際のセッションと照らして計測すると、R2の違反の84%は、主な役割がファンアウトであるコマンドを呼び出すターンでした。これは調整が必要な閾値ではありません。概念を追跡できない代替指標を調整しても、その概念を追跡できるようにはなりません。これらのルールは現在、計測した誤検知率をそれぞれ示したうえで、無効な状態で提供されています（precisionはルールの第一級フィールドであり、モデルとrule_healthに表示され、ホバー可能なバッジとしても表示されます）。重要なのは無効にすることではありません。無効にしたうえで、その理由と数値を示すことです。ルールを黙って有効な状態で提供すれば、ガバナンス画面は誰にも信頼されないノイズになります。このプロジェクトが明らかにしようとしている失敗とは、それです。

R8も同じ理由で、コンプライアンス率の報告をやめました。仕組み上、その機会数は違反数と同じです。再読み込みカウンターでは、コンプライアンスに準拠した再読み込みを観測できません。そのため「コンプライアンス率0%」は所見ではなく、恒等式でした。告発のように聞こえるだけで、何も語らない数値です。現在は数量を報告し、比率は報告しません。

これらは1つのコーパスについての観察であり、ベンチマークではありません。皆さんの数値は異なります。重要なのは、これらの数値を読み取れることです。メトリクスは数量を把握し、請求書は金額を把握しますが、どちらも「サブエージェント」という言葉を理解するわけではありません。推論の全容はこちらです：docs/MULTI-AGENT.md。

HarnessScope との比較

HarnessScope が監視するのは、ほとんどの「LLM オブザーバビリティ」ツールとは異なるレイヤーです。計測を組み込んだアプリではなく、トランスクリプトから読み取る エージェントハーネス自体です。

ツール	監視対象	データの取得方法	実行場所
HarnessScope (hscope)	Claude Code セッションのガバナンス準拠状況とトークンの流れを、ターンごとに監視	トランスクリプト JSONL を読み取ります。事後に読み取る方法と、ハーネスが追記する内容をリアルタイムで読み取る方法（--watch）があります。計測は不要で、セッションへのフックもありません	ローカル、LLM は内部で使用しません
ccusage などの CLI	同じトランスクリプトからトークン数とコストの合計を取得	トランスクリプト JSONL を読み取ります	ローカル
LangSmith／Langfuse	アプリケーションが実行する LLM 呼び出しのトレース	自分で記述する SDK 計測	SaaS（Langfuse はセルフホストにも対応）
Arize Phoenix（OpenInference）	計測を組み込んだ LLM アプリの OTel トレース	OTel SDK による計測	ローカル／セルフホスト
Claude Code /cost、OTel メトリクス	現在のセッションの使用額、集計カウンター	ハーネス内	ハーネス内

他のツールが扱っていないのは、「セッションがワークスペースの運用ルールに従ったかどうか」です。コードを書く前に計画すること、完了前に検証すること、パスの境界、コンテキスト予算などです。コストツールはセッションで何に費用がかかったかを示し、トレースツールはアプリの LLM 呼び出しが何をしたかを示します。HarnessScope は、エージェントがワークスペースで定められた作業方法に従ったかどうかを示します。

試してみましょう — 30 秒で、データは一切不要

pipx install hscope        # or: pip install hscope · npx -y hscope  (Python 3.11+ either way)
hscope demo --serve        # synthetic corpus → ingest → judge → viewer

作成した 3 つのセッションを用意しています。準拠したセッション、無駄の多いセッション（再読み込み、不要なコンテキスト、境界外の読み取り、検証なしの完了宣言）、ファンアウトを行うセッション（サブエージェントが 2 つあり、片方は読み取った内容を引用し、もう片方は引用しません。バックグラウンドで起動したものもあり、ホスト外の MCP との往復もあります）。

このコーパスにも実データと同じ基準を適用しています。hscope doctor を通過する必要があるため、パーサーが想定していない形式を生成するコードは、不変条件によって検出されます。この検証にはすでに 2 回合格しています。セッション間で requestId が再利用されていたケース（hscope はこれを、フォークによって再生された 1 回の API 呼び出しとして正しく読み取りました）と、パーサーの正規表現が丸ごと取り込んでしまう、余分な空白の付いた agentId: があったケースです。

次に、自分のセッションを指定します

hscope                     # scan ~/.claude/projects → ingest → judge → check → open the viewer

フラグも設定ファイルも不要です。次の 2 点は間違えません。

• ポートは決め打ちせずに検出します。 8000 は妥当なデフォルトですが、一部の Windows マシンでは予約済みの範囲です（WinError 10013）。初回に表示されるのがスタックトレースでは、よい印象にはなりません。
• トランスクリプトには保存期限があることを伝えます。 ハーネスは約 30 日後にトランスクリプトを削除し、永続化するには取り込みが必要です。それより長い間隔でしか取り込まないと、セッションは気付かないうちに失われます。一度も取り込まれなかったセッションは、そもそも存在しなかったセッションと区別できません。初回実行時に、最も古いトランスクリプトの経過日数と、推奨する取り込み頻度が表示されます。

また、どのルールで判定するかも明示します。中立的なプリセットを使うのか、ディスク上で見つかったワークスペースモデルを使うのかを示します。モデルを適用しながら黙って「プリセット」と称するのは、何も知らせずにフォールバックするのと同じ嘘になります。

すべてが ローカルファーストです。トランスクリプトデータがマシンの外に出ることはありません（唯一の例外はオプトインの Tier B LLM ジャッジですが、デフォルトでは無効で、セッションごとに明示的にクリックした場合にのみ実行されます）。このツールがプロジェクト、.mcp.json、ハーネスの設定を書き換えることはありません。ガバナンスを監視するツールが、監視対象の環境を作り変えてはなりません。

ライブで監視 — 監視だけ

hscope --watch             # the circuit stays live: sessions are re-ingested and re-judged as they run

セッションの進行中、ハーネスはトランスクリプトに追記していきます。そのため、ライブ表示に必要なデータは以前から揃っていました。足りなかったのは監視ループです。--watch は 2 秒ごとに更新時刻を確認し、変更のあったファイルだけをハッシュ化します（更新時刻がきっかけとなり、判定には引き続きハッシュを使います）。そのセッションだけを再判定し、ビューアーが自動で更新されます。何も変更されていない間は、解析もハッシュ化も表示も行われません。

監視はしますが、介入はしません。 セッションにはフックを一切インストールしません。何もブロックされず、画面に違反が表示されても、対応するのはあくまで 人間 です。ブロックするには PreToolUse フックが必要になります。そうすると、上記の「セッションにフックを挿入しない」という行が偽りになり、ツールが特定のハーネスに縛られ、誤判定で作業が止まることになります（事後判定なら、誤りは誤ったバッジで済みます。ライブでは、作業の手が止まります）。5k トークンではなく 40k トークンのリードループやファンアウトを確認できることには価値がありますが、そのためにツールがブレーキを握る必要はありません。

実行中のターンは表示しますが、判定しません。 判定すると、hscope 自身のルールに反します。検証ゲートのルールが、まさにチェックを実行しようとしているターンで発火し、3 秒後に覆る判定になってしまいます。また、ストリーミング応答のトークン使用量は、最後のレコードが届くまで確定しません。そのため、ライブターンには 進行中 · 未判定 バッジが表示され、判定はターン終了後に表示されます。判定の保留が判定のスキップになってはいけません。そのターンを中断すると、ファイルへの追記は止まりますが、hscope はいつまでも保留にせず、稼働状態のウィンドウが過ぎた時点で判定します。

得られるもの

ハーネス回路

1 ターンを、固定トポロジーの模式図として表示します。コンテキストソース → エージェント → アクションサーフェス → ガバナンス出力。サブエージェントは起動エッジ と 戻りエッジを持つノードとして示され、戻ってきた内容がラベル付けされます。これはサブエージェントが消費した内容とは異なります（実際のあるターンでは、3 つのエージェントが出力トークンを 16.5k／6.3k／5.3k 消費し、親に 1.5k／2.2k／2.0k を返しました）。ホスト外への MCP ホップと書き込み可能なサーバーは、接続線上に表示されます。

セッションリプレイ

ターンのタイムラインです。コンテキストに読み込まれた内容、実行されたツール、各ターンのルール判定を表示します。合格したものも含まれます。違反だけを一覧にするガバナンスビューでは、「準拠している」と「一度もチェックされていない」を区別できません。

ルールの健全性

ルールごとの準拠率 × カバレッジです。評価可能な 3 ターンで準拠率 100% のルールは、300 ターンで 100% のルールと同じではありません。また、評価できないルールはスコアを付けず、その旨を報告します。

トークン／ループ

ターンごとのトークン消費量とロスのピンポイントマーカーを表示します。リード、使われなかったコンテキスト（読み込まれたものの、引用されなかった内容）、エラーの連鎖、キャッシュウィンドウの浪費を、そのコストを実際に負担したターンとコンテキストウィンドウに紐付けます。

セットアップ

登録したすべてのフック、MCP サーバー、スキル、サブエージェントを、トランスクリプト上で実際に呼び出された内容と並べて表示します。active／unused／unregistered-call。登録は申告であり、証拠はトランスクリプトです。（ここにスクリーンショットがないのは意図的です。この画面は あなたの マシンの設定を読み取るため、画面を撮影すれば誰かの実際のワークスペースが写ってしまいます。）

書かなくてよかったルール

ツールを試すためのルールを人が手書きする必要はありません。初回実行時にワークスペースモデルが見つからない場合、リポジトリの構成からモデルを生成し、すでに使っている LLM 向けのページを用意します。

hscope                   # ...with no rules of your own, writes ~/.hscope/<id>/HSCOPE-SETUP.md
hscope mcp --install     # prints an MCP snippet; paste it into .mcp.json
hscope setup             # regenerate the page whenever your canon moves

HSCOPE-SETUP.md は、2 種類の読者を想定しています。あなた向けには、hscope が見つけた規範、フック、MCP サーバー、スキル、サブエージェントと、まだどのルールからも参照されていない規範の条項をまとめています。LLM 向けには、get_setup_guide → suggest_rules → set_rule を呼び出してルールを作成する手順を記載しています。承認するのはあなた、下書きするのは LLM です。

一連の作業は手動操作 3 回だけです。hscope を実行し、スニペットを貼り付け、ページを渡します。スニペットには HSCOPE_MCP_WRITE=1 が含まれているため、貼り付けることがそのまま書き込みへの同意となり、追加の操作は不要です。また、hscope が .mcp.json 自体を編集することはありません。

オンボーディングは本当に機能しましたか？

hscope onboard      # read-only, idempotent; exit 1 while incomplete

観測された 6 つのステージと判定結果です。hscope は実行のたびに最後にこれを表示するため、コマンドの存在を知らなくても目にすることになります。

1  transcripts ingested             PASS   297 session(s), oldest 35d
       -> oldest is 35d and the harness deletes transcripts at ~30d -- ingest more often
2  hscope MCP registered            FAIL   not in your harness config
       -> run `hscope mcp --install` and paste the snippet it prints
3  workspace model exists           PASS   ~/.hscope/warp/workspace-model.json
4  the model governs your sessions  PASS   289 of 297 session(s)
5  the model is not empty           PASS   14 rule(s), 25 role(s)
6  your rules actually fire         PASS   10 of 10 enabled rule(s) had an opportunity

disabled, so not judged at all: R1, R2, R6, B1

INCOMPLETE -- next: step 2, hscope MCP registered

そのうち 4 つはチェックリストです。2 つは失敗しても表面化せず、それこそがこのコマンドの存在理由です。

• ステップ 4 — モデルがあなたのセッションを適切に管理している。 モデルがディスク上にあっても、workspace.roots に実際に作業しているパスが 1 つも含まれていないことがあります。その場合、hscope は中立プリセットで判定します。この確認項目が設けられるまでは、そのことを知らせていなかったため、実際にはルールが適用されていない画面に、自分のルール名が表示されているのを見ていたかもしれません。現在は、セッションが実際に実行された作業ディレクトリ（cwd）を表示します。
• ステップ 6 — ルールが実際に適用されている。 LLM が作成した 12 個のルールに、コーパス内で適用される機会が一度もないなら、それはオンボーディングではなく、何もないところに表示された緑のチェックマークです。適用機会がゼロのルールには、名前が表示されます。単に無効になっているルールは、適用されていないのではなくオフとして報告されます。この 2 つは異なる事実であり、混同するのは、このツールが見つけ出そうとしている種類の嘘です。

適用されていないルールは失敗ではなく、検出結果です。カバレッジがゼロでも、「まだ機会がなかった」という正直な結果である可能性があり、これを理由に確認項目を不合格にすれば、ルールを少なく書くほど有利になってしまいます。しかし、作成したルールが一度も適用されていない場合、確認項目は INCOMPLETE を返します。それは実質的な意味のない合格であり、hscope doctor はすでにトランスクリプトについてそのような報告を拒否しています。ここでも同じように、今度はセットアップに対して報告を拒否します。

ワークスペースモデル（任意ですが推奨）

モデルがない場合、HarnessScope は中立プリセットで動作します。ドメイン固有の値が空の汎用ルールを使用し、パスのラベルはファイル名にフォールバックし、セッションはフラットなリストとして表示されます。どのリポジトリでもクラッシュしないこと、それがドメインに依存しない設計の契約です。

モデル（~/.hscope/<workspace>/workspace-model.json）を使うと、1 つの JSON ドキュメントで、あなたのワークスペースがどのように管理されているかを宣言できます。

• rules[] — 独自のパラメーター（キーワード、しきい値、マーカー）を指定したルールの原型のインスタンス
• roles[] — 各パス／MCP サーバー／サブエージェントの役割（ラベル、回路のノード、ホストの境界）
• gates[] — 管理パイプライン（例：context-load → plan-approval → implement → verify → ledger）
• unmeasurable[] — 検出器では確認できない規範の条項（偽って測定可能に見せず、そのまま提示）
• work_items — セッション上位の任意のグループ化（このワークスペースでは、ステータスを示すフロントマターを持つ plans/** を使用。他のリポジトリでは、同じ枠組みに課題や PR を割り当てられます）。指定がない場合は、セッションをフラットに表示します。

スキーマと中立的な例は hscope/schema/ にあります。次のコマンドで検証できます。

python -m hscope.schema.validate_model ~/.hscope/<workspace>/workspace-model.json

MCP サーフェス

どの MCP クライアントでも HarnessScope が観測した内容を読み取れます。これでループが完結します。エージェントは、前回の評価結果を読んでセッションを開始するため、すでに得られた知見をもう一度得る必要がありません。

// .mcp.json
{ "mcpServers": { "harness-scope": {
    "command": "python", "args": ["-m", "hscope.cli", "mcp", "--db", "/path/to/harness_scope.db"] } } }

ツール
list_sessions · session_report · token_hotspots · rule_health	ビューアーの数値
get_workspace_model	このリポジトリのガバナンスをまとめた 1 つのドキュメント
get_setup_guide · suggest_roles · suggest_rules	ルール作成の根拠
set_role · set_rule	ルールを書き戻す

このサーバー内ではモデルを実行しません。 モデルの役割を担うのはクライアントです。get_setup_guide は、クローズドなアーキタイプライブラリと各アーキタイプのパラメータスキーマをクライアントに渡し、suggest_rules はどのルールからも参照されていないカノン条項を渡します。そして判断結果は set_rule を通じて返され、何かを書き込む前に、そのパラメータがアーキタイプのスキーマに照らして検証されます。そのため、MCP 経由ではプロバイダーも認証情報も、ホスト外への同意も必要ありません。hscope compile は 1 回のバッチ LLM 呼び出しで同じ処理を行います。これは、その会話型かつ段階的な代替手段です。

書き込みはデフォルトで無効（HSCOPE_MCP_WRITE=1）であり、書き込み先は常に ~/.hscope/<workspace>/workspace-model.json に限られます。プロジェクトファイルに書き込んだり、別のエージェントを動かしたりするツールはありません。HarnessScope は観測して判断しますが、動作を指示することはありません。

ドキュメント

MULTI-AGENT.md	セッションが 1 つのモデルの独り言ではない理由と、検出内容 にあるすべての数値について
DOCTOR.md	hscope doctor：9 つの不変条件と、実行を拒否する 2 つの処理
FAILURE-MODES.md	グレースフルデグラデーション：トランスクリプト、DB、モデルに問題がある場合の動作
VERIFICATION.md	検証ハーネス（完了の定義）。CI では 3 つの OS で実行します
CONFIG.md	環境変数 · オプトインの Tier B ジャッジ
RUN-FROM-SOURCE.md	コントリビューター向け：必要条件、各段階のパイプライン、リポジトリの構成

よくある質問

HarnessScope とは何ですか？ Claude Code 向けのローカルファーストな可観測性ツールです。トランスクリプトの JSONL ファイルを SQLite に解析し、ワークスペース独自の運用ルールに照らしてすべてのターンを判定し、各セッションがそのガバナンス構造をどのようにたどったかを示すウェブビューアーを提供します。pip install hscope（または npx -y hscope）でインストールできます。

トランスクリプトデータはマシンの外部に送信されますか？ いいえ。解析、ルール評価、ビューアーはすべてローカルで実行され、サーバーは 127.0.0.1 にバインドされます。例外はオプトイン方式の Tier B LLM 判定機能です。デフォルトでは無効で、そのセッションの判定ボタンをクリックした場合に限り、セッションごとのダイジェストを 1 件送信します。

実行に API キーや LLM は必要ですか？ いいえ。HarnessScope 内にモデルはなく、ルールエンジンは決定論的です。LLM が関わるのは、オプションの Tier B 判定機能を使う場合や、MCP サーフェスを通じてコーディングエージェントにルールを作成させる場合だけです。

ccusage、LangSmith、Phoenix とは何が違いますか？ 異なるレイヤーを扱います（上の比較表を参照）。コスト CLI はセッションの支出を合計し、トレースプラットフォームは アプリケーションの LLM 呼び出しを計測します。HarnessScope は ハーネス自体の トランスクリプトを読み取り、ガバナンスを判定します。つまり、セッションがコーディング前に計画したか、完了を宣言する前に検証したか、パスの境界内にとどまったか、そしてトークンが実際にどこで失われたかを確認します。

エージェントは結果を読み取れますか？ はい。それが MCP サーフェスの目的です。あらゆる MCP クライアントが session_report、token_hotspots、rule_health、ワークスペースモデルを取得できます。そのため、次のセッションは調査結果を再び得るのではなく、前回の評価を読むところから始められます。

Claude Code がトランスクリプト形式を変更するとどうなりますか？ 不変条件を破ったハーネスのバージョンを明示して hscope doctor がエラーを報告し、誤った数値をひそかに出力することはありません。このコーパスだけでも、1 か月で 29 種類のハーネスバージョンが宣言されています。形式の変化は検出され、調整によって見過ごされることはありません。

どのプラットフォームで動作しますか？ Windows、macOS、Linux に対応しています。CI マトリックスでは、3 つすべてで検証用ハーネスを実行します。Python 3.10 以降に対応しています（3.11 以降を推奨）。

データとプライバシー

• SQLite DB には、トランスクリプトの プロンプト全文 が含まれます。gitignore 対象（*.db）であり、ローカルに保管する必要があります。コミットしたりアップロードしたりしないでください。
• サーバーはデフォルトで 127.0.0.1 にバインドされ、DB に対して読み取り専用です。
• Tier B（LLM 判定機能）がセッションごとのダイジェストをホスト外に送信するのは、そのセッションの判定ボタンをクリックした場合 のみ です。ルール（B1）は無効の状態で提供されます。

ライセンスとオープンコアの境界

HarnessScope は Apache-2.0 オープンコア です。個人ユーザーが利用する機能はすべて、機能制限なく永久に無料です。有料プラン（将来提供される場合）は、個人ユーザーの機能を取り上げるのではなく、組織 に必要なものだけを追加します。

レイヤー	無料（Apache-2.0 コア）	エンタープライズ（ee/、将来提供）
取得	トランスクリプトの取り込み＋フック	MCP ゲートウェイ（複数ハーネスの横断的な取得）
分析	ルールエンジン・回路・トークン損失・カバレッジ — すべて	複数ユーザーの集計、組織ダッシュボード
セキュリティ	ローカルのセキュリティフロールール（セルフ監査）	組織向けコンプライアンスレポート、監査ログ
アカウント	ローカル、単一ユーザー	SSO / RBAC

LICENSE（Apache-2.0）、ee/README.md（境界）、CONTRIBUTING.md（DCO）を参照してください。