@diffexai/diffex 0.3.0 → 0.3.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/subagents/services.d.ts

@@ -1,6 +1,7 @@
 import type { TelemetryContext, ThinkingLevel } from "@diffexai/diffex-agent-core";
 import type { Model } from "@diffexai/diffex-ai";
 import type { HarnessStateStore, HarnessVersionBundle } from "@diffexai/diffex-harness-state";
+import type { BackgroundProcessPolicy } from "../../utils/owned-shell-processes.ts";
 import type { AgentSession } from "../agent-session.ts";
 import { type AgentSessionServices } from "../agent-session-services.ts";
 import type { ModelRuntime } from "../model-runtime.ts";
@@ -19,6 +20,7 @@ export interface CreateSubagentServicesOptions {
     telemetryContext?: TelemetryContext;
 }
 export interface SubagentSessionConfig {
+    readonly backgroundProcessPolicy?: BackgroundProcessPolicy;
     readonly cwd: string;
     readonly agentDir: string;
     readonly modelRuntime: ModelRuntime;

package/dist/core/subagents/services.js

@@ -39,6 +39,7 @@ export function captureSubagentSessionConfig(parent, agentDir) {
         .getActiveToolNames()
         .filter((name) => allToolNames.has(name) && toolsByName.get(name)?.sourceInfo.source === "builtin"));
     return Object.freeze({
+        backgroundProcessPolicy: parent.backgroundProcessPolicy,
         cwd: parent.sessionManager.getCwd(),
         agentDir,
         modelRuntime: parent.modelRuntime,
@@ -133,6 +134,7 @@ export async function createSubagentSession(config, options = {}) {
     markFixedHarnessSubagentSession(sessionManager);
     const { session } = await createInternalAgentSessionFromServices({
         services,
+        backgroundProcessPolicy: config.backgroundProcessPolicy,
         sessionManager,
         model: config.model,
         thinkingLevel: config.thinkingLevel,

package/dist/core/tools/bash.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { access as fsAccess } from "node:fs/promises";
 import { Container, Text, truncateToWidth } from "@diffexai/diffex-tui";
@@ -8,6 +9,7 @@ import { truncateToVisualLines } from "../../modes/interactive/components/visual
 import { theme } from "../../modes/interactive/theme/theme.js";
 import { waitForChildProcess } from "../../utils/child-process.js";
 import { getShellConfig, getShellEnv, killProcessTree, trackDetachedChildPid, untrackDetachedChildPid, } from "../../utils/shell.js";
+import { SHELL_EXECUTION_ID_ENV } from "../../utils/shell-process-identity.js";
 import { OutputAccumulator } from "./output-accumulator.js";
 import { getTextOutput, invalidArgText, str } from "./render-utils.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
@@ -56,10 +58,11 @@ export function createLocalBashOperations(options) {
             }
             signal?.throwIfAborted();
             const commandFromStdin = shellConfig.commandTransport === "stdin";
+            const executionId = randomUUID();
             const child = spawn(shellConfig.shell, commandFromStdin ? shellConfig.args : [...shellConfig.args, command], {
                 cwd,
                 detached: process.platform !== "win32",
-                env: env ?? getShellEnv(),
+                env: { ...(env ?? getShellEnv()), [SHELL_EXECUTION_ID_ENV]: executionId },
                 stdio: [commandFromStdin ? "pipe" : "ignore", "pipe", "pipe"],
                 windowsHide: true,
             });
@@ -67,25 +70,52 @@ export function createLocalBashOperations(options) {
                 child.stdin?.on("error", () => { });
                 child.stdin?.end(command);
             }
-            if (child.pid) {
-                if (options?.owner)
-                    options.owner.track(child.pid);
-                else
-                    trackDetachedChildPid(child.pid);
-            }
             let timedOut = false;
+            const environmentLifetime = options?.owner?.policy.lifetime === "environment";
+            let completed = false;
+            let completionError;
             let timeoutHandle;
             const onAbort = () => {
-                if (child.pid)
-                    killProcessTree(child.pid);
+                if (child.pid) {
+                    if (options?.owner)
+                        options.owner.terminate(child.pid);
+                    else
+                        killProcessTree(child.pid);
+                }
             };
+            const onExit = (code) => {
+                completed = true;
+                if (environmentLifetime && timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                try {
+                    if (child.pid)
+                        options?.owner?.complete(child.pid, code === 0 && !timedOut && !signal?.aborted);
+                }
+                catch (error) {
+                    completionError = error;
+                    try {
+                        onAbort();
+                    }
+                    catch (cleanupError) {
+                        completionError = new AggregateError([error, cleanupError], "Shell ownership handoff failed");
+                    }
+                }
+            };
+            child.once("exit", onExit);
             try {
+                if (child.pid) {
+                    if (options?.owner)
+                        options.owner.track(child.pid, executionId);
+                    else
+                        trackDetachedChildPid(child.pid);
+                }
                 // Set timeout if provided.
                 if (timeoutMs !== undefined) {
                     timeoutHandle = setTimeout(() => {
+                        if (environmentLifetime && completed)
+                            return;
                         timedOut = true;
-                        if (child.pid)
-                            killProcessTree(child.pid);
+                        onAbort();
                     }, timeoutMs);
                 }
                 // Stream stdout and stderr.
@@ -100,7 +130,11 @@ export function createLocalBashOperations(options) {
                 }
                 // Handle shell spawn errors and wait for the process to terminate without hanging
                 // on inherited stdio handles held by detached descendants.
-                const exitCode = await waitForChildProcess(child);
+                const exitCode = await waitForChildProcess(child, {
+                    maxPostExitMs: environmentLifetime ? 100 : undefined,
+                });
+                if (completionError)
+                    throw completionError;
                 if (signal?.aborted) {
                     throw new Error("aborted");
                 }
@@ -110,6 +144,7 @@ export function createLocalBashOperations(options) {
                 return { exitCode };
             }
             finally {
+                child.removeListener("exit", onExit);
                 if (child.pid) {
                     if (options?.owner)
                         options.owner.releaseIfExited(child.pid);

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 {};

package/dist/core/tools/update-plan.js

@@ -9,26 +9,34 @@ const updatePlanStatusSchema = Type.Unsafe({
     description: "Status of this plan item.",
 });
 const updatePlanItemSchema = Type.Object({
+    id: Type.String({ description: "Stable step ID; retain it across edits and reordering." }),
     step: Type.String({ description: "Task step text." }),
     status: updatePlanStatusSchema,
+    success_criteria: Type.Optional(Type.Array(Type.String(), { description: "Observable completion criteria." })),
 }, { additionalProperties: false });
 const updatePlanSchema = Type.Object({
     plan: Type.Optional(Type.Array(updatePlanItemSchema, {
         minItems: 1,
-        description: "Full ordered plan snapshot. Provide exactly one operation: plan or clear.",
+        description: "Full ordered plan snapshot. Keep existing IDs for retained steps.",
     })),
+    update: Type.Optional(Type.Object({
+        id: Type.String({ description: "ID of an existing step." }),
+        step: Type.Optional(Type.String()),
+        status: Type.Optional(updatePlanStatusSchema),
+        success_criteria: Type.Optional(Type.Array(Type.String())),
+    }, { additionalProperties: false })),
     clear: Type.Optional(Type.Literal(true, {
-        description: "Explicitly abandon and clear the current plan. Provide exactly one operation: plan or clear.",
+        description: "Explicitly abandon and clear the current plan.",
     })),
     explanation: Type.Optional(Type.String({ description: "Reason for changing or clearing the plan." })),
 }, { additionalProperties: false });
 export const updatePlanToolSystemPromptContribution = {
-    snippet: "track progress with an ordered task checklist",
+    snippet: "persist an ordered plan with step IDs and optional success criteria",
     guidelines: [
         "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.",
+        "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 the checklist at meaningful milestones and mark completed work before moving on.",
+        "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.",
     ],
@@ -39,28 +47,52 @@ function isRecord(value) {
 function isUpdatePlanStatus(value) {
     return typeof value === "string" && UPDATE_PLAN_STATUSES.includes(value);
 }
+function validateCriteria(value, label) {
+    if (!Array.isArray(value) ||
+        value.some((criterion) => typeof criterion !== "string" || criterion.trim().length === 0)) {
+        throw new Error(`${label} must be an array of non-empty strings.`);
+    }
+    return [...value];
+}
 function validatePlanSnapshot(rawPlan) {
     if (!Array.isArray(rawPlan) || rawPlan.length === 0) {
         throw new Error("Plan must contain at least one item.");
     }
     const plan = [];
+    const ids = new Set();
     for (let index = 0; index < rawPlan.length; index++) {
         const rawItem = rawPlan[index];
         if (!isRecord(rawItem)) {
             throw new Error(`Plan item ${index + 1} must be an object.`);
         }
-        const unexpectedField = Object.keys(rawItem).find((field) => field !== "step" && field !== "status");
+        const unexpectedField = Object.keys(rawItem).find((field) => field !== "id" && field !== "step" && field !== "status" && field !== "success_criteria");
         if (unexpectedField !== undefined) {
             throw new Error(`Plan item ${index + 1} contains unexpected field: ${unexpectedField}.`);
         }
-        const { step, status } = rawItem;
+        const { id, step, status } = rawItem;
+        if (typeof id !== "string" || id.trim().length === 0) {
+            throw new Error(`Plan item ${index + 1} id must be a non-empty string.`);
+        }
+        if (ids.has(id)) {
+            throw new Error(`Duplicate plan item id: ${id}.`);
+        }
+        ids.add(id);
         if (typeof step !== "string" || step.trim().length === 0) {
             throw new Error(`Plan item ${index + 1} step must be a non-empty string.`);
         }
         if (!isUpdatePlanStatus(status)) {
             throw new Error(`Plan item ${index + 1} status must be pending, in_progress, or completed.`);
         }
-        plan.push({ step, status });
+        plan.push({
+            id,
+            step,
+            status,
+            ...(Object.hasOwn(rawItem, "success_criteria")
+                ? {
+                    success_criteria: validateCriteria(rawItem.success_criteria, `Plan item ${index + 1} success_criteria`),
+                }
+                : {}),
+        });
     }
     const counts = countPlanStatuses(plan);
     if (counts.completed !== plan.length && counts.inProgress !== 1) {
@@ -72,14 +104,15 @@ export function parseUpdatePlanOperation(input) {
     if (!isRecord(input)) {
         throw new Error("update_plan input must be an object.");
     }
-    const unexpectedField = Object.keys(input).find((field) => field !== "plan" && field !== "clear" && field !== "explanation");
+    const unexpectedField = Object.keys(input).find((field) => field !== "plan" && field !== "update" && field !== "clear" && field !== "explanation");
     if (unexpectedField !== undefined) {
         throw new Error(`Unexpected update_plan field: ${unexpectedField}.`);
     }
     const hasPlan = Object.hasOwn(input, "plan");
+    const hasUpdate = Object.hasOwn(input, "update");
     const hasClear = Object.hasOwn(input, "clear");
-    if (hasPlan === hasClear) {
-        throw new Error("Provide exactly one update_plan operation: plan or clear.");
+    if (Number(hasPlan) + Number(hasUpdate) + Number(hasClear) !== 1) {
+        throw new Error("Provide exactly one update_plan operation: plan, update, or clear.");
     }
     const hasExplanation = Object.hasOwn(input, "explanation");
     if (hasExplanation && typeof input.explanation !== "string") {
@@ -92,9 +125,64 @@ export function parseUpdatePlanOperation(input) {
         }
         return hasExplanation ? { clear: true, explanation } : { clear: true };
     }
+    if (hasUpdate) {
+        if (!isRecord(input.update))
+            throw new Error("Update must be an object.");
+        const unexpectedUpdateField = Object.keys(input.update).find((field) => field !== "id" && field !== "step" && field !== "status" && field !== "success_criteria");
+        if (unexpectedUpdateField !== undefined)
+            throw new Error(`Unexpected update field: ${unexpectedUpdateField}.`);
+        const { id, step, status } = input.update;
+        if (typeof id !== "string" || id.trim().length === 0)
+            throw new Error("Update id must be a non-empty string.");
+        if (step !== undefined && (typeof step !== "string" || step.trim().length === 0)) {
+            throw new Error("Update step must be a non-empty string.");
+        }
+        if (status !== undefined && !isUpdatePlanStatus(status)) {
+            throw new Error("Update status must be pending, in_progress, or completed.");
+        }
+        const hasCriteria = Object.hasOwn(input.update, "success_criteria");
+        if (step === undefined && status === undefined && !hasCriteria)
+            throw new Error("Update must change a step field.");
+        const update = {
+            id,
+            ...(step === undefined ? {} : { step }),
+            ...(status === undefined ? {} : { status }),
+            ...(hasCriteria
+                ? { success_criteria: validateCriteria(input.update.success_criteria, "Update success_criteria") }
+                : {}),
+        };
+        return hasExplanation ? { update, explanation } : { update };
+    }
     const plan = validatePlanSnapshot(input.plan);
     return hasExplanation ? { plan, explanation } : { plan };
 }
+export function resolveUpdatePlanOperation(input, currentPlan) {
+    const operation = parseUpdatePlanOperation(input);
+    if (!("update" in operation))
+        return operation;
+    if (!currentPlan)
+        throw new Error("Cannot update a step without a current plan.");
+    const index = currentPlan.findIndex((item) => item.id === operation.update.id);
+    if (index < 0)
+        throw new Error(`Unknown plan step id: ${operation.update.id}.`);
+    const plan = currentPlan.map((item, itemIndex) => {
+        if (itemIndex !== index)
+            return item;
+        const { success_criteria, ...changes } = operation.update;
+        const updated = { ...item, ...changes };
+        if (success_criteria !== undefined) {
+            if (success_criteria.length === 0)
+                delete updated.success_criteria;
+            else
+                updated.success_criteria = success_criteria;
+        }
+        return updated;
+    });
+    return {
+        plan: validatePlanSnapshot(plan),
+        ...(operation.explanation === undefined ? {} : { explanation: operation.explanation }),
+    };
+}
 function countPlanStatuses(plan) {
     let completed = 0;
     let inProgress = 0;
@@ -151,27 +239,43 @@ function formatPlanCall(args, theme, showInvalidArgs) {
     if ("clear" in details) {
         return `${text}\n${theme.fg("toolOutput", "Plan cleared.")}`;
     }
+    if ("update" in details) {
+        text += `\n${theme.fg("toolOutput", `Update ${details.update.id}`)}`;
+        if (details.update.status)
+            text += ` ${formatPlanMarker(details.update.status, theme)}`;
+        if (details.update.step)
+            text += ` ${formatPlanStep(details.update.step, theme)}`;
+        if (details.update.success_criteria) {
+            for (const criterion of details.update.success_criteria)
+                text += `\n  ${theme.fg("toolOutput", `- ${criterion}`)}`;
+        }
+        return text;
+    }
     for (const item of details.plan) {
-        text += `\n${formatPlanMarker(item.status, theme)} ${formatPlanStep(item.step, theme)}`;
+        text += `\n${formatPlanMarker(item.status, theme)} ${theme.fg("toolOutput", item.id)} ${formatPlanStep(item.step, theme)}`;
+        for (const criterion of item.success_criteria ?? [])
+            text += `\n  ${theme.fg("toolOutput", `- ${criterion}`)}`;
     }
     return text;
 }
-export function createUpdatePlanToolDefinition() {
+export function createUpdatePlanToolDefinition(_cwd, getCurrentPlan) {
     return {
         name: "update_plan",
         label: "update_plan",
-        description: "Replace or explicitly clear the full ordered task checklist. Unfinished plans require exactly one in_progress item.",
+        description: "Write or clear a plan, or update one step by ID. Use optional success_criteria for validation.",
         promptSnippet: updatePlanToolSystemPromptContribution.snippet,
         promptGuidelines: [...updatePlanToolSystemPromptContribution.guidelines],
         parameters: updatePlanSchema,
         executionMode: "sequential",
         async execute(_toolCallId, input) {
-            const details = parseUpdatePlanOperation(input);
+            const details = resolveUpdatePlanOperation(input, getCurrentPlan?.());
             return {
                 content: [
                     {
                         type: "text",
-                        text: "clear" in details ? "Plan cleared." : formatPlanSummary(details.plan),
+                        text: "clear" in details
+                            ? "Plan cleared."
+                            : `${formatPlanSummary(details.plan)}\n${JSON.stringify({ plan: details.plan }, null, 2)}`,
                     },
                 ],
                 details,
@@ -188,6 +292,6 @@ export function createUpdatePlanToolDefinition() {
         },
     };
 }
-export function createUpdatePlanTool() {
-    return wrapToolDefinition(createUpdatePlanToolDefinition());
+export function createUpdatePlanTool(getCurrentPlan) {
+    return wrapToolDefinition(createUpdatePlanToolDefinition(undefined, getCurrentPlan));
 }

package/dist/index.d.ts

@@ -33,4 +33,5 @@ export { copyToClipboard } from "./utils/clipboard.ts";
 export { parseFrontmatter, stripFrontmatter } from "./utils/frontmatter.ts";
 export { convertToPng } from "./utils/image-convert.ts";
 export { formatDimensionNote, type ResizedImage, resizeImage } from "./utils/image-resize.ts";
+export type { BackgroundProcessPolicy, ShellOwnershipRecord } from "./utils/owned-shell-processes.ts";
 export { getShellConfig } from "./utils/shell.ts";

package/dist/main.js

@@ -439,6 +439,9 @@ export async function main(args, options) {
         : undefined;
     const trustPromptMode = parsed.help || parsed.listModels !== undefined ? "print" : appMode;
     const projectTrustByCwd = new Map();
+    const backgroundProcessPolicy = parsed.backgroundProcessLifetime === "environment"
+        ? { lifetime: "environment", ownershipDirectory: resolvePath(parsed.backgroundProcessOwnershipDir, cwd) }
+        : { lifetime: "session" };
     const resolvedExtensionPaths = resolveCliPaths(cwd, parsed.extensions);
     const resolvedSkillPaths = resolveCliPaths(cwd, parsed.skills);
     const resolvedPromptTemplatePaths = resolveCliPaths(cwd, parsed.promptTemplates);
@@ -530,6 +533,7 @@ export async function main(args, options) {
             }
         }
         const created = await createAgentSessionFromServices({
+            backgroundProcessPolicy,
             services,
             sessionManager,
             sessionStartEvent,

package/dist/modes/interactive/components/footer.js

@@ -131,6 +131,11 @@ export class FooterComponent {
         const contextFull = theme.fg("footerContext", `context ${contextPercent}%`) +
             theme.fg("borderMuted", " / ") +
             theme.fg("footerWindow", windowDisplay);
+        const { input, cacheRead, cacheWrite } = this.session.getSessionStats().tokens;
+        const promptTokens = input + cacheRead + cacheWrite;
+        const cacheHitPercent = promptTokens > 0 && (cacheRead > 0 || cacheWrite > 0)
+            ? `${((cacheRead / promptTokens) * 100).toFixed(1)}%`
+            : undefined;
         const planMode = getCollaborationMode(this.session) === "plan";
         const planFull = theme.fg("warning", "Plan mode");
         const planCompact = theme.fg("warning", "Plan");
@@ -176,6 +181,9 @@ export class FooterComponent {
         };
         const tryAddField = (field) => trySetFields([...fields, field]);
         const tryUpgradeField = (key, text) => trySetFields(fields.map((field) => (field.key === key ? { ...field, text } : field)));
+        if (cacheHitPercent !== undefined) {
+            tryAddField({ key: "cache", order: 3, text: theme.fg("dim", `cache ${cacheHitPercent}`) });
+        }
         // Extension statuses are public UI state, so admit them before optional
         // detail upgrades and shortcut hints. Truncate only their own field.
         const extensionStatuses = this.footerData.getExtensionStatuses();
@@ -189,7 +197,7 @@ export class FooterComponent {
             if (statusText.length > 0 && availableWidth > 0) {
                 tryAddField({
                     key: "extensions",
-                    order: 4,
+                    order: 5,
                     text: truncateToWidth(theme.fg("dim", statusText), availableWidth, glyphs.ellipsis),
                 });
             }
@@ -197,14 +205,17 @@ export class FooterComponent {
         tryAddField({ key: "thinking", order: 1, text: theme.fg("thinkingText", thinkingLevel) });
         tryAddField({
             key: "harness",
-            order: 3,
+            order: 4,
             text: theme.fg("dim", `h:${harnessVersion}`) + evolutionSpinner,
         });
         tryUpgradeField("context", contextMedium);
         tryUpgradeField("thinking", theme.fg("thinkingText", `thinking ${thinkingLevel}`));
+        if (cacheHitPercent !== undefined) {
+            tryUpgradeField("cache", theme.fg("dim", `input cache hit ${cacheHitPercent}`));
+        }
         tryUpgradeField("harness", theme.fg("dim", `harness ${harnessVersion}`) + evolutionSpinner);
         tryUpgradeField("context", contextFull);
-        tryAddField({ key: "hotkeys", order: 7, text: theme.fg("dim", "/hotkeys") });
+        tryAddField({ key: "hotkeys", order: 8, text: theme.fg("dim", "/hotkeys") });
         const getBindingHint = (action, label) => {
             try {
                 const binding = keyText(action);
@@ -216,11 +227,11 @@ export class FooterComponent {
         };
         const thinkingHint = getBindingHint("app.thinking.cycle", "thinking");
         if (thinkingHint) {
-            tryAddField({ key: "thinkingHint", order: 5, text: thinkingHint });
+            tryAddField({ key: "thinkingHint", order: 6, text: thinkingHint });
         }
         const modelHint = getBindingHint("app.model.cycleForward", "model");
         if (modelHint) {
-            tryAddField({ key: "modelHint", order: 6, text: modelHint });
+            tryAddField({ key: "modelHint", order: 7, text: modelHint });
         }
         return [renderFields(fields)];
     }

package/dist/modes/interactive/components/tool-group.d.ts

@@ -7,6 +7,7 @@ export declare class ToolGroupComponent implements Component {
     private pathOrigin;
     private reusesLeadingGap;
     private settled;
+    private cachedRender?;
     constructor(outputPad?: number, pathOrigin?: DiffexPathOrigin, options?: {
         reuseLeadingGap?: boolean;
     });