friday-mcp-v2 3.0.1 → 3.0.2

package/dist/mcp-server.js

@@ -207,13 +207,15 @@ function checkRevisionMismatch(expectedRevision, currentState, mode, postId, ses
     const currentRevision = computeRevision(currentState, mode);
     if (expectedRevision === currentRevision) return null;
 
-    // 不一致 — 更新は拒否するが、最新 snapshot を返して再取得の往復を省く
+    // 不一致 — snapshot をキャッシュに登録（AI が新 snapshotId で refetch 可能に）
+    // Phase 2: blocks 一覧は出力しない（コンテキスト軽量化）
     const latestSnapshot = buildSnapshotFromState(currentState, mode, postId, sessionId, siteName);
-    let text = `❌ REVISION_MISMATCH: 記事の構造が変更されています（expected: ${expectedRevision}, current: ${currentRevision}）。\n` +
-               `更新はスキップしました。以下の最新 snapshot で再試行してください。`;
-    if (latestSnapshot) {
-        text = appendSnapshotToText(text, latestSnapshot);
-    }
+    const snapshotLine = latestSnapshot
+        ? `\n[snapshot:${latestSnapshot.snapshotId} rev:${latestSnapshot.revision}]`
+        : '';
+    const text = `❌ REVISION_MISMATCH: expected ${expectedRevision}, actual ${currentRevision}` +
+                 snapshotLine +
+                 `\n→ get_article_structure で最新を取得してください`;
     return { content: [{ type: "text", text }], isError: true };
 }
 
@@ -1005,11 +1007,11 @@ async function resolveRefsAndCheckRevision({
         try {
             if (ref) {
                 const index = resolveRefFromState(snapshotId, ref, mode, sessionId, postId, currentState);
-                return { index };
+                return { index, currentState };
             }
             if (refs) {
                 const indices = refs.map(r => resolveRefFromState(snapshotId, r, mode, sessionId, postId, currentState));
-                return { indices };
+                return { indices, currentState };
             }
         } catch (e) {
             return { error: {
@@ -1021,10 +1023,11 @@ async function resolveRefsAndCheckRevision({
 
     // Case 2: ref なし + expectedRevision のみ
     if (expectedRevision) {
-        const { error } = await acquireFreshState({
+        const { currentState, error } = await acquireFreshState({
             expectedRevision, mode, client, postId, sessionId, siteName,
         });
         if (error) return { error };
+        return { currentState };
     }
 
     // Case 3: どちらもなし
@@ -1032,15 +1035,62 @@ async function resolveRefsAndCheckRevision({
 }
 
 /**
- * 更新後のレスポンス snapshot を構築する
+ * 下流レスポンスの blocks を buildSnapshotBlocks / computeRevision が
+ * 期待する state.allBlocks 形式に正規化する。
+ * @param {Array} blocks - 下流 formatBlocksForSnapshot() の結果
+ * @returns {{ allBlocks: Array }}
+ */
+function normalizeDownstreamBlocks(blocks) {
+    return {
+        allBlocks: blocks.map(b => ({
+            index: b.index,
+            type: b.type,
+            html: b.html || '',
+            attributes: b.attributes || {},
+            section: b.section || null,
+            depth: b.depth || 0,
+            parentIndex: b.parentIndex ?? null,
+        })),
+    };
+}
+
+/**
+ * 下流レスポンスの result.blocks から snapshot を構築する。
+ * blocks がない場合は null を返す（呼び出し元でフォールバック判断）。
+ * @param {object} result - 下流レスポンス
+ * @param {string} mode
+ * @param {number} postId
+ * @param {string|null} sessionId
+ * @param {string} siteName
+ * @returns {object|null} { snapshotId, revision, blocks[] } or null
+ */
+function buildResponseSnapshotFromResult(result, mode, postId, sessionId, siteName) {
+    const blocks = result?.blocks;
+    if (!blocks || !Array.isArray(blocks) || blocks.length === 0) {
+        return null;
+    }
+    const state = normalizeDownstreamBlocks(blocks);
+    return buildSnapshotFromState(state, mode, postId, sessionId, siteName);
+}
+
+/**
+ * 更新後のレスポンス snapshot を構築する。
+ * result が渡され、result.blocks があればそこから構築（再取得不要）。
+ * なければ従来通り getCurrentStructure() で再取得する。
  * @param {string} mode
  * @param {object} client
  * @param {number} postId
  * @param {string|null} sessionId
  * @param {string} siteName
+ * @param {object} [result] - 下流レスポンス（Phase 1: blocks 再利用）
  * @returns {Promise<object|null>} { snapshotId, revision, blocks[] } or null
  */
-async function buildResponseSnapshot(mode, client, postId, sessionId, siteName) {
+async function buildResponseSnapshot(mode, client, postId, sessionId, siteName, result) {
+    // Phase 1: 下流 result.blocks があればそこから構築（再取得不要）
+    if (result) {
+        const fromResult = buildResponseSnapshotFromResult(result, mode, postId, sessionId, siteName);
+        if (fromResult) return fromResult;
+    }
     let newState;
     try {
         newState = await getCurrentStructure(mode, client, postId, sessionId);
@@ -1083,6 +1133,7 @@ async function buildResponseSnapshot(mode, client, postId, sessionId, siteName)
 }
 
 /**
+ * @deprecated Phase 7 で削除予定。batch 経路および index 経路の後方互換用。
  * snapshot 情報をテキストレスポンスに付加する
  * blocks[] を含めて AI が新しい ref を取得できるようにする
  * @param {string} text - 元のレスポンステキスト
@@ -1093,7 +1144,7 @@ async function buildResponseSnapshot(mode, client, postId, sessionId, siteName)
  * @param {number} [refInfo.resolvedIndex] - 解決された元の index
  * @returns {string} snapshot 行と blocks 一覧が付加されたテキスト
  */
-function appendSnapshotToText(text, snapshot, refInfo) {
+function appendSnapshotToTextLegacy(text, snapshot, refInfo) {
     if (!snapshot) return text;
 
     // 1→N 展開チェック（単体操作時のみ）
@@ -1125,6 +1176,491 @@ function appendSnapshotToText(text, snapshot, refInfo) {
     return out;
 }
 
+/**
+ * Phase 5: update_blocks / insert_block の差分/Legacy 自動分岐。
+ * inputRef が null なら即 Legacy。差分構築失敗時も Legacy フォールバック。
+ * @param {string} text - メッセージ本文
+ * @param {object|null} snap - buildResponseSnapshot の結果
+ * @param {object} result - 下流レスポンス
+ * @param {object|null} preState - _preState
+ * @param {string|null} inputRef - 入力 ref（null = Legacy 固定）
+ * @param {boolean} isInsert - insertOnly 操作か
+ * @param {object|null} refInfo - Legacy フォールバック用 _refInfo
+ * @returns {string}
+ */
+function buildUpdateDiffResponse(text, snap, result, preState, inputRef, isInsert, refInfo) {
+    if (!inputRef || !snap) {
+        return appendSnapshotToTextLegacy(text, snap, refInfo);
+    }
+
+    if (isInsert) {
+        const changeInfo = buildChangeInfoFromResult('inserted', snap, result, preState);
+        if (changeInfo) return appendRefChangesToText(text, changeInfo);
+        return appendSnapshotToTextLegacy(text, snap, refInfo);
+    }
+
+    // update / expand 判定
+    // success:false の change を除外（invalid regex, parse failure 等）
+    const changes = result?.changes?.filter(c => c.success !== false);
+    if (!changes || changes.length === 0) {
+        return appendSnapshotToTextLegacy(text, snap, refInfo);
+    }
+    // filtered 済み changes で result を差し替え（buildChangeInfoFromResult が result.changes を直接参照するため）
+    const filteredResult = { ...result, changes };
+    if (changes.length === 1 && changes[0]?.newIndices?.length > 1) {
+        // 1→N 展開（単体 target のみ）
+        const changeInfo = buildChangeInfoFromResult('expanded', snap, filteredResult, preState, { inputRef });
+        if (changeInfo) return appendRefChangesToText(text, changeInfo);
+    } else if (changes.length === 1) {
+        // 1→1 更新（単体 ref で成功 1 件のときだけ差分化）
+        const changeInfo = buildChangeInfoFromResult('updated', snap, filteredResult, preState);
+        if (changeInfo) return appendRefChangesToText(text, changeInfo);
+    }
+
+    return appendSnapshotToTextLegacy(text, snap, refInfo);
+}
+
+// ============================================================
+// Phase 2: ref 変化分類ロジック（差分通知方式の基盤）
+// ============================================================
+
+/**
+ * @typedef {Object} DeletedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'deleted'} type
+ * @property {string[]} deletedRefs - 削除された ref 配列 ['r5', 'r8']
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} InsertedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'inserted'} type
+ * @property {Array<{index: number, ref: string, blockType: string, depth: number}>} inserted
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} MovedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'moved'} type
+ * @property {Array<{oldRef: string, newRef: string}>} moved
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} UpdatedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'updated'} type
+ * @property {string[]} updatedRefs - fingerprint 変化した ref 配列
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} ExpandedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'expanded'} type
+ * @property {{oldRef: string, newRefs: string[]}} expanded
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} DuplicatedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'duplicated'} type
+ * @property {string} sourceRef
+ * @property {string} newRef
+ * @property {number} sourceIndex
+ * @property {number} newIndex
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {DeletedChange|InsertedChange|MovedChange|UpdatedChange|ExpandedChange|DuplicatedChange} ChangeInfo
+ */
+
+/**
+ * ref 変化情報をテキストに付加する��差分モード）��
+ * blocks 一��は出力しない。
+ * @param {string} text
+ * @param {ChangeInfo|null} changeInfo
+ * @returns {string}
+ */
+function appendRefChangesToText(text, changeInfo) {
+    if (!changeInfo) return text;
+
+    let out = text + `\n\n[snapshot:${changeInfo.snapshotId} rev:${changeInfo.revision}]`;
+
+    switch (changeInfo.type) {
+        case 'deleted':
+            out += `\ndeleted: [${changeInfo.deletedRefs.join(', ')}] (invalid in new snapshot)`;
+            break;
+        case 'inserted':
+            out += '\ninserted: ' + changeInfo.inserted
+                .map(b => `[${b.index}|${b.ref}] ${b.blockType} (d:${b.depth})`)
+                .join(', ');
+            break;
+        case 'moved':
+            out += '\nmoved: ' + changeInfo.moved
+                .map(m => `${m.oldRef}\u2192${m.newRef}`)
+                .join(', ');
+            break;
+        case 'updated':
+            out += `\nupdated: [${changeInfo.updatedRefs.join(', ')}] (use new snapshot)`;
+            break;
+        case 'expanded':
+            out += `\nexpanded: ${changeInfo.expanded.oldRef} \u2192 [${changeInfo.expanded.newRefs.join(', ')}]`;
+            break;
+        case 'duplicated':
+            out += `\nduplicated: ${changeInfo.sourceRef} \u2192 ${changeInfo.newRef} (source:[${changeInfo.sourceIndex}], new:[${changeInfo.newIndex}]) (use new snapshot)`;
+            break;
+    }
+
+    if (changeInfo.refetchRequired) {
+        out += '\n\u26a0 refetchRequired: \u5b50\u30d6\u30ed\u30c3\u30af\u5909\u66f4\u3042\u308a\u3002get_article_structure \u3067\u6700\u65b0\u3092\u53d6\u5f97\u3057\u3066\u304f\u3060\u3055\u3044\u3002';
+    }
+
+    return out;
+}
+
+/**
+ * @typedef {Object} BatchDiffEntry
+ * @property {number} opIndex
+ * @property {'updated'|'expanded'|'failed'|'skipped'} type
+ * @property {string} [ref] - updated/failed/skipped 時
+ * @property {string} [oldRef] - expanded 時
+ * @property {string[]} [newRefs] - expanded 時
+ * @property {string} [error] - failed 時
+ * @property {boolean} [refetchRequired] - この entry 単体の refetch 判定
+ */
+
+/**
+ * @typedef {Object} BatchDiffInfo
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'batch'} type
+ * @property {BatchDiffEntry[]} entries
+ * @property {boolean} [refetchRequired] - batch 全体の OR
+ */
+
+/**
+ * BatchDiffInfo をテキストに付加する（batch 差分モード）。
+ * @param {string} text
+ * @param {BatchDiffInfo|null} batchInfo
+ * @returns {string}
+ */
+function appendBatchRefChangesToText(text, batchInfo) {
+    if (!batchInfo) return text;
+
+    let out = text + `\n\n[snapshot:${batchInfo.snapshotId} rev:${batchInfo.revision}]`;
+    out += '\nchanges:';
+
+    for (const entry of batchInfo.entries) {
+        switch (entry.type) {
+            case 'updated':
+                out += `\n  [${entry.opIndex}] updated: [${entry.ref}]`;
+                break;
+            case 'expanded':
+                out += `\n  [${entry.opIndex}] expanded: ${entry.oldRef} \u2192 [${entry.newRefs.join(', ')}]`;
+                break;
+            case 'failed':
+                out += `\n  [${entry.opIndex}] failed: ${entry.ref}`;
+                if (entry.error) out += ` \u2014 ${entry.error}`;
+                break;
+            case 'skipped':
+                out += `\n  [${entry.opIndex}] skipped: ${entry.ref}`;
+                break;
+        }
+        if (entry.refetchRequired) out += ' (refetch)';
+    }
+
+    if (batchInfo.refetchRequired) {
+        out += '\n\u26a0 refetchRequired: \u5b50\u30d6\u30ed\u30c3\u30af\u5909\u66f4\u3042\u308a\u3002get_article_structure \u3067\u6700\u65b0\u3092\u53d6\u5f97\u3057\u3066\u304f\u3060\u3055\u3044\u3002';
+    }
+
+    return out;
+}
+
+// ============================================================
+// Phase 7: batch 差分化 helper
+// ============================================================
+
+/**
+ * allBlocks の parentIndex チェーンを辿り、resolvedOps 間に祖先/子孫関係があるか検出。
+ * @param {Array<{resolvedIndex: number, ref: string}>} resolvedOps
+ * @param {Array<{index: number, parentIndex: number|null}>} allBlocks
+ * @returns {{childRef: string, childIndex: number, ancestorRef: string, ancestorIndex: number}|null}
+ */
+function checkAncestorOverlap(resolvedOps, allBlocks) {
+    const targetMap = new Map(resolvedOps.map(o => [o.resolvedIndex, o.ref]));
+    const parentMap = new Map(allBlocks.map(b => [b.index, b.parentIndex ?? null]));
+
+    for (const op of resolvedOps) {
+        let current = parentMap.get(op.resolvedIndex);
+        while (current != null) {
+            if (targetMap.has(current)) {
+                return {
+                    childRef: op.ref,
+                    childIndex: op.resolvedIndex,
+                    ancestorRef: targetMap.get(current),
+                    ancestorIndex: current,
+                };
+            }
+            current = parentMap.get(current) ?? null;
+        }
+    }
+    return null;
+}
+
+/**
+ * allBlocks 内の rootIndex を含む subtree の flat size を返す。
+ * @param {Array<{index: number, parentIndex: number|null}>} allBlocks
+ * @param {number} rootIndex
+ * @returns {number}
+ */
+function countFlatSubtreeSize(allBlocks, rootIndex) {
+    const childrenOf = new Map();
+    for (const b of allBlocks) {
+        if (b.parentIndex != null) {
+            if (!childrenOf.has(b.parentIndex)) childrenOf.set(b.parentIndex, []);
+            childrenOf.get(b.parentIndex).push(b.index);
+        }
+    }
+    let count = 1;
+    const stack = childrenOf.get(rootIndex) ? [...childrenOf.get(rootIndex)] : [];
+    while (stack.length > 0) {
+        const idx = stack.pop();
+        count++;
+        const children = childrenOf.get(idx);
+        if (children) stack.push(...children);
+    }
+    return count;
+}
+
+/**
+ * opResult.blocks から新 subtree の flat size を計算する。
+ * rawNewIndices のうち集合内に親を持たないものを root とみなし、各 root の subtree size を合算。
+ * editor（top-level のみ）/ headless（flat 全体）両対応。
+ * @param {Array<{index: number, parentIndex?: number|null}>} opResultBlocks
+ * @param {number[]} rawNewIndices
+ * @returns {number}
+ */
+function computeNewFlatSize(opResultBlocks, rawNewIndices) {
+    if (!rawNewIndices || rawNewIndices.length === 0) return 0;
+    const indexSet = new Set(rawNewIndices);
+    const newRoots = rawNewIndices.filter(idx => {
+        const b = opResultBlocks.find(bl => bl.index === idx);
+        return !b || b.parentIndex == null || !indexSet.has(b.parentIndex);
+    });
+    let total = 0;
+    const blocksForSize = opResultBlocks.map(b => ({ index: b.index, parentIndex: b.parentIndex ?? null }));
+    for (const root of newRoots) {
+        total += countFlatSubtreeSize(blocksForSize, root);
+    }
+    return total;
+}
+
+/**
+ * [pre-state 戦略] 操作前の状態で対象ブロックにネスト子があるか判定。
+ * delete, move, duplicate 用。操作後は対象が消える/移動するため pre-state で見る。
+ * 下流 hasChildren フラグがあればそちらを優先（duplicate, move が返す）。
+ * @param {object|null} preState - 操作前の state
+ * @param {number[]} targetIndices - 操作対象 index 配列
+ * @param {object} [downstream] - 下流 result（hasChildren があれば優先）
+ * @returns {boolean}
+ */
+function checkRefetchFromPreState(preState, targetIndices, downstream) {
+    if (downstream?.hasChildren === true) return true;
+    if (downstream?.hasChildren === false) return false;
+
+    if (!preState?.allBlocks) return true;
+
+    for (const idx of targetIndices) {
+        const hasChild = preState.allBlocks.some(b => b.parentIndex === idx);
+        if (hasChild) return true;
+    }
+    return false;
+}
+
+/**
+ * [post-result 戦略] 操作結果にネストブロックが含ま���るか判定。
+ * insert, update 用��非ネストだったブロックを nested HTML に更新したケースを検知。
+ * 新 snapshot の blocks から、対象 index を parentIndex に持つブロックがあるかで判定。
+ * @param {object} snapshot - buildResponseSnapshot() の結果（新 snapshot）
+ * @param {number[]} resultIndices - 操作結果の index 配列（挿入/更新された位置）
+ * @returns {boolean}
+ */
+function checkRefetchFromResult(snapshot, resultIndices) {
+    if (!snapshot?.blocks || resultIndices.length === 0) return false;
+
+    for (const idx of resultIndices) {
+        const hasNested = snapshot.blocks.some(b => b.parentIndex === idx);
+        if (hasNested) return true;
+    }
+    return false;
+}
+
+/**
+ * 下流 result + 新 snapshot → ChangeInfo を構築する。
+ * 構築不能な場合は null を返す（呼び出し側は Legacy フォールバック必須）。
+ * @param {'deleted'|'inserted'|'moved'|'updated'|'expanded'|'duplicated'} type
+ * @param {object} snapshot - buildResponseSnapshot() の結果
+ * @param {object} result - 下流レスポンス
+ * @param {object|null} preState - _preState
+ * @param {object} [opts] - 追加オプション
+ * @returns {ChangeInfo|null} null = Legacy フォールバック
+ */
+function buildChangeInfoFromResult(type, snapshot, result, preState, opts) {
+    if (!snapshot?.snapshotId || !result) return null;
+
+    const base = { snapshotId: snapshot.snapshotId, revision: snapshot.revision };
+
+    switch (type) {
+        case 'deleted': {
+            const deleted = result.deleted;
+            if (!deleted || deleted.length === 0) return null;
+            const deletedRefs = opts?.inputRefs || deleted.map(d => generateBlockRef(d.index));
+            const refetch = checkRefetchFromPreState(preState, deleted.map(d => d.index), result);
+            return { ...base, type: 'deleted', deletedRefs, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'inserted': {
+            let indices = result.insertedIndices;
+            if (!indices && result.changes) {
+                indices = result.changes.flatMap(c => c.newIndices || []).filter(i => i != null);
+            }
+            if (!indices || indices.length === 0) return null;
+            // refetchRequired は全 indices で判定（子孫含む）
+            const refetch = checkRefetchFromResult(snapshot, indices);
+            // top-level のみ: 他の inserted index を parentIndex に持つものを除外
+            // （headless は subtree 全体の flat index を返すが、editor は top-level のみ。差分レスポンスは top-level に統一）
+            const indexSet = new Set(indices);
+            const topLevelIndices = indices.filter(idx => {
+                const b = snapshot.blocks?.find(bl => bl.index === idx);
+                return !b || b.parentIndex == null || !indexSet.has(b.parentIndex);
+            });
+            const inserted = topLevelIndices.map(idx => {
+                const b = snapshot.blocks?.find(bl => bl.index === idx);
+                return b
+                    ? { index: b.index, ref: b.ref, blockType: b.type, depth: b.depth }
+                    : { index: idx, ref: generateBlockRef(idx), blockType: 'unknown', depth: 0 };
+            });
+            if (inserted.length === 0) return null;
+            return { ...base, type: 'inserted', inserted, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'moved': {
+            const mapping = result.movedMapping;
+            if (!mapping || mapping.length === 0) return null;
+            // inputRefs 長さ不一致 → Legacy フォールバック（count > 1 安全弁）
+            if (opts?.inputRefs && opts.inputRefs.length !== mapping.length) return null;
+            const moved = mapping.map((m, i) => ({
+                oldRef: opts?.inputRefs ? opts.inputRefs[i] : generateBlockRef(m.oldIndex),
+                newRef: generateBlockRef(m.newIndex),
+            }));
+            const refetch = checkRefetchFromPreState(preState, mapping.map(m => m.oldIndex), result);
+            return { ...base, type: 'moved', moved, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'updated': {
+            const changes = result.changes;
+            if (!changes || changes.length === 0) return null;
+            const updatedRefs = changes.map(c => generateBlockRef(c.newIndices?.[0] ?? c.oldIndex));
+            const resultIndices = changes.flatMap(c => c.newIndices || []).filter(i => i != null);
+            const refetch = checkRefetchFromResult(snapshot, resultIndices);
+            return { ...base, type: 'updated', updatedRefs, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'expanded': {
+            const changes = result.changes || [];
+            if (changes.length !== 1) return null;
+            const change = changes[0];
+            if (!change || !change.newIndices || change.newIndices.length <= 1) return null;
+            const oldRef = opts?.inputRef || generateBlockRef(change.oldIndex);
+            const newRefs = change.newIndices.map(idx => generateBlockRef(idx));
+            const refetch = checkRefetchFromResult(snapshot, change.newIndices);
+            return { ...base, type: 'expanded', expanded: { oldRef, newRefs }, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'duplicated': {
+            const srcIdx = result.sourceIndex ?? result.duplicated?.index;
+            const newIdx = result.newIndex ?? result.duplicated?.newIndex;
+            if (srcIdx == null || newIdx == null) return null;
+            const refetch = checkRefetchFromPreState(preState, [srcIdx], result);
+            return {
+                ...base, type: 'duplicated',
+                sourceRef: opts?.inputRef || generateBlockRef(srcIdx),
+                newRef: generateBlockRef(newIdx),
+                sourceIndex: srcIdx, newIndex: newIdx,
+                ...(refetch ? { refetchRequired: true } : {}),
+            };
+        }
+        default:
+            return null;
+    }
+}
+
+/**
+ * 実行完了した resolvedOps + snapshot から BatchDiffInfo を構築する。
+ * @param {Array} resolvedOps - rebasing 済みの op 配列
+ * @param {object|null} snapshot - 最終 snapshot
+ * @returns {BatchDiffInfo|null}
+ */
+function buildBatchDiffInfo(resolvedOps, snapshot) {
+    if (!snapshot?.snapshotId) return null;
+
+    let refetchRequired = false;
+    const entries = [];
+
+    // opIndex 順（入力順）でソート
+    const opsByInput = [...resolvedOps].sort((a, b) => a.opIndex - b.opIndex);
+
+    for (const op of opsByInput) {
+        if (op.status === 'failed') {
+            entries.push({ opIndex: op.opIndex, type: 'failed', ref: op.ref, error: op.error || null });
+            continue;
+        }
+        if (op.status === 'skipped') {
+            entries.push({ opIndex: op.opIndex, type: 'skipped', ref: op.ref });
+            continue;
+        }
+
+        // rebased な新 ref を snapshot から取得
+        const newRefs = (op.rebasedNewIndices || []).map(idx => {
+            const b = snapshot.blocks?.find(bl => bl.index === idx);
+            return b ? b.ref : generateBlockRef(idx);
+        });
+
+        // refetch 判定
+        const opRefetch = checkRefetchFromResult(snapshot, op.rebasedNewIndices || []);
+        if (opRefetch) refetchRequired = true;
+
+        if (op.status === 'expanded') {
+            entries.push({
+                opIndex: op.opIndex, type: 'expanded',
+                oldRef: op.ref, newRefs,
+                ...(opRefetch ? { refetchRequired: true } : {}),
+            });
+        } else {
+            // updated
+            entries.push({
+                opIndex: op.opIndex, type: 'updated',
+                ref: newRefs[0] || op.ref,
+                ...(opRefetch ? { refetchRequired: true } : {}),
+            });
+        }
+    }
+
+    return {
+        snapshotId: snapshot.snapshotId,
+        revision: snapshot.revision,
+        type: 'batch',
+        entries,
+        ...(refetchRequired ? { refetchRequired: true } : {}),
+    };
+}
+
 /**
  * batch operations の実行
  * @param {Array} operations - 各 operation: { target, newHTML?, replacements?, attributeUpdates? }
@@ -1221,17 +1757,30 @@ async function handleBatchOperations(operations, snapshotId, mode, client, postI
         indexSet.add(op.resolvedIndex);
     }
 
-    // 2. 降順ソート（index が大きい方から処理 — 1 op = 1 index なので安全）
+    // ancestor/descendant overlap チェック（親子関係の target は batch 不可）
+    const ancestorOverlap = checkAncestorOverlap(resolvedOps, currentState.allBlocks);
+    if (ancestorOverlap) {
+        return {
+            content: [{ type: "text", text: `❌ operations に親子関係の target が含まれるため batch 不可です。ref ${ancestorOverlap.childRef} (index ${ancestorOverlap.childIndex}) は ref ${ancestorOverlap.ancestorRef} (index ${ancestorOverlap.ancestorIndex}) の子孫です。` }],
+            isError: true,
+        };
+    }
+
+    // 2. oldFlatSize を計算（rebasing 用、降順ソート前に実行）
+    for (const op of resolvedOps) {
+        op.oldFlatSize = countFlatSubtreeSize(currentState.allBlocks, op.resolvedIndex);
+    }
+
+    // 3. 降順ソート（index が大きい方から処理 — 1 op = 1 index なので安全）
     resolvedOps.sort((a, b) => b.resolvedIndex - a.resolvedIndex);
 
-    // 3. 各 operation を順次実行
-    const results = [];
+    // 4. 各 operation を順次実行（結果情報を保持）
+    let lastSuccessfulResult = null;
     for (const op of resolvedOps) {
         const index = op.resolvedIndex;
 
         let opResult;
         try {
-            // batch は ref → index 解決済み。1 op = 1 index で下流に渡す
             const downstreamParams = {
                 index,
                 replacements: op.replacements,
@@ -1246,39 +1795,95 @@ async function handleBatchOperations(operations, snapshotId, mode, client, postI
             } else {
                 opResult = await client.sendEditorCommand("update_blocks", downstreamParams, 10000, postId, sessionId);
             }
-
-            results.push({
-                ref: op.ref,
-                resolvedIndex: op.resolvedIndex,
-                status: (opResult && opResult.success !== false && opResult.ok !== false) ? 'updated' : 'failed',
-                error: opResult?.error || null,
-            });
         } catch (e) {
-            results.push({
-                ref: op.ref,
-                resolvedIndex: op.resolvedIndex,
-                status: 'failed',
-                error: e.message,
-            });
+            op.status = 'failed';
+            op.error = e.message;
+            op.rawNewIndices = [];
+            op.newFlatSize = op.oldFlatSize;
+            op.opResult = null;
+            continue;
+        }
+
+        // op 成功判定
+        const topLevelFail = !opResult || opResult.success === false || opResult.ok === false;
+        if (topLevelFail) {
+            op.status = 'failed';
+            op.error = opResult?.error || 'unknown error';
+            op.rawNewIndices = [];
+            op.newFlatSize = op.oldFlatSize;
+            op.opResult = opResult;
+            continue;
         }
+
+        // skipped 判定（attributeUpdates の filter mismatch）
+        const successfulChanges = (opResult.changes || []).filter(c => c.success !== false);
+        const hasSkippedResult = opResult.results?.some(r => r.skipped === true);
+        if (successfulChanges.length === 0 && !topLevelFail && !opResult.error) {
+            if (hasSkippedResult || op.attributeUpdates != null) {
+                op.status = 'skipped';
+                op.rawNewIndices = [];
+                op.newFlatSize = op.oldFlatSize;
+                op.opResult = opResult;
+                continue;
+            }
+            // changes 空で skipped でもない → failed
+            op.status = 'failed';
+            op.error = 'no successful changes';
+            op.rawNewIndices = [];
+            op.newFlatSize = op.oldFlatSize;
+            op.opResult = opResult;
+            continue;
+        }
+
+        // 成功: rawNewIndices を取得
+        op.rawNewIndices = successfulChanges.flatMap(c => c.newIndices || []);
+        op.newFlatSize = (opResult.blocks && opResult.blocks.length > 0)
+            ? computeNewFlatSize(opResult.blocks, op.rawNewIndices)
+            : op.rawNewIndices.length || op.oldFlatSize;
+        op.status = (op.rawNewIndices.length > 1) ? 'expanded' : 'updated';
+        op.opResult = opResult;
+        lastSuccessfulResult = opResult;
+    }
+
+    // 5. rebasing（resolvedIndex 昇順で走査、低 index の展開が高 index をずらす）
+    const opsForRebase = [...resolvedOps].sort((a, b) => a.resolvedIndex - b.resolvedIndex);
+    let cumulativeDelta = 0;
+    for (const op of opsForRebase) {
+        if (op.status === 'failed' || op.status === 'skipped') {
+            op.rebasedNewIndices = [];
+            continue;
+        }
+        op.rebasedNewIndices = op.rawNewIndices.map(idx => idx + cumulativeDelta);
+        cumulativeDelta += (op.newFlatSize - op.oldFlatSize);
+    }
+
+    // 6. 最終 snapshot 構築
+    let snapshot;
+    if (lastSuccessfulResult) {
+        snapshot = buildResponseSnapshotFromResult(lastSuccessfulResult, mode, postId, sessionId, siteName);
+    }
+    if (!snapshot) {
+        // 全 op 失敗/skipped or result.blocks なし → currentState から構築
+        snapshot = buildSnapshotFromState(currentState, mode, postId, sessionId, siteName);
     }
+    if (!snapshot) {
+        // 最終手段: 再取得
+        snapshot = await buildResponseSnapshot(mode, client, postId, sessionId, siteName);
+    }
+
+    // 7. BatchDiffInfo 構築
+    const batchDiff = buildBatchDiffInfo(resolvedOps, snapshot);
 
-    // 4. レスポンス snapshot 構築
-    const snapshot = await buildResponseSnapshot(mode, client, postId, sessionId, siteName);
+    // 8. レスポンス組み立て
+    const successCount = resolvedOps.filter(r => r.status !== 'failed' && r.status !== 'skipped').length;
+    const totalCount = resolvedOps.length;
+    let text = `\u2705 batch \u5b8c\u4e86 (${successCount}/${totalCount} \u6210\u529f)`;
 
-    // レスポンス組み立て
-    // 注: 1→N 展開の newRefs[] は snapshot.blocks[] 全体を返しているため、
-    //      AI は新 snapshot から直接新しい ref を特定できる。
-    //      per-operation の newRefs 追跡は複数変更時に不正確になるため省略。
-    const successCount = results.filter(r => r.status !== 'failed').length;
-    const failCount = results.filter(r => r.status === 'failed').length;
-    let text = `✅ batch 完了\n\n成功: ${successCount} / 失敗: ${failCount}`;
-    for (const r of results) {
-        const refLabel = r.ref ? ` (${r.ref})` : '';
-        text += `\n  [${r.resolvedIndex}]${refLabel}: ${r.status}`;
-        if (r.error) text += ` — ${r.error}`;
+    if (batchDiff) {
+        text = appendBatchRefChangesToText(text + _modeTag, batchDiff);
+    } else {
+        text = appendSnapshotToTextLegacy(text + _modeTag, snapshot);
     }
-    text = appendSnapshotToText(text + _modeTag, snapshot);
 
     return { content: [{ type: "text", text }] };
 }
@@ -1901,6 +2506,7 @@ async function handleUpdateBlocksTool(args, toolName) {
         mode, client, postId, sessionId: _sessionId, siteName: _siteName,
     });
     if (resolved.error) return resolved.error;
+    const _preState = resolved.currentState || null;  // Phase 2: 差分計算用
     if (resolved.index !== undefined) {
         tp.index = resolved.index;
         delete tp._ref;
@@ -1924,6 +2530,12 @@ async function handleUpdateBlocksTool(args, toolName) {
             _fromInsertBlock, appendToEnd } = (args || {});
     let { newHTML } = (args || {});
 
+    // Phase 5: 差分化オプション
+    // - 単体 target.ref かつ snapshotId ありのみ差分化
+    // - appendToEnd は Legacy 固定（早期リターンで自然に除外）
+    const _inputRef = (snapshotId && args?.target?.ref) ? args.target.ref : null;
+    const _isRefInsert = !!(insertOnly && _inputRef);
+
     // [INSERT_OBSERVE] Step 5: insert_block 経由時の送信パラメータログ
     if (process.env.FRIDAY_DEBUG === '1' && _fromInsertBlock) {
         console.log(`[INSERT_OBSERVE] mcp-send: index=${index}, postId=${postId}, sessionId=${_sessionId || 'none'}, mode=${mode}, appendToEnd=${appendToEnd}, htmlLen=${(newHTML || '').length}`);
@@ -2011,8 +2623,8 @@ async function handleUpdateBlocksTool(args, toolName) {
                     _fromInsertBlock: _fromInsertBlock || false,
                 });
                 const count = result.results?.[0]?.count || 1;
-                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
             }
 
             const result = await client.headlessUpdate(postId, {
@@ -2037,14 +2649,14 @@ async function handleUpdateBlocksTool(args, toolName) {
                 return { content: [{ type: "text", text: `🔍 プレビュー\n\n対象: ${result.results.length} ブロック\n\n${previewText}${deprecationWarning}` }] };
             }
 
-            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
+            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
             if (result.results) {
                 const successCount = result.results.filter(r => r.success).length;
                 const failCount = result.results.filter(r => !r.success).length;
-                return { content: [{ type: "text", text: appendSnapshotToText(`✅ 完了\n\n成功: ${successCount} / 失敗: ${failCount}${deprecationWarning}`, _snap, _refInfo) }] };
+                return { content: [{ type: "text", text: buildUpdateDiffResponse(`✅ 完了\n\n成功: ${successCount} / 失敗: ${failCount}${deprecationWarning}`, _snap, result, _preState, _inputRef, _isRefInsert, _refInfo) }] };
             }
 
-            return { content: [{ type: "text", text: appendSnapshotToText(`✅ 更新完了${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
+            return { content: [{ type: "text", text: buildUpdateDiffResponse(`✅ 更新完了${deprecationWarning}${_modeTag}`, _snap, result, _preState, _inputRef, _isRefInsert, _refInfo) }] };
         } catch (e) {
             const formatted = formatHeadlessConflictError(e);
             if (formatted) return formatted;
@@ -2066,8 +2678,8 @@ async function handleUpdateBlocksTool(args, toolName) {
         if (!result || result.timeout) return timeoutResponse(name, client, args?.site);
         if (!result.success) return errorResponse(name, result.error, args?.site);
         const count = result.inserted || 1;
-        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-        return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
+        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
     }
 
     // target: "selected" の場合 → エディタ状態から選択情報を取得してMCP側で処理
@@ -2121,8 +2733,8 @@ async function handleUpdateBlocksTool(args, toolName) {
             if (!result.success)
                 return errorResponse(name, result.error, args?.site);
             {
-                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${hasTextSelection ? "（カーソル選択モード）" : "（差分）"}${deprecationWarning}`, _snap, _refInfo) }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${hasTextSelection ? "（カーソル選択モード）" : "（差分）"}${deprecationWarning}`, _snap, _refInfo) }] };
             }
         }
 
@@ -2140,8 +2752,8 @@ async function handleUpdateBlocksTool(args, toolName) {
             if (!result.success)
                 return errorResponse(name, result.error, args?.site);
             {
-                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}`, _snap, _refInfo) }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}`, _snap, _refInfo) }] };
             }
         }
 
@@ -2157,8 +2769,8 @@ async function handleUpdateBlocksTool(args, toolName) {
         if (!result.success)
             return errorResponse(name, result.error, args?.site);
         {
-            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-            return { content: [{ type: "text", text: appendSnapshotToText(`✅ 属性更新完了${deprecationWarning}`, _snap, _refInfo) }] };
+            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+            return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ 属性更新完了${deprecationWarning}`, _snap, _refInfo) }] };
         }
     }
 
@@ -2198,16 +2810,16 @@ async function handleUpdateBlocksTool(args, toolName) {
         return { content: [{ type: "text", text: `🔍 プレビュー\n\n対象: ${result.results.length} ブロック\n\n${previewText || "(対象なし)"}${deprecationWarning}` }] };
     }
 
-    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
+    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
     if (result.results) {
         const successCount = result.results.filter(r => r.success && !r.skipped).length;
         const skipCount = result.results.filter(r => r.skipped).length;
         const failCount = result.results.filter(r => !r.success).length;
         const detailText = result.results.filter(r => r.success && r.replaceCount > 0).map(r => `  [${r.index}]: ${r.replaceCount}箇所`).join('\n');
-        return { content: [{ type: "text", text: appendSnapshotToText(`✅ 完了\n\n成功: ${successCount} / スキップ: ${skipCount} / 失敗: ${failCount}\n\n${detailText}${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
+        return { content: [{ type: "text", text: buildUpdateDiffResponse(`✅ 完了\n\n成功: ${successCount} / スキップ: ${skipCount} / 失敗: ${failCount}\n\n${detailText}${deprecationWarning}${_modeTag}`, _snap, result, _preState, _inputRef, _isRefInsert, _refInfo) }] };
     }
 
-    return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
+    return { content: [{ type: "text", text: buildUpdateDiffResponse(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}${_modeTag}`, _snap, result, _preState, _inputRef, _isRefInsert, _refInfo) }] };
 }
 
 // ツール実行のハンドラ
@@ -2763,11 +3375,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     mode, client, postId, sessionId: _sessionId, siteName: _siteName,
                 });
                 if (resolved.error) return resolved.error;
+                const _preState = resolved.currentState || null;  // Phase 2: 差分計算用
 
                 let { index, count, indices } = args;
                 if (resolved.index !== undefined) { index = resolved.index; count = count || 1; }
                 if (resolved.indices !== undefined) { indices = resolved.indices; }
 
+                // Phase 3: 入力 ref を保持（ref + count > 1 は差分化できないので Legacy）
+                const _inputRefs = args?.refs ? [...new Set(args.refs)]
+                    : (args?.ref && (count || 1) <= 1) ? [args.ref]
+                    : null;
+
                 // indices と index/count の排他バリデーション
                 if (indices !== undefined && (index !== undefined || count !== undefined)) {
                     return { content: [{ type: "text", text: "❌ indices と index/count は同時に指定できません。" }], isError: true };
@@ -2788,8 +3406,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         try {
                             const result = await client.headlessDeleteMultiple(postId, uniqueIndices);
                             const details = result.deleted.map(d => `  [${d.index}] ${d.type}`).join('\n');
-                            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                            return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`, _snap) }] };
+                            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                            const _msg = `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`;
+                            if (_inputRefs) {
+                                const changeInfo = buildChangeInfoFromResult('deleted', _snap, result, _preState, { inputRefs: _inputRefs });
+                                if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                            }
+                            return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                         } catch (e) {
                             const formatted = formatHeadlessConflictError(e);
                             if (formatted) return formatted;
@@ -2803,8 +3426,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     if (!result.success)
                         return errorResponse(name, result.error, args?.site);
                     const details = result.deleted.map(d => `  [${d.index}] ${d.type}`).join('\n');
-                    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                    return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`, _snap) }] };
+                    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                    const _msg = `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`;
+                    if (_inputRefs) {
+                        const changeInfo = buildChangeInfoFromResult('deleted', _snap, result, _preState, { inputRefs: _inputRefs });
+                        if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                    }
+                    return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                 }
 
                 // 既存モード（index + count）
@@ -2815,8 +3443,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     try {
                         const result = await client.headlessDelete(postId, index, count || 1);
                         const details = result.deleted.map(d => `  [${d.index}] ${d.type}`).join('\n');
-                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                        return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`, _snap) }] };
+                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                        const _msg = `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`;
+                        if (_inputRefs) {
+                            const changeInfo = buildChangeInfoFromResult('deleted', _snap, result, _preState, { inputRefs: _inputRefs });
+                            if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                        }
+                        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -2830,8 +3463,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!result.success)
                     return errorResponse(name, result.error, args?.site);
                 const details = result.deleted.map(d => `  [${d.index}] ${d.type}`).join('\n');
-                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`, _snap) }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                const _msg = `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`;
+                if (_inputRefs) {
+                    const changeInfo = buildChangeInfoFromResult('deleted', _snap, result, _preState, { inputRefs: _inputRefs });
+                    if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                }
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
             }
 
             case "move_block": {
@@ -2875,12 +3513,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                 // expectedRevision チェック（全モード共通）
                 // ref モード以外でも expectedRevision が指定されていれば revision チェックを実施
+                let _preState = null;  // Phase 2: 差分計算用
                 if (args?.expectedRevision && !hasRef) {
-                    const { error: _revError } = await acquireFreshState({
+                    const { currentState, error: _revError } = await acquireFreshState({
                         expectedRevision: args.expectedRevision,
                         mode, client, postId, sessionId: _sessionId, siteName: _siteName,
                     });
                     if (_revError) return _revError;
+                    _preState = currentState || null;
                 }
 
                 // ref モード: fromRef + beforeRef/afterRef
@@ -2904,6 +3544,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         mode, client, postId, sessionId: _sessionId, siteName: _siteName,
                     });
                     if (_stateError) return _stateError;
+                    _preState = currentState || null;  // Phase 2: 差分計算用
 
                     // ref 解決（同じ currentState で 2 つの ref を解決）
                     try {
@@ -2919,6 +3560,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     // ref → flat に変換完了。以降 flat モードに合流
                 }
 
+                // Phase 4: 入力 ref 保持（ref モード + count <= 1 のみ差分化）
+                const _inputRefs = (hasRef && count <= 1) ? [args.fromRef] : null;
+
                 // 移動結果のレスポンス生成ヘルパー
                 const moveMsg = (moved) => {
                     if (moved?.noop) return `✅ 移動不要（同じ位置）${_mt_mb}`;
@@ -2941,8 +3585,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     if (mode === 'headless') {
                         try {
                             const result = await client.headlessMoveFlat(postId, fromFlat, toFlat, count);
-                            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                            return { content: [{ type: "text", text: appendSnapshotToText(moveMsg(result.moved), _snap) }] };
+                            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                            const _msg = moveMsg(result.moved);
+                            if (_inputRefs) {
+                                const changeInfo = buildChangeInfoFromResult('moved', _snap, result, _preState, { inputRefs: _inputRefs });
+                                if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                            }
+                            return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                         } catch (e) {
                             const formatted = formatHeadlessConflictError(e);
                             if (formatted) return formatted;
@@ -2955,8 +3604,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         return timeoutResponse(name, client, args?.site);
                     if (!result.success)
                         return errorResponse(name, result.error, args?.site);
-                    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                    return { content: [{ type: "text", text: appendSnapshotToText(moveMsg(result.moved), _snap) }] };
+                    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                    const _msg = moveMsg(result.moved);
+                    if (_inputRefs) {
+                        const changeInfo = buildChangeInfoFromResult('moved', _snap, result, _preState, { inputRefs: _inputRefs });
+                        if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                    }
+                    return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                 }
 
                 // 既存モード（from/to トップレベル）
@@ -2967,8 +3621,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (mode === 'headless') {
                     try {
                         const result = await client.headlessMove(postId, from, to, count);
-                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                        return { content: [{ type: "text", text: appendSnapshotToText(moveMsg(result.moved), _snap) }] };
+                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(moveMsg(result.moved), _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -2981,8 +3635,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return timeoutResponse(name, client, args?.site);
                 if (!result.success)
                     return errorResponse(name, result.error, args?.site);
-                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                return { content: [{ type: "text", text: appendSnapshotToText(moveMsg(result.moved), _snap) }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(moveMsg(result.moved), _snap) }] };
             }
 
             case "undo": {
@@ -3041,9 +3695,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     mode, client, postId, sessionId: _sessionId, siteName: _siteName,
                 });
                 if (resolved.error) return resolved.error;
+                const _preState = resolved.currentState || null;  // Phase 2: 差分計算用
 
                 const index = resolved.index !== undefined ? resolved.index : args?.index;
 
+                // Phase 3: 入力 ref を保持（index 経路は差分化しない）
+                const _inputRef = args?.ref || null;
+
                 if (mode === 'headless') {
                     const _guard = await guardHeadlessConflict(postId, client, name);
                     if (_guard) return _guard;
@@ -3052,8 +3710,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                     try {
                         const result = await client.headlessDuplicate(postId, index);
-                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                        return { content: [{ type: "text", text: appendSnapshotToText(`✅ ブロック複製完了 (index ${result.duplicated.index} → ${result.duplicated.newIndex})${_mt_dup}`, _snap) }] };
+                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                        const _msg = `✅ ブロック複製完了 (index ${result.duplicated.index} → ${result.duplicated.newIndex})${_mt_dup}`;
+                        if (_inputRef) {
+                            const changeInfo = buildChangeInfoFromResult('duplicated', _snap, result, _preState, { inputRef: _inputRef });
+                            if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                        }
+                        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -3066,8 +3729,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return timeoutResponse(name, client, args?.site);
                 if (!result.success)
                     return errorResponse(name, result.error, args?.site);
-                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ブロック複製完了${_mt_dup}`, _snap) }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                const _msg = `✅ ブロック複製完了${_mt_dup}`;
+                if (_inputRef) {
+                    const changeInfo = buildChangeInfoFromResult('duplicated', _snap, result, _preState, { inputRef: _inputRef });
+                    if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                }
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
             }
 
             case "save_post": {
@@ -3421,7 +4089,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
 
             case "get_selection": {
-                const { mode, postId: _postId, sessionId: _sessionId, message, client } = await resolveMode(args, name);
+                const { mode, postId: _postId, sessionId: _sessionId, message, client, siteName } = await resolveMode(args, name);
                 if (mode === 'error') {
                     return errorResponse(name, message, args?.site);
                 }
@@ -3437,16 +4105,48 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         content: [{ type: "text", text: `ブロックが選択されていません。${_mt_gs}` }],
                     };
                 }
+
+                // ref 対応: fresh state から snapshot を毎回新規作成
+                // safetyCritical: true — stale Store へのフォールバックを防ぐ
+                const _siteName_gs = siteName || args?.site || 'default';
+                let _snapInfo = null;
+                try {
+                    const freshState = await getCurrentStructure(mode, client, _postId, _sessionId, { safetyCritical: true });
+                    if (freshState?.allBlocks?.length > 0) {
+                        _snapInfo = buildSnapshotFromState(freshState, mode, _postId, _sessionId, _siteName_gs);
+                    }
+                } catch (_e) {
+                    // fresh state 取得失敗 → ref なしで index-only にフォールバック
+                }
+
                 // 複数選択
                 if (sel.isMultiSelect && sel.blockIds) {
                     let text = `選択中: ${sel.blockIds.length}ブロック\n` +
                         `タイプ: ${sel.blockTypes?.join(", ")}\n` +
-                        `位置: ${sel.blockIndices?.join(", ")}${_mt_gs}`;
+                        `位置: ${sel.blockIndices?.join(", ")}`;
+                    if (_snapInfo && sel.blockIndices?.length > 0) {
+                        const refs = sel.blockIndices
+                            .map(idx => _snapInfo.blocks?.find(b => b.index === idx)?.ref)
+                            .filter(Boolean);
+                        // 全数一致のときだけ refs を返す（部分一致は AI を誤誘導するため）
+                        if (refs.length === sel.blockIndices.length) {
+                            text += `\nrefs: ${refs.join(", ")}`;
+                            text += `\n[snapshot:${_snapInfo.snapshotId} rev:${_snapInfo.revision}]`;
+                        }
+                    }
+                    text += _mt_gs;
                     return { content: [{ type: "text", text }] };
                 }
                 // 単一選択
                 let text = `選択中: ${sel.blockType}\n` +
                     `位置: index ${sel.blockIndex}`;
+                if (_snapInfo) {
+                    const refEntry = _snapInfo.blocks?.find(b => b.index === sel.blockIndex);
+                    if (refEntry) {
+                        text += `\nref: ${refEntry.ref}`;
+                        text += `\n[snapshot:${_snapInfo.snapshotId} rev:${_snapInfo.revision}]`;
+                    }
+                }
                 if (sel.textSelection?.text) {
                     text += `\n\nカーソル選択テキスト: "${sel.textSelection.text}"`;
                     if (sel.textSelection.context) {
@@ -3474,6 +4174,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const _siteName = siteName || args?.site || 'default';
 
                 const { action } = (args || {});
+                const _inputRef = args?.ref || null;
                 if (!action) {
                     return { content: [{ type: "text", text: "❌ action は必須です" }], isError: true };
                 }
@@ -3490,6 +4191,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     mode, client, postId, sessionId: _sessionId, siteName: _siteName,
                 });
                 if (resolved.error) return resolved.error;
+                const _preState = resolved.currentState || null;  // Phase 2: 差分計算用
 
                 const index = resolved.index !== undefined ? resolved.index : args?.index;
                 if (index === undefined) {
@@ -3536,8 +4238,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         if (!_isWrite) {
                             return { content: [{ type: "text", text: formatStructure(result) + _mt_to }] };
                         }
-                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                        return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${action} 完了: ${JSON.stringify(result.detail || result)}${_mt_to}`, _snap) }] };
+                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                        const _msg = `✅ ${action} 完了: ${JSON.stringify(result.detail || result)}${_mt_to}`;
+                        if (_inputRef) {
+                            const changedIndex = result.targetIndex ?? index;
+                            const syntheticResult = { changes: [{ oldIndex: changedIndex, newIndices: [changedIndex], success: true }] };
+                            const changeInfo = buildChangeInfoFromResult('updated', _snap, syntheticResult, _preState);
+                            if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                        }
+                        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -3555,8 +4264,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!_isWrite) {
                     return { content: [{ type: "text", text: formatStructure(result.structure) + _mt_to }] };
                 }
-                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
-                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${action} 完了: ${JSON.stringify(result.detail || {})}${_mt_to}`, _snap) }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                const _msg = `✅ ${action} 完了: ${JSON.stringify(result.detail || {})}${_mt_to}`;
+                if (_inputRef) {
+                    const changedIndex = result.targetIndex ?? index;
+                    const syntheticResult = { changes: [{ oldIndex: changedIndex, newIndices: [changedIndex], success: true }] };
+                    const changeInfo = buildChangeInfoFromResult('updated', _snap, syntheticResult, _preState);
+                    if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                }
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
             }
 
             case "open_in_browser": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "friday-mcp-v2",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "WordPress MCP Server for Claude Code - REST API direct communication",
   "type": "module",
   "main": "dist/mcp-server.js",