@diffexai/diffex 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # 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
+
+- Added opt-in background services that survive CLI and subagent exit, with explicit environment ownership.
+  See [Background process lifetime](docs/background-processes.md) ([#242](https://github.com/diffexai/diffex/pull/242)).
+
+### Added
+
+- Added CLI and SDK options for environment-owned background processes on Linux and macOS, with durable ownership records and inherited policy for child sessions.
+  See [Background process lifetime](docs/background-processes.md) ([#242](https://github.com/diffexai/diffex/pull/242)).
+
+### Fixed
+
+- Fixed successful background services being terminated after ownership transfers to the environment, including on later failures, interruption, session replacement, and disposal ([#242](https://github.com/diffexai/diffex/pull/242)).
+- Fixed print-mode shutdown to await shared runtime disposal and handle SIGINT cleanup ([#242](https://github.com/diffexai/diffex/pull/242)).
+
 ## [0.3.0] - 2026-09-20
 
 ### New Features

package/dist/cli/args.d.ts

@@ -6,6 +6,8 @@ import type { ExtensionFlag } from "../core/extensions/types.ts";
 import type { TuiMode } from "../core/settings-manager.ts";
 export type Mode = "text" | "json" | "rpc";
 export interface Args {
+    backgroundProcessLifetime?: "session" | "environment";
+    backgroundProcessOwnershipDir?: string;
     provider?: string;
     model?: string;
     apiKey?: string;

package/dist/cli/args.js

@@ -28,6 +28,29 @@ export function parseArgs(args) {
                 result.mode = mode;
             }
         }
+        else if (arg === "--background-process-lifetime" || arg.startsWith("--background-process-lifetime=")) {
+            const value = arg.includes("=") ? arg.slice(arg.indexOf("=") + 1) : args[i + 1];
+            if (!arg.includes("=") && value !== undefined && !value.startsWith("-"))
+                i++;
+            if (value === "session" || value === "environment")
+                result.backgroundProcessLifetime = value;
+            else
+                result.diagnostics.push({
+                    type: "error",
+                    message: "--background-process-lifetime requires session or environment",
+                });
+        }
+        else if (arg === "--background-process-ownership-dir" ||
+            arg.startsWith("--background-process-ownership-dir=")) {
+            const value = arg.includes("=") ? arg.slice(arg.indexOf("=") + 1) : args[i + 1];
+            if (value && !value.startsWith("-")) {
+                result.backgroundProcessOwnershipDir = value;
+                if (!arg.includes("="))
+                    i++;
+            }
+            else
+                result.diagnostics.push({ type: "error", message: "--background-process-ownership-dir requires a path" });
+        }
         else if (arg === "--continue" || arg === "-c") {
             result.continue = true;
         }
@@ -213,6 +236,18 @@ export function parseArgs(args) {
             result.messages.push(arg);
         }
     }
+    if (result.backgroundProcessLifetime === "environment" && !result.backgroundProcessOwnershipDir) {
+        result.diagnostics.push({
+            type: "error",
+            message: "Environment lifetime requires --background-process-ownership-dir",
+        });
+    }
+    if (result.backgroundProcessOwnershipDir && result.backgroundProcessLifetime !== "environment") {
+        result.diagnostics.push({
+            type: "error",
+            message: "--background-process-ownership-dir requires environment lifetime",
+        });
+    }
     return result;
 }
 export function printHelp(extensionFlags) {
@@ -248,6 +283,10 @@ ${chalk.bold("Options:")}
   --append-system-prompt <text>  Append text or file contents to the system prompt (can be used multiple times)
   --mode <mode>                  Output mode: text (default), json, or rpc
   --print, -p                    Non-interactive mode: process prompt and exit
+  --background-process-lifetime <session|environment>
+                                 Background shell ownership (default: session)
+  --background-process-ownership-dir <path>
+                                 Supervisor handoff records (required for environment lifetime)
   --continue, -c                 Continue previous session
   --resume, -r                   Select a session to resume
   --session <path|id>            Use specific session file or partial UUID

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

@@ -46,6 +46,7 @@ export interface CreateAgentSessionServicesOptions {
  * have been resolved against those services.
  */
 export interface CreateAgentSessionFromServicesOptions {
+    backgroundProcessPolicy?: CreateAgentSessionOptions["backgroundProcessPolicy"];
     services: AgentSessionServices;
     sessionManager: SessionManager;
     sessionStartEvent?: SessionStartEvent;

package/dist/core/agent-session-services.js

@@ -137,6 +137,7 @@ export async function createAgentSessionFromServices(options) {
 export async function createInternalAgentSessionFromServices(options, internalCustomTools = []) {
     registerSubagentRuntimeDiagnosticSink(options.sessionManager, options.services.diagnostics);
     return createInternalAgentSession({
+        backgroundProcessPolicy: options.backgroundProcessPolicy,
         cwd: options.services.cwd,
         agentDir: options.services.agentDir,
         modelRuntime: options.services.modelRuntime,

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

@@ -15,6 +15,7 @@
 import { type Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type TelemetryContext, type ThinkingLevel } from "@diffexai/diffex-agent-core";
 import type { ImageContent, Model, TextContent } from "@diffexai/diffex-ai/compat";
 import type { HarnessStateStore, HarnessVersion, HarnessVersionBundle, HarnessVersionList, HarnessWorkspaceIdentity } from "@diffexai/diffex-harness-state";
+import { type BackgroundProcessPolicy } from "../utils/owned-shell-processes.ts";
 import type { AgentSessionLifecycleObserver } from "./agent-session-lifecycle.ts";
 import { type BashResult } from "./bash-executor.ts";
 import { CHANGE_COLLABORATION_MODE, type CollaborationMode, type CollaborationModeTransitionResult, GET_COLLABORATION_MODE, IS_COLLABORATION_MODE_BUSY, SUBSCRIBE_PROMPT_ADMISSION } from "./collaboration-mode.ts";
@@ -135,6 +136,8 @@ export type AgentSessionEvent = Exclude<AgentEvent, {
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
 export interface AgentSessionConfig {
+    /** Lifetime of background groups launched by successful local shell commands. */
+    backgroundProcessPolicy?: BackgroundProcessPolicy;
     agent: Agent;
     sessionManager: SessionManager;
     settingsManager: SettingsManager;
@@ -250,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;
@@ -334,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;
@@ -565,6 +563,7 @@ export declare class AgentSession {
     private _abort;
     /** Stop and verify all shell processes owned by this session, including background jobs. */
     terminateOwnedShellProcesses(): Promise<void>;
+    get backgroundProcessPolicy(): BackgroundProcessPolicy;
     get ownedShellProcessCount(): number;
     waitForIdle(): Promise<void>;
     private _emitModelSelect;

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;
@@ -162,7 +159,7 @@ export class AgentSession {
     _bashAbortControllers = new Set();
     _pendingBashMessages = [];
     _ownedOperations = new Set();
-    _shellProcesses = new OwnedShellProcesses();
+    _shellProcesses;
     _bashOperations = new Set();
     // Extension system
     _extensionRunner;
@@ -220,6 +217,7 @@ export class AgentSession {
     _agentRunAborted = false;
     _disposePromise;
     constructor(config) {
+        this._shellProcesses = new OwnedShellProcesses(config.backgroundProcessPolicy);
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
         this.settingsManager = config.settingsManager;
@@ -244,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,
@@ -433,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
     // =========================================================================
@@ -1808,7 +1755,6 @@ export class AgentSession {
                 return;
             pendingCompaction.commit();
             pendingCompaction = undefined;
-            this._armCurrentPlanRestorationIfActive();
         };
         const rollbackPendingCompaction = () => {
             if (!pendingCompaction)
@@ -2401,6 +2347,9 @@ export class AgentSession {
     async terminateOwnedShellProcesses() {
         await this._shellProcesses.terminateAll();
     }
+    get backgroundProcessPolicy() {
+        return this._shellProcesses.policy;
+    }
     get ownedShellProcessCount() {
         return this._shellProcesses.count;
     }
@@ -2725,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);
@@ -2759,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;
     }
     /**
@@ -3755,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/sdk.d.ts

@@ -1,6 +1,7 @@
 import { type TelemetryContext, type ThinkingLevel } from "@diffexai/diffex-agent-core";
 import { type Model } from "@diffexai/diffex-ai/compat";
 import type { HarnessStateStore, HarnessVersionBundle } from "@diffexai/diffex-harness-state";
+import type { BackgroundProcessPolicy } from "../utils/owned-shell-processes.ts";
 import { AgentSession } from "./agent-session.ts";
 import type { AgentSessionLifecycleObserver } from "./agent-session-lifecycle.ts";
 import type { LoadExtensionsResult, SessionStartEvent, ToolDefinition } from "./extensions/index.ts";
@@ -15,6 +16,8 @@ export interface SubagentOptions extends SubagentSupervisionOptions {
     maxConcurrent?: number;
 }
 export interface CreateAgentSessionOptions {
+    /** Local shell background lifetime. Defaults to session-owned cleanup. */
+    backgroundProcessPolicy?: BackgroundProcessPolicy;
     /** Working directory for project-local discovery. Default: process.cwd() */
     cwd?: string;
     /** Global config directory. Default: ~/.diffex/agent */

package/dist/core/sdk.js

@@ -436,6 +436,7 @@ export async function createInternalAgentSession(options = {}, internalCustomToo
         sessionManager.appendThinkingLevelChange(thinkingLevel);
     }
     const session = new AgentSession({
+        backgroundProcessPolicy: options.backgroundProcessPolicy,
         agent,
         sessionManager,
         settingsManager,