pi-ultracode 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ Deterministic multi-agent workflows for [Pi](https://github.com/earendil-works/p
 
 **English** · [简体中文](https://github.com/ekil1100/pi-ultracode/blob/main/README.zh-CN.md)
 
-`pi-ultracode` adds an opt-in high-effort mode to Pi. When a task benefits from delegation, the main agent can run a bounded JavaScript workflow with parallel subagents, isolated worktrees, structured output, durable resume, and live progress.
+`pi-ultracode` adds opt-in semantic analysis-depth modes to Pi. It can route each task automatically or hold a fixed focused, standard, or deep policy. When delegation adds value, the main agent can run a bounded JavaScript workflow with parallel subagents, isolated worktrees, structured output, durable resume, and live progress.
 
 The project combines the terminal-first agentic experience of [Claude Code](https://github.com/anthropics/claude-code) with the explicit workflow and structural-control ideas found in [Grok Build](https://github.com/xai-org/grok-build), while keeping Pi as the runtime.
 
@@ -14,14 +14,14 @@ The project combines the terminal-first agentic experience of [Claude Code](http
 pi install npm:pi-ultracode
 ```
 
-Then reload Pi and toggle Ultracode on:
+Then reload Pi and enable adaptive Ultracode:
 
 ```text
 /reload
 /ultracode
 ```
 
-You can also enable it at startup:
+You can also start directly in `auto` mode:
 
 ```bash
 pi --ultracode
@@ -33,7 +33,7 @@ Current releases are tested with Pi 0.84.
 
 ## Core features
 
-- **Opt-in high-effort mode** — requests the highest thinking level supported by the current model and restores the previous level when disabled.
+- **Adaptive semantic depth** — choose `auto`, `focused`, `standard`, or `deep`; `auto` selects the smallest evidence-sufficient depth and `off` restores the previous thinking level.
 - **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.
@@ -44,7 +44,7 @@ Current releases are tested with Pi 0.84.
 
 ## Quick start
 
-Toggle Ultracode on and describe a substantial task:
+Enable adaptive Ultracode and describe a task:
 
 ```text
 /ultracode
@@ -59,16 +59,32 @@ Useful commands:
 
 | Command | Action |
 | --- | --- |
-| `/ultracode` | Toggle Ultracode on or off |
-| `/ultracode on` | Explicitly enable it (optional alias) |
+| `/ultracode` | Enable `auto` from off; disable any active mode |
+| `/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 current mode and effective thinking level |
+| `/ultracode status` | Show the configured mode and effective thinking level |
 | `/workflows` or `F6` | Open the workflow browser |
 | `/workflows <runId>` | Open a specific run |
 | `/workflows abort` | Abort active runs |
 
 Press `Esc` to cancel a running workflow. In Pi's fullscreen TUI, use `Ctrl+PageUp`, `Ctrl+PageDown`, and `Ctrl+End` inside workflow details.
 
+## Analysis depth
+
+Depth is semantic, not time-based:
+
+- **Focused** prefers the parent agent and one bounded line of inquiry. It does not run adversarial verification by default.
+- **Standard** covers the few independent dimensions that can change the answer and verifies only high-risk, conflicting, or weakly evidenced claims.
+- **Deep** uses bounded multi-perspective investigation and adversarial verification for high-risk or explicitly comprehensive work.
+- **Auto** routes to the smallest sufficient level from user intent, consequence risk, scope, ambiguity, available evidence, and conflicts. It escalates only when evidence requires it.
+
+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.
+
 ## Workflow example
 
 The main agent normally writes workflows for you. Reusable workflows can also be saved under `.pi/ultracode/workflows/*.workflow.js` or `~/.pi/ultracode/workflows/*.workflow.js`. Project-scoped workflows are discovered only after Pi marks the project as trusted; user-scoped workflows remain available in untrusted projects.
@@ -133,7 +149,7 @@ Workflow agent sessions retain project context and ordinary skills, but do not i
 
 Resume is intentionally immutable: the normalized script, arguments, canonical repository/relative cwd, project-trust context, agent definitions, effective models, and call structure must still match. Worktree delivery writes a durable recovery intent before changing the shared repository; an interrupted or conflicted delivery blocks automatic replay and reports its recovery patch. Changed work starts a new run.
 
-Token and cost data are reported for observability, not enforced as a budget. Worker and VM restrictions are determinism and liveness guards, not a security sandbox.
+Token and cost data are reported for observability, not enforced as a budget. Worker and VM restrictions are determinism and liveness guards, not a security sandbox and not analysis-depth controls.
 
 ## Design inspiration
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 [English](README.md) · **简体中文**
 
-`pi-ultracode` 为 Pi 增加一个可选的高强度执行模式。当任务适合拆分时，主代理可以运行有边界的 JavaScript 工作流，使用并行子代理、隔离 worktree、结构化输出、持久恢复和实时进度。
+`pi-ultracode` 为 Pi 增加可选的语义化分析深度模式。它既可以自动判断任务需要的深度，也可以固定使用 focused、standard 或 deep 策略。当委派确有价值时，主代理可以运行有边界的 JavaScript 工作流，使用并行子代理、隔离 worktree、结构化输出、持久恢复和实时进度。
 
 项目结合了 [Claude Code](https://github.com/anthropics/claude-code) 的终端 Agentic 体验，以及 [Grok Build](https://github.com/xai-org/grok-build) 的显式工作流和结构控制思路，同时继续使用 Pi 作为运行时。
 
@@ -14,14 +14,14 @@
 pi install npm:pi-ultracode
 ```
 
-然后重新加载 Pi，并用主命令切换到 Ultracode：
+然后重新加载 Pi，并用主命令开启自适应 Ultracode：
 
 ```text
 /reload
 /ultracode
 ```
 
-也可以在启动时直接启用：
+也可以在启动时直接进入 `auto` 模式：
 
 ```bash
 pi --ultracode
@@ -33,7 +33,7 @@ pi --ultracode
 
 ## 核心特性
 
-- **可选高强度模式**：请求当前模型支持的最高思考强度，关闭时恢复之前的强度。
+- **自适应语义深度**：可选择 `auto`、`focused`、`standard` 或 `deep`；`auto` 使用证据充分的最小深度，关闭时恢复之前的思考强度。
 - **显式工作流**：通过 `agent()`、`parallel()`、`pipeline()` 和嵌套 `workflow()` 组合任务。
 - **独立子代理**：每个代理拥有独立的 Pi 会话、上下文、工具、模型选择和可选角色。
 - **并行 worktree 隔离**：写入型代理可在临时 git worktree 中工作，再集成补丁。
@@ -44,7 +44,7 @@ pi --ultracode
 
 ## 快速开始
 
-用主命令开启 Ultracode，然后描述一个较复杂的任务：
+用主命令开启自适应 Ultracode，然后描述任务：
 
 ```text
 /ultracode
@@ -59,16 +59,32 @@ Pi 会自行判断工作流是否有帮助。小任务仍可继续使用普通
 
 | 命令 | 作用 |
 | --- | --- |
-| `/ultracode` | 切换 Ultracode 的开启或关闭状态 |
-| `/ultracode on` | 显式启用（可选别名） |
+| `/ultracode` | 关闭时开启 `auto`；任一模式已开启时关闭 |
+| `/ultracode auto` | 使用自适应语义深度路由 |
+| `/ultracode focused` | 固定使用轻量、聚焦的分析策略 |
+| `/ultracode standard` | 固定使用平衡策略和条件验证 |
+| `/ultracode deep` | 固定使用高保障深度验证和 max effort |
 | `/ultracode off` | 关闭并恢复之前的思考强度 |
-| `/ultracode status` | 查看当前模式和实际思考强度 |
+| `/ultracode status` | 查看配置模式和实际思考强度 |
 | `/workflows` 或 `F6` | 打开工作流浏览器 |
 | `/workflows <runId>` | 打开指定运行 |
 | `/workflows abort` | 中止活动运行 |
 
 按 `Esc` 可取消正在运行的工作流。在 Pi 的 fullscreen TUI 中，请在工作流详情内使用 `Ctrl+PageUp`、`Ctrl+PageDown` 和 `Ctrl+End`。
 
+## 分析深度
+
+深度是语义化质量决策，不按运行时间判断：
+
+- **Focused** 优先使用主代理和单一、边界明确的调查路径，默认不做对抗验证。
+- **Standard** 覆盖少量真正会改变结论的独立维度，只验证高风险、冲突或证据薄弱的结论。
+- **Deep** 面向高风险或用户明确要求全面分析的任务，使用有界的多视角调查和对抗验证。
+- **Auto** 根据用户意图、影响风险、范围、歧义、现有证据和结论冲突，选择足够完成任务的最小等级；仅在证据要求升级时加深。
+
+当关键结论已有直接证据、没有实质冲突或未解决的高风险问题，且下一轮只会重复已知证据时停止。墙钟时间、deadline 和 duration limit 不得用于选择或停止分析深度。`maxAgents` 与 `reserveAgents` 继续作为结构性准入限制。
+
+Focused 默认使用 medium effort，auto 和 standard 默认使用 high，deep 使用 max；单个 workflow agent 仍可通过模型后缀覆盖 effort。skeptic 和独立 synthesis agent 都不是默认步骤。
+
 ## 工作流示例
 
 通常由主代理自动编写工作流。需要复用时，可以保存到 `.pi/ultracode/workflows/*.workflow.js` 或 `~/.pi/ultracode/workflows/*.workflow.js`。只有 Pi 将项目标记为可信后，才会发现项目级工作流；用户级工作流在未信任项目中仍可使用。
@@ -133,7 +149,7 @@ Workflow 子代理会保留项目上下文和普通 skills，但不会初始化
 
 Resume 刻意保持不可变：规范化脚本、参数、规范仓库及仓内相对 cwd、项目信任上下文、代理定义、实际模型和调用结构都必须匹配。Worktree 交付会在修改共享仓库前先写入持久恢复意图；中断或冲突的交付会阻止自动回放，并报告恢复补丁。工作内容发生变化时，应启动新的 run。
 
-Token 和成本只用于可观测性，不作为执行预算。Worker 与 VM 限制用于确定性和存活性保护，不是安全沙箱。
+Token 和成本只用于可观测性，不作为执行预算。Worker 与 VM 限制用于确定性和存活性保护，不是安全沙箱，也不参与分析深度判断。
 
 ## 设计参考
 

package/extensions/ultracode.ts

@@ -1,10 +1,8 @@
 /**
  * pi-ultracode extension entrypoint.
  *
- * Wires together the three pillars of Claude-Code-style "ultracode":
- *   1. The ultracode effort mode (max thinking + standing workflow opt-in).
- *   2. The full `workflow` orchestration tool.
- *   3. The `/ultracode` and `/workflows` commands.
+ * Wires together Ultracode's semantic analysis-depth modes, deterministic
+ * workflow orchestration, and the `/ultracode` / `/workflows` commands.
  */
 
 import {
@@ -53,7 +51,7 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
   // Opt-in via CLI flag: `pi --ultracode`.
   pi.registerFlag("ultracode", {
     type: "boolean",
-    description: "Start the session in ultracode mode (max thinking + default workflow orchestration).",
+    description: "Start the session in adaptive Ultracode mode.",
   });
 
   // SDK-created sessions can prompt without emitting session_start. Sync during
@@ -68,7 +66,7 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
     if (event.toolName === workflowTool.name && !mode.isEnforcing()) {
       return {
         block: true,
-        reason: "The workflow tool is disabled. Run /ultracode on before using it.",
+        reason: "The workflow tool is disabled. Run /ultracode or select an Ultracode depth before using it.",
       };
     }
   });
@@ -92,7 +90,7 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
       // ignore
     }
     if (!mode.isEnabled() && pi.getFlag?.("ultracode") === true) {
-      mode.enable(pi);
+      mode.enable(pi, "auto");
     }
     // Registration makes extension tools discoverable; activation remains opt-in.
     mode.syncWorkflowTool(pi);
@@ -128,7 +126,7 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
 
   pi.on("session_shutdown", async () => {
     // Quiesce first so late model/effort events cannot undo restoration. The
-    // persisted enabled state remains on for reload/resume/fork replacements.
+    // The persisted configured mode remains active for reload/resume/fork replacements.
     mode.suspend(pi);
     await mode.flushThinkingPreference();
   });
@@ -137,7 +135,7 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
     // Reconcile the tool schema and always append the standing block on an
     // enforcing turn, even when another active-tool writer caused drift.
     mode.syncWorkflowTool(pi);
-    mode.reapplyMaximumThinking(pi);
+    mode.reapplyConfiguredThinking(pi);
     await mode.flushThinkingPreference();
     return mode.beforeAgentStart(event);
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-ultracode",
-  "version": "0.4.0",
-  "description": "Claude-Code-style \"ultracode\" for Pi: an effort mode that defaults to deterministic multi-agent workflow orchestration, with worktree isolation, per-agent model overrides, custom agent types, nested workflows, resumable runs, and a /workflows manager.",
+  "version": "0.5.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": [
     "pi-package",

package/src/commands.ts

@@ -3,6 +3,7 @@
  */
 
 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 { WorkflowRegistry } from "./workflow/registry.ts";
 import { workflowRunsDir } from "./workflow/tool.ts";
@@ -10,10 +11,10 @@ import { openWorkflowOverlay } from "./workflow/workflow-overlay.ts";
 
 export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode, registry: WorkflowRegistry): void {
   pi.registerCommand("ultracode", {
-    description: "Toggle ultracode mode (max thinking + default workflow orchestration). Bare /ultracode toggles; subcommands: on|off|status",
+    description: "Toggle adaptive Ultracode, or select a fixed semantic depth: auto|focused|standard|deep|off|status",
     getArgumentCompletions(prefix: string) {
-      return ["on", "off", "status"]
-        .filter((s) => s.startsWith(prefix))
+      return [...ACTIVE_ULTRACODE_MODES, "off", "status"]
+        .filter((value) => value.startsWith(prefix))
         .map((value) => ({ value, label: value }));
     },
     handler: async (args: string, ctx) => {
@@ -21,32 +22,31 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode, registry
       const parts = args.trim().split(/\s+/).filter(Boolean);
       const sub = (parts[0] ?? "").toLowerCase();
 
-      // Bare `/ultracode` is a toggle.
+      // 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 on — ${mode.statusLine()}` : "Ultracode off — thinking restored and workflow tool disabled.",
+          nowOn
+            ? `Ultracode auto — ${mode.statusLine()}`
+            : "Ultracode off — thinking restored and workflow tool disabled.",
           "info",
         );
         ctx.ui.setStatus("ultracode", nowOn ? mode.statusLine() : undefined);
         return;
       }
 
+      if (parts.length > 1) {
+        ctx.ui.notify(ultracodeUsage(), "error");
+        return;
+      }
+
       if (sub === "status") {
-        if (parts.length > 1) {
-          ctx.ui.notify(ultracodeUsage(), "error");
-          return;
-        }
         ctx.ui.notify(mode.statusLine(), "info");
         return;
       }
 
       if (sub === "off") {
-        if (parts.length > 1) {
-          ctx.ui.notify(ultracodeUsage(), "error");
-          return;
-        }
         mode.disable(pi);
         await mode.flushThinkingPreference();
         ctx.ui.notify("Ultracode off — thinking restored and workflow tool disabled.", "info");
@@ -54,14 +54,14 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode, registry
         return;
       }
 
-      if (sub !== "on" || parts.length > 1) {
+      if (!isActiveUltracodeMode(sub)) {
         ctx.ui.notify(ultracodeUsage(), "error");
         return;
       }
 
-      mode.enable(pi);
+      mode.enable(pi, sub);
       await mode.flushThinkingPreference();
-      ctx.ui.notify(`Ultracode on — ${mode.statusLine()}`, "info");
+      ctx.ui.notify(`Ultracode ${sub} — ${mode.statusLine()}`, "info");
       ctx.ui.setStatus("ultracode", mode.statusLine());
     },
   });
@@ -100,5 +100,5 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode, registry
 }
 
 function ultracodeUsage(): string {
-  return "Usage: /ultracode [on|off|status]";
+  return "Usage: /ultracode [auto|focused|standard|deep|off|status]";
 }

package/src/depth.ts

@@ -0,0 +1,38 @@
+/** Ultracode's configured analysis modes and their default reasoning effort. */
+
+import type { ThinkingLevel } from "./thinking.ts";
+
+export const ACTIVE_ULTRACODE_MODES = ["auto", "focused", "standard", "deep"] as const;
+
+export type ActiveUltracodeMode = (typeof ACTIVE_ULTRACODE_MODES)[number];
+export type UltracodeModeName = "off" | ActiveUltracodeMode;
+
+const ACTIVE_MODE_SET = new Set<string>(ACTIVE_ULTRACODE_MODES);
+
+export function isActiveUltracodeMode(value: unknown): value is ActiveUltracodeMode {
+  return typeof value === "string" && ACTIVE_MODE_SET.has(value);
+}
+
+export function isUltracodeModeName(value: unknown): value is UltracodeModeName {
+  return value === "off" || isActiveUltracodeMode(value);
+}
+
+/**
+ * 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.
+ */
+export function thinkingLevelForMode(mode: UltracodeModeName): ThinkingLevel | undefined {
+  switch (mode) {
+    case "focused":
+      return "medium";
+    case "auto":
+    case "standard":
+      return "high";
+    case "deep":
+      return "max";
+    case "off":
+      return undefined;
+  }
+}

package/src/index.ts

@@ -2,6 +2,14 @@
 
 export { default } from "../extensions/ultracode.ts";
 export { UltracodeMode, MODE_ENTRY_TYPE } from "./mode.ts";
+export {
+  ACTIVE_ULTRACODE_MODES,
+  isActiveUltracodeMode,
+  isUltracodeModeName,
+  thinkingLevelForMode,
+  type ActiveUltracodeMode,
+  type UltracodeModeName,
+} from "./depth.ts";
 export { registerCommands } from "./commands.ts";
 export {
   ULTRACODE_TAGLINE,

package/src/mode.ts

@@ -1,16 +1,21 @@
 /**
  * Ultracode mode controller.
  *
- * Ultracode is a session-scoped effort mode. While on, it:
- *   - raises the thinking level to the model's maximum (remembering the previous level),
+ * 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,
  *   - keeps the `workflow` tool active,
- *   - injects a standing "author and run a workflow by default" system block on
- *     every turn,
- *   - persists its on/off state in session custom entries so it survives
- *     reload, resume, fork, and compaction.
+ *   - injects the configured auto/focused/standard/deep policy on every turn,
+ *   - persists branch-local mode state across reload, resume, fork, and compaction.
  */
 
 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,
@@ -24,7 +29,7 @@ export type { ThinkingLevel } from "./thinking.ts";
 export const MODE_ENTRY_TYPE = "ultracode-mode";
 
 interface PersistedModeState {
-  enabled: boolean;
+  mode: UltracodeModeName;
   previousThinking?: ThinkingLevel;
   /** `null` records that the setting was originally absent (Pi defaults to medium). */
   previousDefaultThinking?: ThinkingLevel | null;
@@ -47,13 +52,13 @@ export interface ThinkingPreferenceStore {
 }
 
 export class UltracodeMode {
-  private enabled = false;
+  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 maximum request. */
+  /** 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;
@@ -95,36 +100,45 @@ export class UltracodeMode {
     }
   }
 
-  /** Enable if off, disable if on. Returns the new enabled state. */
+  /** Enable auto if off, otherwise disable. Returns the new enabled state. */
   toggle(pi: ExtensionAPI): boolean {
-    if (this.enabled) {
+    if (this.isEnabled()) {
       this.disable(pi);
       return false;
     }
-    this.enable(pi);
+    this.enable(pi, "auto");
     return true;
   }
 
-  /** The thinking level Pi actually applied (`max`, or the model/runtime fallback). */
+  getMode(): UltracodeModeName {
+    return this.mode;
+  }
+
+  /** The thinking level Pi actually applied after model/runtime clamping. */
   getAppliedThinking(): ThinkingLevel | undefined {
     return this.appliedThinking;
   }
 
   /**
-   * Return the raw maximum request, not the parent's applied value, so every
-   * workflow subagent is clamped independently against its own model.
+   * Return the configured raw effort request so every workflow subagent is
+   * clamped independently against its own model.
    */
   getSubagentThinkingLevel(): ThinkingLevel | undefined {
-    return this.isEnforcing() ? ULTRACODE_THINKING_LEVEL : undefined;
+    return this.isEnforcing() ? thinkingLevelForMode(this.mode) : undefined;
   }
 
-  /** Reassert the maximum before a turn or after a model change. */
-  reapplyMaximumThinking(pi: ExtensionAPI): boolean {
+  /** Reassert the configured mode effort before a turn or after a model change. */
+  reapplyConfiguredThinking(pi: ExtensionAPI): boolean {
     if (!this.isEnforcing()) return false;
-    this.applyUltracodeThinking(pi);
+    this.applyConfiguredThinking(pi);
     return true;
   }
 
+  /** @deprecated Use reapplyConfiguredThinking(). */
+  reapplyMaximumThinking(pi: ExtensionAPI): boolean {
+    return this.reapplyConfiguredThinking(pi);
+  }
+
   /**
    * Handle model switches both while active and after a clamped restoration.
    * Returns true when Ultracode remains active and the UI should be refreshed.
@@ -132,8 +146,8 @@ export class UltracodeMode {
   handleModelSelect(pi: ExtensionAPI): boolean {
     if (this.suspended) return false;
     this.pendingClearGeneration++;
-    if (this.enabled) {
-      this.applyUltracodeThinking(pi);
+    if (this.isEnabled()) {
+      this.applyConfiguredThinking(pi);
       return true;
     }
     if (this.pendingPreviousThinking) {
@@ -147,7 +161,7 @@ export class UltracodeMode {
 
   /** 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);
+    if (this.isEnabled() && this.previousThinking) this.applyCompatibleThinking(pi, this.previousThinking);
   }
 
   /** Stop enforcing synchronously, then restore effort before session teardown. */
@@ -162,34 +176,32 @@ export class UltracodeMode {
   }
 
   /**
-   * 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.
+   * 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.enabled) {
+    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.applyUltracodeThinking(pi);
+    this.applyConfiguredThinking(pi);
     return true;
   }
 
   isEnabled(): boolean {
-    return this.enabled;
+    return this.mode !== "off";
   }
 
   isSuspended(): boolean {
     return this.suspended;
   }
 
-
   /** Keep tool availability aligned with the current mode state. */
   syncWorkflowTool(pi: ExtensionAPI): void {
     if (this.isEnforcing()) this.activateWorkflowTool(pi);
@@ -200,12 +212,16 @@ export class UltracodeMode {
     return ULTRACODE_TAGLINE;
   }
 
-  /** Turn ultracode on. Idempotent. */
-  enable(pi: ExtensionAPI): void {
+  /**
+   * 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(pi: ExtensionAPI, mode: ActiveUltracodeMode = "deep"): void {
     this.suspended = false;
     this.pendingPreviousThinking = undefined;
     this.pendingClearGeneration++;
-    if (!this.enabled) {
+    if (!this.isEnabled()) {
       const current = safeGetThinking(pi);
       const preference = this.captureThinkingPreference();
       const effectivePreference = this.runtimeCompatibleThinking(preference.effective) as
@@ -222,16 +238,16 @@ export class UltracodeMode {
         : current;
       this.previousDefaultThinking = this.runtimeCompatibleThinking(preference.global);
       this.legacyDefaultMigrationPending = false;
-      this.enabled = true;
     }
-    this.applyUltracodeThinking(pi);
+    this.mode = mode;
+    this.applyConfiguredThinking(pi);
     this.syncWorkflowTool(pi);
     this.persist(pi);
   }
 
-  /** Turn ultracode off, restoring the previous thinking level. */
+  /** Turn Ultracode off, restoring the pre-mode thinking level. */
   disable(pi: ExtensionAPI): void {
-    if (!this.enabled) {
+    if (!this.isEnabled()) {
       this.syncWorkflowTool(pi);
       return;
     }
@@ -241,7 +257,7 @@ export class UltracodeMode {
       ? previous
       : undefined;
     this.pendingClearGeneration++;
-    this.enabled = false;
+    this.mode = "off";
     this.suspended = false;
     this.syncWorkflowTool(pi);
     this.persist(pi);
@@ -286,7 +302,7 @@ export class UltracodeMode {
           ?? (wasEnforcing ? this.previousThinking : undefined)
           ?? effectivePreference,
       ) as ThinkingLevel | undefined;
-      this.enabled = false;
+      this.mode = "off";
       this.suspended = false;
       this.pendingPreviousThinking = undefined;
       this.previousThinking = target;
@@ -306,7 +322,7 @@ export class UltracodeMode {
     }
 
     this.suspended = false;
-    this.enabled = latest.enabled;
+    this.mode = latest.mode;
     this.syncWorkflowTool(pi);
     const maxIsUnknownToRuntime = !this.runtimeSupportsMaxThinking
       && preference.effective === ULTRACODE_THINKING_LEVEL;
@@ -319,7 +335,7 @@ export class UltracodeMode {
     // 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
+    const migratesLegacyDefault = latest.mode !== "off"
       && latest.previousDefaultThinking === undefined
       && latest.previousThinking !== undefined
       && (preference.global === LEGACY_ULTRACODE_THINKING_LEVEL
@@ -331,9 +347,9 @@ export class UltracodeMode {
         : this.runtimeCompatibleThinking(latest.previousDefaultThinking);
     this.legacyDefaultMigrationPending = migratesLegacyDefault;
 
-    this.pendingPreviousThinking = this.enabled ? undefined : latest.pendingPreviousThinking;
-    if (this.enabled) {
-      this.applyUltracodeThinking(pi);
+    this.pendingPreviousThinking = this.isEnabled() ? undefined : latest.pendingPreviousThinking;
+    if (this.isEnabled()) {
+      this.applyConfiguredThinking(pi);
       if (migratesLegacyDefault) {
         this.queueDefaultThinkingRestore(() => {
           this.legacyDefaultMigrationPending = false;
@@ -374,30 +390,29 @@ export class UltracodeMode {
     }
   }
 
-  /**
-   * Build the before_agent_start result: appends the ultracode system block to the
-   * turn's system prompt when enabled.
-   */
+  /** Append the configured semantic-depth policy to the turn's system prompt. */
   beforeAgentStart(event: { systemPrompt: string }): { systemPrompt: string } | undefined {
-    if (!this.isEnforcing()) return undefined;
-    const block = ultracodeSystemBlock();
+    if (!this.isEnforcing() || !isActiveUltracodeMode(this.mode)) return undefined;
+    const block = ultracodeSystemBlock(this.mode);
     return { systemPrompt: `${event.systemPrompt}\n\n${block}\n\n${ULTRACODE_ACTIVE_REMINDER}` };
   }
 
   statusLine(): string {
-    if (!this.enabled) return `ultracode: off`;
-    const parts = ["ultracode: on"];
+    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 applyUltracodeThinking(pi: ExtensionAPI): void {
+  private applyConfiguredThinking(pi: ExtensionAPI): void {
+    const target = thinkingLevelForMode(this.mode);
+    if (!target) return;
     const writeGeneration = this.preferenceWriteGeneration;
-    this.applyCompatibleThinking(pi, ULTRACODE_THINKING_LEVEL);
+    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 max -> max request.
+    // baseline even after a stable mode-owned request.
     if (writeGeneration === this.preferenceWriteGeneration) {
       this.queueDefaultThinkingRestore();
     }
@@ -433,7 +448,7 @@ export class UltracodeMode {
   }
 
   isEnforcing(): boolean {
-    return this.enabled && !this.suspended;
+    return this.isEnabled() && !this.suspended;
   }
 
   private pendingRestoreSucceeded(pending: ThinkingLevel): boolean {
@@ -495,7 +510,7 @@ export class UltracodeMode {
     setImmediate(() => {
       if (
         generation !== this.pendingClearGeneration
-        || this.enabled
+        || this.isEnabled()
         || this.suspended
         || safeGetThinking(pi) !== level
       ) return;
@@ -528,7 +543,7 @@ export class UltracodeMode {
 
   private persist(pi: ExtensionAPI): void {
     const state: PersistedModeState = {
-      enabled: this.enabled,
+      mode: this.mode,
       previousThinking: this.previousThinking,
       previousDefaultThinking: this.legacyDefaultMigrationPending
         ? undefined
@@ -547,8 +562,17 @@ 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)
+    ? value.mode
+    : value.mode === "off"
+      ? "off"
+      : value.enabled === true
+        ? "deep"
+        : "off";
   return {
-    enabled: value.enabled === true,
+    mode,
     previousThinking: isThinkingLevel(value.previousThinking) ? value.previousThinking : undefined,
     previousDefaultThinking: previousDefault === null || isThinkingLevel(previousDefault)
       ? previousDefault

package/src/prompts.ts

@@ -1,59 +1,92 @@
-/**
- * Prompt text for ultracode mode.
- *
- * These strings reproduce the behavioural contract of Claude Code's "ultracode"
- * effort level: a standing opt-in to deterministic multi-agent workflow
- * orchestration, biased toward the most exhaustive, correct answer.
- */
+/** Prompt text for Ultracode's adaptive analysis-depth modes. */
+
+import type { ActiveUltracodeMode } from "./depth.ts";
 
 /** One-line description shown by `/ultracode status` and the footer. */
-export const ULTRACODE_TAGLINE = "max thinking + dynamic workflow orchestration";
+export const ULTRACODE_TAGLINE = "semantic-depth workflow orchestration";
 
 /**
- * The standing system-prompt block injected on every turn while ultracode is on.
- * Mirrors the "Ultracode" section of the Workflow tool contract.
+ * The standing system-prompt block injected on every turn while Ultracode is
+ * active. The parent model performs the semantic routing itself; starting a
+ * separate agent merely to classify depth would defeat the focused path.
  */
-export function ultracodeSystemBlock(): string {
+export function ultracodeSystemBlock(mode: ActiveUltracodeMode = "deep"): string {
   return [
     "<ultracode>",
-    "Ultracode is ON. This opt-in is standing: author and run a workflow for every substantive task by default.",
+    `Configured mode: ${mode}.`,
+    "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.",
     "",
-    "The goal is a bounded, exhaustive-enough, correct answer: choose explicit fan-out and round limits before launching work.",
-    "For multi-phase work (understand → design → implement → review), prefer one bounded workflow and inspect the result before deciding whether another workflow is justified. Do not run consecutive workflows by default; continue only when new evidence changes the plan.",
+    ...modeInstructions(mode),
     "",
-    "Lean toward orchestrating with the workflow tool and adversarially verifying your findings, unless the work is trivial or already verified. Solo (no workflow) only on conversational turns or trivial mechanical edits.",
+    "Evidence-driven escalation and stopping:",
+    "- Escalate only for material correctness risk, missing direct evidence, conflicting findings, or an unresolved question that can change the answer.",
+    "- Treat security, GC, ABI, deoptimization, concurrency, data-loss, irreversible operations, and critical architecture semantics as high-risk unless bounded evidence proves otherwise.",
+    "- Stop when key claims have direct evidence, no material conflict or unresolved high-risk question remains, and another round would only repeat known evidence.",
+    "- Model-reported confidence alone is not sufficient. Prefer concrete citations, reproduction, tests, and independent agreement.",
+    "- If fixed focused/standard is insufficient, report the remaining uncertainty and recommend a deeper mode; in deep, report any irreducible uncertainty. Never silently exceed a fixed mode.",
     "",
-    "Quality patterns to compose as the task calls for it:",
-    "- Adversarial verify: spawn N independent skeptics per finding, each prompted to REFUTE it; kill the finding if a majority refute. Stops plausible-but-wrong findings from surviving.",
-    "- Perspective-diverse verify: when a finding can fail in more than one way, give each verifier a distinct lens (correctness, security, performance, does-it-reproduce) instead of N identical refuters.",
-    "- Multi-modal sweep: parallel agents each searching a different way (by-container, by-content, by-entity, by-time); each is blind to what the others surface.",
-    "- Loop-until-dry: for unknown-size discovery (bugs, edge cases), run at most 2 rounds by default (3 only when the user explicitly asks for comprehensive coverage); stop sooner when no fresh evidence appears.",
-    "- Completeness critic: a final agent that asks \"what's missing — a modality not run, a claim unverified, a source unread?\" What it finds becomes the next round of work.",
-    "- No silent caps: if a workflow bounds coverage (top-N, no-retry, sampling), log() what was dropped.",
-    "",
-    "Scale to the task: \"find any bugs\" → a few finders, single-vote verify; \"thoroughly audit\" / \"be comprehensive\" → a larger but explicit finder pool, 3–5 vote adversarial pass, and a synthesis stage within maxAgents.",
+    "Workflow policy:",
+    "- 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.",
+    "- 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");
 }
 
-/** Short reminder appended to confirm the mode is active (system-reminder style). */
+function modeInstructions(mode: ActiveUltracodeMode): string[] {
+  switch (mode) {
+    case "auto":
+      return [
+        "Before acting, silently route this task to focused, standard, or deep. Do not spawn a router agent.",
+        "Choose from user intent, consequence risk, scope, ambiguity, available evidence, cross-module or cross-repository breadth, and whether independent verification is necessary.",
+        "Begin at the shallowest sufficient depth and escalate only when evidence triggers an escalation condition below.",
+      ];
+    case "focused":
+      return [
+        "Focused is a fixed lightweight depth: prefer one bounded line of inquiry and the normal parent-agent loop.",
+        "Do not run adversarial verification by default. Use at most a small, narrowly scoped delegation only when it clearly reduces duplicated exploration.",
+      ];
+    case "standard":
+      return [
+        "Standard is a fixed balanced depth: cover the few independent dimensions that can materially change the answer.",
+        "Prefer one discovery round and conditional verification of only disputed, high-risk, or weakly evidenced claims.",
+      ];
+    case "deep":
+      return [
+        "Deep is a fixed high-assurance depth: default to a bounded workflow for substantive tasks unless the work is conversational, trivial, or already verified.",
+        "Use multi-perspective investigation and adversarial verification where the task supports it. Choose fan-out and round limits before launch.",
+        "Use at most two discovery rounds by default; add a third only when the user explicitly requests exhaustive coverage and fresh evidence is still appearing.",
+      ];
+  }
+}
+
+/** Short reminder appended after the standing block. */
 export const ULTRACODE_ACTIVE_REMINDER =
-  "Reminder: ultracode is on — default to authoring and running a workflow for substantive tasks, and adversarially verify your findings.";
+  "Reminder: Ultracode is active — obey its configured semantic depth, escalate only from evidence, and never use elapsed time as an analysis budget.";
 
 /** Tool description for the `workflow` tool. */
 export const WORKFLOW_TOOL_DESCRIPTION = [
-  "Execute a deterministic JavaScript workflow that orchestrates multiple subagents to be comprehensive (decompose and cover in parallel), confident (independent perspectives and adversarial checks before committing), or to take on scale one context can't hold (migrations, audits, broad sweeps).",
+  "Execute a deterministic JavaScript workflow that orchestrates a proportionate set of subagents for independent coverage, targeted verification, or work that exceeds one context.",
+  "Choose the smallest workflow justified by the configured Ultracode depth and current evidence; workflow use and adversarial checks are not automatic.",
   "Each invocation must provide workflow source via `script`, `scriptPath`, or `name`. Inline `script` must be raw JavaScript (no Markdown fences) beginning with `export const meta = { name, description }` (a pure literal) and should call agent() at least once for useful orchestration.",
-  "Available globals: agent(prompt, opts), parallel(thunks, options?), pipeline(items, ...stages), phase(title), log(message), workflow(name, args), args, cwd. The tool accepts maxAgents (default 128, max 1024) as a lifetime live-agent admission cap across resumes, not a token budget; cache replay is free.",
+  "Available globals: agent(prompt, opts), parallel(thunks, options?), pipeline(items, ...stages), phase(title), log(message), workflow(name, args), args, cwd. The tool accepts maxAgents (default 128, max 1024) as a lifetime live-agent admission cap across resumes, not a token or depth budget; cache replay is free.",
 ].join(" ");
 
 /** One-line snippet for the Available tools section. */
 export const WORKFLOW_PROMPT_SNIPPET =
-  "Run a deterministic JS workflow that fans out subagents. Header: export const meta = { name: 'snake_case', description: '...' }. Globals: agent/parallel/pipeline/phase/log/workflow/args/cwd.";
+  "Run a deterministic JS workflow with proportionate subagent fan-out. Header: export const meta = { name: 'snake_case', description: '...' }. Globals: agent/parallel/pipeline/phase/log/workflow/args/cwd.";
 
 /** Guideline bullets appended to the Guidelines section when the tool is active. */
 export const WORKFLOW_GUIDELINES: string[] = [
-  "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.",
+  "Use the workflow tool only when independent decomposition, targeted verification, isolation, or context scale adds value; use the parent agent directly for a bounded task.",
+  "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 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.",
@@ -66,7 +99,7 @@ export const WORKFLOW_GUIDELINES: string[] = [
   "For the workflow tool, agent opts also accept: model (override the subagent model by pattern), agentType (use a custom subagent role/system-prompt), isolation:'worktree' (run the agent in an isolated git worktree — use ONLY when agents mutate files in parallel and would conflict), and phase (assign the agent to a progress group explicitly inside parallel()/pipeline()).",
   "For the workflow tool, workflow(name, args) runs a trust-aware saved workflow by name as a sub-step, sharing this run's concurrency, maxAgents, active reservations, and agent counter. Explicit nested script paths are not supported. Nesting is one level only. Child subagent sessions do not load ambient extensions or expose workflow/subagent orchestration tools, so they cannot start an independent recursive workflow chain.",
   "For workflow resumeFromRunId, reuse the exact same script and args. Resume is immutable, successful calls replay by stable structural call path, and maxAgents may only stay the same or increase; changed work must start a new run.",
-  "For the workflow tool, failed agent()/parallel()/pipeline() branches return null and log the failure (unless the whole run is aborted or a policy limit is hit). Check for nulls before synthesizing conclusions, and prefer a final synthesis/assertion agent that returns a compact JSON-serializable verdict.",
+  "For the workflow tool, failed agent()/parallel()/pipeline() branches return null and log the failure (unless the whole run is aborted or a policy limit is hit). Check for nulls before synthesizing conclusions, and prefer a final compact JSON-serializable result.",
   "For the workflow tool, directly await or return every orchestration promise (agent/parallel/pipeline/workflow). Native .then/.catch/.finally chains and Promise.all/allSettled/race/any are rejected; use parallel() or pipeline() so call identity stays deterministic. Unobserved, pending, or native same-scope concurrent orchestration is fatal.",
   "Workflow helpers that call orchestration must be directly declared functions/function variables or static methods on a declared object/stored class instance. Do not alias them, assign them later, forward through this.otherMethod(), or call them from temporary/awaited factory receivers; rewrite those forms as a direct declared helper so resume identity remains stable.",
   "For the workflow tool, do not assume subagents share the parent's repository context; include enough task context and relevant file paths in each agent prompt.",

package/src/thinking.ts

@@ -4,7 +4,7 @@ export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhig
 
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 
-/** Ultracode always asks Pi for the strongest effort the selected model supports. */
+/** Deep mode 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. */

package/src/workflow/tool.ts

@@ -93,9 +93,8 @@ export interface WorkflowToolDeps {
   registry?: WorkflowRegistry;
   /** Canonical runtime supplied by an SDK host; shared by all child sessions. */
   modelRuntime?: ModelRuntimeLike;
-  /** The ultracode effort level to forward to every workflow subagent as its
-   *  default thinking level (`max` when ultracode is on, so each subagent's own
-   *  session clamps it independently; undefined when off). A per-call
+  /** 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. */
   getThinkingLevel?: () => ThinkingLevel | undefined;
   /** Optional execution gate for mode-scoped registrations. Omit for standalone use. */
@@ -132,7 +131,7 @@ export function createWorkflowTool(deps: WorkflowToolDeps = {}): ToolDefinition<
     parameters: workflowToolSchema,
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       if (deps.isExecutionAllowed?.() === false) {
-        throw new Error("The workflow tool is disabled. Run /ultracode on before using it.");
+        throw new Error("The workflow tool is disabled. Run /ultracode or select an Ultracode depth before using it.");
       }
       const controller = new AbortController();
       let abortRequested = false;
@@ -164,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 raw `max` request so each subagent session clamps it against
-      // that subagent's model. Undefined when ultracode is off.
+      // Forward the mode's raw effort request so each subagent session clamps it
+      // against that subagent's model. Undefined when Ultracode is off.
       const thinkingLevel = deps.getThinkingLevel?.();
       if (controller.signal.aborted) throw new Error("Workflow was aborted before it started");
       const run = deps.runWorkflowFn ?? runWorkflow;