pi-ultracode 0.3.2 → 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,19 +59,35 @@ 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`.
+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.
 
 ```js
 export const meta = {
@@ -107,7 +123,9 @@ Custom agent roles live in:
 
 ```text
 .pi/ultracode/agents/*.md
+.pi/agents/*.md
 ~/.pi/ultracode/agents/*.md
+~/.pi/agent/agents/*.md
 ```
 
 A call can select a role, model, thinking level, or worktree isolation:
@@ -121,17 +139,17 @@ await agent("Implement and test the fix.", {
 });
 ```
 
-Worktree isolation requires a git repository with at least one commit. If setup fails, Ultracode logs the fallback and runs that agent in the shared working directory; avoid parallel writers in that case. A clean working tree is recommended for predictable patch integration.
+Worktree isolation requires a git repository with at least one commit and fails closed if the isolated tree cannot be created. Each call receives a unique detached worktree. Integration preserves the user's index and applies only byte-exact patches that pass cached checks in a private, object-format-matched Git index; raw blobs are then materialized without repository attributes, filters, or EOL conversion. A conflicting patch is saved for manual recovery instead of using a destructive three-way fallback. Successful delivery patches are retained so resume can verify that the shared-tree effect still exists. Isolated trees never link the shared writable `node_modules`; install dependencies there when needed, or run final tests after integration. A clean working tree is recommended for predictable patch integration.
 
 ## Guardrails
 
-A workflow defaults to `maxAgents: 128`, supports at most 16 concurrent agent calls, and allows one level of nested workflows. The lifetime agent limit is preserved across resumes; cached replay does not consume it again.
+A workflow defaults to `maxAgents: 128`, supports at most 16 concurrent agent calls, and allows one level of nested workflows. Nested `workflow()` calls accept only trust-aware saved-workflow names, not explicit paths. The lifetime agent limit is preserved across resumes; cached replay does not consume it again.
 
-Workflow agent sessions retain project context and ordinary skills, but do not initialize ambient Pi extensions or expose parent orchestration tools and skills (`workflow`, `subagent`, `subagent_wait`, or `pi-subagents`). This keeps orchestration at the parent boundary and allows `pi-ultracode` and `pi-subagents` to coexist in the main session.
+Workflow agent sessions retain project context and ordinary skills, but do not initialize ambient Pi extensions or expose parent orchestration tools and skills (`workflow`, `subagent`, `subagent_wait`, or `pi-subagents`). This keeps orchestration at the parent boundary and allows `pi-ultracode` and `pi-subagents` to coexist in the main session. Project-scoped agents and settings follow Pi's project-trust decision. The built-in Explore and Plan roles have a sealed read-only tool list without shell or write tools.
 
-Resume is intentionally immutable: the script, arguments, agent definitions, effective models, and call structure must still match. Changed work starts a new run.
+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,19 +59,35 @@ 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/ultracode/workflows/*.workflow.js` 或 `~/.pi/ultracode/workflows/*.workflow.js`。只有 Pi 将项目标记为可信后，才会发现项目级工作流；用户级工作流在未信任项目中仍可使用。
 
 ```js
 export const meta = {
@@ -107,7 +123,9 @@ return findings.filter(Boolean);
 
 ```text
 .pi/ultracode/agents/*.md
+.pi/agents/*.md
 ~/.pi/ultracode/agents/*.md
+~/.pi/agent/agents/*.md
 ```
 
 每次调用都可以选择角色、模型、思考强度或 worktree 隔离：
@@ -121,17 +139,17 @@ await agent("Implement and test the fix.", {
 });
 ```
 
-Worktree 隔离只能在至少有一个 commit 的 Git 仓库中使用。如果创建失败，Ultracode 会记录回退信息，并让该代理在共享工作目录中运行；此时应避免并行写入。为保证补丁集成可预测，建议保持工作区干净。
+Worktree 隔离只能在至少有一个 commit 的 Git 仓库中使用；隔离树创建失败时会直接失败，不会回退到共享工作目录。每次调用都会获得唯一的 detached worktree。补丁集成不修改用户 index；byte-exact patch 会先在 object format 匹配的私有 Git index 中完成 cached check，再绕开仓库 attributes、filter 与 EOL 转换直接 materialize 原始 blob；冲突补丁会保存供人工恢复，不使用可能破坏 index 的三方合并回退。成功交付的补丁会保留，用于 resume 时校验共享树效果仍然存在。隔离树不会链接共享仓库的可写 `node_modules`；需要时请在隔离树中安装依赖，或在集成后执行最终测试。为保证补丁集成可预测，建议保持工作区干净。
 
 ## 执行边界
 
-工作流默认使用 `maxAgents: 128`，最多并发运行 16 个代理，并只允许一层嵌套工作流。累计代理上限会跨 resume 保留，缓存回放不会再次占用额度。
+工作流默认使用 `maxAgents: 128`，最多并发运行 16 个代理，并只允许一层嵌套工作流。嵌套 `workflow()` 只接受经过 trust-aware discovery 的已保存工作流名称，不接受显式路径。累计代理上限会跨 resume 保留，缓存回放不会再次占用额度。
 
-Workflow 子代理会保留项目上下文和普通 skills，但不会初始化环境中的 Pi 扩展，也不会暴露父级编排工具与 skill（`workflow`、`subagent`、`subagent_wait` 或 `pi-subagents`）。这样可把编排限制在父会话边界，同时允许 `pi-ultracode` 与 `pi-subagents` 在主会话中共存。
+Workflow 子代理会保留项目上下文和普通 skills，但不会初始化环境中的 Pi 扩展，也不会暴露父级编排工具与 skill（`workflow`、`subagent`、`subagent_wait` 或 `pi-subagents`）。这样可把编排限制在父会话边界，同时允许 `pi-ultracode` 与 `pi-subagents` 在主会话中共存。项目级代理和设置遵循 Pi 的项目信任结果；内置 Explore 与 Plan 角色使用封闭的只读工具列表，不包含 shell 或写入工具。
 
-Resume 刻意保持不可变：脚本、参数、代理定义、实际模型和调用结构都必须匹配。工作内容发生变化时，应启动新的 run。
+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 {
@@ -17,6 +15,7 @@ import { createWorkflowTool, type WorkflowToolDeps } from "../src/workflow/tool.
 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";
 
 export interface ThinkingPreferenceContext {
   cwd: string;
@@ -38,19 +37,21 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
     ...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);
+  registerCommands(pi, mode, registry);
 
   // 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
@@ -65,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.",
       };
     }
   });
@@ -89,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);
@@ -125,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();
   });
@@ -134,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.3.2",
-  "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",
@@ -69,10 +69,20 @@
     "typebox": "*"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-agent-core": { "optional": true },
-    "@earendil-works/pi-ai": { "optional": true },
-    "@earendil-works/pi-coding-agent": { "optional": true },
-    "@earendil-works/pi-tui": { "optional": true },
-    "typebox": { "optional": true }
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   }
 }

package/src/commands.ts

@@ -3,17 +3,18 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ACTIVE_ULTRACODE_MODES, isActiveUltracodeMode } from "./depth.ts";
 import type { UltracodeMode } from "./mode.ts";
-import { getRegistry } from "./workflow/registry.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): void {
+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): void {
       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,20 +54,19 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode): void {
         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());
     },
   });
 
   const openWorkflows = async (ctx: any, runId?: string) => {
-    const registry = getRegistry();
     registry.restoreRuns(workflowRunsDir(ctx));
     await openWorkflowOverlay(ctx, registry, runId);
   };
@@ -77,7 +76,7 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode): void {
     getArgumentCompletions(prefix: string) {
       const values = [
         "abort",
-        ...getRegistry().list().map((handle) => handle.snapshot.runId).filter((runId): runId is string => Boolean(runId)),
+        ...registry.list().map((handle) => handle.snapshot.runId).filter((runId): runId is string => Boolean(runId)),
       ];
       return [...new Set(values)]
         .filter((value) => value.startsWith(prefix))
@@ -86,7 +85,7 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode): void {
     handler: async (args: string, ctx) => {
       const arg = args.trim();
       if (arg.toLowerCase() === "abort") {
-        getRegistry().abortAll();
+        registry.abortAll();
         ctx.ui.notify("Requested abort of all active workflow runs.", "warning");
         return;
       }
@@ -101,5 +100,5 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode): void {
 }
 
 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,
@@ -41,7 +49,7 @@ export {
   type AgentTypeDef,
 } from "./workflow/agent-types.ts";
 export { RunJournal, agentCallKey, hashString, stableStringify } from "./workflow/journal.ts";
-export { getRegistry, WorkflowRegistry } from "./workflow/registry.ts";
+export { WorkflowRegistry } from "./workflow/registry.ts";
 export {
   createSnapshot,
   recompute,