@oh-my-pi/pi-coding-agent 13.16.3 → 13.16.5

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [13.16.5] - 2026-03-29
+
+### Fixed
+
+- Fixed `--model provider/id` resolving to wrong provider when model ID exists in multiple catalogs ([#560](https://github.com/can1357/oh-my-pi/issues/560))
+
+## [13.16.4] - 2026-03-28
+### Changed
+
+- Renamed hashline helper functions from `hlineref`/`hlinefull` to `href`/`hline` for brevity
+- Simplified hashline edit location API: replaced separate `line` and `block` properties with unified `range` property accepting `{ pos, end }` for all range-based edits
+- Updated hashline prompt documentation to reflect new `range` syntax and clarified editing guidelines
+
+### Fixed
+
+- Added detection for `kysely-codegen` generated files in auto-generated file guard
+
 ## [13.16.1] - 2026-03-27
 
 ### Added
@@ -17,6 +34,7 @@
 - Updated grep tool description to remove ripgrep-specific implementation detail
 
 ## [13.16.0] - 2026-03-27
+
 ### Added
 
 - Implemented root path alias: bare `/` in tool inputs now resolves to the session working directory instead of the filesystem root
@@ -36,6 +54,7 @@
 - Added configurable `app.model.selectTemporary` keybinding for temporary model selection.
 
 ## [13.15.0] - 2026-03-23
+
 ### Breaking Changes
 
 - Changed hashline edit schema from flat `op`/`pos`/`end`/`lines` fields to structured `loc`/`content` format with location-specific objects
@@ -162,10 +181,10 @@
 - Fixed autoresearch logging to require durable ASI metadata (hypothesis, rollback_reason, next_action_hint) for every run including rollback context for discarded, crashed, and checks-failed experiments
 - Fixed autoresearch logging to require durable ASI metadata for every run, including rollback context for discarded, crashed, and checks-failed experiments
 
-
 ### Fixed
 
 - Fixed resumed and session-switched GitHub Copilot/OpenAI Responses conversations replaying stale assistant native history from older saved sessions by sanitizing persisted assistant replay metadata on rehydration and resetting provider session state across live session boundaries ([#505](https://github.com/can1357/oh-my-pi/issues/505))
+
 ## [13.14.0] - 2026-03-20
 
 ### Added
@@ -200,6 +219,7 @@
 - Added `mcpServerName` and `mcpToolName` optional properties to custom tools for MCP server discovery and search metadata
 
 ## [13.13.1] - 2026-03-18
+
 ### Added
 
 - Automatic deduplication of identical context files by content, keeping the closest (lowest depth) copy when duplicates are discovered
@@ -218,6 +238,7 @@
 - Enhanced auto-generated marker detection to only scan leading header comments rather than entire file prefix, improving accuracy for files with generated markers in code
 
 ## [13.12.10] - 2026-03-17
+
 ### Added
 
 - Added `args` field to ShellResult to capture the executed command
@@ -230,6 +251,7 @@
 - Updated `run()` command documentation to clarify available ShellResult fields
 
 ## [13.12.9] - 2026-03-17
+
 ### Added
 
 - Added `/session delete` command to delete current session with confirmation and return to session selector
@@ -274,6 +296,7 @@
 - Fixed session directory resolution to correctly handle symlink-equivalent paths, ensuring aliased home and temp directories resolve to the same session storage location as their real targets
 
 ## [13.12.7] - 2026-03-16
+
 ### Changed
 
 - Modified `getSelectedMCPToolNames()` to return only active MCP tools in non-discovery sessions, filtering by tool registry availability
@@ -285,6 +308,7 @@
 - Fixed MCP tool selection tracking to properly distinguish between discovery-enabled and non-discovery sessions, preventing orphaned tool selections after manual deactivation
 
 ## [13.12.6] - 2026-03-15
+
 ### Changed
 
 - Updated llama.cpp model discovery to read context window from the `/props` endpoint's `default_generation_settings.n_ctx` field instead of using hardcoded 128000 default
@@ -320,6 +344,7 @@
 - Fixed automatic migration of legacy session directories to new `-tmp-` prefixed naming scheme for temp-root sessions
 
 ## [13.12.4] - 2026-03-15
+
 ### Added
 
 - Exposed `settings` instance in `CustomToolContext` for session-specific configuration access
@@ -357,6 +382,7 @@
 - Fixed skill loading to properly respect disabled skill names when loading from custom directories
 
 ## [13.12.1] - 2026-03-15
+
 ### Added
 
 - Support for move-only operations that preserve exact bytes including binary files
@@ -396,7 +422,7 @@
 - Moved LSP settings (lsp.enabled, lsp.formatOnWrite, lsp.diagnosticsOnWrite, lsp.diagnosticsOnEdit) to the Editing tab
 - Moved bash interceptor settings to the Editing tab
 - Moved Python settings (python.toolMode, python.kernelMode, python.sharedGateway) to the Editing tab
-- Moved task delegation settings (task.isolation.*, task.eager, task.maxConcurrency, task.maxRecursionDepth) to the Tasks tab
+- Moved task delegation settings (task.isolation.\*, task.eager, task.maxConcurrency, task.maxRecursionDepth) to the Tasks tab
 - Moved skill and command settings to the Tasks tab
 - Moved provider selection settings (providers.webSearch, providers.codeSearch, providers.image, etc.) to the Providers tab
 - Moved Exa settings to the Providers tab
@@ -452,6 +478,7 @@
 - Fixed line number parsing in compact diff preview to handle variable-width line number fields with leading whitespace
 
 ## [13.11.0] - 2026-03-12
+
 ### Added
 
 - Added Parallel as a web search provider with support for fast and research modes
@@ -494,6 +521,7 @@
 - Per-role `modelRoles` thinking selectors now propagate through commit/title helper model selection, legacy commit analysis, and agentic commit sessions while preserving default thinking inheritance when no role override is configured
 
 ## [13.10.1] - 2026-03-10
+
 ### Added
 
 - Exported `submitInteractiveInput()` function for programmatic submission of user input in interactive mode
@@ -501,15 +529,19 @@
 - Added reactive 401/403 retry with automatic token refresh on HTTP MCP transports
 - Added `refreshMCPOAuthToken()` for standard OAuth 2.0 refresh_token grants
 - Persisted `tokenUrl`, `clientId`, and `clientSecret` in MCP auth config for cross-session token refresh
+
 ### Fixed
+
 - Respected `PI_CONFIG_DIR` when discovering native user config paths for slash commands and related config directories ([#349](https://github.com/can1357/oh-my-pi/issues/349))
 
 ## [13.10.0] - 2026-03-10
+
 ### Fixed
 
 - Preserved text signature metadata (id and phase) when building OpenAI native history during session compaction
 
 ## [13.9.16] - 2026-03-10
+
 ### Breaking Changes
 
 - Web search tool no longer accepts `provider` parameter in tool calls; use internal provider resolution instead
@@ -548,6 +580,7 @@
 - Fixed model selector to show discovery status messages when provider has no models
 
 ## [13.9.15] - 2026-03-10
+
 ### Added
 
 - Added `ensureLoadingAnimation()` method to manage loading animation lifecycle and prevent duplicate spinners
@@ -558,6 +591,7 @@
 - Updated `showError()` to properly clean up loading animation state when errors occur
 
 ## [13.9.12] - 2026-03-09
+
 ### Added
 
 - Added Tavily as a supported web search provider with `TAVILY_API_KEY` credential discovery and provider fallback support
@@ -575,6 +609,7 @@
 - Canonicalized bash executor working directories before handing them to brush so `pwd` stays aligned with canonical Git worktree paths in symlinked workspaces
 
 ## [13.9.10] - 2026-03-08
+
 ### Added
 
 - Added `env` parameter to bash tool to pass environment variables safely without shell re-parsing, preventing quote and special character bugs with multiline or untrusted values
@@ -586,6 +621,7 @@
 - Changed bash tool to display environment variable assignments in command preview when `env` parameter is used
 
 ## [13.9.8] - 2026-03-08
+
 ### Added
 
 - Added docs.rs scraper for extracting Rust crate documentation from rustdoc JSON, including support for modules, functions, structs, traits, enums, and other Rust items with caching
@@ -620,6 +656,7 @@
 - Updated `grep` tool to combine glob patterns from `path` and `glob` parameters instead of throwing an error when both are provided
 
 ## [13.9.4] - 2026-03-07
+
 ### Added
 
 - Automatic detection of Ollama model capabilities including reasoning/thinking support and vision input via the `/api/show` endpoint
@@ -708,6 +745,7 @@
 - Auto-corrected off-by-one range start errors in hashline edits that would duplicate preceding lines
 
 ## [13.9.0] - 2026-03-05
+
 ### Added
 
 - Added `read.defaultLimit` setting to configure default number of lines returned by read tool when no limit is specified (default: 300 lines)
@@ -736,6 +774,7 @@
 - Fixed provider session state not being cleared when branching or navigating tree history, preventing resource leaks with codex provider sessions
 
 ## [13.8.0] - 2026-03-04
+
 ### Added
 
 - Added `buildCompactHashlineDiffPreview()` function to generate compact diff previews for model-visible tool responses, collapsing long unchanged runs and consecutive additions/removals to show edit shape without full file content
@@ -751,6 +790,7 @@
 - Fixed `:thinking` suffix in `modelRoles` config values silently breaking model resolution (e.g., `slow: anthropic/claude-opus-4-6:high`) and being stripped on Ctrl+P role cycling
 
 ## [13.7.6] - 2026-03-04
+
 ### Added
 
 - Exported `dedupeParseErrors` utility function to deduplicate parse error messages while preserving order
@@ -761,7 +801,9 @@
 - Normalized parse error output in ast-grep to remove pattern-specific prefixes and show only file-level errors
 
 ## [13.7.4] - 2026-03-04
+
 ### Added
+
 - Added `fetch.useKagiSummarizer` setting to toggle Kagi Universal Summarizer usage in the fetch tool.
 
 ### Fixed
@@ -781,7 +823,7 @@
 ### Changed
 
 - Updated hashline prompt documentation with clearer operation syntax and improved examples showing full edit structure with path and edits array
-- Refactored `hlineref` Handlebars helper to return JSON-quoted strings for safer embedding in JSON blocks within prompts
+- Refactored `href` Handlebars helper to return JSON-quoted strings for safer embedding in JSON blocks within prompts
 - Improved `hashlineParseText` to correctly preserve blank lines and trailing empty strings in array input while stripping trailing newlines from string input
 - Optimized duplicate line detection in range replacements to use trimmed comparison, reducing false positives from whitespace differences
 - Refactored Kagi search provider to use shared Kagi API utilities from `web/kagi` module
@@ -792,6 +834,7 @@
 - Fixed `isEscapedTabAutocorrectEnabled` environment variable parsing to use switch statement for clearer logic and consistent default behavior
 
 ## [13.7.2] - 2026-03-04
+
 ### Added
 
 - Added support for direct OAuth provider login via `/login <provider>` command (e.g., `/login kagi`)
@@ -808,6 +851,7 @@
 - Fixed `ask` timeout handling to auto-select the recommended option instead of aborting the turn, while preserving explicit user-cancel abort behavior ([#266](https://github.com/can1357/oh-my-pi/issues/266))
 
 ## [13.6.2] - 2026-03-03
+
 ### Fixed
 
 - Fixed LM Studio API key retrieval to use configured provider name instead of hardcoded 'lm-studio'
@@ -822,7 +866,9 @@
 - Fixed `omp update` silently succeeding without actually updating the binary when the update channel (bun global vs compiled binary) doesn't match the installation method ([#247](https://github.com/can1357/oh-my-pi/issues/247))
 - Added post-update verification that checks the resolved `omp` binary reports the expected version, with actionable warnings on mismatch
 - `omp update` now detects when the `omp` in PATH is not managed by bun and falls back to binary replacement instead of updating the wrong location
+
 ## [13.6.0] - 2026-03-03
+
 ### Added
 
 - Added `mcp://` internal URL protocol for reading MCP server resources directly via the read tool (e.g., `read(path="mcp://resource-uri")`)
@@ -853,9 +899,11 @@
 - Fixed URI template matching to correctly handle expressions that expand to empty strings
 
 ## [13.5.6] - 2026-03-01
+
 ### Changed
 
 - Updated OAuth client name from 'oh-my-pi MCP' to 'Codex' for dynamic client registration
+
 ### Fixed
 
 - Fixed exit_plan_mode handler to abort active agent turn before opening plan approval selector, ensuring proper session cleanup
@@ -867,6 +915,7 @@
 - Added Kagi web search provider (Search API v0) with related searches support and automatic `KAGI_API_KEY` detection
 
 ## [13.5.4] - 2026-03-01
+
 ### Added
 
 - Added `authServerUrl` field to `AuthDetectionResult` to capture OAuth server metadata from `Mcp-Auth-Server` headers
@@ -875,6 +924,7 @@
 - Added recursive auth server discovery to follow `authorization_servers` references when discovering OAuth endpoints
 
 - Added `omp agents unpack` CLI subcommand to export bundled subagent definitions to `~/.omp/agent/agents` by default, with `--project` support for `./.omp/agents`
+
 ### Changed
 
 - Enhanced `discoverOAuthEndpoints()` to accept optional `authServerUrl` parameter and query both auth server and resource server for OAuth metadata
@@ -1569,7 +1619,7 @@
 - Updated hashline reference format from `LINE:HASH` to `LINE#ID` throughout the codebase for improved clarity
 - Renamed hashline edit operations: `set_line` → `set`, `replace_lines` → `set_range`, `insert_after` → `insert` with support for `before` and `between` anchors
 - Changed hashline edit `body` field from string to array of strings for clearer multiline handling
-- Updated handlebars helpers: renamed `hashline` to `hlineref` and added `hlinefull` for formatted line output
+- Updated handlebars helpers: renamed `hashline` to `href` and added `hline` for formatted line output
 - Improved insert operation to support `before`, `after`, and `between` (both anchors) positioning modes
 - Made autocorrect heuristics (boundary echo stripping, indent restoration) conditional on `PI_HL_AUTOCORRECT` environment variable
 - Updated SSH host discovery to load from managed omp config paths (.omp/ssh.json and ~/.omp/agent/ssh.json) in addition to legacy root-level ssh.json and .ssh.json files
@@ -1901,7 +1951,6 @@
 - Improved error reporting in fetch tool to include HTTP status codes when URL fetching fails
 - Fixed fetch tool to preserve actual response metadata (finalUrl, contentType) instead of defaults when requests fail
 
-
 ## [12.1.0] - 2026-02-13
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.16.3",
+	"version": "13.16.5",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -42,12 +42,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.16.3",
-		"@oh-my-pi/pi-agent-core": "13.16.3",
-		"@oh-my-pi/pi-ai": "13.16.3",
-		"@oh-my-pi/pi-natives": "13.16.3",
-		"@oh-my-pi/pi-tui": "13.16.3",
-		"@oh-my-pi/pi-utils": "13.16.3",
+		"@oh-my-pi/omp-stats": "13.16.5",
+		"@oh-my-pi/pi-agent-core": "13.16.5",
+		"@oh-my-pi/pi-ai": "13.16.5",
+		"@oh-my-pi/pi-natives": "13.16.5",
+		"@oh-my-pi/pi-tui": "13.16.5",
+		"@oh-my-pi/pi-utils": "13.16.5",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/config/model-registry.ts

@@ -28,6 +28,7 @@ import {
 import { isRecord, logger } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import { type ConfigError, ConfigFile } from "../config";
+import { parseModelString } from "../config/model-resolver";
 import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
 import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
 import type { Settings } from "./settings";
@@ -721,6 +722,14 @@ function buildCustomModel(
 	return finalizeCustomModel(model, options);
 }
 
+function normalizeSuppressedSelector(selector: string): string {
+	const trimmed = selector.trim();
+	if (!trimmed) return trimmed;
+	const parsed = parseModelString(trimmed);
+	if (!parsed) return trimmed;
+	return `${parsed.provider}/${parsed.id}`;
+}
+
 /**
  * Model registry - loads and manages models, resolves API keys via AuthStorage.
  */
@@ -737,6 +746,7 @@ export class ModelRegistry {
 	#registeredProviderSources: Set<string> = new Set();
 	#providerDiscoveryStates: Map<string, ProviderDiscoveryState> = new Map();
 	#cacheDbPath?: string;
+	#suppressedSelectors: Map<string, number> = new Map();
 	#backgroundRefresh?: Promise<void>;
 	#lastDiscoveryWarnings: Map<string, string> = new Map();
 
@@ -766,6 +776,7 @@ export class ModelRegistry {
 	 */
 	async refresh(strategy: ModelRefreshStrategy = "online-if-uncached"): Promise<void> {
 		this.#reloadStaticModels();
+		this.#suppressedSelectors.clear();
 		await this.#refreshRuntimeDiscoveries(strategy);
 	}
 
@@ -789,6 +800,11 @@ export class ModelRegistry {
 
 	async refreshProvider(providerId: string, strategy: ModelRefreshStrategy = "online"): Promise<void> {
 		this.#reloadStaticModels();
+		for (const selector of this.#suppressedSelectors.keys()) {
+			if (selector.startsWith(`${providerId}/`)) {
+				this.#suppressedSelectors.delete(selector);
+			}
+		}
 		await this.#refreshRuntimeDiscoveries(strategy, new Set([providerId]));
 	}
 
@@ -1825,6 +1841,27 @@ export class ModelRegistry {
 			});
 		}
 	}
+
+	/**
+	 * Suppress a specific model selector (e.g., "provider/id") until a specific timestamp.
+	 */
+	suppressSelector(selector: string, untilMs: number): void {
+		this.#suppressedSelectors.set(normalizeSuppressedSelector(selector), untilMs);
+	}
+
+	/**
+	 * Check if a model selector is currently suppressed due to rate limits.
+	 */
+	isSelectorSuppressed(selector: string): boolean {
+		const normalizedSelector = normalizeSuppressedSelector(selector);
+		const suppressedUntil = this.#suppressedSelectors.get(normalizedSelector);
+		if (!suppressedUntil) return false;
+		if (suppressedUntil <= Date.now()) {
+			this.#suppressedSelectors.delete(normalizedSelector);
+			return false;
+		}
+		return true;
+	}
 }
 
 /**

package/src/config/model-resolver.ts

@@ -730,9 +730,24 @@ export function resolveCliModel(options: {
 
 	if (!provider) {
 		const lower = cliModel.toLowerCase();
-		const exact = availableModels.find(
-			model => model.id.toLowerCase() === lower || `${model.provider}/${model.id}`.toLowerCase() === lower,
-		);
+		// When input has provider/id format (e.g. "zai/glm-5"), prefer decomposed
+		// provider+id match over flat id match. Without this, a model with id
+		// "zai/glm-5" on provider "vercel-ai-gateway" wins over provider "zai"
+		// with id "glm-5", because Array.find returns the first catalog hit.
+		const slashIdx = lower.indexOf("/");
+		let exact: (typeof availableModels)[number] | undefined;
+		if (slashIdx !== -1) {
+			const prefix = lower.substring(0, slashIdx);
+			const suffix = lower.substring(slashIdx + 1);
+			exact = availableModels.find(
+				model => model.provider.toLowerCase() === prefix && model.id.toLowerCase() === suffix,
+			);
+		}
+		if (!exact) {
+			exact = availableModels.find(
+				model => model.id.toLowerCase() === lower || `${model.provider}/${model.id}`.toLowerCase() === lower,
+			);
+		}
 		if (exact) {
 			return { model: exact, warning: undefined, thinkingLevel: undefined, error: undefined };
 		}

package/src/config/prompt-templates.ts

@@ -258,19 +258,19 @@ function formatHashlineRef(lineNum: unknown, content: unknown): { num: number; t
 }
 
 /**
- * {{hlineref lineNum "content"}} — compute a real hashline ref for prompt examples.
+ * {{href lineNum "content"}} — compute a real hashline ref for prompt examples.
  * Returns `"lineNum#hash"` using the actual hash algorithm.
  */
-handlebars.registerHelper("hlineref", (lineNum: unknown, content: unknown): string => {
+handlebars.registerHelper("href", (lineNum: unknown, content: unknown): string => {
 	const { ref } = formatHashlineRef(lineNum, content);
 	return JSON.stringify(ref);
 });
 
 /**
- * {{hlinefull lineNum "content"}} — format a full read-style line with prefix.
+ * {{hline lineNum "content"}} — format a full read-style line with prefix.
  * Returns `"lineNum#hash:content"`.
  */
-handlebars.registerHelper("hlinefull", (lineNum: unknown, content: unknown): string => {
+handlebars.registerHelper("hline", (lineNum: unknown, content: unknown): string => {
 	const { ref, text } = formatHashlineRef(lineNum, content);
 	return `${ref}:${text}`;
 });

package/src/config/settings-schema.ts

@@ -525,6 +525,18 @@ export const SETTINGS_SCHEMA = {
 	},
 
 	"retry.baseDelayMs": { type: "number", default: 2000 },
+	"retry.fallbackChains": { type: "record", default: {} as Record<string, string[]> },
+	"retry.fallbackRevertPolicy": {
+		type: "enum",
+		values: ["cooldown-expiry", "never"] as const,
+		default: "cooldown-expiry",
+		ui: {
+			tab: "model",
+			label: "Fallback Revert Policy",
+			description: "When to return to the primary model after a fallback",
+			submenu: true,
+		},
+	},
 
 	// ────────────────────────────────────────────────────────────────────────
 	// Interaction

package/src/extensibility/skills.ts

@@ -54,7 +54,7 @@ export async function loadSkillsFromDir(options: LoadSkillsFromDirOptions): Prom
 			name: capSkill.name,
 			description: typeof capSkill.frontmatter?.description === "string" ? capSkill.frontmatter.description : "",
 			filePath: capSkill.path,
-			baseDir: capSkill.path.replace(/\/SKILL\.md$/, ""),
+			baseDir: capSkill.path.replace(/[\\/]SKILL\.md$/, ""),
 			source: options.source,
 			_source: capSkill._source,
 		})),
@@ -168,7 +168,7 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 				name: capSkill.name,
 				description: typeof capSkill.frontmatter?.description === "string" ? capSkill.frontmatter.description : "",
 				filePath: capSkill.path,
-				baseDir: capSkill.path.replace(/\/SKILL\.md$/, ""),
+				baseDir: capSkill.path.replace(/[\\/]SKILL\.md$/, ""),
 				source: `${capSkill._source.provider}:${capSkill.level}`,
 				_source: capSkill._source,
 			});
@@ -204,7 +204,7 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 					description:
 						typeof capSkill.frontmatter?.description === "string" ? capSkill.frontmatter.description : "",
 					filePath: capSkill.path,
-					baseDir: capSkill.path.replace(/\/SKILL\.md$/, ""),
+					baseDir: capSkill.path.replace(/[\\/]SKILL\.md$/, ""),
 					source: "custom:user",
 					_source: { ...capSkill._source, providerName: "Custom" },
 				},

package/src/modes/components/settings-defs.ts

@@ -117,6 +117,15 @@ const OPTION_PROVIDERS: Partial<Record<SettingPath, OptionProvider>> = {
 		{ value: "5", label: "5 retries" },
 		{ value: "10", label: "10 retries" },
 	],
+	// Retry fallback revert policy
+	"retry.fallbackRevertPolicy": [
+		{
+			value: "cooldown-expiry",
+			label: "Cooldown expiry",
+			description: "Return to the primary model after its suppression window ends",
+		},
+		{ value: "never", label: "Never", description: "Stay on the fallback model until manually changed" },
+	],
 	// Task max concurrency
 	"task.maxConcurrency": [
 		{ value: "0", label: "Unlimited" },

package/src/modes/controllers/event-controller.ts

@@ -534,6 +534,16 @@ export class EventController {
 				break;
 			}
 
+			case "retry_fallback_applied": {
+				this.ctx.showWarning(`Fallback: ${event.from} -> ${event.to}`);
+				break;
+			}
+
+			case "retry_fallback_succeeded": {
+				this.ctx.showStatus(`Fallback succeeded on ${event.model}`);
+				break;
+			}
+
 			case "ttsr_triggered": {
 				const component = new TtsrNotificationComponent(event.rules);
 				component.setExpanded(this.ctx.toolOutputExpanded);

package/src/modes/interactive-mode.ts

@@ -306,6 +306,11 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		const startupQuiet = settings.get("startup.quiet");
 
+		for (const warning of this.session.configWarnings) {
+			this.ui.addChild(new Text(theme.fg("warning", `Warning: ${warning}`), 1, 0));
+			this.ui.addChild(new Spacer(1));
+		}
+
 		if (!startupQuiet) {
 			// Add welcome header
 			const welcome = new WelcomeComponent(this.#version, modelName, providerName, recentSessions, lspServerInfo);

package/src/patch/index.ts

@@ -187,12 +187,9 @@ const locSchema = Type.Union(
 		Type.Object({ append: Type.String({ description: "anchor" }) }),
 		Type.Object({ prepend: Type.String({ description: "anchor" }) }),
 		Type.Object({
-			line: Type.String({ description: "anchor" }),
-		}),
-		Type.Object({
-			block: Type.Object({
-				pos: Type.String({ description: "anchor" }),
-				end: Type.String({ description: "limit position" }),
+			range: Type.Object({
+				pos: Type.String({ description: "first line to edit (inclusive)" }),
+				end: Type.String({ description: "last line to edit (inclusive)" }),
 			}),
 		}),
 	],
@@ -231,8 +228,7 @@ export type HashlineParams = Static<typeof hashlineEditParamsSchema>;
  * loc can be:
  *   - "append" / "prepend" — file-level insert
  *   - { append: anchor } / { prepend: anchor } — insert relative to anchor
- *   - { replace_line: anchor } — replace one line
- *   - { replace_block: { pos, end } } — replace inclusive range
+ *   - { range: { pos, end } } — replace inclusive range
  */
 function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
 	const result: HashlineEdit[] = [];
@@ -253,17 +249,13 @@ function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
 				const anchor = tryParseTag(loc.prepend);
 				if (!anchor) throw new Error("prepend requires a valid anchor.");
 				result.push({ op: "prepend_at", pos: anchor, lines });
-			} else if ("line" in loc) {
-				const anchor = tryParseTag(loc.line);
-				if (!anchor) throw new Error("line requires a valid anchor.");
-				result.push({ op: "replace_line", pos: anchor, lines });
-			} else if ("block" in loc) {
-				const posAnchor = tryParseTag(loc.block.pos);
-				const endAnchor = tryParseTag(loc.block.end);
-				if (!posAnchor || !endAnchor) throw new Error("block requires valid pos and end anchors.");
+			} else if ("range" in loc) {
+				const posAnchor = tryParseTag(loc.range.pos);
+				const endAnchor = tryParseTag(loc.range.end);
+				if (!posAnchor || !endAnchor) throw new Error("range requires valid pos and end anchors.");
 				result.push({ op: "replace_range", pos: posAnchor, end: endAnchor, lines });
 			} else {
-				throw new Error("Unknown loc shape. Expected append, prepend, line, or block.");
+				throw new Error("Unknown loc shape. Expected append, prepend, or range.");
 			}
 		} else {
 			throw new Error(`Invalid loc value: ${JSON.stringify(loc)}`);

package/src/patch/shared.ts

@@ -164,9 +164,8 @@ function formatStreamingHashlineEdits(edits: Partial<HashlineToolEdit>[], uiThem
 			return { srcLabel: `• ${loc} (file-level)`, dst: contentLines };
 		}
 		if (typeof loc === "object" && loc) {
-			if ("block" in loc && typeof loc.block === "object" && loc.block) {
-				const rb = loc.block as { pos?: string; end?: string };
-				return { srcLabel: `• block ${rb.pos ?? "?"}…${rb.end ?? "?"}`, dst: contentLines };
+			if ("range" in loc && typeof loc.range === "object" && loc.range) {
+				return { srcLabel: `• range ${loc.range.pos ?? "?"}…${loc.range.end ?? "?"}`, dst: contentLines };
 			}
 			if ("line" in loc) {
 				return { srcLabel: `• line ${(loc as { line: string }).line}`, dst: contentLines };

package/src/prompts/tools/bash.md

@@ -30,10 +30,10 @@ You **MUST** use specialized tools instead of bash for ALL file operations:
 |---|---|
 |`cat file`, `head -n N file`|`read(path="file", limit=N)`|
 |`cat -n file \|sed -n '50,150p'`|`read(path="file", offset=50, limit=100)`|
-|`grep -A 20 'pat' file`|`grep(pattern="pat", path="file", post=20)`|
+{{#if hasGrep}}|`grep -A 20 'pat' file`|`grep(pattern="pat", path="file", post=20)`|
 |`grep -rn 'pat' dir/`|`grep(pattern="pat", path="dir/")`|
-|`rg 'pattern' dir/`|`grep(pattern="pattern", path="dir/")`|
-|`find dir -name '*.ts'`|`find(pattern="dir/**/*.ts")`|
+|`rg 'pattern' dir/`|`grep(pattern="pattern", path="dir/")`|{{/if}}
+{{#if hasFind}}|`find dir -name '*.ts'`|`find(pattern="dir/**/*.ts")`|{{/if}}
 |`ls dir/`|`read(path="dir/")`|
 |`cat <<'EOF' > file`|`write(path="file", content="…")`|
 |`sed -i 's/old/new/' file`|`edit(path="file", edits=[…])`|

package/src/prompts/tools/hashline.md

@@ -16,40 +16,39 @@ Read the file first. Copy anchors exactly from the latest `read` output. In one
 **`loc` values**
 - `"append"` / `"prepend"` — insert at end/start of file
 - `{ append: "N#ID" }` / `{ prepend: "N#ID" }` — insert after/before anchored line
-- `{ line: "N#ID" }` — replace exactly one anchored line
-- `{ block: { pos: "N#ID", end: "N#ID" } }` — replace inclusive `pos..end`
-</operations>
+- `{ range: { pos: "N#ID", end: "N#ID" } }` — replace inclusive range of lines `pos..end` with new content
+  </operations>
 
 <examples>
-All examples below reference the same file, `util.ts`:
-```ts
-{{hlinefull  1 "// @ts-ignore"}}
-{{hlinefull  2 "const timeout = 5000;"}}
-{{hlinefull  3 "const tag = \"DO NOT SHIP\";"}}
-{{hlinefull  4 ""}}
-{{hlinefull  5 "function alpha() {"}}
-{{hlinefull  6 "\tlog();"}}
-{{hlinefull  7 "}"}}
-{{hlinefull  8 ""}}
-{{hlinefull  9 "function beta() {"}}
-{{hlinefull 10 "\t// TODO: remove after migration"}}
-{{hlinefull 11 "\tlegacy();"}}
-{{hlinefull 12 "\ttry {"}}
-{{hlinefull 13 "\t\treturn parse(data);"}}
-{{hlinefull 14 "\t} catch (err) {"}}
-{{hlinefull 15 "\t\tconsole.error(err);"}}
-{{hlinefull 16 "\t\treturn null;"}}
-{{hlinefull 17 "\t}"}}
-{{hlinefull 18 "}"}}
+All examples below reference the same file:
+```ts title="a.ts"
+{{hline  1 "// @ts-ignore"}}
+{{hline  2 "const timeout = 5000;"}}
+{{hline  3 "const tag = \"DO NOT SHIP\";"}}
+{{hline  4 ""}}
+{{hline  5 "function alpha() {"}}
+{{hline  6 "\tlog();"}}
+{{hline  7 "}"}}
+{{hline  8 ""}}
+{{hline  9 "function beta() {"}}
+{{hline 10 "\t// TODO: remove after migration"}}
+{{hline 11 "\tlegacy();"}}
+{{hline 12 "\ttry {"}}
+{{hline 13 "\t\treturn parse(data);"}}
+{{hline 14 "\t} catch (err) {"}}
+{{hline 15 "\t\tconsole.error(err);"}}
+{{hline 16 "\t\treturn null;"}}
+{{hline 17 "\t}"}}
+{{hline 18 "}"}}
 ```
 
 <example name="replace a block body">
 Replace only the catch body. Do not target the shared boundary line `} catch (err) {`.
 ```
 {
-  path: "util.ts",
+  path: "a.ts",
   edits: [{
-    loc: { block: { pos: {{hlineref 15 "\t\tconsole.error(err);"}}, end: {{hlineref 16 "\t\treturn null;"}} } },
+    loc: { range: { pos: {{href 15 "\t\tconsole.error(err);"}}, end: {{href 16 "\t\treturn null;"}} } },
     content: [
       "\t\tif (isEnoent(err)) return null;",
       "\t\tthrow err;"
@@ -60,12 +59,12 @@ Replace only the catch body. Do not target the shared boundary line `} catch (er
 </example>
 
 <example name="replace whole block including closing brace">
-Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be {{hlineref 7 "}"}} because `content` includes `}`.
+Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be {{href 7 "}"}} because `content` includes `}`.
 ```
 {
-  path: "util.ts",
+  path: "a.ts",
   edits: [{
-    loc: { block: { pos: {{hlineref 6 "\tlog();"}}, end: {{hlineref 7 "}"}} } },
+    loc: { range: { pos: {{href 6 "\tlog();"}}, end: {{href 7 "}"}} } },
     content: [
       "\tvalidate();",
       "\tlog();",
@@ -74,15 +73,15 @@ Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be
   }]
 }
 ```
-**Wrong**: using `end: {{hlineref 6 "\tlog();"}}` with the same content — line 7 (`}`) survives the replacement AND content emits `}`, producing two closing braces.
+**Wrong**: using `end: {{href 6 "\tlog();"}}` with the same content — line 7 (`}`) survives the replacement AND content emits `}`, producing two closing braces.
 </example>
 
 <example name="replace one line">
 ```
 {
-  path: "util.ts",
+  path: "a.ts",
   edits: [{
-    loc: { line: {{hlineref 2 "const timeout = 5000;"}} },
+    loc: { range: { pos: {{href 2 "const timeout = 5000;"}}, end: {{href 2 "const timeout = 5000;"}} } },
     content: ["const timeout = 30_000;"]
   }]
 }
@@ -92,9 +91,9 @@ Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be
 <example name="delete a range">
 ```
 {
-  path: "util.ts",
+  path: "a.ts",
   edits: [{
-    loc: { block: { pos: {{hlineref 10 "\t// TODO: remove after migration"}}, end: {{hlineref 11 "\tlegacy();"}} } },
+    loc: { range: { pos: {{href 10 "\t// TODO: remove after migration"}}, end: {{href 11 "\tlegacy();"}} } },
     content: null
   }]
 }
@@ -105,9 +104,9 @@ Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be
 When adding a sibling declaration, prefer `prepend` on the next declaration.
 ```
 {
-  path: "util.ts",
+  path: "a.ts",
   edits: [{
-    loc: { prepend: {{hlineref 9 "function beta() {"}} },
+    loc: { prepend: {{href 9 "function beta() {"}} },
     content: [
       "function gamma() {",
       "\tvalidate();",
@@ -123,10 +122,10 @@ When adding a sibling declaration, prefer `prepend` on the next declaration.
 <critical>
 - Make the minimum exact edit. Do not rewrite nearby code unless the consumed range requires it.
 - Use anchors exactly as `N#ID` from the latest `read` output.
-- `block` requires both `pos` and `end`. Other anchored ops require one anchor.
+- `range` requires both `pos` and `end`.
 - When your replacement `content` ends with a closing delimiter (`}`, `*/`, `)`, `]`), verify `end` includes the original line carrying that delimiter. If `end` stops one line too early, the original delimiter survives and your content adds a second copy.
 - **Self-check**: compare the last line of `content` with the line immediately after `end` in the file. If they match (e.g., both are `}`), extend `end` to include that line.
-- For a block, either replace only the body or replace the whole block. Do not split block boundaries.
+- For a range, either replace only the body or replace the whole range. Do not split range boundaries.
 - `content` must be literal file content with matching indentation. If the file uses tabs, use real tabs.
-- Do not use this tool to reformat or clean up unrelated code.
-</critical>
+- You **MUST NOT** use this tool to reformat or clean up unrelated code. **ALWAYS** use project-specific tooling like linters or code formatters which are much more efficient and reliable.
+  </critical>

package/src/session/agent-session.ts

@@ -55,7 +55,12 @@ import { abortableSleep, getAgentDbPath, isEnoent, logger } from "@oh-my-pi/pi-u
 import type { AsyncJob, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
 import { MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
-import { extractExplicitThinkingSelector, parseModelString, resolveModelRoleValue } from "../config/model-resolver";
+import {
+	extractExplicitThinkingSelector,
+	formatModelString,
+	parseModelString,
+	resolveModelRoleValue,
+} from "../config/model-resolver";
 import { expandPromptTemplate, type PromptTemplate, renderPromptTemplate } from "../config/prompt-templates";
 import type { Settings, SkillsSettings } from "../config/settings";
 import { type BashResult, executeBash as executeBashCommand } from "../exec/bash-executor";
@@ -170,6 +175,8 @@ export type AgentSessionEvent =
 	  }
 	| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
 	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
+	| { type: "retry_fallback_applied"; from: string; to: string; role: string }
+	| { type: "retry_fallback_succeeded"; model: string; role: string }
 	| { type: "ttsr_triggered"; rules: Rule[] }
 	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
 	| { type: "todo_auto_clear" };
@@ -315,6 +322,46 @@ interface HandoffOptions {
 
 const AUTO_HANDOFF_THRESHOLD_FOCUS = renderPromptTemplate(autoHandoffThresholdFocusPrompt);
 
+type RetryFallbackChains = Record<string, string[]>;
+
+type RetryFallbackRevertPolicy = "never" | "cooldown-expiry";
+
+interface RetryFallbackSelector {
+	raw: string;
+	provider: string;
+	id: string;
+	thinkingLevel: ThinkingLevel | undefined;
+}
+
+interface ActiveRetryFallbackState {
+	role: string;
+	originalSelector: string;
+	originalThinkingLevel: ThinkingLevel | undefined;
+	lastAppliedFallbackThinkingLevel: ThinkingLevel | undefined;
+}
+
+function parseRetryFallbackSelector(selector: string): RetryFallbackSelector | undefined {
+	const trimmed = selector.trim();
+	if (!trimmed) return undefined;
+	const parsed = parseModelString(trimmed);
+	if (!parsed) return undefined;
+	return {
+		raw: trimmed,
+		provider: parsed.provider,
+		id: parsed.id,
+		thinkingLevel: parsed.thinkingLevel,
+	};
+}
+
+function formatRetryFallbackSelector(model: Model, thinkingLevel: ThinkingLevel | undefined): string {
+	const selector = formatModelString(model);
+	return thinkingLevel ? `${selector}:${thinkingLevel}` : selector;
+}
+
+function formatRetryFallbackBaseSelector(selector: RetryFallbackSelector): string {
+	return `${selector.provider}/${selector.id}`;
+}
+
 const noOpUIContext: ExtensionUIContext = {
 	select: async (_title, _options, _dialogOptions) => undefined,
 	confirm: async (_title, _message, _dialogOptions) => false,
@@ -352,6 +399,7 @@ export class AgentSession {
 	readonly sessionManager: SessionManager;
 	readonly settings: Settings;
 	readonly searchDb: SearchDb | undefined;
+	readonly configWarnings: string[] = [];
 
 	#asyncJobManager: AsyncJobManager | undefined = undefined;
 	#scopedModels: Array<{ model: Model; thinkingLevel?: ThinkingLevel }>;
@@ -391,7 +439,7 @@ export class AgentSession {
 	#retryAttempt = 0;
 	#retryPromise: Promise<void> | undefined = undefined;
 	#retryResolve: (() => void) | undefined = undefined;
-
+	#activeRetryFallback: ActiveRetryFallbackState | undefined = undefined;
 	// Todo completion reminder state
 	#todoReminderCount = 0;
 	#todoPhases: TodoPhase[] = [];
@@ -478,6 +526,7 @@ export class AgentSession {
 		this.#customCommands = config.customCommands ?? [];
 		this.#skillsSettings = config.skillsSettings;
 		this.#modelRegistry = config.modelRegistry;
+		this.#validateRetryFallbackChains();
 		this.#toolRegistry = config.toolRegistry ?? new Map();
 		this.#transformContext = config.transformContext ?? (messages => messages);
 		this.#onPayload = config.onPayload;
@@ -787,6 +836,13 @@ export class AgentSession {
 					assistantMsg.stopReason !== "aborted" &&
 					this.#retryAttempt > 0
 				) {
+					if (this.#activeRetryFallback && this.model) {
+						await this.#emitSessionEvent({
+							type: "retry_fallback_succeeded",
+							model: formatRetryFallbackSelector(this.model, this.thinkingLevel),
+							role: this.#activeRetryFallback.role,
+						});
+					}
 					await this.#emitSessionEvent({
 						type: "auto_retry_end",
 						success: true,
@@ -985,6 +1041,7 @@ export class AgentSession {
 					return;
 				}
 				try {
+					await this.#maybeRestoreRetryFallbackPrimary();
 					await this.agent.continue();
 				} catch {
 					options?.onError?.();
@@ -2288,6 +2345,8 @@ export class AgentSession {
 			// Reset todo reminder count on new user prompt
 			this.#todoReminderCount = 0;
 
+			await this.#maybeRestoreRetryFallbackPrimary();
+
 			// Validate model
 			if (!this.model) {
 				throw new Error(
@@ -3108,6 +3167,7 @@ export class AgentSession {
 			throw new Error(`No API key for ${model.provider}/${model.id}`);
 		}
 
+		this.#clearActiveRetryFallback();
 		this.#setModelWithProviderSessionReset(model);
 		this.sessionManager.appendModelChange(`${model.provider}/${model.id}`, role);
 		this.settings.setModelRole(role, this.#formatRoleModelValue(role, model));
@@ -3128,6 +3188,7 @@ export class AgentSession {
 			throw new Error(`No API key for ${model.provider}/${model.id}`);
 		}
 
+		this.#clearActiveRetryFallback();
 		this.#setModelWithProviderSessionReset(model);
 		this.sessionManager.appendModelChange(`${model.provider}/${model.id}`, "temporary");
 		this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
@@ -3253,6 +3314,7 @@ export class AgentSession {
 		const next = scopedModels[nextIndex];
 
 		// Apply model
+		this.#clearActiveRetryFallback();
 		this.#setModelWithProviderSessionReset(next.model);
 		this.sessionManager.appendModelChange(`${next.model.provider}/${next.model.id}`);
 		this.settings.setModelRole("default", this.#formatRoleModelValue("default", next.model));
@@ -3281,11 +3343,11 @@ export class AgentSession {
 			throw new Error(`No API key for ${nextModel.provider}/${nextModel.id}`);
 		}
 
+		this.#clearActiveRetryFallback();
 		this.#setModelWithProviderSessionReset(nextModel);
 		this.sessionManager.appendModelChange(`${nextModel.provider}/${nextModel.id}`);
 		this.settings.setModelRole("default", this.#formatRoleModelValue("default", nextModel));
 		this.settings.getStorage()?.recordModelUsage(`${nextModel.provider}/${nextModel.id}`);
-
 		// Re-apply the current thinking level for the newly selected model
 		this.setThinkingLevel(this.thinkingLevel);
 
@@ -4768,6 +4830,217 @@ export class AgentSession {
 		);
 	}
 
+	#getRetryFallbackChains(): RetryFallbackChains {
+		const configuredChains = this.settings.get("retry.fallbackChains");
+		if (!configuredChains || typeof configuredChains !== "object") return {};
+		return configuredChains as RetryFallbackChains;
+	}
+
+	#validateRetryFallbackChains(): void {
+		const configuredChains = this.settings.get("retry.fallbackChains");
+		if (configuredChains === undefined) return;
+		if (!configuredChains || typeof configuredChains !== "object" || Array.isArray(configuredChains)) {
+			const msg = "retry.fallbackChains must be a mapping of role names to selector arrays.";
+			logger.warn(msg);
+			this.configWarnings.push(msg);
+			return;
+		}
+
+		for (const [role, chain] of Object.entries(configuredChains)) {
+			if (!Array.isArray(chain)) {
+				const msg = `Fallback chain for role '${role}' must be an array of selector strings.`;
+				logger.warn(msg);
+				this.configWarnings.push(msg);
+				continue;
+			}
+			for (const selectorStr of chain) {
+				if (typeof selectorStr !== "string") {
+					const msg = `Fallback chain for role '${role}' contains a non-string selector.`;
+					logger.warn(msg);
+					this.configWarnings.push(msg);
+					continue;
+				}
+				const parsed = parseRetryFallbackSelector(selectorStr);
+				if (!parsed) {
+					const msg = `Invalid fallback selector format in role '${role}': ${selectorStr}`;
+					logger.warn(msg);
+					this.configWarnings.push(msg);
+					continue;
+				}
+				const exists = this.#modelRegistry.find(parsed.provider, parsed.id);
+				if (!exists) {
+					const msg = `Fallback chain for role '${role}' references unknown model: ${selectorStr}`;
+					logger.warn(msg);
+					this.configWarnings.push(msg);
+				}
+			}
+		}
+	}
+
+	#getRetryFallbackRevertPolicy(): RetryFallbackRevertPolicy {
+		return this.settings.get("retry.fallbackRevertPolicy") === "never" ? "never" : "cooldown-expiry";
+	}
+
+	#getRetryFallbackPrimarySelector(role: string): RetryFallbackSelector | undefined {
+		const configuredSelector = this.settings.getModelRole(role);
+		return configuredSelector ? parseRetryFallbackSelector(configuredSelector) : undefined;
+	}
+
+	#clearActiveRetryFallback(): void {
+		this.#activeRetryFallback = undefined;
+	}
+
+	#isRetryFallbackSelectorSuppressed(selector: RetryFallbackSelector): boolean {
+		return this.#modelRegistry.isSelectorSuppressed(selector.raw);
+	}
+
+	#noteRetryFallbackCooldown(currentSelector: string, retryAfterMs: number | undefined, errorMessage: string): void {
+		let cooldownMs = retryAfterMs;
+		if (!cooldownMs || cooldownMs <= 0) {
+			const reason = parseRateLimitReason(errorMessage);
+			cooldownMs = reason === "UNKNOWN" ? 5 * 60 * 1000 : calculateRateLimitBackoffMs(reason);
+		}
+		this.#modelRegistry.suppressSelector(currentSelector, Date.now() + cooldownMs);
+	}
+
+	#resolveRetryFallbackRole(currentSelector: string): string | undefined {
+		const parsedCurrent = parseRetryFallbackSelector(currentSelector);
+		if (!parsedCurrent) return undefined;
+		const currentBaseSelector = formatRetryFallbackBaseSelector(parsedCurrent);
+		for (const role of Object.keys(this.#getRetryFallbackChains())) {
+			const primarySelector = this.#getRetryFallbackPrimarySelector(role);
+			if (!primarySelector) continue;
+			if (primarySelector.raw === currentSelector) return role;
+			if (formatRetryFallbackBaseSelector(primarySelector) === currentBaseSelector) return role;
+		}
+		return undefined;
+	}
+
+	#getRetryFallbackEffectiveChain(role: string): RetryFallbackSelector[] {
+		const primarySelector = this.#getRetryFallbackPrimarySelector(role);
+		if (!primarySelector) return [];
+		const chain = [primarySelector];
+		const seen = new Set<string>([primarySelector.raw]);
+		for (const selector of this.#getRetryFallbackChains()[role] ?? []) {
+			const parsed = parseRetryFallbackSelector(selector);
+			if (!parsed || seen.has(parsed.raw)) continue;
+			seen.add(parsed.raw);
+			chain.push(parsed);
+		}
+		return chain;
+	}
+
+	#findRetryFallbackCandidates(role: string, currentSelector: string): RetryFallbackSelector[] {
+		const chain = this.#getRetryFallbackEffectiveChain(role);
+		if (chain.length <= 1) return [];
+		const parsedCurrent = parseRetryFallbackSelector(currentSelector);
+		const currentBaseSelector = parsedCurrent ? formatRetryFallbackBaseSelector(parsedCurrent) : undefined;
+		const exactIndex = chain.findIndex(selector => selector.raw === currentSelector);
+		if (exactIndex >= 0) return chain.slice(exactIndex + 1);
+		const baseIndex = currentBaseSelector
+			? chain.findIndex(selector => formatRetryFallbackBaseSelector(selector) === currentBaseSelector)
+			: -1;
+		if (baseIndex >= 0) return chain.slice(baseIndex + 1);
+		return chain.slice(1);
+	}
+
+	async #applyRetryFallbackCandidate(
+		role: string,
+		selector: RetryFallbackSelector,
+		currentSelector: string,
+	): Promise<void> {
+		const candidate = this.#modelRegistry.find(selector.provider, selector.id);
+		if (!candidate) {
+			throw new Error(`Retry fallback model not found: ${selector.raw}`);
+		}
+		const apiKey = await this.#modelRegistry.getApiKey(candidate, this.sessionId);
+		if (!apiKey) {
+			throw new Error(`No API key for retry fallback ${selector.raw}`);
+		}
+
+		const currentThinkingLevel = this.thinkingLevel;
+		const nextThinkingLevel = selector.thinkingLevel ?? currentThinkingLevel;
+
+		this.#setModelWithProviderSessionReset(candidate);
+		this.sessionManager.appendModelChange(`${candidate.provider}/${candidate.id}`, "temporary");
+		this.settings.getStorage()?.recordModelUsage(`${candidate.provider}/${candidate.id}`);
+		this.setThinkingLevel(nextThinkingLevel);
+		if (!this.#activeRetryFallback) {
+			this.#activeRetryFallback = {
+				role,
+				originalSelector: currentSelector,
+				originalThinkingLevel: currentThinkingLevel,
+				lastAppliedFallbackThinkingLevel: nextThinkingLevel,
+			};
+		} else {
+			this.#activeRetryFallback.lastAppliedFallbackThinkingLevel = nextThinkingLevel;
+		}
+		await this.#emitSessionEvent({
+			type: "retry_fallback_applied",
+			from: currentSelector,
+			to: selector.raw,
+			role,
+		});
+	}
+
+	async #tryRetryModelFallback(currentSelector: string): Promise<boolean> {
+		const role = this.#activeRetryFallback?.role ?? this.#resolveRetryFallbackRole(currentSelector);
+		if (!role) return false;
+
+		for (const selector of this.#findRetryFallbackCandidates(role, currentSelector)) {
+			if (this.#isRetryFallbackSelectorSuppressed(selector)) continue;
+			const candidate = this.#modelRegistry.find(selector.provider, selector.id);
+			if (!candidate) continue;
+			const apiKey = await this.#modelRegistry.getApiKey(candidate, this.sessionId);
+			if (!apiKey) continue;
+			await this.#applyRetryFallbackCandidate(role, selector, currentSelector);
+			return true;
+		}
+
+		return false;
+	}
+
+	async #maybeRestoreRetryFallbackPrimary(): Promise<void> {
+		if (!this.#activeRetryFallback) return;
+		if (this.#getRetryFallbackRevertPolicy() !== "cooldown-expiry") return;
+
+		const {
+			originalSelector: originalSelectorRaw,
+			originalThinkingLevel,
+			lastAppliedFallbackThinkingLevel,
+		} = this.#activeRetryFallback;
+		const originalSelector = parseRetryFallbackSelector(originalSelectorRaw);
+		if (!originalSelector) {
+			this.#clearActiveRetryFallback();
+			return;
+		}
+
+		const currentModel = this.model;
+		if (!currentModel) return;
+		const currentSelector = formatRetryFallbackSelector(currentModel, this.thinkingLevel);
+		if (currentSelector === originalSelector.raw) {
+			if (!this.#isRetryFallbackSelectorSuppressed(originalSelector)) {
+				this.#clearActiveRetryFallback();
+			}
+			return;
+		}
+		if (this.#isRetryFallbackSelectorSuppressed(originalSelector)) return;
+
+		const primaryModel = this.#modelRegistry.find(originalSelector.provider, originalSelector.id);
+		if (!primaryModel) return;
+		const apiKey = await this.#modelRegistry.getApiKey(primaryModel, this.sessionId);
+		if (!apiKey) return;
+
+		const currentThinkingLevel = this.thinkingLevel;
+		const thinkingToApply =
+			currentThinkingLevel === lastAppliedFallbackThinkingLevel ? originalThinkingLevel : currentThinkingLevel;
+		this.#setModelWithProviderSessionReset(primaryModel);
+		this.sessionManager.appendModelChange(`${primaryModel.provider}/${primaryModel.id}`, "temporary");
+		this.settings.getStorage()?.recordModelUsage(`${primaryModel.provider}/${primaryModel.id}`);
+		this.setThinkingLevel(thinkingToApply);
+		this.#clearActiveRetryFallback();
+	}
+
 	#parseRetryAfterMsFromError(errorMessage: string): number | undefined {
 		const now = Date.now();
 		const retryAfterMsMatch = /retry-after-ms\s*[:=]\s*(\d+)/i.exec(errorMessage);
@@ -4847,12 +5120,13 @@ export class AgentSession {
 		}
 
 		const errorMessage = message.errorMessage || "Unknown error";
+		const parsedRetryAfterMs = this.#parseRetryAfterMsFromError(errorMessage);
 		let delayMs = retrySettings.baseDelayMs * 2 ** (this.#retryAttempt - 1);
+		let switchedCredential = false;
+		let switchedModel = false;
 
 		if (this.model && isUsageLimitError(errorMessage)) {
-			const retryAfterMs =
-				this.#parseRetryAfterMsFromError(errorMessage) ??
-				calculateRateLimitBackoffMs(parseRateLimitReason(errorMessage));
+			const retryAfterMs = parsedRetryAfterMs ?? calculateRateLimitBackoffMs(parseRateLimitReason(errorMessage));
 			const switched = await this.#modelRegistry.authStorage.markUsageLimitReached(
 				this.model.provider,
 				this.sessionId,
@@ -4862,6 +5136,7 @@ export class AgentSession {
 				},
 			);
 			if (switched) {
+				switchedCredential = true;
 				delayMs = 0;
 			} else if (retryAfterMs > delayMs) {
 				// No more accounts to switch to — wait out the backoff
@@ -4869,6 +5144,17 @@ export class AgentSession {
 			}
 		}
 
+		const currentSelector = this.model ? formatRetryFallbackSelector(this.model, this.thinkingLevel) : undefined;
+		if (!switchedCredential && currentSelector) {
+			this.#noteRetryFallbackCooldown(currentSelector, parsedRetryAfterMs, errorMessage);
+			switchedModel = await this.#tryRetryModelFallback(currentSelector);
+			if (switchedModel) {
+				delayMs = 0;
+			} else if (parsedRetryAfterMs && parsedRetryAfterMs > delayMs) {
+				delayMs = parsedRetryAfterMs;
+			}
+		}
+
 		await this.#emitSessionEvent({
 			type: "auto_retry_start",
 			attempt: this.#retryAttempt,

package/src/tools/auto-generated-guard.ts

@@ -16,7 +16,7 @@ const CHECK_BYTE_COUNT = 1024;
 const HEADER_LINE_LIMIT = 40;
 
 const KNOWN_GENERATOR_PATTERN =
-	"(?:protoc(?:-gen-[\\w-]+)?|sqlc|buf|swagger(?:-codegen)?|openapi(?:-generator)?|grpc-gateway|mockery|stringer|easyjson|deepcopy-gen|defaulter-gen|conversion-gen|client-gen|lister-gen|informer-gen)";
+	"(?:protoc(?:-gen-[\\w-]+)?|sqlc|buf|swagger(?:-codegen)?|openapi(?:-generator)?|grpc-gateway|mockery|stringer|easyjson|deepcopy-gen|defaulter-gen|conversion-gen|client-gen|lister-gen|informer-gen|kysely-codegen)";
 
 /**
  * Strong marker patterns for generated-file headers.

package/src/tools/bash.ts

@@ -222,6 +222,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			asyncEnabled: this.#asyncEnabled,
 			hasAstGrep: this.session.settings.get("astGrep.enabled"),
 			hasAstEdit: this.session.settings.get("astEdit.enabled"),
+			hasGrep: this.session.settings.get("grep.enabled"),
+			hasFind: this.session.settings.get("find.enabled"),
 		});
 	}