@oh-my-pi/pi-agent-core 16.0.11 → 16.1.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [16.1.0] - 2026-06-19
+
+### Added
+
+- Added `SoftToolRequirement` support to `getToolChoice`: a host can require a tool by returning a soft requirement instead of a hard `ToolChoice`. The loop injects the supplied reminder once (leaving `tool_choice` on auto), and escalates to a one-turn forced choice — skipping any detour tool batch — only if the model fails to call the required tool, avoiding the provider message-cache invalidation of forcing every turn.
+- Added `pruneToolDescriptions` option to reduce token usage by stripping tool descriptions from provider-bound specs
+
+### Fixed
+
+- Improved token estimation accuracy for compaction summaries containing multi-block content
+
 ## [16.0.11] - 2026-06-19
 
 ### Changed

package/dist/types/agent-loop.d.ts

@@ -54,7 +54,7 @@ export declare function agentLoopContinueDetailed(context: AgentContext, config:
     readonly stream: EventStream<AgentEvent, AgentMessage[]>;
     readonly detailed: () => Promise<AgentLoopDetailedResult>;
 };
-export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean, exampleDialect?: Dialect): Context["tools"];
+export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean, exampleDialect?: Dialect, pruneDescriptions?: boolean): Context["tools"];
 /** Resolve the human-readable reason an abort carried. A caller that aborts via
  *  `AbortController.abort(reason)` with a string or a non-`AbortError` `Error`
  *  (e.g. the coding agent's user-interrupt label) gets that text surfaced on the

package/dist/types/agent.d.ts

@@ -2,7 +2,7 @@ import { type ApiKey, type AssistantMessage, type AssistantMessageEvent, type Co
 import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context";
-import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AsideMessage, StreamFn, ToolCallContext } from "./types";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AsideMessage, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types";
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
 }
@@ -129,6 +129,12 @@ export interface AgentOptions {
     transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
     /** Enable intent tracing schema injection/stripping in the harness. */
     intentTracing?: boolean;
+    /**
+     * Strip tool descriptions from provider-bound tool specs (top-level + nested
+     * schema annotations). Use when the full catalog is rendered into the system
+     * prompt so descriptions are not duplicated on the wire. Native tool calling only.
+     */
+    pruneToolDescriptions?: boolean;
     /** Owned tool-calling dialect. Undefined keeps provider-native tool calling. */
     dialect?: Dialect;
     /**
@@ -138,8 +144,8 @@ export interface AgentOptions {
      * the loop's {@link AgentLoopConfig.abortOnFabricatedToolResult}.
      */
     abortOnFabricatedToolResult?: boolean;
-    /** Dynamic tool choice override, resolved per LLM call. */
-    getToolChoice?: () => ToolChoice | undefined;
+    /** Dynamic tool-choice directive (hard {@link ToolChoice} or {@link SoftToolRequirement}), resolved once per turn. */
+    getToolChoice?: () => ToolChoiceDirective | undefined;
     /**
      * Cursor exec handlers for local tool execution.
      */

package/dist/types/append-only-context.d.ts

@@ -27,6 +27,8 @@ export interface BuildOptions {
     /** Inject the `_i` intent field into tool schemas (must match agent-loop's normalizeTools). */
     intentTracing: boolean;
     exampleDialect?: Dialect;
+    /** Strip tool descriptions from the provider-bound specs (must match normalizeTools). */
+    pruneToolDescriptions?: boolean;
 }
 /**
  * A frozen prefix (system prompt + tools) that produces stable byte

package/dist/types/compaction/messages.d.ts

@@ -33,7 +33,11 @@ export interface CompactionSummaryMessage {
     shortSummary?: string;
     tokensBefore: number;
     providerPayload?: ProviderPayload;
-    /** Snapcompact frames archived by this compaction; appended as image blocks after the summary text. */
+    /** Runtime-only ordered archive blocks for snapcompact: old text region,
+     *  imaged middle, then new text region. When present, `summary` is already
+     *  the final lead-in text (no legacy wrapper applied). */
+    blocks?: (TextContent | ImageContent)[];
+    /** Snapcompact image blocks, kept for display counts / legacy consumers. */
     images?: ImageContent[];
     timestamp: number;
 }
@@ -50,7 +54,7 @@ export type ConvertToLlm = (messages: AgentMessage[]) => Message[];
 export declare function renderBranchSummaryContext(summary: string): string;
 export declare function renderCompactionSummaryContext(summary: string): string;
 export declare function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage;
-export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, shortSummary?: string, providerPayload?: ProviderPayload, images?: ImageContent[]): CompactionSummaryMessage;
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, shortSummary?: string, providerPayload?: ProviderPayload, images?: ImageContent[], blocks?: (TextContent | ImageContent)[]): CompactionSummaryMessage;
 export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown | undefined, timestamp: string, attribution?: MessageAttribution): CustomMessage;
 /**
  * Transform a single core-domain agent message to its LLM form; `undefined`

package/dist/types/compaction/pruning.d.ts

@@ -19,6 +19,24 @@ export interface PruneConfig {
     supersedeKey?: SupersedeKeyFn;
     /** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
     pruneUseless?: boolean;
+    /**
+     * Compaction boundary: the `firstKeptEntryId` of the latest compaction on
+     * the branch. Entries at indices BEFORE this id are summarized away and never
+     * sent to the model, so mutating them only churns persisted history without
+     * shrinking the prompt — they are skipped. Undefined = no compaction (the
+     * whole branch is sent).
+     */
+    keepBoundaryId?: string;
+    /**
+     * Prompt-cache guard. When set, a tool result whose all-message suffix
+     * (tokens of every message after it) EXCEEDS this is part of the warm,
+     * already-sent cache prefix: mutating it forces the provider to re-write the
+     * whole suffix (cacheWrite premium). Such results — including superseded and
+     * useless ones, which otherwise bypass {@link protectTokens} — are left for
+     * compaction/shake (which rebuild the cache anyway) to reclaim. Undefined =
+     * no cache guard (legacy: superseded/useless prune at any depth).
+     */
+    cacheWarmSuffixTokens?: number;
 }
 export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
 export interface PruneResult {
@@ -44,10 +62,22 @@ export interface SupersedePruneConfig {
     pruneUseless?: boolean;
     /** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
     suffixTokenLimit?: number;
-    /** Prune all candidates when the last message is at least this old (prompt cache is cold anyway). Default 30 min. */
+    /**
+     * Prune all candidates when the last message is at least this old: the
+     * provider prompt cache is then cold, so re-writing it is free. MUST exceed
+     * the cache retention (Anthropic "long" = 1h) or a still-warm prefix is busted
+     * by the flush. Default 30 min — callers on long retention override it.
+     */
     idleFlushMs?: number;
     /** Clock override for tests. */
     now?: number;
+    /**
+     * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+     * before it are summarized away and never sent, so they are skipped in every
+     * path — including the idle flush — to avoid pointless history churn.
+     * Undefined = no compaction (the whole branch is sent).
+     */
+    keepBoundaryId?: string;
     /** Tool-result protection matchers (same contract as {@link PruneConfig.protectedTools}). */
     protectedTools: ProtectedToolMatcher[];
 }
@@ -57,7 +87,8 @@ export interface SupersedePruneConfig {
  * flagged contextually useless. Cheap, incremental, and prompt-cache-aware: a
  * candidate is pruned now only when the suffix after it is small (tail case —
  * the read→edit→read loop) or when the context has been idle long enough that
- * the provider cache is cold anyway (then ALL candidates flush).
+ * the provider cache is cold anyway (then all still-sent candidates flush).
+ * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
  */
 export declare function pruneSupersededToolResults(entries: SessionEntry[], config: SupersedePruneConfig): PruneResult;
 export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;

package/dist/types/compaction/shake.d.ts

@@ -20,6 +20,14 @@ export interface ShakeConfig {
     protectedTools: ProtectedToolMatcher[];
     /** Minimum token size for a fenced/XML block to be eligible. */
     fenceMinTokens: number;
+    /**
+     * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+     * before it are summarized away and never sent, so they are skipped — shaking
+     * them only churns persisted history. Undefined = no compaction (whole branch
+     * is sent). Note: shake still elides the warm cached prefix at/after the
+     * boundary — that is its job as a compaction-class reducer.
+     */
+    keepBoundaryId?: string;
 }
 /** Auto-shake config: protects the live tail, conservative thresholds. */
 export declare const DEFAULT_SHAKE_CONFIG: ShakeConfig;

package/dist/types/types.d.ts

@@ -13,6 +13,38 @@ export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMe
  * (e.g. dropping late diagnostics a newer edit superseded).
  */
 export type AsideMessage = AgentMessage | (() => AgentMessage | null);
+/**
+ * A soft tool requirement: the host wants `toolName` called before the loop
+ * runs other tools or yields, but WITHOUT paying the forced-`toolChoice` cost
+ * up front (changing `tool_choice` invalidates the provider message cache).
+ * Returned from {@link AgentLoopConfig.getToolChoice} in place of a hard
+ * {@link ToolChoice}: the loop injects `reminder` once when a new `id` becomes
+ * active, runs with `toolChoice` unchanged, and escalates to a one-turn forced
+ * choice only if the model fails to call `toolName`. Auto-clears when the host
+ * stops returning it or `toolName` is no longer an active tool.
+ */
+export interface SoftToolRequirement {
+    /** Discriminates a soft requirement from a hard {@link ToolChoice}. */
+    soft: true;
+    /**
+     * Stable id of the *current* requirement. The loop injects `reminder` when
+     * this id first becomes active and again whenever it changes (e.g. one
+     * stacked preview resolves and the next becomes the head), but never
+     * re-injects for an unchanged id across turns.
+     */
+    id: string;
+    /** Tool that must be called before the loop runs other tools or yields. */
+    toolName: string;
+    /** Host-owned reminder messages, injected once per `id` activation. */
+    reminder: AgentMessage[];
+}
+/**
+ * A per-turn tool-choice directive: either a hard provider {@link ToolChoice}
+ * (applied verbatim) or a {@link SoftToolRequirement} (remind-then-escalate).
+ */
+export type ToolChoiceDirective = ToolChoice | SoftToolRequirement;
+/** True when a {@link ToolChoiceDirective} is a soft requirement, not a hard choice. */
+export declare function isSoftToolRequirement(directive: ToolChoiceDirective | undefined): directive is SoftToolRequirement;
 /**
  * Configuration for the agent loop.
  */
@@ -165,6 +197,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * then strips from arguments before executing tools.
      */
     intentTracing?: boolean;
+    /**
+     * Strip tool descriptions (top-level + nested schema annotations) from the
+     * provider-bound tool specs. Use when the full catalog is rendered into the
+     * system prompt instead, so descriptions are not duplicated on the wire.
+     */
+    pruneToolDescriptions?: boolean;
     /**
      * Owned tool calling dialect.
      *
@@ -205,10 +243,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      */
     onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
     /**
-     * Dynamic tool choice override, resolved per LLM call.
-     * When set and returns a value, overrides the static `toolChoice`.
+     * Dynamic tool-choice directive, resolved once per turn. Returns a hard
+     * {@link ToolChoice} (applied verbatim, overriding the static `toolChoice`),
+     * a {@link SoftToolRequirement} (the loop reminds-then-escalates instead of
+     * forcing `tool_choice` immediately, so a model that complies with the
+     * reminder pays no message-cache invalidation), or `undefined` to fall back
+     * to the static `toolChoice`.
      */
-    getToolChoice?: () => ToolChoice | undefined;
+    getToolChoice?: () => ToolChoiceDirective | undefined;
     /**
      * Dynamic reasoning effort override, resolved per LLM call.
      * When set and returns a value, overrides the static `reasoning` captured

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "16.0.11",
+	"version": "16.1.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,12 +35,12 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "16.0.11",
-		"@oh-my-pi/pi-catalog": "16.0.11",
-		"@oh-my-pi/pi-natives": "16.0.11",
-		"@oh-my-pi/pi-utils": "16.0.11",
-		"@oh-my-pi/pi-wire": "16.0.11",
-		"@oh-my-pi/snapcompact": "16.0.11",
+		"@oh-my-pi/pi-ai": "16.1.1",
+		"@oh-my-pi/pi-catalog": "16.1.1",
+		"@oh-my-pi/pi-natives": "16.1.1",
+		"@oh-my-pi/pi-utils": "16.1.1",
+		"@oh-my-pi/pi-wire": "16.1.1",
+		"@oh-my-pi/snapcompact": "16.1.1",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -14,8 +14,11 @@ import {
 	resolveApiKeyOnce,
 	seedApiKeyResolver,
 	streamSimple,
+	stripSchemaDescriptions,
+	type ToolChoice,
 	type ToolResultMessage,
 	type TSchema,
+	toolWireSchema,
 	validateToolArguments,
 	zodToWireSchema,
 } from "@oh-my-pi/pi-ai";
@@ -66,6 +69,7 @@ import type {
 	AsideMessage,
 	StreamFn,
 } from "./types";
+import { isSoftToolRequirement } from "./types";
 import { yieldIfDue } from "./utils/yield";
 
 /** Stop-details marker for a provider error after assistant content/tool args already streamed. */
@@ -82,6 +86,27 @@ const ABORTED: unique symbol = Symbol("agent-loop-aborted");
  */
 const MAX_PAUSED_TURN_CONTINUATIONS = 8;
 
+/**
+ * Cap on consecutive forced escalations for a single soft tool requirement.
+ * A forced `toolChoice` guarantees the call, so this is purely defensive: if a
+ * model somehow never satisfies the requirement, give up forcing rather than
+ * spin the loop. Reset whenever the requirement id changes or clears.
+ */
+const MAX_SOFT_TOOL_ESCALATIONS = 3;
+
+/**
+ * Whether a hard `toolChoice` for a turn conflicts with a pending soft tool
+ * requirement — i.e. forbids tools (`"none"`) or forces a *different* specific
+ * tool. `"auto"`/`"required"`/`"any"` and a same-tool force still let the model
+ * satisfy the requirement, so they do not conflict and the soft gate stays active.
+ */
+function hardToolChoiceBlocks(choice: ToolChoice | undefined, requiredTool: string): boolean {
+	if (choice === undefined) return false;
+	if (typeof choice === "string") return choice === "none";
+	const name = choice.type === "tool" ? choice.name : "function" in choice ? choice.function.name : choice.name;
+	return name !== requiredTool;
+}
+
 /**
  * Cadence (ms) for polling queued steering while an `interruptible` tool is in
  * flight, so a steer cuts the wait short instead of sitting idle until the
@@ -518,7 +543,13 @@ function normalizeMessagesForProvider(
 	});
 }
 
-function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" = "require"): unknown {
+const INTENT_FIELD_DESCRIPTION = "concise intent";
+
+function injectIntentIntoSchema(
+	schema: unknown,
+	mode: "require" | "optional" = "require",
+	describeIntent = true,
+): unknown {
 	if (!schema || typeof schema !== "object" || Array.isArray(schema)) return schema;
 	const schemaRecord = schema as Record<string, unknown>;
 	const propertiesValue = schemaRecord.properties;
@@ -544,10 +575,9 @@ function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" =
 	return {
 		...schemaRecord,
 		properties: {
-			[INTENT_FIELD]: {
-				type: "string",
-				description: "Concise intent in present participle form (2-6 words) strictly on a single line, no newlines",
-			},
+			[INTENT_FIELD]: describeIntent
+				? { type: "string", description: INTENT_FIELD_DESCRIPTION }
+				: { type: "string" },
 			...properties,
 		},
 		...(mode === "require" ? { required: [...required, INTENT_FIELD] } : {}),
@@ -558,26 +588,36 @@ export function normalizeTools(
 	tools: AgentContext["tools"],
 	injectIntent: boolean,
 	exampleDialect?: Dialect,
+	pruneDescriptions = false,
 ): Context["tools"] {
 	injectIntent = injectIntent && Bun.env.PI_NO_INTENT !== "1";
 	return tools?.map(t => {
 		const intentMode = resolveIntentMode(t.intent);
+		const doInjectIntent = injectIntent && intentMode !== "omit";
+		// When the full catalog is rendered into the system prompt, ship the tool
+		// specs without their descriptions (top-level + nested schema annotations)
+		// so they are not duplicated on the wire. Strip the STABLE wire schema (the
+		// memoized `stripSchemaDescriptions` result is reused across requests), then
+		// re-inject `_i` (without its hint, which `describeIntent: false` omits) so
+		// intent tracing keeps the field while no descriptions ride the wire.
+		if (pruneDescriptions) {
+			let parameters = stripSchemaDescriptions(toolWireSchema(t)) as TSchema;
+			if (doInjectIntent) parameters = injectIntentIntoSchema(parameters, intentMode, false) as TSchema;
+			return { ...t, parameters, description: "" };
+		}
 		let parameters: TSchema = t.parameters;
-		if (injectIntent && intentMode !== "omit") {
+		if (doInjectIntent) {
 			if (isZodSchema(parameters)) {
-				const wired = zodToWireSchema(parameters);
-				parameters = injectIntentIntoSchema(wired, intentMode) as TSchema;
+				parameters = injectIntentIntoSchema(zodToWireSchema(parameters), intentMode) as TSchema;
 			} else if (isArkSchema(parameters)) {
-				const wired = arkToWireSchema(parameters);
-				parameters = injectIntentIntoSchema(wired, intentMode) as TSchema;
+				parameters = injectIntentIntoSchema(arkToWireSchema(parameters), intentMode) as TSchema;
 			} else {
 				parameters = injectIntentIntoSchema(parameters, intentMode) as TSchema;
 			}
 		}
 		const description = t.description ?? "";
-		const injectExampleIntent = injectIntent && intentMode !== "omit";
 		const examplesBlock = exampleDialect
-			? renderToolExamples({ ...t, parameters }, exampleDialect, injectExampleIntent ? INTENT_FIELD : undefined)
+			? renderToolExamples({ ...t, parameters }, exampleDialect, doInjectIntent ? INTENT_FIELD : undefined)
 			: "";
 		const finalDescription = examplesBlock ? `${description}\n\n${examplesBlock}` : description;
 		return { ...t, parameters, description: finalDescription };
@@ -713,6 +753,19 @@ async function runLoopBody(
 		let harmonyTruncateResumeCount = 0;
 		let pausedTurnContinuations = 0;
 
+		// Soft tool requirement lifecycle (reminder → escalate; see SoftToolRequirement).
+		// `forcedToolChoice` carries a one-turn escalation into the next model call. It
+		// overrides the static toolChoice but NEVER the host's hard getToolChoice().
+		let softRequirementId: string | undefined;
+		let forcedToolChoice: ToolChoice | undefined;
+		let softEscalations = 0;
+		// Resolved once per logical turn at the fetch site below and reused across
+		// Harmony-leak re-samples (which re-enter the same turn) so the consuming
+		// getToolChoice is never advanced twice; the flag resets at the message boundary.
+		let hostToolChoice: ToolChoice | undefined;
+		let softRequiredTool: string | undefined;
+		let directiveResolvedForTurn = false;
+
 		// Outer loop: continues when queued follow-up messages arrive after agent would stop
 		while (true) {
 			let hasMoreToolCalls = true;
@@ -748,6 +801,41 @@ async function runLoopBody(
 					await config.syncContextBeforeModelCall(currentContext);
 				}
 
+				// Resolve the per-turn tool-choice directive ONCE per logical turn. The
+				// host hard-choice path (getToolChoice → nextToolChoice) is CONSUMING — it
+				// advances a generator on every call — so Harmony-leak retries, which
+				// re-sample the same turn via `continue` without a turn_end, must reuse the
+				// values fetched on the first attempt rather than double-advancing it.
+				// Fetched here (after pending-message flush + context sync, immediately
+				// before the call) so a throw in between cannot wedge an in-flight
+				// directive. A hard ToolChoice is applied verbatim; a SoftToolRequirement
+				// triggers the remind-then-escalate lifecycle: inject its reminder inline
+				// once per new id (toolChoice stays auto), and the gate below escalates to
+				// a forced choice only if the model declines. The host wrapper already
+				// dropped a soft requirement whose tool is inactive.
+				if (!directiveResolvedForTurn) {
+					const directive = signal?.aborted ? undefined : config.getToolChoice?.();
+					const softReq = isSoftToolRequirement(directive) ? directive : undefined;
+					hostToolChoice = directive === undefined || isSoftToolRequirement(directive) ? undefined : directive;
+					softRequiredTool = softReq?.toolName;
+					if (softReq !== undefined) {
+						if (softReq.id !== softRequirementId) {
+							softRequirementId = softReq.id;
+							softEscalations = 0;
+							for (const reminder of softReq.reminder) {
+								stream.push({ type: "message_start", message: reminder });
+								stream.push({ type: "message_end", message: reminder });
+								currentContext.messages.push(reminder);
+								newMessages.push(reminder);
+							}
+						}
+					} else {
+						softRequirementId = undefined;
+						softEscalations = 0;
+					}
+					directiveResolvedForTurn = true;
+				}
+
 				// Stream assistant response
 				let recovered: HarmonyRecoveredToolCall | undefined;
 				let message: AssistantMessage;
@@ -762,6 +850,8 @@ async function runLoopBody(
 						stepCounter,
 						streamFn,
 						harmonyRetryAttempt,
+						hostToolChoice,
+						forcedToolChoice,
 					);
 					harmonyRetryAttempt = 0;
 					harmonyTruncateResumeCount = 0;
@@ -778,6 +868,10 @@ async function runLoopBody(
 						recovered = err.recovered;
 						message = recovered.message;
 						await emitHarmonyAudit(config, err, "truncate_resume", harmonyRetryAttempt);
+						// A recovered message completes the turn, so the abort-retry counter
+						// resets like the normal success path (the truncate-resume counter
+						// keeps accumulating for its cross-turn cap).
+						harmonyRetryAttempt = 0;
 					} else {
 						if (harmonyRetryAttempt >= 2) {
 							await emitHarmonyAudit(config, err, "escalated", harmonyRetryAttempt);
@@ -798,6 +892,14 @@ async function runLoopBody(
 				}
 				newMessages.push(message);
 
+				// The escalation choice (if any) applied to the call above; clear it so
+				// only the single escalation turn carries the forced choice.
+				forcedToolChoice = undefined;
+
+				// A fresh logical turn re-resolves the directive next iteration; a Harmony
+				// retry `continue`s before this line and keeps the cached value.
+				directiveResolvedForTurn = false;
+
 				if (message.stopReason === "error" || message.stopReason === "aborted") {
 					// Create placeholder tool results for any tool calls in the aborted message
 					// This maintains the tool_use/tool_result pairing that the API requires
@@ -850,8 +952,51 @@ async function runLoopBody(
 					hasMoreToolCalls = false;
 				}
 
+				// A turn is compliant ONLY when it calls the required tool and nothing
+				// else — mirroring the forced-tool_choice turn, which can emit only that
+				// tool. A required+detour batch is treated as non-compliant so detour
+				// tools never run side effects while the requirement is still pending.
+				const calledOnlyRequiredTool =
+					softRequiredTool !== undefined &&
+					toolCalls.length > 0 &&
+					toolCalls.every(toolCall => toolCall.name === softRequiredTool);
+				const softGateActive =
+					softRequiredTool !== undefined && !hardToolChoiceBlocks(config.toolChoice, softRequiredTool);
+				const softNonCompliant = softGateActive && !calledOnlyRequiredTool;
+
 				const toolResults: ToolResultMessage[] = [];
-				if (hasMoreToolCalls) {
+				if (softNonCompliant && softRequiredTool !== undefined) {
+					if (softEscalations >= MAX_SOFT_TOOL_ESCALATIONS) {
+						throw new Error(
+							`Soft tool requirement '${softRequiredTool}' was not satisfied after ${MAX_SOFT_TOOL_ESCALATIONS} forced turns; aborting to avoid an unbounded force loop.`,
+						);
+					}
+					// A soft-required tool is pending but the model called something else
+					// (or yielded). Do NOT execute the detour — pair each call with a
+					// skipped result and force the required tool next turn. This is the
+					// only turn that changes toolChoice; a model that complies with the
+					// reminder pays no message-cache invalidation. Re-engage so the loop
+					// never yields while the requirement is unmet.
+					for (const toolCall of toolCalls) {
+						const result = createAbortedToolResult(
+							toolCall,
+							stream,
+							"skipped",
+							`Not executed: call the \`${softRequiredTool}\` tool to resolve the pending action before using other tools.`,
+						);
+						currentContext.messages.push(result);
+						newMessages.push(result);
+						toolResults.push(result);
+						recordSkippedTool(telemetry, {
+							toolCallId: toolCall.id,
+							toolName: toolCall.name,
+							status: "skipped",
+						});
+					}
+					forcedToolChoice = { type: "tool", name: softRequiredTool };
+					softEscalations++;
+					hasMoreToolCalls = true;
+				} else if (hasMoreToolCalls) {
 					const executionResult = await executeToolCalls(
 						currentContext,
 						message,
@@ -999,6 +1144,8 @@ async function streamAssistantResponse(
 	stepCounter: StepCounter,
 	streamFn?: StreamFn,
 	harmonyRetryAttempt = 0,
+	hostToolChoice?: ToolChoice,
+	forcedToolChoice?: ToolChoice,
 ): Promise<AssistantMessage> {
 	// Apply context transform if configured (AgentMessage[] → AgentMessage[])
 	let messages = context.messages;
@@ -1012,6 +1159,9 @@ async function streamAssistantResponse(
 
 	const ownedDialect: Dialect | undefined = config.dialect ?? resolveOwnedDialectFromEnv(Bun.env.PI_DIALECT);
 	const exampleDialect = ownedDialect ?? preferredDialect(config.model.id);
+	// Owned/in-band dialects carry the catalog in the prompt as text and send no
+	// native `tools`, so description pruning only applies to native tool calling.
+	const pruneToolDescriptions = !!config.pruneToolDescriptions && !ownedDialect;
 	// Build LLM context — append-only mode caches system prompt + tools
 	// AND keeps an append-only message log so prior-turn bytes are stable.
 	let llmContext: Context;
@@ -1020,12 +1170,13 @@ async function streamAssistantResponse(
 		llmContext = config.appendOnlyContext.build(context, {
 			intentTracing: !!config.intentTracing,
 			exampleDialect,
+			pruneToolDescriptions,
 		});
 	} else {
 		llmContext = {
 			systemPrompt: context.systemPrompt,
 			messages: normalizedMessages,
-			tools: normalizeTools(context.tools, !!config.intentTracing, exampleDialect),
+			tools: normalizeTools(context.tools, !!config.intentTracing, exampleDialect, pruneToolDescriptions),
 		};
 	}
 	if (config.transformProviderContext) {
@@ -1048,7 +1199,6 @@ async function streamAssistantResponse(
 
 	const streamFunction = streamFn || streamSimple;
 
-	const dynamicToolChoice = config.getToolChoice?.();
 	const dynamicReasoning = config.getReasoning?.();
 	const dynamicDisableReasoning = config.getDisableReasoning?.();
 	const harmonyMitigationEnabled = isHarmonyLeakMitigationTarget(config.model);
@@ -1083,7 +1233,7 @@ async function streamAssistantResponse(
 	const effectiveTemperature =
 		harmonyRetryAttempt > 0 && config.temperature !== undefined ? config.temperature + 0.05 : config.temperature;
 	// Owned tool calling sends no native tools, so any tool_choice would error.
-	const effectiveToolChoice = ownedDialect ? undefined : (dynamicToolChoice ?? config.toolChoice);
+	const effectiveToolChoice = ownedDialect ? undefined : (hostToolChoice ?? forcedToolChoice ?? config.toolChoice);
 	const effectiveReasoning = dynamicReasoning ?? config.reasoning;
 	const effectiveDisableReasoning = dynamicDisableReasoning ?? config.disableReasoning;
 

package/src/agent.ts

@@ -39,7 +39,9 @@ import type {
 	AsideMessage,
 	StreamFn,
 	ToolCallContext,
+	ToolChoiceDirective,
 } from "./types";
+import { isSoftToolRequirement } from "./types";
 import { EventLoopKeepalive } from "./utils/yield";
 
 /**
@@ -223,6 +225,12 @@ export interface AgentOptions {
 
 	/** Enable intent tracing schema injection/stripping in the harness. */
 	intentTracing?: boolean;
+	/**
+	 * Strip tool descriptions from provider-bound tool specs (top-level + nested
+	 * schema annotations). Use when the full catalog is rendered into the system
+	 * prompt so descriptions are not duplicated on the wire. Native tool calling only.
+	 */
+	pruneToolDescriptions?: boolean;
 	/** Owned tool-calling dialect. Undefined keeps provider-native tool calling. */
 	dialect?: Dialect;
 	/**
@@ -232,8 +240,8 @@ export interface AgentOptions {
 	 * the loop's {@link AgentLoopConfig.abortOnFabricatedToolResult}.
 	 */
 	abortOnFabricatedToolResult?: boolean;
-	/** Dynamic tool choice override, resolved per LLM call. */
-	getToolChoice?: () => ToolChoice | undefined;
+	/** Dynamic tool-choice directive (hard {@link ToolChoice} or {@link SoftToolRequirement}), resolved once per turn. */
+	getToolChoice?: () => ToolChoiceDirective | undefined;
 
 	/**
 	 * Cursor exec handlers for local tool execution.
@@ -336,9 +344,10 @@ export class Agent {
 	#preferWebsockets?: boolean;
 	#transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
 	#intentTracing: boolean;
+	#pruneToolDescriptions: boolean;
 	#dialect?: Dialect;
 	#abortOnFabricatedToolResult?: boolean;
-	#getToolChoice?: () => ToolChoice | undefined;
+	#getToolChoice?: () => ToolChoiceDirective | undefined;
 	#onPayload?: SimpleStreamOptions["onPayload"];
 	#onResponse?: SimpleStreamOptions["onResponse"];
 	#onSseEvent?: SimpleStreamOptions["onSseEvent"];
@@ -407,6 +416,7 @@ export class Agent {
 		this.#preferWebsockets = opts.preferWebsockets;
 		this.#transformToolCallArguments = opts.transformToolCallArguments;
 		this.#intentTracing = opts.intentTracing === true;
+		this.#pruneToolDescriptions = opts.pruneToolDescriptions === true;
 		this.#dialect = opts.dialect;
 		this.#abortOnFabricatedToolResult = opts.abortOnFabricatedToolResult;
 		this.#getToolChoice = opts.getToolChoice;
@@ -1009,10 +1019,13 @@ export class Agent {
 					}
 				: undefined;
 
-		const getToolChoice = () => {
-			const queuedToolChoice = this.#getToolChoice?.();
-			if (queuedToolChoice !== undefined) {
-				return refreshToolChoiceForActiveTools(queuedToolChoice, this.#state.tools);
+		const getToolChoice = (): ToolChoiceDirective | undefined => {
+			const queued = this.#getToolChoice?.();
+			if (queued !== undefined) {
+				if (isSoftToolRequirement(queued)) {
+					return (this.#state.tools ?? []).some(tool => tool.name === queued.toolName) ? queued : undefined;
+				}
+				return refreshToolChoiceForActiveTools(queued, this.#state.tools);
 			}
 			return refreshToolChoiceForActiveTools(options?.toolChoice, this.#state.tools);
 		};
@@ -1059,6 +1072,7 @@ export class Agent {
 			cursorOnToolResult,
 			transformToolCallArguments: this.#transformToolCallArguments,
 			intentTracing: this.#intentTracing,
+			pruneToolDescriptions: this.#pruneToolDescriptions,
 			dialect: this.#dialect,
 			abortOnFabricatedToolResult: this.#abortOnFabricatedToolResult,
 			appendOnlyContext: this.#appendOnlyContext,

package/src/append-only-context.ts

@@ -35,6 +35,8 @@ export interface BuildOptions {
 	/** Inject the `_i` intent field into tool schemas (must match agent-loop's normalizeTools). */
 	intentTracing: boolean;
 	exampleDialect?: Dialect;
+	/** Strip tool descriptions from the provider-bound specs (must match normalizeTools). */
+	pruneToolDescriptions?: boolean;
 }
 
 /**
@@ -270,7 +272,8 @@ export class AppendOnlyContextManager {
 
 function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
 	const systemPrompt = [...context.systemPrompt];
-	const tools = normalizeTools(context.tools, options.intentTracing, options.exampleDialect) ?? [];
+	const tools =
+		normalizeTools(context.tools, options.intentTracing, options.exampleDialect, options.pruneToolDescriptions) ?? [];
 	return {
 		systemPrompt,
 		tools,
@@ -291,6 +294,7 @@ function computeFingerprint(systemPrompt: string[], tools: Tool[], options: Buil
 		})),
 		i: options.intentTracing,
 		ex: options.exampleDialect,
+		pd: options.pruneToolDescriptions,
 	});
 	let hash = 0;
 	for (let i = 0; i < payload.length; i++) {

package/src/compaction/compaction.ts

@@ -326,9 +326,16 @@ export function estimateTokens(message: AgentMessage): number {
 		case "branchSummary":
 		case "compactionSummary": {
 			fragments.push(message.summary);
-			if (message.role === "compactionSummary" && message.images) {
-				// Snapcompact frames render at ≥1568px; providers bill the downscaled cap.
-				extra += message.images.length * snapcompact.FRAME_TOKEN_ESTIMATE;
+			if (message.role === "compactionSummary") {
+				if (message.blocks) {
+					for (const block of message.blocks) {
+						if (block.type === "text") fragments.push(block.text);
+						else extra += snapcompact.FRAME_TOKEN_ESTIMATE;
+					}
+				} else if (message.images) {
+					// Snapcompact frames render at ≥1568px; providers bill the downscaled cap.
+					extra += message.images.length * snapcompact.FRAME_TOKEN_ESTIMATE;
+				}
 			}
 			break;
 		}

package/src/compaction/messages.ts

@@ -51,7 +51,11 @@ export interface CompactionSummaryMessage {
 	shortSummary?: string;
 	tokensBefore: number;
 	providerPayload?: ProviderPayload;
-	/** Snapcompact frames archived by this compaction; appended as image blocks after the summary text. */
+	/** Runtime-only ordered archive blocks for snapcompact: old text region,
+	 *  imaged middle, then new text region. When present, `summary` is already
+	 *  the final lead-in text (no legacy wrapper applied). */
+	blocks?: (TextContent | ImageContent)[];
+	/** Snapcompact image blocks, kept for display counts / legacy consumers. */
 	images?: ImageContent[];
 	timestamp: number;
 }
@@ -101,14 +105,19 @@ export function createCompactionSummaryMessage(
 	shortSummary?: string,
 	providerPayload?: ProviderPayload,
 	images?: ImageContent[],
+	blocks?: (TextContent | ImageContent)[],
 ): CompactionSummaryMessage {
+	const imageBlocks =
+		blocks?.filter((block): block is ImageContent => block.type === "image") ??
+		(images && images.length > 0 ? images : undefined);
 	return {
 		role: "compactionSummary",
 		summary,
 		shortSummary,
 		tokensBefore,
 		providerPayload,
-		images: images && images.length > 0 ? images : undefined,
+		blocks: blocks && blocks.length > 0 ? blocks : undefined,
+		images: imageBlocks && imageBlocks.length > 0 ? imageBlocks : undefined,
 		timestamp: new Date(timestamp).getTime(),
 	};
 }
@@ -182,13 +191,16 @@ export function convertMessageToLlm(message: AgentMessage): Message | undefined
 			case "compactionSummary":
 				return {
 					role: "user",
-					content: [
-						{
-							type: "text" as const,
-							text: renderCompactionSummaryContext(message.summary),
-						},
-						...(message.images ?? []),
-					],
+					content:
+						message.blocks !== undefined
+							? [{ type: "text" as const, text: message.summary }, ...message.blocks]
+							: [
+									{
+										type: "text" as const,
+										text: renderCompactionSummaryContext(message.summary),
+									},
+									...(message.images ?? []),
+								],
 					attribution: "agent",
 					providerPayload: message.providerPayload,
 					timestamp: message.timestamp,

package/src/compaction/pruning.ts

@@ -30,6 +30,24 @@ export interface PruneConfig {
 	supersedeKey?: SupersedeKeyFn;
 	/** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
 	pruneUseless?: boolean;
+	/**
+	 * Compaction boundary: the `firstKeptEntryId` of the latest compaction on
+	 * the branch. Entries at indices BEFORE this id are summarized away and never
+	 * sent to the model, so mutating them only churns persisted history without
+	 * shrinking the prompt — they are skipped. Undefined = no compaction (the
+	 * whole branch is sent).
+	 */
+	keepBoundaryId?: string;
+	/**
+	 * Prompt-cache guard. When set, a tool result whose all-message suffix
+	 * (tokens of every message after it) EXCEEDS this is part of the warm,
+	 * already-sent cache prefix: mutating it forces the provider to re-write the
+	 * whole suffix (cacheWrite premium). Such results — including superseded and
+	 * useless ones, which otherwise bypass {@link protectTokens} — are left for
+	 * compaction/shake (which rebuild the cache anyway) to reclaim. Undefined =
+	 * no cache guard (legacy: superseded/useless prune at any depth).
+	 */
+	cacheWarmSuffixTokens?: number;
 }
 
 export const DEFAULT_PRUNE_CONFIG: PruneConfig = {
@@ -66,10 +84,22 @@ export interface SupersedePruneConfig {
 	pruneUseless?: boolean;
 	/** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
 	suffixTokenLimit?: number;
-	/** Prune all candidates when the last message is at least this old (prompt cache is cold anyway). Default 30 min. */
+	/**
+	 * Prune all candidates when the last message is at least this old: the
+	 * provider prompt cache is then cold, so re-writing it is free. MUST exceed
+	 * the cache retention (Anthropic "long" = 1h) or a still-warm prefix is busted
+	 * by the flush. Default 30 min — callers on long retention override it.
+	 */
 	idleFlushMs?: number;
 	/** Clock override for tests. */
 	now?: number;
+	/**
+	 * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+	 * before it are summarized away and never sent, so they are skipped in every
+	 * path — including the idle flush — to avoid pointless history churn.
+	 * Undefined = no compaction (the whole branch is sent).
+	 */
+	keepBoundaryId?: string;
 	/** Tool-result protection matchers (same contract as {@link PruneConfig.protectedTools}). */
 	protectedTools: ProtectedToolMatcher[];
 }
@@ -103,6 +133,35 @@ function estimatePrunedSavings(tokens: number, notice: string): number {
 	return Math.max(0, tokens - noticeTokens);
 }
 
+/**
+ * For each entry index, the estimated token total of all *message* entries
+ * strictly after it — how much prompt-cache content the provider must re-write
+ * (cacheWrite premium) if that entry is mutated in place. Used to keep prune
+ * mutations inside the cheap-to-recache tail.
+ */
+function computeMessageSuffixTokens(entries: readonly SessionEntry[]): number[] {
+	const suffix = new Array<number>(entries.length);
+	let accumulated = 0;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		suffix[i] = accumulated;
+		const entry = entries[i];
+		if (entry.type === "message") accumulated += estimateTokens(entry.message as AgentMessage);
+	}
+	return suffix;
+}
+
+/**
+ * Resolve the array index of the compaction boundary (`keepBoundaryId`). Entries
+ * before this index are summarized away by the latest compaction and never sent,
+ * so prune passes must not mutate them. Returns 0 when there is no boundary (no
+ * compaction → whole branch is sent) or the id is absent from `entries`.
+ */
+function resolveBoundaryIndex(entries: readonly SessionEntry[], keepBoundaryId: string | undefined): number {
+	if (keepBoundaryId === undefined) return 0;
+	const index = entries.findIndex(entry => entry.id === keepBoundaryId);
+	return index < 0 ? 0 : index;
+}
+
 interface SupersedeCandidate {
 	entry: SessionMessageEntry;
 	message: ToolResultMessage;
@@ -183,7 +242,8 @@ function collectUselessResults(
  * flagged contextually useless. Cheap, incremental, and prompt-cache-aware: a
  * candidate is pruned now only when the suffix after it is small (tail case —
  * the read→edit→read loop) or when the context has been idle long enough that
- * the provider cache is cold anyway (then ALL candidates flush).
+ * the provider cache is cold anyway (then all still-sent candidates flush).
+ * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
  */
 export function pruneSupersededToolResults(entries: SessionEntry[], config: SupersedePruneConfig): PruneResult {
 	const toolCallsById = collectToolCallsById(entries);
@@ -209,20 +269,24 @@ export function pruneSupersededToolResults(entries: SessionEntry[], config: Supe
 	const idle =
 		lastMessageTimestamp !== undefined && now - lastMessageTimestamp >= (config.idleFlushMs ?? DEFAULT_IDLE_FLUSH_MS);
 
+	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
+
 	let toPrune: SupersedeCandidate[];
 	if (idle) {
-		toPrune = candidates;
+		// Provider cache is cold (idle exceeds the retention TTL), so re-writing
+		// the sent region costs nothing. Entries before the compaction boundary
+		// are summarized away and never sent — skip them to avoid pointless churn.
+		toPrune = candidates.filter(candidate => candidate.index >= boundaryIndex);
 	} else {
 		const suffixTokenLimit = config.suffixTokenLimit ?? DEFAULT_SUFFIX_TOKEN_LIMIT;
 		// suffixTokens[i] = estimated tokens of all messages strictly after entry i.
-		const suffixTokens = new Array<number>(entries.length);
-		let accumulated = 0;
-		for (let i = entries.length - 1; i >= 0; i--) {
-			suffixTokens[i] = accumulated;
-			const entry = entries[i];
-			if (entry.type === "message") accumulated += estimateTokens(entry.message as AgentMessage);
-		}
-		toPrune = candidates.filter(candidate => suffixTokens[candidate.index] <= suffixTokenLimit);
+		// Mutating a candidate re-writes its suffix in the warm cache, so prune only
+		// when that suffix is small (cheap-to-recache tail) and the candidate sits
+		// at/after the compaction boundary.
+		const suffixTokens = computeMessageSuffixTokens(entries);
+		toPrune = candidates.filter(
+			candidate => candidate.index >= boundaryIndex && suffixTokens[candidate.index] <= suffixTokenLimit,
+		);
 	}
 	if (toPrune.length === 0) return { prunedCount: 0, tokensSaved: 0 };
 
@@ -262,6 +326,11 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 				)
 			: undefined;
 
+	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
+	const cacheWarmSuffixTokens = config.cacheWarmSuffixTokens;
+	// All-message suffix per index, only when the cache guard is armed.
+	const messageSuffix = cacheWarmSuffixTokens === undefined ? undefined : computeMessageSuffixTokens(entries);
+
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
 		const message = getToolResultMessage(entry);
@@ -275,10 +344,23 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 			continue;
 		}
 
-		// Superseded and useless results are pruned first: they bypass the
-		// protect window (a stale copy of re-read content — or a result the
-		// tool itself flagged as carrying no information — is dead weight at
-		// any age).
+		// Prompt-cache guard: a result whose all-message suffix exceeds the
+		// warm-cache window sits in the already-sent cached prefix — mutating it
+		// re-writes the whole suffix (cacheWrite premium). Entries before the
+		// compaction boundary are summarized away (never sent). Both are skipped
+		// before any prune decision, so superseded/useless cannot reach a deep,
+		// still-cached copy; compaction/shake reclaim those when they rebuild.
+		const inWarmPrefix =
+			messageSuffix !== undefined && cacheWarmSuffixTokens !== undefined && messageSuffix[i] > cacheWarmSuffixTokens;
+		if (inWarmPrefix || i < boundaryIndex) {
+			accumulatedTokens += tokens;
+			continue;
+		}
+
+		// Superseded and useless results bypass the age-based protect window
+		// (a stale re-read copy, or a result the tool flagged as uninformative,
+		// is dead weight at any age) — but only within the cache-warm tail: the
+		// guard above already excluded deeper, still-cached copies.
 		const superseded = supersededMessages?.has(message) ?? false;
 		const useless = uselessMessages?.has(message) ?? false;
 		const tooSmall = tokens < MIN_PRUNE_TOKENS;

package/src/compaction/shake.ts

@@ -31,6 +31,14 @@ export interface ShakeConfig {
 	protectedTools: ProtectedToolMatcher[];
 	/** Minimum token size for a fenced/XML block to be eligible. */
 	fenceMinTokens: number;
+	/**
+	 * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+	 * before it are summarized away and never sent, so they are skipped — shaking
+	 * them only churns persisted history. Undefined = no compaction (whole branch
+	 * is sent). Note: shake still elides the warm cached prefix at/after the
+	 * boundary — that is its job as a compaction-class reducer.
+	 */
+	keepBoundaryId?: string;
 }
 
 /** Auto-shake config: protects the live tail, conservative thresholds. */
@@ -289,9 +297,20 @@ export function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig
 
 	const toolCallsById = collectToolCallsById(entries);
 
+	// Entries before the compaction boundary are summarized away and never sent —
+	// shaking them only churns persisted history (no prompt/cache effect).
+	const boundaryIndex =
+		config.keepBoundaryId === undefined
+			? 0
+			: Math.max(
+					0,
+					entries.findIndex(entry => entry.id === config.keepBoundaryId),
+				);
+
 	const regions: ShakeRegion[] = [];
 	for (let i = 0; i < n; i++) {
 		const entry = entries[i];
+		if (i < boundaryIndex) continue;
 		const toolResult = getToolResultMessage(entry);
 		// Useless-flagged results carry no information once consumed; they are
 		// eligible even inside the protect-recent window.

package/src/types.ts

@@ -36,6 +36,43 @@ export type StreamFn = (
  */
 export type AsideMessage = AgentMessage | (() => AgentMessage | null);
 
+/**
+ * A soft tool requirement: the host wants `toolName` called before the loop
+ * runs other tools or yields, but WITHOUT paying the forced-`toolChoice` cost
+ * up front (changing `tool_choice` invalidates the provider message cache).
+ * Returned from {@link AgentLoopConfig.getToolChoice} in place of a hard
+ * {@link ToolChoice}: the loop injects `reminder` once when a new `id` becomes
+ * active, runs with `toolChoice` unchanged, and escalates to a one-turn forced
+ * choice only if the model fails to call `toolName`. Auto-clears when the host
+ * stops returning it or `toolName` is no longer an active tool.
+ */
+export interface SoftToolRequirement {
+	/** Discriminates a soft requirement from a hard {@link ToolChoice}. */
+	soft: true;
+	/**
+	 * Stable id of the *current* requirement. The loop injects `reminder` when
+	 * this id first becomes active and again whenever it changes (e.g. one
+	 * stacked preview resolves and the next becomes the head), but never
+	 * re-injects for an unchanged id across turns.
+	 */
+	id: string;
+	/** Tool that must be called before the loop runs other tools or yields. */
+	toolName: string;
+	/** Host-owned reminder messages, injected once per `id` activation. */
+	reminder: AgentMessage[];
+}
+
+/**
+ * A per-turn tool-choice directive: either a hard provider {@link ToolChoice}
+ * (applied verbatim) or a {@link SoftToolRequirement} (remind-then-escalate).
+ */
+export type ToolChoiceDirective = ToolChoice | SoftToolRequirement;
+
+/** True when a {@link ToolChoiceDirective} is a soft requirement, not a hard choice. */
+export function isSoftToolRequirement(directive: ToolChoiceDirective | undefined): directive is SoftToolRequirement {
+	return typeof directive === "object" && directive !== null && (directive as SoftToolRequirement).soft === true;
+}
+
 /**
  * Configuration for the agent loop.
  */
@@ -203,6 +240,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * then strips from arguments before executing tools.
 	 */
 	intentTracing?: boolean;
+	/**
+	 * Strip tool descriptions (top-level + nested schema annotations) from the
+	 * provider-bound tool specs. Use when the full catalog is rendered into the
+	 * system prompt instead, so descriptions are not duplicated on the wire.
+	 */
+	pruneToolDescriptions?: boolean;
 	/**
 	 * Owned tool calling dialect.
 	 *
@@ -246,10 +289,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 
 	/**
-	 * Dynamic tool choice override, resolved per LLM call.
-	 * When set and returns a value, overrides the static `toolChoice`.
+	 * Dynamic tool-choice directive, resolved once per turn. Returns a hard
+	 * {@link ToolChoice} (applied verbatim, overriding the static `toolChoice`),
+	 * a {@link SoftToolRequirement} (the loop reminds-then-escalates instead of
+	 * forcing `tool_choice` immediately, so a model that complies with the
+	 * reminder pays no message-cache invalidation), or `undefined` to fall back
+	 * to the static `toolChoice`.
 	 */
-	getToolChoice?: () => ToolChoice | undefined;
+	getToolChoice?: () => ToolChoiceDirective | undefined;
 
 	/**
 	 * Dynamic reasoning effort override, resolved per LLM call.