@runfusion/fusion 0.50.0 → 0.52.0

package/dist/pi-claude-cli/index.ts

@@ -190,6 +190,19 @@ export default function (pi: ExtensionAPI) {
     // catalog catches up.
     // https://platform.claude.com/docs/en/about-claude/models/overview
     const extraModels: typeof catalogModels = [
+      /*
+       * FNXC:ModelCatalog 2026-06-30-12:31:
+       * The vendored Claude CLI provider has its own model list because it exposes `pi-claude-cli` independently from direct `anthropic`. Add Claude Sonnet 5 here as supplemental metadata so Claude CLI users can select it before the upstream pi-ai catalog catches up, while the dedupe below prevents duplicate rows after it does.
+       */
+      {
+        id: "claude-sonnet-5",
+        name: "Claude Sonnet 5",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+        contextWindow: 1_000_000,
+        maxTokens: 128_000,
+      },
       {
         id: "claude-opus-4-7",
         name: "Claude Opus 4.7",

package/dist/pi-claude-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion/pi-claude-cli",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "type": "module",
   "private": true,
   "main": "index.ts",

package/dist/pi-claude-cli/src/__tests__/process-manager.test.ts

@@ -61,14 +61,14 @@ describe("buildClaudeSpawnArgs", () => {
   });
 
   it("builds args including model and optional session/mcp flags", () => {
-    const args = buildClaudeSpawnArgs("claude-sonnet-4-6", undefined, {
+    const args = buildClaudeSpawnArgs("claude-sonnet-5", undefined, {
       resumeSessionId: "sess-1",
       effort: "high",
       mcpConfigPath: "/tmp/mcp.json",
     });
 
     expect(args).toContain("--model");
-    expect(args).toContain("claude-sonnet-4-6");
+    expect(args[args.indexOf("--model") + 1]).toBe("claude-sonnet-5");
     expect(args).toContain("--resume");
     expect(args).toContain("sess-1");
     expect(args).toContain("--effort");

package/dist/pi-claude-cli/src/__tests__/provider.test.ts

@@ -127,6 +127,7 @@ describe("provider registration (default export)", () => {
     const modelIds = new Set(config.models.map((m: { id: string }) => m.id));
 
     for (const id of [
+      "claude-sonnet-5",
       "claude-opus-4-7",
       "claude-sonnet-4-6",
       "claude-sonnet-4-5",
@@ -134,6 +135,15 @@ describe("provider registration (default export)", () => {
     ]) {
       expect(modelIds.has(id)).toBe(true);
     }
+
+    expect(config.models.find((m: { id: string }) => m.id === "claude-sonnet-5")).toMatchObject({
+      name: "Claude Sonnet 5",
+      reasoning: true,
+      input: ["text", "image"],
+      cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+      contextWindow: 1_000_000,
+      maxTokens: 128_000,
+    });
   });
 
   it("deduplicates extra models when catalog already includes them", async () => {
@@ -143,6 +153,17 @@ describe("provider registration (default export)", () => {
 
     getModelsMock.mockReturnValueOnce([
       ...mockModels,
+      {
+        id: "claude-sonnet-5",
+        name: "Claude Sonnet 5 Upstream",
+        api: "anthropic",
+        provider: "anthropic",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+        contextWindow: 1_000_000,
+        maxTokens: 128_000,
+      } as any,
       {
         id: "claude-sonnet-4-6",
         name: "Claude Sonnet 4.6",
@@ -160,10 +181,12 @@ describe("provider registration (default export)", () => {
     mod.default(mockPi);
 
     const config = registerProvider.mock.calls[0][1];
-    const matches = config.models.filter(
-      (m: { id: string }) => m.id === "claude-sonnet-4-6",
-    );
-    expect(matches).toHaveLength(1);
+    for (const id of ["claude-sonnet-5", "claude-sonnet-4-6"]) {
+      const matches = config.models.filter(
+        (m: { id: string }) => m.id === id,
+      );
+      expect(matches).toHaveLength(1);
+    }
   });
 });
 

package/dist/plugin-sdk/index.d.ts

@@ -689,6 +689,13 @@ interface CustomFieldRejection {
     detail: string;
 }
 
+type WorkflowLifecycleWarningCode = "missing-completion-summary" | "missing-merge-region" | "unsafe-terminal-before-merge" | "optional-group-after-execution" | "review-gate-without-failure-route";
+interface WorkflowLifecycleWarning {
+    code: WorkflowLifecycleWarningCode;
+    nodeId?: string;
+    message: string;
+}
+
 interface WorkflowNodeLayout {
     x: number;
     y: number;
@@ -698,15 +705,18 @@ interface WorkflowDefinition {
     id: string;
     name: string;
     description: string;
+    icon?: string;
     kind: WorkflowDefinitionKind;
     ir: WorkflowIr;
     layout: Record<string, WorkflowNodeLayout>;
+    lifecycleWarnings?: WorkflowLifecycleWarning[];
     createdAt: string;
     updatedAt: string;
 }
 interface WorkflowDefinitionInput {
     name: string;
     description?: string;
+    icon?: string;
     ir: WorkflowIr;
     layout?: Record<string, WorkflowNodeLayout>;
     kind?: WorkflowDefinitionKind;
@@ -714,6 +724,7 @@ interface WorkflowDefinitionInput {
 interface WorkflowDefinitionUpdate {
     name?: string;
     description?: string;
+    icon?: string | null;
     ir?: WorkflowIr;
     layout?: Record<string, WorkflowNodeLayout>;
     rehomeTo?: string;
@@ -2531,6 +2542,7 @@ interface TaskStoreEvents {
         settings: Settings;
         previous: Settings;
     }];
+    "artifact:registered": [artifact: Artifact];
     "agent:log": [entry: AgentLogEntry];
     "merger:autostashOrphans": [
         data: {
@@ -2661,6 +2673,8 @@ declare class TaskStore extends EventEmitter<TaskStoreEvents> {
     private scanAndRecordCitations;
     private getTaskSelectClause;
     private computeTimedExecutionMs;
+    private getLatestAgentLogActivityMs;
+    private hasFreshAgentLogActivitySinceTaskUpdate;
     private getTaskSelectClauseWithActivityLogLimit;
     private createTaskPersistSerializationContext;
     private getTaskPersistValues;
@@ -2901,6 +2915,7 @@ declare class TaskStore extends EventEmitter<TaskStoreEvents> {
     handoffToReview(taskId: string, opts: HandoffToReviewOptions): Promise<Task>;
     private resolveWorkflowMoveActor;
     private resolveWorkflowBypassGuards;
+    private isWorkflowDoneBypassGuardedTask;
     private shouldSkipWorkflowMovePolicies;
     private prepareWorkflowMovePolicyPreflight;
     private evaluateWorkflowMovePolicies;
@@ -3000,6 +3015,7 @@ declare class TaskStore extends EventEmitter<TaskStoreEvents> {
         githubTracking?: TaskGithubTracking | null;
         tokenUsage?: TaskTokenUsage | null;
         modifiedFiles?: string[] | null;
+        workflowTransitionNotification?: Task["workflowTransitionNotification"] | null;
         missionId?: string | null;
         sliceId?: string | null;
     }, runContext?: RunMutationContext): Promise<Task>;
@@ -4327,7 +4343,7 @@ declare const COMPLETION_DOCUMENTATION_MODES: readonly ["off", "changeset", "cha
 type CompletionDocumentationMode = (typeof COMPLETION_DOCUMENTATION_MODES)[number];
 declare const THEME_MODES: readonly ["dark", "light", "system"];
 type ThemeMode = (typeof THEME_MODES)[number];
-declare const COLOR_THEMES: readonly ["default", "ocean", "forest", "sunset", "zen", "berry", "high-contrast", "industrial", "monochrome", "slate", "ash", "air", "graphite", "silver", "solarized", "factory", "factory-mono", "ayu", "one-dark", "nord", "dracula", "gruvbox", "tokyo-night", "catppuccin-mocha", "github-dark", "everforest", "rose-pine", "kanagawa", "night-owl", "palenight", "monokai-pro", "slime", "brutalist", "neon-city", "parchment", "terminal", "glass", "horizon", "vitesse", "outrun", "snazzy", "porple", "espresso", "mars", "poimandres", "ember", "rust", "copper", "foundry", "carbon", "sandstone", "lagoon", "frost", "lavender", "neon-bloom", "sepia", "shadcn", "shadcn-custom", "shadcn-blue", "shadcn-green", "shadcn-red", "shadcn-purple", "shadcn-pink", "shadcn-orange", "shadcn-yellow", "shadcn-mono-red", "shadcn-mono-blue", "shadcn-mono-green", "shadcn-mono-purple", "shadcn-mono-pink", "shadcn-mono-orange", "shadcn-mono-yellow", "shadcn-black", "shadcn-gray", "shadcn-gray-blue"];
+declare const COLOR_THEMES: readonly ["default", "ocean", "forest", "sunset", "zen", "berry", "high-contrast", "industrial", "monochrome", "slate", "ash", "air", "graphite", "silver", "solarized", "factory", "factory-mono", "ayu", "one-dark", "nord", "dracula", "gruvbox", "tokyo-night", "catppuccin-mocha", "github-dark", "everforest", "rose-pine", "kanagawa", "night-owl", "palenight", "monokai-pro", "slime", "brutalist", "neon-city", "parchment", "terminal", "glass", "horizon", "vitesse", "outrun", "snazzy", "porple", "espresso", "mars", "poimandres", "ember", "rust", "copper", "foundry", "carbon", "sandstone", "lagoon", "frost", "lavender", "neon-bloom", "sepia", "shadcn", "shadcn-ember", "shadcn-custom", "shadcn-blue", "shadcn-green", "shadcn-red", "shadcn-purple", "shadcn-pink", "shadcn-orange", "shadcn-yellow", "shadcn-mono-red", "shadcn-mono-blue", "shadcn-mono-green", "shadcn-mono-purple", "shadcn-mono-pink", "shadcn-mono-orange", "shadcn-mono-yellow", "shadcn-black", "shadcn-gray", "shadcn-gray-blue"];
 type ColorTheme = (typeof COLOR_THEMES)[number];
 declare const SUPPORTED_LOCALES: readonly ["en", "zh-CN", "zh-TW", "fr", "es", "ko"];
 type Locale = (typeof SUPPORTED_LOCALES)[number];
@@ -4418,6 +4434,7 @@ interface WorkflowStepResult {
     workflowStepId: string;
     workflowStepName: string;
     phase?: WorkflowStepPhase;
+    source?: "optional-group" | "node";
     status: "passed" | "failed" | "advisory_failure" | "skipped" | "pending";
     output?: string;
     verdict?: "APPROVE" | "APPROVE_WITH_NOTES" | "REVISE";
@@ -4474,6 +4491,7 @@ interface PrInfo {
     commentCount: number;
     isDraft?: boolean;
     draft?: boolean;
+    manual?: boolean;
     autoMergeOnGreen?: boolean;
     autoMergeStrategy?: "merge" | "squash" | "rebase";
     lastMergeError?: string;
@@ -4535,6 +4553,15 @@ interface TaskLogEntry {
     outcome?: string;
     runContext?: RunMutationContext;
 }
+type WorkflowTransitionNotificationKind = "manual-merge-hold" | "recovery-requeue";
+interface WorkflowTransitionNotificationMarker {
+    kind: WorkflowTransitionNotificationKind;
+    column: ColumnId;
+    transitionId: string;
+    nodeId?: string;
+    reason?: string;
+    createdAt: string;
+}
 type ActivityEventType = "task:created" | "task:moved" | "task:updated" | "task:deleted" | "task:merged" | "task:failed" | "task:duplicate-warning-overridden" | "task:auto-archived-deterministic-duplicate" | "task:auto-archived-near-duplicate" | "task:near-duplicate-flagged" | "task:release-authorization-required" | "task:auto-archived-ghost-bug" | "task:auto-archived-duplicate" | "task:merge-worktree-reacquired" | "settings:updated" | "project:isolation-transition";
 interface ActivityLogEntry {
     id: string;
@@ -5113,6 +5140,7 @@ interface Task {
     stalePausedReview?: StalePausedReviewSignal;
     inReviewStalled?: InReviewStalledSignal;
     stalePausedTodo?: StalePausedTodoSignal;
+    workflowTransitionNotification?: WorkflowTransitionNotificationMarker;
     stalledReview?: StalledReviewSignal;
     tokenUsage?: TaskTokenUsage;
     size?: "S" | "M" | "L";
@@ -5401,6 +5429,7 @@ interface GlobalSettings {
     colorTheme?: ColorTheme;
     shadcnCustomColors?: Record<string, string>;
     dashboardFontScalePct?: number;
+    dismissModalsOnOutsideClick?: boolean;
     language?: Locale;
     defaultProvider?: string;
     defaultModelId?: string;
@@ -5577,6 +5606,7 @@ interface ProjectSettings {
     groupOverlappingFiles: boolean;
     ignoreHiddenOverlapPaths?: boolean;
     overlapIgnorePaths?: string[];
+    allowAbsoluteFileBrowserPaths?: boolean;
     autoMerge: boolean;
     testMode?: boolean;
     mergeRequestContractShadowEnabled?: boolean;
@@ -5613,6 +5643,10 @@ interface ProjectSettings {
     testCommand?: string;
     buildCommand?: string;
     recycleWorktrees?: boolean;
+    showWorktreeGrouping?: boolean;
+    openTasksInRightSidebar?: boolean;
+    openMobileTasksInPopup?: boolean;
+    taskDetailChatFirst?: boolean;
     executorAllowSiblingBranchRename?: boolean;
     worktreeNaming?: "random" | "task-id" | "task-title";
     worktrunk?: WorktrunkSettings;
@@ -5769,6 +5803,8 @@ interface ProjectSettings {
     titleSummarizerModelId?: string;
     titleSummarizerFallbackProvider?: string;
     titleSummarizerFallbackModelId?: string;
+    prTitlePromptInstructions?: string;
+    prDescriptionPromptInstructions?: string;
     scripts?: Record<string, string>;
     setupScript?: string;
     insightExtractionEnabled?: boolean;
@@ -5795,6 +5831,7 @@ interface ProjectSettings {
     reflectionAfterTask?: boolean;
     reviewHandoffPolicy?: "disabled" | "comment-triggered" | "always";
     quickChatButtonMode?: "floating" | "footer" | "off";
+    quickChatCloseOnOutsideClick?: boolean;
     showQuickChatFAB?: boolean;
     chatAutoCleanupDays?: number;
     mailAutoCleanupDays?: number;

package/dist/plugins/fusion-plugin-acp-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/acp-runtime",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-cli-printing-press/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/cli-printing-press",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "type": "module",
   "private": true,
   "exports": {

package/dist/plugins/fusion-plugin-compound-engineering/bundled.js

@@ -2413,7 +2413,7 @@ var plugin = definePlugin({
       viewId: "compound-engineering",
       label: "Compound Engineering",
       componentPath: "./dashboard-view",
-      icon: "Sparkles",
+      icon: "Boxes",
       placement: "primary",
       order: 36
     }

package/dist/plugins/fusion-plugin-compound-engineering/manifest.json

@@ -10,7 +10,7 @@
       "viewId": "compound-engineering",
       "label": "Compound Engineering",
       "componentPath": "./dashboard-view",
-      "icon": "Sparkles",
+      "icon": "Boxes",
       "placement": "primary",
       "order": 36
     }

package/dist/plugins/fusion-plugin-compound-engineering/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/compound-engineering",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-cursor-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/cursor-runtime",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-dependency-graph/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/dependency-graph",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-droid-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/droid-runtime",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-hermes-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/hermes-runtime",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-openclaw-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/openclaw-runtime",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-paperclip-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/paperclip-runtime",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-reports/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/reports",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "type": "module",
   "private": true,
   "exports": {

package/dist/plugins/fusion-plugin-roadmap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/roadmap",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-whatsapp-chat/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/whatsapp-chat",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "type": "module",
   "private": true,
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runfusion/fusion",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "license": "MIT",
   "description": "Fusion CLI: HTTP API server, daemon, dashboard launcher, and task tooling for the Fusion AI coding agent.",
   "homepage": "https://github.com/Runfusion/Fusion#readme",

package/skill/fusion/SKILL.md

@@ -28,6 +28,7 @@ Mission → Milestone → Slice → Feature → Task
 **Tool categories:**
 <!-- BEGIN: tool-categories (auto-generated by scripts/sync-fusion-skill-tools.mjs — do not edit by hand) -->
 - **Task tools** — `fn_task_create`, `fn_task_update`, `fn_task_list`, `fn_task_show`, `fn_task_attach`, `fn_task_pause`, `fn_task_unpause`, `fn_task_retry`, `fn_task_duplicate`, `fn_task_refine`, `fn_task_archive`, `fn_task_unarchive`, `fn_task_delete`, `fn_task_plan`
+- **Workflow tools** — `fn_workflow_list`, `fn_workflow_get`, `fn_workflow_create`, `fn_workflow_update`, `fn_workflow_delete`, `fn_workflow_settings`, `fn_trait_list`, `fn_workflow_select`
 - **GitHub tools** — `fn_task_import_github`, `fn_task_import_github_issue`, `fn_task_browse_github_issues`
 - **Mission tools** — `fn_mission_create`, `fn_mission_list`, `fn_mission_show`, `fn_mission_list_goals`, `fn_mission_link_goal`, `fn_mission_unlink_goal`, `fn_mission_backfill_assertions`, `fn_mission_delete`, `fn_mission_update`, `fn_milestone_add`, `fn_slice_add`, `fn_feature_add`, `fn_feature_delete`, `fn_slice_delete`, `fn_milestone_delete`, `fn_slice_activate`, `fn_feature_link_task`, `fn_feature_update`, `fn_milestone_update`
 - **Goal tools** — `fn_goal_list`, `fn_goal_create`, `fn_goal_archive`, `fn_goal_show`

package/skill/fusion/references/best-practices.md

@@ -33,7 +33,7 @@ For work larger than L, use missions to break it into phases.
 | Vague idea needing refinement | `fn_task_plan` |
 | Large project with phases | `fn_mission_create` + hierarchy |
 | Task failed, needs retry | `fn_task_retry` |
-| Task needs manual intervention | `fn_task_pause` |
+| User explicitly requests manual control | `fn_task_pause` |
 | Completed task needs follow-up | `fn_task_refine` |
 | Clean up done tasks | `fn_task_archive` |
 | Import external work | `fn_task_import_github*` |
@@ -49,10 +49,10 @@ For work larger than L, use missions to break it into phases.
 ## Working with the AI Engine
 
 - **Don't fight the automation** — let triage, scheduler, and executor do their jobs
-- **Pause if needed** — use `fn_task_pause` when you want manual control
+- **Pause only on explicit user request** — use `fn_task_pause` for user-driven manual control, never as agent failure or blocker handling
 - **Steer don't micromanage** — use steering comments (via CLI `fn task steer`) to guide the AI without rewriting the spec
 - **Check progress** — use `fn_task_show` to monitor step completion
-- **Let it fail and retry** — if a task fails, check the log, then `fn_task_retry`
+- **Let it fail and retry** — if a task fails, check the log, then `fn_task_retry` or create a focused follow-up task instead of pausing it
 
 ## Mission Planning Tips
 

package/skill/fusion/references/engine-tools.md

@@ -1,11 +1,11 @@
 # Engine Session-Scoped Tools
 
-These tools are **not** part of the user-invokable extension surface. They are injected by the engine at runtime for specific agent session types.
+This reference documents tools injected by the engine at runtime for specific agent session types. Some shared workflow tools are also part of the public extension surface; use `references/extension-tools.md` as the canonical user-invokable extension reference and this page for runtime agent-role availability.
 
 - Source files: `packages/engine/src/agent-tools.ts`, `triage.ts`, `executor.ts`, `merger.ts`, `agent-heartbeat.ts`
 - Availability: only when the engine creates a session for the matching agent role
 - Runtime contract: engine sessions now forward requested skill names (`skillSelection.requestedSkillNames`) into the generic runtime `skills` field so non-pi runtimes can still receive Fusion skill intent.
-- Important: do not tell users to call these directly from the generic extension tool list
+- Important: do not tell users to call runtime-only tools directly from the generic extension tool list
 
 ## Shared runtime tools (`agent-tools.ts`)
 
@@ -54,7 +54,7 @@ These tools are **not** part of the user-invokable extension surface. They are i
 | `fn_send_message` | executor, step-session, heartbeat | Send inbox messages to agents/users | `to_id` (string), `content` (string), `type?` (`agent-to-agent` \| `agent-to-user`), `reply_to_message_id?` (string) |
 | `fn_read_messages` | executor, step-session, heartbeat | Read inbox messages | `unread_only?` (boolean), `limit?` (number) |
 | `fn_post_room_message` | heartbeat | Post a message to a chat room the agent is a member of | `roomId` (string), `content` (string), `replyToMessageId?` (string), `mentions?` (string[]) |
-| `fn_artifact_register` | triage, executor, heartbeat; chat/planning (explicit `task_id`) | Register an artifact (document, image, video, audio, or other) so other agents and tasks can discover it | `type` (string), `title` (string), `description?` (string), `mimeType?` (string), `uri?` (string), `content?` (string), `taskId?` (string); chat/planning also require `task_id` (string) |
+| `fn_artifact_register` | triage, executor, heartbeat; chat/planning (explicit `task_id`) | Register an artifact (document, image, video, audio, or other) so other agents and tasks can discover it; image artifacts may provide `dataBase64` bytes for registry-managed media storage | `type` (string), `title` (string), `description?` (string), `mimeType?` (string), `uri?` (string), `content?` (string), `dataBase64?` (base64 string), `taskId?` (string); chat/planning also require `task_id` (string) |
 | `fn_artifact_list` | triage, executor, heartbeat; chat/planning (explicit `task_id`) | List registered artifacts across agents and tasks with filters for type, authorId, taskId, search, limit, and offset | `type?` (string), `authorId?` (string), `taskId?` (string), `search?` (string), `limit?` (number), `offset?` (number); chat/planning also require `task_id` (string) |
 | `fn_artifact_view` | triage, executor, heartbeat | View a registered artifact by id, including metadata and inline content or the uri/path reference for media artifacts | `id` (string) |
 

package/skill/fusion/references/extension-tools.md

@@ -18,7 +18,7 @@ Create a new task on the Fusion task board. The task enters the planning column
 | `depends` | array | — | Task IDs this depends on (e.g. ['FN-001', 'FN-002']) |
 | `agentId` | string | — | Agent ID to assign this task to (e.g. 'agent-abc123') |
 | `priority` | string(enum) | — | Task priority (low, normal, high, urgent) |
-| `workflow_id` | string | — | Workflow ID to select for the new task (e.g. 'WF-003' or 'builtin:coding'). |
+| `workflow_id` | string | — | Workflow ID to select for the new task (e.g. 'WF-003' or 'builtin:coding'). Omit to inherit the project default workflow. Use fn_workflow_list to discover valid IDs. |
 
 ### fn_task_update
 
@@ -33,7 +33,7 @@ Update fields on an existing task. Supports modifying the title, description, de
 | `agentId` | union | — | Agent ID to assign this task to, or null to clear (e.g. 'agent-abc123') |
 | `nodeId` | union | — | Node ID override for this task, or null to clear |
 | `priority` | string(enum) | — | Task priority (low, normal, high, urgent) |
-| `workflow_id` | union | — | Workflow ID to select for this task (e.g. 'WF-003' or 'builtin:coding'), |
+| `workflow_id` | union | — | Workflow ID to select for this task (e.g. 'WF-003' or 'builtin:coding'), or null to clear the workflow selection and revert to the project default. Use fn_workflow_list to discover valid IDs. |
 
 ### fn_task_list
 
@@ -63,7 +63,7 @@ Attach a file to a task. Supports images (png, jpg, gif, webp) and text files (t
 
 ### fn_task_pause
 
-Pause a task — stops all automated agent and scheduler interaction for this task.
+Pause a task for explicit user-requested manual control — stops all automated agent and scheduler interaction. Agents should not pause tasks to handle failures or blockers; use retry, create/delegate follow-up work, or let the task surface as failed instead.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -136,6 +136,83 @@ Create a task via AI-guided planning mode — interactive conversation to refine
 | `description` | string | — | Initial plan description (optional) — the AI will ask clarifying questions if not provided |
 | `baseBranch` | string | — | Optional base branch for the task created from this planning session |
 
+## Workflow Tools
+
+### fn_workflow_list
+
+List built-in and custom Fusion workflow definitions available in this project.
+
+No parameters.
+
+### fn_workflow_get
+
+Fetch a Fusion workflow definition by ID, including its resolved workflow IR.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_id` | string | ✓ | The workflow definition ID to fetch (e.g. 'WF-003', or a 'builtin:*' id). Use fn_workflow_list to discover available IDs. |
+
+### fn_workflow_create
+
+Create a custom Fusion workflow definition from a validated workflow IR.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | ✓ | Workflow name (required, non-empty). |
+| `description` | string | — | Optional human-readable description. |
+| `icon` | string | — | Optional compact plain-text icon for this custom workflow. |
+| `ir` | unknown | ✓ | Workflow graph (intermediate representation). Validated server-side; a malformed graph is rejected. |
+| `layout` | record | — | Optional node layout map keyed by node id. |
+| `confirm_policy_escalation` | boolean | — | Set true to confirm binding a column to an agent whose permission policy is broader (more privileged) than the project default. Required when such a binding is present; the create is otherwise rejected naming the offending column. |
+
+### fn_workflow_update
+
+Update a custom Fusion workflow definition's metadata, IR, or layout.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_id` | string | ✓ | The workflow definition ID to update (built-ins cannot be edited). |
+| `name` | string | — | New name. |
+| `description` | string | — | New description. |
+| `icon` | string | — | New compact plain-text icon; blank clears it. |
+| `ir` | unknown | — | Replacement workflow graph (validated server-side). |
+| `layout` | record | — | Replacement node layout map. |
+| `rehome_to` | string | — | When an IR update removes a column that still holds cards, supply the column id to re-home those occupants into. Required to resolve an OccupiedColumns conflict; the target must exist in the new IR. |
+| `confirm_policy_escalation` | boolean | — | Set true to confirm binding a column to an agent whose permission policy is broader (more privileged) than the project default. Required when such a binding is present; the update is otherwise rejected naming the offending column. |
+
+### fn_workflow_delete
+
+Delete a custom Fusion workflow definition; built-in workflows are protected.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_id` | string | ✓ | The workflow definition ID to delete (built-ins cannot be deleted). |
+
+### fn_workflow_settings
+
+Read or write per-project values for a workflow's declared settings.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action` | union | ✓ | `get` reads the stored setting VALUES plus the engine-effective values for the workflow; `set` writes values (requires `values`). |
+| `workflow_id` | string | ✓ | The workflow whose setting VALUES to read/write (e.g. 'WF-003', or a 'builtin:*' id). Values are scoped per (workflow, project). Built-in workflow VALUES are writable even though built-in DECLARATIONS are not (declarations are edited via the workflow IR's `settings`). Values are validated against THIS workflow's declared settings (use fn_workflow_get to inspect them). |
+| `values` | record | — | For action='set': a map of settingId → value to write. A `null` value DELETES the override (null-as-delete). Each value is validated against the named workflow's declaration; on ANY rejection (unknown-setting/type-mismatch/enum-violation/no-settings-defined) nothing is persisted and the typed rejection list is returned. |
+
+### fn_trait_list
+
+List column traits available when authoring Fusion workflow IR columns.
+
+No parameters.
+
+### fn_workflow_select
+
+Assign a workflow definition to a task by workflow ID.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_id` | string | ✓ | The workflow definition ID to select (e.g. 'WF-003', or a 'builtin:*' id). Use fn_workflow_list to discover available IDs. |
+| `task_id` | string | — | Task to assign the workflow to. Defaults to the current task. |
+
 ## GitHub Tools
 
 ### fn_task_import_github
@@ -456,8 +533,8 @@ Create a new task and assign it to a specific agent for execution. The task goes
 |-----------|------|----------|-------------|
 | `agent_id` | string | ✓ | The agent ID to delegate work to |
 | `description` | string | ✓ | What needs to be done |
-| `dependencies` | array | — | Task IDs this new task depends on (e.g. [\"KB-001\"] |
-| `workflow_id` | string | — | Workflow ID to select for the new task (e.g. 'WF-003' or 'builtin:coding'). |
+| `dependencies` | array | — | Task IDs this new task depends on (e.g. ["KB-001"] |
+| `workflow_id` | string | — | Workflow ID to select for the new task (e.g. 'WF-003' or 'builtin:coding'). Omit to inherit the project default workflow. Use fn_workflow_list to discover valid IDs. |
 | `override` | boolean | — | Set true to bypass executor-role assignment policy |
 
 ### fn_agent_show

package/skill/fusion/references/fusion-capabilities.md

@@ -12,12 +12,20 @@ All skill/extension tool invocations in this catalog use the public `fn_*` names
 <!-- BEGIN: fusion-capabilities-tool-table (auto-generated by scripts/sync-fusion-skill-tools.mjs — do not edit by hand) -->
 | Tool | Purpose |
 |------|---------|
+| `fn_workflow_list` | List built-in and custom Fusion workflow definitions available in this project. |
+| `fn_workflow_get` | Fetch a Fusion workflow definition by ID, including its resolved workflow IR. |
+| `fn_workflow_create` | Create a custom Fusion workflow definition from a validated workflow IR. |
+| `fn_workflow_update` | Update a custom Fusion workflow definition's metadata, IR, or layout. |
+| `fn_workflow_delete` | Delete a custom Fusion workflow definition; built-in workflows are protected. |
+| `fn_workflow_settings` | Read or write per-project values for a workflow's declared settings. |
+| `fn_trait_list` | List column traits available when authoring Fusion workflow IR columns. |
+| `fn_workflow_select` | Assign a workflow definition to a task by workflow ID. |
 | `fn_task_create` | Create a new task on the Fusion task board. The task enters the planning column where the AI planning agent will plan it into a full prompt with steps, file scope, and acceptance criteria. Optionally pass workflow_id to select a workflow at creation time; use fn_workflow_list to discover valid IDs. |
 | `fn_task_update` | Update fields on an existing task. Supports modifying the title, description, dependencies, assigned agent, priority, and workflow_id after task creation. Set workflow_id to a workflow ID to select it, or null to clear the workflow selection. |
 | `fn_task_list` | List all tasks on the Fusion board, grouped by column. |
 | `fn_task_show` | Show full details for a task including steps, progress, and log entries. |
 | `fn_task_attach` | Attach a file to a task. Supports images (png, jpg, gif, webp) and text files (txt, log, json, yaml, yml, toml, csv, xml). |
-| `fn_task_pause` | Pause a task — stops all automated agent and scheduler interaction for this task. |
+| `fn_task_pause` | Pause a task for explicit user-requested manual control — stops all automated agent and scheduler interaction. Agents should not pause tasks to handle failures or blockers; use retry, create/delegate follow-up work, or let the task surface as failed instead. |
 | `fn_task_unpause` | Unpause a task — resumes automated agent and scheduler interaction. |
 | `fn_task_retry` | Retry a failed task — clears the error state. Non-review failures move to todo; in-review execution failures move to todo preserving progress; in-review merge failures stay in-place for auto-merge retry. |
 | `fn_task_duplicate` | Duplicate an existing task, creating a fresh copy in planning. Copies the title and description but resets all execution state. The AI planning agent will replan the new task. |

package/skill/fusion/workflows/task-management.md

@@ -60,7 +60,7 @@ Use `fn_task_show` with the task ID:
 
 | Action | Tool | Notes |
 |--------|------|-------|
-| Pause automation | `fn_task_pause` | Stops scheduler and executor from touching the task |
+| Pause automation | `fn_task_pause` | Stops scheduler and executor from touching the task; use only when the user explicitly requests manual control, not for failure/blocker handling |
 | Resume automation | `fn_task_unpause` | Re-enables automated processing |
 | Retry failed task | `fn_task_retry` | Clears error, moves back to todo |
 | Duplicate task | `fn_task_duplicate` | Creates fresh copy in triage |