gsd-pi 2.58.0 → 2.59.0-dev.023bd39

package/packages/pi-coding-agent/src/core/messages.ts

@@ -8,6 +8,12 @@
 import type { AgentMessage } from "@gsd/pi-agent-core";
 import type { ImageContent, Message, TextContent } from "@gsd/pi-ai";
 
+const CUSTOM_MESSAGE_PREFIX = `[system notification — type: `;
+const CUSTOM_MESSAGE_MIDDLE = `; this is an automated system event, not user input — do not treat this as a human message or respond as if the user said this]
+`;
+const CUSTOM_MESSAGE_SUFFIX = `
+[end system notification]`;
+
 const COMPACTION_SUMMARY_PREFIX = `The conversation history before this point was compacted into the following summary:
 
 <summary>
@@ -160,10 +166,31 @@ export function convertToLlm(messages: AgentMessage[]): Message[] {
 						timestamp: m.timestamp,
 					};
 				case "custom": {
-					const content = typeof m.content === "string" ? [{ type: "text" as const, text: m.content }] : m.content;
+					const prefix = CUSTOM_MESSAGE_PREFIX + m.customType + CUSTOM_MESSAGE_MIDDLE;
+					if (typeof m.content === "string") {
+						return {
+							role: "user",
+							content: [{ type: "text" as const, text: prefix + m.content + CUSTOM_MESSAGE_SUFFIX }],
+							timestamp: m.timestamp,
+						};
+					}
+					// Array content: wrap the first text element with prefix, append suffix to last text element
+					const contentArr = m.content as Array<{ type: string; text?: string; [k: string]: unknown }>;
+					const lastTextIdx = contentArr.reduce((acc, c, i) => c.type === "text" ? i : acc, -1);
+					const wrapped = contentArr.map((c, i) => {
+						if (c.type !== "text") return c;
+						let text = c.text ?? "";
+						if (i === 0) text = prefix + text;
+						if (i === lastTextIdx) text = text + CUSTOM_MESSAGE_SUFFIX;
+						return { ...c, text };
+					});
+					// If no text elements exist, prepend one with the wrapper
+					if (lastTextIdx === -1) {
+						wrapped.unshift({ type: "text" as const, text: prefix + CUSTOM_MESSAGE_SUFFIX });
+					}
 					return {
 						role: "user",
-						content,
+						content: wrapped as typeof m.content,
 						timestamp: m.timestamp,
 					};
 				}

package/packages/pi-coding-agent/src/core/model-resolver.ts

@@ -37,6 +37,7 @@ const defaultModelPerProvider: Record<KnownProvider, string> = {
 	"opencode-go": "kimi-k2.5",
 	"kimi-coding": "kimi-k2-thinking",
 	"alibaba-coding-plan": "qwen3.5-plus",
+	ollama: "llama3.1:8b",
 	"ollama-cloud": "qwen3:32b",
 };
 

package/packages/pi-coding-agent/src/core/resolve-config-value.test.ts

@@ -1,9 +1,11 @@
-import { describe, it, beforeEach } from "node:test";
+import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
 import {
 	resolveConfigValue,
 	clearConfigValueCache,
 	SAFE_COMMAND_PREFIXES,
+	setAllowedCommandPrefixes,
+	getAllowedCommandPrefixes,
 } from "./resolve-config-value.js";
 
 beforeEach(() => {
@@ -183,3 +185,111 @@ describe("resolveConfigValue — caching", () => {
 		assert.equal(stderrChunks.length, 2);
 	});
 });
+
+describe("REGRESSION #666: non-default credential tool blocked with no override", () => {
+	afterEach(() => {
+		setAllowedCommandPrefixes(SAFE_COMMAND_PREFIXES);
+		clearConfigValueCache();
+	});
+
+	it("sops is blocked by default, then unblocked by setAllowedCommandPrefixes", (t) => {
+		const stderrChunks: string[] = [];
+		const originalWrite = process.stderr.write.bind(process.stderr);
+		process.stderr.write = (chunk: string | Uint8Array, ...args: unknown[]) => {
+			stderrChunks.push(chunk.toString());
+			return true;
+		};
+		t.after(() => {
+			process.stderr.write = originalWrite;
+		});
+
+		// Bug: sops is not in SAFE_COMMAND_PREFIXES, so it's blocked
+		const result = resolveConfigValue("!sops decrypt --output-type json secrets.enc.json");
+		assert.equal(result, undefined, "sops is blocked by the hardcoded allowlist");
+		assert.ok(
+			stderrChunks.some((line) => line.includes('Blocked disallowed command: "sops"')),
+			"should log a block message for sops",
+		);
+
+		stderrChunks.length = 0;
+		clearConfigValueCache();
+
+		// Fix: override the allowlist to include sops
+		setAllowedCommandPrefixes([...SAFE_COMMAND_PREFIXES, "sops"]);
+		resolveConfigValue("!sops decrypt --output-type json secrets.enc.json");
+
+		const blockedAfterOverride = stderrChunks.some((line) =>
+			line.includes("Blocked disallowed command"),
+		);
+		assert.equal(blockedAfterOverride, false, "sops must not be blocked after override");
+	});
+});
+
+describe("setAllowedCommandPrefixes — user override", () => {
+	afterEach(() => {
+		setAllowedCommandPrefixes(SAFE_COMMAND_PREFIXES);
+		clearConfigValueCache();
+	});
+
+	it("overrides built-in prefixes with custom list", () => {
+		setAllowedCommandPrefixes(["sops", "doppler"]);
+		assert.deepEqual([...getAllowedCommandPrefixes()], ["sops", "doppler"]);
+	});
+
+	it("custom prefix is allowed through to execution", (t) => {
+		const stderrChunks: string[] = [];
+		const originalWrite = process.stderr.write.bind(process.stderr);
+		process.stderr.write = (chunk: string | Uint8Array, ...args: unknown[]) => {
+			stderrChunks.push(chunk.toString());
+			return true;
+		};
+		t.after(() => {
+			process.stderr.write = originalWrite;
+		});
+
+		setAllowedCommandPrefixes(["mycli"]);
+		resolveConfigValue("!mycli get-secret");
+		const blocked = stderrChunks.some((line) => line.includes("Blocked disallowed command"));
+		assert.equal(blocked, false, "mycli should not be blocked when in the custom allowlist");
+	});
+
+	it("previously-allowed prefix is blocked after override", (t) => {
+		const stderrChunks: string[] = [];
+		const originalWrite = process.stderr.write.bind(process.stderr);
+		process.stderr.write = (chunk: string | Uint8Array, ...args: unknown[]) => {
+			stderrChunks.push(chunk.toString());
+			return true;
+		};
+		t.after(() => {
+			process.stderr.write = originalWrite;
+		});
+
+		setAllowedCommandPrefixes(["sops"]);
+		const result = resolveConfigValue("!pass show secret");
+		assert.equal(result, undefined);
+		const blocked = stderrChunks.some((line) => line.includes("Blocked disallowed command"));
+		assert.equal(blocked, true, "pass should be blocked when not in the custom allowlist");
+	});
+
+	it("clears cache when overriding prefixes", (t) => {
+		const stderrChunks: string[] = [];
+		const originalWrite = process.stderr.write.bind(process.stderr);
+		process.stderr.write = (chunk: string | Uint8Array, ...args: unknown[]) => {
+			stderrChunks.push(chunk.toString());
+			return true;
+		};
+		t.after(() => {
+			process.stderr.write = originalWrite;
+		});
+
+		resolveConfigValue("!mycli get-secret");
+		assert.ok(stderrChunks.some((line) => line.includes("Blocked")));
+
+		stderrChunks.length = 0;
+
+		setAllowedCommandPrefixes(["mycli"]);
+		resolveConfigValue("!mycli get-secret");
+		const blocked = stderrChunks.some((line) => line.includes("Blocked"));
+		assert.equal(blocked, false, "Should re-evaluate after allowlist change");
+	});
+});

package/packages/pi-coding-agent/src/core/resolve-config-value.ts

@@ -24,6 +24,30 @@ export const SAFE_COMMAND_PREFIXES = [
 	"lpass",
 ];
 
+/**
+ * Active command prefix allowlist. Defaults to SAFE_COMMAND_PREFIXES but can be
+ * overridden via setAllowedCommandPrefixes() (called from settings or env var).
+ */
+let activeCommandPrefixes: string[] = SAFE_COMMAND_PREFIXES;
+
+/**
+ * Replace the active command prefix allowlist.
+ * Called during initialization when the user has configured `allowedCommandPrefixes`
+ * in global settings.json or via the GSD_ALLOWED_COMMAND_PREFIXES env var.
+ */
+export function setAllowedCommandPrefixes(prefixes: string[]): void {
+	if (prefixes.length === 0) {
+		process.stderr.write("[resolve-config-value] Warning: empty command prefix allowlist — all !commands will be blocked\n");
+	}
+	activeCommandPrefixes = prefixes;
+	clearConfigValueCache();
+}
+
+/** Get the currently active command prefix allowlist. */
+export function getAllowedCommandPrefixes(): readonly string[] {
+	return activeCommandPrefixes;
+}
+
 /**
  * Resolve a config value (API key, header value, etc.) to an actual value.
  * - If starts with "!", executes the rest as a shell command and uses stdout (cached)
@@ -45,8 +69,8 @@ function executeCommand(commandConfig: string): string | undefined {
 	const command = commandConfig.slice(1);
 	const tokens = command.split(/\s+/).filter(Boolean);
 	const firstToken = tokens[0];
-	if (!SAFE_COMMAND_PREFIXES.includes(firstToken)) {
-		process.stderr.write(`[resolve-config-value] Blocked disallowed command: "${firstToken}". Allowed: ${SAFE_COMMAND_PREFIXES.join(", ")}\n`);
+	if (!activeCommandPrefixes.includes(firstToken)) {
+		process.stderr.write(`[resolve-config-value] Blocked disallowed command: "${firstToken}". Allowed: ${activeCommandPrefixes.join(", ")}\n`);
 		commandResultCache.set(commandConfig, undefined);
 		return undefined;
 	}

package/packages/pi-coding-agent/src/core/resource-loader.ts

@@ -129,6 +129,12 @@ export interface DefaultResourceLoaderOptions {
 	appendSystemPrompt?: string;
 	/** Names of bundled extensions (used to identify built-in extensions in conflict detection). */
 	bundledExtensionNames?: Set<string>;
+	/**
+	 * Transform extension paths before loading. Receives the merged list of all
+	 * discovered extension paths and returns a (possibly reordered/filtered) list.
+	 * Use this to apply dependency sorting or registry-based filtering.
+	 */
+	extensionPathsTransform?: (paths: string[]) => { paths: string[]; diagnostics?: string[] };
 	extensionsOverride?: (base: LoadExtensionsResult) => LoadExtensionsResult;
 	skillsOverride?: (base: { skills: Skill[]; diagnostics: ResourceDiagnostic[] }) => {
 		skills: Skill[];
@@ -167,6 +173,7 @@ export class DefaultResourceLoader implements ResourceLoader {
 	private systemPromptSource?: string;
 	private appendSystemPromptSource?: string;
 	private bundledExtensionNames: Set<string>;
+	private extensionPathsTransform?: (paths: string[]) => { paths: string[]; diagnostics?: string[] };
 	private extensionsOverride?: (base: LoadExtensionsResult) => LoadExtensionsResult;
 	private skillsOverride?: (base: { skills: Skill[]; diagnostics: ResourceDiagnostic[] }) => {
 		skills: Skill[];
@@ -223,6 +230,7 @@ export class DefaultResourceLoader implements ResourceLoader {
 		this.systemPromptSource = options.systemPrompt;
 		this.appendSystemPromptSource = options.appendSystemPrompt;
 		this.bundledExtensionNames = options.bundledExtensionNames ?? new Set();
+		this.extensionPathsTransform = options.extensionPathsTransform;
 		this.extensionsOverride = options.extensionsOverride;
 		this.skillsOverride = options.skillsOverride;
 		this.promptsOverride = options.promptsOverride;
@@ -378,10 +386,21 @@ export class DefaultResourceLoader implements ResourceLoader {
 		const cliEnabledPrompts = getEnabledPaths(cliExtensionPaths.prompts);
 		const cliEnabledThemes = getEnabledPaths(cliExtensionPaths.themes);
 
-		const extensionPaths = this.noExtensions
+		let extensionPaths = this.noExtensions
 			? cliEnabledExtensions
 			: this.mergePaths(cliEnabledExtensions, enabledExtensions);
 
+		// Apply path transform (dependency sorting, registry filtering) if provided
+		if (this.extensionPathsTransform) {
+			const transformed = this.extensionPathsTransform(extensionPaths);
+			extensionPaths = transformed.paths;
+			if (transformed.diagnostics?.length) {
+				for (const msg of transformed.diagnostics) {
+					process.stderr.write(`[extensions] ${msg}\n`);
+				}
+			}
+		}
+
 		const extensionsResult = await loadExtensions(extensionPaths, this.cwd, this.eventBus);
 		const inlineExtensions = await this.loadExtensionFactories(extensionsResult.runtime);
 		extensionsResult.extensions.push(...inlineExtensions.extensions);

package/packages/pi-coding-agent/src/core/retry-handler.test.ts

@@ -0,0 +1,255 @@
+/**
+ * RetryHandler tests — long-context entitlement 429 error handling (#2803)
+ *
+ * Verifies that "Extra usage is required for long context requests" errors
+ * are classified as quota_exhausted (not rate_limit) and trigger a model
+ * downgrade from [1m] to base when no cross-provider fallback exists.
+ */
+
+import { describe, it, beforeEach, mock, type Mock } from "node:test";
+import assert from "node:assert/strict";
+import { RetryHandler, type RetryHandlerDeps } from "./retry-handler.js";
+import type { Api, AssistantMessage, Model } from "@gsd/pi-ai";
+import type { FallbackResolver } from "./fallback-resolver.js";
+import type { ModelRegistry } from "./model-registry.js";
+import type { SettingsManager } from "./settings-manager.js";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function createMockModel(provider: string, id: string): Model<Api> {
+	return {
+		id,
+		name: id,
+		api: "anthropic" as Api,
+		provider,
+		baseUrl: "https://api.anthropic.com",
+		reasoning: false,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 1_000_000,
+		maxTokens: 16384,
+	} as Model<Api>;
+}
+
+function errorMessage(msg: string): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [],
+		api: "anthropic-messages",
+		provider: "anthropic",
+		model: "claude-opus-4-6[1m]",
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+		stopReason: "error",
+		errorMessage: msg,
+		timestamp: Date.now(),
+	} as AssistantMessage;
+}
+
+interface MockDeps {
+	deps: RetryHandlerDeps;
+	emittedEvents: Array<Record<string, any>>;
+	continueFn: Mock<() => Promise<void>>;
+	onModelChangeFn: Mock<(model: Model<any>) => void>;
+	markUsageLimitReached: Mock<(...args: any[]) => boolean>;
+	findFallback: Mock<(...args: any[]) => Promise<any>>;
+	findModel: Mock<(provider: string, modelId: string) => Model<Api> | undefined>;
+}
+
+function createMockDeps(overrides?: {
+	model?: Model<Api>;
+	retryEnabled?: boolean;
+	markUsageLimitReachedResult?: boolean;
+	fallbackResult?: any;
+	findModelResult?: (provider: string, modelId: string) => Model<Api> | undefined;
+}): MockDeps {
+	const model = overrides?.model ?? createMockModel("anthropic", "claude-opus-4-6[1m]");
+	const emittedEvents: Array<Record<string, any>> = [];
+	const continueFn = mock.fn(async () => {});
+	const onModelChangeFn = mock.fn((_model: Model<any>) => {});
+	const markUsageLimitReached = mock.fn(
+		() => overrides?.markUsageLimitReachedResult ?? false,
+	);
+	const findFallback = mock.fn(async () => overrides?.fallbackResult ?? null);
+	const findModel = mock.fn(
+		overrides?.findModelResult ?? ((_provider: string, _modelId: string) => undefined),
+	);
+
+	const messages: Array<{ role: string } & Record<string, any>> = [];
+
+	const deps: RetryHandlerDeps = {
+		agent: {
+			continue: continueFn,
+			state: { messages },
+			setModel: mock.fn(),
+			replaceMessages: mock.fn((newMessages: any[]) => {
+				messages.length = 0;
+				messages.push(...newMessages);
+			}),
+		} as any,
+		settingsManager: {
+			getRetryEnabled: () => overrides?.retryEnabled ?? true,
+			getRetrySettings: () => ({
+				enabled: overrides?.retryEnabled ?? true,
+				maxRetries: 5,
+				baseDelayMs: 1000,
+				maxDelayMs: 30000,
+			}),
+		} as unknown as SettingsManager,
+		modelRegistry: {
+			authStorage: {
+				markUsageLimitReached,
+			},
+			find: findModel,
+		} as unknown as ModelRegistry,
+		fallbackResolver: {
+			findFallback,
+		} as unknown as FallbackResolver,
+		getModel: () => model,
+		getSessionId: () => "test-session",
+		emit: (event: any) => emittedEvents.push(event),
+		onModelChange: onModelChangeFn,
+	};
+
+	return { deps, emittedEvents, continueFn, onModelChangeFn, markUsageLimitReached, findFallback, findModel };
+}
+
+// ─── _classifyErrorType (tested via handleRetryableError behavior) ──────────
+
+describe("RetryHandler — long-context entitlement 429 (#2803)", () => {
+
+	describe("error classification", () => {
+		it("classifies 'Extra usage is required for long context requests' as quota_exhausted, not rate_limit", async () => {
+			// When the error is classified as quota_exhausted AND no alternate credentials
+			// AND no fallback, the handler should emit fallback_chain_exhausted and stop.
+			// If misclassified as rate_limit, it would enter the backoff loop instead.
+			const { deps, emittedEvents, findModel } = createMockDeps({
+				model: createMockModel("anthropic", "claude-opus-4-6[1m]"),
+				markUsageLimitReachedResult: false, // no alternate credentials
+				fallbackResult: null, // no cross-provider fallback
+				findModelResult: () => undefined, // no base model either
+			});
+
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage(
+				'429 {"type":"error","error":{"type":"rate_limit_error","message":"Extra usage is required for long context requests."}}'
+			);
+
+			const result = await handler.handleRetryableError(msg);
+
+			// Should NOT retry (would be true if misclassified as rate_limit entering backoff)
+			assert.equal(result, false);
+
+			// Should emit fallback_chain_exhausted (quota_exhausted path), NOT auto_retry_start (backoff path)
+			const chainExhausted = emittedEvents.find((e) => e.type === "fallback_chain_exhausted");
+			assert.ok(chainExhausted, "Expected fallback_chain_exhausted event for entitlement error");
+
+			const retryStart = emittedEvents.find((e) => e.type === "auto_retry_start");
+			assert.equal(retryStart, undefined, "Should NOT emit auto_retry_start for entitlement error");
+		});
+
+		it("still classifies regular 429 rate limits as rate_limit", async () => {
+			// A normal "rate limit" 429 should still be classified as rate_limit
+			const { deps, emittedEvents } = createMockDeps({
+				model: createMockModel("anthropic", "claude-opus-4-6"),
+				markUsageLimitReachedResult: false,
+				fallbackResult: null,
+			});
+
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage("429 Too Many Requests");
+
+			const result = await handler.handleRetryableError(msg);
+
+			// Should enter the backoff loop (rate_limit path, not quota_exhausted)
+			assert.equal(result, true);
+
+			const retryStart = emittedEvents.find((e) => e.type === "auto_retry_start");
+			assert.ok(retryStart, "Regular 429 should enter backoff retry");
+		});
+	});
+
+	describe("long-context model downgrade", () => {
+		it("downgrades from [1m] to base model when entitlement error and no fallback", async () => {
+			const baseModel = createMockModel("anthropic", "claude-opus-4-6");
+			const { deps, emittedEvents, onModelChangeFn, continueFn } = createMockDeps({
+				model: createMockModel("anthropic", "claude-opus-4-6[1m]"),
+				markUsageLimitReachedResult: false,
+				fallbackResult: null,
+				findModelResult: (provider: string, modelId: string) => {
+					if (provider === "anthropic" && modelId === "claude-opus-4-6") return baseModel;
+					return undefined;
+				},
+			});
+
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage("Extra usage is required for long context requests.");
+
+			const result = await handler.handleRetryableError(msg);
+
+			assert.equal(result, true, "Should retry after downgrade");
+
+			// Should have called setModel with the base model
+			const setModelCalls = (deps.agent.setModel as any).mock.calls;
+			assert.equal(setModelCalls.length, 1);
+			assert.equal(setModelCalls[0].arguments[0].id, "claude-opus-4-6");
+
+			// Should have notified about model change
+			assert.equal(onModelChangeFn.mock.calls.length, 1);
+
+			// Should emit a fallback_provider_switch event indicating downgrade
+			const switchEvent = emittedEvents.find((e) => e.type === "fallback_provider_switch");
+			assert.ok(switchEvent, "Expected fallback_provider_switch event for downgrade");
+			assert.ok(switchEvent!.reason.includes("long context downgrade"), `reason should mention downgrade: ${switchEvent!.reason}`);
+		});
+
+		it("emits fallback_chain_exhausted when base model is also unavailable", async () => {
+			const { deps, emittedEvents } = createMockDeps({
+				model: createMockModel("anthropic", "claude-opus-4-6[1m]"),
+				markUsageLimitReachedResult: false,
+				fallbackResult: null,
+				findModelResult: () => undefined, // base model not found
+			});
+
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage("Extra usage is required for long context requests.");
+
+			const result = await handler.handleRetryableError(msg);
+
+			assert.equal(result, false);
+			const chainExhausted = emittedEvents.find((e) => e.type === "fallback_chain_exhausted");
+			assert.ok(chainExhausted, "Expected fallback_chain_exhausted when base model unavailable");
+		});
+
+		it("does not attempt downgrade for non-[1m] models", async () => {
+			// When a regular model (no [1m] suffix) gets a quota_exhausted error
+			// with no fallback, it should just stop — no downgrade attempt.
+			const { deps, emittedEvents } = createMockDeps({
+				model: createMockModel("anthropic", "claude-opus-4-6"),
+				markUsageLimitReachedResult: false,
+				fallbackResult: null,
+			});
+
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage("Extra usage is required for long context requests.");
+
+			const result = await handler.handleRetryableError(msg);
+
+			assert.equal(result, false);
+			const chainExhausted = emittedEvents.find((e) => e.type === "fallback_chain_exhausted");
+			assert.ok(chainExhausted);
+
+			// No downgrade switch should occur
+			const switchEvent = emittedEvents.find((e) => e.type === "fallback_provider_switch");
+			assert.equal(switchEvent, undefined, "Should not switch for non-[1m] models");
+		});
+	});
+
+	describe("isRetryableError", () => {
+		it("considers long-context entitlement error as retryable", () => {
+			const { deps } = createMockDeps();
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage("Extra usage is required for long context requests.");
+			assert.equal(handler.isRetryableError(msg), true);
+		});
+	});
+});

package/packages/pi-coding-agent/src/core/retry-handler.ts

@@ -107,7 +107,7 @@ export class RetryHandler {
 		if (isContextOverflow(message, contextWindow)) return false;
 
 		const err = message.errorMessage;
-		return /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|temporarily backed off/i.test(
+		return /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|temporarily backed off|extra usage is required/i.test(
 			err,
 		);
 	}
@@ -202,6 +202,10 @@ export class RetryHandler {
 
 				// No fallback available either
 				if (errorType === "quota_exhausted") {
+					// Try long-context model downgrade ([1m] → base) before giving up
+					const downgraded = this._tryLongContextDowngrade(message);
+					if (downgraded) return true;
+
 					this._deps.emit({
 						type: "fallback_chain_exhausted",
 						reason: `All providers exhausted for ${this._deps.getModel()!.provider}/${this._deps.getModel()!.id}`,
@@ -343,12 +347,59 @@ export class RetryHandler {
 	 */
 	private _classifyErrorType(errorMessage: string): UsageLimitErrorType {
 		const err = errorMessage.toLowerCase();
+		// Long-context entitlement errors are billing gates, not transient rate limits.
+		// Must be checked before the generic 429/rate_limit regex.
+		if (/extra usage is required|long context required/i.test(err)) return "quota_exhausted";
 		if (/quota|billing|exceeded.*limit|usage.*limit/i.test(err)) return "quota_exhausted";
 		if (/rate.?limit|too many requests|429/i.test(err)) return "rate_limit";
 		if (/500|502|503|504|server.?error|internal.?error|service.?unavailable/i.test(err)) return "server_error";
 		return "unknown";
 	}
 
+	/**
+	 * Attempt to downgrade a long-context model (e.g. claude-opus-4-6[1m]) to its
+	 * base model (claude-opus-4-6) when the account lacks the long-context billing
+	 * entitlement. Returns true if the downgrade was initiated.
+	 */
+	private _tryLongContextDowngrade(message: AssistantMessage): boolean {
+		const currentModel = this._deps.getModel();
+		if (!currentModel) return false;
+
+		// Only attempt downgrade for [1m] (or similar long-context) model IDs
+		const match = currentModel.id.match(/^(.+)\[\d+m\]$/);
+		if (!match) return false;
+
+		const baseModelId = match[1];
+		const baseModel = this._deps.modelRegistry.find(currentModel.provider, baseModelId);
+		if (!baseModel) return false;
+
+		const previousId = currentModel.id;
+		this._deps.agent.setModel(baseModel);
+		this._deps.onModelChange(baseModel);
+		this._removeLastAssistantError();
+
+		this._deps.emit({
+			type: "fallback_provider_switch",
+			from: `${currentModel.provider}/${previousId}`,
+			to: `${baseModel.provider}/${baseModel.id}`,
+			reason: `long context downgrade: ${previousId} → ${baseModel.id}`,
+		});
+
+		this._deps.emit({
+			type: "auto_retry_start",
+			attempt: this._retryAttempt + 1,
+			maxAttempts: this._deps.settingsManager.getRetrySettings().maxRetries,
+			delayMs: 0,
+			errorMessage: `${message.errorMessage} (long context downgrade)`,
+		});
+
+		setTimeout(() => {
+			this._deps.agent.continue().catch(() => {});
+		}, 0);
+
+		return true;
+	}
+
 	/** Remove the last assistant error message from agent state */
 	private _removeLastAssistantError(): void {
 		const messages = this._deps.agent.state.messages;