@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/workflow/__tests__/useWorkflowExecutionActions.test.tsx

@@ -23,6 +23,7 @@ const mockResume = vi.fn();
 const mockRecover = vi.fn();
 const mockSubmitApproval = vi.fn();
 const mockSubmitWorkflowTaskApproval = vi.fn();
+const mockSubmitFileDecision = vi.fn();
 
 function makeMockClient(): Stigmer {
   return {
@@ -34,6 +35,7 @@ function makeMockClient(): Stigmer {
       recover: mockRecover,
       submitApproval: mockSubmitApproval,
       submitWorkflowTaskApproval: mockSubmitWorkflowTaskApproval,
+      submitFileDecision: mockSubmitFileDecision,
     },
   } as unknown as Stigmer;
 }
@@ -278,3 +280,277 @@ describe("onSuccess callback", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Per-gate approval state (keyed; separate from the lifecycle scalar)
+// ---------------------------------------------------------------------------
+
+describe("per-gate approval state", () => {
+  it("tracks an in-flight tool approval keyed by toolCallId, not the lifecycle scalar", async () => {
+    let resolve!: (v: unknown) => void;
+    mockSubmitApproval.mockReturnValueOnce(new Promise((r) => (resolve = r)));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let pending: Promise<unknown>;
+    act(() => {
+      pending = result.current.submitApproval("tc-1", 1 as any);
+    });
+
+    expect(result.current.approvalSubmittingToolCallIds.has("tc-1")).toBe(true);
+    // The lifecycle scalar is untouched by an approval.
+    expect(result.current.isSubmitting).toBe(false);
+
+    await act(async () => {
+      resolve(makeExecution());
+      await pending;
+    });
+
+    expect(result.current.approvalSubmittingToolCallIds.size).toBe(0);
+  });
+
+  it("records a failed tool approval in the keyed map, not the lifecycle scalar, and resolves null", async () => {
+    mockSubmitApproval.mockRejectedValueOnce(new Error("gate already resolved"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitApproval("tc-1", 1 as any);
+    });
+
+    expect(returned).toBeNull();
+    expect(result.current.approvalErrorsByToolCallId.get("tc-1")?.message).toBe(
+      "gate already resolved",
+    );
+    // The lifecycle scalar (header banner) must NOT pick up an approval failure.
+    expect(result.current.error).toBeNull();
+    expect(result.current.isSubmitting).toBe(false);
+  });
+
+  it("records a failed task approval keyed by taskName, not the lifecycle scalar", async () => {
+    mockSubmitWorkflowTaskApproval.mockRejectedValueOnce(new Error("signal failed"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitTaskApproval("review_task", "approved");
+    });
+
+    expect(returned).toBeNull();
+    expect(result.current.taskApprovalErrorsByTaskName.get("review_task")?.message).toBe(
+      "signal failed",
+    );
+    expect(result.current.error).toBeNull();
+  });
+
+  it("keeps tool and task approval errors in separate keyed spaces", async () => {
+    mockSubmitApproval.mockRejectedValueOnce(new Error("tool fail"));
+    mockSubmitWorkflowTaskApproval.mockRejectedValueOnce(new Error("task fail"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.submitApproval("tc-1", 1 as any);
+    });
+    await act(async () => {
+      await result.current.submitTaskApproval("review_task", "approved");
+    });
+
+    expect(result.current.approvalErrorsByToolCallId.get("tc-1")?.message).toBe("tool fail");
+    expect(result.current.taskApprovalErrorsByTaskName.get("review_task")?.message).toBe("task fail");
+    // Neither keyed failure crosses into the other space or the scalar.
+    expect(result.current.approvalErrorsByToolCallId.has("review_task")).toBe(false);
+    expect(result.current.taskApprovalErrorsByTaskName.has("tc-1")).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("keeps a failed lifecycle action in the scalar, never in the keyed approval maps", async () => {
+    mockCancel.mockRejectedValueOnce(new Error("temporal down"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.cancel();
+    });
+
+    expect(result.current.error?.message).toBe("temporal down");
+    expect(result.current.approvalErrorsByToolCallId.size).toBe(0);
+    expect(result.current.taskApprovalErrorsByTaskName.size).toBe(0);
+  });
+
+  it("null executionId returns null without recording keyed state", async () => {
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions(null),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitApproval("tc-1", 1 as any);
+    });
+
+    expect(returned).toBeNull();
+    expect(mockSubmitApproval).not.toHaveBeenCalled();
+    expect(result.current.approvalSubmittingToolCallIds.size).toBe(0);
+    expect(result.current.approvalErrorsByToolCallId.size).toBe(0);
+  });
+
+  it("keeps a stable return reference across renders when nothing changes", () => {
+    const { result, rerender } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Per-gate file-decision state (forwarding + keyed like FileReviewCard)
+// ---------------------------------------------------------------------------
+
+describe("submitFileDecision (workflow-parent file review)", () => {
+  it("forwards a CHANGE_SET decision with explicit child routing", async () => {
+    mockSubmitFileDecision.mockResolvedValueOnce(makeExecution());
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.submitFileDecision("aex-child", "fcs-1", 1 /* APPROVE */ as any, {
+        expectedDigest: "sha256:agg",
+      });
+    });
+
+    expect(mockSubmitFileDecision).toHaveBeenCalledTimes(1);
+    const input = mockSubmitFileDecision.mock.calls[0][0];
+    expect(input.executionId).toBe("wex-001");
+    expect(input.childAgentExecutionId).toBe("aex-child");
+    expect(input.changeSetId).toBe("fcs-1");
+    expect(input.scope).toBe(1 /* CHANGE_SET */);
+    expect(input.fileChangeId).toBe("");
+    expect(input.action).toBe(1 /* APPROVE */);
+    expect(input.expectedDigest).toBe("sha256:agg");
+  });
+
+  it("derives FILE scope when a fileChangeId is supplied", async () => {
+    mockSubmitFileDecision.mockResolvedValueOnce(makeExecution());
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.submitFileDecision("aex-child", "fcs-1", 2 /* REJECT */ as any, {
+        fileChangeId: "fc-9",
+        expectedDigest: "sha256:file",
+      });
+    });
+
+    const input = mockSubmitFileDecision.mock.calls[0][0];
+    expect(input.scope).toBe(2 /* FILE */);
+    expect(input.fileChangeId).toBe("fc-9");
+    expect(input.action).toBe(2 /* REJECT */);
+  });
+
+  it("tracks in-flight state keyed like FileReviewCard (changeSetId, then changeSetId:fileChangeId)", async () => {
+    let resolve!: (v: unknown) => void;
+    mockSubmitFileDecision.mockReturnValueOnce(new Promise((r) => (resolve = r)));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let pending: Promise<unknown>;
+    act(() => {
+      pending = result.current.submitFileDecision("aex-child", "fcs-1", 1 as any);
+    });
+
+    expect(result.current.fileDecisionSubmittingKeys.has("fcs-1")).toBe(true);
+    expect(result.current.isSubmitting).toBe(false); // lifecycle scalar untouched
+
+    await act(async () => {
+      resolve(makeExecution());
+      await pending;
+    });
+
+    expect(result.current.fileDecisionSubmittingKeys.size).toBe(0);
+  });
+
+  it("records a failed decision in the keyed map (not the scalar) and resolves null", async () => {
+    mockSubmitFileDecision.mockRejectedValueOnce(new Error("expected_digest mismatch"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitFileDecision("aex-child", "fcs-1", 1 as any, {
+        fileChangeId: "fc-9",
+      });
+    });
+
+    expect(returned).toBeNull();
+    expect(result.current.fileDecisionErrorsByKey.get("fcs-1:fc-9")?.message).toBe(
+      "expected_digest mismatch",
+    );
+    expect(result.current.error).toBeNull(); // header banner unaffected
+  });
+
+  it("does not fire onSuccess", async () => {
+    mockSubmitFileDecision.mockResolvedValueOnce(makeExecution());
+    const onSuccess = vi.fn();
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001", { onSuccess }),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.submitFileDecision("aex-child", "fcs-1", 1 as any);
+    });
+
+    expect(onSuccess).not.toHaveBeenCalled();
+  });
+
+  it("null executionId returns null without calling the SDK", async () => {
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions(null),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitFileDecision("aex-child", "fcs-1", 1 as any);
+    });
+
+    expect(returned).toBeNull();
+    expect(mockSubmitFileDecision).not.toHaveBeenCalled();
+    expect(result.current.fileDecisionSubmittingKeys.size).toBe(0);
+  });
+});

package/src/workflow/execution-inspector/ExecutionInspector.tsx

@@ -35,8 +35,17 @@ export interface ExecutionInspectorProps {
   readonly pendingApprovals?: readonly WorkflowPendingApproval[];
   /** Callback to submit an agent tool approval decision. */
   readonly onSubmitApproval?: (toolCallId: string, action: ApprovalAction, comment?: string) => Promise<unknown>;
-  /** Whether an approval submission is in flight. */
-  readonly isSubmittingApproval?: boolean;
+  /**
+   * Tool-call ids whose agent-tool approval is in flight, keyed by `toolCallId`
+   * so deciding one gate never spins another. Supply
+   * {@link useWorkflowExecutionActions}'s `approvalSubmittingToolCallIds`.
+   */
+  readonly approvalSubmittingToolCallIds?: ReadonlySet<string>;
+  /**
+   * Per-gate agent-tool approval failures, keyed by `toolCallId`. Supply
+   * {@link useWorkflowExecutionActions}'s `approvalErrorsByToolCallId`.
+   */
+  readonly approvalErrorsByToolCallId?: ReadonlyMap<string, Error>;
   /** Callback to submit a workflow-level human_input task decision. */
   readonly onSubmitTaskApproval?: (
     taskName: string,
@@ -44,8 +53,16 @@ export interface ExecutionInspectorProps {
     formData?: Record<string, unknown>,
     comment?: string,
   ) => Promise<unknown>;
-  /** Whether a task approval submission is in flight. */
-  readonly isSubmittingTaskApproval?: boolean;
+  /**
+   * Task names whose human_input approval is in flight, keyed by `taskName`.
+   * Supply {@link useWorkflowExecutionActions}'s `taskApprovalSubmittingTaskNames`.
+   */
+  readonly taskApprovalSubmittingTaskNames?: ReadonlySet<string>;
+  /**
+   * Per-gate human_input approval failures, keyed by `taskName`. Supply
+   * {@link useWorkflowExecutionActions}'s `taskApprovalErrorsByTaskName`.
+   */
+  readonly taskApprovalErrorsByTaskName?: ReadonlyMap<string, Error>;
   /** Additional CSS class names. */
   readonly className?: string;
 }
@@ -89,9 +106,11 @@ export const ExecutionInspector = memo(function ExecutionInspector({
   onNavigateToAgentExecution,
   pendingApprovals,
   onSubmitApproval,
-  isSubmittingApproval,
+  approvalSubmittingToolCallIds,
+  approvalErrorsByToolCallId,
   onSubmitTaskApproval,
-  isSubmittingTaskApproval,
+  taskApprovalSubmittingTaskNames,
+  taskApprovalErrorsByTaskName,
   className,
 }: ExecutionInspectorProps) {
   const { detail } = useExecutionTaskDetail({
@@ -212,17 +231,21 @@ export const ExecutionInspector = memo(function ExecutionInspector({
           )}
           {effectiveTab === "approval" && taskApprovals.length > 0 && onSubmitApproval && (
             <div className="space-y-2">
-              {taskApprovals.map((pa) => (
-                <WorkflowExecutionApprovalCard
-                  key={pa.approval?.toolCallId ?? pa.childAgentExecutionId}
-                  prompt={pa.approval?.message || `Tool "${pa.approval?.toolName}" requires approval`}
-                  toolCallId={pa.approval?.toolCallId ?? ""}
-                  approvers={[]}
-                  timeoutSeconds={0}
-                  onSubmitApproval={onSubmitApproval}
-                  isSubmitting={isSubmittingApproval ?? false}
-                />
-              ))}
+              {taskApprovals.map((pa) => {
+                const toolCallId = pa.approval?.toolCallId ?? "";
+                return (
+                  <WorkflowExecutionApprovalCard
+                    key={toolCallId || pa.childAgentExecutionId}
+                    prompt={pa.approval?.message || `Tool "${pa.approval?.toolName}" requires approval`}
+                    toolCallId={toolCallId}
+                    approvers={[]}
+                    timeoutSeconds={0}
+                    onSubmitApproval={onSubmitApproval}
+                    isSubmitting={approvalSubmittingToolCallIds?.has(toolCallId) ?? false}
+                    error={approvalErrorsByToolCallId?.get(toolCallId) ?? null}
+                  />
+                );
+              })}
             </div>
           )}
           {effectiveTab === "approval" && detail.approval && (
@@ -234,7 +257,8 @@ export const ExecutionInspector = memo(function ExecutionInspector({
                 outcomes={detail.approval.outcomes}
                 formSchema={detail.approval.formSchema ?? undefined}
                 onSubmit={onSubmitTaskApproval}
-                isSubmitting={isSubmittingTaskApproval ?? false}
+                isSubmitting={taskApprovalSubmittingTaskNames?.has(detail.taskName) ?? false}
+                error={taskApprovalErrorsByTaskName?.get(detail.taskName) ?? null}
               />
             ) : (
               // Gate resolved — present the captured decision read-only so a

package/src/workflow/index.ts

@@ -208,6 +208,11 @@ export {
   WorkflowExecutionApprovalCard,
   type WorkflowExecutionApprovalCardProps,
 } from "./WorkflowExecutionApprovalCard";
+export {
+  WorkflowFileReviewList,
+  type WorkflowFileReviewListProps,
+  type WorkflowFileDecisionSubmit,
+} from "./WorkflowFileReviewList";
 
 export {
   WorkflowTaskApprovalCard,

package/src/workflow/useWorkflowExecutionActions.ts

@@ -1,8 +1,9 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
-import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ApprovalAction, FileDecisionAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { FileDecisionScope } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { create, type JsonObject } from "@bufbuild/protobuf";
 import {
   CancelWorkflowExecutionInputSchema,
@@ -12,9 +13,12 @@ import {
   RecoverWorkflowExecutionInputSchema,
   SubmitWorkflowApprovalInputSchema,
   SubmitWorkflowTaskApprovalInputSchema,
+  SubmitWorkflowFileDecisionInputSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
+import { useKeyedSubmission } from "../internal/useKeyedSubmission";
+import { fileDecisionKey, type FileDecisionOptions } from "../execution/useFileReview";
 
 /** Options for {@link useWorkflowExecutionActions}. */
 export interface UseWorkflowExecutionActionsOptions {
@@ -71,12 +75,74 @@ export interface UseWorkflowExecutionActionsReturn {
     formData?: Record<string, unknown>,
     comment?: string,
   ) => Promise<WorkflowExecution | null>;
-  /** `true` while any action is in flight. */
+  /**
+   * Submit a keep/discard decision for a child agent's file review, surfaced on
+   * this workflow via `status.pending_file_reviews`. The file-review sibling of
+   * {@link submitApproval}: the server forwards it to the child's
+   * `AgentExecution.submitFileDecision`.
+   *
+   * `childAgentExecutionId` comes from the surfaced
+   * `WorkflowPendingFileReview` reference. `options` carries the same
+   * per-decision detail as {@link FileReviewCard}'s `onSubmit` (scope,
+   * `fileChangeId`, `expectedDigest`, `reason`, `acknowledgeUnreviewable`).
+   */
+  readonly submitFileDecision: (
+    childAgentExecutionId: string,
+    changeSetId: string,
+    action: FileDecisionAction,
+    options?: FileDecisionOptions,
+  ) => Promise<WorkflowExecution | null>;
+  /**
+   * `true` while a **lifecycle** action (cancel/terminate/pause/resume/recover)
+   * is in flight. Approvals are excluded — they are per-gate, so read their
+   * in-flight state from {@link approvalSubmittingToolCallIds} /
+   * {@link taskApprovalSubmittingTaskNames} instead.
+   */
   readonly isSubmitting: boolean;
-  /** Error from the last failed action, or `null`. */
+  /**
+   * Error from the last failed **lifecycle** action, or `null`. Approval
+   * failures are per-gate and live in {@link approvalErrorsByToolCallId} /
+   * {@link taskApprovalErrorsByTaskName} so each surfaces beside the gate that
+   * failed — never in this shared scalar (which backs the header banner).
+   */
   readonly error: Error | null;
-  /** Reset `error` to `null`. */
+  /** Reset the lifecycle {@link error} to `null`. */
   readonly clearError: () => void;
+  /**
+   * Tool-call ids whose agent-tool approval is currently being submitted, keyed
+   * exactly like {@link approvalErrorsByToolCallId}. A workflow can hold many
+   * concurrent gates, so deciding one must not spin or disable the others.
+   */
+  readonly approvalSubmittingToolCallIds: ReadonlySet<string>;
+  /**
+   * Per-gate agent-tool approval failures, keyed by `toolCallId`. Consumed by
+   * {@link WorkflowExecutionApprovalCard} to surface the failure in-card,
+   * beside the gate that failed. Cleared for a gate when it is retried.
+   */
+  readonly approvalErrorsByToolCallId: ReadonlyMap<string, Error>;
+  /**
+   * Task names whose human_input task approval is currently being submitted,
+   * keyed exactly like {@link taskApprovalErrorsByTaskName}.
+   */
+  readonly taskApprovalSubmittingTaskNames: ReadonlySet<string>;
+  /**
+   * Per-gate human_input task approval failures, keyed by `taskName`. Consumed
+   * by `WorkflowTaskApprovalCard` to surface the failure in-card, beside
+   * the gate that failed. Cleared for a gate when it is retried.
+   */
+  readonly taskApprovalErrorsByTaskName: ReadonlyMap<string, Error>;
+  /**
+   * Decision keys currently being submitted for file reviews, keyed exactly like
+   * {@link FileReviewCard}'s `submittingDecisionKeys` (via {@link fileDecisionKey}
+   * — the change set id for a whole-set decision, `changeSetId:fileChangeId` for a
+   * per-file one). Pass straight through to each surfaced card.
+   */
+  readonly fileDecisionSubmittingKeys: ReadonlySet<string>;
+  /**
+   * Per-decision file-review failures, keyed like {@link fileDecisionSubmittingKeys}.
+   * Pass straight through to {@link FileReviewCard}'s `decisionErrors`.
+   */
+  readonly fileDecisionErrorsByKey: ReadonlyMap<string, Error>;
 }
 
 /**
@@ -107,6 +173,14 @@ export function useWorkflowExecutionActions(
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
+  // Approvals are per-gate (a workflow can hold many at once), so each kind gets
+  // its own keyed in-flight + error state — keyed by tool-call id for agent-tool
+  // approvals and by task name for human_input task approvals. The lifecycle
+  // actions below stay on the shared scalar (they are header singletons).
+  const approvals = useKeyedSubmission<WorkflowExecution>();
+  const taskApprovals = useKeyedSubmission<WorkflowExecution>();
+  const fileDecisions = useKeyedSubmission<WorkflowExecution>();
+
   const executionIdRef = useRef(executionId);
   executionIdRef.current = executionId;
   const stigmerRef = useRef(stigmer);
@@ -202,10 +276,15 @@ export function useWorkflowExecutionActions(
     [wrap],
   );
 
+  // Approvals do NOT go through `wrap`: their in-flight + error state is keyed
+  // (per gate), and the keyed primitive re-throws after recording, so we swallow
+  // to `null` here to keep the `WorkflowExecution | null` contract. They never
+  // fire `onSuccess` — their effects arrive via the event stream.
   const submitApproval = useCallback(
-    (toolCallId: string, action: ApprovalAction, comment?: string) =>
-      wrap(
-        () =>
+    (toolCallId: string, action: ApprovalAction, comment?: string) => {
+      if (!executionIdRef.current) return Promise.resolve(null);
+      return approvals
+        .run(toolCallId, () =>
           stigmerRef.current.workflowExecution.submitApproval(
             create(SubmitWorkflowApprovalInputSchema, {
               executionId: executionIdRef.current!,
@@ -214,15 +293,17 @@ export function useWorkflowExecutionActions(
               comment: comment ?? "",
             }),
           ),
-        false,
-      ),
-    [wrap],
+        )
+        .catch(() => null);
+    },
+    [approvals.run],
   );
 
   const submitTaskApproval = useCallback(
-    (taskName: string, outcome: string, formData?: Record<string, unknown>, comment?: string) =>
-      wrap(
-        () =>
+    (taskName: string, outcome: string, formData?: Record<string, unknown>, comment?: string) => {
+      if (!executionIdRef.current) return Promise.resolve(null);
+      return taskApprovals
+        .run(taskName, () =>
           stigmerRef.current.workflowExecution.submitWorkflowTaskApproval(
             create(SubmitWorkflowTaskApprovalInputSchema, {
               executionId: executionIdRef.current!,
@@ -233,21 +314,88 @@ export function useWorkflowExecutionActions(
               comment: comment ?? "",
             }),
           ),
-        false,
-      ),
-    [wrap],
+        )
+        .catch(() => null);
+    },
+    [taskApprovals.run],
   );
 
-  return {
-    cancel,
-    terminate,
-    pause,
-    resume,
-    recover,
-    submitApproval,
-    submitTaskApproval,
-    isSubmitting,
-    error,
-    clearError,
-  };
+  // File decisions are per-target (a workflow can surface many change sets across
+  // parallel children), so they use the keyed primitive keyed exactly like
+  // FileReviewCard expects (fileDecisionKey). Never fires onSuccess — the effect
+  // arrives via the execution stream.
+  const submitFileDecision = useCallback(
+    (
+      childAgentExecutionId: string,
+      changeSetId: string,
+      action: FileDecisionAction,
+      options?: FileDecisionOptions,
+    ) => {
+      if (!executionIdRef.current) return Promise.resolve(null);
+      const fileChangeId = options?.fileChangeId ?? "";
+      const scope =
+        options?.scope ??
+        (fileChangeId ? FileDecisionScope.FILE : FileDecisionScope.CHANGE_SET);
+      const key = fileDecisionKey(changeSetId, fileChangeId || undefined);
+      return fileDecisions
+        .run(key, () =>
+          stigmerRef.current.workflowExecution.submitFileDecision(
+            create(SubmitWorkflowFileDecisionInputSchema, {
+              executionId: executionIdRef.current!,
+              childAgentExecutionId,
+              changeSetId,
+              scope,
+              fileChangeId,
+              action,
+              expectedDigest: options?.expectedDigest ?? "",
+              reason: options?.reason ?? "",
+              acknowledgeUnreviewable: options?.acknowledgeUnreviewable ?? false,
+            }),
+          ),
+        )
+        .catch(() => null);
+    },
+    [fileDecisions.run],
+  );
+
+  return useMemo(
+    () => ({
+      cancel,
+      terminate,
+      pause,
+      resume,
+      recover,
+      submitApproval,
+      submitTaskApproval,
+      submitFileDecision,
+      isSubmitting,
+      error,
+      clearError,
+      approvalSubmittingToolCallIds: approvals.submittingKeys,
+      approvalErrorsByToolCallId: approvals.errorsByKey,
+      taskApprovalSubmittingTaskNames: taskApprovals.submittingKeys,
+      taskApprovalErrorsByTaskName: taskApprovals.errorsByKey,
+      fileDecisionSubmittingKeys: fileDecisions.submittingKeys,
+      fileDecisionErrorsByKey: fileDecisions.errorsByKey,
+    }),
+    [
+      cancel,
+      terminate,
+      pause,
+      resume,
+      recover,
+      submitApproval,
+      submitTaskApproval,
+      submitFileDecision,
+      isSubmitting,
+      error,
+      clearError,
+      approvals.submittingKeys,
+      approvals.errorsByKey,
+      taskApprovals.submittingKeys,
+      taskApprovals.errorsByKey,
+      fileDecisions.submittingKeys,
+      fileDecisions.errorsByKey,
+    ],
+  );
 }