@diegopetrucci/pi-extensions 0.1.61 → 0.1.63

package/extensions/fast/index.ts

@@ -0,0 +1,383 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+	CONFIG_DIR_NAME,
+	getAgentDir,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+const EXTENSION_ID = "fast";
+const ANTHROPIC_PROVIDER_ID = "anthropic";
+const ANTHROPIC_API_ID = "anthropic-messages";
+const ANTHROPIC_FAST_SPEED = "fast";
+const ANTHROPIC_FAST_BETA = "fast-mode-2026-02-01";
+const CLAUDE_CODE_OAUTH_BETAS = ["claude-code-20250219", "oauth-2025-04-20"];
+const FINE_GRAINED_TOOL_STREAMING_BETA = "fine-grained-tool-streaming-2025-05-14";
+const INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
+const ANTHROPIC_SUPPORTED_MODELS = new Set(["claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"]);
+
+const OPENAI_PROVIDER_ID = "openai-codex";
+const OPENAI_API_ID = "openai-codex-responses";
+const OPENAI_FAST_SERVICE_TIER = "priority";
+const OPENAI_SUPPORTED_MODELS = new Set([
+	"gpt-5.4",
+	"gpt-5.5",
+	"gpt-5.6-sol",
+	"gpt-5.6-terra",
+	"gpt-5.6-luna",
+]);
+
+const DEFAULT_CONFIG: FastConfig = {
+	enabled: false,
+	showStatus: true,
+};
+
+type FastOverride = "auto" | "on" | "off";
+type FastProvider = "anthropic" | "openai";
+
+type FastConfig = {
+	/** Default Fast-mode state when there is no session override. */
+	enabled: boolean;
+	/** Show a compact `fast` status when Fast mode is active for the current model. */
+	showStatus: boolean;
+};
+
+type SessionState = {
+	config: FastConfig;
+	override: FastOverride;
+	lastInjectedAt?: number;
+	lastInjectedModel?: string;
+};
+
+type ProjectConfigContext = {
+	cwd: string;
+	isProjectTrusted?: () => boolean;
+};
+
+type RecursivePartial<T> = {
+	[P in keyof T]?: T[P] extends object ? RecursivePartial<T[P]> : T[P];
+};
+
+type PayloadRecord = Record<string, unknown>;
+
+type AnthropicHeaderCompat = {
+	forceAdaptiveThinking?: boolean;
+	supportsEagerToolInputStreaming?: boolean;
+};
+
+type Eligibility = {
+	eligible: boolean;
+	modelKey: string;
+	provider?: FastProvider;
+	reason?: string;
+};
+
+function readConfigFile(path: string): RecursivePartial<FastConfig> {
+	if (!existsSync(path)) return {};
+
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8"));
+		return isPayloadRecord(parsed) ? (parsed as RecursivePartial<FastConfig>) : {};
+	} catch (error) {
+		console.error(`Warning: Could not parse ${path}: ${error}`);
+		return {};
+	}
+}
+
+function normalizeBoolean(value: unknown, fallback: boolean): boolean {
+	return typeof value === "boolean" ? value : fallback;
+}
+
+function mergeConfig(base: FastConfig, overrides: RecursivePartial<FastConfig>): FastConfig {
+	return {
+		enabled: normalizeBoolean(overrides.enabled, base.enabled),
+		showStatus: normalizeBoolean(overrides.showStatus, base.showStatus),
+	};
+}
+
+function canReadProjectConfig(ctx: ProjectConfigContext): boolean {
+	return typeof ctx.isProjectTrusted === "function" && ctx.isProjectTrusted();
+}
+
+function findProjectConfigPath(cwd: string): string {
+	let current = cwd;
+	while (true) {
+		const candidate = join(current, CONFIG_DIR_NAME, "fast.json");
+		if (existsSync(candidate)) return candidate;
+
+		const parent = dirname(current);
+		if (parent === current) return join(cwd, CONFIG_DIR_NAME, "fast.json");
+		current = parent;
+	}
+}
+
+function loadConfig(ctx: ProjectConfigContext): FastConfig {
+	const globalConfig = readConfigFile(join(getAgentDir(), "extensions", "fast.json"));
+	const projectConfig = canReadProjectConfig(ctx) ? readConfigFile(findProjectConfigPath(ctx.cwd)) : {};
+	return mergeConfig(mergeConfig(DEFAULT_CONFIG, globalConfig), projectConfig);
+}
+
+function isPayloadRecord(payload: unknown): payload is PayloadRecord {
+	return typeof payload === "object" && payload !== null && !Array.isArray(payload);
+}
+
+function modelKey(ctx: ExtensionContext): string {
+	const model = ctx.model;
+	return model ? `${model.provider}/${model.id}` : "no-model";
+}
+
+function isFastEnabled(state: SessionState): boolean {
+	if (state.override === "on") return true;
+	if (state.override === "off") return false;
+	return state.config.enabled;
+}
+
+function describeMode(state: SessionState): string {
+	if (state.override === "on") return "on (session override)";
+	if (state.override === "off") return "off (session override)";
+	return state.config.enabled ? "on (config default)" : "off (config default)";
+}
+
+function getEligibility(ctx: ExtensionContext): Eligibility {
+	const model = ctx.model;
+	if (!model) {
+		return { eligible: false, modelKey: "no-model", reason: "no model is selected" };
+	}
+
+	const key = `${model.provider}/${model.id}`;
+	if (model.provider === ANTHROPIC_PROVIDER_ID) {
+		if (model.api !== ANTHROPIC_API_ID) {
+			return {
+				eligible: false,
+				modelKey: key,
+				reason: `current API is ${model.api}, not ${ANTHROPIC_API_ID}`,
+			};
+		}
+
+		if (!ANTHROPIC_SUPPORTED_MODELS.has(model.id)) {
+			return {
+				eligible: false,
+				modelKey: key,
+				reason: "Fast mode is only enabled for Claude Opus 4.6, 4.7, and 4.8",
+			};
+		}
+
+		return { eligible: true, modelKey: key, provider: "anthropic" };
+	}
+
+	if (model.provider === OPENAI_PROVIDER_ID) {
+		if (model.api !== OPENAI_API_ID) {
+			return {
+				eligible: false,
+				modelKey: key,
+				reason: `current API is ${model.api}, not ${OPENAI_API_ID}`,
+			};
+		}
+
+		if (!OPENAI_SUPPORTED_MODELS.has(model.id)) {
+			return {
+				eligible: false,
+				modelKey: key,
+				reason: "Fast mode is not enabled for this OpenAI Codex model",
+			};
+		}
+
+		if (!ctx.modelRegistry.isUsingOAuth(model)) {
+			return {
+				eligible: false,
+				modelKey: key,
+				reason: "ChatGPT OAuth auth is required; API-key auth is intentionally not used",
+			};
+		}
+
+		return { eligible: true, modelKey: key, provider: "openai" };
+	}
+
+	return {
+		eligible: false,
+		modelKey: key,
+		reason: `current provider ${model.provider} does not support this extension's Fast mode`,
+	};
+}
+
+function updateStatus(ctx: ExtensionContext, state: SessionState): void {
+	if (!ctx.hasUI) return;
+	if (!state.config.showStatus) {
+		ctx.ui.setStatus(EXTENSION_ID, undefined);
+		return;
+	}
+
+	const eligibility = getEligibility(ctx);
+	ctx.ui.setStatus(
+		EXTENSION_ID,
+		isFastEnabled(state) && eligibility.eligible ? "fast" : undefined,
+	);
+}
+
+function getStatusMessage(ctx: ExtensionContext, state: SessionState): string {
+	const enabled = isFastEnabled(state);
+	const eligibility = getEligibility(ctx);
+	const active = enabled && eligibility.eligible;
+	const injected = state.lastInjectedAt
+		? ` Last injected for ${state.lastInjectedModel ?? "unknown model"} ${Math.max(0, Math.round((Date.now() - state.lastInjectedAt) / 1000))}s ago.`
+		: "";
+
+	if (active) {
+		const wireSetting =
+			eligibility.provider === "anthropic"
+				? `speed=${ANTHROPIC_FAST_SPEED}`
+				: `service_tier=${OPENAI_FAST_SERVICE_TIER}`;
+		return `Fast mode is ${describeMode(state)} and active for ${eligibility.modelKey}; requests will use ${wireSetting}.${injected}`;
+	}
+
+	if (enabled) {
+		return `Fast mode is ${describeMode(state)}, but inactive for ${eligibility.modelKey}: ${eligibility.reason}.${injected}`;
+	}
+
+	return `Fast mode is ${describeMode(state)}. Current model: ${eligibility.modelKey}.${injected}`;
+}
+
+function splitBetaHeader(value: string | null | undefined): string[] {
+	return (value ?? "")
+		.split(",")
+		.map((part) => part.trim())
+		.filter(Boolean);
+}
+
+async function isAnthropicOAuth(ctx: ExtensionContext): Promise<boolean> {
+	try {
+		const resolution = await ctx.modelRegistry.getProviderAuth(ANTHROPIC_PROVIDER_ID);
+		const apiKey = resolution?.auth.apiKey;
+		if (typeof apiKey === "string") return apiKey.includes("sk-ant-oat");
+	} catch {
+		// Fall back to the synchronous registry snapshot below.
+	}
+
+	return ctx.model ? ctx.modelRegistry.isUsingOAuth(ctx.model) : false;
+}
+
+function getAnthropicProviderBetas(ctx: ExtensionContext, hasActiveTools: boolean): string[] {
+	const model = ctx.model;
+	if (!model) return [];
+	const compat = model.compat as AnthropicHeaderCompat | undefined;
+
+	const betas: string[] = [];
+	if (hasActiveTools && compat?.supportsEagerToolInputStreaming === false) {
+		betas.push(FINE_GRAINED_TOOL_STREAMING_BETA);
+	}
+	if (compat?.forceAdaptiveThinking !== true) {
+		betas.push(INTERLEAVED_THINKING_BETA);
+	}
+	return betas;
+}
+
+async function injectAnthropicFastHeader(
+	headers: Record<string, string | null>,
+	ctx: ExtensionContext,
+	state: SessionState,
+	hasActiveTools: boolean,
+): Promise<void> {
+	if (!isFastEnabled(state)) return;
+	const eligibility = getEligibility(ctx);
+	if (!eligibility.eligible || eligibility.provider !== "anthropic") return;
+
+	const matchingKeys = Object.keys(headers).filter((name) => name.toLowerCase() === "anthropic-beta");
+	const existing = matchingKeys.flatMap((name) => splitBetaHeader(headers[name]));
+	const matchingModelEntries = Object.entries(ctx.model?.headers ?? {}).filter(
+		([name]) => name.toLowerCase() === "anthropic-beta",
+	);
+	const modelBetas = matchingModelEntries.flatMap(([, value]) => splitBetaHeader(value));
+	const providerBetas = getAnthropicProviderBetas(ctx, hasActiveTools);
+	const oauthBetas = (await isAnthropicOAuth(ctx)) ? CLAUDE_CODE_OAUTH_BETAS : [];
+	const next = Array.from(
+		new Set([...modelBetas, ...existing, ...oauthBetas, ...providerBetas, ANTHROPIC_FAST_BETA]),
+	);
+
+	for (const key of matchingKeys) delete headers[key];
+	const outputKey = matchingModelEntries.at(-1)?.[0] ?? "anthropic-beta";
+	headers[outputKey] = next.join(",");
+}
+
+function injectFastPayload(
+	payload: unknown,
+	ctx: ExtensionContext,
+	state: SessionState,
+): PayloadRecord | undefined {
+	if (!isFastEnabled(state)) return undefined;
+	const eligibility = getEligibility(ctx);
+	if (!eligibility.eligible || !eligibility.provider) return undefined;
+	if (!isPayloadRecord(payload)) return undefined;
+	if (payload.model !== ctx.model?.id) return undefined;
+
+	if (eligibility.provider === "anthropic") {
+		if ("speed" in payload) return undefined;
+		state.lastInjectedAt = Date.now();
+		state.lastInjectedModel = eligibility.modelKey;
+		return { ...payload, speed: ANTHROPIC_FAST_SPEED };
+	}
+
+	if ("service_tier" in payload) return undefined;
+	state.lastInjectedAt = Date.now();
+	state.lastInjectedModel = eligibility.modelKey;
+	return { ...payload, service_tier: OPENAI_FAST_SERVICE_TIER };
+}
+
+export default function fastExtension(pi: ExtensionAPI) {
+	const states = new WeakMap<object, SessionState>();
+
+	function getState(ctx: ExtensionContext): SessionState {
+		let state = states.get(ctx.sessionManager);
+		if (!state) {
+			state = {
+				config: loadConfig(ctx),
+				override: "auto",
+			};
+			states.set(ctx.sessionManager, state);
+		}
+		return state;
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		const state: SessionState = {
+			config: loadConfig(ctx),
+			override: "auto",
+		};
+		states.set(ctx.sessionManager, state);
+		updateStatus(ctx, state);
+	});
+
+	pi.on("model_select", (_event, ctx) => {
+		updateStatus(ctx, getState(ctx));
+	});
+
+	pi.on("before_provider_headers", async (event, ctx) => {
+		const hasActiveTools = typeof pi.getActiveTools === "function" && pi.getActiveTools().length > 0;
+		await injectAnthropicFastHeader(event.headers, ctx, getState(ctx), hasActiveTools);
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		const state = getState(ctx);
+		const nextPayload = injectFastPayload(event.payload, ctx, state);
+		updateStatus(ctx, state);
+		return nextPayload;
+	});
+
+	pi.registerCommand("fast", {
+		description: "Toggle Fast mode for supported OpenAI Codex and Anthropic Claude models",
+		getArgumentCompletions: () => null,
+		handler: async (args, ctx) => {
+			const state = getState(ctx);
+			const action = args.trim();
+
+			if (!action) {
+				state.override = isFastEnabled(state) ? "off" : "on";
+				updateStatus(ctx, state);
+				ctx.ui.notify(getStatusMessage(ctx, state), "info");
+				return;
+			}
+
+			ctx.ui.notify("Usage: /fast", "warning");
+		},
+	});
+}

package/extensions/fast/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@diegopetrucci/pi-fast",
+  "version": "0.1.0",
+  "description": "A pi extension that enables Fast mode for supported OpenAI Codex and Anthropic Claude models based on the currently selected model.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "openai",
+    "anthropic",
+    "fast"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegopetrucci/pi-extensions.git",
+    "directory": "extensions/fast"
+  },
+  "files": [
+    "index.ts",
+    "fast.example.json",
+    "README.md",
+    ".pi-fleet-tested-version"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/extensions/git-footer/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/git-footer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-git-footer",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "A TLH-style git status add-on for pi's built-in footer.",
   "keywords": [
     "pi-package",

package/extensions/gnosis/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/gnosis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-gnosis",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "A pi extension that exposes the gnosis repo-local knowledge base CLI as an agent tool.",
   "keywords": [
     "pi-package",

package/extensions/illustrations-to-explain-things/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/illustrations-to-explain-things/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-illustrations-to-explain-things",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "A pi skill for generating clean, absurd Xiaohei-style article illustrations, shot lists, and visual metaphors.",
   "keywords": [
     "pi-package",

package/extensions/inline-bash/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/inline-bash/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-inline-bash",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "A pi extension that expands inline bash commands in user prompts.",
   "keywords": [
     "pi-package",

package/extensions/librarian/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/librarian/README.md

@@ -4,7 +4,7 @@ A pi GitHub research scout inspired by `pi-librarian`, with a local checkout cac
 
 When the `librarian` tool runs, it can cache/reuse repository checkouts locally. Use `/librarian-cache off` to force GitHub API/search and temporary fetched files only, or `/librarian-cache on` to re-enable cached local checkouts.
 
-The internal librarian subagent uses a fast auto-selected model by default, requests `low` thinking, and prompts its scout to batch independent GitHub probes in parallel. Use `/librarian-config` to set a persistent internal model or thinking-level preference.
+The internal librarian subagent uses a fast auto-selected model by default, requests `low` thinking, and prompts its scout to batch independent GitHub probes in parallel. Automatic candidates and fallbacks stay within the current Pi session's model scope when that scope is non-empty; an explicit tool or `/librarian-config` model remains authoritative. Use `/librarian-config` to set a persistent internal model or thinking-level preference.
 
 ## Install
 

package/extensions/librarian/index.ts

@@ -46,6 +46,31 @@ type PiModel = {
 	thinkingLevelMap?: ThinkingLevelMap;
 };
 
+type ModelSelectionContext = {
+	model?: any;
+	modelRegistry: { getAvailable(): any[] | Promise<any[]> };
+	scopedModels?: ReadonlyArray<{ model: any; thinkingLevel?: ThinkingLevel }>;
+};
+
+function modelKey(model: any): string {
+	return `${model.provider}/${model.id}`.toLowerCase();
+}
+
+function hasModelScope(ctx: ModelSelectionContext): boolean {
+	return Array.isArray(ctx.scopedModels) && ctx.scopedModels.length > 0;
+}
+
+function isModelInScope(ctx: ModelSelectionContext, model: any): boolean {
+	if (!hasModelScope(ctx)) return true;
+	const key = modelKey(model);
+	return ctx.scopedModels!.some((entry) => modelKey(entry.model) === key);
+}
+
+async function getAutoSelectableModels(ctx: ModelSelectionContext): Promise<any[]> {
+	const available = await ctx.modelRegistry.getAvailable();
+	return hasModelScope(ctx) ? available.filter((model) => isModelInScope(ctx, model)) : available;
+}
+
 type CreateAgentSessionOptions = NonNullable<Parameters<typeof createAgentSession>[0]>;
 
 function getModelRuntimeOption(ctx: { modelRegistry?: unknown }): Pick<CreateAgentSessionOptions, "modelRuntime"> {
@@ -677,7 +702,7 @@ function rankPreferredFastLibrarianModel(model: any): number {
 }
 
 async function findAvailableModel(
-	ctx: { model?: any; modelRegistry: { getAvailable(): any[] | Promise<any[]> } },
+	ctx: ModelSelectionContext,
 	modelPreference: string,
 ): Promise<any | undefined> {
 	const available = await ctx.modelRegistry.getAvailable();
@@ -732,7 +757,7 @@ function withLibrarianFallbackReason(candidate: LibrarianCandidate, previous: Li
 // these in order and skip ones that fail with a model-availability error,
 // ultimately falling back to the known-good current session model.
 async function buildLibrarianCandidates(
-	ctx: { model?: any; modelRegistry: { getAvailable(): any[] | Promise<any[]> } },
+	ctx: ModelSelectionContext,
 	modelPreference: string | undefined,
 	thinkingLevel: ThinkingLevel,
 ): Promise<LibrarianCandidate[]> {
@@ -762,7 +787,7 @@ async function buildLibrarianCandidates(
 		}
 	}
 
-	const available = await ctx.modelRegistry.getAvailable();
+	const available = await getAutoSelectableModels(ctx);
 	const preferred = available.filter(isPreferredFastLibrarianModel);
 	const ranked = preferred.length > 0
 		? [...preferred].sort((a, b) => rankPreferredFastLibrarianModel(a) - rankPreferredFastLibrarianModel(b))
@@ -785,7 +810,7 @@ async function buildLibrarianCandidates(
 	});
 
 	// Final fallback: the active session model is known to be servable.
-	if (ctx.model) {
+	if (ctx.model && isModelInScope(ctx, ctx.model)) {
 		push(ctx.model, {
 			modelRef: modelRef(ctx.model),
 			provider: ctx.model.provider,
@@ -797,7 +822,11 @@ async function buildLibrarianCandidates(
 	}
 
 	if (candidates.length === 0) {
-		throw new Error("No authenticated models are available for Librarian. Log in or configure an API key first.");
+		throw new Error(
+			hasModelScope(ctx)
+				? "No authenticated models are available for Librarian in the current session model scope. Adjust the scope, log in, or configure an API key."
+				: "No authenticated models are available for Librarian. Log in or configure an API key first.",
+		);
 	}
 
 	return candidates;

package/extensions/librarian/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-librarian",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "A pi GitHub research scout with a toggleable local repo checkout cache under the user's OS cache directory.",
   "keywords": [
     "pi-package",

package/extensions/minimal-footer/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/minimal-footer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-minimal-footer",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "A minimal custom footer for pi.",
   "keywords": [
     "pi-package",

package/extensions/notify/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/notify/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-notify",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "A pi extension that sends a notification when the agent is ready for input.",
   "keywords": [
     "pi-package",

package/extensions/openai-fast/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/openai-fast/README.md

@@ -2,6 +2,8 @@
 
 A pi extension that enables OpenAI Codex Fast mode for ChatGPT-auth GPT-5.4, GPT-5.5, and GPT-5.6 Codex variants (`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`).
 
+This package is standalone-only and is not auto-loaded by the `@diegopetrucci/pi-extensions` collection package. The collection uses the unified [`fast`](../fast) extension instead.
+
 When active, the extension injects this into eligible OpenAI Codex request payloads:
 
 ```json

package/extensions/openai-fast/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-openai-fast",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "A pi extension that enables OpenAI Codex Fast mode for ChatGPT-auth GPT-5.4, GPT-5.5, and GPT-5.6 Codex variants by injecting the priority service tier.",
   "keywords": [
     "pi-package",

package/extensions/oracle/.pi-fleet-tested-version

@@ -1 +1 @@
-0.82.1
+0.83.0

package/extensions/oracle/README.md

@@ -106,6 +106,8 @@ Tool-call parameters still win over these defaults. `auto` clears the configured
 - `thinkingLevel` - optional reasoning/thinking override; falls back to the `/oracle thinking` default, then built-in defaults
 - `cwd` - optional working directory override
 
+When the current Pi session has a non-empty model scope, Oracle limits automatic model selection and automatic fallbacks to that scope. An explicit tool or `/oracle model` override remains authoritative even when it is outside the session scope.
+
 ## Notes
 
 - The oracle is intentionally **read-only by default**.