@diffexai/diffex 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.3.2] - 2026-09-29
+
+### New Features
+
+- Added persistent plan context with stable step IDs and optional success criteria, attached to every model request and restored across session resume, compaction, and tree navigation.
+  See [Plan Mode](docs/usage.md#plan-mode) ([#249](https://github.com/diffexai/diffex/pull/249)).
+- Added parallel tool execution phases that overlap independent calls around sequential tool barriers.
+  See [Extensions](docs/extensions.md) ([#250](https://github.com/diffexai/diffex/pull/250)).
+- Added a cache hit rate to the interactive footer alongside context usage ([#249](https://github.com/diffexai/diffex/pull/249)).
+
+### Added
+
+- Added persistent plan step identity with stable IDs and optional success criteria, attached as hidden current-task context to every model request and restored across session resume, compaction, and tree navigation.
+  See [Plan Mode](docs/usage.md#plan-mode) and [SDK tools](docs/sdk.md#tools) ([#249](https://github.com/diffexai/diffex/pull/249)).
+- Added a cache hit rate to the interactive footer alongside context usage ([#249](https://github.com/diffexai/diffex/pull/249)).
+- Added parallel tool execution phases that overlap consecutive parallel-capable calls around individual sequential barriers, such as `update_plan`.
+  See [Extensions](docs/extensions.md#tool_execution_start--tool_execution_update--tool_execution_end) ([#250](https://github.com/diffexai/diffex/pull/250)).
+
+### Changed
+
+- Excluded plan tool history and saved plan snapshots from compaction and branch summaries; the latest attached snapshot supersedes retained plan context ([#251](https://github.com/diffexai/diffex/pull/251)).
+
+### Fixed
+
+- Fixed plan cache-prefix preservation so ordinary requests reuse the existing prompt prefix ([#249](https://github.com/diffexai/diffex/pull/249)).
+- Fixed plan restoration on tree navigation to use the destination branch's authoritative plan snapshot ([#249](https://github.com/diffexai/diffex/pull/249)).
+- Fixed settled tool output being remeasured on every keystroke, keeping typing responsive as session history grows ([#249](https://github.com/diffexai/diffex/pull/249)).
+
 ## [0.3.1] - 2026-09-20
 
 ### New Features

package/dist/core/agent-session.d.ts

@@ -253,7 +253,6 @@ export declare class AgentSession {
     private _followUpMessages;
     /** Messages queued to be included with the next user prompt as context ("asides"). */
     private _pendingNextTurnMessages;
-    private _pendingCurrentPlanRestoration;
     private readonly _skillReferenceSnapshots;
     private readonly _skillEnablementOverrides;
     private _activeSkillTrace;
@@ -337,10 +336,6 @@ export declare class AgentSession {
      */
     private _installAgentToolHooks;
     private _installAgentNextTurnRefresh;
-    private _installAgentContextRestoration;
-    private _armInitialCurrentPlanRestoration;
-    private _armCurrentPlanRestorationIfActive;
-    private _consumePendingCurrentPlanRestoration;
     /** Emit an event to all listeners */
     private _emit;
     private _emitQueueUpdate;

package/dist/core/agent-session.js

@@ -26,7 +26,7 @@ import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth
 import { executeBashWithOperations } from "./bash-executor.js";
 import { CHANGE_COLLABORATION_MODE, COLLABORATION_MODE_CUSTOM_TYPE, GET_COLLABORATION_MODE, IS_COLLABORATION_MODE_BUSY, PLAN_MODE_SYSTEM_PROMPT, PLAN_MODE_TOOL_NAMES, planHandoffSettlementGuards, SUBSCRIBE_PROMPT_ADMISSION, } from "./collaboration-mode.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
-import { createSessionUpdatePlanToolDefinition, resolveCurrentPlanState } from "./current-plan-state.js";
+import { createSessionUpdatePlanToolDefinition, formatCurrentPlanSnapshot } from "./current-plan-state.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
@@ -109,8 +109,6 @@ function estimateMessagesTokens(messages) {
 // ============================================================================
 /** Standard thinking levels */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
-const CURRENT_PLAN_RESTORATION_CUSTOM_TYPE = "diffex.current-plan-restoration";
-const CURRENT_PLAN_RESTORATION_REMINDER = "Reminder: restored context is not proof of completion. Verify current state before claiming work is done.";
 const MAX_PENDING_SUBAGENT_ESCALATION_CHARACTERS = 8_000;
 const INCOMPATIBLE_SUBAGENT_PARENT_HOOKS = [
     "resources_discover",
@@ -145,7 +143,6 @@ export class AgentSession {
     _followUpMessages = [];
     /** Messages queued to be included with the next user prompt as context ("asides"). */
     _pendingNextTurnMessages = [];
-    _pendingCurrentPlanRestoration = false;
     _skillReferenceSnapshots = new Map();
     _skillEnablementOverrides = new Map();
     _activeSkillTrace;
@@ -245,12 +242,10 @@ export class AgentSession {
             : createEvolvedSkillCatalog(config.harnessVersionBundle, config.workspaceIdentity));
         this._telemetryContext = config.telemetryContext ?? NOOP_TELEMETRY_CONTEXT;
         this._lifecycleObserver = config.lifecycleObserver;
-        this._armInitialCurrentPlanRestoration();
         // Always subscribe to agent events for internal handling
         // (session persistence, extensions, auto-compaction, retry logic)
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
-        this._installAgentContextRestoration();
         this._installAgentNextTurnRefresh();
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
@@ -434,55 +429,6 @@ export class AgentSession {
             };
         };
     }
-    _installAgentContextRestoration() {
-        const previousTransformContext = this.agent.transformContext;
-        this.agent.transformContext = async (messages, signal) => {
-            const transformedMessages = previousTransformContext
-                ? await previousTransformContext(messages, signal)
-                : messages;
-            return this._consumePendingCurrentPlanRestoration(transformedMessages);
-        };
-    }
-    _armInitialCurrentPlanRestoration() {
-        if (this._sessionStartEvent.reason !== "startup" && this._sessionStartEvent.reason !== "resume") {
-            return;
-        }
-        this._armCurrentPlanRestorationIfActive();
-    }
-    _armCurrentPlanRestorationIfActive() {
-        if (resolveCurrentPlanState(this.sessionManager).status === "active") {
-            this._pendingCurrentPlanRestoration = true;
-        }
-    }
-    _consumePendingCurrentPlanRestoration(messages) {
-        if (!this._pendingCurrentPlanRestoration) {
-            return messages;
-        }
-        const state = resolveCurrentPlanState(this.sessionManager);
-        this._pendingCurrentPlanRestoration = false;
-        if (state.status !== "active") {
-            return messages;
-        }
-        const lines = [
-            "Restored unfinished update_plan checklist from the current session. Use this hidden context to continue the work.",
-        ];
-        if (state.operation.explanation !== undefined) {
-            lines.push("", "Explanation:", state.operation.explanation);
-        }
-        lines.push("", "Checklist:");
-        for (const [index, item] of state.operation.plan.entries()) {
-            lines.push(`${index + 1}. [${item.status}] ${item.step}`);
-        }
-        lines.push("", CURRENT_PLAN_RESTORATION_REMINDER);
-        const restoredContext = {
-            role: "custom",
-            customType: CURRENT_PLAN_RESTORATION_CUSTOM_TYPE,
-            content: [{ type: "text", text: lines.join("\n") }],
-            display: false,
-            timestamp: Date.now(),
-        };
-        return [...messages, restoredContext];
-    }
     // =========================================================================
     // Event Subscription
     // =========================================================================
@@ -1809,7 +1755,6 @@ export class AgentSession {
                 return;
             pendingCompaction.commit();
             pendingCompaction = undefined;
-            this._armCurrentPlanRestorationIfActive();
         };
         const rollbackPendingCompaction = () => {
             if (!pendingCompaction)
@@ -2729,7 +2674,8 @@ export class AgentSession {
         this._branchSummaryAbortController?.abort();
     }
     async _recordSuccessfulCompaction(options) {
-        const transaction = appendCompactionTransaction(this.sessionManager, options.summary, options.firstKeptEntryId, options.tokensBefore, options.details, options.fromExtension, options.usage);
+        const summary = `${options.summary}\n\n${formatCurrentPlanSnapshot(this.sessionManager)}`;
+        const transaction = appendCompactionTransaction(this.sessionManager, summary, options.firstKeptEntryId, options.tokensBefore, options.details, options.fromExtension, options.usage);
         const sessionContext = this.sessionManager.buildSessionContext();
         this.agent.state.messages = sessionContext.messages;
         const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
@@ -2763,15 +2709,13 @@ export class AgentSession {
         else
             transaction.commit();
         const compactionResult = {
-            summary: options.summary,
+            summary,
             firstKeptEntryId: options.firstKeptEntryId,
             tokensBefore: options.tokensBefore,
             estimatedTokensAfter,
             usage: options.usage,
             details: options.details,
         };
-        if (!options.deferCommit)
-            this._armCurrentPlanRestorationIfActive();
         return compactionResult;
     }
     /**
@@ -3759,7 +3703,8 @@ export class AgentSession {
             let summaryEntry;
             const mutateLeaf = () => {
                 if (summaryText) {
-                    const summaryId = this.sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension, summaryUsage);
+                    const summary = `${summaryText}\n\nThe plan below is authoritative for the selected conversation branch. Plan references in the exploration summary above are historical.\n${formatCurrentPlanSnapshot(this.sessionManager, newLeafId)}`;
+                    const summaryId = this.sessionManager.branchWithSummary(newLeafId, summary, summaryDetails, fromExtension, summaryUsage);
                     summaryEntry = this.sessionManager.getEntry(summaryId);
                     if (label)
                         this.sessionManager.appendLabelChange(summaryId, label);

package/dist/core/compaction/branch-summarization.js

@@ -7,7 +7,7 @@
 import { contentText } from "@diffexai/diffex-ai";
 import { convertToLlm, createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "../messages.js";
 import { completeSummarization, estimateTokens } from "./compaction.js";
-import { computeFileLists, createFileOps, extractFileOpsFromMessage, formatFileOperations, SUMMARIZATION_SYSTEM_PROMPT, serializeConversation, } from "./utils.js";
+import { computeFileLists, createFileOps, excludePlanItems, extractFileOpsFromMessage, formatFileOperations, SUMMARIZATION_SYSTEM_PROMPT, serializeConversation, } from "./utils.js";
 // ============================================================================
 // Entry Collection
 // ============================================================================
@@ -120,7 +120,8 @@ export function prepareBranchEntries(entries, tokenBudget = 0) {
     // Second pass: walk from newest to oldest, adding messages until token budget
     for (let i = entries.length - 1; i >= 0; i--) {
         const entry = entries[i];
-        const message = getMessageFromEntry(entry);
+        const rawMessage = getMessageFromEntry(entry);
+        const message = rawMessage ? excludePlanItems([rawMessage])[0] : undefined;
         if (!message)
             continue;
         // Extract file ops from assistant messages (tool calls)

package/dist/core/compaction/compaction.js

@@ -8,8 +8,9 @@ import { NOOP_TELEMETRY_CONTEXT, startAiSpan, } from "@diffexai/diffex-agent-cor
 import { contentText, retryAssistantCall, uuidv7 } from "@diffexai/diffex-ai";
 import { completeSimple } from "@diffexai/diffex-ai/compat";
 import { convertToLlm } from "../messages.js";
+import { stripCurrentPlanSnapshot } from "../plan-snapshot.js";
 import { buildSessionContext, sessionEntryToContextMessages, } from "../session-manager.js";
-import { computeFileLists, createFileOps, extractFileOpsFromMessage, formatFileOperations, SUMMARIZATION_SYSTEM_PROMPT, serializeConversation, } from "./utils.js";
+import { computeFileLists, createFileOps, excludePlanItems, extractFileOpsFromMessage, formatFileOperations, SUMMARIZATION_SYSTEM_PROMPT, serializeConversation, } from "./utils.js";
 /**
  * Extract file operations from messages and previous compaction entries.
  */
@@ -494,13 +495,14 @@ export async function generateSummary(currentMessages, model, reserveTokens, api
 export async function generateSummaryWithUsage(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks, telemetryContext) {
     const maxTokens = Math.min(Math.floor(0.8 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
     // Use update prompt if we have a previous summary, otherwise initial prompt
+    previousSummary = previousSummary === undefined ? undefined : stripCurrentPlanSnapshot(previousSummary);
     let basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;
     if (customInstructions) {
         basePrompt = `${basePrompt}\n\nAdditional focus: ${customInstructions}`;
     }
     // Serialize conversation to text so model doesn't try to continue it
     // Convert to LLM messages first (handles custom types like bashExecution, custom, etc.)
-    const llmMessages = convertToLlm(currentMessages);
+    const llmMessages = convertToLlm(excludePlanItems(currentMessages));
     const conversationText = serializeConversation(llmMessages);
     // Build the prompt with conversation wrapped in tags
     let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
@@ -538,7 +540,7 @@ export function prepareCompaction(pathEntries, settings) {
     let boundaryStart = 0;
     if (prevCompactionIndex >= 0) {
         const prevCompaction = pathEntries[prevCompactionIndex];
-        previousSummary = prevCompaction.summary;
+        previousSummary = stripCurrentPlanSnapshot(prevCompaction.summary);
         const firstKeptEntryIndex = pathEntries.findIndex((entry) => entry.id === prevCompaction.firstKeptEntryId);
         boundaryStart = firstKeptEntryIndex >= 0 ? firstKeptEntryIndex : prevCompactionIndex + 1;
     }
@@ -581,8 +583,8 @@ export function prepareCompaction(pathEntries, settings) {
     }
     return {
         firstKeptEntryId,
-        messagesToSummarize,
-        turnPrefixMessages,
+        messagesToSummarize: excludePlanItems(messagesToSummarize),
+        turnPrefixMessages: excludePlanItems(turnPrefixMessages),
         isSplitTurn: cutPoint.isSplitTurn,
         tokensBefore,
         previousSummary,
@@ -620,7 +622,7 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
     let summary;
     let summaryUsage;
     if (isSplitTurn && turnPrefixMessages.length > 0) {
-        let historyText = "No prior history.";
+        let historyText = previousSummary ?? "No prior history.";
         let historyUsage;
         if (messagesToSummarize.length > 0) {
             const historyResult = await generateSummaryWithUsage(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks, telemetryContext);
@@ -657,7 +659,7 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
  */
 async function generateTurnPrefixSummary(messages, model, reserveTokens, apiKey, headers, env, signal, thinkingLevel, streamFn, retry, callbacks, telemetryContext) {
     const maxTokens = Math.min(Math.floor(0.5 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY); // Smaller budget for turn prefix
-    const llmMessages = convertToLlm(messages);
+    const llmMessages = convertToLlm(excludePlanItems(messages));
     const conversationText = serializeConversation(llmMessages);
     const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
     const summarizationMessages = [

package/dist/core/compaction/utils.d.ts

@@ -25,6 +25,8 @@ export declare function computeFileLists(fileOps: FileOperations): {
  * Format file operations as XML tags for summary.
  */
 export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string;
+/** Exclude plan data from a context projection without changing persisted messages. */
+export declare function excludePlanItems(messages: AgentMessage[]): AgentMessage[];
 /**
  * Serialize LLM messages to text for summarization.
  * This prevents the model from treating it as a conversation to continue.
@@ -32,6 +34,7 @@ export declare function formatFileOperations(readFiles: string[], modifiedFiles:
  *
  * Tool results are truncated to keep the summarization request within
  * reasonable token budgets. Full content is not needed for summarization.
+ * Plan calls and results are omitted because the latest plan is attached separately.
  */
 export declare function serializeConversation(messages: Message[]): string;
 export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";

package/dist/core/compaction/utils.js

@@ -2,6 +2,7 @@
  * Shared utilities for compaction and branch summarization.
  */
 import { contentText } from "@diffexai/diffex-ai";
+import { stripCurrentPlanSnapshot } from "../plan-snapshot.js";
 export function createFileOps() {
     return {
         read: new Set(),
@@ -71,6 +72,21 @@ export function formatFileOperations(readFiles, modifiedFiles) {
 // ============================================================================
 // Message Serialization
 // ============================================================================
+/** Exclude plan data from a context projection without changing persisted messages. */
+export function excludePlanItems(messages) {
+    return messages.flatMap((message) => {
+        if (message.role === "toolResult" && message.toolName === "update_plan")
+            return [];
+        if (message.role === "assistant") {
+            const content = message.content.filter((block) => block.type !== "toolCall" || block.name !== "update_plan");
+            return content.length > 0 ? [{ ...message, content }] : [];
+        }
+        if (message.role === "compactionSummary" || message.role === "branchSummary") {
+            return [{ ...message, summary: stripCurrentPlanSnapshot(message.summary) }];
+        }
+        return [message];
+    });
+}
 /** Maximum characters for a tool result in serialized summaries. */
 const TOOL_RESULT_MAX_CHARS = 2000;
 /**
@@ -90,6 +106,7 @@ function truncateForSummary(text, maxChars) {
  *
  * Tool results are truncated to keep the summarization request within
  * reasonable token budgets. Full content is not needed for summarization.
+ * Plan calls and results are omitted because the latest plan is attached separately.
  */
 export function serializeConversation(messages) {
     const parts = [];
@@ -107,6 +124,8 @@ export function serializeConversation(messages) {
                     thinkingParts.push(block.thinking);
                 }
                 else if (block.type === "toolCall") {
+                    if (block.name === "update_plan")
+                        continue;
                     const args = block.arguments;
                     const argsStr = Object.entries(args)
                         .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
@@ -125,6 +144,8 @@ export function serializeConversation(messages) {
             }
         }
         else if (msg.role === "toolResult") {
+            if (msg.toolName === "update_plan")
+                continue;
             const content = contentText(msg.content, "");
             if (content) {
                 parts.push(`[Tool result]: ${truncateForSummary(content, TOOL_RESULT_MAX_CHARS)}`);

package/dist/core/current-plan-state.d.ts

@@ -15,5 +15,6 @@ export type CurrentPlanState = {
     operation: UpdatePlanToolDetails;
 };
 export declare function appendCurrentPlanRecord(sessionManager: Pick<SessionManager, "appendCustomEntry">, operation: UpdatePlanToolDetails): string;
-export declare function resolveCurrentPlanState(sessionManager: Pick<SessionManager, "getBranch">): CurrentPlanState;
-export declare function createSessionUpdatePlanToolDefinition(sessionManager: Pick<SessionManager, "appendCustomEntry">): ReturnType<typeof createUpdatePlanToolDefinition>;
+export declare function resolveCurrentPlanState(sessionManager: Pick<SessionManager, "getBranch">, fromId?: string | null): CurrentPlanState;
+export declare function formatCurrentPlanSnapshot(sessionManager: Pick<SessionManager, "getBranch">, fromId?: string | null): string;
+export declare function createSessionUpdatePlanToolDefinition(sessionManager: Pick<SessionManager, "appendCustomEntry" | "getBranch">): ReturnType<typeof createUpdatePlanToolDefinition>;

package/dist/core/current-plan-state.js

@@ -1,10 +1,11 @@
-import { createUpdatePlanToolDefinition, parseUpdatePlanOperation, } from "./tools/update-plan.js";
+import { CURRENT_PLAN_SNAPSHOT_PREFIX } from "./plan-snapshot.js";
+import { createUpdatePlanToolDefinition, resolveUpdatePlanOperation, } from "./tools/update-plan.js";
 export const CURRENT_PLAN_CUSTOM_ENTRY_TYPE = "diffex.current-plan";
 export function appendCurrentPlanRecord(sessionManager, operation) {
-    return sessionManager.appendCustomEntry(CURRENT_PLAN_CUSTOM_ENTRY_TYPE, parseUpdatePlanOperation(operation));
+    return sessionManager.appendCustomEntry(CURRENT_PLAN_CUSTOM_ENTRY_TYPE, resolveUpdatePlanOperation(operation));
 }
-export function resolveCurrentPlanState(sessionManager) {
-    const branch = sessionManager.getBranch();
+export function resolveCurrentPlanState(sessionManager, fromId) {
+    const branch = fromId === null ? [] : sessionManager.getBranch(fromId);
     for (let index = branch.length - 1; index >= 0; index--) {
         const entry = branch[index];
         if (entry.type !== "custom" || entry.customType !== CURRENT_PLAN_CUSTOM_ENTRY_TYPE) {
@@ -12,7 +13,7 @@ export function resolveCurrentPlanState(sessionManager) {
         }
         let operation;
         try {
-            operation = parseUpdatePlanOperation(entry.data);
+            operation = resolveUpdatePlanOperation(entry.data);
         }
         catch {
             return { status: "corrupt" };
@@ -24,8 +25,24 @@ export function resolveCurrentPlanState(sessionManager) {
     }
     return { status: "absent" };
 }
+export function formatCurrentPlanSnapshot(sessionManager, fromId) {
+    const state = resolveCurrentPlanState(sessionManager, fromId);
+    const plan = state.status === "active"
+        ? state.operation.plan
+        : state.status === "inactive" && "plan" in state.operation
+            ? state.operation.plan
+            : [];
+    return `${CURRENT_PLAN_SNAPSHOT_PREFIX}${JSON.stringify({ plan }, null, 2)}`;
+}
 export function createSessionUpdatePlanToolDefinition(sessionManager) {
-    const definition = createUpdatePlanToolDefinition();
+    const definition = createUpdatePlanToolDefinition(undefined, () => {
+        const state = resolveCurrentPlanState(sessionManager);
+        if (state.status === "active")
+            return state.operation.plan;
+        if (state.status === "inactive" && "plan" in state.operation)
+            return state.operation.plan;
+        return undefined;
+    });
     const execute = definition.execute;
     return {
         ...definition,

package/dist/core/plan-snapshot.d.ts

@@ -0,0 +1,3 @@
+export declare const CURRENT_PLAN_SNAPSHOT_PREFIX = "Current task context (latest plan):\n";
+/** Remove only the structured plan snapshot appended to a summary. */
+export declare function stripCurrentPlanSnapshot(summary: string): string;

package/dist/core/plan-snapshot.js

@@ -0,0 +1,23 @@
+export const CURRENT_PLAN_SNAPSHOT_PREFIX = "Current task context (latest plan):\n";
+// Branch navigation attaches this authority paragraph with the snapshot.
+const BRANCH_PLAN_AUTHORITY = "The plan below is authoritative for the selected conversation branch. Plan references in the exploration summary above are historical.\n";
+/** Remove only the structured plan snapshot appended to a summary. */
+export function stripCurrentPlanSnapshot(summary) {
+    const index = summary.lastIndexOf(CURRENT_PLAN_SNAPSHOT_PREFIX);
+    const authorityStart = index - BRANCH_PLAN_AUTHORITY.length;
+    const hasBranchAuthority = authorityStart >= 0 && summary.slice(authorityStart, index) === BRANCH_PLAN_AUTHORITY;
+    const attachmentStart = hasBranchAuthority ? authorityStart : index;
+    if (index < 0 || (attachmentStart > 0 && summary.slice(attachmentStart - 2, attachmentStart) !== "\n\n")) {
+        return summary;
+    }
+    try {
+        const snapshot = JSON.parse(summary.slice(index + CURRENT_PLAN_SNAPSHOT_PREFIX.length));
+        if (typeof snapshot !== "object" || snapshot === null || !("plan" in snapshot) || !Array.isArray(snapshot.plan)) {
+            return summary;
+        }
+    }
+    catch {
+        return summary;
+    }
+    return summary.slice(0, attachmentStart === 0 ? 0 : attachmentStart - 2);
+}

package/dist/core/session-manager.js

@@ -7,7 +7,9 @@ import { createInterface } from "readline";
 import { StringDecoder } from "string_decoder";
 import { getAgentDir as getDefaultAgentDir, getSessionsDir } from "../config.js";
 import { normalizePath, resolvePath } from "../utils/paths.js";
+import { excludePlanItems } from "./compaction/utils.js";
 import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "./messages.js";
+import { stripCurrentPlanSnapshot } from "./plan-snapshot.js";
 export const CURRENT_SESSION_VERSION = 3;
 function createSessionId() {
     return uuidv7();
@@ -237,7 +239,25 @@ export function buildContextEntries(entries, leafId, byId) {
 export function buildSessionContext(entries, leafId, byId) {
     const path = buildSessionPath(entries, leafId, byId);
     const { thinkingLevel, model } = getSessionContextSettings(path);
-    const messages = buildContextEntries(entries, leafId, byId).flatMap(sessionEntryToContextMessages);
+    const contextEntries = buildContextEntries(entries, leafId, byId);
+    const contextEntryIds = new Set(contextEntries.map((entry) => entry.id));
+    // Context order puts the latest compaction before its retained tail. Use path
+    // order to find the snapshot that supersedes earlier plan calls and summaries.
+    let snapshotIndex = -1;
+    for (let i = path.length - 1; i >= 0; i--) {
+        const entry = path[i];
+        if (contextEntryIds.has(entry.id) &&
+            (entry.type === "compaction" || entry.type === "branch_summary") &&
+            stripCurrentPlanSnapshot(entry.summary) !== entry.summary) {
+            snapshotIndex = i;
+            break;
+        }
+    }
+    const supersededEntryIds = new Set(path.slice(0, Math.max(0, snapshotIndex)).map((entry) => entry.id));
+    const messages = contextEntries.flatMap((entry) => {
+        const projected = sessionEntryToContextMessages(entry);
+        return supersededEntryIds.has(entry.id) ? excludePlanItems(projected) : projected;
+    });
     return { messages, thinkingLevel, model };
 }
 /**

package/dist/core/tools/update-plan.d.ts

@@ -4,30 +4,51 @@ import type { ToolDefinition } from "../extensions/types.ts";
 declare const UPDATE_PLAN_STATUSES: readonly ["pending", "in_progress", "completed"];
 export type UpdatePlanStatus = (typeof UPDATE_PLAN_STATUSES)[number];
 export interface UpdatePlanItem {
+    id: string;
     step: string;
     status: UpdatePlanStatus;
+    success_criteria?: string[];
 }
 export type UpdatePlanToolInput = {
     plan: UpdatePlanItem[];
     explanation?: string;
+} | {
+    update: {
+        id: string;
+        step?: string;
+        status?: UpdatePlanStatus;
+        success_criteria?: string[];
+    };
+    explanation?: string;
 } | {
     clear: true;
     explanation?: string;
 };
-export type UpdatePlanToolDetails = UpdatePlanToolInput;
+export type UpdatePlanToolDetails = Exclude<UpdatePlanToolInput, {
+    update: unknown;
+}>;
 declare const updatePlanSchema: Type.TObject<{
     plan: Type.TOptional<Type.TArray<Type.TObject<{
+        id: Type.TString;
         step: Type.TString;
         status: Type.TUnsafe<"completed" | "in_progress" | "pending">;
+        success_criteria: Type.TOptional<Type.TArray<Type.TString>>;
     }>>>;
+    update: Type.TOptional<Type.TObject<{
+        id: Type.TString;
+        step: Type.TOptional<Type.TString>;
+        status: Type.TOptional<Type.TUnsafe<"completed" | "in_progress" | "pending">>;
+        success_criteria: Type.TOptional<Type.TArray<Type.TString>>;
+    }>>;
     clear: Type.TOptional<Type.TLiteral<true>>;
     explanation: Type.TOptional<Type.TString>;
 }>;
 export declare const updatePlanToolSystemPromptContribution: {
-    readonly snippet: "track progress with an ordered task checklist";
-    readonly guidelines: readonly ["Use update_plan for complex, ambiguous, dependent, long-running, or multi-part work, when the user requests a plan, or when checkpoints would improve collaboration; skip it for simple or immediately executable work.", "Write short, ordered, outcome-focused steps with observable evidence where useful; do not narrate commands or pad the checklist with obvious actions.", "Include final verification when correctness requires it.", "Update the checklist at meaningful milestones and mark completed work before moving on.", "Explain material replanning, omit explanations for routine progress, and use clear: true only when abandoning the checklist.", "Publishing the checklist communicates progress but does not execute, schedule, or prove completion of its steps."];
+    readonly snippet: "persist an ordered plan with step IDs and optional success criteria";
+    readonly guidelines: readonly ["Use update_plan for complex, ambiguous, dependent, long-running, or multi-part work, when the user requests a plan, or when checkpoints would improve collaboration; skip it for simple or immediately executable work.", "Write short, ordered, outcome-focused steps. Give each step a stable ID and add optional success_criteria for subtasks needing validation.", "Include final verification when correctness requires it.", "Update by ID at meaningful milestones; retain IDs when rewording, reordering, or changing status.", "Explain material replanning, omit explanations for routine progress, and use clear: true only when abandoning the checklist.", "Publishing the checklist communicates progress but does not execute, schedule, or prove completion of its steps."];
 };
-export declare function parseUpdatePlanOperation(input: unknown): UpdatePlanToolDetails;
-export declare function createUpdatePlanToolDefinition(): ToolDefinition<typeof updatePlanSchema, UpdatePlanToolDetails>;
-export declare function createUpdatePlanTool(): AgentTool<typeof updatePlanSchema>;
+export declare function parseUpdatePlanOperation(input: unknown): UpdatePlanToolInput;
+export declare function resolveUpdatePlanOperation(input: unknown, currentPlan?: readonly UpdatePlanItem[]): UpdatePlanToolDetails;
+export declare function createUpdatePlanToolDefinition(_cwd?: string, getCurrentPlan?: () => readonly UpdatePlanItem[] | undefined): ToolDefinition<typeof updatePlanSchema, UpdatePlanToolDetails>;
+export declare function createUpdatePlanTool(getCurrentPlan?: () => readonly UpdatePlanItem[] | undefined): AgentTool<typeof updatePlanSchema>;
 export {};