@oh-my-pi/pi-agent-core 17.1.4 → 17.1.6

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [17.1.6] - 2026-07-27
+
+### Added
+
+- Added a pre-model-call gate: `AgentLoopConfig.beforeModelCall` receives the finalized provider context and run abort signal, and may return `{ stop: true, reason? }` to end the run before the provider is called, so a host can refuse a request it has decided not to pay for (prompt no longer fits, budget boundary crossed, session should hand off). `Agent.setBeforeModelCall` installs the host callback; `Agent.addBeforeModelCall` registers an additional one without displacing it and returns a disposer. A gate-stopped run retains pending soft tool reminders/escalations and an unserved hard tool choice for the next admitted request; deferred choices are revalidated against active tools and cleared with queued session state ([#6543](https://github.com/can1357/oh-my-pi/pull/6543) by [@paralin](https://github.com/paralin)).
+
+### Changed
+
+- Input message events (prompt, steering, soft reminders) are now emitted once provider-context preparation succeeds, so a pre-model gate can veto the request before any turn opens; gate-stopped and failed runs still commit their accepted inputs ([#6543](https://github.com/can1357/oh-my-pi/pull/6543) by [@paralin](https://github.com/paralin)).
+
+## [17.1.5] - 2026-07-27
+
+### Fixed
+
+- Fixed proxy-stream clients dropping finalized provider-only content blocks, including Anthropic native web-search history, by allowing `done` and `error` events to carry terminal assistant content while retaining delta-reconstructed content from older proxy servers that omit it ([#6703](https://github.com/can1357/oh-my-pi/issues/6703)).
+
 ## [17.1.4] - 2026-07-26
 
 ### Changed

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.js";
-import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
+import type { AgentBeforeModelCall, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
 }
@@ -159,6 +159,8 @@ export interface AgentOptions {
     abortOnFabricatedToolResult?: boolean;
     /** Dynamic tool-choice directive (hard {@link ToolChoice} or {@link SoftToolRequirement}), resolved once per turn. */
     getToolChoice?: () => ToolChoiceDirective | undefined;
+    /** Reject a deferred hard choice when its named tool is no longer active. */
+    onToolChoiceUnavailable?: () => void;
     /**
      * Cursor exec handlers for local tool execution.
      */
@@ -374,6 +376,19 @@ export declare class Agent {
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
     setOnTurnEnd(fn: ((messages: AgentMessage[], signal?: AbortSignal, context?: AgentTurnEndContext) => Promise<void> | void) | undefined): void;
+    /**
+     * Install or replace the host pre-model-call gate; pass `undefined` to
+     * remove it. Gates are sampled when a run starts: installing the first
+     * gate while a run is in flight takes effect on the next run.
+     */
+    setBeforeModelCall(fn: AgentBeforeModelCall | undefined): void;
+    /**
+     * Add a pre-model callback without replacing callbacks owned by the host.
+     * Returns a disposer that removes only this callback. Like
+     * {@link setBeforeModelCall}, the first gate installed while a run is in
+     * flight takes effect on the next run.
+     */
+    addBeforeModelCall(fn: AgentBeforeModelCall): () => void;
     /**
      * Provide a source of non-interrupting "aside" messages (e.g. background-job
      * completions, late LSP diagnostics) drained at each step boundary. Never
@@ -408,6 +423,11 @@ export declare class Agent {
     followUp(m: AgentMessage): void;
     clearSteeringQueue(): void;
     clearFollowUpQueue(): void;
+    /**
+     * Drop tool-directive state retained across a gate-stopped run: the
+     * deferred hard choice and the soft-requirement lifecycle.
+     */
+    clearDeferredToolDirectives(): void;
     clearAllQueues(): void;
     hasQueuedMessages(): boolean;
     /** Non-consuming view of the pending steering queue (insertion order, newest

package/dist/types/proxy.d.ts

@@ -53,11 +53,13 @@ export type ProxyAssistantMessageEvent = {
     type: "done";
     reason: Extract<StopReason, "stop" | "length" | "toolUse">;
     usage: AssistantMessage["usage"];
+    content?: AssistantMessage["content"];
 } | {
     type: "error";
     reason: Extract<StopReason, "aborted" | "error">;
     errorMessage?: string;
     usage: AssistantMessage["usage"];
+    content?: AssistantMessage["content"];
 };
 export interface ProxyStreamOptions extends SimpleStreamOptions {
     /** Auth token for the proxy server */

package/dist/types/types.d.ts

@@ -21,6 +21,18 @@ export interface AgentTurnEndContext {
     /** True when the current tool-loop batch is continuing without yielding to post-turn steering. */
     willContinue: boolean;
 }
+export interface AgentPreModelCallStop {
+    /** Stop the agent loop before sending the next provider request. */
+    stop: true;
+    /** Optional owner-facing reason, logged by the loop when it stops. */
+    reason?: string;
+}
+export type AgentPreModelCallResult = AgentPreModelCallStop | undefined;
+/**
+ * A pre-model-call gate. Return {@link AgentPreModelCallStop} to refuse the
+ * request, or nothing to proceed; the signal aborts with the run.
+ */
+export type AgentBeforeModelCall = (context: Context, signal?: AbortSignal) => AgentPreModelCallResult | void | Promise<AgentPreModelCallResult | void>;
 /**
  * A soft tool requirement: the host wants `toolName` called before the loop
  * runs other tools or yields, but WITHOUT paying the forced-`toolChoice` cost
@@ -61,6 +73,12 @@ export interface SoftToolRequirement {
  * (applied verbatim) or a {@link SoftToolRequirement} (remind-then-escalate).
  */
 export type ToolChoiceDirective = ToolChoice | SoftToolRequirement;
+/** Mutable soft-requirement lifecycle retained across stopped agent runs. */
+export interface SoftToolRequirementState {
+    id?: string;
+    forcedToolChoice?: ToolChoice;
+    escalations: number;
+}
 /** True when a {@link ToolChoiceDirective} is a soft requirement, not a hard choice. */
 export declare function isSoftToolRequirement(directive: ToolChoiceDirective | undefined): directive is SoftToolRequirement;
 /** Source category for a queued steering interrupt observed without consuming the queue. */
@@ -230,8 +248,21 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /**
      * Refreshes prompt/tool context from live session state before each model call.
      * Use this when tool availability or the system prompt can change mid-turn.
+     *
+     * Runs after pending messages are folded in and before provider conversion.
+     * Mutate the agent context here; use `beforeModelCall` to inspect the
+     * provider-bound context.
      */
     syncContextBeforeModelCall?: (context: AgentContext) => void | Promise<void>;
+    /**
+     * Asked after the complete provider context has been built, including
+     * message conversion, provider transforms, normalized tools, and owned
+     * dialect prompt injection. Returning {@link AgentPreModelCallStop} ends
+     * the stream without emitting `turn_start`, so no turn is left open and no
+     * request is billed. Return nothing to proceed. The signal aborts when
+     * the run is canceled or its deadline expires.
+     */
+    beforeModelCall?: AgentBeforeModelCall;
     /**
      * Optional transform applied to tool call arguments before execution.
      * Use for deobfuscating secrets or rewriting arguments.
@@ -304,6 +335,17 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * to the static `toolChoice`.
      */
     getToolChoice?: () => ToolChoiceDirective | undefined;
+    /**
+     * Soft-requirement lifecycle retained by the host when a pre-model-call
+     * gate stops a run before its pending reminder or escalation is served.
+     */
+    softToolRequirementState?: SoftToolRequirementState;
+    /**
+     * Notifies the host that the pre-model-call gate stopped the run after a
+     * hard tool choice was obtained from {@link getToolChoice} but before it
+     * was served, so the host can retain it for the next admitted request.
+     */
+    onToolChoiceRejected?: () => void;
     /**
      * 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": "17.1.4",
+	"version": "17.1.6",
 	"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": "17.1.4",
-		"@oh-my-pi/pi-catalog": "17.1.4",
-		"@oh-my-pi/pi-natives": "17.1.4",
-		"@oh-my-pi/pi-utils": "17.1.4",
-		"@oh-my-pi/pi-wire": "17.1.4",
-		"@oh-my-pi/snapcompact": "17.1.4",
+		"@oh-my-pi/pi-ai": "17.1.6",
+		"@oh-my-pi/pi-catalog": "17.1.6",
+		"@oh-my-pi/pi-natives": "17.1.6",
+		"@oh-my-pi/pi-utils": "17.1.6",
+		"@oh-my-pi/pi-wire": "17.1.6",
+		"@oh-my-pi/snapcompact": "17.1.6",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -10,6 +10,7 @@ import {
 	type Context,
 	EventStream,
 	isApiKeyResolver,
+	type Model,
 	resolveApiKeyOnce,
 	seedApiKeyResolver,
 	streamSimple,
@@ -42,7 +43,7 @@ import {
 	signalListLabel,
 } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
-import { sanitizeText, structuredCloneJSON } from "@oh-my-pi/pi-utils";
+import { logger, sanitizeText, structuredCloneJSON } from "@oh-my-pi/pi-utils";
 import { INTENT_FIELD } from "@oh-my-pi/pi-wire";
 import { agentPauseGate } from "./pause";
 import { type AgentRunCoverage, type AgentRunSummary, ToolCallBlockedError } from "./run-collector";
@@ -67,6 +68,7 @@ import type {
 	AgentEvent,
 	AgentLoopConfig,
 	AgentMessage,
+	AgentPreModelCallResult,
 	AgentTool,
 	AgentToolResult,
 	AgentTurnEndContext,
@@ -526,14 +528,9 @@ export function agentLoop(
 		};
 
 		stream.push({ type: "agent_start" });
-		stream.push({ type: "turn_start" });
-		for (const prompt of prompts) {
-			stream.push({ type: "message_start", message: prompt });
-			stream.push({ type: "message_end", message: prompt });
-		}
 
 		try {
-			await runLoop(currentContext, newMessages, config, signal, stream, streamFn);
+			await runLoop(currentContext, newMessages, config, signal, stream, streamFn, prompts);
 		} catch (err) {
 			stream.fail(err);
 		}
@@ -571,7 +568,6 @@ export function agentLoopContinue(
 		const currentContext: AgentContext = { ...context, messages: [...context.messages] };
 
 		stream.push({ type: "agent_start" });
-		stream.push({ type: "turn_start" });
 
 		try {
 			await runLoop(currentContext, newMessages, config, signal, stream, streamFn);
@@ -621,14 +617,36 @@ async function emitTurnEnd(
 	config: AgentLoopConfig,
 	signal?: AbortSignal,
 	context?: Omit<AgentTurnEndContext, "message" | "toolResults">,
+	runHookOnAbortedMessage = false,
 ): Promise<void> {
 	stream.push({ type: "turn_end", message, toolResults });
 	const isAbortedOrError =
 		message.role === "assistant" && (message.stopReason === "aborted" || message.stopReason === "error");
-	if (signal?.aborted || isAbortedOrError) return;
+	if (signal?.aborted || (isAbortedOrError && !runHookOnAbortedMessage)) return;
 	await config.onTurnEnd?.(currentContext.messages, signal, { message, toolResults, willContinue: false, ...context });
 }
 
+function createGateStopMessage(model: Model, reason: string | undefined): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [{ type: "text", text: "" }],
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "aborted",
+		errorMessage: reason ?? "Stopped before model call",
+		timestamp: Date.now(),
+	};
+}
+
 /**
  * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
  * run-level telemetry/coverage rollup to the existing `AgentMessage[]`
@@ -866,6 +884,7 @@ async function runLoop(
 	signal: AbortSignal | undefined,
 	stream: EventStream<AgentEvent, AgentMessage[]>,
 	streamFn?: StreamFn,
+	initialMessages: AgentMessage[] = [],
 ): Promise<void> {
 	const telemetry = resolveTelemetry(config.telemetry, config.sessionId);
 	const invokeAgentSpan = startInvokeAgentSpan(telemetry, config.model);
@@ -882,6 +901,7 @@ async function runLoop(
 				telemetry,
 				invokeAgentSpan,
 				stepCounter,
+				initialMessages,
 				streamFn,
 			),
 		);
@@ -913,6 +933,12 @@ function endAgentStream(
 	stream.push(buildAgentEndEvent(newMessages, telemetry, stepCount));
 	stream.end(newMessages);
 }
+function emitInputMessages(stream: EventStream<AgentEvent, AgentMessage[]>, messages: readonly AgentMessage[]): void {
+	for (const message of messages) {
+		stream.push({ type: "message_start", message });
+		stream.push({ type: "message_end", message });
+	}
+}
 
 /**
  * Resolve aside entries at the moment the loop is about to inject them. Each entry
@@ -940,6 +966,7 @@ async function runLoopBody(
 	telemetry: AgentTelemetry | undefined,
 	invokeAgentSpan: Span | undefined,
 	stepCounter: StepCounter,
+	initialMessages: AgentMessage[],
 	streamFn?: StreamFn,
 ): Promise<void> {
 	let deadlineTimer: Timer | undefined;
@@ -957,26 +984,33 @@ async function runLoopBody(
 		signal = signal ? AbortSignal.any([signal, deadlineAbortController.signal]) : deadlineAbortController.signal;
 	}
 
+	const softRequirementState = config.softToolRequirementState ?? { escalations: 0 };
+	let preserveSoftRequirementState = false;
+
 	try {
-		let firstTurn = true;
+		let messagesToEmit = [...initialMessages];
 		if (isDeadlineExceeded(config.deadline)) {
+			emitInputMessages(stream, messagesToEmit);
 			endAgentStream(stream, newMessages, telemetry, stepCounter.count);
 			return;
 		}
 		// Check for steering messages at start (user may have typed while waiting).
 		// Skip when the run is already externally aborted — dequeuing would strand
 		// the messages in a run that is about to die.
-		let pendingMessages: AgentMessage[] = signal?.aborted ? [] : (await config.getSteeringMessages?.()) || [];
+		let pendingMessages: AgentMessage[];
+		try {
+			pendingMessages = signal?.aborted ? [] : (await config.getSteeringMessages?.()) || [];
+		} catch (error) {
+			stream.push({ type: "turn_start" });
+			emitInputMessages(stream, messagesToEmit);
+			throw error;
+		}
 		let harmonyRetryAttempt = 0;
 		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;
+		// Soft tool requirement lifecycle (reminder then escalation; see SoftToolRequirement).
+		// The host-owned state survives only a gate stop between Agent.prompt calls.
 		// 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.
@@ -984,6 +1018,7 @@ async function runLoopBody(
 		let softRequiredTool: string | undefined;
 		let softSatisfies: SoftToolRequirement["satisfies"];
 		let directiveResolvedForTurn = false;
+		let turnOpen = false;
 
 		// Outer loop: continues when queued follow-up messages arrive after agent would stop
 		while (true) {
@@ -992,6 +1027,7 @@ async function runLoopBody(
 			// Inner loop: process tool calls and steering messages
 			while (hasMoreToolCalls || pendingMessages.length > 0) {
 				if (isDeadlineExceeded(config.deadline)) {
+					emitInputMessages(stream, messagesToEmit);
 					endAgentStream(stream, newMessages, telemetry, stepCounter.count);
 					return;
 				}
@@ -1002,62 +1038,109 @@ async function runLoopBody(
 				// engaged (host /pause). An external abort releases the park so a
 				// cancelled run still unwinds while everything else stays frozen.
 				if (agentPauseGate.paused) await agentPauseGate.waitUntilResumed(signal);
-				if (!firstTurn) {
-					stream.push({ type: "turn_start" });
-				} else {
-					firstTurn = false;
-				}
 
-				// Process pending messages (inject before next assistant response)
+				// Build the provider-bound context before opening the turn. Queue
+				// messages are added now but their events remain deferred until
+				// provider preparation either succeeds or opens an error turn.
+				const turnMessages = messagesToEmit;
+				messagesToEmit = [];
 				if (pendingMessages.length > 0) {
 					for (const message of pendingMessages) {
-						stream.push({ type: "message_start", message });
-						stream.push({ type: "message_end", message });
 						currentContext.messages.push(message);
 						newMessages.push(message);
+						turnMessages.push(message);
 					}
 					pendingMessages = [];
 				}
 
-				// Refresh prompt/tool context from live state before each model call
-				if (config.syncContextBeforeModelCall) {
-					await config.syncContextBeforeModelCall(currentContext);
-				}
+				let preparedProviderCall: PreparedProviderCall;
+				let gateResult: AgentPreModelCallResult;
+				try {
+					if (config.syncContextBeforeModelCall) {
+						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;
-					softSatisfies = softReq?.satisfies;
-					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);
+					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;
+						softSatisfies = softReq?.satisfies;
+						const softRequirementId = softRequirementState.id;
+						if (softReq !== undefined) {
+							if (softReq.id !== softRequirementId) {
+								softRequirementState.id = softReq.id;
+								softRequirementState.forcedToolChoice = undefined;
+								softRequirementState.escalations = 0;
+								for (const reminder of softReq.reminder) {
+									currentContext.messages.push(reminder);
+									newMessages.push(reminder);
+									turnMessages.push(reminder);
+								}
 							}
+						} else {
+							softRequirementState.id = undefined;
+							softRequirementState.forcedToolChoice = undefined;
+							softRequirementState.escalations = 0;
 						}
-					} else {
-						softRequirementId = undefined;
-						softEscalations = 0;
+						directiveResolvedForTurn = true;
+					}
+
+					preparedProviderCall = await prepareProviderCall(currentContext, config, signal);
+					gateResult = (await config.beforeModelCall?.(preparedProviderCall.context, signal)) || undefined;
+				} catch (error) {
+					if (!turnOpen) {
+						stream.push({ type: "turn_start" });
+						emitInputMessages(stream, turnMessages);
+						turnOpen = true;
+					}
+					throw error;
+				}
+				if (config.beforeModelCall && signal?.aborted) {
+					gateResult = { stop: true };
+				}
+				if (gateResult?.stop) {
+					if (gateResult.reason) {
+						logger.debug("Agent loop stopped before the model call", { reason: gateResult.reason });
 					}
-					directiveResolvedForTurn = true;
+					if (!turnOpen && !signal?.aborted) {
+						try {
+							config.onToolChoiceRejected?.();
+						} catch (error) {
+							stream.push({ type: "turn_start" });
+							emitInputMessages(stream, turnMessages);
+							turnOpen = true;
+							throw error;
+						}
+					}
+					emitInputMessages(stream, turnMessages);
+					if (turnOpen) {
+						const stopMessage = createGateStopMessage(preparedProviderCall.model, gateResult.reason);
+						currentContext.messages.push(stopMessage);
+						newMessages.push(stopMessage);
+						stream.push({ type: "message_start", message: stopMessage });
+						stream.push({ type: "message_end", message: stopMessage });
+						await emitTurnEnd(
+							stream,
+							currentContext,
+							stopMessage,
+							[],
+							config,
+							signal,
+							{ willContinue: false },
+							true,
+						);
+						turnOpen = false;
+					}
+					preserveSoftRequirementState = !signal?.aborted;
+					endAgentStream(stream, newMessages, telemetry, stepCounter.count);
+					return;
+				}
+
+				if (!turnOpen) {
+					stream.push({ type: "turn_start" });
+					emitInputMessages(stream, turnMessages);
+					turnOpen = true;
 				}
 
 				// Stream assistant response
@@ -1075,7 +1158,8 @@ async function runLoopBody(
 						streamFn,
 						harmonyRetryAttempt,
 						hostToolChoice,
-						forcedToolChoice,
+						softRequirementState.forcedToolChoice,
+						preparedProviderCall,
 					);
 					harmonyRetryAttempt = 0;
 					harmonyTruncateResumeCount = 0;
@@ -1118,7 +1202,7 @@ async function runLoopBody(
 
 				// The escalation choice (if any) applied to the call above; clear it so
 				// only the single escalation turn carries the forced choice.
-				forcedToolChoice = undefined;
+				softRequirementState.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.
@@ -1161,6 +1245,7 @@ async function runLoopBody(
 						});
 					}
 					await emitTurnEnd(stream, currentContext, message, toolResults, config, signal, { willContinue: false });
+					turnOpen = false;
 
 					stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count));
 					stream.end(newMessages);
@@ -1212,7 +1297,7 @@ async function runLoopBody(
 
 				const toolResults: ToolResultMessage[] = [];
 				if (softNonCompliant && softRequiredTool !== undefined) {
-					if (softEscalations >= MAX_SOFT_TOOL_ESCALATIONS) {
+					if (softRequirementState.escalations >= 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.`,
 						);
@@ -1239,8 +1324,8 @@ async function runLoopBody(
 							status: "skipped",
 						});
 					}
-					forcedToolChoice = { type: "tool", name: softRequiredTool };
-					softEscalations++;
+					softRequirementState.forcedToolChoice = { type: "tool", name: softRequiredTool };
+					softRequirementState.escalations++;
 					hasMoreToolCalls = true;
 				} else if (hasMoreToolCalls) {
 					const executionResult = await executeToolCalls(
@@ -1306,6 +1391,7 @@ async function runLoopBody(
 				await emitTurnEnd(stream, currentContext, message, toolResults, config, signal, {
 					willContinue: hasMoreToolCalls && !isDeadlineExceeded(config.deadline),
 				});
+				turnOpen = false;
 
 				if (isDeadlineExceeded(config.deadline)) {
 					endAgentStream(stream, newMessages, telemetry, stepCounter.count);
@@ -1361,6 +1447,11 @@ async function runLoopBody(
 
 		endAgentStream(stream, newMessages, telemetry, stepCounter.count);
 	} finally {
+		if (!preserveSoftRequirementState) {
+			softRequirementState.id = undefined;
+			softRequirementState.forcedToolChoice = undefined;
+			softRequirementState.escalations = 0;
+		}
 		if (deadlineTimer) {
 			clearTimeout(deadlineTimer);
 		}
@@ -1384,45 +1475,29 @@ async function emitHarmonyAudit(
 	);
 }
 
-/**
- * Stream an assistant response from the LLM.
- * This is where AgentMessage[] gets transformed to Message[] for the LLM.
- */
-async function streamAssistantResponse(
+interface PreparedProviderCall {
+	model: Model;
+	context: Context;
+	promptToolWireTools: Context["tools"];
+	ownedDialect: Dialect | undefined;
+}
+
+async function prepareProviderCall(
 	context: AgentContext,
 	config: AgentLoopConfig,
 	signal: AbortSignal | undefined,
-	stream: EventStream<AgentEvent, AgentMessage[]>,
-	telemetry: AgentTelemetry | undefined,
-	invokeAgentSpan: Span | undefined,
-	stepCounter: StepCounter,
-	streamFn?: StreamFn,
-	harmonyRetryAttempt = 0,
-	hostToolChoice?: ToolChoice,
-	forcedToolChoice?: ToolChoice,
-): Promise<AssistantMessage> {
-	// Re-resolve the model per provider call (like `getReasoning`): mid-run
-	// model switches — context promotion, retry fallback — must apply on the
-	// next call instead of the run silently finishing on the stale model
-	// captured at run start.
+): Promise<PreparedProviderCall> {
 	const model = config.getModel?.() ?? config.model;
-	// Apply context transform if configured (AgentMessage[] → AgentMessage[])
 	let messages = context.messages;
 	if (config.transformContext) {
 		messages = await config.transformContext(messages, signal);
 	}
 
-	// Convert to LLM-compatible messages (AgentMessage[] → Message[])
 	const llmMessages = await config.convertToLlm(messages);
 	const normalizedMessages = normalizeMessagesForProvider(llmMessages, model);
-
 	const ownedDialect: Dialect | undefined = config.dialect ?? resolveOwnedDialectFromEnv(Bun.env.PI_DIALECT);
 	const exampleDialect = ownedDialect ?? preferredDialect(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;
 	if (config.appendOnlyContext) {
 		config.appendOnlyContext.syncMessages(normalizedMessages);
@@ -1442,9 +1517,6 @@ async function streamAssistantResponse(
 		llmContext = await config.transformProviderContext(llmContext, model);
 	}
 
-	// Owned tool calling: take tool calls away from the provider and run them
-	// through the selected in-band prompt dialect. `PI_DIALECT=1` still
-	// force-enables GLM; `PI_DIALECT=<dialect>` force-enables that dialect.
 	let promptToolWireTools: Context["tools"];
 	if (ownedDialect && llmContext.tools && llmContext.tools.length > 0) {
 		promptToolWireTools = llmContext.tools;
@@ -1455,6 +1527,29 @@ async function streamAssistantResponse(
 			tools: undefined,
 		};
 	}
+	return { model, context: llmContext, promptToolWireTools, ownedDialect };
+}
+
+/**
+ * Stream an assistant response from the LLM.
+ * This is where AgentMessage[] gets transformed to Message[] for the LLM.
+ */
+async function streamAssistantResponse(
+	context: AgentContext,
+	config: AgentLoopConfig,
+	signal: AbortSignal | undefined,
+	stream: EventStream<AgentEvent, AgentMessage[]>,
+	telemetry: AgentTelemetry | undefined,
+	invokeAgentSpan: Span | undefined,
+	stepCounter: StepCounter,
+	streamFn?: StreamFn,
+	harmonyRetryAttempt = 0,
+	hostToolChoice?: ToolChoice,
+	forcedToolChoice?: ToolChoice,
+	prepared?: PreparedProviderCall,
+): Promise<AssistantMessage> {
+	const providerCall = prepared ?? (await prepareProviderCall(context, config, signal));
+	const { model, context: llmContext, promptToolWireTools, ownedDialect } = providerCall;
 
 	const streamFunction = streamFn || streamSimple;
 

package/src/agent.ts

@@ -39,6 +39,7 @@ import {
 import type { AppendOnlyContextManager } from "./append-only-context";
 import { isProviderRefusalMessage } from "./replay-policy";
 import type {
+	AgentBeforeModelCall,
 	AgentContext,
 	AgentEvent,
 	AgentLoopConfig,
@@ -267,6 +268,8 @@ export interface AgentOptions {
 	abortOnFabricatedToolResult?: boolean;
 	/** Dynamic tool-choice directive (hard {@link ToolChoice} or {@link SoftToolRequirement}), resolved once per turn. */
 	getToolChoice?: () => ToolChoiceDirective | undefined;
+	/** Reject a deferred hard choice when its named tool is no longer active. */
+	onToolChoiceUnavailable?: () => void;
 
 	/**
 	 * Cursor exec handlers for local tool execution.
@@ -409,6 +412,9 @@ export class Agent {
 	#dialect?: Dialect;
 	#abortOnFabricatedToolResult?: boolean;
 	#getToolChoice?: () => ToolChoiceDirective | undefined;
+	#onToolChoiceUnavailable?: () => void;
+	#softToolRequirementState: NonNullable<AgentLoopConfig["softToolRequirementState"]> = { escalations: 0 };
+	#deferredToolChoice?: ToolChoice;
 	#onPayload?: SimpleStreamOptions["onPayload"];
 	#onResponse?: SimpleStreamOptions["onResponse"];
 	#onSseEvent?: SimpleStreamOptions["onSseEvent"];
@@ -416,6 +422,8 @@ export class Agent {
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
 	#onTurnEnd?: (messages: AgentMessage[], signal?: AbortSignal, context?: AgentTurnEndContext) => Promise<void> | void;
+	#beforeModelCall?: AgentBeforeModelCall;
+	#additionalBeforeModelCalls = new Set<AgentBeforeModelCall>();
 	#asideMessageProvider?: () => AsideMessage[] | Promise<AsideMessage[]>;
 	#telemetry?: AgentLoopConfig["telemetry"];
 	#appendOnlyContext?: AppendOnlyContextManager;
@@ -490,6 +498,7 @@ export class Agent {
 		this.#dialect = opts.dialect;
 		this.#abortOnFabricatedToolResult = opts.abortOnFabricatedToolResult;
 		this.#getToolChoice = opts.getToolChoice;
+		this.#onToolChoiceUnavailable = opts.onToolChoiceUnavailable;
 		this.#onAssistantMessageEvent = opts.onAssistantMessageEvent;
 		this.#onHarmonyLeak = opts.onHarmonyLeak;
 		this.beforeToolCall = opts.beforeToolCall;
@@ -803,6 +812,28 @@ export class Agent {
 		this.#onTurnEnd = fn;
 	}
 
+	/**
+	 * Install or replace the host pre-model-call gate; pass `undefined` to
+	 * remove it. Gates are sampled when a run starts: installing the first
+	 * gate while a run is in flight takes effect on the next run.
+	 */
+	setBeforeModelCall(fn: AgentBeforeModelCall | undefined): void {
+		this.#beforeModelCall = fn;
+	}
+
+	/**
+	 * Add a pre-model callback without replacing callbacks owned by the host.
+	 * Returns a disposer that removes only this callback. Like
+	 * {@link setBeforeModelCall}, the first gate installed while a run is in
+	 * flight takes effect on the next run.
+	 */
+	addBeforeModelCall(fn: AgentBeforeModelCall): () => void {
+		this.#additionalBeforeModelCalls.add(fn);
+		return () => {
+			this.#additionalBeforeModelCalls.delete(fn);
+		};
+	}
+
 	/**
 	 * Provide a source of non-interrupting "aside" messages (e.g. background-job
 	 * completions, late LSP diagnostics) drained at each step boundary. Never
@@ -928,10 +959,20 @@ export class Agent {
 		this.#followUpQueue = [];
 	}
 
+	/**
+	 * Drop tool-directive state retained across a gate-stopped run: the
+	 * deferred hard choice and the soft-requirement lifecycle.
+	 */
+	clearDeferredToolDirectives() {
+		this.#deferredToolChoice = undefined;
+		this.#softToolRequirementState = { escalations: 0 };
+	}
+
 	clearAllQueues() {
 		this.#steeringQueue = [];
 		this.#followUpQueue = [];
 		this.#notifySteeringWaiters();
+		this.clearDeferredToolDirectives();
 	}
 
 	hasQueuedMessages(): boolean {
@@ -1044,6 +1085,7 @@ export class Agent {
 		this.#steeringQueue = [];
 		this.#followUpQueue = [];
 		this.#notifySteeringWaiters();
+		this.clearDeferredToolDirectives();
 	}
 
 	/** Send a prompt with an AgentMessage */
@@ -1219,13 +1261,28 @@ export class Agent {
 			return entry.toolResult;
 		};
 
+		let claimedToolChoice: ToolChoice | undefined;
 		const getToolChoice = (): ToolChoiceDirective | undefined => {
+			claimedToolChoice = undefined;
+			const deferred = this.#deferredToolChoice;
+			if (deferred !== undefined) {
+				this.#deferredToolChoice = undefined;
+				const active = refreshToolChoiceForActiveTools(deferred, this.#state.tools);
+				if (active !== undefined) {
+					claimedToolChoice = deferred;
+					return active;
+				}
+				this.#onToolChoiceUnavailable?.();
+			}
+
 			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);
+				const active = refreshToolChoiceForActiveTools(queued, this.#state.tools);
+				if (active !== undefined) claimedToolChoice = queued;
+				return active;
 			}
 			return refreshToolChoiceForActiveTools(options?.toolChoice, this.#state.tools);
 		};
@@ -1268,6 +1325,18 @@ export class Agent {
 				context.systemPrompt = this.#state.systemPrompt;
 				context.tools = this.#toolsForModel(this.#state.model ?? model);
 			},
+			beforeModelCall:
+				this.#beforeModelCall || this.#additionalBeforeModelCalls.size > 0
+					? async (context, signal) => {
+							const result = (await this.#beforeModelCall?.(context, signal)) || undefined;
+							if (result?.stop) return result;
+							for (const callback of this.#additionalBeforeModelCalls) {
+								const callbackResult = (await callback(context, signal)) || undefined;
+								if (callbackResult?.stop) return callbackResult;
+							}
+							return undefined;
+						}
+					: undefined,
 			cursorExecHandlers: this.#cursorExecHandlers,
 			cursorOnToolResult,
 			cwd: this.#cwd,
@@ -1288,6 +1357,10 @@ export class Agent {
 			onHarmonyLeak: this.#onHarmonyLeak,
 			onTurnEnd: (messages, signal, context) => this.#onTurnEnd?.(messages, signal, context),
 			getToolChoice,
+			softToolRequirementState: this.#softToolRequirementState,
+			onToolChoiceRejected: () => {
+				if (claimedToolChoice !== undefined) this.#deferredToolChoice = claimedToolChoice;
+			},
 			getModel: () => this.#state.model ?? model,
 			getReasoning: () => this.#state.thinkingLevel,
 			getDisableReasoning: () => this.#state.disableReasoning,
@@ -1322,6 +1395,7 @@ export class Agent {
 
 		let partial: AgentMessage | null = null;
 		const completedToolCallIds = new Set<string>();
+		let turnOpen = false;
 
 		try {
 			const stream = messages
@@ -1329,6 +1403,8 @@ export class Agent {
 				: agentLoopContinue(context, config, this.#abortController.signal, this.streamFn);
 
 			for await (const event of stream) {
+				if (event.type === "turn_start") turnOpen = true;
+				if (event.type === "turn_end") turnOpen = false;
 				// Update internal state based on events
 				switch (event.type) {
 					case "message_start":
@@ -1448,6 +1524,10 @@ export class Agent {
 						};
 
 			if (shouldEmitVisibleError) {
+				if (!turnOpen) {
+					this.#emit({ type: "turn_start" });
+					turnOpen = true;
+				}
 				if (!hadAssistantStart) {
 					this.#state.streamMessage = errorMsg;
 					this.#emit({ type: "message_start", message: errorMsg });
@@ -1489,6 +1569,7 @@ export class Agent {
 					toolResults.push(toolResult);
 				}
 				this.#emit({ type: "turn_end", message: errorMsg, toolResults });
+				turnOpen = false;
 				this.#emit({ type: "agent_end", messages: [errorMsg, ...toolResults] });
 			} else {
 				this.appendMessage(errorMsg);

package/src/proxy.ts

@@ -56,12 +56,14 @@ export type ProxyAssistantMessageEvent =
 			type: "done";
 			reason: Extract<StopReason, "stop" | "length" | "toolUse">;
 			usage: AssistantMessage["usage"];
+			content?: AssistantMessage["content"];
 	  }
 	| {
 			type: "error";
 			reason: Extract<StopReason, "aborted" | "error">;
 			errorMessage?: string;
 			usage: AssistantMessage["usage"];
+			content?: AssistantMessage["content"];
 	  };
 
 export interface ProxyStreamOptions extends SimpleStreamOptions {
@@ -372,6 +374,7 @@ function processProxyEvent(
 		case "done":
 			partial.stopReason = proxyEvent.reason;
 			partial.usage = proxyEvent.usage;
+			if (proxyEvent.content !== undefined) partial.content = proxyEvent.content;
 			calculateCost(model, partial.usage);
 			scrubPartialJson(partial);
 			return { type: "done", reason: proxyEvent.reason, message: partial };
@@ -380,6 +383,7 @@ function processProxyEvent(
 			partial.stopReason = proxyEvent.reason;
 			partial.errorMessage = proxyEvent.errorMessage;
 			partial.usage = proxyEvent.usage;
+			if (proxyEvent.content !== undefined) partial.content = proxyEvent.content;
 			calculateCost(model, partial.usage);
 			scrubPartialJson(partial);
 			return { type: "error", reason: proxyEvent.reason, error: partial };

package/src/types.ts

@@ -48,6 +48,24 @@ export interface AgentTurnEndContext {
 	willContinue: boolean;
 }
 
+export interface AgentPreModelCallStop {
+	/** Stop the agent loop before sending the next provider request. */
+	stop: true;
+	/** Optional owner-facing reason, logged by the loop when it stops. */
+	reason?: string;
+}
+
+export type AgentPreModelCallResult = AgentPreModelCallStop | undefined;
+
+/**
+ * A pre-model-call gate. Return {@link AgentPreModelCallStop} to refuse the
+ * request, or nothing to proceed; the signal aborts with the run.
+ */
+export type AgentBeforeModelCall = (
+	context: Context,
+	signal?: AbortSignal,
+) => AgentPreModelCallResult | void | Promise<AgentPreModelCallResult | void>;
+
 /**
  * A soft tool requirement: the host wants `toolName` called before the loop
  * runs other tools or yields, but WITHOUT paying the forced-`toolChoice` cost
@@ -87,6 +105,13 @@ export interface SoftToolRequirement {
  */
 export type ToolChoiceDirective = ToolChoice | SoftToolRequirement;
 
+/** Mutable soft-requirement lifecycle retained across stopped agent runs. */
+export interface SoftToolRequirementState {
+	id?: string;
+	forcedToolChoice?: ToolChoice;
+	escalations: number;
+}
+
 /** 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;
@@ -276,9 +301,23 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	/**
 	 * Refreshes prompt/tool context from live session state before each model call.
 	 * Use this when tool availability or the system prompt can change mid-turn.
+	 *
+	 * Runs after pending messages are folded in and before provider conversion.
+	 * Mutate the agent context here; use `beforeModelCall` to inspect the
+	 * provider-bound context.
 	 */
 	syncContextBeforeModelCall?: (context: AgentContext) => void | Promise<void>;
 
+	/**
+	 * Asked after the complete provider context has been built, including
+	 * message conversion, provider transforms, normalized tools, and owned
+	 * dialect prompt injection. Returning {@link AgentPreModelCallStop} ends
+	 * the stream without emitting `turn_start`, so no turn is left open and no
+	 * request is billed. Return nothing to proceed. The signal aborts when
+	 * the run is canceled or its deadline expires.
+	 */
+	beforeModelCall?: AgentBeforeModelCall;
+
 	/**
 	 * Optional transform applied to tool call arguments before execution.
 	 * Use for deobfuscating secrets or rewriting arguments.
@@ -356,6 +395,19 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	getToolChoice?: () => ToolChoiceDirective | undefined;
 
+	/**
+	 * Soft-requirement lifecycle retained by the host when a pre-model-call
+	 * gate stops a run before its pending reminder or escalation is served.
+	 */
+	softToolRequirementState?: SoftToolRequirementState;
+
+	/**
+	 * Notifies the host that the pre-model-call gate stopped the run after a
+	 * hard tool choice was obtained from {@link getToolChoice} but before it
+	 * was served, so the host can retain it for the next admitted request.
+	 */
+	onToolChoiceRejected?: () => void;
+
 	/**
 	 * Dynamic reasoning effort override, resolved per LLM call.
 	 * When set and returns a value, overrides the static `reasoning` captured