chainlesschain 0.166.130 → 0.166.132

package/src/runtime/agent-core.js

@@ -1,3 +1,4 @@
+import { projectMessagesWithTaskBinding } from "./message-roles.js";
 import {
   providerFetch,
   requireUnscopedToolExecution,
@@ -28,6 +29,7 @@ import { resolveLlmConnection } from "../lib/llm-connection-resolution.js";
  */
 
 import fs from "fs";
+import { isDeepStrictEqual } from "node:util";
 import { isUtf8 } from "node:buffer";
 import {
   _isNonNegativeSafeInteger,
@@ -216,6 +218,19 @@ import {
   buildToolAttribution,
 } from "../lib/agent-tool-admission.js";
 import { captureAgentExecutionPolicy } from "../lib/agent-execution-policy.js";
+import { ephemeralWorktreeConsumerRefusal } from "../lib/ephemeral-worktree-scope.js";
+import {
+  COMPACTION_CONTEXT_REFRESH_ERROR,
+  refreshCompactionHostContext,
+} from "./compaction-host-context.js";
+import {
+  assertMcpCatalogBinding,
+  captureMcpToolCatalog,
+  mergeMcpToolCatalog,
+  projectMcpToolCatalog,
+  readMcpToolCatalog,
+  restrictMcpToolCatalog,
+} from "../lib/mcp-tool-catalog-authority.js";
 import {
   evaluateUnattendedToolAction,
   evaluateUnattendedGitAction,
@@ -259,6 +274,8 @@ import { isMcpRpcError } from "../harness/mcp-client.js";
 import {
   projectCanonicalResumeMessages,
   markRuntimeOnlySessionMessage,
+  isRuntimeOnlySessionMessage,
+  encodePersistedMessage,
 } from "../lib/session-message-provenance.js";
 import { releaseOldLiveSessionResults } from "../lib/session-runtime-retention.js";
 import {
@@ -4040,6 +4057,8 @@ export async function executeTool(name, args, context = {}) {
       externalToolDescriptors: context.externalToolDescriptors || null,
       externalToolExecutors: context.externalToolExecutors || null,
       mcpClient: context.mcpClient || null,
+      mcpToolCatalog: context.mcpToolCatalog || null,
+      mcpCatalogBinding: context.mcpCatalogBinding || null,
       mcpHostClient: context.mcpHostClient || context.mcpClient || null,
       mcpCallLedger: context.mcpCallLedger || null,
       mcpConflictScheduler: context.mcpConflictScheduler || null,
@@ -5656,6 +5675,8 @@ async function executeToolInner(
     externalToolExecutors,
     extraToolDefinitions = null,
     mcpClient,
+    mcpToolCatalog = null,
+    mcpCatalogBinding = null,
     mcpHostClient = mcpClient,
     mcpCallLedger = null,
     mcpConflictScheduler = null,
@@ -6221,6 +6242,10 @@ async function executeToolInner(
       // Bound the declared run_shell data once. Approval and dispatch never
       // observe later mutation of the caller-owned tool arguments.
       args = Object.isFrozen(args) ? args : snapshotShellExecutionArgs(args);
+      if (args.run_in_background === true) {
+        const refusal = ephemeralWorktreeConsumerRefusal("Background shell");
+        if (refusal) return attachDescriptor(refusal);
+      }
       if (unattendedActionPolicy?.unattended === true) {
         const unattendedVerdict = evaluateUnattendedShellAction(args.command, {
           ...unattendedActionPolicy,
@@ -7888,6 +7913,8 @@ async function executeToolInner(
           // filtered by the resolved contract's mcpServers allow-list.
           mcpClient,
           mcpHostClient,
+          mcpToolCatalog,
+          mcpCatalogBinding,
           mcpCallLedger,
           mcpConflictScheduler,
           mcpDispatchAdmission,
@@ -8243,6 +8270,14 @@ async function executeToolInner(
     }
 
     case "schedule": {
+      if (
+        ["wakeup", "cron", "monitor"].includes(
+          String(args.action || "").toLowerCase(),
+        )
+      ) {
+        const refusal = ephemeralWorktreeConsumerRefusal("Deferred schedule");
+        if (refusal) return attachDescriptor(refusal);
+      }
       try {
         const { AgentScheduleStore } = await import(
           "../lib/agent-schedule-store.js"
@@ -8992,6 +9027,16 @@ async function executeToolInner(
         });
       }
 
+      if (match.isolation === true) {
+        const refusal = ephemeralWorktreeConsumerRefusal(
+          "Isolated skill child",
+        );
+        if (refusal) {
+          skillExecutionLease?.release?.();
+          return attachDescriptor(refusal);
+        }
+      }
+
       const selectedSkillDigest =
         match.executionIdentity?.contentDigest ||
         `sha256:${createHash("sha256").update(admittedSkillBody).digest("hex")}`;
@@ -9676,6 +9721,11 @@ async function executeToolInner(
       // MCP tool schemas from the registry attached at setup time. Read-only,
       // local — same risk class as list_skills, so no approval gate.
       if (localToolExecutor?.kind === "tool-search") {
+        try {
+          assertMcpCatalogBinding(mcpCatalogBinding, name);
+        } catch (error) {
+          return attachDescriptor({ error: error.message, code: error.code });
+        }
         return attachDescriptor(
           executeToolSearch(localToolExecutor.registry, args || {}, {
             allowedToolNames: effectiveAllowedToolNames,
@@ -9722,6 +9772,11 @@ async function executeToolInner(
       }
 
       if (localToolExecutor?.kind === "mcp") {
+        try {
+          assertMcpCatalogBinding(mcpCatalogBinding, name);
+        } catch (error) {
+          return attachDescriptor({ error: error.message, code: error.code });
+        }
         if (!mcpClient || typeof mcpClient.callTool !== "function") {
           return attachDescriptor({
             error: `MCP client is unavailable for tool: ${name}`,
@@ -9757,6 +9812,18 @@ async function executeToolInner(
         }
 
         const schedulerScopes = mcpLedgerScopes(mcpWireInput);
+        const catalogDispatchAdmission = mcpCatalogBinding
+          ? (metadata, dispatch) => {
+              assertMcpCatalogBinding(mcpCatalogBinding, name);
+              const admittedDispatch = () => {
+                assertMcpCatalogBinding(mcpCatalogBinding, name);
+                return dispatch();
+              };
+              return mcpDispatchAdmission
+                ? mcpDispatchAdmission(metadata, admittedDispatch)
+                : admittedDispatch();
+            }
+          : mcpDispatchAdmission;
         const ledgerEffectContract = mcpLedgerEffectContract(
           localToolDescriptor,
           hostToolPolicy,
@@ -9869,16 +9936,17 @@ async function executeToolInner(
 
           let pendingResult;
           try {
+            assertMcpCatalogBinding(mcpCatalogBinding, name);
             const callArguments = [
               localToolExecutor.serverName,
               localToolExecutor.toolName,
               mcpWireInput,
             ];
-            if (signal || mcpDispatchAdmission || workflowEffectId) {
+            if (signal || catalogDispatchAdmission || workflowEffectId) {
               callArguments.push({
                 ...(signal ? { signal } : {}),
-                ...(mcpDispatchAdmission
-                  ? { dispatchAdmission: mcpDispatchAdmission }
+                ...(catalogDispatchAdmission
+                  ? { dispatchAdmission: catalogDispatchAdmission }
                   : {}),
                 ...(workflowEffectId
                   ? {
@@ -11164,6 +11232,13 @@ async function _executeSpawnSubAgent(args, ctx) {
     };
   }
 
+  const wantsBackground =
+    args.background === true || effectiveContract?.background === true;
+  if (wantsBackground) {
+    const refusal = ephemeralWorktreeConsumerRefusal("Background sub-agent");
+    if (refusal) return refusal;
+  }
+
   // Filter the parent loop's live MCP plumbing + settings hooks down to what the
   // child may inherit. Default `[]` → null → the spawn passes nothing, so a plain
   // sub-agent is byte-identical to before.
@@ -11262,6 +11337,9 @@ async function _executeSpawnSubAgent(args, ctx) {
 
   // A child can never regain a tool omitted from the parent's effective schema.
   // `[]` remains deny-all all the way into the child's execution-time fence.
+  let requestedMcpTools = Array.isArray(allowedTools)
+    ? Object.freeze([...allowedTools])
+    : null;
   if (Array.isArray(ctx.effectiveAllowedToolNames)) {
     const parentCeiling = new Set(ctx.effectiveAllowedToolNames);
     const requested = Array.isArray(allowedTools)
@@ -11302,6 +11380,7 @@ async function _executeSpawnSubAgent(args, ctx) {
       const perm = resolvePermissionMode(effectiveContract.permissionMode);
       if (perm.readOnly) {
         allowedTools = resolveEnabledTools({ allowedTools, readOnly: true });
+        requestedMcpTools = allowedTools;
       }
       // autopilot ⟺ bypassPermissions — the only mode whose headless confirmer
       // ALLOWS. Threading a deny confirmer would needlessly disable the child's
@@ -11326,6 +11405,29 @@ async function _executeSpawnSubAgent(args, ctx) {
     }
   }
 
+  let childMcpCatalog = null;
+  if (
+    ctx.mcpToolCatalog &&
+    !(Array.isArray(mcpAllow) && mcpAllow.length === 0)
+  ) {
+    try {
+      const { createInheritedMcpToolCatalog } = await import(
+        "../lib/subagent-inheritance.js"
+      );
+      childMcpCatalog = createInheritedMcpToolCatalog(
+        ctx,
+        mcpAllow,
+        requestedMcpTools,
+        allowedTools,
+      );
+      inheritedMcp = readMcpToolCatalog(childMcpCatalog);
+    } catch (error) {
+      return {
+        error: `spawn_sub_agent: live MCP inheritance failed closed (${error.message}).`,
+      };
+    }
+  }
+
   // Build a structured parent handoff if the caller did not provide explicit
   // An explicit `contextMode: fresh` contract suppresses this inheritance (the
   // child starts clean); `fork` / unset keep deterministic auto-inheritance.
@@ -11589,6 +11691,7 @@ async function _executeSpawnSubAgent(args, ctx) {
   const subCtx = SubAgentContext.create({
     role,
     task,
+    signal: ctx.signal || null,
     parentId: parentSessionId,
     // Hook-envelope tracing: the child loop stamps its own runId as trace_id
     // and THIS run's id as parent_id on every settings-hook payload it fires.
@@ -11659,6 +11762,7 @@ async function _executeSpawnSubAgent(args, ctx) {
     ...(inheritedMcp
       ? {
           extraToolDefinitions: inheritedMcp.extraToolDefinitions,
+          mcpToolCatalog: childMcpCatalog,
           externalToolDescriptors: inheritedMcp.externalToolDescriptors,
           externalToolExecutors: inheritedMcp.externalToolExecutors,
           mcpClient: inheritedMcp.mcpClient,
@@ -11788,8 +11892,6 @@ async function _executeSpawnSubAgent(args, ctx) {
   // detached without the caller passing it. `effectiveContract.background`
   // already folds in `args.background`; the explicit OR keeps the path
   // byte-identical if contract resolution was skipped (effectiveContract null).
-  const wantsBackground =
-    args.background === true || effectiveContract?.background === true;
   if (wantsBackground && ctx.backgroundSubAgents instanceof Map) {
     // Cancel with the parent: forward the loop's abort signal so killing the
     // run doesn't orphan a detached child mid-LLM-call.
@@ -12650,6 +12752,10 @@ export async function chatWithTools(rawMessages, options) {
     message.tool_calls = providerMessage.tool_calls;
   }
   const out = { message };
+  if (choice.finish_reason != null) {
+    out.finishReason = choice.finish_reason;
+    out.providerTerminationComplete = data.choices.length === 1;
+  }
   const providerReceipt = supportsOpenAIRequestIdentity
     ? _openAIProviderRequestReceipt(response, data, providerRequestId)
     : null;
@@ -14702,6 +14808,30 @@ function permissionDecision(callId, tool, result) {
 }
 
 export async function* agentLoop(messages, options) {
+  // Bind the actual task before compaction, runtime nudges or provider projection.
+  // A new host-admitted user turn starts a new loop and receives its own binding.
+  const currentUserTask = messages.findLast(
+    (message) =>
+      message?.role === "user" && !isRuntimeOnlySessionMessage(message),
+  );
+  const currentUserTaskSnapshot = currentUserTask
+    ? encodePersistedMessage(currentUserTask)
+    : null;
+  const currentUserTaskBinding = currentUserTaskSnapshot
+    ? {
+        message: currentUserTaskSnapshot,
+        original: currentUserTask,
+        allowContentRelocation:
+          messages.filter(
+            (message) =>
+              message?.role === "user" &&
+              isDeepStrictEqual(
+                encodePersistedMessage(message),
+                currentUserTaskSnapshot,
+              ),
+          ).length === 1,
+      }
+    : null;
   if (options.serviceTier != null) {
     resolveModelServiceTier(
       resolveModelCapabilityProfile(options),
@@ -14715,6 +14845,20 @@ export async function* agentLoop(messages, options) {
     ...options,
     ...executionPolicy,
   };
+  if (options.mcpToolCatalog != null) {
+    captureMcpToolCatalog(options.mcpToolCatalog);
+    // Host publication is the only live extension path. Do not let unrelated
+    // caller-owned startup arrays acquire new authority during a refresh.
+    options.extraToolDefinitions = Object.freeze([
+      ...(options.extraToolDefinitions || []),
+    ]);
+    options.externalToolDescriptors = Object.freeze({
+      ...options.externalToolDescriptors,
+    });
+    options.externalToolExecutors = Object.freeze({
+      ...options.externalToolExecutors,
+    });
+  }
   const configuredChatFn = options.chatFn;
   const evolutionIngress =
     options.evolutionIngress == null
@@ -14857,19 +15001,36 @@ export async function* agentLoop(messages, options) {
     );
   }
 
-  const effectiveToolOptions = hermeticExecution
+  const mcpToolCatalog = hermeticExecution
+    ? null
+    : captureMcpToolCatalog(options.mcpToolCatalog);
+  const loopMcpCatalog = mcpToolCatalog
+    ? projectMcpToolCatalog(mcpToolCatalog, (snapshot) =>
+        restrictMcpToolCatalog(
+          snapshot,
+          getEffectiveToolDefinitions(
+            mergeMcpToolCatalog(options, snapshot, mcpToolCatalog),
+          ).map((tool) => tool.function.name),
+        ),
+      )
+    : null;
+  let currentMcpSnapshot = readMcpToolCatalog(loopMcpCatalog);
+  let effectiveToolOptions = hermeticExecution
     ? {
         ...options,
         hostManagedToolPolicy: null,
         hostManagedToolPolicyAuthority: null,
         extraToolDefinitions: [],
       }
-    : options;
-  const effectiveAllowedToolNames = Object.freeze(
+    : currentMcpSnapshot
+      ? mergeMcpToolCatalog(options, currentMcpSnapshot, mcpToolCatalog)
+      : options;
+  let effectiveAllowedToolNames = Object.freeze(
     getEffectiveToolDefinitions(effectiveToolOptions).map(
       (tool) => tool.function.name,
     ),
   );
+  const startupToolNames = new Set(effectiveAllowedToolNames);
   if (
     fileMutationScope &&
     effectiveAllowedToolNames.some(
@@ -14951,6 +15112,10 @@ export async function* agentLoop(messages, options) {
       ? null
       : options.extraToolDefinitions || null,
     mcpClient: hermeticExecution ? null : options.mcpClient || null,
+    mcpToolCatalog: loopMcpCatalog,
+    mcpCatalogBinding: loopMcpCatalog
+      ? { authority: loopMcpCatalog, snapshot: currentMcpSnapshot }
+      : null,
     mcpHostClient: hermeticExecution
       ? null
       : options.mcpHostClient || options.mcpClient || null,
@@ -15251,6 +15416,8 @@ export async function* agentLoop(messages, options) {
   // one-shot guard means a model that keeps returning empty turns completes
   // rather than looping forever (the iteration budget is the hard backstop).
   let emptyThinkingReprompted = false;
+  let outputLimitRecoveryUsed = false;
+  let outputLimitRecoveryPending = null;
   let readFileLoopGuard = new ReadFileLoopGuard();
   let remoteReadLoopGuard = new RemoteReadLoopGuard();
   const prActionTask = isPrActionRequest(messages);
@@ -15267,6 +15434,39 @@ export async function* agentLoop(messages, options) {
   let lastTaskProgressIntervention = null;
 
   while (budget.hasRemaining()) {
+    if (loopMcpCatalog) {
+      currentMcpSnapshot = readMcpToolCatalog(loopMcpCatalog);
+      effectiveToolOptions = mergeMcpToolCatalog(
+        options,
+        currentMcpSnapshot,
+        mcpToolCatalog,
+      );
+      effectiveAllowedToolNames = Object.freeze(
+        getEffectiveToolDefinitions(effectiveToolOptions)
+          .map((tool) => tool.function.name)
+          .filter(
+            (name) =>
+              startupToolNames.has(name) ||
+              currentMcpSnapshot.identities.has(name),
+          ),
+      );
+      effectiveToolOptions = {
+        ...effectiveToolOptions,
+        enabledToolNames: effectiveAllowedToolNames,
+        exactToolNames: true,
+      };
+      Object.assign(toolContext, {
+        extraToolDefinitions: effectiveToolOptions.extraToolDefinitions,
+        externalToolDescriptors: effectiveToolOptions.externalToolDescriptors,
+        externalToolExecutors: effectiveToolOptions.externalToolExecutors,
+        mcpClient: effectiveToolOptions.mcpClient,
+        effectiveAllowedToolNames,
+        mcpCatalogBinding: {
+          authority: loopMcpCatalog,
+          snapshot: currentMcpSnapshot,
+        },
+      });
+    }
     // Yield only between complete tool batches. Keep all completed tool results
     // and settle child usage before the host accepts queued user steering.
     if (options.shouldYieldToUser?.() === true) {
@@ -15433,6 +15633,7 @@ export async function* agentLoop(messages, options) {
     // its full tool_call→tool_result cycle before we loop, so `messages` has no
     // dangling call; `preserveToolPairs` then guarantees compaction never
     // orphans a tool result. Best-effort — a failure never aborts the run.
+    let compactionHostContextRefreshed = false;
     if (
       !independentReviewContext?.active &&
       options.autoCompact !== false &&
@@ -15453,7 +15654,7 @@ export async function* agentLoop(messages, options) {
           // micro-compact may change the working input, but the durable CAS must
           // still compare against the transcript state that existed before any
           // in-memory compaction happened.
-          const authorityExpectedMessages = [...messages];
+          let authorityExpectedMessages = [...messages];
           let workingMessages = messages;
           let microStats = null;
           // Cheap surgical pre-pass (Claude-Code microcompact parity): build a
@@ -15516,6 +15717,22 @@ export async function* agentLoop(messages, options) {
               reason: preCompactReason,
             };
           }
+          if (!hermeticExecution && options.refreshCompactionContext != null) {
+            // Hooks may update project files. Preserve the original transcript
+            // comparison before replacing only the host-owned live system base.
+            if (!_sameMessageSnapshot(messages, authorityExpectedMessages)) {
+              throw _compactionSettlementError(
+                COMPACTION_CONTEXT_REFRESH_ERROR,
+                "Session messages changed before project context refresh",
+              );
+            }
+            workingMessages = refreshCompactionHostContext(
+              options.refreshCompactionContext,
+              workingMessages,
+            );
+            authorityExpectedMessages = [...messages];
+            compactionHostContextRefreshed = true;
+          }
           // Auto-pin (OPT-IN): when enabled, the original task (first user turn)
           // is pinned so compaction can't drop it. Off by default → no predicate
           // is passed and compaction is byte-identical to before.
@@ -15815,6 +16032,7 @@ export async function* agentLoop(messages, options) {
           }
         }
       } catch (_e) {
+        if (_e?.code === COMPACTION_CONTEXT_REFRESH_ERROR) throw _e;
         if (isAbortError(_e) || signal?.aborted) throw _e;
         if (isFormalBudgetError(_e)) throw _e;
         if (_e?.runtimeLedgerPersistence === true) throw _e;
@@ -15948,6 +16166,12 @@ export async function* agentLoop(messages, options) {
       }
     }
 
+    if (compactionHostContextRefreshed) {
+      // A source file can change while the summary provider is running, or
+      // while a failed summary is falling back to the original transcript.
+      refreshCompactionHostContext(options.refreshCompactionContext, messages);
+    }
+
     // Deliver background sub-agent results that settled since the last turn:
     // inject them as user-role context so THIS LLM call sees them. (There is
     // no open tool_call to attach a late result to — the spawn call already
@@ -16126,27 +16350,43 @@ export async function* agentLoop(messages, options) {
           index === resultIndex ? { ...result, content } : message,
         );
       } else {
-        // Full compaction can leave only the pinned request. Reiterate that
-        // exact request after the source data, not a replacement objective.
-        const request = requestMessages.findLast(
+        // Full compaction can leave only the pinned request. Move that same
+        // message after the source data, preserving its metadata and identity.
+        const requestIndex = requestMessages.findLastIndex(
           (message) => message.role === "user",
         );
+        const request = requestMessages[requestIndex];
         callMessages = [
-          ...requestMessages,
+          ...requestMessages.filter((_, index) => index !== requestIndex),
           ...readContext.map((content) => ({ role: "assistant", content })),
-          {
-            role: "user",
-            content: request?.content || "Continue the original user task.",
-          },
+          ...(request ? [request] : []),
         ];
       }
     }
     // Role normalization is request-only: durable history remains unchanged
     // for tool settlement and canonical compaction authority comparisons.
+    let projectedUserTaskBinding = currentUserTaskBinding;
     if (typeof options.projectProviderMessages === "function") {
-      callMessages = options.projectProviderMessages(callMessages);
+      const projected = projectMessagesWithTaskBinding(
+        options.projectProviderMessages,
+        callMessages,
+        currentUserTaskBinding,
+      );
+      callMessages = projected.messages;
+      projectedUserTaskBinding = projected.taskBinding;
     }
     const contextMemoryTrustedSystemIndexes = [];
+    if (outputLimitRecoveryPending !== null) {
+      // A synthetic user turn would replace the protected real task under
+      // canonical context pressure. Keep this one-request hint out of history
+      // and explicitly admit it as trusted system policy in the next plan.
+      callMessages = [
+        ...callMessages,
+        { role: "system", content: outputLimitRecoveryPending },
+      ];
+      contextMemoryTrustedSystemIndexes.push(callMessages.length - 1);
+      outputLimitRecoveryPending = null;
+    }
     if (Number.isFinite(budget.limit)) {
       // consume() already charged this dispatch. The current request may still
       // act even when no further provider request remains. Rebuild this hint
@@ -16306,6 +16546,11 @@ export async function* agentLoop(messages, options) {
           contextMemoryToolDefinitions:
             getProviderToolDefinitions(iterationToolOptions),
           contextMemoryTrustedSystemIndexes,
+          // Independent review uses its existing merged requirement journal and
+          // validates every original requirement after planning below.
+          contextMemoryRequiredUserBinding: independentReviewContext?.active
+            ? null
+            : projectedUserTaskBinding,
         },
       );
       if (canonicalProviderContext.plan) {
@@ -16571,6 +16816,78 @@ export async function* agentLoop(messages, options) {
       throw error;
     }
 
+    if (result?.finishReason === "content_filter") {
+      // Usage has settled above. A provider-filtered round is never a complete
+      // answer or an executable tool batch, and must not trigger a fresh call.
+      await _awaitBackgroundUsageSettlement(
+        backgroundSubAgents,
+        backgroundUsageFailureState,
+      );
+      const error = new Error(
+        "The provider filtered this response. No tools from that response were executed; the task remains incomplete.",
+      );
+      error.code = "CC_MODEL_CONTENT_FILTER";
+      throw error;
+    }
+
+    if (
+      result?.providerTerminationComplete === false &&
+      result.finishReason != null &&
+      result.finishReason !== "length"
+    ) {
+      // Explicit ambiguity is not an executable or final provider round.
+      // Keep absent-reason compatibility and the separate length policy.
+      await _awaitBackgroundUsageSettlement(
+        backgroundSubAgents,
+        backgroundUsageFailureState,
+      );
+      const error = new Error(
+        "The provider response has an incomplete or ambiguous termination. No tools from that response were executed; the task remains incomplete.",
+      );
+      error.code = "CC_MODEL_TERMINATION_INCOMPLETE";
+      throw error;
+    }
+
+    if (result?.finishReason === "length") {
+      // Settle the completed physical request above before any decision. Never
+      // execute even syntactically valid calls from an incomplete generation,
+      // and never insert its partial assistant/tool group into canonical history.
+      const canRecover =
+        result.providerTerminationComplete === true &&
+        !msg?._truncated &&
+        _hasCompleteProviderUsage(result.usage) &&
+        !outputLimitRecoveryUsed &&
+        budget.hasRemaining() &&
+        !prInvestigationExhausted &&
+        !inspectionSynthesisRequired;
+      if (!canRecover) {
+        await _awaitBackgroundUsageSettlement(
+          backgroundSubAgents,
+          backgroundUsageFailureState,
+        );
+        const error = new Error(
+          "Model output reached its token limit. No tools from that response were executed; the task remains incomplete.",
+        );
+        error.code = "CC_MODEL_OUTPUT_LIMIT";
+        throw error;
+      }
+      outputLimitRecoveryUsed = true;
+      outputLimitRecoveryPending =
+        "The previous model response reached its output token limit and was discarded. " +
+        "None of its tool calls were executed. Continue from the last confirmed tool results. " +
+        "Produce one small, complete operation per response. For large files, write a minimal " +
+        "complete scaffold first, then use separate small edit_file calls to add sections. " +
+        "Do not resend the entire large file or continue an unfinished JSON fragment. " +
+        "If no tools are needed, give a shorter complete answer.";
+      yield {
+        type: "iteration-warning",
+        message:
+          "Model output was truncated; requesting one smaller complete step within the remaining budget.",
+      };
+      // This is a fresh budgeted iteration with new input, never a transport retry.
+      continue;
+    }
+
     if (!msg) {
       await _awaitBackgroundUsageSettlement(
         backgroundSubAgents,

package/src/runtime/compaction-host-context.js

@@ -0,0 +1,72 @@
+import { getDurableSystemMessageProvenance } from "../lib/session-message-provenance.js";
+import { markCompactionHostBase } from "../lib/compaction-host-provenance.js";
+
+export const COMPACTION_CONTEXT_REFRESH_ERROR =
+  "CC_COMPACTION_CONTEXT_REFRESH_FAILED";
+
+/** Refresh only the base system message owned by this live host. */
+export function createCompactionHostContextRefresher({
+  messages,
+  render,
+  onUpdated,
+}) {
+  return (candidate = messages) => {
+    const current = messages[0];
+    if (
+      !current ||
+      current.role !== "system" ||
+      getDurableSystemMessageProvenance(current)
+    )
+      throw new Error("Live host base context is unavailable");
+    if (!Array.isArray(candidate) || !candidate.includes(current))
+      throw new Error(
+        "Compaction candidate does not contain the live host base context",
+      );
+    const content = render();
+    if (content && typeof content.then === "function") {
+      Promise.resolve(content).catch(() => {});
+      throw new TypeError("Host context rendering must be synchronous");
+    }
+    if (typeof content !== "string" || !content.trim())
+      throw new TypeError(
+        "Host context rendering must return a non-empty string",
+      );
+    if (messages[0] !== current)
+      throw new Error("Host base context changed during rendering");
+    if (content === current.content) {
+      markCompactionHostBase(current);
+      return candidate;
+    }
+    const replacement = markCompactionHostBase({ ...current, content });
+    const projected = candidate.map((message) =>
+      message === current ? replacement : message,
+    );
+    messages[0] = replacement;
+    onUpdated?.(replacement);
+    return candidate === messages ? messages : projected;
+  };
+}
+
+/** A failed refresh must not fall through to a model with obsolete rules. */
+export function refreshCompactionHostContext(refresh, messages) {
+  if (refresh == null) return messages;
+  try {
+    if (typeof refresh !== "function")
+      throw new TypeError("Invalid host context refresher");
+    const result = refresh(messages);
+    if (result && typeof result.then === "function") {
+      Promise.resolve(result).catch(() => {});
+      throw new TypeError("Host context refresh must be synchronous");
+    }
+    if (!Array.isArray(result))
+      throw new TypeError("Host context refresh must return messages");
+    return result;
+  } catch (cause) {
+    const error = new Error(
+      "Current project context could not be refreshed before continuing",
+      { cause },
+    );
+    error.code = COMPACTION_CONTEXT_REFRESH_ERROR;
+    throw error;
+  }
+}