@oh-my-pi/pi-coding-agent 17.1.5 → 17.1.7

package/src/session/streaming-output.ts

@@ -53,12 +53,17 @@ export interface OutputSummary {
 export interface OutputSinkOptions {
 	artifactPath?: string;
 	artifactId?: string;
-	/** Tail buffer budget (bytes). Default DEFAULT_MAX_BYTES. */
+	/**
+	 * Total inline body budget (bytes). Default DEFAULT_MAX_BYTES. The head
+	 * window and rolling tail window share this budget, so a composed
+	 * `dump()` body never exceeds it (plus the elision marker).
+	 */
 	spillThreshold?: number;
 	/**
 	 * When > 0, the sink keeps the first `headBytes` of output in addition to
 	 * the rolling tail window. Output between the two windows is elided
-	 * (middle elision). Default 0 = tail-only behavior.
+	 * (middle elision). Clamped to `spillThreshold / 2` so the tail keeps at
+	 * least half the inline budget. Default 0 = tail-only behavior.
 	 */
 	headBytes?: number;
 	/**
@@ -799,7 +804,7 @@ export class OutputSink {
 		this.#artifactPath = artifactPath;
 		this.#artifactId = artifactId;
 		this.#spillThreshold = spillThreshold;
-		this.#headLimit = Math.max(0, headBytes);
+		this.#headLimit = Math.max(0, Math.min(headBytes, Math.floor(spillThreshold / 2)));
 		this.#maxColumns = Math.max(0, maxColumns);
 		this.#onChunk = onChunk;
 		this.#chunkThrottleMs = chunkThrottleMs;
@@ -969,16 +974,23 @@ export class OutputSink {
 		return parts.join("");
 	}
 
+	// The rolling tail budget is whatever the head window has not consumed of
+	// the inline budget: `spillThreshold - #headBytes`. While the head window
+	// fills it shrinks toward `spillThreshold - headLimit`; after `replace()`
+	// (head cleared) it grows back to the full threshold. This keeps
+	// `head + tail <= spillThreshold`, so the composed dump body fits the
+	// inline byte cap by construction.
+
 	#willOverflow(dataBytes: number): boolean {
 		// Triggers file mirroring as soon as the next chunk would push us over
-		// the tail budget (head retention does not change spill-to-artifact).
-		return this.#bufferBytes + dataBytes > this.#spillThreshold;
+		// the tail budget — i.e. the first byte that could be lost from memory.
+		return this.#bufferBytes + dataBytes > this.#spillThreshold - this.#headBytes;
 	}
 
 	#pushTail(chunk: string, dataBytes: number): void {
 		if (dataBytes === 0) return;
 
-		const threshold = this.#spillThreshold;
+		const threshold = Math.max(0, this.#spillThreshold - this.#headBytes);
 		const willOverflow = this.#bufferBytes + dataBytes > threshold;
 
 		if (!willOverflow) {

package/src/session/tool-choice-queue.ts

@@ -13,15 +13,15 @@ export interface RejectInfo {
 	reason: "aborted" | "error" | "cleared" | "removed" | "unavailable" | "not_invoked";
 }
 
-/** "requeue" replays the lost yield next turn; "drop" (or void/undefined) discards it. */
-export type RejectOutcome = "requeue" | "drop";
+/** Controls whether rejection replays a yield, drops it, or drops its remaining sequence. */
+export type RejectOutcome = "requeue" | "drop" | "drop_sequence";
 
 export interface DirectiveCallbacks {
 	/** Fires when the yield completed; onInvoked directives require the requested tool to run first. */
 	onResolved?: (info: ResolveInfo) => void;
 	/**
-	 * Fires when the yield is being discarded. Return "requeue" to replay the
-	 * same value at the head of the queue for the next turn. Default: "drop".
+	 * Return "requeue" to replay the same value, or "drop_sequence" to discard
+	 * its directive including later yields. Default: drop the rejected yield.
 	 */
 	onRejected?: (info: RejectInfo) => RejectOutcome | undefined;
 	/**
@@ -39,6 +39,8 @@ export interface ToolChoiceDirective {
 	/** Stable label for targeted removal and debugging (e.g. "user-force"). */
 	label: string;
 	callbacks: DirectiveCallbacks;
+	/** Original multi-yield directive retained across one-yield replays. */
+	sequenceRoot?: ToolChoiceDirective;
 }
 
 export interface PushOptions {
@@ -83,6 +85,12 @@ interface PendingInvoker {
 
 export class ToolChoiceQueue {
 	#queue: ToolChoiceDirective[] = [];
+	/**
+	 * In-flight yield awaiting resolve()/reject(). May outlive the run that
+	 * claimed it: a pre-model gate stop ends the run without a `turn_end`, and
+	 * the claim is finalized later — by the next admitted turn's `turn_end`,
+	 * the abort safety net, or an `unavailable` rejection on redeem.
+	 */
 	#inFlight: InFlight | undefined;
 	/**
 	 * Label of the directive whose last yield was resolved this turn.
@@ -178,6 +186,12 @@ export class ToolChoiceQueue {
 			reason,
 		});
 
+		if (outcome === "drop_sequence") {
+			const root = inFlight.directive.sequenceRoot ?? inFlight.directive;
+			this.#queue = this.#queue.filter(directive => directive !== root && directive.sequenceRoot !== root);
+			return;
+		}
+
 		if (outcome === "requeue") {
 			// Re-queue only the lost yield, not the rest of the sequence. Carry forward
 			// callbacks so the replayed yield still executes and finalizes correctly,
@@ -185,6 +199,7 @@ export class ToolChoiceQueue {
 			this.#queue.unshift({
 				generator: onceGen(inFlight.yielded),
 				label: `${inFlight.directive.label}-requeued`,
+				sequenceRoot: inFlight.directive.sequenceRoot ?? inFlight.directive,
 				callbacks: {
 					onResolved: inFlight.directive.callbacks.onResolved,
 					onInvoked: inFlight.directive.callbacks.onInvoked,

package/src/session/turn-recovery.ts

@@ -11,6 +11,7 @@ import type {
 	AssistantRetryRecovery,
 	AssistantRetryRecoveryKind,
 	CodexCompactionContext,
+	Effort,
 	Model,
 	TextContent,
 	ToolChoice,
@@ -27,7 +28,12 @@ import type { RecoveredRetryError } from "../extensibility/shared-events";
 import emptyStopRetryTemplate from "../prompts/system/empty-stop-retry.md" with { type: "text" };
 import thinkingLoopRedirectTemplate from "../prompts/system/thinking-loop-redirect.md" with { type: "text" };
 import unexpectedStopRetryTemplate from "../prompts/system/unexpected-stop-retry.md" with { type: "text" };
-import type { ConfiguredThinkingLevel } from "../thinking";
+import {
+	AUTO_THINKING,
+	type ConfiguredThinkingLevel,
+	clampThinkingLevelToCeiling,
+	modelSupportsEffortCeiling,
+} from "../thinking";
 import type { AgentSessionEvent } from "./agent-session-events";
 import type { InitialRetryFallbackState } from "./agent-session-types";
 import { isEmptyErrorTurn } from "./messages";
@@ -98,6 +104,8 @@ export interface TurnRecoveryHost {
 	thinkingLevel(): ThinkingLevel | undefined;
 	configuredThinkingLevel(): ConfiguredThinkingLevel | undefined;
 	setThinkingLevel(level: ConfiguredThinkingLevel | undefined): void;
+	/** Hard per-session effort ceiling; fallback recovery must never raise thinking above it. */
+	thinkingLevelCeiling(): Effort | undefined;
 	isDisposed(): boolean;
 	isStreaming(): boolean;
 	isCompacting(): boolean;
@@ -110,7 +118,7 @@ export interface TurnRecoveryHost {
 	waitForSessionMessagePersistence(message: AssistantMessage): Promise<void>;
 	appendSessionMessage(message: AssistantMessage): void;
 	sessionMessageAlreadyPersisted(message: AssistantMessage): boolean;
-	setModelWithProviderSessionReset(model: Model): void;
+	setModelWithProviderSessionReset(model: Model): Promise<void>;
 	resetCurrentResponsesProviderSession(reason: string): void;
 	maybeAutoRedeemCodexReset(): Promise<boolean>;
 	runAutoCompaction(
@@ -1011,9 +1019,16 @@ export class TurnRecovery {
 		// Capture the configured selector (auto-aware) so a fallback chain preserves
 		// `auto` instead of collapsing it to the level it resolved to this turn.
 		const currentThinkingLevel = this.#host.configuredThinkingLevel();
-		const nextThinkingLevel = selector.thinkingLevel ?? currentThinkingLevel;
+		const requestedThinkingLevel = selector.thinkingLevel ?? currentThinkingLevel;
+		// A fallback selector's explicit level (or the carried level after the
+		// replacement model's floor clamp) must never exceed the session's
+		// per-spawn effort ceiling.
+		const nextThinkingLevel =
+			requestedThinkingLevel === AUTO_THINKING
+				? requestedThinkingLevel
+				: clampThinkingLevelToCeiling(candidate, requestedThinkingLevel, this.#host.thinkingLevelCeiling());
 		const candidateSelector = formatModelStringWithRouting(candidate);
-		this.#host.setModelWithProviderSessionReset(candidate);
+		await this.#host.setModelWithProviderSessionReset(candidate);
 		this.#host.sessionManager.appendModelChange(candidateSelector, EPHEMERAL_MODEL_CHANGE_ROLE);
 		this.#host.settings.getStorage()?.recordModelUsage(candidateSelector);
 		this.#host.setThinkingLevel(nextThinkingLevel);
@@ -1041,11 +1056,15 @@ export class TurnRecovery {
 		const role = this.#activeRetryFallback?.role ?? this.resolveRetryFallbackRole(currentSelector);
 		if (!role) return false;
 
+		const ceiling = this.#host.thinkingLevelCeiling();
 		for (const selector of this.findRetryFallbackCandidates(role, currentSelector)) {
 			if (this.isRetryFallbackSelectorSuppressed(selector)) continue;
 			const resolved = resolveModelOverride([selector.raw], this.#host.modelRegistry, this.#host.settings);
 			const candidate = resolved.model ?? this.#host.modelRegistry.find(selector.provider, selector.id);
 			if (!candidate) continue;
+			// A candidate whose effort floor exceeds the per-spawn ceiling would be
+			// clamped UP past the cap by its model floor — skip it entirely.
+			if (ceiling !== undefined && !modelSupportsEffortCeiling(candidate, ceiling)) continue;
 			const apiKey = await this.#host.modelRegistry.getApiKey(candidate, this.#host.sessionId());
 			if (!apiKey) continue;
 			await this.applyRetryFallbackCandidate(role, selector, currentSelector, options);
@@ -1128,7 +1147,7 @@ export class TurnRecovery {
 		const apiKey = await this.#host.modelRegistry.getApiKey(baseModel, this.#host.sessionId());
 		if (!apiKey) return false;
 		const baseSelector = formatModelStringWithRouting(baseModel);
-		this.#host.setModelWithProviderSessionReset(baseModel);
+		await this.#host.setModelWithProviderSessionReset(baseModel);
 		this.#host.sessionManager.appendModelChange(baseSelector, EPHEMERAL_MODEL_CHANGE_ROLE);
 		this.#host.settings.getStorage()?.recordModelUsage(baseSelector);
 		await this.#host.emitSessionEvent({
@@ -1182,7 +1201,7 @@ export class TurnRecovery {
 		const thinkingToApply =
 			currentThinkingLevel === lastAppliedFallbackThinkingLevel ? originalThinkingLevel : currentThinkingLevel;
 		const primarySelector = formatModelStringWithRouting(primaryModel);
-		this.#host.setModelWithProviderSessionReset(primaryModel);
+		await this.#host.setModelWithProviderSessionReset(primaryModel);
 		this.#host.sessionManager.appendModelChange(primarySelector, EPHEMERAL_MODEL_CHANGE_ROLE);
 		this.#host.settings.getStorage()?.recordModelUsage(primarySelector);
 		this.#host.setThinkingLevel(thinkingToApply);

package/src/slash-commands/builtin-registry.ts

@@ -53,6 +53,7 @@ import {
 	renderChangelogEntries,
 } from "../utils/changelog";
 import { copyToClipboard } from "../utils/clipboard";
+import type { InspectImageMode } from "../utils/inspect-image-mode";
 import { CollabQrCodeComponent } from "./helpers/collab-qrcode";
 import { buildContextReportText } from "./helpers/context-report";
 import { formatDuration } from "./helpers/format";
@@ -151,6 +152,33 @@ async function applyComputerUseToggle(session: AgentSession, enable: boolean): P
 		: "Computer use disabled for this session.";
 }
 
+/** Session-effective `/vision status` line. */
+function formatVisionStatus(session: AgentSession): string {
+	const { mode, active, model } = session.inspectImageState();
+	const override = session.getInspectImageModeOverride();
+	const modelObj = session.model;
+	const capability = modelObj
+		? modelObj.input.includes("image")
+			? "native image input"
+			: "no native image input"
+		: "no active model";
+	return [
+		`inspect_image: ${active ? "active" : "inactive"}`,
+		`mode: ${mode}${override ? " (session override)" : ""}`,
+		...(override ? [`configured: ${session.settings.get("inspect_image.mode")}`] : []),
+		`model: ${model ?? "none"} (${capability})`,
+	].join(" · ");
+}
+
+/** Applies a `/vision` mode for this session and returns the operator feedback line. */
+async function applyVisionMode(session: AgentSession, mode: InspectImageMode): Promise<string> {
+	const applied = await session.setInspectImageMode(mode);
+	if (!applied) {
+		return "inspect_image is unavailable in this session.";
+	}
+	return `Vision mode: ${mode}. ${formatVisionStatus(session)}`;
+}
+
 const AUTOCOMPLETE_DETAIL_LIMIT = 48;
 
 function shortDetail(value: string, limit = AUTOCOMPLETE_DETAIL_LIMIT): string {
@@ -647,6 +675,47 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "vision",
+		description: "Control the inspect_image vision-delegation tool for this session",
+		acpDescription: "Toggle vision delegation",
+		acpInputHint: "[on|off|auto|status]",
+		subcommands: [
+			{ name: "on", description: "Always expose inspect_image this session" },
+			{ name: "off", description: "Never expose inspect_image this session" },
+			{ name: "auto", description: "Follow inspect_image.mode (auto hides it for vision-capable models)" },
+			{ name: "status", description: "Show inspect_image status" },
+		],
+		allowArgs: true,
+		getTuiAutocompleteDescription: runtime => `Vision: ${runtime.ctx.session.inspectImageState().mode}`,
+		handle: async (command, runtime) => {
+			const arg = command.args.trim().toLowerCase();
+			if (arg === "status") {
+				await runtime.output(formatVisionStatus(runtime.session));
+				return commandConsumed();
+			}
+			if (arg === "on" || arg === "off" || arg === "auto") {
+				await runtime.output(await applyVisionMode(runtime.session, arg));
+				return commandConsumed();
+			}
+			return usage("Usage: /vision [on|off|auto|status]", runtime);
+		},
+		handleTui: async (command, runtime) => {
+			const arg = command.args.trim().toLowerCase();
+			if (arg === "status") {
+				runtime.ctx.showStatus(formatVisionStatus(runtime.ctx.session));
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (arg === "on" || arg === "off" || arg === "auto") {
+				runtime.ctx.showStatus(await applyVisionMode(runtime.ctx.session, arg));
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			runtime.ctx.showStatus("Usage: /vision [on|off|auto|status]");
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "prewalk",
 		description: "Switch to a fast/cheap model at the next action (works even without --prewalk)",

package/src/task/executor.ts

@@ -2647,9 +2647,16 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				progress.contextWindow = model.contextWindow;
 			}
 			// Caller-requested coarse effort maps onto the resolved model's
-			// supported range; undefined (no effort, or no controllable effort
-			// surface) falls through to the normal selectors below.
-			const effortLevel = options.effort !== undefined ? resolveTaskEffortLevel(model, options.effort) : undefined;
+			// supported range, then respects the operator-configured ceiling.
+			// Undefined (no effort, or no controllable effort surface) falls
+			// through to the normal selectors below.
+			// The ceiling outlives initial resolution: it rides into the session so
+			// retry-fallback recovery can never clamp effort back up past it.
+			const spawnEffortCeiling = options.effort !== undefined ? settings.get("task.maxEffort") : undefined;
+			const effortLevel =
+				options.effort !== undefined
+					? resolveTaskEffortLevel(model, options.effort, spawnEffortCeiling)
+					: undefined;
 			if (model) {
 				const displayLevel = effortLevel ?? (explicitThinkingLevel ? resolvedThinkingLevel : undefined);
 				progress.resolvedModel =
@@ -2773,6 +2780,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				modelPatternDefaultFallbackChain:
 					model || modelOverride === undefined ? undefined : defaultRetryFallbackChain,
 				thinkingLevel: effectiveThinkingLevel,
+				thinkingLevelCeiling: spawnEffortCeiling,
 				toolNames,
 				outputSchema,
 				outputSchemaMode: options.outputSchemaMode,

package/src/task/index.ts

@@ -156,27 +156,31 @@ export function formatResultOutputFallback(result: Pick<SingleResult, "output" |
 	return result.requests > 0 ? `(no output) after ${result.requests} req` : "(no output)";
 }
 
-/**
- * Render the tool description from a cached agent list and current settings.
- */
-function renderDescription(
-	agents: AgentDefinition[],
-	isolationEnabled: boolean,
-	applyIsolatedChanges: boolean,
-	disabledAgents: string[],
-	batchEnabled: boolean,
-	asyncEnabled: boolean,
-	ircEnabled: boolean,
-	parentSpawns: string,
-): string {
-	const spawnPolicy = resolveSpawnPolicy(parentSpawns);
+interface TaskDescriptionOptions {
+	agents: AgentDefinition[];
+	isolationEnabled: boolean;
+	applyIsolatedChanges: boolean;
+	disabledAgents: string[];
+	batchEnabled: boolean;
+	effortEnabled: boolean;
+	asyncEnabled: boolean;
+	ircEnabled: boolean;
+	parentSpawns: string;
+}
+
+/** Render the tool description from a cached agent list and current settings. */
+function renderDescription(options: TaskDescriptionOptions): string {
+	const spawnPolicy = resolveSpawnPolicy(options.parentSpawns);
 	const spawningDisabled = !spawnPolicy.enabled;
-	let filteredAgents = disabledAgents.length > 0 ? agents.filter(a => !disabledAgents.includes(a.name)) : agents;
+	let filteredAgents =
+		options.disabledAgents.length > 0
+			? options.agents.filter(agent => !options.disabledAgents.includes(agent.name))
+			: options.agents;
 	if (spawningDisabled) {
 		filteredAgents = [];
 	} else if (spawnPolicy.allowedAgents !== null) {
 		const allowed = new Set(spawnPolicy.allowedAgents);
-		filteredAgents = filteredAgents.filter(a => allowed.has(a.name));
+		filteredAgents = filteredAgents.filter(agent => allowed.has(agent.name));
 	}
 	const renderedAgents = filteredAgents.map(agent => ({
 		name: agent.name,
@@ -188,12 +192,13 @@ function renderDescription(
 		agents: renderedAgents,
 		spawningDisabled,
 		defaultAgent: spawnPolicy.defaultAgent,
-		isolationEnabled,
-		applyIsolatedChanges,
-		batchEnabled,
-		asyncEnabled,
+		isolationEnabled: options.isolationEnabled,
+		applyIsolatedChanges: options.applyIsolatedChanges,
+		batchEnabled: options.batchEnabled,
+		effortEnabled: options.effortEnabled,
+		asyncEnabled: options.asyncEnabled,
 		hasBlockingAgents: renderedAgents.some(agent => agent.blocking),
-		ircEnabled,
+		ircEnabled: options.ircEnabled,
 	});
 }
 
@@ -581,28 +586,34 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		const planMode = this.session.getPlanModeState?.()?.enabled === true;
 		const isolationEnabled = !planMode && this.session.settings.get("task.isolation.mode") !== "none";
 		const defaultAgent = resolveSpawnPolicy(this.session.getSessionSpawns()).defaultAgent;
-		return getTaskSchema({ isolationEnabled, batchEnabled: this.#isBatchEnabled(), defaultAgent });
+		return getTaskSchema({
+			isolationEnabled,
+			batchEnabled: this.#isBatchEnabled(),
+			effortEnabled: this.session.settings.get("task.enableEffort"),
+			defaultAgent,
+		});
 	}
 
 	renderCall(args: unknown, options: Parameters<typeof renderTaskCall>[1], theme: Theme) {
 		return renderTaskCall(repairTaskParams(args as TaskParams), options, theme);
 	}
 
-	/** Dynamic description that reflects current disabled-agent settings */
+	/** Dynamic description that reflects current task settings. */
 	get description(): string {
 		const disabledAgents = this.session.settings.get("task.disabledAgents") as string[];
 		const planMode = this.session.getPlanModeState?.()?.enabled === true;
 		const isolationMode = this.session.settings.get("task.isolation.mode");
-		return renderDescription(
-			this.#discoveredAgents,
-			!planMode && isolationMode !== "none",
-			this.session.settings.get("task.isolation.apply"),
+		return renderDescription({
+			agents: this.#discoveredAgents,
+			isolationEnabled: !planMode && isolationMode !== "none",
+			applyIsolatedChanges: this.session.settings.get("task.isolation.apply"),
 			disabledAgents,
-			this.#isBatchEnabled(),
-			this.session.settings.get("async.enabled"),
-			isIrcEnabled(this.session.settings, this.session.taskDepth ?? 0),
-			this.session.getSessionSpawns() ?? "*",
-		);
+			batchEnabled: this.#isBatchEnabled(),
+			effortEnabled: this.session.settings.get("task.enableEffort"),
+			asyncEnabled: this.session.settings.get("async.enabled"),
+			ircEnabled: isIrcEnabled(this.session.settings, this.session.taskDepth ?? 0),
+			parentSpawns: this.session.getSessionSpawns() ?? "*",
+		});
 	}
 	private constructor(
 		private readonly session: ToolSession,

package/src/task/types.ts

@@ -115,7 +115,6 @@ export const taskItemSchema = type({
 	"name?": "string",
 	agent: "string = 'task'",
 	task: "string",
-	"effort?": effortRule,
 	"outputSchema?": outputSchemaInputSchema,
 	"schemaMode?": '"permissive" | "strict"',
 	"+": "delete",
@@ -124,7 +123,6 @@ const taskItemSchemaIsolated = type({
 	"name?": "string",
 	agent: "string = 'task'",
 	task: "string",
-	"effort?": effortRule,
 	"outputSchema?": outputSchemaInputSchema,
 	"schemaMode?": '"permissive" | "strict"',
 	"isolated?": "boolean",
@@ -153,7 +151,6 @@ export const taskSchema = type({
 	"name?": "string",
 	agent: "string = 'task'",
 	task: "string",
-	"effort?": effortRule,
 	"outputSchema?": outputSchemaInputSchema,
 	"schemaMode?": '"permissive" | "strict"',
 	"isolated?": "boolean",
@@ -163,7 +160,6 @@ const taskSchemaNoIsolation = type({
 	"name?": "string",
 	agent: "string = 'task'",
 	task: "string",
-	"effort?": effortRule,
 	"outputSchema?": outputSchemaInputSchema,
 	"schemaMode?": '"permissive" | "strict"',
 	"+": "delete",
@@ -200,15 +196,17 @@ function createTaskSchema(options: {
 	isolationEnabled: boolean;
 	batchEnabled: boolean;
 	defaultAgent: string;
+	effortEnabled: boolean;
 }): BaseType {
 	const agent = taskAgentSchemaRule(options.defaultAgent);
+	const effortField = options.effortEnabled ? { "effort?": effortRule } : {};
 	if (options.batchEnabled) {
 		if (options.isolationEnabled) {
 			const item = type.raw({
 				"name?": "string",
 				agent,
 				task: "string",
-				"effort?": effortRule,
+				...effortField,
 				"outputSchema?": outputSchemaInputSchema,
 				"schemaMode?": '"permissive" | "strict"',
 				"isolated?": "boolean",
@@ -224,7 +222,7 @@ function createTaskSchema(options: {
 			"name?": "string",
 			agent,
 			task: "string",
-			"effort?": effortRule,
+			...effortField,
 			"outputSchema?": outputSchemaInputSchema,
 			"schemaMode?": '"permissive" | "strict"',
 			"+": "delete",
@@ -240,7 +238,7 @@ function createTaskSchema(options: {
 			"name?": "string",
 			agent,
 			task: "string",
-			"effort?": effortRule,
+			...effortField,
 			"outputSchema?": outputSchemaInputSchema,
 			"schemaMode?": '"permissive" | "strict"',
 			"isolated?": "boolean",
@@ -251,33 +249,30 @@ function createTaskSchema(options: {
 		"name?": "string",
 		agent,
 		task: "string",
-		"effort?": effortRule,
+		...effortField,
 		"outputSchema?": outputSchemaInputSchema,
 		"schemaMode?": '"permissive" | "strict"',
 		"+": "delete",
 	});
 }
 
-export function getTaskSchema(options: { isolationEnabled: boolean; batchEnabled: boolean }): DynamicTaskSchema;
-export function getTaskSchema(options: {
-	isolationEnabled: boolean;
-	batchEnabled: boolean;
-	defaultAgent: string;
-}): TaskToolSchemaInstance;
+/** Build the task wire schema for the current settings and spawn policy. */
 export function getTaskSchema(options: {
 	isolationEnabled: boolean;
 	batchEnabled: boolean;
+	effortEnabled?: boolean;
 	defaultAgent?: string;
 }): TaskToolSchemaInstance {
 	const defaultAgent = options.defaultAgent ?? "task";
-	if (defaultAgent === "task") {
+	const effortEnabled = options.effortEnabled ?? false;
+	if (defaultAgent === "task" && !effortEnabled) {
 		if (options.batchEnabled) return options.isolationEnabled ? taskSchemaBatch : taskSchemaBatchNoIsolation;
 		return options.isolationEnabled ? taskSchema : taskSchemaNoIsolation;
 	}
-	const key = `${options.isolationEnabled ? "iso" : "flat"}:${options.batchEnabled ? "batch" : "single"}:${defaultAgent}`;
+	const key = `${options.isolationEnabled ? "iso" : "flat"}:${options.batchEnabled ? "batch" : "single"}:${effortEnabled ? "effort" : "default"}:${defaultAgent}`;
 	const cached = taskSchemaCache.get(key);
 	if (cached) return cached;
-	const schema = createTaskSchema({ ...options, defaultAgent });
+	const schema = createTaskSchema({ ...options, effortEnabled, defaultAgent });
 	taskSchemaCache.set(key, schema);
 	return schema;
 }

package/src/thinking.ts

@@ -271,19 +271,82 @@ export type TaskEffort = (typeof TASK_EFFORTS)[number];
  * at — high, xhigh, or max), `med` = the middle (lower of the two middles for
  * an even-sized range). Without a model, maps over the full canonical range.
  * Returns `undefined` when the model has no controllable effort surface, so
- * callers fall back to their default selector (e.g. `auto`).
+ * callers fall back to their default selector (e.g. `auto`). Throws when the
+ * configured ceiling is below the model's lowest supported effort.
  */
-export function resolveTaskEffortLevel(model: Model | undefined, effort: TaskEffort): Effort | undefined {
+export function resolveTaskEffortLevel(
+	model: Model | undefined,
+	effort: TaskEffort,
+	maxEffort?: Effort,
+): Effort | undefined {
 	const supported = model ? getSupportedEfforts(model) : THINKING_EFFORTS;
 	if (supported.length === 0) return undefined;
+	let resolved: Effort;
 	switch (effort) {
 		case "lo":
-			return supported[0];
+			resolved = supported[0];
+			break;
 		case "med":
-			return supported[(supported.length - 1) >> 1];
+			resolved = supported[(supported.length - 1) >> 1];
+			break;
 		case "hi":
-			return supported[supported.length - 1];
+			resolved = supported[supported.length - 1];
+			break;
+	}
+	if (maxEffort === undefined) return resolved;
+	const maxIndex = THINKING_EFFORTS.indexOf(maxEffort);
+	const ceiling = supported.findLast(candidate => THINKING_EFFORTS.indexOf(candidate) <= maxIndex);
+	if (ceiling === undefined) {
+		const modelName = model ? `${model.provider}/${model.id}` : "Selected model";
+		throw new RangeError(`${modelName} has no supported thinking effort at or below task.maxEffort=${maxEffort}`);
 	}
+	return THINKING_EFFORTS.indexOf(resolved) > THINKING_EFFORTS.indexOf(ceiling) ? ceiling : resolved;
+}
+
+/**
+ * Clamps a concrete thinking selector to a per-session effort ceiling (e.g. a
+ * task spawn's `task.maxEffort`-capped effort hint). `off`/`inherit`/
+ * `undefined` pass through, as do levels already at or below the ceiling.
+ * Levels above it snap to the highest model-supported effort at or below the
+ * ceiling. A model whose floor exceeds the ceiling has nothing valid to snap
+ * to; the requested level is returned unchanged and the caller is responsible
+ * for rejecting or skipping such models (see {@link modelSupportsEffortCeiling}).
+ */
+export function clampThinkingLevelToCeiling(
+	model: Model | undefined,
+	level: Effort | undefined,
+	ceiling: Effort | undefined,
+): Effort | undefined;
+export function clampThinkingLevelToCeiling(
+	model: Model | undefined,
+	level: ThinkingLevel | undefined,
+	ceiling: Effort | undefined,
+): ThinkingLevel | undefined;
+export function clampThinkingLevelToCeiling(
+	model: Model | undefined,
+	level: ThinkingLevel | undefined,
+	ceiling: Effort | undefined,
+): ThinkingLevel | undefined {
+	if (ceiling === undefined || level === undefined || level === ThinkingLevel.Off || level === ThinkingLevel.Inherit) {
+		return level;
+	}
+	const maxIndex = THINKING_EFFORTS.indexOf(ceiling);
+	if (THINKING_EFFORTS.indexOf(level) <= maxIndex) return level;
+	const supported = model ? getSupportedEfforts(model) : THINKING_EFFORTS;
+	return supported.findLast(candidate => THINKING_EFFORTS.indexOf(candidate) <= maxIndex) ?? level;
+}
+
+/**
+ * True when `model` can honor a thinking-effort ceiling: it either has no
+ * controllable effort surface (nothing to cap) or supports at least one effort
+ * at or below the ceiling. Retry-fallback candidate filtering uses this to
+ * skip models whose floor would force the session above the ceiling.
+ */
+export function modelSupportsEffortCeiling(model: Model, ceiling: Effort): boolean {
+	const supported = getSupportedEfforts(model);
+	if (supported.length === 0) return true;
+	const maxIndex = THINKING_EFFORTS.indexOf(ceiling);
+	return supported.some(candidate => THINKING_EFFORTS.indexOf(candidate) <= maxIndex);
 }
 
 /**