pi-ultracode 0.1.0 → 0.1.2

package/src/mode.ts

@@ -2,7 +2,7 @@
  * Ultracode mode controller.
  *
  * Ultracode is a session-scoped effort mode. While on, it:
- *   - raises the thinking level to xhigh (remembering the previous level),
+ *   - raises the thinking level to the model's maximum (remembering the previous level),
  *   - keeps the `workflow` tool active,
  *   - injects a standing "author and run a workflow by default" system block on
  *     every turn, plus an optional token budget,
@@ -12,8 +12,14 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { ULTRACODE_ACTIVE_REMINDER, ULTRACODE_TAGLINE, ultracodeSystemBlock } from "./prompts.ts";
+import {
+  LEGACY_ULTRACODE_THINKING_LEVEL,
+  ULTRACODE_THINKING_LEVEL,
+  isThinkingLevel,
+  type ThinkingLevel,
+} from "./thinking.ts";
 
-export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export type { ThinkingLevel } from "./thinking.ts";
 
 export const MODE_ENTRY_TYPE = "ultracode-mode";
 
@@ -21,20 +27,76 @@ interface PersistedModeState {
   enabled: boolean;
   budgetTotal: number | null;
   previousThinking?: ThinkingLevel;
+  /** `null` records that the setting was originally absent (Pi defaults to medium). */
+  previousDefaultThinking?: ThinkingLevel | null;
+  /** Deferred when the selected model cannot represent the pre-mode level. */
+  pendingPreviousThinking?: ThinkingLevel;
+}
+
+export interface ThinkingPreferenceSnapshot {
+  /** Raw global value; undefined means Pi's implicit medium default. */
+  global: ThinkingLevel | undefined;
+  /** Global + project merged value used by Pi for model switches. */
+  effective: ThinkingLevel | undefined;
+}
+
+/** Adapter for preserving Pi's raw global effort preference while this mode is active. */
+export interface ThinkingPreferenceStore {
+  getThinkingPreference(): ThinkingPreferenceSnapshot;
+  setDefaultThinkingLevel(level: ThinkingLevel | undefined): void | Promise<void>;
+  flush?(): Promise<void>;
 }
 
 export class UltracodeMode {
   private enabled = false;
+  private suspended = false;
   private budgetTotal: number | null = null;
   private previousThinking: ThinkingLevel | undefined;
-  /** The level pi actually applied after clamping "xhigh" to the model's capability. */
+  private previousDefaultThinking: ThinkingLevel | null | undefined;
+  /** Restore a level later if the current non-reasoning model clamps it to off. */
+  private pendingPreviousThinking: ThinkingLevel | undefined;
+  /** The level Pi actually applied after clamping the maximum request. */
   private appliedThinking: ThinkingLevel | undefined;
+  /** Prevent mode-owned thinking changes from being mistaken for manual overrides. */
+  private applyingThinking = false;
+  private thinkingPreferenceStore: ThinkingPreferenceStore | undefined;
+  private preferenceWriteQueue: Promise<void> = Promise.resolve();
+  private preferenceWriteGeneration = 0;
+  private legacyDefaultMigrationPending = false;
+  private pendingClearGeneration = 0;
+  private currentModelSupportsThinking: boolean | undefined;
+  private runtimeSupportsMaxThinking = true;
   private readonly workflowToolName: string;
 
   constructor(workflowToolName: string) {
     this.workflowToolName = workflowToolName;
   }
 
+  /** Bind the settings adapter once the session cwd is known. */
+  bindThinkingPreferenceStore(store: ThinkingPreferenceStore | undefined): void {
+    this.preferenceWriteGeneration++;
+    this.thinkingPreferenceStore = store;
+  }
+
+  /** Track capability explicitly; `off` alone cannot distinguish clamp from intent. */
+  setCurrentModelSupportsThinking(supportsThinking: boolean | undefined): void {
+    this.currentModelSupportsThinking = supportsThinking;
+  }
+
+  /** Configure migration behavior for Pi versions released before `max`. */
+  setRuntimeSupportsMaxThinking(supportsMaxThinking: boolean): void {
+    this.runtimeSupportsMaxThinking = supportsMaxThinking;
+  }
+
+  /** Wait for queued preference restoration before teardown or command completion. */
+  async flushThinkingPreference(): Promise<void> {
+    try {
+      await this.preferenceWriteQueue;
+    } catch {
+      // Pi owns settings error reporting; effort enforcement must remain usable.
+    }
+  }
+
   /** Enable if off, disable if on. Returns the new enabled state. */
   toggle(pi: ExtensionAPI, opts: { budget?: number | null } = {}): boolean {
     if (this.enabled) {
@@ -45,29 +107,100 @@ export class UltracodeMode {
     return true;
   }
 
-  /** The thinking level pi actually applied (xhigh, or clamped down for models that lack it). */
+  /** The thinking level Pi actually applied (`max`, or the model/runtime fallback). */
   getAppliedThinking(): ThinkingLevel | undefined {
     return this.appliedThinking;
   }
 
-  /** The effort level to forward to workflow subagents: xhigh when ultracode is
-   *  on, so each subagent's own session clamps it to THAT subagent model's max
-   *  (mirroring the parent's "request xhigh, clamp per model" contract). This
-   *  keeps subagents at their respective model's max even when they run a
-   *  different model than the parent. Undefined when off, so subagents fall back
-   *  to the session default. */
+  /**
+   * Return the raw maximum request, not the parent's applied value, so every
+   * workflow subagent is clamped independently against its own model.
+   */
   getSubagentThinkingLevel(): ThinkingLevel | undefined {
-    return this.enabled ? "xhigh" : undefined;
+    return this.isEnforcing() ? ULTRACODE_THINKING_LEVEL : undefined;
+  }
+
+  /** Reassert the maximum before a turn or after a model change. */
+  reapplyMaximumThinking(pi: ExtensionAPI): boolean {
+    if (!this.isEnforcing()) return false;
+    this.applyUltracodeThinking(pi);
+    return true;
+  }
+
+  /**
+   * Handle model switches both while active and after a clamped restoration.
+   * Returns true when Ultracode remains active and the UI should be refreshed.
+   */
+  handleModelSelect(pi: ExtensionAPI): boolean {
+    if (this.suspended) return false;
+    this.pendingClearGeneration++;
+    if (this.enabled) {
+      this.applyUltracodeThinking(pi);
+      return true;
+    }
+    if (this.pendingPreviousThinking) {
+      const pending = this.pendingPreviousThinking;
+      this.applyCompatibleThinking(pi, pending);
+      if (this.pendingRestoreSucceeded(pending)) this.pendingPreviousThinking = undefined;
+      this.persist(pi);
+    }
+    return false;
+  }
+
+  /** Restore the pre-mode effective effort without changing persisted mode state. */
+  restorePreviousThinking(pi: ExtensionAPI): void {
+    if (this.enabled && this.previousThinking) this.applyCompatibleThinking(pi, this.previousThinking);
+  }
+
+  /** Stop enforcing synchronously, then restore effort before session teardown. */
+  suspend(pi: ExtensionAPI): void {
+    if (this.suspended) {
+      this.syncWorkflowTool(pi);
+      return;
+    }
+    this.suspended = true;
+    this.restorePreviousThinking(pi);
+    this.syncWorkflowTool(pi);
+  }
+
+  /**
+   * Enforce the mode after an external thinking-level selection. Stale events
+   * and events emitted by this mode are ignored to avoid recursive updates.
+   * Returns true when a manual selection was overridden.
+   */
+  handleThinkingLevelSelect(pi: ExtensionAPI, level: ThinkingLevel): boolean {
+    if (this.suspended || this.applyingThinking) return false;
+    const current = safeGetThinking(pi);
+    if (!current || current !== level) return false;
+    if (!this.enabled) {
+      // Pi emits the same event for a user selection and an automatic model
+      // re-clamp. Defer clearing until model_select has had a chance to consume it.
+      if (this.pendingPreviousThinking) this.deferPendingClear(pi, level);
+      return false;
+    }
+    if (current === this.appliedThinking) return false;
+    this.applyUltracodeThinking(pi);
+    return true;
   }
 
   isEnabled(): boolean {
     return this.enabled;
   }
 
+  isSuspended(): boolean {
+    return this.suspended;
+  }
+
   getBudget(): number | null {
     return this.budgetTotal;
   }
 
+  /** Keep tool availability aligned with the current mode state. */
+  syncWorkflowTool(pi: ExtensionAPI): void {
+    if (this.isEnforcing()) this.activateWorkflowTool(pi);
+    else this.deactivateWorkflowTool(pi);
+  }
+
   tagline(): string {
     return ULTRACODE_TAGLINE;
   }
@@ -75,19 +208,48 @@ export class UltracodeMode {
   /** Turn ultracode on. Idempotent. */
   enable(pi: ExtensionAPI, opts: { budget?: number | null } = {}): void {
     if (opts.budget !== undefined) this.budgetTotal = opts.budget;
+    this.suspended = false;
+    this.pendingPreviousThinking = undefined;
+    this.pendingClearGeneration++;
     if (!this.enabled) {
-      this.previousThinking = safeGetThinking(pi);
+      const current = safeGetThinking(pi);
+      const preference = this.captureThinkingPreference();
+      const effectivePreference = this.runtimeCompatibleThinking(preference.effective) as
+        | ThinkingLevel
+        | undefined;
+      const maxIsUnknownToRuntime = !this.runtimeSupportsMaxThinking
+        && preference.effective === ULTRACODE_THINKING_LEVEL;
+      // A non-reasoning model exposes only `off`; preserve the merged default
+      // that Pi would use when the user later selects a reasoning model. A
+      // pre-max Pi also reports a persisted max preference as off.
+      this.previousThinking = current === "off"
+        && (this.currentModelSupportsThinking !== true || maxIsUnknownToRuntime)
+        ? effectivePreference ?? current
+        : current;
+      this.previousDefaultThinking = this.runtimeCompatibleThinking(preference.global);
+      this.legacyDefaultMigrationPending = false;
       this.enabled = true;
     }
-    this.applyThinking(pi, "xhigh");
-    this.activateWorkflowTool(pi);
+    this.applyUltracodeThinking(pi);
+    this.syncWorkflowTool(pi);
     this.persist(pi);
   }
 
   /** Turn ultracode off, restoring the previous thinking level. */
   disable(pi: ExtensionAPI): void {
-    if (this.enabled && this.previousThinking) this.applyThinking(pi, this.previousThinking);
+    if (!this.enabled) {
+      this.syncWorkflowTool(pi);
+      return;
+    }
+    const previous = this.previousThinking;
+    this.restorePreviousThinking(pi);
+    this.pendingPreviousThinking = previous && !this.pendingRestoreSucceeded(previous)
+      ? previous
+      : undefined;
+    this.pendingClearGeneration++;
     this.enabled = false;
+    this.suspended = false;
+    this.syncWorkflowTool(pi);
     this.persist(pi);
   }
 
@@ -96,21 +258,131 @@ export class UltracodeMode {
     this.persist(pi);
   }
 
-  /** Restore mode state from session entries (called on session_start). */
-  restore(pi: ExtensionAPI, entries: Array<{ type?: string; customType?: string; data?: unknown }>): void {
-    let latest: PersistedModeState | undefined;
+  /** Restore mode state from the active session branch. */
+  restore(
+    pi: ExtensionAPI,
+    entries: Array<{
+      type?: string;
+      customType?: string;
+      data?: unknown;
+      thinkingLevel?: unknown;
+    }>,
+  ): void {
+    const wasEnforcing = this.isEnforcing();
+    this.pendingClearGeneration++;
+    let latestData: unknown;
+    let branchThinking: ThinkingLevel | undefined;
+    let thinkingAfterLatestMode: ThinkingLevel | undefined;
     for (const entry of entries) {
       if (entry.type === "custom" && entry.customType === MODE_ENTRY_TYPE && entry.data) {
-        latest = entry.data as PersistedModeState;
+        latestData = entry.data;
+        thinkingAfterLatestMode = undefined;
+      } else if (entry.type === "thinking_level_change" && isThinkingLevel(entry.thinkingLevel)) {
+        branchThinking = entry.thinkingLevel;
+        if (latestData !== undefined) thinkingAfterLatestMode = entry.thinkingLevel;
       }
     }
-    if (!latest) return;
-    this.budgetTotal = latest.budgetTotal ?? null;
-    this.previousThinking = latest.previousThinking;
-    if (latest.enabled) {
-      this.enabled = true;
-      this.applyThinking(pi, "xhigh");
-      this.activateWorkflowTool(pi);
+
+    const current = safeGetThinking(pi);
+    const preference = this.captureThinkingPreference();
+    const effectivePreference = this.runtimeCompatibleThinking(preference.effective) as
+      | ThinkingLevel
+      | undefined;
+    const globalPreference = this.runtimeCompatibleThinking(preference.global);
+    const latest = parsePersistedModeState(latestData);
+    if (!latest) {
+      const target = this.runtimeCompatibleThinking(
+        branchThinking
+          ?? (wasEnforcing ? this.previousThinking : undefined)
+          ?? effectivePreference,
+      ) as ThinkingLevel | undefined;
+      this.enabled = false;
+      this.suspended = false;
+      this.budgetTotal = null;
+      this.pendingPreviousThinking = undefined;
+      this.previousThinking = target;
+      this.previousDefaultThinking = globalPreference;
+      this.legacyDefaultMigrationPending = false;
+      this.appliedThinking = current;
+      this.syncWorkflowTool(pi);
+      if (target && current !== target) this.applyCompatibleThinking(pi, target);
+      if (target && !this.pendingRestoreSucceeded(target)) {
+        this.pendingPreviousThinking = target;
+        this.persist(pi);
+      } else {
+        this.previousThinking = undefined;
+        this.previousDefaultThinking = undefined;
+      }
+      return;
+    }
+
+    this.suspended = false;
+    this.enabled = latest.enabled;
+    this.budgetTotal = latest.budgetTotal;
+    this.syncWorkflowTool(pi);
+    const maxIsUnknownToRuntime = !this.runtimeSupportsMaxThinking
+      && preference.effective === ULTRACODE_THINKING_LEVEL;
+    this.previousThinking = latest.previousThinking
+      ?? (current === "off"
+        && (this.currentModelSupportsThinking !== true || maxIsUnknownToRuntime)
+        ? effectivePreference ?? current
+        : current);
+
+    // Pre-preference-store releases persisted only previousThinking while their
+    // active xhigh request polluted Pi's global default. Recover that baseline
+    // once instead of treating the known Ultracode value as a user preference.
+    const migratesLegacyDefault = latest.enabled
+      && latest.previousDefaultThinking === undefined
+      && latest.previousThinking !== undefined
+      && (preference.global === LEGACY_ULTRACODE_THINKING_LEVEL
+        || preference.global === ULTRACODE_THINKING_LEVEL);
+    this.previousDefaultThinking = migratesLegacyDefault
+      ? this.runtimeCompatibleThinking(latest.previousThinking)
+      : preference.global !== undefined
+        ? globalPreference
+        : this.runtimeCompatibleThinking(latest.previousDefaultThinking);
+    this.legacyDefaultMigrationPending = migratesLegacyDefault;
+
+    this.pendingPreviousThinking = this.enabled ? undefined : latest.pendingPreviousThinking;
+    if (this.enabled) {
+      this.applyUltracodeThinking(pi);
+      if (migratesLegacyDefault) {
+        this.queueDefaultThinkingRestore(() => {
+          this.legacyDefaultMigrationPending = false;
+          this.persist(pi);
+        });
+      }
+      return;
+    }
+
+    if (this.pendingPreviousThinking) {
+      if (thinkingAfterLatestMode !== undefined) {
+        // A thinking entry after the disabled mode snapshot is an explicit user
+        // choice and supersedes the older deferred restoration.
+        const target = this.runtimeCompatibleThinking(thinkingAfterLatestMode) as ThinkingLevel;
+        this.pendingPreviousThinking = undefined;
+        this.previousThinking = target;
+        this.appliedThinking = current;
+        if (current !== target) this.applyCompatibleThinking(pi, target);
+        if (!this.pendingRestoreSucceeded(target)) this.pendingPreviousThinking = target;
+        this.persist(pi);
+      } else if (this.currentModelSupportsThinking === true) {
+        const pending = this.pendingPreviousThinking;
+        this.applyCompatibleThinking(pi, pending);
+        if (this.pendingRestoreSucceeded(pending)) this.pendingPreviousThinking = undefined;
+        this.persist(pi);
+      }
+      return;
+    }
+
+    const target = this.runtimeCompatibleThinking(branchThinking ?? latest.previousThinking) as
+      | ThinkingLevel
+      | undefined;
+    this.appliedThinking = current;
+    if (target && current !== target) this.applyCompatibleThinking(pi, target);
+    if (target && !this.pendingRestoreSucceeded(target)) {
+      this.pendingPreviousThinking = target;
+      this.persist(pi);
     }
   }
 
@@ -119,7 +391,7 @@ export class UltracodeMode {
    * turn's system prompt when enabled.
    */
   beforeAgentStart(event: { systemPrompt: string }): { systemPrompt: string } | undefined {
-    if (!this.enabled) return undefined;
+    if (!this.isEnforcing()) return undefined;
     const block = ultracodeSystemBlock({ budgetTotal: this.budgetTotal });
     return { systemPrompt: `${event.systemPrompt}\n\n${block}\n\n${ULTRACODE_ACTIVE_REMINDER}` };
   }
@@ -127,23 +399,124 @@ export class UltracodeMode {
   statusLine(): string {
     if (!this.enabled) return `ultracode: off`;
     const parts = ["ultracode: on"];
-    // Show the level that actually applied (xhigh, or whatever the model clamped to).
-    if (this.appliedThinking) parts.push(`thinking ${this.appliedThinking}`);
+    // Show the level that actually applied, including compatibility/model fallback.
+    if (this.appliedThinking) parts.push(this.appliedThinking);
     if (this.budgetTotal) parts.push(`budget ~${formatTokens(this.budgetTotal)}`);
     return parts.join(" · ");
   }
 
+  private applyUltracodeThinking(pi: ExtensionAPI): void {
+    const writeGeneration = this.preferenceWriteGeneration;
+    this.applyCompatibleThinking(pi, ULTRACODE_THINKING_LEVEL);
+    // Pi normally skips persistence when the effective level is unchanged, but
+    // the extension API does not promise that. Defensively restore the raw
+    // baseline even after a stable max -> max request.
+    if (writeGeneration === this.preferenceWriteGeneration) {
+      this.queueDefaultThinkingRestore();
+    }
+  }
+
+  /** Apply max compatibly and return the concrete level accepted as success. */
+  private applyCompatibleThinking(pi: ExtensionAPI, level: ThinkingLevel): ThinkingLevel {
+    this.applyThinking(pi, level);
+    if (level === ULTRACODE_THINKING_LEVEL && this.appliedThinking !== level) {
+      // Modern Pi clamps max per model. Pre-max Pi may treat it as unknown, so
+      // retry xhigh for both activation and restoration of persisted max state.
+      this.applyThinking(pi, LEGACY_ULTRACODE_THINKING_LEVEL);
+      return LEGACY_ULTRACODE_THINKING_LEVEL;
+    }
+    return level;
+  }
+
   private applyThinking(pi: ExtensionAPI, level: ThinkingLevel): void {
+    const wasApplying = this.applyingThinking;
+    const before = safeGetThinking(pi);
+    this.applyingThinking = true;
     try {
-      // pi clamps the requested level down to the model's capability (e.g. "high",
-      // or "off" for non-reasoning models); it never throws. Read back what stuck.
-      pi.setThinkingLevel(level);
+      // Pi clamps the request and persists the effective level. Preference
+      // restoration is queued after Pi's own SettingsManager chain drains.
+      pi.setThinkingLevel(level as any);
       this.appliedThinking = safeGetThinking(pi) ?? level;
     } catch {
       this.appliedThinking = safeGetThinking(pi);
+    } finally {
+      if (this.appliedThinking !== before) this.queueDefaultThinkingRestore();
+      this.applyingThinking = wasApplying;
+    }
+  }
+
+  isEnforcing(): boolean {
+    return this.enabled && !this.suspended;
+  }
+
+  private pendingRestoreSucceeded(pending: ThinkingLevel): boolean {
+    if (this.appliedThinking === pending) return true;
+    return pending === ULTRACODE_THINKING_LEVEL
+      && !this.runtimeSupportsMaxThinking
+      && this.appliedThinking !== undefined
+      && this.appliedThinking !== "off";
+  }
+
+  private runtimeCompatibleThinking(
+    level: ThinkingLevel | null | undefined,
+  ): ThinkingLevel | null | undefined {
+    return level === ULTRACODE_THINKING_LEVEL && !this.runtimeSupportsMaxThinking
+      ? LEGACY_ULTRACODE_THINKING_LEVEL
+      : level;
+  }
+
+  private captureThinkingPreference(): {
+    global: ThinkingLevel | null | undefined;
+    effective: ThinkingLevel | undefined;
+  } {
+    if (!this.thinkingPreferenceStore) return { global: undefined, effective: undefined };
+    try {
+      const preference = this.thinkingPreferenceStore.getThinkingPreference();
+      return {
+        global: isThinkingLevel(preference.global) ? preference.global : null,
+        effective: isThinkingLevel(preference.effective) ? preference.effective : undefined,
+      };
+    } catch {
+      return { global: undefined, effective: undefined };
     }
   }
 
+  private queueDefaultThinkingRestore(onSuccess?: () => void): void {
+    const store = this.thinkingPreferenceStore;
+    const baseline = this.runtimeCompatibleThinking(this.previousDefaultThinking);
+    if (!store || baseline === undefined) return;
+    const generation = ++this.preferenceWriteGeneration;
+    this.preferenceWriteQueue = this.preferenceWriteQueue
+      .catch(() => {})
+      .then(waitForSettingsWrites)
+      .then(async () => {
+        if (generation !== this.preferenceWriteGeneration) return;
+        const currentGlobal = this.captureThinkingPreference().global;
+        if (currentGlobal !== baseline) {
+          await store.setDefaultThinkingLevel(baseline ?? undefined);
+          await store.flush?.();
+        }
+        if (generation === this.preferenceWriteGeneration) onSuccess?.();
+      })
+      .catch(() => {
+        // Keep the session usable even when settings cannot be restored.
+      });
+  }
+
+  private deferPendingClear(pi: ExtensionAPI, level: ThinkingLevel): void {
+    const generation = ++this.pendingClearGeneration;
+    setImmediate(() => {
+      if (
+        generation !== this.pendingClearGeneration
+        || this.enabled
+        || this.suspended
+        || safeGetThinking(pi) !== level
+      ) return;
+      this.pendingPreviousThinking = undefined;
+      this.persist(pi);
+    });
+  }
+
   private activateWorkflowTool(pi: ExtensionAPI): void {
     try {
       const active = pi.getActiveTools();
@@ -151,7 +524,18 @@ export class UltracodeMode {
         pi.setActiveTools([...active, this.workflowToolName]);
       }
     } catch {
-      // ignore
+      // Mode enforcement remains usable when tool selection is unavailable.
+    }
+  }
+
+  private deactivateWorkflowTool(pi: ExtensionAPI): void {
+    try {
+      const active = pi.getActiveTools();
+      if (active.includes(this.workflowToolName)) {
+        pi.setActiveTools(active.filter((name) => name !== this.workflowToolName));
+      }
+    } catch {
+      // The execution guards still fail closed when selection cannot be updated.
     }
   }
 
@@ -160,6 +544,10 @@ export class UltracodeMode {
       enabled: this.enabled,
       budgetTotal: this.budgetTotal,
       previousThinking: this.previousThinking,
+      previousDefaultThinking: this.legacyDefaultMigrationPending
+        ? undefined
+        : this.previousDefaultThinking,
+      pendingPreviousThinking: this.pendingPreviousThinking,
     };
     try {
       pi.appendEntry(MODE_ENTRY_TYPE, state);
@@ -169,9 +557,32 @@ export class UltracodeMode {
   }
 }
 
+function parsePersistedModeState(data: unknown): PersistedModeState | undefined {
+  if (!data || typeof data !== "object") return undefined;
+  const value = data as Record<string, unknown>;
+  const budget = value.budgetTotal;
+  const previousDefault = value.previousDefaultThinking;
+  return {
+    enabled: value.enabled === true,
+    budgetTotal: typeof budget === "number" && Number.isFinite(budget) && budget > 0 ? budget : null,
+    previousThinking: isThinkingLevel(value.previousThinking) ? value.previousThinking : undefined,
+    previousDefaultThinking: previousDefault === null || isThinkingLevel(previousDefault)
+      ? previousDefault
+      : undefined,
+    pendingPreviousThinking: isThinkingLevel(value.pendingPreviousThinking)
+      ? value.pendingPreviousThinking
+      : undefined,
+  };
+}
+
+function waitForSettingsWrites(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
 function safeGetThinking(pi: ExtensionAPI): ThinkingLevel | undefined {
   try {
-    return pi.getThinkingLevel() as ThinkingLevel;
+    const level = pi.getThinkingLevel();
+    return isThinkingLevel(level) ? level : undefined;
   } catch {
     return undefined;
   }

package/src/prompts.ts

@@ -7,7 +7,7 @@
  */
 
 /** One-line description shown by `/ultracode status` and the footer. */
-export const ULTRACODE_TAGLINE = "xhigh thinking + dynamic workflow orchestration";
+export const ULTRACODE_TAGLINE = "max thinking + dynamic workflow orchestration";
 
 /**
  * The standing system-prompt block injected on every turn while ultracode is on.
@@ -59,7 +59,7 @@ export const WORKFLOW_PROMPT_SNIPPET =
 
 /** Guideline bullets appended to the Guidelines section when the tool is active. */
 export const WORKFLOW_GUIDELINES: string[] = [
-  "Use the workflow tool to decompose-and-cover in parallel, to gather independent perspectives that adversarially verify each other, or to take on scale a single context can't hold. Outside ultracode mode, reserve it for explicit fan-out / multi-agent requests.",
+  "While Ultracode is enabled, use the workflow tool to decompose-and-cover in parallel, gather independent perspectives that adversarially verify each other, or take on scale one context can't hold.",
   "For the workflow tool, pass one raw JavaScript string in the required `script` parameter; no Markdown fences, no prose around the script.",
   "For the workflow tool, the script's first statement must be `export const meta = { name: 'short_snake_case', description: 'non-empty human description' }`. meta must be a pure literal: no variables, function calls, spreads, or template interpolation. meta.phases is optional and should mirror your phase() titles.",
   "For the workflow tool, write plain JavaScript after the meta export. No TypeScript syntax, imports, require(), fs, network, Date.now(), Math.random(), or new Date() (they break determinism and resume). Stamp timestamps after the workflow returns; vary randomness by agent index.",

package/src/thinking.ts

@@ -0,0 +1,27 @@
+/** Shared thinking-level vocabulary for the mode, workflow agents, and config parser. */
+
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+/** Ultracode always asks Pi for the strongest effort the selected model supports. */
+export const ULTRACODE_THINKING_LEVEL: ThinkingLevel = "max";
+
+/** Compatibility retry for Pi versions released before the `max` level existed. */
+export const LEGACY_ULTRACODE_THINKING_LEVEL: ThinkingLevel = "xhigh";
+
+const THINKING_LEVEL_SET = new Set<string>(THINKING_LEVELS);
+
+export function isThinkingLevel(value: unknown): value is ThinkingLevel {
+  return typeof value === "string" && THINKING_LEVEL_SET.has(value);
+}
+
+/** Whether this Pi runtime recognizes `max` as a first-class thinking level. */
+export function piVersionSupportsMaxThinking(version: string): boolean {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (!match) return true;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const patch = Number(match[3]);
+  return major > 0 || minor > 80 || (minor === 80 && patch >= 6);
+}