Claude Code の /clear でセッション一覧が汚れる問題を根絶する

VSCode 拡張（および CLI）で /clear を多用すると、セッション履歴が「中身のない残骸」で埋まり、 さらに「押したか分からず何度も押す」という体験の悪化が起きる。この指示書はその3つの原因を分離して 機械的に潰す手順。AI エージェントに読ませればそのまま実装できる。

前提の理解（ここを間違えると対策を誤る）

1. /clear は履歴の削除コマンドではない。 「会話文脈をリセットして新しいセッションを始める」機能。 だからセッション一覧からは何も消えない。一覧から消す操作は各行のゴミ箱アイコン（下記の通り 「非表示化」であって実体削除ではない）。
2. /clear は押すたびに残骸セッションを1件作る。 そのセッションの JSONL には /clear の コマンド記録（<command-name>/clear</command-name> 等）しか入っていない。数KB・実発言0件・応答0件。
3. 拡張のゴミ箱アイコンは実体を消さない。 セッション ID を「非表示リスト」に足すだけで、 JSONL は ~/.claude/projects/<プロジェクトdir>/<uuid>.jsonl に残り続ける。
4. hook が返す文字列は VSCode 拡張の UI に描画されない。 statusLine 設定もスキーマ上は 受理されるが webview 側に描画実装が無い（拡張の bundle を grep -o "statusLine[A-Za-z]*" で 確認できる: extension.js に数件ヒット / webview に0件）。可視化したいなら「AI の応答に言わせる」しかない。

対策1: 残骸セッションを自動で一覧から外す（掃除の自動化）

常駐スクリプト（Python/Node どちらでもよい）を 30 秒間隔で回し、次の条件を全て満たす JSONL を ~/.claude/projects/_deleted-backup/_empty/ へ move（削除ではなく退避） する。

• ファイルサイズが小さい（例: 200KB 未満。大きいものは読まずに除外して誤検出と I/O を防ぐ）
• type が user / assistant の行のうち、本文が空でないものが0件 （<local-command-caveat> <command-name> <command-message> のようなコマンド記録は「発言」に数えない。 1件でも実発言・実応答を見つけた時点で即 false を返す＝早期打ち切り）
• 最終更新から一定時間が経っている

最後の「猶予時間」の設計がキモ:

対象	猶予	理由
通常のセッション（実発言あり）	600 秒	書き込み中・稼働中を絶対に触らないため長めに取る
空の残骸セッション	90 秒	実発言0・応答0で失う情報が無く、実体も退避先に保全されるので長く待つ意味がない

同じ猶予を使い回すと「10分間は残骸が一覧に居座る」＝人間には「消えていない」と体験される。 空セッション専用の短い閾値を別定数で持たせること。

実装メモ:

• 退避先は「バックアップ」であり削除ではない。復元できる形を保つ（過去のセッションは資産）。
• スクリプトを書き換えたら常駐プロセスの再起動が必須（起動時のコードを保持するため）。 再起動手順は「heartbeat ファイルの PID を kill → heartbeat を削除 → 再起動」。heartbeat を消さないと 「最近生きている」と誤判定して再起動がスキップされることがある。
• 単一インスタンス保証は heartbeat ファイル（PID + mtime による stale 判定）で行う。

対策2: /clear したことを可視化する（二重押しの防止）

多くのエージェント CLI には SessionStart 系の hook に「起動理由」のマッチャがあり、 /clear 由来の起動だけで発火させられる（例: matcher に clear を指定）。UI に描画されないので、 hook の出力で「応答の1行目に必ず印を出せ」とエージェント自身に指示するのが唯一効く経路。

hook スクリプトの骨子（Node、依存ゼロ）:

#!/usr/bin/env node
import fs from "node:fs"; import os from "node:os"; import path from "node:path";
let sid = "";
try { sid = JSON.parse(fs.readFileSync(0, "utf8") || "{}").session_id || ""; } catch {}
const hhmm = new Date().toLocaleTimeString("ja-JP", { hour: "2-digit", minute: "2-digit" });
try {
  fs.writeFileSync(path.join(os.homedir(), ".claude", "last-clear.json"),
    JSON.stringify({ at: new Date().toISOString(), session_id: sid }, null, 2));
} catch {}
process.stdout.write(
  `【/clear 直後のセッション】${hhmm} に /clear が実行され、この会話は文脈ゼロの新セッション。` +
  `最初の応答の1行目に必ず \`🧹 /clear 済み（${hhmm}）\` と表示せよ（省略禁止）。\n`);

• stdin が空でも落ちないようにする（hook の呼ばれ方は環境差がある）。
• 時刻をファイルにも残すと「本当に発火したか」の診断ができる。
• 効果: 印が出れば実行済み、出なければ未実行と判断できるので同じ操作を繰り返さなくなる。

対策3: そもそも /clear を使わない（推奨）

VSCode 拡張には「新しい会話」コマンドがあり、キーボードショートカット（Ctrl/Cmd+N）は既定で無効。 ユーザー設定で有効化する:

{ "claudeCode.enableNewConversationShortcut": true }

これで Claude パネルにフォーカスして Ctrl+N を押すと新しい会話が開く。利点:

• 画面が明示的に切り替わるので「押したか分からない」が構造的に起きない（＝二重押し不能）
• /clear のようなコマンド記録だけの残骸セッションが作られない
• 設定変更の反映はウィンドウの再読み込み（Developer: Reload Window）または次回起動時

導入後の検証（ここまでやって初めて「直った」と言える）

1. 掃除スクリプトを1回パスで実際に実行し、ログに「残骸を退避した」旨が出ることを確認する。
2. 稼働中セッションの JSONL が無傷であることをサイズ・mtime で確認する（最重要の退行チェック）。
3. 常駐プロセスが生きていることを PID で確認する（heartbeat の PID がプロセス一覧に居るか）。
4. 可視化 hook は echo '{"session_id":"test"}' | node <hook> で単体実行し、出力文字列を目視する。
5. UI 側の見え方（印が出るか、ショートカットが効くか）だけは人間の1回確認に残る。ここは正直に伝える。

落とし穴

• 「一覧から消えない」を /clear の不具合と誤診しない。仕様であり、原因は別（残骸の蓄積・非表示化の仕組み）。
• 猶予時間を一律に長く取ると「消えない」体験が残る。逆に一律に短くすると稼働中セッションを触る危険がある。対象別に分ける。
• 残骸を削除しない。退避（move）にする。誤検出時に戻せる状態を必ず残す。
• スクリプト修正後の常駐再起動を忘れると「直したのに直っていない」になる。