@code-yeongyu/senpi 2026.8.14 → 2026.8.17

package/dist/core/agent-session.js

@@ -37,6 +37,7 @@ import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { buildDynamicSystemPrompt } from "./dynamic-prompt/index.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
+import { CODEX_RESPONSES_API } from "./extensions/builtin/service-tier.js";
 import { deriveExtensionRegistrationId } from "./extensions/builtin/tool-search/engine/marker.js";
 import { getToolSearchService } from "./extensions/builtin/tool-search/service.js";
 import { ExecuteToolError, ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
@@ -47,7 +48,7 @@ import { filterContextExcludedMessages } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
 import { getModelNarrowingPatterns, resolveModelScope } from "./model-resolver.js";
 import { PROMPT_CACHE_SAFE_WAIT_ENV, resolvePromptCacheSafeWaitSeconds } from "./prompt-cache-budget.js";
-import { expandPromptTemplate } from "./prompt-templates.js";
+import { expandPromptTemplateWithMetadata } from "./prompt-templates.js";
 import { createProviderTimeoutRetryPlan, runBoundedRetryContinuation } from "./provider-timeout-retry.js";
 import { isBillingErrorMessage } from "./retry-fallback/billing.js";
 import { formatSelector } from "./retry-fallback/chains.js";
@@ -70,21 +71,132 @@ import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
 const TURN_RETRY_SUPPRESSION_PREFIX = "senpi:no-turn-retry:";
+const DEFERRED_RETRY_QUEUE_OWNERS = new WeakSet();
+/** Format the user-attributed payload for one or more explicit skill invocations. */
+export function formatSkillInvocationPrompt(skills, userRequest) {
+    const skillBlocks = skills.map((skill) => `The user explicitly invoked the "${skill.name}" skill. Follow the instructions in <skill-instruction> as binding for this request, while respecting higher-priority instructions.\n\n<skill-instruction name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${skill.body}\n</skill-instruction>`);
+    const expandedSkills = skillBlocks.join("\n\n");
+    return userRequest && /\S/.test(userRequest)
+        ? `${expandedSkills}\n\n<user-request>\n${userRequest}\n</user-request>`
+        : expandedSkills;
+}
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
  */
 export function parseSkillBlock(text) {
-    const match = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
-    if (!match)
+    const instructionPattern = /^The user explicitly invoked the "([^"]+)" skill\. Follow the instructions in <skill-instruction> as binding for this request, while respecting higher-priority instructions\.\n\n<skill-instruction name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill-instruction>/;
+    const instructionMatch = text.match(instructionPattern);
+    if (instructionMatch) {
+        if (instructionMatch[1] !== instructionMatch[2])
+            return null;
+        let remainder = text.slice(instructionMatch[0].length);
+        while (remainder.startsWith("\n\nThe user explicitly invoked the ")) {
+            const chainedMatch = remainder.slice(2).match(instructionPattern);
+            if (!chainedMatch || chainedMatch[1] !== chainedMatch[2])
+                return null;
+            remainder = remainder.slice(chainedMatch[0].length + 2);
+        }
+        const requestMatch = remainder.match(/^\n\n<user-request>\n([\s\S]*?)\n<\/user-request>$/);
+        if (remainder && !requestMatch)
+            return null;
+        return {
+            name: instructionMatch[1],
+            location: instructionMatch[3],
+            content: instructionMatch[4],
+            userMessage: requestMatch?.[1].trim() || undefined,
+        };
+    }
+    const legacyMatch = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
+    if (!legacyMatch)
         return null;
     return {
-        name: match[1],
-        location: match[2],
-        content: match[3],
-        userMessage: match[4]?.trim() || undefined,
+        name: legacyMatch[1],
+        location: legacyMatch[2],
+        content: legacyMatch[3],
+        userMessage: legacyMatch[4]?.trim() || undefined,
     };
 }
+export const MAX_SKILL_INVOCATION_TOKENS_PER_PROMPT = 64;
+const LEADING_SKILL_INVOCATION_PATTERN = /^(?:\/skill:([a-zA-Z][a-zA-Z0-9:_-]*)|\$([a-zA-Z][a-zA-Z0-9:_-]*))(?=\s|$)/;
+const INLINE_DOLLAR_SKILL_INVOCATION_PATTERN = /(^|\s)\$skill:([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+/**
+ * Find explicit skill invocation tokens without treating ordinary inline dollar
+ * prose (for example `$HOME`) as executable.
+ *
+ * Leading runs accept `/skill:name`, `$name`, and `$skill:name`. Outside the
+ * leading run only the desktop's explicit `$skill:name` token is executable.
+ */
+export function parseSkillInvocationTokens(text) {
+    const tokens = [];
+    let cursor = 0;
+    while (cursor < text.length) {
+        while (cursor < text.length && /\s/.test(text[cursor]))
+            cursor++;
+        const match = text.slice(cursor).match(LEADING_SKILL_INVOCATION_PATTERN);
+        if (!match)
+            break;
+        const syntax = match[1] ? "slash" : "dollar";
+        const dollarName = match[2];
+        const name = match[1] ?? (dollarName?.startsWith("skill:") ? dollarName.slice("skill:".length) : dollarName);
+        if (!name)
+            break;
+        tokens.push({
+            name,
+            syntax,
+            start: cursor,
+            end: cursor + match[0].length,
+            position: "leading",
+        });
+        if (tokens.length >= MAX_SKILL_INVOCATION_TOKENS_PER_PROMPT)
+            return tokens;
+        cursor += match[0].length;
+    }
+    INLINE_DOLLAR_SKILL_INVOCATION_PATTERN.lastIndex = cursor;
+    for (const match of text.matchAll(INLINE_DOLLAR_SKILL_INVOCATION_PATTERN)) {
+        const start = (match.index ?? 0) + match[1].length;
+        tokens.push({
+            name: match[2],
+            syntax: "dollar",
+            start,
+            end: start + `$skill:${match[2]}`.length,
+            position: "inline",
+        });
+        if (tokens.length >= MAX_SKILL_INVOCATION_TOKENS_PER_PROMPT)
+            break;
+    }
+    return tokens;
+}
+function stripLeadingInvocationSeparators(text) {
+    let cursor = 0;
+    while (text[cursor] === " " || text[cursor] === "\t")
+        cursor++;
+    while (text[cursor] === "\n" || (text[cursor] === "\r" && text[cursor + 1] === "\n")) {
+        cursor += text[cursor] === "\r" ? 2 : 1;
+        const lineStart = cursor;
+        while (text[cursor] === " " || text[cursor] === "\t")
+            cursor++;
+        if (text[cursor] !== "\n" && !(text[cursor] === "\r" && text[cursor + 1] === "\n")) {
+            return text.slice(lineStart);
+        }
+    }
+    return text.slice(cursor);
+}
+function removeSkillInvocationTokens(text, tokens) {
+    let cursor = 0;
+    let result = "";
+    for (const token of tokens) {
+        result += text.slice(cursor, token.start);
+        cursor = token.end;
+        if (token.position === "inline" &&
+            (result.endsWith(" ") || result.endsWith("\t")) &&
+            (text[cursor] === " " || text[cursor] === "\t")) {
+            cursor++;
+        }
+    }
+    result += text.slice(cursor);
+    return tokens.some((token) => token.position === "leading") ? stripLeadingInvocationSeparators(result) : result;
+}
 // ============================================================================
 // Types
 // ============================================================================
@@ -328,6 +440,9 @@ export class AgentSession {
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
         this.settingsManager = config.settingsManager;
+        this._unsubscribeSettingsSource = this.settingsManager.subscribeToSourceSelection((source) => {
+            this._emit({ type: "settings_source_selected", ...source });
+        });
         const noModelFallback = config.resourceLoader.getExtensions().runtime.flagValues.get("no-model-fallback") === true ||
             envValue("NO_FALLBACK") === "1";
         if (noModelFallback) {
@@ -381,6 +496,7 @@ export class AgentSession {
         });
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
+        this._defaultToolNames = config.defaultToolNames ? new Set(config.defaultToolNames) : undefined;
         this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
         this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
         this._baseToolsOverride = config.baseToolsOverride;
@@ -513,7 +629,7 @@ export class AgentSession {
         this.agent.beforeToolCall = async ({ toolCall, args }) => {
             this._toolExecutionDepth++;
             try {
-                const result = await this._emitBeforeToolCallHooks(toolCall, args);
+                const result = await this.preflightToolCall(toolCall, args);
                 if (result?.block) {
                     this._toolExecutionDepth--;
                 }
@@ -533,7 +649,7 @@ export class AgentSession {
             }
         };
     }
-    async _emitBeforeToolCallHooks(toolCall, args, options = {}) {
+    async preflightToolCall(toolCall, args, options = {}) {
         if (options.waitForEventQueue !== false) {
             await this._agentEventQueue;
         }
@@ -788,6 +904,13 @@ export class AgentSession {
     get agentDir() {
         return this._agentDir;
     }
+    /**
+     * Working directory this session resolves settings against — the same value extensions
+     * receive as `ctx.cwd`, so a host surface (RPC) reads project settings identically.
+     */
+    get cwd() {
+        return this._cwd;
+    }
     async _waitForSettledSessionWork() {
         await this._sessionWorkBarrier.waitForSettled(() => this._agentEventQueue);
     }
@@ -1191,6 +1314,7 @@ export class AgentSession {
         // Check auto-retry and auto-compaction after agent completes.
         let launchedContinuation = false;
         let retryContinuationBlocked = false;
+        let retryExhaustionAllowsQueuedContinuation = false;
         let allowsPostCompactionUsageExemptContinuation = false;
         const userAbortSuppressedQueuedContinuation = event.type === "agent_end" && this._suppressQueuedContinuationAfterUserAbort;
         if (userAbortSuppressedQueuedContinuation) {
@@ -1220,6 +1344,8 @@ export class AgentSession {
                 retryContinuationBlocked = !compactedBeforeRetry && !this._isCompactionDelegated();
             }
             let retryOutcome = "not-handled";
+            const retryOwnedDeferredQueue = DEFERRED_RETRY_QUEUE_OWNERS.has(this);
+            DEFERRED_RETRY_QUEUE_OWNERS.delete(this);
             if (!retryContinuationBlocked && !userAbortSuppressedQueuedContinuation) {
                 if (retryableError) {
                     retryOutcome = await this._handleRetryableError(msg);
@@ -1232,6 +1358,16 @@ export class AgentSession {
                 this._abortProvenance.closeAgentEndBoundary();
                 return;
             }
+            // Provider-timeout retries deliberately skip their first queue poll so
+            // steering cannot be consumed by another doomed retry request. Once the
+            // managed retry owner exhausts its budget, hand that retained queue back
+            // to the normal scheduled-continuation path instead of parking it until
+            // an unrelated later prompt arrives.
+            retryExhaustionAllowsQueuedContinuation =
+                !userAbortSuppressedQueuedContinuation &&
+                    retryOwnedDeferredQueue &&
+                    retryOutcome === "not-handled" &&
+                    (msg.stopReason === "error" || msg.stopReason === "aborted");
             if (retryOutcome === "not-handled" && this._retryAttempt > 0 && msg.errorMessage) {
                 const attempt = this._retryAttempt;
                 this._retryAttempt = 0;
@@ -1276,7 +1412,9 @@ export class AgentSession {
             this._flushPendingBashMessages();
             if (!launchedContinuation &&
                 !retryContinuationBlocked &&
-                (allowsQueuedContinuation || allowsPostCompactionUsageExemptContinuation) &&
+                (allowsQueuedContinuation ||
+                    allowsPostCompactionUsageExemptContinuation ||
+                    retryExhaustionAllowsQueuedContinuation) &&
                 this.agent.hasQueuedMessages()) {
                 // A scheduled continuation owns the queue now; the stored admission
                 // rejection from a superseded required compaction must not surface.
@@ -1545,6 +1683,9 @@ export class AgentSession {
      */
     subscribe(listener) {
         this._eventListeners.push(listener);
+        for (const source of this.settingsManager.getSelectedSettingsSources()) {
+            listener({ type: "settings_source_selected", ...source });
+        }
         // Return unsubscribe function for this specific listener
         return () => {
             const index = this._eventListeners.indexOf(listener);
@@ -1592,6 +1733,8 @@ export class AgentSession {
         }
         this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().");
         this._disconnectFromAgent();
+        this._unsubscribeSettingsSource?.();
+        this._unsubscribeSettingsSource = undefined;
         this._eventListeners = [];
         cleanupSessionResources(this.sessionId);
     }
@@ -1625,13 +1768,54 @@ export class AgentSession {
     isFastModeActive() {
         return this._sessionFastMode || this._currentServiceTier === "priority";
     }
-    /** Session-scoped fast-mode indicator; never persisted, reset on session start. */
+    /**
+     * The tier a request would carry right now: `serviceTier`, promoted to `"priority"` while
+     * session fast mode is on (which is exactly what the service-tier extension puts on the
+     * wire). Reported to clients so `serviceTier` and `fastMode` can never disagree.
+     */
+    get effectiveServiceTier() {
+        return this.isFastModeActive() ? "priority" : this._currentServiceTier;
+    }
+    /**
+     * Session-scoped fast-mode indicator; never persisted, reset on session start.
+     *
+     * Turning fast OFF also clears the cached priority tier: `/fast off` writes a remembered
+     * `"auto"` that must override an inherited catalog-priority tier immediately (display and
+     * request side), not only on the next session. Only codex-response models are touched, and
+     * never when an explicit scoped/favorite `:priority` pin is in force — those are pinned by
+     * the user's model selection, not by `/fast`.
+     */
     setSessionFastMode(enabled) {
+        const previousFastMode = this.isFastModeActive();
+        const previousTier = this._currentServiceTier;
         this._sessionFastMode = enabled;
+        if (!enabled && this._currentServiceTier === "priority" && this.model?.api === CODEX_RESPONSES_API) {
+            // Only an INHERITED (catalog) priority is cleared. A priority the catalog does not
+            // explain came from an explicit scoped/favorite `:priority` pin, which `/fast` must not undo.
+            if (this._modelRuntime.getCompatibilityRequestConfig(this.model).serviceTier === "priority") {
+                this._currentServiceTier = undefined;
+            }
+        }
+        this._emitServiceTierChangeIfNeeded(previousTier, previousFastMode);
+    }
+    /**
+     * Emit `service_tier_changed` when the effective tier or the fast-mode indicator actually
+     * moved. Both are observable state for RPC clients (`get_state.serviceTier` / `.fastMode`),
+     * and they can move independently: a session fast-mode toggle need not change the resolved
+     * tier, and a model switch can change the tier with fast mode untouched.
+     */
+    _emitServiceTierChangeIfNeeded(previousTier, previousFastMode) {
+        const fastMode = this.isFastModeActive();
+        if (previousTier === this._currentServiceTier && previousFastMode === fastMode)
+            return;
+        this._emit({ type: "service_tier_changed", tier: this.effectiveServiceTier, fastMode });
     }
     /**
      * Explicit scoped/favorite tiers win; otherwise fall back to the model's
-     * configured serviceTier from models.json/extension compatibility config.
+     * configured serviceTier from models.json/extension compatibility config. The per-model
+     * `/fast` memory is honored by the service-tier extension (`liveMemoryTier` + the session
+     * flag in `before_provider_request`), not cached here: caching it would survive a same-session
+     * `/fast off` (no model switch to re-resolve) and leak an inherited priority onto the wire.
      */
     _resolveServiceTier(model, explicit) {
         if (explicit)
@@ -1711,7 +1895,7 @@ export class AgentSession {
         catch (err) {
             throw new ExecuteToolError("invalid_params", toolName, err instanceof Error ? err.message : String(err), activeTools);
         }
-        const beforeResult = await this._emitBeforeToolCallHooks(prepared.toolCall, prepared.args, {
+        const beforeResult = await this.preflightToolCall(prepared.toolCall, prepared.args, {
             waitForEventQueue: this._toolExecutionDepth === 0,
         });
         if (beforeResult?.block) {
@@ -1758,6 +1942,15 @@ export class AgentSession {
      * Also rebuilds the system prompt to reflect the new tool set.
      * Changes take effect on the next agent turn.
      */
+    /**
+     * Resolve an executable tool from the full registry (builtin + extension
+     * tools), independent of the active set. The Cursor exec bridge uses this:
+     * Cursor drives its native tools (read/bash/grep/ls/write) over the exec
+     * channel regardless of which tools the request advertised.
+     */
+    getRegisteredTool(name) {
+        return this._toolRegistry.get(name);
+    }
     setActiveToolsByName(toolNames) {
         const tools = [];
         const validToolNames = [];
@@ -1913,6 +2106,8 @@ export class AgentSession {
             selectedTools: validToolNames,
             toolSnippets,
             promptGuidelines,
+            customPrompt: loaderSystemPrompt,
+            appendSystemPrompt: loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined,
         };
         const basePrompt = loaderSystemPrompt ?? buildDynamicSystemPrompt(this._baseSystemPromptOptions);
         return loaderAppendSystemPrompt.length > 0
@@ -2018,6 +2213,13 @@ export class AgentSession {
         let titlePrompt;
         let consumedNextTurnMessages;
         let inputId;
+        let pendingCommandInvocation;
+        const emitPendingCommandInvocation = () => {
+            if (!pendingCommandInvocation)
+                return;
+            this._emit({ type: "command_invocation", command: pendingCommandInvocation });
+            pendingCommandInvocation = undefined;
+        };
         const emitInputDisposition = async (disposition) => {
             if (inputId === undefined)
                 return;
@@ -2046,7 +2248,16 @@ export class AgentSession {
             let expandedText = currentText;
             if (expandPromptTemplates) {
                 expandedText = this._expandSkillCommand(expandedText);
-                expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+                const templateExpansion = expandPromptTemplateWithMetadata(expandedText, [...this.promptTemplates]);
+                expandedText = templateExpansion.text;
+                if (templateExpansion.template) {
+                    pendingCommandInvocation = {
+                        name: templateExpansion.template.name,
+                        source: "prompt",
+                        sourceInfo: templateExpansion.template.sourceInfo,
+                        syntax: "slash",
+                    };
+                }
             }
             titlePrompt = options?.sessionTitlePrompt === false ? undefined : (options?.sessionTitlePrompt ?? text);
             // If streaming, queue via steer() or followUp() based on option
@@ -2063,6 +2274,7 @@ export class AgentSession {
                 else {
                     await this._queueSteer(expandedText, currentImages);
                 }
+                emitPendingCommandInvocation();
                 await emitInputDisposition("queued");
                 promptDisposition?.("queued");
                 preflightResult?.(true);
@@ -2081,6 +2293,7 @@ export class AgentSession {
                 else {
                     await this._queueSteer(expandedText, currentImages);
                 }
+                emitPendingCommandInvocation();
                 await emitInputDisposition("queued");
                 promptDisposition?.("queued");
                 preflightResult?.(true);
@@ -2105,6 +2318,7 @@ export class AgentSession {
                     else {
                         await this._queueSteer(expandedText, currentImages);
                     }
+                    emitPendingCommandInvocation();
                     await emitInputDisposition("queued");
                     promptDisposition?.("queued");
                     preflightResult?.(true);
@@ -2126,6 +2340,7 @@ export class AgentSession {
                 else {
                     await this._queueSteer(expandedText, currentImages);
                 }
+                emitPendingCommandInvocation();
                 await emitInputDisposition("queued");
                 promptDisposition?.("queued");
                 preflightResult?.(true);
@@ -2219,6 +2434,7 @@ export class AgentSession {
             return;
         }
         promptDisposition?.("started");
+        emitPendingCommandInvocation();
         preflightResult?.(true);
         if (options?.thinkingLevel !== undefined) {
             this.setSessionThinkingLevel(options.thinkingLevel);
@@ -2254,6 +2470,15 @@ export class AgentSession {
         const command = this._extensionRunner.getCommand(commandName);
         if (!command)
             return false;
+        this._emit({
+            type: "command_invocation",
+            command: {
+                name: commandName,
+                source: "extension",
+                sourceInfo: command.sourceInfo,
+                syntax: "slash",
+            },
+        });
         // Get command context from extension runner (includes session control methods)
         const ctx = this._extensionRunner.createCommandContext();
         try {
@@ -2271,63 +2496,73 @@ export class AgentSession {
         }
     }
     /**
-     * Expand a leading run of skill commands (/skill:name /skill:other args) to their full content.
-     * Returns the expanded text, or the original text if the first skill command is not found.
-     * Emits errors via extension runner if file reads fail or the expansion cap is reached.
+     * Expand explicit skill invocations to their full content.
+     * Leading runs accept slash and dollar syntax; inline expansion is limited to
+     * the desktop's explicit `$skill:name` token so ordinary dollar prose stays literal.
      */
     _expandSkillCommand(text) {
-        if (!text.startsWith("/skill:"))
+        const invocationTokens = parseSkillInvocationTokens(text);
+        if (invocationTokens.length === 0)
             return text;
         const skills = this.resourceLoader.getSkills().skills;
         const expandedSkillNames = new Set();
         const skillBlocks = [];
-        let tokenStart = 0;
-        while (tokenStart < text.length) {
-            let tokenEnd = tokenStart;
-            while (tokenEnd < text.length && !/\s/.test(text[tokenEnd])) {
-                tokenEnd += 1;
-            }
-            const token = text.slice(tokenStart, tokenEnd);
-            if (!token.startsWith("/skill:"))
-                break;
-            const skillName = token.slice(7);
-            const skill = skills.find((candidate) => candidate.name === skillName);
-            if (!skill)
-                break; // Unknown skills and everything after them remain literal text.
-            if (!expandedSkillNames.has(skill.name)) {
-                if (skillBlocks.length >= MAX_SKILL_EXPANSIONS_PER_PROMPT) {
-                    this._extensionRunner.emitError({
-                        extensionPath: "skill:expansion",
-                        event: "skill_expansion",
-                        error: `Expanded at most ${MAX_SKILL_EXPANSIONS_PER_PROMPT} skills; remaining skill commands were left as literal text.`,
-                    });
+        const invocationMetadata = [];
+        const removedTokens = [];
+        for (const token of invocationTokens) {
+            const skill = skills.find((candidate) => candidate.name === token.name);
+            if (!skill) {
+                if (token.position === "leading")
                     break;
-                }
-                try {
-                    const content = readFileSync(skill.filePath, "utf-8");
-                    const body = stripFrontmatter(content).trim();
-                    skillBlocks.push(`<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`);
-                    expandedSkillNames.add(skill.name);
-                }
-                catch (err) {
-                    this._extensionRunner.emitError({
-                        extensionPath: skill.filePath,
-                        event: "skill_expansion",
-                        error: err instanceof Error ? err.message : String(err),
-                    });
-                    return text; // Return the original prompt when any skill file cannot be read.
-                }
+                continue;
+            }
+            if (skillBlocks.length >= MAX_SKILL_EXPANSIONS_PER_PROMPT) {
+                this._extensionRunner.emitError({
+                    extensionPath: "skill:expansion",
+                    event: "skill_expansion",
+                    error: `Expanded at most ${MAX_SKILL_EXPANSIONS_PER_PROMPT} skills; remaining skill commands were left as literal text.`,
+                });
+                break;
             }
-            tokenStart = tokenEnd;
-            while (tokenStart < text.length && /\s/.test(text[tokenStart])) {
-                tokenStart += 1;
+            removedTokens.push(token);
+            if (expandedSkillNames.has(skill.name)) {
+                this._extensionRunner.emitError({
+                    extensionPath: skill.filePath,
+                    event: "skill_expansion",
+                    error: `Skipped duplicate skill invocation: ${skill.name}`,
+                });
+                continue;
+            }
+            try {
+                const content = readFileSync(skill.filePath, "utf-8");
+                const body = stripFrontmatter(content).trim();
+                skillBlocks.push({
+                    name: skill.name,
+                    filePath: skill.filePath,
+                    baseDir: skill.baseDir,
+                    body,
+                });
+                expandedSkillNames.add(skill.name);
+                invocationMetadata.push({
+                    name: skill.name,
+                    path: skill.filePath,
+                    syntax: token.syntax,
+                });
+            }
+            catch (err) {
+                this._extensionRunner.emitError({
+                    extensionPath: skill.filePath,
+                    event: "skill_expansion",
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return text; // Return the original prompt when any skill file cannot be read.
             }
         }
         if (skillBlocks.length === 0)
             return text;
-        const args = text.slice(tokenStart).trim();
-        const expandedSkills = skillBlocks.join("\n\n");
-        return args ? `${expandedSkills}\n\n${args}` : expandedSkills;
+        const userRequest = removeSkillInvocationTokens(text, removedTokens);
+        this._emit({ type: "skill_invocation", skills: invocationMetadata });
+        return formatSkillInvocationPrompt(skillBlocks, userRequest);
     }
     /**
      * Queue a steering message while the agent is running.
@@ -2344,8 +2579,20 @@ export class AgentSession {
         }
         // Expand skill commands and prompt templates
         let expandedText = this._expandSkillCommand(text);
-        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        const templateExpansion = expandPromptTemplateWithMetadata(expandedText, [...this.promptTemplates]);
+        expandedText = templateExpansion.text;
         await this._queueSteer(expandedText, images, recovery?.enqueueOrder);
+        if (templateExpansion.template) {
+            this._emit({
+                type: "command_invocation",
+                command: {
+                    name: templateExpansion.template.name,
+                    source: "prompt",
+                    sourceInfo: templateExpansion.template.sourceInfo,
+                    syntax: "slash",
+                },
+            });
+        }
     }
     /**
      * Queue a follow-up message to be processed after the agent finishes.
@@ -2361,8 +2608,20 @@ export class AgentSession {
         }
         // Expand skill commands and prompt templates
         let expandedText = this._expandSkillCommand(text);
-        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        const templateExpansion = expandPromptTemplateWithMetadata(expandedText, [...this.promptTemplates]);
+        expandedText = templateExpansion.text;
         await this._queueFollowUp(expandedText, images, recovery?.enqueueOrder);
+        if (templateExpansion.template) {
+            this._emit({
+                type: "command_invocation",
+                command: {
+                    name: templateExpansion.template.name,
+                    source: "prompt",
+                    sourceInfo: templateExpansion.template.sourceInfo,
+                    syntax: "slash",
+                },
+            });
+        }
     }
     _startSessionTitleGeneration(firstPrompt) {
         if (!this._autoTitleSessions || this.sessionManager.getSessionName() || shouldSkipSessionTitle(firstPrompt)) {
@@ -2532,7 +2791,7 @@ export class AgentSession {
             if (options?.deliverAs === "nextTurn") {
                 this._pendingNextTurnMessages.push(appMessage);
             }
-            else if (this.isStreaming) {
+            else if (this.isStreaming && options?.triggerTurn !== false) {
                 if (options?.deliverAs === "followUp") {
                     this.agent.followUp(appMessage);
                 }
@@ -2593,6 +2852,7 @@ export class AgentSession {
      *
      * @param content User message content (string or content array)
      * @param options.deliverAs Delivery mode when streaming: "steer" or "followUp"
+     * @param options.expandPromptTemplates Whether to dispatch extension commands and expand skill commands and prompt templates. Default: false.
      */
     async sendUserMessage(content, options) {
         const bindingPromptReadiness = this._extensionBindingPromptReadiness;
@@ -2631,9 +2891,8 @@ export class AgentSession {
         let finishSessionWork;
         let disposition;
         try {
-            // Use prompt() with expandPromptTemplates: false to skip command handling and template expansion
             await this.prompt(text, {
-                expandPromptTemplates: false,
+                expandPromptTemplates: options?.expandPromptTemplates ?? false,
                 streamingBehavior: options?.deliverAs,
                 images,
                 source: "extension",
@@ -2840,7 +3099,7 @@ export class AgentSession {
         if (opts.invalidateCompaction && this._modelSelectionChangesContext(previousModel, model)) {
             this._invalidateCompactionForModelSelection();
         }
-        const thinkingLevel = this._getThinkingLevelForModelSwitch(opts.ephemeralThinkingLevel);
+        const thinkingLevel = this._getThinkingLevelForModelSwitch(model, opts.ephemeralThinkingLevel);
         this.agent.state.model = model;
         this.agent.abortServerSideFallback =
             this.settingsManager.getAbortServerSideFallback() && this._retryFallback.hasConfiguredChain();
@@ -2851,6 +3110,8 @@ export class AgentSession {
             this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
         }
         const scopedMatch = this._scopedModels.find((sm) => modelsAreEqual(sm.model, model));
+        const previousTier = this._currentServiceTier;
+        const previousFastMode = this.isFastModeActive();
         this._currentServiceTier = this._resolveServiceTier(model, scopedMatch?.serviceTier);
         if (opts.ephemeralThinkingLevel !== undefined) {
             this._applyEphemeralThinkingLevel(thinkingLevel);
@@ -2859,6 +3120,15 @@ export class AgentSession {
             this.setSessionThinkingLevel(thinkingLevel);
         }
         this._emitHighReasoningWarningIfNeeded();
+        // Post-switch: the level reported here is the one actually in force (clamped, or restored
+        // from this model's memory), not the level requested for the previous model.
+        this._emit({
+            type: "model_changed",
+            model,
+            thinkingLevel: this.thinkingLevel,
+            source: opts.modelSelectSource,
+        });
+        this._emitServiceTierChangeIfNeeded(previousTier, previousFastMode);
         if (!opts.emitModelSelect)
             return undefined;
         return await this._emitModelSelect(model, previousModel, opts.modelSelectSource);
@@ -2903,16 +3173,26 @@ export class AgentSession {
         }
         this._probeBackScheduler.cancel("manual-model-change");
         this._retryFallback.clearForManualModelChange(next.model);
-        const thinkingLevel = this._getThinkingLevelForModelSwitch(next.thinkingLevel);
+        const thinkingLevel = this._getThinkingLevelForModelSwitch(next.model, next.thinkingLevel);
         this.agent.state.model = next.model;
         this.sessionManager.appendModelChange(next.model.provider, next.model.id);
         this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
+        const previousTier = this._currentServiceTier;
+        const previousFastMode = this.isFastModeActive();
         this._currentServiceTier = this._resolveServiceTier(next.model, next.serviceTier);
         // Apply thinking level.
         // - Explicit favorite model thinking level overrides the effective session level
         // - Undefined favorite model thinking level restores the remembered user preference
         // setSessionThinkingLevel clamps without replacing that preference.
         this.setSessionThinkingLevel(thinkingLevel);
+        // Post-switch, same contract as _switchActiveModel: the level in force AFTER the cycle.
+        this._emit({
+            type: "model_changed",
+            model: next.model,
+            thinkingLevel: this.thinkingLevel,
+            source: "cycle",
+        });
+        this._emitServiceTierChangeIfNeeded(previousTier, previousFastMode);
         const systemPromptChange = await this._emitModelSelect(next.model, currentModel, "cycle");
         const cycleResult = { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
         if (systemPromptChange) {
@@ -2926,7 +3206,7 @@ export class AgentSession {
     /**
      * Set thinking level.
      * Clamps to model capabilities based on available thinking levels.
-     * Saves to session and settings only if the level actually changes.
+     * Persistent calls refresh per-model memory; session entries and events are emitted only on change.
      */
     setThinkingLevel(level) {
         this._setThinkingLevel(level, true);
@@ -2948,6 +3228,12 @@ export class AgentSession {
             this._retryFallback.noteManualThinkingLevel();
         }
         this.agent.state.thinkingLevel = effectiveLevel;
+        if (updateGlobalDefault) {
+            const model = this.model;
+            if (model) {
+                this.settingsManager.setModelThinkingLevel(model.provider, model.id, effectiveLevel);
+            }
+        }
         if (isChanging) {
             this.sessionManager.appendThinkingLevelChange(effectiveLevel);
             if (updateGlobalDefault && (this.supportsThinking() || effectiveLevel !== "off")) {
@@ -3019,11 +3305,12 @@ export class AgentSession {
     supportsThinking() {
         return !!this.model?.reasoning;
     }
-    _getThinkingLevelForModelSwitch(explicitLevel) {
-        if (explicitLevel !== undefined) {
-            return explicitLevel;
-        }
-        return this.settingsManager.getDefaultThinkingLevel() ?? this.thinkingLevel ?? DEFAULT_THINKING_LEVEL;
+    _getThinkingLevelForModelSwitch(model, explicitLevel) {
+        const requestedLevel = explicitLevel ??
+            this.settingsManager.getModelThinkingLevel(model.provider, model.id) ??
+            this.settingsManager.getDefaultThinkingLevel() ??
+            DEFAULT_THINKING_LEVEL;
+        return this._clampThinkingLevel(requestedLevel, getSupportedThinkingLevels(model));
     }
     _clampThinkingLevel(level, availableLevels) {
         const available = new Set(availableLevels);
@@ -3687,8 +3974,9 @@ export class AgentSession {
             if (compacted)
                 return true;
         }
-        if (this._isCompactionOnCooldown() || this._isCompactionDelegated())
+        if (this._isCompactionOnCooldown() || this._isCompactionDelegated() || this._hasSupersedingCompactionClaim()) {
             return false;
+        }
         throw new RequiredCompactionError();
     }
     /**
@@ -3729,6 +4017,8 @@ export class AgentSession {
         const compacted = await this._runPrePromptCompaction(lastAssistantMessage, false, "pre_prompt");
         if (!compacted && this._isCompactionDelegated())
             return;
+        if (!compacted && this._hasSupersedingCompactionClaim())
+            return;
         if (!compacted && !isOversized() && this._isCompactionOnCooldown())
             return;
         if (!compacted || isOversized()) {
@@ -3819,7 +4109,7 @@ export class AgentSession {
                 this._restoreAgentMessagesFromSession();
                 this._incrementMessageRevision();
             }
-            if (!compacted && inlineReason && !this._isCompactionDelegated()) {
+            if (!compacted && inlineReason && !this._isCompactionDelegated() && !this._hasSupersedingCompactionClaim()) {
                 throw new RequiredCompactionError();
             }
             return compacted;
@@ -3888,6 +4178,17 @@ export class AgentSession {
         const state = this._compactionLifecycle.state;
         return state.status === "failed" && state.rejectionCause === "circuit-breaker";
     }
+    /**
+     * Compaction claims are last-writer-wins: a newer admission aborts the
+     * incumbent controller (_claimCompactionController). When the failed attempt
+     * lost that race, a live claimant now owns the route and re-gates admission
+     * itself, so the loser must not surface RequiredCompactionError (issue #886).
+     * A user abort leaves no live claimant behind and keeps throwing.
+     */
+    _hasSupersedingCompactionClaim() {
+        const claimant = this._compactionAbortController ?? this._autoCompactionAbortController;
+        return claimant !== undefined && !claimant.signal.aborted;
+    }
     _isCompactionDelegated() {
         const state = this._compactionLifecycle.state;
         const model = this.model;
@@ -3961,8 +4262,9 @@ export class AgentSession {
             return;
         const compacted = await this._runPrePromptCompaction(this._findLastAssistantMessage(), true, "pre_prompt");
         if (!compacted) {
-            if (this._isCompactionOnCooldown() || this._isCompactionDelegated())
+            if (this._isCompactionOnCooldown() || this._isCompactionDelegated() || this._hasSupersedingCompactionClaim()) {
                 return;
+            }
             throw new RequiredCompactionError();
         }
         this._scheduledContinuationRecompacted = true;
@@ -4028,9 +4330,15 @@ export class AgentSession {
         const finishContinuationWork = this._sessionWorkBarrier.begin();
         const continueAfterEvent = async () => {
             try {
-                await this._continueAgentAfterCurrentRun(options, retryTimeoutMs);
+                const outcome = await this._continueAgentAfterCurrentRun(options, retryTimeoutMs);
+                if (retryContinuation && outcome === "taken-over") {
+                    DEFERRED_RETRY_QUEUE_OWNERS.delete(this);
+                }
             }
             catch (error) {
+                if (retryContinuation) {
+                    DEFERRED_RETRY_QUEUE_OWNERS.delete(this);
+                }
                 const message = error instanceof Error ? error.message : String(error);
                 this._emit({
                     type: "continuation_error",
@@ -4208,6 +4516,7 @@ export class AgentSession {
             this._applyExtensionBindings(this._extensionRunner);
             this.syncPromptCacheSafeWaitEnv();
             await this._extensionRunner.emit(this._sessionStartEvent);
+            this._enforceConfiguredDefaultTools();
             await this.extendResourcesFromExtensions(this._sessionStartEvent.reason === "reload" ? "reload" : "startup");
         }
         finally {
@@ -4541,6 +4850,22 @@ export class AgentSession {
     get fallbackValidationWarnings() {
         return this._fallbackValidationWarnings;
     }
+    _isBuiltinExtensionPath(path) {
+        return path.startsWith("<builtin:") || /[\\/]senpi-codemode[\\/]/u.test(path);
+    }
+    _enforceConfiguredDefaultTools() {
+        const defaultToolNames = this._defaultToolNames;
+        if (defaultToolNames === undefined)
+            return;
+        this.setActiveToolsByName(this.getActiveToolNames().filter((name) => {
+            if (defaultToolNames.has(name))
+                return true;
+            const entry = this._toolDefinitions.get(name);
+            return (entry !== undefined &&
+                !this._isBuiltinExtensionPath(entry.sourceInfo.path) &&
+                entry.sourceInfo.source !== "builtin");
+        }));
+    }
     _refreshToolRegistry(options) {
         const previousRegistryNames = new Set(this._toolRegistry.keys());
         const previousActiveToolNames = this.getActiveToolNames();
@@ -4548,8 +4873,12 @@ export class AgentSession {
         const excludedToolNames = this._excludedToolNames;
         const isAllowedTool = (name) => (!allowedToolNames || allowedToolNames.has(name)) && !excludedToolNames?.has(name);
         const registeredTools = this._extensionRunner.getAllRegisteredTools();
+        const defaultToolNames = this._defaultToolNames;
+        const isConfiguredBuiltinTool = (tool) => (tool.sourceInfo.source !== "builtin" && !this._isBuiltinExtensionPath(tool.sourceInfo.path)) ||
+            defaultToolNames === undefined ||
+            defaultToolNames.has(tool.definition.name);
         const allCustomTools = [
-            ...registeredTools,
+            ...registeredTools.filter(isConfiguredBuiltinTool),
             ...this._customTools.map((definition) => ({
                 definition,
                 sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, { source: "sdk" }),
@@ -5176,7 +5505,7 @@ export class AgentSession {
                 finalError: "Retry cancelled",
             });
             this._resolveRetry();
-            return "not-handled";
+            return "cancelled";
         }
         this._retryAbortController = undefined;
         // Turn boundary: a suppression that expired during the backoff sleep lets
@@ -5192,7 +5521,10 @@ export class AgentSession {
             model &&
             shouldCompact(contextTokens, model.contextWindow, compactionSettings)) {
             const preRetryCompaction = await this._runPrePromptCompaction(message, true, "threshold", true, true);
-            if (!preRetryCompaction && !this._isCompactionOnCooldown() && !this._isCompactionDelegated()) {
+            if (!preRetryCompaction &&
+                !this._isCompactionOnCooldown() &&
+                !this._isCompactionDelegated() &&
+                !this._hasSupersedingCompactionClaim()) {
                 const attempt = this._retryAttempt;
                 this._retryAttempt = 0;
                 this._resetHintTierState();
@@ -5219,6 +5551,12 @@ export class AgentSession {
             timeoutMs: this.agent.timeoutMs,
             streamStartTimeoutMs: this.agent.streamStartTimeoutMs,
         });
+        if (continuation.options.deferQueuedMessages === true) {
+            DEFERRED_RETRY_QUEUE_OWNERS.add(this);
+        }
+        else {
+            DEFERRED_RETRY_QUEUE_OWNERS.delete(this);
+        }
         this.agent.suppressQueuedMessageDrain();
         this._scheduleContinuationAfterCurrentEvent(continuation.options, true, continuation.watchdogTimeoutMs);
         return "continued";
@@ -5681,11 +6019,11 @@ export class AgentSession {
     /**
      * Export session to HTML.
      * @param outputPath Optional output path (defaults to session directory)
+     * @param options Optional export presentation settings
      * @returns Path to exported file
      */
-    async exportToHtml(outputPath) {
-        const configuredThemeName = this.settingsManager.getTheme();
-        const themeName = configuredThemeName && getThemeByName(configuredThemeName) ? configuredThemeName : undefined;
+    async exportToHtml(outputPath, options = {}) {
+        const themeName = [options.themeName, this.settingsManager.getTheme()].find((candidate) => candidate !== undefined && getThemeByName(candidate) !== undefined);
         // Create tool renderer if we have an extension runner (for custom tool HTML rendering)
         const toolRenderer = createToolHtmlRenderer({
             getToolDefinition: (name) => this.getToolDefinition(name),