@namzu/sdk 37.0.0 → 38.1.0

package/src/provider/fallback.ts

@@ -31,7 +31,10 @@ import type {
 	ThinkingConfig,
 } from '../types/provider/index.js'
 import type { Logger } from '../utils/logger.js'
-import { assertNativeStructuredOutputSupported } from './capabilities.js'
+import {
+	assertHostedWebSearchSupported,
+	assertNativeStructuredOutputSupported,
+} from './capabilities.js'
 
 /**
  * One member of the chain: a constructed provider, and the model to ask it for.
@@ -210,13 +213,14 @@ function shouldFallOver(err: unknown, providerId: string): boolean {
  */
 function isOutputChunk(chunk: StreamChunk): boolean {
 	if (chunk.retry !== undefined || chunk.fallback !== undefined) return false
-	const { content, toolCalls, toolCallEnd, reasoning, citation } = chunk.delta
+	const { content, toolCalls, toolCallEnd, reasoning, citation, hostedTool } = chunk.delta
 	return Boolean(
 		content ||
 			toolCalls?.length ||
 			toolCallEnd ||
 			reasoning !== undefined ||
-			citation !== undefined,
+			citation !== undefined ||
+			hostedTool !== undefined,
 	)
 }
 
@@ -398,6 +402,7 @@ export function withProviderFallback(
 				},
 			}
 			assertNativeStructuredOutputSupported(member.provider, request)
+			assertHostedWebSearchSupported(member.provider, request)
 			let produced = false
 			try {
 				for await (const chunk of member.provider.chatStream(request)) {
@@ -500,6 +505,12 @@ export function withProviderFallback(
 		// the request that may actually traverse the whole chain. The method is
 		// always present on a multi-member wrapper: `undefined` is its honest
 		// answer when any member cannot enumerate its selected model.
+		supportsHostedWebSearchFor: (model: string, mode: 'live' | 'cached') =>
+			members.every(
+				(member) =>
+					member.provider.capabilities?.supportsHostedWebSearch === true &&
+					(member.provider.supportsHostedWebSearchFor?.(member.model ?? model, mode) ?? true),
+			),
 		reasoningEffortLevelsFor: (model: string, thinking?: ThinkingConfig) =>
 			commonReasoningEffortLevels(members, model, thinking),
 		// Present on the chain wrapper for the same reason the menu method is:

package/src/provider/idle-timeout.ts

@@ -212,6 +212,12 @@ export function withStreamIdleTimeout(
 		...(provider.doctorCheck
 			? { doctorCheck: (model?: string) => provider.doctorCheck?.(model) }
 			: {}),
+		...(provider.supportsHostedWebSearchFor
+			? {
+					supportsHostedWebSearchFor: (model: string, mode: 'live' | 'cached') =>
+						provider.supportsHostedWebSearchFor?.(model, mode) ?? false,
+				}
+			: {}),
 		...(provider.reasoningEffortLevelsFor
 			? {
 					reasoningEffortLevelsFor: (

package/src/provider/retry.ts

@@ -270,6 +270,12 @@ export function withProviderRetry(
 		...(provider.doctorCheck
 			? { doctorCheck: (model?: string) => provider.doctorCheck?.(model) }
 			: {}),
+		...(provider.supportsHostedWebSearchFor
+			? {
+					supportsHostedWebSearchFor: (model: string, mode: 'live' | 'cached') =>
+						provider.supportsHostedWebSearchFor?.(model, mode) ?? false,
+				}
+			: {}),
 		...(provider.reasoningEffortLevelsFor
 			? {
 					reasoningEffortLevelsFor: (

package/src/public-runtime.ts

@@ -1339,3 +1339,5 @@ export { WORKING_STATE_MIME } from './connector/mcp/adapter.js'
 export { TokenBudget, validateTokenBudgetSnapshot } from './run/token-budget.js'
 export { DiskTokenBudgetStore, openTokenBudget } from './store/run/token-budget-disk.js'
 export { validateTokenBudgetBinding } from './types/run/token-budget-store.js'
+
+export { snapshotRequestContext, diffRequestContext } from './runtime/query/request-context.js'

package/src/public-tools.ts

@@ -125,3 +125,5 @@ export {
 	createConnectorRouterTool,
 	createConnectorTools,
 } from './connector/tools/index.js'
+
+export { createFileReadTracker } from './tools/file-read-tracker.js'

package/src/public-types.ts

@@ -439,3 +439,9 @@ export type {
 	DiskTokenBudgetStoreConfig,
 	OpenTokenBudgetOptions,
 } from './store/run/token-budget-disk.js'
+
+export type {
+	RequestContextPart,
+	RequestContextSnapshot,
+	RequestContextChange,
+} from './runtime/query/request-context.js'

package/src/run/reporter.ts

@@ -431,6 +431,7 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'hosted_tool':
 			case 'tool_calls_admitted':
 			case 'compaction_shed':
 				// Deliberately silent. The report is what a human reads about a

package/src/run/token-budget.ts

@@ -21,6 +21,8 @@ export interface TokenBudgetRequestSnapshot {
 	runId: RunId
 	/** Cumulative request usage already charged to the owning run. */
 	usage?: TokenUsage
+	/** No reliable final receipt; only explicit reconciliation clears this marker. */
+	unresolved?: boolean
 }
 
 /** Durable authority independent of a message checkpoint's cadence. */
@@ -49,8 +51,10 @@ export interface TokenBudgetSummary {
 	remainingTokens: number | null
 	inFlightRequests: number
 	unsettledChildren: number
-	/** An unresolved provider call or failed ledger write prevents admission. */
+	/** This account is blocked by accounting failure or uncertain finite allowance. */
 	poisoned: boolean
+	/** Unresolved receipts in this subtree, including retained completion records. */
+	unresolvedRequests?: number
 }
 
 interface SharedLedger {
@@ -150,9 +154,6 @@ export function validateTokenBudgetSnapshot(value: unknown): TokenBudgetSnapshot
 		const accountId = id(account.id, 'account id')
 		if (typeof account.settled !== 'boolean') throw new Error('Invalid token budget settled flag')
 		const limit = count(account.limit, 'limit')
-		if (accountId !== rootAccountId && limit === 0) {
-			throw new Error('A child token budget must have a positive limit')
-		}
 		const usage: Record<string, TokenUsage> = {}
 		for (const [runId, rawUsage] of Object.entries(object(account.usage, 'account usage'))) {
 			id(runId, 'usage run id')
@@ -198,6 +199,8 @@ export function validateTokenBudgetSnapshot(value: unknown): TokenBudgetSnapshot
 		const request = object(raw, 'request')
 		const requestId = id(request.id, 'request id')
 		const accountId = id(request.accountId, 'request account id')
+		if (request.unresolved !== undefined && typeof request.unresolved !== 'boolean')
+			throw new Error('Invalid unresolved request marker')
 		if (!isEntityId(request.runId, 'run')) throw new Error('Invalid token budget request run id')
 		if (requestIds.has(requestId)) throw new Error('Duplicate token budget request')
 		requestIds.add(requestId)
@@ -209,6 +212,7 @@ export function validateTokenBudgetSnapshot(value: unknown): TokenBudgetSnapshot
 			accountId,
 			runId: request.runId,
 			...(request.usage === undefined ? {} : { usage: usageValue(request.usage) }),
+			...(request.unresolved === true ? { unresolved: true } : {}),
 		}
 	}
 	const requests = source.requests.map(parseRequest)
@@ -346,9 +350,11 @@ export class TokenBudget {
 				rootAccountId: state.rootAccountId,
 				rootRunId: state.rootRunId,
 				accounts: new Map(state.accounts.map((account) => [account.id, account])),
-				requests: new Map(state.requests.map((request) => [request.id, request])),
+				requests: new Map(
+					state.requests.map((request) => [request.id, { ...request, unresolved: true }]),
+				),
 				finishedRequests: new Map(state.completedRequests.map((request) => [request.id, request])),
-				poisoned: state.poisoned === true || state.requests.length > 0,
+				poisoned: state.poisoned === true,
 				persistence,
 				writes: Promise.resolve(),
 			},
@@ -384,7 +390,7 @@ export class TokenBudget {
 	}
 
 	get remaining(): number {
-		if (this.ledger.poisoned || this.node.settled) return 0
+		if (this.admissionBlocked() || this.node.settled) return 0
 		let cursor = this.node
 		let available = this.free(cursor)
 		while (cursor.parentId !== undefined) {
@@ -430,7 +436,7 @@ export class TokenBudget {
 	reserve(tokens: number): TokenBudget {
 		count(tokens, 'reservation')
 		if (this.hasRequest(this.node)) throw new Error('Token budget has an in-flight request')
-		if (tokens === 0 || tokens > this.remaining)
+		if ((tokens === 0 && this.remaining !== Number.POSITIVE_INFINITY) || tokens > this.remaining)
 			throw new Error('Token budget cannot reserve the requested tokens')
 		count(this.totals(this.node).reserved + tokens, 'reserved allowance')
 		const accountId = randomUUID()
@@ -468,7 +474,8 @@ export class TokenBudget {
 	}
 
 	async beginRequest(): Promise<string> {
-		if (this.ledger.poisoned) throw new Error('Token budget has unresolved spend')
+		if (this.admissionBlocked())
+			throw new Error('Token budget has unresolved spend or an accounting failure')
 		if (this.node.settled) throw new Error('Token budget is settled')
 		if (this.remaining <= 0) throw new Error('Token budget is exhausted')
 		const runId = this.runId
@@ -504,10 +511,11 @@ export class TokenBudget {
 	async failRequest(requestId: string, usage?: TokenUsage): Promise<void> {
 		if (this.hasReceipt(requestId)) return this.flush()
 		const request = this.requireRequest(requestId)
-		this.ledger.poisoned = true
+		request.unresolved = true
 		try {
 			if (usage !== undefined) this.recordRequestUsage(request, usage)
 		} catch (error) {
+			this.ledger.poisoned = true
 			this.persist()
 			await this.flush()
 			throw error
@@ -518,9 +526,9 @@ export class TokenBudget {
 
 	/**
 	 * Explicit host recovery after obtaining the provider's final usage receipt.
-	 * Ordinary completion never reopens an uncertain ledger. Reconciliation can
-	 * do so only after every outstanding request has a measured receipt and all
-	 * accounting writes succeeded; it never resets usage or settled accounts.
+	 * Ordinary completion never clears uncertainty. Reconciliation resolves this
+	 * request after its receipt is persisted; other uncertain requests continue
+	 * to constrain their shared finite allowances. Usage and settlement are retained.
 	 */
 	async reconcileRequest(requestId: string, usage: TokenUsage): Promise<void> {
 		const measured = usageValue(usage)
@@ -536,6 +544,10 @@ export class TokenBudget {
 		} else {
 			await this.finishRequest(requestId, measured)
 		}
+		const receipt = this.ledger.finishedRequests.get(requestId)
+		if (receipt) receipt.unresolved = false
+		this.persist()
+		await this.flush()
 		if (this.ledger.requests.size === 0 && this.ledger.persistenceError === undefined) {
 			this.ledger.poisoned = false
 			this.persist()
@@ -574,7 +586,10 @@ export class TokenBudget {
 			).length,
 			unsettledChildren: this.children(this.node).filter((child) => !this.totals(child).closed)
 				.length,
-			poisoned: this.ledger.poisoned,
+			poisoned: this.admissionBlocked(),
+			unresolvedRequests: this.uncertainRequests().filter((request) =>
+				descendants.has(request.accountId),
+			).length,
 		}
 	}
 
@@ -595,6 +610,28 @@ export class TokenBudget {
 		if (this.ledger.persistenceError !== undefined) throw this.ledger.persistenceError
 	}
 
+	private uncertainRequests(): TokenBudgetRequestSnapshot[] {
+		return [...this.ledger.requests.values(), ...this.ledger.finishedRequests.values()].filter(
+			(request) => request.unresolved === true,
+		)
+	}
+	private admissionBlocked(): boolean {
+		if (this.ledger.poisoned || this.ledger.persistenceError !== undefined) return true
+		const uncertain = this.uncertainRequests()
+		if (uncertain.length === 0) return false
+		// An account cannot resume its own uncertain request, even without a cap.
+		if (uncertain.some((request) => request.accountId === this.accountId)) return true
+		let cursor = this.node
+		for (;;) {
+			if (cursor.limit > 0) {
+				const descendants = this.descendants(cursor)
+				if (uncertain.some((request) => descendants.has(request.accountId))) return true
+			}
+			if (cursor.parentId === undefined) return false
+			cursor = this.requireAccount(cursor.parentId)
+		}
+	}
+
 	private get node(): TokenBudgetAccountSnapshot {
 		return this.requireAccount(this.accountId)
 	}

package/src/runtime/query/executor.ts

@@ -11,8 +11,8 @@ import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
 import { renderToolSchema } from '../../registry/tool/schema.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
-import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import { SKILL_TOOL_NAME } from '../../tools/builtins/skill.js'
+import { createFileReadTracker } from '../../tools/file-read-tracker.js'
 import type { RunId, ToolUseId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import {
@@ -290,6 +290,7 @@ function parseArguments(raw: string): unknown {
 }
 
 export interface ToolExecutorConfig {
+	fileReadTracker?: FileReadTracker
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
@@ -501,20 +502,7 @@ export class ToolExecutor {
 	private readonly preparedBatches = new WeakSet<PreparedToolBatch>()
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
-	private readonly readPaths: Set<string> = new Set()
-	private readonly readFingerprints: Map<string, string> = new Map()
-	private readonly fileReadTracker: FileReadTracker = {
-		recordRead: (key: string, content?: string) => {
-			this.readPaths.add(key)
-			// Only when the reader had the body. A tool that records a read
-			// without one leaves the previous fingerprint alone rather than
-			// clearing it, so a later write is still checked against the last
-			// body anyone actually saw.
-			if (content !== undefined) this.readFingerprints.set(key, fingerprintContent(content))
-		},
-		hasRead: (key: string) => this.readPaths.has(key),
-		fingerprint: (key: string) => this.readFingerprints.get(key),
-	}
+	private readonly fileReadTracker: FileReadTracker
 
 	constructor(
 		config: ToolExecutorConfig,
@@ -532,6 +520,7 @@ export class ToolExecutor {
 				config.readToolCallBudgetEvents,
 			)
 		}
+		this.fileReadTracker = config.fileReadTracker ?? createFileReadTracker()
 		this.config = config
 		this.activityStore = activityStore
 		this.emitEvent = emitEvent
@@ -1211,6 +1200,7 @@ export class ToolExecutor {
 			toolUseId: nestedId,
 			toolName: name,
 			result: budgeted.output,
+			...(!budgeted.truncated ? this.resultPresentation(name, preparedInput, result) : {}),
 			isError: !result.success,
 			durationMs: Date.now() - startedAt,
 			outputLength: budgeted.originalLength,
@@ -1230,6 +1220,21 @@ export class ToolExecutor {
 		return visibleResult
 	}
 
+	private resultPresentation(name: string, input: unknown, result: ToolResult) {
+		if (!result.success) return {}
+		try {
+			const view = this.config.tools.get(name)?.presentResult?.(input, result)
+			if (view?.kind !== 'diff') return {}
+			const serialized = JSON.stringify(view)
+			if (serialized.length > (this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS))
+				return {}
+			return { presentation: view }
+		} catch {
+			// A presentation hook must not fail an already completed mutation.
+			return {}
+		}
+	}
+
 	private buildToolContext(
 		recordObservation: (observation: ToolResultObservation) => void = () => {},
 	): ToolContext {
@@ -1721,6 +1726,9 @@ export class ToolExecutor {
 			toolUseId: toolCall.id,
 			toolName,
 			result: output,
+			...(!postOverride && !budgeted.truncated && rawOutput === output
+				? this.resultPresentation(toolName, input, result)
+				: {}),
 			isError: effectiveIsError,
 			durationMs,
 			// Pre-truncation size, so a host can show "returned 2.1 MB" even

package/src/runtime/query/index.ts

@@ -157,6 +157,8 @@ import { createToolPause } from './tool-pause.js'
 import { ToolingBootstrap } from './tooling.js'
 
 export interface QueryParams {
+	/** Share observations across turns of one conversation and filesystem; otherwise run-local. */
+	fileReadTracker?: import('../../types/tool/index.js').FileReadTracker
 	/** One account shared with the task scheduler and descendant runs. */
 	budget?: TokenBudget
 	/** Canonical tree ledger; defaults to disk beside the root run. */
@@ -1731,6 +1733,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// registry would answer about whatever the last run configured.
 			...(params.skillRegistry ? { skills: params.skillRegistry } : {}),
 			...(params.web ? { web: params.web } : {}),
+			...(params.fileReadTracker ? { fileReadTracker: params.fileReadTracker } : {}),
 			...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
 			...(params.toolRetryBackoff !== undefined
 				? { toolRetryBackoff: params.toolRetryBackoff }

package/src/runtime/query/iteration/index.ts

@@ -54,7 +54,13 @@ import { toErrorMessage } from '../../../utils/error.js'
 import { stableDigest } from '../../../utils/hash.js'
 import { generateMessageId } from '../../../utils/id.js'
 import type { ToolCallOutcome } from '../executor.js'
+import { projectObservationContext } from '../observation-context.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
+import {
+	type RequestContextSnapshot,
+	diffRequestContext,
+	snapshotRequestContext,
+} from '../request-context.js'
 import {
 	DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 	type RequestImageIdentity,
@@ -164,6 +170,14 @@ export class IterationOrchestrator {
 	 * one process must not suppress each other's first envelope.
 	 */
 	private lastEnvelopeKey: string | undefined
+	private previousRequestContext: RequestContextSnapshot | undefined
+
+	private projectObservations(messages: Message[]): Message[] {
+		const config = this.ctx.compactionConfig
+		return config && config.strategy !== 'disabled' && config.deduplicateObservations !== false
+			? projectObservationContext(messages, this.ctx.tools, config.preserveToolResultsFrom)
+			: messages
+	}
 	/** Rich tool blocks already reported; durable history is scanned every turn. */
 	private readonly warnedRichToolResults = new Set<string>()
 	/**
@@ -614,7 +628,7 @@ export class IterationOrchestrator {
 						? [...baseMessages, createSystemMessage(stepPreamble)]
 						: [...baseMessages]
 					const messages = projectRequestRichContent(
-						requestHistory,
+						this.projectObservations(requestHistory),
 						this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
 					await this.reportUnsupportedToolResults(messages)
@@ -664,6 +678,16 @@ export class IterationOrchestrator {
 					}
 
 					if (this.ctx.pluginManager) {
+						const snapshot = snapshotRequestContext(messages)
+						const context = Object.freeze({
+							snapshot,
+							...(this.previousRequestContext
+								? {
+										change: diffRequestContext(this.previousRequestContext, snapshot),
+									}
+								: {}),
+						})
+						this.previousRequestContext = snapshot
 						const hookResults = await this.ctx.pluginManager.executeHooks(
 							'pre_llm_call',
 							{
@@ -673,6 +697,7 @@ export class IterationOrchestrator {
 								// Built inside the guard: a run with no plugins installed
 								// pays nothing for a projection nobody reads.
 								request: Object.freeze({
+									context,
 									model: stepModel,
 									// Copied per turn, not handed over live: these are the
 									// run's own message objects, and a hook writing into
@@ -752,6 +777,7 @@ export class IterationOrchestrator {
 							cacheControl: { type: 'auto' },
 							...(runConfig.thinking ? { thinking: runConfig.thinking } : {}),
 							...(runConfig.effort ? { effort: runConfig.effort } : {}),
+							...(!forceFinalize && runConfig.webSearch ? { webSearch: runConfig.webSearch } : {}),
 							// Thread the run abort into the model call so a Stop tears the
 							// in-flight turn down (provider passes it to fetch; the consumer
 							// also races it). Inert when never aborted.
@@ -2424,7 +2450,7 @@ export class IterationOrchestrator {
 				),
 			]
 			const finalMessages = projectRequestRichContent(
-				finalHistory,
+				this.projectObservations(finalHistory),
 				this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 			)
 			await this.reportUnsupportedToolResults(finalMessages)

package/src/runtime/query/iteration/stream-turn.ts

@@ -1,5 +1,8 @@
 import { type Span, SpanStatusCode } from '@opentelemetry/api'
-import { assertNativeStructuredOutputSupported } from '../../../provider/capabilities.js'
+import {
+	assertHostedWebSearchSupported,
+	assertNativeStructuredOutputSupported,
+} from '../../../provider/capabilities.js'
 import { isProviderRequestError } from '../../../provider/errors.js'
 import { GENAI, NAMZU, chatSpanName, parentContext } from '../../../telemetry/attributes.js'
 import {
@@ -155,6 +158,7 @@ export async function* streamProviderTurn(
 	},
 ): AsyncGenerator<RunEvent, StreamingTurnResult> {
 	assertNativeStructuredOutputSupported(provider, params)
+	assertHostedWebSearchSupported(provider, params)
 	// The `chat {model}` span the GenAI conventions require. There was none:
 	// `chatSpanName` existed with zero call sites, so a trace carried no LLM
 	// latency at all and the token counts landed on the iteration span
@@ -340,6 +344,15 @@ export async function* streamProviderTurn(
 				recordTimeToFirstToken(params.model, Date.now() - callStartedAt)
 			}
 
+			if (chunk.delta.hostedTool) {
+				await emitEvent({
+					type: 'hosted_tool',
+					runId,
+					iteration,
+					tool: chunk.delta.hostedTool,
+				})
+				yield* drainPending()
+			}
 			if (chunk.delta.citation) citations.push(chunk.delta.citation)
 
 			const reasoning = chunk.delta.reasoning

package/src/runtime/query/observation-context.ts

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto'
+import { findRetainedIndices } from '../../compaction/retention.js'
+import { estimateMessageTokens } from '../../compaction/token-estimate.js'
+import { isClearedToolResult } from '../../compaction/tool-result-editing.js'
+import type { Message, ToolMessage } from '../../types/message/index.js'
+import type { ToolRegistryContract } from '../../types/tool/index.js'
+
+/**
+ * Request-only exact observation masking. Every reference targets a full result
+ * in THIS projection. Recompute from canonical history, never from yesterday's
+ * mask, so removing a former representative cannot leave a dangling reference.
+ * No tool executions are skipped, and equal output is not a freshness claim.
+ */
+export function projectObservationContext(
+	messages: Message[],
+	tools: Pick<ToolRegistryContract, 'get'>,
+	preserveToolResultsFrom: readonly string[] = [],
+): Message[] {
+	const calls = new Map<string, { name: string; arguments: string } | null>()
+	for (const message of messages) {
+		if (message.role !== 'assistant') continue
+		for (const call of message.toolCalls ?? []) {
+			// Ambiguous IDs cannot prove which observation belongs to which call.
+			if (calls.has(call.id)) calls.set(call.id, null)
+			else calls.set(call.id, call.metadata?.inputTruncated ? null : call.function)
+		}
+	}
+	const resultCounts = new Map<string, number>()
+	for (const message of messages) {
+		if (message.role === 'tool') {
+			resultCounts.set(message.toolCallId, (resultCounts.get(message.toolCallId) ?? 0) + 1)
+		}
+	}
+	const protectedIndices = findRetainedIndices(messages)
+	const representatives = new Map<string, ToolMessage>()
+	let projected: Message[] | undefined
+	for (let index = 0; index < messages.length; index++) {
+		const message = messages[index]
+		if (
+			!message ||
+			message.role !== 'tool' ||
+			message.isError ||
+			typeof message.content !== 'string' ||
+			message.content.length < 1024 ||
+			isClearedToolResult(message.content) ||
+			resultCounts.get(message.toolCallId) !== 1
+		)
+			continue
+		const call = calls.get(message.toolCallId)
+		if (!call || preserveToolResultsFrom.includes(call.name)) continue
+		const definition = tools.get(call.name)
+		if (!definition) continue
+		try {
+			const input = definition.inputSchema.safeParse(JSON.parse(call.arguments))
+			if (
+				!input.success ||
+				definition.isReadOnly?.(input.data) !== true ||
+				definition.isDestructive?.(input.data) === true
+			)
+				continue
+		} catch {
+			// Classification is advisory; invalid input or a broken custom predicate
+			// must leave evidence intact, not abort the request.
+			continue
+		}
+		// Exact arguments intentionally: equivalent JSON with different formatting
+		// is a missed optimization, not permission to merge different file ranges.
+		const key = createHash('sha256')
+			.update(JSON.stringify([call.name, call.arguments, message.content]))
+			.digest('hex')
+		const representative = representatives.get(key)
+		if (!representative) {
+			representatives.set(key, message)
+			continue
+		}
+		if (protectedIndices.has(index)) continue
+		const replacement: ToolMessage = {
+			...message,
+			content: `[Duplicate observation: this call returned exactly the same text as tool result ${JSON.stringify(representative.toolCallId)}, whose full content remains in this request. Both calls occurred. This is historical evidence, not a claim that external state is still unchanged.]`,
+		}
+		if (estimateMessageTokens(replacement) >= estimateMessageTokens(message)) continue
+		projected ??= [...messages]
+		projected[index] = replacement
+	}
+	return projected ?? messages
+}