@danypops/pi-jittor 0.5.3 → 0.6.0

package/README.md

@@ -1,75 +1,44 @@
 # @danypops/pi-jittor
 
-The Pi extension for Jittor: token, cost, context, provider-budget, and model-run observation plus routing, recovery, and model-selection controls, all through an authenticated loopback client to the [`@danypops/jittor`](../jittor) daemon. See the [repo root README](../../README.md) for the two-package overview.
+The Pi extension for Jittor: token, cost, context, provider-budget, and model-run observation plus routing, recovery, and model-selection controls, over an authenticated loopback client to the [`@danypops/jittor`](../jittor) daemon. See the [repo root README](../../README.md) for the two-package overview.
 
-## Architecture
+## What it does
 
-- `extension/src/observability/` collects and presents token, cost, context, provider-budget, and model-run observations.
-- `extension/src/optimization/` contains routing-adjacent recovery and model-selection controls.
-- `extension/src/index.ts` composes Pi lifecycle handlers; daemon transport, settings, and session identity remain thin boundary modules.
+Records context composition, response headers, finalized usage, cost, and model-run behavior through the daemon; preflights provider turns and applies model/thinking decisions; blocks requests when required telemetry is unsafe. It follows Pi's current authenticated model/provider and re-syncs Pi's available models before every decision, so an unavailable catalog route is never selected. Route state is scoped per Pi session, so concurrent sessions can't clobber each other's active provider or footer budget.
 
-## Behavior
+The extension registers no model-callable tools — daemon JSON, CLI `--json`, human CLI output, notifications, panels, and the footer are separate bounded channels (see `@danypops/jittor`'s `docs/OUTPUT_CHANNELS.md`).
 
-The extension records context composition, response headers, finalized usage, cost, and model-run behavior through the daemon. It also preflights provider turns, applies model/thinking decisions, and blocks requests when required telemetry is unsafe. It follows Pi's current authenticated model/provider and synchronizes Pi's available models before every decision, so unavailable catalog routes are never selected. Mutable route state is scoped by Pi session, so concurrent sessions cannot replace each other's active provider or footer budget selection. Each session registers an opaque secret with the daemon at `session_start` (best-effort; a registration failure leaves that session unarmored rather than blocked) and presents it on every router-mutating call for the rest of its lifetime; an unregistered `session_id` continues to mutate exactly as before, so this is additive armor, not a breaking change for other callers of the same API. A configured required budget source still fails closed; a provider with no enforceable budget window continues explicitly monitor-only.
+Blocking always has an escape hatch: `/jittor off` enters persisted monitor-only mode and never blocks; `/jittor footer on|off` controls the informational footer independently of enforcement; `/jittor on` only re-enables enforcement after telemetry/route-sync succeed.
 
-Its responsive integrated footer groups repository and model identity with cumulative usage, a color-coded context-window bar, and current-provider budget telemetry. Codex shows the active model's bounded quota as a draining remaining-budget bar with reset and freshness information. OpenRouter uses the same drain semantics when its official key telemetry exposes a configured limit and remaining balance; keys without a limit remain honest text-only spend and never receive a fabricated denominator. Anthropic shows the same drain semantics from its most-restrictive-in-effect token bucket, falling back to the request bucket when no token telemetry has been observed yet. During Pi compaction, the context bar drains from its captured fill against a learned median duration estimated from the last few completed compactions (bounded to the most recent 20 samples, requiring at least 3 before trusting it). It never renders a timer. Until enough evidence exists, the bar does not drain; it blinks in place at its captured fill. Run `jittor compaction estimate [--json]` (via the core CLI) to inspect the current estimate and its confidence directly. Unknown and stale telemetry are marked explicitly. Run `/jittor` for the consolidated Settings TUI (its default action), or `/jittor status` for detailed burn pressure, freshness, route state, and confirmed emergency-halt/override controls.
+## Footer
 
-The extension currently registers no model-callable native tools, so Pi's native model `content` versus renderer `details` contract is explicitly not applicable. Daemon JSON, CLI `--json`, human CLI output, command notifications, panels, and the footer remain separate bounded channels. See the core package's [`docs/OUTPUT_CHANNELS.md`](../jittor/docs/OUTPUT_CHANNELS.md) for the conformance matrix and the requirements that apply if a native tool is introduced later.
+An integrated footer shows repository/model identity, cumulative usage, a color-coded context-window bar, and current-provider budget telemetry. Codex/OpenRouter/Anthropic each render a draining remaining-budget bar when the provider's own telemetry exposes a real limit; without one, spend stays honest text-only rather than a fabricated denominator. During Pi compaction the bar drains against a learned duration estimate (median of the last ≤20 completed compactions, needs ≥3 before trusting it) — never a fake timer, and it blinks in place until there's enough evidence. `jittor compaction estimate [--json]` inspects the estimate directly.
 
-Blocking always has a daemon-independent escape hatch. `/jittor off` immediately enters persisted monitor-only mode and never blocks provider requests. The informational footer is independently controlled with `/jittor footer on` and `/jittor footer off`, so showing status never enables enforcement. `/jittor on` only enables enforcement after telemetry polling and available-route synchronization succeed. Every fail-closed error includes these recovery commands plus the daemon restart command.
+## `/jittor` — settings and status
 
-### Opt-in Codex settled-turn recovery
-
-Transient Codex recovery is securely off by default and controlled through the existing Jittor command surface:
-
-```text
-/jittor recovery status
-/jittor recovery on
-/jittor recovery off
-/jittor recovery cancel
-```
-
-The on/off choice persists privately in `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`). Status reports only enabled state, cooldown, bounded attempt/window counters, and the normalized failure class. `cancel` clears the current cooldown and attempt window without changing the persisted on/off choice.
-
-The extension observes finalized Codex assistant errors through Pi's public message lifecycle, classifies only bounded error metadata, and waits for `agent_settled` before acting. That boundary guarantees Pi's built-in retry, compaction retry, and queued follow-up work has finished. A transient concurrency, rate-limit, overload, or transport failure then schedules one hidden follow-up with Retry-After-aware capped jitter. Recovery is limited to three attempts per ten-minute window, never overlaps pending Pi messages, resets after success, and is canceled by human input or session shutdown. Quota, authentication, invalid-request, unknown, and aborted failures remain terminal. Raw provider payloads are never retained or injected.
-
-### Settings
-
-`/jittor` is the settings and control command. Bare `/jittor` (or `/jittor settings`) opens one keyboard-navigable TUI covering routing enforcement, the informational footer, Codex recovery, and all four token-budget thresholds, with explicit ON/OFF and configured/not-configured labels, bounded rendering on narrow terminals, and confirmation for weaker enforcement/recovery changes. `/jittor status` shows the routing/pressure panel that used to be the bare command's default. Existing non-TUI subcommands (`benchmarks`, `outcome`, `recovery`, `on`/`off`, `footer on`/`off`, `context`) remain available for automation and are unchanged.
+`/jittor` (or `/jittor settings`) opens a keyboard-navigable TUI covering routing enforcement, the footer, Codex recovery, and the four token-budget thresholds. `/jittor status` shows the routing/pressure panel. `benchmarks`, `outcome`, `recovery`, `on`/`off`, `footer on`/`off`, and `context` remain available as direct subcommands for automation.
 
-### Usage and cost graphs
-
-`/usage` is its own top-level command, separate from `/jittor`. Bare `/usage` opens a colored Unicode cumulative graph with X/Y axes, per-provider/model series, and explicit **Hourly**, **Daily**, **Weekly**, **Monthly**, and **Quarterly** periods; `/usage cost` opens the same graph showing aggregated USD spend instead of tokens, reusing the `cost` metric already recorded content-free on every finalized Pi assistant message (no new instrumentation). Left/Right or Tab/Shift+Tab changes the time frame, `v` toggles between the token and cost views, and `r` refreshes.
-
-The graph fetches metrics per distinct provider/model scope (`jittor metrics distinct-scopes`, bounded to 40 scopes, 250 rows each) rather than one flat "most recent rows" query. A flat query lets one heavy, long-running session monopolize the entire row budget with its own most recent activity, silently hiding every other provider from the chart no matter which time frame is selected, since the query would never reach back far enough in time to see anything else. Fetching per scope guarantees every active provider/model gets its own fair share of the query budget instead.
-
-Series are colored with a categorical palette chosen to avoid this UI's own status colors ("success"/"warning"/"error" already mean something specific elsewhere in this panel, so reusing them for arbitrary model identity would make a model's bar segment look like a warning or a failure) and instead reuses the theme's syntax-highlighting roles. A stable provider/model identity hash keeps each model's color fixed across token and cost graphics, period switches, refreshes, ranking changes, and extension restarts. The hash also selects an optional bold variant as a second visual channel, reducing collisions when more model identities exist than terminal hues. Multiple models active within the same cumulative time frame are rendered as one bar stacked by color, not separate bars.
-
-Token-budget thresholds are optional and must be configured by the user; Jittor never infers a token allowance from Codex or another provider's subscription percentage. Configure or clear one period with `/usage budget <hourly|daily|weekly|monthly|quarterly> <positive-tokens|off>`, and inspect all of them with `/usage budget`. A configured budget appears as a horizontal threshold on the cumulative graph with explicit remaining or **OVER BUDGET** state; the cost view does not yet support a budget threshold. These private settings persist in `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`).
-
-See [`docs/USAGE_PRIOR_ART.md`](docs/USAGE_PRIOR_ART.md) for the chart design research.
-
-### Cost per Papyrus task
+### Opt-in Codex settled-turn recovery
 
-The extension observes Papyrus's task-focus lifecycle in real time over a shared Pi extension event bus (`papyrus.task-focus.v1`) -- Papyrus never depends on Jittor, it only broadcasts which task is currently focused. Every token/cost metric already recorded on a finalized Pi assistant message is tagged with the currently focused task's id, and the provider/model/thinking level active at that moment, the instant it is recorded (no time-window estimation, no new instrumentation). A paused or cleared focus stops tagging; spend recorded with nothing focused is reported separately as unattributed, never dropped or folded into an invented task. Run `jittor metrics cost-by-task --since <ms> --until <ms> [--json]` (via the core CLI) for a bounded per-task breakdown of cost and input/output/cache tokens, broken down further by which provider/model/thinking combination each task actually spent on.
+Off by default. `/jittor recovery on|off|status|cancel` — a transient Codex failure (rate-limit, overload, transport) schedules one hidden retry after Pi's own `agent_settled` boundary, Retry-After-aware, capped at 3 attempts per 10-minute window, canceled by human input or session shutdown. Quota/auth/invalid-request/unknown/aborted failures stay terminal; raw provider payloads are never retained. The on/off choice persists in `$XDG_CONFIG_HOME/jittor/extension.json`.
 
-### Benchmark evidence panel
+## `/usage` — token and cost graphs
 
-Run `/jittor benchmarks [coding|general] [research|planning|general]` (either order, either or both omitted) for the responsive recommendation panel over the core daemon's benchmark ranking operation (see `@danypops/jittor`'s README for ingestion sources). Because the released Pi extension API does not expose the exact `/scoped-models` set, the current adapter labels candidates `available-models`; the panel says **ADVISORY** and offers no selection action. Automatic route ordering is allowed only for `exact-session` authority and then narrows/reorders routes already present in the supplied candidate set. `/jittor outcome accepted` or `/jittor outcome rejected` attaches explicit outcome evidence to the latest completed local run; runtime completion alone is not treated as quality success.
+A colored Unicode cumulative graph (Hourly/Daily/Weekly/Monthly/Quarterly) per provider/model; `/usage cost` shows aggregated USD spend on the same axes. `Tab`/arrows switch period, `v` toggles token/cost, `r` refreshes. Each active provider/model gets a stable color (a second bold-variant channel once identities exceed available hues) so a model's color stays fixed across periods, refreshes, and restarts. `/usage budget <period> <tokens|off>` sets an optional threshold, rendered as a horizontal line on the graph with remaining/**OVER BUDGET** state (token view only; Jittor never infers a budget from a provider's own subscription tier). See [`docs/USAGE_PRIOR_ART.md`](docs/USAGE_PRIOR_ART.md) for the chart design research.
 
-### Context Hub inspection
+## Cost per Papyrus task
 
-Run `/context` for a tree-aware breakdown of the current context window. The TUI supports `/` live search, `f` scope cycling (**all**, **active**, **historical/compacted**), `m` minimum-size thresholds, `g`/`G` top/bottom navigation, and arrow-key scrolling. Search and filters preserve ancestor rows so a matching message block never loses its segment, turn, or branch context.
+Every token/cost metric already recorded on a finalized assistant message is tagged with the currently-focused Papyrus task (via the `papyrus.task-focus.v1` event bus, no new instrumentation) plus the provider/model/thinking level active at that moment. `jittor metrics cost-by-task --since <ms> --until <ms> [--json]` gives a bounded per-task cost/token breakdown. Spend with nothing focused reports as unattributed rather than folding into an invented task.
 
-Conversation entries drill into text, thinking, tool-call arguments, shell commands, and outputs. For conservatively mapped OpenAI-family models, `/context` lazily loads the corresponding `gpt-tokenizer` BPE and marks those individual values `tokenizer-exact-text`, naming the encoding. Unsupported/unknown models and character-only structural inputs remain visibly marked `≈ char/4`; failure to load a tokenizer falls back rather than blocking a request or guessing exactness. Base-prompt aggregates still drill into tool snippets, skills, project context files, guidelines, and custom/appended prompt inputs with structural provenance.
+## Benchmark evidence panel
 
-Assistant turns also expose the authoritative **provider-reported aggregate request context** (`input + cacheRead + cacheWrite`). The aggregate stays separate from individual item costs, with an explicit unattributed residual rather than proportional allocation. Images, message envelopes, chat templates, tool schemas, cache-control serialization, and provider rewrites remain provider/model-specific, so exact local text counts are never described as exact requests or billing. Measurements retain only bounded provenance/identity metadata; tokenizer input and prompt/response content are never persisted. See [`../jittor/docs/TOKEN_MEASUREMENT.md`](../jittor/docs/TOKEN_MEASUREMENT.md).
+`/jittor benchmarks [coding|general] [research|planning|general]` shows a responsive model-recommendation panel over the daemon's benchmark ranking (see `@danypops/jittor`'s own README for ingestion sources). Labeled **ADVISORY** — Pi's extension API doesn't expose the real `/scoped-models` set, so this offers no direct selection action. `/jittor outcome accepted|rejected` attaches real outcome evidence to the latest completed run.
 
-At Pi's `before_provider_request` boundary, Jittor also records a bounded content-free snapshot of final request structure plus compaction-aware/inactive session history. `/context` shows the latest stable-prefix size, first changed segment, lifecycle counts, per-source growth, and truncation state. These keyed-HMAC correlations are structural evidence, never proof of provider cache behavior. See [`../jittor/docs/CONTEXT_SNAPSHOTS.md`](../jittor/docs/CONTEXT_SNAPSHOTS.md).
+## `/context` — context window inspection
 
-### Context pressure
+A tree-aware breakdown of the current context window: `/` search, `f` scope (all/active/historical), `m` size threshold, `g`/`G`/arrows navigate. Conservatively-mapped OpenAI-family models get exact `gpt-tokenizer` counts (marked `tokenizer-exact-text`); everything else stays `≈ char/4`. Assistant turns also show the provider's own authoritative aggregate request context (input + cache read + cache write) alongside individual item costs, with an explicit unattributed residual rather than proportional allocation. See [`../jittor/docs/TOKEN_MEASUREMENT.md`](../jittor/docs/TOKEN_MEASUREMENT.md) and [`../jittor/docs/CONTEXT_SNAPSHOTS.md`](../jittor/docs/CONTEXT_SNAPSHOTS.md).
 
-Run `/jittor context` for the in-session summary of Papyrus prompt-injection and Pi compaction telemetry; see `@danypops/jittor`'s README for what is recorded and the equivalent CLI command.
+`/jittor context` shows the in-session Papyrus prompt-injection / Pi compaction telemetry summary — see `@danypops/jittor`'s README for what's recorded.
 
 ## Development
 

package/extension/src/index.ts

@@ -6,7 +6,10 @@ import {
 	CONTEXT_HUB_CONTRIBUTION_CHANNEL,
 	CompactionTelemetry,
 	type ContextAssessment,
+	classifyEffort,
 	classifyTaskFromTools,
+	declaredEffortFromTaskFocusEvent,
+	EFFORT_CLASSIFICATION_MAX_TOOL_NAMES,
 	FOOTER_COMPACTION_RENDER_INTERVAL_MS,
 	HmacContextFingerprinter,
 	loadOpenAiTextTokenCounter,
@@ -15,6 +18,7 @@ import {
 	MILLISECONDS_PER_DAY,
 	type ModelCandidate,
 	type ModelTaskDomain,
+	type ModelTaskEffort,
 	type ModelTaskType,
 	PAPYRUS_CONTEXT_INJECTION_CHANNEL,
 	PAPYRUS_TASK_FOCUS_CHANNEL,
@@ -54,10 +58,19 @@ import { captureProviderContextSnapshot } from "./observability/provider-context
 import { ProviderResponseTelemetry } from "./observability/provider-response.ts";
 import { buildFooterBudget, providerBudgetMetricQuery } from "./observability/status.ts";
 import { showUsagePanel } from "./observability/usage.ts";
+import { candidateIdentityOf, decideAutoMode, newAutoModeSessionState, recordAutoModeDismissal } from "./optimization/auto-mode.ts";
+import { showAutoModeSuggestion } from "./optimization/auto-mode-dialog.ts";
+import { fetchBenchmarkRanking } from "./optimization/model-selection-panel.ts";
 import { CodexRecoveryCapability, type CodexRecoveryRuntime, SYSTEM_RECOVERY_RUNTIME } from "./optimization/recovery/codex.ts";
 import { callJittor } from "./service-client.ts";
 import { cacheSessionSecret, forgetSessionSecret, sessionSecretField } from "./session-identity.ts";
-import { type CodexRecoveryControl, type EnforcementControl, persistentEnforcementControl, type UsageBudgetControl } from "./settings.ts";
+import {
+	type AutoModeControl,
+	type CodexRecoveryControl,
+	type EnforcementControl,
+	persistentEnforcementControl,
+	type UsageBudgetControl,
+} from "./settings.ts";
 
 export { formatFooterStatus } from "./observability/status.ts";
 export type { CodexRecoveryRuntime } from "./optimization/recovery/codex.ts";
@@ -108,6 +121,28 @@ function recoveryControl(enforcement: EnforcementControl): CodexRecoveryControl
 		: { isCodexRecoveryEnabled: () => false, setCodexRecoveryEnabled() {} };
 }
 
+/**
+ * Falls back to "off" (never "suggest", the real persisted default in persistentEnforcementControl
+ * itself) when the passed-in control doesn't implement AutoModeControl -- e.g. a test harness's
+ * minimal enforcement-only fake. Matches usageBudgetControl/recoveryControl's own conservative
+ * fallback stubs: assume the feature is off/unconfigured rather than defaulting it on somewhere
+ * a caller never actually wired real persisted state for it.
+ */
+function autoModeControl(enforcement: EnforcementControl): AutoModeControl {
+	const candidate = enforcement as EnforcementControl & Partial<AutoModeControl>;
+	return typeof candidate.getAutoMode === "function" &&
+		typeof candidate.setAutoMode === "function" &&
+		typeof candidate.isAutoModeVerbose === "function" &&
+		typeof candidate.setAutoModeVerbose === "function"
+		? {
+				getAutoMode: () => candidate.getAutoMode!(),
+				setAutoMode: (mode) => candidate.setAutoMode!(mode),
+				isAutoModeVerbose: () => candidate.isAutoModeVerbose!(),
+				setAutoModeVerbose: (verbose) => candidate.setAutoModeVerbose!(verbose),
+			}
+		: { getAutoMode: () => "off", setAutoMode() {}, isAutoModeVerbose: () => false, setAutoModeVerbose() {} };
+}
+
 async function recordMetrics(client: JittorExtensionClient, metrics: MetricObservation[]): Promise<void> {
 	if (metrics.length === 0) return;
 	// One atomic transaction rather than a per-metric RPC loop: a later observation in the same
@@ -404,12 +439,57 @@ export function registerJittorExtension(
 	codexRecovery: CodexRecoveryControl = recoveryControl(enforcement),
 	recoveryRuntime: CodexRecoveryRuntime = SYSTEM_RECOVERY_RUNTIME,
 	contextGrowth: ContextGrowthCapability = new ContextGrowthCapability(),
+	autoMode: AutoModeControl = autoModeControl(enforcement),
 ): void {
 	const footerState: IntegratedFooterState = { providerBudget: null };
 	const usageBudgets = usageBudgetControl(enforcement);
 	let compactionTelemetry = new CompactionTelemetry();
 	let contextGrowthTurn = 0;
 	const localRunTelemetry = new LocalRunTelemetry();
+	// Auto mode's own turn-boundary state: the just-received user text and the completed prior
+	// turn's tool-call mix feed classifyEffort; autoModeState remembers the last-seen effort and
+	// any dismissed suggestion (see optimization/auto-mode.ts's own anti-nag doc comment).
+	let pendingUserText: string | null = null;
+	let currentTurnToolNames: string[] = [];
+	let priorTurnToolNames: string[] = [];
+	const autoModeState = newAutoModeSessionState();
+	let autoModeSwitchNotifiedThisSession = false;
+	// Advisory/best-effort by construction: any failure here must never block or halt the turn the
+	// way budget enforcement's own fail-closed halt does -- callers wrap this in try/catch and swallow.
+	// Bind-beforehand: a Papyrus task focused with a declared `extra.effort` pins routing to that
+	// effort for as long as it stays focused -- no live per-turn detection needed for that task.
+	// Live classification remains the fallback whenever no task is focused, or the focused task
+	// declares no effort. Reset semantics mirror focusedTaskId's own handling below.
+	const runAutoModeTurn = async (ctx: ExtensionContext): Promise<void> => {
+		const mode = autoMode.getAutoMode();
+		if (mode === "off" || !ctx.model) return;
+		const candidates = benchmarkCandidatesFromPi(scopedOrAvailableModels(ctx), pi.getThinkingLevel());
+		if (candidates.length === 0) return;
+		const currentCandidate: ModelCandidate = { provider: ctx.model.provider, model: ctx.model.id, thinking: pi.getThinkingLevel() };
+		const effort = declaredEffort ?? classifyEffort({ userText: pendingUserText ?? "", priorTurnToolNames }).effort;
+		const ranking = await fetchBenchmarkRanking(ctx, client, candidates, "general", "general", effort, currentCandidate);
+		const decision = decideAutoMode({ mode, effort, ranking, state: autoModeState });
+		if (decision.kind === "switch") {
+			const applied = await applyRoute(pi, ctx, decision.candidate);
+			if (applied && !autoModeSwitchNotifiedThisSession) {
+				ctx.ui.notify(`Jittor auto-switched to ${candidateIdentityOf(decision.candidate)} (effort: ${effort}).`, "info");
+				autoModeSwitchNotifiedThisSession = true;
+			}
+		} else if (decision.kind === "suggest") {
+			const choice = await showAutoModeSuggestion(
+				ctx,
+				decision.candidate,
+				effort,
+				decision.utilityDelta,
+				decision.confidence,
+				ranking,
+				`${currentCandidate.provider}/${currentCandidate.model}`,
+				autoMode.isAutoModeVerbose(),
+			);
+			if (choice === "switch") await applyRoute(pi, ctx, decision.candidate);
+			else recordAutoModeDismissal(autoModeState, decision.candidate);
+		}
+	};
 	const providerResponseTelemetry = new ProviderResponseTelemetry();
 	const codexRecoveryCapability = new CodexRecoveryCapability(pi, codexRecovery, recoveryRuntime);
 	const contextHub = new ContextHubCapability();
@@ -494,11 +574,14 @@ export function registerJittorExtension(
 	// affect this one's attribution.
 	let currentSessionId: string | undefined;
 	let focusedTaskId: string | null = null;
+	// Read by runAutoModeTurn (declared above, only ever invoked later) as the bind-beforehand pin.
+	let declaredEffort: ModelTaskEffort | null = null;
 	const stopPapyrusTaskFocus = pi.events?.on?.(PAPYRUS_TASK_FOCUS_CHANNEL, (payload) => {
 		try {
 			const event = validateTaskFocusEvent(payload);
 			if (event.sessionId !== undefined && event.sessionId !== currentSessionId) return;
 			focusedTaskId = applyTaskFocusEvent(event);
+			declaredEffort = declaredEffortFromTaskFocusEvent(event);
 		} catch {
 			// Reject malformed or stale cross-extension events without retaining payloads or crashing the extension.
 		}
@@ -595,6 +678,7 @@ export function registerJittorExtension(
 					enforcement,
 					recovery: codexRecovery,
 					budgets: usageBudgets,
+					autoMode,
 					effects: {
 						setEnforcement: async (enabled) => (enabled ? enable(ctx) : disable(ctx)),
 						setFooter: async (enabled) => {
@@ -606,6 +690,8 @@ export function registerJittorExtension(
 							if (!enabled) cancelRecovery(true);
 							await codexRecovery.setCodexRecoveryEnabled(enabled);
 						},
+						setAutoMode: (mode) => autoMode.setAutoMode(mode),
+						setAutoModeVerbose: (verbose) => autoMode.setAutoModeVerbose(verbose),
 					},
 				},
 				status: { client },
@@ -615,6 +701,11 @@ export function registerJittorExtension(
 					currentIdentity: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "",
 					domain: benchmarksTask?.domain ?? "general",
 					type: benchmarksTask?.type ?? "general",
+					// This on-demand panel is not tied to a live turn, so it always uses the neutral
+					// "medium" effort (matching the pre-effort-axis cost weighting exactly) -- live
+					// per-turn effort detection feeds the turn_start Auto-mode decision path instead.
+					effort: "medium",
+					currentCandidate: ctx.model ? { provider: ctx.model.provider, model: ctx.model.id, thinking: pi.getThinkingLevel() } : null,
 				},
 				cache: { client, windowMs: 7 * MILLISECONDS_PER_DAY },
 			});
@@ -821,6 +912,7 @@ export function registerJittorExtension(
 	pi.on("session_start", async (_event, ctx) => {
 		currentSessionId = ctx.sessionManager.getSessionId();
 		focusedTaskId = null;
+		declaredEffort = null;
 		finishCompactionUi();
 		compactionTelemetry = new CompactionTelemetry();
 		contextGrowthTurn = 0;
@@ -918,7 +1010,13 @@ export function registerJittorExtension(
 	});
 
 	pi.on("input", async (event, ctx) => {
-		if (event.source !== "extension") cancelRecovery(true);
+		if (event.source !== "extension") {
+			cancelRecovery(true);
+			// Auto mode's own effort classifier reads this at the next turn_start -- captured
+			// unconditionally (independent of enforcement.isEnabled()) since Auto mode is a
+			// separate, independently-toggled feature from budget enforcement.
+			pendingUserText = event.text;
+		}
 		if (event.source === "extension" || !enforcement.isEnabled()) return { action: "continue" as const };
 		try {
 			const next = (await client.call("router.decide", { session_id: ctx.sessionManager.getSessionId() })) as PolicyDecision;
@@ -950,20 +1048,26 @@ export function registerJittorExtension(
 		codexRecoveryCapability.resetTurn();
 		providerResponseTelemetry.resetTurn();
 		localRunTelemetry.beginTurn(event.timestamp);
-		if (!enforcement.isEnabled()) return;
-		try {
-			await syncCurrentRoute(pi, client, ctx);
-			await syncAvailableRoutes(pi, client, ctx);
-			await applyDecision(
-				pi,
-				client,
-				ctx,
-				(await client.call("router.decide", { session_id: ctx.sessionManager.getSessionId() })) as PolicyDecision,
-			);
-			await refreshFooter(client, footerState, ctx.sessionManager.getSessionId());
-		} catch {
-			halt(ctx, "Jittor could not verify or apply a safe route");
+		// Budget/enforcement routing is safety-critical and always wins on conflict: Auto mode is
+		// only evaluated when budget pressure required no action this turn (action === "continue"),
+		// so the two decision sources never fight over the model mid-turn.
+		let budgetActedThisTurn = false;
+		if (enforcement.isEnabled()) {
+			try {
+				await syncCurrentRoute(pi, client, ctx);
+				await syncAvailableRoutes(pi, client, ctx);
+				const budgetDecision = (await client.call("router.decide", {
+					session_id: ctx.sessionManager.getSessionId(),
+				})) as PolicyDecision;
+				budgetActedThisTurn = budgetDecision.action !== "continue";
+				await applyDecision(pi, client, ctx, budgetDecision);
+				await refreshFooter(client, footerState, ctx.sessionManager.getSessionId());
+			} catch {
+				halt(ctx, "Jittor could not verify or apply a safe route");
+				return;
+			}
 		}
+		if (!budgetActedThisTurn) await runAutoModeTurn(ctx).catch(() => undefined);
 	});
 
 	pi.on("message_update", async (event) => {
@@ -974,6 +1078,10 @@ export function registerJittorExtension(
 		localRunTelemetry.onToolExecutionEnd(event.toolName, event.isError);
 		const classification = classifyTaskFromTools([event.toolName]);
 		compactionTelemetry.observeToolClass(`${classification.domain}-${classification.type}`, event.isError);
+		// Bounded accumulation for the effort classifier's tool-call-mix signal -- classifyEffort
+		// itself would slice defensively too, but there's no reason to grow this array unboundedly
+		// across a very long turn in the meantime.
+		if (currentTurnToolNames.length < EFFORT_CLASSIFICATION_MAX_TOOL_NAMES) currentTurnToolNames.push(event.toolName);
 	});
 
 	pi.on("after_provider_response", async (event, ctx) => {
@@ -991,6 +1099,8 @@ export function registerJittorExtension(
 		if (typeof tokens === "number" && Number.isFinite(tokens)) contextGrowth.observe(++contextGrowthTurn, tokens);
 		const metrics = localRunTelemetry.completeTurn(event.message, pi.getThinkingLevel());
 		await recordMetrics(client, metrics).catch(() => undefined);
+		priorTurnToolNames = currentTurnToolNames;
+		currentTurnToolNames = [];
 	});
 
 	pi.on("message_end", async (event, ctx) => {

package/extension/src/jittor-shell.ts

@@ -19,7 +19,7 @@
  * shell first opens. Switching to a tab that has never been visited fetches it once, on first
  * visit, not before.
  */
-import type { ModelCandidate, ModelRankingResult, ModelTaskDomain, ModelTaskType, RouterStatus } from "@danypops/jittor";
+import type { ModelCandidate, ModelRankingResult, ModelTaskDomain, ModelTaskEffort, ModelTaskType, RouterStatus } from "@danypops/jittor";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { BorderedSelectPanel, type MnemonicContext, type TabBarTheme, TabbedContainer, type TextMeasure } from "malevich-tui-components";
@@ -46,7 +46,7 @@ import {
 	fetchBenchmarkRanking,
 	showBenchmarkPanel,
 } from "./optimization/model-selection-panel.ts";
-import type { CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
+import type { AutoModeControl, CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
 import {
 	createSettingsPanel,
 	runSettingsAction,
@@ -64,6 +64,7 @@ export interface JittorShellDeps {
 		enforcement: EnforcementControl;
 		recovery: CodexRecoveryControl;
 		budgets: UsageBudgetControl;
+		autoMode: AutoModeControl;
 		effects: SettingsEffects;
 	};
 	status: { client: JittorPanelClient };
@@ -73,6 +74,8 @@ export interface JittorShellDeps {
 		currentIdentity: string;
 		domain: ModelTaskDomain;
 		type: ModelTaskType;
+		effort: ModelTaskEffort;
+		currentCandidate: ModelCandidate | null;
 	};
 	cache: { client: CacheEconomicsPanelClient; windowMs: number; now?: () => number };
 }
@@ -158,7 +161,7 @@ async function ensureLoaded(
 ): Promise<void> {
 	// Settings reads already-in-memory persisted state -- no daemon round trip, so eagerly keeping
 	// it fresh costs nothing and never violates "no network call for a tab never visited".
-	state.settings = settingsSnapshot(deps.settings.enforcement, deps.settings.recovery, deps.settings.budgets);
+	state.settings = settingsSnapshot(deps.settings.enforcement, deps.settings.recovery, deps.settings.budgets, deps.settings.autoMode);
 	if (activeKey === "status" && state.status === undefined) {
 		state.status = await fetchStatusSnapshot(deps.status.client, ctx.sessionManager.getSessionId());
 	}
@@ -169,6 +172,8 @@ async function ensureLoaded(
 			deps.benchmarks.candidates,
 			deps.benchmarks.domain,
 			deps.benchmarks.type,
+			deps.benchmarks.effort,
+			deps.benchmarks.currentCandidate,
 		);
 	}
 	if (activeKey === "cache" && state.cache === undefined) {
@@ -205,7 +210,14 @@ function tabBarTheme(theme: ShellTheme): TabBarTheme {
  */
 async function showNonTuiFallback(ctx: ExtensionCommandContext, deps: JittorShellDeps, initialTab: JittorTabKey): Promise<void> {
 	if (initialTab === "settings")
-		return showSettingsPanel(ctx, deps.settings.enforcement, deps.settings.recovery, deps.settings.budgets, deps.settings.effects);
+		return showSettingsPanel(
+			ctx,
+			deps.settings.enforcement,
+			deps.settings.recovery,
+			deps.settings.budgets,
+			deps.settings.autoMode,
+			deps.settings.effects,
+		);
 	if (initialTab === "status") return showJittorPanel(ctx, deps.status.client);
 	if (initialTab === "benchmarks")
 		return showBenchmarkPanel(
@@ -215,6 +227,8 @@ async function showNonTuiFallback(ctx: ExtensionCommandContext, deps: JittorShel
 			deps.benchmarks.currentIdentity,
 			deps.benchmarks.domain,
 			deps.benchmarks.type,
+			deps.benchmarks.effort,
+			deps.benchmarks.currentCandidate,
 		);
 	return showCacheEconomicsPanel(ctx, deps.cache.client, deps.cache.windowMs, deps.cache.now);
 }
@@ -314,6 +328,7 @@ export async function showJittorShell(
 				deps.settings.recovery,
 				deps.settings.budgets,
 				deps.settings.effects,
+				deps.settings.autoMode,
 			);
 			continue;
 		}

package/extension/src/optimization/auto-mode-dialog.ts

@@ -0,0 +1,108 @@
+/**
+ * Suggest-mode's real interactive surface: a compact one-line Dialog (Switch / Details / Not
+ * now) with Details expanding into the existing benchmark panel's full component/confidence/
+ * provenance breakdown before the user decides -- both verbosity levels are supported, never
+ * just one. Reuses `createBenchmarkPanel` rather than building a second detail renderer.
+ */
+
+import type { ModelCandidate, ModelRankingResult, ModelTaskEffort } from "@danypops/jittor";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Dialog, type TextMeasure } from "malevich-tui-components";
+import { candidateIdentityOf } from "./auto-mode.ts";
+import { createBenchmarkPanel } from "./model-selection-panel.ts";
+
+export type AutoModeSuggestionChoice = "switch" | "dismiss";
+
+interface SuggestionTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+const hostTextMeasure: TextMeasure = { visibleWidth, truncateToWidth };
+
+function summaryLine(candidate: ModelCandidate, effort: ModelTaskEffort, utilityDelta: number, confidence: number): string {
+	return `Jittor suggests ${candidateIdentityOf(candidate)} for this turn -- effort: ${effort}, +${utilityDelta.toFixed(2)} utility, ${(confidence * 100).toFixed(0)}% confidence.`;
+}
+
+/** Shows the existing benchmark breakdown as a read-only detail view; any dismissal (Esc, "r", Ctrl+C) returns control to the caller, which re-shows the compact decision dialog. */
+async function showSuggestionDetails(ctx: ExtensionContext, ranking: ModelRankingResult, currentIdentity: string): Promise<void> {
+	await ctx.ui.custom<"close">((_tui, theme: SuggestionTheme, _keybindings, done) => {
+		const panel = createBenchmarkPanel(ranking, currentIdentity, theme, () => done("close"), true);
+		return {
+			invalidate: () => panel.invalidate(),
+			render: (width: number) => panel.render(width),
+			handleInput(data: string): void {
+				if (matchesKey(data, "ctrl+c")) {
+					done("close");
+					return;
+				}
+				panel.handleInput(data);
+			},
+		};
+	});
+}
+
+/**
+ * Non-TUI (`ctx.mode !== "tui"`) mode has no interactive dialog to show, matching every other
+ * jittor confirmation's own non-TUI fallback -- it stays a plain notify and the suggestion is
+ * treated as dismissed (advisory-only; the user reads it, no automatic action follows).
+ */
+export async function showAutoModeSuggestion(
+	ctx: ExtensionContext,
+	candidate: ModelCandidate,
+	effort: ModelTaskEffort,
+	utilityDelta: number,
+	confidence: number,
+	ranking: ModelRankingResult,
+	currentIdentity: string,
+	verboseByDefault: boolean,
+): Promise<AutoModeSuggestionChoice> {
+	const summary = summaryLine(candidate, effort, utilityDelta, confidence);
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(`${summary} Run /jittor benchmarks for details.`, "info");
+		return "dismiss";
+	}
+	let showDetails = verboseByDefault;
+	for (;;) {
+		if (showDetails) {
+			await showSuggestionDetails(ctx, ranking, currentIdentity);
+			showDetails = false;
+			continue;
+		}
+		const choice = await ctx.ui.custom<AutoModeSuggestionChoice | "details">((_tui, theme: SuggestionTheme, _keybindings, done) => {
+			const dialog = new Dialog({
+				title: "Jittor suggestion",
+				body: summary,
+				actions: [
+					{ label: "Switch", key: "s", action: () => done("switch") },
+					{ label: "Details", key: "d", action: () => done("details") },
+					{ label: "Not now", key: "n", action: () => done("dismiss") },
+				],
+				theme: {
+					border: (text) => theme.fg("borderMuted", text),
+					title: theme.bold,
+					body: (text) => text,
+					dim: (text) => theme.fg("dim", text),
+				},
+				measure: hostTextMeasure,
+			});
+			return {
+				invalidate: () => dialog.invalidate(),
+				render: (width: number) => dialog.render(width),
+				handleInput(data: string): void {
+					if (matchesKey(data, "ctrl+c")) {
+						done("dismiss");
+						return;
+					}
+					dialog.handleInput(data);
+				},
+			};
+		});
+		if (choice === "details") {
+			showDetails = true;
+			continue;
+		}
+		return choice ?? "dismiss";
+	}
+}

package/extension/src/optimization/auto-mode.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure effort-based Auto mode decision logic -- deliberately separate from the existing
+ * budget-pressure `JittorRouter`/`applyDecision` path (optimization/routing), which reacts to
+ * provider quota pressure, not task complexity. The two compose at the call site (index.ts's
+ * `turn_start` handler): budget/enforcement always takes precedence on conflict, matching the
+ * design recorded in Doc "Auto mode: effort-aware model routing -- prior art and design".
+ *
+ * This module owns only the decision (what should happen this turn, given a fresh ranking
+ * result and the anti-nag session state) -- never the side effect itself (showing a dialog,
+ * calling `pi.setModel`, persisting a setting). That stays in index.ts, so this logic is fully
+ * unit-testable without mocking any Pi/TUI surface.
+ */
+import type { ModelCandidate, ModelRankingResult, ModelTaskEffort } from "@danypops/jittor";
+
+export const AUTO_MODE_SETTINGS = ["off", "suggest", "auto-switch"] as const;
+export type AutoModeSetting = (typeof AUTO_MODE_SETTINGS)[number];
+
+export interface AutoModeSessionState {
+	lastEffort: ModelTaskEffort | null;
+	dismissedIdentity: string | null;
+}
+
+export function newAutoModeSessionState(): AutoModeSessionState {
+	return { lastEffort: null, dismissedIdentity: null };
+}
+
+export function candidateIdentityOf(candidate: ModelCandidate): string {
+	return `${candidate.provider}/${candidate.model}:${candidate.thinking}`;
+}
+
+export interface AutoModeDecisionInput {
+	mode: AutoModeSetting;
+	/** The effort level this turn was classified/declared as -- only used to decide whether to re-evaluate a previously dismissed suggestion, never re-derived here. */
+	effort: ModelTaskEffort;
+	/** A ranking result already computed with this turn's effort and current model as its own uplift-gate baseline (see rankModelCandidates). */
+	ranking: ModelRankingResult;
+	state: AutoModeSessionState;
+}
+
+export type AutoModeDecision =
+	| { kind: "none" }
+	| { kind: "suggest"; candidate: ModelCandidate; utilityDelta: number; confidence: number }
+	| { kind: "switch"; candidate: ModelCandidate };
+
+/**
+ * Anti-nag bound: a Suggest-mode dismissal for one specific candidate identity is remembered and
+ * not re-offered again until either the detected/declared effort changes, or the recommended
+ * candidate itself changes (a stronger, different upgrade is always worth surfacing). The uplift
+ * gate inside `rankModelCandidates` itself is the primary anti-spam mechanism -- this only
+ * prevents re-nagging about the exact same already-declined suggestion every single turn.
+ */
+export function decideAutoMode(input: AutoModeDecisionInput): AutoModeDecision {
+	const { mode, effort, ranking, state } = input;
+	const effortChanged = state.lastEffort !== effort;
+	state.lastEffort = effort;
+	if (mode === "off") return { kind: "none" };
+	const recommendation = ranking.recommendation;
+	if (!recommendation) {
+		state.dismissedIdentity = null;
+		return { kind: "none" };
+	}
+	const identity = candidateIdentityOf(recommendation.candidate);
+	if (!effortChanged && state.dismissedIdentity === identity) return { kind: "none" };
+	if (mode === "auto-switch") return { kind: "switch", candidate: recommendation.candidate };
+	return {
+		kind: "suggest",
+		candidate: recommendation.candidate,
+		utilityDelta: recommendation.utilityDelta,
+		confidence: recommendation.confidence,
+	};
+}
+
+export function recordAutoModeDismissal(state: AutoModeSessionState, candidate: ModelCandidate): void {
+	state.dismissedIdentity = candidateIdentityOf(candidate);
+}

package/extension/src/optimization/model-selection-panel.ts

@@ -9,11 +9,12 @@ import {
 	type ModelCandidate,
 	type ModelRankingResult,
 	type ModelTaskDomain,
+	type ModelTaskEffort,
 	type ModelTaskType,
 	type RankedModel,
 	type UtilityComponentName,
 } from "@danypops/jittor";
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { BorderedSelectPanel, Table, type TextMeasure } from "malevich-tui-components";
 import { sessionSecretField } from "../session-identity.ts";
@@ -130,22 +131,39 @@ export function renderBenchmarkView(result: ModelRankingResult, currentIdentity:
 	return createBenchmarkPanel(result, currentIdentity, theme, () => undefined).render(Math.max(1, width));
 }
 
+/**
+ * Pi's own `--models`/`enabledModels` scoping (`ctx.scopedModels`, the same set the
+ * `/scoped-models` command shows) is the exact-session authority once it is configured -- an
+ * empty list means "no scoping configured" (matching Pi's own semantics), not "scoped to
+ * nothing", and stays advisory. Mirrors the identical predicate `scopedOrAvailableModels` in
+ * `index.ts` already uses to build the candidate set itself; this call site independently
+ * hardcoded `"available-models"` after that fix landed, which kept automatic selection
+ * disabled for a reason (Pi lacking `ctx.scopedModels`) that no longer exists.
+ */
+function scopeAuthorityFor(ctx: ExtensionContext): ModelRankingResult["scopeAuthority"] {
+	return ctx.scopedModels.length > 0 ? "exact-session" : "available-models";
+}
+
 /** Shared by the standalone benchmark panel below and the unified /jittor shell, so both fetch identically. */
 export async function fetchBenchmarkRanking(
-	ctx: ExtensionCommandContext,
+	ctx: ExtensionContext,
 	client: BenchmarkPanelClient,
 	candidates: ModelCandidate[],
 	domain: ModelTaskDomain,
 	type: ModelTaskType,
+	effort: ModelTaskEffort,
+	currentCandidate: ModelCandidate | null,
 ): Promise<ModelRankingResult> {
 	const session_id = ctx.sessionManager.getSessionId();
 	return (await client.call("models.rank", {
 		candidates,
 		session_id,
 		...sessionSecretField(session_id),
-		scopeAuthority: "available-models",
+		scopeAuthority: scopeAuthorityFor(ctx),
 		domain,
 		type,
+		effort,
+		currentCandidate,
 		budgetPressure: 0,
 		weights: {
 			quality: MODEL_RANKING_DEFAULT_QUALITY_WEIGHT,
@@ -165,9 +183,11 @@ export async function showBenchmarkPanel(
 	currentIdentity: string,
 	domain: ModelTaskDomain,
 	type: ModelTaskType,
+	effort: ModelTaskEffort,
+	currentCandidate: ModelCandidate | null,
 ): Promise<void> {
 	for (;;) {
-		const result = await fetchBenchmarkRanking(ctx, client, candidates, domain, type);
+		const result = await fetchBenchmarkRanking(ctx, client, candidates, domain, type, effort, currentCandidate);
 		if (ctx.mode !== "tui") {
 			ctx.ui.notify(
 				renderBenchmarkView(result, currentIdentity, 100, { fg: (_color, text) => text, bold: (text) => text }).join("\n"),

package/extension/src/settings-tui.ts

@@ -2,7 +2,8 @@ import { USAGE_PERIODS, type UsagePeriod } from "@danypops/jittor";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { BorderedSelectPanel, Menu, type MenuTheme, type TextMeasure } from "malevich-tui-components";
-import type { CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
+import { AUTO_MODE_SETTINGS, type AutoModeSetting } from "./optimization/auto-mode.ts";
+import type { AutoModeControl, CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
 import { showConfirmDialog } from "./tui-prompts.ts";
 
 export interface SettingsSnapshot {
@@ -10,6 +11,8 @@ export interface SettingsSnapshot {
 	footerEnabled: boolean;
 	codexRecoveryEnabled: boolean;
 	usageTokenBudgets: Partial<Record<UsagePeriod, number>>;
+	autoMode: AutoModeSetting;
+	autoModeVerbose: boolean;
 }
 
 interface SettingsTheme {
@@ -17,26 +20,37 @@ interface SettingsTheme {
 	bold(text: string): string;
 }
 
-export type SettingsKey = "enforcement" | "footer" | "recovery" | `budget-${UsagePeriod}`;
+export type SettingsKey = "enforcement" | "auto-mode" | "auto-mode-verbose" | "footer" | "recovery" | `budget-${UsagePeriod}`;
 export type SettingsAction = { kind: "activate"; key: SettingsKey } | { kind: "close" };
 
 export interface SettingsEffects {
 	setEnforcement(enabled: boolean): void | Promise<void>;
 	setFooter(enabled: boolean): void | Promise<void>;
 	setRecovery(enabled: boolean): void | Promise<void>;
+	setAutoMode(mode: AutoModeSetting): void | Promise<void>;
+	setAutoModeVerbose(verbose: boolean): void | Promise<void>;
 }
 
-// Enforcement -> Budget -> Providers -> UI: safety posture (the global kill-switch everything
-// else is downstream of) leads, followed by spend limits, then provider-specific quirks (today,
-// only Codex recovery -- grouped under its own header instead of sitting flat next to global
-// switches, which read as "too Codex-oriented" with nothing to signal its narrower scope), then
-// display preferences last.
-const SETTINGS_KEYS: SettingsKey[] = ["enforcement", ...USAGE_PERIODS.map(({ id }) => `budget-${id}` as const), "recovery", "footer"];
+// Enforcement -> Routing -> Budget -> Providers -> UI: safety posture (the global kill-switch
+// everything else is downstream of) leads, followed by effort-based Auto mode (a routing
+// behavior, not a safety switch, but consequential enough to sit right after Enforcement), then
+// spend limits, then provider-specific quirks (today, only Codex recovery -- grouped under its
+// own header instead of sitting flat next to global switches, which read as "too Codex-oriented"
+// with nothing to signal its narrower scope), then display preferences last.
+const SETTINGS_KEYS: SettingsKey[] = [
+	"enforcement",
+	"auto-mode",
+	"auto-mode-verbose",
+	...USAGE_PERIODS.map(({ id }) => `budget-${id}` as const),
+	"recovery",
+	"footer",
+];
 
-type SettingsCategory = "Enforcement" | "Budget" | "Providers" | "UI";
+type SettingsCategory = "Enforcement" | "Routing" | "Budget" | "Providers" | "UI";
 
 function categoryOf(key: SettingsKey): SettingsCategory {
 	if (key === "enforcement") return "Enforcement";
+	if (key === "auto-mode" || key === "auto-mode-verbose") return "Routing";
 	if (key === "recovery") return "Providers";
 	if (key === "footer") return "UI";
 	return "Budget";
@@ -51,8 +65,16 @@ function budgetLabel(period: UsagePeriod, snapshot: SettingsSnapshot): string {
 	return value === undefined ? "not configured" : `${value.toLocaleString()} tokens`;
 }
 
+function autoModeLabel(mode: AutoModeSetting, theme: SettingsTheme): string {
+	if (mode === "off") return theme.fg("muted", "OFF");
+	if (mode === "auto-switch") return theme.fg("success", "AUTO-SWITCH");
+	return theme.fg("accent", "SUGGEST");
+}
+
 function rowText(key: SettingsKey, snapshot: SettingsSnapshot, theme: SettingsTheme): string {
 	if (key === "enforcement") return `Routing enforcement  ${state(snapshot.enforcementEnabled, theme)}`;
+	if (key === "auto-mode") return `Auto mode  ${autoModeLabel(snapshot.autoMode, theme)}`;
+	if (key === "auto-mode-verbose") return `Suggestion details  ${state(snapshot.autoModeVerbose, theme)}`;
 	if (key === "footer") return `Informational footer  ${state(snapshot.footerEnabled, theme)}`;
 	if (key === "recovery") return `Codex recovery  ${state(snapshot.codexRecoveryEnabled, theme)}`;
 	const period = key.slice("budget-".length) as UsagePeriod;
@@ -63,12 +85,15 @@ export function settingsSnapshot(
 	enforcement: EnforcementControl,
 	recovery: CodexRecoveryControl,
 	budgets: UsageBudgetControl,
+	autoMode: AutoModeControl,
 ): SettingsSnapshot {
 	return {
 		enforcementEnabled: enforcement.isEnabled(),
 		footerEnabled: enforcement.isFooterEnabled(),
 		codexRecoveryEnabled: recovery.isCodexRecoveryEnabled(),
 		usageTokenBudgets: Object.fromEntries(USAGE_PERIODS.map(({ id }) => [id, budgets.getUsageTokenBudget(id)])),
+		autoMode: autoMode.getAutoMode(),
+		autoModeVerbose: autoMode.isAutoModeVerbose(),
 	};
 }
 
@@ -201,8 +226,31 @@ export async function runSettingsAction(
 	recovery: CodexRecoveryControl,
 	budgets: UsageBudgetControl,
 	effects: SettingsEffects,
+	autoMode: AutoModeControl,
 ): Promise<void> {
 	if (action.kind === "close") return;
+	if (action.key === "auto-mode") {
+		const current = autoMode.getAutoMode();
+		const next = AUTO_MODE_SETTINGS[(AUTO_MODE_SETTINGS.indexOf(current) + 1) % AUTO_MODE_SETTINGS.length]!;
+		// Entering the highest-autonomy state gets the same explicit confirmation Codex recovery's
+		// own opt-in already gets; leaving it (like disabling enforcement) needs none -- becoming
+		// more conservative is never something to gate behind a confirmation.
+		if (next === "auto-switch") {
+			if (
+				await showConfirmDialog(
+					ctx,
+					"Enable Auto-switch?",
+					"Jittor may switch your active model on its own when a turn's effort clearly calls for a different one, with no confirmation prompt.",
+				)
+			)
+				await effects.setAutoMode(next);
+		} else await effects.setAutoMode(next);
+		return;
+	}
+	if (action.key === "auto-mode-verbose") {
+		await effects.setAutoModeVerbose(!autoMode.isAutoModeVerbose());
+		return;
+	}
 	if (action.key === "enforcement") {
 		if (enforcement.isEnabled()) {
 			if (
@@ -241,19 +289,22 @@ export async function showSettingsPanel(
 	enforcement: EnforcementControl,
 	recovery: CodexRecoveryControl,
 	budgets: UsageBudgetControl,
+	autoMode: AutoModeControl,
 	effects: SettingsEffects = {
 		setEnforcement: (enabled) => enforcement.setEnabled(enabled),
 		setFooter: (enabled) => enforcement.setFooterEnabled(enabled),
 		setRecovery: (enabled) => recovery.setCodexRecoveryEnabled(enabled),
+		setAutoMode: (mode) => autoMode.setAutoMode(mode),
+		setAutoModeVerbose: (verbose) => autoMode.setAutoModeVerbose(verbose),
 	},
 ): Promise<void> {
 	if (ctx.mode !== "tui") {
-		const snapshot = settingsSnapshot(enforcement, recovery, budgets);
+		const snapshot = settingsSnapshot(enforcement, recovery, budgets, autoMode);
 		ctx.ui.notify(["Jittor Settings", ...SETTINGS_KEYS.map((key) => rowText(key, snapshot, plainTheme()))].join("\n"), "info");
 		return;
 	}
 	for (;;) {
-		const snapshot = settingsSnapshot(enforcement, recovery, budgets);
+		const snapshot = settingsSnapshot(enforcement, recovery, budgets, autoMode);
 		const action = await ctx.ui.custom<SettingsAction>((tui, theme, _keybindings, done) => {
 			const panel = createSettingsPanel(snapshot, theme, done);
 			return {
@@ -266,6 +317,6 @@ export async function showSettingsPanel(
 			};
 		});
 		if (!action || action.kind === "close") return;
-		await runSettingsAction(ctx, action, enforcement, recovery, budgets, effects);
+		await runSettingsAction(ctx, action, enforcement, recovery, budgets, effects, autoMode);
 	}
 }

package/extension/src/settings.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { JITTOR_EXTENSION_SETTINGS_FILENAME, JITTOR_STATE_DIRECTORY, USAGE_PERIODS, type UsagePeriod } from "@danypops/jittor";
 import { createAtomicJsonWriter } from "@danypops/vehicle-core";
 import { createNodeAtomicJsonFsAdapter } from "@danypops/vehicle-server/atomic-json";
+import { AUTO_MODE_SETTINGS, type AutoModeSetting } from "./optimization/auto-mode.ts";
 
 const atomicJson = createAtomicJsonWriter({ fs: createNodeAtomicJsonFsAdapter() });
 
@@ -30,17 +31,35 @@ export interface UsageBudgetControl {
 	setUsageTokenBudget(period: UsagePeriod, tokens: number | undefined): void | Promise<void>;
 }
 
-export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl, UsageBudgetControl {}
+export interface AutoModeControl {
+	getAutoMode(): AutoModeSetting;
+	setAutoMode(mode: AutoModeSetting): void | Promise<void>;
+	/** Whether a Suggest-mode dialog opens straight to the full benchmark breakdown instead of requiring the "Details" keypress. Purely a display preference -- never changes what action is taken. */
+	isAutoModeVerbose(): boolean;
+	setAutoModeVerbose(verbose: boolean): void | Promise<void>;
+}
+
+export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl, UsageBudgetControl, AutoModeControl {}
 
 interface ExtensionSettings {
 	enforcementEnabled: boolean;
 	footerEnabled: boolean;
 	codexRecoveryEnabled: boolean;
 	usageTokenBudgets: Partial<Record<UsagePeriod, number>>;
+	/** Suggest, not Auto-switch, is the recorded default -- Auto-switch (an active mutation) is fully available from day one but never silently pre-selected, per this project's shadow-mode-first governance for optimization interventions. */
+	autoMode: AutoModeSetting;
+	autoModeVerbose: boolean;
 }
 
 function defaultSettings(): ExtensionSettings {
-	return { enforcementEnabled: true, footerEnabled: true, codexRecoveryEnabled: false, usageTokenBudgets: {} };
+	return {
+		enforcementEnabled: true,
+		footerEnabled: true,
+		codexRecoveryEnabled: false,
+		usageTokenBudgets: {},
+		autoMode: "suggest",
+		autoModeVerbose: false,
+	};
 }
 
 function parseUsageTokenBudgets(value: unknown): Partial<Record<UsagePeriod, number>> {
@@ -69,6 +88,8 @@ function loadSettings(path: string): ExtensionSettings {
 			footerEnabled: record.footerEnabled !== false,
 			codexRecoveryEnabled: record.codexRecoveryEnabled === true,
 			usageTokenBudgets: parseUsageTokenBudgets(record.usageTokenBudgets),
+			autoMode: AUTO_MODE_SETTINGS.includes(record.autoMode as AutoModeSetting) ? (record.autoMode as AutoModeSetting) : "suggest",
+			autoModeVerbose: record.autoModeVerbose === true,
 		};
 	} catch {
 		return defaultSettings();
@@ -109,5 +130,16 @@ export function persistentEnforcementControl(env: Record<string, string | undefi
 			else settings.usageTokenBudgets[period] = tokens;
 			await persistSettings(path, settings);
 		},
+		getAutoMode: () => settings.autoMode,
+		async setAutoMode(mode): Promise<void> {
+			if (!AUTO_MODE_SETTINGS.includes(mode)) throw new Error("auto mode must be one of off, suggest, auto-switch");
+			settings.autoMode = mode;
+			await persistSettings(path, settings);
+		},
+		isAutoModeVerbose: () => settings.autoModeVerbose,
+		async setAutoModeVerbose(verbose): Promise<void> {
+			settings.autoModeVerbose = verbose;
+			await persistSettings(path, settings);
+		},
 	};
 }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@danypops/pi-jittor",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Pi extension for Jittor token and context observability with optimization controls backed by the @danypops/jittor daemon",
+  "license": "MIT",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],
   "scripts": {
@@ -15,7 +16,7 @@
     "@danypops/vehicle-client": "^0.10.1",
     "@danypops/vehicle-core": "^0.17.1",
     "@danypops/vehicle-server": "^0.25.1",
-    "@danypops/jittor": "^0.18.0",
+    "@danypops/jittor": "^0.20.0",
     "malevich-tui-components": "^0.28.0"
   },
   "peerDependencies": {