@zergai/ztc 0.5.0-beta.1 → 0.6.0-beta.1

package/dist/agent/agent.js

@@ -5,10 +5,11 @@ import { existsSync, readFileSync, realpathSync } from 'fs';
 import { extname, resolve } from 'path';
 import { formatTaskHandoffContext, parseTaskHandoffProjection } from '../session_handoff_contract.js';
 import { createBackendForProvider } from './backends/index.js';
+import { RequestRefusedError } from './backends/types.js';
 import { mergeTokenUsage } from './backends/token_usage.js';
 import { createUsageSnapshot, mergeUsageSnapshots, parseUsageSnapshot, recordUsageReceipt } from '../usage_snapshot.js';
-import { isTransportCodeError, isTransportMessageError } from './backends/transport_errors.js';
-import { retryAfterDelayMs } from './backends/http_error.js';
+import { IncompleteStreamError, isIncompleteStreamError, isTransportCodeError, isTransportMessageError } from './backends/transport_errors.js';
+import { BackendHttpError, redactErrorText, retryAfterDelayMs } from './backends/http_error.js';
 import { inferDefaultProvider, getDefaultApiKeyForProvider, getDefaultModelForProvider } from '../config/defaults.js';
 import { apiRetryDelayMs, resolveApiRetrySettings } from '../config/api_retry.js';
 import { resolveExecutionSettings } from '../config/execution.js';
@@ -25,7 +26,10 @@ import { defaultTools as baseDefaultTools } from './tools/registry.js';
 import { toolSearchTool } from './tools/tool_search.js';
 import { recallToolResponseTool } from './tools/recall_tool_response.js';
 import { adaptationRunTool } from './tools/adaptation.js';
+import { ToolGroupRuntime } from './tools/tool_groups.js';
+import { isCodexAppServerProvider } from './backends/provider_ids.js';
 import { getRequestToolDefinitions } from './tools/deferred.js';
+import { isToolResultMessage } from '../utils/tool_result_message.js';
 import { getLatestTodos } from './tools/todo.js';
 import { ToolResponseStore, ToolResponseIntegrityError, describeOffloadPlaceholderFormat } from './tool_response_store.js';
 import { formatEvidenceContext } from './runtime/evidence.js';
@@ -34,15 +38,24 @@ import { projectCurrentVerification } from './runtime/source_verification.js';
 import { sessionEvidenceTool } from './tools/session_evidence.js';
 import { MEASUREMENT_EVIDENCE_GUIDANCE } from './measurement_guidance.js';
 import { RequestEncoder, STABLE_RESULT_LIMIT, nativeHistoryContextId } from './request_encoder.js';
+import { presentToolResult } from './tool_result_presentation.js';
+import { BackgroundWorkers, formatWorkerReports } from './background_workers.js';
 import { parseImageToolResult } from './tool_result_parsing.js';
-import { createRepeatGuard, pinnedTaskSystem } from './loop_policy.js';
+import { completionCheckDue, createRepeatGuard, needsCompletionCheck, pinnedTaskSystem } from './loop_policy.js';
 import { extractSourcePath } from './tool_compression.js';
 import { executeToolWithRuntime } from './runtime/tool_runtime.js';
 import { createToolProgressAccumulator } from './runtime/tool_progress.js';
 import { ToolCapability } from './runtime/capabilities.js';
 import { buildUserSubprocessEnv } from '../utils/subprocess_env.js';
-import { resolvePromptPrefixId } from '../utils/compaction.js';
-import { INCOMPLETE_MODEL_RESPONSE_CODE, incompleteModelResponseMessage, isIncompleteModelResponse, } from './completion_state.js';
+import { projectHandoffHistory, resolvePromptPrefixId } from '../utils/compaction.js';
+import { estimateConversationTokens, getContextWindowSize } from '../utils/context.js';
+import { shouldCompactMidTurn } from '../utils/mid_turn_compaction.js';
+import { clampCompletionTokens } from '../utils/deepseek.js';
+import { resolveToolEffect } from './runtime/tool_effects.js';
+import { INCOMPLETE_MODEL_RESPONSE_CODE, INCOMPLETE_MODEL_RESPONSE_MESSAGE, incompleteModelResponseMessage, isIncompleteModelResponse, isOutputLimitStop, OUTPUT_LIMIT_RETRY_NOTE, outputLimitRetryEffort, repeatedRunawayMessage, RUNAWAY_OUTPUT_CODE, RUNAWAY_OUTPUT_RETRY_NOTE, } from './completion_state.js';
+import { guardRunawayOutput, RunawayOutputError } from './runaway_output.js';
+import { isEphemeralToolCall } from '../utils/ephemeral_tools.js';
+import { canReadCopies, COPY_ADVICE, resultCopyNote, saveCopy } from '../utils/tool_output_copies.js';
 import { remoteDeletionReport, NO_VERIFIED_DELETION_REPORT } from './runtime/remote_deletion_receipts.js';
 const defaultTools = [
     ...baseDefaultTools,
@@ -87,6 +100,16 @@ export function isContextOverflowMessage(message) {
     const haystack = message.toLowerCase();
     return CONTEXT_OVERFLOW_SUBSTRINGS.some(s => haystack.includes(s));
 }
+// Router usage-control refusals (zergrouter usage-denials.ts) that last until
+// their daily, weekly or monthly window resets.
+const LASTING_ROUTER_USAGE_LIMITS = new Set(['router_usage_budget_exceeded', 'router_usage_token_limit_exceeded']);
+const ROUTER_RATE_LIMIT_CODES = new Set(['rate_limit_exceeded', 'free_model_daily_limit']);
+/**
+ * Continuous recovery rides out an outage, but a provider that keeps refusing for its rate limit is not recovering:
+ * a free OpenRouter model was retried 27 times in ten minutes (2026-10-27). After this many rate-limited attempts in
+ * a row (about four minutes at the default backoff) the turn ends and says so.
+ */
+const RATE_LIMITED_ATTEMPTS = 10;
 const DEFAULT_LLM_REQUEST_TIMEOUT_MS = 120_000;
 /**
  * Resolve the per-attempt request timeout.
@@ -164,11 +187,29 @@ function normalizeRepeatedResponseContent(content) {
         return normalized === block.text ? block : { ...block, text: normalized };
     });
 }
+/** The environment lines a saved row must still match to be resent: its
+ * listing and git status are labelled as of the start, these are not. */
+const RUNTIME_FACT_LINE = /^(?:Working directory:|Platform:|OS Version:|Today's date:|You are powered by the model:|Commands and file tools run inside |Current branch:)/;
+function runtimeFacts(text) {
+    return text.split('\n').filter(line => RUNTIME_FACT_LINE.test(line)).join('\n');
+}
+/** A handoff without its freshness lines: each save moves the as-of time and
+ * revision, and each process its owner PID, without changing the task facts. */
+function handoffSubstance(text) {
+    return text.split('\n').filter(line => !line.startsWith('Source session: ') && !line.startsWith('Historical owner: ')).join('\n');
+}
 // --- Agent Class ---
 export class Agent {
     config;
+    onMidTurnCompact;
+    midTurnCompactThresholdPercent;
+    midTurnCompactWindow;
+    midTurnCompactTokenBudget;
     /** Codex/GPT reasoning effort override; undefined = provider default. */
     _codexEffort;
+    /** One-shot: the next request carries the output-limit note at this effort. */
+    /** The next request retries a discarded response: a note for the model, and lower effort when offered. */
+    responseRetry = null;
     /** Fast mode — request the priority service tier from the Codex/GPT backend. */
     _codexFastMode;
     eventHandlers = new Set();
@@ -190,6 +231,11 @@ export class Agent {
     _autoContinue;
     /** Auto-continues spent since the last tool run; reset per turn and per tool. */
     _consecutiveAutoContinues = 0;
+    _turnAutoContinues = 0;
+    _turnToolBatches = 0;
+    _turnToolChangedState = false;
+    _turnCommandsRun = new Set();
+    _turnCheckAsked = false;
     _subprocessEnv;
     commandPolicy;
     toolEffectObserver;
@@ -319,11 +365,16 @@ export class Agent {
             ? [record.source.verification.receipt_id] : []));
         this.toolResponseStore.evidence.setVerificationCoverage(coverage.filter(row => retained.has(row.receipt_id)));
     }
+    toolGroups;
     discoveredTools = new Set();
     // Host-injected agent-domain tools that ship every request regardless of the
     // deferred-tool registry. Unlike discoveredTools (session-scoped, cleared on
     // session bind), this is fixed for the agent's lifetime.
     alwaysLoadedToolNames = new Set();
+    /** Workers started with delegate_task `background: true`; stopped when a run ends. */
+    backgroundWorkers;
+    /** The latest authored prompt, for a worker's brief. */
+    turnInstruction = '';
     hooks;
     approvalRequester;
     approvalRequiredCapabilities;
@@ -333,7 +384,7 @@ export class Agent {
     constructor(config = {}) {
         this.toolResponseStore = config.toolResponseStore ?? new ToolResponseStore();
         const ambientDiscovery = config.ambientDiscovery ?? true;
-        const defaultProvider = ambientDiscovery ? inferDefaultProvider() : 'anthropic';
+        const defaultProvider = config.provider ?? (ambientDiscovery ? inferDefaultProvider() : 'anthropic');
         const defaultModel = getDefaultModelForProvider(defaultProvider);
         const apiKey = config.apiKey
             || (ambientDiscovery && config.disableApiKeyFallback !== true
@@ -344,15 +395,21 @@ export class Agent {
             apiKey,
             apiEndpoint: config.apiEndpoint,
         });
-        const tools = config.tools ?? (ambientDiscovery ? defaultTools : []);
+        const suppliedTools = config.tools ?? (ambientDiscovery ? defaultTools : []);
+        this.toolGroups = config.toolGroups ? new ToolGroupRuntime(config.toolGroups, suppliedTools, !isCodexAppServerProvider(config.runtimeFacts?.provider ?? defaultProvider)) : undefined;
+        const tools = this.toolGroups?.tools ?? suppliedTools;
         this.config = {
+            provider: defaultProvider,
             model: config.model || defaultModel,
             apiKey,
             disableApiKeyFallback: config.disableApiKeyFallback ?? false,
-            runtimeCredentialsAvailable: config.runtimeCredentialsAvailable ?? false,
+            runtimeCredentialsAvailable: config.runtimeCredentialsAvailable ?? (defaultProvider === 'bedrock'),
             apiEndpoint: config.apiEndpoint || ((defaultProvider === 'anthropic' || defaultProvider === 'claude_code' || defaultProvider === 'claude-code') ? 'https://api.anthropic.com/v1/messages' : 'https://api.openai.com/v1'),
             maxTokens: config.maxTokens,
             routePlan: config.routePlan,
+            leadTurnNote: config.leadTurnNote,
+            leadStaffingNote: config.leadStaffingNote,
+            workerCheckIntervalMs: config.workerCheckIntervalMs,
             maxIterations: config.maxIterations || 10,
             execution: resolveExecutionSettings(config.execution),
             sessionId: config.sessionId ?? randomUUID(),
@@ -367,10 +424,16 @@ export class Agent {
             tracer: config.tracer || new NoopTracer(),
             cwd: config.cwd || process.cwd(),
             autoContinue: config.autoContinue ?? true,
+            completionCheck: config.completionCheck ?? false,
             maxConsecutiveAutoContinues: config.maxConsecutiveAutoContinues ?? 3,
             pinTaskHeader: config.pinTaskHeader ?? true,
-            deferToolSchemas: config.deferToolSchemas ?? true
+            deferToolSchemas: config.deferToolSchemas ?? true,
         };
+        this.onMidTurnCompact = config.onMidTurnCompact;
+        this.midTurnCompactThresholdPercent = config.midTurnCompactThresholdPercent;
+        this.midTurnCompactWindow = config.midTurnCompactWindow;
+        this.midTurnCompactTokenBudget = config.midTurnCompactTokenBudget;
+        this.runtimeContext = config.runtimeContext?.trim() ? config.runtimeContext : null;
         this._subprocessEnv = config.subprocessEnv === undefined
             ? undefined
             : buildUserSubprocessEnv(config.subprocessEnv);
@@ -383,6 +446,7 @@ export class Agent {
         // Host-injected agent-domain tools always ship their schema (they're the
         // agent's primary surface, not a corpus to search). Kept separate from
         // discoveredTools so a session bind's discovered.clear() can't drop them.
+        this.backgroundWorkers = new BackgroundWorkers(config.workerCheckIntervalMs);
         for (const name of config.alwaysLoadedToolNames ?? []) {
             this.alwaysLoadedToolNames.add(name);
         }
@@ -394,6 +458,19 @@ export class Agent {
         this.policy = this.config.policy;
         const suppliedTracer = this.config.tracer;
         this.tracer = { event: event => {
+                // Opaque provider continuation is session state, not diagnostic content.
+                // Never leak it into prompt viewers, traces, or caller audit sinks.
+                if (event.type === 'api_request' || event.type === 'api_response') {
+                    const sanitize = (value) => {
+                        if (Array.isArray(value))
+                            return value.filter(item => !(item && typeof item === 'object' && 'type' in item && item.type === 'responses_reasoning')).map(sanitize);
+                        if (value && typeof value === 'object')
+                            return Object.fromEntries(Object.entries(value)
+                                .filter(([key]) => key !== 'responsesItem' && key !== 'responseItems' && key !== 'openaiResponseItems' && key !== 'encrypted_content').map(([key, child]) => [key, sanitize(child)]));
+                        return value;
+                    };
+                    event = { ...event, data: sanitize(event.data) };
+                }
                 this.captureDiagnosticTrace(event);
                 suppliedTracer.event(event);
             } };
@@ -431,6 +508,8 @@ export class Agent {
     /** Override the agent's system prompt (e.g., for simulation persona injection). */
     setSystemPrompt(prompt) {
         this.config.systemPrompt = prompt;
+        // The override replaces the composed prompt, environment included.
+        this.runtimeContext = null;
         this._hasCustomSystemPrompt = true;
     }
     /**
@@ -484,10 +563,30 @@ export class Agent {
     getCwd() {
         return this._cwd;
     }
+    /** Load a declared group after a host page change; Codex requires a new session. */
+    loadToolGroup(group) {
+        if (!this.toolGroups)
+            throw new Error('No tool groups are configured.');
+        return this.toolGroups.load(group);
+    }
     /** Snapshot the effective tool surface after mode/provider filtering. */
     getConfiguredToolNames() {
         return this.config.tools.map((tool) => tool.definition.name);
     }
+    getHandoffContext(messages = []) {
+        return { ...this.buildRequest([...messages]), backend: this.backend,
+            onMetrics: metrics => {
+                this.emit({ type: 'request_metrics', metrics });
+                if (!metrics.usage)
+                    return;
+                this.retainUsageReceipt({ id: `usage_${randomUUID()}`, sessionId: this.config.sessionId,
+                    projectHash: createHash('sha256').update(this._cwd).digest('hex').slice(0, 12),
+                    provider: this.config.runtimeFacts.provider ?? null, model: this.config.model, accountId: null,
+                    observedAt: new Date().toISOString(), source: metrics.usage.estimated ? 'estimated' : 'reported',
+                    usage: metrics.usage, costUsd: null });
+            },
+        };
+    }
     getDefaultSystemPrompt(tools) {
         const offloadEnabled = this.toolResponseStore.getConfig().offloadEnabled;
         const offloadSection = offloadEnabled
@@ -527,6 +626,12 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         return () => this.eventHandlers.delete(handler);
     }
     emit(event) {
+        if (event.type === 'history_checkpoint') {
+            event = { ...event, messages: event.messages.map(message => {
+                    const { openaiResponseItems, ...metadata } = message.metadata ?? {};
+                    return { ...message, metadata };
+                }) };
+        }
         for (const handler of this.eventHandlers) {
             handler(event);
         }
@@ -575,14 +680,19 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
     _nativeContextId;
     formatMessages(messages) {
         // Pre-pass: collect every tool_use_id appearing in tool_result messages,
-        // and remember the LAST batch (treated as current turn). Running the
+        // and retain every batch since the latest authored prompt. Running the
         // selector once for the whole request gives aggregate budget control;
         // buildContentBlocks below just reads the verdict.
         const allToolIds = [];
-        let currentTurnToolIds = new Set();
+        const currentTurnToolIds = new Set();
         for (const m of messages) {
             if (m.role !== 'user' || !m.content)
                 continue;
+            if (!isToolResultMessage(m)) {
+                if (!m.metadata?.synthetic && !m.metadata?.hostContext)
+                    currentTurnToolIds.clear();
+                continue;
+            }
             const trimmed = m.content.trimStart();
             if (!trimmed.startsWith('[') || !trimmed.includes('"tool_use_id"'))
                 continue;
@@ -592,7 +702,8 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     .map(p => (typeof p?.tool_use_id === 'string' ? p.tool_use_id : null))
                     .filter((id) => Boolean(id));
                 allToolIds.push(...ids);
-                currentTurnToolIds = new Set(ids);
+                for (const id of ids)
+                    currentTurnToolIds.add(id);
             }
             catch {
                 // Unparseable user message; skip.
@@ -635,10 +746,25 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
             selectorVerdict: this._selectorVerdict,
             currentTurnToolIds: this._currentRequestToolIds,
             renderForContext: (id) => this.toolResponseStore.renderForContext(id),
+            saveFullResult: (id, content) => this.saveFullResult(id, content),
+            frozenResultContent: (id) => this.toolResponseStore.frozenResultContent(id),
+            freezeResultContent: (id, content) => this.toolResponseStore.freezeResultContent(id, content),
             loadImageBlock: (path) => this.loadImageBlock(path),
             loadVideoBlock: (path) => this.loadVideoBlock(path),
         };
     }
+    /** A whole result kept on disk before it is sent shortened; an ephemeral tool's stays in memory. */
+    saveFullResult(toolUseId, content, call) {
+        const config = this.toolResponseStore.getConfig();
+        if (this.toolResponseStore.getMeta(toolUseId)?.ephemeral
+            || (call && isEphemeralToolCall(call.name, call.args, config.ephemeralToolNames, config.ephemeralToolRules)))
+            return null;
+        const folder = this.toolResponseStore.outputCopyDir();
+        // A copy nothing can read would only leave the result in plain text on disk.
+        if (!folder || !canReadCopies(this.config.tools.map(tool => tool.definition.name)))
+            return null;
+        return saveCopy(folder, toolUseId, 'result', content);
+    }
     contentLength(content) {
         if (typeof content === 'string')
             return content.length;
@@ -878,7 +1004,9 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     content = 'Tool outcome unknown: the original result was not durably observed. Inspect this exact call and its existing receipts/current state before deciding whether to retry. Do not automatically repeat the original command; local interruption does not prove that an external operation stopped.';
                 }
                 if (content.length > SYNTH_RESULT_CAP) {
-                    content = content.slice(0, SYNTH_RESULT_CAP) + `\n[truncated — ${content.length} chars total]`;
+                    const copy = this.saveFullResult(tc.id, content, tc);
+                    content = content.slice(0, SYNTH_RESULT_CAP)
+                        + `\n[truncated — ${content.length} chars total${copy ? `; ${resultCopyNote(tc.id, copy)}; ${COPY_ADVICE}` : ''}]`;
                 }
                 emittedToolResultIds.add(tc.id);
                 return { tool_use_id: tc.id, content, is_error: Boolean(tc.error) || tc.result == null };
@@ -899,13 +1027,22 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         return repaired;
     }
     buildRequest(messages, availableTools = this.config.tools) {
+        messages = projectHandoffHistory(messages);
         this.captureUserInstructions(messages);
-        const evidence = formatEvidenceContext(this.getEvidenceSnapshot());
+        // A call with a recorded outcome is sent with its result (inline or as a
+        // stored preview), so its evidence needs no second copy of the output.
+        const toolCallsInContext = new Set(messages.flatMap(message => (message.toolCalls ?? [])
+            .filter(call => call.result !== undefined || call.error !== undefined).map(call => call.id)));
         const evidenceTurn = [...messages].reverse().find(message => message.role === 'user');
         // Stamp each source turn once. Render the host index next to that turn
         // without changing its text, the system prefix or prior request records.
-        if (evidence && evidenceTurn && typeof evidenceTurn.metadata?.evidenceContext !== 'string') {
-            evidenceTurn.metadata = { ...evidenceTurn.metadata, evidenceContext: evidence };
+        // Earlier stamps stay in the conversation, so a new stamp lists only the
+        // records they do not already show unchanged.
+        if (evidenceTurn && typeof evidenceTurn.metadata?.evidenceContext !== 'string') {
+            const renderedEarlier = messages.flatMap(message => typeof message.metadata?.evidenceContext === 'string' ? [message.metadata.evidenceContext] : []);
+            const evidence = formatEvidenceContext(this.getEvidenceSnapshot(), { toolCallsInContext, renderedEarlier });
+            if (evidence)
+                evidenceTurn.metadata = { ...evidenceTurn.metadata, evidenceContext: evidence };
         }
         // Repair any orphaned tool_use blocks before building request
         if (this.config.pinTaskHeader) {
@@ -954,26 +1091,65 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         });
         if (this.config.pinTaskHeader && this.taskHandoff) {
             const snapshot = this.taskHandoff.snapshot;
-            // Saved user/tool text retains conversation priority, alongside the other
-            // host observations, without changing a hosted thread's base instructions.
-            let currentUserIndex = contextMessages.length - 1;
-            for (; currentUserIndex >= 0; currentUserIndex--) {
-                const message = contextMessages[currentUserIndex];
-                if (message.role === 'user' && !message.metadata?.synthetic && !message.metadata?.hostContext
-                    && !message.metadata?.toolResult && !message.metadata?.compactionSummary)
-                    break;
+            const currentRequest = [...contextMessages].reverse().find(message => message.role === 'user'
+                && !message.metadata?.synthetic && !message.metadata?.hostContext
+                && !message.metadata?.toolResult && !message.metadata?.compactionSummary);
+            const compactedHead = resolvePromptPrefixId(contextMessages) ?? null;
+            const prefixId = compactedHead ?? currentRequest?.id ?? null;
+            const kept = this.taskHandoffTurn;
+            if (!kept || (!kept.pinned && kept.prefixId !== prefixId)) {
+                const content = formatTaskHandoffContext(snapshot);
+                // The handoff sits ahead of all history, so new bytes there void the
+                // prompt cache for the whole conversation. Every save moves the
+                // checkpoint's as-of time and revision; only a checkpoint that says
+                // something new, or compacted history, which voids the cache anyway,
+                // replaces the row.
+                if (kept && kept.compactedHead === compactedHead
+                    && handoffSubstance(kept.content) === handoffSubstance(content)) {
+                    kept.prefixId = prefixId;
+                }
+                else {
+                    this.taskHandoffTurn = { id: `handoff_${snapshot.source.sessionId}_${snapshot.revision}`,
+                        content, capturedAt: snapshot.source.capturedAt, prefixId, compactedHead };
+                }
             }
-            // Historical context belongs before the current instruction. Never split
-            // an assistant/tool-result pair or replace the request tail with history.
-            contextMessages.splice(currentUserIndex < 0 ? 0 : currentUserIndex, 0, {
-                id: `handoff_${snapshot.source.sessionId}_${snapshot.revision}`,
-                role: 'user', content: formatTaskHandoffContext(snapshot),
-                timestamp: new Date(snapshot.source.capturedAt),
+            const handoff = this.taskHandoffTurn;
+            contextMessages.unshift({
+                id: handoff.id,
+                role: 'user', content: handoff.content,
+                timestamp: new Date(handoff.capturedAt),
                 metadata: { synthetic: true, hostContext: true, preserveUserBoundary: true }
             });
         }
+        if (this.config.pinTaskHeader && this.runtimeContext) {
+            this.runtimeEnvironmentTurn ??= { id: 'runtime_environment', content: this.runtimeContext,
+                capturedAt: (contextMessages[0]?.timestamp instanceof Date
+                    ? contextMessages[0].timestamp : new Date()).toISOString() };
+            contextMessages.unshift({ id: this.runtimeEnvironmentTurn.id, role: 'user',
+                content: this.runtimeEnvironmentTurn.content,
+                timestamp: new Date(this.runtimeEnvironmentTurn.capturedAt),
+                metadata: { synthetic: true, hostContext: true, preserveUserBoundary: true } });
+        }
+        const responseRetry = this.responseRetry;
+        this.responseRetry = null;
+        if (responseRetry) {
+            contextMessages.push({ id: `retry_note_${randomUUID()}`, role: 'user', content: responseRetry.note,
+                timestamp: new Date(), metadata: { synthetic: true, hostContext: true } });
+        }
+        if (this.config.leadTurnNote) {
+            // After every authored prompt, not only the latest, so earlier requests stay a prefix of later ones.
+            for (let index = contextMessages.length - 1; index >= 0; index--) {
+                const message = contextMessages[index];
+                if (message.role !== 'user' || message.metadata?.synthetic || message.metadata?.hostContext
+                    || message.metadata?.toolResult || message.metadata?.compactionSummary)
+                    continue;
+                contextMessages.splice(index + 1, 0, { id: `lead_note_${message.id}`, role: 'user', content: this.config.leadTurnNote,
+                    timestamp: message.timestamp, metadata: { synthetic: true, hostContext: true, preserveUserBoundary: true } });
+            }
+        }
         const system = this.systemWithTaskHeader(messages);
-        const tools = getRequestToolDefinitions(availableTools, this.discoveredTools, this.config.deferToolSchemas !== false, this.alwaysLoadedToolNames);
+        const baseDefinitions = getRequestToolDefinitions(availableTools, this.discoveredTools, this.config.deferToolSchemas !== false, this.alwaysLoadedToolNames);
+        const tools = this.toolGroups?.requestDefinitions(baseDefinitions, availableTools) ?? baseDefinitions;
         this._nativeContextId = this.backend.preservesNativeHistory ? nativeHistoryContextId(system, tools) : undefined;
         return {
             model: this.config.model,
@@ -986,7 +1162,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
             // was warmed for. That is compaction, and only this layer can see it.
             promptPrefixId: resolvePromptPrefixId(repairedMessages),
             routePlan: this.config.routePlan,
-            codexEffort: this._codexEffort,
+            codexEffort: responseRetry?.effort ?? this._codexEffort,
             codexFastMode: this._codexFastMode,
         };
     }
@@ -1043,7 +1219,9 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         let text = '';
         let reasoning = '';
         const toolUses = [];
+        const closedToolUses = new Set();
         const nativeContent = [];
+        let responseItems;
         let usage;
         let reportedUsage;
         let costUsd;
@@ -1056,8 +1234,11 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         // paints an empty "Zerg" row in the transcript. Hold it until a visible
         // character shows up and ship it with that text, so no byte is dropped.
         let pendingWhitespace = '';
+        let streamStarted = false;
+        let sawCompletion = false;
         try {
-            for await (const ev of this.backend.generateStream(request)) {
+            for await (const ev of guardRunawayOutput(this.backend.generateStream(request))) {
+                streamStarted = true;
                 if (signal?.aborted)
                     throw new AgentError('Cancelled', 'CANCELLED');
                 // Every stream event is a sign of life for callAPI's inactivity guard,
@@ -1066,6 +1247,9 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                 switch (ev.type) {
                     case 'heartbeat':
                         break;
+                    case 'response_items':
+                        responseItems = ev.items;
+                        break;
                     case 'content_block':
                         nativeContent.push(ev.block);
                         break;
@@ -1120,6 +1304,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         break;
                     }
                     case 'tool_use_end':
+                        closedToolUses.add(ev.id);
                         break;
                     case 'usage': {
                         usage = ev.usage;
@@ -1144,34 +1329,49 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             costUsd = ev.costUsd;
                         break;
                     case 'done':
+                        sawCompletion = true;
                         stopReason = ev.stopReason;
                         stopDetails = ev.stopDetails;
                         break;
                 }
             }
         }
+        catch (error) {
+            if (streamStarted && error instanceof Error
+                && !(error instanceof AgentError) && !(error instanceof RunawayOutputError)
+                && !(error instanceof NativeObservationLimitError)
+                && !isIncompleteStreamError(error) && !(error instanceof BackendHttpError)) {
+                throw new IncompleteStreamError(error.message);
+            }
+            throw error;
+        }
         finally {
             // Always close an opened stream so the mirror clears its cursor, even on
             // abort/error mid-stream.
             if (streamOpen)
                 this.emit({ type: 'stream_end' });
         }
+        if (!sawCompletion)
+            throw new IncompleteStreamError();
         const content = [];
         if (text)
             content.push({ type: 'text', text });
-        for (const tu of toolUses) {
-            let input = {};
-            if (tu.inputJson.trim()) {
-                try {
-                    input = JSON.parse(tu.inputJson);
-                }
-                catch {
-                    input = {};
-                }
+        for (const tu of isIncompleteModelResponse(stopReason) ? [] : toolUses) {
+            if (nativeContent.some(block => block.type === 'tool_use' && block.id === tu.id))
+                continue;
+            if (!tu.inputJson.trim() && !closedToolUses.has(tu.id)) {
+                throw new IncompleteStreamError(`Tool call ${tu.name} arrived with no arguments.`);
+            }
+            let input;
+            try {
+                input = tu.inputJson.trim() ? JSON.parse(tu.inputJson) : {};
+            }
+            catch {
+                throw new IncompleteStreamError(`Tool call ${tu.name} arrived with incomplete arguments.`);
             }
             content.push({ type: 'tool_use', id: tu.id, name: tu.name, input });
         }
-        return { content: nativeContent.length > 0 ? nativeContent : content, stopReason,
+        return { content: nativeContent.length > 0 ? nativeContent : content, stopReason, responseItems,
             ...(stopDetails ? { stopDetails } : {}), reasoning: reasoning || undefined, usage,
             ...(costUsd === undefined ? {} : { costUsd }) };
     }
@@ -1250,6 +1450,9 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         'submit_plan',
         'plan_mode',
     ]);
+    static SELF_RESOLVING_TOOLS = new Set([
+        'ztc_command',
+    ]);
     /**
      * R7: the original task, pinned into request.system so it survives compaction
      * (which only rewrites the message array, never request.system) and the rolling
@@ -1259,7 +1462,10 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
      * genuinely multi-task long-lived agents is deferred (plan A10).
      */
     _taskHeader = null;
+    runtimeContext = null;
     taskHandoff = null;
+    taskHandoffTurn = null;
+    runtimeEnvironmentTurn = null;
     /** Only a host-selected checkpoint may supply historical task context. */
     setTaskHandoff(projection) {
         const admitted = projection === null ? null : parseTaskHandoffProjection(projection);
@@ -1269,6 +1475,38 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
             throw new TypeError('Task handoff belongs to a different selected session');
         }
         this.taskHandoff = admitted;
+        if (!admitted) {
+            this.taskHandoffTurn = null;
+            return;
+        }
+        if (this.taskHandoffTurn)
+            return;
+        this.taskHandoffTurn = { id: `handoff_${admitted.snapshot.source.sessionId}_${admitted.snapshot.revision}`,
+            content: formatTaskHandoffContext(admitted.snapshot),
+            capturedAt: admitted.snapshot.source.capturedAt, prefixId: null };
+    }
+    hostScaffoldMessages() {
+        const rows = [];
+        if (this.taskHandoffTurn)
+            rows.push({ id: this.taskHandoffTurn.id,
+                content: this.taskHandoffTurn.content, capturedAt: this.taskHandoffTurn.capturedAt });
+        if (this.runtimeEnvironmentTurn)
+            rows.push(this.runtimeEnvironmentTurn);
+        return rows;
+    }
+    setHostScaffoldMessages(rows) {
+        if (!rows?.length)
+            return;
+        for (const row of rows) {
+            if (row.id.startsWith('handoff_')) {
+                this.taskHandoffTurn = { id: row.id, content: row.content, capturedAt: row.capturedAt,
+                    prefixId: this.taskHandoffTurn?.prefixId ?? null, pinned: true };
+            }
+            else if (row.id === 'runtime_environment' && this.runtimeContext !== null
+                && runtimeFacts(row.content) === runtimeFacts(this.runtimeContext)) {
+                this.runtimeEnvironmentTurn = { ...row };
+            }
+        }
     }
     /**
      * Drop the explicitly pinned task for the next conversation. Wired into the /clear-only path (clearTransientState), never into
@@ -1311,8 +1549,9 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
     }
     systemWithTaskHeader(_messages) {
         // Hosted chat owns its system prompt: no local execution facts and no pin.
-        if (!this.config.pinTaskHeader)
-            return this.config.systemPrompt;
+        if (!this.config.pinTaskHeader) {
+            return this.runtimeContext ? `${this.config.systemPrompt}\n\n${this.runtimeContext}` : this.config.systemPrompt;
+        }
         return pinnedTaskSystem(this.config.systemPrompt, this._taskHeader);
     }
     async persistToolCheckpoint(phase, toolCallId, messages, handler = this.toolCheckpoint) {
@@ -1462,7 +1701,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                 ...(result.nativeContent ? { nativeContent: result.nativeContent, nativeModel: result.nativeModel, nativeContextId: result.nativeContextId } : {}),
                 timestamp: new Date(),
                 ...(result.toolCalls.length > 0 ? { toolCalls: result.toolCalls } : {}),
-                metadata: { ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(result.reasoning ? { reasoningContent: result.reasoning } : {}) },
+                metadata: { ...(result.responseItems ? { openaiResponseItems: result.responseItems, openaiResponseModel: this.config.model } : {}), ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(result.reasoning ? { reasoningContent: result.reasoning } : {}) },
             };
             const receipt = await binding.driver.publish({
                 turn,
@@ -1505,6 +1744,9 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         if (!this.hasApiKey()) {
             throw new AgentError('No API key configured. Use /config key <key> to set one.', 'NO_API_KEY');
         }
+        const authored = [...messages].reverse().find(message => message.role === 'user' && !message.metadata?.synthetic
+            && !message.metadata?.hostContext && !message.metadata?.toolResult && !message.metadata?.compactionSummary);
+        this.turnInstruction = typeof authored?.content === 'string' ? authored.content : this.turnInstruction;
         for (const message of messages) {
             if (message.role !== 'assistant')
                 continue;
@@ -1519,6 +1761,10 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         // Each turn gets its own auto-continue budget; a long-running Agent must
         // not inherit one spent by the previous turn.
         this._consecutiveAutoContinues = 0;
+        this._turnAutoContinues = 0;
+        this._turnToolBatches = 0;
+        this._turnCommandsRun.clear();
+        this._turnCheckAsked = false;
         let finalContent = '';
         // Provider-opaque reasoning trace for the turn the caller will persist.
         // Reasoning models (Kimi K3, DeepSeek) expect the assistant message replayed
@@ -1526,6 +1772,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         // only inside one run() and every later user turn sends a stripped history.
         let finalReasoning;
         let finalNativeContent;
+        let finalResponseItems;
         let lastToolTurnText = '';
         let totalUsage = null;
         let runError = null;
@@ -1534,6 +1781,10 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         // Falling through the `while` condition means the model still wanted to
         // continue but ran out of iterations — a silent stall today (C5/F8).
         let stopReason = 'max_iterations';
+        let outputLimitRetried = false;
+        let runawayRetried = false;
+        let midTurnMessagesSinceCompaction = 0;
+        let midTurnLastFreedTokens;
         // R5 progress-delta guard (shared loop_policy, identical to SubAgent.run so
         // the two loops cannot drift): flags a tool call whose byte-identical input
         // reproduced a byte-identical result as non-progressing (F8 churn / F1
@@ -1554,6 +1805,24 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     const availability = await Promise.all(this.config.tools.map(tool => tool.isAvailable?.({ cwd: this._cwd }) ?? true));
                     const availableTools = this.config.tools.filter((_tool, index) => availability[index]);
                     await this.refreshVerificationCoverage();
+                    // Background workers' reports join the conversation once, ahead of the request that follows them.
+                    const reports = this.backgroundWorkers.takeReady();
+                    if (reports.length > 0) {
+                        messages.push({ id: `worker_reports_${randomUUID()}`, role: 'user', content: formatWorkerReports(reports),
+                            timestamp: new Date(), metadata: { synthetic: true, hostContext: true } });
+                    }
+                    // A lead busy with its own work still gets each progress check on its running workers.
+                    const check = this.backgroundWorkers.takeDueCheck();
+                    if (check) {
+                        messages.push({ id: `worker_check_${randomUUID()}`, role: 'user', content: check, timestamp: new Date(),
+                            metadata: { synthetic: true, hostContext: true } });
+                    }
+                    // A lead knows what to hand off only after exploring, so one that has worked alone is asked once.
+                    const staffing = this.config.leadStaffingNote;
+                    if (staffing && iterations === staffing.afterSteps + 1 && !allToolCalls.some(call => call.name === 'delegate_task')) {
+                        messages.push({ id: `lead_staffing_${randomUUID()}`, role: 'user', content: staffing.content, timestamp: new Date(),
+                            metadata: { synthetic: true, hostContext: true } });
+                    }
                     const request = this.buildRequest(messages, availableTools);
                     request.signal = signal;
                     request.onMetrics = metrics => {
@@ -1602,6 +1871,17 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         else
                             this.retainUsageReceipt({ ...identity, observedAt: new Date().toISOString(),
                                 source: 'unavailable', usage: null, costUsd: null });
+                        // A runaway response was stopped while streaming and is never accepted.
+                        // Partial tool calls in it never run. Retry once per turn with a note.
+                        if (error instanceof RunawayOutputError) {
+                            if (runawayRetried)
+                                throw new AgentError(repeatedRunawayMessage(error), RUNAWAY_OUTPUT_CODE);
+                            runawayRetried = true;
+                            this.responseRetry = { note: RUNAWAY_OUTPUT_RETRY_NOTE, effort: outputLimitRetryEffort(this.backend.getModelCapabilities?.(request.model)?.reasoning?.choices, this._codexEffort) };
+                            this.emit({ type: 'api_retry', attempt: 1, maxAttempts: 1, delay: 0, phase: 'retry', elapsedMs: 0,
+                                reason: 'The response kept repeating the same text and was stopped; retrying' });
+                            continue;
+                        }
                         throw error;
                     }
                     // Retain returned accounting before a later cancellation/checkpoint guard can discard the answer.
@@ -1651,11 +1931,23 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     // incomplete tool payload. The fixed error deliberately excludes model
                     // output so callers can log it without reflecting sensitive content.
                     if (isIncompleteModelResponse(response.stopReason)) {
+                        // A response that used its whole output limit reasoning, before any
+                        // visible answer, gets one retry per turn. Partial tool calls in it are
+                        // never executed; a response that already showed text is not repeated.
+                        if (!outputLimitRetried && isOutputLimitStop(response.stopReason, request.maxTokens, response.usage?.outputTokens)
+                            && !response.content.some(block => this.isTextBlock(block) && block.text.trim())) {
+                            outputLimitRetried = true;
+                            this.responseRetry = { note: OUTPUT_LIMIT_RETRY_NOTE, effort: outputLimitRetryEffort(this.backend.getModelCapabilities?.(request.model)?.reasoning?.choices, this._codexEffort) };
+                            this.emit({ type: 'api_retry', attempt: 1, maxAttempts: 1, delay: 0, phase: 'retry', elapsedMs: 0,
+                                reason: 'The response reached the output limit while reasoning; retrying in smaller steps' });
+                            continue;
+                        }
                         throw new AgentError(incompleteModelResponseMessage(response.stopReason, request.maxTokens, response.usage?.outputTokens), INCOMPLETE_MODEL_RESPONSE_CODE);
                     }
                     if (response.stopReason === 'refusal') {
                         throw new AgentError('The model declined this request.', 'MODEL_REFUSAL');
                     }
+                    finalResponseItems = response.responseItems;
                     // Check for tool use
                     const requestedToolBlocks = response.content.filter(this.isToolUseBlock);
                     const requestedIds = new Set();
@@ -1733,7 +2025,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                                     const answer = {
                                         id: `assistant_${Date.now()}_${iterations}`, role: 'assistant', content: iterationText, timestamp: new Date(),
                                         turn: requestUsage?.getTurn?.(),
-                                        metadata: { ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(response.reasoning ? { reasoningContent: response.reasoning } : {}) },
+                                        metadata: { ...(response.responseItems ? { openaiResponseItems: response.responseItems, openaiResponseModel: this.config.model } : {}), ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(response.reasoning ? { reasoningContent: response.reasoning } : {}) },
                                     };
                                     messages.push(answer);
                                     turnMessages.push(answer);
@@ -1770,23 +2062,75 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             }
                             this.emit({ type: 'auto_continue', reason });
                             // Add the assistant's response
-                            messages.push({
+                            const autoContinueAnswer = {
                                 id: `assistant_${Date.now()}`,
                                 role: 'assistant',
                                 content: iterationText,
                                 ...(this.backend.preservesNativeHistory ? { nativeContent: structuredClone(response.content), nativeModel: this.config.model, nativeContextId: this._nativeContextId } : {}),
                                 timestamp: new Date(),
-                                metadata: { ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(response.reasoning ? { reasoningContent: response.reasoning } : {}) },
-                            });
+                                metadata: { ...(response.responseItems ? { openaiResponseItems: response.responseItems, openaiResponseModel: this.config.model } : {}), ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(response.reasoning ? { reasoningContent: response.reasoning } : {}) },
+                            };
+                            messages.push(autoContinueAnswer);
+                            turnMessages.push(autoContinueAnswer);
                             // Add auto-continue prompt as user message
-                            messages.push({
+                            const autoContinuePrompt = {
                                 id: `auto_continue_${Date.now()}`,
                                 role: 'user',
                                 content: continueMsg,
-                                timestamp: new Date()
-                            });
+                                timestamp: new Date(),
+                                metadata: { synthetic: true, autoContinue: true },
+                            };
+                            messages.push(autoContinuePrompt);
+                            turnMessages.push(autoContinuePrompt);
+                            continue; // Don't break, keep looping
+                        }
+                        if (!this.remoteResourceSession
+                            && needsCompletionCheck({ usedTools: this._turnToolBatches > 0, hasPendingToolCall: false })
+                            && completionCheckDue({ autoContinue: this._autoContinue && this.config.completionCheck === true, toolBatches: this._turnToolBatches,
+                                changedState: this._turnToolChangedState,
+                                askedSinceProgress: this._turnCheckAsked,
+                                turnChecks: this._turnAutoContinues, hardCap: this.config.maxConsecutiveAutoContinues,
+                                reply: iterationText })) {
+                            const hardCap = this.config.maxConsecutiveAutoContinues;
+                            this._turnAutoContinues++;
+                            this._turnCheckAsked = this._turnAutoContinues < hardCap;
+                            this._turnToolBatches = 0;
+                            const acTodos = getLatestTodos();
+                            const incomplete = acTodos.filter(t => t.status !== 'completed');
+                            const remaining = incomplete.length > 0
+                                ? ` You still have ${incomplete.length} incomplete task(s): ${incomplete.map(t => t.content).join(', ')}.`
+                                : '';
+                            const continueMsg = 'If any part of this task is still unfinished, continue with the next step now. '
+                                + 'Otherwise, reply that the work is complete, or state exactly what you need from the user.'
+                                + remaining;
+                            const reason = 'completion check';
+                            this.emit({ type: 'auto_continue', reason });
+                            // Add the assistant's response
+                            const completionAnswer = {
+                                id: `assistant_${Date.now()}`,
+                                role: 'assistant',
+                                turn: requestUsage?.getTurn?.(),
+                                content: iterationText,
+                                ...(this.backend.preservesNativeHistory ? { nativeContent: structuredClone(response.content), nativeModel: this.config.model, nativeContextId: this._nativeContextId } : {}),
+                                timestamp: new Date(),
+                                metadata: { ...(response.responseItems ? { openaiResponseItems: response.responseItems, openaiResponseModel: this.config.model } : {}), ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(response.reasoning ? { reasoningContent: response.reasoning } : {}) },
+                            };
+                            messages.push(completionAnswer);
+                            turnMessages.push(completionAnswer);
+                            // Add auto-continue prompt as user message
+                            const completionPrompt = {
+                                id: `auto_continue_${Date.now()}`,
+                                role: 'user',
+                                content: continueMsg,
+                                turn: requestUsage?.getTurn?.(),
+                                timestamp: new Date(),
+                                metadata: { synthetic: true, autoContinue: true },
+                            };
+                            messages.push(completionPrompt);
+                            turnMessages.push(completionPrompt);
                             continue; // Don't break, keep looping
                         }
+                        this._turnToolBatches = 0;
                         stopReason = 'complete';
                         break;
                     }
@@ -1806,7 +2150,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             : response.content.filter(this.isTextBlock).map(block => block.text).join('\n') || '[Using tools...]',
                         ...(this.backend.preservesNativeHistory ? { nativeContent: structuredClone(response.content), nativeModel: this.config.model, nativeContextId: this._nativeContextId } : {}),
                         timestamp: new Date(), toolCalls: batchCalls,
-                        metadata: { toolCheckpoint: true, ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(response.reasoning ? this.remoteResourceSession
+                        metadata: { ...(response.responseItems ? { openaiResponseItems: response.responseItems, openaiResponseModel: this.config.model } : {}), toolCheckpoint: true, ...(this.config.runtimeFacts.mode === 'plan' ? { planMode: true } : {}), ...(response.reasoning ? this.remoteResourceSession
                                 ? { providerReasoning: response.reasoning } : { reasoningContent: response.reasoning } : {}) },
                     };
                     messages.push(toolUseMessage);
@@ -1814,7 +2158,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     allToolCalls.push(...batchCalls);
                     const toolResultMessage = {
                         id: `tool_${randomUUID()}`, role: 'user', content: '[]', timestamp: new Date(),
-                        metadata: { toolResult: true, toolCheckpoint: true },
+                        metadata: { toolResult: true, toolCheckpoint: true, preserveUserBoundary: true },
                     };
                     const completedResults = new Map();
                     const retainToolResult = async (toolCall, rawContent, guardedContent, managedCommand, contentTruncated = false, verificationReceipt, verifierDecision, benchmarkComparisonDecision) => {
@@ -1832,6 +2176,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         if (!turnMessages.some(message => message.id === toolResultMessage.id)) {
                             messages.push(toolResultMessage);
                             turnMessages.push(toolResultMessage);
+                            midTurnMessagesSinceCompaction += 1;
                         }
                         await this.refreshVerificationCoverage();
                         await this.persistToolCheckpoint('terminal', toolCall.id, turnMessages, toolCheckpoint);
@@ -1920,18 +2265,23 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             return recordToolError(toolBlock, toolCall, 'finish_task must be the only tool call; observe other results before completing the task.');
                         }
                         // Selector intent does not prove visibility: the encoder may cap or
-                        // compress the result. Acknowledge only exact encoded source bytes
-                        // that also remain within the historical stability limit. Larger
-                        // current results become previews after this recall is appended.
+                        // compress the result. Acknowledge only when the request holds the
+                        // whole stored result, as the model reads it (tool_result_presentation.ts),
+                        // and the stored result is within the historical stability limit.
+                        // Larger current results become previews after this recall is appended.
                         // A hook dispatcher still owns each invocation's admission and outcome.
                         const innerId = recallInnerIdOf(toolBlock);
-                        if (!this.hooks && innerId !== null &&
+                        const stored = innerId === null ? undefined : this.toolResponseStore.cachedContent(innerId);
+                        const innerName = request.messages.flatMap(message => typeof message.content === 'string' ? [] : message.content)
+                            .find((block) => block.type === 'tool_use' && block.id === innerId)?.name ?? '';
+                        if (!this.hooks && innerId !== null && stored !== undefined &&
                             toolBlock.input.cursor === undefined && toolBlock.input.max_bytes === undefined &&
+                            (toolBlock.input.part === undefined || toolBlock.input.part === 'result') &&
                             this.toolResponseStore.willInlineNextRender(innerId) &&
-                            this.toolResponseStore.hasCached(innerId) &&
+                            stored.length <= STABLE_RESULT_LIMIT &&
+                            createHash('sha256').update(stored).digest('hex') === this.toolResponseStore.getMeta(innerId)?.result_sha256 &&
                             request.messages.some(message => typeof message.content !== 'string' && message.content.some(block => block.type === 'tool_result' && block.tool_use_id === innerId &&
-                                typeof block.content === 'string' && block.content.length <= STABLE_RESULT_LIMIT &&
-                                createHash('sha256').update(block.content).digest('hex') === this.toolResponseStore.getMeta(innerId)?.result_sha256))) {
+                                block.content === presentToolResult(innerName, stored)))) {
                             const ack = JSON.stringify({
                                 ok: true,
                                 tool_use_id: innerId,
@@ -1964,6 +2314,8 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                                             signal,
                                             toolResponseStore: this.toolResponseStore,
                                             discoveredTools: this.discoveredTools,
+                                            backgroundWorkers: this.backgroundWorkers,
+                                            leadBrief: { task: this.turnInstruction, environment: this.runtimeContext ?? undefined },
                                             availableTools: this.config.tools,
                                             subprocessEnv: this.copySubprocessEnv(),
                                             commandPolicy: this.commandPolicy,
@@ -1995,6 +2347,8 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                                         signal,
                                         toolResponseStore: this.toolResponseStore,
                                         discoveredTools: this.discoveredTools,
+                                        backgroundWorkers: this.backgroundWorkers,
+                                        leadBrief: { task: this.turnInstruction, environment: this.runtimeContext ?? undefined },
                                         availableTools: this.config.tools,
                                         subprocessEnv: this.copySubprocessEnv(),
                                         commandPolicy: this.commandPolicy,
@@ -2028,9 +2382,26 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         }
                     }, result => result.toolCall.status === 'error' || result.managedCommand?.result.status === 'running'
                         || commandStillRunning(result.toolResult.content), signal, exclusiveTransitionId);
-                    // Real work happened, so the turn has demonstrably not stalled on
-                    // narration: give it a fresh continuation budget.
-                    this._consecutiveAutoContinues = 0;
+                    const changedState = combined.every(result => result.toolCall.status === 'complete' && !result.toolResult.is_error)
+                        && combined.some(result => {
+                            const tool = this.config.tools.find(candidate => candidate.definition.name === result.toolCall.name);
+                            if (tool === undefined || resolveToolEffect(tool) === 'read')
+                                return false;
+                            const command = typeof result.toolCall.args?.command === 'string' ? result.toolCall.args.command : undefined;
+                            if (command === undefined)
+                                return true;
+                            if (this._turnCommandsRun.has(command))
+                                return false;
+                            this._turnCommandsRun.add(command);
+                            return true;
+                        });
+                    this._turnToolChangedState = changedState;
+                    if (changedState) {
+                        this._consecutiveAutoContinues = 0;
+                        this._turnCheckAsked = false;
+                    }
+                    if (changedState)
+                        this._turnToolBatches += 1;
                     // Add assistant message with tool use
                     const textContent = this.remoteResourceSession
                         ? combined.filter(result => result.toolCall.name === 'remote_resource' && result.toolCall.status === 'complete')
@@ -2088,10 +2459,6 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                             break;
                         }
                     }
-                    // Break the loop for interactive tools (ask_user, submit_plan) — the TUI
-                    // needs control to show the user interaction widget. Without this break,
-                    // auto-continue (shouldContinue) can keep looping if there are pending todos.
-                    // Only break if the interactive tool actually succeeded (not an error).
                     const hasSuccessfulInteractiveTool = toolUseBlocks.some(tb => {
                         if (!Agent.TURN_ENDING_TOOLS.has(tb.name))
                             return false;
@@ -2102,6 +2469,14 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         stopReason = 'interactive';
                         break;
                     }
+                    const resolvedTurn = toolUseBlocks.some(tb => {
+                        if (!Agent.SELF_RESOLVING_TOOLS.has(tb.name))
+                            return false;
+                        const result = completedResults.get(tb.id);
+                        return result ? !result.content.startsWith('Error:') : false;
+                    });
+                    if (resolvedTurn)
+                        this._turnToolBatches = 0;
                     // A busy user message belongs after the completed tool-use/result pair
                     // and before the next inference. Keep terminal tools and exhausted turns
                     // on the normal next-turn path because no model request remains here.
@@ -2155,6 +2530,35 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                                 throw new AgentError('Cancelled', 'CANCELLED');
                         }
                     }
+                    if (this.onMidTurnCompact && shouldCompactMidTurn({
+                        usedTokens: contextTokens > 0 ? contextTokens : estimateConversationTokens(messages),
+                        windowTokens: getContextWindowSize(this.config.model, this.midTurnCompactWindow !== undefined ? this.midTurnCompactWindow : usage.contextWindow),
+                        thresholdPercent: this.midTurnCompactThresholdPercent ?? 90,
+                        tokenBudget: this.midTurnCompactTokenBudget,
+                        reservedOutputTokens: clampCompletionTokens(this.config.model, this.config.maxTokens
+                            ?? this.backend.getModelCapabilities?.(this.config.model)?.max_output_tokens),
+                        messagesSinceLastCompaction: midTurnMessagesSinceCompaction,
+                        lastFreedTokens: midTurnLastFreedTokens,
+                        enabled: true,
+                    })) {
+                        try {
+                            const before = estimateConversationTokens(messages);
+                            const compacted = await this.onMidTurnCompact({ messages: [...messages], usedTokens: contextTokens, windowTokens: usage.contextWindow, signal });
+                            if (compacted && compacted.length > 0) {
+                                const after = estimateConversationTokens(compacted);
+                                messages.length = 0;
+                                messages.push(...compacted);
+                                turnMessages.length = 0;
+                                turnMessages.push(...compacted);
+                                midTurnLastFreedTokens = before - after;
+                                midTurnMessagesSinceCompaction = 0;
+                                this.emit({ type: 'history_checkpoint', messages: [...turnMessages], replacesHistory: true });
+                            }
+                        }
+                        catch (error) {
+                            this.emit({ type: 'error', error: `Mid-turn compaction failed: ${error.message}` });
+                        }
+                    }
                 }
                 catch (err) {
                     const error = err.message;
@@ -2179,6 +2583,8 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
             throw err;
         }
         finally {
+            // Workers still running when the run ends have no lead left to read their reports.
+            this.backgroundWorkers.stopAll();
             // Stop fires on every exit path — clean completion, cancel, API error,
             // and exhausted maxIterations. Without this, any error in the run loop
             // silently skipped Stop, leaving teardown hooks (e.g. `notify me when
@@ -2208,6 +2614,8 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
             usage: totalUsage || undefined,
             stopReason,
             ...(finalReasoning ? { reasoning: finalReasoning } : {}),
+            responseItems: finalResponseItems,
+            ...(finalResponseItems ? { nativeModel: this.config.model } : {}),
             ...(finalNativeContent ? { nativeContent: finalNativeContent, nativeModel: this.config.model, nativeContextId: this._nativeContextId } : {}),
             turnMessages,
         };
@@ -2295,7 +2703,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         };
         const toolResultMessage = {
             id: `tool_${randomUUID()}`, role: 'user', content: '[]', timestamp: new Date(),
-            metadata: { toolResult: true, toolCheckpoint: true },
+            metadata: { toolResult: true, toolCheckpoint: true, preserveUserBoundary: true },
         };
         owner.messages.push(toolUseMessage);
         owner.turnMessages.push(toolUseMessage);
@@ -2316,6 +2724,8 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     onUsage: options.onUsage,
                     toolResponseStore: this.toolResponseStore,
                     discoveredTools: this.discoveredTools,
+                    backgroundWorkers: this.backgroundWorkers,
+                    leadBrief: { task: this.turnInstruction, environment: this.runtimeContext ?? undefined },
                     availableTools: this.config.tools,
                     subprocessEnv: this.copySubprocessEnv(),
                     commandPolicy: this.commandPolicy,
@@ -2450,7 +2860,9 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         const useStream = process.env.ZTC_NO_STREAM !== '1' && !this.backend.streamsSyntheticallyFor?.(request);
         let answerOutputEmitted = false;
         let effectObserved = false;
+        let freshTurnRetried = false;
         let recoveryStartedAt;
+        let rateLimitedAttempts = 0;
         let lastReason = 'Server temporarily unavailable';
         const canRegenerate = () => this.backend.allowsRequestRetryAfterFailure?.(request) !== false;
         const returned = (response) => { onReturnedResponse?.(response); return response; };
@@ -2467,6 +2879,7 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
             const attemptController = new AbortController();
             let providerAttemptActive = true;
             let timedOut = false;
+            let streamingAttempt = useStream;
             let removeAbortListener;
             // Inactivity guard, not a total-duration cap: harness-owning backends
             // (Codex App Server) run their whole tool loop inside ONE request, so a
@@ -2569,11 +2982,14 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         // attempt — never regress a turn just because generateStream can't
                         // serve this request.
                         if (this.backend.allowsBufferedFallbackAfterStreamFailure?.(guardedRequest) === false
+                            || isIncompleteStreamError(streamErr)
                             || !canRegenerate() || effectObserved || answerOutputEmitted || timedOut || signal?.aborted
+                            || streamErr instanceof RunawayOutputError
                             || (streamErr instanceof AgentError && streamErr.code === 'CANCELLED')) {
                             throw streamErr;
                         }
                         this._lastResponseStreamed = false;
+                        streamingAttempt = false;
                         return await Promise.race([
                             this.backend.generate(guardedRequest).then(response => {
                                 if (response.usage)
@@ -2603,24 +3019,46 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     this.nativeEvidenceFailure ??= new AgentError(err.message, 'NATIVE_OBSERVATION_LIMIT');
                     throw this.nativeEvidenceFailure;
                 }
+                // Router keeps producing a turn after the client leaves, up to the model's
+                // output limit: stop reading and stop generation for every abandoned one.
+                if (err instanceof RunawayOutputError || timedOut || signal?.aborted
+                    || (err instanceof AgentError && err.code === 'CANCELLED')) {
+                    attemptController.abort();
+                    void this.backend.cancelTurn?.(guardedRequest).catch(() => undefined);
+                }
                 if (err instanceof AgentError && err.code === 'CANCELLED') {
                     throw err;
                 }
                 if (signal?.aborted) {
                     throw new AgentError('Cancelled', 'CANCELLED');
                 }
+                if (err instanceof RunawayOutputError)
+                    throw err;
                 const error = err;
-                if (timedOut) {
-                    throw new AgentError('LLM request timed out. Try again, reduce tool output, or raise ZTC_LLM_REQUEST_TIMEOUT_MS if this model needs longer.', 'API_TIMEOUT');
-                }
-                // A streaming attempt that already emitted answer text can't be retried
-                // — re-streaming would duplicate that text in the UI. Fail the turn
-                // instead. (Connect-time failures, and failures during the reasoning
-                // phase only, still retry.)
-                if (effectObserved || !canRegenerate() || useStream && answerOutputEmitted) {
+                if (effectObserved || !canRegenerate() || timedOut && !streamingAttempt) {
+                    if (isIncompleteStreamError(error)) {
+                        throw new AgentError(INCOMPLETE_MODEL_RESPONSE_MESSAGE, INCOMPLETE_MODEL_RESPONSE_CODE);
+                    }
+                    if (timedOut) {
+                        throw new AgentError('LLM request timed out. Try again, reduce tool output, or raise ZTC_LLM_REQUEST_TIMEOUT_MS if this model needs longer.', 'API_TIMEOUT');
+                    }
                     throw new AgentError(this.parseAPIError(error).reason, 'API_ERROR');
                 }
-                const { retryable, reason, kind } = this.parseAPIError(error);
+                if (useStream && answerOutputEmitted) {
+                    this.emit({ type: 'stream_reset' });
+                    answerOutputEmitted = false;
+                }
+                const stalled = timedOut;
+                const { retryable, reason, kind } = stalled
+                    ? { retryable: true, reason: 'LLM request stalled without activity', kind: undefined }
+                    : this.parseAPIError(error);
+                // The Router lost this turn's producer before any answer text: nothing ran and nothing was
+                // shown, so ask once more under a new turn id (resuming the lost turn cannot work).
+                if (kind === 'stream_lost' && !isIncompleteStreamError(error) && attempt < maxAttempts && !freshTurnRetried && request.transportTurnId !== undefined) {
+                    freshTurnRetried = true;
+                    request = { ...request, transportTurnId: randomUUID() };
+                    continue;
+                }
                 // Transport failures deliberately fall through to the normal retryable
                 // path even when the backend owns transport reconnects. The backend has
                 // already spent its bounded reconnect budget by the time control reaches
@@ -2628,19 +3066,34 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                 // attempt resumes the same Router-buffered turn instead of appending a
                 // duplicate. Only a failure AFTER answer text is unrecoverable, and the
                 // answerOutputEmitted guard above already handled that case.
-                if (!retryable || maxAttempts === 1 || attempt >= maxAttempts && recoveryWindowMs === 0) {
+                if (!retryable || maxAttempts === 1
+                    || attempt >= maxAttempts && (recoveryWindowMs === 0 || stalled || isIncompleteStreamError(error))) {
                     if (kind === 'context_overflow') {
                         throw new ContextOverflowError(reason, request, error.message);
                     }
+                    if (stalled) {
+                        throw new AgentError('LLM request timed out. Try again, reduce tool output, or raise ZTC_LLM_REQUEST_TIMEOUT_MS if this model needs longer.', 'API_TIMEOUT');
+                    }
+                    if (isIncompleteStreamError(error)) {
+                        throw new AgentError(INCOMPLETE_MODEL_RESPONSE_MESSAGE, INCOMPLETE_MODEL_RESPONSE_CODE);
+                    }
                     throw new AgentError(reason, 'API_ERROR');
                 }
+                if (isIncompleteStreamError(error) && request.transportTurnId !== undefined) {
+                    request = { ...request, transportTurnId: randomUUID() };
+                }
+                rateLimitedAttempts = kind === 'rate_limit' ? rateLimitedAttempts + 1 : 0;
+                if (rateLimitedAttempts >= RATE_LIMITED_ATTEMPTS) {
+                    throw new AgentError(`${reason.replace(/\.?\s*$/, '.')} Still rate-limited after ${rateLimitedAttempts} attempts, so ZTC `
+                        + 'stopped retrying. Send a message to try again, or choose another model with /model.', 'API_ERROR');
+                }
                 lastReason = reason;
                 const recovering = attempt >= maxAttempts;
                 if (recovering)
                     recoveryStartedAt ??= Date.now();
                 const elapsedMs = recoveryStartedAt === undefined ? 0 : Math.max(0, Date.now() - recoveryStartedAt);
                 if (recovering && recoveryWindowMs !== null && elapsedMs >= recoveryWindowMs) {
-                    throw new AgentError(reason, 'API_ERROR');
+                    throw new AgentError(reason, stalled ? 'API_TIMEOUT' : 'API_ERROR');
                 }
                 // Keep the exact pending inference alive. Never resubmit the user turn
                 // or revisit already checkpointed tool results to recover an endpoint.
@@ -2673,6 +3126,12 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
     }
     // Parse API error to determine if retryable and extract user-friendly message
     parseAPIError(error) {
+        if (isIncompleteStreamError(error)) {
+            return { retryable: true, reason: error.message, kind: 'stream_lost' };
+        }
+        // ZTC refused the request before sending it, in words meant for the person.
+        if (error instanceof RequestRefusedError)
+            return { retryable: false, reason: error.message };
         // A provider may embed an oversized/malformed diagnostic in an Error.
         // Keep all parsing bounded even for transports with their own error type.
         const message = error.message.slice(0, 64 * 1024);
@@ -2686,6 +3145,11 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         let errorCode = '';
         let errorMessage = '';
         let admissionMessage = '';
+        let admissionCode = '';
+        // OpenRouter answers "Provider returned error" and nests the upstream provider's own error, as a JSON string, in
+        // error.metadata.raw. That nested message is the one a person can act on.
+        let providerName = '';
+        let upstreamMessage = '';
         try {
             // Provider envelopes start with an object after the diagnostic prefix.
             // Index searches avoid a greedy regex restarting at every forged colon.
@@ -2701,6 +3165,13 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                     errorType = errorPayload.type || errorPayload.status || '';
                     errorCode = typeof errorPayload.code === 'string' ? errorPayload.code : '';
                     errorMessage = errorPayload.message || '';
+                    const metadata = errorPayload.metadata;
+                    if (metadata && typeof metadata === 'object') {
+                        if (typeof metadata.provider_name === 'string')
+                            providerName = metadata.provider_name;
+                        if (typeof metadata.raw === 'string')
+                            upstreamMessage = nestedProviderMessage(metadata.raw);
+                    }
                 }
                 if (!errorMessage && typeof parsed.detail === 'string') {
                     errorMessage = parsed.detail;
@@ -2721,15 +3192,28 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
                         admissionMessage = parsed.message;
                     else if (typeof parsed.statusMessage === 'string')
                         admissionMessage = parsed.statusMessage;
+                    if (typeof parsed.data?.code === 'string')
+                        admissionCode = parsed.data.code;
                 }
             }
         }
         catch {
             // Not valid JSON, use raw message
         }
+        // The provider's own words, shown so a person can act on them. The HTTP layer already redacted credentials from
+        // its body; an error raised outside it is redacted here.
+        const httpError = error instanceof BackendHttpError;
+        // An error with no HTTP status (a broken stream, a backend's own failure) is its message.
+        const body = httpError ? error.body : /API error \(\d+\): ([\s\S]*)$/.exec(message)?.[1] ?? (statusCode === 0 ? message : '');
+        const providerSource = upstreamMessage || (typeof errorMessage === 'string' ? errorMessage : '') || (body.trimStart().startsWith('{') ? '' : body);
+        const providerText = (httpError ? providerSource : redactErrorText(providerSource)).replace(/\s+/g, ' ').trim();
+        const providerDetail = providerText.length > PROVIDER_DETAIL_CHARS ? `${providerText.slice(0, PROVIDER_DETAIL_CHARS - 1)}…` : providerText;
+        // A message that only repeats the heading ("Invalid request: Invalid request") adds nothing.
+        const withProviderDetail = (base) => `${base}${providerName ? ` from ${providerName}` : ''}`
+            + (providerDetail && providerDetail.replace(/\.$/, '').toLowerCase() !== base.toLowerCase() ? `: ${providerDetail}` : '');
         if (statusCode === 410 && message.startsWith('ZRouter API error (')
             && ['stream_producer_lost', 'stream_producer_failed', 'stream_resume_expired'].includes(errorCode)) {
-            return { retryable: false, reason: 'The Router stream was interrupted and cannot be resumed. '
+            return { retryable: false, kind: 'stream_lost', reason: 'The Router stream was interrupted and cannot be resumed. '
                     + 'Send a message to continue from the existing conversation.' };
         }
         // Detected before the generic 400 bucket so the host can dump the request.
@@ -2740,16 +3224,28 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         if (statusCode === 529 || errorType === 'overloaded_error') {
             return { retryable: true, reason: 'API is overloaded' };
         }
+        // Router usage controls refuse before dispatch. A spending or token limit
+        // lasts until its window resets, so retrying only delays the explanation;
+        // the concurrency limit is temporary and stays a retryable rate limit.
+        if (statusCode === 429 && admissionMessage && LASTING_ROUTER_USAGE_LIMITS.has(admissionCode)) {
+            return { retryable: false, reason: `${admissionMessage.replace(/\.?\s*$/, '.')} `
+                    + 'Wait for the limit to reset, or ask a Zerg Router administrator to raise it.' };
+        }
+        // Router words every OpenRouter rate limit itself, so its message is public. A used-up daily
+        // free-model quota lasts until the day resets; retrying only spends what is left of it.
+        const routerRateLimit = statusCode === 429 && message.startsWith('ZRouter API error (')
+            && ROUTER_RATE_LIMIT_CODES.has(errorCode) && /^OpenRouter(?:'s)? /.test(errorMessage) ? errorMessage.trim() : '';
+        if (routerRateLimit && errorCode === 'free_model_daily_limit') {
+            return { retryable: false, reason: `${routerRateLimit.replace(/\.?\s*$/, '.')} Choose another model with /model, or wait for the limit to reset.` };
+        }
         if (statusCode === 429 || errorType === 'rate_limit_error' || errorType === 'RESOURCE_EXHAUSTED') {
-            return { retryable: true, reason: 'Rate limit exceeded', kind: 'rate_limit' };
+            return { retryable: true, reason: routerRateLimit || 'Rate limit exceeded', kind: 'rate_limit' };
         }
         if (statusCode === 504 || statusCode === 503 || statusCode === 502 || statusCode === 500 || errorType === 'UNAVAILABLE' || errorType === 'INTERNAL') {
-            // Only Router admission guidance is public. Provider diagnostics stay
-            // private; a bounded response-header ID supplies support correlation.
+            // A bounded response-header ID supplies support correlation beside the provider's message.
             const requestId = /(?:fly-request-id|x-request-id)=([A-Za-z0-9._:-]{1,128})(?:[ \]]|$)/.exec(message)?.[1];
-            const detail = [admissionMessage.trim().replace(/\s+/g, ' '), requestId && `request_id: ${requestId}`].filter(Boolean).join('; ');
-            const cause = detail ? `: ${detail.length > 160 ? `${detail.slice(0, 159)}…` : detail}` : '';
-            return { retryable: true, reason: `Upstream server error (${statusCode || 'no status'})${cause}` };
+            const base = withProviderDetail(`Upstream server error (${statusCode || 'no status'})`);
+            return { retryable: true, reason: requestId ? `${base}${providerDetail ? ';' : ':'} request_id: ${requestId}` : base };
         }
         // Non-retryable errors with clean messages
         if (statusCode === 401 || errorType === 'authentication_error' || errorType === 'UNAUTHENTICATED') {
@@ -2777,13 +3273,26 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         // Keep the Router's setup failure actionable without echoing arbitrary
         // remote bodies. Only these known provider names can enter the message.
         const missingRouterKey = typeof errorMessage === 'string'
-            ? errorMessage.match(/^No API key available for provider: (anthropic|openai|gemini|deepseek|kimi|modal|inception|clarifai)$/)
+            ? errorMessage.match(/^No API key available for provider: (anthropic|openai|gemini|deepseek|kimi|modal|inception|clarifai|openrouter|fireworks)$/)
             : null;
         if (statusCode === 400 && message.startsWith('ZRouter API error (') && missingRouterKey) {
-            return { retryable: false, reason: `No API key available for provider: ${missingRouterKey[1]}. Configure that provider in Zerg Router.` };
+            const provider = missingRouterKey[1];
+            // Modal runs only on Zerg's own key, so another model is the only way on.
+            return { retryable: false, reason: provider === 'modal'
+                    ? 'Zerg Router has no key for modal, so it cannot run this model. Choose another model with /model.'
+                    : `Zerg Router has no key for ${provider}. Add one in Zerg Router, or choose another model with /model.` };
+        }
+        // OpenRouter choices that leave no provider: Router names the cause, and it stays until changed.
+        const openRouterNext = admissionCode === 'openrouter_limits_unmet'
+            ? 'Loosen them on the reasoning page (/effort) or with /config openrouter limit.'
+            : admissionCode === 'openrouter_pinned_unsupported'
+                ? 'Choose another provider on the reasoning page (/effort).'
+                : admissionCode === 'openrouter_parameters_unsupported' ? 'Choose another model with /model.' : null;
+        if (statusCode === 400 && message.startsWith('ZRouter API error (') && openRouterNext && admissionMessage) {
+            return { retryable: false, reason: `${admissionMessage.replace(/\.?\s*$/, '.')} ${openRouterNext}` };
         }
         if (statusCode === 400 || errorType === 'invalid_request_error' || errorType === 'INVALID_ARGUMENT') {
-            return { retryable: false, reason: 'Invalid request' };
+            return { retryable: false, reason: withProviderDetail('Invalid request') };
         }
         // Transport-layer network failures (R8/F10): a raw `fetch failed` / ECONNRESET
         // carries no `API error (NNN)` status and no JSON body, so it reaches here and
@@ -2798,9 +3307,24 @@ INVESTIGATION STRATEGY — before making tool calls to explore or debug, follow
         if (statusCode === 0 && isTransportMessageError(error)) {
             return { retryable: true, reason: 'Network error reaching the LLM endpoint', kind: 'transport' };
         }
-        // Provider failures can echo request headers, credentials, prompts, or host
-        // paths. Keep the raw detail inside the provider boundary.
-        return { retryable: false, reason: 'Provider request failed.' };
+        return { retryable: false, reason: providerDetail || providerName ? withProviderDetail('Provider request failed') : 'Provider request failed.' };
     }
 }
+/** The longest provider message an error shows, on one line. */
+const PROVIDER_DETAIL_CHARS = 300;
+/** The message inside a provider's raw error body: Anthropic's error.message, a bare message, or the text itself. */
+function nestedProviderMessage(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        const nested = parsed?.error;
+        if (typeof nested?.message === 'string')
+            return nested.message;
+        if (typeof nested === 'string')
+            return nested;
+        if (typeof parsed?.message === 'string')
+            return parsed.message;
+    }
+    catch { /* not JSON: the raw text is the message */ }
+    return raw;
+}
 export default Agent;