pi-ultracode 0.4.0 → 0.6.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 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.
@@ -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 off` | Disable it and restore the previous thinking level |
-| `/ultracode status` | Show the current mode and effective thinking level |
+| `/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 |
+| `/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 |
 
 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.
+
+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
 
 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` 使用证据充分的最小深度，父代理 effort 始终由用户控制。
 - **显式工作流**：通过 `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 off` | 关闭并恢复之前的思考强度 |
-| `/ultracode status` | 查看当前模式和实际思考强度 |
+| `/ultracode` | 关闭时开启 `auto`；任一模式已开启时关闭 |
+| `/ultracode auto` | 使用自适应语义深度路由 |
+| `/ultracode focused` | 固定使用轻量、聚焦的分析策略 |
+| `/ultracode standard` | 固定使用平衡策略和条件验证 |
+| `/ultracode deep` | 固定使用高保障深度验证 |
+| `/ultracode off` | 关闭且不改变父代理 effort |
+| `/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` 继续作为结构性准入限制。
+
+Ultracode 不会修改父会话的 effort。对于 workflow 子代理，父代理会按具体任务通过模型后缀选择 effort：边界明确的搜索或汇总通常使用 `:medium`，实质分析或实现使用 `:high`，只有深度调查或决定性的高风险验证才使用 `:max`。Workflow UI 会展示每个子代理经模型裁剪后实际生效的 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,21 +1,13 @@
 /**
  * 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 {
-  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 { WorkflowRegistry } from "../src/workflow/registry.ts";
 
@@ -25,7 +17,7 @@ export interface ThinkingPreferenceContext {
 }
 
 export interface UltracodeExtensionDeps extends Partial<WorkflowToolDeps> {
-  /** SDK-host seam when the active profile differs from Pi's ambient agent dir. */
+  /** @deprecated Parent effort is user-owned; retained for source compatibility. */
   createThinkingPreferenceStore?: (
     context: ThinkingPreferenceContext,
   ) => ThinkingPreferenceStore | undefined;
@@ -33,15 +25,13 @@ 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,
     ...workflowDeps
   } = extraDeps;
 
   const registry = workflowDeps.registry ?? new WorkflowRegistry();
   const workflowTool = createWorkflowTool({
-    getThinkingLevel: () => mode.getSubagentThinkingLevel(),
     ...workflowDeps,
     registry,
     isExecutionAllowed: () => mode.isEnforcing(),
@@ -53,7 +43,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,22 +58,12 @@ 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.",
       };
     }
   });
 
   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.
     try {
       // Mode entries are branch-local; discarded future branches must not win.
@@ -92,85 +72,38 @@ 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);
-    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
-    // 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();
   });
 
   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.reapplyMaximumThinking(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,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.6.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,59 +11,60 @@ 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) => {
-      mode.setCurrentModelSupportsThinking(ctx.model ? Boolean(ctx.model.reasoning) : undefined);
       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 — 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 (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");
+        ctx.ui.notify("Ultracode off — workflow tool disabled; parent effort unchanged.", "info");
         ctx.ui.setStatus("ultracode", undefined);
         return;
       }
 
-      if (sub !== "on" || parts.length > 1) {
+      if (!isActiveUltracodeMode(sub)) {
         ctx.ui.notify(ultracodeUsage(), "error");
         return;
       }
 
-      mode.enable(pi);
-      await mode.flushThinkingPreference();
-      ctx.ui.notify(`Ultracode on — ${mode.statusLine()}`, "info");
-      ctx.ui.setStatus("ultracode", mode.statusLine());
+      mode.enable(pi, sub);
+      ctx.ui.notify(`Ultracode ${sub} — ${mode.statusLine()}`, "info");
+      ctx.ui.setStatus(
+        "ultracode",
+        mode.statusLine((label) => ctx.ui.theme.fg("accent", label)),
+      );
     },
   });
 
@@ -100,5 +102,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,37 @@
+/** Ultracode's configured semantic analysis-depth modes. */
+
+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);
+}
+
+/**
+ * @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) {
+    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,