@oh-my-pi/pi-ai 16.3.4 → 16.3.5

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [16.3.5] - 2026-07-04
+
+### Added
+
+- `OAuthCallbackFlow` now serves a `GET /launch` route on its loopback callback server that 302-redirects to the pending authorization URL, and exposes that short URL as `OAuthAuthInfo.launchUrl`. UIs can advertise it as a truncation-safe copy target (~30 chars) instead of the full authorize URL, so terminals narrower than the composed row cannot silently drop OAuth query parameters like `code_challenge_method=S256` ([#4418](https://github.com/can1357/oh-my-pi/issues/4418)).
+- Preserved explicit `tool.strict === false` on OpenAI-family function tool payloads (openai-responses, openai-codex-responses, openai-completions) so backends that distinguish `strict: false` from an omitted flag stop over-filling optional arguments ([#4336](https://github.com/can1357/oh-my-pi/issues/4336)).
+
+### Fixed
+
+- Fixed tool-call validation to strip stray trailing line terminators on schema-matching enum values and on well-known identifier fields (`path`, `paths`, `file`, `file_path`, `url`, `uri`, `title`, `label`) before dispatch, keeping ordinary trailing spaces and content-carrying fields (`content`, `input`, `code`, `command`, etc.) intact ([#4461](https://github.com/can1357/oh-my-pi/issues/4461)).
+
 ## [16.3.4] - 2026-07-03
 
 ### Added

package/dist/types/auth-storage.d.ts

@@ -9,7 +9,7 @@
  */
 import { Database } from "bun:sqlite";
 import type { ApiKeyResolver } from "./auth-retry";
-import type { OAuthController, OAuthCredentials, OAuthProviderId } from "./registry/oauth/types";
+import type { OAuthAuthInfo, OAuthController, OAuthCredentials, OAuthProviderId } from "./registry/oauth/types";
 import type { Provider } from "./types";
 import type { CredentialRankingStrategy, UsageCostHistoryEntry, UsageCostHistoryQuery, UsageHistoryEntry, UsageHistoryQuery, UsageLogger, UsageProvider, UsageReport } from "./usage";
 import { type CodexResetConsumeCode, type CodexResetCredit } from "./usage/openai-codex-reset";
@@ -694,10 +694,7 @@ export declare class AuthStorage {
      */
     login(provider: OAuthProviderId, ctrl: OAuthController & {
         /** onAuth is required by auth-storage but optional in OAuthController */
-        onAuth: (info: {
-            url: string;
-            instructions?: string;
-        }) => void;
+        onAuth: (info: OAuthAuthInfo) => void;
         /** onPrompt is required for some providers (github-copilot, openai-codex) */
         onPrompt: (prompt: {
             message: string;

package/dist/types/registry/oauth/types.d.ts

@@ -18,7 +18,21 @@ export type OAuthPrompt = {
     allowEmpty?: boolean;
 };
 export type OAuthAuthInfo = {
+    /**
+     * Full authorization URL. Suitable for direct browser launch, OSC 8
+     * hyperlinks, and clipboard when the target UI can guarantee the full
+     * string reaches the user unmodified.
+     */
     url: string;
+    /**
+     * Short loopback URL that 302-redirects to {@link url}. Provided by flows
+     * that host the redirect on the same callback server they already run
+     * ({@link OAuthCallbackFlow}). UIs SHOULD prefer this as the copy target
+     * so viewport truncation cannot corrupt OAuth query parameters. Undefined
+     * for flows without a loopback callback server (device code, paste-code
+     * providers with fixed non-loopback redirects, etc.).
+     */
+    launchUrl?: string;
     instructions?: string;
 };
 export interface OAuthProviderInfo {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.3.4",
+	"version": "16.3.5",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "16.3.4",
-		"@oh-my-pi/pi-utils": "16.3.4",
-		"@oh-my-pi/pi-wire": "16.3.4",
+		"@oh-my-pi/pi-catalog": "16.3.5",
+		"@oh-my-pi/pi-utils": "16.3.5",
+		"@oh-my-pi/pi-wire": "16.3.5",
 		"arktype": "^2.2.0",
 		"zod": "^4"
 	},

package/src/auth-storage.ts

@@ -16,7 +16,13 @@ import * as AIError from "./error";
 import { isUsageLimitOutcome } from "./error/rate-limit";
 import { getProviderDefinition, PASTE_CODE_LOGIN_PROVIDERS } from "./registry";
 import { getOAuthApiKey, getOAuthProvider, refreshOAuthToken } from "./registry/oauth";
-import type { OAuthController, OAuthCredentials, OAuthProvider, OAuthProviderId } from "./registry/oauth/types";
+import type {
+	OAuthAuthInfo,
+	OAuthController,
+	OAuthCredentials,
+	OAuthProvider,
+	OAuthProviderId,
+} from "./registry/oauth/types";
 import { getEnvApiKey, getEnvApiKeyName } from "./stream";
 import type { Provider } from "./types";
 import type {
@@ -1863,7 +1869,7 @@ export class AuthStorage {
 		provider: OAuthProviderId,
 		ctrl: OAuthController & {
 			/** onAuth is required by auth-storage but optional in OAuthController */
-			onAuth: (info: { url: string; instructions?: string }) => void;
+			onAuth: (info: OAuthAuthInfo) => void;
 			/** onPrompt is required for some providers (github-copilot, openai-codex) */
 			onPrompt: (prompt: { message: string; placeholder?: string }) => Promise<string>;
 		},

package/src/providers/openai-codex-responses.ts

@@ -3311,7 +3311,12 @@ export function convertOpenAICodexResponsesTools(
 			name: tool.name,
 			description: tool.description || "",
 			parameters,
-			...(effectiveStrict && { strict: true }),
+			// See openai-responses.ts::convertTools — explicit `strict: false` is
+			// preserved on the wire because some backends distinguish it from
+			// omitted (#4336). `strict: true` still requires enforcement success,
+			// and the `PI_NO_STRICT` global bypass MUST suppress the flag entirely
+			// so Codex proxies that reject the `strict` key stay silent.
+			...(effectiveStrict ? { strict: true } : !NO_STRICT && tool.strict === false ? { strict: false } : {}),
 		};
 	});
 }

package/src/providers/openai-completions.ts

@@ -2115,6 +2115,17 @@ function convertTools(
 	return {
 		tools: adaptedTools.map(({ tool, baseParameters, parameters, strict }) => {
 			const includeStrict = toolStrictMode === "all_strict" || (toolStrictMode === "mixed" && strict);
+			// `strict: false` is semantically distinct from omitted `strict` on some
+			// backends: with it absent, optional properties may be over-filled with
+			// placeholder values (#4336). Preserve the author's explicit `false`,
+			// but only in "mixed" mode against a provider that understands the
+			// field — the `all_strict → none` collapse and `supportsStrictMode:
+			// false` paths deliberately keep the wire flag uniformly absent.
+			const includeExplicitFalse =
+				!includeStrict &&
+				tool.strict === false &&
+				toolStrictMode === "mixed" &&
+				compat.supportsStrictMode !== false;
 			const wireParameters = includeStrict ? parameters : baseParameters;
 			return {
 				type: "function",
@@ -2128,7 +2139,7 @@ function convertTools(
 							? (normalizeSchemaForMoonshot(wireParameters) as Record<string, unknown>)
 							: wireParameters,
 					// Only include strict if provider supports it. Some reject unknown fields.
-					...(includeStrict && { strict: true }),
+					...(includeStrict ? { strict: true } : includeExplicitFalse ? { strict: false } : {}),
 				},
 			};
 		}),

package/src/providers/openai-responses.ts

@@ -987,7 +987,16 @@ export function convertTools(
 			name: tool.name,
 			description: tool.description || "",
 			parameters,
-			...(effectiveStrict && { strict: true }),
+			// `strict: false` and an omitted `strict` are NOT equivalent for every
+			// OpenAI-compat backend — some over-fill optional args when the flag is
+			// absent (#4336). Preserve the author's explicit `false` only while the
+			// Responses strict field is enabled; compatibility disables and
+			// strict-schema fallback retries rely on uniformly absent flags.
+			...(effectiveStrict
+				? { strict: true }
+				: !NO_STRICT && strictMode && tool.strict === false
+					? { strict: false }
+					: {}),
 		} as OpenAITool);
 	}
 	return out;

package/src/registry/oauth/callback-server.ts

@@ -17,6 +17,14 @@ import type { OAuthController, OAuthCredentials } from "./types";
 const DEFAULT_TIMEOUT = 300_000;
 const DEFAULT_HOSTNAME = "localhost";
 const CALLBACK_PATH = "/callback";
+/**
+ * Path served by {@link OAuthCallbackFlow} that 302-redirects to the pending
+ * authorization URL. Kept out of {@link OAuthCallbackFlowOptions} because it
+ * lives on the loopback callback server alongside {@link CALLBACK_PATH} and
+ * must never clash with a provider-registered redirect URI (all known
+ * providers register `/callback`-shaped paths).
+ */
+const LAUNCH_PATH = "/launch";
 
 export type CallbackResult = { code: string; state: string };
 
@@ -54,6 +62,14 @@ export abstract class OAuthCallbackFlow {
 	allowPortFallback: boolean;
 	#callbackResolve?: (result: CallbackResult) => void;
 	#callbackReject?: (error: string) => void;
+	/**
+	 * Authorization URL the `/launch` route currently redirects to. Set by
+	 * {@link login} after {@link generateAuthUrl} and before {@link OAuthController.onAuth}
+	 * fires, cleared when the server stops. `undefined` before the flow reaches
+	 * that point and after it finishes, so `/launch` returns 503 rather than
+	 * a stale URL.
+	 */
+	#pendingAuthUrl?: string;
 
 	constructor(
 		ctrl: OAuthController,
@@ -120,7 +136,7 @@ export abstract class OAuthCallbackFlow {
 		this.#throwIfCancelled();
 
 		// Start callback server first to get actual redirect URI
-		const { server, redirectUri } = await this.#startCallbackServer(state);
+		const { server, redirectUri, launchUrl } = await this.#startCallbackServer(state);
 
 		try {
 			this.#throwIfCancelled();
@@ -128,8 +144,14 @@ export abstract class OAuthCallbackFlow {
 			const { url: authUrl, instructions } = await this.generateAuthUrl(state, redirectUri);
 			this.#throwIfCancelled();
 
+			// Publish the auth URL to the `/launch` route BEFORE handing it to
+			// callers. `onAuth` immediately renders a UI that advertises the
+			// launch URL as a copy target, so `/launch` must already resolve if
+			// the user clicks/pastes it during the same render pass.
+			this.#pendingAuthUrl = authUrl;
+
 			// Notify controller that auth is ready
-			this.ctrl.onAuth?.({ url: authUrl, instructions });
+			this.ctrl.onAuth?.({ url: authUrl, launchUrl, instructions });
 			this.ctrl.onProgress?.("Waiting for browser authentication...");
 
 			// Wait for callback or manual input
@@ -140,21 +162,33 @@ export abstract class OAuthCallbackFlow {
 
 			return await this.exchangeToken(code, state, redirectUri);
 		} finally {
+			this.#pendingAuthUrl = undefined;
 			server.stop();
 		}
 	}
 
 	/**
 	 * Start callback server, trying preferred port first, falling back to random.
+	 * `launchUrl` is `undefined` when the caller configured `callbackPath` to
+	 * collide with {@link LAUNCH_PATH} — the callback handler resolves the real
+	 * callback in that case, so advertising a self-redirecting URL would be
+	 * incorrect.
 	 */
-	async #startCallbackServer(expectedState: string): Promise<{ server: Bun.Server<unknown>; redirectUri: string }> {
+	async #startCallbackServer(
+		expectedState: string,
+	): Promise<{ server: Bun.Server<unknown>; redirectUri: string; launchUrl: string | undefined }> {
 		try {
 			const server = this.#createServer(this.preferredPort, expectedState);
+			// `preferredPort: 0` opts into a random port — read the actual bound
+			// port from the server so both the redirect URI and launch URL point at
+			// a reachable socket, not the sentinel.
+			const actualPort = this.#resolveServerPort(server);
+			const launchUrl = this.#launchUrlIfSafe(actualPort);
 			if (this.redirectUri) {
-				return { server, redirectUri: this.redirectUri };
+				return { server, redirectUri: this.redirectUri, launchUrl };
 			}
-			const redirectUri = `http://${this.callbackHostname}:${this.preferredPort}${this.callbackPath}`;
-			return { server, redirectUri };
+			const redirectUri = `http://${this.callbackHostname}:${actualPort}${this.callbackPath}`;
+			return { server, redirectUri, launchUrl };
 		} catch (cause) {
 			if (this.redirectUri) {
 				throw new AIError.ConfigurationError(
@@ -169,11 +203,49 @@ export abstract class OAuthCallbackFlow {
 				);
 			}
 			const server = this.#createServer(0, expectedState);
-			const actualPort = server.port;
+			const actualPort = this.#resolveServerPort(server);
 			const redirectUri = `http://${this.callbackHostname}:${actualPort}${this.callbackPath}`;
+			const launchUrl = this.#launchUrlIfSafe(actualPort);
 			this.ctrl.onProgress?.(`Preferred port ${this.preferredPort} unavailable, using port ${actualPort}`);
-			return { server, redirectUri };
+			return { server, redirectUri, launchUrl };
+		}
+	}
+
+	/**
+	 * Read the numeric port a callback server bound to. `Bun.Server.port` is
+	 * declared `number | undefined` because Unix-socket servers have no port,
+	 * but every callback flow uses TCP; a missing port here indicates a
+	 * configuration error rather than a fallback case.
+	 */
+	#resolveServerPort(server: Bun.Server<unknown>): number {
+		const port = server.port;
+		if (typeof port !== "number") {
+			throw new AIError.ConfigurationError(
+				"OAuth callback server bound to a non-TCP endpoint; expected a numeric port. Check `oauth.callbackPort`/`oauth.redirectUri`.",
+			);
+		}
+		return port;
+	}
+
+	/**
+	 * Build the `/launch` URL served by the callback server bound to `port`, or
+	 * `undefined` when the configured `callbackPath` (or a `redirectUri` whose
+	 * pathname resolves to {@link LAUNCH_PATH}) would collide with the launch
+	 * route. Kept short (~30 chars) so UIs can advertise it as a
+	 * viewport-truncation-safe copy target for the full authorization URL.
+	 */
+	#launchUrlIfSafe(port: number): string | undefined {
+		if (this.callbackPath === LAUNCH_PATH) return undefined;
+		if (this.redirectUri) {
+			try {
+				if (new URL(this.redirectUri).pathname === LAUNCH_PATH) return undefined;
+			} catch {
+				// A non-parseable redirectUri (e.g. `vscode://...` handled elsewhere)
+				// can't collide with an HTTP `/launch` route — fall through and
+				// advertise the launch URL against the loopback server.
+			}
 		}
+		return `http://${this.callbackHostname}:${port}${LAUNCH_PATH}`;
 	}
 
 	/**
@@ -190,12 +262,28 @@ export abstract class OAuthCallbackFlow {
 	}
 
 	/**
-	 * Handle OAuth callback HTTP request.
+	 * Handle OAuth callback HTTP request. Two routes on the same loopback server:
+	 * - `callbackPath` (default `/callback`) — the provider redirect target.
+	 * - {@link LAUNCH_PATH} (`/launch`) — 302 to the pending authorization URL so
+	 *   viewport-safe copy targets can survive TUI truncation.
+	 *
+	 * `callbackPath` wins any collision: an OMP config that pins the provider
+	 * redirect at `/launch` (via `oauth.callbackPath` or a loopback
+	 * `oauth.redirectUri`) must resolve the callback normally rather than
+	 * self-redirect. `#startCallbackServer` also suppresses `launchUrl` in that
+	 * case, so the launch route is never advertised when it would collide.
 	 */
 	#handleCallback(req: Request, expectedState: string): Response {
 		const url = new URL(req.url);
 
 		if (url.pathname !== this.callbackPath) {
+			if (url.pathname === LAUNCH_PATH) {
+				const pending = this.#pendingAuthUrl;
+				if (!pending) {
+					return new Response("OAuth launch URL is no longer active", { status: 503 });
+				}
+				return Response.redirect(pending, 302);
+			}
 			return new Response("Not Found", { status: 404 });
 		}
 

package/src/registry/oauth/types.ts

@@ -23,7 +23,21 @@ export type OAuthPrompt = {
 };
 
 export type OAuthAuthInfo = {
+	/**
+	 * Full authorization URL. Suitable for direct browser launch, OSC 8
+	 * hyperlinks, and clipboard when the target UI can guarantee the full
+	 * string reaches the user unmodified.
+	 */
 	url: string;
+	/**
+	 * Short loopback URL that 302-redirects to {@link url}. Provided by flows
+	 * that host the redirect on the same callback server they already run
+	 * ({@link OAuthCallbackFlow}). UIs SHOULD prefer this as the copy target
+	 * so viewport truncation cannot corrupt OAuth query parameters. Undefined
+	 * for flows without a loopback callback server (device code, paste-code
+	 * providers with fixed non-loopback redirects, etc.).
+	 */
+	launchUrl?: string;
 	instructions?: string;
 };
 

package/src/utils/schema/CONSTRAINTS.md

@@ -53,6 +53,7 @@ When strict mode is requested (`strict=true` at call site), the schema MUST sati
 
 6. **Provider payload strict flag must match effective strictness**
    - Callers MUST send `strict: true` only if enforcement succeeded (`effectiveStrict === true`).
+   - Callers MUST preserve an author's explicit `tool.strict === false` on the wire so that `strict: false` and omitted `strict` remain distinguishable — some OpenAI-compat backends over-fill optional fields when the flag is absent but respect it when set to `false` (#4336). Exceptions: `openai-responses` emits explicit `false` only while its `strictMode` gate and `PI_NO_STRICT` permit sending the strict field; `openai-codex-responses` gates explicit `false` on `!PI_NO_STRICT` so the documented global bypass keeps the `strict` key off the wire for Codex proxies that reject it; `openai-completions` emits explicit `false` only in `toolStrictMode === "mixed"` with `compat.supportsStrictMode !== false`, because the `all_strict → none` collapse and providers that reject the `strict` key rely on uniform absence.
 
 ---
 

package/src/utils/validation.ts

@@ -835,6 +835,263 @@ function normalizeOptionalNullsForSchema(
 	return { value: changed ? nextValue : value, changed };
 }
 
+function decodeJsonPointerToken(token: string): string {
+	return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function resolveLocalJsonSchemaRef(root: unknown, ref: string): unknown | undefined {
+	if (ref === "#") return root;
+	if (!ref.startsWith("#/")) return undefined;
+	let current: unknown = root;
+	for (const rawToken of ref.slice(2).split("/")) {
+		const token = decodeJsonPointerToken(rawToken);
+		if (current === null || typeof current !== "object") return undefined;
+		current = (current as Record<string, unknown>)[token];
+	}
+	return current;
+}
+
+function normalizeEnumStringWhitespace(
+	schema: unknown,
+	value: unknown,
+	root: unknown = schema,
+	refs: ReadonlySet<string> = new Set(),
+): { value: unknown; changed: boolean } {
+	if (value === null || value === undefined) return { value, changed: false };
+	if (schema === null || typeof schema !== "object") return { value, changed: false };
+
+	const schemaObject = schema as Record<string, unknown>;
+	const ref = schemaObject.$ref;
+	if (typeof ref === "string") {
+		if (refs.has(ref)) return { value, changed: false };
+		const resolved = resolveLocalJsonSchemaRef(root, ref);
+		if (resolved === undefined) return { value, changed: false };
+		return normalizeEnumStringWhitespace(resolved, value, root, new Set([...refs, ref]));
+	}
+
+	const branchMatches = (branch: unknown, candidate: unknown): boolean => {
+		if (branch !== null && typeof branch === "object") {
+			const branchRef = (branch as Record<string, unknown>).$ref;
+			if (typeof branchRef === "string" && !refs.has(branchRef)) {
+				const resolved = resolveLocalJsonSchemaRef(root, branchRef);
+				if (resolved !== undefined) return branchMatchesSchema(resolved, candidate);
+			}
+		}
+		return branchMatchesSchema(branch, candidate);
+	};
+
+	const normalizeAnyOfLike = (keyword: "anyOf" | "oneOf"): { value: unknown; changed: boolean } => {
+		const branches = schemaObject[keyword];
+		if (!Array.isArray(branches)) return { value, changed: false };
+		if (branches.some(branch => branchMatches(branch, value))) return { value, changed: false };
+
+		for (const branch of branches) {
+			const normalized = normalizeEnumStringWhitespace(branch, value, root, refs);
+			if (!normalized.changed) continue;
+			if (branchMatches(branch, normalized.value)) return normalized;
+		}
+		return { value, changed: false };
+	};
+
+	const anyOfNormalization = normalizeAnyOfLike("anyOf");
+	if (anyOfNormalization.changed) return anyOfNormalization;
+
+	const oneOfNormalization = normalizeAnyOfLike("oneOf");
+	if (oneOfNormalization.changed) return oneOfNormalization;
+
+	if (Array.isArray(schemaObject.allOf)) {
+		let changed = false;
+		let nextValue: unknown = value;
+		for (const branch of schemaObject.allOf) {
+			const normalized = normalizeEnumStringWhitespace(branch, nextValue, root, refs);
+			if (!normalized.changed) continue;
+			nextValue = normalized.value;
+			changed = true;
+		}
+		if (changed) return { value: nextValue, changed: true };
+	}
+
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed !== value) {
+			const enumValues = schemaObject.enum;
+			if (Array.isArray(enumValues) && !enumValues.includes(value) && enumValues.includes(trimmed)) {
+				return { value: trimmed, changed: true };
+			}
+			const constValue = schemaObject.const;
+			if (typeof constValue === "string" && trimmed === constValue) {
+				return { value: trimmed, changed: true };
+			}
+		}
+		return { value, changed: false };
+	}
+
+	if (Array.isArray(value)) {
+		let changed = false;
+		let nextValue = value;
+		const prefixItems = schemaObject.prefixItems;
+		if (Array.isArray(prefixItems)) {
+			for (let i = 0; i < value.length && i < prefixItems.length; i += 1) {
+				const itemSchema = prefixItems[i];
+				const normalized = normalizeEnumStringWhitespace(itemSchema, value[i], root, refs);
+				if (!normalized.changed) continue;
+				if (!changed) {
+					nextValue = [...value];
+					changed = true;
+				}
+				nextValue[i] = normalized.value;
+			}
+		}
+
+		const itemSchema = schemaObject.items;
+		if (itemSchema !== null && typeof itemSchema === "object" && !Array.isArray(itemSchema)) {
+			for (let i = 0; i < value.length; i += 1) {
+				if (Array.isArray(prefixItems) && i < prefixItems.length) continue;
+				const normalized = normalizeEnumStringWhitespace(itemSchema, nextValue[i], root, refs);
+				if (!normalized.changed) continue;
+				if (!changed) {
+					nextValue = [...value];
+					changed = true;
+				}
+				nextValue[i] = normalized.value;
+			}
+		}
+		return { value: changed ? nextValue : value, changed };
+	}
+
+	if (typeof value !== "object") return { value, changed: false };
+	const properties = schemaObject.properties;
+	if (!properties || typeof properties !== "object") return { value, changed: false };
+
+	const propsObject = properties as Record<string, unknown>;
+	const valueObject = value as Record<string, unknown>;
+	let changed = false;
+	let nextValue = valueObject;
+	for (const [key, propertySchema] of Object.entries(propsObject)) {
+		if (!(key in nextValue)) continue;
+		const normalized = normalizeEnumStringWhitespace(propertySchema, nextValue[key], root, refs);
+		if (!normalized.changed) continue;
+		if (!changed) {
+			nextValue = { ...nextValue };
+			changed = true;
+		}
+		nextValue[key] = normalized.value;
+	}
+	return { value: changed ? nextValue : valueObject, changed };
+}
+
+// ============================================================================
+// Identifier-string trailing-whitespace normalization (LLM quirk).
+// ============================================================================
+//
+// LLMs sometimes emit tool arguments with a trailing newline dangling off a
+// short identifier — a path, URL, or a display label like `title`. These
+// values are never legitimately terminated by line breaks, so we strip trailing
+// line terminators from string values on the well-known keys below before the
+// tool ever sees them. Content-carrying properties (`content`, `input`, `body`,
+// `text`, `command`, `code`) are intentionally not traversed or trimmed so
+// genuine trailing whitespace survives on writes, patches, shell commands, and
+// eval snippets.
+// ============================================================================
+
+/**
+ * Property names whose values are treated as short identifiers — filesystem
+ * paths, URLs, URIs, or display labels. The trim only fires on strings sitting
+ * under one of these keys, so `path: "docs/report "` still targets the file
+ * whose name ends in a space.
+ */
+const IDENTIFIER_STRING_KEYS: ReadonlySet<string> = new Set([
+	"path",
+	"paths",
+	"file",
+	"file_path",
+	"filePath",
+	"filepath",
+	"url",
+	"uri",
+	"title",
+	"label",
+]);
+
+const CONTENT_CARRYING_KEYS: ReadonlySet<string> = new Set(["content", "input", "body", "text", "command", "code"]);
+
+const TRAILING_LINE_TERMINATOR_RE = /[\r\n]+$/;
+
+function trimTrailingLineTerminators(input: string): string {
+	if (!TRAILING_LINE_TERMINATOR_RE.test(input)) return input;
+	return input.replace(TRAILING_LINE_TERMINATOR_RE, "");
+}
+
+function trimIdentifierStringLeaf(input: unknown): unknown {
+	if (typeof input === "string") {
+		const trimmed = trimTrailingLineTerminators(input);
+		return trimmed === input ? input : trimmed;
+	}
+	if (Array.isArray(input)) {
+		let changed = false;
+		let next = input;
+		for (let i = 0; i < input.length; i += 1) {
+			const item = input[i];
+			if (typeof item !== "string") continue;
+			const trimmed = trimTrailingLineTerminators(item);
+			if (trimmed === item) continue;
+			if (!changed) {
+				next = input.slice();
+				changed = true;
+			}
+			next[i] = trimmed;
+		}
+		return changed ? next : input;
+	}
+	return input;
+}
+
+/**
+ * Recursively strip trailing line terminators from string values whose property
+ * key matches {@link IDENTIFIER_STRING_KEYS}. Runs by property name only
+ * (schema-agnostic) so it fires uniformly across Zod, ArkType, and plain JSON
+ * Schema tools while preserving nested payloads under content-carrying keys.
+ */
+function normalizeIdentifierStringWhitespace(value: unknown): { value: unknown; changed: boolean } {
+	if (Array.isArray(value)) {
+		let changed = false;
+		let next = value;
+		for (let i = 0; i < value.length; i += 1) {
+			const normalized = normalizeIdentifierStringWhitespace(value[i]);
+			if (!normalized.changed) continue;
+			if (!changed) {
+				next = [...value];
+				changed = true;
+			}
+			next[i] = normalized.value;
+		}
+		return { value: changed ? next : value, changed };
+	}
+
+	if (value === null || typeof value !== "object") return { value, changed: false };
+
+	const source = value as Record<string, unknown>;
+	let changed = false;
+	let out: Record<string, unknown> = source;
+	for (const [key, entry] of Object.entries(source)) {
+		let nextEntry = entry;
+		if (CONTENT_CARRYING_KEYS.has(key)) continue;
+		if (IDENTIFIER_STRING_KEYS.has(key)) {
+			const trimmed = trimIdentifierStringLeaf(entry);
+			if (trimmed !== entry) nextEntry = trimmed;
+		}
+		const nested = normalizeIdentifierStringWhitespace(nextEntry);
+		if (nested.changed) nextEntry = nested.value;
+		if (nextEntry === entry) continue;
+		if (!changed) {
+			out = { ...source };
+			changed = true;
+		}
+		out[key] = nextEntry;
+	}
+	return { value: changed ? out : value, changed };
+}
+
 // ============================================================================
 // Double-encoded object-key normalization (LLM quirk).
 // ============================================================================
@@ -1485,6 +1742,23 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 		changed = true;
 	}
 
+	const enumStringNormalization = normalizeEnumStringWhitespace(json, normalizedArgs);
+	if (enumStringNormalization.changed) {
+		normalizedArgs = enumStringNormalization.value;
+		changed = true;
+	}
+
+	// Strip trailing whitespace from string values on well-known
+	// identifier-like property names (paths, URLs, titles). Some models tack
+	// a newline onto a short-identifier arg from stream artifacts; downstream
+	// tools then either fail to stat the target or annotate a "corrected
+	// from" hint the model misreads as tool corruption.
+	const identifierStringNormalization = normalizeIdentifierStringWhitespace(normalizedArgs);
+	if (identifierStringNormalization.changed) {
+		normalizedArgs = identifierStringNormalization.value;
+		changed = true;
+	}
+
 	// Then re-shape JSON-stringified arrays whose schema accepts both string
 	// and array (e.g. `paths: string | string[]`). Without this, zod accepts
 	// the literal `'["a","b"]'` as a string and downstream tools treat it as
@@ -1495,6 +1769,12 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 		changed = true;
 	}
 
+	const identifierStringNormalizationAfterArray = normalizeIdentifierStringWhitespace(normalizedArgs);
+	if (identifierStringNormalizationAfterArray.changed) {
+		normalizedArgs = identifierStringNormalizationAfterArray.value;
+		changed = true;
+	}
+
 	// Single-argument tools (e.g. `edit`): if the model put the lone required
 	// string under a different key, adopt the first string field as that key.
 	const singleStringNorm = normalizeSingleStringField(json, normalizedArgs);
@@ -1527,6 +1807,16 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 			normalizedArgs = nullNormalization.value;
 		}
 
+		const enumStringNormalizationPass = normalizeEnumStringWhitespace(json, normalizedArgs);
+		if (enumStringNormalizationPass.changed) {
+			normalizedArgs = enumStringNormalizationPass.value;
+		}
+
+		const identifierStringNormalizationPass = normalizeIdentifierStringWhitespace(normalizedArgs);
+		if (identifierStringNormalizationPass.changed) {
+			normalizedArgs = identifierStringNormalizationPass.value;
+		}
+
 		// Re-run the union-string coercion because `coerceArgsFromIssues` may
 		// have just unwrapped a JSON-stringified object at the root or inside a
 		// nested field — exposing `string | string[]` descendants the initial
@@ -1536,6 +1826,11 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 			normalizedArgs = stringEncodedArrayNormPass.value;
 		}
 
+		const identifierStringNormalizationAfterArrayPass = normalizeIdentifierStringWhitespace(normalizedArgs);
+		if (identifierStringNormalizationAfterArrayPass.changed) {
+			normalizedArgs = identifierStringNormalizationAfterArrayPass.value;
+		}
+
 		// Re-run single-string remap: `coerceArgsFromIssues` may have just
 		// unwrapped a JSON-stringified root object, exposing a mislabelled lone
 		// string field the initial pre-pass could not see.