pi-ultracode 0.5.0 → 0.7.0

package/README.md

@@ -33,7 +33,7 @@ Current releases are tested with Pi 0.84.
 
 ## Core features
 
-- **Adaptive semantic depth** — choose `auto`, `focused`, `standard`, or `deep`; `auto` selects the smallest evidence-sufficient depth and `off` restores the previous thinking level.
+- **Adaptive semantic depth** — choose `auto`, `focused`, `standard`, or `deep`; `auto` selects the smallest evidence-sufficient depth while the parent effort remains under user control.
 - **Explicit workflows** — compose work with `agent()`, `parallel()`, `pipeline()`, and nested `workflow()` calls.
 - **Independent subagents** — each agent gets its own Pi session, context, tools, model selection, and optional role.
 - **Parallel worktree isolation** — writing agents can work in temporary git worktrees before their patches are integrated.
@@ -63,9 +63,9 @@ Useful commands:
 | `/ultracode auto` | Select adaptive semantic-depth routing |
 | `/ultracode focused` | Fix the lightweight, narrowly scoped policy |
 | `/ultracode standard` | Fix the balanced policy with conditional verification |
-| `/ultracode deep` | Fix the high-assurance policy with deep verification and max effort |
-| `/ultracode off` | Disable it and restore the previous thinking level |
-| `/ultracode status` | Show the configured mode and effective thinking level |
+| `/ultracode deep` | Fix the high-assurance policy with deep verification |
+| `/ultracode off` | Disable it without changing the parent effort |
+| `/ultracode status` | Show the configured semantic-depth mode |
 | `/workflows` or `F6` | Open the workflow browser |
 | `/workflows <runId>` | Open a specific run |
 | `/workflows abort` | Abort active runs |
@@ -83,7 +83,7 @@ Depth is semantic, not time-based:
 
 Research stops when key claims have direct evidence, no material conflict or unresolved high-risk question remains, and another round would repeat known evidence. Wall-clock time, deadlines, and duration limits are never used to choose or stop analysis depth. `maxAgents` and `reserveAgents` remain structural admission limits.
 
-Focused defaults to medium effort, auto and standard to high, and deep to max; individual workflow agents can still override effort with a model suffix. A separate skeptic or synthesis agent is not automatic.
+Ultracode never changes the parent session's effort. For workflow children, the parent selects effort per assigned task with a model suffix: typically `:medium` for bounded discovery or synthesis, `:high` for substantive analysis or implementation, and `:max` only for deep or decisive high-risk verification. The workflow UI reports each child's actual model-clamped effort. If no suffix is supplied, the child uses its normal user/model configuration. A separate skeptic or synthesis agent is not automatic.
 
 ## Workflow example
 

package/README.zh-CN.md

@@ -33,7 +33,7 @@ pi --ultracode
 
 ## 核心特性
 
-- **自适应语义深度**：可选择 `auto`、`focused`、`standard` 或 `deep`；`auto` 使用证据充分的最小深度，关闭时恢复之前的思考强度。
+- **自适应语义深度**：可选择 `auto`、`focused`、`standard` 或 `deep`；`auto` 使用证据充分的最小深度，父代理 effort 始终由用户控制。
 - **显式工作流**：通过 `agent()`、`parallel()`、`pipeline()` 和嵌套 `workflow()` 组合任务。
 - **独立子代理**：每个代理拥有独立的 Pi 会话、上下文、工具、模型选择和可选角色。
 - **并行 worktree 隔离**：写入型代理可在临时 git worktree 中工作，再集成补丁。
@@ -63,13 +63,18 @@ Pi 会自行判断工作流是否有帮助。小任务仍可继续使用普通
 | `/ultracode auto` | 使用自适应语义深度路由 |
 | `/ultracode focused` | 固定使用轻量、聚焦的分析策略 |
 | `/ultracode standard` | 固定使用平衡策略和条件验证 |
-| `/ultracode deep` | 固定使用高保障深度验证和 max effort |
-| `/ultracode off` | 关闭并恢复之前的思考强度 |
-| `/ultracode status` | 查看配置模式和实际思考强度 |
+| `/ultracode deep` | 固定使用高保障深度验证 |
+| `/ultracode off` | 关闭且不改变父代理 effort |
+| `/ultracode status` | 查看配置的语义深度模式 |
+| `/ultracode default on` | 全局默认开启，新会话使用 `auto` |
+| `/ultracode default off` | 取消默认开启 |
+| `/ultracode default` | 查看全局启动默认值 |
 | `/workflows` 或 `F6` | 打开工作流浏览器 |
 | `/workflows <runId>` | 打开指定运行 |
 | `/workflows abort` | 中止活动运行 |
 
+`/ultracode default on|off` 只修改启动默认值，不切换当前会话的模式，也不改变 effort。设置保存在 `~/.pi/agent/ultracode.json`（遵循 `PI_CODING_AGENT_DIR`），跨项目和重启生效；未设置时默认关闭。启动时，只有当前分支没有保存 Ultracode 模式才应用默认值，已有的 `off` 或深度选择在 reload、resume、fork 后继续保留。显式 `pi --ultracode` 仍可启用 `auto`。如需立即开启当前会话，执行 `/ultracode auto`。
+
 按 `Esc` 可取消正在运行的工作流。在 Pi 的 fullscreen TUI 中，请在工作流详情内使用 `Ctrl+PageUp`、`Ctrl+PageDown` 和 `Ctrl+End`。
 
 ## 分析深度
@@ -83,7 +88,7 @@ Pi 会自行判断工作流是否有帮助。小任务仍可继续使用普通
 
 当关键结论已有直接证据、没有实质冲突或未解决的高风险问题，且下一轮只会重复已知证据时停止。墙钟时间、deadline 和 duration limit 不得用于选择或停止分析深度。`maxAgents` 与 `reserveAgents` 继续作为结构性准入限制。
 
-Focused 默认使用 medium effort，auto 和 standard 默认使用 high，deep 使用 max；单个 workflow agent 仍可通过模型后缀覆盖 effort。skeptic 和独立 synthesis agent 都不是默认步骤。
+Ultracode 不会修改父会话的 effort。对于 workflow 子代理，父代理会按具体任务通过模型后缀选择 effort：边界明确的搜索或汇总通常使用 `:medium`，实质分析或实现使用 `:high`，只有深度调查或决定性的高风险验证才使用 `:max`。Workflow UI 会展示每个子代理经模型裁剪后实际生效的 effort；未指定后缀时，子会话使用正常的用户/模型配置。skeptic 和独立 synthesis agent 都不是默认步骤。
 
 ## 工作流示例
 

package/extensions/ultracode.ts

@@ -5,16 +5,11 @@
  * workflow orchestration, and the `/ultracode` / `/workflows` commands.
  */
 
-import {
-  getAgentDir,
-  SettingsManager,
-  VERSION as PI_VERSION,
-  type ExtensionAPI,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createWorkflowTool, type WorkflowToolDeps } from "../src/workflow/tool.ts";
 import { UltracodeMode, type ThinkingPreferenceStore } from "../src/mode.ts";
-import { isThinkingLevel, piVersionSupportsMaxThinking } from "../src/thinking.ts";
 import { registerCommands } from "../src/commands.ts";
+import { UltracodePreferences, type UltracodePreferenceStore } from "../src/preferences.ts";
 import { WorkflowRegistry } from "../src/workflow/registry.ts";
 
 export interface ThinkingPreferenceContext {
@@ -23,7 +18,8 @@ export interface ThinkingPreferenceContext {
 }
 
 export interface UltracodeExtensionDeps extends Partial<WorkflowToolDeps> {
-  /** SDK-host seam when the active profile differs from Pi's ambient agent dir. */
+  preferences?: UltracodePreferenceStore;
+  /** @deprecated Parent effort is user-owned; retained for source compatibility. */
   createThinkingPreferenceStore?: (
     context: ThinkingPreferenceContext,
   ) => ThinkingPreferenceStore | undefined;
@@ -31,22 +27,21 @@ export interface UltracodeExtensionDeps extends Partial<WorkflowToolDeps> {
 
 export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensionDeps = {}): void {
   const mode = new UltracodeMode("workflow");
-  mode.setRuntimeSupportsMaxThinking(piVersionSupportsMaxThinking(PI_VERSION));
   const {
-    createThinkingPreferenceStore = createPiThinkingPreferenceStore,
+    createThinkingPreferenceStore: _unusedThinkingPreferenceStore,
+    preferences = new UltracodePreferences(),
     ...workflowDeps
   } = extraDeps;
 
   const registry = workflowDeps.registry ?? new WorkflowRegistry();
   const workflowTool = createWorkflowTool({
-    getThinkingLevel: () => mode.getSubagentThinkingLevel(),
     ...workflowDeps,
     registry,
     isExecutionAllowed: () => mode.isEnforcing(),
   });
   pi.registerTool(workflowTool);
 
-  registerCommands(pi, mode, registry);
+  registerCommands(pi, mode, registry, preferences);
 
   // Opt-in via CLI flag: `pi --ultracode`.
   pi.registerFlag("ultracode", {
@@ -72,103 +67,53 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    await mode.flushThinkingPreference();
-    mode.setCurrentModelSupportsThinking(ctx.model ? Boolean(ctx.model.reasoning) : undefined);
-    try {
-      mode.bindThinkingPreferenceStore(createThinkingPreferenceStore({
-        cwd: ctx.cwd,
-        projectTrusted: ctx.isProjectTrusted(),
-      }));
-    } catch {
-      mode.bindThinkingPreferenceStore(undefined);
-    }
     // Restore persisted mode state across reload / resume / fork.
+    let hasSavedMode = true;
     try {
       // Mode entries are branch-local; discarded future branches must not win.
-      mode.restore(pi, ctx.sessionManager.getBranch() as any);
+      hasSavedMode = mode.restore(pi, ctx.sessionManager.getBranch() as any);
     } catch {
-      // ignore
+      // Do not apply a startup default when branch restoration failed.
     }
     if (!mode.isEnabled() && pi.getFlag?.("ultracode") === true) {
       mode.enable(pi, "auto");
+    } else if (!hasSavedMode && !mode.isEnabled()) {
+      try {
+        if (preferences.getDefaultEnabled()) mode.enable(pi, "auto");
+      } catch (error) {
+        ctx.ui.notify(`Failed to read Ultracode default: ${String(error)}`, "warning");
+      }
     }
-    // Registration makes extension tools discoverable; activation remains opt-in.
+    // Registration makes tools discoverable; activation follows the chosen mode.
     mode.syncWorkflowTool(pi);
-    await mode.flushThinkingPreference();
     if (ctx.hasUI) {
-      ctx.ui.setStatus("ultracode", mode.isEnabled() ? mode.statusLine() : undefined);
+      ctx.ui.setStatus(
+        "ultracode",
+        mode.isEnabled() ? mode.statusLine((label) => ctx.ui.theme.fg("accent", label)) : undefined,
+      );
     }
   });
 
   pi.on("session_tree", async (_event, ctx) => {
-    await mode.flushThinkingPreference();
     if (mode.isSuspended()) return;
-    mode.setCurrentModelSupportsThinking(ctx.model ? Boolean(ctx.model.reasoning) : undefined);
     mode.restore(pi, ctx.sessionManager.getBranch() as any);
-    await mode.flushThinkingPreference();
     if (ctx.hasUI) {
-      ctx.ui.setStatus("ultracode", mode.isEnabled() ? mode.statusLine() : undefined);
+      ctx.ui.setStatus(
+        "ultracode",
+        mode.isEnabled() ? mode.statusLine((label) => ctx.ui.theme.fg("accent", label)) : undefined,
+      );
     }
   });
 
-  pi.on("model_select", async (event, ctx) => {
-    mode.setCurrentModelSupportsThinking(Boolean(event.model.reasoning));
-    const refreshStatus = mode.handleModelSelect(pi);
-    await mode.flushThinkingPreference();
-    if (refreshStatus && ctx.hasUI) ctx.ui.setStatus("ultracode", mode.statusLine());
-  });
-
-  pi.on("thinking_level_select", async (event, ctx) => {
-    if (!mode.handleThinkingLevelSelect(pi, event.level)) return;
-    await mode.flushThinkingPreference();
-    if (ctx.hasUI) ctx.ui.setStatus("ultracode", mode.statusLine());
-  });
-
   pi.on("session_shutdown", async () => {
-    // Quiesce first so late model/effort events cannot undo restoration. The
     // The persisted configured mode remains active for reload/resume/fork replacements.
     mode.suspend(pi);
-    await mode.flushThinkingPreference();
   });
 
   pi.on("before_agent_start", async (event) => {
-    // Reconcile the tool schema and always append the standing block on an
+    // Reconcile tool availability and append the standing policy on every
     // enforcing turn, even when another active-tool writer caused drift.
     mode.syncWorkflowTool(pi);
-    mode.reapplyConfiguredThinking(pi);
-    await mode.flushThinkingPreference();
     return mode.beforeAgentStart(event);
   });
 }
-
-function createPiThinkingPreferenceStore(
-  context: ThinkingPreferenceContext,
-): ThinkingPreferenceStore {
-  const createSettings = () => SettingsManager.create(
-    context.cwd,
-    getAgentDir(),
-    { projectTrusted: context.projectTrusted },
-  );
-  return {
-    getThinkingPreference() {
-      // Use a fresh manager so a selection made after session_start is visible;
-      // SettingsManager instances intentionally keep their own cached snapshot.
-      const settings = createSettings();
-      const global = settings.getGlobalSettings().defaultThinkingLevel;
-      const effective = settings.getDefaultThinkingLevel();
-      return {
-        global: isThinkingLevel(global) ? global : undefined,
-        effective: isThinkingLevel(effective) ? effective : "medium",
-      };
-    },
-    async setDefaultThinkingLevel(level) {
-      // Use a fresh queue after the mode's macrotask barrier. This serializes
-      // behind Pi's already-enqueued writes instead of racing a long-lived peer.
-      const settings = createSettings();
-      // An absent setting is semantically Pi's `medium` default. SettingsManager
-      // has no unset operation, so restore that equivalent value explicitly.
-      settings.setDefaultThinkingLevel((level ?? "medium") as any);
-      await settings.flush();
-    },
-  };
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ultracode",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Adaptive semantic-depth workflow orchestration for Pi, with focused, standard, and deep modes, isolated subagents, worktree delivery, structured output, and durable resume.",
   "type": "module",
   "keywords": [

package/src/commands.ts

@@ -5,34 +5,60 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { ACTIVE_ULTRACODE_MODES, isActiveUltracodeMode } from "./depth.ts";
 import type { UltracodeMode } from "./mode.ts";
+import type { UltracodePreferenceStore } from "./preferences.ts";
 import type { WorkflowRegistry } from "./workflow/registry.ts";
 import { workflowRunsDir } from "./workflow/tool.ts";
 import { openWorkflowOverlay } from "./workflow/workflow-overlay.ts";
 
-export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode, registry: WorkflowRegistry): void {
+export function registerCommands(
+  pi: ExtensionAPI,
+  mode: UltracodeMode,
+  registry: WorkflowRegistry,
+  preferences: UltracodePreferenceStore,
+): void {
   pi.registerCommand("ultracode", {
-    description: "Toggle adaptive Ultracode, or select a fixed semantic depth: auto|focused|standard|deep|off|status",
+    description: "Toggle Ultracode, select auto|focused|standard|deep|off|status, or set default on|off",
     getArgumentCompletions(prefix: string) {
-      return [...ACTIVE_ULTRACODE_MODES, "off", "status"]
+      return [...ACTIVE_ULTRACODE_MODES, "off", "status", "default", "default on", "default off"]
         .filter((value) => value.startsWith(prefix))
         .map((value) => ({ value, label: value }));
     },
     handler: async (args: string, ctx) => {
-      mode.setCurrentModelSupportsThinking(ctx.model ? Boolean(ctx.model.reasoning) : undefined);
       const parts = args.trim().split(/\s+/).filter(Boolean);
       const sub = (parts[0] ?? "").toLowerCase();
 
       // Bare `/ultracode` enables auto from off and disables any active mode.
       if (sub === "") {
         const nowOn = mode.toggle(pi);
-        await mode.flushThinkingPreference();
         ctx.ui.notify(
           nowOn
             ? `Ultracode auto — ${mode.statusLine()}`
-            : "Ultracode off — thinking restored and workflow tool disabled.",
+            : "Ultracode off — workflow tool disabled; parent effort unchanged.",
           "info",
         );
-        ctx.ui.setStatus("ultracode", nowOn ? mode.statusLine() : undefined);
+        ctx.ui.setStatus(
+          "ultracode",
+          nowOn ? mode.statusLine((label) => ctx.ui.theme.fg("accent", label)) : undefined,
+        );
+        return;
+      }
+
+      if (sub === "default") {
+        const value = parts[1]?.toLowerCase();
+        if (parts.length > 2 || (value !== undefined && value !== "on" && value !== "off")) {
+          ctx.ui.notify("Usage: /ultracode default [on|off]", "error");
+          return;
+        }
+        try {
+          if (value !== undefined) preferences.setDefaultEnabled(value === "on");
+          const enabled = preferences.getDefaultEnabled();
+          ctx.ui.notify(
+            `Ultracode default ${enabled ? "on (auto)" : "off"} — global startup preference; current session unchanged.`,
+            "info",
+          );
+        } catch (error) {
+          ctx.ui.notify(`Failed to ${value === undefined ? "read" : "save"} Ultracode default: ${String(error)}`, "error");
+        }
         return;
       }
 
@@ -48,8 +74,7 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode, registry
 
       if (sub === "off") {
         mode.disable(pi);
-        await mode.flushThinkingPreference();
-        ctx.ui.notify("Ultracode off — thinking restored and workflow tool disabled.", "info");
+        ctx.ui.notify("Ultracode off — workflow tool disabled; parent effort unchanged.", "info");
         ctx.ui.setStatus("ultracode", undefined);
         return;
       }
@@ -60,9 +85,11 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode, registry
       }
 
       mode.enable(pi, sub);
-      await mode.flushThinkingPreference();
       ctx.ui.notify(`Ultracode ${sub} — ${mode.statusLine()}`, "info");
-      ctx.ui.setStatus("ultracode", mode.statusLine());
+      ctx.ui.setStatus(
+        "ultracode",
+        mode.statusLine((label) => ctx.ui.theme.fg("accent", label)),
+      );
     },
   });
 
@@ -100,5 +127,5 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode, registry
 }
 
 function ultracodeUsage(): string {
-  return "Usage: /ultracode [auto|focused|standard|deep|off|status]";
+  return "Usage: /ultracode [auto|focused|standard|deep|off|status] or /ultracode default [on|off]";
 }

package/src/depth.ts

@@ -1,4 +1,4 @@
-/** Ultracode's configured analysis modes and their default reasoning effort. */
+/** Ultracode's configured semantic analysis-depth modes. */
 
 import type { ThinkingLevel } from "./thinking.ts";
 
@@ -18,10 +18,9 @@ export function isUltracodeModeName(value: unknown): value is UltracodeModeName
 }
 
 /**
- * Default effort for the parent turn and for child agents that do not override
- * it explicitly. Auto starts from the balanced standard effort; its prompt
- * policy can route individual workflow agents lower or higher as evidence
- * requires. Pi still clamps each request to the selected model's capabilities.
+ * @deprecated Legacy mode-to-effort mapping retained for API compatibility.
+ * Ultracode no longer applies it to the parent or as a workflow child default;
+ * each child selects effort per task and Pi clamps it to model capabilities.
  */
 export function thinkingLevelForMode(mode: UltracodeModeName): ThinkingLevel | undefined {
   switch (mode) {

package/src/mode.ts

@@ -2,8 +2,7 @@
  * Ultracode mode controller.
  *
  * Ultracode is a session-scoped semantic analysis-depth mode. While active, it:
- *   - applies the configured mode's default thinking level while preserving the
- *     user's previous level,
+ *   - leaves the parent session's thinking level under user control,
  *   - keeps the `workflow` tool active,
  *   - injects the configured auto/focused/standard/deep policy on every turn,
  *   - persists branch-local mode state across reload, resume, fork, and compaction.
@@ -12,17 +11,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   isActiveUltracodeMode,
-  thinkingLevelForMode,
   type ActiveUltracodeMode,
   type UltracodeModeName,
 } from "./depth.ts";
 import { ULTRACODE_ACTIVE_REMINDER, ULTRACODE_TAGLINE, ultracodeSystemBlock } from "./prompts.ts";
-import {
-  LEGACY_ULTRACODE_THINKING_LEVEL,
-  ULTRACODE_THINKING_LEVEL,
-  isThinkingLevel,
-  type ThinkingLevel,
-} from "./thinking.ts";
+import type { ThinkingLevel } from "./thinking.ts";
 
 export type { ThinkingLevel } from "./thinking.ts";
 
@@ -30,21 +23,15 @@ export const MODE_ENTRY_TYPE = "ultracode-mode";
 
 interface PersistedModeState {
   mode: UltracodeModeName;
-  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;
 }
 
+/** @deprecated Ultracode no longer reads or writes the parent's effort preference. */
 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. */
+/** @deprecated Ultracode no longer reads or writes the parent's effort preference. */
 export interface ThinkingPreferenceStore {
   getThinkingPreference(): ThinkingPreferenceSnapshot;
   setDefaultThinkingLevel(level: ThinkingLevel | undefined): void | Promise<void>;
@@ -54,51 +41,23 @@ export interface ThinkingPreferenceStore {
 export class UltracodeMode {
   private mode: UltracodeModeName = "off";
   private suspended = false;
-  private previousThinking: ThinkingLevel | undefined;
-  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 configured 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;
-  }
+  /** @deprecated Parent effort is user-owned; retained as a compatibility no-op. */
+  bindThinkingPreferenceStore(_store: ThinkingPreferenceStore | undefined): void {}
 
-  /** Track capability explicitly; `off` alone cannot distinguish clamp from intent. */
-  setCurrentModelSupportsThinking(supportsThinking: boolean | undefined): void {
-    this.currentModelSupportsThinking = supportsThinking;
-  }
+  /** @deprecated Parent effort is user-owned; retained as a compatibility no-op. */
+  setCurrentModelSupportsThinking(_supportsThinking: boolean | undefined): void {}
 
-  /** Configure migration behavior for Pi versions released before `max`. */
-  setRuntimeSupportsMaxThinking(supportsMaxThinking: boolean): void {
-    this.runtimeSupportsMaxThinking = supportsMaxThinking;
-  }
+  /** @deprecated Parent effort is user-owned; retained as a compatibility no-op. */
+  setRuntimeSupportsMaxThinking(_supportsMaxThinking: boolean): void {}
 
-  /** 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.
-    }
-  }
+  /** @deprecated Parent effort is user-owned; retained as a compatibility no-op. */
+  async flushThinkingPreference(): Promise<void> {}
 
   /** Enable auto if off, otherwise disable. Returns the new enabled state. */
   toggle(pi: ExtensionAPI): boolean {
@@ -114,84 +73,51 @@ export class UltracodeMode {
     return this.mode;
   }
 
-  /** The thinking level Pi actually applied after model/runtime clamping. */
+  /** @deprecated Ultracode no longer applies a parent thinking level. */
   getAppliedThinking(): ThinkingLevel | undefined {
-    return this.appliedThinking;
+    return undefined;
   }
 
   /**
-   * Return the configured raw effort request so every workflow subagent is
-   * clamped independently against its own model.
+   * @deprecated Workflow agents now select effort per call. An omitted suffix
+   * falls back to the child Pi session's normal user/model configuration rather
+   * than a mode-owned default.
    */
   getSubagentThinkingLevel(): ThinkingLevel | undefined {
-    return this.isEnforcing() ? thinkingLevelForMode(this.mode) : undefined;
+    return undefined;
   }
 
-  /** Reassert the configured mode effort before a turn or after a model change. */
-  reapplyConfiguredThinking(pi: ExtensionAPI): boolean {
-    if (!this.isEnforcing()) return false;
-    this.applyConfiguredThinking(pi);
-    return true;
+  /** @deprecated Parent effort is user-owned; retained as a compatibility no-op. */
+  reapplyConfiguredThinking(_pi: ExtensionAPI): boolean {
+    return false;
   }
 
-  /** @deprecated Use reapplyConfiguredThinking(). */
-  reapplyMaximumThinking(pi: ExtensionAPI): boolean {
-    return this.reapplyConfiguredThinking(pi);
+  /** @deprecated Parent effort is user-owned; retained as a compatibility no-op. */
+  reapplyMaximumThinking(_pi: ExtensionAPI): boolean {
+    return false;
   }
 
-  /**
-   * 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.isEnabled()) {
-      this.applyConfiguredThinking(pi);
-      return true;
-    }
-    if (this.pendingPreviousThinking) {
-      const pending = this.pendingPreviousThinking;
-      this.applyCompatibleThinking(pi, pending);
-      if (this.pendingRestoreSucceeded(pending)) this.pendingPreviousThinking = undefined;
-      this.persist(pi);
-    }
+  /** @deprecated Model changes do not alter Ultracode mode or parent effort. */
+  handleModelSelect(_pi: ExtensionAPI): boolean {
     return false;
   }
 
-  /** Restore the pre-mode effective effort without changing persisted mode state. */
-  restorePreviousThinking(pi: ExtensionAPI): void {
-    if (this.isEnabled() && this.previousThinking) this.applyCompatibleThinking(pi, this.previousThinking);
-  }
+  /** @deprecated Parent effort is never restored because Ultracode never changes it. */
+  restorePreviousThinking(_pi: ExtensionAPI): void {}
 
-  /** Stop enforcing synchronously, then restore effort before session teardown. */
+  /** Quiesce tool and prompt enforcement 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 configured effort after an external thinking-level selection.
-   * Stale events and events emitted by this mode are ignored to avoid recursion.
-   */
-  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.isEnabled()) {
-      // 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.applyConfiguredThinking(pi);
-    return true;
+  /** @deprecated User-selected parent effort is accepted without interception. */
+  handleThinkingLevelSelect(_pi: ExtensionAPI, _level: ThinkingLevel): boolean {
+    return false;
   }
 
   isEnabled(): boolean {
@@ -213,58 +139,28 @@ export class UltracodeMode {
   }
 
   /**
-   * Enable or switch modes without replacing the saved baseline. The no-argument
-   * form retains the pre-0.5 programmatic deep behavior; user commands pass an
-   * explicit mode and bare `/ultracode` uses toggle() to enter auto.
+   * Enable or switch modes. The no-argument form retains the pre-0.5
+   * programmatic deep behavior; user commands pass an explicit mode and bare
+   * `/ultracode` uses toggle() to enter auto.
    */
   enable(pi: ExtensionAPI, mode: ActiveUltracodeMode = "deep"): void {
     this.suspended = false;
-    this.pendingPreviousThinking = undefined;
-    this.pendingClearGeneration++;
-    if (!this.isEnabled()) {
-      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.mode = mode;
-    this.applyConfiguredThinking(pi);
     this.syncWorkflowTool(pi);
     this.persist(pi);
   }
 
-  /** Turn Ultracode off, restoring the pre-mode thinking level. */
+  /** Turn Ultracode off without changing the parent thinking level. */
   disable(pi: ExtensionAPI): void {
-    if (!this.isEnabled()) {
-      this.syncWorkflowTool(pi);
-      return;
-    }
-    const previous = this.previousThinking;
-    this.restorePreviousThinking(pi);
-    this.pendingPreviousThinking = previous && !this.pendingRestoreSucceeded(previous)
-      ? previous
-      : undefined;
-    this.pendingClearGeneration++;
+    // Persist an explicit off even when already disabled, so startup defaults
+    // cannot override this session's choice on reload or resume.
     this.mode = "off";
     this.suspended = false;
     this.syncWorkflowTool(pi);
     this.persist(pi);
   }
 
-
-  /** Restore mode state from the active session branch. */
+  /** Restore branch-local state; return whether a saved mode was found. */
   restore(
     pi: ExtensionAPI,
     entries: Array<{
@@ -273,121 +169,19 @@ export class UltracodeMode {
       data?: unknown;
       thinkingLevel?: unknown;
     }>,
-  ): void {
-    const wasEnforcing = this.isEnforcing();
-    this.pendingClearGeneration++;
+  ): boolean {
     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) {
         latestData = entry.data;
-        thinkingAfterLatestMode = undefined;
-      } else if (entry.type === "thinking_level_change" && isThinkingLevel(entry.thinkingLevel)) {
-        branchThinking = entry.thinkingLevel;
-        if (latestData !== undefined) thinkingAfterLatestMode = entry.thinkingLevel;
       }
     }
 
-    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.mode = "off";
-      this.suspended = false;
-      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;
-    }
-
+    const state = parsePersistedModeState(latestData);
+    this.mode = state?.mode ?? "off";
     this.suspended = false;
-    this.mode = latest.mode;
     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.mode !== "off"
-      && 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.isEnabled() ? undefined : latest.pendingPreviousThinking;
-    if (this.isEnabled()) {
-      this.applyConfiguredThinking(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);
-    }
+    return state !== undefined;
   }
 
   /** Append the configured semantic-depth policy to the turn's system prompt. */
@@ -397,128 +191,14 @@ export class UltracodeMode {
     return { systemPrompt: `${event.systemPrompt}\n\n${block}\n\n${ULTRACODE_ACTIVE_REMINDER}` };
   }
 
-  statusLine(): string {
-    if (!this.isEnabled()) return "ultracode: off";
-    const parts = [`ultracode: ${this.mode}`];
-    // Show the level that actually applied, including compatibility/model fallback.
-    if (this.appliedThinking) parts.push(this.appliedThinking);
-    return parts.join(" · ");
-  }
-
-  private applyConfiguredThinking(pi: ExtensionAPI): void {
-    const target = thinkingLevelForMode(this.mode);
-    if (!target) return;
-    const writeGeneration = this.preferenceWriteGeneration;
-    this.applyCompatibleThinking(pi, target);
-    // 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 mode-owned 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 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;
-    }
+  statusLine(styleLabel: (label: string) => string = (label) => label): string {
+    return [styleLabel("ultracode"), this.mode].join(" · ");
   }
 
   isEnforcing(): boolean {
     return this.isEnabled() && !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.isEnabled()
-        || this.suspended
-        || safeGetThinking(pi) !== level
-      ) return;
-      this.pendingPreviousThinking = undefined;
-      this.persist(pi);
-    });
-  }
-
   private activateWorkflowTool(pi: ExtensionAPI): void {
     try {
       const active = pi.getActiveTools();
@@ -526,7 +206,7 @@ export class UltracodeMode {
         pi.setActiveTools([...active, this.workflowToolName]);
       }
     } catch {
-      // Mode enforcement remains usable when tool selection is unavailable.
+      // Prompt policy remains usable when tool selection is unavailable.
     }
   }
 
@@ -542,14 +222,7 @@ export class UltracodeMode {
   }
 
   private persist(pi: ExtensionAPI): void {
-    const state: PersistedModeState = {
-      mode: this.mode,
-      previousThinking: this.previousThinking,
-      previousDefaultThinking: this.legacyDefaultMigrationPending
-        ? undefined
-        : this.previousDefaultThinking,
-      pendingPreviousThinking: this.pendingPreviousThinking,
-    };
+    const state: PersistedModeState = { mode: this.mode };
     try {
       pi.appendEntry(MODE_ENTRY_TYPE, state);
     } catch {
@@ -561,7 +234,6 @@ export class UltracodeMode {
 function parsePersistedModeState(data: unknown): PersistedModeState | undefined {
   if (!data || typeof data !== "object") return undefined;
   const value = data as Record<string, unknown>;
-  const previousDefault = value.previousDefaultThinking;
   // Sessions written before semantic-depth modes stored only enabled:boolean.
   // Preserve their behavior by migrating enabled:true to the old deep mode.
   const mode: UltracodeModeName = isActiveUltracodeMode(value.mode)
@@ -571,27 +243,5 @@ function parsePersistedModeState(data: unknown): PersistedModeState | undefined
       : value.enabled === true
         ? "deep"
         : "off";
-  return {
-    mode,
-    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 {
-    const level = pi.getThinkingLevel();
-    return isThinkingLevel(level) ? level : undefined;
-  } catch {
-    return undefined;
-  }
+  return { mode };
 }

package/src/preferences.ts

@@ -0,0 +1,50 @@
+/** Global Ultracode startup preferences, separate from Pi's own settings. */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface UltracodePreferenceStore {
+  getDefaultEnabled(): boolean;
+  setDefaultEnabled(enabled: boolean): void;
+}
+
+export class UltracodePreferences implements UltracodePreferenceStore {
+  private readonly path: string;
+
+  constructor(path = join(getAgentDir(), "ultracode.json")) {
+    this.path = path;
+  }
+
+  getDefaultEnabled(): boolean {
+    return this.read().defaultEnabled === true;
+  }
+
+  setDefaultEnabled(enabled: boolean): void {
+    const settings = { ...this.read(), defaultEnabled: enabled };
+    mkdirSync(dirname(this.path), { recursive: true });
+    const temporaryPath = `${this.path}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temporaryPath, `${JSON.stringify(settings, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+      renameSync(temporaryPath, this.path);
+    } finally {
+      rmSync(temporaryPath, { force: true });
+    }
+  }
+
+  private read(): Record<string, unknown> {
+    let content: string;
+    try {
+      content = readFileSync(this.path, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+      throw error;
+    }
+    const value: unknown = JSON.parse(content);
+    if (!value || typeof value !== "object" || Array.isArray(value)
+      || ("defaultEnabled" in value && typeof value.defaultEnabled !== "boolean")) {
+      throw new Error(`Invalid Ultracode preferences in ${this.path}: expected an object with a boolean defaultEnabled.`);
+    }
+    return value as Record<string, unknown>;
+  }
+}

package/src/prompts.ts

@@ -17,6 +17,7 @@ export function ultracodeSystemBlock(mode: ActiveUltracodeMode = "deep"): string
     "Analysis depth is a semantic quality decision, never a wall-clock decision. Do not use elapsed time, deadlines, or duration limits to choose, lower, or stop analysis depth.",
     "Use the smallest depth that can establish a correct answer. Depth is controlled by research rounds, independent perspectives, verification strength, evidence requirements, skeptic count, and per-agent reasoning effort.",
     "Existing maxAgents/reserveAgents limits are structural admission bounds, not evidence that every available slot should be used.",
+    "Ultracode does not change the parent session's effort; that remains under user control.",
     "",
     ...modeInstructions(mode),
     "",
@@ -31,7 +32,7 @@ export function ultracodeSystemBlock(mode: ActiveUltracodeMode = "deep"): string
     "- Use a workflow only when independent decomposition, verification, isolation, or context scale provides real value. Otherwise solve directly in the parent session.",
     "- Make skeptics conditional: verify high-risk, conflicting, weakly evidenced, or low-confidence claims instead of automatically verifying every branch.",
     "- Avoid a separate synthesis agent when deterministic merging or parent synthesis is enough. Use an adjudicator only when a material conflict remains.",
-    "- Match effort to the stage with per-call model suffixes when useful: focused discovery/synthesis may use :medium, standard analysis :high, and :max is reserved for deep or decisive high-risk verification.",
+    "- Select each workflow agent's effort from its task: use a per-call model suffix such as :medium for bounded discovery/synthesis, :high for substantive analysis or implementation, and :max only for deep or decisive high-risk verification. If omitted, the child session uses its normal user/model configuration.",
     "- When a workflow runs, log `analysis-depth: <level> — <reason>` before launching agents, `analysis-escalation: ...` for each semantic escalation, and `analysis-stop: ...` for the final evidence-based stop reason. Never use time as an escalation or stop reason.",
     "</ultracode>",
   ].join("\n");
@@ -86,7 +87,7 @@ export const WORKFLOW_GUIDELINES: string[] = [
   "For an auto-depth workflow, log `analysis-depth: <level> — <reason>` before launching agents, `analysis-escalation: ...` when evidence requires more depth, and `analysis-stop: ...` when evidence is sufficient. Elapsed time must never determine depth.",
   "For workflow verification, run skeptics only for high-risk, conflicting, low-confidence, or weakly evidenced claims. Do not automatically attach a skeptic to every branch.",
   "For workflow synthesis, prefer structured results plus deterministic or parent-session merging. Start a synthesis/adjudication agent only for a material unresolved conflict, and normally give pure synthesis lower effort and no broad source-search mandate.",
-  "For workflow agent effort, use a model suffix such as `:medium`, `:high`, or `:max` when the stage should differ from the mode default; reserve max for deep investigation or decisive high-risk verification.",
+  "For every substantive workflow agent, select effort from the assigned task with a model suffix such as `:medium`, `:high`, or `:max`: use medium for bounded discovery/synthesis, high for substantive analysis or implementation, and reserve max for deep or decisive high-risk verification. Ultracode never changes the parent session's effort; an omitted child suffix uses the child session's normal user/model configuration.",
   "For the workflow tool, provide workflow source with `script`, `scriptPath`, or `name`. Inline `script` must be one raw JavaScript string: 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/Intl/Temporal, Math.random(), binary memory constructors, WebAssembly, or dynamic method calls such as value[key](...) (they bypass deterministic checks or resource bounds). Stamp timestamps after the workflow returns; vary randomness by agent index.",

package/src/thinking.ts

@@ -4,10 +4,10 @@ export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhig
 
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 
-/** Deep mode asks Pi for the strongest effort the selected model supports. */
+/** Strongest child-agent effort request supported by current Pi releases. */
 export const ULTRACODE_THINKING_LEVEL: ThinkingLevel = "max";
 
-/** Compatibility retry for Pi versions released before the `max` level existed. */
+/** Child-session compatibility retry for Pi versions released before `max`. */
 export const LEGACY_ULTRACODE_THINKING_LEVEL: ThinkingLevel = "xhigh";
 
 const THINKING_LEVEL_SET = new Set<string>(THINKING_LEVELS);

package/src/workflow/runtime.ts

@@ -669,7 +669,7 @@ class Runtime implements ScriptExecutorHost {
         prompt,
         cached: true,
         modelPattern: opts.model,
-        requestedEffort: this.options.thinkingLevel,
+        requestedEffort: selection.thinkingLevel,
         agentType: opts.agentType,
         isolation: opts.isolation,
         structuredOutput: opts.schema != null,
@@ -712,7 +712,7 @@ class Runtime implements ScriptExecutorHost {
         prompt,
         cached: false,
         modelPattern: opts.model,
-        requestedEffort: this.options.thinkingLevel,
+        requestedEffort: selection.thinkingLevel,
         agentType: opts.agentType,
         isolation: opts.isolation,
         structuredOutput: opts.schema != null,
@@ -785,7 +785,7 @@ class Runtime implements ScriptExecutorHost {
               retries: usage.retries,
               compactions: usage.compactions,
               requestedModelId: opts.model,
-              requestedEffort: this.options.thinkingLevel,
+              requestedEffort: selection.thinkingLevel,
               modelId: result.modelId,
               effort: result.effort,
               agentType: opts.agentType,

package/src/workflow/tool.ts

@@ -93,9 +93,9 @@ export interface WorkflowToolDeps {
   registry?: WorkflowRegistry;
   /** Canonical runtime supplied by an SDK host; shared by all child sessions. */
   modelRuntime?: ModelRuntimeLike;
-  /** The configured Ultracode mode's raw default effort for workflow subagents.
-   *  Each child session clamps it independently; undefined when off. A per-call
-   *  `model: "X:level"` suffix or agentType `thinking:` override still wins. */
+  /** Optional host-provided fallback effort for workflow subagents.
+   *  Each child session clamps it independently. A per-call `model: "X:level"`
+   *  suffix or agentType `thinking:` override still wins. */
   getThinkingLevel?: () => ThinkingLevel | undefined;
   /** Optional execution gate for mode-scoped registrations. Omit for standalone use. */
   isExecutionAllowed?: () => boolean;
@@ -163,8 +163,8 @@ export function createWorkflowTool(deps: WorkflowToolDeps = {}): ToolDefinition<
       if (resuming && !RunJournal.exists(runsDir, runId)) {
         throw new Error(`workflow: resumeFromRunId ${runId} was not found in this session`);
       }
-      // Forward the mode's raw effort request so each subagent session clamps it
-      // against that subagent's model. Undefined when Ultracode is off.
+      // Forward an optional host fallback. Per-call and agent-role effort
+      // selection is resolved later for each child and clamped by its model.
       const thinkingLevel = deps.getThinkingLevel?.();
       if (controller.signal.aborted) throw new Error("Workflow was aborted before it started");
       const run = deps.runWorkflowFn ?? runWorkflow;