@oh-my-pi/pi-coding-agent 13.11.1 → 13.12.0

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 ## [Unreleased]
 
+## [13.12.0] - 2026-03-14
+
+### Added
+
+- Added per-rule TTSR interrupt mode override via `interruptMode` field in rule frontmatter to allow fine-grained control over when TTSR interrupts stream processing
+- Added `task` model role to allow configuring a dedicated model for subtask execution via `modelRoles.task` setting
+- Added `moveCursorToMessageEnd` and `moveCursorToMessageStart` prompt actions to navigate to the beginning and end of the entire message
+- Added support for provider-level `compat` configuration to apply OpenAI compatibility settings across all models from a provider
+- Added `reasoningEffortMap` configuration option to map reasoning effort levels to provider-specific values
+- Added support for `supportsUsageInStreaming`, `requiresToolResultName`, `requiresAssistantAfterToolResult`, `requiresThinkingAsText`, `thinkingFormat`, and `supportsStrictMode` OpenAI compatibility options
+- Added support for provider-configurable `OpenAICompat.extraBody` to inject request-body fields for custom gateway/proxy routing
+- Added `close()` method to SessionManager for properly closing persistent writers after flushing pending data
+- Added `omp config init-xdg` command to initialize XDG Base Directory structure on Linux
+- Added `getHistoryDbPath()`, `getModelDbPath()`, `getMemoriesDir()`, `getTerminalSessionsDir()` path helpers
+
+### Changed
+
+- Path resolution on Linux redirects to XDG locations when `XDG_DATA_HOME` / `XDG_STATE_HOME` / `XDG_CACHE_HOME` environment variables are set
+
+### Changed
+
+- Changed TTSR interrupt logic to respect per-rule `interruptMode` settings, falling back to global `ttsr.interruptMode` when rule-level override is not specified
+- Reorganized settings tabs from 12 tabs (display, agent, input, tools, config, services, bash, lsp, ttsr, status) to 8 focused tabs (appearance, model, interaction, context, editing, tools, tasks, providers) for improved discoverability
+- Consolidated status line settings into the Appearance tab instead of a separate Status tab
+- Reorganized sampling parameters (temperature, topP, topK, minP, presencePenalty, repetitionPenalty) into the Model tab
+- Moved edit tool settings (mode, fuzzyMatch, fuzzyThreshold, streamingAbort) to the Editing tab
+- Moved read tool settings (readLineNumbers, readHashLines, read.defaultLimit) to the Editing tab
+- 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 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
+- Moved secret handling settings to the Providers tab
+- Moved speech-to-text settings to the Interaction tab
+- Moved context promotion, compaction, branch summary, memories, and TTSR settings to the Context tab
+- Updated tab icon symbols across unicode, nerd, and ASCII presets to match new tab structure
+- Changed default agent model from `default` to `pi/task` to enable independent model configuration for subtasks
+- Changed agent model resolution to support single-pattern inheritance fallback, allowing `pi/task` agents to inherit the active session model when the task role is unconfigured
+- Changed system prompt to use ISO 8601 date format (YYYY-MM-DD) instead of locale-specific formatting
+- Changed system prompt template to use `{{date}}` instead of `{{dateTime}}` for current date display
+- Changed tool download timeout from 15 seconds to 120 seconds to accommodate slower network conditions
+- Changed working directory paths in system prompt to use forward slashes for consistency across platforms
+- Modified bash executor to fall back to one-shot shell execution after a persistent session hard timeout, preventing subsequent commands from hanging
+
+### Removed
+
+- Removed bash executor hard timeout recovery test file (functionality already documented in existing entries)
+
+### Fixed
+
+- Fixed bash execution to fall back to one-shot shell runs after a persistent session hard timeout, preventing later commands from hanging until restart
+- Fixed timeout handling in RpcClient to properly clear timeouts and prevent resource leaks
+- Fixed AgentSession disposal to call SessionManager's `close()` method when available, ensuring proper cleanup of persistent writers
+- Removed redundant `path.join()` call wrapping `getHistoryDbPath()` in history-storage.ts
+
 ## [13.11.1] - 2026-03-13
 
 ### Added
@@ -46,6 +103,7 @@
 - Added `buildNamedToolChoice` utility function to build provider-aware tool choice constraints for named tools
 - Support for comma/space-separated path lists in `find`, `grep`, `ast_grep`, and `ast_edit` tools (e.g., `apps/,packages/,phases/` or `apps/ packages/ phases/`)
 - New `resolveMultiSearchPath` and `resolveMultiFindPattern` functions to handle multi-path search inputs with automatic common base path detection
+- Added `display.showTokenUsage` setting to show per-turn token usage (input, output, cache) on assistant messages
 
 ### Changed
 

package/package.json

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

package/src/capability/rule.ts

@@ -20,6 +20,8 @@ export interface RuleFrontmatter {
 	condition?: string | string[];
 	/** New key for TTSR stream scope. */
 	scope?: string | string[];
+	/** Per-rule TTSR interrupt mode override. */
+	interruptMode?: "never" | "prose-only" | "tool-only" | "always";
 	[key: string]: unknown;
 }
 
@@ -43,6 +45,8 @@ export interface Rule {
 	condition?: string[];
 	/** Optional stream scope tokens (for example: text, thinking, tool:edit(*.ts)). */
 	scope?: string[];
+	/** Per-rule TTSR interrupt mode override (falls back to global ttsr.interruptMode). */
+	interruptMode?: "never" | "prose-only" | "tool-only" | "always";
 	/** Source metadata */
 	_source: SourceMeta;
 }

package/src/cli/commands/init-xdg.ts

@@ -0,0 +1,27 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const APP_NAME = "omp";
+
+export async function initXdg(): Promise<void> {
+	if (process.platform !== "linux") {
+		console.error("XDG directory setup is only supported on Linux.");
+		process.exit(1);
+	}
+
+	const dataHome = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local/share");
+	const stateHome = process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local/state");
+	const cacheHome = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+
+	const dirs = [path.join(dataHome, APP_NAME), path.join(stateHome, APP_NAME), path.join(cacheHome, APP_NAME)];
+
+	for (const dir of dirs) {
+		await fs.mkdir(dir, { recursive: true });
+		console.log(`Created ${dir.replace(os.homedir(), "~")}`);
+	}
+
+	console.log("\nXDG directories initialized.");
+	console.log("Ensure XDG_DATA_HOME, XDG_STATE_HOME, and XDG_CACHE_HOME");
+	console.log("are set in your shell profile for omp to use them.");
+}

package/src/cli/config-cli.ts

@@ -19,12 +19,13 @@ import {
 } from "../config/settings";
 import { SETTINGS_SCHEMA } from "../config/settings-schema";
 import { theme } from "../modes/theme/theme";
+import { initXdg } from "./commands/init-xdg";
 
 // =============================================================================
 // Types
 // =============================================================================
 
-export type ConfigAction = "list" | "get" | "set" | "reset" | "path";
+export type ConfigAction = "list" | "get" | "set" | "reset" | "path" | "init-xdg";
 
 export interface ConfigCommandArgs {
 	action: ConfigAction;
@@ -34,7 +35,6 @@ export interface ConfigCommandArgs {
 		json?: boolean;
 	};
 }
-
 // =============================================================================
 // Setting Filtering
 // =============================================================================
@@ -73,7 +73,7 @@ function getSettingValues(def: CliSettingDef): readonly string[] | undefined {
 // Argument Parser
 // =============================================================================
 
-const VALID_ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path"];
+const VALID_ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg"];
 
 /**
  * Parse config subcommand arguments.
@@ -251,6 +251,9 @@ export async function runConfigCommand(cmd: ConfigCommandArgs): Promise<void> {
 		case "path":
 			handlePath();
 			break;
+		case "init-xdg":
+			await initXdg();
+			break;
 	}
 }
 
@@ -394,6 +397,7 @@ ${chalk.bold("Commands:")}
   set <key> <value>  Set a setting value
   reset <key>        Reset a setting to its default value
   path               Print the config directory path
+  init-xdg           Initialize XDG Base Directory structure (Linux only)
 
 ${chalk.bold("Options:")}
   --json             Output as JSON
@@ -406,6 +410,7 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} config set defaultThinkingLevel medium
   ${APP_NAME} config reset steeringMode
   ${APP_NAME} config list --json
+  ${APP_NAME} config init-xdg
 
 ${chalk.bold("Boolean Values:")}
   true, false, yes, no, on, off, 1, 0

package/src/cli/shell-cli.ts

@@ -85,7 +85,7 @@ export async function runShellCommand(cmd: ShellCommandArgs): Promise<void> {
 
 	const interruptHandler = () => {
 		if (active) {
-			shellSession.abort();
+			void shellSession.abort();
 			return;
 		}
 		rl.close();

package/src/commands/config.ts

@@ -5,7 +5,7 @@ import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import { type ConfigAction, type ConfigCommandArgs, runConfigCommand } from "../cli/config-cli";
 import { initTheme } from "../modes/theme/theme";
 
-const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path"];
+const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg"];
 
 export default class Config extends Command {
 	static description = "Manage configuration settings";

package/src/config/model-registry.ts

@@ -37,7 +37,7 @@ export function isAuthenticated(apiKey: string | undefined | null): apiKey is st
 	return Boolean(apiKey) && apiKey !== kNoAuth;
 }
 
-export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "commit";
+export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "commit" | "task";
 
 export interface ModelRoleInfo {
 	tag?: string;
@@ -52,9 +52,10 @@ export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
 	vision: { tag: "VISION", name: "Vision", color: "error" },
 	plan: { tag: "PLAN", name: "Architect", color: "muted" },
 	commit: { tag: "COMMIT", name: "Commit", color: "dim" },
+	task: { tag: "TASK", name: "Subtask", color: "muted" },
 };
 
-export const MODEL_ROLE_IDS: ModelRole[] = ["default", "smol", "slow", "vision", "plan", "commit"];
+export const MODEL_ROLE_IDS: ModelRole[] = ["default", "smol", "slow", "vision", "plan", "commit", "task"];
 
 const OpenRouterRoutingSchema = Type.Object({
 	only: Type.Optional(Type.Array(Type.String())),
@@ -68,13 +69,36 @@ const VercelGatewayRoutingSchema = Type.Object({
 });
 
 // Schema for OpenAI compatibility settings
+const ReasoningEffortMapSchema = Type.Object({
+	minimal: Type.Optional(Type.String()),
+	low: Type.Optional(Type.String()),
+	medium: Type.Optional(Type.String()),
+	high: Type.Optional(Type.String()),
+	xhigh: Type.Optional(Type.String()),
+});
+
 const OpenAICompatSchema = Type.Object({
 	supportsStore: Type.Optional(Type.Boolean()),
 	supportsDeveloperRole: Type.Optional(Type.Boolean()),
 	supportsReasoningEffort: Type.Optional(Type.Boolean()),
+	reasoningEffortMap: Type.Optional(ReasoningEffortMapSchema),
 	maxTokensField: Type.Optional(Type.Union([Type.Literal("max_completion_tokens"), Type.Literal("max_tokens")])),
+	supportsUsageInStreaming: Type.Optional(Type.Boolean()),
+	requiresToolResultName: Type.Optional(Type.Boolean()),
+	requiresAssistantAfterToolResult: Type.Optional(Type.Boolean()),
+	requiresThinkingAsText: Type.Optional(Type.Boolean()),
+	thinkingFormat: Type.Optional(
+		Type.Union([
+			Type.Literal("openai"),
+			Type.Literal("zai"),
+			Type.Literal("qwen"),
+			Type.Literal("qwen-chat-template"),
+		]),
+	),
 	openRouterRouting: Type.Optional(OpenRouterRoutingSchema),
 	vercelGatewayRouting: Type.Optional(VercelGatewayRoutingSchema),
+	extraBody: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+	supportsStrictMode: Type.Optional(Type.Boolean()),
 });
 
 const EffortSchema = Type.Union([
@@ -180,6 +204,7 @@ const ProviderConfigSchema = Type.Object({
 		]),
 	),
 	headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+	compat: Type.Optional(OpenAICompatSchema),
 	authHeader: Type.Optional(Type.Boolean()),
 	auth: Type.Optional(ProviderAuthSchema),
 	discovery: Type.Optional(ProviderDiscoverySchema),
@@ -212,6 +237,7 @@ interface ProviderValidationConfig {
 	auth?: ProviderAuthMode;
 	oauthConfigured?: boolean;
 	discovery?: ProviderDiscovery;
+	compat?: Model<Api>["compat"];
 	modelOverrides?: Record<string, unknown>;
 	models: ProviderValidationModel[];
 }
@@ -227,9 +253,9 @@ function validateProviderConfiguration(
 	if (models.length === 0) {
 		if (mode === "models-config") {
 			const hasModelOverrides = config.modelOverrides && Object.keys(config.modelOverrides).length > 0;
-			if (!config.baseUrl && !hasModelOverrides && !config.discovery) {
+			if (!config.baseUrl && !config.compat && !hasModelOverrides && !config.discovery) {
 				throw new Error(
-					`Provider ${providerName}: must specify "baseUrl", "modelOverrides", "discovery", or "models".`,
+					`Provider ${providerName}: must specify "baseUrl", "compat", "modelOverrides", "discovery", or "models"`,
 				);
 			}
 		}
@@ -288,6 +314,7 @@ export const ModelsConfigFile = new ConfigFile<ModelsConfig>("models", ModelsCon
 					api: providerConfig.api as Api | undefined,
 					auth: (providerConfig.auth ?? "apiKey") as ProviderAuthMode,
 					discovery: providerConfig.discovery as ProviderDiscovery | undefined,
+					compat: providerConfig.compat,
 					modelOverrides: providerConfig.modelOverrides,
 					models: (providerConfig.models ?? []) as ProviderValidationModel[],
 				},
@@ -297,11 +324,12 @@ export const ModelsConfigFile = new ConfigFile<ModelsConfig>("models", ModelsCon
 	},
 );
 
-/** Provider override config (baseUrl, headers, apiKey) without custom models */
+/** Provider override config (baseUrl, headers, apiKey, compat) without custom models */
 interface ProviderOverride {
 	baseUrl?: string;
 	headers?: Record<string, string>;
 	apiKey?: string;
+	compat?: Model<Api>["compat"];
 }
 
 interface DiscoveryProviderConfig {
@@ -309,6 +337,7 @@ interface DiscoveryProviderConfig {
 	api: Api;
 	baseUrl?: string;
 	headers?: Record<string, string>;
+	compat?: Model<Api>["compat"];
 	discovery: ProviderDiscovery;
 	optional?: boolean;
 }
@@ -397,12 +426,18 @@ function mergeCompat(
 	const base = baseCompat ?? {};
 	const override = overrideCompat;
 	const merged: NonNullable<Model<Api>["compat"]> = { ...base, ...override };
+	if (baseCompat?.reasoningEffortMap || overrideCompat.reasoningEffortMap) {
+		merged.reasoningEffortMap = { ...baseCompat?.reasoningEffortMap, ...overrideCompat.reasoningEffortMap };
+	}
 	if (baseCompat?.openRouterRouting || overrideCompat.openRouterRouting) {
 		merged.openRouterRouting = { ...baseCompat?.openRouterRouting, ...overrideCompat.openRouterRouting };
 	}
 	if (baseCompat?.vercelGatewayRouting || overrideCompat.vercelGatewayRouting) {
 		merged.vercelGatewayRouting = { ...baseCompat?.vercelGatewayRouting, ...overrideCompat.vercelGatewayRouting };
 	}
+	if (baseCompat?.extraBody || overrideCompat.extraBody) {
+		merged.extraBody = { ...baseCompat?.extraBody, ...overrideCompat.extraBody };
+	}
 	return merged;
 }
 
@@ -475,6 +510,7 @@ function buildCustomModel(
 	providerHeaders: Record<string, string> | undefined,
 	providerApiKey: string | undefined,
 	authHeader: boolean | undefined,
+	providerCompat: Model<Api>["compat"] | undefined,
 	modelDef: CustomModelDefinitionLike,
 	options: CustomModelBuildOptions,
 ): Model<Api> | undefined {
@@ -496,7 +532,7 @@ function buildCustomModel(
 		contextWindow: modelDef.contextWindow ?? (withDefaults ? 128000 : undefined),
 		maxTokens: modelDef.maxTokens ?? (withDefaults ? 16384 : undefined),
 		headers: mergeCustomModelHeaders(providerHeaders, modelDef.headers, authHeader, providerApiKey),
-		compat: modelDef.compat,
+		compat: mergeCompat(providerCompat, modelDef.compat),
 		contextPromotionTarget: modelDef.contextPromotionTarget,
 		premiumMultiplier: modelDef.premiumMultiplier,
 	} as Model<Api>);
@@ -630,6 +666,7 @@ export class ModelRegistry {
 						...model,
 						baseUrl: providerOverride.baseUrl ?? model.baseUrl,
 						headers: providerOverride.headers ? { ...model.headers, ...providerOverride.headers } : model.headers,
+						compat: mergeCompat(model.compat, providerOverride.compat),
 					};
 				}
 				const modelOverride = perModelOverrides?.get(m.id);
@@ -669,7 +706,10 @@ export class ModelRegistry {
 				});
 				continue;
 			}
-			const models = this.#applyProviderModelOverrides(providerConfig.provider, cache.models);
+			const models = this.#applyProviderModelOverrides(
+				providerConfig.provider,
+				this.#applyProviderCompat(providerConfig.compat, cache.models),
+			);
 			cachedModels.push(...models);
 			this.#providerDiscoveryStates.set(providerConfig.provider, {
 				provider: providerConfig.provider,
@@ -683,6 +723,11 @@ export class ModelRegistry {
 		return cachedModels;
 	}
 
+	#applyProviderCompat(compat: Model<Api>["compat"] | undefined, models: Model<Api>[]): Model<Api>[] {
+		if (!compat) return models;
+		return models.map(model => ({ ...model, compat: mergeCompat(model.compat, compat) }));
+	}
+
 	#addImplicitDiscoverableProviders(configuredProviders: Set<string>): void {
 		if (!configuredProviders.has("ollama")) {
 			this.#discoverableProviders.push({
@@ -752,12 +797,13 @@ export class ModelRegistry {
 		const configuredProviders = new Set(Object.keys(value.providers));
 
 		for (const [providerName, providerConfig] of Object.entries(value.providers)) {
-			// Always set overrides when baseUrl/headers present
-			if (providerConfig.baseUrl || providerConfig.headers || providerConfig.apiKey) {
+			// Always set overrides when baseUrl/headers/apiKey/compat are present
+			if (providerConfig.baseUrl || providerConfig.headers || providerConfig.apiKey || providerConfig.compat) {
 				overrides.set(providerName, {
 					baseUrl: providerConfig.baseUrl,
 					headers: providerConfig.headers,
 					apiKey: providerConfig.apiKey,
+					compat: providerConfig.compat,
 				});
 			}
 
@@ -772,6 +818,7 @@ export class ModelRegistry {
 					api: providerConfig.api as Api,
 					baseUrl: providerConfig.baseUrl,
 					headers: providerConfig.headers,
+					compat: providerConfig.compat,
 					discovery: providerConfig.discovery,
 					optional: false,
 				});
@@ -906,7 +953,10 @@ export class ModelRegistry {
 		if (discoveryError) {
 			this.#warnProviderDiscoveryFailure(providerConfig, discoveryError);
 		}
-		return this.#applyProviderModelOverrides(providerId, result.models);
+		return this.#applyProviderModelOverrides(
+			providerId,
+			this.#applyProviderCompat(providerConfig.compat, result.models),
+		);
 	}
 
 	#discoverModelsByProviderType(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
@@ -1302,6 +1352,7 @@ export class ModelRegistry {
 					providerConfig.headers,
 					providerConfig.apiKey,
 					providerConfig.authHeader,
+					providerConfig.compat,
 					modelDef as CustomModelDefinitionLike,
 					{ useDefaults: true },
 				);
@@ -1463,6 +1514,7 @@ export class ModelRegistry {
 					config.headers,
 					config.apiKey,
 					config.authHeader,
+					config.compat,
 					modelDef as CustomModelDefinitionLike,
 					{ useDefaults: false },
 				);
@@ -1506,6 +1558,7 @@ export interface ProviderConfigInput {
 	api?: Api;
 	streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
 	headers?: Record<string, string>;
+	compat?: Model<Api>["compat"];
 	authHeader?: boolean;
 	oauth?: {
 		name: string;

package/src/config/model-resolver.ts

@@ -318,16 +318,41 @@ export function parseModelPattern(
 const PREFIX_MODEL_ROLE = "pi/";
 const DEFAULT_MODEL_ROLE = "default";
 
-/**
- * Check if a model override value is effectively the default role.
- */
-export function isDefaultModelAlias(value: string | string[] | undefined): boolean {
-	if (!value) return true;
-	if (Array.isArray(value)) return value.every(entry => isDefaultModelAlias(entry));
-	if (value.startsWith(PREFIX_MODEL_ROLE)) {
-		value = value.slice(PREFIX_MODEL_ROLE.length);
+function getModelRoleAlias(value: string): ModelRole | undefined {
+	const normalized = value.trim();
+	if (!normalized.startsWith(PREFIX_MODEL_ROLE)) return undefined;
+
+	const candidate = normalized.slice(PREFIX_MODEL_ROLE.length);
+	for (const role of MODEL_ROLE_IDS) {
+		if (candidate === role) return role;
 	}
-	return value === DEFAULT_MODEL_ROLE;
+	return undefined;
+}
+
+function normalizeModelPatternList(value: string | string[] | undefined): string[] {
+	if (!value) return [];
+	const patterns = Array.isArray(value) ? value : value.split(",");
+	return patterns.map(pattern => pattern.trim()).filter(Boolean);
+}
+
+function isSessionInheritedAgentPattern(value: string): boolean {
+	return value === DEFAULT_MODEL_ROLE || value === `${PREFIX_MODEL_ROLE}${DEFAULT_MODEL_ROLE}` || value === "pi/task";
+}
+
+function resolveConfiguredRolePattern(value: string, settings?: Settings): string | undefined {
+	const normalized = value.trim();
+	if (!normalized) return undefined;
+
+	const lastColonIndex = normalized.lastIndexOf(":");
+	const thinkingLevel =
+		lastColonIndex > PREFIX_MODEL_ROLE.length ? parseThinkingLevel(normalized.slice(lastColonIndex + 1)) : undefined;
+	const aliasCandidate = thinkingLevel ? normalized.slice(0, lastColonIndex) : normalized;
+	const role = getModelRoleAlias(aliasCandidate);
+	if (!role) return normalized;
+
+	const configured = settings?.getModelRole(role)?.trim();
+	if (!configured) return undefined;
+	return thinkingLevel ? `${configured}:${thinkingLevel}` : configured;
 }
 
 /**
@@ -335,11 +360,48 @@ export function isDefaultModelAlias(value: string | string[] | undefined): boole
  */
 export function expandRoleAlias(value: string, settings?: Settings): string {
 	const normalized = value.trim();
-	if (normalized === "default") return settings?.getModelRole("default") ?? value;
-	if (!normalized.startsWith(PREFIX_MODEL_ROLE)) return value;
-	const role = normalized.slice(PREFIX_MODEL_ROLE.length) as ModelRole;
-	if (!MODEL_ROLE_IDS.includes(role)) return value;
-	return settings?.getModelRole(role) ?? value;
+	if (normalized === DEFAULT_MODEL_ROLE) {
+		return settings?.getModelRole("default") ?? value;
+	}
+
+	const resolved = resolveConfiguredRolePattern(value, settings);
+	return resolved ?? value;
+}
+
+export function resolveConfiguredModelPatterns(value: string | string[] | undefined, settings?: Settings): string[] {
+	const patterns = normalizeModelPatternList(value);
+	return patterns.flatMap(pattern => {
+		const resolved = resolveConfiguredRolePattern(pattern, settings);
+		return resolved ? [resolved] : [];
+	});
+}
+
+export interface AgentModelPatternResolutionOptions {
+	settingsOverride?: string | string[];
+	agentModel?: string | string[];
+	settings?: Settings;
+	activeModelPattern?: string;
+	fallbackModelPattern?: string;
+}
+
+export function resolveAgentModelPatterns(options: AgentModelPatternResolutionOptions): string[] {
+	const { settingsOverride, agentModel, settings, activeModelPattern, fallbackModelPattern } = options;
+
+	const overridePatterns = resolveConfiguredModelPatterns(settingsOverride, settings);
+	if (overridePatterns.length > 0) return overridePatterns;
+
+	const normalizedAgentPatterns = normalizeModelPatternList(agentModel);
+	const configuredAgentPatterns = resolveConfiguredModelPatterns(agentModel, settings);
+	const singleAgentPattern = normalizedAgentPatterns.length === 1 ? normalizedAgentPatterns[0] : undefined;
+	const agentInheritsSessionModel = singleAgentPattern ? isSessionInheritedAgentPattern(singleAgentPattern) : false;
+	if (configuredAgentPatterns.length > 0) {
+		if (!agentInheritsSessionModel) return configuredAgentPatterns;
+		if (singleAgentPattern === "pi/task") return configuredAgentPatterns;
+	}
+
+	const fallback =
+		activeModelPattern?.trim() || fallbackModelPattern?.trim() || settings?.getModelRole("default")?.trim() || "";
+	return resolveConfiguredModelPatterns(fallback, settings);
 }
 
 /**
@@ -367,13 +429,14 @@ export function resolveModelRoleValue(
 	}
 
 	const lastColonIndex = normalized.lastIndexOf(":");
-	const hasThinkingSuffix =
-		lastColonIndex > PREFIX_MODEL_ROLE.length && parseThinkingLevel(normalized.slice(lastColonIndex + 1));
-	const aliasCandidate = hasThinkingSuffix ? normalized.slice(0, lastColonIndex) : normalized;
-	const effectivePattern = expandRoleAlias(aliasCandidate, options?.settings);
-	const patternWithSuffix = hasThinkingSuffix
-		? `${effectivePattern}:${normalized.slice(lastColonIndex + 1)}`
-		: effectivePattern;
+	const thinkingSelector =
+		lastColonIndex > PREFIX_MODEL_ROLE.length ? parseThinkingLevel(normalized.slice(lastColonIndex + 1)) : undefined;
+	const aliasCandidate = thinkingSelector ? normalized.slice(0, lastColonIndex) : normalized;
+	const effectivePattern = resolveConfiguredRolePattern(aliasCandidate, options?.settings);
+	if (!effectivePattern) {
+		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
+	}
+	const patternWithSuffix = thinkingSelector ? `${effectivePattern}:${thinkingSelector}` : effectivePattern;
 	const { model, thinkingLevel, warning, explicitThinkingLevel } = parseModelPattern(
 		patternWithSuffix,
 		availableModels,