@prestyj/cli 5.29.1 → 5.30.1

package/dist/core/agent-session.js

@@ -13,31 +13,27 @@ import { dualAuthProvider } from "@prestyj/core";
 import { getClaudeCliUserAgent, recordRequiredClaudeCodeVersion } 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 { SessionManager, } from "./session-manager.js";
 import { ExtensionLoader } from "./extensions/loader.js";
 import { shouldCompact, compact, } from "./compaction/compactor.js";
-import { getHistoryMessageVisibility, remapAnchorForCompaction, stripRecordedPosition, } from "./session-history.js";
+import { getHistoryMessageVisibility } from "./session-history.js";
 import { sourceFingerprint as computeSourceFingerprint } from "./session-compaction.js";
-import { getAuthStorageKeys, getContextWindow, getModel, getToolResultCharLimit, MODELS, } from "./model-registry.js";
+import { getAuthStorageKeys, getContextWindow, getModel, MODELS } from "./model-registry.js";
 import { discoverSkills } from "./skills.js";
 import { ensureAppDirs } from "../config.js";
 import { buildSubAgentSystemPrompt, buildSystemPrompt, } from "../system-prompt.js";
 import { createTools, createWebSearchTool, } from "../tools/index.js";
 import { partitionToolsByTier } from "../tools/tool-tiers.js";
 import { formatImpactForVerification } from "./test-impact.js";
-import { autoBackgroundedId } from "../tools/bash.js";
 import { buildProcessCompletionFollowUp } from "./process-gate.js";
+import { PLAN_SUBMISSION_NUDGE, shouldNudgePlanSubmission } from "./plan-submission-gate.js";
 import { buildSubAgentCompletionFollowUp } from "./subagent-manager.js";
 import { applyAsyncSubagentPolicy } from "./subagent-policy.js";
 import { resolveResponsesLite, resolveStrictTools, } from "./codex-request-shape.js";
 import { subAgentDescription } from "../tools/subagent.js";
-import { z } from "zod";
-import { MCPClientManager, getAllMcpServers } from "./mcp/index.js";
-import { clampMcpToolDescription, DeferredToolCatalog } from "./mcp/deferred-catalog.js";
+import { getAllMcpServers } from "./mcp/index.js";
 import { CONTEXT_LIMITS, resolveSessionContextLimits, } from "./context-limits.js";
-import { McpCatalogCache } from "./mcp/catalog-cache.js";
 import { describeDropped, importForeignSession, } from "./foreign-session-import.js";
-import { createToolSearchTool } from "../tools/tool-search.js";
 import { createSessionStatsTool } from "../tools/session-stats.js";
 import { createDiagnoseCommand, isInternalDiagnosticsEnabled, SessionDiagnosticsRecorder, } from "./internal-diagnostics.js";
 import { log } from "./logger.js";
@@ -54,15 +50,13 @@ import { pruneStaleToolResults } from "./compaction/tool-result-pruner.js";
 import { discoverAgents } from "./agents.js";
 import { enhancePrompt } from "../utils/prompt-enhancer.js";
 import { detectLanguages, detectProjectStack } from "./language-detector.js";
-import { evaluateLoopBreak, buildLoopBreakMessage, CycleDetector, ToolCallProgressTracker, detectTextRepetition, } from "./loop-breaker.js";
+import { buildLoopBreakMessage } from "./loop-breaker.js";
 import { buildRegroundingMessage, requestTextForRegrounding } from "./regrounding.js";
-import { buildSemanticLoopJudgePrompt, buildSemanticLoopMessage, MAX_SEMANTIC_LOOP_CALLS, parseSemanticLoopVerdict, shouldRunSemanticLoopCheck, SEMANTIC_LOOP_JUDGE_TIMEOUT_MS, withJudgeTimeout, } from "./semantic-loop-check.js";
+import { buildSemanticLoopJudgePrompt, buildSemanticLoopMessage, parseSemanticLoopVerdict, SEMANTIC_LOOP_JUDGE_TIMEOUT_MS, withJudgeTimeout, } from "./semantic-loop-check.js";
 import { buildEnvDeltaMessage } from "./env-delta.js";
 import { wrapSteeringText, buildNotificationSteeringText, STEERING_PREFIX } from "./steering.js";
 import { AgentNotificationQueue } from "./agent-notifications.js";
-import { VerificationGate, isCheckOwnFile, extractAddedLines, isCodeFilePath, VERIFICATION_STATE_KIND, isVerificationCommand, } from "./verification-gate.js";
-import { classifyVerificationCommand } from "./verification-evidence.js";
-import { captureVerificationSnapshot } from "./verification-snapshot.js";
+import { VerificationGate, VERIFICATION_STATE_KIND } from "./verification-gate.js";
 import { findUserSessionPrompt, getUserSessionPrompt } from "./session-preview.js";
 import { normalizeMessageImages } from "./message-images.js";
 import { loadStreamRules } from "./stream-rules.js";
@@ -70,41 +64,12 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { editTargetPaths } from "../tools/edit-targets.js";
-/**
- * A run whose tool calls fail more often than this is thrashing, not
- * progressing — refuse to extend its turn budget.
- */
-const TURN_EXTENSION_MAX_FAILURE_RATIO = 0.5;
-// ── Tool-result policy ─────────────────────────────────────
-/** Resolve the per-result cap passed to the agent loop for the active transport. */
-export function resolveSessionToolResultCharLimit(model, provider, accountId) {
-    return (getToolResultCharLimit(model, { provider, accountId }) ??
-        Math.floor(getContextWindow(model, { provider, accountId }) * 3.5 * 0.3));
-}
-/**
- * Aggregate budget for ALL tool results produced in one assistant turn.
- * Individual results are already capped, but wide parallel fan-outs (GPT-5.6's
- * signature behavior) were observed injecting 100k+ uncached tokens in a single
- * turn. ~15% of the context window in chars (1 token ≈ 3.5 chars), floored at
- * 100KB so small windows still fit two full-size reads, ceilinged at 240KB so
- * 1M-context models don't waive the budget entirely.
- */
-export function resolveSessionTurnToolResultCharLimit(model, provider, accountId) {
-    const contextChars = getContextWindow(model, { provider, accountId }) * 3.5;
-    return Math.max(100_000, Math.min(Math.floor(contextChars * 0.15), 240_000));
-}
-/** Marker the compactor prepends to the summary message it injects. */
-/**
- * True when an assistant message ends a turn with tool calls still awaiting
- * their results. Inserting a user message there would orphan the tool_use
- * blocks and the provider rejects the next request.
- */
-function hasUnresolvedToolCalls(message) {
-    if (typeof message.content === "string" || !Array.isArray(message.content))
-        return false;
-    return message.content.some((part) => part.type === "tool_call");
-}
+import { resolveSessionToolResultCharLimit, resolveSessionTurnToolResultCharLimit, hasUnresolvedToolCalls, resolveHomePath, } from "./agent-session/helpers.js";
+import { RunLoopMonitor } from "./agent-session/run-loop-monitor.js";
+import { VerificationTracker } from "./agent-session/verification-tracker.js";
+import { McpToolRegistry } from "./agent-session/mcp-tools.js";
+import { TranscriptMarkers } from "./agent-session/transcript-markers.js";
+export { resolveSessionToolResultCharLimit, resolveSessionTurnToolResultCharLimit, } from "./agent-session/helpers.js";
 // ── Agent Session ──────────────────────────────────────────
 export class AgentSession {
     eventBus = new EventBus();
@@ -114,24 +79,10 @@ export class AgentSession {
     sessionManager;
     extensionLoader = new ExtensionLoader();
     messages = [];
-    // Nolan Grout (mentor agent) turns recorded against this build session. Advisory
-    // only — NEVER part of `messages` (EZ Coder must not see them), but persisted
-    // alongside the session and reloaded on resume so they reappear in the
-    // transcript. Each carries the non-system message count at record time so the
-    // webview can interleave them chronologically.
-    nolanTurns = [];
-    // Autopilot Nolan (auto-reviewer) markers recorded against this build session:
-    // the review verdict shown in the transcript (prompted / done / human /
-    // capped). Same not-on-the-DAG treatment as nolanTurns — advisory only,
-    // persisted + reloaded so a resumed session shows the identical Nolan bubble
-    // the live run showed instead of dropping it or replaying a raw verdict.
-    autopilotMarkers = [];
-    // Generic app transcript markers (plan-mode banner, task header, error rows,
-    // user-bubble display hints). Same not-on-the-DAG treatment as nolanTurns —
-    // display only, persisted + reloaded so a resumed session shows the same
-    // transcript rows the live run showed.
-    appMarkers = [];
-    turnMetrics = [];
+    // Display-only transcript history (Nolan turns, autopilot verdicts, app markers,
+    // turn metrics). NEVER part of `messages` (EZ Coder must not see them), but
+    // persisted alongside the session and reloaded on resume.
+    markers = new TranscriptMarkers(() => this.sessionManager, () => this.sessionPath);
     cacheDiagnostics = new CacheDiagnostics();
     /** Internal-only (EZ_INTERNAL): live per-session cost/reliability recorder.
      * Absent entirely in public builds — see core/internal-diagnostics.ts. */
@@ -150,25 +101,8 @@ export class AgentSession {
     // ── Self-correction hook state (mirrors the TUI's useAgentLoop refs) ──
     // Reset at the start of every run; observed from the event stream; read by
     // the loop-break (mid-loop) callback.
-    hookStats = { toolCalls: 0, toolFailures: 0, turns: 0 };
-    hookText = "";
-    hookConsecutiveFailures = 0;
-    hookRepeatedNoProgressCalls = 0;
-    hookProgressTracker = new ToolCallProgressTracker();
-    hookCycleDetector = new CycleDetector();
-    hookCyclicPattern = null;
-    hookFileEditCounts = new Map();
-    hookToolCalls = new Map();
-    backgroundVerification = new Map();
-    /** 0 = none; 1 = first nudge sent; 2 = final stop-and-report injected. */
-    loopBreakInjected = 0;
+    loopMonitor = new RunLoopMonitor();
     regroundingInjected = false;
-    /** Recent tool-call digests for the semantic loop judge — bounded ring. */
-    hookRecentCalls = [];
-    /** LLM-judged loop detection state. `verdict` holds a LOOP verdict awaiting
-     *  injection at the next steering poll; judge failures fail open (no
-     *  injection) and still consume budget + cooldown. */
-    semanticLoop = { checksUsed: 0, lastCheckTurn: 0, pending: false, verdict: null, injected: false };
     /**
      * The environment as the cached system prompt currently describes it.
      * Re-recorded on every prompt build, so a rebuild (e.g. `/add-dir`) needs no
@@ -179,10 +113,14 @@ export class AgentSession {
     runStartedAt = 0;
     /** Gate injections spent this run, capped by MAX_PROCESS_GATE_INJECTIONS. */
     processGateInjected = 0;
+    /** Plan-submission reminders spent this run (plan-submission-gate.ts). */
+    planSubmissionNudges = 0;
     /** Verification gate: code edited this run, nothing proved it since. Always
      *  tracks evidence for run status; the `verificationGateEnabled` setting
      *  decides whether an unverified stop is also continued once. */
     verificationGate = new VerificationGate();
+    /** Host-observed evidence (edited files, in-flight and background checks) feeding the gate. */
+    verificationTracker;
     /** Mirror of the last `hook_armed` value, so the event fires only on an edge. */
     preFinalArmed = false;
     compactionOccurred = false;
@@ -249,9 +187,8 @@ export class AgentSession {
         this.lspManager?.clearPendingDiagnostics();
         void this.subAgentManager?.interruptAll();
     };
-    mcpManager;
-    /** Deferred MCP tools awaiting discovery via tool_search. */
-    mcpCatalog;
+    /** MCP client, deferred tool_search catalog and cached-stub reconcile state. */
+    mcp = new McpToolRegistry(() => this.tools, () => this.contextLimits);
     /** Resolved prompt-injection byte budgets (contextLimits setting). */
     contextLimits = CONTEXT_LIMITS;
     /**
@@ -260,11 +197,6 @@ export class AgentSession {
      * 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. */
-    cachedMcpToolServers = new Map();
-    mcpCatalogCache = new McpCatalogCache();
     provider;
     model;
     cwd;
@@ -337,6 +269,7 @@ export class AgentSession {
     opts;
     constructor(options) {
         this.opts = options;
+        this.verificationTracker = new VerificationTracker(this.verificationGate, options.cwd, () => this.processManager?.list() ?? []);
         this.provider = options.provider;
         this.model = options.model;
         this.cwd = options.cwd;
@@ -438,12 +371,13 @@ export class AgentSession {
             authStorage: this.authStorage,
             onFileMutated: (filePath) => {
                 const relative = path.relative(this.cwd, filePath) || path.basename(filePath);
-                this.hookFileEditCounts.set(relative, (this.hookFileEditCounts.get(relative) ?? 0) + 1);
+                this.verificationTracker.recordFileMutated(relative);
             },
             // Lazy — sessionId/model/provider can change after createTools() runs, so
             // sub-agent spawns read the current parent state at execution time.
             getProvider: () => this.provider,
             getModel: () => this.model,
+            getThinkingLevel: () => this.thinkingLevel,
             getBaseUrl: () => this.baseUrl,
             getCacheKey: () => this.getPromptCacheKey(),
             getMaxPerModel: () => this.settingsManager.get("subagentMaxPerModel"),
@@ -484,6 +418,10 @@ export class AgentSession {
         // 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")) {
+            // Wrap before partitioning: spawn_agent itself may be deferred, and the
+            // catalog must hold the wrapped tool so a promoted spawn still loads
+            // wait_agent.
+            this.promoteFollowUpTools();
             const { core, deferred } = partitionToolsByTier(this.tools);
             if (deferred.length > 0) {
                 // Append-only: `core` preserves the original relative order and
@@ -491,10 +429,7 @@ export class AgentSession {
                 // 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.contextLimits);
-                this.mcpCatalog.add(deferred);
-                this.ensureToolSearchTool();
-                this.promoteWaitAgentAfterSpawn();
+                this.mcp.addDeferred(deferred);
             }
         }
         this.rebuildReadTool = rebuildReadTool;
@@ -509,8 +444,7 @@ export class AgentSession {
         // Connect MCP servers. Child sessions skip user-configured servers to avoid
         // cold-spawning every server per short-lived worker. Background connection
         // keeps slow first-run stdio servers off the host readiness path.
-        this.mcpManager = new MCPClientManager({
-            catalogCache: this.mcpCatalogCache,
+        this.mcp.createManager({
             modernProtocol: this.settingsManager.get("mcpModernProtocol"),
             onElicit: this.opts.onMcpElicit,
         });
@@ -659,7 +593,8 @@ export class AgentSession {
      * turn, so background-connected servers become available on the next prompt.
      */
     async connectMcpServers() {
-        if (!this.mcpManager)
+        const mcpManager = this.mcp.manager;
+        if (!mcpManager)
             return;
         // Allow-listed (read-only advisory) sessions enforce a fixed tool set by
         // name. An MCP server is only connected when its name is explicitly
@@ -695,7 +630,7 @@ export class AgentSession {
             // empty catalog and tool_search would answer "the catalog is empty" for
             // capabilities that genuinely exist — a wrong answer, not a slow one.
             await this.seedMcpCatalogFromCache(servers);
-            const connected = await this.mcpManager.connectAll(servers);
+            const connected = await mcpManager.connectAll(servers);
             // Defense-in-depth: even from a whitelisted server, only push tools that
             // pass the allow-list (no-op when there's no allow-list).
             const mcpTools = this.opts.allowedTools
@@ -734,170 +669,65 @@ export class AgentSession {
      * 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
-     * re-reads every turn, so promoted tools are callable on the next step.
      */
     addMcpTools(mcpTools) {
-        if (mcpTools.length === 0)
-            return;
-        for (const tool of mcpTools) {
-            this.liveMcpTools.set(tool.name, tool);
-            this.cachedMcpToolServers.delete(tool.name);
-        }
         const defer = !this.opts.allowedTools && this.settingsManager.get("deferredMcpTools");
-        if (!defer) {
-            // Eager path bypasses the catalog, so budget descriptions here too.
-            this.replaceOrPushTools(mcpTools.map((tool) => clampMcpToolDescription(tool, this.contextLimits)));
-            return;
-        }
-        this.mcpCatalog ??= new DeferredToolCatalog(this.contextLimits);
-        // `add` is name-keyed, so live definitions replace cached stubs in place.
-        this.mcpCatalog.add(mcpTools);
-        // A stub the model already promoted lives in `this.tools`; swap it for the
-        // live tool so later calls dispatch directly instead of through the stub.
-        this.replaceLivePromotedTools(mcpTools);
-        this.ensureToolSearchTool();
+        this.mcp.addMcpTools(mcpTools, defer);
     }
     /**
-     * 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.
+     * Deferred follow-up tools whose need is certain once a trigger succeeds.
+     * `wait_agent` follows nearly every `spawn_agent`, and loading it through
+     * `tool_search` cost a whole turn (bench 41: ~6 s per fan-out). Likewise a
+     * background `bash` is always followed by `task_output` (and sometimes
+     * `task_send`/`task_stop`). Promote them as soon as the trigger succeeds: the
+     * tool list grows exactly as it would after that `tool_search`, one turn
+     * earlier, and sessions that never trigger keep the smaller prefix.
+     * Call before tier partitioning so a deferred trigger is wrapped too.
      */
-    ensureToolSearchTool() {
-        this.mcpCatalog ??= new DeferredToolCatalog(this.contextLimits);
-        if (this.tools.some((t) => t.name === "tool_search"))
-            return;
-        this.tools.push(createToolSearchTool(this.mcpCatalog, (promoted) => {
-            this.tools.push(...promoted);
-        }, async (toolName) => {
-            if (this.liveMcpTools.has(toolName))
-                return undefined;
-            const serverName = this.cachedMcpToolServers.get(toolName);
-            if (!serverName)
-                return undefined;
-            const outcome = (await this.mcpManager?.whenConnected(serverName)) ?? {
-                ok: false,
-                error: "MCP is disabled for this session",
-            };
-            return outcome.ok
-                ? { serverName, ok: true }
-                : { serverName, ok: false, error: outcome.error };
-        }, this.contextLimits));
+    promoteFollowUpTools() {
+        this.wrapToPromote("spawn_agent", ["wait_agent"]);
+        this.wrapToPromote("bash", ["task_output", "task_send", "task_stop"], (args) => args.run_in_background === true);
     }
-    /**
-     * `wait_agent` is deferred, yet nearly every `spawn_agent` is followed by it,
-     * so the model spent a whole turn on `tool_search` just to load it (bench 41:
-     * ~6 s per fan-out). Promote it as soon as a spawn succeeds instead: the tool
-     * list grows exactly as it would after that `tool_search`, one turn earlier,
-     * and sessions that never spawn keep the smaller prefix.
-     */
-    promoteWaitAgentAfterSpawn() {
-        const index = this.tools.findIndex((t) => t.name === "spawn_agent");
-        const spawn = index >= 0 ? this.tools[index] : undefined;
-        if (!spawn)
+    /** Append a deferred built-in to the live tool list (append-only). */
+    promoteDeferredBuiltin(name) {
+        if (!this.deferredBuiltinToolNames.includes(name))
+            return undefined;
+        const live = this.tools.find((t) => t.name === name);
+        if (live)
+            return live;
+        const [tool] = this.mcp.promote([name]);
+        if (tool)
+            this.tools.push(tool);
+        return tool;
+    }
+    wrapToPromote(trigger, followUps, when = () => true) {
+        const index = this.tools.findIndex((t) => t.name === trigger);
+        const tool = index >= 0 ? this.tools[index] : undefined;
+        if (!tool)
             return;
         this.tools[index] = {
-            ...spawn,
+            ...tool,
             execute: async (args, context) => {
-                const result = await spawn.execute(args, context);
-                if (!this.tools.some((t) => t.name === "wait_agent")) {
-                    this.tools.push(...(this.mcpCatalog?.promote(["wait_agent"]) ?? []));
+                const result = await tool.execute(args, context);
+                if (when(args)) {
+                    const missing = followUps.filter((name) => !this.tools.some((t) => t.name === name));
+                    if (missing.length > 0)
+                        this.tools.push(...this.mcp.promote(missing));
                 }
                 return result;
             },
         };
     }
-    /** Append tools, replacing any same-named entry (cached stub → live tool). */
-    replaceOrPushTools(tools) {
-        for (const tool of tools) {
-            const index = this.tools.findIndex((t) => t.name === tool.name);
-            if (index >= 0)
-                this.tools[index] = tool;
-            else
-                this.tools.push(tool);
-        }
-    }
-    /** Swap already-promoted cached stubs for their live equivalents, in place. */
-    replaceLivePromotedTools(tools) {
-        for (const tool of tools) {
-            const index = this.tools.findIndex((t) => t.name === tool.name);
-            if (index >= 0)
-                this.tools[index] = tool;
-        }
-    }
     /**
      * Publish cached tool definitions into the deferred catalog so `tool_search`
-     * answers correctly on turn 1. A cached stub carries the real name, one-line
-     * description and input schema; calling it waits for the live connection and
-     * then dispatches against the real client, or returns a clear error when that
-     * server ultimately failed. Live tools replace stubs on connect.
+     * answers correctly on turn 1 (see {@link McpToolRegistry.seedFromCache}).
      */
     async seedMcpCatalogFromCache(servers) {
         if (!this.opts.backgroundMcpConnect)
             return;
         if (this.opts.allowedTools || !this.settingsManager.get("deferredMcpTools"))
             return;
-        let entries;
-        try {
-            entries = await this.mcpCatalogCache.entriesFor(servers);
-        }
-        catch {
-            return;
-        }
-        const stubs = [];
-        for (const [serverName, entry] of entries) {
-            for (const cached of entry.tools) {
-                if (this.liveMcpTools.has(cached.name))
-                    continue;
-                this.cachedMcpToolServers.set(cached.name, serverName);
-                stubs.push(this.buildCachedMcpTool(serverName, cached));
-            }
-        }
-        if (stubs.length === 0)
-            return;
-        log("INFO", "mcp", "Seeded deferred tool catalog from cache", {
-            tools: String(stubs.length),
-            servers: String(entries.size),
-        });
-        this.addCachedMcpTools(stubs);
-    }
-    /** Catalog-only registration for cached stubs — never marks them live. */
-    addCachedMcpTools(stubs) {
-        this.mcpCatalog ??= new DeferredToolCatalog(this.contextLimits);
-        this.mcpCatalog.add(stubs);
-        this.ensureToolSearchTool();
-    }
-    buildCachedMcpTool(serverName, cached) {
-        return {
-            name: cached.name,
-            description: cached.description,
-            parameters: z.record(z.string(), z.unknown()),
-            rawInputSchema: cached.rawInputSchema,
-            execute: async (args, context) => {
-                const live = this.liveMcpTools.get(cached.name);
-                if (live)
-                    return live.execute(args, context);
-                const outcome = (await this.mcpManager?.whenConnected(serverName)) ?? {
-                    ok: false,
-                    error: "MCP is disabled for this session",
-                };
-                if (!outcome.ok) {
-                    return (`MCP tool ${cached.name} is unavailable: server "${serverName}" did not connect ` +
-                        `(${outcome.error}). This tool was offered from a cached catalog. ` +
-                        `Use a different approach or ask the user to check their MCP configuration.`);
-                }
-                const connected = this.liveMcpTools.get(cached.name);
-                if (!connected) {
-                    return (`MCP tool ${cached.name} no longer exists: server "${serverName}" connected but ` +
-                        `does not expose it. The cached catalog entry was stale.`);
-                }
-                return connected.execute(args, context);
-            },
-        };
+        await this.mcp.seedFromCache(servers);
     }
     /**
      * Resolve a `/name [args]` input to the prompt template it expands into, or
@@ -1084,33 +914,15 @@ export class AgentSession {
     resetHookState(originalRequest) {
         this.opts.completionReview?.begin(originalRequest);
         this.lspManager?.clearPendingDiagnostics();
-        this.hookStats = { toolCalls: 0, toolFailures: 0, turns: 0 };
-        this.hookText = "";
-        this.hookConsecutiveFailures = 0;
-        this.hookRepeatedNoProgressCalls = 0;
-        this.hookProgressTracker.reset();
-        this.hookCycleDetector.reset();
-        this.hookCyclicPattern = null;
-        this.hookFileEditCounts.clear();
-        this.hookToolCalls.clear();
-        this.loopBreakInjected = 0;
+        this.loopMonitor.reset();
+        this.verificationTracker.resetRun();
         this.regroundingInjected = false;
-        this.hookRecentCalls = [];
-        this.semanticLoop = {
-            checksUsed: 0,
-            lastCheckTurn: 0,
-            pending: false,
-            verdict: null,
-            injected: false,
-        };
         this.runStartedAt = Date.now();
         this.processGateInjected = 0;
+        this.planSubmissionNudges = 0;
         this.verificationGate.beginRun();
         const processes = new Set(this.processManager?.list().map((p) => p.id) ?? []);
-        for (const id of this.backgroundVerification.keys()) {
-            if (!processes.has(id))
-                this.backgroundVerification.delete(id);
-        }
+        this.verificationTracker.pruneBackground(processes);
         this.compactionOccurred = false;
         // Post-turn compaction may have landed between runs — adopt its armed
         // signal so the re-grounding hook fires for this run exactly as it would
@@ -1134,153 +946,20 @@ export class AgentSession {
         }
         switch (event.type) {
             case "text_delta":
-                this.hookText += event.text;
+                this.loopMonitor.recordText(event.text);
                 break;
             case "tool_call_start": {
-                this.hookToolCalls.set(event.toolCallId, {
-                    name: event.name,
-                    args: event.args ?? {},
-                    revision: this.verificationGate.revision,
-                });
-                const startClassification = event.name === "bash" && typeof event.args?.command === "string"
-                    ? classifyVerificationCommand(event.args.command)
-                    : null;
-                if (startClassification &&
-                    typeof event.args?.command === "string" &&
-                    (isVerificationCommand(event.args.command) ||
-                        startClassification.accepted ||
-                        // Must match the tool_call_end predicate: a snapshot-eligible
-                        // command that never captured a "before" snapshot is misread at
-                        // the end as an uncomparable workspace and re-arms the gate.
-                        startClassification.snapshotEligible === true)) {
-                    // A check that can rewrite files (--fix, build scripts, emitters)
-                    // invalidates earlier in-flight evidence AND marks the run as
-                    // touched. A check that is merely UNRECOGNIZED (`make test`, `deno
-                    // test`) rewrites nothing we can point to: bumping the revision for
-                    // it poisoned the gate on green output and re-armed the hook into
-                    // every later question turn.
-                    this.verificationGate.recordVerificationAttempt();
-                    const classification = startClassification;
-                    if (classification.snapshotEligible && event.args.persist !== true) {
-                        const call = this.hookToolCalls.get(event.toolCallId);
-                        call.sourceSnapshot = await captureVerificationSnapshot(this.opts.cwd, [
-                            ...this.hookFileEditCounts.keys(),
-                        ]);
-                        if (call.sourceSnapshot === null)
-                            this.verificationGate.requireFreshVerification(true, event.args.command);
-                    }
-                    else if ((classification.accepted && event.args.persist !== true) ||
-                        (!classification.accepted && classification.mayMutate)) {
-                        // Flag the workspace unknown only when tool_call_end can resolve
-                        // it: a bounded check records pass/fail, a file-rewriting command
-                        // bumps the revision. An unrecognized read-only check (`biome ci`)
-                        // or a persistent-shell run records nothing at the end, so
-                        // flagging it left verified work Unverified forever — and
-                        // autopilot silently refused every later turn.
-                        this.verificationGate.requireFreshVerification(!classification.accepted && classification.mayMutate, event.args.command);
-                    }
+                if (await this.verificationTracker.recordToolCallStart(event)) {
                     await this.persistVerificationState();
                 }
                 break;
             }
             case "tool_call_end": {
-                const call = this.hookToolCalls.get(event.toolCallId);
+                const call = this.verificationTracker.getToolCall(event.toolCallId);
                 const name = call?.name ?? "";
                 const args = call?.args;
-                this.hookStats.toolCalls += 1;
-                if (event.isError)
-                    this.hookStats.toolFailures += 1;
-                this.hookConsecutiveFailures = event.isError ? this.hookConsecutiveFailures + 1 : 0;
-                this.hookRepeatedNoProgressCalls = this.hookProgressTracker.record(name, args, event.result, event.isError);
-                this.hookCyclicPattern = this.hookCycleDetector.record(name, args, event.result, event.isError);
-                // Semantic-loop judge input: a bounded digest of WHAT was attempted and
-                // HOW it came out. Args/results are sliced AT RECORD TIME — a write with
-                // a 50 KiB payload or a bash dump must never inflate the ring, and the
-                // judge needs shapes, not payloads.
-                this.hookRecentCalls.push({
-                    tool: name,
-                    args: args === undefined ? "" : JSON.stringify(args).slice(0, 300),
-                    ok: !event.isError,
-                    result: event.result.slice(0, 400),
-                });
-                if (this.hookRecentCalls.length > MAX_SEMANTIC_LOOP_CALLS) {
-                    this.hookRecentCalls.splice(0, this.hookRecentCalls.length - MAX_SEMANTIC_LOOP_CALLS);
-                }
-                // Only host-observed successful mutations and trustworthy check results
-                // affect approval. The model's text is never evidence.
-                let verificationChanged = false;
-                if (!event.isError && args) {
-                    if (name === "edit" || name === "write") {
-                        // Check-owning files (tsconfig.json, pytest.ini, vitest.config.ts …)
-                        // are tracked even when they are not source code: editing one is how
-                        // a red suite is turned green without fixing anything. A multi-file
-                        // edit records every file; its combined diff is scanned for each.
-                        const addedText = name === "write"
-                            ? String(args.content ?? "")
-                            : extractAddedLines(event.details?.diff ?? event.result);
-                        for (const filePath of editTargetPaths(args)) {
-                            if (isCodeFilePath(filePath) || isCheckOwnFile(filePath)) {
-                                this.verificationGate.recordMutation(filePath, addedText);
-                                verificationChanged = true;
-                            }
-                        }
-                    }
-                }
-                if (args && call && name === "bash") {
-                    const command = typeof args.command === "string" ? args.command : "";
-                    const classification = classifyVerificationCommand(command);
-                    if (classification.accepted || classification.snapshotEligible) {
-                        // A foreground check that outlived the default budget was moved to
-                        // the background, not failed: track it to its real exit the same way.
-                        const autoBackgroundId = event.isError ? undefined : autoBackgroundedId(event.result);
-                        if ((autoBackgroundId !== undefined || args.run_in_background === true) &&
-                            !event.isError &&
-                            args.persist !== true) {
-                            const id = autoBackgroundId ?? /^ID:\s*(\S+)/m.exec(event.result)?.[1];
-                            // No parseable ID means the check cannot be tracked to a real exit
-                            // code — no evidence either way. Recording a FAILURE here made
-                            // every later green run of a different spelling look owed.
-                            if (id)
-                                this.backgroundVerification.set(id, {
-                                    revision: call.revision,
-                                    command,
-                                    ...(classification.snapshotEligible
-                                        ? { sourceSnapshot: call.sourceSnapshot ?? null }
-                                        : {}),
-                                });
-                            else if (classification.snapshotEligible)
-                                this.verificationGate.requireFreshVerification(true, command);
-                        }
-                        else if (args.persist === true) {
-                            // Persistent-shell checks are not bounded evidence (steering can
-                            // interleave): neither a pass nor a failure. A recorded failure
-                            // here blocked approval for sessions that prefer the shell.
-                        }
-                        else if (classification.snapshotEligible) {
-                            await this.finishSnapshotVerification({ command, revision: call.revision, sourceSnapshot: call.sourceSnapshot ?? null }, !event.isError && /^Exit code:\s*0(?:\s|$)/i.test(event.result.trim()));
-                            verificationChanged = true;
-                        }
-                        else {
-                            if (!event.isError && /^Exit code:\s*0(?:\s|$)/i.test(event.result.trim())) {
-                                this.verificationGate.recordVerification(call.revision, command);
-                            }
-                            else {
-                                this.verificationGate.recordFailedVerification(command, call.revision);
-                            }
-                            verificationChanged = true;
-                        }
-                        delete call.sourceSnapshot;
-                    }
-                    else if (classification.candidate) {
-                        // Green but untrusted: remember WHY so the demand can tell the
-                        // agent which command shape actually clears the gate.
-                        this.verificationGate.recordRejectedCheck(command, classification.reason);
-                    }
-                }
-                if (!event.isError && args && name === "task_output" && typeof args.id === "string") {
-                    verificationChanged =
-                        (await this.recordFinishedBackgroundVerification(args.id)) || verificationChanged;
-                }
+                this.loopMonitor.recordToolEnd(name, args, event.result, event.isError);
+                const verificationChanged = await this.verificationTracker.recordToolCallEnd(event, call, this.planModeRef.current);
                 if (verificationChanged)
                     await this.persistVerificationState();
                 // Tool results are what push the run over the review gate, and they all
@@ -1290,7 +969,7 @@ export class AgentSession {
                 break;
             }
             case "turn_end":
-                this.hookStats.turns = event.turn;
+                this.loopMonitor.recordTurn(event.turn);
                 this.refreshHookArming();
                 for (let index = this.messages.length - 1; index >= 0; index--) {
                     const anchor = this.messages[index];
@@ -1467,51 +1146,26 @@ export class AgentSession {
         // Deterministic stuck verdict, computed once and shared: the semantic
         // judge must not spend tokens on a burst the deterministic breaker is
         // about to correct itself.
-        const deterministicDecision = evaluateLoopBreak({
-            consecutiveFailures: this.hookConsecutiveFailures,
-            repeatedNoProgressCalls: this.hookRepeatedNoProgressCalls,
-            textRepetitionDetected: detectTextRepetition(this.hookText),
-            ...(this.hookCyclicPattern ? { cyclicPattern: this.hookCyclicPattern } : {}),
-        });
+        const deterministicDecision = this.loopMonitor.evaluateLoopBreak();
         this.maybeStartSemanticLoopCheck(deterministicDecision.shouldBreak);
         // Two-stage loop-breaker: stage 1 nudges; a FRESH detection after that
         // injects the harsher final stop-and-report prompt. Signals reset after
         // each injection so stage 2 only fires on new evidence.
-        if (this.loopBreakInjected < 2) {
-            const decision = deterministicDecision;
-            if (decision.shouldBreak) {
-                const stage = this.loopBreakInjected === 0 ? 1 : 2;
-                this.loopBreakInjected = stage;
-                this.hookProgressTracker.reset();
-                this.hookCycleDetector.reset();
-                this.hookCyclicPattern = null;
-                this.hookConsecutiveFailures = 0;
-                this.hookRepeatedNoProgressCalls = 0;
-                // The deterministic breaker owns this burst — a semantic verdict from
-                // the same burst must not double-correct on the next poll.
-                this.semanticLoop.verdict = null;
-                // Clear the text buffer too — otherwise a stage-1 text-repetition
-                // trigger still sees the same repeated tail on the next check and
-                // escalates to stage 2 on stale evidence.
-                this.hookText = "";
-                log("INFO", "loop-break", "Injecting loop-break nudge", {
-                    stage: String(stage),
-                    reasons: decision.reasons.join(", "),
-                });
-                this.eventBus.emit("hook", { kind: "loop_break" });
-                return [buildLoopBreakMessage(decision.reasons, stage === 2)];
-            }
+        const stage = this.loopMonitor.takeLoopBreakStage(deterministicDecision);
+        if (stage !== null) {
+            log("INFO", "loop-break", "Injecting loop-break nudge", {
+                stage: String(stage),
+                reasons: deterministicDecision.reasons.join(", "),
+            });
+            this.eventBus.emit("hook", { kind: "loop_break" });
+            return [buildLoopBreakMessage(deterministicDecision.reasons, stage === 2)];
         }
         // Semantic loop-break: an LLM verdict (started by maybeStartSemanticLoopCheck
         // on a suspicious-but-syntactically-quiet burst) is consumed here, exactly
         // once, with the deterministic breaker getting priority above. Fail-open:
         // no verdict or no-loop verdict injects nothing.
-        if (this.semanticLoop.verdict && !this.semanticLoop.injected) {
-            const verdict = this.semanticLoop.verdict;
-            this.semanticLoop.injected = true;
-            this.semanticLoop.verdict = null;
-            // The judged burst has been addressed; a fresh burst must re-accumulate.
-            this.hookConsecutiveFailures = 0;
+        const verdict = this.loopMonitor.takeSemanticVerdict();
+        if (verdict) {
             log("INFO", "loop-break", "Injecting semantic loop-break steering", {
                 reason: verdict.reason,
             });
@@ -1531,34 +1185,26 @@ export class AgentSession {
      *  Fire-and-forget: the call runs while the next turn streams, and a finished
      *  verdict is consumed by the NEXT steering poll — never blocking a turn. */
     maybeStartSemanticLoopCheck(deterministicBreak) {
-        if (!shouldRunSemanticLoopCheck({
-            consecutiveFailures: this.hookConsecutiveFailures,
-            totalFailures: this.hookStats.toolFailures,
-            turns: this.hookStats.turns,
-            lastCheckTurn: this.semanticLoop.lastCheckTurn,
-            checksUsed: this.semanticLoop.checksUsed,
-            checkPending: this.semanticLoop.pending,
-            deterministicBreak,
-        })) {
+        const monitor = this.loopMonitor;
+        if (!monitor.shouldRunSemanticCheck(deterministicBreak)) {
             return;
         }
-        // resetHookState replaces this object on every prompt. A late judge must
+        // resetHookState replaces the run state on every prompt. A late judge must
         // not publish a verdict or consume the next run's budget/cooldown.
-        const runState = this.semanticLoop;
-        runState.pending = true;
+        const runState = monitor.beginSemanticCheck();
         log("INFO", "loop-break", "Starting semantic loop judge", {
-            turn: String(this.hookStats.turns),
-            consecutiveFailures: String(this.hookConsecutiveFailures),
-            recentCalls: String(this.hookRecentCalls.length),
+            turn: String(monitor.stats.turns),
+            consecutiveFailures: String(monitor.consecutiveFailures),
+            recentCalls: String(monitor.recentCalls.length),
         });
         void (async () => {
             try {
-                const prompt = buildSemanticLoopJudgePrompt(this.hookRecentCalls, this.originalRequest);
+                const prompt = buildSemanticLoopJudgePrompt(monitor.recentCalls, this.originalRequest);
                 const raw = await (this.opts.semanticLoopJudge?.(prompt) ??
                     this.callSemanticLoopJudge(prompt));
                 const verdict = parseSemanticLoopVerdict(raw);
-                if (this.semanticLoop === runState && verdict?.loop)
-                    runState.verdict = verdict;
+                if (verdict?.loop)
+                    monitor.publishSemanticVerdict(runState, verdict);
             }
             catch (error) {
                 // Fail open: judge errors never stop a run. Budget and cooldown are
@@ -1568,11 +1214,7 @@ export class AgentSession {
                 });
             }
             finally {
-                if (this.semanticLoop === runState) {
-                    runState.pending = false;
-                    runState.checksUsed += 1;
-                    runState.lastCheckTurn = this.hookStats.turns;
-                }
+                monitor.settleSemanticCheck(runState);
             }
         })();
     }
@@ -1668,23 +1310,7 @@ export class AgentSession {
      * with — so reuse the same stuck signals that drive the loop-breaker.
      */
     shouldExtendTurnBudget(ctx) {
-        const refusals = [];
-        const stuck = evaluateLoopBreak({
-            consecutiveFailures: this.hookConsecutiveFailures,
-            repeatedNoProgressCalls: this.hookRepeatedNoProgressCalls,
-            textRepetitionDetected: detectTextRepetition(this.hookText),
-            ...(this.hookCyclicPattern ? { cyclicPattern: this.hookCyclicPattern } : {}),
-        });
-        if (stuck.shouldBreak)
-            refusals.push(...stuck.reasons);
-        // Stage 2 means the loop-breaker already detected spinning twice and told
-        // the agent to stop and report. Do not overrule that with more turns.
-        if (this.loopBreakInjected >= 2)
-            refusals.push("loop-breaker already escalated");
-        const { toolCalls, toolFailures } = this.hookStats;
-        if (toolCalls > 0 && toolFailures / toolCalls > TURN_EXTENSION_MAX_FAILURE_RATIO) {
-            refusals.push(`${toolFailures}/${toolCalls} tool calls failed`);
-        }
+        const refusals = this.loopMonitor.turnExtensionRefusals();
         const granted = refusals.length === 0;
         log("INFO", "turn-budget", granted ? "Extending turn budget" : "Refusing turn-budget extension", {
             turn: String(ctx.turn),
@@ -1737,11 +1363,7 @@ export class AgentSession {
     async getHookFollowUpMessages() {
         // Exit notifications and task_output refer to the same host process record.
         // Do not force an extra polling tool/turn merely to acknowledge a known exit.
-        let backgroundChanged = false;
-        for (const id of this.backgroundVerification.keys()) {
-            backgroundChanged =
-                (await this.recordFinishedBackgroundVerification(id)) || backgroundChanged;
-        }
+        const backgroundChanged = await this.verificationTracker.settleFinishedBackground();
         if (backgroundChanged)
             await this.persistVerificationState();
         // Edits return immediately; only the completion boundary waits for remaining
@@ -1817,6 +1439,22 @@ export class AgentSession {
         // verification demand above instead of manufacturing a separate hook.
         if (diagnosticMessages.length > 0)
             return diagnosticMessages;
+        if (shouldNudgePlanSubmission({
+            enabled: this.opts.planSubmissionGate === true,
+            planMode: this.planModeRef.current,
+            aborted: this.opts.signal?.aborted === true,
+            nudgesThisRun: this.planSubmissionNudges,
+        })) {
+            this.planSubmissionNudges += 1;
+            log("INFO", "plan-gate", "Run stopping in plan mode without a submitted plan; reminding");
+            return [
+                {
+                    role: "user",
+                    content: buildNotificationSteeringText([PLAN_SUBMISSION_NUDGE]),
+                    provenance: { source: "runtime", kind: "notification", visibility: "hidden" },
+                },
+            ];
+        }
         if (this.opts.completionReview) {
             const followUp = await this.opts.completionReview.followUp((request, signal) => this.callCompletionReviewer(request, signal), this.opts.signal);
             await this.persistCompletionReviewState();
@@ -2043,6 +1681,11 @@ export class AgentSession {
                 maxTurnToolResultChars: resolveSessionTurnToolResultCharLimit(this.model, this.provider, accountId),
                 // Warn when web/MCP output contains instruction-like text (see injection-detect.ts).
                 transformToolResult: flagUntrustedToolResult,
+                // A deferred built-in called by its advertised name runs directly
+                // instead of costing a turn on "Unknown tool" then tool_search.
+                ...(options.disableTools
+                    ? {}
+                    : { resolveTool: (name) => this.promoteDeferredBuiltin(name) }),
                 // Self-correction hooks (same as the TUI): loop-break + re-grounding are
                 // polled mid-loop; the ideal review is polled when the agent would stop.
                 getSteeringMessages: () => this.getHookSteeringMessages(),
@@ -2376,11 +2019,12 @@ export class AgentSession {
             // there avoids tearing down a live stdio child and
             // gambling on a `npx` re-spawn that could fail and drop the tools.
             const glmInvolved = this.provider === "glm" || prevProvider === "glm";
-            if (this.mcpManager && glmInvolved) {
+            const mcpManager = this.mcp.manager;
+            if (mcpManager && glmInvolved) {
                 // Remove old MCP tools
                 this.tools = this.tools.filter((t) => !t.name.startsWith("mcp__"));
                 // Disconnect old MCP servers
-                await this.mcpManager.dispose();
+                await mcpManager.dispose();
                 // Connect new MCP servers for the new provider
                 try {
                     let apiKey;
@@ -2397,13 +2041,11 @@ export class AgentSession {
                     const servers = await getAllMcpServers(this.provider, apiKey, this.cwd, {
                         allowProjectScope: this.settingsManager.isProjectTrusted(this.cwd),
                     });
-                    const mcpTools = await this.mcpManager.connectAll(servers);
+                    const mcpTools = await 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.
                     this.tools = this.tools.filter((t) => !t.name.startsWith("mcp__"));
-                    this.mcpCatalog?.removeWhere((name) => name.startsWith("mcp__"));
-                    this.liveMcpTools.clear();
-                    this.cachedMcpToolServers.clear();
+                    this.mcp.clearMcpTools();
                     this.addMcpTools(mcpTools);
                 }
                 catch (err) {
@@ -2446,10 +2088,7 @@ export class AgentSession {
         this.checkpointGeneration = loaded.header.generation ?? 0;
         this.currentLeafId = loaded.header.leafId;
         this.setSessionPath(loaded.path);
-        this.nolanTurns = this.sessionManager.getNolanTurns(loaded.entries, loaded.header.leafId);
-        this.autopilotMarkers = this.sessionManager.getAutopilotMarkers(loaded.entries, loaded.header.leafId);
-        this.appMarkers = this.sessionManager.getAppMarkers(loaded.entries, loaded.header.leafId);
-        this.turnMetrics = this.sessionManager.getTurnMetrics(loaded.entries);
+        this.markers.restore(loaded.entries, loaded.header.leafId);
         this.lastPersistedIndex = this.messages.length;
         this.providerContext = null;
         await this.subAgentManager?.rebindParentSession(this.sessionId);
@@ -2489,10 +2128,7 @@ export class AgentSession {
                 await this.persistMessage(message);
         }
         this.lastPersistedIndex = this.messages.length;
-        await this.rePersistTurnMetrics();
-        await this.rePersistNolanTurns();
-        await this.rePersistAutopilotMarkers();
-        await this.rePersistAppMarkers();
+        await this.markers.rePersistAll();
         await this.persistVerificationState();
         await this.persistAppMarker("compaction", {
             originalCount: result.originalCount,
@@ -2851,12 +2487,17 @@ export class AgentSession {
         });
     }
     async newSession(preserveConversation = false) {
+        // A background post-turn compaction replaces `this.messages` when it
+        // lands. Letting it finish after the reset would swap the old history back
+        // into the fresh session (e.g. an accepted plan's build would inherit the
+        // whole planning conversation and lose the approved-plan prompt).
+        await this.settlePostTurnCompaction();
         this.cacheDiagnostics.reset();
         // Approved-plan execution is a clean checkpoint of the same conversation;
         // explicit new sessions reset the conversation identity.
         if (!preserveConversation) {
             this.verificationGate.reset();
-            this.backgroundVerification.clear();
+            this.verificationTracker.clearBackground();
             this.conversationId = "";
             this.checkpointGeneration = 0;
             this.sessionPreview = "";
@@ -2868,10 +2509,7 @@ export class AgentSession {
         // turns / autopilot verdicts / app markers linger in memory, show up in the
         // new session's /history, and get re-persisted into the new file by the
         // next compaction — the cross-session duplicate-marker propagation bug.
-        this.nolanTurns = [];
-        this.autopilotMarkers = [];
-        this.appMarkers = [];
-        this.turnMetrics = [];
+        this.markers.clear();
         const basePrompt = await this.buildBasePrompt(false, undefined);
         this.baseSystemPrompt = basePrompt;
         this.messages = [{ role: "system", content: this.withSystemPromptTail(basePrompt) }];
@@ -2993,9 +2631,7 @@ export class AgentSession {
         else {
             used = calculateActiveContextTokens(this.messages);
         }
-        const costUsd = this.turnMetrics.length > 0 && this.turnMetrics.every((m) => m.cost.status === "known")
-            ? this.turnMetrics.reduce((sum, m) => sum + (m.cost.status === "known" ? m.cost.usd : 0), 0)
-            : undefined;
+        const costUsd = this.markers.knownCostUsd();
         return costUsd === undefined ? { used, size } : { used, size, costUsd };
     }
     /**
@@ -3119,6 +2755,11 @@ export class AgentSession {
      */
     async setPlanMode(active) {
         this.planModeRef.current = active;
+        // Plan mode always ends with `exit_plan`; a deferred one must be callable
+        // without a tool_search turn. Append-only, like any promotion.
+        if (active && !this.tools.some((t) => t.name === "exit_plan")) {
+            this.tools.push(...this.mcp.promote(["exit_plan"]));
+        }
         // Entering plan mode discards any prior approved-plan contract (a new plan
         // is about to be drafted); exiting keeps it (set explicitly via accept).
         if (active)
@@ -3322,7 +2963,10 @@ export class AgentSession {
     orchestrationPolicyTail() {
         if (this.opts.orchestrationPrompt === false)
             return "";
-        return applyAsyncSubagentPolicy("", this.provider, this.model, this.thinkingLevel, this.tools.map((tool) => tool.name)).trim();
+        return applyAsyncSubagentPolicy("", this.provider, this.model, this.thinkingLevel, 
+        // Deferred spawn_agent/wait_agent are one call away (resolveTool loads
+        // them on first use), so the policy must still see them.
+        [...this.tools.map((tool) => tool.name), ...this.deferredBuiltinToolNames]).trim();
     }
     /**
      * Re-render the uncached tail of messages[0] in place. The cached prefix is
@@ -3344,12 +2988,7 @@ export class AgentSession {
         return this.messages;
     }
     getTurnMetrics() {
-        return this.turnMetrics.map((metric) => ({
-            ...metric,
-            usage: { ...metric.usage },
-            timing: { ...metric.timing },
-            cost: { ...metric.cost },
-        }));
+        return this.markers.getTurnMetrics();
     }
     async persistTurnMetric(event) {
         if (event.stopReason === "error")
@@ -3376,31 +3015,23 @@ export class AgentSession {
                 reason: "No authoritative effective-dated provider pricing is available",
             },
         };
-        this.turnMetrics.push(payload);
+        this.markers.addTurnMetric(payload);
         // Internal diagnostics piggyback on the authoritative per-turn metric —
         // one source of truth, and the record flushes to disk every turn.
         this.diagnosticsRecorder?.recordTurnMetric(payload);
-        if (this.sessionPath)
-            await this.sessionManager.appendTurnMetric(this.sessionPath, payload);
-    }
-    async rePersistTurnMetrics() {
-        if (!this.sessionPath)
-            return;
-        for (const metric of this.turnMetrics) {
-            await this.sessionManager.appendTurnMetric(this.sessionPath, metric);
-        }
+        await this.markers.persistTurnMetric(payload);
     }
     /** Nolan Grout (mentor) turns recorded against this session, in record order. Used
      *  by the host to interleave Nolan's advisory exchanges back into the transcript
      *  on resume. Never part of the LLM message history. */
     getNolanTurns() {
-        return this.nolanTurns;
+        return this.markers.getNolanTurns();
     }
     /** Autopilot verdict markers recorded against this session, in record order.
      *  Used by the host to interleave the auto-review loop's markers back into
      *  the transcript on resume, mirroring `getNolanTurns`. */
     getAutopilotMarkers() {
-        return this.autopilotMarkers;
+        return this.markers.getAutopilotMarkers();
     }
     /** Non-system messages that are actually on disk. Transcript markers anchor
      *  against this (not the in-memory list, which can run ahead after a failed
@@ -3415,15 +3046,7 @@ export class AgentSession {
      * file, so the new file carries positions that match its own transcript.
      */
     remapMarkerAnchors(remap) {
-        if (!remap)
-            return;
-        const move = (payload) => ({
-            ...payload,
-            afterMessageCount: remapAnchorForCompaction(payload.afterMessageCount, remap),
-        });
-        this.nolanTurns = this.nolanTurns.map(move);
-        this.autopilotMarkers = this.autopilotMarkers.map(move);
-        this.appMarkers = this.appMarkers.map(move);
+        this.markers.remapAnchors(remap);
     }
     /**
      * Record one Nolan Grout (mentor agent) turn against this build session: the
@@ -3436,39 +3059,7 @@ export class AgentSession {
      * appendEntry's own handling.
      */
     async persistNolanTurn(question, reply) {
-        const afterMessageCount = this.persistedTranscriptCount();
-        const payload = { version: 1, question, reply, afterMessageCount };
-        this.nolanTurns.push(payload);
-        if (!this.sessionPath)
-            return;
-        const entry = {
-            type: "custom",
-            kind: NOLAN_TURN_CUSTOM_KIND,
-            id: crypto.randomUUID(),
-            parentId: null,
-            timestamp: new Date().toISOString(),
-            data: payload,
-        };
-        await this.sessionManager.appendEntry(this.sessionPath, entry);
-    }
-    /** Re-append the in-memory Nolan turns to the current session file. Called after
-     *  a continuation/compaction file is created so Nolan's advisory history isn't
-     *  lost when the session is rewritten (those rewrites only re-persist
-     *  messages). Each turn keeps its original `afterMessageCount` anchor. */
-    async rePersistNolanTurns() {
-        if (!this.sessionPath)
-            return;
-        for (const payload of this.nolanTurns) {
-            const entry = {
-                type: "custom",
-                kind: NOLAN_TURN_CUSTOM_KIND,
-                id: crypto.randomUUID(),
-                parentId: null,
-                timestamp: new Date().toISOString(),
-                data: stripRecordedPosition(payload),
-            };
-            await this.sessionManager.appendEntry(this.sessionPath, entry);
-        }
+        await this.markers.recordNolanTurn(question, reply, this.persistedTranscriptCount());
     }
     /**
      * Record one autopilot verdict marker (prompted / done / human / capped)
@@ -3478,23 +3069,6 @@ export class AgentSession {
      * instead of dropping the marker or falling back to a raw verdict string.
      * No-op persistence for transient sessions (kept in memory only).
      */
-    async recordFinishedBackgroundVerification(id) {
-        const started = this.backgroundVerification.get(id);
-        const proc = this.processManager?.list().find((entry) => entry.id === id);
-        if (!started || !proc || proc.exitCode === null)
-            return false;
-        if (started.sourceSnapshot !== undefined) {
-            await this.finishSnapshotVerification(started, proc.exitCode === 0);
-        }
-        else if (proc.exitCode === 0) {
-            this.verificationGate.recordVerification(started.revision, started.command);
-        }
-        else {
-            this.verificationGate.recordFailedVerification(started.command, started.revision);
-        }
-        this.backgroundVerification.delete(id);
-        return true;
-    }
     getVerificationEvidence() {
         return this.verificationGate.evidence();
     }
@@ -3506,39 +3080,8 @@ export class AgentSession {
             evidence: this.verificationGate.evidence("run"),
         };
     }
-    async finishSnapshotVerification(check, passed) {
-        const after = check.sourceSnapshot
-            ? await captureVerificationSnapshot(this.opts.cwd, [...this.hookFileEditCounts.keys()])
-            : null;
-        if (after === null || after !== check.sourceSnapshot) {
-            this.verificationGate.requireFreshVerification(true, check.command);
-            this.verificationGate.recordRejectedCheck(check.command, after === null
-                ? "Workspace inputs could not be compared; run a read-only check after the command"
-                : "Command changed workspace inputs; run checks against the changed source");
-            if (!passed)
-                this.verificationGate.recordFailedVerification(check.command);
-        }
-        else if (passed) {
-            const classification = classifyVerificationCommand(check.command);
-            if (classification.snapshotPreserveOnly) {
-                this.verificationGate.recordRejectedCheck(check.command, classification.reason);
-            }
-            else {
-                this.verificationGate.recordVerification(check.revision, check.command);
-            }
-        }
-        else {
-            this.verificationGate.recordFailedVerification(check.command, check.revision);
-        }
-    }
     getVerificationProblem() {
-        if ([...this.hookToolCalls.values()].some((call) => call.sourceSnapshot !== undefined)) {
-            return "Unverified: a build is still running or its workspace comparison is pending.";
-        }
-        return (this.verificationGate.verificationProblem() ??
-            (this.backgroundVerification.size > 0
-                ? "Unverified: a background check is still running or its result has not been confirmed."
-                : null));
+        return this.verificationTracker.verificationProblem();
     }
     async persistCompletionReviewState() {
         if (!this.sessionPath || !this.opts.completionReview)
@@ -3571,50 +3114,13 @@ export class AgentSession {
         await this.sessionManager.appendEntry(this.sessionPath, entry);
     }
     async persistAutopilotMarker(phase, extra) {
-        const afterMessageCount = this.persistedTranscriptCount();
-        const payload = {
-            version: 1,
-            phase,
-            afterMessageCount,
-            ...(extra?.reason !== undefined ? { reason: extra.reason } : {}),
-            ...(extra?.body !== undefined ? { body: extra.body } : {}),
-        };
-        this.autopilotMarkers.push(payload);
-        if (!this.sessionPath)
-            return;
-        const entry = {
-            type: "custom",
-            kind: AUTOPILOT_MARKER_CUSTOM_KIND,
-            id: crypto.randomUUID(),
-            parentId: null,
-            timestamp: new Date().toISOString(),
-            data: payload,
-        };
-        await this.sessionManager.appendEntry(this.sessionPath, entry);
-    }
-    /** Re-append the in-memory autopilot markers to the current session file.
-     *  Mirrors `rePersistNolanTurns` — called after a continuation/compaction file
-     *  is created so the auto-review history survives the rewrite. */
-    async rePersistAutopilotMarkers() {
-        if (!this.sessionPath)
-            return;
-        for (const payload of this.autopilotMarkers) {
-            const entry = {
-                type: "custom",
-                kind: AUTOPILOT_MARKER_CUSTOM_KIND,
-                id: crypto.randomUUID(),
-                parentId: null,
-                timestamp: new Date().toISOString(),
-                data: stripRecordedPosition(payload),
-            };
-            await this.sessionManager.appendEntry(this.sessionPath, entry);
-        }
+        await this.markers.recordAutopilotMarker(phase, extra, this.persistedTranscriptCount());
     }
     /** App transcript markers recorded against this session, in record order.
      *  Used by the host to interleave display-only rows (plan banner, task
      *  header, errors, user-bubble hints) back into the transcript on resume. */
     getAppMarkers() {
-        return this.appMarkers;
+        return this.markers.getAppMarkers();
     }
     /**
      * Record one app transcript marker (display-only row) against this session.
@@ -3626,20 +3132,7 @@ export class AgentSession {
      * No-op persistence for transient sessions.
      */
     async persistAppMarker(kind, data, anchorOffset = 0) {
-        const afterMessageCount = this.persistedTranscriptCount() + anchorOffset;
-        const payload = { version: 1, kind, afterMessageCount, data };
-        this.appMarkers.push(payload);
-        if (!this.sessionPath)
-            return;
-        const entry = {
-            type: "custom",
-            kind: APP_MARKER_CUSTOM_KIND,
-            id: crypto.randomUUID(),
-            parentId: null,
-            timestamp: new Date().toISOString(),
-            data: payload,
-        };
-        await this.sessionManager.appendEntry(this.sessionPath, entry);
+        await this.markers.recordAppMarker(kind, data, this.persistedTranscriptCount() + anchorOffset);
     }
     /**
      * Open the run journal for one `RunLifecycle` generation.
@@ -3668,24 +3161,6 @@ export class AgentSession {
             outcome,
         });
     }
-    /** Re-append the in-memory app markers to the current session file. Mirrors
-     *  `rePersistNolanTurns` — called after a continuation/compaction file is
-     *  created so display-only rows survive the rewrite. */
-    async rePersistAppMarkers() {
-        if (!this.sessionPath)
-            return;
-        for (const payload of this.appMarkers) {
-            const entry = {
-                type: "custom",
-                kind: APP_MARKER_CUSTOM_KIND,
-                id: crypto.randomUUID(),
-                parentId: null,
-                timestamp: new Date().toISOString(),
-                data: stripRecordedPosition(payload),
-            };
-            await this.sessionManager.appendEntry(this.sessionPath, entry);
-        }
-    }
     /**
      * Rewrite a draft prompt into a tighter, terminology-correct version using
      * the ACTIVE provider/model. A stateless one-off LLM call (no agent loop, no
@@ -3927,7 +3402,7 @@ export class AgentSession {
         this.stopBackgroundProcesses();
         this.lspManager?.shutdownAll();
         this.debugManager?.shutdown();
-        await Promise.all([this.subAgentManager?.shutdownAll(), this.mcpManager?.dispose()]);
+        await Promise.all([this.subAgentManager?.shutdownAll(), this.mcp.manager?.dispose()]);
         await this.extensionLoader.deactivateAll();
         this.setSessionPath("");
         this.eventBus.removeAllListeners();
@@ -3972,7 +3447,7 @@ export class AgentSession {
             .reverse()
             .find((entry) => entry.type === "custom" && entry.kind === COMPLETION_REVIEW_STATE_KIND);
         this.opts.completionReview?.restore(savedCompletionReview?.type === "custom" ? savedCompletionReview.data : null);
-        this.backgroundVerification.clear();
+        this.verificationTracker.clearBackground();
         const savedVerification = [...loaded.entries]
             .reverse()
             .find((entry) => entry.type === "custom" && entry.kind === VERIFICATION_STATE_KIND);
@@ -4002,12 +3477,8 @@ export class AgentSession {
         // Restore Nolan's advisory turns (custom entries, not on the message branch) so
         // they reappear in the transcript and survive into the continuation file.
         // The leaf lets marker replay retain its independent file-order position.
-        this.nolanTurns = this.sessionManager.getNolanTurns(loaded.entries, loaded.header.leafId);
-        // Restore autopilot verdict markers the same way (not on the message DAG).
-        this.autopilotMarkers = this.sessionManager.getAutopilotMarkers(loaded.entries, loaded.header.leafId);
-        // Restore app transcript markers (plan banner / task header / errors / hints).
-        this.appMarkers = this.sessionManager.getAppMarkers(loaded.entries, loaded.header.leafId);
-        this.turnMetrics = this.sessionManager.getTurnMetrics(loaded.entries);
+        // Autopilot verdicts, app markers and turn metrics are restored the same way.
+        this.markers.restore(loaded.entries, loaded.header.leafId);
         // A run that opened the journal and never closed it died mid-flight. Read
         // it here, before anything rewrites the file, and report it once the
         // transcript is in place.
@@ -4207,13 +3678,4 @@ export class AgentSession {
         }
     }
 }
-/** Expand a leading `~` so `/import ~/.codex/...` works from any shell. */
-function resolveHomePath(filePath) {
-    if (filePath === "~")
-        return os.homedir();
-    if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
-        return path.join(os.homedir(), filePath.slice(2));
-    }
-    return filePath;
-}
 //# sourceMappingURL=agent-session.js.map