@oh-my-pi/pi-agent-core 14.9.2 → 14.9.5

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [14.9.5] - 2026-05-12
+
+### Added
+
+- Added an `isError?: boolean` field on `AgentToolResult` so tools can flag a non-throwing failure (e.g. an aggregator that catches per-entry errors). `coerceToolResult` preserves the flag and the agent loop surfaces it as a tool error on the wire.
+
+## [14.9.3] - 2026-05-10
+### Added
+
+- Added `onHarmonyLeak` option on `Agent`/loop config to receive GPT-5 Harmony leak audit callbacks
+- Added harmony-leak detection and audit exports to the package index for programmatic leak detection and recovery hooks
+
+### Changed
+
+- Changed OpenAI Codex model runs to detect GPT-5 Harmony protocol leakage during streaming and automatically retry or recover tool calls instead of sending contaminated arguments downstream
+
+### Security
+
+- Hardened tool-call handling against leaked `to=functions.*` protocol tails by truncating or retrying before execution
+- Hardened failure handling so repeated GPT-5 Harmony leak mitigation is retried only up to two times before escalating to an explicit error
+
 ## [14.9.0] - 2026-05-10
 ### Added
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "14.9.2",
+	"version": "14.9.5",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -35,9 +35,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "14.9.2",
-		"@oh-my-pi/pi-natives": "14.9.2",
-		"@oh-my-pi/pi-utils": "14.9.2"
+		"@oh-my-pi/pi-ai": "14.9.5",
+		"@oh-my-pi/pi-natives": "14.9.5",
+		"@oh-my-pi/pi-utils": "14.9.5"
 	},
 	"devDependencies": {
 		"@sinclair/typebox": "^0.34.49",

package/src/agent-loop.ts

@@ -12,6 +12,15 @@ import {
 	validateToolArguments,
 } from "@oh-my-pi/pi-ai";
 import { sanitizeText } from "@oh-my-pi/pi-natives";
+import {
+	createHarmonyAuditEvent,
+	extractHarmonyRemoved,
+	type HarmonyDetection,
+	type HarmonyRecoveredToolCall,
+	isHarmonyLeakMitigationTarget,
+	recoverHarmonyToolCall,
+	signalListLabel,
+} from "./harmony-leak";
 import type {
 	AgentContext,
 	AgentEvent,
@@ -25,6 +34,17 @@ import type {
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
 const ABORTED: unique symbol = Symbol("agent-loop-aborted");
 
+class HarmonyLeakInterruption extends Error {
+	constructor(
+		readonly detection: HarmonyDetection,
+		readonly removed: string,
+		readonly recovered?: HarmonyRecoveredToolCall,
+	) {
+		super(`Detected GPT-5 Harmony protocol leakage (${signalListLabel(detection.signals)})`);
+		this.name = "HarmonyLeakInterruption";
+	}
+}
+
 /**
  * Normalize a value coming back from `tool.execute()` (or its streaming partial-update callback)
  * into a structurally valid {@link AgentToolResult}.
@@ -38,12 +58,17 @@ function coerceToolResult(raw: unknown): { result: AgentToolResult<any>; malform
 	const rawObj = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : null;
 	const rawContent = rawObj?.content;
 	const details = rawObj && "details" in rawObj ? rawObj.details : {};
+	// Tools may flag a non-throwing failure on the result itself (e.g. an
+	// aggregator that catches per-entry errors and synthesizes a combined
+	// result). Preserve the flag so agent-loop can surface it on the wire.
+	const explicitError = Boolean(rawObj && "isError" in rawObj && rawObj.isError);
 
 	if (!Array.isArray(rawContent)) {
 		return {
 			result: {
 				content: [{ type: "text", text: "Tool returned an invalid result: missing content array." }],
 				details,
+				isError: true,
 			},
 			malformed: true,
 		};
@@ -62,7 +87,7 @@ function coerceToolResult(raw: unknown): { result: AgentToolResult<any>; malform
 			content.push(block as { type: "image"; data: string; mimeType: string });
 		}
 	}
-	return { result: { content, details }, malformed: false };
+	return { result: { content, details, ...(explicitError ? { isError: true } : {}) }, malformed: false };
 }
 
 /**
@@ -255,6 +280,8 @@ async function runLoop(
 	let firstTurn = true;
 	// Check for steering messages at start (user may have typed while waiting)
 	let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];
+	let harmonyRetryAttempt = 0;
+	let harmonyTruncateResumeCount = 0;
 
 	// Outer loop: continues when queued follow-up messages arrive after agent would stop
 	while (true) {
@@ -285,7 +312,44 @@ async function runLoop(
 			}
 
 			// Stream assistant response
-			const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn);
+			let recovered: HarmonyRecoveredToolCall | undefined;
+			let message: AssistantMessage;
+			try {
+				message = await streamAssistantResponse(
+					currentContext,
+					config,
+					signal,
+					stream,
+					streamFn,
+					harmonyRetryAttempt,
+				);
+				harmonyRetryAttempt = 0;
+				harmonyTruncateResumeCount = 0;
+			} catch (err) {
+				if (!(err instanceof HarmonyLeakInterruption)) throw err;
+				if (err.recovered) {
+					if (harmonyTruncateResumeCount >= 2) {
+						await emitHarmonyAudit(config, err, "escalated", harmonyRetryAttempt);
+						throw new Error(
+							`GPT-5 Harmony leak recurred after truncate-and-resume recovery (${signalListLabel(err.detection.signals)}).`,
+						);
+					}
+					harmonyTruncateResumeCount++;
+					recovered = err.recovered;
+					message = recovered.message;
+					await emitHarmonyAudit(config, err, "truncate_resume", harmonyRetryAttempt);
+				} else {
+					if (harmonyRetryAttempt >= 2) {
+						await emitHarmonyAudit(config, err, "escalated", harmonyRetryAttempt);
+						throw new Error(
+							`GPT-5 Harmony leak persisted after ${harmonyRetryAttempt} retries (${signalListLabel(err.detection.signals)}).`,
+						);
+					}
+					await emitHarmonyAudit(config, err, "abort_retry", harmonyRetryAttempt);
+					harmonyRetryAttempt++;
+					continue;
+				}
+			}
 			newMessages.push(message);
 			let steeringMessagesFromExecution: AgentMessage[] | undefined;
 
@@ -355,6 +419,23 @@ async function runLoop(
 	stream.end(newMessages);
 }
 
+async function emitHarmonyAudit(
+	config: AgentLoopConfig,
+	interruption: HarmonyLeakInterruption,
+	action: "truncate_resume" | "abort_retry" | "escalated",
+	retryN: number,
+): Promise<void> {
+	await config.onHarmonyLeak?.(
+		createHarmonyAuditEvent({
+			action,
+			detection: interruption.detection,
+			model: config.model,
+			retryN,
+			removed: interruption.removed,
+		}),
+	);
+}
+
 /**
  * Stream an assistant response from the LLM.
  * This is where AgentMessage[] gets transformed to Message[] for the LLM.
@@ -365,6 +446,7 @@ async function streamAssistantResponse(
 	signal: AbortSignal | undefined,
 	stream: EventStream<AgentEvent, AgentMessage[]>,
 	streamFn?: StreamFn,
+	harmonyRetryAttempt = 0,
 ): Promise<AssistantMessage> {
 	// Apply context transform if configured (AgentMessage[] → AgentMessage[])
 	let messages = context.messages;
@@ -397,33 +479,63 @@ async function streamAssistantResponse(
 
 	const dynamicToolChoice = config.getToolChoice?.();
 	const dynamicReasoning = config.getReasoning?.();
+	const harmonyMitigationEnabled = isHarmonyLeakMitigationTarget(config.model);
+	const harmonyAbortController = harmonyMitigationEnabled ? new AbortController() : undefined;
+	const requestSignal = harmonyAbortController
+		? signal
+			? AbortSignal.any([signal, harmonyAbortController.signal])
+			: harmonyAbortController.signal
+		: signal;
 	const response = await streamFunction(config.model, llmContext, {
 		...config,
 		apiKey: resolvedApiKey,
 		metadata: resolvedMetadata,
 		toolChoice: dynamicToolChoice ?? config.toolChoice,
 		reasoning: dynamicReasoning ?? config.reasoning,
-		signal,
+		temperature:
+			harmonyRetryAttempt > 0 && config.temperature !== undefined ? config.temperature + 0.05 : config.temperature,
+		signal: requestSignal,
 	});
 
 	let partialMessage: AssistantMessage | null = null;
 	let addedPartial = false;
 
 	const responseIterator = response[Symbol.asyncIterator]();
+
+	const _interruptForHarmonyLeak = (message: AssistantMessage, detection: HarmonyDetection): never => {
+		const recovered = recoverHarmonyToolCall(message, detection);
+		const removed = recovered?.removed ?? extractHarmonyRemoved(message, detection);
+		harmonyAbortController?.abort();
+		responseIterator.return?.()?.catch(() => {});
+		if (recovered) {
+			if (addedPartial) {
+				context.messages[context.messages.length - 1] = recovered.message;
+			} else {
+				context.messages.push(recovered.message);
+				stream.push({ type: "message_start", message: { ...recovered.message } });
+			}
+			stream.push({ type: "message_end", message: recovered.message });
+			throw new HarmonyLeakInterruption(detection, removed, recovered);
+		}
+		if (addedPartial) {
+			context.messages.pop();
+		}
+		throw new HarmonyLeakInterruption(detection, removed);
+	};
 	// Set up a single abort race: register the abort listener once for the whole
 	// stream and reuse the same race promise for every iterator.next() instead of
 	// allocating Promise.withResolvers and add/removeEventListener per event.
 	let abortRacePromise: Promise<typeof ABORTED> | undefined;
 	let detachAbortListener: (() => void) | undefined;
-	if (signal) {
-		if (signal.aborted) {
+	if (requestSignal) {
+		if (requestSignal.aborted) {
 			return emitAbortedAssistantMessage(partialMessage, addedPartial, context, config, stream);
 		}
 		const { promise, resolve } = Promise.withResolvers<typeof ABORTED>();
 		const onAbort = () => resolve(ABORTED);
-		signal.addEventListener("abort", onAbort, { once: true });
+		requestSignal.addEventListener("abort", onAbort, { once: true });
 		abortRacePromise = promise;
-		detachAbortListener = () => signal.removeEventListener("abort", onAbort);
+		detachAbortListener = () => requestSignal.removeEventListener("abort", onAbort);
 	}
 
 	try {
@@ -439,7 +551,7 @@ async function streamAssistantResponse(
 			} else {
 				next = await responseIterator.next();
 			}
-			if (signal?.aborted) {
+			if (requestSignal?.aborted) {
 				return emitAbortedAssistantMessage(partialMessage, addedPartial, context, config, stream);
 			}
 			if (next.done) break;
@@ -720,7 +832,7 @@ async function executeToolCalls(
 			);
 			const coerced = coerceToolResult(rawResult);
 			result = coerced.result;
-			if (coerced.malformed) isError = true;
+			if (coerced.malformed || result.isError) isError = true;
 		} catch (e) {
 			result = {
 				content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],

package/src/agent.ts

@@ -21,6 +21,7 @@ import {
 	type ToolResultMessage,
 } from "@oh-my-pi/pi-ai";
 import { agentLoop, agentLoopContinue } from "./agent-loop";
+import type { HarmonyAuditEvent } from "./harmony-leak";
 import type {
 	AgentContext,
 	AgentEvent,
@@ -144,6 +145,11 @@ export interface AgentOptions {
 	 * Use this when abort decisions must happen before buffered events continue flowing.
 	 */
 	onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+
+	/**
+	 * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
+	 */
+	onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	/**
 	 * Custom token budgets for thinking levels (token-based providers only).
 	 */
@@ -264,6 +270,7 @@ export class Agent {
 	#onResponse?: SimpleStreamOptions["onResponse"];
 	#onSseEvent?: SimpleStreamOptions["onSseEvent"];
 	#onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 
 	/** Buffered Cursor tool results with text length at time of call (for correct ordering) */
 	#cursorToolResultBuffer: CursorToolResultEntry[] = [];
@@ -304,6 +311,7 @@ export class Agent {
 		this.#intentTracing = opts.intentTracing === true;
 		this.#getToolChoice = opts.getToolChoice;
 		this.#onAssistantMessageEvent = opts.onAssistantMessageEvent;
+		this.#onHarmonyLeak = opts.onHarmonyLeak;
 	}
 
 	/**
@@ -861,6 +869,7 @@ export class Agent {
 			transformToolCallArguments: this.#transformToolCallArguments,
 			intentTracing: this.#intentTracing,
 			onAssistantMessageEvent: this.#onAssistantMessageEvent,
+			onHarmonyLeak: this.#onHarmonyLeak,
 			getToolChoice,
 			getReasoning: () => this.#state.thinkingLevel,
 			getSteeringMessages: async () => {

package/src/harmony-leak.ts

@@ -0,0 +1,428 @@
+/**
+ * GPT-5 Harmony-header leakage detection and recovery.
+ *
+ * Background and policy: see `docs/ERRATA-GPT5-HARMONY.md`. This module
+ * implements §3 of that document: detection by signal fusion, plus a
+ * truncate-and-resume primitive for the `edit` tool when its input is in
+ * hashline DSL form. Other tools and surfaces fall through to
+ * abort-and-retry handled by the agent loop.
+ */
+import type { AssistantMessage, Model, ToolCall } from "@oh-my-pi/pi-ai";
+
+// Single source of truth for the marker pattern. `M` in the errata.
+// Use a fresh non-global instance for `.test()` to avoid lastIndex pitfalls.
+const MARKER_RE = /\bto=functions\.[A-Za-z_]\w*/g;
+const HARMONY_RE = /<\|(start|end|channel|message|call|return)\|>/g;
+
+// Channel-word adjacency (`C`): channel/role name appearing immediately before the marker.
+const CHANNEL_WORD_RE = /\b(?:analysis|commentary|assistant|user|system|developer|tool)\s+to=functions\./;
+
+// Glitch-token adjacency (`G`). The Japgolly literal is escaped so this regex
+// source itself does not trip detection if the file is scanned (e.g. when
+// editing this module via the same agent that detects).
+const GLITCH_RE = /\b(?:changedFiles|RTLU|Jsii(?:_commentary)?|\x4aapgolly)\b/;
+
+// Body-channel cascade (`B`): marker followed by ` code` then another marker
+// within 200 chars. Single regex; no manual slicing needed.
+const BODY_CASCADE_RE = /to=functions\.\w+\s+code\b[\s\S]{0,200}?to=functions\./;
+
+// Fake-result framing (`R`): marker followed within 80 chars by Cell N: framing.
+const FAKE_RESULT_RE = /to=functions\.\w+[\s\S]{0,80}?code_output\s*\nCell\s+\d+:/;
+
+const FENCE_RE = /^\s*(?:```+|~~~+)/;
+
+// Non-Latin scripts seen in the corpus: CJK + ext, Cyrillic, Thai, Georgian,
+// Armenian, Kannada, Telugu, Devanagari, Arabic, Malayalam.
+const SCRIPT_CLASS =
+	"\u3400-\u4DBF\u4E00-\u9FFF\uF900-\uFAFF\u0400-\u04FF\u0E00-\u0E7F\u10A0-\u10FF\u0530-\u058F\u0C80-\u0CFF\u0C00-\u0C7F\u0900-\u097F\u0600-\u06FF\u0D00-\u0D7F";
+const SCRIPT_RUN_RE = new RegExp(`[${SCRIPT_CLASS}]{2,}`, "u");
+const _SCRIPT_CHAR_RE = new RegExp(`[${SCRIPT_CLASS}]`, "u");
+
+// Recovery registry. Each entry's parser must recognize the configured
+// sentinel (per-tool, see eval/parse.ts and hashline/parser.ts) and surface
+// a warning to the model so it knows to re-issue any remaining work.
+// `accepts` gates on input shape: tools whose contaminated input doesn't
+// match the parser's expected DSL fall through to abort-and-retry.
+//
+// • `edit`: hashline DSL input begins with `@<path>`. Apply_patch envelopes
+//   (`*** Begin Patch …`) and JSON-schema variants are not recoverable —
+//   their parsers don't recognize `*** Abort`.
+// • `eval`: any string is a parseable cell sequence (the parser is lenient
+//   and falls back to implicit-cell mode on bare strings).
+interface RecoveryConfig {
+	sentinel: string;
+	accepts: (input: string) => boolean;
+}
+const RECOVERY_REGISTRY: Record<string, RecoveryConfig> = {
+	edit: {
+		sentinel: "\n*** Abort\n",
+		accepts: input => input.replace(/^\s+/, "").startsWith("@"),
+	},
+	eval: {
+		sentinel: "\n*** Abort\n",
+		accepts: () => true,
+	},
+};
+
+const SIGNAL_ORDER = ["M", "C", "G", "S", "B", "R", "T"] as const;
+
+export type HarmonySignalClass = "H" | (typeof SIGNAL_ORDER)[number];
+
+export type HarmonySurface = "assistant_text" | "assistant_thinking" | "tool_arg";
+
+export interface HarmonySignal {
+	classes: HarmonySignalClass[];
+	start: number;
+	end: number;
+	text: string;
+}
+
+export interface HarmonyDetection {
+	surface: HarmonySurface;
+	contentIndex?: number;
+	toolName?: string;
+	toolCallId?: string;
+	signals: HarmonySignal[];
+}
+
+export interface HarmonyAuditEvent {
+	action: "truncate_resume" | "abort_retry" | "escalated";
+	surface: HarmonySurface;
+	signal: string;
+	retryN: number;
+	model: string;
+	provider: string;
+	toolName?: string;
+	removedLen: number;
+	removedSha8: string;
+	removedPreview: string;
+	removedBlob?: string;
+}
+
+export interface HarmonyRecoveredToolCall {
+	message: AssistantMessage;
+	removed: string;
+}
+
+/**
+ * Whether to run leak detection on responses from this model. We default-on
+ * for every openai-codex model rather than enumerating ids, so a future
+ * gpt-5.6 (or whatever) doesn't silently bypass the mitigation. Detection
+ * itself is cheap; the cost of missing a leak on a new model is not.
+ */
+export function isHarmonyLeakMitigationTarget(model: Model): boolean {
+	return model.provider === "openai-codex";
+}
+
+export function signalListLabel(signals: readonly HarmonySignal[]): string {
+	const seen: string[] = [];
+	for (const signal of signals) {
+		const label = signal.classes.join("+");
+		if (!seen.includes(label)) seen.push(label);
+	}
+	return seen.join(",") || "none";
+}
+
+/**
+ * Detect harmony-protocol leakage in `text`. Returns undefined if clean.
+ *
+ * Trip rule: `H` alone, or `M` paired with at least one co-signal
+ * (`C`/`G`/`S`/`B`/`R`/`T`). Bare `M` does not trip — this document, its
+ * tests, and bug reports legitimately carry the marker.
+ *
+ * `parsedEnd`, when supplied, marks the byte at which a structurally valid
+ * tool-argument parse ends; markers strictly after it set the `T` co-signal.
+ * `contentIndex`/`toolName`/`toolCallId` flow through to the returned
+ * detection for downstream auditing.
+ */
+export function detectHarmonyLeak(
+	text: string,
+	surface: HarmonySurface,
+	options: {
+		parsedEnd?: number;
+		contentIndex?: number;
+		toolName?: string;
+		toolCallId?: string;
+	} = {},
+): HarmonyDetection | undefined {
+	const fences = computeFenceRanges(text);
+	const signals: HarmonySignal[] = [];
+
+	for (const match of text.matchAll(HARMONY_RE)) {
+		const start = match.index ?? 0;
+		if (isInsideFence(fences, start)) continue;
+		signals.push(makeSignal(["H"], start, start + match[0].length, match[0]));
+	}
+
+	for (const match of text.matchAll(MARKER_RE)) {
+		const start = match.index ?? 0;
+		if (isInsideFence(fences, start)) continue;
+		const end = start + match[0].length;
+		const classes: HarmonySignalClass[] = ["M"];
+
+		const adjacent = text.slice(Math.max(0, start - 64), Math.min(text.length, end + 16));
+		const near = text.slice(Math.max(0, start - 16), Math.min(text.length, end + 16));
+		const forward = text.slice(start, Math.min(text.length, start + 240));
+
+		if (CHANNEL_WORD_RE.test(adjacent)) classes.push("C");
+		if (GLITCH_RE.test(near)) classes.push("G");
+		if (hasScriptMismatchNear(text, start, end)) classes.push("S");
+		if (BODY_CASCADE_RE.test(forward)) classes.push("B");
+		if (FAKE_RESULT_RE.test(forward)) classes.push("R");
+		if (options.parsedEnd !== undefined && start >= options.parsedEnd) classes.push("T");
+
+		// `M` alone never trips: legitimate documentation/tests carry it.
+		if (classes.length > 1) {
+			signals.push(makeSignal(classes, start, end, match[0]));
+		}
+	}
+
+	if (signals.length === 0) return undefined;
+	signals.sort((a, b) => a.start - b.start || a.end - b.end);
+	return {
+		surface,
+		contentIndex: options.contentIndex,
+		toolName: options.toolName,
+		toolCallId: options.toolCallId,
+		signals,
+	};
+}
+
+/** Scan an assistant message's content blocks; return the first detection. */
+export function detectHarmonyLeakInAssistantMessage(message: AssistantMessage): HarmonyDetection | undefined {
+	for (let i = 0; i < message.content.length; i++) {
+		const block = message.content[i];
+		if (block.type === "text") {
+			const d = detectHarmonyLeak(block.text, "assistant_text", { contentIndex: i });
+			if (d) return d;
+		} else if (block.type === "thinking") {
+			const d = detectHarmonyLeak(block.thinking, "assistant_thinking", { contentIndex: i });
+			if (d) return d;
+		} else if (block.type === "toolCall") {
+			const argText = getToolArgumentText(block);
+			if (argText !== undefined) {
+				const d = detectHarmonyLeak(argText, "tool_arg", {
+					contentIndex: i,
+					toolName: block.name,
+					toolCallId: block.id,
+				});
+				if (d) return d;
+			}
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Truncate a contaminated tool call at the start of the contaminated line and
+ * append the tool's recovery sentinel. Returns a recovered AssistantMessage
+ * (containing only the cleaned tool call), a synthetic continuation user
+ * message asking the model to re-issue the rest, and the removed substring
+ * for auditing. Returns undefined when the tool is not recovery-eligible or
+ * the truncation would leave nothing meaningful to dispatch.
+ *
+ * `providerPayload` is dropped from the recovered message: for Codex the
+ * encrypted reasoning blob is opaque/signed and we cannot validate that it is
+ * uncontaminated. The model re-reasons on the next turn.
+ */
+export function recoverHarmonyToolCall(
+	message: AssistantMessage,
+	detection: HarmonyDetection,
+): HarmonyRecoveredToolCall | undefined {
+	if (detection.surface !== "tool_arg" || detection.contentIndex === undefined) return undefined;
+	const block = message.content[detection.contentIndex];
+	if (!block || block.type !== "toolCall") return undefined;
+
+	const config = RECOVERY_REGISTRY[block.name];
+	if (!config) return undefined;
+
+	const input = block.arguments?.input;
+	if (typeof input !== "string") return undefined;
+	if (!config.accepts(input)) return undefined;
+
+	const offset = detection.signals[0]?.start;
+	if (offset === undefined) return undefined;
+
+	const truncated = truncateAtLineAndAppendSentinel(input, offset, config.sentinel);
+	if (truncated === undefined) return undefined;
+
+	const cleanToolCall: ToolCall = {
+		...block,
+		arguments: { ...block.arguments, input: truncated.clean },
+	};
+	const cleanMessage: AssistantMessage = {
+		...message,
+		content: [cleanToolCall],
+		// Drop encrypted reasoning blob: opaque, possibly carries the leak forward.
+		providerPayload: undefined,
+		stopReason: "toolUse",
+		errorMessage: undefined,
+	};
+	return { message: cleanMessage, removed: truncated.removed };
+}
+
+/**
+ * Return the contaminated substring from `message` for audit purposes when
+ * recovery is not applicable (abort path). Walks from the first detected
+ * signal to end-of-content within the relevant block. Returns "" if the
+ * detection cannot be resolved against the message.
+ */
+export function extractHarmonyRemoved(message: AssistantMessage, detection: HarmonyDetection): string {
+	if (detection.contentIndex === undefined) return "";
+	const block = message.content[detection.contentIndex];
+	if (!block) return "";
+	const start = detection.signals[0]?.start ?? 0;
+	if (block.type === "text") return block.text.slice(start);
+	if (block.type === "thinking") return block.thinking.slice(start);
+	if (block.type === "toolCall") {
+		const text = getToolArgumentText(block);
+		return text ? text.slice(start) : "";
+	}
+	return "";
+}
+
+export function createHarmonyAuditEvent(params: {
+	action: HarmonyAuditEvent["action"];
+	detection: HarmonyDetection;
+	model: Model;
+	retryN: number;
+	removed: string;
+}): HarmonyAuditEvent {
+	return {
+		action: params.action,
+		surface: params.detection.surface,
+		signal: signalListLabel(params.detection.signals),
+		retryN: params.retryN,
+		model: params.model.id,
+		provider: params.model.provider,
+		toolName: params.detection.toolName,
+		removedLen: params.removed.length,
+		removedSha8: sha8(params.removed),
+		removedPreview: redactedJunkPreview(params.removed),
+		removedBlob: Bun.env.OMP_HARMONY_DEBUG === "1" ? params.removed : undefined,
+	};
+}
+
+// ─── internals ──────────────────────────────────────────────────────────────
+
+function makeSignal(classes: HarmonySignalClass[], start: number, end: number, text: string): HarmonySignal {
+	if (classes[0] === "H") return { classes: ["H"], start, end, text };
+	const sorted: HarmonySignalClass[] = [];
+	for (const cls of SIGNAL_ORDER) {
+		if (classes.includes(cls)) sorted.push(cls);
+	}
+	return { classes: sorted, start, end, text };
+}
+
+/**
+ * Precompute fenced-code-block ranges once per text. Each range is a
+ * [start, end) span of bytes inside any ```/~~~ fence. O(n) once instead of
+ * O(n) per detected match.
+ */
+function computeFenceRanges(text: string): Array<[number, number]> {
+	const ranges: Array<[number, number]> = [];
+	let inFence = false;
+	let fenceStart = 0;
+	let lineStart = 0;
+	while (lineStart <= text.length) {
+		const newline = text.indexOf("\n", lineStart);
+		const lineEnd = newline === -1 ? text.length : newline;
+		const line = text.slice(lineStart, lineEnd);
+		if (FENCE_RE.test(line)) {
+			if (inFence) {
+				ranges.push([fenceStart, lineEnd]);
+				inFence = false;
+			} else {
+				fenceStart = lineStart;
+				inFence = true;
+			}
+		}
+		if (newline === -1) break;
+		lineStart = newline + 1;
+	}
+	if (inFence) ranges.push([fenceStart, text.length]);
+	return ranges;
+}
+
+function isInsideFence(ranges: Array<[number, number]>, position: number): boolean {
+	for (const [start, end] of ranges) {
+		if (position >= start && position < end) return true;
+		if (start > position) break;
+	}
+	return false;
+}
+
+function hasScriptMismatchNear(text: string, start: number, end: number): boolean {
+	const near = text.slice(Math.max(0, start - 32), Math.min(text.length, end + 32));
+	if (!SCRIPT_RUN_RE.test(near)) return false;
+	const surrounding = text.slice(Math.max(0, start - 200), Math.min(text.length, end + 200));
+	if (surrounding.length === 0) return false;
+	let ascii = 0;
+	for (let i = 0; i < surrounding.length; i++) {
+		if (surrounding.charCodeAt(i) < 128) ascii++;
+	}
+	return ascii / surrounding.length >= 0.85;
+}
+
+/**
+ * Tool-call argument text used for detection scanning. For tools whose args
+ * include a free-form `input` string we scan that directly so reported byte
+ * offsets line up with the original. For everything else we fall back to a
+ * JSON-stringified blob so detection still fires; that path's offsets are
+ * NOT meaningful for slicing the original args, but the recovery path gates
+ * on `block.arguments.input` being a string and only ever slices that.
+ */
+function getToolArgumentText(toolCall: ToolCall): string | undefined {
+	if (typeof toolCall.arguments?.input === "string") return toolCall.arguments.input;
+	try {
+		return JSON.stringify(toolCall.arguments);
+	} catch {
+		return undefined;
+	}
+}
+
+function truncateAtLineAndAppendSentinel(
+	input: string,
+	offset: number,
+	sentinel: string,
+): { clean: string; removed: string } | undefined {
+	const lineStart = offset <= 0 ? 0 : input.lastIndexOf("\n", offset - 1) + 1;
+	if (lineStart === 0) return undefined; // would cut everything
+	const head = input.slice(0, lineStart).replace(/\s+$/, "");
+	if (head.length === 0) return undefined;
+	return {
+		clean: head + sentinel,
+		removed: input.slice(lineStart),
+	};
+}
+
+function sha8(text: string): string {
+	return new Bun.CryptoHasher("sha256").update(text).digest("hex").slice(0, 8);
+}
+
+const PREVIEW_KEEP_RE = new RegExp(`[${SCRIPT_CLASS}\\s】【”“…」「、。]`, "u");
+const PREVIEW_TOKEN_RE =
+	/^(?:to=functions\.[A-Za-z_]\w*|analysis|commentary|assistant|user|system|developer|tool|changedFiles|RTLU|Jsii(?:_commentary)?|\x4aapgolly)/;
+
+/**
+ * Privacy-safe preview for the audit log: keeps marker/channel/glitch tokens,
+ * non-Latin script chars, and CJK punctuation; replaces everything else
+ * (potential source/secrets) with `·`. Sufficient to grow the glitch-token
+ * denylist from logs without exposing source content. Capped at 64 chars.
+ */
+function redactedJunkPreview(text: string): string {
+	const source = text.slice(0, 64);
+	let out = "";
+	for (let i = 0; i < source.length; ) {
+		const tok = PREVIEW_TOKEN_RE.exec(source.slice(i));
+		if (tok) {
+			out += tok[0];
+			i += tok[0].length;
+			continue;
+		}
+		const ch = source[i] ?? "";
+		out += PREVIEW_KEEP_RE.test(ch) ? ch : "·";
+		i++;
+	}
+	return out;
+}

package/src/index.ts

@@ -2,6 +2,7 @@
 export * from "./agent";
 // Loop functions
 export * from "./agent-loop";
+export * from "./harmony-leak";
 // Proxy utilities
 export * from "./proxy";
 // Thinking selectors

package/src/types.ts

@@ -14,6 +14,7 @@ import type {
 	ToolResultMessage,
 } from "@oh-my-pi/pi-ai";
 import type { Static, TSchema } from "@sinclair/typebox";
+import type { HarmonyAuditEvent } from "./harmony-leak";
 
 /** Stream function - can return sync or Promise for async config lookup */
 export type StreamFn = (
@@ -150,6 +151,11 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
 
+	/**
+	 * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
+	 */
+	onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
+
 	/**
 	 * Dynamic tool choice override, resolved per LLM call.
 	 * When set and returns a value, overrides the static `toolChoice`.
@@ -217,6 +223,9 @@ export interface AgentToolResult<T = any, _TInput = unknown> {
 	content: (TextContent | ImageContent)[];
 	// Details to be displayed in a UI or logged
 	details?: T;
+	// Marks a non-throwing failure (e.g. an aggregator catching per-entry errors).
+	// agent-loop honors this and surfaces it as a tool error on the wire.
+	isError?: boolean;
 }
 
 // Callback for streaming tool execution updates