spec(adapter): split settings.json ownership and ship mcp_tool entry by default (patch)

[liplus-lin-lay]

概要

adapter/claude/hooks-settings.md の旧ルール「.claude/settings.json が存在する場合は Li+ が一切触らない」を見直し、ファイル単位で所有権を分割。

• .claude/settings.json = Li+ 所有 (compare-and-overwrite で内容差分時のみ上書き、no-diff なら sensitive-file プロンプトも出ない)
• .claude/settings.local.json = ユーザー所有 (Li+ 不可侵。permissions / env / theme / 独自 hook / 追加 mcp_tool entry はここ)
• Claude Code が runtime で両ファイルを merge

これに合わせて、PR #1164 で opt-in 経路として導入した type: \"mcp_tool\" UserPromptSubmit hook entry を default テンプレートに昇格。手動 settings.json 編集が不要になる。

設計判断の経緯

`mcp_tool` entry の render 戦略について以下 3 案を検討:

案	内容	採否
(i) 常に含める	未接続環境では Claude Code resolver が `not connected` plain text を毎ターン context に出すが、挙動上の害なし	採用
(ii) bootstrap が MCP 登録源を読んで条件 render	settings.json はクリーンだが、MCP 後付け登録時に1セッション stale + 次 bootstrap で再書込み摩擦。bootstrap が CLI/Desktop で異なる platform 別 path 解決ロジックを抱える	不採用
(iii) LI_PLUS_WEBHOOK_DELIVERY config に紐付け	config 駆動で明示的だが mid-session 切替時の stale が残る	不採用

採用根拠 = bootstrap を MCP enumeration から decoupled に保つ + mid-session MCP 追加で即動く + noise は一行 plain text で実害なし。

変更ファイル

• `Li+bootstrap.md` Phase 4c.4: compare-and-overwrite ロジックに改訂
• `adapter/claude/hooks-settings.md`: default JSON に `mcp_tool` entry 追加 + File ownership boundary 節 + 移行注意 + mcp_tool entry behavior 節
• `adapter/claude/CLAUDE.md`: Optional Webhook Notification Flow 節を default 化に合わせて更新
• `docs/B.-Configuration.md`: `LI_PLUS_WEBHOOK_DELIVERY` 注記更新 + settings.json/local.json 所有境界節を追加
• `skills/operations-foreground-webhook-intake/SKILL.md`: `mcp_hook` 行から「manual addition」記述を削除

既存 workspace への影響 (移行注意)

既に `.claude/settings.json` に user-added キー (permissions / env / theme / 独自 hook / 追加 `mcp_tool` entry) を入れている環境は、本仕様適用前に `settings.local.json` へ移してください。compare-and-overwrite が差分を検出すると Li+ template で上書きされ、user-added キーが失われます。

本セッション workspace (`C:/Users/smile/Code`) では既に分離済みであることを実機確認済み (settings.json top-level keys = ["hooks"] のみ)。

バージョン

minor (large + user-observable structural change per `rules/operations/release-version.md`)

関連

• Closes spec(adapter): relax settings.json silent-rewrite rule for Li+-owned hook entries #1165
• 元 PR (mcp_hook delivery 導入時に opt-in 設計): feat(adapter): add mcp_hook webhook delivery via type=mcp_tool hook #1164
• 直近 release: build-2026-04-25.2 (docs(mcp_hook): document v0.11.3 decision-JSON wrap as precondition (patch) #1168 マージで CD auto-tag)

[liplus-lin-lay]

AI 自己レビュー (semi_auto, minor)

仕様適合

• #1165 の改定後の前提 3 項目すべて反映: (a) settings.local.json に env/secret 等を分離する所有境界、(b) settings.json は Li+ 管轄、(c) bootstrap が Li+ 部分のみ更新（compare-and-overwrite で実現、user 部分は settings.local.json 経由で保護）
• 検討課題 4 つの扱い:
  • JSON マージ実装の信頼性 → 「マージしない、ファイル単位で所有分割」で回避（最小意外性）
  • .claude/settings.local.json の役割明文化 → docs/B に節を追加 + hooks-settings.md File ownership boundary 節
  • backward compat → 移行注意を docs/B + hooks-settings.md + commit body の 3 箇所に記載
  • マージ衝突時の挙動 → 「マージしない」設計で発生しない

内容整合

• compare-and-overwrite 規則は Li+bootstrap.md Phase 4c.4 と adapter/claude/hooks-settings.md の Bootstrap behavior 節で同じ literal を使用
• mcp_tool entry の前提条件 (github-webhook-mcp >= v0.11.3) は hooks-settings.md / docs/B / SKILL.md / adapter/claude/CLAUDE.md の 4 箇所すべてで一致
• LI_PLUS_WEBHOOK_DELIVERY の semantics は据え置き (bash hook reminder の挙動制御)。mcp_tool entry 自体は config に依存せず常に発火する旨を hooks-settings.md mcp_tool entry behavior 節で明示

自己リスク申告

• 既存 workspace の data loss リスク: user-added キーが settings.json に直接置かれていた環境では上書きで失われる。docs/B / commit body / PR body / hooks-settings.md の 4 重で移行注意を書いたが、release 前に Master へ周知タイミングを調整した方が安全
• MCP 未接続環境の noise: 未接続環境では not connected plain text が毎ターン context に出る。挙動上は害ないが視覚的ノイズ。本 PR では「設計判断として受容」と明示。長期的には #1160 (plugin distribution path) でバンドル戦略の中で再検討
• Desktop / CLI 非対称: 本 PR は registration 源の違いには立ち入らず、user が手動で各 host に MCP を登録する前提を維持。バンドル化は #1160 で別軸検討

バージョン判定

minor (large + user-observable structural change per rules/operations/release-version.md)。#1165 body の「minor bump 候補」と一致。

判定

self-review 承認。semi_auto minor のため、Master の review 後 merge。

Note

本セッション workspace の .claude/settings.json に user-added キーが無い (top-level keys = ["hooks"] のみ) ことを実機確認済み。本 PR を本ワークスペースで適用しても data loss は発生しない。