yepanywhere 0.5.2 → 0.6.1

package/dist/sdk/providers/claude.js

@@ -1,17 +1,19 @@
 import { execFile, spawn } from "node:child_process";
-import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync, } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { promisify } from "node:util";
-import { query, } from "@anthropic-ai/claude-agent-sdk";
-import { HELPER_SIDE_MODEL_CHEAPEST, getModelContextWindow, } from "../../../bundled/@yep-anywhere/shared/dist/index.js";
+import { forkSession as sdkForkSession, query, } from "@anthropic-ai/claude-agent-sdk";
+import { DEFAULT_PROMPT_CACHE_KEEPALIVE_INACTIVITY_MINUTES, HELPER_SIDE_MODEL_CHEAPEST, getModelContextWindow, } from "../../../bundled/@yep-anywhere/shared/dist/index.js";
 import { getLogger } from "../../logging/logger.js";
 import { detectClaudeCli } from "../cli-detection.js";
 import { logSDKMessage } from "../messageLogger.js";
 import { MessageQueue } from "../messageQueue.js";
+import { ClaudeProviderRetentionTracker } from "./claude-retention.js";
 import { checkRemotePath, createRemoteSpawn, getRemoteHome, testSSHConnection, translateHomePath, } from "../remote-spawn.js";
 import { getProjectDirFromCwd, syncSessionFile } from "../session-sync.js";
+import { createAgentctlSessionEnvBridge } from "./agentctl-session-env.js";
 import { filterEnvForChildProcess } from "./env-filter.js";
 /**
  * Use a spawn wrapper to capture the child process reference for liveness checks.
@@ -22,6 +24,9 @@ import { filterEnvForChildProcess } from "./env-filter.js";
 const USE_SPAWN_WRAPPER = true;
 const CLAUDE_LIVENESS_PROBE_TIMEOUT_MS = 5000;
 const CLAUDE_LIVENESS_PROBE_SOURCE = "claude:control/mcp_status";
+const CLAUDE_PROMPT_CACHE_KEEPALIVE_TIMEOUT_MS = 60_000;
+const CLAUDE_PROMPT_CACHE_KEEPALIVE_MAX_BUDGET_USD = 0.02;
+const DEFAULT_CLAUDE_LOGIN_COMMAND = "claude auth login --claudeai";
 const CLAUDE_EFFORT_LEVELS = [
     "low",
     "medium",
@@ -33,6 +38,22 @@ const execFileAsync = promisify(execFile);
 const requireFromHere = createRequire(import.meta.url);
 const requireFromClaudeSdk = createRequire(requireFromHere.resolve("@anthropic-ai/claude-agent-sdk"));
 let cachedLocalClaudeCodeExecutable;
+function extractClaudeAssistantText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    let text = "";
+    for (const block of content) {
+        if (block &&
+            typeof block === "object" &&
+            block.type === "text" &&
+            typeof block.text === "string") {
+            text += block.text;
+        }
+    }
+    return text;
+}
 function isExecutableFile(filePath) {
     if (!filePath)
         return false;
@@ -103,42 +124,233 @@ function resolveLocalClaudeCodeExecutable() {
     cachedLocalClaudeCodeExecutable = executable ?? null;
     return executable;
 }
+function parseCommandLines(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function numericField(source, field) {
+    if (!source || typeof source !== "object") {
+        return undefined;
+    }
+    const value = source[field];
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+function extractPromptCacheRefreshUsage(message) {
+    const record = message;
+    const usage = record.usage ?? record.modelUsage ?? record.message?.usage ?? null;
+    if (!usage) {
+        return undefined;
+    }
+    const result = {};
+    const inputTokens = numericField(usage, "input_tokens") ?? numericField(usage, "inputTokens");
+    const outputTokens = numericField(usage, "output_tokens") ?? numericField(usage, "outputTokens");
+    const cacheReadTokens = numericField(usage, "cache_read_input_tokens") ??
+        numericField(usage, "cached_input_tokens") ??
+        numericField(usage, "cacheReadTokens");
+    const cacheCreationTokens = numericField(usage, "cache_creation_input_tokens") ??
+        numericField(usage, "cacheCreationTokens");
+    if (inputTokens !== undefined)
+        result.inputTokens = inputTokens;
+    if (outputTokens !== undefined)
+        result.outputTokens = outputTokens;
+    if (cacheReadTokens !== undefined)
+        result.cacheReadTokens = cacheReadTokens;
+    if (cacheCreationTokens !== undefined) {
+        result.cacheCreationTokens = cacheCreationTokens;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+function safeMtimeMs(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+function quotePowerShellDoubleQuoted(value) {
+    return `"${value
+        .replace(/`/g, "``")
+        .replace(/\$/g, "`$")
+        .replace(/"/g, '`"')}"`;
+}
+function quotePosixSingleQuoted(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+export function formatClaudeLoginCommand(executablePath, platform = process.platform) {
+    const trimmedPath = executablePath?.trim();
+    if (!trimmedPath || trimmedPath === "claude") {
+        return DEFAULT_CLAUDE_LOGIN_COMMAND;
+    }
+    const executable = platform === "win32"
+        ? quotePowerShellDoubleQuoted(trimmedPath)
+        : quotePosixSingleQuoted(trimmedPath);
+    const invocation = platform === "win32" ? `& ${executable}` : executable;
+    return `${invocation} auth login --claudeai`;
+}
+function getClaudeDesktopCodeRoots() {
+    if (process.platform !== "win32")
+        return [];
+    const localAppData = process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+    const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+    const roots = [];
+    try {
+        for (const entry of readdirSync(join(localAppData, "Packages"), {
+            withFileTypes: true,
+        })) {
+            if (entry.isDirectory() && entry.name.startsWith("Claude_")) {
+                roots.push(join(localAppData, "Packages", entry.name, "LocalCache", "Roaming", "Claude", "claude-code"));
+            }
+        }
+    }
+    catch {
+        // Claude Desktop may not be installed through the Store package.
+    }
+    roots.push(join(appData, "Claude", "claude-code"));
+    return roots;
+}
+function findClaudeDesktopExecutables() {
+    const candidates = [];
+    for (const root of getClaudeDesktopCodeRoots()) {
+        try {
+            for (const entry of readdirSync(root, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                const candidateDir = join(root, entry.name);
+                const candidate = join(candidateDir, "claude.exe");
+                if (existsSync(candidate)) {
+                    candidates.push({
+                        path: candidate,
+                        mtimeMs: safeMtimeMs(candidateDir),
+                    });
+                }
+            }
+        }
+        catch {
+            // This Claude Desktop layout is optional and version-dependent.
+        }
+    }
+    return candidates
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)
+        .map((candidate) => candidate.path);
+}
+async function hasShellClaudeCommand() {
+    if (process.platform !== "win32")
+        return true;
+    try {
+        const { stdout } = await execFileAsync("where.exe", ["claude"], {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        return parseCommandLines(stdout).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function isUsableClaudeExecutable(path) {
+    try {
+        await execFileAsync(path, ["--version"], {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findPreferredClaudeLoginExecutable() {
+    if (process.platform !== "win32" || (await hasShellClaudeCommand())) {
+        return undefined;
+    }
+    for (const executable of findClaudeDesktopExecutables()) {
+        if (await isUsableClaudeExecutable(executable)) {
+            return executable;
+        }
+    }
+    return undefined;
+}
+export async function getClaudeLoginCommand() {
+    return formatClaudeLoginCommand(await findPreferredClaudeLoginExecutable());
+}
+async function* withCleanup(iterator, cleanup) {
+    try {
+        yield* iterator;
+    }
+    finally {
+        cleanup();
+    }
+}
+/**
+ * Opus and Sonnet both run with the 1M-token context window: their 1M is
+ * standard-priced (no per-token premium), so bare `opus`/`sonnet` are
+ * normalized to the extended-context alias at every launch/setModel chokepoint
+ * and surfaced with the 1M window in the exposed model list.
+ *
+ * Sonnet's 1M was previously credit-gated (launching `sonnet[1m]` errored with
+ * "Usage credits required for 1M context"), so it once kept a separate 200K
+ * entry. Sonnet 5 lifted that gate: a live probe on this account runs
+ * `--model sonnet` as `claude-sonnet-5[1m]` at a 1,000,000 window on the
+ * standard tier with no error. The "Sonnet 5" label is pinned in the
+ * description (the name stays the generic "Sonnet") rather than taken from the
+ * SDK, because `supportedModels()` still reports the `sonnet` alias as
+ * "Sonnet 4.6" even though it routes to Sonnet 5 at runtime; that pin will
+ * drift once the SDK catalog catches up, and we accept it. See
+ * topics/claude-1m-context.md.
+ */
+const ALWAYS_EXTENDED_CONTEXT_ALIASES = {
+    opus: "opus[1m]",
+    sonnet: "sonnet[1m]",
+};
+const ALWAYS_EXTENDED_DESCRIPTIONS = {
+    opus: "Opus 4.8 with the full 1M-token context window",
+    sonnet: "Sonnet 5 with the full 1M-token context window · newer tokenizer bills ~30% more tokens",
+};
+/** Normalize the opus alias to its always-on 1M variant at launch. */
+export function withExtendedClaudeContext(model) {
+    return (model && ALWAYS_EXTENDED_CONTEXT_ALIASES[model]) || model;
+}
 /** Static fallback list of Claude models (used if probe fails) */
 const CLAUDE_MODELS_FALLBACK = [
     {
         id: "default",
-        name: "Default (recommended)",
-        description: "Claude Code chooses the recommended model for your account",
+        name: "Default",
+        description: "Claude Code chooses the recommended model for your account (probably Sonnet)",
         contextWindow: getModelContextWindow("default", "claude"),
     },
     {
         id: "best",
         name: "Best",
-        description: "Highest-capability Claude Code alias for complex work",
-        contextWindow: getModelContextWindow("best", "claude"),
+        description: "Highest-capability Claude Code alias (probably Opus 4.8, full 1M context)",
+        contextWindow: getModelContextWindow("opus[1m]", "claude"),
     },
     {
-        id: "sonnet",
-        name: "Sonnet",
-        description: "Standard-context Sonnet for everyday coding tasks",
-        contextWindow: getModelContextWindow("sonnet", "claude"),
+        id: "fable",
+        name: "Fable",
+        description: "Most capable Claude model for demanding reasoning and long-horizon agentic work",
+        contextWindow: getModelContextWindow("fable", "claude"),
+        supportsAdaptiveThinking: true,
+        supportsAutoMode: true,
+        supportsEffort: true,
+        supportsFastMode: false,
+        supportedEffortLevels: CLAUDE_EFFORT_LEVELS,
+        defaultEffortLevel: "high",
     },
     {
-        id: "sonnet[1m]",
-        name: "Sonnet 1M",
-        description: "Sonnet with 1M context for long sessions and large codebases",
+        id: "sonnet",
+        name: "Sonnet",
+        description: ALWAYS_EXTENDED_DESCRIPTIONS.sonnet,
         contextWindow: getModelContextWindow("sonnet[1m]", "claude"),
     },
     {
         id: "opus",
         name: "Opus",
-        description: "Standard-context Opus for the most demanding reasoning",
-        contextWindow: getModelContextWindow("opus", "claude"),
-    },
-    {
-        id: "opus[1m]",
-        name: "Opus 1M",
-        description: "Opus with 1M context for the largest working sets",
+        description: ALWAYS_EXTENDED_DESCRIPTIONS.opus,
         contextWindow: getModelContextWindow("opus[1m]", "claude"),
     },
     {
@@ -190,6 +402,18 @@ function enrichClaudeModel(model) {
         supportedEffortLevels: model.supportedEffortLevels ?? CLAUDE_EFFORT_LEVELS,
     };
 }
+function mapClaudeSdkModel(model) {
+    return {
+        id: model.value,
+        name: model.displayName,
+        description: model.description,
+        supportsEffort: model.supportsEffort,
+        supportedEffortLevels: mapClaudeSupportedEffortLevels(model.supportedEffortLevels),
+        supportsAdaptiveThinking: model.supportsAdaptiveThinking,
+        supportsFastMode: model.supportsFastMode,
+        supportsAutoMode: model.supportsAutoMode,
+    };
+}
 export function mergeClaudeModels(models) {
     const byId = new Map();
     for (const model of CLAUDE_MODELS_FALLBACK) {
@@ -205,9 +429,34 @@ export function mergeClaudeModels(models) {
         ...CLAUDE_MODELS_FALLBACK.map((model) => model.id),
         ...models.map((model) => model.id),
     ];
-    return [...new Set(orderedIds)]
+    const merged = [...new Set(orderedIds)]
         .map((id) => byId.get(id))
         .filter((model) => model !== undefined);
+    // Opus and Sonnet always use the 1M window (withExtendedClaudeContext), so
+    // drop the redundant "opus[1m]"/"sonnet[1m]" entries and surface the 1M
+    // window + label on the base alias — including when the SDK probe supplies a
+    // 200K window. Sonnet also forces its description (not its name) because the
+    // SDK catalog still reports the alias as "Sonnet 4.6" while it routes to
+    // Sonnet 5.
+    return merged
+        .filter((model) => model.id !== "opus[1m]" && model.id !== "sonnet[1m]")
+        .map((model) => {
+        if (model.id === "opus") {
+            return {
+                ...model,
+                contextWindow: getModelContextWindow("opus[1m]", "claude"),
+                description: ALWAYS_EXTENDED_DESCRIPTIONS.opus,
+            };
+        }
+        if (model.id === "sonnet") {
+            return {
+                ...model,
+                contextWindow: getModelContextWindow("sonnet[1m]", "claude"),
+                description: ALWAYS_EXTENDED_DESCRIPTIONS.sonnet,
+            };
+        }
+        return model;
+    });
 }
 /** Cached models from SDK probe */
 let cachedModels = null;
@@ -273,9 +522,23 @@ export class ClaudeProvider {
     supportsPermissionMode = true;
     supportsThinkingToggle = true;
     supportsSlashCommands = true;
-    supportsSteering = false;
+    supportsSteering = true;
+    supportsSteerNow = true;
     supportsRecaps = true;
+    // Intentionally false. Claude emits native away_summary recaps only in the
+    // interactive TUI (entrypoint:cli), which writes them to the session JSONL
+    // after idle; YA reads and shows those regardless of recap mode. YA drives
+    // Claude via the TS SDK (entrypoint:sdk-ts), and there is no known way to
+    // make an SDK/YA-owned session emit native recaps, so a "native" choice here
+    // is a no-op (and would make fork/tailed wait a pointless native grace
+    // window). Do not re-enable on the basis of seeing CLI recaps in the JSONL.
+    supportsNativeRecaps = false;
     supportsNativePromptSuggestions = true;
+    promptCacheKeepalive = {
+        supportsNoContextPollutionNudge: true,
+        defaultMode: "auto",
+        defaultInactivityMinutes: DEFAULT_PROMPT_CACHE_KEEPALIVE_INACTIVITY_MINUTES,
+    };
     /**
      * Check if Claude SDK is available.
      * Since we bundle the SDK, this is always true.
@@ -299,11 +562,11 @@ export class ClaudeProvider {
     async getAuthStatus() {
         const installed = await this.isClaudeCliInstalled();
         if (!installed) {
-            return {
+            return this.withLoginCommand({
                 installed: false,
                 authenticated: false,
                 enabled: false,
-            };
+            });
         }
         const apiKey = process.env.ANTHROPIC_API_KEY?.trim();
         if (apiKey) {
@@ -315,45 +578,54 @@ export class ClaudeProvider {
         }
         const cliAuthStatus = await this.getCliAuthStatus();
         if (cliAuthStatus) {
-            return cliAuthStatus;
+            return this.withLoginCommand(cliAuthStatus);
         }
         const credentialsPath = join(homedir(), ".claude", ".credentials.json");
         if (!existsSync(credentialsPath)) {
-            return {
+            return this.withLoginCommand({
                 installed: true,
                 authenticated: false,
                 enabled: false,
-            };
+            });
         }
         try {
             const parsed = JSON.parse(readFileSync(credentialsPath, "utf-8"));
             const oauth = parsed.claudeAiOauth;
             const hasTokens = Boolean(oauth?.accessToken || oauth?.refreshToken);
             if (!hasTokens) {
-                return {
+                return this.withLoginCommand({
                     installed: true,
                     authenticated: false,
                     enabled: false,
-                };
+                });
             }
             const expiresAt = typeof oauth?.expiresAt === "number"
                 ? new Date(oauth.expiresAt)
                 : undefined;
             const authenticated = !expiresAt || expiresAt >= new Date() || Boolean(oauth?.refreshToken);
-            return {
+            return this.withLoginCommand({
                 installed: true,
                 authenticated,
                 enabled: authenticated,
                 expiresAt,
-            };
+            });
         }
         catch {
-            return {
+            return this.withLoginCommand({
                 installed: true,
                 authenticated: false,
                 enabled: false,
-            };
+            });
+        }
+    }
+    async withLoginCommand(status) {
+        if (status.authenticated || status.loginCommand) {
+            return status;
         }
+        return {
+            ...status,
+            loginCommand: await getClaudeLoginCommand(),
+        };
     }
     async getCliAuthStatus() {
         try {
@@ -386,6 +658,26 @@ export class ClaudeProvider {
         const cliInfo = detectClaudeCli();
         return cliInfo.found;
     }
+    /**
+     * Reported Claude model id → canonical YA alias, matched by family component.
+     * Anthropic has shipped both "{family}-{version}" (claude-opus-4-8) and
+     * "{version}-{family}" (claude-3-5-sonnet), so we look for the family anywhere
+     * in the name. One-to-(zero or more): we return the plain alias ("sonnet",
+     * not "sonnet[1m]"/"best") because the reported id can't say which the user
+     * actually launched. Used only to recover a keying id for non-YA-started
+     * sessions. See topics/provider-abstraction.md § Per-model settings keying.
+     */
+    yaModelIdForReported(reported) {
+        if (!reported)
+            return undefined;
+        const name = reported.toLowerCase();
+        for (const family of ["opus", "sonnet", "haiku", "fable"]) {
+            if (new RegExp(`(?:^|[-/])${family}(?:[-/]|$)`).test(name)) {
+                return family;
+            }
+        }
+        return undefined;
+    }
     /**
      * Get available Claude models.
      * Fetches dynamically from SDK via a probe session, with caching.
@@ -488,13 +780,7 @@ export class ClaudeProvider {
                 sdkQuery.supportedModels(),
                 new Promise((_, reject) => setTimeout(() => reject(new Error("Model probe timed out")), 15000)),
             ]);
-            return mergeClaudeModels(models.map((m) => ({
-                id: m.value,
-                name: m.displayName,
-                description: m.description,
-                supportsEffort: m.supportsEffort,
-                supportedEffortLevels: mapClaudeSupportedEffortLevels(m.supportedEffortLevels),
-            })));
+            return mergeClaudeModels(models.map((model) => mapClaudeSdkModel(model)));
         }
         finally {
             abortController.abort();
@@ -515,7 +801,17 @@ export class ClaudeProvider {
      * recaps; the renderer should still strip defensively in case the SDK
      * later forwards a TUI-shaped recap unchanged.
      */
-    async generateRecap(recentAssistantText, options) {
+    async generateSummary(request) {
+        switch (request.strategy) {
+            case "side-session":
+                return {
+                    text: await this.generateSideSessionRecap(request.recentAssistantText, request.model),
+                };
+            case "fork":
+                return await this.generateForkBackedSummary(request);
+        }
+    }
+    async generateSideSessionRecap(recentAssistantText, model) {
         const trimmed = recentAssistantText
             .map((text) => text.trim())
             .filter((text) => text.length > 0);
@@ -565,7 +861,7 @@ export class ClaudeProvider {
                 session_id: "",
             };
         }
-        const helperModel = options?.model === HELPER_SIDE_MODEL_CHEAPEST ? "haiku" : options?.model;
+        const helperModel = model === HELPER_SIDE_MODEL_CHEAPEST ? "haiku" : model;
         try {
             const sdkQuery = query({
                 prompt: singlePrompt(),
@@ -585,20 +881,7 @@ export class ClaudeProvider {
             for await (const message of sdkQuery) {
                 if (message.type === "assistant" &&
                     typeof message.message?.content !== "undefined") {
-                    const content = message.message.content;
-                    if (typeof content === "string") {
-                        text += content;
-                    }
-                    else if (Array.isArray(content)) {
-                        for (const block of content) {
-                            if (block &&
-                                typeof block === "object" &&
-                                block.type === "text" &&
-                                typeof block.text === "string") {
-                                text += block.text;
-                            }
-                        }
-                    }
+                    text += extractClaudeAssistantText(message.message.content);
                 }
                 if (message.type === "result") {
                     break;
@@ -617,6 +900,196 @@ export class ClaudeProvider {
             abortController.abort();
         }
     }
+    async generateForkBackedSummary(request) {
+        const userPrompt = request.purpose === "session-retitle"
+            ? this.createSessionRetitlePrompt(request)
+            : request.purpose === "recap"
+                ? this.createForkedRecapPrompt()
+                : this.createForkAfterSummaryPrompt(request);
+        const abortController = new AbortController();
+        const abortFromJob = () => abortController.abort();
+        if (request.signal?.aborted) {
+            abortController.abort();
+        }
+        else {
+            request.signal?.addEventListener("abort", abortFromJob, { once: true });
+        }
+        const SUMMARY_TIMEOUT_MS = 60_000;
+        const timeout = setTimeout(() => abortController.abort(), SUMMARY_TIMEOUT_MS);
+        timeout.unref?.();
+        async function* singlePrompt() {
+            yield {
+                type: "user",
+                message: { role: "user", content: userPrompt },
+                parent_tool_use_id: null,
+                session_id: request.generatorSessionId,
+            };
+        }
+        try {
+            const sdkQuery = query({
+                prompt: singlePrompt(),
+                options: {
+                    cwd: request.cwd,
+                    abortController,
+                    permissionMode: "default",
+                    pathToClaudeCodeExecutable: resolveLocalClaudeCodeExecutable(),
+                    env: this.getEnv(),
+                    resume: request.generatorSessionId,
+                    maxTurns: 1,
+                    systemPrompt: request.purpose === "session-retitle"
+                        ? "You are a title helper. Reply with the session title only, no preamble."
+                        : request.purpose === "recap"
+                            ? "You are a recap helper. Reply with the recap text only, no preamble."
+                            : "You are a handoff summary helper. Reply with the summary text only, no preamble.",
+                },
+            });
+            let text = "";
+            for await (const message of sdkQuery) {
+                if (message.type === "assistant" &&
+                    typeof message.message?.content !== "undefined") {
+                    text += extractClaudeAssistantText(message.message.content);
+                }
+                if (message.type === "result") {
+                    break;
+                }
+            }
+            const cleaned = text.trim();
+            if (!cleaned) {
+                throw new Error("Summary generation returned empty text");
+            }
+            return { text: cleaned };
+        }
+        finally {
+            clearTimeout(timeout);
+            request.signal?.removeEventListener("abort", abortFromJob);
+            abortController.abort();
+        }
+    }
+    createForkAfterSummaryPrompt(request) {
+        const instructions = request.instructions?.trim();
+        const boundaryContext = request.afterTurnContext?.trim();
+        return [
+            "The first non-empty line must be a concise title of at most 120 characters, with no trailing period.",
+            "Write it as: Title: <title>",
+            "Then leave one blank line before the handoff summary.",
+            "",
+            "Summarize the useful state after the retained fork boundary for a peer-agent handoff.",
+            `The target fork retains the conversation through completed-turn message id ${request.afterTurnMessageId}.`,
+            boundaryContext
+                ? `The retained boundary is the completed turn ending with this excerpt:\n${boundaryContext}`
+                : undefined,
+            "The target fork already includes the original request and the assistant/tool work through that selected completed turn.",
+            "Do not repeat setup, instruction loading, initial repository orientation, or investigation already present in that retained prefix.",
+            "Preserve decisions, constraints, current state, changed files, verification evidence, open risks, and the next useful action.",
+            "Do not continue the task. Write text that can be submitted as the next user turn in the target fork.",
+            instructions ? "" : undefined,
+            instructions ? "Additional user instructions:" : undefined,
+            instructions || undefined,
+        ]
+            .filter((part) => part !== undefined)
+            .join("\n");
+    }
+    createForkedRecapPrompt() {
+        return [
+            "The user stepped away and is coming back.",
+            "Recap the current session state in under 40 words, 1-2 plain sentences, no markdown.",
+            "Lead with what the assistant did or is doing; mention any pending next action.",
+            "Do not greet, do not ask a question, do not add a sign-off.",
+        ].join("\n");
+    }
+    createSessionRetitlePrompt(request) {
+        const lengthTarget = request.lengthTarget ?? 80;
+        const currentTitle = request.currentTitle?.trim();
+        return [
+            "What is a good new title for this session?",
+            "",
+            `Target length: under ${lengthTarget} characters.`,
+            currentTitle ? `Current title: ${currentTitle}` : undefined,
+            "Prefer a concrete task/result phrase over a generic chat title.",
+            "Return only the title. Do not quote it. Do not add a trailing period.",
+        ]
+            .filter((part) => part !== undefined)
+            .join("\n");
+    }
+    async refreshPromptCache(options) {
+        const abortController = new AbortController();
+        const timeout = setTimeout(() => abortController.abort(), CLAUDE_PROMPT_CACHE_KEEPALIVE_TIMEOUT_MS);
+        timeout.unref?.();
+        async function* singlePrompt() {
+            yield {
+                type: "user",
+                message: {
+                    role: "user",
+                    content: "Prompt-cache keepalive only. Reply exactly: OK.",
+                },
+                parent_tool_use_id: null,
+                session_id: options.sessionId,
+            };
+        }
+        const spawnClaudeCodeProcess = options.executor
+            ? createRemoteSpawn({
+                host: options.executor,
+                remoteEnv: options.remoteEnv,
+            })
+            : undefined;
+        try {
+            const sdkQuery = query({
+                prompt: singlePrompt(),
+                options: {
+                    cwd: options.cwd,
+                    resume: options.sessionId,
+                    abortController,
+                    permissionMode: "default",
+                    canUseTool: async () => ({
+                        behavior: "deny",
+                        message: "Prompt-cache keepalive does not run tools",
+                        interrupt: true,
+                    }),
+                    systemPrompt: this.getSystemPrompt(options.globalInstructions),
+                    settingSources: ["user", "project", "local"],
+                    includePartialMessages: false,
+                    persistSession: false,
+                    maxTurns: 1,
+                    maxBudgetUsd: CLAUDE_PROMPT_CACHE_KEEPALIVE_MAX_BUDGET_USD,
+                    model: withExtendedClaudeContext(options.model),
+                    thinking: options.thinking,
+                    effort: options.effort,
+                    pathToClaudeCodeExecutable: options.pathToClaudeCodeExecutable,
+                    env: options.env,
+                    spawnClaudeCodeProcess,
+                },
+            });
+            let usage;
+            for await (const message of sdkQuery) {
+                usage = extractPromptCacheRefreshUsage(message) ?? usage;
+                if (message.type === "result") {
+                    break;
+                }
+            }
+            return {
+                mode: "no-context-pollution-nudge",
+                refreshed: true,
+                usage,
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+            abortController.abort();
+        }
+    }
+    /**
+     * Fork a session's transcript into a new resumable session via the Agent
+     * SDK (`forkSession`): copies the jsonl with remapped UUIDs, optionally
+     * sliced at `upToMessageId`. The kept prefix is byte-identical to the
+     * source, so provider prompt-cache warmth carries over on resume.
+     */
+    async forkSession(options) {
+        return sdkForkSession(options.sessionId, {
+            dir: options.cwd,
+            upToMessageId: options.upToMessageId,
+            title: options.title,
+        });
+    }
     /**
      * Start a new Claude session.
      */
@@ -624,6 +1097,18 @@ export class ClaudeProvider {
         const log = getLogger();
         const queue = new MessageQueue();
         const abortController = new AbortController();
+        const agentctlSessionEnvBridge = options.executor
+            ? null
+            : createAgentctlSessionEnvBridge(options.resumeSessionId);
+        const claudeEnv = agentctlSessionEnvBridge
+            ? agentctlSessionEnvBridge.extendEnv(this.getEnv())
+            : this.getEnv();
+        const remoteEnv = options.executor && options.resumeSessionId
+            ? {
+                ...options.remoteEnv,
+                AGENTCTL_SESSION_ID: options.resumeSessionId,
+            }
+            : options.remoteEnv;
         // Effective cwd for the session (may be translated for remote executors)
         let effectiveCwd = options.cwd;
         // If remote executor specified, test connection first
@@ -700,7 +1185,7 @@ export class ClaudeProvider {
         if (options.executor) {
             spawnClaudeCodeProcess = createRemoteSpawn({
                 host: options.executor,
-                remoteEnv: options.remoteEnv,
+                remoteEnv,
             });
         }
         else if (USE_SPAWN_WRAPPER) {
@@ -790,6 +1275,7 @@ export class ClaudeProvider {
                 return proc;
             };
         }
+        const providerRetention = new ClaudeProviderRetentionTracker(options.onProviderRetentionChange);
         // Create the SDK query with our message generator
         let sdkQuery;
         try {
@@ -798,6 +1284,7 @@ export class ClaudeProvider {
                 options: {
                     cwd: effectiveCwd,
                     resume: options.resumeSessionId,
+                    resumeSessionAt: options.resumeSessionAt,
                     abortController,
                     // Pass permission mode to SDK for system prompt configuration.
                     // However, for "bypassPermissions" we pass "default" to the SDK so it always
@@ -812,18 +1299,31 @@ export class ClaudeProvider {
                     includePartialMessages: true,
                     promptSuggestions: options.promptSuggestions === true,
                     // Model, thinking, and effort options
-                    model: options.model,
+                    model: withExtendedClaudeContext(options.model),
                     thinking: options.thinking,
                     effort: options.effort,
                     pathToClaudeCodeExecutable,
                     // Filter env to exclude npm_*, yep-anywhere specific, and other irrelevant vars
-                    env: this.getEnv(),
+                    env: claudeEnv,
+                    hooks: {
+                        Stop: [
+                            {
+                                hooks: [
+                                    async (input) => {
+                                        providerRetention.observeStopHook(input);
+                                        return { continue: true };
+                                    },
+                                ],
+                            },
+                        ],
+                    },
                     // Remote execution via SSH
                     spawnClaudeCodeProcess,
                 },
             });
         }
         catch (error) {
+            agentctlSessionEnvBridge?.cleanup();
             // Handle common SDK initialization errors
             if (error instanceof Error) {
                 if (error.message.includes("Claude Code executable not found")) {
@@ -842,17 +1342,28 @@ export class ClaudeProvider {
         const wrappedIterator = this.wrapIterator(sdkQuery, {
             executor: options.executor,
             cwd: effectiveCwd,
-            remoteEnv: options.remoteEnv,
+            remoteEnv,
+            providerRetention,
         });
+        const iterator = agentctlSessionEnvBridge
+            ? withCleanup(wrappedIterator, () => agentctlSessionEnvBridge.cleanup())
+            : wrappedIterator;
         const isCapturedProcessAlive = USE_SPAWN_WRAPPER && !options.executor
             ? () => capturedProcess !== null &&
                 capturedProcess.exitCode === null &&
                 !capturedProcess.killed
             : undefined;
         return {
-            iterator: wrappedIterator,
+            iterator,
             queue,
-            abort: () => abortController.abort(),
+            abort: () => {
+                abortController.abort();
+                agentctlSessionEnvBridge?.cleanup();
+            },
+            steer: async (message) => {
+                queue.push(message);
+                return true;
+            },
             isProcessAlive: isCapturedProcessAlive,
             probeLiveness: () => probeClaudeControlLiveness(sdkQuery, {
                 isProcessAlive: isCapturedProcessAlive,
@@ -860,6 +1371,22 @@ export class ClaudeProvider {
             get pid() {
                 return capturedProcess?.pid;
             },
+            getProviderRetention: () => providerRetention.getSnapshot(),
+            refreshPromptCache: ({ sessionId }) => this.refreshPromptCache({
+                sessionId,
+                cwd: effectiveCwd,
+                model: withExtendedClaudeContext(options.model),
+                thinking: options.thinking,
+                effort: options.effort,
+                globalInstructions: options.globalInstructions,
+                executor: options.executor,
+                remoteEnv,
+                pathToClaudeCodeExecutable,
+                env: claudeEnv,
+            }),
+            publishAgentctlSessionId: (sessionId) => {
+                agentctlSessionEnvBridge?.publishSessionId(sessionId);
+            },
             setMaxThinkingTokens: (tokens) => sdkQuery.setMaxThinkingTokens(tokens),
             interrupt: async () => {
                 await sdkQuery.interrupt();
@@ -868,13 +1395,7 @@ export class ClaudeProvider {
             supportedModels: async () => {
                 const models = await sdkQuery.supportedModels();
                 // Map SDK ModelInfo (value, displayName, description) to our ModelInfo (id, name, description)
-                const mappedModels = mergeClaudeModels(models.map((m) => ({
-                    id: m.value,
-                    name: m.displayName,
-                    description: m.description,
-                    supportsEffort: m.supportsEffort,
-                    supportedEffortLevels: mapClaudeSupportedEffortLevels(m.supportedEffortLevels),
-                })));
+                const mappedModels = mergeClaudeModels(models.map((model) => mapClaudeSdkModel(model)));
                 // Update cache for future getAvailableModels() calls
                 cachedModels = mappedModels;
                 return mappedModels;
@@ -888,7 +1409,7 @@ export class ClaudeProvider {
                     argumentHint: c.argumentHint || undefined,
                 })));
             },
-            setModel: (model) => sdkQuery.setModel(model),
+            setModel: (model) => sdkQuery.setModel(withExtendedClaudeContext(model)),
         };
     }
     /**
@@ -907,6 +1428,7 @@ export class ClaudeProvider {
                     message.session_id ?? sessionId;
                 logSDKMessage(sessionId, message, { provider: "claude" });
                 const converted = this.convertMessage(message);
+                remoteOptions?.providerRetention?.observeMessage(converted);
                 yield converted;
                 // For remote sessions, sync session files after result messages
                 // This keeps the local UI up-to-date with remote progress