pi-ultracode 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 **Ultracode** 是 [Pi](https://github.com/badlogic/pi-mono) 的“全力执行”模式。它把 Pi 的 Agentic Loop 从单线程编码助手升级为能够运行子代理团队的编排器。
 
-启用 Ultracode 后，主代理会获得一条 `workflow` 工具，以及一段要求它主动使用该工具处理复杂任务的系统提示词。每个子代理都运行在独立的内存 Pi 会话中，拥有标准编码工具、独立上下文，并可选择结构化输出、模型覆盖、Agent Type 和隔离的 git worktree。
+启用 Ultracode 后，主代理会获得一条 `workflow` 工具，以及一段要求它主动使用该工具处理复杂任务的系统提示词。扩展加载时会先注册该工具，并在模型请求前的 input 与 `before_agent_start` 边界按模式校准 active tools；未启用或已暂停时，残留调用会被拒绝。每个子代理都运行在独立的内存 Pi 会话中，拥有标准编码工具、独立上下文，并可选择结构化输出、模型覆盖、Agent Type 和隔离的 git worktree。
 
 Ultracode 保留 Pi 自身的核心循环、内存模型、工具系统、扩展 API 与会话格式。它是在 Pi 之上增加编排能力，而不是替换 Pi。
 
@@ -10,7 +10,7 @@ Ultracode 保留 Pi 自身的核心循环、内存模型、工具系统、扩展
 
 | 能力 | 说明 |
 | --- | --- |
-| `workflow` 工具 | 运行确定性的 JavaScript 编排脚本，并调用 `agent()`、`parallel()`、`pipeline()` 和 `workflow()`。 |
+| `workflow` 工具 | 模型请求前按 Ultracode 状态校准；运行确定性的 JavaScript 编排脚本，并调用 `agent()`、`parallel()`、`pipeline()` 和 `workflow()`。 |
 | 独立子代理 | 每次 `agent()` 调用都会创建一条带标准编码工具的新 Pi 会话。 |
 | 并行执行 | `parallel()` 并发运行任务，且保留输入顺序。 |
 | 流水线 | `pipeline()` 让任务独立流经多个阶段，无需全局屏障。 |
@@ -18,7 +18,7 @@ Ultracode 保留 Pi 自身的核心循环、内存模型、工具系统、扩展
 | Agent Type | 通过 `.pi/ultracode/agents/*.md` 定义角色提示词、工具白名单、模型和思考强度。 |
 | 模型覆盖 | 每次 `agent()` 调用都可指定模型模式，例如 `anthropic/claude-sonnet-4`。 |
 | Worktree 隔离 | 让写入型并行代理在临时 git worktree 中运行，并把改动安全合并回共享工作树。 |
-| 进度面板 | 实时状态、活动计数、token 与成本统计、阶段信息，以及可选的 TUI 面板。 |
+| 进度与详情 | 实时状态、实际模型/effort、turn/工具/token 统计，以及可流式展开的 TUI 任务详情浮层。 |
 | Ultracode 模式 | `/ultracode on` 启用主动编排提示词，并请求当前模型支持的最高思考强度。 |
 | 配额执行 | 可选 token 预算、代理数量限制、并发限制、脚本超时与嵌套深度限制。 |
 
@@ -82,17 +82,19 @@ pi --ultracode
 工作流运行时会内联显示实时进度，例如：
 
 ```text
-◆ ▶ audit_repo (4/7 done, 2 running) · 3 cached · 41.2k/500k tok
+◆ ▶ audit_repo (4/7 done, 2 running) · 3 cached · 203k token (141k new, 62k replayed) · 41.2k/500k out
   ✓ Survey 1/1
     #1 ✓ repo inventory
+       gpt-5.6-sol • max · 15 turns · 42 tool uses · 141k token
   ▶ Review 3/4 · 1 running
     #2 ✓ auth module
     #3 ✓ db layer
     #4 ● payments module
+       claude-sonnet-4 • high · 6 turns · 18 tool uses · 52.3k+ token · partial
   ▶ Verify 0/2 · 2 running
 ```
 
-按 `Esc` 可取消；运行中的子代理会被终止并显示为 skipped。
+紧凑 token 数始终是 input + output；cache read/write 与成本只出现在任务详情中。主对话会折叠较早任务并明确显示省略数量，按 `Ctrl+O` 可展开全部，或用 `F6` 打开详情。按 `Esc` 可取消；运行中的子代理会被终止并显示为 cancelled，同时保留已有输出和部分用量。
 
 ## 命令
 
@@ -100,17 +102,25 @@ pi --ultracode
 /ultracode             # toggle on/off
 /ultracode on          # enable orchestration mode
 /ultracode on 500k     # enable it with an output-token budget
-/ultracode off         # disable it and restore the previous thinking level
+/ultracode off         # disable the tool and restore the previous thinking level
 /ultracode status      # show status and the configured budget
 /ultracode budget 500k # set a token budget
 /ultracode budget off  # remove the budget
-/workflows             # toggle the workflow run panel
-/workflows <runId>     # show one run's detail
-/workflows clear       # hide the panel
-/workflows abort       # abort active runs and hide the panel
+/workflows             # open the interactive workflow detail overlay
+/workflows <runId>     # open one run directly (prefix accepted)
+/workflows abort       # abort active runs
+F6                     # open the workflow detail overlay
 ```
 
-`/workflows` 面板是执行命令时生成的静态快照；再次运行该命令可刷新，`/workflows clear` 只隐藏面板，不删除 registry 记录。工作流执行期间的实时进度显示在工具结果中。为缩小隐私边界，进度只包含结构化生命周期状态和安全摘要，不捕获、持久化或展示子代理的原始流式响应正文。
+`/workflows` 与 `F6` 打开实时浮层。只有一个活动运行时会直接进入；多个活动运行会先显示选择器；没有活动运行时会打开最近完成的运行。宽终端使用任务/详情双栏，窄终端在列表与详情间切换。键盘操作：
+
+- `↑` / `↓` 选择运行或任务；`Enter` 打开；`Tab` 切换双栏焦点；`Esc` 返回或关闭；
+- `PageUp` / `PageDown` 滚动；`End` 恢复尾随；
+- `/` 搜索任务，`r` 只看运行中的任务，`a` 恢复全部，`p` 展开或收起任务 prompt。
+
+每次 `agent()` 调用都是一个可独立展开的任务。详情按时间交错显示 turn、assistant 正文、工具调用、重试、上下文压缩、错误与 thinking 持续时间；thinking 正文不会被捕获。正文 delta 只保存在有界内存中并以不超过每 100ms 一次的频率刷新，消息完成后改用 Markdown 渲染。
+
+所有可视化和落盘内容都会移除终端控制序列并脱敏凭据。内存上限为每任务 1MiB / 5000 行、每工作流 32MiB；最终 transcript 上限为每任务 10MB（约 1MB 头部 + 9MB 尾部）、每工作流 128MB。最终清理后的 timeline 与 manifest 保存在 session 的 `ultracode-runs/` 目录，因而 `/reload` 后仍可浏览；不会复制系统 prompt、注入 skill、AGENTS 内容或父会话上下文。
 
 状态行会显示实际生效的思考强度，例如：
 
@@ -133,7 +143,7 @@ Ultracode 请求的是**当前模型支持的最高强度**，不是固定标签
 
 ## 工作原理
 
-扩展注册单个 `workflow` 工具。工具输入是 JavaScript 源码，其中必须包含纯字面量 `meta` 导出：
+扩展注册单个 `workflow` 工具，并在 input preflight 与 `before_agent_start` 边界按 Ultracode 状态校准 active tools，同时保留其他 active tools。关闭或暂停时，`tool_call` 与实际执行入口会双重 fail-closed 拒绝残留调用。工具输入是 JavaScript 源码，其中必须包含纯字面量 `meta` 导出：
 
 ```js
 export const meta = {
@@ -410,11 +420,12 @@ while (budget.total && budget.remaining() > 50_000) {
 
 Ultracode 模式状态通过自定义 session entry 持久化。恢复、reload、fork 和 `/tree` 导航都会按当前 branch 重新读取状态；被丢弃分支中的 entry 不会错误启用模式。旧版 Pi 或旧模型会把 `max` 兼容回退为 `xhigh`，而不会把未知值静默变成 `off`。
 
-扩展清理只管理自己的 widget、status 与运行状态，不会调用 Pi 的全局 `ui.clear()`，因此不会清除其他扩展的 UI。
+扩展清理只管理自己的详情浮层、status 与运行状态，不会调用 Pi 的全局 `ui.clear()`，因此不会清除其他扩展的 UI。
 
 ## 开发
 
 ```bash
+npm ci
 npm run typecheck
 npm test
 npm pack --dry-run
@@ -429,7 +440,32 @@ npm pack --dry-run
 - `test/`：单元、扩展和回归测试；
 - `docs/parity.md`：与原生 Pi 能力边界的说明。
 
-直接运行 Node 测试时没有 Pi 的模块加载器，需要把真实的 `acorn` 与 Pi 提供的 peer 包链接到 `node_modules/`；`npm run typecheck` 还要求本地可用的 TypeScript。通过 `pi install` 加载扩展时，Pi 会提供这些 peer 依赖。
+开发依赖会安装 TypeScript 和用于测试的 Pi peer 包；通过 `pi install` 加载正式包时，Pi 仍会提供这些 peer 依赖。
+
+## 发布
+
+npm 发布由 [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml) 完成，使用 npm Trusted Publishing（OIDC），无需保存长期 `NPM_TOKEN`。
+
+首次使用前，在 npm 的 `pi-ultracode` 包设置中添加 GitHub Actions Trusted Publisher：
+
+- Organization or user：`ekil1100`
+- Repository：`pi-ultracode`
+- Workflow filename：`publish-npm.yml`
+- Environment name：`npm`
+- Allowed action：`npm publish`
+
+同时在 GitHub 仓库中创建名为 `npm` 的 Environment；可以按需增加审批人。正常发布无需打开 Actions 页面：
+
+```bash
+npm version patch # or: minor / major / 0.2.0-beta.1
+git push origin main --follow-tags
+```
+
+`npm version` 会同步更新 `package.json` 和 `package-lock.json`，创建版本提交与 `v<version>` Tag；推送 Tag 后 CI 自动发布。稳定版本发布到 `latest`，预发布版本发布到 `next`。
+
+需要重试或指定其他 npm dist-tag 时，也可以在 Actions 中手动运行工作流；填写完全匹配 `package.json` 的版本，且只允许从 `main` 运行。
+
+工作流会校验 Tag 与包版本完全一致、确认版本尚未发布，并在正式发布前执行干净安装、测试和类型检查。
 
 ## 设计原则
 

package/extensions/ultracode.ts

@@ -42,6 +42,7 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
     getDefaultBudget: () => mode.getBudget(),
     getThinkingLevel: () => mode.getSubagentThinkingLevel(),
     ...workflowDeps,
+    isExecutionAllowed: () => mode.isEnforcing(),
   });
   pi.registerTool(workflowTool);
 
@@ -53,6 +54,23 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
     description: "Start the session in ultracode mode (max thinking + default workflow orchestration).",
   });
 
+  // SDK-created sessions can prompt without emitting session_start. Sync during
+  // input preflight so before_agent_start receives Pi's rebuilt base prompt.
+  pi.on("input", () => {
+    mode.syncWorkflowTool(pi);
+  });
+
+  // Fail closed if another active-tool writer re-exposes workflow while the
+  // mode is off or quiescing.
+  pi.on("tool_call", (event) => {
+    if (event.toolName === workflowTool.name && !mode.isEnforcing()) {
+      return {
+        block: true,
+        reason: "The workflow tool is disabled. Run /ultracode on before using it.",
+      };
+    }
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     await mode.flushThinkingPreference();
     mode.setCurrentModelSupportsThinking(ctx.model ? Boolean(ctx.model.reasoning) : undefined);
@@ -74,13 +92,8 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
     if (!mode.isEnabled() && pi.getFlag?.("ultracode") === true) {
       mode.enable(pi);
     }
-    // Always keep the workflow tool available so the model can use it on request.
-    try {
-      const active = pi.getActiveTools();
-      if (!active.includes(workflowTool.name)) pi.setActiveTools([...active, workflowTool.name]);
-    } catch {
-      // ignore
-    }
+    // 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);
@@ -119,7 +132,9 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
   });
 
   pi.on("before_agent_start", async (event) => {
-    // Final synchronous effort barrier before Pi starts the provider request.
+    // 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);
     await mode.flushThinkingPreference();
     return mode.beforeAgentStart(event);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ultracode",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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, token budgets, resumable runs, and a /workflows manager.",
   "type": "module",
   "keywords": [
@@ -16,6 +16,14 @@
   ],
   "author": "pi-ultracode",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ekil1100/pi-ultracode.git"
+  },
+  "homepage": "https://github.com/ekil1100/pi-ultracode#readme",
+  "bugs": {
+    "url": "https://github.com/ekil1100/pi-ultracode/issues"
+  },
   "files": [
     "extensions/",
     "src/",
@@ -23,6 +31,10 @@
     "examples/",
     "README.md"
   ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "pi": {
     "extensions": [
       "./extensions/ultracode.ts"
@@ -40,6 +52,15 @@
   "dependencies": {
     "acorn": "^8.11.0"
   },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.83.0",
+    "@earendil-works/pi-ai": "^0.83.0",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
+    "@types/node": "^24.12.4",
+    "typebox": "1.3.7",
+    "typescript": "^5.9.3"
+  },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",

package/src/commands.ts

@@ -5,8 +5,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { parseBudget, type UltracodeMode } from "./mode.ts";
 import { getRegistry } from "./workflow/registry.ts";
-import { renderWorkflowLines } from "./workflow/display.ts";
-import { truncateDisplay } from "./workflow/display-text.ts";
+import { workflowRunsDir } from "./workflow/tool.ts";
+import { openWorkflowOverlay } from "./workflow/workflow-overlay.ts";
 
 export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode): void {
   pi.registerCommand("ultracode", {
@@ -25,7 +25,10 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode): void {
       if (sub === "") {
         const nowOn = mode.toggle(pi);
         await mode.flushThinkingPreference();
-        ctx.ui.notify(nowOn ? `Ultracode on — ${mode.statusLine()}` : "Ultracode off — thinking restored.", "info");
+        ctx.ui.notify(
+          nowOn ? `Ultracode on — ${mode.statusLine()}` : "Ultracode off — thinking restored and workflow tool disabled.",
+          "info",
+        );
         ctx.ui.setStatus("ultracode", nowOn ? mode.statusLine() : undefined);
         return;
       }
@@ -38,7 +41,7 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode): void {
       if (sub === "off") {
         mode.disable(pi);
         await mode.flushThinkingPreference();
-        ctx.ui.notify("Ultracode off — thinking restored, workflow orchestration is opt-in again.", "info");
+        ctx.ui.notify("Ultracode off — thinking restored and workflow tool disabled.", "info");
         ctx.ui.setStatus("ultracode", undefined);
         return;
       }
@@ -71,96 +74,36 @@ export function registerCommands(pi: ExtensionAPI, mode: UltracodeMode): void {
     },
   });
 
-  // Tracks whether the run panel is currently shown, so bare /workflows toggles it.
-  let panelVisible = false;
+  const openWorkflows = async (ctx: any, runId?: string) => {
+    const registry = getRegistry();
+    registry.restoreRuns(workflowRunsDir(ctx));
+    await openWorkflowOverlay(ctx, registry, runId);
+  };
 
   pi.registerCommand("workflows", {
-    description: "Toggle the workflow-run panel. Usage: /workflows [runId | clear | abort]",
+    description: "Open the interactive workflow/task detail overlay. Usage: /workflows [runId | abort]",
     getArgumentCompletions(prefix: string) {
-      return ["clear", "abort"]
-        .filter((s) => s.startsWith(prefix))
+      const values = [
+        "abort",
+        ...getRegistry().list().map((handle) => handle.snapshot.runId).filter((runId): runId is string => Boolean(runId)),
+      ];
+      return [...new Set(values)]
+        .filter((value) => value.startsWith(prefix))
         .map((value) => ({ value, label: value }));
     },
     handler: async (args: string, ctx) => {
-      const registry = getRegistry();
       const arg = args.trim();
-      const sub = arg.toLowerCase();
-
-      const hide = () => {
-        ctx.ui.setWidget("ultracode-workflows", undefined);
-        panelVisible = false;
-      };
-      const show = (lines: string[]) => {
-        ctx.ui.setWidget("ultracode-workflows", lines);
-        panelVisible = true;
-      };
-
-      if (sub === "clear" || sub === "hide" || sub === "off") {
-        hide();
-        ctx.ui.notify("Workflow panel hidden.", "info");
-        return;
-      }
-
-      if (sub === "abort") {
-        registry.abortAll();
-        hide();
-        ctx.ui.notify("Requested abort of all active workflow runs; panel hidden.", "info");
-        return;
-      }
-
-      const runs = registry.list();
-
-      // Explicit run id -> show that run's detail.
-      if (arg) {
-        const handle = registry.get(arg) ?? runs.find((r) => r.snapshot.runId?.startsWith(arg));
-        if (!handle) {
-          ctx.ui.notify(`No workflow run matching "${truncateDisplay(arg, 80)}". /workflows to list, /workflows clear to hide.`, "warning");
-          return;
-        }
-        show(renderWorkflowLines(handle.snapshot, { maxAgents: 12, maxLogs: 6, showResultPreviews: true }));
-        ctx.ui.notify(`Showing ${truncateDisplay(handle.snapshot.runId ?? "run", 128)}. /workflows clear to hide.`, "info");
+      if (arg.toLowerCase() === "abort") {
+        getRegistry().abortAll();
+        ctx.ui.notify("Requested abort of all active workflow runs.", "warning");
         return;
       }
-
-      // Bare /workflows toggles the panel off if it's already up.
-      if (panelVisible) {
-        hide();
-        ctx.ui.notify("Workflow panel hidden.", "info");
-        return;
-      }
-
-      if (runs.length === 0) {
-        hide();
-        ctx.ui.notify("No workflow runs in this session yet.", "info");
-        return;
-      }
-
-      const summary = runs.map((handle) => {
-        const s = handle.snapshot;
-        return `${statusGlyph(s.status)} ${truncateDisplay(s.runId ?? "run", 128)}  ${truncateDisplay(s.name, 80)}  ${s.doneCount}/${s.agentCount}${
-          s.runningCount ? ` (${s.runningCount} running)` : ""
-        }`;
-      });
-      show(["◆ Ultracode workflow runs  ·  /workflows clear to hide", ...summary.map((l) => `  ${l}`)]);
-      ctx.ui.notify(
-        `${runs.length} run(s), ${registry.active().length} active. /workflows again (or /workflows clear) to hide.`,
-        "info",
-      );
+      await openWorkflows(ctx, arg || undefined);
     },
   });
-}
 
-function statusGlyph(status: string): string {
-  switch (status) {
-    case "completed":
-      return "✓";
-    case "running":
-      return "▶";
-    case "aborted":
-      return "■";
-    case "failed":
-      return "✗";
-    default:
-      return "·";
-  }
+  pi.registerShortcut("f6", {
+    description: "Open workflow task details",
+    handler: async (ctx) => openWorkflows(ctx),
+  });
 }

package/src/index.ts

@@ -22,9 +22,15 @@ export {
   matchModelIn,
   type AgentRunCall,
   type AgentRunResult,
+  type AgentTelemetryEvent,
+  type AgentTurnUsage,
+  type AgentUsage,
   type ThinkingLevel,
   type ModelLike,
   type ModelRegistryLike,
+  type ModelRuntimeCreateOptions,
+  type ModelRuntimeFactory,
+  type ModelRuntimeLike,
 } from "./workflow/agent-runner.ts";
 export { createStructuredOutputTool, type StructuredOutputCapture } from "./workflow/structured-output.ts";
 export {
@@ -42,8 +48,22 @@ export {
   renderWorkflowLines,
   renderWorkflowText,
   preview,
+  type WorkflowAgentSnapshot,
+  type WorkflowAgentUsageSnapshot,
   type WorkflowSnapshot,
 } from "./workflow/display.ts";
+export {
+  WorkflowRunDetails,
+  MAX_LIVE_TASK_BYTES,
+  MAX_LIVE_TASK_LINES,
+  MAX_LIVE_RUN_BYTES,
+  MAX_TASK_TRANSCRIPT_BYTES,
+  MAX_RUN_TRANSCRIPT_BYTES,
+  type WorkflowTaskDetail,
+  type WorkflowTaskSummary,
+  type WorkflowTaskUsage,
+  type WorkflowTimelineEvent,
+} from "./workflow/run-details.ts";
 export {
   createWorktree,
   captureWorktreeDiff,

package/src/mode.ts

@@ -154,9 +154,13 @@ export class UltracodeMode {
 
   /** Stop enforcing synchronously, then restore effort before session teardown. */
   suspend(pi: ExtensionAPI): void {
-    if (this.suspended) return;
+    if (this.suspended) {
+      this.syncWorkflowTool(pi);
+      return;
+    }
     this.suspended = true;
     this.restorePreviousThinking(pi);
+    this.syncWorkflowTool(pi);
   }
 
   /**
@@ -191,6 +195,12 @@ export class UltracodeMode {
     return this.budgetTotal;
   }
 
+  /** Keep tool availability aligned with the current mode state. */
+  syncWorkflowTool(pi: ExtensionAPI): void {
+    if (this.isEnforcing()) this.activateWorkflowTool(pi);
+    else this.deactivateWorkflowTool(pi);
+  }
+
   tagline(): string {
     return ULTRACODE_TAGLINE;
   }
@@ -221,13 +231,16 @@ export class UltracodeMode {
       this.enabled = true;
     }
     this.applyUltracodeThinking(pi);
-    this.activateWorkflowTool(pi);
+    this.syncWorkflowTool(pi);
     this.persist(pi);
   }
 
   /** Turn ultracode off, restoring the previous thinking level. */
   disable(pi: ExtensionAPI): void {
-    if (!this.enabled) return;
+    if (!this.enabled) {
+      this.syncWorkflowTool(pi);
+      return;
+    }
     const previous = this.previousThinking;
     this.restorePreviousThinking(pi);
     this.pendingPreviousThinking = previous && !this.pendingRestoreSucceeded(previous)
@@ -236,6 +249,7 @@ export class UltracodeMode {
     this.pendingClearGeneration++;
     this.enabled = false;
     this.suspended = false;
+    this.syncWorkflowTool(pi);
     this.persist(pi);
   }
 
@@ -290,6 +304,7 @@ export class UltracodeMode {
       this.previousDefaultThinking = globalPreference;
       this.legacyDefaultMigrationPending = false;
       this.appliedThinking = current;
+      this.syncWorkflowTool(pi);
       if (target && current !== target) this.applyCompatibleThinking(pi, target);
       if (target && !this.pendingRestoreSucceeded(target)) {
         this.pendingPreviousThinking = target;
@@ -304,6 +319,7 @@ export class UltracodeMode {
     this.suspended = false;
     this.enabled = latest.enabled;
     this.budgetTotal = latest.budgetTotal;
+    this.syncWorkflowTool(pi);
     const maxIsUnknownToRuntime = !this.runtimeSupportsMaxThinking
       && preference.effective === ULTRACODE_THINKING_LEVEL;
     this.previousThinking = latest.previousThinking
@@ -330,7 +346,6 @@ export class UltracodeMode {
     this.pendingPreviousThinking = this.enabled ? undefined : latest.pendingPreviousThinking;
     if (this.enabled) {
       this.applyUltracodeThinking(pi);
-      this.activateWorkflowTool(pi);
       if (migratesLegacyDefault) {
         this.queueDefaultThinkingRestore(() => {
           this.legacyDefaultMigrationPending = false;
@@ -430,7 +445,7 @@ export class UltracodeMode {
     }
   }
 
-  private isEnforcing(): boolean {
+  isEnforcing(): boolean {
     return this.enabled && !this.suspended;
   }
 
@@ -509,7 +524,18 @@ export class UltracodeMode {
         pi.setActiveTools([...active, this.workflowToolName]);
       }
     } catch {
-      // ignore
+      // Mode enforcement remains usable when tool selection is unavailable.
+    }
+  }
+
+  private deactivateWorkflowTool(pi: ExtensionAPI): void {
+    try {
+      const active = pi.getActiveTools();
+      if (active.includes(this.workflowToolName)) {
+        pi.setActiveTools(active.filter((name) => name !== this.workflowToolName));
+      }
+    } catch {
+      // The execution guards still fail closed when selection cannot be updated.
     }
   }
 

package/src/prompts.ts

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