# AI の応答を止める「番人 hook」を増やしたら user の手間が増えた — 1ランナーに統合して書き直しを最大1回にする ## この指示書が解く問題 Claude Code などの AI エージェントに、応答の末尾で「品質ゲート」を Stop hook として掛けている環境向け。 ゲートを1本ずつ足していくと、次の副作用が出る（実測値: あるPCの7日分の transcript）。 - Stop 304回のうち 198回（65%）が「どこかのゲートが block → AI が書き直し → 再 Stop」だった。 user は同じ応答を 2回以上読む。ゲートが別プロセスで順番に block するので、1回の応答が 3〜4回書き直されることもある。 - 最も多く block していたゲートの block 78件のうち 71件（91%）が誤爆だった。 原因は `/user.*(操作|側で)/s` のような広い正規表現が「user の操作は 0 回」「手作業はゼロ」という**否定文**に一致していたこと。 「手間を減らすための番人」が、最大の手間源になっていた。 ## やること（AI に読ませればそのまま実装できる粒度） ### 1. 誤爆率を先に測る（実装前・必須） 1. 既存ゲートの台帳（block した応答の抜粋を残している jsonl）から、直近7日の block 分を fixture として抜き出す。 2. 「user への命令形（してください／クリック／貼り付け／押して／開いて／ログインして）を含むか」で機械的に2分し、 含まないものは誤爆候補として全件目で確認する。 3. 誤爆率が 30% を超えていたら、ゲートを足す前にまずそのゲートを直す。 4. **fixture は公開リポにコミットしない**（実会話の抜粋には業務情報が入る）。ローカルに置き、 テストは環境変数でパスが渡された時だけ回帰確認し、無ければ skip する。 ### 2. 否定文を手渡し扱いしない - 判定前に否定表現を除去する: `手作業(は|が)?(ゼロ|0回|なし|不要)` / `手渡し(は)?(なし|発生しません)` / `user の操作(は)?(0|なし)`。 - 広いパターン（`user.*操作` など）は、**同じ文の中に命令形がある時だけ**一致とみなす。応答全体をまたぐ `s` フラグの `.*` は使わない。 - 手渡しが検出されない応答には、定型ブロック（「手渡し判定: …」のような記載）を要求しない。 ### 3. ゲートを1つのランナーに合流する `tools/stop-gate-runner.mjs` を1本作り、Stop hook はこれ1本だけ登録する。 - stdin の hook 入力（`session_id` / `transcript_path` / `stop_hook_active`）を **1回だけ**読む。 - transcript から「直近の assistant 本文」と「直前の user 発言」を **1回だけ**抽出する（各ゲートが transcript を読み直さない）。 - 既存ゲートは `evaluate(ctx)` 形式の純関数として import し、同一プロセス内で順に評価する。 既存の CLI エントリ（stdin 読み）は残す。旧 settings.json がまだ個別に呼ぶ移行期間があるため。 - block 理由は全部集めて **1つの `decision: "block"`** にまとめて返す（ゲート名を見出しにした箇条書き）。 これで書き直しは最大1回になる。 - **再試行上限をセッション単位で1つに統一**する。`{ [sessionId]: { blocks, lastTs } }` を state ファイルに持ち、 同一セッションで累計2回 block したら以後は pass（理由 `retry-cap`）。ゲートごとの上限を別々に持つと合計が増える。 - `stop_hook_active === true` の時は判定せず pass。 - 1本のゲートが例外を投げても他は評価し、例外は台帳に `error:` として残して pass 扱い。 **ランナー全体が落ちて AI を止めることは絶対に無い**（fail-open）。 - 台帳は 1 Stop = 1 行: `{ ts, sessionId, verdict: pass|block|retry-cap|skipped, blockedBy: [gate名], reasonCodes, excerpt }`。 - ピギーバック・ヒント: 「応答末尾に次の行動を1行書け」のような**注意**は、他の理由で block する時だけ末尾に添える。単独では block しない。 ### 4. 全PCへの配布 - hook 登録スクリプトに「旧ゲート N 本のファイル名を拾って、ランナー 1 本のコマンドに置換する」移行を入れる。 コマンド文字列に含まれるツリーパスは PC ごとに違うので、**ファイル名で判定**し、置換先は環境変数由来のリポパスを使う。 - 別ツールの hook（`.ps1` や通知系）は触らない。 - 書き込み後に settings.json を読み戻して JSON 同値か検査する。 - 必須 hook 一覧（自己点検）から旧 N 本を外し、ランナー 1 本を入れる。 ### 5. 効果の測り方 user の手間を KPI として毎回出す（7日集計）: `rewrite_stops`（`stop_hook_active` の回数）、`followups_per_session`、 `kick_turns`（「すすめて」「これ」「この先どうしたら」など 40 字以下の蹴り返し）、`chars_read`、`long_turns`。 セッション開始時のレポートに 5 行で出し、導入前の値と比べる。 **導入2日後に台帳の block を1件ずつ読む**こと。発火率だけ見て「効いている」と判断すると誤爆 60〜90% を見逃す。 ## 検証で確認したこと（実測） | 項目 | 結果 | |---|---| | fixture 78件をランナーに流す | block 78 → 3（誤爆 91% が消えた） | | 実 transcript での E2E | pass、1 Stop 0.18 秒（9 プロセス直列より速い） | | settings.json の移行 | Stop hook 17 → 10（ゲート 9 本 → ランナー 1 本、他ツールの 8 本は無変更） | | 同一セッションで3回連続 block | 3回目が `retry-cap` で pass | ## 越えてはいけない線 ランナーは「合流と誤爆修正」であり判定の緩和ではない。承認が要る行為（送信・公開・課金・削除・本番デプロイ・マージ）や user 固有の事実（予算・宛先・期限）を聞く質問は、引き続き止めない。安全機構を「通すために切る」ことはしない。 ---