mixdog 1.3.1 → 1.3.2

package/src/runtime/agent/orchestrator/session/loop/fresh-context.mjs

@@ -5,7 +5,6 @@ import { getProvider, initProviders } from '../../providers/registry.mjs';
 import { resolveMaintenanceRoute } from '../../agent-runtime/maintenance-route.mjs';
 import { resolveSessionContextMeta } from '../manager/context-meta.mjs';
 import { isAccountQuotaError } from '../../providers/account-pool.mjs';
-import { builtinFeatureActive } from '../../runtime-core/builtin-features.mjs';
 import { positiveInt } from '../../../../shared/numbers.mjs';
 import { estimateMessagesTokens, providerTokenCalibration } from '../context-utils.mjs';
 import {
@@ -16,6 +15,8 @@ import {
   COMPACT_TARGET_MIN_TOKENS,
 } from '../compact.mjs';
 import { summarizeOnSharedPrefix } from '../compact/forked-summary.mjs';
+import { normalizeCompactionSummaryMode } from '../compact/summary-mode.mjs';
+import { compactionCacheWarm, lighterSubscriptionModel } from '../compact/summary-route.mjs';
 import { retireCompactionFork } from '../side-question-store.mjs';
 
 // Conversation summarization triggers independently of the post-compact target:
@@ -24,52 +25,103 @@ import { retireCompactionFork } from '../side-question-store.mjs';
 const CONVERSATION_COMPACT_TRIGGER_RATIO = 0.05;
 const CONVERSATION_COMPACT_TRIGGER_MAX_TOKENS = 20_000;
 
-// Select an explicitly configured, enabled maintenance route only. An absent
-// or disabled maintenance role falls back to the conversation's own model,
-// not an unrelated global default. Provider failures/cancellation are not
-// absence and must propagate without silently routing around them.
-export async function resolveCompactionRoute({
+// One summary route: the provider, its model and the window the summary
+// request must fit. `source` names the step: 'session' (the conversation's
+// own model), 'maintenance' (the Maintainer) or 'lighter' (the subscription
+// provider's lighter model).
+function summaryRoute({ sessionRef, provider, providerName, model, fast, source }) {
+  if (!provider || typeof provider.send !== 'function' || !model) {
+    throw new Error(`compact summary route unavailable: ${providerName || 'unknown'}/${model || 'unknown'}`);
+  }
+  const sameModel = providerName === sessionRef?.provider && model === sessionRef?.model;
+  const contextWindow =
+    sameModel && positiveInt(sessionRef?.contextWindow)
+      ? positiveInt(sessionRef.contextWindow)
+      : resolveSessionContextMeta(provider, model, {}, { wholeWindow: true }).contextWindow;
+  return { provider, providerName, model, contextWindow, fast, source };
+}
+
+// The Maintainer's own model when one is set and enabled, whatever the memory
+// or recap settings; null otherwise (an unrelated global default is never
+// borrowed). Provider failures/cancellation are not absence and propagate.
+async function resolveMaintainerRoute({ sessionRef, config, signal, getProviderFn, initProvidersFn }) {
+  const route = resolveMaintenanceRoute({ agent: 'cycle1-agent', config, includeDefault: false });
+  if (!(route?.provider && route?.model && config.providers?.[route.provider]?.enabled !== false)) return null;
+  await initProvidersFn(config.providers || {}, { signal });
+  signal?.throwIfAborted();
+  return summaryRoute({
+    sessionRef,
+    provider: getProviderFn(route.provider),
+    providerName: route.provider,
+    model: route.model,
+    fast: route.fast === true,
+    source: 'maintenance',
+  });
+}
+
+function resolveSessionRoute({ sessionRef, provider, model, getProviderFn }) {
+  const providerName = sessionRef?.provider || provider?.name;
+  return summaryRoute({
+    sessionRef,
+    provider: provider || getProviderFn(providerName),
+    providerName,
+    model: model || sessionRef?.model,
+    source: 'session',
+  });
+}
+
+// The newest lighter model of a subscription provider's saved account
+// catalog; null on any other provider, without a saved catalog, when none is
+// listed, or when the conversation already runs on it.
+async function resolveLighterRoute(input) {
+  const session = resolveSessionRoute(input);
+  const lighter = await lighterSubscriptionModel(session.providerName);
+  input.signal?.throwIfAborted();
+  if (!lighter || lighter === session.model) return null;
+  return summaryRoute({
+    sessionRef: input.sessionRef,
+    provider: session.provider,
+    providerName: session.providerName,
+    model: lighter,
+    source: 'lighter',
+  });
+}
+
+/**
+ * The compaction summary plan (compact/summary-mode.mjs): the saved mode,
+ * whether the session's prompt cache is warm, and the routes in the order
+ * they are tried, each resolved only when reached (null = unavailable, the
+ * next one runs). The conversation's own model is always the last step.
+ */
+export function compactionSummaryPlan({
   sessionRef,
+  sessionId = sessionRef?.id,
   provider,
   model,
   config = loadConfig(),
   signal,
   getProviderFn = getProvider,
   initProvidersFn = initProviders,
-  allowMaintenance = true,
+  now = Date.now(),
 } = {}) {
   signal?.throwIfAborted();
-  const route =
-    allowMaintenance && builtinFeatureActive(config, 'memory') && config.recap?.enabled !== false
-      ? resolveMaintenanceRoute({ agent: 'cycle1-agent', config, includeDefault: false })
-      : null;
-  const useMaintenance = !!(route?.provider && route?.model && config.providers?.[route.provider]?.enabled !== false);
-  const providerName = useMaintenance ? route.provider : sessionRef?.provider || provider?.name;
-  const selectedModel = useMaintenance ? route.model : model || sessionRef?.model;
-  if (useMaintenance) await initProvidersFn(config.providers || {}, { signal });
-  signal?.throwIfAborted();
-  const selectedProvider = useMaintenance ? getProviderFn(providerName) : provider || getProviderFn(providerName);
-  if (!selectedProvider || typeof selectedProvider.send !== 'function' || !selectedModel) {
-    throw new Error(`compact summary route unavailable: ${providerName || 'unknown'}/${selectedModel || 'unknown'}`);
-  }
-  const sameModel = providerName === sessionRef?.provider && selectedModel === sessionRef?.model;
-  const contextWindow =
-    sameModel && positiveInt(sessionRef?.contextWindow)
-      ? positiveInt(sessionRef.contextWindow)
-      : resolveSessionContextMeta(selectedProvider, selectedModel, {}, { wholeWindow: true }).contextWindow;
-  return {
-    provider: selectedProvider,
-    providerName,
-    model: selectedModel,
-    contextWindow,
-    fast: useMaintenance ? route.fast === true : undefined,
-    source: useMaintenance ? 'maintenance' : 'session',
-  };
+  const input = { sessionRef, provider, model, config, signal, getProviderFn, initProvidersFn };
+  const mode = normalizeCompactionSummaryMode(config.compaction);
+  const warm = compactionCacheWarm(sessionId, now);
+  const session = async () => resolveSessionRoute(input);
+  const maintainer = () => resolveMaintainerRoute(input);
+  const lighter = () => resolveLighterRoute(input);
+  let steps = [session];
+  if (mode === 'maintainer') steps = [maintainer, session];
+  else if (mode === 'smart' && !warm) steps = [maintainer, lighter, session];
+  return { mode, warm, steps };
 }
 
-// The isolated summary request on one route. Its input budget belongs to
-// its OWN model, whereas the rebuilt conversation must fit the original
-// session's target/window.
+// The summary request on one route: the conversation alone (earlier summary
+// and dialogue; tool output, skills and injections excluded), never the
+// cached context. Its input budget belongs to its OWN model, split into
+// batches when the conversation is larger, whereas the rebuilt conversation
+// must fit the original session's target/window.
 function summarizeConversation(target, ctx) {
   const { sessionRef, sessionId, signal, sendOpts, compactPolicy } = ctx;
   const summaryWindow = positiveInt(target.contextWindow) || ctx.contextWindow;
@@ -117,24 +169,24 @@ function sumUsage(a, b) {
   return Object.fromEntries(Object.keys(a).map((key) => [key, (a[key] || 0) + (Number(b[key]) || 0)]));
 }
 
-// Summary policy. On the session's own provider and model the summary forks
-// the latest cached request (compact/forked-summary.mjs): the context is
-// already in the prompt cache, so reading it costs a tenth to a twentieth of
-// sending the text-only transcript uncached, and the summary sees the full
-// execution context. A different summary route (the maintenance model)
-// cannot share that cache; there the isolated text-only request runs: on
-// the usage ledger it cost a median $0.16 and 24.5 s against a projected
-// $0.19 and 27 s for a cache-read fork of the main model's median 500k-token
-// context (the fork is cheaper than a same-model isolated request, $0.20).
-// A fork that cannot run or fails falls back to the isolated request.
-async function summarizeOnRoute(route, ctx) {
-  const shared = await summarizeOnSharedPrefix({
-    sessionId: ctx.sessionId,
-    route,
-    conversationInput: ctx.conversationInput,
-    signal: ctx.signal,
-    timeoutMs: ctx.compactPolicy.handoffTimeoutMs,
-  });
+// The summary on one route. While the session's prompt cache is warm, the
+// summary forks the latest cached request on the conversation's own model
+// (compact/forked-summary.mjs): reading the cached context costs a tenth to a
+// twentieth of sending the text-only transcript uncached, and the summary
+// sees the full execution context. A cold cache would be rewritten in full,
+// so the isolated text-only request runs instead; so does any other route
+// (a cache is never shared across models). A fork that cannot run or fails
+// falls back to the isolated request on the same route.
+async function summarizeOnRoute(route, ctx, warm) {
+  const shared = warm
+    ? await summarizeOnSharedPrefix({
+        sessionId: ctx.sessionId,
+        route,
+        conversationInput: ctx.conversationInput,
+        signal: ctx.signal,
+        timeoutMs: ctx.compactPolicy.handoffTimeoutMs,
+      })
+    : { fallback: 'cold_cache' };
   if (shared.generated) return shared.generated;
   ctx.signal?.throwIfAborted();
   const generated = await summarizeConversation(route, ctx);
@@ -145,34 +197,45 @@ async function summarizeOnRoute(route, ctx) {
   };
 }
 
-// A maintenance summary model that is out of quota must not take the whole
-// turn down: the conversation's own model still has budget and can
-// summarize. Only exhaustion reroutes — every other compaction failure
-// (overflow, malformed summary, transport) keeps its existing handling, and
-// an aborted turn stays aborted.
-async function summarizeWithQuotaFallback(ctx, routeInput) {
-  const route = await resolveCompactionRoute(routeInput);
-  try {
-    return { route, generated: await summarizeOnRoute(route, ctx) };
-  } catch (error) {
-    ctx.signal?.throwIfAborted();
-    const status = Number(error?.status || error?.httpStatus || error?.response?.status || 0);
-    const exhausted = error?.code === 'provider_accounts_exhausted' || status === 429 || isAccountQuotaError(error);
-    const fallback =
-      route.source === 'maintenance' && exhausted
-        ? await resolveCompactionRoute({ ...routeInput, allowMaintenance: false })
-        : null;
-    if (!fallback || (fallback.providerName === route.providerName && fallback.model === route.model)) {
-      error.compactRoute = { provider: route.providerName, model: route.model };
-      throw error;
-    }
+// A Maintainer or lighter model that is out of quota or not available to the
+// account must not take the whole turn down: the next route still can
+// summarize. Every other compaction failure (overflow, malformed summary,
+// transport) keeps its existing handling, and an aborted turn stays aborted.
+function fallsToNextRoute(error) {
+  const status = Number(error?.status || error?.httpStatus || error?.response?.status || 0);
+  return (
+    error?.code === 'provider_accounts_exhausted' ||
+    error?.code === 'model_not_found' ||
+    status === 429 ||
+    status === 404 ||
+    isAccountQuotaError(error)
+  );
+}
+
+// Resolving a route (provider init, catalog lookup) is part of its step: a
+// quota or availability failure there moves to the next route like one from
+// the summary request. The conversation's own model is the last step, so its
+// failure always ends the compaction.
+async function summarizeOnPlan(ctx, plan) {
+  const tried = new Set();
+  let failure = null;
+  for (const step of plan.steps) {
+    let route = null;
     try {
-      return { route: fallback, generated: await summarizeOnRoute(fallback, ctx) };
-    } catch (fallbackError) {
-      fallbackError.compactRoute = { provider: fallback.providerName, model: fallback.model };
-      throw fallbackError;
+      route = await step();
+      ctx.signal?.throwIfAborted();
+      const key = route && `${route.providerName}\u0000${route.model}`;
+      if (!route || tried.has(key)) continue;
+      tried.add(key);
+      return { route, generated: await summarizeOnRoute(route, ctx, plan.warm) };
+    } catch (error) {
+      ctx.signal?.throwIfAborted();
+      if (route) error.compactRoute = { provider: route.providerName, model: route.model };
+      if (route?.source === 'session' || !fallsToNextRoute(error)) throw error;
+      failure = error;
     }
   }
+  throw failure;
 }
 
 // The window this compaction must fit (calibrated to the provider's token
@@ -200,7 +263,10 @@ function freshContextBudget({ compactPolicy, sessionRef, provider, compactBudget
   return { contextWindow, hardBudget, conversationInput, conversationTokens, conversationThresholdTokens };
 }
 
-function freshContextBuildOptions({ compactPolicy = {}, sessionId, goalReminderText, activeTurn }, budget) {
+function freshContextBuildOptions(
+  { compactPolicy = {}, sessionId, goalReminderText, activeTurn, referenceLatestAttachments },
+  budget
+) {
   return {
     reserveTokens: compactPolicy.reserveTokens,
     maxBudgetTokens: budget.hardBudget,
@@ -209,6 +275,7 @@ function freshContextBuildOptions({ compactPolicy = {}, sessionId, goalReminderT
     sessionId,
     latestUserPrefix: goalReminderText,
     activeTurn,
+    referenceLatestAttachments: referenceLatestAttachments === true,
   };
 }
 
@@ -230,6 +297,27 @@ export function previewFreshContextCompaction(input) {
   return { beforeTokens, afterTokens, reducesTokens: afterTokens < beforeTokens, summaryTriggered };
 }
 
+function buildFreshContextResult(
+  { messages, compactBudgetTokens, buildOptions, requireReduction, sessionId },
+  handoffText
+) {
+  const result = freshContextCompactMessages(messages, compactBudgetTokens, { ...buildOptions, handoffText });
+  // A generated summary can differ from its prediction. Never replace the
+  // original with an automatic result that is equal-sized or larger.
+  if (requireReduction && estimateMessagesTokens(result.messages) >= estimateMessagesTokens(messages)) {
+    return {
+      ...result,
+      messages,
+      freshContext: false,
+      skipped: true,
+      diagnostics: { ...result.diagnostics, noOp: true, reason: 'no_token_reduction' },
+    };
+  }
+  // The rewritten transcript is no longer what the saved request carried.
+  if (result.freshContext) retireCompactionFork(sessionId);
+  return result;
+}
+
 export async function runFreshContextCompact({
   sessionRef,
   messages,
@@ -246,35 +334,19 @@ export async function runFreshContextCompact({
   getProviderFn,
   initProvidersFn,
   requireReduction = false,
+  referenceLatestAttachments = false,
 } = {}) {
   const startedAt = Date.now();
   signal?.throwIfAborted();
   const { contextWindow, hardBudget, conversationInput, conversationTokens, conversationThresholdTokens } =
     freshContextBudget({ compactPolicy, sessionRef, provider, compactBudgetTokens, messages });
   const summaryTriggered = conversationTokens >= conversationThresholdTokens;
-  const build = (handoffText) => {
-    const result = freshContextCompactMessages(messages, compactBudgetTokens, {
-      ...freshContextBuildOptions(
-        { compactPolicy, sessionId, goalReminderText, activeTurn },
-        { contextWindow, hardBudget }
-      ),
-      handoffText,
-    });
-    // A generated summary can differ from its prediction. Never replace the
-    // original with an automatic result that is equal-sized or larger.
-    if (requireReduction && estimateMessagesTokens(result.messages) >= estimateMessagesTokens(messages)) {
-      return {
-        ...result,
-        messages,
-        freshContext: false,
-        skipped: true,
-        diagnostics: { ...result.diagnostics, noOp: true, reason: 'no_token_reduction' },
-      };
-    }
-    // The rewritten transcript is no longer what the saved request carried.
-    if (result.freshContext) retireCompactionFork(sessionId);
-    return result;
-  };
+  const buildOptions = freshContextBuildOptions(
+    { compactPolicy, sessionId, goalReminderText, activeTurn, referenceLatestAttachments },
+    { contextWindow, hardBudget }
+  );
+  const build = (handoffText) =>
+    buildFreshContextResult({ messages, compactBudgetTokens, buildOptions, requireReduction, sessionId }, handoffText);
   const pipeline = {
     mode: summaryTriggered ? 'conversation-summary' : 'rules',
     conversationTokens,
@@ -291,7 +363,17 @@ export async function runFreshContextCompact({
       pipeline: { ...pipeline, totalMs: Date.now() - startedAt },
     });
   }
-  const { route, generated } = await summarizeWithQuotaFallback(
+  const plan = compactionSummaryPlan({
+    sessionRef,
+    sessionId,
+    provider,
+    model,
+    config,
+    signal,
+    getProviderFn,
+    initProvidersFn,
+  });
+  const { route, generated } = await summarizeOnPlan(
     {
       sessionRef,
       sessionId,
@@ -303,7 +385,7 @@ export async function runFreshContextCompact({
       contextWindow,
       conversationInput,
     },
-    { sessionRef, provider, model, config, signal, getProviderFn, initProvidersFn }
+    plan
   );
   signal?.throwIfAborted();
   const result = build(generated.summary);
@@ -315,6 +397,8 @@ export async function runFreshContextCompact({
     pipeline: {
       ...pipeline,
       handoffSource: 'session-local',
+      summaryMode: plan.mode,
+      cacheWarm: plan.warm,
       summaryRoute: route.source,
       summaryProvider: route.providerName,
       summaryModel: route.model,

package/src/runtime/agent/orchestrator/session/loop/pre-dispatch-deny.mjs

@@ -16,7 +16,8 @@ import { isOffReadonlySurface } from './deferred-call-through.mjs';
 import { BRIDGE_CALL_TOOL_NAME, bridgeErrorText, isToolBridgeEnabled } from '../../runtime-core/tool-bridge.mjs';
 import { sessionAllowlistExcludes, sessionDisallows } from '../../runtime-core/deferred-tool-availability.mjs';
 import { providerToolExclusionReason } from './provider-tool-exclusions.mjs';
-import { agentMcpToolPermission, projectMcpToolDisabled } from '../../mcp/agent-connectors.mjs';
+import { workflowOverlayDenial } from '../manager/workflow-switch-notice.mjs';
+import { agentMcpToolPermission, connectorPolicyAgentOf, projectMcpToolDisabled } from '../../mcp/agent-connectors.mjs';
 
 const WORKER_DENIED_TOOLS = new Set(['agent', 'ask_user', 'session']);
 const BRIDGE_DISCOVERY_TOOL_NAMES = new Set(['load_tool']);
@@ -120,12 +121,15 @@ export function preDispatchDenyForSession(sessionRef, call) {
   if (!bridgeDiscovery && sessionAllowlistExcludes(sessionRef, schemaName)) {
     return `Error: tool "${name}" is not available on this session's schema allowlist.`;
   }
+  // A workflow switched mid-conversation keeps the schema; its denials apply here.
+  const workflowDenial = workflowOverlayDenial(sessionRef, schemaName);
+  if (workflowDenial) return workflowDenial;
   if (sessionDisallows(sessionRef, schemaName)) {
     return `Error: tool "${name}" is not available in this session.`;
   }
   // An agent's connectors: a tool of a server it does not mount, or one set
   // to `disabled`, stays refused though the process-wide registry knows it.
-  if (agentMcpToolPermission(sessionRef?.agent, schemaName) === 'disabled') {
+  if (agentMcpToolPermission(connectorPolicyAgentOf(sessionRef), schemaName) === 'disabled') {
     return `Error: tool "${name}" is not available to this agent.`;
   }
   // The project the session runs in may switch a connector off as well.

package/src/runtime/agent/orchestrator/session/loop/route-fallback.mjs

@@ -67,8 +67,7 @@ function annotateEndedChain(session, error, skipped = null) {
 
 // A context overflow moves only to a model whose window is larger.
 async function nextContextGrows(state, next) {
-  const config = ensureProviderEnabled(loadConfig(), next.provider);
-  await initProviders(config.providers, { signal: state.signal });
+  await initProviders(ensureProviderEnabled(loadConfig(), next.provider), { signal: state.signal });
   state.throwIfAborted();
   const provider = getProvider(next.provider);
   if (!provider) return false;
@@ -93,8 +92,7 @@ export async function advanceAgentRoute(state, error) {
     return false;
   }
   state.throwIfAborted();
-  const config = ensureProviderEnabled(loadConfig(), next.provider);
-  await initProviders(config.providers, { signal: state.signal });
+  await initProviders(ensureProviderEnabled(loadConfig(), next.provider), { signal: state.signal });
   state.throwIfAborted();
   const provider = getProvider(next.provider);
   if (!provider) throw new Error(`Provider "${next.provider}" not available`);
@@ -128,7 +126,9 @@ export async function advanceAgentRoute(state, error) {
       contextTokens: next.contextTokens,
       selectedContextWindow: resolveSessionContextMeta(provider, next.model, next).rawContextWindow,
     },
-    { crossProvider: true }
+    // The live turn object is what changes: the route is applied to it in place, never to
+    // another copy of the id (a disk reload after a generation takeover).
+    { crossProvider: true, session }
   );
   if (!updated) throw new Error('agent session closed during model fallback');
   updated.routeFallbackIndex = index + 1;

package/src/runtime/agent/orchestrator/session/loop/send-phase.mjs

@@ -4,6 +4,7 @@
  * consume a retry verdict, and settle a completed send into the loop state.
  */
 import { traceCacheBreak } from '../../cache-break-trace.mjs';
+import { anthropicPrefixChanges } from '../../providers/lib/anthropic-prefix-trace.mjs';
 import { resolveLiveToolCwd } from './tool-exec.mjs';
 import { notifySkillsApplied, prepareExplicitSkills, recordAppliedSkills } from '../explicit-skills.mjs';
 import { addUsage, usageDeltaEvent } from './usage.mjs';
@@ -352,6 +353,8 @@ function traceActualCacheMiss(state, sent, response, { previousGuardState, previ
         previousCachedPrefixTokens: baseline,
         idleMs,
         missingPrefixGuardBaseline: !previousGuardState,
+        // Which wire block moved ('none': same bytes, so the cache itself dropped it).
+        ...anthropicPrefixChanges(sessionId),
       },
       state.cacheBreakTraceOptions
     );

package/src/runtime/agent/orchestrator/session/loop/steering.mjs

@@ -1,6 +1,7 @@
 // Steering-message normalization/merge helpers.
 // Merges queued steering entries into a single content payload + display text.
 import { stableMessageId } from '../../../../shared/transcript-metadata.mjs';
+import { raiseTurnHop } from '../../../../shared/bot-hops.mjs';
 
 function steeringContentText(content) {
   if (typeof content === 'string') return content;
@@ -140,6 +141,8 @@ function injectSteeringEntry(merged, { messages, opts, stage, onSkillPrompt }) {
   // gets it back (onSteerMessage) for the row it draws. A steered prompt
   // keeps the id the surface gave it, else gets one.
   const messageId = stableMessageId(merged.transcriptMeta?.messageId);
+  // A bot's message at a higher hop makes the running turn bot-descended at that hop.
+  raiseTurnHop(opts.session, merged.transcriptMeta);
   const steeringTranscriptMeta =
     merged.transcriptMeta && typeof merged.transcriptMeta === 'object'
       ? { at: submittedAt ?? injectedAt, ...merged.transcriptMeta, messageId }

package/src/runtime/agent/orchestrator/session/loop/tool-exec/before-hook.mjs

@@ -6,15 +6,20 @@ import { resolvePreToolAskApproval } from '../tool-helpers.mjs';
 import { runAbortable, throwIfAborted } from '../../../../../shared/abort-race.mjs';
 import { evaluateExecPolicy } from '../../../tools/bash-policy-scan.mjs';
 import { beginSessionApprovalWait } from '../../manager/runtime-liveness.mjs';
-import { agentMcpToolPermission } from '../../../mcp/agent-connectors.mjs';
-import { humanGateDecision, recordHumanDecision } from '../../human-gate/gate.mjs';
+import { agentMcpToolPermission, writeAgentMcpToolPermission } from '../../../mcp/agent-connectors.mjs';
+import {
+  actingContactBotId,
+  humanGateDecision,
+  recordHumanDecision,
+  rememberSurfaceOf,
+} from '../../human-gate/gate.mjs';
 import { applyEditedArgs } from '../../human-gate/requests.mjs';
 
 const isArgsObject = (value) => value && typeof value === 'object' && !Array.isArray(value);
 
 async function askApproval(
   call,
-  { callerSessionId, executeOpts, toolApprovalHook, decision, request = null, gate = null }
+  { callerSessionId, executeOpts, toolApprovalHook, decision, request = null, gate = null, onApproved = null }
 ) {
   const askReason = String(decision?.reason || 'approval requested by hook').trim();
   // While the user decides, the session is waiting on them, not working.
@@ -46,26 +51,52 @@ async function askApproval(
   }
   // The user approved this very call on the richer outbound card.
   if (request?.kind === 'outbound') call.outboundApproved = true;
+  await onApproved?.(approval);
   return null;
 }
 
+/** The renderer translates this exact text (desktop-toasts.tsx ALLOW_NOT_SAVED_TEXT). */
+export const ALLOW_NOT_SAVED_NOTICE = 'Allowed this once. The setting could not be saved.';
 export const CONNECTOR_APPROVAL_REASON = 'This connector tool is set to ask before it runs for this agent.';
 
 /**
  * A connector tool the running agent set to `needs_approval` asks through the
  * ordinary approval hook, whatever the PreToolUse hooks decided. Run after
  * them, on the final call: a renamed call is judged under its final name.
- * A call the outbound card already got approved is not asked a second time.
+ * A call the outbound gate owns (its card approved it, or a remembered
+ * outbound grant answered it) is not asked a second time.
  * @returns {Promise<{ denial: string } | null>} the denial, or null to run
  */
 export function applyConnectorApproval(call, { agentId, callerSessionId, executeOpts, toolApprovalHook }) {
   if (call.outboundApproved) return null;
   if (agentMcpToolPermission(agentId, call.name) !== 'needs_approval') return null;
+  // "Always allow" is offered only to the contact bot that is acting, for its
+  // own policy entry for this one tool: never another bot, Mixy or the Lead.
+  const botId = actingContactBotId(callerSessionId);
+  const rememberable = Boolean(botId) && botId === agentId;
   return askApproval(call, {
     callerSessionId,
     executeOpts,
     toolApprovalHook,
     decision: { reason: CONNECTOR_APPROVAL_REASON },
+    request: rememberable
+      ? {
+          kind: 'approval',
+          agentId: botId,
+          remember: ['once', 'agent'],
+          rememberAt: rememberSurfaceOf(callerSessionId),
+        }
+      : null,
+    onApproved: async (approval) => {
+      if (!rememberable || approval?.remember !== 'agent') return;
+      try {
+        if (await writeAgentMcpToolPermission(botId, call.name, 'auto')) return;
+      } catch {
+        // fall through to the notice below
+      }
+      // Not saved: this call still runs once, and the next one asks again.
+      toolApprovalHook?.notice?.(ALLOW_NOT_SAVED_NOTICE, 'warn');
+    },
   });
 }
 
@@ -120,7 +151,7 @@ export async function applyBeforeToolHook({
     // Judged as the call will run: only a rewriting decision changes name/args.
     const hookAction = String(hookDecision?.action || hookDecision?.decision || '').toLowerCase();
     const rewritten = hookAction === 'ask' || hookAction === 'modify' || hookAction === 'rewrite';
-    const { decision, request, gate } = await humanGateDecision(
+    const { decision, request, gate, remembered } = await humanGateDecision(
       {
         name:
           rewritten && typeof hookDecision?.name === 'string' && hookDecision.name.trim()
@@ -132,6 +163,8 @@ export async function applyBeforeToolHook({
       { sessionId: callerSessionId, mcpScopeId }
     );
     const action = String(decision?.action || decision?.decision || '').toLowerCase();
+    // A remembered outbound grant answered this call: the connector ask is not repeated.
+    if (remembered) call.outboundApproved = true;
     if (action === 'deny' || action === 'block') {
       const reason = decision?.reason ? `: ${decision.reason}` : '';
       return { denial: `Error: tool "${name}" denied by hook${reason}` };

package/src/runtime/agent/orchestrator/session/loop/tool-exec/dispatch.mjs

@@ -17,6 +17,26 @@ import { isOnDeferredToolSurface } from '../deferred-call-through.mjs';
 import { _executeCodeGraphToolLazy } from '../../manager/runtime-loaders.mjs';
 import { requiresReadBody } from '../tool-classify.mjs';
 import { executeCursorNativeBuiltin } from '../../../tools/builtin/external-tool-adapters.mjs';
+import { providerNativePdf, providerReadsImages } from '../../../providers/registry.mjs';
+import { getModelMetadataSync } from '../../../../../shared/llm/model-catalog.mjs';
+
+/**
+ * How read returns a PDF to this session's model. Native PDF support decides
+ * only whether a short PDF may arrive whole as a document block. A scanned
+ * page arrives as a page image whenever the model sees images — the provider
+ * sends image input (only the text-only local runtime does not) and the
+ * catalog does not say the model lacks it — and as OCR text otherwise.
+ */
+export function pdfReadModes(
+  sessionRef,
+  { nativePdf = providerNativePdf, readsImages = providerReadsImages, catalogRow = getModelMetadataSync } = {}
+) {
+  const provider = sessionRef?.provider;
+  const model = sessionRef?.model;
+  const seesImages =
+    readsImages(provider) && (model ? catalogRow(model, provider)?.supportsVision : undefined) !== false;
+  return { pdfPageMode: seesImages ? 'image' : 'ocr', pdfNativeDocument: nativePdf(provider) };
+}
 
 function dispatchMcp(name, args, { cwd, callerSessionId, sessionRef, executeOpts }) {
   const mcpScopeId = sessionRef?.mcpScopeId || null;
@@ -107,6 +127,7 @@ export function dispatchToolCall({ name, args }, ctx) {
         : {}),
       // Runtime-granted only; any value inherited from executeOpts is overridden.
       elevationApproved: ctx.elevationApproved === true,
+      ...pdfReadModes(sessionRef),
     };
     return executeCursorNativeBuiltin(
       name,

package/src/runtime/agent/orchestrator/session/loop/tool-exec.mjs

@@ -6,6 +6,7 @@
 //   tool-exec/after-hook.mjs         — PostToolUse result override
 //   tool-exec/read-only-deadline.mjs — bounded read-only I/O with partial-output grace
 import { isMcpTool } from '../../mcp/client.mjs';
+import { connectorPolicyAgentOf } from '../../mcp/agent-connectors.mjs';
 import { prepareDeferredToolCallThrough } from './deferred-call-through.mjs';
 import { refreshDeferredMcpToolCatalog } from '../../runtime-core/tool-catalog.mjs';
 import { bridgeTargetUnavailable } from '../../runtime-core/tool-bridge.mjs';
@@ -54,7 +55,7 @@ async function executeToolOwned(name, args, cwd, callerSessionId, sessionRef, ex
   });
   if (hooked.denial) return hooked.denial;
   const connectorDenied = await applyConnectorApproval(hooked, {
-    agentId: sessionRef?.agent,
+    agentId: connectorPolicyAgentOf(sessionRef),
     callerSessionId,
     executeOpts,
     toolApprovalHook,