ヘッドレス CLI 実行が「ライフサイクル hook」経由で通知/ミラーを汚染する問題の恒久対策

誰向け・何の問題か

CLI エージェント（Claude Code / 類似の LLM CLI）を バックグラウンドの定期ジョブ（メール収集・カレンダー同期・要約バッチ等）で --print/-p のような非対話モードで大量に自動起動している環境向け。

症状:

• スマホ/Web のセッション一覧・通知チャンネル・ミラー画面に、自動ジョブ由来の項目が毎時積み上がる
• ユーザーが削除しても、次の自動実行でまた現れる（実際は毎回別 ID の新規項目なので「復活」に見える）

根本原因

多くの CLI エージェントには「実行終了時 hook」「プロンプト送信時 hook」等の ライフサイクル hook がある。ここに「実行内容を外部（通知/ミラー）へ転送する」処理を仕込むと、対話セッションだけでなく非対話バッチ実行でも hook が発火し、そのたびに転送される。

よくある誤解: 「セッションを永続化しないオプション（例 --no-session-persistence）を付けたから大丈夫」。これはローカルのセッション保存を止めるだけで、hook の発火は止めない。転送 hook は依然として動く。

対策（多層防御）

1. 発生源で環境変数フラグを立てる（確実・第一層）

非対話ジョブを起動する すべての launcher で、CLI 起動の直前にスキップ用フラグを立てる。

# 例（POSIX）
export AGENT_HEADLESS=1
printf '%s' "$PROMPT" | agent-cli -p --no-session-persistence

# 例（Windows PowerShell）
$env:AGENT_HEADLESS = '1'
$prompt | & $agentExe -p --no-session-persistence

# 例（cmd 経由でパイプする場合）
set "AGENT_HEADLESS=1"&& type prompt.txt | agent-cli -p

転送 hook の冒頭でこのフラグを見て即 return:

if ($env:AGENT_HEADLESS -eq '1') { exit 0 }   # 何も転送しない

ポイント: launcher を1つでも直し忘れると漏れる。-p/--print を叩く箇所を全部洗い出して統一する。将来 launcher を足す時の規約としてコメントに残す。

2. hook 側で「対話 entrypoint 許可リスト」を保険にする（第二層）

多くの CLI は起動モードを環境変数で公開する（例: AGENT_ENTRYPOINT が対話版だと xxx-vscode / xxx-desktop、非対話だと cli 等）。hook 側で 対話の値以外なら転送しないallowlist を入れると、フラグを立て忘れた未知の launcher も捕捉できる。

$ep = $env:AGENT_ENTRYPOINT
# 対話(vscode/desktop)以外は headless とみなしスキップ。空/不明は fail-open（本物を誤って隠さない）
if ($ep -and $ep -ne 'agent-vscode' -and $ep -ne 'agent-desktop') { exit 0 }

注意: launcher が「対話セッションの環境を継承したまま」子プロセスで CLI を起動すると、entrypoint が対話値のまま漏れることがある。だから 第1層（明示フラグ）が主、第2層は保険。

3. 既存の溜まったゴミを確実に判別して一掃

「本物の対話セッションだけ残す」判別は、永続トランスクリプトの有無が確実な指標になる（非対話は --no-session-persistence で保存されない）。ミラー/一覧の各 ID について、CLI のセッション保存ディレクトリに対応ファイルがあるものだけ残す。

// 疑似コード
const realIds = new Set(listPersistedTranscriptIds());   // 保存ディレクトリを走査
store.items = store.items.filter(x => realIds.has(x.id)); // 無い ID = headless ゴミ → 除去
// 実行前に必ずバックアップを取る

削除が「効かない」ように見える時の切り分け

削除ロジック自体（tombstone/hidden 方式）は正しくても、発生源が毎回別 ID を作っていれば「消しても出る」。まず「同じ ID が復活しているのか、別 ID が増えているのか」を確認する。後者なら削除ロジックではなく**発生源（本ドキュメントの対策1）**を直すのが本質。

チェックリスト

• -p/--print を叩く launcher を全部列挙したか
• 各 launcher でスキップフラグを立てたか（cmd 経由も忘れず）
• 転送 hook 冒頭でフラグを見て return しているか
• entrypoint allowlist を保険で入れたか（fail-open）
• 既存ゴミを「永続トランスクリプト有無」で判別し、バックアップの上で一掃したか
• 対策後に「対話セッションは今も転送される・非対話は転送されない」を実際に発火させて確認したか