@oh-my-pi/pi-coding-agent 17.1.8 → 17.2.1

package/src/edit/hashline/diff.ts

@@ -13,6 +13,7 @@ import * as path from "node:path";
 import {
 	type ApplyResult,
 	applyEdits,
+	type Clipboard,
 	type Cursor,
 	computeFileHash,
 	type Edit,
@@ -26,8 +27,10 @@ import {
 	parsePatchStreaming,
 	Recovery,
 	resolveBlockEdits,
+	resolveClipboardEdits,
 	type SnapshotStore,
 	stripBom,
+	validateClipboardSequence,
 } from "@oh-my-pi/hashline";
 import { resolveToCwd } from "../../tools/path-utils";
 import { generateDiffString } from "../diff";
@@ -48,6 +51,14 @@ export interface HashlineDiffOptions {
 	 * authoring input; the final apply path still validates through Patcher.
 	 */
 	skipHashValidation?: boolean;
+	/**
+	 * Clipboard register shared across the sections of one patch preview.
+	 * `CUT` in an earlier section feeds `PASTE` in a later one, so the preview
+	 * matches apply. Multi-section previews MUST thread one register through
+	 * sections in patch order; omitted, each section gets a
+	 * private register (same-file cut/paste still previews correctly).
+	 */
+	clipboard?: Clipboard;
 }
 
 async function readSectionText(absolutePath: string, sectionPath: string): Promise<string> {
@@ -144,6 +155,7 @@ function hasAnchorScopedEdit(edits: readonly Edit[]): boolean {
 	return edits.some(edit => {
 		if (edit.kind === "delete") return true;
 		if (edit.kind === "block") return true;
+		if (edit.kind === "cut") return true;
 		return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
 	});
 }
@@ -204,14 +216,24 @@ function applyPreviewEdits(args: {
 	const liveMatches = expected !== undefined && computeFileHash(normalized) === expected;
 	const edits = parsePreviewEdits(section, options.streaming);
 	const resolved = resolvePreviewEdits({ section, absolutePath, normalized, snapshots, expected, liveMatches, edits });
-	if (options.skipHashValidation || expected === undefined || liveMatches) return applyEdits(normalized, resolved);
-	if (!hasAnchorScopedEdit(resolved)) return applyEdits(normalized, resolved);
+	const clipboard = options.clipboard ?? {};
+	// Mirror the Patcher: surface clipboard sequencing mistakes with their
+	// targeted message before the recovery path below swallows them. Streaming
+	// previews stay lenient — a mid-typed op transiently violating sequencing
+	// must not flash an error frame.
+	if (!options.streaming) validateClipboardSequence(resolved, clipboard);
+	const applyOptions = { clipboard, ...(options.streaming ? { onEmptyPaste: "drop" as const } : {}) };
+	if (options.skipHashValidation || expected === undefined || liveMatches) {
+		return applyEdits(normalized, resolved, applyOptions);
+	}
+	if (!hasAnchorScopedEdit(resolved)) return applyEdits(normalized, resolved, applyOptions);
 
 	const recovered = new Recovery(snapshots).tryRecover({
 		path: absolutePath,
 		currentText: normalized,
 		fileHash: expected,
 		edits: resolved,
+		clipboard,
 	});
 	if (recovered) return recovered;
 	throw createMismatchError(section, absolutePath, normalized, snapshots, expected);
@@ -250,18 +272,36 @@ function insertCursorLine(cursor: Cursor, fileLineCount: number): number {
 function buildStreamingSectionDiff(
 	section: PatchSection,
 	normalized: string,
+	clipboard: Clipboard,
 ): { diff: string; firstChangedLine: number | undefined } | { error: string } {
 	const { edits, fileOp } = parsePatchStreaming(section.diff);
-	const resolved = resolveBlockEdits(edits, normalized, section.path, nativeBlockResolver, { onUnresolved: "drop" });
+	const blockResolved = resolveBlockEdits(edits, normalized, section.path, nativeBlockResolver, {
+		onUnresolved: "drop",
+	});
+	const fileLines = normalized.split("\n");
+	// Expand clipboard ops so a `PASTE` previews the moved rows. Resolve into
+	// a scratch register and commit it back only on success: a mid-typed
+	// capture (out-of-range while the range digits are still streaming,
+	// transient sequencing violations) throws AFTER earlier captures may have
+	// landed, and leaking those into the shared register would let a later
+	// section preview a paste that never happened. On failure, fall back to
+	// filtering the clipboard edits out of this section's frame.
+	const scratch: Clipboard = { ...clipboard };
+	let resolved: readonly Edit[];
+	try {
+		resolved = resolveClipboardEdits(blockResolved, fileLines, scratch, { onEmptyPaste: "drop" });
+		if (scratch.lines === undefined) delete clipboard.lines;
+		else clipboard.lines = scratch.lines;
+	} catch {
+		resolved = blockResolved.filter(edit => edit.kind !== "cut" && edit.kind !== "paste");
+	}
 	if (resolved.length === 0) {
-		// A whole-file op (REM / MV) carries no line edits: the change is the
-		// delete/move itself, conveyed by the result header, so emit an empty
-		// diff rather than a misleading "No changes" error.
+		// A whole-file op (REM / MV) carries no line edits; the result header
+		// conveys the change, so emit an empty diff.
 		if (fileOp) return { diff: "", firstChangedLine: undefined };
 		return { error: `No changes would be made to ${section.path}.` };
 	}
 
-	const fileLines = normalized.split("\n");
 	const rows: string[] = [];
 	let firstChangedLine: number | undefined;
 
@@ -323,11 +363,10 @@ export async function computeHashlineSectionDiff(
 		// diff: feed the in-flight ops through the natural-order builder so the
 		// streamed cursor stays pinned to the bottom. The args-complete pass
 		// (`streaming` unset) falls through to the real Myers diff below.
-		if (options.streaming) return buildStreamingSectionDiff(section, normalized);
+		if (options.streaming) return buildStreamingSectionDiff(section, normalized, options.clipboard ?? {});
 		const result = applyPreviewEdits({ section, absolutePath, normalized, snapshots, options });
 		if (normalized === result.text) {
-			// REM/MV-only sections change no text; the header conveys the
-			// delete/move, so don't surface a "No changes" error.
+			// REM/MV-only sections change no text; the header conveys the op.
 			if (section.fileOp) return { diff: "", firstChangedLine: undefined };
 			return { error: `No changes would be made to ${section.path}.` };
 		}

package/src/edit/hashline/execute.ts

@@ -13,6 +13,9 @@
 import {
 	type BlockResolution,
 	buildCompactDiffPreview,
+	type Clipboard,
+	commitClipboard,
+	forkClipboard,
 	MismatchError as HashlineMismatchError,
 	Patch,
 	Patcher,
@@ -25,6 +28,7 @@ import type { ToolSession } from "../../tools";
 import { outputMeta } from "../../tools/output-meta";
 import { ToolError } from "../../tools/tool-errors";
 import { generateDiffString } from "../diff";
+import { getEditClipboard } from "../edit-clipboard";
 import { getFileSnapshotStore } from "../file-snapshot-store";
 import type { EditToolDetails, EditToolPerFileResult, LspBatchRequest } from "../renderer";
 import { pruneOversizedEditSnapshots } from "../snapshot-details";
@@ -98,12 +102,24 @@ interface RenderedSection {
 	perFileResult: EditToolPerFileResult;
 }
 
+const BLOCK_OP_LABELS: Record<BlockResolution["op"], string> = {
+	replace: "SWAP.BLK",
+	insert_after: "INS.BLK.POST",
+	cut: "CUT.BLK",
+	paste_after: "PASTE.BLK.POST",
+};
+
 function formatBlockResolution(resolution: BlockResolution): string {
-	const op = resolution.op === "delete" ? "DEL.BLK" : resolution.op === "insert_after" ? "INS.BLK.POST" : "SWAP.BLK";
+	const op = BLOCK_OP_LABELS[resolution.op];
 	const lines = resolution.end - resolution.start + 1;
 	const span =
 		resolution.start === resolution.end ? `line ${resolution.start}` : `lines ${resolution.start}-${resolution.end}`;
-	const suffix = resolution.op === "insert_after" ? `; body lands after line ${resolution.end}` : "";
+	const suffix =
+		resolution.op === "insert_after"
+			? `; body lands after line ${resolution.end}`
+			: resolution.op === "paste_after"
+				? `; clipboard lands after line ${resolution.end}`
+				: "";
 	return `${op} ${resolution.anchorLine} → resolved ${span} (${lines} line${lines === 1 ? "" : "s"})${suffix}`;
 }
 
@@ -213,12 +229,19 @@ export async function executeHashlineSingle(
 	const enforceSeenLines = options.session.settings.get("edit.enforceSeenLines");
 	const patcher = new Patcher({ fs, snapshots, blockResolver: nativeBlockResolver, enforceSeenLines });
 
+	// The clipboard register is session-persistent: `CUT` in one edit call can
+	// `PASTE` in a later one. Each batch works on a fork and publishes it back
+	// only after writes land.
+	const sessionClipboard = getEditClipboard(options.session);
+	const clipboard = forkClipboard(sessionClipboard);
+
 	// Single-section fast path: prepare, commit, render.
 	const inputHash = hashPatchInput(options.input);
 	if (patch.sections.length === 1) {
 		fs.setBatchRequest(narrowBatchRequest(options.batchRequest, true));
-		const prepared = await patcher.prepare(patch.sections[0]);
+		const prepared = await patcher.prepare(patch.sections[0], clipboard);
 		const sectionResult = await patcher.commit(prepared);
+		commitClipboard(clipboard, sessionClipboard);
 		if (sectionResult.op === "noop") {
 			const { count, escalate } = recordNoopEdit(options.session, sectionResult.canonicalPath, inputHash);
 			if (escalate) {
@@ -231,9 +254,18 @@ export async function executeHashlineSingle(
 	}
 
 	// Multi-section: prepare every section up front so we fail fast before
-	// any write hits the filesystem.
+	// any write hits the filesystem. One clipboard register spans the batch,
+	// so `CUT` in one section feeds `PASTE` in a later one.
 	const prepared: PreparedSection[] = [];
-	for (const section of patch.sections) prepared.push(await patcher.prepare(section));
+	// Register state after each section's prepare. Commits are non-atomic: a
+	// mid-batch write failure leaves earlier sections on disk, so the session
+	// register must reflect exactly the landed prefix — content a landed CUT
+	// deleted would otherwise be lost.
+	const sectionStates: Clipboard[] = [];
+	for (const section of patch.sections) {
+		prepared.push(await patcher.prepare(section, clipboard));
+		sectionStates.push(forkClipboard(clipboard));
+	}
 	assertUniqueCanonicalPaths(prepared);
 	for (const entry of prepared) {
 		if (entry.isNoop) {
@@ -251,6 +283,7 @@ export async function executeHashlineSingle(
 		const isLast = i === prepared.length - 1;
 		fs.setBatchRequest(narrowBatchRequest(options.batchRequest, isLast));
 		const sectionResult = await patcher.commit(prepared[i]);
+		commitClipboard(sectionStates[i], sessionClipboard);
 		if (sectionResult.op === "noop") {
 			const { count, escalate } = recordNoopEdit(options.session, sectionResult.canonicalPath, inputHash);
 			throw escalate
@@ -260,7 +293,6 @@ export async function executeHashlineSingle(
 		resetNoopEdit(options.session, sectionResult.canonicalPath);
 		rendered.push(renderSection(sectionResult, fs.consumeDiagnostics(sectionResult.path), prepared[i].section.path));
 	}
-
 	return {
 		content: [
 			{

package/src/edit/hashline/filesystem.ts

@@ -198,9 +198,33 @@ export class HashlineFilesystem extends Filesystem {
 		const finalContent = await serializeEditFileText(absolutePath, relativePath, content);
 
 		// Route through ACP bridge when available; skips internal artifacts.
-		if (await routeWriteThroughBridge(this.session, relativePath, absolutePath, finalContent, this.#signal)) {
+		// `finalContent` is storage-space (e.g. a notebook's full JSON); the
+		// bridge may also report content that diverges from it (e.g. the
+		// client reformatted on save). `WriteResult.text` must stay in
+		// view-space — the same space `readText` returns — so a follow-up
+		// `readText` sees exactly what this write reports.
+		const bridgeResult = await routeWriteThroughBridge(
+			this.session,
+			relativePath,
+			absolutePath,
+			finalContent,
+			this.#signal,
+		);
+		if (bridgeResult) {
 			this.#diagnosticsByPath.set(relativePath, undefined);
-			return { text: finalContent };
+			if (!bridgeResult.driftedFromRequest) {
+				// No client-side transform: the view we sent is what's on disk.
+				return { text: content };
+			}
+			// Drifted (e.g. format-on-save): re-derive the view from what
+			// actually landed on disk instead of assuming `content` still
+			// matches. Falls back to `content` if the drifted file can't be
+			// re-read as a valid view (e.g. a formatter broke notebook JSON).
+			try {
+				return { text: await readEditFileText(absolutePath, relativePath) };
+			} catch {
+				return { text: content };
+			}
 		}
 
 		const diagnostics = await this.#writethrough(
@@ -213,7 +237,7 @@ export class HashlineFilesystem extends Filesystem {
 		);
 		invalidateFsScanAfterWrite(absolutePath);
 		this.#diagnosticsByPath.set(relativePath, diagnostics);
-		return { text: finalContent };
+		return { text: content };
 	}
 
 	async exists(relativePath: string): Promise<boolean> {

package/src/edit/index.ts

@@ -399,14 +399,24 @@ export class EditTool implements AgentTool<TInput> {
 	readonly #editMode?: EditMode;
 	readonly #deferredDiagnostics: DeferredDiagnostics;
 
-	constructor(private readonly session: ToolSession) {
+	/**
+	 * `mode` pins the edit variant for this instance, for callers whose protocol
+	 * fixes the shape of an edit. The Cursor `pi_edit` frame carries
+	 * `old_text`/`new_text` pairs, which only `replace` accepts — under the
+	 * default `hashline` mode those args do not match the schema at all. Left
+	 * unset, the env/settings resolution applies as before.
+	 */
+	constructor(
+		private readonly session: ToolSession,
+		mode?: EditMode,
+	) {
 		const {
 			PI_EDIT_FUZZY: editFuzzy = "auto",
 			PI_EDIT_FUZZY_THRESHOLD: editFuzzyThreshold = "auto",
 			PI_EDIT_VARIANT: envEditVariant = "auto",
 		} = Bun.env;
 
-		this.#editMode = resolveConfiguredEditMode(envEditVariant);
+		this.#editMode = mode ?? resolveConfiguredEditMode(envEditVariant);
 		this.#allowFuzzy = resolveAllowFuzzy(session, editFuzzy);
 		this.#fuzzyThreshold = resolveFuzzyThreshold(session, editFuzzyThreshold);
 		const deduplicateDiagnostics =

package/src/edit/renderer.ts

@@ -140,7 +140,7 @@ interface HashlineInputEntry {
 	path: string;
 	op?: Operation;
 	rename?: string;
-	/** A SWAP/DEL/INS line-editing op precedes the file op — keeps a move framed. */
+	/** A SWAP/CUT/INS line-editing op precedes the file op — keeps a move framed. */
 	hasLineEdits?: boolean;
 }
 
@@ -568,9 +568,9 @@ function parseHashlineInputPreviewHeader(line: string): string | null {
 	return previewPath.length > 0 ? previewPath : null;
 }
 
-// Line-editing op headers (SWAP/DEL/INS family), distinct from the file-level
-// REM/MV ops. Body rows are always `+TEXT`, so this only matches real headers.
-const HL_LINE_OP_HEADER = /^(?:SWAP|DEL|INS)\b/;
+// Line-editing op headers (SWAP/CUT/INS family), distinct from file-level
+// REM/MV ops. Body rows are `+TEXT`, so this only matches real headers.
+const HL_LINE_OP_HEADER = /^(?:SWAP|CUT|INS)\b/;
 
 /**
  * Walk a (possibly mid-stream) hashline payload into per-section descriptors:

package/src/edit/streaming.ts

@@ -16,8 +16,10 @@
 import {
 	ABORT_MARKER,
 	BEGIN_PATCH_MARKER,
+	type Clipboard,
 	containsRecognizableHashlineOperations,
 	END_PATCH_MARKER,
+	forkClipboard,
 	type PatchSection as HashlineInputSection,
 	Patch as HashlinePatch,
 	type SnapshotStore,
@@ -50,6 +52,13 @@ export interface StreamingDiffContext {
 	 * not flicker in the preview.
 	 */
 	isStreaming?: boolean;
+	/**
+	 * Session-persistent clipboard register (`CUT`/`PASTE`). Previews
+	 * fork it per frame — never mutating it — so a `PASTE` of content cut in
+	 * an earlier edit call (or an earlier section of this patch) renders the
+	 * real rows.
+	 */
+	clipboard?: Clipboard;
 }
 
 /**
@@ -411,7 +420,7 @@ const patchStrategy: EditStreamingStrategy<PatchArgs> = {
 			if (typeof edit?.diff !== "string") continue;
 			// `create` ops carry full file content in `diff` with no +/- markers;
 			// pass that content through whole.
-			const added = extractAddedLines(edit.diff, true);
+			const added = extractAddedLines(edit.diff, edit.op === "create");
 			digest = digest === undefined ? added : `${digest}\n${added}`;
 		}
 		return digest;
@@ -542,7 +551,9 @@ const hashlineStrategy: EditStreamingStrategy<HashlineArgs> = {
 			// to parse; suppress until the next chunk arrives. Once args are
 			// complete, surface the error so the model sees what went wrong.
 			if (ctx.isStreaming) return null;
-			const result = await computeHashlineDiff({ input }, ctx.cwd, ctx.snapshots);
+			const result = await computeHashlineDiff({ input }, ctx.cwd, ctx.snapshots, {
+				clipboard: forkClipboard(ctx.clipboard),
+			});
 			ctx.signal.throwIfAborted();
 			return [toPerFilePreview("", result)];
 		}
@@ -558,12 +569,16 @@ const hashlineStrategy: EditStreamingStrategy<HashlineArgs> = {
 		const trailingProcessedIndex = sectionsToProcess.length - 1;
 
 		const previews: PerFileDiffPreview[] = [];
+		// Fork the session register per preview frame: sections feed each other
+		// in patch order, but a preview must never mutate the live register.
+		const clipboard = forkClipboard(ctx.clipboard);
 		for (let i = 0; i < sectionsToProcess.length; i++) {
 			ctx.signal.throwIfAborted();
 			const section = sectionsToProcess[i];
 			const result = await computeHashlineSectionDiff(section, ctx.cwd, ctx.snapshots, {
 				streaming: ctx.isStreaming,
 				skipHashValidation: ctx.isStreaming === true,
+				clipboard,
 			});
 			ctx.signal.throwIfAborted();
 			// Ignore parse/apply errors from the trailing (actively-typed)

package/src/eval/py/prelude.py

@@ -376,10 +376,14 @@ if "__omp_prelude_loaded__" not in globals():
             raise RuntimeError("tool bridge is unavailable in this kernel")
         return (base.rstrip("/"), token, session)
 
+    import urllib.error, urllib.request
+
+    # urllib discovers environment and macOS SystemConfiguration proxies. This
+    # host-owned loopback endpoint must always connect directly.
+    _BRIDGE_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
     def _bridge_call(name: str, args: dict):
         """POST one request to the host tool bridge and return its `value`."""
-        import urllib.request, urllib.error
-
         base, token, session = _tool_proxy_from_env()
         _run_id_getter = globals().get("__omp_current_run_id__")
         _run_id = (
@@ -400,7 +404,7 @@ if "__omp_prelude_loaded__" not in globals():
             },
         )
         try:
-            with urllib.request.urlopen(req) as resp:
+            with _BRIDGE_OPENER.open(req) as resp:
                 body = resp.read()
         except urllib.error.HTTPError as exc:
             body = exc.read()

package/src/export/html/template.js

@@ -395,7 +395,7 @@
           }
 
           // Apply filter mode
-          const isSettingsEntry = ['label', 'custom', 'model_change', 'thinking_level_change', 'mode_change', 'ttsr_injection', 'session_init'].includes(entry.type);
+          const isSettingsEntry = ['label', 'custom', 'model_change', 'thinking_level_change', 'mode_change', 'ttsr_injection', 'session_init', 'credential_pin'].includes(entry.type);
           let passesFilter = true;
 
           switch (filterMode) {

package/src/extensibility/extensions/runner.ts

@@ -10,6 +10,7 @@ import type { Settings } from "../../config/settings";
 import type { LocalProtocolOptions } from "../../internal-urls/local-protocol";
 import type { MemoryRuntimeContext } from "../../memory-backend";
 import { type Theme, theme } from "../../modes/theme/theme";
+import type { AsyncJobSnapshot } from "../../session/agent-session";
 import type { SessionManager } from "../../session/session-manager";
 import type { BranchHandler, NavigateTreeHandler, NewSessionHandler } from "../session-handler-types";
 import { ManagedTimers } from "./managed-timers";
@@ -40,6 +41,7 @@ import type {
 	ExtensionUIDialogOptions,
 	InputEvent,
 	InputEventResult,
+	McpNotificationEvent,
 	MessageRenderer,
 	RegisteredCommand,
 	RegisteredTool,
@@ -218,6 +220,14 @@ async function raceHandlerWithTimeout<T>(
 
 const MAX_PENDING_CREDENTIAL_DISABLED = 32;
 
+/**
+ * Buffer cap for `mcp_notification` events received before {@link ExtensionRunner.initialize}
+ * has run. Sized to match the manager-side buffer in `MCPManager.NOTIFICATION_BUFFER_CAP` so
+ * the two layers can't drop different amounts of the same burst — the pipe drains, or it
+ * spills, but it does so consistently at both ends. Drop-oldest under pressure.
+ */
+const MAX_PENDING_MCP_NOTIFICATIONS = 100;
+
 /**
  * Events handled by the generic emit() method.
  * Events with dedicated emitXxx() methods are excluded for stronger type safety.
@@ -327,6 +337,7 @@ export class ExtensionRunner {
 	#getContextUsageFn: () => ContextUsage | undefined = () => undefined;
 	#compactFn: (instructionsOrOptions?: string | CompactOptions) => Promise<void> = async () => {};
 	#getSystemPromptFn: () => string[] = () => [];
+	#getAsyncJobSnapshotFn: () => AsyncJobSnapshot | null = () => null;
 	#newSessionHandler: NewSessionHandler = async () => ({ cancelled: false });
 	#branchHandler: BranchHandler = async () => ({ cancelled: false });
 	#navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
@@ -345,6 +356,19 @@ export class ExtensionRunner {
 	 */
 	#pendingCredentialDisabled: CredentialDisabledEvent[] = [];
 
+	/**
+	 * Buffer for `mcp_notification` events received via {@link emitMcpNotification} before
+	 * {@link initialize} has run. Two-layer race: `MCPManager` also buffers frames until
+	 * its first `addNotificationListener` subscriber attaches, but the sdk.ts bridge is
+	 * registered inside `createAgentSession` — BEFORE the mode controller calls
+	 * `ExtensionRunner.initialize()`. Without this second buffer, the manager's drain
+	 * arrives at the bridge → the bridge calls `emitMcpNotification` → the runner drops
+	 * the frame because `#initialized === false`, and the frame evaporates a second time.
+	 * Bounded at {@link MAX_PENDING_MCP_NOTIFICATIONS}; oldest entries are dropped under
+	 * pressure. Drained in {@link initialize} once the runtime/UI context is wired.
+	 */
+	#pendingMcpNotifications: Array<Omit<McpNotificationEvent, "type">> = [];
+
 	/**
 	 * Timers scheduled by extensions through the sanctioned `ctx.setInterval` /
 	 * `ctx.setTimeout` helpers. Callbacks run with the same isolation as handler
@@ -392,9 +416,11 @@ export class ExtensionRunner {
 		getMemory?: () => MemoryRuntimeContext | undefined,
 		private readonly settings?: Settings,
 		private readonly localProtocolOptions?: LocalProtocolOptions,
+		getAsyncJobSnapshot?: () => AsyncJobSnapshot | null,
 	) {
 		this.#uiContext = noOpUIContext;
 		this.#getMemoryFn = getMemory;
+		this.#getAsyncJobSnapshotFn = getAsyncJobSnapshot ?? (() => null);
 	}
 
 	initialize(
@@ -457,6 +483,23 @@ export class ExtensionRunner {
 				});
 			}
 		});
+
+		// Drain events buffered by emitMcpNotification() before initialize ran, using the
+		// same deferred-microtask ordering as the credential-disabled drain above so any
+		// onError listener registered synchronously after initialize() still catches
+		// handler errors during flush.
+		const pendingMcp = this.#pendingMcpNotifications.splice(0);
+		queueMicrotask(() => {
+			for (const event of pendingMcp) {
+				this.emit({ type: "mcp_notification", ...event }).catch((error: unknown) => {
+					logger.warn("mcp_notification handler threw during initialize flush", {
+						server: event.server,
+						method: event.method,
+						error: error instanceof Error ? error.message : String(error),
+					});
+				});
+			}
+		});
 	}
 
 	/**
@@ -484,6 +527,32 @@ export class ExtensionRunner {
 		await this.emit({ type: "credential_disabled", ...event });
 	}
 
+	/**
+	 * Forward an MCP server notification to extension handlers.
+	 *
+	 * If {@link initialize} has not yet run, the notification is buffered and replayed
+	 * once initialize wires the runtime/UI context. Matches the credential-disabled
+	 * deferral above: the sdk.ts bridge registers `MCPManager.addNotificationListener`
+	 * inside `createAgentSession` — BEFORE the mode controller calls `initialize()` on
+	 * this runner — so notification frames drained by the manager (either fresh
+	 * arrivals or replay from its own startup buffer) can reach us pre-init. Without
+	 * this buffer they would evaporate for a second time here.
+	 *
+	 * Bounded at {@link MAX_PENDING_MCP_NOTIFICATIONS}; oldest entries drop under
+	 * pressure. Never throws; per-handler errors are routed through {@link onError}
+	 * via {@link emit}'s normal isolation.
+	 */
+	async emitMcpNotification(event: Omit<McpNotificationEvent, "type">): Promise<void> {
+		if (!this.#initialized) {
+			if (this.#pendingMcpNotifications.length >= MAX_PENDING_MCP_NOTIFICATIONS) {
+				this.#pendingMcpNotifications.shift();
+			}
+			this.#pendingMcpNotifications.push(event);
+			return;
+		}
+		await this.emit({ type: "mcp_notification", ...event });
+	}
+
 	/** Emits a session stop pass that can be cancelled with the active settle signal. */
 	async emitSessionStop(event: Omit<SessionStopEvent, "type">): Promise<SessionStopEventResult | undefined> {
 		if (event.signal.aborted) return undefined;
@@ -666,6 +735,7 @@ export class ExtensionRunner {
 			ui: this.#uiContext,
 			getContextUsage: () => this.#getContextUsageFn(),
 			compact: instructionsOrOptions => this.#compactFn(instructionsOrOptions),
+			getAsyncJobSnapshot: () => this.#getAsyncJobSnapshotFn(),
 			hasUI: this.hasUI(),
 			cwd: this.cwd,
 			sessionManager: this.sessionManager,

package/src/extensibility/extensions/types.ts

@@ -49,6 +49,7 @@ import type { LocalProtocolOptions } from "../../internal-urls/local-protocol";
 import type { MemoryRuntimeContext } from "../../memory-backend";
 import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { Theme } from "../../modes/theme/theme";
+import type { AsyncJobSnapshot } from "../../session/agent-session";
 import type { CompactMode } from "../../session/compact-modes";
 import type { CustomMessage, CustomMessagePayload } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
@@ -415,6 +416,8 @@ export interface ExtensionContext {
 	ui: ExtensionUIContext;
 	/** Get current context usage for the active model. */
 	getContextUsage(): ContextUsage | undefined;
+	/** Get a read-only snapshot of async jobs owned by this session. */
+	getAsyncJobSnapshot(): AsyncJobSnapshot | null;
 	/** Compact the session context (interactive mode shows UI). */
 	compact(instructionsOrOptions?: string | CompactOptions): Promise<void>;
 	/** Whether UI is available (false in print/RPC mode) */
@@ -713,6 +716,31 @@ export interface CredentialDisabledEvent {
 	disabledCause: string;
 }
 
+// ============================================================================
+// MCP Events
+// ============================================================================
+
+/**
+ * Fired for every JSON-RPC notification received from a connected MCP server,
+ * AFTER the runtime's own handling of known list/update methods. Unknown or
+ * server-custom methods are delivered too — extensions can bridge them into
+ * session behavior by inspecting `method`/`params` and injecting a follow-up
+ * via `pi.sendMessage(..., { deliverAs })` or `pi.sendUserMessage(...)`.
+ */
+export interface McpNotificationEvent {
+	type: "mcp_notification";
+	/**
+	 * Server name as declared in the MCP config (raw, unsanitized). Note this
+	 * differs from the sanitized prefix used in `mcp__<sanitized_server>_<tool>`
+	 * tool names — filter by this raw name, not by tool-name prefix matching.
+	 */
+	server: string;
+	/** JSON-RPC method (e.g. `notifications/tools/list_changed`, or server-custom). */
+	method: string;
+	/** JSON-RPC params, opaque to the runtime. */
+	params: unknown;
+}
+
 // ============================================================================
 // User Bash Events
 // ============================================================================
@@ -941,6 +969,7 @@ export type ExtensionEvent =
 	| TodoReminderEvent
 	| GoalUpdatedEvent
 	| CredentialDisabledEvent
+	| McpNotificationEvent
 	| UserBashEvent
 	| UserPythonEvent
 	| InputEvent
@@ -1133,6 +1162,7 @@ export interface ExtensionAPI {
 	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
 	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
 	on(event: "user_python", handler: ExtensionHandler<UserPythonEvent, UserPythonEventResult>): void;
+	on(event: "mcp_notification", handler: ExtensionHandler<McpNotificationEvent>): void;
 
 	// =========================================================================
 	// Tool Registration