@prestyj/cli 5.11.0 → 5.13.0

package/dist/core/agent-session.js

@@ -6,9 +6,10 @@ import { PROMPT_COMMANDS, getPromptCommand } from "./prompt-commands.js";
 import { loadCustomCommands } from "./custom-commands.js";
 import { SettingsManager } from "./settings-manager.js";
 import { AuthStorage } from "./auth-storage.js";
-import { MOONSHOT_OAUTH_KEY } from "@prestyj/core";
+import { dualAuthProvider } from "@prestyj/core";
 import { getClaudeCliUserAgent } from "./claude-code-version.js";
 import { kimiCodingHeaders, isKimiCodingEndpoint } from "./oauth/kimi.js";
+import { isGrokCliEndpoint } from "./oauth/xai.js";
 import { SessionManager, NOLAN_TURN_CUSTOM_KIND, AUTOPILOT_MARKER_CUSTOM_KIND, APP_MARKER_CUSTOM_KIND, } from "./session-manager.js";
 import { ExtensionLoader } from "./extensions/loader.js";
 import { shouldCompact, compact, } from "./compaction/compactor.js";
@@ -17,8 +18,9 @@ import { sourceFingerprint as computeSourceFingerprint } from "./session-compact
 import { getAuthStorageKeys, getContextWindow, getModel, getToolResultCharLimit, MODELS, } from "./model-registry.js";
 import { discoverSkills } from "./skills.js";
 import { ensureAppDirs } from "../config.js";
-import { buildSystemPrompt } from "../system-prompt.js";
+import { buildSubAgentSystemPrompt, buildSystemPrompt, } from "../system-prompt.js";
 import { createTools, createWebSearchTool, } from "../tools/index.js";
+import { partitionToolsByTier } from "../tools/tool-tiers.js";
 import { buildProcessCompletionFollowUp } from "./process-gate.js";
 import { buildSubAgentCompletionFollowUp } from "./subagent-manager.js";
 import { applyAsyncSubagentPolicy } from "./subagent-policy.js";
@@ -41,6 +43,7 @@ import { evaluateLoopBreak, buildLoopBreakMessage, CycleDetector, ToolCallProgre
 import { buildRegroundingMessage } from "./regrounding.js";
 import { wrapSteeringText, buildNotificationSteeringText, STEERING_PREFIX } from "./steering.js";
 import { AgentNotificationQueue } from "./agent-notifications.js";
+import { VerificationGate, isCodeFilePath, isVerificationCommand } from "./verification-gate.js";
 import { findUserSessionPrompt, getUserSessionPrompt } from "./session-preview.js";
 import { normalizeMessageImages } from "./message-images.js";
 import crypto from "node:crypto";
@@ -138,6 +141,14 @@ export class AgentSession {
     idealReviewPhase = "idle";
     /** Runtime-only suppression while Nolan owns verification in autopilot mode. */
     idealReviewSuppressed = false;
+    /** Mirror of the last `hook_armed` value broadcast this run, so the event
+     *  fires only on a real edge. */
+    idealReviewArmed = false;
+    /** Cached test-drift probe, keyed by the size of the edited-file set. Drift
+     *  depends only on WHICH files were edited and that set only grows, so this
+     *  keeps the arming check off the filesystem on most tool results — the probe
+     *  is several sync existsSync calls per edited file. */
+    idealDriftProbe = null;
     reviewCoverage;
     /** Coverage follow-ups spent this run, capped by MAX_REVIEW_COVERAGE_INJECTIONS. */
     reviewCoverageInjected = 0;
@@ -148,6 +159,8 @@ export class AgentSession {
     runStartedAt = 0;
     /** Gate injections spent this run, capped by MAX_PROCESS_GATE_INJECTIONS. */
     processGateInjected = 0;
+    /** Verification gate: code edited this run, nothing proved it since. */
+    verificationGate = new VerificationGate();
     compactionOccurred = false;
     lastCompactionCompacted = false;
     compactionRetryAfter = 0;
@@ -180,8 +193,14 @@ export class AgentSession {
         void this.subAgentManager?.interruptAll();
     };
     mcpManager;
-    /** Deferred MCP tools awaiting discovery via tool_search (bench A win). */
+    /** Deferred MCP tools awaiting discovery via tool_search. */
     mcpCatalog;
+    /**
+     * Built-in tools held in the catalog instead of the live toolset. Their names
+     * still render as one-line hints in the prompt's Tools section, so the model
+     * can discover and promote them; a promoted name drops out of this list.
+     */
+    deferredBuiltinToolNames = [];
     /** Live (connected) MCP tools by name — the reconcile target for cached stubs. */
     liveMcpTools = new Map();
     /** Server name for each cached-only tool, so a stub knows what to wait on. */
@@ -199,6 +218,8 @@ export class AgentSession {
     maxTokens;
     thinkingLevel;
     customSystemPrompt;
+    /** Sub-agent definition body composed into the standard prompt scaffolding. */
+    agentPrompt;
     /** Stable prompt prefix retained separately from the volatile uncached tail. */
     baseSystemPrompt = "";
     /** Shared with the tool layer so plan-mode restrictions read live state. */
@@ -258,6 +279,7 @@ export class AgentSession {
         this.maxTokens = this.resolveMaxTokens(options.model);
         this.thinkingLevel = options.thinkingLevel;
         this.customSystemPrompt = options.systemPrompt;
+        this.agentPrompt = options.agentPrompt;
     }
     /**
      * Derive the output-token cap for a model. Follows the active model's
@@ -338,6 +360,7 @@ export class AgentSession {
                 additionalRoots: this.additionalRoots,
                 allowOutsideWorkspaceWrites: this.settingsManager.get("allowOutsideWorkspaceWrites"),
             }),
+            getUseExternalGrep: () => this.settingsManager.get("grepUseRipgrep"),
             authStorage: this.authStorage,
             onFileRead: (filePath) => this.reviewCoverage.recordRead(filePath),
             onFileMutated: (filePath) => {
@@ -375,6 +398,23 @@ export class AgentSession {
         // a hallucinated call can't mutate the repo — and buildSystemPrompt below is
         // fed the same filtered names so the Tools section matches exactly.
         this.tools = this.opts.allowedTools ? tools.filter((t) => this.isToolAllowed(t.name)) : tools;
+        // Tier the built-ins: rarely reached schemas move into the tool_search
+        // catalog and cost one hint line each instead of a full parameter schema on
+        // every request. Allow-listed sessions keep the eager path — their fixed
+        // tool expectations predate the catalog, and tool_search isn't allow-listed.
+        if (!this.opts.allowedTools && this.settingsManager.get("deferredBuiltinTools")) {
+            const { core, deferred } = partitionToolsByTier(this.tools);
+            if (deferred.length > 0) {
+                // Append-only: `core` preserves the original relative order and
+                // tool_search is pushed after it, so the serialized tool block that
+                // sits inside the cached prefix stays byte-stable across turns.
+                this.tools = core;
+                this.deferredBuiltinToolNames = deferred.map((t) => t.name);
+                this.mcpCatalog ??= new DeferredToolCatalog();
+                this.mcpCatalog.add(deferred);
+                this.ensureToolSearchTool();
+            }
+        }
         this.rebuildReadTool = rebuildReadTool;
         this.processManager = processManager;
         this.lspManager = lspManager;
@@ -394,8 +434,7 @@ export class AgentSession {
         else {
             await this.connectMcpServers();
         }
-        const basePrompt = this.customSystemPrompt ??
-            (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider, this.promptEnvironment()));
+        const basePrompt = await this.buildBasePrompt(false, undefined);
         this.baseSystemPrompt = basePrompt;
         this.messages = [{ role: "system", content: this.withSystemPromptTail(basePrompt) }];
         // Load or create session. Transient sessions (subagent spawns) never
@@ -542,7 +581,9 @@ export class AgentSession {
                     // GLM not configured — skip Z.AI MCP servers
                 }
             }
-            let servers = await getAllMcpServers(this.provider, apiKey, this.cwd);
+            let servers = await getAllMcpServers(this.provider, apiKey, this.cwd, {
+                allowProjectScope: this.settingsManager.isProjectTrusted(this.cwd),
+            });
             // Whitelisted allow-listed session: connect ONLY the named servers, never
             // the user's full configured set (which could include mutating tools). The
             // whitelist only restricts in allow-list mode (the documented contract) so
@@ -573,15 +614,25 @@ export class AgentSession {
             if (this.opts.backgroundMcpConnect && mcpTools.length > 0) {
                 await this.rebuildSystemPromptInPlace();
             }
+            // Detect project-scope servers excluded because the repo isn't trusted,
+            // so the host can offer a per-repo "Trust" button. Computed after the
+            // connect so the blocked list reflects the same connect attempt.
         }
         catch (err) {
             log("WARN", "mcp", `MCP initialization failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /** Persist `cwd` as a trusted project for project-scope MCP. Called by the
+     *  sidecar's `/mcp/add` handler when a user adds a project-scope server via
+     *  the MCP modal — the explicit add is itself the trust signal. The next
+     *  session load connects its `.ezcoder/mcp.json` servers. */
+    async trustProject(cwd) {
+        await this.settingsManager.trustProject(cwd);
+    }
     /**
      * Route freshly connected MCP tools: deferred into the tool_search catalog
-     * (default — keeps ~8k tokens of schema out of every cache-miss turn, see
-     * bench/RESULTS.md bench A) or pushed eagerly when the user opted out.
+     * (default — keeps ~8k tokens of schema out of every cache-miss turn) or
+     * pushed eagerly when the user opted out.
      * Allow-listed sessions (Nolan) always get the eager path — their fixed tool
      * expectations predate the catalog, and tool_search isn't allow-listed.
      * Promotion pushes onto the live `this.tools` array the running agent loop
@@ -611,10 +662,13 @@ export class AgentSession {
      * Register `tool_search` once. Promotion of a cached-only entry waits for its
      * server so the model is told immediately when that capability turns out to
      * be unreachable, instead of promoting a tool that fails on first call.
+     *
+     * The catalog is created on demand rather than required up front: deferred
+     * built-in tools populate it with zero MCP servers connected, so gating
+     * registration on an existing catalog would leave those tools unreachable.
      */
     ensureToolSearchTool() {
-        if (!this.mcpCatalog)
-            return;
+        this.mcpCatalog ??= new DeferredToolCatalog();
         if (this.tools.some((t) => t.name === "tool_search"))
             return;
         this.tools.push(createToolSearchTool(this.mcpCatalog, (promoted) => {
@@ -905,10 +959,14 @@ export class AgentSession {
         this.reviewCoverage.reset();
         this.reviewCoverageInjected = 0;
         this.idealReviewPhase = "idle";
+        // No event here: clients reset their own hold on run_start.
+        this.idealReviewArmed = false;
+        this.idealDriftProbe = null;
         this.loopBreakInjected = 0;
         this.regroundingInjected = false;
         this.runStartedAt = Date.now();
         this.processGateInjected = 0;
+        this.verificationGate.reset();
         this.compactionOccurred = false;
         this.originalRequest = originalRequest;
     }
@@ -947,10 +1005,40 @@ export class AgentSession {
                     const removed = (diff.match(/^-[^-]/gm) ?? []).length;
                     this.hookStats.changedLines += added + removed;
                 }
+                // Verification-gate bookkeeping: successful code mutations and completed
+                // foreground verification commands, in occurrence order.
+                if (!event.isError && args) {
+                    if ((name === "edit" || name === "write") &&
+                        isCodeFilePath(String(args.file_path ?? ""))) {
+                        this.verificationGate.recordMutation(String(args.file_path));
+                    }
+                    if (name === "bash" &&
+                        !args.run_in_background &&
+                        isVerificationCommand(String(args.command ?? ""))) {
+                        this.verificationGate.recordVerification();
+                    }
+                    // Reading the final output of an EXITED background verification run
+                    // counts: the process gate forces this read anyway, so without it the
+                    // gate would demand a redundant foreground re-run of tests the agent
+                    // already watched finish.
+                    if (name === "task_output") {
+                        const proc = this.processManager
+                            ?.list()
+                            .find((p) => p.id === args.id);
+                        if (proc && proc.exitCode !== null && isVerificationCommand(proc.command)) {
+                            this.verificationGate.recordVerification();
+                        }
+                    }
+                }
+                // Tool results are what push the run over the review gate, and they all
+                // land before the model writes its candidate final answer — so this is
+                // the point where arming still beats the draft's first token.
+                this.refreshIdealReviewArmed();
                 break;
             }
             case "turn_end":
                 this.hookStats.turns = event.turn;
+                this.refreshIdealReviewArmed();
                 for (let index = this.messages.length - 1; index >= 0; index--) {
                     const anchor = this.messages[index];
                     if (anchor?.role === "assistant") {
@@ -1134,6 +1222,51 @@ export class AgentSession {
         });
         return granted;
     }
+    /**
+     * Would the stop AFTER the current turn inject the Ideal review? Same inputs
+     * as the pre-stop gate below, evaluated early so clients know a candidate
+     * final answer is a review draft BEFORE it streams.
+     *
+     * The turn count is looked ahead by one on purpose. `hookStats.turns` only
+     * advances at `turn_end`, so while the model is writing the draft the counter
+     * still reads the PREVIOUS turn; the real gate sees one more. Without the
+     * lookahead a run sitting on score 3 crosses to 4 on the draft's own
+     * `turn_end` — after the text already streamed — which is precisely the
+     * appear-then-vanish flash. Over-arming by one turn point costs only live
+     * token streaming on a final answer that then shows whole; under-arming costs
+     * the flash, so this errs toward arming.
+     */
+    wouldInjectIdealReview() {
+        if (this.opts.selfCorrectionHooks === false || this.idealReviewSuppressed)
+            return false;
+        if (this.idealReviewPhase !== "idle")
+            return false;
+        if (!this.settingsManager.get("idealReviewEnabled"))
+            return false;
+        if (evaluateIdealReview({ ...this.hookStats, turns: this.hookStats.turns + 1 }).shouldReview) {
+            return true;
+        }
+        const files = this.hookFileEditCounts.size;
+        if (files === 0)
+            return false;
+        if (this.idealDriftProbe?.files !== files) {
+            this.idealDriftProbe = {
+                files,
+                drifted: detectTestDrift(this.hookFileEditCounts.keys(), this.cwd).length > 0,
+            };
+        }
+        return this.idealDriftProbe.drifted;
+    }
+    /** Broadcast Ideal-review arming on change. Both edges matter: armed=false
+     *  after the review fires is what lets a client stream the REVIEWED final
+     *  answer live again. */
+    refreshIdealReviewArmed() {
+        const armed = this.wouldInjectIdealReview();
+        if (armed === this.idealReviewArmed)
+            return;
+        this.idealReviewArmed = armed;
+        this.eventBus.emit("hook_armed", { kind: "ideal", armed });
+    }
     /**
      * Pre-stop Ideal review phase machine. Once review starts, completion is
      * blocked until harness-owned post-injection reads cover every changed file.
@@ -1153,6 +1286,18 @@ export class AgentSession {
             });
             return processFollowUp;
         }
+        // Verification gate: code was edited but nothing verified since the last
+        // edit. Above the Ideal review so checks RUN before the read-based review
+        // starts; off for allow-listed sessions that cannot run commands at all.
+        if (this.opts.selfCorrectionHooks !== false &&
+            this.settingsManager.get("verificationGateEnabled") &&
+            (!this.opts.allowedTools || this.opts.allowedTools.includes("bash"))) {
+            const verificationFollowUp = this.verificationGate.followUp();
+            if (verificationFollowUp) {
+                log("INFO", "verification-gate", "Injecting verification follow-up", {});
+                return verificationFollowUp;
+            }
+        }
         if (this.opts.selfCorrectionHooks === false || this.idealReviewSuppressed)
             return null;
         if (this.idealReviewPhase === "reviewing") {
@@ -1202,6 +1347,11 @@ export class AgentSession {
             coverageExpected: coverage.expected,
             coverageMissing: coverage.missing,
         });
+        // Disarm strictly AFTER the hook event. Clients release held text on
+        // disarm, so the reverse order would paint the draft and then delete it —
+        // the exact flash arming exists to prevent. Leaving `idle` is what lets the
+        // reviewed final answer stream live instead of being held.
+        this.refreshIdealReviewArmed();
         log("INFO", "ideal", "Injecting ideal review before final response", {
             coverageExpected: coverage.expected,
             coverageMissing: coverage.missing,
@@ -1271,6 +1421,10 @@ export class AgentSession {
         // Cache for sync callers (see field doc) — kept in step with `creds`
         // through the 401 force-refresh retry below.
         this.lastAccountId = creds.accountId;
+        // The access token most recently handed to the provider. Tracked separately
+        // from `creds` because the per-turn resolver can rotate it mid-run, and the
+        // 401 handler must name the token that was actually rejected.
+        let lastResolvedAccessToken = creds.accessToken;
         // Auto-compact if needed. This must happen after credential resolution so
         // OpenAI OAuth/Codex sessions use the Codex product context window instead
         // of the public API model window. Failed/no-op attempts cool down across
@@ -1332,6 +1486,7 @@ export class AgentSession {
         const userAgent = this.provider === "anthropic" ? await getClaudeCliUserAgent() : undefined;
         const loopMessages = await this.prepareDynamicContext();
         const runAgentLoop = async (apiKey, accountId, projectId) => {
+            lastResolvedAccessToken = apiKey;
             const modelInfo = getModel(this.model);
             const effectiveBaseUrl = this.baseUrl ?? creds.baseUrl;
             const generator = agentLoop(loopMessages, {
@@ -1344,6 +1499,23 @@ export class AgentSession {
                 maxTurnExtensions: this.opts.maxTurnExtensions,
                 thinking: this.thinkingLevel,
                 apiKey,
+                // Per-turn credential resolution. A run can span many minutes; if any
+                // process sharing auth.json refreshes this grant meanwhile, the token
+                // captured above is invalidated server-side and every remaining turn
+                // would fail with an authentication error until the user restarted.
+                // Static API keys resolve to the same value, so this is a no-op for them.
+                resolveCredentials: async () => {
+                    const live = await this.authStorage.resolveCredentials(this.provider, {
+                        storageKeys: this.currentAuthStorageKeys(),
+                    });
+                    this.lastAccountId = live.accountId;
+                    lastResolvedAccessToken = live.accessToken;
+                    return {
+                        apiKey: live.accessToken,
+                        ...(live.accountId !== undefined ? { accountId: live.accountId } : {}),
+                        ...(live.projectId !== undefined ? { projectId: live.projectId } : {}),
+                    };
+                },
                 baseUrl: effectiveBaseUrl,
                 signal: this.opts.signal,
                 accountId,
@@ -1507,29 +1679,45 @@ export class AgentSession {
             if (isAbortError(err) || this.opts.signal?.aborted) {
                 return;
             }
-            // Kimi OAuth plan ran out of usage (hard usage-limit stop, or an HTTP 402
-            // billing stop). If the user ALSO configured a Moonshot API key, mark
-            // the OAuth credential usage-exhausted (honoring the provider-stated
-            // reset time when present) and retry this turn on the API key — OAuth
-            // stays the preferred credential and resumes automatically once the mark
-            // lapses. A generic 429 is deliberately excluded: it may be a transient
-            // rate limit and must not silently switch the user to a billed API key.
-            // Guarded on the Kimi managed endpoint actually being in use: if the API
-            // key was already active, the same error means BOTH are out and must surface.
-            if (this.provider === "moonshot" &&
+            // A subscription OAuth plan ran out of usage (hard usage-limit stop, or an
+            // HTTP 402 billing stop). If the user ALSO configured that provider's API
+            // key, mark the OAuth credential usage-exhausted (honoring the
+            // provider-stated reset time when present) and retry this turn on the API
+            // key — OAuth stays the preferred credential and resumes automatically once
+            // the mark lapses. A generic 429 is deliberately excluded: it may be a
+            // transient rate limit and must not silently switch the user to a billed
+            // API key.
+            //
+            // Grok adds one case Kimi doesn't have: xAI gates its CLI chat proxy by
+            // subscription tier, so an entitled-looking account can be refused outright
+            // with a 403. That means "OAuth cannot serve this", not a transient error,
+            // so it counts as exhausted too — otherwise a dual-configured user would
+            // hard-fail while holding a perfectly good API key.
+            //
+            // Guarded on the subscription endpoint actually being in use: if the API key
+            // was already active, the same error means BOTH are out and must surface.
+            const dualAuth = dualAuthProvider(this.provider);
+            const onSubscriptionEndpoint = (this.provider === "moonshot" && isKimiCodingEndpoint(creds.baseUrl)) ||
+                (this.provider === "xai" && isGrokCliEndpoint(creds.baseUrl));
+            const tierRefusal = this.provider === "xai" && err instanceof ProviderError && err.statusCode === 403;
+            const oauthIsOut = isUsageLimitError(err) ||
+                (err instanceof ProviderError && err.statusCode === 402) ||
+                tierRefusal;
+            if (dualAuth &&
                 !this.baseUrl &&
-                isKimiCodingEndpoint(creds.baseUrl) &&
-                (isUsageLimitError(err) || (err instanceof ProviderError && err.statusCode === 402)) &&
-                (await this.authStorage.hasCredentials("moonshot"))) {
+                onSubscriptionEndpoint &&
+                oauthIsOut &&
+                (await this.authStorage.hasCredentials(dualAuth.provider))) {
                 const resetsAt = err instanceof ProviderError ? err.resetsAt : undefined;
-                await this.authStorage.markUsageExhausted(MOONSHOT_OAUTH_KEY, resetsAt);
-                log("WARN", "auth", "Kimi OAuth usage limit reached — retrying this turn on the Moonshot API key", { resetsAt: resetsAt !== undefined ? String(resetsAt) : "unknown" });
+                await this.authStorage.markUsageExhausted(dualAuth.oauthKey, resetsAt);
+                log("WARN", "auth", `${dualAuth.oauthLabel} usage limit reached — retrying this turn on the ${dualAuth.apiKeyLabel}`, { resetsAt: resetsAt !== undefined ? String(resetsAt) : "unknown" });
                 creds = await this.authStorage.resolveCredentials(this.provider, {
                     storageKeys: this.currentAuthStorageKeys(),
                 });
                 this.lastAccountId = creds.accountId;
                 // The runAgentLoop closure re-reads `creds`, so the retry picks up the
-                // API key's baseUrl (api.moonshot.ai) and drops the Kimi coding headers.
+                // API key's public baseUrl (api.moonshot.ai / api.x.ai) and drops the
+                // subscription endpoint's client-identity headers.
                 try {
                     await runAgentLoop(creds.accessToken, creds.accountId, creds.projectId);
                 }
@@ -1544,15 +1732,21 @@ export class AgentSession {
             else if (err instanceof ProviderError && err.statusCode === 401) {
                 // Static API-key providers (GLM, Moonshot API key, etc.) have no refresh
                 // mechanism — retrying with the same key is pointless. Clear the
-                // credential and surface the error so the user re-logins. Kimi OAuth
-                // (active for `moonshot` when present) is refreshable, so it falls
-                // through to the force-refresh path below.
+                // credential and surface the error so the user re-logins. Subscription
+                // OAuth (active for `moonshot`/`xai` when present) is refreshable, so it
+                // falls through to the force-refresh path below.
                 if (await clearInvalidStaticApiKey(err))
                     throw err;
                 log("INFO", "auth", "Got 401, force-refreshing token and retrying");
                 creds = await this.authStorage.resolveCredentials(this.provider, {
                     forceRefresh: true,
                     storageKeys: this.currentAuthStorageKeys(),
+                    // Name the token the provider actually rejected (which the per-turn
+                    // resolver may have rotated since the run started). If disk already
+                    // holds a newer one, adopt it instead of minting another — a fresh
+                    // refresh would invalidate the token every sibling process is using
+                    // and turn one 401 into a cascade of them.
+                    rejectedToken: lastResolvedAccessToken,
                 });
                 this.lastAccountId = creds.accountId;
                 await runAgentLoop(creds.accessToken, creds.accountId, creds.projectId);
@@ -1666,7 +1860,9 @@ export class AgentSession {
                         }
                     }
                     // Use getAllMcpServers so user-configured servers survive the reconnect.
-                    const servers = await getAllMcpServers(this.provider, apiKey, this.cwd);
+                    const servers = await getAllMcpServers(this.provider, apiKey, this.cwd, {
+                        allowProjectScope: this.settingsManager.isProjectTrusted(this.cwd),
+                    });
                     const mcpTools = await this.mcpManager.connectAll(servers);
                     // Drop stale MCP tools from both the live set and deferred catalog before
                     // re-adding. Some tools may already have been promoted out of the catalog.
@@ -1934,8 +2130,7 @@ export class AgentSession {
         this.autopilotMarkers = [];
         this.appMarkers = [];
         this.turnMetrics = [];
-        const basePrompt = this.customSystemPrompt ??
-            (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider, this.promptEnvironment()));
+        const basePrompt = await this.buildBasePrompt(false, undefined);
         this.baseSystemPrompt = basePrompt;
         this.messages = [{ role: "system", content: this.withSystemPromptTail(basePrompt) }];
         // Fresh conversation — new entries must not chain onto the old DAG's leaf.
@@ -2070,6 +2265,9 @@ export class AgentSession {
             this.idealReviewPhase = "idle";
             this.reviewCoverage.reset();
         }
+        // Suppression flips mid-run (autopilot takes over verification), so a client
+        // holding a draft under a stale arming must be released.
+        this.refreshIdealReviewArmed();
     }
     /** Queue a user message (optionally with attachments) to be injected mid-run
      *  as steering. Returns the new queue length. No-op semantics are the caller's
@@ -2217,6 +2415,17 @@ export class AgentSession {
         await this.rebuildSystemPromptInPlace();
         return { ok: true, root: resolved };
     }
+    /**
+     * Names to advertise as available-on-demand. A tool the model already
+     * promoted lives in `this.tools` and carries its own schema, so it drops out
+     * of the index rather than being listed twice.
+     */
+    deferredToolNamesForPrompt(liveNames) {
+        if (this.deferredBuiltinToolNames.length === 0)
+            return [];
+        const live = new Set(liveNames);
+        return this.deferredBuiltinToolNames.filter((name) => !live.has(name));
+    }
     /** Environment facts that vary per session rather than per host. */
     promptEnvironment() {
         const networkAllow = this.settingsManager.get("networkMode") === "allowlist"
@@ -2224,11 +2433,37 @@ export class AgentSession {
             : [];
         return { additionalRoots: this.additionalRoots, networkAllow };
     }
+    /**
+     * Build the stable system-prompt prefix for the current tool set and state.
+     *
+     * Three modes, in precedence order: a full replacement (`systemPrompt`), a
+     * composed sub-agent prompt (`agentPrompt` — agent body plus Tools, project
+     * context, return contract and Environment), or the standard prompt.
+     */
+    async buildBasePrompt(planMode, approvedPlanPath) {
+        if (this.customSystemPrompt)
+            return this.customSystemPrompt;
+        const toolNames = this.tools.map((tool) => tool.name);
+        const deferredToolNames = this.deferredToolNamesForPrompt(toolNames);
+        if (this.agentPrompt !== undefined) {
+            return buildSubAgentSystemPrompt(this.agentPrompt, {
+                cwd: this.cwd,
+                toolNames,
+                deferredToolNames,
+                context: this.opts.agentContext,
+                environment: this.promptEnvironment(),
+            });
+        }
+        return buildSystemPrompt(this.cwd, this.skills, planMode, approvedPlanPath, toolNames, undefined, this.provider, this.promptEnvironment(), deferredToolNames);
+    }
     /** Rebuild messages[0] from current plan-mode + approved-plan state. */
     async rebuildSystemPromptInPlace() {
+        // A full replacement is verbatim by contract — there is nothing to rebuild.
+        // A composed agent prompt still must be: its Tools section has to follow
+        // late-arriving MCP tools, or a compacted child loses tools it can call.
         if (this.customSystemPrompt)
             return;
-        const rebuilt = await buildSystemPrompt(this.cwd, this.skills, this.planModeRef.current, this.approvedPlanPath, this.tools.map((tool) => tool.name), undefined, this.provider, this.promptEnvironment());
+        const rebuilt = await this.buildBasePrompt(this.planModeRef.current, this.approvedPlanPath);
         this.baseSystemPrompt = rebuilt;
         const content = this.withSystemPromptTail(rebuilt);
         if (this.messages[0]?.role === "system") {