@oh-my-pi/pi-agent-core 18.7.0 → 18.8.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [18.8.1] - 2026-10-07
+
+### Added
+
+- Added the public `validateAgentToolArguments()` API for consistent, lenient-aware validation of agent tool arguments across agent and coding-agent workflows.
+
+## [18.8.0] - 2026-10-07
+
+### Changed
+
+- Improved performance when pruning tool output and capturing telemetry messages during long-running sessions.
+
 ## [18.7.0] - 2026-10-06
 
 ### Fixed

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

@@ -127,10 +127,11 @@ export declare const MIN_PRUNE_TOKENS = 50;
  * candidate is pruned now only when the suffix after it is small (tail case —
  * the read→edit→read loop) or when the context has been idle long enough that
  * the provider cache is cold anyway (then all still-sent candidates flush).
- * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
+ * Never mutates entries before `keepBoundaryId` (summarized away — not sent),
+ * and never walks them unless a sent result's call lives there.
  */
-export declare function pruneSupersededToolResults(entries: SessionEntry[], tokenizer: Tokenizer, config: SupersedePruneConfig): PruneResult;
-export declare function pruneToolOutputs(entries: SessionEntry[], tokenizer: Tokenizer, config?: PruneConfig): PruneResult;
+export declare function pruneSupersededToolResults(entries: readonly SessionEntry[], tokenizer: Tokenizer, config: SupersedePruneConfig): PruneResult;
+export declare function pruneToolOutputs(entries: readonly SessionEntry[], tokenizer: Tokenizer, config?: PruneConfig): PruneResult;
 /**
  * Supersede key for the `read` tool: the file path with the trailing line/raw
  * selector stripped (the read tool's own splitter grammar via

package/dist/types/compaction/tool-protection.d.ts

@@ -6,7 +6,8 @@ export interface ProtectedToolContext {
     readonly toolCall: AgentToolCall | undefined;
 }
 export type ProtectedToolMatcher = string | ((context: ProtectedToolContext) => boolean);
-export declare function collectToolCallsById(entries: readonly SessionEntry[]): Map<string, AgentToolCall>;
+/** Map tool-call ids to their calls across `entries[start, end)` (later calls win). */
+export declare function collectToolCallsById(entries: readonly SessionEntry[], start?: number, end?: number): Map<string, AgentToolCall>;
 /** Return the tool-result message carried by a session entry, if any. */
 export declare function getToolResultMessage(entry: SessionEntry): ToolResultMessage | undefined;
 /**

package/dist/types/index.d.ts

@@ -13,5 +13,6 @@ export * from "./telemetry.js";
 export * from "./thinking.js";
 export * from "./tool-context.js";
 export * from "./tokenizer.js";
+export * from "./tool-arguments.js";
 export * from "./types.js";
 export * from "./utils/yield.js";

package/dist/types/speculative-execution.d.ts

@@ -1,4 +1,4 @@
-import { type AssistantMessage } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
 import type { AgentContext, AgentLoopConfig, AgentTool, AgentToolCall, AgentToolResult, SpeculativeAuthorization, SpeculativeChildDefinition, SpeculativeChildHandle, SpeculativeLaunchContext, SpeculativeToolExecutionConfig, ToolSpeculationEffect, ToolSpeculationStreamSession } from "./types.js";
 export type SpeculativeRawOutcome = {
     result: AgentToolResult<unknown>;

package/dist/types/tool-arguments.d.ts

@@ -0,0 +1,19 @@
+import { type ToolCall } from "@oh-my-pi/pi-ai";
+import type { AgentTool } from "./types.js";
+/**
+ * Where a call's `__parseError`/`__rawJson` keys came from.
+ * - `"parsed"`: a provider stream parsed the arguments, so `__parseError` is a
+ *   genuine parse-failure sentinel and is never handed to a tool.
+ * - `"payload"`: the arguments are a payload the model wrote (eval tool bridge,
+ *   `xd://` device content), so those keys are forged and only stripped.
+ */
+export type ToolArgumentSource = "parsed" | "payload";
+/**
+ * Validate a call's arguments against `tool`'s schema, honoring
+ * {@link AgentTool.lenientArgValidation}: on a schema mismatch a lenient tool
+ * receives its raw arguments minus the internal `__parseError`/`__rawJson`
+ * sentinels. Malformed JSON from a provider stream is never lenient.
+ *
+ * @throws the validation error when the tool is strict or the arguments failed to parse.
+ */
+export declare function validateAgentToolArguments(tool: AgentTool, toolCall: ToolCall, source?: ToolArgumentSource): ToolCall["arguments"];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.7.0",
+	"version": "18.8.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -38,16 +38,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.7.0",
-		"@oh-my-pi/pi-catalog": "18.7.0",
-		"@oh-my-pi/pi-natives": "18.7.0",
-		"@oh-my-pi/pi-utils": "18.7.0",
-		"@oh-my-pi/pi-wire": "18.7.0",
-		"@oh-my-pi/snapcompact": "18.7.0",
+		"@oh-my-pi/pi-ai": "18.8.1",
+		"@oh-my-pi/pi-catalog": "18.8.1",
+		"@oh-my-pi/pi-natives": "18.8.1",
+		"@oh-my-pi/pi-utils": "18.8.1",
+		"@oh-my-pi/pi-wire": "18.8.1",
+		"@oh-my-pi/snapcompact": "18.8.1",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.7.0",
+		"@oh-my-pi/omptype": "18.8.1",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent-loop.ts

@@ -23,7 +23,6 @@ import {
 	type TSchema,
 	toolWireSchema,
 	type UserMessage,
-	validateToolArguments,
 } from "@oh-my-pi/pi-ai";
 import {
 	type Dialect,
@@ -76,6 +75,7 @@ import {
 	startExecuteToolSpan,
 	startInvokeAgentSpan,
 } from "./telemetry";
+import { validateAgentToolArguments } from "./tool-arguments";
 import { createAdditionalContextMessage, isNonBlankContext, joinAdditionalContext } from "./tool-context";
 import dsmlToolCallLeakPrompt from "./prompts/dsml-tool-call-leak.md" with { type: "text" };
 import type {
@@ -3062,15 +3062,9 @@ async function prepareToolCallDispatch(
 				if (!tool) {
 					throw new Error(formatToolNotFoundMessage(toolCall.name, context.tools, suggestFallbackToolNames?.()));
 				}
-				return validateToolArguments(tool, { ...toolCall, arguments: args });
+				return validateAgentToolArguments(tool, { ...toolCall, arguments: args });
 			} catch (validationError) {
-				// Lenience covers schema mismatches; a parse failure has no args to hand over.
 				const parseFailed = "__parseError" in args;
-				if (tool?.lenientArgValidation && !parseFailed) {
-					const fallback = { ...args };
-					delete fallback.__rawJson;
-					return fallback;
-				}
 				entry.args = parseFailed ? { __parseError: args.__parseError } : args;
 				entry.validationErrorMessage =
 					validationError instanceof Error ? validationError.message : String(validationError);

package/src/compaction/pruning.ts

@@ -179,24 +179,6 @@ function estimatePrunedSavings(tokens: number, notice: string): number {
 	return Math.max(0, tokens - noticeTokens);
 }
 
-/**
- * For each entry index, the estimated token total of all *message* entries
- * strictly after it — how much prompt-cache content the provider must re-write
- * (cacheWrite premium) if that entry is mutated in place. Used to keep prune
- * mutations inside the cheap-to-recache tail.
- */
-function computeMessageSuffixTokens(entries: readonly SessionEntry[], tokenizer: Tokenizer): number[] {
-	// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
-	const suffix = new Array<number>(entries.length);
-	let accumulated = 0;
-	for (let i = entries.length - 1; i >= 0; i--) {
-		suffix[i] = accumulated;
-		const entry = entries[i];
-		if (entry.type === "message") accumulated += tokenizer.countMessage(entry.message as AgentMessage);
-	}
-	return suffix;
-}
-
 /**
  * Resolve the array index of the compaction boundary (`keepBoundaryId`). Entries
  * before this index are summarized away by the latest compaction and never sent,
@@ -205,8 +187,36 @@ function computeMessageSuffixTokens(entries: readonly SessionEntry[], tokenizer:
  */
 function resolveBoundaryIndex(entries: readonly SessionEntry[], keepBoundaryId: string | undefined): number {
 	if (keepBoundaryId === undefined) return 0;
-	const index = entries.findIndex(entry => entry.id === keepBoundaryId);
-	return index < 0 ? 0 : index;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		if (entries[i].id === keepBoundaryId) return i;
+	}
+	return 0;
+}
+
+/**
+ * Tool-call lookup for results in the sent region `entries[start, end)`.
+ * Calls there are indexed eagerly; the summarized-away prefix is indexed only
+ * on the first miss, so lookups match a whole-branch scan while the common
+ * case never walks history the boundary already excludes.
+ */
+class SentToolCalls {
+	readonly #entries: readonly SessionEntry[];
+	readonly #start: number;
+	readonly #sent: Map<string, AgentToolCall>;
+	#prefix: Map<string, AgentToolCall> | undefined;
+
+	constructor(entries: readonly SessionEntry[], start: number) {
+		this.#entries = entries;
+		this.#start = start;
+		this.#sent = collectToolCallsById(entries, start);
+	}
+
+	get(id: string): AgentToolCall | undefined {
+		const call = this.#sent.get(id);
+		if (call !== undefined || this.#start === 0) return call;
+		this.#prefix ??= collectToolCallsById(this.#entries, 0, this.#start);
+		return this.#prefix.get(id);
+	}
 }
 
 interface SupersedeCandidate {
@@ -240,19 +250,22 @@ interface NewerResults {
  */
 function collectSupersededResults(
 	entries: readonly SessionEntry[],
+	start: number,
 	tokenizer: Tokenizer,
-	toolCallsById: ReadonlyMap<string, AgentToolCall>,
+	toolCalls: SentToolCalls,
 	supersedeKey: SupersedeKeyFn,
 	supersedeComplete: SupersedeCompleteFn | undefined,
 	protectedTools: readonly ProtectedToolMatcher[],
 ): SupersedeCandidate[] {
+	// Walk newest → oldest: supersession only depends on NEWER results, so
+	// stopping at `start` yields exactly the full scan's candidates at/after it.
 	const candidates: SupersedeCandidate[] = [];
 	const newerByKey = new Map<string, NewerResults>();
-	for (let i = entries.length - 1; i >= 0; i--) {
+	for (let i = entries.length - 1; i >= start; i--) {
 		const entry = entries[i];
 		const message = getToolResultMessage(entry);
 		if (!message || message.prunedAt !== undefined) continue;
-		const toolCall = toolCallsById.get(message.toolCallId);
+		const toolCall = toolCalls.get(message.toolCallId);
 		if (!toolCall) continue;
 		if (isProtectedToolResult(message, toolCall, protectedTools)) continue;
 		const key = supersedeKey(toolCall.name, toolCall.arguments as Record<string, unknown>);
@@ -289,18 +302,19 @@ function collectSupersededResults(
  */
 function collectUselessResults(
 	entries: readonly SessionEntry[],
+	start: number,
 	tokenizer: Tokenizer,
-	toolCallsById: ReadonlyMap<string, AgentToolCall>,
+	toolCalls: SentToolCalls,
 	protectedTools: readonly ProtectedToolMatcher[],
 	exclude: ReadonlySet<ToolResultMessage>,
 ): SupersedeCandidate[] {
 	const candidates: SupersedeCandidate[] = [];
-	for (let i = 0; i < entries.length; i++) {
+	for (let i = start; i < entries.length; i++) {
 		const entry = entries[i];
 		const message = getToolResultMessage(entry);
 		if (message?.useless !== true || message.prunedAt !== undefined || message.isError === true) continue;
 		if (exclude.has(message)) continue;
-		if (isProtectedToolResult(message, toolCallsById.get(message.toolCallId), protectedTools)) continue;
+		if (isProtectedToolResult(message, toolCalls.get(message.toolCallId), protectedTools)) continue;
 		const tokens = tokenizer.countMessage(message as AgentMessage);
 		if (estimatePrunedSavings(tokens, USELESS_NOTICE) <= 0) continue;
 		candidates.push({ entry: entry as SessionMessageEntry, message, index: i, tokens, notice: USELESS_NOTICE });
@@ -315,19 +329,22 @@ function collectUselessResults(
  * candidate is pruned now only when the suffix after it is small (tail case —
  * the read→edit→read loop) or when the context has been idle long enough that
  * the provider cache is cold anyway (then all still-sent candidates flush).
- * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
+ * Never mutates entries before `keepBoundaryId` (summarized away — not sent),
+ * and never walks them unless a sent result's call lives there.
  */
 export function pruneSupersededToolResults(
-	entries: SessionEntry[],
+	entries: readonly SessionEntry[],
 	tokenizer: Tokenizer,
 	config: SupersedePruneConfig,
 ): PruneResult {
-	const toolCallsById = collectToolCallsById(entries);
+	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
+	const toolCalls = new SentToolCalls(entries, boundaryIndex);
 	const candidates = config.supersedeKey
 		? collectSupersededResults(
 				entries,
+				boundaryIndex,
 				tokenizer,
-				toolCallsById,
+				toolCalls,
 				config.supersedeKey,
 				config.supersedeComplete,
 				config.protectedTools,
@@ -335,7 +352,16 @@ export function pruneSupersededToolResults(
 		: [];
 	if (config.pruneUseless) {
 		const exclude = new Set(candidates.map(candidate => candidate.message));
-		candidates.push(...collectUselessResults(entries, tokenizer, toolCallsById, config.protectedTools, exclude));
+		for (const candidate of collectUselessResults(
+			entries,
+			boundaryIndex,
+			tokenizer,
+			toolCalls,
+			config.protectedTools,
+			exclude,
+		)) {
+			candidates.push(candidate);
+		}
 		candidates.sort((a, b) => a.index - b.index);
 	}
 	if (candidates.length === 0) return NOTHING_PRUNED;
@@ -352,38 +378,40 @@ export function pruneSupersededToolResults(
 	const idle =
 		lastMessageTimestamp !== undefined && now - lastMessageTimestamp >= (config.idleFlushMs ?? DEFAULT_IDLE_FLUSH_MS);
 
-	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
-
 	let toPrune: SupersedeCandidate[];
 	if (idle) {
 		// Provider cache is cold (idle exceeds the retention TTL), so re-writing
-		// the sent region costs nothing. Entries before the compaction boundary
-		// are summarized away and never sent — skip them to avoid pointless churn.
-		toPrune = candidates.filter(candidate => candidate.index >= boundaryIndex);
+		// the sent region costs nothing. Candidates already start at the
+		// compaction boundary (summarized-away entries are never sent).
+		toPrune = candidates;
 	} else {
+		// Mutating a candidate re-writes its suffix (tokens of every message
+		// strictly after it) in the warm cache, so prune only when that suffix is
+		// small. The suffix only grows walking back, so stop at the first index
+		// past the limit instead of measuring the whole branch.
 		const suffixTokenLimit = config.suffixTokenLimit ?? DEFAULT_SUFFIX_TOKEN_LIMIT;
-		// suffixTokens[i] = estimated tokens of all messages strictly after entry i.
-		// Mutating a candidate re-writes its suffix in the warm cache, so prune only
-		// when that suffix is small (cheap-to-recache tail) and the candidate sits
-		// at/after the compaction boundary.
-		const suffixTokens = computeMessageSuffixTokens(entries, tokenizer);
-		toPrune = candidates.filter(
-			candidate => candidate.index >= boundaryIndex && suffixTokens[candidate.index] <= suffixTokenLimit,
-		);
+		toPrune = [];
+		let suffixTokens = 0;
+		let next = candidates.length - 1;
+		for (let i = entries.length - 1; next >= 0 && suffixTokens <= suffixTokenLimit; i--) {
+			while (next >= 0 && candidates[next].index === i) toPrune.push(candidates[next--]);
+			const entry = entries[i];
+			if (entry.type === "message") suffixTokens += tokenizer.countMessage(entry.message as AgentMessage);
+		}
+		toPrune.reverse();
 	}
 	if (toPrune.length === 0) return NOTHING_PRUNED;
 
-	const prunedAt = Date.now();
 	let tokensSaved = 0;
-	const steps = toPrune.map(candidate => {
-		tokensSaved += estimatePrunedSavings(candidate.tokens, candidate.notice);
-		return blankToolResult(candidate.message, candidate.notice, prunedAt);
-	});
+	for (const candidate of toPrune) tokensSaved += estimatePrunedSavings(candidate.tokens, candidate.notice);
+
+	const prunedAt = Date.now();
+	const steps = toPrune.map(candidate => blankToolResult(candidate.message, candidate.notice, prunedAt));
 	return { prunedCount: toPrune.length, tokensSaved, undo: undoAll(steps) };
 }
 
 export function pruneToolOutputs(
-	entries: SessionEntry[],
+	entries: readonly SessionEntry[],
 	tokenizer: Tokenizer,
 	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
 ): PruneResult {
@@ -391,13 +419,17 @@ export function pruneToolOutputs(
 	let tokensSaved = 0;
 
 	const candidates: Array<{ entry: SessionMessageEntry; tokens: number; superseded: boolean; useless: boolean }> = [];
-	const toolCallsById = collectToolCallsById(entries);
+	// Entries before the compaction boundary are summarized away (never sent)
+	// and are never prune candidates, so no pass below walks them.
+	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
+	const toolCalls = new SentToolCalls(entries, boundaryIndex);
 	const supersededMessages = config.supersedeKey
 		? new Set(
 				collectSupersededResults(
 					entries,
+					boundaryIndex,
 					tokenizer,
-					toolCallsById,
+					toolCalls,
 					config.supersedeKey,
 					config.supersedeComplete,
 					config.protectedTools,
@@ -409,42 +441,41 @@ export function pruneToolOutputs(
 			? new Set(
 					collectUselessResults(
 						entries,
+						boundaryIndex,
 						tokenizer,
-						toolCallsById,
+						toolCalls,
 						config.protectedTools,
 						supersededMessages ?? new Set(),
 					).map(candidate => candidate.message),
 				)
 			: undefined;
 
-	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
 	const cacheWarmSuffixTokens = config.cacheWarmSuffixTokens;
-	// All-message suffix per index, only when the cache guard is armed.
-	const messageSuffix =
-		cacheWarmSuffixTokens === undefined ? undefined : computeMessageSuffixTokens(entries, tokenizer);
+	// Tokens of every message strictly after entry `i` (cache guard only).
+	let messageSuffix = 0;
 
-	for (let i = entries.length - 1; i >= 0; i--) {
+	for (let i = entries.length - 1; i >= boundaryIndex; i--) {
 		const entry = entries[i];
+		const suffixAfter = messageSuffix;
 		const message = getToolResultMessage(entry);
-		if (!message) continue;
-
-		const tokens = tokenizer.countMessage(message as AgentMessage);
-		const isProtected = isProtectedToolResult(message, toolCallsById.get(message.toolCallId), config.protectedTools);
-
-		if (message.prunedAt !== undefined) {
-			accumulatedTokens += tokens;
+		if (!message) {
+			if (cacheWarmSuffixTokens !== undefined && entry.type === "message") {
+				messageSuffix += tokenizer.countMessage(entry.message as AgentMessage);
+			}
 			continue;
 		}
 
+		const tokens = tokenizer.countMessage(message as AgentMessage);
+		messageSuffix += tokens;
+
 		// Prompt-cache guard: a result whose all-message suffix exceeds the
 		// warm-cache window sits in the already-sent cached prefix — mutating it
-		// re-writes the whole suffix (cacheWrite premium). Entries before the
-		// compaction boundary are summarized away (never sent). Both are skipped
-		// before any prune decision, so superseded/useless cannot reach a deep,
-		// still-cached copy; compaction/shake reclaim those when they rebuild.
-		const inWarmPrefix =
-			messageSuffix !== undefined && cacheWarmSuffixTokens !== undefined && messageSuffix[i] > cacheWarmSuffixTokens;
-		if (inWarmPrefix || i < boundaryIndex) {
+		// re-writes the whole suffix (cacheWrite premium). The suffix only grows
+		// walking back, so every older result is in the warm prefix too. Deeper,
+		// still-cached superseded/useless copies are left for compaction/shake.
+		if (cacheWarmSuffixTokens !== undefined && suffixAfter > cacheWarmSuffixTokens) break;
+
+		if (message.prunedAt !== undefined) {
 			accumulatedTokens += tokens;
 			continue;
 		}
@@ -456,7 +487,13 @@ export function pruneToolOutputs(
 		const superseded = supersededMessages?.has(message) ?? false;
 		const useless = uselessMessages?.has(message) ?? false;
 		const tooSmall = tokens < MIN_PRUNE_TOKENS;
-		if (!superseded && !useless && (accumulatedTokens < config.protectTokens || isProtected || tooSmall)) {
+		if (
+			!superseded &&
+			!useless &&
+			(accumulatedTokens < config.protectTokens ||
+				tooSmall ||
+				isProtectedToolResult(message, toolCalls.get(message.toolCallId), config.protectedTools))
+		) {
 			accumulatedTokens += tokens;
 			continue;
 		}

package/src/compaction/tool-protection.ts

@@ -11,9 +11,15 @@ export type ProtectedToolMatcher = string | ((context: ProtectedToolContext) =>
 
 const SKILL_INTERNAL_URL_PREFIX = "skill://";
 
-export function collectToolCallsById(entries: readonly SessionEntry[]): Map<string, AgentToolCall> {
+/** Map tool-call ids to their calls across `entries[start, end)` (later calls win). */
+export function collectToolCallsById(
+	entries: readonly SessionEntry[],
+	start = 0,
+	end = entries.length,
+): Map<string, AgentToolCall> {
 	const toolCalls = new Map<string, AgentToolCall>();
-	for (const entry of entries) {
+	for (let i = start; i < end; i++) {
+		const entry = entries[i];
 		if (entry.type !== "message") continue;
 		const message = entry.message;
 		if (message.role !== "assistant") continue;

package/src/index.ts

@@ -28,6 +28,8 @@ export * from "./thinking";
 export * from "./tool-context";
 // Tokenizer choice
 export * from "./tokenizer";
+// Lenient-aware tool argument validation
+export * from "./tool-arguments";
 // Types
 export * from "./types";
 // Yield utilities for Bun event-loop busy-wait prevention

package/src/speculative-execution.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
-import { type AssistantMessage, validateToolArguments } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import { validateAgentToolArguments } from "./tool-arguments";
 import type {
 	AgentContext,
 	AgentLoopConfig,
@@ -712,15 +713,10 @@ export class SpeculativeOperationCoordinator {
 		}
 		let validatedArgs: Record<string, unknown>;
 		try {
-			validatedArgs = validateToolArguments(tool, toolCall);
+			validatedArgs = validateAgentToolArguments(tool, toolCall);
 		} catch {
-			// Lenience covers schema mismatches; a parse failure has no args to hand over.
-			if (!tool.lenientArgValidation || "__parseError" in toolCall.arguments) {
-				this.ineligible(toolCall, "tool arguments are not valid", source, parentToolCallId);
-				return undefined;
-			}
-			validatedArgs = { ...toolCall.arguments };
-			delete validatedArgs.__rawJson;
+			this.ineligible(toolCall, "tool arguments are not valid", source, parentToolCallId);
+			return undefined;
 		}
 		let executionArgs: Record<string, unknown>;
 		try {

package/src/telemetry.ts

@@ -836,15 +836,27 @@ function serializeRequestMessagesForTelemetry(
 ): string | undefined {
 	const serializer = telemetry.config.contentSerializer?.requestMessages;
 	if (serializer) return callContentSerializer(telemetry, "requestMessages", () => serializer(request));
+	const systemParts = normalizeSystemPromptParts(request.systemPrompt);
+	const requestMessages = request.messages ?? [];
+	const total = systemParts.length + requestMessages.length;
+	if (total === 0) return undefined;
+	// Summarize only what survives the message cap; the rest is counted.
 	const messages: TelemetryMessageSummary[] = [];
-	for (const text of normalizeSystemPromptParts(request.systemPrompt))
+	for (const text of systemParts) {
+		if (messages.length === MAX_TELEMETRY_MESSAGE_COUNT) break;
 		messages.push({ role: "system", content: summarizeTelemetryValue(text) });
-	if (request.messages) {
-		for (const message of request.messages) {
-			messages.push({ role: message.role, content: summarizeTelemetryValue(message.content) });
-		}
 	}
-	return messages.length === 0 ? undefined : stringifyJsonAttribute(limitTelemetryMessages(messages));
+	for (const message of requestMessages) {
+		if (messages.length === MAX_TELEMETRY_MESSAGE_COUNT) break;
+		messages.push({ role: message.role, content: summarizeTelemetryValue(message.content) });
+	}
+	if (total > MAX_TELEMETRY_MESSAGE_COUNT) {
+		messages.push({
+			role: "system",
+			content: { kind: "truncated", omittedMessages: total - MAX_TELEMETRY_MESSAGE_COUNT },
+		});
+	}
+	return stringifyJsonAttribute(messages);
 }
 
 function serializeResponseTextForTelemetry(telemetry: AgentTelemetry, message: AssistantMessage): string | undefined {
@@ -1022,17 +1034,6 @@ function callContentSerializer(
 	}
 }
 
-function limitTelemetryMessages(messages: readonly TelemetryMessageSummary[]): TelemetryMessageSummary[] {
-	const limited = messages.slice(0, MAX_TELEMETRY_MESSAGE_COUNT);
-	if (messages.length > MAX_TELEMETRY_MESSAGE_COUNT) {
-		limited.push({
-			role: "system",
-			content: { kind: "truncated", omittedMessages: messages.length - MAX_TELEMETRY_MESSAGE_COUNT },
-		});
-	}
-	return limited;
-}
-
 function limitTelemetryToolCalls(toolCalls: readonly TelemetryToolCallSummary[]): TelemetryToolCallSummary[] {
 	const limited = toolCalls.slice(0, MAX_TELEMETRY_ARRAY_ITEMS);
 	if (toolCalls.length > MAX_TELEMETRY_ARRAY_ITEMS) {

package/src/tool-arguments.ts

@@ -0,0 +1,38 @@
+import { type ToolCall, validateToolArguments } from "@oh-my-pi/pi-ai";
+import type { AgentTool } from "./types";
+
+/**
+ * Where a call's `__parseError`/`__rawJson` keys came from.
+ * - `"parsed"`: a provider stream parsed the arguments, so `__parseError` is a
+ *   genuine parse-failure sentinel and is never handed to a tool.
+ * - `"payload"`: the arguments are a payload the model wrote (eval tool bridge,
+ *   `xd://` device content), so those keys are forged and only stripped.
+ */
+export type ToolArgumentSource = "parsed" | "payload";
+
+/**
+ * Validate a call's arguments against `tool`'s schema, honoring
+ * {@link AgentTool.lenientArgValidation}: on a schema mismatch a lenient tool
+ * receives its raw arguments minus the internal `__parseError`/`__rawJson`
+ * sentinels. Malformed JSON from a provider stream is never lenient.
+ *
+ * @throws the validation error when the tool is strict or the arguments failed to parse.
+ */
+export function validateAgentToolArguments(
+	tool: AgentTool,
+	toolCall: ToolCall,
+	source: ToolArgumentSource = "parsed",
+): ToolCall["arguments"] {
+	try {
+		return validateToolArguments(tool, toolCall);
+	} catch (error) {
+		const args: unknown = toolCall.arguments;
+		if (!tool.lenientArgValidation) throw error;
+		if (args === null || typeof args !== "object" || Array.isArray(args)) return args as ToolCall["arguments"];
+		if (source === "parsed" && "__parseError" in args) throw error;
+		const fallback = { ...(args as Record<string, unknown>) };
+		delete fallback.__parseError;
+		delete fallback.__rawJson;
+		return fallback;
+	}
+}