From 87ee013d787bdd4f652b7ed6c4b3ce79c4e3a703 Mon Sep 17 00:00:00 2001
From: otomatty <saedgewell@gmail.com>
Date: Sun, 5 Apr 2026 09:21:39 +0900
Subject: [PATCH 1/5] feat(ai-chat): add Claude Code multi-step workflow panel
 (#462)

- Workflow tab, templates, save/import JSON, run/pause/resume/stop
- streamClaudeQuery + runWorkflowExecution; note updates via editor handler
- parseWorkflowDefinitionImport for safe JSON import

Made-with: Cursor
---
 src/components/ai-chat/AIChatPanelContent.tsx |  30 +-
 .../ai-chat/AIChatViewTabs.test.tsx           |  11 +-
 src/components/ai-chat/AIChatViewTabs.tsx     |  11 +-
 .../ai-chat/AIChatWorkflowPanel.tsx           |  16 +
 src/components/ai-chat/WorkflowPanelForm.tsx  | 133 +++++++++
 .../ai-chat/WorkflowPanelMetaSection.tsx      | 166 +++++++++++
 .../ai-chat/WorkflowPanelStepsAndProgress.tsx | 110 +++++++
 src/components/ai-chat/workflowPanelTypes.ts  |  12 +
 src/hooks/useWorkflowDraft.ts                 | 163 ++++++++++
 src/hooks/useWorkflowPanelLogic.ts            |  21 ++
 src/hooks/useWorkflowRunSession.ts            | 180 +++++++++++
 src/hooks/workflowRunOutcomeHandlers.ts       |  71 +++++
 src/i18n/locales/en/aiChat.json               |  44 +++
 src/i18n/locales/ja/aiChat.json               |  44 +++
 .../claudeCode/runQueryToCompletion.test.ts   |   2 +
 src/lib/claudeCode/runQueryToCompletion.ts    | 160 +---------
 src/lib/claudeCode/streamClaudeQuery.ts       | 205 +++++++++++++
 .../workflow/buildWorkflowStepPrompt.test.ts  |  44 +++
 src/lib/workflow/buildWorkflowStepPrompt.ts   |  80 +++++
 .../formatWorkflowNoteMarkdown.test.ts        |  32 ++
 .../workflow/formatWorkflowNoteMarkdown.ts    |  57 ++++
 src/lib/workflow/newWorkflowId.ts             |  15 +
 .../parseWorkflowDefinitionImport.test.ts     |  48 +++
 .../workflow/parseWorkflowDefinitionImport.ts |  88 ++++++
 src/lib/workflow/runWorkflowExecution.test.ts |  91 ++++++
 src/lib/workflow/runWorkflowExecution.ts      | 280 ++++++++++++++++++
 src/lib/workflow/templates.ts                 | 148 +++++++++
 src/lib/workflow/types.ts                     |  67 +++++
 src/stores/workflowDefinitionsStore.ts        |  39 +++
 29 files changed, 2200 insertions(+), 168 deletions(-)
 create mode 100644 src/components/ai-chat/AIChatWorkflowPanel.tsx
 create mode 100644 src/components/ai-chat/WorkflowPanelForm.tsx
 create mode 100644 src/components/ai-chat/WorkflowPanelMetaSection.tsx
 create mode 100644 src/components/ai-chat/WorkflowPanelStepsAndProgress.tsx
 create mode 100644 src/components/ai-chat/workflowPanelTypes.ts
 create mode 100644 src/hooks/useWorkflowDraft.ts
 create mode 100644 src/hooks/useWorkflowPanelLogic.ts
 create mode 100644 src/hooks/useWorkflowRunSession.ts
 create mode 100644 src/hooks/workflowRunOutcomeHandlers.ts
 create mode 100644 src/lib/claudeCode/streamClaudeQuery.ts
 create mode 100644 src/lib/workflow/buildWorkflowStepPrompt.test.ts
 create mode 100644 src/lib/workflow/buildWorkflowStepPrompt.ts
 create mode 100644 src/lib/workflow/formatWorkflowNoteMarkdown.test.ts
 create mode 100644 src/lib/workflow/formatWorkflowNoteMarkdown.ts
 create mode 100644 src/lib/workflow/newWorkflowId.ts
 create mode 100644 src/lib/workflow/parseWorkflowDefinitionImport.test.ts
 create mode 100644 src/lib/workflow/parseWorkflowDefinitionImport.ts
 create mode 100644 src/lib/workflow/runWorkflowExecution.test.ts
 create mode 100644 src/lib/workflow/runWorkflowExecution.ts
 create mode 100644 src/lib/workflow/templates.ts
 create mode 100644 src/lib/workflow/types.ts
 create mode 100644 src/stores/workflowDefinitionsStore.ts

diff --git a/src/components/ai-chat/AIChatPanelContent.tsx b/src/components/ai-chat/AIChatPanelContent.tsx
index 2eebbd69..8539bd28 100644
--- a/src/components/ai-chat/AIChatPanelContent.tsx
+++ b/src/components/ai-chat/AIChatPanelContent.tsx
@@ -14,6 +14,10 @@ const AIChatBranchTree = lazy(() =>
   import("./AIChatBranchTree").then((m) => ({ default: m.AIChatBranchTree })),
 );
 
+const AIChatWorkflowPanel = lazy(() =>
+  import("./AIChatWorkflowPanel").then((m) => ({ default: m.AIChatWorkflowPanel })),
+);
+
 /**
  * Props for {@link AIChatPanelContent}.
  * {@link AIChatPanelContent} 向けプロパティ。
@@ -116,7 +120,7 @@ export function AIChatPanelContent({
             onSwitchBranch={switchBranch}
             isStreaming={isStreaming}
           />
-        ) : (
+        ) : activeViewTab === "branch" ? (
           <Suspense fallback={null}>
             <AIChatBranchTree
               messageMap={messageMap}
@@ -127,18 +131,24 @@ export function AIChatPanelContent({
               onDeleteBranch={handleDeleteBranchFromTree}
             />
           </Suspense>
+        ) : (
+          <Suspense fallback={null}>
+            <AIChatWorkflowPanel />
+          </Suspense>
         )}
       </div>
 
-      <div className="bg-background border-t p-4">
-        <AIChatInput
-          onSendMessage={handleSendMessage}
-          onStopStreaming={stopStreaming}
-          prefillText={inputPrefill?.text}
-          prefillNonce={inputPrefill?.nonce}
-          focusEditorNonce={focusEditorNonce}
-        />
-      </div>
+      {activeViewTab !== "workflow" && (
+        <div className="bg-background border-t p-4">
+          <AIChatInput
+            onSendMessage={handleSendMessage}
+            onStopStreaming={stopStreaming}
+            prefillText={inputPrefill?.text}
+            prefillNonce={inputPrefill?.nonce}
+            focusEditorNonce={focusEditorNonce}
+          />
+        </div>
+      )}
     </div>
   );
 }
diff --git a/src/components/ai-chat/AIChatViewTabs.test.tsx b/src/components/ai-chat/AIChatViewTabs.test.tsx
index b21ac763..4506671a 100644
--- a/src/components/ai-chat/AIChatViewTabs.test.tsx
+++ b/src/components/ai-chat/AIChatViewTabs.test.tsx
@@ -19,11 +19,12 @@ describe("AIChatViewTabs", () => {
     vi.clearAllMocks();
   });
 
-  it("renders Chat and Branch tabs", () => {
+  it("renders Chat, Branch, and Workflow tabs", () => {
     const onTabChange = vi.fn();
     render(<AIChatViewTabs activeTab="chat" onTabChange={onTabChange} />);
     expect(screen.getByRole("tab", { name: "aiChat.viewTabs.chat" })).toBeInTheDocument();
     expect(screen.getByRole("tab", { name: "aiChat.viewTabs.branch" })).toBeInTheDocument();
+    expect(screen.getByRole("tab", { name: "aiChat.viewTabs.workflow" })).toBeInTheDocument();
   });
 
   it("Branch tab is always enabled", () => {
@@ -47,4 +48,12 @@ describe("AIChatViewTabs", () => {
     await user.click(screen.getByRole("tab", { name: "aiChat.viewTabs.chat" }));
     expect(onTabChange).toHaveBeenCalledWith("chat");
   });
+
+  it("calls onTabChange with workflow when Workflow tab is clicked", async () => {
+    const user = userEvent.setup();
+    const onTabChange = vi.fn();
+    render(<AIChatViewTabs activeTab="chat" onTabChange={onTabChange} />);
+    await user.click(screen.getByRole("tab", { name: "aiChat.viewTabs.workflow" }));
+    expect(onTabChange).toHaveBeenCalledWith("workflow");
+  });
 });
diff --git a/src/components/ai-chat/AIChatViewTabs.tsx b/src/components/ai-chat/AIChatViewTabs.tsx
index 2512a43d..b158b146 100644
--- a/src/components/ai-chat/AIChatViewTabs.tsx
+++ b/src/components/ai-chat/AIChatViewTabs.tsx
@@ -1,12 +1,12 @@
 import { useTranslation } from "react-i18next";
-import { MessageSquare, GitBranch } from "lucide-react";
+import { MessageSquare, GitBranch, ListChecks } from "lucide-react";
 import { Tabs, TabsList, TabsTrigger } from "@zedi/ui";
 
 /**
  * Active AI chat panel view: threaded messages or branch tree.
  * AI チャットパネルの表示：スレッド表示かブランチツリーか。
  */
-export type AIChatViewTab = "chat" | "branch";
+export type AIChatViewTab = "chat" | "branch" | "workflow";
 
 /**
  * Props for {@link AIChatViewTabs}.
@@ -43,6 +43,13 @@ export function AIChatViewTabs({ activeTab, onTabChange }: AIChatViewTabsProps)
           <GitBranch className="h-3.5 w-3.5" />
           {t("aiChat.viewTabs.branch")}
         </TabsTrigger>
+        <TabsTrigger
+          value="workflow"
+          className="flex h-7 items-center gap-1.5 px-3 text-xs data-[state=active]:shadow-sm"
+        >
+          <ListChecks className="h-3.5 w-3.5" />
+          {t("aiChat.viewTabs.workflow")}
+        </TabsTrigger>
       </TabsList>
     </Tabs>
   );
diff --git a/src/components/ai-chat/AIChatWorkflowPanel.tsx b/src/components/ai-chat/AIChatWorkflowPanel.tsx
new file mode 100644
index 00000000..a474adff
--- /dev/null
+++ b/src/components/ai-chat/AIChatWorkflowPanel.tsx
@@ -0,0 +1,16 @@
+/**
+ * Multi-step Claude Code workflow UI (Issue #462).
+ * Claude Code マルチステップワークフロー UI（Issue #462）。
+ */
+
+import { useWorkflowPanelLogic } from "@/hooks/useWorkflowPanelLogic";
+import { WorkflowPanelForm } from "./WorkflowPanelForm";
+
+/**
+ * Workflow editor and runner embedded in the AI chat panel.
+ * AI チャットパネルに埋め込むワークフロー編集・実行。
+ */
+export function AIChatWorkflowPanel() {
+  const logic = useWorkflowPanelLogic();
+  return <WorkflowPanelForm {...logic} />;
+}
diff --git a/src/components/ai-chat/WorkflowPanelForm.tsx b/src/components/ai-chat/WorkflowPanelForm.tsx
new file mode 100644
index 00000000..bb06471a
--- /dev/null
+++ b/src/components/ai-chat/WorkflowPanelForm.tsx
@@ -0,0 +1,133 @@
+/**
+ * Form layout for the workflow panel (Issue #462).
+ * ワークフローパネルのフォームレイアウト（Issue #462）。
+ */
+
+import { Button, ScrollArea } from "@zedi/ui";
+import { ListChecks, Pause, Play, Square } from "lucide-react";
+import { isTauriDesktop } from "@/lib/platform";
+import { WorkflowPanelMetaSection } from "./WorkflowPanelMetaSection";
+import { WorkflowPanelStepsAndProgress } from "./WorkflowPanelStepsAndProgress";
+import type { WorkflowPanelFormProps } from "./workflowPanelTypes";
+
+export type { WorkflowPanelFormProps } from "./workflowPanelTypes";
+
+/**
+ * Renders workflow name, templates, steps, progress, and run controls.
+ * ワークフロー名・テンプレート・ステップ・進捗・実行操作を描画する。
+ */
+export function WorkflowPanelForm(props: WorkflowPanelFormProps) {
+  const {
+    t,
+    draft,
+    setDraft,
+    definitions,
+    selectedSavedId,
+    progress,
+    activeRunSteps,
+    pausedState,
+    importInputRef,
+    isEditor,
+    running,
+    runExecution,
+    handlePause,
+    handleStop,
+    addStep,
+    removeStep,
+    updateStep,
+    loadTemplate,
+    saveCustom,
+    exportJson,
+    onImportFile,
+    loadSaved,
+    deleteSaved,
+  } = props;
+
+  return (
+    <div className="flex h-full min-h-0 flex-col gap-3 p-3">
+      <div className="text-muted-foreground flex items-center gap-2 text-xs">
+        <ListChecks className="h-4 w-4 shrink-0" />
+        <span>{t("aiChat.workflow.subtitle")}</span>
+      </div>
+
+      {!isTauriDesktop() && (
+        <p className="text-destructive text-xs">{t("aiChat.workflow.desktopOnly")}</p>
+      )}
+
+      <ScrollArea className="min-h-0 flex-1 pr-2">
+        <div className="flex flex-col gap-3 pb-2">
+          <WorkflowPanelMetaSection
+            t={t}
+            draft={draft}
+            setDraft={setDraft}
+            definitions={definitions}
+            selectedSavedId={selectedSavedId}
+            importInputRef={importInputRef}
+            running={running}
+            loadTemplate={loadTemplate}
+            saveCustom={saveCustom}
+            exportJson={exportJson}
+            onImportFile={onImportFile}
+            loadSaved={loadSaved}
+            deleteSaved={deleteSaved}
+          />
+          <WorkflowPanelStepsAndProgress
+            t={t}
+            draft={draft}
+            running={running}
+            progress={progress}
+            activeRunSteps={activeRunSteps}
+            addStep={addStep}
+            removeStep={removeStep}
+            updateStep={updateStep}
+          />
+        </div>
+      </ScrollArea>
+
+      <div className="border-border flex flex-wrap gap-2 border-t pt-2">
+        <Button
+          type="button"
+          size="sm"
+          className="h-8 text-xs"
+          disabled={running || !isEditor}
+          onClick={() => void runExecution("fresh")}
+        >
+          <Play className="mr-1 h-3 w-3" />
+          {t("aiChat.workflow.run")}
+        </Button>
+        <Button
+          type="button"
+          variant="secondary"
+          size="sm"
+          className="h-8 text-xs"
+          disabled={!running}
+          onClick={handlePause}
+        >
+          <Pause className="mr-1 h-3 w-3" />
+          {t("aiChat.workflow.pause")}
+        </Button>
+        <Button
+          type="button"
+          variant="secondary"
+          size="sm"
+          className="h-8 text-xs"
+          disabled={running || !pausedState}
+          onClick={() => void runExecution("resume")}
+        >
+          {t("aiChat.workflow.resume")}
+        </Button>
+        <Button
+          type="button"
+          variant="destructive"
+          size="sm"
+          className="h-8 text-xs"
+          disabled={!running}
+          onClick={handleStop}
+        >
+          <Square className="mr-1 h-3 w-3" />
+          {t("aiChat.workflow.stop")}
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/ai-chat/WorkflowPanelMetaSection.tsx b/src/components/ai-chat/WorkflowPanelMetaSection.tsx
new file mode 100644
index 00000000..6cdaca00
--- /dev/null
+++ b/src/components/ai-chat/WorkflowPanelMetaSection.tsx
@@ -0,0 +1,166 @@
+/**
+ * Workflow name, templates, saved definitions, and import/export (Issue #462).
+ * ワークフロー名・テンプレート・保存定義・インポート/エクスポート（Issue #462）。
+ */
+
+import {
+  Button,
+  Input,
+  Label,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@zedi/ui";
+import { Download, Trash2, Upload } from "lucide-react";
+import {
+  WORKFLOW_TEMPLATE_IDS,
+  WORKFLOW_TEMPLATE_NAME_KEYS,
+  type WorkflowTemplateId,
+} from "@/lib/workflow/templates";
+import type { WorkflowPanelFormProps } from "./workflowPanelTypes";
+
+type Props = Pick<
+  WorkflowPanelFormProps,
+  | "t"
+  | "draft"
+  | "setDraft"
+  | "definitions"
+  | "selectedSavedId"
+  | "importInputRef"
+  | "running"
+  | "loadTemplate"
+  | "saveCustom"
+  | "exportJson"
+  | "onImportFile"
+  | "loadSaved"
+  | "deleteSaved"
+>;
+
+/**
+ * Name field, template selector, saved workflow picker, and JSON import/export.
+ * 名前・テンプレート・保存済み選択・JSON インポート/エクスポート。
+ */
+export function WorkflowPanelMetaSection(props: Props) {
+  const {
+    t,
+    draft,
+    setDraft,
+    definitions,
+    selectedSavedId,
+    importInputRef,
+    running,
+    loadTemplate,
+    saveCustom,
+    exportJson,
+    onImportFile,
+    loadSaved,
+    deleteSaved,
+  } = props;
+
+  return (
+    <>
+      <div className="grid gap-2">
+        <Label className="text-xs">{t("aiChat.workflow.workflowName")}</Label>
+        <Input
+          value={draft.name}
+          onChange={(e) => setDraft((d) => ({ ...d, name: e.target.value, updatedAt: Date.now() }))}
+          placeholder={t("aiChat.workflow.workflowNamePlaceholder")}
+          disabled={running}
+        />
+      </div>
+
+      <div className="grid gap-2">
+        <Label className="text-xs">{t("aiChat.workflow.template")}</Label>
+        <Select disabled={running} onValueChange={(v) => loadTemplate(v as WorkflowTemplateId)}>
+          <SelectTrigger className="h-8 text-xs">
+            <SelectValue placeholder={t("aiChat.workflow.templatePlaceholder")} />
+          </SelectTrigger>
+          <SelectContent>
+            {WORKFLOW_TEMPLATE_IDS.map((id) => (
+              <SelectItem key={id} value={id} className="text-xs">
+                {t(WORKFLOW_TEMPLATE_NAME_KEYS[id])}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+
+      <div className="grid gap-2">
+        <Label className="text-xs">{t("aiChat.workflow.savedWorkflows")}</Label>
+        <div className="flex gap-2">
+          <Select
+            disabled={running}
+            value={selectedSavedId || undefined}
+            onValueChange={(v) => loadSaved(v)}
+          >
+            <SelectTrigger className="h-8 flex-1 text-xs">
+              <SelectValue placeholder={t("aiChat.workflow.pickSaved")} />
+            </SelectTrigger>
+            <SelectContent>
+              {definitions.map((d) => (
+                <SelectItem key={d.id} value={d.id} className="text-xs">
+                  {d.name}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+          <Button
+            type="button"
+            variant="outline"
+            size="icon"
+            className="h-8 w-8 shrink-0"
+            disabled={!selectedSavedId || running}
+            onClick={deleteSaved}
+            title={t("aiChat.workflow.deleteSaved")}
+          >
+            <Trash2 className="h-3.5 w-3.5" />
+          </Button>
+        </div>
+      </div>
+
+      <div className="flex flex-wrap gap-2">
+        <Button
+          type="button"
+          variant="secondary"
+          size="sm"
+          className="h-8 text-xs"
+          disabled={running}
+          onClick={saveCustom}
+        >
+          {t("aiChat.workflow.save")}
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="h-8 text-xs"
+          disabled={running}
+          onClick={exportJson}
+        >
+          <Download className="mr-1 h-3 w-3" />
+          {t("aiChat.workflow.export")}
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="h-8 text-xs"
+          disabled={running}
+          onClick={() => importInputRef.current?.click()}
+        >
+          <Upload className="mr-1 h-3 w-3" />
+          {t("aiChat.workflow.import")}
+        </Button>
+        <input
+          ref={importInputRef}
+          type="file"
+          accept="application/json"
+          className="hidden"
+          onChange={onImportFile}
+        />
+      </div>
+    </>
+  );
+}
diff --git a/src/components/ai-chat/WorkflowPanelStepsAndProgress.tsx b/src/components/ai-chat/WorkflowPanelStepsAndProgress.tsx
new file mode 100644
index 00000000..a2c0e4a1
--- /dev/null
+++ b/src/components/ai-chat/WorkflowPanelStepsAndProgress.tsx
@@ -0,0 +1,110 @@
+/**
+ * Step editor list and run progress summary (Issue #462).
+ * ステップ編集リストと実行進捗サマリー（Issue #462）。
+ */
+
+import { Button, Input, Label } from "@zedi/ui";
+import { Plus, Trash2 } from "lucide-react";
+import type { WorkflowPanelFormProps } from "./workflowPanelTypes";
+
+type Props = Pick<
+  WorkflowPanelFormProps,
+  | "t"
+  | "draft"
+  | "running"
+  | "progress"
+  | "activeRunSteps"
+  | "addStep"
+  | "removeStep"
+  | "updateStep"
+>;
+
+/**
+ * Editable steps and optional streaming progress block.
+ * 編集可能なステップとストリーミング進捗ブロック。
+ */
+export function WorkflowPanelStepsAndProgress(props: Props) {
+  const { t, draft, running, progress, activeRunSteps, addStep, removeStep, updateStep } = props;
+
+  return (
+    <>
+      <div className="border-border space-y-2 border-t pt-2">
+        <div className="flex items-center justify-between">
+          <Label className="text-xs">{t("aiChat.workflow.steps")}</Label>
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="h-7 text-xs"
+            disabled={running}
+            onClick={addStep}
+          >
+            <Plus className="mr-1 h-3 w-3" />
+            {t("aiChat.workflow.addStep")}
+          </Button>
+        </div>
+
+        {draft.steps.map((step, index) => (
+          <div key={step.id} className="bg-muted/40 space-y-2 rounded-md border p-2">
+            <div className="flex items-center justify-between gap-2">
+              <span className="text-muted-foreground text-xs font-medium">
+                {t("aiChat.workflow.stepLabel", { n: index + 1 })}
+              </span>
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                className="h-7 w-7"
+                disabled={running || draft.steps.length <= 1}
+                onClick={() => removeStep(index)}
+              >
+                <Trash2 className="h-3 w-3" />
+              </Button>
+            </div>
+            <Input
+              className="h-8 text-xs"
+              value={step.title}
+              placeholder={t("aiChat.workflow.stepTitlePlaceholder")}
+              disabled={running}
+              onChange={(e) => updateStep(index, { title: e.target.value })}
+            />
+            <textarea
+              className="border-input bg-background focus-visible:ring-ring min-h-[72px] w-full rounded-md border px-2 py-1.5 text-xs focus-visible:ring-2 focus-visible:outline-none"
+              value={step.instruction}
+              placeholder={t("aiChat.workflow.stepInstructionPlaceholder")}
+              disabled={running}
+              onChange={(e) => updateStep(index, { instruction: e.target.value })}
+            />
+          </div>
+        ))}
+      </div>
+
+      {progress && (
+        <div className="bg-muted/30 rounded-md border p-2 text-xs">
+          <div className="text-muted-foreground mb-1 font-medium">
+            {t("aiChat.workflow.progressTitle")}
+          </div>
+          <ul className="space-y-1">
+            {(activeRunSteps ?? draft.steps).map((s, i) => {
+              const st = progress.stepStatuses[i] ?? "pending";
+              const mark =
+                st === "done" ? "☑" : st === "running" ? "🔄" : st === "error" ? "⚠️" : "⬜";
+              return (
+                <li key={s.id} className="flex flex-col gap-0.5">
+                  <span>
+                    {mark} {s.title || t("aiChat.workflow.unnamedStep", { n: i + 1 })}
+                  </span>
+                  {st === "running" && progress.currentStepStreaming ? (
+                    <span className="text-muted-foreground line-clamp-3 pl-4">
+                      {progress.currentStepStreaming}
+                    </span>
+                  ) : null}
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      )}
+    </>
+  );
+}
diff --git a/src/components/ai-chat/workflowPanelTypes.ts b/src/components/ai-chat/workflowPanelTypes.ts
new file mode 100644
index 00000000..ab94c2fc
--- /dev/null
+++ b/src/components/ai-chat/workflowPanelTypes.ts
@@ -0,0 +1,12 @@
+/**
+ * Shared props type for workflow panel subcomponents (Issue #462).
+ * ワークフローパネル子コンポーネント共通の props 型（Issue #462）。
+ */
+
+/**
+ * Props mirror {@link useWorkflowPanelLogic} return shape.
+ * {@link useWorkflowPanelLogic} の戻り値と同形。
+ */
+export type WorkflowPanelFormProps = ReturnType<
+  typeof import("@/hooks/useWorkflowPanelLogic").useWorkflowPanelLogic
+>;
diff --git a/src/hooks/useWorkflowDraft.ts b/src/hooks/useWorkflowDraft.ts
new file mode 100644
index 00000000..b1dc865f
--- /dev/null
+++ b/src/hooks/useWorkflowDraft.ts
@@ -0,0 +1,163 @@
+/**
+ * Draft editing and local persistence for workflow definitions (Issue #462).
+ * ワークフロー定義のドラフト編集とローカル永続化（Issue #462）。
+ */
+
+import { useCallback, useRef, useState, type ChangeEvent } from "react";
+import { useTranslation } from "react-i18next";
+import { useToast } from "@zedi/ui";
+import { newWorkflowId } from "@/lib/workflow/newWorkflowId";
+import { parseWorkflowDefinitionImport } from "@/lib/workflow/parseWorkflowDefinitionImport";
+import type { WorkflowDefinition, WorkflowStepDefinition } from "@/lib/workflow/types";
+import {
+  WORKFLOW_TEMPLATE_NAME_KEYS,
+  instantiateWorkflowTemplate,
+  type WorkflowTemplateId,
+} from "@/lib/workflow/templates";
+import { useWorkflowDefinitionsStore } from "@/stores/workflowDefinitionsStore";
+
+function emptyDraft(): WorkflowDefinition {
+  const now = Date.now();
+  return {
+    id: newWorkflowId(),
+    name: "",
+    steps: [{ id: newWorkflowId(), title: "", instruction: "" }],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * Draft state, templates, import/export, and saved-definition list.
+ * ドラフト状態・テンプレート・インポート/エクスポート・保存一覧。
+ */
+export function useWorkflowDraft() {
+  const { t } = useTranslation();
+  const { toast } = useToast();
+
+  const definitions = useWorkflowDefinitionsStore((s) => s.definitions);
+  const upsertDefinition = useWorkflowDefinitionsStore((s) => s.upsertDefinition);
+  const removeDefinition = useWorkflowDefinitionsStore((s) => s.removeDefinition);
+
+  const [draft, setDraft] = useState<WorkflowDefinition>(() => emptyDraft());
+  const [selectedSavedId, setSelectedSavedId] = useState<string | "">("");
+  const importInputRef = useRef<HTMLInputElement | null>(null);
+
+  const addStep = useCallback(() => {
+    setDraft((d) => ({
+      ...d,
+      steps: [...d.steps, { id: newWorkflowId(), title: "", instruction: "" }],
+      updatedAt: Date.now(),
+    }));
+  }, []);
+
+  const removeStep = useCallback((index: number) => {
+    setDraft((d) => ({
+      ...d,
+      steps: d.steps.filter((_, i) => i !== index),
+      updatedAt: Date.now(),
+    }));
+  }, []);
+
+  const updateStep = useCallback((index: number, patch: Partial<WorkflowStepDefinition>) => {
+    setDraft((d) => ({
+      ...d,
+      steps: d.steps.map((s, i) => (i === index ? { ...s, ...patch } : s)),
+      updatedAt: Date.now(),
+    }));
+  }, []);
+
+  const loadTemplate = useCallback(
+    (tid: WorkflowTemplateId) => {
+      const name = t(WORKFLOW_TEMPLATE_NAME_KEYS[tid]);
+      setDraft(instantiateWorkflowTemplate(tid, name));
+      setSelectedSavedId("");
+    },
+    [t],
+  );
+
+  const saveCustom = useCallback(() => {
+    if (!draft.name.trim()) {
+      toast({ title: t("aiChat.workflow.nameRequired"), variant: "destructive" });
+      return;
+    }
+    const now = Date.now();
+    upsertDefinition({ ...draft, updatedAt: now });
+    toast({ title: t("aiChat.workflow.saved") });
+  }, [draft, t, toast, upsertDefinition]);
+
+  const exportJson = useCallback(() => {
+    const blob = new Blob([JSON.stringify(draft, null, 2)], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${draft.name.trim() || "workflow"}.json`;
+    a.click();
+    URL.revokeObjectURL(url);
+  }, [draft]);
+
+  const onImportFile = useCallback(
+    (e: ChangeEvent<HTMLInputElement>) => {
+      const file = e.target.files?.[0];
+      e.target.value = "";
+      if (!file) return;
+      const reader = new FileReader();
+      reader.onload = () => {
+        try {
+          const parsed = JSON.parse(String(reader.result)) as unknown;
+          const { name, steps } = parseWorkflowDefinitionImport(parsed);
+          const now = Date.now();
+          setDraft({
+            id: newWorkflowId(),
+            name,
+            steps,
+            createdAt: now,
+            updatedAt: now,
+          });
+          setSelectedSavedId("");
+          toast({ title: t("aiChat.workflow.imported") });
+        } catch {
+          toast({ title: t("aiChat.workflow.importFailed"), variant: "destructive" });
+        }
+      };
+      reader.readAsText(file);
+    },
+    [t, toast],
+  );
+
+  const loadSaved = useCallback(
+    (id: string) => {
+      const found = definitions.find((d) => d.id === id);
+      if (found) {
+        setDraft({ ...found });
+        setSelectedSavedId(id);
+      }
+    },
+    [definitions],
+  );
+
+  const deleteSaved = useCallback(() => {
+    if (!selectedSavedId) return;
+    removeDefinition(selectedSavedId);
+    setSelectedSavedId("");
+    toast({ title: t("aiChat.workflow.deleted") });
+  }, [removeDefinition, selectedSavedId, t, toast]);
+
+  return {
+    t,
+    draft,
+    setDraft,
+    definitions,
+    selectedSavedId,
+    importInputRef,
+    addStep,
+    removeStep,
+    updateStep,
+    loadTemplate,
+    saveCustom,
+    exportJson,
+    onImportFile,
+    loadSaved,
+    deleteSaved,
+  };
+}
diff --git a/src/hooks/useWorkflowPanelLogic.ts b/src/hooks/useWorkflowPanelLogic.ts
new file mode 100644
index 00000000..1b7cc1cc
--- /dev/null
+++ b/src/hooks/useWorkflowPanelLogic.ts
@@ -0,0 +1,21 @@
+/**
+ * Composes draft editing and workflow execution for the AI chat workflow panel (Issue #462).
+ * AI チャットのワークフローパネル向けにドラフト編集と実行を合成する（Issue #462）。
+ */
+
+import { useWorkflowDraft } from "./useWorkflowDraft";
+import { useWorkflowRunSession } from "./useWorkflowRunSession";
+
+/**
+ * Combined state and actions for {@link AIChatWorkflowPanel}.
+ * {@link AIChatWorkflowPanel} 向けの状態とアクションをまとめる。
+ */
+export function useWorkflowPanelLogic() {
+  const draftApi = useWorkflowDraft();
+  const runApi = useWorkflowRunSession(draftApi.draft);
+
+  return {
+    ...draftApi,
+    ...runApi,
+  };
+}
diff --git a/src/hooks/useWorkflowRunSession.ts b/src/hooks/useWorkflowRunSession.ts
new file mode 100644
index 00000000..43628771
--- /dev/null
+++ b/src/hooks/useWorkflowRunSession.ts
@@ -0,0 +1,180 @@
+/**
+ * Claude Code multi-step workflow execution for the workflow panel (Issue #462).
+ * ワークフローパネル向け Claude Code マルチステップ実行（Issue #462）。
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { useToast } from "@zedi/ui";
+import { useAIChatContext } from "@/contexts/AIChatContext";
+import { isTauriDesktop } from "@/lib/platform";
+import { runWorkflowExecution } from "@/lib/workflow/runWorkflowExecution";
+import type {
+  WorkflowDefinition,
+  WorkflowRunProgress,
+  WorkflowStepDefinition,
+} from "@/lib/workflow/types";
+import { applyWorkflowRunOutcome } from "./workflowRunOutcomeHandlers";
+
+/**
+ * Runs, pauses, and resumes workflows against the current note context.
+ * 現在のノート文脈に対してワークフローを実行・一時停止・再開する。
+ */
+export function useWorkflowRunSession(draft: WorkflowDefinition) {
+  const { t } = useTranslation();
+  const { toast } = useToast();
+  const { pageContext, contentAppendHandlerRef } = useAIChatContext();
+
+  const [progress, setProgress] = useState<WorkflowRunProgress | null>(null);
+  const [activeRunSteps, setActiveRunSteps] = useState<WorkflowStepDefinition[] | null>(null);
+  const [pausedState, setPausedState] = useState<{
+    pausedAtStepIndex: number;
+    stepOutputs: string[];
+    partialForStep: string;
+  } | null>(null);
+
+  const workflowAbortRef = useRef<AbortController | null>(null);
+  const currentStepAbortRef = useRef<AbortController | null>(null);
+  const baseSnapshotRef = useRef<string>("");
+
+  const isEditor = pageContext?.type === "editor";
+  const cwd = pageContext?.claudeWorkspaceRoot;
+  const pageExcerpt =
+    pageContext?.pageFullContent?.slice(0, 12_000) ??
+    pageContext?.pageContent?.slice(0, 12_000) ??
+    "";
+
+  useEffect(() => {
+    return () => {
+      workflowAbortRef.current?.abort();
+      currentStepAbortRef.current?.abort();
+    };
+  }, []);
+
+  const applyNoteContent = useCallback(
+    (fullMarkdown: string) => {
+      const fn = contentAppendHandlerRef.current;
+      if (fn) fn(fullMarkdown);
+    },
+    [contentAppendHandlerRef],
+  );
+
+  const runExecution = useCallback(
+    async (mode: "fresh" | "resume") => {
+      if (!isTauriDesktop()) {
+        toast({ title: t("aiChat.workflow.desktopOnly"), variant: "destructive" });
+        return;
+      }
+      if (!isEditor) {
+        toast({ title: t("aiChat.workflow.editorRequired"), variant: "destructive" });
+        return;
+      }
+      if (mode === "resume" && !pausedState) {
+        toast({ title: t("aiChat.workflow.nothingToResume"), variant: "destructive" });
+        return;
+      }
+      if (!draft.name.trim()) {
+        toast({ title: t("aiChat.workflow.nameRequired"), variant: "destructive" });
+        return;
+      }
+      const validSteps = draft.steps.filter((s) => s.title.trim() && s.instruction.trim());
+      if (validSteps.length === 0) {
+        toast({ title: t("aiChat.workflow.stepsRequired"), variant: "destructive" });
+        return;
+      }
+
+      const def: WorkflowDefinition = {
+        ...draft,
+        steps: validSteps,
+        updatedAt: Date.now(),
+      };
+
+      workflowAbortRef.current = new AbortController();
+      baseSnapshotRef.current = pageContext?.pageFullContent ?? "";
+
+      const startIndex = mode === "resume" && pausedState ? pausedState.pausedAtStepIndex : 0;
+      const initialOutputs = mode === "resume" && pausedState ? [...pausedState.stepOutputs] : [];
+      const resumePartial =
+        mode === "resume" && pausedState ? pausedState.partialForStep : undefined;
+
+      if (mode === "fresh") {
+        setPausedState(null);
+      }
+
+      setActiveRunSteps(validSteps);
+
+      setProgress({
+        phase: "running",
+        currentStepIndex: startIndex,
+        stepStatuses: validSteps.map((_, i) =>
+          i < startIndex ? "done" : i === startIndex ? "running" : "pending",
+        ),
+        stepOutputs: initialOutputs.length
+          ? initialOutputs
+          : Array.from({ length: validSteps.length }, () => ""),
+        currentStepStreaming: resumePartial ?? "",
+      });
+
+      const result = await runWorkflowExecution({
+        definition: def,
+        cwd,
+        pageExcerpt,
+        workflowSignal: workflowAbortRef.current.signal,
+        createStepAbort: () => {
+          const c = new AbortController();
+          currentStepAbortRef.current = c;
+          return c;
+        },
+        startStepIndex: startIndex,
+        stepOutputs: initialOutputs.length
+          ? initialOutputs
+          : Array.from({ length: validSteps.length }, () => ""),
+        resumePartialForCurrentStep: resumePartial,
+        onProgress: setProgress,
+        onNoteMarkdown: applyNoteContent,
+        baseContentBeforeWorkflow: baseSnapshotRef.current,
+      });
+
+      applyWorkflowRunOutcome(result, validSteps, {
+        t,
+        toast,
+        setPausedState,
+        setActiveRunSteps,
+        setProgress,
+      });
+    },
+    [
+      applyNoteContent,
+      cwd,
+      draft,
+      isEditor,
+      pageContext?.pageFullContent,
+      pageExcerpt,
+      pausedState,
+      t,
+      toast,
+    ],
+  );
+
+  const handlePause = useCallback(() => {
+    currentStepAbortRef.current?.abort();
+  }, []);
+
+  const handleStop = useCallback(() => {
+    workflowAbortRef.current?.abort();
+    currentStepAbortRef.current?.abort();
+  }, []);
+
+  const running = progress?.phase === "running";
+
+  return {
+    progress,
+    activeRunSteps,
+    pausedState,
+    isEditor,
+    running,
+    runExecution,
+    handlePause,
+    handleStop,
+  };
+}
diff --git a/src/hooks/workflowRunOutcomeHandlers.ts b/src/hooks/workflowRunOutcomeHandlers.ts
new file mode 100644
index 00000000..b1c2ca53
--- /dev/null
+++ b/src/hooks/workflowRunOutcomeHandlers.ts
@@ -0,0 +1,71 @@
+/**
+ * Maps {@link WorkflowExecutionOutcome} to UI state updates (Issue #462).
+ * {@link WorkflowExecutionOutcome} を UI 状態更新へ写す（Issue #462）。
+ */
+
+import type { Dispatch, SetStateAction } from "react";
+import type { TFunction } from "i18next";
+import type { WorkflowExecutionOutcome } from "@/lib/workflow/runWorkflowExecution";
+import type { WorkflowRunProgress, WorkflowStepDefinition } from "@/lib/workflow/types";
+
+type ToastArg = { title: string; variant?: "destructive" };
+type ToastFn = (props: ToastArg) => void;
+
+type PausedState = {
+  pausedAtStepIndex: number;
+  stepOutputs: string[];
+  partialForStep: string;
+};
+
+/**
+ * Applies execution outcome: toasts and state setters for pause / complete / error.
+ * 実行結果を適用する（トーストと pause / 完了 / エラー用の setter）。
+ */
+export function applyWorkflowRunOutcome(
+  result: WorkflowExecutionOutcome,
+  validSteps: WorkflowStepDefinition[],
+  ctx: {
+    t: TFunction;
+    toast: ToastFn;
+    setPausedState: Dispatch<SetStateAction<PausedState | null>>;
+    setActiveRunSteps: Dispatch<SetStateAction<WorkflowStepDefinition[] | null>>;
+    setProgress: Dispatch<SetStateAction<WorkflowRunProgress | null>>;
+  },
+): void {
+  const { t, toast, setPausedState, setActiveRunSteps, setProgress } = ctx;
+
+  switch (result.outcome) {
+    case "completed":
+      setPausedState(null);
+      setActiveRunSteps(null);
+      setProgress((p) => (p ? { ...p, phase: "completed" } : null));
+      toast({ title: t("aiChat.workflow.completed") });
+      return;
+    case "paused":
+      setActiveRunSteps(validSteps);
+      setPausedState({
+        pausedAtStepIndex: result.pausedAtStepIndex,
+        stepOutputs: result.stepOutputs,
+        partialForStep: result.partialForStep,
+      });
+      setProgress((p) => (p ? { ...p, phase: "paused" } : null));
+      toast({ title: t("aiChat.workflow.paused") });
+      return;
+    case "stopped":
+      setActiveRunSteps(null);
+      setProgress((p) => (p ? { ...p, phase: "aborted" } : null));
+      toast({ title: t("aiChat.workflow.stopped") });
+      return;
+    case "error":
+      setActiveRunSteps(null);
+      toast({
+        title: t("aiChat.workflow.error", { message: result.error }),
+        variant: "destructive",
+      });
+      return;
+    default: {
+      const _exhaustive: never = result;
+      throw new Error(`Unhandled outcome: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
diff --git a/src/i18n/locales/en/aiChat.json b/src/i18n/locales/en/aiChat.json
index 031525a6..435cb9c1 100644
--- a/src/i18n/locales/en/aiChat.json
+++ b/src/i18n/locales/en/aiChat.json
@@ -72,8 +72,52 @@
   "viewTabs": {
     "chat": "Chat",
     "branch": "Branches",
+    "workflow": "Workflow",
     "noBranches": "No branches in this conversation"
   },
+  "workflow": {
+    "subtitle": "Multi-step Claude Code runs with live note updates (desktop).",
+    "desktopOnly": "Workflows require the Zedi desktop app with Claude Code.",
+    "editorRequired": "Open a note page to write results into the editor.",
+    "nameRequired": "Enter a workflow name.",
+    "stepsRequired": "Add at least one step with a title and instructions.",
+    "nothingToResume": "Nothing to resume. Run a workflow first, then pause.",
+    "workflowName": "Workflow name",
+    "workflowNamePlaceholder": "e.g. New API endpoint design",
+    "template": "Template",
+    "templatePlaceholder": "Load a template…",
+    "templates": {
+      "codeInvestigateDesign": "Code investigation → design memo",
+      "testAnalyzeImprove": "Run tests → analyze → suggest improvements",
+      "repoAnalyzeDocs": "Repository analysis → documentation draft",
+      "webResearchNote": "Web research → organize → draft note"
+    },
+    "savedWorkflows": "Saved workflows",
+    "pickSaved": "Load saved…",
+    "deleteSaved": "Delete saved workflow",
+    "save": "Save",
+    "export": "Export",
+    "import": "Import",
+    "steps": "Steps",
+    "addStep": "Add step",
+    "stepLabel": "Step {{n}}",
+    "stepTitlePlaceholder": "Step title",
+    "stepInstructionPlaceholder": "What Claude Code should do in this step",
+    "unnamedStep": "Step {{n}}",
+    "progressTitle": "Progress",
+    "run": "Run",
+    "pause": "Pause",
+    "resume": "Resume",
+    "stop": "Stop",
+    "saved": "Workflow saved",
+    "deleted": "Workflow removed",
+    "imported": "Workflow imported",
+    "importFailed": "Could not import workflow JSON",
+    "completed": "Workflow completed",
+    "paused": "Workflow paused",
+    "stopped": "Workflow stopped",
+    "error": "Workflow error: {{message}}"
+  },
   "branchTree": {
     "goToBranch": "Go to this branch",
     "branchFromHere": "Branch from here",
diff --git a/src/i18n/locales/ja/aiChat.json b/src/i18n/locales/ja/aiChat.json
index 701283e4..f85f0623 100644
--- a/src/i18n/locales/ja/aiChat.json
+++ b/src/i18n/locales/ja/aiChat.json
@@ -72,8 +72,52 @@
   "viewTabs": {
     "chat": "チャット",
     "branch": "ブランチ",
+    "workflow": "ワークフロー",
     "noBranches": "この会話にはブランチがありません"
   },
+  "workflow": {
+    "subtitle": "Claude Code で複数ステップを順に実行し、ノートへリアルタイム反映（デスクトップ）。",
+    "desktopOnly": "ワークフローは Claude Code 利用可能な Zedi デスクトップアプリが必要です。",
+    "editorRequired": "結果を書き込むにはノートページを開いてください。",
+    "nameRequired": "ワークフロー名を入力してください。",
+    "stepsRequired": "タイトルと指示があるステップを1つ以上追加してください。",
+    "nothingToResume": "再開できる実行がありません。実行して一時停止してください。",
+    "workflowName": "ワークフロー名",
+    "workflowNamePlaceholder": "例: 新 API エンドポイント設計",
+    "template": "テンプレート",
+    "templatePlaceholder": "テンプレートを読み込む…",
+    "templates": {
+      "codeInvestigateDesign": "コード調査→設計メモ作成",
+      "testAnalyzeImprove": "テスト実行→結果分析→改善提案",
+      "repoAnalyzeDocs": "リポジトリ分析→ドキュメント生成",
+      "webResearchNote": "Web 調査→情報整理→ノート作成"
+    },
+    "savedWorkflows": "保存済みワークフロー",
+    "pickSaved": "保存を読み込む…",
+    "deleteSaved": "保存を削除",
+    "save": "保存",
+    "export": "エクスポート",
+    "import": "インポート",
+    "steps": "ステップ",
+    "addStep": "ステップを追加",
+    "stepLabel": "ステップ {{n}}",
+    "stepTitlePlaceholder": "ステップのタイトル",
+    "stepInstructionPlaceholder": "このステップで Claude Code にやってほしいこと",
+    "unnamedStep": "ステップ {{n}}",
+    "progressTitle": "進捗",
+    "run": "実行",
+    "pause": "一時停止",
+    "resume": "再開",
+    "stop": "中断",
+    "saved": "ワークフローを保存しました",
+    "deleted": "ワークフローを削除しました",
+    "imported": "ワークフローをインポートしました",
+    "importFailed": "ワークフロー JSON を読み込めませんでした",
+    "completed": "ワークフローが完了しました",
+    "paused": "ワークフローを一時停止しました",
+    "stopped": "ワークフローを中断しました",
+    "error": "ワークフローエラー: {{message}}"
+  },
   "branchTree": {
     "goToBranch": "このブランチに移動",
     "branchFromHere": "ここから分岐",
diff --git a/src/lib/claudeCode/runQueryToCompletion.test.ts b/src/lib/claudeCode/runQueryToCompletion.test.ts
index ba6116a4..ccf96f0d 100644
--- a/src/lib/claudeCode/runQueryToCompletion.test.ts
+++ b/src/lib/claudeCode/runQueryToCompletion.test.ts
@@ -30,6 +30,8 @@ vi.mock("./bridge", () => ({
     onError = cb;
     return Promise.resolve(() => {});
   }),
+  onClaudeToolUseStart: vi.fn().mockResolvedValue(() => {}),
+  onClaudeToolUseComplete: vi.fn().mockResolvedValue(() => {}),
 }));
 
 import { claudeQuery } from "./bridge";
diff --git a/src/lib/claudeCode/runQueryToCompletion.ts b/src/lib/claudeCode/runQueryToCompletion.ts
index b993a42e..70a3d19f 100644
--- a/src/lib/claudeCode/runQueryToCompletion.ts
+++ b/src/lib/claudeCode/runQueryToCompletion.ts
@@ -5,58 +5,14 @@
  * Used by executable code blocks and similar flows that need a full result string.
  * 実行可能コードブロックなど、完全な結果文字列が必要なフローで使用する。
  *
- * Events that arrive after listeners are registered but before `claudeQuery` resolves
- * its request id are buffered and replayed for the matching id (avoids losing early chunks).
- * リスナー登録後〜`claudeQuery` が ID を返すまでに届くイベントはバッファし、同一 ID で再生する（早期チャンク欠落を防ぐ）。
+ * Implemented via {@link streamClaudeQuery} without incremental callbacks.
+ * {@link streamClaudeQuery} をチャンクコールバックなしで呼び出す実装。
  */
 
-import { isTauriDesktop } from "@/lib/platform";
-import {
-  claudeAbort,
-  claudeQuery,
-  onClaudeError,
-  onClaudeStreamChunk,
-  onClaudeStreamComplete,
-} from "./bridge";
 import type { ClaudeQueryOptions } from "./bridge";
+import { streamClaudeQuery, type ClaudeQueryCompletionResult } from "./streamClaudeQuery";
 
-/** Outcome of {@link runClaudeQueryToCompletion}. / {@link runClaudeQueryToCompletion} の結果。 */
-export type ClaudeQueryCompletionResult =
-  | { ok: true; content: string }
-  | { ok: false; error: string };
-
-type PreRequestEvent =
-  | { type: "chunk"; id: string; content: string }
-  | { type: "complete"; id: string; result?: { content: string } }
-  | { type: "error"; id: string; error: string };
-
-/**
- * Applies buffered sidecar events that arrived before `requestId` was known.
- * `requestId` 確定前に届いた sidecar イベントを適用する。
- */
-function applyPreRequestBuffer(
-  requestId: string,
-  buffer: PreRequestEvent[],
-  state: {
-    aggregated: string;
-    finished: boolean;
-    errorMessage: string | null;
-  },
-): void {
-  for (const ev of buffer) {
-    if (ev.id !== requestId) continue;
-    if (ev.type === "chunk") {
-      state.aggregated += ev.content;
-    } else if (ev.type === "complete") {
-      state.aggregated = ev.result?.content ?? state.aggregated;
-      state.finished = true;
-    } else if (ev.type === "error") {
-      state.errorMessage = ev.error;
-      state.finished = true;
-    }
-  }
-  buffer.length = 0;
-}
+export type { ClaudeQueryCompletionResult } from "./streamClaudeQuery";
 
 /**
  * Sends `prompt` via the sidecar and resolves when the stream completes or errors.
@@ -67,111 +23,5 @@ export async function runClaudeQueryToCompletion(
   options?: ClaudeQueryOptions,
   signal?: AbortSignal,
 ): Promise<ClaudeQueryCompletionResult> {
-  if (!isTauriDesktop()) {
-    return { ok: false, error: "Claude Code is only available in the desktop app." };
-  }
-
-  let requestId: string | null = null;
-  let resolveWait: (() => void) | null = null;
-  /** Removes the pending `abort` listener when the wait ends without firing abort. */
-  let pendingAbortCleanup: (() => void) | null = null;
-  const wake = (): void => {
-    pendingAbortCleanup?.();
-    pendingAbortCleanup = null;
-    resolveWait?.();
-    resolveWait = null;
-  };
-
-  let aggregated = "";
-  let finished = false;
-  let errorMessage: string | null = null;
-
-  const preRequestBuffer: PreRequestEvent[] = [];
-
-  const unlistenChunk = await onClaudeStreamChunk((payload) => {
-    if (finished) return;
-    if (requestId && payload.id === requestId) {
-      aggregated += payload.content;
-      wake();
-    } else if (!requestId) {
-      preRequestBuffer.push({ type: "chunk", id: payload.id, content: payload.content });
-    }
-  });
-
-  const unlistenComplete = await onClaudeStreamComplete((payload) => {
-    if (finished) return;
-    if (requestId && payload.id === requestId) {
-      const text = payload.result?.content ?? aggregated;
-      aggregated = text;
-      finished = true;
-      wake();
-    } else if (!requestId) {
-      preRequestBuffer.push({
-        type: "complete",
-        id: payload.id,
-        result: payload.result,
-      });
-    }
-  });
-
-  const unlistenError = await onClaudeError((payload) => {
-    if (finished) return;
-    if (requestId && payload.id === requestId) {
-      errorMessage = payload.error;
-      finished = true;
-      wake();
-    } else if (!requestId) {
-      preRequestBuffer.push({ type: "error", id: payload.id, error: payload.error });
-    }
-  });
-
-  try {
-    requestId = await claudeQuery(prompt, options);
-
-    const merged = { aggregated, finished, errorMessage };
-    applyPreRequestBuffer(requestId, preRequestBuffer, merged);
-    aggregated = merged.aggregated;
-    finished = merged.finished;
-    errorMessage = merged.errorMessage;
-    if (finished) wake();
-
-    while (!finished) {
-      if (signal?.aborted) {
-        if (requestId) await claudeAbort(requestId);
-        return { ok: false, error: "Aborted" };
-      }
-
-      await new Promise<void>((resolve) => {
-        resolveWait = resolve;
-        const onAbort = (): void => {
-          pendingAbortCleanup = null;
-          resolve();
-          resolveWait = null;
-        };
-        pendingAbortCleanup = (): void => {
-          signal?.removeEventListener("abort", onAbort);
-        };
-        signal?.addEventListener("abort", onAbort, { once: true });
-        if (finished || signal?.aborted) {
-          pendingAbortCleanup?.();
-          pendingAbortCleanup = null;
-          resolve();
-          resolveWait = null;
-        }
-      });
-    }
-
-    if (errorMessage) {
-      return { ok: false, error: errorMessage };
-    }
-    return { ok: true, content: aggregated };
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    return { ok: false, error: msg };
-  } finally {
-    unlistenChunk();
-    unlistenComplete();
-    unlistenError();
-    requestId = null;
-  }
+  return streamClaudeQuery(prompt, options, signal, {});
 }
diff --git a/src/lib/claudeCode/streamClaudeQuery.ts b/src/lib/claudeCode/streamClaudeQuery.ts
new file mode 100644
index 00000000..e6c2b681
--- /dev/null
+++ b/src/lib/claudeCode/streamClaudeQuery.ts
@@ -0,0 +1,205 @@
+/**
+ * Streams a Claude Code sidecar query with incremental text callbacks.
+ * Claude Code sidecar のクエリをテキストチャンク単位でコールバックする。
+ *
+ * @see {@link runClaudeQueryToCompletion} — thin wrapper with no chunk handler.
+ */
+
+import { isTauriDesktop } from "@/lib/platform";
+import {
+  claudeAbort,
+  claudeQuery,
+  onClaudeError,
+  onClaudeStreamChunk,
+  onClaudeStreamComplete,
+  onClaudeToolUseComplete,
+  onClaudeToolUseStart,
+} from "./bridge";
+import type { ClaudeQueryOptions } from "./bridge";
+/** Outcome of {@link streamClaudeQuery} / {@link runClaudeQueryToCompletion}. */
+export type ClaudeQueryCompletionResult =
+  | { ok: true; content: string }
+  | { ok: false; error: string };
+
+type PreRequestEvent =
+  | { type: "chunk"; id: string; content: string }
+  | { type: "complete"; id: string; result?: { content: string } }
+  | { type: "error"; id: string; error: string };
+
+/**
+ * Optional callbacks while streaming Claude Code output.
+ * ストリーミング中の任意コールバック。
+ */
+export interface StreamClaudeQueryCallbacks {
+  /** Each text delta from the assistant. / アシスタントからのテキスト差分 */
+  onChunk?: (text: string) => void;
+  /** Tool invocation started (Claude Code). / ツール呼び出し開始 */
+  onToolUseStart?: (toolName: string) => void;
+  /** Tool invocation finished. / ツール呼び出し完了 */
+  onToolUseComplete?: (toolName: string) => void;
+}
+
+/**
+ * Applies buffered sidecar events that arrived before `requestId` was known.
+ * `requestId` 確定前に届いた sidecar イベントを適用する。
+ */
+function applyPreRequestBuffer(
+  requestId: string,
+  buffer: PreRequestEvent[],
+  state: {
+    aggregated: string;
+    finished: boolean;
+    errorMessage: string | null;
+  },
+  onChunk?: (text: string) => void,
+): void {
+  for (const ev of buffer) {
+    if (ev.id !== requestId) continue;
+    if (ev.type === "chunk") {
+      state.aggregated += ev.content;
+      onChunk?.(ev.content);
+    } else if (ev.type === "complete") {
+      state.aggregated = ev.result?.content ?? state.aggregated;
+      state.finished = true;
+    } else if (ev.type === "error") {
+      state.errorMessage = ev.error;
+      state.finished = true;
+    }
+  }
+  buffer.length = 0;
+}
+
+/**
+ * Sends `prompt` via the sidecar; invokes `onChunk` for each text delta; resolves with final text.
+ * `prompt` を sidecar へ送り、テキスト差分ごとに `onChunk` を呼び、最終テキストで解決する。
+ */
+export async function streamClaudeQuery(
+  prompt: string,
+  options: ClaudeQueryOptions | undefined,
+  signal: AbortSignal | undefined,
+  callbacks: StreamClaudeQueryCallbacks,
+): Promise<ClaudeQueryCompletionResult> {
+  if (!isTauriDesktop()) {
+    return { ok: false, error: "Claude Code is only available in the desktop app." };
+  }
+
+  let requestId: string | null = null;
+  let resolveWait: (() => void) | null = null;
+  let pendingAbortCleanup: (() => void) | null = null;
+  const wake = (): void => {
+    pendingAbortCleanup?.();
+    pendingAbortCleanup = null;
+    resolveWait?.();
+    resolveWait = null;
+  };
+
+  let aggregated = "";
+  let finished = false;
+  let errorMessage: string | null = null;
+
+  const preRequestBuffer: PreRequestEvent[] = [];
+
+  const unlistenChunk = await onClaudeStreamChunk((payload) => {
+    if (finished) return;
+    if (requestId && payload.id === requestId) {
+      aggregated += payload.content;
+      callbacks.onChunk?.(payload.content);
+      wake();
+    } else if (!requestId) {
+      preRequestBuffer.push({ type: "chunk", id: payload.id, content: payload.content });
+    }
+  });
+
+  const unlistenComplete = await onClaudeStreamComplete((payload) => {
+    if (finished) return;
+    if (requestId && payload.id === requestId) {
+      const text = payload.result?.content ?? aggregated;
+      aggregated = text;
+      finished = true;
+      wake();
+    } else if (!requestId) {
+      preRequestBuffer.push({
+        type: "complete",
+        id: payload.id,
+        result: payload.result,
+      });
+    }
+  });
+
+  const unlistenError = await onClaudeError((payload) => {
+    if (finished) return;
+    if (requestId && payload.id === requestId) {
+      errorMessage = payload.error;
+      finished = true;
+      wake();
+    } else if (!requestId) {
+      preRequestBuffer.push({ type: "error", id: payload.id, error: payload.error });
+    }
+  });
+
+  const unlistenToolStart = await onClaudeToolUseStart((payload) => {
+    if (finished) return;
+    if (requestId && payload.id === requestId) {
+      callbacks.onToolUseStart?.(payload.toolName);
+    }
+  });
+
+  const unlistenToolComplete = await onClaudeToolUseComplete((payload) => {
+    if (finished) return;
+    if (requestId && payload.id === requestId) {
+      callbacks.onToolUseComplete?.(payload.toolName);
+    }
+  });
+
+  try {
+    requestId = await claudeQuery(prompt, options);
+
+    const merged = { aggregated, finished, errorMessage };
+    applyPreRequestBuffer(requestId, preRequestBuffer, merged, callbacks.onChunk);
+    aggregated = merged.aggregated;
+    finished = merged.finished;
+    errorMessage = merged.errorMessage;
+    if (finished) wake();
+
+    while (!finished) {
+      if (signal?.aborted) {
+        if (requestId) await claudeAbort(requestId);
+        return { ok: false, error: "Aborted" };
+      }
+
+      await new Promise<void>((resolve) => {
+        resolveWait = resolve;
+        const onAbort = (): void => {
+          pendingAbortCleanup = null;
+          resolve();
+          resolveWait = null;
+        };
+        pendingAbortCleanup = (): void => {
+          signal?.removeEventListener("abort", onAbort);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (finished || signal?.aborted) {
+          pendingAbortCleanup?.();
+          pendingAbortCleanup = null;
+          resolve();
+          resolveWait = null;
+        }
+      });
+    }
+
+    if (errorMessage) {
+      return { ok: false, error: errorMessage };
+    }
+    return { ok: true, content: aggregated };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, error: msg };
+  } finally {
+    unlistenChunk();
+    unlistenComplete();
+    unlistenError();
+    unlistenToolStart();
+    unlistenToolComplete();
+    requestId = null;
+  }
+}
diff --git a/src/lib/workflow/buildWorkflowStepPrompt.test.ts b/src/lib/workflow/buildWorkflowStepPrompt.test.ts
new file mode 100644
index 00000000..86bd2bcb
--- /dev/null
+++ b/src/lib/workflow/buildWorkflowStepPrompt.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { buildWorkflowStepPrompt, defaultWorkflowStepMaxTurns } from "./buildWorkflowStepPrompt";
+
+describe("buildWorkflowStepPrompt", () => {
+  it("includes step meta, instruction, and prior outputs", () => {
+    const text = buildWorkflowStepPrompt({
+      workflowName: "W",
+      step: { id: "s2", title: "Design", instruction: "Propose schema." },
+      stepIndex: 1,
+      totalSteps: 3,
+      priorOutputs: ["analysis done"],
+    });
+    expect(text).toContain("step 2 of 3");
+    expect(text).toContain("Design");
+    expect(text).toContain("Propose schema.");
+    expect(text).toContain("analysis done");
+  });
+
+  it("adds page excerpt and resume partial when provided", () => {
+    const text = buildWorkflowStepPrompt({
+      workflowName: "W",
+      step: { id: "s1", title: "T", instruction: "Go" },
+      stepIndex: 0,
+      totalSteps: 1,
+      pageExcerpt: "Note body",
+      priorOutputs: [],
+      resumeFromPartial: "half-done",
+    });
+    expect(text).toContain("Note body");
+    expect(text).toContain("half-done");
+  });
+});
+
+describe("defaultWorkflowStepMaxTurns", () => {
+  it("falls back to 15 when maxTurns is missing", () => {
+    expect(defaultWorkflowStepMaxTurns({ id: "a", title: "t", instruction: "i" })).toBe(15);
+  });
+
+  it("uses explicit maxTurns", () => {
+    expect(
+      defaultWorkflowStepMaxTurns({ id: "a", title: "t", instruction: "i", maxTurns: 7 }),
+    ).toBe(7);
+  });
+});
diff --git a/src/lib/workflow/buildWorkflowStepPrompt.ts b/src/lib/workflow/buildWorkflowStepPrompt.ts
new file mode 100644
index 00000000..a927afb7
--- /dev/null
+++ b/src/lib/workflow/buildWorkflowStepPrompt.ts
@@ -0,0 +1,80 @@
+/**
+ * Builds the user prompt for one workflow step (Issue #462).
+ * ワークフロー 1 ステップ分のユーザープロンプトを組み立てる（Issue #462）。
+ */
+
+import type { WorkflowStepDefinition } from "./types";
+
+const DEFAULT_MAX_TURNS = 15;
+
+/**
+ * Returns default max turns when a step omits `maxTurns`.
+ * ステップが `maxTurns` を省略したときの既定値。
+ */
+export function defaultWorkflowStepMaxTurns(step: WorkflowStepDefinition): number {
+  return step.maxTurns ?? DEFAULT_MAX_TURNS;
+}
+
+/**
+ * Builds Claude Code prompt text for `stepIndex` including prior step outputs.
+ * 先行ステップの出力を含めた Claude Code 用プロンプトを組み立てる。
+ */
+export function buildWorkflowStepPrompt(options: {
+  workflowName: string;
+  step: WorkflowStepDefinition;
+  stepIndex: number;
+  totalSteps: number;
+  /** Plain-text excerpt of the open page (optional). / 開いているページの抜粋（任意） */
+  pageExcerpt?: string;
+  /** Completed assistant outputs from earlier steps. / 先行ステップの完了出力 */
+  priorOutputs: string[];
+  /** When resuming after pause, partial text from the interrupted attempt. / 一時停止後の再開時、中断前の部分テキスト */
+  resumeFromPartial?: string;
+}): string {
+  const {
+    workflowName,
+    step,
+    stepIndex,
+    totalSteps,
+    pageExcerpt,
+    priorOutputs,
+    resumeFromPartial,
+  } = options;
+
+  const parts: string[] = [
+    `You are executing step ${stepIndex + 1} of ${totalSteps} in a workflow named "${workflowName}".`,
+    "",
+    `## Step title`,
+    step.title,
+    "",
+    `## Instructions`,
+    step.instruction.trim() || "(no additional instructions)",
+    "",
+  ];
+
+  if (pageExcerpt?.trim()) {
+    parts.push(`## Context from the open note (excerpt)`, pageExcerpt.trim(), "");
+  }
+
+  if (priorOutputs.length > 0) {
+    parts.push(`## Outputs from previous steps`);
+    for (let i = 0; i < priorOutputs.length; i += 1) {
+      parts.push(`### Step ${i + 1}`, priorOutputs[i].trim() || "(empty)", "");
+    }
+  }
+
+  if (resumeFromPartial?.trim()) {
+    parts.push(
+      `## Resume`,
+      "The previous attempt was interrupted. Continue and improve from this partial output:",
+      resumeFromPartial.trim(),
+      "",
+    );
+  }
+
+  parts.push(
+    `Respond with the result for this step only. Use clear Markdown. Be concise unless the instructions ask for detail.`,
+  );
+
+  return parts.join("\n");
+}
diff --git a/src/lib/workflow/formatWorkflowNoteMarkdown.test.ts b/src/lib/workflow/formatWorkflowNoteMarkdown.test.ts
new file mode 100644
index 00000000..983f388f
--- /dev/null
+++ b/src/lib/workflow/formatWorkflowNoteMarkdown.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { formatWorkflowNoteMarkdown } from "./formatWorkflowNoteMarkdown";
+
+describe("formatWorkflowNoteMarkdown", () => {
+  it("renders title and step markers", () => {
+    const md = formatWorkflowNoteMarkdown({
+      title: "Test",
+      stepTitles: ["A", "B"],
+      stepStatuses: ["done", "pending"],
+      stepOutputs: ["out-a", ""],
+      streamingStepIndex: null,
+      streamingText: "",
+    });
+    expect(md).toContain("## 📋 Workflow: Test");
+    expect(md).toContain("### ☑ 1. A");
+    expect(md).toContain("out-a");
+    expect(md).toContain("### ⬜ 2. B");
+  });
+
+  it("includes streaming text for the running step", () => {
+    const md = formatWorkflowNoteMarkdown({
+      title: "S",
+      stepTitles: ["One"],
+      stepStatuses: ["running"],
+      stepOutputs: [""],
+      streamingStepIndex: 0,
+      streamingText: "partial...",
+    });
+    expect(md).toContain("### 🔄 1. One");
+    expect(md).toContain("partial...");
+  });
+});
diff --git a/src/lib/workflow/formatWorkflowNoteMarkdown.ts b/src/lib/workflow/formatWorkflowNoteMarkdown.ts
new file mode 100644
index 00000000..bd57dabf
--- /dev/null
+++ b/src/lib/workflow/formatWorkflowNoteMarkdown.ts
@@ -0,0 +1,57 @@
+/**
+ * Builds Markdown for embedding workflow progress into a note (Issue #462).
+ * ノートへ進捗を埋め込む Markdown を組み立てる（Issue #462）。
+ */
+
+import type { WorkflowStepRunStatus } from "./types";
+
+const STATUS_PREFIX: Record<WorkflowStepRunStatus, string> = {
+  pending: "⬜",
+  running: "🔄",
+  done: "☑",
+  error: "⚠️",
+};
+
+/**
+ * Formats a workflow block with step headings, optional streaming text, and outputs.
+ * ステップ見出し・ストリーミングテキスト・出力付きのワークフローブロックを整形する。
+ */
+export function formatWorkflowNoteMarkdown(options: {
+  /** Workflow title. / ワークフロー名 */
+  title: string;
+  /** Step titles in order. / ステップタイトル（順序どおり） */
+  stepTitles: string[];
+  /** Status per step. / ステップごとの状態 */
+  stepStatuses: WorkflowStepRunStatus[];
+  /** Final text for steps that finished successfully. / 成功完了したステップの最終テキスト */
+  stepOutputs: string[];
+  /** Index of the step currently streaming, or null. / ストリーム中のステップ index、なければ null */
+  streamingStepIndex: number | null;
+  /** Partial text for the streaming step. / ストリーム中ステップの部分テキスト */
+  streamingText: string;
+}): string {
+  const { title, stepTitles, stepStatuses, stepOutputs, streamingStepIndex, streamingText } =
+    options;
+
+  const lines: string[] = [`## 📋 Workflow: ${title}`, ""];
+
+  for (let i = 0; i < stepTitles.length; i += 1) {
+    const status = stepStatuses[i] ?? "pending";
+    const prefix = STATUS_PREFIX[status];
+    lines.push(`### ${prefix} ${i + 1}. ${stepTitles[i]}`);
+    lines.push("");
+
+    if (status === "done" && stepOutputs[i]) {
+      lines.push(stepOutputs[i].trim() || "(empty)");
+      lines.push("");
+    } else if (status === "running" && streamingStepIndex === i && streamingText.trim()) {
+      lines.push(streamingText.trim());
+      lines.push("");
+    } else if (status === "error") {
+      lines.push("(step failed)");
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n").trimEnd();
+}
diff --git a/src/lib/workflow/newWorkflowId.ts b/src/lib/workflow/newWorkflowId.ts
new file mode 100644
index 00000000..a119ae81
--- /dev/null
+++ b/src/lib/workflow/newWorkflowId.ts
@@ -0,0 +1,15 @@
+/**
+ * Generates a random id for workflow definitions and steps.
+ * ワークフロー定義・ステップ用のランダム ID を生成する。
+ */
+
+/**
+ * Returns a UUID when `crypto.randomUUID` exists; otherwise a fallback string.
+ * `crypto.randomUUID` があれば UUID、なければフォールバック文字列。
+ */
+export function newWorkflowId(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `wf-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
diff --git a/src/lib/workflow/parseWorkflowDefinitionImport.test.ts b/src/lib/workflow/parseWorkflowDefinitionImport.test.ts
new file mode 100644
index 00000000..145ec004
--- /dev/null
+++ b/src/lib/workflow/parseWorkflowDefinitionImport.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { parseWorkflowDefinitionImport } from "./parseWorkflowDefinitionImport";
+
+describe("parseWorkflowDefinitionImport", () => {
+  it("parses minimal valid JSON", () => {
+    const r = parseWorkflowDefinitionImport({
+      name: "W",
+      steps: [{ id: "a", title: "T", instruction: "Do" }],
+    });
+    expect(r.name).toBe("W");
+    expect(r.steps).toHaveLength(1);
+    expect(r.steps[0].title).toBe("T");
+    expect(r.steps[0].instruction).toBe("Do");
+  });
+
+  it("rejects non-object root", () => {
+    expect(() => parseWorkflowDefinitionImport(null)).toThrow();
+  });
+
+  it("rejects missing steps array", () => {
+    expect(() => parseWorkflowDefinitionImport({ name: "x" })).toThrow();
+  });
+
+  it("rejects step without string title/instruction", () => {
+    expect(() =>
+      parseWorkflowDefinitionImport({
+        name: "x",
+        steps: [{ id: "1", title: 1, instruction: "a" }],
+      }),
+    ).toThrow();
+  });
+
+  it("accepts optional maxTurns and allowedTools", () => {
+    const r = parseWorkflowDefinitionImport({
+      name: "x",
+      steps: [
+        {
+          title: "a",
+          instruction: "b",
+          maxTurns: 10,
+          allowedTools: ["Read", "Bash"],
+        },
+      ],
+    });
+    expect(r.steps[0].maxTurns).toBe(10);
+    expect(r.steps[0].allowedTools).toEqual(["Read", "Bash"]);
+  });
+});
diff --git a/src/lib/workflow/parseWorkflowDefinitionImport.ts b/src/lib/workflow/parseWorkflowDefinitionImport.ts
new file mode 100644
index 00000000..86a0efe1
--- /dev/null
+++ b/src/lib/workflow/parseWorkflowDefinitionImport.ts
@@ -0,0 +1,88 @@
+/**
+ * Validates JSON imported as a workflow definition (Issue #462).
+ * ワークフロー定義としてインポートする JSON を検証する（Issue #462）。
+ */
+
+import { newWorkflowId } from "./newWorkflowId";
+import type { WorkflowStepDefinition } from "./types";
+
+const MAX_STEPS = 50;
+const MAX_FIELD_LEN = 50_000;
+const MAX_TOOL_NAME_LEN = 64;
+
+const INVALID = "invalid workflow JSON";
+
+/**
+ * Parses one step object from imported JSON.
+ * インポート JSON のステップオブジェクトを 1 件パースする。
+ */
+function parseWorkflowStepImport(s: Record<string, unknown>): WorkflowStepDefinition {
+  if (typeof s.title !== "string" || typeof s.instruction !== "string") {
+    throw new Error(INVALID);
+  }
+  const title = s.title.slice(0, MAX_FIELD_LEN);
+  const instruction = s.instruction.slice(0, MAX_FIELD_LEN);
+  const id =
+    typeof s.id === "string" && s.id.trim().length > 0 ? s.id.slice(0, 200) : newWorkflowId();
+
+  const step: WorkflowStepDefinition = { id, title, instruction };
+
+  if (s.maxTurns !== undefined) {
+    if (typeof s.maxTurns !== "number" || !Number.isFinite(s.maxTurns)) {
+      throw new Error(INVALID);
+    }
+    const mt = Math.floor(s.maxTurns);
+    if (mt < 1 || mt > 500) {
+      throw new Error(INVALID);
+    }
+    step.maxTurns = mt;
+  }
+
+  if (s.allowedTools !== undefined) {
+    if (!Array.isArray(s.allowedTools)) {
+      throw new Error(INVALID);
+    }
+    step.allowedTools = s.allowedTools.map((t) => {
+      if (typeof t !== "string") {
+        throw new Error(INVALID);
+      }
+      return t.slice(0, MAX_TOOL_NAME_LEN);
+    });
+  }
+
+  return step;
+}
+
+/**
+ * Parses and validates unknown JSON from file import.
+ * ファイルインポート由来の不明な JSON をパースし検証する。
+ *
+ * @throws Error when the shape is invalid or limits are exceeded.
+ */
+export function parseWorkflowDefinitionImport(raw: unknown): {
+  name: string;
+  steps: WorkflowStepDefinition[];
+} {
+  if (!raw || typeof raw !== "object") {
+    throw new Error(INVALID);
+  }
+  const o = raw as Record<string, unknown>;
+  const name = typeof o.name === "string" ? o.name.slice(0, MAX_FIELD_LEN) : "";
+
+  if (!Array.isArray(o.steps)) {
+    throw new Error(INVALID);
+  }
+  if (o.steps.length === 0 || o.steps.length > MAX_STEPS) {
+    throw new Error(INVALID);
+  }
+
+  const steps: WorkflowStepDefinition[] = [];
+  for (const item of o.steps) {
+    if (!item || typeof item !== "object") {
+      throw new Error(INVALID);
+    }
+    steps.push(parseWorkflowStepImport(item as Record<string, unknown>));
+  }
+
+  return { name, steps };
+}
diff --git a/src/lib/workflow/runWorkflowExecution.test.ts b/src/lib/workflow/runWorkflowExecution.test.ts
new file mode 100644
index 00000000..ffa55b1f
--- /dev/null
+++ b/src/lib/workflow/runWorkflowExecution.test.ts
@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { runWorkflowExecution } from "./runWorkflowExecution";
+
+vi.mock("@/lib/claudeCode/streamClaudeQuery", () => ({
+  streamClaudeQuery: vi.fn(),
+}));
+
+import { streamClaudeQuery } from "@/lib/claudeCode/streamClaudeQuery";
+
+describe("runWorkflowExecution", () => {
+  beforeEach(() => {
+    vi.mocked(streamClaudeQuery).mockReset();
+  });
+
+  it("returns error when there are no steps", async () => {
+    const r = await runWorkflowExecution({
+      definition: { id: "w", name: "W", steps: [], createdAt: 0, updatedAt: 0 },
+      workflowSignal: new AbortController().signal,
+      createStepAbort: () => new AbortController(),
+      startStepIndex: 0,
+      stepOutputs: [],
+      onProgress: vi.fn(),
+      onNoteMarkdown: vi.fn(),
+      baseContentBeforeWorkflow: "",
+    });
+    expect(r).toEqual({ outcome: "error", error: "Workflow has no steps." });
+  });
+
+  it("runs one step and completes", async () => {
+    vi.mocked(streamClaudeQuery).mockResolvedValue({ ok: true, content: "done" });
+
+    const onNote = vi.fn();
+    const r = await runWorkflowExecution({
+      definition: {
+        id: "w",
+        name: "W",
+        steps: [{ id: "s1", title: "Only", instruction: "Do work" }],
+        createdAt: 0,
+        updatedAt: 0,
+      },
+      workflowSignal: new AbortController().signal,
+      createStepAbort: () => new AbortController(),
+      startStepIndex: 0,
+      stepOutputs: [],
+      onProgress: vi.fn(),
+      onNoteMarkdown: onNote,
+      baseContentBeforeWorkflow: "base",
+    });
+
+    expect(r).toEqual({ outcome: "completed" });
+    expect(streamClaudeQuery).toHaveBeenCalledTimes(1);
+    const lastNote = onNote.mock.calls.at(-1)?.[0] as string;
+    expect(lastNote).toContain("base");
+    expect(lastNote).toContain("Workflow: W");
+    expect(lastNote).toContain("done");
+  });
+
+  it("returns paused when only the step signal aborts", async () => {
+    vi.mocked(streamClaudeQuery).mockResolvedValue({ ok: false, error: "Aborted" });
+
+    const workflow = new AbortController();
+    const step = new AbortController();
+    let createCount = 0;
+    const r = await runWorkflowExecution({
+      definition: {
+        id: "w",
+        name: "W",
+        steps: [{ id: "s1", title: "A", instruction: "x" }],
+        createdAt: 0,
+        updatedAt: 0,
+      },
+      workflowSignal: workflow.signal,
+      createStepAbort: () => {
+        createCount += 1;
+        return step;
+      },
+      startStepIndex: 0,
+      stepOutputs: [],
+      onProgress: vi.fn(),
+      onNoteMarkdown: vi.fn(),
+      baseContentBeforeWorkflow: "",
+    });
+
+    expect(r.outcome).toBe("paused");
+    if (r.outcome === "paused") {
+      expect(r.pausedAtStepIndex).toBe(0);
+      expect(r.stepOutputs).toEqual([""]);
+    }
+    expect(createCount).toBe(1);
+  });
+});
diff --git a/src/lib/workflow/runWorkflowExecution.ts b/src/lib/workflow/runWorkflowExecution.ts
new file mode 100644
index 00000000..a7099326
--- /dev/null
+++ b/src/lib/workflow/runWorkflowExecution.ts
@@ -0,0 +1,280 @@
+/**
+ * Orchestrates multi-step Claude Code workflow runs (Issue #462).
+ * Claude Code のマルチステップワークフロー実行をオーケストレーションする（Issue #462）。
+ */
+
+import { streamClaudeQuery } from "@/lib/claudeCode/streamClaudeQuery";
+import type { WorkflowDefinition, WorkflowRunProgress, WorkflowStepRunStatus } from "./types";
+import { buildWorkflowStepPrompt, defaultWorkflowStepMaxTurns } from "./buildWorkflowStepPrompt";
+import { formatWorkflowNoteMarkdown } from "./formatWorkflowNoteMarkdown";
+
+/** Outcome when {@link runWorkflowExecution} finishes or yields control. */
+export type WorkflowExecutionOutcome =
+  | { outcome: "completed" }
+  | { outcome: "stopped" }
+  | {
+      outcome: "paused";
+      /** Step index where the run stopped (same step on resume). / 停止したステップ index（再開時も同じ） */
+      pausedAtStepIndex: number;
+      /** Snapshot of outputs for completed steps. / 完了ステップの出力スナップショット */
+      stepOutputs: string[];
+      /** Streaming buffer at pause time for the active step. / 停止時点のアクティブステップのストリーム */
+      partialForStep: string;
+    }
+  | { outcome: "error"; error: string };
+
+type RunWorkflowStepsLoopParams = {
+  definition: WorkflowDefinition;
+  cwd?: string;
+  pageExcerpt?: string;
+  workflowSignal: AbortSignal;
+  createStepAbort: () => AbortController;
+  startStepIndex: number;
+  stepOutputs: string[];
+  resumePartialForCurrentStep?: string;
+  onProgress: (p: WorkflowRunProgress) => void;
+  onNoteMarkdown: (fullMarkdown: string) => void;
+  baseContentBeforeWorkflow: string;
+};
+
+/**
+ * Runs or resumes a workflow: streams each step into the note via `onNoteMarkdown`.
+ * ワークフローを実行または再開し、各ステップを `onNoteMarkdown` 経由でノートへストリームする。
+ */
+export async function runWorkflowExecution(options: {
+  definition: WorkflowDefinition;
+  cwd?: string;
+  pageExcerpt?: string;
+  /** Aborts the whole run (Stop). / 実行全体を中止（停止） */
+  workflowSignal: AbortSignal;
+  /** Fresh controller per step; UI aborts the current one on Pause. / ステップごとに新規。UI が一時停止で現在のみ abort */
+  createStepAbort: () => AbortController;
+  /** First step index to execute (0 on fresh run). / 最初に実行するステップ index（新規は 0） */
+  startStepIndex: number;
+  /** Completed outputs for steps before `startStepIndex`. / `startStepIndex` より前の完了出力 */
+  stepOutputs: string[];
+  /** When resuming the same step after pause, partial assistant text. / 一時停止後に同じステップを再開するときの部分テキスト */
+  resumePartialForCurrentStep?: string;
+  onProgress: (p: WorkflowRunProgress) => void;
+  /** Full note body = base snapshot + formatted workflow block. / ベーススナップショット + 整形済みブロック */
+  onNoteMarkdown: (fullMarkdown: string) => void;
+  /** Editor content before the workflow block was inserted. / ワークフローブロック挿入前のエディタ内容 */
+  baseContentBeforeWorkflow: string;
+}): Promise<WorkflowExecutionOutcome> {
+  const {
+    definition,
+    cwd,
+    pageExcerpt,
+    workflowSignal,
+    createStepAbort,
+    startStepIndex,
+    stepOutputs: initialOutputs,
+    resumePartialForCurrentStep,
+    onProgress,
+    onNoteMarkdown,
+    baseContentBeforeWorkflow,
+  } = options;
+
+  const steps = definition.steps;
+  if (steps.length === 0) {
+    return { outcome: "error", error: "Workflow has no steps." };
+  }
+
+  const stepOutputs = normalizeStepOutputs(initialOutputs, steps.length);
+
+  return runWorkflowStepsLoop({
+    definition,
+    cwd,
+    pageExcerpt,
+    workflowSignal,
+    createStepAbort,
+    startStepIndex,
+    stepOutputs,
+    resumePartialForCurrentStep,
+    onProgress,
+    onNoteMarkdown,
+    baseContentBeforeWorkflow,
+  });
+}
+
+/**
+ * Pads or trims `stepOutputs` to match `stepsLength`.
+ * `stepOutputs` を `stepsLength` に合わせて埋めたり切り詰めたりする。
+ */
+function normalizeStepOutputs(initialOutputs: string[], stepsLength: number): string[] {
+  const stepOutputs = [...initialOutputs];
+  while (stepOutputs.length < stepsLength) {
+    stepOutputs.push("");
+  }
+  if (stepOutputs.length > stepsLength) {
+    stepOutputs.length = stepsLength;
+  }
+  return stepOutputs;
+}
+
+/**
+ * Main step loop: streams each step, updates note and progress.
+ * メインのステップループ：各ステップをストリームし、ノートと進捗を更新する。
+ */
+async function runWorkflowStepsLoop(
+  params: RunWorkflowStepsLoopParams,
+): Promise<WorkflowExecutionOutcome> {
+  const {
+    definition,
+    cwd,
+    pageExcerpt,
+    workflowSignal,
+    createStepAbort,
+    startStepIndex,
+    stepOutputs,
+    resumePartialForCurrentStep,
+    onProgress,
+    onNoteMarkdown,
+    baseContentBeforeWorkflow,
+  } = params;
+
+  const steps = definition.steps;
+  const stepTitles = steps.map((s) => s.title);
+
+  const pushProgress = (
+    phase: WorkflowRunProgress["phase"],
+    currentStepIndex: number,
+    statuses: WorkflowStepRunStatus[],
+    streaming: string,
+    lastError?: string,
+  ): void => {
+    onProgress({
+      phase,
+      currentStepIndex,
+      stepStatuses: statuses,
+      stepOutputs: [...stepOutputs],
+      currentStepStreaming: streaming,
+      lastError,
+    });
+  };
+
+  const emitNote = (
+    currentStepIndex: number,
+    statuses: WorkflowStepRunStatus[],
+    streamingStepIndex: number | null,
+    streamingText: string,
+  ): void => {
+    const block = formatWorkflowNoteMarkdown({
+      title: definition.name,
+      stepTitles,
+      stepStatuses: statuses,
+      stepOutputs,
+      streamingStepIndex,
+      streamingText,
+    });
+    const base = baseContentBeforeWorkflow.trimEnd();
+    const full = base.length > 0 ? `${base}\n\n${block}` : block;
+    onNoteMarkdown(full);
+  };
+
+  for (let i = startStepIndex; i < steps.length; i += 1) {
+    if (workflowSignal.aborted) {
+      pushProgress("aborted", i, buildStatuses(steps.length, i, "pending"), "", undefined);
+      return { outcome: "stopped" };
+    }
+
+    const step = steps[i];
+    const statusesBefore = buildStatuses(steps.length, i, "running");
+    const initialStreaming =
+      resumePartialForCurrentStep && i === startStepIndex ? resumePartialForCurrentStep : "";
+    pushProgress("running", i, statusesBefore, initialStreaming, undefined);
+    emitNote(i, statusesBefore, i, initialStreaming);
+
+    const prior = stepOutputs.slice(0, i).map((_, idx) => stepOutputs[idx] ?? "");
+
+    const prompt = buildWorkflowStepPrompt({
+      workflowName: definition.name,
+      step,
+      stepIndex: i,
+      totalSteps: steps.length,
+      pageExcerpt,
+      priorOutputs: prior,
+      resumePartial: i === startStepIndex ? resumePartialForCurrentStep : undefined,
+    });
+
+    const stepController = createStepAbort();
+    const merged = AbortSignal.any([workflowSignal, stepController.signal]);
+
+    let streaming = initialStreaming;
+
+    const result = await streamClaudeQuery(
+      prompt,
+      {
+        cwd,
+        maxTurns: defaultWorkflowStepMaxTurns(step),
+        allowedTools: step.allowedTools,
+      },
+      merged,
+      {
+        onChunk: (chunk) => {
+          streaming += chunk;
+          const statuses = buildStatuses(steps.length, i, "running");
+          pushProgress("running", i, statuses, streaming, undefined);
+          emitNote(i, statuses, i, streaming);
+        },
+      },
+    );
+
+    if (!result.ok) {
+      if (result.error === "Aborted") {
+        if (workflowSignal.aborted) {
+          pushProgress("aborted", i, buildStatuses(steps.length, i, "error"), "", undefined);
+          return { outcome: "stopped" };
+        }
+        pushProgress("paused", i, buildStatuses(steps.length, i, "running"), streaming, undefined);
+        emitNote(i, buildStatuses(steps.length, i, "running"), i, streaming);
+        return {
+          outcome: "paused",
+          pausedAtStepIndex: i,
+          stepOutputs: [...stepOutputs],
+          partialForStep: streaming,
+        };
+      }
+      stepOutputs[i] = "";
+      const errStatuses = buildStatuses(steps.length, i, "error");
+      pushProgress("running", i, errStatuses, streaming, result.error);
+      emitNote(i, errStatuses, null, "");
+      return { outcome: "error", error: result.error };
+    }
+
+    stepOutputs[i] = result.content;
+    const doneStatuses = buildStatuses(steps.length, i, "done");
+    pushProgress("running", i, doneStatuses, "", undefined);
+    emitNote(i, doneStatuses, null, "");
+  }
+
+  pushProgress(
+    "completed",
+    steps.length - 1,
+    steps.map(() => "done"),
+    "",
+    undefined,
+  );
+  emitNote(
+    steps.length - 1,
+    steps.map(() => "done"),
+    null,
+    "",
+  );
+
+  return { outcome: "completed" };
+}
+
+function buildStatuses(
+  total: number,
+  runningIndex: number,
+  runningKind: WorkflowStepRunStatus,
+): WorkflowStepRunStatus[] {
+  const out: WorkflowStepRunStatus[] = [];
+  for (let j = 0; j < total; j += 1) {
+    if (j < runningIndex) out.push("done");
+    else if (j === runningIndex) out.push(runningKind);
+    else out.push("pending");
+  }
+  return out;
+}
diff --git a/src/lib/workflow/templates.ts b/src/lib/workflow/templates.ts
new file mode 100644
index 00000000..5ce1bbf5
--- /dev/null
+++ b/src/lib/workflow/templates.ts
@@ -0,0 +1,148 @@
+/**
+ * Built-in workflow templates (Issue #462).
+ * 組み込みワークフローテンプレート（Issue #462）。
+ */
+
+import type { WorkflowDefinition, WorkflowStepDefinition } from "./types";
+import { newWorkflowId } from "./newWorkflowId";
+
+/**
+ * Known template ids for selection UI.
+ * 選択 UI 用のテンプレート ID。
+ */
+export const WORKFLOW_TEMPLATE_IDS = [
+  "code-investigate-design",
+  "test-analyze-improve",
+  "repo-analyze-docs",
+  "web-research-note",
+] as const;
+
+/** Template id union. / テンプレート ID ユニオン */
+export type WorkflowTemplateId = (typeof WORKFLOW_TEMPLATE_IDS)[number];
+
+/**
+ * i18n key for the template title (see `aiChat.workflow.templates.*`).
+ * テンプレートタイトル用 i18n キー（`aiChat.workflow.templates.*`）。
+ */
+export const WORKFLOW_TEMPLATE_NAME_KEYS: Record<WorkflowTemplateId, string> = {
+  "code-investigate-design": "aiChat.workflow.templates.codeInvestigateDesign",
+  "test-analyze-improve": "aiChat.workflow.templates.testAnalyzeImprove",
+  "repo-analyze-docs": "aiChat.workflow.templates.repoAnalyzeDocs",
+  "web-research-note": "aiChat.workflow.templates.webResearchNote",
+};
+
+type StepSeed = Omit<WorkflowStepDefinition, "id">;
+
+function stepsForTemplate(id: WorkflowTemplateId): StepSeed[] {
+  switch (id) {
+    case "code-investigate-design":
+      return [
+        {
+          title: "Investigate code patterns",
+          instruction:
+            "Explore the linked workspace: identify API or routing patterns, naming conventions, and error-handling style. Summarize findings as bullet points.",
+          maxTurns: 20,
+          allowedTools: ["Read"],
+        },
+        {
+          title: "Draft design memo",
+          instruction:
+            "Based on the investigation, propose a design for the feature described in the note context. Output structured Markdown (goal, options, recommendation, risks).",
+          maxTurns: 16,
+          allowedTools: ["Read"],
+        },
+      ];
+    case "test-analyze-improve":
+      return [
+        {
+          title: "Run tests",
+          instruction:
+            "Run the project's test command in the linked workspace (e.g. `bun run test:run` or the standard command you detect). Capture failing vs passing summary.",
+          maxTurns: 12,
+          allowedTools: ["Bash", "Read"],
+        },
+        {
+          title: "Analyze results",
+          instruction:
+            "Analyze the test output: categorize failures, likely root causes, and flaky vs deterministic issues.",
+          maxTurns: 14,
+          allowedTools: ["Read"],
+        },
+        {
+          title: "Suggest improvements",
+          instruction:
+            "Propose concrete next steps: code changes, test fixes, and follow-up commands. Use Markdown with numbered actions.",
+          maxTurns: 14,
+          allowedTools: ["Read"],
+        },
+      ];
+    case "repo-analyze-docs":
+      return [
+        {
+          title: "Repository analysis",
+          instruction:
+            "Scan the repository structure (top-level dirs, packages, build entrypoints). Summarize architecture and main technologies.",
+          maxTurns: 20,
+          allowedTools: ["Read", "Bash"],
+        },
+        {
+          title: "Generate documentation draft",
+          instruction:
+            "Produce a documentation outline: overview, setup, development, testing, deployment. Fill with what you can infer from the repo.",
+          maxTurns: 18,
+          allowedTools: ["Read"],
+        },
+      ];
+    case "web-research-note":
+      return [
+        {
+          title: "Web research",
+          instruction:
+            "Research the topic implied by the note title/context using web search. Collect key facts, sources, and conflicting viewpoints.",
+          maxTurns: 20,
+          allowedTools: ["WebSearch", "Read"],
+        },
+        {
+          title: "Organize information",
+          instruction:
+            "Structure the findings: summary table or bullets, source list, and open questions.",
+          maxTurns: 12,
+          allowedTools: [],
+        },
+        {
+          title: "Draft note content",
+          instruction:
+            "Write polished Markdown suitable for the note: clear headings, links to sources, and a short conclusion.",
+          maxTurns: 16,
+          allowedTools: [],
+        },
+      ];
+    default: {
+      const _exhaustive: never = id;
+      throw new Error(`Unknown template: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * Creates a new {@link WorkflowDefinition} from a built-in template.
+ * 組み込みテンプレートから新しい {@link WorkflowDefinition} を作る。
+ */
+export function instantiateWorkflowTemplate(
+  id: WorkflowTemplateId,
+  displayName: string,
+): WorkflowDefinition {
+  const now = Date.now();
+  const seeds = stepsForTemplate(id);
+  const steps: WorkflowStepDefinition[] = seeds.map((s) => ({
+    ...s,
+    id: newWorkflowId(),
+  }));
+  return {
+    id: newWorkflowId(),
+    name: displayName,
+    steps,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
diff --git a/src/lib/workflow/types.ts b/src/lib/workflow/types.ts
new file mode 100644
index 00000000..7e110476
--- /dev/null
+++ b/src/lib/workflow/types.ts
@@ -0,0 +1,67 @@
+/**
+ * Multi-step Claude Code workflow (Issue #462).
+ * Claude Code マルチステップワークフロー（Issue #462）。
+ */
+
+/**
+ * One step in a workflow definition.
+ * ワークフロー定義の 1 ステップ。
+ */
+export interface WorkflowStepDefinition {
+  /** Stable id for React keys and persistence. / React キーと永続化用の安定 ID */
+  id: string;
+  /** Short label shown in UI and note. / UI とノートに表示する短いラベル */
+  title: string;
+  /** Instruction sent to Claude Code for this step. / このステップで Claude Code に渡す指示 */
+  instruction: string;
+  /**
+   * Max agent turns for this step (Claude Agent SDK `maxTurns`).
+   * このステップのエージェント最大ターン数（SDK `maxTurns`）。
+   */
+  maxTurns?: number;
+  /**
+   * Allowed tools for this step; omit for default sidecar tool set.
+   * このステップで許可するツール。省略時は sidecar 既定ツール。
+   */
+  allowedTools?: string[];
+}
+
+/**
+ * A saved or template-derived workflow.
+ * 保存済みまたはテンプレート由来のワークフロー。
+ */
+export interface WorkflowDefinition {
+  id: string;
+  name: string;
+  steps: WorkflowStepDefinition[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+/**
+ * Lifecycle of a workflow run in the UI engine.
+ * UI エンジン上のワークフロー実行ライフサイクル。
+ */
+export type WorkflowRunPhase = "idle" | "running" | "paused" | "completed" | "aborted";
+
+/**
+ * Status of each step during a run.
+ * 実行中の各ステップの状態。
+ */
+export type WorkflowStepRunStatus = "pending" | "running" | "done" | "error";
+
+/**
+ * Snapshot emitted to UI while executing.
+ * 実行中に UI へ送るスナップショット。
+ */
+export interface WorkflowRunProgress {
+  phase: WorkflowRunPhase;
+  currentStepIndex: number;
+  stepStatuses: WorkflowStepRunStatus[];
+  /** Final assistant text per completed step. / 完了ステップごとの最終テキスト */
+  stepOutputs: string[];
+  /** Streaming buffer for the active step. / 実行中ステップのストリームバッファ */
+  currentStepStreaming: string;
+  /** Error message when a step fails. / ステップ失敗時のメッセージ */
+  lastError?: string;
+}
diff --git a/src/stores/workflowDefinitionsStore.ts b/src/stores/workflowDefinitionsStore.ts
new file mode 100644
index 00000000..1aac0cef
--- /dev/null
+++ b/src/stores/workflowDefinitionsStore.ts
@@ -0,0 +1,39 @@
+/**
+ * Persisted custom workflow definitions (Issue #462).
+ * 永続化するカスタムワークフロー定義（Issue #462）。
+ */
+
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import type { WorkflowDefinition } from "@/lib/workflow/types";
+
+interface WorkflowDefinitionsState {
+  definitions: WorkflowDefinition[];
+  /** Insert or replace by id. / id で挿入または置換 */
+  upsertDefinition: (definition: WorkflowDefinition) => void;
+  removeDefinition: (id: string) => void;
+}
+
+/**
+ * Local persisted store for user-defined workflows.
+ * ユーザー定義ワークフローをローカル永続化するストア。
+ */
+export const useWorkflowDefinitionsStore = create<WorkflowDefinitionsState>()(
+  persist(
+    (set, get) => ({
+      definitions: [],
+      upsertDefinition: (definition) => {
+        const rest = get().definitions.filter((d) => d.id !== definition.id);
+        const next = [...rest, definition].sort((a, b) => b.updatedAt - a.updatedAt);
+        set({ definitions: next });
+      },
+      removeDefinition: (id) => {
+        set({ definitions: get().definitions.filter((d) => d.id !== id) });
+      },
+    }),
+    {
+      name: "zedi-workflow-definitions",
+      version: 1,
+    },
+  ),
+);

From 899e91e61803209a866ea35c0aaa5b414518c303 Mon Sep 17 00:00:00 2001
From: otomatty <saedgewell@gmail.com>
Date: Sun, 5 Apr 2026 09:49:16 +0900
Subject: [PATCH 2/5] fix: address PR #477 review comments

- Only refresh workflow base snapshot on fresh runs (avoid duplicate blocks on resume).
- On error/stop: clear paused state, set progress to aborted, sync UI with Copilot/Gemini/Devin.
- Skip claudeQuery when already aborted.
- Fix buildWorkflowStepPrompt option name (resumeFromPartial) and simplify prior outputs slice.

Made-with: Cursor
---
 src/hooks/useWorkflowRunSession.ts       | 4 +++-
 src/hooks/workflowRunOutcomeHandlers.ts  | 3 +++
 src/lib/claudeCode/streamClaudeQuery.ts  | 3 +++
 src/lib/workflow/runWorkflowExecution.ts | 4 ++--
 4 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/hooks/useWorkflowRunSession.ts b/src/hooks/useWorkflowRunSession.ts
index 43628771..04f3957b 100644
--- a/src/hooks/useWorkflowRunSession.ts
+++ b/src/hooks/useWorkflowRunSession.ts
@@ -90,7 +90,9 @@ export function useWorkflowRunSession(draft: WorkflowDefinition) {
       };
 
       workflowAbortRef.current = new AbortController();
-      baseSnapshotRef.current = pageContext?.pageFullContent ?? "";
+      if (mode === "fresh") {
+        baseSnapshotRef.current = pageContext?.pageFullContent ?? "";
+      }
 
       const startIndex = mode === "resume" && pausedState ? pausedState.pausedAtStepIndex : 0;
       const initialOutputs = mode === "resume" && pausedState ? [...pausedState.stepOutputs] : [];
diff --git a/src/hooks/workflowRunOutcomeHandlers.ts b/src/hooks/workflowRunOutcomeHandlers.ts
index b1c2ca53..edcd2ca3 100644
--- a/src/hooks/workflowRunOutcomeHandlers.ts
+++ b/src/hooks/workflowRunOutcomeHandlers.ts
@@ -52,12 +52,15 @@ export function applyWorkflowRunOutcome(
       toast({ title: t("aiChat.workflow.paused") });
       return;
     case "stopped":
+      setPausedState(null);
       setActiveRunSteps(null);
       setProgress((p) => (p ? { ...p, phase: "aborted" } : null));
       toast({ title: t("aiChat.workflow.stopped") });
       return;
     case "error":
+      setPausedState(null);
       setActiveRunSteps(null);
+      setProgress((p) => (p ? { ...p, phase: "aborted" } : null));
       toast({
         title: t("aiChat.workflow.error", { message: result.error }),
         variant: "destructive",
diff --git a/src/lib/claudeCode/streamClaudeQuery.ts b/src/lib/claudeCode/streamClaudeQuery.ts
index e6c2b681..ace79006 100644
--- a/src/lib/claudeCode/streamClaudeQuery.ts
+++ b/src/lib/claudeCode/streamClaudeQuery.ts
@@ -152,6 +152,9 @@ export async function streamClaudeQuery(
   });
 
   try {
+    if (signal?.aborted) {
+      return { ok: false, error: "Aborted" };
+    }
     requestId = await claudeQuery(prompt, options);
 
     const merged = { aggregated, finished, errorMessage };
diff --git a/src/lib/workflow/runWorkflowExecution.ts b/src/lib/workflow/runWorkflowExecution.ts
index a7099326..9ac213b9 100644
--- a/src/lib/workflow/runWorkflowExecution.ts
+++ b/src/lib/workflow/runWorkflowExecution.ts
@@ -185,7 +185,7 @@ async function runWorkflowStepsLoop(
     pushProgress("running", i, statusesBefore, initialStreaming, undefined);
     emitNote(i, statusesBefore, i, initialStreaming);
 
-    const prior = stepOutputs.slice(0, i).map((_, idx) => stepOutputs[idx] ?? "");
+    const prior = stepOutputs.slice(0, i);
 
     const prompt = buildWorkflowStepPrompt({
       workflowName: definition.name,
@@ -194,7 +194,7 @@ async function runWorkflowStepsLoop(
       totalSteps: steps.length,
       pageExcerpt,
       priorOutputs: prior,
-      resumePartial: i === startStepIndex ? resumePartialForCurrentStep : undefined,
+      resumeFromPartial: i === startStepIndex ? resumePartialForCurrentStep : undefined,
     });
 
     const stepController = createStepAbort();

From 83bb2e127726548184f92148b79e382dd4e6608d Mon Sep 17 00:00:00 2001
From: otomatty <saedgewell@gmail.com>
Date: Sun, 5 Apr 2026 10:07:57 +0900
Subject: [PATCH 3/5] fix: address CodeRabbit PR #477 review (workflow UI,
 a11y, streamClaudeQuery)

- Gate Run/Resume on desktop + editor; sync stop/error UI state and streaming guard.
- Keep workflow panel mounted after first visit so tab switches do not reset runs.
- Meta/steps a11y (labels, aria-labels); empty done outputs in note markdown; dedupe import IDs.
- streamClaudeQuery: buffer pre-request tool events; cleanup listeners if subscribe fails.
- Defer revokeObjectURL after export; tighten pause test to use aborted step signal.

Made-with: Cursor
---
 src/components/ai-chat/AIChatPanelContent.tsx |  35 +++-
 src/components/ai-chat/WorkflowPanelForm.tsx  |   6 +-
 .../ai-chat/WorkflowPanelMetaSection.tsx      |  18 +-
 .../ai-chat/WorkflowPanelStepsAndProgress.tsx |   7 +-
 src/hooks/useWorkflowDraft.ts                 |   2 +-
 src/hooks/workflowRunOutcomeHandlers.ts       |  23 ++-
 src/i18n/locales/en/aiChat.json               |   3 +
 src/i18n/locales/ja/aiChat.json               |   3 +
 src/lib/claudeCode/streamClaudeQuery.ts       | 154 +++++++++++-------
 .../formatWorkflowNoteMarkdown.test.ts        |  12 ++
 .../workflow/formatWorkflowNoteMarkdown.ts    |   4 +-
 .../parseWorkflowDefinitionImport.test.ts     |  13 ++
 .../workflow/parseWorkflowDefinitionImport.ts |   8 +-
 src/lib/workflow/runWorkflowExecution.test.ts |   8 +-
 14 files changed, 214 insertions(+), 82 deletions(-)

diff --git a/src/components/ai-chat/AIChatPanelContent.tsx b/src/components/ai-chat/AIChatPanelContent.tsx
index 8539bd28..64fc89fb 100644
--- a/src/components/ai-chat/AIChatPanelContent.tsx
+++ b/src/components/ai-chat/AIChatPanelContent.tsx
@@ -1,6 +1,6 @@
-import { Suspense, lazy, useCallback } from "react";
+import { Suspense, lazy, useCallback, useLayoutEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { useToast } from "@zedi/ui";
+import { cn, useToast } from "@zedi/ui";
 import { AIChatHeader } from "./AIChatHeader";
 import { AIChatViewTabs } from "./AIChatViewTabs";
 import { AIChatInput } from "./AIChatInput";
@@ -91,6 +91,19 @@ export function AIChatPanelContent({
 
   const canInsert = pageContext?.type === "editor";
 
+  /** After the workflow tab is visited once, keep the panel mounted so run state survives tab switches. / ワークフロータブを一度開いたらマウントを維持し、タブ切替で実行状態を失わない */
+  const [keepWorkflowMounted, setKeepWorkflowMounted] = useState(
+    () => activeViewTab === "workflow",
+  );
+  useLayoutEffect(() => {
+    if (activeViewTab === "workflow") {
+      // Latch: after first visit to the workflow tab, keep the panel mounted so run/pause state survives tab switches.
+      // 初回表示後はマウントを維持し、タブ切替で実行状態を失わない。
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- one-way latch from tab selection (not external sync)
+      setKeepWorkflowMounted(true);
+    }
+  }, [activeViewTab]);
+
   return (
     <div className="bg-background relative flex h-full flex-col border-l">
       <AIChatHeader />
@@ -131,11 +144,19 @@ export function AIChatPanelContent({
               onDeleteBranch={handleDeleteBranchFromTree}
             />
           </Suspense>
-        ) : (
-          <Suspense fallback={null}>
-            <AIChatWorkflowPanel />
-          </Suspense>
-        )}
+        ) : null}
+        {keepWorkflowMounted ? (
+          <div
+            className={cn(
+              "min-h-0 flex-1 flex-col",
+              activeViewTab === "workflow" ? "flex" : "hidden",
+            )}
+          >
+            <Suspense fallback={null}>
+              <AIChatWorkflowPanel />
+            </Suspense>
+          </div>
+        ) : null}
       </div>
 
       {activeViewTab !== "workflow" && (
diff --git a/src/components/ai-chat/WorkflowPanelForm.tsx b/src/components/ai-chat/WorkflowPanelForm.tsx
index bb06471a..e922fd63 100644
--- a/src/components/ai-chat/WorkflowPanelForm.tsx
+++ b/src/components/ai-chat/WorkflowPanelForm.tsx
@@ -43,6 +43,8 @@ export function WorkflowPanelForm(props: WorkflowPanelFormProps) {
     deleteSaved,
   } = props;
 
+  const canRunWorkflow = isTauriDesktop() && isEditor;
+
   return (
     <div className="flex h-full min-h-0 flex-col gap-3 p-3">
       <div className="text-muted-foreground flex items-center gap-2 text-xs">
@@ -89,7 +91,7 @@ export function WorkflowPanelForm(props: WorkflowPanelFormProps) {
           type="button"
           size="sm"
           className="h-8 text-xs"
-          disabled={running || !isEditor}
+          disabled={running || !canRunWorkflow}
           onClick={() => void runExecution("fresh")}
         >
           <Play className="mr-1 h-3 w-3" />
@@ -111,7 +113,7 @@ export function WorkflowPanelForm(props: WorkflowPanelFormProps) {
           variant="secondary"
           size="sm"
           className="h-8 text-xs"
-          disabled={running || !pausedState}
+          disabled={running || !pausedState || !canRunWorkflow}
           onClick={() => void runExecution("resume")}
         >
           {t("aiChat.workflow.resume")}
diff --git a/src/components/ai-chat/WorkflowPanelMetaSection.tsx b/src/components/ai-chat/WorkflowPanelMetaSection.tsx
index 6cdaca00..ce08566c 100644
--- a/src/components/ai-chat/WorkflowPanelMetaSection.tsx
+++ b/src/components/ai-chat/WorkflowPanelMetaSection.tsx
@@ -62,8 +62,11 @@ export function WorkflowPanelMetaSection(props: Props) {
   return (
     <>
       <div className="grid gap-2">
-        <Label className="text-xs">{t("aiChat.workflow.workflowName")}</Label>
+        <Label htmlFor="workflow-panel-name" className="text-xs">
+          {t("aiChat.workflow.workflowName")}
+        </Label>
         <Input
+          id="workflow-panel-name"
           value={draft.name}
           onChange={(e) => setDraft((d) => ({ ...d, name: e.target.value, updatedAt: Date.now() }))}
           placeholder={t("aiChat.workflow.workflowNamePlaceholder")}
@@ -72,9 +75,11 @@ export function WorkflowPanelMetaSection(props: Props) {
       </div>
 
       <div className="grid gap-2">
-        <Label className="text-xs">{t("aiChat.workflow.template")}</Label>
+        <Label htmlFor="workflow-panel-template" className="text-xs">
+          {t("aiChat.workflow.template")}
+        </Label>
         <Select disabled={running} onValueChange={(v) => loadTemplate(v as WorkflowTemplateId)}>
-          <SelectTrigger className="h-8 text-xs">
+          <SelectTrigger id="workflow-panel-template" className="h-8 text-xs">
             <SelectValue placeholder={t("aiChat.workflow.templatePlaceholder")} />
           </SelectTrigger>
           <SelectContent>
@@ -88,14 +93,16 @@ export function WorkflowPanelMetaSection(props: Props) {
       </div>
 
       <div className="grid gap-2">
-        <Label className="text-xs">{t("aiChat.workflow.savedWorkflows")}</Label>
+        <Label htmlFor="workflow-panel-saved" className="text-xs">
+          {t("aiChat.workflow.savedWorkflows")}
+        </Label>
         <div className="flex gap-2">
           <Select
             disabled={running}
             value={selectedSavedId || undefined}
             onValueChange={(v) => loadSaved(v)}
           >
-            <SelectTrigger className="h-8 flex-1 text-xs">
+            <SelectTrigger id="workflow-panel-saved" className="h-8 flex-1 text-xs">
               <SelectValue placeholder={t("aiChat.workflow.pickSaved")} />
             </SelectTrigger>
             <SelectContent>
@@ -113,6 +120,7 @@ export function WorkflowPanelMetaSection(props: Props) {
             className="h-8 w-8 shrink-0"
             disabled={!selectedSavedId || running}
             onClick={deleteSaved}
+            aria-label={t("aiChat.workflow.deleteSaved")}
             title={t("aiChat.workflow.deleteSaved")}
           >
             <Trash2 className="h-3.5 w-3.5" />
diff --git a/src/components/ai-chat/WorkflowPanelStepsAndProgress.tsx b/src/components/ai-chat/WorkflowPanelStepsAndProgress.tsx
index a2c0e4a1..521b0cc2 100644
--- a/src/components/ai-chat/WorkflowPanelStepsAndProgress.tsx
+++ b/src/components/ai-chat/WorkflowPanelStepsAndProgress.tsx
@@ -57,6 +57,7 @@ export function WorkflowPanelStepsAndProgress(props: Props) {
                 className="h-7 w-7"
                 disabled={running || draft.steps.length <= 1}
                 onClick={() => removeStep(index)}
+                aria-label={t("aiChat.workflow.removeStep", { n: index + 1 })}
               >
                 <Trash2 className="h-3 w-3" />
               </Button>
@@ -65,6 +66,7 @@ export function WorkflowPanelStepsAndProgress(props: Props) {
               className="h-8 text-xs"
               value={step.title}
               placeholder={t("aiChat.workflow.stepTitlePlaceholder")}
+              aria-label={t("aiChat.workflow.stepTitleAria", { n: index + 1 })}
               disabled={running}
               onChange={(e) => updateStep(index, { title: e.target.value })}
             />
@@ -72,6 +74,7 @@ export function WorkflowPanelStepsAndProgress(props: Props) {
               className="border-input bg-background focus-visible:ring-ring min-h-[72px] w-full rounded-md border px-2 py-1.5 text-xs focus-visible:ring-2 focus-visible:outline-none"
               value={step.instruction}
               placeholder={t("aiChat.workflow.stepInstructionPlaceholder")}
+              aria-label={t("aiChat.workflow.stepInstructionAria", { n: index + 1 })}
               disabled={running}
               onChange={(e) => updateStep(index, { instruction: e.target.value })}
             />
@@ -94,7 +97,9 @@ export function WorkflowPanelStepsAndProgress(props: Props) {
                   <span>
                     {mark} {s.title || t("aiChat.workflow.unnamedStep", { n: i + 1 })}
                   </span>
-                  {st === "running" && progress.currentStepStreaming ? (
+                  {progress.phase === "running" &&
+                  st === "running" &&
+                  progress.currentStepStreaming ? (
                     <span className="text-muted-foreground line-clamp-3 pl-4">
                       {progress.currentStepStreaming}
                     </span>
diff --git a/src/hooks/useWorkflowDraft.ts b/src/hooks/useWorkflowDraft.ts
index b1dc865f..523db16a 100644
--- a/src/hooks/useWorkflowDraft.ts
+++ b/src/hooks/useWorkflowDraft.ts
@@ -93,7 +93,7 @@ export function useWorkflowDraft() {
     a.href = url;
     a.download = `${draft.name.trim() || "workflow"}.json`;
     a.click();
-    URL.revokeObjectURL(url);
+    window.setTimeout(() => URL.revokeObjectURL(url), 0);
   }, [draft]);
 
   const onImportFile = useCallback(
diff --git a/src/hooks/workflowRunOutcomeHandlers.ts b/src/hooks/workflowRunOutcomeHandlers.ts
index edcd2ca3..dd8333b3 100644
--- a/src/hooks/workflowRunOutcomeHandlers.ts
+++ b/src/hooks/workflowRunOutcomeHandlers.ts
@@ -54,13 +54,32 @@ export function applyWorkflowRunOutcome(
     case "stopped":
       setPausedState(null);
       setActiveRunSteps(null);
-      setProgress((p) => (p ? { ...p, phase: "aborted" } : null));
+      setProgress((p) => {
+        if (!p) return null;
+        const stepStatuses = p.stepStatuses.map((s) => (s === "running" ? "pending" : s));
+        return {
+          ...p,
+          phase: "aborted",
+          stepStatuses,
+          currentStepStreaming: "",
+        };
+      });
       toast({ title: t("aiChat.workflow.stopped") });
       return;
     case "error":
       setPausedState(null);
       setActiveRunSteps(null);
-      setProgress((p) => (p ? { ...p, phase: "aborted" } : null));
+      setProgress((p) => {
+        if (!p) return null;
+        const stepStatuses = p.stepStatuses.map((s) => (s === "running" ? "error" : s));
+        return {
+          ...p,
+          phase: "aborted",
+          stepStatuses,
+          currentStepStreaming: "",
+          lastError: result.error,
+        };
+      });
       toast({
         title: t("aiChat.workflow.error", { message: result.error }),
         variant: "destructive",
diff --git a/src/i18n/locales/en/aiChat.json b/src/i18n/locales/en/aiChat.json
index 435cb9c1..7ea0bff5 100644
--- a/src/i18n/locales/en/aiChat.json
+++ b/src/i18n/locales/en/aiChat.json
@@ -101,6 +101,9 @@
     "steps": "Steps",
     "addStep": "Add step",
     "stepLabel": "Step {{n}}",
+    "removeStep": "Remove step {{n}}",
+    "stepTitleAria": "Step {{n}} title",
+    "stepInstructionAria": "Step {{n}} instructions",
     "stepTitlePlaceholder": "Step title",
     "stepInstructionPlaceholder": "What Claude Code should do in this step",
     "unnamedStep": "Step {{n}}",
diff --git a/src/i18n/locales/ja/aiChat.json b/src/i18n/locales/ja/aiChat.json
index f85f0623..2e4d4ef3 100644
--- a/src/i18n/locales/ja/aiChat.json
+++ b/src/i18n/locales/ja/aiChat.json
@@ -101,6 +101,9 @@
     "steps": "ステップ",
     "addStep": "ステップを追加",
     "stepLabel": "ステップ {{n}}",
+    "removeStep": "ステップ {{n}} を削除",
+    "stepTitleAria": "ステップ {{n}} のタイトル",
+    "stepInstructionAria": "ステップ {{n}} の指示",
     "stepTitlePlaceholder": "ステップのタイトル",
     "stepInstructionPlaceholder": "このステップで Claude Code にやってほしいこと",
     "unnamedStep": "ステップ {{n}}",
diff --git a/src/lib/claudeCode/streamClaudeQuery.ts b/src/lib/claudeCode/streamClaudeQuery.ts
index ace79006..5f20f734 100644
--- a/src/lib/claudeCode/streamClaudeQuery.ts
+++ b/src/lib/claudeCode/streamClaudeQuery.ts
@@ -24,7 +24,9 @@ export type ClaudeQueryCompletionResult =
 type PreRequestEvent =
   | { type: "chunk"; id: string; content: string }
   | { type: "complete"; id: string; result?: { content: string } }
-  | { type: "error"; id: string; error: string };
+  | { type: "error"; id: string; error: string }
+  | { type: "toolStart"; id: string; toolName: string }
+  | { type: "toolComplete"; id: string; toolName: string };
 
 /**
  * Optional callbacks while streaming Claude Code output.
@@ -51,19 +53,23 @@ function applyPreRequestBuffer(
     finished: boolean;
     errorMessage: string | null;
   },
-  onChunk?: (text: string) => void,
+  callbacks: StreamClaudeQueryCallbacks,
 ): void {
   for (const ev of buffer) {
     if (ev.id !== requestId) continue;
     if (ev.type === "chunk") {
       state.aggregated += ev.content;
-      onChunk?.(ev.content);
+      callbacks.onChunk?.(ev.content);
     } else if (ev.type === "complete") {
       state.aggregated = ev.result?.content ?? state.aggregated;
       state.finished = true;
     } else if (ev.type === "error") {
       state.errorMessage = ev.error;
       state.finished = true;
+    } else if (ev.type === "toolStart") {
+      callbacks.onToolUseStart?.(ev.toolName);
+    } else if (ev.type === "toolComplete") {
+      callbacks.onToolUseComplete?.(ev.toolName);
     }
   }
   buffer.length = 0;
@@ -99,66 +105,90 @@ export async function streamClaudeQuery(
 
   const preRequestBuffer: PreRequestEvent[] = [];
 
-  const unlistenChunk = await onClaudeStreamChunk((payload) => {
-    if (finished) return;
-    if (requestId && payload.id === requestId) {
-      aggregated += payload.content;
-      callbacks.onChunk?.(payload.content);
-      wake();
-    } else if (!requestId) {
-      preRequestBuffer.push({ type: "chunk", id: payload.id, content: payload.content });
-    }
-  });
-
-  const unlistenComplete = await onClaudeStreamComplete((payload) => {
-    if (finished) return;
-    if (requestId && payload.id === requestId) {
-      const text = payload.result?.content ?? aggregated;
-      aggregated = text;
-      finished = true;
-      wake();
-    } else if (!requestId) {
-      preRequestBuffer.push({
-        type: "complete",
-        id: payload.id,
-        result: payload.result,
-      });
-    }
-  });
-
-  const unlistenError = await onClaudeError((payload) => {
-    if (finished) return;
-    if (requestId && payload.id === requestId) {
-      errorMessage = payload.error;
-      finished = true;
-      wake();
-    } else if (!requestId) {
-      preRequestBuffer.push({ type: "error", id: payload.id, error: payload.error });
-    }
-  });
-
-  const unlistenToolStart = await onClaudeToolUseStart((payload) => {
-    if (finished) return;
-    if (requestId && payload.id === requestId) {
-      callbacks.onToolUseStart?.(payload.toolName);
-    }
-  });
-
-  const unlistenToolComplete = await onClaudeToolUseComplete((payload) => {
-    if (finished) return;
-    if (requestId && payload.id === requestId) {
-      callbacks.onToolUseComplete?.(payload.toolName);
-    }
-  });
+  const cleanups: Array<() => void> = [];
 
   try {
+    cleanups.push(
+      await onClaudeStreamChunk((payload) => {
+        if (finished) return;
+        if (requestId && payload.id === requestId) {
+          aggregated += payload.content;
+          callbacks.onChunk?.(payload.content);
+          wake();
+        } else if (!requestId) {
+          preRequestBuffer.push({ type: "chunk", id: payload.id, content: payload.content });
+        }
+      }),
+    );
+
+    cleanups.push(
+      await onClaudeStreamComplete((payload) => {
+        if (finished) return;
+        if (requestId && payload.id === requestId) {
+          const text = payload.result?.content ?? aggregated;
+          aggregated = text;
+          finished = true;
+          wake();
+        } else if (!requestId) {
+          preRequestBuffer.push({
+            type: "complete",
+            id: payload.id,
+            result: payload.result,
+          });
+        }
+      }),
+    );
+
+    cleanups.push(
+      await onClaudeError((payload) => {
+        if (finished) return;
+        if (requestId && payload.id === requestId) {
+          errorMessage = payload.error;
+          finished = true;
+          wake();
+        } else if (!requestId) {
+          preRequestBuffer.push({ type: "error", id: payload.id, error: payload.error });
+        }
+      }),
+    );
+
+    cleanups.push(
+      await onClaudeToolUseStart((payload) => {
+        if (finished) return;
+        if (requestId && payload.id === requestId) {
+          callbacks.onToolUseStart?.(payload.toolName);
+        } else if (!requestId) {
+          preRequestBuffer.push({
+            type: "toolStart",
+            id: payload.id,
+            toolName: payload.toolName,
+          });
+        }
+      }),
+    );
+
+    cleanups.push(
+      await onClaudeToolUseComplete((payload) => {
+        if (finished) return;
+        if (requestId && payload.id === requestId) {
+          callbacks.onToolUseComplete?.(payload.toolName);
+        } else if (!requestId) {
+          preRequestBuffer.push({
+            type: "toolComplete",
+            id: payload.id,
+            toolName: payload.toolName,
+          });
+        }
+      }),
+    );
+
     if (signal?.aborted) {
       return { ok: false, error: "Aborted" };
     }
     requestId = await claudeQuery(prompt, options);
 
     const merged = { aggregated, finished, errorMessage };
-    applyPreRequestBuffer(requestId, preRequestBuffer, merged, callbacks.onChunk);
+    applyPreRequestBuffer(requestId, preRequestBuffer, merged, callbacks);
     aggregated = merged.aggregated;
     finished = merged.finished;
     errorMessage = merged.errorMessage;
@@ -198,11 +228,15 @@ export async function streamClaudeQuery(
     const msg = e instanceof Error ? e.message : String(e);
     return { ok: false, error: msg };
   } finally {
-    unlistenChunk();
-    unlistenComplete();
-    unlistenError();
-    unlistenToolStart();
-    unlistenToolComplete();
+    for (let i = cleanups.length - 1; i >= 0; i -= 1) {
+      const unlisten = cleanups[i];
+      if (!unlisten) continue;
+      try {
+        unlisten();
+      } catch {
+        /* ignore unlisten errors */
+      }
+    }
     requestId = null;
   }
 }
diff --git a/src/lib/workflow/formatWorkflowNoteMarkdown.test.ts b/src/lib/workflow/formatWorkflowNoteMarkdown.test.ts
index 983f388f..9236cbb7 100644
--- a/src/lib/workflow/formatWorkflowNoteMarkdown.test.ts
+++ b/src/lib/workflow/formatWorkflowNoteMarkdown.test.ts
@@ -17,6 +17,18 @@ describe("formatWorkflowNoteMarkdown", () => {
     expect(md).toContain("### ⬜ 2. B");
   });
 
+  it("shows (empty) for done step with empty output", () => {
+    const md = formatWorkflowNoteMarkdown({
+      title: "E",
+      stepTitles: ["Only"],
+      stepStatuses: ["done"],
+      stepOutputs: [""],
+      streamingStepIndex: null,
+      streamingText: "",
+    });
+    expect(md).toContain("(empty)");
+  });
+
   it("includes streaming text for the running step", () => {
     const md = formatWorkflowNoteMarkdown({
       title: "S",
diff --git a/src/lib/workflow/formatWorkflowNoteMarkdown.ts b/src/lib/workflow/formatWorkflowNoteMarkdown.ts
index bd57dabf..68ef6a83 100644
--- a/src/lib/workflow/formatWorkflowNoteMarkdown.ts
+++ b/src/lib/workflow/formatWorkflowNoteMarkdown.ts
@@ -41,8 +41,8 @@ export function formatWorkflowNoteMarkdown(options: {
     lines.push(`### ${prefix} ${i + 1}. ${stepTitles[i]}`);
     lines.push("");
 
-    if (status === "done" && stepOutputs[i]) {
-      lines.push(stepOutputs[i].trim() || "(empty)");
+    if (status === "done") {
+      lines.push((stepOutputs[i] ?? "").trim() || "(empty)");
       lines.push("");
     } else if (status === "running" && streamingStepIndex === i && streamingText.trim()) {
       lines.push(streamingText.trim());
diff --git a/src/lib/workflow/parseWorkflowDefinitionImport.test.ts b/src/lib/workflow/parseWorkflowDefinitionImport.test.ts
index 145ec004..ded387ec 100644
--- a/src/lib/workflow/parseWorkflowDefinitionImport.test.ts
+++ b/src/lib/workflow/parseWorkflowDefinitionImport.test.ts
@@ -30,6 +30,19 @@ describe("parseWorkflowDefinitionImport", () => {
     ).toThrow();
   });
 
+  it("re-issues step ids when duplicates appear", () => {
+    const r = parseWorkflowDefinitionImport({
+      name: "Dup",
+      steps: [
+        { id: "same", title: "A", instruction: "a" },
+        { id: "same", title: "B", instruction: "b" },
+      ],
+    });
+    expect(r.steps[0].id).toBe("same");
+    expect(r.steps[1].id).not.toBe("same");
+    expect(r.steps[1].title).toBe("B");
+  });
+
   it("accepts optional maxTurns and allowedTools", () => {
     const r = parseWorkflowDefinitionImport({
       name: "x",
diff --git a/src/lib/workflow/parseWorkflowDefinitionImport.ts b/src/lib/workflow/parseWorkflowDefinitionImport.ts
index 86a0efe1..b4589459 100644
--- a/src/lib/workflow/parseWorkflowDefinitionImport.ts
+++ b/src/lib/workflow/parseWorkflowDefinitionImport.ts
@@ -77,11 +77,17 @@ export function parseWorkflowDefinitionImport(raw: unknown): {
   }
 
   const steps: WorkflowStepDefinition[] = [];
+  const seenIds = new Set<string>();
   for (const item of o.steps) {
     if (!item || typeof item !== "object") {
       throw new Error(INVALID);
     }
-    steps.push(parseWorkflowStepImport(item as Record<string, unknown>));
+    let step = parseWorkflowStepImport(item as Record<string, unknown>);
+    if (seenIds.has(step.id)) {
+      step = { ...step, id: newWorkflowId() };
+    }
+    seenIds.add(step.id);
+    steps.push(step);
   }
 
   return { name, steps };
diff --git a/src/lib/workflow/runWorkflowExecution.test.ts b/src/lib/workflow/runWorkflowExecution.test.ts
index ffa55b1f..5a77e64c 100644
--- a/src/lib/workflow/runWorkflowExecution.test.ts
+++ b/src/lib/workflow/runWorkflowExecution.test.ts
@@ -56,7 +56,12 @@ describe("runWorkflowExecution", () => {
   });
 
   it("returns paused when only the step signal aborts", async () => {
-    vi.mocked(streamClaudeQuery).mockResolvedValue({ ok: false, error: "Aborted" });
+    vi.mocked(streamClaudeQuery).mockImplementation(async (_p, _o, signal) => {
+      if (signal?.aborted) {
+        return { ok: false, error: "Aborted" };
+      }
+      return { ok: false, error: "Aborted" };
+    });
 
     const workflow = new AbortController();
     const step = new AbortController();
@@ -72,6 +77,7 @@ describe("runWorkflowExecution", () => {
       workflowSignal: workflow.signal,
       createStepAbort: () => {
         createCount += 1;
+        step.abort();
         return step;
       },
       startStepIndex: 0,

From f823f68a5d586adb6c007e2c5810d92f9f962fb6 Mon Sep 17 00:00:00 2001
From: otomatty <saedgewell@gmail.com>
Date: Sun, 5 Apr 2026 10:52:44 +0900
Subject: [PATCH 4/5] fix: address PR #477 Devin review (workflow height,
 resume by step id)

- Use h-full on workflow panel wrapper so ScrollArea gets a bounded height.
- Pause outcome carries pausedStepId + stepOutputsById; resume resolves index by id.
- Toast when paused step is missing after draft edits; extract resolveResumeFromPaused.

Made-with: Cursor
---
 src/components/ai-chat/AIChatPanelContent.tsx |  2 +-
 src/hooks/useWorkflowRunSession.ts            | 46 +++++++++++++++----
 src/hooks/workflowRunOutcomeHandlers.ts       | 10 ++--
 src/i18n/locales/en/aiChat.json               |  1 +
 src/i18n/locales/ja/aiChat.json               |  1 +
 src/lib/workflow/runWorkflowExecution.test.ts |  2 +
 src/lib/workflow/runWorkflowExecution.ts      | 10 ++++
 7 files changed, 58 insertions(+), 14 deletions(-)

diff --git a/src/components/ai-chat/AIChatPanelContent.tsx b/src/components/ai-chat/AIChatPanelContent.tsx
index 64fc89fb..2ff45156 100644
--- a/src/components/ai-chat/AIChatPanelContent.tsx
+++ b/src/components/ai-chat/AIChatPanelContent.tsx
@@ -148,7 +148,7 @@ export function AIChatPanelContent({
         {keepWorkflowMounted ? (
           <div
             className={cn(
-              "min-h-0 flex-1 flex-col",
+              "h-full min-h-0 flex-col",
               activeViewTab === "workflow" ? "flex" : "hidden",
             )}
           >
diff --git a/src/hooks/useWorkflowRunSession.ts b/src/hooks/useWorkflowRunSession.ts
index 04f3957b..451eaadc 100644
--- a/src/hooks/useWorkflowRunSession.ts
+++ b/src/hooks/useWorkflowRunSession.ts
@@ -16,6 +16,30 @@ import type {
 } from "@/lib/workflow/types";
 import { applyWorkflowRunOutcome } from "./workflowRunOutcomeHandlers";
 
+/** Snapshot while paused (step id + outputs by id). / 一時停止中のスナップショット */
+type PausedSnapshot = {
+  pausedStepId: string;
+  stepOutputsById: Record<string, string>;
+  partialForStep: string;
+};
+
+/**
+ * Maps paused snapshot onto current valid steps; returns null if the paused step id is missing.
+ * 現在の有効ステップへ一時停止状態を写す。paused ステップが無ければ null。
+ */
+function resolveResumeFromPaused(
+  paused: PausedSnapshot,
+  validSteps: WorkflowStepDefinition[],
+): { startIndex: number; initialOutputs: string[]; resumePartial: string } | null {
+  const j = validSteps.findIndex((s) => s.id === paused.pausedStepId);
+  if (j === -1) return null;
+  return {
+    startIndex: j,
+    initialOutputs: validSteps.map((s, k) => (k < j ? (paused.stepOutputsById[s.id] ?? "") : "")),
+    resumePartial: paused.partialForStep,
+  };
+}
+
 /**
  * Runs, pauses, and resumes workflows against the current note context.
  * 現在のノート文脈に対してワークフローを実行・一時停止・再開する。
@@ -27,11 +51,7 @@ export function useWorkflowRunSession(draft: WorkflowDefinition) {
 
   const [progress, setProgress] = useState<WorkflowRunProgress | null>(null);
   const [activeRunSteps, setActiveRunSteps] = useState<WorkflowStepDefinition[] | null>(null);
-  const [pausedState, setPausedState] = useState<{
-    pausedAtStepIndex: number;
-    stepOutputs: string[];
-    partialForStep: string;
-  } | null>(null);
+  const [pausedState, setPausedState] = useState<PausedSnapshot | null>(null);
 
   const workflowAbortRef = useRef<AbortController | null>(null);
   const currentStepAbortRef = useRef<AbortController | null>(null);
@@ -94,10 +114,18 @@ export function useWorkflowRunSession(draft: WorkflowDefinition) {
         baseSnapshotRef.current = pageContext?.pageFullContent ?? "";
       }
 
-      const startIndex = mode === "resume" && pausedState ? pausedState.pausedAtStepIndex : 0;
-      const initialOutputs = mode === "resume" && pausedState ? [...pausedState.stepOutputs] : [];
-      const resumePartial =
-        mode === "resume" && pausedState ? pausedState.partialForStep : undefined;
+      let startIndex = 0;
+      let initialOutputs: string[] = [];
+      let resumePartial: string | undefined;
+      if (mode === "resume" && pausedState) {
+        const resolved = resolveResumeFromPaused(pausedState, validSteps);
+        if (!resolved) {
+          toast({ title: t("aiChat.workflow.pausedStepNotFound"), variant: "destructive" });
+          setPausedState(null);
+          return;
+        }
+        ({ startIndex, initialOutputs, resumePartial } = resolved);
+      }
 
       if (mode === "fresh") {
         setPausedState(null);
diff --git a/src/hooks/workflowRunOutcomeHandlers.ts b/src/hooks/workflowRunOutcomeHandlers.ts
index dd8333b3..a45d1262 100644
--- a/src/hooks/workflowRunOutcomeHandlers.ts
+++ b/src/hooks/workflowRunOutcomeHandlers.ts
@@ -12,8 +12,10 @@ type ToastArg = { title: string; variant?: "destructive" };
 type ToastFn = (props: ToastArg) => void;
 
 type PausedState = {
-  pausedAtStepIndex: number;
-  stepOutputs: string[];
+  /** Step to resume (lookup in current valid steps). / 再開するステップ（現在の有効ステップで解決） */
+  pausedStepId: string;
+  /** Completed outputs keyed by step id. / 完了ステップの出力（id キー） */
+  stepOutputsById: Record<string, string>;
   partialForStep: string;
 };
 
@@ -44,8 +46,8 @@ export function applyWorkflowRunOutcome(
     case "paused":
       setActiveRunSteps(validSteps);
       setPausedState({
-        pausedAtStepIndex: result.pausedAtStepIndex,
-        stepOutputs: result.stepOutputs,
+        pausedStepId: result.pausedStepId,
+        stepOutputsById: result.stepOutputsById,
         partialForStep: result.partialForStep,
       });
       setProgress((p) => (p ? { ...p, phase: "paused" } : null));
diff --git a/src/i18n/locales/en/aiChat.json b/src/i18n/locales/en/aiChat.json
index 7ea0bff5..db959c32 100644
--- a/src/i18n/locales/en/aiChat.json
+++ b/src/i18n/locales/en/aiChat.json
@@ -82,6 +82,7 @@
     "nameRequired": "Enter a workflow name.",
     "stepsRequired": "Add at least one step with a title and instructions.",
     "nothingToResume": "Nothing to resume. Run a workflow first, then pause.",
+    "pausedStepNotFound": "The paused step is no longer in this workflow. Run again from the start.",
     "workflowName": "Workflow name",
     "workflowNamePlaceholder": "e.g. New API endpoint design",
     "template": "Template",
diff --git a/src/i18n/locales/ja/aiChat.json b/src/i18n/locales/ja/aiChat.json
index 2e4d4ef3..0fe4f57c 100644
--- a/src/i18n/locales/ja/aiChat.json
+++ b/src/i18n/locales/ja/aiChat.json
@@ -82,6 +82,7 @@
     "nameRequired": "ワークフロー名を入力してください。",
     "stepsRequired": "タイトルと指示があるステップを1つ以上追加してください。",
     "nothingToResume": "再開できる実行がありません。実行して一時停止してください。",
+    "pausedStepNotFound": "一時停止中のステップがワークフローにありません。最初からやり直してください。",
     "workflowName": "ワークフロー名",
     "workflowNamePlaceholder": "例: 新 API エンドポイント設計",
     "template": "テンプレート",
diff --git a/src/lib/workflow/runWorkflowExecution.test.ts b/src/lib/workflow/runWorkflowExecution.test.ts
index 5a77e64c..cbbdac28 100644
--- a/src/lib/workflow/runWorkflowExecution.test.ts
+++ b/src/lib/workflow/runWorkflowExecution.test.ts
@@ -90,6 +90,8 @@ describe("runWorkflowExecution", () => {
     expect(r.outcome).toBe("paused");
     if (r.outcome === "paused") {
       expect(r.pausedAtStepIndex).toBe(0);
+      expect(r.pausedStepId).toBe("s1");
+      expect(r.stepOutputsById).toEqual({});
       expect(r.stepOutputs).toEqual([""]);
     }
     expect(createCount).toBe(1);
diff --git a/src/lib/workflow/runWorkflowExecution.ts b/src/lib/workflow/runWorkflowExecution.ts
index 9ac213b9..aafceb59 100644
--- a/src/lib/workflow/runWorkflowExecution.ts
+++ b/src/lib/workflow/runWorkflowExecution.ts
@@ -16,6 +16,10 @@ export type WorkflowExecutionOutcome =
       outcome: "paused";
       /** Step index where the run stopped (same step on resume). / 停止したステップ index（再開時も同じ） */
       pausedAtStepIndex: number;
+      /** Step id at pause (stable across draft edits). / 一時停止時のステップ id（ドラフト編集後も追跡） */
+      pausedStepId: string;
+      /** Completed outputs keyed by step id. / 完了ステップの出力（id キー） */
+      stepOutputsById: Record<string, string>;
       /** Snapshot of outputs for completed steps. / 完了ステップの出力スナップショット */
       stepOutputs: string[];
       /** Streaming buffer at pause time for the active step. / 停止時点のアクティブステップのストリーム */
@@ -228,9 +232,15 @@ async function runWorkflowStepsLoop(
         }
         pushProgress("paused", i, buildStatuses(steps.length, i, "running"), streaming, undefined);
         emitNote(i, buildStatuses(steps.length, i, "running"), i, streaming);
+        const stepOutputsById: Record<string, string> = {};
+        for (let k = 0; k < i; k += 1) {
+          stepOutputsById[steps[k].id] = stepOutputs[k];
+        }
         return {
           outcome: "paused",
           pausedAtStepIndex: i,
+          pausedStepId: steps[i].id,
+          stepOutputsById,
           stepOutputs: [...stepOutputs],
           partialForStep: streaming,
         };

From 07128a41f38506885390e08e8b807936fc5b0fc5 Mon Sep 17 00:00:00 2001
From: otomatty <saedgewell@gmail.com>
Date: Sun, 5 Apr 2026 11:07:04 +0900
Subject: [PATCH 5/5] fix: address PR #477 review (chat input mount, progress
 step alignment)

- Keep AIChatInput mounted when workflow tab is active (hidden) so drafts are not cleared.
- On completed/stopped/error, keep activeRunSteps as validSteps so progress matches stepStatuses.

Made-with: Cursor
---
 src/components/ai-chat/AIChatPanelContent.tsx | 21 +++++++++----------
 src/hooks/workflowRunOutcomeHandlers.ts       |  9 +++++---
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/src/components/ai-chat/AIChatPanelContent.tsx b/src/components/ai-chat/AIChatPanelContent.tsx
index 2ff45156..06ceed75 100644
--- a/src/components/ai-chat/AIChatPanelContent.tsx
+++ b/src/components/ai-chat/AIChatPanelContent.tsx
@@ -159,17 +159,16 @@ export function AIChatPanelContent({
         ) : null}
       </div>
 
-      {activeViewTab !== "workflow" && (
-        <div className="bg-background border-t p-4">
-          <AIChatInput
-            onSendMessage={handleSendMessage}
-            onStopStreaming={stopStreaming}
-            prefillText={inputPrefill?.text}
-            prefillNonce={inputPrefill?.nonce}
-            focusEditorNonce={focusEditorNonce}
-          />
-        </div>
-      )}
+      {/* Stay mounted on workflow tab so uncontrolled input draft is not lost. / ワークフロー切替で下書きを失わない */}
+      <div className={cn("bg-background border-t p-4", activeViewTab === "workflow" && "hidden")}>
+        <AIChatInput
+          onSendMessage={handleSendMessage}
+          onStopStreaming={stopStreaming}
+          prefillText={inputPrefill?.text}
+          prefillNonce={inputPrefill?.nonce}
+          focusEditorNonce={focusEditorNonce}
+        />
+      </div>
     </div>
   );
 }
diff --git a/src/hooks/workflowRunOutcomeHandlers.ts b/src/hooks/workflowRunOutcomeHandlers.ts
index a45d1262..e5964708 100644
--- a/src/hooks/workflowRunOutcomeHandlers.ts
+++ b/src/hooks/workflowRunOutcomeHandlers.ts
@@ -22,6 +22,9 @@ type PausedState = {
 /**
  * Applies execution outcome: toasts and state setters for pause / complete / error.
  * 実行結果を適用する（トーストと pause / 完了 / エラー用の setter）。
+ *
+ * Terminal outcomes keep `activeRunSteps` as `validSteps` so progress rows align with `stepStatuses`
+ * when the draft still contains empty placeholder steps. / 終端時も activeRunSteps を validSteps に保ち、空ステップがあっても進捗行と stepStatuses を一致させる。
  */
 export function applyWorkflowRunOutcome(
   result: WorkflowExecutionOutcome,
@@ -39,7 +42,7 @@ export function applyWorkflowRunOutcome(
   switch (result.outcome) {
     case "completed":
       setPausedState(null);
-      setActiveRunSteps(null);
+      setActiveRunSteps(validSteps);
       setProgress((p) => (p ? { ...p, phase: "completed" } : null));
       toast({ title: t("aiChat.workflow.completed") });
       return;
@@ -55,7 +58,7 @@ export function applyWorkflowRunOutcome(
       return;
     case "stopped":
       setPausedState(null);
-      setActiveRunSteps(null);
+      setActiveRunSteps(validSteps);
       setProgress((p) => {
         if (!p) return null;
         const stepStatuses = p.stepStatuses.map((s) => (s === "running" ? "pending" : s));
@@ -70,7 +73,7 @@ export function applyWorkflowRunOutcome(
       return;
     case "error":
       setPausedState(null);
-      setActiveRunSteps(null);
+      setActiveRunSteps(validSteps);
       setProgress((p) => {
         if (!p) return null;
         const stepStatuses = p.stepStatuses.map((s) => (s === "running" ? "error" : s));