@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/agent/loop.ts

@@ -1,34 +1,32 @@
 import * as Sentry from "@sentry/node";
 
 import type { LLMCallSite } from "../config/schemas/llm.js";
+import { stripInjectionsForCompaction } from "../context/strip-injections.js";
 import {
   estimatePromptTokensRaw,
+  estimatePromptTokensWithTools,
   estimateToolsTokens,
   getCalibrationProviderKey,
 } from "../context/token-estimator.js";
-import { calculateMaxToolResultChars } from "../context/tool-result-truncation.js";
+import type { ContextWindowResult } from "../context/window-manager.js";
 import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
-import { defaultEmptyResponseTerminal } from "../plugins/defaults/empty-response.js";
-import { defaultToolErrorTerminal } from "../plugins/defaults/tool-error.js";
-import { defaultToolResultTruncateTerminal } from "../plugins/defaults/tool-result-truncate.js";
-import { DEFAULT_TIMEOUTS, runPipeline } from "../plugins/pipeline.js";
-import { getMiddlewaresFor } from "../plugins/registry.js";
-import type {
-  EmptyResponseArgs,
-  EmptyResponseDecision,
-  LLMCallArgs,
-  LLMCallResult,
-  ToolErrorArgs,
-  ToolErrorDecision,
-  ToolResultTruncateArgs,
-  ToolResultTruncateResult,
-  TurnContext,
-} from "../plugins/types.js";
+import { HOOKS } from "../plugin-api/constants.js";
+import type { PostToolUseContext, StopContext } from "../plugin-api/types.js";
+import {
+  DEFAULT_COMPACTION_PLUGIN_NAME,
+  defaultCompact,
+} from "../plugins/defaults/compaction/compact.js";
+import type { PostCompactionHookInput } from "../plugins/defaults/memory-retrieval/hooks/post-compact.js";
+import { runHook } from "../plugins/pipeline.js";
+import type { CompactionCircuitEvent, TurnContext } from "../plugins/types.js";
+import { PluginExecutionError } from "../plugins/types.js";
 import { normalizeThinkingConfigForWire } from "../providers/thinking-config.js";
 import type {
   ContentBlock,
   Message,
   Provider,
+  ProviderResponse,
+  SendMessageOptions,
   ToolDefinition,
   ToolResultContent,
 } from "../providers/types.js";
@@ -37,12 +35,20 @@ import {
   applyStreamingSubstitution,
   applySubstitutions,
 } from "../tools/sensitive-output-placeholders.js";
-import { AssistantError, ErrorCode, ProviderError } from "../util/errors.js";
+import { ProviderError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import { isRetryableNetworkError } from "../util/retry.js";
+import { CompactionCircuit } from "./compaction-circuit.js";
 
 const log = getLogger("agent-loop");
 
+/** Fraction of the preflight budget at which a checkpoint triggers mid-loop compaction. */
+const MID_LOOP_YIELD_THRESHOLD_RATIO = 0.85;
+
+/** In-context message count above which the budget gate raises the safety-margin floor. */
+const LONG_HISTORY_MESSAGE_THRESHOLD = 50;
+const LONG_HISTORY_SAFETY_MARGIN_FLOOR = 0.15;
+
 export interface AgentLoopConfig {
   maxTokens: number;
   maxInputTokens?: number; // context window size for tool result truncation
@@ -66,7 +72,39 @@ export interface CheckpointInfo {
   history: Message[]; // current history snapshot for token estimation
 }
 
-export type CheckpointDecision = "continue" | "yield";
+/**
+ * Why a checkpoint paused the loop. Surfaced back to the caller via
+ * {@link AgentLoopRunResult.exitReason} so the orchestrator reacts to
+ * the loop's own signal (hand off to a queued message vs. compact and
+ * re-enter) instead of the checkpoint callback mutating orchestrator state.
+ */
+export type ExitReason = "handoff" | "budget";
+
+export type CheckpointDecision = "continue" | ExitReason;
+
+/** Result of {@link AgentLoop.run}. */
+export interface AgentLoopRunResult {
+  /** Full conversation history after the run, including everything appended this run. */
+  history: Message[];
+  /**
+   * Reason the loop paused at a checkpoint, or `null` on a terminal stop
+   * (completion, error, abort, or a tool-requested yield-to-user).
+   */
+  exitReason: ExitReason | null;
+  /**
+   * Whether the loop produced at least one new assistant message this run —
+   * the forward-progress signal for the ordering-error retry gate and the
+   * overflow convergence fold (immune to in-loop compaction shrinking history
+   * below a pre-run length).
+   */
+  appendedNewMessages: boolean;
+  /**
+   * Slice of `history` appended this run, measured from the loop's input or
+   * from the compacted base when it compacts in place. The loop owns this
+   * boundary, so it cannot desync the way an externally-held index can.
+   */
+  newMessages: Message[];
+}
 
 /**
  * Why an agent turn reached a terminal state.
@@ -89,8 +127,6 @@ export type CheckpointDecision = "continue" | "yield";
 export type AgentLoopExitReason =
   /** `if (signal?.aborted) break;` at the top of the loop. */
   | "aborted_pre_call"
-  /** Empty assistant response after the configured retry budget. */
-  | "empty_response_exhausted"
   /** Assistant message has no tool-use blocks (or no tool executor). */
   | "no_tool_calls"
   /** Signal aborted while building the user-side tool-results message. */
@@ -111,6 +147,8 @@ export type AgentLoopExitReason =
    * leaving `agent_loop_exit_reason` NULL.
    */
   | "budget_yield_unrecovered"
+  /** Provider stopped because the configured output-token limit was reached. */
+  | "max_tokens_reached"
   /** User cancellation landed after a non-terminal checkpoint yield. */
   | "aborted_after_checkpoint"
   /** Signal aborted while the catch handler was synthesizing an error turn. */
@@ -119,9 +157,19 @@ export type AgentLoopExitReason =
   | "error";
 
 export type AgentEvent =
+  /**
+   * Emitted once per LLM call inside the loop, immediately before the
+   * `provider.sendMessage` invocation. Carries the optional `callSite` tag so
+   * downstream handlers (the daemon's persistence pipeline) can decide
+   * whether to reserve a row for this call. One `llm_call_started` precedes
+   * every `message_complete` for the same call; multi-call agent turns emit
+   * one pair per call.
+   */
+  | { type: "llm_call_started"; callSite?: LLMCallSite }
   | { type: "text_delta"; text: string }
   | { type: "thinking_delta"; thinking: string }
   | { type: "message_complete"; message: Message }
+  | { type: "max_tokens_reached"; stopReason: string }
   | {
       type: "tool_use";
       id: string;
@@ -157,6 +205,14 @@ export type AgentEvent =
       approvalReason?: string;
       riskThreshold?: string;
       activityMetadata?: ToolActivityMetadata;
+      /**
+       * Set when the loop synthesizes this result for a tool_use that never
+       * executed (a "Cancelled by user" block on abort). The daemon still
+       * captures it into `pendingToolResults` and forwards it to the client,
+       * but skips the side effects that assume the tool ran — marking the
+       * workspace dirty and emitting a post-tool "thinking" activity state.
+       */
+      cancelled?: boolean;
     }
   | { type: "tool_use_preview_start"; toolUseId: string; toolName: string }
   | {
@@ -191,7 +247,7 @@ export type AgentEvent =
   | { type: "error"; error: Error }
   | {
       /**
-       * Emitted when the `llmCall` pipeline throws — i.e. the provider
+       * Emitted when the provider call throws — i.e. the provider
        * rejected the request before returning a usable response. Carries
        * the loop-level raw request we attempted to send (messages, tools,
        * system prompt, provider-agnostic config) plus the thrown error.
@@ -234,6 +290,60 @@ export type AgentEvent =
        */
       estimatedInputTokens?: number;
     }
+  | {
+      /**
+       * Emitted when the loop begins compacting the running history because
+       * the mid-loop budget gate tripped. The daemon's event dispatcher
+       * translates it into a "compacting context" activity state so clients
+       * surface that the turn paused to summarize context.
+       */
+      type: "context_compacting";
+    }
+  | {
+      /**
+       * Emitted after the loop's inline mid-loop compaction pipeline runs,
+       * immediately before re-injection — whether or not the pipeline actually
+       * compacted. The daemon's event dispatcher always commits `basis` (the
+       * stripped pre-compaction history) as the conversation's durable message
+       * state, so re-injection ({@link MidLoopCompaction.reinject}) re-applies
+       * injections onto the stripped base rather than stacking on top of the
+       * still-injected messages. When `result.compacted` is set it
+       * additionally commits the durable compaction result (DB-record fields,
+       * graph-memory side effects, SSE) and flips the per-turn re-injection
+       * guards on the handler state.
+       *
+       * Treated as a critical event: a failed durable commit re-throws so the
+       * turn aborts rather than re-injecting against half-applied state.
+       *
+       * `basis` is the stripped pre-compaction history the summary was built
+       * from; the dispatcher uses it to project Slack provenance onto the
+       * compacted result.
+       */
+      type: "compaction_completed";
+      result: ContextWindowResult;
+      basis: Message[];
+    }
+  | {
+      /**
+       * Emitted right after the loop strips runtime injections from the
+       * running history, before the compaction pipeline runs. The daemon's
+       * event dispatcher records the history-stripped marker — a Conversation
+       * DB-record field read back at load time to strip embedded injection
+       * prefixes from pre-strip messages. Best-effort: a transient marker
+       * write must not abort the turn, so unlike `compaction_completed` this
+       * event is not treated as critical.
+       */
+      type: "history_stripped";
+    }
+  /**
+   * Circuit-breaker transitions emitted when auto-compaction is paused
+   * (`compaction_circuit_open`, after three consecutive summary-LLM
+   * failures) or resumed (`compaction_circuit_closed`). These are already
+   * in wire-contract shape; the daemon's event dispatcher forwards them to
+   * the client unchanged so the "auto-compaction paused" banner shows and
+   * dismisses.
+   */
+  | CompactionCircuitEvent
   | {
       /**
        * Emitted when an agent turn reaches a terminal state. Checkpoint
@@ -254,8 +364,19 @@ const DEFAULT_CONFIG: AgentLoopConfig = {
   minTurnIntervalMs: 150,
 };
 
-const MAX_CONSECUTIVE_ERROR_NUDGES = 3;
-const MAX_EMPTY_RESPONSE_RETRIES = 1;
+const MAX_STOP_CONTINUE_RETRIES = 1;
+const MAX_TOKENS_STOP_REASONS = new Set([
+  "length",
+  "max_output_tokens",
+  "max_tokens",
+]);
+
+export function isMaxTokensStopReason(
+  stopReason: string | null | undefined,
+): boolean {
+  if (!stopReason) return false;
+  return MAX_TOKENS_STOP_REASONS.has(stopReason.trim().toLowerCase());
+}
 
 /**
  * Build a minimal {@link TurnContext} for pipeline invocations inside the
@@ -264,12 +385,11 @@ const MAX_EMPTY_RESPONSE_RETRIES = 1;
  * {@link AgentLoop.run}); this helper is the fallback used only by unit
  * tests that construct `AgentLoop` directly without an orchestrator.
  *
- * When the orchestrator-supplied context is present, {@link resolveLoopTurnContext}
- * is used instead of this helper so the pipeline sees the real
- * `conversationId`, trust, and `contextWindowManager`. In the fallback path
- * the returned context is still useful for pipeline logging: `requestId`
- * surfaces in every structured record, and `turnIndex` reflects the
- * current tool-use iteration.
+ * When the orchestrator-supplied context is present it is used directly so the
+ * pipeline sees the real `conversationId`, trust, and `contextWindowManager`.
+ * In the fallback path the returned context is still useful for pipeline
+ * logging: `requestId` surfaces in every structured record, and `turnIndex`
+ * reflects the current tool-use iteration.
  */
 function buildLoopTurnContext(
   requestId: string | undefined,
@@ -289,29 +409,6 @@ function buildLoopTurnContext(
   };
 }
 
-/**
- * Produce a `TurnContext` for a pipeline call inside {@link AgentLoop.run}.
- *
- * When the orchestrator supplied a `turnContext`, clone it and overwrite
- * `requestId` + `turnIndex` with the loop-scoped values so plugin log
- * records correctly attribute the call to the current tool-use iteration
- * while preserving the real `conversationId`, trust context, and
- * `contextWindowManager` the orchestrator assembled for the turn. Without
- * an orchestrator context (unit tests that instantiate `AgentLoop` with no
- * `turnContext`), fall back to {@link buildLoopTurnContext}'s synthesized
- * placeholder.
- */
-function resolveLoopTurnContext(
-  base: TurnContext | undefined,
-  requestId: string | undefined,
-  turnIndex: number,
-): TurnContext {
-  if (base) {
-    return { ...base, requestId: requestId ?? base.requestId, turnIndex };
-  }
-  return buildLoopTurnContext(requestId, turnIndex);
-}
-
 /**
  * User-config HTTP status codes that should never page the on-call: billing
  * exhaustion (402), invalid credentials (401), and forbidden/plan-gated (403).
@@ -354,23 +451,91 @@ export interface ResolvedSystemPrompt {
   model?: string;
 }
 
+/**
+ * Orchestrator-supplied hook the loop invokes when the mid-loop budget gate
+ * trips and inline compaction runs. The loop owns the trigger, the
+ * compaction call, the result interpretation (circuit-breaker
+ * bookkeeping + the exhaustion decision), and the inline continue; this hook
+ * bridges the injection state the loop is intentionally blind to. Durable
+ * persistence is signalled out-of-band via the `history_stripped` (marker)
+ * and `compaction_completed` (basis commit + successful summary) {@link
+ * AgentEvent}s; the {@link MidLoopCompaction.postCompactionHook} is
+ * orchestrator-supplied, and its inputs migrate loop-ward as the loop
+ * subsumes the re-injection ceremony.
+ */
+export interface MidLoopCompaction {
+  /**
+   * Re-apply runtime injections onto the post-compaction history and return
+   * the history to continue from. The loop supplies its own working state via
+   * {@link PostCompactionHookInput} so the hook re-injects from that rather
+   * than reading it back from orchestrator state.
+   */
+  postCompactionHook: (input: PostCompactionHookInput) => Promise<Message[]>;
+}
+
+export interface AgentLoopRunOptions {
+  signal?: AbortSignal;
+  requestId?: string;
+  onCheckpoint?: (
+    checkpoint: CheckpointInfo,
+  ) => CheckpointDecision | Promise<CheckpointDecision>;
+  callSite?: LLMCallSite;
+  /**
+   * Per-turn context supplied by the orchestrator. Every pipeline
+   * invocation inside the loop clones from this value (overwriting only
+   * `turnIndex`/`requestId`) so middleware sees the real conversation
+   * identity, trust class, and `contextWindowManager` rather than the
+   * `"agent-loop"` sentinel used when the loop is instantiated standalone
+   * in unit tests.
+   */
+  turnContext?: TurnContext;
+  /**
+   * Ad-hoc inference-profile override applied to every LLM call the loop
+   * issues. When set, each `SendMessageOptions.config` carries
+   * `overrideProfile = <name>` so the provider's resolver layers
+   * `llm.profiles[<name>]` between the workspace `activeProfile` and any
+   * call-site named profile. Missing profile names silently fall through.
+   */
+  overrideProfile?: string;
+  resolveOverrideProfile?: () => string | undefined;
+  /**
+   * Resolves the orchestrator's effective context window for this turn: the
+   * provider max-input-token ceiling (read by tool-result truncation) plus the
+   * `overflowRecovery` config that drives the mid-loop budget gate. Resolved
+   * fresh per checkpoint so a mid-turn profile change is reflected. Absent →
+   * truncation falls back to `this.config.maxInputTokens` and the budget gate
+   * is skipped (agent wakes pass `overflowRecovery.enabled = false`).
+   */
+  resolveContextWindow?: () => {
+    maxInputTokens: number;
+    overflowRecovery: { enabled: boolean; safetyMarginRatio: number };
+  };
+  /**
+   * Hooks for inline mid-loop compaction. When supplied and the budget gate
+   * trips, the loop compacts in place and continues instead of yielding
+   * `exitReason = "budget"`. Callers without a compaction path (agent wakes,
+   * convergence/auto-compress reruns) omit this and keep yielding for budget.
+   */
+  compaction?: MidLoopCompaction;
+  /**
+   * When true, the latest user message carries a volatile per-turn block
+   * (e.g. a memory-v3 `<memory>` injection) that varies across otherwise
+   * identical turns. Forwarded to each `SendMessageOptions.config` so the
+   * provider anchors its long-TTL cache breakpoint on the most recent STABLE
+   * user message instead of the volatile latest one, keeping the cached
+   * prefix reusable. Default unset → existing behavior.
+   */
+  mutableLatestUserMessage?: boolean;
+}
+
 /**
  * Callback shape the loop uses to execute a tool invocation.
- *
- * The trailing `turnContext` is optional so in-process tests that wire the
- * callback without an orchestrator keep working. Production sites (the
- * `Conversation`'s `createToolExecutor`) forward the supplied context into
- * `ToolExecutor.execute` so the `toolExecute` pipeline sees the orchestrator's
- * real conversation identity/trust/contextWindowManager instead of the
- * synthesized placeholder `ToolExecutor` would otherwise build from the
- * `ToolContext` alone.
  */
 export type LoopToolExecutor = (
   name: string,
   input: Record<string, unknown>,
   onOutput?: (chunk: string) => void,
   toolUseId?: string,
-  turnContext?: TurnContext,
 ) => Promise<{
   content: string;
   isError: boolean;
@@ -401,6 +566,20 @@ export type LoopToolExecutor = (
   activityMetadata?: ToolActivityMetadata;
 }>;
 
+export interface AgentLoopConstructorOptions {
+  config?: Partial<AgentLoopConfig>;
+  tools?: ToolDefinition[];
+  toolExecutor?: LoopToolExecutor;
+  resolveTools?: (history: Message[]) => ToolDefinition[];
+  resolveSystemPrompt?: (history: Message[]) => ResolvedSystemPrompt;
+  /**
+   * Conversation this loop drives. Used to scope the loop-held compaction
+   * circuit breaker; defaults to an empty key for test loops that never
+   * exercise compaction.
+   */
+  conversationId?: string;
+}
+
 export class AgentLoop {
   private provider: Provider;
   private systemPrompt: string;
@@ -412,15 +591,28 @@ export class AgentLoop {
     | null;
   private toolExecutor: LoopToolExecutor | null;
 
+  /**
+   * Loop-held compaction circuit breaker. The loop has a 1:1 lifetime with its
+   * conversation, so it is the source of truth for the cross-turn failure
+   * counter and cooldown deadline. Non-loop callers (the orchestrator's
+   * compaction paths, `Conversation.forceCompact`, and the dev-only playground
+   * routes) reach it via `agentLoop.compactionCircuit`.
+   */
+  readonly compactionCircuit: CompactionCircuit;
+
   constructor(
     provider: Provider,
     systemPrompt: string,
-    config?: Partial<AgentLoopConfig>,
-    tools?: ToolDefinition[],
-    toolExecutor?: LoopToolExecutor,
-    resolveTools?: (history: Message[]) => ToolDefinition[],
-    resolveSystemPrompt?: (history: Message[]) => ResolvedSystemPrompt,
+    options?: AgentLoopConstructorOptions,
   ) {
+    const {
+      config,
+      tools,
+      toolExecutor,
+      resolveTools,
+      resolveSystemPrompt,
+      conversationId,
+    } = options ?? {};
     this.provider = provider;
     this.systemPrompt = systemPrompt;
     this.config = { ...DEFAULT_CONFIG, ...config };
@@ -428,16 +620,16 @@ export class AgentLoop {
     this.resolveTools = resolveTools ?? null;
     this.resolveSystemPrompt = resolveSystemPrompt ?? null;
     this.toolExecutor = toolExecutor ?? null;
+    this.compactionCircuit = new CompactionCircuit(conversationId ?? "");
   }
 
   /**
    * Resolve the tool definitions sent to the provider for the given turn.
    *
    * Mirrors the logic of {@link getToolTokenBudget} but returns the tool
-   * array itself — callers that need to thread the tool set into a plugin
-   * pipeline (e.g. `tokenEstimate`, where the pipeline's args include
-   * `tools`) use this rather than re-implementing the dynamic-vs-static
-   * resolver fork.
+   * array itself — callers that need to thread the tool set into the token
+   * estimate (`estimatePromptTokensWithTools`, whose args include `tools`)
+   * use this rather than re-implementing the dynamic-vs-static resolver fork.
    */
   getResolvedTools(history?: Message[]): ToolDefinition[] {
     return history && this.resolveTools
@@ -457,58 +649,167 @@ export class AgentLoop {
     return estimateToolsTokens(this.getResolvedTools(history));
   }
 
+  /**
+   * Calibrated prompt-token estimate for `history`, including the
+   * resolved-tool budget for the turn.
+   */
+  private estimateTokens(history: Message[]): number {
+    return estimatePromptTokensWithTools(
+      history,
+      this.systemPrompt,
+      this.getResolvedTools(history),
+      getCalibrationProviderKey(this.provider),
+    );
+  }
+
+  /**
+   * Record a compaction outcome against the loop's circuit breaker. Three
+   * consecutive failures trip a cooldown that suspends auto-compaction; a
+   * success resets the counter. Any open/closed transition is emitted on the
+   * loop's own event channel via `onEvent`.
+   *
+   * Bookkeeping is best-effort — a failure here must not turn a recoverable
+   * compaction outcome into a user-visible turn failure.
+   */
+  private async recordCompactionOutcome(
+    turnContext: TurnContext,
+    summaryFailed: boolean,
+    onEvent: (event: AgentEvent) => void | Promise<void>,
+  ): Promise<void> {
+    try {
+      await this.compactionCircuit.recordOutcome(summaryFailed, onEvent);
+    } catch (recordError) {
+      log.error(
+        { err: recordError, requestId: turnContext.requestId },
+        "Recording a compaction outcome against the circuit breaker failed; suppressing to keep the agent loop alive",
+      );
+    }
+  }
+
+  /**
+   * Compact the running history in place when the mid-loop budget gate trips.
+   *
+   * Calls the default compaction plugin on the stripped history, then
+   * re-applies injections via the supplied hooks. Returns the history to
+   * continue from, or `null` when the compactor exhausted its retry budget so
+   * the caller yields `exitReason = "budget"` and the orchestrator escalates.
+   */
+  private async compact(
+    history: Message[],
+    turnContext: TurnContext,
+    compaction: MidLoopCompaction,
+    signal: AbortSignal | undefined,
+    onEvent: (event: AgentEvent) => void | Promise<void>,
+    overrideProfile: string | null,
+  ): Promise<Message[] | null> {
+    await onEvent({ type: "context_compacting" });
+    // Strip runtime injections so the compactor summarizes the raw persistent
+    // messages.
+    const rawHistory = stripInjectionsForCompaction(history);
+    // Record the history-stripped marker right after stripping, before the
+    // pipeline runs.
+    await onEvent({ type: "history_stripped" });
+    const manager = turnContext.contextWindowManager;
+    if (manager == null) {
+      throw new PluginExecutionError(
+        "default-compaction: turnContext.contextWindowManager is missing — orchestrator must attach it before invoking compaction",
+        DEFAULT_COMPACTION_PLUGIN_NAME,
+      );
+    }
+    // The mid-loop budget gate is reached only when this turn decides to
+    // compact in place, so `force` past the auto-threshold check.
+    // `actorTrustClass` comes from the turn context (the actor whose turn
+    // triggered compaction) so the compactor's image manifest excludes
+    // guardian-only attachments for untrusted actors. `overrideProfile` is the
+    // turn's resolved inference-profile override for the summary call.
+    const compactResult = await defaultCompact({
+      manager,
+      messages: rawHistory,
+      signal,
+      force: true,
+      actorTrustClass: turnContext.trust.trustClass,
+      overrideProfile,
+    });
+    // `force: true` bypasses the auto-threshold gate, but early returns
+    // for "no eligible messages" / "insufficient messages" still leave
+    // `summaryFailed` undefined. Only record an outcome when the summary LLM
+    // actually ran.
+    if (compactResult.summaryFailed !== undefined) {
+      await this.recordCompactionOutcome(
+        turnContext,
+        compactResult.summaryFailed,
+        onEvent,
+      );
+    }
+    // Emit unconditionally: the dispatcher commits the stripped `basis` as the
+    // durable message base whether or not the pipeline compacted (re-injection
+    // reads it), and runs the durable compaction commit only when
+    // `result.compacted`.
+    await onEvent({
+      type: "compaction_completed",
+      result: compactResult,
+      basis: rawHistory,
+    });
+    if (compactResult.exhausted ?? false) {
+      return null;
+    }
+    // Re-inject onto the same base the `compaction_completed` dispatch commits:
+    // the compacted messages when the pipeline compacted, the stripped
+    // pre-compaction history otherwise.
+    return compaction.postCompactionHook({
+      history: compactResult.compacted ? compactResult.messages : rawHistory,
+      turnContext,
+    });
+  }
+
   async run(
     messages: Message[],
     onEvent: (event: AgentEvent) => void | Promise<void>,
-    signal?: AbortSignal,
-    requestId?: string,
-    onCheckpoint?: (
-      checkpoint: CheckpointInfo,
-    ) => CheckpointDecision | Promise<CheckpointDecision>,
-    callSite?: LLMCallSite,
-    /**
-     * Optional per-turn context supplied by the orchestrator. Every pipeline
-     * invocation inside the loop clones from this value (overwriting only
-     * `turnIndex`/`requestId`) so middleware sees the real conversation
-     * identity, trust class, and `contextWindowManager` rather than the
-     * `"agent-loop"` sentinel used when the loop is instantiated standalone
-     * in unit tests.
-     */
-    turnContext?: TurnContext,
-    /**
-     * Optional ad-hoc inference-profile override applied to every LLM call
-     * the loop issues. When set, each `SendMessageOptions.config` carries
-     * `overrideProfile = <name>` so the provider's resolver layers
-     * `llm.profiles[<name>]` between the workspace `activeProfile` and any
-     * call-site named profile. Missing profile names silently fall through.
-     * Used by per-conversation pinned profiles to override the workspace
-     * default for the lifetime of an agent loop run.
-     */
-    overrideProfile?: string,
-    effectiveMaxInputTokens?: number,
-    resolveOverrideProfile?: () => string | undefined,
-    resolveEffectiveMaxInputTokens?: () => number | undefined,
-  ): Promise<Message[]> {
-    const history = [...messages];
-    const initialHistoryLength = messages.length;
+    options?: AgentLoopRunOptions,
+  ): Promise<AgentLoopRunResult> {
+    const {
+      signal,
+      requestId,
+      onCheckpoint,
+      callSite,
+      turnContext,
+      overrideProfile,
+      resolveOverrideProfile,
+      resolveContextWindow,
+      compaction,
+      mutableLatestUserMessage,
+    } = options ?? {};
+    let history = [...messages];
+    // Index into `history` where this run's appended output begins. It starts
+    // after the input and resets to the compacted base whenever the loop
+    // compacts in place, so `history.slice(newMessagesStart)` is always exactly
+    // what the loop produced since the last (re-injected) base.
+    let newMessagesStart = history.length;
+    let producedVisibleTextThisRun = false;
     let toolUseTurns = 0;
-    let consecutiveErrorTurns = 0;
-    let emptyResponseRetries = 0;
+    let stopContinueRetries = 0;
     let lastLlmCallTime = 0;
+    let exitReason: ExitReason | null = null;
+    let appendedNewMessages = false;
     const rlog = requestId ? log.child({ requestId }) : log;
 
+    // Resolve the inference-profile override that applies right now. The
+    // optional resolver lets a turn observe a confirmed mid-turn profile switch
+    // before the next model call; absent a resolver the turn-start value holds.
+    const resolveEffectiveOverrideProfile = (): string | undefined =>
+      resolveOverrideProfile ? resolveOverrideProfile() : overrideProfile;
+
     // Per-run substitution map for sensitive output placeholders.
     // Bindings are accumulated from tool results; placeholders are
     // resolved in streamed deltas and final assistant message text.
     const substitutionMap = new Map<string, string>();
     let streamingPending = "";
 
-    // Idempotency guard for `emitExit`. Used so the throw path in the
-    // empty-response branch can stamp its reason ("empty_response_exhausted")
-    // before throwing — the catch handler that observes the rethrow will
-    // then attempt to stamp "error" and harmlessly no-op, preserving the
-    // more specific reason. Also defends against accidental future
-    // double-emits if a new break site is added without checking this.
+    // Idempotency guard for `emitExit`: the first reason stamped wins. A break
+    // site that stamps a specific reason before unwinding into the catch
+    // handler keeps that reason instead of the generic "error", and the guard
+    // also defends against accidental double-emits if a new break site is
+    // added without checking this.
     let exitReasonEmitted = false;
     const emitExit = async (reason: AgentLoopExitReason): Promise<void> => {
       if (exitReasonEmitted) return;
@@ -593,6 +894,15 @@ export class AgentLoop {
           providerConfig.cacheTtl = this.config.cacheTtl;
         }
 
+        // Cache-anchor signal for volatile latest-user-message turns (e.g.
+        // memory-v3 injects its `<memory>` block into the latest user
+        // message). Not part of the call-site schema, so it is always sourced
+        // from the per-run option regardless of `callSite`. Only set when true
+        // so the wire/config stays byte-identical when off.
+        if (mutableLatestUserMessage) {
+          providerConfig.mutableLatestUserMessage = true;
+        }
+
         // Per-call LLM call-site identifier. Surfaces on the per-call
         // `config.callSite` so `RetryProvider.normalizeSendMessageOptions`
         // can route through `resolveCallSiteConfig` against
@@ -603,6 +913,16 @@ export class AgentLoop {
         if (callSite) {
           providerConfig.callSite = callSite;
           providerConfig.usageTracking = "manual";
+          // Per-conversation seed for deterministic `mix`-profile expansion.
+          // Sourced from the orchestrator-supplied turn context's
+          // conversationId so every LLM call in a conversation resolves the
+          // same mix arm (stable across turns and retries, and across daemon
+          // restarts since the seed is the durable conversation id). Absent
+          // for standalone `AgentLoop` instances (unit tests / no turnContext)
+          // — those fall back to per-call random mix selection.
+          if (turnContext?.conversationId) {
+            providerConfig.selectionSeed = turnContext.conversationId;
+          }
         }
 
         // Per-call inference-profile override. The resolver layers
@@ -610,12 +930,8 @@ export class AgentLoop {
         // `activeProfile` and any call-site named profile. Threading it on
         // every send (rather than once at construction) keeps subagents that
         // share an `AgentLoop` instance but ought to inherit a different
-        // profile correct — and matches how `callSite` is plumbed. The
-        // optional resolver lets a turn observe an explicitly confirmed
-        // profile-session switch before the next model call.
-        const effectiveOverrideProfile = resolveOverrideProfile
-          ? resolveOverrideProfile()
-          : overrideProfile;
+        // profile correct — and matches how `callSite` is plumbed.
+        const effectiveOverrideProfile = resolveEffectiveOverrideProfile();
         if (effectiveOverrideProfile) {
           providerConfig.overrideProfile = effectiveOverrideProfile;
         }
@@ -658,98 +974,91 @@ export class AgentLoop {
         // Also strip old AX tree snapshots to keep TTFT from growing
         // linearly with step count in computer-use sessions.
         const providerHistory = compactAxTreeHistory(
-          stripOldImageBlocks(history),
+          stripOldMediaBlocks(history),
         );
 
-        // Wrap the provider call in the `llmCall` pipeline so middleware
-        // contributed by plugins may observe, rewrite, short-circuit, or
-        // post-process every LLM request. The terminal below is the real
-        // `provider.sendMessage(...)` call; middleware reach it by calling
-        // `next(args)`. The default `defaultLlmCallPlugin` contributes a
-        // passthrough middleware that forwards to `next(args)` — it
-        // registers at module load and sits at the outermost onion layer,
-        // so it must yield to keep user-registered `llmCall` middleware
-        // reachable. Timeout is `null` (`DEFAULT_TIMEOUTS.llmCall`) — the
-        // provider layer already enforces its own HTTP-level budgets.
-        //
-        // The `onEvent` wrapping is kept inside `args.options` so substitution
-        // and streaming behavior exactly match the pre-pipeline call site.
-        const llmCallArgs: LLMCallArgs = {
-          provider: this.provider,
-          messages: providerHistory,
+        // The `onEvent` wrapping below applies sensitive-output placeholder
+        // substitution to streamed text while forwarding every other event
+        // type through unchanged.
+        const providerOptions: SendMessageOptions = {
           tools: currentTools.length > 0 ? currentTools : undefined,
           systemPrompt: turnSystemPrompt,
-          options: {
-            config: providerConfig,
-            onEvent: (event) => {
-              if (event.type === "text_delta") {
-                // Apply sensitive-output placeholder substitution (chunk-safe)
-                if (substitutionMap.size > 0) {
-                  const combined = streamingPending + event.text;
-                  const { emit, pending } = applyStreamingSubstitution(
-                    combined,
-                    substitutionMap,
-                  );
-                  streamingPending = pending;
-                  if (emit.length > 0) {
-                    onEvent({ type: "text_delta", text: emit });
-                  }
-                } else {
-                  onEvent({ type: "text_delta", text: event.text });
+          config: providerConfig,
+          onEvent: (event) => {
+            if (event.type === "text_delta") {
+              // Apply sensitive-output placeholder substitution (chunk-safe)
+              if (substitutionMap.size > 0) {
+                const combined = streamingPending + event.text;
+                const { emit, pending } = applyStreamingSubstitution(
+                  combined,
+                  substitutionMap,
+                );
+                streamingPending = pending;
+                if (emit.length > 0) {
+                  onEvent({ type: "text_delta", text: emit });
                 }
-              } else if (event.type === "thinking_delta") {
-                onEvent({ type: "thinking_delta", thinking: event.thinking });
-              } else if (event.type === "tool_use_preview_start") {
-                onEvent({
-                  type: "tool_use_preview_start",
-                  toolUseId: event.toolUseId,
-                  toolName: event.toolName,
-                });
-              } else if (event.type === "input_json_delta") {
-                onEvent({
-                  type: "input_json_delta",
-                  toolName: event.toolName,
-                  toolUseId: event.toolUseId,
-                  accumulatedJson: event.accumulatedJson,
-                });
-              } else if (event.type === "server_tool_start") {
-                onEvent({
-                  type: "server_tool_start",
-                  name: event.name,
-                  toolUseId: event.toolUseId,
-                  input: event.input,
-                });
-              } else if (event.type === "server_tool_complete") {
-                onEvent({
-                  type: "server_tool_complete",
-                  toolUseId: event.toolUseId,
-                  isError: event.isError,
-                  ...(event.content ? { content: event.content } : {}),
-                  ...(event.resolvedInput
-                    ? { resolvedInput: event.resolvedInput }
-                    : {}),
-                  ...(event.errorCode ? { errorCode: event.errorCode } : {}),
-                  ...(event.errorMessage
-                    ? { errorMessage: event.errorMessage }
-                    : {}),
-                });
+              } else {
+                onEvent({ type: "text_delta", text: event.text });
               }
-            },
-            signal,
+            } else if (event.type === "thinking_delta") {
+              onEvent({ type: "thinking_delta", thinking: event.thinking });
+            } else if (event.type === "tool_use_preview_start") {
+              onEvent({
+                type: "tool_use_preview_start",
+                toolUseId: event.toolUseId,
+                toolName: event.toolName,
+              });
+            } else if (event.type === "input_json_delta") {
+              onEvent({
+                type: "input_json_delta",
+                toolName: event.toolName,
+                toolUseId: event.toolUseId,
+                accumulatedJson: event.accumulatedJson,
+              });
+            } else if (event.type === "server_tool_start") {
+              onEvent({
+                type: "server_tool_start",
+                name: event.name,
+                toolUseId: event.toolUseId,
+                input: event.input,
+              });
+            } else if (event.type === "server_tool_complete") {
+              onEvent({
+                type: "server_tool_complete",
+                toolUseId: event.toolUseId,
+                isError: event.isError,
+                ...(event.content ? { content: event.content } : {}),
+                ...(event.resolvedInput
+                  ? { resolvedInput: event.resolvedInput }
+                  : {}),
+                ...(event.errorCode ? { errorCode: event.errorCode } : {}),
+                ...(event.errorMessage
+                  ? { errorMessage: event.errorMessage }
+                  : {}),
+              });
+            }
           },
+          signal,
         };
 
-        // Per-turn pipeline context. When the orchestrator threaded a full
-        // `turnContext` into `run()`, use it (overwriting `turnIndex` with
-        // the loop-scoped tool-use iteration) so middleware sees the real
-        // conversation identity, trust, and `contextWindowManager`. The
-        // synthesized fallback is only reached by standalone unit-test
-        // instantiations that never plumb a context through.
-        const turnCtx = resolveLoopTurnContext(
-          turnContext,
-          requestId,
-          toolUseTurns,
-        );
+        // Per-turn pipeline context. Real call sites thread a full
+        // `turnContext` into `run()` and it is used directly; standalone
+        // unit-test instantiations that never plumb a context through fall
+        // back to a synthesized placeholder scoped to the tool-use iteration.
+        const turnCtx =
+          turnContext ?? buildLoopTurnContext(requestId, toolUseTurns);
+
+        // Announce the LLM-call boundary so downstream handlers (the
+        // daemon's persistence pipeline) can reserve an empty assistant row
+        // and stamp the resulting `messageId` onto every streaming event the
+        // call emits. Emit as late as possible — after history stripping,
+        // arg construction, and turn-context resolution — so the gap
+        // between "we said the call started" and the actual provider HTTP
+        // call is minimized. Awaited so the row is created and the
+        // `assistant_turn_start` wire event reaches the client BEFORE the
+        // provider starts streaming deltas — the deltas downstream will
+        // carry the freshly-reserved id.
+        await onEvent({ type: "llm_call_started", callSite });
 
         // Inner try/catch narrows error-recording scope to the provider
         // call itself. The outer agent-loop catch (below) wraps the entire
@@ -760,21 +1069,11 @@ export class AgentLoop {
         // `llm_request_logs` row, then re-throw so the existing outer catch
         // continues to handle abort sync, Sentry capture, the `error` event,
         // and the loop break unchanged.
-        let response: LLMCallResult;
+        let response: ProviderResponse;
         try {
-          response = await runPipeline<LLMCallArgs, LLMCallResult>(
-            "llmCall",
-            getMiddlewaresFor("llmCall"),
-            (args) =>
-              args.provider.sendMessage(
-                args.messages,
-                args.tools,
-                args.systemPrompt,
-                args.options,
-              ),
-            llmCallArgs,
-            turnCtx,
-            DEFAULT_TIMEOUTS.llmCall,
+          response = await this.provider.sendMessage(
+            providerHistory,
+            providerOptions,
           );
         } catch (llmCallError) {
           // Skip recording on abort — the user cancelled the request and
@@ -792,10 +1091,10 @@ export class AgentLoop {
             // misrepresent both.
             const rawRequest = {
               provider: this.provider.name,
-              messages: llmCallArgs.messages,
-              tools: llmCallArgs.tools,
-              systemPrompt: llmCallArgs.systemPrompt,
-              config: llmCallArgs.options?.config,
+              messages: providerHistory,
+              tools: providerOptions.tools,
+              systemPrompt: providerOptions.systemPrompt,
+              config: providerOptions.config,
             };
             onEvent({
               type: "provider_error",
@@ -862,130 +1161,100 @@ export class AgentLoop {
           "LLM call complete",
         );
 
-        // Detect empty responses: no user-visible text and no tool calls.
-        // This can happen when the model fails to produce output after
-        // receiving a large tool result. Retry once with a nudge before
-        // the message is persisted.
-        //
-        // Only nudge when the model hasn't already delivered text to the user
-        // earlier in this tool-use chain. If a prior assistant turn in history
-        // contained visible text (e.g. the model said its piece before calling
-        // a side-effect tool like `remember`), an empty follow-up is the model
-        // correctly ending its turn — nudging would mislead it into thinking
-        // its earlier text didn't land and cause a verbatim re-send.
-        //
-        // Note: we check ANY prior assistant turn from this run()
-        // invocation, not just the most recent one. In multi-step tool-use
-        // chains (say-something → call-tool → call-another-tool → end),
-        // the "say-something" text lives on an earlier assistant turn while
-        // the most recent assistant turn is a pure tool_use with no text.
-        // Restricting the check to the most recent assistant turn would
-        // falsely nudge in that case and trigger a duplicate re-send of
-        // text the user already saw.
-        //
-        // Scope the scan to messages appended during this run() call only.
-        // Assistant text from prior conversation turns (earlier run()
-        // invocations passed in via `messages`) must NOT suppress the
-        // nudge — those turns completed long ago and have no bearing on
-        // whether the current tool-use chain has delivered text yet.
-        //
-        // The actual decision (nudge vs. accept vs. error) is delegated to
-        // the `emptyResponse` plugin pipeline. The pipeline returns a
-        // decision; the loop carries out the side-effect (pushing the nudge
-        // or surfacing the error). See `plugins/defaults/empty-response.ts`
-        // for the default decision logic.
-        const hasVisibleText = response.content.some(
-          (block) => block.type === "text" && block.text.trim().length > 0,
-        );
-        const priorAssistantHadVisibleText = (() => {
-          for (let i = history.length - 1; i >= initialHistoryLength; i--) {
-            const msg = history[i];
-            if (msg.role !== "assistant") continue;
-            const hasText = msg.content.some(
-              (block) =>
-                block.type === "text" &&
-                typeof (block as { text?: unknown }).text === "string" &&
-                (block as { text: string }).text.trim().length > 0,
-            );
-            if (hasText) return true;
-          }
-          return false;
-        })();
-
-        const emptyResponseArgs: EmptyResponseArgs = {
-          responseContent: response.content,
-          toolUseBlocksLength: toolUseBlocks.length,
-          toolUseTurns,
-          emptyResponseRetries,
-          maxEmptyResponseRetries: MAX_EMPTY_RESPONSE_RETRIES,
-          priorAssistantHadVisibleText,
-        };
-        const emptyResponseCtx = resolveLoopTurnContext(
-          turnContext,
-          requestId,
-          toolUseTurns,
-        );
-        const emptyResponseDecision: EmptyResponseDecision = await runPipeline(
-          "emptyResponse",
-          getMiddlewaresFor("emptyResponse"),
-          async (args) => defaultEmptyResponseTerminal(args),
-          emptyResponseArgs,
-          emptyResponseCtx,
-          DEFAULT_TIMEOUTS.emptyResponse,
-        );
-
-        if (emptyResponseDecision.action === "nudge") {
-          // Fall back to the canonical nudge text if the plugin returned
-          // `action: "nudge"` but forgot `nudgeText`. Keeps a misbehaving
-          // plugin from silently breaking the loop invariant that the
-          // model sees a coherent prompt.
-          const nudgeText =
-            emptyResponseDecision.nudgeText ??
-            "<system_notice>Your previous response was empty. You must respond to the user with a summary of what you found or did. Do not use any tools — just respond with text.</system_notice>";
-          emptyResponseRetries++;
+        if (isMaxTokensStopReason(response.stopReason)) {
+          const safeContent = response.content.filter(
+            (block) =>
+              block.type !== "tool_use" &&
+              block.type !== "server_tool_use" &&
+              block.type !== "web_search_tool_result",
+          );
+          const safeAssistantMessage: Message = {
+            role: "assistant",
+            content: safeContent,
+          };
           rlog.warn(
-            { turn: toolUseTurns, retry: emptyResponseRetries },
-            "Model returned empty response after tool results — retrying",
+            {
+              turn: toolUseTurns,
+              stopReason: response.stopReason,
+              contentBlocks: response.content.length,
+              safeContentBlocks: safeContent.length,
+              toolUseCount: toolUseBlocks.length,
+            },
+            "LLM response reached output token limit",
           );
-          history.push({
-            role: "user",
-            content: [{ type: "text", text: nudgeText }],
+          history.push(safeAssistantMessage);
+          appendedNewMessages = true;
+          await onEvent({
+            type: "max_tokens_reached",
+            stopReason: response.stopReason,
+          });
+          await onEvent({
+            type: "message_complete",
+            message: safeAssistantMessage,
           });
-          continue;
+          await emitExit("max_tokens_reached");
+          break;
         }
 
-        if (emptyResponseDecision.action === "error") {
-          rlog.error(
-            { turn: toolUseTurns, retries: emptyResponseRetries },
-            "emptyResponse pipeline requested error surface",
-          );
-          // Stamp the specific exit reason *before* throwing. The catch
-          // handler below will see the rethrown error and attempt to stamp
-          // "error" — guarded by `exitReasonEmitted`, that becomes a no-op
-          // and the more specific reason wins.
-          await emitExit("empty_response_exhausted");
-          throw new AssistantError(
-            "Model returned empty response after tool results",
-            ErrorCode.INTERNAL_ERROR,
-          );
+        // The model's "stop" moment: a response with no tool calls is about to
+        // yield to the user. The `stop` hook (below) decides whether to accept
+        // the turn or re-query with a follow-up; `priorAssistantHadVisibleText`
+        // gates the ops log for the post-tool empty case.
+        const hasVisibleText = response.content.some(
+          (block) => block.type === "text" && block.text.trim().length > 0,
+        );
+        const priorAssistantHadVisibleText = producedVisibleTextThisRun;
+        if (hasVisibleText) {
+          producedVisibleTextThisRun = true;
         }
 
-        // action === "accept" — fall through. Emit a dedicated log line for
-        // the specific "empty turn after tool results, retries exhausted"
-        // case so ops dashboards that grep on this line keep working.
-        if (
-          !hasVisibleText &&
-          toolUseBlocks.length === 0 &&
-          toolUseTurns > 0 &&
-          !priorAssistantHadVisibleText
-        ) {
-          rlog.error(
-            { turn: toolUseTurns, retries: emptyResponseRetries },
-            "Model returned empty response after tool results — retries exhausted",
-          );
+        if (toolUseBlocks.length === 0) {
+          // The model stopped requesting tools — the run's stop boundary. The
+          // `stop` hook decides whether to let the turn end or re-query with a
+          // follow-up turn. It receives the full history and, when it asks to
+          // continue, appends the follow-up turn itself.
+          const stopCtx: StopContext = {
+            conversationId: turnCtx.conversationId,
+            messages: [...history],
+            responseContent: response.content,
+            stopReason: response.stopReason,
+            decision: "stop",
+            logger: rlog,
+          };
+          const finalStopCtx = await runHook(HOOKS.STOP, stopCtx);
+
+          if (finalStopCtx.decision === "continue") {
+            // The loop owns the retry budget: a hook always asks to continue
+            // when a nudge is warranted, and the loop stops anyway once the
+            // budget is spent. This bounds the hook-driven re-query loop.
+            if (stopContinueRetries < MAX_STOP_CONTINUE_RETRIES) {
+              stopContinueRetries++;
+              rlog.warn(
+                { turn: toolUseTurns, retry: stopContinueRetries },
+                "Model returned empty response after tool results — retrying",
+              );
+              history = finalStopCtx.messages;
+              continue;
+            }
+
+            // Budget spent — accept the empty turn. Emit a dedicated log line
+            // for the post-tool empty case so ops dashboards that grep on it
+            // keep working.
+            if (
+              !hasVisibleText &&
+              toolUseTurns > 0 &&
+              !priorAssistantHadVisibleText
+            ) {
+              rlog.error(
+                { turn: toolUseTurns, retries: stopContinueRetries },
+                "Model returned empty response after tool results — retries exhausted",
+              );
+            }
+          }
         }
 
         history.push(assistantMessage);
+        appendedNewMessages = true;
 
         await onEvent({ type: "message_complete", message: assistantMessage });
 
@@ -1015,6 +1284,15 @@ export class AgentLoop {
             }),
           );
           history.push({ role: "user", content: cancelledBlocks });
+          for (const toolUse of toolUseBlocks) {
+            await onEvent({
+              type: "tool_result",
+              toolUseId: toolUse.id,
+              content: "Cancelled by user",
+              isError: true,
+              cancelled: true,
+            });
+          }
           await emitExit("aborted_post_response");
           break;
         }
@@ -1044,14 +1322,6 @@ export class AgentLoop {
                 });
               },
               toolUse.id,
-              // Forward the loop's resolved `TurnContext` through the
-              // executor callback so `ToolExecutor.execute` can thread the
-              // real orchestrator context into the `toolExecute` pipeline.
-              // Standalone tests that don't wire a `turnContext` into
-              // `AgentLoop.run()` pass `undefined` here and the executor
-              // falls back to the synthesized placeholder — preserving the
-              // existing unit-test behavior.
-              turnCtx,
             );
 
             return { toolUse, result };
@@ -1115,61 +1385,39 @@ export class AgentLoop {
           }),
         );
 
-        // Pre-emptively truncate oversized tool results to prevent context
-        // overflow. The work is delegated to the `toolResultTruncate`
-        // plugin pipeline so downstream plugins can swap in a smarter
-        // truncation strategy (e.g. a summariser) while the default
-        // middleware preserves the historical tail-drop behaviour.
+        // Run the `post-tool-use` hook once per tool result, after the tool
+        // returns and before the result joins the provider-bound history.
+        // The default tool-result-truncate plugin tail-drops oversized output
+        // to fit the context window; user hooks can swap in a smarter strategy
+        // (e.g. a summariser) or observe results for side effects.
         const contextWindowTokens =
-          resolveEffectiveMaxInputTokens?.() ??
-          effectiveMaxInputTokens ??
+          resolveContextWindow?.().maxInputTokens ??
           this.config.maxInputTokens ??
           180_000;
-        const maxChars = calculateMaxToolResultChars(contextWindowTokens);
-        const truncateMiddlewares = getMiddlewaresFor("toolResultTruncate");
 
-        let truncatedCount = 0;
-        const truncatedBlocks: ContentBlock[] = [];
+        const resultBlocks: ContentBlock[] = [];
+        const additionalContextBlocks: ContentBlock[] = [];
         for (const block of rawResultBlocks) {
           if (block.type !== "tool_result") {
-            truncatedBlocks.push(block);
+            resultBlocks.push(block);
             continue;
           }
-          const toolBlock = block as ToolResultContent;
-          if (
-            typeof toolBlock.content !== "string" ||
-            toolBlock.content.length <= maxChars
-          ) {
-            truncatedBlocks.push(block);
-            continue;
-          }
-          const pipelineResult = await runPipeline<
-            ToolResultTruncateArgs,
-            ToolResultTruncateResult
-          >(
-            "toolResultTruncate",
-            truncateMiddlewares,
-            async (args) => defaultToolResultTruncateTerminal(args),
-            { content: toolBlock.content, maxChars },
-            turnCtx,
-            DEFAULT_TIMEOUTS.toolResultTruncate,
-          );
-          if (pipelineResult.truncated) {
-            truncatedCount++;
-            truncatedBlocks.push({
-              ...toolBlock,
-              content: pipelineResult.content,
+          const postToolUseCtx: PostToolUseContext = {
+            conversationId: turnCtx.conversationId,
+            toolResponse: block as ToolResultContent,
+            messages: history,
+            maxInputTokens: contextWindowTokens,
+            logger: rlog,
+          };
+          const finalCtx = await runHook(HOOKS.POST_TOOL_USE, postToolUseCtx);
+          resultBlocks.push(finalCtx.toolResponse);
+          if (finalCtx.additionalContext !== undefined) {
+            additionalContextBlocks.push({
+              type: "text",
+              text: finalCtx.additionalContext,
             });
-          } else {
-            truncatedBlocks.push(block);
           }
         }
-        const resultBlocks = truncatedBlocks;
-        if (truncatedCount > 0) {
-          log.warn(
-            `Truncated ${truncatedCount} oversized tool result(s) to prevent context overflow`,
-          );
-        }
 
         // Emit tool_result events AFTER truncation so downstream consumers
         // (e.g. session persistence) receive the truncated content.
@@ -1221,59 +1469,20 @@ export class AgentLoop {
 
         toolUseTurns++;
 
-        // When any tool returned an error, nudge the LLM to retry with
-        // corrected parameters instead of ending its turn. Skip the nudge
-        // after MAX_CONSECUTIVE_ERROR_NUDGES consecutive error turns
-        // (the error is likely unrecoverable at that point). The nudge
-        // decision is delegated to the `toolError` plugin pipeline so user
-        // plugins can change the text, observe the event, or suppress it.
-        const hasToolError = toolResults.some(({ result }) => result.isError);
-        if (hasToolError) {
-          consecutiveErrorTurns++;
-        } else {
-          consecutiveErrorTurns = 0;
-        }
-        const toolErrorArgs: ToolErrorArgs = {
-          hasToolError,
-          consecutiveErrorTurns,
-          maxConsecutiveErrorNudges: MAX_CONSECUTIVE_ERROR_NUDGES,
-        };
-        const toolErrorCtx: TurnContext = resolveLoopTurnContext(
-          turnContext,
-          requestId,
-          toolUseTurns - 1,
-        );
-        const toolErrorDecision = await runPipeline<
-          ToolErrorArgs,
-          ToolErrorDecision
-        >(
-          "toolError",
-          getMiddlewaresFor("toolError"),
-          // Terminal: the canonical nudge decision. The default plugin's
-          // middleware is a passthrough (so later-registered user plugins
-          // aren't shadowed), so this terminal is what actually produces
-          // the decision when no user plugin overrides it. Wiring the
-          // decision here also ensures the nudge fires for direct
-          // AgentLoop callers (tests, benchmarks) that skip
-          // `bootstrapPlugins()` and therefore never register the default.
-          async (args) => defaultToolErrorTerminal(args),
-          toolErrorArgs,
-          toolErrorCtx,
-          DEFAULT_TIMEOUTS.toolError,
-        );
-        if (toolErrorDecision.action === "nudge") {
-          resultBlocks.push({
-            type: "text",
-            text: toolErrorDecision.nudgeText,
-          });
-        }
+        // Append any guidance a post-tool-use hook surfaced via
+        // `additionalContext` (e.g. tool-error retry coaching) as separate
+        // blocks. They join the provider-bound history below but were not part
+        // of the tool_result events emitted above, so the model sees the
+        // guidance while the client-facing and persisted tool output stay the
+        // tool's actual result.
+        resultBlocks.push(...additionalContextBlocks);
 
-        // Add tool results as a user message and continue the loop
+        // Add tool results as a user message and continue the loop.
         history.push({ role: "user", content: resultBlocks });
 
         // Invoke checkpoint callback after tool results are in history.
-        // The callback may be async — the mid-loop budget check delegates
-        // to the `tokenEstimate` plugin pipeline, which is asynchronous.
+        // Handoff is offered first so a queued message takes precedence over
+        // the mid-loop budget yield below.
         if (onCheckpoint) {
           const decision = await onCheckpoint({
             turnIndex: toolUseTurns - 1, // 0-based (toolUseTurns was already incremented)
@@ -1281,7 +1490,64 @@ export class AgentLoop {
             hasToolUse: true,
             history,
           });
-          if (decision === "yield") {
+          if (decision !== "continue") {
+            exitReason = decision;
+            break;
+          }
+        }
+
+        // Mid-loop budget gate: when overflow recovery is enabled, estimate
+        // the running context size as it approaches the preflight budget.
+        // With a `compaction` hook the loop compacts in place and continues;
+        // without one it yields (`exitReason = "budget"`) so the orchestrator
+        // can recover before the next provider call risks a hard
+        // context-too-large rejection. Keyed off the loop's own
+        // `history.length` (the messages actually in context this turn,
+        // including tool iterations) rather than the durable conversation
+        // count.
+        const contextWindow = resolveContextWindow?.();
+        if (contextWindow?.overflowRecovery.enabled) {
+          const { maxInputTokens, overflowRecovery } = contextWindow;
+          const safetyMargin =
+            history.length > LONG_HISTORY_MESSAGE_THRESHOLD
+              ? Math.max(
+                  overflowRecovery.safetyMarginRatio,
+                  LONG_HISTORY_SAFETY_MARGIN_FLOOR,
+                )
+              : overflowRecovery.safetyMarginRatio;
+          const preflightBudget = Math.floor(
+            maxInputTokens * (1 - safetyMargin),
+          );
+          const midLoopThreshold =
+            preflightBudget * MID_LOOP_YIELD_THRESHOLD_RATIO;
+          const estimated = this.estimateTokens(history);
+          if (estimated > midLoopThreshold) {
+            if (compaction) {
+              rlog.info(
+                { phase: "mid-loop", estimated, threshold: midLoopThreshold },
+                "Token estimate approaching budget — compacting in place",
+              );
+              const compacted = await this.compact(
+                history,
+                turnCtx,
+                compaction,
+                signal,
+                onEvent,
+                resolveEffectiveOverrideProfile() ?? null,
+              );
+              if (compacted) {
+                history = compacted;
+                // The compacted, re-injected array is the new base; output
+                // produced after this point is what the orchestrator persists.
+                newMessagesStart = history.length;
+                continue;
+              }
+            }
+            rlog.warn(
+              { phase: "mid-loop", estimated, threshold: midLoopThreshold },
+              "Token estimate approaching budget — yielding for compaction",
+            );
+            exitReason = "budget";
             break;
           }
         }
@@ -1300,6 +1566,15 @@ export class AgentLoop {
               }),
             );
             history.push({ role: "user", content: cancelledBlocks });
+            for (const toolUse of toolUseBlocks) {
+              await onEvent({
+                type: "tool_result",
+                toolUseId: toolUse.id,
+                content: "Cancelled by user",
+                isError: true,
+                cancelled: true,
+              });
+            }
           }
           await emitExit("aborted_via_error");
           break;
@@ -1313,11 +1588,9 @@ export class AgentLoop {
           Sentry.captureException(err);
         }
         onEvent({ type: "error", error: err });
-        // Catch-block fallback. If the rethrow came from the
-        // empty-response throw path above, `emitExit("error")` no-ops
-        // because `emitExit("empty_response_exhausted")` already ran
-        // before the throw. Otherwise, this is the genuine
-        // unhandled-error exit.
+        // Catch-block fallback. A break site that stamped a more specific
+        // reason before unwinding here keeps it; the guard makes this a no-op.
+        // Otherwise this is the genuine unhandled-error exit.
         await emitExit("error");
         break;
       }
@@ -1332,7 +1605,12 @@ export class AgentLoop {
       "Agent loop exited",
     );
 
-    return history;
+    return {
+      history,
+      exitReason,
+      appendedNewMessages,
+      newMessages: history.slice(newMessagesStart),
+    };
   }
 }
 
@@ -1433,7 +1711,7 @@ export function compactAxTreeHistory(messages: Message[]): Message[] {
  * turn. Using the last user message unconditionally would leave the most
  * recent tool screenshots unprotected from stripping.
  */
-function stripOldImageBlocks(history: Message[]): Message[] {
+function stripOldMediaBlocks(history: Message[]): Message[] {
   // Find the last user message that contains tool_result blocks.
   let lastToolResultUserIdx = -1;
   for (let i = history.length - 1; i >= 0; i--) {
@@ -1450,29 +1728,32 @@ function stripOldImageBlocks(history: Message[]): Message[] {
     // Keep the most recent tool-result user message intact (current turn)
     if (idx === lastToolResultUserIdx || msg.role !== "user") return msg;
 
-    // Check if any tool_result blocks have image contentBlocks
-    const hasImages = msg.content.some(
+    // Check if any tool_result blocks carry embedded media (image or audio).
+    const isMedia = (cb: ContentBlock) =>
+      cb.type === "image" || cb.type === "file";
+    const hasMedia = msg.content.some(
       (b) =>
         b.type === "tool_result" &&
-        (b as ToolResultContent).contentBlocks?.some(
-          (cb) => cb.type === "image",
-        ),
+        (b as ToolResultContent).contentBlocks?.some(isMedia),
     );
-    if (!hasImages) return msg;
+    if (!hasMedia) return msg;
 
-    // Strip images from tool_result blocks, replacing with text marker
+    // Strip media from tool_result blocks, replacing with a text marker. The
+    // model already saw/heard the media in the turn it was captured; resending
+    // the bytes every turn (a 12 MB audio clip isn't optimized like images)
+    // bloats the request until compaction.
     return {
       ...msg,
       content: msg.content.map((b) => {
         if (b.type !== "tool_result") return b;
         const tr = b as ToolResultContent;
-        if (!tr.contentBlocks?.some((cb) => cb.type === "image")) return b;
+        if (!tr.contentBlocks?.some(isMedia)) return b;
         return {
           ...tr,
           contentBlocks: undefined,
           content:
             (tr.content || "") +
-            "\n[Screenshot was captured and shown previously — image data removed to save context.]",
+            "\n[Media (image/audio) was captured and shown previously — binary data removed to save context.]",
         };
       }),
     };